midas-pdf 0.1.0__tar.gz

midas_pdf-0.1.0/LICENSE

@@ -0,0 +1,53 @@
+Copyright (c) 2012, UChicago Argonne, LLC
+ 
+All Rights Reserved
+ 
+MIDAS Microstructural Imaging using Diffraction Analysis Software
+
+Materials Physics and Engineering
+Computational X-ray Science
+Advanced Photon Source
+Argonne National Laboratory
+
+Contributing Authors:
+Hemant Sharma (hsharma@anl.gov)
+
+OPEN SOURCE LICENSE
+ 
+Redistribution and use in source and binary forms, with or without  
+modification, are permitted provided that the following conditions are met:
+ 
+1. Redistributions of source code must retain the above copyright notice,  
+   this list of conditions and the following disclaimer.  Software changes,  
+   modifications, or derivative works, should be noted with comments and  
+   the author and organization's name.
+ 
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation  
+   and/or other materials provided with the distribution.
+ 
+3. Neither the names of UChicago Argonne, LLC or the Department of Energy  
+   nor the names of its contributors may be used to endorse or promote  
+   products derived from this software without specific prior written  
+   permission.
+ 
+4. The software and the end-user documentation included with the  
+   redistribution, if any, must include the following acknowledgment:
+ 
+   "This product includes software produced by UChicago Argonne, LLC  
+   under Contract No. DE-AC02-06CH11357 with the Department of Energy."
+ 
+****************************************************************************
+ 
+DISCLAIMER
+ 
+THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND.
+ 
+Neither the United States GOVERNMENT, nor the United States Department  
+of Energy, NOR UChicago Argonne, LLC, nor any of their employees, makes  
+any warranty, express or implied, or assumes any legal liability or  
+responsibility for the accuracy, completeness, or usefulness of any  
+information, data, apparatus, product, or process disclosed, or  
+represents that its use would not infringe privately owned rights.
+ 
+****************************************************************************

