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	One-dimensional dense vectors, without Jordan structure by default.

Structured spaces

spacecore.space.HermitianSpace	Dense n x n Hermitian matrices with the Frobenius inner product.
spacecore.space.TreeSpace	Finite direct product \(\prod_\ell X_\ell\) whose elements are Python trees.
spacecore.space.TreeElement	Leaves bound to a TreeSpace; plain trees of the right structure work too.
spacecore.space.TreeSpectralDecomposition	Leafwise Jordan spectral data, in leaf order.
spacecore.space.StackedSpace	count leading-axis copies of a coordinate space; operations vmap over the copies.

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

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.OperatorInnerProduct	Operator-metric geometry \(\langle x, y\rangle = \langle x, M y\rangle_E\).
spacecore.space.InnerProductSpace	Vector space capability with an inner-product geometry.

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	Dense coordinates with the elementwise Jordan product, real or complex.
spacecore.space.EuclideanElementwiseJordanSpace	Real elementwise Jordan algebra with Euclidean geometry, selected automatically for that case.

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, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

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, …]

check_member(x)

Parameters:

x (Any)

Return type:

None

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

Return this object’s runtime validation level.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

class spacecore.space.VectorSpace(ctx=None, check_level=None)

Bases: Space

Abstract vector-space capability: linear operations only.

A family implements the check-free cores _add_core and _scale_core; the public add and scale wrap them with membership checks.

Parameters:

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

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

abstractmethod zeros()

Return the additive identity.

Return type:

Any

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

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, …]

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

