Underlying#

safety_gymnasium.bases.underlying#

class safety_gymnasium.bases.underlying.Underlying(config: dict | None = None)#

Base class which is in charge of mujoco and underlying process.

Methods:

Attributes:

  • sim_conf (SimulationConf): Simulation options.

  • placements_conf (PlacementsConf): Placement options.

  • render_conf (RenderConf): Render options.

  • vision_env_conf (VisionEnvConf): Vision observation parameters.

  • floor_conf (FloorConf): Floor options.

  • random_generator (RandomGenerator): Random generator instance.

  • world (World): World, which is in charge of mujoco.

  • world_info (WorldInfo): World information generated according to environment in running.

  • viewer (Union[KeyboardViewer, RenderContextOffscreen]): Viewer for environment.

  • _viewers (dict): Viewers.

  • _geoms (dict): Geoms which are added into current environment.

  • _free_geoms (dict): FreeGeoms which are added into current environment.

  • _mocaps (dict): Mocaps which are added into current environment.

  • agent_name (str): Name of the agent in current environment.

  • observe_vision (bool): Whether to observe vision from the agent.

  • debug (bool): Whether to enable debug mode, which is pre-config during registration.

  • observation_flatten (bool): Whether to flatten the observation.

  • agent (Agent): Agent instance added into current environment.

  • action_noise (float): Magnitude of independent per-component gaussian action noise.

  • model: mjModel.

  • data: mjData.

  • _obstacles (list): All types of object in current environment.

Initialize the engine.

Parameters:

config (dict) – Configuration dictionary, used to pre-config some attributes according to tasks via safety_gymnasium.register().

DataClass#

class safety_gymnasium.bases.underlying.SimulationConf(frameskip_binom_n: int = 10, frameskip_binom_p: float = 1.0)#

Simulation options.

Note

Frameskip is the number of physics simulation steps per environment step and is sampled as a binomial distribution. For deterministic steps, set frameskip_binom_p = 1.0 (always take max frameskip).

Variables:

  • frameskip_binom_n (int) – Number of draws trials in binomial distribution (max frameskip).

  • frameskip_binom_p (float) – Probability of trial return (controls distribution).

class safety_gymnasium.bases.underlying.PlacementsConf#

Placement options.

Variables:

  • placements (dict) – Generated during running.

  • extents (list) – Placement limits (min X, min Y, max X, max Y).

  • margin (float) – Additional margin added to keepout when placing objects.

class safety_gymnasium.bases.underlying.RenderConf(labels: bool = False, lidar_markers: bool = True, lidar_radius: float = 0.15, lidar_size: float = 0.025, lidar_offset_init: float = 0.5, lidar_offset_delta: float = 0.06)#

Render options.

Variables:

  • libels (bool) – Whether to render labels.

  • lidar_markers (bool) – Whether to render lidar markers.

  • lidar_radius (float) – Radius of the lidar markers.

  • lidar_size (float) – Size of the lidar markers.

  • lidar_offset_init (float) – Initial offset of the lidar markers.

  • lidar_offset_delta (float) – Delta offset of the lidar markers.

class safety_gymnasium.bases.underlying.VisionEnvConf#

Vision observation parameters.

Variables:

vision_size (tuple) – Size (width, height) of vision observation.

class safety_gymnasium.bases.underlying.FloorConf(type: str = 'mat', size: tuple = (3.5, 3.5, 0.1))#

Floor options.

Variables:

  • type (str) – Type of floor.

  • size (tuple) – Size of floor in environments.

class safety_gymnasium.bases.underlying.WorldInfo(layout: dict | None = None, reset_layout: dict | None = None, world_config_dict: dict | None = None)#

World information generated in running.

Variables:

  • layout (dict) – Layout of the world.

  • reset_layout (dict) – Saved layout of the world after reset.

  • world_config_dict (dict) – World configuration dictionary.

Methods#

safety_gymnasium.bases.underlying.Underlying.__init__(self, config: dict | None = None) → None#

Initialize the engine.

Parameters:

config (dict) – Configuration dictionary, used to pre-config some attributes according to tasks via safety_gymnasium.register().

safety_gymnasium.bases.underlying.Underlying._parse(self, config: dict) → None#

Parse a config dict.

Modify some attributes according to config. So that easily adapt to different environment settings.

Parameters:

config (dict) – Configuration dictionary.

safety_gymnasium.bases.underlying.Underlying._build_agent(self, agent_name: str) → None#

