Update adhesion.rst

Author: zfergus

docs/source/index.rst

@@ -13,6 +13,7 @@
     tutorial/getting_started.rst
     tutorial/convergent.rst
     tutorial/nonlinear_ccd.rst
+    tutorial/adhesion.rst
     tutorial/simulation.rst
     tutorial/misc.rst
     tutorial/faq.rst

docs/source/tutorial/adhesion.rst

@@ -1,34 +1,40 @@
 Adhesion
---------
-Adhesion simulates the sticking interaction between surfaces, such as glue bonding or material contact. 
-Provides functionality to compute normal adhesion (perpendicular forces) and tangential adhesion (parallel forces).
+========
+
+Adhesion simulates the sticking interaction between surfaces, such as glue bonding or material contact.
+
+We provide functionality to compute normal adhesion (perpendicular forces) and tangential adhesion (parallel forces) using the model of :cite:`Fang2023AugmentedStickyInteractions`.
 
 Normal Adhesion
-^^^^^^^^^^^^^^^
+---------------
 
-For a given distance :math:`d`:
+The normal adhesion potential models the attraction force based on the distance between two surfaces.
+
+.. math::
+    A_n(\mathbf{x}) = \sum_{k \in C} a(d_k(\mathbf{x}); \hat{d}_p, \hat{d}_a, Y, \epsilon_c)
 
-- If :math:`d < \hat{d}_p`:
-  
-  .. math::
-     A_n(d) = a_1 \cdot d^2 + c_1, \quad \text{where } a_1 = a_2 \left(1 - \frac{\hat{d}_a}{\hat{d}_p}\right)
+For a given distance :math:`d`:
 
-- If :math:`\hat{d}_p \leq d < \hat{d}_a`:
+.. math::
+    a(d)= \begin{cases}
+    a_2\left(1-\frac{\hat{d}_a}{\hat{d}_p}\right) d^2+a_2\left(\hat{d}_a-\hat{d}_p\right)^2-d_p^2 a_1 & 0<d<\hat{d}_p \\
+    a_2 d^2 - 2 a_2 \hat{d}_a d+a_2 \hat{d}_a^2 & \hat{d}_p \leq d<\hat{d}_a \\
+    0 & \hat{d}_a \leq d
+    \end{cases}
 
-  .. math::
-     A_n(d) = (a_2 \cdot d + b_2) \cdot d + c_2, \quad \text{where } b_2 = -2 a_2 \hat{d}_a, \, c_2 = a_2 \hat{d}_a^2
+and
 
-- If :math:`d \geq \hat{d}_a`:
+.. math::
+    a_2=\frac{Y \varepsilon_c}{2\left(\hat{d}_p-\hat{d}_a\right)}.
 
-  .. math::
-     A_n(d) = 0
+The parameters are:
 
