kinepet 0.4.2__tar.gz

kinepet-0.4.2/.github/workflows/deploy-pages.yml

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+name: Deploy Documentation Artifact
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy documentation to GitHub Pages
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy the validated artifact from this run
+        id: deployment
+        uses: actions/deploy-pages@v4

kinepet-0.4.2/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+      - ".github/workflows/pages.yml"
+      - ".github/workflows/deploy-pages.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+      - ".github/workflows/pages.yml"
+      - ".github/workflows/deploy-pages.yml"
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      source_ref:
+        description: Source tag, branch, or commit; defaults to the triggering commit
+        type: string
+        default: ""
+      upload_pages:
+        description: Upload the built site for the Pages deployment workflow
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_ref || github.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m pip install uv
+      - run: uv sync --locked --group docs
+      - run: uv run --group docs mkdocs build --strict
+      - name: Upload GitHub Pages artifact
+        if: inputs.upload_pages
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+          retention-days: 90

kinepet-0.4.2/.github/workflows/pages.yml

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+name: Publish Documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      source_ref:
+        description: Release tag or reviewed documentation-only branch/commit to publish
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main' && inputs.source_ref != ''
+    uses: ./.github/workflows/docs.yml
+    with:
+      source_ref: ${{ inputs.source_ref }}
+      upload_pages: true
+
+  deploy:
+    needs: build
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: ./.github/workflows/deploy-pages.yml

kinepet-0.4.2/.github/workflows/publish.yml

