Metadata-Version: 2.4
Name: vehicle-dynamics-sim
Version: 0.1.2
Summary: Modular vehicle dynamics simulation package
Author: Fabien Lionti
Project-URL: Homepage, https://github.com/fabien-lionti/vdsim
Project-URL: Documentation, https://fabien-lionti.github.io/vdsim/
Project-URL: Repository, https://github.com/fabien-lionti/vdsim
Project-URL: Issues, https://github.com/fabien-lionti/vdsim/issues
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 vehicle-dynamics simulator with two backends:

- `vdsim.backends.numpy`: standard NumPy simulation, controllers, trajectories,
  logging, and analysis.
- `vdsim.backends.torch`: differentiable PyTorch vehicle dynamics for gradient
  based calibration, optimization, and learning workflows.

The historical packages `vdsim.models`, `vdsim.simulation`, `vdsim.controllers`,
`vdsim.trajectories`, `vdsim.analysis`, and `vdsim.torch` remain available as
compatibility facades, but new code should prefer `vdsim.backends.*`.

## Features

- Vehicle models: DOF2, DOF7, and DOF10.
- Tire models: linear and simplified Pacejka.
- NumPy backend with Euler/RK4 integration, closed-loop runner, controllers,
  trajectories, logs, and analysis helpers.
- PyTorch backend with differentiable DOF2/DOF7/DOF10, differentiable tire
  models, batched tensor calls, and open-loop Euler/RK4 simulation.
- Torch control helpers for gradient-based direct shooting and batched MPPI.
- Examples for tire calibration, DOF10-to-DOF7 reduced-model identification,
  closed-loop trajectories, and dataset generation.
- MkDocs documentation under `docs/`.

## Installation

From the repository root:

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

Install the optional PyTorch dependency when using the differentiable backend:

```bash
python -m pip install -e ".[torch]"
```

## Quick Start: NumPy Backend

```python
import numpy as np

from vdsim.backends.numpy import (
    DOF2,
    LinearTireParams,
    VehicleConfig2DOF,
    VehiclePhysicalParams2DOF,
)

vehicle = VehiclePhysicalParams2DOF(
    g=9.81,
    m=1500.0,
    lf=1.2,
    lr=1.6,
    r=0.3,
    iz=2500.0,
)
tire = LinearTireParams(Cx=80000.0, Cy=80000.0)
model = DOF2(VehicleConfig2DOF(vehicle, tire, tire, tire, tire))

state = np.array([0.0, 20.0, 0.0, 0.0, 0.0, 0.0])
control = np.array([0.0, 0.0, 0.0, 0.0, 0.01, 0.0])

dx, outputs = model.get_dx__dt(state, control)
print(dx)
print(outputs["Fy"])
```

## Quick Start: PyTorch Backend

```python
import torch

from vdsim.backends.numpy import LinearTireParams, VehicleConfig7DOF, VehiclePhysicalParams7DOF
from vdsim.backends.torch import TorchDOF7
from vdsim.backends.torch.simulation import simulate

vehicle = VehiclePhysicalParams7DOF(
    g=9.81,
    m=1500.0,
    lf=1.2,
    lr=1.6,
    h=0.5,
    L1=1.0,
    L2=1.6,
    r=0.3,
    iz=2500.0,
    ir=1.2,
    ra=0.015,
    s=0.01,
    cx=0.3,
)
tire = LinearTireParams(Cx=80000.0, Cy=80000.0)
model = TorchDOF7(VehicleConfig7DOF(vehicle, tire, tire, tire, tire))

x0 = torch.tensor([0.0, 20.0, 0.0, 0.0, 0.0, 0.0, 66.0, 66.0, 66.0, 66.0])
u = torch.zeros(20, 6, dtype=torch.float64, requires_grad=True)
states, outputs = simulate(model, x0, u, dt=0.001, method="rk4")

loss = states[-1, 2].square()
loss.backward()
print(u.grad is not None)
```

## Useful Commands

```bash
python -m pytest
```

## Examples

Useful calibration examples:

```bash
python examples/calibrate_dof7_tire_params_torch.py
python examples/calibrate_dof7_pacejka_tire_params_torch.py
python examples/calibrate_dof7_from_dof10_pacejka_torch.py
python examples/differentiable_mpc_dof7.py
python examples/mppi_batched_dof7.py
```

Other scenario examples live in `examples/`.

## Project Layout

```text
vdsim/
  backends/
    numpy/
      models/
      simulation/
      controllers/
      trajectories/
      analysis/
    torch/
      vehicle/
      tires/
      simulation/
  models/         # compatibility facade
  simulation/     # compatibility facade
  controllers/    # compatibility facade
  trajectories/   # compatibility facade
  analysis/       # compatibility facade
  torch/          # compatibility facade
```

## Documentation

The complete documentation is available online:

https://fabien-lionti.github.io/vdsim/

The most important pages are:

- `docs/reference/backend_architecture.md`
- `docs/reference/state_conventions.md`
- `docs/reference/numpy.md`
- `docs/reference/torch.md`

## Tests

```bash
python -m pytest
```

The test suite covers NumPy models, PyTorch parity, backend import
compatibility, state conventions, analysis helpers, and differentiable
simulation.
