Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Diff_2D_FEM

A differentiable, GPU-batched 2D simulator for soft robots, on NVIDIA Warp.

Soft bodies, rigid bodies, contact with friction, and pressure, tendons, active material and prescribed motion, advanced together by one implicit solve. Bodies are pixel masks (a design is an image) or triangle meshes. Thousands of independent scenes run in one batched solve, and the solve has an adjoint.

It is a 2D counterpart to Taccel: the same Model + Integrator shape and the same ingredients (FEM soft bodies, affine rigid bodies, IPC contact), in plane strain, solved by preconditioned nonlinear conjugate gradients (PNCG) instead of Newton.

Requirements

  • Python 3.9+, with numpy, scipy and warp-lang (tested on 1.11).
  • GPU: a CUDA GPU is the default device; Model(device="cpu") runs the same kernels on the CPU.
  • Optional: matplotlib for pictures and --plot; pyglet for the live window.

Quickstart

pip install -e .                 # from this directory
pip install -e ".[examples]"     # + matplotlib, for Diff_2D_FEM.viz and --plot
python examples/pneunet.py --plot

A strip of soft material lying on the ground, under gravity:

import numpy as np, warp as wp
import Diff_2D_FEM as D
wp.init()

model = D.Model()
model.add_ground(height=0.0, mu=0.8)
body = model.add_soft_body(np.ones((6, 72), np.uint8),          # (H, W) pixels, row 0 at the bottom
                           physical_size=(0.054, 0.0045),        # width, height [m]
                           center=(0.0, 0.0030),
                           E=0.5e6, nu=0.40, density=1100.0)
model.finalize()
model.gravity = (0.0, -9.81)

integ = D.ImplicitIntegrator()
for step in range(200):
    integ.simulate(model, dt=2e-3)
x = model.get_body_x(body)                                       # (n_nodes, 2)

Everything else (more bodies, colliders, actuators) is added to the Model the same way; the examples below show each.

Examples

Soft robots

pneunet
fluid pressure · pneunet.py
a PneuNet bending actuator curls 172° at 18 kPa
bone_finger
tendons · bone_finger.py
rigid phalanges on flexure hinges wrap a disc
crawler
active material · crawler.py
a strip walks on a travelling wave of contraction
pinch_and_lift
prescribed motion · pinch_and_lift.py
a parallel gripper with soft fingertips lifts a block
muscle_arm
springs and pins · muscle_arm.py
a rigid forearm on a pivot, flexed by a contracting spring
magnetic_beam
external forces · magnetic_beam.py
a hard-magnetic beam turns into a uniform field
mesh_body
meshes · mesh_body.py
bodies given as triangle meshes

Design and optimisation

evolve_walker
genetic algorithm · evolve_walker.py
where a pneumatic walker has material around its two air channels; 48 designs per solve
morph_finger
adjoint · morph_finger.py
per-pixel stiffness of a strip so it curls into a target finger: 1.29 → 0.16 mm RMS
tendon_gripper
adjoint · tendon_gripper.py
per-pixel stiffness of a tendon-driven gripper's fingers, so one design cradles four objects: 2.98 → 1.34 mm RMS

Example options

Argument Description Examples
--plot save a picture of the run all
--viz open the live window all but magnetic_beam, morph_finger, tendon_gripper
--quick a short run evolve_walker
--iters N the number of optimiser iterations morph_finger, tendon_gripper
python examples/crawler.py --viz
python examples/tendon_gripper.py --iters 5 --plot

The robots run in seconds to two minutes on an RTX A5000; the design examples take up to about an hour. The pictures are made by tools/example_thumbnails.py.

Conventions

  • Plane strain, per unit depth. Pressure is in Pa; forces, tendon tensions and contact reactions in N per metre of depth; spring stiffness in Pa. SI units throughout.
  • A pixel body is a mask, shape (H, W), non-zero = material, row 0 at the bottom. Each pixel becomes two linear (P1) triangles; per-pixel maps (stiffness, active and rigid regions) use the layout of the body's own mask.
  • A mesh body is taken as given: vertex i is node i, triangle j is element j.
  • Double precision by default.

Differentiability

adj = integ.adjoint(model, dt)
adj.set_density(rho)                          # per element, in [0, 1]
model.reset(); xs = [model.get_x()]
for t in range(T):
    ...; integ.simulate(model, dt); xs.append(model.get_x())
g = adj.transient_adjoint(xs, seed={T: dJ_dx_T}, use_disc=True)       # dJ / d rho

