Metadata-Version: 2.4
Name: simkit
Version: 0.1.0
Summary: SimKit: A Simulation Toolkit For Computer Animation
Author-email: Otman Benchekroun <otmanbench@gmail.com>
Maintainer-email: Otman Benchekroun <otmanbench@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/otmanon/simkit
Project-URL: Repository, https://github.com/otmanon/simkit
Project-URL: Documentation, https://otmanon.github.io/simkit/
Project-URL: Issues, https://github.com/otmanon/simkit/issues
Keywords: simulation,animation,physics,computer-graphics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.MIT
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: mesh
Requires-Dist: libigl; extra == "mesh"
Provides-Extra: viz
Requires-Dist: matplotlib; extra == "viz"
Requires-Dist: polyscope==2.5.0; extra == "viz"
Provides-Extra: solvers
Requires-Dist: cvxopt; extra == "solvers"
Provides-Extra: video
Requires-Dist: pillow; extra == "video"
Provides-Extra: cmaes
Requires-Dist: cma; extra == "cmaes"
Provides-Extra: all
Requires-Dist: libigl; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: polyscope==2.5.0; extra == "all"
Requires-Dist: cvxopt; extra == "all"
Requires-Dist: pillow; extra == "all"
Requires-Dist: cma; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-autoapi>=3; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Requires-Dist: myst-nb>=1; extra == "docs"
Dynamic: license-file


# SimKit : A Simulation Toolkit for Computer Animation

[![CI](https://github.com/otmanon/simkit/actions/workflows/ci.yml/badge.svg)](https://github.com/otmanon/simkit/actions/workflows/ci.yml)
[![Docs](https://github.com/otmanon/simkit/actions/workflows/docs.yml/badge.svg)](https://github.com/otmanon/simkit/actions/workflows/docs.yml)

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:
```bash
git clone --recursive https://github.com/otmanon/simkit.git
```

Installation is recommended on a fresh conda environment:

```bash
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.

| Extra      | Adds                                       | Enables                                                          |
| ---------- | ------------------------------------------ | ---------------------------------------------------------------- |
| `mesh`     | `libigl`                                   | 2D Triangle meshing (`shape_outlines`)                           |
| `viz`      | `matplotlib`, `polyscope`                  | `simkit.matplotlib`, `simkit.polyscope` plotters                 |
| `solvers`  | `cvxopt`                                   | Sparse eigensolvers (`simkit.eigs`)                              |
| `video`    | `Pillow`                                   | `simkit.filesystem` image / video frame helpers                 |
| `cmaes`    | `cma`                                      | `simkit.solvers.CMAESSolver`                                     |
| `all`      | union of the above                         | Everything end-user-facing                                       |
| `dev`      | `pytest`, `pytest-cov`                     | Running the test suite                                           |
| `docs`     | `sphinx`, `sphinx-autoapi`, `pydata-sphinx-theme`, ... | Building the documentation                            |

Install one or more extras with the usual `pip` syntax:

```bash
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/`](examples/fast_complementary_dynamics) -- Fast Complementary Dynamics via Skinning Eigenmodes (SIGGRAPH 2023).
- [`modal_muscles/`](examples/modal_muscles) -- CMA-ES-optimised modal-actuator locomotion.
- [`subspace_mfem/`](examples/subspace_mfem) -- Subspace Mixed FEM elastodynamics (SIGGRAPH Asia 2023), including an interactive demo.
- [`force_dual_modes/`](examples/force_dual_modes) -- force-dual / linear modal-analysis subspaces.

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

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

## Running tests

```bash
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:

```bash
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:

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

Quick reference for the script form:

| What | Command |
| --- | --- |
| Build sdist + wheel | `./scripts/release.sh build` (or `make build`) |
| Upload to TestPyPI | `./scripts/release.sh upload-test` |
| Install from TestPyPI in a throwaway venv | `./scripts/release.sh test-install` |
| Upload to **real** PyPI | `./scripts/release.sh upload-prod` |
| Build the docs | `./scripts/release.sh docs` |
| Build + open the docs | `./scripts/release.sh docs-open` |
| Remove all build/docs/cache junk | `./scripts/release.sh clean` |

### 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:

```bash
git tag v0.1.0
git push --tags
```
