Metadata-Version: 2.4
Name: vehicle-dynamics-sim
Version: 0.1.0
Summary: Modular vehicle dynamics simulation package
Author: Fabien Lionti
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: pytest
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"

# VDSim

VDSim is a Python package for vehicle dynamics simulation. It provides vehicle
models, tire models, reference trajectories, controllers, integrators, and
logging utilities for open-loop and closed-loop simulation scenarios.

The current package namespace is `vdsim`.

## Features

- `DOF7` and `DOF10` vehicle models.
- Linear and Simplified Pacejka tire models.
- Reference trajectories: straight line, slalom, double lane change, circle,
  lemniscate, waypoints, and smooth random paths.
- PID speed control and Stanley lateral tracking.
- Closed-loop orchestration with `ClosedLoopRunner`.
- Euler and RK4 integrators.
- Vehicle state, command, and tire signal logs.
- Example scripts and generated CSV datasets under `examples/`.
- MkDocs documentation under `docs/`.

## Requirements

- Python 3.8 or newer.
- `pip`.
- Runtime dependencies declared in `setup.py`: `numpy`, `matplotlib`,
  `pandas`, and `pytest`.
- `scipy` is required for `vdsim.trajectories.SmoothRandomTrajectory`.
- Documentation tools: `mkdocs`, `mkdocs-material`, and `mkdocstrings[python]`.

## Installation

From the repository root:

```bash
python -m pip install -e .
```

Documentation tools are optional:

```bash
python -m pip install mkdocs mkdocs-material "mkdocstrings[python]"
```

Install `scipy` if you use `SmoothRandomTrajectory`:

```bash
python -m pip install scipy
```

## Quick Start

Run a minimal tire-model check:

```bash
python - <<'PY'
from vdsim.models.tires import LinearTireParams, LinearTireModel

tire = LinearTireModel(LinearTireParams(Cx=1000.0, Cy=800.0))
print(tire.get_fx0(fz0=3000.0, fz=3000.0, sigma=0.1))
PY
```

Expected output:

```text
100.0
```

Sample a reference trajectory:

```python
from vdsim.trajectories import SlalomTrajectory

trajectory = SlalomTrajectory(v_ref=20.0)
point = trajectory.sample(t=1.0)

print(point.to_dict())
```

## Useful Commands

```bash
# Run tests
python -m pytest

# Serve the documentation locally
mkdocs serve

# Build the static documentation
mkdocs build
```

## Project Layout

```text
.
├── setup.py
├── mkdocs.yml
├── docs/
├── examples/
├── tests/
└── vdsim/
    ├── analysis/
    │   └── rollover.py
    ├── controllers/
    │   ├── base.py
    │   ├── pid_speed.py
    │   └── stanley.py
    ├── models/
    │   ├── tires/
    │   │   ├── base.py
    │   │   ├── linear.py
    │   │   ├── pacejka.py
    │   │   └── registry.py
    │   └── vehicle/
    │       ├── base.py
    │       ├── dof7.py
    │       └── dof10.py
    ├── simulation/
    │   ├── runner.py
    │   ├── integrators/
    │   │   ├── euler.py
    │   │   ├── rk4.py
    │   │   └── step.py
    │   └── results/
    └── trajectories/
        ├── base.py
        ├── library.py
        └── smooth_random.py
```

Module files use lowercase `snake_case`; public classes keep `PascalCase`.

## Main Modules

- `vdsim.models.vehicle`: vehicle models, physical parameters, and model
  configuration dataclasses.
- `vdsim.models.tires`: tire models, tire parameter dataclasses, and the tire
  model registry.
- `vdsim.trajectories`: reference trajectories sampled with `sample(t)`.
- `vdsim.controllers`: speed and steering controllers.
- `vdsim.simulation.integrators`: Euler and RK4 integration utilities.
- `vdsim.simulation.runner`: closed-loop simulation orchestration.
- `vdsim.simulation.results`: `VehicleLog`, `TireLog`, and `SimulationResult`
  containers.
- `vdsim.analysis`: analysis helpers.

## Examples

The `examples/` directory contains simulation and dataset scripts, including:

- `example_circle_dof10linear.py`
- `example_circle_dof10pacejka.py`
- `example_double_lanechange_dof10linear.py`
- `example_double_lanechange_dof10pacejka.py`
- `example_slalom_dof10pacejka.py`
- `example_lemniscate_dof10pacejka.py`
- `trajectory_closed_loop.py`
- `example_generate_dataset.py`
- `sim_data.py`

Example scripts use imports from the public `vdsim` namespace:

```python
from vdsim.models.vehicle import DOF10, VehiclePhysicalParams10DOF, VehicleConfig10DOF
from vdsim.models.tires import LinearTireParams, SimplifiedPacejkaTireParams
from vdsim.controllers import SpeedPIDController, StanleyController
from vdsim.trajectories import DoubleLaneChangeTrajectory
from vdsim.simulation.runner import ClosedLoopRunner
```

## Documentation

Documentation sources live in `docs/`; MkDocs configuration lives in
`mkdocs.yml`.

```bash
mkdocs serve
```

The local site is served by default at:

```text
http://127.0.0.1:8000/
```

## Tests

```bash
python -m pytest
```

The existing tests cover vehicle parameters, the 7DOF/10DOF models, and
integrator consistency.
