Merge pull request #349 from xylar/further_updates_to_docs

A lot of new additions to the documentation

This merge adds documentation for all of the remaining functionality in the mpas_tools conda package with the exception of the scripts copied from the landice directory.

This merge also fixes some very minor bugs related to a deprecated xarray method (drop --> drop_vars) and some warnings about unneeded parentheses that were discovered in the process of improving docstrings.

conda_package/docs/api.rst

@@ -9,40 +9,41 @@ the documentation.
 MPAS mesh tools
 ===============
 
+Mesh creation
+-------------
+
 .. currentmodule:: mpas_tools.planar_hex
 
 .. autosummary::
    :toctree: generated/
 
    make_planar_hex_mesh
 
-.. currentmodule:: mpas_tools.translate
-
-.. autosummary::
-   :toctree: generated/
-
-   translate
-
 .. currentmodule:: mpas_tools.mesh.creation
 
 .. autosummary::
    :toctree: generated/
 
+   build_mesh
    build_mesh.build_spherical_mesh
    build_mesh.build_planar_mesh
    jigsaw_driver.jigsaw_driver
    jigsaw_to_netcdf.jigsaw_to_netcdf
+   mesh_definition_tools
    mesh_definition_tools.mergeCellWidthVsLat
    mesh_definition_tools.EC_CellWidthVsLat
    mesh_definition_tools.RRS_CellWidthVsLat
    mesh_definition_tools.AtlanticPacificGrid
    mpas_to_triangle.mpas_to_triangle
-   open_msh.readmsh
+   signed_distance
    signed_distance.signed_distance_from_geojson
    signed_distance.mask_from_geojson
    signed_distance.distance_from_geojson
    triangle_to_netcdf.triangle_to_netcdf
 
+Mesh conversion
+---------------
+
 .. currentmodule:: mpas_tools.mesh.conversion
 
 .. autosummary::
@@ -66,6 +67,16 @@ MPAS mesh tools
 
    split_grids
 
+.. currentmodule:: mpas_tools.translate
+
+.. autosummary::
+   :toctree: generated/
+
+   translate
+   center
+   center_on_mesh
+
+
 .. currentmodule:: mpas_tools.io
 
 .. autosummary::
@@ -80,43 +91,62 @@ MPAS mesh tools
 
    scrip_from_mpas
 
-Ocean Tools
-===========
+Inerpolation
+------------
 
-.. currentmodule:: mpas_tools.ocean.coastline_alteration
+.. currentmodule:: mpas_tools.mesh.interpolation
 
 .. autosummary::
    :toctree: generated/
 
-   add_critical_land_blockages
-   widen_transect_edge_masks
+   interp_bilin
+
+CIME constants
+--------------
 
-.. currentmodule:: mpas_tools.ocean.moc
+.. currentmodule:: mpas_tools.cime
 
 .. autosummary::
    :toctree: generated/
 
-   make_moc_basins_and_transects
-   build_moc_basins
+   constants
+
+Ocean Tools
+===========
 
-.. currentmodule:: mpas_tools.ocean.coastal_tools
+.. currentmodule:: mpas_tools.ocean
 
 .. autosummary::
    :toctree: generated/
 
-   coastal_refined_mesh
-   create_background_mesh
-   extract_coastlines
-   distance_to_coast
-   compute_cell_width
-   save_matfile
-   CPP_projection
-   smooth_coastline
-   get_data_inside_box
-   get_indices_inside_quad
-   get_convex_hull_coordinates
-   plot_coarse_coast
-   plot_region_box
+   coastline_alteration
+   coastline_alteration.add_critical_land_blockages
+   coastline_alteration.widen_transect_edge_masks
+   coastline_alteration.add_land_locked_cells_to_mask
+
+   moc
+   moc.make_moc_basins_and_transects
+   moc.build_moc_basins
+   moc.add_moc_southern_boundary_transects
+
+   build_mesh
+   build_mesh.build_spherical_mesh
+   build_mesh.build_planar_mesh
+
+   coastal_tools
+   coastal_tools.coastal_refined_mesh
+   coastal_tools.create_background_mesh
+   coastal_tools.extract_coastlines
+   coastal_tools.distance_to_coast
+   coastal_tools.compute_cell_width
+   coastal_tools.save_matfile
+   coastal_tools.CPP_projection
+   coastal_tools.smooth_coastline
+   coastal_tools.get_data_inside_box
+   coastal_tools.get_indices_inside_quad
+   coastal_tools.get_convex_hull_coordinates
+   coastal_tools.plot_coarse_coast
+   coastal_tools.plot_region_box
 
 .. currentmodule:: mpas_tools.ocean.inject_bathymetry
 
