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/coverage.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - '.github/workflows/coverage.yml'
       - 'cmake/**'
+      - 'demo/**'
       - 'src/**'
       - 'tests/**'
       - 'CMakeLists.txt'
@@ -56,6 +57,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 \
             -DCMAKE_BUILD_TYPE=Release \
 

.gitignore

@@ -676,4 +676,6 @@ CMakeGraphVizOptions.cmake
 
 CLAUDE.md
 .claude
-graphify-out
+graphify-out
+__cmake_systeminformation
+simulator_test.glb

.pre-commit-config.yaml

@@ -7,10 +7,8 @@ repos:
     rev: v21.1.2
     hooks:
       - id: clang-format
-        name: clang-format
-        description: "Use clang-format to format C/C++ code"
-        entry: clang-format
         args:
+          - -i
           - --style=file
           - --verbose
         files: '\.(c|cc|cpp|h|hpp|tpp|cxx|hh|inl|ipp)$'

CMakeLists.txt

@@ -65,13 +65,34 @@ project(IPCToolkit
         VERSION "1.6.0")
 
 if(IPC_TOOLKIT_TOPLEVEL_PROJECT)
-  option(IPC_TOOLKIT_BUILD_TESTS  "Build unit-tests"       ON)
-  option(IPC_TOOLKIT_BUILD_PYTHON "Build Python bindings" OFF)
+  # Generate a compile_commands.json file
+  set(CMAKE_EXPORT_COMPILE_COMMANDS ${CLO_IPC_TOPLEVEL_PROJECT})
+
+  # If we are on a Mac, explicitly add the sysroot to the compiler flags
+  if(CMAKE_EXPORT_COMPILE_COMMANDS AND APPLE)
+    # CMake usually finds the sysroot automatically, but if it didn't, fetch it
+    if(NOT CMAKE_OSX_SYSROOT)
+      execute_process(COMMAND xcrun --show-sdk-path
+                          OUTPUT_VARIABLE CMAKE_OSX_SYSROOT
+                          OUTPUT_STRIP_TRAILING_WHITESPACE)
+    endif()
+
+    # Force the -isysroot flag into the compile commands for clang-tidy
+    add_compile_options("-isysroot" "${CMAKE_OSX_SYSROOT}")
+  endif()
+endif()
+
+if(IPC_TOOLKIT_TOPLEVEL_PROJECT)
+  option(IPC_TOOLKIT_BUILD_TESTS  "Build unit-tests"          ON)
+  option(IPC_TOOLKIT_BUILD_PYTHON "Build Python bindings"    OFF)
+  option(IPC_TOOLKIT_BUILD_DEMO   "Build the demo simulator"  ON)
 else()
-  # If this is not the top-level project, we don't want to build tests or Python
-  # bindings. This is useful for projects that use IPC Toolkit as a submodule.
-  set(IPC_TOOLKIT_BUILD_TESTS  OFF CACHE BOOL "Build unit-tests"      FORCE)
-  set(IPC_TOOLKIT_BUILD_PYTHON OFF CACHE BOOL "Build Python bindings" FORCE)
+  # If this is not the top-level project, we don't want to build tests, Python
+  # bindings, or the demo simulator. This is useful for projects that use IPC
+  # Toolkit as a submodule.
+  set(IPC_TOOLKIT_BUILD_TESTS  OFF CACHE BOOL "Build unit-tests"          FORCE)
+  set(IPC_TOOLKIT_BUILD_PYTHON OFF CACHE BOOL "Build Python bindings"     FORCE)
+  set(IPC_TOOLKIT_BUILD_DEMO   OFF CACHE BOOL "Build the demo simulator"  FORCE)
 endif()
 
 option(IPC_TOOLKIT_WITH_CUDA                  "Enable CUDA CCD"                               OFF)
@@ -80,6 +101,7 @@ option(IPC_TOOLKIT_WITH_RATIONAL_INTERSECTION "Use rational edge-triangle inters
 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)
@@ -214,6 +236,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
@@ -287,6 +315,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
 ################################################################################
@@ -313,6 +351,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()
 
 ################################################################################

README.md

@@ -24,7 +24,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/ipc_toolkit/ipc_toolkit_tests_data.cmake

@@ -30,7 +30,7 @@ else()
         SOURCE_DIR ${IPC_TOOLKIT_TESTS_DATA_DIR}
 
         GIT_REPOSITORY https://github.com/ipc-sim/ipc-toolkit-tests-data.git
-        GIT_TAG c7eba549d9a80d15569a013c473f0aff104ac44a
+        GIT_TAG 5f455c16f461e56d68e9241fa038bd20d95bce0a
 
         CONFIGURE_COMMAND ""
         BUILD_COMMAND ""

