embodichain.lab.sim

embodichain.lab.sim#

EmbodiChain’s simulation core.

Organized around the SimulationManager (the DexSim scene handle), the scene-object hierarchy, sensors, IK solvers, motion planners, the atomic-action layer, and shared configuration types.

Overview#

The sim package is EmbodiChain’s simulation core. It is organized around the SimulationManager (the DexSim scene handle), the scene-object hierarchy (lights, rigid/soft/cloth bodies, articulations, robots, gizmos, constraints), the sensor suite (cameras, stereo cameras, contact sensors), the motion package for solvers, planners, workspace, and trajectory augmentation, the atomic-action motion-primitive layer, and the shared configuration types and utilities that wire all of these together.

Submodules

`sim_manager`
`profiler`	Lightweight hierarchical profiler shared by simulation and environments.
`cfg`	Public simulation-configuration facade.
`common`
`material`
`shapes`
`objects`	Scene-object classes spawned into the `SimulationManager`.
`robots`	Generic dual-arm composition; concrete presets live in embodichain_robots.
`sensors`	Sensors attached to the simulation scene.
`motion`	Robot motion solving, planning, workspace analysis, and trajectory augmentation.
`atomic_actions`	Typed planning contracts and built-in atomic actions.
`types`
`utility`	Helper utilities for simulation state conversion, mesh/geometry handling, configuration transforms, keyboard interaction, and action/solver adaptation.

Simulation Manager#

embodichain.lab.sim.sim_manager

Profiler#

class embodichain.lab.sim.Profiler[source]#

Bases: object

Hierarchical wall-time profiler.

Parameters:

cfg (Optional[ProfilerCfg]) – Profiler configuration. None disables profiling entirely.
device (device) – Device used for optional CUDA synchronization and NVTX ranges.

Note

One profiler tracks one synchronous call stack. Use it on the simulation thread that owns the associated simulation manager.

Methods:

`__init__`(cfg, device)
`report`()	Log a profiling report table and optionally dump JSON.
`section`(name, *[, is_root])	Record wall time for a named section.

Attributes:

enabled

Whether profiling is active.

__init__(cfg, device)[source]#

property enabled: bool#: Whether profiling is active.

report()[source]#

Log a profiling report table and optionally dump JSON.

Return type:: Dict[str, object]
Returns:: Report data, or an empty dictionary when profiling is disabled.

section(name, *, is_root=False)[source]#

Record wall time for a named section.

Parameters:

name (str) – Leaf section name. The full name is derived from the active section stack.
is_root (bool) – Whether this section starts a top-level profiling sample. A nested root is transparent and its children remain attached to the active outer hierarchy.

Return type:

Iterator[None]

class embodichain.lab.sim.ProfilerCfg[source]#

Bases: object

Configuration for hierarchical wall-time profiling.

Attributes:

`color_output`	Color terminal report rows by logical module.
`enable_time`	Enable per-section wall-time statistics (mean/min/max/std).
`nvtx`	Push NVTX ranges for sections so they appear in Nsight Systems.
`output_path`	Optional JSON path written by `Profiler.report()`.
`sync_cuda`	Synchronize CUDA at section boundaries for accurate GPU wall time.
`warmup_steps`	Number of top-level root sections to discard before recording.

color_output: bool#

Color terminal report rows by logical module.

This only affects the logged table; JSON report data remains unchanged.

enable_time: bool#: Enable per-section wall-time statistics (mean/min/max/std).

nvtx: bool#: Push NVTX ranges for sections so they appear in Nsight Systems.

output_path: str | None#: Optional JSON path written by Profiler.report().

sync_cuda: bool#: Synchronize CUDA at section boundaries for accurate GPU wall time.

warmup_steps: int#: Number of top-level root sections to discard before recording.

Configuration#

Public simulation-configuration facade.

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

Classes:

`ArticulationCfg`	Configuration for an articulation asset in the simulation.
`ArticulationRootPropertiesCfg`	Articulation-root properties shared by robot definitions.
`ClothObjectCfg`	alias of `SurfaceDeformableObjectCfg`
`CollisionPropertiesCfg`	Collision-shape properties with identical intent across both backends.
`DLSSCfg`	DLSS settings for the public `dlss` rendering path.
`DefaultCollisionPropertiesCfg`	Collision-solver properties consumed only by the Default backend.
`DefaultPhysicsCfg`	Configuration selector for the Default physics backend.
`DefaultRigidBodyPropertiesCfg`	Rigid-body properties consumed only by the Default backend.
`DeformableObjectCfg`	Common configuration contract for one deformable asset.
`DenoisingCfg`	Select denoising/reconstruction independently by rendering scope.
`GPUMemoryCfg`	GPU buffer capacities for the Default backend's GPU dynamics pipeline.
`JointDrivePropertiesCfg`	Portable joint-drive and joint-dynamics properties.
`LightCfg`	Configuration for a light asset in the simulation.
`LinkPhysicsOverrideCfg`	Partial physics overlay for a selected set of articulation links.
`MarkerCfg`	Configuration for visual markers in the simulation.
`MassPropertiesCfg`	Backend-neutral rigid-body mass properties.
`MeshCfg`	Configuration parameters for a triangle mesh shape.
`MeshCollisionCfg`	Collision-geometry construction for `MeshCfg`.
`NRDCfg`	Algorithm settings shared by targets that use the NRD path.
`NewtonCollisionPipelineCfg`	Newton collision-pipeline settings owned at scene scope.
`NewtonCollisionPropertiesCfg`	Newton-native contact-envelope and particle-contact properties.
`NewtonJointDrivePropertiesCfg`	Compatibility subtype for serialized Newton joint-drive configs.
`NewtonPhysicsCfg`	Configuration selector for the Newton physics backend.
`NewtonRigidBodyMaterialCfg`	Newton contact-material extensions.
`ObjectBaseCfg`	Base configuration for an asset in the simulation.
`PhysicsBackendCfg`	Backend-neutral simulation timing, device, and gravity configuration.
`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>)
`RigidBodyMaterialCfg`	Common rigid-contact material intent.
`RigidBodyPhysicsCfg`	Grouped rigid-body physics configuration used by Spawn.
`RigidConstraintCfg`	Configuration for a fixed constraint between two RigidObjects.
`RigidObjectCfg`	Configuration for a rigid body asset in the simulation.
`RigidObjectGroupCfg`	Configuration for a rigid object group 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.
`RobotWorkspaceCfg`	Runtime configuration for a control-part workspace cache.
`ShapeCfg`	ShapeCfg(shape_type: 'str' = <factory>, visual_material: 'VisualMaterialCfg \| None' = <factory>)
`SoftObjectCfg`	alias of `VolumeDeformableObjectCfg`
`SurfaceDeformableObjectCfg`	Configuration for a Newton surface-deformable particle set.
`SurfaceDeformablePhysicsCfg`	Surface density, Newton surface elements, and optional mesh springs.
`SurfaceElementPropertiesCfg`	Newton surface triangle, bending, and aerodynamic properties.
`URDFCfg`	Standalone configuration class for URDF assembly.
`UsdSourceCfg`	Select a typed asset from a source USD stage.
`VisualObjectCfg`	Configure a render-only object, without a rigid body or colliders.
`VolumeDeformableMeshingCfg`	Newton tetrahedralization and render-volume binding parameters.
`VolumeDeformableObjectCfg`	Configuration for a Newton volume-deformable particle set.
`VolumeDeformablePhysicsCfg`	Volume density, elasticity, and optional Newton surface constraints.
`WindowCameraPoseCfg`	Configuration for printing the interactive viewer camera pose.
`WindowRecordCfg`	Configuration for interactive viewer window recording.

Functions:

`get_data_path`(data_path_in_config)	Get the absolute path of the data file.
`link_attrs_from_dict`(value)	Parse a `link_attrs` mapping from YAML/JSON-style dicts.
`physics_backend_from_cfg`(physics_cfg)	Infer the physics backend name from a physics configuration instance.
`physics_cfg_for_backend`(backend)	Return a default physics configuration instance for the given backend.
`validate_physics_cfg`(physics_cfg)	Validate that `physics_cfg` is a supported backend configuration.

class embodichain.lab.sim.cfg.ArticulationCfg[source]#

Bases: ObjectBaseCfg

Configuration for an articulation asset in the simulation.

This class extends the base asset configuration to include specific properties for articulations, such as joint drive properties, physical attributes.

Attributes:

`asset_physics_mode`	How source-authored articulation physics is handled.
`attrs`	Physical attributes for all links.
`body_scale`	Scale of the articulation in the simulation world frame.
`build_pk_chain`	Build a pytorch-kinematics chain for FK and Jacobian computation.
`compute_uv`	Whether to compute the UV mapping for the articulation link.
`fpath`	Path to the articulation asset file.
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_qpos`	Initial joint positions of the articulation.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`joint_drive_props`	Optional joint-drive and joint-dynamics overrides.
`link_attrs`	Named per-link physics override groups keyed by regex on link names.
`qpos_limits`	Override joint position limits of the articulation.
`root_props`	Grouped articulation-root properties.
`source`	USD source asset; mutually exclusive with `fpath`.
`uid`

Methods:

`from_dict`(init_dict)	Initialize the configuration from a dictionary.
`resolve_asset_physics_mode`()	Return the effective file-backed physics policy.

asset_physics_mode: Literal['preserve', 'overlay']#

How source-authored articulation physics is handled.

"preserve" keeps link, joint-drive, and joint-limit properties from either USD or URDF. "overlay" applies only explicitly configured values after the source has been resolved.

Import policy such as root fixation and body scale remains controlled by root_props and body_scale.

attrs: RigidBodyPhysicsCfg#: Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: tuple | list#: Scale of the articulation in the simulation world frame.

build_pk_chain: bool#

Build a pytorch-kinematics chain for FK and Jacobian computation.

USD assets use resolved simulation joint descriptors after preparation; URDF assets use their source kinematic tree. USD kinematics supports trees of fixed, revolute, and prismatic joints, including child-side joint frames. Set False to load other joint topologies for simulation without FK.

compute_uv: bool#

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

fpath: str#: Path to the articulation asset file.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: ArticulationCfg

init_local_pose: ndarray | None#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_qpos: Union[Tensor, ndarray, Sequence[float]]#

Initial joint positions of the articulation.

If None, the joint positions will be set to zero. If provided, it should be an array of shape (num_dofs,).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

joint_drive_props: JointDrivePropertiesCfg | None#

Optional joint-drive and joint-dynamics overrides.

None preserves source drive properties. Individual None fields in a provided config also preserve the corresponding source values.

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None#

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

qpos_limits: Union[Tensor, ndarray, Sequence[Sequence[float]], Dict[str, List[float]], None]#

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_dofs, 2), it is applied in flattened source-resolved DOF order before the backend model is built. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

resolve_asset_physics_mode()[source]#

Return the effective file-backed physics policy.

Return type:: Literal['preserve', 'overlay']

root_props: ArticulationRootPropertiesCfg#

Grouped articulation-root properties.

Fixed-base and self-collision intent is portable. Root sleep and solver iterations are Default-only fields and are ignored by Newton. The portable fields default to a fixed base with self-collision disabled. Set either field to None to preserve an authored USD/backend value; URDF imports then use the established fixed-base, self-collision-off defaults.

source: UsdSourceCfg | None = None#: USD source asset; mutually exclusive with fpath.

uid: str | None#

class embodichain.lab.sim.cfg.ArticulationRootPropertiesCfg[source]#

Bases: object

Articulation-root properties shared by robot definitions.

fixed_base and self_collision_enabled are consumed by both backends. sleep_threshold and the solver-iteration fields are supported only by the Default backend and are ignored by Newton. By default, the articulation root is fixed and self-collision is disabled. Explicit None values preserve the source value or backend/import default.

Attributes:

`fixed_base`	Whether the articulation root is rigidly fixed to the world frame.
`min_position_iters`	Default-only minimum root position-solver iterations (1 to 255).
`min_velocity_iters`	Default-only minimum root velocity-solver iterations (0 to 255).
`self_collision_enabled`	Whether non-filtered link pairs in the articulation may self-collide.
`sleep_threshold`	Default-only articulation sleep threshold; Newton ignores this field.

Methods:

from_dict(init_dict)

Parse articulation-root properties without a backend subtype.

fixed_base: bool | None#

Whether the articulation root is rigidly fixed to the world frame.

Set to None to preserve the source value or backend/import default.

classmethod from_dict(init_dict)[source]#

Parse articulation-root properties without a backend subtype.

Return type:: ArticulationRootPropertiesCfg

min_position_iters: int | None#: Default-only minimum root position-solver iterations (1 to 255).

min_velocity_iters: int | None#: Default-only minimum root velocity-solver iterations (0 to 255).

self_collision_enabled: bool | None#

Whether non-filtered link pairs in the articulation may self-collide.

Newton may still apply source-authored or Spawn-owned filtering to adjacent parent-child bodies. Set to None to preserve the source value or backend/import default.

sleep_threshold: float | None#: Default-only articulation sleep threshold; Newton ignores this field.

embodichain.lab.sim.cfg.ClothObjectCfg#: alias of SurfaceDeformableObjectCfg

class embodichain.lab.sim.cfg.CollisionPropertiesCfg[source]#

Bases: object

Collision-shape properties with identical intent across both backends.

The framework default contact envelope is contact_offset=0.002 and rest_offset=0.0. The contact envelope is expressed once with Default-backend terminology and is compiled to Newton’s margin/gap representation at the Spawn boundary. Pass None explicitly for a sparse source-asset overlay. Mesh approximation and SDF cooking belong to MeshCollisionCfg.

Attributes:

`collision_enabled`	Whether the shape participates in rigid shape-shape collision.
`contact_offset`	Per-shape distance at which contact generation starts [m].
`rest_offset`	Per-shape target separation at rest [m].

collision_enabled: bool | None#

Whether the shape participates in rigid shape-shape collision.

On Newton this maps to ShapeConfig.has_shape_collision. None preserves the source/backend value.

contact_offset: float | None#

Per-shape distance at which contact generation starts [m].

The pair threshold is the sum of both shapes’ contact offsets. This value must be non-negative and no smaller than rest_offset. Default consumes it directly; Newton compiles it together with rest_offset to gap = contact_offset - rest_offset.

rest_offset: float | None#

Per-shape target separation at rest [m].

Pairwise rest separation is the sum of both shapes’ values. Positive values leave an air gap, zero targets touching surfaces, and negative values permit limited penetration. Default consumes it directly; Newton maps it to margin.

class embodichain.lab.sim.cfg.DLSSCfg[source]#

Bases: object

DLSS settings for the public dlss rendering path.

Pipeline selection belongs to DenoisingCfg. These controls apply when a target selects "dlss".

