TensorNetwork

symbolica.community.spenso Class

TensorNetwork(expr: Any, library: Optional[TensorLibrary] = None)

A graph of tensor operations that can be simplified and executed.

Named tensor expressions are resolved through a TensorLibrary. Register concrete data before constructing and executing a network; an expression alone supplies structure, not component values.

A network retains the semantic source expression and its public tensor interface separately from the executable graph and its stored values. Value specialization and graph execution therefore do not rewrite the source expression returned by structure() or used by the semantic display methods.

Examples

from symbolica.community.spenso import (
    ExecutionMode,
    Representation,
    Tensor,
    TensorLibrary,
    TensorName,
    TensorNetwork,
)
rep = Representation.euc(2)
A = TensorName("A")
structure = A(rep, rep)
library = TensorLibrary()
library.register(
    Tensor.dense(structure, [1.0, 0.0, 0.0, 1.0])
)
network = TensorNetwork(
    A(rep("i"), rep("j")),
    library=library,
)
network.execute(library=library, mode=ExecutionMode.All)
result = network.result_tensor(library=library)
len(result)

Constructor

Create a tensor network by parsing an arithmetic expression.

Parses symbolic expressions containing tensor operations and converts them into an optimizable computational graph representation.

Returns

TensorNetwork

A new TensorNetwork representing the parsed expression

Parameters

Name	Type	Default	Description
`expr`	`Any`	`—`	The arithmetic expression or tensor structure to parse
`library`	`Optional[TensorLibrary]`	`None`	Tensor library for resolving named tensor references. Defaults to the built-in four-dimensional HEP and SU(3) library returned by `TensorLibrary.hep_lib()`.

Member details

`one`

Static method

one() -> TensorNetwork

Create a tensor network representing the scalar value 1.

Returns

TensorNetwork

A TensorNetwork containing only the scalar 1

Examples

from symbolica.community.spenso import TensorNetwork
one_net = TensorNetwork.one()
result = one_net.result_scalar()

`bracket`

Static method

bracket() -> Expression

Return the symbolic head used for structured product brackets.

`broadcast`

Static method

broadcast(str: str) -> Expression

Create a Symbolica function symbol tagged for elementwise tensor broadcasting.

Parameters

Name	Type	Default	Description
`str`	`str`	`—`	—

`zero`

Static method

zero() -> TensorNetwork

Create a tensor network representing the scalar value 0.

Returns

TensorNetwork

A TensorNetwork containing only the scalar 0

Examples

from symbolica.community.spenso import TensorNetwork
zero_net = TensorNetwork.zero()
result = zero_net.result_scalar()

`replace`

Method

replace(pattern: Expression | int | Float | int | float | str | decimal.Decimal | ComplexFloat | Float | int | float | str | decimal.Decimal | complex | tuple[Float | int | float | str | decimal.Decimal, Float | int | float | str | decimal.Decimal], rhs: Expression | int | Float | int | float | str | decimal.Decimal | ComplexFloat | Float | int | float | str | decimal.Decimal | complex | tuple[Float | int | float | str | decimal.Decimal, Float | int | float | str | decimal.Decimal] | HeldExpression | Callable[[dict[Expression, Expression]], Expression] | int | float | complex | Float | ComplexFloat | decimal.Decimal, cond: Optional[PatternRestriction | Condition] = None, non_greedy_wildcards: Optional[Sequence[Expression]] = None, level_range: Optional[tuple[int, Optional[int]]] = None, level_is_tree_depth: Optional[bool] = None, allow_new_wildcards_on_rhs: Optional[bool] = None, rhs_cache_size: Optional[int] = None, repeat: Optional[bool] = None) -> TensorNetwork

Replace patterns in stored symbolic network values.

Rewrites scalar coefficients and symbolic elements of parametric tensors in the execution store. Tensor identities, graph topology, the public interface, and the semantic source expression returned by structure() are unchanged. Rewrite a TensorExpression before constructing the network when the source tensor expression itself should change.

Returns

TensorNetwork

A new TensorNetwork with matching stored values replaced and the same semantic source structure

Parameters

Name	Type	Default	Description
`pattern`	`Expression \| int \| Float \| int \| float \| str \| decimal.Decimal \| ComplexFloat \| Float \| int \| float \| str \| decimal.Decimal \| complex \| tuple[Float \| int \| float \| str \| decimal.Decimal, Float \| int \| float \| str \| decimal.Decimal]`	`—`	The symbolic pattern to match within stored values
`rhs`	`Expression \| int \| Float \| int \| float \| str \| decimal.Decimal \| ComplexFloat \| Float \| int \| float \| str \| decimal.Decimal \| complex \| tuple[Float \| int \| float \| str \| decimal.Decimal, Float \| int \| float \| str \| decimal.Decimal] \| HeldExpression \| Callable[[dict[Expression, Expression]], Expression] \| int \| float \| complex \| Float \| ComplexFloat \| decimal.Decimal`	`—`	The replacement expression or pattern
`cond`	`Optional[PatternRestriction \| Condition]`	`None`	Additional restriction that each match must satisfy
`non_greedy_wildcards`	`Optional[Sequence[Expression]]`	`None`	List of wildcard symbols to match non-greedily
`level_range`	`Optional[tuple[int, Optional[int]]]`	`None`	Tuple specifying depth range for pattern matching
`level_is_tree_depth`	`Optional[bool]`	`None`	Whether level refers to tree depth or expression depth
`allow_new_wildcards_on_rhs`	`Optional[bool]`	`None`	Allow new wildcards in replacement pattern
`rhs_cache_size`	`Optional[int]`	`None`	Size of cache for replacement pattern compilation
`repeat`	`Optional[bool]`	`None`	Whether to repeatedly apply the replacement until no more matches

