TensorLibrary

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

TensorLibrary

class TensorLibrary

Reusable component definitions indexed by tensor name and signature.

Register a named Tensor, then use its symbolic expression in calculations with this library. A full signature includes the name, scalar arguments, and representations. A name alone is a shortcut when it identifies one entry.

Lookup returns independent component data. Enumeration lists stored entries; dimension-dependent factories, such as metrics, are resolved on demand.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
library[A.name][1, 0]
3.0

Methods

Name Description
__contains__ Check whether a stored signature or factory can resolve a key.
__getitem__ Retrieve a tensor by exact signature or unambiguous name.
__iter__ Iterate over a snapshot of stored tensor signatures.
__len__ Count stored tensor definitions.
__new__ Create an empty tensor component library.
__repr__ Return a readable object description for inspection.
_repr_html_
construct Create an empty tensor component library.
get Retrieve a tensor, returning a default when its signature is absent.
hep_lib Load standard Dirac and SU(3) tensors with floating-point components.
hep_lib_atom Load standard Dirac and SU(3) tensors with exact symbolic components.
items List stored tensor signatures together with their component data.
keys List the full unresolved signatures of stored tensors.
register Store an independent copy of a named tensor’s components.
to_html Display stored tensors with on-demand component and construction details.
values List independent copies of the stored tensors.

__contains__

TensorLibrary.__contains__(key: TensorExpression | TensorName | Expression | builtins.str) -> builtins.bool

Related types: TensorExpression, TensorName, Expression

Check whether a stored signature or factory can resolve a key.

Parameters

  • key (TensorExpression, TensorName, Expression, or str) A fully unresolved tensor expression selects an exact signature. A TensorName, symbol, or string selects a name only when exactly one stored signature has that name. Exact signatures also select factories. Strings without a namespace use “spenso_python”; prefer TensorName or a fully qualified string when the symbol uses another namespace.

Returns

  • bool False for a missing key. Factories are checked without constructing their component data.

Notes

An ambiguous name or invalid key raises the same error as lookup.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
A in library
True

__getitem__

TensorLibrary.__getitem__(key: TensorExpression | TensorName | Expression | builtins.str) -> Tensor

Related types: TensorExpression, TensorName, Expression, Tensor

Retrieve a tensor by exact signature or unambiguous name.

Parameters

  • key (TensorExpression, TensorName, Expression, or str) A fully unresolved tensor expression selects an exact signature. A TensorName, symbol, or string selects a name only when exactly one stored signature has that name. Exact signatures also select factories. Strings without a namespace use “spenso_python”; prefer TensorName or a fully qualified string when the symbol uses another namespace.

Returns

  • Tensor An independent copy in the requested logical axis order. Call its expression() method for a symbolic reference.

Raises

  • KeyError: The key is missing or the name matches more than one stored signature.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
stored = library[A]
stored[0, 1]
2.0

__iter__

TensorLibrary.__iter__() -> typing.Iterator[TensorExpression]

Related type: TensorExpression

Iterate over a snapshot of stored tensor signatures.

Returns

  • iterator of TensorExpression Same entries and ordering as keys().

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
len(list(library))
1

__len__

TensorLibrary.__len__() -> builtins.int

Count stored tensor definitions.

Returns

  • int Number of stored entries; excludes on-demand factories.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
len(library)
1

__new__

TensorLibrary.__new__() -> TensorLibrary

Create an empty tensor component library.

Examples

from symbolica.community import tensor as sp
library = sp.TensorLibrary()

Returns

  • TensorLibrary Library ready to accept named tensors through register().

Examples

from symbolica.community.tensor import TensorLibrary
library = TensorLibrary()
len(library)
0

__repr__

TensorLibrary.__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])
library = sp.TensorLibrary()
library.register(tensor)
text = repr(library)

_repr_html_

TensorLibrary._repr_html_() -> typing.Optional[builtins.str]

construct

TensorLibrary.construct() -> TensorLibrary

Create an empty tensor component library.

Examples

from symbolica.community import tensor as sp
library = sp.TensorLibrary.construct()

Returns

  • TensorLibrary Library ready to accept named tensors through register().

Examples

from symbolica.community.tensor import TensorLibrary
library = TensorLibrary.construct()
len(library)
0

get

TensorLibrary.get(
    key: TensorExpression | TensorName | Expression | builtins.str,
    default: None = None,
) -> Tensor | None
TensorLibrary.get(
    key: TensorExpression | TensorName | Expression | builtins.str,
    default: _LibraryDefault,
) -> Tensor | _LibraryDefault

