MAPL_Base – MAPL

MODULE: `MAPL_Base`

Author: GMAO SI-Team

The module MAPL_Base provides a collection assorted utilities and constants used throughout the MAPL Library.

Uses

- iso_fortran_env
- ESMF
Help

Graph Key

Nodes of different colours represent the following:

Solid arrows point from a submodule to the (sub)module which it is descended from. Dashed arrows point from a module or program unit to modules which it uses.
Where possible, edges connecting nodes are given different colours to make them easier to distinguish in large graphs.

Variables

Type	Visibility	Attributes		Name		Initial
character(len=ESMF_MAXSTR),	public,	parameter	::	MAPL_BundleItemOrderList	=	'MAPL_BundleItemOrderList'
character(len=ESMF_MAXSTR),	public,	parameter	::	MAPL_StateItemOrderList	=	'MAPL_StateItemOrderList'
real,	public,	parameter	::	MAPL_UNDEF	=	1.0e15

Interfaces

interface

public module subroutine MAPL_AllocateCoupling(field, rc)

Arguments

Type	Intent	Optional	Attributes		Name
type(ESMF_Field),	intent(inout)			::	field
integer,	intent(out),	optional		::	rc

public interface MAPL_AttributeSet

private interface MAPL_StateAttSetI4()

Arguments
None
private interface MAPL_BundleAttSetI4()

Arguments
None
private interface MAPL_FieldAttSetI4()

Arguments
None

interface

public module function MAPL_BundleCreate(name, grid, fieldNames, is2D, isEdge, long_names, units, rc) result(B)

Arguments

Type	Intent	Optional		Name
character(len=*),	intent(in)		::	name
type(ESMF_Grid),	intent(inout)		::	grid
character(len=*),	intent(in)		::	fieldNames(:)
logical,	intent(in),	optional	::	is2D(:)
logical,	intent(in),	optional	::	isEdge(:)
character(len=*),	intent(in),	optional	::	long_names(:)
character(len=*),	intent(in),	optional	::	units(:)
integer,	intent(out),	optional	::	rc

Return Value type(ESMF_FieldBundle)

interface

public module subroutine MAPL_ClimInterpFac(CLOCK, I1, I2, FAC, RC)

Arguments

Type	Intent	Optional		Name
type(ESMF_Clock),	intent(in)		::	CLOCK
integer,	intent(out)		::	I1
integer,	intent(out)		::	I2
real,	intent(out)		::	FAC
integer,	intent(out),	optional	::	RC

interface

public pure module subroutine MAPL_DecomposeDim(dim_world, dim, NDEs, unusable, symmetric, min_DE_extent)

Arguments

Type	Intent	Optional		Name
integer,	intent(in)		::	dim_world
integer,	intent(out)		::	dim(0:NDEs-1)
integer,	intent(in)		::	NDEs
class(KeywordEnforcer),	intent(in),	optional	::	unusable
logical,	intent(in),	optional	::	symmetric
integer,	intent(in),	optional	::	min_DE_extent

interface

public module subroutine MAPL_FieldAllocCommit(field, dims, location, typekind, hw, ungrid, default_value, rc)

Arguments

Type	Intent	Optional		Name
type(ESMF_Field),	intent(inout)		::	field
integer,	intent(in)		::	dims
integer,	intent(in)		::	location
integer,	intent(in)		::	typekind
integer,	intent(in)		::	hw
integer,	intent(in),	optional	::	ungrid(:)
real,	intent(in),	optional	::	default_value
integer,	intent(out),	optional	::	rc

public interface MAPL_FieldBundleAdd

private interface MAPL_FieldBundleAddField()

Arguments
None

interface

public module subroutine MAPL_FieldBundleDestroy(Bundle, RC)

Arguments

Type	Intent	Optional	Attributes		Name
type(ESMF_FieldBundle),	intent(inout)			::	Bundle
integer,	intent(out),	optional		::	RC

public interface MAPL_FieldBundleGet

private interface MAPL_FieldBundleGetByIndex()

Arguments
None

interface

public module subroutine MAPL_FieldCopy(FROM, TO, RC)

Arguments

Type	Intent	Optional		Name
type(ESMF_Field),	intent(inout)		::	FROM
type(ESMF_Field),	intent(inout)		::	TO
integer,	intent(out),	optional	::	RC

interface

public module subroutine MAPL_FieldCopyAttributes(FIELD_IN, FIELD_OUT, RC)

