# ioniels/rf-track_uh_thermionicrfgun architecture

> Architecture diagram of the GitHub repository ioniels/rf-track_uh_thermionicrfgun, 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/ioniels/rf-track_uh_thermionicrfgun
- Repository: https://github.com/ioniels/rf-track_uh_thermionicrfgun

## Overview

This repository models a University of Hawai‘i thermionic RF gun: it qualifies XFdtd-derived RF fields, emits electrons from a LaB6 cathode, tracks them through the gun, and produces exit-beam data plus cathode-return heating results. The main run path is documented in the README; a separate back-bombardment study orchestrates event analysis, deposition, and thermal solving. The graph also shows field-map reduction and qualification, emission iteration, diagnostics, and COMSOL interchange. Some links are documented capabilities rather than inspected call sites; unsampled implementation details are not inferred.

Main entry points: [`rf_gun/simulation.py`](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/simulation.py) (Run orchestration), [`rf_gun/studies/back_bombardment_macropulse.py`](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/studies/back_bombardment_macropulse.py) (Macropulse study), [`run_thermionic_tm010.py`](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/run_thermionic_tm010.py) (Gun run CLI), [`rf_gun/fieldmaps/artifact.py`](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/artifact.py) (Field artifact)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fields["Field Maps"]
  node_map_reader["XFdtd reader<br/>[xfdtd_h5.py]"]
  node_map_reduction["Map reduction<br/>[pipeline.py]"]
  node_map_workflow["Map qualification<br/>[workflow.py]"]
  node_field_artifact[("Field artifact<br/>[artifact.py]")]
  node_field_models["Field models<br/>[models.py]"]
end

subgraph group_gun["Gun Simulation"]
  node_run_cli["Gun run CLI"]
  node_emission["Thermionic emission<br/>[emission_models.py]"]
  node_emission_sampling["Source sampling"]
  node_emission_iteration["Emission iteration"]
  node_cathode_fields["Cathode fields<br/>[cathode_fields.py]"]
  node_rf_transport["RF-Track transport<br/>[rftrack_volume.py]"]
  node_simulation["Run orchestration<br/>[simulation.py]"]
end

subgraph group_bombardment["Return Heating"]
  node_geometry["Cathode geometry"]
  node_events["Return events"]
  node_deposition["Energy deposition"]
  node_macropulse_study["Macropulse study"]
  node_thermal["Thermal solver<br/>[thermal.py]"]
end

subgraph group_materials["Material Models"]
  node_material_registry["Material registry<br/>[registry.py]"]
  node_material_data["Material properties<br/>[base.py]"]
end

subgraph group_outputs["Results"]
  node_comsol["COMSOL exchange<br/>[comsol_io.py]"]
  node_run_io["Run data I/O<br/>[io.py]"]
  node_diagnostics["Beam diagnostics<br/>[diagnostics.py]"]
  node_plotting["Plots and reports<br/>[save_run.py]"]
end

node_xfdtd[("XFdtd volume")]
node_operator(("Run operator"))
node_beamline(("Downstream beamline"))

