Installation

Instructions

This package is based on GitHub and Conda [1]. To begin, go to a clean folder on your computer where you want to do the install.

First clone the package:

git clone git@github.com:abukowski21/SAMI3-GITM-python.git

Checkout the ESMF branch:

git checkout -b esmf

Enter the directory:

cd SAMI3-GITM-python

Create a new conda[1] environment according to the requirements specified by this project:

conda env create -f python-env.yml && conda activate SAMI3-GITM

Note

Conda is not required, but it makes things easier. If you do not want to use conda, you can install the packages with pip or manually. To use pip:

pip install -r requirements.txt

This usage is not supported, so you may run into dependency issues doing this.

[1]

Additional information on conda can be found on their website at the Installation and Environment pages.

Installing ESMF

ESMF is required to run the interpolation code on this branch. This section of the documentation is a work in progress, so contact me with issues & questions.

ESMF (Earth System Modeling Framework) is a robust software suite designed to facilitate the communication between models. We are only using a tiny aspect so can cut some corners in the installation, but the software package is massive and care must be taken to ensure everything iscorrectly installed.

For complete details on how to install ESMF, see their documentation. I will provide a bit of information on the crucial steps, but this is by no means complete. The necessary pages in the documentation are the the quick start page and this page on more details on the installation specifics.

Note

The installation of ESMF is independent of the conda environment above. No need to put them in the same directory or keep the conda environment activated. I recommend installing ESMF without the conda environment active so there’s no confusion about which NetCDF and MPI libraries are being used.

We need to install ESMF with just the command line tools, howerver we need support for PIO, and NetCDF. Here are general instructions along with some tips. We will be following these instructions.

1. Ensure that a suitable version of ESMF is downloaded and uncompressed. Not all versions support 3D spherical interpolations in offline mode. I recommend version 8.4.0, but it is not required. Details can be found on the ESMF regridding page. You need to install a version that supports offline, 3D (spherical), bilinear interpolation.

2. Set the required environmental variables. These are: ESMF_DIR, ESMF_COMM, ESMF_COMPILER, ESMF_NETCDF, ESMF_PNETCDF, and ESMF_PIO. Other variables in the documentation can be set, but my testing has shown that these will work. These are only necessary during the install, no need to set them when you run the interpolation code.

   • ESMF_DIR is the path to the installation location

   • ESMF_COMM denotes if ESMF should be installed with support for MPI. Set this to the correct implementation of MPI that your system is using.

   • ESMF_COMPILER denotes the Fortran/C++ compiler that ESMF will be built with. typing make info shows which compiler & MPI impletation are currently planned on being used.

   • ESMF_NETCDF enables the ESMF command line tools to read NetCDF files from disk. This is required. See this link for more information, but usually this can be set to “nc-config” if the commands nc-config and nf-config run successfully on your system. If not, either install (or load) the C and Fortran NetCDF modules.

   • ESMF_PNETCDF can be set to “pnetcdf-config” if the command pnetcdf-config runs successfully. If not, either install or load the modules.

   • ESMF_PIO enables MPI executables to read and write NetCDF files. This can be set to “internal” if you would like for ESMF to install this, or “external” if you have this software installed already.

3. Double check everything looks right by running make info. Take a close look at the directories and include paths.

4. Install the command line tools with make build_apps. This will take a while.

5. Should be done! You can double check that it is correctly installed by running ./$(ESMF_DIR)/apps/..../ESMF_PrintInfo and the information on the EMSF installation will be displayed. Ensure PIO and NetCDF support is enabled.

Post-Installation

To run the scripts provided with this package, make sure you are in the correct directory and call them from the command line.

To call any of the scripts in you own code, you will need to add the package to your $PATH. This can be done by adding the following to the top of your code:

import sys
sys.path.append('/path/to/SAMI3-GITM-python')

For more information on how to use the provided code, continue reading!

Issues

• Older GitHub versions may require a slightly different command to access the correct branch.

• If you do not have conda installed and don’t want to install it, you can install the required packages with pip.

• If you encounter more problems, please either fill out a GitHub issue or contact the author directly.