MODULE dart_pop_mod (POP)

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: dart_pop_mod.html 6340 2013-07-31 14:15:20Z nancy $

NAMELIST / INTERFACES / FILES / REFERENCES / ERRORS / PLANS / PRIVATE COMPONENTS / TERMS OF USE

Overview

dart_pop_mod provides a consistent collection of routines that are useful for multiple programs e.g. dart_to_pop, pop_to_dart, etc.

[top]

NAMELIST

There are no namelists unique to this module. It is necessary for this module to read some of the POP namelists, and so they are declared in this module. In one instance, DART will read the time_manager_nml namelist and write an updated version to control the length of the integration of POP. All other information is simply read from the namelists and is used in the same context as POP itself. The POP documentation should be consulted. Only the variables of interest to DART are described in this document.

All namelists are read from a file named pop_in.

namelist /time_manager_nml/  allow_leapyear, stop_count, stop_option

dart_to_pop controls the model advance of LANL/POP by creating a &time_manager_nml in pop_in.DART IFF the DART state being converted has the 'advance_to_time' record. The pop_in.DART must be concatenated with the other namelists needed by POP into a file called pop_in . We have chosen to store the other namelists (which contain static information) in a file called pop_in.part2. Initially, the time_manager_nml is stored in a companion file called pop_in.part1 and the two files are concatenated into the expected pop_in - then, during the course of an assimilation experiment, DART keeps writing out a new time_manager_nml with new integration information - which gets appended with the static information in pop_in.part2 

Contents Type Description
allow_leapyear    logical DART ignores the setting of this parameter. All observations must use a Gregorian calendar. There are pathological cases, but if you are doing data assimilation, just use the Gregorian calendar. [default: .true.]
stop_count integer the number of model advance steps to take. [default: 1]
stop_option character(len=64)    The units for the number of model advance steps (stop_count) to take. [default: 'ndays']

namelist /io_nml/  luse_pointer_files, pointer_filename
Contents Type Description
luse_pointer_files logical switch to indicate the use of pointer files or not. If .true., a pointer file is used to contain the name of the restart file to be used. DART requires this to be .true. [default: .true.]
pointer_filename character(len=100) The name of the pointer file. All of the DART scripts presume and require the use of the default. Each ensmeble member gets its own pointer file. [default: rpointer.ocn.[1-N].restart]


namelist /restart_nml/  restart_freq_opt, restart_freq
Contents Type Description
luse_pointer_files    logical switch to indicate the use of pointer files or not. If .true., a pointer file is used to contain the name of the restart file to be used. DART requires this to be .true. [default: .true.]
pointer_filename character(len=100)    The name of the pointer file. All of the DART scripts presume and require the use of the default. Each ensmeble member gets its own pointer file. [default: rpointer.ocn.[1-N].restart]


namelist /init_ts_nml/  init_ts_option, init_ts_file, init_ts_file_fmt

The dart_pop_mod:initialize_module() routine reads pop_in . There are several code stubs for future use that may allow for a more fully-supported POP namelist implementation. This namelist is one of them. Until further notice, the init_ts_nml is completely ignored by DART.

Contents Type Description
init_ts_option character(len=64) NOT USED by DART. All T,S information comes from a netCDF restart file named pop.r.nc [default: 'restart']
init_ts_file character(len=100)    NOT USED by DART. All T,S information comes from pop.r.nc [default: 'pop.r']
init_ts_file_fmt    character(len=64) NOT USED by DART. The file format is 'nc' [default: 'nc']


namelist /domain_nml/  ew_boundary_type

DART needs to know if the East-West domain is cyclic for spatial interpolations. Presently, DART has only been tested for the dipole grid, which is cyclic E-W and closed N-S.

Contents Type Description
ew_boundary_type    character(len=64)    switch to indicate whether the East-West domain is cyclic or not. DART/POP has not been tested in a regional configuration, so DART requires this to be 'cyclic'. [default: 'cyclic']


namelist /grid_nml/  horiz_grid_opt,  vert_grid_opt,  topography_opt, &
                               horiz_grid_file, vert_grid_file, topography_file

The POP grid information comes in several files: horizontal grid lat/lons in one, the vertical grid spacing in another, and the topography (lowest valid vertical level) in a third.

Here is what we can get from the (binary) horizontal grid file:

