Examples
This page provides worked examples showing how to use radpair to
simulate cw-EPR spectra of spin-correlated radical pairs. All examples
use typed dataclass objects (Spinsystem, Experiment,
SimulationOptions from radpair._types) to define the spin
system, experiment, and simulation options.
Every code block on this page is self-contained — you can copy and paste
it into a .py file and run it directly.
Note
The examples require Matplotlib
for plotting, which is included in the dev dependencies. Install with
uv sync --dev or pip install matplotlib.
Common setup
All seven example spectra share the same X-band experiment and simulation options. The following code is needed for every example below:
import numpy as np
import matplotlib.pyplot as plt
from radpair._types import Experiment, SimulationOptions, Spinsystem
from radpair.core import do_simulation
# Experiment: X-band EPR, 9.75 GHz, field sweep 344–350 mT
field_axis = np.linspace(344.0, 350.0, 500)
experiment = Experiment(
B_z=field_axis,
freq_mw=9.75e9, # Hz
)
# Simulation options: 12 orientation grid knots, single core
simopt = SimulationOptions(
knots=12,
refinement=1,
cpu_cores=1,
max_chunk_mb=None, # auto-detect chunk size from available RAM
)
_zero = np.array([0.0, 0.0, 0.0])
The do_simulation() function takes three arguments
— spinsystem, experiment, simopt — and returns a
real-valued intensity array matching the shape of experiment.B_z:
intensity = do_simulation(spinsystem, experiment, simopt)
Unit conventions
Attribute |
Unit |
|---|---|
|
milliTesla |
|
Hz |
|
MHz (list of 3-element arrays) |
|
MHz |
|
MHz |
|
milliTesla (despite the name) |
|
radians (Euler angles [alpha, beta, gamma]) |
|
dimensionless (3-element diagonal) |
|
list of equivalent-nuclei counts (int >= 0) |
|
list of nuclear spins (float, 1/2 multiples) |
|
0-indexed list of donor nuclei positions |
|
0-indexed list of acceptor nuclei positions |
Example 1: Bare radical pair (S1)
The simplest anisotropic radical pair: two radicals with anisotropic g-tensors, nonzero ZFS (D = 8 MHz, E = 1.5 MHz) and exchange (J = 2 MHz), but no resolved hyperfine couplings.
spinsystem = Spinsystem(
g1=np.array([2.0023, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[_zero, _zero, _zero, _zero, _zero],
nuclei_n=[0, 0, 0, 0, 0],
nuclei_I=[0.0, 0.0, 0.0, 0.0, 0.0],
D=8.0, E=1.5, J_ex=2.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[_zero, _zero, _zero, _zero, _zero],
donor_list=[], acceptor_list=[],
)
intensity = do_simulation(spinsystem, experiment, simopt)
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity, lw=0.8, color="C0")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S1 — Bare radical pair (0 nuclei)")
ax.axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Example 2: Single donor nucleus, isotropic (S2)
One donor proton with isotropic g-tensors and isotropic hyperfine coupling (A = 1.5 MHz). The acceptor is “silent” (no nuclei, isotropic g). A small exchange (J = 0.1 MHz) is present; ZFS is zero.
spinsystem = Spinsystem(
g1=np.array([2.0030, 2.0030, 2.0030]),
g2=np.array([2.0090, 2.0090, 2.0090]),
A_tensors=[np.array([1.5, 1.5, 1.5]), _zero, _zero, _zero, _zero],
nuclei_n=[1, 0, 0, 0, 0],
nuclei_I=[0.5, 0.0, 0.0, 0.0, 0.0],
D=0.0, E=0.0, J_ex=0.1,
width_gauss=0.05,
g1_frame=_zero, g2_frame=_zero, D_frame=_zero,
A_frames=[_zero, _zero, _zero, _zero, _zero],
donor_list=[0], acceptor_list=[],
)
intensity = do_simulation(spinsystem, experiment, simopt)
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity, lw=0.8, color="C1")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S2 — Single donor ¹H, isotropic")
ax.axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Example 3: Two anisotropic nuclei, mixed donor/acceptor (S3)
A more realistic system: the donor carries one ¹H with anisotropic hyperfine coupling (A = [5, 3, 4] MHz), and the acceptor carries two equivalent ¹⁴N nuclei (I = 1, n = 2, A = [2.5, 1.8, 3.2] MHz). Both g-tensors are anisotropic, and ZFS (D = 8, E = 1.5 MHz) and exchange (J = 3 MHz) are nonzero. Several Euler frames are nonzero, so tensors are rotated relative to the lab frame.
spinsystem = Spinsystem(
g1=np.array([2.0020, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([5.0, 3.0, 4.0]),
np.array([2.5, 1.8, 3.2]),
_zero, _zero, _zero,
],
nuclei_n=[1, 2, 0, 0, 0],
nuclei_I=[0.5, 1.0, 0.0, 0.0, 0.0],
D=8.0, E=1.5, J_ex=3.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
np.array([0.0, 0.1, 0.0]),
np.array([0.1, 0.0, 0.0]),
_zero, _zero, _zero,
],
donor_list=[0], acceptor_list=[1],
)
intensity = do_simulation(spinsystem, experiment, simopt)
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity, lw=0.8, color="C2")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S3 — 2 nuclei (donor ¹H + acceptor 2×¹⁴N), anisotropic")
ax.axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Example 4: Donor/acceptor swap (S3 vs S4)
Systems S3 and S4 are identical except that the donor and acceptor nuclei assignments are swapped. This demonstrates how the same nuclei produce different spectra depending on which radical they belong to — the MHz-to-Tesla conversion uses different g-tensors for donor vs. acceptor nuclei.
# S3: donor ¹H + acceptor 2×¹⁴N
spinsystem_S3 = Spinsystem(
g1=np.array([2.0020, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([5.0, 3.0, 4.0]),
np.array([2.5, 1.8, 3.2]),
_zero, _zero, _zero,
],
nuclei_n=[1, 2, 0, 0, 0],
nuclei_I=[0.5, 1.0, 0.0, 0.0, 0.0],
D=8.0, E=1.5, J_ex=3.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
np.array([0.0, 0.1, 0.0]),
np.array([0.1, 0.0, 0.0]),
_zero, _zero, _zero,
],
donor_list=[0], acceptor_list=[1],
)
# S4: same tensors, swapped assignments
spinsystem_S4 = Spinsystem(
g1=np.array([2.0020, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([5.0, 3.0, 4.0]),
np.array([2.5, 1.8, 3.2]),
_zero, _zero, _zero,
],
nuclei_n=[1, 2, 0, 0, 0],
nuclei_I=[0.5, 1.0, 0.0, 0.0, 0.0],
D=8.0, E=1.5, J_ex=3.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
np.array([0.0, 0.1, 0.0]),
np.array([0.1, 0.0, 0.0]),
_zero, _zero, _zero,
],
donor_list=[1], acceptor_list=[0],
)
intensity_S3 = do_simulation(spinsystem_S3, experiment, simopt)
intensity_S4 = do_simulation(spinsystem_S4, experiment, simopt)
print(f"S3 sum: {intensity_S3.sum():.10e}")
print(f"S4 sum: {intensity_S4.sum():.10e}")
print(f"Max abs diff: {np.max(np.abs(intensity_S3 - intensity_S4)):.2e}")
fig, axes = plt.subplots(3, 1, figsize=(9, 9), sharex=True)
axes[0].plot(field_axis, intensity_S3, lw=0.8, color="C2")
axes[0].set_ylabel("Intensity")
axes[0].set_title("S3 — donor ¹H + acceptor 2×¹⁴N")
axes[0].axhline(0, color="gray", lw=0.5, ls="--")
axes[1].plot(field_axis, intensity_S4, lw=0.8, color="C5")
axes[1].set_ylabel("Intensity")
axes[1].set_title("S4 — acceptor ¹H + donor 2×¹⁴N (swap)")
axes[1].axhline(0, color="gray", lw=0.5, ls="--")
axes[2].plot(field_axis, intensity_S3 - intensity_S4, lw=0.8, color="C7")
axes[2].set_ylabel("S3 − S4")
axes[2].set_xlabel("Magnetic field $B_z$ (mT)")
axes[2].set_title("Difference")
axes[2].axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Example 5: Three nuclei with methyl group (S5)
Donor with a methyl group (3 equivalent ¹H, n = 3, A = [4.5, 3.0, 5.5] MHz) plus a single ¹H (A = [1.2, 1.5, 0.8] MHz), acceptor with 2 equivalent ¹⁴N (A = [2.5, 1.8, 3.2] MHz). All tensors are anisotropic, with full ZFS (D = 10, E = 2 MHz) and exchange (J = 5 MHz).
spinsystem = Spinsystem(
g1=np.array([2.0020, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([4.5, 3.0, 5.5]),
np.array([1.2, 1.5, 0.8]),
np.array([2.5, 1.8, 3.2]),
_zero, _zero,
],
nuclei_n=[3, 1, 2, 0, 0],
nuclei_I=[0.5, 0.5, 1.0, 0.0, 0.0],
D=10.0, E=2.0, J_ex=5.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
np.array([0.1, 0.0, 0.0]),
np.array([0.0, 0.1, 0.0]),
np.array([0.1, 0.1, 0.0]),
_zero, _zero,
],
donor_list=[0, 1], acceptor_list=[2],
)
intensity = do_simulation(spinsystem, experiment, simopt)
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity, lw=0.8, color="C4")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S5 — 3 nuclei (methyl 3×¹H + ¹H + 2×¹⁴N)")
ax.axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Example 6: Four nuclei with ³⁵Cl (S6)
Donor with one ¹H (A = [1.5, 1.5, 1.5] MHz, isotropic), acceptor with ¹⁴N (A = [3.0, 2.0, 4.0] MHz) + ³⁵Cl (I = 3/2, A = [8.0, 5.0, 10.0] MHz) + 2×¹H (A = [0.8, 1.2, 0.6] MHz). The donor g-tensor is isotropic while the acceptor g-tensor is anisotropic. ZFS (D = 6, E = 1 MHz) and exchange (J = 1.5 MHz).
spinsystem = Spinsystem(
g1=np.array([2.0030, 2.0030, 2.0030]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([1.5, 1.5, 1.5]),
np.array([3.0, 2.0, 4.0]),
np.array([8.0, 5.0, 10.0]),
np.array([0.8, 1.2, 0.6]),
_zero,
],
nuclei_n=[1, 1, 1, 2, 0],
nuclei_I=[0.5, 1.0, 1.5, 0.5, 0.0],
D=6.0, E=1.0, J_ex=1.5,
width_gauss=0.05,
g1_frame=_zero,
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
_zero,
np.array([0.1, 0.0, 0.0]),
np.array([0.0, 0.2, 0.0]),
_zero, _zero,
],
donor_list=[0], acceptor_list=[1, 2, 3],
)
intensity = do_simulation(spinsystem, experiment, simopt)
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity, lw=0.8, color="C5")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S6 — 4 nuclei (¹H + ¹⁴N + ³⁵Cl + 2×¹H)")
ax.axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Example 7: Five nuclei, maximum complexity (S7)
All five nuclei groups are active (3 donor + 2 acceptor), with anisotropic g-tensors, full ZFS (D = 10, E = 2 MHz), exchange (J = 5 MHz), and multiple nuclear spins (I = 1/2, 1, 3/2) and multiplicities (n = 1, 2).
spinsystem = Spinsystem(
g1=np.array([2.0020, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([4.5, 3.0, 5.5]),
np.array([2.0, 1.5, 2.8]),
np.array([6.0, 4.0, 8.0]),
np.array([1.5, 1.0, 2.0]),
np.array([3.0, 2.0, 4.0]),
],
nuclei_n=[1, 2, 1, 1, 2],
nuclei_I=[0.5, 1.0, 1.5, 0.5, 0.5],
D=10.0, E=2.0, J_ex=5.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
np.array([0.1, 0.0, 0.0]),
np.array([0.0, 0.1, 0.0]),
np.array([0.1, 0.1, 0.0]),
_zero, _zero,
],
donor_list=[0, 1, 2], acceptor_list=[3, 4],
)
intensity = do_simulation(spinsystem, experiment, simopt)
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity, lw=0.8, color="C3")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S7 — 5 nuclei (3 donor + 2 acceptor), maximum complexity")
ax.axhline(0, color="gray", lw=0.5, ls="--")
fig.tight_layout()
plt.show()
Multi-core simulation
For computationally expensive systems, do_simulation_multicore()
runs the analytic pipeline once on the main process, then distributes
the Gaussian peak summation across cpu_cores worker processes.
Each worker handles a chunk of peaks, keeping per-process memory
bounded by max_chunk_mb. The result is numerically identical to
the single-core call.
from radpair._types import SimulationOptions
from radpair.core import do_simulation, do_simulation_multicore
# Reuse the S3 spinsystem from Example 3
spinsystem = Spinsystem(
g1=np.array([2.0020, 2.0040, 2.0060]),
g2=np.array([2.0080, 2.0100, 2.0120]),
A_tensors=[
np.array([5.0, 3.0, 4.0]),
np.array([2.5, 1.8, 3.2]),
_zero, _zero, _zero,
],
nuclei_n=[1, 2, 0, 0, 0],
nuclei_I=[0.5, 1.0, 0.0, 0.0, 0.0],
D=8.0, E=1.5, J_ex=3.0,
width_gauss=0.05,
g1_frame=np.array([0.1, 0.2, 0.0]),
g2_frame=np.array([0.0, 0.3, 0.1]),
D_frame=np.array([0.2, 0.1, 0.0]),
A_frames=[
np.array([0.0, 0.1, 0.0]),
np.array([0.1, 0.0, 0.0]),
_zero, _zero, _zero,
],
donor_list=[0], acceptor_list=[1],
)
simopt_multicore = SimulationOptions(
knots=12,
refinement=1,
cpu_cores=4, # use 4 worker processes (0 = auto-detect)
max_chunk_mb=None, # auto-detect chunk size from available RAM
)
intensity_sc = do_simulation(spinsystem, experiment, simopt)
intensity_mc = do_simulation_multicore(spinsystem, experiment, simopt_multicore)
print(f"Single-core sum: {intensity_sc.sum():.10e}")
print(f"Multi-core sum: {intensity_mc.sum():.10e}")
print(f"Max abs diff: {np.max(np.abs(intensity_sc - intensity_mc)):.2e}")
fig, ax = plt.subplots(figsize=(8, 4))
ax.plot(field_axis, intensity_mc, lw=0.8, color="C4", label="4 cores")
ax.set_xlabel("Magnetic field $B_z$ (mT)")
ax.set_ylabel("Intensity (arb. u.)")
ax.set_title("S3 — Multi-core simulation (cpu_cores = 4)")
ax.axhline(0, color="gray", lw=0.5, ls="--")
ax.legend()
fig.tight_layout()
plt.show()
Chunked Gaussian summation
The EPR spectrum is assembled by summing Gaussian line shapes for every
(orientation, hyperfine combination, transition) triplet. The total
number of peaks grows as n_orientations × n_combinations × 4 and can
easily reach hundreds of thousands or millions. Internally,
eprbase builds a dense float32 array of shape
(n_peaks, n_field) for the Gaussian evaluation — at 500 field points
this consumes n_peaks × 2 KB of memory.
The max_chunk_mb option controls how much memory a single chunk may
use:
``None`` (default) — auto-detect from available RAM (targets 25% of free memory per chunk). This works well on most systems.
``0`` or negative — disable chunking entirely. All peaks are processed in one pass. Fastest for small systems but may cause out-of-memory errors for large ones.
Positive integer — maximum memory in megabytes per chunk. Smaller values reduce peak memory at the cost of more iterations. Useful when running multiple simulations in parallel or when the auto-detection is too aggressive.
# Explicit 512 MB per chunk
simopt = SimulationOptions(
knots=25,
max_chunk_mb=512,
)
# No limit (use with caution on large systems)
simopt = SimulationOptions(
knots=25,
max_chunk_mb=0,
)
The same option applies to both do_simulation() and
do_simulation_multicore(). In multicore mode each
worker respects the limit independently, so the total memory
requirement is approximately cpu_cores × max_chunk_mb.
Overview of all seven example spectra (S1–S7), showing the increasing spectral complexity as more nuclei groups are added.
Available example scripts
All scripts are in the examples/ directory and can be run individually
with uv run python examples/<script_name>.py. They use shared system
definitions from examples/_systems.py.
Script |
Description |
|---|---|
|
S1: bare radical pair, 0 nuclei |
|
S2: single donor ¹H, isotropic |
|
S3: 2 nuclei, mixed donor/acceptor, anisotropic |
|
S3 vs S4: donor/acceptor swap comparison |
|
S7: 5 nuclei, maximum complexity |
|
Multi-core simulation demo |
|
Generate all 7 spectra plots for the docs |