Skip to content
A ground-up and standalone reimplementation of TensorFlow for ruby. Comes with a pure ruby and OpenCL opcode evaluator
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Use custom circleci dockerfile Jun 5, 2018
bin v1.0.1 changes Mar 3, 2019
exe v1.0.1 changes Mar 3, 2019
lib bug fix for grayscale jpg images Jun 13, 2019
spec bug fix for grayscale jpg images Jun 13, 2019
.gitignore feature 1.0.7 Apr 8, 2019
.rake_tasks~ Initial commit May 11, 2018
.rspec Initial commit May 11, 2018
.rubocop.yml v1.0.1 changes Mar 3, 2019
.travis.yml Initial commit May 11, 2018 Update CHANGELOG Apr 8, 2019 Initial commit May 11, 2018
Dockerfile Revert bundler update Mar 16, 2019
Gemfile v1.0.1 changes Mar 3, 2019
LICENSE.txt Update copyright notice to 2019 [ci skip] Jan 12, 2019 Add a USAGE guide Jan 7, 2019
Rakefile v1.0.1 changes Mar 3, 2019 Squashed commit of the following: Mar 23, 2019
benchmark_intel.txt Squashed commit of the following: Jun 26, 2018
benchmark_nvidia.txt Squashed commit of the following: Jun 26, 2018
benchmark_ryzen_amd.txt Add ruby like floor and ceil calls to tensor object Jun 27, 2018
tensor_stream.gemspec Add jpeg decode support Jun 12, 2019

Gem VersionGem VersionCircleCI Join the chat at


TensorStream is an opensource framework for machine learning for ruby, its goal is to allow machine learning models to be easily built and run them in various hardware like GPUs and CPUs. It is heavily based on TensorFlow with the goal of being able to easily port its higher level libraries and model examples. As such it is also based on data flow graphs wherein you define computations and data flows between those computations in order to achieve the desired output.

TensorStream is designed to support various backends with a Pure Ruby and OpenCL implementation. These implementations are designed to work together, you can perform training on an OpenCL implementation (where you have a GPU) and then run the resulting trained model on a Pure Ruby implementation where you can deploy anywhere that you can run ruby on. TensorStream has been tested to run on most ruby implementations like MRI, JRuby and TruffleRuby.

Goals & Features

  • Easy to use - Improve model readability
  • Replicates most of the commonly used low-level tensorflow ops (tf.add, tf.constant, tf.placeholder, tf.matmul, tf.sin etc...)
  • Supports auto-differentiation using formal derivation
  • Extensible - use your own opcode evaluator (OpenCL and Pure ruby currently supported)
  • wide support - Run on most ruby implementations as well as hardware acceleration on OpenCL supported hardware


TensorStream comes with a pure ruby and OpenCL implementation out of the box. The pure ruby implementation is known to work with most ruby implementations including TruffleRuby, JRuby as well as jit enabled versions of mri (ruby-2.6.0).

OpenCL is supported only on mri implementations of ruby. This can be enabled by adding OpenCL evaluator gem (Make sure you have OpenCL drivers installed correctly on your system):

gem 'tensor_stream-opencl'

and then (without bundler)

require 'tensor_stream/opencl'

OpenCL is basically a requirement for deep learning and image processing tasks as the ruby implementation is too slow even with jit speedups using latest ruby implementations.

OpenCL kernels used by tensorstream can be found at tensor_stream/lib/evaluator/opencl/kernels. These are non specific and should work with any device that supports OpenCL including intel GPUs and CPUs, as well as GPUs from Nvidia and AMD.


Installation is easy, no need to mess with docker, python, clang or other shennanigans, works with both mri and jruby out of the box.

Add this line to your application's Gemfile:

gem 'tensor_stream'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tensor_stream


Usage is similar to how you would use TensorFlow except with ruby syntax. There are also enhancements to the syntax to make it as consice as possible.

Linear regression sample:

require 'tensor_stream'

tf = TensorStream

learning_rate = 0.01
training_epochs = 1000
display_step = 50

train_x = [3.3, 4.4, 5.5, 6.71, 6.93, 4.168, 9.779, 6.182, 7.59, 2.167,
           7.042, 10.791, 5.313, 7.997, 5.654, 9.27, 3.1]

train_y = [1.7, 2.76, 2.09, 3.19, 1.694, 1.573, 3.366, 2.596, 2.53, 1.221,
           2.827, 3.465, 1.65, 2.904, 2.42, 2.94, 1.3]