midas_pdf-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: midas-pdf
+Version: 0.1.0
+Summary: Differentiable, error-propagating total-scattering / pair-distribution-function (PDF, G(r)) pipeline. Thin Faber-Ziman layer over midas-hkls (form factors) and midas-integrate-v2 (integration, Compton, sine FT).
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/marinerhemant/MIDAS
+Project-URL: Issues, https://github.com/marinerhemant/MIDAS/issues
+Keywords: MIDAS,X-ray,total scattering,pair distribution function,PDF,G(r),delta-PDF,Faber-Ziman,differentiable,PyTorch,uncertainty propagation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: torch>=2.1
+Requires-Dist: midas-hkls>=0.5.0
+Requires-Dist: midas-integrate-v2>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: matplotlib>=3.6; extra == "dev"
+Provides-Extra: bayes
+Requires-Dist: pyro-ppl>=1.9.0; extra == "bayes"
+Dynamic: license-file
+
+# midas-pdf
+
+**Differentiable, error-propagating total-scattering / pair-distribution-function
+(PDF, *G(r)*) pipeline.**
+
+`midas-pdf` is a deliberately thin layer. Almost everything it needs already
+exists elsewhere in MIDAS and is reused rather than reimplemented:
+
+| Stage | Provided by | Status |
+|-------|-------------|--------|
+| detector geometry + wavelength (+ covariance) | `midas-calibrate-v2` | existing |
+| pixels → I(Q) with σ (polygon-exact, pol/solid-angle/dark) | `midas-integrate-v2` | existing |
+| atomic form factors f(Q), anomalous f′,f″ (differentiable) | `midas-hkls` | existing |
+| Compton / incoherent subtraction | `midas-integrate-v2.corrections.compton` | existing |
+| S(Q) → G(r) sine FT **with σ propagation** | `midas-integrate-v2.pdf` | existing |
+| **polyatomic Faber-Ziman normalization** ⟨f²⟩, ⟨f⟩² | **`midas-pdf` (new)** | this package |
+| **Δ-PDF (difference PDF) for time-resolved/operando** | **`midas-pdf` (new)** | this package |
+
+The single piece that did not exist anywhere was the **composition layer**: the
+existing `midas_integrate_v2.pdf.normalize_to_S` is *monoatomic* (it divides by a
+single ⟨f²⟩). Real total scattering of a polyatomic sample needs the Faber-Ziman
+form, which requires both ⟨f²⟩(Q) and ⟨f⟩²(Q) built from the sample composition.
+That bridge — and the Δ-PDF helper — is all `midas-pdf` adds.
+
+## What is novel
+
+Every arrow in the chain is a torch operation carrying a 1σ uncertainty, so the
+pipeline is **end-to-end differentiable** *and* **end-to-end error-propagating** —
+a combination no production total-scattering tool (PDFgetX3 / PDFgetN / GudrunX)
+offers. Concretely this enables:
+
+* gradient-based **normalization refinement** (`refine.py`): `scale`/`offset`/ρ₀
+  are fit by L-BFGS against model-free physics (⟨S⟩→1 at high Q, G(r)=−4πρ₀r at
+  low r) — the "ad hoc scale twiddling" of PDF analysis becomes an optimization;
+* an analytic 1σ band on every G(r) point, **validated** against a Monte-Carlo
+  bootstrap to <1% (`dev/demo_sigma_validation.py`) — error propagation is the
+  one thing existing software tends to drop;
+* statistically-meaningful **Δ-PDF** difference maps for time-resolved studies:
+  σ²(ΔG) = σ²(G₁) + σ²(G₂), so a feature change can be tested against noise;
+* differentiability in atomic positions (`validate.py`, Debye equation), so the
+  same code is a forward model for structure refinement against G(r).
+
+## Modules
+
+| Module | Contents |
+|--------|----------|
+| `composition.py` | `Composition` → ⟨f⟩(Q), ⟨f²⟩(Q), Laue term, Compton |
+| `compton.py` | Hubbell tabulated incoherent scattering + Breit-Dirac recoil |
+| `corrections.py` | Q-dependent detector efficiency, flat-plate self-absorption (MAC-backed) |
+| `fluorescence.py` | `expected_fluorescence`: which elements fluoresce at a given energy |
+| `multiple_scattering.py` | `lumped_background`: Tier-1 smooth MS/fluorescence/air background |
+| `cross_section.py` | `differential_cross_section`: per-atom dσ/dΩ(Q) (MS engine) |
+| `ms.py` | first-principles MS: analytic single + double scattering, Monte-Carlo references (slab + cylinder) |
+| `ms_transport.py` | all-orders MS by differentiable discrete-ordinates radiative transfer (slab) |
+| `structure.py` | differentiable small-box PDF (PDFfit-style) forward model + error-aware refinement |
+| `normalize.py` | `faber_ziman_S`: I(Q) → S(Q) with σ (and lumped `background`) |
+
+Runnable, one-per-capability demonstrations live in [`examples/`](examples/).
+| `gr.py` | re-export of the reused sine FT (S(Q) → G(r) with σ) |
+| `pipeline.py` | `i_of_q_to_Gr`: I(Q) → G(r) end to end |
+| `frontend.py` | `image_to_iq`, `image_to_Gr`: detector pixels → G(r) |
+| `conventions.py` | `structure_function_F`, `pair_distribution_g`, `total_correlation_T`, `radial_distribution_R` |
+| `refine.py` | `refine_normalization`: differentiable scale/offset/ρ₀ fit |
+| `deltapdf.py` | `delta_pdf`, `significant_mask`: difference PDF + n-σ test |
+| `validate.py` | `debye_scattering_intensity`, `synthetic_powder_image`: model-free references |
+
+## Quick start
+
+```python
+import torch
+from midas_pdf import Composition, i_of_q_to_Gr
+
+comp = Composition({"Si": 1, "O": 2})          # SiO2, number fractions
+q = torch.linspace(0.5, 25.0, 2000, dtype=torch.float64)
+r = torch.linspace(0.0, 10.0, 1000, dtype=torch.float64)
+
+# I_q, sigma_I come from midas-integrate-v2 (pixels -> I(Q) with sigma)
+G, sigma_G, S = i_of_q_to_Gr(
+    q, I_q, comp, r,
+    wavelength_A=0.1665, sigma_intensity=sigma_I,
+    compton=True, q_max=22.0,
+)
+```
+
+## Conventions
+
+Default is the **Faber-Ziman** total structure factor (X-ray, neutral-atom
+form factors), matching the PDFgetX3 default. `S(Q) → 1` as `Q → ∞`;
+`G(r) = (2/π) ∫ Q[S(Q)-1] sin(Qr) W(Q) dQ`. Window defaults to Lorch.
+Convention choice (FZ vs Keen; which of S/F/G/g/D/T to report) is intended to be
+settled with the experimental collaborators — see `dev/PLAN.md`.
+
+See `dev/PLAN.md` for the phased build plan and open items.

