embodichain.lab.sim.cfg#

Public simulation-configuration facade.

The implementation is split by domain while this package preserves the historical embodichain.lab.sim.cfg import surface.

Overview#

This module collects the @configclass configuration objects for everything that can be spawned into a simulation scene. It covers global simulation settings (rendering, physics, GPU memory, markers, window recording/camera), rigid-body / soft-body / cloth physical attributes and their overrides, joint drive properties, and the per-entity configs consumed by SimulationManager and the object factory in embodichain.lab.sim.utility.sim_utils.

Entity configs form a small inheritance hierarchy rooted at ObjectBaseCfg (LightCfg, VisualObjectCfg, RigidObjectCfg, VolumeDeformableObjectCfg, SurfaceDeformableObjectCfg, ArticulationCfg and its RobotCfg subclass), while URDFCfg and RigidConstraintCfg describe multi-component assembly and constraints. RobotPresetCfg provides replace-only complete robot alternatives when a backend-specific asset or actuator definition is unavoidable. Public backend selectors use only default and newton. Nested physical property groups may additionally use common for backend-neutral intent; DexSim names belong to the runtime and Spawn SDK adapter boundary. Surface deformables may keep a stable low-resolution simulation topology in shape while binding an independently indexed visual_shape for authored UV seams and render detail.

Type aliases

AssetPhysicsMode

alias of Literal['preserve', 'overlay']

DenoisingMode

alias of Literal['off', 'optix', 'dlss', 'nrd']

MeshCollisionApproximation

alias of Literal['convex_hull', 'convex_decomposition', 'triangle_mesh', 'sdf']

Classes

RenderCfg

RenderCfg(renderer: "Literal['auto', 'no-render', 'hybrid', 'fast-rt', 'rt']" = <factory>, spp: 'int' = <factory>, denoising: 'DenoisingCfg' = <factory>, dlss: 'DLSSCfg' = <factory>, nrd: 'NRDCfg' = <factory>, tone_mapping_enabled: 'bool' = <factory>, tone_mapping_exposure: 'float' = <factory>, min_bounces: 'int' = <factory>, max_bounces: 'int' = <factory>)

DenoisingCfg

Select denoising/reconstruction independently by rendering scope.

DLSSCfg

DLSS settings for the public dlss rendering path.

NRDCfg

Algorithm settings shared by targets that use the NRD path.

PhysicsBackendCfg

Backend-neutral simulation timing, device, and gravity configuration.

DefaultPhysicsCfg

Configuration selector for the Default physics backend.

NewtonPhysicsCfg

Configuration selector for the Newton physics backend.

NewtonCollisionPipelineCfg

Newton collision-pipeline settings owned at scene scope.

MarkerCfg

Configuration for visual markers in the simulation.

WindowRecordCfg

Configuration for interactive viewer window recording.

WindowCameraPoseCfg

Configuration for printing the interactive viewer camera pose.

GPUMemoryCfg

GPU buffer capacities for the Default backend's GPU dynamics pipeline.

MassPropertiesCfg

Backend-neutral rigid-body mass properties.

DefaultRigidBodyPropertiesCfg

Rigid-body properties consumed only by the Default backend.

CollisionPropertiesCfg

Collision-shape properties with identical intent across both backends.

DefaultCollisionPropertiesCfg

Collision-solver properties consumed only by the Default backend.

NewtonCollisionPropertiesCfg

Newton-native contact-envelope and particle-contact properties.

RigidBodyMaterialCfg

Common rigid-contact material intent.

NewtonRigidBodyMaterialCfg

Newton contact-material extensions.

MeshCollisionCfg

Collision-geometry construction for MeshCfg.

RigidBodyPhysicsCfg

Grouped rigid-body physics configuration used by Spawn.

ArticulationRootPropertiesCfg

Articulation-root properties shared by robot definitions.

LinkPhysicsOverrideCfg

Partial physics overlay for a selected set of articulation links.

VolumeDeformableMeshingCfg

Newton tetrahedralization and render-volume binding parameters.

VolumeDeformablePhysicsCfg

Volume density, elasticity, and optional Newton surface constraints.

SurfaceDeformablePhysicsCfg

Surface density, Newton surface elements, and optional mesh springs.

SurfaceElementPropertiesCfg

Newton surface triangle, bending, and aerodynamic properties.

JointDrivePropertiesCfg

Portable joint-drive and joint-dynamics properties.

NewtonJointDrivePropertiesCfg

Compatibility subtype for serialized Newton joint-drive configs.

