simulation-dev

name	simulation-dev
description	General simulation development best practices for correctness, stability, and debuggability. Use when implementing or modifying simulation systems, solvers, constraints, or GPU kernels, especially for index safety, NaN/Inf issues, and diagnostics.

Simulation Development Best Practices

General rules for building simulation code that is correct first, debuggable second, and fast third.

When to Use

Use this skill when:

• adding or modifying simulation systems, solvers, integrators, constraints, or contact logic,
• touching CPU/GPU compute paths that can fail from invalid indices or unstable numerics,
• debugging crashes, divergence, NaN/Inf, or non-deterministic behavior,
• improving diagnostics, assertions, and reproducibility.

Core Principles

1. Correctness before performance.
2. Fail fast on invalid states.
3. Prefer deterministic behavior during debugging.
4. Prefer MUDA-native diagnostics for GPU paths whenever possible.
5. Validate data at subsystem boundaries.
6. Instrument first, optimize after evidence.

Safety Rules (Always Apply)

Input and shape validation

• Validate counts, offsets, dimensions, and index ranges before compute.
• Verify assumptions at boundaries (API input, scene load, assembly, solver entry).
• Use clear sentinel conventions and assert them (-1, empty, null, etc.).

Index safety for GPU/parallel code

• Guard every computed index before read/write.
• Return early on invalid thread work instead of continuing with partial writes.
• Prefer host-side prevalidation to avoid propagating bad mappings into kernels.

Numerical robustness

• Check for finite values (isfinite) at key checkpoints.