`evaluate`

Method

evaluate(constants: Mapping[Expression, float], functions: Mapping[Expression, Any]) -> TensorNetwork

Evaluate symbolic tensor values in the execution store.

Substitutes symbolic constants and functions in stored parametric tensor elements, converting them to concrete numerical tensors. Tensor identities, graph topology, the public interface, and the semantic source expression are retained.

Returns

TensorNetwork

A new TensorNetwork with stored tensor values evaluated and the same semantic source structure

Parameters

Name	Type	Default	Description
`constants`	`Mapping[Expression, float]`	`—`	Dict mapping symbolic expressions to their numerical values
`functions`	`Mapping[Expression, Any]`	`—`	Dict mapping function symbols to Python callable objects

`execute`

Method

execute(library: Optional[TensorLibrary] = None, function_library: Optional[TensorFunctionLibrary] = None, n_steps: Optional[int] = None, mode: ExecutionMode = ExecutionMode.All) -> None

Execute the tensor network to perform tensor contractions and simplifications.

Processes the computational graph by executing tensor operations such as contractions, additions, and multiplications. The execution can be controlled by mode and step limits.

Examples

from symbolica.community.spenso import TensorNetwork, ExecutionMode, TensorLibrary
network = TensorNetwork(some_expression)
network.execute()
network.execute(n_steps=5)
network.execute(mode=ExecutionMode.Scalar)
lib = TensorLibrary.hep_lib()
network.execute(library=lib)

Parameters

Name	Type	Default	Description
`library`	`Optional[TensorLibrary]`	`None`	Optional tensor library for resolving tensor operations
`function_library`	`Optional[TensorFunctionLibrary]`	`None`	Tensor function callbacks; None uses the built-in function library
`n_steps`	`Optional[int]`	`None`	Maximum number of execution steps (None for complete execution)
`mode`	`ExecutionMode`	`ExecutionMode.All`	Execution strategy. ExecutionMode.Single selects one smallest-degree rewrite per step; use n_steps to bound how many steps run.

`result_tensor`

Method

result_tensor(library: Optional[TensorLibrary] = None) -> Tensor

Extract the final tensor result from the executed network.

After network execution, retrieves the computed tensor result. The network should be executed before calling this method.

Returns

Tensor

The computed tensor result

Raises

RuntimeError: If the network execution resulted in an error

Examples

from symbolica.community.spenso import TensorNetwork, TensorLibrary
network = TensorNetwork(tensor_expression)
network.execute()
result = network.result_tensor()
lib = TensorLibrary.hep_lib()
result_with_lib = network.result_tensor(library=lib)

Parameters

Name	Type	Default	Description
`library`	`Optional[TensorLibrary]`	`None`	Optional tensor library for resolving tensor structures

`result_scalar`

Method

result_scalar() -> Expression

Extract the final scalar result from the executed network.

For networks that evaluate to scalar expressions, retrieves the computed scalar value. The network should be executed before calling this method.

Returns

Expression

The computed scalar expression

Raises

RuntimeError: If the network execution resulted in an error

Examples

from symbolica.community.spenso import TensorNetwork
network = TensorNetwork(scalar_expression)
network.execute()
scalar_result = network.result_scalar()

`str`

Method

__str__() -> str

Return a DOT representation of the executable network graph.

Generates a DOT format representation of the computational graph that can be visualized using graphviz or similar tools.

`to_dot`

Method

to_dot() -> str

Return the computational graph in Graphviz DOT format.

`format_tensor`

Method

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

Format the exact semantic structure using compact Spenso notation.

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 the semantic source structure as Typst math source.

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 the semantic source structure.

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

No description is available for this member.

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

No description is available for this member.

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.

`structure`

Method

structure() -> TensorExpression

Return the semantic source expression and its public tensor interface.

This expression records the tensor-aware structure used for composition and provenance. It is not reconstructed from the current execution store, so replace(), evaluate(), and execute() leave it unchanged. Use result_scalar() or result_tensor() to inspect the current computed value.

`index`

Method

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

Fill the unresolved external ports with indices in interface order.

Pass AUTO to leave a port unresolved. Set cook_indices=True to flatten nested symbolic index payloads before insertion.

Parameters

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

`call`

Method

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

Fill the unresolved external ports with indices in interface order.

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

Add two tensor networks element-wise.

Returns

TensorNetwork

A new TensorNetwork representing the sum

Examples

net1 = TensorNetwork(expr1)
net2 = TensorNetwork(expr2)
sum_net = net1 + net2

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	The tensor network to add (right-hand side)

`radd`

Method

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

Add two tensor networks element-wise (right-hand addition).

Parameters

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

`sub`

Method

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

Subtract one tensor network from another element-wise.

Returns

TensorNetwork

A new TensorNetwork representing the difference

Examples

net1 = TensorNetwork(expr1)
net2 = TensorNetwork(expr2)
diff_net = net1 - net2

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	The tensor network to subtract (right-hand side)

`rsub`

Method

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

Subtract one tensor network from another (right-hand subtraction).

Parameters

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

`mul`

Method

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

Multiply two tensor networks.

Returns

TensorNetwork

A new TensorNetwork representing the product

Examples

net1 = TensorNetwork(expr1)
net2 = TensorNetwork(expr2)
product_net = net1 * net2

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| Float \| ComplexFloat \| TensorExpression \| TensorNetwork \| Tensor`	`—`	The tensor network to multiply with (right-hand side)

`rmul`

Method

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

Multiply two tensor networks (right-hand multiplication).

Parameters

Name	Type	Default	Description
`rhs`	`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 an outer tensor 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 public 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 explicitly selected 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 a selected or uniquely inferred propagation channel.

Parameters

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

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