How josephgwoods/ismrm2022_vsasl_bloch_simulations works
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