@@ -0,0 +1,213 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+name: Publish Distributions
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release_metadata:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Check tag, version, license, and release notes
+        env:
+          RELEASE_REF: ${{ github.ref }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          test "${RELEASE_REF#refs/tags/}" != "$RELEASE_REF"
+          python scripts/check_release.py --tag "$RELEASE_TAG" --notes-output "$RUNNER_TEMP/release-notes.md"
+
+  tests:
+    needs: release_metadata
+    uses: ./.github/workflows/tests.yml
+    with:
+      full_matrix: true
+
+  docs:
+    needs: release_metadata
+    uses: ./.github/workflows/docs.yml
+    with:
+      upload_pages: true
+
+  distributions:
+    needs: release_metadata
+    uses: ./.github/workflows/wheels.yml
+
+  prepare_artifacts:
+    name: Validate and save release artifacts
+    runs-on: ubuntu-latest
+    needs: [tests, docs, distributions]
+    outputs:
+      artifact_id: ${{ steps.upload.outputs.artifact-id }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: release/dist
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: release/dist
+          merge-multiple: true
+      - name: Check distribution licenses and contents
+        run: python scripts/check_distributions.py release/dist --require-license
+      - name: Check package metadata and README rendering
+        run: |
+          python -m pip install twine
+          python -m twine check --strict release/dist/*
+      - name: Prepare release notes
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python scripts/check_release.py --tag "$RELEASE_TAG" --notes-output release/release-notes.md
+      - name: Record distribution checksums
+        working-directory: release/dist
+        run: sha256sum * > ../SHA256SUMS
+      - uses: actions/upload-artifact@v4
+        id: upload
+        with:
+          name: release-distributions
+          path: release/
+          if-no-files-found: error
+          retention-days: 90
+
+  testpypi:
+    name: Publish to TestPyPI
+    needs: prepare_artifacts
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/kinepet
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          artifact-ids: ${{ needs.prepare_artifacts.outputs.artifact_id }}
+          path: release
+          merge-multiple: true
+      - name: Verify saved artifacts
+        working-directory: release/dist
+        run: sha256sum --check ../SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: release/dist/
+          repository-url: https://test.pypi.org/legacy/
+
+  draft_release:
+    name: Prepare draft GitHub release
+    outputs:
+      release_id: ${{ steps.draft.outputs.result }}
+    needs: [prepare_artifacts, testpypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          artifact-ids: ${{ needs.prepare_artifacts.outputs.artifact_id }}
+          path: release
+          merge-multiple: true
+      - name: Create draft from the changelog
+        id: draft
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const tag = context.ref.replace(/^refs\/tags\//, '');
+            // The tag lookup endpoint excludes drafts; list releases with write access.
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              ...context.repo, per_page: 100
+            });
+            const existing = releases.find(release => release.tag_name === tag);
+            if (existing && !existing.draft) {
+              throw new Error(`Release ${tag} is already published; do not republish this version.`);
+            }
+            // Preserve any notes the maintainer edited while reviewing a draft.
+            const release = existing || (await github.rest.repos.createRelease({
+              ...context.repo,
+              tag_name: tag,
+              name: `KinePET ${tag}`,
+              body: require('fs').readFileSync('release/release-notes.md', 'utf8'),
+              draft: true,
+              prerelease: /(?:a|b|rc)\d/.test(tag)
+            })).data;
+            await core.summary
+              .addHeading('Ready for release review')
+              .addLink('Review draft release notes', release.html_url)
+              .addRaw('\n\nVerify the TestPyPI installation, then approve the pypi environment deployment.\n')
+              .write();
+            return release.id;
+
+  pypi:
+    name: Approve and publish to PyPI
+    needs: [prepare_artifacts, draft_release]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kinepet
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          artifact-ids: ${{ needs.prepare_artifacts.outputs.artifact_id }}
+          path: release
+          merge-multiple: true
+      - name: Verify the artifacts tested on TestPyPI
+        working-directory: release/dist
+        run: sha256sum --check ../SHA256SUMS
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: release/dist/
+
+  github_release:
+    name: Publish GitHub release
+    needs: [pypi, draft_release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/github-script@v7
+        env:
+          RELEASE_ID: ${{ needs.draft_release.outputs.release_id }}
+        with:
+          script: |
+            const tag = context.ref.replace(/^refs\/tags\//, '');
+            const {data: release} = await github.rest.repos.getRelease({
+              ...context.repo, release_id: Number(process.env.RELEASE_ID)
+            });
+            if (release.tag_name !== tag) throw new Error("Release tag changed during review");
+            if (release.draft) {
+              await github.rest.repos.updateRelease({
+                ...context.repo, release_id: release.id, draft: false
+              });
+            }
+            await core.summary.addLink('Published release', release.html_url).write();
+
+  documentation:
+    name: Publish released documentation
+    needs: github_release
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: ./.github/workflows/deploy-pages.yml

kinepet-0.4.2/.github/workflows/tests.yml

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      full_matrix:
+        description: Test every supported Python version
+        type: boolean
+        default: true
+  workflow_call:
+    inputs:
+      full_matrix:
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Python and C++ tests (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ fromJSON(inputs.full_matrix && '["3.11", "3.12", "3.13"]' || '["3.13"]') }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        run: python -m pip install --upgrade uv
+      - name: Install dependencies
+        run: uv sync --locked --group dev --python ${{ matrix.python-version }}
+      - name: Configure CMake
+        run: cmake -S . -B build -DPython_EXECUTABLE="$(uv run --python ${{ matrix.python-version }} python -c 'import sys; print(sys.executable)')"
+      - name: Build CLI and extension
+        run: cmake --build build --parallel
+      - name: Run C++ numerical tests
+        run: ctest --test-dir build --output-on-failure
+      - name: Run Python tests, including CLI parity
+        run: uv run --python ${{ matrix.python-version }} python -m pytest -q

kinepet-0.4.2/.github/workflows/wheels.yml

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+name: Build Distributions
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build --sdist
+
+      - name: Check source archive
+        run: python scripts/check_distributions.py dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  build_wheels:
+    name: Build wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-15
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install cibuildwheel
+        run: python -m pip install --upgrade cibuildwheel
+
+      - name: Build wheels
+        env:
+          CIBW_BUILD: cp311-* cp312-* cp313-*
+          CIBW_ARCHS_MACOS: arm64
+          CIBW_BUILD_FRONTEND: pip
+          CIBW_BUILD_VERBOSITY: 1
+          CIBW_TEST_COMMAND: python {project}/scripts/wheel_smoke.py
+        run: python -m cibuildwheel --output-dir wheelhouse
+
+      - name: Check wheel contents
+        run: python scripts/check_distributions.py wheelhouse
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl

kinepet-0.4.2/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+*.venv*
+site/
+.DS_Store
+
+# Virtual environments
+.venv
+nohup.out
+AGENTS.md
+data/
+output/
+notebooks/

kinepet-0.4.2/.python-version

@@ -0,0 +1 @@
+3.13

kinepet-0.4.2/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## 0.4.2 (2026-11-11)
+
+This release updates packaging, release automation, and documentation hosting.
+The fitting algorithms and public model API are unchanged from 0.4.1.
+
+### Changed
+
+- Build distributions once, upload them to TestPyPI for review, then publish the
+  same files to official PyPI after approval through the `pypi` environment.
+  Saved artifact IDs and SHA-256 checksums preserve the files between uploads.
+- Generate draft GitHub release notes from the matching changelog entry and
+  publish the release after the PyPI upload succeeds.
+- Deploy the validated release documentation to GitHub Pages after successful
+  PyPI and GitHub release publication, retaining `https://kinepet.salodev.no/`.
+  Development pushes validate documentation without updating the live site;
+  manual publication requires an explicit source tag, branch, or commit.
+- Run one Linux/Python configuration for routine pushes and pull requests.
+  Reserve the full supported Python test matrix and platform distribution builds
+  for release tags and manual runs.
+- Document Trusted Publishing setup, release review and recovery, and GitHub
+  Pages configuration. Update citation metadata and add the Zenodo DOI badge.
+
+### Fixed
+
+- Replace the retired `macos-14` runner with `macos-15` and explicitly build
+  Apple Silicon (`arm64`) wheels. The unavailable runner previously prevented
+  the distribution workflow from reaching publication.
+
+## 0.4.1 (2026-11-11)
+
+### Added
+
+- Explicit Python `Irreversible2TCM` and `Reversible2TCM` descriptions with
+  `FittedVB()` or `FixedVB(value)`. Accepted by fitting, forward evaluation, and
+  bounds helpers alongside the existing `irr` / `rev` names.
+- Direct C++ tests for reversible coefficient recovery, parameter layout,
+  rejected warm starts, and pre-refactor initialization baselines.
+- Python model-configuration and CLI/API parity tests, including shared/per-TAC
+  inputs and optional AIF parameters. C++ numerical tests run in CLI CI.
+- Architecture and equation-location guide in `docs/architecture.md`.
+
+### Changed
+
+- Move paper-specific comparison scripts and tests, standalone simulations,
+  and the synthetic benchmark to the companion validation repository. Library
+  numerical tests, CLI parity checks, and wheel validation remain in KinePET.
+- Group contributor and maintenance documentation separately from user guides.
+
+- C++ models carry their blood-fraction setting explicitly; optional AIF settings
+  are grouped rather than passed as repeated boolean/value arguments.
+- Model-specific LLS regressions and kinetic parameter recovery have separate,
+  named implementations with coefficient definitions beside the equations.
+- Tissue kinetics, convolution, AIF transformations, vascular mixing, parameter
+  layout, bounds, and default frame weights have distinct source files.
+- Internal per-curve C++ entrypoints are named `fit_tac` and
+  `fit_tac_with_initial_guess`, replacing the legacy voxel terminology.
+- Python public exports, model descriptions, fitting, evaluation, validation, and
+  result containers have separate modules.
+- Distribution builds omit C++ test targets; standalone CMake builds retain CTest.
+
+The model API refactor preserves string-model calls, effective defaults, result
+shapes, CLI flags and filenames, status semantics, bounds, and numerical algorithms.
+With a model object, configure blood fraction on that object; combining it with
+legacy `fit_vb` / `fixed_vb` options raises `ValueError`. A standalone evaluation
+also rejects a numeric `vB` that conflicts with the model's `FixedVB`.
+
+### Fixes and distribution updates
+
+- Reject nonfinite inputs, invalid time grids/weights, and invalid solver options
+  in the shared C++ path. Preserve per-TAC invalid status 5 in batch outputs;
+  guard objective, derivative, and linear-step overflow against false convergence.
+- Fix in-place AIF transformation for negative delays and dispersion.
+- Add numerical input regressions and independent compartment ODE checks.
+- Resolve public development dependencies without a private index. Prepare
+  Trusted Publishing with release metadata/license gates and numerical wheel tests.
+- Add dependency notices, contribution guidance, citation metadata, scientific
+  conventions, validation scope, and release instructions.
+- Add AGPL-3.0-only licensing and SPDX notices to project source and build files.

kinepet-0.4.2/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "Please cite the version of KinePET used in your work, including its release number or commit identifier."
+type: software
+title: "KinePET: TAC-based fitting of dynamic PET two-tissue compartment models"
+authors:
+  - family-names: "Salomonsen"
+    given-names: "Christian"
+    orcid: "https://orcid.org/0009-0007-4958-4544"
+doi: 10.5281/zenodo.24132816
+date-released: 2026-11-11
+repository-code: "https://github.com/c-salomonsen/KinePET"
+url: "https://kinepet.salodev.no/"
+abstract: "A bounded nonlinear C++ solver with Python bindings for reversible and irreversible two-tissue compartment models, with linear least-squares initialization."
+keywords:
+  - PET
+  - kinetic modeling
+  - compartment models
+identifiers:
+  - type: doi
+    value: "10.5281/zenodo.24132816"
+    description: "The concept DOI for the collection containing all versions of the software."

kinepet-0.4.2/CMakeLists.txt

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: 2026 Christian Salomonsen
+# SPDX-License-Identifier: AGPL-3.0-only
+
+cmake_minimum_required(VERSION 3.20)
+
+project(tcm_fit LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
+endif()
+
+option(TCM_ENABLE_OPENMP "Enable OpenMP TAC parallelism when available" ON)
+option(TCM_ENABLE_PYTHON_BINDINGS "Build the nanobind Python extension" ON)
+
+add_library(
+  tcm_solver_core
+  src/model.cpp
+  src/parameters.cpp
+  src/aif.cpp
+  src/frame_weights.cpp
+  src/models/convolution.cpp
+  src/models/irreversible.cpp
+  src/models/reversible.cpp
+  src/lls.cpp
+  src/lls/regression.cpp
+  src/lls/irreversible.cpp
+  src/lls/reversible.cpp
+  src/solver.cpp
+  src/tac_batch.cpp
+  src/tcm_model.cpp
+)
+
+target_include_directories(tcm_solver_core PUBLIC src)
+set_target_properties(tcm_solver_core PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+if(MSVC)
+  target_compile_options(tcm_solver_core PRIVATE /W4 /O2)
+else()
+  target_compile_options(tcm_solver_core PRIVATE -Wall -Wextra -Wpedantic -O3)
+endif()
+
+if(TCM_ENABLE_OPENMP)
+  find_package(OpenMP QUIET)
+  if(OpenMP_CXX_FOUND)
+    target_link_libraries(tcm_solver_core PUBLIC OpenMP::OpenMP_CXX)
+    target_compile_definitions(tcm_solver_core PUBLIC TCM_HAS_OPENMP=1)
+  endif()
+endif()
+
+add_executable(
+  tcm_fit_tacs
+  src/npy.cpp
+  src/tac_fit_main.cpp
+)
+
+target_link_libraries(tcm_fit_tacs PRIVATE tcm_solver_core)
+target_include_directories(tcm_fit_tacs PRIVATE src)
+
+if(MSVC)
+  target_compile_options(tcm_fit_tacs PRIVATE /W4 /O2)
+else()
+  target_compile_options(tcm_fit_tacs PRIVATE -Wall -Wextra -Wpedantic -O3)
+endif()
+
+if(TCM_ENABLE_PYTHON_BINDINGS)
+  if (CMAKE_VERSION VERSION_LESS 3.18)
+    set(DEV_MODULE Development)
+  else()
+    set(DEV_MODULE Development.Module)
+  endif()
+
+  find_package(Python 3.11 COMPONENTS Interpreter ${DEV_MODULE} REQUIRED)
+
+  execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+    RESULT_VARIABLE TCM_NANOBIND_STATUS
+    OUTPUT_VARIABLE nanobind_ROOT
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+  )
+  if (NOT TCM_NANOBIND_STATUS EQUAL 0)
+    message(FATAL_ERROR "Could not locate nanobind. Install it in the active Python environment first.")
+  endif()
+
+  find_package(nanobind CONFIG REQUIRED)
+
+  nanobind_add_module(
+    _core
+    NB_STATIC
+    src/python_bindings.cpp
+  )
+
+  target_link_libraries(_core PRIVATE tcm_solver_core)
+  target_include_directories(_core PRIVATE src)
+
+  install(TARGETS _core LIBRARY DESTINATION kinepet)
+endif()
+
+include(CTest)
+if(BUILD_TESTING)
+  add_executable(test_core tests/cpp/test_core.cpp)
+  target_link_libraries(test_core PRIVATE tcm_solver_core)
+  add_test(NAME core_numerics COMMAND test_core "${CMAKE_CURRENT_SOURCE_DIR}/tests/fixtures/warm_starts.txt")
+endif()