perf(rbd): performance improvements of the RBD solver

README.md

@@ -26,6 +26,31 @@ Nexus is organized into independent physics modules, each available in 2D and 3D
   materials, fluids, etc. Supports one-way coupling with rigid-bodies (= rigid-bodies can push particles but particles
   cannot push rigid-bodies).
 
+## Rigid-body friction (3D)
+
+Choose the contact model globally with `RbdSimParams::friction_model`:
+
+```rust ignore
+use nexus_rbd3d::dynamics::{FrictionModel, RbdSimParams};
+
+let params = RbdSimParams {
+    friction_model: FrictionModel::Simplified,
+    ..RbdSimParams::default()
+};
+```
+
+`Coulomb` (the default) solves sliding friction at each contact point.
+`Simplified` follows Rapier's twist-friction model: per-point normal constraints,
+one sliding-friction constraint at the manifold center, and one angular constraint
+resisting twist about its normal. A single-point contact has no twist constraint.
+The models approximate friction differently and can produce different motion.
+Multibody contacts always use Coulomb, as in Rapier; 2D is unchanged.
+
+Pass these parameters to `RbdState::from_rapier` (identically for every environment),
+or call `NexusState::set_rbd_friction_model` before `finalize`. A live `RbdState`
+can switch all environments with `set_friction_model(&backend, model)`.
+Switching clears incompatible friction warmstarts and preserves normal warmstarts.
+
 ## Prerequisites
 
 ### Install `cargo gpu`

crates/examples2d/all_examples2.rs

@@ -25,13 +25,17 @@ mod mpm_hourglass2;
 mod mpm_sand2;
 mod mpm_snowball2;
 
+// Large stress scenes, listed in their own picker group.
+mod stress_scenes;
+
 /// Declares the demo registry: a `(name, kind)` list for the picker UI and a
 /// name -> `run()` dispatcher. Keeping both in one macro keeps them in sync.
 macro_rules! demos {
     ( $( $name:literal => $kind:ident : $module:ident ),* $(,)? ) => {
         fn demo_list() -> Vec<(String, DemoKind)> {
             let mut demos: Vec<(String, DemoKind)> =
                 vec![ $( ($name.to_string(), DemoKind::$kind) ),* ];
+            demos.extend(stress_scenes::demo_list());
             demos.sort_by(|a, b| match (a.0.starts_with('('), b.0.starts_with('(')) {
                 (true, true) | (false, false) => a.0.cmp(&b.0),
                 (true, false) => std::cmp::Ordering::Greater,
@@ -46,7 +50,11 @@ macro_rules! demos {
                 // migrated to the `NexusState` API); discard whatever it yields
                 // so every arm has the same `()` type.
                 $( $name => { let _ = $module::run(viewer, pipeline).await; }, )*
-                _ => eprintln!("Unknown demo: '{name}'"),
+                _ => {
+                    if stress_scenes::run(name, viewer, pipeline).await.is_none() {
+                        eprintln!("Unknown demo: '{name}'");
+                    }
+                }
             }
         }
     };
@@ -85,6 +93,8 @@ struct CliOptions {
     metal: bool,
     run: bool,
     deterministic: bool,
+    snapshot: Option<(u32, String)>,
+    headless: bool,
 }
 
 fn parse_command_line() -> CliOptions {
@@ -98,6 +108,8 @@ fn parse_command_line() -> CliOptions {
         metal: false,
         run: false,
         deterministic: false,
+        snapshot: None,
+        headless: false,
     };
 
     while let Some(arg) = args.next() {
@@ -110,6 +122,11 @@ fn parse_command_line() -> CliOptions {
             "--metal" => opts.metal = true,
             "--run" => opts.run = true,
             "--deterministic" => opts.deterministic = true,
+            "--headless" => opts.headless = true,
+            "--snapshot" => {
+                let frame = args.next().and_then(|f| f.parse().ok());
+                opts.snapshot = frame.zip(args.next());
+            }
             _ => {}
         }
     }
@@ -143,8 +160,14 @@ pub async fn main() {
         }
     }
 
-    let mut viewer = NexusViewer::new(demos.clone()).await;
-    viewer = viewer.with_selected_demo(selected);
+    let mut viewer = if opts.headless {
+        NexusViewer::new_headless_with_size(demos.clone(), 1600, 1200).await
+    } else {
+        NexusViewer::new(demos.clone()).await
+    };
+    viewer = viewer
+        .with_selected_demo(selected)
+        .with_wait_for_render(true);
     if opts.cpu {
         viewer = viewer.with_cpu();
     }
@@ -165,6 +188,10 @@ pub async fn main() {
     if opts.deterministic {
         viewer = viewer.with_deterministic(true);
     }
+    #[cfg(not(target_arch = "wasm32"))]
+    if let Some((frame, path)) = opts.snapshot.clone() {
+        viewer = viewer.with_snapshot(frame, path);
+    }
 
     // The GPU pipelines are owned here (not by `NexusState`) so they can be
     // compiled once up-front and reused across demos. A backend switch drops and

crates/examples2d/stress_scenes/box_rain.rs

@@ -0,0 +1,49 @@
+//! A grid of boxes dropped into a walled container.
+
+use super::builder::{Camera, Random, Scene};
+
+/// A `cols` × `rows` grid of boxes (slightly jittered sizes) dropped into a walled container.
+fn box_rain(camera: Camera, cols: usize, rows: usize) -> Scene {
+    let mut s = Scene::new(camera);
+    let width = cols as f32 * 1.2 + 4.0;
+    let wall_height = rows as f32 * 1.4 + 10.0;
+    s.rigid([width + 2.0, 1.0], 0.0, 0.5, [0.0, -0.5, 0.0]);
+    s.rigid(
+        [1.0, wall_height],
+        0.0,
+        0.5,
+        [-width / 2.0, wall_height / 2.0, 0.0],
+    );
+    s.rigid(
+        [1.0, wall_height],
+        0.0,
+        0.5,
+        [width / 2.0, wall_height / 2.0, 0.0],
+    );
+    let mut rand = Random::new(1);
+    for y in 0..rows {
+        for x in 0..cols {
+            let w = 0.6 + rand.next() * 0.5;
+            let h = 0.6 + rand.next() * 0.5;
+            let pos = [
+                x as f32 * 1.2 - (cols - 1) as f32 * 0.6,
+                2.0 + y as f32 * 1.4,
+                rand.next() * 0.5,
+            ];
+            s.rigid([w, h], 1.0, 0.5, pos);
+        }
+    }
+    s
+}
+
+pub fn box_rain_40x25() -> Scene {
+    box_rain(Camera::new(0.0, 15.0, 12.0), 40, 25)
+}
+
+pub fn box_rain_100x50() -> Scene {
+    box_rain(Camera::new(0.0, 30.0, 5.5), 100, 50)
+}
+
+pub fn box_rain_900x100() -> Scene {
+    box_rain(Camera::new(0.0, 60.0, 0.7), 900, 100)
+}