This is the opensource reference implementation of the SIGGRAPH 2020 paper Incremental Potential Contact: Intersection- and Inversion-free Large Deformation Dynamics.
src/
: source code
cmake/
and CMakeLists.txt
: CMake files
Format/
: automatic code formatting (requires clang-format
)
input/
: input data and scripts needed to rerun all examples in our paper, together with some tutorial examples
output/
: output data (will be created)
tests/
: unit-tests
tools/
: Python and Bash scripts for generating and processing results
wiki/
: images used in Github wiki page
build.py
: a python script to automatically build IPC with default compiler
batch.py
: a python script to automatically run a batch of examples (in input/n/
by default) with n
threads for each linear solver in the program
batch_tetgen.py
: a python script to automatically tetrahedralize a batch of closed surface meshes using Tetgen
You can either use python build.py
or
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j4
gcc 7 or later is recommended.
-DIPC_WITH_CHOLMOD=OFF
brew install suite-sparse
SuiteSparse/include
and SuiteSparse/lib
to /usr/local/include
and
/usr/local/lib
respectively.sudo apt-get install libsuitesparse-dev libmetis-dev
make library BLAS='-lmkl_intel_lp64 -lmkl_core -lmkl_intel_thread -lpthread -lm -lmkl_blas95_lp64 -liomp5' LAPACK='-lmkl_lapack95_lp64' -j 8
IPC_LINSYSSOLVER
in CMakeLists.txt
. To use custom linear solvers, you can implement a new interface (subclass) to our LinSysSolver
class.-DIPC_WITH_AMGCL=OFF
If your system does not have the required OpenGL libraries, you can disable the viewer using the CMake argument -DIPC_WITH_OPENGL=OFF
. It is important to then run IPC in offline mode (see below).
IPC is only implemented for 3D simulation.
If your system uses Slurm like our cluster does, then you can take advantage of our scripts to build IPC as a batch job.
From the IPC root directory use sbatch build.sh
to compile IPC via a
batch job. You can check the status of the job using
squeue -u $USER -n IPC_build
.
It is important to not build on the login node because while it supports AVX2,
the compute nodes may not. Building on the login node will enable AVX2
support which may cause an Illegal instruction
error when run on a compute
node. Alternatively, this can be fixed by using Intel's compilers, icc
and icpc
, with the
flag -axCORE-AVX2
. This enables executables to run on compute nodes with or
without AVX2 instructions. If the compute nodes support AVX2 instructions,
executables will run AVX2 instructions, otherwise it will use other available
instructions such as AVX or SSE4.2.
IPC contains two optional sub-projects for unit tests, debug, and file processing. To enable them use the CMake
flag -DIPC_BUILD_<sub-project-name>_PROJECT=On
where sub-project-name
is the name
of the sub-project (e.g. DIAGNOSTIC
or MESH_PROCESSING
). You can also set these interactively using ccmake
.
Please see our quick start guide for a hello world
example with various settings. The output of each script will be saved into a separate folder in output/
.
It is possible to run IPC with and without the viewer. By default, the batch.py
script runs IPC with the viewer. If you provide the argument --offline
to batch.py
then it will run IPC in offline mode (i.e. without the viewer).
If you are running the IPC_bin
executable directly then the first argument controls the mode. Mode 10
runs IPC with the viewer and is the default in the batch.py
. Mode 100
runs IPC in offline mode (without the viewer). See IPC_bin --help
for more detail.
From the IPC root directory use sbatch run.sh
to processes all the input
files in input/12/
using 12 CPU cores.
This will process all input scenes in series. I am currently, working on a script to process all scenes in parallel via separate batch jobs.
The executables for the sub-projects are placed in their respective directory
in src/Projects/
.
<n>.obj
: surface mesh of the simulated objects and volumetric/surface kinematic collision objects in n-th time stepn.seg
: mesh file of the segment kinematic collision objects if any in n-th time steppt<n>.obj
: vertex coordinates of the point cloud kinematic collision objects if any in n-th time stepstatus<n>
: saved information of n-th time step that can be used to restart simulation fromACO<m>_<n>.obj
: mesh file of m-th analytical plane if any in n-th (and the following if unchanged) time stepsBC_<n>.txt
: node index of Dirichlet nodes if any in n-th (and the following if unchanged) time steps0.png
: snapshot of initial time stepfinalResult.png
: snapshot of last time stepfinalResult_mesh.msh
: rest shape of simulated objectanim.gif
: animation preview of the simulationconfig.txt
: the config file containing all simulation settings that can be used to rerun the simulationiterStats.txt
: simulation/optimization statistics of each iterationinfo.txt
: timing informationlog.txt
: debug informationsysE.txt
: total energy (kinematic, gravity, and elasticity) of each simulated objectsysL.txt
: linear momentum of each simulated objectsysM.txt
: angular momentum of each simulated objectSee our quick start guide for detailed examples of minimal settings needed for a simulation.
energy {FCR | NH}
NH
: Neo-Hookean elasticity energy (default)FCR
: Fixed Co-rotational elasticity energytimeIntegration {BE | NM} <β> <γ>
BE
: Backward Euler (default)NM
: Newmark (optional: add β and γ to change from default of 0.25 and 0.5)dampingStiff <dampingStiff>
dampingStiff
or not if dampingStiff
is zero or not specifieddampingStiff
must be greater than or equal to zerodampingRatio <dampingRatio>
dampingStiff
to be 0.75 * dampingRatio * h^3
or 0
if dampingRatio
is zero or not specifieddampingRatio
must be greater than or equal to zerotime <num-seconds> <time-step>
density <density>
stiffness <young-modulus> <poisson-ratio>
turnOffGravity
shapes input <num-of-shapes>
<mesh-file-path> <x> <y> <z> <rot-deg-x> <rot-deg-y> <rot-deg-z> <scale-x> <scale-y> <scale-z> <extra-command> ...
<extra-command>
: assigning different materials, initial velocities, boundary conditions, or scripted motions for each shape individually if any
material <density> <young-modulus> <poisson-ratio>
initVel <lvx> <lvy> <lvz> <avx> <avy> <avz>
DBC <left-bottom-back-x> <left-bottom-back-y> <left-bottom-back-z> <right-top-front-x> <right-top-front-y> <right-top-front-z> <lvx> <lvy> <lvz> <avx> <avy> <avz> [<t_begin>] [<t_end>]
NBC <left-bottom-back-x> <left-bottom-back-y> <left-bottom-back-z> <right-top-front-x> <right-top-front-y> <right-top-front-z> <ax> <ay> <az> [<t_begin>] [<t_end>]
linearVelocity <lvx> <lvy> <lvz>
angularVelocity <avx> <avy> <avz>
DBCTimeRange <t_begin> <t_end>
shapes
command during (t_begin, t_end]
, by default (0, +inf]
NBCTimeRange <t_begin> <t_end>
shapes
command during (t_begin, t_end]
, by default (0, +inf]
ground <friction-coefficient> <height>
halfSpace <x> <y> <z> <nx> <ny> <nz> <stiffness> <friction-coefficient>
stiffness
is unusedselfCollisionOff
selfFric <selfFricCoeff>
: specify the friction coefficient of self-contact, by default 0
(no friction)
selfFricCoeff
must be larger or equal to 0
, setting it larger than 1
is alloweddHat <dHat>
: set the distance that IPC sees objects as attaching and exert contact forces, by default it is 1e-3
that of the diagonal length of the bounding box of the scene
dHat
must be larger than 0
epsv <epsv>
: set the relative tangent velocity that IPC sees the attached objects as not sliding and exert static friction forces, by default it is 1e-3
that of the diagonal length of the bounding box of the scene per second
epsv
must be larger than 0
fricIterAmt <fricIterAmt>
: set the maximal friction iterations that IPC updates friction tangent and normal forces, by default it is 1
0
or negative, IPC will update friction tangent and normal forces until convergence (not guaranteed so not recommended)tol positiveInteger
positiveInteger
is also a relative value on the bounding box diagonal lengthconstraintSolver {interiorPoint | QP | SQP}
interiorPoint
: IPC (default)QP
: solve elasticity as a single QP with nonlinear contact constraintsSQP
: solve elasticity as a sequence of quadratic programs with nonlinear contact constraintsrestart <status-file-path-str>
view {orthographic | perspective}
zoom <positive-real-number>
cameraTracking
playBackSpeed <playBackSpeed>
anim.gif
, which also controls how many frame data will be output (smaller value results in more output (at most output every frame))appendStr <str>
disableCout
section {interiorPoint | QP | penalty}
section end
is encountered or at the end
of a file.constraintSolver QP
# ...
section QP
constraintType graphics
section end
Some of our settings are legacy settings or the ones that are not usually used/recommended. We include them here for completeness as they have been used by our paper examples or tests.
The following settings only affect the QP and SQP contact constraint solvers we use for comparisons.
QPSolver {OSQP | Gurobi}
constraintType {volume | graphics | gapFunction | nonsmoothNewmark | CMR | Verschoor}
volume
)volume
: measure the volume of a tetrahedron comprised of the colliding pointsgraphics
: distance constraint from Harmon et al. [2008].nonsmoothNewmark
: variation of volume constraints proposed by Kane et al. [1999].gapFunction
: signed distance along the normal direction from the point of intersection.CMR
: constraint manifold refinement (same as standard graphics approach).Verschoor
: Variant of standard graphics approach by Verschoor and Jalba [2019].constraintOffset <offset>
constraintSolver QP
/SQP
useActiveSetConvergence
We conducted a lengthy comparison of our method and several other commercial and open-source software, and "vanilla" implementations of other methods. You can read the full details in Supplement B.
You can find the scenes, meshes, and other files used in these comparisons in
input/paperExamples/supplementB
.
SQPBenchmark
: The collection of scene files used to generate the benchmark
of QP and SQP methods.
tools/run-comparison-benchmark-sqp.sh
tools/run-comparison-benchmark-hpc.sh
COMSOL
: The 2D COMSOL files used in our comparisonHoudini
: The Houdini files used to generate the chain comparisonSOFA
: The SOFA scene files used to compare against SOFAUtopia
: The mesh and IPC script used to compare against Utopia [Krause and Zulian 2016]The tests
directory contains a very limited number of unit-tests. These tests
use Catch2 which is downloaded through
CMake unless the option -DIPC_WITH_TESTS=OFF
is provided. Currently, these
test contain test the collision constraints used by the SQP solver.
The tools
directory contains several tools for generating meshes, running
scenes, and processing results.
convert_to_ipc_msh.py
: this script uses PyMesh
to convert a tetrahedral mesh to the expected .msh
format of IPC
geo_to_msh.py
: this script uses PyMesh
to convert a GEO (format exported by Houdini) format mesh to a standard MSH meshgenerate_chain_scene.py
: generate a IPC script for a variable length chainrun-comparison-benchmark-sqp.sh
: run the comparison SQP benchmark with default settingsrun-comparison-benchmark-hpc.sh
: run the comparison full sweep of the SQP benchmark
hpc-job.sh
scriptprocess_*_results.py
: process the benchmark results, generating a CSV of the table