Ions input documentation
========================

Initialize geometry and pseudopotentials.


Used to initialize class :class:`qimpy.dft.ions.Ions`.

YAML template:
--------------

.. parsed-literal::

   :yamlparam:`qimpy.dft.ions.Ions:fractional`: :yamlkey:`yes`         :yamlcomment:`# Whether to use fractional coordinates for input/output.`
   :yamlparam:`qimpy.dft.ions.Ions:coordinates`: :yamlkey:`null`       :yamlcomment:`# List of [symbol, x, y, z, args] for each ion in unit cell.`
   :yamlparam:`qimpy.dft.ions.Ions:pseudopotentials`: :yamlkey:`null`  :yamlcomment:`# Pseudopotential filenames or filename templates.`

Parameters:
-----------

fractional
++++++++++

*Type:* :yamltype:`bool`, *Default:*  :yamlkey:`yes`

Whether to use fractional coordinates for input/output.
Note that positions in memory and checkpoint files are always fractional.

coordinates
+++++++++++

*Type:* :yamltype:`list` or :yamltype:`null`, *Default:*  :yamlkey:`null`

List of [symbol, x, y, z, args] for each ion in unit cell.
Here, `symbol` is the chemical symbol of the element, while
`x`, `y` and `z` are positions in fractional or Cartesian
coordinates for `fractional` = :yamlkey:`yes` or :yamlkey:`no` respectively.
Optional `args` is a dictionary of additional per-ion
parameters that may include:

    * `Q`: initial oxidation state / charge for the ion.
      This can be used to tune initial density for LCAO,
      or to specify charge disproportionation for symmetry detection.
    * `M`: initial magnetic moment for the ion, which would be a
      single Mz or [Mx, My, Mz] depending on if the calculation
      is spinorial. Only specify in spin-polarized calculations.
      This can be used to tune initial magnetization for LCAO,
      or to specify magnetic order for symmetry detection.
    * `v`: initial velocities [vx, vy, vz] in Cartesian coordinates.
    * Relaxation constraints: TODO

Ions of the same type (symbol) must be specified consecutively.

pseudopotentials
++++++++++++++++

*Type:* :yamltype:`string` or :yamltype:`list` of :yamltype:`string`, or :yamltype:`null`, *Default:*  :yamlkey:`null`

Pseudopotential filenames or filename templates.
Templates for families of pseudopotentials are specified by
including a $ID in the name which is replaced by the chemical
symbol of the element. The list of specified file names and
templates is processed in order, and the first match for
each element takes precedence.