# josephgwoods/ismrm2022_vsasl_bloch_simulations architecture

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

- Interactive diagram: https://gitdiagram.com/josephgwoods/ismrm2022_vsasl_bloch_simulations
- Repository: https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations

## Overview

##### Project type and purpose
- This is an open-source MATLAB-based simulation and tutorial codebase for Velocity Selective Arterial Spin Labeling (VSASL) using Bloch‐equation simulations.
- The top-level entry point is run_VSASL_Simulations.m, which orchestrates generation of RF pulse modules, invokes Bloch‐simulation routines, and produces analysis/plots for the ISMRM 2022 tutorial.

##### File structure
- Top-level files:
- README.md – project description, tutorial references, usage notes
- run_VSASL_Simulations.m / .pdf – driver script and tutorial handout
- LICENSE
- Directories:
- PulseGen/ – MATLAB functions that generate RF pulse definitions (genBIR, genBIR4, genVSGrad, etc.)
- Bloch/ – MEX interface to C Bloch simulator (bloch_Hz.c, bloch_Hz.m, platform-specific mex binaries)
- Tools/ – utility functions (findNearest, fnsd, ndp, etc.) used by the pipeline
- Plot/ – plotting and visualization scripts (plot_VSprofile, surf_custom, laminarFlowInt)

##### Insights from the README
- run_VSASL_Simulations.m is the “controller” script.
- Bloch simulations rely on an adapted version of Brian Hargreaves’ MEX Bloch code.
- Core workflow: PulseGen → Bloch MEX → analysis via Tools → Plot.

