.. _user-section:

Input file sections
===================

The |pyretis| input file described in detail
in :ref:`the user guide <user-guide-input-structure>`. The short version is:

1. The input file is organised into ``sections`` where ``keywords`` are given values:

   .. code-block:: rst

       Section Title
       -------------
       keyword = value

2. Comments are marked with a ``#``.

3. Input is in general **not** case-sensitive **unless** you are
   referring to **files** and **Python classes**.

.. toctree::
    :maxdepth: 1
    :hidden:

    simulation.rst
    system.rst
    box.rst
    particles.rst
    forcefield.rst
    potential.rst
    engine.rst
    orderparameter.rst
    retis.rst
    tis.rst
    initial.rst
    output.rst
    unitsystem.rst
    analysis.rst

Below, we list the different sections that you can make use of
in order to define your simulation:

.. |sec_simulation| replace:: :ref:`simulation <user-section-simulation>`

.. |sec_system| replace:: :ref:`system <user-section-system>`

.. |sec_box| replace:: :ref:`box <user-section-box>`

.. |sec_particles| replace:: :ref:`particles <user-section-particles>`

.. |sec_forcefield| replace:: :ref:`forcefield <user-section-forcefield>`

.. |sec_potential| replace:: :ref:`potential <user-section-potential>`

.. |sec_engine| replace:: :ref:`engine <user-section-engine>`

.. |sec_orderparameter| replace:: :ref:`orderparameter <user-section-orderparameter>`

.. |sec_retis| replace:: :ref:`retis <user-section-retis>`

.. |sec_tis| replace:: :ref:`tis <user-section-tis>`

.. |sec_path| replace:: :ref:`initial-path <user-section-initial-path>`

.. |sec_output| replace:: :ref:`output <user-section-output>`

.. |sec_usystem| replace:: :ref:`unit-system <user-section-unit-system>`

.. _table-sections:

.. table:: Input sections for defining simulations.
   :class: table-hover table-striped

   +----------------------+---------------------------------------------------+
   | Section              | Usage                                             |
   +======================+===================================================+
   | |sec_simulation|     | For defining the simulation we are going to run.  |
   +----------------------+---------------------------------------------------+
   | |sec_system|         | For defining system properties.                   |
   +----------------------+---------------------------------------------------+
   | |sec_box|            | For defining a simulation box.                    |
   +----------------------+---------------------------------------------------+
   | |sec_particles|      | For defining the initial state of particles.      |
   +----------------------+---------------------------------------------------+
   | |sec_forcefield|     | For defining a forcefield.                        |
   +----------------------+---------------------------------------------------+
   | |sec_potential|      | For defining potential functions to use in the    |
   |                      | force field.                                      |
   +----------------------+---------------------------------------------------+
   | |sec_engine|         | For defining the simulation engine.               |
   +----------------------+---------------------------------------------------+
   | |sec_orderparameter| | For defining the order parameter.                 |
   +----------------------+---------------------------------------------------+
   | |sec_retis|          | For defining settings for a RETIS simulation.     |
   +----------------------+---------------------------------------------------+
   | |sec_tis|            | For defining settings for a TIS simulation.       |
   +----------------------+---------------------------------------------------+
   | |sec_path|           | For defining how the initial path is generated.   |
   +----------------------+---------------------------------------------------+
   | |sec_output|         | For defining output settings.                     |
   +----------------------+---------------------------------------------------+
   | |sec_usystem|        | For defining custom unit systems.                 |
   +----------------------+---------------------------------------------------+

In addition, an analysis can be defined using:

.. |sec_analysis| replace:: :ref:`analysis <user-section-analysis>`

.. _table-sections-analysis:

.. table:: Input sections for defining an analysis.
   :class: table-hover table-striped

   +----------------------+---------------------------------------------------+
   | Section              | Usage                                             |
   +======================+===================================================+
   | |sec_analysis|       | For defining an analysis.                         |
   +----------------------+---------------------------------------------------+

Notation for describing keywords
--------------------------------

Each keyword entry is shown as:

.. code-block:: text

   keyword = DATA-TYPE

where ``keyword`` is the input-file key and ``DATA-TYPE`` is the kind of value
accepted by that key. The paragraph below each keyword explains what it controls.
When a keyword has a default value, the default is listed directly below the
description.

Example:

.. code-block:: text

   task = string

   Selects the simulation task to run.

   Default:
     md

The data types used in the keyword reference are listed below.


.. _table_data_types:

.. table:: The different data types encountered in |pyretis|.
   :class: table-hover table-striped

   +-------------------+--------------------------+-----------------------------------+
   |  *DATA-TYPE*      | Description              | Example                           |
   +===================+==========================+===================================+
   | *string*          | A string of characters,  |  ``task = retis``                 |
   |                   | i.e. text.               |                                   |
   +-------------------+--------------------------+-----------------------------------+
   | *integer*         | An integer.              | ``steps = 100``                   |
   +-------------------+--------------------------+-----------------------------------+
   | *float*           | A floating-point number  | ``timestep = 0.002``              |
   +-------------------+--------------------------+-----------------------------------+
   | *boolean*         | A boolean value          | ``shift = True``                  |
   |                   | (``True`` or ``False``). |                                   |
   +-------------------+--------------------------+-----------------------------------+
   |  *dictionary*     | A Python dictionary.     | ``mass = {'Ar': 1.0}``            |
   +-------------------+--------------------------+-----------------------------------+
   | *list*            | A Python list.           | ``interfaces = [0.1, 0.2, 0.3]``  |
   +-------------------+--------------------------+-----------------------------------+
   | *tuple*           | A Python tuple.          | ``index = (7,8)``                 |
   +-------------------+--------------------------+-----------------------------------+
   | *None*            | This represents an       |                                   |
   |                   | optional value           |                                   |
   +-------------------+--------------------------+-----------------------------------+