reflectofit 0.1.0__tar.gz

reflectofit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isaac Yong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reflectofit-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: reflectofit
+Version: 0.1.0
+Summary: X-ray reflectivity fitting engine and command line
+Keywords: x-ray reflectivity,XRR,thin films,parratt,fitting
+Author: Isaac Yong
+Author-email: Isaac Yong <isaacyong@naver.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: reflectosim>=0.1,<0.2
+Requires-Dist: emcee>=3.1 ; extra == 'mcmc'
+Requires-Dist: reflectosim[torch]>=0.1,<0.2 ; extra == 'torch'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/NaNIsaac/ReflectoFit
+Project-URL: Repository, https://github.com/NaNIsaac/ReflectoFit
+Project-URL: Issues, https://github.com/NaNIsaac/ReflectoFit/issues
+Project-URL: Changelog, https://github.com/NaNIsaac/ReflectoFit/blob/main/CHANGELOG.md
+Provides-Extra: mcmc
+Provides-Extra: torch
+Description-Content-Type: text/markdown
+
+# ReflectoFit
+
+[![Tests](https://github.com/NaNIsaac/ReflectoFit/actions/workflows/ci.yml/badge.svg)](https://github.com/NaNIsaac/ReflectoFit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+<img src="https://raw.githubusercontent.com/NaNIsaac/ReflectoFit/main/docs/media/fit.png" width="720" alt="The first run below: Poisson counts from examples/film.toml, the starting model and the fit, with normalised residuals">
+
+A fast X-ray reflectivity fitting engine and command line: layer models, an instrument model, least
+squares, differential evolution and MCMC, model selection, and fit reports.
+
+It is for anyone with a measured specular XRR curve of a thin film who wants the thickness, roughness
+and density of each layer. The forward model is a float64 Parratt recursion (compiled with numba)
+with Névot-Croce roughness, Gaussian resolution, beam footprint, Cu Kα₂ and a 2θ offset; it agrees
+with refnx to 1e-10. A torch backend gives the same curves with gradients. The forward physics
+lives in [ReflectoSim](https://github.com/NaNIsaac/ReflectoSim), which also generates synthetic XRR
+data for machine learning; ReflectoFit is the inverse problem on top of it.
+
+Status: early development. The design is in [`docs/DESIGN.md`](docs/DESIGN.md); model selection
+follows.
+
+<img src="https://raw.githubusercontent.com/NaNIsaac/ReflectoFit/main/docs/media/throughput.png" width="720" alt="Forward-model curves per second against batch size for seven engines, for one film, five layers and a 50-layer superlattice">
+
+Forward-model throughput on the benchmark machine (`docs/design-bench/throughput.json`, DESIGN.md section 5). The numba backend computes about 57 000 five-layer curves per second in batches of 100 000 on CPU; hollow markers are values scaled or extrapolated from a smaller batch.
+
+## Install
+
+Not on PyPI yet. From a clone, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/NaNIsaac/ReflectoFit
+cd ReflectoFit
+uv sync
+```
+
+## First run
+
+Simulate a measured curve of a 240 Å film on SiO₂ on Si with Poisson counts, then fit it from a wrong
+starting guess:
+
+<!-- test -->
+```sh
+uv run reflectofit calc --model examples/film.toml --counts 1e8 -o film.dat
+uv run reflectofit fit film.dat --model examples/film_start.toml --loss poisson --counts-scale 1e8 -o fit
+```
+
+The fit prints each free parameter with its standard error and writes `fit/result.json`,
+`fit/model.toml` (the fitted model, reusable as a start) and `fit/fitted.dat`.
+
+Model files, every command and the Python API: [docs/usage.md](docs/usage.md).
+
+## Development
+
+```sh
+uv run pytest
+```
+
+## License
+
+MIT

reflectofit-0.1.0/README.md

@@ -0,0 +1,58 @@
+# ReflectoFit
+
+[![Tests](https://github.com/NaNIsaac/ReflectoFit/actions/workflows/ci.yml/badge.svg)](https://github.com/NaNIsaac/ReflectoFit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+<img src="https://raw.githubusercontent.com/NaNIsaac/ReflectoFit/main/docs/media/fit.png" width="720" alt="The first run below: Poisson counts from examples/film.toml, the starting model and the fit, with normalised residuals">
+
+A fast X-ray reflectivity fitting engine and command line: layer models, an instrument model, least
+squares, differential evolution and MCMC, model selection, and fit reports.
+
+It is for anyone with a measured specular XRR curve of a thin film who wants the thickness, roughness
+and density of each layer. The forward model is a float64 Parratt recursion (compiled with numba)
+with Névot-Croce roughness, Gaussian resolution, beam footprint, Cu Kα₂ and a 2θ offset; it agrees
+with refnx to 1e-10. A torch backend gives the same curves with gradients. The forward physics
+lives in [ReflectoSim](https://github.com/NaNIsaac/ReflectoSim), which also generates synthetic XRR
+data for machine learning; ReflectoFit is the inverse problem on top of it.
+
+Status: early development. The design is in [`docs/DESIGN.md`](docs/DESIGN.md); model selection
+follows.
+
+<img src="https://raw.githubusercontent.com/NaNIsaac/ReflectoFit/main/docs/media/throughput.png" width="720" alt="Forward-model curves per second against batch size for seven engines, for one film, five layers and a 50-layer superlattice">
+
+Forward-model throughput on the benchmark machine (`docs/design-bench/throughput.json`, DESIGN.md section 5). The numba backend computes about 57 000 five-layer curves per second in batches of 100 000 on CPU; hollow markers are values scaled or extrapolated from a smaller batch.
+
+## Install
+
+Not on PyPI yet. From a clone, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/NaNIsaac/ReflectoFit
+cd ReflectoFit
+uv sync
+```
+
+## First run
+
+Simulate a measured curve of a 240 Å film on SiO₂ on Si with Poisson counts, then fit it from a wrong
+starting guess:
+
+<!-- test -->
+```sh
+uv run reflectofit calc --model examples/film.toml --counts 1e8 -o film.dat
+uv run reflectofit fit film.dat --model examples/film_start.toml --loss poisson --counts-scale 1e8 -o fit
+```
+
+The fit prints each free parameter with its standard error and writes `fit/result.json`,
+`fit/model.toml` (the fitted model, reusable as a start) and `fit/fitted.dat`.
+
+Model files, every command and the Python API: [docs/usage.md](docs/usage.md).
+
+## Development
+
+```sh
+uv run pytest
+```
+
+## License
+
+MIT

reflectofit-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "reflectofit"
+version = "0.1.0"
+description = "X-ray reflectivity fitting engine and command line"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "x-ray reflectivity",
+    "XRR",
+    "thin films",
+    "parratt",
+    "fitting",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.0",
+    "scipy>=1.13",
+    "reflectosim>=0.1,<0.2",
+]
+
+[[project.authors]]
+name = "Isaac Yong"
+email = "isaacyong@naver.com"
+
+[project.optional-dependencies]
+torch = ["reflectosim[torch]>=0.1,<0.2"]
+mcmc = ["emcee>=3.1"]
+
+[project.scripts]
+reflectofit = "reflectofit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/NaNIsaac/ReflectoFit"
+Repository = "https://github.com/NaNIsaac/ReflectoFit"
+Issues = "https://github.com/NaNIsaac/ReflectoFit/issues"
+Changelog = "https://github.com/NaNIsaac/ReflectoFit/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "torch>=2.5",
+    "emcee>=3.1",
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.sources.torch]]
+index = "pytorch-cpu"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = [
+    "B",
+    "I",
+    "UP",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13"]
+build-backend = "uv_build"

reflectofit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,68 @@
+[project]
+name = "reflectofit"
+version = "0.1.0"
+description = "X-ray reflectivity fitting engine and command line"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Isaac Yong", email = "isaacyong@naver.com" }]
+keywords = ["x-ray reflectivity", "XRR", "thin films", "parratt", "fitting"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.0",
+    "scipy>=1.13",
+    "reflectosim>=0.1,<0.2",
+]
+
+[project.optional-dependencies]
+torch = ["reflectosim[torch]>=0.1,<0.2"]
+mcmc = ["emcee>=3.1"]
+
+[project.scripts]
+reflectofit = "reflectofit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/NaNIsaac/ReflectoFit"
+Repository = "https://github.com/NaNIsaac/ReflectoFit"
+Issues = "https://github.com/NaNIsaac/ReflectoFit/issues"
+Changelog = "https://github.com/NaNIsaac/ReflectoFit/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "torch>=2.5",
+    "emcee>=3.1",
+]
+
+# CPU torch wheels for this project's own lock (tests, CI); installs from PyPI are not affected.
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = [{ index = "pytorch-cpu" }]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = ["B", "I", "UP"]

reflectofit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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")