2.5. Build initial and boundary conditions

Initial and boundary conditions, here after “ibc” (surface elevation, 3D currents, barotropic currents, temperature and salinity, eventually other tracers) for realistic simulations are extracted from an ocean (re-)analysis (generally at lower resolution, and encompassing a larger area), named in the following OGCM.

Initial conditions are interpolated over the whole 3D CROCO grid at the initialization date, while boundary conditions are interpolated for the whole simulation timeseries but only at the 4 lateral grid boundaries. A sponge layer in CROCO ensures a smooth transition between the boundary and the interior values.

These 2 processing steps are performed with make_ini.py and make_bry.py scripts.

The different steps to build ibc are:

• Extrapolate values on mask

• At each Z-level of the OGCM grid, interpolate each field on the CROCO horizontal grid

• Then, interpolate on the vertical sigma-coordinates

• For velocities (u,v vectors), project them on the grid angle, and shift them to the u,v grid

2.5.1. User-defined parameters

All the requested user-defined parameters to build the IBC conditions are gathered in a configuration file, here named ibc.ini.

This file contains:

The [Croco_Files] section defines the path and prefix for CROCO files:

croco_files_dir	Path of the CROCO files directory
croco_grd_prefix	Prefix for the CROCO grid file
croco_ini_prefix	Prefix used for the CROCO initial file, usually = croco_ini
croco_bry_prefix	Prefix used for CROCO boundary files, usually = croco_bry
croco_bry_format	How boundary files are splitted (options: MONTHLY,YEARLY,FULL)

The [Zoom_Options] section defines if you are using the main grid (parent grid) or a nested grid (zoom or child grid). If using agrif, it will uses agrif_level as extension of created files.

is_zoom	True/False flag to define if the grid is a zoom or the main grid
is_agrif	True/False flag to define if the grid is an agrif nested grid
agrif_level	integer level of the agrif grid to consider (0 is parent, 1 is first child)

The [Times] section defines dates of the simulation:

Ystart, Mstart, Dstart, Hstart	year, month, day, hour of the chosen start date to prepare initial and boundary conditions
Yend, Mend, Dend, Hend	year, month, day, hour of the chosen end date to prepare boundary conditions
Yorig, Morig, Dorig, Horig	year, month, day, hour of the time origin date

The origin date defines the time at which the OGCM input data will be referenced in CROCO ibc files (e.g. days since XXXX:XX:XX). Note that it can be different from the reference of the source data input files (this reference is properly read in python tools), but it must be consistent between boundary and surface forcing conditions :

Note

Origin time and initial time can be different. Origin time should be consistent between boundary and forcing conditions.

The [Sigma_Params] section defines the stretching parameters for the sigma coordinate:

theta_s	Vertical sigma-coordinate surface stretching parameter
theta_b	Vertical sigma-coordinate bottom stretching parameter
N	Number of vertical sigma levels
hc	Vertical sigma-coordinate critical depth parameter, giving approximately the transition depth between the horizontal surface levels and the bottom terrain following levels.

CROCO uses sigma coordinate, which is a generalized vertical terrain-following vertical coordinate system:

\begin{eqnarray} z(x,y,\sigma,t) & = & \zeta(x,y,\sigma) + \left[ \zeta(x,y,t) + h(x,y) \right] z_0(x,y,\sigma) \end{eqnarray}

with:

• \(\sigma\) a fractional vertical stretching coordinate, \(-1 \le \sigma \le 0\)

• \(\zeta (x,y,\sigma)\) the free-surface

• \(h(x,y)\) the ocean bottom

• \(z_0 (x,y,\sigma)\) a nonlinear vertical transformation defined as:

\begin{eqnarray} z_0 (x,y,\sigma) & = & \frac{ h_c \sigma + h(x,y)Cs(\sigma)}{h_c+h(x,y)} \end{eqnarray}

with:

• \(h_c\) a positive thickness controlling the stretching

• \(Cs(\sigma)\) a nondimensional, monotonic, vertical stretching, \(-1 \le (C\sigma) \le 0\), defined as:

\begin{eqnarray} Cs(\sigma) & = & \frac{e^{\theta_b csf}-1.}{1.-e^{-\theta_b}} \quad \qquad \textrm{if} \ \theta_s > 0 , \\ Cs(\sigma)=csf \quad \textrm{otherwise} \end{eqnarray}

with:

\begin{eqnarray} csf & = & \frac{1.-cosh(\theta_s \ sc)}{cosh(\theta_s)-1.} \quad \textrm{if} \ \theta_b > 0 , \\ csf=-sc^2 \quad \textrm{otherwise} \end{eqnarray}

and:

\begin{eqnarray} sc & = & \frac{\sigma-N}{N} \end{eqnarray}

Warning

Note that sigma levels prescribed here during pre-processing MUST be consistent with sigma parameters prescribed for the run in croco.in (stretching parameters) and param.h (number of vertical levels, N).

The [IBC_Options] section defines several parameters regarding the initial input data:

obc_dict	define boundary status: opened or closed (1=open , [S W E N])
cycle_time_bry	used if you want to create a cycle in number of days on bry conditions: typically, to have a repetition of a year of boundary forcing cycle would be set to 365. If no cycling put 0.
tracers	list of tracers to consider. Names defined here must also be defined in your reader
uv_conserv	0/1 flag to correct the 3D velocities according to the barotropic OGCM transport, i.e. for each water column remove the integrated tranport on the sigma grid and add instead the OGCM transport: u(z) = u(z) - integ(u.ds) + integ(u_ogcm.dz)
min_nb_valid_data	minimum number of valid data in a given z-level layer to consider this z-level as valid. If at a certain depth this threshold is not reached, the level will be considered as not intersecting the ocean.

Note

Initialization time for the simulation is set by Ystart, Mstart, Dstart, Hstart. Time in the input file is not considered for creating the initial file, only the time index, tndx, to select data in the input file is considered.

The [IBC_Input_Files] section defines directories and path of inputs and outputs files:

ibc_reader	keyword of the reader to use as defined in readers.jsonc
ibc_dir	path of OGCM input data
ibc_prefix	prefix of OGCM input data filenames (expected filename form is prefix_Y????M??ibc_extension, example mercator_Y2013M01.cdf)
ibc_extension	extension (e.g. .nc or .cdf) of OGCM input data filenames (expected filename form is prefix_Y????M??ibc_extension, example `mercator_Y2013M01.cdf)
ibc_freq	indicate the frequency of inputs to be read to build boundary conditions. Accepted format: 1M, 1D, 3h, 15m, 30s. This is used only in case of missing data at the begining or at the end of the wanted simulation period to duplicate the first or the last time step to be able to perform time interpolation.
ibc_multi_files	True/False flag to indicate if the different variables are in separated files or in the same input file
ibc_file_ssh, input_file_tracers, ibc_file_u, ibc_file_v	if multi_files is True provide the names of variables in the various filenames (expected filenames form is prefix_input_file_var_Y????M??ibc_extension, example mercator_ssh_Y2013M01.cdf mercator_u_Y2013M01.cdf mercator_v_Y2013M01.cdf)
ini_filedate	date in the filename of the initial file to read
ini_idx	time index to read in the input file used for initial conditions

In the provided example of ibc.ini, we use as initial and boundary conditions the Mercator product GLORYS12, but already processed in a CROCO-like format by tools available for downloading Mercator data in croco_tools. An extraction from January 2013 to March 2013 is available in the tutorial section of CROCO website: https://www.croco-ocean.org/trainings/, in the section ‘Regional configuration (#define REGIONAL in cppdefs.h)’ under ‘Global datasets needed for preprocessing’. Here is the link to download them: https://data-croco.ifremer.fr/CONFIGS_EXAMPLES/DATASETS_GLOB_INTER/CROCO/MERCATOR_GLOB_201301.tar.gz The following 3 files are provided:

• mercator_Y2013M1.cdf

• mercator_Y2013M2.cdf

• mercator_Y2013M3.cdf

These files are not “original” mercator files, and we will use the mercator_croco keyword in readers.jsonc to differentiate their formatting.

2.5.2. Check or add reader for input data

Check/edit the reader configuration, readers.jsonc, for these data. In this example, we use the mercator_croco style of formatting:

"mercator_croco": {
     "depth": "depth",
     "lonr": "lonT",
     "lonu": "lonU",
     "lonv": "lonV",
     "latr": "latT",
     "latu": "latU",
     "latv": "latV",
     "ssh": "ssh",
     "temp": "temp",
     "salt": "salt",
     "u": "u",
     "v": "v",
     "time": "time",
     "time_dim": "time"
   }

You can check the variables name from the input data by doing:

ncdump -h mercator_Y2013M1.cdf

If you have downloaded mercator data on your own (for example using the provided script download_mercator.py) , with a more “mercator-native” format, you may rather use the mercator dictionnary:

"mercator": {
     "depth": "depth",
     "lonr": "longitude",
     "lonu": "longitude",
     "lonv": "longitude",
     "latr": "latitude",
     "latu": "latitude",
     "latv": "latitude",
     "ssh": "zos",
     "temp": "thetao",
     "salt": "so",
     "u": "uo",
     "v": "vo",
     "time": "time",
     "time_dim": "time"
   },

If you have another type of input data, not already existing in reader configuration (readers.jsonc), you can add it.

2.5.3. Build the initial conditions with make_ini.py

• Edit the ibc.ini configuration file.

• Eventually edit the readers.jsonc reader dictionnary

• Launch the script:

  ./make_ini.py ibc.ini
  

• Check the generated file, which path and prefix is defined in ibc.ini. In this example it will be:

croco_ini_mercator_croco_Y2013M01.nc

2.5.4. Build the boundary conditions with make_bry.py

If not alreay done, edit the relevant sections in ibc.ini, and then launch:

./make_bry.py ibc.ini

Check the generated files in the directory defined in croco_dir. In this example they will be:

• croco_bry_mercator_croco_Y2013M01.nc

• croco_bry_mercator_croco_Y2013M02.nc

• croco_bry_mercator_croco_Y2013M03.nc

Note that make_bry is quite similar to make_ini, but you will have several time frames in the output bry file, and only the four boundaries are computed instead of the full 3D grid.