Feature/doc ug

doc/description/pbl_turbulence.tex

@@ -81,7 +81,7 @@ \subsection{Basic formulation of PBL parameterizations}
 
 \subsection{Mellor--Yamada Nakanishi--Niino (MYNN) level 2.0 model}
 %%
-This model employs the local-equilibrium form of the MYNN second-moment closure.
+This model employs the local-equilibrium form of the MYNN second-moment closure \citep{Nakanishi2006}.
 In this model, the turbulent velocity scale $q$ is diagnosed from the local balance of turbulent kinetic energy (TKE), 
 rather than predicted from a time-dependent TKE equation.
 The local TKE balance is written as

doc/user-guide/11_introduction.tex

@@ -132,7 +132,7 @@ \subsubsection{Framework}
   %  \begin{itemize}
   %  \item Selection of {\netcdf}3 and {\netcdf}4 formats
   %  \end{itemize}
- \item Generation of initial data for an ideal experiment
+ \item Generation of initial data for idealized experiments
 %  \item Generation of topographical and land-use data, converted from external data
 %  \item Generation of initial and boundary data from external data
   %  \begin{itemize}
@@ -171,6 +171,7 @@ \subsubsection{Physical processes}
   \item \citet{smagorinsky1963general} \& \citet{lilly1962numerical}-type sub-grid scale turbulent model
     with the corrections by \citet{brown1994largeeddy} and \citet{Scotti_1993}
   % \item \citet{Deardorff_1980} sub-grid scale turbulent model
+  \item MYNN level 2.0 boundary layer scheme 
   % \item MYNN level 2.5 boundary scheme ( \citet{my_1982,nakanishi_2004,nakanishi_2009} )
   \end{itemize}
 \item Cloud microphysics: selectable from among the following
@@ -179,17 +180,27 @@ \subsubsection{Physical processes}
   \item 6-class 1 moment bulk scheme \citep{tomita_2008}
 % \item 6-class 2 moment bulk scheme \citep{sn_2014}
 %  \item spectral bin scheme \citep{suzuki_etal_2010}
+   \item Large-scale condensation scheme
   \end{itemize}
-% \item Radiation process: a k-distribution-based broadband radiation transfer model ( \citet{sekiguchi_2008} )
-\item Surface models
+\item Cumulus process
+  \begin{itemize}
+  \item Moist convective adjustment
+  \end{itemize}
+\item Radiation process: selectable from among the following
+  \begin{itemize}
+    \item Gray radiation scheme
+    \item Two-band infrared and one-band solar radiation scheme
+%  \item a k-distribution-based broadband radiation transfer model ( \citet{sekiguchi_2008} )
+  \end{itemize}
+\item Surface processes
   \begin{itemize}
   % \item Land model: heat diffusion/bucket model
-  % \item Ocean model: selectable from among the following
-  %   \begin{itemize}
-  %   \item fixed to initial condition
-  %   \item input from external data
-  %   \item slab model
-  %   \end{itemize}
+    \item Ocean model: selectable from among the following
+    \begin{itemize}
+      \item Fixed to initial condition
+  %   \item Input from external data
+      \item Slab model
+    \end{itemize}
   % \item Urban model: a single-layer canopy model \citep{kusaka_2001}
   % \item Heat transfer coefficient at surface: selectable from among the following
   %   \begin{itemize}

doc/user-guide/58_setting_physics_bl.tex

