DOCSEARCHbyAlgolia
Submit Docs

Torch7 Documentation

repository·master·Indexed 27 days ago

https://github.com/torch/torch7

A legacy Lua-based framework for multi-dimensional tensors and mathematical operations used for deep learning. The documentation covers core packages including the Tensor library, File I/O interfaces (DiskFile, MemoryFile, PipeFile), and utilities like torch.CmdLine for parameter parsing and logging. It also provides detailed C API references for the luaT library, including memory management, class creation via luaT_newmetatable, and userdata type checking.

Tokens
18.5K
Snippets
48
Records
160
Agent score
94%

What's inside Torch7

  1. Overview of Torch7 core packages

    master

    Torch7 is organized into several core functional libraries:

    Tensor Library

    • Tensor: Defines the multi-dimensional tensor object with type templating.
    • Mathematical operations: Provides math operations for tensor object types.
    • Storage: Manages the underlying storage for tensor objects.

    File I/O Interface Library

    • File: Abstract interface for common file operations.
    • Disk File: Operations for files stored on disk.
    • Memory File: Operations for files stored in RAM.
    • Pipe File: Operations for using piped commands.
    • High-Level File operations: Provides serialization functions.

    Useful Utilities

    • Timer: Measures execution time.
    • Tester: A generic testing framework.
    • CmdLine: Utility for parsing command line arguments.
    • Random: Random number generator with various distributions.
    • utility: Functions for handling torch tensor types and class inheritance.

  2. Overview of the Torch package

    master
    The torch package is the core component of Torch7. It provides the fundamental data structures for multi-dimensional tensors, mathematical operations for those tensors, and utilities for file access and object serialization.

  3. Important notice on Torch7 development status

    master

    Torch is no longer in active development. The functionality previously provided by the C backend (TH, THNN, THC, THCUNN libraries) is being actively extended and rewritten in the ATen C++11 library.

    Key differences to note when moving to ATen:

    • ATen exposes operators from torch7, nn, cutorch, and cunn directly in C++11.
    • ATen includes support for sparse tensors and distributed operations.
    • Semantics: ATen uses numpy-style broadcasting, whereas the TH* libraries in Torch-7 do not.

    For details on building the forked Torch-7 libraries in C, refer to "The C interface" in the pytorch/aten/src/README.md file within the PyTorch repository.

  4. Create and manage Torch Storages

    master

    Storages are arrays of basic C types that allow Lua to access memory via C pointers or arrays. They are used for raw data; for arrays of Torch objects, use Lua tables instead.

    Available Storage types:

    • ByteStorage (unsigned chars)
    • CharStorage (signed chars)
    • ShortStorage (short integers)
    • IntStorage (integers)
    • LongStorage (long integers)
    • FloatStorage (floats)
    • DoubleStorage (doubles)

    An alias torch.Storage() is available and its default type is controlled by torch.setdefaulttensortype (defaults to torch.DoubleStorage).

  5. Understand the torch.Tensor class

    master
    The Tensor class is the primary class for handling multi-dimensional numeric data in Torch7. Tensors are views over a Storage object, which contains the actual raw data. Because tensors are views, many operations (like narrow) do not copy memory but instead return a new tensor that references the same underlying Storage using different stride and storageOffset values. This makes tensor manipulations highly efficient.

  6. Get support for Torch7

    master

    As of 2019, the Torch-7 community is minimal. Use the following channels for assistance:

    • Questions, Support, and Installation issues: Google groups
    • Reporting bugs: Use the specific GitHub issue tracker for the component you are using:
      • torch7
      • nn
      • cutorch
      • cunn
      • optim
      • threads
    • Developer Chat: Gitter Chat (Note: strictly for developer discussion; do not use for installation issues or large text blobs).

  7. Implement operator overloading for luaT classes

    master

    When defining a luaT class, the metatable can implement Lua operators like __index, __newindex, __tostring, __add, etc. To ensure correct inheritance behavior, follow these rules for specific operators:

    • __index__: Must return a value AND true, or return false only. Returning false allows the root metatable to attempt to handle the request.
    • __newindex__: Must return true or false. Returning true means the operator handled the argument; returning false allows the root metatable to either raise an error (if the object is userdata) or apply a rawset (if the object is a Lua table).
    • Other operators (e.g., __add__): No specific constraints required.

  8. Manage memory allocation with Torch math functions

    master

    Torch math functions follow a pattern that allows for manual memory management. By default, functions allocate a new Tensor for the result. However, you can pass a target Tensor as the first argument to have the result written into that existing tensor (resized if necessary). This avoids repeated memory allocations in loops.

    Calling a function using object-oriented syntax on a tensor is equivalent to passing that tensor as the first argument. For example, x:log() is equivalent to torch.log(x, x).

    -- Case 1: Allocates a new tensor
res1 = torch.conv2(x, k)

-- Case 2: Reuses an existing tensor (no new allocation in loops)
res2 = torch.Tensor()
for i = 1, 100 do
     torch.conv2(res2, x, k)
end

  9. Use torch.Tester for unit testing

    master

    The torch.Tester class provides a generic unit testing framework for Torch. It allows you to define test suites, add test functions (or tables of functions), and run them with detailed reporting on successes, failures, and errors. It supports deep equality checks for tensors, tables, and other objects, including tolerance for numerical comparisons.

    local mytest = torch.TestSuite()
local tester = torch.Tester()

function mytest.testA()
   local a = torch.Tensor{1, 2, 3}
   local b = torch.Tensor{1, 2, 4}
   tester:eq(a, b, "a and b should be equal")
end

function mytest.testB()
   local a = {2, torch.Tensor{1, 2, 2}}
   local b = {2, torch.Tensor{1, 2, 2.001}}
   tester:eq(a, b, 0.01, "a and b should be approximately equal")
end

function mytest.testC()
   local function myfunc()
      return "hello " .. world
   end
   tester:assertNoError(myfunc, "myfunc shouldn't give an error")
end

tester:add(mytest)
tester:run()

  10. Configure File encoding modes (ASCII vs Binary)

    master

    The torch.File abstract class (implemented by DiskFile, MemoryFile, and PipeFile) supports two encoding modes:

    • ASCII mode: Numbers are converted to human-readable characters. Booleans are 0 (false) or 1 (true). By default, autoSpacing() is enabled, which adds a space after each written value and a carriage return after each call. This can be disabled with noAutoSpacing().
    • Binary mode: Numbers and booleans are encoded directly as computer registers. This mode is faster and more efficient but not human-readable and less portable.

    Use ascii() to enable ASCII mode and binary() to enable binary mode.

  11. Use torch.CmdLine for parameter parsing and logging

    master
    The torch.CmdLine class provides a framework for parsing command-line arguments and managing experiment logs. It allows you to define options with default values, parse them from the command line, and automatically redirect output to both the screen and a log file. It is particularly useful for running multiple experiments with different parameter settings by generating unique directory names based on the provided arguments.

  12. Use TestSuite for organizing tests

    master

    A TestSuite is a specialized Lua table used to organize tests in conjunction with torch.Tester. It is created using torch.TestSuite(). Unlike a plain Lua table, a TestSuite prevents the accidental creation of duplicate tests by throwing an error if you attempt to define a function with a name that is already present in the suite.

    It is recommended to always use torch.TestSuite instead of a standard Lua table for managing test collections.

    test = torch.TestSuite()

function test.myTest()
   -- test implementation
end