2.1. Parameter file — PyPAGO 1.0.1 documentation

# 2.1. Parameter file

The working of PyPAGO is based on a Python parameter file, which contains the variables needed by the program. The default parameter file (dedicated to the analysis of the NEMO model) is shown below.

Prior to run PyPAGO analysis, the user is requiered to create, in the working directory, a param.py file, which will overwrite these default parameters.

The most critical variable is the `dictvname` directory, which contains the names of the coordinate and scale factor variables and which will dictate the behaviour of PyPAGO, as detailed below.

Warning

The variables defined in the `dictvname` dictionnary are required and must all be included in a unique file (`mesh_mask.nc` for instance).

    """
    This program contains the main settings of |pypago|
    associated with the NEMO model.
    """

    import sys
    import numpy as np
    import pylab as plt
    import matplotlib as mp
    from mpl_toolkits.basemap import pyproj

    ######################################################## Output redirection

    # Uncomment below to change the outputs
    # and erros locations.
    sys.stdout = sys.stdout
    sys.stderr = sys.stdout

    ######################################################## Scale variables

    # List of model variable names stored
    # as a dictionary
    dictvname = {}
    dictvname["lon_varname"] = "glamt"  # longitude
    dictvname["lat_varname"] = "gphit"  # latitude
    dictvname["depth_varname"] = "gdept_0"  # 1D depth array
    dictvname["mbathy_varname"] = "mbathy"   # last layer index
    dictvname["tmask_varname"] = "tmask"   # mask on t-points
    dictvname["umask_varname"] = "umask"  # mask on u-points
    dictvname["vmask_varname"] = "vmask"  # mask on v-points

    dictvname["dxt_varname"] = "e1t"  # zonal width of t-cells
    dictvname["dyt_varname"] = "e2t"  # meridional width of t-cells
    dictvname["dye_varname"] = "e2u"  # meridional width of u-cells
    dictvname["dxn_varname"] = "e1v"  # zonal width of v-cells
    dictvname["dzt_varname"] = "e3t"   # height of t-cells
    dictvname["dze_varname"] = "e3u"    # height of u-cells
    dictvname["dzn_varname"] = "e3v"  # height of v-cells
    dictvname["time_varname"] = "time_counter"  # height of v-cells

    # used only if the e3t variable is 2D
    # (height of the last ocean layer)
    # dictvname["bathy_varname"] = "ht"   # bathymetry
    # dictvname["dzt1d_varname"] = "e3t_0"

    ######################################################## Settings for diagnostics

    rho0_c = 4.186e6  # for heat transport calculations
    S0 = 34.8  # reference salinity for freshwater calculations

    lev1 = 500  # first depth interval from surface down to lev1
    lev2 = 1000  # second depth interval from lev1 down to lev2
    lev3 = 2000  # third depth interval from lev2 m down to lev3 m

    # Sigma vectors (used in density related transport indices, not implemented yet)
    sigma0_vec_lr = np.array([24, 24.4, 24.9, 25.4, 25.9, 26.4,
                              26.75, 27.05, 27.30, 27.45, 27.58, 27.68, 27.75,
                              27.80, 27.83, 27.86, 27.89, 27.92, 27.95, 27.98,
                              28.01, 28.04, 28.07, 28.1, 28.6, 29.1])

    sigma0_vec_hr = np.array([24, 24.2, 24.4, 24.65, 24.9, 25.15, 25.4, 25.65,
                              25.9, 16.15, 26.4, 16.57, 26.75, 26.90, 27.05, 27.17,
                              27.30, 27.37, 27.45, 27.52, 27.58,
                              27.63, 27.68, 27.72, 27.75, 27.78, 27.80, 27.815,
                              27.83, 27.845, 27.86, 27.875, 27.89,
                              27.905, 27.92, 27.935, 27.95, 27.965,
                              27.98, 27.99, 28.01, 28.025,
                              28.04, 28.055, 28.07, 28.085, 28.1, 28.35,
                              28.6, 28.8, 29.1])

    sigma2_vec = np.array([34.4, 34.6, 34.8, 35, 35.2, 35.4, 36, 36.4,
                           36.6, 36.7, 36.8, 36.9, 36.95, 37, 37.05,
                           37.1, 37.15, 37.2, 37.4, 37.6, 38])

    sigma1_vec = np.arange(29.68, 34.6800+1, 1)

    ######################################################## Settings for figures

    mp.rcParams['lines.linewidth'] = 1.  # line width
    mp.rcParams['text.usetex'] = False  # no latex in matplotlib

    left = 0.07
    right = 0.99
    wspace = 0.07
    top = 0.93
    bottom = 0.03
    figsize = (11, 4)
    bgcolor = 'black'
    cmapt = plt.cm.get_cmap('jet')
    cmaps = plt.cm.get_cmap('jet')
    cmapv = plt.cm.get_cmap('RdBu_r')

    ######################################################## Settings for projection (change carefully)

    ee = pyproj.Geod(ellps='GRS80')  # ellipsoid used for distance calculation

