Use LMDS-SACS with CIF
######################

This section explains how to setup a YAML configuration file to CIF to run LMDZ-SACS.
For exaustive list of options, please refer to the :ref:`plugins documentation pages <Plugins in pyCIF>`

Model configuration
===================

LMDZ-SACS needs the :doc:`LMDZ/reg-ico model plugin </documentation/plugins/models/lmdz_ico>`

.. note::

    If ``pycif`` was installed in editable mode, there is no need to provide the path to the executable or the sources directory.
    The plugin will automatically find source directory that was cloned with CIF along side the ``pycif`` sources.

Minimal configuration
---------------------

Input arguments
~~~~~~~~~~~~~~~

* :ref:`grid <lmdz-reg-ico-grid>`: 
    the grid type, "regular" or "dynamico", will change the required domain plugin
* :ref:`auto-recompile <lmdz-reg-ico-auto-recompile>`:
    allow CIF to automatically compile LMDZ-SACS executables
* :ref:`compile-acc-target <lmdz-reg-ico-compile-acc-target>`:
    the device on which LMDZ-SACS will run, "gpu" or "multicore"
* :ref:`do_chemistry <lmdz-reg-ico-do_chemistry>`: 
    all the chemistry computation will be skipped if set to false
* :ref:`autoflush <lmdz-reg-ico-autoflush>`: 
    automatically flush the input files after each sub-period run

YAML example
~~~~~~~~~~~~

.. code-block:: yaml

    model:
      plugin:
        name: LMDZ
        version: reg-ico

      grid: dynamico

      auto-recompile: true
      compile-acc-target: gpu

      do_chemistry: false
      autoflush: true


Chemical scheme
===============

LMDZ-SACS needs a chemical scheme (even if chemistry is not enabled),
provided by :doc:`LMDZ/SACS chemistry plugin </documentation/plugins/chemistries/lmdz>`

Input arguments
--------------

* :ref:`active_species <lmdz-sacs-active-species>`:
    list of tracers to be transported in the model with their molar mass in g/mol.
    A parameter in the ``inicond`` component of the datavect plugin will be required for each emitted species
  
* :ref:`emitted_species <lmdz-sacs-emitted-species>`:
    list of tracers with emissions, by default all active species have emissions.
    A parameter in the ``flux`` component of the datavect plugin will be required for each emitted species
* :ref:`prescribed_species <lmdz-sacs-prescribed-species>`:
    list of prescribed species.
    A parameter in the ``precrconcs`` component of the datavect plugin will be required for each emitted species
  
* :ref:`prodloss_species <lmdz-sacs-prodloss-species>`:
    list of production/loss species.
    A parameter in the ``prodloss3d`` component of the datavect plugin will be required for each emitted species
  
* :ref:`deposition_species <lmdz-sacs-deposition-species>`:
    list of deposition species.
    A parameter in the ``deposition`` component of the datavect plugin will be required for each emitted species
  
* :ref:`reactions <lmdz-sacs-reactions>`:
    list of tracers to be transported in the model with their molar mass in g/mol
    
Reactions syntax
----------------

Reactions are defined by a string of the form ``"[reactants] -> [products] [rate_formula], [rate_terms]"``,
where ``[reactants]`` is composed of the reactives species names separated by ``"+"``,
``[products]`` is composed of the reactives species names separated by ``"+"`` with optional stoichiometric coefficients (for example ``"2*H2O"``), 
``[rate_formula]`` is one of the supported rate formula (see below), and ``[rate_terms]`` is a comma separated list of terms.

Reactants must be either in ``active_species`` or ``prescribed_species``.
Products that are not in ``active_species`` will be ignored.

Accepted rate formula
~~~~~~~~~~~~~~~~~~~~~

* **Constant rate** :math:`k = \mathrm{cste}`: ``k = [value]`` 
* **Simplified arrhenius** :math:`k(T) = A\exp\left( \frac{-B}{T} \right)`: ``k(T) = A*exp(-B/T)``
* **Complete arrhenius** :math:`k(T) = A\exp\left( \frac{-B}{T} \right) \left( \frac{300}{T} \right)^N`: ``k(T) = A*exp(-B/T)*(300/T)^N``
* **Relative pressure** :math:`k(P) = A\left( B + C \frac{P}{P_\mathrm{ref}} \right)`: ``k(P) = A(B+C*P/Pref)``

Photolysis rate formula
~~~~~~~~~~~~~~~~~~~~~~~

A photolysis reaction is defined by a string of the form ``"[reactant] + hv -> [products] J = [variable_name]"``,
where ``[reactant]`` is the reactive species, and ``[variable_name]`` the corresponding J rate variable name.


YAML example
------------

.. code-block:: yaml

    chemistry:
      plugin:
        name: LMDZ
        version: SACS
  
      active_species:
        CH4:
          molar_mass: 16.0425
        C2H6:
          molar_mass: 30.069
  
      emitted_species:
        - CH4
        - C2H6
  
      prescribed_species:
        - OH
        - O1D
        - Cl
  
      reactions:
        - CH4 + O1D -> PRODUCTS    k = 1.75e-10
        - CH4 + OH -> CH3 + H2O    k(T) = Aexp(-B/T), A=2.45e-12, B=1775
        - CH4 + Cl -> HCl + CH3    k(T) = Aexp(-B/T), A=7.1e-12, B=1270
        - C2H6 + OH -> H2O + C2H5  k(T) = Aexp(-B/T), A = 7.66e-12, B = 1020
        - C2H6 + Cl -> HCl + C2H5  k(T) = Aexp(-B/T), A = 7.2e-11, B = 70

Domain definition
=================

LMDZ-SACS domain is defined by the :doc:`LMDZ/regular domain plugin </documentation/plugins/domains/lmdz_reg>`
for the regular lat-lon grid or by the :doc:`LMDZ/dynamico domain plugin </documentation/plugins/domains/lmdz_ico>`
for the icosahedral grid.

YAML example for the regular grid
---------------------------------

.. code-block:: yaml

    domain:
      plugin:
        name: LMDZ
        version: regular
      dir: /path/to/LMDZ/grid/directory
      file: LMDZ_grid_144x143x79.nc


YAML example for the icosahedral grid
-------------------------------------

The LMDZ/dynamico domain plugin requires an additional input file to be provided.

.. code-block:: yaml

    domain:
      plugin:
        name: LMDZ
        version: dynamico
      dir: /path/to/LMDZ/grid/directory
      file: dynamico_grid_nbp80.nc
      file_vcoord: dynamico_vcoord_L79.nc
      file_mesh: dynamico_mesh_nbp80.nc