Merge pull request #311 from xylar/add_mesh_creation

Add mesh creation module to  mpas_tools conda package

compass/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "compass" %}
-{% set version = "0.1.8" %}
+{% set version = "0.1.9" %}
 {% set build = 0 %}
 
 {% if mpi == "nompi" %}
@@ -30,16 +30,12 @@ build:
 requirements:
   run:
     - python
-    - geometric_features 0.1.10
-    - mpas_tools 0.0.10
+    - geometric_features 0.1.11
+    - mpas_tools 0.0.11
     - jigsaw 0.9.12
     - jigsawpy 0.2.1
     - metis
-    - pyflann
-    - scikit-image
-    - cartopy
     - cartopy_offlinedata
-    - pyamg
     - ffmpeg
     - {{ mpi }}  # [mpi != 'nompi']
     - esmf * {{ mpi_prefix }}_*

conda_package/docs/api.rst

@@ -23,8 +23,27 @@ MPAS mesh tools
 
    translate
 
+.. currentmodule:: mpas_tools.mesh.creation
 
-.. currentmodule:: mpas_tools.conversion
+.. autosummary::
+   :toctree: generated/
+
+   build_mesh.build_mesh
+   coastal_tools.coastal_refined_mesh
+   inject_bathymetry.inject_bathymetry
+   inject_meshDensity.inject_meshDensity
+   inject_preserve_floodplain.inject_preserve_floodplain
+   jigsaw_driver.jigsaw_driver
+   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
+   triangle_to_netcdf.triangle_to_netcdf
+   jigsaw_to_netcdf.jigsaw_to_netcdf
+
+.. currentmodule:: mpas_tools.mesh.conversion
 
 .. autosummary::
    :toctree: generated/

conda_package/docs/building_docs.rst

@@ -0,0 +1,26 @@
+.. _dev_building_docs:
+
+**************************
+Building the Documentation
+**************************
+
+To make a local test build of the documentation, it is easiest to follow the
+:ref:`dev_testing_changes` procedure for how to make a local build of the
+``mpas_tools`` package.  Then, you need to set up a conda environment with the
+test build and some other required packages:
+
+code-block::
+
+  $ conda create -y -n test_mpas_tools_docs --use-local mpas_tools sphinx mock \
+       sphinx_rtd_theme
+  $ conda activate test_mpas_tools_docs
+
+Then, to build the documentation, run:
+
+code-block::
+
+  $ export DOCS_VERSION="test"
+  $ cd conda_package/docs
+  $ make html
+
+Then, you can view the documentation by opening ``_build/html/index.html``.

conda_package/docs/define_base_mesh.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+"""
+% Create cell width array for this mesh on a regular latitude-longitude grid.
+% Outputs:
+%    cellWidth - m x n array, entries are desired cell width in km
+%    lat - latitude, vector of length m, with entries between -90 and 90, degrees
+%    lon - longitude, vector of length n, with entries between -180 and 180, degrees
+"""
+import numpy as np
+
+
+def cellWidthVsLatLon():
+
+    ddeg = 10
+    constantCellWidth = 240
+
+    lat = np.arange(-90, 90.01, ddeg)
+    lon = np.arange(-180, 180.01, ddeg)
+
+    cellWidth = constantCellWidth * np.ones((lat.size, lon.size))
+    return cellWidth, lon, lat

conda_package/docs/index.rst

@@ -15,11 +15,24 @@ ocean and land-ice test cases,
 the `MPAS-Analysis <https://github.com/MPAS-Dev/MPAS-Analysis>`_ package for
 analyzing simulations, and in other MPAS-related workflows.
 
+User's Guide
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   mesh_creation
+   mesh_conversion
+
 Developer's Guide
 =================
 .. toctree::
    :maxdepth: 2
 
+   making_changes
+   testing_changes
+   building_docs
+
    api
 
 Indices and tables

conda_package/docs/making_changes.rst

@@ -0,0 +1,83 @@
+.. _dev_making_changes:
+
+****************************
+Making Changes to mpas_tools
+****************************
+
+New python functions and modules (``.py`` files) can be added within the
+``conda_package/mpas_tools``.  These will automatically be part of the
+``mpas_tools`` package.  New directories with python modules should include an
+``__init__.py`` file (which can be empty) to indicate that they are also part of
+the package.
+
+Entry Points
+============
+
+The best way to add new "scripts" to the package is to add a function without
+any arguments somewhere in the package, and then to add it as an "entry point"
+both in ``conda_package/setup.py`` and ``conda_package/recipe/meta.yaml``.
+
+As an example, the entry point ``planar_hex`` is defined in ``setup.py`` as:
+
+.. code-block:: python
+
+  setup(name='mpas_tools',
+  ...
+        entry_points={'console_scripts':
+                    ['planar_hex = mpas_tools.planar_hex:main',
+  ...
+
+and in ``meta.yaml`` as:
+
+.. code-block::
+
+  build:
+    number: 0
+    entry_points:
+      - planar_hex = mpas_tools.planar_hex:main
+
+When the package is installed in a conda environment, a stub script
+``planar_hex`` will be in the user's path that will call the function ``main()``
+in the module ``mpas_tools.planar_hex``:
+
+.. code-block:: python
+
+  def main():
+
+      parser = argparse.ArgumentParser(
+          description=__doc__, formatter_class=argparse.RawTextHelpFormatter)
+      parser.add_argument('--nx', dest='nx', type=int, required=True,
+                          help='Cells in x direction')
+      ...
+      args = parser.parse_args()
+
+      make_planar_hex_mesh(args.nx, args.ny, args.dc,
+                           args.nonperiodic_x, args.nonperiodic_y,
+                           args.outFileName)
+
+As you can see, the function pointed to by the entry point can used to parse
+command-line arguments, just as a "normal" python script would do
+
+By convention, entry points do not typically include the ``.py`` extension.
+
+Dependencies
+============
+
+If you changes introduce new dependencies, these need to be added to the recipe
+for the conda package in ``conda_package/recipe/meta.yaml``
+
+Add these changes to the end of the ``run`` section of ``requirements``:
+
+.. code-block::
+
+  requirements:
+  ...
+    run:
+      - python
+      - netcdf4
+      ...
+      - affine
+
+These requirements *must* be on the ``conda-forge`` anaconda channel.  If you
+need help with this, please contact the developers.
+