grax

grax is an independent Python package for diffraction-grating simulations in X-ray optics, inspired by RETICOLO v9 and extended with higher-level workflows for practical studies.

Documentation

Full user and API documentation is published online.

• User guide and tutorials: see the project documentation site
• API reference: see the API section in the documentation site

For local docs builds from this repository, use:

tools/build_docs.sh --html

Installation

graxpy supports Python 3.12 and 3.13 only.

python -m pip install graxpy

graxpy now supports local Henke-table material lookup for elemental string names such as "Si" and "Pt", with optional density overrides through grax.MaterialSpec. Existing DataFrame optical-constants inputs still work, and xrt-compatible material objects remain supported for now but emit a deprecation warning.

PyPI project page: https://pypi.org/project/graxpy/0.1.0/

For local editable installs:

python -m pip install -e .

Local web app

Install the package and web extra, then start the local server.

From PyPI:

python -m pip install "graxpy[web]"
grax-web

From a local repository checkout:

python -m pip install -e ".[web]"
grax-web

The syntax graxpy.[web] is invalid. The extra must be attached directly to the package name: graxpy[web].

Then open http://127.0.0.1:5050. Use the home page to create and save gratings, then open the plot page to combine saved runs and select the diffraction orders to overlay.

grax-web now opens that local URL in your default browser automatically on startup.

Start on a different port when needed:

grax-web --port 8000

You can also override the bind address:

grax-web --host 0.0.0.0 --port 8000

When developing the web app locally, restart grax-web after changing run-state or UI logic so the browser sees the updated server behavior.

Local data is stored in .grax-web/ by default:

• saved gratings: .grax-web/saved_gratings/
• run results: .grax-web/runs/
• combined plots: .grax-web/plots/
• grating previews: .grax-web/previews/

Each saved run lives in .grax-web/runs/<run_id>/ and includes:

• manifest.json
• summary.csv
• all_orders.csv
• selected_efficiency.png

Use Plots to combine saved runs and choose which diffraction orders to overlay for each run. Use Manage runs to rename runs or bulk delete them.

Repository at a glance

• src/grax/: core package source code
• examples/: runnable examples
• docs/: documentation sources

Attribution

grax is inspired by RETICOLO v9. This project is an independent Python implementation and is not an official RETICOLO distribution. RETICOLO is not bundled as part of the public graxpy package distribution.

• RETICOLO DOI: https://doi.org/10.5281/zenodo.14631950
• RETICOLO license (CC BY 4.0): https://creativecommons.org/licenses/by/4.0/

License

Copyright (C) [2026] [Helmholtz-Berlin fur Materialen und Energie GmbH (HZB)]

Licensed under the European Union Public License (EUPL), Version 1.2.

You may not use this work except in compliance with the License.

A copy of the License is available at: https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12