quantized-lab 0.8.0__py3-none-any.whl

quantized/cli.py

@@ -0,0 +1,214 @@
+"""``qz`` — launch the quantized app (API + built SPA) and open the browser.
+
+    qz                  serve http://127.0.0.1:8000, open a browser tab, and
+                        exit when the last tab closes (app-like run model;
+                        pre-set QZ_AUTO_SHUTDOWN=0 to opt out)
+    qz --port 9000      use a different port
+    qz --no-browser     don't open a browser (headless / CI; never auto-exits)
+    qz --dev            Vite dev server (HMR) + auto-reloading backend
+    qz --desktop        native window (pywebview; pip install quantized[desktop])
+    qz --calc           calculator-only view (DiraCulator materials calculators),
+                        opens /?view=calc; combine with --desktop for a small
+                        native window titled "DiraCulator" (also: `diraculator`
+                        console-script alias runs this by default)
+    qz plugin list      list discovered plugins and what they contribute
+    qz plugin enable <name>    re-enable a previously disabled plugin
+    qz plugin disable <name>   disable a plugin without deleting it
+
+If the requested port is busy and ``--port`` was NOT given explicitly, qz
+falls back to a free ephemeral port automatically (the main app is often
+already running on 8000) and prints a note. An explicit ``--port`` that's
+busy still errors as before.
+
+The UI is served from the Vite build output (``src/quantized/web``). On a bare
+dev checkout that directory is absent — build it once with
+``cd frontend && npm run build``, or just double-click the ``run`` launcher,
+which builds on first use.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import uvicorn
+
+from quantized.server_launch import _open_when_healthy, _resolve_port, _run_desktop, _run_dev
+
+# Same resolution as quantized.app._WEB_DIR (kept as a separate constant here
+# rather than importing app.py, so this pre-uvicorn check stays cheap — it
+# doesn't need to pull in FastAPI and every router just to print a warning).
+_WEB_DIR = Path(__file__).parent / "web"
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Dispatch: ``qz plugin ...`` to the plugin CLI, else launch the server."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args and args[0] == "plugin":
+        _plugin_command(args[1:])
+        return
+    _serve(args)
+
+
+def main_calc(argv: list[str] | None = None) -> None:
+    """``diraculator`` console-script entry point — the same as ``qz --calc``.
+
+    Injects ``--calc`` ahead of the caller's args and delegates to ``main``;
+    ``--desktop``/``--port``/etc. all still compose normally (e.g.
+    ``diraculator --desktop``)."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    main(["--calc", *args])
+
+
+def _serve(argv: list[str]) -> None:
+    """Parse serve args, (optionally) schedule the browser, and run the server."""
+    parser = argparse.ArgumentParser(prog="qz", description="Launch the quantized app.")
+    parser.add_argument("--host", default="127.0.0.1", help="bind host (default 127.0.0.1)")
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="bind port (default 8000; falls back to a free port if that's "
+        "busy and --port wasn't given explicitly)",
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true", help="do not open a browser tab"
+    )
+    parser.add_argument(
+        "--calc",
+        action="store_true",
+        help="calculator-only view (DiraCulator) — opens /?view=calc",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--dev", action="store_true", help="Vite dev server (HMR) + reloading backend"
+    )
+    mode.add_argument(
+        "--desktop", action="store_true", help="native window (pywebview)"
+    )
+    args = parser.parse_args(argv)
+
+    explicit_port = args.port is not None
+    port = _resolve_port(args.host, args.port if explicit_port else 8000, explicit=explicit_port)
+    calc_path = "/?view=calc" if args.calc else ""
+
+    if args.dev:
+        _run_dev(args.host, port)
+        return
+    if args.desktop:
+        if args.calc:
+            _run_desktop(
+                args.host, port, title="DiraCulator", width=520, height=680, path=calc_path
+            )
+        else:
+            _run_desktop(args.host, port)
+        return
+
+    url = f"http://{args.host}:{port}{calc_path}"
+    if not _WEB_DIR.is_dir():
+        print(
+            f"[qz] UI not built ({_WEB_DIR} missing). "
+            "Run: cd frontend && npm run build  (or use the run launcher)."
+        )
+
+    if not args.no_browser:
+        # App-like run model: the SPA holds /api/ws open per tab, and app.py
+        # exits when the last tab closes (past a refresh grace window) — armed
+        # here, before uvicorn imports quantized.app by string, so the module-
+        # level env read sees it. setdefault so an explicit QZ_AUTO_SHUTDOWN=0
+        # in the user's environment wins. Headless (--no-browser) never arms.
+        os.environ.setdefault("QZ_AUTO_SHUTDOWN", "1")
+        # Open the tab once /api/health answers (a fixed delay races the cold
+        # numpy/scipy/matplotlib import); daemon thread, so Ctrl+C still exits.
+        _open_when_healthy(url, args.host, port)
+
+    print(f"[qz] quantized -> {url}   (press Ctrl+C to stop)")
+    uvicorn.run("quantized.app:app", host=args.host, port=port, log_level="warning")
+
+
+def _plugin_command(argv: list[str]) -> None:
+    """``qz plugin ...`` — inspect and manage installed/drop-in plugins.
+
+    Subcommands: ``list`` (default — also runs when no subcommand is given),
+    ``enable <name>``, ``disable <name>``. ``<name>`` is the source
+    identifier shown in the first column of ``qz plugin list`` (the drop-in
+    module's file stem, or the entry-point name for a packaged plugin).
+    Enable/disable persist the ``disabled`` list in
+    ``<config_dir>/plugins.json`` (see :mod:`quantized.plugins.loader`); a
+    disabled plugin is never imported, so it can be parked without deleting
+    it.
+    """
+    parser = argparse.ArgumentParser(prog="qz plugin", description="Inspect quantized plugins.")
+    sub = parser.add_subparsers(dest="action")
+    sub.add_parser("list", help="list discovered plugins and what they contribute")
+    enable_parser = sub.add_parser("enable", help="re-enable a disabled plugin")
+    enable_parser.add_argument("name", help="plugin source identifier (see 'qz plugin list')")
+    disable_parser = sub.add_parser("disable", help="disable a plugin without deleting it")
+    disable_parser.add_argument("name", help="plugin source identifier (see 'qz plugin list')")
+    args = parser.parse_args(argv)
+
+    if args.action == "enable":
+        _plugin_set_enabled(args.name, enabled=True)
+    elif args.action == "disable":
+        _plugin_set_enabled(args.name, enabled=False)
+    else:
+        _plugin_list()
+
+
+def _plugin_list() -> None:
+    """Print each discovered plugin: identifier, name/version, contributions, status."""
+    from quantized.plugins import load_plugins
+
+    infos = load_plugins()
+    if not infos:
+        print("No plugins discovered.")
+        print("  Drop a .py module into the plugins directory, or install a package")
+        print("  exposing the 'quantized.plugins' entry point. See docs/plugins.md.")
+        return
+    for info in infos:
+        head = info.source
+        if info.name:
+            head += f"  ({info.name} v{info.version})"
+        print(f"{head}  [{info.status}]")
+        if info.parsers:
+            print(f"    parsers: {', '.join(info.parsers)}")
+        if info.fit_models:
+            print(f"    fit models: {', '.join(info.fit_models)}")
+        if info.steps:
+            print(f"    steps: {', '.join(info.steps)}")
+        if info.error:
+            print(f"    ! {info.error}")
+
+
+def _plugin_set_enabled(name: str, *, enabled: bool) -> None:
+    """``qz plugin enable|disable <name>``: flip ``name``'s disabled state.
+
+    ``name`` is validated against the currently discoverable plugins (a
+    disabled plugin still shows up here — only a nonexistent source is
+    rejected) so a typo fails loudly with the known names, instead of
+    silently writing a dead entry to ``plugins.json``. Reloads afterwards so
+    the change (and a following ``qz plugin list``) reflects it immediately.
+    """
+    from quantized.plugins import disable_plugin, enable_plugin, load_plugins
+
+    known = {info.source for info in load_plugins()}
+    if name not in known:
+        print(f"[qz] unknown plugin {name!r}.")
+        if known:
+            print(f"  known plugins: {', '.join(sorted(known))}")
+        else:
+            print("  no plugins discovered. Run 'qz plugin list' for details.")
+        sys.exit(1)
+
+    if enabled:
+        enable_plugin(name)
+    else:
+        disable_plugin(name)
+    load_plugins()
+    print(f"[qz] plugin {name!r} {'enabled' if enabled else 'disabled'}.")
+
+
+if __name__ == "__main__":
+    main()

