ATLAS Controls Lab

Reproducible controls, accelerated simulation, system identification, and model-fidelity evidence

Predict. Measure. Identify the mismatch. Update the model. Prove what improved.

Purpose · Platform · Mathematics · Experiments · Evidence · Documentation

Observed seed-0 simulation evidence generated directly from the locked benchmark runner by a reproducible script.

Important

ATLAS is a simulation-fidelity and controls research platform, not a flight-qualified autonomy stack. Results are claims about the declared models, scenarios, seeds, constraints, and metrics. PX4, ROS 2, acados, HIL, and flight boundaries are explicit; they are not presented as completed hardware validation.

ATLAS turns controls code into a falsifiable model of a physical vehicle. It runs the same declared case through canonical simulation and, when real evidence exists, an instrumented system; aligns both traces; identifies parameters on training data; measures held-out divergence; and promotes only traceable, eligible calibration back into the simulator. The controls stack remains substantial: a 17-state nonlinear quadrotor, geometric control, constrained MPC, an inertial ESKF, relative-degree-two CBF-QP safety, deterministic campaigns, immutable artifacts, regression gates, and exact-input replay.

The original PID, LQR, Kalman-filter, drone-attitude, and pure-pursuit simulations remain intact as transparent educational baselines.

What ATLAS is for

The expensive robotics failure is rarely that a controller equation was never written. It is that the model, firmware, frames, clocks, actuator dynamics, or test conditions changed between a clean simulation and the machine on the bench. ATLAS makes that gap measurable.

The target workflow is:

declare case → validate asset → run seeded predictions → ingest measured trace
             → align clocks and frames → quantify divergence in physical units
             → identify on training data → evaluate on held-out data
             → promote a checksummed calibration → gate future regressions

Agent-to-hardware assurance boundary

External agents may eventually discover devices and request bounded procedures through MHS, MCP, ROS 2, a command-line client, or a vendor API. ATLAS treats each of those as a transport adapter. The adapter cannot redefine the experiment, widen the command envelope, enter the high-rate flight-control loop, or replace PX4 and independent physical interlocks.

The planned boundary is:

agent intent → protocol adapter → normalized procedure request
             → ATLAS authorization and evidence supervisor
             → deterministic executor and device controller
             → trace, metrics, decision record, and replay bundle

The first stage is read-only telemetry in simulation and SITL. Write-capable requests require denial, approval, idempotency, timeout, abort, and provenance evidence. MHS is currently a possible adapter target, not a supported integration. The specification was not public when this trajectory was accepted. See Agent-to-hardware assurance and ADR 0002.

Today the complete software path exists, including asset QA, Experiment Schema v2, deterministic environment traces, MJX-JAX/MJX-Warp execution boundaries, hardware manifest and CSV ingestion, physical-unit fidelity metrics, paired uncertainty, actuator identification, and calibration overlays. The next evidence-bearing milestone is an instrumented IRIS actuator or vehicle dataset. Until that data exists, the identification and fidelity results are software-validated with synthetic fixtures and are not hardware claims.

Run it in 60 seconds

ATLAS supports Python 3.11 through 3.13. uv.lock is the authoritative dependency graph.

git clone https://github.com/Vedangalle/atlas-controls-lab.git
cd atlas-controls-lab

uv sync --locked --no-editable --extra dev --extra examples
uv run pytest -q
uv run atlas-asset assets/atlas_x4/manifest.json
uv run atlas submit configs/benchmarks/ci-platform.json --workers 2

The asset command verifies the canonical MJCF material, SI inertias, frame tree, and actuator contract without requiring MuJoCo. The final command runs a six-rollout controller/scenario/seed matrix and prints its content-derived Experiment Schema v2 ID. Traces, metrics, provenance, checksums, and the query index are written under artifacts/atlas/. For a conventional environment:

python -m pip install ".[examples]"

After changing package source, refresh the non-editable development installation:

uv sync --locked --no-editable --extra dev --extra examples \
  --reinstall-package atlas-controls-lab

