Metadata-Version: 2.4
Name: dfxm-geo
Version: 2.4.0
Summary: Geometrical-optics forward model for dark-field X-ray microscopy
Author-email: Sina Borgi <borgi@dtu.dk>
License: MIT License
        
        Copyright (c) 2024-2026 Sina Borgi and contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/borgi-s/Geometrical_Optics_master
Project-URL: Repository, https://github.com/borgi-s/Geometrical_Optics_master
Project-URL: Issues, https://github.com/borgi-s/Geometrical_Optics_master/issues
Project-URL: Documentation, https://github.com/borgi-s/Geometrical_Optics_master/tree/main/docs
Project-URL: Changelog, https://github.com/borgi-s/Geometrical_Optics_master/releases
Project-URL: Paper, https://journals.iucr.org/j/issues/2024/02/00/nb5370/
Keywords: dfxm,x-ray,synchrotron,dislocations,materials-science
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.23
Requires-Dist: scipy<2,>=1.10
Requires-Dist: numba>=0.56
Requires-Dist: matplotlib>=3.6
Requires-Dist: seaborn>=0.12
Requires-Dist: fabio>=2023.4
Requires-Dist: h5py>=3.0
Requires-Dist: joblib>=1.3
Requires-Dist: tqdm>=4.66.3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: pytest-benchmark>=4; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Provides-Extra: beamstop-wire
Requires-Dist: xraylib>=4.1; extra == "beamstop-wire"
Provides-Extra: memory-aware
Requires-Dist: psutil>=5; extra == "memory-aware"
Provides-Extra: identification
Requires-Dist: plotly>=5; extra == "identification"
Dynamic: license-file

<p align="center">
  <img src="docs/img/fig_3_1_microscope_schematic.png" alt="DFXM optics schematic — monochromator, slits + condenser, sample on goniometer, CRL objective, detector" />
</p>

# DFXM Geometrical-Optics Forward Model

> A physics-based forward model that simulates Dark-Field X-ray Microscopy images of crystals with dislocations — published in the *Journal of Applied Crystallography* (2024).

## What this is

