midas-saxs 0.1.0__tar.gz

midas_saxs-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, UChicago Argonne, LLC, operator of Argonne National
+Laboratory, and the midas-diffract authors.
+All rights reserved.
+
+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.
+
+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 name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

midas_saxs-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: midas-saxs
+Version: 0.1.0
+Summary: Differentiable small-angle X-ray scattering for MIDAS: particle form factors and polydispersity, plus a 2-D detector-image forward model for dislocation loops and voids driven by a discrete-dislocation network.
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/marinerhemant/MIDAS
+Project-URL: Documentation, https://github.com/marinerhemant/MIDAS/tree/master/packages/midas_saxs
+Project-URL: Issues, https://github.com/marinerhemant/MIDAS/issues
+Keywords: MIDAS,SAXS,USAXS,small-angle scattering,X-ray,dislocation loop,irradiation,void,form factor,differentiable,PyTorch
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: torch>=2.0
+Requires-Dist: midas-hkls>=0.9.0
+Requires-Dist: midas-transforms>=0.10.0
+Requires-Dist: midas-distortion>=0.2.0
+Provides-Extra: dislocations
+Requires-Dist: midas-ddd>=0.1.0; extra == "dislocations"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+Requires-Dist: midas-ddd>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# midas-saxs
+
+Differentiable small-angle X-ray scattering for MIDAS. Two source terms, one
+detector:
+
+- **Density contrast** — voids, gas bubbles, precipitates. Sphere / ellipsoid /
+  cylinder form factors, lognormal polydispersity, Percus-Yevick `S(Q)`, Guinier
+  and Porod analysis. These came from `midas_pdf.saxs`, which now re-exports them
+  from here, so MIDAS has one definition of "SAXS form factor".
+- **Strain contrast** — dislocation loops, driven by a `midas_ddd` network read
+  from ExaDiS. Optional extra: `pip install 'midas-saxs[dislocations]'`.
+
+```python
+from midas_saxs import SAXSGeometry, SpherePopulation, simulate_frame
+
+geom = SAXSGeometry(lsd_um=2.0e6, bcy_px=512, bcz_px=512, px_um=75.0,
+                    wavelength_A=0.7293, n_pix_y=1024, n_pix_z=1024,
+                    beamstop_radius_px=30)
+voids = SpherePopulation(radius_A=50.0, number_density_per_A3=1e-8,
+                         delta_rho_e_per_A3=-2.45, label="voids")
+frame = simulate_frame(geom, particles=[voids], sample_volume_A3=1e15)
+```
+
+`dev/paper/loop_vs_void_demo.py` renders the five-panel figure that motivates the
+whole package.
+
+## Read this before promising anyone a loop measurement
+
+Three numbers, all reproducible from the demo script.
+
+**1. Loops are faint.** A dislocation loop of radius R displaces only its
+relaxation volume `pi R^2 b`; a void of the same radius displaces
+`4 pi R^3 / 3`. For R = 5 nm in Cu that is 26x in volume and **680x in forward
+intensity**. The loop scatters like a *sphere of radius 1.7 nm*.
+
+**2. What separates a loop from a void is shape, not size.** The loop's
+small-angle amplitude is direction-dependent — `kappa dV` in its own plane,
+`dV` along its normal, with `kappa = lambda/(lambda + 2 mu)`. Intensity is
+therefore modulated by `1 - kappa^2` (0.84 for `lambda = 100, mu = 75`). A void
+is isotropic. **Radially averaging a frame destroys exactly this**, which is why
+this package renders 2-D frames and offers `azimuthal_profile` alongside
+`radial_average`.
+
+**3. Real voids bury the signature.** Measured on the demo: 24 aligned loops
+alone give an azimuthal contrast of **6.30x** (the closed form predicts
+`1/kappa^2 = 6.25`). Add equal-radius voids at the same number density — the
+physically realistic irradiated case — and the contrast collapses to **1.002x**,
+with the voids outshining the loops by **1089x** integrated over the frame.
+
+So: loops are detectable at small angle in a clean matrix, and essentially
+undetectable alongside a void or bubble population of comparable size. If the
+question is defect-type discrimination in an irradiated material, near-Bragg
+diffuse (Huang) scattering is stronger than the small-angle signal by
+`(G/q)^2` ~ 1e4 to 1e7 and is the better measurement.
+
+## Scope
+
+**Closed dislocation loops only.** A cut surface exists only for a closed
+circuit. Open lines — the *deformation* population — enclose no area, carry no
+relaxation volume, and contribute nothing as `q -> 0`; their small-angle
+signature is a weak transverse streak that is not modelled. `simulate_frame`
+reports how much line length it ignored rather than returning a number that
+looks complete.
+
+## Units
+
+| Quantity | Unit |
+|---|---|
+| distances, geometry | micrometers |
+| wavelength, particle radii, electron density | angstroms |
+| `q` from `midas_saxs.geometry` | **inverse angstroms** |
+| `q` into the `midas_ddd` kernel | **inverse micrometers** |
+
+The 1e4 between the last two is easy to lose, so `inv_A_to_inv_um` /
+`inv_um_to_inv_A` exist and `strain_source` uses them rather than a literal.
+
+## Detector geometry
+
+`pixel_to_q` goes through `midas_transforms.apply_tilt_distortion` — the same
+tilt (`R_z R_y R_x`) and 15-coefficient distortion model the HEDM side uses.
+That is deliberate: a SAXS geometry and an FF geometry calibrated from the same
+detector must agree about where q sits. Transmission SAXS has no omega, so lab q
+is sample q.
+
+## Migration note
+
+`form_factors`, `model`, `wide_band` and `core_shell` moved here from
+`midas_pdf.saxs`. Both the package-level path (`from midas_pdf.saxs import
+SAXSModel`) and the deep path (`from midas_pdf.saxs.form_factors import ...`)
+still resolve, to the same objects — asserted by
+`test_midas_pdf_reexports_the_same_objects`. `midas_pdf.saxs` keeps the genuinely
+PDF-coupled part: joint SAXS + PDF refinement and its Bayesian variants.
+
+One convention worth knowing: `sphere_form_factor_squared` returns `V^2 |F|^2`,
+**not** the normalised `|F|^2`. `SpherePopulation.intensity` multiplies it by
+`n * delta_rho^2` and nothing else, which is only correct because the volume is
+already in there.

