Tutorials

Examples of using PyZFS

See also the examples folder.

Overview

After installation, PyZFS can be executed in two ways:

1. Python library interface

Construct WavefunctionLoader and ZFSCalculation from within Python terminal or Jupyter notebook, and call ZFSCalculation.solve to perform the calculation.

An example Python script for computing the ZFS tensor for the oxygen molecule is shown below. path/to/o2.xml should be replaced by the path to the pyzfs/examples/o2_qbox_xml/o2.xml file in the PyZFS folder.

>>> from pyzfs.common.wfc.qboxloader import QboxWavefunctionLoader
>>> from pyzfs.zfs.main import ZFSCalculation
>>> wfcloader = QboxWavefunctionLoader(filename="/path/to/o2.xml")  # Construct wavefunction loader
>>> zfscalc = ZFSCalculation(wfcloader=wfcloader)  # Set up ZFS calculation
>>> zfscalc.solve()  # Perform ZFS calculation

After PyZFS is executed, the D tensor, its eigenvalues and eigenvectors are printed by the end of the output. The widely-used scalar D and E parameters are also printed. A zfs.xml file is generated that includes these information, facilitating parsing the results through scripts.

2. Command line interface

Directly execute PyZFS from the command line. This approach works more smoothly with MPI.

For serial execution, simply type the following command in the folder that contains the DFT wavefunction file(s)

$ pyzfs [--flags]

For parallel execution, use the following command

$ mpiexec [-n num_of_processes] pyzfs [--flags]

where num_of_processes is the number of processes. PyZFS distributes the calculations on a square grid of processes. If num_of_processes is not a square number, PyZFS will use the largest square number of processes smaller than num_of_processes.

Note that to use the above pyzfs command, one needs to install PyZFS through pip (see Installation). If one manually added the PyZFS directory to PYTHONPATH without installing it, one needs to use

$ python -m pyzfs.run [--flags]

and

$ mpiexec [-n num_of_processes] python -m pyzfs.run [--flags]

Acceptable flags [--flags] are listed below.

  • path: Working directory for this calculation. Python will first change the working dir before any calculations. Default is ..

  • wfcfmt: Format of wavefunctions. Default is qeh5. Supported options are:

    • qeh5: Quantum ESPRESSO (v6.x or v7.x) HDF5. path should contain the prefix.xml file and the prefix.save folder.

    • qe: Quantum ESPRESSO (v6.1 only). Deprecated.

    • qbox: Qbox XML.

    • gpaw: GPAW calculator (assumed to be finished).

    • cube-wfc: Cube files of (real) wavefunctions.

    • cube-density: Cube files of (signed) squared wavefunction. This option supports pp.x output with plot_num = 7 and lsign = .TRUE..

  • prefix: QE prefix. Only used if wfcfmt is qeh5.

  • filename: Name of the Qbox sample XML file that contains the wavefunctions. Only used if wfcfmt is qbox.

  • gpwfile: Name of the GPAW calculator. Only used if wfcfmt is gpaw.

  • ae: Boolean, whether all-electron (AE) reconstruction is performed. Default is False. Only used if wfcfmt is gpaw.

  • ae_reduce: Scale to reduce AE real-space grid. Default is 4. Only used if wfcfmt is gpaw.

  • fftgrid: FFT grid used. Default is wave. Supported options are:

    • density: The density grid is used for FFT.

    • wave: A reduced grid is used for FFT, which is computationally less expensive and is recommended for large-scale calculations.

  • memory: Controls whether certain intermediate quantities are kept in memory or re-computed every time. Supported options are high, low, and critical which keeps the decreasing amount of quantities in memory. Default is critical which costs least memory and is recommended for large-scale calculations.

An example execution command for the Quantum ESPRESSO HDF5 wfcfmt is

$ mpiexec pyzfs --wfcfmt qeh5 --prefix pwscf

where pwscf is the prefix used in the Quantum ESPRESSO calculation.

An example execution command for Qbox XML wfcfmt is

$ mpiexec pyzfs --wfcfmt qbox --filename gs.xml

where gs.xml is the XML file generated by Qbox.

Scalability

PyZFS can scale to thousands of MPI processes. Starting from version 2.0, further speedup can be achieved by using NVIDIA GPUs. The code has been applied to systems with thousands of valence electrons. For large calculations, typical walltime for a calculation is on the order of 12-24 hours on CPUs, and 1-2 hours on GPUs.

Spin decontamination

The accuracy of the computed ZFS can be affected by spin contamination in spin-polarized DFT calculations, where the Kohn–Sham states in the two spin channels have different energies and spatial distributions. Biktagirov et al. proposed a correction scheme that effectively cancels spin contamination errors, providing more accurate computation of ZFS tensors while reducing the dependence on the exchange-correlation functional employed in DFT calculations. See Correcting for spin contamination in zero-field splitting calculations for an example of applying this correction to a PyZFS calculation.