########################
Miscellaneous hints
########################

Debugging hints
----------------

Insert an interactive session within the code: the CIF will run till this point and then provide a prompt to the user. Use the two following lines:

.. code-block:: python

  import code
  code.interact(local=dict(locals(), **globals()))

You are then in a python command-line environment at this point in the code e.g. all variables known at this point are accessible. To get back to the automatic running, ctrl-D XXXTO CHECKXXX


Inputs of a CTM
----------------
 In the plugin dedicated to the model, in :bash:`plugins/models/the_model`, :bash:`ini_mapper` lists many dictionnaries used by the_model. Among them are the dictionnaries used for types or groups of inputs. Each dictionnary has a list of keys with the names of the input variables to finally write in the input files (done by the :bash:`write.py` function of the default plugin for each input type for the_model).

Example: for a CTM with emitted species, 
  
.. code-block:: python

    emis = {
      ("flux", s): dict_surface
      for s in model.chemistry.emis_species.attributes
    }

so that the dictionnay contains the list of emitted species as retrieved from information obtained previously, here in the chemical scheme's relevant file.

To add a type of inputs, add the definition of the matching dictionnary and add it to the inputs' list.

Example: for a CTM with 5 types of inputs,
  .. code-block:: python

     mapper["inputs"].update(
        {**emis, **inicond, **prescrcond, **prodloss3d, **photj})


It may be required to treat inputs which are not (or should not) be accessible to users e.g. mandatory variables never to be modified.

Example: for LMDz, the chemistry data must include pressure "pmid" and temperature "temp" fields.

In this case, the keys of the matching dictionnary must be explicitely hard-written in :bash:`ini_mapper`.

Example: for a CTM with chemical inputs, some of which depend on the chemical scheme chosen by the user and others are mandatory,
  .. code-block:: python
    
    # list of Js from chemical scheme + 2 mandatory variables   
    list_var = [ j[1][1] for j in model.chemistry.photo_rates.iterrows() ]+ [ 'pmid', 'temp' ]
    # make a dictionnary out of it
    photj = {
        ("kinetic", l): dict_ini
         for l in list_var
    }

To simply access a dictionnary, declare it in :bash:`ini_mapper` e.g. "model.photj = photj"

Running two versions of the CIF
--------------------------------

It can be useful to install a version of the CIF for running simulations while working on developments in another version simultaneously.

This can be done by installing an alternative version of the CIF in a `Python virtual environment <https://docs.python.org/3/library/venv.html>`_

* Get the code for the CIF version you want to install in a new directory, here :bash:`cif-bis` (two options):

  * Copy your CIF directory: :bash:`cp -r cif/ cif-bis/`
  
  * Clone the CIF repository: :bash:`git clone git@gitlab.in2p3.fr:satinv/cif.git cif-bis` (and checkout the desired branch/commit)

* Create a Python virtual environment: :bash:`python -m venv env-cif-bis`. Here :bash:`env-cif-bis` is the virtual environment directory (you can choose any directory name or location)

* Activate the virtual environment: :bash:`source env-cif-bis/bin/activate`. Now the commands :bash:`python` and :bash:`pip` refer to the virtual environment in :bash:`env-cif-bis` (at any point, to deactivate the virtual environment and go back to the usual python installation, use the command :bash:`deactivate`)

* Install the alternative CIF version in the activated environment: :bash:`cd cif-bis`, :bash:`pip install -e .`

You now have two versions of :bash:`pycif` installed, one supposedly in your main python installation, and a new one in your :bash:`env-cif-bis` virtual environnement.

To use the new :bash:`pycif` version, you need to activate the virtual environment first:

.. code-block:: bash

  source env-cif-bis/bin/activate
  python -m pycif some-config-file.yaml
  deactivate # Not strictly necessary 

.. note::

  You an check if everything went as intented by checking to which file the new :bash:`pycif` refers:

  Activate the virtual environment (if not already activated): :bash:`source env-cif-bis/bin/activate`.
  Then run :bash:`python` and do:

  .. code-block:: python

    >>> import pycif
    >>> pycif.__file__
    '/some/path/pycif/__init__.py'

  The printed path should be in your **virtual environment directory** or in the **new CIF directory** (:bash:`cif-bis` in the example above) if you installed  :bash:`pycif` in editable mode (with :bash:`pip install -e .`)

Quick check of a datastore file
--------------------------------
To make a quick check in interctive mode of a CIF monitor file, launch a python or an ipython session and import the required plugins as in the following example:

.. code-block:: python

  from pycif.utils.datastores import dump
  ds = dump.read_datastore('monitor.nc')


The datastore file, here monitor.nc, is stored as a dataframe, here ds.