MAPL Documentation Standards with FORD - GEOS-ESM/MAPL GitHub Wiki

!>
! Compute the area of a triangle using the Heron's formula:
!
!$$
!\begin{equation}
!s  = \frac{a+b+c}{2}  \\\\
!A  = \sqrt{s(s-a)(s-b)(s-c)}
!\label{eq:tri}
!\end{equation}
!$$
!
   real function calc_area( a, b, c )
      ! This line will not be documented.
      real, intent(in)  :: a !! Opposite
                            !! More comments on the opposite.
      real, intent(in)  :: b !! Adjacent
      real, intent(in) :: c  !! Hypothenus
      real :: s
      s = (a + b + c) / 2.0
      calc_area = sqrt(s*(s-a)*(s-b)*(s-c))
   end function calc_area
   
!> 
! Compute the hypothenus of a right angle triangle.
! 
! The length of the hypotehnus is given by: 
! \( c = \sqrt{a^2 + b^2} \)
! 
! This is the last line of the commented section.
subroutine compute_hypothenus(a, b, c)
    real, intent(in)   :: a !! Base
    real, intent(in)   :: b !! Perpendicular
    real, intent(out) :: c  !! Hypothenus
    c = sqrt(a**2 + b**2)
end subroutine compute_hypothenus

!------------------------------------------------------------------------------
!               Global Modeling and Assimilation Office (GMAO)                !
!                    Goddard Earth Observing System (GEOS)                    !
!                                 MAPL Component                              !
!------------------------------------------------------------------------------
!>
!# Short title 
!
! `program_name` is used for ...
! Provide a description of what the program does.
!
! @note
! `Usage`:
!
!   Briefly describe how to use the program.
!
!       mpiexec -np 56 pfio_MAPL_demo.x --npes_model 28 --oserver_type multigroup \
!                               --nodes_output_server 1 --npes_backend_pernode 5
! @endnote
!
! @todo
! Report anything to be done here.
!@endtodo
!
! @bug
! Report any bug here.
!@endbug
!
program program_name

!------------------------------------------------------------------------------
!               Global Modeling and Assimilation Office (GMAO)                !
!                    Goddard Earth Observing System (GEOS)                    !
!                                 MAPL Component                              !
!------------------------------------------------------------------------------
!>
!### MODULE: `module_name`
!
! Author: GMAO SI-Team
!
! `module_name` is an abstract base class representing
! individual values of VariableSpec properties.  Concrete subclasses
! are used to encapsulate various intrinsic types (logical, integer,
! real, string) and allow more generic access to those values
!
! Special interfaces are provided to support allocatable strings which
! unfortunately cannot use the usual interface.  Instead all
! subclasses have both the generic and string-specific interfaces and
! the BaseSchemaElement subclass provides concrete implementations
! that return exceptions.  Concrete subclasses should override as
! appropriate.
!
!#### History
!- 09Nov2022: First implementation.
!
! @todo
! Report anything to be done here.
!@endtodo
!
! @bug
! Report any bug here.
!@endbug
!
module module_name
   implicit none
   private

   public :: public_unit

   type, abstract :: AbstractSchemaElement
   contains
      procedure(i_has_default), deferred :: has_default
      procedure(i_accepts_value), deferred :: accepts_value
      procedure(i_get_default_scalar), deferred :: get_default_scalar
      procedure(i_get_default_string), deferred :: get_default_string
      generic   :: get_default => get_default_scalar
      procedure(i_copy_value), deferred :: copy_value
      procedure(i_copy_string_value), deferred :: copy_string_value
   end type AbstractSchemaElement

   abstract interface

!------------------------------------------------------------------------------
!>
! For a given number of grid points along a dimension and a number of
! available processors for that dimension, determine the number of
! grid points assigned to each processor.
!
!### Example
! The subroutine can be used as:
!```fortran
!    allocate(dim_array(16))
!    call decompose_dim(181, dim_array, 16)
!```
!
   subroutine decompose_dim(dim_world, dim_array, num_procs)

      integer, intent(in)  :: dim_world    !! total number of grid points
      integer, intent(in)  :: num_procs    !! number of processors
      integer, intent(out) :: dim_array(0:num_procs-1) !! Array containing the
                                                            !! number of grids assign to each processor

      integer ::   n, im, rm
!------------------------------------------------------------------------------
      im = dim_world/num_procs
      rm = dim_world-num_procs*im
      do n = 0, num_procs-1
                      dim_array(n) = im
      if( n.le.rm-1 ) dim_array(n) = im+1
      enddo
   end subroutine decompose_dim
!------------------------------------------------------------------------------

    !> 
    ! Docstrings can go on derived types
    ! and you can put more comment here
    ! and end here with the derived type comment.
    type :: my_type
        real :: R_major        !! Docstrings can include in-line LaTeX 
                               !! like this: \(R\)
        real :: R_major_prime  !! Or as a displayed equation:
                               !! $$\frac{\partial R}{\partial \psi}$$
        integer :: n_R         !! Code-formatting uses `backticks`
    contains
        procedure :: my_read_var  => read_var  !! Read my variable
        procedure :: my_write_var => write_var !! Write my variable
    end type my_type

---
parallel: 4
src_dir: ../MAPL_code
preprocessor: /usr/local/bin/cpp-12 -traditional-cpp -E
search: true
graph: true
coloured_edges: true
graph_maxdepth: 4
graph_maxnodes: 32
include: ../MAPL_code/include/
         ../gFTL/install/GFTL-1.8/include/v1
         ../gFTL/install/GFTL-1.8/include/v2
exclude_dir: ../MAPL_code/Ford
             ../MAPL_code/Doxygen
             ../MAPL_code/ESMA_cmake
             ../MAPL_code/ESMA_env
             ../MAPL_code/build
             ../MAPL_code/gFTL
