---
title: 'FindMuonWorkchain: Automated DFT+μ Workflow'
url: https://www.emergentmind.com/topics/findmuonworkchain
type: topic
---

# FindMuonWorkchain: Automated DFT+μ Workflow

FindMuonWorkchain is a top-level automated AiiDA workflow for performing first-principles muon site finding and interaction calculations using the DFT+$\mu$ framework, as described and implemented by Onuorah et al. [2408.16722]. It operationalizes the strategy of modeling the muon as a hydrogen impurity in density functional theory and encompasses the generation, relaxation, and post-processing of candidate muon stopping sites in arbitrary host materials, automating the complex sequence required for quantitative muon spin spectroscopy calculations.

## 1. Workflow Architecture and Stepwise Execution

FindMuonWorkchain is implemented within the aiida-muon plugin and coordinates the end-to-end DFT+$\mu$ protocol. The high-level orchestration involves two major components: supercell convergence (IsolatedImpurityWorkChain, imported from aiida-impuritysupercellconv) and muon site search, relaxation, and interaction evaluation (in FindMuonWorkchain proper).

The workflow executes as a seven-step pipeline:

1. **Initial Position Generation**: $N_0$ candidate interstitial muon positions are generated in the primitive cell using a regular grid scheme with user-customizable spacing $d_u$ (default: $1\ \text{\AA}$). Points within $1\ \text{\AA}$ of any host atom are discarded, and space-group symmetry analysis removes redundancies, yielding distinct starting sites.

2. **Supercell Convergence**: If not specified, IsolatedImpurityWorkChain is invoked to determine the minimal supercell size that renders boundary forces from the inserted muon negligible, using a force-difference recipe with a typical threshold $A_F = 1\times10^{-3}$ Ry/Bohr ($\approx 0.0257$ eV/\AA).

3. **Structure Preparation and Relaxation**: For each candidate site, a supercell is constructed and a H pseudopotential is placed at the specified fractional coordinate. Full structural relaxation—using aiida-quantumespresso’s PwBaseWorkChain or PwRelaxWorkChain—is performed for each initial configuration.

4. **Relaxation Filtering**: If fewer than $60\%$ of relaxations converge, the protocol aborts.

5. **Site Clustering and Symmetry Analysis**: Relaxed structures are analyzed to identify symmetry-inequivalent muon sites based on distance ($A_d$, $0.5\ \text{\AA}$) and energy ($A_s$, $0.05$ eV) tolerances, with additional magnetic-symmetry expansion for magnetic hosts.

6. **Spin-Polarized SCF and Contact Field Evaluation** (Optional): Spin-polarized self-consistent runs are performed for each unique relaxed configuration, extracting the Fermi-contact field $B_c$ from the computed spin density.

7. **Dipolar Field Calculation**: The classical dipolar field $B_\mathrm{dip}$ at each site is computed via MUESR code, using a Lorentz-sphere summation of host nuclear or electronic moments.

All outputs—including relaxed supercell structures, total energies $E_i$, energy differences $\Delta E_i = E_i - E_0$, Fermi-contact fields $B_c(i)$, dipolar fields $B_\mathrm{dip}(i)$, and combined internal fields $B_u(i) = B_\mathrm{dip}(i) + B_c(i)$—are persisted in the AiiDA database [2408.16722].

## 2. Algorithms for Muon Site Identification and Supercell Convergence

Candidate muon sites are generated on a uniform grid: for lattice vectors $a, b, c$ and grid spacing $d_u$, the number of points along direction $i$ is $n_i = \lfloor a_i / d_u \rfloor$. Site exclusion proceeds by removing points within $1\ \text{\AA}$ of any host atom, and symmetry reduction is performed with space-group analysis, resulting in $N_0$ inequivalent candidates.

Supercell convergence is ensured via the IsolatedImpurityWorkChain. The method iteratively increases the supercell size until the muon-induced force perturbation at the boundary (modeled using a H pseudopotential at a generic interstitial) drops below $A_F$. At each iteration, the procedure:

