.. _hco-examples:

##################################
Example scripts for use with HEMCO
##################################

.. _hco-examples-hcosa:

=====================================================
Generate a HEMCO_sa_Spec.rc file for HEMCO Standalone
=====================================================

The `HEMCO Standalone model
<https://hemco.readthedocs.io/en/stable/hco-sa-guide/intro.html>`_
reads species metadata (name, molecular weight, Henry's law constants)
from a text file named `HEMCO_sa_Spec.rc
<https://hemco.readthedocs.io/en/latest/hco-sa-guide/config-sim.html#hemco-sa-spec-rc>`_.
The default :file:`HEMCO_sa_Spec.rc` file corresponds to the
"standard" GEOS-Chem full-chemistry simulation and looks similar to this:

.. code-block:: none

   # List species below. For each species, the following entries must be given:
   # ID        : species ID
   # NAME      : species name
   # MW        : molecular weight (g/mol)
   # K0        : Henry constant at 298 K (M/atm, liquid over gas)
   # CR        : Henry temperature dependency (-d ln(KH)/d(1/T)
   # pKA       : acid dissociation constant
   #
   # NOTE: These are the species corresponding to the standard simulation!
   #
   #ID NAME           MW      K0                CR        PKA
   1   NO             30.00   0.000000E+00      0.00      0.00
   2   O3             48.00   0.000000E+00      0.00      0.00
   3   PAN           121.00   0.000000E+00      0.00      0.00
   4   CO             28.00   0.000000E+00      0.00      0.00
   5   ALK4           58.12   0.000000E+00      0.00      0.00
   6   ISOP           68.12   0.000000E+00      0.00      0.00

You may easily generate a :file:`HEMCO_sa_Spec.rc` corresponding to a
other GEOS-Chem simulations with the `GCPy
<https://gcpy.readthedocs.io>`_ example script
`make_hemco_sa_spec.py
<https://github.com/geoschem/gcpy/blob/main/gcpy/examples/hemco/make_hemco_sa_spec.py>`_.

First, activate the GCPy Python environment (unless you have installed
GCPy from PyPI, in which case no further action is needed).

.. code-block:: console

   $ conda activate gcpy_env
   (gcpy_env) $

You will see the :literal:`(gcpy_env)` prefix added to the command
prompt.

Next, run the :file:`make_hemco_sa_spec.py` script on the
`geoschem_species_metadata.yml <https://geos-chem.readthedocs.io/en/latest/gcclassic-user-guide/log-files.html#geos-chem-species-metadata-log>`_ file
generated by a GEOS-Chem simulation.  This file is typically created
in the :file:`OutputDir` folder of a GEOS-Chem run directory. 

.. code-block:: console
      
   (gcpy_env) $ python -m gcpy.examples.hemco.make_hemco_sa_spec /path/to/geoschem_species_metadata.yml

Move the :file:`HEMCO_sa_Spec.rc` file to your HEMCO standalone run
directory.  Then deactivate the GCPy Python environment.
   
.. code-block:: console

   (gcpy_env) $ conda deactivate
   $