Attention

DLSS requires a Vulkan render device, a compatible NVIDIA GPU/driver, and a DexSim build with the NGX runtime. Initialization is deferred until rendering; configuration conversion alone cannot verify support. Each enabled offscreen camera needs its own temporal history and Vulkan exchange images, increasing GPU memory use.

Attributes:

`dlss_quality`	`-1` auto (58%), `0` Ultra Performance (~33%), `1` Performance (50%), `2` Balanced (58%), `3` Quality (~67%), `4` Ultra Quality (77%), `5` DLAA (100%).
`exposure_compensation`	Positive, finite exposure multiplier used by the RR bridge.
`render_height`	Internal FastRT/OfflineRT window height; zero derives it from quality.
`render_width`	Internal FastRT/OfflineRT window width; zero derives it from quality.
`target_height`	DexSim compatibility field.
`target_width`	DexSim compatibility field.
`tiled_enabled`	Evaluate compatible multi-camera targets through one tiled DLSS atlas.
`upsample_ratio`	Optional window target/render ratio, at least 1.0.

Methods:

to_dexsim_cfg(window_width, window_height)

Convert settings without changing the window or camera output size.

dlss_quality: int#

-1 auto (58%), 0 Ultra Performance (~33%), 1 Performance (50%), 2 Balanced (58%), 3 Quality (~67%), 4 Ultra Quality (77%), 5 DLAA (100%).

Type:: Quality mode and derived internal scale

exposure_compensation: float#: Positive, finite exposure multiplier used by the RR bridge.

render_height: int#: Internal FastRT/OfflineRT window height; zero derives it from quality.

render_width: int#: Internal FastRT/OfflineRT window width; zero derives it from quality.

target_height: int#: DexSim compatibility field. Set the actual window or camera height instead.

target_width: int#: DexSim compatibility field. Set the actual window or camera width instead.

tiled_enabled: bool#: Evaluate compatible multi-camera targets through one tiled DLSS atlas.

to_dexsim_cfg(window_width, window_height)[source]#

Convert settings without changing the window or camera output size.

Parameters:

window_width (int) – Window width in pixels.
window_height (int) – Window height in pixels.

Return type:

DLSSConfig

Returns:

Populated dexsim.DLSSConfig instance ready to assign to world_config.dlss_config.

Raises:

ValueError – If the configuration contains invalid values.

upsample_ratio: float | None#: Optional window target/render ratio, at least 1.0. None leaves zero render dimensions for DexSim to derive from quality. When specified, computes each unset render dimension from the actual window size. Only FastRT/OfflineRT windows honor these overrides; hybrid and offscreen targets derive their internal resolution from quality.

class embodichain.lab.sim.cfg.DefaultCollisionPropertiesCfg[source]#

Bases: CollisionPropertiesCfg

Collision-solver properties consumed only by the Default backend.

contact_offset and rest_offset are portable fields defined by CollisionPropertiesCfg. This backend extension keeps them sparse so a backend-native source overlay does not accidentally replace an authored portable envelope.

Attributes:

`collision_enabled`	Whether the shape participates in rigid shape-shape collision.
`contact_offset`	Optional portable contact-generation distance [m].
`disable_strong_friction`	Whether to disable Default-backend strong-friction contact anchoring.
`min_torsional_patch_radius`	Minimum contact-patch radius used for torsional friction [m].
`rest_offset`	Optional portable target separation at rest [m].
`torsional_patch_radius`	Contact-patch radius used to approximate torsional friction [m].

collision_enabled: bool | None#

Whether the shape participates in rigid shape-shape collision.

On Newton this maps to ShapeConfig.has_shape_collision. None preserves the source/backend value.

contact_offset: float | None#: Optional portable contact-generation distance [m].

disable_strong_friction: bool | None#: Whether to disable Default-backend strong-friction contact anchoring.

min_torsional_patch_radius: float | None#: Minimum contact-patch radius used for torsional friction [m].

rest_offset: float | None#: Optional portable target separation at rest [m].

torsional_patch_radius: float | None#: Contact-patch radius used to approximate torsional friction [m].

class embodichain.lab.sim.cfg.DefaultPhysicsCfg[source]#

Bases: PhysicsBackendCfg

Configuration selector for the Default physics backend.

Attributes:

`bounce_threshold`	Relative normal-speed threshold below which contacts do not bounce [m/s].
`cache_material`	Reuse identical physics materials across objects and environment clones.
`device`	Compute device used to build and step the selected physics backend.
`enable_ccd`	Whether to enable scene-level continuous collision detection (CCD).
`gpu_memory`	Fixed-capacity GPU buffers used by Default-backend CUDA simulation.
`gravity`	World-frame gravity vector in meters per second squared.
`length_tolerance`	Representative scene length used by the Default backend's tolerance scale [m].
`physics_dt`	Duration of one physics step in seconds.
`speed_tolerance`	Representative scene speed used by the Default backend's tolerance scale [m/s].

Methods:

to_dexsim_args()

Convert to DexSim physics arguments.

bounce_threshold: float#: Relative normal-speed threshold below which contacts do not bounce [m/s].

cache_material: bool#

Reuse identical physics materials across objects and environment clones.

Enable this for large batches to avoid exhausting the native material table.

device: str | device#

Compute device used to build and step the selected physics backend.

Concrete backend configurations may redeclare this field when their native runtime has a different default. In particular, NewtonPhysicsCfg intentionally shadows this CPU default with "cuda:0". Callers can still provide an explicit device override.

enable_ccd: bool#

Whether to enable scene-level continuous collision detection (CCD).

A rigid body must also set DefaultRigidBodyPropertiesCfg.enable_ccd for CCD to be used on that body.

gpu_memory: GPUMemoryCfg#: Fixed-capacity GPU buffers used by Default-backend CUDA simulation.

gravity: Union[Sequence[float], ndarray]#: World-frame gravity vector in meters per second squared.

length_tolerance: float#

Representative scene length used by the Default backend’s tolerance scale [m].

Set this near the characteristic size of simulated objects. It is a scene scale, not an accuracy knob, and must be configured before world creation.

physics_dt: float#

Duration of one physics step in seconds.

Environment control steps may contain multiple physics steps. For Newton, this interval is further divided by NewtonPhysicsCfg.num_substeps.

speed_tolerance: float#

Representative scene speed used by the Default backend’s tolerance scale [m/s].

The backend derives several internal thresholds from this value and length_tolerance.

to_dexsim_args()[source]#

Convert to DexSim physics arguments.

Solver implementation details that are not exposed by DefaultPhysicsCfg retain their established defaults here.

Return type:: dict[str, Any]

class embodichain.lab.sim.cfg.DefaultRigidBodyPropertiesCfg[source]#

Bases: object

Rigid-body properties consumed only by the Default backend.

Every field defaults to None so a partial overlay preserves an authored USD/URDF value or the backend default.

Attributes:

`angular_damping`	Non-negative damping coefficient applied to angular velocity.
`enable_ccd`	Whether continuous collision detection is enabled for this body.
`has_gravity`	Whether world gravity accelerates this body (Default backend only).
`linear_damping`	Non-negative damping coefficient applied to linear velocity.
`max_angular_velocity`	Maximum rigid-body angular speed [rad/s].
`max_depenetration_velocity`	Maximum separation speed introduced to resolve penetration [m/s].
`max_linear_velocity`	Maximum rigid-body linear speed [m/s].
`min_position_iters`	Minimum number of position-solver iterations for this body (1 to 255).
`min_velocity_iters`	Minimum number of velocity-solver iterations for this body (0 to 255).
`retain_acceleration`	Whether accumulated acceleration is retained across simulation steps.
`sleep_threshold`	Mass-normalized kinetic-energy threshold below which the body may sleep.

