Isca

<h1 align="center"> <a href="https://execlim.github.io/Isca"> <img src="docs/source/_static/isca_logo_large.png" alt="Isca" width="300"></a><br> </h1> <p align="center"> <a href="https://doi.org/10.5194/gmd-11-843-2018"> <img src="https://img.shields.io/badge/Paper-GMD-orange.svg?logo=data:image/svg%2bxml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iMzI1IiB3aWR0aD0iNDEwIj4KPGcgc3R5bGU9ImZpbGw6IzAwNzJiYyI+CjxwYXRoIGQ9Im0gMjE5LjcsMjQ5LjcgYyAtMTkuNSwxNi4xIC00NC41LDI1LjggLTcxLjgsMjUuOCAtNjIuMywwIC0xMTMsLTUwLjcgLTExMywtMTEzIDAsLTYyLjMgNTAuNywtMTEzIDExMywtMTEzIDI3LjIsMCA1Mi4zLDkuNyA3MS44LDI1LjggNy41LC0yIDE1LjMsLTMuMSAyMy41LC0zLjEgOC41LDAgMTYuNywxLjIgMjQuNCwzLjQgQyAyNTYuMyw2MC4xIDI0Mi4xLDQ2LjkgMjI1LjgsMzYuOCBMIDIzNi4xLDE0LjkgMjA0LjQsMC4xIDE5NC4yLDIyIEMgMTc5LjYsMTcuMiAxNjQuMSwxNC42IDE0OCwxNC42IDY2LjQsMTQuNiAwLDgxIDAsMTYyLjYgYyAwLDUzIDI4LDk5LjYgNzAsMTI1LjcgbCAtMTAuMiwyMS45IDMxLjcsMTQuOCAxMC4yLC0yMS44IGMgMTQuNiw0LjggMzAuMSw3LjQgNDYuMiw3LjQgNDkuMSwwIDkyLjgsLTI0LjEgMTE5LjcsLTYxLjEgLTcuOCwyLjIgLTE2LDMuNCAtMjQuNCwzLjQgLTguMSwtMC4xIC0xNiwtMS4yIC0yMy41LC0zLjIgeiIvPgo8cGF0aCBkPSJtIDE2MCwxMjMuOSBjIDQuNSwtOS44IDEwLjcsLTE4LjcgMTguMiwtMjYuMyBsIC05Mi42LDAgMCwxMjkgOTIuNSwwIEMgMTcwLjYsMjE5IDE2NC41LDIxMC4xIDE2MCwyMDAuMyBsIC00OC4xLDAgMCwtMjUgNDAuNywwIGMgLTAuNiwtNC4zIC0wLjksLTguNyAtMC45LC0xMy4xIDAsLTQuNSAwLjMsLTguOSAxLC0xMy4yIGwgLTQwLjgsMCAwLC0yNSBjIDAsLTAuMSAzMS42LC0wLjEgNDguMSwtMC4xIHoiLz4KPHBhdGggZD0ibSAyMzMuMSwxNzQuNyAzMS42LDAgMCwyNCBjIC02LjMsMy43IC0xMy41LDUuNiAtMjEsNS42IC0yMy4zLDAgLTQyLjIsLTE4LjkgLTQyLjIsLTQyLjIgMCwtMjMuMyAxOC45LC00Mi4yIDQyLjIsLTQyLjIgOS41LDAgMTguNSwzLjEgMjYsOSBMIDI4NiwxMDguMiBjIC0xMi4yLC05LjUgLTI2LjgsLTE0LjYgLTQyLjMsLTE0LjYgLTM3LjgsMCAtNjguNiwzMC44IC02OC42LDY4LjYgMCwzNy44IDMwLjgsNjguNiA2OC42LDY4LjYgMTUuNSwwIDMwLjEsLTUgNDIuMywtMTQuNiBsIDUsLTQgMCwtNjMuNyAtNTcuOSwwIDAsMjYuMiB6Ii8+CjxwYXRoIGQ9Im0gMzgzLjgsOTcuNSAwLDg0LjQgYyAwLDEyLjMgLTEwLDIyLjQgLTIyLjQsMjIuNCAtMTIuMywwIC0yMi40LC0xMCAtMjIuNCwtMjIuNCBsIDAsLTg0LjQgLTI2LjMsMCAwLDg0LjQgYyAwLDI2LjkgMjEuOSw0OC43IDQ4LjcsNDguNyAyNi45LDAgNDguNywtMjEuOSA0OC43LC00OC43IGwgMCwtODQuNCAtMjYuMywwIHoiLz4KPC9nPgo8L3N2Zz4K&logoColor=white" alt="Python 3.7+"></a> <a href="https://www.python.org/downloads/"> <img src="https://img.shields.io/badge/python-3.7+-blue.svg?logo=python&logoColor=white" alt="Python 3.7+"></a> <a href="https://github.com/psf/black"> <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="black"></a> <a href="https://github.com/execlim/Isca/actions?query=workflow%3Atests"> <img src="https://github.com/execlim/Isca/workflows/tests/badge.svg" alt="Tests"></a> <a href="https://execlim.github.io/Isca"> <img src="https://img.shields.io/badge/docs-latest-green?logo=github" alt="Documentation"></a> <a href="LICENSE"> <img src="https://img.shields.io/badge/license-GPL%20v3-blue.svg?logo=gnu" alt="License: GPL v3"></a> <a href="https://twitter.com/IscaModel"> <img src="https://img.shields.io/twitter/follow/IscaModel?color=yellow&label=twitter%7CIscaModel&logo=twitter&style=flat" alt="twitter IscaModel"></a> </p>

