quantized-lab 0.8.0__py3-none-any.whl

quantized/io/_jcamp_asdf.py

@@ -0,0 +1,135 @@
+"""JCAMP-DX ASDF ordinate decoder for ``(X++(Y..Y))`` XYDATA.
+
+ASDF (ASCII Squeezed Difference Form) packs ordinates with four schemes:
+
+* **AFFN / PAC** — plain signed numbers (space- or ``+``/``-``-separated).
+* **SQZ** (squeezed) — the leading digit carries the sign as a letter
+  (``@``=+0, ``A``-``I``=+1..+9, ``a``-``i``=-1..-9); an *absolute* value.
+* **DIF** (difference) — leading letter (``%``=0, ``J``-``R``=+1..+9,
+  ``j``-``r``=-1..-9) encodes the *difference* from the previous ordinate.
+* **DUP** (duplicate) — ``S``-``Z``,``s`` = 1..9 repeat the previous token that
+  many times *total* (so ``count-1`` additional copies); after a DIF token the
+  difference is re-applied, after an absolute the value is repeated.
+
+Cross-line rule: in DIF mode each continuation line's first ordinate repeats
+the previous line's last value as a **Y-value check** — it is verified and
+dropped (the line's abscissa also leads each line and is discarded, since X is
+reconstructed from FIRSTX/LASTX).
+
+Algorithm adapted from the JCAMP-DX standard (McDonald & Wilks, 1988) and the
+MIT-licensed ``nzhagen/jcamp`` reference; re-implemented here.
+"""
+
+from __future__ import annotations
+
+__all__ = ["DifCheckError", "decode_xydata"]
+
+_SQZ = {"@": 0, "A": 1, "B": 2, "C": 3, "D": 4, "E": 5, "F": 6, "G": 7, "H": 8, "I": 9,
+        "a": -1, "b": -2, "c": -3, "d": -4, "e": -5, "f": -6, "g": -7, "h": -8, "i": -9}
+_DIF = {"%": 0, "J": 1, "K": 2, "L": 3, "M": 4, "N": 5, "O": 6, "P": 7, "Q": 8, "R": 9,
+        "j": -1, "k": -2, "l": -3, "m": -4, "n": -5, "o": -6, "p": -7, "q": -8, "r": -9}
+_DUP = {"S": 1, "T": 2, "U": 3, "V": 4, "W": 5, "X": 6, "Y": 7, "Z": 8, "s": 9}
+
+# Token modes.
+_ABS, _DIFF, _DUPL = "ABS", "DIF", "DUP"
+
+
+class DifCheckError(ValueError):
+    """A DIF Y-value check failed (a line's leading value != previous last)."""
+
+
+def _tokenize(line: str) -> list[tuple[str, float]]:
+    """Split one data line into ``(mode, value)`` tokens (X first, then Y's).
+
+    A new token starts at a sign, a SQZ/DIF/DUP letter, or after a delimiter.
+    Digits, ``.`` and exponent chars extend a plain number.
+    """
+    tokens: list[tuple[str, float]] = []
+    cur = ""
+    cur_letter = ""  # the SQZ/DIF/DUP letter that opened `cur`, if any
+
+    def flush() -> None:
+        nonlocal cur, cur_letter
+        if cur == "" and cur_letter == "":
+            return
+        if cur_letter in _SQZ:
+            tokens.append((_ABS, float(f"{_SQZ[cur_letter]}{cur}")))
+        elif cur_letter in _DIF:
+            tokens.append((_DIFF, float(f"{_DIF[cur_letter]}{cur}")))
+        elif cur_letter in _DUP:
+            tokens.append((_DUPL, float(int(f"{_DUP[cur_letter]}{cur}"))))
+        elif cur not in ("", "+", "-"):
+            tokens.append((_ABS, float(cur)))
+        cur, cur_letter = "", ""
+
+    for ch in line:
+        if ch in " \t,":
+            flush()
+        elif ch in _SQZ or ch in _DIF or ch in _DUP:
+            flush()
+            cur_letter = ch
+        elif ch in "+-" and cur[-1:] not in ("e", "E"):
+            flush()
+            cur = ch
+        elif ch.isdigit() or ch in ".eE":
+            cur += ch
+        # any other char (stray) ends the current token
+        elif ch:
+            flush()
+    flush()
+    return tokens
+
+
+def decode_xydata(
+    data_lines: list[str], *, ycheck: bool = True, ytol: float = 1e-6
+) -> list[float]:
+    """Decode ASDF ``(X++(Y..Y))`` lines into a flat list of raw ordinates.
+
+    Parameters
+    ----------
+    ycheck
+        Verify DIF-mode Y-value checks; raise :class:`DifCheckError` on mismatch.
+    ytol
+        Absolute tolerance for the Y-value check (raw ordinate units).
+    """
+    y: list[float] = []
+    last = 0.0
+    prev_mode, prev_val = _ABS, 0.0
+    prev_line_dif = False  # did the previous line end in DIF mode?
+
+    for li, line in enumerate(data_lines):
+        toks = _tokenize(line)
+        if not toks:
+            continue
+        ords = toks[1:]  # first token is the abscissa (X) -> discard
+        line_dif = False
+        first = True
+        for mode, val in ords:
+            if mode == _DUPL:
+                for _ in range(int(val) - 1):
+                    if prev_mode == _DIFF:
+                        last += prev_val
+                        line_dif = True
+                    else:
+                        last = prev_val
+                    y.append(last)
+                continue
+            if mode == _DIFF:
+                last += val
+                y.append(last)
+                prev_mode, prev_val, line_dif = _DIFF, val, True
+            else:  # absolute (SQZ / AFFN / PAC)
+                if first and li > 0 and prev_line_dif:
+                    # continuation Y-check: must equal the running last value
+                    if ycheck and abs(val - last) > ytol:
+                        raise DifCheckError(
+                            f"line {li + 1}: Y-check {val} != previous last {last}"
+                        )
+                    prev_mode, prev_val = _ABS, val
+                else:
+                    last = val
+                    y.append(last)
+                    prev_mode, prev_val = _ABS, val
+            first = False
+        prev_line_dif = line_dif
+    return y