midas_saxs-0.1.0/README.md

@@ -0,0 +1,97 @@
+# midas-saxs
+
+Differentiable small-angle X-ray scattering for MIDAS. Two source terms, one
+detector:
+
+- **Density contrast** — voids, gas bubbles, precipitates. Sphere / ellipsoid /
+  cylinder form factors, lognormal polydispersity, Percus-Yevick `S(Q)`, Guinier
+  and Porod analysis. These came from `midas_pdf.saxs`, which now re-exports them
+  from here, so MIDAS has one definition of "SAXS form factor".
+- **Strain contrast** — dislocation loops, driven by a `midas_ddd` network read
+  from ExaDiS. Optional extra: `pip install 'midas-saxs[dislocations]'`.
+
+```python
+from midas_saxs import SAXSGeometry, SpherePopulation, simulate_frame
+
+geom = SAXSGeometry(lsd_um=2.0e6, bcy_px=512, bcz_px=512, px_um=75.0,
+                    wavelength_A=0.7293, n_pix_y=1024, n_pix_z=1024,
+                    beamstop_radius_px=30)
+voids = SpherePopulation(radius_A=50.0, number_density_per_A3=1e-8,
+                         delta_rho_e_per_A3=-2.45, label="voids")
+frame = simulate_frame(geom, particles=[voids], sample_volume_A3=1e15)
+```
+
+`dev/paper/loop_vs_void_demo.py` renders the five-panel figure that motivates the
+whole package.
+
+## Read this before promising anyone a loop measurement
+
+Three numbers, all reproducible from the demo script.
+
+**1. Loops are faint.** A dislocation loop of radius R displaces only its
+relaxation volume `pi R^2 b`; a void of the same radius displaces
+`4 pi R^3 / 3`. For R = 5 nm in Cu that is 26x in volume and **680x in forward
+intensity**. The loop scatters like a *sphere of radius 1.7 nm*.
+
+**2. What separates a loop from a void is shape, not size.** The loop's
+small-angle amplitude is direction-dependent — `kappa dV` in its own plane,
+`dV` along its normal, with `kappa = lambda/(lambda + 2 mu)`. Intensity is
+therefore modulated by `1 - kappa^2` (0.84 for `lambda = 100, mu = 75`). A void
+is isotropic. **Radially averaging a frame destroys exactly this**, which is why
+this package renders 2-D frames and offers `azimuthal_profile` alongside
+`radial_average`.
+
+**3. Real voids bury the signature.** Measured on the demo: 24 aligned loops
+alone give an azimuthal contrast of **6.30x** (the closed form predicts
+`1/kappa^2 = 6.25`). Add equal-radius voids at the same number density — the
+physically realistic irradiated case — and the contrast collapses to **1.002x**,
+with the voids outshining the loops by **1089x** integrated over the frame.
+
+So: loops are detectable at small angle in a clean matrix, and essentially
+undetectable alongside a void or bubble population of comparable size. If the
+question is defect-type discrimination in an irradiated material, near-Bragg
+diffuse (Huang) scattering is stronger than the small-angle signal by
+`(G/q)^2` ~ 1e4 to 1e7 and is the better measurement.
+
+## Scope
+
+**Closed dislocation loops only.** A cut surface exists only for a closed
+circuit. Open lines — the *deformation* population — enclose no area, carry no
+relaxation volume, and contribute nothing as `q -> 0`; their small-angle
+signature is a weak transverse streak that is not modelled. `simulate_frame`
+reports how much line length it ignored rather than returning a number that
+looks complete.
+
+## Units
+
+| Quantity | Unit |
+|---|---|
+| distances, geometry | micrometers |
+| wavelength, particle radii, electron density | angstroms |
+| `q` from `midas_saxs.geometry` | **inverse angstroms** |
+| `q` into the `midas_ddd` kernel | **inverse micrometers** |
+
+The 1e4 between the last two is easy to lose, so `inv_A_to_inv_um` /
+`inv_um_to_inv_A` exist and `strain_source` uses them rather than a literal.
+
+## Detector geometry
+
+`pixel_to_q` goes through `midas_transforms.apply_tilt_distortion` — the same
+tilt (`R_z R_y R_x`) and 15-coefficient distortion model the HEDM side uses.
+That is deliberate: a SAXS geometry and an FF geometry calibrated from the same
+detector must agree about where q sits. Transmission SAXS has no omega, so lab q
+is sample q.
+
+## Migration note
+
+`form_factors`, `model`, `wide_band` and `core_shell` moved here from
+`midas_pdf.saxs`. Both the package-level path (`from midas_pdf.saxs import
+SAXSModel`) and the deep path (`from midas_pdf.saxs.form_factors import ...`)
+still resolve, to the same objects — asserted by
+`test_midas_pdf_reexports_the_same_objects`. `midas_pdf.saxs` keeps the genuinely
+PDF-coupled part: joint SAXS + PDF refinement and its Bayesian variants.
+
+One convention worth knowing: `sphere_form_factor_squared` returns `V^2 |F|^2`,
+**not** the normalised `|F|^2`. `SpherePopulation.intensity` multiplies it by
+`n * delta_rho^2` and nothing else, which is only correct because the volume is
+already in there.

