# Quadcopter‑Sim
Light‑weight, strictly‑typed Python toolkit for **6‑DoF quadrotor simulation**, 3‑D plotting and step‑wise control loops — perfect for control‑systems classes, flight‑code prototyping or RL research.
[](https://pypi.org/project/quadcopter-sim)
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Command Line Interface](#command-line-interface)
- [Core Features](#core-features)
- [API Reference](#api-reference)
- [Usage Examples](#usage-examples)
- [Examples & Notebooks](#examples--notebooks)
- [Testing & Verification](#testing--verification)
- [Academic Use](#academic-use)
- [Roadmap](#roadmap)
---
## Installation
```bash
# Latest release
pip install quadcopter-sim
# Development install with all optional dependencies
git clone https://github.com/2black0/quadcopter-sim-python
cd quadcopter-sim-python
pip install -e .[all] # includes all optional dependencies for development
# Install specific optional dependencies
pip install -e .[rl] # Gymnasium for RL
pip install -e .[control] # SciPy for advanced control
pip install -e .[data] # SciPy for data export
pip install -e .[dev] # Core development tools (testing, linting)
```
---
## Quick Start
### Minimal Example
```python
import numpy as np
from quadcopter.simulation import simulate, Params
from quadcopter.plotting import plot_trajectory
p = Params()
hover_speed = np.sqrt(p.m * p.g / (4 * p.b)) # rad/s
t, s, u = simulate(
4.0, 0.02,
controller=lambda *_: np.full(4, hover_speed),
method="rk4",
)
plot_trajectory(t, s, u)
```
### Command Line Usage
```bash
# Basic hover simulation with 3D plot
python -m quadcopter --plot
# PID position control
python -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot
```
---
## Command Line Interface
The package provides a comprehensive command-line interface for simulation, control, and analysis:
### Basic Usage Examples
```bash
# Basic hover simulation
python -m quadcopter --plot # 4 s hover + 3‑D figure
python -m quadcopter --duration 6 --csv run.csv --quiet
# PID position control
python -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot
# LQR control with custom parameters
python -m quadcopter --controller lqr --duration 5 --plot
# Academic analysis and logging
python -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --academic-log results
# Advanced PID tuning
python -m quadcopter --controller pid --target-pos 1 0 1 --duration 5 \
--pid-kp 3 3 5 --pid-ki 0.2 0.2 0.3 --pid-kd 0.6 0.6 1.2 \
--plot
# Custom initial conditions
python -m quadcopter --controller pid --target-pos 0 0 2 --duration 5 \
--init-pos 0 0 1 --init-vel 0 0 0.5 \
--csv trajectory.csv --json log.json --matlab data.mat
# Enhanced plotting options
python -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot-errors
python -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot-comparison
```
### CLI Options Reference
```
usage: python -m quadcopter [-h] [--duration DURATION] [--dt DT]
[--method {rk45,rk4}] [--rtol RTOL] [--atol ATOL]
[--controller {hover,pid,lqr}]
[--pid-kp PID_KP PID_KP PID_KP]
[--pid-ki PID_KI PID_KI PID_KI]
[--pid-kd PID_KD PID_KD PID_KD]
[--target-pos TARGET_POS TARGET_POS TARGET_POS]
[--plot] [--csv CSV] [--json JSON]
[--matlab MATLAB] [--academic-log ACADEMIC_LOG]
[--controller-type {pid,lqr,rl}]
[--init-pos INIT_POS INIT_POS INIT_POS]
[--init-vel INIT_VEL INIT_VEL INIT_VEL] [--quiet]
[--verbose]
Comprehensive quadcopter simulation and analysis tool.
Simulation Parameters:
--duration DURATION simulation time [s]
--dt DT integration step [s]
--method {rk45,rk4} integration method (adaptive RK45 or fixed‑step RK4)
--rtol RTOL solver rtol
--atol ATOL solver atol
Controller Options:
--controller {hover,pid,lqr} controller type to use
--pid-kp PID_KP PID_KP PID_KP PID Kp gains for x, y, z axes
--pid-ki PID_KI PID_KI PID_KI PID Ki gains for x, y, z axes
--pid-kd PID_KD PID_KD PID_KD PID Kd gains for x, y, z axes
--target-pos TARGET_POS TARGET_POS TARGET_POS target position [x, y, z]
Initial Conditions:
--init-pos INIT_POS INIT_POS INIT_POS initial position [x, y, z]
--init-vel INIT_VEL INIT_VEL INIT_VEL initial velocity [vx, vy, vz]
Output Options:
--plot show matplotlib figure
--csv CSV save (t, state, control) to CSV
--json JSON save simulation log to JSON
--matlab MATLAB save simulation log to MATLAB .mat file
--academic-log ACADEMIC_LOG enable academic logging and save to directory
--quiet suppress info output
--verbose enable verbose output
```
---
## Core Features
### 1. Advanced Control Systems
Comprehensive control system implementations:
```python
from quadcopter.controllers import PIDController, PositionController, LQRController
# PID Position Control
position_ctrl = PositionController(
x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),
target_pos=np.array([1.0, -1.0, 2.0])
)
# LQR Control
A = np.eye(12) # State matrix
B = np.eye(12, 4) # Input matrix
lqr_ctrl = LQRController(A=A, B=B, Q=np.eye(12), R=np.eye(4))
```
### 2. Reinforcement Learning Integration
Gymnasium-compatible environment for RL research:
```python
from quadcopter.gym_env import QuadcopterGymEnv
env = QuadcopterGymEnv()
obs, info = env.reset()
action = env.action_space.sample() # Random action
obs, reward, terminated, truncated, info = env.step(action)
```
### 3. Real-time Simulation
Enhanced environment with real-time capabilities:
```python
from quadcopter.env import RealTimeQuadcopterEnv
# Run simulation at half real-time speed
env = RealTimeQuadcopterEnv(dt=0.02, real_time_factor=0.5)
```
### 4. Comprehensive Logging
Advanced logging with multiple export formats:
```python
from quadcopter.logging import simulate_with_logging
log = simulate_with_logging(duration=5.0, dt=0.02, controller=my_controller)
log.save_csv("simulation.csv") # CSV for analysis
log.save_json("simulation.json") # JSON for structured data
log.save_matlab("simulation.mat") # MATLAB for advanced analysis
```
### 5. Academic Evaluation and Visualization
Comprehensive academic evaluation tools for research publications:
```python
from quadcopter.logging import simulate_with_academic_logging
from quadcopter.evaluation import AcademicEvaluator
# Run simulation with academic logging
log = simulate_with_academic_logging(
duration=10.0,
dt=0.02,
controller=my_controller,
ref_position=np.array([1.0, -1.0, 2.0]),
controller_type="pid"
)
# Create academic evaluator
evaluator = AcademicEvaluator(log)
# Generate comprehensive analysis
metrics = evaluator.generate_comprehensive_analysis("results")
# Generate specific plots
evaluator.plot_3d_trajectory("trajectory.png")
evaluator.plot_state_tracking("tracking.png")
evaluator.plot_error_analysis("errors.png")
evaluator.plot_control_effort("control.png")
```
### 6. Enhanced Visualization
Comprehensive plotting capabilities:
```python
from quadcopter.plotting import (
plot_trajectory,
plot_control_errors,
plot_3d_trajectory_comparison,
plot_frequency_analysis
)
# Control error analysis
plot_control_errors(t, states, targets)
# Trajectory comparison
plot_3d_trajectory_comparison([
(states1, "Controller A"),
(states2, "Controller B")
])
# Frequency domain analysis
plot_frequency_analysis(t, signals, ["X Position", "Y Position", "Z Position"])
```
---
## API Reference
| Function / Class | Purpose | Key Arguments |
|------------------|---------|---------------|
| **Core Simulation** |
| `quadcopter.simulation.simulate` | One‑shot trajectory generator (adaptive RK45 or fixed‑step RK4) | `duration`, `dt`, `controller`, `method` |
| `quadcopter.dynamics.Params` | Physical constants (mass, arm length, thrust factor) | edit attributes to match your air‑frame |
| `quadcopter.dynamics.QuadState` | Minimal dataclass for the 13‑dim state | `.from_vector(vec)` / `.as_vector()` |
| **Environments** |
| `quadcopter.env.QuadcopterEnv` | Real‑time, fixed‑step RK4 environment | `dt`, `reset()`, `step()` |
| `quadcopter.env.RealTimeQuadcopterEnv` | Real-time environment with timing control | `dt`, `real_time_factor`, `reset()`, `step()` |
| `quadcopter.gym_env.QuadcopterGymEnv` | Gymnasium-compatible environment for RL training | `dt`, `max_steps` |
| **Controllers** |
| `quadcopter.controllers.PIDController` | PID controller with anti-windup and output limits | `kp`, `ki`, `kd`, `max_output` |
| `quadcopter.controllers.PositionController` | 3D position controller using PID for each axis | `x_pid`, `y_pid`, `z_pid`, `target_pos` |
| `quadcopter.controllers.LQRController` | Linear Quadratic Regulator controller | `A`, `B`, `Q`, `R` matrices |
| **Logging & Analysis** |
| `quadcopter.logging.SimulationLog` | Comprehensive logging with multiple export formats | `save_csv()`, `save_json()`, `save_matlab()` |
| `quadcopter.logging.AcademicLog` | Academic-grade logging for research publications | `add_entry()`, `save_csv()`, `save_json()`, `save_matlab()` |
| `quadcopter.logging.simulate_with_academic_logging` | Simulation with academic-grade logging | `duration`, `dt`, `controller`, `ref_position` |
| `quadcopter.evaluation.AcademicEvaluator` | Academic evaluation tools for performance analysis | `plot_3d_trajectory()`, `plot_state_tracking()`, `generate_performance_report()` |
| **Visualization** |
| `quadcopter.plotting.plot_trajectory` | Static 3‑D + time‑series figure | `t, states, controls` |
| `quadcopter.plotting.plot_control_errors` | Control error analysis over time | `t, states, targets` |
| `quadcopter.plotting.plot_3d_trajectory_comparison` | Compare multiple trajectories in 3D | `trajectories` |
| `quadcopter.plotting.plot_frequency_analysis` | Frequency domain analysis of signals | `t, signals, signal_names` |
| `quadcopter.plotting.animate_trajectory` | Matplotlib animation (MP4 / Jupyter) | `t, states`, `fps`, `save_path` |
| **Utilities** |
| `quadcopter.utils.create_pid_position_controller` | Create PID position controller with default gains | `target_pos`, `kp`, `ki`, `kd` |
| `quadcopter.utils.create_pid_attitude_controller` | Create PID attitude controller with default gains | `target_attitude`, `kp`, `ki`, `kd` |
| `quadcopter.utils.create_lqr_controller` | Create LQR controller with default matrices | `params`, `Q`, `R` |
| `quadcopter.utils.create_hover_controller` | Create simple hover controller | `params` |
---
## Usage Examples
### 1. Simplified PID Position Control
```python
from quadcopter import simulate, create_pid_position_controller
from quadcopter.dynamics import QuadState
from quadcopter.plotting import plot_trajectory
import numpy as np
# Create position controller using utility function
controller = create_pid_position_controller(
target_pos=[1.0, -1.0, 2.0],
kp=(2.0, 2.0, 4.0),
ki=(0.1, 0.1, 0.2),
kd=(0.5, 0.5, 1.0)
)
# Set up initial state
initial_state = QuadState(
pos=np.array([0.0, 0.0, 0.0]),
vel=np.array([0.0, 0.0, 0.0]),
quat=np.array([1.0, 0.0, 0.0, 0.0]),
ang_vel=np.array([0.0, 0.0, 0.0])
)
# Run simulation
t, states, controls = simulate(
duration=10.0,
dt=0.02,
controller=controller,
initial_state=initial_state,
method="rk4"
)
# Plot results
plot_trajectory(t, states, controls)
```
### 2. Advanced PID Position Control
```python
from quadcopter import simulate, PositionController, PIDController
from quadcopter.dynamics import QuadState
from quadcopter.plotting import plot_trajectory
import numpy as np
# Create position controller
controller = PositionController(
x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),
target_pos=np.array([1.0, -1.0, 2.0])
)
# Set up initial state
initial_state = QuadState(
pos=np.array([0.0, 0.0, 0.0]),
vel=np.array([0.0, 0.0, 0.0]),
quat=np.array([1.0, 0.0, 0.0, 0.0]),
ang_vel=np.array([0.0, 0.0, 0.0])
)
# Run simulation
t, states, controls = simulate(
duration=10.0,
dt=0.02,
controller=controller,
initial_state=initial_state,
method="rk4"
)
# Plot results
plot_trajectory(t, states, controls)
```
### 3. Reinforcement Learning
```python
from quadcopter.gym_env import QuadcopterGymEnv
import numpy as np
# Create RL environment
env = QuadcopterGymEnv()
# Simple policy
def simple_policy(observation):
# Simple hover policy
hover_speed = np.sqrt(0.65 * 9.81 / (4 * 3.25e-5))
return np.full(4, hover_speed)
# Training loop
obs, info = env.reset()
for _ in range(1000):
action = simple_policy(obs)
obs, reward, terminated, truncated, info = env.step(action)
if terminated or truncated:
obs, info = env.reset()
```
### 4. Real-time Simulation
```python
from quadcopter.env import RealTimeQuadcopterEnv
import numpy as np
# Create real-time environment (half speed)
env = RealTimeQuadcopterEnv(dt=0.02, real_time_factor=0.5)
obs = env.reset()
# Simple hover controller
hover_speed = np.sqrt(0.65 * 9.81 / (4 * 3.25e-5))
motor_speeds = np.full(4, hover_speed)
# Run simulation
for _ in range(200): # 4 seconds
obs = env.step(motor_speeds)
print(f"t={obs['t'][0]:.2f}s, pos={obs['pos']}")
print("Simulation completed!")
```
### 5. Comprehensive Logging
```python
from quadcopter.logging import simulate_with_logging
from quadcopter.controllers import PositionController, PIDController
import numpy as np
# Create controller
controller = PositionController(
x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),
target_pos=np.array([1.0, -1.0, 2.0])
)
# Run simulation with logging
log = simulate_with_logging(
duration=5.0,
dt=0.02,
controller=controller,
method="rk4"
)
# Export data in multiple formats
log.save_csv("trajectory_data.csv")
log.save_json("trajectory_data.json")
log.save_matlab("trajectory_data.mat")
```
### 6. Academic Evaluation
```python
from quadcopter.logging import simulate_with_academic_logging
from quadcopter.evaluation import AcademicEvaluator
from quadcopter.controllers import PositionController, PIDController
from quadcopter.dynamics import QuadState
import numpy as np
# Create position controller
controller = PositionController(
x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),
z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),
target_pos=np.array([1.0, -1.0, 2.0])
)
# Set up initial state
initial_state = QuadState(
pos=np.array([0.0, 0.0, 0.0]),
vel=np.array([0.0, 0.0, 0.0]),
quat=np.array([1.0, 0.0, 0.0, 0.0]),
ang_vel=np.array([0.0, 0.0, 0.0])
)
# Run simulation with academic logging
log = simulate_with_academic_logging(
duration=10.0,
dt=0.02,
controller=controller,
initial_state=initial_state,
ref_position=np.array([1.0, -1.0, 2.0]),
controller_type="pid"
)
# Create academic evaluator
evaluator = AcademicEvaluator(log)
# Generate comprehensive analysis with all plots and metrics
metrics = evaluator.generate_comprehensive_analysis("academic_results")
print("Academic evaluation completed! Results saved to 'academic_results' directory.")
```
---
## Examples & Notebooks
The library includes comprehensive examples demonstrating various features:
### Python Examples
Run any example with: `python examples/<example_name>.py`
- **`pid_control_example.py`** - PID position control demonstration
- **`lqr_control_example.py`** - LQR control implementation
- **`rl_training_example.py`** - Reinforcement learning training
- **`real_time_simulation.py`** - Real-time simulation with timing
- **`enhanced_plotting_example.py`** - Advanced visualization techniques
- **`enhanced_logging_example.py`** - Comprehensive data logging
- **`academic_evaluation_example.py`** - Academic evaluation and analysis
### Jupyter Notebooks
Run any notebook with: `jupyter notebook notebooks/<notebook_name>.ipynb`
- **`control_system_design.ipynb`** - Interactive PID/LQR tuning
- **`rl_training_tutorial.ipynb`** - RL experimentation and analysis
- **`data_analysis.ipynb`** - Log analysis and visualization
- **`performance_comparison.ipynb`** - Comparing different control methods
---
## Testing & Verification
```bash
pytest -q # Unit + performance tests (should be all dots)
mypy quadcopter # Static typing gate (should be 'Success')
python -m quadcopter --quiet # CLI smoke test
```
All three commands should finish without errors. A 4s RK4 simulation typically takes ≈ 0.05–0.08s on a 2020‑era laptop.
---
## Academic Use
This library is designed for academic research and education. When using in research publications, please cite:
```bibtex
@software{quadcopter_dynamics_2025,
author = {2black0},
title = {Quadcopter-Sim: A Python Toolkit for 6-DoF Quadrotor Simulation},
year = {2025},
doi = {TBD},
url = {https://github.com/2black0/quadcopter-sim-python}
}
```
---
## Roadmap
✅ **Completed Features:**
- Advanced control systems (PID, LQR, Fuzzy Logic)
- Gymnasium‑compatible wrapper for RL training
- Comprehensive logging for academic research
- Real-time simulation capabilities
- Enhanced visualization and analysis tools
- Academic evaluation and analysis tools for research publications
- Optional aerodynamic drag model
- Notebook benchmark for tuning PID / LQR / MPC / RL policies
🚧 **Future Development:**
- More controller types (MPC, Sliding Mode, etc.)
- Advanced disturbance models
- Multi-agent simulation capabilities
- Integration with hardware-in-the-loop testing
---
**Released under the MIT License.** Contributions and issues are very welcome!
Raw data
{
"_id": null,
"home_page": null,
"name": "quadcopter-sim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "2black0 <2black0@gmail.com>",
"keywords": "quadcopter, simulation, control, PID, education",
"author": null,
"author_email": "2black0 <2black0@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4d/e8/a5c00a267eef88c38446943b620c215e994c06a64002cf14a427232e2d39/quadcopter_sim-0.3.0.tar.gz",
"platform": null,
"description": "# Quadcopter\u2011Sim\n\nLight\u2011weight, strictly\u2011typed Python toolkit for **6\u2011DoF quadrotor simulation**, 3\u2011D plotting and step\u2011wise control loops \u2014 perfect for control\u2011systems classes, flight\u2011code prototyping or RL research.\n\n[](https://pypi.org/project/quadcopter-sim)\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Command Line Interface](#command-line-interface)\n- [Core Features](#core-features)\n- [API Reference](#api-reference)\n- [Usage Examples](#usage-examples)\n- [Examples & Notebooks](#examples--notebooks)\n- [Testing & Verification](#testing--verification)\n- [Academic Use](#academic-use)\n- [Roadmap](#roadmap)\n\n---\n\n## Installation\n\n```bash\n# Latest release\npip install quadcopter-sim\n\n# Development install with all optional dependencies\ngit clone https://github.com/2black0/quadcopter-sim-python\ncd quadcopter-sim-python\npip install -e .[all] # includes all optional dependencies for development\n\n# Install specific optional dependencies\npip install -e .[rl] # Gymnasium for RL\npip install -e .[control] # SciPy for advanced control\npip install -e .[data] # SciPy for data export\npip install -e .[dev] # Core development tools (testing, linting)\n```\n\n---\n\n## Quick Start\n\n### Minimal Example\n\n```python\nimport numpy as np\nfrom quadcopter.simulation import simulate, Params\nfrom quadcopter.plotting import plot_trajectory\n\np = Params()\nhover_speed = np.sqrt(p.m * p.g / (4 * p.b)) # rad/s\n\nt, s, u = simulate(\n 4.0, 0.02,\n controller=lambda *_: np.full(4, hover_speed),\n method=\"rk4\",\n)\nplot_trajectory(t, s, u)\n```\n\n### Command Line Usage\n\n```bash\n# Basic hover simulation with 3D plot\npython -m quadcopter --plot\n\n# PID position control\npython -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot\n```\n\n---\n\n## Command Line Interface\n\nThe package provides a comprehensive command-line interface for simulation, control, and analysis:\n\n### Basic Usage Examples\n\n```bash\n# Basic hover simulation\npython -m quadcopter --plot # 4 s hover + 3\u2011D figure\npython -m quadcopter --duration 6 --csv run.csv --quiet\n\n# PID position control\npython -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot\n\n# LQR control with custom parameters\npython -m quadcopter --controller lqr --duration 5 --plot\n\n# Academic analysis and logging\npython -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --academic-log results\n\n# Advanced PID tuning\npython -m quadcopter --controller pid --target-pos 1 0 1 --duration 5 \\\n --pid-kp 3 3 5 --pid-ki 0.2 0.2 0.3 --pid-kd 0.6 0.6 1.2 \\\n --plot\n\n# Custom initial conditions\npython -m quadcopter --controller pid --target-pos 0 0 2 --duration 5 \\\n --init-pos 0 0 1 --init-vel 0 0 0.5 \\\n --csv trajectory.csv --json log.json --matlab data.mat\n\n# Enhanced plotting options\npython -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot-errors\npython -m quadcopter --controller pid --target-pos 1 1 2 --duration 10 --plot-comparison\n```\n\n### CLI Options Reference\n\n```\nusage: python -m quadcopter [-h] [--duration DURATION] [--dt DT]\n [--method {rk45,rk4}] [--rtol RTOL] [--atol ATOL]\n [--controller {hover,pid,lqr}]\n [--pid-kp PID_KP PID_KP PID_KP]\n [--pid-ki PID_KI PID_KI PID_KI]\n [--pid-kd PID_KD PID_KD PID_KD]\n [--target-pos TARGET_POS TARGET_POS TARGET_POS]\n [--plot] [--csv CSV] [--json JSON]\n [--matlab MATLAB] [--academic-log ACADEMIC_LOG]\n [--controller-type {pid,lqr,rl}]\n [--init-pos INIT_POS INIT_POS INIT_POS]\n [--init-vel INIT_VEL INIT_VEL INIT_VEL] [--quiet]\n [--verbose]\n\nComprehensive quadcopter simulation and analysis tool.\n\nSimulation Parameters:\n --duration DURATION simulation time [s]\n --dt DT integration step [s]\n --method {rk45,rk4} integration method (adaptive RK45 or fixed\u2011step RK4)\n --rtol RTOL solver rtol\n --atol ATOL solver atol\n\nController Options:\n --controller {hover,pid,lqr} controller type to use\n --pid-kp PID_KP PID_KP PID_KP PID Kp gains for x, y, z axes\n --pid-ki PID_KI PID_KI PID_KI PID Ki gains for x, y, z axes\n --pid-kd PID_KD PID_KD PID_KD PID Kd gains for x, y, z axes\n --target-pos TARGET_POS TARGET_POS TARGET_POS target position [x, y, z]\n\nInitial Conditions:\n --init-pos INIT_POS INIT_POS INIT_POS initial position [x, y, z]\n --init-vel INIT_VEL INIT_VEL INIT_VEL initial velocity [vx, vy, vz]\n\nOutput Options:\n --plot show matplotlib figure\n --csv CSV save (t, state, control) to CSV\n --json JSON save simulation log to JSON\n --matlab MATLAB save simulation log to MATLAB .mat file\n --academic-log ACADEMIC_LOG enable academic logging and save to directory\n --quiet suppress info output\n --verbose enable verbose output\n```\n\n---\n\n## Core Features\n\n### 1. Advanced Control Systems\n\nComprehensive control system implementations:\n\n```python\nfrom quadcopter.controllers import PIDController, PositionController, LQRController\n\n# PID Position Control\nposition_ctrl = PositionController(\n x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),\n target_pos=np.array([1.0, -1.0, 2.0])\n)\n\n# LQR Control\nA = np.eye(12) # State matrix\nB = np.eye(12, 4) # Input matrix\nlqr_ctrl = LQRController(A=A, B=B, Q=np.eye(12), R=np.eye(4))\n```\n\n### 2. Reinforcement Learning Integration\n\nGymnasium-compatible environment for RL research:\n\n```python\nfrom quadcopter.gym_env import QuadcopterGymEnv\n\nenv = QuadcopterGymEnv()\nobs, info = env.reset()\naction = env.action_space.sample() # Random action\nobs, reward, terminated, truncated, info = env.step(action)\n```\n\n### 3. Real-time Simulation\n\nEnhanced environment with real-time capabilities:\n\n```python\nfrom quadcopter.env import RealTimeQuadcopterEnv\n\n# Run simulation at half real-time speed\nenv = RealTimeQuadcopterEnv(dt=0.02, real_time_factor=0.5)\n```\n\n### 4. Comprehensive Logging\n\nAdvanced logging with multiple export formats:\n\n```python\nfrom quadcopter.logging import simulate_with_logging\n\nlog = simulate_with_logging(duration=5.0, dt=0.02, controller=my_controller)\nlog.save_csv(\"simulation.csv\") # CSV for analysis\nlog.save_json(\"simulation.json\") # JSON for structured data\nlog.save_matlab(\"simulation.mat\") # MATLAB for advanced analysis\n```\n\n### 5. Academic Evaluation and Visualization\n\nComprehensive academic evaluation tools for research publications:\n\n```python\nfrom quadcopter.logging import simulate_with_academic_logging\nfrom quadcopter.evaluation import AcademicEvaluator\n\n# Run simulation with academic logging\nlog = simulate_with_academic_logging(\n duration=10.0, \n dt=0.02, \n controller=my_controller,\n ref_position=np.array([1.0, -1.0, 2.0]),\n controller_type=\"pid\"\n)\n\n# Create academic evaluator\nevaluator = AcademicEvaluator(log)\n\n# Generate comprehensive analysis\nmetrics = evaluator.generate_comprehensive_analysis(\"results\")\n\n# Generate specific plots\nevaluator.plot_3d_trajectory(\"trajectory.png\")\nevaluator.plot_state_tracking(\"tracking.png\")\nevaluator.plot_error_analysis(\"errors.png\")\nevaluator.plot_control_effort(\"control.png\")\n```\n\n### 6. Enhanced Visualization\n\nComprehensive plotting capabilities:\n\n```python\nfrom quadcopter.plotting import (\n plot_trajectory, \n plot_control_errors, \n plot_3d_trajectory_comparison,\n plot_frequency_analysis\n)\n\n# Control error analysis\nplot_control_errors(t, states, targets)\n\n# Trajectory comparison\nplot_3d_trajectory_comparison([\n (states1, \"Controller A\"),\n (states2, \"Controller B\")\n])\n\n# Frequency domain analysis\nplot_frequency_analysis(t, signals, [\"X Position\", \"Y Position\", \"Z Position\"])\n```\n\n---\n\n## API Reference\n\n| Function / Class | Purpose | Key Arguments |\n|------------------|---------|---------------|\n| **Core Simulation** |\n| `quadcopter.simulation.simulate` | One\u2011shot trajectory generator (adaptive RK45 or fixed\u2011step RK4) | `duration`, `dt`, `controller`, `method` |\n| `quadcopter.dynamics.Params` | Physical constants (mass, arm length, thrust factor) | edit attributes to match your air\u2011frame |\n| `quadcopter.dynamics.QuadState` | Minimal dataclass for the 13\u2011dim state | `.from_vector(vec)` / `.as_vector()` |\n| **Environments** |\n| `quadcopter.env.QuadcopterEnv` | Real\u2011time, fixed\u2011step RK4 environment | `dt`, `reset()`, `step()` |\n| `quadcopter.env.RealTimeQuadcopterEnv` | Real-time environment with timing control | `dt`, `real_time_factor`, `reset()`, `step()` |\n| `quadcopter.gym_env.QuadcopterGymEnv` | Gymnasium-compatible environment for RL training | `dt`, `max_steps` |\n| **Controllers** |\n| `quadcopter.controllers.PIDController` | PID controller with anti-windup and output limits | `kp`, `ki`, `kd`, `max_output` |\n| `quadcopter.controllers.PositionController` | 3D position controller using PID for each axis | `x_pid`, `y_pid`, `z_pid`, `target_pos` |\n| `quadcopter.controllers.LQRController` | Linear Quadratic Regulator controller | `A`, `B`, `Q`, `R` matrices |\n| **Logging & Analysis** |\n| `quadcopter.logging.SimulationLog` | Comprehensive logging with multiple export formats | `save_csv()`, `save_json()`, `save_matlab()` |\n| `quadcopter.logging.AcademicLog` | Academic-grade logging for research publications | `add_entry()`, `save_csv()`, `save_json()`, `save_matlab()` |\n| `quadcopter.logging.simulate_with_academic_logging` | Simulation with academic-grade logging | `duration`, `dt`, `controller`, `ref_position` |\n| `quadcopter.evaluation.AcademicEvaluator` | Academic evaluation tools for performance analysis | `plot_3d_trajectory()`, `plot_state_tracking()`, `generate_performance_report()` |\n| **Visualization** |\n| `quadcopter.plotting.plot_trajectory` | Static 3\u2011D + time\u2011series figure | `t, states, controls` |\n| `quadcopter.plotting.plot_control_errors` | Control error analysis over time | `t, states, targets` |\n| `quadcopter.plotting.plot_3d_trajectory_comparison` | Compare multiple trajectories in 3D | `trajectories` |\n| `quadcopter.plotting.plot_frequency_analysis` | Frequency domain analysis of signals | `t, signals, signal_names` |\n| `quadcopter.plotting.animate_trajectory` | Matplotlib animation (MP4 / Jupyter) | `t, states`, `fps`, `save_path` |\n| **Utilities** |\n| `quadcopter.utils.create_pid_position_controller` | Create PID position controller with default gains | `target_pos`, `kp`, `ki`, `kd` |\n| `quadcopter.utils.create_pid_attitude_controller` | Create PID attitude controller with default gains | `target_attitude`, `kp`, `ki`, `kd` |\n| `quadcopter.utils.create_lqr_controller` | Create LQR controller with default matrices | `params`, `Q`, `R` |\n| `quadcopter.utils.create_hover_controller` | Create simple hover controller | `params` |\n\n---\n\n## Usage Examples\n\n### 1. Simplified PID Position Control\n\n```python\nfrom quadcopter import simulate, create_pid_position_controller\nfrom quadcopter.dynamics import QuadState\nfrom quadcopter.plotting import plot_trajectory\nimport numpy as np\n\n# Create position controller using utility function\ncontroller = create_pid_position_controller(\n target_pos=[1.0, -1.0, 2.0],\n kp=(2.0, 2.0, 4.0),\n ki=(0.1, 0.1, 0.2),\n kd=(0.5, 0.5, 1.0)\n)\n\n# Set up initial state\ninitial_state = QuadState(\n pos=np.array([0.0, 0.0, 0.0]),\n vel=np.array([0.0, 0.0, 0.0]),\n quat=np.array([1.0, 0.0, 0.0, 0.0]),\n ang_vel=np.array([0.0, 0.0, 0.0])\n)\n\n# Run simulation\nt, states, controls = simulate(\n duration=10.0,\n dt=0.02,\n controller=controller,\n initial_state=initial_state,\n method=\"rk4\"\n)\n\n# Plot results\nplot_trajectory(t, states, controls)\n```\n\n### 2. Advanced PID Position Control\n\n```python\nfrom quadcopter import simulate, PositionController, PIDController\nfrom quadcopter.dynamics import QuadState\nfrom quadcopter.plotting import plot_trajectory\nimport numpy as np\n\n# Create position controller\ncontroller = PositionController(\n x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),\n target_pos=np.array([1.0, -1.0, 2.0])\n)\n\n# Set up initial state\ninitial_state = QuadState(\n pos=np.array([0.0, 0.0, 0.0]),\n vel=np.array([0.0, 0.0, 0.0]),\n quat=np.array([1.0, 0.0, 0.0, 0.0]),\n ang_vel=np.array([0.0, 0.0, 0.0])\n)\n\n# Run simulation\nt, states, controls = simulate(\n duration=10.0,\n dt=0.02,\n controller=controller,\n initial_state=initial_state,\n method=\"rk4\"\n)\n\n# Plot results\nplot_trajectory(t, states, controls)\n```\n\n### 3. Reinforcement Learning\n\n```python\nfrom quadcopter.gym_env import QuadcopterGymEnv\nimport numpy as np\n\n# Create RL environment\nenv = QuadcopterGymEnv()\n\n# Simple policy\ndef simple_policy(observation):\n # Simple hover policy\n hover_speed = np.sqrt(0.65 * 9.81 / (4 * 3.25e-5))\n return np.full(4, hover_speed)\n\n# Training loop\nobs, info = env.reset()\nfor _ in range(1000):\n action = simple_policy(obs)\n obs, reward, terminated, truncated, info = env.step(action)\n if terminated or truncated:\n obs, info = env.reset()\n```\n\n### 4. Real-time Simulation\n\n```python\nfrom quadcopter.env import RealTimeQuadcopterEnv\nimport numpy as np\n\n# Create real-time environment (half speed)\nenv = RealTimeQuadcopterEnv(dt=0.02, real_time_factor=0.5)\nobs = env.reset()\n\n# Simple hover controller\nhover_speed = np.sqrt(0.65 * 9.81 / (4 * 3.25e-5))\nmotor_speeds = np.full(4, hover_speed)\n\n# Run simulation\nfor _ in range(200): # 4 seconds\n obs = env.step(motor_speeds)\n print(f\"t={obs['t'][0]:.2f}s, pos={obs['pos']}\")\n\nprint(\"Simulation completed!\")\n```\n\n### 5. Comprehensive Logging\n\n```python\nfrom quadcopter.logging import simulate_with_logging\nfrom quadcopter.controllers import PositionController, PIDController\nimport numpy as np\n\n# Create controller\ncontroller = PositionController(\n x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),\n target_pos=np.array([1.0, -1.0, 2.0])\n)\n\n# Run simulation with logging\nlog = simulate_with_logging(\n duration=5.0,\n dt=0.02,\n controller=controller,\n method=\"rk4\"\n)\n\n# Export data in multiple formats\nlog.save_csv(\"trajectory_data.csv\")\nlog.save_json(\"trajectory_data.json\")\nlog.save_matlab(\"trajectory_data.mat\")\n```\n\n### 6. Academic Evaluation\n\n```python\nfrom quadcopter.logging import simulate_with_academic_logging\nfrom quadcopter.evaluation import AcademicEvaluator\nfrom quadcopter.controllers import PositionController, PIDController\nfrom quadcopter.dynamics import QuadState\nimport numpy as np\n\n# Create position controller\ncontroller = PositionController(\n x_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n y_pid=PIDController(kp=2.0, ki=0.1, kd=0.5),\n z_pid=PIDController(kp=4.0, ki=0.2, kd=1.0),\n target_pos=np.array([1.0, -1.0, 2.0])\n)\n\n# Set up initial state\ninitial_state = QuadState(\n pos=np.array([0.0, 0.0, 0.0]),\n vel=np.array([0.0, 0.0, 0.0]),\n quat=np.array([1.0, 0.0, 0.0, 0.0]),\n ang_vel=np.array([0.0, 0.0, 0.0])\n)\n\n# Run simulation with academic logging\nlog = simulate_with_academic_logging(\n duration=10.0,\n dt=0.02,\n controller=controller,\n initial_state=initial_state,\n ref_position=np.array([1.0, -1.0, 2.0]),\n controller_type=\"pid\"\n)\n\n# Create academic evaluator\nevaluator = AcademicEvaluator(log)\n\n# Generate comprehensive analysis with all plots and metrics\nmetrics = evaluator.generate_comprehensive_analysis(\"academic_results\")\n\nprint(\"Academic evaluation completed! Results saved to 'academic_results' directory.\")\n```\n\n---\n\n## Examples & Notebooks\n\nThe library includes comprehensive examples demonstrating various features:\n\n### Python Examples\n\nRun any example with: `python examples/<example_name>.py`\n\n- **`pid_control_example.py`** - PID position control demonstration\n- **`lqr_control_example.py`** - LQR control implementation\n- **`rl_training_example.py`** - Reinforcement learning training\n- **`real_time_simulation.py`** - Real-time simulation with timing\n- **`enhanced_plotting_example.py`** - Advanced visualization techniques\n- **`enhanced_logging_example.py`** - Comprehensive data logging\n- **`academic_evaluation_example.py`** - Academic evaluation and analysis\n\n### Jupyter Notebooks\n\nRun any notebook with: `jupyter notebook notebooks/<notebook_name>.ipynb`\n\n- **`control_system_design.ipynb`** - Interactive PID/LQR tuning\n- **`rl_training_tutorial.ipynb`** - RL experimentation and analysis\n- **`data_analysis.ipynb`** - Log analysis and visualization\n- **`performance_comparison.ipynb`** - Comparing different control methods\n\n---\n\n## Testing & Verification\n\n```bash\npytest -q # Unit + performance tests (should be all dots)\nmypy quadcopter # Static typing gate (should be 'Success')\npython -m quadcopter --quiet # CLI smoke test\n```\n\nAll three commands should finish without errors. A 4s RK4 simulation typically takes \u2248 0.05\u20130.08s on a 2020\u2011era laptop.\n\n---\n\n## Academic Use\n\nThis library is designed for academic research and education. When using in research publications, please cite:\n\n```bibtex\n@software{quadcopter_dynamics_2025,\n author = {2black0},\n title = {Quadcopter-Sim: A Python Toolkit for 6-DoF Quadrotor Simulation},\n year = {2025},\n doi = {TBD},\n url = {https://github.com/2black0/quadcopter-sim-python}\n}\n```\n\n---\n\n## Roadmap\n\n\u2705 **Completed Features:**\n- Advanced control systems (PID, LQR, Fuzzy Logic)\n- Gymnasium\u2011compatible wrapper for RL training\n- Comprehensive logging for academic research\n- Real-time simulation capabilities\n- Enhanced visualization and analysis tools\n- Academic evaluation and analysis tools for research publications\n- Optional aerodynamic drag model\n- Notebook benchmark for tuning PID / LQR / MPC / RL policies\n\n\ud83d\udea7 **Future Development:**\n- More controller types (MPC, Sliding Mode, etc.)\n- Advanced disturbance models\n- Multi-agent simulation capabilities\n- Integration with hardware-in-the-loop testing\n\n---\n\n**Released under the MIT License.** Contributions and issues are very welcome!\n",
"bugtrack_url": null,
"license": null,
"summary": "Light\u2011weight quadcopter dynamics, PID control and visualisation in pure Python.",
"version": "0.3.0",
"project_urls": null,
"split_keywords": [
"quadcopter",
" simulation",
" control",
" pid",
" education"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6e014c0aed73de96684d8401040a8536eb608a76b74d87ea2eeb9aed11b9f41a",
"md5": "1228ce1b2246f3412d1c2f714610d14f",
"sha256": "52dc2d40045eaeae4067959d06f88be2409770818ae3072a0b7fa3bd9958edbf"
},
"downloads": -1,
"filename": "quadcopter_sim-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1228ce1b2246f3412d1c2f714610d14f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 36666,
"upload_time": "2025-08-12T22:24:13",
"upload_time_iso_8601": "2025-08-12T22:24:13.266534Z",
"url": "https://files.pythonhosted.org/packages/6e/01/4c0aed73de96684d8401040a8536eb608a76b74d87ea2eeb9aed11b9f41a/quadcopter_sim-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4de8a5c00a267eef88c38446943b620c215e994c06a64002cf14a427232e2d39",
"md5": "a4133cc7965a8e463ff309c52c807747",
"sha256": "d0a1202d34804741a241c1eaf4f3c6f0007a3e5a1ac61f7bcb7330f5d9425463"
},
"downloads": -1,
"filename": "quadcopter_sim-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a4133cc7965a8e463ff309c52c807747",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44257,
"upload_time": "2025-08-12T22:24:15",
"upload_time_iso_8601": "2025-08-12T22:24:15.191333Z",
"url": "https://files.pythonhosted.org/packages/4d/e8/a5c00a267eef88c38446943b620c215e994c06a64002cf14a427232e2d39/quadcopter_sim-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 22:24:15",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "quadcopter-sim"
}
JSON