bathyutils module

gridtools.bathyutils.applyExistingLandmask(grd, dsData, dsVariable, maskFile, maskVariable, **kwargs)

Modify a given bathymetry using a specified land mask.

Parameters

grd (GridUtils) – class object
dsData (xarray) – data source data object
dsVariable (string) – data source variable name
maskFile (string) – filename
maskVariable (string) – variable name in maskFile
**kwargs – See below

Keyword arguments:

epsilon (float) – When a point is declared an ocean point, if the depth is shallower than the masking depth, the depth is set to the minimum depth. If the masking depth is undefined or equal to the minimum depth, the new depth is set deeper by epsilon to avoid becoming masked as land. Default: 1.0e-14

MINIMUM_DEPTH (float) – Minimum ocean depth. Default: 0.0

MASKING_DEPTH (float) – Ocean depths equal or shallower than the masking depth are masked as land. Default: undefined

MAXIMUM_DEPTH (float) – Maximum depth of the ocean. Defaults to maximum depth from data source if not specified.

TOPO_EDITS_FILE (string) – Changed mask points in the MOM6 zEdits format will be recorded to the specified filename. (Unimplemented)

Note

For ocean points, if a depth is shallower than the MINIMUM_DEPTH but deeper than the MASKING_DEPTH, the depth will be set to the MINIMUM_DEPTH.

Ocean points that are to become land will be set to the MASKING_DEPTH. If MASKING_DEPTH is not defined, MINIMUM_DEPTH is used as the masking depth.

gridtools.bathyutils.applyExistingOceanmask(grd, dsData, dsVariable, maskFile, maskVariable, **kwargs)

Modify a given bathymetry using a specified ocean mask.

Parameters

grd (GridUtils) – class object
dsData (xarray) – data source data object
dsVariable (string) – data source variable name
maskFile (string) – filename
maskVariable (string) – variable name in maskFile
**kwargs – See below

Keyword arguments:

epsilon (float) – When a point is declared an ocean point, if the depth is shallower than the masking depth, the depth is set to the minimum depth. If the masking depth is undefined or equal to the minimum depth, the new depth is set deeper by epsilon to avoid becoming masked as land. Default: 1.0e-14

MINIMUM_DEPTH (float) – Minimum ocean depth. Default: 0.0

MASKING_DEPTH (float) – Ocean depths equal or shallower than the masking depth are masked as land. Default: undefined

MAXIMUM_DEPTH (float) – Maximum depth of the ocean. Defaults to maximum depth from data source if not specified.

TOPO_EDITS_FILE (string) – Changed mask points in the MOM6 zEdits format will be recorded to the specified filename. (Unimplemented)

Note

For ocean points, if a depth is shallower than the MINIMUM_DEPTH but deeper than the MASKING_DEPTH, the depth will be set to the MINIMUM_DEPTH.

Ocean points that are to become land will be set to the MASKING_DEPTH. If MASKING_DEPTH is not defined, MINIMUM_DEPTH is used as the masking depth.

gridtools.bathyutils.break_array_to_blocks(a, xb=4, yb=1, useOverlap=False, useSupergrid=False)

gridtools.bathyutils.computeBathymetricRoughness(grd, dsName, **kwargs)

This generates h2 and other variables and returns an xarray DataSet.

Parameters

grd (GridUtils) – class object
dsName (string) – data source name
**kwargs – See below

Keyword arguments:

maxMb (int) – Memory limit for grid refinements. Default: 8000.0

h2Name (string) – The computed bathymetric roughness grid name. Default: h2

depthName (string) – The bathymetry grid name to use from data source. Default: depth

gridPoint (string) – Grid placement of bathymetric roughness values. See below. Default: h

auxVariables (list) – Specify additional variables to include with bathymetric roughness. See below. Default: []

superGrid (boolean) – If True, the bathymetric roughness grid returned is a supergrid. Otherwise, the ocean roughness is the same size as the current grid. Default: False

useClipping (boolean) – Use True if the current grid is periodic and should be clipped prior to computing the bathymetric roughness. Defualt: False

useFixByOverlapQHGridShift (boolean) – When using a regular grid, use overlapping grid technique to fill in partition boundaries. See IMPLEMENTATION NOTES below. Default: True

useQHGridShift (boolean) – For a regular grid, use the Q point values as the H values to fill missing points.

useOverlap (boolean) – Use overlapping grid technique to fill in partition boundaries. The outer column and row will still be missing.

extendedGrid (boolean) – If True, the grid provided by this routine has been extended and should use the overlap technique on h-points only and not q-points which are then shifted back to h-points. See IMPLEMENTATION NOTES below. Default: False