Related types: TensorExpression, TensorName, Expression, Tensor

Retrieve a tensor, returning a default when its signature is absent.

Parameters

  • key (TensorExpression, TensorName, Expression, or str) A fully unresolved tensor expression selects an exact signature. A TensorName, symbol, or string selects a name only when exactly one stored signature has that name. Exact signatures also select factories. Strings without a namespace use “spenso_python”; prefer TensorName or a fully qualified string when the symbol uses another namespace.
  • default (object, default None) Value returned only when the signature is missing.

Returns

  • Tensor or object Independent tensor snapshot, or the supplied default.

Notes

Ambiguous names and invalid keys still raise; they do not select the default.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
library.get("missing_tensor") is None
True

hep_lib

TensorLibrary.hep_lib() -> TensorLibrary

Load standard Dirac and SU(3) tensors with floating-point components.

Examples

from symbolica.community import tensor as sp
library = sp.TensorLibrary.hep_lib()
gamma = sp.TensorExpression.dirac_gamma(4)
components = gamma.to_tensor(library)

Returns

  • TensorLibrary Independent library with four-dimensional Dirac matrices in the Weyl basis, SU(3) color tensors, and dimension-dependent metric factories.

Notes

Values use double-precision real or complex numbers. This explicitly selects numerical components; omitted HEP libraries and hep_lib_atom() use exact Symbolica expressions.

Examples

from symbolica.community.tensor import TensorLibrary, TensorExpression
library = TensorLibrary.hep_lib()
library[TensorExpression.dirac_gamma(4)].shape
(4, 4, 4)

hep_lib_atom

TensorLibrary.hep_lib_atom() -> TensorLibrary

Load standard Dirac and SU(3) tensors with exact symbolic components.

Examples

from symbolica.community import tensor as sp
library = sp.TensorLibrary.hep_lib_atom()
gamma = sp.TensorExpression.dirac_gamma(4)
components = gamma.to_tensor(library)

Returns

  • TensorLibrary Independent library with four-dimensional Dirac matrices in the Weyl basis, SU(3) color tensors, and dimension-dependent metric factories.

Notes

Components are Symbolica Expressions, retaining exact rational and algebraic constants for symbolic component calculations. This is the same component convention used when tensor-network evaluation omits a library. Use hep_lib() to request floating-point HEP data explicitly.

Examples

from symbolica.community.tensor import TensorLibrary, TensorExpression
library = TensorLibrary.hep_lib_atom()
library[TensorExpression.dirac_gamma(4)].shape
(4, 4, 4)

items

TensorLibrary.items() -> builtins.list[tuple[TensorExpression, Tensor]]

Related types: TensorExpression, Tensor

List stored tensor signatures together with their component data.

Returns

  • list of (TensorExpression, Tensor) Independent snapshots in the same order as keys().

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
len(library.items())
1

keys

TensorLibrary.keys() -> builtins.list[TensorExpression]

Related type: TensorExpression

List the full unresolved signatures of stored tensors.

Returns

  • list of TensorExpression Snapshot in name/signature order, excluding on-demand factories.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
len(library.keys())
1

register

TensorLibrary.register(tensor: Tensor) -> None

Related type: Tensor

Store an independent copy of a named tensor’s components.

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])
library = sp.TensorLibrary()
library.register(tensor)
stored = library[A]

Parameters

  • tensor (Tensor) Tensor with a name, scalar key arguments, concrete dimensions, and fully unresolved external axes (no explicit index labels). Use tensor.with_name(…) if the tensor is unnamed.

Returns

  • None Adds or replaces the entry for this exact signature.

Notes

Changing the original tensor afterward does not change this library. Register a modified tensor again to update its stored definition.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
len(library)
1

to_html

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

Related type: DisplaySettings

Display stored tensors with on-demand component and construction details.

Parameters

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

Returns

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

Notes

Stored entries can be selected to inspect the same component explorer as a standalone Tensor. On-demand factories are listed 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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
value = library
html = value.to_html()

values

TensorLibrary.values() -> builtins.list[Tensor]

Related type: Tensor

List independent copies of the stored tensors.

Returns

  • list of Tensor Snapshot in the same order as keys(), excluding on-demand factories.

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 TensorLibrary
library = TensorLibrary()
library.register(tensor)
len(library.values())
1