Isca is a framework for the idealized modelling of the global circulation of planetary atmospheres at varying levels of complexity and realism. The framework is an outgrowth of models from GFDL designed for Earth's atmosphere, but it may readily be extended into other planetary regimes. Various forcing and radiation options are available. At the simple end of the spectrum a Held-Suarez case is available. An idealized grey radiation scheme, a grey scheme with moisture feedback, a two-band scheme and a multi-band scheme are also available, all with simple moist effects and astronomically-based solar forcing. At the complex end of the spectrum the framework provides a direct connection to comprehensive atmospheric general circulation models.

For Earth modelling, options include an aqua-planet and configurable (idealized or realistic) continents with idealized or realistic topography. Continents may be defined by changing albedo, heat capacity and evaporative parameters, and/or by using a simple bucket hydrology model. Oceanic Q-fluxes may be added to reproduce specified sea-surface temperatures, with any continents or on an aquaplanet. Planetary atmospheres may be configured by changing planetary size, solar forcing, atmospheric mass, radiative, and other parameters.

The underlying model is written in Fortran and may largely be configured with Python scripts, with internal coding changes required for non-standard cases. Python scripts are also used to run the model on different architectures, to archive the output, and for diagnostics, graphics, and post-processing. All of these features are publicly available on a Git-based repository.

Getting Started

A python module isca (note lowercase) is provided alongside the Fortran source code that should help to do a lot of the heavy-lifting of compiling, configuring and running the model for you. Isca can be compiled, run and configured without using python, but using the python wrapper is recommended.

Installing the isca python module

The python module is found in the src directory and can be installed using pip. It's recommended that you use some sort of python environment manager to do this, such as using a conda distribution and creating an environment (in the code below called "isca_env"), or using virtualenv instead. This "getting started" will show you how to create a python environment that includes Isca's required packages, and then install the model.

1. Install Miniforge

Recommended step: Some workstations may have outdated default python and conda installations, which may cause conflicts during installation. As a lightweight solution to get up-to-date installations, we recommend downloading Miniforge. To ensure this works as expected, check that $PYTHONPATH is unset and that your .bashrc does not contain module load statements that may cause conda conflicts.

If you have a recent conda version installed in your home directory already you may wish to skip this step.

2. Check out or download this repository

To begin you'll need a copy of the source code. Either fork the Isca repository to your own github username, or clone directly from the ExeClim group.

$ git clone https://github.com/ExeClim/Isca
$ cd Isca

3. Create a conda environment

Requirements for Isca can be installed via the .yml files included with the model in Isca/ci/. The choice of which yml file depends on your system:

Both the environment-py3.12_frozen.yml and environment-py.yml files install everything required to install Isca, including the gfortran compilers and netcdf-fortran. The environment-py3.12_frozen.yml file has frozen versions of all the packages that we ourselves have tested, whereas the environment-py.yml file will grab the latest versions of all of these libraries etc.

The environment-py_no_compilers.yml version includes only the packages needed by Isca without the gfortran compilers and netcdf-fortran. This is the option to choose if you want to install Isca on a system that already has a fortran compiler, MPI and netcdf-fortran already installed.

Once you've decided on the yml file to use, you should navigate to the downloaded Isca folder, and create a conda environment isca_env containing the required packages using:

$ conda env create -f ci/YML_FILE_THAT_YOU_CHOSE.yml

Then activate the environment; you'll need to do this each time you launch a new bash session.

$ conda activate isca_env

or

$ conda activate isca_env_no_comp

if you chose the no-compilers yml file.

4. Install the model

Now install the isca python module in "development mode". This will allow you, if you wish, to edit the src/extra/python/isca files and have those changes be used when you next run an Isca script. Navigate to Isca/src/extra/python/ and run:

(isca_env)$ pip install -e .
...
Successfully installed Isca

Compiling for the first time

By installing Isca using the ci/environment-py3.12_frozen.yml file, you will have installed everything you need to run Isca, including the gfortran compiler, openmpi and netcdf. Whilst this may not be the optimal way of running Isca on your machine, it should work without too much extra effort.

Before Isca is compiled/run, an environment is first configured which loads the specific compilers and libraries necessary to build the code. This done by setting the environment variable GFDL_ENV in your session. There is an option within Isca to use set GFDL_ENV=ubuntu_conda, which is setup to use the gfortran compiler you installed via the environment file.

To make use of this environment, you should add a version of the following to your ~/.bashrc:

# directory of the Isca source code
export GFDL_BASE=/scratch/jamesp/Isca 
# "environment" configuration for use with ubuntu-conda
export GFDL_ENV=ubuntu_conda
# temporary working directory used in running the model
export GFDL_WORK=/scratch/jamesp/isca_work
# directory for storing model output
export GFDL_DATA=/scratch/jamesp/isca_data

The value of GFDL_ENV corresponds to a file in src/extra/env that is sourced before each run or compilation.

You may wish to configure your own way to run Isca using locally available compilers, e.g. the Intel compilers. An example using such a setup is available here - src/extra/env/emps-gv.

At the University of Exeter, Isca is compiled using:

• Intel Compiler Suite 14.0
• OpenMPI 10.0.1
• NetCDF 4.3.3.1
• git 2.1.2

Different workstations/servers at different institutions will have different compilers and libraries available. The Isca framework should run 'out of the box' using the gfortran compilers installed from the environment fil