# mflowcode/mfc architecture

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

- Interactive diagram: https://gitdiagram.com/mflowcode/mfc
- Repository: https://github.com/mflowcode/mfc

## Overview

MFC is an exascale multiphysics flow solver with a Python toolchain for configuring, validating, building, running, and visualizing simulations. The main user workflow starts with a case file, validates its parameters, generates target inputs, builds and launches solver targets, then reads and visualizes results. The graph also preserves parameter metadata/code generation and interactive visualization as substantial capabilities. Solver physics are documented in the README, but solver implementation files are not present in the supplied tree; relationships for that layer are therefore documented rather than source-traced.

Main entry points: [`toolchain/mfc/run/run.py`](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/run.py) (Simulation runner), [`toolchain/mfc/viz/viz.py`](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/viz.py) (Visualization entry), [`toolchain/mfc/params/definitions.py`](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/definitions.py) (Parameter definitions), [`toolchain/mfc/run/input.py`](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/input.py) (Target input generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["Command dispatch<br/>[commands.py]"]
end

subgraph group_cases["Cases and parameters"]
  node_case["Case model<br/>[case.py]"]
  node_validation["Case validation<br/>[case_validator.py]"]
  node_param_definitions["Parameter definitions<br/>[definitions.py]"]
  node_param_schema["Parameter schema<br/>[schema.py]"]
  node_param_registry["Parameter registry<br/>[registry.py]"]
  node_param_analysis["Case AST analysis<br/>[ast_analyzer.py]"]
  node_param_docs["Parameter descriptions<br/>[descriptions.py]"]
  node_eos_families["EOS families<br/>[eos_families.py]"]
  node_fortran_gen["Fortran generation<br/>[fortran_gen.py]"]
  node_namelist["Namelist parsing<br/>[namelist_parser.py]"]
end

subgraph group_execution["Build and execution"]
  node_input["Target input generation<br/>[input.py]"]
  node_build["Solver build<br/>[build.py]"]
  node_solver["Flow solver<br/>[CMakeLists.txt]"]
  node_run["Simulation runner<br/>[run.py]"]
  node_queues["Batch queues<br/>[queues.py]"]
  node_archive["Run archive<br/>[archive.py]"]
  node_state["Toolchain configuration<br/>[state.py]"]
end

subgraph group_visualization["Results and visualization"]
  node_viz_entry["Visualization entry<br/>[viz.py]"]
  node_reader["Result readers<br/>[reader.py]"]
  node_silo_reader["Silo reader<br/>[silo_reader.py]"]
  node_renderer["Result renderer<br/>[renderer.py]"]
  node_interactive["Interactive viewer<br/>[interactive.py]"]
  node_step_cache[("Step cache<br/>[_step_cache.py]")]
  node_tui["Terminal viewer<br/>[tui.py]"]
end

node_user(("MFC user"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_run
node_cli -->|"dispatches"| node_build
node_user -->|"provides"| node_case
node_case -.->|"validates"| node_validation
node_param_definitions -->|"defines with"| node_param_schema
node_param_definitions -->|"registers"| node_param_registry
node_param_definitions -->|"uses descriptions"| node_param_docs
node_param_definitions -->|"uses families"| node_eos_families
node_param_analysis -.->|"analyzes"| node_param_definitions
node_fortran_gen -->|"generates from"| node_param_definitions
node_fortran_gen -->|"reads registry"| node_param_registry
node_fortran_gen -->|"dispatches EOS"| node_eos_families
node_namelist -->|"checks generated parameters"| node_fortran_gen
node_run -->|"loads case"| node_input
node_input -->|"validates parameters"| node_validation
node_input -->|"constructs"| node_case
node_input -->|"generates target inputs"| node_build
node_run -->|"builds targets"| node_build
node_run -->|"uses queues"| node_queues
node_run -->|"archives run"| node_archive
node_build -.->|"builds"| node_solver
node_run -.->|"launches targets"| node_solver
node_run -->|"reads configuration"| node_state
node_user -->|"opens results"| node_viz_entry
node_viz_entry -->|"reads results"| node_reader
node_viz_entry -->|"reads Silo"| node_silo_reader
node_viz_entry -->|"renders"| node_renderer
node_viz_entry -->|"opens viewer"| node_interactive
node_viz_entry -->|"opens terminal UI"| node_tui
node_interactive -->|"caches steps"| node_step_cache
node_tui -->|"caches steps"| node_step_cache

click node_cli "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/cli/commands.py"
click node_case "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/case.py"
click node_validation "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/case_validator.py"
click node_param_definitions "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/definitions.py"
click node_param_schema "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/schema.py"
click node_param_registry "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/registry.py"
click node_param_analysis "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/ast_analyzer.py"
click node_param_docs "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/descriptions.py"
click node_eos_families "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/eos_families.py"
click node_fortran_gen "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/generators/fortran_gen.py"
click node_namelist "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/namelist_parser.py"
click node_input "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/input.py"
click node_build "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/build.py"
click node_solver "https://github.com/mflowcode/mfc/blob/master/CMakeLists.txt"
click node_run "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/run.py"
click node_queues "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/queues.py"
click node_archive "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/archive.py"
click node_state "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/state.py"
click node_viz_entry "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/viz.py"
click node_reader "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/reader.py"
click node_silo_reader "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/silo_reader.py"
click node_renderer "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/renderer.py"
click node_interactive "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/interactive.py"
click node_step_cache "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/_step_cache.py"
click node_tui "https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/tui.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_cli,node_user toneBlue
class node_case,node_validation,node_param_definitions,node_param_schema,node_param_registry,node_param_analysis,node_param_docs,node_eos_families,node_fortran_gen,node_namelist toneAmber
class node_input,node_build,node_solver,node_run,node_queues,node_archive,node_state toneMint
class node_viz_entry,node_reader,node_silo_reader,node_renderer,node_interactive,node_step_cache,node_tui toneRose
```

## Components

### User entry

- [Command dispatch](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/cli/commands.py): `toolchain/mfc/cli/commands.py`

### Cases and parameters

- [Case model](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/case.py): `toolchain/mfc/case.py`
- [Case validation](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/case_validator.py): `toolchain/mfc/case_validator.py`
- [Parameter definitions](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/definitions.py): `toolchain/mfc/params/definitions.py`
- [Parameter schema](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/schema.py): `toolchain/mfc/params/schema.py`
- [Parameter registry](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/registry.py): `toolchain/mfc/params/registry.py`
- [Case AST analysis](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/ast_analyzer.py): `toolchain/mfc/params/ast_analyzer.py`
- [Parameter descriptions](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/descriptions.py): `toolchain/mfc/params/descriptions.py`
- [EOS families](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/eos_families.py): `toolchain/mfc/params/eos_families.py`
- [Fortran generation](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/generators/fortran_gen.py): `toolchain/mfc/params/generators/fortran_gen.py`
- [Namelist parsing](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/params/namelist_parser.py): `toolchain/mfc/params/namelist_parser.py`

### Build and execution

- [Target input generation](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/input.py): `toolchain/mfc/run/input.py`
- [Solver build](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/build.py): `toolchain/mfc/build.py`
- [Flow solver](https://github.com/mflowcode/mfc/blob/master/CMakeLists.txt): `CMakeLists.txt`
- [Simulation runner](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/run.py): `toolchain/mfc/run/run.py`
- [Batch queues](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/queues.py): `toolchain/mfc/run/queues.py`
- [Run archive](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/run/archive.py): `toolchain/mfc/run/archive.py`
- [Toolchain configuration](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/state.py): `toolchain/mfc/state.py`

### Results and visualization

- [Visualization entry](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/viz.py): `toolchain/mfc/viz/viz.py`
- [Result readers](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/reader.py): `toolchain/mfc/viz/reader.py`
- [Silo reader](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/silo_reader.py): `toolchain/mfc/viz/silo_reader.py`
- [Result renderer](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/renderer.py): `toolchain/mfc/viz/renderer.py`
- [Interactive viewer](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/interactive.py): `toolchain/mfc/viz/interactive.py`
- [Step cache](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/_step_cache.py): `toolchain/mfc/viz/_step_cache.py`
- [Terminal viewer](https://github.com/mflowcode/mfc/blob/master/toolchain/mfc/viz/tui.py): `toolchain/mfc/viz/tui.py`

### Other components

- **MFC user**

## Connections

- MFC user → Command dispatch: invokes
- Command dispatch → Simulation runner: dispatches (evidence: `toolchain/main.py`)
- Command dispatch → Solver build: dispatches (evidence: `toolchain/main.py`)
- MFC user → Case model: provides
- Case model → Case validation: validates
- Parameter definitions → Parameter schema: defines with (evidence: `toolchain/mfc/params/definitions.py`)
- Parameter definitions → Parameter registry: registers (evidence: `toolchain/mfc/params/definitions.py`)
- Parameter definitions → Parameter descriptions: uses descriptions (evidence: `toolchain/mfc/params/definitions.py`)
- Parameter definitions → EOS families: uses families (evidence: `toolchain/mfc/params/definitions.py`)
- Case AST analysis → Parameter definitions: analyzes
- Fortran generation → Parameter definitions: generates from (evidence: `toolchain/mfc/params/generators/fortran_gen.py`)
- Fortran generation → Parameter registry: reads registry (evidence: `toolchain/mfc/params/generators/fortran_gen.py`)
- Fortran generation → EOS families: dispatches EOS (evidence: `toolchain/mfc/params/generators/fortran_gen.py`)
- Namelist parsing → Fortran generation: checks generated parameters (evidence: `toolchain/mfc/params/namelist_parser.py`)
- Simulation runner → Target input generation: loads case (evidence: `toolchain/mfc/run/run.py`)
- Target input generation → Case validation: validates parameters (evidence: `toolchain/mfc/run/input.py`)
- Target input generation → Case model: constructs (evidence: `toolchain/mfc/run/input.py`)
- Target input generation → Solver build: generates target inputs (evidence: `toolchain/mfc/run/input.py`)
- Simulation runner → Solver build: builds targets (evidence: `toolchain/mfc/run/run.py`)
- Simulation runner → Batch queues: uses queues (evidence: `toolchain/mfc/run/run.py`)
- Simulation runner → Run archive: archives run (evidence: `toolchain/mfc/run/run.py`)
- Solver build → Flow solver: builds
- Simulation runner → Flow solver: launches targets
- Simulation runner → Toolchain configuration: reads configuration (evidence: `toolchain/mfc/run/run.py`)
- MFC user → Visualization entry: opens results
- Visualization entry → Result readers: reads results (evidence: `toolchain/mfc/viz/viz.py`)
- Visualization entry → Silo reader: reads Silo (evidence: `toolchain/mfc/viz/viz.py`)
- Visualization entry → Result renderer: renders (evidence: `toolchain/mfc/viz/viz.py`)
- Visualization entry → Interactive viewer: opens viewer (evidence: `toolchain/mfc/viz/viz.py`)
- Visualization entry → Terminal viewer: opens terminal UI (evidence: `toolchain/mfc/viz/viz.py`)
- Interactive viewer → Step cache: caches steps (evidence: `toolchain/mfc/viz/interactive.py`)
- Terminal viewer → Step cache: caches steps (evidence: `toolchain/mfc/viz/tui.py`)