quchip.declarative.expr

One backend-neutral expression tree for authored scalar and operator physics.

Functions

as_operator_expr(value, *, labels, dims, name)	Normalize symbolic, matrix, or opaque callable operator authorship.
as_scalar_expr(value, *, name[, arguments, ...])	Normalize symbolic, numeric, or opaque callable scalar authorship.
as_state_expr(value, *, labels, dims, name)	Normalize an authored ket array or opaque callable without evaluating it.
declared_excitation_changes(expr)	Return the total energy-level changes a matrix contribution declares, if any.
ensure_expr(value)	Coerce a scalar value into the shared expression tree.
is_energy_diagonal(expr, bases)	Return whether authored algebra guarantees zero energy-change weight in captured bases.
is_opaque_callable(value)	Return whether value is a callable authoring function, not a matrix-like object.
materialize_array(expr, *[, bindings, t])	Materialize authored physics as a backend-independent JAX array.
materialize_expr(expr, backend, *[, ...])	Lower symbolic physics, and pass an already-native contribution through unchanged.
materialize_scalar(expr, *[, bindings])	Materialize a scalar expression without coercing traced values.
scalar_signal_program(expr)	Lower scalar signal algebra into the backend-neutral signal program.
split_dynamic_hamiltonian(expr)	Split a linear Hamiltonian sum into scalar-signal and operator factors.

Classes

ParameterNamespace(scope, fields)	Attribute view that exposes one owner's declared fields as symbolic leaves.
PhysicsExpr(kind[, args, labels, _bindings])	Authored scalar and operator algebra, independent of numerical values.

Exceptions

UnboundParameterError

Numerical materialization started without all required values.

exception quchip.declarative.expr.UnboundParameterError

Bases: ValueError

Numerical materialization started without all required values.

quchip.declarative.expr.is_opaque_callable(value)

Return whether value is a callable authoring function, not a matrix-like object.

class quchip.declarative.expr.PhysicsExpr(kind, args=(), labels=(), _bindings=<factory>)

Bases: object

Authored scalar and operator algebra, independent of numerical values.

Parameters:

• kind (str) – Expression node kind, such as "op", "add", "parameter" or "matrix".

• args (tuple, default ()) – Node payload in the representation that kind requires.

• labels (tuple[str, ...], default ()) – Ordered endpoint labels for this expression’s support.

kind: str

args: tuple[Any, ...] = ()

labels: tuple[str, ...] = ()

classmethod parameter(*, scope, name, symbol=None, unit=None)

Create a symbolic declared-parameter leaf.

Parameters:

• scope (str) – Dotted owner scope and declared field name.

• name (str) – Dotted owner scope and declared field name.

• symbol (str or None) – Optional display symbol and unit metadata.

• unit (str or None) – Optional display symbol and unit metadata.

classmethod literal(value)

Create a literal scalar leaf.

Parameters:

value (scalar) – Numerical constant copied into the expression.

classmethod from_matrix(value, *, labels, dims, name=None, excitation_changes=None)

Create a named backend-neutral matrix contribution.

Parameters:

• value (array-like) – Matrix payload with one local block per dims entry.

• labels (tuple) – Matching ordered endpoint labels and positive dimensions.

• dims (tuple) – Matching ordered endpoint labels and positive dimensions.

• name (str or None) – Optional display name.

• excitation_changes (iterable of int or None) – Total energy-level changes that the matrix can carry (column minus row in the captured energy bases). Band decomposition treats all other total changes as structural zeros, even for traced payloads. None declares no structure.

classmethod from_function(function, *arguments, labels, dims, name=None)

Create an opaque matrix-valued contribution from a pure function.

The function runs only during numerical materialization. Display keeps its declared name and arguments, such as X(a, b), and does not show the implementation as symbolic algebra.

Parameters:

• function (callable) – Pure callable evaluated during numerical materialization.

• *arguments (Any) – Expression arguments passed to function.

• labels (tuple) – Matching endpoint labels and dimensions.

• dims (tuple) – Matching endpoint labels and dimensions.

• name (str or None) – Display name, required for anonymous callables.

classmethod from_state(value, *, labels, dims, name)

Create a named authored ket contribution.

Parameters:

• value (array-like) – Ket payload.

• labels (tuple) – Matching endpoint labels and dimensions.

• dims (tuple) – Matching endpoint labels and dimensions.

• name (str) – Display name.

classmethod from_state_function(function, *arguments, labels, dims, name)

Create an opaque callable ket contribution.

Parameters:

• function (callable) – Callable that returns a ket during materialization.

• *arguments (Any) – Expression arguments passed to function.

• labels (tuple) – Matching endpoint labels and dimensions.

• dims (tuple) – Matching endpoint labels and dimensions.

• name (str) – Display name.

classmethod from_signal(signal, *, name='f')

Create a scalar time-function leaf backed by an engine signal.

Parameters:

• signal (object) – Engine signal object evaluated at runtime.

• name (str, default "f") – Display name for the signal node.

embed(labels, dims)

