# loicpoisson/slac-xrf-project architecture

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

- Interactive diagram: https://gitdiagram.com/loicpoisson/slac-xrf-project
- Repository: https://github.com/loicpoisson/slac-xrf-project

## Overview

This research pipeline turns coarse XRF scans into adaptive fine-scan plans, deciding both where to scan and how long to dwell, with iterative multi-resolution acquisition as its production workflow. Offline scripts validate spatial, temporal, combined, and cascade strategies against fine-scan ground truth; profiling and recommendation provide supporting analysis. The graph preserves the README’s major capabilities. Some script internals were not sampled, so their documented roles are shown without asserting unverified call paths.

Main entry points: [`scripts/10_run_pipeline.py`](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/10_run_pipeline.py) (Iterative scan planner), [`scripts/utils/validation_utils.py`](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/validation_utils.py) (Grid and scan metrics), [`scripts/utils/cascade.py`](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/cascade.py) (Refinement cascade), [`scripts/utils/roi_utils.py`](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/roi_utils.py) (ROI and mask tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Planning Workflow"]
  node_planner["Iterative scan planner<br/>[10_run_pipeline.py]"]
  node_scanplan["Adaptive scan plan"]
end

subgraph group_methods["Adaptive Methods"]
  node_roi["Spatial ROI detection"]
  node_trajectory["ROI trajectory<br/>[02_trajectory.py]"]
  node_morph["Morphological mask"]
  node_temporal["Adaptive dwell"]
  node_combined["Combined strategy"]
  node_recommender["Strategy recommender"]
  node_cascade["Refinement cascade<br/>[cascade.py]"]
end

subgraph group_analysis["Validation and Analysis"]
  node_roi_validation["ROI validation<br/>[03_validate_roi.py]"]
  node_hierarchical["Cascade validation"]
  node_pareto["Pareto strategy sweep<br/>[06_pareto_sweep.py]"]
  node_combined_validation["Combined validation"]
  node_profiler["Sample profiler"]
  node_report_figures["Report figures"]
end

subgraph group_core["Shared Runtime"]
  node_roiutils["ROI and mask tools<br/>[roi_utils.py]"]
  node_reader["SSRL HDF5 reader<br/>[hdf5_reader.py]"]
  node_dwell["Dwell allocator<br/>[dwell.py]"]
  node_quality["Poisson quality metrics<br/>[quality.py]"]
  node_validation["Grid and scan metrics"]
  node_paths["Data path discovery<br/>[paths.py]"]
  node_cli["Shared input arguments<br/>[cli.py]"]
  node_plotting["Figure output<br/>[plotting.py]"]
end

node_operator(("Beamline user"))

node_operator -->|"runs"| node_planner
node_planner -->|"loads scans"| node_reader
node_planner -->|"selects strategy"| node_recommender
node_planner -->|"allocates dwell"| node_dwell
node_planner -->|"refines levels"| node_cascade
node_planner -->|"builds regions"| node_roiutils
node_planner -->|"projects grids"| node_validation
node_planner -->|"scores quality"| node_quality
node_planner -->|"saves figure"| node_plotting
node_planner -->|"writes plan"| node_scanplan
node_planner -->|"discovers scans"| node_paths
node_roi -->|"loads scan"| node_reader
node_roi -->|"detects regions"| node_roiutils
node_trajectory -->|"loads scan"| node_reader
node_trajectory -->|"groups regions"| node_roiutils
node_morph -->|"validates mask"| node_validation
node_temporal -->|"allocates dwell"| node_dwell
node_temporal -->|"measures MSE"| node_quality
node_combined -->|"allocates dwell"| node_dwell
node_combined -->|"projects mask"| node_validation
node_recommender -->|"discovers levels"| node_cascade
node_recommender -->|"finds scans"| node_paths
node_cascade -->|"detects footprint"| node_roiutils
node_cascade -->|"projects mask"| node_validation
node_roi_validation -->|"loads scans"| node_reader
node_roi_validation -->|"detects ROIs"| node_roiutils
node_hierarchical -->|"validates cascade"| node_cascade
node_pareto -->|"compares methods"| node_validation
node_combined_validation -.->|"runs comparison"| node_combined
node_profiler -->|"profiles samples"| node_recommender
node_report_figures -->|"plots metrics"| node_quality
node_report_figures -->|"plots validation"| node_validation
node_cli -->|"finds defaults"| node_paths

click node_planner "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/10_run_pipeline.py"
click node_scanplan "https://github.com/loicpoisson/slac-xrf-project/tree/main/outputs"
click node_roi "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/01_roi_detection.py"
click node_trajectory "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/02_trajectory.py"
click node_morph "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/04_validate_morphological.py"
click node_temporal "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/07_validate_temporal.py"
click node_combined "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/08_validate_combined.py"
click node_recommender "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/09_recommend_strategy.py"
click node_cascade "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/cascade.py"
click node_roiutils "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/roi_utils.py"
click node_reader "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/hdf5_reader.py"
click node_dwell "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/dwell.py"
click node_quality "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/quality.py"
click node_validation "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/validation_utils.py"
click node_paths "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/paths.py"
click node_cli "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/cli.py"
click node_plotting "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/plotting.py"
click node_roi_validation "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/03_validate_roi.py"
click node_hierarchical "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/05_validate_hierarchical.py"
click node_pareto "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/06_pareto_sweep.py"
click node_combined_validation "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/08_validate_combined.py"
click node_profiler "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/11_profile_samples.py"
click node_report_figures "https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/12_report_figures.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_planner,node_scanplan,node_operator toneBlue
class node_roi,node_trajectory,node_morph,node_temporal,node_combined,node_recommender,node_cascade toneAmber
class node_roi_validation,node_hierarchical,node_pareto,node_combined_validation,node_profiler,node_report_figures toneMint
class node_roiutils,node_reader,node_dwell,node_quality,node_validation,node_paths,node_cli,node_plotting toneRose
```

## Components

### Planning Workflow

- [Iterative scan planner](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/10_run_pipeline.py): `scripts/10_run_pipeline.py`
- [Adaptive scan plan](https://github.com/loicpoisson/slac-xrf-project/tree/main/outputs): `outputs`

### Adaptive Methods

- [Spatial ROI detection](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/01_roi_detection.py): `scripts/01_roi_detection.py`
- [ROI trajectory](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/02_trajectory.py): `scripts/02_trajectory.py`
- [Morphological mask](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/04_validate_morphological.py): `scripts/04_validate_morphological.py`
- [Adaptive dwell](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/07_validate_temporal.py): `scripts/07_validate_temporal.py`
- [Combined strategy](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/08_validate_combined.py): `scripts/08_validate_combined.py`
- [Strategy recommender](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/09_recommend_strategy.py): `scripts/09_recommend_strategy.py`
- [Refinement cascade](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/cascade.py): `scripts/utils/cascade.py`

### Validation and Analysis

- [ROI validation](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/03_validate_roi.py): `scripts/03_validate_roi.py`
- [Cascade validation](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/05_validate_hierarchical.py): `scripts/05_validate_hierarchical.py`
- [Pareto strategy sweep](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/06_pareto_sweep.py): `scripts/06_pareto_sweep.py`
- [Combined validation](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/08_validate_combined.py): `scripts/08_validate_combined.py`
- [Sample profiler](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/11_profile_samples.py): `scripts/11_profile_samples.py`
- [Report figures](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/12_report_figures.py): `scripts/12_report_figures.py`

### Shared Runtime

- [ROI and mask tools](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/roi_utils.py): `scripts/utils/roi_utils.py`
- [SSRL HDF5 reader](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/hdf5_reader.py): `scripts/utils/hdf5_reader.py`
- [Dwell allocator](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/dwell.py): `scripts/utils/dwell.py`
- [Poisson quality metrics](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/quality.py): `scripts/utils/quality.py`
- [Grid and scan metrics](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/validation_utils.py): `scripts/utils/validation_utils.py`
- [Data path discovery](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/paths.py): `scripts/utils/paths.py`
- [Shared input arguments](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/cli.py): `scripts/utils/cli.py`
- [Figure output](https://github.com/loicpoisson/slac-xrf-project/blob/main/scripts/utils/plotting.py): `scripts/utils/plotting.py`

### Other components

- **Beamline user**

## Connections

- Beamline user → Iterative scan planner: runs (evidence: `README.md`)
- Iterative scan planner → SSRL HDF5 reader: loads scans (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Strategy recommender: selects strategy (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Dwell allocator: allocates dwell (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Refinement cascade: refines levels (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → ROI and mask tools: builds regions (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Grid and scan metrics: projects grids (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Poisson quality metrics: scores quality (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Figure output: saves figure (evidence: `scripts/10_run_pipeline.py`)
- Iterative scan planner → Adaptive scan plan: writes plan (evidence: `README.md`)
- Iterative scan planner → Data path discovery: discovers scans (evidence: `scripts/10_run_pipeline.py`)
- Spatial ROI detection → SSRL HDF5 reader: loads scan (evidence: `scripts/01_roi_detection.py`)
- Spatial ROI detection → ROI and mask tools: detects regions (evidence: `scripts/01_roi_detection.py`)
- ROI trajectory → SSRL HDF5 reader: loads scan (evidence: `scripts/02_trajectory.py`)
- ROI trajectory → ROI and mask tools: groups regions (evidence: `scripts/02_trajectory.py`)
- Morphological mask → Grid and scan metrics: validates mask (evidence: `scripts/04_validate_morphological.py`)
- Adaptive dwell → Dwell allocator: allocates dwell (evidence: `scripts/07_validate_temporal.py`)
- Adaptive dwell → Poisson quality metrics: measures MSE (evidence: `scripts/07_validate_temporal.py`)
- Combined strategy → Dwell allocator: allocates dwell (evidence: `scripts/08_validate_combined.py`)
- Combined strategy → Grid and scan metrics: projects mask (evidence: `scripts/08_validate_combined.py`)
- Strategy recommender → Refinement cascade: discovers levels (evidence: `scripts/09_recommend_strategy.py`)
- Strategy recommender → Data path discovery: finds scans (evidence: `scripts/09_recommend_strategy.py`)
- Refinement cascade → ROI and mask tools: detects footprint (evidence: `scripts/utils/cascade.py`)
- Refinement cascade → Grid and scan metrics: projects mask (evidence: `scripts/utils/cascade.py`)
- ROI validation → SSRL HDF5 reader: loads scans (evidence: `scripts/03_validate_roi.py`)
- ROI validation → ROI and mask tools: detects ROIs (evidence: `scripts/03_validate_roi.py`)
- Cascade validation → Refinement cascade: validates cascade (evidence: `scripts/05_validate_hierarchical.py`)
- Pareto strategy sweep → Grid and scan metrics: compares methods (evidence: `scripts/06_pareto_sweep.py`)
- Combined validation → Combined strategy: runs comparison (evidence: `README.md`)
- Sample profiler → Strategy recommender: profiles samples (evidence: `scripts/11_profile_samples.py`)
- Report figures → Poisson quality metrics: plots metrics (evidence: `scripts/12_report_figures.py`)
- Report figures → Grid and scan metrics: plots validation (evidence: `scripts/12_report_figures.py`)
- Shared input arguments → Data path discovery: finds defaults (evidence: `scripts/utils/cli.py`)