Flint Documentation

Overview

Types and Functions

The use of Tensors alone isn't enough to correctly use Flint. Especially cleaning up the library when you are finished is important to allow the backends to deallocate resources and joining Threads. The function

Flint::cleanup()

automatically cleans up all initialized backends.

template <typename T> struct Tensor

The 1 dimensional implementation of

Tensor

Tensor() : node(nullptr)

Uninitialized Tensor

Tensor(storage_type data) : shape

Creates a Tensor from a

std::vector

. (

storage_type

is a recursive defined type definition, for

n=1

it is just an alias for

std::vector

). E.g.

 Tensor<float, 1> t1{-1., 0., 1., 2.};

Tensor(FGraphNode *node, size_t shape) : node(node), shape

Constructs a Tensor directly from a

FGraphNode

and a shape

Tensor(FGraphNode *node) : node(node)

Constructs a Tensor directly from a

FGraphNode

Tensor(init_type data) : shape

Creates a Tensor from a

std::initializer_list

. (

init_type

is a recursive defined type definition, for

n=1

it is just an alias for

std::initializer_list

). E.g.

 Tensor<float, 1> t(std::vector<float>{-1., 0., 1., 2.});

Tensor(FGraphNode *node, std::array shape)
			: node(node), shape(shape)

Constructs a Tensor directly from a

FGraphNode

and a shape

Tensor(const Tensor &other)

Copy constructor. Copies the underlying Graph structure by creating a new node with the same operation, shape and data types. The new predecessor array points to the same predecessors (memory safety is ensured with reference counting).

other

has result data or if it is a storage node, the complete CPU data is directly copied. Since this operation is expensive it is advised to only use it if it is completly necessary.

void operator=(const Tensor &other)

Copy operator. Copies the underlying Graph structure by creating a new node with the same operation, shape and data types. If there was any previous allocated operation node allocated by this Tensor it is cleaned up. The new predecessor array points to the same predecessors (memory safety is ensured with reference counting).

other

has result data or if it is a storage node, the complete CPU data is directly copied. Since this operation is expensive it is advised to only use it if it is completly necessary.

void operator=(Tensor &&other)

Move operator. Moves every important field from

other

to this Tensor.

other

is invalidated after this operation. If there was any previous allocated operation node allocated by this Tensor it is cleaned up.

~Tensor()

Cleans up this tensor and frees all underlying data by reference counting.

void inverse_broadcasting()

Sometimes there are combinations of nodes where both normal and inverse broadcasting is possible, but yields different results, e.g. multiplication for two nodes with shapes

[3, 5, 3, 5]

and

[3, 5]

. The framework chooses normal broadcasting over inverse if both are possible, this function allows you to alter this behaviour and mark a node to be inversely broadcasted. After the call to this function the given node will from then on only inversely broadcasted (in cases where only normal broadcasting is available an error will occur!). It has no effect in operations that don't use broadcasting. You can "unmark" the node with

disable_inverse_broadcasting

void disable_inverse_broadcasting()

Undoes

inverse_broadcasting

T &operator[](const size_t index)

Indexes the Tensor and returns the element. If the underlying data is not yet computed, executes this Tensor.

static Tensor<T, 1> constant(T value, size_t size)

Generates a Tensor containing the single given value in every entry. The resulting Tensor will have a dimensionality of 1 and a size denoted by

size

. e.g.

 Tensor<double, 1> foo = Tensor<double, 1>::constant(3.141592, 3);
 std::cout << foo << std::endl;
 // Tensor<FLOAT64, shape: 3>([3.141592, 3.141592, 3.141592])

std::vector<char> serialize()

Serializes the underlying data of the Tensor to a binary vector. If the Tensor has no Result Data it is executed.

static Tensor<T, 1> deserialize(char *data, size_t *bytes_read)

Deserializes the binary representation of Tensor data back to a Tensor object. The number of bytes read is stored in

bytes_read

static Tensor<T, 1> deserialize(std::vector data)

