cc.redberry.core.tensor

Interface TensorBuilder

All Known Implementing Classes:

AbstractSumBuilder, ExpressionBuilder, PowerBuilder, ProductBuilder, ScalarsBackedProductBuilder, SumBuilder, SumBuilderSplitingScalars

public interface TensorBuilder

All tensors in the system are reduced to the general form. For example: if there are several numerical factors in the product they will be multiplied and only one resulting numerical factor will be in the resulting product. To maintain this reduced form of expressions, specific infrastructure for tensor creation is provided. All creations of tensors are performed using this infrastructure and explicit tensor creation is architecturally forbidden for the user. Tensor creation infrastructure consists of two functionally redundant but optimized for different usage strategies interfaces: TensorBuilder and TensorFactory. In fact TensorBuilder and TensorFactory for one particular tensor will produce exactly the same result for the same input sub-tensor sequence.

This class determines the common interface for tensor builders. Objects of this type are produced by Tensor.getBuilder() method, or can be directly created using constructors.

Main contract for the builder infrastructure could be expressed in the following code:

 Tensor tensor = ....;
 TensorBuilder builder = tensor.getBuilder();
 for(Tensor t: tensor)
     builder.put(t);
 assert TensorUtils.compare(builder.build(),tensor);

So, using a builder of any tensor you can rebuild it into the equivalent tensor.

The main goal of the builders infrastructure is reduction of all tensors in the program to some general form. So, result of tensor creation by the builder can be very different from simple sequential concatenation of tensors passed to put() method, even the type of resulting tensor could be different form the original one. Here are several examples:

Example 1

 TensorBuilder builder = new ProductBuilder(); //builder of product
 builder.put(Tensors.parse("2"));
 builder.put(Tensors.parse("3"));
 builder.put(Tensors.parse("a"));
 assert TensorUtils.equals(builder.build(),Tensors.parse("6*a"));

Example 2

 Tensor tensor = Tensors.parse("b*a");
 TensorBuilder builder = tensor.getBuilder(); //builder of product
 builder.put(Tensors.parse("2"));
 builder.put(Tensors.parse("1/2"));
 builder.put(Tensors.parse("a+q"));
 assert TensorUtils.equals(builder.build(),Tensors.parse("a+q")); //Resulting tensor class is Sum

There is a mimic infrastructure for tensor creation in the system, see TensorFactory for more information.

For general tensor creation use factory methods in Tensors class.

Since:

1.0

Author:

Dmitry Bolotin, Stanislav Poslavsky

See Also:

Tensor.getBuilder(), TensorUtils.equals(cc.redberry.core.tensor.Tensor, cc.redberry.core.tensor.Tensor), http://en.wikipedia.org/wiki/Builder_pattern

Method Summary

Methods

Modifier and Type	Method and Description
Tensor	build() Builds the tensor.
TensorBuilder	clone()
void	put(Tensor tensor) Method to sequentially add sub-tensors to the future tensor.

Method Detail

put

void put(Tensor tensor)

Method to sequentially add sub-tensors to the future tensor.

Parameters:

tensor - sub-tensor to be added

build

Tensor build()

Builds the tensor. This method should be called only once for the particular object.

Returns:

resulting tensor

clone

TensorBuilder clone()