TensorNetwork

`TensorNetwork`

TensorNetwork()

A tensor network representing computational graphs of tensor operations.

A tensor network is a graph-based representation of tensor computations where nodes represent tensors and operations, edges represent tensor contractions and data flow, and the network can be optimized and executed to compute results.

Tensor networks are particularly useful for symbolic manipulation of complex tensor expressions, optimization of tensor contraction orders, efficient evaluation of large tensor computations, and physics calculations involving many-body systems.

Examples

import symbolica as sp
from symbolica.community.spenso import TensorNetwork, Tensor, TensorIndices
x = sp.symbol('x')
expr = x * sp.symbol('T')(sp.symbol('mu'), sp.symbol('nu'))
network = TensorNetwork(expr)
network.execute()
result = network.result_tensor()

Methods

Name	Description
`__add__`	Add two tensor networks element-wise.
`__mul__`	Multiply two tensor networks.
`__new__`	Create a tensor network by parsing an arithmetic expression
`__radd__`	Add two tensor networks element-wise (right-hand addition).
`__rmul__`	Multiply two tensor networks (right-hand multiplication).
`__rsub__`	Subtract one tensor network from another (right-hand subtraction).
`__str__`	Return a string representation of the network structure
`__sub__`	Subtract one tensor network from another element-wise.
`bracket`
`broadcast`
`evaluate`	Evaluate symbolic expressions in the network with numerical values
`execute`	Execute the tensor network to perform tensor contractions and simplifications
`one`	Create a tensor network representing the scalar value 1.
`replace`	Replace patterns in the tensor network using symbolic pattern matching
`result_scalar`	Extract the final scalar result from the executed network
`result_tensor`	Extract the final tensor result from the executed network
`zero`	Create a tensor network representing the scalar value 0.

`add`

TensorNetwork.__add__(rhs: Expression | int | str | float | builtins.complex | TensorIndices | Expression | TensorNetwork | Tensor) -> TensorNetwork

Add two tensor networks element-wise.

Parameters

rhs (TensorNetwork) The tensor network to add (right-hand side)

Returns

TensorNetwork A new TensorNetwork representing the sum

Examples

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

`mul`

TensorNetwork.__mul__(rhs: Expression | int | str | float | builtins.complex | TensorIndices | Expression | TensorNetwork | Tensor) -> TensorNetwork

Multiply two tensor networks.

Parameters

rhs (TensorNetwork) The tensor network to multiply with (right-hand side)

Returns

TensorNetwork A new TensorNetwork representing the product

Examples

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

`new`

TensorNetwork.__new__(
    expr: Expression | int | str | float | builtins.complex | TensorIndices | Expression,
    library: typing.Optional[TensorLibrary] = None,
) -> TensorNetwork

Create a tensor network by parsing an arithmetic expression.

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

Parameters

expr (ArithmeticStructure) The arithmetic expression or tensor structure to parse
library (TensorLibrary, optional) Optional tensor library for resolving named tensor references

Returns

TensorNetwork A new TensorNetwork representing the parsed expression

`radd`

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

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

`rmul`

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

Multiply two tensor networks (right-hand multiplication).

`rsub`

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

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

`str`

TensorNetwork.__str__() -> builtins.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.

`sub`

TensorNetwork.__sub__(rhs: Expression | int | str | float | builtins.complex | TensorIndices | Expression | TensorNetwork | Tensor) -> TensorNetwork

Subtract one tensor network from another element-wise.

Parameters

rhs (TensorNetwork) The tensor network to subtract (right-hand side)

Returns

TensorNetwork A new TensorNetwork representing the difference

Examples

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

`bracket`

TensorNetwork.bracket() -> Expression

`broadcast`

TensorNetwork.broadcast(str: builtins.str) -> Expression

`evaluate`

TensorNetwork.evaluate(
    constants: typing.Mapping[Expression, builtins.float],
    functions: typing.Mapping[Expression, typing.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.

Parameters

constants (dict) Dict mapping symbolic expressions to their numerical values
functions (dict) Dict mapping function symbols to Python callable objects

Returns

TensorNetwork A new TensorNetwork with symbolic expressions evaluated

`execute`

TensorNetwork.execute(
    library: typing.Optional[TensorLibrary] = None,
    function_library: typing.Optional[TensorFunctionLibrary] = None,
    n_steps: typing.Optional[builtins.int] = None,
    mode: ExecutionMode = ...,
) -> 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.

Parameters

library (TensorLibrary, optional) Optional tensor library for resolving tensor operations
n_steps (int, optional) Maximum number of execution steps (None for complete execution)
mode (ExecutionMode, optional) Execution strategy (ExecutionMode.All, ExecutionMode.Scalar, or ExecutionMode.Single)

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)

`one`

TensorNetwork.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()

`replace`

TensorNetwork.replace(
    pattern: Expression | int | str | float | builtins.complex,
    rhs: Expression | int | str | float | builtins.complex | HeldExpression | typing.Callable[[dict[Expression, Expression]], Expression] | int | float | complex | decimal.Decimal,
    _cond: typing.Optional[PatternRestriction | Condition] = None,
    non_greedy_wildcards: typing.Optional[typing.Sequence[Expression]] = None,
    level_range: typing.Optional[tuple[builtins.int, typing.Optional[builtins.int]]] = None,
    level_is_tree_depth: typing.Optional[builtins.bool] = None,
    allow_new_wildcards_on_rhs: typing.Optional[builtins.bool] = None,
    rhs_cache_size: typing.Optional[builtins.int] = None,
    repeat: typing.Optional[builtins.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.

Parameters

pattern (Expression) The symbolic pattern to match against
rhs (Expression) The replacement expression or pattern
non_greedy_wildcards (list of Expression, optional) List of wildcard symbols to match non-greedily
level_range (tuple of int, optional) Tuple specifying depth range for pattern matching
level_is_tree_depth (bool, optional) Whether level refers to tree depth or expression depth
allow_new_wildcards_on_rhs (bool, optional) Allow new wildcards in replacement pattern
rhs_cache_size (int, optional) Size of cache for replacement pattern compilation
repeat (bool, optional) Whether to repeatedly apply the replacement until no more matches

Returns

TensorNetwork A new TensorNetwork with the replacements applied

`result_scalar`

TensorNetwork.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()

`result_tensor`

TensorNetwork.result_tensor(library: typing.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.

Parameters

library (TensorLibrary, optional) Optional tensor library for resolving tensor structures

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)

`zero`

TensorNetwork.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()