xraydc — X-Ray Diffraction Cooking

xraydc provides X-ray diffraction recipes and helper functions for the nx5d analysis framework. Within the nx5d Spice Concept, it supplies the domain-specific logic that "cooks" raw detector data into reciprocal-space representations that are ready for physical interpretation.

Overview

• QMapper maps angular detector images into reciprocal-space with coordinates $q_x$, $q_y$, and $q_z$ using well tested algorithms provided by xrayutilities.
• sRSM generates static reciprocal-space maps from a single scan.
• TRSM generates parameter-grouped reciprocal-space maps, for example over delay, temperature, or scan index.
• QMapper.qmap_groupby() provides split-apply-combine Q-mapping over grouped xarray datasets.

The package is designed to work with xarray, supports arbitrary goniometer and detector geometries, and can be used with pixelated area detectors beyond the original beamline setup.

Provenance

xraydc originated at the KMC3-XPP beamline at BESSY II (Helmholtz-Zentrum Berlin). It is also used in the Ultrafast Dynamics group of Prof. Matias Bargheer (University of Potsdam) for laboratory-based plasma X-ray source time-resolved diffraction experiments.

The Q-mapping workflow has been used with the following detector and beamline combinations:

Installation

pip install xraydc

Runtime dependencies:

Quick Start

The example below uses the standard KMC3-XPP geometry with a Pilatus 100K detector and the actual motor names used at the beamline.

Standard KMC3-XPP 4-circle geometry with Pilatus 100K area detector.

from xraydc.signal import QMapper

exp_setup = {
    "goniometerAxes": {
        "Theta_mea": "y-",
        "Chi": "x+",
        "Phi": "z+",
    },
    "detectorAxes": {
        "TwoTheta_mea": "y-",
    },
    "detectorTARAlign": [0.0, 0.0, 0.0],
    "imageAxes": ["y-", "z-"],
    "imageSize": [195, 487],
    "imageCenter": [95, 244],
    "imageDistance": 481.0,
    "imageChannelSize": [0.172, 0.172],
    "sampleFaceUp": "z+",
    "beamDirection": [1, 0, 0],
    "sampleNormal": [0, 0, 1],
    "beamEnergy": 10000.0,
}

mapper = QMapper(**exp_setup)

# raw_data is an xarray.Dataset containing detector images and angle arrays
q_data = mapper.qmap(raw_data)

# Example: 2D reciprocal-space projection
q_data_2d = mapper.qmap(raw_data, dims=("qx", "qz"))

Using nx5d Recipes

Inside an nx5d Spice pipeline, the recipe layer is usually called through nx5d rather than directly:

from xraydc.cooking import TRSM, sRSM

result = sRSM(scan_type, data, exp_info=exp_info, offsets=offsets)

result = TRSM(
    scan_type,
    data,
    exp_info=exp_info,
    qargs={"groupby": "delay", "dims": ("qy", "qz"), "qsize": None, "gridargs": None},
)

Repository Layout

src/xraydc/
├── signal.py     # QMapper and Q-space conversion logic
├── cooking.py    # nx5d-compatible XRD recipes
└── _version.py   # generated by setuptools_scm during packaging

scripts/
└── release.sh    # maintainer release helper

Development

# install package with test and documentation extras
pip install -e ".[all]"

# run the test suite
pytest

Release Workflow

The repository includes a maintainer release helper at scripts/release.sh.

./scripts/release.sh 0.2.3

Before creating and pushing the release tag, the script verifies:

• semantic version format (X.Y.Z)
• current branch is master
• working tree is clean
• local master is in sync with origin/master
• tag vX.Y.Z does not already exist
• setuptools_scm write_to target in pyproject.toml matches src/xraydc/_version.py

Notes:

• Run the script from the repository root in Git Bash, Linux, or WSL.
• The script asks for confirmation before creating and pushing the tag.
• CI release jobs are triggered by the pushed tag.

License

GPLv3+ — see pyproject.toml for package metadata and licensing information.

Authors

• Matthias Rössle (Helmholtz-Zentrum Berlin)
• Alexander von Reppert (University of Potsdam)
• Florin Boariu (Helmholtz-Zentrum Berlin)