@@ -0,0 +1,48 @@
+%Setting the physical process
+
+\section{Planetary Boundary Layer Scheme} \label{sec:basic_usel_pbl}
+%------------------------------------------------------
+The planetary boundary layer (PBL) scheme parameterizes vertical turbulent mixing in the atmospheric boundary layer.
+It is intended for Reynolds-averaged Navier--Stokes (RANS) simulations.
+The PBL process is configured by two namelists.
+First, the PBL component is enabled by
+\nmitem{ATMOS_PHY_BL_DO} in \namelist{PARAM_ATMOS}.
+Then, the PBL scheme and its calling interval are specified in \namelist{PARAM_ATMOS_PHY_BL}.
+
+\editboxtwo{
+ \verb|&PARAM_ATMOS | & \\
+ \verb|ATMOS_PHY_BL_DO = .true.,| & ; Enable planetary boundary layer parameterization \\
+ \verb|/ | & \\
+}
+\editboxtwo{
+ \verb|&PARAM_ATMOS_PHY_BL | & \\
+ \verb|BL_TYPE      = "MYNN_LEVEL2",| & ; Choose from PBL schemes in Table \ref{tab:bl_scheme_list} \\
+ \verb|TIME_DT      = 600.D0,|      & ; Time interval of PBL process \\
+ \verb|TIME_DT_UNIT = "SEC",|      & ; Unit for \verb|TIME_DT| \\
+ \verb|/ | & \\
+}
+
+The available choices of \nmitem{BL_TYPE} are listed in Table \ref{tab:bl_scheme_list}.
+
+%%%%%%%%%%%
+\begin{table}[htbp]
+\caption{Planetary boundary layer schemes available in \scaledg.}
+\label{tab:bl_scheme_list}
+\begin{center}
+\begin{tabularx}{150mm}{lXX}
+\hline
+\rowcolor[gray]{0.9}
+\verb|BL_TYPE| & Description & Reference \\
+\hline
+\verb|MYNN_LEVEL2|  & MYNN level 2 scheme & \cite{Nakanishi2006} \\
+\hline
+\end{tabularx}
+\end{center}
+\end{table}
+%%%%%%%%%%%
+
+%------------------------------------------------------
+\subsection{MYNN level 2 scheme}
+\label{subsec:physics_bl_mynn}
+The current implementation provides the Mellor--Yamada--Nakanishi--Niino (MYNN) level 2 turbulence closure scheme\cite{Nakanishi2006}.
+The MYNN level 2 scheme diagnoses turbulent diffusion coefficients for momentum and scalars from the local stability of the atmosphere and applies vertical turbulent mixing within the planetary boundary layer.

doc/user-guide/58_setting_physics_mp.tex

@@ -34,7 +34,7 @@ \section{Cloud Micro-Physics} \label{sec:basic_usel_microphys}
 refer to the SCALE-RM User's Guide.
 
 %%%%%%%%%%%
-\begin{table}[t]
+\begin{table}[htbp]
 \caption{Cloud microphysics schemes available in \scaledg.}
 \label{tab:mp_scheme_list}
 \begin{center}

doc/user-guide/58_setting_physics_ocn.tex

