qmcpack/manual/additional_tools.tex

\chapter{Additional Tools}
\label{chap:additional_tools}
QMCPACK provides a set of lightweight executables that address certain
common problems in QMC workflow and analysis.  These range from conversion utilities between 
different file formats and QMCPACK (e.g. ppconvert and convert4qmc),  
(extract-eshdf-kvectors), to post-processing utilities (trace-density and qmcfinitesize), and to many others.  In this chapter, we cover the use cases, syntax, and features of all additional tools provided with QMCPACK.  

\section{Initialization Tools}
  \subsection{getSupercell}

\section{Post-Processing}
  \subsection{qmca}
    \texttt{qmca} is a versatile tool to analyze and plot the raw data from QMCPACK *.scalar.dat files.
    It is a python executable and part of the Nexus suite of tools.  It can be found in 
    \texttt{trunk/nexus/executables}. For more detail, see section \ref{sec:qmca}.
  \subsection{qfit}
    \texttt{qfit} is a curve fitting tool to obtain statistical error bars on fitted parameters.
    It is useful for DMC timestep extrapolation.  For more details, see section \ref{sec:qfit}.
  \subsection{qmcfinitesize}
    \texttt{qmcfinitesize} is a utility to compute many-body finite-size corrections to the energy.  It
    is a C++ executable that is built alongside the qmcpack executable.  It can be found in 
    \texttt{trunk/build/bin}

\section{Converters} 
\input{convert4qmc}    
  \subsection{pw2qmcpack.x}
    pw2qmcpack.x is an executable that converts PWSCF wavefunctions to QMCPACK readable 
    HDF5 format.  This utility is built alongside the Quantum Espresso post-processing utilities.
    This utility is written in Fortran90, and is distributed as a patch of the Quantum Espresso 
    source code.  The patch, as well as automated QE download and patch scripts, can be found in 
    \texttt{trunk/external\_codes/quantum\_espresso}.

pw2qmcpack used to be used in serial without problems in small systems and becomes a severe bottleneck for a large system.
Due to the large energy cutoff in the calculation with pw.x required by the pseudopotentials and the increasing sizes of systems we are interested in, one limitation of QE can be easily reached
that \texttt{wf\_collect=.true.} results in problems of writing and loading correct plane wave coefficients on disks by pw.x because of the 32bit integer issue. Thus, pw2qmcpack.x fails to convert the orbitals for QMCPACK.

Since Quantum ESPRESSO 5.3.0, the new converter has been fully parallelized to overcome that limitation completely.
By setting \texttt{wf\_collect=.false.} (by default \texttt{.false.} 6.1 and before and \texttt{.true.} since 6.2), pw.x doesn't collect the whole wave function into individual files for each k point but write one small file for each processor instead.
By just running pw2qmcpack.x in the same parallel setup (MPI tasks and k-pools) as the last scf/nscf calculation with pw.x,
the orbitals distributed among processors will first be aggregated by the converter into individual temporal HDF5 files for each k-pool and then merged into the final file.
In large calculations, users should benefit from a significant reduction of time in writing the wave function by pw.x thanks to avoiding the wavefunction collection.

pw2qmcpack has been included in the test suite of QMCPACK, see instructions about how to activate the tests in Sec.~\ref{sec:buildqe}.
There are tests labeled ``no-collect'' running the pw.x with setting \texttt{wf\_collect=.false.}.
The input files are stored at examples/solids/dft-inputs-polarized-no-collect.
The scf, nscf, pw2qmcpack runs are performed on 16, 12, 12 MPI tasks with 16, 2, 2 k-pools respectively.

  \subsection{ppconvert}
    \label{sec:ppconvert}
    ppconvert is a utility to convert pseudopotentials between different commonly used formats.
    It is a stand alone C++ executable that is not built by default but accessible via adding
    \texttt{-DBUILD\_PPCONVERT=1} to cmake and then typing \texttt{make ppconvert}.
    Currently it converts CASINO, FHI, UPF (generated by OPIUM), BFD, GAMESS formats to several formats
    including XML (QMCPACK) and UPF (Quantum ESPRESSO). See all the formats via \texttt{ppconvert -h}.
    For the output formats requiring Kleinman-Bylander projectors, the atom will be solved with DFT
    if the projectors are not provided in the input formats.
    This requires providing reference states and sometimes needs extra tuning for heavy elements.
    To avoid ghost states, the local channel can be changed via the \texttt{--local\_channel} option. Ghost state considerations are similar to those of DFT calculations, but may be worse if ghost states were not considered during the original pseudopotential construction.
    To make the self-consistent calculation converge, the density mixing parameter may need to be reduced
    via the \texttt{--density\_mix} option.

    Note that the reference state should include only the valence electrons.
    One reference state should be included for each channel in the pseudopotential.
    For example, for a sodium atom with a neon core, the reference state would be ``1s(1)''.
    \texttt{--s\_ref} needs to include a 1s state, \texttt{--p\_ref} needs to include a 2p state,
    \texttt{--d\_ref} needs to include a 3d state, etc. If not specified, a corresponding state with zero occupation is added.
    If the reference state is chosen as the neon core, setting empty reference states ``'' is techinically correct.
    In practice, reasonable reference states should be picked with care.
    For pseudopotentials with semi-core electrons in the valence, the reference state can be long.
    For example, Ti pseudopotential has 12 valence electrons. When using the neutral atom state,
    \texttt{--s\_ref}, \texttt{--p\_ref}, \texttt{--d\_ref} are all set as ``1s(2)2p(6)2s(2)3d(2)''.
    When using an ionized state, the three reference states are all set as ``1s(2)2p(6)2s(2)'' or ``1s(2)2p(6)2s(2)3d(0)''.
    Unfortunately, if the generated UPF file is used in Quantum ESPRESSO, the calculation may be incorrect due to the presence of ``ghost'' states. Potentially these can be removed by adjusting the local chanel, e.g. by setting \texttt{--local\_channel 1} which chooses the p channel as the local channel instead of d.
    For this reason, validation of UPF pseudopotentials is always required from the third row and strongly encouraged in general. For example, check that the expected ionization potential and electron affinities are obtained for the atom and check that dimer properties are consistent with those obtained by a Quantum Chemistry code or a plane-wave code that does not use the Kleinman-Bylander projectors.
\input{pseudopotentials}
%\section{Miscellaneous}
%  \subsection{extract-eshdf-kvectors}