Yaml configuration
------------------

.. role:: bash(code)
   :language: bash

pyCIF can be entirely set up with a
`Yaml <http://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html>`__
file such as in the example below.
The Yaml configuration file structure is used to define, initialize and run the building blocks of pyCIF:
:doc:`Plugins <plugins/index>`.

General info about Yaml
........................

The basic idea of Yaml
syntax is that you can easily define a tree structure using ':' and
indentation, which would be automatically interpreted by Python.

Please note that Yaml is flexible with the keys it accepts for booleans.
The following keys will be automatically accepted as True or False:

y / Y / yes / Yes / YES / n / N / no / No / NO / true / True / TRUE /
false / False / FALSE / on / On / ON / off / Off / OFF

For instance, the following Yaml syntax:

.. code-block:: yaml

    root:
       branch1: grub
       branch2: [0, 1]
       branch3:
          subbranch0: some text
          subbranch1: 2004-01-01
          subbranch2: T

will be interpreted into the following Python dictionary:

.. code-block:: python

    {
    'root':
       'branch1': 'grub',
       'branch2': [0,1],
       'branch3':
          'subbranch0': 'some text',
          'subbranch1': datetime.datetime(2004, 01, 01),
          'subbranch2': True
    }

which is itself loaded into a pyCIF plugin automatically integrated with
other plugins and dependencies.

Further examples about the Yaml syntax can be found
`here <http://sweetohm.net/article/introduction-yaml.en.html>`__.

The initialized dictionary is then loaded as :doc:`Plugins <plugins/index>` for later use by pyCIF.


Yaml and pyCIF
........................

There is a minimal number of arguments mandatory to run a pyCIF simulations.
They are:

    1. :bash:`verbose`: the verbose level of the simulations.
       pyCIF uses the `logging <https://docs.python.org/3/library/logging.html>`__
       python package. Log instances are determined by the commands :bash:`info`,
       :bash:`debug` and :bash:`warning`

       Verbose levels corresponds to `levels in logging <https://docs.python.org/3/library/logging.html#logging-levels>`__:
        - :bash:`verbose = 0`:  debugging verbose. Includes the path to the python script were
          the log instance was called
        - :bash:`verbose = 1`:  debugging verbose, without extra information on the script path
        - :bash:`verbose = 2`:  only main information are displayed
        - :bash:`verbose > 2`:  only warnings are displayed

    2. :bash:`workdir`: directory were the pyCIF computations will be saved
    3. :bash:`logfile`: name of the logfile
    4. :bash:`datei` and :bash:`datef`: the start and end dates of the simulations

.. note::

    Please consult the page :doc:`here <../paths>` for details on how paths are handled in pyCIF.

The most basic Yaml file is thus:

.. literalinclude:: config_basic.yml
    :linenos:
    :language: yaml