real(r8), dimension(:,:) :: ULAT,  &! latitude  (radians) of U points
real(r8), dimension(:,:) :: ULON,  &! longitude (radians) of U points
real(r8), dimension(:,:) :: HTN ,  &! length (cm) of north edge of T box
real(r8), dimension(:,:) :: HTE ,  &! length (cm) of east  edge of T box
real(r8), dimension(:,:) :: HUS ,  &! length (cm) of south edge of U box
real(r8), dimension(:,:) :: HUW ,  &! length (cm) of west  edge of U box
real(r8), dimension(:,:) :: ANGLE  &! angle

The vertical grid file is ascii, with 3 columns/line:

cell thickness(in cm)   cell center(in m)   cell bottom(in m)

Here is what we can get from the topography file:

integer, dimension(:,:), :: KMT    &! k index of deepest grid cell on T grid

These must be derived or come from someplace else ...

KMU               k index of deepest grid cell on U grid
HT                real(r8) value of deepest valid T depth (in cm)
HU                real(r8) value of deepest valid U depth (in cm)
Contents Type Description
horiz_grid_opt, vert_grid_opt, topography_opt character(len=64) switch to indicate whether or not the grids will come from an external file or not. DART requires ALL of these to be 'file'. [default: 'file']
horiz_grid_file character(len=100) The name of the binary file containing the values for the horizontal grid. The dimensions of the grid are read from pop.r.nc. It would have been nice to include the actual grid information in the netCDF files. [default: 'horiz_grid.gx3v5.r8ieee.le']
vert_grid_file character(len=100) The name of the ASCII file containing the values for the vertical grid. The file must contain three columns of data pertaining to the cell thickness (in cm), the cell center (in meters), and the cell bottom (in meters). Again, it would have been nice to include the vertical grid information in the netCDF files. [default: 'vert_grid.gx3v5']
topography_grid_file character(len=100) The name of the binary file containing the values for the topography information. The dimensions of the grid are read from pop.r.nc. [default: 'topography.gx3v5.r8ieee.le']

[top]

OTHER MODULES USED

types_mod
time_manager_mod
utilities_mod
typesizes
netcdf
[top]

PUBLIC INTERFACES

Only a select number of interfaces used are discussed here. Each module has its own discussion of their routines.

Interface Routines

use dart_pop_mod, only : get_pop_calendar
 set_model_time_step
 get_horiz_grid_dims
 get_vert_grid_dim
 read_horiz_grid
 read_topography
 read_vert_grid
 write_pop_namelist
 get_pop_restart_filename

Required Interface Routines


call get_pop_calendar(calstring)
character(len=*), intent(out) :: calstring

Returns a string containing the type of calendar in use.

calstring DART/POP uses a 'gregorian' calendar.


poptimestep = set_model_time_step()
type(time_type), intent(out) :: poptimestep

set_model_time_step returns the model time step that was set in the restart_nmlrestart_freq. This is the minimum amount of time DART thinks the POP model can advance. Indirectly, this specifies the minimum assimilation interval.

poptimestep the minimum assimilation interval


call get_horiz_grid_dims(Nx, Ny)
integer, intent(out) :: Nx, Ny

get_horiz_grid_dims reads pop.r.nc to determine the number of longitudes and latitudes.

Nx    the length of the 'i' dimension in the POP restart file. The number of longitudes in use.
Ny    the length of the 'j' dimension in the POP restart file. The number of latitudes in use.


call get_vert_grid_dim( Nz )
integer, intent(out) :: Nz

get_vert_grid_dim reads pop.r.nc to determine the number of vertical levels in use.

Nz    the length of the 'k' dimension in the POP restart file. The number of vertical levels in use.


call read_horiz_grid(nx, ny, ULAT, ULON, TLAT, TLON)
integer,                    intent(in)  :: nx, ny
real(r8), dimension(nx,ny), intent(out) :: ULAT, ULON, TLAT, TLON

read_horiz_grid reads the direct access binary files containing the POP grid information. The first record is REQUIRED to be 'ULAT', the second record is REQUIRED to be 'ULON'.

nx    The number of longitudes in the grid.
ny    The number of latitudes in the grid.
ULAT    The matrix of latitudes for the UVEL and VVEL variables. Units are degrees [-90,90].
ULON    The matrix of longitudes for the UVEL and VVEL variables. Units are degrees. [0,360]
TLAT    The matrix of latitudes for the SALT and TEMP variables. Units are degrees [-90,90].
TLON    The matrix of longitudes for the SALT and TEMP variables. Units are degrees. [0,360]


call read_topography(nx, ny, KMT, KMU)
integer,                   intent(in)  :: nx, ny
integer, dimension(nx,ny), intent(out) :: KMT, KMU

