TensorEvaluator

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

TensorEvaluator

class TensorEvaluator

Optimized numerical evaluation of a tensor’s component formulas.

Create this object with Tensor.evaluator. Each input row supplies values for parameters and produces one Tensor with output_shape. Real coefficients support both real and complex evaluation; complex coefficients require evaluate_complex.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.evaluate([[2.0], [3.0]])[1][1]
9.0

Attributes

Name Description
input_size Number of values required in each evaluation row.
output_shape Logical component shape of each result tensor.
parameters Symbolic inputs in the required evaluation order.
supports_real Whether a real-valued evaluation path is available.

input_size

TensorEvaluator.input_size: builtins.int

Number of values required in each evaluation row.

Returns

  • int Length of parameters.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.input_size
1

output_shape

TensorEvaluator.output_shape: tuple[int, ...]

Logical component shape of each result tensor.

Returns

  • tuple of int Shape excluding the batch dimension.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.output_shape
(2,)

parameters

TensorEvaluator.parameters: builtins.list[Expression]

Symbolic inputs in the required evaluation order.

Returns

  • list of Expression One entry for each value in an input row.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.parameters == [x]
True

supports_real

TensorEvaluator.supports_real: builtins.bool

Whether a real-valued evaluation path is available.

Returns

  • bool False when the formulas contain complex coefficients; use evaluate_complex in that case.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.supports_real
True

Methods

Name Description
__repr__ Return a readable object description for inspection.
compile Compile and load native C++ code for repeated tensor evaluation.
evaluate Evaluate a batch of real input rows.
evaluate_complex Evaluate a batch of complex input rows.

__repr__

TensorEvaluator.__repr__() -> builtins.str

Return a readable object description for inspection.

Examples

from symbolica.community import tensor as sp
from symbolica import E, S
r = sp.Representation.euc(2)
A = sp.TensorName("docs::A")(r, r)
x = S("docs::x")
tensor = sp.Tensor.dense(A, [x, E("0"), E("0"), x + 1])
evaluator = tensor.evaluator({}, {}, [x], iterations=1, n_cores=1)
text = repr(evaluator)

compile

TensorEvaluator.compile(
    function_name: builtins.str,
    filename: builtins.str,
    library_name: builtins.str,
    inline_asm: builtins.str = 'default',
    optimization_level: builtins.int = 3,
    compiler_path: typing.Optional[builtins.str] = None,
    custom_header: typing.Optional[builtins.str] = None,
) -> CompiledTensorEvaluator

Related type: CompiledTensorEvaluator

Compile and load native C++ code for repeated tensor evaluation.

Parameters

  • function_name (str) Exported C++ function name.
  • filename (str) Path for generated complex-evaluation C++ source. When real evaluation is supported, an additional file with suffix .real.cpp is written.
  • library_name (str) Output library path. A separate .real library is generated when supported.
  • inline_asm (str, default “default”) Assembly mode: “default”, “x64”, “aarch64”, or “none”.
  • optimization_level (int, default 3) Compiler optimization level.
  • compiler_path (str, optional) C++ compiler executable; omit to use Symbolica’s default compiler.
  • custom_header (str, optional) Additional C++ header source included in the generated code.

Returns

  • CompiledTensorEvaluator Loaded native evaluator with the same input ordering and result shape.

Notes

This writes source and compiled library files to the supplied paths.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
from tempfile import TemporaryDirectory
directory = TemporaryDirectory()
compiled = evaluator.compile("eval", directory.name + "/eval.cpp", directory.name + "/eval", inline_asm="none")
compiled.input_size
1
directory.cleanup()

evaluate

TensorEvaluator.evaluate(inputs: typing.Sequence[typing.Sequence[builtins.float]]) -> builtins.list[Tensor]

Related type: Tensor

Evaluate a batch of real input rows.

Parameters

  • inputs (sequence of sequences of float) One row per evaluation, with input_size entries in parameters order.

Returns

  • list of Tensor One real component tensor per input row, each with output_shape.

Raises

  • ValueError: A row has the wrong size, or the formulas contain complex coefficients. Use evaluate_complex for those formulas.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.evaluate([[2.0]])[0][1]
4.0

evaluate_complex

TensorEvaluator.evaluate_complex(inputs: typing.Sequence[typing.Sequence[builtins.complex]]) -> builtins.list[Tensor]

Related type: Tensor

Evaluate a batch of complex input rows.

Parameters

  • inputs (sequence of sequences of complex) One row per evaluation, with input_size entries in parameters order.

Returns

  • list of Tensor One complex component tensor per input row, each with output_shape.

Raises

  • ValueError: A row has the wrong size.

Examples

from symbolica import S
from symbolica.community.tensor import Tensor, TensorName, Representation
x = S("x")
values = Tensor.dense(TensorName.vector("eval_v")(Representation.euc(2)), [x, x**2])
evaluator = values.evaluator({}, {}, [x], iterations=1, n_cores=1)
evaluator.evaluate_complex([[2.0]])[0][1]
(4+0j)