Merge dev branch

* Switch to drone models for physics
* Switch to drone controllers for onboard controllers
* Improve tests
* Rename physics modes
* Remove symbolic models in favor of drone-models
* Add visualization helpers
* Add support for purely functional sims
* Remove assets
* Add rudimentary docs support
* Remove scipy build tools

Author: amacati

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      
+    - name: Setup pixi
+      uses: prefix-dev/setup-pixi@v0.8.1
+      with:
+        pixi-version: v0.49.0
+        cache: true
+        
+    - name: Build documentation
+      run: pixi run -e docs mkdocs build
+      
+    - name: Setup Pages
+      uses: actions/configure-pages@v3
+      
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.github/workflows/ruff.yml

@@ -1,8 +1,16 @@
 name: Ruff
 on: [ push, pull_request ]
 jobs:
-  ruff:
+  ruff-check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/ruff-action@v1
+      - uses: astral-sh/ruff-action@v1
+
+  ruff-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v1
+        with:
+          args: "format --check --diff"

.github/workflows/testing.yml

@@ -2,20 +2,24 @@ name: Testing
 on: [push, pull_request]
 
 jobs:
-  test:
+  tests:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install submodules
+        run: |
+          git submodule update --init --recursive
+
       - name: Setup Pixi (installs pixi + caches envs) # https://github.com/marketplace/actions/setup-pixi
-        uses: prefix-dev/setup-pixi@v0.9.0            # pin the action version
+        uses: prefix-dev/setup-pixi@v0.9.3            # pin the action version
         with:
-          pixi-version: v0.49.0                       # pin the pixi binary version (optional)
+          pixi-version: v0.61.0                       # pin the pixi binary version (optional)
           cache: true                                 # enable caching of installed envs
           # only write new caches on main pushes (TODO: Enable)
           # cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
-          # ensure the 'test' environment(s) are installed
-          environments: test
+          # ensure the 'tests' environment(s) are installed
+          environments: tests
           # don't activate env (we'll call pixi run -e test explicitly)
           activate-environment: false
           # prefer using existing lockfile if present (faster, deterministic)
@@ -24,4 +28,4 @@ jobs:
       - name: Verify pixi and run tests
         run: |
           pixi --version
-          pixi run -e test pytest
+          pixi run -e tests tests

.gitignore

@@ -20,3 +20,9 @@ benchmark/data
 # pixi environments
 .pixi
 *.egg-info
+
+# MkDocs build output
+site/
+# Temporary files
+.DS_Store
+Thumbs.db

.gitmodules

@@ -0,0 +1,8 @@
+[submodule "submodules/drone-models"]
+	path = submodules/drone-models
+	url = https://github.com/utiasDSL/drone-models.git
+	branch = main
+[submodule "submodules/drone-controllers"]
+	path = submodules/drone-controllers
+	url = https://github.com/utiasDSL/drone-controllers.git
+	branch = main

README.md

@@ -6,18 +6,44 @@ Fast, parallelizable simulations of Crazyflies with JAX.
 
 [![Python Version]][Python Version URL] [![Ruff Check]][Ruff Check URL] [![Documentation Status]][Documentation Status URL] [![Tests]][Tests URL]
 
-[Python Version]: https://img.shields.io/badge/python-3.10+-blue.svg
+[Python Version]: https://img.shields.io/badge/python-3.11+-blue.svg
 [Python Version URL]: https://www.python.org
 
 [Ruff Check]: https://github.com/utiasDSL/crazyflow/actions/workflows/ruff.yml/badge.svg?style=flat-square
 [Ruff Check URL]: https://github.com/utiasDSL/crazyflow/actions/workflows/ruff.yml
 
-[Documentation Status]: https://readthedocs.org/projects/crazyflow/badge/?version=latest
-[Documentation Status URL]: https://crazyflow.readthedocs.io/en/latest/?badge=latest
+[Documentation Status]: https://github.com/utiasDSL/crazyflow/actions/workflows/docs.yml/badge.svg
+[Documentation Status URL]: https://utiasdsl.github.io/crazyflow
 
 [Tests]: https://github.com/utiasDSL/crazyflow/actions/workflows/testing.yml/badge.svg
 [Tests URL]: https://github.com/utiasDSL/crazyflow/actions/workflows/testing.yml
 
