Simulator

Simulator#

Main simulator class

This module provides the Simulator class, which integrates the mesh, material model, and time integration solver into a unified interface for running physics simulations.

The simulator manages:

  • State variables (positions, velocities)

  • Vertex masses computed from density and element volumes

  • Boundary conditions (fixed vertices)

  • Time tracking

  • Energy computation

For differentiable simulation with gradient support, use DifferentiableSimulator instead.

class diffsim.simulator.Simulator(mesh, material, solver, density=1000.0, device='cpu', use_compile=False)[source]#

Bases: object

Main physics simulator for non-differentiable forward simulation

This class combines a TetrahedralMesh, material model, and SemiImplicitSolver into a unified interface. It manages simulation state, computes vertex masses, handles boundary conditions, and provides methods for running simulations.

For gradient-based optimization and differentiable simulation, use DifferentiableSimulator instead.

Parameters:

  • mesh (TetrahedralMesh) – Tetrahedral mesh

  • material (StableNeoHookean) – Material model

  • solver (SemiImplicitSolver) – Time integration solver

  • density (float) – Material density in kg/m³ (default: 1000.0)

  • device (str) – ‘cpu’ or ‘cuda’ (default: ‘cpu’)

  • use_compile (bool) – Use torch.compile for speedup (default: False)

positions#

Current vertex positions \((N \times 3)\)

Type:

torch.Tensor

velocities#

Current vertex velocities \((N \times 3)\)

Type:

torch.Tensor

masses#

Vertex masses \((N,)\)

Type:

torch.Tensor

fixed_vertices#

Indices of fixed vertices

Type:

torch.Tensor

time#

Current simulation time in seconds

Type:

float

__init__(mesh, material, solver, density=1000.0, device='cpu', use_compile=False)[source]#

Initialize simulator

Parameters:

  • mesh – TetrahedralMesh object

  • material – Material model (e.g., StableNeoHookean)

  • solver – Time integration solver (e.g., SemiImplicitSolver)

  • density – material density (kg/m^3)

  • device – ‘cpu’ or ‘cuda’

  • use_compile – use torch.compile for speedup (requires PyTorch 2.0+)

set_fixed_vertices(vertex_indices)[source]#

Set vertices that should remain fixed during simulation

Parameters:

vertex_indices – list or tensor of vertex indices to fix

fix_bottom_vertices(threshold=0.05)[source]#

Fix vertices below a certain height threshold

Parameters:

threshold – height threshold (relative to min y-coordinate)

add_velocity(vertex_indices, velocity)[source]#

Add velocity to specific vertices

Parameters:

  • vertex_indices – indices of vertices

  • velocity – \((3,)\) velocity vector to add

step()[source]#

Perform one simulation step

reset()[source]#

Reset simulation to initial state

warmstart(num_steps=10)[source]#

Warm start the simulation to reach equilibrium

This helps prevent initial artifacts by letting the mesh settle with reduced forces before the main simulation starts

Parameters:

num_steps – number of warm-start steps

get_surface_mesh()[source]#

Extract surface triangles for visualization (boundary faces only)

Returns:

\((N, 3)\) vertex positions faces: \((F, 3)\) triangle indices

Return type:

vertices

compute_energy()[source]#

Compute total energy (kinetic + potential)

Returns:

kinetic energy elastic_energy: elastic potential energy gravitational_energy: gravitational potential energy

Return type:

kinetic_energy

Contents