From specification to replay

The unit of work in ATLAS is a declared experiment. One Schema v2 JSON file fixes the controllers, scenarios, seeds, safety settings, platform, executor, environment, asset, ODD material, evaluator, artifact policy, resources, and limits before execution begins.

specification → canonical experiment ID → independent seeded rollouts
             → local worker processes → immutable attempt artifacts
             → independent evaluation → regression gate → exact-input replay

# Resume-safe parallel execution
uv run atlas submit configs/benchmarks/ci-platform.json \
  --store artifacts/atlas --workers 4

# The checked-in protocol resolves to this stable ID
uv run atlas status exp_de2307f7f453b7944a4733bf --store artifacts/atlas

# Fail when tracking, control, or safety moves beyond declared tolerances
uv run atlas compare exp_de2307f7f453b7944a4733bf \
  --store artifacts/atlas \
  --baseline configs/baselines/ci-platform.json

# Audit and replay one recorded attempt
uv run atlas verify att_<id> --store artifacts/atlas
uv run atlas reproduce att_<id> --store artifacts/atlas

An experiment ID is derived from canonical content. A rollout ID fixes one controller, scenario, seed, and safety mode. Every execution receives a separate attempt ID, so a retry never overwrites the evidence it is meant to explain. Completed rollouts resume without rerunning; failures, solver errors, timeouts, lost workers, and publication failures remain explicit.

Read the Schema v2 contract and the full experiment, artifact, regression, and replay contract.

Research thesis

A controller is not better because one trajectory looks clean. It is better only when it outperforms a declared baseline under the same plant, reference, uncertainty, constraints, seeds, metrics, and success criteria.

ATLAS is built around one question:

Can controls, estimation, and safety methods be compared without changing the experimental world beneath them?

That question changes the unit of work from an isolated plotting script to an experiment with evidence.

Conventional controls demo	ATLAS research contract
One controller and one successful run	Interchangeable methods over a shared plant
Implicit frames and units	Declared ENU world, FLU body, SI units
Noise chosen inside the script	Seeded scenario and uncertainty definitions
Plot as the final output	Trace, metrics, provenance, checksums, and indexed artifacts
Solver fallback may be invisible	Infeasibility and solver failure are explicit
Simulation result may read like deployment evidence	Claim boundaries are documented with the result

What the platform asks

• Does tracking remain stable under motor lag, saturation, drag, wind, mass mismatch, and measurement noise?
• Is estimator error statistically consistent with its reported covariance?
• Are safety interventions feasible, traceable, and free of silent fallbacks?
• Can controller and solver latency be measured without changing the experiment?
• Can CI catch a numerical regression before the expected result is quietly replaced?
• Can one failed attempt be replayed from its exact inputs and material provenance?

System architecture

The architecture separates truth, state information, decision-making, safety authority, actuation, and evidence. No algorithm owns the physics or the success criteria used to evaluate it.

Boundary	Owns	Does not own
Scenario protocol	Reference, seed, uncertainty, constraints, success rules	Controller-specific tuning logic
Dynamics	Continuous plant, actuator state, disturbances, integration	Measurement interpretation or control policy
Estimation	Nominal state, local error state, covariance, updates	Plant truth
Control	Nominal acceleration, wrench, or rotor command	Safety-set definition or benchmark scoring
Safety	Projection onto hard CBF constraints	A hidden uncertified fallback
Experiment platform	Rollout identity, execution state, trace, metrics, provenance, artifact integrity, replay	Redefinition of plant or algorithm mathematics

The default controller benchmark currently uses simulated state with declared additive position and velocity noise. The ESKF is validated in an independent consistency campaign but is not yet closed into the default control benchmark. This boundary is intentional and prevents estimator-in-the-loop performance from being implied before it has been measured.

Research invariants

