feat: rename cfm_factor, damping_ratio to contact_cfm_factor and contact_damping_ratio

src/dynamics/integration_parameters.rs

@@ -25,25 +25,31 @@ pub struct IntegrationParameters {
     pub min_ccd_dt: Real,
 
     /// > 0: the damping ratio used by the springs for contact constraint stabilization.
-    /// Lower values make the constraints more compliant (more "springy", allowing more visible
+    ///
+    /// Larger values make the constraints more compliant (allowing more visible
     /// penetrations before stabilization).
     /// (default `5.0`).
     pub contact_damping_ratio: Real,
 
     /// > 0: the natural frequency used by the springs for contact constraint regularization.
+    ///
     /// Increasing this value will make it so that penetrations get fixed more quickly at the
     /// expense of potential jitter effects due to overshooting. In order to make the simulation
-    /// look stiffer, it is recommended to increase the [`Self::damping_ratio`] instead of this
+    /// look stiffer, it is recommended to increase the [`Self::contact_damping_ratio`] instead of this
     /// value.
     /// (default: `30.0`).
     pub contact_natural_frequency: Real,
 
     /// > 0: the natural frequency used by the springs for joint constraint regularization.
+    ///
     /// Increasing this value will make it so that penetrations get fixed more quickly.
     /// (default: `1.0e6`).
     pub joint_natural_frequency: Real,
 
     /// The fraction of critical damping applied to the joint for constraints regularization.
+    ///
+    /// Larger values make the constraints more compliant (allowing more joint
+    /// drift before stabilization).
     /// (default `1.0`).
     pub joint_damping_ratio: Real,
 
@@ -65,7 +71,7 @@ pub struct IntegrationParameters {
     ///
     /// This value can be understood as the number of units-per-meter in your physical world compared
     /// to a human-sized world in meter. For example, in a 2d game, if your typical object size is 100
-    /// pixels, set the `[`Self::length_unit`]` parameter to 100.0. The physics engine will interpret
+    /// pixels, set the [`Self::length_unit`] parameter to 100.0. The physics engine will interpret
     /// it as if 100 pixels is equivalent to 1 meter in its various internal threshold.
     /// (default `1.0`).
     pub length_unit: Real,
@@ -74,7 +80,7 @@ pub struct IntegrationParameters {
     ///
     /// This value is implicitly scaled by [`IntegrationParameters::length_unit`].
     pub normalized_allowed_linear_error: Real,
-    /// Maximum amount of penetration the solver will attempt to resolve in one timestep.
+    /// Maximum amount of penetration the solver will attempt to resolve in one timestep (default: `10.0`).
     ///
     /// This value is implicitly scaled by [`IntegrationParameters::length_unit`].
     pub normalized_max_corrective_velocity: Real,
@@ -84,7 +90,7 @@ pub struct IntegrationParameters {
     pub normalized_prediction_distance: Real,
     /// The number of solver iterations run by the constraints solver for calculating forces (default: `4`).
     pub num_solver_iterations: NonZeroUsize,
-    /// Number of addition friction resolution iteration run during the last solver sub-step (default: `4`).
+    /// Number of addition friction resolution iteration run during the last solver sub-step (default: `0`).
     pub num_additional_friction_iterations: usize,
     /// Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration (default: `1`).
     pub num_internal_pgs_iterations: usize,
@@ -130,23 +136,23 @@ impl IntegrationParameters {
     }
 
     /// The contact’s spring angular frequency for constraints regularization.
-    pub fn angular_frequency(&self) -> Real {
+    pub fn contact_angular_frequency(&self) -> Real {
         self.contact_natural_frequency * Real::two_pi()
     }
 
-    /// The [`Self::erp`] coefficient, multiplied by the inverse timestep length.
+    /// The [`Self::contact_erp`] coefficient, multiplied by the inverse timestep length.
-    pub fn erp_inv_dt(&self) -> Real {
+    pub fn contact_erp_inv_dt(&self) -> Real {
-        let ang_freq = self.angular_frequency();
+        let ang_freq = self.contact_angular_frequency();
         ang_freq / (self.dt * ang_freq + 2.0 * self.contact_damping_ratio)
     }
 
     /// The effective Error Reduction Parameter applied for calculating regularization forces
     /// on contacts.
     ///
-    /// This parameter is computed automatically from [`Self::natural_frequency`],
+    /// This parameter is computed automatically from [`Self::contact_natural_frequency`],
-    /// [`Self::damping_ratio`] and the substep length.
+    /// [`Self::contact_damping_ratio`] and the substep length.
-    pub fn erp(&self) -> Real {
+    pub fn contact_erp(&self) -> Real {
-        self.dt * self.erp_inv_dt()
+        self.dt * self.contact_erp_inv_dt()
     }
 
     /// The joint’s spring angular frequency for constraint regularization.
@@ -171,11 +177,11 @@ impl IntegrationParameters {
 
     /// The CFM factor to be used in the constraint resolution.
     ///
-    /// This parameter is computed automatically from [`Self::natural_frequency`],
+    /// This parameter is computed automatically from [`Self::contact_natural_frequency`],
-    /// [`Self::damping_ratio`] and the substep length.
+    /// [`Self::contact_damping_ratio`] and the substep length.
-    pub fn cfm_factor(&self) -> Real {
+    pub fn contact_cfm_factor(&self) -> Real {
         // Compute CFM assuming a critically damped spring multiplied by the damping ratio.
-        let inv_erp_minus_one = 1.0 / self.erp() - 1.0;
+        let inv_erp_minus_one = 1.0 / self.contact_erp() - 1.0;
 
         // let stiffness = 4.0 * damping_ratio * damping_ratio * projected_mass
         //     / (dt * dt * inv_erp_minus_one * inv_erp_minus_one);

src/dynamics/solver/contact_constraint/one_body_constraint.rs

@@ -272,9 +272,9 @@ impl OneBodyConstraintBuilder {
         rb2_pos: &Isometry<Real>,
         constraint: &mut OneBodyConstraint,
     ) {
-        let cfm_factor = params.cfm_factor();
+        let cfm_factor = params.contact_cfm_factor();
         let inv_dt = params.inv_dt();
-        let erp_inv_dt = params.erp_inv_dt();
+        let erp_inv_dt = params.contact_erp_inv_dt();
 
         let all_infos = &self.infos[..constraint.num_contacts as usize];
         let all_elements = &mut constraint.elements[..constraint.num_contacts as usize];

src/dynamics/solver/contact_constraint/one_body_constraint_simd.rs

@@ -261,10 +261,10 @@ impl SimdOneBodyConstraintBuilder {
         _multibodies: &MultibodyJointSet,
         constraint: &mut OneBodyConstraintSimd,
     ) {
-        let cfm_factor = SimdReal::splat(params.cfm_factor());
+        let cfm_factor = SimdReal::splat(params.contact_cfm_factor());
         let inv_dt = SimdReal::splat(params.inv_dt());
         let allowed_lin_err = SimdReal::splat(params.allowed_linear_error());
-        let erp_inv_dt = SimdReal::splat(params.erp_inv_dt());
+        let erp_inv_dt = SimdReal::splat(params.contact_erp_inv_dt());
         let max_corrective_velocity = SimdReal::splat(params.max_corrective_velocity());
         let warmstart_coeff = SimdReal::splat(params.warmstart_coefficient);
 

src/dynamics/solver/contact_constraint/two_body_constraint.rs

@@ -373,9 +373,9 @@ impl TwoBodyConstraintBuilder {
         rb2_pos: &Isometry<Real>,
         constraint: &mut TwoBodyConstraint,
     ) {
-        let cfm_factor = params.cfm_factor();
+        let cfm_factor = params.contact_cfm_factor();
         let inv_dt = params.inv_dt();
-        let erp_inv_dt = params.erp_inv_dt();
+        let erp_inv_dt = params.contact_erp_inv_dt();
 
         let all_infos = &self.infos[..constraint.num_contacts as usize];
         let all_elements = &mut constraint.elements[..constraint.num_contacts as usize];

src/dynamics/solver/contact_constraint/two_body_constraint_simd.rs

@@ -250,10 +250,10 @@ impl TwoBodyConstraintBuilderSimd {
         _multibodies: &MultibodyJointSet,
         constraint: &mut TwoBodyConstraintSimd,
     ) {
-        let cfm_factor = SimdReal::splat(params.cfm_factor());
+        let cfm_factor = SimdReal::splat(params.contact_cfm_factor());
         let inv_dt = SimdReal::splat(params.inv_dt());
         let allowed_lin_err = SimdReal::splat(params.allowed_linear_error());
-        let erp_inv_dt = SimdReal::splat(params.erp_inv_dt());
+        let erp_inv_dt = SimdReal::splat(params.contact_erp_inv_dt());
         let max_corrective_velocity = SimdReal::splat(params.max_corrective_velocity());
         let warmstart_coeff = SimdReal::splat(params.warmstart_coefficient);
 

src_testbed/ui.rs

@@ -173,19 +173,19 @@ pub fn update_ui(
 
             let mut substep_params = *integration_parameters;
             substep_params.dt /= substep_params.num_solver_iterations.get() as Real;
-            let curr_erp = substep_params.erp();
+            let curr_erp = substep_params.contact_erp();
-            let curr_cfm_factor = substep_params.cfm_factor();
+            let curr_cfm_factor = substep_params.contact_cfm_factor();
             ui.add(
                 Slider::new(
                     &mut integration_parameters.contact_natural_frequency,
-                    0.0..=120.0,
+                    0.01..=120.0,
                 )
                 .text(format!("contacts Hz (erp = {:.3})", curr_erp)),
             );
             ui.add(
                 Slider::new(
                     &mut integration_parameters.contact_damping_ratio,
-                    0.0..=20.0,
+                    0.01..=20.0,
                 )
                 .text(format!(
                     "damping ratio (cfm-factor = {:.3})",