# lucanagel/bloch_sim_gui architecture

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

## Overview

Bloch Equation Simulator is a Python MRI simulation package with a desktop GUI and Python API. Its main workflows are either configuring tissue and RF parameters for a Free Mode Bloch simulation, or loading/generating a Pulseq sequence, simulating it against a phantom, and inspecting reconstructed acquisitions. The README also documents phantom and B1 design, spectral-spatial RF design, project persistence, notebook export, and Bruker export. Edges reflect those documented workflows and capabilities; unsampled implementation details are not inferred.

Main entry points: [`src/blochsimulator/ui/main_window.py`](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/main_window.py) (Desktop GUI), [`src/blochsimulator/ui/sequence_designer.py`](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/sequence_designer.py) (Sequence workspace), [`src/blochsimulator/simulator.py`](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/simulator.py) (Bloch simulator), [`src/blochsimulator/sequence/compiler.py`](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/compiler.py) (Sequence engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation"]
  node_simulator["Bloch simulator<br/>[simulator.py]"]
  node_c_core["C solver core"]
  node_rf_design["RF pulse design<br/>[rf_pulses.py]"]
  node_metal_backend["Metal backend"]
end

subgraph group_sequence["Sequence workflows"]
  node_sequence_designer["Sequence workspace"]
  node_pulseq_builders["Pulseq builders<br/>[pulseq_builders.py]"]
  node_spectral_rf["Spectral-spatial RF"]
  node_sequence_engine["Sequence engine<br/>[compiler.py]"]
  node_spin_sampling["Spin sampling<br/>[spin_sampling.py]"]
  node_acquisition["Acquisition layouts<br/>[acquisition.py]"]
  node_bruker["Bruker export<br/>[bruker_export.py]"]
end

subgraph group_phantoms["Phantoms and fields"]
  node_phantom["Tissue phantom<br/>[phantom.py]"]
  node_spectral_phantom["Spectral phantom"]
  node_dynamic_phantom["Dynamic phantom<br/>[dynamic_phantom.py]"]
  node_phantom_design["Phantom designer<br/>[phantom_design.py]"]
  node_b1_fields["B1 field design<br/>[b1_fields.py]"]
end

subgraph group_interface["GUI and outputs"]
  node_gui["Desktop GUI<br/>[main_window.py]"]
  node_reconstruction["Reconstruction explorer"]
  node_project_io["Project persistence<br/>[project_io.py]"]
  node_notebook_export["Notebook export"]
  node_visualization["Simulation views<br/>[visualization.py]"]
end

node_user(("MRI researcher"))

node_user -->|"configures"| node_gui
node_gui -->|"runs simulation"| node_simulator
node_user -->|"runs API"| node_simulator
node_simulator -->|"solves Bloch equations"| node_c_core
node_gui -->|"designs RF"| node_rf_design
node_gui -->|"configures tissue"| node_phantom
node_gui -->|"opens sequence mode"| node_sequence_designer
node_sequence_designer -->|"generates sequences"| node_pulseq_builders
node_sequence_designer -->|"simulates sequences"| node_sequence_engine
node_sequence_designer -->|"designs spectral RF"| node_spectral_rf
node_sequence_designer -->|"configures dynamic phantom"| node_dynamic_phantom
node_sequence_designer -->|"configures spectral phantom"| node_spectral_phantom
node_gui -->|"designs phantom"| node_phantom_design
node_gui -->|"designs B1 fields"| node_b1_fields
node_sequence_engine -->|"samples spins"| node_spin_sampling
node_sequence_engine -->|"organizes acquisition"| node_acquisition
node_gui -->|"inspects reconstruction"| node_reconstruction
node_gui -->|"saves projects"| node_project_io
node_gui -->|"exports notebooks"| node_notebook_export
node_gui -->|"views results"| node_visualization
node_gui -->|"exports acquisitions"| node_bruker
node_simulator -.->|"optional acceleration"| node_metal_backend

click node_gui "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/main_window.py"
click node_simulator "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/simulator.py"
click node_c_core "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/bloch_core_modified.c"
click node_rf_design "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/rf_pulses.py"
click node_phantom "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/phantom.py"
click node_spectral_phantom "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/spectral_phantom.py"
click node_dynamic_phantom "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/dynamic_phantom.py"
click node_phantom_design "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/phantom_design.py"
click node_b1_fields "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/b1_fields.py"
click node_metal_backend "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/dynamic_metal_backend.py"
click node_sequence_designer "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/sequence_designer.py"
click node_pulseq_builders "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/pulseq_builders.py"
click node_spectral_rf "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/spectral_spatial.py"
click node_sequence_engine "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/compiler.py"
click node_spin_sampling "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/spin_sampling.py"
click node_acquisition "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/acquisition.py"
click node_reconstruction "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/reconstruction_explorer.py"
click node_project_io "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/project_io.py"
click node_notebook_export "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/notebook_exporter.py"
click node_visualization "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/visualization.py"
click node_bruker "https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/bruker_export.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_simulator,node_c_core,node_rf_design,node_metal_backend toneBlue
class node_sequence_designer,node_pulseq_builders,node_spectral_rf,node_sequence_engine,node_spin_sampling,node_acquisition,node_bruker toneAmber
class node_phantom,node_spectral_phantom,node_dynamic_phantom,node_phantom_design,node_b1_fields toneMint
class node_gui,node_reconstruction,node_project_io,node_notebook_export,node_visualization toneRose
class node_user toneIndigo
```

## Components

### Simulation

- [Bloch simulator](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/simulator.py): `src/blochsimulator/simulator.py`
- [C solver core](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/bloch_core_modified.c): `src/blochsimulator/bloch_core_modified.c`
- [RF pulse design](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/rf_pulses.py): `src/blochsimulator/sequence/rf_pulses.py`
- [Metal backend](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/dynamic_metal_backend.py): `src/blochsimulator/dynamic_metal_backend.py`

### Sequence workflows

- [Sequence workspace](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/sequence_designer.py): `src/blochsimulator/ui/sequence_designer.py`
- [Pulseq builders](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/pulseq_builders.py): `src/blochsimulator/sequence/pulseq_builders.py`
- [Spectral-spatial RF](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/spectral_spatial.py): `src/blochsimulator/sequence/spectral_spatial.py`
- [Sequence engine](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/compiler.py): `src/blochsimulator/sequence/compiler.py`
- [Spin sampling](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/spin_sampling.py): `src/blochsimulator/sequence/spin_sampling.py`
- [Acquisition layouts](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/acquisition.py): `src/blochsimulator/sequence/acquisition.py`
- [Bruker export](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/sequence/bruker_export.py): `src/blochsimulator/sequence/bruker_export.py`

### Phantoms and fields

- [Tissue phantom](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/phantom.py): `src/blochsimulator/phantom.py`
- [Spectral phantom](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/spectral_phantom.py): `src/blochsimulator/spectral_phantom.py`
- [Dynamic phantom](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/dynamic_phantom.py): `src/blochsimulator/dynamic_phantom.py`
- [Phantom designer](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/phantom_design.py): `src/blochsimulator/phantom_design.py`
- [B1 field design](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/b1_fields.py): `src/blochsimulator/b1_fields.py`

### GUI and outputs

- [Desktop GUI](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/main_window.py): `src/blochsimulator/ui/main_window.py`
- [Reconstruction explorer](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/ui/reconstruction_explorer.py): `src/blochsimulator/ui/reconstruction_explorer.py`
- [Project persistence](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/project_io.py): `src/blochsimulator/project_io.py`
- [Notebook export](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/notebook_exporter.py): `src/blochsimulator/notebook_exporter.py`
- [Simulation views](https://github.com/lucanagel/bloch_sim_gui/blob/main/src/blochsimulator/visualization.py): `src/blochsimulator/visualization.py`

### Other components

- **MRI researcher**

## Connections

- MRI researcher → Desktop GUI: configures
- Desktop GUI → Bloch simulator: runs simulation (evidence: `src/blochsimulator/ui/main_window.py`)
- MRI researcher → Bloch simulator: runs API
- Bloch simulator → C solver core: solves Bloch equations
- Desktop GUI → RF pulse design: designs RF
- Desktop GUI → Tissue phantom: configures tissue (evidence: `src/blochsimulator/ui/main_window.py`)
- Desktop GUI → Sequence workspace: opens sequence mode (evidence: `src/blochsimulator/ui/main_window.py`)
- Sequence workspace → Pulseq builders: generates sequences
- Sequence workspace → Sequence engine: simulates sequences
- Sequence workspace → Spectral-spatial RF: designs spectral RF
- Sequence workspace → Dynamic phantom: configures dynamic phantom
- Sequence workspace → Spectral phantom: configures spectral phantom
- Desktop GUI → Phantom designer: designs phantom
- Desktop GUI → B1 field design: designs B1 fields
- Sequence engine → Spin sampling: samples spins (evidence: `src/blochsimulator/sequence/__init__.py`)
- Sequence engine → Acquisition layouts: organizes acquisition (evidence: `src/blochsimulator/sequence/__init__.py`)
- Desktop GUI → Reconstruction explorer: inspects reconstruction
- Desktop GUI → Project persistence: saves projects (evidence: `src/blochsimulator/ui/main_window.py`)
- Desktop GUI → Notebook export: exports notebooks (evidence: `src/blochsimulator/ui/main_window.py`)
- Desktop GUI → Simulation views: views results (evidence: `src/blochsimulator/ui/main_window.py`)
- Desktop GUI → Bruker export: exports acquisitions
- Bloch simulator → Metal backend: optional acceleration (evidence: `src/blochsimulator/simulator.py`)