Conversion policy#

SpaceCore is built around the chain

\[\texttt{BackendOps} \to \texttt{Context} \to \texttt{Space} \to \texttt{LinOp}.\]

Spaces and operators therefore always live under a numerical policy: a backend, a dtype, and a checking policy. As soon as objects may come from different sources, the library must decide which backend to use, which dtype to use, and whether backend changes should happen silently.

SpaceCore treats backend conversion as an explicit context operation. Objects that inherit from ContextBound provide:

converted = obj.convert(target_context)

The target may be a Context, backend family string, backend enum value, or None. Passing None resolves to the default context, subject to dtype policy.

Why conversion is visible#

Backend changes can affect execution mode, sparse support, dtype semantics, and compilation behavior. A JAX-backed operator and a NumPy-backed operator may expose the same SpaceCore methods, but they are not interchangeable at the array level.

Without an explicit conversion policy, common construction patterns become ambiguous. For example, if a ProductSpace is created from several spaces and one of the inputs uses a JAX context while the global context is NumPy, the library must choose between inferring from the inputs or converting inputs to the global default context. The policy layer makes that decision deterministic.

Context resolution#

When a new context-bound object is created, SpaceCore resolves its context in a fixed order:

  1. Use an explicit context provided through ctx=.... If the explicit context is given as a string, missing context parameters are filled from defaults.

  2. If no explicit context is provided, infer a context from input objects that carry a ctx attribute.

  3. A common context can be inferred only when all context-carrying inputs use the same backend family.

  4. The inferred context uses the shared backend and the most general dtype among the inferred dtypes. The inferred enable_checks flag is enabled only if all inferred contexts have checks enabled.

  5. If no context can be inferred, use the global default context set by spacecore.set_context().

Once the context is resolved, it is assigned to the new object. Inputs that carry their own contexts are adapted to the backend of the resolved context. Their dtype is handled separately by the dtype policy.

User code can apply this same priority rule through spacecore.resolve_context_priority(priority_ctx, *objects). The helper is the public entry point for context-priority resolution; the internal context manager singleton is not part of the user-facing API.

Policy modes#

The resolution_policy regulates what happens when an object with a native context is converted to a target context with a different backend family. This policy is used when conversion is enforced through the context manager.

Use spacecore.set_resolution_policy(...) to set it and spacecore.get_resolution_policy() to inspect the active value.

resolution_policy types

  • warning: if the object has a native context and the target context has a different backend family, conversion is allowed but a warning is issued. This is the default behavior.

  • error: if the object has a native context and the target context is backend-incompatible, conversion is rejected. This is useful when accidental backend migration must be forbidden.

  • silent: if the object has a native context and the target context is backend-incompatible, conversion proceeds without warning. This is useful in controlled pipelines where automatic conversion is expected.

The default is warning.

Summary#

Context resolution and backend conversion are related but separate decisions:

  • Context resolution decides which context the new object receives.

  • Conversion adapts context-carrying inputs to that resolved context.

  • resolution_policy controls whether backend-incompatible conversion warns, errors, or proceeds silently.

  • Dtype handling during conversion is governed separately by the dtype policy.