@@ -151,3 +181,29 @@ Visualization
    :toctree: generated/
 
    extract_vtk
+
+.. currentmodule:: mpas_tools.viz.mesh_to_triangles
+
+.. autosummary::
+   :toctree: generated/
+
+   mesh_to_triangles
+
+
+.. currentmodule:: mpas_tools.viz.colormaps
+
+.. autosummary::
+   :toctree: generated/
+
+   register_sci_viz_colormaps
+
+Tests
+=====
+
+.. currentmodule:: mpas_tools.tests.test_cime_constants
+
+.. autosummary::
+   :toctree: generated/
+
+   test_cime_constants
+

conda_package/docs/cime.rst

@@ -0,0 +1,12 @@
+.. _cime_mod:
+
+CIME Constants
+==============
+
+The module :py:mod:`mpas_tools.cime.constants` contains constants that are in
+sync with `CIME <https://github.com/ESMCI/cime>`_, which provides infrastructure
+and utilities for Earth System Models such at E3SM.  Currently, the only
+constant being synched with CIME is the radius of the Earth.  Constants are
+checked against their values on CIME's master branch during tests of the
+conda build.  See
+:py:func:`mpas_tools.tests.test_cime_constants.test_cime_constants`.

conda_package/docs/index.rst

@@ -23,6 +23,22 @@ User's Guide
 
    mesh_creation
    mesh_conversion
+   interpolation
+
+   cime
+
+   visualization
+
+Ocean Tools
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   ocean/mesh_creation
+   ocean/coastal_tools
+   ocean/coastline_alteration
+   ocean/moc
 
 Developer's Guide
 =================

conda_package/docs/interpolation.rst

@@ -0,0 +1,48 @@
+.. _mesh_interpolation:
+
+.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
+   :trim:
+
+*************
+Interpolation
+*************
+
+Previously, various tools in this package used ``scipy`` for interpolation.
+However, the interpolation routines in ``scipy`` are not well suited to
+interpolation from regular grids to MPAS meshes---they are slow and very memory
+intensive, particularly for large meshes.
+
+For bilinear interpolation from a tensor lon/lat grid to an MPAS mesh, it will
+be faster to use the function
+:py:func:`mpas_tools.mesh.interpolation.interp_bilin()`
+Here is an example where we define cell width for an EC mesh (see
+:ref:`ec_mesh`), read in longitude and latitude from an MPAS mesh, and
+interpolate the cell widths to cell centers on the MPAS mesh.
+
+.. code-block:: python
+
+    import numpy as np
+    import netCDF4 as nc4
+    from mpas_tools.mesh.interpolation import interp_bilin
+
+    dlon = 1.
+    dlat = dlon
+    earth_radius = constants['SHR_CONST_REARTH']
+    nlon = int(360./dlon) + 1
+    nlat = int(180./dlat) + 1
+    lon = np.linspace(-180., 180., nlon)
+    lat = np.linspace(-90., 90., nlat)
+
+    cellWidth = mdt.EC_CellWidthVsLat(lat)
+
+    # broadcast cellWidth to 2D
+    _, cellWidth = np.meshgrid(lon, cellWidthVsLat)
+
+    ds = nc4.Dataset('base_mesh.nc', 'r+')
+    lonCell = ds.variables['lonCell'][:]
+    latCell = ds.variables['latCell'][:]
+
+    lonCell = np.mod(np.rad2deg(lonCell) + 180., 360.) - 180.
+    latCell = np.rad2deg(latCell)
+
+    cellWidthOnMpas = interp_bilin(lon, lat, cellWidth, lonCell, latCell)