IPython kernel for Torch with visualization and plotting
Jupyter Notebook Lua Other
Latest commit 488ac01 Oct 7, 2016 @nhynes nhynes committed with Facebook Github Bot Allow redef of torch classes
Running code that defines classes using `torch.class` in an interactive environment leads to the well-intentioned but undesirable `parent class/factor is already defined` error.

This PR introduces a hacky workaround that silently unsets the existing class if it already exists.
Closes #136

Reviewed By: soumith

Differential Revision: D3982016

Pulled By: ebetica

fbshipit-source-id: 4fa402ee9254e9127025910ea0ef9a4ea6535a55
Failed to load latest commit information.
kernelspec add torch logo to kernelspec Feb 4, 2015
screenshots adding historam docs Jan 22, 2015
static removing jquery Jan 14, 2015
.gitignore gitignore Nov 2, 2014
.luacheckrc Make iTorch LuaCheck-clean Dec 4, 2014
CMakeLists.txt plots working in itorch again Jan 6, 2015
CONTRIBUTING.md Fix formatting issue in CONTRIBUTING.md Apr 21, 2015
IOHandler.lua Add session_key attribute to util module Apr 21, 2015
LICENSE adding license Jan 14, 2015
PATENTS updating PATENTS file Apr 20, 2015
Plot.lua Fix legend issue. Sep 10, 2016
README.md install compatible lzmq for Ubuntu Sep 6, 2016
_env.lua adding license Jan 14, 2015
bokeh.lua adding license Jan 14, 2015
completer.lua fixes for jupyter 4.1.0 Feb 4, 2016
custom.css adding contrast fix Jan 8, 2015
custom.js overriding xlua.progress for usability Feb 12, 2015
gfx.lua Stream instead of print Sep 11, 2016
iTorch_Demo.ipynb adding docs about new features Dec 22, 2015
init.lua Allow redef of torch classes Oct 7, 2016
ipynblogo.png logo overwrite Oct 23, 2014
itorch correct typo in itorch launcher Jul 17, 2016
itorch-scm-1.rockspec adding luacrypto dep to rockspec May 1, 2015
itorch_launcher itorch_launcher: portable test for existence of luajit Jun 11, 2016
main.lua Stream instead of print Sep 11, 2016
small.mp4 fixing bokeh plots on reloading the notebook Jan 8, 2015
test.lua linter fixes Jan 27, 2015
util.lua Add session_key attribute to util module Apr 21, 2015
volkswagen.mp3 test/example for audio and video Jan 7, 2015



iTorch is an IPython Kernel for Torch, with plotting (using Bokeh.js plots) and visualization of images, video and audio


iTorch in notebook mode works like any other IPython notebook.
It provides useful inline auto-complete. Whenever you need auto-complete, use the TAB key.

It also provides inline help using the ? symbol. For example, ?torch.cmul screenshot

In addition, we introduce visualization functions for images, video, audio, html and plots.

itorch.image(img) - You can pass in a 3-D tensor (for a single image), or a table of 3D tensors (image collages).

  itorch.image({image.lena(), image.lena(), image.lena()})


itorch.audio(path) - You can pass in a filename of an audio file. Formats supported are mp3, ogg, aac



itorch.video(path) - You can pass in a filename of a video file. Formats supported are mp4, ogv, mpeg



[window-id] = itorch.html(htmlstring, [window-id]) - Raw HTML string that is passed is rendered. A window handle is returned, that can be reused to replace the HTML with something else.

itorch.html('<p><b>Hi there!</b> this is arbitrary HTML</p>')
window_id = itorch.html('<p>This text will be replaced in 2 seconds</p>')
os.execute('sleep 2')
itorch.html('<p>magic!</p>', window_id)



iTorch can plot to screen in notebook mode, or save the plot to disk as a html file.

A Plot object is introduced, that can plot different kinds of plots such as scatter, line, segment, quiver plots.

Plot = require 'itorch.Plot'

The plotting can be extended to more kinds of plots, as it uses Bokeh.js as its backend.

