# lauragrundy100/vcdsuite-public architecture

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

- Interactive diagram: https://gitdiagram.com/lauragrundy100/vcdsuite-public
- Repository: https://github.com/lauragrundy100/vcdsuite-public

## Overview

VCDsuite is a notebook-led analysis pipeline for comparing ORCA-calculated and measured VCD/IR spectra, then assessing fit, planning measurements, evaluating evidence tiers, and preparing comparisons or screening predictions. The documented workflow runs setup, plotting, vibrational analysis, optimisation, prediction, evidence analysis, and final comparison; appendices screen unmeasured molecules with theory alone or theory plus IR. Internal edges use the supplied source references; notebook-stage links follow the README. Several notebook and integration implementations were not sampled, so their internal calls are not inferred.

Main entry points: [`01_setup.ipynb`](https://github.com/lauragrundy100/vcdsuite-public/blob/main/01_setup.ipynb) (Data setup), [`VCDlib/presets.py`](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/presets.py) (Molecule constants), [`VCDlib/stage4.py`](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage4.py) (Fit and scoring), [`VCDlib/transform.py`](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/transform.py) (Spectrum transforms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data and setup"]
  node_databank[("Spectrum registry<br/>[registry.py]")]
  node_setup["Data setup<br/>[01_setup.ipynb]"]
  node_cache["ORCA cache<br/>[cache_builder.py]"]
  node_constants["Molecule constants<br/>[presets.py]"]
end

subgraph group_spectra["Spectra and modes"]
  node_spectrum_io["Spectrum loading<br/>[io_.py]"]
  node_transform["Spectrum transforms<br/>[transform.py]"]
  node_plotting["Spectrum plotting<br/>[02_plotting.ipynb]"]
  node_figures["Figure engine<br/>[figures.py]"]
  node_mode_engine["Mode analysis<br/>[analysis.py]"]
  node_mode_parse["Mode parsing<br/>[modes.py]"]
  node_segments["Segment boundaries<br/>[segments.py]"]
  node_vibration_stage["Vibrational analysis"]
end

subgraph group_inference["Fit and prediction"]
  node_optimise["IR fit<br/>[optimise.py]"]
  node_fit_stage["Fit and scoring<br/>[stage4.py]"]
  node_fit_plots["Fit figures<br/>[stage4_plots.py]"]
  node_optimisation_notebook["Optimisation stage"]
  node_prediction["Path planning<br/>[stage5.py]"]
  node_prediction_notebook["Prediction stage"]
end

subgraph group_reporting["Evidence and reports"]
  node_evidence["Evidence tiers<br/>[stage6.py]"]
  node_evidence_notebook["Evidence stage<br/>[06_evidence.ipynb]"]
  node_appendix_a["Theory-only screen<br/>[appendixA.py]"]
  node_appendix_b["Theory-plus-IR screen<br/>[appendixB.py]"]
  node_comparison["Final comparison"]
  node_report_figures["Report figures<br/>[figures_report.py]"]
end

subgraph group_operations["ORCA operations"]
  node_launcher["ORCA job launcher<br/>[00_orca-launch.py]"]
end

node_researcher(("Researcher"))
node_measurements["Measured spectra"]
node_orca_data["ORCA calculations"]

node_researcher -->|"starts pipeline"| node_setup
node_measurements -->|"registered as rows"| node_databank
node_orca_data -->|"provides calculations"| node_setup
node_setup -->|"validates registry"| node_databank
node_setup -->|"builds cache"| node_cache
node_setup -->|"writes constants"| node_constants
node_databank -->|"supplies rows"| node_spectrum_io
node_spectrum_io -.->|"loads spectra for"| node_transform
node_transform -->|"transforms spectra for"| node_figures
node_constants -->|"provides settings"| node_figures
node_cache -->|"feeds plotting"| node_plotting
node_constants -->|"provides settings"| node_plotting
node_plotting -.->|"renders plots"| node_figures
node_researcher -->|"runs analysis"| node_vibration_stage
node_orca_data -->|"supplies mode inputs"| node_mode_engine
node_mode_engine -.->|"produces NMA for parsing"| node_mode_parse
node_mode_parse -.->|"derives mode character"| node_segments
node_vibration_stage -->|"writes boundaries"| node_segments
node_segments -->|"updates molecule data"| node_constants
node_optimise -->|"uses transformations"| node_transform
node_optimise -->|"reads molecule settings"| node_constants
node_optimisation_notebook -.->|"fits IR widths"| node_optimise
node_optimisation_notebook -->|"scores theory"| node_fit_stage
node_fit_stage -->|"uses transformations"| node_transform
node_fit_stage -.->|"supplies fit results"| node_fit_plots
node_optimisation_notebook -->|"provides frozen fit"| node_prediction_notebook
node_prediction -->|"uses fit computations"| node_fit_stage
node_prediction_notebook -.->|"plans path lengths"| node_prediction
node_prediction -->|"uses transformations"| node_transform
node_evidence -->|"uses scoring"| node_fit_stage
node_evidence -->|"uses predictions"| node_prediction
node_evidence_notebook -.->|"computes evidence tiers"| node_evidence
node_researcher -->|"screens theory alone"| node_appendix_a
node_researcher -->|"screens with IR"| node_appendix_b
node_researcher -->|"reviews results"| node_comparison
node_comparison -.->|"produces report figures"| node_report_figures
node_report_figures -->|"uses figure engine"| node_figures
node_report_figures -->|"uses fit results"| node_optimise
node_researcher -->|"launches ORCA jobs"| node_launcher

click node_databank "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/registry.py"
click node_setup "https://github.com/lauragrundy100/vcdsuite-public/blob/main/01_setup.ipynb"
click node_cache "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/cache_builder.py"
click node_constants "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/presets.py"
click node_spectrum_io "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/io_.py"
click node_transform "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/transform.py"
click node_plotting "https://github.com/lauragrundy100/vcdsuite-public/blob/main/02_plotting.ipynb"
click node_figures "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/figures.py"
click node_mode_engine "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VAlib/analysis.py"
click node_mode_parse "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VAlib/modes.py"
click node_segments "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VAlib/segments.py"
click node_vibration_stage "https://github.com/lauragrundy100/vcdsuite-public/blob/main/03_vibration-analysis.ipynb"
click node_optimise "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/optimise.py"
click node_fit_stage "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage4.py"
click node_fit_plots "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage4_plots.py"
click node_optimisation_notebook "https://github.com/lauragrundy100/vcdsuite-public/blob/main/04_optimisation.ipynb"
click node_prediction "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage5.py"
click node_prediction_notebook "https://github.com/lauragrundy100/vcdsuite-public/blob/main/05_prediction.ipynb"
click node_evidence "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage6.py"
click node_evidence_notebook "https://github.com/lauragrundy100/vcdsuite-public/blob/main/06_evidence.ipynb"
click node_appendix_a "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/appendixA.py"
click node_appendix_b "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/appendixB.py"
click node_comparison "https://github.com/lauragrundy100/vcdsuite-public/blob/main/07_comparison.ipynb"
click node_report_figures "https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/figures_report.py"
click node_launcher "https://github.com/lauragrundy100/vcdsuite-public/blob/main/00_orca-launch.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_databank,node_setup,node_cache,node_constants toneBlue
class node_spectrum_io,node_transform,node_plotting,node_figures,node_mode_engine,node_mode_parse,node_segments,node_vibration_stage toneAmber
class node_optimise,node_fit_stage,node_fit_plots,node_optimisation_notebook,node_prediction,node_prediction_notebook toneMint
class node_evidence,node_evidence_notebook,node_appendix_a,node_appendix_b,node_comparison,node_report_figures toneRose
class node_launcher,node_researcher,node_measurements,node_orca_data toneIndigo
```

## Components

### Data and setup

- [Spectrum registry](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/registry.py): `VCDlib/registry.py`
- [Data setup](https://github.com/lauragrundy100/vcdsuite-public/blob/main/01_setup.ipynb): `01_setup.ipynb`
- [ORCA cache](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/cache_builder.py): `VCDlib/cache_builder.py`
- [Molecule constants](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/presets.py): `VCDlib/presets.py`

### Spectra and modes

- [Spectrum loading](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/io_.py): `VCDlib/io_.py`
- [Spectrum transforms](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/transform.py): `VCDlib/transform.py`
- [Spectrum plotting](https://github.com/lauragrundy100/vcdsuite-public/blob/main/02_plotting.ipynb): `02_plotting.ipynb`
- [Figure engine](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/figures.py): `VCDlib/figures.py`
- [Mode analysis](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VAlib/analysis.py): `VAlib/analysis.py`
- [Mode parsing](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VAlib/modes.py): `VAlib/modes.py`
- [Segment boundaries](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VAlib/segments.py): `VAlib/segments.py`
- [Vibrational analysis](https://github.com/lauragrundy100/vcdsuite-public/blob/main/03_vibration-analysis.ipynb): `03_vibration-analysis.ipynb`

### Fit and prediction

- [IR fit](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/optimise.py): `VCDlib/optimise.py`
- [Fit and scoring](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage4.py): `VCDlib/stage4.py`
- [Fit figures](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage4_plots.py): `VCDlib/stage4_plots.py`
- [Optimisation stage](https://github.com/lauragrundy100/vcdsuite-public/blob/main/04_optimisation.ipynb): `04_optimisation.ipynb`
- [Path planning](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage5.py): `VCDlib/stage5.py`
- [Prediction stage](https://github.com/lauragrundy100/vcdsuite-public/blob/main/05_prediction.ipynb): `05_prediction.ipynb`

### Evidence and reports

- [Evidence tiers](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/stage6.py): `VCDlib/stage6.py`
- [Evidence stage](https://github.com/lauragrundy100/vcdsuite-public/blob/main/06_evidence.ipynb): `06_evidence.ipynb`
- [Theory-only screen](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/appendixA.py): `VCDlib/appendixA.py`
- [Theory-plus-IR screen](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/appendixB.py): `VCDlib/appendixB.py`
- [Final comparison](https://github.com/lauragrundy100/vcdsuite-public/blob/main/07_comparison.ipynb): `07_comparison.ipynb`
- [Report figures](https://github.com/lauragrundy100/vcdsuite-public/blob/main/VCDlib/figures_report.py): `VCDlib/figures_report.py`

### ORCA operations

- [ORCA job launcher](https://github.com/lauragrundy100/vcdsuite-public/blob/main/00_orca-launch.py): `00_orca-launch.py`

### Other components

- **Researcher**
- **Measured spectra**
- **ORCA calculations**

## Connections

- Researcher → Data setup: starts pipeline (evidence: `README.md`)
- Measured spectra → Spectrum registry: registered as rows (evidence: `README.md`)
- ORCA calculations → Data setup: provides calculations (evidence: `README.md`)
- Data setup → Spectrum registry: validates registry (evidence: `README.md`)
- Data setup → ORCA cache: builds cache (evidence: `README.md`)
- Data setup → Molecule constants: writes constants (evidence: `README.md`)
- Spectrum registry → Spectrum loading: supplies rows (evidence: `VCDlib/io_.py`)
- Spectrum loading → Spectrum transforms: loads spectra for (evidence: `VCDlib/transform.py`)
- Spectrum transforms → Figure engine: transforms spectra for (evidence: `VCDlib/figures.py`)
- Molecule constants → Figure engine: provides settings (evidence: `VCDlib/figures.py`)
- ORCA cache → Spectrum plotting: feeds plotting (evidence: `README.md`)
- Molecule constants → Spectrum plotting: provides settings (evidence: `README.md`)
- Spectrum plotting → Figure engine: renders plots
- Researcher → Vibrational analysis: runs analysis (evidence: `README.md`)
- ORCA calculations → Mode analysis: supplies mode inputs (evidence: `README.md`)
- Mode analysis → Mode parsing: produces NMA for parsing
- Mode parsing → Segment boundaries: derives mode character
- Vibrational analysis → Segment boundaries: writes boundaries (evidence: `README.md`)
- Segment boundaries → Molecule constants: updates molecule data (evidence: `README.md`)
- IR fit → Spectrum transforms: uses transformations (evidence: `VCDlib/optimise.py`)
- IR fit → Molecule constants: reads molecule settings (evidence: `VCDlib/optimise.py`)
- Optimisation stage → IR fit: fits IR widths
- Optimisation stage → Fit and scoring: scores theory (evidence: `README.md`)
- Fit and scoring → Spectrum transforms: uses transformations (evidence: `VCDlib/stage4.py`)
- Fit and scoring → Fit figures: supplies fit results (evidence: `VCDlib/stage4_plots.py`)
- Optimisation stage → Prediction stage: provides frozen fit (evidence: `README.md`)
- Path planning → Fit and scoring: uses fit computations (evidence: `VCDlib/stage5.py`)
- Prediction stage → Path planning: plans path lengths
- Path planning → Spectrum transforms: uses transformations (evidence: `VCDlib/stage5.py`)
- Evidence tiers → Fit and scoring: uses scoring (evidence: `VCDlib/stage6.py`)
- Evidence tiers → Path planning: uses predictions (evidence: `VCDlib/stage6.py`)
- Evidence stage → Evidence tiers: computes evidence tiers
- Researcher → Theory-only screen: screens theory alone (evidence: `README.md`)
- Researcher → Theory-plus-IR screen: screens with IR (evidence: `README.md`)
- Researcher → Final comparison: reviews results (evidence: `README.md`)
- Final comparison → Report figures: produces report figures
- Report figures → Figure engine: uses figure engine (evidence: `VCDlib/figures_report.py`)
- Report figures → IR fit: uses fit results (evidence: `VCDlib/figures_report.py`)
- Researcher → ORCA job launcher: launches ORCA jobs (evidence: `README.md`)
