Metadata-Version: 2.4
Name: xraydc
Version: 0.3.3
Summary: X-Ray Diffraction Cooking -- nx5d data processing recipes
Author-email: Matthias Rössle <matthias.roessle@helmholtz-berlin.de>, Florin Boariu <florin.pt@rootshell.ro>
Project-URL: Source Code, https://gitlab.com/kmc3-xpp/xraydc/
Project-URL: Bug Tracker, https://gitlab.com/kmc3-xpp/xraydc/
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: nx5d
Requires-Dist: xarray
Requires-Dist: scipy
Requires-Dist: dask
Requires-Dist: xrayutilities
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: tqdm; extra == "test"
Provides-Extra: doc
Requires-Dist: mkdocs; extra == "doc"
Requires-Dist: mkdocstrings[python]; extra == "doc"
Requires-Dist: mkdocs-jupyter; extra == "doc"
Provides-Extra: all
Requires-Dist: pytest; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: tqdm; extra == "all"
Requires-Dist: mkdocs; extra == "all"
Requires-Dist: mkdocstrings[python]; extra == "all"
Requires-Dist: mkdocs-jupyter; extra == "all"

# xraydc — X-Ray Diffraction Cooking

`xraydc` provides X-ray diffraction recipes and helper functions for the [nx5d](https://gitlab.com/kmc3-xpp/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:

| Facility | Beamline | Detector(s) |
|---|---|---|
| BESSY II | KMC3-XPP | Dectris Pilatus 100K, Dectris Eiger |
| MAX IV | FemtoMAX | Dectris Pilatus 1M |
| European XFEL | MID | AGIPD |

## Installation

```bash
pip install xraydc
```

Runtime dependencies:

| Package | Role |
|---|---|
| [nx5d](https://gitlab.com/kmc3-xpp/nx5d) | Data management and Spice framework |
| [xrayutilities](https://xrayutilities.sourceforge.io/) | Angle-to-Q conversion backend |
| [xarray](https://docs.xarray.dev/) | Labelled multidimensional arrays |
| [dask](https://www.dask.org/) | Lazy and parallel computation |
| [scipy](https://scipy.org/) | Scientific computing utilities |

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

<p align="center">
  <img src="doc/kmc3-goniometer.png" alt="KMC3-XPP 4-circle goniometer geometry with θ, 2θ, χ, φ axes and area detector" width="500">
  <br><em>Standard KMC3-XPP 4-circle geometry with Pilatus 100K area detector.</em>
</p>

```python
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:

```python
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

```text
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

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

```bash
./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](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)

