Goals and Scope

[rowanc1]

Overview

The goal of this package is to create a repository for the growing number of analytic functions that are currently scattered throughout the SimPEG repository and those in the http://geosci.xyz educational materials. The current analytics range from electromagnetics to fluid flow to earthquake displacement to gravity. The scope will hopefully grow outside of these analytics to include other geoscience related analytic and simple numerical functions. We hope to collaborate with other geoscience package developers.

Why

Analytics are often locked up in textbooks in a static form, however, to actually make use of them we have to: transcribe the equation, give meaning to the greek letters, create a plot, a function, a test, and finally play with all of the parameters to gain some geo-scientific intuition. This intuition is invaluable to students. This interrogation is necessary for research.

The process of going from a static equation to a plot that is inviting to change and interrogate is an involved procedure. This is not the focus of students or researchers, as such, the output of many current efforts is (potentially) a standalone package with scattered functionality but, more often than not, a neglected script that has limited scope and use beyond the author. This means the next curious geoscientist starts by squinting at the pixelated equation.

Much of the implementation and infrastructure details are similar between these analytics. What we are proposing (and will pursue within the initial scope of the SimPEG organization) is that the analytics be accessible in a common way. A geoscience repository for analytic functions, visualizations, and interactive widgets.

Philosophy

1. The analytics are classes - there is inheritance and shared functionality
2. The interface is consistent - set params, solve, plot, repeat
3. They are interactive by default - think like a student; we are all here to learn
4. The parameters are strongly typed - with useful errors and auto-documentation
5. The math, descriptions and citations are first class - like a text book, but actually useful

Interaction

We will give two examples, one from our repositories and one from an external repo. The implementation is a sketch at how the package might be used.

First, a sketch at the interaction for a magnetic dipole in a wholespace (time-domain):

from geoana.em.tdem import MagDipoleWholespace
mdw = MagDipoleWholespace(location=[0,0,0])
mdw.orientation = 'up'
print(mdw.orientation)  # [1,0,0] coercion and validation
mdw.moment = 50.
mdw.sigma = 1e-2  # Electrical conductivity

ex = mdw.electric_field(xyz, component='x', **options) # component can be any orientation

mdw.plot() # that is just the default plot

mdw.plot_fields()  # type `plot <tab>` and see all the options!

mdw.interact()  # shows a widget!

print(mdw.description)  # tell me something
print(mdw.math)  # shows the math
print(mdw.cite)  # who should we cite?

Second, a sketch at a rate-state-friction model from @jrleeman et al on https://github.com/jrleeman/rsfmodel :

from geoana.seismic import RateStateFiction as rsf # not sure of path etc.
model = rsf(mu0=0.6)
print(model.vref, model.vref.__doc__)  # 10. Reference velocity
print(type(rsf.state_relations[0]))  # "DieterichState"
rsf.state_relations[0].Dc = 10.  # Set critical slip distance

model.plot_phase()  # Make the phase plot
model.interact()  # etc.

The implementation would build on many of the advancements being made by the Jupyter organization for integration with interactive computation. Namely traitlets and ipywidgets. We will automate as much of the testing and documentation as is (inhumanly?) possible.

We note that it is likely that existing packages will want to keep the analytics inside the scope of their package. As this project matures we will provide base classes that hopefully can be used by those authors, these classes will be light-wrappers on the Jupyter codebase to add some geoscience scope and structure.

Vision

Putting these analytics in one place, or at least promoting the use of a common interface will:

• lower the barrier to entry to these analytic and simple numerical functions
• allow their reuse in educational and computational materials (e.g. geosci textbooks)
• become a resource that is cross-disciplinary and perhaps promote interesting conversations
• promote infrastructure investment and updates, e.g. deploy geoana to serve dynamic plots in your blog

An example of what may come out of this work is here, but the future is refactored and interactive:
http://em.geosci.xyz/content/maxwell2_dc/fields_from_grounded_sources_dcr/electrostatic_sphere.html

A web-based interface to interact with these equations:

Request for comments

Over the next month @lheagy and I will be sketching the basic infrastructure and will be very interested in getting comments from other geoscience package developers to help refine the scope and interface as well as map out the necessary functionality.

Some potential overlaps:

• https://github.com/agile-geoscience/bruges
• https://github.com/fatiando/fatiando
• https://github.com/jrleeman/rsfmodel
• https://github.com/simpeg/simpeg
• https://github.com/ubcgif
• many more, but that is kinda the point

From simpeg/simpeg#412

cc @simpeg/developers @kwinkunks @leouieda @jrleeman @EvanBianco

[lheagy]

also cc @dougoldenburg, @yangdikun, @thast, @fourndo, @dccowan, @krisdavis, @Pbellive, @sdevriese

[leouieda]

@rowanc1 and @lheagy this is great! I like the idea of pulling out common denominators. One thing that I didn't understand is what you mean by "analytics". Is it like "analytic solutions" (not numerical)? Or like "google analytics" (data analysis)?

Either way, it's good to have this discussion. Collectively, we've gotten a lot of experience with our different projects. The goals and designs are a bit different but there is a lot of overlap.

[lheagy]

Hey @leouieda, we are thinking analytic solutions (not data analysis), and perhaps some semi-analytic / simple numeric solutions.

With simpeg and educational resources we have been working on, analytics often rapidly become a set of utils with inconsistent inputs and outputs. The aim here would be to give them more structure.

[leouieda]

OK! Well, this is mostly what we have in Fatiando. There are very few numerical solutions (in the sense of PDEs like simpeg). Any code we have there can be copied over here as well without a problem.

I've been struggling with the design of these functions for some time. One problem with having classes is that the physical objects will have to know how to compute their own fields. This can become strange when you have solutions for very different methods, like gravity and seismic. Where would the class live?

The way it's implemented in Fatiando is that physical objects are separated from the actual analytic solutions. This is nice because it's a bit simpler to use these functions in inversions. But there is the drawback that you don't easily get all the interactivity you're proposing.

analytics often rapidly become a set of utils with inconsistent inputs and outputs. The aim here would be to give them more structure.

That'll be a big challenge because they do need different inputs. It will be very hard to design something that is very consistent and will stay that way as more solutions are added.

[jrleeman]

A lot of the rsfmodel stuff in numerical, but pretty simple. This sounds like a great plan and very useful! I'm also separated into physical entities, but much smaller ones. Hopefully I can get some other functionality in to play with soon as well!