Tensor

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

Tensor

class Tensor

Tensor components together with their symbolic identity and ordered axes.

Use dense(), sparse(), or from_numpy() to construct one. Components can be real floats, complex floats, or Symbolica expressions. Square brackets access components; calling the tensor assigns abstract index labels and returns a lazy TensorNetwork. Arithmetic also builds networks, retaining component data.

The default notebook view is an interactive component explorer with a matrix toggle. to_typst() provides static mathematical source.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor[1, 0]
3.0

Attributes

Name Description
axes External axes in the current component and port-position order.
dtype Python type used for the stored components.
is_scalar Whether the tensor has no external axes.
rank Number of external tensor axes.
shape Dimensions in logical axis order.
storage How components are stored.
structure Canonical external signature of the whole tensor.

axes

Tensor.axes: tuple[Slot | Representation, ...]

External axes in the current component and port-position order.

Returns

  • tuple of Slot or Representation Indexed or unresolved axes, respectively. Component coordinates and methods taking axis positions use this order. It follows construction and explicit permute_axes() calls; structure.axes instead gives the canonical signature.

Examples

from symbolica.community.tensor import Representation, TensorName
r = Representation.euc(3)
A = TensorName("A")(r("j"), r("i"))
A.axes == (r("j"), r("i"))
True
A.permute_axes([1, 0]).axes == A.axes[::-1]
True

dtype

Tensor.dtype: type[float] | type[complex] | type[Expression]

Python type used for the stored components.

Returns

  • type One of float, complex, or Expression.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.dtype is float
True

is_scalar

Tensor.is_scalar: builtins.bool

Whether the tensor has no external axes.

Returns

  • bool True exactly when rank is zero.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.is_scalar
False

rank

Tensor.rank: builtins.int

Number of external tensor axes.

Returns

  • int Zero for a scalar.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.rank
2

shape

Tensor.shape: tuple[int, ...]

Dimensions in logical axis order.

Returns

  • tuple of int Axis sizes in the order of axes, the current component view.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.shape
(2, 2)

storage

Tensor.storage: typing.Literal['dense', 'sparse']

How components are stored.

Returns

  • str “dense” for all entries, or “sparse” for populated entries.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.storage
'dense'

structure

Tensor.structure: TensorStructure

Canonical external signature of the whole tensor.

Returns

  • TensorStructure Free axes in canonical order, independent of names and component layout.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.structure.rank
2

Methods

Name Description
__add__ Add tensors with compatible external interfaces.
__call__ Assign labels to the unresolved external axes.
__copy__ Implement copy.copy using an independent Tensor copy.
__getitem__ Read components in logical row-major order.
__iter__ Iterate over all components in logical row-major order.
__len__ Count all components in the tensor shape.
__mul__ Multiply tensors, contracting unambiguous compatible axes.
__neg__ Negate every tensor component.
__radd__ Implement reflected addition.
__repr__ Return a readable object description for inspection.
__rmul__ Implement reflected multiplication.
__rsub__ Implement reflected subtraction.
__rtruediv__ Implement reflected division.
__setitem__ Change one stored component in place.
__str__ Return a readable text representation.
__sub__ Subtract tensors with compatible external interfaces.
__truediv__ Divide tensor components by a scalar expression.
_repr_html_
_repr_latex_
_repr_pretty_
compose Multiply two tensors along explicitly selected matrix channels.
contract_ports Contract one chosen pair of axes between two tensors.
copy Copy this tensor’s components and metadata.
dense Store every component of a named tensor.
dot Contract two rank-one tensors using their representation pairing.
evaluator Prepare repeated numerical evaluation of symbolic component formulas.
expression Return the symbolic descriptor for these components.
format_tensor Produce compact plain-text tensor notation.
formatted Create a rich display value for a notebook.
from_numpy Copy a numerical array into a named tensor.
index Assign labels to the unresolved external axes.
map_components Apply a scalar function to component values.
outer Form an outer product without implicit contractions between the operands.
permute_axes Reorder the external axes in logical component order.
reindex Assign labels to all external axes.
rename_indices Rename selected external labels without changing the tensor rank.
scalar Extract the only component of a rank-zero tensor.
sparse Create an initially zero tensor using sparse component storage.
to_dense Copy the components into dense storage.
to_html Render the tensor as an HTML fragment.
to_numpy Copy numerical components into a NumPy array.
to_sparse Copy the components into sparse storage.
to_svg Render static mathematical tensor notation to SVG.
to_typst Produce static Typst math source.
trace Close a pair of matrix axes on this tensor.
with_name Assign a data identity without rewriting the symbolic computation.