midas_saxs-0.1.0/midas_saxs/__init__.py

@@ -0,0 +1,105 @@
+"""midas-saxs — differentiable small-angle X-ray scattering for MIDAS.
+
+Two source terms, one detector.
+
+**Density contrast** (:mod:`midas_saxs.particles`, :mod:`midas_saxs.form_factors`,
+:mod:`midas_saxs.model`, :mod:`midas_saxs.core_shell`, :mod:`midas_saxs.wide_band`)
+— voids, bubbles, precipitates; sphere / ellipsoid / cylinder form factors,
+lognormal polydispersity, Percus-Yevick S(Q), Guinier and Porod analysis. These
+came from ``midas_pdf.saxs``, which now re-exports them from here, so there is
+one definition of "SAXS form factor" in MIDAS.
+
+**Strain contrast** (:mod:`midas_saxs.strain_source`) — dislocation loops, driven
+by a :mod:`midas_ddd` network read from ExaDiS. Optional extra; plain particle
+SAXS does not pull a dislocation-dynamics stack.
+
+    pip install 'midas-saxs[dislocations]'
+
+Quick start
+-----------
+    from midas_saxs import SAXSGeometry, SpherePopulation, simulate_frame
+
+    geom = SAXSGeometry(lsd_um=2.0e6, bcy_px=512, bcz_px=512, px_um=75.0,
+                        wavelength_A=0.7293, n_pix_y=1024, n_pix_z=1024,
+                        beamstop_radius_px=30)
+    voids = SpherePopulation(radius_A=50.0, number_density_per_A3=1e-32,
+                             delta_rho_e_per_A3=-2.2, label="voids")
+    frame = simulate_frame(geom, particles=[voids], sample_volume_A3=1e15)
+
+The one number to keep in mind
+------------------------------
+A dislocation loop of radius R displaces only its relaxation volume
+``pi R^2 b``, while a void of the same radius displaces ``4 pi R^3 / 3``. At
+R = 5 nm in Cu that is a factor 27 in volume and ~700 in forward intensity. If
+an irradiated sample has voids or bubbles, they dominate the small-angle image,
+and a dislocation-only simulation will not resemble the measurement.
+
+What distinguishes them is not magnitude but **shape**: voids are isotropic,
+loops are not (``kappa dV`` in-plane versus ``dV`` along the normal, with
+``kappa = lambda/(lambda + 2 mu)``). That lives on the 2-D frame and is destroyed
+by radial averaging — see :func:`midas_saxs.detector.azimuthal_profile`.
+"""
+
+__version__ = "0.1.0"
+
+from .core_shell import (
+    core_shell_sphere_form_factor_squared,
+    multi_shell_sphere_form_factor_squared,
+)
+from .detector import (
+    Frame,
+    azimuthal_profile,
+    radial_average,
+    simulate_frame,
+)
+from .form_factors import (
+    cylinder_form_factor_squared,
+    ellipsoid_form_factor_squared,
+    percus_yevick_S,
+    sphere_form_factor_squared,
+)
+from .geometry import (
+    SAXSGeometry,
+    inv_A_to_inv_um,
+    inv_um_to_inv_A,
+    pixel_to_q,
+    q_magnitude_grid,
+    two_theta_to_q,
+)
+from .model import SAXSModel, lognormal_quadrature_nodes
+from .particles import (
+    SpherePopulation,
+    loop_equivalent_sphere_radius_A,
+    void_intensity,
+)
+from .wide_band import (
+    GuinierFit,
+    PorodFit,
+    guinier_fit,
+    kratky_plot,
+    porod_fit,
+    porod_invariant,
+    worm_like_chain_form_factor_squared,
+)
+
+# `midas_saxs.strain_source` is NOT imported here: it needs midas_ddd, which is
+# an optional extra. Import it explicitly, or go through `simulate_frame`, which
+# only reaches for it when a network is actually passed.
+
+__all__ = [
+    # geometry
+    "SAXSGeometry", "pixel_to_q", "q_magnitude_grid", "two_theta_to_q",
+    "inv_A_to_inv_um", "inv_um_to_inv_A",
+    # detector
+    "Frame", "simulate_frame", "radial_average", "azimuthal_profile",
+    # particles
+    "SpherePopulation", "void_intensity", "loop_equivalent_sphere_radius_A",
+    # form factors (migrated from midas_pdf.saxs)
+    "sphere_form_factor_squared", "ellipsoid_form_factor_squared",
+    "cylinder_form_factor_squared", "percus_yevick_S",
+    "core_shell_sphere_form_factor_squared", "multi_shell_sphere_form_factor_squared",
+    "SAXSModel", "lognormal_quadrature_nodes",
+    "GuinierFit", "guinier_fit", "PorodFit", "porod_fit", "porod_invariant",
+    "kratky_plot", "worm_like_chain_form_factor_squared",
+    "__version__",
+]

