Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
f7fc592
perf(rl): reduce rollout bookkeeping and batch physics updates
acrlw Oct 21, 2026
d9420ac
fix(rl): pass vector gravity to Newton planar reach builders
acrlw Oct 21, 2026
668aa33
perf(gym): make per-step episode context snapshots optional
acrlw Oct 22, 2026
fc3c1dc
perf(sim): expose mesh BVH construction for Newton terrain queries
acrlw Oct 22, 2026
7d49f6a
fix: Support custom asset caches and require compatible DexSim packages
acrlw Oct 22, 2026
0635df1
test: track explicit terrain conversion descriptor option
acrlw Oct 23, 2026
c1fc67b
Improve batched physics controls and lazy recording metadata
acrlw Nov 2, 2026
ce1e083
test(gym): preserve task outcomes with optional episode context
acrlw Nov 2, 2026
9ed54ed
fix(gym): preserve episode seed when recording is enabled
acrlw Nov 3, 2026
0e3f3b8
Merge RL rollout updates with the DexSim 0.6 baseline
acrlw Nov 9, 2026
59c678c
fix(env): preserve episode context for existing configurations
acrlw Nov 9, 2026
75e4466
fix(rl): preserve recording metadata and native scene settings
acrlw Nov 9, 2026
2c2baa4
fix(sim): preserve episode provenance and reset graph motors
acrlw Nov 10, 2026
21afa5e
Restart joint stability intervals after target re-entry
acrlw Nov 10, 2026
062c84f
Merge main into rollout improvements and restore camera CI
acrlw Nov 10, 2026
e5fbf64
Isolate NoRender motor reset test and merge main
acrlw Nov 11, 2026
035bd72
Sync merged marker and locomotion changes from main
acrlw Nov 11, 2026
3859425
Fix locomotion benchmark checks for DexUni
acrlw Nov 11, 2026
e3684a4
Sync current main and retain plane descriptor support
acrlw Nov 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion agent_context/topics/env-framework/env-framework.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,14 @@ physical-objective initialization and final observations; it is not forwarded
to functors. `BaseEnv` owns `EpisodeContext`; successful initialization seeds recording from
the final observation. `EmbodiedEnv` consumes old records before physical reset.
Failed checks remain attached to buffers until the selected rows are consumed
and a new episode begins. Info and recorder metadata carry owned context snapshots. The concrete preparation/restore host and
and a new episode begins. Info and recorder metadata carry owned context snapshots.
`EnvCfg.episode_context_in_info` defaults to true. Batched RL deployments may
disable automatic info snapshots while retaining context lifecycle, recorder
metadata and explicit snapshots. Reset retains each row's seed and shared
provenance snapshot even without a recorder. Demo recording materializes
independent metadata rows on access; row UUIDs and mutable
segment lists are owned by each episode. Reset reuses the snapshot from `get_info()`;
overrides that omit it receive one when the option is enabled. The concrete preparation/restore host and
snapshot limitations belong to [scene expansion](../scene-expansion/scene-expansion.md).

## Change sites and focused validation
Expand Down
8 changes: 8 additions & 0 deletions agent_context/topics/env-framework/execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,3 +335,11 @@ All normal output selections also intersect context eligibility. Explicit
and are never dataset commits. Closing only drains committed writes and discards
live buffers. Camera recordings use independent row buffers and files, with owned
context sidecars; asynchronous jobs do not wait for another row or a mosaic.

## Recording cost during RL rollouts

`EmbodiedEnv` allocates raw/controller action histories on the first recording
sample. Demo provenance is created when recording metadata is requested;
episode initialization refreshes it once it has been used. Ordinary RL resets
do not enumerate empty recording histories on the host. Metadata snapshots
retain deep-copy and episode-context ownership.
4 changes: 4 additions & 0 deletions agent_context/topics/sensor-system/contact-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,3 +152,7 @@ evidence window.
it returns the highest accepted contact or NaN for an unavailable row. It does
not create a physical window or choose a Task Program verdict. Geometric world
mesh envelopes are numerical Compute inputs, independent of this contact proof.
Normal-force-only consumers can use `ContactSensor._reduce_normal_impulses()`
to reduce packed contact impulses directly into a task-owned snapshot. It
retains dropped-contact accounting and does not replace the row-buffer/history
path used by consumers requiring per-contact information.
11 changes: 11 additions & 0 deletions agent_context/topics/simulation-system/articulation-adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,13 @@ DexSim's batch fetch and converts the root-pose layout once. Returned tensors
are borrowed buffers, not snapshots; clone values that must survive later
reads. Fetch after reset or direct writes rather than caching across them.