angular_damping: float | None#: Non-negative damping coefficient applied to angular velocity.

enable_ccd: bool | None#

Whether continuous collision detection is enabled for this body.

Scene-level CCD must also be enabled through DefaultPhysicsCfg.enable_ccd.

has_gravity: bool | None#

Whether world gravity accelerates this body (Default backend only).

None preserves source/backend intent. Articulation attrs applies to all links; link_attrs can override individual links. File-backed assets require asset_physics_mode="overlay" to apply this property. Explicit gravity overrides are rejected by the Newton integration.

linear_damping: float | None#: Non-negative damping coefficient applied to linear velocity.

max_angular_velocity: float | None#: Maximum rigid-body angular speed [rad/s].

max_depenetration_velocity: float | None#: Maximum separation speed introduced to resolve penetration [m/s].

max_linear_velocity: float | None#: Maximum rigid-body linear speed [m/s].

min_position_iters: int | None#: Minimum number of position-solver iterations for this body (1 to 255).

min_velocity_iters: int | None#: Minimum number of velocity-solver iterations for this body (0 to 255).

retain_acceleration: bool | None#: Whether accumulated acceleration is retained across simulation steps.

sleep_threshold: float | None#: Mass-normalized kinetic-energy threshold below which the body may sleep.

class embodichain.lab.sim.cfg.DeformableObjectCfg[source]#

Bases: ObjectBaseCfg

Common configuration contract for one deformable asset.

Concrete volume and surface configurations author Newton particle-set properties. The discriminator is explicit so manager and visualization code do not need to infer topology from a mesh or material type.

Attributes:

`deformable_type`	Physical topology represented by the asset.
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`particle_flags`	Newton particle flags, provided as one broadcast value or one value per node.
`particle_radius`	Newton particle radius; `None` uses the active solver default.
`shape`	Render and source-mesh configuration.
`uid`
`validate_mesh`	Whether Newton reports source-mesh quality validation warnings.

Methods:

from_dict(init_dict)

Parse nested deformable configs using the current schema.

deformable_type: Literal['volume', 'surface']#: Physical topology represented by the asset.

classmethod from_dict(init_dict)[source]#

Parse nested deformable configs using the current schema.

Parameters:: init_dict (Mapping[str, Any]) – Configuration fields from a dictionary or YAML loader.
Return type:: DeformableObjectCfg
Returns:: A typed configuration with the base asset pose conventions applied.

init_local_pose: ndarray | None#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

particle_flags: Union[int, Sequence[int], ndarray, None]#

Newton particle flags, provided as one broadcast value or one value per node.

Clear the Newton ACTIVE bit for nodes that will be driven kinematically. Per-node arrays must follow the resolved simulation-particle order. For a surface deformable, an array-backed MeshCfg preserves this order. A volume deformable is voxelized into a separate tetrahedral simulation mesh, so its particle indices do not correspond to source-mesh vertex indices.

particle_radius: float | None#: Newton particle radius; None uses the active solver default.

shape: MeshCfg#: Render and source-mesh configuration.

uid: str | None#

validate_mesh: bool#: Whether Newton reports source-mesh quality validation warnings.

class embodichain.lab.sim.cfg.DenoisingCfg[source]#

Bases: object

Select denoising/reconstruction independently by rendering scope.

The public values describe complete image-processing paths. Native NRD method variants remain an implementation detail instead of becoming additional user-facing modes.

Attributes:

`offscreen`	Pipeline used by offscreen camera targets.
`window`	Pipeline used by the interactive window.

Methods:

to_dexsim_modes()

Convert window and offscreen selections to DexSim modes.

offscreen: Literal['off', 'optix', 'dlss', 'nrd']#: Pipeline used by offscreen camera targets.

to_dexsim_modes()[source]#

Convert window and offscreen selections to DexSim modes.

Return type:: tuple[RTRenderMode, RTRenderMode]
Returns:: Window and offscreen modes, in that order.
Raises:: ValueError – If mutable settings no longer contain valid modes.

window: Literal['off', 'optix', 'dlss', 'nrd']#: Pipeline used by the interactive window.

class embodichain.lab.sim.cfg.GPUMemoryCfg[source]#

Bases: object

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

Default-backend GPU buffers cannot all grow dynamically. Values that are too small may therefore produce overflow warnings, dropped contacts, or an invalid simulation. These settings are applied only when the Default backend runs on CUDA; they have no effect on Default CPU or Newton.

Attributes:

`found_lost_aggregate_pairs_capacity`	Capacity of found/lost pair records generated by aggregates.
`found_lost_pairs_capacity`	Capacity of broad-phase found/lost pair records.
`heap_capacity`	Initial capacity in bytes of the GPU and pinned-host memory heaps.
`max_rigid_contact_count`	Maximum number of rigid-contact records in the GPU contact stream.
`max_rigid_patch_count`	Maximum number of rigid-contact patches in the GPU patch stream.
`temp_buffer_capacity`	Temporary pinned-host buffer capacity in bytes.
`total_aggregate_pairs_capacity`	Capacity of all aggregate-pair records in the GPU pipeline.

found_lost_aggregate_pairs_capacity: int#: Capacity of found/lost pair records generated by aggregates.

found_lost_pairs_capacity: int#: Capacity of broad-phase found/lost pair records.

heap_capacity: int#: Initial capacity in bytes of the GPU and pinned-host memory heaps.

max_rigid_contact_count: int#

Maximum number of rigid-contact records in the GPU contact stream.

Increase this when the Default backend reports Contact buffer overflow detected.

max_rigid_patch_count: int#

Maximum number of rigid-contact patches in the GPU patch stream.

A patch groups nearby contact points that share a contact normal. Increase this when the Default backend reports Patch buffer overflow detected.

temp_buffer_capacity: int#

Temporary pinned-host buffer capacity in bytes.

Increase this when the Default backend reports a pinned-host linear allocator overflow.

total_aggregate_pairs_capacity: int#: Capacity of all aggregate-pair records in the GPU pipeline.

class embodichain.lab.sim.cfg.JointDrivePropertiesCfg[source]#

Bases: object

Portable joint-drive and joint-dynamics properties.

A scalar applies to every resolved joint. A dictionary maps exact joint names, full-match regular expressions, or robot control-part names to values; exact/regex rules override broader control-part rules. None preserves source/backend ownership of a field.

drive_type retains the Default drive response (force, acceleration, or disabled), while target_mode selects the commanded target components. Spawn resolves the two concepts before lowering them to the Default drive descriptor and Newton JointDofConfig.

Effort and velocity limits, friction, and armature share the same matching rules and descriptor compilation boundary as the actuator target and gains.

Newton stores all fields in the model, but individual solvers may ignore limits, friction, armature, or target modes; consult the Newton solver feature matrix.

Attributes:

`armature`	Artificial inertia added to the joint-space diagonal.
`damping`	Derivative velocity gain of the joint drive.
`drive_type`	Joint drive type to apply.
`friction`	Passive friction value applied along the joint degree of freedom.
`max_effort`	Maximum drive effort [N for prismatic, N*m for revolute joints].
`max_velocity`	Maximum joint speed [m/s for prismatic, rad/s for revolute joints].
`stiffness`	Proportional position gain of the joint drive.
`target_mode`	Portable actuator target mode, as a scalar or joint-rule mapping.

