uncomplicate.diamond.tensor — org.uncomplicate/deep-diamond-base 0.34.0

Contains type-agnostic general tensor functions. Does not contain functions related to deep neural networks (DNN); see the [[dnn]] namespace for these.

How to use

(ns test
  (:require [uncomplicate.diamond
             [tensor :refer :all]
             [native :refer :all]]))

Examples

The best and most accurate examples can be found in the comprehensive test suite, full examples, core tensor examples core DNN examples internal CPU engine tests, internal GPU engine tests,

There are quite a few tutorials on my blog dragan.rocks.

For the comprehensive real-world examples, with detailed tutorials and guides, see the Interactive Programming for Artificial intelligence book series, and specifically the Deep Learning for Programmers book.

Cheat Sheet

• Default engine (factory) binding: *diamond-factory*, with-diamond. All functions can also receive engine through parameters.

• Tensor descriptor: desc, [[shape]], [[layout]], [[data-type]],

• Create : tensor, transformer, batcher, shuffler

• Inspect, transform, and manage tensors: [[view-tz]], [[revert]], [[input]], [[output]], [[connector]], batch-size, offset!.

Tensors support typical core Fluokitten functions.

*diamond-factory* clj

The default factory binding. Most polymorphic functions that have factory as a parameter, have a version that uses this binding. The default is nil, though, and the user has to require a namespace that initializes and binds the default engine. The most common way is to require uncomplicate.diamond.native, which binds the DNNL based CPU engine as the default, but you are free to provide another implementation of your own, either by this root binding, or through Clojure's dynamic binding through with-diamond.

Please see [dnnl-tensor-test] for examples.

batch-size clj

(batch-size x)

Determines batch size from tensor or descriptor's shape, depending on the context. Usually batch size is the first shape entry, but in some cases (RNN for example) it may be the second entry, or even something else.

batcher clj

(batcher x y)

(batcher x y mb-size)

Creates a function that can transfer mini-batches of tensor x to tensor y.

Useful for, but not limited to, cycling through mini-batches during stochastic gradient descent. Assumes that the input data has already been shuffled (but does not depend on it technically).

Example:

(def t1 (tensor [2 3] :float :nc))
(def t2 (tensor [1 3] :float :cn))
(transfer! (range) t1)
(def bat (batcher t1 t2))

(bat)
=>
{:shape [1 3], :data-type :float, :layout [1 1]}
[   0.00    1.00    2.00 ]

(bat 1)
=>
{:shape [1 3], :data-type :float, :layout [1 1]}
[   3.00    4.00    5.00 ]

ConnectorCreator clj protocol

An object that can create a connection and provide its state in another shape, or gets its state from an object with another shape.

connector clj

(connector in out)

Creates a connector between in and out descriptor or tensor.

default-desc clj

(default-desc tdesc)

(default-desc shape type)

Creates a general, technology-agnostic, tensor descriptor with default contiguous stride appropritate for input descriptors' shape.

desc clj

(desc tdesc)

(desc shape layout)

(desc shape type layout)

Creates a general, technology-agnostic, tensor descriptor.

The required parameter shape is a vector of tensor dimensions. Optionally, type and layout can be provided as keywords, that are later transformed to appropriate internal implementations supported by specific backends. Alternatively, layout might be provided as a vector of offsets.

Examples:

(desc [2 3 2]) => {:shape [2 3 2], :data-type nil, :layout nil}
(desc [2 3] :nc) => {:shape [2 3], :data-type nil, :layout :nc}
(desc [2 3 2 4] :nhwc) => {:shape [2 3 2 4], :data-type nil, :layout :nhwc}

offset! clj

(offset! tz n)

Destructively moves tensor's beginning to a different place in the underlying memory.

Revert clj protocol

A directed transformation whose direction can be reverted.

revert clj

(revert this)

Revert the direction of the transformation

shuffler clj

(shuffler x y)

Creates a function that can transfer randomly selected columns of tensor x to tensor y in mini-batches.

Useful for, but not limited to, cycling through mini-batches during stochastic gradient descent. The difference from batcher is that it randomly selects the grouping of columns. Shuffler is generally slower than plain batcher; it may or may not make a difference in speed.

Example:

(def t1 (tensor [2 3] :float :nc))
(def t2 (tensor [1 3] :float :cn))
(transfer! (range) t1)
(def bat (batcher t1 t2))

(bat)
=>
{:shape [1 3], :data-type :float, :layout [1 1]}
[   0.00    1.00    2.00 ]

(bat 1)
=>
{:shape [1 3], :data-type :float, :layout [1 1]}
[   3.00    4.00    5.00 ]

tensor clj

(tensor desc)

(tensor tz-factory desc)

(tensor shape type layout)

(tensor tz-factory shape type layout)

(tensor tz-factory shape type layout batch-index)

Creates a technology-specific tensor.

The backend is determined by tz-factory, while the structure is provided either from a general or technology specific descriptor desc, or from directly provided descriptor parameters shape, type, and layout. If tz-factory is not provided, it is taken from the *diamond-factory* binding, which is by default [[internal/dnnl]].

Examples:

(tensor {:shape [2 3] :data-type :float :layout :nc})
=>
{:shape [2 3], :data-type :float, :layout [3 1]}
[   0.00    0.00    0.00    ⋯      0.00    0.00 ]

(tensor (desc [2 3] :float :nc))
=>
{:shape [2 3], :data-type :float, :layout [3 1]}
[   0.00    0.00    0.00    ⋯      0.00    0.00 ]

(tensor [2 3] :float :nc)
=>
{:shape [2 3], :data-type :float, :layout [3 1]}
[   0.00    0.00    0.00    ⋯      0.00    0.00 ]

TensorContainer clj protocol

An object that can be viewed as a tensor.

view-tz clj

(view-tz this)

(view-tz this sub)

View the object's underlying data through a (sub)tensor

TensorDescriptor clj protocol

Generic tensor descriptor. Most Clojure and Java data types and structures (such as numbers, collections, persistent structures, etc. can be used as tensor descriptors). Technology-specific engines often provide their own implementation internally. Please see Deep Diamond tests, examples, and the Deep Learning for Programmers book.

data-type clj

(data-type tz)

Data type of tensor entries (:float).

layout clj

(layout tz)

Tensor layout, as a keyword (:nchw).

shape clj

(shape tz)

Tensor shape, as a vector ([2 3 4]).

Transfer clj protocol

An operation that transfers input to output.

input clj

(input this)

The input tensor of the Transfer.

output clj

(output this)

The output tensor of the Transfer.

transformer clj

(transformer x y)

Creates a function optimized for transferring data from tensor x to tensor y.

Example:

(def t1 (tensor [2 3] :float :nc))
(transfer! (range) t1)
(def t2 (tensor [2 3] :float :cn))
(def tr-1-2 (transformer t1 t2))

(tr-1-2)
=>
{:shape [2 3], :data-type :float, :layout [1 2]}
[   0.00    3.00    1.00    ⋯      2.00    5.00 ]

t2
=>
{:shape [2 3], :data-type :float, :layout [1 2]}
[   0.00    3.00    1.00    ⋯      2.00    5.00 ]

with-diamond clj macro

(with-diamond factory-fn params & body)

Dynamically binds a factory created by factory-fn with parameters params, and evaluates body in the context of that factory.

See [[*diamond-factory]].