.. _tutorial:

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.

   .. code:: python

      >>> 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)

   .. code:: bash

      $ pyzfs [--flags]

   For parallel execution, use the following command

   .. code:: bash

      $ 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 :ref:`installation`). If one manually added the **PyZFS** directory to ``PYTHONPATH`` without installing it, one needs to replace the above commands with

   .. code:: bash

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

   and

   .. code:: bash

      $ 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

   .. code:: bash

      $ 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

   .. code:: bash

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