Merging develop to master

.github/workflows/python-package.yml

@@ -5,7 +5,7 @@ name: Python package
 
 on:
   push:
-    branches: [ master, develop, shuffle ]
+    branches: [ master]
   pull_request:
     branches: [ master, develop ]
 

AUTHORS.rst

@@ -0,0 +1,18 @@
+=======
+Credits
+=======
+
+Original Creator
+----------------
+
+* Jeff Whitaker <jeffrey.s.whitaker@noaa.gov>
+
+Development Lead
+----------------
+
+* Abel Shibu <abels2000@gmail.com>
+
+Contributors
+------------
+
+* Joy Monteiro <joy.monteiro@misu.su.se>

HISTORY.rst

@@ -5,4 +5,4 @@ History
 Latest
 ---------
 
-* GFS Dynamical core shifted over from CliMT and working.
+* GFS Dynamical core moved from CLiMT to this repository.

README.rst

@@ -3,13 +3,25 @@ gfs-dynamical-core
 ==================
 
 **gfs-dynamical-core** is home to the GFS dynamical core, which was previously available on
-CliMT.
-
-* Free software: BSD license
+CliMT_.
 
 Installation
 -------------
 
 gfs-dynamical-core can be installed directly from the python package index using pip.
 
     pip install gfs-dynamical-core
+
+This command should work on most systems and will install wheels for generic architecture. However,
+this may result in a slower code.
+
+To optimise the package for your system architecture, build it from source. See the documentation_
+for instructions.
+
+.. _Cookiecutter: https://github.com/audreyr/cookiecutter
+.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
+.. _sympl: https://github.com/mcgibbon/sympl
+.. _Pint: https://pint.readthedocs.io
+.. _xarray: http://xarray.pydata.org
+.. _documentation: https://gfs-dynamical-core.readthedocs.io
+.. _CliMT: https://github.com/CliMT/climt

docs/.ipynb_checkpoints/Description_of_SecondBEST-checkpoint.ipynb