This routine is based on a paper by Adcroft [Adc03] and python code from OMtopogen/create_topog_refinedSampling.py [Zad20b].

Note

maxMB

The memory limit for successive grid refinements. This should be maximized for the memory footprint of the compute node. If the program crashes, use lower amounts of memory.

auxVariables

h_std, h_min, h_max, and height variables. Ask for one or more additional variables by python list [] to auxVariables. Default is an empty list: []

gridPoint

By default, this generates bathymetric roughness grids on Arakawa C h-points but may be specified via gridPoint.

For gridPoint, a diagram of a grid cells is:

q-----v-----q
|           |
u     h     u
|           |
q-----v-----q

Valid values for gridPoint are:

‘h’ h-point; grid center
‘q’ q-point; grid corners
‘uv’ u- and v-point; grid faces

superGrid

If you want all supergrid points, set superGrid=True. Setting tells this routine to use the supergrid when calculating the bathymetric roughness. This will require more RAM. Default: False

IMPLEMENTATION NOTES:

For the supergrid, four zero bands along longitude are returned representing the four grid partitions. This needs to be fixed in the future.
useFixByOverlapQHGridShift by default is True. Roughness (h2) is diagnosed on the q-points and shifted by 1/2 a grid cell back to the h-points. Accuracy of the roughness and other resultant variables are off by a 1/2 grid cell. This only works for the regular grid, not the supergrid. If the grid is extended, setting extendedGrid to True, tells this routine to attempt to diagnose h2 on the h-points without shifting the grid. The extended grid should be extended by two grid points on the supergrid.
Support for ‘q’ and ‘uv’ grid points are not supported.
If the program is running out of memory, reduce the maxMb value. This reduces the available memory footprint available to this routine. This will also reduce the number of available refinements against the bathymetry data source.

gridtools.bathyutils.do_block(grd, part, lon, lat, topo_lons, topo_lats, topo_elvs, max_mb=500)

gridtools.bathyutils.extend_by_zeros(x, shape)

gridtools.bathyutils.get_indices1D(lon_grid, lat_grid, x, y): This function returns the j,i indices for the grid point closest to the input lon,lat coordinates.

gridtools.bathyutils.get_indices1D_old(lon_grid, lat_grid, x, y): This function returns the j,i indices for the grid point closest to the input lon,lat coordinates.

gridtools.bathyutils.get_indices2D(lon_grid, lat_grid, x, y): This function returns the j,i indices for the grid point closest to the input lon,lat coordinates.

gridtools.bathyutils.ice9(grd, **kwargs)

This is a implementation of the ice-9 algorithm for filling in disconnected ocean bodies (lakes) for a given ocean grid. Be sure to specify anticipated MINIMUM_DEPTH, MASKING_DEPTH and MAXIMUM_DEPTH that will be used for the model run.

Parameters

grd (GridUtils) – class object
**kwargs – See below

Keyword arguments:

ocean_seeds ([(int, int)]) – Provide ice-9 algorithm with one or more (j,i) ocean body grid points to designate as areas that should be treated as areas of continuous ocean points. If more than one seed is given, all the discovered wet points will be merged together to form the final grid minus any detached ocean points (lakes). NOTE: Only the first seed is used! Future releases will allow multiple seeds.

depth (grid) – The depth grid to use for ice-9 algorithm. This should be the same size as the provided latitude and logitude points defining the grid. Values are positive for depth (water) and negative for height (land).

periodic (boolean) – Tells the algorithm that the grid is periodic and should check wrap points. Default: False NOTE: Not implemented!

returnFields (list) – List of fields to be returned in the grd object. Default: [‘wetMask’]

MINIMUM_DEPTH (float) – minimum depth of ocean in meters. Default: 0.0

MASKING_DEPTH (float) – masking depth of ocean in meters. Default: 0.0

MAXIMUM_DEPTH (float) – maximum depth of ocean in meters. Default: -99999.0

zEdits (boolean) – Utilize zEdits for the provided depth field. Store any updates to the depth field in zEdits as well. Default: False NOTE: Not implemented!

The ice-9 algorithm was first mentioned in a program written by Niki Zadeh in the ocean_model_topog_generator repository. [Zad20b]

Another reference to the ice-9 algorithm is metioned in the repository regrid_runoff by Alistair Adcroft. [Adc20].

gridtools.bathyutils.mdist(x1, x2): Returns positive distance modulo 360.

gridtools.bathyutils.refine_by_repeat(x, rf)

gridtools.bathyutils.undo_break_array_to_blocks(a, xb=4, yb=1, useOverlap=False, extendedGrid=False, useSupergrid=False, useQHGridShift=False)