cosseratbench

A visual benchmark suite for evaluating rope, cable, and Cosserat rod simulation across deformation, contact, and dynamic stress cases.

Status

Early. Two experiments (catenary, cantilever) run against two solvers (PyElastica and MuJoCo's cable plugin), each scored against an analytical reference. Contact, driven boundaries and the web viewer are not built yet.

Usage

uv sync --all-extras        # from a clone; installs both solver backends
uv run cosseratbench list
uv run cosseratbench run    # every experiment x every solver, saved under results/
uv run cosseratbench run catenary --solver pyelastica --n-elements 100

Each run writes results/<experiment>/<solver>/result.json (metrics, wall time) and trajectory.npz (node positions over time).

How it fits together

• A scenario describes the physics and nothing else: geometry, material, boundary conditions, loads, gravity, duration, all in SI units. Time steps, element counts, contact stiffnesses and damping coefficients are not part of it; they are each solver's business.
• A solver adapter turns a scenario into a trajectory, node positions over time, at a requested resolution. It declares the physics it models (Capability), and an experiment that needs more is reported as unsupported rather than run.
• An experiment pairs a scenario with metrics. Metrics see only the scenario and the trajectory, so every solver is judged by the same code.

Adding a solver or an experiment

Both are discovered through entry points, so they can live in your own package:

[project.entry-points."cosseratbench.solvers"]
mysolver = "mypackage.adapter:MySolver"

[project.entry-points."cosseratbench.experiments"]
myexperiment = "mypackage.experiments:my_experiment"

from cosseratbench import Capability, Scenario, Trajectory


class MySolver:
    name = "mysolver"
    capabilities = frozenset({Capability.STRETCH})

    def run(self, scenario: Scenario, *, n_elements: int, n_frames: int) -> Trajectory: ...

The built-in solvers and experiments register the same way; see src/cosseratbench/solvers and src/cosseratbench/experiments.