Meridional Overturning Circulation

The mpas_tools.ocean.moc module contains tools for setting up masks used by both MPAS-Ocean and MPAS-Analysis for computing the global and basin-wide Meridional Overturning Circulation (MOC).

Building MOC Basins

The mpas_tools.ocean.moc.build_moc_basins() function can be used to merge a large number of individual seas from the geometric_features <http://mpas-dev.github.io/geometric_features/stable/> package into 5 larger features defining the MOC basins:

  • Global

  • Atlantic

  • Indian

  • Pacific

  • Indo-pacific

A call to this function returns a FeatureCollection with these 5 basins.

A typical workflow calling this function would look like:

from geometric_features import GeometricFeatures
from mpas_tools.ocean.moc import build_moc_basins


gf = GeometricFeatures()
fcMOC = build_moc_basins(gf)

Adding Southern Transects

Typically, the basins on their own are not particularly useful. For all but the global MOC, a southern transect is needed to determine the flow into or out of the basin from the south. The function mpas_tools.ocean.mocadd_moc_southern_boundary_transects() can be used to add masks for all the edges associated with the southern boundary of each MOC basin.

A typical workflow calling this function would look like:

import xarray
from geometric_features import GeometricFeatures
from mpas_tools.ocean.moc import build_moc_basins


mesh_filename = 'mesh.nc'

gf = GeometricFeatures()
fcMOC = build_moc_basins(gf)

dsMesh = xarray.open_dataset(mesh_filename)
dsMasks = mpas_tools.mesh.conversion.mask(dsMesh=dsMesh, fcMask=fcMOC)

dsMasksAndTransects = add_moc_southern_boundary_transects(dsMasks, dsMesh)

In this example, only the mesh.nc file is required as an input. The resulting xarray.Dataset contains both the basin and southern-transect masks.

A command-line tool moc_southern_boundary_extractor.py is also available for this purpose:

$ moc_southern_boundary_extractor.py --help

usage: moc_southern_boundary_extractor.py [-h] -f IN_FILE -m MESH_FILE -o
                                          OUT_FILE

This script takes a mesh file (-m flag) and a file with MOC regions masks
(-f flag) produce by the MPAS mask creator.  The script produces a copy of
the contents of the MOC mask file, adding transects that mark the southern
boundary of each region in a file indicated with the -o flag.  The transect
is applied only to vertices and edges, not cells, because the need for southern
boundary transect data on cells is not foreseen.

Author: Xylar Asay-Davis
last modified: 5/22/2018

optional arguments:
  -h, --help            show this help message and exit
  -f IN_FILE, --in_file IN_FILE
                        Input file with MOC masks
  -m MESH_FILE, --mesh_file MESH_FILE
                        Input mesh file
  -o OUT_FILE, --out_file OUT_FILE
                        Output file for MOC masks and southern-boundary transects

The command-line tool is largely intended for backwards compatibility and the python function is the preferred way of building a workflow with this functionality.

Building MOC Basins and Transects Together

Typically, a workflow can be made more efficient by using the function mpas_tools.ocean.moc.make_moc_basins_and_transects() takes care of both Building MOC Basins and Adding Southern Transects as well as writing out the results to files.

A typical workflow calling this function would look like:

from geometric_features import GeometricFeatures
from mpas_tools.ocean.moc import make_moc_basins_and_transects


mesh_filename = 'mesh.nc'
mesh_name = 'EC30to60kmL60E3SMv2r03'

mask_filename = '{}_moc_masks.nc'.format(mesh_name)
mask_and_transect_filename = '{}_moc_masks_and_transects.nc'.format(
    mesh_name)

geojson_filename = 'moc_basins.geojson'

gf = GeometricFeatures()

make_moc_basins_and_transects(gf, mesh_filename, mask_and_transect_filename,
                              geojson_filename=geojson_filename,
                              mask_filename=mask_filename)

In this example, only the mesh.nc file is required as an input. The basin and transect masks are written to mask_and_transect_filename, and we also request that the intermediate data sets get written out for, perhaps for purposes of debugging or provenance. The MOC feature collection from Building MOC Basins will be written to geojson_filename, while the basin masks (without the associate transect masks) will be written to mask_filename.