read_topography reads the direct access binary files containing the POP topography information. The first record is REQUIRED to be 'KMT'. 'KMU' is calculated from 'KMT'.

nx    The number of longitudes in the grid.
ny    The number of latitudes in the grid.
KMT    The matrix containing the lowest valid depth index at grid centroids.
KMU    The matrix containing the lowest valid depth index at grid corners.


call read_vert_grid(nz, ZC, ZG)
integer,                 intent(in)  :: nz
real(r8), dimension(nz), intent(out) :: ZC, ZG

read_vert_grid reads the ASCII file containing the information about the vertical levels. The file must contain three columns of data pertaining to; 1) the cell thickness (in cm),
2) the cell center (in meters),
and 3) the cell bottom (in meters).

nz    The number of vertical levels.
ZC    The depth (in meters) at the grid centers.
ZG    The depth (in meters) at the grid edges.


call write_pop_namelist(model_time, adv_to_time)
type(time_type), intent(in)  :: model_time
type(time_type), intent(in)  :: adv_to_time

write_pop_namelist writes the POP namelist time_manager_nml with the information necessary to advance POP to the next assimilation time. The namelist is written to a file called pop_in.DART. Presently, DART is configured to minimally advance POP for 86400 seconds - i.e. 1 day. The forecast length (the difference between 'model_time' and 'adv_to_time') must be an integer number of days with the current setup. An error will result if it is not.

model_time    The 'valid' time of the current model state.
adv_to_time    The time of the next assimilation.


call get_pop_restart_filename( filename )
character(len=*), intent(out) :: filename

get_pop_restart_filename returns the filename containing the POP restart information. At this point the filename is hardwired to pop.r.nc, but may become more flexible in future versions. The filename may be derived from the restart_nml but is currently ignored.

filename    The name of the POP restart file.

[top]

FILES

filename purpose
pop_in to read the POP namelists
pop.r.nc provides grid dimensions and 'valid_time' of the model state
&grid_nml "horiz_grid_file" contains the values of the horizontal grid
&grid_nml "vert_grid_file" contains the number and values of the vertical levels
&grid_nml "topography_grid_file" contains the indices of the wet/dry cells
pop_in.DART to control the integration of the POP model advance

[top]

REFERENCES

[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
initialize_module pop_in:init_ts_file pop.r.nc not found' The POP restart file MUST be called 'pop.r.nc'. Make a soft link if necessary.
get_horiz_grid_dims unable to find either 'i' or 'nlon' in file pop.r.nc The POP restart file must contain dimensions named either 'i' or 'nlon'.
get_horiz_grid_dims unable to find either 'j' or 'nlat' in file pop.r.nc The POP restart file must contain dimensions named either 'j' or 'nlat'.
set_model_time_step restart_freq_opt must be nday Pretty self-explanatory. The POP namelist must specify the forecast length as a multiple of 'days'.
write_pop_namelist adv_to_time has seconds == xxx must be zero' DART is asking POP to advance to a time that is a fraction of a day away. This should not be possible. Contact the DART developers.
write_pop_namelist stop_option must be "nday" the POP time_manager_nml:stop_option is not set to 'nday'. This is required by DART.
read_horiz_grid pop_in:horiz_grid_file 'XYZ' not found The horizontal grid filename specified in pop_ingrid_nml cannot be found.
calc_tpoints pop_in&domain_nml:ew_boundary_type 'X' unknown The ew_boundary_type must be 'cyclic' - until DART/POP gets tested with non-cyclic domains.
read_topography pop_in:topography_file 'XYZ' not found The topography file specified in pop_ingrid_nml cannot be found.
read_vert_grid pop_in:vert_grid_file 'XYZ' not found The vertical grid file specified in pop_ingrid_nml cannot be found.
read_vert_grid error reading depths, line 'X' The vertical grid file is corrupt or does not have the expected three pieces of information per line.

KNOWN BUGS

There are no known bugs, but there sure is a lot of dependence on assimilating on daily boundaries - and the pop.r.nc file.

[top]

FUTURE PLANS

none at this time

[top]

PRIVATE COMPONENTS

N/A

[top]

Terms of Use

DART software - Copyright 2004 - 2013 UCAR.
This open source software is provided by UCAR, "as is",
without charge, subject to all terms of use at
http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 6340 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/classic/models/POP/dart_pop_mod.html $
Change Date: $Date: 2013-07-31 08:15:20 -0600 (Wed, 31 Jul 2013) $
Change history:  try "svn log" or "svn diff"