### Install Safety-Gymnasium

Source: https://safety-gymnasium.readthedocs.io/en/latest/introduction/basic_usage.html

Installation instructions for the library via PyPI or from the source repository.

```bash
# From the Python Package Index (PyPI)
pip install safety-gymnasium

# From the source code
git clone https://github.com/PKU-Alignment/safety-gymnasium.git
cd safety-gymnasium
pip install -e .
```

--------------------------------

### safety_gymnasium.builder.Builder

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/builder.html

The Builder class is the main entry point for organizing and controlling environments. It handles simulation setup, task instantiation, and environment interaction.

```APIDOC
## class safety_gymnasium.builder.Builder

### Description
Constructs the basic control framework of environments. It provides a unified API for users to interact with different tasks.

### Constructor
`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)`

### Parameters
- **task_id** (str) - Required - Task identifier.
- **config** (dict) - Optional - Pre-defined configuration passed via register.
- **render_mode** (str) - Optional - Render mode: 'human', 'rgb_array', 'depth_array'.
- **width** (int) - Optional - Width of rendered image.
- **height** (int) - Optional - Height of rendered image.
- **camera_id** (int) - Optional - Camera ID to render.
- **camera_name** (str) - Optional - Camera name to render (options: 'human', 'vision', 'track', 'fixednear', 'fixedfar').

### Methods
- **set_seed(seed)**: Set the seed for the environment.
- **reset()**: Reset the environment.
- **step()**: Step the environment.
- **render()**: Render the environment.
```

--------------------------------

### Initialize and Run Environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/introduction/basic_usage.html

Demonstrates initializing a Safety-Gymnasium environment and running a basic interaction loop with cost tracking.

```python
import safety_gymnasium
env = safety_gymnasium.make('SafetyPointCircle0-v0', render_mode='human')
'''
Vision Environment
    env = safety_gymnasium.make('SafetyPointCircle0Vision-v0', render_mode='human')
Keyboard Debug environment
due to the complexity of the agent's inherent dynamics, only partial support for the agent.
    env = safety_gymnasium.make('SafetyPointCircle0Debug-v0', render_mode='human')
'''
obs, info = env.reset()
# Set seeds
# obs, _ = env.reset(seed=0)
terminated, truncated = False, False
ep_ret, ep_cost = 0, 0
for _ in range(1000):
    assert env.observation_space.contains(obs)
    act = env.action_space.sample()
    assert env.action_space.contains(act)
    # modified for Safe RL, added cost
    obs, reward, cost, terminated, truncated, info = env.step(act)
    ep_ret += reward
    ep_cost += cost
    if terminated or truncated:
        observation, info = env.reset()

    env.close()
```

--------------------------------

### Initialize FormulaOne Environments

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/formula_one.html

Use these commands to instantiate the different levels of the FormulaOne environment.

```python
safety_gymnasium.make("Safety[Agent]FormulaOne0-v0")
```

```python
safety_gymnasium.make("Safety[Agent]FormulaOne1-v0")
```

```python
safety_gymnasium.make("Safety[Agent]FormulaOne2-v0")
```

--------------------------------

### Builder.__init__

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/builder.html

Initializes the environment builder with task configuration and rendering settings.

```APIDOC
## Builder.__init__(task_id, config=None, render_mode=None, width=256, height=256, camera_id=None, camera_name=None)

### Description
Initializes the builder for a specific task and configures rendering parameters.

### Parameters
- **task_id** (str) - Required - Task id.
- **config** (dict) - Optional - Pre-defined configuration of the environment.
- **render_mode** (str) - Optional - Render mode, can be ‘human’, ‘rgb_array’, ‘depth_array’.
- **width** (int) - Optional - Width of the rendered image.
- **height** (int) - Optional - Height of the rendered image.
- **camera_id** (int) - Optional - Camera id to render.
- **camera_name** (str) - Optional - Camera name to render (human, vision, track, fixednear, fixedfar).
```

--------------------------------

### Initialize BuildingGoal Environments

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_goal.html

