⚛️ phenomenology

axionbloch: an Open-Source Python Package for Simulating Axion-Induced Spin Dynamics

The paper introduces **axionbloch**, an open-source Python package that simulates axion-induced spin dynamics using Bloch equations to generate accurate signal signatures for designing and analyzing ultralight dark matter experiments.

Original authors: Yuzhe Zhang

Published 2026-06-24

📖 4 min read🧠 Deep dive

CC BY 4.0

Original authors: Yuzhe Zhang

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine the universe is filled with a ghostly, invisible fog called axions. Scientists think this fog might be "dark matter," the stuff that holds galaxies together but doesn't let us see or touch it.

This paper introduces a new digital tool called axionbloch. Think of it as a high-tech flight simulator, but instead of teaching pilots how to fly planes, it teaches scientists how to "fly" through the invisible world of axions to see if they can catch a glimpse of them.

Here is how the paper explains it, broken down into simple concepts:

1. The Invisible Wind (The Axion Problem)

Imagine you are standing in a room with a giant, invisible fan blowing. You can't see the air, but if you hold a pinwheel, it will spin.

The Reality: Axions are like that invisible wind. They interact with the "spins" of tiny particles (like atoms) in a way that feels exactly like a magnetic field pushing on them.
The Challenge: Scientists want to build sensitive detectors (like super-precise pinwheels) to catch this wind. But before they build the real machine, they need to know exactly what the pinwheel should look like when the wind hits it.

2. The Simulator (axionbloch)

This is where axionbloch comes in. It is a free, open-source computer program written in Python (a popular coding language).

What it does: It acts as a virtual laboratory. Scientists can tell the computer, "Here is a specific type of axion wind, and here is our detector." The program then runs a movie of what happens to the atoms inside the detector.
The Engine: To make these movies run fast and smoothly, the program uses a powerful engine written in C++ (a faster, lower-level language) hidden inside the Python interface. It solves complex math equations (called Bloch equations) that describe how spins move, similar to how a weather model predicts how clouds move.

3. The "Test Drive" (Calibration)

Before you trust a flight simulator to train a pilot, you have to make sure the simulator behaves exactly like a real plane.

The Paper's Check: The author tested axionbloch against known physics rules. They simulated standard experiments (like spinning a pinwheel with a known magnet) and checked if the computer's results matched the real-world math perfectly.
The Result: The simulator passed with flying colors. The difference between the computer's prediction and the real math was so tiny it was practically zero. This means scientists can trust the results it produces for the unknown axion experiments.

4. The "Flight Plan" (How it Works)

The paper shows a code example (Figure 5) which is like a recipe.

Ingredients: You define your "sample" (the atoms), your "magnet" (the background field), and your "axion model" (the type of invisible wind you are looking for).
The Run: The program runs the simulation, calculating how the atoms wiggle and spin over time.
The Output: It produces a graph showing the signal. If the axion wind is there, the graph shows a specific wobble. If not, it stays flat.

5. Why This Matters

The paper argues that as scientists propose new theories about axions and build new, more sensitive detectors, they need a reliable way to predict what the data will look like.

The Benefit: Instead of guessing or doing messy math by hand, researchers can use axionbloch to quickly simulate thousands of scenarios. It helps them design better experiments and know exactly what signal to look for in their real-world data.

In summary: The paper presents axionbloch as a reliable, free, and easy-to-use digital sandbox. It allows physicists to simulate how invisible axion particles would nudge atoms in a detector, ensuring that when they finally build their real experiments, they know exactly what a "hit" looks like.

Technical Summary of axionbloch: an Open-Source Python Package for Simulating Axion-Induced Spin Dynamics

Problem Statement
The interaction between ultralight bosonic dark matter (axions and axion-like particles, or ALPs) and ordinary matter can be modeled as a pseudo-magnetic field acting on fermionic spins. This interaction is described by a Hamiltonian where the axion field gradient couples to the spin operator, inducing spin dynamics detectable via precision measurement experiments such as Nuclear Magnetic Resonance (NMR) and comagnetometer searches. While theoretical studies have derived axion signal signatures and experimental sensitivities, there has been a lack of dedicated numerical tools to verify these signatures or systematically simulate spin dynamics under diverse physical conditions and axion field configurations (e.g., cosmic axion backgrounds, fine-grained axions, or quadratically coupled axions). Furthermore, as new axion models and experimental proposals emerge, a flexible framework is required to bridge theoretical models with experimental observables.

