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

.. role:: bash(code)
   :language: bash

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.

From an installation with only one CIF already installed in a git directory:

  - in the directory of the CIF, remove :bash:`*egg-info`
  - in :bash:`$HOME/.local/lib/python3.7/site-packages/`, remove :bash:`*pyCIF*egg*`
  - uninstall the CIF (in its directory, :bash:`python setup.py develop --user -u`)
  - always in the same first CIF directory, install the version chosen for debug/developments (:bash:`git pull` of the chosen version and :bash:`python setup.py develop --user`)
  - get the version for computing in a new directory: :bash:`git clone git@gitlab.in2p3.fr:satinv/cif.git $HOME/cif-for-prod/` and chose the right branch
  - in this new directory:

     a) in :bash:`setup.py`, line 64, change the name of the CIF (original: pyCIF)
     b) change the name of the directory where the sources are (original: pycif)
     c) run the usual install


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.