diff --git a/config_src/solo_driver/Neverland_surface_forcing.F90 b/config_src/solo_driver/Neverland_surface_forcing.F90 index 55476f9051..65a5ca1339 100644 --- a/config_src/solo_driver/Neverland_surface_forcing.F90 +++ b/config_src/solo_driver/Neverland_surface_forcing.F90 @@ -22,9 +22,10 @@ module Neverland_surface_forcing public Neverland_surface_forcing_init !> This control structure should be used to store any run-time variables -!! associated with the Neverland forcing. It can be readily modified -!! for a specific case, and because it is private there will be no changes -!! needed in other code (although they will have to be recompiled). +!! associated with the Neverland forcing. +!! +!! It can be readily modified for a specific case, and because it is private there +!! will be no changes needed in other code (although they will have to be recompiled). type, public :: Neverland_surface_forcing_CS ; private logical :: use_temperature !< If true, use temperature and salinity. diff --git a/config_src/solo_driver/user_surface_forcing.F90 b/config_src/solo_driver/user_surface_forcing.F90 index 201723933f..e0136abf0f 100644 --- a/config_src/solo_driver/user_surface_forcing.F90 +++ b/config_src/solo_driver/user_surface_forcing.F90 @@ -1,48 +1,8 @@ +!> Template for user to code up surface forcing. module user_surface_forcing ! This file is part of MOM6. See LICENSE.md for the license. -!********+*********+*********+*********+*********+*********+*********+** -!* * -!* Rewritten by Robert Hallberg, June 2009 * -!* * -!* This file contains the subroutines that a user should modify to * -!* to set the surface wind stresses and fluxes of buoyancy or * -!* temperature and fresh water. They are called when the run-time * -!* parameters WIND_CONFIG or BUOY_CONFIG are set to "USER". The * -!* standard version has simple examples, along with run-time error * -!* messages that will cause the model to abort if this code has not * -!* been modified. This code is intended for use with relatively * -!* simple specifications of the forcing. For more complicated forms, * -!* it is probably a good idea to read the forcing from input files * -!* using "file" for WIND_CONFIG and BUOY_CONFIG. * -!* * -!* USER_wind_forcing should set the surface wind stresses (taux and * -!* tauy) perhaps along with the surface friction velocity (ustar). * -!* * -!* USER_buoyancy forcing is used to set the surface buoyancy * -!* forcing, which may include a number of fresh water flux fields * -!* (evap, lprec, fprec, lrunoff, frunoff, and * -!* vprec) and the surface heat fluxes (sw, lw, latent and sens) * -!* if temperature and salinity are state variables, or it may simply * -!* be the buoyancy flux if it is not. This routine also has coded a * -!* restoring to surface values of temperature and salinity. * -!* * -!* Macros written all in capital letters are defined in MOM_memory.h. * -!* * -!* A small fragment of the grid is shown below: * -!* * -!* j+1 x ^ x ^ x At x: q * -!* j+1 > o > o > At ^: v, tauy * -!* j x ^ x ^ x At >: u, taux * -!* j > o > o > At o: h, fluxes. * -!* j-1 x ^ x ^ x * -!* i-1 i i+1 At x & ^: * -!* i i+1 At > & o: * -!* * -!* The boundaries always run through q grid points (x). * -!* * -!********+*********+*********+*********+*********+*********+*********+** use MOM_diag_mediator, only : post_data, query_averaging_enabled use MOM_diag_mediator, only : register_diag_field, diag_ctrl, safe_alloc_ptr use MOM_domains, only : pass_var, pass_vector, AGRID @@ -62,9 +22,10 @@ module user_surface_forcing public USER_wind_forcing, USER_buoyancy_forcing, USER_surface_forcing_init !> This control structure should be used to store any run-time variables -!! associated with the user-specified forcing. It can be readily modified -!! for a specific case, and because it is private there will be no changes -!! needed in other code (although they will have to be recompiled). +!! associated with the user-specified forcing. +!! +!! It can be readily modified for a specific case, and because it is private there +!! will be no changes needed in other code (although they will have to be recompiled). type, public :: user_surface_forcing_CS ; private ! The variables in the cannonical example are used for some common ! cases, but do not need to be used. @@ -360,4 +321,28 @@ subroutine USER_surface_forcing_init(Time, G, param_file, diag, CS) end subroutine USER_surface_forcing_init +!! \namespace user_surface_forcing +!! +!! This file contains the subroutines that a user should modify to +!! to set the surface wind stresses and fluxes of buoyancy or +!! temperature and fresh water. They are called when the run-time +!! parameters WIND_CONFIG or BUOY_CONFIG are set to "USER". The +!! standard version has simple examples, along with run-time error +!! messages that will cause the model to abort if this code has no +!! been modified. This code is intended for use with relatively +!! simple specifications of the forcing. For more complicated forms, +!! it is probably a good idea to read the forcing from input files +!! using "file" for WIND_CONFIG and BUOY_CONFIG. +!! +!! USER_wind_forcing() should set the surface wind stresses (taux and +!! tauy) perhaps along with the surface friction velocity (ustar). +!! +!! USER_buoyancy() forcing is used to set the surface buoyancy +!! forcing, which may include a number of fresh water flux fields +!! (evap, lprec, fprec, lrunoff, frunoff, and +!! vprec) and the surface heat fluxes (sw, lw, latent and sens) +!! if temperature and salinity are state variables, or it may simply +!! be the buoyancy flux if it is not. This routine also has coded a +!! restoring to surface values of temperature and salinity. + end module user_surface_forcing diff --git a/src/ALE/MOM_ALE.F90 b/src/ALE/MOM_ALE.F90 index eede57808b..a71dfb557c 100644 --- a/src/ALE/MOM_ALE.F90 +++ b/src/ALE/MOM_ALE.F90 @@ -1,8 +1,10 @@ !> This module contains the main regridding routines. +!! !! Regridding comprises two steps: -!! (1) Interpolation and creation of a new grid based on target interface -!! densities (or any other criterion). -!! (2) Remapping of quantities between old grid and new grid. +!! 1. Interpolation and creation of a new grid based on target interface +!! densities (or any other criterion). +!! 2. Remapping of quantities between old grid and new grid. +!! !! Original module written by Laurent White, 2008.06.09 module MOM_ALE diff --git a/src/core/MOM_forcing_type.F90 b/src/core/MOM_forcing_type.F90 index fa4295006c..9486967b40 100644 --- a/src/core/MOM_forcing_type.F90 +++ b/src/core/MOM_forcing_type.F90 @@ -33,10 +33,11 @@ module MOM_forcing_type public set_derived_forcing_fields, copy_back_forcing_fields, set_net_mass_forcing !> Structure that contains pointers to the boundary forcing used to drive the -!! liquid ocean simulated by MOM. Data in this type is allocated in the module -!! MOM_surface_forcing.F90, of which there are three: solo, coupled, and -!! ice-shelf. Alternatively, they are allocated in MESO_surface_forcing.F90, -!! which is a special case of solo_driver/MOM_surface_forcing.F90. +!! liquid ocean simulated by MOM. +!! +!! Data in this type is allocated in the module MOM_surface_forcing.F90, of which there +!! are three: solo, coupled, and ice-shelf. Alternatively, they are allocated in +!! MESO_surface_forcing.F90, which is a special case of solo_driver/MOM_surface_forcing.F90. type, public :: forcing ! Pointers in this module should be initialized to NULL. diff --git a/src/core/MOM_variables.F90 b/src/core/MOM_variables.F90 index 343c5e6793..d176b407d3 100644 --- a/src/core/MOM_variables.F90 +++ b/src/core/MOM_variables.F90 @@ -27,8 +27,7 @@ module MOM_variables real, dimension(:,:), pointer :: p => NULL() !< A pointer to a 2D array end type p2d -!> The following structure contains pointers to various fields -!! which may be used describe the surface state of MOM, and which +!> Pointers to various fields which may be used describe the surface state of MOM, and which !! will be returned to a the calling program type, public :: surface real, allocatable, dimension(:,:) :: & @@ -69,9 +68,8 @@ module MOM_variables !! has had its memory allocated. end type surface -!> The thermo_var_ptrs structure contains pointers to an assortment of -!! thermodynamic fields that may be available, including potential temperature, -!! salinity, heat capacity, and the equation of state control structure. +!> Pointers to an assortment of thermodynamic fields that may be available, including +!! potential temperature, salinity, heat capacity, and the equation of state control structure. type, public :: thermo_var_ptrs ! If allocated, the following variables have nz layers. real, pointer :: T(:,:,:) => NULL() !< Potential temperature in C. @@ -111,9 +109,9 @@ module MOM_variables !! calculate_surface_state, in units of deg C kg m-2. end type thermo_var_ptrs -!> The ocean_internal_state structure contains pointers to all of the prognostic -!! variables allocated in MOM_variables.F90 and MOM.F90. It is useful for -!! sending these variables for diagnostics, and in preparation for ensembles +!> Pointers to all of the prognostic variables allocated in MOM_variables.F90 and MOM.F90. +!! +!! It is useful for sending these variables for diagnostics, and in preparation for ensembles !! later on. All variables have the same names as the local (public) variables !! they refer to in MOM.F90. type, public :: ocean_internal_state @@ -143,11 +141,10 @@ module MOM_variables v_prev => NULL() !< Pointer to meridional velocity at the end of the last timestep end type ocean_internal_state -!> The accel_diag_ptrs structure contains pointers to arrays with accelerations, -!! which can later be used for derived diagnostics, like energy balances. +!> Pointers to arrays with accelerations, which can later be used for derived diagnostics, like energy balances. type, public :: accel_diag_ptrs -! Each of the following fields has nz layers. + ! Each of the following fields has nz layers. real, pointer, dimension(:,:,:) :: & diffu => NULL(), & !< Zonal acceleration due to along isopycnal viscosity, in m s-2. diffv => NULL(), & !< Meridional acceleration due to along isopycnal viscosity, in m s-2. @@ -174,8 +171,7 @@ module MOM_variables end type accel_diag_ptrs -!> The cont_diag_ptrs structure contains pointers to arrays with transports, -!! which can later be used for derived diagnostics, like energy balances. +!> Pointers to arrays with transports, which can later be used for derived diagnostics, like energy balances. type, public :: cont_diag_ptrs ! Each of the following fields has nz layers. @@ -190,8 +186,7 @@ module MOM_variables end type cont_diag_ptrs -!> The vertvisc_type structure contains vertical viscosities, drag -!! coefficients, and related fields. +!> Vertical viscosities, drag coefficients, and related fields. type, public :: vertvisc_type real :: Prandtl_turb !< The Prandtl number for the turbulent diffusion !! that is captured in Kd_shear. @@ -256,8 +251,8 @@ module MOM_variables !! at the interfaces. This is done in find_coupling_coef. end type vertvisc_type -!> The BT_cont_type structure contains information about the summed layer -!! transports and how they will vary as the barotropic velocity is changed. +!> Container for information about the summed layer transports +!! and how they will vary as the barotropic velocity is changed. type, public :: BT_cont_type real, allocatable :: FA_u_EE(:,:) !< The effective open face area for zonal barotropic transport !! drawing from locations far to the east, in H m. @@ -291,8 +286,8 @@ module MOM_variables contains -!> This subroutine allocates the fields for the surface (return) properties of -!! the ocean model. Unused fields are unallocated. +!> Allocates the fields for the surface (return) properties of +!! the ocean model. Unused fields are unallocated. subroutine allocate_surface_state(sfc_state, G, use_temperature, do_integrals, & gas_fields_ocn) type(ocean_grid_type), intent(in) :: G !< ocean grid structure @@ -350,7 +345,7 @@ subroutine allocate_surface_state(sfc_state, G, use_temperature, do_integrals, & end subroutine allocate_surface_state -!> This subroutine deallocates the elements of a surface state type. +!> Deallocates the elements of a surface state type. subroutine deallocate_surface_state(sfc_state) type(surface), intent(inout) :: sfc_state !< ocean surface state type to be deallocated. @@ -374,8 +369,7 @@ subroutine deallocate_surface_state(sfc_state) end subroutine deallocate_surface_state -!> alloc_BT_cont_type allocates the arrays contained within a BT_cont_type and -!! initializes them to 0. +!> Allocates the arrays contained within a BT_cont_type and initializes them to 0. subroutine alloc_BT_cont_type(BT_cont, G, alloc_faces) type(BT_cont_type), pointer :: BT_cont !< The BT_cont_type whose elements will be allocated type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure @@ -411,7 +405,7 @@ subroutine alloc_BT_cont_type(BT_cont, G, alloc_faces) end subroutine alloc_BT_cont_type -!> dealloc_BT_cont_type deallocates the arrays contained within a BT_cont_type. +!> Deallocates the arrays contained within a BT_cont_type. subroutine dealloc_BT_cont_type(BT_cont) type(BT_cont_type), pointer :: BT_cont !< The BT_cont_type whose elements will be deallocated. @@ -432,8 +426,7 @@ subroutine dealloc_BT_cont_type(BT_cont) end subroutine dealloc_BT_cont_type -!> MOM_thermovar_chksum does diagnostic checksums on various elements of a -!! thermo_var_ptrs type for debugging. +!> Diagnostic checksums on various elements of a thermo_var_ptrs type for debugging. subroutine MOM_thermovar_chksum(mesg, tv, G) character(len=*), intent(in) :: mesg !< A message that appears in the checksum lines type(thermo_var_ptrs), intent(in) :: tv !< A structure pointing to various thermodynamic variables diff --git a/src/framework/MOM_coms.F90 b/src/framework/MOM_coms.F90 index 7b468d1964..40ea23945e 100644 --- a/src/framework/MOM_coms.F90 +++ b/src/framework/MOM_coms.F90 @@ -47,9 +47,11 @@ module MOM_coms end interface reproducing_sum !> The Extended Fixed Point (EFP) type provides a public interface for doing sums -!! and taking differences with this type. The use of this type is documented in +!! and taking differences with this type. +!! +!! The use of this type is documented in !! Hallberg, R. & A. Adcroft, 2014: An Order-invariant Real-to-Integer Conversion Sum. -!! Parallel Computing, 40(5-6), doi:10.1016/j.parco.2014.04.007. +!! Parallel Computing, 40(5-6), doi:10.1016/j.parco.2014.04.007. type, public :: EFP_type ; private integer(kind=8), dimension(ni) :: v !< The value in this type end type EFP_type diff --git a/src/framework/MOM_diag_mediator.F90 b/src/framework/MOM_diag_mediator.F90 index a309a32a59..b87cc71b7a 100644 --- a/src/framework/MOM_diag_mediator.F90 +++ b/src/framework/MOM_diag_mediator.F90 @@ -127,6 +127,7 @@ module MOM_diag_mediator end type diag_grid_storage !> This type is used to represent a diagnostic at the diag_mediator level. +!! !! There can be both 'primary' and 'seconday' diagnostics. The primaries !! reside in the diag_cs%diags array. They have an id which is an index !! into this array. The secondaries are 'variations' on the primary diagnostic. diff --git a/src/framework/MOM_diag_remap.F90 b/src/framework/MOM_diag_remap.F90 index dd21aabe3f..737e7a3fbf 100644 --- a/src/framework/MOM_diag_remap.F90 +++ b/src/framework/MOM_diag_remap.F90 @@ -1,15 +1,17 @@ -!> This module is used for runtime remapping of diagnostics to z star, sigma and -!! rho vertical coordinates. It defines the diag_remap_ctrl type which -!! represents a remapping of diagnostics to a particular vertical coordinate. -!! The module is used by the diag mediator module in the following way: -!! 1) _init() is called to initialise a diag_remap_ctrl instance. -!! 2) _configure_axes() is called to read the configuration file and set up the +!> provides runtime remapping of diagnostics to z star, sigma and +!! rho vertical coordinates. +!! +!! The diag_remap_ctrl type represents a remapping of diagnostics to a particular +!! vertical coordinate. The module is used by the diag mediator module in the +!! following way: +!! 1. diag_remap_init() is called to initialize a diag_remap_ctrl instance. +!! 2. diag_remap_configure_axes() is called to read the configuration file and set up the !! vertical coordinate / axes definitions. -!! 3) _get_axes_info() returns information needed for the diag mediator to +!! 3. diag_remap_get_axes_info() returns information needed for the diag mediator to !! define new axes for the remapped diagnostics. -!! 4) _update() is called periodically (whenever h, T or S change) to either +!! 4. diag_remap_update() is called periodically (whenever h, T or S change) to either !! create or update the target remapping grids. -!! 5) _do_remap() is called from within a diag post() to do the remapping before +!! 5. diag_remap_do_remap() is called from within a diag post() to do the remapping before !! the diagnostic is written out. module MOM_diag_remap @@ -53,8 +55,8 @@ module MOM_diag_remap public vertically_interpolate_diag_field public horizontally_average_diag_field -!> This type represents remapping of diagnostics to a particular vertical -!! coordinate. +!> Represents remapping of diagnostics to a particular vertical coordinate. +!! !! There is one of these types for each vertical coordinate. The vertical axes !! of a diagnostic will reference an instance of this type indicating how (or !! if) the diagnostic should be vertically remapped when being posted. diff --git a/src/parameterizations/vertical/MOM_ALE_sponge.F90 b/src/parameterizations/vertical/MOM_ALE_sponge.F90 index 631adfe57b..ec285072ed 100644 --- a/src/parameterizations/vertical/MOM_ALE_sponge.F90 +++ b/src/parameterizations/vertical/MOM_ALE_sponge.F90 @@ -1,11 +1,12 @@ !> This module contains the routines used to apply sponge layers when using !! the ALE mode. +!! !! Applying sponges requires the following: -!! (1) initialize_ALE_sponge -!! (2) set_up_ALE_sponge_field (tracers) and set_up_ALE_sponge_vel_field (vel) -!! (3) apply_ALE_sponge -!! (4) init_ALE_sponge_diags (not being used for now) -!! (5) ALE_sponge_end (not being used for now) +!! 1. initialize_ALE_sponge +!! 2. set_up_ALE_sponge_field (tracers) and set_up_ALE_sponge_vel_field (vel) +!! 3. apply_ALE_sponge +!! 4. init_ALE_sponge_diags (not being used for now) +!! 5. ALE_sponge_end (not being used for now) module MOM_ALE_sponge @@ -40,6 +41,7 @@ module MOM_ALE_sponge end interface !> Ddetermine the number of points which are within sponges in this computational domain. +!! !! Only points that have positive values of Iresttime and which mask2dT indicates are ocean !! points are included in the sponges. It also stores the target interface heights. interface initialize_ALE_sponge diff --git a/src/tracer/ISOMIP_tracer.F90 b/src/tracer/ISOMIP_tracer.F90 index 6864b2ce19..40e8ef6db5 100644 --- a/src/tracer/ISOMIP_tracer.F90 +++ b/src/tracer/ISOMIP_tracer.F90 @@ -1,20 +1,14 @@ -!> This module contains the routines used to set up and use a set of (one for now) -!! dynamically passive tracers. For now, just one passive tracer is injected in +!> Routines used to set up and use a set of (one for now) +!! dynamically passive tracers in the ISOMIP configuration. +!! +!! For now, just one passive tracer is injected in !! the sponge layer. -!! Set up and use passive tracers requires the following: -!! (1) register_ISOMIP_tracer -!! (2) module ISOMIP_tracer ! This file is part of MOM6. See LICENSE.md for the license. -!********+*********+*********+*********+*********+*********+*********+** -!* * -!* Original sample tracer package by Robert Hallberg, 2002 * -!* Adapted to the ISOMIP test case by Gustavo Marques, May 2016 * -!* * -!********+*********+*********+*********+*********+*********+*********+** - +! Original sample tracer package by Robert Hallberg, 2002 +! Adapted to the ISOMIP test case by Gustavo Marques, May 2016 use MOM_diag_mediator, only : diag_ctrl use MOM_diag_to_Z, only : diag_to_Z_CS diff --git a/src/tracer/dyed_obc_tracer.F90 b/src/tracer/dyed_obc_tracer.F90 index 2e8da7299f..20a68c9d21 100644 --- a/src/tracer/dyed_obc_tracer.F90 +++ b/src/tracer/dyed_obc_tracer.F90 @@ -268,35 +268,19 @@ subroutine dyed_obc_tracer_end(CS) end subroutine dyed_obc_tracer_end !> \namespace dyed_obc_tracer -!! * -!! By Kate Hedstrom, 2017, copied from DOME tracers and also * -!! dye_example. * -!! * -!! This file contains an example of the code that is needed to set * -!! up and use a set of dynamically passive tracers. These tracers * -!! dye the inflowing water, one per open boundary segment. * -!! * -!! A single subroutine is called from within each file to register * -!! each of the tracers for reinitialization and advection and to * -!! register the subroutine that initializes the tracers and set up * -!! their output and the subroutine that does any tracer physics or * -!! chemistry along with diapycnal mixing (included here because some * -!! tracers may float or swim vertically or dye diapycnal processes). * -!! * -!! Macros written all in capital letters are defined in MOM_memory.h. * -!! * -!! A small fragment of the grid is shown below: * -!! * -!! j+1 x ^ x ^ x At x: q * -!! j+1 > o > o > At ^: v * -!! j x ^ x ^ x At >: u * -!! j > o > o > At o: h, tr * -!! j-1 x ^ x ^ x * -!! i-1 i i+1 At x & ^: * -!! i i+1 At > & o: * -!! * -!! The boundaries always run through q grid points (x). * -!! * -!!*******+*********+*********+*********+*********+*********+*********+** +!! +!! By Kate Hedstrom, 2017, copied from DOME tracers and also +!! dye_example. +!! +!! This file contains an example of the code that is needed to set +!! up and use a set of dynamically passive tracers. These tracers +!! dye the inflowing water, one per open boundary segment. +!! +!! A single subroutine is called from within each file to register +!! each of the tracers for reinitialization and advection and to +!! register the subroutine that initializes the tracers and set up +!! their output and the subroutine that does any tracer physics or +!! chemistry along with diapycnal mixing (included here because some +!! tracers may float or swim vertically or dye diapycnal processes). end module dyed_obc_tracer