+## Quick Start
+For a more detailed guide, check out our [documentation TODO](TODO).
+
+### Normal installation
+The regular way to use Crazyflow is to install it from PyPI with your favourite package manager, e.g., with pip:
+``` bash
+pip install crazyflow
+```
+
+### Developer installation
+If you plan to develop with and around Crazyflow, you can use the existing [pixi](https://pixi.sh/) environment.
+``` bash
+git clone --recurse-submodules git@github.com:utiasDSL/crazyflow.git
+cd crazyflow
+pixi shell
+```
+
+This will install Crazyflow, drone-models, and drone-controllers in editable mode for easy development.
+
+In case you want to use another package manager or install the simulator with it's subpackages into another project, simply install all packages manually in your environment:
+``` bash
+pip install -e . # Installing Crazyflow
+pip install -e ./submodules/drone-models
+pip install -e ./submodules/drone-controllers
+```
+
 
 ## Architecture
 
@@ -30,8 +56,10 @@ The simulation is built as a pipeline of functions that are composed at initiali
 
 #### Physics Backends
 Multiple physics models are supported:
-- analytical: A first-principles model based on physical equations
-- sys_id: A system-identified model trained on real drone data
+- first_principles: A first-principles model based on physical equations
+- so_rpy: A system-identified model trained on real drone data
+- so_rpy_rotor: An enhanced system-identified model that includes thrust dynamics
+- so_rpy_rotor_drag: A system-identified model that includes thrust dynamics and drag effects
 
 #### Control Modes
 Different control interfaces are available:

benchmark/main.py

@@ -151,7 +151,7 @@ def main(device: str = "cpu", n_worlds_exp: int = 6):
     sim_config = config_dict.ConfigDict()
     sim_config.n_worlds = 1
     sim_config.n_drones = 1
-    sim_config.physics = "analytical"
+    sim_config.physics = "first_principles"
     sim_config.control = "attitude"
     sim_config.attitude_freq = 500
     sim_config.device = device

benchmark/op_count.py

@@ -4,7 +4,7 @@
 
 def main():
     """Main entry point for profiling."""
-    sim = Sim(n_worlds=1, n_drones=1, physics="analytical", control="attitude")
+    sim = Sim(n_worlds=1, n_drones=1, physics="first_principles", control="attitude")
 
     compiled_reset = sim._reset.lower(sim.data, sim.default_data, None).compile()
     compiled_step = sim._step.lower(sim.data, 1).compile()

benchmark/performance.py

@@ -77,7 +77,7 @@ def main():
     sim_config = config_dict.ConfigDict()
     sim_config.n_worlds = 1
     sim_config.n_drones = 1
-    sim_config.physics = "analytical"
+    sim_config.physics = "first_principles"
     sim_config.control = "attitude"
     sim_config.device = device
 

crazyflow/__init__.py

@@ -1,3 +1,21 @@
+import os
+import sys
+
+# SciPy array API check. We use the most recent array API features, which require the
+# SCIPY_ARRAY_API environment variable to be set to "1". This flag MUST be set before importing
+# scipy, because scipy's C extensions cannot be unloaded once they have been imported. Therefore, we
+# have to error out if the flag is not set. Otherwise, we immediately import scipy to ensure that no
+# other package sets the flag to a different value before importing scipy.
+
+if "scipy" in sys.modules and os.environ.get("SCIPY_ARRAY_API") != "1":
+    msg = """scipy has already been imported and the 'SCIPY_ARRAY_API' environment variable has not
+    been set. Please restart your Python session and set SCIPY_ARRAY_API="1" before importing any
+    packages that depend on scipy, or import this package first to automatically set the flag."""
+    raise RuntimeError(msg)
+
+os.environ["SCIPY_ARRAY_API"] = "1"
+import scipy  # noqa: F401, ensure scipy uses array API features
+
 import crazyflow.envs  # noqa: F401, ensure gymnasium envs are registered
 from crazyflow.control import Control
 from crazyflow.sim import Physics, Sim