Input Datasets for SURF¶
To execute the SURFNEMO package, several input datasets are required. These include bathymetry datasets, which provide seafloor elevation; coastline datasets, which define the borders between land and sea; the initial condition dataset, containing initial values for model prognostic variables; and the boundary condition datasets, which contain variables necessary to impose boundary conditions for mass, momentum, and energy flows at the surface and lateral open boundaries of the domain.
Figure 6.1 illustrates the interfaces and external forcings acting on a typical computational domain.
Input Datasets¶
The input datasets for the model are provided in the classic NetCDF format for bathymetry, initial conditions, and lateral boundary conditions. NetCDF is a widely used file format in atmospheric and oceanic research which allows storage of different types of array based data, along with a short data description. The coastline datasets are instead provided in Shapefile format, a digital vector data format for geographic information system (GIS) software.
SURF allows also to use, if needed, two different model type of input data during the execution: analysis data for the spinup period and forecast data afterward. Users can configure these parameters in the setParFree.json
file, specifying path, filename, dimensions, variables, and other data characteristics.
Bathymetry Dataset¶
The bathymetry dataset contains the sea floor elevation and is required for generating the child meshmask file. Users need to configure the necessary parameters in the set_dataDownlBat
section of the configuration file. The data are distributed on a curvilinear spherical grid (which may be regular or irregular) over a region containing the nested domain.
The bathymetry file contains an elevation variable (in meters) with a specific horizontal resolution. Elevation values are relative to a reference level and can either increase (positive values) or decrease (negative values) with increasing water depth. The coordinate variables (latitude and longitude) can be structured as one or twodimensional arrays.
An example CDL (Common Data Language) representation of a bathymetry file is shown in Listing 6.1.1.
netcdf bathymetry_filename {
dimensions:
x = 300;
y = 200;
variables: \\
float lon(y,x);
lon: units = "degrees_east";
float lat(y,x);
lat: units = "degrees_north";
float elevation(y,x);
elevation: units = "m";
}
Users must specify the following logical parameters in the set_dataDownlBat_fileName
section of the user configuration file:

fileBat_lcompression
: Indicates whether the file is compressed (.gzip) or not. 
fileBat_llonFlip
: Specifies if the longitude coordinate is defined in the range [0:360] or [180:+180]. 
fileBat_llatInv
: Indicates whether the dataset contains latitude values that decrease towards the poles. 
fileBat_ldepthIncr
: Defines if the dataset contains seafloor elevation (positive values) that increases with increasing water depth. 
fileBat_lkeepSrcFull
: Specifies whether the original downloaded file should be deleted after cropping it for the nested domain.
The available input bathymetry dataset included in the SURF package is the General Bathymetric Chart of the Oceans (GEBCO) 2014, a publicly accessible dataset that provides global bathymetric coverage with a resolution of 30 arcseconds. More information can be found on the official GEBCO website here.
Coastline Dataset¶
The coastline dataset defines the borders between land and sea areas and is stored in shapefile format. It is required for generating the child meshmask. Users must configure the necessary parameters in the set_dataDownlCoast
section of the configuration file.
The available coastline dataset within the SURF package is the Global Selfconsistent Hierarchical Highresolution Geography (GSHHG) dataset, produced by the National Oceanic and Atmospheric Administration (NOAA). This dataset includes 20 shapefiles, each containing hierarchically arranged polygons that define shorelines. More information about GSHHG can be found on their official website here.
The GSHHG data are provided at five different resolutions, each stored as a separate shapefile:
 f (full): highest resolution with a resolution of xx m
 h (high): high resolution with a resolution of xx m
 i (intermediate): intermediate resolution with a resolution of xx m
 l (low): low resolution with a resolution of xx m
 c (coarse): coarsest resolution with a resolution of xx m
Each resolution level contains shorelines organized into four hierarchical categories:
 L1: Boundary between land and ocean
 L2: Boundary between lake and land
 L3: Boundary between islands within lakes and the lakes
 L4: Boundary between ponds within islands and the islands
