Simulation

The user interacts with the simulated fly via the Simulation class, which implements the Gym Env API. Additionally, we have provided a SingleFlySimulation class — a shorthand wrapper for simulations with only one fly.

class flygym.Simulation(flies: Iterable[Fly] | Fly, cameras: Iterable[Camera] | Camera | None, arena: BaseArena = None, timestep: float = 0.0001, gravity: tuple[float, float, float] = (0.0, 0.0, -9.81e3))

Bases: Env

A multi-fly simulation environment using MuJoCo as the physics engine.

Parameters:
fliesIterable[flygym.fly.Fly] or Fly

List of flies in the simulation.

camerasIterable[flygym.camera.Camera] or Camera, optional

List of cameras in the simulation. Defaults to the left camera of the first fly.

arenaflygym.arena.BaseArena, optional

The arena in which the fly is placed. FlatTerrain will be used if not specified.

timestepfloat

Simulation timestep in seconds, by default 0.0001.

gravitytuple[float, float, float]

Gravity in (x, y, z) axes, by default (0., 0., -9.81e3). Note that the gravity is -9.81 * 1000 due to the scaling of the model.

Attributes:
flieslist[flygym.fly.Fly]

List of flies in the simulation.

cameraslist[flygym.camera.Camera]

List of cameras in the simulation.

arenaflygym.arena.BaseArena

The arena in which the fly is placed.

timestep: float

Simulation timestep in seconds.

gravitytuple[float, float, float]

Gravity in (x, y, z) axes. Note that the gravity is -9.81 * 1000 due to the scaling of the model.

curr_timefloat

The (simulated) time elapsed since the last reset (in seconds).

physics: dm_control.mjcf.Physics

The MuJoCo Physics object built from the arena’s MJCF model with the fly in it.

property action_space
close() → None

Close the simulation, save data, and release any resources.

get_wrapper_attr(name: str) → Any

Gets the attribute name from the environment.

property gravity
has_wrapper_attr(name: str) → bool

Checks if the attribute name exists in the environment.

metadata: dict[str, Any] = {'render_modes': []}
property np_random: Generator

Returns the environment’s internal _np_random that if not set will initialise with a random seed.

Returns:

Instances of np.random.Generator

property np_random_seed: int

Returns the environment’s internal _np_random_seed that if not set will first initialise with a random int as seed.

If np_random_seed was set directly instead of through reset() or set_np_random_through_seed(), the seed will take the value -1.

Returns:

int: the seed of the current np_random or -1, if the seed of the rng is unknown

property observation_space
render(*args, **kwargs)

Compute the render frames as specified by render_mode during the initialization of the environment.

