reflectofit 0.1.0__py3-none-any.whl

reflectofit/__init__.py

@@ -0,0 +1,5 @@
+"""X-ray reflectivity fitting engine on the ReflectoSim forward model."""
+
+from importlib.metadata import version
+
+__version__ = version("reflectofit")

reflectofit/cli.py

@@ -0,0 +1,117 @@
+"""Command line: reflectofit calc | fit | score | stitch."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+from reflectosim.grid import q_grid
+from reflectosim.noise import poisson_counts
+
+from reflectofit import __version__, data, fit, model
+
+
+def _calc(args) -> int:
+    m = model.load(args.model)
+    q = q_grid(args.grid, m.instrument.wavelength)
+    r = m.curves(q, m.start())[0]
+    y = (
+        poisson_counts(r[None, :], args.counts, np.random.default_rng(args.seed))[0]
+        if args.counts
+        else r
+    )
+    data.write(args.out, data.Curve(q, y, meta={"wavelength": m.instrument.wavelength}), x=args.x)
+    print(f"wrote {args.out} ({q.size} points{', Poisson counts' if args.counts else ''})")
+    return 0
+
+
+def _fit(args) -> int:
+    m = model.load(args.model)
+    curve = data.read(args.data, x=args.x, wavelength=m.instrument.wavelength)
+    common = {"loss": args.loss, "counts_scale": args.counts_scale}
+    if args.method == "lsq":
+        res = fit.lsq(m, curve, trust=args.trust, max_nfev=args.max_nfev, **common)
+    else:
+        res = fit.de(m, curve, seed=args.seed, **common)
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "result.json").write_text(res.to_json(), encoding="utf-8")
+    (out / "model.toml").write_text(model.dumps(res.model), encoding="utf-8")
+    lam = res.model.curves(curve.q, res.model.start())[0] * (args.counts_scale or 1.0)
+    data.write(out / "fitted.dat", data.Curve(curve.q, lam, meta=curve.meta), x=args.x)
+    width = max(len(k) for k in res.values)
+    for k, v in res.values.items():
+        print(f"{k:<{width}}  {v:.6g} +/- {res.errors[k]:.2g}")
+    if res.at_bound:
+        print(f"on a bound (errors not meaningful): {', '.join(res.at_bound)}")
+    print(f"{res.loss} objective {res.objective:.6g} over {res.n_points} points; {res.message}")
+    print(f"wrote {out / 'result.json'}, {out / 'model.toml'}, {out / 'fitted.dat'}")
+    return 0 if res.success else 2
+
+
+def _score(args) -> int:
+    m = model.load(args.model)
+    curve = data.read(args.data, x=args.x, wavelength=m.instrument.wavelength)
+    print(json.dumps(fit.score(m, curve, counts_scale=args.counts_scale), indent=1))
+    return 0
+
+
+def _stitch(args) -> int:
+    scans = [np.loadtxt(p, ndmin=2) for p in args.scans]
+    out = data.stitch(scans, method=args.method)
+    np.savetxt(args.out, out)
+    print(f"wrote {args.out} ({len(out)} points from {len(scans)} scans)")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="reflectofit", description="X-ray reflectivity fitting")
+    p.add_argument("--version", action="version", version=f"reflectofit {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("calc", help="compute a model curve, optionally with Poisson counts")
+    c.add_argument("--model", required=True, help="model TOML")
+    c.add_argument("--grid", default="tth:0.1:6:300", help="tth:START:STOP:N or q:START:STOP:N")
+    c.add_argument(
+        "--counts", type=float, default=None, help="counts at R = 1; draws Poisson counts"
+    )
+    c.add_argument("--seed", type=int, default=0)
+    c.add_argument("--x", choices=("tth", "q"), default="tth", help="x column of the output")
+    c.add_argument("-o", "--out", required=True)
+    c.set_defaults(run=_calc)
+
+    for name, helptext, run in (
+        ("fit", "fit a model to a curve", _fit),
+        ("score", "losses of a model", _score),
+    ):
+        f = sub.add_parser(name, help=helptext)
+        f.add_argument("data", help="2- or 3-column text: x, intensity[, error]")
+        f.add_argument("--model", required=True, help="model TOML with [fit] bounds")
+        f.add_argument("--x", choices=("tth", "q"), default="tth", help="x column of the data")
+        f.add_argument(
+            "--counts-scale", type=float, default=None, help="data are counts; counts at R = 1"
+        )
+        f.set_defaults(run=run)
+        if name == "fit":
+            f.add_argument("--method", choices=("lsq", "de"), default="lsq")
+            f.add_argument("--loss", choices=("log", "raw", "poisson", "chi2"), default="log")
+            f.add_argument(
+                "--trust", type=float, default=None, help="limit each start to +/- fraction"
+            )
+            f.add_argument("--max-nfev", type=int, default=200)
+            f.add_argument("--seed", type=int, default=0)
+            f.add_argument("-o", "--out", default="fit", help="output directory")
+
+    s = sub.add_parser("stitch", help="join scans measured through different attenuators")
+    s.add_argument("scans", nargs="+", help="scan files (x, intensity[, error]) in increasing x")
+    s.add_argument("--method", choices=("boundary", "median"), default="boundary")
+    s.add_argument("-o", "--out", required=True)
+    s.set_defaults(run=_stitch)
+
+    args = p.parse_args(argv)
+    return args.run(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

reflectofit/data.py

@@ -0,0 +1,118 @@
+"""Measured curves: reading, stitching attenuated segments, held-out splits.
+
+Measured files are never part of this repository (DESIGN.md section 6); tests use synthetic files.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+from reflectosim.units import CU_KALPHA1, q_to_tth, tth_to_q
+
+
+@dataclass
+class Curve:
+    q: NDArray[np.float64]
+    y: NDArray[np.float64]
+    sigma: NDArray[np.float64] | None = None
+    meta: dict = field(default_factory=dict)
+
+    def tth(self, wavelength: float | None = None) -> NDArray[np.float64]:
+        return q_to_tth(self.q, wavelength or self.meta.get("wavelength", CU_KALPHA1))
+
+
+def read(path: str | Path, x: Literal["tth", "q"] = "tth", wavelength: float = CU_KALPHA1) -> Curve:
+    """Read 2- or 3-column text (x, intensity[, error]); whitespace or commas, comment and header
+    lines skipped. Sorted by q; equal q values are kept."""
+    rows = []
+    for line in Path(path).read_text(encoding="utf-8", errors="ignore").splitlines():
+        line = line.strip()
+        if not line or line[0] in "#!;%/":
+            continue
+        parts = line.replace(",", " ").split()
+        try:
+            rows.append([float(p) for p in parts[:3]])
+        except ValueError:
+            continue
+    rows = [r for r in rows if len(r) >= 2]
+    if not rows:
+        raise ValueError(f"no numeric data with at least two columns in {path}")
+    width = min(len(r) for r in rows)
+    arr = np.array([r[:width] for r in rows])
+    q = tth_to_q(arr[:, 0], wavelength) if x == "tth" else arr[:, 0]
+    order = np.argsort(q, kind="stable")
+    sigma = arr[order, 2] if width >= 3 else None
+    meta = {"source": str(path), "x": x, "wavelength": wavelength}
+    return Curve(np.asarray(q)[order], arr[order, 1], sigma, meta)
+
+
+def write(path: str | Path, curve: Curve, x: Literal["tth", "q"] = "tth") -> None:
+    cols = [curve.tth() if x == "tth" else curve.q, curve.y]
+    if curve.sigma is not None:
+        cols.append(curve.sigma)
+    header = f"{'2theta_deg' if x == 'tth' else 'q_invA'} intensity" + (
+        " error" if curve.sigma is not None else ""
+    )
+    np.savetxt(path, np.column_stack(cols), header=header)
+
+
+def stitch(
+    scans: list[NDArray], method: Literal["boundary", "median"] = "boundary"
+) -> NDArray[np.float64]:
+    """Join scans (N, 2+) of [x, intensity, (error, ...)] measured through different attenuators.
+
+    boundary (xrr_combine, ReflectoLearn): scans in increasing x share exactly one boundary point;
+    the last scan is the reference, each earlier scan is scaled so its last point equals the next
+    scan's first point, and the duplicate is dropped.
+    median (xray_ooguy): the first scan is the reference; each later scan is scaled by the median of
+    the point-by-point ratio to the curve assembled so far (linear interpolation) over their overlap,
+    which needs at least two points; all points are kept. A scan without such an overlap raises.
+    Every column after x is scaled together.
+    """
+    scans = [np.asarray(s, dtype=float) for s in scans]
+    if not scans:
+        return np.empty((0, 3))
+    if method == "boundary":
+        out = [scans[-1]]
+        head = scans[-1][0, 1]
+        for scan in reversed(scans[:-1]):
+            scan = scan.copy()
+            scan[:, 1:] *= head / scan[-1, 1]
+            scan = scan[:-1]
+            head = scan[0, 1]
+            out.append(scan)
+        return np.concatenate(out[::-1])
+    if method != "median":
+        raise ValueError(f"unknown method {method!r}; use 'boundary' or 'median'")
+    order = sorted(scans, key=lambda s: s[0, 0])
+    acc = order[0].copy()
+    for scan in order[1:]:
+        inside = scan[:, 0] <= acc[-1, 0]
+        prev = np.interp(scan[inside, 0], acc[:, 0], acc[:, 1], left=np.nan)
+        ok = np.isfinite(prev) & (prev > 0) & (scan[inside, 1] > 0)
+        if ok.sum() < 2:
+            raise ValueError(
+                f"scan starting at x = {scan[0, 0]} overlaps the curve in fewer than two points"
+            )
+        scaled = scan.copy()
+        scaled[:, 1:] *= np.median(prev[ok] / scan[inside, 1][ok])
+        acc = np.concatenate([acc, scaled])
+        acc = acc[np.argsort(acc[:, 0], kind="stable")]
+    return acc
+
+
+def block_split(
+    q: NDArray, n_blocks: int, held: tuple[int, ...], q_min: float = 0.0
+) -> tuple[NDArray[np.bool_], NDArray[np.bool_]]:
+    """Training and held-out masks: points with q < q_min always train; the rest are cut into
+    `n_blocks` contiguous blocks of equal size (np.array_split) and the blocks in `held` (0-based)
+    are held out (ReflectoLearn#35 section 3.2)."""
+    q = np.asarray(q)
+    upper = np.flatnonzero(q >= q_min)
+    held_mask = np.zeros(q.shape, bool)
+    for i, block in enumerate(np.array_split(upper, n_blocks)):
+        if i in held:
+            held_mask[block] = True
+    return ~held_mask, held_mask

