COHERENS V2 User Manual: Patrick Luyten

MUMM - BMM - UGMM [1]
' $
COHERENS V2 user manual
Patrick Luyten
Royal Belgian Institute of the Natural Sciences

Management Unit of the Mathematical Models
RBINS-MUMM
Patrick.Luyten@mumm.ac.be
COHERENS training course

& %
' $
Setup files for user application

defruns : Simulation titles, activates CIF
Usrdef Model.f90 : “Basic” model setup (model parameters, bathymetry, domain
decomposition, initial conditions, open boundary conditions)
Usrdef Surface Data.f90 : Surface grids and data
Usrdef Nested Grids.f90 : Definition of nested sub-grids
Usrdef Time Series.f90 : Time series output
Usrdef Time Averages.f90 : Time-averaged output
Usrdef Harmonic Analysis.f90: Harmonic analysis and output
Usrdef Output.f90 : User-defined output
& %
' $
File defruns V2.1.2

Format:
runtitle,status,name
runtitle,status,,
runtitle,,
.......
• Each line represents a separate simulation and is composed of three arguments, separated by a “,”
• runtitle is the title of the simulation (must be present)
• status is either:
– ‘W’: A CIF is written
– ‘R’: Setup parameters are defined by reading from a CIF
– ‘’ (empty): The CIF is neither read or written
• name is the name of the CIF (if status is defined). A default is taken if no name is given.
• Lines starting with “!” are ignored
& %
' $
File Usrdef Model.f90

Contains the following subroutinesa
usrdef init params∗ : parameters for log files, error checking, timer report
usrdef mod params∗ : switches and model parameters, file definitions
usrdef grid : model grid and bathymetry
usrdef partition : domain decomposition
usrdef phsics : initial conditions for the physics
usrdef 1dsur spec : define specifier arrays for surface forcing (1-D mode only)
usrdef 2dobc spec : define specifier arrays for the open boundary conditions of the 2-D mode
(transports and elevations)
usrdef profobc spec: define specifier arrays for the open boundary conditions of the 3-D mode (currents,
temperature and salinity)
usrdef 1dsur data : data for surface forcing (1-D mode only)
usrdef 2dobc data : open boundary data for the 2-D mode (transports and elevations)
usrdef profobc data: open boundary data for the 3-D mode (currents, temperature and salinity)
usrdef rlxobc spec : define specifier arrays for application of flow relaxation scheme
a routines marked by a ∗ can be replaced by a CIF
& %
' $
usrdef init params

Define initial setup parameters:
- cold or warm start
- monitoring files: “log”-files, error checking and error files, warning file, timer report file
LOGICAL :: cold start The program executes model initialisation and finalisation, but does
not enter the time loop (.FALSE.).
INTEGER :: levprocs ini(npworld) Determines the level of tracing of the inilog file for each process. If 0
(default value), no log file will be written. The inilog file only contains
information about model initialisation and is closed as soon as the
program enters the time loop. The size (npworld) of the vector array
equals the number of processes, initially defined within
MPI COMM WORLD or equals 1 in the serial case.
INTEGER :: levprocs run(npworld) Determines the level of tracing of the runlog file for each process. If 0
(default value), no log file will be written. The runlog file traces
program execution during the time loop.
& %
' $
INTEGER :: levprocs err(npworld) Level for error checking (0).

0: error checking disabled (for particular processor)
1: error checking enabled during initialisation phase only
2: error checking enabled throughout the whole program
INTEGER :: levtimer Determines the type of information in the timer report (0).
0: No timer report is written.
1: Writes the total execution time only.
2: Writes time information (in % of total time) for all “timers”.
3: In case of a parallel run, the information is written for each
individual process. In the serial case, behaviour is as for case 2.
INTEGER :: timer format Write format for total execution time in the timer report (0).
0: no timer report is written
1: seconds
2: minutes
3: hours
4: days
& %
' $
usrdef mod params
Process numbers for parallel processing

The parameters below only need to be supplied in case of parallel applications. Values are between 0
and npworld.
nprocs The actual number of processes to be used (1).
nprocsx X-dimension of the decomposed domain (0).
nprocsy Y-dimension of the decomposed domain (0).
In case of an external (user-defined) decomposition (iopt MPI partit = 2) nprocs must equal its external
definition, while nprocsx and nprocsy are defined internally by the program. Otherwise (iopt MPI partit
= 1), the procedure is as follows:
1. nprocsx and nprocsy are non-zero: nprocs is set to nprocsx×nprocsy
2. both nprocsx and nprocsy are zero: both values are set internally so that nprocsx×nprocsy = nprocs
and |nprocsx-nprocsy| is minimal
3. nprocsx is non-zero, while nprocsy is zero: nprocsy = nprocs/nprocsx
4. nprocsy is non-zero, while nprocsx is zero: nprocsx = nprocs/nprocsy
Remarks
- Cases 2–4: if nprocs is zero, its value is set to npworld
- Case 3–4: if no integer division is possible, an error is issued
& %
' $
Model switches (84)

Defaults are given in parentheses.
model grid
iopt grid sph Type of coordinates (0).

0 : Cartesian coordinates
1 : spherical coordinates
iopt grid htype Type of horizontal grid (1).
1 : uniform rectangular grid
2 : non-uniform rectangular grid
3 : curvilinear grid
iopt grid vtype Type of vertical grid (1).
1 : uniform σ-grid
2 : non-uniform σ-grid
3 : general (horizontally and vertically non-uniform) σ-coordinate grid
iopt grid nodim Grid dimension (3).
1 : 1-dimensional grid (water column model)
2 : 2-dimensional grid (depth-averaged model without vertical structure)
3 : 3-dimensional grid
& %
' $
density
iopt dens Evaluation of density and expansion coefficients (0).
0 : uniform density, zero expansion coefficients
1 : density from linear equation of state, uniform expansion coefficients
2 : from general equation of state (McDougall et al., 2006) without pressure effects
3 : from general equation of state with pressure effects
iopt dens grad Selects numerical algorithm for discretisation of baroclinic pressure gradient (see User
Documentation) (1).
0 : gradient set to zero
1 : traditional σ-coordinate (second order) method
2 : z-level method
3 : method of Shchepetkin and McWilliams [2003]
iopt sal Salinity update (0).
0 : uniform (space and time) salinity field
1 : salinity field initialised but not updated in time
2 : salinity field initialised and updated in time
iopt sal sbc Type of surface boundary condition for salinity (0).
0 : zero surface flux
1 : surface flux proportional to evaporation minus precipitation rate
& %
' $
iopt temp Temperature update (0).

0 : uniform (space and time) temperature field
1 : temperature field initialised but not updated in time
2 : temperature field initialised and updated in time
iopt temp optic Disables/enables (0/1) optical module (1).
0 : all solar radiation is absorbed at the surface, i.e. the solar heat flux is considered as a
downward surface heat flux defined at the surface
1 : solar radiation is absorbed within the water column using specified values for the attenuation
depths
iopt temp sbc Type of surface boundary condition for temperature (1).
1 : Neumann condition using the model’s surface heat flux formulations
2 : Dirichlet using prescribed surface temperature from a data file at the first grid point below
the surface
3 : Dirichlet using prescribed surface temperature from a data file at the surface itself
& %
' $
bottom boundary conditions
iopt bstres form Type of formulation for bottom stress (2).

