# romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis architecture

> Architecture diagram of the GitHub repository romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis
- Repository: https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis

## Overview

This repository is an ML research pipeline for diagnosing faults in simulated pressurized-water-reactor sensor time series. The user-facing workflow is to obtain and preprocess NPPAD data, train and evaluate anomaly detectors and accident classifiers, and train a physics-informed digital twin. Classification interpretability and uncertainty support diagnosis; a documented cross-validation script combines classifier outcomes with twin physics residuals. Edges reflect README workflow statements and shown/import-indexed dependencies; unsampled source limits finer runtime wiring.

Main entry points: [`scripts/train_classifier.py`](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/train_classifier.py) (Classifier training entry), [`src/data/dataset.py`](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/dataset.py) (Window dataset), [`scripts/pipeline_xvalidation.py`](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/pipeline_xvalidation.py) (Pipeline cross-validation), [`data/scripts/download.py`](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/download.py) (Dataset download)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_download["Dataset download<br/>[download.py]"]
  node_convert["MDB conversion<br/>[convert_mdb.py]"]
  node_preprocess["Window preprocessing<br/>[preprocess.py]"]
  node_windowdata["Window dataset<br/>[dataset.py]"]
  node_twindata["Twin dataset<br/>[dataset_twin.py]"]
  node_transforms["Data transforms<br/>[transforms.py]"]
end

subgraph group_anomaly["Anomaly detection"]
  node_anomaly_models["Anomaly detectors<br/>[autoencoder.py]"]
  node_anomaly_train["Anomaly training<br/>[trainer.py]"]
end

subgraph group_diagnosis["Accident diagnosis"]
  node_classifier["Accident classifier<br/>[classifier.py]"]
  node_interpret["Root-cause attribution"]
  node_classmetrics["Classification metrics"]
end

subgraph group_twin["Digital twin"]
  node_surrogate["Reactor surrogate<br/>[surrogate.py]"]
  node_physicsloss["Physics-informed loss<br/>[loss.py]"]
  node_physics["Reactor physics<br/>[physics.py]"]
  node_twintrain["Twin training entry"]
end

subgraph group_support["Training and evaluation"]
  node_config["Experiment config<br/>[config.py]"]
  node_evaluation["Anomaly metrics<br/>[metrics.py]"]
  node_uncertainty["Uncertainty estimates<br/>[uncertainty.py]"]
  node_classifiertrain["Classifier training entry"]
  node_xvalidation["Pipeline cross-validation"]
end

node_user(("Research user"))
node_nppad[("NPPAD data")]

node_user -->|"starts with"| node_download
node_nppad -->|"provides data"| node_download
node_download -.->|"converts files"| node_convert
node_download -->|"precedes"| node_preprocess
node_preprocess -->|"creates processed data"| node_windowdata
node_windowdata -.->|"supplies windows"| node_anomaly_train
node_windowdata -->|"loads windows"| node_classifiertrain
node_twindata -->|"loads context pairs"| node_twintrain
node_classifiertrain -->|"builds model"| node_classifier
node_classifiertrain -.->|"uses trainer"| node_anomaly_train
node_anomaly_train -->|"trains model"| node_anomaly_models
node_classifiertrain -->|"loads config"| node_config
node_twintrain -->|"loads config"| node_config
node_twintrain -->|"builds model"| node_surrogate
node_surrogate -->|"uses loss"| node_physicsloss
node_physicsloss -->|"computes constraints"| node_physics
node_classifier -->|"supports attribution"| node_interpret
node_classifier -->|"evaluated by"| node_classmetrics
node_anomaly_models -->|"evaluated by"| node_evaluation
node_anomaly_models -.->|"supports uncertainty"| node_uncertainty
node_user -->|"trains classifier"| node_classifiertrain
node_user -->|"trains twin"| node_twintrain
node_xvalidation -->|"loads validation data"| node_windowdata
node_xvalidation -->|"builds classifier"| node_classifier
node_xvalidation -->|"builds surrogate"| node_surrogate
node_xvalidation -->|"computes residuals"| node_physics
node_transforms -.->|"transforms data"| node_windowdata

