parameters¶
air-density¶
Default Value |
0.001 (float) |
Name |
Air Density |
Description |
Air density for drag and lift force computation. |
air-friction¶
Default Value |
0.2 (float) |
Name |
Air Tangental Friction |
Recommended Range |
0 to 1 |
Description |
When an object is moving in the air, both drag and lift forces are computed. This value controls the ratio of the tangential friction to the normal friction. |
area-density¶
Default Value |
1000.0 (float) |
Name |
Shell Density |
Description |
Material density for the shell. |
area-poiss-rat¶
Default Value |
0.25 (float) |
Name |
Poisson’s Ratio for Shells |
Allowed Range |
0.0 to 0.4999 |
Description |
Poisson’s ratio for the shell material, encoding how much the material responds to compression. 0.0 means the material does not respond to any compression, while 0.5 means completely incompressible. 0.5 leads to numerical instability, so it must be less than 0.5. |
area-young-mod¶
Default Value |
100.0 (float) |
Name |
Young’s Modulus for Shells |
Recommended Range |
100 to 1e4 |
Description |
This value is not the actual Young’s modulus but the one divided by the density of the material. |
auto-save¶
Default Value |
0 (int) |
Name |
Auto Save Interval |
Description |
Interval in frames at which the simulation state is automatically saved. Set to 0 to disable auto-saving. |
barrier¶
Default Value |
“cubic” (str) |
Name |
Barrier Model for Contact |
Choices |
cubic, quad, log |
Description |
Contact barrier potential model. |
bend¶
Default Value |
1.0 (float) |
Name |
Bend Stiffness for Shells |
Recommended Range |
0.0 to 1e2 |
Description |
This bending stiffness not scaled by the density. If you change the density, you need to adjust this value accordingly. This behavior also change by the material thickness. |
bvh-alloc-factor¶
Default Value |
2 (int) |
Name |
Extra Memory Allocation Factor for BVH on the GPU |
Recommended Range |
2 to 3 |
Description |
We pre-allocate the memory for the BVH on the GPU to avoid dynamic memory allocation. BVH size can dynamically grow during the simulation. This number is multiplied to the initial BVH size to allocate the memory. |
ccd-max-iter¶
Default Value |
4096 (int) |
Name |
Maximum CCD Iterations |
Description |
The maximum number of iterations for ACCD. |
ccd-reduction¶
Default Value |
0.01 (float) |
Name |
ACCD Reduction Factor |
Recommended Range |
1e-2 to 0.5 |
Description |
ACCD needs some small number to determine that the gap distance is close enough to the surface. This factor is multiplied to the initial gap to set this threshold. |
cg-max-iter¶
Default Value |
10000 (int) |
Name |
Maximum Number of PCG Iterations |
Description |
When PCG iterations exceed this value, the solver is regarded as diverged. |
cg-tol¶
Default Value |
0.001 (float) |
Name |
Relative Tolerance for PCG |
Recommended Range |
1e-4 to 1e-3 |
Description |
The relative tolerance for the PCG solver. The solver is terminated when the relative residual reaches below this value. |
constraint-ghat¶
Default Value |
0.001 (float) |
Name |
Gap Distance for Boundary Conditions |
Reommended Range |
1e-3 to 1e-2 |
Description |
For boundary conditions such as pinned vertices and wall conditions, this value is used to determine the gap distance to activate the barrier to enforce the boundary conditions. |
constraint-tol¶
Default Value |
0.01 (float) |
Name |
Moving Constraint Minimum Gap Tolerance |
Recommended Range |
1e-3 to 0.1 |
Description |
For moving constraints, the gap distance can be negative at Newton’s steps. This value multiplies the constraint gap is used to cap such small gaps. |
contact-ghat¶
Default Value |
0.001 (float) |
Name |
Contact Gap |
Recommended Range |
0.25e-3 to 1e-2 |
Description |
This value dictates the maximal gap distance when nearly touching objects are considered in contact. A contact barrier is then activated to prevent the objects from penetrating. Since we employ single precision floating point, we recommend setting this value to be larger than 1e-4. |
contact-offset¶
Default Value |
0.0 (float) |
Name |
Shell Contact Offset |
Recommended Range |
0 to 1e-2 |
Description |
This value is used to offset the contact to give a visible thickness to shell contact surfaces. |
csrmat-max-nnz¶
Default Value |
10000000 (int) |
Name |
Maximal Matrix Entries for Contact Matrix Entries on the GPU |
Recommended Range |
1e6 to 1e9 |
Description |
We pre-alocate the contact matrix entries to avoid cost arising from dynamic memory allocation. This value is manually chosen by the user. If this value is too large, the GPU runs out of memory. On the other hand, if this value is too small, the simulation may fail due to the lack of memory for contact matrix assembly. |
disable-strain-limit¶
Default Value |
False (bool) |
Name |
Flag to Disable Strain Limit |
Description |
When this flag is enabled, the strain limit is disabled regardless of strain_limit_eps. |
dt¶
Default Value |
0.001 (float) |
Name |
Step Size |
Recommended Range |
1e-3 to 1e-2 |
Description |
Step size for the simulation. Small step size will make the simulation more accurate. Large step size may make the simulation faster but can introduce noticeable damping. We recommend to use 1e-3 for most cases. Setting a larger value can results in PCG solver divergence. |
eiganalysis-eps¶
Default Value |
0.01 (float) |
Name |
Epsilon for Eigenvalue Analysis |
Recommended Range |
1e-3 to 1e-2 |
Description |
When two singular values are close to each other, our analysis can be unstable as it involves division by the difference of the two singular values. In such cases, we switch to a stable approximation. |
fake-crash-frame¶
Default Value |
-1 (int) |
Name |
Fake Crash Frame |
Description |
Frame number at which to intentionally crash the simulation for testing purposes. Set to -1 to disable fake crashing. |
fitting¶
Default Value |
False (bool) |
Name |
Fitting Mode |
Description |
Enable fitting mode for the simulation. This mode adjusts the simulation step size and disable inertia. |
fix-xz¶
Default Value |
0.0 (float) |
Name |
Whether to fix xz positions |
Description |
For falling objects if their y position is higher than this value, their xz positions are fixed. |
fps¶
Default Value |
60.0 (float) |
Name |
Frame Per Second for Video Frames |
Description |
The time interval for writing meshes are determined by this value so that when a video is generated, the frame rate corresponds to this value. |
frames¶
Default Value |
300 (int) |
Name |
Maximal Frame Count to Simulate |
Description |
This number dictates the maximal number of frames to simulate. |
friction¶
Default Value |
0.5 (float) |
Name |
Friction Coefficient |
Allowed Range |
0 to 1 |
Description |
Friction coefficient for the contact. 0.0 means no friction and 1.0 means full friction. |
friction-eps¶
Default Value |
1e-05 (float) |
Name |
Epsilon for Friction |
Recommended Range |
1e-5 to 1e-4 |
Description |
We employ a quadratic friction model to approximate Coulomb friction. In doing so, we need to set a small value to avoid division by zero. This occurs when the motion undergoes static friction. |
gravity¶
Default Value |
-9.8 (float) |
Name |
Gravity Coefficient |
include-face-mass¶
Default Value |
False (bool) |
Name |
Flag to Include Shell Mass for Volume Solids |
Description |
The mass of volume solids is computed by their tetrahedral elements. If this option is enabled, the mass of the shell is included for the surface elements of the volume solids. |
isotropic-air-friction¶
Default Value |
0.0 (float) |
Name |
Air Dragging Coefficient |
Description |
Per-vertex air dragging coefficient. |
keep-states¶
Default Value |
10 (int) |
Name |
Keep States |
Description |
This parameter specifies the number of simulation states to keep in the output directory. |
line-search-max-t¶
Default Value |
1.25 (float) |
Name |
Extended Line Search Maximum Time |
Recommended Range |
1.25 to 1.75 |
Description |
Continuous Collision Detection (CCD) is used to determine the time of impact (TOI), but if we advance the time to the actual TOI, contact gaps can be nearly zero. Such a small gap can cause the solver to diverge, so we extend the time to the TOI by this factor, and the actual TOI is recaled by dividing by this factor. For example, if the actual TOI is 1.0 and this value is 1.25, the actual TOI is 1.0/1.25. |
load¶
Default Value |
0 (int) |
Name |
Load |
Description |
This parameter specifies the frame number at which the simulation starts. The files associated with this frame number must be present in the output directory. |
max-dx¶
Default Value |
1.0 (float) |
Name |
Maximum Search Direction |
Recommended Range |
0.01m to 1m |
Description |
This parameter defines the maximum allowable search direction magnitude during optimization processes. It helps in controlling the step size and ensuring stability. |
min-newton-steps¶
Default Value |
0 (int) |
Name |
Lower Bound of Newton Steps |
Recommended Range |
0 to 32 |
Description |
Minimal Newton’s steps that must be consumed to advance a step. The solver tries to determine the actual Newton’s step count, but this number assumes that static friction is not present. If static friction is present, we recommend setting this value to 32. Also, the step size should be somewhat large (e.g., 1e-2) to more accurately account for static friction. |
model-shell¶
Default Value |
“baraffwitkin” (str) |
Name |
Constitutive Model for Shells |
Choices |
baraffwitkin, shhk (Stable Neo-Hookean), arap (As-Rigid-As-Possible), stvk (St. Venant-Kirchhoff) |
Description |
Physical model for the Finite Element shell. |
model-tet¶
Default Value |
“snhk” (str) |
Name |
Constitutive Model for Volumetric Solids |
Choices |
snhk (Stable Neo-Hookean), arap (As-Rigid-As-Possible), stvk (St. Venant-Kirchhoff) |
Description |
Physical model for the Finite Element volumetric solid. |
playback¶
Default Value |
1.0 (float) |
Name |
Playback Speed |
Description |
The speed at which the simulation is played back. 1.0 means unaltered playback, values greater than 1.0 speed up the playback, and values less than 1.0 slow down the playback. |
rod-bend¶
Default Value |
2.0 (float) |
Name |
Bend Stiffness for Rods |
Recommended Range |
0.0 to 10 |
Description |
Rod bending stiffness. The actual force is amplified by the rod mass, which includes rod density. |
rod-density¶
Default Value |
1.0 (float) |
Name |
Rod Density |
Description |
Material density per unit length for the rod. |
rod-offset¶
Default Value |
0.005 (float) |
Name |
Rod Contact Offset |
Recommended Range |
0 to 1e-2 |
Description |
This value is used to offset the contact to give a visible thickness to rod contact surfaces. |
rod-young-mod¶
Default Value |
10000.0 (float) |
Name |
Young’s Modulus for Rods |
Recommended Range |
1e3 to 1e6 |
Description |
Unlike shells or volumetric solids, this value is the actual Young’s modulus. |
static-mesh-offset¶
Default Value |
0.0 (float) |
Name |
Offset for Static Mesh |
Recommended Range |
0 to 1e-2 |
Description |
This value is used to offset the contact to give a visible thickness to surfaces on static mesh surfaces. |
stitch-stiffness¶
Default Value |
1.0 (float) |
Name |
Stiffness Factor for Stitches |
Recommended Range |
0.5 to 2.0 |
Description |
Stiffness factor for the stitches. |
strain-limit-eps¶
Default Value |
0.05 (float) |
Name |
Strain Limit Epsilon |
Recommended Range |
0 to 0.05 |
Description |
After the strain limit is activated, this value is used to control the maximal stretch. For example, if this value is 0.05, the maximal stretch ratio is 5%. |
target-toi¶
Default Value |
0.25 (float) |
Name |
Target Accumulated Time of Impact (TOI) |
Recommended Range |
0.1 to 0.5 |
Description |
At each inner Newton’s step, the minimal TOI for continuous collision detection is computed. This TOI is used to rewind back the time to the TOI and a new Newton’s step is computed. We accumulate this TOI, and if the accumulated TOI exceeds this value, we terminate the Newton’s loop and compute the actual step size advanced. |
use-thrust¶
Default Value |
False (bool) |
Name |
Use Thrust |
Description |
When this flag is enabled, the simulation will use Thrust for GPU acceleration. |
volume-density¶
Default Value |
1000.0 (float) |
Name |
Volume Density |
Description |
Material density for the volumetric solid. |
volume-poiss-rat¶
Default Value |
0.35 (float) |
Name |
Poisson’s Ratio for Volume Solids |
Allowed Range |
0.0 to 0.4999 |
Description |
Poisson’s ratio for the volumetric solid material, encoding how much the material responds to compression. 0.0 means the material does not respond to any compression, while 0.5 means completely incompressible. 0.5 leads to numerical instability, so it must be less than 0.5. |
volume-young-mod¶
Default Value |
500.0 (float) |
Name |
Young’s Modulus for Volumetric Solids |
Recommended Range |
100 to 1e4 |
Description |
This value is not the actual Young’s modulus but the one divided by the density of the material. |
wind¶
Default Value |
0.0 (float) |
Name |
Wind Coefficient |
Description |
The wind strength. |
wind-dim¶
Default Value |
0 (int) |
Name |
Wind Direction |
Description |
The wind direction. |