Embed this local contribution into an ordered composite Hilbert space.

Parameters:

• labels (tuple) – Complete ordered composite labels and matching dimensions.

• dims (tuple) – Complete ordered composite labels and matching dimensions.

with_bindings(bindings)

Attach default values that only direct numerical inspection uses.

Parameters:

bindings (mapping[str, Any]) – Dotted parameter paths to numerical values.

parameter_paths()

Return referenced dotted parameter paths in authored order.

numeric_values()

Return bound and matrix payloads for tracer-safe cache decisions.

property shape: tuple[int, int]

Matrix shape implied by this operator expression’s static support.

latex()

Render the authored expression with familiar mathematical notation.

matrix(bindings=None, *, t=None, backend=None)

Materialize this expression and return its dense numerical array.

Parameters:

• bindings (mapping or None, optional) – Values for unresolved parameter paths.

• t (scalar or None, keyword-only) – Time for signal evaluation.

• backend (backend or None, keyword-only) – Backend lowering object. None selects the default.

class quchip.declarative.expr.ParameterNamespace(scope, fields)

Bases: object

Attribute view that exposes one owner’s declared fields as symbolic leaves.

quchip.declarative.expr.ensure_expr(value)

Coerce a scalar value into the shared expression tree.

quchip.declarative.expr.as_operator_expr(value, *, labels, dims, name, arguments=(), owner=None, scope=None, allowed=None)

Normalize symbolic, matrix, or opaque callable operator authorship.

Parameters:

• value (PhysicsExpr, callable, or matrix) – Authored operator representation.

• labels (tuple) – Ordered endpoint labels and matching dimensions.

• dims (tuple) – Ordered endpoint labels and matching dimensions.

• name (str) – Display name for opaque or matrix contributions.

• arguments (tuple, default ()) – Arguments for an opaque callable.

• owner (object or None, default None) – Object whose fields bind the positional argument names of a callable. Do not combine with explicit arguments.

• scope (str or None, default None) – Dotted-path prefix for owner-bound parameters, such as a device label. Required with owner when the callable has arguments.

• allowed (mapping or None, default None) – Permitted owner-field names, given as mapping keys whose values are not used. None accepts all named owner fields.

quchip.declarative.expr.as_scalar_expr(value, *, name, arguments=(), owner=None, scope=None, allowed=None)

Normalize symbolic, numeric, or opaque callable scalar authorship.

Parameters:

• value (PhysicsExpr, scalar, or callable) – Authored scalar representation.

• name (str) – Display name for opaque callables.

• arguments (tuple, default ()) – Arguments for an opaque callable.

• owner (object or None, default None) – Object whose fields bind the positional argument names of a callable. Do not combine with explicit arguments.

• scope (str or None, default None) – Dotted-path prefix for owner-bound parameters, such as a device label. Required with owner when the callable has arguments.

• allowed (mapping or None, default None) – Permitted owner-field names, given as mapping keys whose values are not used. None accepts all named owner fields.

quchip.declarative.expr.as_state_expr(value, *, labels, dims, name, arguments=(), owner=None, scope=None, allowed=None)

Normalize an authored ket array or opaque callable without evaluating it.

Parameters:

• value (PhysicsExpr, callable, or array) – Authored ket representation.

• labels (tuple) – Ordered endpoint labels and matching dimensions.

• dims (tuple) – Ordered endpoint labels and matching dimensions.

• name (str) – Display name for the state contribution.

• arguments (tuple, default ()) – Arguments for an opaque callable.

• owner (object or None, default None) – Object whose fields bind the positional argument names of a callable. Do not combine with explicit arguments.

• scope (str or None, default None) – Dotted-path prefix for owner-bound parameters, such as a device label. Required with owner when the callable has arguments.

• allowed (mapping or None, default None) – Permitted owner-field names, given as mapping keys whose values are not used. None accepts all named owner fields.

quchip.declarative.expr.split_dynamic_hamiltonian(expr)

Split a linear Hamiltonian sum into scalar-signal and operator factors.

Signal algebra can be nonlinear and can contain more than one signal leaf. Only the quantum operator must be linear. Each additive term must be one operator-valued factor times a scalar expression that depends on at least one delivered signal.

quchip.declarative.expr.scalar_signal_program(expr)

Lower scalar signal algebra into the backend-neutral signal program.

quchip.declarative.expr.declared_excitation_changes(expr)

Return the total energy-level changes a matrix contribution declares, if any.

quchip.declarative.expr.is_energy_diagonal(expr, bases)

Return whether authored algebra guarantees zero energy-change weight in captured bases.

quchip.declarative.expr.materialize_expr(expr, backend, *, bindings=None, t=None, local_bases=None)

Lower symbolic physics, and pass an already-native contribution through unchanged.

quchip.declarative.expr.materialize_array(expr, *, bindings=None, t=None)

Materialize authored physics as a backend-independent JAX array.

quchip.declarative.expr.materialize_scalar(expr, *, bindings=None)

Materialize a scalar expression without coercing traced values.