1. Shared physics. Competing controllers do not receive method-specific plants.
2. Replayable uncertainty. Randomness enters through declared deterministic seeds.
3. Hard failure semantics. Failed MPC or CBF optimization raises an error.
4. Evidence before claims. Traces and metrics precede interpretation.
5. Simulation is not flight. Software interfaces do not establish SITL, HIL, or hardware safety.

Detailed component ownership, state flow, frames, and units are recorded in Architecture.

Mathematical core

All equations below describe implemented simulation methods unless a boundary is explicitly identified.

17-state nonlinear quadrotor

The world frame is ENU; the body frame is FLU. The scalar-first quaternion $q_{WB}$ rotates body-frame vectors into the world frame. The plant state and input are

$$\mathbf{x} = \begin{bmatrix} \mathbf{p}^{W} & \mathbf{v}^{W} & \mathbf{q}_{WB} & \boldsymbol{\omega}^{B} & f_1 & f_2 & f_3 & f_4 \end{bmatrix}^{\mathsf T} \in \mathbb{R}^{17}, \qquad \mathbf{u} = \mathbf{f}^{\mathrm{cmd}} \in \mathbb{R}^{4}.$$

With $R_{WB}=R(q_{WB})$, $e_3=[0,0,1]^{\mathsf T}$, linear drag $D_v$, angular damping $D_\omega$, and an X-configuration allocation $\mathcal{A}\mathbf{f}=[T,\boldsymbol{\tau}^{\mathsf T}]^{\mathsf T}$, the implemented continuous dynamics are

$$\begin{aligned} \dot{\mathbf{p}}^W &= \mathbf{v}^W, \\\ m\dot{\mathbf{v}}^W &= m\mathbf{g}^W + R_{WB}e_3\sum_{i=1}^{4}f_i - D_v\mathbf{v}^W + \mathbf{F}_{\mathrm{ext}}^W, \\\ \dot{q}_{WB} &= \tfrac{1}{2}q_{WB}\otimes \begin{bmatrix}0 & (\boldsymbol{\omega}^{B})^{\mathsf T}\end{bmatrix}^{\mathsf T}, \\\ J\dot{\boldsymbol{\omega}}^B &= \boldsymbol{\tau}^B - \boldsymbol{\omega}^B \times J\boldsymbol{\omega}^B - D_\omega\boldsymbol{\omega}^B + \boldsymbol{\tau}_{\mathrm{ext}}^B, \\\ \dot{f}_i &= \frac{\mathrm{clip}(f_i^{\mathrm{cmd}})-f_i}{\tau_m}. \end{aligned}$$

RK4 advances the reference model. Each step normalizes the quaternion and projects rotor state onto declared thrust bounds. The model intentionally excludes blade flapping, voltage sag, propeller inflow, ground effect, and flexible modes.

Geometric tracking on SE(3)

The outer loop forms a desired translational acceleration and force:

$$\begin{aligned} \mathbf{e}_p &= \mathbf{p}-\mathbf{p}_d, & \mathbf{e}_v &= \mathbf{v}-\mathbf{v}_d, \\\ \mathbf{a}_c &= -K_p\mathbf{e}_p-K_v\mathbf{e}_v+\mathbf{a}_d, & \mathbf{A} &= m(\mathbf{a}_c+ge_3). \end{aligned}$$

The normalized force defines the desired body $z$-axis; desired yaw completes $R_d$. The attitude and angular-rate errors are

$$\mathbf{e}_R = \tfrac{1}{2} \left(R_d^{\mathsf T}R-R^{\mathsf T}R_d\right)^\vee, \qquad \mathbf{e}_\omega = \boldsymbol{\omega}-R^{\mathsf T}R_d\boldsymbol{\omega}_d.$$

Collective thrust projects $\mathbf{A}$ onto the current body $z$-axis. The requested moment applies attitude and rate feedback plus rigid-body gyroscopic compensation. Allocation maps the requested wrench to four bounded rotor thrusts and records saturation and residual error.

Constrained translational MPC

The portable reference MPC uses an exact zero-order-hold discretization of the six-state double integrator. Over horizon $N$, it solves