0 : bottom stress set to zero
1 : linear bottom stress law
2 : quadratic bottom stress
iopt bstres drag Formulation for bottom drag coefficient (3).
0 : not used
1 : spatially uniform value
2 : spatially non-uniform obtained from data file
3 : using spatially uniform roughness length
4 : using spatially non-uniform roughness length taken from a data file
iopt bstres nodim Type of currents in bottom stress formulation (3).
2 : depth-mean currents
3 : 3-D current at bottom grid cell
& %
' $
advection
iopt adv scal Type of advection of scheme for advection of scalar quantities (3).
0 : advection disabled
1 : upwind scheme
2 : Lax-Wendroff (explicit) in the horizontal, central (semi-implicit) in the vertical (not
recommended!)
3 : TVD scheme
iopt adv 2D Type of advection of scheme for advection of 2-D transports (1).
1 : upwind scheme
recommended!)
3 : TVD scheme
iopt adv 3D Type of advection of scheme for advection of 3-D currents (1).
1 : upwind scheme
recommended!)
3 : TVD scheme
& %
' $
diffusion coefficients
iopt hdif coef Type of scheme for horizontal diffusion coefficients (0).
0: not used
1: spatially uniform
2: Smagorinsky formulation
iopt hdif scal Disables/enables (0/1) horizontal diffusion in scalar transport equations (0).
iopt hdif 2D Disables/enables (0/1) horizontal diffusion in 2-D transport equations (0).
iopt hdif 3D Disables/enables (0/1) horizontal diffusion in 3-D current transport equations (0).
iopt hdif turb Disables/enables (0/1) horizontal diffusion in turbulence transport equations (0).
iopt vdif coef Selects (general) type of vertical diffusion scheme (3).
0: vertical diffusion disabled
1: uniform diffusion coefficient
2: algebraic formulation
3: second order turbulence closure
& %
' $
turbulence schemes
iopt turb alg Type of algebraic scheme if iopt vdif coef =2 (1).
1 : Pacanowski-Philander
2 : Munk-Anderson
3–5: Flow dependent formulations
iopt turb lmix Mixing length formulation (4).
1 : parabolic law
2 : “modified” parabolic law
3 : “Xing” formulation
4 : “Blackadar” asymptotic formulation
iopt turb ntrans Number of transport equations (1).
0 : equilibrium method (“Mellor-Yamada level 2”)
1 : turbulence energy equation + mixing length selected by iopt turb lmix
2 : k-ε of k-kl equation
iopt turb param Selects type of second turbulent variable (2).
1 : mixing length l (k-l scheme)
2 : dissipation rate ε (k-ε scheme)
& %
' $
iopt turb stab mod Selects type of closure (RANS) model (4).
1 : Mellor and Yamada [Mellor and Yamada, 1974; Galperin et al., 1988]
2 : Kantha and Clayson [1994]
3 : Burchard and Baumert [1995]
4 : Hossain and Rodi [1982]
5 : Canuto A-scheme [Canuto, 2001]
6 : Canuto B-scheme [Canuto, 2001]
drying/wetting scheme
iopt fld Disables/enables (0/1) drying/wetting scheme (0).
& %
' $
open boundary conditions

iopt obc 2d (General) type of open boundary conditions for 2-D mode (0).
0 : default conditions at all open boundaries
1 : non-default conditions for at least one open boundary point
iopt obc 3d (General) type of open boundary conditions for 3-D currents (0).
iopt obc sal (General) type of open boundary conditions for salinity (0).
iopt obc temp (General) type of open boundary conditions for temperature (0).
tides
iopt astro tide Disables/enables (0/1) inclusion of astronomical tidal force in momentum equations (0).
iopt astro pars Selects evaluation of tidal parameters (0).
0 : astronomical argument set to zero, nodal factors set to 1
1 : evaluate astronomical phases at a given time and reference longitude, nodal factors are set to 1
& %
2 : evaluate astronomical phases and nodal factors at a given time and reference longitude
' $
meteorological forcing
iopt meteo Disables/enables (0/1) meteorological input (0).

iopt meteo stres Selects type of input data for barotropic mode, i.e. surface stress and pressure (0).
0 : no input
1 : components of wind speed (U10 ,V10 ) and (unless iopt grid nodim=1) atmospheric
pressure Pa
2 : components of surface stress (τsu ,τsv ) and (unless iopt grid nodim=1) atmospheric
pressure Pa
iopt meteo heat Selects type of input data for heat fluxes (0).
0 : no input
1 : air temperature Ta , relative humidity RH, cloud cover fc
2 : total (downward) non-solar surface heat flux, cloud cover fc
3 : total (downward) non-solar surface heat flux, surface solar radiance Qrad
4 : cloud cover fc
5 : surface solar radiance Qrad
iopt meteo salflx Selects type of input data for salinity flux (0).
0 : no input
1 : evaporation minus precipitation rate Evap − Prc
2 : precipitation rate Prc
& %
' $
surface boundary conditions
iopt sflux cds Formulation for neutral surface drag coefficient CDs (0).
0 : constant value
1 : Large and Pond [1981]
2 : Smith and Banke [1975]
3 : Geernaert et al. [1986]
4 : Kondo [1975]
5 : Blanc [1985]
6 : Charnock’s relation
iopt sflux cehs Formulation for neutral surface (heat) exchange coefficients CE , CH (0).
0 : constant value
1 : Large and Pond [1982]
2 : Anderson and Smith [1981]
3 : Kondo [1975]
4 : Blanc [1985]
& %
' $
iopt sflux strat Selects dependence of surface drag and exchange coefficients on atmospheric
stratification effects (0).
0 : no dependence
1 : using Kondo’s [1975] parameterisation
2 : using Monin-Obukhov similarity theory
nesting
iopt nests Disables/enables (0/1) output for nested sub-grids (0).
& %
' $
MPI mode
The non-blocking options need to be re-programmed and should not be used in the present version !
iopt MPI partit Selects method for domain decomposition (1).
1: “simple” partition based on the values of nprocsx and nprocsy
2: decomposition obtained from an external data file
user output
iopt out tsers Disables/enables (0/1) time series output (1).

iopt out avrgd Disables/enables (0/1) time averaged output (0).
iopt out anal Disables/enables (0/1) harmonic output (0).
& %
' $
A * means that a parameter must always be defined (no default available).
Date and time parameters

