Tensor

symbolica.community.spenso Class

Tensor()

A tensor class that can be either dense or sparse with flexible data types.

The tensor can store data as floats, complex numbers, or symbolic expressions. Tensors have an associated structure that defines their shape and index properties.

Examples

from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(4)
structure = TensorName.vector("v")(rep("mu"))
data = [1.0, 2.0, 3.0, 4.0]
tensor = Tensor.dense(structure, data)
sparse_tensor = Tensor.sparse(structure, float)

Member details

`structure`

Method

structure() -> TensorExpression

Return the exact structured expression describing this tensor's data.

`with_name`

Method

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

Return a copy with a new data identity while preserving its expression and interface.

Parameters

Name	Type	Default	Description
`name`	`TensorName \| str \| Expression \| TensorExpression`	`—`	—

`sparse`

Static method

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

Create a new sparse empty tensor with the given structure and data type.

Returns

Tensor

A new sparse tensor with all elements initially zero

Examples

import symbolica
from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(3)
structure = TensorName("T")(rep, rep)
sparse_float = Tensor.sparse(structure, float)
sparse_sym = Tensor.sparse(structure, symbolica.Expression)

Parameters

Name	Type	Default	Description
`structure`	`TensorExpression`	`—`	A named expression with unresolved, explicit, or mixed interface ports
`type_info`	`type`	`—`	The data type - either `float` or `Expression` class

`dense`

Static method

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

Create a new dense tensor with the given structure and data.

Returns

Tensor

A new dense tensor with the specified data

Examples

from symbolica import S
from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(2)
structure = TensorName("T")(rep("mu"), rep("nu"))
data = [1.0, 2.0, 3.0, 4.0]
tensor = Tensor.dense(structure, data)
x, y = S("x", "y")
sym_data = [x, y, x * y, x + y]
sym_tensor = Tensor.dense(structure, sym_data)

Parameters

Name	Type	Default	Description
`structure`	`TensorExpression`	`—`	A named expression with unresolved, explicit, or mixed interface ports
`data`	`Sequence[Expression] \| Sequence[float] \| Sequence[complex]`	`—`	Tensor values in logical row-major order: the last interface axis varies fastest, regardless of the canonical order used by internal storage. Representation-axis movement occurs only at this input boundary; later index-only storage permutations do not change the public layout.

`to_dense`

Method

to_dense() -> None

Convert this tensor to dense storage format.

Converts sparse tensors to dense format in-place. Dense tensors are unchanged. This allocates memory for all tensor elements.

Examples

from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(4)
structure = TensorName.vector("v")(rep("mu"))
tensor = Tensor.sparse(structure, float)
tensor[0] = 1.0
tensor.to_dense()

`to_sparse`

Method

to_sparse() -> None

Convert this tensor to sparse storage format.

Converts dense tensors to sparse format in-place, only storing non-zero elements. This can save memory for tensors with many zero elements.

Examples

from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(2)
structure = TensorName("T")(rep("mu"), rep("nu"))
data = [1.0, 0.0, 0.0, 2.0]
tensor = Tensor.dense(structure, data)
tensor.to_sparse()

`repr`

Method

__repr__() -> str

No description is available for this member.

`str`

Method

__str__() -> str

No description is available for this member.

`format_tensor`

Method

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

Format this concrete tensor using compact Spenso notation.

Values are read in logical interface order without transposing or densifying the stored tensor. Large results show a bounded edge preview.

Parameters

Name	Type	Default	Description
`show_dimensions`	`Optional[bool]`	`None`	—
`settings`	`Optional[DisplaySettings]`	`None`	—

`to_typst`

Method

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

Format this concrete tensor as Typst math source.

Values are read in logical interface order without transposing or densifying the stored tensor. Large results show a bounded edge preview.

Parameters

Name	Type	Default	Description
`show_dimensions`	`Optional[bool]`	`None`	—
`settings`	`Optional[DisplaySettings]`	`None`	—

`formatted`

Method

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

Build Symbolica's rich display wrapper for this concrete tensor.

Its text, HTML, and LaTeX representations all use logical interface order.

Parameters

