pulserver 0.4.0__tar.gz → 0.4.2__tar.gz

{pulserver-0.4.0 → pulserver-0.4.2}/CMakeLists.txt

@@ -28,7 +28,7 @@ pybind11_add_module(_ext
     ${CMAKE_SOURCE_DIR}/src/cpp/ir/collection.cpp
     ${CMAKE_SOURCE_DIR}/src/cpp/ir/waves.cpp
     ${CMAKE_SOURCE_DIR}/src/cpp/ir/wave_plan.cpp
-    ${CMAKE_SOURCE_DIR}/src/cpp/ir/repetition.cpp
+    ${CMAKE_SOURCE_DIR}/src/cpp/ir/gradient_stretch.cpp
     ${CMAKE_SOURCE_DIR}/src/cpp/fourier/bindings.cpp
     ${CMAKE_SOURCE_DIR}/src/cpp/fourier/timeline.cpp
 )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pulserver
-Version: 0.4.0
+Version: 0.4.2
 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,22 +21,21 @@ 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.42
+Requires-Dist: pypulseqpp>=0.0.46
 Requires-Dist: numpy>=2.2.6
 Requires-Dist: ismrmrd>=1.15.0
 Requires-Dist: pydicom>=3.0.2
 Requires-Dist: torch>=2.4
 Requires-Dist: blochsim>=0.0.12
-Requires-Dist: bartorch>=0.0.14
+Requires-Dist: bartorch>=0.0.17
 Requires-Dist: brainweb-dl>=0.4.6
 Requires-Dist: websockets>=16.1.1
-Requires-Dist: tomli>=2.0.1; python_version < "3.11"
 Provides-Extra: dev
 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.17.0; extra == "dev"
+Requires-Dist: ruff==0.17.1; extra == "dev"
 Requires-Dist: pre-commit>=4.6.2; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Provides-Extra: doc

{pulserver-0.4.0 → pulserver-0.4.2}/docs/api/design.md

@@ -28,17 +28,16 @@ control variable, are described in {doc}`../explanations/protocol`.
 
 ## Options
 
-A plugin's options are module constants a parameter file sets when the plugin
-is loaded, so that they shape its sequence function and the protocol it
-declares. A design call selects the file by number: set `N` of a plugin whose
-file is `<script>.py` is `parameters/<script>/<NN>.toml`, and set 0 loads the
-plugin with its defaults.
+A plugin's options are module constants that shape its sequence function and
+the protocol it declares. Each is a user entry holding the index of its value
+among its choices, and a design call loads the plugin at the options its
+request states ({ref}`plugin-options`).
 
 | Object | Description |
 | --- | --- |
-| {obj}`~pulserver.design.option` | The value of an option: the parameter file's, else its default. |
-| {obj}`~pulserver.design.read_options` | The options a parameter file sets. |
-| {obj}`~pulserver.design.OptionError` | An option a parameter file sets that the plugin does not declare or take. |
+| {obj}`~pulserver.design.option` | Declare an option at a user entry; the value the plugin is loaded with. |
+| {obj}`~pulserver.design.OptionParam` | The entry an option is listed as: the index of its value among its choices. |
+| {obj}`~pulserver.design.OptionError` | An option a plugin is loaded with that it does not declare or take, or a declaration the console cannot list. |
 
 ## RF layout
 

{pulserver-0.4.0 → pulserver-0.4.2}/docs/api/ir.md

@@ -40,7 +40,8 @@ the cache layout in {doc}`../developer-guide/internals/ir-cache`.
 | {obj}`~pulserver.ir.Format` | Whether a quantity is stored as a float in its SI unit or as an integer. |
 | {obj}`~pulserver.ir.sample_wave` | A cache's wave on a playout's gradient raster, as loaded into a region of its waveform memory. |
 | {obj}`~pulserver.ir.playout` | Both stages of a segmented playout of a cache, the scan or its receive-gain prescan, recorded: what each position prepares, the registers of each block, what each wave reads from waveform memory and, on request, the waveforms each block plays. |
-| {obj}`~pulserver.ir.Prescan` | The receive-gain calibration a playout plays instead of the scan: one subsequence, to the instance completing its readouts. |
-| {obj}`~pulserver.ir.repetition_gradients` | The gradients of a subsequence's repetition of most gradient energy, as corner points and on a raster: what a scanner's heating and acoustic models are evaluated on. |
+| {obj}`~pulserver.ir.Prescan` | The receive-gain calibration a playout plays instead of the scan: one subsequence, to the instance completing its readouts, opened by the pTx tour on request. |
+| {obj}`~pulserver.ir.prescan_tour` | The pTx prescan tour of a cache: the segment instance holding each channel's largest drive of every parallel-transmit RF definition. |
+| {obj}`~pulserver.ir.gradient_stretch` | The gradients of a subsequence's hyper-repetition-long stretch of most gradient energy, or of the one from its heaviest repetition, as corner points and on a raster: what a scanner's heating model is evaluated on. |
 | {obj}`~pulserver.ir.chain` | Files of the `NextSequence` chain starting at a sequence file, in play order. |
 | {obj}`~pulserver.ir.cache_path` | Cache file of a sequence file. |

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

