Merge branch 'master' into shallow_and_baro_clean_gfort_input_file

.github/workflows/tests.yml

@@ -36,7 +36,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]  # ,  macos-latest]
-        python-version: ['3.9']
+        python-version: ['3.12']
 
     steps:
       - name: Checkout source
@@ -46,7 +46,7 @@ jobs:
         uses: conda-incubator/setup-miniconda@v2
         with:
           python-version: ${{ matrix.python-version }}
-          environment-file: ci/environment-py${{ matrix.python-version }}.yml
+          environment-file: ci/environment-py${{ matrix.python-version }}_frozen.yml
           miniforge-variant: Mambaforge
           miniforge-version: "latest"
           use-mamba: true

ReadMe.md

@@ -78,10 +78,10 @@ $ cd Isca
 
 3. **Create a conda environment**
 
-Requirements for Isca can be installed via the .yml file included with the model in `Isca/ci/environment-py3.9.yml`
+Requirements for Isca can be installed via the .yml file included with the model in `Isca/ci/environment-py3.12_frozen.yml`
 Navigate to the downloaded Isca folder, and create a conda environment `isca_env` containing the required packages using: 
 ```{bash}
-$ conda env create -f ci/environment-py3.9.yml
+$ conda env create -f ci/environment-py3.12_frozen.yml
 ```
 Then activate the environment; you'll need to do this each time you launch a new bash session.
 ```{bash}
@@ -100,33 +100,35 @@ Successfully installed Isca
 
 ### Compiling for the first time
 
-At Exeter University, Isca is compiled using:
-
-* Intel Compiler Suite 14.0
-* OpenMPI 10.0.1
-* NetCDF 4.3.3.1
-* git 2.1.2
+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. 
 
-Different workstations/servers at different institutions will have different compilers and libraries available.  The Isca framework assumes you have something similar to our stack at Exeter, but provides a hook for you to configure the environment in which the model is run.
+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.
 
-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.
-
-For example, on the EMPS workstations at Exeter, I have the following in my `~/.bashrc`:
+To make use of this environment, you should add a version of the following to your `~/.bashrc`:
 
 ```{bash}
 # directory of the Isca source code
 export GFDL_BASE=/scratch/jamesp/Isca 
-# "environment" configuration for emps-gv4
-export GFDL_ENV=emps-gv
+# "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/gfdl_work
+export GFDL_WORK=/scratch/jamesp/isca_work
 # directory for storing model output
-export GFDL_DATA=/scratch/jamesp/gfdl_data
+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.  For an example that you could adapt to work on your machine, see `src/extra/env/emps-gv`.
+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 Exeter University, Isca is compiled using:
+
+* Intel Compiler Suite 14.0
+* OpenMPI 10.0.1
+* NetCDF 4.3.3.1
+* git 2.1.2
 
-We are not able to provide support in configuring your environment at other institutions other than Exeter University - we suggest that you contact your friendly local sysops technician for guidance in getting the compilers and libraries collated if you are not sure how to proceed.
+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 file. However, if you want to install the model using your own configuration then we are not able to provide support in configuring your environment. We suggest that you contact your friendly local sysops technician for guidance in getting the compilers and libraries collated if you are not sure how to proceed.
 
 If you work at another large institution and have successfully compiled and run Isca, we welcome you to commit your own environment config to `/src/extra/env/my-new-env` for future scientists to benefit from and avoid the pain of debugging compilation!
 

ci/environment-py3.9.yml → ci/environment-py.yml

@@ -10,9 +10,9 @@ dependencies:
 - libgfortran
 - netcdf-fortran
 - numpy
-- openmpi
+- openmpi=4.*
 - pandas
-- python=3.9
+- python
 - pip
 - pytest
 - sh

ci/environment-py3.12_frozen.yml

