pulserver 0.2.2__tar.gz → 0.3.0__tar.gz

pulserver-0.3.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.3.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.3.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.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pulserver
-Version: 0.2.2
+Version: 0.3.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>

{pulserver-0.2.2 → pulserver-0.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.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.3.0}/docs/user-guide/reconstruction-client.md

@@ -42,6 +42,7 @@ 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 |
@@ -52,8 +53,8 @@ connection, so the client can finish sending and read the reason.
 | `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.
 
 ## Acquisitions
 

{pulserver-0.2.2 → pulserver-0.3.0}/docs/user-guide/running.md

@@ -19,9 +19,9 @@ store are described in {doc}`../explanations/architecture`.
 ```bash
 pulserver design list     --plugins DIR --plugin NAME [--limits FILE --rf-definitions] [--socket PATH]
 pulserver design validate --plugins DIR --plugin NAME --limits FILE [--rf-layout] [--exam DIR] [--socket PATH] < VALUES
-pulserver design generate --plugins DIR --plugin NAME --limits FILE --store DIR [--exam DIR] [--push URL] [--socket PATH] < VALUES
-pulserver design import   --limits FILE --store DIR [--push URL] [--socket PATH] < IMPORT
-pulserver design push     --store DIR --to URL ID...
+pulserver design generate --plugins DIR --plugin NAME --limits FILE --store DIR --scan NAME [--exam DIR] [--push URL] [--socket PATH] < VALUES
+pulserver design import   --limits FILE --store DIR --scan NAME [--push URL] [--socket PATH] < IMPORT
+pulserver design push     --store DIR --scan NAME --to URL ID...
 pulserver design prune    --store DIR [--max-age-days D] [--max-bytes B]
 ```
 
@@ -31,16 +31,17 @@ arguments. `--plugins` is a directory of scanner-sequence plugin files,
 `<plugin>.py`, and may be repeated: a plugin is the file of the first directory
 that holds it, and the shipped plugins are searched last
 ({ref}`shipped-sequences`). `--store` is the design store, created when
-missing.
+missing, and `--scan` the name of the scan the design is stored for: one
+directory name, not starting with `.`.
 
 | Call | Reply |
 | --- | --- |
 | `list` | `PROTOCOL` and the plugin's listing block; with `--rf-definitions`, the `[RfDefinitions]` block |
 | `validate` | `VALID <seconds>` or `INVALID`, an `INFO` line and the value block of the resolved protocol; with `--rf-layout`, a valid reply ends with the `[RfLayout]` block |
-| `generate` | `GENERATED <id>`, the identifier of the design in the store |
+| `generate` | `GENERATED <id>`, the identifier of the design in the scan's directory |
 | `import` | `IMPORTED <id>` |
 | `push` | `PUSHED <count>`: the designs sent, not counting those the intake already holds |
-| `prune` | `PRUNED <count>` |
+| `prune` | `PRUNED <count>`: the scans removed |
 
 A failed call replies `ERROR <message>` and exits with status 1; a plugin that
 ends its process ends the call without a reply and with a nonzero exit status.
@@ -188,20 +189,24 @@ block = "[Protocol]\nTE: 5000\nnx: 96\n[Protocol End]\n"
 status, reply = call("validate", plugins="sequences", plugin="gre2d",
                      limits=limits, block=block)
 status, reply = call("generate", plugins="sequences", plugin="gre2d",
-                     limits=limits, block=block, store=DesignStore("designs"))
+                     limits=limits, block=block,
+                     store=DesignStore("designs", "scan"))
 ```
 
 A plugin file is imported again when its modification time changes.
 
 ### Design store
 
-The store holds one directory per design, `<store>/<id>/`, laid out as
-{doc}`../explanations/architecture` shows. `prune` removes designs least
-recently used first: those unused for longer than `--max-age-days`, then others
-until the store holds at most `--max-bytes`. A design used within the last day
-is kept whatever the limits, since a series may still be playing it or the
-proxy reading it. A store that receives pushed designs is pruned the same way,
-on the reconstruction computer.
+The store holds one directory per scan, `<store>/<scan>/`, and a scan's
+directory holds its design, `<store>/<scan>/<id>/`, laid out as
+{doc}`../explanations/architecture` shows. A design is reused while its scan
+holds it: a call that resolves to the same design replies with it, and one
+that resolves to another stores the new design in place of the scan's
+previous one. `prune` removes whole scans, least recently used first: those
+unused for longer than `--max-age-days`, then others until the store holds at
+most `--max-bytes`. A scan used within the last day is kept whatever the
+limits, since it may still be playing or reconstructing. A store that receives
+pushed designs is pruned the same way, on the reconstruction computer.
 
 ### Design push
 
@@ -258,13 +263,13 @@ pulserver proxy --store DIR --port N --forward HOST:PORT [--forward-config NAME]
 
 | Option | Meaning |
 | --- | --- |
-| `--store` | The design store the proxy reads: the one the design calls write, or the one the intake writes |
+| `--store` | The design store the proxy reads: the one the design calls write, or the one the intake writes. It also holds each scan's pose file, `<store>/<scan>/motion.buf`, for a scan corrected for motion |
 | `--port` | TCP port the scanner's reconstruction client connects to |
 | `--host` | Address to listen on; the loopback interface when unset, `0.0.0.0` for every interface |
 | `--intake-port` | TCP port of the design intake, on the `--host` address; no intake when unset |
 | `--plugins` | Directory of reconstruction plugin files, `<plugin>.py`, repeatable, searched in order before the shipped ones; required unless `--forward` is given |
 | `--queue` | Directory the series waiting for a slot are written to; a temporary directory, removed when the proxy stops, when unset |
