TensorNetwork

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

TensorNetwork

class TensorNetwork

An executable tensor calculation that retains component data.

Networks combine tensor contractions, sums, products, and elementwise functions. Arithmetic creates new networks. execute() advances a network in place; step() and to_tensor() work on copies. expression() returns the symbolic source, while status reports remaining work.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network.to_tensor()
result[0, 1]
2.0

Attributes

Name Description
axes External axes in the current component and port-position order.
is_scalar Whether the tensor has no external axes.
rank Number of external tensor axes.
shape Dimensions in logical axis order.
status Read a snapshot of the remaining graph work without executing it.
structure Canonical external signature of the whole tensor.

axes

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

is_scalar

TensorNetwork.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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.is_scalar
False

rank

TensorNetwork.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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.rank
2

shape

TensorNetwork.shape: tuple[int | Expression, ...]

Dimensions in logical axis order.

Returns

  • tuple of int or Expression 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.shape
(2, 2)

status

TensorNetwork.status: ExecutionStatus

Read a snapshot of the remaining graph work without executing it.

Returns

  • ExecutionStatus Counts and ready operations at the moment of inspection.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.status.complete
True

structure

TensorNetwork.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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.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 TensorNetwork copy.
__mul__ Multiply tensors, contracting unambiguous compatible axes.
__neg__ Negate every tensor component.
__new__ Create a network from tensor components or symbolic algebra.
__radd__ Implement reflected addition.
__repr__ Return a readable object description for inspection.
__rmul__ Implement reflected multiplication.
__rsub__ Implement reflected subtraction.
__rtruediv__ Implement reflected division.
__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_
bracket Return the symbolic function used to group a tensor subexpression.
broadcast Register a raw Symbolica function for elementwise tensor application.
compose Multiply two tensors along explicitly selected matrix channels.
contract_ports Contract one chosen pair of axes between two tensors.
copy Copy this network and its current execution progress.
dot Contract two rank-one tensors using their representation pairing.
evaluate Numerically evaluate symbolic component values in a network copy.
execute Advance this network’s computation in place.
expression Return the symbolic source computation of this network.
format_tensor Produce compact plain-text tensor notation.
formatted Create a lazy rich display value for a notebook.
index Assign labels to the unresolved external axes.
one Construct the scalar 1 network.
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.
render Render the current network graph to SVG.
replace Replace scalar expressions and symbolic component values in a copy.
result_scalar Read the scalar value of a completed rank-zero network.
result_tensor Read the component tensor from a completed network.
step Run one execution round on a copy of this network.
to_dot Export the current network graph in Graphviz DOT syntax.
to_html Display the current network graph and execution status.
to_linnest Export a self-contained Typst document embedding the native SVG graph.
to_svg Render static mathematical tensor notation to SVG.
to_tensor Evaluate an independent copy of this network and return its components.
to_typst Produce static Typst math source.
trace Close a pair of matrix axes on this tensor.
zero Construct the scalar 0 network.

__add__

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

Related types: TensorExpression, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network + network

__call__

TensorNetwork.__call__(
    *indices: _IndexInput,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
indexed = network("i", "j")
indexed.rank
2

__copy__

TensorNetwork.__copy__() -> TensorNetwork

Implement copy.copy using an independent TensorNetwork copy.

Returns

  • TensorNetwork Copy of the component data and execution progress.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
import copy
copied = copy.copy(network)

__mul__

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

Related types: TensorExpression, Tensor, 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_ports(), 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network * 2

__neg__

TensorNetwork.__neg__() -> 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
negated = -network

__new__

TensorNetwork.__new__(
    expr: typing.Any,
    library: typing.Optional[TensorLibrary] = None,
) -> TensorNetwork

Related type: TensorLibrary

Create a network from tensor components or symbolic algebra.

Parameters

  • expr (Tensor, TensorNetwork, TensorExpression, or scalar expression) Computation to represent. A Tensor retains its data; a TensorNetwork is copied with its execution progress.
  • library (TensorLibrary, optional) Component definitions. Defaults to the built-in four-dimensional Dirac and SU(3) library. Unregistered tensors receive symbolic components.

Returns

  • TensorNetwork A new network with the corresponding external tensor interface.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.shape
(2, 2)

__radd__

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

Related types: TensorExpression, Tensor, FactorProjector

Implement reflected addition.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network + network

__repr__

TensorNetwork.__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])
network = tensor("i", "j") * tensor("j", "k")
text = repr(network)

