quantized-lab 0.8.0__py3-none-any.whl

quantized/io/bruker_raw.py

@@ -0,0 +1,158 @@
+"""Bruker/Siemens Diffrac-AT ``.raw`` binary XRD parser, version "RAW1.01".
+
+Also known in ``xylib`` as "Bruker RAW ver. 3" (``bruker_raw.cpp``,
+``load_version1_01``). Fixed-layout little-endian binary produced by Siemens/
+Bruker D-series diffractometers (Diffrac-AT / DIFFRAC^plus).
+
+Byte layout (offsets 0-indexed, little-endian). Cross-checked against xylib's
+ASCII ``.UXD`` export of the same raw file::
+
+    File header (712 bytes):
+        0    8  bytes  magic  b'RAW1.01\\x00'
+        12   4  <I     range_cnt   (number of scan ranges)
+        608  4  ascii  anode_material
+        616  8  <d     alpha_average  (Ka average wavelength, A)
+        624  8  <d     alpha1
+        632  8  <d     alpha2
+
+    Per-range header (nominally 304 bytes, but read header_len):
+        0    4  <I     header_len   (== 304 for RAW1.01)
+        4    4  <I     steps        (number of data points)
+        16   8  <d     start_2theta (deg)
+        176  8  <d     step_size    (deg)
+        192  4  <f     time_per_step (s)
+        256  4  <I     supplementary_headers_size
+
+    Intensity data (per range):
+        starts at range_start + header_len + supplementary_headers_size
+        <steps>  float32  counts (stored as float even when integer)
+        next range (if any) starts immediately after: data_start + steps*4
+
+The supplementary-header block is variable (0 in some files, 40 in others), so
+``data_start`` must be computed from the file's own header_len + supp size, not
+a hardcoded 304 — a one-file test would miss this.
+
+Reference: xylib (github.com/wojdyr/xylib), ``bruker_raw.cpp``. Sample files
+``xylib_BT86.raw`` / ``xylib_Cu3Au.raw`` (LGPL-2.1, attribution) seed the
+parity tests.
+"""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["import_bruker_raw", "is_bruker_raw"]
+
+_FILE_HEADER_LEN = 712
+_RANGE_HEADER_LEN = 304
+_MAGIC = b"RAW1.01\x00"
+
+
+def is_bruker_raw(path: Path) -> bool:
+    """Sniff a ``.raw`` as Bruker RAW1.01 via its magic bytes.
+
+    Rigaku ``.raw`` uses magic ``FI``, so there is no collision. Other Bruker
+    versions (``RAW2``/``RAW4.00``) start with ``RAW`` too but are not the
+    RAW1.01 layout; this sniffer accepts only RAW1.01 so the registry does not
+    mis-route them.
+    """
+    with Path(path).open("rb") as fh:
+        return fh.read(8) == _MAGIC
+
+
+def import_bruker_raw(
+    filepath: str | Path,
+    *,
+    use_counts_per_sec: bool = False,
+    allow_partial: bool = False,
+) -> DataStruct:
+    """Import a Bruker RAW1.01 ``.raw`` (2theta vs intensity).
+
+    Parameters
+    ----------
+    use_counts_per_sec
+        Divide counts by ``time_per_step`` and label the channel ``counts/s``.
+    allow_partial
+        Multi-range files import range 0 only. Without this flag a multi-range
+        file raises (so the truncation is never silent); with it, range 0 is
+        returned and the extra ranges are recorded in metadata.
+
+    Returns
+    -------
+    DataStruct
+        ``time`` = 2theta (deg), one ``Intensity`` channel.
+    """
+    path = Path(filepath)
+    raw = path.read_bytes()
+    n_bytes = len(raw)
+    if n_bytes < _FILE_HEADER_LEN + _RANGE_HEADER_LEN:
+        raise ValueError(f"file too small to be a Bruker RAW1.01 ({n_bytes} bytes): {path.name}")
+    if raw[0:8] != _MAGIC:
+        raise ValueError(f"bad magic {raw[0:8]!r} (expected {_MAGIC!r}): {path.name}")
+
+    range_cnt = int(struct.unpack_from("<I", raw, 12)[0])
+    if range_cnt < 1:
+        raise ValueError(f"no scan ranges in file: {path.name}")
+
+    range_start = _FILE_HEADER_LEN
+    header_len = int(struct.unpack_from("<I", raw, range_start + 0)[0])
+    steps = int(struct.unpack_from("<I", raw, range_start + 4)[0])
+    start_2theta = float(struct.unpack_from("<d", raw, range_start + 16)[0])
+    step_size = float(struct.unpack_from("<d", raw, range_start + 176)[0])
+    time_per_step = float(struct.unpack_from("<f", raw, range_start + 192)[0])
+    supp_len = int(struct.unpack_from("<I", raw, range_start + 256)[0])
+
+    if header_len < _RANGE_HEADER_LEN:
+        raise ValueError(f"implausible range header length ({header_len}): {path.name}")
+    if steps < 1:
+        raise ValueError(f"range has no data points: {path.name}")
+    if step_size <= 0 or step_size > 10:
+        raise ValueError(f"implausible step size ({step_size:.6g} deg): {path.name}")
+
+    data_start = range_start + header_len + supp_len
+    if data_start + steps * 4 > n_bytes:
+        raise ValueError(
+            f"range claims {steps} points but only {(n_bytes - data_start) // 4} fit: {path.name}"
+        )
+
+    if range_cnt > 1 and not allow_partial:
+        raise ValueError(
+            f"multi-range .raw detected ({range_cnt} ranges); pass allow_partial=True "
+            f"to import the first range only: {path.name}"
+        )
+
+    intensities = np.frombuffer(raw, dtype="<f4", count=steps, offset=data_start).astype(float)
+    two_theta = start_2theta + np.arange(steps) * step_size
+
+    if use_counts_per_sec and time_per_step > 0:
+        values = intensities / time_per_step
+        unit = "counts/s"
+    else:
+        values = intensities
+        unit = "counts"
+
+    anode = raw[608:612].split(b"\x00", 1)[0].decode("ascii", "replace").strip()
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_bruker_raw",
+        "format_version": "RAW1.01",
+        "x_column_name": "2-Theta",
+        "x_column_unit": "deg",
+        "num_points": steps,
+        "start_angle": start_2theta,
+        "end_angle": float(two_theta[-1]),
+        "step_size": step_size,
+        "time_per_step": time_per_step,
+        "range_count": range_cnt,
+        "anode_material": anode,
+        "alpha_average": float(struct.unpack_from("<d", raw, 616)[0]),
+    }
+    return DataStruct.create(
+        two_theta, values, labels=["Intensity"], units=[unit], metadata=metadata
+    )