Initial Condition Datasets¶
To initiate a model run, the initial values for the model's prognostic variables must be provided. These include temperature, salinity, sea surface height, and the zonal and meridional velocity components. Initial condition datasets are typically derived from coarsegrid model outputs. Users must configure the necessary parameters in the set_dataDownlOceIC
section of the configuration file.
The data can be provided on a curvilinear spherical grid (which may be regular or irregular) using an unstaggered or staggered ArakawaC grid arrangement within a region that contains the nested domain. The model assumes that all input ocean variables are defined on the same grid.
The coarseresolution ocean files contain the following variables at a specified horizontal resolution:
 Potential Temperature [\(C\)]
 Salinity [\(PSU\)]
 Sea Surface Height [\(m\)]
 Zonal Velocity [\(ms^{1}\)]
 Meridional Velocity [\(ms^{1}\)]
An example CDL (Common Data Language) representation of an initial condition file is shown in Listing 6.1.2.
netcdf fields_filename {
dimensions:
x = 40 ;
y = 35 ;
z = 72 ;
time = UNLIMITED ; // (1 currently)
variables:
float lont(y, x) ;
lont:units = "degrees_east" ;
float latt(y, x) ;
latt:units = "degrees_north" ;
float deptht(z) ;
deptht:units = "m" ;
double time(time) ;
time_counter:units = "seconds since
19700101 00:00:00" ;
float temperature(time, z, y, x) ;
temperature:units = "degC" ;
}
To perform the extrapolation (SOL) of ocean fields (see Section 4.3 for more details), the parent landsea mask file must be provided as an input dataset. The user needs to configure the required parameters in the set_dataDownlOceICMesh
section of the configuration file.
This file contains information about the coarseresolution ocean model grids, including the following variables:
 Longitude on TUVF grid points [\(degree\)]
 Latitude on TUVF grid points [\(degree\)]
 Depth on TUVF grid points [\(m\)]
 Landsea mask on TUVF grid points [01]
 Scale factors on TUVF grid points [\(m\)]
An example CDL text representation of this file is shown in Listing 6.1.3.
netcdf meshmask_filename {
dimensions :
x = 677;
y = 253;
z = 72;
t = UNLIMITED; // (7 currently)
variables : \\
float lon(y,x);
float lat(y,x);
float lev(z);
double time(t);
byte tmask(t,z,y,x);
byte umask(t,z,y,x);
byte vmask(t,z,y,x);
byte fmask(t,z,y,x);
float glamt(t,y,x);
float glamu(t,y,x);
float glamv(t,y,x);
float glamf(t,y,x);
float gphit(t,y,x);
float gphiu(t,y,x);
float gphiv(t,y,x);
float gphif(t,y,x);
double e1t(t,y,x);
double e1u(t,y,x);
double e1v(t,y,x);
double e1f(t,y,x);
double e2t(t,y,x);
double e2u(t,y,x);
double e2v(t,y,x);
double e2f(t,y,x);
double e3t(t,z,y,x);
double e3u(t,z,y,x);
double e3v(t,z,y,x);
double e3w(t,z,y,x);
}
Lateral Open Boundary Condition Datasets¶
In order to integrate the primitive equations, the NEMO ocean model needs to impose appropriate boundary conditions at the oceanocean interface (i.e., the sides of the domain not bounded by land). Lateral open boundary values for the model's prognostic variables must be specified for the entire simulation period. These include fields such as temperature, salinity, sea surface height, and velocity.
Users must configure the necessary parameters in the set_dataDownlOceBC_preSpinup
and set_dataDownlOceBC_postSpinup
sections of the configuration file. The data can be distributed on a curvilinear spherical grid (regular or irregular) with an unstaggered or staggered ArakawaC grid arrangement covering the nested domain. The model assumes that all input ocean variables during the pre and postspinup periods are defined on the same grid.
The coarseresolution ocean files contain the following variables at a given horizontal resolution and temporal frequency:
 Potential Temperature [\(C\)]
 Salinity [\(PSU\)]
 Sea Surface Height [\(m\)]
 Zonal Velocity [\(ms^{1}\)]
 Meridional Velocity [\(ms^{1}\)]
