Tutorial

After installation, PyZFS can be executed in two manners:

1. Construct WavefunctionLoader and ZFSCalculation loader 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 PyZFS directory to the 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 values are:

     • “qeh5”: Quantum Espresso HDF5 save file. path should contains “prefix.xml” and save folder.
     • “qe”: Quantum Espresso (v6.1) save file. path should be the save folder that contains “data-files.xml”, etc.
     • “qbox”: Qbox xml file.
     • “cube-wfc”: cube files of (real) wavefunctions (Kohn-Sham orbitals).
     • “cube-density”: cube files of (signed) squared wavefunction, this option is to support 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 = “qbox”.

   • fftgrid: FFT grid used. Supported values are “density” or “wave”. “density”: the density grid is used for FFT; “wave”: a reduced grid is used for FFT. Default is “wave”, 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 values 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 for 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 hundreds of MPI processes, and has been applied to systems with up to 3000 valence electrons. For large calculations, typical walltime for a calculation is on the order of 12-24 hours.