ObjectBaseCfg

Base configuration for an asset in the simulation.

UsdSourceCfg

Select a typed asset from a source USD stage.

LightCfg

Configuration for a light asset in the simulation.

VisualObjectCfg

Configure a render-only object, without a rigid body or colliders.

RigidObjectCfg

Configuration for a rigid body asset in the simulation.

RigidObjectGroupCfg

Configuration for a rigid object group asset in the simulation.

RigidConstraintCfg

Configuration for a fixed constraint between two RigidObjects.

URDFCfg

Standalone configuration class for URDF assembly.

ArticulationCfg

Configuration for an articulation asset in the simulation.

RobotCfg

RobotCfg(uid: 'str | None' = <factory>, init_pos: 'tuple[float, float, float]' = <factory>, init_rot: 'tuple[float, float, float]' = <factory>, init_local_pose: 'np.ndarray | None' = <factory>, fpath: 'str' = <factory>, body_scale: 'tuple | list' = <factory>, compute_uv: 'bool' = <factory>, asset_physics_mode: 'AssetPhysicsMode' = <factory>, attrs: 'RigidBodyPhysicsCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, root_props: 'ArticulationRootPropertiesCfg' = <factory>, joint_drive_props: 'JointDrivePropertiesCfg' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[Sequence[float]] | Dict[str, List[float]] | None' = <factory>, build_pk_chain: 'bool' = <factory>, control_parts: 'Dict[str, List[str]] | None' = <factory>, urdf_cfg: 'URDFCfg | None' = <factory>, solver_cfg: 'SolverCfg | Dict[str, SolverCfg] | None' = <factory>, workspace_cfg: 'Dict[str, RobotWorkspaceCfg] | None' = <factory>, sensors: 'list[SensorCfg]' = <factory>, enable_sensor: 'bool' = <factory>, *, source: 'UsdSourceCfg | None' = None)

RobotPresetCfg

Base class for replace-only robot configurations across physics backends.

USD source selection#

UsdSourceCfg groups the source file and its optional exact source_prim_path. The path addresses an object inside the source USD stage; uid identifies the resulting runtime instance. Source selection does not set a destination path or attach the instance to a parent/link.

from embodichain.lab.sim.cfg import UsdSourceCfg, VisualObjectCfg

mug = VisualObjectCfg(
    uid="mug_visual",
    source=UsdSourceCfg(
        file_path="scene.usda",
        source_prim_path="/World/Props/Mug",
    ),
)

The same source configuration is supported by RigidObjectCfg and ArticulationCfg (including RobotCfg). Supply either source or the existing shape/fpath input. Ordinary mesh files continue to use MeshCfg(fpath=...). Without a selector, USD loading requires one candidate of the requested type; ambiguous sources fail instead of selecting the first object. Whole-scene imports preserve this source address on their facades.

Deformable physics and meshing#

Like RigidObjectCfg.attrs, deformable objects group physical intent under attrs. Volume objects keep mesh generation under meshing. Both physics configs share the seven Newton surface-element parameters through attrs.surface_props; volume coefficients default to zero, while cloth coefficients default to None (Newton defaults). Density remains topology specific: kg/m³ for volumes and kg/m² for surfaces.

class embodichain.lab.sim.cfg.VolumeDeformablePhysicsCfg[source]

Volume density, elasticity, and optional Newton surface constraints.

Methods:

__init__([youngs, poissons, ...])

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:

add_surface_edges

Whether Newton creates surface bending-edge constraints.

density

Volume density [kg/m³].

elasticity_damping

Volumetric damping coefficient forwarded as Newton k_damp.

poissons

Poisson's ratio; values approaching 0.5 resist volume change.

surface_props

Optional surface forces; all coefficients default to zero.

youngs

Young's modulus [Pa]; higher values make the volume stiffer.

__init__(youngs=<factory>, poissons=<factory>, elasticity_damping=<factory>, density=<factory>, surface_props=<factory>, add_surface_edges=<factory>)
add_surface_edges: bool

Whether Newton creates surface bending-edge constraints.

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.

density: float

Volume density [kg/m³].

elasticity_damping: float

Volumetric damping coefficient forwarded as Newton k_damp.

poissons: float

Poisson’s ratio; values approaching 0.5 resist volume change.

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.

surface_props: SurfaceElementPropertiesCfg

Optional surface forces; all coefficients default to zero.

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.

youngs: float

Young’s modulus [Pa]; higher values make the volume stiffer.

class embodichain.lab.sim.cfg.SurfaceDeformablePhysicsCfg[source]

