https://github.com/hanruihua/ir-sim
A Python-based lightweight robot simulator designed for navigation, control, and learning
https://github.com/hanruihua/ir-sim
autonomous-driving control ir-sim multi-agent navigation python reinforcement-learning robotics robotics-simulation simulator
Last synced: about 2 hours ago
JSON representation
A Python-based lightweight robot simulator designed for navigation, control, and learning
- Host: GitHub
- URL: https://github.com/hanruihua/ir-sim
- Owner: hanruihua
- License: mit
- Created: 2022-05-30T03:51:40.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2026-04-03T18:03:22.000Z (3 days ago)
- Last Synced: 2026-04-03T20:25:21.318Z (3 days ago)
- Topics: autonomous-driving, control, ir-sim, multi-agent, navigation, python, reinforcement-learning, robotics, robotics-simulation, simulator
- Language: Python
- Homepage: https://ir-sim.readthedocs.io/en/stable/
- Size: 145 MB
- Stars: 1,047
- Watchers: 10
- Forks: 132
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
# Intelligent Robot Simulator (IR-SIM)
*A lightweight, YAML-driven robot simulator for navigation, control, and learning*
## Overview
**IR-SIM** is an open-source, Python-based, lightweight robot simulator designed for navigation, control, and learning. It provides a simple, user-friendly framework with built-in collision detection for modeling robots, sensors, and environments. Ideal for academic and educational use, IR-SIM enables rapid prototyping of robotics and learning algorithms in custom scenarios with minimal coding and hardware requirements.
## Key Features
- Simulate robot platforms with diverse kinematics, sensors, and behaviors ([support](#support)).
- Quickly configure and customize scenarios using straightforward YAML files. No complex coding required.
- Visualize simulation outcomes using a naive visualizer matplotlib for immediate debugging.
- Support collision detection and customizable behavior policies for each object.
- Suitable for mutli-agent/robot learning ([Projects](#projects-using-ir-sim)).
## Demonstrations
Multi-Robot RVO Collision Avoidance
Source
Ackermann Robot with 2D LiDAR
Source
HM3D / MatterPort3D Grid Map
Source
Field-of-View Detection
Source
Dynamic Random Obstacles
Source
200-Agent ORCA via pyrvo
Source
## Installation
> **Requires Python >= 3.10**
### pip
```bash
pip install ir-sim
# Optional: keyboard control and all extras
pip install ir-sim[all]
```
### From source
```bash
git clone https://github.com/hanruihua/ir-sim.git
cd ir-sim
pip install -e .
```
### uv
```bash
git clone https://github.com/hanruihua/ir-sim.git
cd ir-sim
uv sync
```
## Quick Start
A minimal example: a differential-drive robot navigates toward a goal using the built-in `dash` behavior.
```python
import irsim
env = irsim.make('robot_world.yaml') # initialize the environment with the configuration file
for i in range(300): # run the simulation for 300 steps
env.step() # update the environment
env.render() # render the environment
if env.done(): break # check if the simulation is done
env.end() # close the environment
```
YAML Configuration: `robot_world.yaml`
```yaml
world:
height: 10 # the height of the world
width: 10 # the width of the world
step_time: 0.1 # 10Hz calculate each step
sample_time: 0.1 # 10 Hz for render and data extraction
offset: [0, 0] # the offset of the world on x and y
robot:
kinematics: {name: 'diff'} # omni, diff, acker
shape: {name: 'circle', radius: 0.2} # radius
state: [1, 1, 0] # x, y, theta
goal: [9, 9, 0] # x, y, theta
behavior: {name: 'dash'} # move toward to the goal directly
color: 'g' # green
```
For more examples, see the [usage directory](https://github.com/hanruihua/ir-sim/tree/main/usage) and the [documentation](https://ir-sim.readthedocs.io/en).
## Support
| **Category** | **Features** |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kinematics** | Differential Drive mobile Robot · Omnidirectional mobile Robot · Ackermann Steering mobile Robot |
| **Sensors** | 2D LiDAR · FOV Detector |
| **Geometries** | Circle · Rectangle · Polygon · LineString · Binary Grid Map |
| **Behaviors** | dash (move directly toward goal) · RVO (Reciprocal Velocity Obstacle) · ORCA (Optimal Reciprocal Collision Avoidance) |
## Documentation
- **English:** [https://ir-sim.readthedocs.io/en](https://ir-sim.readthedocs.io/en)
- **Chinese (中文):** [https://ir-sim.readthedocs.io/zh-cn](https://ir-sim.readthedocs.io/zh-cn)
## Projects Using IR-SIM
### Academic Publications
- **[RAL & ICRA 2023]** [rl-rvo-nav](https://github.com/hanruihua/rl_rvo_nav) -- Reinforcement learning-based RVO behavior for multi-robot navigation.
- **[RAL & IROS 2023]** [RDA_planner](https://github.com/hanruihua/RDA_planner) -- Accelerated collision-free motion planner for cluttered environments.
- **[T-RO 2025]** [NeuPAN](https://github.com/hanruihua/NeuPAN) -- Direct point robot navigation with end-to-end model-based learning.
### Community Projects
- [DRL-robot-navigation-IR-SIM](https://github.com/reiniscimurs/DRL-robot-navigation-IR-SIM) -- Deep reinforcement learning for robot navigation.
- [AutoNavRL](https://github.com/harshmahesheka/AutoNavRL) -- Autonomous navigation using reinforcement learning.
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/hanruihua/ir-sim/blob/main/CONTRIBUTING.md) for guidelines.
## Acknowledgement
- [PythonRobotics](https://github.com/AtsushiSakai/PythonRobotics)
## License
IR-SIM is released under the [MIT License](https://github.com/hanruihua/ir-sim?tab=MIT-1-ov-file).