add support for gmsh

.github/workflows/documentation.yaml

@@ -15,7 +15,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v2
       with:
-        python-version: '3.x'
+        python-version: '3.7'
     - name: Install docs dependencies
       run: |
         python -m pip install -r docs/requirements.txt
@@ -24,4 +24,10 @@ jobs:
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         pip install -e .
     - name: Build ${{ matrix.doc-type }} documentation
+      # there is an issue with gmsh on GitHub Actions
+      # it cannot be reproduced locally or on RTD
+      # See https://github.com/kip-hart/MicroStructPy/runs/1204718343?check_suite_focus=true#step:5:45
+      # this should be investigated at a later date
+      # in the meantime, an RTD webhook will be used to check docs builds
+      continue-on-error: true
       run: sphinx-build -Wnb ${{ matrix.doc-type }} docs/source/ docs/build-${{ matrix.doc-type }}/

CHANGELOG.rst

@@ -11,6 +11,7 @@ and this project adheres to `Semantic Versioning`_.
 Added
 '''''''
 - References within XML input files using the ``<include>`` tag.
+- Support for gmsh. (addresses `#16`_)
 
 `1.3.5`_ -  2020-09-20
 --------------------------
@@ -180,3 +181,4 @@ Added
 .. _`Semantic Versioning`: https://semver.org/spec/v2.0.0.html
 
 .. _`#14`: https://github.com/kip-hart/MicroStructPy/issues/14
+.. _`#16`: https://github.com/kip-hart/MicroStructPy/issues/16

docs/requirements.txt

@@ -1,5 +1,6 @@
+gmsh==4.6.0.post2
 matplotlib
 numpy==1.17.3
 pybind11==2.4.3
 sphinx==3.0.4
-sphinx-gallery==0.4.0
+sphinx-gallery==0.8.1

docs/source/cli/settings.rst

@@ -43,9 +43,12 @@ quality, among other things. The default settings are:
             <edge_opt> False </edge_opt>
             <edge_opt_n_iter> 100 </edge_opt_n_iter>
 
-            <mesh_max_volume> inf </mesh_max_volume>
-            <mesh_min_angle> 0 </mesh_min_angle>
-            <mesh_max_edge_length> inf </mesh_max_edge_length>
+            <mesher>  Triangle/TetGen </mesher>
+
+            <mesh_size> inf </mesh_size> <!-- used with gmsh -->
+            <mesh_max_volume> inf </mesh_max_volume> <!-- used with Triangle and TetGen -->
+            <mesh_min_angle> 0 </mesh_min_angle> <!-- used with Triangle and TetGen -->
+            <mesh_max_edge_length> inf </mesh_max_edge_length> <!-- used with Triangle -->
 
             <verify> False </verify>
 

docs/source/conf.py

@@ -96,6 +96,7 @@
     'meshpy',
     'mpl_toolkits',
     'numpy',
+    'pygmsh',
     'pyquaternion',
     'pyvoro',
     'pyvtk',

docs/source/examples/cli/minimal.rst

@@ -42,6 +42,9 @@ They are saved in a folder named ``minimal``, in the current directory
 The axes are turned off in these plots, creating PNG files with
 minimal whitespace.
 
+This example also demonstrates how to use gmsh to generate a mesh, using the
+``<mesher>`` and ``<mesh_size>``  tags in the input file.
+
 Finally, the seeds and grains are colored by their seed number, not by
 material.
 

docs/source/package_guide.rst

@@ -196,9 +196,10 @@ Unstructured Meshing
 ++++++++++++++++++++
 
 The triangular/tetrahedral meshes are generated in MicroStructPy using the
-`MeshPy`_ package.
-It links with `Triangle`_ to create 2D triangular meshes and with `TetGen`_
+`MeshPy`_ and `pygmsh`_ packages.
+MeshPy links with `Triangle`_ to create 2D triangular meshes and with `TetGen`_
 to create 3D tetrahedral meshes.
+Pygmsh links with `gmsh`_ to produce both 2D and 3D meshes.
 
 A polygonal mesh, :class:`.PolyMesh`, can be converted into an unstructured
 mesh using the :meth:`.TriMesh.from_polymesh` method.
@@ -288,8 +289,10 @@ The ``max_volume`` option allows for maximum element volume controls to be
 phase-specific.
 
 