Deserializes the binary representation of Tensor data back to a Tensor object.

Tensor<T, 1> reduce_sum()

Reduces one dimension of the tensor by additive folding e.g.

 Tensor<int, 1> a{0, 1, 2, 3, 4, 5, 6};
 std::cout << (a.reduce_sum())() << std::endl;
 // Tensor<INT32, shape: 1>([21])

The results of this Tensor must be available, to ensure that the method may execute the Tensor.

Tensor<T, 1> reduce_mul()

Reduces one dimension of the tensor by multiplicative folding e.g.

 Tensor<int, 1> a{1, 2, 3, 4};
 std::cout << (a.reduce_mul())() << std::endl;
 // Tensor<INT32, shape: 1>([24])

The results of this Tensor must be available, to ensure that the method may execute the Tensor.

Tensor<T, 1> reduce_min()

Reduces one dimension of the tensor by keeping the minimum e.g.

 Tensor<int, 1> a{0, 1, 32, 2, 3, 4, -6, 7, -4}

; std::cout << e.reduce_min()() << std::endl; // Tensor<INT32, shape: [1]>([-6])

The results of this Tensor must be available, to ensure that the method may execute the Tensor.

Tensor<T, 1> reduce_max()

Reduces one dimension of the tensor by keeping the maximum e.g.

 Tensor<int, 1> a{0, 1, 32, 2, 3, 4, -6, 7, -4}

; std::cout << e.reduce_max()() << std::endl; // Tensor<INT32, shape: [1]>([32])

The results of this Tensor must be available, to ensure that the method may execute the Tensor.

const std::array<size_t, 1> get_shape() const

Returns the number of entries in this Tensor

std::vector<T> operator*()

Retrieves the data of the current node and converts it into a vector. Executes the node if necessary (if it was not executed prior). This operation has to duplicate the complete data. Since that is a memory heavy and slow operation, it is recommended to use the index operator

operator[]

whenever possible instead. E.g.

 Tensor<int, 1> foo = Tensor<int, 1>::constant(42, 5);
 std::vector<int> foo_res = *foo;
 // foo_res = {42, 42, 42, 42, 42}

void execute()

Executes the underlying operation (and lazily the operations of the parents if needed) if it was not already executed prior (in that case the operation does nothing). If Flint was initiallized implicitly (without ever calling

flintInit

) or with

FLINT_BACKEND_BOTH

the backend is chosen automatically by heuristics and initialized if it was not prior.

void execute_cpu()

Executes the underlying operation (and lazily the operations of the parents if needed) if it was not already executed prior (in that case the operation does nothing). Uses the CPU backend and initializes it if it was not initialized.

void execute_gpu()

Tensor<T, 1> operator()()

Convenience Method that calls

execute

and returns a lightweight copy of the Tensor

  Tensor<float, 1> t = ...;
  std::cout << t() << std::endl;

Tensor<T, 1> operator-() const

Negates the elements of this Tensor. E.g.

 Tensor<float, 1> foo = {-3, 3.141592, 42.0798, -4.3};
 std::cout << (-foo)() << std::endl;
 // Tensor<FLOAT32, shape: 4>([3.000000, -3.141592,<ul><li>2.079800, 4.300000])
</li></ul>

Tensor<int, 1> sign() const

Returns a tensor

with the shape of a with

x[i] = 1

a[i] >=
 0

else

x[i] = -1

. If you need to distinguish additionally for 0 values, take a look at

equal

. E.g.

 Tensor<float, 1> foo = {-3, 3.141592, 42.0798, -4.3};
 std::cout << (foo.sign())() << std::endl;
 // Tensor<INT32, shape: 4>([-1, 1, 1, -1])

Tensor<int, 1> even() const

Returns a int tensor

with the shape of

this

with

x[i] = 1

this[i] % 2 = 0

else

x[i] = 0

