Input Datasets for SURF

To execute the SURF-NEMO 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.

Figure 6.1. Schematized representation of the interface and external forcing 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 spin-up 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 two-dimensional 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";
}

Listing 6.1.1: Example of a netCDF file for bathymetry.

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 arc-seconds. 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 Self-consistent Hierarchical High-resolution 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 coarse-grid 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 Arakawa-C 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 coarse-resolution 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
                  1970-01-01 00:00:00" ;
   float temperature(time, z, y, x) ;
      temperature:units = "degC" ;
}

Listing 6.1.2: Example of a netCDF file for the Initial Condition temperature

To perform the extrapolation (SOL) of ocean fields (see Section 4.3 for more details), the parent land-sea 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 coarse-resolution 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\)]
• Land-sea mask on TUVF grid points [0-1]
• 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);
}

Listing 6.1.3: Example of a netCDF file for the Initial Condition meshmask.

Lateral Open Boundary Condition Datasets

In order to integrate the primitive equations, the NEMO ocean model needs to impose appropriate boundary conditions at the ocean-ocean 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 Arakawa-C grid arrangement covering the nested domain. The model assumes that all input ocean variables during the pre- and post-spinup periods are defined on the same grid.

The coarse-resolution 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
                  1970-01-01 00:00:00";
   float temperature(t,z,y,x);
         temperature: units = "degC";
}

Listing 6.1.4: Example of a netCDF file for Open boundary Condition temperature.

To perform the extrapolation (SOL) of ocean fields (see Section 4.3 for more details), the parent land-sea 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 coarse-resolution 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\)]
• Land-sea mask on TUVF grid points [0-1]
• 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);
}

Listing 6.1.5: Example of a netCDF file for the Initial Condition meshmask.

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 Arakawa-C 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" ;
}

Listing 6.1.6: Example of a netCDF file for the Zonal and meridional Tidal transport for the constituent K1.

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" ;
}

Listing 6.1.7: Example of a netCDF file for the Initial Condition meshmask.

The available input barotropic tide datasets included in the SURF package are derived from the Topex Poseidon Cross-Over (TPXO8-ATLAS) 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 TPXO8-ATLAS website.

The TPXO8 tidal model consists of a multi-resolution bathymetric grid solution, with 1/6° resolution in the global open ocean and 1/30° resolution in shallow-water regions for improved modeling. The dataset includes complex amplitudes of tidal sea-surface elevations and transports for eight primary (M2, S2, N2, K2, K1, O1, P1, Q1), two long-period (Mf, Mm), and three non-linear (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 atmosphere-ocean interface. The following six fields must be provided for the integration domain:

1. Zonal components of surface ocean stress,
2. Meridional components of surface ocean stress,
3. Solar heat fluxes (Qsr),
4. Non-solar heat fluxes (Qns),
5. Water flux exchanged with the atmosphere (E-P), representing evaporation minus precipitation.

Additionally, an optional field can be provided:

6. 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 post-spinup 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 3-hour 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
                  1970-01-01 00:00:00";
   float T2M(time,lat,lon);
         T2M: units = "K";
}

Listing 6.1.8: Example of a netCDF file for the Atmospheric Forcing temperature.

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 Long-Wave Radiation [\(W m^{-2}\)],
• Incoming Short-Wave 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 3-hour 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
                  1970-01-01 00:00:00";
   float T2M(time,lat,lon);
         T2M: units = "K";
}

Listing 6.1.9: Example of a netCDF file for the Atmospheric Forcing temperature.

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 3-hour 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
                  1970-01-01 00:00:00";
   float T2M(time,lat,lon);
         T2M: units = "K";
}

Listing 6.1.10: Example of a netCDF file for the Atmospheric Forcing temperature.

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 land-sea mask variable [0-1].

An example of CDL text representation of the atmospheric land-sea 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
                  1970-01-01 00:00:00";
   float LSM(time,lat,lon);
         LSM: units = "0-1";
}

Listing 6.1.11: Example of a netCDF file for the Atmospheric Forcing meshmask.