Merge branch 'master' into shallow_and_baro_clean_gfort

ExeClim · Aug 5, 2024 · 117be8a · 117be8a
2 parents a9610f5 + f77ba4e
commit 117be8a
Show file tree

Hide file tree

Showing 75 changed files with 8,777 additions and 1,693 deletions.
diff --git a/.github/workflows/tests.yml b/.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

diff --git a/ReadMe.md b/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!
 

diff --git a/ci/environment-py3.9.yml → ci/environment-py.yml b/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

diff --git a/ci/environment-py3.12_frozen.yml b/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
diff --git a/docs/source/begginers_guide.rst b/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/``
 

diff --git a/docs/source/bve_swe_equations.rst b/docs/source/bve_swe_equations.rst
@@ -0,0 +1,13 @@
+Barotropic Vorticity and Shallow Water Equation Solvers
+=======================================================
+We would like to direct people interested into these equation solvers in Isca to the original documentation written by GFDL.
+
+Barotropic Vorticty Equation
+----------------------------
+
+ `Here <https://www.gfdl.noaa.gov/wp-content/uploads/files/user_files/pjp/barotropic.pdf>`_
+
+Shallow Water Equation
+----------------------
+
+ `Here <https://www.gfdl.noaa.gov/wp-content/uploads/files/user_files/pjp/shallow.pdf>`_
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -131,6 +131,7 @@ Contents
    changelog
    contributing
    testing/index.rst
+   bve_swe_equations
    references
    remote_access
 