@@ -0,0 +1,20 @@
+name: isca_env
+channels:
+- conda-forge
+dependencies:
+- dask=2024.1.0
+- f90nml=1.4.4
+- fortran-compiler=1.7.0
+- ipykernel=6.29.0
+- jinja2=3.1.3
+- libgfortran=3.0.0
+- netcdf-fortran=4.6.1 
+- numpy=1.26.3
+- openmpi=4.1.6
+- pandas=2.2.0
+- python=3.12.1
+- pip=23.3.2
+- pytest=7.4.4 
+- sh=2.0.6
+- tqdm=4.66.1
+- xarray=2024.1.1

docs/source/begginers_guide.rst

@@ -1,7 +1,7 @@
 Isca Beginner's Guide
 ====================
 
-Below is a list of reading and activites that will help you get comfortable using Isca. Be assured that your supervisor/tutor will not expect you to be fluent with this when you start using Isca, but it will help to have an idea of what to expect when you start running the model.
+Below is a list of reading and activities that will help you get comfortable using Isca. Be assured that your supervisor/tutor will not expect you to be fluent with this when you start using Isca, but it will help to have an idea of what to expect when you start running the model.
 
 This document is essentially a suggestion of signposts. With this kind of work, self-study and initiative is very important. It is up to you to go and research the topics until you feel comfortable.
 
@@ -112,7 +112,7 @@ Now you have made plots – or indeed any file you want to transfer between the
 
 *SFTP (SSH File Transfer Protocol)* is one, it will work on all operating systems and is the easiest for windows. One way of using SFTP is with an *SFTP client*, many are available. One of them is `Cyberduck <https://cyberduck.io>`_. It will require setting up but it is fairly straight forward. These clients tend to have a GUI so you can just drag and drop the files you want to transfer. It is also possible to view and transfer files using the native file browser if you're using Linux or macOS, using their built-in functions to connect via SFTP.
 
-Other option is to use a command line function, for example ``scp``. This is a secure file copy protol, which uses SSH. The usage is simple, for example on the computer you want to transfer the file to, type:
+Other option is to use a command line function, for example ``scp``. This is a secure file copy protocol, which uses SSH. The usage is simple, for example on the computer you want to transfer the file to, type:
 
 ``scp [email protected]:/path_to_file/file.png /path_to_destination/``
 

docs/source/remote_access.rst

@@ -4,16 +4,16 @@ Remote Access
 Overview
 --------
 This is a guide for how to edit remote files on a local text editor via port-
-fowarding. By the end you should know: 
+forwarding. By the end you should know: 
 
 * how to quickly login to your remote server using an SSH config file
 * how to edit remote files in a local text editor through ``rmate``
 * how to edit remote python files in a local ``jupyter`` environment
 
-Simplifying logins and port-fowarding
+Simplifying logins and port-forwarding
 -------------------------------------
 If you use a Unix-based operating system on your personal computer, you can make use
-of an SSH config file to create shortcuts to your frequently used remote computers. We will take this one step further to simplify port-fowarding, a method which allows a user to redirect data from a specified remote host and port, through a secure tunnel, to a specified local port. Port-fowarding is helfpul because it will enable us to edit remote files locally.
+of an SSH config file to create shortcuts to your frequently used remote computers. We will take this one step further to simplify port-forwarding, a method which allows a user to redirect data from a specified remote host and port, through a secure tunnel, to a specified local port. Port-forwarding is helpful because it will enable us to edit remote files locally.
 
 As an example without any fancy tricks, let's set up an SSH tunnel that maps ``localhost`` port 3039 on my local machine to 3039 on my remote machine (the number is arbitrary as long as its between 1024 and 49150): ``$ ssh -l localhost:3039:host:3039 user@host``. You will then be required to enter in your password. This is cumbersome to repeat everytime we log in. Our goal will be to shorten the command to : ``$ ssh hostalias`` and without having to enter in your password. We give some instructions below:
 
@@ -51,12 +51,12 @@ You should not be able to log in simply by typing ``$ ssh hostalias``. Congratul
 Edit remote files in a local text editor using ``rmate``
 --------------------------------------------------------
 As an alternative to remote-based text editors such as ``vi`` and ``emacs``, we can