midas_saxs-0.1.0/midas_saxs/core_shell.py

@@ -0,0 +1,122 @@
+"""Core-shell and multi-shell SAXS form factors.
+
+The single-density sphere / ellipsoid / cylinder in
+:mod:`midas_saxs.form_factors` model a uniform-density particle.
+Many real nanoparticles are structured:
+
+  * Coated nanoparticles: metallic core + oxide / ligand shell.
+  * Reverse micelles: solvent core + amphiphile shell.
+  * Multi-shell nanocrystals: layered lattice + interface + surface region.
+
+For these, the SAXS form factor is a difference of nested-sphere
+amplitudes weighted by the contrast (electron-density difference)
+in each layer.
+
+For a two-shell (core + shell) spherical particle:
+
+    F(Q) = 4π (ρ_core − ρ_shell) V_core · j₁(Q R_core) / (Q R_core)
+         + 4π (ρ_shell − ρ_solvent) V_total · j₁(Q R_total) / (Q R_total)
+
+where ``j₁`` is the spherical Bessel of order 1 and V is the volume of
+each region. This generalises to N shells recursively.
+
+All routines here return **|F(Q)|²** and are torch-differentiable in the
+shell radii and contrast ratios.
+"""
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+import numpy as np
+import torch
+
+_FOUR_PI = 4.0 * float(np.pi)
+
+
+def _sphere_amplitude(q: torch.Tensor, R: torch.Tensor) -> torch.Tensor:
+    """Complex spherical-shell amplitude at Q = 0 is V (the volume).
+
+    Returns ``F(Q, R) = V · 3 [sin(QR) − QR cos(QR)] / (QR)³``
+    with a stable Q → 0 limit.
+    """
+    V = _FOUR_PI * R ** 3 / 3.0
+    x = q * R
+    small = x.abs() < 1e-3
+    # small-x: 1 − x²/10 + x⁴/280
+    shape_small = 1.0 - x ** 2 / 10.0 + x ** 4 / 280.0
+    x_safe = x.clamp(min=1e-9)
+    shape_general = 3.0 * (torch.sin(x_safe) - x_safe * torch.cos(x_safe)) / x_safe ** 3
+    return V * torch.where(small, shape_small, shape_general)
+
+
+def core_shell_sphere_form_factor_squared(
+    q: torch.Tensor,
+    R_core_A: float | torch.Tensor,
+    R_total_A: float | torch.Tensor,
+    contrast_core: float | torch.Tensor = 1.0,
+    contrast_shell: float | torch.Tensor = 0.5,
+) -> torch.Tensor:
+    """|F(Q)|² for a core-shell spherical particle.
+
+    Parameters
+    ----------
+    R_core_A : radius of the core (Å).
+    R_total_A : outer radius (core + shell, Å); shell thickness =
+        R_total − R_core.
+    contrast_core : electron-density difference (core − solvent), arbitrary
+        units. Only the ratio (core − shell)/(shell − solvent) matters
+        for the shape of I(Q); the absolute scale drops into the caller's
+        overall scale factor.
+    contrast_shell : electron-density difference (shell − solvent).
+
+    Returns
+    -------
+    |F(Q)|² of the same units as (contrast · ų)².
+    """
+    q_t = torch.as_tensor(q, dtype=torch.float64)
+    R_c = torch.as_tensor(R_core_A, dtype=torch.float64)
+    R_t = torch.as_tensor(R_total_A, dtype=torch.float64)
+    delta_core  = torch.as_tensor(contrast_core,  dtype=torch.float64) \
+                  - torch.as_tensor(contrast_shell, dtype=torch.float64)
+    delta_shell = torch.as_tensor(contrast_shell, dtype=torch.float64)
+    F_core  = _sphere_amplitude(q_t, R_c)
+    F_total = _sphere_amplitude(q_t, R_t)
+    F = delta_core * F_core + delta_shell * F_total
+    return F ** 2
+
+
+def multi_shell_sphere_form_factor_squared(
+    q: torch.Tensor,
+    radii_A: Sequence[float | torch.Tensor],
+    contrasts: Sequence[float | torch.Tensor],
+) -> torch.Tensor:
+    """|F(Q)|² for a multi-shell spherical particle.
+
+    ``radii_A``: list of *outer* radii of each shell (monotonically
+    increasing).  E.g. for a 3-shell particle, ``[R_1, R_2, R_3]``.
+
+    ``contrasts``: contrast of *each* shell against the solvent (same
+    length as ``radii_A``).  The interfacial contrast between successive
+    shells drives the SAXS signal.
+    """
+    q_t = torch.as_tensor(q, dtype=torch.float64)
+    if len(radii_A) != len(contrasts):
+        raise ValueError("len(radii_A) must equal len(contrasts)")
+    if len(radii_A) < 1:
+        raise ValueError("need at least one shell")
+    # F = sum_i (ρ_i − ρ_{i+1}) F_i, with ρ_{N+1} = solvent ≡ 0
+    F = torch.zeros_like(q_t)
+    for i in range(len(radii_A)):
+        rho_here = torch.as_tensor(contrasts[i], dtype=torch.float64)
+        rho_next = (torch.as_tensor(contrasts[i + 1], dtype=torch.float64)
+                    if i + 1 < len(contrasts) else torch.tensor(0.0, dtype=torch.float64))
+        delta = rho_here - rho_next
+        R = torch.as_tensor(radii_A[i], dtype=torch.float64)
+        F = F + delta * _sphere_amplitude(q_t, R)
+    return F ** 2
+
+
+__all__ = [
+    "core_shell_sphere_form_factor_squared",
+    "multi_shell_sphere_form_factor_squared",
+]