CStartDateTime Start date in string format (yyyy/mm/dd;hh:mm:ss,mmm) of 23 characters (*).
CEndDateTime End date in string format (*).
delt2d 2-D time step [s]. Time step is limited to one millisecond if delt2d is lower than 1000 s
or to 1 second otherwise (*).
ic3d number of 2-D time steps within one 3-D time step (1).
icnodal time step (measured in units of delt2d) for updating of nodal tidal factors and
astronomical arguments if iopt astro pars >0. If zero, nodal factors are initialised by
not updated (0).
time zone Time zone, i.e. difference of local time with respect to GMT [hours]. Difference is
positive (negative) eastwards (westwards) from Greenwich (0).
& %
' $
Model constants
nc Number of grid cells in the X-direction (including an extra column along the eastern
edge) (*)
nr Number of grid cells in the Y-direction (including an extra column along the northern
edge) (*)
nz Number of grid cells in the vertical direction (*)
nosbu Number of open sea boundaries at U-nodes (West/East) (0)
nosbv Number of open sea boundaries at V-nodes (South/North) (0)
nrvbu Number of river boundaries at U-nodes (West/East) (0)
nrvbv Number of river boundaries at V-nodes (South/North) (0)
nconobc Number of constituents for open boundary tidal forcing (0).
nonestsets Number of nested sub-grids used when iopt nests = 1 (0).
norestarts Number of restart times (1).
ntrestart(1:norestarts) Restart time indices for writing of initial conditions. If a value equals int fill, it
will be replaced by the total number of 2-D time steps (int fill).
dlat ref Reference latitude to be used for the Coriolis frequency in case of a Cartesian grid
[decimal degrees] (0.0).
dlon ref Reference longitude to be used for solar irradiance in case of a Cartesian grid [decimal
degrees] (0.0).
& %
' $
dlon ref obc If iopt astro pars > 0, phases at open boundaries are assumed to be taken with respect
to astronomical argument at this reference value [decimal degrees]. If zero, the reference
longitude is taken at Greenwich (0.0).
gacc ref If different from real fill, spatially uniform acceleration of gravity. Otherwise, g is
evaluated as function of latitude [m/s2 ] (real fill).
sal ref Reference salinity used if iopt sal=0 or iopt dens ≤ 1 [PSU] (33.0).
temp min Minimum temperature. If set to real fill, the minimum is taken as the freezing point of
sea water which is a function of salinity [deg C] (0.0).
temp ref Reference temperature used if iopt temp=0 or iopt dens ≤1 [deg C] (12.0).
dcrit fld Critical water depth used in drying/wetting algorithm [m] (0.1).
dmin fld Minimum water depth used in drying/wetting algorithm [m] (0.02).
hdifmom cst Constant coefficient for horizontal momentum diffusion when iopt hdif coef=1 [m2 /s]
(0.0).
hdifscal cst Constant coefficient for horizontal scalar diffusion when iopt hdif coef=1 [m2 /s] (0.0).
vdifmom cst Constant coefficient for vertical diffusion of momentum used if iopt vdif coef=1 or as
bacground value if iopt turb iwlim=0 [m2 /s] (10−6 ).
vdifscal cst Constant coefficient for vertical diffusion of scalars used if iopt vdif coef=1 or as
bacground value if iopt turb iwlim=0 [m2 /s] (10−6 ).
bdragcoef cst Constant bottom drag coefficient CDb when iopt bstres drag=1 [-] (0.0).
zrough cst Constant bottom roughness length z0b when iopt bstres drag=3 [m] (0.0).
& %
' $
cds cst Constant surface drag coefficient CDs when iopt sflux cds=0 [-] (0.0013).
ces cst Constant surface exchange coefficient CE when iopt sflux cehs=0 [-] (0.0013).
chs cst Constant surface exchange coefficient CH when iopt sflux cehs=0 [-] (0.0013).
optattcoef1 cst Inverse optical attenuation depth for the absorption of long-wave solar radiation [m−1 ]
(10.0).
optattcoef2 cst Inverse optical attenuation depth for the absorption of short-wave solar radiation [m−1 ]
(2.06).
opt frac Long-wave fraction R of surface solar radiance [-] (0.54).
index obc(1:nconobc) Key ids of the tidal constituents used for the tidal forcing at open boundaries (0).
Turbulence constants
See User Documentation.
& %
' $
Parameters for surface data grids
Parameters characterising a surface grid are stored into the Fortran 90 DERIVED TYPE 2-D array
surfacegrids.
TYPE :: GridParams
INTEGER :: nhtype, n1dat, n2dat
REAL :: delxdat, delydat, x0dat, y0dat
END TYPE GridParams
TYPE (GridParams), DIMENSION(MaxGridTypes,2) :: surfacegrids
An element of the array surfacegrids can be generically represented as surfacegrids(igrd,ifil) where igrd is
the “grid descriptor” and ifil the “file number” (which in the present version always equals 1).
file descriptors
igrd model model grid

igrd meteo meteorological external grid
igrd sst sea surface temperature external grid
& %
' $
grid parameters
nhtype Type of surface grid.
0: single grid point
1: uniform rectangular grid
2: non-uniform rectangular grid
3: non-rectangular (curvilinear or non-structured)
4: same as model grid
n1dat X-dimension of surface grid.
n2dat Y-dimension of surface grid.
delxdat grid spacings in X-direction (m or fractional degrees longitude) when nhtype=1
delydat grid spacings in Y-direction (m or fractional degrees latitude) when nhtype=1
x0dat X-coordinate (Cartesian or longitude) of lower left corner when nhtype=1
y0dat Y-coordinate (Cartesian or latitude) of lower left corner when nhtype=1
• Note that if nhtype=4, then n1dat=nc and n2dat=nr.
• If nhtype=1, all parameters need to be defined.
• If nhtype=2,3, only n1dat and n2dat need to be defined.
• If nhtype=4, no further definitions need to be made.
• Parameters for the model grid need to be set according to the value of iopt grid htype which equals
nhtype. If nhtype=1, the (horizontal) model grid is defined by delxdat, delydat, x0dat, y0dat. The
latter 2 parameters are defined at the Soutwest corner of the domain.
& %
' $
Parameters for input and output forcing
The file parameters related to model forcing (either input or output) are stored into the Fortran 90
DERIVED TYPE 3-D array modfiles.
TYPE :: FileParams
LOGICAL :: defined, info, opened, time regular
CHARACTER (LEN=1) :: form, status
CHARACTER (LEN=leniofile) :: filename, pathname
CHARACTER (LEN=lendesc) :: filedesc
INTEGER :: endfile, header type, iostat, iunit, &
& lenrec, maxrecs, nocoords, nodim, novars, timeid, &
& timerec, tskips, varid, zetaid
INTEGER, DIMENSION(3) :: tlims
END TYPE FileParams
TYPE (FileParams), DIMENSION(MaxIOTypes,MaxIOFiles,2) :: modfiles
Only the underlined parameters can be defined by the user, the others are used internally in the
program (e.g. iunit giving the FORTRAN file unit number).
& %
' $
An element of the array modfiles can be generically represented as modfiles(idesc,ifil,iotype) where idesc
is the “file descriptor”, ifil the “file number” and iotype represents input (output) data if 1 (2).
Almost all forcing data (except nesting) are input data, i.e. represented by an element of modfiles with
iotype=1. By defining a corresponding output element with iotype=2 the input data will re-written in a
COHERENS standard format. In case of nested output, iotype=2. The method also allows to define
multiple files for a given descriptor.
file descriptors
io mppmod parallel decomposition (ifil=1)

