ipc-sim · zfergus · Jun 29, 2025 · Jun 29, 2025
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -307,7 +307,7 @@ Added
 Changed
 ^^^^^^^
 
-* Changed CMake target name to :cmake:`ipc::toolkit`
+* Changed CMake target name to ``ipc::toolkit``
 
 2021-07-26 (`1479aae <https://github.com/ipc-sim/ipc-toolkit/commit/1479aaea958daaa4e963529493e4169dc7757913>`__)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -317,7 +317,7 @@ Changed
 Changed
 ^^^^^^^
 
-* Updated the CMake system to use modern :cpp:`FetchContent` to download externals
+* Updated the CMake system to use modern ``FetchContent`` to download externals
 
 2021-07-22 (`e24c76d <https://github.com/ipc-sim/ipc-toolkit/commit/e24c76ddc818fb9efc4d522ef72a581a15abf751>`__)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -414,7 +414,7 @@ Changed
 ^^^^^^^
 
 * :cpp:`ignore_codimensional_vertices` to :cpp:`false` by default
-* CMake option :cmake:`TIGHT_INCLUSION_WITH_NO_ZERO_TOI=ON` as default
+* CMake option ``TIGHT_INCLUSION_WITH_NO_ZERO_TOI=ON`` as default
 
 2021-06-18 (`aa59aeb <https://github.com/ipc-sim/ipc-toolkit/commit/aa59aeb0634af981a8f1cfbb6d2ff2b76a04d610>`__)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -21,7 +21,10 @@
 # -- Project information -----------------------------------------------------
 
 from datetime import datetime
-import ipctk
+
+import sys
+sys.path.append(str(pathlib.Path(__file__).parents[2] / "python"))
+from _find_ipctk import ipctk  # noqa
 
 project = "IPC Toolkit"
 copyright = f'2020-{datetime.now().year}, IPC-Sim Organization; MIT License'

diff --git a/docs/source/cpp-api/barrier.rst b/docs/source/cpp-api/barrier.rst
@@ -20,7 +20,7 @@ Adaptive Barrier Stiffness
 Semi-Implicit Stiffness
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. doxygenfunction:: ipc::semi_implicit_stiffness(const CollisionMesh&, const Eigen::MatrixXd&, const StencilsT&, const Eigen::VectorXd&, const Eigen::SparseMatrix<double>&, const double)
+.. doxygenfunction:: ipc::semi_implicit_stiffness(const CollisionMesh&, Eigen::ConstRef<Eigen::MatrixXd>, const StencilsT&, Eigen::ConstRef<Eigen::VectorXd>, const Eigen::SparseMatrix<double>&, const double)
 
 Barrier Class
 -------------
@@ -34,10 +34,10 @@ Clamped Log Barrier
 .. doxygenclass:: ipc::ClampedLogBarrier
     :allow-dot-graphs:
 
-Normalized Clamped Log Barrier
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Normalized Barrier
+~~~~~~~~~~~~~~~~~~
 
-.. doxygenclass:: ipc::NormalizedClampedLogBarrier
+.. doxygenclass:: ipc::NormalizedBarrier
     :allow-dot-graphs:
 
 Clamped Log Squared Barrier

diff --git a/docs/source/cpp-api/distance.rst b/docs/source/cpp-api/distance.rst
@@ -19,11 +19,11 @@ Edge-Edge Mollifier
 .. doxygenfunction:: edge_edge_cross_squarednorm
 .. doxygenfunction:: ipc::edge_edge_cross_squarednorm_gradient
 .. doxygenfunction:: ipc::edge_edge_cross_squarednorm_hessian
