midas-dfxm 0.1.0__tar.gz

midas_dfxm-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_dfxm-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: midas-dfxm
+Version: 0.1.0
+Summary: Differentiable forward + inverse for Dark-Field X-ray Microscopy (DFXM): deformation-gradient field imaging through a magnifying objective, and per-dislocation defect-type discrimination, on top of midas-stress / midas-hkls / midas-defect.
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 1 - Planning
+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.20
+Requires-Dist: torch>=2.0
+Requires-Dist: midas-stress
+Requires-Dist: midas-hkls>=0.5
+Requires-Dist: midas-2d>=0.1
+Requires-Dist: midas-defect
+Requires-Dist: midas-invert>=0.1
+Requires-Dist: midas-distortion
+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"
+Dynamic: license-file
+
+# midas-dfxm
+
+Differentiable **forward + inverse** for **Dark-Field X-ray Microscopy (DFXM)**.
+
+DFXM images a bulk grain through a magnifying objective (CRL / MLL) placed on one
+diffracted beam. The objective is a **reciprocal-space bandpass**: a sample voxel
+contributes intensity to its magnified detector pixel only if its *local*
+scattering vector falls inside the instrument's resolution function for the
+current goniometer setting. Rocking the sample (a *mosaicity scan*) maps local
+**orientation**; scanning 2θ / energy (a *strain scan*) maps local **d-spacing**;
+weak-beam settings image **individual dislocations**.
+
+This package models that signal from a voxelised **deformation-gradient field**
+`F(r)`, and (later phases) inverts a DFXM image stack back to `F(r)` and to
+**per-dislocation defect types** (edge/screw, Burgers vector, slip system).
+
+**Reuse-first, no re-porting.** Built on the MIDAS differentiable stack:
+`midas-stress` (orientation/strain), `midas-hkls` (structure factors, form
+factors, DWF), `midas-2d` (continuous-q structure factor, resolution
+convolution), `midas-defect` (Stroh anisotropic-elasticity contrast solver, slip
+systems, GND, planar-defect rods), `midas-invert` (fit / UQ / experiment design),
+`midas-distortion` (detector model). Everything is torch-differentiable and
+device-portable (CPU / CUDA / MPS).
+
+See [`implementation_plan.md`](implementation_plan.md) for the full roadmap,
+physics reuse map, phase gates, and honest scope/novelty gates.
+
+## Status
+
+**Pre-alpha (v0.0.1a0).** Phases 0,1,3,4,5 + a simulation-anchored roadmap
+implemented and tested — **64 tests pass (CPU + MPS; 3 CUDA-skipped), ~2400 LOC.**
+
+Highlights:
+- **Phase 4 (defect typing):** anisotropic-elasticity (Stroh) per-dislocation forward;
+  `g·b` invisibility; edge/screw character; **Burgers-vector recovery**.
+- **Phase 5 (inverse typing):** `identify_dislocation` recovers slip system, character,
+  core position, and the **Burgers-vector sign** (the gap Borgi 2025 leaves open) from
+  multi-reflection weak-beam images.
+- **Phase 3 (field inverse):** full strain-tensor recovery + identifiability + UQ;
+  honest finding — regularisation helps at low SNR, ~neutral at high SNR.
+- **#1 physics coupling:** recover a **GND density** end-to-end through the forward
+  (Nye `κ = ρb`) — the DFXM↔DDD/CP interface, differentiably.
+- **#2 credibility anchor:** independent numpy oracle agrees **bit-for-bit** (~1e-16).
+- **Borbély-ready:** `field_from_deformation_gradient` consumes an external `F(r)` with
+  zero rework.
+
+See [`SIMULATION_CATALOG.md`](SIMULATION_CATALOG.md) and `examples/` (figures land in
+`dev/paper/figures/`).
+
+<details><summary>Earlier milestone note</summary>
+
+Phases 0–1 implemented and tested (30 passing, CPU + MPS):
+
+- **Phase 0 — conventions + field.** `conventions.py` (lab/sample/imaging frames,
+  goniometer), `field.py` (`DeformationField`, the kinematic deform operator
+  `Q = F⁻ᵀ G0`, polar decomposition `F = R·U`), `io.py` (synthetic-field
+  generators: perfect crystal, orientation gradient, uniform strain, isotropic
+  screw dislocation; plus a stub loader for Borbély's field).
+- **Phase 1 — geometrical-optics forward.** `resolution.py` (anisotropic-Gaussian
+  reciprocal-space acceptance), `optics.py` (magnifying inclined projection +
+  bilinear detector splat), `scan.py` (mosaicity / rocking / strain scan builders,
+  Bragg-angle helpers), `forward.py` (`dfxm_image`, `dfxm_stack`, `mosaicity_curve`).
+
+Validated analytic limits: rocking-curve FWHM = `2√(2ln2)·σ⊥ / |axis×q|`, FCC
+forbidden reflection is dark, uniaxial strain shifts `|Q|` correctly; plus
+gradcheck on the deform operator and end-to-end autograd to `F` and the instrument
+widths.
+
+**Next:** Phase 2 (field forward on Borbély's realistic `F(r)` when it lands),
+Phase 3 (field inverse + identifiability study), **Phase 4 (per-dislocation
+forward via the Stroh solver + `g·b` defect typing)**, Phase 5 (inverse defect
+discovery).
+
+</details>
+
+## Quickstart
+
+```python
+import torch
+from midas_dfxm import (
+    make_uniform_field, with_orientation_gradient,
+    GoniometerSetting, reference_q_nom, aligned_resolution,
+    ObjectiveOptics, bragg_two_theta_deg, dfxm_image,
+)
+
+# A curved crystal grain (smooth lattice rotation across x).
+field = make_uniform_field(shape=(64, 64, 1), spacing_um=0.5)
+field = with_orientation_gradient(field, axis=(0, 0, 1), deg_per_um=0.01, along=0)
+
+hkl, center = (1, 1, 1), GoniometerSetting()
+q_nom = reference_q_nom(field, hkl, center)
+res = aligned_resolution(q_nom, sigma_par=5e-3, sigma_perp=5e-3)
+tt = bragg_two_theta_deg(float(torch.linalg.vector_norm(q_nom)), wavelength_A=0.172979)
+optics = ObjectiveOptics(two_theta_deg=tt, magnification=10.0, detector_shape=(256, 256))
+
+image = dfxm_image(field, hkl, center, res, optics)   # (256, 256), differentiable
+```
+
+## Tests
+
+```bash
+# macOS: work around the duplicate-OpenMP-runtime abort (torch + MIDAS siblings).
+export KMP_DUPLICATE_LIB_OK=TRUE
+python -m pytest tests/ -q
+```
+
+Markers: `unit` (analytic correctness), `autograd` (gradcheck / autograd),
+`device` (CPU/CUDA/MPS parity), `slow` (heavy integration).

midas_dfxm-0.1.0/README.md

@@ -0,0 +1,108 @@
+# midas-dfxm
+
+Differentiable **forward + inverse** for **Dark-Field X-ray Microscopy (DFXM)**.
+
+DFXM images a bulk grain through a magnifying objective (CRL / MLL) placed on one
+diffracted beam. The objective is a **reciprocal-space bandpass**: a sample voxel
+contributes intensity to its magnified detector pixel only if its *local*
+scattering vector falls inside the instrument's resolution function for the
+current goniometer setting. Rocking the sample (a *mosaicity scan*) maps local
+**orientation**; scanning 2θ / energy (a *strain scan*) maps local **d-spacing**;
+weak-beam settings image **individual dislocations**.
+
+This package models that signal from a voxelised **deformation-gradient field**
+`F(r)`, and (later phases) inverts a DFXM image stack back to `F(r)` and to
+**per-dislocation defect types** (edge/screw, Burgers vector, slip system).
+
+**Reuse-first, no re-porting.** Built on the MIDAS differentiable stack:
+`midas-stress` (orientation/strain), `midas-hkls` (structure factors, form
+factors, DWF), `midas-2d` (continuous-q structure factor, resolution
+convolution), `midas-defect` (Stroh anisotropic-elasticity contrast solver, slip
+systems, GND, planar-defect rods), `midas-invert` (fit / UQ / experiment design),
+`midas-distortion` (detector model). Everything is torch-differentiable and
+device-portable (CPU / CUDA / MPS).
+
+See [`implementation_plan.md`](implementation_plan.md) for the full roadmap,
+physics reuse map, phase gates, and honest scope/novelty gates.
+
+## Status
+
+**Pre-alpha (v0.0.1a0).** Phases 0,1,3,4,5 + a simulation-anchored roadmap
+implemented and tested — **64 tests pass (CPU + MPS; 3 CUDA-skipped), ~2400 LOC.**
+
+Highlights:
+- **Phase 4 (defect typing):** anisotropic-elasticity (Stroh) per-dislocation forward;
+  `g·b` invisibility; edge/screw character; **Burgers-vector recovery**.
+- **Phase 5 (inverse typing):** `identify_dislocation` recovers slip system, character,
+  core position, and the **Burgers-vector sign** (the gap Borgi 2025 leaves open) from
+  multi-reflection weak-beam images.
+- **Phase 3 (field inverse):** full strain-tensor recovery + identifiability + UQ;
+  honest finding — regularisation helps at low SNR, ~neutral at high SNR.
+- **#1 physics coupling:** recover a **GND density** end-to-end through the forward
+  (Nye `κ = ρb`) — the DFXM↔DDD/CP interface, differentiably.
+- **#2 credibility anchor:** independent numpy oracle agrees **bit-for-bit** (~1e-16).
+- **Borbély-ready:** `field_from_deformation_gradient` consumes an external `F(r)` with
+  zero rework.
+
+See [`SIMULATION_CATALOG.md`](SIMULATION_CATALOG.md) and `examples/` (figures land in
+`dev/paper/figures/`).
+
+<details><summary>Earlier milestone note</summary>
+
+Phases 0–1 implemented and tested (30 passing, CPU + MPS):
+
+- **Phase 0 — conventions + field.** `conventions.py` (lab/sample/imaging frames,
+  goniometer), `field.py` (`DeformationField`, the kinematic deform operator
+  `Q = F⁻ᵀ G0`, polar decomposition `F = R·U`), `io.py` (synthetic-field
+  generators: perfect crystal, orientation gradient, uniform strain, isotropic
+  screw dislocation; plus a stub loader for Borbély's field).
+- **Phase 1 — geometrical-optics forward.** `resolution.py` (anisotropic-Gaussian
+  reciprocal-space acceptance), `optics.py` (magnifying inclined projection +
+  bilinear detector splat), `scan.py` (mosaicity / rocking / strain scan builders,
+  Bragg-angle helpers), `forward.py` (`dfxm_image`, `dfxm_stack`, `mosaicity_curve`).
+
+Validated analytic limits: rocking-curve FWHM = `2√(2ln2)·σ⊥ / |axis×q|`, FCC
+forbidden reflection is dark, uniaxial strain shifts `|Q|` correctly; plus
+gradcheck on the deform operator and end-to-end autograd to `F` and the instrument
+widths.
+
+**Next:** Phase 2 (field forward on Borbély's realistic `F(r)` when it lands),
+Phase 3 (field inverse + identifiability study), **Phase 4 (per-dislocation
+forward via the Stroh solver + `g·b` defect typing)**, Phase 5 (inverse defect
+discovery).
+
+</details>
+
+## Quickstart
+
+```python
+import torch
+from midas_dfxm import (
+    make_uniform_field, with_orientation_gradient,
+    GoniometerSetting, reference_q_nom, aligned_resolution,
+    ObjectiveOptics, bragg_two_theta_deg, dfxm_image,
+)
+
+# A curved crystal grain (smooth lattice rotation across x).
+field = make_uniform_field(shape=(64, 64, 1), spacing_um=0.5)
+field = with_orientation_gradient(field, axis=(0, 0, 1), deg_per_um=0.01, along=0)
+
+hkl, center = (1, 1, 1), GoniometerSetting()
+q_nom = reference_q_nom(field, hkl, center)
+res = aligned_resolution(q_nom, sigma_par=5e-3, sigma_perp=5e-3)
+tt = bragg_two_theta_deg(float(torch.linalg.vector_norm(q_nom)), wavelength_A=0.172979)
+optics = ObjectiveOptics(two_theta_deg=tt, magnification=10.0, detector_shape=(256, 256))
+
+image = dfxm_image(field, hkl, center, res, optics)   # (256, 256), differentiable
+```
+
+## Tests
+
+```bash
+# macOS: work around the duplicate-OpenMP-runtime abort (torch + MIDAS siblings).
+export KMP_DUPLICATE_LIB_OK=TRUE
+python -m pytest tests/ -q
+```
+
+Markers: `unit` (analytic correctness), `autograd` (gradcheck / autograd),
+`device` (CPU/CUDA/MPS parity), `slow` (heavy integration).

midas_dfxm-0.1.0/midas_dfxm/__init__.py

@@ -0,0 +1,281 @@
+"""midas-dfxm -- differentiable forward + inverse for Dark-Field X-ray Microscopy.
+
+Phase 0 (conventions + deformation field):
+    from midas_dfxm import (
+        GoniometerSetting, rotation_matrix, rot_x, rot_y, rot_z,
+        DeformationField, deform_reflection, polar_decomposition,
+        make_uniform_field, with_orientation_gradient, with_screw_dislocation,
+    )
+
+Builds on midas-stress (orientation/strain), midas-hkls (structure factors),
+midas-2d (continuous-q F, resolution), midas-defect (Stroh contrast solver, GND),
+midas-invert (fit/UQ). See implementation_plan.md.
+"""
+from .conventions import (
+    GoniometerSetting,
+    rot_x,
+    rot_y,
+    rot_z,
+    rotation_matrix,
+)
+from .field import (
+    DeformationField,
+    deform_reflection,
+    polar_decomposition,
+    reciprocal_basis,
+    small_strain_from_F,
+)
+from .io import (
+    fcc_reference_crystal,
+    load_borbely_field,
+    make_uniform_field,
+    with_orientation_gradient,
+    with_screw_dislocation,
+    with_uniform_strain,
+)
+from .resolution import ResolutionFunction, aligned_resolution, poulsen_resolution_widths
+from .detector import apply_psf, detector_model, quantize_16bit
+from .optics import ObjectiveOptics, diffracted_beam_direction
+from .scan import (
+    bragg_two_theta_deg,
+    mosaicity_scan,
+    reference_q_nom,
+    rocking_scan,
+    scan_angles,
+)
+from .forward import (
+    dfxm_image,
+    dfxm_stack,
+    mosaicity_curve,
+    structure_factor_intensity,
+    voxel_intensity,
+)
+from .dislocation import (
+    StrohDislocation,
+    cubic_stiffness,
+    dislocation_deformation_field,
+    dislocation_dipole,
+    edge_dislocation_wall,
+    stroh_dislocation,
+)
+from .typing import (
+    classify_character,
+    dfxm_contrast,
+    dilatation_ratio,
+    g_dot_b,
+    recover_burgers,
+    reflection_signal,
+    visibility_series,
+)
+from .inverse import (
+    normal_strain,
+    recover_strain_direct,
+    recover_strain_regularised,
+    strain_covariance,
+    strain_design_matrix,
+    strain_identifiability,
+)
+from .detect import (
+    DislocationLabel,
+    identify_dislocation,
+    match_residual,
+    weak_beam_stack,
+)
+from .validate import cross_check_voxel_intensity, voxel_intensity_numpy
+from .physics import fit_gnd_density, fit_wall_spacing, gnd_curvature_field
+from .generators import (
+    dislocation_pileup,
+    ensemble_density_per_um2,
+    field_from_deformation_gradient,
+    field_from_strain,
+    random_dislocation_ensemble,
+)
+from .plasticity import (
+    gnd_identifiability,
+    multislip_gnd_field,
+    nye_from_densities,
+    recover_gnd_densities,
+    slip_dislocation_types,
+)
+from .mosaicity_fit import fit_orientation_mosaicity, moment_orientation
+from .joint_inverse import fit_dislocation_field, fit_dislocation_ensemble, signal_peaks
+from .finite_beam import beam_integrated_observable
+from .beamline import (Illumination, beamline_resolution, crl_abcd, crl_focal_length, crl_image, crl_na, delta_beryllium)
+from .coherence import (
+    coherent_image,
+    dislocation_exit_wave,
+    coherent_psf,
+    dislocation_phase,
+    exit_amplitude,
+    incoherent_image,
+    partially_coherent_image,
+)
+from .aberration import (
+    ABERRATIONS,
+    aberrated_psf,
+    coeffs_to_tensor,
+    convolve_psf,
+    fit_aberration,
+    wiener_deconvolve,
+    zernike_terms,
+)
+from .field_inverse import (
+    angular_condition_number,
+    angular_sensitivity_matrix,
+    decompose_deformation,
+    deformation_covariance,
+    deformation_design_matrix,
+    deformation_identifiability,
+    deformation_observable,
+    fisher_information,
+    crlb_trace,
+    select_reflections_greedy,
+    recover_deformation_direct,
+    recover_deformation_regularised,
+    reference_Q,
+)
+from .coded_aperture import (
+    coded_forward,
+    coded_identifiability,
+    coding_matrix,
+    de_bruijn,
+    decode_nnls,
+    decode_regularized,
+    depth_axis,
+)
+from .pink_beam import (
+    EPS_MONO,
+    EPS_PINK,
+    axial_reciprocal_width,
+    intensity_gain,
+    pink_beam_res_cov,
+    pink_beam_resolution,
+    strain_resolution_ratio,
+)
+from .cpfem import (
+    cpfem_true_strain,
+    load_cpfem_field,
+    save_cpfem_field,
+    validate_dfxm_on_cpfem,
+)
+
+__all__ = [
+    "GoniometerSetting",
+    "rotation_matrix",
+    "rot_x",
+    "rot_y",
+    "rot_z",
+    "DeformationField",
+    "deform_reflection",
+    "polar_decomposition",
+    "reciprocal_basis",
+    "small_strain_from_F",
+    "fcc_reference_crystal",
+    "make_uniform_field",
+    "with_orientation_gradient",
+    "with_uniform_strain",
+    "with_screw_dislocation",
+    "load_borbely_field",
+    "ResolutionFunction",
+    "aligned_resolution",
+    "poulsen_resolution_widths",
+    "detector_model",
+    "apply_psf",
+    "quantize_16bit",
+    "ObjectiveOptics",
+    "diffracted_beam_direction",
+    "bragg_two_theta_deg",
+    "reference_q_nom",
+    "mosaicity_scan",
+    "rocking_scan",
+    "scan_angles",
+    "dfxm_image",
+    "dfxm_stack",
+    "mosaicity_curve",
+    "voxel_intensity",
+    "structure_factor_intensity",
+    "StrohDislocation",
+    "stroh_dislocation",
+    "cubic_stiffness",
+    "dislocation_deformation_field",
+    "edge_dislocation_wall",
+    "dislocation_dipole",
+    "g_dot_b",
+    "reflection_signal",
+    "dfxm_contrast",
+    "dilatation_ratio",
+    "classify_character",
+    "visibility_series",
+    "recover_burgers",
+    "normal_strain",
+    "strain_design_matrix",
+    "strain_identifiability",
+    "recover_strain_direct",
+    "recover_strain_regularised",
+    "strain_covariance",
+    "identify_dislocation",
+    "DislocationLabel",
+    "weak_beam_stack",
+    "match_residual",
+    "cross_check_voxel_intensity",
+    "voxel_intensity_numpy",
+    "gnd_curvature_field",
+    "fit_gnd_density",
+    "fit_wall_spacing",
+    "field_from_deformation_gradient",
+    "field_from_strain",
+    "dislocation_pileup",
+    "random_dislocation_ensemble",
+    "ensemble_density_per_um2",
+    "slip_dislocation_types",
+    "nye_from_densities",
+    "gnd_identifiability",
+    "recover_gnd_densities",
+    "multislip_gnd_field",
+    "load_cpfem_field",
+    "save_cpfem_field",
+    "cpfem_true_strain",
+    "validate_dfxm_on_cpfem",
+    "fit_orientation_mosaicity",
+    "moment_orientation",
+    "reference_Q",
+    "deformation_design_matrix",
+    "deformation_identifiability",
+    "deformation_observable",
+    "recover_deformation_direct",
+    "recover_deformation_regularised",
+    "deformation_covariance",
+    "fisher_information",
+    "crlb_trace",
+    "select_reflections_greedy",
+    "angular_sensitivity_matrix",
+    "angular_condition_number",
+    "decompose_deformation",
+    "fit_dislocation_field",
+    "fit_dislocation_ensemble",
+    "signal_peaks",
+    "beam_integrated_observable",
+    "Illumination",
+    "beamline_resolution",
+    "crl_abcd",
+    "crl_focal_length",
+    "crl_image",
+    "crl_na",
+    "delta_beryllium",
+    "de_bruijn",
+    "coding_matrix",
+    "coded_forward",
+    "coded_identifiability",
+    "decode_nnls",
+    "decode_regularized",
+    "depth_axis",
+    "EPS_MONO",
+    "EPS_PINK",
+    "axial_reciprocal_width",
+    "intensity_gain",
+    "pink_beam_resolution",
+    "pink_beam_res_cov",
+    "strain_resolution_ratio",
+]
+
+__version__ = "0.1.0"