Separate Static and Kinetic Coefficients of Friction (#177)

- Add separate static and kinetic friction coefficients (mu_s, mu_k) to tangential collisions.
- Added `smooth_mu`, `smooth_mu_derivative`, `smooth_mu_f0`, `smooth_mu_f1`, `smooth_mu_f2`, `smooth_mu_f1_over_x`, and `smooth_mu_f2_x_minus_f1_over_x3` functions in `smooth_mu.cpp` and `smooth_mu.hpp` to handle the transition between static and kinetic friction smoothly.
- Implemented unit tests for the smooth friction functions in `test_smooth_mu.cpp`, including gradient and Hessian checks using finite difference methods.
- Introduced smooth friction mollifier functions: `smooth_mu_a0`, `smooth_mu_a1`, `smooth_mu_a2`, `smooth_mu_a1_over_x`, and `smooth_mu_a2_x_minus_mu_a1_over_x3` in `adhesion.cpp` and `adhesion.hpp`.
- Refactored existing friction mollifier functions for improved clarity and performance.
- Added unit tests for the new smooth friction mollifier functions to ensure correctness and stability.
- Enhance documentation for adhesion and friction modules with new `smooth_mu` functions.
- Update bindings to include new `smooth_mu` functionalities.

Author: zfergus

docs/source/cpp-api/adhesion.rst

@@ -27,6 +27,16 @@ Functions
       - The first derivative of the tangential adhesion mollifier function divided by y.
     * - :func:`tangential_adhesion_f2_x_minus_f1_over_x3`
       - The second derivative of the tangential adhesion mollifier function times y minus the first derivative all divided by y cubed.
+    * - :func:`smooth_mu_a0`
+      - Compute the value of the ∫ μ(y) a₁(y) dy, where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+    * - :func:`smooth_mu_a1`
+      - Compute the value of the μ(y) a₁(y), where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+    * - :func:`smooth_mu_a2`
+      - Compute the value of d/dy (μ(y) a₁(y)), where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+    * - :func:`smooth_mu_a1_over_x`
+      - Compute the value of the μ(y) a₁(y) / y, where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+    * - :func:`smooth_mu_a2_x_minus_mu_a1_over_x3`
+      - Compute the value of the [(d/dy μ(y) a₁(y)) ⋅ y - μ(y) a₁(y)] / y³, where a₁ and a₂ are the first and second derivatives of the smooth tangential adhesion mollifier.
 
 
 Normal Adhesion Potential

docs/source/cpp-api/friction.rst

@@ -8,4 +8,16 @@ Smooth Mollifier
 .. doxygenfunction:: smooth_friction_f1
 .. doxygenfunction:: smooth_friction_f2
 .. doxygenfunction:: smooth_friction_f1_over_x
-.. doxygenfunction:: smooth_friction_f2_x_minus_f1_over_x3
+.. doxygenfunction:: smooth_friction_f2_x_minus_f1_over_x3
+
+Smooth :math:`\mu`
+------------------
+
+.. doxygenfunction:: smooth_mu
+.. doxygenfunction:: smooth_mu_derivative
+
+.. doxygenfunction:: smooth_mu_f0
+.. doxygenfunction:: smooth_mu_f1
+.. doxygenfunction:: smooth_mu_f2
+.. doxygenfunction:: smooth_mu_f1_over_x
+.. doxygenfunction:: smooth_mu_f2_x_minus_f1_over_x3

docs/source/python-api/adhesion.rst

@@ -16,4 +16,13 @@ Tangential Adhesion Potential
 .. autofunction:: ipctk.tangential_adhesion_f1
 .. autofunction:: ipctk.tangential_adhesion_f2
 .. autofunction:: ipctk.tangential_adhesion_f1_over_x
-.. autofunction:: ipctk.tangential_adhesion_f2_x_minus_f1_over_x3
+.. autofunction:: ipctk.tangential_adhesion_f2_x_minus_f1_over_x3
+
+Smooth :math:`\mu`
+------------------
+
+.. autofunction:: ipctk.smooth_mu_a0
+.. autofunction:: ipctk.smooth_mu_a1
+.. autofunction:: ipctk.smooth_mu_a2
+.. autofunction:: ipctk.smooth_mu_a1_over_x
+.. autofunction:: ipctk.smooth_mu_a2_x_minus_mu_a1_over_x3

docs/source/python-api/friction.rst

@@ -8,4 +8,15 @@ Smooth Mollifier
 .. autofunction:: ipctk.smooth_friction_f1
 .. autofunction:: ipctk.smooth_friction_f2
 .. autofunction:: ipctk.smooth_friction_f1_over_x
-.. autofunction:: ipctk.smooth_friction_f2_x_minus_f1_over_x3
+.. autofunction:: ipctk.smooth_friction_f2_x_minus_f1_over_x3
+
+Smooth :math:`\mu`
+------------------
+
+.. autofunction:: ipctk.smooth_mu
+.. autofunction:: ipctk.smooth_mu_derivative
+.. autofunction:: ipctk.smooth_mu_f0
+.. autofunction:: ipctk.smooth_mu_f1
+.. autofunction:: ipctk.smooth_mu_f2
+.. autofunction:: ipctk.smooth_mu_f1_over_x
+.. autofunction:: ipctk.smooth_mu_f2_x_minus_f1_over_x3

notebooks/separate_mu.ipynb

@@ -142,4 +142,102 @@ void define_adhesion(py::module_& m)
             The second derivative of the tangential adhesion mollifier function times y minus the first derivative all divided by y cubed.
         )ipc_Qu8mg5v7",
         "y"_a, "eps_a"_a);
+
+    m.def(
+        "smooth_mu_a0", &smooth_mu_a0,
+        R"ipc_Qu8mg5v7(
+        Compute the value of the ∫ μ(y) a₁(y) dy, where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+
+        Note:
+            The `a0`/`a1` are unrelated to the `a0`/`a1` in the normal adhesion.
+
+        Parameters:
+            y: The tangential relative speed.
+            mu_s: Coefficient of static adhesion.
+            mu_k: Coefficient of kinetic adhesion.
+            eps_a: Velocity threshold below which static adhesion force is applied.
+
+        Returns:
+            The value of the integral at y.
+        )ipc_Qu8mg5v7",
+        "y"_a, "mu_s"_a, "mu_k"_a, "eps_a"_a);
+
+    m.def(
+        "smooth_mu_a1", &smooth_mu_a1,
+        R"ipc_Qu8mg5v7(
+        Compute the value of the μ(y) a₁(y), where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+
+        Note:
+            The `a1` is unrelated to the `a1` in the normal adhesion.
+
+        Parameters:
+            y: The tangential relative speed.
+            mu_s: Coefficient of static adhesion.
+            mu_k: Coefficient of kinetic adhesion.
+            eps_a: Velocity threshold below which static adhesion force is applied.
+
+        Returns:
+            The value of the product at y.
+        )ipc_Qu8mg5v7",
+        "y"_a, "mu_s"_a, "mu_k"_a, "eps_a"_a);
+
+    m.def(
+        "smooth_mu_a2", &smooth_mu_a2,
+        R"ipc_Qu8mg5v7(
+        Compute the value of d/dy (μ(y) a₁(y)), where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+
+        Note:
+            The `a1`/`a2` are unrelated to the `a1`/`a2` in the normal adhesion.
+
+        Parameters:
+            y: The tangential relative speed.
+            mu_s: Coefficient of static adhesion.
+            mu_k: Coefficient of kinetic adhesion.
+            eps_a: Velocity threshold below which static adhesion force is applied.
+
+        Returns:
+            The value of the derivative at y.
+        )ipc_Qu8mg5v7",
+        "y"_a, "mu_s"_a, "mu_k"_a, "eps_a"_a);
+
+    m.def(
+        "smooth_mu_a1_over_x", &smooth_mu_a1_over_x,
+        R"ipc_Qu8mg5v7(
+        Compute the value of the μ(y) a₁(y) / y, where a₁ is the first derivative of the smooth tangential adhesion mollifier.
+
+        Notes:
+            The `x` in the function name refers to the parameter `y`.
+            The `a1` is unrelated to the `a1` in the normal adhesion.
+
+        Parameters:
+            y: The tangential relative speed.
+            mu_s: Coefficient of static adhesion.
+            mu_k: Coefficient of kinetic adhesion.
+            eps_a: Velocity threshold below which static adhesion force is applied.
+
+        Returns:
+            The value of the product at y.
+        )ipc_Qu8mg5v7",
+        "y"_a, "mu_s"_a, "mu_k"_a, "eps_a"_a);
+
+    m.def(
+        "smooth_mu_a2_x_minus_mu_a1_over_x3",
+        &smooth_mu_a2_x_minus_mu_a1_over_x3,
+        R"ipc_Qu8mg5v7(
+        Compute the value of the [(d/dy μ(y) a₁(y)) ⋅ y - μ(y) a₁(y)] / y³, where a₁ and a₂ are the first and second derivatives of the smooth tangential adhesion mollifier.
+
+        Notes:
+            The `x` in the function name refers to the parameter `y`.
+            The `a1`/`a2` are unrelated to the `a1`/`a2` in the normal adhesion.
+
+        Parameters:
+            y: The tangential relative speed.
+            mu_s: Coefficient of static adhesion.
+            mu_k: Coefficient of kinetic adhesion.
+            eps_a: Velocity threshold below which static adhesion force is applied.
+
+        Returns:
+            The value of the expression at y.
+        )ipc_Qu8mg5v7",
+        "y"_a, "mu_s"_a, "mu_k"_a, "eps_a"_a);
 }

