Openpnm

This hotfix repairs a bug in the handling of overlapping pores for cases where the pores overlap but the throat endpoints are not collinear with the pore centers. This bug was leading to erroneous calculations of permeability and tortuosity in extracted networks by incorrect conductance values for affected conduits.

This release is a bit ahead of schedule (based on our plan to release at the beginning of each semester), but it's a *very* important release. It fixes several important bugs in the ReactiveTransport class and adds some major improvements to the handling of iterative calculations, among other things. The complete list of updates is given below:

🚀 Improvements and Enhancements

* Major upgrade to pore-scale model dependency checking
* Added detailed checking for NaNs in GenericTransport
* Enhanced the mixture submodule
* Renamed the PNP related classes to more descriptive names
* Improved performance of CubicTemplate by removing finding and labeling of surface pores
* Enhanced plot_networkx to work for 1D networks and improved robustness
* Improved docstrings in algorithms, especially settings, with help of docrep
* Added Python 3.8 to testing suite
* Consolidated solver tolerances
* Algorithms now accept initial guess when calling run
* README.md now renders propertly on PyPI
* Optimized OpenPNM import time dramatically
* Added full pytest integration for jupyter notebooks, as well as scipy 2 deprecation-proofing

🚀 New Features and Functionality

* Added a PoreSpy option to io module
* Added preliminary ability to export to Salome
* Add example on how to create a custom phase object
* Added inspect_locations method to the Project class

🐛🐛🐛 Major Bug Fixes

* Fixed _run_generic to rebuild A and b when cache_A/b set to False
* Fixed PETSc wrapper to be compatible with the latest MUMPS release
* Fixed missing minus sign when using source terms in transient algs with Crank-Nicolson
* Fixed dispersion rate calculation
* Improved tolerance in transient simulations to match steady-state

🐛 Minor Bug Fixes

* Default values for source term models now ensure zero rate/S1/S2
* Replaced is not with != throughout
* Removed use of floats as indices in arange and linspace
* Fix set_source so calling it w/ same propname does not lead to duplicate source terms
* Solver rejects solution when residual equals tolerance
* Fixed throat models that would break with no throats were present
* Fix dispersion conductance bug: now updates iteratively
* Fixed bug in merge_networks when networks were 2D

This is the first release of 2020, and is hopefully part of a new 'semester-based' release schedule. So instead of waiting an undefined amount of time until we have enough new features for a release, we will release all the new features we have added in the past semester.

🚀 New features (experimental)

* The MultiPhase class for better automated handling of multiphase simulations, including species partitioning between phases
* The Mixtures submodule for better automated handling of mixtures such as air or brine

🐛 Improvements and bugfixes

* Example scripts have been moved out of the main directory and into /scripts
* Enhanced the cooperative pore filling models for the MixedIP algorithm
* Improved speed of InvasionPercolation very substantially (about 25x)
* Enhanced purge_object to accept list of objects
* Added reset method to GenericTransport and ReactiveTransport so objects can be reused inside a for-loop
* Bug fix in plot_networkx method

I recently added a small feature that appends the git commit to the version number for users working on a branch other than master, but the import of gitpython apparently fails if the host machine does not have git installed. Now this import occurs inside a try-accept so will not break

Several of our dependencies broke with the release of numpy 1.15, so users doing pip install with a recent conda installation (on windows) would receive a build error. This version has moved the offending deps to be optional.

There are a number of other small bug fixes and tweaks that were also added, but these were not as urgent.

🚀 New features and capabilities

* All Transport algorithms are now transient, including non-linear reactions
* A Dispersion algorithm with 4 optional discretization schemes has been added
* A mixed percolation algorithm has been added that can model drainage and/or imbibition, and includes detailed menisci movements such as snap-off, burst, and coalescence
* Several new network generators have been added such as *bcc* and *fcc* lattices
* Support for several new solvers, including [pyAMG](https://github.com/pyamg/pyamg) and [scikit-umfpack](https://github.com/scikit-umfpack/scikit-umfpack) which can now both be installed using `pip`, and [PetSc](http://www.mcs.anl.gov/petsc/index.html), assuming you are able to install it yourself (not supported by `pip`).
* The symmetry of the coefficient matrix is now maintained when boundary conditions are are added, which significantly improves the speed of some CG based solvers (>2x faster).

Pore-Scale Models

* Much more rigorous and accurate pore-scale conductance models
* Pore-scale models can now be assigned to any object, so a model that calculates pore diameters can be assigned to a network if desired
* Pore-scale models are now stored in a top level module, making then more prominent and easier to find

Importing and Exporting Data

* Added support for two new data export formats: hdf5 and xdmf. These are designed for storing massive data sets with maximum speed, and the xdmf format can be open in Paraview for vastly sped-up visualization
* The PNM file format was refined to save either single projects or entire workspaces seamlessly

Better Organization and General Housekeeping

* The algorithm classes have been completely re-written for better consistency
* A settings attribute has been added to all objects to contain various flags and values which used to be stored as hidden attributes
* Topological manipulation tools have been moved from a sub-module of `network` to a top level module (`topotools`) to make it easier to access and more prominent
* A `Project` class has been added, that acts as a container for a given pore network simulation, such that the `Workspace` is populated with a collection of `Projects`, each of which contains a Network object and all other associated objects (i.e. geometries, phases, etc.)

📖 Documentation

* The documentation has been thoroughly overhauled, and now includes complete coverage of all modules, classes, methods, and functions.
* The [OpenPNM-Example repository](https://github.com/PMEAL/OpenPNM-Examples) has been converted to Jupyter Notebooks so users can download actual functioning code to get started

⚠️ Backwards incompatible changes

One of the main reasons for the version bump to 2.0 was to allow several long delayed changes that break backward compatibility. These are all quite superficial, so any experience using V1.0 should be easily transferred:

* All module names, including the package itself, have been changed to lowercase in accord with [pep8](https://www.python.org/dev/peps/pep-0008/) rules
* Neumann and Dirichlet boundary conditions have been renamed to Rate and Value to be more descriptive
* The behavior of the various lookup methods (`pores`, `find_neighbor_pores`) have been cleaned up for better consistency
* A unique Physics objects must be defined for each Geomery object. This is a bit more effort for the user, but allows much more reliable associations between objects. The new `Project` class has a `grid` method that can help to organize and visualize these associations.