diff --git a/docs/source/modules/damping_driver.rst b/docs/source/modules/damping_driver.rst
@@ -0,0 +1,141 @@
+Damping Driver
+======================
+
+Summary
+-------
+The ``damping_driver`` module is called by the ``idealized_moist_phys`` module by setting ``do_damping`` to true. It controls the upper level momentum damping in Isca. It controls 4 optional functions:
+
+1. **Rayleigh friction** which acts on levels ``1`` to ``kbot``. This function is located in ``damping_driver`` itself.
+2. A (orographic) **mountain gravity wave drag** module (``cg_drag``) may be called.
+3. A (non orographic) **convective gravity wave drag** module (``mg_drag``) may be called.
+4. A **time independent drag** may be called. This function is located in ``damping_driver`` itself.
+
+Another module (``topo_drag``) is referenced in the code, but is not available in Isca at present.
+
+It is located at: ``Isca/src/atmos_param/damping_driver/damping_driver.f90``
+
+Namelist options
+----------------
+``trayfric`` - (for Rayleigh friction) damping time in seconds for Rayleigh damping momentum in the top model layers, the number of which is specified by ``nlev_rayfric`` (non namelist parameter, automatically determined in code). If ``trayfric`` < 0 then time in days. Default 0.
+
+``do_rayleigh`` - On/Off switch for doing Rayleigh friction. Default False
+
+``sponge_pbottom`` - (for Rayleigh friction) used to calculate ``nlev_rayfric``, it specifies the bottom level where the Rayleigh friction starts. Default 50Pa.
+
+``do_cg_drag`` - On/Off switch for doing mountain gravity wave drag. Default False.
+
+``do_topo_drag`` - On/Off switch for doing the topo_drag module which is currently unavailable. Default False. 
+
+``do_mg_drag`` - On/Off switch for doing convective gravity wave drag. Default False.
+
+``do_conserve_energy`` - (for Rayleigh friction) On/Off switch for also calculating the temperature tendency (if True). Default False.
+
+``do_const_drag`` - On/Off switch for doing the constant drag. Default False.
+
+``const_drag_amp`` - (for constant drag) Parameter for adjusting drag. Default 3.e-04.
+
+``const_drag_off`` - (for constant drag) Parameter for adjusting drag. Default 0.
+
+For a typical idealized Earth set up there is no parameterised gravity wave drag and Rayleigh damping is only needed to keep the model stable. The namelist would then look like:: 
+    ``'do_rayleigh': True,
+    'trayfric': -0.25,
+    'sponge_pbottom':  50.,
+    'do_conserve_energy': True``
+
+Diagnostics
+-----------
+There are many diagnostics either in or passed by damping driver. 
+
+**Rayleigh friction:**
+
++-----------------------+------------------------------------+------------------------+
+| Name                  | Description                        | Units                  |
+|                       |                                    |                        |
++=======================+====================================+========================+
+| ``udt_rdamp``         | u wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+| ``vdt_rdamp``         | v wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+| ``tdt_diss_rdamp``    | dissipative heating                |:math:`K s^{-1}`        |
++-----------------------+------------------------------------+------------------------+
+| ``diss_heat_rdamp``   | integrated dissipative heating     |:math:`W m^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+
+**Mountain GWD:**
+
++-----------------------+------------------------------------+------------------------+
+| Name                  | Description                        | Units                  |
+|                       |                                    |                        |
++=======================+====================================+========================+
+| ``udt_gwd``           | u wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+| ``vdt_gwd``           | v wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+| ``taubx``             | x base flux                        |:math:`kg m^{-1} s^{-2}`|
++-----------------------+------------------------------------+------------------------+
+| ``tauby``             | y base flux                        |:math:`kg m^{-1} s^{-2}`|
++-----------------------+------------------------------------+------------------------+
+| ``taus``              | saturation flux                    |:math:`kg m^{-1} s^{-2}`|
++-----------------------+------------------------------------+------------------------+
+| ``tdt_diss_gwd``      | dissipative heating                |:math:`K s^{-1}`        |
++-----------------------+------------------------------------+------------------------+
+| ``diss_heat_gwd``     | integrated dissipative heating     |:math:`W s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+| ``sgsmtn``            | sub-grid scale topography variance |:math:`m`               |
++-----------------------+------------------------------------+------------------------+
+
+**Convective GWD:**
+
++-----------------------+------------------------------------+------------------------+
+| Name                  | Description                        | Units                  |
+|                       |                                    |                        |
++=======================+====================================+========================+
+| ``udt_cgwd``          | u wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+
+**Constant Drag:**
+
++-----------------------+------------------------------------+------------------------+
+| Name                  | Description                        | Units                  |
+|                       |                                    |                        |
++=======================+====================================+========================+
+| ``udt_cnstd``         | u wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+
+**topo_drag:**
+
+Note: These are not currently available
+
++-----------------------+------------------------------------+------------------------+
+| Name                  | Description                        | Units                  |
+|                       |                                    |                        |
++=======================+====================================+========================+
+| ``udt_topo``          | u wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+| ``vdt_topo``          | v wind tendency                    |:math:`m s^{-2}`        |
++-----------------------+------------------------------------+------------------------+
+
+Relevant modules and subroutines
+--------------------------------
+The code is split into 4 subroutines; ``damping_driver``, ``damping_driver_init``, ``damping_driver_end`` and ``rayleigh``. The ``_init`` and ``_end`` subroutines are for initializing and closing the module. The majority of the ``damping driver`` code is just a switchboard with the exception of the Rayleigh and constant drag calculations. The calculations for the other drag schemes are given in their own documentation.
+
+**Rayleigh Drag**
+
+Located in the ``rayleigh`` subroutine. This code damps the momentum toward zero in the specified upper model levels. The zonal/meridional tendency for each grid cell is calculated my multiplying the zonal/meridional velocity by a factor determined by the pressure and Rayleigh parameters. The damping is therefor proportional to the wind velocity.
+
+The temperature tendency is calculated using the wind velocities, wind tendencies, and the heat capacity of air.
+
+**Constant Drag**
+
+Located in the ``damping_driver`` subroutine. This is modelled on Alexander-Dunkerton winter average, it uses a 3rd order polynomial and the constant drag parameters to calculate a time invariant drag. This set up is modelled on Earth's atmosphere and therefore not recommended for other planets. 
+
+
+References
+----------
+Convective Gravity Wave Drag (cg_drag) [Pierrehumbert1986]_
+
+Orographic Gravity Wave Drag (mg_drag) [Alexander1999]_
+
+Authors
+-------
+This documentation was written by Ross Castle, peer reviewed by Stephen Thomson, and quality controlled by Matthew Henry.
diff --git a/docs/source/modules/idealised_moist_phys.rst b/docs/source/modules/idealised_moist_phys.rst
@@ -11,6 +11,8 @@
     Here is a guide on reST formatting:
     https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
+.. _idealized_moist_phys:
+
 Moist physics driver: idealized_moist_phys.F90
 ==============================================
 

diff --git a/docs/source/modules/index.rst b/docs/source/modules/index.rst
@@ -12,10 +12,13 @@ Components of Isca
    physics
    constants
    output
+   damping_driver
    idealised_moist_phys
    two_stream_gray_rad
    convection_simple_betts_miller
+   lscale_cond
+   topography
    socrates
+   mixedlayer
    surface_flux
-   diag_manager_mod
-
+   diag_manager_mod