An example CDL (Common Data Language) representation of this file is shown in Listing 6.1.4.
netcdf fields_filename {
dimensions :
x = 677;
y = 253;
z = 72;
t = UNLIMITED; // (7 currently)
variables : \\
float lont(x);
lont: units = "degrees_east";
float latt(y);
latt: units = "degrees_north";
float deptht(z);
deptht: units = "m";
double time(t);
time: units = "seconds since
19700101 00:00:00";
float temperature(t,z,y,x);
temperature: units = "degC";
}
To perform the extrapolation (SOL) of ocean fields (see Section 4.3 for more details), the parent landsea mask file must be provided as an input dataset. Users must configure the necessary parameters in the set_dataDownlOceBCMesh
section of the configuration file.
This file contains the necessary information about the coarseresolution ocean model grids and includes the following variables:
 Longitude on TUVF grid points [\(degree\)]
 Latitude on TUVF grid points [\(degree\)]
 Depth on TUVF grid points [\(m\)]
 Landsea mask on TUVF grid points [01]
 Scale factor on TUVF grid points [\(m\)]
An example CDL text representation of this file is shown in Listing 6.1.5.
netcdf meshmask_filename {
dimensions :
x = 677;
y = 253;
z = 72;
t = UNLIMITED; // (7 currently)
variables : \\
float lon(y,x);
float lat(y,x);
float lev(z);
double time(t);
byte tmask(t,z,y,x);
byte umask(t,z,y,x);
byte vmask(t,z,y,x);
byte fmask(t,z,y,x);
float glamt(t,y,x);
float glamu(t,y,x);
float glamv(t,y,x);
float glamf(t,y,x);
float gphit(t,y,x);
float gphiu(t,y,x);
float gphiv(t,y,x);
float gphif(t,y,x);
double e1t(t,y,x);
double e1u(t,y,x);
double e1v(t,y,x);
double e1f(t,y,x);
double e2t(t,y,x);
double e2u(t,y,x);
double e2v(t,y,x);
double e2f(t,y,x);
double e3t(t,z,y,x);
double e3u(t,z,y,x);
double e3v(t,z,y,x);
double e3w(t,z,y,x);
}
Tidal Datasets for the open boundaries¶
For barotropic solutions, there is an option to include tidal harmonic forcing at the open boundaries in addition to other external data. These tidal datasets include the harmonic constituents for amplitude and phase of surface height and velocity. Users must configure the required parameters in the set_dataDownlTide
section of the configuration file.
The tidal data are distributed on a regular curvilinear spherical grid with either unstaggered or staggered ArakawaC grid arrangements covering the nested domain. The model assumes that all input tidal harmonic variables are defined on the same grid.
The barotropic tide files contain the following variables for each harmonic constituent at a given horizontal resolution:
 Tidal elevation complex amplitude (Real and Imaginary parts) [\(mm\)]
 Tidal WE transport complex amplitude (Real and Imaginary parts) [\(cm^2/s\)]
 Tidal SN transport complex amplitude (Real and Imaginary parts) [\(cm^2/s\)]
