Discretize

- from pr: 152
- commits from: banesullivan
- review from: lheagy

Changes

- Update `discretize` to work with PyVista (previously `vtki`)
- Enable the PyVista 3D visualization examples to be run when making the docs on CI services
- Switch the documentation hosting service to GitHub Pages from Read The Docs
- New `InterfaceOMF` mixin for converting `discretize` meshes to Open Mining Format (OMF) objects
- `pep8` refactoring of `mixins`
- Drop Windows testing on Python 3.5

- from pr: 143
- commits from: prisae, banesullivan
- review from: lheagy

This PR adds html and non-html representations which should be more generally applicable, for small and big `TensorMesh`'s.

Based on work by banesullivan on `vtki` and prisae on the `printversion`-tool.


- from prs: 141, 146
- commits from: fourndo, jcapriot, lheagy, prisae
- review from: prisae, lheagy, jcapriot

Tree Mesh updates
- Add functionality for TreeMesh creation
- General bug fix on refine function

Docs
- typo fix in the installation from source

- From PR 134
- commits from: lheagy
- review from: dccowan

Improvements
Organization of base classes
- move base classes to a `base` directory (closes 128)

Docs
- use napoleon + numpy-style docs to compile the docs (closes 126)
- convert existing docstrings to numpy-styled docs
- separate the API documentation from user documentation (closes 127)


Testing
- travis cleanup (previously it was confusing which version of python was being used. We used the python 3.6 image on travis but then downloaded the latest conda - which is python 3.7): now each test suite is clearly labeled
- use pytest for testing instead of nose

Follow ups
- content to be developed in the "User Guide" (see 149)
- create a contributor guide (separate pr) that includes info on how we document classes, methods, functions and class attributes (e.g. https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) (see 150)
- pr on SimPEG to ensure it is up-to-date with the changes in the base-class don't cause upstream problems (see simpeg/simpeg776)

Thanks:
- leouieda : for your beautiful repo-setup and docs to follow :)

- from pr: 145
- commits from: prisae
- review from: fourndo

Add `fig`-parameter to `plot_3d_slicer`

Small change to provide more flexibility for `plot_3d_slicer`. It now takes an optional `fig`-parameter (100% backwards compatible), in which one can provide an existing figure handle. The figure is cleared at every call, but no new figure is created. This can give some more flexibility, for instance in the use together with widgets.

Initiated upon an idea by fourndo, who uses it for a Mag Tutorial:
where he used the figure handle to replace the YZ-plot with a data plot, and wrap it into a widget.

Code example: Now you can call

fig = plt.figure()
mesh.plot_3d_slicer(model, fig=fig)

where `fig` is an existing figure. And then you can do more funky stuff with your figure handle. It is sort of a convenience addition, as the same would be possible with:

fig = plt.figure()
tracker = discretize.View.Slicer(mesh, model, **kwargs)
fig.canvas.mpl_connect('scroll_event', tracker.onscroll)

Add access for vtkToTensorMesh function

- from pr 140
- commits from: banesullivan

This patch makes available a feature that was tucked away in the `vtkModule` enabling users to back convert `vtkRectilinearGrid`s or `vtki.UnstructuredGrid`s to `TensorMesh` objects. This new feature is the `discretize.TensorMesh.vtkToTensorMesh()` function.

These changes are motivated by a need to easily and interactively create meshes in `vtki` then send those meshes back to `discretize` for use in `SimPEG`.

Example

The following example allows a user to repeatedly tweak a mesh with interactive visualization before deciding on a final mesh structure before sending that mesh to `discretize`:

**Note: the needs to be done in IPython**

Necessary imports
py
import vtki
from vtki import examples
import discretize
import numpy as np


Create a background plotting window that can be interacted with throughout a Jupyter notebook
py
Create a plotting window
p = vtki.BackgroundPlotter()
p.show_grid()


Download a sample topography dataset using `vtki` to surround with a mesh
py
Get a sample topo surface from vtki
Note: this requires vtki>=0.17.1
topo = examples.download_st_helens().warp_by_scalar()

p.add_mesh(topo, name='topo')


Repeatedly change this cell and rerun to decide on your mesh discretization
py
Create the mesh interactively
tweak these parameters and rerun this cell until satisfied

b = topo.bounds
xcoords = np.linspace(b[0], b[1], 50)
ycoords = np.linspace(b[2], b[3], 50)
zcoords = np.linspace(b[4]-5000, b[5], 50)

mesh = vtki.RectilinearGrid(xcoords, ycoords, zcoords)

p.add_mesh(mesh, name='mesh', opacity=0.5, show_edges=True)
output the mesh
mesh


<table><tr><th>RectilinearGrid</th><th>Information</th></tr><tr><td>N Cells</td><td>117649</td></tr><tr><td>N Points</td><td>125000</td></tr><tr><td>X Bounds</td><td>5.579e+05, 5.677e+05</td></tr><tr><td>Y Bounds</td><td>5.108e+06, 5.122e+06</td></tr><tr><td>Z Bounds</td><td>-3.636e+03, 3.225e+03</td></tr><tr><td>Volume</td><td>9.381e+11</td></tr><tr><td>N Scalars</td><td>0</td></tr></table>


Finally, send the mesh to `discretize` for use in other processing routines
py
Once satisfied, convert to discretize:
dmesh, _ = discretize.TensorMesh.vtkToTensorMesh(mesh)
dmesh

<discretize.TensorMesh.TensorMesh at 0xb2a555588>


And a GIF to demo