blochsim 0.0.9__tar.gz

blochsim-0.0.9/.gitattributes

@@ -0,0 +1,42 @@
+# Normalise line endings in the repository; check out native on Windows.
+* text=auto
+
+# Text, whatever the platform.
+*.py       text diff=python
+*.pyi      text diff=python
+*.cpp      text diff=cpp
+*.hpp      text diff=cpp
+*.md       text
+*.rst      text
+*.txt      text
+*.toml     text
+*.cfg      text
+*.yml      text
+*.yaml     text
+*.json     text
+*.ipynb    text
+CMakeLists.txt text
+*.cmake    text
+
+# Shell scripts must keep LF even when checked out on Windows, so a WSL or
+# Git Bash run of scripts/ does not fail on carriage returns.
+*.sh       text eol=lf
+
+# Binary, never diffed or line-ending converted.
+*.png      binary
+*.jpg      binary
+*.jpeg     binary
+*.gif      binary
+*.svg      binary
+*.pdf      binary
+*.npy      binary
+*.npz      binary
+*.so       binary
+*.pyd      binary
+*.dylib    binary
+*.dll      binary
+
+# What the repository's language bar reports: the package, not the pages that
+# describe it. Affects GitHub's statistics only, nothing that is built.
+docs/**        linguist-documentation
+examples/**    linguist-documentation

blochsim-0.0.9/.github/DISCUSSION_TEMPLATE/ideas.yml

@@ -0,0 +1,19 @@
+labels: ["idea"]
+body:
+  - type: textarea
+    id: idea
+    attributes:
+      label: The idea
+      description: |
+        A model, an interface or a direction you think BlochSim should take,
+        before it is concrete enough to be a feature request.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Where it comes from
+      description: |
+        The experiment that prompted it, and any paper or implementation that
+        already does something like it.

blochsim-0.0.9/.github/DISCUSSION_TEMPLATE/q-a.yml

@@ -0,0 +1,24 @@
+labels: ["question"]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: What you are trying to do
+      description: |
+        The sequence or the analysis, and where you got stuck. If a signal
+        looks wrong, say what you expected it to look like and why.
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: What you have so far
+      description: The call you are making, if there is one.
+      render: python
+
+  - type: input
+    id: version
+    attributes:
+      label: BlochSim version
+      placeholder: "0.4.1, or the commit you are on"

blochsim-0.0.9/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,69 @@
+name: Bug report
+description: A simulation that raises, hangs, or returns a signal you can show is wrong.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Questions about how to use BlochSim, and results you are unsure about,
+        belong in [Discussions](https://github.com/pulserver/blochsim/discussions).
+        This form is for behaviour you can pin down.
+
+  - type: textarea
+    id: what-happens
+    attributes:
+      label: What happens
+      description: What you ran, and what it did instead of what you expected.
+      placeholder: |
+        A 48-echo FSE train at 60 degree refocusing returns NaN from the
+        second echo on, on CPU, for T2 = 0.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Code that reproduces it
+      description: |
+        The shortest script that shows the problem, with the tissue and the
+        protocol it was run on. Paste it whole rather than describing it -- a
+        sequence is enough numbers that a description leaves the run ambiguous.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or output
+      description: The full traceback, or the numbers that are wrong beside the ones you expected.
+      render: shell
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        Paste the output of
+
+        ```sh
+        python -c "from importlib.metadata import version; print('blochsim', version('blochsim'))"
+        python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.get_device_name() if torch.cuda.is_available() else 'cpu')"
+        python -VV
+        ```
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: where
+    attributes:
+      label: Where it runs
+      description: Which backends you have seen it on.
+      multiple: true
+      options:
+        - CPU
+        - CUDA (Triton kernels)
+        - Both
+    validations:
+      required: true

blochsim-0.0.9/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question, or a result you are unsure about
+    url: https://github.com/pulserver/blochsim/discussions
+    about: Ask how to model a sequence, or whether a signal you got is expected.
+  - name: Security report
+    url: https://github.com/pulserver/blochsim/security/policy
+    about: Report a vulnerability privately rather than in a public issue.

blochsim-0.0.9/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature request
+description: A sequence, a physical effect, an estimator or an interface BlochSim should carry.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What you are trying to simulate or fit
+      description: |
+        The acquisition or the analysis, in the vocabulary of the experiment
+        rather than of the API. What the sequence plays, which properties you
+        need out, and what stops you today.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you would like BlochSim to do
+      description: |
+        If you already know the shape of it -- an operator, a tissue property,
+        a keyword on an existing simulator -- sketch the call you would like
+        to write.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: reference
+    attributes:
+      label: Reference
+      description: |
+        The paper the model comes from, if there is one, and the figure or
+        equation the implementation would have to reproduce.
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would be willing to open a pull request for this.

blochsim-0.0.9/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## What this changes
+
+<!-- What the code does now that it did not do before, in one or two
+     sentences. Link the issue or discussion it comes from, if there is one. -->
+
+## How it was checked
+
+<!-- The command you ran and what it printed: a test that fails before the
+     change and passes after it, an analytic case the new physics reproduces,
+     a benchmark. "Tests pass" on its own does not say which ones. -->
+
+```
+pytest tests/
+```
+
+## Checklist
+
+- [ ] `pytest tests/` passes locally, and a new test covers what changed.
+- [ ] `pre-commit run --all-files` is clean -- the `ruff format` and
+      `ruff check` that CI's Lint job runs.
+- [ ] Public functions and classes carry a numpydoc docstring: one line of
+      what, then Parameters, Returns, Raises.
+- [ ] Comments and docstrings describe the code as it is now -- no
+      "previously", no "this replaces", no naming of a bug that is fixed.
+- [ ] A change to what the kernels compute is in both of them, and arrives
+      with a test that pins it against something outside BlochSim.
+- [ ] The documentation is updated where the change is visible to a caller,
+      and `bash scripts/build_docs.sh` still builds.

blochsim-0.0.9/.github/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are applied to the latest release on PyPI and to `main`.
+Older releases are not patched.
+
+## Reporting a vulnerability
+
+Report privately, not as a public issue:
+
+- open a draft advisory through
+  [Security -> Report a vulnerability](https://github.com/pulserver/blochsim/security/advisories/new),
+  which is the preferred route; or
+- email **matteo.cencini@gmail.com** if you cannot use GitHub.
+
+Please include what an attacker can do, the version and platform you saw it
+on, and a minimal reproduction. You can expect an acknowledgement within a
+week, an assessment within two, and credit in the advisory unless you ask
+otherwise. Please give us a chance to release a fix before disclosing
+publicly.
+
+## Scope
+
+BlochSim executes the code you give it: a sequence layout, a cost function and
+a signal model are all Python that runs in your process, so a malicious
+*script* is out of scope in the same way it is for NumPy or PyTorch.
+
+In scope is anything that turns *data* into execution or into memory
+corruption -- a sequence description, a pulse waveform, a phantom or a
+dictionary read from a file, or values passed to the simulator, reaching the
+C++ and Triton kernels. Those kernels index raw pointers, so an out-of-bounds
+read or write reachable from ordinary arguments is a vulnerability and not
+merely a bug.
+
+## Not a vulnerability
+
+A simulation that returns wrong physics, diverges, or raises is a
+[bug report](https://github.com/pulserver/blochsim/issues/new/choose).

blochsim-0.0.9/.github/copilot-instructions.md

@@ -0,0 +1 @@
+../CLAUDE.md

blochsim-0.0.9/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  # The actions the workflows pin. A pinned action that is never updated is a
+  # pinned action that stops working.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "ci"
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # The dependency floors in pyproject.toml, and the toolchain the extras pull.
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "deps"
+    groups:
+      python:
+        patterns: ["*"]
+        update-types: [minor, patch]

blochsim-0.0.9/.github/skills/add-a-sequence/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: add-a-sequence
+description: Write a new simulator, signal model, or sequence operator in BlochSim. Use when asked to add a sequence, a readout module, a physical effect, or a tissue property.
+---
+
+# Add a sequence to BlochSim
+
+**There is one base class, `Simulator`, written in one of two ways.** Nothing
+downstream ever asks which way.
+
+## A signal that has to be played
+
+Implement `layout()`: a train of pulses whose magnetization state carries from
+one event to the next, which is almost every quantitative sequence.
+
+1. Set `model` to a `SpinPhysics` — what a voxel holds, so which tissue
+   properties are exposed and which terms the kernels carry, and what each kind
+   of event does to it.
+2. Implement `layout()`, returning the operators of one repetition in the order
+   they are played.
+
+The extended phase-graph engine, the derivative, the device placement and the
+memory policy all follow, and none of them is yours to write. The two pieces
+are separate so either can change without the other: giving an MRF timing a
+selective excitation, or a refocused train a readout that spoils rather than
+winds, is an assignment rather than a new model.
+
+`EventOperators` names the operator each kind of event plays. Four are supplied
+and a `SpinPhysics` picks one: `SPOILED` and `UNBALANCED` for gradient-spoiled
+and gradient-echo trains, `BALANCED` for a fully refocused steady state,
+`REFOCUSED` for a spin-echo train.
+
+## A signal with a closed form
+
+Implement `evaluate()` instead — a mono-exponential decay, an
+inversion-recovery curve, an Ernst steady state. There is nothing to play and
+no state to carry, so there is no `layout` and the `SpinPhysics` carries only
+the property declaration. `SPGRSimulator` is written this way; `MP2RAGESimulator`
+carries both, the closed form a lookup table is built from and the layout a
+description arriving from a scanner is compared against.
+
+## An operator of your own
+
+An operator is a Python function that returns events. `Excitation`,
+`Refocusing`, `Readout`, `Dephase`, `Spoil`, `Delay` and the readout modules
+built from them speak exactly the vocabulary the kernels implement, so a module
+you write — a T2 preparation, an MT saturation, a shaped pulse — reaches the
+fused kernels with no change to them.
+
+An event is a wait, an RF pulse, or an ADC. **Gradients are not events**: each
+event declares its own role (`CRUSH_BEFORE`, `CRUSH_AFTER`, `SHIFT_AFTER`,
+`SPOIL_AFTER`), because a Pulseq file has no gradient *use* field and a crusher
+cannot be told from a phase encode by looking at waveforms. What an operator
+cannot say is how much a gradient dephases: a description carries one crusher
+moment for the whole sequence, and dephasing is quantized to whole
+configuration orders.
+
+## Adding a physical effect
+
+A tissue property has an **identity** — the value at which it has no effect —
+and a run reads which properties were passed to decide which terms the kernel
+evaluates. Adding an effect is one line in a model's property declaration, plus
+the term itself in **both** kernels.
+
+The shared parameter ABI is `src/blochsim/sequence/_parameters.py`, read by the
+Python dispatch, the C++ extension and the Triton kernels. A parameter added
+there is added in all three or in none.
+
+## What the change has to arrive with
+
+A test that pins the new physics against something **outside** BlochSim: a
+closed form, a published figure, or an isochromat summation written out in the
+test itself. Comparing BlochSim to BlochSim proves the two agree, which was
+never in doubt. Put it in `tests/epg/` and state the invariant in the module
+docstring.
+
+Units are public at the edges and internal underneath: a caller writes
+milliseconds, degrees and Hz; a description timestamps in microseconds and
+carries radians. Convert at the boundary and name the unit in the identifier.

blochsim-0.0.9/.github/skills/build-and-test/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: build-and-test
+description: Compile the C++ kernels and run the BlochSim suite, including the Triton paths on a machine with no GPU. Use when asked to build, install, test, or reproduce a failure in blochsim.
+---
+
+# Build and test BlochSim
+
+## Install
+
+```sh
+pip install -e ".[dev]" ; echo "exit: $?"
+```
+
+`dev` is `test` + `doc` + `examples` plus ruff, mypy and pre-commit. For a test
+run alone, `pip install -e ".[test]"` is enough and much smaller.
+
+An editable install puts the Python sources on the path, so an edit under
+`src/blochsim` takes effect on the next import. The two C++ extensions are
+compiled artifacts and do not: re-run the install after editing any `.cpp`.
+
+**Read the exit status, not the output.** A failed compile leaves the
+previously built `.so` importable, so the suite runs green against a kernel
+that no longer corresponds to the source. Confirm the extension is the one you
+just built:
+
+```sh
+python -c "import blochsim._epg_cpu as k; print(k.__file__)"
+```
+
+## Test
+
+```sh
+pytest tests/                          # everything, with coverage
+pytest tests/epg/                      # one area
+pytest tests/epg/test_shift.py -k inversion
+pytest tests/ -n auto                  # across cores
+```
+
+`tests/` mirrors the source. `epg/` pins the state machine operator by operator
+against closed forms — the shift, the RF rotation, relaxation, diffusion, flow,
+spoiling, the two-pool and three-pool longitudinal steps — while `sequence/`,
+`model/`, `estimators/`, `recon/` and `optim/` cover the layers above.
+
+## The Triton paths, without a GPU
+
+The tests carrying the `interpreted` marker are deselected by `addopts`. They
+run a Triton kernel through Triton's CPU interpreter — no card, no compile,
+about a minute each — and are how the GPU plumbing is verified anywhere:
+
+```sh
+pytest tests/ -m interpreted
+TRITON_INTERPRET=1 python your_script.py     # the same trick, by hand
+```
+
+Triton has no wheel for macOS or Windows. On those platforms the default
+deselection is not an optimisation, it is the only thing that runs.
+
+## Before you time anything
+
+Kernel compiles dominate a cold GPU run, not the arithmetic. A suite that takes
+minutes on a card is mostly Triton compiling one specialization per feature
+combination it meets; the second run of the same suite is a different number
+entirely. Run the whole suite at natural boundaries rather than after every
+edit.
+
+The cache keys on the *source* of `_epg_triton.py`, not on what it means, so a
+formatting pass or a deleted dead local costs the same full recompile as a new
+`tl.constexpr`. If the suite suddenly takes an hour where it took minutes,
+check whether that file changed before looking for a performance regression.
+
+## Style
+
+```sh
+pre-commit install              # once per clone; nothing runs on commit until you do
+pre-commit run --all-files      # the whole tree, which is what CI's Lint job runs
+pre-commit run --files path/to/one.py
+```
+
+`ruff format`, then `ruff check --fix`, plus whitespace and file hygiene. There
+is no black and no isort, and `.pre-commit-config.yaml` pins the ruff version
+so a local run and CI agree on it.
+
+A hook that rewrites a file fails the commit and leaves the fix in the working
+tree: read it, `git add` it, commit again.
+
+To get a commit through without them — a work-in-progress commit, or a merge
+you did not write:
+
+```sh
+SKIP=ruff-check git commit -m "..."     # one hook
+git commit --no-verify -m "..."         # all of them
+```
+
+CI runs the same hooks over the whole tree on every branch, so either one
+defers the failure rather than avoiding it.

blochsim-0.0.9/.github/skills/build-the-docs/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: build-the-docs
+description: Build the BlochSim documentation, add a figure to an explanation page, or add a gallery example. Use when asked about docs, Sphinx, the gallery, MyST, or Read the Docs for blochsim.
+---
+
+# Build the BlochSim documentation
+
+```sh
+bash scripts/build_docs.sh              # incremental
+bash scripts/build_docs.sh --clean      # re-execute every example
+PYTHON_BIN=~/envs/blochsim/bin/python bash scripts/build_docs.sh
+python -m http.server --directory docs/build/html 8000
+```
+
+The script checks that the interpreter it is given can import BlochSim and the
+documentation extensions, then builds into `docs/build/html`. Two things make
+it slower than a plain Sphinx run and are the point of it: **sphinx-gallery
+executes the examples**, and **the explanation pages' figures are re-rendered**
+by `docs/explanation_figures.py` with the BlochSim in your working tree.
+
+An example is executed when the interpreter can import everything it imports:
+an environment with the `dev` or `examples` extra runs the whole gallery, one
+with `doc` alone runs what needs nothing but BlochSim. A page already carrying
+output executed from the source as it stands is reused rather than re-run, and
+the build names each example it did not run and where its output came from. To
+build the pages without running any of them, pass `-D plot_gallery=0`.
+
+## Where the published pages are built
+
+`.github/workflows/docs.yml` builds them, and GitHub Pages serves them from
+the `gh-pages` branch at <https://pulserver.github.io/blochsim/>.
+
+Its **HTML** job runs on every branch and pull request with the `doc` extra:
+every page is written and the examples needing nothing but BlochSim are
+executed, in a few minutes, and the tree is uploaded as an artifact to read.
+
+Its **Site** job runs on `main`, on a `v*.*.*` tag and on demand. It installs
+the `examples` extra, so every notebook is executed, and hands what
+Sphinx wrote to `scripts/publish_docs.py`, which places it in the site:
+
+    site/latest/     the development branch
+    site/v1.2.3/     one directory per release, kept as it was published
+    site/index.html  a page sending a reader to the newest release
+    site/versions.json  the list the switcher in the sidebar reads
+
+`BLOCHSIM_DOCS_VERSION` is what a build calls itself; it names the directory,
+the switcher's mark and the Binder path prefix, and defaults to `latest`.
+
+## Markdown, and the two places it is not
+
+Pages are **MyST Markdown**. Two file sets stay reStructuredText because the
+tooling requires it — converting either breaks the build:
+
+- `examples/**/README.rst` — sphinx-gallery concatenates a gallery header
+  verbatim into a generated `index.rst`.
+- `docs/_templates/autosummary/*.rst` — `sphinx.ext.autosummary` writes stubs
+  with a hardcoded `.rst` suffix and finds its directives by regex over raw
+  source lines.
+
+That regex is also why the API pages hold `autosummary` and `currentmodule`
+inside `` ```{eval-rst} `` blocks rather than in MyST directive syntax: written
+as `` ```{autosummary} `` the stub generator never sees them and every linked
+page 404s.
+
+## Add a figure to an explanation page
+
+Write a function in `docs/explanation_figures.py` that returns a Matplotlib
+figure, register it in the `FIGURES` mapping at the bottom, and reference the
+file it writes:
+
+````markdown
+```{figure} /generated/figures/your_figure.png
+:width: 100%
+:alt: One sentence a screen reader can use.
+
+The caption, which is where the reader is told what to look at.
+```
+````
+
+Figures are simulated at build time rather than checked in, so one cannot
+outlive the behaviour it shows.
+
+## Add a gallery example
+
+Drop a script into the right `examples/` section. The numeric prefix orders it
+within the section, and the module docstring — an reStructuredText title block
+— becomes the page's introduction. What it imports decides where it is
+executed and where it is published as source.
+
+## Writing
+
+The audience is MR scientists: pulse sequences and physics, not software
+architecture. Describe what BlochSim does and why that is right on its own
+terms. These pages are not a changelog — never justify a design by describing
+the design it replaced.
+
+
+## Documentation architecture
+
+Keep the public sidebar shallow and in this order:
+
+1. User Guide
+2. Developer Guide
+3. Explanations
+4. Examples
+5. API
+6. Miscellaneous
+
+The first four Framework examples are the Course. They teach the public
+abstraction in order; the remaining example sections are standalone Tours.
+
+For a new sequence, teach {class}`blochsim.model.Simulator` as the extension
+point. A state-machine simulator has two complementary inputs: its class-level
+handlers interpret commands from an incoming Pulseq/MRD description, and
+`layout()` constructs the same sequence offline. Lower-level
+`SequenceDescription`, `SpinPhysics` and operator machinery are important
+reference/developer concepts, not competing user-facing sequence APIs.
+
+Functional `*_sim` calls are conveniences around shipped simulators. Do not
+present them as the abstraction a user implements.
+
+Figures must remain readable at final documentation width in both light and
+dark mode. Use `docs/figure_style.py` for common typography, transparent
+backgrounds and foreground colors; examples set only figure-specific geometry
+and scientific encodings.

blochsim-0.0.9/.github/skills/cut-a-release/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: cut-a-release
+description: Publish a BlochSim release to PyPI, and diagnose a wheel build. Use when asked about releasing, versioning, cibuildwheel, abi3 wheels, or the packaging setup.
+---
+
+# Cut a BlochSim release
+
+The version comes from the git tag through setuptools-scm; nothing in the tree
+states it. To release:
+
+```sh
+git tag -a v0.1.0 -m "v0.1.0"
+git push origin v0.1.0
+```
+
+The `Wheels` workflow then builds the sdist and every wheel, tests each one,
+and publishes to PyPI through trusted publishing — no token is stored
+anywhere. The `pypi` environment on the repository gates it.
+
+`workflow_dispatch` builds and tests everything without publishing, which is
+how to check a packaging change before tagging. So does any pull request that
+touches `pyproject.toml`, `CMakeLists.txt`, the `.cpp` sources, or the workflow.
+
+## What gets built, and why there is so little of it
+
+Both kernels are plain CPython extensions against the **stable ABI** from 3.10
+on. They call no PyTorch API and link no PyTorch library. So:
+
+- one `cp310-abi3` wheel per platform serves every supported interpreter —
+  there is no per-minor-version build to repeat;
+- the wheel is a couple of megabytes rather than the size of libtorch, and
+  needs no `auditwheel`/`delocate` repair beyond manylinux compliance.
+
+A `#include <torch/...>` in either `.cpp` ends all of that: the wheel would
+become per-version, per-torch-version, and hundreds of megabytes.
+`scripts/check_wheel.py` guards the size and is what cibuildwheel tests every
+wheel with — it loads each kernel by file path, so it needs no PyTorch.
+
+Platforms: manylinux x86_64 and aarch64 on native runners, macOS arm64 with the
+Intel wheel cross-compiled beside it, Windows AMD64.
+
+## The build itself
+
+`scikit-build-core` drives `CMakeLists.txt`. `setup.py` is a shim for tools
+that still shell out to it and configures nothing — do not put build logic
+there. `[tool.scikit-build]` in `pyproject.toml` sets `wheel.py-api = "cp310"`,
+which is what produces the abi3 tag, and excludes the `.cpp` and `.hpp` sources
+from the wheel.
+
+CMake 3.26 or newer is required, for `python_add_library(... USE_SABI ...)`.
+scikit-build-core installs it as a build-time wheel when the system CMake is
+older, so a stale system CMake is not a problem — unless you build with
+`--no-build-isolation`, where it is.