The adjoint of the implicit solve: one linear solve per step, the gradient of an objective on the trajectory with respect to a per-element density that scales each element's modulus, E(rho) = E · (Emin + rho (1 − Emin)). model.to_elements(h, field) and model.to_pixels(h, values) map between a body's pixels and its elements. Checked against finite differences of the full rollout: cosine 0.9999 or better. Its scope is narrow:

  • contact is differentiated with the active set frozen at each converged state — with every collider, shared or of a single environment (env_id=), several to a scene: the discs with use_disc=True, every other shape with use_sdf=True;
  • friction has no tangent (cosine 0.33 at mu = 0.6): differentiate frictionless rollouts — transient_adjoint refuses a collider with mu > 0 unless the integrator has friction=False;
  • pressure, tendons (tension- or length-controlled), springs and pins are in the adjoint, with commands that may change every step: build the adjoint before the rollout — from then on the integrator records each step's commands — and call transient_adjoint right after it, since it linearises the last len(xs) − 1 steps simulated;
  • active material, rigid bodies and IPC contact between bodies are not (gravity, external forces and "node" contact are): differentiate a scene of several bodies with ImplicitIntegrator(self_collision=False) or model.body_contact = "node";
  • the design variable is density only — not shape, not control signals.

The objective can also be the elastic force at some nodes, e.g. the reaction at a held output:

J, dJ_dx, explicit = adj.force_objective(xs[T], nodes, direction)   # J = direction . force on nodes
g = adj.transient_adjoint(xs, seed={T: dJ_dx}, rtol=1e-14) + explicit

Keep rtol=1e-14 for such a seed: at the default 1e-9 a reaction gradient came out 4 % off. A trajectory with large motion needs steps small enough to follow it (turning a strip through 130°: 3 % off in 12 steps, 0.06 % in 24).

Watching it run

renderer = D.Renderer(model)                 # after model.finalize(): opens the window
for step in range(n):
    ...command the actuators...
    integ.simulate(model, dt)
    renderer.draw()                          # = begin_frame(model.time); render(); end_frame()

The examples open it with --viz (python examples/crawler.py --viz). Drag or arrow keys to move, scroll or + / - to zoom, F fit, R reset the view, X wireframe, SPACE pause, ESC close (the loop runs on).

  • D.Renderer(model, envs="all") shows a batch side by side; bounds=((xmin, ymin), (xmax, ymax)) sets the view.
  • renderer.play(frames, dt) replays saved states at their true speed (the live window is slow motion: one scene runs at 10–30 steps per second).
  • renderer.hold() keeps the window open; renderer.pixels() returns the frame as an image; headless=True renders without a window.

Pictures and animations

from Diff_2D_FEM import viz
viz.draw(model)                              # bodies, rigid parts, colliders, cables, springs
viz.draw(model, values=model.me.mu)          # colour by any per-element field
viz.draw(model, field="stress")              # von Mises stress, with a colour bar
viz.draw(model, field="stress", signed=True) # tension red (+), compression blue (-)
viz.animate(model, frames, "run.gif", field="strain",        # frames: a list of model.get_x(),
            titles=[f"t = {t:.3f} s" for t in times])        # recoloured on ONE scale
viz.animate(model, frames, "batch.gif", envs="all", field="stress",   # a batch side by side
            panel_titles=[...], bounds=((x0, y0), (x1, y1)))

field="strain" / "stress" are the von Mises equivalents of the Green–Lagrange strain and the Cauchy stress [Pa], one value per triangle; model.element_strain(x) and model.element_stress(x) give the same numbers. clim= and cmap= override the scale and the colour map (coolwarm by default).

Layout

sim_model.py     Model — the scene
implicit/        integrator.py   ImplicitIntegrator
                 solver.py, kernels.py   the PNCG-IPC iteration
                 actuation.py    pressure, tendon, active strain, springs, forces
                 affine.py       rigid bodies; rigid-mode coarse space
                 ipc_contact.py  IPC contact between bodies
                 body_contact.py friction for the older "node" contact
                 adjoint.py      adjoint of the implicit solve
core/            mesh.py (the scene mesh; check_mesh, mask_to_mesh), sdf.py + objects.py
                 (colliders), fields.py (strain, stress), actuators.py, math.py,
                 precision.py, config.py
render.py        the live window (Renderer)
viz.py           pictures and animations with matplotlib
tests/           the checks (python tests/test_<name>.py)
tools/           the studies and measurements behind the defaults
examples/
docs/images/     the pictures of the examples

References

  • IPC — Li et al., Incremental Potential Contact: Intersection- and Inversion-free, Large-Deformation Dynamics, ACM Trans. Graph. 39(4), 2020.
  • PNCG — Shen et al., Preconditioned Nonlinear Conjugate Gradient Method for Real-time Interior-point Hyperelasticity, SIGGRAPH 2024; direction of Dai & Kou, SIAM J. Optim. 23(1), 2013.
  • Affine body dynamics — Lan et al., Affine Body Dynamics: Fast, Stable and Intersection-free Simulation of Stiff Materials, ACM Trans. Graph. 41(4), 2022.
  • Additive CCD — Li et al., Codimensional Incremental Potential Contact, ACM Trans. Graph. 40(4), 2021.
  • Vertex corrections — Li et al., Convergent Incremental Potential Contact, arXiv:2307.15908, 2023.
  • Taccel — Li et al., Taccel: Scaling Up Vision-based Tactile Robotics via High-performance GPU Simulation, arXiv:2504.12908, 2025.
  • Warp — Macklin, Warp: A High-performance Python Framework for GPU Simulation and Graphics, NVIDIA GTC 2022.

Licence

MIT.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages