simrun 0.1.0__tar.gz

simrun-0.1.0/.bumpversion.toml

@@ -0,0 +1,24 @@
+[tool.bumpversion]
+current_version = "0.1.0"
+commit = true
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+# no tag: the bump is merged into develop through a pull request, which
+# rewrites the commit, so the tag is created on develop afterwards
+tag = false
+sign_tags = false
+tag_name = "{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+allow_dirty = false
+message = "Bump version: {current_version} → {new_version}"
+commit_args = ""
+
+[[tool.bumpversion.files]]
+filename = "./src/simrun/__init__.py"
+
+[[tool.bumpversion.files]]
+filename = "./CITATION.cff"

simrun-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @matthiaskoenig

simrun-0.1.0/.github/actions/setup/action.yml

@@ -0,0 +1,48 @@
+name: Set up the environment
+description: >-
+  Install uv with its cache, set the python version of the job and sync the
+  environment of the project from uv.lock
+inputs:
+  python-version:
+    description: the python version, e.g. 3.14
+    required: true
+  sync:
+    description: >-
+      the arguments of `uv sync --locked`, e.g. `--extra dev`; empty does not
+      sync
+    required: false
+    default: ""
+  save-cache:
+    description: >-
+      whether the job saves the cache of uv; jobs which share a key would race
+      for it and warn "Unable to reserve cache"
+    required: false
+    default: "false"
+  cache:
+    description: >-
+      whether the job uses the cache of uv at all; the release builds the
+      distributions without one, so nothing a cache holds ends up in them
+    required: false
+    default: "true"
+runs:
+  using: composite
+  steps:
+    - name: Install uv and set the python version
+      # astral-sh/setup-uv publishes no floating major tag beyond v7
+      uses: astral-sh/setup-uv@v10.2.0
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: ${{ inputs.cache }}
+        # the interpreter is cached with the packages instead of downloaded by every run
+        cache-python: ${{ inputs.cache }}
+        save-cache: ${{ inputs.save-cache }}
+    - name: Sync the environment from the lock (fails if uv.lock is out of date with pyproject.toml, run `uv lock`)
+      if: inputs.sync != ''
+      shell: bash
+      env:
+        SYNC: ${{ inputs.sync }}
+      # every job runs against the versions of uv.lock, the same ones as a
+      # local `uv sync`. `--locked` refuses to update the lock: a change of the
+      # dependencies in pyproject.toml has to come with the `uv lock` which
+      # records it. Word splitting of the arguments is intended
+      run: uv sync --locked $SYNC

simrun-0.1.0/.github/dependabot.yml

@@ -0,0 +1,55 @@
+# Keep the GitHub Actions used in the workflows and the locked python dependencies up to date,
+# monthly, since every update pull request runs the checks.
+# See https://docs.github.com/code-security/dependabot/dependabot-version-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    # a single pull request for all action updates instead of one per action
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+
+  # the locked python dependencies (uv.lock), bumped together
+  - package-ecosystem: "uv"
+    directory: "/"
+    # only uv.lock is updated: the default would raise the lower bounds in
+    # pyproject.toml, which are what a user of the library installs against,
+    # so they are only ever changed by hand
+    versioning-strategy: lockfile-only
+    schedule:
+      interval: "monthly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "build"
+
+  # the locked npm dependencies of the web app (frontend/package-lock.json), bumped together
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "monthly"
+    ignore:
+      # vue-tsc and openapi-typescript need the API of the compiler in
+      # javascript, which TypeScript 7 (the native port) does not have
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+      # the types of node follow the node of continuous integration (24)
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
+    groups:
+      npm-dependencies:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "build"