quantized/datastruct.py

@@ -0,0 +1,153 @@
+"""The canonical data contract: ``DataStruct``.
+
+Every parser returns one, and every consumer (corrections, fitting, plotting,
+export) reads one. Mirrors the MATLAB ``parser.createDataStruct`` contract:
+
+    time     (N,)    independent variable / x-axis
+    values   (N, M)  data matrix — N samples, M channels
+    labels   (M,)    channel names (deduplicated: 'A','A' -> 'A','A (2)')
+    units    (M,)    channel units ('' when unknown)
+    metadata         immutable mapping of import metadata
+
+Pure layer — no fastapi/pydantic imports (enforced by test_repo_integrity).
+The instance is frozen and its arrays are read-only, honouring the
+"raw data is preserved, never mutated in place" rule: compute on copies.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = ["DataStruct"]
+
+
+def _deduplicate(labels: tuple[str, ...]) -> tuple[str, ...]:
+    """Append ' (2)', ' (3)', ... to repeated labels (matches MATLAB)."""
+    seen: dict[str, int] = {}
+    out: list[str] = []
+    for lbl in labels:
+        if lbl in seen:
+            seen[lbl] += 1
+            out.append(f"{lbl} ({seen[lbl]})")
+        else:
+            seen[lbl] = 1
+            out.append(lbl)
+    return tuple(out)
+
+
+@dataclass(frozen=True, slots=True)
+class DataStruct:
+    """Immutable, parser-agnostic dataset. Build via :meth:`create`."""
+
+    time: NDArray[np.float64]
+    values: NDArray[np.float64]
+    labels: tuple[str, ...] = ()
+    units: tuple[str, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        time = np.asarray(self.time, dtype=float).ravel()
+        values = np.asarray(self.values, dtype=float)
+        if values.ndim == 1:
+            values = (
+                values.reshape(-1, 1)
+                if values.size
+                else np.empty((time.shape[0], 0), dtype=float)
+            )
+        if values.ndim != 2:
+            raise ValueError(f"values must be 2-D, got {values.ndim}-D")
+
+        n = time.shape[0]
+        if values.shape[0] != n:
+            raise ValueError(
+                f"time length ({n}) must equal values row count ({values.shape[0]})"
+            )
+        m = values.shape[1]
+
+        labels = tuple(self.labels) if self.labels else tuple(f"ch{i + 1}" for i in range(m))
+        units = tuple(self.units) if self.units else tuple("" for _ in range(m))
+        if len(labels) != m:
+            raise ValueError(f"expected {m} labels for {m} columns, got {len(labels)}")
+        if len(units) != m:
+            raise ValueError(f"expected {m} units for {m} columns, got {len(units)}")
+        labels = _deduplicate(labels)
+
+        time.flags.writeable = False
+        values.flags.writeable = False
+
+        object.__setattr__(self, "time", time)
+        object.__setattr__(self, "values", values)
+        object.__setattr__(self, "labels", labels)
+        object.__setattr__(self, "units", units)
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+
+    # ── Construction ──────────────────────────────────────────────────────
+    @classmethod
+    def create(
+        cls,
+        time: ArrayLike,
+        values: ArrayLike,
+        *,
+        labels: Sequence[str] | None = None,
+        units: Sequence[str] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> DataStruct:
+        """Mirror of MATLAB ``createDataStruct``. Accepts array-likes."""
+        return cls(
+            time=np.asarray(time, dtype=float),
+            values=np.asarray(values, dtype=float),
+            labels=tuple(labels) if labels is not None else (),
+            units=tuple(units) if units is not None else (),
+            metadata=dict(metadata) if metadata is not None else {},
+        )
+
+    # ── Shape helpers ─────────────────────────────────────────────────────
+    @property
+    def n_points(self) -> int:
+        return int(self.time.shape[0])
+
+    @property
+    def n_channels(self) -> int:
+        return int(self.values.shape[1])
+
+    def column(self, key: int | str) -> NDArray[np.float64]:
+        """Return one channel's data (read-only) by index or label."""
+        idx = key if isinstance(key, int) else self.labels.index(key)
+        return self.values[:, idx]
+
+    # ── Serialization (route boundary) ────────────────────────────────────
+    # NOTE: JSON here is Python-round-trippable (NaN/Inf survive via the
+    # stdlib json's non-standard tokens). The HTTP boundary (M1 #5) will map
+    # non-finite floats to null for valid wire JSON — that's a routes concern.
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "time": self.time.tolist(),
+            "values": self.values.tolist(),
+            "labels": list(self.labels),
+            "units": list(self.units),
+            "metadata": dict(self.metadata),
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> DataStruct:
+        return cls.create(
+            time=payload["time"],
+            values=payload["values"],
+            labels=payload.get("labels"),
+            units=payload.get("units"),
+            metadata=payload.get("metadata"),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, text: str) -> DataStruct:
+        return cls.from_dict(json.loads(text))

