Spaces API#

Spaces describe valid elements, array representation, geometry, flattening, and validation.

Coordinate and vector spaces#

spacecore.space.Space

General space capability: context ownership and membership checks.

spacecore.space.VectorSpace

Abstract vector-space capability: linear operations only.

spacecore.space.CoordinateSpace

Finite coordinate vector space capability.

spacecore.space.DenseCoordinateSpace

Concrete dense backend arrays with arbitrary finite coordinate shape.

spacecore.space.DenseVectorSpace

Plain one-dimensional dense vectors with no Jordan capability by default.

  • Space owns context and membership checking.

  • VectorSpace adds linear operations on elements.

  • CoordinateSpace adds a finite coordinate shape and flattening.

  • DenseCoordinateSpace represents dense arrays of fixed shape with an inner product.

  • DenseVectorSpace represents one-dimensional dense vectors with star but no Jordan capability by default.

Structured spaces#

spacecore.space.HermitianSpace

Represent dense Hermitian matrices with Frobenius geometry.

spacecore.space.TreeSpace

Represent a finite direct product as a Python tree.

spacecore.space.TreeElement

Bind ordered leaves to a TreeSpace.

spacecore.space.TreeSpectralDecomposition

Store leafwise Jordan spectral data in deterministic leaf order.

spacecore.space.StackedSpace

Leading-axis copies of a coordinate leaf space.

  • HermitianSpace represents dense Hermitian or symmetric matrices with Frobenius geometry.

  • TreeSpace is the single structured finite direct-product abstraction. Its Python tree records representation, not a tensor product.

  • TreeElement binds ordered leaves to a TreeSpace and reconstructs the Python value.

  • StackedSpace represents a fixed number of leading-axis copies of one coordinate leaf space.

Inner products and geometries#

spacecore.space.InnerProduct

Geometry of a space: inner product plus Riesz maps.

spacecore.space.EuclideanInnerProduct

Standard coordinate inner product vdot(x, y) with identity Riesz maps.

spacecore.space.WeightedInnerProduct

Diagonal-metric geometry <x, y> = vdot(x, weights * y).

spacecore.space.InnerProductSpace

Vector space capability with an inner-product geometry.

  • InnerProduct defines inner and Riesz maps.

  • EuclideanInnerProduct is the standard coordinate vdot geometry.

  • WeightedInnerProduct is a positive diagonal metric with weights stored as a backend array.

  • InnerProductSpace exposes inner, norm, riesz, and riesz_inverse.

Star and Jordan-capable spaces#

spacecore.space.StarSpace

Space capability with a canonical involution/star operation.

spacecore.space.JordanAlgebraSpace

Vector space capability with a Jordan product and spectral calculus.

spacecore.space.EuclideanJordanAlgebraSpace

Jordan algebra capability with a compatible inner product.

spacecore.space.ElementwiseJordanSpace

Elementwise Jordan algebra for real or complex dense coordinates.

spacecore.space.EuclideanElementwiseJordanSpace

Real elementwise Euclidean Jordan algebra.

  • StarSpace exposes a canonical involution.

  • JordanAlgebraSpace exposes Jordan products and spectral calculus.

  • EuclideanJordanAlgebraSpace marks Jordan structure compatible with Euclidean geometry.

  • ElementwiseJordanSpace represents coordinatewise multiplication and spectral application.

  • EuclideanElementwiseJordanSpace is the real Euclidean specialization.

Validation#

spacecore.space.SpaceCheck

Define a membership check for Space objects.

spacecore.space.SpaceValidationError

Raised when an object is not a member of a space.

spacecore.space.BackendCheck

Check that a value is a dense array for a space backend.

spacecore.space.ShapeCheck

Check that a value has the canonical shape of a space.

spacecore.space.FieldCheck

Check that a value is compatible with a space's mathematical field.

spacecore.space.DTypeCheck

Check that a value has the dtype required by a space context.

spacecore.space.SquareMatrixCheck

Check that a value has square trailing matrix axes.

spacecore.space.HermitianCheck

Check that a value is Hermitian within tolerances.

Autodoc#

class spacecore.space.Space(ctx=None)[source]#

Bases: ContextBound

General space capability: context ownership and membership checks.

Parameters:

ctx (Context, str, or None, optional) – Context specification used for elements and validation checks.

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()[source]#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

check_member(x)[source]#
Parameters:

x (Any)

Return type:

None

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

class spacecore.space.VectorSpace(ctx=None)[source]#

Bases: Space

Abstract vector-space capability: linear operations only.

Parameters:

ctx (Context, str, or None, optional) – Context specification used for elements and validation checks.

abstractmethod zeros()[source]#

Return the additive identity.

Return type:

Any

abstractmethod add(x, y)[source]#

Return x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

abstractmethod scale(a, x)[source]#

Return a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

axpy(a, x, y)[source]#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

class spacecore.space.CoordinateSpace(shape, ctx=None)[source]#

Bases: VectorSpace

Finite coordinate vector space capability.

Parameters:

  • shape (tuple of int) – Canonical coordinate shape for one element of the space.

  • ctx (Context, str, or None, optional) – Context specification used for coordinate arrays.

shape: Tuple[int, ...]#
property size: int#

Return the flat coordinate dimension of this space.

abstractmethod flatten(x)[source]#

Return a dense one-dimensional coordinate vector.

Parameters:

x (Any)

Return type:

DenseArray

abstractmethod unflatten(v)[source]#

Inverse of flatten.

Parameters:

v (DenseArray)

Return type:

Any

flatten_batch(xs)[source]#

Flatten a leading-axis batch of space elements to shape (N, size).

Parameters:

xs (Any)

Return type:

DenseArray

unflatten_batch(vs)[source]#

Unflatten rows of shape (N, size) into a leading-axis batch.

Parameters:

vs (DenseArray)

Return type:

Any

add_batch(x, y)[source]#

Return the leading-axis batch sum of x and y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