$$\begin{aligned} \min_{\mathbf{u}_{0:N-1}}\quad & \sum_{k=0}^{N-1} \left( \lVert\mathbf{x}_k-\mathbf{x}^{\mathrm{ref}}_k\rVert_Q^2 + \lVert\mathbf{u}_k-\mathbf{u}^{\mathrm{ref}}_k\rVert_R^2 \right) + \lVert\mathbf{x}_N-\mathbf{x}^{\mathrm{ref}}_N\rVert_{Q_f}^2 \\\ \text{subject to}\quad & \mathbf{x}_{k+1}=A_d\mathbf{x}_k+B_d\mathbf{u}_k, \\\ & -\mathbf{v}_{\max}\leq\mathbf{v}_k\leq\mathbf{v}_{\max}, \\\ & -\mathbf{a}_{\max}\leq\mathbf{u}_k\leq\mathbf{a}_{\max}. \end{aligned}$$

SciPy SLSQP is the verified portable backend and retains a shifted warm start. The optional acados SQP-RTI backend shares the six-state outer-loop interface but requires a separately built acados toolchain.

Exponential CBF-QP safety

For a spherical obstacle centered at $\mathbf{p}_o$ with protected radius $r_s$,

$$h(\mathbf{p}) = \lVert\mathbf{p}-\mathbf{p}_o\rVert_2^2-r_s^2.$$

Under $\dot{\mathbf{p}}=\mathbf{v}$ and $\dot{\mathbf{v}}=\mathbf{a}$, ATLAS projects nominal acceleration through

$$\begin{aligned} \mathbf{a}^{*} &= \arg\min_{\mathbf{a}} \tfrac{1}{2}\lVert\mathbf{a}-\mathbf{a}_{\mathrm{nom}}\rVert_2^2, \\\ \text{subject to}\quad \ddot{h} &+2\zeta\omega_n\dot{h} +\omega_n^2h \geq 0, \\\ -\mathbf{a}_{\max} &\leq \mathbf{a} \leq \mathbf{a}_{\max}. \end{aligned}$$

Lower and upper altitude bounds use the same relative-degree-two construction. Infeasibility is a hard solver failure. The formal condition assumes a continuous double integrator, exact state, continuous enforcement, and feasibility; sampled nonlinear simulation is an empirical stress test, not a formal proof.

15-error-state inertial ESKF

The filter separates its 16-element nominal state from a 15-dimensional local error:

$$\hat{\mathbf{x}}_{\mathrm{nom}} = \begin{bmatrix} \hat{\mathbf{p}} & \hat{\mathbf{v}} & \hat{\mathbf{q}} & \hat{\mathbf{b}}_a & \hat{\mathbf{b}}_g \end{bmatrix}^{\mathsf T}, \qquad \delta\mathbf{x} = \begin{bmatrix} \delta\mathbf{p} & \delta\mathbf{v} & \delta\boldsymbol{\theta} & \delta\mathbf{b}_a & \delta\mathbf{b}_g \end{bmatrix}^{\mathsf T} \in\mathbb{R}^{15}.$$

Bias-corrected IMU measurements propagate the nominal state. Van Loan discretization propagates covariance; position and orientation updates use linear solves, Joseph-form covariance updates, local quaternion injection, covariance reset, and positive-semidefinite numerical projection.

For simulated truth, consistency is evaluated with

$$\epsilon_{\mathrm{NEES}} = \delta\mathbf{x}^{\mathsf T}P^{-1}\delta\mathbf{x}, \qquad \epsilon_{\mathrm{NIS}} = \mathbf{r}^{\mathsf T}S^{-1}\mathbf{r}.$$

The complete derivations and numerical conventions are in Methods.

Implemented research stack

