simrun 0.1.0__py3-none-any.whl

simrun/workflow.py

@@ -0,0 +1,188 @@
+"""The workflow model: tasks, the references between them and their order."""
+
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Self
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError, model_validator
+
+
+class SplitMode(StrEnum):
+    """How the pieces of a task are placed on the nodes."""
+
+    FASTEST = "fastest"
+    SINGLE_SERVER = "single-server"
+
+
+class Priority(StrEnum):
+    """The priority of a run in the queue."""
+
+    OWNER = "owner"
+    STANDARD = "standard"
+    AGENT = "agent"
+
+
+class WorkflowError(ValueError):
+    """A workflow which is not valid."""
+
+
+class ResourceOverride(BaseModel):
+    """Resources of a task which replace the learned or default ones."""
+
+    workers: int | None = None
+    memory_per_worker_gb: float | None = None
+    scratch_gb: float | None = None
+    gpus: int | None = None
+
+
+class TaskSpec(BaseModel):
+    """A task of a workflow.
+
+    Attributes:
+        id: Identifier of the task within the workflow.
+        type: Name of the task plugin.
+        settings: Settings handed to the plugin.
+        inputs: Input port to the output of another task, `<task>.<port>`.
+        split: Split mode of the task, the one of the workflow by default.
+        resources: Resources replacing the learned or default ones.
+        stage: Input ports copied to local scratch.
+    """
+
+    id: str = Field(pattern=r"^[a-z][a-z0-9-]*$")
+    type: str
+    settings: dict[str, Any] = Field(default_factory=dict)
+    inputs: dict[str, str] = Field(default_factory=dict)
+    split: SplitMode | None = None
+    resources: ResourceOverride | None = None
+    stage: list[str] = Field(default_factory=list)
+
+    def dependencies(self) -> list[str]:
+        """Ids of the tasks this task reads from, in input order, without repeats."""
+        return list(dict.fromkeys(ref.split(".", 1)[0] for ref in self.inputs.values()))
+
+
+class Workflow(BaseModel):
+    """A workflow: tasks which read the outputs of each other."""
+
+    name: str
+    tasks: list[TaskSpec]
+    split: SplitMode = SplitMode.FASTEST
+    reserve: str | None = None
+
+    def __init__(self, **data: Any) -> None:
+        """Create a workflow, a reference error is raised as a `WorkflowError`."""
+        try:
+            super().__init__(**data)
+        except ValidationError as error:
+            for detail in error.errors():
+                cause = detail.get("ctx", {}).get("error")
+                if isinstance(cause, WorkflowError):
+                    raise cause from error
+            raise
+
+    @model_validator(mode="after")
+    def _validate(self) -> Self:
+        ids = [t.id for t in self.tasks]
+        duplicates = sorted({i for i in ids if ids.count(i) > 1})
+        if duplicates:
+            raise WorkflowError(f"duplicate task ids: {', '.join(duplicates)}")
+        for task in self.tasks:
+            for port, ref in task.inputs.items():
+                source, dot, output = ref.partition(".")
+                if not dot or not output:
+                    raise WorkflowError(
+                        f"input {port!r} of task {task.id!r} must be "
+                        f"'<task>.<port>', got {ref!r}"
+                    )
+                if source not in ids:
+                    raise WorkflowError(
+                        f"input {port!r} of task {task.id!r} refers to "
+                        f"unknown task {source!r}"
+                    )
+        self.order()
+        return self
+
+    def task(self, task_id: str) -> TaskSpec:
+        """Return the task with the given id.
+
+        Raises:
+            WorkflowError: If there is no such task.
+        """
+        for task in self.tasks:
+            if task.id == task_id:
+                return task
+        raise WorkflowError(f"unknown task {task_id!r}")
+
+    def order(self) -> list[TaskSpec]:
+        """Return the tasks in topological order, stable in file order.
+
+        Raises:
+            WorkflowError: If the references form a cycle.
+        """
+        remaining = {t.id: set(t.dependencies()) for t in self.tasks}
+        done: set[str] = set()
+        ordered: list[TaskSpec] = []
+        while remaining:
+            ready = next(
+                (
+                    t
+                    for t in self.tasks
+                    if t.id in remaining and remaining[t.id] <= done
+                ),
+                None,
+            )
+            if ready is None:
+                raise WorkflowError(
+                    f"cycle among tasks: {', '.join(sorted(remaining))}"
+                )
+            ordered.append(ready)
+            done.add(ready.id)
+            del remaining[ready.id]
+        return ordered
+
+
+def load_workflow(path: Path) -> Workflow:
+    """Read a workflow from a YAML file.
+
+    Raises:
+        WorkflowError: If the file is not a valid workflow.
+    """
+    try:
+        data = yaml.safe_load(path.read_text())
+        if not isinstance(data, dict):
+            raise WorkflowError(f"{path}: not a mapping")
+        return Workflow(**data)
+    except (ValidationError, yaml.YAMLError, UnicodeDecodeError, TypeError) as error:
+        raise WorkflowError(f"{path}: {error}") from error
+
+
+def dump_workflow(workflow: Workflow, path: Path) -> None:
+    """Write a workflow as a YAML file."""
+    data = workflow.model_dump(mode="json")
+    path.write_text(yaml.safe_dump(data, sort_keys=False))
+
+
+class _IndentedDumper(yaml.SafeDumper):
+    """The safe dumper which indents a sequence below its key, as `- id:` below `tasks:`."""
+
+    def increase_indent(self, flow: bool = False, indentless: bool = False) -> None:
+        """Indent every block, also a sequence which PyYAML would leave indentless."""
+        super().increase_indent(flow, False)
+
+
+def workflow_yaml(workflow: Workflow) -> str:
+    """The compact YAML of a workflow: the fields which differ from the defaults.
+
+    `name` and `tasks` are always written, also when they are the defaults. A
+    sequence is indented below its key, as the workflows of the docs are written.
+
+    Args:
+        workflow: The workflow.
+
+    Returns:
+        The YAML text.
+    """
+    data = workflow.model_dump(mode="json", exclude_defaults=True)
+    data = {"name": workflow.name, "tasks": data.get("tasks", [])} | data
+    return yaml.dump(data, Dumper=_IndentedDumper, sort_keys=False)

