Documentation
------------------------


This is the documentation of the usage and expension of HERMES in combination with TM5-MP

---------------------
Overview
---------------------

What is HERMES?
HERMES is a tool which reads data from various, defined emission inventories and creates a emission input file for (in this case) TM5-MP.
It combines the different used inventories and gives the possibility to change the emissions by applying e.g. regional masks

How is the workflow?
0. If no valid preprocessor for the inventory is ready, you have to create one by yourself
1. Preprocess all emission to be used for all times to be used usig the preprocessor for each inventory
2. Design your EI_configuration.csv file
    This file contains all the inventories to be used splitted in their sectors
    Also masks are applied here
3. Run HERMES for this config file
    Future: run python script to run HERMES one by one for every line in config file to get multiple files per inventory
4. Link TM5-MP to the correct place of HERMES-emission files
5. un TM5-MP


-------------------
Installation on Aether
-------------------

On Aether (and probably other systems too) hermes is installed using 
    python setup.py install --user --record files.txt
While having loaded a conda module
The record of files is used for unistall
(There might be a better way)

-------------------
Editing config file
------------------

One of the key files of hermes is the config file, per default called hermes.conf
here one has to define the input and output paths as well as the domain set up

On Aether the needed emission dta is stored in /mnt/beegfs2/emis/HERMESv3, change data_path accordningly. More info on the data can be found in section preprocessor

The vertical description has to be replaced by a file fitting the needs of your model to use

Fot use with tm5 for two addition paths were added, the gph_data_path and the meteo_data_path. For the gph data make sure the directory is there, the files will be clacualted by need.
The meteo data path gives the paths for the reai or era5 (in the future) T and Q data (including sfcp), change this accordingly.

The cross table is the second important file to edit, change path to the file to be used, more info on this in the section cross table

normaly the paths in the emission inventory,but the p_speciation, files don't have to be change, for more info look into section cross table

for p_speciation please choose the profile corresponding to your model and chemical mechanism used (in tm5 version there is just one tm5 file at the moment)

-------------------
cross table
-------------------

The cross table links your configuration file to the emissions you want to use
Attention: per default all(!) lines of your cross table are combined into a single emission file, so if you e.g. use htap and cmip6 data, you will count emissions of both inventories. In the tm5 version this is updated to read comments, so using # you can comment signle lines to not have to edit the whole cross table everytime.

The cross table consists of many columns, please checl the official user guide for help: https://earth.bsc.es/gitlab/es/hermesv3_gr/-/wikis/examples/cross_table


-------------------
Preprocessors
------------------

The preprocessor have to be run to create suitable emission data for use with hermes from the offical emission datasets, a list of included inventories can be found here: https://earth.bsc.es/gitlab/es/hermesv3_gr/-/wikis/user_guide/emission_inventories

also included in the tm5 version is a preprocessor for cmip6 future data

please notice, that even if hermes officially runs using python 3, the preprocessors are based on python2 so far, therefore you can not run it using the default conda enviroment (sometimes it works anyways, but not garantueed for all settings). Therefore please use the model hemerv3gr instead, load it using

    module load hermesv3gr

Please also make sure to adapt the input and maybe output path the way needed! There is a gathered emission directory for hermes on beegfs2 (see in section cross table), but here we have to check how to deal with this in the future

--------------
Contact
-------------

If you have any questions please contact me (Sarah-Lena Meyer) for example via mail:
slmeyer@iup.physik.uni-bremen.de

