### Install IR-SIM from Source (Standard)

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install IR-SIM from the local source code. This is a standard installation process.

```bash
pip install .
```

--------------------------------

### Install IR-SIM

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Install IR-SIM from PyPI. Python 3.10 or higher is required. Use `[all]` for full support.

```bash
pip install ir-sim
# With keyboard control support and all extras:
pip install ir-sim[all]
```

--------------------------------

### Install IR-SIM with pip

Source: https://github.com/hanruihua/ir-sim/blob/main/README.md

Install the IR-SIM package using pip. The `[all]` extra installs keyboard control and other optional features.

```bash
pip install ir-sim

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

--------------------------------

### Install cvxpy for QP Solving

Source: https://github.com/hanruihua/ir-sim/blob/main/usage/21cbf_world/README.md

Install the cvxpy library, which is required for solving the Quadratic Programs used in the CBF controllers.

```bash
python -m pip install cvxpy
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/hanruihua/ir-sim/blob/main/CLAUDE.md

Installs pre-commit hooks for the project. This command should be run once.

```bash
pre-commit install
```

--------------------------------

### Install IR-SIM with uv

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install IR-SIM using the uv package manager. This is an alternative to pip for faster installations.

```bash
uv pip install ir-sim
```

--------------------------------

### Basic YAML Configuration Example

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/yaml_config/configuration.md

This example demonstrates a basic YAML configuration for setting up the world, robot, and obstacle parameters. It includes world dimensions, step and sample times, collision modes, robot kinematics, shape, state, goal, and behavior, as well as obstacle distribution, shape, and state.

```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 
  collision_mode: 'stop'  # 'stop', 'unobstructed', 'unobstructed_obstacles'
  plot:
    show_title: true
    figure_pixels: [1000, 800]

robot:
  - kinematics: {name: 'diff'}  # omni, diff, acker
    shape: {name: 'circle', radius: 0.2}  # radius
    # shape: {name: 'rectangle', length: 0.5, width: 0.2}  # radius
    state: [1, 1, 0]  
    goal: [9, 9, 0] 
    # acce: [3, .inf]   # acce of [linear, angular]  or [v_x, v_y] or [linear, steer]
    behavior: {name: 'dash'} # move toward to the goal directly 
  
obstacle:
  - number: 10
    distribution: {name: 'random'}
    shape:
      - {name: 'circle', radius: 1.0}  # radius
      - {name: 'rectangle', length: 1.5, width: 1.2}  # radius
    state:
      - [5, 5, 0]  
      - [4, 4, 0]
  
  - shape: {name: 'rectangle', length: 1.5, width: 1.2}  # radius
    state: [6, 5, 1] 

  - shape: {name: 'linestring', vertices: [[5, 5], [4, 0], [1, 6]] }  # vertices
    state: [0, 0, 0] 
    unobstructed: True

```

--------------------------------

### Install All Optional Features with pip

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install IR-SIM along with all optional dependencies and features, including keyboard control and enhanced video support.

```bash
pip install ir-sim[all]
```

--------------------------------

### Install IR-SIM with Keyboard Control

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install the optional keyboard control dependencies for IR-SIM. This requires pip.

```bash
pip install ir-sim[keyboard]
```

--------------------------------

### Install IR-SIM from Source (Editable)

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install IR-SIM in editable mode, allowing changes in the source code to be reflected immediately without reinstallation.

```bash
pip install -e .
```

--------------------------------

### Install IR-SIM from source

Source: https://github.com/hanruihua/ir-sim/blob/main/README.md

Clone the IR-SIM repository and install it in editable mode using pip. This is useful for development or when using the latest unreleased features.

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

--------------------------------

### Sync All Dependency Groups with uv

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install all optional dependency groups (lint, test, docs) for IR-SIM using uv.

```bash
uv sync --all-groups
```

--------------------------------

### Install IR-SIM with uv

Source: https://github.com/hanruihua/ir-sim/blob/main/README.md

Clone the IR-SIM repository and synchronize dependencies using uv. This is an alternative installation method for managing Python projects.

