LibraryTensor

LibraryTensor

LibraryTensor()

A library tensor class optimized for use in tensor libraries and networks.

Library tensors are similar to regular tensors but use explicit keys for efficient lookup and storage in tensor libraries. They can be either dense or sparse and store data as floats, complex numbers, or symbolic expressions.

LibraryTensors are designed for:

  • Registration in TensorLibrary instances
  • Use in tensor networks where structure reuse is important
  • Efficient symbolic manipulation and pattern matching

Examples

from symbolica.community.spenso import LibraryTensor, TensorStructure, Representation
rep = Representation.euc(3)
structure = TensorStructure(rep, rep, name="T")
data = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
tensor = LibraryTensor.dense(structure, data)
sparse_tensor = LibraryTensor.sparse(structure, float)

Methods

Name Description
__getitem__ Get library tensor elements at the specified range of indices.
__len__
__repr__
__setitem__ Set library tensor element(s) at the specified index or indices.
__str__
dense Create a new dense library tensor with the given structure and data
one Create a scalar library tensor with value 1.0.
scalar Extract the scalar value from a rank-0 (scalar) library tensor.
sparse Create a new sparse empty library tensor with the given structure and data type
structure
to_dense Convert this library tensor to dense storage format
to_sparse Convert this library tensor to sparse storage format
zero Create a scalar library tensor with value 0.0.

__getitem__

__getitem__ has 3 variants:

__getitem__ returning typing.Any

LibraryTensor.__getitem__(item: builtins.slice | builtins.int | builtins.list[builtins.int]) -> typing.Any

__getitem__ returning builtins.list[Expression | builtins.complex | float]

LibraryTensor.__getitem__(item: builtins.slice) -> builtins.list[Expression | builtins.complex | float]

Related type: Expression

Get library tensor elements at the specified range of indices.

Parameters

  • item (slice) Slice object defining the range of indices

Returns

  • list of float, complex, or Expression The tensor elements at the specified range

__getitem__ returning Expression | builtins.complex | float

LibraryTensor.__getitem__(item: typing.Sequence[builtins.int] | builtins.int) -> Expression | builtins.complex | float

Related type: Expression

Get library tensor element at the specified index or indices.

Parameters

  • item (int or list of int) Index specification (int for flat index, list of int for coordinates)

Returns

  • float, complex, or Expression The tensor element at the specified index

__len__

LibraryTensor.__len__() -> builtins.int

__repr__

LibraryTensor.__repr__() -> builtins.str

__setitem__

LibraryTensor.__setitem__(item: typing.Any, value: typing.Any) -> None
LibraryTensor.__setitem__(
    item: typing.Sequence[builtins.int] | builtins.int,
    value: Expression | builtins.complex | float,
) -> None

Related type: Expression

Set library tensor element(s) at the specified index or indices.

Parameters

  • item (int or list of int) Index specification (int for flat index, list of int for coordinates)
  • value (float, complex, or Expression) The value to set

Examples

from symbolica.community.spenso import LibraryTensor, TensorStructure, Representation
rep = Representation.euc(2)
structure = TensorStructure(rep, rep)
tensor = LibraryTensor.sparse(structure, float)
tensor[0] = 1.0
tensor[1, 1] = 2.0

__str__

LibraryTensor.__str__() -> builtins.str

dense

LibraryTensor.dense(
    structure: TensorStructure | builtins.list[Representation] | builtins.list[builtins.int],
    data: typing.Sequence[Expression] | typing.Sequence[builtins.float] | typing.Sequence[builtins.complex],
) -> LibraryTensor

Related types: TensorStructure, Representation, Expression

Create a new dense library tensor with the given structure and data.

Dense tensors store all elements explicitly in row-major order. The structure defines the tensor’s shape and indexing properties.

Parameters

  • structure (TensorStructure, list of Representations, or list of int) The tensor structure defining shape and index properties
  • data (list of float, complex, or Expression) The tensor data in row-major order

Returns

  • LibraryTensor A new dense library tensor with the specified data

Examples

from symbolica import S
from symbolica.community.spenso import LibraryTensor, TensorStructure, Representation
rep = Representation.euc(2)
sigma = S("sigma")
structure = TensorStructure(rep, rep, name=sigma)
data = [0.0, 1.0, 1.0, 0.0]
tensor = LibraryTensor.dense(structure, data)
x, y = S("x", "y")
sym_data = [x, y, -y, x]
sym_tensor = LibraryTensor.dense(structure, sym_data)

one

LibraryTensor.one() -> LibraryTensor

Create a scalar library tensor with value 1.0.

Returns

  • LibraryTensor A scalar library tensor containing the value 1.0

Examples

from symbolica.community.spenso import LibraryTensor
one = LibraryTensor.one()

scalar

LibraryTensor.scalar() -> Expression

Related type: Expression

Extract the scalar value from a rank-0 (scalar) library tensor.

Returns

  • Expression The scalar expression contained in this tensor

Raises

  • RuntimeError: If the tensor is not a scalar

Examples

from symbolica.community.spenso import LibraryTensor
scalar_tensor = LibraryTensor.one()
value = scalar_tensor.scalar()

sparse

LibraryTensor.sparse(
    structure: TensorStructure | builtins.list[Representation] | builtins.list[builtins.int],
    type_info: type,
) -> LibraryTensor

Related types: TensorStructure, Representation

Create a new sparse empty library tensor with the given structure and data type.

Creates a sparse tensor that initially contains no non-zero elements. Elements can be set individually using indexing operations.

Parameters

  • structure (TensorStructure, list of Representations, or list of int) The tensor structure defining shape and index properties
  • type_info (type) The data type - either float or Expression class

Returns

  • LibraryTensor A new sparse library tensor with all elements initially zero

Examples

import symbolica as sp
from symbolica.community.spenso import LibraryTensor, TensorStructure, Representation
rep = Representation.euc(3)
structure = TensorStructure(rep, rep)
sparse_float = LibraryTensor.sparse(structure, float)
sparse_sym = LibraryTensor.sparse(structure, sp.Expression)
sparse_float[0, 0] = 1.0
sparse_float[1, 1] = 2.0

structure

LibraryTensor.structure() -> TensorStructure

Related type: TensorStructure

to_dense

LibraryTensor.to_dense() -> None

Convert this library tensor to dense storage format.

Converts sparse tensors to dense format in-place. Dense tensors are unchanged. This allocates memory for all tensor elements.

Examples

from symbolica.community.spenso import LibraryTensor, TensorStructure, Representation

rep = Representation.cof(2)
structure = TensorStructure([rep, rep])
tensor = LibraryTensor.sparse(structure, float)
tensor[0, 0] = 1.0
tensor.to_dense()  # Now stores all 4 elements explicitly

to_sparse

LibraryTensor.to_sparse() -> None

Convert this library tensor to sparse storage format.

Converts dense tensors to sparse format in-place, only storing non-zero elements. This can save memory for tensors with many zero elements.

Examples

from symbolica.community.spenso import LibraryTensor, TensorStructure, Representation

rep = Representation.euc(2)
structure = TensorStructure(rep, rep)
data = [1.0, 0.0, 0.0, 2.0]
tensor = LibraryTensor.dense(structure, data)
tensor.to_sparse()  # Now only stores 2 non-zero elements

zero

LibraryTensor.zero() -> LibraryTensor

Create a scalar library tensor with value 0.0.

Returns

  • LibraryTensor A scalar library tensor containing the value 0.0

Examples

from symbolica.community.spenso import LibraryTensor
zero = LibraryTensor.zero()