The app is not signed with an Apple Developer ID, so macOS quarantines it. Move BlochSimulator.app to Applications and launch it. If it is blocked:

1. Dismiss the warning.
2. Open System Settings > Privacy & Security and scroll to Security.
3. Click Open Anyway next to the BlochSimulator.app message.
4. Launch BlochSimulator again.

Alternatively, if you trust the download, remove the quarantine flag:

xattr -cr /Applications/BlochSimulator.app

Load a saved project

from blochsimulator.project_io import load_project

project = load_project("simulation.blochproj")
phantom = project["phantom"]
result = project["sequence_result"]

See Bloch project vs. exported results and load_bloch_project.ipynb.

Spin echo sequence

from blochsimulator import BlochSimulator, SpinEcho, TissueParameters

sim = BlochSimulator()

# Create spin echo sequence
sequence = SpinEcho(te=20e-3, tr=500e-3)  # 20ms TE, 500ms TR

# Simulate white matter
tissue = TissueParameters.white_matter(3.0)

# Run simulation with multiple frequencies (T2* effects)
frequencies = np.linspace(-50, 50, 11)  # Hz
result = sim.simulate(sequence, tissue, frequencies=frequencies)

# Access magnetization components
mx, my, mz = result['mx'], result['my'], result['mz']
signal = result['signal']

Custom pulse design

from blochsimulator import design_rf_pulse

# Design a sinc pulse
b1, time = design_rf_pulse(
    pulse_type='sinc',
    duration=2e-3,      # 2 ms
    flip_angle=180,     # degrees
    time_bw_product=4,  # Time-bandwidth product
    npoints=200
)

# Apply phase
phase = np.pi/4  # 45 degrees
b1_phased = b1 * np.exp(1j * phase)

Parallel simulation

# Simulate multiple positions and frequencies in parallel
positions = np.random.randn(100, 3) * 0.01  # Position scale: 10 mm
frequencies = np.linspace(-200, 200, 41)     # 41 frequencies

result = sim.simulate(
    sequence=sequence,
    tissue=tissue,
    positions=positions,
    frequencies=frequencies,
    mode=0  # Endpoint only (faster)
)

# Result shape: (100 positions, 41 frequencies)
print(f"Signal shape: {result['signal'].shape}")

Xarray integration

For advanced analysis, you can convert simulation results directly to an xarray.Dataset. This provides named dimensions, coordinates, and automatic metadata tracking.

# Convert last result to xarray
ds = sim.get_results_as_xarray()

# Access data with named dimensions
# Dimensions: (time, position, frequency)
print(ds.mx.dims)

# Powerful selection and plotting
ds.signal.sel(frequency=0, method='nearest').plot()

# Metadata is preserved in attributes
print(ds.attrs['t1'], ds.attrs['te'])

Sequence library

Pre-defined sequences are available:

from blochsimulator import SpinEcho, GradientEcho

# Spin Echo
se = SpinEcho(te=30e-3, tr=1.0)

# Gradient Echo
gre = GradientEcho(te=5e-3, tr=10e-3, flip_angle=30)

# Compile to waveforms
b1, gradients, time = se.compile(dt=1e-6)

Tissue parameter library

Common tissues at different field strengths:

from blochsimulator import TissueParameters

# 3T parameters
gm = TissueParameters.gray_matter(3.0)
wm = TissueParameters.white_matter(3.0)
csf = TissueParameters.csf(3.0)

# 7T parameters
gm_7t = TissueParameters.gray_matter(7.0)

# Custom tissue
liver = TissueParameters(
    name="Liver",
    t1=0.812,
    t2=0.042,
    t2_star=0.028,
    density=0.9
)

Install from source

The Python package supports Python 3.10 or later. Desktop GUI development and PyInstaller app builds use the shared Python 3.12 runtime declared in .python-version, so the source GUI and packaged app do not silently use different interpreters.

• Windows: Install Python from python.org and select Add Python to PATH. Install Visual Studio Build Tools with Desktop development with C++.
• macOS: Install Python from python.org or with brew install python. Install the compiler with xcode-select --install. For optional OpenMP acceleration, install libomp with Homebrew.
• Linux: Install Python and a compiler with sudo apt install python3 python3-pip build-essential on Ubuntu/Debian, or install the corresponding Python and Development Tools packages on Fedora.

Clone the repository and install it in editable mode:

git clone https://github.com/LucaNagel/bloch_sim_gui.git
cd bloch_sim_gui
pip install -e .

For desktop GUI development, use the shared launcher instead of invoking an arbitrary python or python3 from PATH:

./scripts/run_gui.sh

Both this launcher and scripts/build_pyinstaller.sh use .venv-packaging. The current repository is installed there in editable mode, preventing an old installed BlochSimulator package from shadowing the working tree. Set BLOCH_PYTHON=/path/to/python3.12 if Python 3.12 is not discoverable as python3.12.

Verify the installation:

from blochsimulator import BlochSimulator, TissueParameters

sim = BlochSimulator()
tissue = TissueParameters.gray_matter(3.0)
print(f"T1: {tissue.t1:.3f}s, T2: {tissue.t2:.3f}s")

Conda environment for notebooks and the Python API

From the repository root, create an environment with an explicit Python version:

conda create -n bloch-simulator python=3.12 pip
conda activate bloch-simulator
python -m pip install -e .

Select this environment as the kernel in your notebook editor.

Pip installs h5py automatically because it is declared in pyproject.toml. If no compatible pre-built wheel is available, pip attempts a source build, which needs a separately installed HDF5 library. To use Conda's pre-built h5py package and its HDF5 dependency, optionally add h5py to the conda create command before running pip. See the Conda setup notes for details.

Build the desktop application

Standalone applications for macOS, Windows, and Linux are automatically built and attached to GitHub Releases whenever a new version tag is pushed. The instructions below are for manual local builds. One build per operating system is required.

Prerequisites:

• macOS: Xcode CLT; brew install libomp
• Windows: Python 3.10+ and MSVC Build Tools for the C extension
• Linux: gcc/g++; ensure libgomp is available

Quick build:

./scripts/build_pyinstaller.sh

The artifact is written to dist/BlochSimulator as a single binary, with an .exe suffix on Windows.

The equivalent explicit commands use the same environment:

.venv-packaging/bin/python setup.py build_ext --inplace
.venv-packaging/bin/python -m PyInstaller bloch_gui.spec --noconfirm

Run the packaged application with ./dist/BlochSimulator on macOS/Linux or dist\\BlochSimulator.exe on Windows.

Runtime data and exports:

• rfpulses/ is bundled automatically.
• Exports default to per-user data directories:
  • macOS: ~/Library/Application Support/BlochSimulator/exports
  • Windows: %APPDATA%\\BlochSimulator\\exports
  • Linux: ~/.local/share/BlochSimulator/exports
• Override the location with BLOCH_APP_DIR or BLOCH_EXPORT_DIR.

Project structure

blochsimulator/
├── src/
│   └── blochsimulator/
│       ├── __init__.py
│       ├── simulator.py            # Core Python API
│       ├── gui.py                  # PyQt5 GUI
│       ├── bloch_core_modified.c   # C implementation
│       ├── bloch_core.h            # C header
│       ├── bloch_wrapper.pyx       # Cython wrapper
│       └── ...
├── tests/                          # Unit tests
├── docs/                           # Sphinx documentation
├── pyproject.toml                  # Modern build config
├── setup.py                        # C-extension build config
├── MANIFEST.in                     # Source dist manifest
└── README.md