class spacecore.space.CoordinateSpace(shape, ctx=None, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

shape: Tuple[int, ...]

property size: int

Return the flat coordinate dimension of this space.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

flatten_batch(xs)

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

Parameters:

xs (Any)

Return type:

DenseArray

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

add_batch(x, y)

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

Parameters:

• x (Any)

• y (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• x (Any)

Return type:

Any

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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

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, …]

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

stacked(count)

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

Bases: ABC

Geometry of a space: inner product plus Riesz maps.

An orthonormal basis gives a representer for each linear functional (Horn & Johnson, Matrix Analysis, 2nd ed., Sec. 0.6.5). In coordinates, <x, y> = x^H R y with positive-definite Gram matrix R; riesz(x) = R x stores the column in <x, y> = (R x)^H y.

abstractmethod inner(ops, x, y)

Return the inner product of x and y.

riesz(ops, x)

Map an element to its dual; non-Euclidean geometry must implement this.

riesz_inverse(ops, x)

Invert the Riesz map; non-Euclidean geometry must implement this.

convert(ctx)

Return this geometry represented in ctx when conversion is needed.

validate_for(space)

Raise if this inner product is invalid for space.

Parameters:

space (InnerProductSpace)

Return type:

None

is_euclidean = False

Whether this geometry is the Euclidean coordinate inner product.

property has_riesz_maps: bool

Whether both Riesz maps are available, so metric adjoints can be formed.

class spacecore.space.EuclideanInnerProduct

Bases: InnerProduct

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

is_euclidean = True

Whether this geometry is the Euclidean coordinate inner product.

inner(ops, x, y)

Return the inner product of x and y.

riesz(ops, x)

Return the Euclidean representer unchanged.

riesz_inverse(ops, x)

Return the Euclidean covector unchanged.

convert(ctx)

Return this geometry represented in ctx when conversion is needed.

property has_riesz_maps: bool

Whether both Riesz maps are available, so metric adjoints can be formed.

validate_for(space)

Raise if this inner product is invalid for space.

Parameters:

space (InnerProductSpace)

Return type:

None

class spacecore.space.WeightedInnerProduct(weights)

Bases: InnerProduct

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

Parameters:

weights (array-like) – Positive, finite diagonal weights in the context dtype, with a shape that broadcasts to the coordinate-space shape (a 0-d array gives a scaled Euclidean metric). Values are checked from standard checks upward.

inner(ops, x, y)

Return the inner product of x and y.

riesz(ops, x)

Map an element to its dual; non-Euclidean geometry must implement this.

riesz_inverse(ops, x)

Invert the Riesz map; non-Euclidean geometry must implement this.

convert(ctx)

Return this geometry represented in ctx when conversion is needed.

validate_for(space)

Validate diagonal weights against a coordinate space.

Parameters:

space (InnerProductSpace)

Return type:

None

property has_riesz_maps: bool

Whether both Riesz maps are available, so metric adjoints can be formed.

is_euclidean = False

Whether this geometry is the Euclidean coordinate inner product.

class spacecore.space.OperatorInnerProduct(M, M_inverse=None)

Bases: InnerProduct

Operator-metric geometry \(\langle x, y\rangle = \langle x, M y\rangle_E\).

M is a self-adjoint, positive-definite linear operator on the space’s Euclidean coordinates: block, Kronecker, low-rank-plus-diagonal or any matrix-free metric. The Riesz map is M; its inverse is M_inverse, which may be any operator approximating it, such as one that runs sc.cg to a tolerance. Without M_inverse, riesz_inverse raises CapabilityError.

From standard checks upward, an M known to be non-self-adjoint, or with non-positive curvature on a fixed probe vector, is rejected; at strict, its Lanczos estimate of the smallest eigenvalue must also be positive.

Parameters:

• M (LinOp) – Self-adjoint positive-definite operator from the Euclidean coordinate space of the target space to itself.

• M_inverse (LinOp or None, optional) – Operator applying (an approximation of) the inverse of M.

inner(ops, x, y)

Return the inner product of x and y.

riesz(ops, x)

Map an element to its dual; non-Euclidean geometry must implement this.

property has_riesz_maps: bool

Whether both Riesz maps are available, so metric adjoints can be formed.

riesz_inverse(ops, x)

Invert the Riesz map; non-Euclidean geometry must implement this.

convert(ctx)

Return this geometry represented in ctx when conversion is needed.

validate_for(space)

Check that M (and M_inverse) act on the space’s Euclidean coordinates.

Parameters:

space (InnerProductSpace)

Return type:

None

is_euclidean = False

Whether this geometry is the Euclidean coordinate inner product.

class spacecore.space.InnerProductSpace(ctx=None, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

inner(x, y)

Return \(\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

norm(x)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

property is_euclidean: bool

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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

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, …]

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

abstractmethod zeros()

Return the additive identity.

Return type:

Any

class spacecore.space.StarSpace(ctx=None, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

star(x)

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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

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, …]

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

class spacecore.space.JordanAlgebraSpace(ctx=None, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

jordan(x, y)

Return the Jordan product of x and y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

spectrum(x, **kwargs)

Return Jordan-algebraic eigenvalues of x.

Parameters:

• x (Any)

• kwargs (Any)

Return type:

Any

spectral_decompose(x)

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

from_spectrum(eigvals, frame=None)

Reconstruct an element from spectral data.

Parameters:

• eigvals (Any)

• frame (Any)

Return type:

Any

spectral_apply(x, f)

Apply f to the spectrum of x and reconstruct.

Parameters:

• x (Any)

• f (Callable)

Return type:

Any

trace(x)

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

Parameters:

x (Any)

Return type:

Any

determinant(x)

Return the Jordan determinant prod_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

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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

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, …]

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

abstractmethod zeros()

Return the additive identity.

Return type:

Any

class spacecore.space.EuclideanJordanAlgebraSpace(ctx=None, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

determinant(x)

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

Parameters:

x (Any)

Return type:

Any

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

from_spectrum(eigvals, frame=None)

Reconstruct an element from spectral data.

Parameters:

• eigvals (Any)

• frame (Any)

Return type:

Any

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

inner(x, y)

Return \(\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

property is_euclidean: bool

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)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

spectral_apply(x, f)

Apply f to the spectrum of x and reconstruct.

Parameters:

• x (Any)

• f (Callable)

Return type:

Any

spectral_decompose(x)

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

spectrum(x, **kwargs)

Return Jordan-algebraic eigenvalues of x.

Parameters:

• x (Any)

• kwargs (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

class spacecore.space.DenseCoordinateSpace(shape, ctx=None, geometry=None, check_level=None)

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.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

axpy(a, x, y)

Return a*x + y.

Parameters:

• a (Any)

• x (Any)

• y (Any)

Return type:

Any

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

zeros()

Return the zero vector in this space.

Return type:

DenseArray

add_batch(x, y)

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

Parameters:

• x (Any)

• y (Any)

Return type:

Any

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

Return this object’s runtime validation level.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

Return type:

DenseArray

inner(x, y)

Return \(\langle x, y\rangle_X\).

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)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale_batch(a, x)

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

Parameters:

• a (Any)

• 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

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

shape: Tuple[int, ...]

class spacecore.space.DenseVectorSpace(shape, ctx=None, geometry=None, check_level=None)

Bases: DenseCoordinateSpace, StarSpace

One-dimensional dense vectors, without Jordan structure by default.

Parameters:

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

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

• geometry (InnerProduct or None, optional) – Inner product; Euclidean when omitted.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

add_batch(x, y)

Return the leading-axis batch sum of x and 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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

Return type:

DenseArray

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

inner(x, y)

Return \(\langle x, y\rangle_X\).

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)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• 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

star(x)

Return the canonical star/involution of x.

Parameters:

x (Any)

Return type:

Any

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

zeros()

Return the zero vector in this space.

Return type:

DenseArray

shape: Tuple[int, ...]

class spacecore.space.ElementwiseJordanSpace(shape, ctx=None, geometry=None, check_level=None, *, inner_product=None)

Bases: PyTreeNode, JordanAlgebraSpace, DenseCoordinateSpace, StarSpace

Dense coordinates with the elementwise Jordan product, real or complex.

Parameters:

• shape (tuple of int) – Element shape.

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

• geometry (InnerProduct or None, optional) – Inner product; Euclidean when omitted.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

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

unit()

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

Return type:

DenseArray

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

add_batch(x, y)

Return the leading-axis batch sum of x and 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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

determinant(x)

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

Parameters:

x (Any)

Return type:

Any

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

Return type:

DenseArray

from_spectrum(eigvals, frame=None)

Reconstruct an element from spectral data.

Parameters:

• eigvals (Any)

• frame (Any)

Return type:

Any

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

inner(x, y)

Return \(\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

property is_euclidean: bool

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)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• x (Any)

Return type:

Any

property size: int

Return the flat coordinate dimension of this space.

spectral_apply(x, f)

Apply f to the spectrum of x and reconstruct.

Parameters:

• x (Any)

• f (Callable)

Return type:

Any

spectral_decompose(x)

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

spectrum(x, **kwargs)

Return Jordan-algebraic eigenvalues of x.

Parameters:

• x (Any)

• kwargs (Any)

Return type:

Any

stacked(count)

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

Parameters:

count (int)

Return type:

CoordinateSpace

star(x)

Return the canonical star/involution 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

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

zeros()

Return the zero vector in this space.

Return type:

DenseArray

shape: Tuple[int, ...]

class spacecore.space.EuclideanElementwiseJordanSpace(shape, ctx=None, geometry=None, check_level=None, *, inner_product=None)

Bases: ElementwiseJordanSpace, EuclideanJordanAlgebraSpace

Real elementwise Jordan algebra with Euclidean geometry, selected automatically for that case.

Parameters:

• shape (tuple of int) – Element shape.

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

• geometry (InnerProduct or None, optional) – Inner product; Euclidean when omitted.

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

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

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

add_batch(x, y)

Return the leading-axis batch sum of x and 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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

determinant(x)

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

Parameters:

x (Any)

Return type:

Any

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

Return type:

DenseArray

from_spectrum(eigvals, frame=None)

Reconstruct an element from spectral data.

Parameters:

• eigvals (Any)

• frame (Any)

Return type:

Any

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

inner(x, y)

Return \(\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

property is_euclidean: bool

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)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• x (Any)

Return type:

Any

property size: int

Return the flat coordinate dimension of this space.

spectral_apply(x, f)

Apply f to the spectrum of x and reconstruct.

Parameters:

• x (Any)

• f (Callable)

Return type:

Any

spectral_decompose(x)

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

spectrum(x, **kwargs)

Return Jordan-algebraic eigenvalues of x.

Parameters:

• x (Any)

• kwargs (Any)

Return type:

Any

stacked(count)

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

Parameters:

count (int)

Return type:

CoordinateSpace

star(x)

Return the canonical star/involution 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

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

unit()

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

Return type:

DenseArray

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

zeros()

Return the zero vector in this space.

Return type:

DenseArray

shape: Tuple[int, ...]

class spacecore.space.HermitianSpace(n, atol=0.0, rtol=0.0, enforce_herm=True, ctx=None, check_level=None)

Bases: DenseCoordinateSpace, StarSpace, EuclideanJordanAlgebraSpace

Dense n x n Hermitian matrices with the Frobenius inner product.

A real vector space: scaling by a non-real number is rejected. Membership checks Hermitian structure up to atol/rtol. Horn & Johnson, Matrix Analysis, 2nd ed., Thm 4.1.5 (spectral decomposition).

Parameters:

• n (int) – Matrix dimension.

• atol (float, optional) – Absolute tolerance of the Hermitian check.

• rtol (float, optional) – Relative tolerance of the Hermitian check.

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

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

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = 'real'

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

is_hermitian(x)

Return whether x satisfies this space’s Hermitian check.

Parameters:

x (DenseArray)

Return type:

bool

symmetrize(x)

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

Parameters:

x (DenseArray)

Return type:

DenseArray

unit()

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

Return type:

DenseArray

psd_proj(x)

Project onto the PSD cone in Frobenius norm by clipping negative eigenvalues.

Horn & Johnson, Matrix Analysis, 2nd ed., Thm 4.1.5 and Eq. (5.2.7): in an eigenbasis, off-diagonal entries add squared error and the optimal nonnegative diagonal entries are max(lambda_i, 0).

Parameters:

x (DenseArray)

Return type:

DenseArray

eig_to_dense(evals, evecs)

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

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

add_batch(x, y)

Return the leading-axis batch sum of x and 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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

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

dual_norm(xi)

Return the dual norm of a covector, \(\|\xi\|_* = \|R^{-1}\xi\|\).

A covector is not an element, so there is no membership check to run.

Parameters:

xi (Any)

Return type:

Any

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

Return type:

DenseArray

from_spectrum(eigvals, frame=None)

Reconstruct an element from spectral data.

Parameters:

• eigvals (Any)

• frame (Any)

Return type:

Any

geometry: InnerProduct = EuclideanInnerProduct()

The space’s inner product; Euclidean unless a family sets another.

inner(x, y)

Return \(\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

property is_euclidean: bool

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)

Return \(\|x\|_X = \sqrt{\operatorname{Re}\langle x, x\rangle_X}\).

Parameters:

x (Any)

Return type:

Any

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

real_inner(x, y)

Return the real inner product \(\operatorname{Re}\langle x, y\rangle_X\).

Parameters:

• x (Any)

• y (Any)

Return type:

Any

riesz(x)

Return the covector R x of an element, or of each element of a leading-axis batch.

Parameters:

x (Any)

Return type:

Any

riesz_inverse(xi)

Return the element R^{-1} xi of a covector, or of each covector in a batch.

A covector has the element’s coordinate shape, so the input check is that shape check.

Parameters:

xi (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• x (Any)

Return type:

Any

property size: int

Return the flat coordinate dimension of this space.

spectral_apply(x, f)

Apply f to the spectrum of x and reconstruct.

Parameters:

• x (Any)

• f (Callable)

Return type:

Any

spectral_decompose(x)

Return spectral data sufficient to reconstruct x.

Parameters:

x (Any)

Return type:

Any

spectrum(x, **kwargs)

Return Jordan-algebraic eigenvalues of x.

Parameters:

• x (Any)

• kwargs (Any)

Return type:

Any

stacked(count)

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

Parameters:

count (int)

Return type:

CoordinateSpace

star(x)

Return the canonical star/involution 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

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

zeros()

Return the zero vector in this space.

Return type:

DenseArray

shape: Tuple[int, ...]

class spacecore.space.TreeSpace(treedef, leaf_spaces, *, ctx=None, check_level=None)

Bases: PyTreeNode, CoordinateSpace

Finite direct product \(\prod_\ell X_\ell\) whose elements are Python trees.

Any tuple, list, dict, named-tuple or optree-registered structure works. Vector operations, conversion, checks and batching act leaf by leaf, and a capability (inner product, star, Jordan) is offered only when every leaf has it.

Parameters:

• treedef (optree.PyTreeSpec or tree) – Structure, or an example tree; its leaf order pairs with leaf_spaces.

• leaf_spaces (sequence of CoordinateSpace) – Leaf spaces, in leaf order.

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

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

Raises:

• TypeError – If leaf_spaces are not coordinate spaces.

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

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)

Build a tuple-structured TreeSpace from ordered leaf spaces.

Parameters:

• leaf_spaces (Sequence[CoordinateSpace])

• ctx (Context | str | None)

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

Return type:

TreeSpace

classmethod from_template(template, leaf_spaces, *, ctx=None, check_level=None)

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)

Flatten a matching Python tree value into ordered leaves.

Parameters:

value (Any)

Return type:

tuple[Any, …]

unflatten_tree(leaves)

Rebuild the configured Python tree from ordered leaves.

Parameters:

leaves (Sequence[Any])

Return type:

Any

element(value)

Bind a matching Python tree value to this space.

Parameters:

value (Any)

Return type:

TreeElement

zero()

Return the additive identity.

Return type:

Any

zeros()

Return the leafwise additive identity.

Return type:

Any

ones()

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

Return type:

Any

stacked(count)

Return a tree whose leaves are stacked leaf spaces.

Parameters:

count (int)

Return type:

TreeSpace

check(x)

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

Parameters:

x (Any)

Return type:

None

convert_element(x, new_ctx=None)

Convert each leaf and preserve the configured tree structure.

Parameters:

• x (Any)

• new_ctx (Context | str | None)

Return type:

Any

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

add_batch(x, y)

Return the leading-axis batch sum of x and 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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property ctx: Context

Return the execution context bound to this object.

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

property dtype: Any

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

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

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, …]