n_samples = train_x.size

x_value = Float.placeholder
y_value = Float.placeholder

# Set model weights
weight = rand.t.var name: "weight"

bias = rand.t.var name: "bias"

# Construct a linear model
pred = x_value * weight + bias

# Mean squared error
cost = ((pred - y_value)**2).reduce / (2 * n_samples)

# Other optimizers --
# optimizer =, momentum, use_nesterov: true).minimize(cost)
# optimizer =
# optimizer =
# optimizer =
# optimizer =, centered: true).minimize(cost)
optimizer =

# Initialize the variables (i.e. assign their default value)
init = tf.global_variables_initializer

tf.session do |sess|
  start_time =

  (0..training_epochs).each do |epoch| do |x, y|, feed_dict: { x_value => x, y_value => y })

    if (epoch + 1) % display_step == 0
      c =, feed_dict: { x_value => train_x, y_value => train_y })
      puts("Epoch:", '%04d' % (epoch + 1), "cost=", c, \
           "W=",, "b=",

  puts "Optimization Finished!"
  training_cost =, feed_dict: { x_value => train_x, y_value => train_y })
  puts "Training cost=", training_cost, "W=",, "b=",, '\n'
  puts "time elapsed ", - start_time.to_i

You can take a look at spec/tensor_stream/operation_spec.rb for a list of supported ops and various examples and test cases used. Of course these contain only a sliver of what TensorFlow can do, so feel free to file a PR to add requested ops and test cases.

Other working samples can also be seen under tensor_stream/samples.

Samples that are used for development and are still being made to work can be found under test_samples

Python to Ruby guide

Not all ops are available. Available ops are defined in lib/tensor_stream/ops.rb, corresponding gradients are found at lib/tensor_stream/math_gradients.

There are also certain differences with regards to naming conventions, and named parameters:

Variables and Constants

To make referencing python examples easier it is recommended to use "tf" as the TensorStream namespace

At the beginning

tf = TensorStream # recommended to use tf since most sample models on the net use this
ts = TensorStream # use this if you plan to use TensorStream only features, so other devs will know about that

Note the difference in named and optional parameters


w = ts.Variable(0, name='weights')
w = ts.Variable(0, 'weights')


w = ts.variable(0, name: 'weights')
c = ts.constant(1.0)

# concise way when initializing using a constant
w = 0.t.var name: 'weights'
c = 1.0.t

Calling .t to Integer, Array and Float types converts it into a tensor



x = tf.placeholder(tf.float32, shape=(1024, 1024))
x = tf.placeholder(tf.float32, shape=(None, 1024))

ruby supports symbols for specifying data types, nil can be used for None


x = ts.placeholder(:float32, shape: [1024, 1024])
x = ts.placeholder(:float32, shape: [nil, 1024])

# Another a bit more terse way
x = Float.placeholder shape: [1024, 1024]
y = Float.placeholder shape: [nil, 1024]

For debugging, each operation or tensor supports the to_math method

X = ts.placeholder("float")
Y = ts.placeholder("float")
W = ts.variable(rand, name: "weight")
b = ts.variable(rand, name: "bias")
pred = X * W + b
cost = ts.reduce_sum(ts.pow(pred - Y, 2)) / ( 2 * 10)
cost.to_math # "(reduce_sum(|((((Placeholder: * weight) + bias) - Placeholder_2:)^2)|) / 20.0)"

breakpoints can also be set, block will be evaluated during computation

a = ts.constant([2,2])
b = ts.constant([3,3])

f = ts.matmul(a, b).breakpoint! { |tensor, a, b, result_value| binding.pry }


For OpenCL support, make sure that the required OpenCL drivers for your hardware are correctly installed on your system. Also OpenCL only supports ruby-mri at the moment.

To use, include the following gem in your project:

gem 'tensor_stream-opencl'

To use the opencl evaluator instead of the ruby evaluator simply require it (if using rails this should be loaded automatically).

require 'tensor_stream/opencl'

Adding the OpenCL evaluator should expose additional devices available to tensor_stream

# ["job:localhost/ts:ruby:cpu", "job:localhost/ts:opencl:apple:0", "job:localhost/ts:opencl:apple:1"]

Here we see 1 "ruby" cpu device and 2 opencl "apple" devices (Intel CPU, Intel Iris GPU)

By default TensorStream will determine using the given evaluators the best possible placement for each tensor operation

