Skip to main content

soft_body_cohesion

Rapier supports three ways of holding the particles of a soft-body together: shape matching, constraints, and the Finite Elements Method (FEM). They can be combined, e.g., shape matching on top of edge constraints. Note that shape matching works on the particles alone, whereas the constraints need edges or cells, and the FEM solver needs cells.

Shape matching​

Shape matching doesn't need any element. At each timestep, the rest shape of the body is placed where it best fits its current shape, i.e., both shapes are given the same center of mass, and the rest shape is given the rotation bringing its particles the closest to the current ones. Each particle is then pulled toward its twin in that matched rest shape by a spring:

Shape-matching steps

This is cheap, and a body always recovers its original shape whatever the deformation it went through. On the other hand, the particles don't interact with their neighbors: pushing on one particle doesn't pull the ones around it, which makes the deformations feel very local. Shape matching is enabled by the shapeMatching field of the description, and the strength of its springs is the shape matching softness (shapeMatchingSoftness) of the material:

// A cloud of particles without any element: shape matching alone pulls them back toward
// their rest shape, placed where it best fits the current one.
R2Vector points[9];
for (int i = 0; i < 9; i++) {
    points[i] = r2VectorScale(r2Vector(i % 3, i / 3 + 4.0), 0.3);
}
R2SoftBodyDesc cloud = r2DefaultSoftBodyDesc();
r2SoftBodyDesc_SetParticles(&cloud, (R2VectorView){points, 9});
cloud.shapeMatching = (R2OptionalBool){1, 1};
// How fast the particles are pulled back toward their rest shape.
cloud.material.shapeMatchingSoftness = (R2SpringCoefficients){5.0, 1.0};
cloud.particleRadius = (R2OptionalReal){1, 0.1};
R2SoftBodyHandle cloud_handle = r2InsertSoftBody(world, &cloud);
tip

Use shape matching for low-detail deformations, or whenever computing a topology (edges, cells) isn't desired. It is enabled by default by the r3SoftBodyDesc_SetSurfaceMesh and r2SoftBodyDesc_SetTrimesh constructors (unless the shapeMatching override disables it). Note however that it performs very poorly for ropes, cloth, or any open shape. Also note that combining it with edges makes the deformations spread to the neighbors to look more realistic.

Constraints​

The constraints-based soft-body solver is the default solver (R3_SOFT_SOLVER_CONSTRAINTS), and the most versatile one: every edge and cell element of the deformation lattice becomes a constraint, solved together with the contacts and the joints of the scene.

Edge and cell constraints

An edge is a spring-damper pulling its two particles back toward its rest length. A cell is either a volume constraint keeping its area or its volume, the shape itself being held by the edges, or an elastic element resisting any deformation. This is selected by the cell model of the body (cellModel):

  • R3_SOFT_CELL_VOLUME: one constraint per cell keeping its area (2D) or its volume (3D) at its rest value. This is the cheapest model, and combined with the edges it is often enough to obtain a convincing jelly.
  • R3_SOFT_CELL_COROTATIONAL: linear elasticity expressed in the rotation-free frame of the cell. It is stable at any stiffness and recovers from inverted cells.
  • R3_SOFT_CELL_NEO_HOOKEAN: stable Neo-Hookean hyperelasticity. It feels stiffer than linear elasticity on compression, but softer on tension.

The stiffness of every element is configured by the R3SoftBodyMaterial of the body, which can be given to the description or set at any time with r3SoftBody_SetMaterial (the current one being given by r3SoftBody_Material). A material is initialized by r3DefaultSoftBodyMaterial, or by r3UniformSoftBodyMaterial which gives the same softness to every constraint. The edges and the volume constraints are given a softness, i.e., a natural frequency (in Hz) and a damping ratio instead of a stiffness, so it doesn't depend on the masses of the particles:

  • The edge softness (edgeSoftness) for the structural edges;
  • The bend softness (bendSoftness) for the bending edges and the dihedral constraints;
  • The volume softness (volumeSoftness) for the volume constraints.

The elastic cells are given a Young modulus (youngModulus, in force per unit area in 3D, per unit length in 2D), a Poisson ratio (poissonRatio), and a damping ratio (elasticDampingRatio) instead. Their natural frequency is derived from these, therefore a body meshed more finely doesn't become stiffer, whereas it becomes more expensive to simulate.

Finally, a body with a closed surface can preserve the area (2D) or the volume (3D) it encloses (volumePreservation), which target can be scaled by a volumeFactor (or r3SoftBody_SetVolumeFactor after the insertion) greater than 1 in order to inflate the body, e.g., to simulate a pressurized blob:

// Elastic cells: a jelly square with corotational linear elasticity.
R2SoftBodyDesc jelly = r2GridSoftBodyDesc(r2Vector(3.0, 1.2), r2Vector(1.0, 1.0), 6, 6);
// The constitutive model of the cells: R2_SOFT_CELL_VOLUME (per-cell area constraints,
// the shape is held by the edges), R2_SOFT_CELL_COROTATIONAL or R2_SOFT_CELL_NEO_HOOKEAN.
jelly.cellModel = R2_SOFT_CELL_COROTATIONAL;
// Stiffness of the elastic cells.
jelly.material.youngModulus = 3.0e3;
jelly.material.poissonRatio = 0.35;
jelly.material.elasticDampingRatio = 0.5;
// Plasticity: the rest shape flows past 5% strain, at 20 per second.
jelly.material.plasticYield = 0.05;
jelly.material.plasticCreep = 20.0;
// Tearing: an element past 40% strain tears.
jelly.material.tearStrain = (R2OptionalReal){1, 0.4};
jelly.particleMass = 0.2;
R2SoftBodyHandle jelly_handle = r2InsertSoftBody(world, &jelly);

// A pressurized blob: a ring of particles inflated by area preservation.
R2SoftBodyDesc blob = r2DiskSoftBodyDesc(r2Vector(0.0, 3.0), 0.8, 24);
blob.material = r2UniformSoftBodyMaterial((R2SpringCoefficients){20.0, 1.0});
// Target area multiplier (`> 1` inflates the body), for the area preservation enabled by
// the disk constructor (`volumePreservation`).
blob.volumeFactor = 1.1;
blob.selfContacts = 1;
R2SoftBodyHandle blob_handle = r2InsertSoftBody(world, &blob);
info

The stiffness effectively simulated by the constraints solver depends on its convergence: with too few iterations, a stiff body looks softer than its material says. This is why soft-bodies are configured with 3 additional internal PGS solver iterations by default, which can be modified with additionalPgsIterations. The whole island a body belongs to can also be given additional substeps with additionalSolverIterations, just like rigid-bodies.

The same chain solved with 1, 4, and 32 iterations

The following table gathers the settings to look at for the most common problems:

ProblemWhat to change
The body is too soft, or stretches too much.Raise the natural frequency of the material's edgeSoftness, or its youngModulus for the elastic cells. Give it more additionalPgsIterations, or switch it to the FEM solver with solver.
A cloth stretches, but should still fold easily.Keep a stiff edgeSoftness, and give it a soft bendSoftness.
A rope compresses like a spring.Make its edges resist stretching only with tensionOnlyEdges.
The body keeps wobbling after an impact.Raise the damping_ratio of the material's softnesses and its elasticDampingRatio, or its deformationDamping (which damps the deformations but not the motion of the body as a whole).
A closed body collapses, or must be inflated.Enable volumePreservation, and give it a volumeFactor greater than 1.
The deformations are too local.Combine shapeMatching with edges, or rely on edges and cells alone.

FEM solver​

The FEM solver (R3_SOFT_SOLVER_FEM, given to the solver field of the description or to r3SoftBody_SetSolver, and requiring the fem feature of the library) resolves the elasticity of the whole body at once and semi-implicitly: the forces and the stiffness of every cell are assembled into a single linear system, solved at each substep. Therefore the stiffness of the body no longer depends on the number of solver iterations, which makes it capable of simulating very stiff materials, as well as more realistic plastic deformations and failures:

Assembly of the FEM system

This comes at a price: the system is factorized at each timestep, and every constraint touching the body (contacts, joints) needs a solve against it. Note that the FEM solver requires cells, so it only applies to the bodies built with cells, e.g., with the r2GridSoftBodyDesc, r3CuboidSoftBodyDesc, or r3VolumetricSoftBodyDesc constructors. The configuration of its linear solves is shared by every body using it, and lives in the integration parameters:

// A stiff beam simulated by the FEM solver (requires the `fem` feature): its stiffness
// doesn't depend on the number of solver iterations.
R2SoftBodyDesc beam = r2GridSoftBodyDesc(r2Vector(0.0, 2.0), r2Vector(1.0, 0.1), 21, 3);
beam.solver = R2_SOFT_SOLVER_FEM;
beam.cellModel = R2_SOFT_CELL_NEO_HOOKEAN;
beam.material.youngModulus = 1.0e5;
beam.material.poissonRatio = 0.3;
// The particles of the side at `x = -1` are the first 3 ones.
const uint32_t beam_pinned[] = {0, 1, 2};
beam.pinned = (R2IndexView){beam_pinned, 3};
R2SoftBodyHandle beam_handle = r2InsertSoftBody(world, &beam);

// The tuning of the linear solves of the FEM solver, shared by every body using it.
r2FemSetLinearTolerance(world, 1.0e-5);
r2FemSetMaxLinearIterations(world, 20);

The linear solves stop at the relative residual linearTolerance (set by r3FemSetLinearTolerance), or after maxLinearIterations (set by r3FemSetMaxLinearIterations) conjugate-gradient iterations, whatever the residual. The bodies with at most maxDenseDofs (set by r3FemSetMaxDenseDofs) degrees of freedom (600 by default) are factorized directly, whereas the larger ones rely on the iterative conjugate gradient.

tip

Use the FEM solver for stiff materials which simulated stiffness must not depend on the iteration count, e.g., the chassis of a car or a metal beam. This also results in more realistic plasticity and tearing.