pulserver 0.4.2__tar.gz → 0.4.4__tar.gz

{pulserver-0.4.2 → pulserver-0.4.4}/.github/workflows/wheels.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-14]
+        os: [ubuntu-latest, macos-14, windows-latest]
     steps:
       - uses: actions/checkout@v7
         with:
@@ -36,8 +36,12 @@ jobs:
           CIBW_SKIP: "*-musllinux_*"
           CIBW_ARCHS_LINUX: x86_64
           CIBW_ARCHS_MACOS: arm64
+          CIBW_ARCHS_WINDOWS: AMD64
           # Loads the compiled extension, not only the package.
           CIBW_TEST_COMMAND: "python -c \"from pulserver._accelerators import require; print(require().__name__)\""
+          # Windows: also the conversion and checks, which must not reach the
+          # POSIX-only server and reconstruction modules.
+          CIBW_TEST_COMMAND_WINDOWS: "python -c \"from pulserver._accelerators import require; import pulserver.ir; print(require().__name__)\""
 
       - uses: actions/upload-artifact@v7
         with:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pulserver
-Version: 0.4.2
+Version: 0.4.4
 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.46
+Requires-Dist: pypulseqpp>=0.0.49
 Requires-Dist: numpy>=2.2.6
 Requires-Dist: ismrmrd>=1.15.0
 Requires-Dist: pydicom>=3.0.2

{pulserver-0.4.2 → pulserver-0.4.4}/docs/developer-guide/installation.md

@@ -3,8 +3,8 @@
 ## Prerequisites
 
 You need Git, Python 3.10 to 3.14, a C compiler, a C++17 compiler and CMake,
-on Linux or macOS. Windows is not supported: the warm design server forks per
-call and listens on a Unix socket.
+on Linux or macOS. Windows builds wheels but is not a development platform: the
+warm design server forks per call and listens on a Unix socket.
 
 The test that compiles `src/c/` as a 32-bit scanner build needs a 32-bit C
 toolchain, which `gcc-multilib` provides on Debian and Ubuntu; without one it

{pulserver-0.4.2 → pulserver-0.4.4}/docs/developer-guide/releases.md

@@ -1,8 +1,8 @@
 # Releases
 
 Versions are derived from Git tags by `setuptools_scm`. Pushing a tag `vX.Y.Z`
-runs the Release workflow, which builds the wheels (Linux x86-64 and macOS
-arm64, CPython 3.10 to 3.14) and the source distribution, publishes them to
+runs the Release workflow, which builds the wheels (Linux x86-64, macOS
+arm64 and Windows x86-64, CPython 3.10 to 3.14) and the source distribution, publishes them to
 PyPI through trusted publishing, and creates a GitHub release with Sigstore
 signatures.
 

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

@@ -42,9 +42,9 @@ patient safety.
 - **Checks PNS under the scanner's nerve model (chronaxie or SAFE), up to a fraction of its threshold.**
 
   Code: `CheckLimits(pns=..., pns_limit=...)`, `pypulseqpp.safety.check_pns`. Test: *PNS is refused from the fraction of threshold the limits allow* (`test_ir_checks.py`).
-- **Refuses gradient trains in the forbidden bands of mechanical resonance, on the physical axis they play on.**
+- **Refuses gradient trains in the forbidden bands of mechanical resonance, on the physical axis they play on, read over a 20 ms window: a train shorter than that drives a band less.** A band whose table states no amplitude is held to 8 mT/m. A stated amplitude is read as an echo-spacing lockout reads it: the band is refused when it holds a line above 6 mT/m while the axis's gradient exceeds the amplitude. A window that exceeds a band is read again over 80 ms; a steady line that then lies outside the band, at 80 % of its amplitude or more, is leakage through the 20 ms window and is not refused.
 