scale_batch(a, x)[source]#

Return the leading-axis batch scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

abstractmethod add(x, y)#

Return x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

abstractmethod scale(a, x)#

Return a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

stacked(count)[source]#

Return count leading-axis copies of this leaf space as one space.

Parameters:

count (int)

Return type:

CoordinateSpace

abstractmethod zeros()#

Return the additive identity.

Return type:

Any

class spacecore.space.InnerProduct[source]#

Bases: ABC

Geometry of a space: inner product plus Riesz maps.

abstractmethod inner(ops, x, y)[source]#

Return the inner product of x and y.

riesz(ops, x)[source]#

Map a coordinate element to its dual. Euclidean default: identity.

riesz_inverse(ops, x)[source]#

Map a dual element back to coordinates. Euclidean default: identity.

convert(ctx)[source]#

Return this geometry represented in ctx when conversion is needed.

validate_for(space)[source]#

Raise if this inner product is invalid for space.

Parameters:

space (InnerProductSpace)

Return type:

None

property is_euclidean: bool#

Whether this geometry is the Euclidean coordinate inner product.

class spacecore.space.EuclideanInnerProduct[source]#

Bases: InnerProduct

Standard coordinate inner product vdot(x, y) with identity Riesz maps.

inner(ops, x, y)[source]#

Return the inner product of x and y.

property is_euclidean: bool#

Whether this geometry is the Euclidean coordinate inner product.

convert(ctx)#

Return this geometry represented in ctx when conversion is needed.

riesz(ops, x)#

Map a coordinate element to its dual. Euclidean default: identity.

riesz_inverse(ops, x)#

Map a dual element back to coordinates. Euclidean default: identity.

validate_for(space)#

Raise if this inner product is invalid for space.

Parameters:

space (InnerProductSpace)

Return type:

None

class spacecore.space.WeightedInnerProduct(weights)[source]#

Bases: InnerProduct

Diagonal-metric geometry <x, y> = vdot(x, weights * y).

Parameters:

weights (array-like) – Positive, finite diagonal weights with exactly the coordinate-space shape and context dtype.

inner(ops, x, y)[source]#

Return the inner product of x and y.

riesz(ops, x)[source]#

Map a coordinate element to its dual. Euclidean default: identity.

riesz_inverse(ops, x)[source]#

Map a dual element back to coordinates. Euclidean default: identity.

convert(ctx)[source]#

Return this geometry represented in ctx when conversion is needed.

validate_for(space)[source]#

Validate diagonal weights against a coordinate space.

Parameters:

space (InnerProductSpace)

Return type:

None

property is_euclidean: bool#

Whether this geometry is the Euclidean coordinate inner product.

class spacecore.space.InnerProductSpace(ctx=None)[source]#

Bases: VectorSpace

Vector space capability with an inner-product geometry.

Parameters:

ctx (Context, str, or None, optional) – Context specification used for elements and validation checks.

geometry: InnerProduct#
inner(x, y)[source]#
Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

riesz(x)[source]#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)[source]#
Parameters:

x (Any)

Return type:

Any

norm(x)[source]#
Parameters:

x (Any)

Return type:

Any

property is_euclidean: bool#
abstractmethod add(x, y)#

Return x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

abstractmethod scale(a, x)#

Return a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

abstractmethod zeros()#

Return the additive identity.

Return type:

Any

class spacecore.space.StarSpace(ctx=None)[source]#

Bases: Space

Space capability with a canonical involution/star operation.

Parameters:

ctx (Context, str, or None, optional) – Context specification used for elements and validation checks.

abstractmethod star(x)[source]#

Return the canonical star/involution of x.

Parameters:

x (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

class spacecore.space.JordanAlgebraSpace(ctx=None)[source]#

Bases: VectorSpace

Vector space capability with a Jordan product and spectral calculus.

Parameters:

ctx (Context, str, or None, optional) – Context specification used for elements and validation checks.

abstractmethod jordan(x, y)[source]#

Return the Jordan product of x and y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

abstractmethod spectrum(x)[source]#

Return Jordan-algebraic eigenvalues of x.

Parameters:

x (Any)

Return type:

Any

abstractmethod spectral_decompose(x)[source]#

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

abstractmethod from_spectrum(eigvals, frame)[source]#

Reconstruct an element from spectral data.

Parameters:

  • eigvals (Any)

  • frame (Any)

Return type:

Any

spectral_apply(x, f)[source]#
Parameters:

  • x (Any)

  • f (Callable)

Return type:

Any

abstractmethod unit()[source]#

Return the Jordan-algebraic identity element e (all-ones spectrum).

Return type:

Any

trace(x)[source]#

Return the Jordan trace sum_i lambda_i(x) of the spectrum.

Parameters:

x (Any)

Return type:

Any

determinant(x)[source]#

Return the Jordan determinant prod_i lambda_i(x) of the spectrum.

Parameters:

x (Any)

Return type:

Any

abstractmethod add(x, y)#

Return x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

abstractmethod scale(a, x)#

Return a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

abstractmethod zeros()#

Return the additive identity.

Return type:

Any

class spacecore.space.EuclideanJordanAlgebraSpace(ctx=None)[source]#

Bases: JordanAlgebraSpace, InnerProductSpace

Jordan algebra capability with a compatible inner product.

Parameters:

ctx (Context, str, or None, optional) – Context specification used for elements and validation checks.

abstractmethod add(x, y)#

Return x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

determinant(x)#

Return the Jordan determinant prod_i lambda_i(x) of the spectrum.

Parameters:

x (Any)

Return type:

Any

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

abstractmethod from_spectrum(eigvals, frame)#

Reconstruct an element from spectral data.

Parameters:

  • eigvals (Any)

  • frame (Any)

Return type:

Any

inner(x, y)#
Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

property is_euclidean: bool#
abstractmethod jordan(x, y)#

Return the Jordan product of x and y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

norm(x)#
Parameters:

x (Any)

Return type:

Any

riesz(x)#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)#
Parameters:

x (Any)

Return type:

Any

abstractmethod scale(a, x)#

Return a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

spectral_apply(x, f)#
Parameters:

  • x (Any)

  • f (Callable)

Return type:

Any

abstractmethod spectral_decompose(x)#

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

abstractmethod spectrum(x)#

Return Jordan-algebraic eigenvalues of x.

Parameters:

x (Any)

Return type:

Any

trace(x)#

Return the Jordan trace sum_i lambda_i(x) of the spectrum.

Parameters:

x (Any)

Return type:

Any

abstractmethod unit()#

Return the Jordan-algebraic identity element e (all-ones spectrum).

Return type:

Any

abstractmethod zeros()#

Return the additive identity.

Return type:

Any

geometry: InnerProduct#
class spacecore.space.DenseCoordinateSpace(shape, ctx=None, geometry=None)[source]#

Bases: CoordinateSpace, InnerProductSpace

Concrete dense backend arrays with arbitrary finite coordinate shape.

Parameters:

  • shape (tuple of int) – Canonical dense array shape for one element.

  • ctx (Context, str, or None, optional) – Context specification used for dense arrays.

  • geometry (InnerProduct or None, optional) – Inner-product geometry. If omitted, Euclidean coordinate geometry is used.

geometry: InnerProduct#
zeros()[source]#

Return the zero vector in this space.

Return type:

DenseArray

add(x, y)[source]#

Return the vector-space sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

add_batch(x, y)[source]#

Return the leading-axis batch sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

scale(a, x)[source]#

Return the scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

scale_batch(a, x)[source]#

Return the leading-axis batch scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

inner(x, y)[source]#

Return \(\langle x, y\rangle_X\) using this space’s geometry.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

flatten(X)[source]#

Return X as a dense one-dimensional coordinate vector.

Parameters:

X (DenseArray)

Return type:

DenseArray

unflatten(v)[source]#

Reshape a flat coordinate vector into this space’s canonical shape.

Parameters:

v (DenseArray)

Return type:

DenseArray

flatten_batch(xs)[source]#

Flatten a leading-axis batch of dense elements to (N, size).

Parameters:

xs (DenseArray)

Return type:

DenseArray

unflatten_batch(vs)[source]#

Unflatten rows of shape (N, size) into dense space elements.

Parameters:

vs (DenseArray)

Return type:

DenseArray

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

property is_euclidean: bool#
member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

norm(x)#
Parameters:

x (Any)

Return type:

Any

riesz(x)#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)#
Parameters:

x (Any)

Return type:

Any

property size: int#

Return the flat coordinate dimension of this space.

stacked(count)#

Return count leading-axis copies of this leaf space as one space.

Parameters:

count (int)

Return type:

CoordinateSpace

shape: Tuple[int, ...]#
class spacecore.space.DenseVectorSpace(shape, ctx=None, geometry=None)[source]#

Bases: DenseCoordinateSpace, StarSpace

Plain one-dimensional dense vectors with no Jordan capability by default.

Parameters:

  • shape (tuple of int) – One-dimensional dense vector shape.

  • ctx (Context, str, or None, optional) – Context specification used for dense arrays.

  • geometry (InnerProduct or None, optional) – Inner-product geometry. If omitted, Euclidean coordinate geometry is used.

star(x)[source]#

Return elementwise conjugation.

Parameters:

x (DenseArray)

Return type:

DenseArray

add(x, y)#

Return the vector-space sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

add_batch(x, y)#

Return the leading-axis batch sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

flatten(X)#

Return X as a dense one-dimensional coordinate vector.

Parameters:

X (DenseArray)

Return type:

DenseArray

flatten_batch(xs)#

Flatten a leading-axis batch of dense elements to (N, size).

Parameters:

xs (DenseArray)

Return type:

DenseArray

inner(x, y)#

Return \(\langle x, y\rangle_X\) using this space’s geometry.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

property is_euclidean: bool#
member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

norm(x)#
Parameters:

x (Any)

Return type:

Any

riesz(x)#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)#
Parameters:

x (Any)

Return type:

Any

scale(a, x)#

Return the scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

scale_batch(a, x)#

Return the leading-axis batch scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

property size: int#

Return the flat coordinate dimension of this space.

stacked(count)#

Return count leading-axis copies of this leaf space as one space.

Parameters:

count (int)

Return type:

CoordinateSpace

unflatten(v)#

Reshape a flat coordinate vector into this space’s canonical shape.

Parameters:

v (DenseArray)

Return type:

DenseArray

unflatten_batch(vs)#

Unflatten rows of shape (N, size) into dense space elements.

Parameters:

vs (DenseArray)

Return type:

DenseArray

zeros()#

Return the zero vector in this space.

Return type:

DenseArray

geometry: InnerProduct#
shape: Tuple[int, ...]#
class spacecore.space.ElementwiseJordanSpace(shape, ctx=None, geometry=None, *, inner_product=None)[source]#

Bases: JordanAlgebraSpace, DenseCoordinateSpace, StarSpace

Elementwise Jordan algebra for real or complex dense coordinates.

Parameters:

  • shape (tuple of int) – Canonical dense array shape for one element.

  • ctx (Context, str, or None, optional) – Context specification used for dense arrays.

  • geometry (InnerProduct or None, optional) – Inner-product geometry. If omitted, Euclidean coordinate geometry is used.

  • inner_product (InnerProduct or None, optional) – Alias for geometry.

star(x)[source]#

Return elementwise conjugation.

Parameters:

x (DenseArray)

Return type:

DenseArray

jordan(x, y)[source]#

Return the elementwise Jordan product.

Parameters:

  • x (DenseArray)

  • y (DenseArray)

Return type:

DenseArray

spectrum(x)[source]#

Return x as its Jordan spectrum under elementwise product.

Parameters:

x (DenseArray)

Return type:

DenseArray

spectral_decompose(x)[source]#

Return the trivial spectral decomposition (x, None).

Parameters:

x (DenseArray)

Return type:

tuple[DenseArray, None]

from_spectrum(eigvals, frame=None)[source]#

Reconstruct an elementwise Jordan element from its spectrum.

Parameters:

  • eigvals (DenseArray)

  • frame (Any)

Return type:

DenseArray

trace(x)[source]#

Return the Jordan trace as the sum over the element’s own coordinates.

Parameters:

x (DenseArray)

Return type:

DenseArray

determinant(x)[source]#

Return the Jordan determinant as the product over the coordinates.

Parameters:

x (DenseArray)

Return type:

DenseArray

unit()[source]#

Return the Jordan identity: the all-ones element in the space dtype.

Return type:

DenseArray

spectral_apply(x, f)[source]#

Apply a scalar function coordinatewise.

Parameters:

  • x (DenseArray)

  • f (Callable[[DenseArray], DenseArray])

Return type:

DenseArray

add(x, y)#

Return the vector-space sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

add_batch(x, y)#

Return the leading-axis batch sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

flatten(X)#

Return X as a dense one-dimensional coordinate vector.

Parameters:

X (DenseArray)

Return type:

DenseArray

flatten_batch(xs)#

Flatten a leading-axis batch of dense elements to (N, size).

Parameters:

xs (DenseArray)

Return type:

DenseArray

inner(x, y)#

Return \(\langle x, y\rangle_X\) using this space’s geometry.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

property is_euclidean: bool#
member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

norm(x)#
Parameters:

x (Any)

Return type:

Any

riesz(x)#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)#
Parameters:

x (Any)

Return type:

Any

scale(a, x)#

Return the scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

scale_batch(a, x)#

Return the leading-axis batch scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

property size: int#

Return the flat coordinate dimension of this space.

stacked(count)#

Return count leading-axis copies of this leaf space as one space.

Parameters:

count (int)

Return type:

CoordinateSpace

unflatten(v)#

Reshape a flat coordinate vector into this space’s canonical shape.

Parameters:

v (DenseArray)

Return type:

DenseArray

unflatten_batch(vs)#

Unflatten rows of shape (N, size) into dense space elements.

Parameters:

vs (DenseArray)

Return type:

DenseArray

zeros()#

Return the zero vector in this space.

Return type:

DenseArray

geometry: InnerProduct#
shape: Tuple[int, ...]#
class spacecore.space.EuclideanElementwiseJordanSpace(shape, ctx=None, geometry=None, *, inner_product=None)[source]#

Bases: ElementwiseJordanSpace, EuclideanJordanAlgebraSpace

Real elementwise Euclidean Jordan algebra.

Parameters:

  • shape (tuple of int) – Canonical dense array shape for one element.

  • ctx (Context, str, or None, optional) – Context specification used for dense arrays.

  • geometry (InnerProduct or None, optional) – Inner-product geometry. This class is selected only for real contexts with Euclidean coordinate geometry.

  • inner_product (InnerProduct or None, optional) – Alias for geometry.

add(x, y)#

Return the vector-space sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

add_batch(x, y)#

Return the leading-axis batch sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

determinant(x)#

Return the Jordan determinant as the product over the coordinates.

Parameters:

x (DenseArray)

Return type:

DenseArray

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

flatten(X)#

Return X as a dense one-dimensional coordinate vector.

Parameters:

X (DenseArray)

Return type:

DenseArray

flatten_batch(xs)#

Flatten a leading-axis batch of dense elements to (N, size).

Parameters:

xs (DenseArray)

Return type:

DenseArray

from_spectrum(eigvals, frame=None)#

Reconstruct an elementwise Jordan element from its spectrum.

Parameters:

  • eigvals (DenseArray)

  • frame (Any)

Return type:

DenseArray

inner(x, y)#

Return \(\langle x, y\rangle_X\) using this space’s geometry.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

property is_euclidean: bool#
jordan(x, y)#

Return the elementwise Jordan product.

Parameters:

  • x (DenseArray)

  • y (DenseArray)

Return type:

DenseArray

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

norm(x)#
Parameters:

x (Any)

Return type:

Any

riesz(x)#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)#
Parameters:

x (Any)

Return type:

Any

scale(a, x)#

Return the scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

scale_batch(a, x)#

Return the leading-axis batch scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

property size: int#

Return the flat coordinate dimension of this space.

spectral_apply(x, f)#

Apply a scalar function coordinatewise.

Parameters:

  • x (DenseArray)

  • f (Callable[[DenseArray], DenseArray])

Return type:

DenseArray

spectral_decompose(x)#

Return the trivial spectral decomposition (x, None).

Parameters:

x (DenseArray)

Return type:

tuple[DenseArray, None]

spectrum(x)#

Return x as its Jordan spectrum under elementwise product.

Parameters:

x (DenseArray)

Return type:

DenseArray

stacked(count)#

Return count leading-axis copies of this leaf space as one space.

Parameters:

count (int)

Return type:

CoordinateSpace

star(x)#

Return elementwise conjugation.

Parameters:

x (DenseArray)

Return type:

DenseArray

trace(x)#

Return the Jordan trace as the sum over the element’s own coordinates.

Parameters:

x (DenseArray)

Return type:

DenseArray

unflatten(v)#

Reshape a flat coordinate vector into this space’s canonical shape.

Parameters:

v (DenseArray)

Return type:

DenseArray

unflatten_batch(vs)#

Unflatten rows of shape (N, size) into dense space elements.

Parameters:

vs (DenseArray)

Return type:

DenseArray

unit()#

Return the Jordan identity: the all-ones element in the space dtype.

Return type:

DenseArray

zeros()#

Return the zero vector in this space.

Return type:

DenseArray

geometry: InnerProduct#
shape: Tuple[int, ...]#
class spacecore.space.HermitianSpace(n, atol=0.0, rtol=0.0, enforce_herm=True, ctx=None)[source]#

Bases: DenseCoordinateSpace, StarSpace, EuclideanJordanAlgebraSpace

Represent dense Hermitian matrices with Frobenius geometry.

Elements are backend-native dense arrays with shape (n, n). Membership enforces Hermitian structure up to tolerances.

The inner product is Frobenius / Hilbert-Schmidt: <X, Y> = vdot(vec(X), vec(Y)), where vdot conjugates the first argument according to backend rules.

HermitianSpace currently uses Euclidean/Frobenius geometry in flattened coordinates and does not expose custom geometry injection. Metric-aware Hermitian geometries should be introduced as a separate class or explicit extension.

Parameters:

  • n (int) – Matrix dimension.

  • atol (float, optional) – Absolute tolerance for Hermitian membership checks.

  • rtol (float, optional) – Relative tolerance for Hermitian membership checks.

  • enforce_herm (bool, optional) – Whether membership checks enforce Hermitian structure.

  • ctx (Context, str, or None, optional) – Backend context specification.

n#

Matrix dimension.

Type:

int

is_hermitian(x)[source]#

Return whether x satisfies this space’s Hermitian check.

Parameters:

x (DenseArray)

Return type:

bool

symmetrize(x)[source]#

Project x onto the Hermitian subspace as \((X + X^*) / 2\).

Parameters:

x (DenseArray)

Return type:

DenseArray

star(x)[source]#

Return the canonical star operation for Hermitian elements: identity.

Parameters:

x (DenseArray)

Return type:

DenseArray

jordan(x, y)[source]#

Return the Hermitian Jordan product (xy + yx) / 2.

Parameters:

  • x (DenseArray)

  • y (DenseArray)

Return type:

DenseArray

spectrum(x)[source]#

Return the Hermitian eigenvalue spectrum of x.

Parameters:

x (DenseArray)

Return type:

DenseArray

spectral_decompose(x)[source]#

Return the Hermitian eigendecomposition (evals, evecs).

Parameters:

x (DenseArray)

Return type:

Tuple[DenseArray, DenseArray]

from_spectrum(eigvals, frame)[source]#

Reconstruct a Hermitian element from eigenvalues and eigenvectors.

Parameters:

  • eigvals (DenseArray)

  • frame (DenseArray)

Return type:

DenseArray

trace(x)[source]#

Return the (real) trace as the diagonal sum, avoiding an eigendecomposition.

'...ii->...' sums the trailing-two-axes diagonal and preserves leading batch axes; ops.trace/ops.diagonal default to the first two axes and are not batch-safe for (..., n, n) input.

Parameters:

x (DenseArray)

Return type:

DenseArray

unit()[source]#

Return the Jordan identity: the n x n identity in the space dtype.

Return type:

DenseArray

unflatten(v)[source]#

Reshape dense coordinates and symmetrize the result.

Parameters:

v (DenseArray)

Return type:

DenseArray

psd_proj(x)[source]#

Project a Hermitian element onto the positive semidefinite cone.

Parameters:

x (DenseArray)

Return type:

DenseArray

eig_to_dense(evals, evecs)[source]#

Reconstruct a Hermitian matrix from eigenvalues and eigenvectors.

The U diag(evals) U^* reconstruction is mathematically Hermitian but accumulates floating-point skew at the level of a few ULP, which a zero-tolerance Hermitian space would otherwise reject. Symmetrizing projects onto the Hermitian part (a no-op up to that skew) so the reconstruction is a valid member of this space.

Parameters:

  • evals (DenseArray)

  • evecs (DenseArray)

Return type:

DenseArray

spectral_apply(x, f)[source]#

Apply a scalar function to a Hermitian matrix via spectral calculus.

For a Hermitian matrix $$ X in mathbb{H}^n, $$ with eigendecomposition $$ X = U operatorname{diag}(lambda) U^*, $$ this method returns $$ f(X) = U operatorname{diag}(f(lambda)) U^*, $$ where f is applied entrywise to the eigenvalue vector $$ lambda in mathbb{R}^n. $$

Parameters:

  • x (DenseArray) – Hermitian matrix in this space. Must have shape (n, n) and satisfy the Hermitian membership conditions of the space.

  • f (Callable[[DenseArray], DenseArray]) – Callable applied to the eigenvalues of x. It should accept a dense backend array of eigenvalues and return an array of the same shape.

Returns:

The Hermitian matrix obtained by spectral application of f to x.

Return type:

DenseArray

Raises:

TypeError – If x is not a valid Hermitian element of this space.

Notes

This is not an entrywise matrix transformation. The function is applied to the spectrum of x, not to its matrix entries.

In particular, if $$ X = U operatorname{diag}(lambda) U^*, $$ then the eigenvectors are preserved and only the eigenvalues are transformed.

add(x, y)#

Return the vector-space sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

add_batch(x, y)#

Return the leading-axis batch sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

determinant(x)#

Return the Jordan determinant prod_i lambda_i(x) of the spectrum.

Parameters:

x (Any)

Return type:

Any

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

flatten(X)#

Return X as a dense one-dimensional coordinate vector.

Parameters:

X (DenseArray)

Return type:

DenseArray

flatten_batch(xs)#

Flatten a leading-axis batch of dense elements to (N, size).

Parameters:

xs (DenseArray)

Return type:

DenseArray

inner(x, y)#

Return \(\langle x, y\rangle_X\) using this space’s geometry.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

property is_euclidean: bool#
member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

norm(x)#
Parameters:

x (Any)

Return type:

Any

riesz(x)#
Parameters:

x (Any)

Return type:

Any

riesz_inverse(x)#
Parameters:

x (Any)

Return type:

Any

scale(a, x)#

Return the scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

scale_batch(a, x)#

Return the leading-axis batch scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

property size: int#

Return the flat coordinate dimension of this space.

stacked(count)#

Return count leading-axis copies of this leaf space as one space.

Parameters:

count (int)

Return type:

CoordinateSpace

unflatten_batch(vs)#

Unflatten rows of shape (N, size) into dense space elements.

Parameters:

vs (DenseArray)

Return type:

DenseArray

zeros()#

Return the zero vector in this space.

Return type:

DenseArray

geometry: InnerProduct#
shape: Tuple[int, ...]#
class spacecore.space.TreeSpace(treedef, leaf_spaces, *, ctx=None, check_level=None)[source]#

Bases: CoordinateSpace

Represent a finite direct product as a Python tree.

TreeSpace represents \(X = \prod_{\ell \in L} X_\ell\), where each leaf space \(X_\ell\) is a finite-coordinate SpaceCore space. The optree definition records the Python organization of an element; it does not define a tensor product. Tuple, list, dictionary, named-tuple, and registered optree structures are supported.

Parameters:

  • treedef (optree.PyTreeSpec or tree) – Immutable structure definition or example tree. Its deterministic leaf order is paired with leaf_spaces.

  • leaf_spaces (sequence of CoordinateSpace) – Nonempty ordered spaces for the tree leaves.

  • ctx (Context, str, or None, optional) – Backend context. If omitted, it is resolved from leaf_spaces.

  • check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation policy override. Leaf backend, dtype, field, and shape checks retain their normal minimum levels.

treedef#

Tree structure independent of element values.

Type:

optree.PyTreeSpec

leaf_spaces#

Ordered leaf spaces converted to ctx.

Type:

tuple of CoordinateSpace

leaf_paths#

Deterministic paths corresponding to leaf_spaces.

Type:

tuple of tuple

shape#

Dense coordinate shape (sum(leaf.size),).

Type:

tuple of int

Raises:

  • TypeError – If leaf_spaces is not a sequence of coordinate spaces.

  • ValueError – If there are no leaf spaces or the tree leaf count does not match.

Parameters:

  • treedef (optree.PyTreeSpec | Any)

  • leaf_spaces (Sequence[CoordinateSpace])

  • ctx (Context | str | None)

  • check_level (CheckLevel | str | None)

See also

TreeElement

Optional explicit binding of leaves to a TreeSpace.

Notes

Vector operations, conversion, validation, and batching are leafwise. Batches are trees of leaves with leading batch dimensions. The TreeSpace advertises inner-product, star, Jordan, and Euclidean-Jordan capabilities only when every leaf advertises the same mathematically valid capability. Leaf spaces are converted to one resolved context, so the TreeSpace field and representation dtype are inherited uniformly from those leaves. Each leaf performs the actual field and exact-dtype membership checks.

Examples

>>> import numpy as np
>>> import spacecore as sc
>>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
>>> X = sc.DenseCoordinateSpace((2,), ctx)
>>> S = sc.DenseCoordinateSpace((1,), ctx)
>>> T = sc.TreeSpace({"point": 0, "weight": 0}, (X, S), ctx=ctx)
>>> x = {"point": ctx.asarray([1.0, 2.0]), "weight": ctx.asarray([3.0])}
>>> T.flatten(x)
array([1., 2., 3.])
>>> T.scale(2.0, x)["point"]
array([2., 4.])
classmethod from_leaf_spaces(leaf_spaces, ctx=None, *, check_level=None)[source]#

Build a tuple-structured tree from ordered leaf spaces.

Parameters:

  • leaf_spaces (sequence of CoordinateSpace) – Nonempty ordered spaces for tuple leaves.

  • ctx (Context, str, or None, optional) – Backend context resolved from the leaves when omitted.

  • check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation policy override.

Returns:

Tuple-structured finite direct product.

Return type:

TreeSpace

classmethod from_template(template, leaf_spaces, *, ctx=None, check_level=None)[source]#

Build a tree space from an example Python tree value.

Parameters:

  • template (Any)

  • leaf_spaces (Sequence[CoordinateSpace])

  • ctx (Context | str | None)

  • check_level (Literal['none', 'cheap', 'standard', 'strict'] | str | None)

Return type:

TreeSpace

property arity: int#

Return the number of ordered leaves.

flatten_tree(value)[source]#

Flatten a matching Python tree value into ordered leaves.

Parameters:

value (Any)

Return type:

tuple[Any, …]

unflatten_tree(leaves)[source]#

Rebuild the configured Python tree from ordered leaves.

Parameters:

leaves (Sequence[Any])

Return type:

Any

element(value)[source]#

Bind a matching Python tree value to this space.

Parameters:

value (Any)

Return type:

TreeElement

zero()[source]#

Return the additive identity.

Return type:

Any

zeros()[source]#

Return the leafwise additive identity.

Return type:

Any

ones()[source]#

Return a leafwise all-ones element when leaf spaces support it.

Return type:

Any

add(x, y)[source]#

Return the componentwise sum.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

add_batch(x, y)[source]#

Return the componentwise leading-axis batch sum.

Parameters:

  • x (Any)

  • y (Any)

Return type:

Any

scale(a, x)[source]#

Return the componentwise scalar product.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

scale_batch(a, x)[source]#

Return the componentwise batched scalar product.

Parameters:

  • a (Any)

  • x (Any)

Return type:

Any

stacked(count)[source]#

Return a tree whose leaves are stacked leaf spaces.

Parameters:

count (int)

Return type:

TreeSpace

flatten(x)[source]#

Concatenate leaf coordinate vectors into one dense vector.

Parameters:

x (Any)

Return type:

DenseArray

unflatten(v)[source]#

Split dense coordinates into a tree element.

Parameters:

v (DenseArray)

Return type:

Any

flatten_batch(xs)[source]#

Concatenate batched leaf coordinates into shape (N, size).

Parameters:

xs (Any)

Return type:

DenseArray

unflatten_batch(vs)[source]#

Split batched dense coordinates into batched leaves.

Parameters:

vs (DenseArray)

Return type:

Any

check(x)[source]#

Validate an element according to this space’s check level.

Parameters:

x (Any)

Return type:

None

convert_element(x, new_ctx=None)[source]#

Convert each leaf and preserve the configured tree structure.

Parameters:

  • x (Any)

  • new_ctx (Context | str | None)

Return type:

Any

tree_flatten()[source]#

Flatten this space as static JAX pytree data.

classmethod tree_unflatten(aux, children)[source]#

Rebuild this space from JAX pytree auxiliary data.

Parameters:

  • aux (Any)

  • children (Sequence[Any])

Return type:

TreeSpace

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property ctx: Context#

Return the execution context bound to this object.

property dtype: Any#

Return the default dtype associated with this object’s context.

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

property ops: BackendOps#

Return backend operations associated with this object’s context.

property size: int#

Return the flat coordinate dimension of this space.

class spacecore.space.TreeElement(space, leaves)[source]#

Bases: object

Bind ordered leaves to a TreeSpace.

TreeElement is an explicit binding helper. Ordinary tuple, list, dictionary, named-tuple, and registered optree values with the configured structure are also valid TreeSpace elements.

Parameters:

  • space (TreeSpace) – Finite direct-product space that defines leaf order and structure.

  • leaves (sequence) – Leaf values in space.leaf_paths order.

space#

Bound tree space.

Type:

TreeSpace

leaves#

Ordered leaf values.

Type:

tuple

Raises:

  • TypeError – If space is not a TreeSpace.

  • ValueError – If the leaf count does not match space.arity.

Parameters:

Notes

The wrapper does not coerce leaf backend, dtype, field, or shape. Those contracts are inherited from the leaf spaces and enforced by TreeSpace.check() according to space.check_level.

Examples

>>> import numpy as np
>>> import spacecore as sc
>>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
>>> X = sc.DenseCoordinateSpace((1,), ctx)
>>> T = sc.TreeSpace((0, 0), (X, X), ctx=ctx)
>>> element = sc.TreeElement(T, (ctx.asarray([1.0]), ctx.asarray([2.0])))
>>> element.value
(array([1.]), array([2.]))
property value: Any#

Reconstruct the Python tree value represented by this element.

tree_flatten()[source]#

Expose element leaves as JAX pytree children.

classmethod tree_unflatten(space, children)[source]#

Rebuild an element from JAX pytree children.

Parameters:
Return type:

TreeElement

class spacecore.space.TreeSpectralDecomposition(eigvals, frames, treedef=None)[source]#

Bases: object

Store leafwise Jordan spectral data in deterministic leaf order.

Parameters:

  • eigvals (tuple) – Eigenvalue data for each TreeSpace leaf.

  • frames (tuple) – Spectral frame data for each TreeSpace leaf.

  • treedef (optree.PyTreeSpec or None, optional) – The producing space’s treedef, tagged on by TreeSpace.spectral_decompose() so to_tree() can expose the eigenvalues in the tree’s own structure. None for hand-built decompositions.

Notes

treedef is static JAX pytree aux, so decompositions combined in a single jax.lax.cond / while_loop must all be tagged (or all None); otherwise JAX raises a pytree-structure mismatch.

eigvals: tuple[Any, ...]#
frames: tuple[Any, ...]#
treedef: Any = None#
to_tree()[source]#

Return the eigenvalues as a pytree matching the space treedef.

The result mirrors the tree structure (nested for a nested tree), each leaf holding that leaf’s eigenvalue vector. It is a structure-only view: the leaves are eigenvalue-shaped, so it is not a member of the space and must not be fed back into space operations. Requires treedef (set on decompositions produced by TreeSpace.spectral_decompose()).

Return type:

Any

class spacecore.space.StackedSpace(base, count, ctx=None)[source]#

Bases: CoordinateSpace

Leading-axis copies of a coordinate leaf space.

Baseline StackedSpace exposes only coordinate-space operations. Direct construction dispatches to a more specific class that preserves the base space’s inner-product, star, Jordan, and Euclidean-Jordan capabilities.

Parameters:

  • base (Space) – Coordinate leaf space to repeat along a leading axis.

  • count (int) – Number of leading-axis copies.

  • ctx (Context, str, or None, optional) – Context specification. If omitted, the context is resolved from base.

zeros()[source]#

Return the stacked zero element.

Return type:

DenseArray

ones()[source]#

Return the stacked all-ones element.

Return type:

DenseArray

add(x, y)[source]#

Return the stacked sum x + y.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

add_batch(x, y)[source]#

Return the leading-axis batch sum of stacked elements.

Parameters:

  • x (Any)

  • y (Any)

Return type:

DenseArray

scale(a, x)[source]#

Return the stacked scalar product a * x.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

scale_batch(a, x)[source]#

Return the leading-axis batch scalar product of stacked elements.

Parameters:

  • a (Any)

  • x (Any)

Return type:

DenseArray

flatten(x)[source]#

Flatten the whole stacked element to one coordinate vector.

Parameters:

x (Any)

Return type:

DenseArray

unflatten(v)[source]#

Unflatten one coordinate vector to the stacked element shape.

Parameters:

v (DenseArray)

Return type:

DenseArray

flatten_batch(xs)[source]#

Flatten a batch of stacked elements to (N, count * base.size).

Parameters:

xs (DenseArray)

Return type:

DenseArray

unflatten_batch(vs)[source]#

Unflatten rows to a batch of stacked elements.

Parameters:

vs (DenseArray)

Return type:

DenseArray

stacked(count)[source]#

Return a flattened stack of this stack: base.stacked(count * k).

Parameters:

count (int)

Return type:

StackedSpace

axpy(a, x, y)#

Return a*x + y.

Parameters:

  • a (Any)

  • x (Any)

  • y (Any)

Return type:

Any

property check_level: Literal['none', 'cheap', 'standard', 'strict']#

Return this object’s runtime validation level.

check_member(x)#
Parameters:

x (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()#
convert(new_ctx=None)#

Return this object represented in new_ctx.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property field: Literal['real', 'complex']#

Return the mathematical scalar field derived from the context dtype.

Context.dtype controls array representation. This property records only whether the space is over the real or complex scalar field.

member_checks()#

Return every SpaceCheck this instance must satisfy.

Walks the MRO and collects checks class attributes plus any instance-state-driven _local_checks factories. The result is cached on first access because spaces are immutable post-init. Subclasses that depend on mutable state (none in 0.4.0) must clear self._cached_member_checks themselves.

Return type:

tuple[SpaceCheck, …]

property size: int#

Return the flat coordinate dimension of this space.

shape: Tuple[int, ...]#
class spacecore.space.SpaceValidationError[source]#

Bases: ValueError, TypeError

Raised when an object is not a member of a space.

add_note()#

Exception.add_note(note) – add a note to the exception

args#
with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class spacecore.space.SpaceCheck(name)[source]#

Bases: ABC

Define a membership check for Space objects.

Parameters:

name (str) – Human-readable check name used in diagnostics.

name: str#
core_rank: ClassVar[int] = 0#
enforce_core_shape: ClassVar[bool] = False#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'standard'#
core_shape(space)[source]#

Return the trailing shape that defines one element for this check.

Parameters:

space (Any)

Return type:

tuple[int, …]

leading_dims(x, space)[source]#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)[source]#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

validation_message(space, x, *, allow_leading)[source]#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

abstractmethod is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

abstractmethod error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

class spacecore.space.BackendCheck(name='backend')[source]#

Bases: SpaceCheck

Check that a value is a dense array for a space backend.

Parameters:

name (str, optional) – Check name. Default is "backend".

name: str = 'backend'#
core_rank: ClassVar[int] = 0#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'#
is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

core_shape(space)#

Return the trailing shape that defines one element for this check.

Parameters:

space (Any)

Return type:

tuple[int, …]

enforce_core_shape: ClassVar[bool] = False#
leading_dims(x, space)#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

validation_message(space, x, *, allow_leading)#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

class spacecore.space.ShapeCheck(name='shape')[source]#

Bases: SpaceCheck

Check that a value has the canonical shape of a space.

Parameters:

name (str, optional) – Check name. Default is "shape".

name: str = 'shape'#
enforce_core_shape: ClassVar[bool] = True#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'#
core_shape(space)[source]#

Return the whole canonical shape as the trailing element shape.

Parameters:

space (Any)

Return type:

tuple[int, …]

is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

validation_message(space, x, *, allow_leading)[source]#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

core_rank: ClassVar[int] = 0#
leading_dims(x, space)#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

class spacecore.space.FieldCheck(name='field')[source]#

Bases: SpaceCheck

Check that a value is compatible with a space’s mathematical field.

Parameters:

name (str, optional) – Identifier for this check. Default is "field".

name: str = 'field'#
core_rank: ClassVar[int] = 0#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'#
is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

core_shape(space)#

Return the trailing shape that defines one element for this check.

Parameters:

space (Any)

Return type:

tuple[int, …]

enforce_core_shape: ClassVar[bool] = False#
leading_dims(x, space)#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

validation_message(space, x, *, allow_leading)#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

class spacecore.space.DTypeCheck(name='dtype')[source]#

Bases: SpaceCheck

Check that a value has the dtype required by a space context.

Parameters:

name (str, optional) – Check name. Default is "dtype".

name: str = 'dtype'#
core_rank: ClassVar[int] = 0#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'#
is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

core_shape(space)#

Return the trailing shape that defines one element for this check.

Parameters:

space (Any)

Return type:

tuple[int, …]

enforce_core_shape: ClassVar[bool] = False#
leading_dims(x, space)#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

validation_message(space, x, *, allow_leading)#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

class spacecore.space.SquareMatrixCheck(name='square_matrix')[source]#

Bases: SpaceCheck

Check that a value has square trailing matrix axes.

Parameters:

name (str, optional) – Check name. Default is "square_matrix".

name: str = 'square_matrix'#
core_rank: ClassVar[int] = 2#
enforce_core_shape: ClassVar[bool] = True#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'#
is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

core_shape(space)#

Return the trailing shape that defines one element for this check.

Parameters:

space (Any)

Return type:

tuple[int, …]

leading_dims(x, space)#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

validation_message(space, x, *, allow_leading)#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

class spacecore.space.HermitianCheck(name='hermitian', atol=1e-08, rtol=1e-08, enforce=True)[source]#

Bases: SpaceCheck

Check that a value is Hermitian within tolerances.

Parameters:

  • name (str, optional) – Check name. Default is "hermitian".

  • atol (float, optional) – Absolute tolerance for Hermitian comparison.

  • rtol (float, optional) – Relative tolerance for Hermitian comparison.

  • enforce (bool, optional) – Whether to enforce the Hermitian comparison.

name: str = 'hermitian'#
core_rank: ClassVar[int] = 2#
enforce_core_shape: ClassVar[bool] = True#
minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'standard'#
atol: float = 1e-08#
rtol: float = 1e-08#
enforce: bool = True#
is_valid(space, x)[source]#

Return whether x is valid for space.

Parameters:

  • space (Any)

  • x (Any)

Return type:

bool

error_message(space, x)[source]#

Return a diagnostic for an invalid x.

Parameters:

  • space (Any)

  • x (Any)

Return type:

str

core_shape(space)#

Return the trailing shape that defines one element for this check.

Parameters:

space (Any)

Return type:

tuple[int, …]

leading_dims(x, space)#

Return leading batch dimensions before this check’s core axes.

Parameters:

  • x (Any)

  • space (Any)

Return type:

tuple[int, …] | None

validate(space, x, *, allow_leading)#

Return whether x is valid under member or batched shape policy.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

bool

validation_message(space, x, *, allow_leading)#

Return a diagnostic for an invalid validation result.

Parameters:

  • space (Any)

  • x (Any)

  • allow_leading (bool)

Return type:

str

On this page
Show Source