Skip to main content

Determinism

By default, Rapier is locally deterministic, meaning that running the exact same simulation (with the same initial conditions) twice with the same machine, using the same version of Rapier, and the same version of the Rust compiler, will result in the exact same simulation results. However, doing this on two different computers may result in completely different results.

note

Two simulations run with the same initial conditions if all the simulation structures are initialized with the same values, rigid-bodies/colliders/joints are constructed the same way, and they are added/removed to sets (rigid-body sets, etc.) in the exact same order.

It is possible to make Rapier cross-platform deterministic, meaning that running a simulation with two different computers (including different OS and/or different processors) will result in the exact same results. In order to achieve this, both computers must start the simulation with the same initial conditions as discussed above, and the following additional conditions must be met:

  • The enhanced-determinism feature of Rapier is enabled. Note that the enhanced-determinism feature cannot be enabled at the same time as the simd-nightly, simd-stable, and parallel features.
  • The target platforms must strictly comply to the IEEE 754-2008 floating-points standard. This ensures that floating-point computations behave the same on all platforms. This include most modern mainstream processors as well as WASM targets.
  • If some of the values used to initialized Rapier structures are computed using floating points functions (sin, cos, tan, etc.) other than addition/subtraction/multiplication/division, then you need to make sure the functions being used originate from the ComplexField or RealField traits from nalgebra. For example, do ComplexField::sin(0.4) (where ComplexField is imported by use nalgebra::ComplexField) instead of 0.4.sin():
// WRONG version:
// The following will not work cross-platform-deterministically because the values
// given to `ColliderBuilder::translation` won't be cross-platform deterministic.
let collider = ColliderBuilder::ball(0.5)
    .translation(vector![1.0.sqrt(), 2.0.sin(), 3.0.cos()])
    .build();

// CORRECT version:
// The following will work cross-platform-deterministically because we use the
// functions from nalgebra.
let collider = ColliderBuilder::ball(0.5)
    .translation(vector![
        ComplexField::sqrt(1.0),
        ComplexField::sin(2.0),
        ComplexField::cos(3.0),
    ])
    .build();