pylag.grid_metrics module

The grid metrics module exists to assist with the creation of PyLag grid metrics files.

pylag.grid_metrics.create_arakawa_a_grid_metrics_file(file_name, lon_var_name='longitude', lat_var_name='latitude', depth_var_name='depth', mask_var_name=None, reference_var_name=None, bathymetry_var_name=None, dim_names=None, is_global=False, surface_only=False, save_mask=True, prng_seed=10, masked_vertices_per_element=0, central_latitude: Optional[int] = 0.0, grid_metrics_file_name='./grid_metrics.nc')

Create a Arakawa A-grid metrics file

This function creates a grid metrics file for data defined on a regular rectilinear Arakawa A-grid. The approach taken is to reinterpret the regular grid as a single, unstructured grid which can be understood by PyLag.

The unstructured grid can be created in one of two ways. The first is by using the python package scipy to create a Delaunay triangulation. The second uses the python package stripy to create the triangulation. The two methods are tied to different applications. The first method should be used when creating a triangulation of a regional grid. The second method should be used when creating a triangulation of a global grid. The choice is made through the optional argument is_global. Two different methods are used since they offer significant advantages over each other in the two target applications.

We use stripy to create a spherical triangulation on the surface of the Earth in the global use case. In the version tested (stripy 2.02), stripy requires that the first three lat/lon points don’t lie on a Great Circle. As this will typically be the case with regularly gridded data, we must permute the lat and lon arrays. To achieve this we use NumPy to shuffle array indices. These shuffled indices are used to permute data arrays. The shuffled indices are also saved as an extra variable in the grid metrics file so that the same shuffling can be applied to the time dependent variable arrays when PyLag is running. To make the operation reproducible, a fixed seed is used for the PRNG. The seed can be specified using the optional argument prng.

If surface_only is set to True, only 2D surface grid data is extracted and saved. Currently, it is assumed the 0 index corresponds to the ocean’s surface.

If save_mask is set to False, the node and element mask is not saved. This option can be used when creating the grid metrics files for fields where the land-sea mask is not used (e.g. atmospheric winds, waves).

Parameters

  • file_name (str) – The path to an file that can be read in a processed

  • lon_var_name (str, optional) – The name of the longitude variable. Optional, default : ‘longitude’

  • lat_var_name (str, optional) – The name of the latitude variable. Optional, default : ‘latitude’

  • depth_var_name (str, optional) – The name of the depth variable. Optional, default : ‘depth’

  • mask_var_name (str, optional) – The name of the mask variable which will be used to generate the land sea mask. If None, the land sea mask is inferred from the surface mask of reference_var_name, which becomes obligatory if mask_var_name is None. If the output files contain a time varying mask due to changes in sea surface elevation, a land sea mask should be provided. Optional, default : None.

  • reference_var_name (str, optional) – The name of the reference variable from which to infer the land sea mask if mask_var_name is None. Must be given if mask_var_name is None. Optional, default : None.

  • bathymetry_var_name (str, optional) – Bathymetry variable name. If None, the bathymetry is inferred from the depth mask of reference_var_name. If the output files contain a time varying mask due to changes in sea surface elevation, the bathymetry should be provided. Optional, default : None.

  • dim_names (dict, optional) – Dictionary of dimension names. The dictionary should be used to specify dimension names if they are different to the standard names: ‘time’, ‘depth’, ‘latitude’, ‘longitude’. The above strings should be used for the dimension dictionary keys. For example, to specify a longitude dimension name of ‘lon’, pass in the dictionary: dim_names = {‘longitude’: ‘lon’}.

  • is_global (bool, optional) – Boolean flag signifying whether or not the input grid should be treated as a global grid. If True, the python package stripy is used to create a global triangulation. If False, a Delaunay triangulation is created using scipy. To reflect typical PyLag use cases, the flag is optional with a default value of False. Optional, default : False.

  • surface_only (bool, optional) – If False, process depth and bathymetry. If True, only process variables specific to the horizontal grid. Set to False if you want to do 3D transport modelling, and True if you want to do 2D surface only transport modeling. Optional, default : False.

  • save_mask (bool, optional) – If False, don’t include an element or node mask. Can be used if creating surface wind and wave grid metrics files, where the mask is not read. Optional, default: True.

  • prng_seed (int, optional) – Seed for the pseudo random number generator.

  • masked_vertices_per_element (int, optional) – Number of masked vertices allowed within an element. Such elements may occur along the boundary. If masked vertices are allowed, the model will ignore these when interpolating within the element. Optional, default : 0.

  • central_latitude (int) – The central latitude of the FVCOM grid. If the latitudes in the output file are in the range 0 to 180, then this should be set to 90 degrees. PyLag will then automatically convert the latitudes to the range -90 to 90 degrees. Other types of latitude/longitude grids are not supported. Optional, default: 0.

  • grid_metrics_file_name (str, optional) – The name of the grid metrics file that will be created. Optional, default : grid_metrics.nc.