node_xfdtd -->|"supplies volume"| node_map_reader
node_map_reader -->|"reads slabs"| node_map_reduction
node_map_reduction -.->|"checks quality"| node_map_workflow
node_map_reduction -->|"writes artifact"| node_field_artifact
node_map_workflow -->|"qualifies map"| node_field_artifact
node_field_artifact -->|"stores fields"| node_field_models
node_operator -->|"starts run"| node_run_cli
node_field_artifact -->|"loads qualified map"| node_simulation
node_run_cli -->|"runs pipeline"| node_simulation
node_simulation -->|"evaluates emission"| node_emission
node_simulation -->|"samples source"| node_emission_sampling
node_simulation -->|"optionally iterates"| node_emission_iteration
node_simulation -->|"uses cathode fields"| node_cathode_fields
node_simulation -->|"builds transport"| node_rf_transport
node_rf_transport -.->|"saves beam data"| node_run_io
node_rf_transport -->|"provides losses"| node_events
node_events -->|"classifies impacts"| node_geometry
node_run_cli -->|"records diagnostics"| node_diagnostics
node_run_io -->|"feeds run plots"| node_plotting
node_operator -->|"starts study"| node_macropulse_study
node_macropulse_study -->|"analyzes returns"| node_events
node_macropulse_study -->|"computes deposition"| node_deposition
node_macropulse_study -->|"solves heating"| node_thermal
node_macropulse_study -->|"loads material"| node_material_registry
node_deposition -->|"uses properties"| node_material_data
node_thermal -->|"uses thermal data"| node_material_registry
node_material_registry -->|"resolves properties"| node_material_data
node_macropulse_study -->|"compares thermal results"| node_comsol
node_comsol -->|"exchanges heat data"| node_operator
node_run_cli -->|"exports exit beam"| node_beamline