Layer	Implemented method	Verified boundary
Assets	Versioned MJCF manifest, material digest, inertia/frame/actuator QA, MuJoCo compile gate	Canonical X4 reference asset passes structural and MuJoCo 3.10 compilation checks
Dynamics	17-state 6-DoF quadrotor on SE(3), motor lag, drag, saturation, external wrench	RK4 convergence, hover equilibrium, quaternion invariants, closed-loop simulation
Control	Anti-windup PID, validated LQR, geometric SE(3), constrained translational MPC	Analytical checks, failure handling, closed-loop regression
Estimation	15-error-state inertial ESKF with position and attitude updates	PSD covariance, stationary IMU, NIS and NEES campaigns
Safety	Hard relative-degree-two exponential CBF-QP	Constraint satisfaction, intervention, infeasibility reporting
Optimization	SciPy reference MPC and optional acados SQP-RTI nonlinear outer loop	SciPy implementation validated; acados requires an external build
Environment	Versioned observation/action/units contract with deterministic Gymnasium-style reset/step	reset, clipping, termination, seed replay, and episode trace tests
Acceleration	Differentiable JAX dynamics plus MJX-JAX and GPU-only MJX-Warp paths	canonical-asset exact replay and CPU parity; no committed GPU throughput claim
Fidelity	Hardware manifest/CSV ingestion, clock alignment, physical-unit metrics, paired uncertainty, actuator ID, calibration promotion	deterministic synthetic validation; hardware evidence remains outstanding
Deployment	PX4 frame conversions, ROS 2 offboard publisher, pinned PX4 simulation configuration	Frame conversions tested; live SITL/HIL remains external evidence
Evidence	Content-addressed experiments, parallel seeded rollouts, immutable traces, checksummed artifacts, exact-input replay	Python 3.11–3.13 workflow and fixed-seed CI regression gate

Reproduce the research track

The predeclared matrix is configs/benchmarks/research.json. Artifact semantics, timing rules, and success criteria are specified in Benchmarking.

Run or resume the entire matrix through the platform:

uv run atlas submit configs/benchmarks/research.json \
  --store artifacts/research \
  --workers 4

Robust tracking under uncertainty

uv run atlas-bench \
  --scenario wind_mass \
  --controller geometric \
  --seeds 20 \
  --output artifacts/wind-mass.json

This campaign applies 15% mass mismatch, a constant world-frame wind force, and seeded position and velocity measurement noise.

Safety-filtered obstacle avoidance

uv run atlas-bench \
  --scenario obstacle_avoidance \
  --controller geometric \
  --safety \
  --output artifacts/obstacle-cbf.json

The CBF-QP modifies nominal acceleration only when required by the declared safe set. An infeasible problem terminates the run instead of substituting an uncertified command.

Constrained MPC cascade

uv run atlas-bench \
  --scenario hover \
  --controller mpc-geometric \
  --output artifacts/mpc-hover.json

The result records solver p50, p95, and p99 wall time together with state, control, and tracking metrics.

ESKF consistency

uv run atlas-estimator-bench \
  --seeds 5 \
  --duration 3.0 \
  --output artifacts/eskf-consistency.json

NEES, NIS, and empirical 95% interval coverage are consistency diagnostics under the declared simulated noise model. They are not hardware accuracy claims.

Each integration sample follows the same path: reference and measured state, nominal control, optional safety projection, rotor allocation, nonlinear propagation, and trace append. Campaign aggregation occurs only after every seed has produced a complete result or an explicit failure.

Validation snapshot

The following controls results were simulated and observed locally on 2026-08-02. The platform, asset, fidelity, and optional-backend evidence was revalidated locally on 2026-08-23 with CPython 3.12.7 and the locked dependency graph:

Experiment	Observed result
Geometric hover recovery	position RMSE 0.1282 m; final error 2.17 µm
Constrained MPC/geometric hover	position RMSE 0.1354 m; final error 0.055 mm; solver p99 6.69 ms
Wind and 15% mass mismatch, 20 seeds	100% success; mean position RMSE 0.2273 m; standard deviation 0.0006 m
Obstacle avoidance with CBF-QP	zero constraint violations; minimum barrier 0.0379 m²
ESKF consistency, 5 seeds over 3 s	mean NEES 15.63; 100% NEES 95% coverage; mean NIS 3.22; 95.24% NIS coverage
Canonical MJX-JAX CPU smoke (2026-08-23)	exact replay; maximum CPU parity error 2.47e-8; gpu_executed=false
Platform CI campaign	6/6 seeded rollouts completed; 54 direction-aware regression comparisons passed

