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
|
alias of |
|
alias of |
|
alias of |
Classes
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>) |
|
Select denoising/reconstruction independently by rendering scope. |
|
DLSS settings for the public |
|
Algorithm settings shared by targets that use the NRD path. |
|
Backend-neutral simulation timing, device, and gravity configuration. |
|
Configuration selector for the Default physics backend. |
|
Configuration selector for the Newton physics backend. |
|
Newton collision-pipeline settings owned at scene scope. |
|
Configuration for visual markers in the simulation. |
|
Configuration for interactive viewer window recording. |
|
Configuration for printing the interactive viewer camera pose. |
|
GPU buffer capacities for the Default backend's GPU dynamics pipeline. |
|
Backend-neutral rigid-body mass properties. |
|
Rigid-body properties consumed only by the Default backend. |
|
Collision-shape properties with identical intent across both backends. |
|
Collision-solver properties consumed only by the Default backend. |
|
Newton-native contact-envelope and particle-contact properties. |
|
Common rigid-contact material intent. |
|
Newton contact-material extensions. |
|
Collision-geometry construction for |
|
Grouped rigid-body physics configuration used by Spawn. |
|
Articulation-root properties shared by robot definitions. |
|
Partial physics overlay for a selected set of articulation links. |
|
Newton tetrahedralization and render-volume binding parameters. |
|
Volume density, elasticity, and optional Newton surface constraints. |
|
Surface density, Newton surface elements, and optional mesh springs. |
|
Newton surface triangle, bending, and aerodynamic properties. |
|
Portable joint-drive and joint-dynamics properties. |
|
Compatibility subtype for serialized Newton joint-drive configs. |
|
Base configuration for an asset in the simulation. |
|
Select a typed asset from a source USD stage. |
|
Configuration for a light asset in the simulation. |
|
Configure a render-only object, without a rigid body or colliders. |
|
Configuration for a rigid body asset in the simulation. |
|
Configuration for a rigid object group asset in the simulation. |
|
Configuration for a fixed constraint between two RigidObjects. |
|
Standalone configuration class for URDF assembly. |
|
Configuration for an articulation asset in the simulation. |
|
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) |
|
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:
Whether Newton creates surface bending-edge constraints.
Volume density [kg/m³].
Volumetric damping coefficient forwarded as Newton
k_damp.Poisson's ratio; values approaching 0.5 resist volume change.
Optional surface forces; all coefficients default to zero.
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:
Whether Newton creates explicit mesh-edge springs.
Surface density [kg/m²].
Spring damping;
Noneuses the Newton default.Spring stiffness;
Noneuses the Newton default.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;
Noneuses the Newton default.
-
spring_ke:
float|None Spring stiffness;
Noneuses 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.
Nonepreserves 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:
Bending-edge damping.
Bending-edge stiffness.
Aerodynamic drag coefficient.
Triangle area stiffness.
Triangle damping.
Triangle elastic stiffness.
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:
DexSim implementation used to bind render vertices to tetrahedra.
Voxel resolution used to build the tetrahedral simulation mesh.
Resolution used to remesh the source surface before tetrahedralization.
Target face count for the proxy surface; zero disables simplification.
Number of tetrahedral-mesh relaxation iterations.
Minimum tetrahedron volume relative to the voxel volume.
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.
|
Public ray-tracing denoising and reconstruction mode. |
Select denoising/reconstruction independently by rendering scope. |
|
DLSS settings for the public |
|
Algorithm settings shared by targets that use the NRD path. |
|
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.
GPU buffer capacities for the Default backend's GPU dynamics pipeline. |
|
Backend-neutral simulation timing, device, and gravity configuration. |
|
Configuration selector for the Default physics backend. |
|
Newton collision-pipeline settings owned at scene scope. |
|
Configuration selector for the Newton physics backend. |
|
|
Return a default physics configuration instance for the given backend. |
|
Infer the physics backend name from a physics configuration instance. |
|
Validate that |
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.
|
alias of |
|
Select denoising/reconstruction independently by rendering scope. |
|
DLSS settings for the public |
|
Algorithm settings shared by targets that use the NRD path. |
|
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>) |
|
GPU buffer capacities for the Default backend's GPU dynamics pipeline. |
|
Backend-neutral simulation timing, device, and gravity configuration. |
|
Configuration selector for the Default physics backend. |
|
Newton collision-pipeline settings owned at scene scope. |
|
Configuration selector for the Newton physics backend. |
|
Return a default physics configuration instance for the given backend. |
|
Infer the physics backend name from a physics configuration instance. |
|
Validate that |
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.
Backend-neutral rigid-body mass properties. |
|
Rigid-body properties consumed only by the Default backend. |
|
Collision-shape properties with identical intent across both backends. |
|
Collision-solver properties consumed only by the Default backend. |
|
Newton-native contact-envelope and particle-contact properties. |
|
Common rigid-contact material intent. |
|
Newton contact-material extensions. |
|
Grouped rigid-body physics configuration used by Spawn. |