Document parallel gmsh

.appveyor.yml

@@ -77,7 +77,7 @@ install:
 
     # Configure the VM.
     - cmd: if "%TARGET_ARCH%" == "x64" if "%CONDA_PY%" == "27" conda.exe install --quiet --name root python=2.7 fipy
-    - cmd: if "%TARGET_ARCH%" == "x64" if "%CONDA_PY%" == "36" conda.exe install --quiet --name root python=3.6 fipy "gmsh<4.0"
+    - cmd: if "%TARGET_ARCH%" == "x64" if "%CONDA_PY%" == "36" conda.exe install --quiet --name root python>3 fipy gmsh
     - cmd: conda.exe remove --quiet --force fipy
     # FIXME: fipy recipe on conda-forge doesn't have gmsh compatible with Python 2.7
     - ps: |

.circleci/config.yml

@@ -36,7 +36,7 @@ commands:
       - run:
           name: Create Conda Environment
           command: |
-            conda create -v --quiet --prefix << parameters.condaenv >> --show-channel-urls --channel conda-forge << parameters.packages >> "gmsh<4.0"
+            conda create -v --quiet --prefix << parameters.condaenv >> --show-channel-urls --channel conda-forge << parameters.packages >> gmsh
             source activate ~/project/<< parameters.condaenv >>
             conda remove --quiet --channel conda-forge --force fipy
             pip install scikit-fmm

.travis.yml

@@ -45,7 +45,7 @@ before_install:
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
   - conda update -q conda
-  - conda create --quiet --name test-environment --show-channel-urls --channel conda-forge python=$TRAVIS_PYTHON_VERSION fipy "gmsh<4.0";
+  - conda create --quiet --name test-environment --show-channel-urls --channel conda-forge python=$TRAVIS_PYTHON_VERSION fipy gmsh;
   - source activate test-environment
   - conda remove --quiet --channel conda-forge --force fipy
   - if [[ $PY3K -eq 0 ]]; then

INSTALLATION.rst

@@ -67,14 +67,17 @@ Recommended Method
 * `install Miniconda`_ on your computer
 * run::
 
-    $ conda create --name <MYFIPYENV> --channel conda-forge python=<PYTHONVERSION> fipy
+    $ conda create --name <MYFIPYENV> --channel conda-forge python=<PYTHONVERSION> fipy gmsh
 
   .. note::
 
      This command creates a self-contained conda_ environment and then
      downloads and populates the environment with the prerequisites for
      :term:`FiPy` from the conda-forge_ channel at https://anaconda.org.
 
+     :term:`Gmsh` is an optional package because some versions are
+     incompatible with :term:`FiPy`, so it must be requested explicitly.
+
   .. attention::
 
      Windows x86_64 is fully supported, but this does not work on
@@ -85,7 +88,7 @@ Recommended Method
 
      and for Python 3.x, you should be able to do::
 
-      conda create --name <MYFIPYENV> --channel conda-forge python=3.6 numpy scipy matplotlib pysparse
+      conda create --name <MYFIPYENV> --channel conda-forge python=3 numpy scipy matplotlib pysparse gmsh
 
      followed, for either, by::
 
@@ -269,7 +272,7 @@ http://www.geuz.org/gmsh/
 
 :term:`Gmsh` is an application that allows the creation of irregular meshes.
 When running in parallel, :term:`FiPy` requires a version of :term:`Gmsh`
->= 2.5 and < 4.0.
+>= 2.5 and < 4.0 or >= 4.5.2.
 
 SciPy
 =====

fipy/meshes/gmshMesh.py

@@ -176,9 +176,11 @@ def openMSHFile(name, dimensions=None, coordDimensions=None, communicator=parall
             gmshFlags = ["-%d" % dimensions, "-nopopup"]
 
             if communicator.Nproc > 1:
-                if not (StrictVersion("2.5") < version <= StrictVersion("4.0")):
-                    warnstr = "Cannot partition with Gmsh version < 2.5 or >= 4.0. " \
-                               + "Reverting to serial."
+                if  ((version < StrictVersion("2.5"))
+                     or (StrictVersion("4.0") <= version < StrictVersion("4.5.2"))):
+                    warnstr = ("Cannot partition with Gmsh version < 2.5 "
+                               "or 4.0 <= version < 4.5.2. "
+                               "Reverting to serial.")
                     warnings.warn(warnstr, RuntimeWarning, stacklevel=2)
                     communicator = serialComm
 
@@ -190,7 +192,7 @@ def openMSHFile(name, dimensions=None, coordDimensions=None, communicator=parall
                     gmshFlags += ["-part", "%d" % communicator.Nproc]
                     if version >= StrictVersion("4.0"):
                         # Gmsh 4.x needs to be told to generate ghost cells
-                        # Unfortunately, the ghosts are broken
+                        # Unfortunately, the ghosts are broken in Gmsh 4.0--4.5.1
                         # https://gitlab.onelab.info/gmsh/gmsh/issues/733
                         gmshFlags += ["-part_ghosts"]
 
@@ -1387,6 +1389,11 @@ def _localOverlappingCellIDs(self):
 class Gmsh2D(Mesh2D):
     """Construct a 2D Mesh using Gmsh
 
+    If called in parallel, the mesh will be partitioned based on the value
+    of `parallelComm.Nproc`.  If an `MSH` file is supplied, it must have
+    been previously partitioned with the number of partitions matching
+    `parallelComm.Nproc`.
+
     >>> radius = 5.
     >>> side = 4.
     >>> squaredCircle = Gmsh2D('''
@@ -1875,6 +1882,11 @@ def _test(self):
 class Gmsh2DIn3DSpace(Gmsh2D):
     """Create a topologically 2D Mesh in 3D coordinates using Gmsh
 
+    If called in parallel, the mesh will be partitioned based on the value
+    of `parallelComm.Nproc`.  If an `MSH` file is supplied, it must have
+    been previously partitioned with the number of partitions matching
+    `parallelComm.Nproc`.
+
     Parameters
     ----------
     arg : str
@@ -1959,6 +1971,11 @@ def _test(self):
 class Gmsh3D(Mesh):
     """Create a 3D Mesh using Gmsh
 
+    If called in parallel, the mesh will be partitioned based on the value
+    of `parallelComm.Nproc`.  If an `MSH` file is supplied, it must have
+    been previously partitioned with the number of partitions matching
+    `parallelComm.Nproc`.
+
     Parameters
     ----------
     arg : str