Contact: B. Wyman
Reviewers:
Change history: WebCVS Log for bgrid_prog_var.f90
Initializes a data structure that contains the B-grid core
prognostic variables. There are several public routines that
operate with this data structure.
This module allocates memory for the B-grid core prognostics
variables: surface pressure, temperature, momentum, and tracers;
and provides several routines for handling these variables.
The module has routines for:
1) setting up the prognostic variables in a data structure
2) performing simple arithmetic with this data structure
3) applying forward explicit time differencing
4) reading and writing prognostic variable restart files
All array storage includes the halo region when the allocation is done.
Additional public interfaces allocate storage for separate fields.
bgrid_horiz_mod bgrid_vert_mod bgrid_masks_mod bgrid_halo_mod bgrid_cold_start_mod fms_mod field_manager_mod tracer_manager_mod
use bgrid_prog_var_mod [, only: prog_var_type,
prog_var_init,
var_init,
prog_var_times_scalar,
prog_var_equals_scalar,
prog_var_time_diff,
open_prog_var_file,
read_prog_var,
write_prog_var ]
prog_var_type
Data structure containing horizontal and vertical
grid indices, and the prognostic variables for
surface pressure, momentum, temperature, and tracers.
prog_var_init
Initializes the data structure, prog_var_type.
Note: all data arrays are initially set to zero.
var_init
Initializes storage for a single real array (and sets it to zero).
prog_var_times_scalar
Operates on a "prog_var_type" data structure.
Multiplies the prognostic variables by a scalar.
prog_var_equals_scalar
Operates on a "prog_var_type" data structure.
Assigns a scalar to all prognostic variables.
prog_var_time_diff
Operates on "prog_var_type" data structures.
This interface performs explicit time differencing.
open_prog_var_file
Opens the restart file for bgrid prognostic variables.
read_prog_var
Reads the restart file for bgrid prognostic variables.
write_prog_var
Reads the restart file for bgrid prognostic variables.
type prog_var_type
--- integers (scalar) ---
nlon = size of the global x-axis compute grid
(i.e., number of longitude points)
nlat = size of the global y-axis compute grid
(i.e., number of latitude points)
nlev = number of vertical levels
ntrace = number of tracers (in the current data structure)
ilb = lower bound index of x-axis (data domain)
iub = upper bound index of x-axis (data domain)
jlb = lower bound index of y-axis (data domain)
jub = upper bound index of y-axis (data domain)
klb = lower bound index of k-axis (always =1)
kub = upper bound index of k-axis (always =nlev)
--- prognostic fields (real arrays) ---
ps = surface pressure
[real, dimension (ilb:iub, jlb:jub) ]
pssl = surface pressure at eta=1 (sea level)
[real, dimension (ilb:iub, jlb:jub) ]
u = zonal wind component
[real, dimension (ilb:iub, jlb:jub, klb:kub) ]
v = meridional wind component
[real, dimension (ilb:iub, jlb:jub, klb:kub) ]
t = temperature
[real, dimension (ilb:iub, jlb:jub, klb:kub) ]
r = arbitrary number of tracers
[real, dimension (ilb:iub, jlb:jub, klb:kub, 1:ntrace) ]
call prog_var_init ( Hgrid, nlev, ntrs, Vars )
INPUT
Hgrid Data structure containing horizontal grid constants.
[type(horiz_grid_type), see horiz_grid_mod]
nlev The number of full model levels for the prognostic variables.
[integer]
ntrs The total number of tracers.
[integer]
INPUT/OUTPUT
Vars Data structure (derived-type variable) that contains the
B-grid prognostic fields (see above).
[type(prog_var_type)]
---------------------------------------------------------------------
The interface var_init can take several forms.
var => var_init ( Hgrid )
var => var_init ( Hgrid, kdim )
var => var_init ( Hgrid, kdim, ntrace )
var => var_init ( ilb, iub, jlb, jub )
var => var_init ( ilb, iub, jlb, jub, kdim )
var => var_init ( ilb, iub, jlb, jub, kdim, ntrace )
INPUT
Hgrid Data structure containing horizontal grid constants.
[type(horiz_grid_type), see horiz_grid_mod]
ilb Lower bound/index for first dimension.
[integer]
iub Upper bound/index for first dimension.
[integer]
jlb Lower bound/index for second dimension.
[integer]
jub Upper bound/index for second dimension.
[integer]
kdim The size of the third dimension (or level dimension).
[integer]
ntrace The size of the fourth dimension (or tracer dimension).
[integer]
RETURNS
The returned value is a pointer to memory.
Fields that are initialized this way must be declared at pointers.
Use the following syntax:
real, pointer :: var(:,:) or var(:,:,:) or var(:,:,:,:)
---------------------------------------------------------------------
call prog_var_times_scalar ( Var, scalar )
INPUT/OUTPUT
Var prog_var_type which on output will have the
prognostic variable components (u,v,t,r,ps,pssl)
multiplied by scalar
INPUT
scalar a real scalar quantity
---------------------------------------------------------------------
call prog_var_equals_scalar ( Var, scalar )
INPUT/OUTPUT
Var prog_var_type which on output will have the
prognostic variable components (u,v,t,r,ps,pssl)
set equal to scalar
INPUT
scalar a real scalar quantity
---------------------------------------------------------------------
call prog_var_time_diff ( dt, Var_dt, Var, nt )
INPUT
dt time step [real]
INPUT/OUTPUT
Var_dt input value is the tendency for prognostic variables,
the output value is zero [prog_var_type]
Var the prognostic variables, the input values are at time
level n, and the output values are at time level n+1
[prog_var_type]
OPTIONAL INPUT
nt number of tracers to be advanced in time, by default
all tracers will be advanced from time n to n+1
---------------------------------------------------------------------
call open_prog_var_file ( ix, jx, kx [, dir] )
DESCRIPTION
This routine can open and read either a NATIVE or NETCDF restart file.
The file name is "bgrid_prog_var.res" or "bgrid_prog_var.res.nc".
The directory that the file resides in is specified by an
optional argument.
OUTPUT
ix, jx, kx The 3-dimensional size of a prognostic field.
(i.e., global resolution read from the restart file)
[integer]
OPTIONAL INPUT
dir Directory where input restart files reside.
For the current directory use: "" or "."
The maximum length is 128 characters.
[character, default: dir='INPUT']
-------------------------------------------------------------
call read_prog_var ( Hgrid, Var, eta, peta, fis, res )
DESCRIPTION
This routine can read either a NATIVE or NETCDF restart file.
The file name is "bgrid_prog_var.res" or "bgrid_prog_var.res.nc".
The directory that the file resides in is specified by
interface open_prog_var_file.
INPUT/OUTPUT
Hgrid Data structure containing horizontal grid constants.
[type(horiz_grid_type)]
Var Data structure containing prognostic variables.
[type(prog_var_type)]
OUTPUT
eta sigma/eta/bk values at model layer interfaces (half levels)
[real, dimension(:)]
peta reference pressures (pk) at model layer interfaces
[real, dimension(:)]
fis geopotential height of the surface
[real, dimension(Hgrid%ilb:Hgrid%iub,Hgrid%jlb:Hgrid%jub)]
res reciprocal of eta at the surface
[real, dimension(Hgrid%ilb:Hgrid%iub,Hgrid%jlb:Hgrid%jub)]
NOTES
Tracers are not read from the prognostic variable file.
For NETCDF format, the tracers are read from a file
called "atmos_tracers.res.nc".
For NATIVE format, the tracers are read from separate
files for each tracers called "tracer_$$$$.res", where
$$$$ is the tracer name.
-------------------------------------------------------------
call write_prog_var ( Var, Hgrid, Vgrid, fis, res [, dir, format] )
DESCRIPTION
This routine can write either a NATIVE or NETCDF restart file.
The file name is "bgrid_prog_var.res" or "bgrid_prog_var.res.nc".
The directory that the file resides in is specified by an
optional argument.
INPUT
Var Data structure containing prognostic variables.
[type(prog_var_type)]
Hgrid Data structure containing horizontal grid constants.
[type(horiz_grid_type)]
Vgrid Data structure containing vertical grid constants.
[type(vert_grid_type)]
fis geopotential height of the surface
[real, dimension(Hgrid%ilb:Hgrid%iub,Hgrid%jlb:Hgrid%jub)]
res reciprocal of eta at the surface
[real, dimension(Hgrid%ilb:Hgrid%iub,Hgrid%jlb:Hgrid%jub)]
OPTIONAL INPUT
dir Directory where output restart files reside.
For the current directory use: "" or "."
The maximum length is 128 characters.
[character, default: dir='RESTART']
format File format for output restart files.
Valid formats are: 'NATIVE' or 'NETCDF'.
[character, default: format='NETCDF']
NOTES
Tracers are not written to the prognostic variable file.
If format='NETCDF', then tracers are written to a file
called "atmos_tracers.res.nc".
If format='NATIVE', then tracers are written to separate
files for each tracers called "tracer_$$$$.res", where
$$$$ is the tracer name.
FATAL errors in bgrid_prog_var_mod
can not read tracers with wrong size
The size of a tracer in file atmos_tracers.res.nc
does not match the 3D model resolution.
FATAL errors in write_prog_var
invalid value for optional argument format
The optional argument format can only have the
following values: 'NATIVE' or 'NETCDF'.
None.
None.
Need routines to release allocated memory.
These may be called prog_var_end and var_end.