Cheatsheet (original) (raw)

A quick page for everything Torch.

• Newbies
• Installing and Running Torch
• Installing Packages
• Tutorials, Demos by Category
• Loading popular datasets
• List of Packages by Category

• Creating your own package
• Debuggers / Visual Debuggers / IDEs
• GPU Support
• Gotchas
• Shipping proprietary torch scripts (sharing scripts with others without sharing source code

Newbies

1. Read this page end-to-end (especially the Gotchas)
2. Install torch
3. Go though chapter 1 of the video tutorials
4. Look at the coding tutorial
5. Play around with the interpreter
6. Create your own script
7. Create your own package
8. Contribute! :)

If you are used to numpy, have a look at this pageIf you are used to Matlab, have a look at this translation pdf

Installing and Running Torch

Mac OS X and Ubuntu 12+

To make sure that the main install instructions for Mac OS X and Ubuntu 12+ are not replicated, and in a single place, we've put them here.

Gentoo Linux

Some external instructions here.

Windows

Running Torch on Windows

iOS

https://github.com/clementfarabet/torch-ios

Android

https://github.com/soumith/torch-android

EC2 Public AMI

EC2 AMI with the following pre-installed packages:

• CUDA
• cuDNN
• torch-distro (torch + common packages)
• iTorch
• Anaconda

AMI Id: ami-b36981d8. (Can be launched using g2.2xlarge instance)
Launch an instance.

EC2 Bitfusion AMI

EC2 AMI pre-installed with CUDA, cuDNN, torch-distro (torch + common packages), iTorch, Jupyter, and more. Also includes Bitfusion Boost which lets you combine multiple instances into a single virtual instance for max-performance applications and analysis without any code changes required.

Launch an instance from the AWS Marketplace.

Docker Images

docker pull kaixhin/torch

CUDA 7.5 version - see repo for requirementsdocker pull kaixhin/cuda-torch

CUDA 7.0 version - see repo for requirementsdocker pull kaixhin/cuda-torch:7.0

CUDA 6.5 version - see repo for requirementsdocker pull kaixhin/cuda-torch:6.5

Ubuntu 14.04 + iTorch notebook - see docker hub repo for details and usage docker pull dhunter/itorch-notebook

Installing Packages

Given a package name, you can install it at your terminal with:

luarocks install [packagename]

Loading popular datasets

• MNIST Loader - by Ronan Collobert
• CIFAR-10, CIFAR-100 - CIFAR loader by Soumith Chintala
• Imagenet Loader
• Imagenet multi-GPU training on AlexNet and Overfeat
• Another imagenet loading + training by @eladhoffer
• KITTI - KITTI dataset loader by Aysegul Dundar
• Atari2600 - Scripts to generate a dataset with static frames from the Arcade Learning Environment
• torch-INRIA - INRIA dataset loader by Alfredo Canziani
• dataload - MNIST, Penn Tree Bank, and generic data loaders.
• dp - A pylearn2-like deep learning library with several conveniently wrapped datasets including:
  • MNIST
  • NotMNIST
  • CIFAR-10
  • CIFAR-100
  • Google Street View House Numbers (SVHN)
  • Purdue Face Detection
  • Google Billion Words
  • Penn Tree Bank
  • ImageNet
• STL10 Loader
• torch-datasets - Scripts to load several popular datasets including:
  • BSR 500
  • CIFAR-10
  • COIL
  • Street View House Numbers
  • MNIST
  • NORB

Tutorials, Demos by Category

Tutorials

• Deep Learning with Torch, a 60 minute tutorial
• Oxford ML course problems
• Madbits tutorial
• code complementing the tutorials
• dp Tutorials
  • Neural Network
  • Kaggle Facial Keypoint Detection
  • Language Model
• Torch cheatsheet for Matlab users
• Implementing LSTMs with nngraph
• Torch Video Tutorials: getting started, NN, CNN and RNN theory, implementation and training.

Demos

• Core torch7 demos repository.
  • loading data
  • tensors
  • linear-regression, logistic-regression
  • face detector (training and detection as separate demos)
  • mst-based-segmenter
  • train-a-digit-classifier
  • train-autoencoder
  • optical flow demo
  • train-on-housenumbers
  • train-on-cifar
  • tracking with deep nets
  • kinect demo
  • filter-bank visualization
  • saliency-networks