cmake/ipc_toolkit/ipc_toolkit_use_colors.cmake

@@ -13,17 +13,6 @@ include_guard(GLOBAL)
 
 # options
 if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "MSVC")
-  # Reduce the warning level of external files to the selected value (W1 - only major).
-  # Requires Visual Studio 2017 version 15.7
-  # https://blogs.msdn.microsoft.com/vcblog/2017/12/13/broken-warnings-theory/
-
-  # There is an issue in using these flags in earlier versions of MSVC:
-  # https://developercommunity.visualstudio.com/content/problem/220812/experimentalexternal-generates-a-lot-of-c4193-warn.html
-  if(MSVC_VERSION GREATER 1920)
-      add_compile_options(/experimental:external)
-      add_compile_options(/external:W1)
-  endif()
-
   # When building in parallel, MSVC sometimes fails with the following error:
   # > fatal error C1090: PDB API call failed, error code '23'
   # To avoid this problem, we force PDB write to be synchronous with /FS.

cmake/ipc_toolkit/ipc_toolkit_warnings.cmake

@@ -10,8 +10,22 @@ endif()
 # Flags above don't make sense for MSVC
 if(MSVC)
   set(IPC_TOOLKIT_WARNING_FLAGS
-    /Wall # Display all warnings
-    /MP   # Multi-processor compilation
+    /W4 # High warning level (MSVC equivalent of -Wall -Wextra; /Wall is
+        # unusably noisy, enabling off-by-default warnings like C4711/C4710/
+        # C4514/C4820/C5045)
+    /MP # Multi-processor compilation
+    # Silence /W4 warnings that have no counterpart in our GCC/Clang flag set
+    # (-Wall -Wextra -Wpedantic, with -Wconversion intentionally off), so the
+    # MSVC output matches the other compilers:
+    /wd4250 # 'inherits via dominance' (benign; from virtual inheritance)
+    /wd4244 # conversion, possible loss of data (GCC: -Wconversion, off)
+    /wd4267 # size_t -> smaller conversion   (GCC: -Wconversion, off)
+    /wd4201 # nonstandard nameless struct/union (a GCC/Clang extension)
+    /wd4068 # unknown pragma (cross-compiler #pragma gcc/clang directives)
+    /wd4100 # unreferenced formal parameter. GCC's -Wunused-parameter only
+            # fires here because the Windows CI builds Release: asserts (and the
+            # params they use) are compiled out, and the collision-stencil
+            # virtual overrides legitimately ignore some params.
   )
 else()
   set(IPC_TOOLKIT_WARNING_FLAGS

cmake/recipes/polysolve.cmake

@@ -0,0 +1,37 @@
+# PolySolve (https://github.com/polyfem/polysolve)
+# License: MIT
+if(TARGET polysolve::polysolve)
+    return()
+endif()
+
+message(STATUS "Third-party: creating target 'polysolve::polysolve'")
+
+# 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.)
+set(POLYSOLVE_WITH_ACCELERATE OFF CACHE BOOL "Enable Apple Accelerate" FORCE)
+set(POLYSOLVE_WITH_AMGCL      OFF CACHE BOOL "Use AMGCL"               FORCE)
+set(POLYSOLVE_WITH_CHOLMOD    OFF CACHE BOOL "Enable Cholmod library"  FORCE)
+set(POLYSOLVE_WITH_HYPRE      OFF CACHE BOOL "Enable hypre"            FORCE)
+set(POLYSOLVE_WITH_MKL        OFF CACHE BOOL "Enable MKL library"      FORCE)
+set(POLYSOLVE_WITH_PARDISO    OFF CACHE BOOL "Enable Pardiso library"  FORCE)
+set(POLYSOLVE_WITH_SPECTRA    OFF CACHE BOOL "Enable Spectra library"  FORCE)
+set(POLYSOLVE_WITH_SPQR       OFF CACHE BOOL "Enable SPQR library"     FORCE)
+set(POLYSOLVE_WITH_SUPERLU    OFF CACHE BOOL "Enable SuperLU library"  FORCE)
+set(POLYSOLVE_WITH_TESTS      OFF CACHE BOOL "Build unit-tests"        FORCE)
+set(POLYSOLVE_WITH_UMFPACK    OFF CACHE BOOL "Enable UmfPack library"  FORCE)
+
+# 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("gh:polyfem/polysolve#1b01e6cec13c6813ae48846d1f98654bbbf1402b")
+
+# 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,43 @@
+################################################################################
+# 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)
+
+# 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.