Dark-Field X-ray Microscopy (DFXM) is a synchrotron technique for imaging crystal defects with sub-micron resolution deep inside bulk materials. This package implements the geometrical-optics (GO) forward model described in [Borgi et al., *J. Appl. Cryst.* **57**, 358 (2024)](https://doi.org/10.1107/S1600576724001183). Given a dislocation configuration and a beamline geometry, it computes the expected detector image in two stages:

1. **Reciprocal space** — Monte Carlo ray tracing samples the instrument's angular and energy acceptance through monochromator, slits, condenser, CRL objective, and detector to build a voxelized resolution kernel `Resq_i(q_rock', q_roll, q_2θ)`.
2. **Direct space** — the deformation field around each dislocation (Hirth & Lothe, mixed edge/screw via the slip-system angle α) is rotated into the imaging frame and convolved with the kernel to produce the detector image.

The default configuration targets the **ID06 beamline at ESRF**: Al 111 reflection at 17 keV, 88-lenslet Be CRL, ID06 goniometer geometry.

## What it produces

A typical weak-beam DFXM image with five random edge dislocations in single-crystal aluminium, generated by the pipeline:

<p align="center">
  <img src="docs/img/fig_3_5_single_dislocation_weakbeam.png" alt="Weak-beam DFXM forward model showing 5 random edge dislocations in a single crystal of aluminium" width="650" />
</p>

Each dislocation has its own Burgers vector, line direction, and slip-plane normal; the local contrast reflects how the lattice distortion field around each defect couples into the instrument's acceptance.

## How it works — reciprocal space

The reciprocal-space stage draws Monte-Carlo rays from truncated-Gaussian distributions over the incident divergences `(ζ_v, ζ_h)` and energy bandwidth `ΔE/E`, filters them through the CRL numerical aperture, and bins the accepted q-vectors `(q_rock', q_roll, q_2θ)` into a 3D kernel. The figure below shows the raw point cloud for 50 000 rays at the default Al 111 / 17 keV setting:

<p align="center">
  <img src="docs/img/reciprocal_pointcloud_50k.png" alt="3D scatter plot of the reciprocal-space acceptance kernel with 2D projections onto each back-wall" width="520" />
</p>

The central black cloud is the angular/energy acceptance in the imaging coordinate system; the colored projections show its 2D shadows on each back-wall. Optional `[beamstop]` modes (square aperture in the BFP, knife edge, or absorbing tungsten wire) can be enabled to study weak-beam contrast enhancement.

## How it works — direct space → detector

After the kernel is built, the forward stage rocks the sample through the Bragg condition over a (ϕ, χ) grid and renders the expected detector image at each angle. Taking the per-pixel center of mass of each pixel's rocking curve gives the local lattice tilt — one center-of-mass (COM) map per rocking axis, `COM_ϕ` and `COM_χ` (the two together make up the mosaicity). The geometrical-optics model predicts the same field directly, as the projection `qi` of the deformation onto the imaging axes, so the two should agree. The figure below makes that comparison for a low-angle wall of edge dislocations:

<p align="center">
  <img src="docs/img/com_qi_comparison.png" alt="Four-panel comparison of DFXM center-of-mass maps against the geometric-optics qi field for a wall of five edge dislocations. Top row: the negated phi and chi center-of-mass maps. Bottom row: the qi_1 and qi_2 fields at the z=0 sample plane. Each top panel matches the panel below it." width="620" />
</p>

Top row: the (negated) ϕ and χ center-of-mass (COM) maps extracted from the rocking stack. Bottom row: the geometrical-optics `qi₁` / `qi₂` fields at the z = 0 sample plane. Wall of five edge dislocations, Al 111 @ 17 keV, computed with the v2.1.0 closed-form (analytic) resolution backend; all panels share a fixed ±10⁻⁴ rad color scale. The `−COM ≈ qi` correspondence — each top panel reproducing the one beneath it — recovers the result of [Borgi et al. (2024)](https://doi.org/10.1107/S1600576724001183).

## Stack

- **Language:** Python 3.11+
- **Key libraries:** NumPy, SciPy, h5py, matplotlib
- **HPC:** Batch templates for LSF (DTU Sophia) and SLURM (ESRF clusters); HDF5 / BLISS-schema outputs
- **Testing:** pytest (498 tests) with reference golden datasets
- **License:** MIT

## Install

```bash
pip install dfxm-geo
```

or from source:

```bash
git clone https://github.com/borgi-s/Geometrical_Optics_master.git
cd Geometrical_Optics_master
python -m venv .venv && source .venv/bin/activate     # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest                                                # smoke tests against reference data
```

## Run

A literally empty `.toml` file is a valid input (since v2.0.0): the empty case produces a single detector image of a single canonical FCC dislocation at the origin, Al 111 reflection at 17 keV.

If you installed from PyPI/wheel (no repo clone), first create local copies of
the config templates:

```bash
dfxm-init   # writes ./configs/default.toml and the rest of the template tree
```

```bash
# one-time bootstrap (generates reciprocal-space kernel ~50 s; reusable thereafter):
dfxm-bootstrap --config configs/default.toml

# forward simulation:
dfxm-forward    --config configs/default.toml   --output ./run_output

# dislocation identification (image-to-library matching):
dfxm-identify   --config configs/identification_single.toml --output ./id_output
```

Every block in `configs/default.toml` shows the value the pipeline would use if the block were omitted — edit any block to override, delete to fall back to the default. For larger parameter sweeps, see `lsf/` and `slurm/` for ready-to-submit batch scripts. Output is written to a BLISS-schema HDF5 file (master + per-scan layout) that `silx` and `darfix` can consume directly.

## Cite

If this code or the model is useful in your work, please cite:

> Borgi, S., Ræder, T. M., Carlsen, M. A., Detlefs, C., Winther, G., & Poulsen, H. F. (2024). *Simulations of dislocation contrast in dark-field X-ray microscopy.* Journal of Applied Crystallography **57**, 358–368. [doi:10.1107/S1600576724001183](https://doi.org/10.1107/S1600576724001183)

A second paper applying the model to individual-dislocation identification:

> Borgi, S., Winther, G., & Poulsen, H. F. (2025). *Individual dislocation identification in dark-field X-ray microscopy.* J. Appl. Cryst. **58**, 813–821.

## Background

Developed during PhD research at DTU Physics in collaboration with ESRF (European Synchrotron Radiation Facility). The forward model is a Python port and substantial extension of the MATLAB script first introduced by Poulsen et al., *J. Appl. Cryst.* **54**, 1555 (2021). The microscope schematic and example output above are adapted from S. Borgi, *Dislocation identification using dark-field X-ray microscopy in bulk single-crystalline materials* (PhD thesis, DTU Physics, 2025), Chapter 3.

## Roadmap

Released: v2.0.0 (2026-05-23) — empty-TOML defaults, `WallCrystalConfig` defaults stripped (breaking), BLISS-schema HDF5 output, identification → HDF5. Next: Zenodo deposit of reference datasets; expanded multi-reflection support beyond Al; darling/darfix interop polish (see follow-up issues).
