Default Physics Backend

Default Physics Backend#

The Default backend provides CPU and GPU simulation through DexSim. Its default solver is displayed as Constraint Dynamics. Select it with DefaultPhysicsCfg, or physics: default in a Gym configuration. See Physics for the shared capability matrix, device selection, and time-step definitions.

Minimal simulation#

This example declares one falling cube, prepares the scene, and advances 100 physics steps. Set device="cuda:0" to use the GPU path on a compatible installation. CPU physics still uses the normal DexSim runtime; rendering requirements are described in Installation.

from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
from embodichain.lab.sim.cfg import DefaultPhysicsCfg, RigidObjectCfg
from embodichain.lab.sim.shapes import CubeCfg


def run() -> None:
    sim = SimulationManager(
        SimulationManagerCfg(
            headless=True,
            physics_cfg=DefaultPhysicsCfg(device="cpu", physics_dt=0.01),
        )
    )
    try:
        cube = sim.add_rigid_object(
            RigidObjectCfg(
                uid="cube",
                shape=CubeCfg(size=[0.1, 0.1, 0.1]),
                body_type="dynamic",
                init_pos=(0.0, 0.0, 0.5),
            )
        )
        sim.prepare()
        for _ in range(100):
            sim.update(step=1)
    finally:
        sim.destroy(exit_process=False)


try:
    run()
finally:
    # Flush after run() releases its local scene/object references.
    SimulationManager.flush_cleanup_queue()

To run this same scene with Newton, import NewtonPhysicsCfg and replace the physics_cfg value with the configuration in Newton Physics Backend. Asset declaration, preparation, and explicit stepping retain the same structure.

Scene parameters#

Parameter	Default	Meaning and tuning guidance
`physics_dt`	`0.01`	Physics-step duration in seconds; coordinate changes with the control period.
`device`	`"cpu"`	CPU execution; `"cuda:0"` selects GPU execution.
`gravity`	`[0.0, 0.0, -9.81]`	World-frame acceleration in m/s².
`bounce_threshold`	`2.0`	Relative normal-speed threshold in m/s below which contacts do not bounce.
`enable_ccd`	`False`	Scene-level continuous collision detection; participating rigid bodies must also enable CCD.
`length_tolerance`	`0.05`	Representative scene length in metres, usually near the characteristic object size.
`speed_tolerance`	`0.25`	Representative scene speed in m/s; contributes to internal thresholds with the length scale.
`gpu_memory`	`GPUMemoryCfg()`	GPU capacities below; applies only to Default CUDA execution.

Set the tolerance scales before constructing the manager. These represent the scene’s scale; increasing them is not a general accuracy or performance control.

The current integration uses Constraint Dynamics with PCM, disables enhanced determinism, and evaluates friction on every solver iteration. These choices are not selectable fields of DefaultPhysicsCfg. The startup summary reports the runtime’s selected solver as Constraint Dynamics or PGS. Do not copy an upstream framework’s solver_type setting into this configuration.

CCD and articulation properties#

For a body that needs continuous collision detection, set both DefaultPhysicsCfg(enable_ccd=True) and attrs.rigid_props=DefaultRigidBodyPropertiesCfg(enable_ccd=True) on its rigid-body physics configuration. Validate the intended CPU/GPU path with a fast-moving-body example; the scene switch alone does not opt every body in.

Articulation root properties are configured separately with ArticulationRootPropertiesCfg. Root min_position_iters and min_velocity_iters must be specified together; these and sleep_threshold are Default-only. Root iteration settings apply before GPU buffer preparation. They are distinct from per-link DefaultRigidBodyPropertiesCfg settings. See Articulation for source preservation and joint drives.

GPU memory capacities#

Some Default GPU buffers have fixed capacities. Overflow can produce warnings, missing contacts, or invalid simulation results. Size them against the largest scene and worst-case randomized contact configuration, including all arenas.

`gpu_memory` field	Default	Capacity / response to overflow
`temp_buffer_capacity`	`2**24`	Bytes of temporary pinned-host storage; increase for linear allocator overflow.
`max_rigid_contact_count`	`2**19`	Rigid contact records; increase for contact-buffer overflow.
`max_rigid_patch_count`	`2**18`	Contact patches; increase for patch-buffer overflow.
`heap_capacity`	`2**26`	Initial GPU and pinned-host heap bytes.
`found_lost_pairs_capacity`	`2**25`	Broad-phase found/lost pair records.
`found_lost_aggregate_pairs_capacity`	`2**10`	Found/lost aggregate-pair records.
`total_aggregate_pairs_capacity`	`2**10`	Aggregate-pair records in the GPU pipeline.

These fields have no effect on Default CPU or Newton. Newton contact and constraint budgets belong to its selected solver or collision pipeline, so capacity values cannot be transferred directly between backends.

Contacts and validation#

ContactSensor works on Default CPU and GPU. The two paths differ in impulse and static-actor identity reporting; use the public query metadata and contact_capabilities described in Contact Sensor. Do not treat GPU and CPU contact rows as an identical manifold representation.

For a new task, check settling, impact response, joint tracking, and contact sensor output before increasing the environment count.