Update Docs with NL CCD Tutorial (#78)

* Update docs; add NL CCD tutorial

Author: zfergus

CMakeLists.txt

@@ -59,7 +59,7 @@ endif()
 project(IPCToolkit
         DESCRIPTION "A set of reusable functions to integrate IPC into an existing simulation."
         LANGUAGES CXX
-        VERSION "1.1.1")
+        VERSION "1.2.0")
 
 option(IPC_TOOLKIT_BUILD_TESTS                "Build unit-tests"  ${IPC_TOOLKIT_TOPLEVEL_PROJECT})
 option(IPC_TOOLKIT_BUILD_PYTHON               "Build Python bindings"                         OFF)

README.md

@@ -26,6 +26,8 @@ IPC Toolkit is a set of reusable functions to integrate Incremental Potential Co
 
 This is not a full simulation library. As such it does not include any physics or solvers. For a full simulation implementation, we recommend [PolyFEM](https://polyfem.github.io/) (a finite element library) or [Rigid IPC](https://github.com/ipc-sim/rigid-ipc) (rigid-body dynamics) both of which utilize the IPC Toolkit.
 
+<!--- BEGIN C++ README 1 --->
+
 ## Build
 
 The easiest way to add the toolkit to an existing CMake project is to download it through CMake.
@@ -53,6 +55,8 @@ target_link_libraries(${PROJECT_NAME} PUBLIC ipc::toolkit)
 
 where `PROJECT_NAME` is the name of your library/binary.
 
+<!--- BEGIN C++ README 2 --->
+
 ### Dependencies
 
 **All required dependencies are downloaded through CMake** depending on the build options.
@@ -76,7 +80,7 @@ The following libraries are used in this project:
     * Enabled by default
 * [filib](https://github.com/zfergus/filib): interval arithmetic for nonlinear trajectories/CCD
     * Enable by using the CMake option `IPC_TOOLKIT_WITH_FILIB`
-    * Enabled by default 
+    * Enabled by default
 * [rational-cpp](https://github.io/zfergus/rational-cpp): rational arithmetic used for exact intersection checks
     * Enable by using the CMake option `IPC_TOOLKIT_WITH_RATIONAL_INTERSECTION`
     * Requires [GMP](https://gmplib.org/) to be installed at a system level
@@ -87,8 +91,7 @@ The following libraries are used in this project:
 
 ## Usage
 
-The main functionality is provided in the `ipc.hpp` header. Use the prefix directory `ipc` to include all header files (e.g. `#include <ipc/ipc.hpp>`).
-
+See the [tutorial](https://ipctk.xyz/tutorial/getting_started.html) for a quick introduction to the toolkit, or the [documentation](https://ipctk.xyz/cpp.html) for a full reference.
 
 ## Unit Tests
 
@@ -103,11 +106,13 @@ The following are downloaded when unit tests are enabled (`IPC_TOOLKIT_BUILD_TES
 * [finite-diff](https://github.com/zfergus/finite-diff): finite-difference comparisons
 * [Nlohman's JSON library](https://github.com/nlohmann/json): loading test data from JSON files
 
+<!--- END C++ README --->
+
 ## Python Bindings
 
 We provide Python bindings for functions in the toolkit using [pybind11](https://github.com/pybind/pybind11).
 
-For more information see the [Python documentation](https://ipctk.xyz/python/).
+For more information see the [Python documentation](https://ipctk.xyz/python.html).
 
 ## Contributing
 

docs/source/conf.py

@@ -20,10 +20,12 @@
 
 # -- Project information -----------------------------------------------------
 
+import ipctk
+
 project = "IPC Toolkit"
 copyright = '2020-2023, IPC-Sim Organization; MIT License'
 author = "Zachary Ferguson"
-version = "1.1.1"
+version = ipctk.__version__
 
 # -- General configuration ---------------------------------------------------
 

docs/source/cpp.rst

@@ -18,91 +18,15 @@ C++
    :target: https://github.com/ipc-sim/ipc-toolkit/blob/main/LICENSE
    :alt: License
 
-Build
------
-
-The easiest way to add the toolkit to an existing CMake project is to download it through CMake.
-CMake provides functionality for doing this called `FetchContent <https://cmake.org/cmake/help/latest/module/FetchContent.html>`__ (requires CMake ≥ 3.14).
-We use this same process to download all external dependencies.
-
-For example,
-
-.. code:: cmake
-
-   include(FetchContent)
-   FetchContent_Declare(
-       ipc_toolkit
-       GIT_REPOSITORY https://github.com/ipc-sim/ipc-toolkit.git
-       GIT_TAG ${IPC_TOOLKIT_GIT_TAG}
-   )
-   FetchContent_MakeAvailable(ipc_toolkit)
-
-where :cmake:`IPC_TOOLKIT_GIT_TAG` is set to the version of the toolkit you want to use.  This will download and add the toolkit to CMake. The toolkit can then be linked against using
-
-.. code:: cmake
-
-   # Link against the IPC Toolkit
-   target_link_libraries(${PROJECT_NAME} PUBLIC ipc::toolkit)
-
-where :cmake:`PROJECT_NAME` is the name of your library/binary.
+.. include:: ../../README.md
+    :parser: myst_parser.sphinx_
+    :start-after: <!--- BEGIN C++ README 1 --->
+    :end-before: <!--- BEGIN C++ README 2 --->
 
 .. tip::
    If your :cmake:`IPC_TOOLKIT_GIT_TAG` is a tag (e.g. ``v1.1.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`.
 
-Dependencies
-------------
-
-**All required dependencies are downloaded through CMake** depending on the build options.
-
-The following libraries are used in this project:
-
-* `Eigen <https://eigen.tuxfamily.org/>`__: linear algebra
-* `libigl <https://github.com/libigl/libigl>`__: basic geometry functions and predicates
-* `TBB <https://github.com/wjakob/tbb>`__: parallelization
-* `Tight-Inclusion <https://github.com/Continuous-Collision-Detection/Tight-Inclusion>`__: correct (conservative) CCD
-* `spdlog <https://github.com/gabime/spdlog>`__: logging information
-
-Optional
---------
-
-* `robin-map <https://github.com/Tessil/robin-map>`__: faster hash set/map than :cpp:`std::unordered_set`/:cpp:`std::unordered_map`
-
-  * Enable by using the CMake option :cmake:`IPC_TOOLKIT_WITH_ROBIN_MAP`
-  * Enabled by default
-
-* `Abseil <https://abseil.io/>`__: hashing utilities
-
-  * Enable by using the CMake option :cmake:`IPC_TOOLKIT_WITH_ABSEIL`
-  * Enabled by default
-
-* `rational-cpp <https://github.io/zfergus/rational-cpp>`__: rational arithmetic used for exact intersection checks
-
-    * Enable by using the CMake option :cmake:`IPC_TOOLKIT_WITH_RATIONAL_INTERSECTION`
-    * Requires `GMP <https://gmplib.org/>`__ to be installed at a system level
-
-* `Etienne Vouga's Collision Detection Library <https://github.com/evouga/collisiondetection>`__: inexact CCD
-
-  * Included for comparison with the original IPC library
-  * Enable by disabling the CMake option :cmake:`IPC_TOOLKIT_WITH_CORRECT_CCD`
-  * Replaces the default Tight-Inclusion CCD
-
-Usage
------
-
-The main functionality is provided in the ``ipc.hpp`` header. Use the prefix directory ``ipc`` to include all header files (e.g. :cpp:`#include <ipc/ipc.hpp>`).
-
-Unit Tests
-----------
-
-We provide unit tests for ensuring the correctness of our algorithmic pieces. To enable the unit tests use the CMake option :cmake:`IPC_TOOLKIT_BUILD_UNIT_TESTS`.
-
-.. _dependencies-1:
-
-Dependencies
-^^^^^^^^^^^^
-
-The following are downloaded when unit tests are enabled(:cmake:`IPC_TOOLKIT_BUILD_TESTS`)
-
-* `Catch2 <https://github.com/catchorg/Catch2.git>`__: testing framework
-* `finite-diff <https://github.com/zfergus/finite-diff>`__: finite-difference comparisons
-* `Nlohman's JSON library <https://github.com/nlohmann/json>`__: loading test data from JSON files
+.. include:: ../../README.md
+    :parser: myst_parser.sphinx_
+    :start-after: <!--- BEGIN C++ README 2 --->
+    :end-before: <!--- END C++ README --->

docs/source/index.rst

@@ -11,6 +11,7 @@
     :hidden:
 
     tutorial/getting_started.rst
+    tutorial/nonlinear_ccd.rst
     tutorial/simulation.rst
     tutorial/misc.rst
     tutorial/references.rst

docs/source/refs.bib

@@ -2,7 +2,7 @@ @article{Li2020IPC
 	title        = {Incremental Potential Contact: Intersection- and Inversion-free Large Deformation Dynamics},
 	author       = {Minchen Li and Zachary Ferguson and Teseo Schneider and Timothy Langlois and Denis Zorin and Daniele Panozzo and Chenfanfu Jiang and Danny M. Kaufman},
 	year         = 2020,
-	journal      = {ACM Transactions on Graphics (SIGGRAPH)},
+	journal      = {{ACM} Transactions on Graphics ({SIGGRAPH})},
 	volume       = 39,
 	number       = 4,
 	articleno    = 49,
@@ -12,7 +12,7 @@ @article{Li2021CIPC
 	title        = {Codimensional Incremental Potential Contact},
 	author       = {Minchen Li and Danny M. Kaufman and Chenfanfu Jiang},
 	year         = 2021,
-	journal      = {ACM Transactions on Graphics (SIGGRAPH)},
+	journal      = {{ACM} Transactions on Graphics ({SIGGRAPH})},
 	volume       = 40,
 	number       = 4,
 	articleno    = 170,
@@ -31,7 +31,7 @@ @article{Wang2021TightInclusion
 	author       = {Bolun Wang and Zachary Ferguson and Teseo Schneider and Xin Jiang and Marco Attene and Daniele Panozzo},
 	year         = 2021,
 	month        = oct,
-	journal      = {ACM Transactions on Graphics},
+	journal      = {{ACM} Transactions on Graphics},
 	volume       = 40,
 	number       = 5,
 	articleno    = 188,
@@ -57,4 +57,14 @@ @inproceedings{Ferguson2023HighOrderIPC
 	series       = {SIGGRAPH '23},
 	numpages     = 11,
 	note		 = {\url{https://zferg.us/research/high-order-ipc/}}
+}
+@article{Ferguson2021RigidIPC,
+	title     = {Intersection-free Rigid Body Dynamics},
+	author    = {Zachary Ferguson and Minchen Li and Teseo Schneider and Francisca Gil-Ureta and Timothy Langlois and Chenfanfu Jiang and Denis Zorin and Danny M. Kaufman and Daniele Panozzo},
+	year      = 2021,
+	journal   = {{ACM} Transactions on Graphics ({SIGGRAPH})},
+	volume    = 40,
+	number    = 4,
+	articleno = 183,
+	note      = {\url{https://ipc-sim.github.io/rigid-ipc}}
 }

docs/source/tutorial/nonlinear_ccd.rst

@@ -0,0 +1,138 @@
+Nonlinear CCD
+=============
+
+We can also perform CCD of nonlinear trajectories (of linear geometry) using the method of :cite:t:`Ferguson2021RigidIPC`. While :cite:t:`Ferguson2021RigidIPC` introduce their method in the context of rigid bodies, it can be applied to any nonlinear trajectory of linear geometry. The method works by transforming the nonlinear trajectories into (adaptive) piecewise linear trajectories with an envelope/minimum separation around each piece, enclosing the nonlinear trajectory. The method then performs CCD on the piecewise linear trajectories to find the earliest time of impact.
+
+We provide the following functions to perform nonlinear CCD:
+
+.. md-tab-set::
+
+    .. md-tab-item:: C++
+
+        * :cpp:func:`ipc::point_point_nonlinear_ccd`,
+        * :cpp:func:`ipc::point_edge_nonlinear_ccd`,
+        * :cpp:func:`ipc::edge_edge_nonlinear_ccd`, and
+        * :cpp:func:`ipc::point_triangle_nonlinear_ccd`.
+
+        Each of these functions take as input a :cpp:func:`ipc::NonlinearTrajectory` object for the endpoints of the linear geometry.
+
+    .. md-tab-item:: Python
+
+        * :py:func:`ipctk.point_point_nonlinear_ccd`,
+        * :py:func:`ipctk.point_edge_nonlinear_ccd`,
+        * :py:func:`ipctk.edge_edge_nonlinear_ccd`, and
+        * :py:func:`ipctk.point_triangle_nonlinear_ccd`.
+
+        Each of these functions take as input a :py:func:`ipctk.NonlinearTrajectory` object for the endpoints of the linear geometry.
+
+For example, the following code defines a rigid trajectory in 2D in order to perform nonlinear CCD between a point and edge:
+
+.. md-tab-set::
+
+    .. md-tab-item:: C++
+
+        .. literalinclude:: ../../../tests/src/tests/ccd/test_nonlinear_ccd.cpp
+            :language: c++
+            :start-after: // BEGIN_RIGID_2D_TRAJECTORY
+            :end-before: // END_RIGID_2D_TRAJECTORY
+
+    .. md-tab-item:: Python
+
+        .. literalinclude:: ../../../python/tests/test_ccd.py
+            :language: python
+            :start-after: # BEGIN_RIGID_2D_TRAJECTORY
+            :end-before: # END_RIGID_2D_TRAJECTORY
+            :dedent: 4
+
+Defining the Trajectory
+-----------------------
+
+Let's dive deeper by breaking down the implementation of Rigid2DTrajectory. The first function we need to implement is the call operator:
+
+.. md-tab-set::
+
+    .. md-tab-item:: C++
+
+        .. literalinclude:: ../../../tests/src/tests/ccd/test_nonlinear_ccd.cpp
+            :language: c++
+            :lines: 127-134
+            :dedent: 4
+
+
+    .. md-tab-item:: Python
+
+        .. literalinclude:: ../../../python/tests/test_ccd.py
+            :language: python
+            :lines: 88-92
+            :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:
+
+.. math::
+
+    x(t) := R(\theta + t \Delta \theta) \bar{x} + T + t \Delta T
+
+where :math:`\theta` is the angle of rotation about the COM, :math:`T` is the translation of the COM, :math:`\Delta \theta` and :math:`\Delta T` are the updates to :math:`\theta` and :math:`T`, respectively, and :math:`\bar{x}` is the position of the point in the interial frame.
+
+Computing a Conservative Envelope
+---------------------------------
+
+The second function we need to implement is ``max_distance_from_linear``.
+
+.. md-tab-set::
+
+    .. md-tab-item:: C++
+
+        .. literalinclude:: ../../../tests/src/tests/ccd/test_nonlinear_ccd.cpp
+            :language: c++
+            :lines: 136-147
+            :dedent: 4
+
+    .. md-tab-item:: Python
+
+        .. literalinclude:: ../../../python/tests/test_ccd.py
+            :language: python
+            :lines: 94-100
+            :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
+
+.. math::
+
+    \min_{t\in[0, 1]} \|x((t_1 - t_0) t + t_0) - ((x(t_1) - x(t_0))t + x(t_0))\|,
+
+for a given start and end time :math:`t_0` and :math:`t_1`, respectively.
+
+In the case of a 2D rigid body, we can compute this value analytically because we know the :math:`\arg\!\min`:
+
+.. math::
+
+    \underset{t\in[0, 1]}{\arg\!\min} \|x((t_1 - t_0) t + t_0) - ((x(t_1) - x(t_0))t + x(t_0))\| = 0.5,
+
+for :math:`(t_1 - t_0) \Delta \theta \leq \pi/2`, otherwise we can use the most conservative envelope radius of :math:`2 \|\bar{x}\|`.
+
+Performing Nonlinear CCD
+------------------------
+
+Last, we use the ``Rigid2DTrajectory`` to perform nonlinear CCD between a point and edge:
+
+.. md-tab-set::
+
+    .. md-tab-item:: C++
+
+        .. literalinclude:: ../../../tests/src/tests/ccd/test_nonlinear_ccd.cpp
+            :language: c++
+            :start-after: // BEGIN_TEST_RIGID_2D_TRAJECTORY
+            :end-before: // END_TEST_RIGID_2D_TRAJECTORY
+            :dedent: 4
+
+    .. md-tab-item:: Python
+
+        .. literalinclude:: ../../../python/tests/test_ccd.py
+            :language: python
+            :start-after: # BEGIN_TEST_RIGID_2D_TRAJECTORY
+            :end-before: # END_TEST_RIGID_2D_TRAJECTORY
+            :dedent: 4
+
+.. note::
+    We adjust the ``conservative_rescaling`` parameter to get a more accurate time of impact (TOI), but in practice, this is not needed as a more conservative estimate of the TOI is sufficient to avoid penetrations.

notebooks/nonlinear-trajectories.ipynb

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipctk"
-version = "1.1.1"
+version = "1.2.0"
 authors = [{ name = "Zachary Ferguson", email = "[email protected]" }]
 description = "A set of reusable functions to integrate Incremental Potential Contact (IPC) into a simulation."
 readme = "docs/PYPI_README.md"

pyproject.toml

@@ -34,7 +34,7 @@ void define_broad_phase(py::module_& m)
             Construct a registered broad phase object.
 
             Parameters:
-                broad_phase_method: The broad phase method to use.
+                method: The broad phase method to use.
 
             Returns:
                 The constructed broad phase object.