Merge V2.3 into Master

.coveragerc

@@ -1,6 +1,14 @@
 [run]
+source =
+    openpnm/
+
+[report]
+exclude_lines =
+    raise NotImplementedError
+    if __name__ == .__main__.:
 omit =
-    *__init__*
     test/*
+    docs/*
+    tests/*
+    example.py
     setup.py
-    example_script.py

.github/workflows/ci-macos.yml

@@ -27,12 +27,11 @@ jobs:
           ${{ runner.os }}-pip-
 
     - name: Install Dependencies
-      # if: steps.cache.outputs.cache-hit != 'true'
       run: |
         pip install -r requirements/pip_requirements.txt
         pip install -r requirements/test_requirements.txt
         pip uninstall openpnm --yes
         python setup.py install
-        
+
     - name: Running tests
-      run: pytest --pep8 --ignore=tests/integration/examples
+      run: pytest --pep8 --ignore=scripts/

.github/workflows/ci-ubuntu.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: [3.6, 3.7]
+        python-version: [3.6, 3.7, 3.8]
         operating-system: [ubuntu-latest]
 
     steps:
@@ -27,16 +27,21 @@ jobs:
           ${{ runner.os }}-pip-
 
     - name: Install Dependencies
-      # if: steps.cache.outputs.cache-hit != 'true'
       run: |
         pip install -r requirements/pip_requirements.txt
         pip install -r requirements/test_requirements.txt
         pip uninstall openpnm --yes
         python setup.py install
-        
+        pip install pyamg
+        sudo apt update --yes
+        sudo apt-get install mpich --yes
+        pip install mpi4py
+        export PETSC_CONFIGURE_OPTIONS='--download-f2cblaslapack=1 --download-scalapack --download-mumps'
+        pip install petsc petsc4py
+
     - name: Running tests
-      run: pytest --pep8 --cov=./ --cov-report=xml --ignore=tests/integration/examples
-    
+      run: pytest --pep8 --cov=./ --cov-report=xml --ignore=scripts/
+
     - name: Upload coverage to Codecov
       if: matrix.python-version == 3.7
       uses: codecov/codecov-action@v1
@@ -45,4 +50,4 @@ jobs:
         file: ./coverage.xml
         flags: unittests
         name: codecov-umbrella
-        yml: ./codecov.yml     
+        yml: ./codecov.yml

.github/workflows/ci-windows.yml

@@ -27,11 +27,10 @@ jobs:
           ${{ runner.os }}-pip-
 
     - name: Install Dependencies
-      # if: steps.cache.outputs.cache-hit != 'true'
       run: |
         pip install -r requirements/pip_requirements.txt
         pip install -r requirements/test_requirements.txt
         python setup.py install
-        
+
     - name: Running tests
-      run: pytest --pep8 --ignore=tests/integration/examples
+      run: pytest --pep8 --ignore=scripts/

.github/workflows/examples.yml

@@ -33,6 +33,11 @@ jobs:
         pip install -r requirements/test_requirements.txt
         pip uninstall openpnm --yes
         pip install -e .
-        
+        pip install porespy # for ipynb tests
+
     - name: Running tests
-      run: pytest tests/integration/examples
+      run:
+        pytest --nbval -p no:python
+        --ignore=tests/
+        --ignore="examples/paper_recreations/Blunt et al. (2013)"
+        --ignore="examples/paper_recreations/Wu et al. (2010)"

README.md

@@ -8,17 +8,19 @@
 
 -----
 
-**Cite as:**
-> _Gostick, Jeff, Mahmoudreza Aghighi, James Hinebaugh, Tom Tranter, Michael A. Hoeh, Harold Day, Brennan Spellacy et al._ "**OpenPNM: a pore network modeling package.**" Computing in Science & Engineering 18, no. 4 (2016): 60-74.
+**Please cite as:**
+> _Gostick et al._ "**OpenPNM: a pore network modeling package.**" Computing in Science & Engineering 18, no. 4 (2016): 60-74.
 > [doi:10.1109/MCSE.2016.49](https://ieeexplore.ieee.org/document/7478437)
 
 # Overview of OpenPNM
 
-*OpenPNM* is an open source project aiming to provide porous media researchers with a comprehensive framework for performing pore network simulations on a wide range of materials.
+*OpenPNM* is a comprehensive framework for performing pore network simulations of porous materials.
+
+For more details about the package can be found in the [on-line documentation](https://openpnm.readthedocs.io/en/master/index.html)
 
 ## Installation and Requirements
 
-OpenPNM can be installed from the Python Package index using:
+OpenPNM can be installed from the [Python Package Index](https://pypi.org/project/openpnm/) using:
 
 ```
 pip install openpnm
@@ -52,32 +54,22 @@ mip.run()
 
 ```
 
-The network can be visualized in [Paraview](http://www.paraview.org) giving the following:
+The network can be visualized in [`ParaView`](http://www.paraview.org) giving the following:
 
-![](https://i.imgur.com/mSDrIBOm.png)
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/14086031/77927983-dc3dd000-7275-11ea-8700-c96c2d51aa1f.png" width="60%"></img>
+</p>
 
-The drainage curve can be visualized with `MIP.plot_intrusion_curve()` giving something like this:
+The drainage curve can be visualized with `mip.plot_intrusion_curve()` giving something like this:
 
-![](https://i.imgur.com/1C2uXt9m.png)
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/14086031/77930201-96363b80-7278-11ea-95fd-4a55fb1d6148.png" width="60%"></img>
+</p>
 
 A collection of examples is available in the *examples* folder of this repository: [Examples](https://www.github.com/PMEAL/OpenPNM/tree/master/examples)
 
-## Release Management and Versioning
-
-OpenPNM uses [Semantic Versioning](http://semver.org) (i.e. X.Y.Z) to label releases.  All major and minor versions (X.Y.z) are available on [PyPI](https://pypi.python.org/pypi), but bugfixe releases (x.y.Z) are not generally pushed unless the bug is important.
-
-OpenPNM uses the [Github Flow](https://guides.github.com/introduction/flow/) system of Git branching, except instead of merging PRs into *master*, they are merged into a branch called *dev*. Any code added to *dev* is done via Pull Requests (PRs).  When new PRs are merged into the *dev* branch, they are *not* given a new version number. Once enough new features have been added, the *dev* branch is merged into the *master* branch, and the minor release number (x.Y.z) will be incremented. An exception to this rule are bugfixes which may be found on *master*.  In these cases a PR can be merged into *master* and the version number wil be incremented (x.y.Z) to indicate the fix.
-
-OpenPNM depends on several other packages widely known as the [Scipy Stack](https://www.scipy.org/stackspec.html).  It is our policy to always support the latest version of all these packages and their dependencies.
-
-The main developer for this project is Prof. Jeff Gostick ([email protected]).
-
-## Licence and Citation
-
-OpenPNM is free to use and is offered under the permissive [MIT License](http://opensource.org/licenses/MIT)
-
-If you do use OpenPNM in an academic work, the developers ask that you cite the following paper, which outlines the design principles and general uses of OpenPNM:
+## Contact
 
-    Gostick et al. OpenPNM: A pore network modeling package. Computing in Science & Engineering. 18(4), p60-74.
+OpenPNM is developed by the Porous Materials Engineering and Analysis Lab [(PMEAL)](http://pmeal.com), in the [Department of Chemical Engineering](https://uwaterloo.ca/chemical-engineering/) at the [University of Waterloo](https://uwaterloo.ca/) in Waterloo, Ontario, Canada.
 
-A link to this article can be found [here](http://doi.org/10.1109/MCSE.2016.49).
+The lead developer for this project is Prof. Jeff Gostick ([email protected]).

VERSIONING.md

@@ -0,0 +1,7 @@
+## Release Management and Versioning
+
+OpenPNM uses [Semantic Versioning](http://semver.org) (i.e. X.Y.Z) to label releases.  All major and minor versions (X.Y.z) are available on [PyPI](https://pypi.python.org/pypi), but bugfix releases (x.y.Z) are not generally pushed unless the bug is important.  Bubfix releases are available via download of the source code from Github.
+
+OpenPNM uses the [Github Flow](https://guides.github.com/introduction/flow/) system of Git branching, except instead of merging PRs into *master*, they are merged into a branch called *dev*. Any code added to *dev* is done via Pull Requests (PRs).  When new PRs are merged into the *dev* branch, they are *not* given a new version number. Once enough new features have been added, the *dev* branch is merged into the *master* branch, and the minor release number (x.Y.z) will be incremented. An exception to this rule are bugfixes which may be found on *master*.  In these cases a PR can be merged into *master* and the version number will be incremented (x.y.Z) to indicate the fix.
+
+OpenPNM depends on several other packages widely known as the [Scipy Stack](https://www.scipy.org/stackspec.html).  It is our policy to always support the latest version of all these packages and their dependencies.

bin/test

@@ -15,8 +15,11 @@ if 'cov' in sys.argv:
                  '--cov=openpnm',
                  '--cov-config=.coveragerc'])
 
+if 'nbval' in sys.argv:
+    args.append('--nbval')
+
 if 'ignore-examples' in sys.argv:
-    args.extend(['--ignore=tests/integration/examples/'])
+    args.extend(['--ignore=examples/'])
     args.extend(['--ignore=scripts/'])
 
 exit_code = pytest.main(args)

docs/index.rst

@@ -10,7 +10,7 @@ Welcome to the OpenPNM Documentation
 .. sidebar:: Highlight
 
     The image below was extracted using the SNOW algorithm from PoreSpy, then
-    imported into OpenPNM for use, the exported to Paraview for visualization.
+    imported into OpenPNM for use, then exported to Paraview for visualization.
 
     .. image:: /../docs/static/images/extracted_berea.png
         :width: 400px

docs/userguide/algorithms/percolation.rst

@@ -105,9 +105,10 @@ A full invasion simulation using a 2D network can be run with the following comm
  >>> import openpnm as op
  >>> import matplotlib.pyplot as plt
  >>> import scipy as sp
+ >>> import numpy as np
  >>> ws = op.Workspace()
  >>> proj = ws.new_project()
- >>> S = sp.array([100, 100, 1])
+ >>> S = np.array([100, 100, 1])
  >>> pn = op.network.Cubic(shape=S, spacing=0.0001)
  >>> geom = op.geometry.StickAndBall(network=pn, pores=pn.Ps, throats=pn.Ts)
  >>> water = op.phases.Water(network=pn)
@@ -119,8 +120,8 @@ A full invasion simulation using a 2D network can be run with the following comm
  >>> ip.run()
  >>> water.update(ip.results(Snwp=0.5))
 
-Images can be produced easily for 2D networks with commands such as ``plt.imshow(sp.reshape(ip['pore.invasion_sequence'], newshape=S[S > 1]))``
-and ``plt.imshow(sp.reshape(water['pore.occupancy'], newshape=S[S > 1]))``, which produces the following output:
+Images can be produced easily for 2D networks with commands such as ``plt.imshow(np.reshape(ip['pore.invasion_sequence'], newshape=S[S > 1]))``
+and ``plt.imshow(np.reshape(water['pore.occupancy'], newshape=S[S > 1]))``, which produces the following output:
 
 .. image:: https://imgur.com/VPf24cN.png
 

docs/userguide/customizing.rst

@@ -49,7 +49,7 @@ We can now update our script:
 .. code-block:: python
 
 	import openpnm as op
-	import scipy as sp
+	import numpy as np
 	import my_models
 
 	#Generate a simple Cubic Network
@@ -59,7 +59,7 @@ We can now update our script:
 	geom = op.geometry.GenericGeometry(network=pn,pores=pn.pores(),throats=pn.throats())
 
 	#Assign random pores diameters between 0 and 40
-	geom['pore.diameter'] = sp.rand(pn.Np,)*40
+	geom['pore.diameter'] = np.random.rand(pn.Np,)*40
 
 	#Assign model to geometry
 	geom.add_model(propname='pore.surface_area',

docs/userguide/data_storage.rst

@@ -37,6 +37,7 @@ The physical details about pores and throats are referred to as *properties*, wh
 
     >>> import openpnm as op
     >>> import scipy as sp
+    >>> import numpy as np
     >>> pn = op.network.Cubic(shape=[3, 3, 3])
     >>> pn['pore.coords'][1]
     array([0.5, 0.5, 1.5])
@@ -60,7 +61,7 @@ The above lines illustrate how a scalar value is converted to a vector (*Np*-lon
 
 .. code-block:: python
 
-    >>> pn['pore.bar'] = sp.rand(27)  # pn has 27 pores (3*3*3)
+    >>> pn['pore.bar'] = np.random.rand(27)  # pn has 27 pores (3*3*3)
 
 Attempts to write an array of the wrong size will result in an error:
 
@@ -94,15 +95,15 @@ The only distinction between *labels* and *properties* is that *labels* are Bool
 .. code-block:: python
 
     >>> pn['pore.top'][2] = False
-    >>> list(sp.where(pn['pore.top'])[0])
+    >>> list(np.where(pn['pore.top'])[0])
     [5, 8, 11, 14, 17, 20, 23, 26]
     >>> pn['pore.top'][2] = True  # Re-apply label to pore 2
 
 Creating a new label array occurs automatically if a Boolean array is stored on an object:
 
 .. code-block:: python
 
-    >>> pn['pore.dummy_1'] = sp.rand(27) < 0.5
+    >>> pn['pore.dummy_1'] = np.random.rand(27) < 0.5
 
 A complication arises if you have a list of pore numbers you wish to label, such as [3, 4, 5].  You must first create the label array with all ``False`` values, *then* assign ``True`` to the desired locations:
 
@@ -117,7 +118,7 @@ The *label* functionality uses Scipy's ``where`` method to return a list of loca
 
 .. code-block:: python
 
-    >>> list(sp.where(pn['pore.dummy_2'])[0])
+    >>> list(np.where(pn['pore.dummy_2'])[0])
     [3, 4, 5]
 
 The ``pores`` and ``throats`` methods offer several useful enhancements to this approach.  For instance, several labels can be queried at once:

example.py

@@ -31,7 +31,7 @@
 phys_air['pore.n'] = 2
 phys_air['pore.A'] = -1e-5
 phys_air.add_model(propname='pore.2nd_order_rxn', model=mod,
-                   quantity='pore.concentration',
+                   X='pore.concentration',
                    prefactor='pore.A', exponent='pore.n',
                    regen_mode='deferred')
 rxn = op.algorithms.FickianDiffusion(network=pn)

examples/README.md

@@ -1,36 +1,9 @@
-[![Travis](https://travis-ci.org/PMEAL/OpenPNM.svg?branch=master)](https://travis-ci.org/PMEAL/OpenPNM)
-
 # OpenPNM Examples
 
-A collection of scripts illustrating the use of OpenPNM.  The files in these folders are written in MarkDown, which allows for an useful blend of formatted text and highlighted code.  You can browse the available files by clicking through the web interface of the repository seen above.
-> **Note:** All the examples in this repository are subject to automated testing, so if the build badge above says passing then all of these examples should work.  All code within these files is in code-blocks and preceded by the python prompt symbol (>>>).  This is annoying for cutting-and-pasting, but is necessary if we want to run automated tests on the code.
-
-## Contents
-
-The examples are organized in the directory structure of the repository.  The folders and files are given somewhat descriptive names to indicate what sort of example they contain.
-
-## How to Contribute an Example to this Collection
-
-We strongly encourage you to create an example and post it in this collection.  The procedure is straightforward and can be explained in just a few lines:
-
-1.  Fork this repository to your own Github account using the 'Fork' button on the top of this page.  This will create an independent version of the repo under your own Github account, and will let you make edits and additions to the repository without needing write permission from us.
-
-2. Create your example using the instructions below, and push your changes to your forked version of the repository.  You can edit and push as many times as needed to check how the document looks when Github renders it.
-
-3. Make a pull request using the Github website by going the 'Pull Requests' tab on your forked repository, and then selecting the 'New pull request' button.  This will trigger the automated testing to ensure your example works.  You can help ensure this will pass by running the tests locally by typing `python run_tests` at your command prompt (assuming you have [Pytest installed](https://pytest.org/latest/getting-started.html)).
-
-## How to Write an Example
-
-This section introduces a few rules and tips for creating nicely formatted documents that would be suitable for inclusion here.
-
-1. All files must be written in MarkDown.  This is the text formatting language used by Github to create nice looking issues and posts within a given repository.  MarkDown files have an *md* file extension.  If you need some help on MarkDown formatting and notation, checkout the [MarkDown Cheatsheet].  The style is not very strict, but efforts should be made to be consistent with the existing files.
-
-2. All code must be not only enclosed with code blocks denoted by triple ticks (\`\`\`)  (see the [MarkDown Cheatsheet]), but each line must be preceded by >>> like the Python prompt.  The Pytest package which is used for automated testing of examples only recognizes lines of code preceded by the a >>>.  Moreover, each code block must end with one blank line before the closing ticks (\`\`\`), or else Pytest reports an error.  The flip side of this coin is that if you feel that some could should NOT be tested, this can be accomplished by excluding the >>>.
-
-3. Any images to be inserted into an examples should be hosted on an external size such as [imgur](http://imgur.com).  These can then be linked to using the appropriate notations as given in the [MarkDown Cheatsheet].
+[![](https://github.com/PMEAL/OpenPNM/workflows/Examples/badge.svg)](https://github.com/PMEAL/OpenPNM/actions)
 
-4. Any files required by an example (such as data files containing network info) should be stored in the 'fixtures' directory at the top level of this repository.
+This folder contains a collection of Jupyter Notebooks illustrating the use of OpenPNM.  Jupyter Notebooks allows for a helpful combination of formatted text and functioning code.  You can browse the available files by clicking through the web interface of the repository seen above.
 
-5.  The file name should be descriptive of the contents since the user only sees these when navigating the repository. Similarly, the file should be placed in an appropriate folder, or a folder should be created if necessary.
+The examples are organized by the directory structure, with folders and files given somewhat descriptive names to indicate what sort of example they contain.
 
-[MarkDown CheatSheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
+All these notebooks are subjected to our testing suite on each build of the package.  If the badge above says 'passing', then all the examples found here should be functional and compatible with the current version of OpenPNM.