IR-SIM: Lightweight Robot Simulator
A Python-based lightweight simulator for navigation, control, and learning, configured via simple YAML files.
- Source repo
- hanruihua/ir-sim
- Stars
- ★ 1.1k
- Last updated
- 8d ago
- License
- MIT
- Primary language
- Python
- FA score
- 43/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Robotics researchers: Rapidly prototype and test navigation or collision avoidance algorithms in custom YAML scenarios.
- Not a fit if
- Teams needing complex 3D rendering or high-fidelity physics
- Non-technical users unwilling to write YAML config files
- Projects requiring a large mature community and ecosystem
- Source review
- 43/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
IR-SIM is an open-source, lightweight Python robot simulator designed for navigation, control, and learning. It offers a user-friendly framework with built-in collision detection for modeling robots, sensors, and environments. Users can quickly configure and customize scenarios using straightforward YAML files without complex coding. Simulation results are visualized via a simple matplotlib-based visualizer for immediate debugging. IR-SIM supports various kinematics models (e.g., differential, omnidirectional, Ackermann) and sensors (e.g., 2D LiDAR, FOV detector), and includes built-in behaviors like RVO and ORCA for collision avoidance. It has been adopted in academic publications (e.g., RAL & ICRA 2023 RL-RVO navigation) and community projects (e.g., DRL robot navigation). IR-SIM is ranked #1 among 2D robot simulators in the best-of-robot-simulators list.
IR-SIM reads YAML configuration files to initialize the simulation environment, simulates robot motion, processes sensor data, and executes collision detection and behavior policies (e.g., dash, RVO, ORCA). It provides a Python API (e.g., irsim.make('robot_world.yaml')) to create the environment, and users loop over env.step() and env.render() to advance and visualize the simulation. The simulation ends with env.end(). The simulator outputs simulation results for analysis.
- Robotics researchers: Rapidly prototype and test navigation or collision avoidance algorithms in custom YAML scenarios.
- Reinforcement learning practitioners: Train and evaluate navigation agents using multi-agent support, as in the RL-RVO project.
- Educators: Demonstrate robot kinematics and sensor principles in classrooms; students can modify scenarios without deep coding.
- Autonomous driving developers: Simulate Ackermann kinematics with 2D LiDAR to test vehicle control algorithms.
- Multi-agent system developers: Simulate hundreds of agents (e.g., 200 ORCA agents) for collaborative collision avoidance and benchmarking.
How do you install or deploy this agent?
Requires Python >= 3.10. Install via pip: pip install ir-sim, or with all extras: pip install ir-sim[all]. From source: git clone https://github.com/hanruihua/ir-sim.git && cd ir-sim && pip install -e . Alternatively, use uv: uv sync.
How do you use this agent?
Create a YAML configuration file (e.g., robot_world.yaml) defining world dimensions, robot kinematics, shape, initial state, goal, and behavior. Write a Python script using irsim.make() to initialize the environment, loop over env.step() and env.render(), check env.done() to terminate, and finally env.end(). See the usage directory for examples.
What are this agent's strengths and limitations?
- Lightweight and easy to use; scenarios configured via YAML without complex code.
- Supports multiple kinematics models (differential, omnidirectional, Ackermann) and sensors (2D LiDAR, FOV detector).
- Built-in collision avoidance behaviors like RVO and ORCA, suitable for multi-agent research.
- Directly linked to academic papers (e.g., RL-RVO, NeuPAN), providing research validation.
- Relatively new, with a smaller community and ecosystem compared to mature simulators like Gazebo.
- Documentation and examples primarily in English; Chinese docs may be less complete.
- Visualization relies on matplotlib, which may be insufficient for complex 3D renderings.
- Requires writing YAML configuration, presenting a learning curve for non-technical users.
How does this agent compare with similar options?
In contrast to heavyweight simulators like Gazebo, IR-SIM is lighter and easier to get started with, ideal for rapid prototyping. It is ranked #1 among 2D robot simulators in the best-of-robot-simulators list, highlighting its strengths in lightweight 2D simulation.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| IR-SIM: Lightweight Robot Simulator This agent | 43 · Major gaps | Library / SDKFree | ★ 1.1k | 8d ago | Python | — |
| Youtu-Agent | 27 · Major gaps | CLIFree + model costs | ★ 4.6k | 7mo ago | Python | OpenAI API |
| skrl: Modular Reinforcement Learning Library | 43 · Major gaps | Library / SDKFree | ★ 1.1k | today | Python | — |
| AgentGuide - All-in-One AI Agent Development & Interview Guide | 23 · Major gaps | Library / SDKFree + model costs | ★ 11k | 1mo ago | MDX | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: the repository provides no permission model, user confirmation mechanism, data flow transparency, sensitive data handling, external effects control, rollback mechanism, or source attribution. For dependency security, there is a dependency review workflow, but no vulnerability scan results or dependency lock are provided. Therefore, all trust criteria score 0.
Evidence shows: consistency among README, pyproject.toml, test configuration, and examples is good, so self-consistency scores 2. Dependencies are available on PyPI and version constraints are listed in pyproject.toml, but no lock file is provided, so dependency availability scores 2. For failure messages, loguru is used in code, but no user-friendly error handling or documentation is provided, so it scores 1.
Evidence shows: README clearly lists target audience (academic and educational) and multiple usage scenarios, scoring 2. Capability boundaries are clearly described through the support table, scoring 2. Trigger precision is clear through YAML configuration and API design, scoring 2. Environment fit is good with support for multiple Python versions and OS, scoring 2.
Evidence shows: information architecture is clear with README, documentation links, and directory structure, scoring 2. Installation instructions are detailed including pip, source, and uv, scoring 2. Naming stability is good with consistent package and API naming, scoring 2. Examples and FAQ: multiple examples and documentation are present, but no FAQ, scoring 2. Known limitations are not explicitly listed in README, scoring 1. License is MIT, scoring 2. Versioning and changelog: version number exists but no changelog, scoring 1. Maintenance responsibility is clear with contributing guidelines and author info, scoring 2.
Evidence shows: output usability is good with visualization tools and examples, scoring 2. Marginal value is good as a lightweight simulator with unique features, scoring 2. Cost-benefit is good with simple installation and usage, scoring 2.
Evidence shows: claim traceability is good with README claims consistent with code and documentation, scoring 2. Cross-source corroboration: there are arXiv paper and community project references, but not independently verified, scoring 1. Fact-inference separation is good with README distinguishing feature descriptions and citations, scoring 2.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- The repository provides no permission model or user confirmation mechanism; use with caution as an Agent product.
- Dependencies are not locked, posing supply chain risks; consider using a lock file.
- Known limitations and changelog are not provided; users may encounter unexpected issues.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.12.0 ir-sim-v2.12.0
Release notes excerpt
2.12.0 (2026-10-04) This release adds Contact mode for realistic collision handling, a default Okabe-Ito palette for academic figures, the social force model as a group behavior, and fixes to reactive behaviors, lidar readings, and the environment lifecycle. <p align="center"> <img src="https://raw.githubusercontent.com/IR-SIM/ir-sim-gifs/main/robots_obstacles/push_box_keyboard.gif" width="320" alt="Contact mode: a keyboard-driven robot pushes boxes of different mass."/> …View on GitHub ↗ -
v2.11.0 ir-sim-v2.11.0
Release notes excerpt
2.11.0 (2026-09-01) This release adds headless environments for batch training, compound geometry, internal/external step modes, ROS-style simulation messages, and per-environment object ids and random generators, plus much faster stepping for both lidar scans and multi-robot behaviors. Measured headless on an Apple-silicon Mac against 2.10.2 (median of repeated runs): | Time cost | 2.10.2 | 2.11.0 | Speedup | | --- | ---: | ---: | ---: | | env.step(), 200-beam lidar, one polygon | 2.88 ms | 0.26 ms | 11.1x | | env.step(), 200-beam lidar, 50 polygons | 6.20 ms | 1.51 ms | 4.1x | …View on GitHub ↗ -
v2.10.2 ir-sim-v2.10.2
Release notes excerpt
- Fix: - Apply body-frame circle-center offsets consistently across collision geometry, rendering, convex G/h constraints, and RVO neighbor state, and clamp the HRVO inverse-sine input. Keeps offset and Ackermann circles aligned across representations and prevents math-domain failures. ([#344](https://github.com/hanruihua/ir-sim/pull/344)) - Refactor: …View on GitHub ↗