__rmul__

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

Related types: TensorExpression, Tensor, FactorProjector

Implement reflected multiplication.

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_ports(), 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = 2 * network

__rsub__

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

Related types: TensorExpression, Tensor, FactorProjector

Implement reflected subtraction.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network - network

__rtruediv__

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

Related types: TensorExpression, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = 2 / TensorNetwork(3)

__str__

TensorNetwork.__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])
network = tensor("i", "j") * tensor("j", "k")
text = str(network)

__sub__

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

Related types: TensorExpression, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network - network

__truediv__

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

Related types: TensorExpression, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
result = network / 2

_repr_html_

TensorNetwork._repr_html_() -> builtins.str

_repr_latex_

TensorNetwork._repr_latex_() -> builtins.str

_repr_pretty_

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

bracket

TensorNetwork.bracket() -> Expression

Related type: Expression

Return the symbolic function used to group a tensor subexpression.

Returns

  • Expression A callable Symbolica head. Its argument is kept as a grouped tensor subexpression when parsed as a network.

Notes

This is useful when constructing raw Symbolica tensor syntax. Tensor-aware operations and simplifiers already understand this grouping.

Examples

from symbolica import S
from symbolica.community.tensor import TensorNetwork
grouped = TensorNetwork.bracket()(S("x") + 1)

broadcast

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

Related type: Expression

Register a raw Symbolica function for elementwise tensor application.

Parameters

  • str (str) Function name to register with the broadcast tag.

Returns

  • Expression A callable Symbolica function head.

Notes

Prefer BroadcastFunction when applying the function to TensorExpression, Tensor, or TensorNetwork objects so the return type follows the operand.

Examples

from symbolica import S
from symbolica.community.tensor import TensorNetwork
applied = TensorNetwork.broadcast("raw_function")(S("x"))

compose

TensorNetwork.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, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
product = network.compose(network, left=(0, 1), right=(0, 1))
product.rank
2

contract_ports

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

Related types: TensorExpression, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
contracted = network.contract_ports(network, left=1, right=0)
contracted.rank
2

copy

TensorNetwork.copy() -> TensorNetwork

Copy this network and its current execution progress.

Returns

  • TensorNetwork 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
copied = network.copy()
copied.shape == network.shape
True

dot

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

Related types: TensorExpression, Tensor, 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])
TensorNetwork(vector).dot(vector).to_tensor().scalar() == 5
True

evaluate

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

Related type: Expression

Numerically evaluate symbolic component values in a network copy.

Parameters

  • constants (mapping of Expression to float) Real values for symbolic parameters.
  • functions (mapping of Expression to callable) Symbolica function heads and real-valued Python implementations. A callback receives one list of evaluated argument values and returns a float; for example, lambda args: args[0] ** 2.

Returns

  • TensorNetwork Network with evaluated component values; contractions are not executed.

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)
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(values).evaluate({x: 2.0}, {})
network.to_tensor()[1]
4.0
f = S("f_network")
data = Tensor.dense(values.expression(), [f(x), x])
network = TensorNetwork(data).evaluate({x: 2.0}, {f: lambda args: args[0] + 1})
network.to_tensor()[0]
3.0

execute

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

Related types: TensorLibrary, TensorFunctionLibrary, ExecutionMode

Advance this network’s computation in place.

Parameters

  • library (TensorLibrary, optional) Component definitions. Defaults to the built-in four-dimensional Dirac and SU(3) library. Unregistered tensors receive symbolic components.
  • function_library (TensorFunctionLibrary, optional) Numerical implementations of broadcast functions. Defaults to the built-in function library.
  • n_steps (int, optional) Number of execution rounds. None runs the selected strategy to completion.
  • mode (ExecutionMode, default ExecutionMode.All) All uses MinIntermediateCost, which estimates sparse overlap and symbolic intermediate cost when choosing each contraction. Single selects one minimum-degree contraction at a time. Scalar restricts contraction to scalar work. Preprocessing and ready operations may also run in an execution round.

Returns

  • None This network’s execution progress and stored intermediate values change.

Notes

Use to_tensor() to evaluate a copy, or step() for an intermediate copy. result_tensor() extracts the result after execution.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.execute()
network.result_tensor()[1, 0]
3.0

expression

TensorNetwork.expression() -> TensorExpression

Related type: TensorExpression

Return the symbolic source computation of this network.

Returns

  • TensorExpression A symbolic tensor with the same external axes.

