# courtsb/mongoose architecture

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

## Overview

MONGOOSE is an adaptive reduced-order Monte Carlo fission-operator workflow driven by CLI commands and a persistent case workspace. Its main run prepares and executes OpenMC pilot and modal calculations, extracts responses, builds and solves a reduced operator, then uses residuals and importance to refine the basis and allocate further histories. Separate branches support pin-local OpenMC models and bank-informed source phase-space libraries. The controller’s imports and README document the main orchestration; unsampled implementations limit finer-grained claims about internal calls.

Main entry points: [`src/mongoose/workflow/controller.py`](https://github.com/courtsb/mongoose/blob/main/src/mongoose/workflow/controller.py) (Workflow controller), [`src/mongoose/cli.py`](https://github.com/courtsb/mongoose/blob/main/src/mongoose/cli.py) (CLI), [`src/mongoose/operator/assembly.py`](https://github.com/courtsb/mongoose/blob/main/src/mongoose/operator/assembly.py) (Operator assembly), [`src/mongoose/responses/extractor.py`](https://github.com/courtsb/mongoose/blob/main/src/mongoose/responses/extractor.py) (Response extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_case["Case setup"]
  node_config["Configuration<br/>[loader.py]"]
  node_caseindex[("Case index<br/>[index.py]")]
  node_workspace[("Workspace<br/>[workspace.py]")]
end

subgraph group_transport["OpenMC transport"]
  node_pilot["Pilot transport<br/>[pilot.py]"]
  node_prepare["Task preparation<br/>[prepare.py]"]
  node_runner["OpenMC runner<br/>[runner.py]"]
  node_persistent["Persistent workers<br/>[persistent.py]"]
  node_scheduler["Task scheduler<br/>[scheduler.py]"]
  node_pinlocal["Pin-local adapter<br/>[pin_local.py]"]
  node_statepoint["Statepoint reader<br/>[statepoint.py]"]
end

subgraph group_reduction["Adaptive reduction"]
  node_extract["Response extraction<br/>[extractor.py]"]
  node_library[("Response library<br/>[library.py]")]
  node_basis["Basis and enrichment<br/>[enrichment.py]"]
  node_assembly["Operator assembly<br/>[assembly.py]"]
  node_solver["Eigen solver<br/>[eigen.py]"]
  node_allocation["History allocation<br/>[allocation.py]"]
end

subgraph group_sources["Source libraries"]
  node_sourceflow["Source workflow<br/>[workflow.py]"]
  node_phasespace[("Phase-space library<br/>[phase_space.py]")]
  node_spectrum["Source spectrum<br/>[spectrum.py]"]
end

subgraph group_operations["Workflow operations"]
  node_cli["CLI<br/>[cli.py]"]
  node_preflight["Preflight checks<br/>[preflight.py]"]
  node_controller["Workflow controller<br/>[controller.py]"]
end

node_user(("User"))
node_openmc["OpenMC"]

node_user -->|"invokes"| node_cli
node_cli -->|"loads"| node_config
node_cli -.->|"dispatches"| node_controller
node_cli -.->|"runs checks"| node_preflight
node_controller -->|"uses"| node_caseindex
node_controller -.->|"uses"| node_workspace
node_controller -->|"runs"| node_pilot
node_controller -->|"prepares tasks"| node_prepare
node_controller -->|"runs tasks"| node_runner
node_controller -->|"runs tasks"| node_persistent
node_controller -->|"schedules"| node_scheduler
node_controller -->|"refines"| node_basis
node_controller -->|"extracts responses"| node_extract
node_controller -.->|"assembles"| node_assembly
node_controller -.->|"solves"| node_solver
node_controller -.->|"allocates histories"| node_allocation
node_controller -->|"uses"| node_sourceflow
node_controller -->|"uses"| node_phasespace
node_prepare -->|"adapts model"| node_pinlocal
node_extract -->|"reads tally"| node_statepoint
node_extract -->|"stores responses"| node_library
node_assembly -->|"reads responses"| node_library
node_assembly -->|"uses modes"| node_basis
node_solver -.->|"reads operator"| node_assembly
node_basis -.->|"supports solve"| node_solver
node_sourceflow -.->|"uses library"| node_phasespace
node_sourceflow -.->|"uses spectrum"| node_spectrum
node_pilot -->|"launches"| node_runner
node_runner -.->|"runs transport"| node_openmc
node_persistent -.->|"runs transport"| node_openmc
node_preflight -->|"validates indexing"| node_caseindex
node_preflight -->|"checks pilot"| node_pilot

click node_cli "https://github.com/courtsb/mongoose/blob/main/src/mongoose/cli.py"
click node_config "https://github.com/courtsb/mongoose/blob/main/src/mongoose/config/loader.py"
click node_caseindex "https://github.com/courtsb/mongoose/blob/main/src/mongoose/case/index.py"
click node_workspace "https://github.com/courtsb/mongoose/blob/main/src/mongoose/case/workspace.py"
click node_preflight "https://github.com/courtsb/mongoose/blob/main/src/mongoose/validation/preflight.py"
click node_controller "https://github.com/courtsb/mongoose/blob/main/src/mongoose/workflow/controller.py"
click node_pilot "https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/pilot.py"
click node_prepare "https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/prepare.py"
click node_runner "https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/runner.py"
click node_persistent "https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/persistent.py"
click node_scheduler "https://github.com/courtsb/mongoose/blob/main/src/mongoose/execution/scheduler.py"
click node_pinlocal "https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/pin_local.py"
click node_statepoint "https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/statepoint.py"
click node_extract "https://github.com/courtsb/mongoose/blob/main/src/mongoose/responses/extractor.py"
click node_library "https://github.com/courtsb/mongoose/blob/main/src/mongoose/responses/library.py"
click node_basis "https://github.com/courtsb/mongoose/blob/main/src/mongoose/basis/enrichment.py"
click node_assembly "https://github.com/courtsb/mongoose/blob/main/src/mongoose/operator/assembly.py"
click node_solver "https://github.com/courtsb/mongoose/blob/main/src/mongoose/solve/eigen.py"
click node_allocation "https://github.com/courtsb/mongoose/blob/main/src/mongoose/importance/allocation.py"
click node_sourceflow "https://github.com/courtsb/mongoose/blob/main/src/mongoose/source/workflow.py"
click node_phasespace "https://github.com/courtsb/mongoose/blob/main/src/mongoose/source/phase_space.py"
click node_spectrum "https://github.com/courtsb/mongoose/blob/main/src/mongoose/source/spectrum.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_caseindex,node_workspace,node_user toneBlue
class node_pilot,node_prepare,node_runner,node_persistent,node_scheduler,node_pinlocal,node_statepoint toneAmber
class node_extract,node_library,node_basis,node_assembly,node_solver,node_allocation toneMint
class node_sourceflow,node_phasespace,node_spectrum toneRose
class node_cli,node_preflight,node_controller,node_openmc toneIndigo
```

## Components

### Case setup

- [Configuration](https://github.com/courtsb/mongoose/blob/main/src/mongoose/config/loader.py): `src/mongoose/config/loader.py`
- [Case index](https://github.com/courtsb/mongoose/blob/main/src/mongoose/case/index.py): `src/mongoose/case/index.py`
- [Workspace](https://github.com/courtsb/mongoose/blob/main/src/mongoose/case/workspace.py): `src/mongoose/case/workspace.py`

### OpenMC transport

- [Pilot transport](https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/pilot.py): `src/mongoose/adapters/openmc/pilot.py`
- [Task preparation](https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/prepare.py): `src/mongoose/adapters/openmc/prepare.py`
- [OpenMC runner](https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/runner.py): `src/mongoose/adapters/openmc/runner.py`
- [Persistent workers](https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/persistent.py): `src/mongoose/adapters/openmc/persistent.py`
- [Task scheduler](https://github.com/courtsb/mongoose/blob/main/src/mongoose/execution/scheduler.py): `src/mongoose/execution/scheduler.py`
- [Pin-local adapter](https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/pin_local.py): `src/mongoose/adapters/openmc/pin_local.py`
- [Statepoint reader](https://github.com/courtsb/mongoose/blob/main/src/mongoose/adapters/openmc/statepoint.py): `src/mongoose/adapters/openmc/statepoint.py`

### Adaptive reduction

- [Response extraction](https://github.com/courtsb/mongoose/blob/main/src/mongoose/responses/extractor.py): `src/mongoose/responses/extractor.py`
- [Response library](https://github.com/courtsb/mongoose/blob/main/src/mongoose/responses/library.py): `src/mongoose/responses/library.py`
- [Basis and enrichment](https://github.com/courtsb/mongoose/blob/main/src/mongoose/basis/enrichment.py): `src/mongoose/basis/enrichment.py`
- [Operator assembly](https://github.com/courtsb/mongoose/blob/main/src/mongoose/operator/assembly.py): `src/mongoose/operator/assembly.py`
- [Eigen solver](https://github.com/courtsb/mongoose/blob/main/src/mongoose/solve/eigen.py): `src/mongoose/solve/eigen.py`
- [History allocation](https://github.com/courtsb/mongoose/blob/main/src/mongoose/importance/allocation.py): `src/mongoose/importance/allocation.py`

### Source libraries

- [Source workflow](https://github.com/courtsb/mongoose/blob/main/src/mongoose/source/workflow.py): `src/mongoose/source/workflow.py`
- [Phase-space library](https://github.com/courtsb/mongoose/blob/main/src/mongoose/source/phase_space.py): `src/mongoose/source/phase_space.py`
- [Source spectrum](https://github.com/courtsb/mongoose/blob/main/src/mongoose/source/spectrum.py): `src/mongoose/source/spectrum.py`

### Workflow operations

- [CLI](https://github.com/courtsb/mongoose/blob/main/src/mongoose/cli.py): `src/mongoose/cli.py`
- [Preflight checks](https://github.com/courtsb/mongoose/blob/main/src/mongoose/validation/preflight.py): `src/mongoose/validation/preflight.py`
- [Workflow controller](https://github.com/courtsb/mongoose/blob/main/src/mongoose/workflow/controller.py): `src/mongoose/workflow/controller.py`

### Other components

- **User**
- **OpenMC**

## Connections

- User → CLI: invokes (evidence: `README.md`)
- CLI → Configuration: loads
- CLI → Workflow controller: dispatches
- CLI → Preflight checks: runs checks
- Workflow controller → Case index: uses (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Workspace: uses
- Workflow controller → Pilot transport: runs (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Task preparation: prepares tasks (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → OpenMC runner: runs tasks (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Persistent workers: runs tasks (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Task scheduler: schedules (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Basis and enrichment: refines (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Response extraction: extracts responses (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Operator assembly: assembles
- Workflow controller → Eigen solver: solves (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → History allocation: allocates histories
- Workflow controller → Source workflow: uses (evidence: `src/mongoose/workflow/controller.py`)
- Workflow controller → Phase-space library: uses (evidence: `src/mongoose/workflow/controller.py`)
- Task preparation → Pin-local adapter: adapts model (evidence: `src/mongoose/adapters/openmc/prepare.py`)
- Response extraction → Statepoint reader: reads tally (evidence: `src/mongoose/responses/extractor.py`)
- Response extraction → Response library: stores responses (evidence: `src/mongoose/responses/extractor.py`)
- Operator assembly → Response library: reads responses (evidence: `src/mongoose/operator/assembly.py`)
- Operator assembly → Basis and enrichment: uses modes (evidence: `src/mongoose/operator/assembly.py`)
- Eigen solver → Operator assembly: reads operator
- Basis and enrichment → Eigen solver: supports solve (evidence: `src/mongoose/basis/enrichment.py`)
- Source workflow → Phase-space library: uses library
- Source workflow → Source spectrum: uses spectrum
- Pilot transport → OpenMC runner: launches (evidence: `src/mongoose/adapters/openmc/pilot.py`)
- OpenMC runner → OpenMC: runs transport (evidence: `README.md`)
- Persistent workers → OpenMC: runs transport (evidence: `README.md`)
- Preflight checks → Case index: validates indexing (evidence: `src/mongoose/validation/preflight.py`)
- Preflight checks → Pilot transport: checks pilot (evidence: `src/mongoose/validation/preflight.py`)