quantized/io/cif.py

@@ -0,0 +1,266 @@
+"""CIF (Crystallographic Information File) parser. Port of calc.importCIF.
+
+Returns a crystal-structure dict (not a DataStruct — a crystal structure is not a
+time/value series), so this parser is standalone and NOT registered in the
+DataStruct ``registry``. Pure io layer.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+__all__ = ["import_cif"]
+
+
+def _comment_pos(line: str) -> int:
+    """Index of the first '#' not inside a quoted string, or -1."""
+    in_single = in_double = False
+    for k, ch in enumerate(line):
+        if ch == "'" and not in_double:
+            in_single = not in_single
+        elif ch == '"' and not in_single:
+            in_double = not in_double
+        elif ch == "#" and not in_single and not in_double:
+            return k
+    return -1
+
+
+def _strip_uncertainty(s: str) -> float:
+    """'5.4309(2)' -> 5.4309, '3.905' -> 3.905, '?'/'.' -> NaN."""
+    s = s.strip()
+    if s in ("?", "."):
+        return float("nan")
+    s = re.sub(r"\([^)]*\)", "", s)
+    try:
+        return float(s)
+    except ValueError:
+        return float("nan")
+
+
+def _extract_single_value(token: str) -> str:
+    """Strip surrounding quotes; for unquoted, take the first whitespace token."""
+    token = token.strip()
+    if not token:
+        return ""
+    if token[0] == "'":
+        idx = token.rfind("'")
+        return token[1:idx] if idx > 0 else token[1:]
+    if token[0] == '"':
+        idx = token.rfind('"')
+        return token[1:idx] if idx > 0 else token[1:]
+    return token.split()[0]
+
+
+def _read_semicolon_block(lines: list[str], i: int, n: int) -> tuple[str, int]:
+    """Read a ';'-delimited multi-line text field. Returns (text, last_content_idx)."""
+    i += 1
+    parts: list[str] = []
+    while i < n:
+        if lines[i][:1] == ";":
+            break
+        parts.append(lines[i])
+        i += 1
+    return " ".join(parts).strip(), i - 1
+
+
+def _parse_tag_value(lines: list[str], i: int, n: int) -> tuple[str, str, int]:
+    """Parse a '_tag value' pair (value may be on the next line / a text block)."""
+    m = re.match(r"^(\S+)\s*(.*)", lines[i].strip())
+    if not m:
+        return lines[i].strip(), "", i
+    tag = m.group(1).strip().lower()
+    value = m.group(2).strip()
+    if not value:
+        if i + 1 < n:
+            next_line = lines[i + 1].strip()
+            if next_line and next_line[0] == ";":
+                value, i = _read_semicolon_block(lines, i + 1, n)
+            else:
+                i += 1
+                line2 = lines[i].strip()
+                cp = _comment_pos(line2)
+                if cp >= 0:
+                    line2 = line2[:cp].strip()
+                value = _extract_single_value(line2)
+    elif value[0] == ";":
+        value, i = _read_semicolon_block(lines, i, n)
+    else:
+        value = _extract_single_value(value)
+    return tag, value, i
+
+
+def _tokenise_cif_line(line: str) -> list[str]:
+    """Split a CIF data line into tokens, respecting single/double quotes."""
+    tokens: list[str] = []
+    n = len(line)
+    k = 0
+    while k < n:
+        ch = line[k]
+        if ch in (" ", "\t"):
+            k += 1
+            continue
+        if ch in ("'", '"'):
+            quote = ch
+            k += 1
+            start = k
+            while k < n and line[k] != quote:
+                k += 1
+            tokens.append(line[start:k])
+            k += 1
+        else:
+            start = k
+            while k < n and line[k] not in (" ", "\t"):
+                k += 1
+            tokens.append(line[start:k])
+    return tokens
+
+
+def _parse_loop(lines: list[str], i: int, n: int) -> tuple[dict[str, Any], int]:
+    """Parse a loop_ block: collect tag names then data tokens into rows."""
+    loop_tags: list[str] = []
+    while i < n:
+        line = lines[i].strip()
+        cp = _comment_pos(line)
+        if cp >= 0:
+            line = line[:cp].strip()
+        if not line:
+            i += 1
+            continue
+        if line[0] == "_":
+            loop_tags.append(line.strip().lower())
+            i += 1
+        else:
+            break
+
+    n_cols = len(loop_tags)
+    if n_cols == 0:
+        return {"tags": [], "data": []}, i
+
+    tokens: list[str] = []
+    while i < n:
+        line = lines[i]
+        cp = _comment_pos(line)
+        if cp >= 0:
+            line = line[:cp]
+        trimmed = line.strip()
+        if not trimmed:
+            i += 1
+            continue
+        first = trimmed.split()[0]
+        if first.lower() in ("loop_", "save_") or first[:5].lower() == "data_":
+            break
+        if first[0] == "_":
+            break
+        if trimmed[0] == ";":
+            block, i = _read_semicolon_block(lines, i, n)
+            tokens.append(block)
+            i += 1
+            continue
+        tokens.extend(_tokenise_cif_line(trimmed))
+        i += 1
+
+    n_rows = len(tokens) // n_cols
+    data = [[tokens[r * n_cols + c] for c in range(n_cols)] for r in range(n_rows)]
+    return {"tags": loop_tags, "data": data}, i
+
+
+def _find_col(tags: list[str], name: str) -> int:
+    return tags.index(name) if name in tags else -1
+
+
+def _get_cell(row: list[str], col: int) -> str:
+    return row[col] if 0 <= col < len(row) else ""
+
+
+def _extract_atom_sites(loops: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Build the atom-site list from the first _atom_site_* loop."""
+    for lp in loops:
+        tags = lp["tags"]
+        if not tags or not any(t.startswith("_atom_site_") for t in tags):
+            continue
+        col = {
+            "label": _find_col(tags, "_atom_site_label"),
+            "symbol": _find_col(tags, "_atom_site_type_symbol"),
+            "x": _find_col(tags, "_atom_site_fract_x"),
+            "y": _find_col(tags, "_atom_site_fract_y"),
+            "z": _find_col(tags, "_atom_site_fract_z"),
+            "occupancy": _find_col(tags, "_atom_site_occupancy"),
+        }
+        sites = []
+        for row in lp["data"]:
+            sites.append({
+                "label": _get_cell(row, col["label"]),
+                "symbol": _get_cell(row, col["symbol"]),
+                "x": _strip_uncertainty(_get_cell(row, col["x"])),
+                "y": _strip_uncertainty(_get_cell(row, col["y"])),
+                "z": _strip_uncertainty(_get_cell(row, col["z"])),
+                "occupancy": _strip_uncertainty(_get_cell(row, col["occupancy"])),
+            })
+        return sites
+    return []
+
+
+def import_cif(file_path: str | Path) -> dict[str, Any]:
+    """Parse a CIF file into a crystal-structure dict. Port of calc.importCIF.
+
+    Returns ``blockName``, ``tags`` (lowercased tag -> value string), ``loops``,
+    ``cellParams`` (a/b/c/alpha/beta/gamma, NaN if absent), ``spaceGroup``,
+    ``formula``, and ``atomSites`` (label/symbol/x/y/z/occupancy).
+    """
+    lines = Path(file_path).read_text(encoding="utf-8").splitlines()
+    n = len(lines)
+    result: dict[str, Any] = {
+        "blockName": "",
+        "tags": {},
+        "loops": [],
+        "cellParams": {k: float("nan") for k in ("a", "b", "c", "alpha", "beta", "gamma")},
+        "spaceGroup": "",
+        "formula": "",
+        "atomSites": [],
+    }
+    tags: dict[str, str] = result["tags"]
+
+    i = 0
+    while i < n:
+        raw = lines[i]
+        cp = _comment_pos(raw)
+        if cp >= 0:
+            raw = raw[:cp]
+        line = raw.strip()
+        if not line or line[0] == "#":
+            i += 1
+            continue
+        if line[:5].lower() == "data_":
+            result["blockName"] = line[5:].strip()
+            i += 1
+            continue
+        if line.lower() == "loop_":
+            loop_struct, i = _parse_loop(lines, i + 1, n)
+            result["loops"].append(loop_struct)
+            continue
+        if line[0] == "_":
+            tag, value, i = _parse_tag_value(lines, i, n)
+            tags[tag] = value
+            i += 1
+            continue
+        i += 1
+
+    cell_map = {
+        "_cell_length_a": "a", "_cell_length_b": "b", "_cell_length_c": "c",
+        "_cell_angle_alpha": "alpha", "_cell_angle_beta": "beta", "_cell_angle_gamma": "gamma",
+    }
+    for tag, field in cell_map.items():
+        if tag in tags:
+            result["cellParams"][field] = _strip_uncertainty(tags[tag])
+
+    for sg in ("_symmetry_space_group_name_h-m", "_space_group_name_h-m_alt"):
+        if sg in tags:
+            result["spaceGroup"] = tags[sg].strip()
+            break
+    if "_chemical_formula_sum" in tags:
+        result["formula"] = tags["_chemical_formula_sum"].strip()
+
+    result["atomSites"] = _extract_atom_sites(result["loops"])
+    return result

