.. _input-output:

================
Input and output
================

.. _io_files:

Input files
-----------

.. _io_cq_in:

Conquest_input
++++++++++++++
All necessary input parameters should be specified in the ``Conquest_input`` file,
including the names of the coordinate file and the ion files.  This
file controls the run; there are many sensible default values for
input parameters, but you should ensure that you understand what
they mean.  After a run, the full set of relevant input parameters
(whether specified by the user, or default, are available in the file ``input.log``).

The most common input tags are listed briefly here.
Full documentation can be found in :ref:`input_tags`.

* ``AtomMove.TypeOfRun`` takes ``static``, ``md``, ``sqnm``, ``cg``
* ``IO.Coordinates`` File name
* ``IO.Iprint`` 0-3 (controls amount of output)* ``DM.SolutionMethod`` diagon

  * ``Diag.MPMesh``   T/F
  * ``Diag.MPMeshX`` (and ``Y`` and ``Z``) N
  * ``Diag.GammaCentred`` T/F
* ``Grid.GridCutoff`` Energy in Ha (sets a grid spacing :math:`\delta x = \pi/\sqrt{2E}` for cutoff E in Ha; this spacing can also be set manually using ``Grid.GridSpacing`` in Bohr)
* ``AtomMove.NumSteps`` N
* ``AtomMove.MaxForceTol`` in Ha/bohr
* ``AtomMove.OptCell`` T/F (optimises simulation cell size)
* ``General.NumberOfSpecies`` N
* ``%block ChemicalSpeciesLabel`` Block specifying element number, mass and
  ion file name
* ``IO.FractionalAtomicCoords`` T/F
* ``Spin.SpinPolarised`` T/F
  
  * ``Spin.FixSpin`` T/F
  * ``Spin.Magn`` Difference between spin channel occupations
* ``minE.SCTolerance`` Fractional tolerance on magnitude of residual divided by number of electrons
* ``SC.KerkerPreCondition`` T/F (for Kerker preconditioning of SCF)
* ``SC.MaxIters`` N (maximum number of SCF iterations)
  
Go to :ref:`top <input-output>`

.. _io_ion:

Ion files
+++++++++

The ion files contain data on the different species being modelled:
valence charge, pseudopotentials, pseudo-atomic orbitals (PAOs) etc.  Full
details on how the PAOs are used as basis functions for CONQUEST can
be found in the manual section on :ref:`basis sets <basissets>`.  A
utility for generating these files is provided with CONQUEST, but Siesta ion
files can also be read.  The CONQUEST utility uses the
pseudopotentials generated by the `ONCVPSP`_ code (though note that to
generate new files for CONQUEST, you will need a small patch).

A set of input files for all elements in the `PseudoDojo`_ library for
the LDA, PBE and PBEsol exchange-correlation functionals is provided in the
directory ``pseudo-and-pao``.  This will allow you to generate ion
files for these elements easily.

The utility for generating ion files is called `MakeIonFiles`, and its
source code is found in the ``tools/BasisGeneration`` directory.  It
uses the same ``system.make`` file as CONQUEST, and following
compilation the executable will be moved to the ``bin`` directory.
The input file is ``Conquest_ion_input``, and the key parameters to be set for the
ion file generation are:

* ``General.NumberOfSpecies`` to specify number of species
* ``%block SpeciesLabels`` to specify what the species are
* In the species block (set with ``%block XX`` for species XX):
  
  * ``Atom.PseudopotentialFile`` to specify the input file for the ONCVPSP code
  * ``Atom.VKBFile`` to specify the file that CONQUEST needs to read
    (included in the library of inputs, and generally named ``XX.pot`` for species XX)
  * ``Atom.BasisSize`` to specify the size of the basis; at present
    this can take the values: ``minimal``; ``small``; ``medium``; and
    ``large``.

These are all included in the default input files.
Further fine-grained control can be applied to the basis functions;
this will be documented after the pre-release of CONQUEST.

.. _ONCVPSP: http://http://www.mat-simresearch.com
.. _PseudoDojo: https://www.pseudo-dojo.org/