property ops: BackendOps

Return backend operations associated with this object’s context.

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• x (Any)

Return type:

Any

property size: int

Return the flat coordinate dimension of this space.

tree_flatten()

Return (children, aux) for this container.

Returns:

children — dynamic, array-bearing members, in a stable order; aux — static metadata sufficient, with children, to rebuild.

Return type:

tuple

classmethod tree_unflatten(aux, children)

Rebuild an instance from aux and children.

Parameters:

• aux (object) – The static metadata returned by tree_flatten().

• children (tuple) – The dynamic members, possibly transformed or traced.

Return type:

Self

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

class spacecore.space.TreeElement(*args, **kwargs)

Bases: PyTreeNode

Leaves bound to a TreeSpace; plain trees of the right structure work too.

Leaves are not coerced; the leaf spaces check them.

Parameters:

• space (TreeSpace) – The space fixing leaf order and structure.

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

Raises:

• TypeError – If space is not a TreeSpace.

• ValueError – If the leaf count differs from space.arity.

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()

Expose element leaves as JAX pytree children.

classmethod tree_unflatten(space, children)

Rebuild an element from JAX pytree children.

Parameters:

• space (TreeSpace)

• children (Sequence[Any])

Return type:

TreeElement

class spacecore.space.TreeSpectralDecomposition(*args, **kwargs)

