quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/mcmc.py

@@ -0,0 +1,177 @@
+r"""MCMC posterior sampling for nonlinear-fit uncertainty (``fitting.mcmcSample``).
+
+Pure calc layer. A single-chain random-walk Metropolis sampler with a Gaussian
+proposal — the same scaffold as the MATLAB original (the production target is an
+affine-invariant ensemble sampler; not yet implemented on either side).
+
+The algorithm, per step ``k``:
+
+.. math::
+
+    p' = p_{k-1} + \sigma \odot \mathcal{N}(0, I), \qquad
+    \text{accept if } \log u < \log P(p') - \log P(p_{k-1}), \; u \sim U(0,1)
+
+where :math:`\sigma` is a uniform per-dimension proposal scale (``step_size``).
+Post burn-in the chain is thinned, and an effective sample size is estimated from
+the integrated autocorrelation time (Sokal 1997) via a single batched FFT.
+
+Because the sampler is RNG-driven it is **not** golden-frozen against MATLAB
+(NumPy and MATLAB use different generators); it is verified by invariants —
+posterior-mean recovery, an acceptance rate in the target band, correct output
+shapes, and seeded reproducibility (see ``tests/test_calc_mcmc.py``), mirroring
+how ``tests/fitting/test_mcmcSample.m`` tests the MATLAB scaffold.
+
+References
+----------
+Goodman, J. & Weare, J., *Ensemble samplers with affine invariance*,
+Commun. Appl. Math. Comput. Sci. **5**, 65 (2010).
+Foreman-Mackey, D. et al., *emcee: the MCMC Hammer*, PASP **125**, 306 (2013).
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = ["mcmc_sample"]
+
+LogPosterior = Callable[[NDArray[np.float64]], float]
+
+
+def mcmc_sample(
+    log_posterior: LogPosterior,
+    initial_params: float | list[float] | NDArray[np.float64],
+    *,
+    num_steps: int = 10000,
+    burn_in: int = 1000,
+    thin: int = 1,
+    step_size: float = 0.05,
+    seed: int | None = None,
+) -> dict[str, Any]:
+    r"""Random-walk Metropolis MCMC over a log-posterior.
+
+    Parameters
+    ----------
+    log_posterior
+        Callable taking a 1-D parameter vector and returning a scalar
+        log-posterior (log-likelihood + log-prior). Return ``-inf`` for
+        out-of-prior parameters.
+    initial_params
+        Starting parameter vector (scalar or length-``P`` sequence).
+    num_steps
+        Total MCMC steps (``> 0``).
+    burn_in
+        Leading steps to discard (``>= 0``).
+    thin
+        Keep every ``thin``-th post-burn-in sample (``> 0``).
+    step_size
+        Gaussian proposal scale, uniform across dimensions (``> 0``).
+    seed
+        RNG seed for reproducibility; ``None`` for a fresh generator.
+
+    Returns
+    -------
+    dict
+        ``samples`` ``[N × P]`` post-burn-in thinned draws, ``log_posterior``
+        ``[N]`` at each, ``accept_rate`` (target 0.2–0.5), and ``diagnostic``
+        (``n_steps``, ``n_accepted``, ``ess`` per dimension, ``r_hat`` = NaN
+        placeholder, ``sampler``).
+    """
+    if num_steps < 1:
+        raise ValueError("num_steps must be a positive integer")
+    if burn_in < 0:
+        raise ValueError("burn_in must be non-negative")
+    if thin < 1:
+        raise ValueError("thin must be a positive integer")
+    if not (step_size > 0):
+        raise ValueError("step_size must be positive")
+
+    rng = np.random.default_rng(seed)
+    p0 = np.atleast_1d(np.asarray(initial_params, dtype=float)).ravel()
+    if p0.size == 0:
+        raise ValueError("initial_params must be non-empty")
+    n_params = int(p0.size)
+    n = int(num_steps)
+
+    chain = np.zeros((n, n_params), dtype=float)
+    log_post = np.zeros(n, dtype=float)
+    chain[0] = p0
+    log_post[0] = float(log_posterior(p0))
+
+    # Uniform proposal scale in every dimension. A fraction-of-|p| rule would
+    # collapse when any initial parameter is near zero (MATLAB note).
+    prop_scale = step_size * np.ones(n_params, dtype=float)
+
+    n_accepted = 0
+    for kk in range(1, n):
+        prop = chain[kk - 1] + rng.standard_normal(n_params) * prop_scale
+        lp_prop = float(log_posterior(prop))
+        log_ratio = lp_prop - log_post[kk - 1]
+        if math.log(rng.random()) < log_ratio:
+            chain[kk] = prop
+            log_post[kk] = lp_prop
+            n_accepted += 1
+        else:
+            chain[kk] = chain[kk - 1]
+            log_post[kk] = log_post[kk - 1]
+
+    # Burn-in + thinning. MATLAB (1-based) (BurnIn+1):Thin:N → 0-based
+    # burn_in:thin:N.
+    keep = np.arange(burn_in, n, thin)
+    samples = chain[keep]
+    lp_kept = log_post[keep]
+    ess = _effective_sample_size(samples)
+
+    accept_rate = n_accepted / (n - 1) if n > 1 else float("nan")
+    return {
+        "samples": samples,
+        "log_posterior": lp_kept,
+        "accept_rate": accept_rate,
+        "diagnostic": {
+            "n_steps": n,
+            "n_accepted": n_accepted,
+            "ess": ess,
+            "r_hat": float("nan"),  # Gelman-Rubin needs multiple chains (TODO)
+            "sampler": "random-walk-metropolis",
+        },
+    }
+
+
+def _effective_sample_size(samples: NDArray[np.float64]) -> NDArray[np.float64]:
+    r"""Per-dimension ESS from the integrated autocorrelation time (Sokal 1997).
+
+    For each column the normalised autocorrelation is the inverse FFT of
+    ``|FFT(z)|²`` (``z`` = mean-centred chain), zero-padded to avoid circular
+    wrap. ``τ = 1 + 2·Σ ρ_lag`` over positive-lag autocorrelations above 0.05,
+    and ``ESS = N / max(τ, 1)``. All-constant columns get ``ESS = N`` directly.
+    """
+    n_kept, n_params = samples.shape
+    ess = np.zeros(n_params, dtype=float)
+    z = samples - samples.mean(axis=0)  # mean-centred [n_kept × P]
+
+    zero_mask = np.all(z == 0.0, axis=0)
+    ess[zero_mask] = n_kept
+    active = ~zero_mask
+    if not np.any(active):
+        return ess
+
+    z_active = z[:, active]
+    nfft = 1 << _nextpow2(2 * n_kept - 1)  # zero-pad past the wrap point
+    freq = np.fft.fft(z_active, n=nfft, axis=0)
+    ac = np.real(np.fft.ifft(freq * np.conj(freq), axis=0))
+    ac = np.asarray(ac / ac[0], dtype=float)  # normalise each column by lag-0
+    ac_pos = ac[1:n_kept]  # positive lags 1 … n_kept-1
+    tau = 1.0 + 2.0 * np.sum(ac_pos * (ac_pos > 0.05), axis=0)
+    ess[active] = n_kept / np.maximum(tau, 1.0)
+    return ess
+
+
+def _nextpow2(value: int) -> int:
+    """Smallest integer ``p`` with ``2**p >= value`` (MATLAB ``nextpow2``)."""
+    if value <= 1:
+        return 0
+    return int(math.ceil(math.log2(value)))

quantized/calc/optics.py

@@ -0,0 +1,228 @@
+r"""Optics calculators (DiraCulator ``buildOpticsTab`` + ``+calc/+optics``).
+
+Pure calc layer — closed-form scalars in, result dicts out. No fastapi /
+pydantic imports. Ports the seven MATLAB ``calc.optics`` functions verbatim:
+
+.. math::
+
+    r_s = \frac{n_1\cos\theta_i - n_2\cos\theta_t}
+               {n_1\cos\theta_i + n_2\cos\theta_t} \qquad R_s = |r_s|^2 \\
+    \theta_c = \arcsin(n_2/n_1) \qquad \theta_B = \arctan(n_2/n_1) \\
+    \delta_{\text{pen}} = \frac{\lambda}{4\pi k} \qquad
+    \delta_{\text{skin}} = \sqrt{\frac{2\rho}{\omega\mu_0}} \\
+    \varepsilon_1 = n^2 - k^2 \qquad \varepsilon_2 = 2 n k
+
+Conventions follow the MATLAB toolbox (the behavioural reference): angles in
+degrees, penetration-depth wavelength in any consistent length unit (output in
+the same unit), skin-depth resistivity in Ω·m (SI) and frequency in Hz.
+
+Reference values (from the MATLAB docstrings / closed form):
+  - ``fresnel_coefficients(1.0, 1.5, 0) -> Rs = Rp = 0.04`` (air/glass)
+  - ``critical_angle(1.5, 1.0) -> theta_c ≈ 41.81`` deg (glass/air)
+  - ``brewster_angle(1.0, 1.5) -> theta_b ≈ 56.31`` deg (air/glass)
+  - ``penetration_depth(5.6, 0.39, 400) -> depth ≈ 81.6`` nm (Si @ 400 nm)
+  - ``skin_depth(1.68e-8, 1e9) -> delta ≈ 2.06`` µm (Cu @ 1 GHz)
+  - ``refractive_to_dielectric(3.5, 0) -> eps1 = 12.25, eps2 = 0`` (Si, IR)
+"""
+
+from __future__ import annotations
+
+import cmath
+import math
+
+from quantized.calc.constants import constants
+
+__all__ = [
+    "brewster_angle",
+    "critical_angle",
+    "dielectric_to_refractive",
+    "fresnel_coefficients",
+    "penetration_depth",
+    "refractive_to_dielectric",
+    "skin_depth",
+]
+
+
+def fresnel_coefficients(n1: float, n2: float, theta: float) -> dict[str, float]:
+    """Fresnel reflectance/transmittance at an interface (``fresnelCoefficients.m``).
+
+    Generalised Snell's law ``cos θ_t = √(1 − (n₁/n₂·sin θᵢ)²)`` (principal
+    branch) gives evanescent waves above the critical angle. Amplitude
+    coefficients are computed with complex arithmetic; only the real-valued
+    intensity coefficients are returned (complex amplitudes can't serialize).
+
+    Args:
+        n1: refractive index of the incident medium, > 0.
+        n2: refractive index of the transmitted medium, > 0.
+        theta: angle of incidence (degrees from normal), >= 0.
+
+    Returns ``Rs``/``Rp`` reflectances |r|² and ``Ts``/``Tp`` transmittances
+    (energy-conserving form).
+
+    >>> r = fresnel_coefficients(1.0, 1.5, 0.0)
+    >>> round(r["Rs"], 4)
+    0.04
+    >>> round(r["Ts"], 4)
+    0.96
+    """
+    if n1 <= 0 or n2 <= 0:
+        raise ValueError("n1 and n2 must be positive")
+    if theta < 0:
+        raise ValueError("theta must be non-negative")
+
+    th = math.radians(theta)
+    cos_i = complex(math.cos(th))
+    sin_i = complex(math.sin(th))
+
+    sin_t = (n1 / n2) * sin_i
+    cos_t = cmath.sqrt(1 - sin_t**2)  # principal sqrt; evanescent if TIR
+
+    rs = (n1 * cos_i - n2 * cos_t) / (n1 * cos_i + n2 * cos_t)
+    rp = (n2 * cos_i - n1 * cos_t) / (n2 * cos_i + n1 * cos_t)
+    ts = (2 * n1 * cos_i) / (n1 * cos_i + n2 * cos_t)
+    tp = (2 * n1 * cos_i) / (n2 * cos_i + n1 * cos_t)
+
+    r_s = abs(rs) ** 2
+    r_p = abs(rp) ** 2
+    factor = (n2 * cos_t.conjugate()).real / (n1 * cos_i.conjugate()).real
+    t_s = factor * abs(ts) ** 2
+    t_p = factor * abs(tp) ** 2
+
+    return {"Rs": r_s, "Rp": r_p, "Ts": t_s, "Tp": t_p, "theta": theta}
+
+
+def critical_angle(n1: float, n2: float) -> dict[str, float]:
+    """Critical angle for total internal reflection (``criticalAngle.m``).
+
+    ``θ_c = arcsin(n₂/n₁)`` (degrees). TIR requires ``n₁ > n₂``; when
+    ``n₂ >= n₁`` returns ``theta_c = NaN`` (no error) so callers can use it in
+    vectorised workflows without branching.
+
+    >>> round(critical_angle(1.5, 1.0)["theta_c"], 2)
+    41.81
+    >>> import math
+    >>> math.isnan(critical_angle(1.0, 1.5)["theta_c"])
+    True
+    """
+    if n1 <= 0 or n2 <= 0:
+        raise ValueError("n1 and n2 must be positive")
+    theta_c = float("nan") if n2 >= n1 else math.degrees(math.asin(n2 / n1))
+    return {"theta_c": theta_c, "n1": n1, "n2": n2}
+
+
+def brewster_angle(n1: float, n2: float) -> dict[str, float]:
+    """Brewster angle for p-polarised light (``brewsterAngle.m``).
+
+    ``θ_B = arctan(n₂/n₁)`` (degrees). At this angle the reflected beam is
+    purely s-polarised (``R_p = 0``). Exact for real, lossless media.
+
+    >>> round(brewster_angle(1.0, 1.5)["theta_b"], 2)
+    56.31
+    """
+    if n1 <= 0 or n2 <= 0:
+        raise ValueError("n1 and n2 must be positive")
+    return {"theta_b": math.degrees(math.atan(n2 / n1)), "n1": n1, "n2": n2}
+
+
+def penetration_depth(n: float, k: float, wavelength: float) -> dict[str, float]:
+    """Optical penetration depth for an absorbing medium (``penetrationDepth.m``).
+
+    1/e intensity depth ``δ = λ / (4π k) = 1/α``. When ``k = 0`` the medium is
+    lossless: ``depth`` and ``abs_length`` are +inf and ``abs_coeff`` is 0.
+    Output length unit matches the wavelength unit.
+
+    Args:
+        n: real part of refractive index, > 0.
+        k: extinction coefficient, >= 0.
+        wavelength: wavelength (any length unit), > 0.
+
+    >>> round(penetration_depth(5.6, 0.39, 400.0)["depth"], 1)
+    81.6
+    >>> penetration_depth(1.5, 0.0, 500.0)["depth"]
+    inf
+    """
+    if n <= 0:
+        raise ValueError("n must be positive")
+    if k < 0:
+        raise ValueError("k must be non-negative")
+    if wavelength <= 0:
+        raise ValueError("wavelength must be positive")
+
+    if k == 0:
+        abs_coeff = 0.0
+        depth = float("inf")
+        abs_length = float("inf")
+    else:
+        abs_coeff = 4 * math.pi * k / wavelength
+        depth = 1.0 / abs_coeff  # = lambda / (4*pi*k)
+        abs_length = 1.0 / (2 * abs_coeff)
+    return {
+        "depth": depth,
+        "abs_coeff": abs_coeff,
+        "abs_length": abs_length,
+        "wavelength": wavelength,
+        "n": n,
+        "k": k,
+    }
+
+
+def skin_depth(rho: float, f: float) -> dict[str, float]:
+    """Electromagnetic skin depth of a conductor (``skinDepth.m``).
+
+    Good-conductor approximation ``δ = √(2ρ / (ω μ₀))`` with ``ω = 2π f`` and
+    ``μ₀`` the vacuum permeability. Assumes relative permeability μ_r = 1.
+
+    Args:
+        rho: electrical resistivity (Ω·m, SI), > 0.
+        f: field frequency (Hz), > 0.
+
+    Returns ``delta`` (m) plus ``delta_um`` (µm) and ``delta_nm`` (nm).
+
+    >>> round(skin_depth(1.68e-8, 1e9)["delta_um"], 2)
+    2.06
+    """
+    if rho <= 0:
+        raise ValueError("rho must be positive")
+    if f <= 0:
+        raise ValueError("f must be positive")
+    mu0 = constants()["mu0"]
+    omega = 2 * math.pi * f
+    delta = math.sqrt(2 * rho / (omega * mu0))
+    return {
+        "delta": delta,
+        "delta_um": delta * 1e6,
+        "delta_nm": delta * 1e9,
+        "rho": rho,
+        "f": f,
+    }
+
+
+def refractive_to_dielectric(n: float, k: float = 0.0) -> dict[str, float]:
+    """Complex refractive index (n, k) → dielectric function (``refractiveToDielectric.m``).
+
+    ``ε = (n + ik)²``  →  ``ε₁ = n² − k²``, ``ε₂ = 2 n k``.
+
+    >>> r = refractive_to_dielectric(3.5, 0.0)
+    >>> round(r["eps1"], 4), round(r["eps2"], 4)
+    (12.25, 0.0)
+    """
+    if k < 0:
+        raise ValueError("k must be non-negative")
+    return {"eps1": n**2 - k**2, "eps2": 2.0 * n * k, "n": n, "k": k}
+
+
+def dielectric_to_refractive(eps1: float, eps2: float = 0.0) -> dict[str, float]:
+    """Dielectric function (ε₁, ε₂) → complex refractive index (``dielectricToRefractive.m``).
+
+    Physical square root (``n >= 0``, ``k >= 0``):
+    ``n = √((|ε| + ε₁)/2)``, ``k = √((|ε| − ε₁)/2)`` with ``|ε| = √(ε₁² + ε₂²)``.
+    For metals with ``ε₁ < 0`` and ``ε₂ = 0``: ``n = 0``, ``k = √(−ε₁)``.
+
+    >>> r = dielectric_to_refractive(12.25, 0.0)
+    >>> round(r["n"], 4), round(r["k"], 4)
+    (3.5, 0.0)
+    """
+    mod_eps = math.sqrt(eps1**2 + eps2**2)
+    n = math.sqrt((mod_eps + eps1) / 2)
+    k = math.sqrt((mod_eps - eps1) / 2)
+    return {"n": n, "k": k, "eps1": eps1, "eps2": eps2}

quantized/calc/pawley.py

@@ -0,0 +1,251 @@
+r"""Pawley whole-pattern refinement for powder XRD (``fitting.pawleyRefine``).
+
+Pure calc layer. Pawley refinement fits **integrated peak intensities freely** —
+it does not require a structural model (that is Rietveld). This is the same
+scaffold as the MATLAB original: lattice parameters + an overall scale are
+refined by an adaptive grid search around the initial cell, while at each trial
+the peak intensities and a linear background are solved by linear least-squares.
+
+Pipeline
+--------
+1. For a trial cell, enumerate allowed reflections via
+   :func:`quantized.calc.crystallography.plane_spacings` (centering rules only —
+   glide/screw absences are not applied, matching the MATLAB scaffold), keeping
+   ``0 < 2θ <= max_two_theta``.
+2. Build a fixed-width pseudo-Voigt (50–50 Gaussian/Lorentzian) basis, one column
+   per peak, plus a linear background basis ``[1, 2θ]``; solve
+   ``[peaks | bg] · x = I_obs`` by least-squares, clamping peak intensities ``≥ 0``.
+3. ``χ² = Σ (model − obs)²`` scores the trial cell. An adaptive grid search steps
+   each free axis ``± 0.02·a₀`` (halving on stalls), tying axes by crystal system
+   (cubic ``a=b=c``; tetragonal ``a=b≠c``; else all three free).
+4. Report the refined cell, the fitted model/background/residual, per-peak
+   intensities, and the weighted-profile R-factor
+   ``R_wp = sqrt( Σ w·resid² / Σ w·obs² )`` with Poisson-like weights
+   ``w = 1/max(I, 1)``.
+
+Verified by invariants (cell recovery on a synthetic pattern, output-field
+presence, size-mismatch rejection) rather than golden values — mirroring
+``tests/fitting/test_pawleyRefine.m``, since the adaptive grid search + LAPACK
+least-squares can branch differently from MATLAB at the last significant digit.
+
+References
+----------
+Pawley, G.S., *Unit-cell refinement from powder diffraction scans*,
+J. Appl. Cryst. **14**, 357 (1981).
+Cagliotti, G. et al., Nucl. Instrum. **3**, 223 (1958) — U/V/W profile.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.calc.crystallography import plane_spacings
+
+__all__ = ["pawley_refine"]
+
+_REQUIRED_FIELDS = ("a", "b", "c", "symmetry")
+_BACKGROUNDS = ("linear", "polynomial", "cheby")
+
+
+def pawley_refine(
+    two_theta: NDArray[np.float64] | list[float],
+    intensity: NDArray[np.float64] | list[float],
+    phase_info: dict[str, Any],
+    *,
+    wavelength: float = 1.5406,
+    max_two_theta: float = 120.0,
+    background: str = "linear",
+    profile_fwhm: float = 0.05,
+    refine_cell: bool = True,
+    max_iter: int = 20,
+) -> dict[str, Any]:
+    r"""Pawley refine a powder pattern against a phase's lattice.
+
+    Parameters
+    ----------
+    two_theta, intensity
+        Observed scan (``2θ`` in degrees, counts/intensity). Same length.
+    phase_info
+        Dict with ``a``, ``b``, ``c`` (Å) and ``symmetry`` (Bravais letter /
+        centering, e.g. ``'F'``); optional ``alpha``/``beta``/``gamma`` (deg,
+        default 90) and ``hklMax`` (default 6).
+    wavelength
+        X-ray wavelength (Å); CuKα1 by default.
+    max_two_theta
+        Upper ``2θ`` cut-off (deg).
+    background
+        ``'linear'`` (only linear is implemented, matching the scaffold).
+    profile_fwhm
+        Fixed pseudo-Voigt FWHM per peak (deg).
+    refine_cell
+        Refine the lattice parameters (else keep the initial cell).
+    max_iter
+        Outer grid-search iterations.
+
+    Returns
+    -------
+    dict
+        ``cell`` / ``cell_initial`` ``[a b c α β γ]``, ``scale`` (NaN — folded
+        into per-peak intensity), ``peaks`` (list of ``hkl``/``two_theta``/``d``/
+        ``multiplicity``/``intensity``), ``background``/``model``/``residual``
+        ``[N]``, ``rwp``, ``n_peaks``.
+    """
+    tt = np.asarray(two_theta, dtype=float).ravel()
+    obs = np.asarray(intensity, dtype=float).ravel()
+    if tt.size == 0 or obs.size == 0:
+        raise ValueError("two_theta and intensity must be non-empty")
+    if tt.size != obs.size:
+        raise ValueError(
+            f"two_theta ({tt.size}) and intensity ({obs.size}) must have the same length."
+        )
+    if background not in _BACKGROUNDS:
+        raise ValueError(f"background must be one of {_BACKGROUNDS}, got {background!r}")
+
+    for field in _REQUIRED_FIELDS:
+        if field not in phase_info:
+            raise ValueError(f'phase_info is missing required field "{field}".')
+    alpha = float(phase_info.get("alpha", 90.0))
+    beta = float(phase_info.get("beta", 90.0))
+    gamma = float(phase_info.get("gamma", 90.0))
+    hkl_max = int(phase_info.get("hklMax", 6))
+    symmetry = str(phase_info["symmetry"])
+    cell0 = [
+        float(phase_info["a"]),
+        float(phase_info["b"]),
+        float(phase_info["c"]),
+        alpha,
+        beta,
+        gamma,
+    ]
+
+    def compute_peaks(cell: list[float]) -> list[dict[str, Any]]:
+        ps = plane_spacings(
+            cell[0],
+            b=cell[1],
+            c=cell[2],
+            alpha=cell[3],
+            beta=cell[4],
+            gamma=cell[5],
+            centering=symmetry,
+            max_hkl=hkl_max,
+            lambda_=wavelength,
+        )
+        peaks: list[dict[str, Any]] = []
+        for hkl, d, tth, mult in zip(
+            ps["hkl"], ps["d"], ps["two_theta"], ps["multiplicity"], strict=True
+        ):
+            if math.isnan(tth) or tth > max_two_theta or tth <= 0:
+                continue
+            peaks.append(
+                {"hkl": hkl, "two_theta": tth, "d": d, "multiplicity": mult, "intensity": 0.0}
+            )
+        return peaks
+
+    def trial_chi2(cell: list[float]) -> float:
+        peaks = compute_peaks(cell)
+        if not peaks:
+            return math.inf
+        model_y, _bg, _peak_i = _build_model(peaks, tt, obs, profile_fwhm)
+        resid = model_y - obs
+        return float(np.sum(resid**2))
+
+    # ── Adaptive grid search around the initial cell ────────────────────────
+    cell_refined = list(cell0)
+    if refine_cell:
+        tol_eq = 1e-4
+        is_cubic = abs(cell0[0] - cell0[1]) < tol_eq and abs(cell0[1] - cell0[2]) < tol_eq
+        is_tetrag = abs(cell0[0] - cell0[1]) < tol_eq and abs(cell0[1] - cell0[2]) >= tol_eq
+        if is_cubic:
+            axes_to_step = [0]  # a only; mirror to b, c
+        elif is_tetrag:
+            axes_to_step = [0, 2]  # a (mirror to b) and c
+        else:
+            axes_to_step = [0, 1, 2]
+
+        step = [0.02 * cell0[0], 0.02 * cell0[1], 0.02 * cell0[2]]
+        for _ in range(max_iter):
+            chi_base = trial_chi2(cell_refined)
+            improved = False
+            for ax in axes_to_step:
+                for sign in (1, -1):
+                    trial = list(cell_refined)
+                    if is_cubic:
+                        new_val = cell_refined[0] + sign * step[0]
+                        trial = [new_val, new_val, new_val, *cell_refined[3:6]]
+                    elif is_tetrag and ax == 0:
+                        new_val = cell_refined[0] + sign * step[0]
+                        trial = [new_val, new_val, cell_refined[2], *cell_refined[3:6]]
+                    else:
+                        trial[ax] = cell_refined[ax] + sign * step[ax]
+                    if trial_chi2(trial) < chi_base:
+                        cell_refined = trial
+                        improved = True
+                        break
+            if not improved:
+                step = [s / 2 for s in step]
+                if max(abs(s) for s in step) < 1e-5:
+                    break
+
+    # ── Final model on the refined cell ─────────────────────────────────────
+    peaks = compute_peaks(cell_refined)
+    model_y, bg, peak_i = _build_model(peaks, tt, obs, profile_fwhm)
+    residual = obs - model_y
+
+    weights = 1.0 / np.maximum(obs, 1.0)  # Poisson-like weights
+    rwp_num = float(np.sum(weights * residual**2))
+    rwp_den = float(np.sum(weights * obs**2))
+    rwp = math.sqrt(rwp_num / rwp_den) if rwp_den > 0 else float("nan")
+
+    for k, pk in enumerate(peaks):
+        pk["intensity"] = float(peak_i[k]) if k < peak_i.size else 0.0
+
+    return {
+        "cell": cell_refined,
+        "cell_initial": cell0,
+        "scale": float("nan"),  # folded into per-peak intensity (scaffold)
+        "peaks": peaks,
+        "background": bg,
+        "model": model_y,
+        "residual": residual,
+        "rwp": rwp,
+        "n_peaks": len(peaks),
+    }
+
+
+def _build_model(
+    peaks: list[dict[str, Any]],
+    two_theta: NDArray[np.float64],
+    intensity: NDArray[np.float64],
+    profile_fwhm: float,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Fit peak intensities + a linear background by least-squares (``buildModel``).
+
+    Each peak is a fixed-FWHM 50–50 pseudo-Voigt column; the background basis is
+    ``[1, 2θ]``. Solves ``[peaks | bg] · x = I`` and clamps peak intensities ``≥ 0``.
+    """
+    n_pk = len(peaks)
+    if n_pk == 0:
+        zeros = np.zeros_like(two_theta)
+        return zeros, np.zeros_like(two_theta), np.zeros(0, dtype=float)
+
+    w = profile_fwhm / 2.0
+    basis = np.zeros((two_theta.size, n_pk), dtype=float)
+    for k, pk in enumerate(peaks):
+        dx = two_theta - pk["two_theta"]
+        lorentz = 1.0 / (1.0 + (dx / w) ** 2)
+        gauss = np.exp(-0.5 * (dx / (w / math.sqrt(2.0 * math.log(2.0)))) ** 2)
+        basis[:, k] = 0.5 * lorentz + 0.5 * gauss
+
+    bg_basis = np.column_stack([np.ones_like(two_theta), two_theta])
+    design = np.column_stack([basis, bg_basis])
+    coeffs, *_ = np.linalg.lstsq(design, intensity, rcond=None)
+
+    peak_intensity = np.asarray(np.maximum(coeffs[:n_pk], 0.0), dtype=float)
+    bg_coeff = coeffs[n_pk:]
+    bg = np.asarray(bg_basis @ bg_coeff, dtype=float)
+    model_y = np.asarray(basis @ peak_intensity + bg, dtype=float)
+    return model_y, bg, peak_intensity