Torch7 Deployment and Usage Guide

This guide provides instructions for deploying and using Torch7. Please note that Torch7 is no longer in active development. Its functionality has largely been superseded by ATen within PyTorch.

1. Prerequisites

Before installing Torch7, ensure you have the following:

Operating System: Linux or macOS. Windows is not officially supported.
C Compiler: A C99 compatible compiler like GCC or Clang.
Build Tools: make and cmake.
Git: For cloning the repository.
LuaJIT: Torch7 is built on LuaJIT. While the installation script typically handles this, having development headers might be beneficial.

2. Installation

Torch7 can be installed by cloning the repository and running the provided installation script.

Clone the Torch7 repository:

git clone https://github.com/torch/torch7.git
cd torch7

Run the installation script: The main Torch7 installation script will guide you through the process, including installing LuaJIT and core Torch packages.
```
./install.sh
```
Follow the on-screen prompts. The script will typically install Torch into ~/torch/.
Add Torch to your PATH: The installer usually prompts you to add the Torch binaries to your PATH and LD_LIBRARY_PATH (for Linux) or DYLD_LIBRARY_PATH (for macOS). If it doesn't, or you skip it, you'll need to do it manually. Add the following lines to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc):
```
export TORCH_PATH=~/torch
export PATH=$PATH:$TORCH_PATH/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TORCH_PATH/lib
# For macOS, use DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH
# export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$TORCH_PATH/lib
```
After adding, source your configuration file:
```
source ~/.bashrc # or ~/.zshrc
```

Verify Installation: Open a new terminal and run the th interpreter:

th

If successful, you should see the Torch prompt:

  ______             __   |  Torch7
 /_  __/__  ________/ /   |  http://torch.ch
  / / / _ \/ __/ __/ _ \  |  Lua version: 5.1
 /_/  \___/_/  \__/_//_/  |  JIT: ON
                           |  Methods: 19

You can then test a simple command:

> torch.Tensor{1,2,3}
 1
 2
 3
[torch.DoubleTensor of size 3]

Type os.exit() or ^D to exit the interpreter.

3. Configuration

Torch7 primarily relies on environment variables for its runtime configuration, especially for locating libraries.

TORCH_PATH: Specifies the root directory where Torch is installed (e.g., ~/torch).
PATH: Includes $TORCH_PATH/bin to make Torch executables (like th) accessible.
LD_LIBRARY_PATH (Linux) / DYLD_LIBRARY_PATH (macOS): Includes $TORCH_PATH/lib so the system can find Torch's shared libraries.

These are typically set during the installation process and should be added to your shell's profile for persistence.

4. Build & Run

Torch7 is primarily a C library with a Lua frontend. Building involves compiling the C source code. Running typically involves using the th interpreter or executing Lua scripts that leverage Torch.

Building (Core Libraries)

The install.sh script handles the compilation of the core Torch libraries (e.g., libTH.so, libTHNN.so). If you need to rebuild specific components or contribute to the C backend, you would typically navigate to the respective module's directory and use cmake and make.

For example, to build the torch package (which contains the Tensor library):

# Assuming you are in the torch7 directory
cd pkg/torch
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$TORCH_PATH
make
make install

This process is generally abstracted away by the main install.sh script for end-users.

Running Locally (Development & Production)

Torch7 applications are run using the th interpreter or standard Lua interpreters with Torch modules loaded.

Interactive Mode: Launch the Torch interpreter for interactive development and testing:
```
th
```
You can then execute Lua commands and Torch operations directly.
Running Lua Scripts: Create a Lua script (e.g., my_script.lua):
```
-- my_script.lua
require 'torch'

local a = torch.Tensor{{1,2},{3,4}}
print(a)

local b = a:add(10)
print(b)
```
Execute it using the th interpreter:
```
th my_script.lua
```
Or, if you want to use a standard Lua interpreter, ensure Torch is correctly configured in your LUA_PATH and LUA_CPATH:
```
lua my_script.lua
```
The th interpreter is generally preferred as it sets up the environment correctly by default.

5. Deployment

Given that Torch7 is a C library with a Lua interface, deployment typically involves ensuring the compiled libraries and the LuaJIT runtime are available on the target system.

Self-Contained Deployment: The easiest way to deploy a Torch7 application is to replicate the installation steps on the target server. This ensures all dependencies (LuaJIT, Torch libraries, and packages) are correctly installed and configured.

Containerization (e.g., Docker): For reproducible deployments, Docker is highly recommended. You can create a Dockerfile that performs the Torch7 installation steps, then copies your application code into the container.

Example Dockerfile snippet:

FROM ubuntu:18.04 # Or another suitable base image

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    git \
    libreadline-dev \
    libjpeg-dev \
    libpng-dev \
    libqt4-dev \
    libcairo2-dev \
    libffi-dev \
    # Add any other dependencies your specific Torch7 project might need
    && rm -rf /var/lib/apt/lists/*

# Clone and install Torch7
RUN git clone https://github.com/torch/torch7.git /opt/torch \
    && cd /opt/torch \
    && ./install.sh -b # -b for batch mode, non-interactive

# Set up environment variables for Torch
ENV TORCH_PATH=/opt/torch
ENV PATH=$PATH:$TORCH_PATH/bin
ENV LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TORCH_PATH/lib

# Copy your application code
COPY . /app

# Define the command to run your application
CMD ["th", "your_application.lua"]

6. Troubleshooting

Here are some common issues and their solutions when working with Torch7.

th: command not found:
- Reason: Torch's bin directory is not in your system's PATH.
- Solution: Ensure export PATH=$PATH:$TORCH_PATH/bin is in your shell's configuration file (e.g., .bashrc, .zshrc) and that you've sourced it or opened a new terminal.
error loading module 'torch' from file '.../libtorch.so': ... undefined symbol:
- Reason: The dynamic linker cannot find Torch's shared libraries.
- Solution: Ensure export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TORCH_PATH/lib (or DYLD_LIBRARY_PATH on macOS) is correctly set and sourced.
Installation script fails with compilation errors:
- Reason: Missing build dependencies (e.g., build-essential, cmake), or an outdated compiler.
- Solution: Install necessary build tools. On Ubuntu/Debian: sudo apt-get install build-essential cmake git. On macOS with Homebrew: brew install cmake. Ensure your compiler is up-to-date.
lua: ... module 'torch' not found::
- Reason: When running with lua instead of th, the LUA_PATH and LUA_CPATH environment variables might not be set correctly to find Torch modules.
- Solution: Use th instead of lua. If you must use lua, ensure your LUA_PATH and LUA_CPATH include the Torch installation directories. The th wrapper handles this automatically.
No active development warning:
- Reason: As stated in the README, Torch7 is no longer actively developed. This is expected behavior and not an error.
- Solution: Acknowledge this limitation. For new projects, consider PyTorch, which is the spiritual successor and actively maintained.
Issues with specific packages (e.g., cutorch, cunn):
- Reason: These packages require NVIDIA CUDA toolkit and cuDNN to be installed and correctly configured.
- Solution: Ensure CUDA and cuDNN are installed, and their paths are correctly set in your environment variables (e.g., CUDA_PATH, LD_LIBRARY_PATH). The Torch7 installer for these packages might fail if CUDA is not detected.

How to Deploy & Use torch/torch7