reflectofit/estimate.py

@@ -0,0 +1,89 @@
+"""Quick estimators read directly off a curve, without a fit."""
+
+from typing import Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def critical_q(
+    q: NDArray, y: NDArray, rule: Literal["steepest", "half_plateau"] = "steepest"
+) -> float:
+    """q of the critical edge.
+
+    steepest: the steepest descent of log R above the plateau (the minimum of d log10 R / dq,
+    refined by a parabola through it and its neighbours).
+    half_plateau: where the 3-point mean of y first falls to half the plateau, the plateau being
+    the largest 3-point mean in the first 10 % of points; linear interpolation between the two
+    points around the crossing (the rule of ReflectoLearn#35 protocol A1, step 2). NaN if it never
+    falls that far.
+
+    Neither is exactly the film's q_c: the half-plateau point is about 9 % high for 250 Å films and
+    can be several times low for 20-40 Å dense films whose edge tunnels (physics review on
+    ReflectoLearn#35).
+    """
+    q = np.asarray(q, float)
+    y = np.asarray(y, float)
+    if rule == "half_plateau":
+        ys = np.convolve(y, np.ones(3) / 3, mode="same")
+        ys[0], ys[-1] = y[0], y[-1]
+        top = int(np.argmax(ys[: max(len(ys) // 10, 3)]))
+        below = np.flatnonzero(ys[top:] < 0.5 * ys[top])
+        if below.size == 0:
+            return float("nan")
+        k = top + int(below[0])
+        if k == 0:
+            return float(q[0])
+        f = (ys[k - 1] - 0.5 * ys[top]) / (ys[k - 1] - ys[k])
+        return float(q[k - 1] + f * (q[k] - q[k - 1]))
+    if rule != "steepest":
+        raise ValueError(f"unknown rule {rule!r}; use 'steepest' or 'half_plateau'")
+    logy = np.log10(np.clip(y, np.finfo(float).tiny, None))
+    start = int(np.argmax(logy))
+    slope = np.gradient(logy[start:], q[start:])
+    i = int(np.argmin(slope))
+    if 0 < i < slope.size - 1:
+        a, b, c = slope[i - 1 : i + 2]
+        denom = a - 2 * b + c
+        if denom > 0:
+            dq = q[start + i + 1] - q[start + i]
+            return float(q[start + i] + 0.5 * (a - c) / denom * dq)
+    return float(q[start + i])
+
+
+def kiessig_thickness(
+    q: NDArray,
+    y: NDArray,
+    d_range: tuple[float, float] = (20.0, 2000.0),
+    sld: float | None = None,
+    d_min: float = 60.0,
+    mask: NDArray | None = None,
+) -> float:
+    """Film thickness [Å] from the Kiessig period: the strongest peak of the real-space transform
+    of the detrended log R (port of ReflectoLearn `refine.fft_thickness`, b6fb0c4).
+
+    Only points with y > 0 (and inside `mask`, if given) are used: a zero-count point has no
+    logarithm. Fringes are periodic in the film's own wavevector sqrt(q² − q_c²); with `sld`
+    [1e-6 Å⁻²] the transform runs over it, otherwise over q (which overestimates d by a few percent
+    near the edge). NaN with fewer than 40 usable points or no peak in [max(d_min, lo), hi].
+    """
+    q = np.asarray(q, float)
+    y = np.asarray(y, float)
+    ok = y > 0 if mask is None else (y > 0) & np.asarray(mask, bool)
+    usable = np.flatnonzero(ok)
+    if usable.size < 40:
+        return float("nan")
+    logy = np.log10(y[usable])
+    qu = q[usable]
+    qc2 = 16e-6 * np.pi * max(sld, 0.0) if sld is not None else 0.0
+    z = np.arange(max(d_min, d_range[0]) - 1.0, d_range[1] + 2.0, 1.0)
+    start = int(np.argmax(logy))  # skip the plateau and the critical edge
+    idx = np.flatnonzero((np.arange(qu.size) > start + 5) & (qu**2 > 1.2 * qc2))
+    if idx.size < 40:
+        return float("nan")
+    qq, yy = np.sqrt(qu[idx] ** 2 - qc2), logy[idx]
+    yy = yy - np.polyval(np.polyfit(qq, yy, 5), qq)
+    yy = yy * np.hanning(yy.size)
+    amp = np.abs(np.exp(-1j * np.outer(z, qq)) @ yy)
+    peak = (amp[1:-1] > amp[:-2]) & (amp[1:-1] >= amp[2:])
+    return float(z[1:-1][peak][np.argmax(amp[1:-1][peak])]) if peak.any() else float("nan")