`Articulation.set_state()` writes selected root, joint and drive fields in one
backend operation. Current joint positions are clipped to joint limits.
Position targets are also clipped by default; `clamp_target_qpos=False` retains
raw PD targets while physical joint limits remain enabled. `set_qpos()` exposes
the same target-only option. Keep this distinction when a task records motor
commands for learned dynamics.

`Articulation.set_root_velocity()` writes selected world-frame linear and
angular velocities as `(N, 6)` rows. The Scene adapter validates the complete
input before writing one selected batch; other environment rows are preserved.
Expand All @@ -94,6 +101,10 @@ output tensors. Public inertia/COM remain principal moments plus `xyz + xyzw`;
scalar descriptors expose body-frame mat33. Runtime writes compose the pair
before DexSim, and reset restores the saved pair together to avoid reordering
principal axes between two writes.
COM writes pass environment rows and link columns directly to
`ArticulationBatch.apply_link_com_local_pose(rows=..., link_ids=...)`. Property
selection does not need a selected batch's joint/link state routing buffers;
DexSim retains descriptor updates and solver-constant refresh ownership.

## Mimic coupling

Expand Down
15 changes: 15 additions & 0 deletions agent_context/topics/simulation-system/lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,3 +119,18 @@ camera attachment, replacement, control registration, reset and teardown.
`tests/sim/spawn/test_scene.py` covers declaration/source/binding state;
`tests/sim/test_runtime_controls.py` covers nodal behavior and one-shot joint seeding. Physical
baseline tests live with the corresponding objects under `tests/sim/objects/`.

## Batched RL controls and property writes

`_register_joint_dc_motor_control()` installs a graph-compatible motor before
scene preparation, resolving public joint names in Arena order. Effort is held
through solver substeps and refreshed at the next outer physics step.
`configure_ground_plane_collision()` sets ground geometry and Newton collision
options before preparation; calls after preparation fail.

Spawn-bound Newton articulations forward unique selected mass, principal
inertia and COM-pose writes through Scene batches. Public COM poses remain
XYZ + XYZW; the adapter converts the batch pose convention. Duplicate selections
retain ordered per-entity behavior. Matching DexSim selected-link batch methods
are required. `preserve_mesh_transform` retains authored collision mesh pose
and scale when explicitly selected in Newton collision configuration.
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ names pass through to DexSim's `RegisteredNewtonSolverCfg`; unregistered names
remain errors. Read exact solver options/defaults in `cfg/physics.py` and the
installed DexSim config types; do not substitute a
hardcoded fallback when an expected DexSim API is absent.
`mesh_bvh_constructor` selects the mesh and heightfield query acceleration
structure. `None` keeps the native default.

The spring-slider provider lives only in
`scripts/tutorials/sim/simple_newton_solver/`; see its
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,12 @@ It is independent of the drive velocity gain ``damping`` and stays active for
passive and effort target modes. In dictionaries, select this subtype with
``joint_drive_props.backend="newton"``. Both settings require Newton.

``JointDrivePropertiesCfg.limit_stiffness`` and ``limit_damping`` separate
joint-limit gains from drive gains. Each accepts a scalar or joint-rule mapping;
``None`` preserves the source/backend value. With Newton's MuJoCo solver,
setting both to zero selects the default MuJoCo limit response while retaining
joint bounds.

.. currentmodule:: embodichain.lab.sim.cfg.articulation

.. autosummary::
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Overview

Geometry configuration objects used to build collision, visual, and deformable
simulation shapes. :class:`ShapeCfg` is the common base; :class:`MeshCfg`,
:class:`CubeCfg`, and :class:`SphereCfg` describe triangle-mesh, box, and
sphere primitives respectively. :class:`MeshCollisionCfg` explicitly selects
:class:`CubeCfg`, :class:`PlaneCfg`, and :class:`SphereCfg` describe triangle-mesh,
box, plane, and sphere primitives respectively. :class:`MeshCollisionCfg` explicitly selects
the collision representation and its cooking settings, while
:class:`LoadOption` controls mesh loading.

Expand All @@ -18,6 +18,10 @@ surface deformables, the array-backed form preserves node order for particle
flags and kinematic trajectories. Volume deformables generate a separate
tetrahedral simulation mesh during voxelization.

``PlaneCfg`` creates an infinite collision plane on a static rigid object.
Its ``size`` controls only the visual width and length. The plane's local normal
is +Z; the rigid object's initial pose sets its world position and orientation.

.. rubric:: Type aliases

.. autosummary::
Expand All @@ -32,6 +36,7 @@ tetrahedral simulation mesh during voxelization.
LoadOption
MeshCollisionCfg
MeshCfg
PlaneCfg
ShapeCfg
SphereCfg

Expand Down Expand Up @@ -61,6 +66,12 @@ tetrahedral simulation mesh during voxelization.
:show-inheritance:
:exclude-members: __init__, copy, replace, to_dict, validate

.. autoclass:: PlaneCfg
:members:
:undoc-members:
:show-inheritance:
:exclude-members: __init__, copy, replace, to_dict, validate

.. autoclass:: SphereCfg
:members:
:undoc-members:
Expand Down
18 changes: 18 additions & 0 deletions docs/source/overview/rl/locomotion.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,21 @@ embodichain train-rl --config embodichain_tasks/configs/tasks/locomotion/velocit
Local smoke checks cover environment construction, stepping, finite tensors, selective reset and policy forward execution, with zero training updates.

See the [task API reference](../../api_reference/locomotion_tasks.rst) for configuration and MDP types.

## Batched simulation updates

RL rollouts allocate demonstration action histories only when recording starts.
Requesting demonstration metadata still produces an owned snapshot with episode
provenance; recording and replay retain their existing interfaces.

For spawn-bound Newton articulations, `set_mass`, `set_inertia`, and
`set_com_pose` use selected-row batch writes when row/link selections are
unique. Inertia values remain principal moments in the applied COM frame; COM
poses use XYZ followed by XYZW. The paired DexSim version must expose selected
link writes. Duplicate selections preserve ordered per-entity updates.