x1 = torch.randn(40):mul(100)
y1 = torch.randn(40):mul(100)
x2 = torch.randn(40):mul(100)
y2 = torch.randn(40):mul(100)
x3 = torch.randn(40):mul(200)
y3 = torch.randn(40):mul(200)

-- scatter plots
plot = Plot():circle(x1, y1, 'red', 'hi'):circle(x2, y2, 'blue', 'bye'):draw()
plot:circle(x3,y3,'green', 'yolo'):redraw()
plot:title('Scatter Plot Demo'):redraw()
-- print(plot:toHTML())


-- line plots
plot = Plot():line(x1, y1,'red','example'):legend(true):title('Line Plot Demo'):draw()
-- segment plots
plot = Plot():segment(x1, y1, x1+10,y1+10, 'red','demo'):title('Segment Plot Demo'):draw()
-- quiver plots
U = torch.randn(3,3):mul(100)
V = torch.randn(3,3):mul(100)
plot = Plot():quiver(U,V,'red',''):title('Quiver Plot Demo'):draw()


-- quads/rectangles
plot = Plot():quad(x1,y1,x1+1,y1+1,'red',''):draw()
-- histogram
plot = Plot():histogram(torch.randn(10000)):draw()


Hover Tool in Plotting

local t = torch.Tensor
local y = t(10)
local x = t(y:size()):zero()
local labels = {}
for i = 1, 10 do
    y[i] = i
    labels[i] = tostring(i)

  :circle(x, y, 'red', nil, {foo=labels})
  :hover_tool({{'xy', '@x @y'}, {'foo', '@foo'}})

Text method to plotting

local t = torch.Tensor
local y = t(10)
local x = t(y:size()):zero()
local labels = {}
for i = 1, 10 do
    y[i] = i
    labels[i] = tostring(i)

itorch.Plot():gscatter(x, y)
  :text(x, y, labels, y, 'black')
  :triangle(x, y, 'blue')

Group Scatter plot

Run the following in itorch to produce plots:

x = torch.randn(200); y = torch.randn(200); x:narrow(1, 1, 100):add(2);
labels = torch.LongTensor(200):zero(); labels:add(1); labels:narrow(1, 1, 100):add(1)
itorch.Plot():gscatter(x, y):title('Scatter plot without labels'):draw()
itorch.Plot():gscatter(x, y, labels):title('Scatter plot with labels and legend #1'):legend(true):draw()
itorch.Plot():gscatter(x, y, labels, true):title('Scatter plot with labels and legend #2'):draw()
itorch.Plot():gscatter(x, y, labels, false):title('Scatter plot with labels and no legend'):draw()


iTorch requires or works with

  • Mac OS X or Linux (tested in Ubuntu 14.04 and Arch Linux)
  • Torch-7
  • IPython version 2.2 or above (you can check your version of ipython using ipython --version)
  • ZeroMQ
brew install zeromq
brew install openssl
luarocks install luacrypto OPENSSL_DIR=/usr/local/opt/openssl/

# Ubuntu
sudo apt-get install libzmq3-dev libssl-dev python-zmq

# Ubuntu 16
luarocks install lzmq

Installing iTorch

git clone https://github.com/facebook/iTorch.git
cd iTorch
luarocks make 

If you have to use sudo for some reason (if you globally installed torch on Linux for example), use these commands:

sudo env "PATH=$PATH" luarocks make
sudo chown -R $USER $(dirname $(ipython locate profile))

Docker Images

Ubuntu 14.04 + iTorch notebook + Miniconda: see docker hub repo.

docker pull dhunter/itorch-notebook

How iTorch works

Start iTorch at command-line using the following command:

itorch notebook  # notebook mode
itorch  # console mode
itorch qtconsole  # Qt mode

In notebook mode, you can use the "New" button to create a new notebook.


Demo iTorch notebook: http://nbviewer.ipython.org/github/facebook/iTorch/blob/master/iTorch_Demo.ipynb

Join the Torch community

See the CONTRIBUTING file for how to help out.


iTorch is BSD-licensed. We also provide an additional patent grant.