.. _user_guide:

Using ClayCode
=================

The package comes with the required data files to construct the clay structures. For more information on the files and what they contain see the :ref:`data files guide <data_files>`.

Input Parameters
----------------

The target clay composition should be specified in .CSV format. For each clay listed this should contain the reduced unit cell structure including:

- partial atomic occupancies 
- charge balancing ions
- layer charges

See full details in :ref:`Input files: CSV <input_files_csv>`.

It is also possible to supply the clay composition within the .YAML input only. See the :ref:`Pyrophyllite tutorial <pyro_tutorial>` for an example.

The system specification for the set-up should be given in .YAML format. The required parameters are:

- :code:`OUTPATH`: the output directory path
- :code:`SYSNAME`: the clay system name as given in the .csv file
- :code:`CLAY_COMP`: the filepath for the .csv file
- :code:`CLAY_TYPE`: the unit cell type

For the full details of the parameters see :ref:`Input files: YAML <input_files_yaml>`.


ClayCode.builder
-----------------

This module builds clay models based on average target occupancies for a specified unit cell type.

:code:`ClayCode.builder` will match a combination of differently substituted unit cells to fit the average target occupancies specified by the user (Figure 1). These clay sheets are then stacked with interlayer sheets, the box extended and solvated and then the system is energy minimised using GROMACS (Figure 2).

.. figure:: ../images/sheets.png
   :alt: clay sheet building from unit cells
   :align: center
   :figwidth: image

   Figure 1. The clay sheet generation workflow

.. figure:: ../images/box.png
   :alt: clay model assembly workflow
   :align: center
   :figwidth: image

   Figure 2. The clay model assembly workflow

Usage
~~~~~

:code:`ClayCode.builder` can be run using:

.. code-block:: bash
   
   ClayCode builder -f path/to/input_Clay.yaml
   

The arguments accepted for :code:`builder` are:

- :code:`-f`: the filepath for the system specification .YAML file
- :code:`-comp`: the filepath for the clay composition .CSV file
- :code:`--manual_setup`: to run builder in interactive mode

Information on the output files can be found :ref:`here <output_files>`.


ClayCode.siminp
----------------

Coming soon!