```bash
git clone https://github.com/hanruihua/ir-sim.git
cd ir-sim
uv sync
```

--------------------------------

### Install IR-SIM with pip

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Use this command to install the base IR-SIM package and its core dependencies.

```bash
pip install ir-sim
```

--------------------------------

### Install pynput for Keyboard Control

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_keyboard_Mouse_control.md

Install the `pynput` library to enable global keyboard hooks for robot control. This is the recommended method for keyboard control in IR-SIM.

```bash
pip install pynput
```

--------------------------------

### Run Default CBF World Example

Source: https://github.com/hanruihua/ir-sim/blob/main/usage/21cbf_world/README.md

Execute the default scene using the distance-based CBF controller.

```bash
python usage/21cbf_world/cbf_world.py
```

--------------------------------

### Run Collision-Cone CBF World Example

Source: https://github.com/hanruihua/ir-sim/blob/main/usage/21cbf_world/README.md

Execute the scene using the collision-cone CBF (C3BF) controller.

```bash
python usage/21cbf_world/c3bf_world.py
```

--------------------------------

### Install and Run Ruff for Code Linting

Source: https://github.com/hanruihua/ir-sim/blob/main/CONTRIBUTING.md

Install Ruff and run it to check Python code style and linting. Ensure code adheres to project standards before submitting.

```bash
pip install ruff
ruff check
```

--------------------------------

### Install pyrvo Library for ORCA

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_behavior.md

This command installs the 'pyrvo' library, which is a Python binding for the ORCA C++ algorithm, necessary for using group behavior.

```bash
pip install pyrvo
```

--------------------------------

### Basic Keyboard Control Setup

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_keyboard_Mouse_control.md

To enable keyboard control, set the `control_mode` parameter to 'keyboard' in the `world` section of your configuration. This script demonstrates a basic simulation loop where keyboard input is used for control.

```python
import irsim

env = irsim.make()

for i in range(1000):

    env.step()
    env.render(0.05)

    if env.done():
        break

env.end()
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Set up a new conda environment named 'irsim_env' and activate it before installing IR-SIM.

```bash
conda create --name irsim_env
conda activate irsim_env
```

--------------------------------

### Basic ORCA Configuration Script

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_behavior.md

This Python script demonstrates the basic setup and execution of a simulation using the IR-SIM environment with ORCA behavior enabled.

```python
import irsim

env = irsim.make()

while True:
    env.step()
    env.render()

    if env.done():
        break

env.end()
```

--------------------------------

### Sync Documentation Dependencies with uv

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install the dependencies required for building documentation using uv. This command syncs the 'docs' group defined in pyproject.toml.

```bash
uv sync --group docs
```

--------------------------------

### Configure Keyboard Control

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/yaml_config/configuration.md

Example of enabling keyboard control and setting its parameters in the GUI configuration. This includes specifying the backend, global hook, and velocity limits.

```yaml
world:
  control_mode: 'keyboard'

gui:
  keyboard:
    backend: 'pynput'     # or 'mpl'
    global_hook: true     # if your want to capture keys globally. Default is False.
    key_id: 0
    key_lv_max: 3.0
    key_ang_max: 1.0
```

--------------------------------

### Configure Mouse Control

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/yaml_config/configuration.md

Example of configuring mouse control settings in the GUI. This snippet shows how to set the zoom factor for mouse-based zooming.

```yaml
gui:
  mouse:
    zoom_factor: 1.1
```

--------------------------------

### Sync Testing Dependencies with uv

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install the dependencies required for running tests using uv. This command syncs the 'test' group defined in pyproject.toml.

```bash
uv sync --group test
```

--------------------------------

### Sync Linting Dependencies with uv

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Install the dependencies required for linting using uv. This command syncs the 'lint' group defined in pyproject.toml.

```bash
uv sync --group lint
```

--------------------------------

### YAML Configuration for irsim World

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/save_animation.md

Configure world dimensions, step and sample times, and plot settings in YAML. This example sets up a 10x10 world with a differential drive robot.

```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 
  plot:
    show_title: False