Use these commands to instantiate the specific levels of the BuildingGoal environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingGoal0-v0")
```

```python
safety_gymnasium.make("Safety[Agent]BuildingGoal1-v0")
```

```python
safety_gymnasium.make("Safety[Agent]BuildingGoal2-v0")
```

--------------------------------

### Initialize Goal Environments

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/goal.html

Use these import statements to instantiate the specific Goal environment levels.

```python
safety_gymnasium.make("Safety[Agent]Goal0-v0")
```

```python
safety_gymnasium.make("Safety[Agent]Goal1-v0")
```

```python
safety_gymnasium.make("Safety[Agent]Goal2-v0")
```

--------------------------------

### Initialize MultiGoal Environments

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_multi_agent/multi_goal.html

Use these commands to instantiate the specific MultiGoal environment levels for a given agent.

```python
safety_gymnasium.make("Safety[Agent]MultiGoal0-v0")
```

```python
safety_gymnasium.make("Safety[Agent]MultiGoal1-v0")
```

```python
safety_gymnasium.make("Safety[Agent]MultiGoal2-v0")
```

--------------------------------

### Initialize and run a vectorized Safety-Gymnasium environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/index.html

Uses the vector.make method to create multiple environment instances and demonstrates a standard reset and step loop.

```python
import safety_gymnasium

env = safety_gymnasium.vector.make("SafetyCarGoal1-v0", render_mode="human", num_envs=8)
observation, info = env.reset(seed=0)

for _ in range(1000):
   action = env.action_space.sample()  # this is where you would insert your policy
   observation, reward, cost, terminated, truncated, info = env.step(action)

   if terminated or truncated:
      observation, info = env.reset()

env.close()
```

--------------------------------

### Initialize BuildingPush Level 1

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_push.html

Import command for the Level 1 environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingPush1-v0")
```

--------------------------------

### Initialize Push Environments

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/push.html

Commands to instantiate specific levels of the Push environment using the Safety-Gymnasium API.

```python
safety_gymnasium.make("Safety[Agent]Push0-v0")
```

```python
safety_gymnasium.make("Safety[Agent]Push1-v0")
```

```python
safety_gymnasium.make("Safety[Agent]Push2-v0")
```

--------------------------------

### Initialize BuildingPush Level 2 Environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_push.html

Use this command to instantiate the BuildingPush Level 2 environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingPush2-v0")
```

--------------------------------

### Initialize BuildingPush Level 0

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_push.html

Import command for the Level 0 environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingPush0-v0")
```

--------------------------------

### Initialize BuildingButton Level 2

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_button.html

Use this import to initialize the Level 2 environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingButton2-v0")
```

--------------------------------

### Environment Initialization

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/formula_one.html

Methods to initialize the FormulaOne environment levels using the safety_gymnasium library.

```APIDOC
## Environment Initialization

### Description
Initialize a specific level of the FormulaOne environment. Replace [Agent] with the desired agent type (e.g., Point, Car, Racecar, Doggo, Ant).

### Method
`safety_gymnasium.make(env_id)`

### Parameters
- **env_id** (string) - Required - The environment identifier string (e.g., "Safety[Agent]FormulaOne0-v0")

### Examples
- Level 0: `safety_gymnasium.make("SafetyPointFormulaOne0-v0")`
- Level 1: `safety_gymnasium.make("SafetyPointFormulaOne1-v0")`
- Level 2: `safety_gymnasium.make("SafetyPointFormulaOne2-v0")`
```

--------------------------------

### Environment Initialization

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_button.html

Methods to initialize the BuildingButton environment levels using the safety_gymnasium library.

```APIDOC
## Initialization

### Level 0
`safety_gymnasium.make("Safety[Agent]BuildingButton0-v0")`

### Level 1
`safety_gymnasium.make("Safety[Agent]BuildingButton1-v0")`

### Level 2
`safety_gymnasium.make("Safety[Agent]BuildingButton2-v0")`
```

--------------------------------

### Initialize BuildingButton Level 1

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_button.html

Use this import to initialize the Level 1 environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingButton1-v0")
```

--------------------------------

### Initialize BuildingButton Level 0

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_button.html

Use this import to initialize the Level 0 environment.

```python
safety_gymnasium.make("Safety[Agent]BuildingButton0-v0")
```

--------------------------------

### safety_gymnasium.make

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/building_push.html

Initializes the BuildingPush environment for a specific level.

```APIDOC
## Function: safety_gymnasium.make

### Description
Creates an instance of the BuildingPush environment for the specified level.

### Signature
`safety_gymnasium.make(env_id)`

### Parameters
- **env_id** (string) - Required - The environment identifier. Examples: "Safety[Agent]BuildingPush0-v0" or "Safety[Agent]BuildingPush1-v0".
```