__add__

Tensor.__add__(rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Add tensors with compatible external interfaces.

Parameters

  • rhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

Scalar zero acts as the additive identity. Other scalars can be added only to rank-zero tensors.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = tensor + tensor

__call__

Tensor.__call__(
    *indices: _IndexInput,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> TensorNetwork

Related type: TensorNetwork

Assign labels to the unresolved external axes.

Parameters

  • *indices (int, str, Expression, Slot, or AUTO) One label per unresolved axis, in logical order. AUTO leaves the corresponding axis unchanged. A Slot must have the matching representation. Repeated compatible labels cause contraction.
  • intern ({“indices”, “flattened”} or None, optional) Encode compound index labels before checking the tensor structure. “indices” retains reversible payloads; “flattened” creates readable names. Both preserve index tags and leave scalar arguments and tensor heads intact. None leaves labels unchanged and requires ordinary atomic index labels.

Returns

  • TensorNetwork An indexed network retaining the component data; the original is unchanged.

Notes

Equivalent to index(*indices).

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
indexed = tensor("i", "j")
indexed.rank
2

__copy__

Tensor.__copy__() -> Tensor

Implement copy.copy using an independent Tensor copy.

Returns

  • Tensor Copy of the component data and metadata.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
import copy
copied = copy.copy(tensor)

__getitem__

Tensor.__getitem__(item: builtins.slice) -> builtins.list[Expression | builtins.complex | float]
Tensor.__getitem__(item: typing.Sequence[builtins.int] | builtins.int) -> Expression | builtins.complex | float
Tensor.__getitem__(item: tuple[int | slice, ...]) -> _Components

Related type: Expression

Read components in logical row-major order.

Parameters

  • item (int, slice, or tuple of int or slice) An integer is a flat position. A tuple gives one selector per axis. A flat slice returns a list; coordinate slices return nested lists. Negative indices count from the end.

Returns

  • Expression, float, complex, or list A scalar component, or lists for the sliced axes.

Notes

Coordinates follow axes, the current component view; structure.axes is a canonical signature.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor[:, 1]
[2.0, 4.0]
tensor[-1]
4.0

__iter__

Tensor.__iter__() -> typing.Iterator[Expression | float | complex]

Related type: Expression

Iterate over all components in logical row-major order.

Returns

  • iterator of Expression, float, or complex Includes implicit zeros from sparse storage.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
list(tensor)
[1.0, 2.0, 3.0, 4.0]

__len__

Tensor.__len__() -> builtins.int

Count all components in the tensor shape.

Returns

  • int Product of the axis dimensions, including implicit zeros.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
len(tensor)
4

__mul__

Tensor.__mul__(rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Multiply tensors, contracting unambiguous compatible axes.

Parameters

  • rhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

Matching explicit labels contract. Compatible unresolved axes are paired only when the choice is unambiguous. Use outer(), contract(), or compose() to make the intended pairing explicit.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = tensor * 2

__neg__

Tensor.__neg__() -> TensorNetwork

Related type: TensorNetwork

Negate every tensor component.

Returns

  • TensorNetwork Negated symbolic algebra retaining component data lazily.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
negated = -tensor

__radd__

Tensor.__radd__(lhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Implement reflected addition.

Parameters

  • lhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

Scalar zero acts as the additive identity. Other scalars can be added only to rank-zero tensors.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = tensor + tensor

__repr__

Tensor.__repr__() -> builtins.str

Return a readable object description for inspection.

Examples

from symbolica.community import tensor as sp
r = sp.Representation.euc(2)
A = sp.TensorName("docs::A")(r, r)
tensor = sp.Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
text = repr(tensor)

__rmul__

Tensor.__rmul__(lhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Implement reflected multiplication.

Parameters

  • lhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

Matching explicit labels contract. Compatible unresolved axes are paired only when the choice is unambiguous. Use outer(), contract(), or compose() to make the intended pairing explicit.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = 2 * tensor

__rsub__

Tensor.__rsub__(lhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Implement reflected subtraction.

Parameters

  • lhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

Subtraction requires matching tensor axes; a nonzero scalar cannot be subtracted from a tensor with external axes.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = tensor - tensor

__rtruediv__

Tensor.__rtruediv__(lhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Implement reflected division.

Parameters

  • lhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

The denominator must be scalar. For scalar divided by tensor, the tensor must also have rank zero.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = 2 / TensorExpression(3).to_tensor()

__setitem__

Tensor.__setitem__(
    item: builtins.int | typing.Sequence[builtins.int],
    value: Expression | int | builtins.complex | float,
) -> None

Related type: Expression

Change one stored component in place.

Parameters

  • item (int or sequence of int) Flat logical row-major position or one coordinate per logical axis. Negative indices count from the end.
  • value (float, complex, or Expression) Replacement matching the tensor’s component type: float for real storage, complex for complex storage, or Expression for symbolic storage.

Returns

  • None The tensor is modified in place.

Notes

Coordinates follow axes, the current component view; structure.axes is a canonical signature.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor[1, 0] = 7.0
tensor[1, 0]
7.0

__str__

Tensor.__str__() -> builtins.str

Return a readable text representation.

Examples

from symbolica.community import tensor as sp
r = sp.Representation.euc(2)
A = sp.TensorName("docs::A")(r, r)
tensor = sp.Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
text = str(tensor)

__sub__

Tensor.__sub__(rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Subtract tensors with compatible external interfaces.

Parameters

  • rhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

Subtraction requires matching tensor axes; a nonzero scalar cannot be subtracted from a tensor with external axes.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = tensor - tensor

__truediv__

Tensor.__truediv__(rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Divide tensor components by a scalar expression.

Parameters

  • rhs (scalar expression, TensorExpression, Tensor, or TensorNetwork) Other operand. Component data are retained in a lazy network.

Returns

  • TensorNetwork New lazy calculation; operands are unchanged.

Notes

The denominator must be scalar. For scalar divided by tensor, the tensor must also have rank zero.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
result = tensor / 2

_repr_html_

Tensor._repr_html_() -> typing.Optional[builtins.str]

_repr_latex_

Tensor._repr_latex_() -> typing.Optional[builtins.str]

_repr_pretty_

Tensor._repr_pretty_(pretty: typing.Any, cycle: builtins.bool) -> None

compose

Tensor.compose(
    rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork],
    *,
    left: tuple[builtins.int, builtins.int],
    right: tuple[builtins.int, builtins.int],
) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Multiply two tensors along explicitly selected matrix channels.

Parameters

  • rhs (TensorExpression, Tensor, or TensorNetwork) Next factor in the ordered matrix product.
  • left, right (tuple of int and int) (input_axis, output_axis) in this tensor and rhs, respectively. The left output contracts with the right input. Other axes are retained as spectator axes.

Returns

  • TensorNetwork A lazy ordered matrix product retaining component data.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
product = tensor.compose(tensor, left=(0, 1), right=(0, 1))
product.rank
2

contract_ports

Tensor.contract_ports(
    rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork],
    *,
    left: builtins.int,
    right: builtins.int,
) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Contract one chosen pair of axes between two tensors.

Parameters

  • rhs (TensorExpression, Tensor, or TensorNetwork) Tensor to contract with this tensor.
  • left, right (int) Zero-based axis positions in this tensor and rhs, respectively. The representations must be compatible under contraction.

Returns

  • TensorNetwork A lazy contraction retaining component data.

Notes

Other axes remain external. Axis numbers refer to axes.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
contracted = tensor.contract_ports(tensor, left=1, right=0)
contracted.rank
2

copy

Tensor.copy() -> Tensor

Copy this tensor’s components and metadata.

Returns

  • Tensor An independent copy. Changes to it do not alter the original.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
copied = tensor.copy()
copied.shape == tensor.shape
True

dense

Tensor.dense(
    structure: TensorExpression,
    data: typing.Sequence[Expression | int | builtins.complex | float],
) -> Tensor

Related types: TensorExpression, Expression

Store every component of a named tensor.

Parameters

  • structure (TensorExpression) Named descriptor with concrete dimensions and the desired logical axis order. Use with_name() to give a composite expression a name.
  • data (sequence of int, float, complex, or Expression) Flat component data in logical row-major order. The length must equal the product of the dimensions. An explicit Expression selects symbolic storage for the sequence, preserving exact rational and algebraic values. Integer-only input is exact too. Float or complex sequences without Expressions retain numerical storage.

Returns

  • Tensor A dense component tensor; the input descriptor remains symbolic.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.shape
(2, 2)

dot

Tensor.dot(rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Contract two rank-one tensors using their representation pairing.

Parameters

  • rhs (TensorExpression, Tensor, or TensorNetwork) Rank-one tensor in a compatible space.

Returns

  • TensorNetwork A lazy scalar contraction, including the metric signs of the space.

Examples

from symbolica.community.tensor import TensorName, Tensor, TensorNetwork, Representation
vector = Tensor.dense(TensorName.vector("dot_v")(Representation.euc(2)), [1.0, 2.0])
vector.dot(vector).to_tensor().scalar() == 5
True

evaluator

Tensor.evaluator(
    constants: typing.Mapping[Expression, Expression],
    funs: typing.Mapping[tuple[Expression, builtins.str, typing.Sequence[Expression]], Expression],
    params: typing.Sequence[Expression],
    iterations: builtins.int = 100,
    n_cores: builtins.int = 4,
    verbose: builtins.bool = False,
) -> TensorEvaluator

Related types: Expression, TensorEvaluator

Prepare repeated numerical evaluation of symbolic component formulas.

Parameters

  • constants (mapping of Expression to Expression) Fixed values that are exact rational real or complex numbers. Use parameters for values that cannot be represented this way.
  • funs (mapping) Function definitions keyed by (function_symbol, name, argument_symbols), with Expression bodies. The name field is accepted but not used.
  • params (sequence of Expression) Inputs in the exact order expected by every evaluation row.
  • iterations (int, default 100) Horner-optimization iterations.
  • n_cores (int, default 4) Number of cores for expression optimization.
  • verbose (bool, default False) Print optimization progress.

Returns

  • TensorEvaluator Optimized batch evaluator retaining this tensor’s shape and identity.

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

expression

Tensor.expression() -> TensorExpression

Related type: TensorExpression

Return the symbolic descriptor for these components.

Returns

  • TensorExpression A symbolic tensor with the same external axes.

Notes

The descriptor identifies the data but does not embed its components. Register the tensor in a TensorLibrary to evaluate that symbolic reference.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.expression().rank
2

format_tensor

Tensor.format_tensor(
    show_dimensions: typing.Optional[builtins.bool] = None,
    *,
    settings: typing.Optional[DisplaySettings] = None,
) -> builtins.str

Related type: DisplaySettings

Produce compact plain-text tensor notation.

Parameters

  • show_dimensions (bool, optional) Override settings.show_dimensions for this call. None retains the selected settings, whose default omits dimensions.
  • settings (DisplaySettings, optional) Tensor notation and display choices. Defaults to DisplaySettings().

Returns

  • str Readable tensor text, suitable for logs or terminal output.

Notes

Only ports layout and default spacing are supported in this source format. Use to_html() or to_svg() for other layouts and custom gaps.

Components follow the current view’s logical interface order (the order of axes), independently of the canonical structure signature. Large static displays show a bounded preview rather than every component.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
output = tensor.format_tensor()

formatted

Tensor.formatted(
    show_dimensions: typing.Optional[builtins.bool] = None,
    *,
    settings: typing.Optional[DisplaySettings] = None,
    notation_source: typing.Optional[builtins.str] = None,
) -> FormattedOutput

Related types: DisplaySettings, FormattedOutput

Create a rich display value for a notebook.

Parameters

  • show_dimensions (bool, optional) Override settings.show_dimensions for this call. None retains the selected settings, whose default omits dimensions.
  • settings (DisplaySettings, optional) Tensor notation and display choices. Defaults to DisplaySettings().
  • notation_source (str, optional) Custom Typst notation source used by the rich renderer. This is Typst code, not a filename; omit it for the supplied tensor notation.

Returns

  • FormattedOutput Symbolica display wrapper with text and available rich representations.

Notes

Components follow logical axis order. Large static displays show a bounded preview rather than every component.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
output = tensor.formatted()

from_numpy

Tensor.from_numpy(structure: TensorExpression, array: numpy.typing.ArrayLike) -> Tensor

Related type: TensorExpression

Copy a numerical array into a named tensor.

Parameters

  • structure (TensorExpression) Named descriptor with concrete dimensions matching the array shape.
  • array (numpy.typing.ArrayLike) Real or complex array-like data. Axes follow the descriptor’s current axes.

Returns

  • Tensor Dense tensor with float or complex components.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.from_numpy(A, [[1.0, 2.0], [3.0, 4.0]])
tensor[1, 0]
3.0

index

Tensor.index(
    *indices: _IndexInput,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> TensorNetwork

Related type: TensorNetwork

Assign labels to the unresolved external axes.

Parameters

  • *indices (int, str, Expression, Slot, or AUTO) One label per unresolved axis, in logical order. AUTO leaves the corresponding axis unchanged. A Slot must have the matching representation. Repeated compatible labels cause contraction.
  • intern ({“indices”, “flattened”} or None, optional) Encode compound index labels before checking the tensor structure. “indices” retains reversible payloads; “flattened” creates readable names. Both preserve index tags and leave scalar arguments and tensor heads intact. None leaves labels unchanged and requires ordinary atomic index labels.

Returns

  • TensorNetwork An indexed network retaining the component data; the original is unchanged.

Notes

Existing explicit labels are left in place. Use reindex to replace them.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
indexed = tensor.index("i", "j")
indexed.rank
2

map_components

Tensor.map_components(
    callback: typing.Callable[[Expression | float | complex], Expression | float | complex],
    *,
    dtype: type[float] | type[complex] | type[Expression] | None = None,
) -> Tensor

Related type: Expression

Apply a scalar function to component values.

Parameters

  • callback (callable) Function receiving one component and returning its replacement. The traversal order is unspecified.
  • dtype (type, optional) Output component type: float, complex, or Expression. Defaults to the current type; callback results must convert to the selected type.

Returns

  • Tensor An independent tensor with the same axes and mapped components.

Notes

Sparse storage remains sparse when the implicit zero maps to zero. If it maps to a nonzero value, the result becomes dense. The implicit zero is mapped once; avoid relying on callback invocation counts.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.map_components(lambda value: value * 2)[1, 0]
6.0

outer

Tensor.outer(rhs: _ScalarInput | TensorExpression | TensorNetwork | Tensor | FactorProjector[TensorExpression] | FactorProjector[TensorNetwork]) -> TensorNetwork

Related types: TensorExpression, TensorNetwork, FactorProjector

Form an outer product without implicit contractions between the operands.

Parameters

  • rhs (TensorExpression, Tensor, or TensorNetwork) Tensor whose axes follow this tensor’s axes.

Returns

  • TensorNetwork A lazy outer product retaining the operands’ component data.

Notes

Use this when compatible unresolved axes should remain independent. Choose explicit distinct labels if you need to refer to them separately.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
product = tensor.outer(tensor)
product.rank
4

permute_axes

Tensor.permute_axes(axes: typing.Sequence[builtins.int]) -> Tensor

Reorder the external axes in logical component order.

Parameters

  • axes (sequence of int) Each current axis position exactly once, in the desired new order. For a matrix, [1, 0] exchanges the two axes.

Returns

  • Tensor A new tensor view with the reordered interface and correspondingly reordered component access.

Notes

This permutes axes; it does not conjugate component values.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
transposed = tensor.permute_axes([1, 0])
transposed.shape
(2, 2)

reindex

Tensor.reindex(
    *indices: _IndexInput,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> TensorNetwork

Related type: TensorNetwork

Assign labels to all external axes.

Parameters

  • *indices (int, str, Expression, Slot, or AUTO) One label per external axis, in logical order. AUTO leaves the corresponding axis unchanged. A Slot must have the matching representation. Repeated compatible labels cause contraction.
  • intern ({“indices”, “flattened”} or None, optional) Encode compound index labels before checking the tensor structure. “indices” retains reversible payloads; “flattened” creates readable names. Both preserve index tags and leave scalar arguments and tensor heads intact. None leaves labels unchanged and requires ordinary atomic index labels.

Returns

  • TensorNetwork An indexed network retaining the component data; the original is unchanged.

Notes

Existing labels are replaced as well as unresolved axes.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
indexed = tensor.reindex("i", "j")
indexed.rank
2

rename_indices

Tensor.rename_indices(
    mapping: dict[int | str | Expression | Slot, _IndexInput],
    *,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> Tensor

Related types: Expression, Slot

Rename selected external labels without changing the tensor rank.

Parameters

  • mapping (dict) Old label to new label. A Slot key also restricts the representation. Keys must identify existing external axes. Each axis may be renamed once; renaming must preserve the external interface.
  • intern ({“indices”, “flattened”} or None, optional) Encode compound index labels before checking the tensor structure. “indices” retains reversible payloads; “flattened” creates readable names. Both preserve index tags and leave scalar arguments and tensor heads intact. None leaves labels unchanged and requires ordinary atomic index labels.

Returns

  • Tensor A new value with renamed axes; the original is unchanged.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
indexed = Tensor.dense(A("i", "j"), [1.0, 2.0, 3.0, 4.0])
indexed.rename_indices({"i": "k"}).rank
2

scalar

Tensor.scalar() -> Expression

Related type: Expression

Extract the only component of a rank-zero tensor.

Examples

from symbolica.community import tensor as sp
scalar = sp.Tensor.dense(sp.TensorName("docs::scalar")(), [2.0])
value = scalar.scalar()

Returns

  • Expression Scalar value converted to a Symbolica expression, including numeric data.

Raises

  • RuntimeError: The tensor has external axes.

Examples

from symbolica.community.tensor import TensorExpression
TensorExpression(3).to_tensor().scalar() == 3
True

sparse

Tensor.sparse(structure: TensorExpression, type_info: type) -> Tensor

Related type: TensorExpression

Create an initially zero tensor using sparse component storage.

Parameters

  • structure (TensorExpression) Named descriptor with concrete dimensions in logical axis order.
  • type_info (type) Component type: float or Expression. Expression storage preserves exact symbolic values and accepts integer assignments without rounding. Floating-point storage requires numerical assignments.

Returns

  • Tensor A zero tensor storing only explicitly populated entries.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.sparse(A, float)
tensor[1, 0] = 3.0
tensor[0, 0]
0.0

to_dense

Tensor.to_dense() -> Tensor

Copy the components into dense storage.

Returns

  • Tensor Independent dense tensor with the same values and logical axes.

Notes

Dense storage allocates space for every component.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.to_dense().storage
'dense'

to_html

Tensor.to_html(
    show_dimensions: typing.Optional[builtins.bool] = None,
    *,
    settings: typing.Optional[DisplaySettings] = None,
    notation_source: typing.Optional[builtins.str] = None,
) -> builtins.str

Related type: DisplaySettings

Render the tensor as an HTML fragment.

Parameters

  • show_dimensions (bool, optional) Override settings.show_dimensions for this call. None retains the selected settings, whose default omits dimensions.
  • settings (DisplaySettings, optional) Tensor notation and display choices. Defaults to DisplaySettings().
  • notation_source (str, optional) Custom Typst notation source used by the rich renderer. This is Typst code, not a filename; omit it for the supplied tensor notation.

Returns

  • str Self-contained output fragment for an HTML-capable notebook or page.

Notes

Mathematical rendering uses the embedded Typst compiler. The returned string is not automatically displayed; pass it to the notebook’s HTML or SVG display facility.

Components follow logical axis order. Large static displays show a bounded preview rather than every component.

The default is a responsive component explorer with a Memory grid / Matrix toggle. Dark mode follows the surrounding page. The color scale measures stored component payload bytes, not total process memory. Use DisplaySettings(tensor_view=“matrix”) for static mathematical HTML.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
output = tensor.to_html()

to_numpy

Tensor.to_numpy() -> numpy.typing.NDArray[numpy.float64] | numpy.typing.NDArray[numpy.complex128]

Copy numerical components into a NumPy array.

Returns

  • numpy.ndarray Array with the tensor’s logical shape and dtype float64 or complex128.

Raises

  • TypeError: The tensor stores symbolic Expressions. Evaluate them first.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.to_numpy().tolist()
[[1.0, 2.0], [3.0, 4.0]]

to_sparse

Tensor.to_sparse() -> Tensor

Copy the components into sparse storage.

Returns

  • Tensor Independent sparse tensor with the same values and logical axes.

Notes

Sparse storage retains nonzero entries and represents other entries by zero.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.to_sparse().storage
'sparse'

to_svg

Tensor.to_svg(
    show_dimensions: typing.Optional[builtins.bool] = None,
    *,
    settings: typing.Optional[DisplaySettings] = None,
    notation_source: typing.Optional[builtins.str] = None,
) -> builtins.str

Related type: DisplaySettings

Render static mathematical tensor notation to SVG.

Parameters

  • show_dimensions (bool, optional) Override settings.show_dimensions for this call. None retains the selected settings, whose default omits dimensions.
  • settings (DisplaySettings, optional) Tensor notation and display choices. Defaults to DisplaySettings().
  • notation_source (str, optional) Custom Typst notation source used by the rich renderer. This is Typst code, not a filename; omit it for the supplied tensor notation.

Returns

  • str SVG markup suitable for embedding or saving to a file.

Notes

Mathematical rendering uses the embedded Typst compiler. The returned string is not automatically displayed; pass it to the notebook’s HTML or SVG display facility.

Components follow logical axis order. Large static displays show a bounded preview rather than every component.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
output = tensor.to_svg()

to_typst

Tensor.to_typst(
    show_dimensions: typing.Optional[builtins.bool] = None,
    *,
    settings: typing.Optional[DisplaySettings] = None,
) -> builtins.str

Related type: DisplaySettings

Produce static Typst math source.

Parameters

  • show_dimensions (bool, optional) Override settings.show_dimensions for this call. None retains the selected settings, whose default omits dimensions.
  • settings (DisplaySettings, optional) Tensor notation and display choices. Defaults to DisplaySettings().

Returns

  • str Typst source without an enclosing document; no compilation is performed.

Notes

Only ports layout and default spacing are supported in this source format. Use to_html() or to_svg() for other layouts and custom gaps.

Components follow the current view’s logical interface order (the order of axes), independently of the canonical structure signature. Large static displays show a bounded preview rather than every component.

Static Typst output remains available independently of the HTML explorer.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
output = tensor.to_typst()

trace

Tensor.trace(*, channel: typing.Optional[tuple[builtins.int, builtins.int]] = None) -> TensorNetwork

Related type: TensorNetwork

Close a pair of matrix axes on this tensor.

Parameters

  • channel (tuple of int and int, optional) (input_axis, output_axis) to contract. If omitted, the matrix channel must be uniquely determined by the representations. Specify it when more than one pairing is possible.

Returns

  • TensorNetwork The traced tensor; spectator axes remain external.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
tensor.trace(channel=(0, 1)).is_scalar
True

with_name

Tensor.with_name(name: TensorName | builtins.str | Expression | TensorExpression) -> Tensor

Related types: TensorName, Expression, TensorExpression

Assign a data identity without rewriting the symbolic computation.

Parameters

  • name (TensorName, str, Expression, or TensorExpression) New tensor name. A rank-zero atomic TensorExpression may also supply scalar key arguments, for example TensorName(“B”)(7).

Returns

  • Tensor A new value with the requested identity and the same axes and components.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import Tensor
tensor = Tensor.dense(A, [1.0, 2.0, 3.0, 4.0])
named = tensor.with_name("named_matrix")
named.rank
2