Repository validation:

• 111 tests passed, including installed optional-backend and multiprocess paths;
• 85.05% branch-aware package coverage against an enforced 85% floor;
• Ruff lint and formatting passed;
• strict mypy passed across 49 source files;
• source distribution and wheel built successfully;
• the wheel installed and imported in a clean isolated environment;
• repository metadata, local Markdown links, lockfile integrity, and diff checks passed.

Exact commands, exclusions, and evidence limitations are recorded in Validation.

Evidence artifact contract

atlas submit publishes one immutable directory per attempt. A successful attempt contains result.json, separately addressable metrics.json, the full numeric trace.npz, and manifest.json. The manifest records source and runtime provenance and the SHA-256 digest and byte count of every artifact. index.sqlite3 tracks experiments, rollouts, retries, terminal states, and scientific failures without replacing the files as the source evidence.

atlas evaluate recomputes metrics from the stored trace. atlas verify recomputes artifact digests. atlas reproduce first checks material provenance, executes the exact rollout again, and compares state, control, reference, time, and non-timing metrics under declared numerical tolerances.

The original atlas-bench command remains a useful compact campaign interface. Every result uses a versioned JSON schema and records enough context to interpret the run.

This is an abridged form of the observed hover output:

{
  "schema_version": 1,
  "scenario": "hover",
  "controller": "geometric",
  "seed_count": 1,
  "summary": {
    "success_rate": 1.0,
    "position_rmse_mean": 0.1282496085026583
  },
  "results": [
    {
      "schema_version": 1,
      "scenario": {
        "name": "hover",
        "seed": 0,
        "duration": 6.0,
        "step_size": 0.01
      },
      "metrics": {
        "position_rmse": 0.1282496085026583,
        "final_position_error": 2.167621485817417e-06,
        "saturation_fraction": 0.03,
        "success": true
      },
      "sample_count": 600
    }
  ]
}

Campaign summaries aggregate seed-level artifacts without discarding failure status.

Optional acceleration and optimization

MJX-JAX and MJX-Warp

uv sync --locked --no-editable --extra dev --extra warp \
  --reinstall-package atlas-controls-lab
uv run pytest tests/unit/test_optional_backends.py -q

uv run atlas-mjx-bench assets/atlas_x4/model.xml \
  --implementation jax \
  --batch-size 1024 \
  --warmup-steps 10 \
  --measured-steps 100 \
  --output artifacts/performance/mjx-jax.json

The report separates initialization/compilation, warm-up, measured synchronized steps, throughput, aggregate real-time factor, exact replay, CPU parity, package versions, device, and model digest. MJX-Warp requires an NVIDIA GPU and refuses to execute on a CPU-only host. The JAX backend also exposes differentiable single-step dynamics, batched propagation, rollouts, and discrete state/control Jacobians.

Feed measured behavior back into the model

ATLAS normalizes instrumented traces without changing the raw log, fits actuator parameters on a chronological training split, diagnoses the result on held-out data, and creates a checksummed simulator overlay only after promotion checks pass.

uv run atlas-fidelity ingest hardware-run.csv \
  --columns configs/hardware/trace-columns.json \
  --hardware-manifest hardware-manifest.json \
  --output artifacts/hardware/run-001.npz

uv run atlas-fidelity identify-actuator actuator-bench.csv \
  --time-column time_s --command-column command \
  --thrust-column thrust_n --voltage-column voltage_v \
  --output artifacts/hardware/actuator-fit.json

uv run atlas-fidelity promote-actuator artifacts/hardware/actuator-fit.json \
  --output artifacts/hardware/actuator-overlay.json