Name	Type	Default	Description
`show_dimensions`	`Optional[bool]`	`None`	—
`settings`	`Optional[DisplaySettings]`	`None`	—
`notation_source`	`Optional[str]`	`None`	—

`to_html`

Method

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

Compile this concrete tensor to semantic HTML with the optional Typst renderer.

Parameters

Name	Type	Default	Description
`show_dimensions`	`Optional[bool]`	`None`	—
`settings`	`Optional[DisplaySettings]`	`None`	—
`notation_source`	`Optional[str]`	`None`	—

`to_svg`

Method

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

Compile this concrete tensor to SVG with the optional Typst renderer.

Parameters

Name	Type	Default	Description
`show_dimensions`	`Optional[bool]`	`None`	—
`settings`	`Optional[DisplaySettings]`	`None`	—
`notation_source`	`Optional[str]`	`None`	—

`_repr_html_`

Method

_repr_html_() -> Optional[str]

No description is available for this member.

`_repr_latex_`

Method

_repr_latex_() -> Optional[str]

No description is available for this member.

`_repr_pretty_`

Method

_repr_pretty_(pretty: Any, cycle: bool) -> None

No description is available for this member.

Parameters

Name	Type	Default	Description
`pretty`	`Any`	`—`	—
`cycle`	`bool`	`—`	—

`len`

Method

__len__() -> int

No description is available for this member.

`getitem`

Method

Overloads

Overload 1 #

__getitem__(item: slice | int | list[int]) -> Any

Return tensor data in logical interface order.

An integer is a flat logical row-major position. A list supplies one coordinate per slot in structure().interface; slices likewise traverse flat logical order. Canonical storage-axis order is never exposed through this API.

Parameters

Name	Type	Default	Description
`item`	`slice \| int \| list[int]`	`—`	—

Overload 2 #

__getitem__(item: slice) -> list[Expression | complex | float]

Get tensor elements at the specified range of indices.

Slices traverse the flat logical row-major order shown by Tensor.structure().interface; canonical storage-axis order is not exposed.

Returns

list of float, complex, or Expression

The tensor elements at the specified range

Parameters

Name	Type	Default	Description
`item`	`slice`	`—`	Slice object defining the range of indices

Overload 3 #

__getitem__(item: Sequence[int] | int) -> Expression | complex | float

Get tensor element at the specified index or indices.

Integers are flat logical row-major positions. Coordinate lists follow Tensor.structure().interface; canonical storage-axis order is not exposed.

Returns

float, complex, or Expression

The tensor element at the specified index

Parameters

Name	Type	Default	Description
`item`	`Sequence[int] \| int`	`—`	Index specification (int for flat index, list of int for coordinates)

`setitem`

Method

Overloads

Overload 1 #

__setitem__(item: Any, value: Any) -> None

Set tensor element(s) at the specified index or indices.

Examples

from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(2)
structure = TensorName("T")(rep("mu"), rep("nu"))
tensor = Tensor.sparse(structure, float)
tensor[0] = 4.0
tensor[1, 1] = 1.0

Parameters

Name	Type	Default	Description
`item`	`Any`	`—`	Logical index specification (int for flat row-major position, list of int for coordinates following `structure().interface`)
`value`	`Any`	`—`	The value to set. Its coefficient kind must match the tensor: `float` for real storage, `complex` for complex storage, or `Expression` for parametric storage.

Overload 2 #

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

Set tensor element at the specified index.

Integers are flat logical row-major positions. Coordinate lists follow Tensor.structure().interface; canonical storage-axis order is not exposed.

Examples

from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(2)
structure = TensorName("T")(rep("mu"), rep("nu"))
tensor = Tensor.sparse(structure, float)
tensor[0] = 1.0
tensor[1, 1] = 2.0

Parameters

Name	Type	Default	Description
`item`	`int \| Sequence[int]`	`—`	Index specification (int for flat index, list of int for coordinates)
`value`	`Expression \| complex \| float`	`—`	The value to set. Use float for real storage, complex for complex storage, or Expression for parametric storage.

`evaluator`

Method

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

Create an optimized evaluator for symbolic tensor expressions.