@@ -0,0 +1,244 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# SecondBEST\n",
+    "------------------\n",
+    "\n",
+    "`SecondBEST` is a simplified implementation of the Bare Essentials for Surface Transfer (BEST) land surface model. The main simplifications are that `SecondBEST` does not incorporate the effects of vegetation, which reduces a lot of calculations within BEST. We also assume each grid cell is either fully bare soil or snow/ice, i.e, there are no fractional land types. The implementation here follows the description in [Pitman et al.](http://www.geo.utexas.edu/climate/Research/Reprints/Pitman.BMRC.1991.pdf)\n",
+    "\n",
+    "This notebook is a ready reference to the equations used in `SecondBEST` so that interested users don't have to read the above reference if they don't wish to. However, if you plan on making heavy use of `SecondBEST`, you are encouraged to do so!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Notation\n",
+    "\n",
+    "**Surface types**:\n",
+    "* _s_ = air above the surface, or lowest atmospheric model layer.\n",
+    "* _u_ = upper soil layer. BEST uses three soild layers.\n",
+    "* _l_ = lower soil layer.\n",
+    "* _b_ = base soil layer.\n",
+    "* _n_ = snow.\n",
+    "* _d_ = intercepted water.\n",
+    "\n",
+    "**Spectral regions, phases of water**\n",
+    "* _L_ = liquid.\n",
+    "* _F_ = frozen.\n",
+    "* _SW_ = shortwave.\n",
+    "* _LW_ = longwave.\n",
+    "\n",
+    "**Water content**\n",
+    "* $X_w$ = volumetric soil liquid water content\n",
+    "* $X_i$ = volumetric soil ice content"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Soil properties\n",
+    "\n",
+    "Certain soil properties are calculated initially based on the soil and area types.\n",
+    "Currently, `SecondBEST` recognises two soil types: `clay` and `sand`.\n",
+    "\n",
+    "* Soil colour ($clr$):\n",
+    "    * 0.2 if `clay`\n",
+    "    * 1.0 if `sand`\n",
+    "* Soil texture ($tex$):\n",
+    "    * 0 if `clay`\n",
+    "    * 9 if `sand`\n",
+    "    * 0.07 if area type is `land_ice`\n",
+    "* Soil porosity ($X_v$), Eq. 4.10:\n",
+    "    * $0.6 - 0.03\\times tex$\n",
+    "* Soil moisture volume fraction at field capacity ($X_{FC}$), Eq. 4.11:\n",
+    "    * $(0.95 - 0.086\\times tex)X_v$\n",
+    "* Soil moisture volume fraction at wilting point ($X_{wilt}$), Eq. 4.12:\n",
+    "    * $X_v - 0.03$\n",
+    "    * 0.01 when area type is `land_ice`.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Albedo Calculation\n",
+    "\n",
+    "The albedo calculation is described in section 5.0 of Pitman et al. `SecondBEST` calculates albedo in the near-infraread and shortwave separately. This is also quite convenient since RRTMG, the radiative transfer code also uses two separate albedos.\n",
+    "\n",
+    "### Bare soil\n",
+    "\n",
+    "The albedo for bare soil is calculated as (Eqns. 5.5, 5.6):\n",
+    "$$\\alpha_{SW,u} = 0.10 + 0.1clr + 0.06(1-W_{L,u})\\\\\n",
+    "\\alpha_{LW,u} = 2\\alpha_{SW,u}$$\n",
+    "\n",
+    "where $clr$ is the soil colour defined above.\n",
+    "\n",
+    "$W_{L,u}$ is the soil wetness factor, and is defined as the ratio of the\n",
+    "liquid soil water content in the upper soil layer to its porosity.\n",
+    "\n",
+    "$$W_{L,u} = X_{w,u}/X_v$$\n",
+    "\n",
+    "### Land Ice\n",
+    "\n",
+    "The albedo of Land Ice is calculated as (Eqns. 5.7, 5.8):\n",
+    "$$\\alpha_{SW,u} = 0.60 + 0.06(1-W_{L,u}) \\\\\n",
+    "\\alpha_{LW,u} = \\frac{1}{3}\\alpha_{SW,u}$$\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Surface drag parameters\n",
+    "\n",
+    "`SecondBEST` calculates the drag parameters as in section 6 of Pitman et al.\n",
+    "\n",
+    "### Roughness length\n",
+    "\n",
+    "$$ z_0 = \\left \\{ \\begin{array}{1} 0.01m,\\ (soil) \\\\ 0.001m,\\ (snow\\ or\\ ice)\\\\ 0.0002m,\\ (sea) \\end{array} \\right .$$\n",
+    "\n",
+    "### Neutral drag coefficient\n",
+    "\n",
+    "$$ C_{DN} = \\left ( \\frac{\\kappa}{\\log{z_m} - \\log{z_0}} \\right )^2 ,$$\n",
+    "\n",
+    "where $z_m$ is the hydrostatic mid-level height of the lowest atmosphere level and $\\kappa$ is the von Karman constant.\n",
+    "\n",
+    "### Normalised mixing length\n",
+    "\n",
+    "$$\\zeta = \\exp{\\left (\\frac{-\\kappa}{\\sqrt{C_{DN}}}\\right )}$$\n",
+    "\n",
+    "### Richardson number\n",
+    "\n",
+    "$$Ri = -\\frac{gz_m}{T_s U_m^2}\\left [ T_u - T_s\\right ] $$\n",
+    "\n",
+    "Where $U_m$ is the magnitude of the wind speed at the lowest model level and the other notation is as before. $U_m$ has a minimum value that can be set during initialisation of `SecondBEST`.\n",
+    "A negative Richardson number indicates unstable conditions.\n",
+    "\n",
+    "### Momentum drag coefficient\n",
+    "\n",
+    "$$ C_{Dm} = \\left \\{ \\begin{array}{1} C_{DN}\\left [ 1 - \\frac{8Ri}{1 + 56.768 C_{DN}\\sqrt{\\frac{-Ri}{\\zeta}}}\\right ],\\ Ri<0 \\\\ C_{DN} \\left [\\frac{(1 - 4\\epsilon Ri)^2}{1 + 8(1-\\epsilon)Ri} \\right ],\\ Ri \\ge 0 \\end{array} \\right .$$\n",
+    "\n",
+    "### Heat and other scalars drag coefficient\n",
+    "$$ C_{Dh} = \\left \\{ \\begin{array}{1} C_{DN}\\left [ 1 - \\frac{12Ri}{1 + 41.801 C_{DN}\\sqrt{\\frac{-Ri}{\\zeta}}}\\right ],\\ Ri<0 \\\\ C_{DN} \\left [\\frac{1 - 4\\epsilon Ri}{1 + (6-4\\epsilon)Ri} \\right ]^2,\\ Ri \\ge 0 \\end{array} \\right .$$\n",
+    "\n",
+    "where $\\epsilon$ is 0.01 for land and 1.0 for oceans."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Surface fluxes\n",
+    "\n",
+    "The equations are from Section 8. in Pitman et al.\n",
+    "\n",
+    "### Sensible heat flux (Eq. 8.3)\n",
+    "\n",
+    "is given by the relatively well known bulk aerodynamic formula.\n",
+    "\n",
+    "$$SHF = \\rho_s C_{pd} U_m C_{Dh} (T_u - T_s)$$\n",
+    "\n",
+    "### Latent heat flux (Eq. 8.4)\n",
+    "\n",
+    "is also given by the bulk formula\n",
+    "\n",
+    "$$LHF = L_v\\rho_s U_m C_{Dh} \\beta_u(q^*_u - q_s) $$\n",
+    "\n",
+    "where $q^*_u$ is the saturation specific humidity at the soil surface. A \"wetness factor\", $\\beta_u$, is also required, defined as\n",
+    "\n",
+    "$$\\beta_u = \\left \\{ \\begin{array}{1} 1,\\ snow\\\\ \\frac{W_{F,u}L_v}{L_i} + \\frac{E_{usmax}}{E_{usP}},\\ soil\\end{array} \\right .$$\n",
+    "\n",
+    "$L_v$ is the latent heat of vapourisation, $L_i$ is the latent heat of sublimation, $W_{F,u}$ is the frozen soil moisture in the upper soil layer. The first term containing these terms represents the rate at which frozen soil can sublimate.\n",
+    "\n",
+    "$E_{usP}$ is the potential evaporation rate at the soil surface,\n",
+    "\n",
+    "$$E_{usP} = \\rho_s c_u (q^*_u - q_s)$$\n",
+    "\n",
+    "where $c_u$ is the soil conductance, defined as (Eq. 7.22)\n",
+    "\n",
+    "$$c_u = C_{Dh}U_m.$$\n",
+    "\n",
+    "$E_{usmax}$ is the exfiltration rate given by\n",
+    "\n",
+    "$$E_{usmax} = K_{HD}\\Theta_u^{0.5B + 2} - K_{H0}\\Theta_u^{2B + 3}$$\n",
+    "\n",
+    "Where\n",
+    "\n",
+    "$$B = \\left \\{ \\begin{array} 10,\\ clay\\\\ 4,\\ sand\\end{array} \\right .$$\n",
+    "\n",
+    "$$K_{H0} = \\left \\{ \\begin{array} 0.001,\\ clay\\\\ 0.1,\\ sand \\end{array} \\right .$$\n",
+    "\n",
+    "and\n",
+    "$$K_{HD} = \\left ( \\frac{-4K_{H0}B\\Psi_0\\rho_wX_v(1 - W_{F,u})}{\\pi\\Delta t}\\right )$$\n",
+    "\n",
+    "where \n",
+    "* $\\rho_w$ is the density of the water \n",
+    "* $\\Psi_0 = -0.2m$ for all soil types is the soil suction at saturation.\n",
+    "* $\\Delta t$ is the model time step\n",
+    "* $\\pi$ is the constant.\n",
+    "\n",
+    "$\\Theta_u$ is defined as\n",
+    "\n",
+    "$$\\Theta_u  = \\frac{W_{L,u} - 0.01}{1 - W_{F,u}}$$\n",
+    "\n",
+    "The wetness factors $W_{L,x}$ in the soil in the upper and lower layers is **NOT** allowed to fall below 0.01 due to physical and numerical issues.\n",
+    "\n",
+    "### Momentum fluxes\n",
+    "\n",
+    "are directly calculated from the momentum bulk coefficient\n",
+    "$$U_s = -\\rho_s C_{Dm}U_mu$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Surface energy balance\n",
+    "\n",
+    "The energy balance is straightforward once the latent and sensible heat fluxes are known.\n",
+    "Adding the radiative fluxes completes the balance.\n",
+    "\n",
+    "$$Net = Net_{SW} + Net_{LW} - LHF - SHF$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Moisture and heat conduction through snow, ice and soil\n",
+    "\n",
+    "The transfer of heat and moisture through the snow-ice-soil pack requires solving\n",
+    "the diffusion equation along with local sources and sinks of heat and moisture which \n",
+    "\n",
+    "### Heat conductivity"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.5.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}