pypulseqpp 0.0.1__tar.gz

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

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

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

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

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

pypulseqpp-0.0.1/.github/dependabot.yml

@@ -0,0 +1,36 @@
+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: ["*"]
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: ["dependencies", "python"]
+    commit-message:
+      prefix: "deps"
+    groups:
+      # The reference implementation moves the parity fixtures with it, so its
+      # bumps arrive alone and get a full run of their own.
+      reference:
+        patterns: ["pypulseq"]
+      numerical:
+        patterns: ["numpy"]
+      build:
+        patterns: ["scikit-build-core", "pybind11", "setuptools_scm"]
+      dev-tooling:
+        patterns: ["pytest*", "coverage", "ruff", "pre-commit", "build"]

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

@@ -0,0 +1,33 @@
+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
+        with:
+          submodules: recursive # the solver in external/ is compiled in
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          build-mode: none
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"

pypulseqpp-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,131 @@
+name: Docs
+
+# Builds the documentation and publishes it to GitHub Pages, which serves the
+# gh-pages branch. The site holds one directory per version: main publishes
+# `latest`, a release tag publishes `vX.Y.Z` and copies it to `stable`, and the
+# root redirects to whichever of the two a reader should see. Pull requests
+# build without publishing, so a documentation warning fails review rather than
+# the site.
+#
+# The branch is the site's archive. GitHub Pages can be deployed from an
+# artifact instead, but a deployment replaces the whole site, so publishing one
+# version would drop the others.
+
+on:
+  push:
+    branches: [main]
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Every publish commits to the same branch, so main, the tags and a manual run
+# share one group and wait for each other rather than racing to push. A pull
+# request publishes nothing and gets a group of its own.
+concurrency:
+  group: docs-${{ github.event.pull_request.number || 'publish' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # the publish step pushes the built site to gh-pages
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive # the solver in external/ is compiled in
+          fetch-depth: 0 # setuptools_scm reads the tags
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Name this version
+        id: version
+        # A release is built as `stable`, the URL a reader should land on, and
+        # archived under its tag as well; the canonical link in both copies
+        # points at `stable`, so a search result leads to the current release
+        # rather than to whichever version was indexed first.
+        run: |
+          if [ "$GITHUB_REF_TYPE" = tag ]; then
+            echo "dir=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
+            echo "canonical=stable" >> "$GITHUB_OUTPUT"
+          else
+            echo "dir=latest" >> "$GITHUB_OUTPUT"
+            echo "canonical=latest" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install
+        # Into the CMake build directory build_docs.sh uses, so the build it
+        # makes for Sphinx reuses these objects rather than compiling twice.
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -Cbuild-dir="$PWD/docs/build/cmake" '.[doc]'
+
+      - name: Build
+        env:
+          PYPULSEQPP_DOCS_VERSION: ${{ steps.version.outputs.canonical }}
+        run: bash scripts/build_docs.sh
+
+      - name: Check that the site is only the site
+        # Sphinx caches parsed documents in the output directory unless given
+        # `-d`, and the cache is far larger than the pages. Publishing commits
+        # whatever is there to a branch that is never pruned, so a build that
+        # leaves it behind has to fail here rather than on main.
+        run: |
+          if [ -e docs/build/html/.doctrees ]; then
+            echo "::error::The doctree cache is inside the built site and would be published." >&2
+            exit 1
+          fi
+
+      - name: Publish
+        if: github.event_name != 'pull_request'
+        env:
+          DIR: ${{ steps.version.outputs.dir }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          site="$RUNNER_TEMP/pages"
+          remote="https://x-access-token:$GH_TOKEN@github.com/$GITHUB_REPOSITORY"
+          # The branch does not exist before the first publish.
+          if ! git clone --depth 1 --branch gh-pages "$remote" "$site"; then
+            git init -b gh-pages "$site"
+            git -C "$site" remote add origin "$remote"
+          fi
+
+          # Only this version's directory is replaced; the others stay as the
+          # release that built them left them.
+          rm -rf "${site:?}/$DIR"
+          cp -r docs/build/html "$site/$DIR"
+
+          # `stable` is the newest release, so a patch tagged after a later
+          # release archives itself without taking `stable` backwards.
+          if [ "$GITHUB_REF_TYPE" = tag ]; then
+            newest=$(ls "$site" | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+            if [ "$newest" = "$DIR" ]; then
+              rm -rf "$site/stable"
+              cp -r "$site/$DIR" "$site/stable"
+            else
+              echo "$newest is newer than $DIR; leaving stable alone."
+            fi
+          fi
+
+          # The root goes to the current release, or to main's pages until
+          # there is one.
+          target=latest
+          [ -d "$site/stable" ] && target=stable
+          printf '<!doctype html>\n<meta http-equiv="refresh" content="0; url=%s/">\n' \
+            "$target" > "$site/index.html"
+          # Pages runs the branch through Jekyll unless told not to, and Jekyll
+          # drops the _static and _sources directories Sphinx writes.
+          touch "$site/.nojekyll"
+
+          git -C "$site" add -A
+          git -C "$site" -c user.name='github-actions[bot]' \
+            -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
+            commit -m "Documentation for $DIR from $GITHUB_SHA" \
+            || { echo "No documentation change to publish."; exit 0; }
+          git -C "$site" push origin gh-pages

pypulseqpp-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:
+  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
+        with:
+          submodules: recursive # the solver in external/ is compiled in
+      - 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

pypulseqpp-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-*"
+
+  publish-to-pypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pypulseqpp
+    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 }}'

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

@@ -0,0 +1,74 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Every platform a wheel ships for: the compiled core is the package,
+        # so a platform that is not tested is not supported.
+        os: [ubuntu-latest, macos-14, windows-latest]
+        # 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:
+          submodules: recursive # the solver in external/ is compiled in
+          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
+          python -m pip install .[dev] -r tests/requirements.txt
+
+      - name: Run the tests
+        run: pytest -q --cov --cov-report=xml
+
+      - uses: codecov/codecov-action@v7
+        if: matrix.os == 'ubuntu-latest'
+        with:
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: pulserver/pypulseqpp
+
+  sanitize:
+    name: sanitizers
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive # the solver in external/ is compiled in
+
+      # A read past the end of an array is not a wrong answer, it is whatever
+      # was there -- so the tests above catch it only when the memory it lands
+      # on differs enough to change a number. One such bug reported the same
+      # waveform on five of those six jobs and a different one on the sixth,
+      # and gave two different answers within a single process. This is the
+      # job that would have named it on the first run.
+      - name: Build the core with the sanitizers on
+        run: |
+          g++ -std=c++17 -g -O1 \
+            -fsanitize=address,undefined -fno-sanitize-recover=all \
+            -fno-omit-frame-pointer \
+            -I src/cpp -o sanitize \
+            tests/cpp/sanitize.cpp src/cpp/pulseq/*.cpp
+
+      - name: Read, write and expand every sequence in the corpus
+        run: ./sanitize tests/seq/*.seq

pypulseqpp-0.0.1/.github/workflows/viewer-release.yml

@@ -0,0 +1,30 @@
+name: Viewer release
+
+# Publishes pypulseqpp-seqeyes, the GPL viewer package in viewer/, from a tag
+# of its own: it is versioned after the SeqEyes release it builds, not after
+# pypulseqpp.
+
+on:
+  push:
+    tags:
+      - "viewer-v[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  build:
+    uses: ./.github/workflows/viewer-wheels.yml
+
+  publish-to-pypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-viewer
+      url: https://pypi.org/p/pypulseqpp-seqeyes
+    permissions:
+      id-token: write # trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: "{viewer-wheels-*,viewer-sdist}"
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

pypulseqpp-0.0.1/.github/workflows/viewer-wheels.yml

@@ -0,0 +1,104 @@
+name: Viewer wheels
+
+# SeqEyes, built from viewer/ as the pypulseqpp-seqeyes wheels that
+# `pip install 'pypulseqpp[plot]'` installs. Reusable: the viewer release
+# publishes what this builds, and any change under viewer/ runs it.
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  pull_request:
+    paths: ["viewer/**", ".gitmodules", ".github/workflows/viewer-*.yml"]
+  push:
+    branches: [main]
+    paths: ["viewer/**", ".gitmodules", ".github/workflows/viewer-*.yml"]
+
+jobs:
+  wheels:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # The platforms pypulseqpp ships for. Each build job also installs the
+        # wheel beside PySide6 and draws a sequence with it: see
+        # viewer/tests/smoke.py and [tool.cibuildwheel] in viewer/pyproject.toml.
+        os: [ubuntu-latest, macos-14, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive # SeqEyes is the submodule in viewer/seqeyes
+
+      - uses: pypa/cibuildwheel@v4.2.0
+        with:
+          package-dir: viewer
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: viewer-wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  plot:
+    # pypulseqpp's own plot tests, against the wheel just built: the test that
+    # opens SeqEyes skips when there is none, so here it is made to run.
+    name: plot / ${{ matrix.os }}
+    needs: wheels
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+    env:
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+          fetch-depth: 0 # setuptools_scm reads the tags
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: viewer-wheels-${{ matrix.os }}
+          path: viewer-wheel
+
+      # PySide6's Qt draws with the system's display libraries, which every
+      # desktop has and the runner image does not all of. These are what
+      # drawing offscreen needs; viewer/README.md lists them too.
+      - name: System libraries
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libegl1 libgl1 libx11-6 libdbus-1-3 \
+            libfontconfig1 libfreetype6 libglib2.0-0 libxkbcommon0
+
+      - name: Install
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]" -r tests/requirements.txt viewer-wheel/*.whl
+
+      - name: Test
+        run: python -m pytest tests/test_plot.py -ra
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist viewer --outdir dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: viewer-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error