Arguments

Type	Intent	Optional		Name
type(ESMF_Field),	intent(inout)		::	FIELD_IN
type(ESMF_Field),	intent(inout)		::	FIELD_OUT
integer,	intent(out),	optional	::	RC

public interface MAPL_FieldCreate

private interface MAPL_FieldCreateRename()

Arguments
None
private interface MAPL_FieldCreateNewgrid()

Arguments
None
private interface MAPL_FieldCreateR4()

Arguments
None

interface

public module function MAPL_FieldCreateEmpty(NAME, GRID, RC) result(FIELD)

Arguments

Type	Intent	Optional		Name
character(len=*),	intent(in)		::	NAME
type(ESMF_Grid),	intent(inout)		::	GRID
integer,	intent(out),	optional	::	RC

Return Value type(ESMF_Field)

public interface MAPL_FieldGetTime

private interface MAPL_GetFieldTimeFromField()

Arguments
None
private interface MAPL_GetFieldTimeFromState()

Arguments
None

public interface MAPL_FieldSetTime

private interface MAPL_SetFieldTimeFromField()

Arguments
None
private interface MAPL_SetFieldTimeFromState()

Arguments
None

interface

public module subroutine MAPL_FieldSplit(field, fields, aliasName, rc)

Arguments

Type	Intent	Optional	Attributes		Name
type(ESMF_Field),	intent(in)			::	field
type(ESMF_Field),	intent(out),		pointer	::	fields(:)
character(len=*),	intent(in),	optional		::	aliasName
integer,	intent(out),	optional		::	rc

interface

public module subroutine MAPL_GRID_INTERIOR(grid, I1, IN, J1, JN)

Arguments

Type	Intent		Name
type(ESMF_Grid),	intent(in)	::	grid
integer,	intent(out)	::	I1
integer,	intent(out)	::	IN
integer,	intent(out)	::	J1
integer,	intent(out)	::	JN

interface

public module subroutine MAPL_GenGridName(im, jm, lon, lat, xyoffset, gridname, geos_style)

Arguments

Type	Optional		Name
integer		::	im
integer		::	jm
real,	optional	::	lon(:)
real,	optional	::	lat(:)
integer,	optional	::	xyoffset
character(len=*)		::	gridname
logical,	optional	::	geos_style

interface

public module function MAPL_GenXYOffset(lon, lat) result(xy)

Arguments

Type	Intent	Optional	Attributes		Name
real				::	lon(:)
real				::	lat(:)

Return Value integer

interface

public module subroutine MAPL_GeosNameNew(name)

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*)				::	name

interface

public module function MAPL_GetCorrectedPhase(gc, rc) result(phase)

Arguments

Type	Intent	Optional	Attributes		Name
type(ESMF_GridComp),	intent(inout)			::	gc
integer,	intent(out),	optional		::	rc

Return Value integer

interface

public module subroutine MAPL_GetGlobalHorzIJIndex(npts, II, JJ, lon, lat, lonR8, latR8, Grid, rc)

Arguments

Type	Intent	Optional		Name
integer,	intent(in)		::	npts
integer,	intent(inout)		::	II(npts)
integer,	intent(inout)		::	JJ(npts)
real,	intent(in),	optional	::	lon(npts)
real,	intent(in),	optional	::	lat(npts)
real(kind=ESMF_KIND_R8),	intent(in),	optional	::	lonR8(npts)
real(kind=ESMF_KIND_R8),	intent(in),	optional	::	latR8(npts)
type(ESMF_Grid),	intent(inout),	optional	::	Grid
integer,	intent(out),	optional	::	rc

interface

public module subroutine MAPL_GetHorzIJIndex(npts, II, JJ, lon, lat, lonR8, latR8, Grid, rc)

Arguments

Type	Intent	Optional		Name
integer,	intent(in)		::	npts
integer,	intent(inout)		::	II(npts)
integer,	intent(inout)		::	JJ(npts)
real,	intent(in),	optional	::	lon(npts)
real,	intent(in),	optional	::	lat(npts)
real(kind=ESMF_KIND_R8),	intent(in),	optional	::	lonR8(npts)
real(kind=ESMF_KIND_R8),	intent(in),	optional	::	latR8(npts)
type(ESMF_Grid),	intent(inout),	optional	::	Grid
integer,	intent(out),	optional	::	rc

interface

public module subroutine MAPL_GridGetCorners(GRID, gridCornerLons, gridCornerLats, RC)

