Skip to content

Commit

Permalink
Module dOxyGenization for framework code
Browse files Browse the repository at this point in the history 
  Added dOxygen comments describing the various MOM6 framework modules,
including extended documentation at the end of some of these modules.  All
answers are bitwise identical.
  • Loading branch information
@Hallberg-NOAA
Hallberg-NOAA committed Jul 11, 2018
1 parent 4bd838e commit 7c4d684
Show file tree
Hide file tree
Showing 13 changed files with 107 additions and 164 deletions.
11 changes: 6 additions & 5 deletions src/framework/MOM_checksums.F90
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
!> Routines to calculate checksums of various array and vector types
module MOM_checksums

! This file is part of MOM6. See LICENSE.md for the license.
Expand Down Expand Up @@ -76,11 +77,11 @@ module MOM_checksums
module procedure chksum_general_1d, chksum_general_2d, chksum_general_3d
end interface

integer, parameter :: default_shift=0
logical :: calculateStatistics=.true. ! If true, report min, max and mean.
logical :: writeChksums=.true. ! If true, report the bitcount checksum
logical :: checkForNaNs=.true. ! If true, checks array for NaNs and cause
! FATAL error is any are found
integer, parameter :: default_shift=0 !< The default array shift
logical :: calculateStatistics=.true. !< If true, report min, max and mean.
logical :: writeChksums=.true. !< If true, report the bitcount checksum
logical :: checkForNaNs=.true. !< If true, checks array for NaNs and cause
!! FATAL error is any are found

contains

Expand Down
32 changes: 17 additions & 15 deletions src/framework/MOM_coms.F90
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
!> Interfaces to non-domain-oriented communication subroutines, including the
!! MOM6 reproducing sums facility
module MOM_coms

! This file is part of MOM6. See LICENSE.md for the license.
Expand All @@ -23,23 +25,26 @@ module MOM_coms
! This module provides interfaces to the non-domain-oriented communication
! subroutines.

integer(kind=8), parameter :: prec=2_8**46 ! The precision of each integer.
real, parameter :: r_prec=2.0**46 ! A real version of prec.
real, parameter :: I_prec=1.0/(2.0**46) ! The inverse of prec.
integer(kind=8), parameter :: prec=2_8**46 !< The precision of each integer.
real, parameter :: r_prec=2.0**46 !< A real version of prec.
real, parameter :: I_prec=1.0/(2.0**46) !< The inverse of prec.
integer, parameter :: max_count_prec=2**(63-46)-1
! The number of values that can be added together
! with the current value of prec before there will
! be roundoff problems.
!< The number of values that can be added together
!! with the current value of prec before there will
!! be roundoff problems.

integer, parameter :: ni=6 ! The number of long integers to use to represent
! a real number.
integer, parameter :: ni=6 !< The number of long integers to use to represent
!< a real number.
real, parameter, dimension(ni) :: &
pr = (/ r_prec**2, r_prec, 1.0, 1.0/r_prec, 1.0/r_prec**2, 1.0/r_prec**3 /)
!< An array of the real precision of each of the integers
real, parameter, dimension(ni) :: &
I_pr = (/ 1.0/r_prec**2, 1.0/r_prec, 1.0, r_prec, r_prec**2, r_prec**3 /)
!< An array of the inverse of thereal precision of each of the integers

logical :: overflow_error = .false., NaN_error = .false.
logical :: debug = .false. ! Making this true enables debugging output.
logical :: overflow_error = .false. !< This becomes true if an overflow is encountered.
logical :: NaN_error = .false. !< This becomes true if a NaN is encountered.
logical :: debug = .false. !< Making this true enables debugging output.

!> Find an accurate and order-invariant sum of distributed 2d or 3d fields
interface reproducing_sum
Expand Down Expand Up @@ -677,7 +682,7 @@ function real_to_EFP(val, overflow)

end function real_to_EFP

!< This subroutine does a sum across PEs of a list of EFP variables,
!> This subroutine does a sum across PEs of a list of EFP variables,
!! returning the sums in place, with all overflows carried.
subroutine EFP_list_sum_across_PEs(EFPs, nval, errors)
type(EFP_type), dimension(:), &
Expand Down Expand Up @@ -727,12 +732,9 @@ subroutine EFP_list_sum_across_PEs(EFPs, nval, errors)

end subroutine EFP_list_sum_across_PEs