quantized/io/__init__.py

@@ -0,0 +1,11 @@
+"""Pure I/O library: parsers, the single registry, export writers, session I/O.
+
+Pure layer — MUST NOT import fastapi / pydantic / starlette / quantized.routes
+(enforced by tests/test_repo_integrity.py). Data in → DataStruct out.
+"""
+
+from __future__ import annotations
+
+from quantized.io.registry import import_auto, resolve_parser
+
+__all__ = ["import_auto", "resolve_parser"]

quantized/io/_hdf5_layout.py

@@ -0,0 +1,308 @@
+"""Tree-building helpers for the HDF5 exporter (:mod:`quantized.io.hdf5`).
+
+Split out of ``hdf5.py`` to keep both modules under the 500-line ceiling and
+to make the tree-shaping logic independently testable. Pure layer: ndarray /
+``DataStruct`` / ``h5py`` group in -> datasets/attributes written. No
+fastapi/pydantic imports.
+
+Schema (mirrors MATLAB ``+utilities/exportHDF5.m`` v1.0)::
+
+    /file_schema_version          uint8 [1,1] = 1   (root sentinel)
+    /  (root attrs)               toolboxName, hdf5Schema, createdAt,
+                                  hasCorrected, hasPeaks, correctionsApplied
+    /raw/                         time, values, labels, units, nRows (+attrs)
+    /corrected/                   (optional, same layout as /raw/)
+    /corrections/                 xOff, yOff, bgSlope, bgInt (double scalars)
+    /peaks/                       count, center, fwhm, height, bg,
+                                  xRange_lo, xRange_hi, status, model
+    /metadata/                    schema_version (+ common attrs)
+    /metadata/parserSpecific/     schema_version (+ flattened struct attrs)
+
+String datasets (labels, units, datetime time, peak status/model) are written
+as space-padded ASCII ``uint8`` matrices, one string per row, exactly like the
+MATLAB original; the companion ``encoding`` attribute documents the format.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+if TYPE_CHECKING:  # pragma: no cover - h5py only needed at write time
+    import h5py
+
+__all__ = [
+    "CORRECTION_FIELDS",
+    "META_COMMON_KEYS",
+    "PEAK_NUMERIC_FIELDS",
+    "encode_padded_ascii",
+    "first_meta",
+    "write_corrections_group",
+    "write_data_group",
+    "write_metadata_group",
+    "write_peaks_group",
+    "write_struct_attrs",
+]
+
+# MATLAB writes exactly these four correction scalars, in this order, always
+# defaulting absent ones to 0.0 (see exportHDF5.m corrFieldNames).
+CORRECTION_FIELDS: tuple[str, ...] = ("xOff", "yOff", "bgSlope", "bgInt")
+
+# Common /metadata attributes, mapped MATLAB-attr-name -> candidate metadata
+# keys (quantized snake_case first, then MATLAB camelCase, mirroring xrd_csv).
+META_COMMON_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("parserName", ("parser_name", "parserName")),
+    ("xColumnName", ("x_column_name", "xColumnName")),
+    ("xColumnUnit", ("x_column_unit", "xColumnUnit")),
+    ("source", ("source", "sourceFile")),
+)
+
+# Peak numeric fields written as parallel [P,1] double vectors (NaN fallback).
+PEAK_NUMERIC_FIELDS: tuple[str, ...] = ("center", "fwhm", "height", "bg")
+
+
+def first_meta(meta: Mapping[str, Any], keys: Sequence[str]) -> Any:
+    """First present, non-empty value among ``keys`` (or ``None``).
+
+    Mirrors the dual-provenance lookup in ``xrd_csv._meta_get`` (accepts both
+    quantized snake_case and MATLAB camelCase keys, plus a nested
+    ``parser_specific`` / ``parserSpecific`` mapping).
+    """
+    sources: list[Mapping[str, Any]] = [meta]
+    for nested_key in ("parser_specific", "parserSpecific"):
+        nested = meta.get(nested_key)
+        if isinstance(nested, Mapping):
+            sources.append(nested)
+    for src in sources:
+        for key in keys:
+            if key in src:
+                val = src[key]
+                if val is None or (isinstance(val, str) and val == ""):
+                    continue
+                return val
+    return None
+
+
+def encode_padded_ascii(strings: Sequence[str]) -> NDArray[np.uint8]:
+    """Encode ``strings`` as an ``[M, maxLen]`` space-padded ASCII uint8 matrix.
+
+    One string per row, right-padded with ASCII space (0x20). An empty input
+    becomes a single empty row (``[1, 1]`` of spaces), matching MATLAB's
+    ``writeCellStrDataset`` (which substitutes ``{''}`` for an empty cell and a
+    minimum column count of 1). Non-ASCII codepoints are replaced (``?``) so
+    each character maps to exactly one byte, matching MATLAB ``uint8(char)``
+    behaviour for ASCII labels.
+    """
+    rows = [str(s) for s in strings]
+    if not rows:
+        rows = [""]
+    encoded = [r.encode("ascii", errors="replace") for r in rows]
+    max_len = max((len(b) for b in encoded), default=1)
+    max_len = max(max_len, 1)
+    mat = np.full((len(encoded), max_len), ord(" "), dtype=np.uint8)
+    for i, b in enumerate(encoded):
+        if b:
+            mat[i, : len(b)] = np.frombuffer(b, dtype=np.uint8)
+    return mat
+
+
+def _write_padded_ascii(
+    group: h5py.Group,
+    name: str,
+    strings: Sequence[str],
+    *,
+    count_attr: bool = True,
+) -> None:
+    """Create a padded-ASCII dataset + ``encoding`` (and optional ``count``)."""
+    mat = encode_padded_ascii(strings)
+    dset = group.create_dataset(name, data=mat)
+    dset.attrs["encoding"] = "ASCII_padded_space"
+    if count_attr:
+        dset.attrs["count"] = np.int32(len(strings) if strings else 1)
+
+
+def write_data_group(parent: h5py.Group, group_path: str, d: DataStruct) -> None:
+    """Write ``time``, ``values``, ``labels``, ``units`` (+attrs) under a group.
+
+    ``group_path`` is relative to ``parent`` (e.g. ``"raw"`` or ``"corrected"``).
+    quantized's ``DataStruct.time`` is always numeric float64 (datetime axes are
+    converted to epoch seconds on import), so ``timeIsDatetime`` is always 0
+    here — the datetime branch in MATLAB has no quantized analogue.
+    """
+    grp = parent.require_group(group_path)
+    n = int(d.time.shape[0])
+    m = int(d.values.shape[1])
+
+    grp.create_dataset("time", data=d.time.astype(np.float64).reshape(n, 1))
+    grp["time"].attrs["timeIsDatetime"] = np.uint8(0)
+
+    grp.create_dataset("values", data=d.values.astype(np.float64).reshape(n, m))
+
+    _write_padded_ascii(grp, "labels", list(d.labels))
+    _write_padded_ascii(grp, "units", list(d.units))
+
+    # nRows sentinel dataset (carries group attrs in the MATLAB original).
+    grp.create_dataset("nRows", data=np.int32(n).reshape(1, 1))
+    grp.attrs["nChannels"] = np.int32(m)
+    grp.attrs["timeIsDatetime"] = np.uint8(0)
+
+
+def write_corrections_group(
+    parent: h5py.Group, corrections: Mapping[str, float]
+) -> None:
+    """Write the four correction scalars as ``[1,1]`` double datasets."""
+    grp = parent.require_group("corrections")
+    for field in CORRECTION_FIELDS:
+        val = float(corrections.get(field, 0.0))
+        grp.create_dataset(field, data=np.float64(val).reshape(1, 1))
+
+
+def write_peaks_group(parent: h5py.Group, peaks: Sequence[Mapping[str, Any]]) -> None:
+    """Write parallel peak datasets into ``/peaks/`` (mirrors MATLAB)."""
+    grp = parent.require_group("peaks")
+    p = len(peaks)
+    grp.create_dataset("count", data=np.uint32(p).reshape(1, 1))
+
+    for field in PEAK_NUMERIC_FIELDS:
+        vec = np.array([_safe_num(pk.get(field)) for pk in peaks], dtype=np.float64)
+        grp.create_dataset(field, data=vec.reshape(p, 1))
+
+    x_lo = np.full(p, np.nan)
+    x_hi = np.full(p, np.nan)
+    for i, pk in enumerate(peaks):
+        xr = pk.get("xRange", pk.get("x_range"))
+        if xr is not None and len(xr) == 2:
+            x_lo[i] = float(xr[0])
+            x_hi[i] = float(xr[1])
+    grp.create_dataset("xRange_lo", data=x_lo.reshape(p, 1))
+    grp.create_dataset("xRange_hi", data=x_hi.reshape(p, 1))
+
+    status = [_safe_str(pk.get("status"), "unknown") for pk in peaks]
+    model = [_safe_str(pk.get("model"), "") for pk in peaks]
+    _write_padded_ascii(grp, "status", status)
+    _write_padded_ascii(grp, "model", model)
+
+
+def write_metadata_group(parent: h5py.Group, meta: Mapping[str, Any]) -> None:
+    """Write common ``/metadata`` attrs and the ``parserSpecific`` sub-group."""
+    grp = parent.require_group("metadata")
+    grp.create_dataset("schema_version", data=np.uint8(1).reshape(1, 1))
+
+    for attr_name, keys in META_COMMON_KEYS:
+        val = first_meta(meta, keys)
+        grp.attrs[attr_name] = "" if val is None else str(val)
+
+    # quantized time axis is always numeric.
+    grp.attrs["timeIsDatetime"] = np.uint8(0)
+
+    import_date = first_meta(meta, ("import_date", "importDate"))
+    if import_date is not None:
+        grp.attrs["importDate"] = str(import_date)
+
+    parser_specific = _parser_specific(meta)
+    if parser_specific is not None:
+        ps = grp.require_group("parserSpecific")
+        ps.create_dataset("schema_version", data=np.uint8(1).reshape(1, 1))
+        write_struct_attrs(ps, parser_specific, "")
+
+
+def write_struct_attrs(
+    group: h5py.Group, mapping: Mapping[str, Any], prefix: str
+) -> None:
+    """Flatten ``mapping`` into HDF5 attributes (port of ``writeStructAttrs``).
+
+    Scalars -> numeric attr; NaN -> ``"NaN"``; short numeric vectors -> array
+    attr; str/bool/None handled; one level of nested-dict flattening with an
+    ``<field>_`` prefix; lists of strings joined with ``|`` (+ ``__delim``);
+    anything else records ``<name>__type``.
+    """
+    for field, val in mapping.items():
+        attr_name = f"{prefix}{field}"
+        if isinstance(val, bool):
+            group.attrs[attr_name] = np.uint8(val)
+        elif isinstance(val, (int, float, np.integer, np.floating)):
+            fval = float(val)
+            group.attrs[attr_name] = "NaN" if np.isnan(fval) else fval
+        elif isinstance(val, str):
+            group.attrs[attr_name] = val
+        elif val is None:
+            group.attrs[f"{attr_name}__type"] = "NoneType"
+        elif isinstance(val, Mapping) and not prefix:
+            write_struct_attrs(group, val, f"{field}_")
+        elif _is_str_list(val):
+            items = [str(x) for x in val]
+            if 0 < len(items) <= 128:
+                group.attrs[attr_name] = "|".join(items)
+                group.attrs[f"{attr_name}__delim"] = "|"
+            else:
+                group.attrs[f"{attr_name}__type"] = "cell"
+        elif _is_num_vector(val):
+            arr = np.asarray(val, dtype=np.float64).ravel()
+            if 1 < arr.size <= 64:
+                group.attrs[attr_name] = arr
+            else:
+                group.attrs[f"{attr_name}__type"] = "double"
+        else:
+            group.attrs[f"{attr_name}__type"] = type(val).__name__
+
+
+# ── small value helpers ─────────────────────────────────────────────────────
+
+
+def _parser_specific(meta: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    """Return the parserSpecific mapping.
+
+    quantized parsers keep instrument-specific fields flat in ``metadata``
+    (alongside the common keys) rather than nested. To mirror the MATLAB
+    ``/metadata/parserSpecific`` group we take an explicit nested mapping when
+    present, else the leftover flat keys (everything not a recognised common
+    key).
+    """
+    for key in ("parser_specific", "parserSpecific"):
+        nested = meta.get(key)
+        if isinstance(nested, Mapping):
+            return nested
+    common = {k for _, keys in META_COMMON_KEYS for k in keys}
+    common |= {"import_date", "importDate", "parser_specific", "parserSpecific"}
+    leftover = {k: v for k, v in meta.items() if k not in common}
+    return leftover or None
+
+
+def _safe_num(val: Any) -> float:
+    if val is None:
+        return float("nan")
+    try:
+        if hasattr(val, "__len__") and not isinstance(val, str):
+            return float(val[0]) if len(val) else float("nan")
+        return float(val)
+    except (TypeError, ValueError):
+        return float("nan")
+
+
+def _safe_str(val: Any, default: str) -> str:
+    if val is None or (isinstance(val, str) and val == ""):
+        return default
+    return str(val)
+
+
+def _is_str_list(val: Any) -> bool:
+    return (
+        isinstance(val, (list, tuple))
+        and len(val) > 0
+        and all(isinstance(x, str) for x in val)
+    )
+
+
+def _is_num_vector(val: Any) -> bool:
+    if not isinstance(val, (list, tuple, np.ndarray)):
+        return False
+    try:
+        arr = np.asarray(val, dtype=np.float64)
+    except (TypeError, ValueError):
+        return False
+    return arr.ndim == 1 and arr.size > 0