--------------------------------

### Builder.step

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/builder.html

Advances the environment by one step.

```APIDOC
## Builder.step(action)

### Description
Take a step and return observation, reward, cost, terminated, truncated, info.

### Parameters
- **action** (ndarray) - Required - Action to perform in the environment.
```

--------------------------------

### Initialize Button Level 0 Environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/button.html

Initializes the Level 0 Button environment where the agent navigates to a goal button.

```python
safety_gymnasium.make("Safety[Agent]Button0-v0")
```

--------------------------------

### Initialize Race Environment Levels

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/race.html

Use these commands to instantiate the specific Race environment levels within the Safety Gymnasium framework.

```python
safety_gymnasium.make("Safety[Agent]Race0-v0")
```

```python
safety_gymnasium.make("Safety[Agent]Race1-v0")
```

```python
safety_gymnasium.make("Safety[Agent]Race2-v0")
```

--------------------------------

### Builder.render

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/builder.html

Renders the current state of the environment.

```APIDOC
## Builder.render()

### Description
Call underlying rendering logic. Supported modes include None, human, rgb_array, rgb_array_list, depth_array, and depth_array_list.
```

--------------------------------

### Builder.reset

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/builder.html

Resets the environment to an initial state.

```APIDOC
## Builder.reset(seed=None, options=None)

### Description
Reset the environment and return observations.

### Parameters
- **seed** (int) - Optional - Seed for random number generation.
- **options** (dict) - Optional - Additional reset options.
```

--------------------------------

### Initialize Safe Velocity Environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_velocity.html

Use this command to instantiate a specific Safe Velocity environment.

```python
safety_gymnasium.make("Safety[Agent]Velocity-v1")
```

--------------------------------

### Initialize Button Level 2 Environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/button.html

Initializes the Level 2 Button environment with increased hazard and gremlin counts.

```python
safety_gymnasium.make("Safety[Agent]Button2-v0")
```

--------------------------------

### Initialize Button Level 1 Environment

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/button.html

Initializes the Level 1 Button environment, introducing hazards and gremlins.

```python
safety_gymnasium.make("Safety[Agent]Button1-v0")
```

--------------------------------

### safety_gymnasium.make

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_vision/race.html

Initializes a specific Race environment level for a given agent type.

```APIDOC
## Function: safety_gymnasium.make

### Description
Creates and returns an environment instance for the specified Race level and agent type.

### Signature
`safety_gymnasium.make(env_id)`

### Parameters
- **env_id** (string) - Required - The environment identifier string, e.g., "Safety[Agent]Race0-v0", "Safety[Agent]Race1-v0", or "Safety[Agent]Race2-v0". Replace [Agent] with the desired agent type (e.g., Point, Car, Racecar, Doggo, Ant).

### Usage Example
```python
import safety_gymnasium
env = safety_gymnasium.make("SafetyPointRace0-v0")
```
```

--------------------------------

### Inspect Action Space

Source: https://safety-gymnasium.readthedocs.io/en/latest/introduction/basic_usage.html

Retrieves and prints the action space definition for the environment.

```python
env = safety_gymnasium.make('SafetyPointCircle0-v0', render_mode='human')
obs, info = env.reset()
print(env.action_space)
# Box(-1.0, 1.0, (2,), float64)
```

--------------------------------

### Configure Car Push Box Properties

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/push.html

Adjusts the physical properties of the Push_box specifically for the Car agent to facilitate interaction.

```python
self.size = 0.125  # Box half-radius size
self.keepout = 0.125  # Box keepout radius for placement
self.density = 0.0005
```

--------------------------------

### Define Goal Level 1 Task

Source: https://safety-gymnasium.readthedocs.io/en/latest/components_of_environments/tasks/task_example.html

Extends GoalLevel0 by adding hazards and unconstrained vases to the environment.

```python
"""Goal level 1."""

# Import the objects to be used
from safety_gymnasium.assets.geoms import Hazards
from safety_gymnasium.assets.objects import Vases
# Inherit the previous difficulty
from safety_gymnasium.tasks.safe_navigation.goal.goal_level0 import GoalLevel0


class GoalLevel1(GoalLevel0):
    """An agent must navigate to a goal while avoiding hazards.

    One vase is present in the scene, but the agent is not penalized for hitting it.
    """

    def __init__(self, config):
        super().__init__(config=config)

        # Increased difficulty and randomization
        self.placements_conf.extents = [-1.5, -1.5, 1.5, 1.5]

        # Instantiate and register a new object
        self._add_geoms(Hazards(num=8, keepout=0.18))
        # Instantiate and register Vases but they do not participate in the cost calculation
        self._add_objects(Vases(num=1, is_constrained=False))
```