simrun-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- what does this change and why -->
+
+## Checklist
+
+- [ ] the pull request targets `develop`
+- [ ] tests were added or updated for the change
+- [ ] `pytest` and `ty check` pass locally, `tox run-parallel` runs the tests on every supported python
+- [ ] the change to the cluster was tested on k3d (`SIMRUN_K3D=1 pytest -m cluster`) or the pull request has the label `cluster`
+- [ ] `ruff check` and `ruff format` are clean, e.g., via `pre-commit run --all-files`
+- [ ] public functions and classes have type annotations and a docstring
+- [ ] user visible changes are in `release-notes/` and, if needed, in `docs/`

simrun-0.1.0/.github/rulesets/apply.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Apply the repository policies of simrun: the merge settings of the
+# repository and the rulesets in this directory. The script is idempotent, i.e.,
+# a ruleset which already exists is updated instead of added a second time, so
+# it can be run again after every change of the json files.
+#
+# The file name of a ruleset has to match the "name" in the json. A ruleset which
+# is removed from this directory stays on the repository, delete it with
+# `gh api -X DELETE repos/<owner>/<repo>/rulesets/<id>`.
+#
+# Requires the github cli (https://cli.github.com) authenticated as a user with
+# admin permission on the repository:
+#
+#   gh auth login
+#   .github/rulesets/apply.sh [owner/repo]
+#
+set -euo pipefail
+
+REPO="${1:-matthiaskoenig/simrun}"
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "repository settings of ${REPO}"
+gh api -X PATCH "repos/${REPO}" \
+  -F allow_auto_merge=true \
+  -F delete_branch_on_merge=true \
+  -F allow_update_branch=true \
+  -F allow_squash_merge=true \
+  -F allow_rebase_merge=true \
+  -F allow_merge_commit=false \
+  --silent
+
+for path in "${DIR}"/*.json; do
+  name="$(basename "${path}" .json)"
+  id="$(gh api "repos/${REPO}/rulesets" --jq "map(select(.name == \"${name}\")) | .[0].id // empty")"
+  if [[ -n "${id}" ]]; then
+    gh api -X PUT "repos/${REPO}/rulesets/${id}" --input "${path}" --silent
+    echo "ruleset ${name} updated (${id})"
+  else
+    id="$(gh api -X POST "repos/${REPO}/rulesets" --input "${path}" --jq .id)"
+    echo "ruleset ${name} created (${id})"
+  fi
+done

simrun-0.1.0/.github/rulesets/develop.json

@@ -0,0 +1,61 @@
+{
+  "name": "develop",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "refs/heads/develop"
+      ],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "required_linear_history"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "allowed_merge_methods": [
+          "squash",
+          "rebase"
+        ],
+        "require_extra_approval_for_unattributed_changes": false
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          {
+            "context": "tests"
+          },
+          {
+            "context": "ruff"
+          },
+          {
+            "context": "ty"
+          },
+          {
+            "context": "docs"
+          }
+        ]
+      }
+    }
+  ]
+}

simrun-0.1.0/.github/rulesets/main.json

@@ -0,0 +1,25 @@
+{
+  "name": "main",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "refs/heads/main"
+      ],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "required_linear_history"
+    }
+  ]
+}

simrun-0.1.0/.github/rulesets/tags.json

@@ -0,0 +1,16 @@
+{
+  "name": "tags",
+  "target": "tag",
+  "enforcement": "active",
+  "bypass_actors": [],
+  "conditions": {
+    "ref_name": {
+      "include": ["~ALL"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {"type": "deletion"},
+    {"type": "non_fast_forward"}
+  ]
+}

simrun-0.1.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,277 @@
+name: CI-CD
+
+on:
+  push:
+    # feature branches are tested through their pull request, tags release
+    branches: [develop, main]
+    tags: ['*']
+  pull_request:
+    branches: [develop, main]
+  workflow_dispatch:
+
+# least privilege by default, the release job raises what it needs
+permissions:
+  contents: read
+
+concurrency:
+  # a newer run supersedes the running one of the same pull request. A push is
+  # a group of its own, so it is never superseded: a release waits for the run
+  # of its commit on develop (see the job `tested`), and two merges in a row
+  # would otherwise leave the first commit untested. A release is never
+  # superseded either, every tag is a group of its own
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || format('{0}-{1}', github.ref, github.sha) }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    # a tag is not tested again, see the job `tested`
+    if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        # simrun runs on linux only (cgroups, k3s); every supported python
+        python-version: ["3.14", "3.15"]
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Set up the environment
+      # the dependencies are the versions of uv.lock, the package is installed
+      # as a wheel and not editable, so the tests run against what is
+      # published. The key of the cache has the os and the python version but
+      # not the job, so every entry of the matrix has a key of its own and
+      # saves it; the other jobs with python 3.14 (ty, docs, cluster) share the
+      # key of the entry 3.14 and only restore it
+      uses: ./.github/actions/setup
+      with:
+        python-version: ${{ matrix.python-version }}
+        sync: --extra dev --no-editable
+        save-cache: "true"
+    - name: Test
+      # in parallel on every core (`addopts` of pyproject.toml), without the
+      # tests on the cluster (`-m 'not cluster'` of `addopts`, see the job
+      # `cluster`); the slowest tests are listed at the end of the log
+      run: uv run --no-sync pytest --durations=15
+
+  install:
+    # the package as `pip install simrun` installs it, without extras: the
+    # environment of the test matrix has the extras of `dev`, which would hide
+    # a dependency the package needs and does not declare. It is the one job
+    # which does not use uv.lock: it resolves from pyproject.toml as the
+    # install of a user does, i.e. the newest releases within the bounds, so a
+    # release of a dependency which breaks simrun shows up here before
+    # dependabot moves the lock to it
+    name: plain install
+    if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Set up uv and python
+      uses: ./.github/actions/setup
+      with:
+        python-version: "3.14"
+    - name: Install the package without extras
+      run: |
+        uv venv "$RUNNER_TEMP/plain"
+        uv pip install --python "$RUNNER_TEMP/plain/bin/python" .
+    - name: Import every module and run the command line
+      # isolated (-I) and outside of the repository, so the package is the
+      # installed one and not the sources. Every module but `simrun.cwl`, whose
+      # export needs the extra `cwl`, imports at the top what it needs
+      working-directory: ${{ runner.temp }}
+      run: |
+        "$RUNNER_TEMP/plain/bin/python" -I -c '
+        import importlib, pkgutil, simrun
+        names = [m.name for m in pkgutil.walk_packages(simrun.__path__, "simrun.")]
+        for name in names:
+            importlib.import_module(name)
+        print(f"simrun {simrun.__version__}: {len(names)} modules imported")
+        '
+        "$RUNNER_TEMP/plain/bin/simrun" --help
+        "$RUNNER_TEMP/plain/bin/simrun" submit --help
+
+  frontend:
+    # the web app in frontend/: the versions of package-lock.json, the types,
+    # the tests and the build the service serves at /ui/
+    if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Set up node
+      uses: actions/setup-node@v7
+      with:
+        node-version: 24
+        cache: npm
+        cache-dependency-path: frontend/package-lock.json
+    - name: Install the dependencies
+      run: npm ci
+    - name: Check the types
+      run: npm run typecheck
+    - name: Test
+      run: npm test
+    - name: Build
+      run: npm run build
+    - name: Check that the types of the API are those of openapi.json
+      # src/api/schema.d.ts is generated from src/api/openapi.json, which a
+      # test of the service keeps equal to the API; after a change of the API
+      # run `uv run python scripts/openapi.py`, then `npm run types`
+      run: |
+        npm run types
+        git diff --exit-code -- src/api/schema.d.ts
+
+  tests:
+    # the one check the branch protection requires; the names of the matrix
+    # jobs change with the matrix, this name does not, see .github/rulesets/
+    name: tests
+    needs: [test, install, frontend]
+    if: ${{ always() && !startsWith(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+    - name: Check the results of the test matrix, of the plain install and of the web app
+      env:
+        RESULT: ${{ needs.test.result }}
+        INSTALL: ${{ needs.install.result }}
+        FRONTEND: ${{ needs.frontend.result }}
+      run: |
+        echo "test matrix: $RESULT, plain install: $INSTALL, web app: $FRONTEND"
+        test "$RESULT" = "success" && test "$INSTALL" = "success" && test "$FRONTEND" = "success"
+
+  cluster:
+    # the tests on a k3d cluster with Kueue, Argo Workflows and BuildKit, on a
+    # push to develop, on a release and when the workflow is started by hand.
+    # A pull request runs them with the label `cluster`, see cluster.yml
+    if: github.event_name != 'pull_request'
+    uses: ./.github/workflows/cluster.yml
+
+  tested:
+    # a release does not run the test matrix again. The tag is on a commit of
+    # develop, and the push of that commit ran the matrix on exactly this
+    # tree; the job waits for that run and fails unless it succeeded, so the
+    # tag can be pushed right after the merge of the release
+    name: tested on develop
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    permissions:
+      actions: read  # the runs of this workflow
+      contents: read
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+        persist-credentials: false
+    - name: Check that the tag is on develop
+      run: |
+        if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/develop; then
+          echo "::error::$GITHUB_REF_NAME is not on develop, a release is tagged on develop"
+          exit 1
+        fi
+    - name: Wait for the run of the commit on develop
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        api="repos/$GITHUB_REPOSITORY/actions"
+        # the run starts with the merge, a tag pushed right after it may be first
+        run_id=""
+        for attempt in $(seq 1 20); do
+          run_id=$(gh api "$api/workflows/ci-cd.yml/runs?branch=develop&event=push&head_sha=$GITHUB_SHA" \
+            --jq '.workflow_runs[0].id // empty' || true)
+          [ -n "$run_id" ] && break
+          sleep 15
+        done
+        if [ -z "$run_id" ]; then
+          echo "::error::no CI-CD run of the push of $GITHUB_SHA to develop"
+          exit 1
+        fi
+        url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$run_id"
+        echo "waiting for $url"
+        # a failed request answers nothing, which is not `completed` either
+        until [ "$(gh api "$api/runs/$run_id" --jq .status || true)" = "completed" ]; do
+          sleep 30
+        done
+        conclusion=$(gh api "$api/runs/$run_id" --jq .conclusion)
+        echo "$url: $conclusion"
+        if [ "$conclusion" != "success" ]; then
+          echo "::error::the tests of $GITHUB_SHA on develop did not pass ($url); once they do, re-run the failed jobs of this release"
+          exit 1
+        fi
+
+  release:
+    needs: [tested, cluster]
+    if: >-
+      ${{ !cancelled() && startsWith(github.ref, 'refs/tags/')
+      && needs.tested.result == 'success'
+      && needs.cluster.result == 'success' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/simrun
+    permissions:
+      id-token: write  # trusted publishing to PyPI
+      contents: write  # create the GitHub release
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Set up uv
+      uses: ./.github/actions/setup
+      with:
+        python-version: "3.14"
+        cache: "false"
+    - name: Check that the tag is the version of the package
+      run: |
+        version=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/simrun/__init__.py)
+        if [ "$version" != "$GITHUB_REF_NAME" ]; then
+          echo "::error::the tag $GITHUB_REF_NAME is not the version $version of src/simrun/__init__.py"
+          exit 1
+        fi
+    - name: Build package
+      # the sdist and the wheel
+      run: uvx hatch build
+    - name: Check the package
+      run: uvx twine check --strict dist/*
+    - name: Publish to PyPI
+      # trusted publishing: the environment `pypi` of this repository is the
+      # publisher of the project on pypi.org, no token
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: dist
+    - name: Create GitHub release
+      # the release triggers the archive on Zenodo
+      uses: softprops/action-gh-release@v3
+      with:
+        body_path: "release-notes/${{ github.ref_name }}.md"
+        files: dist/*
+        draft: false
+        prerelease: false
+
+  sync-main:
+    # main tracks the latest published release, see docs/development.md
+    needs: release
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write  # fast-forward main to the released commit
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        # a shallow clone cannot be pushed to another branch
+        fetch-depth: 0
+    - name: Fast-forward main to the release
+      # no --force: the push fails loudly if it would not be a fast-forward
+      run: git push origin HEAD:main

simrun-0.1.0/.github/workflows/cluster.yml

@@ -0,0 +1,82 @@
+name: cluster
+
+# The tests on a k3d cluster (`tests/cluster`): k3s with Kueue, Argo Workflows,
+# BuildKit and a registry in docker, the service in the process of the tests.
+# They take half an hour and are not part of the required checks: the job
+# `cluster` of CI-CD calls this workflow on a push to develop, on a release,
+# which waits for it, and when CI-CD is started by hand; a pull request runs it
+# when it has the label `cluster`, once the label is added and with every push
+# after it.
+
+on:
+  workflow_call:
+  pull_request:
+    branches: [develop, main]
+    types: [opened, synchronize, reopened, labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  cluster:
+    name: cluster
+    # a pull request without the label skips the job; adding another label to
+    # a pull request with the label does not run it again
+    if: >-
+      ${{ github.event_name != 'pull_request'
+      || (github.event.action == 'labeled' && github.event.label.name == 'cluster')
+      || (github.event.action != 'labeled' && contains(github.event.pull_request.labels.*.name, 'cluster')) }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 75
+    concurrency:
+      # a newer push to a pull request supersedes its running cluster tests;
+      # a push to develop and a release are groups of their own
+      group: cluster-${{ github.event.pull_request.number || github.run_id }}
+      cancel-in-progress: true
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
+    - name: Free the disk for the images
+      # the tests need about 20 GiB for the images of k3s, Kueue, Argo,
+      # BuildKit, the runs and the environments (`MIN_FREE_GB` of
+      # tests/cluster/k3d_cluster.py); the toolchains of the runner image
+      # which the tests do not use take more than that
+      run: |
+        df -h /
+        sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /usr/local/.ghcup \
+          /opt/hostedtoolcache/CodeQL /usr/local/share/boost /usr/share/swift
+        docker system prune --all --force
+        df -h /
+    - name: Set up the environment
+      uses: ./.github/actions/setup
+      with:
+        python-version: "3.14"
+        sync: --extra dev
+    - name: Set up node
+      # the image of the service has the web app, built in frontend/
+      # (`build_service_image` of tests/cluster/k3d_cluster.py)
+      uses: actions/setup-node@v7
+      with:
+        node-version: 24
+        cache: npm
+        cache-dependency-path: frontend/package-lock.json
+    - name: Test on the k3d cluster
+      # the session downloads k3d and kubectl into .tools/bin and creates the
+      # cluster; the cluster is kept (`SIMRUN_K3D_KEEP=1`), the runner is
+      # thrown away, so the next step can describe it after a failure
+      env:
+        SIMRUN_K3D: "1"
+        SIMRUN_K3D_KEEP: "1"
+      run: uv run --no-sync pytest -m cluster tests/cluster --durations=0
+    - name: Describe the cluster after a failure
+      if: failure()
+      env:
+        KUBECONFIG: .tools/kubeconfig
+      run: |
+        kubectl=.tools/bin/kubectl
+        $kubectl get nodes -o wide || true
+        $kubectl get pods --all-namespaces -o wide || true
+        $kubectl get workflows,workloads --namespace simrun || true
+        $kubectl get events --all-namespaces --sort-by=.lastTimestamp | tail -n 200 || true
+        df -h / || true