-  Code: `CheckLimits(bands=...)`, `pypulseqpp.safety.check_mech_resonance`. Tests: *a gradient train in a forbidden band is refused on the axis it plays* (`test_ir_checks.py`); *the prescription moves a train into the forbidden band of another axis* (`test_ir_checks.py`).
+  Code: `CheckLimits(bands=...)`, `RESONANCE_WINDOW`, `RESONANCE_FLOOR`, `pypulseqpp.safety.check_mech_resonance`. Tests: *a gradient train in a forbidden band is refused on the axis it plays* (`test_ir_checks.py`); *a train drives a band over the 20 ms memory of the resonance* (`test_ir_checks.py`); *a band stating no amplitude is held to 8 mT/m* (`test_ir_checks.py`); *a stated amplitude limits the gradient while the band holds a line* (`test_ir_checks.py`); *the prescription moves a train into the forbidden band of another axis* (`test_ir_checks.py`).
 - **Holds the loudest repetition to 140 dB peak and 99 dB(A) average (IEC 60601-2-33), and writes both levels into the cache.**
 
   Code: `CheckLimits(acoustic=...)`, {func}`~pulserver.ir.spl_levels`, {class}`~pulserver.ir.SplLevels`. Tests: *a repetition too loud on the physical axis it plays on is refused* (`test_ir_checks.py`); *the levels the cache carries are those the check holds to its limits* (`test_ir_checks.py`).

{pulserver-0.4.2 → pulserver-0.4.4}/docs/user-guide/index.md

@@ -25,13 +25,16 @@ virtual-scanner
 ## Supported platforms
 
 pulserver supports Python 3.10 through 3.14; CI tests both bounds on Linux and
-macOS. Windows is not supported: the warm design server forks one process per
-call and listens on a Unix socket.
+macOS. On Windows, sequence design, the safety checks and conversion run from
+the wheel; the warm design server and the reconstruction runtime do not, since
+they fork one process per call, listen on Unix sockets and lock files with
+`fcntl`.
 
 | Platform | Wheel architectures |
 | --- | --- |
 | Linux | x86-64, glibc (`manylinux`) |
 | macOS | Apple silicon |
+| Windows | x86-64 |
 
 Each wheel carries the compiled extension `pulserver._ext`. A source build
 needs a C compiler, a C++17 compiler, CMake and the Python development headers.

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

@@ -176,7 +176,7 @@ gradient heating from it.
 | `pns_chronaxie`, `pns_rheobase`, `pns_alpha` | Chronaxie nerve model: chronaxie in s, rheobase in T/m/s, `alpha` 1 when left out. The rheobase and the alpha are one value or three separated by spaces, one per physical axis |
 | `pns_<axis>_<field>` | SAFE nerve model, for the axes `x`, `y` and `z` and the fields `a1` to `a3`, `tau1` to `tau3` in ms, `stim_limit` in T/m/s and `g_scale` |
 | `pns_limit` | Largest PNS response allowed, as a fraction of the model's threshold; 1 when left out |
-| `forbidden_band_<n>` | One forbidden band: its physical axis (`x`, `y`, `z` or `all`), its lowest and highest frequency in Hz and, optionally, the largest amplitude allowed in it in mT/m, separated by spaces. Without an amplitude, the `min_threshold` of `pypulseqpp.safety.check_mech_resonance` |
+| `forbidden_band_<n>` | One forbidden band: its physical axis (`x`, `y`, `z` or `all`), its lowest and highest frequency in Hz and, optionally, the readout gradient amplitude in mT/m above which it is locked, as an echo-spacing lockout table states it, separated by spaces. Without an amplitude, the band is held to 8 mT/m (`RESONANCE_FLOOR`) |
 | `vop_file` | `.mat` or `.npz` file of VOPs and the head SAR matrix of each body model, at a path the design calls can read; its `safety_factor` multiplies local SAR |
 | `vop_head_limit`, `vop_local_limit` | The scanner's head and local SAR limits in W/kg in its current operating mode |
 | `vop_drive_per_hz` | Channel drive per Hz of RF amplitude, one value or one per channel separated by spaces; a scale common to every channel cancels. Equal drives when left out |

{pulserver-0.4.2 → pulserver-0.4.4}/pyproject.toml

