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:

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 SoftBodyBuilder.shape_matching, and the strength of its springs is the shape matching softness (shape_matching_softness) 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.
points = 0.3 * np.array([(i % 3, i // 3 % 3 + 4.0, i // 9) for i in range(27)])
blob = (
    rp.SoftBodyBuilder(points)
    .shape_matching(True)
    .material(
        rp.SoftBodyMaterial(
            # How fast the particles are pulled back toward their rest shape.
            shape_matching_softness=rp.SpringCoefficients(5.0, 1.0),
        )
    )
    .particle_radius(0.1)
)
blob_handle = world.add_soft_body(blob)

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 trimesh constructor. 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 (SoftBodySolver.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.

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 (cell_model, which takes a SoftBodyCellModel):

• 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.
• COROTATIONAL: linear elasticity expressed in the rotation-free frame of the cell. It is stable at any stiffness and recovers from inverted cells.
• 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 SoftBodyMaterial of the body, which can be given to the builder or set at any time with the material property of SoftBody. This property is a live view of the material of the body: modifying one of its fields modifies the body, whereas SoftBodyMaterial.copy gives a detached copy. A material is created with the SoftBodyMaterial constructor, which takes any of its fields as keyword arguments, or with SoftBodyMaterial.uniform 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 (edge_softness) for the structural edges;
• The bend softness (bend_softness) for the bending edges and the dihedral constraints;
• The volume softness (volume_softness) for the volume constraints.

The elastic cells are given a Young modulus (young_modulus, in force per unit area in 3D, per unit length in 2D), a Poisson ratio (poisson_ratio), and a damping ratio (elastic_damping_ratio) 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 (volume_preservation, or enable_volume_preservation after the insertion), which target can be scaled by a volume_factor (or the volume_factor property of SoftBody after the insertion) greater than 1 in order to inflate the body, e.g., to simulate a pressurized blob:

# Elastic cells: a jelly cube with corotational linear elasticity.
jelly = (
    rp.SoftBody.cuboid((3.0, 1.0, 0.0), (0.5, 0.5, 0.5), 4, 4, 4)
    # The constitutive model of the cells: `VOLUME` (per-cell volume constraints,
    # the shape is held by the edges), `COROTATIONAL` or `NEO_HOOKEAN`.
    .cell_model(rp.SoftBodyCellModel.COROTATIONAL)
    .material(
        rp.SoftBodyMaterial(
            # Stiffness of the elastic cells.
            young_modulus=2.0e3,
            poisson_ratio=0.35,
            elastic_damping_ratio=0.5,
            # Plasticity: the rest shape flows past 5% strain, at 20 per second.
            plastic_yield=0.05,
            plastic_creep=20.0,
            # Tearing: an element past 40% strain tears.
            tear_strain=0.4,
        )
    )
    .particle_mass(0.2)
)
jelly_handle = world.add_soft_body(jelly)

# A material shared by the edges, bending constraints and volume constraints.
material = rp.SoftBodyMaterial.uniform(rp.SpringCoefficients(30.0, 1.0))
# Softness of the bending constraints, on top of a uniform 30 Hz softness.
material.bend_softness = rp.SpringCoefficients(3.0, 1.0)
world.soft_bodies[cloth_handle].material = material
# The `material` property is also a live view: its fields can be modified in place.
world.soft_bodies[cloth_handle].material.deformation_damping = 0.1

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 additional_pgs_iterations. The whole island a body belongs to can also be given additional substeps with additional_solver_iterations, just like rigid-bodies.

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

Problem	What to change
The body is too soft, or stretches too much.	Raise the natural frequency of the material's edge_softness, or its young_modulus for the elastic cells. Give it more additional_pgs_iterations, or switch it to the FEM solver with solver.
A cloth stretches, but should still fold easily.	Keep a stiff edge_softness, and give it a soft bend_softness.
A rope compresses like a spring.	Make its edges resist stretching only with tension_only.
The body keeps wobbling after an impact.	Raise the damping_ratio of the material's softnesses and its elastic_damping_ratio, or its deformation_damping (which damps the deformations but not the motion of the body as a whole).
A closed body collapses, or must be inflated.	Enable volume_preservation, and give it a volume_factor greater than 1.
The deformations are too local.	Combine shape_matching with edges, or rely on edges and cells alone.

FEM solver

The FEM solver (SoftBodySolver.FEM, given to the builder with solver, or to the solver property of SoftBody after the insertion) 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:

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 cuboid, volumetric, or volumetric_with 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: its stiffness doesn't depend on the number of
# solver iterations.
beam = (
    rp.SoftBody.cuboid((0.0, 2.0, -3.0), (1.0, 0.1, 0.1), 11, 3, 3)
    .solver(rp.SoftBodySolver.FEM)
    .cell_model(rp.SoftBodyCellModel.NEO_HOOKEAN)
    .material(rp.SoftBodyMaterial(young_modulus=1.0e5, poisson_ratio=0.3))
    # The particles of the face at `x = -1` are the first 3 × 3 ones.
    .pinned_particles(range(9))
)
beam_handle = world.add_soft_body(beam)

# The tuning of the linear solves of the FEM solver, shared by every body using it.
fem = world.integration_parameters.soft_bodies.fem
fem.linear_tolerance = 1.0e-5
fem.max_linear_iterations = 20

The linear solves stop at the relative residual linear_tolerance, or after max_linear_iterations conjugate-gradient iterations, whatever the residual. The bodies with at most max_dense_dofs 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.