TensorStructure

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

TensorStructure

class TensorStructure

The canonical external signature of an opaque tensor.

A Slot denotes a labeled axis; a Representation denotes an unresolved axis. This immutable signature contains only free axes: no tensor name, scalar arguments, expression, component data, or layout permutation. Axes follow Spenso’s canonical representation/index ordering. A(i,j), A(j,i), and their sum have the same structure. The expression retains argument order; tensor and network component views retain their own axis order.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(3)
A = TensorName("A")(space, space)
metadata = A.structure
metadata.rank
2

Attributes

Name Description
axes Free axes in canonical representation/index order
is_scalar Whether the tensor has no external axes.
rank Number of external tensor axes.
shape Dimensions in canonical signature order.

axes

TensorStructure.axes: tuple[Slot | Representation, ...]

Free axes in canonical representation/index order.

The signature is independent of argument order, factor order, and summand order. It describes the whole expression as an opaque tensor. Component coordinates belong to the tensor’s current view, not to this signature.

Returns

  • tuple of Slot or Representation Labeled and unresolved axes, respectively.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(3)
A = TensorName("A")(space, space)
A.structure.axes == (space, space)
True

is_scalar

TensorStructure.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(3)
A = TensorName("A")(space, space)
A = A.structure
A.is_scalar
False

rank

TensorStructure.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(3)
A = TensorName("A")(space, space)
A = A.structure
A.rank
2

shape

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

Dimensions in canonical signature order.

Returns

  • tuple of int or Expression Concrete dimensions are integers; symbolic dimensions remain expressions.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(3)
A = TensorName("A")(space, space)
A = A.structure
A.shape
(3, 3)

Methods

Name Description
__eq__
__new__ Describe an opaque tensor by its canonical free axes.
__repr__ Return a readable object description for inspection.
_repr_html_
representations Return every external axis as an unresolved representation.
slots Return every external axis as an explicitly indexed slot.
to_html Render a compact HTML view of this tensor metadata.

__eq__

TensorStructure.__eq__(other: builtins.object) -> builtins.bool

__new__

TensorStructure.__new__(slots: typing.Sequence[Slot | Representation]) -> TensorStructure

Related types: Slot, Representation

Describe an opaque tensor by its canonical free axes.

Parameters

  • slots (sequence of Slot or Representation) Free axes, sorted into canonical order. Repeated unresolved spaces remain distinct axes. This describes a signature without contracting it.

Returns

  • TensorStructure Canonical signature, independent of the supplied sequence order.

Examples

from symbolica.community.tensor import Representation, TensorStructure
metadata = TensorStructure([Representation.euc(2), Representation.euc(3)])
metadata.shape
(2, 3)

__repr__

TensorStructure.__repr__() -> builtins.str

Return a readable object description for inspection.

Examples

from symbolica.community import tensor as sp
r = sp.Representation.euc(2)
structure = sp.TensorStructure([r("i"), r("j")])
text = repr(structure)

_repr_html_

TensorStructure._repr_html_() -> builtins.str

representations

TensorStructure.representations() -> builtins.list[Representation]

Related type: Representation

Return every external axis as an unresolved representation.

Returns

  • list of Representation Representations in canonical order; an empty list for a scalar. Different spaces, dimensions, and dualities are allowed.

Raises

  • ValueError: If any axis has an explicit index. Labels are never discarded. Use axes to inspect a mixed structure.

Examples

from symbolica.community.tensor import Representation, TensorStructure
spaces = [Representation.mink(4), Representation.euc(3)]
TensorStructure(spaces) == TensorStructure(spaces[::-1])
True

slots

TensorStructure.slots() -> builtins.list[Slot]

Related type: Slot

Return every external axis as an explicitly indexed slot.

Returns

  • list of Slot Slots in canonical order; an empty list for a scalar. Representations and dimensions may differ between axes.

Raises

  • ValueError: If any axis is unresolved. No indices are invented or axes omitted. Use axes to inspect a mixed structure.

Examples

from symbolica.community.tensor import Representation, TensorStructure
space = Representation.euc(3)
metadata = TensorStructure([space("j"), space("i")])
metadata.slots() == TensorStructure([space("i"), space("j")]).slots()
True

to_html

TensorStructure.to_html(*, settings: typing.Optional[DisplaySettings] = None) -> builtins.str

Related type: DisplaySettings

Render a compact HTML view of this tensor metadata.

Parameters

  • settings (DisplaySettings, optional) Index and tensor presentation choices; defaults to DisplaySettings().

Returns

  • str HTML fragment for display in a notebook or page.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
value = A.structure
html = value.to_html()