@@ -24,7 +24,7 @@ classifiers = [
 ]
 
 dependencies = [
-  "pypulseqpp>=0.0.46",
+  "pypulseqpp>=0.0.49",
   "numpy>=2.2.6",
   "ismrmrd>=1.15.0",
   "pydicom>=3.0.2",

{pulserver-0.4.2 → pulserver-0.4.4}/src/pulserver/ir/_checks.py

@@ -31,6 +31,14 @@ _RASTERS = (
 REFERENCE_FLIP = np.pi
 REFERENCE_DURATION = 1e-3
 
+#: Window (s) the gradient spectrum is read over against the forbidden bands:
+#: the memory a gradient coil's resonance is driven over, so a train shorter
+#: than it drives a band less. The bands' default threshold is set for it.
+RESONANCE_WINDOW = 0.02
+
+#: Threshold (mT/m) of a forbidden band whose table states no amplitude.
+RESONANCE_FLOOR = 8.0
+
 
 @dataclass(frozen=True)
 class CheckLimits:
@@ -170,7 +178,10 @@ def check(
     ``pypulseqpp.safety.check_max_grad`` and ``check_max_slew``, against the
     gradient limits, dead times and ringdown time of ``system``; and with
     ``check_pns``, ``check_mech_resonance`` and ``check_spl`` where ``limits``
-    carries a nerve model, forbidden bands or an acoustic transfer function.
+    carries a nerve model, forbidden bands or an acoustic transfer function;
+    the gradient spectrum is read over windows of ``RESONANCE_WINDOW``, a
+    band stating no amplitude is held to ``RESONANCE_FLOOR``, and a stated
+    amplitude limits the axis's gradient while the band holds a line.
     The waveforms are timed by the file's own rasters. VOPs are not checked
     here: see :func:`sar_ratios`.
 
@@ -306,11 +317,24 @@ def _pns(sequence: pp.Sequence, system: pp.Opts, limits: CheckLimits) -> list[st
 def _resonance(
     sequence: pp.Sequence, system: pp.Opts, limits: CheckLimits
 ) -> list[str]:
-    _, found = safety.check_mech_resonance(sequence, limits.bands, system=system)
+    _, found = safety.check_mech_resonance(
+        sequence,
+        limits.bands,
+        window_width=RESONANCE_WINDOW,
+        min_threshold=RESONANCE_FLOOR,
+        tolerance_limits="gradient",
+        system=system,
+    )
     return [
         f"{band.peak:.1f} mT/m at {band.frequency:.0f} Hz on {band.peak_axis} in "
-        f"the window at {band.window_start:.3f} s exceeds the {band.threshold:.1f} "
-        f"mT/m of the forbidden band {band.f_min:.0f}-{band.f_max:.0f} Hz"
+        f"the window at {band.window_start:.3f} s "
+        + (
+            f"with the gradient at {band.gradient:.1f} mT/m exceeds the "
+            f"{band.tolerance:.1f} mT/m"
+            if band.tolerance > 0.0
+            else f"exceeds the {band.threshold:.1f} mT/m"
+        )
+        + f" of the forbidden band {band.f_min:.0f}-{band.f_max:.0f} Hz"
         + ("" if band.axis is None else f" on {band.axis}")
         for band in found.bands
         if band.violations

{pulserver-0.4.2 → pulserver-0.4.4}/tests/test_design_service.py

@@ -20,6 +20,7 @@ from pulserver.host import DesignStore, design_id, design_identity, prune
 from pulserver.host import _service as service
 from pulserver.host._blocks import format_import, format_limits
 from pulserver.host._store import scans
+from pulserver.ir import _checks
 from pulserver.protocol import (
     FOV_ROTATION,
     PROTOCOL_BEGIN,
@@ -580,8 +581,10 @@ def test_a_request_is_validated_and_designed_under_the_peak_b1_limit(store):
     assert max(peaks) <= pp.MAX_B1_DERATE * pp.Opts(**limited).max_b1 * (1 + 1e-6)
 
 
-def test_a_design_in_a_forbidden_band_is_refused(store):
-    limits = {**LIMITS, "forbidden_band_1": "all 1 5000 0.001"}
+def test_a_design_in_a_forbidden_band_is_refused(store, monkeypatch):
+    # The GRE's lines read under 5 mT/m: a 1 mT/m floor puts them over it.
+    monkeypatch.setattr(_checks, "RESONANCE_FLOOR", 1.0)
+    limits = {**LIMITS, "forbidden_band_1": "all 1 5000"}
     status, text = generate(store, "gre2d", GRE, limits=limits)
     assert status == 1
     assert "of the forbidden band 1-5000 Hz" in text

{pulserver-0.4.2 → pulserver-0.4.4}/tests/test_ir_checks.py

@@ -72,13 +72,56 @@ def test_a_gradient_train_in_a_forbidden_band_is_refused_on_the_axis_it_plays(tr
     # rounding; the window it names is not part of the claim.
     (problem,) = ir.check(train, SYSTEM, limits=ir.CheckLimits(bands=(BAND_X,)))
     assert re.fullmatch(
-        r"17\.9 mT/m at 1000 Hz on x in the window at \d+\.\d{3} s exceeds the "
-        r"5\.0 mT/m of the forbidden band 900-1100 Hz on x",
+        r"17\.9 mT/m at 1000 Hz on x in the window at \d+\.\d{3} s with the "
+        r"gradient at 15\.0 mT/m exceeds the 5\.0 mT/m of the forbidden band "
+        r"900-1100 Hz on x",
         problem,
     )
     assert ir.check(train, SYSTEM, limits=ir.CheckLimits(bands=(BAND_Y,))) == []
 
 
+@pytest.mark.parametrize(("pairs", "refused"), [(4, False), (16, True)])
+def test_a_train_drives_a_band_over_the_20_ms_memory_of_the_resonance(
+    tmp_path, pairs, refused
+):
+    """A 4 ms burst at 1 kHz drives the band too little; 16 ms of it reads over the floor.
+
+    Read over 40 ms, the 16 ms train would read 5.5 mT/m and pass.
+    """
+    lobes = [(_mT("x", sign * 15, 100e-6, 300e-6),) for sign in (1, -1)]
+    path = _written(tmp_path, lobes * pairs + [(pp.make_delay(0.1),)])
+    floor_band = safety.ForbiddenBand("x", 900.0, 1100.0, 0.0)
+    problems = ir.check(path, SYSTEM, limits=ir.CheckLimits(bands=(floor_band,)))
+    assert bool(problems) == refused
+
+
+@pytest.mark.parametrize(("pairs", "refused"), [(8, False), (10, True)])
+def test_a_band_stating_no_amplitude_is_held_to_8_mt_per_m(tmp_path, pairs, refused):
+    """An 8 ms burst at 1 kHz reads 5.5 mT/m in the band and passes; 10 ms reads 8.9 and is refused."""
+    lobes = [(_mT("x", sign * 15, 100e-6, 300e-6),) for sign in (1, -1)]
+    path = _written(tmp_path, lobes * pairs + [(pp.make_delay(0.1),)])
+    floor_band = safety.ForbiddenBand("x", 900.0, 1100.0, 0.0)
+    problems = ir.check(path, SYSTEM, limits=ir.CheckLimits(bands=(floor_band,)))
+    assert bool(problems) == refused
+
+
+@pytest.mark.parametrize(("spoiler", "refused"), [(False, False), (True, True)])
+def test_a_stated_amplitude_limits_the_gradient_while_the_band_holds_a_line(
+    tmp_path, spoiler, refused
+):
+    """A 1 kHz train of 8 mT/m lobes reads 9.5 mT/m in a band stating 12 mT/m.
+
+    The line alone stays under 12; a 30 mT/m spoiler in the same window takes
+    the gradient over it, as an echo-spacing lockout reads its amplitude.
+    """
+    lobes = [(_mT("x", sign * 8, 100e-6, 300e-6),) for sign in (1, -1)]
+    middle = [(_mT("x", 30, 300e-6),)] if spoiler else []
+    path = _written(tmp_path, lobes * 30 + middle + lobes * 30)
+    stated = safety.ForbiddenBand("x", 900.0, 1100.0, 12.0)
+    problems = ir.check(path, SYSTEM, limits=ir.CheckLimits(bands=(stated,)))
+    assert bool(problems) == refused
+
+
 def test_the_prescription_moves_a_train_into_the_forbidden_band_of_another_axis(train):
     on_x, on_y = (ir.CheckLimits(bands=(band,)) for band in (BAND_X, BAND_Y))
     assert ir.check(train, SYSTEM, rotation=QUARTER, limits=on_x) == []
@@ -100,7 +143,8 @@ def test_a_reflected_prescription_is_checked_as_it_plays(train):
 def test_pns_is_refused_from_the_fraction_of_threshold_the_limits_allow(
     tmp_path, pns_limit, refused
 ):
-    # 150 T/m/s for 200 us: 84% of the threshold, sampled at the raster centres.
+    # 150 T/m/s for 200 us: 87% of the threshold, read at the raster interval
+    # ends, where a ramp's response peaks.
     path = _written(tmp_path, [(_mT("x", 30, 200e-6),), (pp.make_delay(5e-3),)])
     nerve = safety.ChronaxieModel(chronaxie=360e-6, rheobase=20.0, alpha=0.324)
     problems = ir.check(
@@ -108,7 +152,7 @@ def test_pns_is_refused_from_the_fraction_of_threshold_the_limits_allow(
     )
     assert problems == (
         [
-            "PNS of 84% of the chronaxie threshold, largest on x, at 0.0002 s in "
+            "PNS of 87% of the chronaxie threshold, largest on x, at 0.0002 s in "
             "block 1 reaches 80%"
         ]
         if refused