Skip to content

Commit fd6a89e

Browse files
amacatiamacati
committed
Add docs
1 parent b9f22de commit fd6a89e

20 files changed

Lines changed: 1991 additions & 5 deletions

‎.github/workflows/docs.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Setup pixi
27+
uses: prefix-dev/setup-pixi@v0.8.1
28+
with:
29+
pixi-version: v0.29.0
30+
cache: true
31+
32+
- name: Build documentation
33+
run: pixi run -e docs mkdocs build
34+
35+
- name: Setup Pages
36+
uses: actions/configure-pages@v3
37+
38+
- name: Upload artifact
39+
uses: actions/upload-pages-artifact@v2
40+
with:
41+
path: ./site
42+
43+
deploy:
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
runs-on: ubuntu-latest
48+
needs: build
49+
if: github.ref == 'refs/heads/main'
50+
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/deploy-pages@v2

‎docs/cite.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Citation
2+
3+
If you use Drone Models in your research, please cite our work.
4+
5+
## BibTeX Entry
6+
7+
!!! info "Coming Soon"
8+
BibTeX entry will be provided here.
9+
10+
## Related Publications
11+
12+
!!! info "Coming Soon"
13+
List of related publications will be added here.
14+
15+
## Acknowledgments
16+
17+
!!! info "Coming Soon"
18+
Acknowledgments and funding information will be added here.

