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([cime_tag])

Parse relevant constants from CIME