Methods:

from_dict(init_dict, *[, defaults])

Initialize the configuration from a dictionary.

armature: Union[Dict[str, float], float, None]#

Artificial inertia added to the joint-space diagonal.

Units depend on the joint model:

For prismatic (linear) joints, the unit is mass [kg].
For revolute (angular) joints, the unit is mass * scene_length^2 [kg-m^2].

Armature changes the physical model and should normally reflect actuator or gearbox inertia. Newton solver support varies.

damping: Union[Dict[str, float], float, None]#

Derivative velocity gain of the joint drive.

The unit depends on the joint model:

For linear joints, the unit is kg-m/s (N-s/m).
For angular joints, the unit is kg-m^2/s/rad (N-m-s/rad).

drive_type: Optional[Literal['force', 'acceleration', 'none']]#

Joint drive type to apply.

On the Default backend, "force" applies a force/torque drive, "acceleration" applies a mass-independent acceleration drive, and "none" disables the drive. Newton has no acceleration-drive equivalent. Unless target_mode is explicit, "force" and "acceleration" select "position_velocity" while "none" selects "none".

friction: Union[Dict[str, float], float, None]#

Passive friction value applied along the joint degree of freedom.

Interpretation and enforcement are backend/solver-dependent.

classmethod from_dict(init_dict, *, defaults=None)[source]#

Initialize the configuration from a dictionary.

Parameters:

init_dict (Dict[str, Any]) – Joint-drive properties to override.
defaults (JointDrivePropertiesCfg | None) – Optional base properties whose unspecified values are preserved. If omitted, the class defaults are used.

Return type:

JointDrivePropertiesCfg

Returns:

Parsed joint-drive properties.

max_effort: Union[Dict[str, float], float, None]#

Maximum drive effort [N for prismatic, N*m for revolute joints].

The value is authored for both backends, but the selected Newton solver may not enforce it.

max_velocity: Union[Dict[str, float], float, None]#

Maximum joint speed [m/s for prismatic, rad/s for revolute joints].

The value is authored for both backends, but support is solver-dependent in Newton.

stiffness: Union[Dict[str, float], float, None]#

Proportional position gain of the joint drive.

The unit depends on the joint model:

For linear joints, the unit is kg-m/s^2 (N/m).
For angular joints, the unit is kg-m^2/s^2/rad (N-m/rad).

target_mode: Union[Literal['none', 'position', 'velocity', 'position_velocity', 'effort'], Dict[str, Union[Literal['none', 'position', 'velocity', 'position_velocity', 'effort'], int]], int, None]#

Portable actuator target mode, as a scalar or joint-rule mapping.

Accepted names and integer values are "none"/0 (passive), "position"/1, "velocity"/2, "position_velocity"/3, and "effort"/4. Default emulates these modes through its drive mode and effective gains. Newton authors the corresponding JointTargetMode; solvers without native target-mode support use deterministic gain-based fallbacks where possible.

class embodichain.lab.sim.cfg.LightCfg[source]#

Bases: ObjectBaseCfg

Configuration for a light asset in the simulation.

Supports six light types matching the dexsim rendering backend:

"point": Per-environment omnidirectional point light with position and falloff radius. Created as a batched light (one per environment).
"sun": Global directional sun light (infinite distance). Created as a single scene-level instance. Uses direction only; position is ignored. Sun-specific fields (angular_radius, halo_size, halo_falloff) are reserved for future backend support.
"direction": Global pure directional light at infinite distance. Created as a single scene-level instance. Direction only; no position.
"spot": Per-environment spotlight with position, direction, and inner/outer cone angles. Created as a batched light.
"rect": Per-environment rectangular area light with position, direction, width, and height. Created as a batched light.
"mesh": Per-environment mesh-based emissive light. Requires a MeshObject via embodichain.lab.sim.objects.light.Light.set_mesh() (not tensor-batched). Created as a batched light.

Attention

The angular_radius, halo_size, and halo_falloff fields are reserved for future use. The dexsim Python bindings do not yet expose setters for these sun-specific properties.

Attributes:

`angular_radius`	Angular radius of the sun disc in degrees.
`color`	RGB color of the light source.
`direction`	Direction vector for directional, spot, rect, and mesh lights.
`enable_shadow`	Whether the light casts shadows.
`halo_falloff`	Halo falloff for sun light.
`halo_size`	Halo size for sun light.
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`intensity`	Intensity of the light source in watts/m^2.
`light_type`	`"point"`, `"sun"`, `"direction"`, `"spot"`, `"rect"`, `"mesh"`.
`mesh_path`	Asset path for mesh-based emissive lights.
`radius`	Falloff radius for point lights.
`rect_height`	Height of the rectangular area light.
`rect_width`	Width of the rectangular area light.
`spot_angle_inner`	Inner cone angle of the spotlight in degrees.
`spot_angle_outer`	Outer cone angle of the spotlight in degrees.
`uid`

angular_radius: float#: Angular radius of the sun disc in degrees. Reserved for future use.

color: tuple[float, float, float]#: RGB color of the light source. Defaults to white (1.0, 1.0, 1.0).

direction: tuple[float, float, float]#: Direction vector for directional, spot, rect, and mesh lights. Defaults to (0.0, 0.0, -1.0) (pointing down along -Z).

enable_shadow: bool#: Whether the light casts shadows. Defaults to True.

halo_falloff: float#: Halo falloff for sun light. Reserved for future use.

halo_size: float#: Halo size for sun light. Reserved for future use.

init_local_pose: ndarray | None#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

intensity: float#: Intensity of the light source in watts/m^2. Defaults to 30.0.

light_type: Literal['point', 'sun', 'direction', 'spot', 'rect', 'mesh']#

"point", "sun", "direction", "spot", "rect", "mesh".

Type:: Light type. Supported

mesh_path: str#: Asset path for mesh-based emissive lights. Only used when light_type="mesh". The actual mesh assignment is done via embodichain.lab.sim.objects.light.Light.set_mesh() which accepts a dexsim.models.MeshObject. This field stores the path for reference.

radius: float#: Falloff radius for point lights. Only used when light_type="point". Defaults to 10.0.

rect_height: float#: Height of the rectangular area light. Only used when light_type="rect". Defaults to 1.0.

rect_width: float#: Width of the rectangular area light. Only used when light_type="rect". Defaults to 1.0.

spot_angle_inner: float#: Inner cone angle of the spotlight in degrees. Only used when light_type="spot". Defaults to 30.0.

spot_angle_outer: float#: Outer cone angle of the spotlight in degrees. Only used when light_type="spot". Defaults to 45.0.

uid: str | None#

class embodichain.lab.sim.cfg.LinkPhysicsOverrideCfg[source]#

Bases: object

Partial physics overlay for a selected set of articulation links.

Regex/control-group resolution happens before Spawn updates exact source link names. A link may match only one override group.

Attributes:

`attrs`	Partial grouped overlay for the selected links.
`link_names_expr`	Regular expressions matched against complete source link names.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

attrs: RigidBodyPhysicsCfg#

Partial grouped overlay for the selected links.

Configure source-inertia recomputation through RigidBodyPhysicsCfg.mass_props.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: LinkPhysicsOverrideCfg

link_names_expr: list[str]#: Regular expressions matched against complete source link names.