+.. _`gmsh`: https://gmsh.info
 .. _`MeshPy`: https://mathema.tician.de/software/meshpy/
 .. _`Power Diagram`: https://en.wikipedia.org/wiki/Power_diagram
+.. _`pygmsh`: https://pygmsh.readthedocs.io
 .. _`pyvoro`: https://github.com/mmalahe/pyvoro
 .. _`TetGen`: http://wias-berlin.de/software/tetgen/
 .. _`Triangle`: https://www.cs.cmu.edu/~quake/triangle.html

requirements.txt

@@ -1,6 +1,7 @@
 aabbtree==2.5.0
 matplotlib==3.0.2
 pybind11==2.4.3
+pygmsh==6.1.1
 MeshPy==2018.2.1
 numpy==1.19.0
 pyquaternion==0.9.5

setup.py

@@ -79,6 +79,7 @@ def find_version(*fname):
         'aabbtree>=2.5.0',
         'matplotlib>=3.0.0',
         'pybind11',  # must come before meshpy for successful install
+        'pygmsh>=6.1.1,<7',  # 7.0.0 released without cell_data
         'lsq-ellipse',
         'meshpy>=2018.2.1',
         'numpy>=1.13.0',

src/microstructpy/cli.py

@@ -221,10 +221,11 @@ def _include_expand(inp, filename, key):
 
 def run(phases, domain, verbose=False, restart=True, directory='.',
         filetypes={}, rng_seeds={}, plot_axes=True, rtol='fit', edge_opt=False,
-        edge_opt_n_iter=100,
+        edge_opt_n_iter=100, mesher='Triangle/TetGen',
         mesh_max_volume=float('inf'), mesh_min_angle=0,
-        mesh_max_edge_length=float('inf'), verify=False, color_by='material',
-        colormap='viridis', seeds_kwargs={}, poly_kwargs={}, tri_kwargs={}):
+        mesh_max_edge_length=float('inf'), mesh_size=float('inf'),
+        verify=False, color_by='material', colormap='viridis',
+        seeds_kwargs={}, poly_kwargs={}, tri_kwargs={}):
     r"""Run MicroStructPy
 
     This is the primary run function for the package. It performs these steps:
@@ -298,6 +299,8 @@ def run(phases, domain, verbose=False, restart=True, directory='.',
         edge_opt_n_iter (int): *(optional)* Maximum number of iterations per
             edge during optimization. Ignored if `edge_opt` set to False.
             Defaults to 100.
+        mesher (str): {'Triangle/TetGen' | 'Triangle'  | 'TetGen' | 'gmsh'}
+            specify the mesh generator. Default is 'Triangle/TetGen'.
         mesh_max_volume (float): *(optional)* The maximum volume (area in 2D)
             of a mesh cell in the triangular mesh. Default is infinity,
             which turns off the maximum volume quality setting.
@@ -309,6 +312,9 @@ def run(phases, domain, verbose=False, restart=True, directory='.',
             Value should be in the range 0-60.
         mesh_max_edge_length (float): *(optional)* The maximum edge length of
             elements along grain boundaries. Currently only supported in 2D.
+        mesh_size (float): The target size of the mesh elements. This
+            option is used with gmsh. Default is infinity, whihch turns off
+            this control.
         plot_axes (bool): *(optional)* Option to show the axes in output plots.
             When False, the plots are saved without axes and very tight
             borders. Defaults to True.
@@ -500,8 +506,9 @@ def run(phases, domain, verbose=False, restart=True, directory='.',
         if verbose:
             print('Creating triangular mesh.')
 
-        tmesh = TriMesh.from_polymesh(pmesh, phases, mesh_min_angle,
-                                      mesh_max_volume, mesh_max_edge_length)
+        tmesh = TriMesh.from_polymesh(pmesh, phases, mesher, mesh_min_angle,
+                                      mesh_max_volume, mesh_max_edge_length,
+                                      mesh_size)
 
     # Write triangular mesh
     tri_types = filetypes.get('tri', [])

src/microstructpy/examples/minimal_paired.xml

@@ -14,5 +14,7 @@
         <plot_axes> False </plot_axes>
         <color_by> seed number </color_by>
         <colormap> Paired </colormap>
+        <mesher> gmsh </mesher>
+        <mesh_size> 0.03 </mesh_size>
     </settings>
 </input>