robot:
  kinematics: {name: 'diff'}  # omni, diff, acker
  shape: {name: 'circle', radius: 0.2}  # radius
  # shape: {name: 'rectangle', length: 0.3, width: 1.0} 
  state: [1, 1, 0]  
  goal: [9, 9, 0] 
  # acce: [3, .inf]   # acce of [linear, angular]  or [v_x, v_y] or [linear, steer]
  behavior: {name: 'dash'} # move toward to the goal directly 
  color: 'g'
  plot:
    show_trajectory: True
    show_trail: True
  # description: 'diff_robot0.png'

  sensors:
      - name: 'lidar2d'
        range_min: 0
        range_max: 5
        angle_range: 3.14 #  4.7123
        number: 200
        noise: False
        std: 0.2
        angle_std: 0.2
        alpha: 0.3
```

--------------------------------

### Configure Robot Behavior with YAML

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_behavior.md

Define robot properties and its behavior using a YAML configuration file. This example shows how to set a 'smooth_dash' behavior with custom smoothing.

```yaml
world:
  height: 10
  width: 10

robot:
  - kinematics: {name: 'diff'}
    shape: {name: 'circle', radius: 0.2}
    state: [2, 2, 0]
    goal: [8, 8]
    behavior:
      name: 'smooth_dash'
      smoothing: 0.5  # Custom smoothing parameter
    vel_max: [2, 2]
    vel_min: [-2, -2]
```

--------------------------------

### Auto-detect YAML and Create Environment with irsim.make

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Automatically detect and load a YAML configuration file based on the running script's name. For example, 'experiment.py' will load 'experiment.yaml'.

```python
import irsim

# Auto-detect YAML from script name (script is named "experiment.py" → loads "experiment.yaml")
env = irsim.make()
```

--------------------------------

### Robot World YAML Configuration

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Example YAML configuration for a robot world, defining world dimensions, step time, collision mode, robot kinematics, shape, initial state, goal, behavior, and color.

```yaml
world:
  height: 10
  width: 10
  step_time: 0.1
  sample_time: 0.1
  offset: [0, 0]
  collision_mode: 'stop'   # 'stop' | 'unobstructed' | 'unobstructed_obstacles'

robot:
  kinematics: {name: 'diff'}   # 'diff' | 'omni' | 'omni_angular' | 'acker'
  shape: {name: 'circle', radius: 0.2}
  state: [1, 1, 0]
  goal: [9, 9, 0]
  behavior: {name: 'dash'}
  color: 'g'
```

--------------------------------

### Define World Properties in YAML

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/make_environment.md

Configure the simulation environment's properties, such as dimensions, time steps, and collision behavior, using a YAML file. This example shows basic world settings.

```yaml
world:
  height: 10  # the height of the world (meters)
  width: 10   # the width of the world (meters)
  step_time: 0.1  # simulation time step (seconds) - 10Hz
  sample_time: 0.1  # rendering frequency (seconds) - 10Hz
  offset: [0, 0] # the offset of the world origin [x, y]
  control_mode: 'auto' # control mode: 'auto', 'keyboard'
  collision_mode: 'stop' # collision behavior: 'stop', 'unobstructed', 'unobstructed_obstacles'
  obstacle_map: null # path to obstacle map file (optional)
```

--------------------------------

### Basic Environment Step and Render (Python)

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_grid_map.md

This Python snippet demonstrates how to initialize, step, render, and end an environment. It's a fundamental loop for interacting with the simulation.

```python
import irsim

env = irsim.make()

for i in range(1000):
    env.step()
    env.render(0.05)
    if env.done():
        break
env.end()
```

--------------------------------

### Build Documentation

Source: https://github.com/hanruihua/ir-sim/blob/main/CLAUDE.md

Builds the project documentation using Make. Requires changing into the docs directory first.

```bash
cd docs && make html
```

--------------------------------

### Build Documentation Locally with Sphinx

Source: https://github.com/hanruihua/ir-sim/blob/main/CONTRIBUTING.md

Navigate to the docs directory and run 'make html' to build the project documentation locally. This allows previewing changes before deployment.

```bash
cd docs
make html
```

--------------------------------

### Control Simulation State and Loop

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/make_environment.md

Demonstrates how to initialize the environment, check its status and time, pause/resume simulation, and run a basic simulation loop with conditional state changes. Ensure to call env.end() to release resources.

```python
import irsim