io inicon initial conditions (ifil=1)
io modgrd model grid (ifil=1)
io metgrd surface meteorological grid (ifil=1)
io sstgrd sea surface temperature grid (ifil=1)
io nstgrd nested sub-grids (one file per sub-grid)
io 1uvsur specifiers for 1-D surface forcing if ifil=1, forcing data if ifil=2
io 2uvobc specifiers for 2-D mode open boundary forcing if ifil=1, open boundary data if ifil>1
io 3uvobc specifiers for 3-D mode (baroclinic currents) open boundary forcing if ifil=1, open boundary
data if ifil>1
io salobc specifiers for salinity open boundary forcing if ifil=1, open boundary data if ifil>1
& %
' $
io tmpobc specifiers for temperature open boundary forcing if ifil=1, open boundary data if ifil>1
io rlxobc definitions of relaxation zones (ifil=1)
io nstspc specifiers for sub-grid nesting (ifil=1)
io 2uvnst 2-D open boundary data for nested sub-grids (one file per sub-grid)
io 3uvnst 3-D (baroclinic current) open boundary data for nested sub-grids (one file per sub-grid)
io salnst salinity open boundary data for nested sub-grids (one file per sub-grid)
io tmpnst temperature open boundary data for nested sub-grids (one file per sub-grid)
io metsur meteorological data (ifil=1)
io sstsur SST data (ifil=1)
& %
' $
file parameters for input forcing (iotype=1)
status Status of the data file.

‘0’: not defined
‘N’: user-defined
‘R’: COHERENS standard file
form File format.
‘A’: ASCII (portable, sequential)
‘U’: unformatted binary (non-portable, sequential)
‘N’: netCDF format (portable, non-sequential)
filename File name (including file path if needed).
tlims Start/end/step time indices (i.e. times measured in units of delt2d). These parameters
are not directly used for reading the data (except when time regular is set to .TRUE.),
but to make updates after tlims(3) 2-D time steps. If tlims(3)>0, time interpolation will
be performed.
endfile Switch to decide what action needs to be taken when an end of file conditions occurs
(0).
0: program aborts with error message
1: program continues, no further attempt will be made to read data
2: program continues, a next attempt to read the data will be made after nowaitsecs
seconds.
& %
' $
file parameters for output forcing (iotype=2)
status Status of the data file.