Surface density, Newton surface elements, and optional mesh springs.

Methods:

__init__([density, surface_props, ...])

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:

add_springs

Whether Newton creates explicit mesh-edge springs.

density

Surface density [kg/m²].

spring_kd

Spring damping; None uses the Newton default.

spring_ke

Spring stiffness; None uses the Newton default.

surface_props

Triangle, bending, and aerodynamic overrides; None uses Newton defaults.

__init__(density=<factory>, surface_props=<factory>, add_springs=<factory>, spring_ke=<factory>, spring_kd=<factory>)
add_springs: bool

Whether Newton creates explicit mesh-edge springs.

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.

density: float

Surface density [kg/m²].

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.

spring_kd: float | None

Spring damping; None uses the Newton default.

spring_ke: float | None

Spring stiffness; None uses the Newton default.

surface_props: SurfaceElementPropertiesCfg

Triangle, bending, and aerodynamic overrides; None uses Newton defaults.

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.

class embodichain.lab.sim.cfg.SurfaceElementPropertiesCfg[source]

Newton surface triangle, bending, and aerodynamic properties.

None preserves Newton’s cloth defaults; volume objects resolve it to zero, matching their disabled-by-default surface forces.

Methods:

__init__([tri_ke, tri_ka, tri_kd, tri_drag, ...])

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:

edge_kd

Bending-edge damping.

edge_ke

Bending-edge stiffness.

tri_drag

Aerodynamic drag coefficient.

tri_ka

Triangle area stiffness.

tri_kd

Triangle damping.

tri_ke

Triangle elastic stiffness.

tri_lift

Aerodynamic lift coefficient.

__init__(tri_ke=<factory>, tri_ka=<factory>, tri_kd=<factory>, tri_drag=<factory>, tri_lift=<factory>, edge_ke=<factory>, edge_kd=<factory>)
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.

edge_kd: float | None

Bending-edge damping.

edge_ke: float | None

Bending-edge stiffness.

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.

tri_drag: float | None

Aerodynamic drag coefficient.

tri_ka: float | None

Triangle area stiffness.

tri_kd: float | None

Triangle damping.

tri_ke: float | None

Triangle elastic stiffness.

tri_lift: float | None

Aerodynamic lift coefficient.

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.

class embodichain.lab.sim.cfg.VolumeDeformableMeshingCfg[source]

Newton tetrahedralization and render-volume binding parameters.

Methods:

__init__([triangle_remesh_resolution, ...])

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:

embedding_impl

DexSim implementation used to bind render vertices to tetrahedra.

simulation_mesh_resolution

Voxel resolution used to build the tetrahedral simulation mesh.

triangle_remesh_resolution

Resolution used to remesh the source surface before tetrahedralization.

triangle_simplify_target

Target face count for the proxy surface; zero disables simplification.

voxel_num_relaxation_iters

Number of tetrahedral-mesh relaxation iterations.

voxel_rel_min_tet_volume

Minimum tetrahedron volume relative to the voxel volume.

voxel_surface_dist_ratio

Maximum surface distance expressed as a voxel-size ratio.

__init__(triangle_remesh_resolution=<factory>, triangle_simplify_target=<factory>, simulation_mesh_resolution=<factory>, voxel_num_relaxation_iters=<factory>, voxel_rel_min_tet_volume=<factory>, voxel_surface_dist_ratio=<factory>, embedding_impl=<factory>)
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.

embedding_impl: str

DexSim implementation used to bind render vertices to tetrahedra.

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.

simulation_mesh_resolution: int

Voxel resolution used to build the tetrahedral simulation mesh.

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.

triangle_remesh_resolution: int

Resolution used to remesh the source surface before tetrahedralization.

triangle_simplify_target: int

Target face count for the proxy surface; zero disables simplification.

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.

voxel_num_relaxation_iters: int

Number of tetrahedral-mesh relaxation iterations.

voxel_rel_min_tet_volume: float

Minimum tetrahedron volume relative to the voxel volume.

voxel_surface_dist_ratio: float

Maximum surface distance expressed as a voxel-size ratio.

Constructors and from_dict() accept only the current fields. Surface-element properties are grouped under attrs.surface_props. Volume elasticity uses youngs and poissons. Configuration dictionaries serialize this same schema; no legacy aliases or field migration are provided.

Rendering configuration module#

Rendering types live in embodichain.lab.sim.cfg.rendering. The public dlss path maps to DLSS Ray Reconstruction and nrd maps to standalone NRD RELAX.

