midas-defect 0.1.0__tar.gz

midas_defect-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_defect-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: midas-defect
+Version: 0.1.0
+Summary: Differentiable, phase-agnostic diffuse-scattering defect metrology on top of standard FF-HEDM: intensity-budget closure, per-grain dislocation density, fault-rod and selection-rule tests.
+Author-email: Hemant Sharma <hsharma@anl.gov>
+License-Expression: BSD-3-Clause
+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.20
+Requires-Dist: torch>=2.0
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.10
+Requires-Dist: tifffile>=2023.0
+Requires-Dist: zarr>=2.14
+Requires-Dist: midas-transforms>=0.1
+Requires-Dist: midas-hkls>=0.1
+Requires-Dist: midas-stress>=0.1
+Requires-Dist: midas-diffract>=0.1
+Requires-Dist: midas-index>=0.1
+Requires-Dist: midas-peakfit>=0.1
+Requires-Dist: midas-invert>=0.1
+Provides-Extra: viz
+Requires-Dist: plotly>=5.0; extra == "viz"
+Requires-Dist: zarr>=2.14; extra == "viz"
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+Dynamic: license-file
+
+# midas-defect
+
+Differentiable **diffuse-scattering defect metrology** layered on top of standard
+far-field HEDM.
+
+The standard MIDAS chain (`midas_index → midas_fit_grain → midas_process_grains`,
+with `midas_transforms` for the detector model and `midas_stress` for
+orientations) operates on **detected Bragg peaks** and returns **grains**. It
+discards everything between and around the peaks. For a deformed material that
+diffuse field is not noise — it is the defect signal:
+
+- **Asterism** — extended, anisotropic intensity hugging each Bragg core,
+  encoding the dislocation strain field and orientation gradient. Quantifying it
+  gives a per-grain **dislocation density** (Williamson–Hall on radial breadth).
+- **Rods** in q-space — 1-D streaks threading several Bragg shells along
+  low-index directions, the reciprocal-space signature of planar defects
+  (stacking faults, twin walls). For FCC, faults on {111} ⇒ ⟨111⟩ rods.
+- **The full intensity budget** — classifying *every* above-threshold voxel
+  against the predicted reciprocal lattice of the indexed grains lets the
+  scattered intensity be **decomposed and closed at 100 %** (Bragg / near-Bragg
+  asterism / inter-Bragg diffuse / low-q halo). Closure is what licenses
+  *quantitative* statements ("31 % dislocation asterism, 4 % fault rods")
+  instead of qualitative ones.
+- **Selection-rule / forbidden-reflection tests** and **3D-ΔPDF** — phase and
+  defect-symmetry checks (no second phase, no anti-phase boundaries).
+
+This package is the productized, tested form of that whole-field, post-indexing
+diffuse layer.
+
+**Phase-agnostic by design.** Every analysis module is driven by a
+`midas_hkls.Crystal` + a `Geometry`; nothing is hard-wired to FCC. The demk
+default is `lattice.fcc_cu_crystal()`, but `lattice.cual2_crystal()` (tetragonal
+θ-Al₂Cu) is retained as a first-class phase — a future CuAl₂ sample that genuinely
+shows superstructure rods is precisely the case the rod / forward-sim / ΔPDF
+machinery was built for, and re-points by swapping the crystal cell.
+
+**Shippable notebooks.** [`midas_defect/examples/`](midas_defect/examples/) holds
+end-to-end notebooks parameterized by `(Crystal, Geometry, data)`. The flagship
+reproduces the demk FCC defect inventory (index → budget → ρ → rods → forbidden)
+and is runnable by external collaborators; the same notebook re-points to a
+CuAl₂ dataset by editing one cell.
+
+See [`implementation_plan.md`](implementation_plan.md) for the analysis pipelines,
+the MIDAS reuse map, and the test/CI architecture.
+
+## Status
+
+Re-scoped 2026-05-21 after the demk FCC re-analysis. The package's original v0.1
+framing — "heavily-deformed *single crystal*, treat the pattern as a continuous
+field because the standard pipeline cannot index it" — is **retired**: on the
+driving dataset the standard pipeline indexes cleanly (~250 grains/layer), the
+material is an ordinary FCC polycrystal/sub-grain mosaic, and the diffuse field
+is dominated by dislocation asterism (~31 %) over rods (~4 %). The corrected
+scope is **diffuse defect metrology on top of, not instead of, standard
+FF-HEDM**.
+
+Pre-alpha. v0.1 target: shared infrastructure (`geometry`, `lattice`,
+`bragg_diffuse`) + the three capabilities that close the budget
+(`intensity_budget`, `williamson_hall`, `defect_tests`), each validated to
+reproduce the published demk numbers. Rod/asterism/sub-grain/ΔPDF/forward-sim
+modules exist and pass synthetic tests; they promote once anchored to real-data
+regressions.
+
+## Module status
+
+The **validated core** (v0.1) is anchored to the published demk full-res numbers;
+the rest is synthetic-tested and promotes once anchored to real data.
+
+| module | status | notes |
+|---|---|---|
+| `geometry` | **core** | MIDAS-canonical detector model (reuses `apply_tilt_distortion`), ω about Z |
+| `lattice` | **core** | FCC + tetragonal CuAl₂, phase-agnostic shells |
+| `bragg_diffuse` | **core** | full-field classifier + geometry QC (96.4 % on-lattice) |
+| `intensity_budget` | **core** | 4-bin partition, closes to 100 % |
+| `williamson_hall` | **core** | per-grain dislocation density (radial-breadth, FCC b) + modified WH (contrast-corrected) |
+| `contrast_factor` | **core** | anisotropic dislocation contrast factors C̄_hkl (Stroh/sextic, ANIZC); cubic; validated to the silver C=0.3843 worked example; symmetry-general single-dislocation core |
+| `contrast_factor_hex` | **core** | hexagonal contrast factors (Dragomir & Ungár 2002): 11 sub-slip-systems, C̄=C̄_{hk.0}(1+q₁x+q₂x²); validated to Table 2 (Ti+Zr, all systems ≤~3%) |
+| `burgers_population` | **core** | ⟨a⟩/⟨c⟩/⟨c+a⟩ Burgers-vector-type fractions from measured (q₁,q₂); reproduces deformed-Ti 75/20/5 % |
+| `defect_tests` | **core** | forbidden-reflection, fault-rod (explicit), fault-α |
+| `examples` | **core** | end-to-end inventory driver + notebook |
+| `rod_detect`, `asterism_fit`, `subgrain`, `delta_pdf`, `forward_sim`, `seed_index` | *experimental* | synthetic-tested; the deformation-physics layer / future genuine-CuAl₂ rod data |
+
+`defect_tests.rod_family_enrichment` is a **screening** metric only — confounded by
+reciprocal-lattice geometry; use `fault_rod_alignment` (explicit per-grain) for the
+authoritative ⟨111⟩ fault-rod test.
+
+## Driving dataset
+
+Sep-2025 1-ID-E beamtime — 10 Y-layers × 1440 ω-frames @ 0.25°/frame on Pilatus3
+CdTe 2M, 71.676 keV (λ = 0.172979 Å). **Phase: FCC Cu(-rich solid solution),
+a = 3.6356 Å** (space group 225). θ-Al₂Cu (CuAl₂, I4/mcm, a ≈ 6.066 Å) was the
+a-priori candidate given the Cu–Al provenance and was **tested and eliminated**
+from the powder line-out (the 1/d² ring sequence is the exact FCC fingerprint;
+CuAl₂'s strongest (110) line at d = 4.29 Å is absent). The validated
+gold-calibrant detector geometry (Lsd 652.7 mm, tilts + distortion, correct ω
+sign) is the default in `geometry.demk_default_geometry()`.
+
+Published analysis (the worked validation case for this package):
+`~/Desktop/analysis/demk/fcc_reanalysis/` (FINDINGS.md + figures + scripts).
+
+## Engineering contract
+
+All modules satisfy ALL four:
+
+1. **Differentiable**. Every physics / scoring / fitting routine is torch;
+   numpy / scipy live only in `_discrete` helpers off the gradient path.
+2. **Device portable**. CPU / CUDA / MPS via `midas_transforms.device.resolve_device`.
+3. **Thoroughly tested**. Per module: synthetic + autograd + device + **real-data
+   regression** (reproduces a published demk number) + benchmark.
+4. **Reuses upstream MIDAS**. No re-ported orientation, lattice, transform, or
+   device-resolution code. See the reuse map in `implementation_plan.md`.

midas_defect-0.1.0/README.md

@@ -0,0 +1,111 @@
+# midas-defect
+
+Differentiable **diffuse-scattering defect metrology** layered on top of standard
+far-field HEDM.
+
+The standard MIDAS chain (`midas_index → midas_fit_grain → midas_process_grains`,
+with `midas_transforms` for the detector model and `midas_stress` for
+orientations) operates on **detected Bragg peaks** and returns **grains**. It
+discards everything between and around the peaks. For a deformed material that
+diffuse field is not noise — it is the defect signal:
+
+- **Asterism** — extended, anisotropic intensity hugging each Bragg core,
+  encoding the dislocation strain field and orientation gradient. Quantifying it
+  gives a per-grain **dislocation density** (Williamson–Hall on radial breadth).
+- **Rods** in q-space — 1-D streaks threading several Bragg shells along
+  low-index directions, the reciprocal-space signature of planar defects
+  (stacking faults, twin walls). For FCC, faults on {111} ⇒ ⟨111⟩ rods.
+- **The full intensity budget** — classifying *every* above-threshold voxel
+  against the predicted reciprocal lattice of the indexed grains lets the
+  scattered intensity be **decomposed and closed at 100 %** (Bragg / near-Bragg
+  asterism / inter-Bragg diffuse / low-q halo). Closure is what licenses
+  *quantitative* statements ("31 % dislocation asterism, 4 % fault rods")
+  instead of qualitative ones.
+- **Selection-rule / forbidden-reflection tests** and **3D-ΔPDF** — phase and
+  defect-symmetry checks (no second phase, no anti-phase boundaries).
+
+This package is the productized, tested form of that whole-field, post-indexing
+diffuse layer.
+
+**Phase-agnostic by design.** Every analysis module is driven by a
+`midas_hkls.Crystal` + a `Geometry`; nothing is hard-wired to FCC. The demk
+default is `lattice.fcc_cu_crystal()`, but `lattice.cual2_crystal()` (tetragonal
+θ-Al₂Cu) is retained as a first-class phase — a future CuAl₂ sample that genuinely
+shows superstructure rods is precisely the case the rod / forward-sim / ΔPDF
+machinery was built for, and re-points by swapping the crystal cell.
+
+**Shippable notebooks.** [`midas_defect/examples/`](midas_defect/examples/) holds
+end-to-end notebooks parameterized by `(Crystal, Geometry, data)`. The flagship
+reproduces the demk FCC defect inventory (index → budget → ρ → rods → forbidden)
+and is runnable by external collaborators; the same notebook re-points to a
+CuAl₂ dataset by editing one cell.
+
+See [`implementation_plan.md`](implementation_plan.md) for the analysis pipelines,
+the MIDAS reuse map, and the test/CI architecture.
+
+## Status
+
+Re-scoped 2026-05-21 after the demk FCC re-analysis. The package's original v0.1
+framing — "heavily-deformed *single crystal*, treat the pattern as a continuous
+field because the standard pipeline cannot index it" — is **retired**: on the
+driving dataset the standard pipeline indexes cleanly (~250 grains/layer), the
+material is an ordinary FCC polycrystal/sub-grain mosaic, and the diffuse field
+is dominated by dislocation asterism (~31 %) over rods (~4 %). The corrected
+scope is **diffuse defect metrology on top of, not instead of, standard
+FF-HEDM**.
+
+Pre-alpha. v0.1 target: shared infrastructure (`geometry`, `lattice`,
+`bragg_diffuse`) + the three capabilities that close the budget
+(`intensity_budget`, `williamson_hall`, `defect_tests`), each validated to
+reproduce the published demk numbers. Rod/asterism/sub-grain/ΔPDF/forward-sim
+modules exist and pass synthetic tests; they promote once anchored to real-data
+regressions.
+
+## Module status
+
+The **validated core** (v0.1) is anchored to the published demk full-res numbers;
+the rest is synthetic-tested and promotes once anchored to real data.
+
+| module | status | notes |
+|---|---|---|
+| `geometry` | **core** | MIDAS-canonical detector model (reuses `apply_tilt_distortion`), ω about Z |
+| `lattice` | **core** | FCC + tetragonal CuAl₂, phase-agnostic shells |
+| `bragg_diffuse` | **core** | full-field classifier + geometry QC (96.4 % on-lattice) |
+| `intensity_budget` | **core** | 4-bin partition, closes to 100 % |
+| `williamson_hall` | **core** | per-grain dislocation density (radial-breadth, FCC b) + modified WH (contrast-corrected) |
+| `contrast_factor` | **core** | anisotropic dislocation contrast factors C̄_hkl (Stroh/sextic, ANIZC); cubic; validated to the silver C=0.3843 worked example; symmetry-general single-dislocation core |
+| `contrast_factor_hex` | **core** | hexagonal contrast factors (Dragomir & Ungár 2002): 11 sub-slip-systems, C̄=C̄_{hk.0}(1+q₁x+q₂x²); validated to Table 2 (Ti+Zr, all systems ≤~3%) |
+| `burgers_population` | **core** | ⟨a⟩/⟨c⟩/⟨c+a⟩ Burgers-vector-type fractions from measured (q₁,q₂); reproduces deformed-Ti 75/20/5 % |
+| `defect_tests` | **core** | forbidden-reflection, fault-rod (explicit), fault-α |
+| `examples` | **core** | end-to-end inventory driver + notebook |
+| `rod_detect`, `asterism_fit`, `subgrain`, `delta_pdf`, `forward_sim`, `seed_index` | *experimental* | synthetic-tested; the deformation-physics layer / future genuine-CuAl₂ rod data |
+
+`defect_tests.rod_family_enrichment` is a **screening** metric only — confounded by
+reciprocal-lattice geometry; use `fault_rod_alignment` (explicit per-grain) for the
+authoritative ⟨111⟩ fault-rod test.
+
+## Driving dataset
+
+Sep-2025 1-ID-E beamtime — 10 Y-layers × 1440 ω-frames @ 0.25°/frame on Pilatus3
+CdTe 2M, 71.676 keV (λ = 0.172979 Å). **Phase: FCC Cu(-rich solid solution),
+a = 3.6356 Å** (space group 225). θ-Al₂Cu (CuAl₂, I4/mcm, a ≈ 6.066 Å) was the
+a-priori candidate given the Cu–Al provenance and was **tested and eliminated**
+from the powder line-out (the 1/d² ring sequence is the exact FCC fingerprint;
+CuAl₂'s strongest (110) line at d = 4.29 Å is absent). The validated
+gold-calibrant detector geometry (Lsd 652.7 mm, tilts + distortion, correct ω
+sign) is the default in `geometry.demk_default_geometry()`.
+
+Published analysis (the worked validation case for this package):
+`~/Desktop/analysis/demk/fcc_reanalysis/` (FINDINGS.md + figures + scripts).
+
+## Engineering contract
+
+All modules satisfy ALL four:
+
+1. **Differentiable**. Every physics / scoring / fitting routine is torch;
+   numpy / scipy live only in `_discrete` helpers off the gradient path.
+2. **Device portable**. CPU / CUDA / MPS via `midas_transforms.device.resolve_device`.
+3. **Thoroughly tested**. Per module: synthetic + autograd + device + **real-data
+   regression** (reproduces a published demk number) + benchmark.
+4. **Reuses upstream MIDAS**. No re-ported orientation, lattice, transform, or
+   device-resolution code. See the reuse map in `implementation_plan.md`.

midas_defect-0.1.0/midas_defect/__init__.py

@@ -0,0 +1,16 @@
+"""midas_defect — phase-agnostic diffuse-scattering defect metrology for FF-HEDM.
+
+Quantifies the diffuse field around and between the Bragg peaks of an indexed
+FF-HEDM dataset (asterism, fault rods, the full intensity budget, defect /
+selection-rule tests) to produce a per-grain defect inventory. Driven by a
+`midas_hkls.Crystal` + a `Geometry`; nothing is hard-wired to a phase.
+"""
+
+import os
+
+# `geometry.pixel_to_qlab` reuses `midas_transforms.apply_tilt_distortion`, which
+# links a second OpenMP runtime alongside torch's. Allow the duplicate at import
+# time (before either runtime initializes) so callers don't hit a hard crash.
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+
+__version__ = "0.1.0"