⚙️ Simulation Parameters

Application-wide simulation parameters. Accessed via frontend.App.get_default_param() and overridden per session with session.param.set(key, value) / session.param.get(key) (see frontend.ParamManager). Keys use hyphens, not underscores.

air-density

Key	air-density
Default	0.001
Label	Air Density
Description	Air density for drag and lift force computation.

air-friction

Key	air-friction
Default	0.2
Label	Air Tangental Friction
Description	Ratio of tangential friction to normal friction for air drag/lift.

auto-save

Key	auto-save
Default	0
Label	Auto Save Interval
Description	Interval (in frames) for auto-saving simulation state. 0 disables auto-save.

barrier

Key	barrier
Default	'cubic'
Label	Barrier Model for Contact
Description	Contact barrier potential model. Choices: cubic, quad, log.

ccd-eps

Key	ccd-eps
Default	1e-07
Label	ACCD Epsilon
Description	Small thickness tolerance for ACCD gap distance checks.

cg-max-iter

Key	cg-max-iter
Default	10000
Label	Maximum Number of PCG Iterations
Description	PCG solver is regarded as diverged if this is exceeded.

cg-tol

Key	cg-tol
Default	0.001
Label	Relative Tolerance for PCG
Description	Relative tolerance for PCG solver termination.

checkpoints

Key	checkpoints
Default	''
Label	Save Checkpoints
Description	Comma-separated frame indices at which to save a resumable state, independent of the auto-save interval. Empty disables explicit checkpoints.

constraint-ghat

Key	constraint-ghat
Default	0.001
Label	Gap Distance for Boundary Conditions
Description	Gap distance to activate boundary condition barriers.

constraint-tol

Key	constraint-tol
Default	0.01
Label	Moving Constraint Minimum Gap Tolerance
Description	This factor is multiplied to the constraint gap to determine the CCD tolerance for moving constraints.

csrmat-max-nnz

Key	csrmat-max-nnz
Default	10000000
Label	Maximal Matrix Entries for Contact Matrix Entries on the GPU
Description	Pre-allocated contact matrix entries for GPU. Too large may cause OOM, too small may cause failure.

disable-contact

Key	disable-contact
Default	False
Label	Disable Contact
Description	When enabled, the simulation will not perform any contact detection.

dt

Key	dt
Default	0.001
Label	Step Size
Description	Step size for the simulation. Small step size increases accuracy, large step size increases speed but may cause solver divergence.

eiganalysis-eps

Key	eiganalysis-eps
Default	0.01
Label	Epsilon for Eigenvalue Analysis
Description	Epsilon for stable eigenvalue analysis when singular values are close.

fake-crash-frame

Key	fake-crash-frame
Default	-1
Label	Fake Crash Frame
Description	Frame number to intentionally crash simulation for testing. -1 disables.

fix-xz

Key	fix-xz
Default	0.0
Label	Whether to fix xz positions
Description	Fix xz positions for falling objects if y > this value. 0.0 disables. Use an extremely small value if nearly a zero is needed.

fps

Key	fps
Default	60.0
Label	Frame Per Second for Video Frames
Description	Frame rate for output video.

frames

Key	frames
Default	300
Label	Maximal Frame Count to Simulate
Description	Maximal number of frames to simulate.

friction-eps

Key	friction-eps
Default	1e-05
Label	Epsilon for Friction
Description	Small value to avoid division by zero in quadratic friction model.

friction-mode

Key	friction-mode
Default	'min'
Label	Friction Combination Mode
Description	How to combine the friction coefficients of two contacting elements. Choices: min, max, mean. Default min preserves the prior behavior (the more slippery side wins).

gravity

Key	gravity
Default	[0.0, -9.8, 0.0]
Label	Gravity Vector
Description	Gravity acceleration vector (solver Y-up).

inactive-momentum

Key	inactive-momentum
Default	False
Label	Inactive Momentum
Description	Enable inactive momentum mode for the simulation. Adjusts step size and disables inertia.

include-face-mass

Key	include-face-mass
Default	False
Label	Flag to Include Shell Mass for Volume Solids
Description	Include shell mass for surface elements of volume solids.

isotropic-air-friction

Key	isotropic-air-friction
Default	0.0
Label	Air Dragging Coefficient
Description	Per-vertex air dragging coefficient.

keep-states

Key	keep-states
Default	10
Label	Keep States
Description	Number of simulation states to keep in the output directory.

keep-verts

Key	keep-verts
Default	0
Label	Keep Vertices
Description	Number of vertex data files to keep in the output directory. 0 means no limit (unlimited). Minimum is 1 to ensure visualization.

line-search-max-t

Key	line-search-max-t
Default	1.25
Label	Extended Line Search Maximum Time
Description	Factor to extend TOI for CCD to avoid possible solver divergence.

max-dx

Key	max-dx
Default	1.0
Label	Maximum Search Direction
Description	Maximum allowable search direction magnitude during optimization.

max-newton-steps

Key	max-newton-steps
Default	2048
Label	Upper Bound of Newton Steps
Description	Maximum Newton’s steps per substep. An over-constrained configuration (a pinned vertex driven into geometry that cannot yield) otherwise loops forever; this bound turns that into a reported failure. 0 removes the bound.

min-newton-steps

Key	min-newton-steps
Default	0
Label	Lower Bound of Newton Steps
Description	Minimal Newton’s steps to advance a step. Raise it when a frictional scene needs the contact forces resolved more tightly within a step; the friction anchor already lets a loaded contact release at 1.

playback

Key	playback
Default	1.0
Label	Playback Speed
Description	Playback speed. 1.0 is normal, >1.0 is faster, <1.0 is slower.

precond

Key	precond
Default	'block-jacobi'
Label	Linear Solver Preconditioner
Description	Preconditioner for the PCG linear solve. Choices: block-jacobi (3x3 per-vertex diagonal, default; fast with the device-resident PCG loop and does not run out of memory on heavy-contact scenes), schwarz (additive aggregate-Schwarz; fewer iterations on mixed stiff/soft systems but heavier per iteration and can OOM on large contact counts; its level count is set by schwarz-levels).

save-state-on-finish

Key	save-state-on-finish
Default	False
Label	Save State on Finish
Description	Save the simulation state on the final frame before the solver exits, even when auto-save is off.

schwarz-levels

Key	schwarz-levels
Default	2
Label	Schwarz Levels
Description	Number of additive levels for the Schwarz preconditioner (only used when precond is schwarz). 1 = single-level smoother; 2 = two-level coarse correction over the connectivity partition (default), which reduces the worst-case PCG iteration count on stiff multibody contact. Values above the solver’s internal cap are clamped.

stitch-length-factor

Key	stitch-length-factor
Default	10.0
Label	Stitch Length Factor
Description	Multiplier on the stitch rest length when capping the stitch separation in the strain force. Cap = stitch_length_factor * l0 + offset_src + max(offset_target). Larger values let stitches stretch farther before the cap saturates the force.

target-toi

Key	target-toi
Default	0.25
Label	Target Accumulated Time of Impact (TOI)
Description	Accumulated TOI threshold for Newton’s loop termination.

wind

Key	wind
Default	[0.0, 0.0, 0.0]
Label	Wind Force
Description	Wind force vector (XYZ).

world-scaling

Key	world-scaling
Default	1.0
Label	World Scaling Factor
Description	Uniform spatial scale applied to all input geometry before the simulation runs; output positions are divided back by it. Values below 1 shrink (e.g. 0.1 simulates a 15 m mesh at 1.5 m and writes results back at 15 m). Only geometry and relative contact gaps scale; gravity and absolute contact gaps do not.