Notes

Execution progress and replacement of component values do not rewrite this source expression. Use result_tensor after execution to inspect 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.expression().rank
2

format_tensor

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

This formats the symbolic source expression, independent of execution progress. Use render() or to_html() for the network graph.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.format_tensor()

formatted

TensorNetwork.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 lazy 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 Each requested backend renders the complete source expression once and caches it.

Notes

This formats the symbolic source expression, independent of execution progress, retaining a snapshot of that source. Use render() or to_html() for the network graph.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.formatted()

index

TensorNetwork.index(
    *indices: _IndexInput,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
indexed = network.index("i", "j")
indexed.rank
2

one

TensorNetwork.one() -> TensorNetwork

Construct the scalar 1 network.

Examples

from symbolica.community import tensor as sp
network = sp.TensorNetwork.one()
value = network.to_tensor().scalar()

Returns

  • TensorNetwork A rank-zero multiplicative identity.

Examples

from symbolica.community.tensor import TensorNetwork
TensorNetwork.one().result_scalar() == 1
True

outer

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

Related types: TensorExpression, Tensor, 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
product = network.outer(network)
product.rank
4

permute_axes

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

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

  • TensorNetwork 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
transposed = network.permute_axes([1, 0])
transposed.shape
(2, 2)

reindex

TensorNetwork.reindex(
    *indices: _IndexInput,
    intern: typing.Optional[typing.Literal['indices', 'flattened']] = None,
) -> 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
indexed = network.reindex("i", "j")
indexed.rank
2

rename_indices

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

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

  • TensorNetwork 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
indexed = network.index("i", "j")
renamed = indexed.rename_indices({"i": "k"})
renamed.rank
2

render

TensorNetwork.render(
    *,
    config: builtins.dict[builtins.str, typing.Any] | None = None,
) -> builtins.str

Render the current network graph to SVG.

Parameters

  • config (dict, optional) Graph layout and rendering options. Omit for the standard network view.

Returns

  • str SVG graph, with notebook-theme styling.

Notes

This depicts the current graph, including execution progress. For the symbolic computation in tensor notation, use formatted() or to_svg(). Graph geometry is drawn in Rust; labels use the embedded Typst compiler.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.render()

replace

TensorNetwork.replace(
    pattern: _ScalarInput,
    rhs: _ReplacementInput,
    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

Related types: PatternRestriction, Condition, Expression

Replace scalar expressions and symbolic component values in a copy.

Examples

from symbolica.community import tensor as sp
from symbolica import E, S
x = S("docs::x")
network = sp.TensorNetwork(sp.TensorExpression(x + 1))
replaced = network.replace(x, E("2"))

Parameters

  • pattern (scalar expression) Symbolica pattern to find in scalar algebra and component expressions.
  • rhs (scalar expression or HeldExpression) Replacement expression. Python replacement callbacks are not supported by this network method; use TensorRule with TensorExpression for whole-tensor replacement.
  • cond (PatternRestriction or Condition, optional) Restriction applied to candidate matches.
  • non_greedy_wildcards (sequence of Expression, optional) Wildcards that should prefer shorter matches.
  • level_range ((int, int or None), optional) Minimum and maximum matching level; defaults to (0, None).
  • level_is_tree_depth (bool, optional) Count tree depth rather than function nesting. Defaults to False.
  • allow_new_wildcards_on_rhs (bool, optional) Permit unbound wildcard symbols in the replacement. Defaults to False.
  • rhs_cache_size (int, optional) Maximum cached right-hand-side substitutions. Defaults to 100.
  • repeat (bool, optional) Repeat replacements until unchanged. Defaults to False.

Returns

  • TensorNetwork A copy with updated scalar/component expressions. Its external axes and symbolic source descriptor are unchanged.

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)
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(values).replace(x, 2)
network.to_tensor()[0] == 2
True

result_scalar

TensorNetwork.result_scalar() -> Expression

Related type: Expression

Read the scalar value of a completed rank-zero network.

Returns

  • Expression Scalar result as Symbolica algebra.

Raises

  • RuntimeError: The network has not reduced to a scalar result.

Examples

from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(3)
network.execute()
network.result_scalar() == 3
True

result_tensor

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

Related types: TensorLibrary, Tensor

Read the component tensor from a completed network.

Parameters

  • library (TensorLibrary, optional) Component definitions. Defaults to the built-in four-dimensional Dirac and SU(3) library. Unregistered tensors receive symbolic components.

Returns

  • Tensor Result components with the source computation’s logical axis order.

Raises

  • RuntimeError: Work remains that prevents extracting one result tensor.

Notes

This does not run pending operations. Call execute() first, or use to_tensor() to execute a copy and extract the result in one operation. Existing component storage is preserved: exact Symbolica expressions are not converted to floating-point 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.execute()
network.result_tensor().shape
(2, 2)

step

TensorNetwork.step(
    library: typing.Optional[TensorLibrary] = None,
    *,
    function_library: typing.Optional[TensorFunctionLibrary] = None,
) -> TensorNetwork

Related types: TensorLibrary, TensorFunctionLibrary

Run one execution round on a copy of this network.

Parameters

  • library (TensorLibrary, optional) Component definitions. Defaults to the built-in four-dimensional Dirac and SU(3) library. Unregistered tensors receive symbolic components.
  • function_library (TensorFunctionLibrary, optional) Numerical implementations of broadcast functions. Defaults to the built-in function library.

Returns

  • TensorNetwork Next intermediate computation; this network remains unchanged.

Notes

The round uses ExecutionMode.Single and includes the usual preprocessing; it is not a promise to remove exactly one graph node.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
intermediate = network.step()
intermediate.shape
(2, 2)

to_dot

TensorNetwork.to_dot() -> builtins.str

Export the current network graph in Graphviz DOT syntax.

Returns

  • str Graph description containing the current tensor nodes and connections.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
source = network.to_dot()

to_html

TensorNetwork.to_html(
    *,
    config: builtins.dict[builtins.str, typing.Any] | None = None,
) -> builtins.str

Display the current network graph and execution status.

Parameters

  • config (dict, optional) Graph layout and rendering options. Omit for the standard network view.

Returns

  • str Interactive HTML graph with its progress summary.

Notes

This depicts the current graph, including execution progress. For the symbolic computation in tensor notation, use formatted() or to_svg(). Graph geometry is drawn in Rust; labels use the embedded Typst compiler.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.to_html()

to_linnest

TensorNetwork.to_linnest(
    *,
    config: builtins.dict[builtins.str, typing.Any] | None = None,
) -> builtins.str

Export a self-contained Typst document embedding the native SVG graph.

Parameters

  • config (dict, optional) Graph layout and rendering options. Omit for the standard network view.

Returns

  • str Typst source containing the complete SVG and its typeset labels.

Notes

This depicts the current graph, including execution progress. For the symbolic computation in tensor notation, use formatted() or to_svg(). Graph geometry is drawn in Rust; labels use the embedded Typst compiler.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.to_linnest()

to_svg

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

This formats the symbolic source expression, independent of execution progress. Use render() or to_html() for the network graph.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.to_svg()

to_tensor

TensorNetwork.to_tensor(
    library: typing.Optional[TensorLibrary] = None,
    *,
    function_library: typing.Optional[TensorFunctionLibrary] = None,
) -> Tensor

Related types: TensorLibrary, TensorFunctionLibrary, Tensor

Evaluate an independent copy of this network and return its components.

Parameters

  • library (TensorLibrary, optional) Component definitions. Defaults to the built-in four-dimensional Dirac and SU(3) library. Unregistered tensors receive symbolic components.
  • function_library (TensorFunctionLibrary, optional) Numerical implementations of broadcast functions. Defaults to the built-in function library.

Returns

  • Tensor Resulting components in logical axis order. Dimensions must be concrete.

Notes

The original network and its execution progress and the supplied libraries are 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.to_tensor().shape
(2, 2)

to_typst

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

This formats the symbolic source expression, independent of execution progress. Use render() or to_html() for the network graph.

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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
output = network.to_typst()

trace

TensorNetwork.trace(
    *,
    channel: typing.Optional[tuple[builtins.int, builtins.int]] = None,
) -> 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])
from symbolica.community.tensor import TensorNetwork
network = TensorNetwork(tensor)
network.trace(channel=(0, 1)).is_scalar
True

zero

TensorNetwork.zero() -> TensorNetwork

Construct the scalar 0 network.

Examples

from symbolica.community import tensor as sp
network = sp.TensorNetwork.zero()
value = network.to_tensor().scalar()

Returns

  • TensorNetwork A rank-zero additive zero.

Examples

from symbolica.community.tensor import TensorNetwork
TensorNetwork.zero().result_scalar() == 0
True