click node_map_reader "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/xfdtd_h5.py"
click node_map_reduction "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/pipeline.py"
click node_map_workflow "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/workflow.py"
click node_field_artifact "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/artifact.py"
click node_field_models "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/models.py"
click node_run_cli "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/run_thermionic_tm010.py"
click node_emission "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/emission_models.py"
click node_emission_sampling "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/emission_sampling.py"
click node_emission_iteration "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/emission_iteration.py"
click node_cathode_fields "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/cathode_fields.py"
click node_rf_transport "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/rftrack_volume.py"
click node_simulation "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/simulation.py"
click node_geometry "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/cathode_geometry.py"
click node_events "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/back_bombardment_events.py"
click node_deposition "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/back_bombardment_deposition.py"
click node_macropulse_study "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/studies/back_bombardment_macropulse.py"
click node_thermal "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/thermal.py"
click node_material_registry "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/materials/registry.py"
click node_material_data "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/materials/base.py"
click node_comsol "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/comsol_io.py"
click node_run_io "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/io.py"
click node_diagnostics "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/diagnostics.py"
click node_plotting "https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/plotting/save_run.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_map_reader,node_map_reduction,node_map_workflow,node_field_artifact,node_field_models toneBlue
class node_run_cli,node_emission,node_emission_sampling,node_emission_iteration,node_cathode_fields,node_rf_transport,node_simulation,node_xfdtd toneAmber
class node_geometry,node_events,node_deposition,node_macropulse_study,node_thermal toneMint
class node_material_registry,node_material_data toneRose
class node_comsol,node_run_io,node_diagnostics,node_plotting,node_operator,node_beamline toneIndigo
```

## Components

### Field Maps

- [XFdtd reader](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/xfdtd_h5.py): `rf_gun/fieldmaps/xfdtd_h5.py`
- [Map reduction](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/pipeline.py): `rf_gun/fieldmaps/pipeline.py`
- [Map qualification](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/workflow.py): `rf_gun/fieldmaps/workflow.py`
- [Field artifact](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/artifact.py): `rf_gun/fieldmaps/artifact.py`
- [Field models](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/fieldmaps/models.py): `rf_gun/fieldmaps/models.py`

### Gun Simulation

- [Gun run CLI](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/run_thermionic_tm010.py): `run_thermionic_tm010.py`
- [Thermionic emission](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/emission_models.py): `rf_gun/emission_models.py`
- [Source sampling](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/emission_sampling.py): `rf_gun/emission_sampling.py`
- [Emission iteration](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/emission_iteration.py): `rf_gun/emission_iteration.py`
- [Cathode fields](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/cathode_fields.py): `rf_gun/cathode_fields.py`
- [RF-Track transport](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/rftrack_volume.py): `rf_gun/rftrack_volume.py`
- [Run orchestration](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/simulation.py): `rf_gun/simulation.py`

### Return Heating

- [Cathode geometry](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/cathode_geometry.py): `rf_gun/cathode_geometry.py`
- [Return events](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/back_bombardment_events.py): `rf_gun/back_bombardment_events.py`
- [Energy deposition](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/back_bombardment_deposition.py): `rf_gun/back_bombardment_deposition.py`
- [Macropulse study](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/studies/back_bombardment_macropulse.py): `rf_gun/studies/back_bombardment_macropulse.py`
- [Thermal solver](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/thermal.py): `rf_gun/thermal.py`

### Material Models

- [Material registry](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/materials/registry.py): `rf_gun/materials/registry.py`
- [Material properties](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/materials/base.py): `rf_gun/materials/base.py`

### Results

- [COMSOL exchange](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/comsol_io.py): `rf_gun/comsol_io.py`
- [Run data I/O](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/io.py): `rf_gun/io.py`
- [Beam diagnostics](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/diagnostics.py): `rf_gun/diagnostics.py`
- [Plots and reports](https://github.com/ioniels/rf-track_uh_thermionicrfgun/blob/main/rf_gun/plotting/save_run.py): `rf_gun/plotting/save_run.py`

### Other components

- **XFdtd volume**
- **Run operator**
- **Downstream beamline**

## Connections

- XFdtd volume → XFdtd reader: supplies volume
- XFdtd reader → Map reduction: reads slabs (evidence: `rf_gun/fieldmaps/pipeline.py`)
- Map reduction → Map qualification: checks quality
- Map reduction → Field artifact: writes artifact (evidence: `rf_gun/fieldmaps/pipeline.py`)
- Map qualification → Field artifact: qualifies map
- Field artifact → Field models: stores fields (evidence: `rf_gun/fieldmaps/artifact.py`)
- Run operator → Gun run CLI: starts run
- Field artifact → Run orchestration: loads qualified map
- Gun run CLI → Run orchestration: runs pipeline
- Run orchestration → Thermionic emission: evaluates emission (evidence: `rf_gun/simulation.py`)
- Run orchestration → Source sampling: samples source (evidence: `rf_gun/simulation.py`)
- Run orchestration → Emission iteration: optionally iterates (evidence: `rf_gun/simulation.py`)
- Run orchestration → Cathode fields: uses cathode fields (evidence: `rf_gun/simulation.py`)
- Run orchestration → RF-Track transport: builds transport (evidence: `rf_gun/simulation.py`)
- RF-Track transport → Run data I/O: saves beam data
- RF-Track transport → Return events: provides losses (evidence: `rf_gun/back_bombardment_events.py`)
- Return events → Cathode geometry: classifies impacts (evidence: `rf_gun/back_bombardment_events.py`)
- Gun run CLI → Beam diagnostics: records diagnostics
- Run data I/O → Plots and reports: feeds run plots (evidence: `rf_gun/plotting/save_run.py`)
- Run operator → Macropulse study: starts study
- Macropulse study → Return events: analyzes returns (evidence: `rf_gun/studies/back_bombardment_macropulse.py`)
- Macropulse study → Energy deposition: computes deposition (evidence: `rf_gun/studies/back_bombardment_macropulse.py`)
- Macropulse study → Thermal solver: solves heating (evidence: `rf_gun/studies/back_bombardment_macropulse.py`)
- Macropulse study → Material registry: loads material (evidence: `rf_gun/studies/back_bombardment_macropulse.py`)
- Energy deposition → Material properties: uses properties (evidence: `rf_gun/back_bombardment_deposition.py`)
- Thermal solver → Material registry: uses thermal data (evidence: `rf_gun/thermal.py`)
- Material registry → Material properties: resolves properties (evidence: `rf_gun/materials/registry.py`)
- Macropulse study → COMSOL exchange: compares thermal results (evidence: `rf_gun/studies/back_bombardment_macropulse.py`)
- COMSOL exchange → Run operator: exchanges heat data
- Gun run CLI → Downstream beamline: exports exit beam
