Environments

Bases: Module

Abstract functional environment.

action_bound abstractmethod property

Actions are clipped to [-action_bound, action_bound].

action_dim abstractmethod property

Dimension of the continuous action vector.

horizon abstractmethod property

Number of control steps per episode.

observation_dim abstractmethod property

Dimension of the observation vector.

info(state)

Diagnostics of state (the same dictionary step puts in TimeStep.info).

Use it after rollout to read fidelity, energy, populations or leakage of the final state without stepping again.

reset(key) abstractmethod

Start a new episode.

step(state, action) abstractmethod

Advance one control interval.

Bases: Module

Everything needed to advance the environment.

Bases: Module

Output of reset/step.

Attributes:

Name	Type	Description
observation	Array	real-valued observation vector.
reward	Array	scalar reward.
done	Array	whether the episode terminated at this step.
info	dict[str, Array]	dictionary of named diagnostics (observable expectation values, ...).

Bases: Environment

Piecewise-constant control towards a target state.

Each step applies the action as constant control amplitudes for dt. The observation is the flattened real/imaginary parts of the quantum state plus the normalised time. The reward is the fidelity gain of the step, so the undiscounted return equals F(final) - F(initial).

Attributes:

Name	Type	Description
model	Model	physical model.
target	QArray	target state (ket or density matrix).
horizon	int	number of control steps.
dt	float	duration of each step.
action_bound	float	maximum control amplitude.
method	Method	dynamiqs ODE method used inside each control interval. The integrator step is independent of dt (adaptive by default).

duration property

Total episode duration horizon * dt.

rollout(actions, key=None)

Open-loop rollout of actions of shape (horizon, action_dim).

Returns the final state and the per-step rewards. Implemented with lax.scan so it is differentiable with respect to actions.

Bases: Environment

Piecewise-constant charging control of a quantum battery.

Works for any :class:~qenvs.models.Model that implements battery_hamiltonian(). The reward is the per-step gain of the chosen quantity, so the undiscounted return equals Q(final) - Q(initial) with Q the stored energy or the ergotropy. info reports energy, ergotropy, average charging power E(t) / t and purity every step.

Attributes:

Name	Type	Description
model	Model	physical model with a battery Hamiltonian.
horizon	int	number of control steps.
dt	float	duration of each step (control period; the integrator adapts inside it).
action_bound	float	maximum control amplitude.
reward	str	"energy" or "ergotropy".
method	Method	dynamiqs ODE method.

duration property

Total episode duration horizon * dt.

rollout(actions, key=None)

Open-loop rollout of actions of shape (horizon, action_dim) via lax.scan.

Bases: Environment

Piecewise-constant control towards a target gate (average gate fidelity reward).

Each step applies the action as constant control amplitudes for dt and composes the step propagator with the accumulated map. The reward is the gain of the average gate fidelity on the computational subspace (the first k levels, k = target.shape[0], or the basis states listed in subspace), so the undiscounted return equals F_final - F_initial with F_initial = F(identity, target).

The observation is the flattened real and imaginary parts of the accumulated map (2 d^2 numbers for U, 2 d^4 for S) plus the normalised time. info reports fidelity (average gate fidelity, Wood and Gambetta 2018), leakage (leakage rate out of the subspace), and the model observables evaluated on map(model.initial_state()); a model observable whose name clashes with fidelity or leakage is reported as state_<name>.

Attributes:

Name	Type	Description
model	Model	physical model (any :class:~qenvs.models.Model; units are the model's).
target	Array	(k, k) target unitary with k <= model.dim.
horizon	int	number of control steps.
dt	float	duration of each step (control period).
action_bound	float	actions are clipped to [-action_bound, action_bound].
method	Method	dynamiqs method for each step propagator. The default Expm() is exact for piecewise-constant controls; ODE methods (Tsit5()) integrate the propagator instead.
subspace	tuple[int, ...] | None	k basis indices spanning the computational subspace, in the order of the target's basis (e.g. (0, 1, 3, 4) for two qutrits in control (x) target order). None (default) means the first k levels.

duration property

Total episode duration horizon * dt.

map_dim property

Side of the accumulated map: d (unitary) or d^2 (superoperator).

n_comp property

Dimension k of the computational subspace (size of the target).

evolved_state(qstate)

The accumulated map applied to model.initial_state().

fidelity(qstate)

Average gate fidelity of the accumulated map against target.

leakage(qstate)

Leakage rate of the accumulated map out of the computational subspace.

rollout(actions, key=None)

Open-loop rollout of actions of shape (horizon, action_dim) via lax.scan.

Returns the final state (state.qstate is the full map) and the per-step rewards; differentiable with respect to actions.

step_propagator(action)

Propagator (U or S) of one control interval with constant action.

Task registry: qenvs.make("qubit/StateTransfer-v0").

Task ids follow the Gymnasium convention namespace/Name-vN. Bump N whenever a change could alter learning results (reward, observation, defaults); never silently change a released task.

TaskSpec dataclass

Metadata attached to a registered task.

make(task_id, *, observation=None, shots=None, diagnostics=None, observables=None, **kwargs)

Instantiate a registered task, forwarding kwargs to its factory.

observation, shots, diagnostics and observables select the observation mode and the finite-shot measurement of the task: if any of them is given, the task is wrapped in :class:qenvs.wrappers.observation.ObservationModel (see its documentation for the modes, the information boundary and the errors raised). If none is given the task is returned unwrapped, exactly as before.

register(task_id, factory, *, description, model, references=(), kwargs=None, units=None, reference=None)

Register a task factory under task_id.