Reintegrate `drone_models` and `drone_controllers` into `crazyflow` by amacati · Pull Request #71 · learnsyslab/crazyflow

amacati · 2026-06-17T11:39:40Z

`drone-models`

Previous state

Drone definitions and dynamics lived in a separate drone-models package, pulled in as a PyPI dependency / git submodule (submodules/drone-models, import drone_models). The MJCF files, meshes and parameters were resolved via drone_models.__file__, and the dynamics were imported into crazyflow/sim/physics.py.

Naming ambiguities

"Model" was overloaded three ways — the MuJoCo MJX model, the dynamics formulation, and the drone hardware. "models", "physics" and "dynamics" were often used interchangeably. These disambiguities have been fixed in the same step:

Concept	Before	After
Dynamics	`Physics` / `models` / `dynamics`	`Dynamics` / `dynamics`
Drone hardware	`drone_model` (param/attr)	`drone`
MuJoCo model	`model` (spec, file name)	`mjx_model`

Proposed naming scheme

drone — a hardware platform (cf2x_L250, cf21B_500, …).
dynamics — a physics formulation that advances the state (first_principles, so_rpy, so_rpy_rotor, so_rpy_rotor_drag), selected via the Dynamics enum.
mjx_model — the MuJoCo MJX model used for kinematics/rendering.

We avoid the use of model where possible because it is ambiguous.

Package split

The vendored package is split by what the files are:

crazyflow/drones/ — hardware descriptions: MJCF *.xml, meshes (assets/), and shared params.toml (mass, inertia, thrust/torque curves). available_drones enumerates platforms.
crazyflow/dynamics/ — the dynamics themselves: one subpackage per fidelity level (each with dynamics.py + params.toml), plus core.py (Dynamics, parametrize), symbols.py, transform.py, and utils/. Written backend-agnostic (Array API: NumPy/JAX/PyTorch) and CasADi-symbolic, so the dynamics stay usable standalone for estimation/control.
available_dynamics / dynamics_features enumerate and introspect them.

Other resulting changes

Removed the drone-models dependency and submodule and added package-data globs for the vendored XML/STL/TOML.
Deleted crazyflow/sim/physics.py; dynamics selection now lives in crazyflow/dynamics.
Added crazyflow/_typing.py (Array/ArrayLike shim until array-api typing lands).
Mechanical renames across docs, examples and tests (physics→dynamics, drone_model→drone);
docs/user-guide/physics-models.md → dynamics-models.md.

Follow-up (separate PR)

Move to_xp (crazyflow/dynamics/utils/__init__.py) to the general crazyflow/utils.py. It's a generic Array-API helper, not dynamics-specific.
Reconsider home of the transform/rotation helpers (crazyflow/dynamics/transform.py, crazyflow/dynamics/utils/rotation.py). Several are general-purpose and may belong in shared utils.

`drone-controllers`

Previous state

Controllers lived in a separate drone-controllers package, pulled in as a PyPI dependency and git submodule (submodules/drone-controllers, import drone_controllers).

Package move

Vendored into crazyflow/control/, mirroring crazyflow/dynamics/: mellinger/ subpackage (controller functions + params.toml), core.py (parametrize, param loaders), control.py (Control enum), transform.py.

Unification

Previously the controller functions, the sim data structs, and the controller-to-SimData adapters were split across packages. They now live together in crazyflow/control/mellinger/control.py, the same way each dynamics module co-locates dynamics + Params + sim_dynamics.

API changes

drone_model param renamed to drone (consistent with dynamics).
load_params split into load_params(controller, drone) (raw, name-keyed loader) and load_fn_params(fn, drone) (per-function selection + signature filter).
Integral errors are explicit named arguments (pos_err_i, r_int_error) instead of a generic ctrl_errors tuple.
Sim adapters renamed control_<stage> and registered in the step pipeline under explicit role-based stage names (state_controller, attitude_controller, force_torque_controller, commit_attitude), so the pipeline is readable and the names are a stable insertion API.

Other resulting changes

Removed the drone-controllers dependency and submodule.
Added array-api-compat and array-api-extra as direct dependencies (were transitive via the package).
Added tests (tests/unit/control/) and docs (docs/user-guide/control/).

ratheron

Thanks for working on this integration! This will make the entry to Crazyflow easier

ratheron · 2026-06-18T09:48:18Z

+\[
+\begin{aligned}
+    \dot{\mathbf{p}} &= \mathbf{v}, \\
+    \dot{\mathbf{q}} &= \tfrac{1}{2}
+        \begin{bmatrix}0 \\ {}^{\mathcal{B}}\boldsymbol{\omega}\end{bmatrix}
+        \otimes \mathbf{q}, \\
+    m\dot{\mathbf{v}} &= m\mathbf{g}
+        + (c_{\mathrm{acc}} + c_f F_{\mathrm{cmd}})\,R\,\mathbf{e}_z, \\
+    \ddot{\boldsymbol{\psi}} &=
+        c_{\psi}\,\boldsymbol{\psi}
+        + c_{\dot{\psi}}\,\dot{\boldsymbol{\psi}}
+        + c_u\,\mathbf{u}_{\mathrm{rpy}},
+\end{aligned}
+\]


