PyFRSOC: A Python package for first-principles spin-orbit coupling and zero-field splitting calculations

PyFRSOC is a Python package for first-principles calculations of spin-orbit coupling (SOC) matrix elements and SOC-induced zero-field splitting (ZFS) tensors using fully relativistic pseudopotentials and wavefunctions from periodic plane-wave density functional theory calculations. Current workflows are built around Quantum ESPRESSO data and support direct SOC matrix construction, sum-over-states ZFS calculations, and Sternheimer-based approaches for open-shell molecules and spin defects in solids.

The methodological background is connected to the Pederson-Khanna framework for magnetic anisotropy [1], related first-principles treatments of ZFS including hybrid-functional formulations [2], and recent PyFRSOC applications and ongoing development [3, 4]. If you use PyFRSOC in published work, please cite the relevant references below.

References

1. J. R. Pederson and S. N. Khanna, Phys. Rev. B 60, 9566 (1999).
2. Frank Neese, J. Chem. Phys. 127, 164112 (2007).
3. Yu Jin, Jinsoo Park, et al., Phys. Rev. Lett. 135, 036401 (2025).
4. Yu Jin, Jinsoo Park, and Giulia Galli, in preparation (2026).

Documentation

Documentation is currently organized around the tutorial notebooks and example workflows below.

The main entry points are:

• Tutorials: doc/tutorials/
• End-to-end examples: examples/
• Example-specific folders:
  • examples/example001/: SOC matrix elements for NV(-) in diamond
  • examples/example002/: SOC-induced ZFS for NiV(0) in diamond via the sum-over-states approach
  • examples/example003/: SOC-induced ZFS for NiV(0) in diamond via the Sternheimer approach
  • examples/example004/: SOC-induced ZFS for AsF molecule via the Sternheimer approach with a hybrid functional

Installation

Required packages

Core Python dependencies:

• numpy
• scipy
• mpi4py

Optional packages:

• cupy for GPU acceleration
• gpustat for GPU usage logging

Simple installation

Create and activate a Python environment, then install the package:

python -m pip install .

For editable development installs:

python -m pip install -e .

MPI-GPU installation on NERSC Perlmutter

An example setup on NERSC Perlmutter is:

module load PrgEnv-gnu cray-mpich cudatoolkit craype-accel-nvidia80 python
conda create -n pyfrsoc python -y
conda activate pyfrsoc
MPICC="cc -shared" pip install --force --no-cache-dir --no-binary=mpi4py mpi4py
LDFLAGS="$CRAY_CUDATOOLKIT_POST_LINK_OPTS" NVCC="nvcc $CRAY_CUDATOOLKIT_INCLUDE_OPTS" CC=cc CXX=CC pip install cupy
python -m pip install .

Running calculations

The easiest way to get started is to run one of the example drivers from its corresponding directory.

Parallelization modes

PyFRSOC currently supports two MPI decomposition modes in the Sternheimer workflows:

• decomp_mode="pw": distributes plane-wave data across MPI ranks
• decomp_mode="band": distributes bands across MPI ranks

For band decomposition, the currently supported band layouts are:

• band_distribution="contiguous"
• band_distribution="block-cyclic"

These options are available in the Sternheimer workflows, including the hybrid-functional workflow.

Restricting the SOC Hamiltonian to selected atoms

PyFRSOC can restrict the SOC Hamiltonian to a selected subset of atoms through the atom_list argument. The list is 0-indexed and follows the atom ordering in the input structure parsed from the Quantum ESPRESSO XML file.

If atom_list is omitted, all atoms are included. For example:

from pyfrsoc.compute_so_mat import soc_mat

solver = soc_mat(
    wfc_files,
    pp_files,
    atom_list=[0, 1, 5],
)

This option is available in the SOC matrix, sum-over-states, Sternheimer, and Sternheimer hybrid-functional workflows.

Quantum ESPRESSO .cube precision for Sternheimer workflows

The Sternheimer solvers require local potentials exported from Quantum ESPRESSO in .cube format. If higher numerical accuracy is needed, it can be helpful to increase the output precision in the Quantum ESPRESSO cube writer.

In PP/src/cube.f90, the following optional change can be applied before rebuilding Quantum ESPRESSO:

! original
WRITE(ounit,'(6E13.5)') (rho(i1,i2,i3),i3=1,nr3)

! higher-precision output
WRITE(ounit,'(6E23.15)') (rho(i1,i2,i3),i3=1,nr3)

This patch is optional, but it may improve the accuracy of Sternheimer calculations that depend on .cube local-potential files.

Example runs

SOC matrix elements:

cd examples/example001
python compute_soc_mat.py

SOC-induced ZFS via the sum-over-states approach:

cd examples/example002
python compute_dso.py

SOC-induced ZFS via the Sternheimer approach:

cd examples/example003
python compute_dso_band.py

SOC-induced ZFS via the Sternheimer hybrid-functional workflow:

cd examples/example004
python compute_dso_band.py

On MPI systems, replace the direct Python launch with your scheduler or MPI launcher as needed. For example:

mpirun -n 4 python compute_dso.py

or on Slurm systems:

srun -n 4 -u python compute_dso.py

CPU and GPU control

PyFRSOC uses the GPU backend by default when cupy is available. To disable GPU usage and force the CPU backend, set:

export PYFRSOC_USE_GPU=0

To enable the GPU backend explicitly, set:

export PYFRSOC_USE_GPU=1

In MPI runs, ranks are assigned to GPUs automatically according to rank % num_gpus.

Authors

• Yu Jin (yjin@flatironinstitute.org)

Acknowledgments

This repository benefited from code cleanup, documentation editing, and development support assisted by OpenAI Codex.

Contact

For bug reports, feature requests, and usage questions, please use the GitHub issue tracker.

For direct correspondence, please contact yjin@flatironinstitute.org.