-.. doxygenfunction:: edge_edge_mollifier(const Eigen::Ref<const Eigen::Vector3d>& ea0, const Eigen::Ref<const Eigen::Vector3d>& ea1, const Eigen::Ref<const Eigen::Vector3d>& eb0, const Eigen::Ref<const Eigen::Vector3d>& eb1, const double eps_x)
+.. doxygenfunction:: edge_edge_mollifier(Eigen::ConstRef<Eigen::Vector3d> ea0, Eigen::ConstRef<Eigen::Vector3d> ea1, Eigen::ConstRef<Eigen::Vector3d> eb0, Eigen::ConstRef<Eigen::Vector3d> eb1, const double eps_x)
 .. doxygenfunction:: edge_edge_mollifier(const double x, const double eps_x)
-.. doxygenfunction:: edge_edge_mollifier_gradient(const Eigen::Ref<const Eigen::Vector3d>& ea0, const Eigen::Ref<const Eigen::Vector3d>& ea1, const Eigen::Ref<const Eigen::Vector3d>& eb0, const Eigen::Ref<const Eigen::Vector3d>& eb1, const double eps_x)
+.. doxygenfunction:: edge_edge_mollifier_gradient(Eigen::ConstRef<Eigen::Vector3d> ea0, Eigen::ConstRef<Eigen::Vector3d> ea1, Eigen::ConstRef<Eigen::Vector3d> eb0, Eigen::ConstRef<Eigen::Vector3d> eb1, const double eps_x)
 .. doxygenfunction:: edge_edge_mollifier_gradient(const double x, const double eps_x)
-.. doxygenfunction:: edge_edge_mollifier_hessian(const Eigen::Ref<const Eigen::Vector3d>& ea0, const Eigen::Ref<const Eigen::Vector3d>& ea1, const Eigen::Ref<const Eigen::Vector3d>& eb0, const Eigen::Ref<const Eigen::Vector3d>& eb1, const double eps_x)
+.. doxygenfunction:: edge_edge_mollifier_hessian(Eigen::ConstRef<Eigen::Vector3d> ea0, Eigen::ConstRef<Eigen::Vector3d> ea1, Eigen::ConstRef<Eigen::Vector3d> eb0, Eigen::ConstRef<Eigen::Vector3d> eb1, const double eps_x)
 .. doxygenfunction:: edge_edge_mollifier_hessian(const double x, const double eps_x)
 
 Edge-Edge
@@ -57,12 +57,12 @@ Point-Line
 Point-Plane
 -----------
 