Arguments

Type	Intent	Optional		Name
type(ESMF_Grid),	intent(inout)		::	GRID
real(kind=ESMF_KIND_R8),	intent(inout)		::	gridCornerLons(:,:)
real(kind=ESMF_KIND_R8),	intent(inout)		::	gridCornerLats(:,:)
integer,	intent(out),	optional	::	RC

interface

public module subroutine MAPL_GridGetInterior(grid, I1, IN, J1, JN)

Arguments

Type	Intent		Name
type(ESMF_Grid),	intent(in)	::	grid
integer,	intent(out)	::	I1
integer,	intent(out)	::	IN
integer,	intent(out)	::	J1
integer,	intent(out)	::	JN

interface

public module subroutine MAPL_Interp_Fac(TIME0, TIME1, TIME2, FAC1, FAC2, RC)

Arguments

Type	Intent	Optional		Name
type(ESMF_Time),	intent(in)		::	TIME0
type(ESMF_Time),	intent(in)		::	TIME1
type(ESMF_Time),	intent(in)		::	TIME2
real,	intent(out)		::	FAC1
real,	intent(out),	optional	::	FAC2
integer,	intent(out),	optional	::	RC

interface

public module function MAPL_LEAP(NY)

Arguments

Type	Intent	Optional	Attributes		Name
integer,	intent(in)			::	NY

Return Value logical

interface

public module function MAPL_LatLonGridCreate(Name, VM, Config, ConfigFile, Nx, Ny, IM_World, BegLon, DelLon, JM_World, BegLat, DelLat, LM_World, rc) result(Grid)

MAPL_LatLonGridCreate — Create regular Lat/Lon Grid

