Builder#

safety_gymnasium.builder#

class safety_gymnasium.builder.Builder(task_id: str, config: dict | None = None, render_mode: str | None = None, width: int = 256, height: int = 256, camera_id: int | None = None, camera_name: str | None = None)#

An entry point to organize different environments, while showing unified API for users.

The Builder class constructs the basic control framework of environments, while the details were hidden. There is another important parts, which is task module including all task specific operation.

Methods:

_setup_simulation(): Set up mujoco the simulation instance.
_get_task(): Instantiate a task object.
set_seed(): Set the seed for the environment.
reset(): Reset the environment.
step(): Step the environment.
_reward(): Calculate the reward.
_cost(): Calculate the cost.
render(): Render the environment.

Attributes:

task_id (str): Task id.
config (dict): Pre-defined configuration of the environment, which is passed via safety_gymnasium.register().
render_parameters (RenderConf): Render parameters.
action_space (gymnasium.spaces.Box): Action space.
observation_space (gymnasium.spaces.Dict): Observation space.
obs_space_dict (dict): Observation space dictionary.
done (bool): Whether the episode is done.

Initialize the builder.

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.

Parameters:

task_id (str) – Task id.
config (dict) – Pre-defined configuration of the environment, which is passed via safety_gymnasium.register().
render_mode (str) – Render mode, can be ‘human’, ‘rgb_array’, ‘depth_array’.
width (int) – Width of the rendered image.
height (int) – Height of the rendered image.
camera_id (int) – Camera id to render.
camera_name (str) – Camera name to render.

DataClass#

class safety_gymnasium.builder.RenderConf(mode: str | None = None, width: int = 256, height: int = 256, camera_id: int | None = None, camera_name: str | None = None)#

Render options.

Variables:

mode (str) – render mode, can be ‘human’, ‘rgb_array’, ‘depth_array’.
width (int) – width of the rendered image.
height (int) – height of the rendered image.
camera_id (int) – camera id to render.
camera_name (str) – camera name to render.
Note – camera_id and camera_name can only be set one of them.

Methods#

safety_gymnasium.builder.Builder.__init__(self, task_id: str, config: dict | None = None, render_mode: str | None = None, width: int = 256, height: int = 256, camera_id: int | None = None, camera_name: str | None = None) → None#

Initialize the builder.

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.

Parameters:

task_id (str) – Task id.
config (dict) – Pre-defined configuration of the environment, which is passed via safety_gymnasium.register().
render_mode (str) – Render mode, can be ‘human’, ‘rgb_array’, ‘depth_array’.
width (int) – Width of the rendered image.
height (int) – Height of the rendered image.
camera_id (int) – Camera id to render.
camera_name (str) – Camera name to render.

safety_gymnasium.builder.Builder._setup_simulation(self) → None#: Set up mujoco the simulation instance.

safety_gymnasium.builder.Builder._get_task(self) → BaseTask#: Instantiate a task object.

safety_gymnasium.builder.Builder.set_seed(self, seed: int | None = None) → None#: Set internal random state seeds.

safety_gymnasium.builder.Builder.reset(self, *, seed: int | None = None, options: dict | None = None) → tuple[np.ndarray, dict]#: Reset the environment and return observations.

safety_gymnasium.builder.Builder.step(self, action: ndarray) → tuple[numpy.ndarray, float, float, bool, bool, dict]#: Take a step and return observation, reward, cost, terminated, truncated, info.

safety_gymnasium.builder.Builder._reward(self) → float#

Calculate the current rewards.

Call exactly once per step.

safety_gymnasium.builder.Builder._cost(self) → dict#

Calculate the current costs and return a dict.

Call exactly once per step.

safety_gymnasium.builder.Builder.render(self) → np.ndarray | None#

Call underlying safety_gymnasium.bases.underlying.Underlying.render() directly.

Width and height in parameters are constant defaults for rendering frames for humans. (not used for vision)

The set of supported modes varies per environment. (And some third-party environments may not support rendering at all.) By convention, if render_mode is:

None (default): no render is computed.
human: render return None. The environment is continuously rendered in the current display or terminal. Usually for human consumption.
rgb_array: return a single frame representing the current state of the environment. A frame is a numpy.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.
rgb_array_list: return a list of frames representing the states of the environment since the last reset. Each frame is a numpy.ndarray with shape (x, y, 3), as with rgb_array.
depth_array: return a single frame representing the current state of the environment. A frame is a numpy.ndarray with shape (x, y) representing depth values for an x-by-y pixel image.
depth_array_list: return a list of frames representing the states of the environment since the last reset. Each frame is a numpy.ndarray with shape (x, y), as with depth_array.

Additional Methods#

property Builder.action_space: Box#: Helper to get action space.

property Builder.observation_space: gymnasium.spaces.Box | gymnasium.spaces.Dict#: Helper to get observation space.

property Builder.obs_space_dict: dict[str, gymnasium.spaces.box.Box]#: Helper to get observation space dictionary.

property Builder.done: bool#: Whether this episode is ended.