Concepts

This page explains the mental model behind IR-SIM — how the pieces fit together and why the API looks the way it does. Read it once; the User Guide then shows how to do specific tasks, and the Configuration reference documents every key.

The big picture

A scene in IR-SIM is a World plus a set of Objects (robots and obstacles). Objects can carry sensors and be driven by behaviors. You describe the whole scene declaratively in YAML, create it with irsim.make(), and advance it one time step at a time.

            irsim.make("scene.yaml")
                       │
                       ▼
   ┌─────────────────────────────────────────┐
   │            Environment (EnvBase)         │
   │  ┌─────────┐   ┌──────────────────────┐  │
   │  │  World  │   │  Objects              │  │
   │  │ size    │   │   robots ── behavior  │  │
   │  │ time    │   │          └─ sensors   │  │
   │  │ map     │   │   obstacles           │  │
   │  │ collide │   │                       │  │
   │  └─────────┘   └──────────────────────┘  │
   └─────────────────────────────────────────┘
        step() → render() → done() → end()

The environment

The environment (EnvBase) is the object you interact with. It owns the world and every object, and it exposes the simulation lifecycle:

• make() — parse the YAML scenario and build the world and objects.

• step() — advance every object by one time step: apply each object’s behavior (or an external command), integrate its kinematics, then refresh sensors and collision state.

• render() — draw the current state with Matplotlib.

• done() — report whether a terminal condition has been reached (e.g. all robots arrived, or a collision).

• reset() / reload() — restore objects to their initial states, or rebuild the scene from YAML.

• end() — close the window and release resources (and write the animation if save_ani=True).

This step → render → done loop is the heart of every IR-SIM program.

The world

The World holds the global state that objects live in: the size (width, height), the clock (step_time for physics, sample_time for rendering), the coordinate frame (offset), an optional obstacle map (an occupancy grid), and the collision detector. Collision checking uses Shapely geometry with a spatial index, so it scales to many objects.

Objects: robots and obstacles

Everything placed in the scene is an object. Robots and obstacles share the same machinery — the difference is mostly their role and whether they are actively controlled. Each object has:

• State — its pose, represented as a column vector [x, y, theta] (some kinematics add dimensions). This is what step() integrates and what sensors and collisions are computed from.

• Kinematics — how a velocity command turns into motion: diff (differential drive), omni (omnidirectional), omni_angular, or acker (Ackermann / car-like). An object with no kinematics is static.

• Shape — circle, rectangle, polygon, or linestring, used for both collision and drawing.

• Goal — an optional target pose; arrival is detected within a distance threshold.

Behaviors: deciding what to do

A behavior maps an object’s state (and, for reactive ones, its neighbours) to a velocity command on every step. The built-ins are dash (head straight to the goal), rvo (reciprocal velocity obstacles), and sfm (social force model), plus the group behavior orca (optimal reciprocal collision avoidance). You don’t have to use a behavior at all — you can drive an object yourself by passing a command to env.step(action), or register your own behavior.

Sensors: perceiving the world

Sensors are attached to objects and produce measurements from the world each step: a 2D LiDAR, a 2D FMCW LiDAR (range and per-beam radial velocity), and a field-of-view detector. Sensors are refreshed after objects move, so a reading always reflects the latest world state.

From YAML to a running scene

IR-SIM is declarative. The world, robot, and obstacle blocks in your YAML are turned into World and object instances by an internal factory — which is why you rarely write imperative setup code. You describe the scene and IR-SIM builds it, so the same scenario file can be shared, version-controlled, and reused across experiments. The Configuration reference documents every available key.

Where to go next

• Getting Started — install IR-SIM and run your first scene.

• User Guide — task-focused how-to guides.

• Configuration — the full YAML schema.

• API Reference — classes and methods.