DenoisingMode

Public ray-tracing denoising and reconstruction mode.

DenoisingCfg

Select denoising/reconstruction independently by rendering scope.

DLSSCfg

DLSS settings for the public dlss rendering path.

NRDCfg

Algorithm settings shared by targets that use the NRD path.

RenderCfg

RenderCfg(renderer: "Literal['auto', 'no-render', 'hybrid', 'fast-rt', 'rt']" = <factory>, spp: 'int' = <factory>, denoising: 'DenoisingCfg' = <factory>, dlss: 'DLSSCfg' = <factory>, nrd: 'NRDCfg' = <factory>, tone_mapping_enabled: 'bool' = <factory>, tone_mapping_exposure: 'float' = <factory>, min_bounces: 'int' = <factory>, max_bounces: 'int' = <factory>)

Physics configuration module#

Physics backend types live in embodichain.lab.sim.cfg.physics. The legacy embodichain.lab.sim.cfg.simulation module remains a compatibility facade. For manager-owned Newton steps, sync_to_renderer=None or False publishes only for visual consumers; True additionally requests publication on steps without consumers.

GPUMemoryCfg

GPU buffer capacities for the Default backend's GPU dynamics pipeline.

PhysicsBackendCfg

Backend-neutral simulation timing, device, and gravity configuration.

DefaultPhysicsCfg

Configuration selector for the Default physics backend.

NewtonCollisionPipelineCfg

Newton collision-pipeline settings owned at scene scope.

NewtonPhysicsCfg

Configuration selector for the Newton physics backend.

physics_cfg_for_backend(backend)

Return a default physics configuration instance for the given backend.

physics_backend_from_cfg(physics_cfg)

Infer the physics backend name from a physics configuration instance.

validate_physics_cfg(physics_cfg)

Validate that physics_cfg is a supported backend configuration.

Compatibility facade#

The historical embodichain.lab.sim.cfg.simulation module re-exports the rendering and physics configuration types for callers that have not migrated to the split modules.

DenoisingMode

alias of Literal['off', 'optix', 'dlss', 'nrd']

DenoisingCfg

Select denoising/reconstruction independently by rendering scope.

DLSSCfg

DLSS settings for the public dlss rendering path.

NRDCfg

Algorithm settings shared by targets that use the NRD path.

RenderCfg

RenderCfg(renderer: "Literal['auto', 'no-render', 'hybrid', 'fast-rt', 'rt']" = <factory>, spp: 'int' = <factory>, denoising: 'DenoisingCfg' = <factory>, dlss: 'DLSSCfg' = <factory>, nrd: 'NRDCfg' = <factory>, tone_mapping_enabled: 'bool' = <factory>, tone_mapping_exposure: 'float' = <factory>, min_bounces: 'int' = <factory>, max_bounces: 'int' = <factory>)

GPUMemoryCfg

GPU buffer capacities for the Default backend's GPU dynamics pipeline.

PhysicsBackendCfg

Backend-neutral simulation timing, device, and gravity configuration.

DefaultPhysicsCfg

Configuration selector for the Default physics backend.

NewtonCollisionPipelineCfg

Newton collision-pipeline settings owned at scene scope.

NewtonPhysicsCfg

Configuration selector for the Newton physics backend.

physics_cfg_for_backend(backend)

Return a default physics configuration instance for the given backend.

physics_backend_from_cfg(physics_cfg)

Infer the physics backend name from a physics configuration instance.

validate_physics_cfg(physics_cfg)

Validate that physics_cfg is a supported backend configuration.

Rigid-body property module#

The rigid-body configuration types are also available from embodichain.lab.sim.cfg.rigid. They describe mass, collision properties, materials, and backend-specific overrides. NewtonCollisionPropertiesCfg accepts an optional priority for MuJoCo contact-parameter selection; None preserves the source value.

MassPropertiesCfg

Backend-neutral rigid-body mass properties.

DefaultRigidBodyPropertiesCfg

Rigid-body properties consumed only by the Default backend.

CollisionPropertiesCfg

Collision-shape properties with identical intent across both backends.

DefaultCollisionPropertiesCfg

Collision-solver properties consumed only by the Default backend.

NewtonCollisionPropertiesCfg

Newton-native contact-envelope and particle-contact properties.

RigidBodyMaterialCfg

Common rigid-contact material intent.

NewtonRigidBodyMaterialCfg

Newton contact-material extensions.

RigidBodyPhysicsCfg

Grouped rigid-body physics configuration used by Spawn.