Go to :ref:`top <input-output>`

.. _io_coords:
  
Coordinates
+++++++++++

The coordinates are specified in a separate file with relatively
simple format.  The coordinates can be specified in fractional form
(default) or cartesian (set the input tag ``IO.FractionalAtomicCoords T``).
Distance units can be Bohr radii (default) or Angstroms (set the input tag
``General.DistanceUnits`` to ``Ang``).  At present,
CONQUEST only handles *orthorhombic* unit cells.

The coordinate file is formatted as follows:

::
   
   a   0.0 0.0
   0.0 b   0.0
   0.0 0.0 c
   NAtoms
   x y z species MoveX MoveY MoveZ
   .
   .
   .

Note that the flags ``MoveX`` etc take values T/F and indicate whether
atoms are free to move in x, y and z, respectively.  The flag
``species`` is an integer, and selects based on species defined in the
:ref:`atomic specification <input_atomic_spec>` section of the
``Conquest_input`` file. 

Go to :ref:`top <input-output>`

.. _io_output:

Output files
------------

.. _io_output_main:

Main output
+++++++++++

By default, CONQUEST writes output to the ``Conquest_out`` file
(though the filename can be set with the parameter ``IO.OutputFile``,
and the flag ``IO.WriteOutToFile`` (T/F) selects output to file or
``stdout``).  This file contains all details of the calculation,
including energies, forces and information on the different stages of
the calculation.  The output verbosity is controlled by the
``IO.Iprint`` family of parameters, which allows different levels of
output detail to be set for different areas of the code.  For
production runs, we expect ``IO.Iprint 0`` to give sufficient detail;
``IO.Iprint 3`` provides a level of detail that would normally only be
needed for debugging.

Warnings from the calculation (including indications that the
convergence should be improved, and technical issues) are written to the
``Conquest_warnings`` file, which should be checked after each run.  The
warnings are also written to the output file at certain ``IO.Iprint``
levels.

Go to :ref:`top <input-output>`

.. _io_output_elec:

Electronic structure
++++++++++++++++++++

Different electronic structure outputs are available; in each case,
the key output flag is given.  Further output flags are described in :ref:`input_tags`.

  * Charge density
  * Band-resolved charge density (``IO.outputWF``)
  * Density of states (``IO.writeDOS``)
  * Atom-projected density of states (``IO.write_proj_DOS``)
  * Atomic charges, using the Mulliken approach (``IO.AtomChargeOutput``)

The Kohn-Sham eigenvalues are output in the ``eigenvalues.dat`` file.
The charge densities need post-processing to convert from the
standard output format to a file compatible with visualisation
(current supported formats include Gaussian CUBE file and OpenDX
files).

Note that Becke charges can be calculated if the following parameters
are set:

::
   
   SC.BeckeWeights T
   SC.BeckeAtomicRadii T
   IO.Iprint_SC 3

This method of output will be refined soon.

Go to :ref:`top <input-output>`

.. _io_output_atoms:

Atomic structure
++++++++++++++++

During structural relaxation and molecular dynamics, the atomic
structure at the end of each step is saved in the output file
``coord_next.dat``.  This is in the same format as the input.

Go to :ref:`top <input-output>`

.. _io_md:

Molecular dynamics
++++++++++++++++++

A molecular dynamics run will generate a number of additional plain text output
files:

  * ``md.stats`` --- summarises thermodynamic quantities at each steps
  * ``md.frames`` --- contains the complete physical state of the system (lattice
    parameters, atomic positions, velocities, forces, stress).
  * ``md.checkpoint`` --- data required for MD restart, namely atomic velocities
    and extended system variables.
  * ``md.positions`` --- Atomic coordinates saved at the moment of checkpointing
  * ``trajectory.xsf`` --- atomic coordinates save in .xsf format, which can be
    visualised using (for example) VMD, if ``AtomMove.WriteXSF`` is true..

Full details are available in :ref:`moldyn`.

Go to :ref:`top <input-output>`