embodichain.lab.gym

Submodules

envs
utils

Overview

The gym module provides a comprehensive framework for creating robot learning environments. It extends the Gymnasium interface to support multi-environment parallel execution, custom observations, and robotic-specific functionality.

Key Features:

• Multi-Environment Support: Run multiple environment instances in parallel for efficient training

• Gymnasium Integration: Full compatibility with the Gymnasium API and ecosystem

• Robotic Focus: Built-in support for robot control, sensors, and manipulation tasks

• Extensible Architecture: Easy to create custom environments and tasks

• GPU Acceleration: Leverage GPU computing for high-performance simulation

Environments Module (envs)

Base Environment Classes

class embodichain.lab.gym.envs.BaseEnv

Bases: Env

Base environment for robot learning.

Parameters:

• cfg (EnvCfg) – The environment configuration.

• **kwargs – Additional keyword arguments.

The foundational environment class that provides the core functionality for all EmbodiChain RL environments. This class extends the Gymnasium Env interface with multi-environment support and robotic-specific features. Methods:

__init__(cfg, **kwargs)
check_truncated(obs, info)	Check if the episode is truncated.
close()	Close the environment and release resources.
evaluate(**kwargs)	Evaluate whether the environment is currently in a success state by returning a dictionary with a "success" key or a failure state via a "fail" key
get_info(**kwargs)	Get info about the current environment state, include elapsed steps, success, fail, etc.
get_obs(**kwargs)	Get the observation from the robot agent and the environment.
get_reward(obs, action, info)	Get the reward for the current step.
get_sensor(name, **kwargs)	Get the sensor instance by name.
get_wrapper_attr(name)	Gets the attribute name from the environment.
render()	Compute the render frames as specified by render_mode during the initialization of the environment.
reset([seed, options])	Reset the SimulationManager environment and return the observation and info.
step(action, **kwargs)	Step the environment with the given action.

Attributes:

device	Return the device used by the environment.
np_random	Returns the environment's internal _np_random that if not set will initialise with a random seed.
unwrapped	Returns the base non-wrapped environment.

__init__(cfg, **kwargs)

check_truncated(obs, info)

Check if the episode is truncated.

Parameters:

• obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation from the environment.

• info (Dict[str, Any]) – The info dictionary.

Return type:

bool

Returns:

True if the episode is truncated, False otherwise.

close()

Close the environment and release resources.

Return type:

None

property device: Tensor

Return the device used by the environment.

evaluate(**kwargs)

Evaluate whether the environment is currently in a success state by returning a dictionary with a “success” key or a failure state via a “fail” key

This function may also return additional data that has been computed (e.g. is the robot grasping some object) that may be reused when generating observations and rewards.

By default if not overridden, this function returns an empty dictionary

Parameters:

**kwargs – Additional keyword arguments to be passed to the evaluate() function.

Return type:

Dict[str, Any]

Returns:

The evaluation dictionary.

get_info(**kwargs)

Get info about the current environment state, include elapsed steps, success, fail, etc.

The returned info dictionary must contain at the success and fail status of the current step.

Parameters:

**kwargs – Additional keyword arguments to be passed to the get_info() function.

Return type:

Dict[str, Any]

Returns:

The info dictionary.

get_obs(**kwargs)

Get the observation from the robot agent and the environment.

The default observation are:

• robot: the robot proprioception.

• sensor (optional): the sensor readings.

• extra (optional): any extra information.

Note

If self.num_envs == 1, return the observation in single_observation_space format. If self.num_envs > 1, return the observation in observation_space format.

Parameters:

**kwargs – Additional keyword arguments to be passed to the _get_sensor_obs() functions.

Return type:

Dict[str, Union[Tensor, Dict[str, Tensor]]]

Returns:

The observation dictionary.

get_reward(obs, action, info)

Get the reward for the current step.

Each SimulationManager env must implement its own get_reward function to define the reward function for the task, If the env is considered for RL/IL training.

Parameters:

• obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation from the environment.

• action (Union[Tensor, Dict[str, Tensor]]) – The action applied to the robot agent.

• info (Dict[str, Any]) – The info dictionary.

Return type:

float

Returns:

The reward for the current step.

get_sensor(name, **kwargs)

Get the sensor instance by name.

Parameters:

• name (str) – The name of the sensor.

• kwargs – Additional keyword arguments.

Return type:

BaseSensor

Returns:

The sensor instance.

get_wrapper_attr(name)

Gets the attribute name from the environment.

Return type:

Any

property np_random: Generator

Returns the environment’s internal _np_random that if not set will initialise with a random seed.