env = irsim.make('config.yaml')

# Check current status
print(f"Current status: {env.status}")
print(f"Current time: {env.time}")

# Control simulation state
env.pause()    # Pause the simulation
env.resume()   # Resume the simulation

# Simulation loop with status checking
for i in range(50):
    env.step()
    env.render(0.05)

    if i < 10:
        env.pause()
    elif i > 20 and i < 30:
        env.resume()
    
    if env.status == "Pause":
        print("Environment is paused")
    
    if env.done():
        print("Simulation completed successfully")

env.end()
```

--------------------------------

### Install Pre-commit Hook for Automatic Checks

Source: https://github.com/hanruihua/ir-sim/blob/main/CONTRIBUTING.md

Install the pre-commit hook to automatically run checks on each commit. This helps maintain code quality and consistency.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Save Animation as Video

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/save_animation.md

To save the animation as a video file (e.g., MP4), set the `suffix` parameter to the desired video format (e.g., '.mp4') in the `env.end()` function. Ensure that `ffmpeg` is installed on your system (`pip install imageio[ffmpeg]`).

```python
env = irsim.make(save_ani=True)

for i in range(300):

    env.step()
    env.render(0.05)

    if env.done():
        break

env.end(ending_time=3, suffix='.mp4')
```

--------------------------------

### Create 3D Simulation Environment with irsim.make

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Create a 3D simulation environment by specifying a YAML configuration file and setting the `projection` parameter to '3d'.

```python
import irsim

# 3-D projection
env = irsim.make("robot_world_3d.yaml", projection="3d")
```

--------------------------------

### Get Obstacle Info List

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Retrieves a list containing information for all obstacles in the simulation.

```APIDOC
## env.get_obstacle_info_list

### Description
Retrieves a list containing information for all obstacles in the simulation.

### Method
`env.get_obstacle_info_list() -> list[object]`

### Returns
- **list[object]** - A list of objects, where each object contains information about an obstacle.
```

--------------------------------

### Environment Control and Status Management

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/make_environment.md

Demonstrates how to initialize the environment, check its current status and time, and control its state using pause, resume, and step operations within a simulation loop.

```APIDOC
## Environment Control and Status

### Status Management

```python
import irsim

env = irsim.make('config.yaml')

# Check current status
print(f"Current status: {env.status}")
print(f"Current time: {env.time}")

# Control simulation state
env.pause()    # Pause the simulation
env.resume()   # Resume the simulation

# Simulation loop with status checking
for i in range(50):
    env.step()
    env.render(0.05)

    if i < 10:
        env.pause()
    elif i > 20 and i < 30:
        env.resume()
    
    if env.status == "Pause":
        print("Environment is paused")
    
    if env.done():
        print("Simulation completed successfully")

env.end()
```

### Available Status Values

- **`"Running"`**: The environment is running in auto control mode
- **`"Running (keyboard)"`**: The environment is running in keyboard control mode
- **`"Pause"`**: Simulation is paused
- **`"Done"`**: Simulation has completed
- **`"Arrived"`**: All robots have arrived at their goals
- **`"Collision"`**: A collision has occurred
- **`"Pause (Debugging)"`**: Debugging mode (when `F5` key is pressed)
- **`"Reset"`**: The environment is reset
- **`"Reload"`**: The environment is reloaded
- **`"Save Figure"`**: The figure is saved
- **`"Quit"`**: The environment is quit
```

--------------------------------

### Get Robot State

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Retrieves the current state of the robot, including its position (x, y) and orientation (theta).

```APIDOC
## env.get_robot_state

### Description
Gets the current state of the robot in the simulation.

### Method
`env.get_robot_state() -> np.ndarray`

### Returns
- **np.ndarray** - A numpy array of shape (3,1) representing the robot's state [x, y, theta].
```

--------------------------------

### Run Robot Simulation in Python

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/quick_start.md

Initialize the environment with a configuration file, run the simulation for a set number of steps, and then close the environment.

```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
```

--------------------------------

### Path Planning with Multiple Algorithms

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Demonstrates path planning using various algorithms: A*, JPS, RRT, and RRT*. It first obtains the environment map and robot information, then initializes a planner and computes a path to the goal. The resulting trajectory can be visualized.

```python
import irsim
from irsim.lib.path_planners import AStarPlanner, JPSPlanner, RRTPlanner, RRTStarPlanner

env = irsim.make("path_planning.yaml", save_ani=False)

# Build occupancy map from the world (resolution in meters/cell)
env_map = env.get_map(resolution=0.2)

robot_state = env.get_robot_state()          # (3,1) [x, y, theta]
robot_info  = env.get_robot_info()
goal_xy     = robot_info.goal[:2, 0].tolist()

# --- A* ---
planner = AStarPlanner(env_map)
path = planner.planning(robot_state, goal_xy, show_animation=True)

# --- JPS (faster, same optimal path) ---
# planner = JPSPlanner(env_map)
# path = planner.planning(robot_state, goal_xy)

# --- RRT ---
# planner = RRTPlanner(env_map)
# path = planner.planning(robot_state, goal_xy, max_iter=2000)

# --- RRT* ---
# planner = RRTStarPlanner(env_map)
# path = planner.planning(robot_state, goal_xy, max_iter=5000)

if path is not None:
    env.draw_trajectory(path, traj_type="r-")

env.end(5)
```

--------------------------------

### Get Group by Name

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Retrieves a list of objects belonging to a specific group, identified by the group's name.

```APIDOC
## env.get_group_by_name

### Description
Retrieves a list of objects that belong to a specified group.

### Method
`env.get_group_by_name(group_name: str) -> list[object]`

### Parameters
- **group_name** (str) - The name of the group.

### Returns
- **list[object]** - A list of objects belonging to the specified group.
```

--------------------------------

### Get LiDAR Scan

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Obtains the LiDAR scan data for a specified robot, including range measurements and endpoint coordinates.

```APIDOC
## env.get_lidar_scan

### Description
Retrieves the LiDAR scan data for a given robot.

### Method
`env.get_lidar_scan(id: int) -> dict`

### Parameters
- **id** (int) - The ID of the robot for which to get the LiDAR scan.

### Returns
- **dict** - A dictionary containing scan data, with keys like 'ranges' and 'points'.
```

--------------------------------

### Create 2D Simulation Environment with irsim.make

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Create a 2D simulation environment using `irsim.make` by specifying a YAML configuration file. This function returns an `EnvBase` instance.

```python
import irsim

# Minimal 2-D environment from YAML
env = irsim.make("robot_world.yaml")
```

--------------------------------

### Get Robot Info

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Retrieves detailed information about a specific robot, such as its goal. Can also retrieve a list of all robot information.

```APIDOC
## env.get_robot_info

### Description
Retrieves detailed information for a specific robot identified by its ID.

### Method
`env.get_robot_info(id: int) -> object`

### Parameters
- **id** (int) - The ID of the robot.

### Returns
- **object** - An object containing robot information, including a 'goal' attribute.
```

```APIDOC
## env.get_robot_info_list

### Description
Retrieves a list containing information for all robots in the simulation.

### Method
`env.get_robot_info_list() -> list[object]`

### Returns
- **list[object]** - A list of objects, where each object contains information about a robot.
```

--------------------------------

### Get Object by Name or ID

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Finds and returns a specific object (robot or obstacle) in the simulation using its name or unique ID.

```APIDOC
## env.get_object_by_name

### Description
Retrieves an object from the simulation using its name.

### Method
`env.get_object_by_name(name: str) -> object`

### Parameters
- **name** (str) - The name of the object to retrieve.

### Returns
- **object** - The found object.
```

```APIDOC
## env.get_object_by_id

### Description
Retrieves an object from the simulation using its unique ID.

### Method
`env.get_object_by_id(id: int) -> object`