. This Tensor needs to have a integer type. E.g.

 Tensor<int, 1> foo = {2, 3, 42, 7};
 std::cout << (foo.even())() << std::endl;
 // Tensor<INT32, shape: 4>([1, 0, 1, 0])

operator std::string()

Converts this Tensor to a string representation. If the Tensor was not yet executed, it won't be, instead of the data it will say "<not yet executed>".

friend std::ofstream &operator<<(std::ofstream &os, Tensor t)

Calls

serialize

on this Tensor and pipes the returned data to the stream.

friend std::ostream &operator<<(std::ostream &os, Tensor t)

Calls

std::string()

on this Tensor and pipes the returned string to the pipe.

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k>
		operator+(const Tensor &other) const

Elementwise addition of this Tensor and

other

. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> operator+(const K con) const

Elementwise addition of the constant

other

to this Tensor. If the datatype of

is stronger (stronger precedence) than the datatype of this Tensor

will be the result type, else

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k>
		operator-(const Tensor &other) const

Elementwise substraction of this Tensor and

other

. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> operator-(const K con) const

Elementwise substraction of this Tensor and the constant

other

. If the datatype of

is stronger (stronger precedence) than the datatype of this Tensor

will be the result type, else

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k>
		operator*(const Tensor &other) const

Elementwise multiplication of this Tensor and

other

. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> operator*(const K con) const

Elementwise multiplication of this Tensor and the constant

other

. If the datatype of

is stronger (stronger precedence) than the datatype of this Tensor

will be the result type, else

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k>
		operator/(const Tensor &other) const

Elementwise division of this Tensor and

other

. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> operator/(const K con) const

Elementwise division of this Tensor and the constant

other

. If the datatype of

is stronger (stronger precedence) than the datatype of this Tensor

will be the result type, else

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k> pow(const Tensor &other) const

Takes the elementwise power of this Tensor to

other

. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> pow(const K other) const

Takes the elementwise power of this Tensor to the constant

other

. If the datatype of

is stronger (stronger precedence) than the datatype of this Tensor

will be the result type, else

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k> min(const Tensor &other) const

Elementwise minimum of this Tensor and

other

. Per element either the entry of this Tensor or

other

is returned, depending on which is smaller. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> min(const K other) const

Elementwise minimum of this Tensor and the constant

other

. Per element either the entry of this Tensor or

other

is returned, depending on which is smaller. The datatype of the result is the datatype with higher precedence.

template <typename K, unsigned int k>
		Tensor<stronger_return<K>, k> max(const Tensor &other) const

Elementwise maximum of this Tensor and

other

. Per element either the entry of this Tensor or

other

is returned, depending on which is larger. The datatype of the result is the datatype with higher precedence.

template <typename K>
		Tensor<stronger_return<K>, 1> max(const K other) const

Elementwise maximum of this Tensor and the constant

other

. Per element either the entry of this Tensor or

other

is returned, depending on which is larger. The datatype of the result is the datatype with higher precedence.

Tensor<to_float<T>, 1> log()

Takes the elementwise natural logarithm of this Tensor.

Tensor<to_float<T>, 1> log2()

Takes the elementwise logarithm dualis of this Tensor.

Tensor<to_float<T>, 1> log10()

Takes the elementwise logarithm to basis 10 of this Tensor.

Tensor<to_float<T>, 1> sqrt()

Takes the elementwise square root of this Tensor.

Tensor<to_float<T>, 1> exp()

Takes the elementwise exponent of this Tensor (power of the constant

to this Tensor).

Tensor<to_float<T>, 1> sin()

Takes the elementwise sinus of this Tensor.

Tensor<to_float<T>, 1> cos()

Takes the elementwise cosinus of this Tensor.

Tensor<to_float<T>, 1> tan()

Takes the elementwise tangents of this Tensor.

Tensor<to_float<T>, 1> asin()