Note

This function only needs to be called once per model grid - the grid metrics file generated can be reused by all future simulations.

pylag.grid_metrics.create_fvcom_grid_metrics_file(str fvcom_file_name: str, dimension_names: Optional[dict] = {}, variable_names: Optional[dict] = {}, obc_file_name: Optional[str] = None, obc_file_delimiter: Optional[str] = ' ', central_latitude: Optional[int] = 0.0, grid_metrics_file_name: Optional[str] = './grid_metrics.nc')

Create FVCOM grid metrics file

This function creates a FVCOM grid metrics file for use with PyLag given a FVCOM output file.

At a minimum, the FVCOM output file must contain the following dimension variables for 3D runs:

time - the number of time points, node - the number of nodes in the unstructured horizontal triangular mesh, nele - the number of elements in the unstructured horizontal triangular mesh, siglay - the number of sigma layers.

and the following variables:

Itime and Itime2 - time variables, x, y and/or lon, lat - nodal coordinates, xc, yc and/or lonc, latc - element centre coordinates, nv - nodes surrounding each element, siglay - sigma coordinates of layer centres, h - bathymetry, zeta - sea surface elevation, u, v - lateral velocity components, ww - vertical velocity component.

NB zeta and the velocity components are not required to generate the grid metrics file.

If the FVCOM output file contains non-standard names for the dimensions or variables, these can be specified using the optional dimension_names and variable_names arguments. The above default names will be adopted for any dimensions or variables not specified in these dictionaries.

PyLag expects longitudes to be in the range -180 to 180 degrees. If the longitudes in the FVCOM output file are in the range 0 to 360, then this will be automatically detected and the longitudes will be converted to the range -180 to 180 degrees. The central longitude of the FVCOM longitude variable must be 0 degrees. Similarly, PyLag expects latitudes to be in the range -90 to 90 degrees. If the latitudes in the FVCOM output file are in the range 0 to 180, then this can be specified using the optional central_latitude argument, which should be set to 90 degrees in this scenario. PyLag will then automatically convert the latitudes to the range -90 to 90 degrees. Other types of latitude/longitude grids are not supported.

In FVCOM output files, the grid variables nv and nbe are odered in the opposite direction to what PyLag requires. These variables are reordered here before being written to the grid metrics file.

If the siglev variable is missing, then it will be estimated through a combination of linear interpolation and extrapolation using the siglay variable, which is mandatory.

FVCOM does not distinguish between open and land boundary nodes - all sides lying along a boundary are simply given a -1 flag. To distinguish between open and land boundaries, a list of open boundary nodes can be specified using the optional obc_file_name argument. Nominally, this file is the same as that used in the original FVCOM run. Given this information, PyLag will flag all open boundary nodes with a distinct -2 flag. If the obc_file_name argument is not given, all boundary nodes will be given a -1 flag.

Parameters

  • fvcom_file_name (str) – The path to an FVCOM output file for the domain of interest.

  • dimension_names (dict) – A dictionary containing the names of the dimensions in the FVCOM output file. Supported keys include: node, nele, siglay, siglev. The values should be the name of the corresponding dimensions in the FVCOM output file. Default FVCOM names will be tried if a given key/value pair are not provided, or the dictionary itself is not given. The dimensions node, element and siglay are mandatory, and must be present within the FVCOM output file. If siglev is not given, the model will estimate values for siglev through interpolation. Optional, default: {}.

  • variables_names (dict) – A dictionary containing the names of the variables in the FVCOM output file. Supported keys include: Itime, Itime2, x, y, lon, lat, xc, yc, lonc, latc, nv, nbe, siglay, siglev, h. The values should be the name of the corresponding variables in the FVCOM output file. Default FVCOM names will be tried if a given key/value pair are not provided, or the dictionary itself is not given. Optional, default: {}.

  • obc_file_name (str) – The path to the text file containing a list of open boundary nodes, as read in by FVCOM. If the file is not provided, all boundaries will be treated as land boundaries. Optional, default: None.

  • obc_file_delimiter (str) – The delimiter used in the obc ascii file. To specify a tab delimited file, set this equal to ‘ ‘. Default: ‘ ‘.

  • central_latitude (int) – The central latitude of the FVCOM grid. If the latitudes in the FVCOM output file are in the range 0 to 180, then this should be set to 90 degrees. PyLag will then automatically convert the latitudes to the range -90 to 90 degrees. Other types of latitude/longitude grids are not supported. Optional, default: 0.

  • grid_metrics_file_name (str, optional) – The name of the grid metrics file that will be created

Note

This function only needs to be called once per model grid - the grid metrics file generated can be reused by all future simulations.

Todo

1) Add support for creating a grid based on surface values only.