An example CDL text representation of this file is shown in Listing 6.1.6.
netcdf uv.k1_tpxo8_atlas_30c_v1 {
dimensions:
nx = 10800 ;
ny = 5401 ;
variables:
double lon_u(nx) ;
lon_u:units = "degree_east" ;
double lat_u(ny) ;
lat_u:units = "degree_north" ;
double lon_v(nx) ;
lon_v:units = "degree_east" ;
double lat_v(ny) ;
lat_v:units = "degree_north" ;
int uRe(nx, ny) ;
uRe:units = "centimeter^2/sec" ;
int uIm(nx, ny) ;
uIm:units = "centimeter^2/sec" ;
int vRe(nx, ny) ;
vRe:units = "centimeter^2/sec" ;
int vIm(nx, ny) ;
vIm:units = "centimeter^2/sec" ;
}
A tidal model bathymetry file also needs to be provided as part of the input dataset. Users must configure the required parameters in the set_dataDownlTideMesh
section of the configuration file.
This file contains information about the tidal model grids and depth, including the following variables:
 Longitude on TUV grid points [\(degree\)]
 Latitude on TUV grid points [\(degree\)]
 Bathymetry at TUV grid points [\(m\)]
An example CDL text representation of this file is shown in Listing 6.1.7.
netcdf grid_tpxo8atlas_30_v1 {
dimensions:
nx = 10800 ;
ny = 5401 ;
variables:
double lon_z(nx) ;
lon_z:units = "degree_east" ;
double lat_z(ny) ;
lat_z:units = "degree_north" ;
double lon_u(nx) ;
lon_u:units = "degree_east" ;
double lat_u(ny) ;
lat_u:units = "degree_north" ;
double lon_v(nx) ;
lon_v:units = "degree_east" ;
double lat_v(ny) ;
lat_v:units = "degree_north" ;
float hz(nx, ny) ;
hz:units = "meter" ;
float hu(nx, ny) ;
hu:units = "meter" ;
float hv(nx, ny) ;
hv:units = "meter" ;
}
The available input barotropic tide datasets included in the SURF package are derived from the Topex Poseidon CrossOver (TPXO8ATLAS) global inverse tide model, obtained using the OTIS (OSU Tidal Inversion Software) package implementing methods described in Egbert and Erofeeva,2002. For more information, visit the TPXO8ATLAS website.
The TPXO8 tidal model consists of a multiresolution bathymetric grid solution, with 1/6° resolution in the global open ocean and 1/30° resolution in shallowwater regions for improved modeling. The dataset includes complex amplitudes of tidal seasurface elevations and transports for eight primary (M2, S2, N2, K2, K1, O1, P1, Q1), two longperiod (Mf, Mm), and three nonlinear (M4, MS4, MN4) harmonic constituents.
Atmospheric Forcing Datasets¶
To integrate the primitive equations, the NEMO ocean model needs to impose appropriate boundary conditions for the exchange of mass, momentum, and energy at the atmosphereocean interface. The following six fields must be provided for the integration domain:
 Zonal components of surface ocean stress,
 Meridional components of surface ocean stress,
 Solar heat fluxes (Qsr),
 Nonsolar heat fluxes (Qns),
 Water flux exchanged with the atmosphere (EP), representing evaporation minus precipitation.
Additionally, an optional field can be provided:
 Atmospheric pressure at the ocean surface (pa).
The NEMO model offers different methods for providing these fields, controlled by namelist variables (refer to the NEMO Manual). In the SURF platform, the choice of atmospheric forcing is determined by setting the sbc_iformulat
parameter in the user configuration file:
sbc_iformulat=0
for the MFS bulk formulae,sbc_iformulat=1
for the Flux formulation,sbc_iformulat=2
for the CORE bulk formulae.
The atmospheric data are distributed on a regular unstaggered grid covering the nested domain. The model assumes that the input atmospheric variables for both the pre and postspinup periods are defined on the same mesh, though different meshes are allowed for different variables. The user must configure the required parameters in the set_dataDownlAtm_preSpinup
and set_dataDownlAtm_postSpinup
sections of the configuration file.
MFS bulk formulae¶
The MFS Bulk Formulae are selected by setting sbc_iformulat=0
in the user configuration file.
The atmospheric forcing files contain the following variables at a specific horizontal resolution and temporal frequency:
 10 m Zonal Wind Component [\(ms^{1}\)],
 10 m Meridional Wind Component [\(ms^{1}\)],
 2 m Air Temperature [\(K\)],
 2 m Dew Point Temperature [\(K\)],
 Mean Sea Level Pressure [\(Pa\)],
 Total Cloud Cover [%],
 Total Precipitation [\(m\)].
