Read the input as a scientific model, not as configuration noise
A MolSpin input file encodes a physical problem: which spins exist, how they interact, how the state is prepared, which kinetic processes are present and which numerical task turns that model into an observable. This module walks through real examples from the public MolSpin repository.
Map each MolSpin input object onto the physical model it represents.
Choose a task whose numerical capabilities match the Hamiltonian, kinetics and time dependence.
Record software versions, units and convergence settings so that a simulation remains reproducible.
Input anatomy
Seven object types carry most of the scientific meaning
Every input object should answer a physical question
What it is: They define the degrees of freedom and the Hamiltonian terms acting between them.
What it changes: They determine the energy levels and coherent quantum dynamics before any reaction or relaxation model is added.
What you observe: All subsequent simulated spectra, populations and yields inherit these choices.
What it is: It defines how the spin system is prepared at the start of the calculation or reaction step.
What it changes: Changing the initial singlet/triplet/coherent state can qualitatively change the dynamics even with the same Hamiltonian.
What you observe: Different transient populations, spin polarization and reaction yields.
What it is: It represents kinetic loss, recombination or transfer between states/systems rather than a Hamiltonian interaction.
What it changes: It competes with coherent spin evolution and sets how long the system has to explore spin-state space.
What you observe: Lifetimes, product yields and kinetic branching.
What it is: It selects the numerical interpretation of the model: static yield, time evolution, eigenvalues, spectroscopy and so on.
What it changes: It determines what equations are solved and which approximation/propagator is used.
What you observe: The form and meaning of the output; the same physical input can produce very different observables under different tasks.
The syntax is therefore easier to understand if you read it in the order physical system → Hamiltonian → state preparation → kinetics → numerical task.
Notebook A
Static radical pair and orientation scan
The public file Example/standard_examples/example.msd defines two electron spins, two nuclear spins, a Zeeman interaction and two hyperfine interactions. It then constructs singlet and triplet states, applies a spin-independent decay and rotates the magnetic field between calculation steps.
A short anatomy excerpt looks like this:
Spin electron1
{
type = electron;
}
Interaction zeeman1
{
type = Zeeman;
field = "0 0 0.05";
spins = electron1, electron2;
prefactor = 0.001;
}
State Singlet
{
spins(electron1,electron2)
= |1/2,-1/2> - |-1/2,1/2>;
}The same public example demonstrates several task classes: StaticSS, StaticHS-SymmetricDecay, RP-SymmetricUncoupled and Eigenvalues. This is useful because the physical spin system stays almost the same while the numerical question changes.
Notebook B
Time-dependent fields and interactions
The public time_dependent_example.msd shows that time dependence belongs to the interaction itself. The file contains linearly polarized and circularly polarized Zeeman fields, broadband modulation, Ornstein–Uhlenbeck modulation and time-dependent hyperfine tensors.
Interaction linearpolarized
{
type = Zeeman;
field = "0.0 0 0.05";
spins = electron1, electron2;
fieldtype = LinearPolarized;
frequency = 1e-2;
phase = 0;
}Its run section uses the public task name DynamicHS-Direct-TimeEvo. The important modelling lesson is that a time-dependent simulation requires both a time-dependent Hamiltonian object and a task that actually supports time-dependent propagation.
Notebook C
Pulses and spectroscopy
The public spectroscopy example introduces Pulse and PulseSequence objects. It contains instantaneous pulses, finite-duration pulses and a run task using MultiStaticSS-timeevolution.
Pulse pulse1
{
type = InstantPulse;
angle = 90;
rotationaxis = "1 0 0";
group = E1,E2,H1,H2;
}
PulseSequence seq
{
tau1 = 10;
tau2 = 15;
sequence = pulse1, tau1, pulse2, tau2;
}The same example enables chemically induced spin polarization through cidsp = true and specifies the spins for which polarization should be evaluated.
Notebook D
Multiple communicating radical-pair systems
The public TwoRadicalPairs-Example.msd defines two separate SpinSystem blocks and uses transitions with targetsystem and targetstate to transfer population between them.
This is the useful conceptual step: a kinetic network can contain several spin Hamiltonians rather than forcing the entire reaction sequence into one static spin system.
How to debug an input
Work from physics outward
Most simulation mistakes are unit, frame or model-definition mistakes before they are algorithmic mistakes
What it is: Spin parameters may be specified as energy, angular frequency, ordinary frequency, field units or code-specific scaled values.
What it changes: A missing factor of \(2\pi\), \(\hbar\) or a unit conversion changes the physical timescale even if the input parses correctly.
What you observe: Resonances, oscillation periods or relaxation times displaced by large systematic factors.
What it is: An anisotropic tensor has principal values and a specific orientation relative to the molecular/laboratory frame.
What it changes: Using the correct numbers in the wrong frame changes orientation-dependent dynamics and spectra.
What you observe: Wrong powder patterns, angular dependences and anisotropic radical-pair yields.
What it is: The same labels such as singlet, triplet or polarized state must correspond to the spin ordering and basis used by the input.
What it changes: A mismatched state definition changes the entire transient even if the Hamiltonian is correct.
What you observe: Qualitatively wrong early-time populations, polarization or reaction yields.
Check quantum numbers, electron/nuclear identity and tensor definitions before touching the task.
Check units, prefactors, groups and tensor frames. A numerically valid interaction can still represent the wrong physics.
Verify that the state or mixed ensemble corresponds to the preparation mechanism you intend to model.
Check whether transitions are spin selective, spin independent or transfers between systems.
Use a task that supports the interactions, decay model and time dependence present in the system.
Only after the model is correct should you tune timestep, stochastic samples, orientation grids or propagator tolerances.
Public main versus development branches
Do not mix syntax from different generations of MolSpin
The public examples above describe the repository state pinned at commit cc7cc7f3cd8580e074318b7baae960d84a054bb0. Active development can introduce unified task classes, new stochastic methods or changed property names before those interfaces become the public reference.
Methods papers
What the software is designed to solve
MolSpin—Flexible and extensible general spin dynamics software
The foundational MolSpin publication by Claus Nielsen and Ilia A. Solov’yov.
J. Chem. Phys. (2019) →Modeling spin relaxation in complex radical systems using MolSpin
Extends the framework toward open-system relaxation in complex radical systems.
J. Comput. Chem. (2023) →Spin Dynamics of Radical Pairs Using the Stochastic Schrödinger Equation in MolSpin
Develops stochastic state-vector propagation for larger radical-pair spin systems.
J. Chem. Theory Comput. (2024) →Key external literature
Where to read next
These are deliberately selected from outside my own work: foundational papers or reviews that are especially useful for this topic.
EasySpin, a comprehensive software package for spectral simulation and analysis in EPR
S. Stoll and A. Schweiger · Journal of Magnetic Resonance (2006). A complementary reference for EPR-oriented spin-Hamiltonian simulation and analysis.
Open DOI →Spinach – A software library for simulation of spin dynamics in large spin systems
H. J. Hogben et al. · Journal of Magnetic Resonance (2011). A useful comparison for numerical representations and large-system spin-dynamics strategies.
Open DOI →