-.. doxygenfunction:: point_plane_distance(const Eigen::Ref<const Eigen::Vector3d>& p, const Eigen::Ref<const Eigen::Vector3d>& origin, const Eigen::Ref<const Eigen::Vector3d>& normal)
-.. doxygenfunction:: point_plane_distance(const Eigen::Ref<const Eigen::Vector3d>& p, const Eigen::Ref<const Eigen::Vector3d>& t0, const Eigen::Ref<const Eigen::Vector3d>& t1, const Eigen::Ref<const Eigen::Vector3d>& t2)
-.. doxygenfunction:: point_plane_distance_gradient(const Eigen::Ref<const Eigen::Vector3d>& p, const Eigen::Ref<const Eigen::Vector3d>& origin, const Eigen::Ref<const Eigen::Vector3d>& normal)
-.. doxygenfunction:: point_plane_distance_gradient(const Eigen::Ref<const Eigen::Vector3d>& p, const Eigen::Ref<const Eigen::Vector3d>& t0, const Eigen::Ref<const Eigen::Vector3d>& t1, const Eigen::Ref<const Eigen::Vector3d>& t2)
-.. doxygenfunction:: point_plane_distance_hessian(const Eigen::Ref<const Eigen::Vector3d>& p, const Eigen::Ref<const Eigen::Vector3d>& origin, const Eigen::Ref<const Eigen::Vector3d>& normal)
-.. doxygenfunction:: point_plane_distance_hessian(const Eigen::Ref<const Eigen::Vector3d>& p, const Eigen::Ref<const Eigen::Vector3d>& t0, const Eigen::Ref<const Eigen::Vector3d>& t1, const Eigen::Ref<const Eigen::Vector3d>& t2)
+.. doxygenfunction:: point_plane_distance(Eigen::ConstRef<Eigen::Vector3d> p, Eigen::ConstRef<Eigen::Vector3d> origin, Eigen::ConstRef<Eigen::Vector3d> normal)
+.. doxygenfunction:: point_plane_distance(Eigen::ConstRef<Eigen::Vector3d> p, Eigen::ConstRef<Eigen::Vector3d> t0, Eigen::ConstRef<Eigen::Vector3d> t1, Eigen::ConstRef<Eigen::Vector3d> t2)
+.. doxygenfunction:: point_plane_distance_gradient(Eigen::ConstRef<Eigen::Vector3d> p, Eigen::ConstRef<Eigen::Vector3d> origin, Eigen::ConstRef<Eigen::Vector3d> normal)
+.. doxygenfunction:: point_plane_distance_gradient(Eigen::ConstRef<Eigen::Vector3d> p, Eigen::ConstRef<Eigen::Vector3d> t0, Eigen::ConstRef<Eigen::Vector3d> t1, Eigen::ConstRef<Eigen::Vector3d> t2)
+.. doxygenfunction:: point_plane_distance_hessian(Eigen::ConstRef<Eigen::Vector3d> p, Eigen::ConstRef<Eigen::Vector3d> origin, Eigen::ConstRef<Eigen::Vector3d> normal)
+.. doxygenfunction:: point_plane_distance_hessian(Eigen::ConstRef<Eigen::Vector3d> p, Eigen::ConstRef<Eigen::Vector3d> t0, Eigen::ConstRef<Eigen::Vector3d> t1, Eigen::ConstRef<Eigen::Vector3d> t2)
 
 Point-Point
 -----------

diff --git a/docs/source/cpp.rst b/docs/source/cpp.rst
@@ -24,7 +24,7 @@ C++
     :end-before: <!--- BEGIN C++ README 2 --->
 
 .. tip::
-   If your :cmake:`IPC_TOOLKIT_GIT_TAG` is a tag (e.g. ``v1.3.1``), then you can use the :cmake:`FetchContent_Declare` argument :cmake:`GIT_SHALLOW TRUE` to download only a single commit. Otherwise, you should use the default :cmake:`GIT_SHALLOW FALSE`.
+   If your ``IPC_TOOLKIT_GIT_TAG`` is a tag (e.g. ``v1.3.1``), then you can use the ``FetchContent_Declare`` argument ``GIT_SHALLOW TRUE`` to download only a single commit. Otherwise, you should use the default ``GIT_SHALLOW FALSE``.
 
 .. include:: ../../README.md
     :parser: myst_parser.sphinx_
@@ -34,7 +34,7 @@ C++
 .. _filib_dependency_note:
 
 .. warning::
-    ``filib`` is licensed under `LGPL-2.1 <https://github.com/zfergus/filib/blob/main/LICENSE>`_ and as such it is required to be dynamically linked. Doing so automatically is a challenge, so by default we use static linkage. Enabling dynaic linkage requires copying the ``.so``/``.dylib``/``.dll`` file to the binary directory or system path. To enable this, set the CMake option :cmake:`FILIB_BUILD_SHARED_LIBS` to :cmake:`ON` and add this CMake code to copy the shared libaray object to the binary directory:
+    ``filib`` is licensed under `LGPL-2.1 <https://github.com/zfergus/filib/blob/main/LICENSE>`_ and as such it is required to be dynamically linked. Doing so automatically is a challenge, so by default we use static linkage. Enabling dynaic linkage requires copying the ``.so``/``.dylib``/``.dll`` file to the binary directory or system path. To enable this, set the CMake option ``FILIB_BUILD_SHARED_LIBS`` to ``ON`` and add this CMake code to copy the shared libaray object to the binary directory:
 
     .. code-block:: cmake
 