quantized/io/_xrdml_scan.py

@@ -0,0 +1,291 @@
+"""XRDML per-scan model + generalized (cloud) 2-D assembly.
+
+Split out of ``io/xrdml.py`` (500-line module ceiling). ``_Scan`` is the
+per-scan record collected during the parse; ``_classify_cloud`` /
+``_build_2d_cloud`` implement the snapshot/coupled RSM layouts that go
+beyond the MATLAB-compatible mesh (see the ``io/xrdml`` module docstring);
+``_classify_pole`` / ``_build_pole`` implement the pole-figure layout
+(gap #46 residual).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.calc.qspace import compute_qspace
+from quantized.datastruct import DataStruct
+
+_SECONDARY_AXES = ("Omega", "Chi", "Phi")
+# Tilt-axis element names PANalytical schemas use for pole-figure cradles:
+# "Psi" on texture-goniometer (Eulerian/chi-less) cradles, "Chi" on older
+# Eulerian cradles. Checked in this order; either satisfies _classify_pole.
+_TILT_AXES = ("Psi", "Chi")
+
+class _Scan:
+    """Per-scan data collected during the parse (1D concat + 2D classification)."""
+
+    __slots__ = ("tt_range", "tt_list", "counts", "sec_value", "sec_ranges")
+
+    def __init__(
+        self,
+        tt_range: tuple[float, float],
+        tt_list: NDArray[np.float64] | None,
+        counts: NDArray[np.float64],
+        sec_value: float,
+        sec_ranges: dict[str, tuple[float, float]],
+    ) -> None:
+        self.tt_range = tt_range
+        self.tt_list = tt_list
+        self.counts = counts
+        self.sec_value = sec_value
+        # (start, end) per present secondary axis — start == end means the
+        # axis was held fixed for this scan.
+        self.sec_ranges = sec_ranges
+
+    def two_theta(self) -> NDArray[np.float64]:
+        """This scan's per-pixel 2theta vector (listPositions or linspace)."""
+        if self.tt_list is not None and self.tt_list.size == self.counts.size:
+            return self.tt_list
+        return np.linspace(self.tt_range[0], self.tt_range[1], self.counts.size)
+
+    def axis_vector(self, axis: str) -> NDArray[np.float64]:
+        """The secondary axis as a per-pixel vector: constant when fixed,
+        linspace(start, end) when the axis moved during the scan (coupled)."""
+        start, end = self.sec_ranges[axis]
+        if start == end:
+            return np.full(self.counts.size, start)
+        return np.linspace(start, end, self.counts.size)
+
+
+def _classify_cloud(scans: list[_Scan]) -> tuple[str, str] | None:
+    """Generalized 2-D detection BEYOND the MATLAB-compatible mesh (`_is_2d`).
+
+    Returns ``(axis, kind)`` or ``None``. Tried only after `_is_2d` fails, so
+    reaching the snapshot branch implies the per-scan 2theta windows differ.
+    Requires >= 3 scans (a 2-range 1-D file must never classify as a map).
+
+    - ``snapshot``: an axis held fixed within EVERY scan whose value varies
+      across scans (PIXcel3D "Scanning snapshot": omega fixed per frame while
+      both omega and the 2theta window step frame-to-frame).
+    - ``coupled``: all scans share one 2theta window while an axis sweeps
+      WITHIN each scan (start != end) at a stepped offset across scans
+      (schema-1.0 Omega-2Theta RSMs — a sheared mesh).
+    """
+    if len(scans) < 3:
+        return None
+    for axis in _SECONDARY_AXES:
+        ranges = [s.sec_ranges.get(axis) for s in scans]
+        if any(r is None for r in ranges):
+            continue
+        rr = [r for r in ranges if r is not None]  # narrow for the type checker
+        if all(r[0] == r[1] for r in rr):
+            vals = [r[0] for r in rr]
+            if max(vals) - min(vals) > 1e-6:
+                return axis, "snapshot"
+    s0, e0 = scans[0].tt_range
+    tt_same = all(
+        abs(s.tt_range[0] - s0) < 1e-4 and abs(s.tt_range[1] - e0) < 1e-4 for s in scans
+    )
+    if tt_same:
+        for axis in _SECONDARY_AXES:
+            ranges = [s.sec_ranges.get(axis) for s in scans]
+            if any(r is None for r in ranges):
+                continue
+            rr = [r for r in ranges if r is not None]
+            if all(r[0] != r[1] for r in rr):
+                mids = [0.5 * (r[0] + r[1]) for r in rr]
+                if max(mids) - min(mids) > 1e-6:
+                    return axis, "coupled"
+    return None
+
+
+def _classify_pole(scans: list[_Scan]) -> tuple[str, float] | None:
+    """Detect a PANalytical pole-figure layout.
+
+    A pole figure holds 2Theta fixed at the Bragg condition for one
+    reflection, sweeps Phi (azimuthal, typically ~360 deg) WITHIN every
+    scan, and steps a tilt axis -- "Psi" (texture cradles) or "Chi" (older
+    Eulerian cradles) -- fixed within each scan but varying ACROSS scans.
+
+    Returns ``(tilt_axis, two_theta_deg)`` or ``None``. Must run BEFORE
+    ``_is_2d``/``_classify_cloud``: a Chi-named tilt axis alone already
+    satisfies the generic ``snapshot`` cloud pattern (fixed-per-scan,
+    varying across scans) and would silently classify as a mesh/snapshot
+    RSM while dropping the Phi sweep entirely; a Psi-named one is invisible
+    to both classifiers (Psi is not one of the axes they inspect), so it
+    would otherwise fall through to the flat 1-D path.
+    """
+    if len(scans) < 2:
+        return None
+    s0, e0 = scans[0].tt_range
+    if abs(s0 - e0) > 1e-6:
+        return None  # 2Theta itself sweeps -> not a fixed-reflection pole figure
+    tt_same = all(
+        abs(s.tt_range[0] - s0) < 1e-4 and abs(s.tt_range[1] - e0) < 1e-4 for s in scans
+    )
+    if not tt_same:
+        return None
+
+    phi_ranges = [s.sec_ranges.get("Phi") for s in scans]
+    if any(r is None for r in phi_ranges):
+        return None
+    phi_rr = [r for r in phi_ranges if r is not None]
+    if not all(r[0] != r[1] for r in phi_rr):
+        return None  # Phi must sweep WITHIN every scan
+
+    for tilt_axis in _TILT_AXES:
+        ranges = [s.sec_ranges.get(tilt_axis) for s in scans]
+        if any(r is None for r in ranges):
+            continue
+        rr = [r for r in ranges if r is not None]
+        if not all(r[0] == r[1] for r in rr):
+            continue  # tilt axis must be fixed WITHIN every scan
+        vals = [r[0] for r in rr]
+        if max(vals) - min(vals) > 1e-6:  # and step ACROSS scans
+            return tilt_axis, s0
+    return None
+
+
+def _build_pole(
+    scans: list[_Scan],
+    tilt_axis: str,
+    two_theta_deg: float,
+    path: Path,
+    intensity: str,
+    counting_time: float,
+    intensity_tag: str,
+    att: dict[str, Any],
+) -> DataStruct:
+    """Assemble a pole-figure point cloud: per-point (Phi, Psi, Intensity).
+
+    Every scan is an azimuthal Phi sweep at one fixed tilt. Unlike the RSM
+    mesh/cloud kinds, 2Theta does not vary point-to-point here -- it is the
+    single Bragg condition for the whole measurement, so it is recorded as
+    scalar metadata (``two_theta_deg``) rather than a column. The tilt axis
+    is normalized to the "Psi" label in the output regardless of whether
+    the source XML called it "Psi" or "Chi" (``tilt_axis_source`` keeps the
+    original element name), so downstream code has one consistent name.
+    Stereographic/polar projection is a later view (ORIGIN_GAP_PLAN #46) --
+    this is the flat psi x phi map that feeds it.
+    """
+    order = sorted(range(len(scans)), key=lambda i: scans[i].sec_ranges[tilt_axis][0])
+    phi = np.concatenate([scans[i].axis_vector("Phi") for i in order])
+    psi = np.concatenate(
+        [np.full(scans[i].counts.size, scans[i].sec_ranges[tilt_axis][0]) for i in order]
+    )
+    counts = np.concatenate([scans[i].counts for i in order])
+
+    vals, unit = _apply_intensity(counts, intensity, counting_time)
+    values = np.column_stack([phi, psi, np.asarray(vals, dtype=float)])
+    labels = ["Phi", "Psi", "Intensity"]
+    units = ["deg", "deg", unit]
+
+    pix_counts = {s.counts.size for s in scans}
+    n_pix = pix_counts.pop() if len(pix_counts) == 1 else None
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_xrdml",
+        "x_column_name": "Phi",
+        "x_column_unit": "deg",
+        "num_points": int(values.shape[0]),
+        "counting_time": counting_time,
+        "intensity_tag": intensity_tag,
+        "is2D": True,
+        "mesh_kind": "pole",
+        # Index grid (frames x pixels) only when every scan has the same
+        # Phi-sample count; None = ragged (rare, but no reason to require it).
+        "map_shape": [len(scans), int(n_pix)] if n_pix is not None else None,
+        "axis1_name": "Psi",
+        "axis2_name": "Phi",
+        "two_theta_deg": float(two_theta_deg),
+        "tilt_axis_source": tilt_axis,
+    }
+    metadata.update(att)
+    return DataStruct.create(
+        np.arange(values.shape[0], dtype=float),
+        values,
+        labels=labels,
+        units=units,
+        metadata=metadata,
+    )
+
+
+def _build_2d_cloud(
+    scans: list[_Scan],
+    sec_name: str,
+    mesh_kind: str,
+    path: Path,
+    intensity: str,
+    counting_time: float,
+    wavelength: float,
+    intensity_tag: str,
+    att: dict[str, Any],
+) -> DataStruct:
+    """Assemble a generalized RSM point cloud (snapshot / coupled layouts).
+
+    Unlike `_build_2d` there is no shared 2theta vector: every scan contributes
+    its own per-pixel 2theta (and, for coupled scans, per-pixel omega), so the
+    output is a true scattered cloud. Same column schema as the mesh path.
+    """
+
+    def _mid(s: _Scan) -> float:
+        r = s.sec_ranges[sec_name]
+        return 0.5 * (r[0] + r[1])
+
+    order = sorted(range(len(scans)), key=lambda i: _mid(scans[i]))
+    tt = np.concatenate([scans[i].two_theta() for i in order])
+    sec = np.concatenate([scans[i].axis_vector(sec_name) for i in order])
+    counts = np.concatenate([scans[i].counts for i in order])
+
+    vals, unit = _apply_intensity(counts, intensity, counting_time)
+    columns = [tt, sec, np.asarray(vals, dtype=float)]
+    labels = ["2Theta", sec_name, "Intensity"]
+    units = ["deg", "deg", unit]
+    if sec_name == "Omega" and np.isfinite(wavelength) and wavelength > 0:
+        qx, qz = compute_qspace(tt, sec, wavelength)
+        columns += [np.asarray(qx, dtype=float).ravel(), np.asarray(qz, dtype=float).ravel()]
+        labels += ["Qx", "Qz"]
+        units += ["Ang^-1", "Ang^-1"]
+
+    pix_counts = {s.counts.size for s in scans}
+    n_pix = pix_counts.pop() if len(pix_counts) == 1 else None
+    values = np.column_stack(columns)
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_xrdml",
+        "x_column_name": "2-Theta",
+        "x_column_unit": "deg",
+        "num_points": int(values.shape[0]),
+        "counting_time": counting_time,
+        "intensity_tag": intensity_tag,
+        "is2D": True,
+        "mesh_kind": mesh_kind,
+        # Index grid (frames x pixels) only when every frame has the same
+        # pixel count; None = ragged cloud (grid cuts unavailable, scattered
+        # rendering + segment cuts still work).
+        "map_shape": [len(scans), int(n_pix)] if n_pix is not None else None,
+        "axis1_name": sec_name,
+        "axis2_name": "2Theta",
+        "wavelength_a": float(wavelength) if np.isfinite(wavelength) else None,
+    }
+    metadata.update(att)
+    return DataStruct.create(
+        np.arange(values.shape[0], dtype=float),
+        values,
+        labels=labels,
+        units=units,
+        metadata=metadata,
+    )
+
+
+def _apply_intensity(
+    counts: NDArray[np.float64], intensity: str, counting_time: float
+) -> tuple[NDArray[np.float64], str]:
+    """counts -> (cps or counts, unit). cps needs a positive counting time."""
+    if intensity == "cps" and not np.isnan(counting_time) and counting_time > 0:
+        return np.asarray(counts / counting_time, dtype=float), "cps"
+    return counts, "counts"

