SimKit : A Simulation Toolkit for Computer Animation

This library should be considered a toolbox for the development of physically-based animation research. It is designed to be modular, easy to use, and easy to extend. In particular, it is designed to be emphasize fast creative and experimental prototyping.

Installation

Clone the repository:

git clone --recursive https://github.com/otmanon/simkit.git

Installation is recommended on a fresh conda environment:

cd simkit
conda create -n simkit python=3.11
conda activate simkit
pip install -e .

Optional Dependencies

The base install only requires numpy and scipy -- and now covers the clustering / sampling helpers (farthest_point_sampling, spectral_clustering, spectral_cubature) too. Heavier or specialized dependencies are exposed as named extras so you only install what you need. Importing simkit is always safe -- functionality whose extras are missing just isn't exported, and a one-line warning tells you exactly what to install.

Install one or more extras with the usual pip syntax:

pip install -e ".[mesh]"            # just mesh ops
pip install -e ".[mesh,viz]"        # multiple extras
pip install -e ".[all]"             # everything end-user-facing
pip install -e ".[all,dev,docs]"    # everything, including dev tooling

Running Examples

The repository includes several end-to-end demos under examples/, each reproducing a slice of a published paper:

• fast_complementary_dynamics/ -- Fast Complementary Dynamics via Skinning Eigenmodes (SIGGRAPH 2023).
• modal_muscles/ -- CMA-ES-optimised modal-actuator locomotion.
• subspace_mfem/ -- Subspace Mixed FEM elastodynamics (SIGGRAPH Asia 2023), including an interactive demo.
• interactive_demos/ -- 15 short polyscope demos, from a single deformation gradient up to interactive 3D mixed FEM.

Force-dual / linear modal-analysis subspaces are not on main yet; they live on the force_dual_modes branch.

Each demo has its own README with the exact extras to install and the command to run. See examples/README.md for the index. As a quick start:

pip install -e ".[mesh,viz,video]"
python examples/subspace_mfem/drop_fem_vs_mfem.py

Running tests

pip install -e ".[dev]"
pytest

Building the documentation

The docs are generated from the docstrings in the simkit package using Sphinx + sphinx-autoapi + the PyData theme. To build them locally:

pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html

Then open docs/_build/html/index.html in your browser. Every function in simkit/ is automatically picked up and rendered into the API reference -- just write a good docstring and rebuild.

Release / dev workflow

Two equivalent ways to do every build/test/release/docs task. Pick whichever you prefer.

• scripts/COMMANDS.md — raw, copy/paste-able bash commands organized by task. Read it top-to-bottom or grab whichever block you need. No abstraction, no functions, just shell commands.
• scripts/release.sh — the same commands wrapped as subcommands so you can run e.g. ./scripts/release.sh build instead of pasting. There's also a Makefile with make build / make docs / etc. targets.

First-time setup on a new machine:

chmod +x scripts/release.sh
conda activate simkit   # so `python` points at the right interpreter

Quick reference for the script form:

Local upload vs GitHub Actions Trusted Publishing

The script has the full tradeoff in a header comment. Summarized:

• Local (upload-test / upload-prod): fastest path, but requires a PyPI API token on your laptop and the build runs in your local environment. Best for the very first upload (claiming the project name) or one-off hotfixes.
• GitHub Actions (.github/workflows/release.yml, triggered by pushing a vX.Y.Z git tag): no secrets stored anywhere thanks to Trusted Publishing; every release is a reproducible build from a tagged commit; auto-publishes to TestPyPI first, then PyPI. Best for every release after the first.

Recommended flow: claim the project on PyPI/TestPyPI with one local upload, then switch to tag-triggered GitHub Actions for everything afterward:

git tag v0.1.1
git push --tags