-The normal adhesion potential models the attraction force based on the distance between two surfaces.
+- :math:`\hat{d}_p` (``dhat_p``) is the threshold distance for adhesion (in units of distance) where the largest adhesion force is applied
+- :math:`\hat{d}_a` (``dhat_a``) is the adhesion activation distance (in units of distance), representing the maximum range where adhesion forces are active
+- :math:`Y` (``Y``) is the adhesion stiffness (in units of stress, such as Young's modulus), controlling the intensity of adhesion forces
+- :math:`\epsilon_c` (``eps_c``) is the adhesion coefficient (unitless) that defines the critical strain at which adhesion forces decrease
 
-Here dhat_p (:math:\hat{d}_p) is the threshold distance for adhesion (in units of distance) where the largest adhesion force is applied.
-Here dhat_a (:math:\hat{d}_a) is the adhesion activation distance (in units of distance), representing the maximum range where adhesion forces are active.
-Here Y (:math:Y) is the adhesion stiffness (in units of stress, such as Young's modulus), controlling the intensity of adhesion forces.
-Here eps_c (:math:\epsilon_c) is the adhesion coefficient (unitless) that defines the critical strain at which adhesion forces decrease.
+We can build a normal adhesion potential object and compute the adhesion potential for a given set of normal collisions.
 
 .. md-tab-set::
 
@@ -41,8 +47,8 @@ Here eps_c (:math:\epsilon_c) is the adhesion coefficient (unitless) that define
                 const double Y = 1e3;
                 const double eps_c = 0.5;
 
-                const NormalAdhesionPotential A(dhat_p, dhat_a, Y, eps_c)
-                double adhesion_potential = A(normal_collisions, collision_mesh, displacement);
+                const ipc::NormalAdhesionPotential A_n(dhat_p, dhat_a, Y, eps_c)
+                double adhesion_potential = A_n(normal_collisions, collision_mesh, vertices);
 
     .. md-tab-item:: Python
 
@@ -53,13 +59,13 @@ Here eps_c (:math:\epsilon_c) is the adhesion coefficient (unitless) that define
                 Y = 1e3
                 eps_c = 0.5
 
-                A = NormalAdhesionPotential(dhat_p, dhat_a, Y, eps_c)
-                adhesion_potential = A(normal_collisions, collision_mesh, displacement)
+                A_n = ipctk.NormalAdhesionPotential(dhat_p, dhat_a, Y, eps_c)
+                adhesion_potential = A_n(normal_collisions, collision_mesh, vertices)
 
-Normal Derivatives
+Derivatives
 ^^^^^^^^^^^
 
-We can also compute the first and second derivatives of the normal adhesion potential with respect to the displacement.
+We can also compute the first and second derivatives of the normal adhesion potential with respect to the vertex positions.
 
 .. md-tab-set::
 
@@ -68,39 +74,42 @@ We can also compute the first and second derivatives of the normal adhesion pote
         .. code-block:: c++
 
             Eigen::VectorXd adhesion_potential_grad =
-                A.gradient(normal_collisions, collision_mesh, displacement);
+                A_n.gradient(normal_collisions, collision_mesh, vertices);
 
             Eigen::SparseMatrix<double> adhesion_potential_hess =
-                A.hessian(normal_collisions, collision_mesh, displacement);
+                A_n.hessian(normal_collisions, collision_mesh, vertices);
 
     .. md-tab-item:: Python
 
         .. code-block:: python
 
-            adhesion_potential_grad = A.gradient(
-                normal_collisions, collision_mesh, displacement)
+            adhesion_potential_grad = A_n.gradient(normal_collisions, collision_mesh, vertices)
 
-            adhesion_potential_hess = A.hessian(
-                normal_collisions, collision_mesh, displacement)
+            adhesion_potential_hess = A_n.hessian(normal_collisions, collision_mesh, vertices)
 
 Tangential Adhesion
-^^^^^^^^^^^^^^^
+-------------------
 
 The tangential adhesion potential models resistance to sliding (parallel to surfaces).
 
-For displacement :math:`x`:
+It is structured similar to the friction model with a smooth transition between sticking and sliding and lagged normal forces and tangential bases.
 
-- If :math:`0 \leq x < 2 \varepsilon_a`:
+.. math::
+    A_{t}(\mathbf{u}) = \sum_{k \in C} \mu_a \lambda_{k}^a f_{0}^a(\|\mathbf{T}_k^⊤ \mathbf{u}\|; \epsilon_a)
 
-  .. math::
-     A_t(x) = \frac{x^2}{\varepsilon_a} \left(1 - \frac{y}{3 \varepsilon_a}\right)
+where :math:`C` is the lagged collisions, :math:`\lambda_k^a` is the normal adhesion force magnitude for the :math:`k`-th collision, :math:`\mathbf{T}_k` is the tangential basis for the :math:`k`-th collision, and :math:`f_0^a` is the smooth tangential adhesion function used to approximate the non-smooth transition from sticking to sliding.
 
-- If :math:`x \geq 2 \varepsilon_a`:
+For relative displacement magnitude :math:`y`:
 
-  .. math::
-     A_t(x) = \frac{4 \varepsilon_a}{3}
+.. math::
+    f_0^a(y) = \begin{cases}
+    -\frac{y^3}{3\epsilon_a^2} + \frac{y^2}{\epsilon_a} & 0 < y < 2 \epsilon_a \\
+    \frac{4 \epsilon_a}{3} & 2 \epsilon_a \leq y
+    \end{cases}
 
-Here ``eps_a`` (:math:`\epsilon_a`) is the adhesion threshold (in units of displacement) used to smoothly transition.
+where :math:`\epsilon_a` (``eps_a``) is the adhesion threshold (in units of displacement) used to smoothly transition from sticking to sliding.
+
+We can build a tangential adhesion potential object and compute the adhesion potential for a given set of tangential collisions.
 
 .. md-tab-set::
 
@@ -109,16 +118,16 @@ Here ``eps_a`` (:math:`\epsilon_a`) is the adhesion threshold (in units of displ
         .. code-block:: c++
 
             const double eps_a = 0.01;
-            const TangentialAdhesionPotential A(eps_a);
-            double adhesion_potential = A(tangential_collisions, collision_mesh, displacement);
-    
+            const ipc::TangentialAdhesionPotential A_t(eps_a);
+            double adhesion_potential = A_t(tangential_collisions, collision_mesh, displacement);
+
     .. md-tab-item:: Python
 
         .. code-block:: python
 
             eps_a = 0.01
-            A = TangentialAdhesionPotential(eps_a)
-            adhesion_potential = A(tangential_collisions, collision_mesh, displacement);
+            A_t = ipctk.TangentialAdhesionPotential(eps_a)
+            adhesion_potential = A_t(tangential_collisions, collision_mesh, displacement);
 
 Derivatives
 ^^^^^^^^^^^
@@ -132,17 +141,15 @@ We can also compute the first and second derivatives of the tangential adhesion
         .. code-block:: c++
 
             Eigen::VectorXd adhesion_potential_grad =
-                A.gradient(tangential_collisions, collision_mesh, displacement);
+                A_t.gradient(tangential_collisions, collision_mesh, displacement);
 
             Eigen::SparseMatrix<double> adhesion_potential_hess =
-                A.hessian(tangential_collisions, collision_mesh, displacement);
+                A_t.hessian(tangential_collisions, collision_mesh, displacement);
 
     .. md-tab-item:: Python
 
         .. code-block:: python
 
-            adhesion_potential_grad = A.gradient(
-                tangential_collisions, collision_mesh, displacement)
+            adhesion_potential_grad = A_t.gradient(tangential_collisions, collision_mesh, displacement)
 
-            adhesion_potential_hess = A.hessian(
-                tangential_collisions, collision_mesh, displacement)
+            adhesion_potential_hess = A_t.hessian(tangential_collisions, collision_mesh, displacement)

docs/source/tutorial/getting_started.rst

@@ -132,9 +132,9 @@ This returns a scalar value ``barrier_potential`` which is the sum of the barrie
 Mathematically this is defined as
 
 .. math::
-   B(x) = \sum_{k \in C} b(d_k(x), \hat{d}),
+   B(\mathbf{x}) = \sum_{k \in C} b(d_k(\mathbf{x}); \hat{d}),
 
-where :math:`x` is our deformed vertex positions, :math:`C` is the active collisions, :math:`d_k` is the distance (squared) of the :math:`k`-th active collision, and :math:`b` is IPC's C2-clamped log-barrier function.
+where :math:`\mathbf{x}` is our deformed vertex positions, :math:`C` is the active collisions, :math:`d_k` is the distance (squared) of the :math:`k`-th active collision, and :math:`b` is IPC's C2-clamped log-barrier function.
 
 .. note::
    This is **not** premultiplied by the barrier stiffness :math:`\kappa`.
@@ -392,14 +392,14 @@ Now we can compute the friction dissipative potential using the ``FrictionPotent
 
         .. code-block:: c++
 
-            const FrictionPotential D(eps_v);
+            const ipc::FrictionPotential D(eps_v);
             double friction_potential = D(tangential_collisions, collision_mesh, velocity);
 
     .. md-tab-item:: Python
 
         .. code-block:: python
 
-            D = FrictionPotential(eps_v)
+            D = ipctk.FrictionPotential(eps_v)
             friction_potential = D(tangential_collisions, collision_mesh, velocity)
 
 Here ``eps_v`` (:math:`\epsilon_v`) is the static friction threshold (in units of velocity) used to smoothly transition from dynamic to static friction.
@@ -408,18 +408,18 @@ Here ``eps_v`` (:math:`\epsilon_v`) is the static friction threshold (in units o
    The friction potential is a function of the velocities rather than the positions. We can compute the velocities directly from the current and previous position(s) based on our time-integration scheme. For example, if we are using backward Euler integration, then the velocity is
 
    .. math::
-      v = \frac{x - x^t}{h},
+      \mathbf{v} = \frac{\mathbf{x} - \mathbf{x}^t}{h},
 
-   where :math:`x` is the current position, :math:`x^t` is the previous position, and :math:`h` is the time step size.
+   where :math:`\mathbf{x}` is the current position, :math:`\mathbf{x}^t` is the previous position, and :math:`h` is the time step size.
 
 This returns a scalar value ``friction_potential`` which is the sum of the individual friction potentials.
 
 Mathematically this is defined as
 
 .. math::
-   D(v) = \sum_{k \in C} \mu\lambda_k^nf_0\left(\|T_k^\top v\|, \epsilon_v\right),
+   D(\mathbf{v}) = \sum_{k \in C} \mu\lambda_k^nf_0\left(\|\mathbf{T}_k^\top \mathbf{v}\|; \epsilon_v\right),
 
-where :math:`C` is the lagged collisions, :math:`\lambda_k^n` is the normal force magnitude for the :math:`k`-th collision, :math:`T_k` is the tangential basis for the :math:`k`-th collision, and :math:`f_0` is the smooth friction function used to approximate the non-smooth transition from dynamic to static friction.
+where :math:`C` is the lagged collisions, :math:`\lambda_k^n` is the normal force magnitude for the :math:`k`-th collision, :math:`\mathbf{T}_k` is the tangential basis for the :math:`k`-th collision, and :math:`f_0` is the smooth friction function used to approximate the non-smooth transition from dynamic to static friction.
 
 Derivatives
 ^^^^^^^^^^^