.. _input_files_csv:

CSV File
========

For the .csv file to be read by :code:`ClayCode.builder`, the relative path needs to be referenced in the .yaml file. See :ref:`Input files: YAML <input_files_yaml>` more for information.
A CSV file is supplied with :code:`ClayCode` within the :code:`Tutorial` directory. The file (:code:`exp_clay.csv`) contains clay structures from the `Clay Mineral Society`_'s Source Clays. :cite:p:`Sourceclays, Clays`


File Structure
--------------

The file should be comprised of at least 3 columns:

- First column - :code:`sheet` with each row containing one of the following options:

   - :code:`T` for tetrahedral occupancies
   
   - :code:`O` for octahedral occupancies
   
   - :code:`I` for interlayer ion occupancies (if the total layer charge is non-zero)
   
   - :code:`C` for the tetrahedral, octahedral and total unit cell charges


- Second column - :code:`element` containing either:

   - Atom names

      - The oxidation state of clay atoms can be specified by adding the charge after the element name (e.g. Fe2)
      - If the specified atom is not supported by :code:`ClayFF.ff`, :code:`ClayCode.builder` will try to assign it to a supported atom of same charge and re-assign the occupancies

   - Whether the charge (:code:`sheet: C`) is for the :code:`T` layer, :code:`O` layer or the :code:`tot` total


- Subsequent columns - the clay name(s) with each row giving the corresponding value for that clay. One of these should match the :code:`SYSNAME` option in the corresponding .yaml file.

.. figure:: ../../images/csv.png
   :alt: CSV structure
   :align: center
   :figwidth: image

   The file structure for the CSV file.

Iron Oxidation State
~~~~~~~~~~~~~~~~~~~~~~

There is no need to specify how much of the total iron content is Fe\ :sup:`2+` or Fe\ :sup:`3+` if at least two
charge values are given (:code:`T` layer, :code:`O` layer or the :code:`tot` total). :code:`ClayCode.builder` will
determine the iron content splitting based on these values.


Rules
------

Occupancies:
~~~~~~~~~~~~

- Tetrahedral (:code:`T`) unit cell occupancies should sum to **4** for each sheet

- Dioctahedral (:code:`O`) unit cell occupancies should sum to **4** for each sheet

- Trioctahedral (:code:`O`) unit cell occupancies should sum to **3** for each sheet

For example, a dioctahedral 2:1 clay (TOT) should have 8 tetrahedral occupancies and 4 octahedral occupancies

Experimental stoichiometries do not necessarily sum up to integer occupancies. :code:`ClayCode.builder` will first process the target composition such that the occupancies match those expected for the specified unit cell type.


Interlayer Ions
~~~~~~~~~~~~~~~~~~

- Interlayer ions will be added to compensate the total charge imbalance resulting from :code:`T` and :code:`O` sheet substitutions

- The sum of all ion contributions should be **1**

- Only ion species of the opposite sign to the layer charge will be considered

Example File
--------------

For the :ref:`Nontronite tutorial <non_tutorial>` clays NAu-1 and NAu-2, the CSV file would be written as follows:

.. table::
   :widths: auto

   ===== ======= ====== ======
   sheet element NAu-1  NAu-2
   ===== ======= ====== ======
   T     Si        6.98   7.55
   T     Al        0.95   0.16
   T     Fe3       0.07   0.29
   O     Al        0.36   0.34
   O     Fe        3.61   3.54
   O     Mg        0.04   0.05
   I     Ca       0.525   0.36
   C     T       \-1.02 \-0.45
   C     O       \-0.03 \-0.27
   C     tot     \-1.05 \-0.72
   ===== ======= ====== ======

.. _`Clay Mineral Society`: https://www.clays.org

.. bibliography::
   :style: plain
   :filter: False

   Sourceclays
   Clays