Spaces API

Spaces define element structure, geometry, flattening, and validation.

spacecore.space.Space	Abstract Space.
spacecore.space.VectorSpace	Dense vector space R^{n1, ..., nK} or C^{n1, ..., nK}.
spacecore.space.HermitianSpace	Space of dense n×n Hermitian matrices.
spacecore.space.ProductSpace	Cartesian product space X = X1 × .
spacecore.space.SpaceCheck
spacecore.space.SpaceValidationError	Raised when an object is not a member of a space.

Space

class spacecore.space.Space(shape, ctx=None)

Bases: ContextBound

Abstract Space.

A Space owns the geometry (inner product, norm) and the basic linear structure (add/scale/axpy) for its elements.

Solvers should use only this API.

Parameters:

• shape (Tuple[int, ...])

• ctx (Context | str | None)

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

member_checks()

Return type:

tuple[SpaceCheck, …]

check_member(x)

Parameters:

x (Any)

Return type:

None

abstractmethod zeros()

Return the additive identity in the requested representation.

Return type:

Any

abstractmethod add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

abstractmethod scale(a, x)

Return a * x.

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

abstractmethod inner(x, y)

Inner product ⟨x, y⟩ for elements of this space.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

norm(x)

Induced norm ||x|| = sqrt(real(⟨x,x⟩)). Override if you can do better.

Parameters:

x (Any)

Return type:

Any

abstractmethod eigh(x, k=None)

Eigendecomposition of x (if applicable).)

Parameters:

• x (Any)

• k (int)

Return type:

Any

abstractmethod flatten(x)

Return a dense 1D coordinate vector (backend-native dense array).

If a representation forbids materialization, raise a policy/capability error.

Parameters:

x (Any)

Return type:

DenseArray

abstractmethod unflatten(v)

Inverse of flatten; returns an element in the requested representation.

Parameters:

v (DenseArray)

Return type:

Any

apply(x, f)

Parameters:

• x (Any)

• f (Callable)

Return type:

Any

convert(new_ctx=None)

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property ctx: Context

property dtype: Any

property ops: BackendOps

VectorSpace

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

Bases: Space

Dense vector space R^{n1, …, nK} or C^{n1, …, nK}.

Elements:

• backend-native dense arrays;

• canonical shape is (n1, …, nK).

Geometry:

• Euclidean / ℓ2 inner product

  ⟨x, y⟩ = vdot(x, y).

Parameters:

• shape (Tuple[int, ...])

• ctx (Context | str | None)

zeros()

Return the additive identity in the requested representation.

Return type:

DenseArray

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

DenseArray

scale(a, x)

Return a * x.

Parameters:

• a (Any)

• x (Any)

Return type:

DenseArray

inner(x, y)

Inner product ⟨x, y⟩ for elements of this space.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

eigh(x, k=None)

Eigendecomposition of x (if applicable).)

Parameters:

• x (Any)

• k (int)

Return type:

Any

flatten(X)

Return a dense 1D coordinate vector (backend-native dense array).

If a representation forbids materialization, raise a policy/capability error.

Parameters:

X (DenseArray)

Return type:

DenseArray

unflatten(v)

Inverse of flatten; returns an element in the requested representation.

Parameters:

v (DenseArray)

Return type:

DenseArray

apply(x, f)

Apply a scalar function to a vector-space element entrywise.

For a space element $$ x in mathbb{K}^{n_1 times cdots times n_k}, $$ this method returns the element $$ y = f(x) $$ obtained by applying f coordinatewise to the entries of x.

Parameters:

• x (DenseArray) – Element of this vector space. Must have shape self.shape and dtype compatible with this space.

• f (Callable[[DenseArray], DenseArray]) – Callable representing an entrywise transformation. It is expected to act elementwise on backend arrays, or to be compatible with the backend vectorization fallback.

Returns:

The transformed element, with the same shape as x.

Return type:

DenseArray

Raises:

• TypeError – If x is not a valid member of this space.

• ValueError – If the result of the application does not preserve the shape of the space element.

Notes

This is the canonical functional calculus for VectorSpace: application is performed entrywise in the distinguished coordinate representation.

axpy(a, x, y)

Return a*x + y.

Parameters:

• a (Any)

• x (Any)

• y (Any)

Return type:

Any

check_member(x)

Parameters:

x (Any)

Return type:

None

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

convert(new_ctx=None)

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property ctx: Context

property dtype: Any

member_checks()

Return type:

tuple[SpaceCheck, …]

norm(x)

Induced norm ||x|| = sqrt(real(⟨x,x⟩)). Override if you can do better.

Parameters:

x (Any)

Return type:

Any

property ops: BackendOps

HermitianSpace

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

Bases: VectorSpace

Space of dense n×n Hermitian matrices.

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

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

Parameters:

• n (int)

• atol (float)

• rtol (float)

• enforce_herm (bool)

• ctx (Context | str | None)

property n: int

is_hermitian(x)

Parameters:

x (DenseArray)

Return type:

bool

symmetrize(x)

Project onto the Hermitian cone: (X + X^H)/2.

Parameters:

x (DenseArray)

Return type:

DenseArray

eigh(x, k=None)

Eigendecomposition of x (if applicable).)

Parameters:

• x (DenseArray)

• k (int)

Return type:

Tuple[DenseArray, DenseArray]

