=============================
Introduction and Setup
=============================


Introduction
============

This section introduces the reader to the setup and use of the EHRATM workflow from a user perspective, trying to avoid much underlying detail.  The goal in this section is to provide a series of examples, incremental in their complexity, that illustrate how to use an already-installed setup of the software components.  This is currently set up for a user who will have no interest in modifying any code.  Everything should be doable by running a pre-installed program, **ehratmwf.py**, giving it a workflow namelist (*wfnamelist*) argument.

I’m trying to describe this for the perspective of a user who is not **morton**, but I have no way to test that scenario, so there could be some unanticipated permission problems.

The paths in this documentation are set up for specific locations on devlan, for now.

Within this section we will

* Clone the git repository and checkout a snapshot branch
* Create a local working directory so that any output logs, etc. won’t go into the repository
* Set several environment variables to ensure that you are using a compatible Python 3 environment, and that you are set up to access a working distribution of the code

----

Setup
=====

For the purposes of this documentation, where we want some stability, a snapshot branch of the current develop branch has been made **snapshot/develop-YYYY-MM-DD**

The Python environment is not the standard one installed on devlan machines, so users will probably want to try using a custom Anaconda environment.   In the following, I describe the creation of a symlink and **PYTHONPATH** that should give you full and immediate access to the environment from my own account.  However, if you need to create this environment in your own account, the environment I’ve used on home machine plus devlan is defined in the repository (and the snapshot) in **misc/conda/ehratmv0.02.yml**.  If I remember correctly, the only non-standard module is *f90nml* (I also include *matplotlib* in the YML file, but it’s only used for some experimental things).  Alternatively, for the purpose of this introduction, the following environment settings will allow you all the access you need, without having to create a new conda environment

.. code-block:: bash

    $ git clone git@gitlabx.ctbto.org:ctbtosa/high-res-atm.git --branch snapshot/develop-2023-09-04
    $ cd high-res-atm


.. code-block:: bash

    $ mkdir ehratm-test1
    $ cd ehratm-test1

Although you could use the *ehratmwf.py* directly in the repository, in this case we’ll copy it to the working directory to make things easier

.. code-block:: bash

    $ cp <path-to-high-res-atm>/packages/ehratmworkflow/src/ehratmworkflow/ehratmwf.py .


As mentioned above, one can create and use the provided **ehratmv0.02.yml** Conda environment for Python, but in this case we’ll just make a link to a version already installed, and use that, calling it **epython3**.  In the long run, however, it’s probably best to have one’s own activated conda environment.

.. code-block:: bash

    $ ln -sf /dvlscratch/ATM/morton/anaconda3/envs/ehratmv0.02/bin/python3 epython3

Finally, we need to add the three repository packages to **PYTHONPATH**


.. code-block:: bash

    export PYTHONPATH=<path-to-high-res-atm>/packages/nwpservice/src:<path-to-high-res-atm>/packages/ehratm/src:<path-to-high-res-atm>/packages/ehratmworkflow/src

.. toctree::