Takes the elementwise arcsinus of this Tensor (

sin^(-1)

Tensor<to_float<T>, 1> acos()

Takes the elementwise arccosinus of this Tensor (

cos^(-1)

Tensor<to_float<T>, 1> atan()

Takes the elementwise arctangents of this Tensor (

tan^(-1)

template <typename K> Tensor<K, 1> convert() const

Converts this Tensor (and the underlying data) to type

given in the template.

must be one of

int

long

float

double

. The data is converted, not reinterpreted.

Tensor<T, 1> abs() const

Takes the elementwise absolute value of this Tensor (negative signs are removed).

template <typename K, unsigned int k>
		Tensor<int, k> operator<(const Tensor &other) const

Compares this tensor and

other

elementwise and returns a 0,1 integer Tensor.

denotes that

this >= other

that

this <
 other

for that element.

template <typename K> Tensor<int, 1> operator<(const K other) const

Compares this tensor and the constant

other

elementwise and returns a 0,1 integer Tensor.

denotes that

this >= other

that

this < other

for that element.

template <typename K, unsigned int k>
		Tensor<int, 1> operator>(const Tensor &other) const

Compares this tensor and

other

elementwise and returns a 0,1 integer Tensor.

denotes that

this <= other

that

this >
 other

for that element.

template <typename K> Tensor<int, 1> operator>(const K other) const

Compares this tensor and the constant

other

elementwise and returns a 0,1 integer Tensor.

denotes that

this <= other

that

this > other

for that element.

template <typename K, unsigned int k>
		Tensor<int, k> equal(const Tensor &other) const

Compares this tensor and

other

elementwise and returns a 0,1 integer Tensor.

denotes that

this != other

that

this ==
 other

template <typename K> Tensor<int, 1> equal(const K other) const

Compares this tensor and the constant

other

elementwise and returns a 0,1 integer Tensor.

denotes that

this != other

that

this == other

Tensor<T, 1> slice(long start = 0, long end = TensorRange::MAX_SCOPE,
						   long step = 1) const

Slices a selection of the Tensor beginning by

start

(inclusive), ending with

end

(exclusive) by a step size

step

. The step size may be negative in which case traversal order changes, therefor

start > end

must hold (for forward traversal of course

end >
 start

). E.g.

 Tensor<int, 1> a{1, 2, 3, 4, 5, 6, 7, 8};
 std::cout << (a.slice(6, 1, -2))() << std::endl;
 // Tensor<INT32, shape: 3>([7, 5, 3])

To help with indexing there is the value

TensorRange::MAX_SCOPE

which describes a index depending on the traversal order in that dimension (i.e. the sign of step):

for forward traversel it denotes in start the shape of this Tensor
1 (which is the last element start can index) and for end the shape

of this Tensor.

for backward traversal it denotes in start 0 and in end the element before 0 (this is necessary since otherwise it would not be

possible to just inverse a dimension without eliminating values).

Tensor<T, 1> slice(TensorRange r1)

Compability version of

slice

. Calls the overloaded one dimensional slice operation with the corresponding attributes of

r1

Copied Documentation of that function:

Slices a selection of the Tensor beginning by

start

(inclusive), ending with

end

(exclusive) by a step size

step

. The step size may be negative in which case traversal order changes, therefor

start > end

must hold (for forward traversal of course

end >
 start

). E.g.

 Tensor<int, 1> a{1, 2, 3, 4, 5, 6, 7, 8};
 std::cout << (a.slice(6, 1, -2))() << std::endl;
 // Tensor<INT32, shape: 3>([7, 5, 3])

To help with indexing there is the value

TensorRange::MAX_SCOPE

which describes a index depending on the traversal order in that dimension (i.e. the sign of step):

for forward traversel it denotes in start the shape of this Tensor
1 (which is the last element start can index) and for end the shape

of this Tensor.

for backward traversal it denotes in start 0 and in end the element before 0 (this is necessary since otherwise it would not be

possible to just inverse a dimension without eliminating values).

Tensor<T, 2> expand(int ax = 2, int ax_size = 0)

Adds a new dimension at an arbitrary position to the tensor and repeats the following dimensions to match a given shape.

```
ax
```
the dimension prior to which the new dimension will be inserted (
```
0
```
means a new dimension in the front,
```
n
```
means as a new last dimension).
```
ax_size
```
the new size of that dimension (repeats the following dimensions
```
ax_size - 1
```
times).

Tensor<T, 1> dropout(double p) const

Randomly sets elements in the tensor by probability

to 0.

FGraphNode *get_graph_node() const

Returns the underlying

FGraphNode

for use with the C-Frontend. It is still memory managed by this Tensor instance, so be carefull about variable lifetimes.

void set_graph_node(FGraphNode *node)

Without freeing or changing the reference counter of the current node changes the managed node to the given parameter (is reference counter is modified neither). If the node is not

nullptr

the reference counter should have been incremented before this method, be carefull about variable lifetimes!

Tensor<T, 1> repeat(int repetitions) const

Repeats this Tensor

repetitions

times. A value of

would yield the input Tensor. E.g.

 Tensor<int, 1> a{0, 1, -1};
 std::cout << (a.repeat(2))() << std::endl;
 // Tensor<INT32, shape: 7>([0, 1, -1, 0, 1, -1, 0, 1, -1])

template <typename... args>
		Tensor<T, sizeof...(args)> reshape(args... shape)

Reshapes this Tensor to a new shape with arbitrary dimensions. It can have less dimensions, more dimensions and a completly different shape, the only assumption that has to hold is that the product of the new shape is the same as the product of the old shape (the new shape represents as many elements as the old).

template <size_t k>
		Tensor<T, k> reshape_array(std::array new_shape)

template <typename K>
		Tensor<T, 1> index(const Tensor &indices) const

Selects single elements with a index-tensor (integer tensor containing indices for the selected dimension). It indexes a dimension of the input tensor and the result has the shape of the input tensor except for the indexed dimension. It is assumed that except for the last entry the shape of

indices

is a prefix of the shape of the input tensor and the indexing will occur in the matched subsets (the last dimension of the

indices

Tensor is the one indexed in the input tensor).

 Tensor<int, 1> a3 = {0, 7, -1, 9, 4, 1, 4};
 Tensor<int, 1> i3 = {0, 0, 2, 4};
 std::cout << a3.index(i3)() << std::endl;
 // Tensor<INT32, shape: 4>([0, 0, -1, 4])

template <typename K, unsigned int k>
		Tensor<to_float<stronger_return<K>>, k>
		gradient(const Tensor &dx) const

Calculates the gradient of this Tensor to

dx

. A gradient is always a Tensor of type

double

dx

needs to have been marked with

watch

before construction of this Tensor and this Tensor must be constructed inside a gradient context, either started by

fStartGradientContext

or a

GradientContext

object.

Tensor<T, 2> sliding_window(size_t window_size,
									unsigned int step_size = 1) const

Creates "views" in an additional dimension of a fixed size windows. The window of size

window_size

is slid along the Tensor starting from the beginning and moving

step_size

entries. The windows are concatenated in a extra dimension, which becomes the first dimension of the result Tensor. E.g.

 Tensor<int, 1> a = {0, 7, -1, 9, 4, 1, 4};
 std::cout << a.sliding_window(3, 2)() << std::endl;
 // Tensor<INT32, shape: [3, 3]>(
 // [[0, 7, -1],
 //  [-1, 9, 4],
 //  [4, 1, 4]])

Tensor<T, 1> permutate(unsigned int ax) const

Randomly permutates (=swaps multiple elements with each other without creating, copying or deleting new ones) one axis of the input tensor.

void watch()

Watches this node, i.e. collects information needed to calculate the gradient with this node as a derivative

void unwatch()

Removes the gradient mark (ans subsequent memory overhead) for this node. After a call to this method no subsequent gradient calculations with this node as a derivative will be possible.

Documentation flint.hpp

Tensor<T, 1>