pulserver 0.4.4__cp313-cp313-win_amd64.whl

pulserver/__init__.py

@@ -0,0 +1,25 @@
+"""Orchestrator for MR acquisitions: sequence design, scanner preparation and reconstruction."""
+
+from __future__ import annotations
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_2():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'pulserver.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_2()
+del _delvewheel_patch_1_13_2
+# end delvewheel patch
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+
+try:
+    __version__ = _distribution_version(__name__)
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

pulserver/_accelerators.py

@@ -0,0 +1,68 @@
+"""Load the compiled extension shipped inside the wheel."""
+
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+from pathlib import Path
+from typing import Any
+
+__all__ = ["require"]
+
+_MODULE = "pulserver._ext"
+
+
+def _installed_tags() -> list[str]:
+    """Return the ABI tags of the extension builds present beside the package."""
+    suffix = ".pyd" if sys.platform == "win32" else ".so"
+    package = import_module("pulserver")
+    tags = set()
+    for directory in getattr(package, "__path__", ()):
+        for path in Path(directory).glob(f"_ext.*{suffix}"):
+            parts = path.name.split(".")
+            if len(parts) >= 3:
+                tags.add(parts[1])
+    return sorted(tags)
+
+
+def require(attribute: str | None = None) -> Any:
+    """Load the bundled extension, or raise naming the mismatch.
+
+    The wheel ships the extension for every supported interpreter, so a failed
+    import means a broken installation, never an optional feature.
+
+    Parameters
+    ----------
+    attribute : str, default=None
+        Symbol the caller needs, checked at load so a binary that predates it
+        fails here rather than at the call.
+
+    Returns
+    -------
+    module or object
+        The extension module, or the named attribute when one is given.
+
+    Raises
+    ------
+    ImportError
+        The extension is absent, was built for another interpreter, or does not
+        provide ``attribute``.
+    """
+    try:
+        module = import_module(_MODULE)
+    except ImportError as error:
+        installed = _installed_tags()
+        found = ", ".join(installed) if installed else "none"
+        raise ImportError(
+            f"the bundled extension did not load. Running "
+            f"{sys.implementation.cache_tag}, builds present: {found}."
+        ) from error
+    if attribute is None:
+        return module
+    try:
+        return getattr(module, attribute)
+    except AttributeError as error:
+        raise ImportError(
+            f"the bundled extension does not provide {attribute!r}; "
+            f"the installed binary predates it."
+        ) from error

pulserver/_cli.py