Bases: PyTreeNode

Leafwise Jordan spectral data, in leaf order.

Parameters:

• eigvals (tuple) – Eigenvalues of each leaf.

• frames (tuple) – Spectral frames of each leaf.

• treedef (optree.PyTreeSpec or None, optional) – The producing space’s structure, used by to_tree(); None for hand-built data. It is static pytree data, so decompositions merged in one lax.cond or while_loop must agree on it.

eigvals: tuple[Any, ...]

frames: tuple[Any, ...]

treedef: Any = None

to_tree()

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, check_level=None)

Bases: PyTreeNode, CoordinateSpace

count leading-axis copies of a coordinate space; operations vmap over the copies.

Construction picks a subclass that keeps the base space’s inner-product, star and Jordan capabilities.

Parameters:

• base (Space) – Coordinate space to repeat.

• count (int) – Number of copies.

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

• check_level ({"none", "cheap", "standard", "strict"}, optional) – Validation level; the ambient default when omitted.

zeros()

Return the stacked zero element.

Return type:

DenseArray

ones()

Return the stacked all-ones element.

Return type:

DenseArray

stacked(count)

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

Parameters:

count (int)

Return type:

StackedSpace

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

add_batch(x, y)

Return the leading-axis batch sum of x and 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.

The level is stored on the bound object (_check_level), seeded at construction. The fallback covers any construction path that assigns _ctx without going through __init__/_bind_context.

check_member(x)

Parameters:

x (Any)

Return type:

None

check_scalar(a)

Raise if a is not an admissible multiplier, unless checks are off.

Only rejects a multiplier that is provably inadmissible, so a traced scalar under jax.jit always passes (see spacecore._lazy_algebra.is_recognizably_nonreal()).

Parameters:

a (Any)

Return type:

None

checks: ClassVar[tuple[SpaceCheck, ...]] = ()

convert(new_ctx=None)

Return this object represented in new_ctx.

The object’s check_level is a property of the object, not of the backend/dtype context, so it is preserved across conversion rather than re-seeded from the ambient default.

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

declared_scalar_field: ClassVar[Literal['real', 'complex'] | None] = None

Scalar field this space is closed under, when that is narrower than the field implied by the dtype. None (the default) means “same as field” — the common case, where entries and scalars agree. Subclasses override it with a literal; see scalar_field.

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

Return the field the entries live in, derived from the context dtype.

Context.dtype controls array representation. This property records only whether those entries are real or complex.

This is a fact about representation, and it is not always the field of scalars the space is a vector space over — see scalar_field. Equality and repr use this one: a real-dtype and a complex-dtype space of the same shape are different spaces regardless of what they are closed under.

flatten(x)

Return a dense one-dimensional coordinate vector, in C order.

