Openpnm

🚀 New features
- Two new Network classes have been added that support _Dual_ networks
- `CubicDual` creates an normal cubic network of size [x, y, z] called the 'primary' network, then adds 'secondary' cubic network of size [x-1, y-1, z-1] at the interstices of the 'primary' lattice. These two networks are then interconnected to each other. The point of this class it to enable both pore phase and solid phase transport simultaneously, through primary and secondary networks, as well as allowing exchange between them via the interconnections.
- `DelaunayVoronoiDual` is motivated by the same idea as the `CubicDual`, but uses a Delaunay tessellation of random points as the 'primary' network and the Voronoi tessellation as the 'secondary' network.
- Two new plotting functions were added to `Network.tools`: `plot_coordinates` and `plot_connections`. These are meant for quickly verifying the topology of a network without having to spin-up Paraview
- Several function have been added to `Network.tools`
- `template_disc_ring` creates a circular template for use in `Cubic`
- `generate_base_points` generates random points for use in `Delaunay` and `DelaunayVoronoiDual`
- A new _pore-scale model_ called `largest_sphere` was added to `Geometry.models` that calculates the largest possible pore diameter to put in each location without overlapping the neighboring pores. This model is particularly useful for random networks where the spacing between pore centers is unknown.
- A method for finding the pores on the surface of a network was added to `Network.tools` called `find_surface_pores`.

⚠️ API changes
- `add_boundaries` now accepts a list of which face to add boundaries to, rather than doing all sides (which is still the default).
- Support for Python 3.3 has been dropped, and support for 3.6 has been added. OpenPNM is also compatible with the latest version of Numpy, which made a few significant changes in indexing rules.
- The `save` and `load` methods of the `Workspace` class are now called `save_workspace` and `load_workspace` to more clearly indicate their job.

🍏 Major enhancements and changes
- Added two new import classes for importing from [iMorph](http://imorph.fr) and [3DMA-Rock](http://www.ams.sunysb.edu/~lindquis/3dma/3dma_rock/3dma_rock.html).
- Now uses [dill](https://pypi.python.org/pypi/dill) instead of Python's standard [pickle](https://docs.python.org/3.5/library/pickle.html) library. This means that custom pore scale models and classes can be saved to "pnm" files.
- Changed the name of the "Controller" object to "Workspace", which more literally describes it's role. "Controller" can still be used for backward compatibility.
- All Network and topology manipulation tools are now found under `Network.tools` although they can still be accessed via `Utilities.topology` for backwards compatibility.
- Completely reworked documentation. The 'user guide' now consists of 3 tutorials of varying levels, with the aim that users will know how to use OpenPNM pretty well after completing all three. There is also a separate 'reference' section in the user guide that explains the inner workings of the code in more detail, but users don't have to sift through these to get started anymore.
- All documentation is now hosted on [ReadTheDocs](https://readthedocs.org/projects/openpnm/), which rebuilds the documentation every time a new commit is pushed to Github. The docs will now always be up-to-date!
- A new parallel repository has been created to house all Examples at https://github.com/PMEAL/OpenPNM-Examples. All the code in this repository is tested against the latest version of OpenPNM on PyPI, so if there are any broken examples we'll know about it. This will remedy the frustration felt by many users when trying to learn OpenPNM by examples. This is also why the Tutorials were created as the main User Guide (see 5 above).

🚀 New features
- Added ability to have spatially varying pore seed values, which is useful for creating porosity distributions or undulations.
- Added new arguments to `num_neighbors`. It can now apply set logic (i.e. 'union' and 'intersection') when counting neighbors, and it can now count neighboring throats as well as pores with the `element` keyword (which is 'pores' by default to maintain backwards compatibility).
- Object handles are now stored in dicts rather than lists, so you can access them by name (geom.phases['air']) and also iterate on the dict (pn.phases.values()). This was implemented in a backwards compatible way so geom.phases() and geom.phases('air') still work as they used to...of course using the dict syntax is encourage henceforth.

🐛 Minor improvements and bugfixes

- Fixed code coverage reporting on [Codecov](https://codecov.io/gh/PMEAL/OpenPNM)
- Changed many print statements to logger messages
- Several private methods were removed that were never called by the code

🥇 Acknowledgements

The OpenPNM Developers would like to thank the following people for contributing to this release:
- Matthew Stadelman (stadelmanma) for crafting the iMorph IO class
- Masa Prodanovic for help with the 3DMA-Rock import class

Almost all changes in this minor release are back-end fixes, or were at least implemented in a backwards compatible way. Looking at the length of this list makes me realize that we should be doing minor version bumps more often!

⚠️ API changes (backend)
- `set_locations` was removed from **Core** and moved to **Base.Tools** as a new class. This functionality is now added to **GenericGeometry** and **GenericPhysics** via composition, so they still have a `set_locations` method, but **Phase** and **Network** objects do not.
- Codecov is now working again
- Test coverage was increased by 2%
- Object handles are now stored in _dicts_ rather than _lists_, so you can access them by name (`geom.phases['air']`) and also iterate on the _dict_ (`pn.phases.values()`). This was implemented in a backwards compatible way so `geom.phases()` and `geom.phases('air')` still work as they used to...of course using the _dict_ syntax is encourage henceforth.
- Several private methods were removed that were never called by the code
- The `check_network_health` method now finds duplicate throats in a more robust and reliable way
- Loading simulations from a _pnm_ file now registers objects with the **Controller** properly
- The tools located under **Utilities.topology** have been moved to **Network.tools**, but wrapper methods were left in the old location for backward compatibility.
- Many little tweaks in PR 547
- Changed many print statements to logger messages
- Added a _mode_ argument to `num_neighbors` so you can count neighbors that meet given criteria

The setup.py had a circular reference to our package leading to it being initialized before being installed. On machines without the necessary dependencies (i.e. new users) this was throwing an import error upon installation.

This update has been pushed to PyPI so all future attempts at `pip install openpnm` should work.

Fixed bug in `add_boundary_pores` that was leading to double addition of throats
Changed code in `GenericLinearSolver` to prevent Warnings

🚀 Enhancements and additions
- Added a new Drainage algorithm with much more functionality than `OrdinaryPercolation`. This algorithm was completely overhauled and designed specifically for simulating drainage experiments.
- Major upgrade to the Network Importing and Export capabilities, including the ability to export data to a Pandas `DataFrame`, and import from `NetworkX`.

🚀 New Features
- `merge_pores` was added to Utilities.topology
- `add_boundary_pores` and `make_periodic_connections` were added the Cubic class to provide more power over the process of adding boundary pores compared to the `add_boundaries` method
- `find_path` was added to the Utilities.misc for finding paths between pairs of pores.
- Added an Empty network class which accepts `Nt` and `Np` arguments, so can be used to manually build a network.
- Enhanced the `clear` method on the Core class to provide more control when clearing data from an object.

🍎 Minor improvements
- Improvements to the performance of some methods in `GenericNetwork`
- Various bug fixes in the `subdivide` method and the linear solver
- Added several private `parse` methods to the Core class that help validate inputs to the various methods and provide more helpful error messages.
- Altered the `GenericPhysics` class so that its associated Phase can be changed.