IR-SIM: a YAML-driven 2D robot simulator that starts in a few lines of Python

A scenario in YAML, not a robot in code

IR-SIM is described as an open-source, Python-based, lightweight robot simulator designed for navigation, control, and learning, and the one line summary is more precise: a lightweight, YAML-driven robot simulator.

The YAML point is the design decision that everything else follows from. A scenario is a configuration file, so the geometry of the world, the robots, the obstacles and the goals are data rather than code. The project states the benefit plainly: you can quickly configure and customize scenarios using straightforward YAML files, with no complex coding required.

That is a different bet from the mainstream robotics simulators, which tend to expose the world through a scripting API where you construct objects in Python. IR-SIM inverts that, and the effect on iteration is concrete. Changing a wall position or adding an obstacle becomes a file edit, and a set of experiments across a parameter becomes a loop over a directory of YAML files.

The package description in pyproject.toml makes the audience explicit. IR-SIM provides a simple and user-friendly framework for simulating robots, sensors, and environments, facilitating the development and testing of robotics algorithms with minimal hardware requirements. The overview names academic and educational use and rapid prototyping in custom scenarios as the intended use.

The keywords on the package are navigation, control, learning, robotics, simulation, path planning, multi agent and autonomous driving, and the project classifies itself as Development Status 5, Production/Stable, with classifiers for Python 3.10 through 3.14 and MIT licensing.

The demonstration set, which is really the feature list

The README puts nine demonstrations in a table with links to the source for each, and reading them tells you what the simulator actually supports.

Multi-robot RVO collision avoidance is one, and there is a 200-agent ORCA example that runs through a separate package called pyrvo, also by the same author. An Ackermann robot with 2D LiDAR is another, which means non-differential kinematics are supported and the kinematics are a per-robot choice rather than a global assumption.

The map side has two variants: a plain grid map and an HM3D or MatterPort3D grid map, so a scenario can be generated from an indoor scan dataset. There is fog-of-map exploration, which is a partially observed environment rather than a fully known one, and dynamic random obstacles, which is the case that separates a static planner from a reactive one.

The sensing side includes field-of-view detection, so a sensor sees a cone rather than everything around it. The object side includes rigid-body contact for pushing boxes, and social force model pedestrians, which is a model from crowd dynamics rather than robotics.

That last pair is a signal about the project's scope. A social force model pedestrian is not a robot at all, it is a way of testing whether your planner or your policy behaves sensibly around people. IR-SIM is a 2D world that can hold agents of several kinds, and the demonstrations in the README are the honest catalogue of what that means in practice.

Installing from pip, and the extras that decide your experience

IR-SIM requires Python 3.10 or newer, and the badge row in the README covers 3.10, 3.11, 3.12, 3.13 and 3.14, with a CI workflow that runs the version test matrix.

The ordinary install is one command.

pip install ir-sim

There is an extras variant, and the difference matters more than it looks.

# Optional: keyboard control and all extras
pip install ir-sim[all]

Looking at the optional dependency groups in pyproject.toml, the keyboard extra pulls in pynput, and the all extra is pynput plus imageio with the ffmpeg extra plus pyrvo. So pyrvo, the package behind the 200-agent ORCA demonstration, is an optional dependency rather than a core one, and the keyboard control in one of the demonstrations, pushing boxes, is likewise an extra.

The core dependency list is modest and tells you what the simulator is built on: matplotlib, shapely at 2.1.2 or newer, numpy, pyyaml, imageio, loguru and scipy. Shapely is the geometry library doing the collision work, scipy is there for the numerics, and matplotlib is the renderer.

From source, the project supports both pip and uv.

git clone https://github.com/hanruihua/ir-sim.git
cd ir-sim
pip install -e .

The uv variant uses uv sync instead, and the repository carries a uv.lock file, so the two paths give you a pinned and an editable install respectively.

Matplotlib as the renderer, and what that buys and costs

The visualization claim in the README is a lightweight Matplotlib-based renderer for rapid debugging. That is a real design commitment, not an excuse, and it is worth being explicit about what it means.

What it buys is speed of iteration. A Matplotlib render is a figure you can produce on a laptop with no GPU, no graphics driver configuration and no shader compilation step. The demonstration gifs in the README were produced by the tool itself, which means the whole loop from a YAML edit to a moving picture runs on a normal machine. For a student running a hundred experiments overnight, that is the dominant consideration.