@@ -0,0 +1,59 @@
+"""The ``pulserver`` command."""
+
+from __future__ import annotations
+
+import sys
+
+_USAGE = (
+    "usage: pulserver design {list,validate,generate,import,prune,push,serve} ...\n"
+    "       pulserver scan (--seq FILE | --plugin NAME --plugins DIR) --limits FILE ...\n"
+    "       pulserver console --plugins DIR --limits FILE --store DIR ...\n"
+    "       pulserver validate SEQ [--vendor NAME] [--played FILE] ...\n"
+    "       pulserver proxy --store DIR --port N (--plugins DIR | --forward HOST:PORT) ...\n"
+    "       pulserver recon --plugins DIR --port N ...\n"
+    "       pulserver replay SERIES --plugin FILE (--store DIR | --design SEQ) ...\n"
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run ``pulserver <command> ...``; return its exit status."""
+    argv = sys.argv[1:] if argv is None else argv
+    from ._memory import without_huge_page_advice
+
+    without_huge_page_advice()
+    if argv and argv[0] == "design":
+        from .host._command import main as design
+
+        return design(argv[1:])
+    if argv and argv[0] == "scan":
+        from .virtual._command import main as scan
+
+        return scan(argv[1:])
+    if argv and argv[0] == "proxy":
+        from .proxy.__main__ import main as proxy
+
+        proxy(argv[1:])
+        return 0
+    if argv and argv[0] == "recon":
+        from .recon.__main__ import main as recon
+
+        recon(argv[1:])
+        return 0
+    if argv and argv[0] == "replay":
+        from .recon._replay import main as replay
+
+        return replay(argv[1:])
+    if argv and argv[0] == "validate":
+        from .validate._command import main as check
+
+        return check(argv[1:])
+    if argv and argv[0] == "console":
+        from .virtual._console import main as console
+
+        return console(argv[1:])
+    sys.stderr.write(_USAGE)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pulserver/_labels.py

@@ -0,0 +1,184 @@
+"""Sequence label names and the ISMRMRD counters and flags they map to.
+
+Canonical spellings are the ``.seq`` label names (``LIN``, ``SLC``,
+``LASTSLC``). ISMRMRD and MRPro spellings are translated by
+:func:`canonical_label`.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "COUNTER_LABELS",
+    "ENCODING_COUNTERS",
+    "FLAG_LABELS",
+    "FRAME_COUNTERS",
+    "MRD_COUNTERS",
+    "MRD_FLAGS",
+    "SCANNER_FLAGS",
+    "canonical_label",
+]
+
+#: Counter labels: one integer index per acquisition.
+COUNTER_LABELS = (
+    "SLC",
+    "SEG",
+    "REP",
+    "AVG",
+    "SET",
+    "ECO",
+    "PHS",
+    "LIN",
+    "PAR",
+    "ACQ",
+    "USER0",
+    "USER1",
+    "USER2",
+    "USER3",
+    "USER4",
+    "USER5",
+    "USER6",
+    "USER7",
+)
+
+#: Counters selecting the image an acquisition belongs to.
+FRAME_COUNTERS = ("SLC", "ECO", "PHS", "REP", "AVG", "SET")
+
+#: Counters locating an acquisition within its image.
+ENCODING_COUNTERS = ("LIN", "PAR", "SEG")
+
+#: Counter label to ISMRMRD ``EncodingCounters`` field. ``ACQ`` has no MRD
+#: field. ``USERn`` is ``user_n`` in ``encodingLimits`` and ``idx.user[n]`` on
+#: an acquisition.
+MRD_COUNTERS = {
+    "LIN": "kspace_encode_step_1",
+    "PAR": "kspace_encode_step_2",
+    "AVG": "average",
+    "SLC": "slice",
+    "ECO": "contrast",
+    "PHS": "phase",
+    "REP": "repetition",
+    "SET": "set",
+    "SEG": "segment",
+    "USER0": "user_0",
+    "USER1": "user_1",
+    "USER2": "user_2",
+    "USER3": "user_3",
+    "USER4": "user_4",
+    "USER5": "user_5",
+    "USER6": "user_6",
+    "USER7": "user_7",
+}
+
+#: Flag label to ISMRMRD acquisition-flag constant, for every ISMRMRD flag.
+#: Boundary flags follow from the counters and the acquisition order;
+#: classifying flags come only from the sequence; transport flags come from
+#: whatever packs the data.
+MRD_FLAGS = {
+    # boundary
+    "FIRSTLIN": "ACQ_FIRST_IN_ENCODE_STEP1",
+    "LASTLIN": "ACQ_LAST_IN_ENCODE_STEP1",
+    "FIRSTPAR": "ACQ_FIRST_IN_ENCODE_STEP2",
+    "LASTPAR": "ACQ_LAST_IN_ENCODE_STEP2",
+    "FIRSTAVG": "ACQ_FIRST_IN_AVERAGE",
+    "LASTAVG": "ACQ_LAST_IN_AVERAGE",
+    "FIRSTSLC": "ACQ_FIRST_IN_SLICE",
+    "LASTSLC": "ACQ_LAST_IN_SLICE",
+    "FIRSTECO": "ACQ_FIRST_IN_CONTRAST",
+    "LASTECO": "ACQ_LAST_IN_CONTRAST",
+    "FIRSTPHS": "ACQ_FIRST_IN_PHASE",
+    "LASTPHS": "ACQ_LAST_IN_PHASE",
+    "FIRSTREP": "ACQ_FIRST_IN_REPETITION",
+    "LASTREP": "ACQ_LAST_IN_REPETITION",
+    "FIRSTSET": "ACQ_FIRST_IN_SET",
+    "LASTSET": "ACQ_LAST_IN_SET",
+    "FIRSTSEG": "ACQ_FIRST_IN_SEGMENT",
+    "LASTSEG": "ACQ_LAST_IN_SEGMENT",
+    "LASTSCAN": "ACQ_LAST_IN_MEASUREMENT",
+    # classifying
+    "NOISE": "ACQ_IS_NOISE_MEASUREMENT",
+    "REF": "ACQ_IS_PARALLEL_CALIBRATION",
+    "IMA": "ACQ_IS_PARALLEL_CALIBRATION_AND_IMAGING",
+    "REV": "ACQ_IS_REVERSE",
+    "NAV": "ACQ_IS_NAVIGATION_DATA",
+    "PHASECORR": "ACQ_IS_PHASECORR_DATA",
+    "HPFEEDBACK": "ACQ_IS_HPFEEDBACK_DATA",
+    "DUMMYSCAN": "ACQ_IS_DUMMYSCAN_DATA",
+    "RTFEEDBACK": "ACQ_IS_RTFEEDBACK_DATA",
+    "COILCORR": "ACQ_IS_SURFACECOILCORRECTIONSCAN_DATA",
+    "PHSTABREF": "ACQ_IS_PHASE_STABILIZATION_REFERENCE",
+    "PHSTAB": "ACQ_IS_PHASE_STABILIZATION",
+    # transport
+    "COMPRESS1": "ACQ_COMPRESSION1",
+    "COMPRESS2": "ACQ_COMPRESSION2",
+    "COMPRESS3": "ACQ_COMPRESSION3",
+    "COMPRESS4": "ACQ_COMPRESSION4",
+    # free
+    "USERFLAG1": "ACQ_USER1",
+    "USERFLAG2": "ACQ_USER2",
+    "USERFLAG3": "ACQ_USER3",
+    "USERFLAG4": "ACQ_USER4",
+    "USERFLAG5": "ACQ_USER5",
+    "USERFLAG6": "ACQ_USER6",
+    "USERFLAG7": "ACQ_USER7",
+    "USERFLAG8": "ACQ_USER8",
+}
+
+#: Flag labels the scanner interpreter consumes; they have no MRD counterpart.
+SCANNER_FLAGS = ("PMC", "NOROT", "NOPOS", "NOSCL", "OFF", "ONCE", "TRID")
+
+#: Every flag label. ``SMS`` carries a multiband group index, for which ISMRMRD
+#: has no field; a band index a reconstruction needs travels in a ``USER*``
+#: counter.
+FLAG_LABELS = (*MRD_FLAGS, "SMS", *SCANNER_FLAGS)
+
+_CANONICAL = frozenset(COUNTER_LABELS) | frozenset(FLAG_LABELS)
+
+#: Non-canonical spellings. ``K1`` and ``K2`` are MRPro's ``AcqIdx`` names.
+_ALIASES = {
+    **{mrd.upper(): name for name, mrd in MRD_COUNTERS.items()},
+    **{mrd: name for name, mrd in MRD_FLAGS.items()},
+    **{mrd[len("ACQ_") :]: name for name, mrd in MRD_FLAGS.items()},
+    "K1": "LIN",
+    "K2": "PAR",
+}
+
+#: Names that read as labels but are none, with the reason they are refused.
+_REFUSED = {
+    "K0": (
+        "k0 is the readout direction, the samples within one acquisition, and "
+        "no counter indexes it; the readout extent is "
+        "encodingLimits.kspace_encoding_step_0"
+    ),
+}
+
+
+def canonical_label(name: str) -> str:
+    """Return the canonical spelling of a label name.
+
+    Accepts the canonical name, an ISMRMRD counter field or flag constant name
+    (with or without ``ACQ_``), or MRPro's ``k1``/``k2``, in any case. An
+    unrecognised name is returned unchanged, so custom labels pass through.
+
+    Raises
+    ------
+    ValueError
+        If the name is ``k0``, which reads as a label but indexes nothing.
+
+    Examples
+    --------
+    >>> from pulserver._labels import canonical_label
+    >>> canonical_label("kspace_encode_step_1")
+    'LIN'
+    >>> canonical_label("k1"), canonical_label("k2")
+    ('LIN', 'PAR')
+    >>> canonical_label("ACQ_LAST_IN_SLICE"), canonical_label("LAST_IN_SLICE")
+    ('LASTSLC', 'LASTSLC')
+    >>> canonical_label("LIN"), canonical_label("BIN")
+    ('LIN', 'BIN')
+    """
+    upper = name.upper()
+    if upper in _CANONICAL:
+        return upper
+    if upper in _REFUSED:
+        raise ValueError(f"{name!r} is not a label: {_REFUSED[upper]}")
+    return _ALIASES.get(upper, name)