The detailed measurement, alignment, metric, identification, uncertainty, and claim boundaries are in Simulation fidelity platform and Hardware and HIL evidence protocol.

acados

uv sync --locked --no-editable --extra dev --extra mpc \
  --reinstall-package atlas-controls-lab

CasADi is locked by the optional extra. acados_template must come from an external acados source installation. An acados timing claim requires compiler, target processor, generated code, warm-up, and solver-status metadata.

PX4 and ROS 2 boundary

ATLAS includes:

• tested ENU/NED position and vector transforms;
• tested FLU/FRD body-frame transforms;
• quaternion conversion at the PX4 boundary;
• a ROS 2 offboard setpoint publisher with explicit arming/offboard sequencing;
• a pinned PX4 simulation container definition.

These components establish a software boundary. They do not establish a successful connection, arming sequence, SITL run, HIL run, or safe flight. Follow the staged procedure in PX4 integration.

Educational baselines

The five original examples remain intentionally simple and independent from the research package:

Baseline	Command	Output
PID mass-spring-damper	uv run python notebooks/01_pid_mass_spring_damper.py	position, error, control effort
Inverted-pendulum LQR	uv run python notebooks/02_inverted_pendulum_lqr.py	angle, cart position, control
1D Kalman tracking	uv run python notebooks/03_kalman_filter_1d_tracking.py	position and velocity estimates
Drone attitude PID	uv run python notebooks/04_drone_attitude_pid.py	roll response, angular rate, torque
Pure pursuit	uv run python notebooks/05_path_tracking_pure_pursuit.py	path, tracking error, animation

Legacy pure-pursuit simulation retained as a transparent baseline.

Generated figures are stored in figures/ and the animation in media/.

Repository map

atlas-controls-lab/
├── assets/atlas_x4/    # canonical MJCF and versioned model manifest
├── src/atlas_controls/
│   ├── assets/         # manifest loading, model QA, compile validation
│   ├── backends/       # JAX, MJX-JAX, MJX-Warp, synchronized benchmark
│   ├── benchmarks/     # scenarios, campaigns, metrics, artifact CLI
│   ├── controllers/    # PID, LQR, geometric control, MPC, acados
│   ├── core/           # interfaces, geometry, validation, integration
│   ├── dynamics/       # nonlinear quadrotor plant
│   ├── environments/   # versioned policy-facing reset/step contract
│   ├── estimation/     # inertial ESKF
│   ├── experiments/    # execution, artifacts, provenance, regression, replay
│   ├── fidelity/       # hardware traces, alignment, metrics, ID, calibration
│   ├── integrations/   # PX4 frames and ROS 2 offboard boundary
│   └── safety/         # exponential CBF-QP
├── tests/
│   ├── unit/
│   └── integration/
├── configs/            # experiments, baselines, and hardware templates
├── deploy/px4/         # pinned simulation boundary
├── docs/               # methods, evidence, deployment, limitations
├── scripts/            # reproducible figure and animation generation
├── notebooks/          # legacy educational simulations
├── figures/            # deterministic legacy plots
├── media/              # research validation figure and animations
└── LICENSE             # MIT license

Documentation

Document	Purpose
Architecture	Component boundaries, data flow, states, frames, and units
Fidelity platform	Asset-to-hardware model-closure workflow and current evidence
Asset pipeline	MJCF manifest, inertial/frame/actuator QA, and change protocol
Experiment Schema v2	Explicit execution/evidence fields, identity, and v1 migration
Hardware evidence	IRIS data boundary, actuator bench, HIL gates, and promotion criteria
Claims registry	Supported, unsupported, and excluded claims with evidence gates
Fidelity-first ADR	Accepted trajectory, identity/evidence rules, and rejected alternatives
Agent-to-hardware assurance	Protocol-neutral request, authorization, control-authority, and IRIS pilot boundary
Agent-hardware ADR	Accepted separation between external orchestration and deterministic device authority
Methods	Equations, discretization, control, estimation, and safety
Benchmarking	Scenario protocol, metrics, latency, seeds, artifact schema
Experiment platform	Experiment identity, parallel execution, storage, regression, and replay
ATLAS v1 completion contract	Users, supported December stack, required proof, exclusions, and release gate
December 2026 roadmap	Authoritative task, gate, evidence, risk, and weekly review control plane
Reproducibility	Locked environments, optional extras, and run records
Validation	Exact local evidence and unvalidated external boundaries
PX4 integration	Coordinate transforms, offboard sequence, staged safety procedure
Limitations	Model limits, solver limits, and claims ATLAS does not make
Contributing	Numerical, testing, documentation, and evidence expectations

