# nathanwalash/comp3931_individualproject architecture

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

- Interactive diagram: https://gitdiagram.com/nathanwalash/comp3931_individualproject
- Repository: https://github.com/nathanwalash/comp3931_individualproject

## Overview

This repository is a transdermal diffusion research simulator and ML-surrogate workflow. The principal path runs configured simulations, validates progressively more complex regimes, assembles run outputs into train/validation/test data, and compares black-box and physics-corrected flux-curve surrogates. The graph includes solver internals, dataset handling, and model evaluation capabilities documented in the README. Some subsystem details are documented rather than sampled directly, so those links cite the README; unsampled implementation details are not inferred.

Main entry points: [`src/skin_diffusion/run_utils.py`](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/run_utils.py) (Run setup and outputs), [`scripts/ml/train_corrective.py`](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/train_corrective.py) (Corrective training), [`scripts/ml/train_blackbox.py`](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/train_blackbox.py) (Black-box training), [`src/skin_diffusion/dataset.py`](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/dataset.py) (Run generation and assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation"]
  node_config["Run configuration<br/>[config.py]"]
  node_run_cli["Simulation runner<br/>[run_sim.py]"]
  node_run_setup["Run setup and outputs<br/>[run_utils.py]"]
  node_solver["Diffusion solver<br/>[solver.py]"]
  node_boundary["Boundary conditions<br/>[bc.py]"]
  node_operators["Diffusion operators<br/>[operators.py]"]
  node_layers["Layered fields<br/>[layers.py]"]
  node_metrics["Transport metrics<br/>[metrics.py]"]
end

subgraph group_validation["Validation"]
  node_v1["V1 numerical checks<br/>[benchmark_v1.py]"]
  node_v2["V2 literature calibration"]
  node_v3["V3 regime validation<br/>[validate_v3.py]"]
end

subgraph group_data["Dataset pipeline"]
  node_dataset_spec["Dataset specification<br/>[dataset_spec.py]"]
  node_dataset_build["Run generation and assembly<br/>[dataset.py]"]
  node_run_index["Run index<br/>[run_index.py]"]
  node_ml_dataset["ML split preparation<br/>[ml_dataset.py]"]
  node_run_loader["ML run loading<br/>[ml_run_dataset.py]"]
end

subgraph group_surrogates["Surrogate workflow"]
  node_blackbox["Black-box surrogate<br/>[blackbox_model.py]"]
  node_corrective["Corrective surrogate"]
  node_train_blackbox["Black-box training<br/>[train_blackbox.py]"]
  node_train_corrective["Corrective training"]
  node_evaluation["Surrogate evaluation<br/>[ml_metrics.py]"]
  node_diagnostics["Physics and scalar diagnostics"]
  node_plots["Curve plots<br/>[ml_curve_plots.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts run"| node_run_cli
node_run_cli -->|"loads settings"| node_config
node_run_cli -->|"runs simulation"| node_run_setup
node_run_setup -->|"builds fields"| node_layers
node_run_setup -->|"calls solver"| node_solver
node_run_setup -->|"builds patch"| node_boundary
node_solver -->|"applies conditions"| node_boundary
node_solver -->|"steps diffusion"| node_operators
node_run_setup -->|"derives transport"| node_metrics
node_researcher -->|"checks numerics"| node_v1
node_researcher -->|"checks literature fit"| node_v2
node_researcher -->|"validates final regime"| node_v3
node_v1 -->|"benchmarks"| node_solver
node_v2 -->|"compares targets"| node_metrics
node_v3 -->|"validates regime"| node_run_setup
node_dataset_spec -->|"samples parameters"| node_dataset_build
node_researcher -->|"generates runs"| node_dataset_build
node_dataset_build -->|"generates simulations"| node_run_setup
node_dataset_build -->|"indexes runs"| node_run_index
node_dataset_build -->|"assembles splits"| node_ml_dataset
node_ml_dataset -->|"loads run bundles"| node_run_loader
node_run_loader -->|"resolves run ids"| node_run_index
node_researcher -->|"trains baseline"| node_train_blackbox
node_researcher -->|"trains hybrid"| node_train_corrective
node_train_blackbox -->|"fits model"| node_blackbox
node_train_corrective -->|"fits model"| node_corrective
node_train_corrective -->|"uses backbone"| node_blackbox
node_train_blackbox -->|"computes metrics"| node_evaluation
node_train_corrective -->|"computes metrics"| node_evaluation
node_train_blackbox -->|"runs diagnostics"| node_diagnostics
node_train_corrective -->|"runs diagnostics"| node_diagnostics
node_train_blackbox -->|"creates plots"| node_plots
node_train_corrective -->|"creates plots"| node_plots

click node_config "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/config.py"
click node_run_cli "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/run_sim.py"
click node_run_setup "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/run_utils.py"
click node_solver "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/solver.py"
click node_boundary "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/bc.py"
click node_operators "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/operators.py"
click node_layers "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/layers.py"
click node_metrics "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/metrics.py"
click node_v1 "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/benchmark_v1.py"
click node_v2 "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/compare_literature.py"
click node_v3 "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/validate_v3.py"
click node_dataset_spec "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/dataset_spec.py"
click node_dataset_build "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/dataset.py"
click node_run_index "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/run_index.py"
click node_ml_dataset "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_dataset.py"
click node_run_loader "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_run_dataset.py"
click node_blackbox "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/blackbox_model.py"
click node_corrective "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/corrective_model.py"
click node_train_blackbox "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/train_blackbox.py"
click node_train_corrective "https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/train_corrective.py"
click node_evaluation "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_metrics.py"
click node_diagnostics "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_physics_diagnostics.py"
click node_plots "https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_curve_plots.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_config,node_run_cli,node_run_setup,node_solver,node_boundary,node_operators,node_layers,node_metrics toneBlue
class node_v1,node_v2,node_v3 toneAmber
class node_dataset_spec,node_dataset_build,node_run_index,node_ml_dataset,node_run_loader toneMint
class node_blackbox,node_corrective,node_train_blackbox,node_train_corrective,node_evaluation,node_diagnostics,node_plots toneRose
class node_researcher toneIndigo
```

## Components

### Simulation

- [Run configuration](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/config.py): `src/skin_diffusion/config.py`
- [Simulation runner](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/run_sim.py): `scripts/sim/run_sim.py`
- [Run setup and outputs](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/run_utils.py): `src/skin_diffusion/run_utils.py`
- [Diffusion solver](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/solver.py): `src/skin_diffusion/solver.py`
- [Boundary conditions](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/bc.py): `src/skin_diffusion/bc.py`
- [Diffusion operators](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/operators.py): `src/skin_diffusion/operators.py`
- [Layered fields](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/layers.py): `src/skin_diffusion/layers.py`
- [Transport metrics](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/metrics.py): `src/skin_diffusion/metrics.py`

### Validation

- [V1 numerical checks](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/benchmark_v1.py): `scripts/sim/benchmark_v1.py`
- [V2 literature calibration](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/compare_literature.py): `scripts/sim/compare_literature.py`
- [V3 regime validation](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/sim/validate_v3.py): `scripts/sim/validate_v3.py`

### Dataset pipeline

- [Dataset specification](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/dataset_spec.py): `src/skin_diffusion/dataset_spec.py`
- [Run generation and assembly](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/dataset.py): `src/skin_diffusion/dataset.py`
- [Run index](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/run_index.py): `src/skin_diffusion/run_index.py`
- [ML split preparation](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_dataset.py): `src/skin_diffusion/ml_dataset.py`
- [ML run loading](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_run_dataset.py): `src/skin_diffusion/ml_run_dataset.py`

### Surrogate workflow

- [Black-box surrogate](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/blackbox_model.py): `scripts/ml/blackbox_model.py`
- [Corrective surrogate](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/corrective_model.py): `scripts/ml/corrective_model.py`
- [Black-box training](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/train_blackbox.py): `scripts/ml/train_blackbox.py`
- [Corrective training](https://github.com/nathanwalash/comp3931_individualproject/blob/main/scripts/ml/train_corrective.py): `scripts/ml/train_corrective.py`
- [Surrogate evaluation](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_metrics.py): `src/skin_diffusion/ml_metrics.py`
- [Physics and scalar diagnostics](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_physics_diagnostics.py): `src/skin_diffusion/ml_physics_diagnostics.py`
- [Curve plots](https://github.com/nathanwalash/comp3931_individualproject/blob/main/src/skin_diffusion/ml_curve_plots.py): `src/skin_diffusion/ml_curve_plots.py`

### Other components

- **Researcher**

## Connections

- Researcher → Simulation runner: starts run (evidence: `README.md`)
- Simulation runner → Run configuration: loads settings (evidence: `scripts/sim/run_sim.py`)
- Simulation runner → Run setup and outputs: runs simulation (evidence: `scripts/sim/run_sim.py`)
- Run setup and outputs → Layered fields: builds fields (evidence: `src/skin_diffusion/run_utils.py`)
- Run setup and outputs → Diffusion solver: calls solver (evidence: `src/skin_diffusion/run_utils.py`)
- Run setup and outputs → Boundary conditions: builds patch (evidence: `src/skin_diffusion/run_utils.py`)
- Diffusion solver → Boundary conditions: applies conditions (evidence: `src/skin_diffusion/solver.py`)
- Diffusion solver → Diffusion operators: steps diffusion (evidence: `src/skin_diffusion/solver.py`)
- Run setup and outputs → Transport metrics: derives transport (evidence: `src/skin_diffusion/run_utils.py`)
- Researcher → V1 numerical checks: checks numerics (evidence: `README.md`)
- Researcher → V2 literature calibration: checks literature fit (evidence: `README.md`)
- Researcher → V3 regime validation: validates final regime (evidence: `README.md`)
- V1 numerical checks → Diffusion solver: benchmarks (evidence: `scripts/sim/benchmark_v1.py`)
- V2 literature calibration → Transport metrics: compares targets (evidence: `README.md`)
- V3 regime validation → Run setup and outputs: validates regime (evidence: `scripts/sim/validate_v3.py`)
- Dataset specification → Run generation and assembly: samples parameters (evidence: `scripts/sim/make_dataset.py`)
- Researcher → Run generation and assembly: generates runs (evidence: `README.md`)
- Run generation and assembly → Run setup and outputs: generates simulations (evidence: `src/skin_diffusion/dataset.py`)
- Run generation and assembly → Run index: indexes runs (evidence: `scripts/sim/check_runs.py`)
- Run generation and assembly → ML split preparation: assembles splits
- ML split preparation → ML run loading: loads run bundles (evidence: `src/skin_diffusion/ml_dataset.py`)
- ML run loading → Run index: resolves run ids (evidence: `src/skin_diffusion/ml_run_dataset.py`)
- Researcher → Black-box training: trains baseline (evidence: `README.md`)
- Researcher → Corrective training: trains hybrid (evidence: `README.md`)
- Black-box training → Black-box surrogate: fits model (evidence: `scripts/ml/train_blackbox.py`)
- Corrective training → Corrective surrogate: fits model (evidence: `scripts/ml/train_corrective.py`)
- Corrective training → Black-box surrogate: uses backbone (evidence: `scripts/ml/train_corrective.py`)
- Black-box training → Surrogate evaluation: computes metrics (evidence: `scripts/ml/train_blackbox.py`)
- Corrective training → Surrogate evaluation: computes metrics (evidence: `scripts/ml/train_corrective.py`)
- Black-box training → Physics and scalar diagnostics: runs diagnostics (evidence: `scripts/ml/train_blackbox.py`)
- Corrective training → Physics and scalar diagnostics: runs diagnostics (evidence: `scripts/ml/train_corrective.py`)
- Black-box training → Curve plots: creates plots (evidence: `scripts/ml/train_blackbox.py`)
- Corrective training → Curve plots: creates plots (evidence: `scripts/ml/train_corrective.py`)