require 'tensor_stream/opencl'

# set session to use the opencl evaluator
sess = ts.session # do stuff

You can manually place operations using ts.device e.g:

ts = TensorStream
# Creates a graph. place in the first OpenCL CPU device

a, b = ts.device('/cpu:0') do
  a = ts.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape: [2, 3], name: 'a')
  b = ts.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape: [3, 2], name: 'b')
  [a, b]

c = ts.device('/device:GPU:0') do
  ts.matmul(a, b)

# Creates a session with log_device_placement set to True.
sess = ts.session(log_device_placement: true)
# Runs the op.

# a : apple:0
# b : apple:0
# a_1 : apple:0
# b_1 : apple:0
# matmul:0 : apple:1
# [[22.0, 28.0], [49.0, 64.0]] => nil

To force the ruby evaluator even with the OpenCL evaluator loaded you can use:

ts.device('/ts:ruby:cpu') do
    # put ops here

Note that the OpenCL evaluator provides speedup if you are using large tensors, tensors that are only using scalars like the linear regression sample will actually be slower.

samples/nearest_neighbor.rb contains a sample that uses opencl.

OpenCL support is maintained as a separate project at:

Export Import Models from tensorflow

Experimental support for parsing and exporting pbtext files are supported:


a = ts.constant([1.0, 1.0])
b = ts.constant([1.5, 1.5])
f = a + b

File.write('my_model.pbtext', f.graph.as_graph_def)

Importing (Experimental)

Note that not all tensorflow ops are supported, warnings will be showed if a certain operation is not supported yet.

  pbtext ='linear_regression.pbtxt'))

  # create a graph from pbtext file
  graph = TensorStream::Graph.parse_from_string(pbtext)

  # reference a tensor by name from the created graph,
  # for example you have a tensor named out
  tensor = graph.get_tensor_by_name("out")

  # set graph as default and do operations on it
  graph.as_default do
    sess = ts.session
    expect(tr( eq([[1.0, 1.0], [1.0, 1.0]])


tensorstream does not support tensorboard yet, but a graphml generator is included:

tf = TensorStream
a = tf.constant(1.0)
b = tf.constant(2.0)
result = a + b
sess = tf.session

File.write('gradients.graphml', # dump graph only
File.write('gradients.graphml',, sess)) # dump with values from session

the resulting graphml is designed to work with yED, after loading the graph change layout to "Flowchart" for best results

Exporting to TensorFlow

Still in alpha but tensorstream supports TensorFlows as_graph_def serialization method:

tf = TensorStream
a = tf.constant(1.0)
b = tf.constant(2.0)
result = a + b
File.write("model.pbtext", result.graph.as_graph_def)

Performance notes

Comparative performance with respect to other ruby libraries have not yet been performed. However it is notable that TruffleRuby and ruby-2.6.0 performs considerably better with respect to previous versions of ruby(< 2.6)

Benchmarks running samples/linear_regression.rb with tensor_stream 1.0.0 on an AMD(R) Ryzen(TM) 3 1300X CPU

ruby 2.5

$ ruby -v
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux]
$ ruby samples/linear_regression.rb
296 seconds 3000 epochs

ruby 2.6.0

$ ruby -v
ruby 2.6.0p0 (2018-12-25 revision 66547) [x86_64-linux]
$ ruby samples/linear_regression.rb
232 seconds 10000 epochs

ruby --jit samples/linear_regression.rb
222 seconds 10000 epochs


$ ruby -v
truffleruby 1.0.0-rc10, like ruby 2.4.4, GraalVM CE Native [x86_64-linux]
246 seconds 10000 epochs


$ ruby -v
jruby (2.5.0) 2018-05-24 81156a8 OpenJDK 64-Bit Server VM 25.191-b12 on 1.8.0_191-8u191-b12-0ubuntu0.18.04.1-b12 +jit [linux-x86_64]
205 seconds 10000 epochs

For training large networks that works on images, the opencl evaluator is the only way to go.


  • Docs
  • Complete low-level op support
  • SciRuby evaluator
  • Opencl evaluator
  • TensorFlow savemodel compatibility


  • This is an early preview release and many things still don't work
  • Performance is not great, at least until the opencl and/or sciruby backends are complete
  • However if you really need an op supported please feel free to file a pull request with the corresponding failing test (see spec/operation_spec.rb)


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at[USERNAME]/tensor_stream. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

You can’t perform that action at this time.