‎docs/concepts/drone-models.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Drone Models
2+
3+
Drone Models provides several model types with different complexity levels and capabilities. Understanding these differences will help you choose the right model for your application.
4+
5+
## Model Types Overview
6+
7+
| Model | Rotor Dynamics | Complexity | Physics Level | Best For |
8+
|-------|----------------|------------|---------------|----------|
9+
| `first_principles` | Yes | High | Full rigid body | High-fidelity simulation, MPC |
10+
| `so_rpy` | No | Low | Simplified | Fast simulation, learning |
11+
| `so_rpy_rotor` | Yes | Medium | Simplified + rotors | Balanced performance |
12+
| `so_rpy_rotor_drag` | Yes | High | Simplified + effects | High-speed flight |
13+
14+
## Physics-Based Models
15+
16+
### First Principles Model
17+
18+
The most comprehensive model based on full rigid body dynamics with quaternion representation.
19+
20+
**Features:**
21+
- Quaternion-based attitude representation (no singularities)
22+
- Full 6-DOF rigid body dynamics
23+
- Rotor spin-up dynamics with time constants
24+
- External force and torque disturbances
25+
- Mixing matrix for arbitrary motor configurations
26+
27+
**When to use:**
28+
- High-fidelity simulations
29+
- Model Predictive Control (MPC)
30+
- Research requiring accurate dynamics
31+
- Hardware-in-the-loop testing
32+
33+
```python
34+
from drone_models.first_principles import dynamics
35+
from drone_models.core import parametrize
36+
37+
# Create parametrized model
38+
model = parametrize(dynamics, "cf2x_L250")
39+
40+
# Use with rotor dynamics
41+
pos_dot, quat_dot, vel_dot, ang_vel_dot, rotor_vel_dot = model(
42+
pos, quat, vel, ang_vel, cmd, rotor_vel=rotor_vel
43+
)
44+
```
45+
46+
### SO(3) Roll-Pitch-Yaw Models
47+
48+
Simplified models using Euler angle representation for faster computation.
49+
50+
#### `so_rpy` - Basic Model
51+
- Direct thrust/torque mapping (no rotor dynamics)
52+
- Euler angle representation
53+
- Fastest execution
54+
55+
#### `so_rpy_rotor` - With Rotor Dynamics
56+
- Adds rotor spin-up dynamics
57+
- Models motor response delays
58+
- Good balance of speed and accuracy
59+
60+
#### `so_rpy_rotor_drag` - With Aerodynamic Effects
61+
- Includes drag and aerodynamic forces
62+
- Most complete simplified model
63+
- Better at high speeds
64+
65+
**When to use:**
66+
- Real-time applications requiring speed
67+
- Reinforcement learning training
68+
- Educational demonstrations
69+
- Rapid prototyping
70+
71+
```python
72+
from drone_models.so_rpy import dynamics as so_rpy_dynamics
73+
from drone_models.so_rpy_rotor import dynamics as so_rpy_rotor_dynamics
74+
75+
# Fast model without rotor dynamics
76+
basic_model = parametrize(so_rpy_dynamics, "cf2x_L250")
77+
78+
# Balanced model with rotor dynamics
79+
balanced_model = parametrize(so_rpy_rotor_dynamics, "cf2x_L250")
80+
```
81+
82+
## Data-Driven Models
83+
84+
While the current focus is on physics-based models, the framework is designed to support data-driven approaches:
85+
86+
**Planned features:**
87+
- Neural network residual models
88+
- Gaussian Process corrections
89+
- System identification tools
90+
- Sim-to-real adaptation
91+
92+
## Model Capabilities
93+
94+
### Rotor Dynamics
95+
96+
Models with rotor dynamics (`first_principles`, `so_rpy_rotor`, `so_rpy_rotor_drag`) include:
97+
98+
- **Motor time constants**: Realistic spin-up/spin-down behavior
99+
- **Command to thrust mapping**: Non-instantaneous response
100+
- **Rotor state tracking**: Additional state variables for rotor velocities
101+
102+
### Symbolic Variants
103+
104+
Each model provides both numeric and symbolic implementations:
105+
106+
```python
107+
# Numeric for simulation
108+
from drone_models.first_principles import dynamics
109+
110+
# Symbolic for optimization
111+
from drone_models.first_principles import symbolic_dynamics
112+
113+
# Generate CasADi function for MPC
114+
X_dot, X, U, Y = symbolic_dynamics(model_rotor_vel=True)
115+
f = cs.Function('dynamics', [X, U], [X_dot])
116+
```
117+
118+
### External Disturbances
119+
120+
All models support external force and torque disturbances:
121+
122+
```python
123+
# Add wind disturbance
124+
wind_force = np.array([2.0, 0.0, 0.0]) # 2 N force in x-direction
125+
turbulence_torque = np.array([0.1, 0.1, 0.0]) # Small torque disturbance
126+
127+
derivatives = model(pos, quat, vel, ang_vel, cmd, rotor_vel,
128+
dist_f=wind_force, dist_t=turbulence_torque)
129+
```
130+
131+
## Choosing the Right Model
132+
133+
### For Real-Time Control
134+
- **Fast control loops (>500 Hz)**: `so_rpy`
135+
- **Standard control (100-200 Hz)**: `so_rpy_rotor`
136+
- **High-fidelity control**: `first_principles`
137+
138+
### For Simulation
139+
- **Educational/demos**: `so_rpy` or `so_rpy_rotor`
140+
- **Research simulation**: `first_principles`
141+
- **Large-scale studies**: `so_rpy` for speed
142+
143+
### For Optimization (MPC)
144+
- **Real-time MPC**: `so_rpy_rotor` symbolic
145+
- **High-fidelity MPC**: `first_principles` symbolic
146+
- **Trajectory optimization**: Any symbolic variant
147+
148+
### For Machine Learning
149+
- **RL training**: `so_rpy` for speed
150+
- **Sim-to-real**: `first_principles` + planned data-driven extensions
151+
- **System identification**: `first_principles` as ground truth
152+
153+
## Performance Considerations
154+
155+
### Computational Cost (relative)
156+
1. `so_rpy`: 1x (baseline)
157+
2. `so_rpy_rotor`: ~1.5x
158+
3. `so_rpy_rotor_drag`: ~2x
159+
4. `first_principles`: ~3x
160+
161+
### Memory Usage
162+
- All models have minimal memory footprint
163+
- Batching scales linearly with batch size
164+
- GPU memory usage depends on batch size and backend
165+
166+
### Accuracy Trade-offs
167+
- **Highest accuracy**: `first_principles`
168+
- **Good accuracy**: `so_rpy_rotor_drag`
169+
- **Acceptable accuracy**: `so_rpy_rotor`
170+
- **Basic accuracy**: `so_rpy`
171+
172+
---
173+
174+
*Choose your model based on the trade-off between accuracy, computational cost, and your specific application requirements.*