pulserver/_logs.py

@@ -0,0 +1,44 @@
+"""Log configuration shared by the services."""
+
+from __future__ import annotations
+
+import faulthandler
+import logging
+import os
+import sys
+from pathlib import Path
+
+FORMAT = "%(asctime)s %(process)d %(levelname)s %(name)s: %(message)s"
+
+
+def configure(
+    level: int | str = logging.INFO, logfile: Path | str | None = None
+) -> None:
+    """Log at ``level`` to the standard error, and send that to ``logfile`` when given.
+
+    ``logfile`` is appended to by redirecting the standard output and error
+    descriptors, so ``print``, warnings, native output, a crash's traceback
+    and every child process the caller starts afterwards land in it too.
+    Output is unbuffered in this process and in spawned children, so lines
+    from several processes interleave in the order they were written.
+    """
+    if logfile is not None:
+        redirect(logfile)
+    if isinstance(level, str):
+        level = getattr(logging, level.upper(), logging.INFO)
+    logging.basicConfig(level=level, format=FORMAT, force=True)
+    logging.captureWarnings(True)
+    faulthandler.enable()
+
+
+def redirect(logfile: Path | str) -> None:
+    """Append the standard output and error of this process to ``logfile``."""
+    sys.stdout.flush()
+    sys.stderr.flush()
+    descriptor = os.open(logfile, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o666)
+    os.dup2(descriptor, 1)
+    os.dup2(descriptor, 2)
+    os.close(descriptor)
+    os.environ["PYTHONUNBUFFERED"] = "1"
+    for stream in (sys.stdout, sys.stderr):
+        stream.reconfigure(line_buffering=True)