quantized/io/consolidated.py

@@ -0,0 +1,122 @@
+"""Consolidated CSV export: multiple datasets side-by-side in one file. Port of
+the per-dataset-block path of MATLAB ``+bosonPlotter/saveConsolidatedNeutronCSV.m``
+(also the writer ``+bosonPlotter/exportCombinedCSV.m`` uses).
+
+Each dataset contributes its own ``Q`` (X) column followed by its value columns,
+each tagged with an Origin designation by role (X / Y / yEr / xEr). Columns may
+differ in length; shorter ones leave trailing cells blank (not ``NaN``) so the
+file imports cleanly into Origin / Excel.
+
+Two header styles:
+  * ``standard`` — one row of ``<name> (<unit>)``.
+  * ``origin``   — four rows: Long Name / Units / File Name / Designation.
+
+NOTE: the genuinely-polarized path (shared-Q interpolation + spin asymmetry for
+>=2 distinct ++/-- cross-sections) is not ported here — that narrow neutron case
+needs ++/-- polarization metadata. This covers the general per-dataset block.
+
+Pure layer: ``consolidate_csv(datasets, fmt) -> str``. No disk I/O.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["consolidate_csv"]
+
+
+class _Col:
+    __slots__ = ("name", "unit", "file", "desig", "data")
+
+    def __init__(
+        self, name: str, unit: str, file: str, desig: str, data: np.ndarray
+    ) -> None:
+        self.name = name
+        self.unit = unit
+        self.file = file
+        self.desig = desig
+        self.data = data
+
+
+def _meta_get(meta: dict[str, Any], *keys: str, default: Any = None) -> Any:
+    sources: list[dict[str, Any]] = [meta]
+    for nested in ("parser_specific", "parserSpecific"):
+        sub = meta.get(nested)
+        if isinstance(sub, dict):
+            sources.append(sub)
+    for src in sources:
+        for key in keys:
+            val = src.get(key)
+            if val not in (None, ""):
+                return val
+    return default
+
+
+def _resolve_x_unit(ds: DataStruct) -> str:
+    return str(_meta_get(dict(ds.metadata), "xUnit", "x_column_unit", "xColumnUnit", default=""))
+
+
+def _dataset_filename(ds: DataStruct, name: str) -> str:
+    source = _meta_get(dict(ds.metadata), "source", "filepath", "filename", default="")
+    base = str(source).replace("\\", "/").rsplit("/", 1)[-1]
+    return base or name or "dataset"
+
+
+def _column_role(label: str) -> str:
+    low = label.lower()
+    if low in ("dr", "di") or any(k in low for k in ("uncert", "err", "std", "sigma")):
+        return "yEr"
+    if "resolution" in low or "dq" in low:
+        return "xEr"
+    return "Y"
+
+
+def _csv_field(text: str) -> str:
+    """Quote a header cell if it holds a comma, quote, or newline."""
+    if any(ch in text for ch in ',"\n\r'):
+        return '"' + text.replace('"', '""') + '"'
+    return text
+
+
+def _columns(datasets: list[tuple[DataStruct, str]]) -> list[_Col]:
+    cols: list[_Col] = []
+    for ds, name in datasets:
+        file = _dataset_filename(ds, name)
+        time = np.asarray(ds.time, dtype=float)
+        values = np.asarray(ds.values, dtype=float)
+        cols.append(_Col("Q", _resolve_x_unit(ds), file, "X", time))
+        for i, label in enumerate(ds.labels):
+            unit = ds.units[i] if i < len(ds.units) else ""
+            cols.append(_Col(label, unit, file, _column_role(label), values[:, i]))
+    return cols
+
+
+def consolidate_csv(datasets: list[tuple[DataStruct, str]], *, fmt: str = "standard") -> str:
+    """Combine ``datasets`` (each ``(DataStruct, name)``) into one CSV string."""
+    if fmt not in ("standard", "origin"):
+        raise ValueError("fmt must be 'standard' or 'origin'")
+    if not datasets:
+        raise ValueError("no datasets to consolidate")
+
+    cols = _columns(datasets)
+    lines: list[str] = []
+
+    if fmt == "origin":
+        lines.append(",".join(_csv_field(c.name) for c in cols))
+        lines.append(",".join(_csv_field(c.unit) for c in cols))
+        lines.append(",".join(_csv_field(c.file) for c in cols))
+        lines.append(",".join(_csv_field(c.desig) for c in cols))
+    else:
+        hdr = [f"{c.name} ({c.unit})" if c.unit else c.name for c in cols]
+        lines.append(",".join(_csv_field(h) for h in hdr))
+
+    max_rows = max((c.data.size for c in cols), default=0)
+    for r in range(max_rows):
+        cells = [f"{c.data[r]:.10g}" if r < c.data.size else "" for c in cols]
+        lines.append(",".join(cells))
+
+    return "\n".join(lines) + "\n"