Is there a way to preview the output to double check this nicely?

https://www.tuhh.de/MathJax/test/sample-dynamic-2.html, but it requires copy+paste. Other than that, only running it locally with pixi run docs-serve

Fixed the rotation direction of the quaternion and the ordering of entries

Why is there a q in the equation? The core model only has psi as state. While it get's transformed to fit the Crazyflow states, I think adding this is conversion is more confusing

amacati · 2026-06-18T23:01:06Z

Latest changes are all in and ready for another review

ratheron

Looks like you found a clean solution for the parameterize after all. I like it!
Left some minor comments

ratheron · 2026-06-19T09:49:43Z

+\[
+\begin{aligned}
+    \dot{\mathbf{p}} &= \mathbf{v}, \\
+    \dot{\mathbf{q}} &= \tfrac{1}{2}
+        \begin{bmatrix}0 \\ {}^{\mathcal{B}}\boldsymbol{\omega}\end{bmatrix}
+        \otimes \mathbf{q}, \\
+    m\dot{\mathbf{v}} &= m\mathbf{g}
+        + (c_{\mathrm{acc}} + c_f F_{\mathrm{cmd}})\,R\,\mathbf{e}_z, \\
+    \ddot{\boldsymbol{\psi}} &=
+        c_{\psi}\,\boldsymbol{\psi}
+        + c_{\dot{\psi}}\,\dot{\boldsymbol{\psi}}
+        + c_u\,\mathbf{u}_{\mathrm{rpy}},
+\end{aligned}
+\]


Why is there a q in the equation? The core model only has psi as state. While it get's transformed to fit the Crazyflow states, I think adding this is conversion is more confusing

ratheron

Looks like you found a clean solution for the parameterize after all. I like it!
Left some minor comments

…mics

amacati requested a review from ratheron June 17, 2026 13:22

amacati added the enhancement New feature or request label Jun 17, 2026

amacati force-pushed the feat.merge_models branch from 7afd420 to e53f1e5 Compare June 17, 2026 18:08

amacati changed the title ~~Merge drone_models into crazyflow & unify naming~~ Reintegrate drone_models and drone_controllers into crazyflow Jun 17, 2026

ratheron requested changes Jun 18, 2026

View reviewed changes

ratheron approved these changes Jun 19, 2026

View reviewed changes

ratheron requested changes Jun 19, 2026

View reviewed changes

amacati added 22 commits June 19, 2026 16:16

Merge models back into crazyflow

4fcdfd0

Introduce consistent naming scheme for dynamics/physics/models

a1321af

Improve naming consistency in docs

17a9f2b

Finalize consistent naming for drones/models/physics/dynamics

d7e2bee

Rename dynamics file, simplify so_rpy model, simplify models wrapper

1a228e9

Remove drone-models submodule

347dded

Simplify wrappers, add drone-models test suite to crazyflow

cb7ec8d

Improve tests

afa2d3e

Fix test imports

56a9a4f

Rename dynamics docs

e7e2e06

Add drone model docs

c677f81

Fix docs

026350d

Add controllers back into crazyflow

129fc60

Improve API and add docs

ae62616

Explicitly name controllers

1b052ae

Remove all submodules. Update deps

cc2219f

Update doc mistakes and benchmarks

3109cdf

Address comments

0715579

[WIP] Refactor parametrize

8c76a9c

Move fused models into regular xml

a46fbae

Refactor parametrization

a4bbc8a

Fix docs and comments

f9aef46

amacati added 2 commits June 19, 2026 16:16

Fix model docs. Restructure into core dynamics_euler and wrapper dyna…

9bcfac4

…mics

Fix doctests

f22b001

amacati force-pushed the feat.merge_models branch from 345e1cb to f22b001 Compare June 19, 2026 14:17

amacati requested a review from ratheron June 19, 2026 14:17

Conversation

amacati commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

drone-models

Previous state

Naming ambiguities

Proposed naming scheme

Package split

Other resulting changes

Follow-up (separate PR)

drone-controllers

Previous state

Package move

Unification

API changes

Other resulting changes

Uh oh!

ratheron left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ratheron Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

amacati Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

amacati Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

ratheron Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amacati commented Jun 18, 2026

Uh oh!

ratheron left a comment

Choose a reason for hiding this comment

Uh oh!

ratheron Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ratheron left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

amacati commented Jun 17, 2026 •

edited

Loading

`drone-models`

`drone-controllers`