@@ -7,7 +7,7 @@ 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}`ir-cache` | Conversion passes, waves, playout stages, the gradient stretches, 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 |

{pulserver-0.4.0 → pulserver-0.4.2}/docs/developer-guide/internals/ir-cache.md

@@ -95,8 +95,8 @@ the chain is read. RF and ADC frequency and phase offsets are stored absolute:
 the ppm offsets are resolved on the host, at the gamma and B0 of the call's
 limits, by pypulseqpp's `SequenceLibraries.absolute_offsets`. The labels
 and flags in force at each block, with `PMC` in force from the first, are
-pypulseqpp's `Sequence.evaluate_labels`, and a `TRID` group starts at each block
-`Sequence.label_blocks` lists as setting it; the rotation and RF shim a block
+pypulseqpp's `Sequence.evaluate_labels`, and the blocks that set `TRID` are
+those `Sequence.label_blocks` lists; the rotation and RF shim a block
 plays are `Sequence.block_rotations` and `Sequence.block_shims`. A segment
 position records whether the scanner may move its excitation at run time by a
 carrier offset alone: every instance plays its RF pulse under one gradient,
@@ -200,10 +200,35 @@ instance.
 
 The receive-gain calibration prescan plays one subsequence from its start to
 the segment instance that completes the readouts its sequence declares
-(`NumGainCalibrationReadouts`, at least one). It waits for no trigger and
+(`NumGainCalibrationReadouts`). A readout whose block carries the `NOPRESCAN`
+label plays without being acquired and is not counted, so a multi-echo
+sequence calibrates on its first echo. The count ends with a repetition, so the gain
+is set on whole repetitions of the scan; the conversion refuses one that ends
+inside a repetition, and takes the readouts through the first repetition that
+acquires when the sequence declares none. It waits for no trigger and
 drives no digital output, and every gradient whose amplitude varies across
 repetitions, a phase encoding for instance, plays at zero, as does a wave any
-of whose logical axes varies.
+of whose logical axes varies. An RF pulse whose frequency offset varies across
+repetitions, the slices of a stack, plays at the mean offset over them, as a
+scanner calibrates on one slice. Both are kept per position within the
+repetition, as the gradient flags are, and reported on the block instance
+(`rf_freq_variable` and `rf_freq_mean_hz`). The offsets are those of the
+cache, the field-of-view offset included, so the mean is the centre of the
+positioned stack.
+
+A parallel-transmit sequence can open its prescan with the pTx tour
+(`pulseg_get_prescan_tour`): for every channel of every parallel-transmit RF
+definition of every subsequence, the segment instance holding the largest
+drive that channel receives, the RF amplitude times the channel's shim
+magnitude, or the amplitude alone for a pulse with a waveform per channel.
+Each instance is visited once, under the prescan's rules, whether or not it
+reads out; the tour either acquires its readouts, counted on top of the
+calibration's, or plays them unacquired. A playout reaches each visit by
+seeking the cursor to its first block (`pulseg_cursor_seek`). A visit plays
+part of one occurrence of its subsequence's repetition, each pulse at its
+largest, so resting after it until it has lasted the time per occurrence the
+scan's RF is costed at keeps its average power within the scan's; the rest is
+the interpreter's, from the visit's duration.
 
 Waveform memory holds samples of the type and scale a scanner build defines
 before it includes the library: `PULSEG_WAVE_SAMPLE`, the type;
@@ -229,29 +254,43 @@ to that type.
 
 ## Heaviest repetition
 