### Parameters
- **id** (int) - The ID of the object to retrieve.

### Returns
- **object** - The found object.
```

--------------------------------

### Create Environment from YAML

Source: https://github.com/hanruihua/ir-sim/blob/main/CLAUDE.md

Initializes the IR-SIM environment by loading configuration from a YAML file.

```python
irsim.make('config.yaml')
```

--------------------------------

### Create Headless RL Training Environment with irsim.make

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Create a headless 2D simulation environment for RL training. Set `display=False`, provide a fixed `seed`, and specify `log_level`.

```python
import irsim

# Headless environment for RL training, fixed RNG seed
env = irsim.make("training.yaml", display=False, seed=42, log_level="WARNING")
```

--------------------------------

### Initialize and Run Robot Simulation

Source: https://github.com/hanruihua/ir-sim/blob/main/README.md

Initializes the simulation environment using a YAML configuration file, runs the simulation for a specified number of steps, and updates/renders the environment at each step. The simulation terminates if the environment is done.

```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
```

--------------------------------

### Configure Multiple Robots and Obstacles

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_robots_obstacles.md

This YAML configuration demonstrates setting up multiple robots and obstacles with specified distributions, shapes, states, and colors. Use '-' to define each new robot or obstacle in the list.

```yaml
world:
  height: 10  # the height of the world
  width: 10   # the width of the world

robot:
  - number: 2
    distribution: {name: 'manual'}
    kinematics: {name: 'diff'}
    shape: 
      - {name: 'circle', radius: 0.2}  # radius
    state: 
      - [1, 1, 0]  
      - [2, 1, 0]
    goal:
      - [9, 9, 0] 
      - [9, 2, 0]
    color: 
      - 'royalblue'
      - 'red'
  
  - number: 4
    distribution: {name: 'random'}
    kinematics: {name: 'diff'}
    shape: 
      - {name: 'circle', radius: 0.2}  # radius
    color: 
      - 'pink'


obstacle:
  - number: 4
    distribution: {name: 'manual'}
    state: [[4, 8], [1, 3], [1, 0], [5, 2]]
    shape:
      - {name: 'circle', radius: 0.2}  # radius
      - {name: 'circle', radius: 0.1}  # radius
    color: 'k'
```

--------------------------------

### Class-based Custom Behavior Implementation

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_behavior.md

Implements a stateful custom behavior using the '@register_behavior_class' decorator. This example provides smooth velocity control by maintaining previous velocity.

```python
# custom_behavior_methods.py
from typing import Any
import numpy as np
from irsim.lib.behavior.behavior_registry import register_behavior_class


@register_behavior_class("diff", "smooth_dash")
def init_smooth_dash(object_info, **kwargs):
    """Registered initializer returning a class-based handler."""
    return SmoothDashBehavior(object_info, **kwargs)


class SmoothDashBehavior:
    """
    Class-based smooth dash behavior with velocity smoothing.
    Maintains previous velocity for smooth acceleration.
    """

    def __init__(self, object_info, smoothing: float = 0.3, **kwargs):
        """
        Initialize smooth dash behavior.

        Args:
            object_info: Object information from ObjectBase
            smoothing: Smoothing factor (0-1), higher = smoother
        """
        self._smoothing = smoothing
        self._prev_vel = np.zeros((2, 1))
        self._object_info = object_info

    def __call__(
        self,
        ego_object,
        external_objects: list,
        **kwargs: Any,
    ) -> np.ndarray:
        """
        Generate smoothed velocity toward goal.

        Args:
            ego_object: The controlled object
            external_objects: Other objects in environment
            **kwargs: Additional parameters

        Returns:
            Smoothed velocity array (2x1)
        """
        if ego_object.goal is None:
            return np.zeros((2, 1))

        # Calculate desired velocity (simple dash)
        state = ego_object.state
        goal = ego_object.goal
        _, max_vel = ego_object.get_vel_range()

        diff = goal[:2, 0] - state[:2, 0]
        distance = np.linalg.norm(diff)

        if distance < ego_object.goal_threshold:
            target_vel = np.zeros((2, 1))
        else:
            # Convert to diff drive velocities
            angle_to_goal = np.arctan2(diff[1], diff[0])
            diff_angle = angle_to_goal - state[2, 0]
            diff_angle = np.arctan2(np.sin(diff_angle), np.cos(diff_angle))

            linear = max_vel[0, 0] * np.cos(diff_angle)
            angular = max_vel[1, 0] * np.sign(diff_angle) if abs(diff_angle) > 0.1 else 0

            target_vel = np.array([[linear], [angular]])

        # Apply smoothing (exponential moving average)
        smoothed_vel = (
            self._smoothing * self._prev_vel +
            (1 - self._smoothing) * target_vel
        )
        self._prev_vel = smoothed_vel

        return smoothed_vel