simrun-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: simrun
+Version: 0.1.0
+Summary: Runner of simulation workflows on a k3s cluster with Argo Workflows and Kueue.
+Project-URL: Homepage, https://matthiaskoenig.github.io/simrun
+Project-URL: Documentation, https://matthiaskoenig.github.io/simrun
+Project-URL: Source, https://github.com/matthiaskoenig/simrun
+Project-URL: Issues, https://github.com/matthiaskoenig/simrun/issues
+Project-URL: Changelog, https://github.com/matthiaskoenig/simrun/tree/develop/release-notes
+Project-URL: Download, https://pypi.org/project/simrun
+Author-email: Matthias König <konigmatt@googlemail.com>
+Maintainer-email: Matthias König <konigmatt@googlemail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argo workflows,computational modeling,k3s,kubernetes,kueue,mcp,simulation,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.14
+Requires-Dist: fastapi>=0.162
+Requires-Dist: fastmcp>=4.1
+Requires-Dist: hera>=7.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: kubernetes>=37
+Requires-Dist: pydantic>=2.14
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=14
+Requires-Dist: tomlkit>=0.15.2
+Requires-Dist: typer>=0.27
+Requires-Dist: uvicorn>=0.54.0
+Provides-Extra: cwl
+Requires-Dist: cwl-utils>=0.46; extra == 'cwl'
+Requires-Dist: cwltool>=3.3.20260925135507; extra == 'cwl'
+Provides-Extra: dev
+Requires-Dist: bump-my-version>=1.6.7; extra == 'dev'
+Requires-Dist: cwl-utils>=0.46; extra == 'dev'
+Requires-Dist: cwltool>=3.3.20260925135507; extra == 'dev'
+Requires-Dist: mkdocstrings-python>=2.0.10; extra == 'dev'
+Requires-Dist: pre-commit>=4.7.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=9.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.17.4; extra == 'dev'
+Requires-Dist: tox!=4.67.5,>=4.64.9; extra == 'dev'
+Requires-Dist: tox-uv>=1.36.1; extra == 'dev'
+Requires-Dist: ty>=0.0.98; extra == 'dev'
+Requires-Dist: zensical>=0.0.73; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# simrun: simulation workflows on a k3s cluster
+[![CI-CD](https://github.com/matthiaskoenig/simrun/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/matthiaskoenig/simrun/actions/workflows/ci-cd.yml)
+[![Documentation](https://img.shields.io/badge/docs-simrun-3f51b5.svg)](https://matthiaskoenig.github.io/simrun)
+[![Version](https://img.shields.io/pypi/v/simrun.svg)](https://pypi.org/project/simrun/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/simrun.svg)](https://pypi.org/project/simrun/)
+[![MIT License](https://img.shields.io/pypi/l/simrun.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://img.shields.io/badge/DOI-after%20the%20first%20release-lightgrey.svg)](https://matthiaskoenig.github.io/simrun/development/#pypi-and-zenodo)
+
+`simrun` runs simulation workflows on a small cluster of servers with [k3s](https://k3s.io), [Argo Workflows](https://argoproj.github.io/workflows/) and [Kueue](https://kueue.sigs.k8s.io). 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
+
+```bash
+simrun submit fit.yaml --source model=~/git/pkdb_models --source sbmlsim=~/git/sbmlsim --group hctz
+simrun wait <run>
+simrun compare <run> <run>
+```
+
+The documentation is available at [https://matthiaskoenig.github.io/simrun](https://matthiaskoenig.github.io/simrun): [installation](https://matthiaskoenig.github.io/simrun/installation/), [concepts](https://matthiaskoenig.github.io/simrun/concepts/), [workflows](https://matthiaskoenig.github.io/simrun/workflows/), [command line](https://matthiaskoenig.github.io/simrun/command-line/), [agents and MCP](https://matthiaskoenig.github.io/simrun/mcp/), [plugins](https://matthiaskoenig.github.io/simrun/plugins/), [service](https://matthiaskoenig.github.io/simrun/service/), [cluster deployment](https://matthiaskoenig.github.io/simrun/deployment/) and [development](https://matthiaskoenig.github.io/simrun/development/).
+
+If you have any questions or issues please [open an issue](https://github.com/matthiaskoenig/simrun/issues).
+
+## Installation
+
+```bash
+pip install simrun
+```
+
+`simrun` needs python 3.14 or newer and runs on Linux, see [Installation](https://matthiaskoenig.github.io/simrun/installation/).
+
+## How to cite
+
+If you use `simrun` please cite the archived software on [Zenodo](https://zenodo.org); the DOI follows with the first release, see [CITATION.cff](CITATION.cff).
+
+## License
+
+`simrun` is licensed under the [MIT License](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](https://qualiperf.de) (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

simrun-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+simrun/__init__.py,sha256=2WkMl29mm1mI4GONAAt1hwehkyf5Mk_eGtZBeo19Sfs,88
+simrun/argo.py,sha256=AdOoY3cHBQFAZEcP9oHIcnYPuf-dtlT-arSQeUn3E8M,17169
+simrun/build_constraints.txt,sha256=vUuUCjavINiqy0H0W4Qa4lx_1OQ29RswduUukMHd2QA,722
+simrun/cgroup.py,sha256=pkLqXMRssLstML-2BkUdNZkpjuXfMdlLXuELTnoGpCI,2240
+simrun/cli.py,sha256=TTmBtEP4k8xgGxM9xICJ3j9uG6oT9jPWN9eWO-eJGas,10996
+simrun/client.py,sha256=Z6r2beJj2M1RXB420inAIW7p7Ow4rNiRU9p_p72czDQ,15077
+simrun/config.py,sha256=vYvO0CIDThMJBm76fcT-vOZcjBDzWtypmcWCUG7P9mY,2882
+simrun/cwl.py,sha256=iMNWRPdqNKmXlROSmnrb_GGN1xyoJIx2vL9Uh4V1mUs,10294
+simrun/demo.py,sha256=I0Gy1VpKdGA95crR_4UNxrttpgEJK9AVjBrB2cX6Dfo,3039
+simrun/edit.py,sha256=nYNhLJXWJrRFUL0W2jEC7weuHexRTkihasR47AW6LMo,14618
+simrun/environment.py,sha256=f92LEuwPcLz5Vu3JTUbzl2cRKhJQ9wsyLlNg0sad_mA,16413
+simrun/ledger.py,sha256=RD6tuEoUSJ2p8qfdWI6s12jgxqwYx3-r-wdQjaVTxik,10799
+simrun/mcp.py,sha256=xIUd1QXTIGGh8gPzT0xKXHejNAky4atW0vi3R2VsJNY,5779
+simrun/planner.py,sha256=vdaCrFwFDd_vI639vhkTEbS3xkIj2cx6tkMwqKACSag,9907
+simrun/plugins.py,sha256=nG7qm_d4sF4oc0qhPPnUBhueg4TDM2a9gZh4bM4RMvw,5436
+simrun/plugins_builtin.py,sha256=k8D_28hA9hF5v1y-t0sFxTiTRgJWYi-AXgc9WhmkErk,735
+simrun/podspec.py,sha256=SlRZcECVPXtx8RzWMn6AqRYg6k9Yxctga8SZ1De5zFY,5976
+simrun/resources.py,sha256=8E-wfz96dqE5b7gmPjjq4v8uMyxy-7COrSqD6weYsI4,9709
+simrun/snapshot.py,sha256=iqyhO3C1ONddOXIPHKlPK0VkHCDQht1ixTUHxvz0_FM,7020
+simrun/store.py,sha256=BefcMp_7psI5JcBnZBhW3hyGqxfoIASge0pLvXUOJrw,5749
+simrun/testing.py,sha256=NDYf5iG5yP3fDnrJPodVCJzmMnl-J9MuE17eHJ7PENY,9986
+simrun/worker.py,sha256=NcI4jjLiw_l-Z5xuY3UiUMIet3KQON8eP2snbqDgQZ8,40011
+simrun/workflow.py,sha256=Z-XEsS2VKkutO--As8L6Lxsq5MaOglkudBI0diPzE4U,6294
+simrun/service/__init__.py,sha256=uB44sSOqMuPgxogrzpSbqTSLlOUAd1giqDFmRocqJFY,83
+simrun/service/app.py,sha256=pfAub9oPGOa7ynzJoJATn3FfC53uInK3ze7ih4-24v0,64999
+simrun/service/argo_backend.py,sha256=8pPRVl3Jpgz5IzqMyYR8ywEUaoMMqW9BdQi-MYie8pk,33873
+simrun/service/auth.py,sha256=MlVBPMy6X_NACq66YO9B1CLvkSazTwk10FaUUkxz9nA,2944
+simrun/service/backend.py,sha256=E-jsRzcYPCQCg0Xejfh_MfM3ddAJoPM4uaOf21bp-P8,5685
+simrun/service/compare.py,sha256=o-P-Rwghmo4pZ4a0XTTFqVBF_EPvd6KRa7FJXF_aCjc,2404
+simrun/service/controller.py,sha256=K0NpDTgr0_acfPCu3Xbk10neJKCbL45Ah1k70EDuXws,32918
+simrun/service/edits.py,sha256=kBuQr7AyPViWm-EYDIxeuT-l0T-0ryBFBpjB0Nv68Y8,12974
+simrun/service/index.py,sha256=fPQCImiVHXfCRCib1scWCxG1cjx31qwBhUuOdXDBYwY,10914
+simrun/service/logs.py,sha256=fmLfVDyvbbqQeZaHDjNR9RZ2Usq4P1UO45u405hCVPY,3324
+simrun/service/submission.py,sha256=yTYGxLXoKE6PrTWfjhPFxYgnVmt7yMF71xltxCb_u_c,13852
+simrun-0.1.0.dist-info/METADATA,sha256=LxhHtHnHuoATTKNEkEN_tn_T9iwYcZ1m2_LuFfwRd48,6813
+simrun-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+simrun-0.1.0.dist-info/entry_points.txt,sha256=mYlANnOVF5jAfb1G-5RFtiNEbCnoPs2dIe34ZALW7lQ,281
+simrun-0.1.0.dist-info/licenses/LICENSE,sha256=zPHyGxsERxx2deQExcGSq3mg5NgDaCZ5-4pfkbgsEXo,1059
+simrun-0.1.0.dist-info/RECORD,,

simrun-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simrun-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,10 @@
+[console_scripts]
+simrun = simrun.cli:app
+simrun-exec = simrun.worker:exec_main
+simrun-mcp = simrun.mcp:main
+simrun-merge = simrun.worker:merge_main
+simrun-worker = simrun.worker:main
+
+[simrun.task_types]
+command = simrun.plugins_builtin:COMMAND
+demo.squares = simrun.demo:SQUARES

simrun-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Matthias König
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.