-A scanner evaluates its gradient-heating model on the gradients of a
-repetition, and the host's sound pressure check
-(`pypulseqpp.safety.check_spl`) chooses the same one. For each subsequence,
-the conversion finds the repetition, of those the execution stream holds from
-its first block, over which
+A scanner evaluates its gradient-heating model on the gradients of two
+stretches of each subsequence, each as if played without end against its own
+duration ({func}`~pulserver.ir.gradient_stretch`,
+`pulseg_get_gradient_stretch`). A stretch is the run of whole segment instances
+from one instance's start until they last the subsequence's hyper-repetition,
+or `PULSEG_STRETCH_US`, 10 s, where that is shorter, or to the subsequence's end
+where it comes first, each block at its played duration, a pure delay at its
+instance's. The hyper-repetition is the shortest run of repetitions whose
+durations repeat over the whole subsequence, a last run cut short allowed
+(`hyper_copies` and `hyper_us` of `pulseg_get_tr_timing`, from the prefix
+function of the repetitions' durations in us): one repetition where all last
+the same, five for a five-slice packet whose last slice carries the pad, all of
+them where they do not repeat. Where it is one repetition, the second stretch
+is the heaviest repetition itself.
+
+| Stretch | Start |
+|---|---|
+| `PULSEG_STRETCH_HEAVIEST` | Of the instance starts whose stretch lasts that long, the one of largest $E$, the earliest on a tie; the subsequence's start where none does |
+| `PULSEG_STRETCH_HEAVIEST_REPETITION` | The instance holding the start of the repetition of largest $E$, of those the execution stream holds from its first block, the earliest on a tie |
 
 $$
 E = \int \lVert \mathbf{g}(t) \rVert^2 \, dt
 $$
 
-is largest, the earliest on a tie, or the whole subsequence where it does not
-repeat, and the cache carries its gradients
-({func}`~pulserver.ir.repetition_gradients`, `pulseg_get_tr_corner_points`).
-$E$ sums, over the blocks and their gradient events, the square of each
-event's amplitude times the integral of its normalised waveform's square, which a rotation leaves unchanged, so the choice
-does not depend on the blocks' rotations. The repetition is one the scanner
-plays, each block at its own amplitudes and with its own shapes and rotation,
-or through its wave: a waveform that plays, not an envelope of
-several. Its gradients are joined over its blocks as corner points on one
-timeline, along the logical axes and linear in between; the prescription's
-rotation takes them to the physical axes, and a model that needs them on a
-raster samples them at the centres of its intervals
-(`pulseg_sample_corner_points`).
+sums, over the blocks and their gradient events, the square of each event's
+amplitude times the integral of its normalised waveform's square, which a
+rotation leaves unchanged, so neither choice depends on the blocks' rotations.
+The first stretch is found by sliding its end ahead of its start over the
+instances, each walk passing over the stream once. The second holds a short
+burst the first averages out; the host's sound pressure check
+(`pypulseqpp.safety.check_spl`) chooses the same repetition. Each block plays
+at its own amplitudes and with its own shapes and rotation, or through its
+wave: a waveform that plays, not an envelope of several. The gradients are
+joined over the blocks as corner points on one timeline, along the logical
+axes and linear in between; the prescription's rotation takes them to the
+physical axes, and a model that needs them on a raster samples them at the
+centres of its intervals (`pulseg_sample_corner_points`).
 
 ## Cache file
 
@@ -259,7 +298,7 @@ The cache has the name of the first sequence file with its extension replaced,
 `.pseg` by default. It is divided into sections that a consumer loads
 independently. The pulse-generation stage of a playout reads the
 definitions, their waveforms, the waves and their layout, and the gradients of
-each subsequence's heaviest repetition; the scan loop also reads
+each subsequence's stretches; the scan loop also reads
 the per-block instances, the rotations and the execution stream, whose size
 scales with the scan length. Integer and float fields are 4 bytes. The byte
 order is recorded in the file, and a reader on a machine of the other byte order swaps on load. A
@@ -289,7 +328,7 @@ playout to the cursor's, bit for bit.
 
 The IR is built by C++ passes in `src/cpp/ir/`, which run only on the host:
 the segmentation, the waves, their layout in a playout's waveform memory and
-each subsequence's heaviest repetition. The cache reader and writer, the
+each subsequence's stretches. The cache reader and writer, the
 accessors a playout uses to walk the loaded collection, and the two stages of a
 playout are compiled into the interpreter, whose vendor toolchains accept ANSI
 C. They are therefore C89, in `src/c/`, and call nothing in `src/cpp/`. The

{pulserver-0.4.0 → pulserver-0.4.2}/docs/developer-guide/internals/protocol-wire.md

@@ -96,6 +96,20 @@ imaging_mode: stringlist|1|2d|3d
 A value block carries `name: value` lines only, a string list as the index of
 its chosen option.
 
+An option ({ref}`plugin-options`) is an integer user entry, the index of its
+choice. Its mode, `dropdown` with the indices as options (`0|1` for a flag),
+marks it as an option; an interpreter shows it as a number, like any user entry:
+
+```text
+user36_value: int|dropdown|0|0|1|1||0|1
+user36_name: description|Navigator: 0 off, 1 on
+```
+
+A `list` call reads only the option entries of the value block it is given, and
+lists the plugin at those options; `validate` and `generate` load the plugin at
+the options of their request before reading the rest of it against that
+listing. An interpreter lists the plugin again when an option entry changes.
+
 The RF blocks follow a reply when the call asks for them, and no block follows
 where the evaluation is invalid or states no layout. They are lists of numbers:
 each number is ASCII decimal with nine significant digits, the numbers of a list

{pulserver-0.4.0 → pulserver-0.4.2}/docs/developer-guide/internals/reconstruction-proxy.md

@@ -188,10 +188,17 @@ arrives, and replayed to a worker once a slot is released. The client remains
 connected meanwhile, and the images are returned through its connection.
 
 Images, DICOM datasets and text produced by the worker are relayed to the
-client as they are produced. Closing either connection closes the other. Once
-the client's stream ends, the proxy waits for the worker to close however long
-the reconstruction takes, unless it was started with a reconstruction timeout,
-past which the worker is terminated and the client told so.
+client as they are produced once the client's stream has ended whole, with its
+`CLOSE` or a last acquisition flagged `LAST_IN_MEASUREMENT`; what the worker
+produces before, such as a unit that closes on the last readout, is held until
+then. A stream that ends otherwise is refused and the held output dropped, so a
+scan the scanner stopped after its last readout returns nothing. A worker that
+stops reading, as one whose plugin failed, has the rest of the stream read and
+dropped, so what it said reaches the client of a whole stream. Closing either
+connection closes the other. Once the client's stream ends, the proxy waits for
+the worker to close however long the reconstruction takes, unless it was
+started with a reconstruction timeout, past which the worker is terminated and
+the client told so.
 
 ## Enrichment
 

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

@@ -90,9 +90,9 @@ $$
 \alpha_j = \alpha\,|b^+(\mathbf{r}_j)|\,P(\mathbf{g}\cdot\mathbf{r}_j + f_j - f_\mathrm{rf}),
 $$
 
-about its axis turned by the phase of the transmit field $b^+$, relative to
-the pulse's nominal amplitude. A pulse played under a gradient that changes
-along one direction $\hat{\mathbf{n}}$, as a spectral-spatial pulse's
+with $b^+$ relative to the pulse's nominal amplitude, about its axis turned as
+a pulse phase of $-\arg b^+$ turns it ({ref}`transmit-phase-convention`). A
+pulse played under a gradient that changes along one direction $\hat{\mathbf{n}}$, as a spectral-spatial pulse's
 alternating lobes do, has a profile in both the field and the position along
 it, $P(f_j - f_\mathrm{rf}, \hat{\mathbf{n}}\cdot\mathbf{r}_j)$, simulated
 from its samples under that gradient; a pulse played under no gradient, or
@@ -230,7 +230,8 @@ A pulse plays on every transmit channel, weighted by the coil's default shim,
 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
+$b^+(\mathbf{r}) = \sum_c \overline{w_c}\,s^+_c(\mathbf{r})$, for the weights
+$w_c$, which drive the channels. 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

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

@@ -91,8 +91,8 @@ every block. The *repetition* of a subsequence is the period
 `pypulseqpp.Sequence.repetition()` reports, the whole subsequence where it
 does not repeat; the conversion finds virtual segments within it. Do not write
 "repeating unit", which implies that every sequence is periodic, nor "segment
-definition" for a virtual segment. A `TRID` label marks a *safety group* here,
-not a segment boundary. The *IR cache* is the file; the *collection* is what a
+definition" for a virtual segment. A `TRID` label is carried with each block
+and places no segment boundary. The *IR cache* is the file; the *collection* is what a
 reader loads from it.
 
 **Virtual scanner.** The stand-ins for the scanner in tests: the *virtual

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

@@ -99,7 +99,8 @@ designs/
       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
+    motion.buf            the poses of a scan corrected for motion, created
+                          empty with its design
 ```
 
 A design is reused while its scan holds it; a design call that resolves to

{pulserver-0.4.0 → pulserver-0.4.2}/docs/explanations/reconstruction-session.md

@@ -29,10 +29,13 @@ on the other end refuses a series it cannot serve, enriches it from its design
   Code: {class}`~pulserver.proxy.DesignCache`, {class}`~pulserver.proxy.DesignIntake`. Tests: *a design pushed to the intake is reconstructed from its store*; *a series naming no stored design is refused* (`test_proxy.py`).
 - **Refuses a malformed stream with a text the console shows.**
 
-  Code: {class}`~pulserver.proxy.ReconProxy`. Tests: *a series carrying no header or two is refused*; *a series that ends before its last readout is refused*; *a message the proxy cannot read ends the output with its type* (`test_proxy.py`).
-- **Reconstructs each series in a fresh worker process, with spares that have already imported the engine.**
+  Code: {class}`~pulserver.proxy.ReconProxy`. Tests: *a series carrying no header or two is refused*; *a series that ends before its last readout is refused*; *a message the proxy cannot read ends the output with its type*; *a series carrying a message the proxy cannot read is refused* (`test_proxy.py`).
+- **Returns nothing of a scan whose client ends the stream without a `CLOSE`, though its images were already made.**
 
-  Code: {class}`~pulserver.proxy.ReconProxy`. Tests: *the spare worker is replaced after each series*; *the proxy process does not import the reconstruction engine*; *a crashing plugin closes its series and frees the slot* (`test_proxy.py`).
+  Code: {class}`~pulserver.proxy.ReconProxy`. Tests: *a scan stopped after its last readout exports nothing* (`test_proxy.py`).
+- **Reconstructs each series in a fresh worker process, with spares that have already imported the engine, and returns why one failed.**
+
+  Code: {class}`~pulserver.proxy.ReconProxy`. Tests: *the spare worker is replaced after each series*; *the proxy process does not import the reconstruction engine*; *a crashing plugin closes its series and frees the slot*; *a plugin crashing while its series still arrives reports why* (`test_proxy.py`).
 - **Bounds concurrent series by slots, one per GPU by default, and holds the rest on disk.**
 
   Code: `--slots`, `--gpu-slots`, `--queue`. Tests: *a second series waits for a slot and still returns images*; *a series with every slot busy is held on disk until one frees*; *a series reads the gpu its slot holds* (`test_proxy.py`).
@@ -51,9 +54,9 @@ on the other end refuses a series it cannot serve, enriches it from its design
 - **Publishes the poses of a motion-corrected series to the running scan.**
 
   Code: `pulserver.proxy._motion`. Tests: *a motion corrected series publishes its poses to the scan*; *a series not corrected for motion writes no pose file* (`test_proxy.py`).
-- **Keeps each series as the scanner sent it, for an offline rerun that gives the same image.**
+- **Keeps each series enriched, for an offline rerun that gives the same image.**
 
-  Code: `--save-data`. Tests: *a kept series runs offline and gives the image the proxy returned*; *what a proxy keeps is the header the scanner sent* (`test_proxy.py`).
+  Code: `--save-data`. Tests: *a kept series runs offline and gives the image the proxy returned*; *what a proxy keeps is the series it reconstructed, enriched*; *a kept series given its design is not enriched twice* (`test_proxy.py`).
 - **Holds images for a client that dropped, and closes on its own when idle.**
 
   Code: `--idle-timeout`. Tests: *images whose client has gone reach it when it returns*; *the idle timeout counts from the last client leaving* (`test_proxy.py`).
@@ -85,8 +88,10 @@ A series is `CONFIG`, `HEADER`, the `ACQUISITION`s and optional `WAVEFORM`s,
 then `CLOSE`; what returns is `IMAGE`, `DICOM_WITHNAME` and `TEXT` messages,
 then `CLOSE`. These are the identifiers of Gadgetron's MRD streaming protocol.
 A refused series receives one `TEXT` beginning `pulserver:` and a `CLOSE` at
-once. An MRD message carries no length, so a message type the proxy cannot
-read ends the series.
+once. A stream that ends without its `CLOSE` is a scan that did not finish: it
+is refused, and what its reconstruction produced is not returned. An MRD
+message carries no length, so a message type the proxy cannot read ends the
+series.
 
 ### Workers and slots
 

{pulserver-0.4.0 → pulserver-0.4.2}/docs/explanations/safety-checks.md

@@ -91,8 +91,9 @@ converted into the IR cache with its sound pressure levels and SAR ratios.
 
 Two logical axes at 0.8 of the amplitude limit put $0.8\sqrt{2}$ of it on one
 physical axis at 45°. So the sequence is designed under `design_max_grad` and
-`design_max_slew`, which the scanner derates for the prescription, and checked
-on the physical axes against `max_grad` and `max_slew`. The rotation arrives
+`design_max_slew`, which the scanner derates for the prescription, less the
+design margin of `pypulseqpp.apply_system_derates`, and checked on the physical
+axes against `max_grad` and `max_slew` as sent. The rotation arrives
 in the protocol's `fov_rotation_ij` entries; your sequence function never sees
 it.
 

{pulserver-0.4.0 → pulserver-0.4.2}/docs/explanations/scanner-representation.md

@@ -177,7 +177,7 @@ Two offsets give two caches, and two designs.
 | Aspect | PulSeg 2.1-alpha | pulserver |
 | --- | --- | --- |
 | Segment-instance boundaries | Marked by the sequence designer with `TRID` labels (§4.2) | Found within the repetition under the {class}`~pulserver.ir.Grouping` |
-| `TRID` | Identifies the virtual segment an instance plays | A sticky group, reported to the interpreter's checks with the duration of each occurrence; it places no segment boundary |
+| `TRID` | Identifies the virtual segment an instance plays | Carried with each block; it places no segment boundary |
 | Periodicity | Not part of the model | Taken from pypulseqpp when present, and used to encode the stream |
 | Multishot gradient variants | One base block with shot variants, chosen per instance by the optional `gradient_shot_index` | No shot index: a gradient that differs between instances is played as a wave from waveform memory, or the run is a variant of its virtual segment |
 

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

@@ -31,12 +31,19 @@ names none, or that sends no config, unless it forwards with a
 the proxy searches its own `--plugins` directories for that name, whatever the
 path's directory.
 
-The client then reads until the proxy's `CLOSE`: images (`IMAGE`, 1022),
-DICOM datasets (`DICOM_WITHNAME`, 1018) and texts (`TEXT`, 5), in the order the
-reconstruction produces them. A text beginning `pulserver:` reports a series
-that failed. A refused series receives that text and a `CLOSE` at once; the
-proxy then discards what the client still sends until it closes the
-connection, so the client can finish sending and read the reason.
+The client then reads until the proxy's `CLOSE`: images (`IMAGE`, 1022), DICOM
+datasets (`DICOM_WITHNAME`, 1018) and texts (`TEXT`, 5), in the order the
+reconstruction produces them. Nothing is returned before the series has ended
+whole, with the client's `CLOSE` or a last acquisition flagged
+`LAST_IN_MEASUREMENT`: a reconstruction may finish on the last readout, and
+what it produces then is held until that end. A text beginning `pulserver:`
+reports a series that failed. A refused series receives that text and a `CLOSE`
+at once; the proxy then discards what the client still sends until it closes
+the connection, so the client can finish sending and read the reason.
+
+A client ends a scan the scanner stopped by shutting its side of the connection
+for writing without a `CLOSE`, then reading the reply as usual. The series is
+refused and nothing it produced is returned, even when every readout arrived.
 
 ## Header
 
@@ -107,8 +114,10 @@ noise scans and navigators included, and no other.
 
 A series is refused, and its reconstruction stopped, when an acquisition has a
 sample count other than its readout's, when the scan counters skip or repeat
-one, when an acquisition before the last is flagged `LAST_IN_MEASUREMENT`, or
-when the stream carries more or fewer acquisitions than the chain plays.
+one, when an acquisition before the last is flagged `LAST_IN_MEASUREMENT`,
+when the stream carries more or fewer acquisitions than the chain plays, or
+when it ends without a `CLOSE` or a last acquisition flagged
+`LAST_IN_MEASUREMENT`.
 
 ## See also
 

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

@@ -252,6 +252,16 @@ that unit's calibration k-space (its imaging k-space where it has none), and
 projects every later unit onto it. Compress a unit before requesting its maps,
 so that they are estimated in the basis of the data they are used with.
 
+The `pics` and `nufft` handlers fit the maps with
+`apps.nlinv_maps(kspace, phase_pole=0)`, `bart nlinv --phase-pole 0`, on a grid
+of the central 24 lines, or of the trajectory's samples within 12 grid units of
+the centre, and zero-fill them to the image grid: after every Gauss-Newton step
+the phase poles the maps share are moved into the image. Without it, maps that
+share a phase pole go to zero there in every coil, and the image has a dark
+spot at it. BART refuses the detection on a grid with an axis no longer than a
+twentieth of its longest, rounded up; a slab of fewer than 3 partitions is
+fitted without the correction.
+
 A calibration unit, whose `data.data` is `None`, stores its maps for its slice,
 and the imaging units of that slice take them from the stream. A series that is
 only a calibration leaves its maps to the exam by assigning
@@ -389,10 +399,12 @@ process ID, level and logger name.
 ## Offline reconstruction
 
 {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 first from the design it was played from, found in a design
-store or given as its sequence file, with its manifest beside it:
+the calling process, through the same hooks. A file the proxy's `--save-data`
+keeps is enriched already and plays as it stands. A file recorded as the
+scanner sends it, such as `pulserver scan --mrd raw.h5` 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; given a design, an enriched
+file is still played as it stands, never enriched twice:
 
 ```python
 images = PLUGIN.run("raw.h5", store="designs")
@@ -435,9 +447,9 @@ volume as one image per partition.
 
 | Plugin | Reconstructs |
 | --- | --- |
-| `pics` | One image per slice, contrast, cardiac phase, set and repetition, averages summed, from readouts placed by their encoding counters, whitened, completed to full echoes and cropped to the reconstruction field of view as they arrive (`Prewhiten`, `AsymmetricEcho`, `RemoveReadoutOversampling`). Each image is solved as `bart pics -R W` over the coil sensitivities of {func}`~pulserver.recon.coil_maps` (`bart nlinv` of the unit's calibration readouts, else the maps stored for its slice or the exam's, else a fit to the unit's own low-resolution centre), then completed by `bart homodyne` along a partial-Fourier axis. A unit of calibration readouts only makes no image and stores its maps |
+| `pics` | One image per slice, contrast, cardiac phase, set and repetition, averages summed, from readouts placed by their encoding counters, whitened, completed to full echoes and cropped to the reconstruction field of view as they arrive (`Prewhiten`, `AsymmetricEcho`, `RemoveReadoutOversampling`). Each image is solved as `bart pics -R W` over the coil sensitivities of {func}`~pulserver.recon.coil_maps` (`bart nlinv --phase-pole 0` of the unit's calibration readouts, else the maps stored for its slice or the exam's, else a fit to the unit's own low-resolution centre), then completed by `bart homodyne` along a partial-Fourier axis. A unit of calibration readouts only makes no image and stores its maps |
 | `pics_train` | `pics`'s images from readouts that number their place in an echo train or an inversion shot (`contrast`, `ECO`), merged so that the readouts of every place fill one image |
-| `nufft` | The images of `pics` for a radial, spiral, PROPELLER or zero-echo-time trajectory or a stack of them, each solved as `bart pics -t -R W` over `bart nlinv -t` sensitivities of the unit's samples near the k-space centre. The readouts of every segment of a unit, the blades of a PROPELLER scan or the shells of a zero-echo-time one, enter one solve; a trajectory that encodes the partition direction without a partition axis is solved as one volume |
+| `nufft` | The images of `pics` for a radial, spiral, PROPELLER or zero-echo-time trajectory or a stack of them, each solved as `bart pics -t -R W` over `bart nlinv --phase-pole 0 -t` sensitivities of the unit's samples near the k-space centre. The readouts of every segment of a unit, the blades of a PROPELLER scan or the shells of a zero-echo-time one, enter one solve; a trajectory that encodes the partition direction without a partition axis is solved as one volume |
 | `nufft_train` | `nufft`'s images from readouts that number their place in a train of excitations (`contrast`, `ECO`), merged so that the readouts of every place fill one image |
 | `epi` | `pics`'s images from EPI readouts, each whitened, resampled off its ramps onto the matrix and corrected for its odd/even phase against the shot's navigator as it arrives (`bart` ramp operator, `estimate_epi_phase`). The phase-encode-reversed reference set is an image of its own; with PyHySCO installed (GPL-3.0, not a dependency; the Docker image carries it), each later image of its slice, or volume of a 3D scan, is corrected for susceptibility distortion against it |
 | `pmc` | `pics_train`'s images, and a pose from each three-plane navigator (`NAV` or `RTFEEDBACK` readouts): planes gridded with Pipe-Menon density compensation on one thread, coils combined by root sum of squares, registered against the first navigator and filtered by an extended Kalman filter. The pose is published to the scan when its design sets `EnablePmc` |

{pulserver-0.4.0 → pulserver-0.4.2}/docs/user-guide/running.md

@@ -17,7 +17,7 @@ store are described in {doc}`../explanations/architecture`.
 ## Design calls
 
 ```bash
-pulserver design list     --plugins DIR --plugin NAME [--limits FILE --rf-definitions] [--socket PATH]
+pulserver design list     --plugins DIR --plugin NAME [--values FILE] [--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 --scan NAME [--exam DIR] [--push URL] [--socket PATH] < VALUES
 pulserver design import   --limits FILE --store DIR --scan NAME [--push URL] [--socket PATH] < IMPORT
@@ -36,7 +36,7 @@ directory name, not starting with `.`.
 
 | Call | Reply |
 | --- | --- |
-| `list` | `PROTOCOL` and the plugin's listing block; with `--rf-definitions`, the `[RfDefinitions]` block |
+| `list` | `PROTOCOL` and the plugin's listing block at the options of the value block in `--values` ({ref}`plugin-options`); 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 scan's directory |
 | `import` | `IMPORTED <id>` |
@@ -53,9 +53,9 @@ evaluation states an RF layout ({ref}`stating-the-rf-layout`).
 `--rf-definitions` evaluates the plugin at its default protocol under
 `--limits`, which it then requires. `--rf-layout` follows a valid reply with the
 RF layout of the evaluated request, its amplitudes relative to the peaks the
-listing states. Without `--rf-definitions`, `list` depends on the plugin file
-and the installed packages only, so its reply can be written once at
-installation and read without a call.
+listing states. Without `--rf-definitions`, `list` depends on the plugin file,
+its options and the installed packages only, so its reply can be written once
+at installation and read without a call.
 
 `--exam` names the directory of the current exam's cache, which is passed to
 the plugin hooks that take `exam` ({ref}`exam-cache`); for such a plugin the
@@ -107,12 +107,21 @@ design_max_slew: 86.603
 ```
 
 The lines without a prefix are keyword arguments of `pypulseqpp.Opts`, of which
-`B0`, the field in T, is required: ppm offsets are resolved at it. The limits
-are the `system` the plugin designs under and the checks hold the design to, so
-include the scanner's RF and ADC dead times, RF ringdown time and ADC sample
+`B0`, the field in T, is required: ppm offsets are resolved at it. The limits,
+less a design margin, are the `system` the plugin designs under, and the checks
+hold the design to them as sent, so include the scanner's RF and ADC dead times, RF ringdown time and ADC sample
 divisor; `pypulseqpp.Opts` sets the dead times to zero and the divisor to four
 when they are left out.
 
+`max_b1` is the peak B1 the transmit chain allows, in µT, or in the `b1_unit`
+given beside it, as the scanner states it; left out, the pulses are not
+limited. The selective and non-selective excitation and refocusing modules of
+pypulseqpp keep their own duration while the pulse peaks within
+`pypulseqpp.MAX_B1_DERATE` of it, and are otherwise lengthened, flip
+angle and time-bandwidth product held, until it does; the shortest TE and TR a
+plugin reports follow. Spectral, adiabatic, two-dimensional and multiband
+pulses are designed as given.
+
 `max_grad` and `max_slew` are the limits of the gradient coils, to which the
 checks hold every physical axis. Logical axes played together add on one
 physical axis, so under an oblique prescription a design held to `max_grad` and
@@ -126,7 +135,11 @@ scanner for the prescription's rotation:
 | `design_max_slew` | Slew rate each logical axis is designed under, in the `slew_unit` of `max_slew` |
 
 A design limit above the scanner's leaves the scanner's, and one left out is the
-scanner's. `validate` resolves a request under the same limits as `generate`.
+scanner's. The plugin designs under these limits derated once by
+`pypulseqpp.apply_system_derates`: the gradient amplitude, slew rate and peak
+B1 scaled by `pypulseqpp.MAX_GRAD_DERATE`, `MAX_SLEW_DERATE` and
+`MAX_B1_DERATE`. The checks, the design's identity and its manifest keep the
+limits as the scanner sent them. `validate` resolves a request under the same limits as `generate`.
 An imported chain is not designed, and is checked against `max_grad` and
 `max_slew` alone.
 
@@ -277,7 +290,7 @@ pulserver proxy --store DIR --port N --forward HOST:PORT [--forward-config NAME]
 | `--forward` | `HOST:PORT` of the MRD server that reconstructs every series, instead of local workers |
 | `--forward-config` | Config name sent to the `--forward` server; the series' reconstruction plugin when unset |
 | `--dicom` | Convert each image to DICOM before it is relayed, whatever reconstructed it; for a client that reads DICOM only |
-| `--save-data` | Directory each series is kept in as the scanner sends it; kept nowhere when unset |
+| `--save-data` | Directory each series is kept in, enriched; kept nowhere when unset |
 | `--idle-timeout` | Seconds without a client after which the proxy closes, never while a series is reconstructed. Unlimited when unset |
 | `--logfile` | File the log is appended to, together with the standard output and error of the proxy and its workers, so whatever a reconstruction plugin logs, prints or warns lands there too; standard error when unset |
 | `--log-level` | `DEBUG`, `INFO`, `WARNING` or `ERROR`; `INFO` when unset |
@@ -304,10 +317,10 @@ place of a new reconstruction.
 ### Saved series
 
 With `--save-data`, each series is also written to
-`<save-data>/mrd_<timestamp>.h5` as the scanner sends it, header first and each
-acquisition as it arrives, before it is enriched. `pulserver replay` runs a
-plugin on that file and reconstructs it offline as the proxy did
-({ref}`series-replay`). The queue directory holds a series only until it is
+`<save-data>/mrd_<timestamp>.h5` as the proxy reconstructs it: header and
+acquisitions enriched, the header marked `pulserver_enriched`, each acquisition
+as it arrives. `pulserver replay` runs a plugin on that file as it stands and
+gives the image the proxy did ({ref}`series-replay`). The queue directory holds a series only until it is
 reconstructed.
 
 ### Proxy lifetime
@@ -337,9 +350,9 @@ determine when it is reconstructed. The server receives a config file message
 naming the series' reconstruction plugin, which a reconstruction server runs,
 or the `--forward-config` name, such as the configuration by which a Gadgetron
 or FIRE server selects its pipeline. The client's config text is not
-forwarded. What the server returns is relayed to the client; a message type the
-proxy cannot read ends the relay, and the client receives a `pulserver:` text
-naming the type.
+forwarded. What the server returns is relayed to the client once the client's
+stream has ended whole, as from a worker; a message type the proxy cannot read
+ends the relay, and the client receives a `pulserver:` text naming the type.
 
 ### Sequence description