Draft: Anisotropic friction

.gitignore

@@ -514,7 +514,7 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-build/
+build*/
 develop-eggs/
 dist/
 downloads/

docs/source/cpp-api/friction.rst

@@ -1,6 +1,12 @@
 Friction
 ========
 
+.. seealso::
+
+    :doc:`/tutorials/advanced_friction` explains the friction model, the
+    static/kinetic transition, and anisotropic usage. Full derivation and
+    plots are in ``notebooks/anisotropic_friction_math.ipynb``.
+
 Smooth Mollifier
 ----------------
 
@@ -20,4 +26,31 @@ Smooth :math:`\mu`
 .. doxygenfunction:: smooth_mu_f1
 .. doxygenfunction:: smooth_mu_f2
 .. doxygenfunction:: smooth_mu_f1_over_x
-.. doxygenfunction:: smooth_mu_f2_x_minus_mu_f1_over_x3
+.. doxygenfunction:: smooth_mu_f2_x_minus_mu_f1_over_x3
+
+Anisotropic Friction Helpers
+-----------------------------
+
+Effective friction follows an elliptical :math:`L^2` projection (matchstick cone):
+
+.. math:: \mu_{\text{eff}} = \sqrt{(\mu_0 t_0)^2 + (\mu_1 t_1)^2}
+
+with :math:`t = \tau / \|\tau\|`.
+
+- Use ``anisotropic_mu_eff_from_tau_aniso`` when you have :math:`\tau_{\text{aniso}}` and need :math:`\mu_s`, :math:`\mu_k` for the smooth transition;
+- use ``anisotropic_mu_eff_f`` when you have the unit direction.
+- Zero ``mu_s_aniso`` and ``mu_k_aniso`` falls back to scalar :math:`\mu_s`, :math:`\mu_k`.
+
+For tangential collision evaluation, effective directional coefficients are used
+as lagged scalars (stored on each collision), i.e., no in-evaluation
+:math:`\partial \mu_{\text{eff}} / \partial \tau` terms are taken in the force
+or Jacobian/Hessian paths. Call
+``TangentialCollisions::update_lagged_anisotropic_friction_coefficients(...)``
+after ``build(...)`` and whenever lagged geometry/velocities used for slip are
+updated (typically each Newton iteration).
+
+See :cite:t:`Erleben2019Matchstick` for the Matchstick model; code: `erleben/matchstick <https://github.com/erleben/matchstick>`_.
+
+.. doxygenfunction:: anisotropic_mu_eff_f
+.. doxygenfunction:: anisotropic_x_from_tau_aniso
+.. doxygenfunction:: anisotropic_mu_eff_from_tau_aniso

docs/source/developers/style_guide.rst

@@ -8,6 +8,11 @@ Code Formatting
 
 We utilize `ClangFormat <https://clang.llvm.org/docs/ClangFormat.html>`_ to automate code formatting. Please format your code before pushing and/or creating a pull request.
 
+- The project uses the root ``.clang-format`` (80 columns, WebKit-based).
+- Under ``tests/``, ``tests/.clang-format`` inherits that style and sets ``SortIncludes: false``.
+- CI runs ClangFormat version 20; format with the same version locally to avoid formatting check failures (e.g. ``clang-format -i`` using version 20, or use the pre-commit hook from :doc:`tools`).
+- clang-tidy uses the same style via ``FormatStyle: file`` (see ``.clang-tidy``).
+
 Additionally, ensure that your code adheres to the project's linting rules. Use the provided linting tools to check for any issues before committing your changes.
 
 Naming conventions

docs/source/developers/tools.rst

@@ -4,7 +4,7 @@ Tools for Developers
 Using Pre-Commit Hooks
 ----------------------
 
-Use the ``.pre-commit-config.yaml`` file to apply clang-format on before commits.
+Use the ``.pre-commit-config.yaml`` file to apply ClangFormat before commits. Use ClangFormat version 20 (see :doc:`style_guide`).
 
 Steps:
 

docs/source/python-api/friction.rst

@@ -1,6 +1,11 @@
 Friction
 ========
 
+.. seealso::
+
+    :doc:`/tutorials/advanced_friction` describes the friction model and
+    anisotropic usage. Additional anisotropic helpers are in :doc:`/cpp-api/friction`.
+
 Smooth Mollifier
 ----------------
 
@@ -19,4 +24,17 @@ Smooth :math:`\mu`
 .. autofunction:: ipctk.smooth_mu_f1
 .. autofunction:: ipctk.smooth_mu_f2
 .. autofunction:: ipctk.smooth_mu_f1_over_x
-.. autofunction:: ipctk.smooth_mu_f2_x_minus_mu_f1_over_x3
+.. autofunction:: ipctk.smooth_mu_f2_x_minus_mu_f1_over_x3
+
+Anisotropic Friction Helpers
+-----------------------------
+
+``anisotropic_mu_eff_f`` implements the elliptical :math:`L^2` (matchstick)
+effective-μ formula (:cite:t:`Erleben2019Matchstick`). The C++ API provides
+``anisotropic_mu_eff_from_tau_aniso`` and related helpers. For
+direction-dependent ellipse axes on tangential collisions, call
+``TangentialCollisions.update_lagged_anisotropic_friction_coefficients`` so
+effective μ matches the lagged slip direction; the built-in friction paths then
+use those lagged scalars (they do not differentiate μ with respect to slip).
+
+.. autofunction:: ipctk.anisotropic_mu_eff_f

docs/source/references.bib

@@ -158,6 +158,17 @@ @inproceedings{Cohen1995ICOLLIDE
   address   = {New York, NY, USA},
   doi       = {10.1145/199404.199437}
 }
+@article{Erleben2019Matchstick,
+  title   = {The Matchstick Model for Anisotropic Friction Cones},
+  author  = {Erleben, K. and Macklin, M. and Andrews, S. and Kry, P. G.},
+  year    = 2019,
+  journal = {Computer Graphics Forum},
+  volume  = 38,
+  number  = 8,
+  pages   = {1--12},
+  doi     = {10.1111/cgf.13885},
+  note    = {\url{https://github.com/erleben/matchstick}}
+}
 @inproceedings{Andrus2025Adopting,
   author = {Andrus, Curtis},
   title = {Adopting Research in Production at Netflix Animation Studios},
@@ -228,7 +239,7 @@ @article{Vidulis2023MultistableElasticKnots
   number = {4},
   issn = {0730-0301},
   doi = {10.1145/3592399},
-  journal = {{ACM} Transactions on Graphics)},
+  journal = {{ACM} Transactions on Graphics},
   month = jul,
   articleno = {73},
   numpages = {16},