-| `--exams` | Directory in which the proxies of this host share the caches of an exam; a location under the system temporary directory when unset |
+| `--exams` | Directory in which the proxies of this host share the caches of an exam, one directory per exam named by its identity: `exam-<ExamID>` for a header carrying `ExamID`. Created readable by the proxy's user alone; one that exists is used with the permissions the site gave it, so design calls running as another user can read the exam's maps. A location under the system temporary directory, private to the proxy's user, when unset |
 | `--slots` | Series reconstructed at once; derived from available memory and the GPUs when unset |
 | `--gpu-slots` | Series reconstructed at once on each GPU when `--slots` is unset; 1 by default |
 | `--spares` | Worker processes started ahead of a series; 1 by default |
@@ -283,9 +288,9 @@ fields the client sends in {doc}`reconstruction-client`.
 
 ### Series routing
 
-The MRD header of each series names the design it was played from in the
-`pulserver_design` user parameter, and the proxy refuses a series whose header
-names no stored design. The client's config names the reconstruction plugin, as
+The MRD header of each series names the scan in the `pulserver_scan` user
+parameter and the design it was played from in `pulserver_design`, and the
+proxy refuses a series whose header names no design stored for that scan. The client's config names the reconstruction plugin, as
 a bare plugin name or the path of its file, or as either under
 `parameters.config`; the design names none. A series whose config names none
 is refused unless the proxy forwards with `--forward-config`.
@@ -351,11 +356,11 @@ relayed back to the client.
 
 With `--intake-port`, the proxy runs a design intake beside it
 ({class}`~pulserver.proxy.DesignIntake`), an HTTP endpoint that writes the
-designs pushed to it into `--store`. `HEAD /designs/<id>` answers 200 when the
-store holds the design and 404 otherwise; `PUT /designs/<id>` stores a bundle
-and answers 201, 200 for a design already stored, or 400 with the reason for a
-bundle that is not the design its path names. A `HEAD` for a stored design
-marks it as used for `prune`.
+designs pushed to it into `--store`. `HEAD /designs/<scan>/<id>` answers 200
+when the scan holds the design and 404 otherwise; `PUT /designs/<scan>/<id>`
+stores a bundle as the scan's design and answers 201, 200 for a design already
+stored, or 400 with the reason for a bundle that is not the design its path
+names. A `HEAD` for a stored design marks its scan as used for `prune`.
 
 ### Network exposure
 

{pulserver-0.2.2 → pulserver-0.3.0}/docs/user-guide/virtual-scanner.md

@@ -17,10 +17,12 @@ field-of-view offset in the protocol block, under the limits file `system.txt`
 
 ```bash
 printf '[Protocol]\nTE: 5000\nnx: 64\nny: 64\nfov_offset_x: 20.0\n[Protocol End]\n' \
-  | pulserver design generate --plugins sequences --plugin gre2d --limits system.txt --store designs
+  | pulserver design generate --plugins sequences --plugin gre2d --limits system.txt \
+    --store designs --scan scan1
 ```
 
-The reply is `GENERATED <id>`. Start a reconstruction proxy on the same store
+The reply is `GENERATED <id>`, and the design is stored for the scan `scan1`.
+Start a reconstruction proxy on the same store
 ({doc}`running`):
 
 ```bash
@@ -33,7 +35,7 @@ pulserver proxy --store designs --port 9002 --plugins recon
 from pulserver import virtual
 
 design = "..."  # the identifier the generation replied
-sequence = f"designs/{design}/sequence.seq"
+sequence = f"designs/scan1/{design}/sequence.seq"
 phantom = virtual.Phantom(
     [
         virtual.Ellipse((0.02, 0.0, 0.0), (0.08, 0.06), t1=0.9, t2=0.07),
@@ -44,6 +46,7 @@ phantom = virtual.Phantom(
 readouts = virtual.simulate(sequence, phantom.tissue(1e-3))
 received = virtual.send(
     ("127.0.0.1", 9002),
+    "scan1",
     design,
     readouts,
     position_mm=(20.0, 0.0, 0.0),
@@ -123,7 +126,9 @@ with wave.open("scan.wav", "wb") as audio:
             audio.writeframes(np.round(32767 * chunk.sound.T).astype("<i2").tobytes())
             yield from chunk.readouts
 
-    received = virtual.send(("127.0.0.1", 9002), design, acquired(), config="pics")
+    received = virtual.send(
+        ("127.0.0.1", 9002), "scan1", design, acquired(), config="pics"
+    )
 ```
 
 The scan is simulated in a thread of its own, ahead of the clock. At
@@ -158,6 +163,7 @@ phantom = virtual.Phantom(
 readouts = virtual.simulate(sequence, phantom.tissue(1e-3), rotation=rotation)
 received = virtual.send(
     ("127.0.0.1", 9002),
+    "scan1",
     design,
     readouts,
     position_mm=1e3 * centre,
@@ -192,8 +198,8 @@ line, is written to standard output, and the scan clock to standard error.
 - `--limits` is the `[Limits]` block of {ref}`scanner-limits`; the phantom's
   chemical shifts are resolved at its `B0`. `--protocol` holds a protocol
   block, as `pulserver design generate` reads it on standard input; without
-  it, the plugin's defaults are designed. Without `--store`, the design is
-  stored in a temporary directory.
+  it, the plugin's defaults are designed. The design is stored for a new scan,
+  named after the time; without `--store`, in a temporary directory.
 - `--orientation` names the rotation from logical to physical axes by the
   physical direction of each logical axis: