torchsolve 0.0.1__tar.gz

torchsolve-0.0.1/.gitattributes

@@ -0,0 +1,11 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.npy binary
+*.npz binary
+*.mat binary
+*.h5 binary
+
+# Generated: keep them out of diffs and out of the language statistics.
+*.ipynb linguist-documentation=true

torchsolve-0.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Something behaves differently from what it says it does.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you expect, and what did you get instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Smallest reproduction
+      description: >
+        Code we can run. Prefer synthetic arrays over a data file; if the shape
+        of real data matters, give the shapes and dtypes.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: >
+        Output of `python -c "import torchsolve, sys, torch;
+        print(torchsolve.__version__, sys.version, torch.__version__,
+        torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'cpu')"`
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: device
+    attributes:
+      label: Where it happens
+      options: ["CPU only", "CUDA only", "Both"]
+    validations:
+      required: true

torchsolve-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or idea
+    url: https://github.com/FiRMLAB-Pisa/torchsolve/discussions
+    about: Ask about usage, or propose something before it is a bug report.
+  - name: Security vulnerability
+    url: https://github.com/FiRMLAB-Pisa/torchsolve/security/advisories/new
+    about: Report privately. Please do not open a public issue.

torchsolve-0.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Something this package should be able to do and cannot.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do, and where does it stop?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: >
+        A sketch of the API, if you have one. If there is a paper or another
+        implementation that does this, name it — that is usually the fastest
+        way to agree on what is wanted.
+    validations:
+      required: true
+
+  - type: textarea
+    id: layer
+    attributes:
+      label: Which layer this belongs to
+      description: >
+        This package is one of a family with a strict layering (`mrutils` at the
+        base, `deepmr` at the top). If the feature needs something from a
+        sibling package, say which — that usually means it belongs elsewhere.

torchsolve-0.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## What this changes
+
+<!-- One or two sentences. What behaviour is different afterwards? -->
+
+## Why
+
+<!-- The problem this solves. Link the issue if there is one. -->
+
+## How it was verified
+
+<!-- The commands you ran and what they said. Paste the output, don't
+     summarise it. "Tests pass" is not verification. -->
+
+```
+```
+
+## Checklist
+
+- [ ] `bash scripts/format_and_lint.sh` is clean
+- [ ] `pytest -q` passes, and new behaviour has a test whose name states the
+      invariant it protects
+- [ ] Anything numerical is exercised on CPU and CUDA, or the CUDA leg is
+      marked `@pytest.mark.cuda` and skips cleanly
+- [ ] No comment or docstring describes the code's history

torchsolve-0.0.1/.github/dependabot.yml

@@ -0,0 +1,39 @@
+version: 2
+updates:
+  # The Actions in .github/workflows pin third-party code that runs with
+  # repository credentials, so these are the updates worth having weekly.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    labels: ["dependencies", "ci"]
+    commit-message:
+      prefix: "ci"
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Grouped so the numerical stack arrives as one pull request that can be
+  # tested together rather than as several that each need a full suite run.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: ["dependencies", "python"]
+    commit-message:
+      prefix: "deps"
+    groups:
+      numerical:
+        patterns: ["numpy", "scipy", "torch*", "triton", "mri-nufft", "finufft", "cufinufft"]
+      mr-stack:
+        patterns: ["mrutils", "mrtoeplitz", "mrllr", "mrmotion", "mrdistortion", "torchsolve", "deepinv", "SimpleITK"]
+      dev-tooling:
+        patterns: ["pytest*", "coverage", "ruff", "pre-commit", "build", "sphinx*"]
+    ignore:
+      # Torch major bumps move the CUDA runtime under the whole family, so they
+      # are a deliberate decision rather than a routine update.
+      - dependency-name: "torch"
+        update-types: ["version-update:semver-major"]

torchsolve-0.0.1/.github/workflows/codeql.yml

@@ -0,0 +1,31 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  analyze:
+    name: Analyze Python
+    runs-on: ubuntu-latest
+    # Code scanning on a private repository needs GitHub Advanced Security,
+    # and uploading results without it is a hard error rather than a warning.
+    # The job stands down while the repository is private and starts working
+    # on its own once it is made public.
+    if: github.event.repository.visibility == 'public'
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          build-mode: none
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"

torchsolve-0.0.1/.github/workflows/style.yml

