Discretize

- 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



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

This provides updates to the `vtkModule` documentation that reflect recent development in [`vtki`](http://docs.vtki.org) and a new example for 3D visualization. Check out [the new example](http://discretize.simpeg.xyz/en/master/auto_examples/vtki_demo.html#sphx-glr-auto-examples-vtki-demo-py) and the types of 3D renderings that are now possible in a pure Python environment (also its Python 3 friendly!):


Example in Brief

Using `vtki`, any `discretize` mesh can now be immediately rendered using the `toVTK()` method. Be sure to check out [the `vtki` docs](http://docs.vtki.org/en/latest/) to learn more about using `vtki`!

- [Filtering](http://docs.vtki.org/en/latest/tools/filters.html)
- [IPython Tools](http://docs.vtki.org/en/latest/tools/ipy_tools.html)
- [Understanding VTK data types](http://docs.vtki.org/en/latest/types/common.html)


py
import discretize
import numpy as np
import vtki
vtki.set_plot_theme('document')

Create a TensorMesh
h1 = np.linspace(.1, .5, 3)
h2 = np.linspace(.1, .5, 5)
h3 = np.linspace(.1, .8, 3)
mesh = discretize.TensorMesh([h1, h2, h3])

Get a VTK data object
dataset = mesh.toVTK()

Defined a rotated reference frame
mesh.axis_u = (1,-1,0)
mesh.axis_v = (-1,-1,0)
mesh.axis_w = (0,0,1)
Check that the reference frame is valid
mesh._validate_orientation()

Yield the rotated vtkStructuredGrid
dataset_r = mesh.toVTK()

p = vtki.BackgroundPlotter()
p.add_mesh(dataset, color='green', show_edges=True)
p.add_mesh(dataset_r, color='maroon', show_edges=True)
p.show_grid()
p.screenshot('vtk-rotated-example.png')




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

Add vtki support to make using VTK data objects more Pythonic

banesullivan recently added a ton of new features to [`vtki`](https://github.com/akaszynski/vtki) (the VTK interface Python package) that help make using just about any VTK data objects more intuitive/Pythonic. If `vtki` is available in your Python environment then these changes make using VTK data objects way easier. Here's a screenshot of what this currently looks like in a Jupyter notebook (creates static renderings but can also be interactive in a separate pop-up window).

Also check out [this notebook](https://github.com/OpenGeoVis/PVGeo-Examples/blob/master/3.0%20-%20Using%20the%20vtkInterface%20Package.ipynb) to see more ways to use [`PVGeo`](https://github.com/OpenGeoVis/PVGeo), `discretize`, and [`vtki`](https://github.com/akaszynski/vtki). Below is a screenshot of a simple use case:


<img width="757" alt="screen shot 2018-12-28 at 2 27 21 pm" src="https://user-images.githubusercontent.com/22067021/50525947-ba6eff80-0aac-11e9-8b1d-dfbc770fe3c9.png">


Simple example

py
import discretize
import numpy as np

Create a simple TensorMesh
h1 = np.linspace(.1, .5, 3)
h2 = np.linspace(.1, .5, 5)
h3 = np.linspace(.1, .5, 3)
mesh = discretize.TensorMesh([h1, h2, h3])

Convert to VTK object and use vtki to render it
mesh.toVTK().plot(notebook=False)


Fancy example

Here we load the [**Laguna del Maule Bouguer Gravity**](http://docs.simpeg.xyz/content/examples/04-grav/plot_laguna_del_maule_inversion.html#sphx-glr-content-examples-04-grav-plot-laguna-del-maule-inversion-py) example from the SimPEG docs.

This data scene was produced from the [Laguna del Maule Bouguer Gravity](http://docs.simpeg.xyz/content/examples/04-grav/plot_laguna_del_maule_inversion.html#sphx-glr-content-examples-04-grav-plot-laguna-del-maule-inversion-py) example provided by [Craig Miller](https://github.com/craigmillernz) (Maule volcanic field, Chile. Refer to Miller et al 2016 EPSL for full details.)

> Miller, C. A., Williams-Jones, G., Fournier, D., & Witter, J. (2017). 3D gravity inversion and thermodynamic modelling reveal properties of shallow silicic magma reservoir beneath Laguna del Maule, Chile. Earth and Planetary Science Letters, 459, 14–27. https://doi.org/10.1016/j.epsl.2016.11.007

py
import shelve
import tarfile
import discretize

f = discretize.utils.download(
"https://storage.googleapis.com/simpeg/laguna_del_maule_slicer.tar.gz"
)
tar = tarfile.open(f, "r")
tar.extractall()
tar.close()

with shelve.open('./laguna_del_maule_slicer/laguna_del_maule-result') as db:
mesh = db['mesh']
Lpout = db['Lpout']

mesh = discretize.TensorMesh.copy(mesh)
models = {'Lpout':Lpout}
mesh.toVTK(models).plot()


Usage Notes

Since `vtk` and `vtki` are not required dependencies you'll need to make sure you install them to your Python environment. Pip install for `vtki` should do the trick but Windows folks might need to install `vtk` from conda seperately. Also this is Python 3 friendly!

sh
pip installl vtki

- from pr 95
- commits from micmitch
- review from lheagy

Description

Added stream_thickness keyword argument to plotSlice and _plotImage2D functions so that it is possible to scale the thickness of streamlines to reflect the amplitude of the vector field. This functionality was added in a manner similar to the stream_threshold keyword.

stream_thickness keyword currently takes a float which acts as a scaling factor for the streamline thickness. Bounds are hardwired to fix the thickness of the 10% largest and smallest vector amplitudes. Provides good results with the DC current density plots I've made but could probably be generalized in the future for more flexibility.

e.g.
python
mesh.plotSlice(
u, ax=ax, normal='X', vType='F', view='vec', stream_threshold=1e-8, stream_thickness=3
)