# QEnvS > Physically validated quantum control environments (quantum batteries, qubit state transfer, open systems) for reinforcement learning and optimal control. Python package `qenvs`, built on JAX + dynamiqs. Apache-2.0. Tasks: `transmon/XGate-v0`, `transmon/SXGate-v0`, `transmon/CRGate-v0`, `qubit/StateTransfer-v0`, `battery/TwoLevel-v0`, `battery/Dicke-v0`, `battery/DickeLocal-v0`, `transfer/LambdaSTIRAP-v0`. Every model ships with analytic validation checks (86 in total: closed-form results, physical constraints, solver convergence, QuTiP cross-checks) that run as tests and are printed by `qenvs validate`. Environments are functional (jit/vmap/grad) with a Gymnasium adapter. Alpha: `pip install --pre 'qenvs==0.3.2a1'`. Explicit battery subsystems, endpoint diagnostics and an auditable control example are new in this alpha. ## Docs - [Overview and quickstart](https://beomdo-park.github.io/QEnvS/): install, functional API, gradient-based control, Gymnasium usage - [Getting started](https://beomdo-park.github.io/QEnvS/getting-started/): install (CPU, GPU), checking the installation, precision, troubleshooting - [Stability and versioning](https://beomdo-park.github.io/QEnvS/stability/): task-id versioning, API and CLI stability rules, supported Python / jax / OS versions - [Tutorial: X gate on a transmon](https://beomdo-park.github.io/QEnvS/tutorials/transmon-x-gate/): Gaussian pi pulse, DRAG sweep, GRAPE, T1/T2, pulse export in MHz, Gymnasium - [Model: transmon gates](https://beomdo-park.github.io/QEnvS/models/transmon/): tasks `transmon/XGate-v0`, `transmon/SXGate-v0`, multi-level transmon in ns / rad/ns (GHz, us kwargs), I/Q drive, T1/T2, leakage-aware average gate fidelity, DRAG - [Model: cross-resonance gate](https://beomdo-park.github.io/QEnvS/models/cross_resonance/): task `transmon/CRGate-v0`, two coupled transmons in ns / rad/ns, CR and cancellation drives, ZX(pi/2) on the computational subspace, leakage, T1/T2 - [Guide: bring your own Hamiltonian](https://beomdo-park.github.io/QEnvS/guides/custom-models/): `HamiltonianModel.from_operators`, generic validation, `qenvs validate --model` - [Guide: pulses for hardware toolchains](https://beomdo-park.github.io/QEnvS/guides/pulses/): `qenvs.pulses.Pulse`, JSON/NPZ, exact resampling, MHz, `Transmon.from_properties` - [Guide: uncertainty](https://beomdo-park.github.io/QEnvS/guides/uncertainty/): `ParameterRandomization` (episode-fixed model parameters, Normal / Uniform / TruncatedNormal with support checks, oracle), `ControlErrors` (gain, offset, step noise, clip fraction), the model parameter contract - [Guide: observation modes and robust evaluation](https://beomdo-park.github.io/QEnvS/guides/observation-and-evaluation/): `ObservationModel` (state, expectations, correlations, time; exact finite-shot measurement; information boundary), `qenvs.robust.evaluate` (mean, CVaR, bootstrap intervals and their scope) - [Guide: RL libraries](https://beomdo-park.github.io/QEnvS/guides/rl-libraries/): `GymnasiumEnv(normalize_actions=True)`, `GymnasiumVectorEnv`, SB3 and CleanRL usage, throughput - [Model: qubit battery](https://beomdo-park.github.io/QEnvS/models/qubit_battery/): task `battery/TwoLevel-v0`, open qubit with thermal bath, energy / ergotropy rewards, validation table - [Model: Dicke battery](https://beomdo-park.github.io/QEnvS/models/dicke/): task `battery/Dicke-v0`, N cells + cavity (Tavis-Cummings / Dicke), collective charging, Fock-cutoff caveats, validation table - [Model: Dicke battery with local dissipation](https://beomdo-park.github.io/QEnvS/models/dicke_local/): task `battery/DickeLocal-v0`, local emission, dephasing and pumping on every cell, permutation-invariant method, N <= 5 - [Model: Lambda system](https://beomdo-park.github.io/QEnvS/models/lambda_system/): task `transfer/LambdaSTIRAP-v0`, three-level STIRAP transfer with spontaneous emission, validation table - [Validation report](https://beomdo-park.github.io/QEnvS/validation/): every physics check with measured error, tolerance and margin, regenerated by each docs build (same as `qenvs validate --markdown`) - [Review log](https://beomdo-park.github.io/QEnvS/review-log/): adversarial review rounds, counterexamples found, fixes and the checks that now guard them - [Benchmarks](https://beomdo-park.github.io/QEnvS/benchmarks/): qubit state transfer and battery charging; provable optimum for closed resonant batteries, single-pulse baseline, GRAPE (jax.grad), vectorised PPO, reproduction commands - [Roadmap](https://beomdo-park.github.io/QEnvS/roadmap/): models and validation gates - [API: models](https://beomdo-park.github.io/QEnvS/api/models/): `Model`, `Transmon`, `HamiltonianModel`, `TwoLevel`, `QubitBattery`, `DickeBattery`, `LambdaSystem`, observables (energy, ergotropy, fidelity), `qenvs.gates` (targets, leakage-aware gate fidelity) - [API: environments](https://beomdo-park.github.io/QEnvS/api/envs/): `Environment` (with `info(state)`), `EnvState`, `TimeStep`, `StateTransfer`, `BatteryCharging`, `GateControl`, registry - [API: wrappers](https://beomdo-park.github.io/QEnvS/api/wrappers/): `GymnasiumEnv`, `GymnasiumVectorEnv`, `ParameterRandomization`, `ControlErrors`, `ObservationModel`, distributions (`Normal`, `Uniform`, `TruncatedNormal`), `Wrapper` - [API: robust evaluation](https://beomdo-park.github.io/QEnvS/api/robust/): `qenvs.robust.evaluate`, `stability`, `performance_metric`, and the key tree `qenvs.keys` - [API: endpoint trajectories](https://beomdo-park.github.io/QEnvS/api/trajectories/): `qenvs.trajectories.rollout_metrics`, physical amplitudes, explicit solver settings, right endpoints, jit/vmap/action gradients - [API: validation](https://beomdo-park.github.io/QEnvS/api/validation/): `CheckResult`, generic `model_checks` for any model ## Agent interface - CLI: `qenvs list --json`, `qenvs info --json`, `qenvs run --policy pi-pulse --json`, `qenvs validate --json`, `qenvs doctor --json` - [AGENTS.md](https://github.com/beomdo-park/QEnvS/blob/main/AGENTS.md): repository conventions for coding agents ## Source - [GitHub](https://github.com/beomdo-park/QEnvS) - [PyPI](https://pypi.org/project/qenvs/)