# silx-kit/pyfai architecture

> Architecture diagram of the GitHub repository silx-kit/pyfai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/silx-kit/pyfai
- Repository: https://github.com/silx-kit/pyfai

## Overview

pyFAI is a Python library and toolset for azimuthal integration of diffraction images, detector/geometry calibration, and related image processing. The main workflow is to provide an image and experimental geometry, preprocess pixel data, integrate it with a selected numerical method, and obtain radial or 2D results; calibration tools establish the geometry from diffraction rings. The README documents histogram and sparse-matrix methods, pixel splitting, and optional OpenCL acceleration. The graph uses the README and SOURCE INDEX references; many application and GUI internals were not sampled, so uncertain links are omitted.

Main entry points: [`src/pyFAI/worker.py`](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/worker.py) (Processing worker), [`src/pyFAI/integrator/load_engines.py`](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/integrator/load_engines.py) (Engine selection), [`src/pyFAI/geometry/core.py`](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/geometry/core.py) (Geometry model), [`src/pyFAI/io/integration_config.py`](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/integration_config.py) (Integration config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["User workflows"]
  node_cli["Integration tools<br/>[integrate.py]"]
  node_calibration["Calibration tools<br/>[calib.py]"]
  node_gui["Calibration GUI"]
  node_worker["Processing worker<br/>[worker.py]"]
end

subgraph group_geometry["Geometry and detectors"]
  node_geometrycore["Geometry model<br/>[core.py]"]
  node_detector["Detector models<br/>[_common.py]"]
  node_sensor["Detector sensors<br/>[sensors.py]"]
  node_poni["Geometry files<br/>[ponifile.py]"]
end

subgraph group_integration["Integration runtime"]
  node_azimuthal["Azimuthal integrator<br/>[azimuthal.py]"]
  node_engine_loader["Engine selection<br/>[load_engines.py]"]
  node_registry["Method registry<br/>[method_registry.py]"]
  node_preproc["Pixel preprocessing<br/>[preproc.py]"]
  node_sparse["Sparse engines<br/>[CSR_engine.py]"]
  node_histogram["Histogram engine"]
  node_opencl["OpenCL engines<br/>[azim_csr.py]"]
end

subgraph group_support["Data and utilities"]
  node_results["Integration results<br/>[containers.py]"]
  node_config["Integration config"]
  node_json["JSON support<br/>[_json.py]"]
  node_average["Image averaging<br/>[average.py]"]
  node_units["Coordinate units<br/>[units.py]"]
  node_math["Numerical utilities<br/>[mathutil.py]"]
  node_strings["String utilities<br/>[stringutil.py]"]
  node_decorators["Shared decorators<br/>[decorators.py]"]
end

node_user(("Diffraction user"))

node_user -->|"provides images"| node_cli
node_user -->|"starts calibration"| node_calibration
node_user -.->|"uses calibration"| node_gui
node_cli -.->|"processes data"| node_worker
node_calibration -.->|"fits geometry"| node_geometrycore
node_worker -->|"invokes integration"| node_azimuthal
node_worker -->|"loads geometry"| node_poni
node_worker -->|"loads settings"| node_config
node_worker -->|"uses preprocessing"| node_preproc
node_azimuthal -.->|"loads engines"| node_engine_loader
node_engine_loader -->|"registers methods"| node_registry
node_engine_loader -->|"selects sparse"| node_sparse
node_engine_loader -.->|"selects histogram"| node_histogram
node_engine_loader -->|"selects OpenCL"| node_opencl
node_worker -->|"returns results"| node_results
node_poni -->|"resolves detectors"| node_detector
node_geometrycore -->|"uses detector models"| node_detector
node_geometrycore -->|"uses units"| node_units
node_geometrycore -->|"uses sensor models"| node_sensor
node_config -->|"parses geometry"| node_poni
node_config -->|"uses method registry"| node_registry
node_config -->|"uses JSON support"| node_json
node_sparse -->|"uses preprocessing"| node_preproc
node_sparse -.->|"builds results"| node_results
node_worker -->|"uses averaging"| node_average
node_worker -->|"uses units"| node_units
node_worker -->|"uses math utilities"| node_math
node_worker -->|"uses decorators"| node_decorators
node_detector -->|"uses string utilities"| node_strings

click node_cli "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/app/integrate.py"
click node_calibration "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/app/calib.py"
click node_gui "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/gui/CalibrationWindow.py"
click node_worker "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/worker.py"
click node_geometrycore "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/geometry/core.py"
click node_detector "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/detectors/_common.py"
click node_sensor "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/detectors/sensors.py"
click node_poni "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/ponifile.py"
click node_azimuthal "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/integrator/azimuthal.py"
click node_engine_loader "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/integrator/load_engines.py"
click node_registry "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/method_registry.py"
click node_preproc "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/engines/preproc.py"
click node_sparse "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/engines/CSR_engine.py"
click node_histogram "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/engines/histogram_engine.py"
click node_opencl "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/opencl/azim_csr.py"
click node_results "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/containers.py"
click node_config "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/integration_config.py"
click node_json "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/_json.py"
click node_average "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/average.py"
click node_units "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/units.py"
click node_math "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/utils/mathutil.py"
click node_strings "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/utils/stringutil.py"
click node_decorators "https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/utils/decorators.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_calibration,node_gui,node_worker,node_user toneBlue
class node_geometrycore,node_detector,node_sensor,node_poni toneAmber
class node_azimuthal,node_engine_loader,node_registry,node_preproc,node_sparse,node_histogram,node_opencl toneMint
class node_results,node_config,node_json,node_average,node_units,node_math,node_strings,node_decorators toneRose
```

## Components

### User workflows

- [Integration tools](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/app/integrate.py): `src/pyFAI/app/integrate.py`
- [Calibration tools](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/app/calib.py): `src/pyFAI/app/calib.py`
- [Calibration GUI](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/gui/CalibrationWindow.py): `src/pyFAI/gui/CalibrationWindow.py`
- [Processing worker](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/worker.py): `src/pyFAI/worker.py`

### Geometry and detectors

- [Geometry model](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/geometry/core.py): `src/pyFAI/geometry/core.py`
- [Detector models](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/detectors/_common.py): `src/pyFAI/detectors/_common.py`
- [Detector sensors](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/detectors/sensors.py): `src/pyFAI/detectors/sensors.py`
- [Geometry files](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/ponifile.py): `src/pyFAI/io/ponifile.py`

### Integration runtime

- [Azimuthal integrator](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/integrator/azimuthal.py): `src/pyFAI/integrator/azimuthal.py`
- [Engine selection](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/integrator/load_engines.py): `src/pyFAI/integrator/load_engines.py`
- [Method registry](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/method_registry.py): `src/pyFAI/method_registry.py`
- [Pixel preprocessing](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/engines/preproc.py): `src/pyFAI/engines/preproc.py`
- [Sparse engines](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/engines/CSR_engine.py): `src/pyFAI/engines/CSR_engine.py`
- [Histogram engine](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/engines/histogram_engine.py): `src/pyFAI/engines/histogram_engine.py`
- [OpenCL engines](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/opencl/azim_csr.py): `src/pyFAI/opencl/azim_csr.py`

### Data and utilities

- [Integration results](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/containers.py): `src/pyFAI/containers.py`
- [Integration config](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/integration_config.py): `src/pyFAI/io/integration_config.py`
- [JSON support](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/io/_json.py): `src/pyFAI/io/_json.py`
- [Image averaging](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/average.py): `src/pyFAI/average.py`
- [Coordinate units](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/units.py): `src/pyFAI/units.py`
- [Numerical utilities](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/utils/mathutil.py): `src/pyFAI/utils/mathutil.py`
- [String utilities](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/utils/stringutil.py): `src/pyFAI/utils/stringutil.py`
- [Shared decorators](https://github.com/silx-kit/pyfai/blob/main/src/pyFAI/utils/decorators.py): `src/pyFAI/utils/decorators.py`

### Other components

- **Diffraction user**

## Connections

- Diffraction user → Integration tools: provides images (evidence: `README.md`)
- Diffraction user → Calibration tools: starts calibration (evidence: `README.md`)
- Diffraction user → Calibration GUI: uses calibration
- Integration tools → Processing worker: processes data
- Calibration tools → Geometry model: fits geometry
- Processing worker → Azimuthal integrator: invokes integration (evidence: `src/pyFAI/worker.py`)
- Processing worker → Geometry files: loads geometry (evidence: `src/pyFAI/worker.py`)
- Processing worker → Integration config: loads settings (evidence: `src/pyFAI/worker.py`)
- Processing worker → Pixel preprocessing: uses preprocessing (evidence: `src/pyFAI/worker.py`)
- Azimuthal integrator → Engine selection: loads engines
- Engine selection → Method registry: registers methods (evidence: `src/pyFAI/integrator/load_engines.py`)
- Engine selection → Sparse engines: selects sparse (evidence: `src/pyFAI/integrator/load_engines.py`)
- Engine selection → Histogram engine: selects histogram (evidence: `src/pyFAI/integrator/load_engines.py`)
- Engine selection → OpenCL engines: selects OpenCL (evidence: `src/pyFAI/integrator/load_engines.py`)
- Processing worker → Integration results: returns results (evidence: `src/pyFAI/worker.py`)
- Geometry files → Detector models: resolves detectors (evidence: `src/pyFAI/io/ponifile.py`)
- Geometry model → Detector models: uses detector models (evidence: `src/pyFAI/geometry/core.py`)
- Geometry model → Coordinate units: uses units (evidence: `src/pyFAI/geometry/core.py`)
- Geometry model → Detector sensors: uses sensor models (evidence: `src/pyFAI/geometry/core.py`)
- Integration config → Geometry files: parses geometry (evidence: `src/pyFAI/io/integration_config.py`)
- Integration config → Method registry: uses method registry (evidence: `src/pyFAI/io/integration_config.py`)
- Integration config → JSON support: uses JSON support (evidence: `src/pyFAI/io/integration_config.py`)
- Sparse engines → Pixel preprocessing: uses preprocessing (evidence: `src/pyFAI/engines/CSR_engine.py`)
- Sparse engines → Integration results: builds results (evidence: `src/pyFAI/engines/CSR_engine.py`)
- Processing worker → Image averaging: uses averaging (evidence: `src/pyFAI/worker.py`)
- Processing worker → Coordinate units: uses units (evidence: `src/pyFAI/worker.py`)
- Processing worker → Numerical utilities: uses math utilities (evidence: `src/pyFAI/worker.py`)
- Processing worker → Shared decorators: uses decorators (evidence: `src/pyFAI/worker.py`)
- Detector models → String utilities: uses string utilities (evidence: `src/pyFAI/detectors/_common.py`)