@@ -47,7 +47,7 @@ C++
 
     where ``${MY_EXE_TARGET}`` is the name of your executable target. If you know a better way to handle this, please `let us know <https://github.com/ipc-sim/ipc-toolkit/discussions>`_!
 
-    If you would rather avoid LGPL code entirely, you can disable filib by setting :cmake:`IPC_TOOLKIT_WITH_FILIB` to :cmake:`OFF`. With this option disabled, CMake will not download or use any of filib's code.
+    If you would rather avoid LGPL code entirely, you can disable filib by setting ``IPC_TOOLKIT_WITH_FILIB`` to ``OFF``. With this option disabled, CMake will not download or use any of filib's code.
 
 .. include:: ../../README.md
     :parser: myst_parser.sphinx_

diff --git a/docs/source/tutorial/faq.rst b/docs/source/tutorial/faq.rst
@@ -13,7 +13,7 @@ Frequently Asked Questions
 How do I include IPC Toolkit in my project?
 -------------------------------------------
 
-If you are using CMake, the public include directory is added to the :cmake:`ipc::toolkit` cmake target which means that any lib/bin that includes :cmake:`ipc::toolkit` as a dependency also adds those include directories too.
+If you are using CMake, the public include directory is added to the `ipc::toolkit` cmake target which means that any lib/bin that includes `ipc::toolkit` as a dependency also adds those include directories too.
 
 If you are not using CMake, the include path is ``src``.
 

diff --git a/docs/source/tutorial/nonlinear_ccd.rst b/docs/source/tutorial/nonlinear_ccd.rst
@@ -57,15 +57,17 @@ Let's dive deeper by breaking down the implementation of ``Rigid2DTrajectory``.
 
         .. literalinclude:: ../../../tests/src/tests/ccd/test_nonlinear_ccd.cpp
             :language: c++
-            :lines: 127-134
+            :start-after: // BEGIN_RIGID_2D_CALL
+            :end-before: // END_RIGID_2D_CALL
             :dedent: 4
 
 
     .. md-tab-item:: Python
 
         .. literalinclude:: ../../../python/tests/test_ccd.py
             :language: python
-            :lines: 90-94
+            :start-after: # BEGIN_RIGID_2D_CALL
+            :end-before: # END_RIGID_2D_CALL
             :dedent: 8
 
 This function computes the position of the point at a time :math:`t \in [0, 1]`. This defines the trajectory of the point. In this case, we have a rigid body with a center of mass (COM) at the origin. The trajectory of the point is given by:
@@ -87,14 +89,16 @@ The second function we need to implement is ``max_distance_from_linear``.
 
         .. literalinclude:: ../../../tests/src/tests/ccd/test_nonlinear_ccd.cpp
             :language: c++
-            :lines: 136-147
+            :start-after: // BEGIN_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
+            :end-before: // END_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
             :dedent: 4
 
     .. md-tab-item:: Python
 
         .. literalinclude:: ../../../python/tests/test_ccd.py
             :language: python
-            :lines: 96-102
+            :start-after: # BEGIN_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
+            :end-before: # END_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
             :dedent: 8
 
 This function computes the maximum distance over a time interval :math:`[t_0, t_1]` between the nonlinear trajectory and a line segment from :math:`x(t_0)` to :math:`x(t_1)`. Mathematically this function computes