!< This subroutine carries out all of the calls required to close out the infrastructure cleanly.
!> This subroutine carries out all of the calls required to close out the infrastructure cleanly.
!! This should only be called in ocean-only runs, as the coupler takes care of this in coupled runs.
subroutine MOM_infra_end
! This subroutine should contain all of the calls that are required
! to close out the infrastructure cleanly. This should only be called
! in ocean-only runs, as the coupler takes care of this in coupled runs.
call print_memuse_stats( 'Memory HiWaterMark', always=.TRUE. )
call fms_end
end subroutine MOM_infra_end
Expand Down
8 changes: 2 additions & 6 deletions src/framework/MOM_diag_mediator.F90
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
!> The subroutines here provide convenient wrappers to the fms diag_manager
!! interfaces with additional diagnostic capabilies.
module MOM_diag_mediator

! This file is part of MOM6. See LICENSE.md for the license.

!********+*********+*********+*********+*********+*********+*********+**
!* *
!* The subroutines here provide convenient wrappers to the fms *
!* diag_manager interfaces with additional diagnostic capabilies. *
!* *
!********+*********+*********+*********+*********+*********+*********+**
use MOM_checksums, only : chksum_general
use MOM_coms, only : PE_here
use MOM_cpu_clock, only : cpu_clock_id, cpu_clock_begin, cpu_clock_end
Expand Down
15 changes: 5 additions & 10 deletions src/framework/MOM_document.F90
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,9 @@
!> The subroutines here provide hooks for document generation functions at
!! various levels of granularity.
module MOM_document

! This file is part of MOM6. See LICENSE.md for the license.

!********+*********+*********+*********+*********+*********+*********+**
!* *
!* The subroutines here provide hooks for document generation *
!* functions at various levels of granularity. *
!* *
!********+*********+*********+*********+*********+*********+*********+**

use MOM_time_manager, only : time_type
use MOM_error_handler, only : MOM_error, FATAL, WARNING, is_root_pe

Expand All @@ -27,7 +22,7 @@ module MOM_document
doc_param_time
end interface

integer, parameter :: mLen = 1240 ! Length of interface/message strings
integer, parameter :: mLen = 1240 !< Length of interface/message strings

!> A structure that controls where the documentation occurs, its veborsity and formatting.
type, public :: doc_type ; private
Expand Down Expand Up @@ -56,8 +51,8 @@ module MOM_document
character(len=620) :: msg !< Parameter value and default
end type link_msg

character(len=4), parameter :: STRING_TRUE = 'True'
character(len=5), parameter :: STRING_FALSE = 'False'
character(len=4), parameter :: STRING_TRUE = 'True' !< A string for true logicals
character(len=5), parameter :: STRING_FALSE = 'False' !< A string for false logicals

contains

Expand Down
5 changes: 2 additions & 3 deletions src/framework/MOM_domains.F90
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
!> Describes the decomposed MOM domain and has routines for communications across PEs
module MOM_domains

! This file is part of MOM6. See LICENSE.md for the license.
Expand Down Expand Up @@ -31,8 +32,6 @@ module MOM_domains

implicit none ; private

! #include <MOM_memory.h>

public :: MOM_domains_init, MOM_infra_init, MOM_infra_end, get_domain_extent
public :: MOM_define_domain, MOM_define_io_domain, clone_MOM_domain
public :: pass_var, pass_vector, broadcast, PE_here, root_PE, num_PEs
Expand Down Expand Up @@ -128,7 +127,7 @@ module MOM_domains
!! assigned if all logical processors are used.
end type MOM_domain_type

integer, parameter :: To_All = To_East + To_West + To_North + To_South
integer, parameter :: To_All = To_East + To_West + To_North + To_South !< A flag for passing in all directions

contains

Expand Down
2 changes: 2 additions & 0 deletions src/framework/MOM_dyn_horgrid.F90
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
!> Contains a shareable dynamic type for describing horizontal grids and metric data
!! and utilty routines that work on this type.
module MOM_dyn_horgrid

! This file is part of MOM6. See LICENSE.md for the license.
Expand Down
35 changes: 14 additions & 21 deletions src/framework/MOM_error_handler.F90
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,8 @@
!> Routines for error handling and I/O management
module MOM_error_handler

! This file is part of MOM6. See LICENSE.md for the license.

!********+*********+*********+*********+*********+*********+*********+**
!* *
!* By R. Hallberg, 2005-2012. *
!* *
!* This module wraps the mpp_mod error handling code and the *
!* mpp functions stdlog() and stdout() that return open unit numbers. *
!* *
!********+*********+*********+*********+*********+*********+*********+**