midas_pdf-0.1.0/README.md

@@ -0,0 +1,93 @@
+# midas-pdf
+
+**Differentiable, error-propagating total-scattering / pair-distribution-function
+(PDF, *G(r)*) pipeline.**
+
+`midas-pdf` is a deliberately thin layer. Almost everything it needs already
+exists elsewhere in MIDAS and is reused rather than reimplemented:
+
+| Stage | Provided by | Status |
+|-------|-------------|--------|
+| detector geometry + wavelength (+ covariance) | `midas-calibrate-v2` | existing |
+| pixels → I(Q) with σ (polygon-exact, pol/solid-angle/dark) | `midas-integrate-v2` | existing |
+| atomic form factors f(Q), anomalous f′,f″ (differentiable) | `midas-hkls` | existing |
+| Compton / incoherent subtraction | `midas-integrate-v2.corrections.compton` | existing |
+| S(Q) → G(r) sine FT **with σ propagation** | `midas-integrate-v2.pdf` | existing |
+| **polyatomic Faber-Ziman normalization** ⟨f²⟩, ⟨f⟩² | **`midas-pdf` (new)** | this package |
+| **Δ-PDF (difference PDF) for time-resolved/operando** | **`midas-pdf` (new)** | this package |
+
+The single piece that did not exist anywhere was the **composition layer**: the
+existing `midas_integrate_v2.pdf.normalize_to_S` is *monoatomic* (it divides by a
+single ⟨f²⟩). Real total scattering of a polyatomic sample needs the Faber-Ziman
+form, which requires both ⟨f²⟩(Q) and ⟨f⟩²(Q) built from the sample composition.
+That bridge — and the Δ-PDF helper — is all `midas-pdf` adds.
+
+## What is novel
+
+Every arrow in the chain is a torch operation carrying a 1σ uncertainty, so the
+pipeline is **end-to-end differentiable** *and* **end-to-end error-propagating** —
+a combination no production total-scattering tool (PDFgetX3 / PDFgetN / GudrunX)
+offers. Concretely this enables:
+
+* gradient-based **normalization refinement** (`refine.py`): `scale`/`offset`/ρ₀
+  are fit by L-BFGS against model-free physics (⟨S⟩→1 at high Q, G(r)=−4πρ₀r at
+  low r) — the "ad hoc scale twiddling" of PDF analysis becomes an optimization;
+* an analytic 1σ band on every G(r) point, **validated** against a Monte-Carlo
+  bootstrap to <1% (`dev/demo_sigma_validation.py`) — error propagation is the
+  one thing existing software tends to drop;
+* statistically-meaningful **Δ-PDF** difference maps for time-resolved studies:
+  σ²(ΔG) = σ²(G₁) + σ²(G₂), so a feature change can be tested against noise;
+* differentiability in atomic positions (`validate.py`, Debye equation), so the
+  same code is a forward model for structure refinement against G(r).
+
+## Modules
+
+| Module | Contents |
+|--------|----------|
+| `composition.py` | `Composition` → ⟨f⟩(Q), ⟨f²⟩(Q), Laue term, Compton |
+| `compton.py` | Hubbell tabulated incoherent scattering + Breit-Dirac recoil |
+| `corrections.py` | Q-dependent detector efficiency, flat-plate self-absorption (MAC-backed) |
+| `fluorescence.py` | `expected_fluorescence`: which elements fluoresce at a given energy |
+| `multiple_scattering.py` | `lumped_background`: Tier-1 smooth MS/fluorescence/air background |
+| `cross_section.py` | `differential_cross_section`: per-atom dσ/dΩ(Q) (MS engine) |
+| `ms.py` | first-principles MS: analytic single + double scattering, Monte-Carlo references (slab + cylinder) |
+| `ms_transport.py` | all-orders MS by differentiable discrete-ordinates radiative transfer (slab) |
+| `structure.py` | differentiable small-box PDF (PDFfit-style) forward model + error-aware refinement |
+| `normalize.py` | `faber_ziman_S`: I(Q) → S(Q) with σ (and lumped `background`) |
+
+Runnable, one-per-capability demonstrations live in [`examples/`](examples/).
+| `gr.py` | re-export of the reused sine FT (S(Q) → G(r) with σ) |
+| `pipeline.py` | `i_of_q_to_Gr`: I(Q) → G(r) end to end |
+| `frontend.py` | `image_to_iq`, `image_to_Gr`: detector pixels → G(r) |
+| `conventions.py` | `structure_function_F`, `pair_distribution_g`, `total_correlation_T`, `radial_distribution_R` |
+| `refine.py` | `refine_normalization`: differentiable scale/offset/ρ₀ fit |
+| `deltapdf.py` | `delta_pdf`, `significant_mask`: difference PDF + n-σ test |
+| `validate.py` | `debye_scattering_intensity`, `synthetic_powder_image`: model-free references |
+
+## Quick start
+
+```python
+import torch
+from midas_pdf import Composition, i_of_q_to_Gr
+
+comp = Composition({"Si": 1, "O": 2})          # SiO2, number fractions
+q = torch.linspace(0.5, 25.0, 2000, dtype=torch.float64)
+r = torch.linspace(0.0, 10.0, 1000, dtype=torch.float64)
+
+# I_q, sigma_I come from midas-integrate-v2 (pixels -> I(Q) with sigma)
+G, sigma_G, S = i_of_q_to_Gr(
+    q, I_q, comp, r,
+    wavelength_A=0.1665, sigma_intensity=sigma_I,
+    compton=True, q_max=22.0,
+)
+```
+
+## Conventions
+
+Default is the **Faber-Ziman** total structure factor (X-ray, neutral-atom
+form factors), matching the PDFgetX3 default. `S(Q) → 1` as `Q → ∞`;
+`G(r) = (2/π) ∫ Q[S(Q)-1] sin(Qr) W(Q) dQ`. Window defaults to Lorch.
+Convention choice (FZ vs Keen; which of S/F/G/g/D/T to report) is intended to be
+settled with the experimental collaborators — see `dev/PLAN.md`.
+
+See `dev/PLAN.md` for the phased build plan and open items.

