Rigid and Affine Body Dynamics

.gitattributes

@@ -1,3 +1,3 @@
 # These files should be ignored from GitHub's language statistics.
-python/example.ipynb linguist-vendored
+python/examples/*.ipynb linguist-vendored
 notebooks/*.ipynb linguist-vendored

.github/workflows/clang-format-check.yml

@@ -5,13 +5,15 @@ on:
       - '.github/workflows/clang-format-check.yml'
       - '.clang-format'
       - 'src/**'
+      - 'demo/**'
       - 'tests/src/**'
       - 'python/src/**'
   pull_request:
     paths:
       - '.github/workflows/clang-format-check.yml'
       - '.clang-format'
       - 'src/**'
+      - 'demo/**'
       - 'tests/src/**'
       - 'python/src/**'
 jobs:
@@ -22,6 +24,7 @@ jobs:
       matrix:
         path:
           - 'src'
+          - 'demo'
           - 'tests/src'
           - 'python/src'
     steps:

.github/workflows/continuous.yml

@@ -130,5 +130,8 @@ jobs:
         run: |
           cmake --build build -j ${{ steps.cpu-cores.outputs.count }} && ccache --show-stats
 
+      # We raise CTest's default 1500 s per-test timeout: "ESP potential 2D
+      # finite differences" alone takes ~1000 s in Windows Debug, and running
+      # alongside the demo simulator tests pushes it past the default.
       - name: Tests
-        run: cd build; ctest --verbose -j ${{ steps.cpu-cores.outputs.count }}
+        run: cd build; ctest --verbose --timeout 3600 -j ${{ steps.cpu-cores.outputs.count }}

.github/workflows/coverage.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - '.github/workflows/coverage.yml'
       - 'cmake/**'
+      - 'demo/**'
       - 'src/**'
       - 'tests/**'
       - 'CMakeLists.txt'
@@ -65,6 +66,8 @@ jobs:
           cd build
           cmake .. \
             -DIPC_TOOLKIT_BUILD_TESTS=ON \
+            -DIPC_TOOLKIT_BUILD_DEMO=ON \
+            -DIPC_TOOLKIT_WITH_GLTF=ON \
             -DIPC_TOOLKIT_WITH_CODE_COVERAGE=ON \
             -DSIMD_CXX_FLAGS=-march=x86-64-v3 \
             -DCMAKE_BUILD_TYPE=Release

.gitignore

@@ -676,4 +676,5 @@ CMakeGraphVizOptions.cmake
 
 .claude
 graphify-out
-__cmake_systeminformation
+__cmake_systeminformation
+simulator_test.glb

CMakeLists.txt

@@ -82,17 +82,20 @@ if(IPC_TOOLKIT_TOPLEVEL_PROJECT)
   endif()
 endif()
 
-# If this is not the top-level project, we don't build tests or Python bindings
-# by default. This is useful for projects that use IPC Toolkit as a submodule.
-option(IPC_TOOLKIT_BUILD_TESTS  "Build unit-tests"      ${IPC_TOOLKIT_TOPLEVEL_PROJECT})
-option(IPC_TOOLKIT_BUILD_PYTHON "Build Python bindings" OFF)
+# If this is not the top-level project, we don't build tests, Python bindings,
+# or the demo simulator by default. This is useful for projects that use IPC
+# Toolkit as a submodule.
+option(IPC_TOOLKIT_BUILD_TESTS  "Build unit-tests"         ${IPC_TOOLKIT_TOPLEVEL_PROJECT})
+option(IPC_TOOLKIT_BUILD_PYTHON "Build Python bindings"    OFF)
+option(IPC_TOOLKIT_BUILD_DEMO   "Build the demo simulator" ${IPC_TOOLKIT_TOPLEVEL_PROJECT})
 
 option(IPC_TOOLKIT_WITH_CUDA                  "Enable CUDA CCD"                               OFF)
 option(IPC_TOOLKIT_WITH_SIMD                  "Enable SIMD"                                    ON)
 option(IPC_TOOLKIT_WITH_RATIONAL_INTERSECTION "Use rational edge-triangle intersection check" OFF)
 option(IPC_TOOLKIT_WITH_ROBIN_MAP             "Use Tessil's robin-map rather than std maps"    ON)
 option(IPC_TOOLKIT_WITH_ABSEIL                "Use Abseil's hash functions"                    ON)
 option(IPC_TOOLKIT_WITH_FILIB                 "Use filib for interval arithmetic"              ON)
+option(IPC_TOOLKIT_WITH_GLTF                  "Enable glTF I/O (tinygltf)"                    OFF)
 option(IPC_TOOLKIT_WITH_INEXACT_CCD           "Use the original inexact CCD method of IPC"    OFF)
 option(IPC_TOOLKIT_WITH_PROFILER              "Enable performance profiler"                   OFF)
 option(IPC_TOOLKIT_WITH_TRACY                 "Enable Tracy frame profiler"                   OFF)
@@ -293,6 +296,12 @@ include(tinyad)
 # TODO: Make this a private dependency once we stop exposing TinyAD types in the public API.
 target_link_libraries(ipc_toolkit PUBLIC TinyAD::TinyAD)
 
+# TinyGLTF
+if(IPC_TOOLKIT_WITH_GLTF)
+  include(tinygltf)
+  target_link_libraries(ipc_toolkit PRIVATE tinygltf::tinygltf)
+endif()
+
 # CCD
 if(IPC_TOOLKIT_WITH_INEXACT_CCD)
   # Etienne Vouga's CTCD Library for the floating point root finding algorithm
@@ -433,6 +442,16 @@ endif()
 # Use C++17
 target_compile_features(ipc_toolkit PUBLIC cxx_std_17)
 
+################################################################################
+# Demo simulator (application-side code: solver, problem glue, stepping loop)
+################################################################################
+
+# Added before the tests and Python bindings so both can optionally include
+# the demo's tests and bindings.
+if(IPC_TOOLKIT_BUILD_DEMO)
+  add_subdirectory(demo)
+endif()
+
 ################################################################################
 # Tests
 ################################################################################
@@ -460,6 +479,17 @@ if(IPC_TOOLKIT_WITH_CODE_COVERAGE AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
     --coverage
     -fprofile-update=atomic
   )
+  if(IPC_TOOLKIT_BUILD_DEMO)
+    target_compile_options(ipc_toolkit_demo PRIVATE
+      -g         # generate debug info
+      --coverage # sets all required flags
+      -fprofile-update=atomic
+    )
+    target_link_options(ipc_toolkit_demo PUBLIC
+      --coverage
+      -fprofile-update=atomic
+    )
+  endif()
 endif()
 
 ################################################################################

CMakePresets.json

@@ -72,7 +72,8 @@
       "cacheVariables": {
         "IPC_TOOLKIT_BUILD_PYTHON": "ON",
         "IPC_TOOLKIT_BUILD_TESTS": "OFF",
-        "IPC_TOOLKIT_WITH_CUDA": "OFF"
+        "IPC_TOOLKIT_WITH_CUDA": "ON",
+        "IPC_TOOLKIT_WITH_GLTF": "ON"
       }
     },
     {

README.md

@@ -26,7 +26,9 @@ IPC Toolkit is a set of reusable functions to integrate Incremental Potential Co
 
 ### Limitations
 
-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.
+This is not a full simulation library. As such, it does not include any 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.
+
+A small demo simulator ([`demo/`](demo)) shows how to assemble the toolkit's components (energies, time integration, and CCD) into a rigid/affine body simulator driven by [polysolve](https://github.com/polyfem/polysolve).
 
 ## Build
 

cmake/recipes/polysolve.cmake

@@ -0,0 +1,62 @@
+# PolySolve (https://github.com/polyfem/polysolve)
+# License: MIT
+if(TARGET polysolve::polysolve)
+    return()
+endif()
+
+message(STATUS "Third-party: creating target 'polysolve::polysolve'")
+
+# Pre-register shared dependencies so this project's pins win over polysolve's
+# older ones (both recipe sets guard on the existing targets): finite-diff
+# 1.0.4 vs 1.0.2 (the tests need fd::finite_jacobian_tensor), nlohmann/json
+# 3.12 vs 3.11, and spdlog 1.17.0 vs 1.9.2.
+include(finite_diff)
+include(json)
+include(spdlog)
+
+include(CPM)
+CPMAddPackage(
+  URI "gh:polyfem/polysolve#1b01e6cec13c6813ae48846d1f98654bbbf1402b"
+  OPTIONS
+    # Only the Eigen built-in linear solvers are needed for the demo simulator;
+    # disable the optional heavyweight backends and their dependency tails.
+    # (Accelerate also conflicts with Eigen's BLAS prototypes on recent macOS SDKs.)
+    "POLYSOLVE_WITH_ACCELERATE OFF"
+    "POLYSOLVE_WITH_AMGCL OFF"
+    "POLYSOLVE_WITH_CHOLMOD OFF"
+    "POLYSOLVE_WITH_HYPRE OFF"
+    "POLYSOLVE_WITH_MKL OFF"
+    "POLYSOLVE_WITH_PARDISO OFF"
+    "POLYSOLVE_WITH_SPECTRA OFF"
+    "POLYSOLVE_WITH_SPQR OFF"
+    "POLYSOLVE_WITH_SUPERLU OFF"
+    "POLYSOLVE_WITH_TESTS OFF"
+    "POLYSOLVE_WITH_UMFPACK OFF"
+)
+
+# polysolve always lists its cuSolver backend (CuSolverDN.cu) as a source, even
+# with POLYSOLVE_WITH_CUSOLVER off. That is harmless until we enable the CUDA
+# language for our own kernels: CMake then compiles the file with nvcc, under
+# polysolve's directory-wide MSVC flags (/experimental:external, /FS, ...),
+# which nvcc reads as extra input files and rejects on Windows. We never use
+# that backend, so we keep the file out of the build.
+set_source_files_properties(
+    "${polysolve_SOURCE_DIR}/src/polysolve/linear/CuSolverDN.cu"
+    TARGET_DIRECTORY polysolve_linear
+    PROPERTIES HEADER_FILE_ONLY ON)
+
+# polysolve also hands consumers a bare /utf-8 on MSVC, which would reach nvcc
+# in our CUDA tests the same way. We limit it to C++ sources; CUDA sources
+# already get -Xcompiler=/utf-8 from ipc_toolkit.
+get_target_property(_polysolve_options polysolve_linear INTERFACE_COMPILE_OPTIONS)
+if(_polysolve_options)
+    list(TRANSFORM _polysolve_options
+        REPLACE "^/utf-8$" "$<$<COMPILE_LANGUAGE:CXX>:/utf-8>")
+    set_target_properties(polysolve_linear PROPERTIES
+        INTERFACE_COMPILE_OPTIONS "${_polysolve_options}")
+endif()
+unset(_polysolve_options)
+
+# Folder name for IDE
+set_target_properties(polysolve PROPERTIES FOLDER "ThirdParty")
+set_target_properties(polysolve_linear PROPERTIES FOLDER "ThirdParty")

cmake/recipes/tinygltf.cmake

@@ -0,0 +1,21 @@
+# TinyGLTF (https://github.com/syoyo/tinygltf)
+# License: MIT
+if(TARGET tinygltf::tinygltf)
+    return()
+endif()
+
+message(STATUS "Third-party: creating target 'tinygltf::tinygltf'")
+
+include(CPM)
+CPMAddPackage(
+    URI "gh:syoyo/tinygltf@2.9.6"
+    DOWNLOAD_ONLY TRUE
+)
+
+add_library(tinygltf)
+add_library(tinygltf::tinygltf ALIAS tinygltf)
+target_sources(tinygltf PRIVATE ${tinygltf_SOURCE_DIR}/tiny_gltf.cc)
+target_include_directories(tinygltf INTERFACE
+    $<BUILD_INTERFACE:${tinygltf_SOURCE_DIR}>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)

demo/CMakeLists.txt

@@ -0,0 +1,52 @@
+################################################################################
+# IPC Toolkit Demo Simulator
+#
+# Application-side code intentionally kept out of the core library: the
+# incremental potential presented to the (polysolve) nonlinear solver and the
+# time-stepping loop. The core library only provides the modular components
+# (energies, time integrators, potentials, and CCD); this target is the living
+# proof that they are easy to assemble into a simulator.
+################################################################################
+
+set(SOURCES
+  src/kinematic_driver.cpp
+  src/kinematic_driver.hpp
+  src/kinematics.cpp
+  src/kinematics.hpp
+  src/simulator.cpp
+  src/simulator.hpp
+)
+
+add_library(ipc_toolkit_demo ${SOURCES})
+add_library(ipc::toolkit::demo ALIAS ipc_toolkit_demo)
+
+target_include_directories(ipc_toolkit_demo PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/src")
+
+# The demo depends on the core library; the core library must never depend on
+# the demo (or on any solver).
+target_link_libraries(ipc_toolkit_demo PUBLIC ipc::toolkit)
+
+# polysolve (nonlinear solver with PolyFEM-grade Newton + line search).
+# PUBLIC: the Simulator IS a polysolve::nonlinear::Problem.
+include(polysolve)
+target_link_libraries(ipc_toolkit_demo PUBLIC polysolve::polysolve)
+
+target_compile_features(ipc_toolkit_demo PUBLIC cxx_std_17)
+
+if(IPC_TOOLKIT_WITH_CUDA)
+  # The demo has no CUDA sources, but CMake still device-links it because it
+  # links the separably compiled core library. That bakes a resolved copy of
+  # the core's device code into libipc_toolkit_demo.a, and nvlink then fails to
+  # resolve the core's device functions when an executable (e.g. the tests)
+  # links both. We leave device linking to the final executable instead.
+  set_target_properties(ipc_toolkit_demo PROPERTIES CUDA_RESOLVE_DEVICE_SYMBOLS OFF)
+endif()
+
+# Folder name for IDE
+set_target_properties(ipc_toolkit_demo PROPERTIES FOLDER "DEMO")
+source_group(TREE "${CMAKE_CURRENT_SOURCE_DIR}" FILES ${SOURCES})
+
+# NOTE: The demo's tests live in the unified ipc_toolkit_tests binary
+# (tests/src/tests/demo/) and its Python bindings in the core ipctk module as
+# the ipctk.demo submodule (demo/python/simulator.cpp); both are added by
+# their respective parent targets when IPC_TOOLKIT_BUILD_DEMO is ON.