macro: USE_MPI=1
       BUILD_WITH_PFLOGGER=1
       BUILD_WITH_EXTDATA2G=1
       USE_FLAP=1
       H5_HAVE_PARALLEL=1
       TWO_SIDED_COMM=1
       MAPL_MODE=1
fixed_length_limit: false
source: true
display: public
         private
         protected
extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html
            iso_c_binding:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fC_005fBINDING.html#ISO_005fC_005fBINDING
project: MAPL
project_github: https://github.com/GEOS-ESM/MAPL
project_website: https://github.com/GEOS-ESM/MAPL
summary: MAPL is a foundation layer of the GEOS architecture, whose original purpose is to supplement the Earth System Modeling Framework (ESMF)
author: GMAO SI-Team
author_description: GEOS Software Infrastructure Team
github: https://github.com/JulesKouatchou
email: [email protected]
print_creation_date: true
sort: type-alpha
predocmark_alt: >
predocmark: <
docmark_alt:
docmark: !
md_extensions: markdown.extensions.toc
               markdown.extensions.smarty
extensions: f90
            F90
            pf
fpp_extensions: F90
                pf
                F
---

{!../MAPL_code/README.md!}

!------------------------------------------------------------------------------
!               Global Modeling and Assimilation Office (GMAO)                !
!                    Goddard Earth Observing System (GEOS)                    !
!                                 MAPL Component                              !
!------------------------------------------------------------------------------

#include "MAPL_ErrLog.h"
#include "unused_dummy.H"
!
!>
!### MODULE: `mapl_CapOptionsMod`
! Contains functions to initialize and copy command line parameters.
!
module mapl_CapOptionsMod
   use ESMF
   use mapl_KeywordEnforcerMod
   use mapl_ExceptionHandling
   implicit none
   private

   public :: MAPL_CapOptions

   !> Derived type used to capture all the command line parameters
   ! needed to configure a run.
   type :: MAPL_CapOptions

      integer :: comm
      logical :: use_comm_world = .true.
      character(:), allocatable :: egress_file
      character(:), allocatable :: cap_rc_file
      character(:), allocatable :: root_dso
      type (ESMF_LogKind_Flag) :: esmf_logging_mode = ESMF_LOGKIND_NONE
      integer :: npes_model = -1
      integer, allocatable :: npes_input_server(:)        !! only one of the next two options
                                                          !! can have nonzero values
      integer, allocatable :: nodes_input_server(:)
      integer, allocatable :: npes_output_server(:)       !! only one of the next two options
                                                          !! can have nonzero values
      integer, allocatable :: nodes_output_server(:)
      logical              :: isolate_nodes = .true.      !! whether or not the nodes are
                                                          !! padding with idle when mod(model
                                                          !! total npes , each node npes) /=0
      logical              :: fast_oclient  = .false.     !! whether or not copy the data
                                                          !! before isend to the oserver
                                                          !! it is faster but demands more
                                                          !! memory if it is true
      logical              :: with_io_profiler = .false.  !!  whether or not turn on the io profiler
      logical              :: with_esmf_moab = .false.    !! whether or not to use MOAB in ESMF
      integer :: n_iserver_group = 1                      !! server groups
      integer :: n_oserver_group = 1
      integer :: n_members = 1                            !! ensemble options
      character(:), allocatable :: ensemble_subdir_prefix
      character(:), allocatable :: logging_config         !! logging options
      character(:), allocatable :: oserver_type
      integer :: npes_backend_pernode = 0

   end type MAPL_CapOptions

   interface MAPL_CapOptions
      module procedure new_CapOptions
      module procedure new_CapOptions_copy !! for backward compatibility - delete for 3.0
   end interface MAPL_CapOptions

!------------------------------------------------------------------------------
contains
!------------------------------------------------------------------------------
   !> Initialize the MAPL Cap parameters.
   function new_CapOptions(unusable, cap_rc_file, egress_file, ensemble_subdir_prefix, &
                           esmf_logging_mode, rc) result (cap_options)
      type (MAPL_CapOptions) :: cap_options
      class (KeywordEnforcer), optional, intent(in) :: unusable
      character(*), optional, intent(in) :: cap_rc_file
      character(*), optional, intent(in) :: egress_file
      character(*), optional, intent(in) :: ensemble_subdir_prefix
      type(ESMF_LogKind_Flag), optional, intent(in) :: esmf_logging_mode

      integer, optional, intent(out) :: rc

      _UNUSED_DUMMY(unusable)

      cap_options%cap_rc_file = 'CAP.rc'
      cap_options%egress_file = 'EGRESS'
      cap_options%oserver_type= 'single'
      cap_options%ensemble_subdir_prefix = 'mem'

      cap_options%npes_input_server  =[0]
      cap_options%nodes_input_server =[0]
      cap_options%npes_output_server =[0]
      cap_options%nodes_output_server=[0]

      if (present(cap_rc_file)) cap_options%cap_rc_file = cap_rc_file
      if (present(egress_file)) cap_options%egress_file = egress_file
      if (present(ensemble_subdir_prefix)) cap_options%ensemble_subdir_prefix = ensemble_subdir_prefix
      if (present(esmf_logging_mode)) cap_options%esmf_logging_mode = esmf_logging_mode

      _RETURN(_SUCCESS)

   end function new_CapOptions
!------------------------------------------------------------------------------
   !> Copy the MAPL Cap options.
   function new_CapOptions_copy(options) result(copy)
      type(MAPL_CapOptions) :: copy
      type(MAPL_CapOptions), intent(in) :: options
      copy = options
   end function new_CapOptions_copy
!------------------------------------------------------------------------------

end module MAPL_CapOptionsMod