Public Function Reference
Surface Calculation
- surf.load_tsdata(path, zgriddata, to_varname='to', so_varname='so', vert_dim='deptht', i_dim='x', j_dim='y', open_mf=False, **kwargs)
Create tsdata dictionary by loading from a standard NEMO output (typical a *grid-T.nc file) or a netcdf file containing the necessary temperature and salinity information.
Parameters
- path: String or List of Strings
Location(s) of the file(s) to read using xarray.open_dataset (default, open_mf=False) or xarray.open_mfdataset (open_mf=True)
If open_mf=False: A string in the form “/path/to/my/files/my_file.nc” If open_mf=True: A string glob in the form “/path/to/my/files/*.nc”
or an explicit list of files to open
- zgriddata: Dictionary
Must contain the following information about the vertical C-grid discretization
hgriddata[“tmask3d”]: DataArray (z_t, y, x) 3D mask for T-points using the NEMO masking convention (False = masked point)
- to_varname: String (optional, default = “to”)
Netcdf variable name for the potential or conservative temperature Can be found using ncdump -h your_file.nc
- so_varname: String (optional, default = “so”)
Netcdf variable name for the practical or absolute salinity Can be found using ncdump -h your_file.nc
- vert_dim: String (optional, default = “deptht”)
Dimension name for the vertical (k) axis. Can be found using ncdump -h your_file.nc
- i_dim: String (optional, default = “x”)
Dimension name for the i axis. Can be found using ncdump -h your_file.nc
- j_dim: String (optional, default = “y”)
Dimension name for the j axis. Can be found using ncdump -h your_file.nc
Returns
- tsdata: Dictionary
Contains the following information about the ocean temperature and salinity
tsdata[“to”]: DataArray (time, z_t, y, x) Potential or conservative temperature
tsdata[“so”]: DataArray (time, z_t, y, x) Practical or absolute salinity
- surf.find_omega_surfs(tsdata, neutralgrid, zgriddata, zpins, ipins, jpins, tpins, eos='gsw', ITER_MAX=10, calc_veronis=True, calc_potsurf=True, ver_ref=0.0, pot_ref=0.0, **kwargs)
Calculate omega surfaces with a fixed point at a specific locations in time and space. There are options to also calculate the veronis density and/or the intersecting potential density surfaces for labelling or reference.
Parameters
- tsdata: Dictionary
Can be generated using load_tsdata, Must contain the following information about the ocean temperature and salinity.
tsdata[“to”]: DataArray (time, z_t, y, x) Potential or conservative temperature (depending on the equation of state, see eos argument)
tsdata[“so”]: DataArray (time, z_t, y, x) Practical or absolute salinity (depending on the equation of state, see eos argument)
- neutralgrid: Dictionary
(Description below from NeutralOcean documentation) Can be generated using build_nemo_hgrid Must contain the following:
- edgestuple of length 2
Each element is an array of int of length E, where E is the number of edges in the grid’s graph, i.e. the number of pairs of adjacent water columns (including land) in the grid. If edges = (a, b), the nodes (water columns) whose linear indices are a[i] and b[i] are adjacent.
- dist1d array
Horizontal distance between adjacent water columns (nodes). dist[i] is the distance between nodes whose linear indices are edges[0][i] and edges[1][i].
- distperp1d array
Horizontal distance of the face between adjacent water columns (nodes). distperp[i] is the distance of the interface between nodes whose linear indices are edges[0][i] and edges[1][i].
- zgriddata: Dictionary
Can be generated using load_zgriddata Must contain the following information about the vertical C-grid discretization
hgriddata[“deptht”]: DataArray (z_t, y, x) Depth of the T-points
- zpins: List of floats
Depths of the fixed points
- ipins: List of integers
i-indices of the fixed point
- jpins: List of integers
j-indices of the fixed point
- tpins: List of integers
time indices of the fixed point
- eos: String or Function or Tuple of Functions (optional, default=”gsw”)
Specification for the equation of state.
The definitions of temperature (potential vs conservative) and salinity (practical vs absolute) must match the equation of state. By default the “gsw” equation of state is used which depends on# absolute salinity and conservative temperature.
- Two premade options from NeutralOcean are described below:
“gsw” - TEOS-10 Gibbs Sea Water “jmd95” - Jackett and McDougall 1995 equation of state
(Description below from NeutralOcean documentation) If a str, can be any of the strings accepted by neutralocean.eos.tools.make_eos, e.g. ‘jmd95’, ‘jmdfwg06’, ‘gsw’.
If a function, must take three inputs corresponding to S, T, and P, and output the density (or specific volume). This form is not allowed when diags is True. This can be made as, e.g., eos = neutralocean.eos.make_eos(‘gsw’) for a non-Boussinesq ocean, or as eos = neutralocean.eos.make_eos(‘gsw’, grav, rho_c) for a Boussinesq ocean with grav and rho_c (see inputs below).
If a tuple of functions, the first element must be a function for the equation of state as above, and the second element must be a function taking the same three inputs as above and returning two outputs, namely the partial derivatives of the equation of state with respect to S and T. The second element can be made as, e.g., eos_s_t = neutralocean.eos.make_eos_s_t(‘gsw’, grav, rho_c)
The function (or the first element of the tuple of functions) should be @numba.njit decorated and need not be vectorized – it will be called many times with scalar inputs.
- ITER_MAX: Integer (option, default=10)
Maximum number of iterations for omega surface calculation.
- ITER_MINInteger (option, default=1)
Minimum number of iterations for omega surface calculation.
- calc_veronis: Logical (default=True)
Calculate the Veronis density of each surface at their respective fixed location in time and space
- calc_potsurf: Logical (default=True)
Calculate the potential density surface which intersects the fixed point location in space and time. If you set ITER_MAX=0 while calc_potsurf=True, only potential density surfaces will be calculated.
- ver_ref:
Reference depth for the calculation of the Veronis density (if calc_veronis = True)
- pot_ref:
Reference depth for the calculation of the potential density (if calc_potsurf = True)
- kwargs:
Additional keyword arguments for neutralocean.surface.omega_surf
Returns
surf_dataset: Dataset containing all of the surfaces requested.
Grid interpretation
- grid.build_nemo_hgrid(hgriddata, iperio=True, jperio=False)
Create NeutralOcean grid object from a dictionary of horizontal grid variables.
Parameters
- hgriddata: Dictionary of DataArrays (xarray)
Describes the horizontal discretization. The dictionary can be automatically generated from standard NEMO outputs using grid.load_hgriddata or created by hand. Essential entries in the dictionary are the following:
hgriddata[“e1u”] -> U-cell widths in i direction hgriddata[“e1v”] -> U-cell widths in j direction hgriddata[“e2u”] -> V-cell widths in i direction hgriddata[“e2v”] -> V-cell widths in j direction
- iperio: Logical (optional, default=True)
Specifies periodicity in i-direction iperio = True -> i-coordinate is periodic (true on global ORCA grid)
- jperio: Logical (optional, default=False)
Specifies periodicity in j-direction jperio = True -> j-coordinate is periodic (false on global ORCA grid)
Returns
- neutralgrid: Dictionary
(Description below from NeutralOcean documentation) Containing the following:
- edgestuple of length 2
Each element is an array of int of length E, where E is the number of edges in the grid’s graph, i.e. the number of pairs of adjacent water columns (including land) in the grid. If edges = (a, b), the nodes (water columns) whose linear indices are a[i] and b[i] are adjacent.
- dist1d array
Horizontal distance between adjacent water columns (nodes). dist[i] is the distance between nodes whose linear indices are edges[0][i] and edges[1][i].
- distperp1d array
Horizontal distance of the face between adjacent water columns (nodes). distperp[i] is the distance of the interface between nodes whose linear indices are edges[0][i] and edges[1][i].
- grid.load_hgriddata(path, e1u_varname='e1u', e2u_varname='e2u', e1v_varname='e1v', e2v_varname='e2v', i_dim='x', j_dim='y', open_mf=False, **kwargs)
Create hgriddata dictionary by loading from a standard NEMO output (either a mesh_mask or domaincfg file) or a netcdf file containing the necessary C-grid information
Parameters
- path: String or List of Strings
Location(s) of the file(s) to read using xarray.open_dataset (default, open_mf=False) or xarray.open_mfdataset (open_mf=True)
If open_mf=False: A string in the form “/path/to/my/files/my_file.nc” If open_mf=True: A string glob in the form “/path/to/my/files/*.nc”
or an explicit list of files to open
- e1u_varname: String (optional, default = “e1u”)
Netcdf variable name for the U-cell width in the i-direction. Can be found using ncdump -h your_file.nc
- e2u_varname: String (optional, default = “e2u”)
Netcdf variable name for the U-cell width in the j-direction. Can be found using ncdump -h your_file.nc
- e1v_varname: String (optional, default = “e1v”)
Netcdf variable name for the V-cell width in the i-direction. Can be found using ncdump -h your_file.nc
- e2v_varname: String (optional, default = “e2v”)
Netcdf variable name for the V-cell width in the j-direction. Can be found using ncdump -h your_file.nc
- i_dim: String (optional, default = “x”)
Dimension name for the i axis. Can be found using ncdump -h your_file.nc
- j_dim: String (optional, default = “y”)
Dimension name for the j axis. Can be found using ncdump -h your_file.nc
- open_mf: Logical (optional, default = False)
- open_mf = False -> Load a dataset from a single netcdf file
(see xarray.open_dataset)
- open_mf = True -> Load a dataset from multiple netcdf files
(see xarray.open_mfdataset)
- kwargs: Keyword arguments
Keyword arguments for xarray.open_dataset (default, open_mf=False) or xarray.open_mfdataset (default, open_mf=True)
Returns
- hgriddata: Dictionary
Contains the following information about the horizontal C-grid discretization
hgriddata[“e1u”]: DataArray U-cell width in the i-direction
hgriddata[“e1v”]: DataArray V-cell width in the i-direction
hgriddata[“e2u”]: DataArray U-cell width in the j-direction
hgriddata[“e2v”]: DataArray V-cell width in the j-direction
If any of the above variables cannot be found in the netcdf file(s) then a warning message will appear and the variable will be missing in hgriddata.
- grid.load_zgriddata(path, deptht_varname='gdept_0', tmask3d_varname='tmask', tmask2d_varname='tmaskutil', vert_dim='nav_lev', i_dim='x', j_dim='y', open_mf=False, **kwargs)
Create zgriddata dictionary by loading from a standard NEMO output (either a mesh_mask or domaincfg file) or a netcdf file containing the necessary C-grid information
Parameters
- path: String or List of Strings
Location(s) of the file(s) to read using xarray.open_dataset (default, open_mf=False) or xarray.open_mfdataset (open_mf=True)
If open_mf=False: A string in the form “/path/to/my/files/my_file.nc” If open_mf=True: A string glob in the form “/path/to/my/files/*.nc”
or an explicit list of files to open
- deptht_varname: String (optional, default = “gdept_0”)
Netcdf variable name for the T-cell depth. Can be found using ncdump -h your_file.nc
- tmask3d_varname: String (optional, default = “tmask”)
Netcdf variable name for the 3-dimensional (z,y,x) tmask. The mask must use the NEMO masking convention, 0 (or False) = Masked. Can be found using ncdump -h your_file.nc
- tmask2d_varname: String (optional, default = “tmaskutil”)
Netcdf variable name for the 2-dimensional (y,x) tmask. The mask must use the NEMO masking convention, 0 (or False) = Masked. Can be found using ncdump -h your_file.nc
- vert_dim: String (optional, default = “nav_lev”)
Dimension name for the vertical (k) axis. Can be found using ncdump -h your_file.nc
- i_dim: String (optional, default = “x”)
Dimension name for the i axis. Can be found using ncdump -h your_file.nc
- j_dim: String (optional, default = “y”)
Dimension name for the j axis. Can be found using ncdump -h your_file.nc
- open_mf: Logical (optional, default = False)
- open_mf = False -> Load a dataset from a single netcdf file
(see xarray.open_dataset)
- open_mf = True -> Load a dataset from multiple netcdf files
(see xarray.open_mfdataset)
- kwargs: Keyword arguments
Keyword arguments for xarray.open_dataset (default, open_mf=False) or xarray.open_mfdataset (default, open_mf=True)
Returns
- zgriddata: Dictionary
Contains the following information about the vertical C-grid discretization
hgriddata[“deptht”]: DataArray (z_t, y, x) Depth of the T-points
hgriddata[“tmask3d”]: DataArray (z_t, y, x) 3D mask for T-points using the NEMO masking convention (False = masked point)
hgriddata[“tmask2d”]: DataArray (y, x) 2D mask for T-points using the NEMO masking convention (False = masked point)
If any of the above variables cannot be found in the netcdf file(s) then a warning message will appear and the variable will be missing in hgriddata.