```

--------------------------------

### Multiple Environments (Parallel / RL Training)

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Demonstrates how to create and manage multiple isolated simulation environments in parallel, suitable for reinforcement learning training.

```APIDOC
## irsim.make (multiple environments)

### Description
Creates multiple, independent simulation environments. Each environment can be configured separately and run in parallel.

### Method
`envs = [irsim.make(yaml_path: str, display: bool = True, seed: int | None = None) for _ in range(num_envs)]`

### Parameters
- **yaml_path** (str) - Path to the world configuration YAML file.
- **display** (bool) - Whether to enable visualization for the environment. Defaults to True.
- **seed** (int | None) - Optional seed for reproducibility of the environment's random elements.
```

--------------------------------

### Basic 2D LiDAR Configuration

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_sensor.md

Configure a 2D LiDAR sensor with basic parameters like range, angle, and number of beams. This setup is for a standard robot simulation.

```python
import irsim

env = irsim.make()   

for i in range(1000):

    env.step()
    env.render(0.05)

    if env.done():
        break

env.end()
```

```yaml
world:
  height: 10  
  width: 10   

robot:
  - kinematics: {name: 'diff'}  # omni, diff, acker
    shape: {name: 'circle', radius: 0.2}  # radius
    goal: [9, 9, 0]

    sensors:
      - name: 'lidar2d'
        range_min: 0
        range_max: 5
        angle_range: 3.14 
        number: 200
        noise: False
        alpha: 0.3
      
obstacle:
  - shape: {name: 'circle', radius: 1.0}  # radius
    state: [5, 5, 0]  
  
  - shape: {name: 'rectangle', length: 1.5, width: 1.2}  # length, width
    state: [6, 5, 1] 
  
  - shape: {name: 'linestring', vertices: [[10, 5], [4, 0], [6, 7]]}  # vertices
    state: [0, 0, 0] 
```

--------------------------------

### Navigate to IR-SIM Directory

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/get_started/install.rst

Change the current directory to the root of the cloned IR-SIM repository.

```bash
cd ir-sim
```

--------------------------------

### YAML Configuration for Custom Map Generator

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_grid_map.md

Example YAML configuration for using a custom map generator, such as a maze generator. Requires 'name' and 'resolution', with other parameters specific to the generator.

```yaml
world:
  width: 20
  height: 20
  obstacle_map:
    name: maze
    resolution: 0.1
    seed: 42
    density: 0.3
```

--------------------------------

### Run Simulation with Dynamic Random Environment

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/configure_dynamic_random_env.md

This Python script demonstrates how to initialize the environment, step through episodes, render the simulation, and end the environment. It's used to run simulations within the dynamic random environment.

```python
import irsim

env = irsim.make()   

for i in range(1000):

    env.step()
    env.render(0.05)

    if env.done():
        break

env.end()
```

--------------------------------

### Automatic Configuration Detection

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/usage/make_environment.md

IR-SIM automatically detects the YAML configuration file if it shares the same name as the Python script. This simplifies setup by removing the need to explicitly pass the filename to `irsim.make()`.

```python
import irsim

# Automatically uses 'test.yaml' if this file is 'test.py'
env = irsim.make()
```

--------------------------------

### Control Environment: Pause, Resume, Reset, Reload

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Demonstrates controlling the simulation environment, including pausing and resuming steps, resetting the environment to initial conditions, and hot-reloading the configuration YAML file during runtime.

```python
import irsim

