0.4.7

• from pr: #172
• commits from: @dccowan
• review from: @sarahgarre, @sgkang, @lheagy

Tutorials in the discretize docs

Addition of tutorials for:

• Mesh generation (tensor, cyl and tree)
• Averaging and differential operators
• Discretized approximations to inner products using finite volume (basic, constitutive relations, differential operators and an advanced section)
• Solving PDE examples

Update TensorMesh-OMF interface

• from pr #174
• commits from @banesullivan
• review from @lheagy

Overview

This release adds full support for going back and forth between OMF and discretize.TensorMesh. The OMF support implemented in a previous release only went one way (disscretize ➡️ OMF) and had a bug that messed up the spatial reference of the OMF mesh. This release makes it seamless to go back and forth (discretize ↔️ OMF). Give it a try with the new to_omf(models) method and load your TensorMeshs into other software that supports OMF (e.g. Leapfrog)!

Notes

• At the moment, only TensorMeshs are supported by OMF
• OMFv2 should bring more support for Curvilinear and Tree meshes. When that's released we can fill in the methods that currently raises a NotImplementedError
• These changes makes updates to the TensorMesh-OMF interface to make going to/from OMF/discretize more fluid.

Example

import discretize
import omf
import numpy as np

# Make a TensorMesh
h = np.ones(16)
mesh = discretize.TensorMesh([h, 2*h, 3*h])
vec = np.arange(mesh.nC)
models = {'arange': vec}

# Make an OMF Element
omf_element = mesh.to_omf(models)

# Use OMF to save that element to an OMF project
proj = omf.Project(
    name='My project',
    description='The most awesome project I have ever worked '\
                'on and this is a lengthy description of how '\
                'awesome it is.',
)

# Add the volume element
proj.elements = [omf_element,]

# Verify all is good
assert proj.validate()

# Write it out
omf.OMFWriter(proj, 'myproject.omf')

And now you can use the .omf project file with your tensor mesh or many tensor meshes in your favorite software that supports OMF (e.g. Leapfrog).

Or you could verify this all worked with omfvista:

import omfvista
foo = omfvista.load_project('myproject.omf')
foo.plot()

Make matplotlib a soft dependency

• from pr #156
• commits from @prisae
• review from @rowanc1, @lheagy

Make matplotlib a soft dependency; reasoning:

• it is "only" used for the plotting of meshes, which is sort of a relatively small (yet important) part of the whole discretize scope.
• it would help to install discretize on minimal conda-environments for running models on a server, without having to install matplotlib.

This is achieved by

• using a decorator on functions where matplotlib is required
• removing matplotlib from the setup.py

`plot_3d_slicer` improvements; `refine_mesh_xyz` bug fix; `VTK` interaction improvements

Commits: @dccowan ; @prisae ; @banesullivan ; @lheagy
Reviewers: @lheagy ; @thast

Merged from PR #159 #160 #163 #166

• Add (x,y,z)lim to limit the axis. It works with the interactive tools and the home-button will reset to the provided limits. Resolves #165.

• Fix Broken Example: plot_3d_slicer

• Fix refine_mesh_xyz for Tree mesh class

• Change model array shape check for VTK mixin: It must be an array of size nC

PyVista updates & deploy docs to GitHub Pages

• 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

Add representation methods for `TensorMesh`

• 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.

Tree mesh refinement

• 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

Documentation refactor

• 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/simpeg#776)

Thanks:

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

Add `fig`-parameter to `plot_3d_slicer`

• 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

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 vtkRectilinearGrids or vtki.UnstructuredGrids 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

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

# Create a plotting window
p = vtki.BackgroundPlotter()
p.show_grid()

Download a sample topography dataset using vtki to surround with a mesh

# 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

# 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

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

Finally, send the mesh to discretize for use in other processing routines

# Once satisfied, convert to discretize:
dmesh, _ = discretize.TensorMesh.vtkToTensorMesh(mesh)
dmesh

<discretize.TensorMesh.TensorMesh at 0xb2a555588>

And a GIF to demo