simrun: simulation workflows on a k3s cluster

simrun runs simulation workflows on a small cluster of servers with k3s, Argo Workflows and Kueue. People and agents submit a workflow of tasks together with the working trees of their model and libraries, uncommitted changes included, and get a run id at once; the run is queued, placed, executed and recorded without the submitter staying connected.

Features include

• workflows - YAML files of tasks of task types from plugins, which read the output ports of other tasks
• split tasks - the units of a task (the repeats of a fit, the points of a scan) spread over the idle servers and are taken back by runs of a higher priority, with results which do not depend on the split
• priorities - the owner of the cluster and the owner's agents first, then the other people, then their agents, with preemption by Kueue and reservations of nodes
• learned resources - the memory of a pod is learned from earlier runs, a pod killed for memory is retried with more
• snapshots and environments - the working trees are snapshotted into a shared run store, the third party dependencies are locked and built into an image only when they change
• for people and agents - a command line, an HTTP API and an MCP server to submit, follow, compare and cancel runs

simrun submit fit.yaml --source model=~/git/pkdb_models --source sbmlsim=~/git/sbmlsim --group hctz
simrun wait <run>
simrun compare <run> <run>

Without a cluster the same workflow runs on this machine, with the web app, see local mode:

pip install simrun
simrun submit fit.yaml --source model=. --local
simrun outputs <run> <task> --to results

The documentation is available at https://matthiaskoenig.github.io/simrun: installation, concepts, workflows, command line, local mode, agents and MCP, plugins, service, cluster deployment and development.

If you have any questions or issues please open an issue.

Installation

pip install simrun

simrun needs python 3.14 or newer and runs on Linux, see Installation.

How to cite

If you use simrun please cite the archived software on Zenodo:

König, M. simrun: a runner of simulation workflows on a k3s cluster. Zenodo. https://doi.org/10.5281/zenodo.24035618

This DOI stands for every version of simrun; the DOI of a single version is on its Zenodo page. The metadata of the citation are in CITATION.cff.

License

simrun is licensed under the MIT License.

Funding

Matthias König is supported by the Federal Ministry of Education and Research (BMBF, Germany) within the research network Systems Medicine of the Liver (LiSyM, grant number 031L0054) and by the German Research Foundation (DFG) within the Research Unit Programme FOR 5151 QuaLiPerF (Quantifying Liver Perfusion-Function Relationship in Complex Resection - A Systems Medicine Approach) by grant number 436883643 and by grant number 465194077 (Priority Programme SPP 2311, Subproject SimLivA). Matthias König has received funds from the EOSCsecretariat.eu which has received funding from the European Union's Horizon Programme call H2020-INFRAEOSC-05-2018-2019, grant Agreement number 831644.

© 2026 Matthias König