## 2.1.1. NEMO model

Table 2.1 Grid variables for the NEMO model
Variable | Name | Description
--- | --- | ---
time_varname | time_counter | Time variable
lon_varname | glamt | Longitude
lat_varname | gphit | Latitude
tmask_varname | tmask | 3D mask on T points
dxt_varname | e1t | Zonal width of T points
dyt_varname | e2t | Meridional width of T points
dye_varname | e2u | Meridional width of V points
dxn_varname | e1v | Zonal width of U points
dzt_varname | e3t | Height of T points
bathy_varname | ht | Bathymetry (None if not defined in the file)
depth_varname | gdept_1d | 1D depth array
mbathy_varname | mbathy | 2D array of k-indexes of the last ocean points
dzt1d_varname | e3t_0 | 1-D scale factor
dze_varname | e3u | Height of U points (None if not defined in the file)
dzn_varname | e3v | Height of V points (None if not defined in the file)

### 2.1.1.1. Recontruction of the bathymetry

If the `bathy_varname` is `None`, bathymetry is reconstructed from the `depth_varname` and the `mbathy_varname` variables

### 2.1.1.2. Recontruction of the vertical scale factors

The reconstruction of the vertical scale factors depend on the shape of the `dzt` variable.

- If it is 1D, it is assumed that there are no partial steps, and `dzt` is tiled along the longitude and latitude dimensions. And the `dzw` and dzn variables are set equal to `dzt`.
- If it is 2D, then a 3D `dzt` variable is reconstructed by using the `pypago.coords.NemoCoords.create_3d_e3t()` function. This function needs the 1D scale factor variable, whose name is defined by the `dzt1d_varname` variable. Then, if the `dze_varname` and `dzn_varname` variables are not `None`, these variables are read. Else, they are reconstructed from the 3D `dzt` variable by using the `pypago.coords.NemoCoords.reconstruct_3d_e3uv()` function. Finally, the `dzw` variable is reconstructed from the `dze` variable.

## 2.1.2. ROMS model

Table 2.2 Grid variables for the ROMS model
Variable | Name | Description
--- | --- | ---
time_varname | time | Time variable
bathy_varname | h | Bathymetry
tmask_varname | mask_rho | Mask on T points
lon_varname | lon_rho | Longitude of T points
lat_varname | lat_rho | Latitude of T points
dxt_varname | pm | Zonal width of T points
dyt_varname | pn | Merdional width of T points
dxs_varname | pm | Zonal width of U points (southern face)
dyw_varname | pn | Meridional width of V points (western face)
roms_nsigma |  | Number of sigma levels

### 2.1.2.1. Reconstruction of horizontal scale factors

In ROMS model, U points are located on the western faces, while V points are located on the southern faces. Therefore, the `dzn` variable is reconstructed by shifting the `dzs` variable.

### 2.1.2.2. Recontruction of the vertical scale factors

Since ROMS is a \(\sigma\) model, vertical scale factors is set equal to 1. Since the number of \(\sigma\) levels is stored in the data file, the user has to define it in the `param.py` file so that the `dzt`, `dzn` and `dzw` variables are defined with the right dimensions.

Todo

Complete for all the other models