Environment Configuration — Particles

SRB simulates granular materials such as regolith, sand, and dust with PhysX particles. Particle workflows target Isaac Sim 6.1.0 with Isaac Lab 3.0.0, force the PhysX backend, and require CUDA GPU dynamics.

Enabling Particles

To enable particle simulation in an environment, set env.particles=true:

srb agent teleop -e _manipulation env.particles=true env.robot=franka+scoop

Particle Configuration Parameters

Most particle parameters accept either a single scalar (used for every particle system) or a 2-tuple whose values pair with the two env.particles_size endpoints and interpolate across env.particles_systems. Defaults below are taken from BaseEnvCfg (srb/core/env/common/base/env_cfg.py).

Parameter	Description	Default
`env.particles`	Enable particle simulation	`false`
`env.particles_systems`	Number of independent particle systems per environment	`1`
`env.particles_spawner`	Pile spawner kernel — `grid`, `pyramid`, `crater_pile`, or `mound_pile`	`grid`
`env.particles_size`	Particle diameter in metres (scalar or `(min, max)` 2-tuple)	`(0.01, 0.005)`
`env.particles_area`	Pile XY extent as a fraction of environment spacing (scalar or 2-tuple)	`(0.75, 0.5)`
`env.particles_ratio`	Volume-fill ratio (scalar or 2-tuple)	`(0.025, 0.1)`
`env.particles_height`	Particle layers per system (integer scalar or 2-tuple)	`(1, 10)`
`env.particles_density`	PBD particle-material density (kg/m³)	`1600.0`
`env.particles_friction`	Particle–particle friction coefficient	`1.0`
`env.particles_damping`	Velocity damping	`0.2`
`env.particles_cohesion`	Cohesion (particle–particle stickiness)	`0.01`
`env.particles_adhesion`	Adhesion (particle–surface stickiness)	`0.05`
`env.particles_material`	Visual-material override for the particle set (advanced — a `VisualMaterialCfg`, not a scalar)	`None`
`env.particles_dim_xy`	Override grid count `(dim_x = dim_y)` per system	`None` (derived)
`env.particles_init_pos`	Explicit `(x, y, z)` placement of the first system	`None` (derived)
`env.particles_freeze`	Freeze systems after they settle — the solver stops but the settled geometry keeps rendering (for clean renders)	`false`
`env.particles_conform_to_terrain`	Snap particles onto the terrain height field instead of PBD settling	`false`
`env.particles_conform_jitter`	Random XY scatter (metres) applied when conforming to terrain (`0` keeps the regular grid)	`0.0`
`env.particles_pile_center_jitter`	Per-reset random XY offset (metres) of the whole settled pile — domain randomization of pile location (`0` disables)	`0.0`

srb agent teleop -e _manipulation env.particles=true \
  env.particles_size=0.01 env.particles_ratio=0.1

Particle Behavior

The default grid spawner produces a regular tessellation of particles within particles_area. Switch to particles_spawner=pyramid for natural-looking piles with higher density at the centre. Multi-system stacking (particles_systems>1) layers piles vertically and supports gradients across particle size, area, ratio, etc. Particles collide with rigid bodies and articulations, settle under gravity, and can be pushed, scooped, or otherwise manipulated by the agent.

In the particle tasks (excavation, terrain_landscaping) the agent additionally observes a heightmap of the particle surface. PhysX particle sets are not raycastable, so this heightmap is derived at runtime from the live particle positions rather than from a ray sensor — it tracks the pile as it is reshaped. The landscaping tasks route that derivation through a versioned external-heightmap seam with a fixed footprint-aware surface rule, not through ad-hoc binning.

Note: When particles are enabled, Fabric is automatically disabled (env.sim.use_fabric=false) so that the underlying PhysX particle simulation receives consistent state.

Runtime requirements and limits

Each environment must use its own particle system. Multiple particle environments force env.stack=false; see Parallelism. Cloned-environment runtime acceptance on Isaac Sim 6.1 remains pending.

Domain Randomization

Regolith interaction is a prime sim-to-real gap, so a few knobs randomize the granular material to keep a policy from overfitting one fixed pile:

env.particles_pile_center_jitter — on every reset the settled pile is restored and rigidly translated in XY by an independent per-environment sample in [-jitter, +jitter]. The pile keeps its settled shape (the translation is physically valid without re-settling), so 0.05 scatters where the pile sits by ±5 cm without changing its profile. 0 (the default) keeps the pile fixed.
The excavation and terrain-landscaping tasks additionally randomize the PhysX PBD particle material on every reset — friction is sampled in [0.6, 1.0] and density in [2700, 3100] kg/m³ — so the settled angle of repose and bulk behaviour vary trial-to-trial. This is wired into the tasks themselves rather than exposed as an env.* knob; in those two tasks env.particles_friction / env.particles_density therefore set the spawn baseline, not a per-episode constant.

Static Renders

For clean stills or offline datasets you often want the pile visible but motionless:

env.particles_freeze — after the initial settle completes, each system is disabled (its PhysX particleSystemEnabled flag is cleared and velocities zeroed). The settled points keep rendering, but the solver no longer simulates them, so the particles stay perfectly still. Pair it with the --snapshot capture for a frozen render bed.
env.particles_conform_to_terrain (optionally with env.particles_conform_jitter) snaps the spawned grid onto the terrain height field instead of PBD settling — useful when PBD settling is unavailable and you just need regolith that follows the terrain relief.

Keyboard shortcuts