Integration parameters

Various aspects of the integrator implemented on nphysics can be modified through the integration parameters. Those parameters can be changed by modifying the fields of your instance of 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 tuning parameters for optimal simulation stability, or for compromising between 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.

dt

The timestep length used for each update of the physics engine. The default is 1/601 / 60 seconds. This typically corresponds to a refresh rate of 60Hz. Smaller timesteps yield better accuracy of the integrator. 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).

erp

The Error Reduction Parameter in [0,1][0, 1] is the proportion of the positional error to be corrected at each time step. The default is 0.20.2. An ERP set to 0 means that no penetration will be corrected, and an ERP set to 1 means all the penetrations between two solids will be corrected in a single timestep. While setting 1 seems appealing, this will cause objects to jitter in practice because penetration correction may add or remove kinetic energy to the system.

warmstart_coeff

Each cached impulse are multiplied by this coefficient in [0,1][0, 1] when they are re-used to initialize the constraints solver. The default is 1.01.0. A high warm-start coefficient causes faster convergence but may add kinetic energy to the system (and cause jitters) for fast objects subject to non-elastic contacts. However 1.01.0 still remains a good choice for practical applications as it allows convergence of the constraints solver even if the maximum number of solver iterations is small.

allowed_linear_error

Amount of penetration the engine won't attempt to fix. The default is 0.0010.001 meters. Setting this to 0 would cause jittering because contacts would start and stop being active at a high frequency for resting objects (due to inevitable numerical errors). A value too large would cause noticeable penetrations.

max_linear_correction

Maximum translation-based penetration correction performed by the non-linear position solver during a single iteration. The default is 100.0100.0. A value too small would prevent penetrations from being corrected fast enough while a large value could cause jittering due to the solver overshooting (i.e. applying a correction that is too large).

max_velocity_iterations

Maximum number of iterations performed by the velocity constraints solver for impulse computation. More iterations imply greater accuracy at the cost of increased computation times.

max_position_iterations

Maximum number of iterations performed by the position-based constraints solver for penetration correction. More iterations imply greater accuracy at the cost of increased computation times.