‎docs/concepts/index.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Concepts
2+
3+
Understanding the fundamental concepts behind Drone Models will help you use the package effectively and choose the right approach for your application.
4+
5+
## Core Design Principles
6+
7+
### Functional Programming Paradigm
8+
9+
All models in this package are **pure functions** - they have no internal state and produce deterministic outputs based solely on their inputs. This design choice offers several advantages:
10+
11+
- **Predictability**: The same inputs always produce the same outputs
12+
- **Parallelizability**: Functions can be safely called in parallel
13+
- **Composability**: Easy to combine and integrate with other systems
14+
- **Testability**: Straightforward to unit test and validate
15+
16+
### Array API Compatibility
17+
18+
Models are built using the [Array API standard](https://data-apis.org/array-api/latest/), enabling seamless backend switching without code changes:
19+
20+
```python
21+
import numpy as np
22+
import jax.numpy as jnp
23+
import torch
24+
25+
# Same model, different backends
26+
model_numpy = parametrize(dynamics, "cf2x_L250", xp=np)
27+
model_jax = parametrize(dynamics, "cf2x_L250", xp=jnp)
28+
model_torch = parametrize(dynamics, "cf2x_L250", xp=torch)
29+
```
30+
31+
### Batching by Default
32+
33+
All models support batch processing out of the box, allowing you to simulate multiple drones or scenarios simultaneously:
34+
35+
```python
36+
# Single drone
37+
pos = np.array([0., 0., 1.]) # Shape: (3,)
38+
39+
# 100 drones
40+
pos_batch = np.zeros((100, 3)) # Shape: (100, 3)
41+
42+
# 10x5 grid of scenarios
43+
pos_grid = np.zeros((10, 5, 3)) # Shape: (10, 5, 3)
44+
```
45+
46+
## Key Concepts
47+
48+
### **[Drone Models](drone-models.md)**
49+
Learn about different model types and their trade-offs:
50+
- Physics-based vs. data-driven approaches
51+
- Model complexity levels
52+
- When to use each model type
53+
54+
### **[Parametrization](parameters.md)**
55+
Understand how model parameters work:
56+
- Parameter files and loading
57+
- Default configurations for common drones
58+
- Custom parameter definition
59+
60+
### **[Transformations](transformations.md)**
61+
Explore coordinate and parameter transformations:
62+
- Motor forces to rotor velocities
63+
- PWM to force conversions
64+
- Body frame transformations
65+
66+
## Advanced Topics
67+
68+
### Symbolic vs. Numeric Models
69+
70+
Each model type offers both numeric and symbolic implementations:
71+
72+
- **Numeric models**: Fast execution, suitable for simulation and real-time control
73+
- **Symbolic models**: Generate mathematical expressions for optimization solvers (CasADi)
74+
75+
```python
76+
# Numeric model for simulation
77+
from drone_models.first_principles import dynamics
78+
79+
# Symbolic model for MPC
80+
from drone_models.first_principles import symbolic_dynamics
81+
```
82+
83+
### JIT Compilation
84+
85+
Models are designed to work seamlessly with JAX's JIT compiler for maximum performance:
86+
87+
```python
88+
import jax
89+
90+
# JIT compile for speed
91+
model_jit = jax.jit(model)
92+
derivatives = model_jit(pos, quat, vel, ang_vel, cmd)
93+
```
94+
95+
### GPU Acceleration
96+
97+
Thanks to Array API compatibility, models automatically support GPU acceleration when using appropriate backends:
98+
99+
```python
100+
import jax
101+
import jax.numpy as jnp
102+
103+
# Move computation to GPU
104+
pos = jnp.array(pos_data, device=jax.devices("gpu")[0])
105+
model_gpu = parametrize(dynamics, "cf2x_L250", xp=jnp)
106+
```
107+
108+
## Mathematical Foundations
109+
110+
All models are based on well-established principles of rigid body dynamics and aerodynamics. The mathematical details are covered in each model's specific documentation, but the general approach follows:
111+
112+
1. **State Representation**: Position, orientation (quaternion), linear and angular velocities
113+
2. **Input Mapping**: Motor commands to forces and torques
114+
3. **Dynamics Computation**: Newton-Euler equations for rigid body motion
115+
4. **Optional Extensions**: Rotor dynamics, aerodynamic effects, disturbances
116+
117+
## Next Steps
118+
119+
- **New to drone modeling?** Start with [Drone Models](drone-models.md) to understand the basics
120+
- **Ready to use the package?** Check out [Parameters](parameters.md) for configuration
121+
- **Need coordinate conversions?** Explore [Transformations](transformations.md)
122+
123+
---
124+
125+
*The functional design and Array API compatibility make Drone Models uniquely suited for modern scientific computing workflows.*

0 commit comments

Comments
 (0)