Differentiable Simulator

Differentiable simulation components.

This module provides DifferentiableSolver and DifferentiableSimulator classes that maintain an autograd path through simulation operations. Unlike the standard simulator, these classes use:

• Gradient-preserving updates: State updates are out of place

• Differentiable contact: Smooth barrier functions instead of projection

• Explicit constraints: Fixed vertices use masking so dynamic updates cannot move constrained degrees of freedom

• Checkpointing support: Memory-efficient backpropagation for long rollouts

The differentiable simulator implements the same semi-implicit Euler core update as the standard simulator, but all operations preserve gradients for automatic differentiation.

class diffsim.diff_simulator.DifferentiableSolver(dt=0.01, gravity=-9.8, damping=0.99, substeps=4, use_implicit_diff=False)

Bases: object

Semi-implicit Euler solver with gradient-preserving operations. Forces are derived from the energy gradient; contact uses smooth barriers; constraints use masking to avoid breaking gradients.

Integration scheme:

\[ \begin{align}\begin{aligned}\mathbf{v}^{n+1} &= \mathbf{v}^n + h \, \mathbf{M}^{-1} \mathbf{f}(\mathbf{x}^n)\\\mathbf{x}^{n+1} &= \mathbf{x}^n + h \, \mathbf{v}^{n+1}\end{aligned}\end{align} \]

Parameters:

• dt (float) – Time step size (default: 0.01)

• gravity (float) – Gravity acceleration in m/s² (default: -9.8)

• damping (float) – Velocity damping coefficient (default: 0.99)

• substeps (int) – Number of substeps per timestep (default: 4)

• use_implicit_diff (bool) – Reserved; True is currently unsupported

__init__(dt=0.01, gravity=-9.8, damping=0.99, substeps=4, use_implicit_diff=False)

Parameters:

• dt – time step

• gravity – gravity acceleration

• damping – velocity damping

• substeps – number of substeps

• use_implicit_diff – must be False; the solver uses unrolled autograd

step(mesh, material, positions, velocities, masses, fixed_vertices=None)

Differentiable time step

All operations maintain gradient flow

Parameters:

• mesh – TetrahedralMesh

• material – DifferentiableMaterial

• positions – \((N, 3)\) positions (requires_grad=True for backprop)

• velocities – \((N, 3)\) velocities

• masses – \((N,)\) masses

• fixed_vertices – optional fixed vertices

Returns:

\((N, 3)\) with gradients new_velocities: \((N, 3)\) with gradients

Return type:

new_positions

class diffsim.diff_simulator.DifferentiableSimulator(mesh, material, solver, density=1000.0, device='cpu')

Bases: object

Minimal state wrapper for DifferentiableSolver with gradient support.

__init__(mesh, material, solver, density=1000.0, device='cpu')

Parameters:

• mesh – TetrahedralMesh

• material – DifferentiableMaterial (with requires_grad=True params)

• solver – DifferentiableSolver

• density – material density

• device – ‘cpu’ or ‘cuda’

set_fixed_vertices(vertex_indices)

Set fixed vertices

step()

Perform one differentiable step

rollout(num_steps, checkpoint_every=10)

Perform memory-efficient rollout with checkpointing

Parameters:

• num_steps – number of simulation steps

• checkpoint_every – checkpoint frequency

Returns:

list of (positions, velocities) tuples

Return type:

trajectory

compute_loss(target_positions, loss_type='mse')

Compute loss for optimization

Parameters:

• target_positions – \((N, 3)\) target positions

• loss_type – ‘mse’ or ‘chamfer’

Returns:

scalar loss value

Return type:

loss

reset()

Reset to initial state