click node_download "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/download.py"
click node_convert "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/convert_mdb.py"
click node_preprocess "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/preprocess.py"
click node_windowdata "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/dataset.py"
click node_twindata "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/dataset_twin.py"
click node_transforms "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/transforms.py"
click node_anomaly_models "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/anomaly/autoencoder.py"
click node_anomaly_train "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/training/trainer.py"
click node_classifier "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/diagnosis/classifier.py"
click node_interpret "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/diagnosis/interpretability.py"
click node_classmetrics "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/evaluation/classification_metrics.py"
click node_surrogate "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/digital_twin/surrogate.py"
click node_physicsloss "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/digital_twin/loss.py"
click node_physics "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/digital_twin/physics.py"
click node_twintrain "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/train_digital_twin.py"
click node_config "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/utils/config.py"
click node_evaluation "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/evaluation/metrics.py"
click node_uncertainty "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/evaluation/uncertainty.py"
click node_classifiertrain "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/train_classifier.py"
click node_xvalidation "https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/pipeline_xvalidation.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_download,node_convert,node_preprocess,node_windowdata,node_twindata,node_transforms,node_user toneBlue
class node_anomaly_models,node_anomaly_train,node_nppad toneAmber
class node_classifier,node_interpret,node_classmetrics toneMint
class node_surrogate,node_physicsloss,node_physics,node_twintrain toneRose
class node_config,node_evaluation,node_uncertainty,node_classifiertrain,node_xvalidation toneIndigo
```

## Components

### Data preparation

- [Dataset download](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/download.py): `data/scripts/download.py`
- [MDB conversion](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/convert_mdb.py): `data/scripts/convert_mdb.py`
- [Window preprocessing](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/data/scripts/preprocess.py): `data/scripts/preprocess.py`
- [Window dataset](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/dataset.py): `src/data/dataset.py`
- [Twin dataset](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/dataset_twin.py): `src/data/dataset_twin.py`
- [Data transforms](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/data/transforms.py): `src/data/transforms.py`

### Anomaly detection

- [Anomaly detectors](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/anomaly/autoencoder.py): `src/models/anomaly/autoencoder.py`
- [Anomaly training](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/training/trainer.py): `src/training/trainer.py`

### Accident diagnosis

- [Accident classifier](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/diagnosis/classifier.py): `src/models/diagnosis/classifier.py`
- [Root-cause attribution](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/diagnosis/interpretability.py): `src/models/diagnosis/interpretability.py`
- [Classification metrics](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/evaluation/classification_metrics.py): `src/evaluation/classification_metrics.py`

### Digital twin

- [Reactor surrogate](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/digital_twin/surrogate.py): `src/models/digital_twin/surrogate.py`
- [Physics-informed loss](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/digital_twin/loss.py): `src/models/digital_twin/loss.py`
- [Reactor physics](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/models/digital_twin/physics.py): `src/models/digital_twin/physics.py`
- [Twin training entry](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/train_digital_twin.py): `scripts/train_digital_twin.py`

### Training and evaluation

- [Experiment config](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/utils/config.py): `src/utils/config.py`
- [Anomaly metrics](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Uncertainty estimates](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/src/evaluation/uncertainty.py): `src/evaluation/uncertainty.py`
- [Classifier training entry](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/train_classifier.py): `scripts/train_classifier.py`
- [Pipeline cross-validation](https://github.com/romeo-5/nuclear-power-plant-accident-diagnosis-and-root-cause-analysis/blob/main/scripts/pipeline_xvalidation.py): `scripts/pipeline_xvalidation.py`

### Other components

- **Research user**
- **NPPAD data**

## Connections

- Research user → Dataset download: starts with (evidence: `README.md`)
- NPPAD data → Dataset download: provides data (evidence: `README.md`)
- Dataset download → MDB conversion: converts files
- Dataset download → Window preprocessing: precedes (evidence: `README.md`)
- Window preprocessing → Window dataset: creates processed data (evidence: `README.md`)
- Window dataset → Anomaly training: supplies windows
- Window dataset → Classifier training entry: loads windows (evidence: `scripts/train_classifier.py`)
- Twin dataset → Twin training entry: loads context pairs (evidence: `scripts/train_digital_twin.py`)
- Classifier training entry → Accident classifier: builds model (evidence: `scripts/train_classifier.py`)
- Classifier training entry → Anomaly training: uses trainer (evidence: `scripts/train_classifier.py`)
- Anomaly training → Anomaly detectors: trains model (evidence: `src/training/trainer.py`)
- Classifier training entry → Experiment config: loads config (evidence: `scripts/train_classifier.py`)
- Twin training entry → Experiment config: loads config (evidence: `scripts/train_digital_twin.py`)
- Twin training entry → Reactor surrogate: builds model (evidence: `scripts/train_digital_twin.py`)
- Reactor surrogate → Physics-informed loss: uses loss (evidence: `src/models/digital_twin/surrogate.py`)
- Physics-informed loss → Reactor physics: computes constraints (evidence: `src/models/digital_twin/loss.py`)
- Accident classifier → Root-cause attribution: supports attribution (evidence: `README.md`)
- Accident classifier → Classification metrics: evaluated by (evidence: `README.md`)
- Anomaly detectors → Anomaly metrics: evaluated by (evidence: `README.md`)
- Anomaly detectors → Uncertainty estimates: supports uncertainty
- Research user → Classifier training entry: trains classifier (evidence: `README.md`)
- Research user → Twin training entry: trains twin (evidence: `README.md`)
- Pipeline cross-validation → Window dataset: loads validation data (evidence: `scripts/pipeline_xvalidation.py`)
- Pipeline cross-validation → Accident classifier: builds classifier (evidence: `scripts/pipeline_xvalidation.py`)
- Pipeline cross-validation → Reactor surrogate: builds surrogate (evidence: `scripts/pipeline_xvalidation.py`)
- Pipeline cross-validation → Reactor physics: computes residuals (evidence: `scripts/pipeline_xvalidation.py`)
- Data transforms → Window dataset: transforms data