Usage

Installation

neutralNEMO can be installed using conda

(.venv) $ conda install -c conda-forge neutralNEMO

alternatively, neutralNEMO can be installed through pip

(.venv) $ pip install neutralNEMO

Example of use

First, we will use the load_hgridata and load_zgriddata routines to load the necessary data from the model grid file (typically a mesh_mask or domaincfg file)

from neutralNEMO.grid import load_hgriddata, load_zgriddata

hgd = load_hgriddata( "/path/to/file/mesh_mask.nc" )
zgd = load_zgriddata( "/path/to/file/mesh_mask.nc" )

hgd and zgd are dictionaries containing cell widths, cell thicknesses and T-point masks contained within mesh_mask.nc. The netcdf variable names for these terms can vary between datasets and can be adjusted accordinly using keyword arguments. For example:

hgd = load_hgriddata( "/path/to/file/mesh_mask.nc" , e1u_varname="e1u_0")

A complete list of the available keyword arguments can be found in the Public Function Reference.

We then need to create a neutralocean grid object. This can be simply done using the build_nemo_hgrid routine

from neutralNEMO.grid import build_nemo_hgrid

neutral_grid = build_nemo_hgrid( hgd, iperio=False, jperio = False)

The iperio and jperio keyword arguments specify the periodicity of the model domain. For example, if iperio = True then the model is periodic in the i-direction (this is the case for a global configuration).

The last step before calculating our neutral surface is the loading of the temperature and salinity data.

from neutralNEMO.surf import load_tsdata

tsd = load_tsdata( "/path/to/file/NEMO_grid-T.nc", to_varname="temperature" )

As shown above, the specific netcdf variable name can be specified as a keyword argument.

Now we have our temperature and grid information we can finally calculate our neutral surface.

from neutralNEMO.surf import find_omega_surfs

zpins = [150., 300.]   # List of depths to pin each surface to
ipins = [10, 10]       # List of i-indices to pin each surface to
jpins = [9, 9]         # List of j-indices to pin each surface to
tpins = [-1,-1]        # List of time indices to pin each surface to

surf_dataset = find_omega_surfs( tsd, neutral_grid , zgd, [150., 300.], [10,10], [9,9], [-1,-1],
                                      eos="gsw", ITER_MAX=10, calc_veronis=True)

#Save as netcdf (optional)
surf_dataset.to_netcdf("my_surfs.nc")

In the above example, two neutral surfaces are calculated. The first surface is pinned to 150 m depth at (i=9, j=9) in the final time step. The second surface is the same but pinned to 300 m depth. The surfaces depths, temperatures, and salinities are outputted as an xarray DataSet and can be easilly saved to netcdf.

To calculate the initial potential density, the equation of state needs to be known. In this case, the gsw equation of state is adopted (see neutralocean documentation for specifics on the equation of state.)

ITER_MAX=10 sets the maximum number of iterations carried out by the neutralocean algorithm.

calc_veronis=True, enables the calculation of the Veronis density as a label for the density surfaces.