fatiando/fatiando — pull request #137 by leouieda (2014-11-08 17:09:06+00:00)
Title: An Object Oriented interface for seismic wave finite-differences simulations

Implement "simulator" objects to run the finite-differences time steppers. Re-uses the Cython time-steps and wraps them in classes, instead of the old generator functions (using `yield` statements).

Based on [this prototype](http://nbviewer.ipython.org/github/fatiando/prototypes/blob/master/wavefd-simulation-class.ipynb).

## Storage

The simulation classes store each time frame in an [HDF5](http://www.h5py.org/) file. When you need the simulation results, the class digs into the cache file and returns the data requested. Animation methods load the snapshots from the file and make animations using matplotlib.animate.

The cache file stores all data needed to resume a simulation later. The `from_cache` method rebuilds a simulation object from the cache file and computations can be resumed right away, Source functions are also stored in the cache file as pickles.

## Rich display

Simulation and source wavelet classes have rich display capabilities for use with IPython notebooks. The `snapshot` method loads a time step from the cache file and plots it. The `_repr_png_` for the simulations is the last time step. There is an option to convert the animation to a video and embed it in the IPython notebook.

## Sample usage

A sample notebook using the code from this PR is on the [tutorials repo](http://nbviewer.ipython.org/github/fatiando/tutorials/tree/master/). It will be updated along with the PR.

## Testing

- [ ] We need an analytic solution against which we can test the simulation results.
- [ ] I would also like to have Python+numpy versions of the time stepping function so that we can test them against each other (and also use as a benchmark). It wouldn't hurt having a numba implementation as well.

## TODO

- [ ] Allow the user to specify the boundary conditions. Right now they are fixed as free-surface on top and absorbing on the other sides.
- [ ] Get rid of redundancy in plotting functions. There is a lot of repeated code.
- [ ] Clean-up the way things are stored in the cache file. My use of HDF5 is far from ideal.
- [ ] Try to adapt the elastic P-SV time step so that I don't have to copy (and make C-contiguous) the arrays when initializing the simulation (in the beginning of `run`).
- [ ] Figure out what to do with old code. Should we delete it or only deprecate it (and stop using it in the cookbook). I think deleting wouldn't be too back since not many people use it anyway. Plus, the simulation classes are just so much better.
- [ ] Adapt the new stuff (migration, 3D, etc) by @eusoubrasileiro.

## Checklist

- [ ] Make tests for new code
- [ ] Create/update docstrings
- [ ] Update requirements
- [ ] Code follows PEP8 style conventions
- [ ] Code and docs have been spellchecked
- [ ] Changelog entry
- [ ] Documentation builds properly
- [ ] All tests pass
- [ ] Can be merged