‘0’: not defined
‘W’: a COHERENS standard file will be created
form File format.
‘A’: ASCII (sequential)
‘U’: unformatted binary (machine-dependent, sequential)
‘N’: netCDF format (portable, non-sequential)
filename File name (including file path if needed).
Other relevant parameter components, not defined in usrdef mod params but used internally, are:
iunit File unit. This parameters is set internally and cannot be defined by the user.
iostat File I/O status
-1: open error occurred
0 : file not opened
1 : file is open and file pointer is located at the start or before the end of the file
2 : file pointer is located at the end of the file (i.e. an EOF condition will occur on a next
read
3 : an end of file condition did occur
& %
' $
User output
nosetstsr Number of time series file sets if iopt out tsers=1 (0).
nostatstsr Number of time series output stations if iopt out tsers=1 (0).
novarstsr Number of time series variables if iopt out tsers=1 (0).
nosetsavr Number of time averaged file sets if iopt out avrgd=1 (0).
nostatsavr Number of time averaged output stations if iopt out avrgd=1 (0).
novarsavr Number of time averaged variables if iopt out avrgd=1 (0).
nosetsanal Number of harmonic file sets if iopt out anal=1 (0).
nofreqsanal Number of harmonic frequencies if iopt out anal=1 (0).
nostatsanal Number of harmonic output stations if iopt out anal=1 (0).
novarsanal Number of harmonic variables if iopt out anal=1 (0).
intitle Title used to create names of model forcing files.
outtitle Title used to create names of user output files.
& %
' $
usrdef grid
• Define model grid and bathymetry if modfiles(io modgrd,1,1)%status=‘N’.
• Generic code can be found in examples/Usrdef Model.f90.
• Definitions of coordinate arrays depend on values of the switches iopt grid htype and iopt grid vtype.
• nobu=nosbu+nrvbu and nobv=nosbv+nrvbv are the total number of open boundary points at U-
and V-nodes.
All arrays are global and have the following meaning
gxcoordglb(1:nc,1:nr) X-coordinates (Cartesian or spherical) of model grid corner points (only
when iopt grid htype>1).
gycoordglb(1:nc,1:nr) Y-coordinates (Cartesian or spherical) of model grid corner points (only
when iopt grid htype>1).
gsigcoord(nz+1) σ-coordinates in case of a σ-grid with vertical spacings which are non-uniform
in the vertical but uniform in the horizontal (only when iopt grid vtype=2)
gscoordglb(1:nc-1,1:nr-1,nz+1) general σ-coordinates (only when iopt grid vtype=3)
depmeanglb(1:nc-1,1:nr-1) mean water depths [m] (bathymetry)
iobu grid indices in X-direction of open boundary points at U-nodes
jobu grid indices in Y-direction of open boundary points at U-nodes
iobv grid indices in X-direction of open boundary points at V-nodes
jobv grid indices in Y-direction of open boundary points at V-nodes
& %
' $
usrdef partition
Define domain decomposition if iopt MPI partit=2 and modfiles(io mppmod,1,1)%status=‘N’.
nc1procs(nprocs) global X-index of lower left cell of process domains

nc2procs(nprocs) global X-index of lower right cell of process domains
nr1procs(nprocs) global Y-index of lower left cell of process domains
nr2procs(nprocs) global Y-index of lower right cell of process domains
& %
' $
usrdef phsics
• Define initial conditions if modfiles(io inicon,1,1)%status=‘N’.
• Initialisation of some variables depends on the values of switches (see examples/Usrdef Model.f90).
• Arrays defined on the model grid need to be initialised “locally”. If they are obtained from a global
data file, distribution calls need to be made in the parallel case to extract the local values from the
global data.
• In parallel mode, arrays on the model grid are defined including their halos. The halo size of most
arrays equals nhalo=2.
• ncloc and nrloc are the X- and Y-dimensions of the local grid.
• Example procedures are given in examples/Usrdef Model.f90.
2-D mode
udvel(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) depth-integrated current in the X-direction [m2 /s]
vdvel(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) depth-integrated current in the Y-direction [m2 /s]
zeta(0:ncloc+1,0:nrloc+1) surface elevation [m]
3-D currents
uvel(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) current in X-direction [m/s]
& %
' $
vvel(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) current in Y-direction [m/s]

wvel(0:ncloc,0:nrloc,nz+1) transformed vertical current [m/s]
density arrays
temp(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) temperature [deg C]
sal(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) salinity [PSU]
turbulence arrays
tke(1-nhalo:ncloc+nhalo,nrloc,nz+1) turbulent kinetic energy [J/kg]
zlmix(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz+1) mixing length [m]
dissip(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz+1) dissipation of turbulent energy [W/kg]
bottom stress arrays

bdragcoefatc(0:ncloc,0:nrloc) bottom drag coefficient [-]
zroughatc(0:ncloc,0:nrloc) bottom roughness length [m]
tidal and open boundary arrays

& %
' $
usrdef 1dsur spec

Define specifiers for water column (1-D) surface forcing if modfiles(io 1uvsur,1,1)%status=‘N’.
gxslope amp(nconobc) amplitudes of X-component of pressure gradient [m2 /s]

gxslope pha(nconobc) phases of X-component of pressure gradient [rad]
gyslope amp(nconobc) amplitudes of Y-component of pressure gradient [m2 /s]
gyslope pha(nconobc) phases of Y-component of pressure gradient [rad]
zetadat amp(nconobc) amplitudes of surface elevation [m]
zetadat pha(nconobc) phases of surface elevation [rad]
isur1dtype type of data if surface data are obtained from a data file
(modfiles(io 1uvsur,2,1)%status = ‘N’ or ‘R’)
1: surface slopes and elevation
2: surface elevation
3: surface slopes
& %
' $
usrdef 2dobc spec

• Define specifiers for 2-D open boundary forcing if modfiles(io 2uvobc,1,1)%status=‘N’.
• nofiles-1 is the number of associated data files
general specifiers
ityp2dobu(nobu) type of open boundary condition at U-nodes (between 0-13)
ityp2dobv(nobv) type of open boundary condition at V-nodes (between 0-13)
iloczobu(nobu) position of elevation data at U-nodes
0: not specified
1: at U-node
2: at first C-node outside the domain
iloczobv(nobv) position of elevation data at V-nodes (0/1/2)
no2dobc(2:nofiles) number of data locations within each data file
iobc2dtype(2:nofiles) type of the 2-D data
1: depth-integrated currents and elevations
2: elevations only
3: depth-integrated currents only
& %
' $
index2dobc(nobu+nobv,2:nofiles) Each data file contains a sub-set of open boundary data points. The
element index2dobc(idat,ifil) maps, for file ifil, the local data point idat into a
corresponding global open boundary index (between 1:nobu for U- and
nobu+1:nobu+nobv for V-open boundaries). The physical size of the first
dimension for file ifil equals no2dobc(ifil).
amplitudes
ud2obu amp(nobu,nconobc) amplitudes of depth-integrated X-current at U-open boundaries [m2 /s]
vd2obv amp(nobv,nconobc) amplitudes of depth-integrated Y-current at V-open boundaries [m2 /s]
zetobu amp(nobu,nconobc) amplitudes of surface elevation at U-open boundaries [m]
zetobv amp(nobv,nconobc) amplitudes of surface elevation at V-open boundaries [m]
phases
ud2obu pha(nobu,nconobc) phases of depth-integrated X-current at U-open boundaries [rad]
vd2obv pha(nobv,nconobc) phases of depth-integrated Y-current at V-open boundaries [rad]
zetobu pha(nobu,nconobc) phases of surface elevation at U-open boundaries [rad]
zetobv pha(nobv,nconobc) phases of surface elevation at V-open boundaries [rad]
& %
' $
(5) 15 (5) 16 (5) 17 (5) 18
(2) 8
(2) 7 • first number in () is file number
(2) 6 (3) 11
• second number is open boundary index (nobu is
added at V-node points)
(2) 5 (3) 10
ifil=2: data at (U-)o.b. points 1 to 8
(2) 4 (3) 9
ifil=3: data at (U-)o.b. points 9 to 11
(2) 3 ifil=4: data at (V-)o.b. points 12 to 14
(6) 19
ifil=5: data at (V-)o.b. points 15 to 18
(2) 2
ifil=6: data at (V-)o.b. point 19
(2) 1
(4) 12 (4) 13 (4) 14
nobu = 11, nobv = 8
nofiles = 6; no2dobc = (/8,3,3,4,1/)

index2dobc(1:8,2) = (/1,2,3,4,5,6,7,8/)
index2dobc(1:3,3) = (/9,10,11/)
index2dobc(1:3,4) = (/12,13,14/)
index2dobc(1:4,5) = (/15,16,17,18/)
index2dobc(1,6) = 19
& %
' $
usrdef profobc spec

SUBROUTINE usrdef profobc spec(iddesc,itypobu,itypobv,iprofobu,iprofobv,&
& iprofrlx,noprofsd,indexprof,indexvar,novars,&
& nofiles)
INTEGER, INTENT(IN) :: iddesc, nofiles, novars
INTEGER, INTENT(INOUT), DIMENSION(2:nofiles) :: noprofsd
INTEGER, INTENT(INOUT), DIMENSION(nobu) :: itypobu
INTEGER, INTENT(INOUT), DIMENSION(nobv) :: itypobv
INTEGER, INTENT(INOUT), DIMENSION(nobu,novars) :: iprofobu
INTEGER, INTENT(INOUT), DIMENSION(nobv,novars) :: iprofobv
INTEGER, INTENT(INOUT), DIMENSION(nobu+nobv,2:nofiles) :: indexprof
INTEGER, INTENT(INOUT), DIMENSION(nobu+nobv,2:nofiles) :: indexvar
INTEGER, INTENT(INOUT), DIMENSION(norlxzones) :: iprofrlx
• Define specifiers for 3-D open boundary forcing if modfiles(iddesc,1,1)%status=‘N’.

• Input argument iddesc equals either io 3uvobc, io salobc, io tmpobc
• nofiles-1 is the number of associated data files.
• novars, indexvars are intended for future use and don’t need to be defined in the current version of
the program.
& %
' $
itypobu(nobu) type of open boundary condition at U-nodes

0: default (zero gradient condition or specified external profile)
1: radiation condition using internal wave speed
2: Orlanski condition
itypobv(nobv) type of open boundary condition at V-nodes (0/1/2)
iprofobu(nobu,novars) profile number used at U-open boundaries (0 is none)
iprofobv(nobv,novars) profile number used at V-open boundaries (0 is none)
noprofsd(2:nofiles) number of profiles per data file
indexprof(:,2:nofiles) Each data file contains a sub-set of open boundary profiles. The element
indexprof(iprof,ifil) maps, for file ifil, the local profile number idat into a
corresponding “global” index as defined by iprofobu and iprofobv. The physical size
of the first dimension for file ifil equals noprofsd(ifil).
& %
' $
profiles at open boundaries
(4) 4 (4) 4 (4) 4 (4) 4

• first number in () is file number
(2) 2
• second number is profile number
(2) 2
• total number of profiles is 5
(2) 2 0
• no profiles defined at eastern boundaries
(2) 2 0
(2) 1 0 ifil=2: data for profile numbers 1 and 2

(2) 1 ifil=3: data for profile number 3
(2) 1 (5) 5 ifil=4: data for profile number 4
(2) 1
ifil=5: data for profile number 5
(3) 3 (3) 3 (3) 3
nobu = 11; nobv = 8

itypobu = 0; itypobv = 0
iprofobu(:,1) = (/1,1,1,1,2,2,2,2,0,0,0/)
iprofobv(:,1) = (/3,3,3,4,4,4,4,5/)
nofiles = 5; noprofsd(2:5) = (/2,1,1,1/)
indexprof(1:2,2) = (/1,2/)
indexprof(1,3) = 3
indexprof(1,4) = 4
indexprof(1,5) = 5
& %
' $
usrdef 1dsur data

SUBROUTINE usrdef_1dsur_data(ciodatetime,data1d,novars)
CHARACTER (LEN=lentime), INTENT(INOUT) :: ciodatetime
INTEGER, INTENT(IN) :: novars
REAL, INTENT(INOUT), DIMENSION(novars) :: data1d
Define water column (1-D) surface forcing if modfiles(io 1uvsur,2,1)%status=‘N’. See slides of extended
course.
usrdef 2dobc data

SUBROUTINE usrdef_2dobc_data(ifil,ciodatetime,data2d,nodat,novars)
INTEGER, INTENT(IN) :: ifil, nodat, novars
REAL, INTENT(INOUT), DIMENSION(nodat,novars) :: data2d
• Define 2-D open boundary data if modfiles(io 2uvobc,ifil,1)%status=‘N’.
• nodat equals no2dobc(ifil)
• novars equals 2 if iobc2dtype(ifil)=1, 1 otherwise.
ciodatetime date/time in string format
data2d open boundary data, the second index refers to the type of data
1: depth-integrated currents if iobc2dtype(ifil)=1 or 3, elevations if iobc2dtype(ifil)=2
2: elevations if iobc2dtype(ifil)=1
& %
' $
usrdef profobc data

SUBROUTINE usrdef_profobc_data(iddesc,ifil,ciodatetime,psiprofdat,numprofs)
INTEGER, INTENT(IN) :: iddesc, ifil, numprofs
REAL, INTENT(INOUT), DIMENSION(numprofs,nz) :: psiprofdat
• Define 3-D open boundary profile data if modfiles(iddesc,ifil,1)%status=‘N’.
• iddesc equals either io 3uvobc, io salobc, io tmpobc (or io bioobc)
• numprofs equals noprofsd(ifil)

psiprofdat profile data
usrdef rlxobc spec

Define specifiers for open boundary relaxation are if modfiles(io rlxobc,1,1)%status=‘N’. See User
Documentation.
& %
' $
File Usrdef Surface Data.f90

Contains the following subroutines
usrdef surface absgrd: defines the data grid in “absolute” (geographical) coordinates
usrdef surface relgrd : defines the grid in “relative” coordinates (model grid with respect to data grid or
data grid with respect to model grid)
usrdef surface data : defines surface data
& %
' $
usrdef surface absgrd

SUBROUTINE usrdef_surface_absgrd(iddesc,ifil,n1dat,n2dat,xcoord,ycoord)
INTEGER, INTENT(IN) :: iddesc, ifil, n1dat, n2dat
REAL, INTENT(INOUT), DIMENSION(n1dat,n2dat) :: xcoord, ycoord
• Defines the X- and Y-coordinates of the surface data grid (Cartesian or spherical).
• iddesc is the descriptor of the grid file (io metgrd or io sstgrd).
• The routine is called if modfiles(iddesc,ifil,1)%status=‘N’ and surfacegrids(idgrd,ifil)%nhtype=2 where
iddesc is the file descriptor id and idgrd the corresponding grid id (igrd meteo or igrd sst). The file
number ifil is currently 1.
• n1dat and n2dat are the grid dimensions as given by surfacegrids(idgrd,ifil)%n1dat and
surfacegrids(idgrd,ifil)%n2dat.
• The data grid must be rectangular.
xcoord(n1dat,n2dat) X-coordinate (m or degrees longitude if iopt grid sph = 0 or 1)
ycoord(n1dat,n2dat) Y-coordinate (m or degrees latitude if iopt grid sph = 0 or 1)
usrdef surface relgrd

SUBROUTINE usrdef_surface_relgrd(iddesc,ifil,surfgridglb,nx,ny,nonodes)
INTEGER, INTENT(IN) :: iddesc, ifil, nonodes, nx, ny
TYPE (HRelativeCoords), INTENT(INOUT), DIMENSION(nx,ny,nonodes) :: surfgridglb
& %
' $
usrdef surface data

SUBROUTINE usrdef_surface_data(iddesc,ifil,ciodatetime,surdata,n1dat,n2dat,novars)
INTEGER, INTENT(IN) :: iddesc, ifil, novars, n1dat, n2dat
REAL, INTENT(INOUT), DIMENSION(n1dat,n2dat,novars) :: surdata
• iddesc is the file descriptor (io metsur or io sstsur)
• The file number ifil is currently 1.
• The routine is called if modfiles(iddesc,ifil,1)%status=‘N’
• novars is the number of data variables. For SST this is 1, for meteo data the number depends on
the values of iopt meteo stres, iopt meteo heat and iopt meteo salflx.
• n1dat and n2dat are the grid dimensions as given by surfacegrids(idgrd,ifil)%n1dat and
surfacegrids(idgrd,ifil)%n2dat where idgrd is the id of the corresponding surface grid.

surdata surface forcing data (non-interpolated values on the data grid)
& %
' $
File Usrdef Nested Grids.f90

Contains the following subroutines
usrdef nstgrd spec: defines specifier arrays
usrdef nstgrd abs : defines the locations of the open boundary points for the nested sub-grids in
absolute coordinates
usrdef nstgrd rel : defines the locations of the open boundary points for the nested sub-grids in relative
coordinates
& %
' $
usrdef nstgrd spec

• This routine is called if modfiles(io nstspc,1,1)%status=‘N’.
• The aim is to interpolate data from the main grid to open boundary locations on the sub-grids.
Three types of locations can be distinguished: C-, U-, V-node locations.
The following arrays are defined here
INTEGER, DIMENSION(nonestsets) :: nestcoords, nohnstglbc, nohnstglbu, &
& nohnstglbv, novnst, inst2dtype
nonestsets number of nested sub-grids as defined in usrdef mod params
nestcoords Type of coordinates used to define open boundary locations of the sub-grids
1: absolute coordinates
2: relative coordinates
nohnstglbc number of C-node sub-grid points
nohnstglbu number of U-node sub-grid points
nohnstglbv number of V-node sub-grid points
novnst vertical dimension of the sub-grid
inst2dtype selects type of data for 2-D nesting
1: transport and elevations
2: elevations
& %
3: transport
' $
usrdef nstgrd abs

SUBROUTINE usrdef_nstgrd_abs(iset,nhdat,nzdat,xcoord,ycoord,zcoord,cnode)
CHARACTER (LEN=1), INTENT(IN) :: cnode
INTEGER, INTENT(IN) :: iset, nhdat, nzdat
REAL, INTENT(OUT), DIMENSION(nhdat) :: xcoord, ycoord
REAL, INTENT(OUT), DIMENSION(nhdat,nzdat) :: zcoord
• This routine is called if modfiles(io nstgrd,iset,1)%status=‘N’ and nestcoords(iset)=1.
• Defines the locations of the sub-grid locations in absolute coordinates.
cnode node of the sub-grid locations (‘C’, ‘U’, ‘V’)
iset nest grid index
nhdat number of sub-grid locations (e.g. nohnstglbc(iset) if cnode=‘C’)
nzdat vertical dimension (given by novnst(iset))
xcoord X-coordinates (meters or longitude) of the sub-grid locations
ycoord Y-coordinates (meters or latitude) of the sub-grid locations
zcoord Z-coordinates of the sub-grid locations (only when nzdat>0)
& %
' $
usrdef nstgrd rel

SUBROUTINE usrdef_nstgrd_rel(iset,nhdat,nzdat,nonodes,hnests,zcoord,cnode)
CHARACTER (LEN=1), INTENT(IN) :: cnode
INTEGER, INTENT(IN) :: iset, nhdat, nonodes, nzdat
REAL, INTENT(OUT), DIMENSION(nhdat,nzdat) :: zcoord
TYPE (HRelativeCoords), INTENT(OUT), DIMENSION(nhdat,nonodes) :: hnests
• This routine is called if modfiles(io nstgrd,iset,1)%status=‘N’ and nestcoords(iset)=2.
• Defines the locations of the sub-grid locations in relative coordinates.
cnode node of the sub-grid locations (‘C’, ‘U’, ‘V’)
iset nest grid index
nhdat number of sub-grid locations (e.g. nohnstglbc(iset) if cnode=’C’)
nzdat vertical dimension (given by novnst(iset))
hnests relative coordinates of the sub-grid (‘C’, ‘U’, ‘V’) locations with respect to either the C-, U- or
V-node model grid
zcoord Z-coordinates of the sub-grid locations (only when nzdat>0).
& %
' $
nonodes number of nodes (1 or 2) which depends on the value of cnode

‘C’: One series of coordinates needs to be given (nonodes=1), representing interpolation of
‘C’-node grid points on the model grid to ’C’-subgrid locations.
‘U’: Two series of coordinates need to be given (nonodes=2), the first representing
interpolation of ‘U’-node grid points on the model grid to ‘U’-subgrid locations, the second
interpolation of ’C’-node grid points on the model grid to ‘U’-subgrid locations.
‘V’: Two series of coordinates need to be given (nonodes=2), the first representing
interpolation of ‘V’-node grid points on the model grid to ‘V’-subgrid locations, the second
interpolation of ‘C’-node grid points on the model grid to ’V’-subgrid locations.
& %
' $
File Usrdef Time Series.f90

Define time series output:
• general parameters nosetstsr, novarstsr, nostatstsr
• select the variables used for output and define their attributes
• set the attributes of the output file(s)
• define the output grid(s) and related parameters
• define the output values
There are two types of variables:
• “standard” variables which are known to the program. In that case the user only needs to make a
limited number of definitions. Metadata and output values are automatically provided by the
program.
• user-defined variables: the user must provide all information and the output data. This will not
further discussed here. For details see the User Manual.
& %
' $
The file Usrdef Time Series.f90 contains the following subroutines:

usrdef tsr params: specifiers for time series output. The routine is not called in case input is made via a
CIF.
usrdef tsr0d vals : 0-D (space-independent) output data
usrdef tsr2d vals : 2-D (horizontally dependent) output data
usrdef tsr3d vals : 3-D output data
The last three routines are only used for user-defined variables only.
& %
' $
usrdef tsr params

The following derived type arrays need (or may) be defined here:
TYPE (VariableAtts), DIMENSION(novarstsr) :: tsrvars
INTEGER, DIMENSION(nosetstsr,novarstsr) :: ivarstsr
TYPE (FileParams), DIMENSION(nosetstsr) :: tsr0d, tsr2d, tsr3d
TYPE (OutGridParams), DIMENSION(nosetstsr) :: tsrgpars
INTEGER, DIMENSION(nosetstsr,nostatstsr) :: lstatstsr
TYPE (StationLocs), DIMENSION(nostatstsr) :: tsrstatlocs
nosetstsr number of output “sets” as defined in usrdef mod params
novarstsr total number of output variables as defined in usrdef mod params
nostatstsr total number of stations as defined in usrdef mod params
tsrvars attributes of the output variables
ivarstsr variable indices
tsr0d attributes of 0-D files
tsrgpars attributes of output data grid
lstatstsr stations labels
tsrstatlocs station attributes
& %
' $
definition of variables
TYPE :: VariableAtts
INTEGER :: ivarid, klev, nrank, oopt
REAL :: dep
END TYPE VariableAtts
TYPE (VariableAtts), DIMENSION(novarstsr) :: tsrvars
INTEGER, DIMENSION(nosetstsr,novarstsr) :: ivarstsr
ivarid Variable key id of the output variable (as defined in modids.f90). The syntax is iarr * where * is
the variables’s FORTRAN name (e.g. iarr temp). Variables need to be defined in the following
order: 0-D (if any), 2-D (if any), 3-D (if any). A zero means that the variable is user-defined.
nrank variable rank (0,2 or 3)
oopt (optional) operator applied to the variable. Following values are allowed
oopt null no operator is applied (default)
oopt min minimum value over whole domain
oopt max maximum value over whole domain
oopt mean domain average
oopt klev value at the vertical grid level given by the klev attribute
oopt dep value at a depth given by by the dep attribute
klev vertical grid level applied when oopt=oopt klev
& %
' $
dep depth (distance from the surface) applied when oopt=oopt dep. Output value is obtained by
vertical interpolation
ivarstsr Each file set contains a sub-set of the variables defined in tsrvars. The element ivarstsr(iset,ivar)
maps, for set iset, the local variable ivar into the corresponding array index in tsrvars. The
variables must be defined in the following order: first 0-D (if any), next 2-D (if any) and finally
the 3-D variables (if any).
& %
' $
file attributes
TYPE :: FileParams
LOGICAL :: defined, info
CHARACTER (LEN=1) :: form
CHARACTER (LEN=leniofile) :: filename
INTEGER :: header type
END TYPE FileParams
TYPE (FileParams), DIMENSION(nosetstsr) :: tsr0d, tsr2d, tsr3d
The following file attributes can be defined:
defined Output file will be written (only) if this parameter is set to .TRUE. Default is .FALSE.
form Output format
‘A’: ASCII
‘U’: unformatted binary
‘N’: netCDF
filename File name. If not defined, a default will be constructed by the program.
info An “info” file (ending with ‘I’) will be created if .TRUE. (default value).
header type No heading information will be written if set to 0. Default is 2. This option is not available
for netCDF output.
& %
' $
output data grid
TYPE :: OutGridParams
LOGICAL :: gridded, grid file, land mask, time grid
CHARACTER (LEN=1) :: status
CHARACTER (LEN=lentime) :: enddate, refdate, startdate
INTEGER :: nodim, nostats, time format
INTEGER, DIMENSION(3) :: tlims, xlims, ylims, zlims
END TYPE OutGridParams
TYPE (OutGridParams), DIMENSION(nosetstsr) :: tsrgpars
gridded If .TRUE. (default), output data are defined on a sub-grid of the model grid (or the whole
model grid). If .FALSE., the data are taken at a series of locations (“station” data) defined
below.
grid file If .TRUE., output grid data will be written on a separate output file (defined by tsrgrd).
Otherwise, they are written within the data file itself (default).
land mask A land mask will be applied if .TRUE. and gridded=.TRUE.. This means that the gridded
data will be stored as a vector excluding land points. Advantage may be a significant
reduction in disk space. Default is .FALSE..
time grid If .TRUE., the data grid is time-dependent (vertical positions in a σ- or s-grid are
time-dependent). Surface elevations will be written at each time step. Default if .FALSE..
& %
' $
time format Format of time coordinate (0)

0: date/time in string fromat
1: seconds
2: minutes
3: hours
4: days
5: months
6: years
7: date in years
tlims Start/end/step time indices for data output.
nodim Dimension of the data (0/2/3).
nostats Number of data stations in case of gridded data.
xlims Start/end/step X-index in case of gridded data. This defines the output sub-grid in the
X-direction. (Option not available for 0-D output).
ylims Start/end/step Y-index in case of gridded data. This defines the output sub-grid in the
Y-direction. (Option not available for 0-D output).
zlims Start/end/step Z-index in case of gridded data. This defines the output sub-grid in the
Z-direction. (Option only available for 3-D output).
& %
' $
station attributes
TYPE :: StationLocs
INTEGER :: ipos, jpos
CHARACTER (LEN=lenname) :: name
END TYPE StationLocs
TYPE (StationLocs), DIMENSION(nostatstsr) :: tsrstatlocs
INTEGER, DIMENSION(nosetstsr,nostatstsr) :: lstatstsr
ipos X-index on (global) model grid of output stations
jpos Y-index on (global) model grid of output stations
name descriptive names of the stations
lstatstsr Station labels. Each file set may contain a sub-set of stations. The element lstatstsr(iset,istat)
maps, for set iset, the local station index istat into the corresponding global array index in
tsrstatlocs.
& %
' $
File Usrdef Time Averages.f90

• Used to define time-averaged output
• Procedures are highly similar as for time series output
The file Usrdef Time Averages.f90 contains the following subroutines:
usrdef avr params: specifiers for time averaged output. The routine is not called in case input is made
via a CIF.
usrdef avr0d vals : 0-D (space-independent) output data
usrdef avr2d vals : 2-D (horizontally dependent) output data
usrdef avr3d vals : 3-D output data
The last three routines are only used for user-defined variables only.
& %
' $
usrdef avr params

The following derived type arrays need (or may) be defined here:
TYPE (VariableAtts), DIMENSION(novarsavr) :: avrvars
INTEGER, DIMENSION(nosetsavr,novarsavr) :: ivarsavr
TYPE (FileParams), DIMENSION(nosetsavr) :: avr0d, avr2d, avr3d
TYPE (OutGridParams), DIMENSION(nosetsavr) :: avrgpars
INTEGER, DIMENSION(nosetsavr,nostatsavr) :: lstatsavr
TYPE (StationLocs), DIMENSION(nostatsavr) :: avrstatlocs
Their general meaning is
nosetsavr number of output “sets” as defined in usrdef mod params
novarsavr total number of output variables as defined in usrdef mod params
nostatsavr total number of stations as defined in usrdef mod params
avrvars attributes of the output variables
ivarsavr variable indices
avr0d attributes of 0-D files
& %
' $
avrgpars attributes of output data grid

lstatsavr stations labels
avrstatlocs station attributes
• avrvars, ivarsavr have the same meaning as tsrvars, ivarstsr for time series output
• avr0d, avr2d, avr3d have the same meaning as tsr0d, tsr2d, tsr3d for time series output
• avrgpars has the same meaning as tsrgpars for time series output except that avrgpars(:)%tlims(3)
now represents the period (measured in time indices) for time-averaging
• lstatsavr, avrstatlocs have the same meaning as lstatstsr, tsrstatlocs for time series output
& %
' $
File Usrdef Harmonic Analysis.f90

Defines setup parameters and data for harmonic analysis and contains the following subroutines
usrdef anal freqs : define harmonic frequencies
usrdef anal params: specifiers for harmonic analysis and output
usrdef anal0d vals : 0-D (space-independent) output data
usrdef anal2d vals : 2-D (horizontally dependent) output data
usrdef anal3d vals : 3-D output data
• The first routines are redundant if setup is made through a CIF
• The last three routines are only used in case of user-defined variables. Explanations are given in the
User Documentation.
File Usrdef Output.f90
This routine, called at each 2-D time step, is completely user dependent.
& %
' $
Final remarks
• The user must insert the proper USE statements in the usrdef-routines.
• To open or close a file, do not use the standard OPEN and CLOSE statements. There are two
alternatives:
1. Use open filepars to open and close filepars to close files. The first argument of these routines is a
derived type variable of TYPE FileParams. Besides opening and closing the routines set or reset
a number of file attributes.
2. Use open file and close file. The routines are similar to the classical OPEN and CLOSE and are
defined in inout routines.f90.
• A special procedure need to be followed within a usrdef routine which reads time series data (i.e.
the routines which have ciodatetime as argument.
1. On first call, the file is opened and the %iostat number is reset from 0 to 1. No data are read.
2. A second call is made, immediately after the first one (i.e. at the same model time step) to read
the date/time and first series of data. This is repeated until the date/time of the last input is
later than the actual model time.
3. When during program execution, the model date equals or becomes later than the one obtained
from last read, the usrdef-routine is called again, until the date/time in the file becomes later
than the actual model time.
4. If an end of file condition occurs or the user knows that this will occur on a next read, the user
must set the iostat number to 2. The program will no longer call the routine. Further action
(decided by the program) now depends on the value of the endfile parameter.
& %

COHERENS V2 User Manual: Patrick Luyten

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

COHERENS V2 User Manual: Patrick Luyten

Uploaded by

Copyright:

Available Formats

MUMM - BMM - UGMM [1]

COHERENS V2 user manual

Royal Belgian Institute of the Natural Sciences

COHERENS training course

Setup files for user application

File defruns V2.1.2

File Usrdef Model.f90

usrdef init params

INTEGER :: levprocs err(npworld) Level for error checking (0).

usrdef mod params

Process numbers for parallel processing

Model switches (84)

iopt grid sph Type of coordinates (0).

iopt temp Temperature update (0).

bottom boundary conditions

iopt bstres form Type of formulation for bottom stress (2).

iopt fld Disables/enables (0/1) drying/wetting scheme (0).

open boundary conditions

iopt meteo Disables/enables (0/1) meteorological input (0).

surface boundary conditions

iopt nests Disables/enables (0/1) output for nested sub-grids (0).

iopt out tsers Disables/enables (0/1) time series output (1).

A * means that a parameter must always be defined (no default available).

Date and time parameters

See User Documentation.

Parameters for surface data grids

igrd model model grid

Parameters for input and output forcing

io mppmod parallel decomposition (ifil=1)

file parameters for input forcing (iotype=1)

status Status of the data file.

file parameters for output forcing (iotype=2)

status Status of the data file.

nc1procs(nprocs) global X-index of lower left cell of process domains

vvel(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) current in Y-direction [m/s]

bottom stress arrays

tidal and open boundary arrays

usrdef 1dsur spec

gxslope amp(nconobc) amplitudes of X-component of pressure gradient [m2 /s]

usrdef 2dobc spec

(5) 15 (5) 16 (5) 17 (5) 18

(2) 7 • first number in () is file number

(4) 12 (4) 13 (4) 14

nobu = 11, nobv = 8

nofiles = 6; no2dobc = (/8,3,3,4,1/)

usrdef profobc spec

• Define specifiers for 3-D open boundary forcing if modfiles(iddesc,1,1)%status=‘N’.

itypobu(nobu) type of open boundary condition at U-nodes

profiles at open boundaries

(4) 4 (4) 4 (4) 4 (4) 4

(2) 1 0 ifil=2: data for profile numbers 1 and 2

nobu = 11; nobv = 8

usrdef 1dsur data

usrdef 2dobc data

usrdef profobc data

ciodatetime date/time in string format

usrdef rlxobc spec

File Usrdef Surface Data.f90

usrdef surface absgrd

usrdef surface relgrd

usrdef surface data

ciodatetime date/time in string format

File Usrdef Nested Grids.f90