• dp examples:
  • Neural Network for Image Classification
  • Mixture of Experts for Image Classification
  • Convolution Neural Network for Image Classification
  • Kaggle Facial Keypoint Detector using an MLP or a Convolution Neural Network
  • Neural Network Language Model for Google Billion Words dataset
  • [Recurrent Neural Network Language Model] (https://github.com/nicholas-leonard/dp/blob/master/examples/recurrentlanguagemodel.lua)
• Imagenet single GPU and multi-GPU demo by Facebook
• Recurrent Models for Visual Attention - for image classification
• Deep Recurrent Attentive Writer - for image generation
• Recurrent Networks with Long Short-term memory (LSTM) - for Language modeling
• Character Level RNNs with LSTM/GRU - Training character-level language models for Latex, English language, Linux kernel C code etc.
• Another face detector by @jonathantompson
• Training a Convnet for the Galaxy-Zoo Kaggle challenge(CUDA demo)
• Kaggle CIFAR-10 competition Examples of Network-in-Network and GoogleNet Inception modules by @nagadomi
• Neural Turing Machines - A modified version of NTM with LSTM memory cells
• Recpool - Reconstructing pooling networks by Jason Rolfe, this branch has some fixes.
• Music Tagging - Music Tagging scripts for torch7 by Mikael Henaff
• K-Means feature learning over CIFAR-10: Coates-Single-Layer Networks in Unsupervised Feature Learning
• imagenet loading + training - Train imagenet networks, like AlexNet, MattNet etc.
• Caffe models in Torch - Several state-of-the-art models released to the Caffe PublicZoo can now be used in torch, thanks to @szagoruyko. For non-sequential models like ResNets, try caffegraph.
• libCCV models in Torch - libccv provides state-of-the-art models for computer vision. Load these models in torch and use them naturally.
• Variational Auto encoders
• Object detection using rcnn and spp by fmassa
• Stacked Hourglass Networks for Human Pose estimation - State-of-the-art on the FLIC and MPII benchmarks (2016/3/26).
• Generating adversarial examples and training a model with adversarial cost

List of Packages by Category

General Math

• torch - The core torch package. Apart from tensor operations, has convolutions, cross-correlations, basic linear algebra operations, eigen values/vectors etc.
• cephes - Cephes mathematical functions library, wrapped for Torch. Provides and wraps the 180+ special mathematical functions from the Cephes mathematical library, developed by Stephen L. Moshier. It is used, among many other places, at the heart of SciPy.
• graph - Graph package for Torch
• randomkit - Numpy's randomkit, wrapped for Torch
• signal - A signal processing toolbox for Torch-7. FFT, DCT, Hilbert, cepstrums, stft

Data formats

• csvigo - A CSV library, for Torch
• hdf5 - Read and write Torch tensor data to and from Hierarchical Data Format files.
• lua-cjson - A fast JSON encoding/parsing module
• dataload - Load images from disk using multi-threading, etc.
• mattorch - An interface between Matlab and Torch (This repo is mostly abandoned and not maintained.)
• matio - Package to load tensors from Matlab .mat files, without having matlab installed on your system. Needs open source libmatio.
• LuaXML - a module that maps between Lua and XML without much ado
• lua-capnproto Basically like Protocol buffers except MUCH faster
• LuaZip - Library for reading files inside zip files
• MIDI - Reading, writing and manipulating MIDI data
• audio - Loads as Tensors, all audio formats supported by libsox (mp3, wav, aac, ogg, flac, etc.)
• csv2torchdatasets - Simple Torch7 tool for converting Kaggle-style csv files to torch-datasets.
• image - Loads png, jpg, ppm images
• graphicsmagick - A full Torch/C interface to GraphicsMagick's Wand API and to imagemagick commandline utility, loads all images thrown its way.
• ffmpeg - A simple abstraction class, that uses ffmpeg to encode/decode videos from/to Torch Tensors
• csv2tensor - Package for loading CSV files containing numeric data directly to Torch Tensors
• torchx - Contains paths.indexdir which can be used to efficiently load directories containing thousands of files
• npy4th - Loads NumPy .npy and .npz
• torch-dataframe - Loads and manipulates tabular data (e.g. Kaggle-style CSVs) inspired from R's and pandas' data

Machine Learning

• nn - Neural Network package for Torch
• nngraph - This package provides graphical computation for nn library in Torch7.
• dp - A deep learning library designed for streamlining research and development using the Torch7 distribution.
• dpnn - deep extensions to nn : nn.ReverseTable, nn.ZipTable, nn.Inception, nn.Dictionary, etc.
• rnn - Recurrent Neural Network library for nn
• nnx - A completely unstable and experimental package that extends Torch's builtin nn library
• optim - An optimization library for Torch. SGD, Adagrad, Conjugate-Gradient, LBFGS, RProp and more.
• hypero - Simple distributed hyper-optimization library for torch7
• nninit - Weight initialisation schemes for nn modules
• unsup - A package for unsupervised learning in Torch. Provides modules that are compatible with nn (LinearPsd, ConvPsd, AutoEncoder, ...), and self-contained algorithms (k-means, PCA); see unsupgpu to run ConvPsd on mini-batches with CUDA.
• Autoencoders - Selection of autoencoders (sparse, convolutional, denoising, sequence-to-sequence, variational, adversarial)
• manifold - A package to manipulate manifolds
• metriclearning - A package for metric learning
• rbm_toolbox - Restricted Boltzmann Machines in torch
• svm - Torch-SVM library
• lbfgs - FFI Wrapper for liblbfgs
• vowpalwabbit - An old vowpalwabbit interface to torch.
• OpenGM - OpenGM is a C++ library for graphical modeling, and inference. The Lua bindings provide a simple way of describing graphs, from Lua, and then optimizing them with OpenGM.
• sphagetti - Spaghetti (sparse linear) module for torch7 by @MichaelMathieu
• LuaSHKit - A lua wrapper around the Locality sensitive hashing library SHKit
• kernel smoothing - KNN, kernel-weighted average, local linear regression smoothers
• component analysis - PCA, Whitened PCA, LDA, LPP, NPP, FastICA.
• reinforcement learning - Implementing exercises from Sutton & Barto's textbook Reinforcement Learning: An Introduction
• warp-ctc - A fast parallel implementation of CTC (Connectionist Temporal Classification), useful for performing supervised learning on sequence data, without needing an alignment between input data and labels.
• torch-autograd - Autograd automatically differentiates native Torch code

Visualization

Mainly provided by three styles:

• iTorch - An iPython kernel for torch. Has visualization of images,video, audio and plotting. Example notebook

or

• qtlua - Powerful QT interface to Lua
• qttorch - QT interface to Torch
• gnuplot - Torch interface to Gnuplot
• iterm.torch - Displays images and other docs right in terminal (OS X only)

or

• display - A simplified version of gfx.js that is easier to install and use.
• gfx.js - A graphics backend for the browser, with a Torch7 client. Extend this by writing simple html/javascript templates
• visdom - Like display/gfx.js but with more capabilities, supports Torch

An excellent overview of all plotting packages in torch is given by Florian Strub in this blogpost:http://www.lighting-torch.com/2015/08/24/plotting-with-torch7/

Computer Vision

• fex - A package for feature extraction in Torch. Provides SIFT and dSIFT modules.
• imgraph - An image/graph library for Torch. This package provides routines to construct graphs on images, segment them, build trees out of them, and convert them back to images.
• videograph - A video/graph library for Torch. This package provides routines to construct graphs on videos, segment them, build trees out of them, and convert them back to videos.
• dp - A deep learning library for Torch. Includes preprocessing like Zero-Component Analysis whitening, Global Contrast Normalization, Lecun's Local Contrast Normalization and facilities for interfacing your own.
• opencv wrapper by @marcoscoffier
• saliency - code and tools around integral images. A library for finding interest points based on fast integral histograms.
• stitch - allows us to use hugin to stitch images and apply same stitching to a video sequence
• sfm - A bundle adjustment/structure from motion package
• optical-flow - This is a simple wrapper around the optical-flow algorithm developed/published by C.Liu
• depth-estimation - Depth estimation scripts by @MichaelMathieu
• depth-estimation2 - Depth estimation scripts by @MichaelMathieu
• OpenCV 2.4 - a simple wrapper for certain funcs from the OpenCV library, version 2.4
• sfm2 - OpenCV based SFM functions for Torch
• OverFeat - A quick feature extractor based on Overfeat with pretty clunky torch bindings
• Overfeat-torch - Better Overfeat bindings for Torch by @jhjin
• similarity-matching-ratio tracker - A state-of-the-art tracker by Aysegul Dundar. More info here
• Caffe bindings for Torch
• torch-opencv - OpenCV 3.0 bindings for LuaJIT+Torch
• gSLICr-torch - gSLICr superpixel algorithm binding for Torch
• pcl - Point Cloud Library (PCL) bindings for Torch
• gvnn - Geometric Vision with Neural Networks (includes Spatial Transformer Networks)

Images

• image - An image library for Torch. This package provides routines to load/save and manipulate images using Torch's Tensor data structure, changing color spaces, rotate, translate, warp etc.
• graphicsmagick - A wrapper to GraphicsMagick (binary). GraphichsMagick (.org) is a tool to convert images, quite efficiently. This package provides bindings to it.
• imgraph - An image/graph library for Torch. This package provides routines to construct graphs on images, segment them, build trees out of them, and convert them back to images.

Videos

• camera - A simple wrapper package to give torch access to a webcam
• ffmpeg - An FFMPEG interface for Torch. A simple abstraction class, that uses ffmpeg to encode/decode videos, and represent them as Tensors, in Torch.
• videograph - A video/graph library for Torch. This package provides routines to construct graphs on videos, segment them, build trees out of them, and convert them back to videos.
• torchvid - A Torch interface to the FFmpeg libraries for reading video image data. In contrast to lua---ffmpeg, torchvid does not use the ffmpeg executable or write frames to temporary files. This package also supports video transformations with filtergraphs (such as cropping, flipping and resizing).

Audio

• audio - Audio library for Torch-7. Support audio I/O (Load files) Common audio operations (Short-time Fourier transforms, Spectrograms).
• lua-sndfile - An interface to libsndfile
• lua-pa - Interface to PortAudio library

Natural Language Processing

• nn - Neural language models such as ones defined in Natural Language Processing (almost) from Scratch can be implemented using the nn package. nn.LookupTable is useful in this regard.
• rnn - Recurrent Neural Network library that has a Recurrent and LSTM that can be used for language modeling.
• dp - A deep learning library for Torch. Includes Neural Network Language Model Tutorial and Recurrent Neural Network Language Model implementations using the Google Billion Words dataset.
• senna - Part-of-speech tagging, Chunking, Name Entity Recognition and Semantic Role Labeling, extremely fast and used to be state-of-the-art (dont know now)
• word2vec - Ready to use word2vec embeddings in torch. This repo reads the bin file of word2vec and loads the embeddings to be used. Provides example.
• GloVe - Ready to use GloVe embeddings in torch. This repo reads the text files of GloVe and loads the embeddings to be used. Provides example.
• torch-word-emb - load Word2Vec and GloVe word embeddings to Torch Tensors, implemented in pure C

Sensor Input/Output

• camera - A simple wrapper package to give torch access to a webcam
• mongoose 9dof - Lua/Torch bindings for the Mongoose 9DoF IMU
• AR.Drone - AR.Drone bindings for torch by @MichaelMathieu
• Arcade Learning Environment - A lua wrapper to ALE by Google Deepmind

Distributed Computing / Parallel Processing

• parallel - A simple yet powerful parallel compute package for Torch. Provides a simple mechanism to dispatch and run Torch/Lua code as independent processes and communicate via ZeroMQ sockets. Processes can be forked locally or on remote machines (via ssh).
• thmap - Map jobs onto th nodes (built on top of async)
• threads - An FFI threading system based on SDL2 by Ronan Collobert. More powerful than llthreads, as it allows trivial data sharing between threads.
• lua-llthreads - Low-Level threads(pthreads or WIN32 threads) for Lua.
• MPIT - MPI for Torch by Sixin Zhang
• lua-mapreduce - A map-reduce framework by Paco Zamora Martínez
• hypero - Simple distributed hyper-optimization library for torch7
• torch-ipc - A set of primitives for parallel computation in Torch
• torch-distlearn - A set of distributed learning algorithms for Torch

Alternative REPLs

• trepl - An embedabble, Lua-only REPL for Torch.
• env - Adds pretty printing of tensors/tables and additional path handling to luajit

Utility libraries

Utility toolboxes

• penlight - Lua utility libraries loosely based on the Python standard libraries
• moses - A more up-to-date alternative to underscore
• underscore - Underscore is a utility-belt library for Lua
• torchx - Contains extensions to torch for concatenating tensors, indexing folders, hashing strings and working with nested tables of tensors.

Documentation

• torch-dokx - An awesome automatic documentation generator for torch7
• dash-docset-torch - Dash/Zeal docset for torch and related libraries.

File System

• fs - File system toolbox
• paths - Paths manipulations

Programming helpers

• argcheck - Advanced function argument checker
• class - Simple object-oriented system for Lua, with classes supporting inheritance
• classic - More advanced object-oriented system for Lua
• cwrap - Advanced automatic wrapper for C functions
• fn - Some functional programming tools for Lua and Torch.
• inline-c - A package to dynamically build and run C from within Lua. Each function gets wrapped in it own little lua library which is then made accessible to the Lua runtime.

Printing / Logging / Debugging

• MobDebug - The best debugger for lua. Remote debugger for the Lua programming language
• pprint - A pretty print library for Torch and lua
• logroll - A basic logging library for Lua and Torch.
• xlua - Extra Lua functions. Lua is pretty compact in terms of built-in functionalities: this package extends the table and string libraries, and provide other general purpose tools (progress bar, ...).

Testing

• totem - Alternate torch unit test module

Social

• OAuth - Lua OAuth, an OAuth client library.
• SocialLua - Library for interfacing with many sites and services
• twitter - A Twitter library for Lua.

Uncategorized

• buffer - A buffer object for LuaJIT (to get around LuaJIT limitations)
• curl - An interface to CURL.
• eex - Torch extras from e-Lab
• python - A wrapper to Python
• torch-ipython - An ipython kernel for torch
• restclient - A REST Client.
• sys - A system library for Torch
• utf8 - Basic UTF-8 support.
• util - Random utilities for Lua and Torch.
• uuid - Generates uuids in pure Lua
• net-toolkit - This package allows to save and retrive to/from disk a lighter version of neural networks that is being trained by clearing out their gradients and states.

Databases

• lmdb.torch - LMDB Wrapper for Torch
• ljffi-mongo - MongoDB bindings using Mongo's C driver
• mongorover - MongoDB bindings that easily install into torch7
• lsqlite3 - A binding for Lua to the SQLite3 database library
• LuaSQL-MySQL - Database connectivity for Lua (MySQL driver)
• LuaSQL-Postgres - Database connectivity for Lua (Postgres driver)
• LuaSQL-SQLite3 - Database connectivity for Lua (SQLite3 driver)
• Luchia - Lua API for CouchDB.
• sqltable - Use sql databases as lua tables, SELECT, INSERT, UPDATE, and DELETE are all handled with metamethods in such a way that no SQL needs to be written in most cases.
• persist - A persisting table, built on Redis.
• redis-async - A redis client built off the torch/lua async framework
• redis-queue - A redis queue framework using async redis
• luamongo - Lua driver for mongodb (Use v0.2.0 rockspec) Interfaces to third-party libraries

• sdl2 - A FFI interface to SDL2
• sundown - A FFI interface to the Markdown implementation of the Sundown library
• fftw3 - A FFI interface to FFTW3
• cairo - A FFI interface to Cairo Graphics
• LUSE - Lua bindings for the Filesystems in Userspace (FUSE) library
• lzmq-ffi - Lua bindings to ZeroMQ
• Readline - Interface to the readline library
• LuaSec - A binding for OpenSSL library to provide TLS/SSL communication over LuaSocket.
• PLPlot-FFI - LuaJIT wrapper for PLplot
• libmatio - An FFI interface to libmatio and torch wrappers to load tensors as well.
• ncurses - ncurses wrapper for lua

Asynchronous paradigm - (like nodejs)

• async - An async framework for Torch (based on LibUV)
• redis-async - A redis client built off the torch/lua async framework
• redis-queue - A redis queue framework using async redis
• async-connect - A Connect implementation in Lua

Networking

• LuaSocket - Network support for the Lua language
• nixio - System, Networking and I/O library for Lua
• waffle - Express-like web framework

Security

• LuaSec - A binding for OpenSSL library to provide TLS/SSL communication over LuaSocket.

CUDA

Using multiple GPUs parallely is supported. Look at this link for more info

• cutorch - Torch CUDA Implementation
• cunn - Torch CUDA Neural Network Implementation
• cunnx - Experimental CUDA NN implementations
• nnbhwd - Convnet implementations with the data-layout BHWD (by Maxime Oquab), very useful for certain applications.
• cudnn - NVIDIA CuDNN Bindings
• ccn2 - cuda-convnet2 wrapped for torch
• FindCUDA - Activate incremental builds for cutorch and cunn (experimental)
• Training an Object Classifier in Torch-7 on multiple GPUs over ImageNet - Tutorial for training with Torch7 on multiple GPUs.

OpenCL

• cltorch - Torch OpenCL Implementation
• clnn - Torch OpenCL Neural Network Implementation
• jtorch - Torch cross-platform OpenCL Neural Network Prediction
• pycltorch - Wrappers for using cltorch/clnn from Python.

Reinforcement Learning

• dpnn - provides modules and criterions that implement the REINFORCE algorithm.
• rlenvs - Reinforcement learning environments
• rlcore - Reinforcement learning package (different environments and learning policies) with an interface to openAI Gym
• Atari - DQN, A3C, and related deep reinforcement learning algorithms

Miscellaneous

Packages which I didn't know where to put

• re - Real Estate software
• lutorpy - A python library for bridging Lua/Torch and Python/Numpy.
• pytorch - Wrappers for using Lua and Torch from Python.
• usegpu - A convenient script to assign active GPU(s) for current session.

Creating your own package

You can quickly fork off of this example package:

• https://github.com/soumith/examplepackage.torch

Debuggers / Visual Debuggers / IDEs

• Debugging tutorials for Lua and shared object bindings
• ZeroBrane Studio - Provides a great IDE and visual debugging.
• LDT - An eclipse plugin for Lua.

Some advice from Florian STRUB:

• Eclipse + plugin. Its debug mode is very powerful with watcher, interactive console, stack-trace and so on. It has nice refactoring features but its coloring is quite poor.
• zerobrane is the standard Lua IDE, it works well and its debug mode is fine. Yet, you have to use a fork to use torch (zbs-torch). [There is now full integration via a plugin.] To my mind, this IDE is a bit limited.
• IntellJ + Lua plugin. The best IDE so far with with nice coloring and excellent refactoring tools. Its debug mode is experimental so it might not work with some of your project.

Therefore, I strongly advise you to use Eclipse if you are willing to use advanced debugging features.http://www.eclipse.org/ldt/

In order to run Torch from Eclipse, Torch's LuaJIT should be added via Windows -> Preferences -> Lua -> Interpreters.

GPU Support

CUDA Support, CUDA examples

• Torch: CUDA is supported by installing the package cutorch .
  • Call require "cutorch" on a CUDA-capable machine
  • You get an additional tensor type torch.CudaTensor (just like torch.FloatTensor).
  • CUDA double precision is not supported.
  • Using multiple GPUs parallely is supported. Look at this link for more info
• NN: Install the package cunn
  • Caveats: SpatialConvolutionMM is the very fast module (on both CPU and GPU), but it takes a little bit of extra memory on the CPU (and a teeny bit extra on the GPU).
  • An alternative is to use NVidia CuDNN, which is very reliable, or cuda-convnet2 bindings, or nnbhwd package
  • nnbhwd - Convnet implementations with the data-layout BHWD (by Maxime Oquab), very useful for certain applications.
  • cudnn - NVIDIA CuDNN Bindings
  • ccn2 - cuda-convnet2 ported to torch

NVIDIA Jetson TK1

• Installation and usage instructions for Torch + CuDNN on Jetson TK1

OpenCL support, OpenCL examples

• For a fairly complete port of torch to OpenCL, please see distro-cl
• For cross-platform GPU prediction, please see jtorch

CPU backends

• nnpack.torch - very fast convolutions for modern Intel CPUs.

Gotchas

LuaJIT limitations, gotchas and assumptions

Must read! - http://luapower.com/luajit-notes

2GB and addressing limit

Legacy

• Torch3
• Torch4
• Torch5