crazyflow
Non-obvious traps and conventions in the crazyflow drone simulator. Use when working
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/learnsyslab/crazyflow with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/learnsyslab/crazyflow'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/learnsyslab--crazyflow)HTML
<a href="/listings/learnsyslab--crazyflow"><img src="/api/listings/learnsyslab--crazyflow/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
pip install crazyflow # CPU pip install "crazyflow[gpu]" # GPU (Linux x86-64, CUDA 12)
Developer install with editable install ([pixi](https://pixi.sh/) recommended):
git clone https://github.com/learnsyslab/crazyflow.git cd crazyflow pixi shell
Or with [uv](https://docs.astral.sh/uv/):
git clone https://github.com/learnsyslab/crazyflow.git cd crazyflow uv sync # core + dev tooling (tests, docs, ruff)
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 100 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: crazyflow
- description: Non-obvious traps and conventions in the crazyflow drone simulator. Use when working
- in the crazyflow codebase, adding a dynamics model or drone platform, reusing the dynamics or
- controllers outside Sim for estimation or MPC, or writing code under jax.jit, grad or vmap.
- ---
- # Crazyflow
- Settings are in `pyproject.toml`, layout in the tree, API reference in `docs/`.
- ## Conventions
- - Ruff settings live in `pyproject.toml` and must pass before committing.
- - Dynamics and controllers follow the array API standard. Take the namespace from the inputs with
- `array_namespace(...)`, do all math through it, coerce bound parameters with `to_xp`, and never
- import `numpy` into a computation path.
- - `crazyflow/control/mellinger/params.toml` deliberately holds values that differ from the true
- physical constants in `crazyflow/dynamics/*/params.toml`, reproducing the real firmware. Do not
- unify them.
- ## Testing
- ```bash
- pixi run -e tests tests # what CI runs
- pixi run -e tests test-docs # every example in docstrings and docs
- ```
- Use pixi, not uv. `pixi run <cmd>` resolves task names only, so arbitrary commands need `-e tests`.
- - `addopts = "-m 'not render'"` deselects every render test, and `tests/unit/test_visualizations.py`
- is `@skip_if_headless` without the marker, so it is skipped silently without `DISPLAY`. Rendering
- regressions pass CI green. Run `-m render` locally with a display.
- - Docs and docstrings are executable. The markdown runner catches exceptions but never compares
- output, so a `print` with the result in a trailing comment proves nothing. Output that must be
- checked goes in a `pycon` fence with `>>>` prompts, which doctest picks up.
- - `tests/integration/test_examples.py` runs every script under `examples/`, so a new example is a
- new test.
- - `tests/conftest.py` forces JAX's persistent cache on at `/tmp/jax_cache-<uid>`, shared across
- branches. Delete it when failures make no sense.
- - Request the `device` fixture rather than a GPU marker. It falls back to CPU silently, so
- `gpu-tests` asserts nothing about placement on a machine without CUDA.
- ## Adding a dynamics model or drone
- Grepping the name of an existing model or drone finds every registration site, except when matching
- against all models in the simulation's `build_control_fns`.
- Define the function in `dynamics.py` and never in the package `__init__.py`, because
- `load_fn_params` derives the model name from `fn.__module__.split(".")[-2]`. `parametrize`
- binds exactly the keyword-only parameters after the bare `*`, so anything before it is never bound.
- `Drone` in `crazyflow/drones/__init__.py` is a `StrEnum` with one member per MJCF file in
- `crazyflow/drones`, asserted on import. A model supports a drone when its
- `crazyflow/dynamics/<model>/params.toml` has a section for it. The commented example at the
- top of each file lists the keys. `supported_drones` and `supported_dynamics` report the pairs, and the
- tests only run those. Only `gravity_vec` is global, in `crazyflow/dynamics/params.toml`.
- Registration alone produces roughly 40 parametrized tests. These do not include derivatives tests.
- ## Using dynamics and controllers outside Sim
- Pure, batched, array-API functions with no dependency on `Sim`.
- - Import crazyflow before scipy. `crazyflow/__init__.py` sets `SCIPY_ARRAY_API=1` and imports scipy
- immediately, and scipy cannot be reconfigured once loaded. Transitive imports through acados or
- sklearn trigger this too.
- - `dynamics` and `control` each have `load_params(name, drone)`, returning everything defined for
- the drone, and `load_fn_params(fn, drone)`, which filters to the signature of `fn` and
- drops the rest. Additional platform data is stored as a comment in the drone MJCF.
- - `parametrize` returns a `functools.partial` whose `keywords` dict is shared by every reference to
- it. Call `parametrize` again for an independent copy.
- - Leading batch dimensions, trailing feature axis. `quat` is scalar-last xyzw, `force` is `(..., 1)`
- rather than a scalar, `ang_vel` is body frame.
- - `ctrl_freq` scales only the integral and derivative terms, so it must match your real loop rate.
- Under jit, initialize integral states to zeros rather than `None`, since the pytree structure
- change forces a recompile.
- - `symbolic_dynamics` monkey-patches module-global symbols while building, so it is not reentrant.
- Do not build two concurrently.
- ## The functional API and jit
- `Sim` rebinds `sim.data` as a Python side effect that JAX cannot trace, so anything inside `jit`,
- `grad`, `vmap` or `scan` must use `crazyflow.sim.functional` with `Sim` only as the builder. See
- [`functional-api.md`](docs/user-guide/functional-api.md).
- - **After editing a pipeline, call `build_step_fn()` or `build_reset_fn()` again.** The builders
- snapshot the stages, so a later edit is silently ignored and the stage never runs.
- - `n_steps` is static, so each distinct value compiles separately. Build once and reuse.
- - `states.force` and `states.torque` are inputs, not outputs, and nothing clears them, so writing
- them applies a persistent disturbance.
- - Mutating state does not invalidate `core.mjx_synced`, so `contacts()` can query stale geometry.
- Set the flag false yourself.
- - Gradients vanish at `clip_floor_pos` (`jnp.where` on floor contact) and at any saturation bound.
- ## Splats
- `attach_splats` performs no calibration. Both `.ply` files must already sit in the simulator's
- frames, the scene in the MuJoCo world frame at metric scale and the drone in its body frame. An
- uncalibrated splat looks correct alone but does not match the simulated geometry. See
- [`splat-rendering.md`](docs/user-guide/splat-rendering.md).
README.md · README · 119 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <img src="https://github.com/learnsyslab/crazyflow/raw/main/docs/img/logo.svg" alt="Crazyflow Logo" width="300"><br>
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://github.com/learnsyslab/crazyflow/raw/main/docs/img/logo_text_white.svg">
- <img src="https://github.com/learnsyslab/crazyflow/raw/main/docs/img/logo_text_black.svg" alt="Crazyflow" width="500">
- </picture>
- </p>
- <div align="center">
- --------------------------------------------------------------------------------
- **Fast, parallelizable simulations of quadrotor drones with JAX.**
- [](https://www.python.org)
- [](https://arxiv.org/abs/2606.01478)
- [](https://github.com/learnsyslab/crazyflow/actions/workflows/testing.yml)
- [](https://github.com/learnsyslab/crazyflow/actions/workflows/fuzzing.yml)
- [](https://github.com/learnsyslab/crazyflow/actions/workflows/ruff.yml)
- [](https://learnsyslab.github.io/crazyflow)
- </div>
- Crazyflow is a research simulator for quadrotors. It runs batched, differentiable simulations on CPU and GPU via JAX, with analytical and abstracted dynamics.
- ```python
- import numpy as np
- from crazyflow.sim import Sim
- from crazyflow.control import Control
- from scipy.spatial.transform import Rotation as R
- sim = Sim(n_worlds=4096, n_drones=1, control=Control.state)
- cmd = np.zeros((4096, 1, 16))
- cmd[..., 9:13] = R.from_euler("z", 0.0).as_quat()
- cmd[..., 2] = 0.5 # hover at 0.5 m across all worlds
- for _ in range(100):
- sim.state_control(cmd)
- sim.step(sim.freq // sim.control_freq)
- sim.render()
- ```
- ## Documentation
- [learnsyslab.github.io/crazyflow](https://learnsyslab.github.io/crazyflow) — installation, user guide, examples, and API reference.
- ## Features
- - **n\_worlds x n\_drones** — batched over independent environments and multi-drone swarms simultaneously
- - **GPU-accelerated** — up to 914 M steps/s on an RTX 4090 (first-principles dynamics, 262 K worlds)
- - **Differentiable** — `jax.grad` works through the full dynamics and control pipeline
- - **First-principles dynamics** — dynamics using first-principles equations and parameters identified from real-world measurements
- - **Abstracted dynamics** — simplified dynamics in three flavors fitted from real flight data
- - **Modular pipelines** — step and reset are tuples of plain JAX functions; insert anything, anywhere
- - **MuJoCo integration** — onscreen and offscreen rendering, raycasting, and contact detection via MJX
- ## Supported drones
- Crazyflow supports a variety of drones:
- | Drone | Platform |
- |---|---|
- | `cf2x_L250` | Crazyflie 2.x |
- | `cf2x_P250` | Crazyflie 2.x, plus propellers |
- | `cf2x_T350` | Crazyflie 2.x, thrust upgrade kit |
- | `cf21B_500` | Crazyflie 2.1 Brushless (default) |
- | `hb_x500` | Holybro X500 V2 |
- New platforms can be added as described in the [docs](https://learnsyslab.github.io/crazyflow/user-guide/adding-drones/).
- ## Installation
- ```bash
- pip install crazyflow # CPU
- pip install "crazyflow[gpu]" # GPU (Linux x86-64, CUDA 12)
- ```
- Developer install with editable install ([pixi](https://pixi.sh/) recommended):
- ```bash
- git clone https://github.com/learnsyslab/crazyflow.git
- cd crazyflow
- pixi shell
- ```
- Or with [uv](https://docs.astral.sh/uv/):
- ```bash
- git clone https://github.com/learnsyslab/crazyflow.git
- cd crazyflow
- uv sync # core + dev tooling (tests, docs, ruff)
- ```
- ## Performance
- First-principles dynamics, one drone. CPU: AMD Ryzen 9 7950X. GPU: NVIDIA RTX 4090.
- | n\_worlds | CPU steps/s | GPU steps/s |
- |---|---|---|
- | 64 | 3.3 M | 1.2 M |
- | 1 024 | 9.2 M | 18.7 M |
- | 16 384 | 11.9 M | 257 M |
- | 65 536 | 15.6 M | 678 M |
- | 262 144 | 12.6 M | 914 M |
- Full benchmarks including multi-drone scaling are in the [documentation](https://learnsyslab.github.io/crazyflow).
- ## Citation
- ```bibtex
- @misc{schuck2026crazyflow,
- title={Crazyflow: An Accurate, GPU-Accelerated, Differentiable Drone Simulator in JAX},
- author={Martin Schuck and Marcel P. Rath and Yufei Hua and Abhishek Goudar and SiQi Zhou and Angela P. Schoellig},
- year={2026},
- eprint={2606.01478},
- archivePrefix={arXiv},
- primaryClass={cs.RO},
- url={https://arxiv.org/abs/2606.01478},
- }
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.