Methodology
The paper introduces axionbloch, an open-source Python package designed to simulate spin dynamics induced by both standard magnetic fields and axion-induced pseudo-magnetic fields. The package employs the following technical approach:

Physical Modeling: The core physics is based on the Bloch equations, which describe the evolution of magnetization ( $M$ ) in the presence of effective magnetic fields ( $B_{eff}$ ). The package focuses on spin-1/2 magnetic resonance, treating the axion field gradient as a pseudo-magnetic field added to the bias field. To handle the disparity between the fast Larmor precession of the bias field and the slower axion-induced dynamics, the simulation utilizes a Rotating Coordinate Frame (RCF).
Numerical Integration: The time evolution of magnetization is solved using a fourth-order Runge–Kutta (RK4) method. The algorithm is implemented in a dedicated C++ library for computational efficiency, while the high-level workflow and parameter management are handled in Python. The two languages are interfaced via pybind11.
Architecture: The software is built using object-oriented programming. Key components include:
- Sample: Encapsulates experimental parameters such as relaxation times ( $T_1, T_2, T_2^*$ ) and sample properties.
- Magnet and MagField: Manage bias fields, their inhomogeneity, and the generation of pseudo-magnetic fields.
- MilkyWayAxionHalo (and extensible classes): Models specific axion field configurations, treating the field as an oscillating signal with frequency determined by axion mass and linewidth determined by velocity dispersion.
- Simulation and Simulations: Manage the execution of single or multiple simulation runs, integrating experimental configurations with axion models.
Units and Constants: The package leverages astropy.units for handling physical quantities, ensuring dimensional consistency and easy conversion between SI and CGS systems. Common constants (e.g., gyromagnetic ratios) are pre-defined within the package.

Key Contributions and Results

Open-Source Framework: The primary contribution is the release of axionbloch (available at https://github.com/Yuzhe98/AxionBloch), a modular tool that allows researchers to simulate pseudo-magnetic signals under specific axion model and experimental setups.
Calibration and Validation: The authors performed extensive calibration against theoretical expectations to ensure accuracy. Three specific benchmarks were established:
- Pulsed-NMR: Verified free decay ( $T_2^*$ ) and spin echo ( $T_2$ ) behaviors following 90° and 180° pulses.
- Continuous-Wave (CW) NMR: Validated the growth of transverse magnetization under weak oscillating fields.
- Hyperpolarized Samples: Confirmed the exponential decay of polarization due to $T_1$ relaxation.
- Quantitative Accuracy: The discrepancy between simulated and expected magnetization was quantified using a $\chi^2$ metric. Calibration results showed $\chi^2 < 10^{-4}$ for pulsed NMR and even lower values for CW-NMR and $T_1$ relaxation, confirming the reliability of the numerical implementation.
Demonstration of Capability: The paper presents a simulation of axion-induced signals from a local virialized axion dark matter halo (Milky Way model). The simulation successfully generated pseudo-magnetic fields and the resulting transverse magnetization, demonstrating the package's ability to handle stochastic axion fields and bias field inhomogeneities.
Performance: The hybrid Python/C++ architecture allows for efficient computation. A test case involving $7 \times 10^8$ integration steps completed in 2.7 seconds on a standard personal computer, enabling the exploration of various parameter regimes.

Significance
The paper positions axionbloch as a necessary tool for the systematic simulation of axion-induced spin dynamics, filling a gap in the field where numerical verification of signal signatures was previously lacking. By providing a well-documented, tested, and open-source platform, the package aims to facilitate the design of experimental searches and data analysis for axion detection. It serves as a bridge between theoretical axion models and experimental observables, allowing researchers to derive signal signatures for specific configurations. Additionally, the authors note the package's potential utility for educational purposes within the NMR community, enabling the visualization of pulse sequences and spin dynamics. The tool is designed to be extensible, accommodating future axion models and experimental proposals, including potential future implementations for zero-to-ultra-low-field (ZULF) NMR.