This routine creates a distributed ESMF grid where the horizontal coordinates are regular longitudes and latitudes. The grid is created on the user specified VM, or on the current VM if the user does not specify one. The layout and the coordinate information can be provided with a `ESMF_Config attribute, a resource file name or specified through the argument list.

Using resource files

The resource file has a syntax similar to a GrADS control file. Here is an example defining a typical GEOS-5 1x1.25 grid with 72 layers:

       GDEF: LatLon
       IDEF: 32
       JDEF: 16
       LDEF:  1
       XDEF: 288 LINEAR -180. 1.25
       YDEF: 181 LINEAR -90. 1.
       ZDEF:  72 LINEAR 1 1

More generally,

       GDEF: LatLon
       IDEF: Nx
       JDEF: Ny
       LDEF: Nz
       XDEF: IM_World XCoordType BegLon, DelLon
       YDEF: JM_World YCoordType BegLat, DelLat
       ZDEF: LM_World ZCoordType 1        1

The attribute GDEF must always be LatLon for Lat/Lon grids. The remaining parameters are: - Nx is the number of processors used to decompose the X dimension - Ny is the number of processors used to decompose the Y dimension - Nz is the number of processors used to decompose the Z dimension; must be 1 for now. - IM_World is the number of longitudinal grid points; if IM_World=0 then the grid has no zonal dimension. - XCoordType must be set to LINEAR - BegLon is the longitude (in degrees) of the {\em center} of the first gridbox - DelLon is the constant mesh size (in degrees); if DelLon<1 then a global grid is assumed. - JM_World is the number of meridional grid points; if JM_World=0 then the grid has no meridional dimension. - YCoordType must be set to LINEAR - BegLat s the latitude (in degrees) of the center of the first gridbox - DelLat s the constant mesh size (in degrees); if DelLat<1 then a global grid is assumed. - LM_World is the number of vertical grid points; LM_World=0 then the grid has no vertical dimension.

As of this writing, only the size of the vertical grid LM_World needs to be specified.

Passing an ESMF Config

The ESMF_Config object Config, when specified, must contain the same information as the resource file above.

Providing parameters explicitly through the argument list

Alternatively, one can specify coordinate information in the argument list; their units and meaning is as in the resource file above. In this case you must specify at least Nx, Ny, IM_World, JM_World, and LM_World. The other parameters have default values - BegLon defaults to -180. (the date line) - DelLon defaults to -1. (meaning a global grid) - BegLat defaults to -90. (the south pole) - DelLat deaults to -1. (meaning a global grid)

Restrictions

The current implementation imposes the following restrictions: 1. Only uniform longitude/latitude grids are supported (no Gaussian grids). 2. Only 2D Lon-Lat or 3D Lon-Lat-Lev grids are currently supported (no Lat-Lev or Lon-Lev grids supprted yet). 3. No vertical decomposition yet (Nz=1).

Future enhancements

The IDEF/JDEF/LDEF records in the resource file should be extended as to allow specification of a more general distribution. For consistency with the XDEF/YDEF/ZDEF records a similar syntax could be adopted. For example,

       IDEF 4   LEVELS  22 50 50 22
       XDEF 144 LINEAR -180 2.5

would indicate that longitudes would be decomposed in 4 PETs, with the first PET having 22 grid points, the second 50 gridpoints, and so on.

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*),	intent(in)			::	Name
type(ESMF_VM),	intent(in),	optional,	target	::	VM
type(ESMF_Config),	intent(in),	optional,	target	::	Config
character(len=*),	intent(in),	optional		::	ConfigFile
integer,	intent(in),	optional		::	Nx
integer,	intent(in),	optional		::	Ny
integer,	intent(in),	optional		::	IM_World
real,	intent(in),	optional		::	BegLon
real,	intent(in),	optional		::	DelLon
integer,	intent(in),	optional		::	JM_World
real,	intent(in),	optional		::	BegLat
real,	intent(in),	optional		::	DelLat
integer,	intent(in),	optional		::	LM_World
integer,	intent(out),	optional		::	rc

Return Value type(ESMF_Grid)

interface

public module subroutine MAPL_MakeDecomposition(nx, ny, unusable, reduceFactor, rc)

Arguments

Type	Intent	Optional		Name
integer,	intent(out)		::	nx
integer,	intent(out)		::	ny
class(KeywordEnforcer),	intent(in),	optional	::	unusable
integer,	intent(in),	optional	::	reduceFactor
integer,	intent(out),	optional	::	rc

interface

public module subroutine MAPL_PackDateTime(date_time, yy, mm, dd, h, m, s)

Arguments

Type	Intent		Name
integer,	intent(out)	::	date_time(:)
integer,	intent(in)	::	yy
integer,	intent(in)	::	mm
integer,	intent(in)	::	dd
integer,	intent(in)	::	h
integer,	intent(in)	::	m
integer,	intent(in)	::	s

interface

public module subroutine MAPL_PackTime(TIME, IYY, IMM, IDD)

Arguments

Type	Intent		Name
integer,	intent(out)	::	TIME
integer,	intent(in)	::	IYY
integer,	intent(in)	::	IMM
integer,	intent(in)	::	IDD

public interface MAPL_RemapBounds

private function MAPL_RemapBoundsFull_3dr4(A, I1, IM, J1, JM, L1, LM)

Arguments

Type	Intent	Attributes		Name
real,	intent(in),	target	::	A(I1:IM,J1:JM,L1:LM)
integer,	intent(in)		::	I1
integer,	intent(in)		::	IM
integer,	intent(in)		::	J1
integer,	intent(in)		::	JM
integer,	intent(in)		::	L1
integer,	intent(in)		::	LM

Return Value real, pointer, (:,:,:)

private interface MAPL_RemapBounds_3dr4()

Arguments
None
private interface MAPL_RemapBounds_3dr8()

Arguments
None

interface

public module function MAPL_RmQualifier(str, del) result(new)

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*),	intent(in)			::	str
character(len=*),	intent(in),	optional		::	del

Return Value character(len=len)

public interface MAPL_SetPointer

private interface MAPL_SetPointer2DR4()

Arguments
None
private interface MAPL_SetPointer3DR4()

Arguments
None

public interface MAPL_StateAdd

private interface MAPL_StateAddField()

Arguments
None
private interface MAPL_StateAddBundle()

Arguments
None

interface

public module subroutine MAPL_TimeStringGet(TIMESTRING, YY, MM, DD, H, M, S)

Arguments

Type	Intent	Optional		Name
character(len=*),	intent(in)		::	TIMESTRING
integer,	intent(out),	optional	::	YY
integer,	intent(out),	optional	::	MM
integer,	intent(out),	optional	::	DD
integer,	intent(out),	optional	::	H
integer,	intent(out),	optional	::	M
integer,	intent(out),	optional	::	S

interface

public module function MAPL_TrimString(istring, rc) result(ostring)

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*),	intent(in)			::	istring
integer,	intent(out),	optional		::	rc

Return Value character(len=:), allocatable

interface

public module subroutine MAPL_UnpackDateTime(date_time, yy, mm, dd, h, m, s)

Arguments

Type	Intent		Name
integer,	intent(in)	::	date_time(:)
integer,	intent(out)	::	yy
integer,	intent(out)	::	mm
integer,	intent(out)	::	dd
integer,	intent(out)	::	h
integer,	intent(out)	::	m
integer,	intent(out)	::	s

interface

public module subroutine MAPL_UnpackTime(TIME, IYY, IMM, IDD)

Arguments

Type	Intent		Name
integer,	intent(in)	::	TIME
integer,	intent(out)	::	IYY
integer,	intent(out)	::	IMM
integer,	intent(out)	::	IDD

interface

public module function MAPL_incymd(nymd, m)

Arguments

Type	Intent	Optional	Attributes		Name
integer				::	nymd
integer				::	m

Return Value integer

interface

public module function MAPL_nhmsf(nsec)

Arguments

Type	Intent	Optional	Attributes		Name
integer				::	nsec

Return Value integer

interface

public module function MAPL_nsecf(nhms)

Arguments

Type	Intent	Optional	Attributes		Name
integer,	intent(in)			::	nhms

Return Value integer

interface

public module function MAPL_nsecf2(nhhmmss, nmmdd, nymd)

Arguments

Type		Name
integer	::	nhhmmss
integer	::	nmmdd
integer	::	nymd

Return Value integer

interface

public module subroutine MAPL_tick(nymd, nhms, ndt)

Arguments

Type		Name
integer	::	nymd
integer	::	nhms
integer	::	ndt

Derived Types

type, public :: MAPL_Communicator

Components

Type	Visibility		Name
integer,	public	::	comm
integer,	public	::	rank
integer,	public	::	root
integer,	public	::	size

MAPL_Base Module

Contents

Variables

Interfaces

Derived Types

MODULE: MAPL_Base

Uses

Used by

Descendants:

Variables

Interfaces

interface

public module subroutine MAPL_AllocateCoupling(field, rc)

Arguments

public interface MAPL_AttributeSet

private interface MAPL_StateAttSetI4()

Arguments

private interface MAPL_BundleAttSetI4()

Arguments

private interface MAPL_FieldAttSetI4()

Arguments

interface

public module function MAPL_BundleCreate(name, grid, fieldNames, is2D, isEdge, long_names, units, rc) result(B)

Arguments

Return Value type(ESMF_FieldBundle)

interface

public module subroutine MAPL_ClimInterpFac(CLOCK, I1, I2, FAC, RC)

Arguments

interface

public pure module subroutine MAPL_DecomposeDim(dim_world, dim, NDEs, unusable, symmetric, min_DE_extent)

Arguments

interface

public module subroutine MAPL_FieldAllocCommit(field, dims, location, typekind, hw, ungrid, default_value, rc)

Arguments

public interface MAPL_FieldBundleAdd

private interface MAPL_FieldBundleAddField()

Arguments

interface

public module subroutine MAPL_FieldBundleDestroy(Bundle, RC)

Arguments

public interface MAPL_FieldBundleGet

private interface MAPL_FieldBundleGetByIndex()

Arguments

interface

public module subroutine MAPL_FieldCopy(FROM, TO, RC)

Arguments

interface

public module subroutine MAPL_FieldCopyAttributes(FIELD_IN, FIELD_OUT, RC)

Arguments

public interface MAPL_FieldCreate

private interface MAPL_FieldCreateRename()

Arguments

private interface MAPL_FieldCreateNewgrid()

Arguments

private interface MAPL_FieldCreateR4()

Arguments

interface

public module function MAPL_FieldCreateEmpty(NAME, GRID, RC) result(FIELD)

Arguments

Return Value type(ESMF_Field)

public interface MAPL_FieldGetTime

private interface MAPL_GetFieldTimeFromField()

Arguments

private interface MAPL_GetFieldTimeFromState()

Arguments

public interface MAPL_FieldSetTime

private interface MAPL_SetFieldTimeFromField()

Arguments

private interface MAPL_SetFieldTimeFromState()

Arguments

interface

public module subroutine MAPL_FieldSplit(field, fields, aliasName, rc)

Arguments

interface

public module subroutine MAPL_GRID_INTERIOR(grid, I1, IN, J1, JN)

Arguments

interface

public module subroutine MAPL_GenGridName(im, jm, lon, lat, xyoffset, gridname, geos_style)

Arguments

interface

MODULE: `MAPL_Base`