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, logger, dir, cores])	Use compute_mpas_region_masks to create a set of region masks either from mask feature collections

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

Config

MpasConfigParser()	A "meta" config parser that keeps a dictionary of config parsers and their sources to combine when needed.
MpasConfigParser.add_user_config(filename)	Add a the contents of a user config file to the parser.
MpasConfigParser.add_from_file(filename)	Add the contents of a config file to the parser.
MpasConfigParser.add_from_package(package, ...)	Add the contents of a config file to the parser.
MpasConfigParser.get(section, option)	Get an option value for a given section.
MpasConfigParser.getint(section, option)	Get an option integer value for a given section.
MpasConfigParser.getfloat(section, option)	Get an option float value for a given section.
MpasConfigParser.getboolean(section, option)	Get an option boolean value for a given section.
MpasConfigParser.getlist(section, option[, ...])	Get an option value as a list for a given section.
MpasConfigParser.getexpression(section, option)	Get an option as an expression (typically a list, though tuples and dicts are also available).
MpasConfigParser.has_section(section)	Whether the given section is part of the config
MpasConfigParser.has_option(section, option)	Whether the given section has the given option
MpasConfigParser.set(section, option[, ...])	Set the value of the given option in the given section. The file from
MpasConfigParser.write(fp[, ...])	Write the config options to the given file pointer.
MpasConfigParser.copy()	Get a deep copy of the config parser
MpasConfigParser.__getitem__(section)	Get get the config options for a given section.

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(...)
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

plot_ocean_transects(fc, ds[, ds_mesh, ...])	Plot images of the given variables on the given transects.
add_inset(fig, fc[, latlonbuffer, ...])	Plots an inset map showing the location of a transect or polygon.

Sea-ice Tools

extend_seaice_mask(filenameMesh, ...[, ...])

Add a field icePresenceExtended to filenamePresence if it doesn't already exist.

write_scrip_file(scripFilename, title, ...)	A low-level function for writing a SCRIP file for the given MPAS-Seaice mesh
write_2D_scripfile(filenameScripOut, ...[, ...])	Write a SCRIP file for the given 2D grid
make_mpas_scripfile_on_cells(meshFilename, ...)	Write a SCRIP file for cel quantities on the given MPAS-Seaice mesh
make_mpas_scripfile_on_vertices(...)	Write a SCRIP file for vertex quantities on the given MPAS-Seaice mesh

gen_seaice_mesh_partition(meshFilename, ...)	Generate graph partition(s) for the given MPAS-Seaice mesh and the given number(s) of processors and a file defining regions that each processor should own part of (typically a polar region and an equatorial region)
prepare_partitions()	An entry point for performing preparatory work for making seaice partitions
create_partitions()	An entry point for creating sea-ice partitions

make_regions_file(filenameIcePresent, ...)

regrid_to_other_mesh(meshFilenameSrc, ...[, ...])

Logging

check_call(args[, logger, log_command, timeout])	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)	Compute angular distance between points on the sphere, following: https://en.wikipedia.org/wiki/Great-circle_distance
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