Make Environment#

Python script and YAML configuration file#

To start the simulation, you need to create an environment. The environment is a container for all the objects in the simulation. It is also responsible for updating the state of the simulation at each time step.

Create your environment with a simple Python script:

import irsim

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

The make function creates an environment from a configuration file. Supported parameters include:

  • world_name (str, optional): Path to the world YAML configuration file

  • projection (str, optional): Projection type (“3d” for 3D environment, None for 2D)

  • display (bool): Whether to display the environment visualization (default: True)

  • save_ani (bool): Whether to save the simulation as an animation (default: False)

  • log_level (str): Logging level for the environment (default: “INFO”)

  • seed (int, optional): Seed for IR-SIM’s project RNG. If provided, random elements produced by IR-SIM become reproducible. If omitted/None, a new unseeded generator is used (non-reproducible). Custom extensions using np.random or Python random should either switch to IR-SIM’s RNG or be seeded separately.

For more details, see the EnvBase class documentation.

Define your world properties in a YAML file (empty_world.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)

The configuration file is a YAML file that specifies the properties of the environment. The empty_world.yaml file is a simple configuration file that creates an empty environment.

Important Parameters Explanation#

World Configuration#

  • world: Main section that defines the simulation environment properties

  • height and width: Specify the size of the simulation world in meters

  • step_time: Controls simulation accuracy and speed (smaller = more accurate, slower)

  • sample_time: Controls rendering frequency (larger = faster simulation, less smooth visualization)

  • offset: Shifts the world coordinate system origin [x, y] in meters

  • control_mode: Determines how the simulation is controlled

    • 'auto': Automatic simulation execution

    • 'keyboard': Manual keyboard control

  • collision_mode: Defines collision detection behavior

    • 'stop': Stop simulation when collision occurs (default)

    • 'unobstructed': Ignore all collisions

    • 'unobstructed_obstacles': Ignore only obstacle collisions

  • obstacle_map: Optional path to a pre-defined obstacle map file

Performance Considerations#

  • Smaller step_time: More accurate physics but slower simulation

  • Larger sample_time: Faster simulation but less smooth visualization

  • World size: Larger worlds require more computational resources

Tip

You can use sample_time to control the rendering frequency and accelerate the simulation speed. The default value of sample_time is the same as step_time.

For more detailed parameter information, see the YAML Configuration reference.

Tip

Automatic Configuration Detection: The default YAML configuration file has the same name as your Python script. For example, if you create a script named test.py, IR-SIM automatically looks for test.yaml in the same directory.

import irsim

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

This feature simplifies development by eliminating the need to specify configuration files explicitly.

Basic Simulation Loop#

After creating an environment, you’ll typically run a simulation loop:

import irsim

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

# Main simulation loop
for i in range(1000):
    env.step()        # Update simulation state
    env.render(0.05)  # Render with 0.05 second interval (20Hz)
    
    if env.done():    # Check if simulation should end
        break

env.end()  # Clean up resources

Core Methods Explained#

  • env.step(): Advances the simulation by one time step

  • env.render(interval): Updates the visualization with specified time interval between frames

  • env.done(): Returns True if simulation completion conditions are met

  • env.end(): Properly closes the environment and releases resources

Tip

Update order

The environment advances all objects first, then updates all sensors. This two-phase update ensures sensors read the latest world state consistently. If you step objects manually, either pass sensor_step=True to ObjectBase.step(...) or call obj.sensor_step() after updating states.

Environment Control and Status#

Status Management#

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

Configure Environment Title#

By default, the simulation time and status are shown in the environment title. You can customize this behavior by setting the show_title and customizing the title by env.set_title().

import irsim

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

# Set custom title
env.set_title("Multi-Robot Navigation Simulation")

# Update title dynamically
for i in range(100):
    env.step()
    
    # Update title every 10 steps
    if i % 10 == 0:
        env.set_title(f"Simulation Step: {i}")
    
    env.render(0.05)

env.end()

world:
  height: 20
  width: 20
  control_mode: 'auto'
  plot:
    show_title: true    # Show title with time and status
    show_axis: true     # Optional: show axis labels