An example CDL text representation for an atmospheric forcing file with a 3hour temporal frequency is shown in Listing 6.1.8.
netcdf atmFields_filename {
dimensions :
lon = 245;
lat = 73;
time = UNLIMITED; // (8 currently)
variables : \\
float lon(lon);
lon: units = "degrees_east";
float lat(lat);
lat: units = "degrees_north";
float time(time);
time: units = "seconds since
19700101 00:00:00";
float T2M(time,lat,lon);
T2M: units = "K";
}
Core bulk formulae¶
The CORE Bulk Formulae are selected by setting sbc_iformulat=2
in the user configuration file.
The atmospheric forcing files contain the following variables at a specified horizontal resolution and temporal frequency:
 10 m Zonal Wind Component [\(ms^{1}\)],
 10 m Meridional Wind Component [\(ms^{1}\)],
 2 m Air Temperature [\(K\)],
 2 m Specific Humidity [%],
 Incoming LongWave Radiation [\(W m^{2}\)],
 Incoming ShortWave Radiation [\(W m^{2}\)],
 Total Precipitation (Liquid + Solid) [\(Kg m^{2} s^{1}\)],
 Solid Precipitation [\(Kg m^{2} s^{1}\)].
An example CDL text representation for the atmospheric forcing file with a 3hour temporal frequency is shown in Listing 6.1.9.
netcdf atmFields_filename {
dimensions :
lon = 245;
lat = 73;
time = UNLIMITED; // (8 currently)
variables : \\
float lon(lon);
lon: units = "degrees_east";
float lat(lat);
lat: units = "degrees_north";
float time(time);
time: units = "seconds since
19700101 00:00:00";
float T2M(time,lat,lon);
T2M: units = "K";
}
Flux formulation¶
The Flux Formulation is selected by setting sbc_iformulat=1
in the user configuration file.
The atmospheric forcing files contain the following variables at a specific horizontal resolution and temporal frequency:
 Zonal Wind Stress [0  1],
 Meridional Wind Stress [0  1],
 Total Heat Flux [0  1],
 Solar Radiation Penetration [0  1],
 Mass Flux Exchanged [0  1],
 Surface Temperature [0  1],
 Surface Salinity [0  1].
An example CDL text representation for the atmospheric forcing file with a 3hour temporal frequency is shown in Listing 6.1.10.
netcdf atmFields_filename {
dimensions :
lon = 245;
lat = 73;
time = UNLIMITED; // (8 currently)
variables : \\
float lon(lon);
lon: units = "degrees_east";
float lat(lat);
lat: units = "degrees_north";
float time(time);
time: units = "seconds since
19700101 00:00:00";
float T2M(time,lat,lon);
T2M: units = "K";
}
To perform the extrapolation (SOL) of atmospheric fields (see Section 4.3 for more details), the atmospheric meshmask file must be provided as an input dataset. Users need to configure the required parameters in the set_dataDownlAtmMesh
section of the configuration file.
The atmospheric meshmask file contains the landsea mask variable [01].
An example of CDL text representation of the atmospheric landsea mask file is shown in Listing 6.1.11. The time dimension and coordinate variables can also be omitted if necessary.
netcdf atmFields_filename {
dimensions :
lon = 245;
lat = 73;
time = UNLIMITED; // (1 currently)
variables : \\
float lon(lon);
lon: units = "degrees_east";
float lat(lat);
lat: units = "degrees_north";
float time(time);
time: units = "seconds since
19700101 00:00:00";
float LSM(time,lat,lon);
LSM: units = "01";
}