Responsible interpretation

The current evidence supports statements about deterministic software behavior under the documented simulation models. It does not establish:

• aerodynamic fidelity outside the implemented rigid-body model;
• fidelity to the IRIS vehicle or any hardware-derived parameter value;
• GPU throughput from the local CPU MJX smoke run;
• closed-loop estimator/controller performance;
• a continuous-time safety guarantee for sampled nonlinear dynamics;
• real-time acados performance on a named target computer;
• PX4 SITL, HIL, or airframe compatibility;
• robustness to sensor faults, communication loss, or compute starvation;
• flight safety or regulatory compliance.

See Limitations before extending a result beyond its experimental scope.

Research foundations

The implementation is informed by:

• T. Lee, M. Leok, and N. H. McClamroch, “Geometric Tracking Control of a Quadrotor UAV on SE(3),” for the attitude and position-control structure;
• J. Solà, “Quaternion Kinematics for the Error-State Kalman Filter,” for quaternion and error-state conventions;
• A. Ames et al., “Control Barrier Function Based Quadratic Programs for Safety Critical Systems,” for the safety-filter formulation.

These references motivate the methods; passing ATLAS benchmarks is still required for claims about this implementation.

Roadmap

The authoritative December 2026 schedule, completion gates, and evidence ledger are maintained in the tracked roadmap workbook and operating protocol. The checklist below is only a public summary.

• Installable, typed, locked research package
• SE(3) quadrotor, geometric control, and ESKF
• Constrained MPC, optional acados backend, and CBF-QP safety
• Deterministic campaigns and versioned evidence schema
• Content-addressed experiment and rollout contracts
• Parallel, resumable local execution with explicit terminal states
• Checksummed traces, metrics, manifests, provenance, and a query index
• Independent re-evaluation, fixed-seed CI regression, and exact-input replay
• Canonical MJCF asset manifest with structural and MuJoCo compile QA
• Backend-neutral environment/trace contract and Experiment Schema v2 migration
• MJX-JAX benchmark, exact replay, CPU parity, and GPU-only MJX-Warp boundary
• Hardware manifests, trace ingestion, physical-unit fidelity metrics, and uncertainty
• Held-out actuator identification and checksummed simulator calibration overlays
• PX4/ROS 2 software boundaries
• Run the declared MJX workload on an NVIDIA GPU and commit the report
• Ingest the first instrumented IRIS actuator/vehicle dataset
• Demonstrate held-out divergence reduction after a hardware-derived calibration
• Add a leased remote-worker backend and object-store artifact plane
• Close the benchmark control loop through the ESKF
• Run acados-versus-reference timing on a declared target computer
• Validate PX4 SIH/SITL on a reproducible Linux host
• Validate live ROS 2 compatibility against a pinned px4_msgs release
• Conduct documented HIL testing without propellers
• Conduct controlled flight experiments with an approved safety procedure

Citation

Machine-readable project metadata is available in CITATION.cff.

@software{alle_atlas_controls_lab_2026,
  author = {Alle, Vedang},
  title = {ATLAS Controls Lab},
  year = {2026},
  url = {https://github.com/Vedangalle/atlas-controls-lab}
}

License

ATLAS Controls Lab is released under the MIT License.