# lanl/branson architecture

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

- Interactive diagram: https://gitdiagram.com/lanl/branson
- Repository: https://github.com/lanl/branson

## Overview

Branson is a parallel Monte Carlo radiation-transport application. Users provide XML problem and performance parameters; the executable parses them, constructs and initializes a mesh, selects a transport mode, and advances particle histories/events while tracking tallies and simulation state. The README documents both replicated and domain-decomposed operation, plus particle-passing and event-based transport. Source excerpts are partial, so links to less-sampled capabilities rely on explicit README statements or SOURCE INDEX references; uncertain implementation details are omitted.

Main entry points: [`src/main.cc`](https://github.com/lanl/branson/blob/develop/src/main.cc) (Simulation entry), [`src/event_based_transport.h`](https://github.com/lanl/branson/blob/develop/src/event_based_transport.h) (Event transport), [`src/mesh.h`](https://github.com/lanl/branson/blob/develop/src/mesh.h) (Mesh setup), [`src/history_based_transport.h`](https://github.com/lanl/branson/blob/develop/src/history_based_transport.h) (History transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration and mesh"]
  node_main["Simulation entry<br/>[main.cc]"]
  node_input["Input parser<br/>[input.h]"]
  node_mesh["Mesh setup<br/>[mesh.h]"]
  node_proto["Mesh topology<br/>[proto_mesh.h]"]
  node_decompose["Mesh decomposition<br/>[decompose_mesh.h]"]
end

subgraph group_simulation["Transport simulation"]
  node_history["History transport"]
  node_event["Event transport"]
end

subgraph group_parallel["Parallel execution"]
  node_passdriver["Particle-pass driver"]
  node_passtpt["Particle-pass transport"]
  node_repdriver["Replicated driver"]
  node_reptransport["Replicated transport"]
  node_mpi["MPI datatypes<br/>[mpi_types.h]"]
end

subgraph group_physics["Physics and state"]
  node_photons["Photon state<br/>[photon.h]"]
  node_photonarray["Photon arrays<br/>[photon_array.h]"]
  node_source["Particle sources<br/>[source.h]"]
  node_sampling["Sampling and scattering"]
  node_rng["Counter RNG<br/>[RNG.h]"]
  node_state["IMC state<br/>[imc_state.h]"]
  node_tally["Cell tallies<br/>[cell_tally.h]"]
  node_output["Silo output<br/>[write_silo.h]"]
end

node_user(("Problem author"))
node_xml["XML input"]
node_silo[("Silo/HDF5")]

node_user -->|"defines problem"| node_xml
node_xml -->|"configures"| node_input
node_main -->|"reads"| node_input
node_main -->|"constructs"| node_mesh
node_mesh -->|"uses topology"| node_proto
node_mesh -->|"decomposes"| node_decompose
node_main -->|"dispatches"| node_passdriver
node_passdriver -.->|"runs transport"| node_passtpt
node_main -->|"selects replicated"| node_repdriver
node_repdriver -.->|"runs transport"| node_reptransport
node_main -.->|"selects event mode"| node_event
node_main -.->|"selects history mode"| node_history
node_history -->|"updates particles"| node_photons
node_event -->|"transports particles"| node_photons
node_event -->|"supports arrays"| node_photonarray
node_history -->|"accumulates tallies"| node_tally
node_event -->|"updates tallies"| node_tally
node_sampling -->|"draws random values"| node_rng
node_history -->|"uses sampling"| node_sampling
node_event -->|"uses sampling"| node_sampling
node_main -->|"passes state"| node_state
node_mesh -->|"uses MPI types"| node_mpi
node_user -->|"runs executable"| node_main
node_output -.->|"writes results"| node_silo

click node_main "https://github.com/lanl/branson/blob/develop/src/main.cc"
click node_input "https://github.com/lanl/branson/blob/develop/src/input.h"
click node_mesh "https://github.com/lanl/branson/blob/develop/src/mesh.h"
click node_proto "https://github.com/lanl/branson/blob/develop/src/proto_mesh.h"
click node_decompose "https://github.com/lanl/branson/blob/develop/src/decompose_mesh.h"
click node_history "https://github.com/lanl/branson/blob/develop/src/history_based_transport.h"
click node_event "https://github.com/lanl/branson/blob/develop/src/event_based_transport.h"
click node_passdriver "https://github.com/lanl/branson/blob/develop/src/particle_pass_driver.h"
click node_passtpt "https://github.com/lanl/branson/blob/develop/src/particle_pass_transport.h"
click node_repdriver "https://github.com/lanl/branson/blob/develop/src/replicated_driver.h"
click node_reptransport "https://github.com/lanl/branson/blob/develop/src/replicated_transport.h"
click node_mpi "https://github.com/lanl/branson/blob/develop/src/mpi_types.h"
click node_photons "https://github.com/lanl/branson/blob/develop/src/photon.h"
click node_photonarray "https://github.com/lanl/branson/blob/develop/src/photon_array.h"
click node_source "https://github.com/lanl/branson/blob/develop/src/source.h"
click node_sampling "https://github.com/lanl/branson/blob/develop/src/sampling_functions.h"
click node_rng "https://github.com/lanl/branson/blob/develop/src/RNG.h"
click node_state "https://github.com/lanl/branson/blob/develop/src/imc_state.h"
click node_tally "https://github.com/lanl/branson/blob/develop/src/cell_tally.h"
click node_output "https://github.com/lanl/branson/blob/develop/src/write_silo.h"

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_main,node_input,node_mesh,node_proto,node_decompose toneBlue
class node_history,node_event,node_silo toneAmber
class node_passdriver,node_passtpt,node_repdriver,node_reptransport,node_mpi toneMint
class node_photons,node_photonarray,node_source,node_sampling,node_rng,node_state,node_tally,node_output toneRose
class node_user,node_xml toneIndigo
```

## Components

### Configuration and mesh

- [Simulation entry](https://github.com/lanl/branson/blob/develop/src/main.cc): `src/main.cc`
- [Input parser](https://github.com/lanl/branson/blob/develop/src/input.h): `src/input.h`
- [Mesh setup](https://github.com/lanl/branson/blob/develop/src/mesh.h): `src/mesh.h`
- [Mesh topology](https://github.com/lanl/branson/blob/develop/src/proto_mesh.h): `src/proto_mesh.h`
- [Mesh decomposition](https://github.com/lanl/branson/blob/develop/src/decompose_mesh.h): `src/decompose_mesh.h`

### Transport simulation

- [History transport](https://github.com/lanl/branson/blob/develop/src/history_based_transport.h): `src/history_based_transport.h`
- [Event transport](https://github.com/lanl/branson/blob/develop/src/event_based_transport.h): `src/event_based_transport.h`

### Parallel execution

- [Particle-pass driver](https://github.com/lanl/branson/blob/develop/src/particle_pass_driver.h): `src/particle_pass_driver.h`
- [Particle-pass transport](https://github.com/lanl/branson/blob/develop/src/particle_pass_transport.h): `src/particle_pass_transport.h`
- [Replicated driver](https://github.com/lanl/branson/blob/develop/src/replicated_driver.h): `src/replicated_driver.h`
- [Replicated transport](https://github.com/lanl/branson/blob/develop/src/replicated_transport.h): `src/replicated_transport.h`
- [MPI datatypes](https://github.com/lanl/branson/blob/develop/src/mpi_types.h): `src/mpi_types.h`

### Physics and state

- [Photon state](https://github.com/lanl/branson/blob/develop/src/photon.h): `src/photon.h`
- [Photon arrays](https://github.com/lanl/branson/blob/develop/src/photon_array.h): `src/photon_array.h`
- [Particle sources](https://github.com/lanl/branson/blob/develop/src/source.h): `src/source.h`
- [Sampling and scattering](https://github.com/lanl/branson/blob/develop/src/sampling_functions.h): `src/sampling_functions.h`
- [Counter RNG](https://github.com/lanl/branson/blob/develop/src/RNG.h): `src/RNG.h`
- [IMC state](https://github.com/lanl/branson/blob/develop/src/imc_state.h): `src/imc_state.h`
- [Cell tallies](https://github.com/lanl/branson/blob/develop/src/cell_tally.h): `src/cell_tally.h`
- [Silo output](https://github.com/lanl/branson/blob/develop/src/write_silo.h): `src/write_silo.h`

### Other components

- **Problem author**
- **XML input**
- **Silo/HDF5**

## Connections

- Problem author → XML input: defines problem
- XML input → Input parser: configures (evidence: `src/input.h`)
- Simulation entry → Input parser: reads (evidence: `src/main.cc`)
- Simulation entry → Mesh setup: constructs (evidence: `src/main.cc`)
- Mesh setup → Mesh topology: uses topology (evidence: `src/mesh.h`)
- Mesh setup → Mesh decomposition: decomposes (evidence: `src/mesh.h`)
- Simulation entry → Particle-pass driver: dispatches (evidence: `src/main.cc`)
- Particle-pass driver → Particle-pass transport: runs transport
- Simulation entry → Replicated driver: selects replicated (evidence: `src/main.cc`)
- Replicated driver → Replicated transport: runs transport
- Simulation entry → Event transport: selects event mode
- Simulation entry → History transport: selects history mode
- History transport → Photon state: updates particles (evidence: `src/history_based_transport.h`)
- Event transport → Photon state: transports particles (evidence: `src/event_based_transport.h`)
- Event transport → Photon arrays: supports arrays (evidence: `src/event_based_transport.h`)
- History transport → Cell tallies: accumulates tallies (evidence: `src/history_based_transport.h`)
- Event transport → Cell tallies: updates tallies (evidence: `src/event_based_transport.h`)
- Sampling and scattering → Counter RNG: draws random values (evidence: `src/sampling_functions.h`)
- History transport → Sampling and scattering: uses sampling (evidence: `src/history_based_transport.h`)
- Event transport → Sampling and scattering: uses sampling (evidence: `src/event_based_transport.h`)
- Simulation entry → IMC state: passes state (evidence: `src/main.cc`)
- Mesh setup → MPI datatypes: uses MPI types (evidence: `src/mesh.h`)
- Problem author → Simulation entry: runs executable
- Silo output → Silo/HDF5: writes results