What it costs is realism. There is no 3D, no photorealistic rendering, and no physically accurate lighting or material model. The simulator is 2D, and that is not a limitation of the current build so much as the decision the name and the demonstration set commit to.

The other side of the Matplotlib choice is that it makes the output inspectable. A rendered frame is a figure you can save, plot over, or compare across runs, which matters when you are trying to understand why a planner failed in one configuration and not another. The imageio dependency in the core list, along with the ffmpeg extra, is there to record those frames as video.

The comparison worth drawing is with a full physics simulator. A tool like that gives you contact dynamics, friction, sensor noise models and 3D, and it costs you time to set up, a heavier install, and a slower loop. IR-SIM is the opposite trade, and for algorithm development at the level of a path planner or a control law, the opposite trade is usually the right one.

Collision detection and behaviour policies as the extension points

Two features in the key list define how a scenario is customised. There is support for collision detection and customizable behavior policies for each object.

Collision detection is what makes the world more than a backdrop. With it, a robot's motion is checked against obstacles and other agents, so a planner that cuts a corner through a wall produces a visibly wrong result rather than a plausible one. The presence of shapely in the core dependencies, and the RVO and ORCA demonstrations, suggest the collision model is geometric rather than physical, which is consistent with a 2D simulator that also does rigid-body contact for the pushing boxes example.

The behaviour policies are the second extension point, and they are the one that matters for learning. Each object can carry its own policy, and the demonstrations show what that means in practice: multi-robot RVO collision avoidance where the robots resolve conflicts with reciprocal velocity obstacles, ORCA where 200 agents do so, and the social force model where pedestrians follow crowd dynamics. The policy is per object, so a scenario can mix a differential drive robot with a human and a static obstacle, each behaving according to its own rule.

That per object policy model is what makes the tool usable for reinforcement learning research, which the project lists as a target area. A learning agent needs other agents that react to it, and it needs them to be describable without writing a whole world. The demonstrations directory in the repository, with one folder per example including 11collision_avoidance, 10grid_map, 15fov_world, 08random_obstacle, 19orca_world, 24fog_world, 26push_box_world and 23sfm_world, shows the range.

A project that publishes its paper, its citation and its changelog

The repository contains CITATION.cff and a changelog.md, and the README links an arXiv paper at 2606.08729 along with a Cite IR-SIM badge. That is a small but meaningful signal about how the project sees itself: it is a piece of research output with a citable artefact, not a script someone wrote for their own experiments.

It also means the API is expected to be stable enough to build a paper on. The package classifier says Production/Stable, and the version numbers show a project with a long history: the current release is v2.12.0, preceded by v2.11.0 in September 2026 and v2.10.2 in August 2026. The release cadence on the recent list is roughly monthly.

The repository layout supports a normal development workflow. There is a .pre-commit-config.yaml at the root, an AGENTS.md and a CLAUDE.md, a .readthedocs.yaml for the documentation build, a pyproject.toml, a uv.lock, a tests/ directory, a usage/ directory, a docs/ directory and the irsim/ package itself. The documentation is hosted at ir-sim.readthedocs.io, and the README links the readthedocs page for the stable version.

The licence is MIT, declared in the project metadata and published as a LICENSE file at the root. The topic tags on the repository include reinforcement learning, path planning, multi agent, autonomous driving and robotics simulation, and the README also links a badge ranking the project first among 2D robotics simulators in an external comparison list.

Editorial conclusion

IR-SIM fits a student or researcher who needs a working navigation or control testbed today, who wants the scenario in a YAML file rather than in code, and who needs multi-agent and learning experiments to run without a GPU or a robot. It does not fit a team that needs 3D, physics accurate contact, or realistic sensors, because the renderer is 2D and Matplotlib based. Check three things before you commit. Check that 2D is the right dimension, since the demonstrations are all planar and a 3D problem is the wrong tool here rather than a harder version of the right one. Check the optional dependencies, because the keyboard control and the extra behaviour backends come as extras and pyrvo is needed for the 200 agent ORCA example, which is a separate package by the same author. And check the Python version, since the project requires 3.10 or newer and the CI matrix runs 3.10 through 3.14. The last push was on 2026-10-14, the newest release is v2.12.0 from 2026-10-04, the project publishes an arXiv paper at 2606.08729, and the license is MIT.

Frequently asked questions

Official sources

1. hanruihua/ir-sim on GitHub
2. License: MIT
3. Project website
4. README
5. Releases