env = irsim.make("config.yaml")

for i in range(200):
    env.step()
    env.render(0.05)

    if i == 50:
        env.pause()   # stop stepping; step() becomes a no-op

    if i == 80:
        env.resume()  # continue

    if env.done():
        env.reset()   # restore initial positions

    # Hot-reload YAML from disk (e.g. after editing the file)
    if i == 150:
        env.reload()               # same YAML
        # env.reload("new_world.yaml")  # different YAML

    print(f"Step {i}: status={env.status}")

env.end()
```

--------------------------------

### ORCA Multi-Agent Simulation Configuration

Source: https://context7.com/hanruihua/ir-sim/llms.txt

YAML configuration for a 200-agent ORCA simulation. Sets world parameters, robot properties, and ORCA group behavior settings. Requires `pip install pyrvo`.

```yaml
# 200-agent ORCA simulation
world:
  height: 290
  width: 290
  step_time: 0.1
  sample_time: 0.7
  offset: [-140, -140]

robot:
  - number: 200
    kinematics: {name: 'omni'}
    shape: {name: 'circle', radius: 1.0}
    distribution: {name: 'circle', radius: 140}
    vel_max: [3, 3]
    vel_min: [-3, -3]
    plot:
      show_trajectory: true
      keep_traj_length: 50
    group_behavior:
      name: 'orca'
      neighborDist: 15.0
      maxNeighbors: 10
      timeHorizon: 20.0
      timeHorizonObst: 10.0
      safe_radius: 0.5
      maxSpeed: 2.0
      wander: true
      range_low: [-100, -100, -3.14]
      range_high: [100, 100, 3.14]
```

--------------------------------

### Ackermann Vehicle Configuration

Source: https://github.com/hanruihua/ir-sim/blob/main/docs/source/yaml_config/configuration.md

Configure a simulation with an Ackermann steering vehicle. This example specifies its kinematics, dimensions, initial state, goal, maximum velocities, and behavior, along with plotting options for its trajectory.

```yaml
robot:  
  - kinematics: {name: 'acker'}  
    shape: {name: 'rectangle', length: 4.6, width: 1.6, wheelbase: 3}
    state: [1, 1, 0, 0]
    goal: [40, 40, 0]
    vel_max: [4, 1]
    behavior: {name: 'dash'}
    plot:
      show_trajectory: True
```

--------------------------------

### Get Robot State and Information

Source: https://context7.com/hanruihua/ir-sim/llms.txt

Retrieves various environment states, including robot position, goal, LiDAR scans, and obstacle information. Objects can be queried by name or ID, and groups can be accessed.

```python
import irsim

env = irsim.make("robot_world.yaml")
env.step()

# Robot state [x, y, theta]
state = env.get_robot_state()          # np.ndarray shape (3,1)
print("Robot state:", state.flatten())

# Robot info object
info = env.get_robot_info(id=0)
print("Goal:", info.goal.flatten())

# List of all robot info
robot_infos = env.get_robot_info_list()

# LiDAR scan for robot 0
scan = env.get_lidar_scan(id=0)
# scan['ranges'] → array of distances
# scan['points'] → (2, N) array of endpoint coords

# Obstacle info list
obs_infos = env.get_obstacle_info_list()

# Find objects by name or id
robot_0 = env.get_object_by_name("robot_0")
obj     = env.get_object_by_id(3)

# Group members by group_name attribute
team_a = env.get_group_by_name("team_a")

# Simulation time and step count
print(f"Time: {env.time:.2f}s, Steps: {env.world_param.count}")
print(f"Status: {env.status}")
print(f"Step time: {env.step_time}s")

# Access first robot directly
robot = env.robot
print(f"Robot position: {robot.state[:2, 0]}")
print(f"Arrived: {robot.arrive}, Collision: {robot.collision}")

# All robots / obstacles
for r in env.robot_list:
    print(r.name, r.state.flatten())

for obs in env.obstacle_list:
    print(obs.name, obs.state.flatten())
```