cambrian.envs.env

Defines the MjCambrianEnv class.

Classes

MjCambrianEnvConfig	Defines a config for the cambrian environment.
MjCambrianEnv	A MjCambrianEnv defines a gymnasium environment that's based off mujoco.

Module Contents

class MjCambrianEnvConfig

Bases: hydra_config.HydraContainerConfig

Defines a config for the cambrian environment.

Variables:

• instance (Callable[[Self], "MjCambrianEnv"]) – The class method to use to instantiate the environment.

• xml (MjCambrianXMLConfig) – The xml for the scene. This is the xml that will be used to create the environment. See MjCambrianXML for more info.

• step_fn (MjCambrianStepFn) – The step function to use. See the MjCambrianStepFn for more info. The step fn is called before the termination, truncation, and reward fns, and after the action has been applied to the agents. It takes the environment, the observations, the info dict, and any additional kwargs. Returns the updated observations and info dict.

• termination_fn (MjCambrianTerminationFn) – The termination function to use. See the MjCambrianTerminationFn for more info.

• truncation_fn (MjCambrianTruncationFn) – The truncation function to use. See the MjCambrianTruncationFn for more info.

• reward_fn (MjCambrianRewardFn) – The reward function type to use. See the MjCambrianRewardFn for more info.

• frame_skip (int) – The number of mujoco simulation steps per gym.step() call.

• max_episode_steps (int) – The maximum number of steps per episode.

• n_eval_episodes (int) – The number of episodes to evaluate for.

• add_overlays (bool) – Whether to add overlays or not.

• add_text_overlays (bool) – Whether to add text overlays or not.

• clear_overlays_on_reset (bool) – Whether to clear the overlays on reset or not. Consequence of setting to False is that when drawing position overlays and when mazes change between evaluations, the sites will be drawn on top of each other which may not be desired. When record is False, the overlays are always be cleared.

• debug_overlays_size (float) – The size of the debug overlays. This is a percentage of the total renderer size. If 0, debug overlays are disabled.

• renderer (Optional[MjCambrianViewerConfig]) – The default viewer config to use for the mujoco viewer. If unset, no renderer will be used. Should set to None if render will never be called. This may be useful to reduce the amount of vram consumed by non-rendering environments.

• save_filename (Optional[str]) – The filename to save recordings to. This is more of a placeholder for external scripts to use, if desired.

• agents (List[MjCambrianAgentConfig]) – The configs for the agents. The key will be used as the default name for the agent, unless explicitly set in the agent config.

class MjCambrianEnv(config, name=None)

Bases: pettingzoo.ParallelEnv, gymnasium.Env

A MjCambrianEnv defines a gymnasium environment that’s based off mujoco.

NOTES: - This is an overridden version of the MujocoEnv class. The two main differences is that we allow for /reset multiple agents and use our own custom renderer. It also reduces the need to create temporary xml files which MujocoEnv had to load. It’s essentially a copy of MujocoEnv with the two aforementioned major changes.

Parameters:

• config (MjCambrianEnvConfig) – The config object.

• name (Optional[str]) – The name of the environment. This is added as an overlay to the renderer.

generate_xml()

Generates the xml for the environment.

Todo

Can we update to use MjSpec?

reset(*, seed=None, options=None)

Reset the environment.

Will reset all underlying components (the maze, the agents, etc.). The simulation will then be stepped once to ensure that the observations are up-to-date.

Returns:

Tuple[ObsType, InfoType] –

The observations for each

agent and the info dict for each agent.

step(action)

Step the environment.

The dynamics is updated through the _step_mujoco_simulation method.

Parameters:

action (Dict[str, Any]) – The action to take for each agent. The keys define the agent name, and the values define the action for that agent.

Returns:

Dict[str, Any] – The observations for each agent. Dict[str, float]: The reward for each agent. Dict[str, bool]: Whether each agent has terminated. Dict[str, bool]: Whether each agent has truncated. Dict[str, Dict[str, Any]]: The info dict for each agent.

render()

Renders the environment.

Returns:

Dict[str, RenderFrame] –

The rendered image for each render mode mapped to

its corresponding str.

Todo

Make the cursor stuff clearer

property name: str

Returns the name of the environment.

property xml: cambrian.utils.cambrian_xml.MjCambrianXML

Returns the xml for the environment.

property agents: Dict[str, cambrian.agents.agent.MjCambrianAgent]

Returns the agents in the environment.

property renderer: cambrian.renderer.MjCambrianRenderer

Returns the renderer for the environment.

property spec: cambrian.utils.spec.MjCambrianSpec

Returns the mujoco spec for the environment.

property model: mujoco.MjModel

Returns the mujoco model for the environment.

property data: mujoco.MjData

Returns the mujoco data for the environment.

property episode_step: int

Returns the current episode step.

property num_timesteps: int

Returns the number of timesteps.

property max_episode_steps: int

Returns the max episode steps.

property overlays: Dict[str, Any]

Returns the overlays.

property cumulative_reward: float

Returns the cumulative reward.

property stashed_cumulative_reward: float

Returns the previous cumulative reward.

property num_agents: int

Returns the number of agents in the environment.

This is part of the PettingZoo API.

property possible_agents: List[str]

Returns the possible agents in the environment.

This is part of the PettingZoo API.

Assumes that the possible agents are the same as the agents.

property observation_spaces: gymnasium.spaces.Dict

Creates the observation spaces.

This is part of the PettingZoo API.

By default, this environment will support multi-agent observations/actions/etc. This method will create _all_ the observation spaces for the environment. But note that stable baselines3 only supports single agent environments (i.e. non-nested spaces.Dict), so ensure you wrap this env with a wrappers.MjCambrianSingleagentEnvWrapper if you want to use stable baselines3.

property action_spaces: gymnasium.spaces.Dict

Creates the action spaces.

This is part of the PettingZoo API.

By default, this environment will support multi-agent observations/actions/etc. This method will create _all_ the action spaces for the environment. But note that stable baselines3 only supports single agent environments (i.e. non-nested spaces.Dict), so ensure you wrap this env with a wrappers.MjCambrianSingleagentEnvWrapper if you want to use stable baselines3.

observation_space(agent)

Returns the observation space for the given agent.

This is part of the PettingZoo API.

action_space(agent)

Returns the action space for the given agent.

This is part of the PettingZoo API.

abstract state()

Returns the state of the environment.

This is part of the PettingZoo API.

set_random_seed(seed)

Sets the seed for the environment.

record(record=True, *, path=None)

Sets whether the environment is recording.

save(path, *, save_pkl=False, **kwargs)

Saves the simulation output to the given path.

close()

Closes the environment.