##### Main components & interactions
a. Controller Layer
– run_VSASL_Simulations.m: orchestrates parameter setup, calls PulseGen, invokes Bloch simulation, then Tools & Plot.
b. Pulse Generation Layer
– PulseGen/*.m: generate RF pulse waveforms & timing tables.
– Output: pulse definitions (MAT files or MATLAB variables).
c. Simulation Engine
– Bloch/bloch_Hz.mex* + bloch_Hz.c: high-performance C/MEX Bloch solver.
– Inputs: pulse definitions, simulation parameters (B0, gradients, velocity cutoff).
– Output: magnetization time series or spatial profiles.
d. Utility Layer
– Tools/*.m: helper functions (grid resampling, nearest-neighbor lookup, B1/B0 ratio, resolution increase).
– Used by both PulseGen and post-processing steps.
e. Visualization Layer
– Plot/*.m: scripts to generate VS profiles, laminar flow integrals, custom 3D surf plots.
– Consume simulation outputs to produce figures.

##### Architectural patterns & design principles
- Pipeline (staged) architecture: clear separation of generation → simulation → analysis → visualization.
- Modular code organization: each directory encapsulates a concern.
- Reusability focus: Tools functions are generic utilities.

##### Technologies & external dependencies
- MATLAB interpreter (R2018b or later)
- MATLAB MEX interface (requires C compiler)
- C99 Bloch simulation code
- Platform-specific binaries: .mexw64 (Windows), .mexmaci64 (macOS)

##### Essential elements to capture
- Controller orchestration
- PulseGen generation modules
- MEX/C simulation boundary
- Utility toolkit usage
- Plotting/visualization stage
- Data artifacts exchanged at each hand-off

## Diagram (Mermaid)

```mermaid
graph TD
    %% External dependencies
    MATLAB["MATLAB Runtime"]:::external
    CCompiler["C Compiler"]:::external

    %% Controller
    Controller["run_VSASL_Simulations.m"]:::controller

    %% Pulse Generation Layer
    subgraph "Pulse Generation Layer"
        direction TB
        genBIR["genBIR.m"]:::generation
        genBIR4["genBIR4.m"]:::generation
        genBIR8["genBIR8.m"]:::generation
        genDRHS["genDRHS.m"]:::generation
        genDRHT["genDRHT.m"]:::generation
        genFTVSI["genFTVSI.m"]:::generation
        genHS["genHS.m"]:::generation
        genVSASL["genVSASL.m"]:::generation
        genVSGrad["genVSGrad.m"]:::generation
        gengrad["gengrad.m"]:::generation
        genhard["genhard.m"]:::generation
        VSTimingsEqual["VSTimingsEqual.m"]:::generation
    end

    %% Simulation Engine
    subgraph "Simulation Engine (C/MEX Plugin)"
        direction TB
        blochC["bloch_Hz.c"]:::simulation
        blochM["bloch_Hz.m"]:::simulation
        mexWin["bloch_Hz.mexw64"]:::simulation
        mexMac["bloch_Hz.mexmaci64"]:::simulation
        blochReadme["README.txt"]:::simulation
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        findNearest["findNearest.m"]:::utility
        fnsd["fnsd.m"]:::utility
        gradec["gradec.m"]:::utility
        gyroratio["gyroratio.m"]:::utility
        increaseres["increaseres.m"]:::utility
        ndp["ndp.m"]:::utility
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        laminarFlowInt["laminarFlowInt.m"]:::visualization
        plotVSprofile["plot_VSprofile.m"]:::visualization
        surfCustom["surf_custom.m"]:::visualization
    end

    %% Data flow
    MATLAB --> Controller
    Controller -->|"invoke generation"| genBIR
    Controller -->|"invoke generation"| genBIR4
    Controller -->|"invoke generation"| genBIR8
    Controller -->|"invoke generation"| genDRHS
    Controller -->|"invoke generation"| genDRHT
    Controller -->|"invoke generation"| genFTVSI
    Controller -->|"invoke generation"| genHS
    Controller -->|"invoke generation"| genVSASL
    Controller -->|"invoke generation"| genVSGrad
    Controller -->|"invoke generation"| gengrad
    Controller -->|"invoke generation"| genhard
    Controller -->|"invoke generation"| VSTimingsEqual

    genVSGrad -->|"pulse definitions"| blochM
    mexWin --> blochM
    mexMac --> blochM
    CCompiler -.-> blochC
    blochC --> blochM

    blochM -->|"magnetization time series"| findNearest
    blochM -->|"magnetization time series"| fnsd
    blochM -->|"magnetization time series"| gradec
    blochM -->|"magnetization time series"| gyroratio
    blochM -->|"magnetization time series"| increaseres
    blochM -->|"magnetization time series"| ndp

    ndp --> laminarFlowInt
    ndp --> plotVSprofile
    ndp --> surfCustom

    %% Click events
    click Controller "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/run_VSASL_Simulations.m"
    click genBIR "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genBIR.m"
    click genBIR4 "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genBIR4.m"
    click genBIR8 "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genBIR8.m"
    click genDRHS "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genDRHS.m"
    click genDRHT "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genDRHT.m"
    click genFTVSI "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genFTVSI.m"
    click genHS "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genHS.m"
    click genVSASL "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genVSASL.m"
    click genVSGrad "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genVSGrad.m"
    click gengrad "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/gengrad.m"
    click genhard "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/genhard.m"
    click VSTimingsEqual "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/PulseGen/VSTimingsEqual.m"

    click blochC "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Bloch/bloch_Hz.c"
    click blochM "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Bloch/bloch_Hz.m"
    click mexWin "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Bloch/bloch_Hz.mexw64"
    click mexMac "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Bloch/bloch_Hz.mexmaci64"
    click blochReadme "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Bloch/README.txt"

    click findNearest "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Tools/findNearest.m"
    click fnsd "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Tools/fnsd.m"
    click gradec "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Tools/gradec.m"
    click gyroratio "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Tools/gyroratio.m"
    click increaseres "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Tools/increaseres.m"
    click ndp "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Tools/ndp.m"

    click laminarFlowInt "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Plot/laminarFlowInt.m"
    click plotVSprofile "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Plot/plot_VSprofile.m"
    click surfCustom "https://github.com/josephgwoods/ismrm2022_vsasl_bloch_simulations/blob/main/Plot/surf_custom.m"

    %% Styles
    classDef controller fill:#DDEBF7,stroke:#6C8EBF,color:#000
    classDef generation fill:#BDD7EE,stroke:#6C8EBF,color:#000
    classDef simulation fill:#F4CCCC,stroke:#BF0000,color:#000
    classDef utility fill:#D9EAD3,stroke:#6AA84F,color:#000
    classDef visualization fill:#FCE5CD,stroke:#E69138,color:#000
    classDef external fill:#E7E6E6,stroke:#A6A6A6,color:#000,stroke-dasharray: 5 5
```