- Inserts a H atom at a selected interstitial site.
- Calculates forces with and without the impurity by DFT-SCF.
- Fits the force difference $\Delta F_i$ vs. distance to an exponential decay, $\Delta F_0 \exp(-r_i/\lambda)$.
- Accepts the supercell if the maximum remaining $\Delta F_i \leq A_F$ **and** the maximal boundary distance exceeds $\lambda \ln(\Delta F_0/A_F)$.

If convergence is not achieved within $max\_iter$, the workflow exits with an explicit error [2408.16722].

## 3. Computational Settings and Site Post-processing

The workchain employs Quantum ESPRESSO via aiida-quantumespresso for all DFT tasks. Pseudopotential selection defaults to SSSP PBE efficiency v1.3, with typical planewave cutoffs of 60 Ry (PW) and 480 Ry (charge). The $k$-point mesh spacing defaults to $0.30\ \text{\AA}^{-1}$ and smearing is Gaussian with $\sigma = 0.01$ Ry. Relaxations proceed until all atomic forces are less than $1\times10^{-3}$ Ry/Bohr; SCF energy convergence is set to $1\times10^{-6}$ Ry.

Site clustering reflects a multi-stage protocol:

- Pairs of sites within $A_d$ and $\Delta E < A_s$ are reduced, keeping the lower-energy configuration.
- Pymatgen’s SpacegroupAnalyzer distinguishes crystal symmetry-equivalent sites within $A_d'$ ($0.05~\text{\AA}$) and $A_s'$ ($0.05$ eV).
- For magnetic hosts, candidate sites are expanded over the magnetic supercell, with re-queueing of missing inequivalent relaxations.

## 4. Interaction Calculations: Dipolar and Hyperfine Fields

FindMuonWorkchain supports rigorous evaluation of both classical dipolar and electronic hyperfine fields at muon sites.

- **Dipolar Field**: For $N$ host magnetic moments $m_i$, the classical dipolar field at the muon site $\mathbf{r}_\mu$ is:
  $$
  B_\text{dip}(\mathbf{r}_\mu) = \frac{\mu_0}{4\pi} \sum_{i=1}^N \left[ \frac{3 (\mathbf{r}_i \cdot m_i) \mathbf{r}_i}{r_i^5} - \frac{m_i}{r_i^3} \right]
  $$
  where $\mathbf{r}_i$ is the displacement vector from the muon to each $m_i$. Implementation utilizes MUESR for a Lorentz-sphere summation over all relevant moments.

- **Fermi-Contact (Isotropic Hyperfine) Field**: The Fermi-contact field is extracted as:
  $$
  B_c = \frac{2\mu_0}{3} \mu_B \rho_s(\mathbf{r}_\mu)
  $$
  where $\rho_s = \rho_{\uparrow} - \rho_{\downarrow}$ is the spin density at the muon site.

- **Anisotropic Hyperfine Tensor**: Although the full tensor is not exhaustively implemented in the primary workflow, its DFT expression is:
  $$
  A_{ij} = \frac{\mu_0}{4\pi} \gamma_e \gamma_\mu \hbar \iint \left[ \frac{3 r_i r_j}{r^5} - \frac{\delta_{ij}}{r^3} \right] \rho_\text{spin}(\mathbf{r})\, d^3r + 2\mu_0/3\, \gamma_e \gamma_\mu \hbar\, \rho_s(0)
  $$
  *This suggests potential extension of the workflow to include full tensor evaluation when required.*

## 5. Input Schema, Software Infrastructure, and Example Invocation

Core inputs to FindMuonWorkchain are provided as Python data objects:

- `structure` (AiiDA StructureData, e.g., from CIF)
- `magnetic_structure` (optional, mCIF or AiiDA MagneticStructureData)
- `du` (float, grid spacing, default $1.0\ \text{\AA}$)
- `charged_supercell` (Bool: charged or neutral muon)
- `hubbard` and `custom_hubbard` (Bool and Dict: DFT+U control and manual $U$ values)
- Code labels for Quantum ESPRESSO (`pw.x`) and MUESR

The workchain interfaces with three main AiiDA computational elements:

