nesting

Nesting compilation requirements

There is no need for re-compiling the code to enable nesting. However, you need to edit the namelist file to indicate you want to run FVCOM with nesting at the boundaries.

Nested output

To generate boundary forcing for a subdomain with FVCOM (i.e. how nesting should be used), set NC_NEST to T in the NML_NCNEST section the model name list.

The format of the NML_NCNEST section is:

&NML_NCNEST
 NCNEST_ON         = T,
 NCNEST_BLOCKSIZE  = 5,
 NCNEST_NODE_FILES = 'irish_sea_v20_nodenest.dat',
 NCNEST_OUT_INTERVAL = 'seconds = 900.0'
/

NCNEST_BLOCKSIZE controls the number of model time steps stored in memory and written to disk at once to improve performance.

The format of the NCNEST_NODE_FILES file you specify is as follows:

Node_Nest Number = 25
1 27992 1
2 28735 1
3 27991 1
4 28734 1
5 28733 1
6 29324 1
7 28732 1
8 28731 1
9 28787 1
10 28730 1
11 27986 1
12 28729 1
13 29318 1
14 29317 1
15 29853 1
16 29852 1
17 29850 1
18 29851 1
19 29314 1
20 29313 1
21 29849 1
22 29312 1
23 29848 1
24 29847 1
25 30350 1

where the first column is the node count (1, 2, 3, 4, etc.), the second is the grid node number and the third is 1. All values should be integers and refer to the grid nodes (not the elements).

The nodes in the NCNEST_NODE_FILES should be those which describe the elements along the nested boundary. So, the nodes must describe a set of elements from which the velocity data can also be extracted. Essentially, the nodes in the nest must be two rows deep (each side of a line of elements - see figure below).

The manual contains more information on the configuration (see section describing format for Casename_node_nest.dat). More information on this can probably be gleaned from mod_nesting.F, particularly around line 650 in subroutine SETUP_NEST_DOMAIN.

Weighted nesting (type 3)

I will put information here about creating FVCOM nesting files with weights. The examples comes from coupling POLCOMS MED (GCOMS Mediterranean domain) with the Nadoor domain. The functions to do this are included in the MATLAB fvcom-toolbox.

The nesting with a relaxation method (an example is to get nesting data from HYCOM/POLCOMS/NEMO) we need specific variables interpolated to the nested domain.

Requirements (i.e. outside toolboxes)

http://www.mathworks.com/matlabcentral/fileexchange/24827-hamilton-jacobi-solver-on-unstructured-triangular-grids/content/HJB_Solver_Package/@SolveEikonalmex/SolveEikonalmex.m.
Tidal package (if POLCOMS is run without tidal forcing as is the case for the MED). For Nadoor we have used https://gitlab.ecosystem-modelling.pml.ac.uk/fvcom/TMD.

POLCOMS file requirements

For the POLCOMS data we need UV from U nodes and T and S and zet from B nodes

fileU = '/data/perseus1/to_archive/suka_VECTORS/MEDI29_RA/daily/UVT/dmeanUVT.MEDI29.RA.2000.01.U.nc'
fileB = '/data/perseus1/to_archive/suka_VECTORS/MEDI29_RA/daily/UVT/dmeanUVT.MEDI29.RA.2000.01.B.nc'

we also need

ipexfile = '/users/modellers/rito/Models/MEDINA/polcoms/zet_UBVB.MEDI29.RA.2009.12'
fileparams = '/users/modellers/rito/Models/MEDINA/polcoms/MEDI29.parameters'
filebathy = '/users/modellers/rito/Models/MEDINA/polcoms/MEDI29.bathy'
filescoord = '/users/modellers/rito/Models/MEDINA/polcoms/scoord_params.dat'
ts_controlfile = '/users/modellers/rito/Models/MEDINA/tseries.MEDI29'
tseries_dir = '/users/modellers/rito/Models/MEDINA/polcoms/timeseries'; % all physseries, biolseries and zet_UBVB files should be in there

The above list allows the MATLAB scripts to read the details about the POLCOMS model configuration and details of the data timeseries provided. The ipexu array is extracted directly from one of the netCDF files from POLCOMS.

netCDF information

All grid related variables complying with size of data variables (below) in nesting netCDF file. These variables are the same as in any output netCDF file generated that includes grid information. The grid is read first using subroutine LOAD_GRID_TYPE(NCF,G) in mod_input.F.

