midas-diffract 0.1.0__tar.gz

midas_diffract-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_diffract-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: midas-diffract
+Version: 0.1.0
+Summary: End-to-end differentiable forward model for High-Energy Diffraction Microscopy (FF, NF, pf-HEDM)
+Author: Simon Zhang, Nina Andrejevic, Mathew Cherukara
+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
+Project-URL: Issues, https://github.com/marinerhemant/MIDAS/issues
+Keywords: HEDM,3DXRD,differentiable physics,PyTorch,forward model,crystallography,polycrystal,grain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: hkls
+Requires-Dist: midas-hkls>=0.1.0; extra == "hkls"
+Dynamic: license-file
+
+# midas-diffract
+
+End-to-end differentiable forward model for High-Energy Diffraction Microscopy (HEDM), covering far-field (FF), near-field (NF), and point-focused (pf-HEDM) geometries. Pixel-exact agreement with the canonical C reference simulators in [MIDAS](https://github.com/marinerhemant/MIDAS).
+
+Companion paper: Sharma, Zhang, Andrejevic & Cherukara, *An End-to-End Differentiable Forward Model for High-Energy Diffraction Microscopy*, IUCrJ (in preparation, 2026).
+
+## Installation
+
+```bash
+pip install midas-diffract           # core forward model + losses + optimizer
+pip install midas-diffract[hkls]     # also installs midas-hkls for the
+                                     # pure-Python reflection-list helper
+```
+
+Optional PyTorch CUDA or MPS back-ends are used automatically if available.
+
+## Quick start
+
+```python
+import torch
+import midas_diffract as md
+from midas_hkls import Lattice, SpaceGroup           # optional, see [hkls]
+
+# Detector + scan geometry
+geom = md.HEDMGeometry(
+    Lsd=1_000_000.0,              # um
+    y_BC=1024.0, z_BC=1024.0,
+    px=200.0,
+    omega_start=0.0, omega_step=0.25, n_frames=1440,
+    n_pixels_y=2048, n_pixels_z=2048,
+    min_eta=6.0,
+    wavelength=0.172979,           # Angstroms
+)
+
+# Reflection list: either compute from a SpaceGroup + Lattice via the
+# midas-hkls helper, or supply (hkls_cart, thetas, hkls_int) yourself
+# (e.g. parsed from MIDAS GetHKLList output).
+sg = SpaceGroup.from_number(225)                        # FCC
+lat = Lattice.for_system("cubic", a=4.08)               # Au
+hkls_cart, thetas, hkls_int = md.hkls_for_forward_model(
+    sg, lat, wavelength_A=geom.wavelength, two_theta_max_deg=15.0,
+)
+
+model = md.HEDMForwardModel(
+    hkls=hkls_cart, thetas=thetas, geometry=geom, hkls_int=hkls_int,
+)
+
+# Forward pass: grain state -> predicted spots. All inputs are leaves
+# of the autograd graph.
+euler = torch.tensor([[45.0, 30.0, 60.0]], requires_grad=True) * (3.14159 / 180)
+pos   = torch.tensor([[0.0, 0.0, 0.0]],  requires_grad=True)
+latc  = torch.tensor([4.08, 4.08, 4.08, 90.0, 90.0, 90.0], requires_grad=True)
+spots = model(euler, pos, lattice_params=latc)
+
+# Scalar loss -> gradients w.r.t. orientation, position, lattice
+loss = ((spots.omega * spots.valid) ** 2).sum()
+loss.backward()
+```
+
+## Output modes
+
+- `md.HEDMForwardModel.predict_spot_coords(spots, space="angular")` — returns
+  `(2θ, η, ω)` in radians for each valid reflection (FF and pf-HEDM).
+- `md.HEDMForwardModel.predict_spot_coords(spots, space="detector")` — returns
+  `(y_pixel, z_pixel, frame_nr)` in fractional units (FF and pf-HEDM).
+- `md.HEDMForwardModel.predict_images(spots, ...)` — renders a differentiable
+  3D detector volume via Gaussian splatting (NF-HEDM output mode).
+
+## Validation
+
+The forward model has been validated to pixel-exact agreement against the
+canonical C simulators `ForwardSimulationCompressed` and `simulateNF` in the
+MIDAS distribution. See the companion paper and the MIDAS repository
+`fwd_sim/paper/` directory for reproducibility scripts.
+
+## Scope
+
+`midas-diffract` v0.1.0 is deliberately focused on the forward model and its
+gradient chain. The following capabilities build on this substrate and are
+released separately as they mature:
+
+- Sub-voxel grain mixtures
+- Physics-informed regularisation
+- Bayesian uncertainty quantification via HMC / variational inference
+- Temporal 4D-HEDM tracking
+- Coupling to differentiable crystal plasticity (JAX-FEM)
+- EM spot ownership for ambiguous FF patterns
+
+## Citation
+
+If you use `midas-diffract` in published work, please cite the companion paper.
+
+## Licence
+
+BSD-3-Clause.

midas_diffract-0.1.0/README.md

@@ -0,0 +1,95 @@
+# midas-diffract
+
+End-to-end differentiable forward model for High-Energy Diffraction Microscopy (HEDM), covering far-field (FF), near-field (NF), and point-focused (pf-HEDM) geometries. Pixel-exact agreement with the canonical C reference simulators in [MIDAS](https://github.com/marinerhemant/MIDAS).
+
+Companion paper: Sharma, Zhang, Andrejevic & Cherukara, *An End-to-End Differentiable Forward Model for High-Energy Diffraction Microscopy*, IUCrJ (in preparation, 2026).
+
+## Installation
+
+```bash
+pip install midas-diffract           # core forward model + losses + optimizer
+pip install midas-diffract[hkls]     # also installs midas-hkls for the
+                                     # pure-Python reflection-list helper
+```
+
+Optional PyTorch CUDA or MPS back-ends are used automatically if available.
+
+## Quick start
+
+```python
+import torch
+import midas_diffract as md
+from midas_hkls import Lattice, SpaceGroup           # optional, see [hkls]
+
+# Detector + scan geometry
+geom = md.HEDMGeometry(
+    Lsd=1_000_000.0,              # um
+    y_BC=1024.0, z_BC=1024.0,
+    px=200.0,
+    omega_start=0.0, omega_step=0.25, n_frames=1440,
+    n_pixels_y=2048, n_pixels_z=2048,
+    min_eta=6.0,
+    wavelength=0.172979,           # Angstroms
+)
+
+# Reflection list: either compute from a SpaceGroup + Lattice via the
+# midas-hkls helper, or supply (hkls_cart, thetas, hkls_int) yourself
+# (e.g. parsed from MIDAS GetHKLList output).
+sg = SpaceGroup.from_number(225)                        # FCC
+lat = Lattice.for_system("cubic", a=4.08)               # Au
+hkls_cart, thetas, hkls_int = md.hkls_for_forward_model(
+    sg, lat, wavelength_A=geom.wavelength, two_theta_max_deg=15.0,
+)
+
+model = md.HEDMForwardModel(
+    hkls=hkls_cart, thetas=thetas, geometry=geom, hkls_int=hkls_int,
+)
+
+# Forward pass: grain state -> predicted spots. All inputs are leaves
+# of the autograd graph.
+euler = torch.tensor([[45.0, 30.0, 60.0]], requires_grad=True) * (3.14159 / 180)
+pos   = torch.tensor([[0.0, 0.0, 0.0]],  requires_grad=True)
+latc  = torch.tensor([4.08, 4.08, 4.08, 90.0, 90.0, 90.0], requires_grad=True)
+spots = model(euler, pos, lattice_params=latc)
+
+# Scalar loss -> gradients w.r.t. orientation, position, lattice
+loss = ((spots.omega * spots.valid) ** 2).sum()
+loss.backward()
+```
+
+## Output modes
+
+- `md.HEDMForwardModel.predict_spot_coords(spots, space="angular")` — returns
+  `(2θ, η, ω)` in radians for each valid reflection (FF and pf-HEDM).
+- `md.HEDMForwardModel.predict_spot_coords(spots, space="detector")` — returns
+  `(y_pixel, z_pixel, frame_nr)` in fractional units (FF and pf-HEDM).
+- `md.HEDMForwardModel.predict_images(spots, ...)` — renders a differentiable
+  3D detector volume via Gaussian splatting (NF-HEDM output mode).
+
+## Validation
+
+The forward model has been validated to pixel-exact agreement against the
+canonical C simulators `ForwardSimulationCompressed` and `simulateNF` in the
+MIDAS distribution. See the companion paper and the MIDAS repository
+`fwd_sim/paper/` directory for reproducibility scripts.
+
+## Scope
+
+`midas-diffract` v0.1.0 is deliberately focused on the forward model and its
+gradient chain. The following capabilities build on this substrate and are
+released separately as they mature:
+
+- Sub-voxel grain mixtures
+- Physics-informed regularisation
+- Bayesian uncertainty quantification via HMC / variational inference
+- Temporal 4D-HEDM tracking
+- Coupling to differentiable crystal plasticity (JAX-FEM)
+- EM spot ownership for ambiguous FF patterns
+
+## Citation
+
+If you use `midas-diffract` in published work, please cite the companion paper.
+
+## Licence
+
+BSD-3-Clause.

midas_diffract-0.1.0/midas_diffract/__init__.py

@@ -0,0 +1,55 @@
+"""midas-diffract: End-to-end differentiable forward model for HEDM.
+
+A PyTorch-based differentiable forward simulator for far-field, near-field,
+and point-focused High-Energy Diffraction Microscopy, with pixel-exact
+agreement against the canonical C reference simulators in MIDAS.
+
+See the companion paper for methodology:
+    Sharma, Zhang, Andrejevic, Cherukara, "An End-to-End Differentiable Forward
+    Model for High-Energy Diffraction Microscopy," IUCrJ (in prep, 2026).
+
+Quick start
+-----------
+    import torch
+    import midas_diffract as md
+
+    # Construct the forward model from geometry + reflection list
+    geom = md.HEDMGeometry(Lsd=..., y_BC=..., z_BC=..., px=..., ...)
+    model = md.HEDMForwardModel(hkls=hkls_cart, thetas=thetas,
+                                geometry=geom, hkls_int=hkls_int)
+
+    # Forward: grain state -> predicted spots
+    euler = torch.tensor([[phi1, Phi, phi2]], requires_grad=True)
+    pos   = torch.tensor([[x, y, z]], requires_grad=True)
+    spots = model(euler, pos, lattice_params=latc)
+
+    # Scalar loss -> gradient to all inputs via autograd
+    loss = (spots.omega * spots.valid).pow(2).sum()
+    loss.backward()
+"""
+
+__version__ = "0.1.0"
+
+from .forward import (
+    HEDMForwardModel,
+    HEDMGeometry,
+    ScanConfig,
+    TriVoxelConfig,
+    SpotDescriptors,
+)
+from .hkls import hkls_for_forward_model
+from .losses import SpotMatchingLoss
+from .optimize import optimize_single_grain, evaluate_recovery
+
+__all__ = [
+    "HEDMForwardModel",
+    "HEDMGeometry",
+    "ScanConfig",
+    "TriVoxelConfig",
+    "SpotDescriptors",
+    "SpotMatchingLoss",
+    "hkls_for_forward_model",
+    "optimize_single_grain",
+    "evaluate_recovery",
+    "__version__",
+]