# utat-ss/finch-science_syntheticdata architecture

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

- Interactive diagram: https://gitdiagram.com/utat-ss/finch-science_syntheticdata
- Repository: https://github.com/utat-ss/finch-science_syntheticdata

## Overview

FINCH-Science_SyntheticData develops conditional generators for hyperspectral spectra, synthesizes spectra under sampled or specified abundances, and evaluates whether the synthetic data improve unmixing and resemble real-data distributions. The principal workflow is training a generator, loading it for synthesis, then testing generated data with unmix/critic and nearest-neighbor metrics. The graph preserves the documented autoencoder, diffusion, and evaluation branches. Some subsystem wiring is supported only by the SOURCE INDEX or README; unsampled internals and relationships are not inferred.

Main entry points: [`defs/synthesis/loaders.py`](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/loaders.py) (Synthesis model loaders), [`defs/hsi-cvae/model.py`](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/model.py) (CVAE model selection), [`defs/testing/unmix/script.py`](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/script.py) (Unmix critic metric), [`defs/testing/master/script.py`](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/master/script.py) (Evaluation orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Generator training"]
  node_diff_data["Diffusion data prep"]
  node_diff_train["Diffusion training<br/>[train.py]"]
  node_vae_data["VAE data prep"]
  node_vae_train["VAE training<br/>[train.py]"]
  node_cvae_entry["CVAE training entry<br/>[main.py]"]
end

subgraph group_generators["Generator models"]
  node_cvae_model_router["CVAE model selection<br/>[model.py]"]
  node_cvae_dual["Dual-path CVAE<br/>[cvae.py]"]
  node_cvae_conformer["Conformer CVAE<br/>[cvae.py]"]
  node_cvae_losses["CVAE losses<br/>[losses.py]"]
  node_vae_model["VAE autoencoder<br/>[ae.py]"]
  node_tcvae_model["TCVAE model<br/>[tcvae_model.py]"]
  node_tcvae_backbone["TCVAE backbone<br/>[tcvae_backbone.py]"]
  node_diffusion_core["Gaussian diffusion<br/>[diffusion.py]"]
  node_epsilon_unet["Conditional epsilon U-Net<br/>[unet.py]"]
  node_epsilon_addons["Conformer components<br/>[epsilon_addons.py]"]
  node_noise_schedule["Noise schedules"]
end

subgraph group_synthesis["Data synthesis"]
  node_synth_entry["Synthesis entry<br/>[script.py]"]
  node_synth_loaders["Synthesis model loaders<br/>[loaders.py]"]
  node_abundance["Abundance sampling"]
  node_synth_functions["Spectrum samplers<br/>[synth_func.py]"]
  node_lean_synth["Lean synthesis<br/>[lean_synth.py]"]
end

subgraph group_evaluation["Synthetic data evaluation"]
  node_master_test["Evaluation orchestrator<br/>[script.py]"]
  node_nearest_test["Nearest-neighbor metric<br/>[script.py]"]
  node_unmix_test["Unmix critic metric<br/>[script.py]"]
  node_unmix_data["Critic data preparation<br/>[data.py]"]
  node_critic_train["Critic training<br/>[train.py]"]
  node_critic_loaders["Critic model loaders<br/>[loaders.py]"]
end

node_user(("Research user"))

node_user -.->|"starts training"| node_cvae_entry
node_user -.->|"starts training"| node_diff_train
node_user -.->|"starts training"| node_vae_train
node_user -.->|"starts synthesis"| node_synth_entry
node_user -.->|"starts testing"| node_master_test
node_cvae_entry -->|"uses model"| node_cvae_model_router
node_cvae_model_router -->|"selects architecture"| node_cvae_dual
node_cvae_model_router -->|"selects architecture"| node_cvae_conformer
node_cvae_model_router -->|"uses losses"| node_cvae_losses
node_tcvae_model -->|"uses backbone"| node_tcvae_backbone
node_diffusion_core -->|"uses schedule"| node_noise_schedule
node_epsilon_unet -->|"uses components"| node_epsilon_addons
node_diff_data -.->|"prepares data"| node_diff_train
node_vae_data -.->|"prepares data"| node_vae_train
node_synth_entry -.->|"loads models"| node_synth_loaders
node_synth_loaders -->|"loads generator"| node_diffusion_core
node_synth_loaders -->|"loads generator"| node_vae_model
node_synth_loaders -->|"loads generator"| node_tcvae_model
node_synth_loaders -->|"uses sampler"| node_abundance
node_synth_loaders -->|"uses samplers"| node_synth_functions
node_synth_functions -->|"uses sampling"| node_abundance
node_lean_synth -->|"uses samplers"| node_synth_functions
node_master_test -->|"dispatches metric"| node_nearest_test
node_master_test -->|"dispatches metric"| node_unmix_test
node_unmix_test -->|"prepares data"| node_unmix_data
node_unmix_test -->|"loads critic"| node_critic_loaders
node_unmix_test -->|"trains critic"| node_critic_train
node_critic_train -->|"uses data"| node_unmix_data
node_critic_loaders -.->|"configures training"| node_critic_train

click node_diff_data "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/data/data_preperation.py"
click node_diff_train "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/train.py"
click node_vae_data "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/vae/data/data_preparation.py"
click node_vae_train "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/vae/train.py"
click node_cvae_entry "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/main.py"
click node_cvae_model_router "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/model.py"
click node_cvae_dual "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/models/dual_path_transformer/cvae.py"
click node_cvae_conformer "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/models/conformer/cvae.py"
click node_cvae_losses "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/models/losses.py"
click node_vae_model "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/vae/ae.py"
click node_tcvae_model "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/tcvae/tcvae_model.py"
click node_tcvae_backbone "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/tcvae/tcvae_backbone.py"
click node_diffusion_core "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/diffusion.py"
click node_epsilon_unet "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/epsilon/unet.py"
click node_epsilon_addons "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/epsilon/auxiliary/epsilon_addons.py"
click node_noise_schedule "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/noise/noise_scheduling.py"
click node_synth_entry "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/script.py"
click node_synth_loaders "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/loaders.py"
click node_abundance "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/abundance_sampler.py"
click node_synth_functions "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/synth_func.py"
click node_lean_synth "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/lean/lean_synth.py"
click node_master_test "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/master/script.py"
click node_nearest_test "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/nearest_neighbor/script.py"
click node_unmix_test "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/script.py"
click node_unmix_data "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/data/data.py"
click node_critic_train "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/critic_train/train.py"
click node_critic_loaders "https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/loaders/loaders.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_diff_data,node_diff_train,node_vae_data,node_vae_train,node_cvae_entry,node_user toneBlue
class node_cvae_model_router,node_cvae_dual,node_cvae_conformer,node_cvae_losses,node_vae_model,node_tcvae_model,node_tcvae_backbone,node_diffusion_core,node_epsilon_unet,node_epsilon_addons,node_noise_schedule toneAmber
class node_synth_entry,node_synth_loaders,node_abundance,node_synth_functions,node_lean_synth toneMint
class node_master_test,node_nearest_test,node_unmix_test,node_unmix_data,node_critic_train,node_critic_loaders toneRose
```

## Components

### Generator training

- [Diffusion data prep](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/data/data_preperation.py): `defs/diffusion/data/data_preperation.py`
- [Diffusion training](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/train.py): `defs/diffusion/train.py`
- [VAE data prep](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/vae/data/data_preparation.py): `defs/vae/data/data_preparation.py`
- [VAE training](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/vae/train.py): `defs/vae/train.py`
- [CVAE training entry](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/main.py): `defs/hsi-cvae/main.py`

### Generator models

- [CVAE model selection](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/model.py): `defs/hsi-cvae/model.py`
- [Dual-path CVAE](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/models/dual_path_transformer/cvae.py): `defs/hsi-cvae/models/dual_path_transformer/cvae.py`
- [Conformer CVAE](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/models/conformer/cvae.py): `defs/hsi-cvae/models/conformer/cvae.py`
- [CVAE losses](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/hsi-cvae/models/losses.py): `defs/hsi-cvae/models/losses.py`
- [VAE autoencoder](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/vae/ae.py): `defs/vae/ae.py`
- [TCVAE model](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/tcvae/tcvae_model.py): `defs/tcvae/tcvae_model.py`
- [TCVAE backbone](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/tcvae/tcvae_backbone.py): `defs/tcvae/tcvae_backbone.py`
- [Gaussian diffusion](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/diffusion.py): `defs/diffusion/diffusion.py`
- [Conditional epsilon U-Net](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/epsilon/unet.py): `defs/diffusion/epsilon/unet.py`
- [Conformer components](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/epsilon/auxiliary/epsilon_addons.py): `defs/diffusion/epsilon/auxiliary/epsilon_addons.py`
- [Noise schedules](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/diffusion/noise/noise_scheduling.py): `defs/diffusion/noise/noise_scheduling.py`

### Data synthesis

- [Synthesis entry](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/script.py): `defs/synthesis/script.py`
- [Synthesis model loaders](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/loaders.py): `defs/synthesis/loaders.py`
- [Abundance sampling](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/abundance_sampler.py): `defs/synthesis/abundance_sampler.py`
- [Spectrum samplers](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/synth_func.py): `defs/synthesis/synth_func.py`
- [Lean synthesis](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/synthesis/lean/lean_synth.py): `defs/synthesis/lean/lean_synth.py`

### Synthetic data evaluation

- [Evaluation orchestrator](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/master/script.py): `defs/testing/master/script.py`
- [Nearest-neighbor metric](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/nearest_neighbor/script.py): `defs/testing/nearest_neighbor/script.py`
- [Unmix critic metric](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/script.py): `defs/testing/unmix/script.py`
- [Critic data preparation](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/data/data.py): `defs/testing/unmix/data/data.py`
- [Critic training](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/critic_train/train.py): `defs/testing/unmix/critic_train/train.py`
- [Critic model loaders](https://github.com/utat-ss/finch-science_syntheticdata/blob/main/defs/testing/unmix/loaders/loaders.py): `defs/testing/unmix/loaders/loaders.py`

### Other components

- **Research user**

## Connections

- Research user → CVAE training entry: starts training
- Research user → Diffusion training: starts training
- Research user → VAE training: starts training
- Research user → Synthesis entry: starts synthesis
- Research user → Evaluation orchestrator: starts testing
- CVAE training entry → CVAE model selection: uses model (evidence: `defs/hsi-cvae/main.py`)
- CVAE model selection → Dual-path CVAE: selects architecture (evidence: `defs/hsi-cvae/model.py`)
- CVAE model selection → Conformer CVAE: selects architecture (evidence: `defs/hsi-cvae/model.py`)
- CVAE model selection → CVAE losses: uses losses (evidence: `defs/hsi-cvae/model.py`)
- TCVAE model → TCVAE backbone: uses backbone (evidence: `defs/tcvae/tcvae_model.py`)
- Gaussian diffusion → Noise schedules: uses schedule (evidence: `defs/diffusion/diffusion.py`)
- Conditional epsilon U-Net → Conformer components: uses components (evidence: `defs/diffusion/epsilon/unet.py`)
- Diffusion data prep → Diffusion training: prepares data
- VAE data prep → VAE training: prepares data
- Synthesis entry → Synthesis model loaders: loads models
- Synthesis model loaders → Gaussian diffusion: loads generator (evidence: `defs/synthesis/loaders.py`)
- Synthesis model loaders → VAE autoencoder: loads generator (evidence: `defs/synthesis/loaders.py`)
- Synthesis model loaders → TCVAE model: loads generator (evidence: `defs/synthesis/loaders.py`)
- Synthesis model loaders → Abundance sampling: uses sampler (evidence: `defs/synthesis/loaders.py`)
- Synthesis model loaders → Spectrum samplers: uses samplers (evidence: `defs/synthesis/loaders.py`)
- Spectrum samplers → Abundance sampling: uses sampling (evidence: `defs/synthesis/synth_func.py`)
- Lean synthesis → Spectrum samplers: uses samplers (evidence: `defs/synthesis/lean/lean_synth.py`)
- Evaluation orchestrator → Nearest-neighbor metric: dispatches metric (evidence: `defs/testing/master/script.py`)
- Evaluation orchestrator → Unmix critic metric: dispatches metric (evidence: `defs/testing/master/script.py`)
- Unmix critic metric → Critic data preparation: prepares data (evidence: `defs/testing/unmix/script.py`)
- Unmix critic metric → Critic model loaders: loads critic (evidence: `defs/testing/unmix/script.py`)
- Unmix critic metric → Critic training: trains critic (evidence: `defs/testing/unmix/script.py`)
- Critic training → Critic data preparation: uses data (evidence: `defs/testing/unmix/critic_train/train.py`)
- Critic model loaders → Critic training: configures training
