API reference¶

This page provides an auto-generated summary of the MPAS mesh-tools API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

MPAS mesh tools¶

Mesh creation¶

make_planar_hex_mesh(nx, ny, dc, …[, …])

Builds an MPAS periodic, planar hexagonal mesh with the requested dimensions, optionally saving it to a file, and returns it as an xarray.Dataset.

`build_mesh`
`build_mesh.build_spherical_mesh`(cellWidth, …)	Build an MPAS mesh using JIGSAW with the given cell sizes as a function of latitude and longitude.
`build_mesh.build_planar_mesh`(cellWidth, x, …)	Build a planar MPAS mesh
`jigsaw_driver.jigsaw_driver`(cellWidth, x, y)	A function for building a jigsaw mesh
`jigsaw_to_netcdf.jigsaw_to_netcdf`(…[, …])	Converts mesh data defined in triangle format to NetCDF
`mesh_definition_tools`	These functions are tools used to define the `cellWidth` variable on regular lat/lon grids.
`mesh_definition_tools.mergeCellWidthVsLat`(…)	Combine two cell width distributions using a `tanh` function.
`mesh_definition_tools.EC_CellWidthVsLat`(lat)	Create Eddy Closure spacing as a function of lat.
`mesh_definition_tools.RRS_CellWidthVsLat`(…)	Create Rossby Radius Scaling as a function of lat.
`mesh_definition_tools.AtlanticPacificGrid`(…)	Combine two cell width distributions using a `tanh` function.
`mpas_to_triangle.mpas_to_triangle`(mpasfile, …)	Script to convert from MPAS netCDF format to the Triangle format: https://www.cs.cmu.edu/~quake/triangle.node.html https://www.cs.cmu.edu/~quake/triangle.ele.html
`signed_distance`
`signed_distance.signed_distance_from_geojson`(fc, …)	Get the distance for each point on a lon/lat grid from the closest point on the boundary of the geojson regions.
`signed_distance.mask_from_geojson`(fc, …)	Make a rasterized mask on a lon/lat grid from shapes (geojson multipolygon data).
`signed_distance.distance_from_geojson`(fc, …)	Get the distance for each point on a lon/lat grid from the closest point on the boundary of the geojson regions.
`triangle_to_netcdf.triangle_to_netcdf`(node, …)	Converts mesh data defined in triangle format to NetCDF

Mesh conversion¶

`convert`(dsIn[, graphInfoFileName, logger, dir])	Use `MpasMeshConverter.x` to convert an input mesh to a valid MPAS mesh that is fully compliant with the MPAS mesh specification.
`cull`(dsIn[, dsMask, dsInverse, dsPreserve, …])	Use `MpasCellCuller.x` to cull cells from a mesh based on the `cullCell` field in the input file or DataSet and/or the provided masks.
`mask`(dsMesh[, fcMask, fcSeed, logger, dir])	Use `MpasMaskCreator.x` to create a set of region masks either from mask feature collections or from seed points to be used to flood fill

`compute_mpas_region_masks`(dsMesh, fcMask[, …])	Use shapely and processes to create a set of masks from a feature collection made up of regions (polygons)
`compute_mpas_transect_masks`(dsMesh, fcMask, …)	Use shapely and processes to create a set of masks from a feature collection made up of transects (line strings)
`compute_mpas_flood_fill_mask`(dsMesh, fcSeed)	Flood fill from the given set of seed points to create a contiguous mask.
`compute_lon_lat_region_masks`(lon, lat, fcMask)	Use shapely and processes to create a set of masks from a feature collection made up of regions (polygons) on a tensor lon/lat grid

merge_grids([infile1, infile2, outfile, runner])

Merges two MPAS non-contiguous meshes together into a single file

split_grids([infile, outfile1, outfile2, …])

Split two previously merged MPAS non-contiguous meshes together into separate files.

`translate`(mesh[, xOffset, yOffset])	Translates the coordinate system of the planar MPAS mesh by an arbitrary shift in x and/or y
`center`(mesh)	Translates the coordinate system of the planar MPAS mesh by shifting the origin to the center of the domain
`center_on_mesh`(mesh, otherMesh)	Translates the coordinate system of the planar MPAS mesh by shifting the origin to the center of the domain described in a separate mesh

scrip_from_mpas(mpasFile, scripFile[, …])

Create a SCRIP file from an MPAS mesh

I/O¶

write_netcdf(ds, fileName[, fillValues, …])

Write an xarray.Dataset to a file with NetCDF4 fill values and the given name of the string dimension.

Parallelism¶

create_pool([process_count, method])

Crate a pool for creating masks with Python multiprocessing.

Interpolation¶

interp_bilin(x, y, field, xCell, yCell)

Perform bilinear interpolation of field on a tensor grid to cell centers on an MPAS mesh.

CIME constants¶

constants

Ocean Tools¶

