Tutorial

After installation, PyZFS can be executed in two ways:

1. 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 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
   

   Example Jupyter notebooks can be found at examples/o2_qbox_xml/run.ipynb and examples/o2_qe_hdf5/run.ipynb.

2. Directly execute PyZFS. This approach works more smoothly with MPI.

   For serial execution, simply type the following command in the folder that contains 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 for calculations.

   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 replace the above commands with

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

   and

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

   Acceptable flags [–flags] are listed below. For detailed explanation see pyzfs/run.py.

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

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

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

     • qe: Quantum ESPRESSO (v6.1 only) save file. path should be the save folder that contains data-files.xml etc. Deprecated in favor of qeh5.

     • qbox: Qbox XML file.

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

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

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

   • 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 Quantum ESPRESSO HDF5 save file 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 save file is

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

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

See pyzfs/examples for examples of computing the ZFS tensor for the oxygen molecule and the nitrogen-vacancy (NV) center in diamond.

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.

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 up to 5000 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.