pulserver/_memory.py

@@ -0,0 +1,21 @@
+"""Process-wide memory settings for the pulserver services."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def without_huge_page_advice() -> None:
+    """Stop NumPy advising the kernel to back large arrays with huge pages.
+
+    Under ``transparent_hugepage/defrag = madvise`` the first touch of an
+    advised array compacts memory, which then dominates building the readout
+    tables. Sets ``NUMPY_MADVISE_HUGEPAGE=0`` unless the environment already
+    chooses, and applies it to a NumPy already imported.
+    """
+    os.environ.setdefault("NUMPY_MADVISE_HUGEPAGE", "0")
+    numpy = sys.modules.get("numpy")
+    if numpy is None or os.environ["NUMPY_MADVISE_HUGEPAGE"] != "0":
+        return
+    numpy._core.multiarray._set_madvise_hugepage(False)

pulserver/_plugins.py

@@ -0,0 +1,79 @@
+"""Plugin files, found by name along an ordered list of directories."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+#: Directories searched for ``<name>.py``, in order; a single directory is a
+#: search path of one.
+PluginPath = Path | str | Sequence[Path | str]
+
+NAME = re.compile(r"[A-Za-z0-9_\-]+")
+
+#: The shipped scanner sequences and reconstructions, searched after the
+#: directories a caller gives, so a file of the same name there replaces one.
+SEQUENCES = Path(__file__).parent / "_zoo" / "sequences"
+RECONSTRUCTIONS = Path(__file__).parent / "_zoo" / "recon"
+
+
+def directories(plugins: PluginPath) -> tuple[Path, ...]:
+    """Return the directories of a search path, in search order."""
+    if isinstance(plugins, (str, Path)):
+        return (Path(plugins),)
+    return tuple(Path(directory) for directory in plugins)
+
+
+def find(plugins: PluginPath, name: str) -> Path:
+    """Return ``<directory>/<name>.py`` of the first directory holding it, the shipped plugins last.
+
+    A symbolic link is followed, so a link names the file it points to.
+
+    Raises
+    ------
+    ValueError
+        If ``name`` is not a plugin name.
+    FileNotFoundError
+        If no directory holds it.
+    """
+    if not NAME.fullmatch(name):
+        raise ValueError(f"invalid plugin name {name!r}")
+    given = directories(plugins)
+    for directory in (*given, SEQUENCES, RECONSTRUCTIONS):
+        path = directory / f"{name}.py"
+        if path.is_file():
+            return path
+    raise FileNotFoundError(
+        f"no plugin {name!r} in {', '.join(str(d) for d in given)}"
+        " or among the shipped plugins"
+    )
+
+
+def names(plugins: PluginPath) -> list[str]:
+    """Return the name of each scanner sequence :func:`find` can return, once, sorted.
+
+    The shipped sequences are listed; the shipped reconstructions are not. A
+    directory that does not exist holds none.
+    """
+    return _stems((*directories(plugins), SEQUENCES))
+
+
+def recon_names(plugins: PluginPath = ()) -> list[str]:
+    """Return the name of each reconstruction :func:`find` can return, once, sorted.
+
+    The shipped reconstructions are listed; the shipped sequences are not. A
+    directory that does not exist holds none.
+    """
+    return _stems((*directories(plugins), RECONSTRUCTIONS))
+
+
+def _stems(search: Sequence[Path]) -> list[str]:
+    return sorted(
+        {
+            path.stem
+            for directory in search
+            for path in directory.glob("*.py")
+            if NAME.fullmatch(path.stem) and path.is_file()
+        }
+    )