class embodichain.lab.sim.cfg.MarkerCfg[source]#

Bases: object

Configuration for visual markers in the simulation.

This class defines properties for creating visual markers such as coordinate frames, lines, and points that can be used for debugging, visualization, or reference purposes in the simulation environment.

Attributes:

`arena_index`	Index of the arena where the marker should be placed.
`arrow_type`	Type of arrow head for axis markers (e.g., CONE, ARROW, etc.).
`axis_len`	Length of each axis arm in meters.
`axis_size`	Thickness/size of the axis lines in meters.
`axis_xpos`	List of 4x4 transformation matrices defining the position and orientation of each axis marker.
`corner_type`	Type of corner/joint visualization for axis markers (e.g., SPHERE, CUBE, etc.).
`line_color`	RGBA color values for the marker lines.
`marker_type`	Type of marker to display.
`name`	Name of the marker for identification purposes.

arena_index: int#: Index of the arena where the marker should be placed. -1 means all arenas.

arrow_type: AxisArrowType#: Type of arrow head for axis markers (e.g., CONE, ARROW, etc.).

axis_len: float#: Length of each axis arm in meters.

axis_size: float#: Thickness/size of the axis lines in meters.

axis_xpos: Tensor | None#: List of 4x4 transformation matrices defining the position and orientation of each axis marker.

corner_type: AxisCornerType#: Type of corner/joint visualization for axis markers (e.g., SPHERE, CUBE, etc.).

line_color: List[float]#: RGBA color values for the marker lines. Values should be between 0.0 and 1.0.

marker_type: Literal['axis', 'line', 'point']#: Type of marker to display. Can be ‘axis’ (3D coordinate frame), ‘line’, or ‘point’. (only axis supported now)

name: str#: Name of the marker for identification purposes.

class embodichain.lab.sim.cfg.MassPropertiesCfg[source]#

Bases: object

Backend-neutral rigid-body mass properties.

None means that the source asset or selected backend keeps ownership of that value. For a non-static body, explicit inertia requires a positive mass. A source-backed body retains authored inertia unless recompute_inertia is enabled; procedural or recomputed bodies derive inertia from collision geometry and the effective mass or density. Static bodies omit all mass properties during Spawn compilation.

Attributes:

`com_position`	Center-of-mass position expressed in the rigid body's local frame [m].
`com_quaternion`	Orientation of the center-of-mass/inertia frame in `xyzw` order.
`density`	Uniform density used to derive mass properties from collision shapes [kg/m^3].
`inertia`	Inertia about the center of mass [kg*m^2].
`mass`	Rigid-body mass [kg].
`recompute_inertia`	Whether collision geometry should replace source-authored inertia.

com_position: Union[Sequence[float], ndarray, None]#: Center-of-mass position expressed in the rigid body’s local frame [m].

com_quaternion: Union[Sequence[float], ndarray, None]#

Orientation of the center-of-mass/inertia frame in xyzw order.

With three explicit principal moments, Spawn compiles R diag(I) R.T in body axes. With a full body-frame inertia matrix, the quaternion is ignored with a warning. Without explicit inertia it is rejected. A zero quaternion is invalid.

density: float | None#

Uniform density used to derive mass properties from collision shapes [kg/m^3].

The value must be positive and is ignored when mass is positive. For a source-backed body with valid authored inertia, set recompute_inertia to True when supplying density: deriving density-based properties necessarily replaces the source tensor.

inertia: Union[Sequence[float], ndarray, None]#

Inertia about the center of mass [kg*m^2].

Supply either three positive principal moments or a symmetric, positive-definite 3-by-3 tensor in the body frame. Explicit inertia is accepted only together with a positive mass. For one definition shared by both backends, either representation is supported. Principal moments plus com_quaternion are converted to a body-frame matrix before entering DexSim.

mass: float | None#

Rigid-body mass [kg].

A positive value takes precedence over density. Zero explicitly selects density-based derivation and therefore requires a positive density. Negative values are invalid.

recompute_inertia: bool | None#

Whether collision geometry should replace source-authored inertia.

True discards source inertia so the backend recomputes it from the collision geometry and effective mass or density. False preserves the source inertia. None inherits an outer rigid-body overlay and otherwise behaves like False. An invalid/all-zero source tensor is never preserved: when collision geometry exists, both backends use it as the common fallback. Explicit inertia cannot be combined with recomputation.

class embodichain.lab.sim.cfg.MeshCfg[source]#

Bases: ShapeCfg

Configuration parameters for a triangle mesh shape.

Attributes:

`collision`	Optional collision representation and cooking parameters.
`compute_uv`	Whether to compute UV coordinates for the shape.
`fpath`	File path to the shape mesh file.
`load_option`	Options for loading and processing the shape.
`normals`	Optional per-vertex normals with shape `(N, 3)`.
`project_direction`	Direction to project the UV coordinates.
`shape_type`	Type of the shape.
`triangles`	Optional array-backed triangle indices with shape `(M, 3)`.
`uv_coords`	Optional per-vertex texture coordinates with shape `(N, 2)`.
`vertices`	Optional array-backed mesh vertices with shape `(N, 3)`.
`visual_material`	Configuration parameters for the visual material of the shape.

collision: MeshCollisionCfg | None#

Optional collision representation and cooking parameters.

None uses a single convex hull. Mesh collision construction belongs to the geometry because it cannot be applied meaningfully to primitive shapes or to articulation links without a named source-shape overlay.

compute_uv: bool#

Whether to compute UV coordinates for the shape. Defaults to False.

If the shape already has UV coordinates, setting this to True will recompute and overwrite them.

fpath: str | None#

File path to the shape mesh file.

Provide either this path or both vertices and triangles.

load_option: LoadOption#: Options for loading and processing the shape.

normals: Union[Sequence[Sequence[float]], ndarray, None]#: Optional per-vertex normals with shape (N, 3).

project_direction: List[float]#: Direction to project the UV coordinates. Defaults to [1.0, 1.0, 1.0].

shape_type: str#: Type of the shape. Must be specified in subclasses.

triangles: Union[Sequence[Sequence[int]], ndarray, None]#: Optional array-backed triangle indices with shape (M, 3).

uv_coords: Union[Sequence[Sequence[float]], ndarray, None]#: Optional per-vertex texture coordinates with shape (N, 2).

vertices: Union[Sequence[Sequence[float]], ndarray, None]#

Optional array-backed mesh vertices with shape (N, 3).

Array-backed meshes preserve vertex order, which is useful when per-node deformable flags or kinematic trajectories refer to stable node indices.

visual_material: VisualMaterialCfg | None#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.cfg.MeshCollisionCfg[source]#

Bases: object

Collision-geometry construction for MeshCfg.

The approximation is explicit. Strategy-specific fields are rejected when they do not apply, so changing a numerical cooking value cannot silently select a different collision representation.

Attributes:

`acd_method`	Approximate-convex-decomposition implementation.
`approximation`	Collision representation built from the source triangle mesh.
`is_hydroelastic`	Whether Newton uses the generated SDF for hydroelastic contact.
`max_convex_hull_num`	Deprecated compatibility view of `max_hulls`.
`max_hulls`	Maximum hull count for `convex_decomposition`; must be at least two.
`sdf_narrow_band_range`	Inner and outer signed-distance limits of the Newton SDF band [m].
`sdf_padding`	Extra padding used while Newton builds the mesh SDF [m].
`sdf_resolution`	Maximum SDF grid resolution; valid only for the `sdf` strategy.
`sdf_target_voxel_size`	Target Newton sparse-SDF voxel size [m], alternative to resolution.
`sdf_texture_format`	Newton SDF voxel storage format.

