To execute the SURF-NEMO package, the user must input several model parameters to select a specific simulation region, the simulation period, horizontal and vertical turbulence schemes, input datasets, interpolation methods, etc.
These parameters are used to conduct the pre- and post-processing phases and to populate the Fortran namelist required to execute the NEMO-OPA code.
These choices are made by specifying the values of the input model parameters in the user configuration file "setParFree.json", where all the free-user input parameters are grouped in different sections according to their functionality. In this chapter we provide details of each section of the configuration file and specify the admissible values, the unit measures and the “reference value” used for the test case experiment for each parameter (see Section 6.4).
Some of the input model parameters are fixed and defined inside the SURF source package in the file "setParFix" (see Appendix A for more details)
The user configuration file has a JavaScript Object Notation (JSON)-based format. JSON is a simple, text-based method of storing and transmitting structured data. This format is "self-describing", easy to understand and can support complex data types and structures. It is commonly used for configuration files in web applications.
JSON syntax is derived from JavaScript object notation syntax and can contain either an array of values or an object (an associative array of name/value pairs also referred to as properties). An array is surrounded by square brackets, [ and ], and contains a comma-separated list of values. An object is surrounded by curly brackets,{ and }, and contains a comma-separated list of name/value pairs. A name/value pair consists of a field name (in double quotes), followed by a colon (:), followed by the field value. A value in an array or object can be of type number (integer or floating-point), string (in double-quotes), boolean (true or false), another array (surrounded by square brackets, [ and ]), another object (surrounded by curly brackets, [ and ]), or null.
The JSON configuration file defined for the SURF-NEMO package is shown in Figure 3.1.
At the top level, we have created the “sections” array, which is an object with just one name/value pair. This array contains various objects. Each object contains three properties: a title that reflects the contents of the section, a four-digit alphanumeric identifier ID (id = A001, A002, etc. for pre-processing sections and id = B001, B002, etc. for post-processing sections) and an array of items delimited by square brackets.
Each element of the “items” array is an object that is identified by a name, a value, a data type (int, float, double, bool and string) and a brief description of the corresponding parameter.
JSON representation for the SURF-NEMO user-configuration file.
The section set_xyGrid contains the free input parameters required for the generation of the horizontal model grid.
gr_xygridSpec
Parameters specification for the horizontal grid: if = 0, the grid is function of the 5 variables (lam0,phi0,nlam,nphi,dxy) if = 1, the grid is function of the 5 variables (lam0,phi0,lam1,phi1,dxy)..
Type: int Ref.Value: 0 Range: 0, 1
gr_jpidta
Number of grid points in zonal direction to specify if xygridSpec=0 (if =NOTUSED, parameter not read).
Type: int Ref.Value: 94
gr_jpjdta
Number of grid points in meridional direction to specify if xygridSpec=0 (if =NOTUSED, parameter not read).
Type: int Ref.Value: 79
gr_ppglam0
Longitude of the first raw and column T-point to specify if xygridSpec=0,1.
Type: float Ref.Value: 16.4375
gr_ppglam1
Longitude of the last raw and column T-point to specify if xygridSpec=1 (if =NOTUSED, parameter not read).
Type: float Ref.Value: NOTUSED
gr_ppgphi0
Latitude of the first raw and column T-point to specify if xygridSpec=0,1.
Type: float Ref.Value: 38.9375
gr_ppgphi1
Latitude of the last raw and column T-point to specify if xygridSpec=1 (if =NOTUSED, parameter not read).
Type: float Ref.Value: NOTUSED
gr_jp_cfg
Child model resolution (1/gr_jp_cfg) to specify if xygridSpec=0,1.
The section set_zGrid contains the free input parameters used to generate the vertical grid.
gr_jpkdta
Number of vertical levels.
Type: int Ref.Value: 120
gr_zgridSpec
Parameters specification for the vertical grid: if = 0, the grid is function of the 5 variables (hh0,h1,hsur,hcr,hth) if = 1, the grid is function of the 4 variables (dzmin,hmax,hcr,hth).
Type: int Ref.Value: 1. Range: 0, 1
gr_ppsur
Parameter h_sur for the z-coord. trasformation to specify if zgridSpec=0 (if =NOTUSED, parameter not read).
Type: double Ref.Value: NOTUSED
gr_ppa0
Parameter h_0 for the z-coordinate trasformation to specify if zgridSpec=0 (if =NOTUSED, parameter not read).
Type: double Ref.Value: NOTUSED
gr_ppa1
Parameter h_1 for the z-coordinate trasformation to specify if zgridSpec=0 (if =NOTUSED, parameter not read).
Type: double Ref.Value: NOTUSED
gr_ppkth
Parameter h_th which gives the approximate layer number above which stretching will be maximum (usually of order nz/2) to specify if zgridSpec=0,1.
Type: double Ref.Value: 100
gr_ppacr
Parameter h_cr which gives the grid stretching factor (the highest gr_ppacr, the smallest the stretching) to specify if zgridSpec=0,1.
Type: double Ref.Value: 30
gr_ppdzminw
Depth of the top (first) model layer depth of second 'w' level to specify if zgridSpec=1 (if =NOTUSED, parameter not read).
Type: double Ref.Value: 2.8
gr_pphmaxw
Maximum depth of the ocean depth of the last 'w' level (set to 0.0 to be computed) to specify if zgridSpec=1 (if =NOTUSED, parameter not read).
Type: double Ref.Value: 0.0
gr_dbletanh
Enables the use of the double tanh function for vertical coordinates.
Type: bool. Ref.Value: False.
gr_ppa2
Parameter h_2 to specify if gr_dbletanh=True (if =NOTUSED, parameter not read).
Type: double Ref.Value: NOTUSED
gr_ppkth2
Parameter h_th2 if gr_dbletanh=True (if =NOTUSED, parameter not read).
Type: double Ref.Value: NOTUSED
gr_ppacr2
Parameter h_cr2 if gr_dbletanh=True (if =NOTUSED, parameter not read).
This section of the JSON file contains the free input parameters used to define the tidal components which can be added both as the equilibrium tidal sea level and/or only at the lateral boundaries
latBtide_lPot
Enables the use of tidal potential forcing.
Type: bool Ref.Value: True
latBtide_K1
Name of the Lunar diurnal K1 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: K1 Range: K1
latBtide_O1
Name of the Lunar diurnal O1 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: O1 Range: O1
latBtide_P1
Name of the Solar diurnal P1 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: P1 Range: P1
latBtide_Q1
Name of the Larger lunar elliptic diurnal Q1 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: Q1 Range: Q1
latBtide_K2
Name of the Lunisolar semidiurnal K2 tidal component (if =NOTUSED, component not used)
Type: string Ref.Value: K2 Range: K2
latBtide_M2
Name of the Principal lunar semidiurnal M2 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: M2 Range: M2
latBtide_N2
Name of the Larger lunar elliptic semidiurnal N2 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: N2 Range: N2
latBtide_S2
Name of the Principal solar semidiurnal S2 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: S2 Range: S2
latBtide_M4
Name of the Shallow water overtides of principal lunar M4 tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: M4 Range: M4
latBtide_Mm
Name of the Lunar monthly Mm tidal component (if =NOTUSED, component not used).
Type: string Ref.Value: Mm Range: Mm
latBtide_Mf
Name of the Lunisolar fortnightly Mf tidal component (if =NOTUSED, component not used).
This section of the JSON file contains the free input parameters used to define the parameterization of lateral subgrid-scale diffusion for tracers.
tra_typeOperator
Type of the operator used (0)laplacian, (1)bilaplacian.
Type: int Ref.Value: 0 Range: 0, 1
tra_eddycoeffSpec
Horizontal eddy coeff. specification (0)def. by coeff. tra_eddycoeff_child, (1)def. from coeff. tra_eddycoeff_father according fat/child coeff. relation.
Type: int Ref.Value: 0 Range: 0, 1
tra_eddycoeff_child
Horizontal eddy diffusivity (>0 (m2/s) laplacian or < 0 (m4/s2) bilaplacian) of the child model (if =NOTUSED, parameter not read).
Type: float Ref.Value: 80.
tra_eddycoeff_father
Horizontal eddy diffusivity (>0 (m2/s) laplacian or < 0 (m4/s2) bilaplacian) of the father model to be used in fat/child coeff. relation (if =NOTUSED, parameter not read).
Type: float Ref.Value: NOTUSED
tra_factor
Factor to be used in fat/child coeff. relation (if laplacian:(a_child=factor*???), if bilaplacian:(a_child=factor*a_fat(Dx_child/Dx_fat)^4)).
This section of the JSON file contains the free input parameters used to define the parameterization of lateral subgrid-scale viscosity for momentum.
dyn_typeOperator
type of the operator used (0)laplacian, (1)bilaplacian.
Type: int Ref.Value: 1 Range: 0, 1
dyn_eddycoeffSpec
horizontal eddy coeff. specification (0)def. by coeff. dyn_eddycoeff_child, (1)def. from coeff. dyn_eddycoeff_father according fat/chld coeff. relation.
Type: int Ref.Value: 1 Range: 0, 1
dyn_eddycoeff_child
horizontal eddy viscosity (>0 (m2/s) laplacian or < 0 (m4/s2) bilaplacian) of the child model (if =NOTUSED, parameter not read).
Type: float Ref.Value: NOTUSED
dyn_eddycoeff_father
horizontal eddy viscosity (>0 (m2/s) laplacian or < 0 (m4/s2) bilaplacian) of the father model to be used in fat/child coeff. relation (if =NOTUSED, parameter not read).
Type: float Ref.Value: -0.5e10
dyn_factor
factor to be used in father/child coeff. relation (if laplacian:(a_child=factor*???), if bilaplacian:(a_child=factor*a_fat(Dx_child/Dx_fat)^4)).
This section of the JSON file contains the parameters needed to make up the URL that is required to access the input coastline datasets from a local or remote ropository.
urlCoast_usr
Username to access the coastline datasets from a remote ftp server.
Type: string Ref.Value: usr
urlCoast_pwd
Password to access the coastline datasets from a remote ftp server.
Type: string Ref.Value: pwd
urlCoast_urlbase
Parametric urlname (i.e. ftp:/... or file:///...) for the coastline datasets. Parameters: (RESCOAST).
This section of the JSON file contains the parameters needed to make up the URL that is required to access the input bathymetry datasets from a local or remote ropository.
urlBat_usr
Username to access the bathymetric datasets from a remote ftp server.
Type: string Ref.Value: usr
urlBat_pwd
Password to access the bathymetric datasets from a remote ftp server.
Type: string Ref.Value: pwd
urlBat_urlbase
Parametric urlname (i.e. ftp:/... or file:///...) for the bathymetric datasets. Parameters: (RESOL).
Type: string Ref.Value: usr
urlBat_resol
Name for spatial resolution used to replace the substring (RESOL) on the parametric urlname (if =NOTUSED, parameter not read).
This section of the JSON file contains the parameters needed to make up the URL that is required to access the input atmospheric meshmask datasets from a local or remote ropository.
urlAtmMesh_usr
Username to access the input atmospheric meshmask datasets from a remote ftp server.
Type: string Ref.Value: usr
urlAtmMesh_pwd
Password to access the input atmospheric meshmask datasets from a remote ftp server.
Type: string Ref.Value: pwd
urlAtmMesh_urlbase
Parametric urlname (i.e. ftp:/... or file:///...) for input atmospheric meshmask datasets. Parameters: (FIELD),YYYY(p)MM(p)DD(p).
This section of the JSON file contains the parameters needed to make up the FILENAMEs of the input atmospheric meshmask datasets.
fileAtmMesh_filebase_velU
Parametric filename for the Zonal Air Velocity datasets before the spinup-time (if sbc_iformulat=0,2). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Meridional Air Velocity datasets before the spinup-time (if sbc_iformulat=0,2). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Mean Sea-Level Pressure datasets before the spinup-time (if sbc_iformulat=0 or/and sbc_aprdyn). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Total Cloud Cover datasets before the spinup-time (if sbc_iformulat=0). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Air Temperature datasets before the spinup-time (if sbc_iformulat=0,2). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Dewpoint Temperature datasets before the spinup-time (if sbc_iformulat=0). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Total Precipitation datasets before the spinup-time (if sbc_iformulat=0,2). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Parametric filename for the Zonal Wind Stress datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: NOTUSED
fileAtmMesh_filebase_tauV
Parametric filename for the Meridional Wind Stress datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_qtot
Parametric filename for the Total Heat Flux datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_qsr
Parametric filename for the Solar Radiation Penetration datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_emp
Parametric filename for the Mass Flux Exchanged datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_tempS
Parametric filename for the Surface Temperature datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_salS
Parametric filename for the Surface Salinity datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_umid
Parametric filename for the Air Umidity datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_radLW
Parametric filename for the Long Wave Radiation datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_radSW
Parametric filename for the Short Wave Radiation datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_filebase_snow
Parametric filename for the Solid Precipitation datasets before the spinup-time (if sbc_iformulat=1). Parameters: YYYY(p)MM(p)DD(p),YYYY(i)MM(i)DD(i),YYYY(i-1)MM(i-1)DD(i-1),YYYY(i+1)MM(i+1)DD(i+1).
Type: string Ref.Value: usr
fileAtmMesh_lcompression
(=True) if the datasets you want to download are gzip compressed files (*.gz).
Type: bool Ref.Value: False
fileAtmMesh_llonFlip
(=True) if the longitude coord. is in the 0 to 360 range (=False) if longitude is in -180:+180 range.
Type: bool Ref.Value: False
fileAtmMesh_llatInv
(=True) if the dataset contains latitude decreasing through the pole.
Type: bool Ref.Value: True
fileAtmMesh_lkeepSrcFull
(=True) if you want to keep in your disk the downloaded uncutted datasets.