Returns:

Instances of np.random.Generator

render()

Compute the render frames as specified by render_mode during the initialization of the environment.

The environment’s metadata render modes (env.metadata[“render_modes”]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved through gymnasium.make which automatically applies a wrapper to collect rendered frames. :rtype: Union[TypeVar(RenderFrame), list[TypeVar(RenderFrame)], None]

Note

As the render_mode is known during __init__, the objects used to render the environment state should be initialised in __init__.

By convention, if the render_mode is:

• None (default): no render is computed.

• “human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during step() and render() doesn’t need to be called. Returns None.

• “rgb_array”: Return a single frame representing the current state of the environment. A frame is a np.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

• “ansi”: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

• “rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper, gymnasium.wrappers.RenderCollection that is automatically applied during gymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped after render() is called or reset().

Note

Make sure that your class’s metadata "render_modes" key includes the list of supported modes.

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make("CartPole-v1", render_mode="human")

reset(seed=None, options=None)

Reset the SimulationManager environment and return the observation and info.

Parameters:

• seed (Optional[int]) – The seed for the random number generator. Defaults to None, in which case the seed is not set.

• options (Optional[Dict]) – Additional options for resetting the environment. This can include:

Return type:

Tuple[Dict[str, Union[Tensor, Dict[str, Tensor]]], Dict]

Returns:

A tuple containing the observations and infos.

step(action, **kwargs)

Step the environment with the given action.

Parameters:

action (Union[Tensor, Dict[str, Tensor]]) – The action applied to the robot agent.

Return type:

Tuple[Dict[str, Union[Tensor, Dict[str, Tensor]]], Tensor, Tensor, Tensor, Dict[str, Any]]

Returns:

A tuple contraining the observation, reward, terminated, truncated, and info dictionary.

property unwrapped: Env[ObsType, ActType]

Returns the base non-wrapped environment.

Returns:

The base non-wrapped gymnasium.Env instance

Return type:

Env

class embodichain.lab.gym.envs.EnvCfg

Configuration for an Robot Learning Environment.

Configuration class for basic environment settings including simulation parameters and environment count. Methods:

copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

Attributes:

ignore_terminations	Whether to ignore terminations when deciding when to auto reset.
num_envs	The number of sub environments (arena in dexsim context) to be simulated in parallel.
seed	The seed for the random number generator.
sim_cfg	Simulation configuration for the environment.
sim_steps_per_control	Number of simulation steps per control (env) step.

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

ignore_terminations: bool

Whether to ignore terminations when deciding when to auto reset. Terminations can be caused by the task reaching a success or fail state as defined in a task’s evaluation function.

If set to False, meaning there is early stop in episode rollouts. If set to True, this would generally for situations where you may want to model a task as infinite horizon where a task stops only due to the timelimit.

num_envs: int

The number of sub environments (arena in dexsim context) to be simulated in parallel.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

seed: Optional[int]

The seed for the random number generator. Defaults to -1, in which case the seed is not set.

Note

The seed is set at the beginning of the environment initialization. This ensures that the environment creation is deterministic and behaves similarly across different runs.

sim_cfg: SimulationManagerCfg

Simulation configuration for the environment.

sim_steps_per_control: int

Number of simulation steps per control (env) step.

For instance, if the simulation dt is 0.01s and the control dt is 0.1s, then the sim_steps_per_control is 10. This means that the control action is updated every 10 simulation steps.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

Embodied Environment Classes

class embodichain.lab.gym.envs.EmbodiedEnv

Bases: BaseEnv

Embodied AI environment that is used to simulate the Embodied AI tasks.

Core simulation components for Embodied AI environments. - sensor: The sensors used to perceive the environment, which could be attached to the agent or the environment. - robot: The robot which will be used to interact with the environment. - light: The lights in the environment, which could be used to illuminate the environment.

• indirect: the indirect light sources, such as ambient light, IBL, etc.

  The indirect light sources are used for global illumination which affects the entire scene.

• direct: The direct light sources, such as point light, spot light, etc.

  The direct light sources are used for local illumination which mainly affects the arena in the scene.

• background: Kinematic or Static rigid objects, such as obstacles or landmarks.

• rigid_object: Dynamic objects that can be interacted with.

• rigid_object_group: Groups of rigid objects that can be interacted with.

• deformable_object(TODO: supported in the future): Deformable volumes or surfaces (cloth) that can be interacted with.

• articulation: Articulated objects that can be manipulated, such as doors, drawers, etc.

• event manager: The event manager is used to manage the events in the environment, such as randomization,

  perturbation, etc.

• observation manager: The observation manager is used to manage the observations in the environment,

  such as depth, segmentation, etc.

• action bank: The action bank is used to manage the actions in the environment, such as action composition, action graph, etc.

• affordance_datas: The affordance data that can be used to store the intermediate results or information

An advanced environment class that provides additional features for embodied AI research, including sophisticated observation management, event handling, and multi-modal sensor integration. Methods:

__init__(cfg, **kwargs)
check_truncated(obs, info)	Check if the episode is truncated.
close()	Close the environment and release resources.
create_demo_action_list(*args, **kwargs)	Create a demonstration action list for the environment.
evaluate(**kwargs)	Evaluate whether the environment is currently in a success state by returning a dictionary with a "success" key or a failure state via a "fail" key
get_affordance(key[, default])	Get an affordance value by key.
get_info(**kwargs)	Get info about the current environment state, include elapsed steps, success, fail, etc.
get_obs(**kwargs)	Get the observation from the robot agent and the environment.
get_reward(obs, action, info)	Get the reward for the current step.
get_sensor(name, **kwargs)	Get the sensor instance by name.
get_wrapper_attr(name)	Gets the attribute name from the environment.
is_task_success(**kwargs)	Determine if the task is successfully completed.
preview_sensor_data(name[, data_type, ...])	Preview the sensor data by matplotlib
render()	Compute the render frames as specified by render_mode during the initialization of the environment.
reset([seed, options])	Reset the SimulationManager environment and return the observation and info.
set_affordance(key, value)	Set an affordance value by key.
step(action, **kwargs)	Step the environment with the given action.
to_dataset(id[, save_path])	Convert the recorded episode data to a dataset format.

Attributes:

device	Return the device used by the environment.
np_random	Returns the environment's internal _np_random that if not set will initialise with a random seed.
unwrapped	Returns the base non-wrapped environment.

__init__(cfg, **kwargs)

check_truncated(obs, info)

Check if the episode is truncated.

Parameters:

• obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation from the environment.

• info (Dict[str, Any]) – The info dictionary.

Return type:

bool

Returns:

True if the episode is truncated, False otherwise.

close()

Close the environment and release resources.

Return type:

None

create_demo_action_list(*args, **kwargs)

Create a demonstration action list for the environment.

This function should be implemented in subclasses to generate a sequence of actions that demonstrate a specific task or behavior within the environment.

Returns:

A list of actions if a demonstration is available, otherwise None.

Return type:

Optional[Sequence[EnvAction]]

property device: Tensor

Return the device used by the environment.

evaluate(**kwargs)

Evaluate whether the environment is currently in a success state by returning a dictionary with a “success” key or a failure state via a “fail” key

This function may also return additional data that has been computed (e.g. is the robot grasping some object) that may be reused when generating observations and rewards.

By default if not overridden, this function returns an empty dictionary

Parameters:

**kwargs – Additional keyword arguments to be passed to the evaluate() function.

Return type:

Dict[str, Any]

Returns:

The evaluation dictionary.

get_affordance(key, default=None)

Get an affordance value by key.

Parameters:

• key (str) – The affordance key.

• default (Any, optional) – Default value if key not found.

Returns:

The affordance value or default.

Return type:

Any

get_info(**kwargs)

Get info about the current environment state, include elapsed steps, success, fail, etc.

The returned info dictionary must contain at the success and fail status of the current step.

Parameters:

**kwargs – Additional keyword arguments to be passed to the get_info() function.

Return type:

Dict[str, Any]

Returns:

The info dictionary.

get_obs(**kwargs)

Get the observation from the robot agent and the environment.

The default observation are:

• robot: the robot proprioception.

• sensor (optional): the sensor readings.

• extra (optional): any extra information.

Note

If self.num_envs == 1, return the observation in single_observation_space format. If self.num_envs > 1, return the observation in observation_space format.

Parameters:

**kwargs – Additional keyword arguments to be passed to the _get_sensor_obs() functions.

Return type:

Dict[str, Union[Tensor, Dict[str, Tensor]]]

Returns:

The observation dictionary.

get_reward(obs, action, info)

Get the reward for the current step.

Each SimulationManager env must implement its own get_reward function to define the reward function for the task, If the env is considered for RL/IL training.

Parameters:

• obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation from the environment.

• action (Union[Tensor, Dict[str, Tensor]]) – The action applied to the robot agent.

• info (Dict[str, Any]) – The info dictionary.

Return type:

float

Returns:

The reward for the current step.

get_sensor(name, **kwargs)

Get the sensor instance by name.

Parameters:

• name (str) – The name of the sensor.

• kwargs – Additional keyword arguments.

Return type:

BaseSensor

Returns:

The sensor instance.

get_wrapper_attr(name)

Gets the attribute name from the environment.

Return type:

Any

is_task_success(**kwargs)

Determine if the task is successfully completed. This is mainly used in the data generation process of the imitation learning.

Parameters:

**kwargs – Additional arguments for task-specific success criteria.

Returns:

A boolean tensor indicating success for each environment in the batch.

Return type:

torch.Tensor

property np_random: Generator

Returns the environment’s internal _np_random that if not set will initialise with a random seed.

Returns:

Instances of np.random.Generator

preview_sensor_data(name, data_type='color', env_ids=0, method='plt')

Preview the sensor data by matplotlib

Note

Currently only support RGB image preview.

Parameters:

• name (str) – name of the sensor to preview.

• data_type (str) – type of the sensor data to preview.

• env_ids (int) – index of the arena to preview. Defaults to 0.

• method (str) – method to preview the sensor data. Currently support “plt” and “cv2”. Defaults to “plt”.

Return type:

None

render()

Compute the render frames as specified by render_mode during the initialization of the environment.

The environment’s metadata render modes (env.metadata[“render_modes”]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved through gymnasium.make which automatically applies a wrapper to collect rendered frames. :rtype: Union[TypeVar(RenderFrame), list[TypeVar(RenderFrame)], None]

Note

As the render_mode is known during __init__, the objects used to render the environment state should be initialised in __init__.

By convention, if the render_mode is:

• None (default): no render is computed.

• “human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during step() and render() doesn’t need to be called. Returns None.

• “rgb_array”: Return a single frame representing the current state of the environment. A frame is a np.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

• “ansi”: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

• “rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper, gymnasium.wrappers.RenderCollection that is automatically applied during gymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped after render() is called or reset().

Note

Make sure that your class’s metadata "render_modes" key includes the list of supported modes.

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make("CartPole-v1", render_mode="human")

reset(seed=None, options=None)

Reset the SimulationManager environment and return the observation and info.

Parameters:

• seed (Optional[int]) – The seed for the random number generator. Defaults to None, in which case the seed is not set.

• options (Optional[Dict]) – Additional options for resetting the environment. This can include:

Return type:

Tuple[Dict[str, Union[Tensor, Dict[str, Tensor]]], Dict]

Returns:

A tuple containing the observations and infos.

set_affordance(key, value)

Set an affordance value by key.

Parameters:

• key (str) – The affordance key.

• value (Any) – The affordance value.

step(action, **kwargs)

Step the environment with the given action.

Parameters:

action (Union[Tensor, Dict[str, Tensor]]) – The action applied to the robot agent.

Return type:

Tuple[Dict[str, Union[Tensor, Dict[str, Tensor]]], Tensor, Tensor, Tensor, Dict[str, Any]]

Returns:

A tuple contraining the observation, reward, terminated, truncated, and info dictionary.

to_dataset(id, save_path=None)

Convert the recorded episode data to a dataset format.

Parameters:

• id (str) – Unique identifier for the dataset.

• save_path (str, optional) – Path to save the dataset. If None, use config or default.

Returns:

The path to the saved dataset, or None if failed.

Return type:

Optional[str]

property unwrapped: Env[ObsType, ActType]

Returns the base non-wrapped environment.

Returns:

The base non-wrapped gymnasium.Env instance

Return type:

Env

class embodichain.lab.gym.envs.EmbodiedEnvCfg

Configuration class for the Embodied Environment. Inherits from EnvCfg and can be extended with additional parameters if needed.

Configuration class for embodied environments with extended settings for lighting, observation management, and advanced simulation features. Classes:

EnvLightCfg

EnvLightCfg(direct: List[embodichain.lab.sim.cfg.LightCfg] = <factory>)

Methods:

copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

Attributes:

dataset	Data pipeline configuration.
events	Event settings.
filter_visual_rand	Whether to filter out visual randomization
ignore_terminations	Whether to ignore terminations when deciding when to auto reset.
num_envs	The number of sub environments (arena in dexsim context) to be simulated in parallel.
observations	Observation settings.
seed	The seed for the random number generator.
sim_cfg	Simulation configuration for the environment.
sim_steps_per_control	Number of simulation steps per control (env) step.

class EnvLightCfg

EnvLightCfg(direct: List[embodichain.lab.sim.cfg.LightCfg] = <factory>)

Methods:

copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

dataset: Optional[Dict[str, Any]]

Data pipeline configuration. Defaults to None.

events: Optional[object]

Event settings. Defaults to None, in which case no events are applied through the event manager.

Please refer to the embodichain.lab.gym.managers.EventManager class for more details.

filter_visual_rand: bool

Whether to filter out visual randomization

This is useful when we want to disable visual randomization for debug motion and physics issues.

ignore_terminations: bool

Whether to ignore terminations when deciding when to auto reset. Terminations can be caused by the task reaching a success or fail state as defined in a task’s evaluation function.

If set to False, meaning there is early stop in episode rollouts. If set to True, this would generally for situations where you may want to model a task as infinite horizon where a task stops only due to the timelimit.

num_envs: int

The number of sub environments (arena in dexsim context) to be simulated in parallel.

observations: Optional[object]

Observation settings. Defaults to None, in which case no additional observations are applied through the observation manager.

Please refer to the embodichain.lab.gym.managers.ObservationManager class for more details.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

seed: Optional[int]

The seed for the random number generator. Defaults to -1, in which case the seed is not set.

Note

The seed is set at the beginning of the environment initialization. This ensures that the environment creation is deterministic and behaves similarly across different runs.

sim_cfg: SimulationManagerCfg

Simulation configuration for the environment.

sim_steps_per_control: int

Number of simulation steps per control (env) step.

For instance, if the simulation dt is 0.01s and the control dt is 0.1s, then the sim_steps_per_control is 10. This means that the control action is updated every 10 simulation steps.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

Utilities Module (utils)

Registration System

class embodichain.lab.gym.utils.registration.EnvSpec

Bases: object

Specification class for environment registration, containing environment metadata and creation parameters. Methods:

__init__(uid, cls[, max_episode_steps, ...])

A specification for a Embodied environment.

Attributes:

gym_spec

Return a gym EnvSpec for this env

__init__(uid, cls, max_episode_steps=None, default_kwargs=None)

A specification for a Embodied environment.

property gym_spec

Return a gym EnvSpec for this env

embodichain.lab.gym.utils.registration.register(name, cls, max_episode_steps=None, default_kwargs=None)

Register a Embodied environment.

Register a new environment class with the EmbodiChain environment registry.

Parameters:

• name – Unique identifier for the environment

• cls – Environment class (must inherit from BaseEnv or BaseEnv)

• max_episode_steps – Maximum steps per episode (optional)

• default_kwargs – Default keyword arguments for environment creation

embodichain.lab.gym.utils.registration.register_env(uid, max_episode_steps=None, override=False, **kwargs)

A decorator to register Embodied environments.

Parameters:

• uid (str) – unique id of the environment.

• max_episode_steps (int) – maximum number of steps in an episode.

• override (bool) – whether to override the environment if it is already registered.

Notes

• max_episode_steps is processed differently from other keyword arguments in gym. gym.make wraps the env with gym.wrappers.TimeLimit to limit the maximum number of steps.

• gym.EnvSpec uses kwargs instead of **kwargs!

Decorator function for registering environment classes. This is the recommended way to register environments.

Parameters:

• uid – Unique identifier for the environment

• max_episode_steps – Maximum steps per episode (optional)

• override – Whether to override existing environment with same ID

• kwargs – Additional registration parameters

Example:

@register_env("MyEnv-v1", max_episode_steps=1000)
class MyCustomEnv(BaseEnv):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

embodichain.lab.gym.utils.registration.make(env_id, **kwargs)

Instantiate a Embodied environment.

Parameters:

• env_id (str) – Environment ID.

• as_gym (bool, optional) – Add TimeLimit wrapper as gym.

• **kwargs – Keyword arguments to pass to the environment.

Create an environment instance from a registered environment ID.

Parameters:

• env_id – Registered environment identifier

• kwargs – Additional keyword arguments for environment creation

Returns:

Environment instance

class embodichain.lab.gym.utils.registration.TimeLimitWrapper

Bases: Wrapper

like the standard gymnasium timelimit wrapper but fixes truncated variable to be a batched array

Gymnasium wrapper that adds episode time limits to environments. Methods:

__init__(env, max_episode_steps)	Wraps an environment to allow a modular transformation of the step() and reset() methods.
step(action)	Uses the step() of the env that can be overwritten to change the returned data.

__init__(env, max_episode_steps)

Wraps an environment to allow a modular transformation of the step() and reset() methods.

Parameters:

env (Env) – The environment to wrap

step(action)

Uses the step() of the env that can be overwritten to change the returned data.

Gymnasium Utilities

Helper functions and utilities for Gymnasium environment integration.

Miscellaneous Utilities

Miscellaneous utility functions for environment development and debugging.