@@ -0,0 +1,40 @@
+name: Style
+
+# Runs the same script pre-commit runs, in --check mode: nothing is rewritten
+# and any file that would change fails the job.
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  format-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      # The linter only, taken from the same `dev` extra a contributor's
+      # pre-commit installs, so both apply one ruff. Installing the extra whole
+      # would download the runtime for a job that never imports it.
+      - name: Install ruff
+        run: |
+          python -m pip install --upgrade pip
+          python - <<'PY' > "$RUNNER_TEMP/lint-requirements.txt"
+          import tomllib
+
+          with open("pyproject.toml", "rb") as pyproject:
+              dev = tomllib.load(pyproject)["project"]["optional-dependencies"]["dev"]
+          print("\n".join(line for line in dev if line.startswith("ruff")))
+          PY
+          python -m pip install -r "$RUNNER_TEMP/lint-requirements.txt"
+
+      - name: Format and lint (check only)
+        run: bash scripts/format_and_lint.sh --check

torchsolve-0.0.1/.github/workflows/tags-release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+# Publishes a tagged version: sdist and wheel, then PyPI and a signed GitHub
+# release. The version comes from the tag via setuptools_scm.
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-to-pypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/torchsolve
+    permissions:
+      id-token: write # trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: [publish-to-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the release
+      id-token: write # sigstore
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: sigstore/gh-action-sigstore-python@v3.5.0
+        with:
+          inputs: |
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          gh release create '${{ github.ref_name }}' \
+            --repo '${{ github.repository }}' \
+            --title '${{ github.ref_name }}' \
+            --generate-notes
+          gh release upload '${{ github.ref_name }}' dist/** --repo '${{ github.repository }}'

torchsolve-0.0.1/.github/workflows/test-ci.yml

@@ -0,0 +1,75 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor and the ceiling of the supported band: an intermediate
+        # release that fails on neither is not a plausible failure.
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # setuptools_scm reads the tags
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          # Torch's default Linux wheel bundles the CUDA runtime: gigabytes the
+          # runner has no disk for and no device to use. Installing the CPU
+          # build first is what the rest resolves against.
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install .[dev]
+
+      - name: Run the tests
+        run: pytest -q --cov --cov-report=xml
+
+      - uses: codecov/codecov-action@v7
+        with:
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: FiRMLAB-Pisa/torchsolve
+
+  # Proves the claim the dependency layout rests on: with no CUDA extra and no
+  # device, nothing errors -- the GPU tests skip.
+  gpu-tests-skip-cleanly:
+    name: GPU tests skip without a GPU
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: |
+          python -m pip install --upgrade pip
+          # Torch's default Linux wheel bundles the CUDA runtime: gigabytes the
+          # runner has no disk for and no device to use. Installing the CPU
+          # build first is what the rest resolves against.
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install .[dev]
+      # Exit 5 is "nothing matched", which is also a clean outcome here: the
+      # point is that no CUDA-marked test errors on a machine without a device.
+      - run: |
+          status=0
+          pytest -q -rs -m cuda || status=$?
+          [ "$status" -eq 0 ] || [ "$status" -eq 5 ]

torchsolve-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+wheelhouse/
+*.egg-info/
+.eggs/
+
+.venv/
+venv/
+.env
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+.idea/
+.vscode/
+.DS_Store
+
+# Benchmark inputs are fetched, never committed.
+data/

torchsolve-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# The rules live in scripts/format_and_lint.sh, which the Style workflow also
+# runs (there with --check). One entry point means a commit cannot pass locally
+# and fail in CI on style.
+repos:
+  - repo: local
+    hooks:
+      - id: format-and-lint
+        name: format and lint
+        entry: bash scripts/format_and_lint.sh
+        language: system
+        pass_filenames: false
+        types_or: [python, markdown]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+      - id: check-symlinks
+      - id: destroyed-symlinks
+      - id: mixed-line-ending
+        args: [--fix=lf]

torchsolve-0.0.1/AGENTS.md

@@ -0,0 +1,72 @@
+# torchsolve — agent instructions
+
+<!--
+This file is the SOURCE. CLAUDE.md and GEMINI.md are generated from it by
+scripts/sync_agent_docs.sh, which pre-commit runs. Edit this file, never those.
+-->
+
+## What this package is
+
+Memory-lean iterative solvers for inverse problems in PyTorch: preconditioned CG with arbitrary regularisation, differentiable by implicit differentiation.
+
+It is one of a family of small, single-purpose MRI packages. The layering is
+strict: `mrutils` is the base; `torchsolve`, `mrtoeplitz`, `mrllr`, `mrmotion`
+and `mrdistortion` sit on it and never import each other; `deepmr` sits on all
+of them. If you find yourself wanting a sibling's code, the answer is either to
+move it down into `mrutils` or to move the caller up into `deepmr`.
+
+**deepinv is a `deepmr`-only dependency.** Everything below it is plain Torch
+with duck-typed operators (`A`, `A_adjoint`, `shape`). Do not import deepinv
+here unless this package is `deepmr`.
+
+## Build and test
+
+```bash
+pip install -e .[dev]
+bash scripts/format_and_lint.sh   # rewrites in place; --check to verify only
+pytest -q
+```
+
+Build and test steps are mandatory before reporting a change complete. Run them
+and report the exact output; do not assume success.
+
+## Tests
+
+pytest with plain functions and fixtures — never `unittest.TestCase`. A test
+name states the invariant it protects, so a failure reads as a sentence.
+
+Anything numerical that can run on CPU and CUDA is parametrised over both, and
+the CUDA leg skips when no device is present. A kernel-layout check that ran on
+CPU only has passed in this codebase while CUDA was 100% wrong.
+
+## Comments and docstrings
+
+Write for someone reading the code as it is now, who has no memory of any
+earlier version of it. **Never** write text whose subject is the history of the
+code. Banned in comments, docstrings and prose alike:
+
+- "used to", "was once", "no longer", "previously", "now that", "this replaces",
+  "the old X", "before the fix"
+- justifying the present shape by contrast with a shape that is gone
+- naming a bug that has been fixed, or the session that fixed it
+- restating what the code plainly says
+
+A docstring carries what a caller needs: one line of what, Parameters, Returns,
+Raises. A comment earns its place only by explaining a non-obvious algorithm or
+a choice a reader would otherwise undo — and even then, prefer a well-named
+function or a test whose name states the invariant, because those cannot go
+stale silently. When tempted to explain *why not the other way*, write a test.
+
+Stale comments are actively harmful. Deleting an outdated comment is always
+correct; rewriting one to describe the change is not.
+
+## Documentation style
+
+The audience is MR scientists. Write in the vocabulary of pulse sequences and
+physics, not of software architecture. Never justify a design by describing the
+design it replaced.
+
+Do not print a measured constant that is not guaranteed across releases or
+hardware. Name the symbol and where it comes from, and let the build supply the
+number. Benchmark tables in the README are regenerated by the benchmark script,
+not typed in.

torchsolve-0.0.1/CLAUDE.md

@@ -0,0 +1,74 @@
+<!-- Generated from AGENTS.md by scripts/sync_agent_docs.sh. Do not edit. -->
+
+# torchsolve — agent instructions
+
+<!--
+This file is the SOURCE. CLAUDE.md and GEMINI.md are generated from it by
+scripts/sync_agent_docs.sh, which pre-commit runs. Edit this file, never those.
+-->
+
+## What this package is
+
+Memory-lean iterative solvers for inverse problems in PyTorch: preconditioned CG with arbitrary regularisation, differentiable by implicit differentiation.
+
+It is one of a family of small, single-purpose MRI packages. The layering is
+strict: `mrutils` is the base; `torchsolve`, `mrtoeplitz`, `mrllr`, `mrmotion`
+and `mrdistortion` sit on it and never import each other; `deepmr` sits on all
+of them. If you find yourself wanting a sibling's code, the answer is either to
+move it down into `mrutils` or to move the caller up into `deepmr`.
+
+**deepinv is a `deepmr`-only dependency.** Everything below it is plain Torch
+with duck-typed operators (`A`, `A_adjoint`, `shape`). Do not import deepinv
+here unless this package is `deepmr`.
+
+## Build and test
+
+```bash
+pip install -e .[dev]
+bash scripts/format_and_lint.sh   # rewrites in place; --check to verify only
+pytest -q
+```
+
+Build and test steps are mandatory before reporting a change complete. Run them
+and report the exact output; do not assume success.
+
+## Tests
+
+pytest with plain functions and fixtures — never `unittest.TestCase`. A test
+name states the invariant it protects, so a failure reads as a sentence.
+
+Anything numerical that can run on CPU and CUDA is parametrised over both, and
+the CUDA leg skips when no device is present. A kernel-layout check that ran on
+CPU only has passed in this codebase while CUDA was 100% wrong.
+
+## Comments and docstrings
+
+Write for someone reading the code as it is now, who has no memory of any
+earlier version of it. **Never** write text whose subject is the history of the
+code. Banned in comments, docstrings and prose alike:
+
+- "used to", "was once", "no longer", "previously", "now that", "this replaces",
+  "the old X", "before the fix"
+- justifying the present shape by contrast with a shape that is gone
+- naming a bug that has been fixed, or the session that fixed it
+- restating what the code plainly says
+
+A docstring carries what a caller needs: one line of what, Parameters, Returns,
+Raises. A comment earns its place only by explaining a non-obvious algorithm or
+a choice a reader would otherwise undo — and even then, prefer a well-named
+function or a test whose name states the invariant, because those cannot go
+stale silently. When tempted to explain *why not the other way*, write a test.
+
+Stale comments are actively harmful. Deleting an outdated comment is always
+correct; rewriting one to describe the change is not.
+
+## Documentation style
+
+The audience is MR scientists. Write in the vocabulary of pulse sequences and
+physics, not of software architecture. Never justify a design by describing the
+design it replaced.
+
+Do not print a measured constant that is not guaranteed across releases or
+hardware. Name the symbol and where it comes from, and let the build supply the
+number. Benchmark tables in the README are regenerated by the benchmark script,
+not typed in.

torchsolve-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Code of conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience
+for everyone, regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Behaviour that helps:
+
+- showing empathy and kindness toward other people
+- respecting differing opinions, viewpoints, and experiences
+- giving and gracefully accepting constructive feedback
+- accepting responsibility, apologising to those affected by our mistakes,
+  and learning from the experience
+
+Behaviour that is not acceptable:
+
+- sexualised language or imagery, and sexual attention or advances of any kind
+- trolling, insulting or derogatory comments, and personal or political attacks
+- public or private harassment
+- publishing others' private information, such as a physical or email address,
+  without their explicit permission
+
+## Enforcement
+
+Report abusive, harassing, or otherwise unacceptable behaviour to
+matteo.cencini@gmail.com. All complaints will be reviewed and investigated
+promptly and fairly. The maintainers will respect the privacy and security of
+the reporter of any incident.
+
+Maintainers who do not follow or enforce this code in good faith may face
+temporary or permanent repercussions as determined by other maintainers.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

torchsolve-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to torchsolve
+
+## Getting set up
+
+```bash
+git clone https://github.com/FiRMLAB-Pisa/torchsolve.git
+cd torchsolve
+python -m venv .venv && source .venv/bin/activate
+pip install -e .[dev]
+pre-commit install
+```
+
+## Before you open a pull request
+
+```bash
+bash scripts/format_and_lint.sh   # rewrites in place
+pytest -q
+```
+
+CI runs the same script with `--check`, so anything that passes locally passes
+there. If `pre-commit` rewrites a file, stage it and commit again.
+
+## What the tests expect
+
+- pytest with plain functions and fixtures. No `unittest.TestCase` subclasses.
+- A test name states the invariant it protects, so a failure reads as a
+  sentence: `test_a_double_precision_basis_does_not_reach_the_kernel`.
+- Anything that can run on both CPU and CUDA is parametrised over both, and
+  the CUDA leg skips cleanly when no device is present. A numerical check that
+  only ever ran on CPU has, in this codebase's history, passed while the CUDA
+  path was completely wrong.
+
+## Comments and documentation
+
+Write for someone reading the code as it is now, with no memory of an earlier
+version. Do not write text whose subject is the history of the code — no "used
+to", "previously", "this replaces", no naming a bug that is fixed. A comment
+earns its place by explaining a non-obvious algorithm or a choice a reader
+would otherwise undo; prefer a well-named function, or a test whose name states
+the invariant, because those cannot go stale silently.
+
+## Releasing
+
+Versions come from git tags via `setuptools_scm`. Push a tag matching
+`v[0-9]+.[0-9]+.[0-9]+` and the release workflow builds, signs and publishes it.