python/src/adhesion/adhesion.cpp

@@ -86,6 +86,7 @@ PYBIND11_MODULE(ipctk, m)
 
     // friction
     define_smooth_friction_mollifier(m);
+    define_smooth_mu(m);
 
     // implicits
     define_plane_implicit(m);

python/src/bindings.cpp

@@ -122,8 +122,11 @@ void define_tangential_collision(py::module_& m)
             &TangentialCollision::normal_force_magnitude,
             "Normal force magnitude")
         .def_readwrite(
-            "mu", &TangentialCollision::mu,
-            "Ratio between normal and tangential forces (e.g., friction coefficient)")
+            "mu_s", &TangentialCollision::mu_s,
+            "Ratio between normal and static tangential forces (e.g., friction coefficient)")
+        .def_readwrite(
+            "mu_k", &TangentialCollision::mu_k,
+            "Ratio between normal and kinetic tangential forces (e.g., friction coefficient)")
         .def_readwrite("weight", &TangentialCollision::weight, "Weight")
         .def_property(
             "weight_gradient",

python/src/collisions/tangential/tangential_collision.cpp

@@ -16,30 +16,40 @@ void define_tangential_collisions(py::module_& m)
                 double>(&TangentialCollisions::build),
             "mesh"_a, "vertices"_a, "collisions"_a, "normal_potential"_a,
             "normal_stiffness"_a, "mu"_a)
+        .def(
+            "build",
+            py::overload_cast<
+                const CollisionMesh&, Eigen::ConstRef<Eigen::MatrixXd>,
+                const NormalCollisions&, const NormalPotential&, double, double,
+                double>(&TangentialCollisions::build),
+            "mesh"_a, "vertices"_a, "collisions"_a, "normal_potential"_a,
+            "normal_stiffness"_a, "mu_s"_a, "mu_k"_a)
         .def(
             "build",
             [](TangentialCollisions& self, const CollisionMesh& mesh,
                Eigen::ConstRef<Eigen::MatrixXd> vertices,
                const NormalCollisions& collisions,
                const NormalPotential& normal_potential,
                const double normal_stiffness,
-               Eigen::ConstRef<Eigen::VectorXd> mus) {
+               Eigen::ConstRef<Eigen::VectorXd> mu_s,
+               Eigen::ConstRef<Eigen::VectorXd> mu_k) {
                 self.build(
                     mesh, vertices, collisions, normal_potential,
-                    normal_stiffness, mus);
+                    normal_stiffness, mu_s, mu_k);
             },
             "mesh"_a, "vertices"_a, "collisions"_a, "normal_potential"_a,
-            "normal_stiffness"_a, "mus"_a)
+            "normal_stiffness"_a, "mu_s"_a, "mu_k"_a)
         .def(
             "build",
             py::overload_cast<
                 const CollisionMesh&, Eigen::ConstRef<Eigen::MatrixXd>,
                 const NormalCollisions&, const NormalPotential&, const double,
                 Eigen::ConstRef<Eigen::VectorXd>,
+                Eigen::ConstRef<Eigen::VectorXd>,
                 const std::function<double(double, double)>&>(
                 &TangentialCollisions::build),
             "mesh"_a, "vertices"_a, "collisions"_a, "normal_potential"_a,
-            "normal_stiffness"_a, "mus"_a, "blend_mu"_a)
+            "normal_stiffness"_a, "mu_s"_a, "mu_k"_a, "blend_mu"_a)
         .def(
             "__len__", &TangentialCollisions::size,
             "Get the number of friction collisions.")

python/src/collisions/tangential/tangential_collisions.cpp

@@ -1,5 +1,6 @@
 set(SOURCES
   smooth_friction_mollifier.cpp
+  smooth_mu.cpp
 )
 
 target_sources(ipctk PRIVATE ${SOURCES})