The environment’s metadata render modes (env.metadata[“render_modes”]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved through gymnasium.make which automatically applies a wrapper to collect rendered frames.

Note:

As the render_mode is known during __init__, the objects used to render the environment state should be initialised in __init__.

By convention, if the render_mode is:

  • None (default): no render is computed.

  • “human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during step() and render() doesn’t need to be called. Returns None.

  • “rgb_array”: Return a single frame representing the current state of the environment. A frame is a np.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

  • “ansi”: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

  • “rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper, gymnasium.wrappers.RenderCollection that is automatically applied during gymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped after render() is called or reset().

Note:

Make sure that your class’s metadata "render_modes" key includes the list of supported modes.

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make("CartPole-v1", render_mode="human")

render_mode: str | None = None
reset(*, seed: int | None = None, options: dict | None = None) → tuple[ObsType, dict[str, Any]]

Reset the Simulation.

Parameters:
seedint

Random seed for the simulation. The provided base simulation is deterministic, so this does not have an effect unless extended by the user.

optionsdict

Additional parameter for the simulation. There is none in the provided base simulation, so this does not have an effect unless extended by the user.

Returns:
ObsType

The observation as defined by the simulation environment.

dict[str, Any]

Any additional information that is not part of the observation. This is an empty dictionary by default but the user can override this method to return additional information.

set_slope(slope: float, rot_axis='y')

Set the slope of the simulation environment and modify the camera orientation so that gravity is always pointing down. Changing the gravity vector might be useful during climbing simulations. The change in the camera angle has been extensively tested for the simple cameras (left, right, top, bottom, front, back) but not for the composed ones.

Parameters:
slopefloat

The desired_slope of the environment in degrees.

rot_axisstr, optional

The axis about which the slope is applied, by default “y”.

set_wrapper_attr(name: str, value: Any)

Sets the attribute name on the environment with value.

spec: EnvSpec | None = None
step(action: ObsType) → tuple[ObsType, float, bool, bool, dict[str, Any]]

Step the simulation.

Parameters:
actionObsType

Action dictionary as defined by the simulation environment’s action space.

Returns:
ObsType

The observation as defined by the simulation environment.

float

The reward as defined by the simulation environment.

bool

Whether the episode has terminated due to factors that are defined within the Markov Decision Process (e.g. task completion/failure, etc.).

bool

Whether the episode has terminated due to factors beyond the Markov Decision Process (e.g. time limit, etc.).

dict[str, Any]

Any additional information that is not part of the observation. This is an empty dictionary by default (except when vision is enabled; in this case a “vision_updated” boolean variable indicates whether the visual input to the fly was refreshed at this step) but the user can override this method to return additional information.

property unwrapped: Env[ObsType, ActType]

Returns the base non-wrapped environment.

Returns:

Env: The base non-wrapped gymnasium.Env instance

class flygym.SingleFlySimulation(fly: Fly, cameras: Camera | Iterable[Camera] | None = None, arena: BaseArena = None, timestep: float = 0.0001, gravity: tuple[float, float, float] = (0.0, 0.0, -9.81e3))

Bases: Simulation

A single fly simulation environment using MuJoCo as the physics engine.

This class is a wrapper around the Simulation class with a single fly. It is provided for convenience, so that the action and observation spaces do not have to be keyed by the fly’s name.

Parameters:
flyFly

The fly in the simulation.

camerasIterable[Fly] or Camera, optional

List of cameras in the simulation. Defaults to the left camera of the first fly.

arenaflygym.arena.BaseArena, optional

The arena in which the fly is placed. FlatTerrain will be used if not specified.

timestepfloat

Simulation timestep in seconds, by default 0.0001.

gravitytuple[float, float, float]

Gravity in (x, y, z) axes, by default (0., 0., -9.81e3). Note that the gravity is -9.81 * 1000 due to the scaling of the model.

Attributes:
flyflygym.fly.Fly

The fly in the simulation.

cameraslist[flygym.camera.Camera]

List of cameras in the simulation.

arenaflygym.arena.BaseArena

The arena in which the fly is placed.

timestep: float

Simulation timestep in seconds.

gravitytuple[float, float, float]

Gravity in (x, y, z) axes. Note that the gravity is -9.81 * 1000 due to the scaling of the model.

curr_timefloat

The (simulated) time elapsed since the last reset (in seconds).

physics: dm_control.mjcf.Physics

The MuJoCo Physics object built from the arena’s MJCF model with the fly in it.

property action_space
close() → None

Close the simulation, save data, and release any resources.

get_observation() → ObsType
get_wrapper_attr(name: str) → Any

Gets the attribute name from the environment.

property gravity
has_wrapper_attr(name: str) → bool

Checks if the attribute name exists in the environment.

metadata: dict[str, Any] = {'render_modes': []}
property np_random: Generator

Returns the environment’s internal _np_random that if not set will initialise with a random seed.

Returns:

Instances of np.random.Generator

property np_random_seed: int

Returns the environment’s internal _np_random_seed that if not set will first initialise with a random int as seed.

If np_random_seed was set directly instead of through reset() or set_np_random_through_seed(), the seed will take the value -1.

Returns:

int: the seed of the current np_random or -1, if the seed of the rng is unknown

property observation_space
render(*args, **kwargs)

Compute the render frames as specified by render_mode during the initialization of the environment.

The environment’s metadata render modes (env.metadata[“render_modes”]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved through gymnasium.make which automatically applies a wrapper to collect rendered frames.

Note:

As the render_mode is known during __init__, the objects used to render the environment state should be initialised in __init__.

By convention, if the render_mode is:

  • None (default): no render is computed.

  • “human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during step() and render() doesn’t need to be called. Returns None.

  • “rgb_array”: Return a single frame representing the current state of the environment. A frame is a np.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

  • “ansi”: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

  • “rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper, gymnasium.wrappers.RenderCollection that is automatically applied during gymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped after render() is called or reset().

Note:

Make sure that your class’s metadata "render_modes" key includes the list of supported modes.

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make("CartPole-v1", render_mode="human")

render_mode: str | None = None
reset(*, seed: int | None = None, options: dict | None = None) → tuple[ObsType, dict[str, Any]]

Reset the simulation environment.

Parameters:
seedint

Random seed for the environment. The provided base simulation is deterministic, so this does not have an effect unless extended by the user.

optionsdict

Additional parameter for the simulation. There is none in the provided base simulation, so this does not have an effect unless extended by the user.

Returns:
ObsType

The observation as defined by the environment.

dict[str, Any]

Any additional information that is not part of the observation. This is an empty dictionary by default but the user can override this method to return additional information.

set_slope(slope: float, rot_axis='y')

Set the slope of the simulation environment and modify the camera orientation so that gravity is always pointing down. Changing the gravity vector might be useful during climbing simulations. The change in the camera angle has been extensively tested for the simple cameras (left, right, top, bottom, front, back) but not for the composed ones.

Parameters:
slopefloat

The desired_slope of the environment in degrees.

rot_axisstr, optional

The axis about which the slope is applied, by default “y”.

set_wrapper_attr(name: str, value: Any)

Sets the attribute name on the environment with value.

spec: EnvSpec | None = None
step(action: ObsType) → tuple[ObsType, float, bool, bool, dict[str, Any]]

Step the simulation environment.

Parameters:
actionObsType

Action dictionary as defined by the environment’s action space.

Returns:
ObsType

The observation as defined by the environment.

float

The reward as defined by the environment.

bool

Whether the episode has terminated due to factors that are defined within the Markov Decision Process (e.g. task completion/failure, etc.).

bool

Whether the episode has terminated due to factors beyond the Markov Decision Process (e.g. time limit, etc.).

dict[str, Any]

Any additional information that is not part of the observation. This is an empty dictionary by default (except when vision is enabled; in this case a “vision_updated” boolean variable indicates whether the visual input to the fly was refreshed at this step) but the user can override this method to return additional information.

property unwrapped: Env[ObsType, ActType]

Returns the base non-wrapped environment.

Returns:

Env: The base non-wrapped gymnasium.Env instance