Compiles the symbolic expressions in this tensor into an optimized evaluation tree that can efficiently compute numerical values for different parameter inputs.

Returns

TensorEvaluator

An optimized evaluator for efficient numerical evaluation

Examples

from symbolica import S
from symbolica.community.spenso import Tensor, TensorName, Representation
x, y = S("x", "y")
rep = Representation.euc(2)
structure = TensorName.vector("v")(rep("mu"))
tensor = Tensor.dense(structure, [x * y, x + y])
evaluator = tensor.evaluator(constants={}, funs={}, params=[x, y], iterations=50)
results = evaluator.evaluate_complex([[1.0, 2.0], [3.0, 4.0]])

Parameters

Name	Type	Default	Description
`constants`	`Mapping[Expression, Expression]`	`—`	Dict mapping symbolic expressions to their constant numerical values
`funs`	`Mapping[tuple[Expression, str, Sequence[Expression]], Expression]`	`—`	Dict mapping function signatures to their symbolic definitions
`params`	`Sequence[Expression]`	`—`	List of symbolic parameters that will be varied during evaluation
`iterations`	`int`	`100`	Number of optimization iterations for Horner scheme (default: 100)
`n_cores`	`int`	`4`	Number of CPU cores to use for optimization (default: 4)
`verbose`	`bool`	`False`	Whether to print optimization progress (default: False)

`scalar`

Method

scalar() -> Expression

Extract the scalar value from a rank-0 (scalar) tensor.

Returns

Expression

The scalar expression contained in this tensor

Raises

RuntimeError: If the tensor is not a scalar

Examples

from symbolica.community.spenso import Tensor, TensorName, Representation
rep = Representation.euc(2)
p = TensorName.vector("p")
structure = (p(rep("mu")) * p(rep("mu"))).with_name(TensorName("p2"))
scalar_tensor = Tensor.dense(structure, [1.0])
value = scalar_tensor.scalar()

`index`

Method

index(*indices: Any, cook_indices: bool = False) -> TensorNetwork

Reference this tensor with new abstract indices and return a lazy network.

Parameters

Name	Type	Default	Description
`indices`	`Any`	`—`	—
`cook_indices`	`bool`	`False`	—

`call`

Method

__call__(*indices: Any, cook_indices: bool = False) -> TensorNetwork

Reference this tensor with new abstract indices and return a lazy network.

Parameters

Name	Type	Default	Description
`indices`	`Any`	`—`	—
`cook_indices`	`bool`	`False`	—

`neg`

Method

__neg__() -> TensorNetwork

No description is available for this member.

`add`

Method

__add__(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`radd`

Method

__radd__(lhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`lhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`sub`

Method

__sub__(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`rsub`

Method

__rsub__(lhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`lhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`mul`

Method

__mul__(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`rmul`

Method

__rmul__(lhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`lhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`truediv`

Method

__truediv__(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`rtruediv`

Method

__rtruediv__(lhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

No description is available for this member.

Parameters

Name	Type	Default	Description
`lhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`outer`

Method

outer(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

Form a lazy outer product without contracting compatible ports.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`contract`

Method

contract(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor, *, left: int, right: int) -> TensorNetwork

Contract one selected pair of ordered interface positions.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—
`left`	`int`	`—`	—
`right`	`int`	`—`	—

`compose`

Method

compose(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor, *, left: tuple[int, int], right: tuple[int, int]) -> TensorNetwork

Compose two selected (input, output) matrix channels.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—
`left`	`tuple[int, int]`	`—`	—
`right`	`tuple[int, int]`	`—`	—

`dot`

Method

dot(rhs: Expression | int | Float | ComplexFloat | TensorExpression | TensorNetwork | Tensor) -> TensorNetwork

Contract two rank-one operands into the canonical dot form.

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	—

`trace`

Method

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

Close channel, or the unique matrix channel when it is omitted.

Parameters

Name	Type	Default	Description
`channel`	`Optional[tuple[int, int]]`	`None`	—

`iter`

Method

__iter__() -> Iterator[Any]

Iterator

View generated signature source: docs/api/python/spynso3.pyi:491