Metadata-Version: 2.4
Name: dfxm-geo
Version: 2.1.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 and renders the expected detector image at each angle. Below, a single edge dislocation is imaged as the goniometer tilt ϕ sweeps from −150 to +150 µrad (χ = 0): the matrix brightens through ϕ = 0 (strong beam), while the dislocation's strain field casts a characteristic weak-beam contrast whose lobes invert across the rocking curve.

<p align="center">
  <img src="docs/img/rocking_single_dislocation.gif" alt="Animated DFXM forward model of a single edge dislocation as the sample rocks in phi from -150 to +150 microradians; the matrix brightens through phi=0 and the weak-beam dislocation contrast inverts across the rocking curve" width="650" />
</p>

Single centered dislocation (canonical FCC primary), Al 111 @ 17 keV, Npixels = 360. Each frame is one forward-model evaluation at the labelled ϕ, sharing a fixed (γ-corrected) color scale so the rocking-curve brightness change is faithful.

## 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.

```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).