Nominally it requires the following dimensions:

nele = nelements in relaxation zone ;
node = nnodes in relaxation zone ;
siglay = need to match model setup parameters ;
siglev = need to match model setup parameters ;
three = 3 ;

and nested grid variables are:

float x(node) ;
    x:long_name = "nodal x-coordinate" ;
    x:units = "meters" ;
float y(node) ;
    y:long_name = "nodal y-coordinate" ;
    y:units = "meters" ;
float lon(node) ;
    lon:long_name = "nodal longitude" ;
    lon:standard_name = "longitude" ;
    lon:units = "degrees_east" ;
float lat(node) ;
    lat:long_name = "nodal latitude" ;
    lat:standard_name = "latitude" ;
    lat:units = "degrees_north" ;
float xc(nele) ;
    xc:long_name = "zonal x-coordinate" ;
    xc:units = "meters" ;
float yc(nele) ;
    yc:long_name = "zonal y-coordinate" ;
    yc:units = "meters" ;
float lonc(nele) ;
    lonc:long_name = "zonal longitude" ;
    lonc:standard_name = "longitude" ;
    lonc:units = "degrees_east" ;
float latc(nele) ;
    latc:long_name = "zonal latitude" ;
    latc:standard_name = "latitude" ;
    latc:units = "degrees_north" ;
int nv(three, nele) ;
    nv:long_name = "nodes surrounding element" ;

The interpolated variables from the structured grid model (forcing, weighting etc.) are given below:

Unweighted (DIRECT/INDIRECT) nesting (types 1 and 2)

This section describes how to 'fake' nesting using existing FVCOM model output (without using the NML_NCNEST section of the FVCOM namelist.

For the unweighted (i.e. direct and indirect nesting, referred to as type 1 and 2 in the FVCOM namelists) nesting, the situation is similar to the type 3 (relaxation nesting) except no weight_cell or weight_node arrays are required for the nesting netCDF file.

Using existing FVCOM ouptput

I (Pierre) wrote a Python script to generate a new model grid nest region which is based on a nested grid region (defined as a nodestring from an SMS grid) and a coarse model domain. The script searches for and extracts node and element positions and writes a new section of grid to append to the nested region in SMS. This means an arbitrary nested region can be created from an existing model output. As such, the NML_NCNEST section of the FVCOM namelist need not have been enabled in order to use the coarse model output.

There's a MATLAB script which will take a coarse model output and the new nested grid (complete with nested buffer which shares its nodes with the coarse grid) and extract the required variables for running a nested domain.

The MATLAB fvcom-toolbox routine to write out the netCDF output once the data have been loaded is write_FVCOM_nested_forcing.m.

Currently, I don't know what to use for the hydrostatic vertical velocity, so the values are zero. This may well break things!

netCDF information

Required dimensions are:

nele = nelements in relaxation zone ;
node = nnodes in relaxation zone ;
siglay = need to match model setup parameters ;
siglev = need to match model setup parameters ;
three = 3 ;

and standard variables are:

float x(node) ;
    x:long_name = "nodal x-coordinate" ;
    x:units = "meters" ;
float y(node) ;
    y:long_name = "nodal y-coordinate" ;
    y:units = "meters" ;
float lon(node) ;
    lon:long_name = "nodal longitude" ;
    lon:standard_name = "longitude" ;
    lon:units = "degrees_east" ;
float lat(node) ;
    lat:long_name = "nodal latitude" ;
    lat:standard_name = "latitude" ;
    lat:units = "degrees_north" ;
float xc(nele) ;
    xc:long_name = "zonal x-coordinate" ;
    xc:units = "meters" ;
float yc(nele) ;
    yc:long_name = "zonal y-coordinate" ;
    yc:units = "meters" ;
float lonc(nele) ;
    lonc:long_name = "zonal longitude" ;
    lonc:standard_name = "longitude" ;
    lonc:units = "degrees_east" ;
float latc(nele) ;
    latc:long_name = "zonal latitude" ;
    latc:standard_name = "latitude" ;
    latc:units = "degrees_north" ;
int nv(three, nele) ;
    nv:long_name = "nodes surrounding element" ;

The time series variables extracted from the coarse output are shown below:

For questions regarding FVCOM, to contribute to the wiki please subscribe to the mailing list uk-fvcom mailing list If you would like to cite FVCOM, please refer to its main publication and/or URLs.