# dahbiz/tdsez architecture

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

- Interactive diagram: https://gitdiagram.com/dahbiz/tdsez
- Repository: https://github.com/dahbiz/tdsez

## Overview

TDSE-Z is a parallel B-spline solver for bound-state spectra and time-dependent quantum dynamics. The principal workflow takes an input deck through parsing and validation, constructs the spatial discretisation and operators, solves for bound states, and optionally propagates a wavefunction while recording observables and output. Separate branches cover restart/checkpointing, t-SURFF spectra, diagnostics, and post-processing. The README documents the broad workflow; source excerpts show selected operator, monitor, and propagation links, so unsampled implementation connections are omitted.

Main entry points: [`src/tdsez.cpp`](https://github.com/dahbiz/tdsez/blob/main/src/tdsez.cpp) (Solver Entry), [`src/propagator.cpp`](https://github.com/dahbiz/tdsez/blob/main/src/propagator.cpp) (Time Propagators), [`src/core.cpp`](https://github.com/dahbiz/tdsez/blob/main/src/core.cpp) (B-Spline Core), [`src/assembly/assembly.cpp`](https://github.com/dahbiz/tdsez/blob/main/src/assembly/assembly.cpp) (Operator Assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Input and Setup"]
  node_input["Input Deck"]
  node_parser["Input Parsing<br/>[parser.cpp]"]
  node_validation["Input Validation"]
  node_entry["Solver Entry<br/>[tdsez.cpp]"]
end

subgraph group_physics["Physics and Solvers"]
  node_knots["Knot Sequences<br/>[core_knots.cpp]"]
  node_core["B-Spline Core<br/>[core.cpp]"]
  node_assembly["Operator Assembly<br/>[assembly.cpp]"]
  node_sumfact["Sum-Factored Kernels<br/>[sumfact.cpp]"]
  node_band["Banded Insertion<br/>[band.cpp]"]
  node_manager["Operator Manager<br/>[manager.cpp]"]
  node_tensorops["Tensor Operators<br/>[tensorops.cpp]"]
end

subgraph group_runtime["Propagation and Observables"]
  node_propagator["Time Propagators<br/>[propagator.cpp]"]
  node_multigrid["B-Spline Multigrid<br/>[multigrid.cpp]"]
  node_monitor["Observable Monitor<br/>[monitor.cpp]"]
  node_quadobs["Quadrature Observables<br/>[quadobs.cpp]"]
  node_checkpoint["Checkpoint Restart<br/>[checkpoint.cpp]"]
  node_tsurff["t-SURFF Spectra<br/>[tsurff.cpp]"]
end

subgraph group_results["Results and Analysis"]
  node_hdf5[("HDF5 Results")]
  node_diagnostics["Diagnostics<br/>[diagnostics.cpp]"]
  node_dipoles["Dipole Analysis<br/>[dipoles.cpp]"]
  node_spectrum["Dipole Spectrum"]
  node_recombination["Recombination Analysis<br/>[recombination.cpp]"]
end

node_user(("User"))
node_petsc["PETSc / MPI"]
node_slepc["SLEPc"]
node_petiga["PetIGA"]

node_user -->|"configures"| node_input
node_input -->|"starts run"| node_entry
node_entry -.->|"reads input"| node_parser
node_parser -->|"validates"| node_validation
node_entry -->|"builds solver"| node_core
node_core -.->|"uses knots"| node_knots
node_core -->|"assembles operators"| node_assembly
node_assembly -->|"uses kernels"| node_sumfact
node_assembly -->|"inserts matrices"| node_band
node_entry -.->|"sets up run"| node_manager
node_manager -->|"sets up operators"| node_tensorops
node_entry -->|"starts propagation"| node_propagator
node_propagator -->|"uses preconditioner"| node_multigrid
node_propagator -->|"records steps"| node_monitor
node_monitor -.->|"evaluates expectations"| node_quadobs
node_monitor -->|"samples flux"| node_tsurff
node_propagator -->|"writes restart state"| node_checkpoint
node_monitor -->|"writes observables"| node_hdf5
node_checkpoint -->|"stores checkpoints"| node_hdf5
node_tsurff -->|"writes spectra"| node_hdf5
node_core -->|"solves eigenproblem"| node_slepc
node_assembly -->|"uses B-splines"| node_petiga
node_propagator -->|"uses parallel solvers"| node_petsc
node_diagnostics -.->|"writes results"| node_hdf5
node_dipoles -.->|"reads results"| node_hdf5
node_spectrum -.->|"reads results"| node_hdf5
node_recombination -.->|"reads results"| node_hdf5

click node_parser "https://github.com/dahbiz/tdsez/blob/main/src/parser.cpp"
click node_validation "https://github.com/dahbiz/tdsez/blob/main/src/parser_validation.cpp"
click node_entry "https://github.com/dahbiz/tdsez/blob/main/src/tdsez.cpp"
click node_knots "https://github.com/dahbiz/tdsez/blob/main/src/core_knots.cpp"
click node_core "https://github.com/dahbiz/tdsez/blob/main/src/core.cpp"
click node_assembly "https://github.com/dahbiz/tdsez/blob/main/src/assembly/assembly.cpp"
click node_sumfact "https://github.com/dahbiz/tdsez/blob/main/src/assembly/sumfact.cpp"
click node_band "https://github.com/dahbiz/tdsez/blob/main/src/assembly/band.cpp"
click node_manager "https://github.com/dahbiz/tdsez/blob/main/src/manager.cpp"
click node_tensorops "https://github.com/dahbiz/tdsez/blob/main/src/tensorops.cpp"
click node_propagator "https://github.com/dahbiz/tdsez/blob/main/src/propagator.cpp"
click node_multigrid "https://github.com/dahbiz/tdsez/blob/main/src/multigrid.cpp"
click node_monitor "https://github.com/dahbiz/tdsez/blob/main/src/monitor.cpp"
click node_quadobs "https://github.com/dahbiz/tdsez/blob/main/src/quadobs.cpp"
click node_checkpoint "https://github.com/dahbiz/tdsez/blob/main/src/checkpoint.cpp"
click node_tsurff "https://github.com/dahbiz/tdsez/blob/main/src/tsurff.cpp"
click node_diagnostics "https://github.com/dahbiz/tdsez/blob/main/src/diagnostics.cpp"
click node_dipoles "https://github.com/dahbiz/tdsez/blob/main/src/dipoles.cpp"
click node_spectrum "https://github.com/dahbiz/tdsez/blob/main/src/dipole_spectrum.cpp"
click node_recombination "https://github.com/dahbiz/tdsez/blob/main/src/recombination.cpp"

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_input,node_parser,node_validation,node_entry,node_user toneBlue
class node_knots,node_core,node_assembly,node_sumfact,node_band,node_manager,node_tensorops toneAmber
class node_propagator,node_multigrid,node_monitor,node_quadobs,node_checkpoint,node_tsurff toneMint
class node_hdf5,node_diagnostics,node_dipoles,node_spectrum,node_recombination toneRose
class node_petsc,node_slepc,node_petiga toneIndigo
```

## Components

### Input and Setup

- **Input Deck**
- [Input Parsing](https://github.com/dahbiz/tdsez/blob/main/src/parser.cpp): `src/parser.cpp`
- [Input Validation](https://github.com/dahbiz/tdsez/blob/main/src/parser_validation.cpp): `src/parser_validation.cpp`
- [Solver Entry](https://github.com/dahbiz/tdsez/blob/main/src/tdsez.cpp): `src/tdsez.cpp`

### Physics and Solvers

- [Knot Sequences](https://github.com/dahbiz/tdsez/blob/main/src/core_knots.cpp): `src/core_knots.cpp`
- [B-Spline Core](https://github.com/dahbiz/tdsez/blob/main/src/core.cpp): `src/core.cpp`
- [Operator Assembly](https://github.com/dahbiz/tdsez/blob/main/src/assembly/assembly.cpp): `src/assembly/assembly.cpp`
- [Sum-Factored Kernels](https://github.com/dahbiz/tdsez/blob/main/src/assembly/sumfact.cpp): `src/assembly/sumfact.cpp`
- [Banded Insertion](https://github.com/dahbiz/tdsez/blob/main/src/assembly/band.cpp): `src/assembly/band.cpp`
- [Operator Manager](https://github.com/dahbiz/tdsez/blob/main/src/manager.cpp): `src/manager.cpp`
- [Tensor Operators](https://github.com/dahbiz/tdsez/blob/main/src/tensorops.cpp): `src/tensorops.cpp`

### Propagation and Observables

- [Time Propagators](https://github.com/dahbiz/tdsez/blob/main/src/propagator.cpp): `src/propagator.cpp`
- [B-Spline Multigrid](https://github.com/dahbiz/tdsez/blob/main/src/multigrid.cpp): `src/multigrid.cpp`
- [Observable Monitor](https://github.com/dahbiz/tdsez/blob/main/src/monitor.cpp): `src/monitor.cpp`
- [Quadrature Observables](https://github.com/dahbiz/tdsez/blob/main/src/quadobs.cpp): `src/quadobs.cpp`
- [Checkpoint Restart](https://github.com/dahbiz/tdsez/blob/main/src/checkpoint.cpp): `src/checkpoint.cpp`
- [t-SURFF Spectra](https://github.com/dahbiz/tdsez/blob/main/src/tsurff.cpp): `src/tsurff.cpp`

### Results and Analysis

- **HDF5 Results**
- [Diagnostics](https://github.com/dahbiz/tdsez/blob/main/src/diagnostics.cpp): `src/diagnostics.cpp`
- [Dipole Analysis](https://github.com/dahbiz/tdsez/blob/main/src/dipoles.cpp): `src/dipoles.cpp`
- [Dipole Spectrum](https://github.com/dahbiz/tdsez/blob/main/src/dipole_spectrum.cpp): `src/dipole_spectrum.cpp`
- [Recombination Analysis](https://github.com/dahbiz/tdsez/blob/main/src/recombination.cpp): `src/recombination.cpp`

### Other components

- **User**
- **PETSc / MPI**
- **SLEPc**
- **PetIGA**

## Connections

- User → Input Deck: configures
- Input Deck → Solver Entry: starts run
- Solver Entry → Input Parsing: reads input
- Input Parsing → Input Validation: validates
- Solver Entry → B-Spline Core: builds solver
- B-Spline Core → Knot Sequences: uses knots
- B-Spline Core → Operator Assembly: assembles operators
- Operator Assembly → Sum-Factored Kernels: uses kernels (evidence: `src/assembly/assembly.cpp`)
- Operator Assembly → Banded Insertion: inserts matrices (evidence: `src/assembly/assembly.cpp`)
- Solver Entry → Operator Manager: sets up run
- Operator Manager → Tensor Operators: sets up operators (evidence: `src/manager.cpp`)
- Solver Entry → Time Propagators: starts propagation
- Time Propagators → B-Spline Multigrid: uses preconditioner (evidence: `src/propagator.cpp`)
- Time Propagators → Observable Monitor: records steps
- Observable Monitor → Quadrature Observables: evaluates expectations
- Observable Monitor → t-SURFF Spectra: samples flux (evidence: `src/monitor.cpp`)
- Time Propagators → Checkpoint Restart: writes restart state (evidence: `src/propagator.cpp`)
- Observable Monitor → HDF5 Results: writes observables
- Checkpoint Restart → HDF5 Results: stores checkpoints
- t-SURFF Spectra → HDF5 Results: writes spectra
- B-Spline Core → SLEPc: solves eigenproblem
- Operator Assembly → PetIGA: uses B-splines
- Time Propagators → PETSc / MPI: uses parallel solvers
- Diagnostics → HDF5 Results: writes results
- Dipole Analysis → HDF5 Results: reads results
- Dipole Spectrum → HDF5 Results: reads results
- Recombination Analysis → HDF5 Results: reads results