Build the agent in the world.

safety_gymnasium.bases.underlying.Underlying._add_geoms(self, *geoms: Geom) → None#

Register geom type objects into environments and set corresponding attributes.

safety_gymnasium.bases.underlying.Underlying._add_free_geoms(self, *free_geoms: FreeGeom) → None#

Register FreeGeom type objects into environments and set corresponding attributes.

safety_gymnasium.bases.underlying.Underlying._add_mocaps(self, *mocaps: Mocap) → None#

Register mocap type objects into environments and set corresponding attributes.

safety_gymnasium.bases.underlying.Underlying.reset(self) → None#

Reset the environment.

safety_gymnasium.bases.underlying.Underlying._build(self) → None#

Build the mujoco instance of environment from configurations.

safety_gymnasium.bases.underlying.Underlying.simulation_forward(self, action: ndarray) → None#

Take a step in the physics simulation.

Note

  • The step mentioned above is not the same as the step in Mujoco sense.

  • The step here is the step in episode sense.

safety_gymnasium.bases.underlying.Underlying.update_layout(self) → None#

Update layout dictionary with new places of objects from Mujoco instance.

When the objects moves, and if we want to update locations of some objects in environment, then the layout dictionary needs to be updated to make sure that we won’t wrongly change the locations of other objects because we build world according to layout dictionary.

safety_gymnasium.bases.underlying.Underlying._set_goal(self, pos: ndarray, name='goal') → None#

Set position of goal object in Mujoco instance.

Note

This method is used to make sure the position of goal object in Mujoco instance is the same as the position of goal object in layout dictionary or in attributes of task instance.

safety_gymnasium.bases.underlying.Underlying._render_lidar(self, poses: ndarray, color: ndarray, offset: float, group: int) → None#

Render the lidar observation.

safety_gymnasium.bases.underlying.Underlying._render_compass(self, pose: ndarray, color: ndarray, offset: float) → None#

Render a compass observation.

safety_gymnasium.bases.underlying.Underlying._render_area(self, pos: ndarray, size: float, color: ndarray, label: str = '', alpha: float = 0.1) → None#

Render a radial area in the environment.

safety_gymnasium.bases.underlying.Underlying._render_sphere(self, pos: ndarray, size: float, color: ndarray, label: str = '', alpha: float = 0.1) → None#

Render a radial area in the environment.

safety_gymnasium.bases.underlying.Underlying.render(self, width: int, height: int, mode: str, camera_id: int | None = None, camera_name: str | None = None, cost: float | None = None) → None#

Render the environment to somewhere.

Note

The camera_name parameter can be chosen from:

  • human: the camera used for freely moving around and can get input from keyboard real time.

  • vision: the camera used for vision observation, which is fixed in front of the agent’s head.

  • track: The camera used for tracking the agent.

  • fixednear: the camera used for top-down observation.

  • fixedfar: the camera used for top-down observation, but is further than fixednear.

safety_gymnasium.bases.underlying.Underlying._get_viewer(self, mode: str) → safety_gymnasium.utils.keyboard_viewer.KeyboardViewer | gymnasium.envs.mujoco.mujoco_rendering.RenderContextOffscreen#
safety_gymnasium.bases.underlying.Underlying._update_viewer(self, model, data) → None#

update the viewer with new model and data

safety_gymnasium.bases.underlying.Underlying._obs_lidar(self, positions: ndarray, group: int) → ndarray#

Calculate and return a lidar observation. See sub methods for implementation.

safety_gymnasium.bases.underlying.Underlying._obs_compass(self, pos: ndarray) → ndarray#

Return an agent-centric compass observation of a list of positions.

Compass is a normalized (unit-length) egocentric XY vector, from the agent to the object.

This is equivalent to observing the egocentric XY angle to the target, projected into the sin/cos space we use for joints. (See comment on joint observation for why we do this.)

safety_gymnasium.bases.underlying.Underlying._build_placements_dict(self) → dict#

Build a dict of placements. Happens only once.

safety_gymnasium.bases.underlying.Underlying._build_world_config(self, layout: dict) → dict#

Create a world_config from our own config.

Additional Methods#

property Underlying.model#

Helper to get the world’s model instance.

property Underlying.data#

Helper to get the world’s simulation data instance.

property Underlying._obstacles: list[Geom | FreeGeom | Mocap]#

Get the obstacles in the task.

Combine all types of object in current environment together into single list in order to easily iterate them.