# AlpaSim: A modular, lightweight, and data-driven research simulator for autonomous driving

<div align="center">
  <img src="docs/assets/images/thumbnail.gif" alt="AlpaSim Simulation Demo" width="600">
</div>

## What is AlpaSim?

AlpaSim is an open-source autonomous vehicle simulation platform designed specifically for research
and development. It allows users to test end-to-end AV policies in a closed-loop setting by
simulating realistic sensor data, vehicle dynamics, and traffic scenarios within a modular and
extensible testbed.

Suitable use cases include:

- **Algorithm Validation**: Test new autonomous driving algorithms in realistic environments
- **Safety Analysis**: Evaluate vehicle behavior in edge cases and challenging scenarios
- **Performance Benchmarking/Regression Testing**: Compare different models and configurations
- **Debugging**: Understand and debug complex autonomous driving behaviors

### **Sensor Fidelity**

- Pluggable renderer service with default [NuRec](https://docs.nvidia.com/nurec/) support and
  [OmniDreams](https://github.com/nv-tlabs/omni-dreams) video-model rendering through
  [FlashDreams](https://github.com/NVIDIA/flashdreams)
- High-fidelity camera feeds with configurable field-of-view, resolution, and frame rates
- Stateful video-model rendering for stronger dynamic-object and non-rigid visual fidelity
- Realistic sensor noise and environmental conditions

### **Research Hackability**

- Python-based implementation built for rapid prototyping and experimentation
- Modular grpc interface design allows researchers to swap out components with custom
  implementations
- Extensive configuration options and debugging tools

### **Horizontal Scalability**

- Microservices architecture enabling distributed computing
- Scale individual components for optimal load balancing
- Support for multi-node deployments

To learn more about the design principles and architecture, check out the
[system design docs](docs/DESIGN.md).

## Driving Policies

AlpaSim currently supports the following driver policies:

- [Alpamayo-R1](https://github.com/NVlabs/alpamayo) - NVIDIA Alpamayo, a VLA driving policy with
  chain-of-causation reasoning
- [Alpamayo 1.5](https://github.com/NVlabs/alpamayo1.5) - Public Alpamayo 1.5 checkpoint support
  is also available
- [VaVAM](https://github.com/valeoai/VideoActionModel) - an autoregressive video-action driving
  policy
- [Transfuser](https://github.com/autonomousvision/lead?tab=readme-ov-file#beyond-carla-cross-benchmark-deployment)
  \- Latent TransFuser v6 ([LTFv6](<(https://huggingface.co/ln2697/tfv6_navsim)>)) policy developed
  for [NAVSIM](https://github.com/autonomousvision/navsim) (provisional)

Stay tuned for additional model support. [Contributions](#contributing) from the community are
appreciated.

## Support

📣 **Usage questions and discussion about AlpaSim**: please join us on the [Alpamayo NV Developer Forum](https://forums.developer.nvidia.com/c/autonomous-vehicles/alpamayo/766).

🐛 **Code-level bugs, documentation issues, and feature requests**: file a [GitHub issue](../../issues/new/choose) using the appropriate template (Bug report, Documentation request, or Feature request). The relevant NVIDIA responder is auto-assigned via the `assignees:` field on the template.

🚨 **Security vulnerabilities**: please use [NVIDIA's Vulnerability Disclosure Program](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). Do not file security issues publicly here.

## Getting Started

To run simulations locally (Docker Compose, single machine), see the [Tutorial](docs/TUTORIAL.md).
The default tutorial path uses NuRec; for OmniDreams as the renderer backend, see the
[Video Model Renderer guide](docs/VIDEO_MODEL.md).
For cluster or SLURM deployment, see `src/tools/run-on-slurm`.

## Documentation & Resources

- **[Onboarding Guide](docs/ONBOARDING.md)**: Initial setup and access instructions
- **[Tutorial](docs/TUTORIAL.md)**: Step-by-step usage guide
- **[Manual Driver](docs/MANUAL_DRIVER.md)**: Interactive keyboard control of the ego vehicle
- **[Video Model Renderer](docs/VIDEO_MODEL.md)**: Running OmniDreams through FlashDreams as the
  AlpaSim renderer backend
- **[Operations Guide](docs/OPERATIONS.md)**: Performance tuning, configuration, and troubleshooting
- **[Telemetry Guide](docs/TELEMETRY.md)**: Prometheus metrics, persistence, and central discovery
- **[Data Pipeline](docs/DATA_PIPELINE.md)**: ASL log format and reading logs
- **[Design Documentation](docs/DESIGN.md)**: Technical architecture and design decisions
- **[Plugin System](docs/PLUGIN_SYSTEM.md)**: Extending AlpaSim with custom models, configs, and tools
- **[API Reference](src/grpc/)**: gRPC API documentation
- **[Changelog](CHANGELOG.md)**: Major updates and migration notes
- **[Contributing](CONTRIBUTING.md)**: Code style, coordinate conventions, and PR process
- **[Developer Quick Reference](AGENTS.md)**: Build commands, testing, and CI workflow
- **[Test Suites & Scenes](data/scenes/README.md)**: Available scene datasets

### **Sample Data**

- **Hugging Face Dataset**:
  [PhysicalAI-Autonomous-Vehicles-NuRec 26.01](https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles-NuRec/tree/26.01/sample_set/26.01_release)
  is recommended for new runs. See
  [Test Suites & Scenes](data/scenes/README.md) for release selection and legacy
  dataset commands.
- **Sample Artifacts**: Included in the repository via Git LFS

## Contributing

We welcome contributions from the research community! Please see our
[Contributing Guide](CONTRIBUTING.md) for details on:

- Code style and conventions
- Testing requirements
- Pull request process
- Development setup

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

## Citation

If you use this software, please cite it as follows:

```
@software{alpasim_2025,
  author       = {
    NVIDIA and
    Yulong Cao and
    Riccardo de Lutio and
    Sanja Fidler and
    Guillermo Garcia Cobo and
    Zan Gojcic and
    Maximilian Igl and
    Boris Ivanovic and
    Peter Karkus and
    Janick Martinez Esturo and
    Marco Pavone and
    Aaron Smith and
    Ellie Tanimura and
    Michal Tyszkiewicz and
    Michael Watson and
    Qi Wu and
    Le Zhang
  },
  title        = {AlpaSim: A Modular, Lightweight, and Data-Driven Research Simulator for Autonomous Driving},
  year         = {2025},
  month        = {October},
  url          = {https://github.com/NVlabs/alpasim},
}
```

## Project Contributors:

Contributors in each topic in alphabetical order

**Project Lead:** Maximilian Igl

**Tech Leads:** Michal Tyszkiewicz, Michael Watson

**Architecture Design & Networking:** Michal Tyszkiewicz

**Open Sourcing:** Guillermo Garcia Cobo, Maximilian Igl, Peter Karkus, Ellie Tanimura, Michael
Watson

**Infrastructure & Wizard:** Maximilian Igl, Aaron Smith, Michal Tyszkiewicz, Michael Watson, Qi Wu
(SLURM deployment), Le Zhang (Data management)

**Runtime:** Maximilian Igl, Aaron Smith, Ellie Tanimura, Michal Tyszkiewicz, Michael Watson

**CICD:** Maximilian Igl, Aaron Smith

**Data Pipeline:** Riccardo de Lutio, Janick Martinez, Le Zhang

**Product Manager:** Matt Cragun

**Testing & debugging:** Guillermo Garcia Cobo, Peter Karkus, Ellie Tanimura

**Service Modules:**

- Driver integration: Maximilian Igl, Peter Karkus, Michal Tyszkiewicz
- Evaluation: Yulong Cao, Maximilian Igl
- Controller: Michael Watson
- Physics: Riccardo de Lutio
- Trafficsim: Maximilian Igl, Boris Ivanovic

**Senior Mgmt:** Sanja Fidler, Zan Gojcic, Boris Ivanovic, Marco Pavone

**Acknowledgements for additional contributions:** Fabian Barajas, Kashyap Chitta, Ankit Gupta,
Laura Leal-Taixe, Nicole Yang

<div align="center">
  <strong>Built for researchers, by researchers</strong><br>
  <em>Accelerating autonomous vehicle development through realistic simulation</em>
</div>