pulserver 0.2.2__tar.gz → 0.4.0__tar.gz

pulserver-0.4.0/.github/DISCUSSION_TEMPLATE/ideas.yml

@@ -0,0 +1,19 @@
+labels: ["idea"]
+body:
+  - type: textarea
+    id: idea
+    attributes:
+      label: The idea
+      description: |
+        A capability, an interface or a direction you think pulserver 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.

pulserver-0.4.0/.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 plugin, reconstruction or scanner workflow, and where you got stuck. If a result looks wrong, say what you
+        expected 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: pulserver version
+      placeholder: "0.0.x, or the commit you are on"

pulserver-0.4.0/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,24 @@
+name: Documentation
+description: An error, an omission, or an unanswered question in the documentation.
+labels: ["documentation"]
+body:
+  - type: input
+    id: page
+    attributes:
+      label: Page
+      description: URL of the page, or the docstring's object name.
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: >-
+        The passage that is wrong, unclear or missing, and what the implementation,
+        a test, pypulseqpp, the ISMRMRD specification or the literature says instead.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed wording

{pulserver-0.2.2 → pulserver-0.4.0}/.github/workflows/wheels.yml

@@ -30,7 +30,7 @@ jobs:
         with:
           fetch-depth: 0 # setuptools_scm reads the tags
 
-      - uses: pypa/cibuildwheel@v4.2.1
+      - uses: pypa/cibuildwheel@v4.3.1
         env:
           CIBW_BUILD: ${{ inputs.cibw-build }}
           CIBW_SKIP: "*-musllinux_*"

{pulserver-0.2.2 → pulserver-0.4.0}/AGENTS.md

@@ -1,6 +1,5 @@
 # pulserver — agent instructions
 
-`CLAUDE.md` and `GEMINI.md` import this file. Edit this file only.
 `SKILLS.md` indexes the skills under `.claude/skills/`: the procedures for
 building and testing the package and for writing documentation. This page
 states the rules; a skill states how a recurring task is carried out under

{pulserver-0.2.2 → pulserver-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pulserver
-Version: 0.2.2
+Version: 0.4.0
 Summary: Orchestrator for MR acquisitions: sequence design, scanner preparation and reconstruction.
 Keywords: mri,pulseq,mrd,ismrmrd,reconstruction,scanner
 Author-Email: Matteo Cencini <matteo.cencini@gmail.com>
@@ -21,7 +21,7 @@ Project-URL: Documentation, https://pulserver.github.io/pulserver/
 Project-URL: Issues, https://github.com/pulserver/pulserver/issues
 Project-URL: Source, https://github.com/pulserver/pulserver
 Requires-Python: >=3.10
-Requires-Dist: pypulseqpp>=0.0.40
+Requires-Dist: pypulseqpp>=0.0.42
 Requires-Dist: numpy>=2.2.6
 Requires-Dist: ismrmrd>=1.15.0
 Requires-Dist: pydicom>=3.0.2
@@ -36,7 +36,7 @@ Requires-Dist: pytest>=9.1.1; extra == "dev"
 Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
 Requires-Dist: pytest-xdist>=3; extra == "dev"
 Requires-Dist: coverage>=7.16.2; extra == "dev"
-Requires-Dist: ruff==0.16.10; extra == "dev"
+Requires-Dist: ruff==0.17.0; extra == "dev"
 Requires-Dist: pre-commit>=4.6.2; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Provides-Extra: doc

{pulserver-0.2.2 → pulserver-0.4.0}/docs/api/host.md

@@ -23,6 +23,7 @@ described in {doc}`../user-guide/running`, and the identity of a design in
 
 | Object | Description |
 | --- | --- |
-| {obj}`~pulserver.host.DesignStore` | The designs under one directory, each in `<id>/` and immutable once written. |
+| {obj}`~pulserver.host.DesignStore` | The designs of one scan, each in `<root>/<scan>/<id>/` and immutable once written. |
+| {obj}`~pulserver.host.prune` | Remove scan directories of a store root, least recently used first. |
 | {obj}`~pulserver.host.design_identity` | SHA-256 of what a design depends on: plugin, limits, resolved protocol and source. |
 | {obj}`~pulserver.host.design_id` | Identifier of a design: the first 18 hexadecimal digits of its identity. |

{pulserver-0.2.2 → pulserver-0.4.0}/docs/api/index.md

@@ -5,15 +5,15 @@ Conceptual background is in {doc}`../explanations/index` and procedures in the
 
 | Page | Module | Contents |
 | --- | --- | --- |
-| {doc}`protocol` | `pulserver.protocol` | Protocol entries, presets and the protocol text blocks. |
-| {doc}`design` | `pulserver.design` | {class}`~pulserver.design.SequencePlugin` and its UI entries. |
-| {doc}`host` | `pulserver.host` | Design calls and the design store. |
-| {doc}`ir` | `pulserver.ir` | Segmentation into the IR cache, and its playout. |
-| {doc}`proxy` | `pulserver.proxy` | Reconstruction proxy, design lookup and MRD enrichment. |
-| {doc}`recon` | `pulserver.recon` | {class}`~pulserver.recon.ReconPlugin`, its context, buffers and results. |
-| {doc}`mrd` | `pulserver.mrd` | MRD acquisitions, header entries, images and sequence definitions. |
-| {doc}`validate` | `pulserver.validate` | Playout validation against a recording or the IR cache. |
-| {doc}`virtual` | `pulserver.virtual` | Phantoms, the Fourier engine, the scan clock and the reconstruction client. |
+| {doc}`protocol` | `pulserver.protocol` | Protocol entries, presets and the protocol text blocks |
+| {doc}`design` | `pulserver.design` | {class}`~pulserver.design.SequencePlugin` and its UI entries |
+| {doc}`host` | `pulserver.host` | Design calls and the design store |
+| {doc}`ir` | `pulserver.ir` | Segmentation into the IR cache, and its playout |
+| {doc}`proxy` | `pulserver.proxy` | Reconstruction proxy, design lookup and MRD enrichment |
+| {doc}`recon` | `pulserver.recon` | {class}`~pulserver.recon.ReconPlugin`, its context, buffers and results |
+| {doc}`mrd` | `pulserver.mrd` | MRD acquisitions, header entries, images and sequence definitions |
+| {doc}`validate` | `pulserver.validate` | Playout validation against a recording or the IR cache |
+| {doc}`virtual` | `pulserver.virtual` | Phantoms, the Fourier engine, the scan clock and the reconstruction client |
 
 The C library a scanner interpreter links is documented in its public headers,
 [`src/c/include/pulseg/`](https://github.com/pulserver/pulserver/tree/main/src/c/include/pulseg),

{pulserver-0.2.2 → pulserver-0.4.0}/docs/api/proxy.md

@@ -43,6 +43,7 @@ and fields of a series in {doc}`../user-guide/reconstruction-client`.
 | --- | --- |
 | {obj}`~pulserver.proxy.DesignCache` | The designs of a store, the most recently read kept tabulated. |
 | {obj}`~pulserver.proxy.Design` | A stored design as the reconstruction side reads it. |
+| {obj}`~pulserver.proxy.SCAN_PARAMETER` | Header user parameter naming the scan a series was played in. |
 | {obj}`~pulserver.proxy.DESIGN_PARAMETER` | Header user parameter naming the design a series was played from. |
 | {obj}`~pulserver.proxy.DesignIntake` | HTTP endpoint receiving pushed designs into the store the proxy reads. |
 

{pulserver-0.2.2 → pulserver-0.4.0}/docs/api/recon.md

@@ -70,3 +70,4 @@ sensitivity maps, noise prewhitening and coil compression are the subject of
 | {obj}`~pulserver.recon.ReconData` | The readouts of one reconstruction unit: imaging and calibration k-space, counters and waveforms. |
 | {obj}`~pulserver.recon.ReconBuffer` | K-space of one encoding space, filled one acquisition at a time, with the acquisition nearest the k-space centre. |
 | {obj}`~pulserver.recon.ReconResult` | Image array the runtime packages as an MRD image or DICOM dataset, with the acquisition its geometry is taken from and the rescale of its DICOM pixels. |
+| {obj}`~pulserver.recon.figure_rgb` | Return a matplotlib figure drawn to the pixels of an RGB result, sent as a DICOM secondary capture. |

{pulserver-0.2.2 → pulserver-0.4.0}/docs/developer-guide/documentation.md

@@ -333,7 +333,7 @@ A separate example is justified when it studies something across objects, or goe
 
 The examples landing page carries a **Course** table and a **Tours** table. When examples fall into categories, each category gets a landing page the documentation owns, carrying one or two factual sentences and a table of what is below it. A table is preferred to a wall of thumbnails once a category holds more than a handful of examples, because a reader looking for one sequence or one module reads names rather than pictures.
 
-Every landing table, in every section, has two columns or, on the API landing page, three: the linked page (and its module), then **Contents**. A Contents cell is a short technical noun phrase naming what the page holds (*Single-shot EPI: blurring along the echo train and Nyquist ghosting from gradient delays.*), never a question, an instruction or a narrative sentence.
+Every landing table, in every section, has two columns or, on the API landing page, three: the linked page (and its module), then **Contents**. A Contents cell is a short technical noun phrase naming what the page holds (*Single-shot EPI: blurring along the echo train and Nyquist ghosting from gradient delays*), with no closing period, never a question, an instruction or a narrative sentence.
 
 Global navigation carries the gallery and its categories, to the depth at which a category is still something a reader would look for on its own. Below that depth, an example is reached from the table on its category's page and from cross-references, not from the navigation tree.
 

{pulserver-0.2.2 → pulserver-0.4.0}/docs/developer-guide/index.md

@@ -5,13 +5,13 @@ conventions, and the implementation design behind the explanations.
 
 | Page | Contents |
 | --- | --- |
-| {doc}`installation` | Prerequisites, the editable installation, pre-commit hooks and the documentation build. |
-| {doc}`workflow` | Forks, branches, pull requests, continuous integration and the code of conduct. |
-| {doc}`style` | Ruff, tests, C89 and code conventions, and the KomaMRI simulation. |
-| {doc}`documentation` | Documentation types and scientific writing. |
-| {doc}`terminology` | Scanner, protocol, Pulseq and MRD terminology, units and layers. |
-| {doc}`internals/index` | The IR cache, the protocol text blocks, the reconstruction proxy, calibration, SAR ratios and the virtual scanner. |
-| {doc}`releases` | Versioning, wheels, PyPI and the published documentation. |
+| {doc}`installation` | Prerequisites, the editable installation, pre-commit hooks and the documentation build |
+| {doc}`workflow` | Forks, branches, pull requests, continuous integration and the code of conduct |
+| {doc}`style` | Ruff, tests, C89 and code conventions; KomaMRI simulation |
+| {doc}`documentation` | Documentation types and scientific writing |
+| {doc}`terminology` | Scanner, protocol, Pulseq and MRD terminology, units and layers |
+| {doc}`internals/index` | IR cache, protocol text blocks, reconstruction proxy, calibration, SAR ratios, virtual scanner |
+| {doc}`releases` | Versioning, wheels, PyPI and the published documentation |
 
 ```{toctree}
 :hidden:

{pulserver-0.2.2 → pulserver-0.4.0}/docs/developer-guide/internals/index.md

@@ -6,12 +6,12 @@ authors.
 
 | Page | Contents |
 | --- | --- |
-| {doc}`calibration` | Prewhitening, coil compression, sensitivity maps and the reuse of stored maps. |
-| {doc}`ir-cache` | Conversion passes, waves, playout stages, the heaviest repetition, the cache file and the C89 library. |
-| {doc}`protocol-wire` | RF layout, protocol keys and values, and the protocol text blocks. |
-| {doc}`reconstruction-proxy` | Reconstruction units, image headers, enrichment and trajectory rules, readout placement and workers. |
-| {doc}`sar-ratios` | pTx SAR ratios from VOPs against a reference pulse. |
-| {doc}`virtual-scanner` | Played trajectory, signal model, coils, Fourier engine, export, test coverage and scan clock. |
+| {doc}`calibration` | Prewhitening, coil compression, sensitivity maps and the reuse of stored maps |
+| {doc}`ir-cache` | Conversion passes, waves, playout stages, the heaviest repetition, the cache file and the C89 library |
+| {doc}`protocol-wire` | RF layout, protocol keys and values, and the protocol text blocks |
+| {doc}`reconstruction-proxy` | Reconstruction units, image headers, enrichment and trajectory rules, readout placement and workers |
+| {doc}`sar-ratios` | pTx SAR ratios from VOPs against a reference pulse |
+| {doc}`virtual-scanner` | Played trajectory, signal model, coils, Fourier engine, export, test coverage and scan clock |
 
 ```{toctree}
 :hidden:

{pulserver-0.2.2 → pulserver-0.4.0}/docs/developer-guide/internals/virtual-scanner.md

@@ -227,9 +227,14 @@ the models show none of the dielectric effects of a wavelength comparable to
 the head.
 
 A pulse plays on every transmit channel, weighted by the coil's default shim,
-the unit weights that bring the channels into phase at the isocentre, where the
-pulse then has its nominal amplitude: each cube sees the transmit field
-$b^+(\mathbf{r}) = \sum_c w_c\,s^+_c(\mathbf{r})$, for the weights $w_c$.
+the weights of magnitude $1/\sqrt{N}$ for $N$ channels that bring the channels
+into phase at the isocentre, where the pulse then has its nominal amplitude:
+each cube sees the transmit field
+$b^+(\mathbf{r}) = \sum_c w_c\,s^+_c(\mathbf{r})$, for the weights $w_c$. The
+squares of the weights sum to 1, so the channels together carry the power of
+one channel at the pulse's amplitude, and an RF shim is written in the same
+normalisation: a circularly polarised shim of $N$ channels has weights of
+magnitude $1/\sqrt{N}$.
 
 A console given field maps takes the coils, and the subject's field, from
 electromagnetic and susceptibility models of BrainWeb's head instead
@@ -506,8 +511,8 @@ The maps' transmit coils come with the VOPs mariepy compresses from the same
 fields, and every design is made under those of the exam's transmit coil: its
 limits name the VOP file, the default shim, the drive of every channel per
 hertz of a pulse's amplitude with which the channels' fields reach that
-amplitude at the isocentre, $2 / (\gamma \sum_c |B^-_c(\mathbf{0})|)$ in the
-maps' unit of drive, and the head and local SAR limits of IEC 60601-2-33's
+amplitude at the isocentre through the default shim,
+$2\sqrt{N} / (\gamma \sum_c |B^-_c(\mathbf{0})|)$ in the maps' unit of drive, and the head and local SAR limits of IEC 60601-2-33's
 normal operating mode. The IR cache then reports each subsequence's SAR against
 the reference pulse in that coil ({doc}`../../explanations/safety-checks`).
 

{pulserver-0.2.2 → pulserver-0.4.0}/docs/developer-guide/terminology.md

@@ -70,7 +70,8 @@ estimate; the design the interpreter plays is the stored one.
 **Storage.** A *design* is one generated or imported chain with its IR cache,
 immutable once written. Its *identity* is the hash of what it depends on; its
 *identifier* is the first 18 hexadecimal digits of the identity. The *design
-store* is the directory holding every design. A *design call* is one `list`,
+store* is the directory holding one directory per *scan*, named by whatever
+plays it, and a scan's directory holds the design the scan plays. A *design call* is one `list`,
 `validate`, `generate` or `import` of an interpreter host process; no call
 keeps state beyond the designs it stores. A design is *pushed* to the *design intake*, the
 proxy's HTTP endpoint writing its store, as a *bundle* of the files of its

{pulserver-0.2.2 → pulserver-0.4.0}/docs/examples/course.md

@@ -10,12 +10,12 @@ everything you see is computed by the code on the page.
 
 | Lesson | Contents |
 | --- | --- |
-| {doc}`1. Your first scan </generated/gallery/01-course/01_protocol_to_image>` | An acquisition on the virtual scanner, from protocol to image. |
-| {doc}`2. Your sequence in the scanner UI </generated/gallery/01-course/02_sequence_plugin>` | Sequence plugin, protocol entries and `evaluate`. |
-| {doc}`3. What the scanner plays </generated/gallery/01-course/03_scanner_representation>` | Safety checks, repetition, virtual segments and segment instances. |
-| {doc}`4. What your recon receives </generated/gallery/01-course/04_reconstruction_plugin>` | MRD enrichment: counters, flags, encoding spaces and trajectory. |
-| {doc}`5. Your recon plugin </generated/gallery/01-course/05_recon_plugin>` | Reconstruction units, inverse FFT and `pics`. |
-| {doc}`6. Test your pair on the virtual scanner </generated/gallery/01-course/06_testing_on_the_virtual_scanner>` | Flip-angle series against the closed-form signal. |
+| {doc}`1. Your first scan </generated/gallery/01-course/01_protocol_to_image>` | Acquisition on the virtual scanner, from protocol to image |
+| {doc}`2. Your sequence in the scanner UI </generated/gallery/01-course/02_sequence_plugin>` | Sequence plugin, protocol entries and `evaluate` |
+| {doc}`3. What the scanner plays </generated/gallery/01-course/03_scanner_representation>` | Safety checks, repetition, virtual segments and segment instances |
+| {doc}`4. What your recon receives </generated/gallery/01-course/04_reconstruction_plugin>` | MRD enrichment: counters, flags, encoding spaces and trajectory |
+| {doc}`5. Your recon plugin </generated/gallery/01-course/05_recon_plugin>` | Reconstruction units, inverse FFT and `pics` |
+| {doc}`6. Test your pair on the virtual scanner </generated/gallery/01-course/06_testing_on_the_virtual_scanner>` | Flip-angle series against the closed-form signal |
 
 By the end you have two files, a sequence plugin and a recon plugin, that run
 unchanged on a real scanner through its interpreter

{pulserver-0.2.2 → pulserver-0.4.0}/docs/examples/index.md

@@ -1,7 +1,7 @@
 # Examples
 
-Executable pages, run when the documentation is built, so every figure and
-every printed number on them is produced by the code as it stands.
+Executed when the documentation is built: every figure and number comes from
+the code on the page.
 
 The concepts these pages rely on are in {doc}`/explanations/index`, and the
 interfaces they call are documented in {doc}`/api/index`.
@@ -12,22 +12,22 @@ The shortest path from a protocol to a reconstructed image, read in order.
 
 | Lesson | Contents |
 | --- | --- |
-| {doc}`/generated/gallery/01-course/01_protocol_to_image` | An acquisition on the virtual scanner, from protocol to image. |
-| {doc}`/generated/gallery/01-course/02_sequence_plugin` | Sequence plugin, protocol entries and `evaluate`. |
-| {doc}`/generated/gallery/01-course/03_scanner_representation` | Safety checks, repetition, virtual segments and segment instances. |
-| {doc}`/generated/gallery/01-course/04_reconstruction_plugin` | MRD enrichment: counters, flags, encoding spaces and trajectory. |
-| {doc}`/generated/gallery/01-course/05_recon_plugin` | Reconstruction units, inverse FFT and `pics`. |
-| {doc}`/generated/gallery/01-course/06_testing_on_the_virtual_scanner` | Flip-angle series against the closed-form signal. |
+| {doc}`/generated/gallery/01-course/01_protocol_to_image` | Acquisition on the virtual scanner, from protocol to image |
+| {doc}`/generated/gallery/01-course/02_sequence_plugin` | Sequence plugin, protocol entries and `evaluate` |
+| {doc}`/generated/gallery/01-course/03_scanner_representation` | Safety checks, repetition, virtual segments and segment instances |
+| {doc}`/generated/gallery/01-course/04_reconstruction_plugin` | MRD enrichment: counters, flags, encoding spaces and trajectory |
+| {doc}`/generated/gallery/01-course/05_recon_plugin` | Reconstruction units, inverse FFT and `pics` |
+| {doc}`/generated/gallery/01-course/06_testing_on_the_virtual_scanner` | Flip-angle series against the closed-form signal |
 
 ## Tours
 
-Applications, advanced branches and specialised workflows, each standalone.
+Standalone examples beyond the Course; each names the lessons it assumes.
 
 | Tour | Contents |
 | --- | --- |
-| {doc}`/generated/gallery/02-tours/01_protocol_resolution` | Bandwidth quantization and minimum echo time. |
-| {doc}`/generated/gallery/02-tours/02_segmentation` | Repetition, virtual segments and subsequences; segment count against scan length. |
-| {doc}`/generated/gallery/02-tours/03_fov_offset_enrichment` | Field-of-view offset in the IR cache and its phase in MRD enrichment. |
+| {doc}`/generated/gallery/02-tours/01_protocol_resolution` | Bandwidth quantization and minimum echo time |
+| {doc}`/generated/gallery/02-tours/02_segmentation` | Repetition, virtual segments and subsequences; segment count against scan length |
+| {doc}`/generated/gallery/02-tours/03_fov_offset_enrichment` | Field-of-view offset in the IR cache and its phase in MRD enrichment |
 
 ```{toctree}
 :hidden:

{pulserver-0.2.2 → pulserver-0.4.0}/docs/examples/tours.md

@@ -1,13 +1,12 @@
 # Tours
 
-Applications, advanced branches and specialised workflows. Each Tour stands
-alone and states the lessons of the {doc}`course` it assumes.
+Standalone examples beyond the {doc}`course`. Each names the lessons it assumes.
 
 | Tour | Contents |
 | --- | --- |
-| {doc}`/generated/gallery/02-tours/01_protocol_resolution` | Bandwidth quantization and minimum echo time. |
-| {doc}`/generated/gallery/02-tours/02_segmentation` | Repetition, virtual segments and subsequences; segment count against scan length. |
-| {doc}`/generated/gallery/02-tours/03_fov_offset_enrichment` | Field-of-view offset in the IR cache and its phase in MRD enrichment. |
+| {doc}`/generated/gallery/02-tours/01_protocol_resolution` | Bandwidth quantization and minimum echo time |
+| {doc}`/generated/gallery/02-tours/02_segmentation` | Repetition, virtual segments and subsequences; segment count against scan length |
+| {doc}`/generated/gallery/02-tours/03_fov_offset_enrichment` | Field-of-view offset in the IR cache and its phase in MRD enrichment |
 
 ```{toctree}
 :hidden:

{pulserver-0.2.2 → pulserver-0.4.0}/docs/explanations/architecture.md

@@ -36,9 +36,9 @@ both on the virtual scanner.
 - **Writes a design whole or not at all, once, and never modifies it.**
 
   Code: {mod}`pulserver.host`. Tests: *a design being written is invisible until it is whole*; *two processes designing one protocol at once store it once*; *a stored design holds the files its manifest records and no other* (`test_design_service.py`).
-- **Prunes the store least recently used first.**
+- **Keeps one design per scan, and prunes whole scans least recently used first.**
 
-  Code: `pulserver design prune`. Tests: *pruning removes the designs unused for longest first*; *a design found again is used again*; *pruning keeps a design used within the day whatever the limits* (`test_design_service.py`).
+  Code: {class}`~pulserver.host.DesignStore`, {func}`~pulserver.host.prune`. Tests: *a design committed to a scan replaces the scan's previous design*; *pruning removes the scans unused for longest first*; *a scan whose design is found again is used again*; *pruning keeps a scan used within the day whatever the limits* (`test_design_service.py`).
 - **Pushes each design to a proxy on another computer, which stores it only if every file matches the manifest.**
 
   Code: {class}`~pulserver.proxy.DesignIntake`. Tests: *a generation pushes the design it replies*; *the intake refuses a tampered bundle with the reason* (`test_design_push.py`).
@@ -90,16 +90,23 @@ below $2^{24}$ exactly.
 
 ```text
 designs/
-  3f9c0a1b2c3d4e5f60/
-    sequence.seq          first file of the NextSequence chain, binary Pulseq
-    sequence_main.seq     the remaining files, when there are prescans
-    sequence.pseg         IR cache
-    resolved.protocol
-    manifest.json         identity and identifier, limits, package versions,
+  29258/                  one scan, named by whatever plays it
+    3f9c0a1b2c3d4e5f60/   the scan's design
+      sequence.seq        first file of the NextSequence chain, binary Pulseq
+      sequence_main.seq   the remaining files, when there are prescans
+      sequence.pseg       IR cache
+      resolved.protocol
+      manifest.json       identity and identifier, limits, package versions,
                           creation time, plugin and source, scan time,
                           field-of-view offset, SHA-256 of every file
+    motion.buf            the poses of a scan corrected for motion
 ```
 
+A design is reused while its scan holds it; a design call that resolves to
+another design stores it in place of the scan's previous one. The scanner's
+reconstruction client names the scan and the design in the MRD header, and the
+proxy reads the design from `<store>/<scan>/<id>/`.
+
 The proxy reads the Pulseq files, not the cache: the cache is derived for
 playout, and the Pulseq files are the design of record.
 

{pulserver-0.2.2 → pulserver-0.4.0}/docs/explanations/index.md

@@ -1,24 +1,22 @@
 # Explanations
 
-Conceptual background for the interfaces documented in {doc}`../api/index` and
-used in the {doc}`user guide <../user-guide/index>`. These pages state the
-components, the representations exchanged between them and the conventions the
-rest of the documentation assumes.
+The concepts behind pulserver, one page each, in the order of a scan.
+Interfaces are in the {doc}`API reference <../api/index>`, procedures in the
+{doc}`user guide <../user-guide/index>`.
 
 | Page | Contents |
 | --- | --- |
-| {doc}`architecture` | Design calls, reconstruction proxy and the design store. |
-| {doc}`protocol` | Prescription, resolved protocol, units and wire precision. |
-| {doc}`safety-checks` | Checks run before a design is stored, and those computed by the vendor's routines. |
-| {doc}`scanner-representation` | Base blocks, virtual segments, segment instances and the execution stream. |
-| {doc}`raw-data` | Counters, flags, encoding spaces, trajectory and field-of-view phase. |
-| {doc}`reconstruction-session` | MRD streaming, design lookup, workers and slots, forwarding and DICOM. |
-| {doc}`reconstruction` | Reconstruction units, results and the exam's calibration context. |
-| {doc}`virtual-scanner` | Virtual interpreter, Fourier engine and reconstruction client. |
+| {doc}`architecture` | Design calls, reconstruction proxy and the design store |
+| {doc}`protocol` | Prescription, resolved protocol, units and wire precision |
+| {doc}`safety-checks` | Checks run before a design is stored, and those computed by the vendor's routines |
+| {doc}`scanner-representation` | Base blocks, virtual segments, segment instances and the execution stream |
+| {doc}`raw-data` | Counters, flags, encoding spaces, trajectory and field-of-view phase |
+| {doc}`reconstruction-session` | MRD streaming, design lookup, workers and slots, forwarding and DICOM |
+| {doc}`reconstruction` | Reconstruction units, results and the exam's calibration context |
+| {doc}`virtual-scanner` | Virtual interpreter, Fourier engine and reconstruction client |
 
-Implementation detail -- the cache layout, the wire format, the proxy's
-buffers and workers, and the virtual scanner's Fourier engine -- is in
-{doc}`../developer-guide/internals/index`.
+Layouts, wire formats and numerical methods are in the
+{doc}`internals <../developer-guide/internals/index>`.
 
 ```{toctree}
 :hidden:

pulserver-0.4.0/docs/misc/index.md

@@ -0,0 +1,15 @@
+# Miscellaneous
+
+| Page | Contents |
+| --- | --- |
+| {doc}`license` | MIT licence; notices for adapted code, BrainWeb data and artwork |
+| {doc}`related` | Related projects |
+| {doc}`contributors` | Maintainers and contributors |
+
+```{toctree}
+:hidden:
+
+license
+related
+contributors
+```

{pulserver-0.2.2 → pulserver-0.4.0}/docs/user-guide/index.md

@@ -6,11 +6,11 @@ interfaces, units and defaults in {doc}`../api/index`.
 
 | Page | Contents |
 | --- | --- |
-| {doc}`running` | Design calls, design server, reconstruction proxy and server, playout validation. |
-| {doc}`scanner-sequences` | Sequence plugins, protocol entries and evaluation. |
-| {doc}`reconstruction-plugins` | Reconstruction plugins and offline reconstruction. |
-| {doc}`reconstruction-client` | Messages and header of a reconstruction client. |
-| {doc}`virtual-scanner` | Phantom scans through a stored design, the proxy and a plugin. |
+| {doc}`running` | Design calls, design server, reconstruction proxy and server, playout validation |
+| {doc}`scanner-sequences` | Sequence plugins, protocol entries and evaluation |
+| {doc}`reconstruction-plugins` | Reconstruction plugins and offline reconstruction |
+| {doc}`reconstruction-client` | Messages and header of a reconstruction client |
+| {doc}`virtual-scanner` | Phantom scans through a stored design, the proxy and a plugin |
 
 ```{toctree}
 :hidden:

{pulserver-0.2.2 → pulserver-0.4.0}/docs/user-guide/reconstruction-client.md

@@ -42,18 +42,50 @@ connection, so the client can finish sending and read the reason.
 
 | Element | Requirement | Use |
 | --- | --- | --- |
+| `pulserver_scan`, a `userParameterString` | Required | The scan the design is stored for: the `--scan` of the design call, one directory name of the design store |
 | `pulserver_design`, a `userParameterString` | Required | The identifier of the design the interpreter plays, from the `GENERATED` or `IMPORTED` reply: 18 hexadecimal digits, which are three 24-bit integers of six digits each |
 | `experimentalConditions.H1resonanceFrequency_Hz` | Required by the MRD schema | DICOM `ImagingFrequency` |
 | `acquisitionSystemInformation.receiverChannels` | Optional | The coil count of a reconstruction buffer laid out before its first acquisition |
 | `ExamID`, a `userParameterString`, or else `studyInformation.studyInstanceUID`, or else `studyInformation.studyID` | Optional | The exam; the series of one exam share its exam cache, and a series without one is an exam of its own |
 | `fov_offset_mm`, a `userParameterString` | Optional | The position of the field-of-view centre, three millimetres along the logical readout, phase and slice axes separated by spaces; a difference from the offset the design was converted at is applied to the samples as a receive phase. Without it, the converted offset |
 | `subjectInformation`, `studyInformation`, `measurementInformation`, `acquisitionSystemInformation` | Optional | Copied into the DICOM datasets; `relativeTablePosition` is not |
-| `measurementInformation.measurementID` | A non-negative integer when `systemVendor` names GE | The DICOM series number on a GE system |
+| `measurementInformation.measurementID` | A non-negative integer when `systemVendor` names GE | The DICOM series number on a GE system: of the first series the reconstruction returns, and `100 × measurementID + k` of the `k`-th after it |
+| `dicom:<attribute>`, a `userParameterString` | Optional | A DICOM attribute of every image ({ref}`dicom-attributes`) |
 | `encoding` | Optional | Replaced by one encoding space per subsequence, and one more for the navigator readouts of a subsequence that has them. The reconstruction space is the sequence's matrix size and field of view, one slice deep for a stack of 2D slices; the encoded space of a Cartesian space has the readout widened to the full echo, oversampling included, and its field of view in proportion. The encoding limits are the extremes of the counters the readouts reach, centred on the k-space centre line and partition the sequence defines. A matrix size or field of view the sequence does not define is kept from the client's encoding at the same index |
 | `sequenceParameters` | Optional | TR, TE, TI and flip angles replaced by those the sequence defines; TR and TE it does not define are measured by pypulseqpp's `test_report_dict`, flip angles it does not define are the distinct values of `rf_flip_angles` |
 
-A header that the ISMRMRD schema does not accept, or that names no design of
-the store, is refused before any acquisition is read.
+A header that the ISMRMRD schema does not accept, or that names no design the
+store holds for its scan, is refused before any acquisition is read.
+
+(dicom-attributes)=
+### DICOM attributes
+
+A client states the DICOM attributes the MRD header has no element for as
+`userParameterString` entries named `dicom:<attribute>`. The DICOM builder
+reads them once, with the rest of the header, into the attributes every image
+of the series starts from; an entry whose value names a quantity of the image
+is filled in for each image instead. An image's own meta attributes take
+precedence over both. `<attribute>` is one of:
+
+| Form | Example | Resolved by |
+| --- | --- | --- |
+| A keyword of the DICOM standard | `dicom:ImagedNucleus` = `23Na` | pydicom's dictionary |
+| An explicit tag and value representation | `dicom:(0011,1011)FL` = `{location}` | Itself; a private group's creator is one more entry, `dicom:(0011,0010)LO` |
+| A keyword of a private dictionary | `dicom:PulseSequenceLabel` = `pulserver` | The file `dicom:dictionary` names, in MATLAB's format, one `(gggg,eeee) VR Keyword VM` line per attribute |
+
+A value separates multiple values with `\` and may name, in braces, a quantity
+of the image it is written into; `{{` and `}}` are literal braces:
+
+| Name | Value |
+| --- | --- |
+| `slice_location` | The image centre along the plane normal, in mm: the `SliceLocation` written by default |
+| `location` | The image centre along the patient axis the normal lies closest to, in mm, positive towards right, anterior or superior; for an oblique plane, along the normal turned towards those |
+| `location_letter` | The side `location` lies on: `R` or `L`, `A` or `P`, `S` or `I`, and `+` or `-` for an oblique plane |
+| `instance_number`, `series_number` | The image's `InstanceNumber` and `SeriesNumber` |
+
+An attribute that resolves to no tag, for want of the dictionary, is logged and
+left out. `pulserver replay --dicom-dictionary` names another dictionary for a
+series replayed where the header's is not.
 
 ## Acquisitions
 

{pulserver-0.2.2 → pulserver-0.4.0}/docs/user-guide/reconstruction-plugins.md

@@ -284,7 +284,7 @@ receives carries the message. `required=False` returns `None` instead of
 raising.
 
 (dicom-pixel-values)=
-## DICOM pixel values
+## DICOM output
 
 A DICOM dataset stores integer pixels, made when a result with `dicom=True` is
 converted from the image the plugin returned. The dataset's rescale maps them
@@ -331,6 +331,32 @@ with one mapping per DICOM series, a series being the images that share
 
 `RescaleType` is `US`, unspecified: the units are those of the reconstruction.
 
+A DICOM image is written in the radiological display orientation of the plane
+it lies closest to: an axial image with the patient's right on the left and
+anterior at the top, a coronal one with the right on the left and superior at
+the top, a sagittal one with anterior on the left and superior at the top. Its
+pixels are flipped and transposed to that orientation, never resampled; the MRD
+image keeps the orientation the reconstruction returned.
+
+Each `series_index` is a DICOM series of its own. The first to arrive takes the
+series identity the header states; each later one a series UID derived from it
+and, on a GE system, the series number `100 × measurementID + k` for the
+`k`-th after the first.
+
+A plot, a fit or a report reaches the scanner as an RGB result: a `(y, x, 3)`
+array of values from 0 to 255, which {func}`~pulserver.recon.figure_rgb` draws
+from a matplotlib figure, stored as a DICOM secondary capture.
+
+```python
+return recon.ReconResult(
+    recon.figure_rgb(figure),
+    image_type="rgb",
+    series_index=10,
+    dicom=True,
+    attributes={"SeriesDescription": "T1 fit"},
+)
+```
+
 ## Diffusion tables
 
 The proxy states the diffusion table a design names in the header's
@@ -365,12 +391,17 @@ process ID, level and logger name.
 {meth}`~pulserver.recon.ReconPlugin.run` reconstructs an ISMRMRD HDF5 file in
 the calling process, through the same hooks. A file recorded as the scanner
 sends it, such as `pulserver scan --mrd raw.h5` or the proxy's `--save-data`
-writes, is enriched from its design store first:
+writes, is enriched first from the design it was played from, found in a design
+store or given as its sequence file, with its manifest beside it:
 
 ```python
 images = PLUGIN.run("raw.h5", store="designs")
+images = PLUGIN.run("raw.h5", design="designs/scan/9c74a8aa28527cf231/sequence.seq")
 ```
 
+`pulserver replay` does the same from the command line
+({ref}`series-replay`).
+
 Calling the plugin on an {class}`~pulserver.mrd.AcquisitionBucket` runs
 `startup`, passes every acquisition to `receive`, reconstructs the units still
 open, runs `finish`, and returns the last output. A header need only describe