Methods:

from_dict(init_dict)

Parse a mesh-collision mapping, including deprecated field names.

acd_method: Optional[Literal['visacd', 'coacd', 'vhacd']]#

Approximate-convex-decomposition implementation.

None selects visacd when compiling mesh collision geometry. VisACD requires a DexSim build with CUDA/OptiX support.

approximation: Literal['convex_hull', 'convex_decomposition', 'triangle_mesh', 'sdf']#: Collision representation built from the source triangle mesh.

classmethod from_dict(init_dict)[source]#

Parse a mesh-collision mapping, including deprecated field names.

Return type:: MeshCollisionCfg

is_hydroelastic: bool | None#: Whether Newton uses the generated SDF for hydroelastic contact.

property max_convex_hull_num: int#: Deprecated compatibility view of max_hulls.

max_hulls: int | None#: Maximum hull count for convex_decomposition; must be at least two.

sdf_narrow_band_range: tuple[float, float] | None#: Inner and outer signed-distance limits of the Newton SDF band [m].

sdf_padding: float | None#: Extra padding used while Newton builds the mesh SDF [m].

sdf_resolution: int | None#: Maximum SDF grid resolution; valid only for the sdf strategy.

sdf_target_voxel_size: float | None#: Target Newton sparse-SDF voxel size [m], alternative to resolution.

sdf_texture_format: Optional[Literal['uint16', 'float32', 'uint8']]#: Newton SDF voxel storage format.

class embodichain.lab.sim.cfg.NRDCfg[source]#

Bases: object

Algorithm settings shared by targets that use the NRD path.

Pipeline selection belongs to DenoisingCfg. This class only owns NRD tuning values and intentionally does not expose RELAX/REBLUR selection.

The fields are grouped by how directly they affect the current public nrd path (standalone NRD RELAX): history/disocclusion controls and the post-NRD TAA controls are active-path settings. Reblur-specific blur, stabilization, and anti-lag controls are retained for native parity but can be deferred from a smaller public configuration surface because the current EmbodiChain mode does not select NRD REBLUR. Validation is a debug feature, and SH/SG mode only has an effect on RELAX with FastRT or OfflineRT.

Attributes:

`anti_firefly_enabled`	Suppress isolated bright history samples; may darken sparse highlights.
`antilag_luminance_sensitivity`	REBLUR Anti-Lag luminance sensitivity; inactive for standalone RELAX.
`antilag_luminance_sigma_scale`	REBLUR Anti-Lag luminance sigma scale; inactive for standalone RELAX.
`denoising_range`	Maximum world-space range considered by NRD's denoising passes.
`diffuse_prepass_blur_radius`	Diffuse prepass blur radius; larger values reduce noise and soften detail.
`disocclusion_threshold`	Base view-depth threshold used to reject invalid temporal history.
`disocclusion_threshold_alternate`	Alternate depth threshold for pixels selecting the mixed threshold.
`disocclusion_threshold_mix_enabled`	Use the per-pixel threshold-mix input for thin or transparent geometry.
`history_confidence_enabled`	Generate paired-history confidence from matched probe renders.
`history_confidence_probe_stride`	Full-resolution spacing of paired-history probe rays; native range is 1–8.
`history_confidence_sensitivity`	Sensitivity used when converting history gradients into confidence.
`history_confidence_sigma_scale`	Sigma scale used when converting history gradients into confidence.
`history_fix_frame_num`	Number of frames used to repair history after a disocclusion.
`max_accumulated_frame_num`	Maximum slow temporal history length for RELAX and REBLUR.
`max_blur_radius`	Maximum adaptive blur radius for REBLUR; inactive for standalone RELAX.
`max_fast_accumulated_frame_num`	Maximum fast temporal history length used while a pixel is changing.
`max_indirect_bounces`	Number of indirect continuation rays after the primary surface.
`max_stabilized_frame_num`	Maximum stabilized history for REBLUR; inactive for standalone RELAX.
`min_blur_radius`	Minimum adaptive blur radius for REBLUR; inactive for standalone RELAX.
`sh_mode_enabled`	Enable RELAX directional SH/SG signals on FastRT and OfflineRT paths.
`specular_prepass_blur_radius`	Specular prepass blur radius; mainly an advanced REBLUR tuning knob.
`taa_depth_rejection_enabled`	Reject post-NRD history when reprojected view depth does not match.
`taa_min_current_weight`	Minimum current-frame weight in the post-NRD temporal resolve.
`taa_sigma_scale`	Sigma scale used by the post-NRD temporal resolve.
`taa_tone_mapping_enabled`	Apply NRD's optional tone mapping before the final EmbodiChain output.
`validation_enabled`	Enable NRD validation diagnostics; intended for development builds.

Methods:

to_dexsim_cfg()

Convert the settings to DexSim's native NRD configuration.

anti_firefly_enabled: bool#: Suppress isolated bright history samples; may darken sparse highlights.

antilag_luminance_sensitivity: float#: REBLUR Anti-Lag luminance sensitivity; inactive for standalone RELAX.

antilag_luminance_sigma_scale: float#: REBLUR Anti-Lag luminance sigma scale; inactive for standalone RELAX.

denoising_range: float#: Maximum world-space range considered by NRD’s denoising passes.

diffuse_prepass_blur_radius: float#: Diffuse prepass blur radius; larger values reduce noise and soften detail.

disocclusion_threshold: float#: Base view-depth threshold used to reject invalid temporal history.

disocclusion_threshold_alternate: float#: Alternate depth threshold for pixels selecting the mixed threshold.

disocclusion_threshold_mix_enabled: bool#: Use the per-pixel threshold-mix input for thin or transparent geometry.

history_confidence_enabled: bool#: Generate paired-history confidence from matched probe renders.

history_confidence_probe_stride: int#: Full-resolution spacing of paired-history probe rays; native range is 1–8.

history_confidence_sensitivity: float#: Sensitivity used when converting history gradients into confidence.

history_confidence_sigma_scale: float#: Sigma scale used when converting history gradients into confidence.

history_fix_frame_num: int#: Number of frames used to repair history after a disocclusion.

max_accumulated_frame_num: int#: Maximum slow temporal history length for RELAX and REBLUR.

max_blur_radius: float#: Maximum adaptive blur radius for REBLUR; inactive for standalone RELAX.

max_fast_accumulated_frame_num: int#: Maximum fast temporal history length used while a pixel is changing.

max_indirect_bounces: int#

Number of indirect continuation rays after the primary surface.

Higher values increase lighting detail and ray cost; NRD’s real-time default is one continuation bounce.

max_stabilized_frame_num: int#: Maximum stabilized history for REBLUR; inactive for standalone RELAX.

min_blur_radius: float#: Minimum adaptive blur radius for REBLUR; inactive for standalone RELAX.

sh_mode_enabled: bool#: Enable RELAX directional SH/SG signals on FastRT and OfflineRT paths.

specular_prepass_blur_radius: float#: Specular prepass blur radius; mainly an advanced REBLUR tuning knob.

taa_depth_rejection_enabled: bool#: Reject post-NRD history when reprojected view depth does not match.

taa_min_current_weight: float#: Minimum current-frame weight in the post-NRD temporal resolve.

taa_sigma_scale: float#: Sigma scale used by the post-NRD temporal resolve.