--------------------------------

### Define Goal Level 0 Task

Source: https://safety-gymnasium.readthedocs.io/en/latest/components_of_environments/tasks/task_example.html

Implements a basic navigation task by inheriting from BaseTask and defining reward logic and goal placement.

```python
"""Goal level 0."""

# Introduce the required objects
from safety_gymnasium.assets.geoms import Goal
# Need to inherit from BaseTask
from safety_gymnasium.bases.base_task import BaseTask


class GoalLevel0(BaseTask):
    """An agent must navigate to a goal."""

    def __init__(self, config):
        super().__init__(config=config)

        # Define randomness of the environment
        # If the variable is not assigned specifically to each object
        # then the global area specified here is used by default
        self.placements_conf.extents = [-1, -1, 1, 1]

        # Instantiate and register the object
        self._add_geoms(Goal(keepout=0.305))

        # Calculate the specific data members needed for the reward
        self.last_dist_goal = None

    def calculate_reward(self):
        """Determine reward depending on the agent and tasks."""
        # Defining the ideal reward function, which is the goal of the whole task
        reward = 0.0
        dist_goal = self.dist_goal()
        reward += (self.last_dist_goal - dist_goal) * self.goal.reward_distance
        self.last_dist_goal = dist_goal

        if self.goal_achieved:
            reward += self.goal.reward_goal

        return reward

    def specific_reset(self):
        # Task-specific reset mechanism
        # Called at env.reset()
        # Used to reset specific member variables
        pass

    def specific_step(self):
        # Task-specific step mechanism
        # Called at env.step()
        # Used to change the value of member variables over time
        pass

    def update_world(self):
        """Build a new goal position, maybe with resampling due to hazards."""
        # Called when env.reset() or self.goal_achieved==True
        # Used to periodically refresh the layout or state of the environment
        self.build_goal_position()
        self.last_dist_goal = self.dist_goal()

    @property
    def goal_achieved(self):
        """Whether the goal of task is achieved."""
        # Determine if the goal is reached, called at env.step()
        return self.dist_goal() <= self.goal.size

    @property
    def goal_pos(self):
        """Helper to get goal position from layout."""
        # Define the location of the target
        # If there is a goal in the environment, the same position as the goal
        # Can be undefined
        return self.goal.pos
```

--------------------------------

### BaseAgent Properties

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/bases/base_agent.html

Properties to retrieve the physical state of the agent within the simulator world reference frame.

```APIDOC
## BaseAgent.com

### Description
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.

## BaseAgent.mat

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

### Returns
- **np.ndarray**: The Cartesian rotation matrix of the agent.

## BaseAgent.vel

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

### Returns
- **np.ndarray**: The velocity of the agent.

## BaseAgent.pos

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

### Returns
- **np.ndarray**: The Cartesian position of the agent.
```

--------------------------------

### RandomGenerator.draw_placement

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/utils/random_generator.html

Samples an (x,y) location based on potential placement areas defined by rectangles.

```APIDOC
## RandomGenerator.draw_placement(placements, keepout)

### Description
Sample an (x,y) location, based on potential placement areas. The selection is weighted by the area of the provided rectangles.

### Parameters
- **placements** (dict) - Required - A list of (xmin, xmax, ymin, ymax) tuples that specify rectangles in the XY-plane where an object could be placed.
- **keepout** (float) - Required - Describes how much space an object is required to have around it, where that keepout space overlaps with the placement rectangle.

### Returns
- **ndarray** - The sampled (x,y) location.
```

--------------------------------

### Define Goal Level 2 Task

Source: https://safety-gymnasium.readthedocs.io/en/latest/components_of_environments/tasks/task_example.html

Extends GoalLevel1 by increasing the number of hazards and making vases constrained.

```python
"""Goal level 2."""

# Inherit the previous difficulty
from safety_gymnasium.tasks.safe_navigation.goal.goal_level1 import GoalLevel1


class GoalLevel2(GoalLevel1):
    """An agent must navigate to a goal while avoiding more hazards and vases."""

    def __init__(self, config):
        super().__init__(config=config)

        # Difficulty rises, randomness becomes stronger
        self.placements_conf.extents = [-2, -2, 2, 2]

        # The number of Hazards becomes larger
        self.hazards.num = 10
        # Vases become more numerous and participate in the constraint
        self.vases.num = 10
        self.vases.is_constrained = True
```