-use port-fowarding to set up a `local-based text editor like Atom <https://atom.io>`_ which includes features such as syntax highlighting and code completion. For instructions to install ``rmate`` on your **local machine**, `click here <https://github.com/textmate/rmate>`_. Then to specifically use Atom to edit remote files, `click here <https://atom.io/packages/remote-atom>`_. You will need to add the following line to your ``~/.ssh/config`` file: ``RemoteForward 52698 localhost:52698``.
+use port-forwarding to set up a `local-based text editor like Atom <https://atom.io>`_ which includes features such as syntax highlighting and code completion. For instructions to install ``rmate`` on your **local machine**, `click here <https://github.com/textmate/rmate>`_. Then to specifically use Atom to edit remote files, `click here <https://atom.io/packages/remote-atom>`_. You will need to add the following line to your ``~/.ssh/config`` file: ``RemoteForward 52698 localhost:52698``.
 
 
 Edit remote python files in a ``jupyter`` environment
 -----------------------------------------------------
-The ``jupyter`` environment is a great environent for data exploration and integrating
+The ``jupyter`` environment is a great environment for data exploration and integrating
 your figures inline with your code. To open your first Jupyter notebook, log in to your **remote machine** and type: ``$ jupyter lab --no-browser --port=3039``. 
 
 To make it even quicker, you can type the following on your **local machine**: ``$ssh remotehost "jupyter lab --no-browser --port=3039``. This should function because of all the work we put in during the port forwarding section. To shorten this command, add an alias to your ``~/.bashrc`` file on your **local machine**. I personally use the alias ``rjlab``.
@@ -81,7 +81,7 @@ Your final ``~/.ssh/config`` file should look like this (making sure to replace
 
 * Do not use this with VPN, use ithome aka hashbang as proxy. If the connection is interrupted you can still reconnect, assuming the jupyter process is still running. But make sure not to leave zombie jupyter processes with open ports on remote hosts!
 
-* Remember the port numbers chosen are arbitary. If you choose the same number as someone else on your network, their files may open up on your computer and vice versa!
+* Remember the port numbers chosen are arbitrary. If you choose the same number as someone else on your network, their files may open up on your computer and vice versa!
 
 Authors
 -------

exp/test_cases/README.md

@@ -6,6 +6,9 @@
 `bucket_hydrology`
 * As described in Isca paper (Vallis et al., 2017) but without q-fluxes
 
+`column_test_case`
+* Single column configuration of Isca. Please cite McKim et al. (2024, submitted) (<https://doi.org/10.22541/essoar.170904795.55675140/v1>) if you use the SCM. 
+
 `frierson`
 * Control case of the so-called `Frierson model` described in e.g. <https://doi.org/10.1175/JAS3753.1>
 

exp/test_cases/ape_aquaplanet/socrates_ape_aquaplanet_T42.py

@@ -107,8 +107,8 @@
         'do_read_ozone': True,
         'ozone_file_name':'ozone_1990',
         'ozone_field_name':'ozone_1990',
-        'dt_rad':4320.,
-        'solday':90., #turn off seasonal cycle - diurnal by default
+        'dt_rad':4320,
+        'solday':90, #turn off seasonal cycle - diurnal by default
         'co2_ppmv':348.0,
         'store_intermediate_rad':True,
         'chunk_size': 16,

exp/test_cases/axisymmetric/axisymmetric_test_case.py

@@ -140,6 +140,7 @@
         'do_read_ozone':True,
         'ozone_file':'ozone_1990',
         'dt_rad': 3600, #Set RRTM radiation timestep to 3600 seconds, meaning it runs every 5 atmospheric timesteps
+
     },
 
     # FMS Framework configuration
@@ -184,4 +185,4 @@
 
     exp.run(1, use_restart=False, num_cores=NCORES)
     for i in range(2,121):
-        exp.run(i, num_cores=NCORES)
+        exp.run(i, num_cores=NCORES)