pulserver/_zoo/__init__.py

@@ -0,0 +1,35 @@
+"""The shipped scanner sequences and reconstructions, and the pairs a console reconstructs them with."""
+
+#: The shipped reconstruction plugin a console reconstructs each shipped
+#: scanner-sequence plugin with when a scan names none. The stored design and
+#: the reconstruction proxy do not read it.
+ZOO_PAIRS: dict[str, str] = {
+    "bssfp2d": "pics",
+    "bssfp3d": "pics",
+    "epi2d": "epi",
+    "epi3d": "epi",
+    "fse3d": "pmc",
+    "gre2d": "pics",
+    "gre3d": "pics",
+    "gre_multiecho2d": "pics",
+    "gre_multiecho3d": "pics",
+    "gre_propeller2d": "nufft",
+    "gre_radial2d": "nufft",
+    "gre_spiral2d": "nufft",
+    "gre_stack_of_blades3d": "nufft",
+    "gre_stack_of_spirals3d": "nufft",
+    "gre_stack_of_stars3d": "nufft",
+    "mprage3d": "pmc",
+    "mprage_stack_of_spirals3d": "nufft_train",
+    "mprage_stack_of_stars3d": "nufft_train",
+    "se2d": "pics",
+    "se3d": "pics",
+    "se_epi_propeller2d": "nufft",
+    "se_propeller2d": "nufft",
+    "se_radial2d": "nufft",
+    "se_spiral2d": "nufft",
+    "se_stack_of_blades3d": "nufft",
+    "se_stack_of_spirals3d": "nufft",
+    "se_stack_of_stars3d": "nufft",
+    "zte3d": "nufft",
+}