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

write_map_culled_to_base(base_mesh_filename, ...)	Write out a file with maps from cells, edges and vertices on a culled mesh to the same elements on a base mesh.
map_culled_to_base(ds_base, ds_culled[, workers])	Create maps from cells, edges and vertices on a culled mesh to the same elements on a base mesh.
write_culled_dataset(in_filename, ...[, ...])	Create a new dataset in which all fields from ds have been culled from the base mesh to the culled mesh.
cull_dataset(ds, ds_base_mesh, ds_culled_mesh)	Create a new dataset in which all fields from ds have been culled from the base mesh to the culled mesh.

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.append(other)	Append a deep copy of another config parser to this one.
MpasConfigParser.prepend(other)	Prepend a deep copy of another config parser to this one.
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

Landice Tools

visualization
visualization.plot_transect(data_path, ...)	Plot transects of desired variable from MALI output.
visualization.plot_map(data_path, variable, ax)	Plot map of MALI output either by specifying a variable name or a pre-computed field.
visualization.plot_grounding_lines(...[, ...])	Plot MALI grounding line at arbitrary number of times.

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

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

Vector

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.
Vector.angular_distance(other)	Compute angular distance between points on the sphere, following: https://en.wikipedia.org/wiki/Great-circle_distance
Vector.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.
Vector.intersection(a1, a2, b1, b2)	Based on https://stackoverflow.com/a/26669130/7728169 Find the intersection point as a unit vector between great circle arc from a1 to a2 and from b1 to b2.
Vector.straddles(a1, a2, b1, b2)	Based on https://stackoverflow.com/a/26669130/7728169 Determines if the great circle segment determined by (a1, a2) straddles the great circle determined by (b1, b2)
Vector.dot(other)	Compute the dot product between this vector and other.
Vector.cross(other)	Compute the dot product between this vector and other.
Vector.det(v1, v2, v3)	The determinant of the matrix defined by the three Vector objects
Vector.mag()	The magnitude of the vector

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