TensorNetwork

symbolica.community.spenso Class

TensorNetwork(expr: Expression | int | str | float | complex | TensorIndices | Expression, 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.

Examples

from symbolica.community.spenso import (
    ExecutionMode,
    LibraryTensor,
    Representation,
    TensorLibrary,
    TensorName,
    TensorNetwork,
    TensorStructure,
)
rep = Representation.euc(2)
A = TensorName("A")
structure = TensorStructure(rep, rep, name=A)
library = TensorLibrary()
library.register(
    LibraryTensor.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`	`Expression \| int \| str \| float \| complex \| TensorIndices \| Expression`	`—`	The arithmetic expression or tensor structure to parse
`library`	`Optional[TensorLibrary]`	`None`	Optional tensor library for resolving named tensor references

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

No description is available for this member.

`broadcast`

Static method

broadcast(str: str) -> Expression

No description is available for this member.

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 | str | float | complex, rhs: Expression | int | str | float | complex | HeldExpression | Callable[[dict[Expression, Expression]], Expression] | int | float | complex | 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 the tensor network using symbolic pattern matching.

Applies pattern-based transformations to the network structure, allowing for symbolic simplifications, substitutions, and algebraic manipulations.

Returns

TensorNetwork

A new TensorNetwork with the replacements applied

Parameters

Name	Type	Default	Description
`pattern`	`Expression \| int \| str \| float \| complex`	`—`	The symbolic pattern to match against
`rhs`	`Expression \| int \| str \| float \| complex \| HeldExpression \| Callable[[dict[Expression, Expression]], Expression] \| int \| float \| complex \| decimal.Decimal`	`—`	The replacement expression or pattern
`_cond`	`Optional[PatternRestriction \| Condition]`	`None`	—
`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 expressions in the network with numerical values.

Substitutes symbolic constants and functions with numerical values, converting symbolic parts of the network to concrete numerical tensors.

Returns

TensorNetwork

A new TensorNetwork with symbolic expressions evaluated

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: None = 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`	`None`	`None`	Reserved for an internally supplied 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 string representation of the network structure.

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

`add`

Method

__add__(rhs: Expression | int | str | float | complex | TensorIndices | Expression | 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 \| str \| float \| complex \| TensorIndices \| Expression \| TensorNetwork \| Tensor`	`—`	The tensor network to add (right-hand side)

`radd`

Method

__radd__(rhs: Expression | int | str | float | complex | TensorIndices | Expression | TensorNetwork | Tensor) -> TensorNetwork

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

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| str \| float \| complex \| TensorIndices \| Expression \| TensorNetwork \| Tensor`	`—`	—

`sub`

Method

__sub__(rhs: Expression | int | str | float | complex | TensorIndices | Expression | 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 \| str \| float \| complex \| TensorIndices \| Expression \| TensorNetwork \| Tensor`	`—`	The tensor network to subtract (right-hand side)

`rsub`

Method

__rsub__(rhs: Expression | int | str | float | complex | TensorIndices | Expression | TensorNetwork | Tensor) -> TensorNetwork

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

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| str \| float \| complex \| TensorIndices \| Expression \| TensorNetwork \| Tensor`	`—`	—

`mul`

Method

__mul__(rhs: Expression | int | str | float | complex | TensorIndices | Expression | 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 \| str \| float \| complex \| TensorIndices \| Expression \| TensorNetwork \| Tensor`	`—`	The tensor network to multiply with (right-hand side)

`rmul`

Method

__rmul__(rhs: Expression | int | str | float | complex | TensorIndices | Expression | TensorNetwork | Tensor) -> TensorNetwork

Multiply two tensor networks (right-hand multiplication).

Parameters

Name	Type	Default	Description
`rhs`	`Expression \| int \| str \| float \| complex \| TensorIndices \| Expression \| TensorNetwork \| Tensor`	`—`	—

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