BaseAgent

safety_gymnasium.bases.base_agent

class safety_gymnasium.bases.base_agent.BaseAgent(name: str, random_generator: RandomGenerator, placements: list | None = None, locations: list | None = None, keepout: float = 0.4, rot: float | None = None)

Base class for agent.

Get mujoco-specific info about agent and control agent in environments.

Methods:

• _load_model(): Load agent model from xml file.

• _init_body_info(): Initialize body information.

• _build_action_space(): Build action space for agent.

• _init_jnt_sensors(): Initialize information of joint sensors in current agent.

• set_engine(): Set physical engine instance.

• apply_action(): Agent in physical simulator take specific action.

• build_sensor_observation_space(): Build agent specific observation space according to sensors.

• obs_sensor(): Get agent specific observations according to sensors.

• get_sensor(): Get specific sensor observations in agent.

• dist_xy(): Get distance between agent and target in XY plane.

• world_xy(): Get agent XY coordinate in world frame.

• keyboard_control_callback(): Keyboard control callback designed for debug mode for keyboard controlling.

• debug(): Implement specific action debug mode which maps keyboard input into action of agent.

• is_alive(): Check if agent is alive.

• reset(): Reset agent to specific initial internal state, eg.joints angles.

Attributes:

• base (str): Path to agent XML.

• random_generator (RandomGenerator): Random generator.

• placements (list): Agent placements list (defaults to full extents).

• locations (list): Explicitly place agent XY coordinate.

• keepout (float): Needs to be set to match the agent XML used.

• rot (float): Override agent starting angle.

• engine (Engine): Physical engine instance.

• sensor_conf (SensorConf): Sensor observations configuration.

• sensor_info (SensorInfo): Sensor information.

• body_info (BodyInfo): Body information.

• debug_info (DebugInfo): Debug information.

• z_height (float): Initial height of agent in environments.

• action_space (gymnasium.spaces.Box): Action space.

• com (np.ndarray): The Cartesian coordinate of agent center of mass.

• mat (np.ndarray): The Cartesian rotation matrix of agent.

• vel (np.ndarray): The Cartesian velocity of agent.

• pos (np.ndarray): The Cartesian position of agent.

Initialize the agent.

Parameters:

• name (str) – Name of agent.

• random_generator (RandomGenerator) – Random generator.

• placements (list) – Agent placements list (defaults to full extents).

• locations (list) – Explicitly place agent XY coordinate.

• keepout (float) – Needs to be set to match the agent XML used.

• rot (float) – Override agent starting angle.

DataClass

class safety_gymnasium.bases.base_agent.SensorConf(sensors: tuple[str, ...] = ('accelerometer', 'velocimeter', 'gyro', 'magnetometer'), sensors_hinge_joints: bool = True, sensors_ball_joints: bool = True, sensors_angle_components: bool = True)

Sensor observations configuration.

Variables:

• sensors (tuple) – Specify which sensors to add to observation space.

• sensors_hinge_joints (bool) – Observe named joint position / velocity sensors.

• sensors_ball_joints (bool) – Observe named ball joint position / velocity sensors.

• sensors_angle_components (bool) – Observe sin/cos theta instead of theta.

class safety_gymnasium.bases.base_agent.SensorInfo(hinge_pos_names: list = <factory>, hinge_vel_names: list = <factory>, freejoint_pos_name: str | None = None, freejoint_qvel_name: str | None = None, ballquat_names: list = <factory>, ballangvel_names: list = <factory>, sensor_dim: list = <factory>)

Sensor information generated in running.

Needed to figure out observation space.

Variables:

• hinge_pos_names (list) – List of hinge joint position sensor names.

• hinge_vel_names (list) – List of hinge joint velocity sensor names.

• freejoint_pos_name (str) – Name of free joint position sensor.

• freejoint_qvel_name (str) – Name of free joint velocity sensor.

• ballquat_names (list) – List of ball joint quaternion sensor names.

• ballangvel_names (list) – List of ball joint angular velocity sensor names.

• sensor_dim (list) – List of sensor dimensions.

class safety_gymnasium.bases.base_agent.BodyInfo(nq: int | None = None, nv: int | None = None, nu: int | None = None, nbody: int | None = None, geom_names: list = <factory>)

Body information generated in running.

Needed to figure out the observation spaces.

Variables:

• nq (int) – Number of generalized coordinates in agent = dim(qpos).

• nv (int) – Number of degrees of freedom in agent = dim(qvel).

• nu (int) – Number of actuators/controls in agent = dim(ctrl), needed to figure out action space.

• nbody (int) – Number of bodies in agent.

• geom_names (list) – List of geom names in agent.

class safety_gymnasium.bases.base_agent.DebugInfo(keys: set = <factory>)

Debug information generated in running.

Variables:

keys (set) – Set of keys are pressed on keyboard.

Methods

safety_gymnasium.bases.base_agent.BaseAgent.__init__(self, name: str, random_generator: RandomGenerator, placements: list | None = None, locations: list | None = None, keepout: float = 0.4, rot: float | None = None) → None

Initialize the agent.

Parameters:

• name (str) – Name of agent.

• random_generator (RandomGenerator) – Random generator.

• placements (list) – Agent placements list (defaults to full extents).

• locations (list) – Explicitly place agent XY coordinate.

• keepout (float) – Needs to be set to match the agent XML used.

• rot (float) – Override agent starting angle.

safety_gymnasium.bases.base_agent.BaseAgent._load_model(self) → None

Load the agent model from the xml file.

Note

The physical engine instance which is created here is just used to figure out the dynamics of agent and save some useful information, when the environment is actually created, the physical engine instance will be replaced by the new instance which is created in safety_gymnasium.World via set_engine().

safety_gymnasium.bases.base_agent.BaseAgent._init_body_info(self) → None

Initialize body information.

Access directly from mujoco instance created on agent xml model.

safety_gymnasium.bases.base_agent.BaseAgent._build_action_space(self) → Box

Build the action space for this agent.

Access directly from mujoco instance created on agent xml model.

safety_gymnasium.bases.base_agent.BaseAgent._init_jnt_sensors(self) → None

Initialize joint sensors.

Access directly from mujoco instance created on agent xml model and save different joint names into different lists.

safety_gymnasium.bases.base_agent.BaseAgent.set_engine(self, engine: Engine) → None

Set the engine instance.

Parameters:

engine (Engine) – The engine instance.

Note

This method will be called twice in one single environment.

1. When the agent is initialized, used to get and save useful information.

2. When the environment is created, used to update the engine instance.

safety_gymnasium.bases.base_agent.BaseAgent.apply_action(self, action: np.ndarray, noise: np.ndarray | None = None) → None

Apply an action to the agent.

Just fill up the control array in the engine data.

Parameters:

• action (np.ndarray) – The action to apply.

• noise (np.ndarray) – The noise to add to the action.

safety_gymnasium.bases.base_agent.BaseAgent.build_sensor_observation_space(self) → Dict

Build observation space for all sensor types.

Returns:

gymnasium.spaces.Dict – The observation space generated by sensors bound with agent.

safety_gymnasium.bases.base_agent.BaseAgent.obs_sensor(self) → dict[str, numpy.ndarray]

Get observations of all sensor types.

Returns:

Dict[str, np.ndarray] – The observations generated by sensors bound with agent.

safety_gymnasium.bases.base_agent.BaseAgent.get_sensor(self, name: str) → ndarray

Get the value of one sensor.

Parameters:

name (str) – The name of the sensor to checkout.

Returns:

np.ndarray – The observation value of the sensor.

safety_gymnasium.bases.base_agent.BaseAgent.dist_xy(self, pos: ndarray) → float

Return the distance from the agent to an XY position.

Parameters:

pos (np.ndarray) – The position to measure the distance to.

Returns:

float – The distance from the agent to the position.

safety_gymnasium.bases.base_agent.BaseAgent.world_xy(self, pos: ndarray) → ndarray

Return the world XY vector to a position from the agent.

Parameters:

pos (np.ndarray) – The position to measure the vector to.

Returns:

np.ndarray – The world XY vector to the position.

safety_gymnasium.bases.base_agent.BaseAgent.keyboard_control_callback(self, key: int, action: int) → None

Callback for keyboard control.

Collect keys which are pressed.

Parameters:

• key (int) – The key code inputted by user.

• action (int) – The action of the key in glfw.

safety_gymnasium.bases.base_agent.BaseAgent.debug(self) → None

Debug mode.

Apply action which is inputted from keyboard.

safety_gymnasium.bases.base_agent.BaseAgent.is_alive(self) → bool

Returns True if the agent is healthy.

Returns:

bool – True if the agent is healthy, False if the agent is unhealthy.

safety_gymnasium.bases.base_agent.BaseAgent.reset(self) → None

Called when the environment is reset.

Additional Methods

property BaseAgent.com: ndarray

Get the position of the agent center of mass in the simulator world reference frame.

Returns:

np.ndarray – The Cartesian position of the agent center of mass.

property BaseAgent.mat: ndarray

Get the rotation matrix of the agent in the simulator world reference frame.

Returns:

np.ndarray – The Cartesian rotation matrix of the agent.

property BaseAgent.vel: ndarray

Get the velocity of the agent in the simulator world reference frame.

Returns:

np.ndarray – The velocity of the agent.

property BaseAgent.pos: ndarray

Get the position of the agent in the simulator world reference frame.

Returns:

np.ndarray – The Cartesian position of the agent.