midas_pdf-0.1.0/midas_pdf/__init__.py

@@ -0,0 +1,118 @@
+"""midas-pdf — differentiable, error-propagating total-scattering / G(r) pipeline.
+
+Thin Faber-Ziman normalization layer over ``midas-hkls`` (form factors) and
+``midas-integrate-v2`` (integration, Compton, sine FT with σ propagation).
+
+Typical use::
+
+    from midas_pdf import Composition, i_of_q_to_Gr, delta_pdf
+    comp = Composition({"Si": 1, "O": 2})
+    G, sigma_G, S = i_of_q_to_Gr(q, I_q, comp, r, wavelength_A=0.1665,
+                                 sigma_intensity=sigma_I, q_max=22.0)
+"""
+# macOS (and some Linux setups) can hit an OpenMP-duplicate abort at import
+# time because torch and numpy each ship their own libomp copy.  We set the
+# env var *before* torch loads so users get a clean import instead of a
+# cryptic runtime crash on their first line.  Users who prefer to control
+# it themselves can already have set it, in which case setdefault is a no-op.
+import os as _os
+_os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+from .composition import Composition
+from .compton import breit_dirac_factor, incoherent_scattering
+from .conventions import (
+    pair_distribution_g,
+    radial_distribution_R,
+    structure_function_F,
+    total_correlation_T,
+)
+from .corrections import (
+    apply_detector_efficiency,
+    detector_efficiency,
+    flat_plate_transmission,
+    linear_attenuation_um,
+)
+from .deltapdf import delta_pdf, significant_mask
+from .fluorescence import expected_fluorescence
+from .frontend import image_to_Gr, image_to_iq
+from .gr import G_of_r, R_px_to_Q, estimate_background, fourier_sine_transform
+from .cross_section import differential_cross_section, total_cross_section
+from .ms import (
+    CYLINDER_SLAB_FACTOR,
+    cylinder_effective_tau,
+    ms_background_on_grid,
+    multiple_scattering_mc,
+    multiple_scattering_mc_cylinder,
+    slab_double_scattering,
+    slab_optical_params,
+    slab_single_scattering_factor,
+)
+from .ms_transport import slab_transport_ms
+from .multiple_scattering import lumped_background, polynomial_basis
+from .structure import build_pair_list, pdffit_gr, refine_structure
+from .normalize import faber_ziman_S
+from .pipeline import i_of_q_to_Gr
+from .refine import RefineResult, refine_normalization
+from .validate import (
+    debye_scattering_intensity,
+    interatomic_distances,
+    synthetic_powder_image,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core
+    "Composition",
+    "faber_ziman_S",
+    "i_of_q_to_Gr",
+    "fourier_sine_transform",
+    "G_of_r",
+    "R_px_to_Q",
+    "estimate_background",
+    # front-end (pixels → G(r))
+    "image_to_iq",
+    "image_to_Gr",
+    # convention / output-function family
+    "structure_function_F",
+    "pair_distribution_g",
+    "total_correlation_T",
+    "radial_distribution_R",
+    # corrections (Hubbell Compton, detector efficiency, absorption, fluorescence)
+    "incoherent_scattering",
+    "breit_dirac_factor",
+    "detector_efficiency",
+    "apply_detector_efficiency",
+    "flat_plate_transmission",
+    "linear_attenuation_um",
+    "expected_fluorescence",
+    # multiple scattering (Tier-1 lumped smooth background)
+    "lumped_background",
+    "polynomial_basis",
+    # multiple scattering (Tier-2/3: cross-section + first-principles estimators)
+    "differential_cross_section",
+    "total_cross_section",
+    "slab_single_scattering_factor",
+    "slab_optical_params",
+    "multiple_scattering_mc",
+    "slab_double_scattering",
+    "slab_transport_ms",
+    "multiple_scattering_mc_cylinder",
+    "cylinder_effective_tau",
+    "CYLINDER_SLAB_FACTOR",
+    "ms_background_on_grid",
+    # differentiable refinement
+    "refine_normalization",
+    "RefineResult",
+    # small-box structure modelling (PDFfit-style, error-aware)
+    "pdffit_gr",
+    "build_pair_list",
+    "refine_structure",
+    # Δ-PDF
+    "delta_pdf",
+    "significant_mask",
+    # model-free references / forward model
+    "debye_scattering_intensity",
+    "interatomic_distances",
+    "synthetic_powder_image",
+]