`coastline_alteration`
`coastline_alteration.add_critical_land_blockages`(…)	Add the masks associated with one or more transects to the land mask
`coastline_alteration.widen_transect_edge_masks`(…)	Alter critical passages at polar latitudes to be at least two cells wide, to avoid sea ice blockage
`coastline_alteration.add_land_locked_cells_to_mask`(…)	Find ocean cells that are land-locked, and alter the cell mask so that they are counted as land cells.
`moc`
`moc.make_moc_basins_and_transects`(gf, …[, …])	Builds features defining the ocean basins and southern transects used in computing the meridional overturning circulation (MOC)
`moc.add_moc_southern_boundary_transects`(…)	param dsMask Region masks defining MOC basins
`build_mesh`
`build_mesh.build_spherical_mesh`(cellWidth, …)	Build an MPAS mesh using JIGSAW with the given cell sizes as a function of latitude and longitude
`build_mesh.build_planar_mesh`(cellWidth, x, …)	Build a planar MPAS mesh
`coastal_tools`	name: coastal_tools authors: Steven Brus
`coastal_tools.coastal_refined_mesh`(params[, …])	Optionally create a background field of cell widths, then add a region of refined resolution to the cell widths.
`coastal_tools.create_background_mesh`(…[, …])	Create a background field of cell widths
`coastal_tools.extract_coastlines`(nc_file, …)	Extracts a set of coastline contours
`coastal_tools.distance_to_coast`(coastlines, …)	Extracts a set of coastline contours
`coastal_tools.compute_cell_width`(D, …[, …])	Blend cell widths from the input field with the new resolution in the refined region determined by the distance to the coastline contour.
`coastal_tools.save_matfile`(cell_width, lon, lat)
`coastal_tools.CPP_projection`(lon, lat, origin)
`coastal_tools.smooth_coastline`(x, y, window)
`coastal_tools.get_data_inside_box`(lon, lat, …)
`coastal_tools.get_indices_inside_quad`(lon, …)
`coastal_tools.get_convex_hull_coordinates`(box)
`coastal_tools.plot_coarse_coast`(ax, plot_box)
`coastal_tools.plot_region_box`(box, color)
`depth.add_depth`(inFileName, outFileName[, …])	Add a 1D depth coordinate to an MPAS-Ocean file.
`depth.add_zmid`(inFileName, outFileName[, …])	Add a 3D, time-independent depth coordinate to an MPAS-Ocean file.
`depth.write_time_varying_zmid`(inFileName, …)	Add a 3D, time-independent depth coordinate to an MPAS-Ocean file.
`depth.compute_depth`(refBottomDepth)	Computes depth and depth bounds given refBottomDepth
`depth.compute_zmid`(bottomDepth, …[, depth_dim])	Computes zMid given data arrays for bottomDepth, maxLevelCell and layerThickness

inject_bathymetry(mesh_file)

`inject_meshDensity_from_file`(cw_filename, …)	Add a `meshDensity` field into an MPAS mesh.
`inject_spherical_meshDensity`(cellWidth, lon, …)	Add a `meshDensity` field into a spherical MPAS mesh.
`inject_planar_meshDensity`(cellWidth, x, y, …)	Add a `meshDensity` field into a planar MPAS mesh.

inject_preserve_floodplain(mesh_file, …)

`find_transect_levels_and_weights`(dsTransect, …)	Construct a vertical coordinate for a transect produced by `mpas_tools.viz.transects.find_transect_cells_and_weights()`, then break each resulting quadrilateral into 2 triangles that can later be visualized with functions like `tripcolor` and `tricontourf`.
`interp_mpas_to_transect_triangles`(…)	Interpolate a 3D (`nCells` by `nVertLevels`) MPAS-Ocean DataArray to transect nodes with constant values in each MPAS cell
`interp_mpas_to_transect_triangle_nodes`(…)	Interpolate a 3D (`nCells` by `nVertLevels`) MPAS-Ocean DataArray to transect nodes, linearly interpolating fields between the closest neighboring cells
`interp_transect_grid_to_transect_triangle_nodes`(…)	Interpolate a DataArray on the original transect grid to triangle nodes on the MPAS-Ocean transect.
`get_outline_segments`(dsTransectTriangles[, …])	Get a set of line segments that outline the given transect

Logging¶

`check_call`(args, logger)	Call the given subprocess with logging to the given logger.
`LoggingContext`(name[, logger, log_filename])	A context manager for creating a logger or using an existing logger

Transects¶

`subdivide_great_circle`(x, y, z, maxRes, …)	Subdivide each segment of the transect so the horizontal resolution approximately matches the requested resolution
`cartesian_to_great_circle_distance`(x, y, z, …)	Cartesian transect points to great-circle distance
`subdivide_planar`(x, y, maxRes)	Subdivide each segment of the transect so the horizontal resolution approximately matches the requested resolution
`lon_lat_to_cartesian`(lon, lat, earth_radius, …)	Convert from lon/lat to Cartesian x, y, z
`cartesian_to_lon_lat`(x, y, z, earth_radius, …)	Convert from Cartesian x, y, z to lon/lat
`angular_distance`([x, y, z, first, second])	Compute angular distance between points on the sphere, following: https://en.wikipedia.org/wiki/Great-circle_distance
`intersects`(a1, a2, b1, b2)	Based on https://stackoverflow.com/a/26669130/7728169 Determine if the great circle arc from `a1` to `a2` intersects that from `b1` to `b2`.
`intersection`(a1, a2, b1, b2)	Based on https://stackoverflow.com/a/26669130/7728169 Find the intersection point between great circle arc from `a1` to `a2` and from `b1` to `b2`.
`Vector`(x, y, z)	A class for representing Cartesian vectors with `x`, `y` and `z` components that are either `float` or `numpy.array` objects of identical size.

Visualization¶

extract_vtk(filename_pattern[, …])

Extract fields from a time series of NetCDF files as VTK files for plotting in ParaView.

mesh_to_triangles(dsMesh[, periodicCopy])

Construct a dataset in which each MPAS cell is divided into the triangles connecting pairs of adjacent vertices to cell centers.

`make_triangle_tree`(dsTris)	Make a KD-Tree for finding triangle edges that are near enough to transect segments that they might intersect
`find_transect_cells_and_weights`(lonTransect, …)	Find “nodes” where the transect intersects the edges of the triangles that make up MPAS cells.
`find_planar_transect_cells_and_weights`(…)	Find “nodes” where the transect intersects the edges of the triangles that make up MPAS cells.

register_sci_viz_colormaps()

Register all SciVisColor colormaps with matplotlib

Tests¶

test_cime_constants([e3sm_tag])

Parse relevant constants from CIME