taa_tone_mapping_enabled: bool#: Apply NRD’s optional tone mapping before the final EmbodiChain output.

to_dexsim_cfg()[source]#

Convert the settings to DexSim’s native NRD configuration.

Return type:: NRDConfig
Returns:: Populated dexsim.NRDConfig.
Raises:: ValueError – If mutable settings no longer contain valid values.

validation_enabled: bool#: Enable NRD validation diagnostics; intended for development builds.

class embodichain.lab.sim.cfg.NewtonCollisionPipelineCfg[source]#

Bases: object

Newton collision-pipeline settings owned at scene scope.

Construction values map to DexSim’s NewtonCollisionPipelineCfg. update_interval controls the DexSim-side scheduling of that external pipeline. Per-shape contact and SDF values belong to NewtonCollisionPropertiesCfg instead. The pipeline performs broad-phase pair selection, narrow-phase contact generation, and optional contact reduction for the complete scene.

See the Newton collision guide for the native pipeline semantics.

Attributes:

`broad_phase`	Built-in broad-phase mode or a prebuilt Newton broad-phase object.
`max_triangle_pairs`	Maximum triangle-pair candidates allocated by the narrow phase.
`narrow_phase`	Optional prebuilt Newton narrow-phase object for expert pipelines.
`reduce_contacts`	Whether to reduce dense mesh contacts to a representative subset.
`rigid_contact_max`	Maximum number of allocated rigid contacts.
`sdf_hydroelastic_config`	Optional Newton `HydroelasticSDF.Config`-compatible object.
`shape_pairs_filtered`	Optional precomputed pairs for `"explicit"` broad phase.
`soft_contact_margin`	Particle/soft contact detection distance [m].
`soft_contact_max`	Maximum number of allocated particle/soft contacts.
`update_interval`	External-pipeline updates within one EmbodiChain physics step.

broad_phase: Union[Literal['nxn', 'sap', 'explicit'], Any, None]#

Built-in broad-phase mode or a prebuilt Newton broad-phase object.

"explicit" tests precomputed pairs, "nxn" performs an all-pairs test, and "sap" uses sweep-and-prune. None keeps Newton’s default. A prebuilt object is an expert path and must be compatible with narrow_phase.

max_triangle_pairs: int#

Maximum triangle-pair candidates allocated by the narrow phase.

Increase this only when complex meshes or heightfields report triangle-pair overflow. EmbodiChain intentionally uses a larger default than upstream Newton for mesh-heavy robotics scenes.

narrow_phase: Any | None#: Optional prebuilt Newton narrow-phase object for expert pipelines.

reduce_contacts: bool#

Whether to reduce dense mesh contacts to a representative subset.

Reduction lowers contact count and usually improves performance and solver stability for mesh-heavy scenes.

rigid_contact_max: int | None#

Maximum number of allocated rigid contacts.

None uses the model-provided capacity when available and otherwise lets Newton estimate it from the scene’s shapes and candidate pairs.

sdf_hydroelastic_config: Any | None#

Optional Newton HydroelasticSDF.Config-compatible object.

None disables the hydroelastic pipeline. Individual participating procedural meshes must also opt in through is_hydroelastic.

shape_pairs_filtered: Any | None#

Optional precomputed pairs for "explicit" broad phase.

When provided, this must be a Warp array of shape-index pairs with dtype=wp.vec2i. None uses the model’s contact-pair list.

soft_contact_margin: float#: Particle/soft contact detection distance [m].

soft_contact_max: int | None#

Maximum number of allocated particle/soft contacts.

None lets Newton derive the capacity from shape and particle counts.

update_interval: int | None#

External-pipeline updates within one EmbodiChain physics step.

The default 1 updates before every solver substep. An integer k >= 1 updates at substeps 0, k, 2k, ...; None updates once at the first solver substep of each physics step.

class embodichain.lab.sim.cfg.NewtonCollisionPropertiesCfg[source]#

Bases: CollisionPropertiesCfg

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

Mesh construction belongs to MeshCfg.collision; filtering, visual, and semantic-site policies are deliberately not part of rigid-body physics. Its portable fields remain sparse so a Newton-native source overlay can modify only the requested native properties.

See Newton Shape Configuration.

Attributes:

`collision_enabled`	Whether the shape participates in rigid shape-shape collision.
`condim`	1, 3, 4, or 6.
`contact_offset`	Optional portable contact-generation distance [m].
`gap`	Additional contact-detection distance outside `margin` [m].
`has_particle_collision`	Whether Newton particles collide with this shape.
`margin`	Outward collision-surface offset [m].
`priority`	MuJoCo contact-parameter priority; None preserves the source value.
`rest_offset`	Optional portable target separation at rest [m].

collision_enabled: bool | None#

Whether the shape participates in rigid shape-shape collision.

On Newton this maps to ShapeConfig.has_shape_collision. None preserves the source/backend value.

condim: int | None#

1, 3, 4, or 6.

None preserves the source/backend value (normally 3). Use 4 on gripping surfaces to include torsional friction, or 6 when rolling friction is also required. Author before scene preparation so MuJoCo can allocate the corresponding constraint storage.

Type:: MuJoCo contact dimension

contact_offset: float | None#: Optional portable contact-generation distance [m].

gap: float | None#

Additional contact-detection distance outside margin [m].

Gaps from both shapes are added. Broad phase expands each shape by margin + gap; increasing the gap detects approaching contact earlier.

has_particle_collision: bool | None#

Whether Newton particles collide with this shape.

None preserves the source/backend value. This controls deformable contact participation; scene-level collision isolation remains scene-owned.

margin: float | None#

Outward collision-surface offset [m].

Margins from both shapes are added. They determine where contact is placed and also affect inertia/SDF handling for hollow shapes.

priority: int | None#: MuJoCo contact-parameter priority; None preserves the source value.

rest_offset: float | None#: Optional portable target separation at rest [m].

class embodichain.lab.sim.cfg.NewtonJointDrivePropertiesCfg[source]#

Bases: JointDrivePropertiesCfg

Compatibility subtype for serialized Newton joint-drive configs.

target_mode is now portable and lives on JointDrivePropertiesCfg. The subtype remains so existing backend="newton" dictionaries and round trips retain their type; new robot definitions should use the common class.

Attributes:

`armature`	Artificial inertia added to the joint-space diagonal.
`damping`	Derivative velocity gain of the joint drive.
`drive_type`	Joint drive type to apply.
`friction`	Passive friction value applied along the joint degree of freedom.
`max_effort`	Maximum drive effort [N for prismatic, N*m for revolute joints].
`max_velocity`	Maximum joint speed [m/s for prismatic, rad/s for revolute joints].
`stiffness`	Proportional position gain of the joint drive.
`target_mode`	Portable actuator target mode, as a scalar or joint-rule mapping.

armature: Union[Dict[str, float], float, None]#

Artificial inertia added to the joint-space diagonal.

Units depend on the joint model:

For prismatic (linear) joints, the unit is mass [kg].
For revolute (angular) joints, the unit is mass * scene_length^2 [kg-m^2].

Armature changes the physical model and should normally reflect actuator or gearbox inertia. Newton solver support varies.

damping: Union[Dict[str, float], float, None]#

Derivative velocity gain of the joint drive.

The unit depends on the joint model:

For linear joints, the unit is kg-m/s (N-s/m).
For angular joints, the unit is kg-m^2/s/rad (N-m-s/rad).