quantized/io/base.py

@@ -0,0 +1,82 @@
+"""Shared, pure parsing primitives used across io/ parsers.
+
+Ports of the MATLAB helpers parseColHeader + resolveColumnShorthand.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+
+__all__ = ["NO_COLUMN", "parse_col_header", "resolve_column"]
+
+NO_COLUMN = -1
+
+_HEADER_UNIT_RE = re.compile(r"^(.+?)\s*\(([^)]+)\)\s*$")
+
+
+def parse_col_header(raw: str) -> tuple[str, str]:
+    """Split ``'Magnetic Field (Oe)'`` -> ``('Magnetic Field', 'Oe')``.
+
+    No parenthesised unit -> ``(trimmed name, '')``. Mirrors parseColHeader.
+    """
+    name = raw.strip()
+    if not name:
+        return "", ""
+    match = _HEADER_UNIT_RE.match(name)
+    if match:
+        return match.group(1).strip(), match.group(2).strip()
+    return name, ""
+
+
+def _match_column(needle: str, col_names: Sequence[str]) -> int | None:
+    """Exact (case-insensitive) match, else partial; shortest matching name wins."""
+    lowered = needle.lower()
+    for i, name in enumerate(col_names):
+        if name.lower() == lowered:
+            return i
+    matches = [i for i, name in enumerate(col_names) if lowered in name.lower()]
+    if not matches:
+        return None
+    return min(matches, key=lambda i: len(col_names[i]))
+
+
+def resolve_column(
+    spec: int | str,
+    col_names: Sequence[str],
+    shorthand_map: Mapping[str, str] | None = None,
+    label: str = "column",
+) -> int:
+    """Resolve a column spec to a 0-based index (mirrors resolveColumnShorthand).
+
+    Order: int index -> empty (``NO_COLUMN``) -> [shorthand target, then the
+    literal spec], each tried exact (ci) then partial (ci, shortest name wins)
+    -> ``KeyError``. The literal-spec fallback lets ``"field"`` resolve a column
+    named literally ``Field`` (MPMS-classic naming) when the shorthand target
+    ``"Magnetic Field"`` is absent.
+    """
+    if isinstance(spec, int):
+        if 0 <= spec < len(col_names):
+            return spec
+        raise IndexError(f"{label} index {spec} out of range (0-{len(col_names) - 1})")
+
+    needle = spec.strip()
+    if not needle:
+        return NO_COLUMN
+
+    # Try the shorthand target first (keeps current behaviour), then the literal
+    # spec as a fallback so non-canonical column names still resolve.
+    candidates: list[str] = []
+    if shorthand_map:
+        for short, target in shorthand_map.items():
+            if needle.lower() == short.lower():
+                candidates.append(target)
+                break
+    candidates.append(needle)
+
+    for cand in candidates:
+        hit = _match_column(cand, col_names)
+        if hit is not None:
+            return hit
+
+    raise KeyError(f"cannot resolve {label} '{spec}'. Available: {list(col_names)}")

quantized/io/bruker_brml.py

@@ -0,0 +1,177 @@
+"""Bruker ``.brml`` XRD parser (DIFFRAC.EVA / DIFFRAC.MEASUREMENT).
+
+A ``.brml`` is a ZIP archive of XML documents. The scan lives in
+``Experiment<i>/RawData<j>.xml``; a 1-D line scan has exactly one such file,
+while a reciprocal-space map (RSM) has one per scan line (hundreds).
+
+RawData structure (namespaces declared for ``xsi:type`` only; elements are
+un-prefixed, so ElementTree tags are plain)::
+
+    <RawData>
+      <DataRoutes><DataRoute RouteFlag="Measured">
+        <ScanInformation>
+          <MeasurementPoints>2001</MeasurementPoints>
+          <ScanAxes>
+            <ScanAxisInfo AxisId="TwoTheta" Unit="deg">
+              <Start>44</Start><Stop>48</Stop><Increment>0.002</Increment>
+        <Datum>plannedTime,measuredTime,TwoTheta,Theta,...,Counts</Datum>
+        ...
+
+Each ``<Datum>`` is a comma-separated row; the *first* scan axis (2theta) is
+the abscissa and the *last* field is the recorded counter (intensity). This
+parser handles the 1-D case (item #42); an RSM raises a clear error pointing
+at the map path rather than silently returning one line.
+
+Sample files ``FAIRmat_2thomega.brml`` / ``FAIRmat_RSM.brml`` (Apache-2.0,
+FAIRmat pynxtools-xrd corpus) seed the parity tests.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET  # noqa: S405 (matches io/xrdml.py; trusted local files)
+import zipfile
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["import_bruker_brml", "is_bruker_brml"]
+
+_UNIT_MAP = {"°": "deg", "deg": "deg", "Degree": "deg", "": ""}
+
+
+def _raw_data_members(names: list[str]) -> list[str]:
+    """ZIP members matching ``Experiment*/RawData*.xml`` (the scan documents)."""
+    out = []
+    for n in names:
+        parts = n.replace("\\", "/").split("/")
+        if len(parts) >= 2 and parts[-1].startswith("RawData") and parts[-1].endswith(".xml"):
+            out.append(n)
+    return out
+
+
+def is_bruker_brml(path: Path) -> bool:
+    """Sniff a file as a Bruker ``.brml`` (a ZIP with a RawData scan document)."""
+    p = Path(path)
+    if not zipfile.is_zipfile(p):
+        return False
+    with zipfile.ZipFile(p) as zf:
+        names = zf.namelist()
+    return any(n.endswith("experimentCollection.xml") for n in names) or bool(
+        _raw_data_members(names)
+    )
+
+
+def _first(elem: ET.Element | None, tag: str) -> ET.Element | None:
+    return None if elem is None else elem.find(tag)
+
+
+def _axis_range(axis: ET.Element) -> tuple[float, float]:
+    start = _first(axis, "Start")
+    stop = _first(axis, "Stop")
+    lo = float(start.text) if start is not None and start.text else float("nan")
+    hi = float(stop.text) if stop is not None and stop.text else float("nan")
+    return lo, hi
+
+
+def import_bruker_brml(filepath: str | Path) -> DataStruct:
+    """Import a 1-D Bruker ``.brml`` line scan (2theta vs intensity).
+
+    Returns
+    -------
+    DataStruct
+        ``time`` = the primary scan axis (typically 2theta, deg), one
+        ``Intensity`` channel (counts).
+
+    Raises
+    ------
+    ValueError
+        If the archive is not a ``.brml``, holds no scan, or is a multi-scan
+        RSM (which this 1-D parser does not stitch).
+    """
+    path = Path(filepath)
+    if not zipfile.is_zipfile(path):
+        raise ValueError(f"not a ZIP archive (expected a .brml): {path.name}")
+
+    with zipfile.ZipFile(path) as zf:
+        members = _raw_data_members(zf.namelist())
+        if not members:
+            raise ValueError(f"no RawData scan document in archive: {path.name}")
+        if len(members) > 1:
+            raise ValueError(
+                f"multi-scan .brml detected ({len(members)} scans) — reciprocal-space "
+                f"maps are not supported by the 1-D parser: {path.name}"
+            )
+        xml_text = zf.read(members[0]).decode("utf-8", "replace")
+
+    root = ET.fromstring(xml_text)  # noqa: S314 (trusted local file, matches xrdml)
+
+    routes = root.findall(".//DataRoute")
+    route = next((r for r in routes if r.get("RouteFlag") == "Measured"), None)
+    route = route if route is not None else (routes[0] if routes else None)
+    if route is None:
+        raise ValueError(f"no DataRoute in scan document: {path.name}")
+
+    scan_info = _first(route, "ScanInformation")
+    axes = scan_info.findall(".//ScanAxisInfo") if scan_info is not None else []
+    if not axes:
+        raise ValueError(f"no scan axis in scan document: {path.name}")
+    primary = axes[0]
+    axis_name = primary.get("VisibleName") or primary.get("AxisName") or "2-Theta"
+    axis_unit = _UNIT_MAP.get(primary.get("Unit", ""), primary.get("Unit", "") or "")
+    x_lo, x_hi = _axis_range(primary)
+
+    rows: list[list[float]] = []
+    for datum in route.findall(".//Datum"):
+        if not datum.text:
+            continue
+        try:
+            rows.append([float(v) for v in datum.text.split(",")])
+        except ValueError:
+            continue
+    if not rows:
+        raise ValueError(f"scan document has no data points: {path.name}")
+
+    n_cols = min(len(r) for r in rows)
+    data = np.array([r[:n_cols] for r in rows], dtype=float)
+
+    # The last column is the recorded counter (intensity). The abscissa is the
+    # column matching the primary axis Start->Stop range; fall back to
+    # reconstructing it from Start + i*Increment if no column matches.
+    intensity = data[:, -1]
+    x = _resolve_abscissa(data[:, :-1], x_lo, x_hi, primary, len(rows))
+
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_bruker_brml",
+        "x_column_name": axis_name,
+        "x_column_unit": axis_unit,
+        "num_points": len(rows),
+        "start_angle": x_lo,
+        "end_angle": x_hi,
+        "scan_axes": [a.get("VisibleName") or a.get("AxisName") for a in axes],
+    }
+    return DataStruct.create(
+        x, intensity, labels=["Intensity"], units=["counts"], metadata=metadata
+    )
+
+
+def _resolve_abscissa(
+    axis_cols: np.ndarray, x_lo: float, x_hi: float, primary: ET.Element, n: int
+) -> np.ndarray:
+    """Pick the Datum column that spans the primary axis range, else rebuild it."""
+    if axis_cols.size and np.isfinite(x_lo) and np.isfinite(x_hi):
+        # score each candidate column by how well its ends match Start/Stop
+        errs = np.abs(axis_cols[0, :] - x_lo) + np.abs(axis_cols[-1, :] - x_hi)
+        best = int(np.argmin(errs))
+        span = abs(x_hi - x_lo)
+        if errs[best] <= max(1e-6, 0.01 * span):
+            return np.asarray(axis_cols[:, best], dtype=float)
+    inc = _first(primary, "Increment")
+    if np.isfinite(x_lo) and inc is not None and inc.text:
+        return np.asarray(x_lo + np.arange(n) * float(inc.text), dtype=float)
+    if np.isfinite(x_lo) and np.isfinite(x_hi) and n > 1:
+        return np.asarray(np.linspace(x_lo, x_hi, n), dtype=float)
+    return np.asarray(axis_cols[:, 0] if axis_cols.size else np.arange(n), dtype=float)