Integration parameters

Various aspects of the physics simulation can be tuned by modifying the fields of the IntegrationParameters. Most of these parameters are somewhat advanced and should not be modified unless you know their meaning and effect. Several of them are about balancing efficiency and accuracy. They are given default values that work well in the context of video-games or animations. For more realistic simulations you may want to change those parameters to favor accuracy over performance.

info

Several parameters are expressed in a normalized form, i.e., their value is implicitly multiplied by length_unit before being used. Therefore they don't need to be adjusted when the world is not measured in meters.

Setting the integration parameters

The integration parameters are owned by the physics world, and exposed as its PhysicsWorld.integration_parameters property. This property always gives the same IntegrationParameters object, so the parameters are modified in place by setting its properties, which have the same names as the parameters described in this page. Assigning an IntegrationParameters to the property of the world copies all its parameters at once, e.g., the default values given by IntegrationParameters():

# The integration parameters of the world are modified in place: the property always gives
# the same object.
params = world.integration_parameters
params.dt = 1.0 / 120.0
params.num_solver_iterations = 8
params.warmstart_joints = True
print(f"dt = {params.dt}, {world.integration_parameters.num_solver_iterations} solver iterations")

# They can also be replaced all at once, e.g., to reset them to their default values.
world.integration_parameters = rp.IntegrationParameters()

warning

The contact softnesses (contact_softness and static_contact_softness) are given as copies: modifying the object read from one of these properties has no effect until it is assigned back to the property. On the other hand, the soft_bodies settings are a live view of the parameters, like the IntegrationParameters of the world itself.

Time-stepping

dt

The timestep length used for each update of the physics engine. This is the time by which the physics simulation will be advanced. The default is $1 / 60$ seconds. This typically corresponds to a refresh rate of 60Hz. Smaller timesteps yield better accuracy. Large timesteps increase the negative effect of some approximations (linearization of various parts of the equations of motion) and may result in missed collisions (because of collisions that may occur in-between timesteps for fast-moving objects).

Each call to PhysicsWorld.step advances the simulation by exactly dt. If the physics must follow the real time while the frame rate of your application varies, it is recommended to keep dt constant and to call PhysicsWorld.step as many times as needed at each frame, i.e., to accumulate the time elapsed since the last frame (e.g. measured with time.perf_counter), and to execute one timestep each time this accumulated time exceeds dt. Changing dt at each frame instead makes the simulation depend on the frame rate, therefore it will not give the same simulation results twice (see determinism).

length_unit

The number of your own length units that make one meter. The default is $1.0$, i.e., the simulation is measured in meters. Rapier is tuned for human-scale objects measured in meters, therefore a simulation measured in centimeters should set this to $100.0$, and a 2D game where a typical object is 100 pixels tall should set it to $100.0$ as well. This scales the normalized parameters as well as various internal tolerances, and is the recommended alternative to re-tuning every threshold by hand. Learn more about this in the common mistakes page.

Note that the length unit doesn't scale the gravity, nor any of the values you give to the engine: they must be expressed in your own units as well, e.g., a simulation measured in centimeters needs a gravity of $-981$ along the $y$ axis:

# The simulation is measured in centimeters.
world.integration_parameters.length_unit = 100.0
# The gravity isn't scaled by the length unit: it must be given in centimeters too.
world.gravity = (0.0, -981.0, 0.0)

max_ccd_substeps

The maximum number of CCD substeps performed during one timestep. The default is $1$. This is also the global switch of CCD: setting it to $0$ disables every form of CCD for this world, including the sweeping of the fast dynamic bodies against the fixed colliders.

min_ccd_dt

When CCD with multiple substeps is enabled, the timestep is subdivided into smaller pieces. This timestep subdivision won't generate timestep lengths smaller than min_ccd_dt. The default is $1 / 60 / 100$ seconds.

Setting this to a large value will reduce the opportunity to performing CCD substepping. Setting this to a very small value may lead to numerical instabilities.

Constraints solver

num_solver_iterations

The number of iterations, aka. substeps, run by the constraints solver. The default is $4$. Higher values give more accurate and more stable simulations, at the cost of performance: $8$ to $12$ is a reasonable range for demanding scenes (tall stacks, machinery with stiff joints), whereas $1$ or $2$ may be enough if performance matters more than accuracy. Note that a single rigid-body can be given additional iterations of its own, as described in the rigid-body solver settings section.

num_internal_pgs_iterations

