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.
`ensure_expr`(value)	Coerce a scalar value into the shared expression tree.
`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, *[, bindings, t])	Lower symbolic physics, passing an already-native contribution through.
`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 exposing 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 was requested without every required value.

exception quchip.declarative.expr.UnboundParameterError[source]¶

Bases: ValueError

Numerical materialization was requested without every required value.

quchip.declarative.expr.is_opaque_callable(value)[source]¶

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

Parameters:: value (Any)
Return type:: bool

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

Bases: object

Authored scalar and operator algebra, independent of numerical values.

Parameters:

kind (str)
args (tuple[Any, ...])
labels (tuple[str, ...])
_bindings (Mapping[str, Any])

kind: str¶

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

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

classmethod parameter(*, scope, name, symbol=None, unit=None)[source]¶

Create a symbolic declared-parameter leaf.

Parameters:

scope (str)
name (str)
symbol (str | None)
unit (str | None)

Return type:

PhysicsExpr

classmethod literal(value)[source]¶

Create a literal scalar leaf.

Parameters:: value (Any)
Return type:: PhysicsExpr

classmethod from_matrix(value, *, labels, dims, name=None)[source]¶

Create a named backend-neutral matrix contribution.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str | None)

Return type:

PhysicsExpr

classmethod from_function(function, *arguments, labels, dims, name=None)[source]¶

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), without exposing the implementation as symbolic algebra.

Parameters:

function (Any)
arguments (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str | None)

Return type:

PhysicsExpr

classmethod from_state(value, *, labels, dims, name)[source]¶

Create a named authored ket contribution.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)

Return type:

PhysicsExpr

classmethod from_state_function(function, *arguments, labels, dims, name)[source]¶

Create an opaque callable ket contribution.

Parameters:

function (Any)
arguments (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)

Return type:

PhysicsExpr

classmethod from_signal(signal, *, name='f')[source]¶

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

Parameters:

signal (Any)
name (str)

Return type:

PhysicsExpr

embed(labels, dims)[source]¶

Embed this local contribution into an ordered composite Hilbert space.

Parameters:

labels (tuple[str, ...])
dims (tuple[int, ...])

Return type:

PhysicsExpr

with_bindings(bindings)[source]¶

Attach default values used only by direct numerical inspection.

Parameters:: bindings (Mapping[str, Any])
Return type:: PhysicsExpr

parameter_paths()[source]¶

Return referenced dotted parameter paths in authored order.

Return type:: tuple[str, …]

numeric_values()[source]¶

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

Return type:: tuple[Any, …]

property shape: tuple[int, int]¶: Matrix shape implied by this operator expression’s static support.

latex()[source]¶

Render the authored expression with familiar mathematical notation.

Return type:: str

matrix(bindings=None, *, t=None, backend=None)[source]¶

Materialize this expression and return its dense numerical array.

Parameters:

bindings (Mapping[str, Any] | None)
t (Any | None)
backend (Any)

Return type:

Any

class quchip.declarative.expr.ParameterNamespace(scope, fields)[source]¶

Bases: object

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

Parameters:

scope (str)
fields (Mapping[str, Any])

quchip.declarative.expr.ensure_expr(value)[source]¶

Coerce a scalar value into the shared expression tree.

Parameters:: value (Any)
Return type:: PhysicsExpr

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

Normalize symbolic, matrix, or opaque callable operator authorship.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)
arguments (tuple[Any, ...])
owner (Any | None)
scope (str | None)
allowed (Mapping[str, Any] | None)

Return type:

PhysicsExpr

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

Normalize symbolic, numeric, or opaque callable scalar authorship.

Parameters:

value (Any)
name (str)
arguments (tuple[Any, ...])
owner (Any | None)
scope (str | None)
allowed (Mapping[str, Any] | None)

Return type:

PhysicsExpr

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

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

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)
arguments (tuple[Any, ...])
owner (Any | None)
scope (str | None)
allowed (Mapping[str, Any] | None)

Return type:

PhysicsExpr

quchip.declarative.expr.split_dynamic_hamiltonian(expr)[source]¶

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

Signal algebra may be nonlinear and may contain multiple signal leaves. Linearity is required only in the quantum operator: each additive term must contain one operator-valued factor multiplied by a scalar expression that depends on at least one delivered signal.

Parameters:: expr (PhysicsExpr)
Return type:: tuple[tuple[PhysicsExpr, PhysicsExpr], …]

quchip.declarative.expr.scalar_signal_program(expr)[source]¶

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

Parameters:: expr (PhysicsExpr)
Return type:: Any

quchip.declarative.expr.materialize_expr(expr, backend, *, bindings=None, t=None)[source]¶

Lower symbolic physics, passing an already-native contribution through.

Parameters:

expr (Any)
backend (Any)
bindings (Mapping[str, Any] | None)
t (Any | None)

Return type:

Any

quchip.declarative.expr.materialize_array(expr, *, bindings=None, t=None)[source]¶

Materialize authored physics as a backend-independent JAX array.

Parameters:

expr (Any)
bindings (Mapping[str, Any] | None)
t (Any | None)

Return type:

Any

quchip.declarative.expr.materialize_scalar(expr, *, bindings=None)[source]¶

Materialize a scalar expression without coercing traced values.

Parameters:

expr (Any)
bindings (Mapping[str, Any] | None)

Return type:

Any