mariepy 0.0.1__tar.gz

mariepy-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

mariepy-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 mariepy, sys, torch;
+        print(mariepy.__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

mariepy-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/pulserver/mariepy/discussions
+    about: Ask about usage, or propose something before it is a bug report.
+  - name: Security vulnerability
+    url: https://github.com/pulserver/mariepy/security/advisories/new
+    about: Report privately. Please do not open a public issue.

mariepy-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.

mariepy-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

mariepy-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"]

mariepy-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"

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

@@ -0,0 +1,42 @@
+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:
+  # A branch is tested once, through its pull request.
+  push:
+    branches: [main]
+  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

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

@@ -0,0 +1,58 @@
+name: Release
+
+# Publishes a tagged version: the wheels and sdist from the reusable Wheels
+# workflow, 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:
+    uses: ./.github/workflows/wheels.yml
+    with:
+      cibw-build: "cp310-* cp311-* cp312-* cp313-* cp314-*"
+
+  publish-to-pypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mariepy
+    permissions:
+      id-token: write # trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: "{wheels-*,sdist}"
+          path: dist
+          merge-multiple: true
+      - 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:
+          pattern: "{wheels-*,sdist}"
+          path: dist
+          merge-multiple: true
+      - 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 }}'

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

@@ -0,0 +1,56 @@
+name: Tests
+
+on:
+  # A branch is tested once, through its pull request.
+  push:
+    branches: [main]
+  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.14"]
+    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
+
+      # torch's CPU build: PyPI's carries the CUDA libraries, gigabytes this
+      # runner has no device for.
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install .[dev]
+
+      # No device here, so this run is also the check that every CUDA-marked
+      # test skips cleanly without one: -rs lists the skips. One worker per
+      # core, each held to one thread so the workers do not contend.
+      - name: Run the tests
+        env:
+          OMP_NUM_THREADS: 1
+          OPENBLAS_NUM_THREADS: 1
+          MKL_NUM_THREADS: 1
+        run: pytest -q -rs -n auto --cov --cov-report=xml
+
+      - uses: codecov/codecov-action@v7
+        with:
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: pulserver/mariepy

mariepy-0.0.1/.github/workflows/wheels.yml

@@ -0,0 +1,66 @@
+name: Wheels
+
+# Reusable: the release workflow calls this so what is published was built by
+# the same job pull requests exercise.
+
+on:
+  workflow_call:
+    inputs:
+      cibw-build:
+        description: Interpreters to build, as a CIBW_BUILD pattern.
+        type: string
+        required: true
+  workflow_dispatch:
+    inputs:
+      cibw-build:
+        description: Interpreters to build, as a CIBW_BUILD pattern.
+        type: string
+        default: "cp310-* cp311-* cp312-* cp313-* cp314-*"
+
+jobs:
+  wheels:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Linux and macOS only. The kernels' SIMD paths are guarded on GCC and
+        # Clang, so a Windows build would take the scalar path; add it when
+        # someone needs it rather than paying for it on every release.
+        os: [ubuntu-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # setuptools_scm reads the tags
+
+      - uses: pypa/cibuildwheel@v4.3.4
+        env:
+          CIBW_BUILD: ${{ inputs.cibw-build }}
+          CIBW_SKIP: "*-musllinux_*"
+          CIBW_ARCHS_LINUX: x86_64
+          CIBW_ARCHS_MACOS: arm64
+          CIBW_TEST_COMMAND: "python -c \"import mariepy; print(mariepy.__version__)\""
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  sdist:
+    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 --sdist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error

mariepy-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/

mariepy-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]

mariepy-0.0.1/AGENTS.md

@@ -0,0 +1,72 @@
+# mariepy — 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
+
+Electromagnetic simulation of MRI transmit coils and virtual observation points
+(VOPs) for SAR, ported from MARIE 3.0 (<https://github.com/cloudmrhub/marie-tools>,
+MIT).
+
+`PLAN.md` is the design brief: scope, the VOP file contract, the port's
+milestones, validation, constraints and later stages. Read it before starting
+work. When a decision it records changes, change `PLAN.md` in the same pull
+request.
+
+mariepy stands alone: it depends on torch and numpy, not on other MRI packages.
+Its one external contract is the VOP file that pypulseqpp reads.
+
+## 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.

mariepy-0.0.1/CLAUDE.md

@@ -0,0 +1,74 @@
+<!-- Generated from AGENTS.md by scripts/sync_agent_docs.sh. Do not edit. -->
+
+# mariepy — 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
+
+Electromagnetic simulation of MRI transmit coils and virtual observation points
+(VOPs) for SAR, ported from MARIE 3.0 (<https://github.com/cloudmrhub/marie-tools>,
+MIT).
+
+`PLAN.md` is the design brief: scope, the VOP file contract, the port's
+milestones, validation, constraints and later stages. Read it before starting
+work. When a decision it records changes, change `PLAN.md` in the same pull
+request.
+
+mariepy stands alone: it depends on torch and numpy, not on other MRI packages.
+Its one external contract is the VOP file that pypulseqpp reads.
+
+## 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.