diff --git a/notebooks/find_ipctk.py b/notebooks/find_ipctk.py
@@ -1,20 +1,4 @@
-try:
-    import ipctk  # Try to import the built module
-except ImportError:
-    import sys
-    import pathlib
-    repo_root = pathlib.Path(__file__).parents[1]
-    possible_paths = [
-        pathlib.Path("python").resolve(),
-        repo_root / "build" / "python",
-        repo_root / "build" / "release" / "python",
-        repo_root / "build" / "debug" / "python",
-    ]
-    for path in possible_paths:
-        if path.exists() and len(list(path.glob("ipctk.*"))) > 0:
-            sys.path.append(str(path))
-            break
-    else:
-        raise ImportError("Could not find the ipctk module")
-    print(f"Using found ipctk module at {path}")
-    import ipctk  # Try again
+import sys
+import pathlib
+sys.path.append(str(pathlib.Path(__file__).parents[1] / "python"))
+from _find_ipctk import ipctk  # noqa
diff --git a/python/_find_ipctk.py b/python/_find_ipctk.py
@@ -0,0 +1,20 @@
+try:
+    import ipctk  # Try to import the built module
+except ImportError:
+    import sys
+    import pathlib
+    repo_root = pathlib.Path(__file__).parents[1]
+    possible_paths = [
+        pathlib.Path("python").resolve(),
+        repo_root / "build" / "python",
+        repo_root / "build" / "release" / "python",
+        repo_root / "build" / "debug" / "python",
+    ]
+    for path in possible_paths:
+        if path.exists() and len(list(path.glob("ipctk.*"))) > 0:
+            sys.path.append(str(path))
+            break
+    else:
+        raise ImportError("Could not find the ipctk module")
+    print(f"Using found ipctk module at {path}")
+    import ipctk  # Try again
diff --git a/python/tests/find_ipctk.py b/python/tests/find_ipctk.py
@@ -1,20 +1,4 @@
-try:
-    import ipctk  # Try to import the built module
-except ImportError:
-    import sys
-    import pathlib
-    repo_root = pathlib.Path(__file__).parents[2]
-    possible_paths = [
-        pathlib.Path("python").resolve(),
-        repo_root / "build" / "python",
-        repo_root / "build" / "release" / "python",
-        repo_root / "build" / "debug" / "python",
-    ]
-    for path in possible_paths:
-        if path.exists() and len(list(path.glob("ipctk.*"))) > 0:
-            sys.path.append(str(path))
-            break
-    else:
-        raise ImportError("Could not find the ipctk module")
-    print(f"Using found ipctk module at {path}")
-    import ipctk  # Try again
+import sys
+import pathlib
+sys.path.append(str(pathlib.Path(__file__).parents[1]))
+from _find_ipctk import ipctk  # noqa
diff --git a/python/tests/test_ccd.py b/python/tests/test_ccd.py
@@ -161,19 +161,23 @@ def __init__(self, position, translation, delta_translation, rotation, delta_rot
             self.rotation = rotation
             self.delta_rotation = delta_rotation
 
+        # BEGIN_RIGID_2D_CALL
         def __call__(self, t):
             theta = self.rotation + t * self.delta_rotation
             R = np.array([[np.cos(theta), -np.sin(theta)],
                           [np.sin(theta), np.cos(theta)]])
             return R @ self.position + self.translation + t * self.delta_translation
+        # END_RIGID_2D_CALL
 
+        # BEGIN_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
         def max_distance_from_linear(self, t0, t1):
             if self.delta_rotation * (t1 - t0) >= 2 * np.pi:
                 # This is the most conservative estimate
                 return 2 * np.linalg.norm(self.position)  # 2 * radius
             p_t0 = self(t0)
             p_t1 = self(t1)
             return np.linalg.norm(self((t0 + t1) / 2) - ((p_t1 - p_t0) * 0.5 + p_t0))
+        # END_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
     # END_RIGID_2D_TRAJECTORY
 
     # BEGIN_TEST_RIGID_2D_TRAJECTORY

diff --git a/src/ipc/candidates/collision_stencil.hpp b/src/ipc/candidates/collision_stencil.hpp
@@ -36,7 +36,6 @@ class CollisionStencil {
         Eigen::ConstRef<Eigen::MatrixXi> faces) const = 0;
 
     /// @brief Get the vertex attributes of the collision stencil.
-    /// @tparam T Type of the attributes
     /// @param vertices Vertex attributes
     /// @param edges Collision mesh edges
     /// @param faces Collision mesh faces
@@ -63,7 +62,6 @@ class CollisionStencil {
     }
 
     /// @brief Select this stencil's DOF from the full matrix of DOF.
-    /// @tparam T Type of the DOF
     /// @param X Full matrix of DOF (rowwise).
     /// @param edges Collision mesh edges
     /// @param faces Collision mesh faces

diff --git a/src/ipc/candidates/edge_edge.hpp b/src/ipc/candidates/edge_edge.hpp
@@ -18,6 +18,10 @@ class EdgeEdgeCandidate : virtual public CollisionStencil {
 
     int num_vertices() const override { return 4; };
 
+    /// @brief Get the vertex IDs for the edge-edge pair
+    /// @param edges The edge connectivity matrix
+    /// @param faces The face connectivity matrix
+    /// @return An array of vertex IDs in the order: [ea0i, ea1i, eb0i, eb1i]
     std::array<index_t, 4> vertex_ids(
         Eigen::ConstRef<Eigen::MatrixXi> edges,
         Eigen::ConstRef<Eigen::MatrixXi> faces) const override

diff --git a/src/ipc/candidates/edge_vertex.hpp b/src/ipc/candidates/edge_vertex.hpp
@@ -18,6 +18,10 @@ class EdgeVertexCandidate : virtual public CollisionStencil {
 
     int num_vertices() const override { return 3; };
 
+    /// @brief Get the vertex IDs for the edge-vertex pair
+    /// @param edges The edge connectivity matrix
+    /// @param faces The face connectivity matrix
+    /// @return An array of vertex IDs in the order: [vi, e0i, e1i, -1]
     std::array<index_t, 4> vertex_ids(
         Eigen::ConstRef<Eigen::MatrixXi> edges,
         Eigen::ConstRef<Eigen::MatrixXi> faces) const override

diff --git a/src/ipc/candidates/face_vertex.hpp b/src/ipc/candidates/face_vertex.hpp
@@ -18,6 +18,10 @@ class FaceVertexCandidate : virtual public CollisionStencil {
 
     int num_vertices() const override { return 4; };
 
+    /// @brief Get the vertex IDs for the face-vertex pair
+    /// @param edges The edge connectivity matrix
+    /// @param faces The face connectivity matrix
+    /// @return An array of vertex IDs in the order: [vi, f0i, f1i, f2i]
     std::array<index_t, 4> vertex_ids(
         Eigen::ConstRef<Eigen::MatrixXi> edges,
         Eigen::ConstRef<Eigen::MatrixXi> faces) const override

diff --git a/tests/src/tests/ccd/test_nonlinear_ccd.cpp b/tests/src/tests/ccd/test_nonlinear_ccd.cpp
@@ -126,6 +126,7 @@ class Rigid2DTrajectory : virtual public ipc::NonlinearTrajectory {
     {
     }
 
+    // BEGIN_RIGID_2D_CALL
     VectorMax3d operator()(const double t) const override
     {
         const Eigen::Matrix2d R =
@@ -134,7 +135,9 @@ class Rigid2DTrajectory : virtual public ipc::NonlinearTrajectory {
 
         return R * position + translation + t * delta_translation;
     }
+    // END_RIGID_2D_CALL
 
+    // BEGIN_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
     double
     max_distance_from_linear(const double t0, const double t1) const override
     {
@@ -147,6 +150,7 @@ class Rigid2DTrajectory : virtual public ipc::NonlinearTrajectory {
         const VectorMax3d p_t1 = (*this)(t1);
         return ((*this)((t0 + t1) / 2) - ((p_t1 - p_t0) * 0.5 + p_t0)).norm();
     }
+    // END_RIGID_2D_MAX_DISTANCE_FROM_LINEAR
 
 protected:
     Eigen::Vector2d position;