Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/learnsyslab--crazyflow/badge.svg)](/listings/learnsyslab--crazyflow)

HTML

<a href="/listings/learnsyslab--crazyflow"><img src="/api/listings/learnsyslab--crazyflow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. ---
  2. name: crazyflow
  3. description: Non-obvious traps and conventions in the crazyflow drone simulator. Use when working
  4. in the crazyflow codebase, adding a dynamics model or drone platform, reusing the dynamics or
  5. controllers outside Sim for estimation or MPC, or writing code under jax.jit, grad or vmap.
  6. ---
  7. # Crazyflow
  8. Settings are in `pyproject.toml`, layout in the tree, API reference in `docs/`.
  9. ## Conventions
  10. - Ruff settings live in `pyproject.toml` and must pass before committing.
  11. - Dynamics and controllers follow the array API standard. Take the namespace from the inputs with
  12. `array_namespace(...)`, do all math through it, coerce bound parameters with `to_xp`, and never
  13. import `numpy` into a computation path.
  14. - `crazyflow/control/mellinger/params.toml` deliberately holds values that differ from the true
  15. physical constants in `crazyflow/dynamics/*/params.toml`, reproducing the real firmware. Do not
  16. unify them.
  17. ## Testing
  18. ```bash
  19. pixi run -e tests tests # what CI runs
  20. pixi run -e tests test-docs # every example in docstrings and docs
  21. ```
  22. Use pixi, not uv. `pixi run <cmd>` resolves task names only, so arbitrary commands need `-e tests`.
  23. - `addopts = "-m 'not render'"` deselects every render test, and `tests/unit/test_visualizations.py`
  24. is `@skip_if_headless` without the marker, so it is skipped silently without `DISPLAY`. Rendering
  25. regressions pass CI green. Run `-m render` locally with a display.
  26. - Docs and docstrings are executable. The markdown runner catches exceptions but never compares
  27. output, so a `print` with the result in a trailing comment proves nothing. Output that must be
  28. checked goes in a `pycon` fence with `>>>` prompts, which doctest picks up.
  29. - `tests/integration/test_examples.py` runs every script under `examples/`, so a new example is a
  30. new test.
  31. - `tests/conftest.py` forces JAX's persistent cache on at `/tmp/jax_cache-<uid>`, shared across
  32. branches. Delete it when failures make no sense.
  33. - Request the `device` fixture rather than a GPU marker. It falls back to CPU silently, so
  34. `gpu-tests` asserts nothing about placement on a machine without CUDA.
  35. ## Adding a dynamics model or drone
  36. Grepping the name of an existing model or drone finds every registration site, except when matching
  37. against all models in the simulation's `build_control_fns`.
  38. Define the function in `dynamics.py` and never in the package `__init__.py`, because
  39. `load_fn_params` derives the model name from `fn.__module__.split(".")[-2]`. `parametrize`
  40. binds exactly the keyword-only parameters after the bare `*`, so anything before it is never bound.
  41. `Drone` in `crazyflow/drones/__init__.py` is a `StrEnum` with one member per MJCF file in
  42. `crazyflow/drones`, asserted on import. A model supports a drone when its
  43. `crazyflow/dynamics/<model>/params.toml` has a section for it. The commented example at the
  44. top of each file lists the keys. `supported_drones` and `supported_dynamics` report the pairs, and the
  45. tests only run those. Only `gravity_vec` is global, in `crazyflow/dynamics/params.toml`.
  46. Registration alone produces roughly 40 parametrized tests. These do not include derivatives tests.
  47. ## Using dynamics and controllers outside Sim
  48. Pure, batched, array-API functions with no dependency on `Sim`.
  49. - Import crazyflow before scipy. `crazyflow/__init__.py` sets `SCIPY_ARRAY_API=1` and imports scipy
  50. immediately, and scipy cannot be reconfigured once loaded. Transitive imports through acados or
  51. sklearn trigger this too.
  52. - `dynamics` and `control` each have `load_params(name, drone)`, returning everything defined for
  53. the drone, and `load_fn_params(fn, drone)`, which filters to the signature of `fn` and
  54. drops the rest. Additional platform data is stored as a comment in the drone MJCF.
  55. - `parametrize` returns a `functools.partial` whose `keywords` dict is shared by every reference to
  56. it. Call `parametrize` again for an independent copy.
  57. - Leading batch dimensions, trailing feature axis. `quat` is scalar-last xyzw, `force` is `(..., 1)`
  58. rather than a scalar, `ang_vel` is body frame.
  59. - `ctrl_freq` scales only the integral and derivative terms, so it must match your real loop rate.
  60. Under jit, initialize integral states to zeros rather than `None`, since the pytree structure
  61. change forces a recompile.
  62. - `symbolic_dynamics` monkey-patches module-global symbols while building, so it is not reentrant.
  63. Do not build two concurrently.
  64. ## The functional API and jit
  65. `Sim` rebinds `sim.data` as a Python side effect that JAX cannot trace, so anything inside `jit`,
  66. `grad`, `vmap` or `scan` must use `crazyflow.sim.functional` with `Sim` only as the builder. See
  67. [`functional-api.md`](docs/user-guide/functional-api.md).
  68. - **After editing a pipeline, call `build_step_fn()` or `build_reset_fn()` again.** The builders
  69. snapshot the stages, so a later edit is silently ignored and the stage never runs.
  70. - `n_steps` is static, so each distinct value compiles separately. Build once and reuse.
  71. - `states.force` and `states.torque` are inputs, not outputs, and nothing clears them, so writing
  72. them applies a persistent disturbance.
  73. - Mutating state does not invalidate `core.mjx_synced`, so `contacts()` can query stale geometry.
  74. Set the flag false yourself.
  75. - Gradients vanish at `clip_floor_pos` (`jnp.where` on floor contact) and at any saturation bound.
  76. ## Splats
  77. `attach_splats` performs no calibration. Both `.ply` files must already sit in the simulator's
  78. frames, the scene in the MuJoCo world frame at metric scale and the drone in its body frame. An
  79. uncalibrated splat looks correct alone but does not match the simulated geometry. See
  80. [`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.

  1. <p align="center">
  2. <img src="https://github.com/learnsyslab/crazyflow/raw/main/docs/img/logo.svg" alt="Crazyflow Logo" width="300"><br>
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="https://github.com/learnsyslab/crazyflow/raw/main/docs/img/logo_text_white.svg">
  5. <img src="https://github.com/learnsyslab/crazyflow/raw/main/docs/img/logo_text_black.svg" alt="Crazyflow" width="500">
  6. </picture>
  7. </p>
  8. <div align="center">
  9. --------------------------------------------------------------------------------
  10. **Fast, parallelizable simulations of quadrotor drones with JAX.**
  11. [![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org)
  12. [![arXiv](https://img.shields.io/badge/arXiv-2606.01478-b31b1b.svg)](https://arxiv.org/abs/2606.01478)
  13. [![Tests](https://github.com/learnsyslab/crazyflow/actions/workflows/testing.yml/badge.svg)](https://github.com/learnsyslab/crazyflow/actions/workflows/testing.yml)
  14. [![Fuzzing](https://github.com/learnsyslab/crazyflow/actions/workflows/fuzzing.yml/badge.svg)](https://github.com/learnsyslab/crazyflow/actions/workflows/fuzzing.yml)
  15. [![Ruff](https://github.com/learnsyslab/crazyflow/actions/workflows/ruff.yml/badge.svg)](https://github.com/learnsyslab/crazyflow/actions/workflows/ruff.yml)
  16. [![Docs](https://github.com/learnsyslab/crazyflow/actions/workflows/docs.yml/badge.svg)](https://learnsyslab.github.io/crazyflow)
  17. </div>
  18. Crazyflow is a research simulator for quadrotors. It runs batched, differentiable simulations on CPU and GPU via JAX, with analytical and abstracted dynamics.
  19. ```python
  20. import numpy as np
  21. from crazyflow.sim import Sim
  22. from crazyflow.control import Control
  23. from scipy.spatial.transform import Rotation as R
  24. sim = Sim(n_worlds=4096, n_drones=1, control=Control.state)
  25. cmd = np.zeros((4096, 1, 16))
  26. cmd[..., 9:13] = R.from_euler("z", 0.0).as_quat()
  27. cmd[..., 2] = 0.5 # hover at 0.5 m across all worlds
  28. for _ in range(100):
  29. sim.state_control(cmd)
  30. sim.step(sim.freq // sim.control_freq)
  31. sim.render()
  32. ```
  33. ## Documentation
  34. [learnsyslab.github.io/crazyflow](https://learnsyslab.github.io/crazyflow) — installation, user guide, examples, and API reference.
  35. ## Features
  36. - **n\_worlds x n\_drones** — batched over independent environments and multi-drone swarms simultaneously
  37. - **GPU-accelerated** — up to 914 M steps/s on an RTX 4090 (first-principles dynamics, 262 K worlds)
  38. - **Differentiable** — `jax.grad` works through the full dynamics and control pipeline
  39. - **First-principles dynamics** — dynamics using first-principles equations and parameters identified from real-world measurements
  40. - **Abstracted dynamics** — simplified dynamics in three flavors fitted from real flight data
  41. - **Modular pipelines** — step and reset are tuples of plain JAX functions; insert anything, anywhere
  42. - **MuJoCo integration** — onscreen and offscreen rendering, raycasting, and contact detection via MJX
  43. ## Supported drones
  44. Crazyflow supports a variety of drones:
  45. | Drone | Platform |
  46. |---|---|
  47. | `cf2x_L250` | Crazyflie 2.x |
  48. | `cf2x_P250` | Crazyflie 2.x, plus propellers |
  49. | `cf2x_T350` | Crazyflie 2.x, thrust upgrade kit |
  50. | `cf21B_500` | Crazyflie 2.1 Brushless (default) |
  51. | `hb_x500` | Holybro X500 V2 |
  52. New platforms can be added as described in the [docs](https://learnsyslab.github.io/crazyflow/user-guide/adding-drones/).
  53. ## Installation
  54. ```bash
  55. pip install crazyflow # CPU
  56. pip install "crazyflow[gpu]" # GPU (Linux x86-64, CUDA 12)
  57. ```
  58. Developer install with editable install ([pixi](https://pixi.sh/) recommended):
  59. ```bash
  60. git clone https://github.com/learnsyslab/crazyflow.git
  61. cd crazyflow
  62. pixi shell
  63. ```
  64. Or with [uv](https://docs.astral.sh/uv/):
  65. ```bash
  66. git clone https://github.com/learnsyslab/crazyflow.git
  67. cd crazyflow
  68. uv sync # core + dev tooling (tests, docs, ruff)
  69. ```
  70. ## Performance
  71. First-principles dynamics, one drone. CPU: AMD Ryzen 9 7950X. GPU: NVIDIA RTX 4090.
  72. | n\_worlds | CPU steps/s | GPU steps/s |
  73. |---|---|---|
  74. | 64 | 3.3 M | 1.2 M |
  75. | 1 024 | 9.2 M | 18.7 M |
  76. | 16 384 | 11.9 M | 257 M |
  77. | 65 536 | 15.6 M | 678 M |
  78. | 262 144 | 12.6 M | 914 M |
  79. Full benchmarks including multi-drone scaling are in the [documentation](https://learnsyslab.github.io/crazyflow).
  80. ## Citation
  81. ```bibtex
  82. @misc{schuck2026crazyflow,
  83. title={Crazyflow: An Accurate, GPU-Accelerated, Differentiable Drone Simulator in JAX},
  84. author={Martin Schuck and Marcel P. Rath and Yufei Hua and Abhishek Goudar and SiQi Zhou and Angela P. Schoellig},
  85. year={2026},
  86. eprint={2606.01478},
  87. archivePrefix={arXiv},
  88. primaryClass={cs.RO},
  89. url={https://arxiv.org/abs/2606.01478},
  90. }
  91. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.