quchip.declarative.envelope_shape

Declarative envelope shape base class.

This module lives apart from quchip.declarative.models because importing BaseEnvelope pulls in quchip.control, which imports quchip.engine, which imports back into quchip.declarative — a cycle that a DeviceModel subclass, which does not need BaseEnvelope at all, should not have to pay for.

Classes

EnvelopeShape(**params)

Declarative base for pulse envelope shapes.

class quchip.declarative.envelope_shape.EnvelopeShape(**params)

Bases: BaseEnvelope

Declarative base for pulse envelope shapes.

Subclasses declare their parameters as annotated class attributes via parameter() (e.g. duration: Scalar = parameter(positive=True)) and implement value(), which returns the complex envelope at a given time. The waveform() method is supplied by this base and delegates to value(), keeping the signal pipeline JAX-traceable end-to-end.

Examples

>>> from quchip.declarative import EnvelopeShape, parameter, Scalar
>>> class LinearRise(EnvelopeShape):
...     duration: Scalar = parameter(positive=True)
...     amplitude: Scalar = parameter(default=1.0)
...     def value(self, t):
...         return self.amplitude * (t / self.duration)
>>> env = LinearRise(duration=20.0, amplitude=0.5)
>>> float(env.value(10.0))
0.25

Parameters:

params (Any)

validate()

Cross-field validation hook, run at the end of construction.

Default is a no-op. Subclasses override to enforce constraints that span multiple declared parameters (e.g. 2 * edge_duration <= duration). Checks must be gated on concrete scalars via quchip.utils.jax_utils.maybe_concrete_scalar() so traced parameters never force concretization.

Return type:

None

value(t)

Evaluate the envelope at time points t in ns.

Parameters:

t (Any) – Time or array of times in ns. May be a JAX tracer; the implementation must stay traceable (use quchip.declarative.qnp).

Returns:

The complex envelope value at t, matching the shape of t.

Return type:

Any

waveform(t, *, xp=None)

Evaluate value() through the BaseEnvelope waveform contract.

Parameters:

• t (Any) – Time or array of times in ns, coerced to an array before dispatch.

• xp (module or None, optional) – Array-namespace hint from the caller; ignored here since value() selects its own namespace via quchip.declarative.qnp.

Returns:

The complex envelope value at t.

Return type:

Any

to_dict()

Serialize the envelope type and declared parameter values.

Return type:

dict[str, Any]

classmethod from_dict(d)

Reconstruct the envelope from to_dict() output.

Parameters:

d (dict[str, Any])

Return type:

EnvelopeShape