use mpp_mod, only : mpp_error, NOTE, WARNING, FATAL
use mpp_mod, only : mpp_pe, mpp_root_pe, stdlog, stdout

Expand All @@ -21,18 +13,19 @@ module MOM_error_handler
public callTree_showQuery, callTree_enter, callTree_leave, callTree_waypoint
public assert

! Verbosity level:
! 0 - FATAL messages only
! 1 - FATAL + WARNING messages only
! 2 - FATAL + WARNING + NOTE messages only [default]
! 3 - above + informational
! 4 -
! 5 -
! 6 - above + call tree
! 7 -
! 8 -
! 9 - anything and everything (also set with #define DEBUG)
integer :: verbosity = 6
!< Verbosity level:
!! 0 - FATAL messages only
!! 1 - FATAL + WARNING messages only
!! 2 - FATAL + WARNING + NOTE messages only [default]
!! 3 - above + informational
!! 4 -
!! 5 -
!! 6 - above + call tree
!! 7 -
!! 8 -
!! 9 - anything and everything (also set with DEBUG=True)

! Note that this module default will only hold until the
! VERBOSITY parameter is parsed and the given default imposed.
! We set it to 6 here so that the call tree will print before
Expand All @@ -41,8 +34,8 @@ module MOM_error_handler
! a type passed by argument (preferred for most data) for convenience
! and to reduce obfuscation of code

! The level of calling within the call tree
integer :: callTreeIndentLevel = 0
!< The level of calling within the call tree

contains

Expand Down
65 changes: 33 additions & 32 deletions src/framework/MOM_file_parser.F90
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,8 @@
!> The MOM6 facility to parse input files for runtime parameters
module MOM_file_parser

! This file is part of MOM6. See LICENSE.md for the license.

!********+*********+*********+*********+*********+*********+*********+**
!* *
!* By Robert Hallberg and Alistair Adcroft, updated 9/2013. *
!* *
!* The subroutines here parse a set of input files for the value *
!* a named parameter and sets that parameter at run time. Currently *
!* these files use use one of several formats: *
!* #define VAR ! To set the logical VAR to true. *
!* VAR = True ! To set the logical VAR to true. *
!* #undef VAR ! To set the logical VAR to false. *
!* VAR = False ! To set the logical VAR to false. *
!* #define VAR 999 ! To set the real or integer VAR to 999. *
!* VAR = 999 ! To set the real or integer VAR to 999. *
!* #override VAR = 888 ! To override a previously set value. *
!* VAR = 1.1, 2.2, 3.3 ! To set an array of real values. *
!* *
!* In addition, when set by the get_param interface, the values of *
!* parameters are automatically logged, along with defaults, units, *
!* and a description. It is an error for a variable to be overridden *
!* more than once, and MOM6 has a facility to check for unused lines *
!* to set variables, which may indicate miss-spelled or archaic *
!* parameters. Parameter names are case-specific, and lines may use *
!* a F90 or C++ style comment, starting with ! or //. *
!* *
!********+*********+*********+*********+*********+*********+*********+**

use MOM_coms, only : root_PE, broadcast
use MOM_error_handler, only : MOM_error, FATAL, WARNING, MOM_mesg
use MOM_error_handler, only : is_root_pe, stdlog, stdout
Expand All @@ -40,20 +15,21 @@ module MOM_file_parser

implicit none ; private

integer, parameter, public :: MAX_PARAM_FILES = 5 ! Maximum number of parameter files.
integer, parameter :: INPUT_STR_LENGTH = 320 ! Maximum linelength in parameter file.
integer, parameter :: FILENAME_LENGTH = 200 ! Maximum number of characters in
! file names.
integer, parameter, public :: MAX_PARAM_FILES = 5 !< Maximum number of parameter files.
integer, parameter :: INPUT_STR_LENGTH = 320 !< Maximum line length in parameter file.
integer, parameter :: FILENAME_LENGTH = 200 !< Maximum number of characters in file names.

! The all_PEs_read option should be eliminated with post-riga shared code.
logical :: all_PEs_read = .false.
logical :: all_PEs_read = .false. !< If true, all PEs read the input files
!! TODO: Eliminate this parameter

! Defaults
!>@{ Default values for parameters
logical, parameter :: report_unused_default = .false.
logical, parameter :: unused_params_fatal_default = .false.
logical, parameter :: log_to_stdout_default = .false.
logical, parameter :: complete_doc_default = .true.
logical, parameter :: minimal_doc_default = .true.
!!@}

!> The valid lines extracted from an input parameter file without comments
type, private :: file_data_type ; private
Expand Down Expand Up @@ -2104,4 +2080,29 @@ function popBlockLevel(oldblockName)
endif
end function popBlockLevel

!> \namespace mom_file_parser
!!
!! By Robert Hallberg and Alistair Adcroft, updated 9/2013.
!!
!! The subroutines here parse a set of input files for the value
!! a named parameter and sets that parameter at run time. Currently
!! these files use use one of several formats:
!! \#define VAR ! To set the logical VAR to true.
!! VAR = True ! To set the logical VAR to true.
!! \#undef VAR ! To set the logical VAR to false.
!! VAR = False ! To set the logical VAR to false.
!! \#define VAR 999 ! To set the real or integer VAR to 999.
!! VAR = 999 ! To set the real or integer VAR to 999.
!! \#override VAR = 888 ! To override a previously set value.
!! VAR = 1.1, 2.2, 3.3 ! To set an array of real values.
! Note that in the comments above, dOxygen translates \# to # .
!!
!! In addition, when set by the get_param interface, the values of
!! parameters are automatically logged, along with defaults, units,
!! and a description. It is an error for a variable to be overridden
!! more than once, and MOM6 has a facility to check for unused lines
!! to set variables, which may indicate miss-spelled or archaic
!! parameters. Parameter names are case-specific, and lines may use
!! a F90 or C++ style comment, starting with ! or //.

end module MOM_file_parser
9 changes: 2 additions & 7 deletions src/framework/MOM_intrinsic_functions.F90
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,9 @@
!> A module with intrinsic functions that are used by MOM but are not supported
!! by some compilers.
module MOM_intrinsic_functions

! This file is part of MOM6. See LICENSE.md for the license.

!********+*********+*********+*********+*********+*********+*********+**
!* *
!* This module holds intrinsic functions which are used by MOM but *
!* are not supported by some compilers. *
!* *
!********+*********+*********+*********+*********+*********+*********+**

implicit none ; private

public :: invcosh
Expand Down
42 changes: 1 addition & 41 deletions src/framework/MOM_restart.F90
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,8 @@
!> The MOM6 facility for reading and writing restart files, and querying what has been read.
module MOM_restart

! This file is part of MOM6. See LICENSE.md for the license.

!********+*********+*********+*********+*********+*********+*********+**
!* *
!* By Robert Hallberg, April 1994 - June 2002 *
!* *
!* This file contains four subroutines associated with saving *
!* restart files or restoring the model state from files. *
!* *
!* register_restart_field is used to specify the fields that will *
!* be written to restart files. *
!* *
!* Save_restart saves a restart file from which a simulation can *
!* be restarted with results that are identical to those which would *
!* have been attained if there had been no interruption. If this *
!* file would be larger than 2 Gbytes, it is broken up into a number *
!* of smaller files. *
!* *
!* The subroutine restore_state initializes the fields for the *
!* simulations from a number of restart files or other NetCDF files. *
!* Each restart field is initialized from the first file in the *
!* list in which it is found. The files are separated by spaces, *
!* and all must be in the specified directory. If 'r' is included *
!* in the list, it is expanded to include all of the restart files *
!* that are found in the directory. *
!* *
!* query_initialized returns true if a field (or the entire restart *
!* file) has been initialized from a restart file and false otherwise.*
!* *
!* A small fragment of the grid is shown below: *
!* *
!* j+1 x ^ x ^ x At x: q, CoriolisBu *
!* j+1 > o > o > At ^: v *
!* j x ^ x ^ x At >: u *
!* j > o > o > At o: h, bathyT, tr *
!* j-1 x ^ x ^ x *
!* i-1 i i+1 *
!* i i+1 *
!* *
!* The boundaries always run through q grid points (x). *
!* *
!********+*********+*********+*********+*********+*********+*********+**

use MOM_domains, only : pe_here, num_PEs
use MOM_error_handler, only : MOM_error, FATAL, WARNING, NOTE, is_root_pe
use MOM_file_parser, only : get_param, log_param, log_version, param_file_type
Expand Down
1 change: 1 addition & 0 deletions src/framework/MOM_spatial_means.F90
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
!> Functions and routines to take area, volume, mass-weighted, layerwise, zonal or meridional means
module MOM_spatial_means

! This file is part of MOM6. See LICENSE.md for the license.
Expand Down
Loading

0 comments on commit 7c4d684

Please sign in to comment.