unflatten(v)

Inverse of flatten; returns an element in the requested representation.

Parameters:

v (DenseArray)

Return type:

DenseArray

psd_proj(x)

Parameters:

x (DenseArray)

Return type:

DenseArray

eig_to_dense(evals, evecs)

Parameters:

• evals (DenseArray)

• evecs (DenseArray)

Return type:

DenseArray

apply(x, f)

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

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

Parameters:

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

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

Returns:

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

Return type:

DenseArray

Raises:

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

Notes

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

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

add(x, y)

Return x + y.

Parameters:

• x (Any)

• y (Any)

Return type:

DenseArray

axpy(a, x, y)

Return a*x + y.

Parameters:

• a (Any)

• x (Any)

• y (Any)

Return type:

Any

check_member(x)

Parameters:

x (Any)

Return type:

None

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

convert(new_ctx=None)

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property ctx: Context

property dtype: Any

flatten(X)

Return a dense 1D coordinate vector (backend-native dense array).

If a representation forbids materialization, raise a policy/capability error.

Parameters:

X (DenseArray)

Return type:

DenseArray

inner(x, y)

Inner product ⟨x, y⟩ for elements of this space.

Parameters:

• x (Any)

• y (Any)

Return type:

Any

member_checks()

Return type:

tuple[SpaceCheck, …]

norm(x)

Induced norm ||x|| = sqrt(real(⟨x,x⟩)). Override if you can do better.

Parameters:

x (Any)

Return type:

Any

property ops: BackendOps

scale(a, x)

Return a * x.

Parameters:

• a (Any)

• x (Any)

Return type:

DenseArray

zeros()

Return the additive identity in the requested representation.

Return type:

DenseArray

ProductSpace

class spacecore.space.ProductSpace(spaces, ctx=None)

Bases: Space

Cartesian product space X = X1 × … × Xk.

Elements are tuples:

x = (x1, …, xk) with xi ∈ Xi

Canonical dense coordinates:

flatten(x) = concat(flatten_i(xi))

Notes

• shape for this space is the 1D coordinate length of the concatenated flattening.

• eigh has no canonical meaning here and raises by default.

Parameters:

• spaces (Tuple[Space, ...])

• ctx (Context | str | None)

property arity: int

zeros()

Return the additive identity in the requested representation.

Return type:

Tuple[Any, …]

add(x, y)

Return x + y.

Parameters:

• x (Tuple[Any, ...])

• y (Tuple[Any, ...])

Return type:

Tuple[Any, …]

axpy(a, x, y)

Return a*x + y.

Parameters:

• a (Any)

• x (Any)

• y (Any)

Return type:

Any

check_member(x)

Parameters:

x (Any)

Return type:

None

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

convert(new_ctx=None)

Parameters:

new_ctx (Context | BackendFamily | str | None)

Return type:

Self

property ctx: Context

property dtype: Any

member_checks()

Return type:

tuple[SpaceCheck, …]

norm(x)

Induced norm ||x|| = sqrt(real(⟨x,x⟩)). Override if you can do better.

Parameters:

x (Any)

Return type:

Any

property ops: BackendOps

scale(a, x)

Return a * x.

Parameters:

• a (Any)

• x (Tuple[Any, ...])

Return type:

Tuple[Any, …]

inner(x, y)

Inner product ⟨x, y⟩ for elements of this space.

Parameters:

• x (Tuple[Any, ...])

• y (Tuple[Any, ...])

Return type:

Any

eigh(x, k=None)

Eigendecomposition of x (if applicable).)

Parameters:

• x (Any)

• k (int)

Return type:

Any

flatten(x)

Return a dense 1D coordinate vector (backend-native dense array).

If a representation forbids materialization, raise a policy/capability error.

Parameters:

x (Tuple[Any, ...])

Return type:

DenseArray

unflatten(v)

Inverse of flatten; returns an element in the requested representation.

Parameters:

v (DenseArray)

Return type:

Tuple[Any, …]

apply(x, f)

Apply a function to each component of a product-space element.

For a product space $$ X = X_1 times cdots times X_m, $$ and an element $$ x = (x_1,dots,x_m), qquad x_i in X_i, $$ this method returns $$ f(x) := bigl(f_{X_1}(x_1), dots, f_{X_m}(x_m)bigr), $$ where f_{X_i} denotes application according to the logic of the corresponding component space X_i.

Parameters:

• x (Tuple[Any, ...]) – Tuple representing an element of this product space. Its length must equal the arity of the product space, and each component must be a valid member of the corresponding factor space.

• f (Callable[[Any], Any]) – Callable to apply to each component. The meaning of application is delegated to each component space via spaces[i].apply.

Returns:

Tuple of transformed components, one for each factor space.

Return type:

tuple[Any, …]

Raises:

• TypeError – If x is not a valid product-space element.

• ValueError – If x has the wrong tuple length.

Notes

This method does not define a new joint functional calculus on the product space. It applies the existing functional calculus of each factor space independently, component by component.

Validation

class spacecore.space.SpaceCheck(name: 'str')

Bases: ABC

Parameters:

name (str)

name: str

abstractmethod is_valid(space, x)

Parameters:

• space (Any)

• x (Any)

Return type:

bool

abstractmethod error_message(space, x)

Parameters:

• space (Any)

• x (Any)

Return type:

str

exception 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.