Usage
=====

Preparing the input
-------------------

DGAmore takes as input the result of a DMFT calculation, which currently must be produced with w2dynamics, a
continuous-time quantum Monte Carlo solver based on the hybridisation expansion. A w2dynamics run yields both the
one-particle quantities and a two-particle output containing the four-point Green's functions. The two-particle
output first has to be converted into the format DGAmore expects. This is done by running the ``symmetrize_new.py``
script, which is installed alongside the main entry point; it prompts for the input and output file names and writes
only the density and magnetic spin components of the two-particle Green's function to the output file. The original,
unsymmetrised vertex file is not needed afterwards.

In addition to the processed two-particle file, a run requires a configuration file, which describes all run-time
parameters, as well as a Hamiltonian. The Hamiltonian can be supplied either as a real-space (Wannier) Hamiltonian or as a
momentum-space Hamiltonian generated by wien2wannier, and for interaction types that are not handled directly an
additional file specifying the local and non-local interaction can be provided.

Running a calculation
---------------------

The main entry point of the program is ``DGAmore.py``. Because it is added to the Python environment as a standalone
executable, it can be invoked by name without its full path. For single-core execution, which is mainly intended for
testing, run:

.. code-block:: bash

   DGAmore.py

For a parallel run with MPI, use:

.. code-block:: bash

   mpiexec -np <n_proc> DGAmore.py

Instead of ``mpiexec`` you may also use ``mpirun`` or, on SLURM-based clusters, ``srun``. The number of processes
``<n_proc>`` should be chosen according to the problem size and the available resources; note that increasing the
process count adds communication overhead and does not always improve performance.

Two optional command-line arguments are available. The ``-p`` argument specifies the directory containing the
configuration file, which is useful when several configuration files are kept in different directories; if it is not
given, the path defaults to the repository directory. The ``-c`` argument specifies the name of the configuration
file to load and defaults to ``dga_config.yaml``. As an example, the following command runs the code with eight MPI
processes and loads the configuration file ``my_config.yaml`` from ``/configs/``:

.. code-block:: bash

   mpiexec -np 8 DGAmore.py -p /configs/ -c my_config.yaml

On a SLURM-based cluster, a typical job submission script looks as follows:

.. code-block:: bash

   #!/bin/bash
   #SBATCH -N <n nodes>
   #SBATCH -J <some job name>
   #SBATCH --partition=<some partition>
   #SBATCH --qos=<some qos>
   #SBATCH --ntasks-per-node=<n proc>
   #SBATCH -t <time limit>
   #SBATCH -o log.txt
   #SBATCH -e log.txt

   # Load the necessary modules; here we activate the conda environment that
   # has the DGAmore package and its dependencies preinstalled.
   module purge
   source <path to miniconda>/miniconda3/bin/activate <your conda env>

   # Use MPI for parallelisation, so restrict each task to a single thread.
   export OMP_NUM_THREADS=1

   # Recommended on SLURM-based clusters:
   srun DGAmore.py -p "<path to config>" -c "<name of config>.yaml"

   # Alternatively, with mpirun or mpiexec:
   mpirun -np $SLURM_NTASKS DGAmore.py -p "<path to config>" -c "<name of config>.yaml"

The ``-o`` and ``-e`` options set the files for the job output and errors; here both are written to the same file,
but separate files may be used instead. The results of a completed run are written to a subdirectory of the output
folder, whose name encodes run-specific parameters such as the momentum-grid size and the frequency box.

The full set of run-time parameters is described on the :doc:`configuration` page.