| Plugin/WorkChain            | Role                                                      | Key Inputs/Outputs                                  |
|-----------------------------|-----------------------------------------------------------|-----------------------------------------------------|
| IsolatedImpurityWorkChain   | Supercell convergence                                     | structure, force threshold $\rightarrow$ SC, matrix |
| PwBaseWorkChain / PwRelaxWC | DFT structural relaxation                                | SC structure, pseudo, cutoffs $\rightarrow$ energies, forces |
| calcfunction muesr_dipolar  | Dipolar field evaluation                                 | relaxed structure, mag. config $\rightarrow$ $B_\text{dip}$ |

*Editor's term*: "SC" = supercell; "PW" = plane wave.

Typical user invocation can occur in Python:
```python
from aiida import load_profile
from aiida.orm import StructureData
from aiida_muon.workflows import FindMuonWorkchain

structure = StructureData().get_or_create_from_cif('LaCoPO.cif')
inputs = {
    'structure': structure,
    'charged_supercell': Bool(True),
    'hubbard': Bool(True),
    # code labels, pseudo_family, resources, metadata…
}
result = run(FindMuonWorkchain, **inputs)
```
or from the command line:
```bash
verdi run run_aiida_workflow.py --entry_point aiida_muon.find_muon FindMuonWorkchain \
    structure=@LaCoPO.cif charged_supercell=true hubbard=true
```
[2408.16722]

## 6. Validation and Performance Across Test Cases

Validation is performed on diverse material prototypes:

- **LiF and bcc Fe**: The force-difference protocol reproduces benchmark supercell choices ($4\times4\times4$ for LiF, $3\times3\times3$ for Fe), in line with hyperfine-convergence tests.

- **CaF$_2$ (charged vs neutral)**: For Mu$^+$, the linear F–Mu$^+$–F state (bond length $1.13\ \text{\AA}$) emerges as lowest energy in a $3\times3\times3$ SC. Neutral Mu$^0$ converges to the cubic void center in $2\times2\times2$ SC. Displacement patterns match prior DFT+$\mu$ without ZPM correction.

- **La$_2$NiO$_4$ (AFM insulator)**: $2\times2\times1$ SC, $d_u = 1\ \text{\AA}$ yields 52 initial sites; $U(\mathrm{Ni}) = 6.4$ eV. Four muon–O bound sites (two apical, two planar) are recovered. Dipolar fields at apical sites ($\approx 260$ mT, $15$ mT) closely match experiment ($265.6$ mT, $14.8$ mT); the contact term is negligible. Demonstrates necessity for DFT+U in gap formation and $1.6\ \mu_B$ localization on Ni.

- **AV$_3$Sb$_5$ Kagome metals**: Identical $3\times3\times2$ supercells for K, Rb, and Cs hosts. The site p1 (between A and Sb layers) best models the Kubo–Toyabe ZF-$\mu$SR depolarization, as judged by second-moment $B_\text{dip}$ calculations.

- **LaCoPO (FM metal)**: $3\times3\times2$ SC, $U$(Co) $= 3.3$ eV, 20 initial positions yield four candidates. Site p1 ($1.47\ \text{\AA}$ from P) is lowest energy, $B_\text{dip} + B_c \approx 166$ mT (rescaled to $58.75$ mT via $m_\text{exp}/m_\text{DFT}$). Highlights partial self-consistency effects for itinerant magnets [2408.16722].

## 7. Significance and Context in Computational Muon Spectroscopy

FindMuonWorkchain enables automated, reproducible DFT+$\mu$ workflows for the computational quantification of muon stopping sites and their local fields, systematically linking experiment to first principles. A key advance is the fully automated supercell convergence, symmetry-aware clustering, and robust post-processing of nuclear and electronic fields at muon sites. This protocol extends compatibility to a wide variety of hosts, including complex insulators, metals, magnetic and nonmagnetic materials, providing direct validation against experimental $\mu$SR data. As such, it constitutes a core digital infrastructure for computational muon spin spectroscopy [2408.16722].

Source: https://www.emergentmind.com/topics/findmuonworkchain