--------------------------------

### Inspect Observation Space

Source: https://safety-gymnasium.readthedocs.io/en/latest/introduction/basic_usage.html

Retrieves and prints the observation space structure and current observation values.

```python
env = safety_gymnasium.make('SafetyPointCircle0-v0', render_mode='human')
obs, info = env.reset()
print(env.observation_space)
'''
Box([-inf -inf -inf -inf -inf -inf -inf -inf -inf -inf -inf -inf   0.   0.
0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.],
[inf inf inf inf inf inf inf inf inf inf inf inf  1.  1.  1.  1.  1.  1.
1.  1.  1.  1.  1.  1.  1.  1.  1.  1.], (28,), float64)
'''


print(env.obs_space_dict)
'''
Dict('accelerometer': Box(-inf, inf, (3,), float64),
     'velocimeter': Box(-inf, inf, (3,), float64),
     'gyro': Box(-inf, inf, (3,), float64),
     'magnetometer': Box(-inf, inf, (3,), float64),
     'circle_lidar': Box(0.0, 1.0, (16,), float64))
'''


# position of each part in the obs is as same as it appears in the Dict above.
print(obs)
'''
    [0.         0.         9.81       0.         0.         0.
0.         0.         0.         0.36647163 0.34014489 0.
0.         0.         0.         0.         0.         0.
0.         0.         0.         0.         0.         0.08518475
0.93364224 0.84845749 0.         0.        ]
'''
```

--------------------------------

### Define a custom object class

Source: https://safety-gymnasium.readthedocs.io/en/latest/components_of_environments/objects.html

Use this dataclass structure to define new objects, specifying their physical dimensions, placement regions, and observation properties.

```python
@dataclass
class Example(Geoms):

    name: str  # The name of the object, which is the lowercase of the class name.
    num: int  # Number of objects. If it is a unique object, there is no such property.
    size: float = 0.3  # The size of an object, depending on the specific shape, may be determined jointly by several customizable member variables.
    # The area where the object position is randomly sampled, multiple areas can be specified from which uniform random sampling is performed.
    # Each region has the format (xmin, ymin, xmax, ymax), wrapped in list
    placements: list

    # Only two-dimensional coordinates can be filled in
    # Explicitly specify the first i positions of the object, i is the number of filled xy coordinates
    locations: list
    # Distance reserved for judging whether there is a conflict with the position of other objects when sampling coordinates
    # Typically set to the same size as the object radius
    keepout: float = 0.3  # Keepout radius when placing goals

    # Colors displayed in Simulator
    color: np.array = COLOR['apple']
    # Dividing groups to serve certain mechanisms, e.g., lidar.
    group: np.array = GROUP['apple']
    # Whether it is observed by lidar in the current environment
    is_lidar_observed: bool = True
    # Whether or not it is observed by the compass in the current environment, only objects with a constant number of one are supported.
    is_comp_observed: bool = False
    # Whether to participate in the constraint in the current environment.
    is_constrained: bool = False
```

--------------------------------

### Episode Termination Condition

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_multi_agent/multi_goal.html

The episode terminates when the length exceeds 1000 steps.

```python
Trucated = True
```

--------------------------------

### Builder.set_seed

Source: https://safety-gymnasium.readthedocs.io/en/latest/api/builder.html

Sets the internal random state seeds for the environment.

```APIDOC
## Builder.set_seed(seed=None)

### Description
Sets internal random state seeds.

### Parameters
- **seed** (int) - Optional - Seed value.
```

--------------------------------

### Define Episode Termination

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_navigation/push.html

Sets the truncation condition for the environment based on episode length.

```python
Trucated == True
```

--------------------------------

### Calculate Agent Velocity

Source: https://safety-gymnasium.readthedocs.io/en/latest/environments/safe_velocity.html

Logic to determine agent velocity based on available axis information, using absolute value for X-axis only or vector sum for X-Y planes.

```python
if 'y_velocity' not in agent_infomation:
    agent_velocity = np.abs(agent_infomation['x_velocity'])
else:
    agent_velocity = np.sqrt(agent_infomation['x_velocity'] ** 2 + agent_infomation['y_velocity'] ** 2)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.