Before scene preparation, `SimulationManager.configure_ground_plane_collision`
can replace the global ground geometry and collision descriptor. Newton
collision configuration also accepts `preserve_mesh_transform` to retain the
authored collision mesh pose and scale. These options do not change the default
settings of existing tasks.
8 changes: 8 additions & 0 deletions docs/source/overview/sim/sim_manager/physics/newton.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,3 +129,11 @@ and [solver tuning reference](https://newton-physics.github.io/newton/stable/con
newton/dexuni
newton/runtime_qualification
```

## Mesh query acceleration

`NewtonPhysicsCfg.mesh_bvh_constructor` selects the mesh BVH constructor used
for mesh and heightfield ray queries. Its default `None` preserves the engine
configuration. Large CUDA terrain scans can select `"cubql"`. The constructor
changes the acceleration structure while preserving the mesh geometry and
physical contact parameters.
12 changes: 10 additions & 2 deletions embodichain/compute/trajectory/stability.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ class PositionRangeMonitor:
position_drift: Positive maximum range in one candidate window.

The caller supplies a separate pointwise target predicate. Tick zero does
not count as an elapsed interval. Success is current, not latched: a later
not count as an elapsed interval. Re-entering the target starts a new window
at zero completed intervals. Success is current, not latched: a later
violation resets the row even if an earlier window succeeded. Duplicate
step observations are idempotent; missing intervals cannot prove stability.
This numerical monitor reads no Robot, clock, simulator or normative spec.
Expand Down Expand Up @@ -63,6 +64,7 @@ def __init__(
self._high = initial.clone()
self._counts = torch.zeros_like(initial, dtype=torch.long)
self._satisfied = torch.zeros_like(initial, dtype=torch.bool)
self._previous_good = torch.zeros_like(initial, dtype=torch.bool)
self._required = required_steps
self._drift = float(position_drift)
self._last_step = -1
Expand Down Expand Up @@ -110,11 +112,17 @@ def observe(
good = within_target & torch.isfinite(values)
low = torch.minimum(self._low, values)
high = torch.maximum(self._high, values)
reset = ~good | ~torch.isfinite(self._low) | ((high - low) > self._drift)
reset = (
~good
| (~self._previous_good & (elapsed_steps > 0))
| ~torch.isfinite(self._low)
| ((high - low) > self._drift)
)
self._low = torch.where(reset, values, low)
self._high = torch.where(reset, values, high)
self._counts = torch.where(reset, 0, self._counts + int(elapsed_steps > 0))
self._satisfied = good & (self._counts >= self._required)
self._previous_good = good
self._last_step = elapsed_steps
return self._satisfied.clone()

Expand Down
46 changes: 26 additions & 20 deletions embodichain/data/dataset.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,28 @@
import hashlib
import time
from contextlib import contextmanager
from pathlib import Path
from typing import Iterator
import open3d as o3d

from embodichain.utils import logger


def _dataset_cache_paths(path: str, prefix: str) -> tuple[Path, Path]:
"""Resolve one cache entry and reject paths outside its configured root."""
if not prefix or prefix in {".", "..", ".locks"} or "/" in prefix or "\\" in prefix:
raise ValueError(f"Dataset prefix must name one cache entry: {prefix!r}")
root = Path(path).resolve()
entries = []
for category in ("download", "extract"):
parent = root / category
entry = parent / prefix
if parent.resolve() != parent or entry.resolve() != entry:
raise ValueError(f"Dataset cache entry must stay within {parent}: {entry}")
entries.append(entry)
return entries[0], entries[1]


@contextmanager
def _dataset_download_lock(path: str, prefix: str) -> Iterator[None]:
"""Serialize download and extraction for one dataset cache entry.
Expand All @@ -47,7 +63,12 @@ def _dataset_download_lock(path: str, prefix: str) -> Iterator[None]:
path: Root of the EmbodiChain data cache.
prefix: Dataset cache directory name.
"""
lock_dir = os.path.join(path, "download", ".locks")
download_path, _ = _dataset_cache_paths(path, prefix)
lock_dir = download_path.parent / ".locks"
if lock_dir.resolve() != lock_dir:
raise ValueError(
f"Dataset cache lock directory must not be a symlink: {lock_dir}"
)
os.makedirs(lock_dir, exist_ok=True)
lock_path = os.path.join(lock_dir, f"{prefix}.lock")

Expand Down Expand Up @@ -92,28 +113,13 @@ def __init__(self, prefix, data_descriptor, path):

def check_zip(self, prefix, data_descriptor, path):
"""Check the integrity of the zip file and its extracted contents."""
# Path to the downloaded zip file
# Validate both entries before removing an archive or extracted data.
zip_dir_path, extracted_path = _dataset_cache_paths(path, prefix)
zip_file_name = os.path.split(data_descriptor.urls[0])[1]
zip_dir_path = os.path.join(path, "download", f"{prefix}")
zip_path = os.path.join(path, "download", f"{prefix}", f"{zip_file_name}")
# Path to the extracted directory
extracted_path = os.path.join(path, "extract", prefix)

def is_safe_path(path_to_check):
"""Verify if the path is within safe directory boundaries"""
return (
"embodichain_data/download" in path_to_check
or "embodichain_data/extract" in path_to_check
)
zip_path = zip_dir_path / zip_file_name

def safe_remove_directory(dir_path):
"""Safely remove a directory after path validation"""
if not is_safe_path(dir_path):
logger.log_warning(
f"Safety check failed, refusing to delete directory: {dir_path}"
)
return False

"""Remove an entry whose configured cache boundary was validated."""
if os.path.exists(dir_path):
try:
shutil.rmtree(dir_path)
Expand Down
17 changes: 15 additions & 2 deletions embodichain/lab/gym/envs/base_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,14 @@ class EnvCfg:
only end when the task is successfully completed or failed.
"""

episode_context_in_info: bool = True
"""Include owned episode-context snapshots in step and reset info.

Disable for batched RL consumers that do not read per-row provenance.
Episode lifecycle tracking, recorder metadata, and explicit
``episode_context.snapshot()`` calls remain available.
"""

profiler: EnvProfilerCfg | None = None
"""Optional profiler for reset/step wall-time breakdown. ``None`` keeps
the profiler disabled unless one is configured directly on ``sim_cfg``.
Expand Down Expand Up @@ -802,7 +810,8 @@ def get_info(self, **kwargs) -> TensorDict[str, Any]:
evaluate = self.evaluate(**kwargs)
if evaluate:
info.update(evaluate)
info["episode_context"] = self.episode_context.snapshot()
if getattr(self.cfg, "episode_context_in_info", True):
info["episode_context"] = self.episode_context.snapshot()
return info

def check_truncated(self, obs: EnvObs, info: TensorDict[str, Any]) -> torch.Tensor:
Expand Down Expand Up @@ -1020,7 +1029,11 @@ def reset(
self._record_initial_observation(observation_frame, reset_ids)
with self._profiler.section("get_info"):
info = self.get_info(**options)
info["episode_context"] = context.snapshot()
if (
getattr(self.cfg, "episode_context_in_info", True)
and "episode_context" not in info
):
info["episode_context"] = context.snapshot()
except BaseException as error:
context._abort_initialization(reset_ids, error)
raise
Expand Down
Loading
Loading