C order (row-major, last axis varying fastest) is SpaceCore’s declared vec convention on every backend – see the flattening-order note in spacecore.backend._ops. It is what makes to_matrix and flatten compose: to_matrix() @ flatten(x) == flatten(A.apply(x)) holds only for a consistent choice, and the Kronecker identities assume this one.

Parameters:

x (Any)

Return type:

DenseArray

flatten_batch(xs)

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

Parameters:

xs (Any)

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, …]

pair(xi, x)

Return the metric-free pairing \(\langle \xi, x\rangle = \operatorname{Re}\,\mathrm{vdot}(\xi, x)\) of a covector with an element.

A covector is an array of this space’s coordinate shape; no inner product is involved, so the pairing is the same under every geometry.

Parameters:

• xi (Any)

• x (Any)

Return type:

Any

same_math(other)

Tier-1 equality gate: same concrete type and same math context.

Combines a runtime-type identity check with Context.same_math() (equal backend ops and dtype, ignoring check_level — a validation policy, not a mathematical or backend property). This is the mandatory first check in every __eq__: the type gate guarantees other exposes the same attributes this object’s __eq__ will read, and same_math guarantees any later ops.allclose runs only on same-backend, same-dtype arrays, making cross-backend objects compare unequal.

Callers that fail this gate should return NotImplemented so Python can try the reflected comparison and fall back to identity symmetrically.

Parameters:

other (Any)

Return type:

bool

property scalar_field: Literal['real', 'complex']

Return the field of scalars this space is closed under.

Defaults to field — entries and scalars agree for coordinate spaces. A subclass whose structure survives only real scaling declares otherwise via declared_scalar_field: the complex Hermitian matrices have complex entries but form a real vector space, because i·H is anti-Hermitian for Hermitian H.

Declared, never inferred. The dtype cannot imply this — it is a property of the structure the space enforces, not of how elements are stored.

scale(a, x)

Return a * x; a multiplier that provably leaves the space is rejected.

Parameters:

• a (Any)

• x (Any)

Return type:

Any

scale_batch(a, x)

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

Parameters:

• a (Any)

• x (Any)

Return type:

Any

property size: int

Return the flat coordinate dimension of this space.

unflatten(v)

Inverse of flatten, in the same C order.

Parameters:

v (DenseArray)

Return type:

Any

unflatten_batch(vs)

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

Parameters:

vs (DenseArray)

Return type:

Any

vpair(xi, xs)

Return pair(xi, xs[i]) for every element of a leading-axis batch.

Parameters:

• xi (Any)

• xs (Any)

Return type:

Any

shape: Tuple[int, ...]

class spacecore.space.SpaceValidationError

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)

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)

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

abstractmethod is_valid(space, x)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

abstractmethod error_message(space, x)

Return a diagnostic for an invalid x.

Parameters:

• space (Any)

• x (Any)

Return type:

str

class spacecore.space.BackendCheck(name='backend')

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'

minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'

is_valid(space, x)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

error_message(space, x)

Return a diagnostic for an invalid x.

Parameters:

• space (Any)

• x (Any)

Return type:

str

core_rank: ClassVar[int] = 0

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')

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)

Return the whole canonical shape as the trailing element shape.

Parameters:

space (Any)

Return type:

tuple[int, …]

is_valid(space, x)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

error_message(space, x)

Return a diagnostic for an invalid x.

Parameters:

• space (Any)

• x (Any)

Return type:

str

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

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')

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'

minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'

is_valid(space, x)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

error_message(space, x)

Return a diagnostic for an invalid x.

Parameters:

• space (Any)

• x (Any)

Return type:

str

core_rank: ClassVar[int] = 0

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')

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'

minimum_level: ClassVar[Literal['none', 'cheap', 'standard', 'strict']] = 'cheap'

is_valid(space, x)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

error_message(space, x)

Return a diagnostic for an invalid x.

Parameters:

• space (Any)

• x (Any)

Return type:

str

core_rank: ClassVar[int] = 0

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')

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)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

error_message(space, x)

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)

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)

Return whether x is valid for space.

Parameters:

• space (Any)

• x (Any)

Return type:

bool

error_message(space, x)

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