The number of internal Projected Gauss-Seidel iterations run at each solver iteration. The default is $1$.

num_internal_stabilization_iterations

The number of stabilization iterations run at each solver iteration. The default is $1$. These are the iterations solving the constraints without their depenetration forces. This is what prevents the energy introduced by the position correction from remaining in the simulation.

warmstart_coefficient

Each cached impulse is multiplied by this coefficient in $[0, 1]$ when it is re-used to initialize the constraints solver. The default is $1.0$: it allows the convergence of the solver even when the number of iterations is small.

warmstart_joints

If enabled, the impulse-joint constraints are warm-started like the contacts are, i.e., the impulses accumulated by the previous timestep are re-applied at the beginning of each substep instead of restarting from zero. The default is False. Enabling it noticeably improves the convergence of stiff joint assemblies. Note that the multibody joints are not affected by this parameter.

friction_in_bias_pass

If enabled, friction is solved during the biased pass of each substep as well as during the unbiased one. The default is False, which is both cheaper and often more stable.

friction_model (3D only)

The kind of friction constraints solved by the engine, given by the FrictionModel enum. The FrictionModel.SIMPLIFIED model (the default) solves one Coulomb constraint per group of four contacts, plus one purely rotational "twist" constraint eliminating the angular motion in the tangent plane of the manifold. The FrictionModel.COULOMB model solves one Coulomb constraint per contact point instead: it is more mechanically correct but more expensive.

# Solve one Coulomb friction constraint per contact point.
world.integration_parameters.friction_model = rp.FrictionModel.COULOMB

Contacts

contact_softness and static_contact_softness

The softness of the contact constraints, given as a natural frequency (in Hz) and a damping ratio instead of a stiffness, so it doesn't depend on the masses of the colliding bodies. Softer constraints make the contacts more compliant (meaning that they allow more penetrations when pressed on), whereas harder constraints feel more rigid and correct, but might introduce jitters if too rigid.

Both are given as a SpringCoefficients, with its natural_frequency and damping_ratio properties. The static_contact_softness applies to the contacts where one side is a fixed rigid-body, and is stiffer than contact_softness by default so the bodies are held firmly against the static walls and floors. Keep in mind that these properties give copies of the coefficients, which must be assigned back once modified:

params = world.integration_parameters
# The softness is given as a copy: modify it, then assign it back.
softness = params.contact_softness
print(f"{softness.natural_frequency} Hz, damping ratio {softness.damping_ratio}")
# Contacts against fixed rigid-bodies are stiffer by default: make them as soft as the others.
params.static_contact_softness = softness

normalized_prediction_distance

The maximal distance separating two objects that will generate predictive (aka. speculative) contacts. The default is $0.02$, i.e., four times the geometric slop. Generating contacts before the objects actually touch is what allows the solver to stop them exactly at the surface instead of letting them interpenetrate first.

normalized_allowed_linear_error

The geometric slop distance. The default is $0.005$.

normalized_max_corrective_velocity

The maximum speed at which the solver is allowed to push penetrating objects apart. The default is $3.0$. Capping this velocity is what keeps a deep penetration from being resolved explosively.

normalized_max_linear_velocity

The maximum linear velocity a rigid-body may have after each substep. The default is $400.0$. This velocity cap helps with stability and CCD effectiveness.

contact_clustering

If enabled, the contact manifolds of a collider pair that share (nearly) the same normal are merged into a single cluster manifold before the constraints are generated (default: True, 3D only), so at most four contact points are solved per contact plane. This is a large gain on the composite shapes (triangle-meshes, heightfields, compound shapes, voxels) which generate one manifold per sub-shape.

warning

When contact clustering applies, the impulses of the contact points of ContactPair.manifolds (which are the points of the geometric contact manifolds) don't reflect the impulses applied by the solver. Read the impulses from the totals of the ContactPair instead (e.g. ContactPair.total_impulse() and ContactPair.total_impulse_magnitude()), which account for the clusters. See the contact graph section.

contact_recycling and normalized_contact_recycle_distance

If enabled, a contact pair which relative position moved less than the recycle distance since its last full update keeps its existing contact points instead of recomputing them (default: True, with a recycle distance of $0.05$).

Soft-bodies

soft_bodies

The settings shared by every soft-body of the world. They are detailed in the soft-body settings section. They are given by the soft_bodies property of the IntegrationParameters as a live view, so they are modified in place like the other integration parameters (its copy method gives a detached copy).