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', eos_type='specvol', ITER_MAX=10, calc_veronis=True, calc_potsurf=True, ver_ipins=None, ver_jpins=None, 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.
- EOS_TYPE: String
String describing the quantity returned by the equation of state. The options are
‘specvol’ : Specific volume used by gsw ‘insitu’ : In-situ density
- 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_ipins: None or Integer or list of Integers (default=None)
i-index (or indices) to calculate the Veronis density (if calc_veronis = True). If a single integer, then the Veronis density is calculate at the same position (ver_ipin, ver_jpin) for all surfaces (the preferred method for consisten Veronis density)
If None, then ver_ipins = ipins.
If a list of integers, then the length of the list must match ipins.
- ver_jpins: None or Integer or list of Integers (default=None)
j-index (or indices) to calculate the Veronis density (if calc_veronis = True). If a single integer, then the Veronis density is calculate at the same position (ver_ipin, ver_jpin) for all surfaces (the preferred method for consisten Veronis density)
If None, then ver_jpins = jpins.
If a list of integers, then the length of the list must match jpins.
- 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, gridtype='rectilinear')
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, infer_tmask2d=False, blev_varname='bottom_level', infer_tmask3d=False, infer_path='nemo-T.nc', infer_varname='so', infer_tdim='time_counter', infer_idim='x', infer_jdim='y', infer_zdim='deptht', infer_val=None, **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.
Equation of State
- eos.NEMO_eos(eos_name, rn_a0=0.1655, rn_b0=0.7655, rn_nu=0.0024341, rn_lambda1=0.05952, rn_lambda2=0.00074914, rn_mu1=0.0001497, rn_mu2=1.109e-05)
Create a description of NEMO’s equation of state (TEOS10, EOS80, or SEOS), which is compatible with neutralocean.
Parameters
- eos_name: String
Name of the desired equation of state in NEMO = ‘teos10’ -> the polyTEOS-10-bsq equation of seawater (Roquet et al. 2015) = ‘eos80’ -> the polyEOS80-bsq equation of seawater = ‘seos’ -> A simplified equation of state inspired by Vallis (2006)
All equations use the default parameters used in the NEMO source code (as of v4.0.7). Namelist parameters for the simplified equation of state can be set with the keyword arguments below.
For a linear equation of state, only rn_a0 and rn_b0 should be non-zero (not default behaviour)
- rn_a0: float (optional, default = 1.655e-1)
Only used if eos_name = ‘seos’ seos parameter - Linear thermal expansion coefficient
- rn_b0: float (optional, default = 7.655e-1)
Only used if eos_name = ‘seos’ seos parameter - Linear haline expansion coefficient
- rn_nu: float (optional, default = 2.4341e-3)
Only used if eos_name = ‘seos’ seos parameter - Cabbeling coefficient for T*S
- rn_lambda1: float (optional, default = 5.9520e-2)
Only used if eos_name = ‘seos’ seos parameter - Cabbeling coefficient for T^2
- rn_lambda2: float (optional, default = 7.4914e-4)
Only used if eos_name = ‘seos’ seos parameter - Cabbeling coefficient for S^2
- rn_mu1: float (optional, default = 1.4970e-4)
Only used if eos_name = ‘seos’ seos parameter - Thermobaric coefficient for T
- rn_mu2: float (optional, default = 1.1090e-5)
Only used if eos_name = ‘seos’ seos parameter - Thermobaric coefficient for S
Returns
- ( eos, eos_s_t ): tuple
Tuple of functions describing the insitu density (eos) and it’s partial derivatives wrt temperature and salinity. These functions are compatible with neutralocean functions.
- eos.calc_seos(S, T, Z, rn_a0=0.1655, rn_b0=0.7655, rn_nu=0.0024341, rn_lambda1=0.05952, rn_lambda2=0.00074914, rn_mu1=0.0001497, rn_mu2=1.109e-05)
Calculates the insitu density of NEMO’s simplified equation of state (seos)
Parameters
- S: float
Salinity variable With seos, there is no distinction between Absolute and Practical Salinity
- T: float
Temperature variable With seos, there is no distinction between Conservative and Potential Temperature
- Z: float
Depth in metres
- rn_a0: float (optional, default = 1.655e-1)
seos parameter - Linear thermal expansion coefficient
- rn_b0: float (optional, default = 7.655e-1)
seos parameter - Linear haline expansion coefficient
- rn_nu: float (optional, default = 2.4341e-3)
seos parameter - Cabbeling coefficient for T*S
- rn_lambda1: float (optional, default = 5.9520e-2)
seos parameter - Cabbeling coefficient for T^2
- rn_lambda2: float (optional, default = 7.4914e-4)
seos parameter - Cabbeling coefficient for S^2
- rn_mu1: float (optional, default = 1.4970e-4)
seos parameter - Thermobaric coefficient for T
- rn_mu2: float (optional, default = 1.1090e-5)
seos parameter - Thermobaric coefficient for S
Returns
- rhofloat
The in-situ density [kg/m3]
- eos.calc_seos_s_t(S, T, Z, rn_a0=0.1655, rn_b0=0.7655, rn_nu=0.0024341, rn_lambda1=0.05952, rn_lambda2=0.00074914, rn_mu1=0.0001497, rn_mu2=1.109e-05)
Calculates the partial derivatives wrt S and T for NEMO’s simplified equation of state (seos, in-situ density).
Parameters
- S: float
Salinity variable With seos, there is no distinction between Absolute and Practical Salinity
- T: float
Temperature variable With seos, there is no distinction between Conservative and Potential Temperature
- Z: float
Depth in metres
- rn_a0: float (optional, default = 1.655e-1)
seos parameter - Linear thermal expansion coefficient
- rn_b0: float (optional, default = 7.655e-1)
seos parameter - Linear haline expansion coefficient
- rn_nu: float (optional, default = 2.4341e-3)
seos parameter - Cabbeling coefficient for T*S
- rn_lambda1: float (optional, default = 5.9520e-2)
seos parameter - Cabbeling coefficient for T^2
- rn_lambda2: float (optional, default = 7.4914e-4)
seos parameter - Cabbeling coefficient for S^2
- rn_mu1: float (optional, default = 1.4970e-4)
seos parameter - Thermobaric coefficient for T
- rn_mu2: float (optional, default = 1.1090e-5)
seos parameter - Thermobaric coefficient for S
Returns
- beta, alphatuple
Tuple of floats describing the derivate wrt salinity (beta) and temperature (alpha)
- eos.calc_eos(S, T, Z, eos_name)
Calculates the insitu density for either the TEOS10 or EOS80 equation of state.
Parameters
- S: float
Salinity variable if eos_name = ‘teos10’ -> Use Absolute Salinity if eos_name = ‘eos80’ -> Use Practical Salinity
- T: float
Temperature variable if eos_name = ‘teos10’ -> Use Conservative Temperature if eos_name = ‘eos80’ -> Use Potential Temperature
- Z: float
Depth in metres
- eos_name: String
Name of the desired equation of state in NEMO = ‘teos10’ -> the polyTEOS-10-bsq equation of seawater (Roquet et al. 2015) = ‘eos80’ -> the polyEOS80-bsq equation of seawater
All equations use the default parameters used in the NEMO source code (as of v4.0.7). Namelist parameters for the simplified equation of state can be set with the keyword arguments below.
Returns
- rhofloat
The in-situ density [kg/m3]
- eos.calc_eos_s_t(S, T, Z, eos_name)
Calculates the partial derivatives wrt S and T for either the TEOS10 or EOS80 equation of state (in-situ density).
Parameters
- S: float
Salinity variable if eos_name = ‘teos10’ -> Use Absolute Salinity if eos_name = ‘eos80’ -> Use Practical Salinity
- T: float
Temperature variable if eos_name = ‘teos10’ -> Use Conservative Temperature if eos_name = ‘eos80’ -> Use Potential Temperature
- Z: float
Depth in metres
- eos_name: String
Name of the desired equation of state in NEMO = ‘teos10’ -> the polyTEOS-10-bsq equation of seawater (Roquet et al. 2015) = ‘eos80’ -> the polyEOS80-bsq equation of seawater
All equations use the default parameters used in the NEMO source code (as of v4.0.7). Namelist parameters for the simplified equation of state can be set with the keyword arguments below.
Returns
- beta, alphatuple
Tuple of floats describing the derivate wrt salinity (beta) and temperature (alpha)