@@ -0,0 +1,156 @@
+%-------------------------------------------------------------------------------
+\section{Ocean model} \label{sec:basic_usel_ocean}
+%-------------------------------------------------------------------------------
+
+The ocean component is activated and configured in \namelist{PARAM_OCEAN}.
+The computational mesh for the ocean component is selected by \nmitem{OCEAN_MESH_TYPE}, 
+and the ocean dynamics is enabled by \nmitem{OCEAN_DYN_DO}.
+
+\editboxtwo{
+ \verb|&PARAM_OCEAN | & \\
+ \verb|ACTIVATE_FLAG   = .true.,|     & ; Enable the ocean component \\
+ \verb|OCEAN_MESH_TYPE = "GLOBAL",|   & ; Type of ocean mesh: REGIONAL or GLOBAL \\
+ \verb|OCEAN_DYN_DO    = .true.,|     & ; Enable ocean dynamics \\
+ \verb|TIME_DT          = 3600.D0,|   & ; Time step of the ocean component \\
+ \verb|TIME_DT_UNIT     = "SEC",|      & ; Unit for \verb|TIME_DT| \\
+ \verb|/ | & \\
+}
+
+\nmitem{OCEAN_MESH_TYPE} can be set to \verb|"REGIONAL"| or \verb|"GLOBAL"|.
+
+
+%-------------------------------------------------------------------------------
+\subsection{Setting grids for ocean model}
+\label{subsec:ocean_mesh}
+%-------------------------------------------------------------------------------
+
+The computational grid of the ocean model is configured in \namelist{PARAM_OCEAN_MESH}.
+The available parameters depend on the mesh type selected by \nmitem{OCEAN_MESH_TYPE} in \namelist{PARAM_OCEAN}.
+
+At present, the horizontal mesh configuration of the ocean component must be identical to that of the atmospheric component.
+Therefore, the horizontal domain size, MPI decomposition, number of horizontal elements, and horizontal polynomial order should be specified consistently for both components.
+This restriction arises from the present atmosphere--ocean coupling,
+which exchanges two-dimensional fields without horizontal remapping.
+
+
+%------------------------------------------------------------------------
+\subsubsection{Regional mesh}
+%------------------------------------------------------------------------
+
+For the regional ocean model using the Cartesian coordinates,
+the computational domain and DG mesh are specified in \namelist{PARAM_OCEAN_MESH}.
+
+\editboxtwo{
+ \verb|&PARAM_OCEAN_MESH | & \\
+ \verb|NprcX       = 1,|       & ; Number of MPI processes in the x-direction \\
+ \verb|NprcY       = 1,|       & ; Number of MPI processes in the y-direction \\
+ \verb|NeX         = 2,|       & ; Number of elements in x per MPI process \\
+ \verb|NeY         = 2,|       & ; Number of elements in y per MPI process \\
+ \verb|NeZ         = 1,|       & ; Number of vertical elements \\
+ \verb|dom_xmin    = 0.D0,|    & ; Minimum x-coordinate [m] \\
+ \verb|dom_xmax    = 100.D3,|  & ; Maximum x-coordinate [m] \\
+ \verb|dom_ymin    = 0.D0,|    & ; Minimum y-coordinate [m] \\
+ \verb|dom_ymax    = 100.D3,|  & ; Maximum y-coordinate [m] \\
+ \verb|dom_zmin    = 0.D0,|    & ; Minimum vertical coordinate [m] \\
+ \verb|dom_zmax    = 50.D0,|   & ; Maximum vertical coordinate [m] \\
+ \verb|PolyOrder_h = 2,|       & ; Horizontal polynomial order \\
+ \verb|PolyOrder_v = 1,|       & ; Vertical polynomial order \\
+ \verb|/ | & \\
+}
+
+An arbitrary non-uniform element spacing can also be specified in the vertical direction by giving the locations of all element boundaries using \nmitem{FZ}.
+\editboxtwo{
+ \verb|&PARAM_OCEAN_MESH | & \\
+ \verb|FZ = 0.D0, 10.D0, 50.D0,| & ; Vertical element boundaries [m] \\
+ \verb|/ | & \\
+}
+
+%------------------------------------------------------------------------
+\subsubsection{Global mesh}
+%------------------------------------------------------------------------
+
+For the global ocean model using the cubed-sphere coordinates,
+the grid is also configured in \namelist{PARAM_OCEAN_MESH}.
+
+\editboxtwo{
+ \verb|&PARAM_OCEAN_MESH | & \\
+ \verb|Nprc                    = 6,|      & ; Total number of MPI processes \\
+ \verb|NeGX                    = 6,|      & ; Number of elements in each cubed-sphere panel \\
+ \verb|NeGY                    = 6,|      & ; Number of elements in each cubed-sphere panel \\
+ \verb|NeZ                     = 1,|      & ; Number of vertical elements \\
+ \verb|PolyOrder_h             = 2,|      & ; Horizontal polynomial order \\
+ \verb|PolyOrder_v             = 1,|      & ; Vertical polynomial order \\
+ \verb|dom_zmin                = 0.D0,|   & ; Minimum vertical coordinate [m] \\
+ \verb|dom_zmax                = 50.D0,|  & ; Maximum vertical coordinate [m] \\
+ \verb|SHALLOW_OCN_APPROX_FLAG = .true.,| & ; Apply shallow-ocean approximation \\
+ \verb|/ | & \\
+}
+
+%-------------------------------------------------------------------------------
+\subsection{Ocean-model configurations}
+\label{subsec:ocean_model_config}
+%-------------------------------------------------------------------------------
+
+Currently, SCALE-DG provides two ocean-model options: the slab ocean model and a fixed sea-surface temperature option.
+The slab ocean model predicts the mixed-layer temperature by solving the heat budget of a prescribed mixed layer, 
+while the fixed-temperature option keeps the initial sea-surface temperature unchanged throughout the simulation.
+These are configured in \namelist{PARAM_OCEAN_DYN}.
+
+A typical configuration is
+%%
+\editboxtwo{
+ \verb|&PARAM_OCEAN_DYN | & \\
+ \verb|EQS_TYPE      = "SLAB",| & ; Ocean model; SLAB or FIXED\_INIT\_TEMP \\
+ \verb|TIME_DT       = 3600.D0,| & ; Time interval of ocean dynamics \\
+ \verb|TIME_DT_UNIT  = "SEC",| & ; Unit for \verb|TIME_DT| \\
+ \verb|/ | & \\
+}
+When \verb|EQS_TYPE="SLAB"| is selected, the ocean temperature evolves according to the heat budget of the slab ocean.
+When \verb|EQS_TYPE="FIXED_INIT_TEMP"| is selected, the initially specified ocean temperature is kept fixed.
+For the slab ocean model, the temperature is advanced with a forward Euler method using \nmitem{TIME_DT}. 
+
+
+\subsubsection{Note}
+For the slab ocean model, the ocean temperature is assumed to be vertically uniform.
+Therefore, a zeroth-order polynomial would be the natural choice in the vertical direction.
+However, the current mesh implementation does not support \verb|PolyOrder_v=0|.
+Thus, \nmitem{PolyOrder_v} must be set to one or larger.
+
+Although multiple vertical nodal values are therefore retained redundantly, 
+the slab-ocean temperature tendency is applied uniformly to all vertical degrees of freedom, so that the slab-ocean calculation is effectively vertically uniform.
+
+%-------------------------------------------------------------------------------
+\subsection{Surface fluxes and atmosphere--ocean exchange}
+\label{subsec:ocean_surface_flux}
+%-------------------------------------------------------------------------------
+
+
+For the surface-flux calculation, the ocean component receives the near-surface atmospheric state from the atmosphere through the coupler,
+including density, pressure, temperature, wind velocity, specific humidity, and the thickness of the lowest atmospheric layer.
+The downward direct shortwave and downward diffuse longwave radiative fluxes are also passed from the atmospheric radiation component to the ocean component.
+
+
+Using these atmospheric quantities together with the ocean surface temperature, 
+the ocean component calculates the surface momentum, sensible-heat, latent-heat, and water-vapor fluxes using surface-flux schemes.
+The ocean surface temperature and these surface fluxes are then returned
+to the atmospheric component through the coupler and used as the lower boundary condition of the atmosphere.
+
+
+In the current SCALE-DG, the ocean surface fluxes are calculated using the simple bulk surface-flux scheme described in Section~\ref{subsec:physics_sf_simple}.
+The same module and its parameters are shared with the atmospheric surface-flux component.
+Therefore, the atmospheric surface-flux component should be enabled
+and the simple bulk scheme should be selected as follows:
+\editboxtwo{
+ \verb|&PARAM_ATMOS | & \\
+ \verb|ATMOS_PHY_SF_DO = .true.,| & ; Enable the surface-flux component \\
+ \verb|/ | & \\
+}
+\editboxtwo{
+ \verb|&PARAM_ATMOS_PHY_SFC | & \\
+ \verb|SFCFLX_TYPE = "SIMPLE",| & ; Use the simple bulk surface-flux scheme \\
+ \verb|TIME_DT      = 600.D0,|   & ; Time interval of the atmospheric surface process \\
+ \verb|TIME_DT_UNIT = "SEC",|    & ; Unit for \verb|TIME_DT| \\
+ \verb|/ | & \\
+}
+The parameters of the simple bulk surface-flux scheme are specified in \namelist{PARAM_ATMOS_PHY_SF_SIMPLE}. 
+See Section~\ref{subsec:physics_sf_simple} for details.