midas_pdf-0.1.0/midas_pdf/aniso_refine.py

@@ -0,0 +1,206 @@
+"""Rev-15 anisotropic-ADP + partial-occupancy PDF refinement.
+
+The Rev-8 :func:`midas_pdf.structure.refine_structure` refines a single
+isotropic ``u_iso`` and full occupancy on every site.  Real fits of low-
+symmetry crystals, oxide superlattices, and solid solutions need:
+
+* per-site **anisotropic** displacement tensors ``U_ij`` (3×3 symmetric,
+  6 unique entries), and
+* per-site **partial occupancy** (defect-vacancy / solid-solution work).
+
+This module adds a differentiable L-BFGS refiner that co-refines those two
+sets of DOFs together with the cubic-lattice constant and PDF scale, and
+reports Hessian-derived 1σ on every DOF.  It preserves the diagonal
+constraint on ``U`` (only the six unique entries — ``U11 U22 U33 U12 U13 U23``
+— are stored and refined; the tensor is reconstructed symmetrically each
+forward pass).  A positive-definiteness soft penalty keeps the fit
+physical without needing a hard constraint.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import torch
+
+from .structure import PairList, pdffit_gr
+
+
+__all__ = [
+    "u_vector_to_matrix",
+    "u_matrix_to_vector",
+    "refine_aniso_occupancy",
+    "AnisoRefineResult",
+]
+
+
+def u_vector_to_matrix(u_vec: torch.Tensor) -> torch.Tensor:
+    """Expand (n_uc, 6) unique entries [U11 U22 U33 U12 U13 U23] to
+    (n_uc, 3, 3) symmetric tensors, differentiable."""
+    u = torch.as_tensor(u_vec, dtype=torch.float64)
+    if u.ndim != 2 or u.shape[1] != 6:
+        raise ValueError(f"u_vec must be (n_uc, 6), got {tuple(u.shape)}")
+    n = u.shape[0]
+    U = torch.zeros((n, 3, 3), dtype=torch.float64)
+    U[:, 0, 0] = u[:, 0]
+    U[:, 1, 1] = u[:, 1]
+    U[:, 2, 2] = u[:, 2]
+    U[:, 0, 1] = u[:, 3]; U[:, 1, 0] = u[:, 3]
+    U[:, 0, 2] = u[:, 4]; U[:, 2, 0] = u[:, 4]
+    U[:, 1, 2] = u[:, 5]; U[:, 2, 1] = u[:, 5]
+    return U
+
+
+def u_matrix_to_vector(U: torch.Tensor) -> torch.Tensor:
+    """Pack a (n_uc, 3, 3) symmetric tensor into (n_uc, 6) unique entries."""
+    U = torch.as_tensor(U, dtype=torch.float64)
+    if U.ndim != 3 or U.shape[1:] != (3, 3):
+        raise ValueError(f"U must be (n_uc, 3, 3), got {tuple(U.shape)}")
+    return torch.stack([U[:, 0, 0], U[:, 1, 1], U[:, 2, 2],
+                        U[:, 0, 1], U[:, 0, 2], U[:, 1, 2]], dim=1)
+
+
+class AnisoRefineResult(dict):
+    def __getattr__(self, name):
+        try: return self[name]
+        except KeyError: raise AttributeError(name) from None
+
+
+def refine_aniso_occupancy(
+    crystal_tensor,
+    r: torch.Tensor | np.ndarray,
+    G_obs: torch.Tensor | np.ndarray,
+    pairs: PairList,
+    *,
+    sigma_obs: Optional[torch.Tensor | np.ndarray] = None,
+    init_a: Optional[float] = None,
+    init_u_iso: float = 0.006,
+    init_scale: float = 1.0,
+    refine_aniso: bool = True,
+    refine_occupancy: bool = False,
+    steps: int = 200,
+    lr: float = 0.05,
+    positive_definite_penalty: float = 1e3,
+) -> AnisoRefineResult:
+    """Co-refine cubic-``a``, ``scale``, per-site aniso ADPs and (optional)
+    per-site occupancy against ``G_obs``.
+
+    Parameter layout is:
+
+        θ = [a, scale] + (6 * n_uc aniso entries if refine_aniso else 0)
+                       + (n_uc occupancies if refine_occupancy else 0)
+
+    On ``refine_aniso=False`` the fit still uses ``u_iso`` on every site so
+    the interface stays uniform.  The positive-definite penalty adds
+    ``λ · sum(relu(-eigvals(U)))²`` to χ² — cheap, differentiable, and
+    it turns off automatically once every U is p.d.
+    """
+    r_t = torch.as_tensor(r, dtype=torch.float64)
+    G_t = torch.as_tensor(G_obs, dtype=torch.float64)
+    w = (torch.ones_like(G_t) if sigma_obs is None
+         else 1.0 / torch.as_tensor(sigma_obs, dtype=torch.float64).clamp(min=1e-12) ** 2)
+
+    lat0 = crystal_tensor.lattice_params.detach()
+    angles = lat0[3:]
+    a0 = float(lat0[0]) if init_a is None else float(init_a)
+    n_uc = pairs.n_uc
+
+    theta_parts = [torch.tensor([a0, init_scale], dtype=torch.float64)]
+    n_aniso = 6 * n_uc if refine_aniso else 0
+    if refine_aniso:
+        u_init = torch.tensor([init_u_iso, init_u_iso, init_u_iso, 0.0, 0.0, 0.0],
+                              dtype=torch.float64)
+        theta_parts.append(u_init.repeat(n_uc))
+    n_occ = n_uc if refine_occupancy else 0
+    if refine_occupancy:
+        theta_parts.append(torch.ones(n_uc, dtype=torch.float64))
+    theta = torch.cat(theta_parts).clone().requires_grad_(True)
+
+    def unpack(th):
+        a = th[0]
+        scale = th[1]
+        idx = 2
+        u_aniso = None
+        occupancy = None
+        if refine_aniso:
+            u_flat = th[idx:idx + n_aniso].reshape(n_uc, 6)
+            u_aniso = u_vector_to_matrix(u_flat)
+            idx += n_aniso
+        if refine_occupancy:
+            occupancy = th[idx:idx + n_occ].clamp(min=0.0, max=1.0)
+            idx += n_occ
+        return a, scale, u_aniso, occupancy
+
+    def model(th):
+        a, scale, u_aniso, occupancy = unpack(th)
+        lp = torch.cat([a.reshape(1).expand(3), angles])
+        kwargs = {"lattice_params": lp, "scale": scale}
+        if u_aniso is not None:
+            kwargs["u_aniso"] = u_aniso
+        else:
+            kwargs["u_iso"] = init_u_iso
+        if occupancy is not None:
+            kwargs["occupancy"] = occupancy
+        return pdffit_gr(crystal_tensor, r_t, pairs, **kwargs)
+
+    def chi2(th):
+        res = G_t - model(th)
+        loss = (w * res * res).sum()
+        if refine_aniso and positive_definite_penalty > 0.0:
+            _, _, u_aniso, _ = unpack(th)
+            eigs = torch.linalg.eigvalsh(u_aniso)                        # (n_uc, 3)
+            neg = torch.relu(-eigs)
+            loss = loss + positive_definite_penalty * (neg * neg).sum()
+        return loss
+
+    opt = torch.optim.LBFGS([theta], lr=lr, max_iter=steps,
+                             line_search_fn="strong_wolfe")
+    history: list[float] = []
+
+    def closure():
+        opt.zero_grad()
+        loss = chi2(theta)
+        loss.backward()
+        history.append(float(loss.detach()))
+        return loss
+
+    opt.step(closure)
+
+    with torch.no_grad():
+        th_det = theta.detach()
+        a_val, scale_val, u_aniso_val, occ_val = unpack(th_det)
+        G_fit = model(th_det)
+        ndof = max(int(G_t.numel()) - theta.numel(), 1)
+        chi2_red = float((w * (G_t - G_fit) ** 2).sum()) / ndof
+
+    # Hessian uncertainties (may be huge for weakly-identified aniso entries).
+    uncert = {}
+    try:
+        th_leaf = theta.detach().clone().requires_grad_(True)
+        H = torch.autograd.functional.hessian(chi2, th_leaf)
+        cov = 2.0 * torch.linalg.pinv(H)
+        sig = torch.sqrt(torch.diagonal(cov).clamp(min=0.0))
+        uncert["a"] = float(sig[0])
+        uncert["scale"] = float(sig[1])
+        idx = 2
+        if refine_aniso:
+            uncert["u_aniso"] = sig[idx:idx + n_aniso].reshape(n_uc, 6).tolist()
+            idx += n_aniso
+        if refine_occupancy:
+            uncert["occupancy"] = sig[idx:idx + n_occ].tolist()
+    except Exception:
+        uncert = {"error": "Hessian failed"}
+
+    return AnisoRefineResult(
+        fitted={
+            "a": float(a_val),
+            "scale": float(scale_val),
+            "u_aniso": u_aniso_val.tolist() if u_aniso_val is not None else None,
+            "occupancy": occ_val.tolist() if occ_val is not None else None,
+        },
+        uncertainty=uncert,
+        G_calc=G_fit.detach(),
+        chi2_reduced=chi2_red,
+        loss=history[-1] if history else float("nan"),
+        history=history, loss_history=history,
+    )