simpeg/simpeg: Simulation Article Swipe

SimPEG 0.14.0 Release Notes This release marks a major change in the structure of SimPEG, and it all started with this, #562: What's the problem with <code>Problem</code>? We hope to answer that question with this release! This release will break backward compatibility as many modules and classes have been renamed. Check out the Examples and Tutorials (which have also been improved) to see how it's done. We are also only supporting Python versions &gt;=3.6 at this time. We have dropped all testing and development on Python versions previous to this (especially 2.7). Highlights No more <code>Problem</code>-s, only <code>Simulation</code>-s <code>Data</code> is important PEP 8 renaming Dask parallelism Resistivity Simulation improvements Simulation We will refer to this update as the simulation update, and there are a few large changes that we will attempt to describe here. We (the developers) believed that there were some significant challenges with the overall structure of the SimPEG framework, which all revolved around constructing a forward simulation by <code>pair</code>-ing a <code>Survey</code> and a <code>Problem</code>. The <code>Survey</code> handled things like sources, receivers, and the <code>Problem</code> handled the physics engine of the forward simulation. These two items had to be created separately, then <code>pair</code>-ed afterwards for both the <code>Problem</code> to be able to use sources, and for the <code>Survey</code> to predict data. We found that this structure made it difficult to interface with other packages and was also generally difficult to explain. Also, field data was then attached to the <code>Survey</code> class. These changes within this section are also the ones which will require the most changes to code (which are still hopefully small). The <code>Simulation</code> class <code>Problem</code> has been renamed to <code>Simulation</code> We decided to refactor this code into something a little more understandable. The <code>Simulation</code> class is now the workhorse of the SimPEG forward simulations. It handles things like modeling fields and projecting those fields to the data locations defined by its <code>survey</code>. The <code>Survey</code> class is much lighter weight, now only handling the sources and receivers. Also a single <code>survey</code> can now be attached to many <code>Simulation</code>-s. Previously we had something like, <pre><code>survey = DC.Survey(srcList) prob = DC.Problem3D_CC(mesh, rhoMap=mapping) prob.pair(survey) # Compute the fields from `prob` fields = prob.fields(model) # And predict data using the `survey` dpred = survey.dpred(model, f=fields) </code></pre> Now, <pre><code>survey = resistivity.Survey([source_list]) sim = resistivity.Simulation3DCellCentered( mesh, survey=survey, rhoMap=mapping ) # Compute the fields from `sim` fields = sim.fields(model) # Predict data also using `sim` dpred = sim.dpred(model, f=fields) </code></pre> See? The <code>Simulation</code> handles predicting data. This change will also make it easier to interface with external codes for inversion purposes, as all that is needed to be defined to use a <code>Simulation</code> for an <code>InvProblem</code>, is <code>sim.dpred</code>, <code>sim.Jvec</code> and <code>sim.Jtvec</code>. Please see the documentation for the <code>SimPEG.simulation.BaseSimulation</code> class as well as the individual methods' <code>Simulation</code>-s, for a detailed description of arguments, but largely it accepts the same arguments as the <code>Problem</code> class, but now also requires a <code>Survey</code> to be set. The <code>Data</code> class Previously, field data would also live within the <code>Survey</code> class. Which was not only confusing, but placed the importance on the wrong component. When inverting geophysical data, we are concerned with the data. Thus we would like to enforce this importance by making data live in a dedicated <code>Data</code> class. This <code>Data</code> class can act like a smart dictionary to grab data associated with a specific source, receiver combination. More importantly, this <code>Data</code> class is where we store information related to observed data and its errors. This class started in the <code>SimPEG.Survey</code> module, but has now been moved into its own new module <code>SimPEG.data</code>. See the documentation for the <code>SimPEG.data.Data</code> for all of the details. Previously, <pre><code># Add data to the survey survey.dobs = dobs survey.std = 0.05 # a 5% relative error survey.eps = 1.0E-6 # a noise floor </code></pre> Now, <pre><code># Create a data object data = data.Data(dobs=dobs, relative_error=0.05, noise_floor=1e-6) </code></pre> You might also notice that we changed the name of the terms used to construct the standard deviation. See issue #846. Previously <code>survey.std</code> represented an error that was relative to the absolute value of the data. The name of this term is misleading, as it is not actually the classic statistical standard deviation. Previously the uncertainty was constructed as: <pre><code>uncertainty = survey.std * np.abs(survey.dobs) + survey.eps </code></pre> We now have updated the names to be clearer and more in line with what we would naturally expect, which is accessed from <code>data.standard_deviation</code>. The value that is returned from this is now defined as: <pre><code>data.standard_deviation = ( data.relative_error * np.abs(data.dobs) + data.noise_floor ) </code></pre> You can also directly set the value of <code>data.standard_deviation</code> if you prefer to work with that quantity. <pre><code>data.standard_deviation = 0.01 </code></pre> This <code>Data</code> class is now also the object that is returned from: <pre><code>data = sim.make_synthetic_data( m, relative_error=0.05, noise_floor=0.0, f=None, add_noise=True ) </code></pre> The <code>DataMisfit</code> class Previously, because the <code>Survey</code> class handled predicting data at the receivers, and it also had knowledge of the observed data and its noise, we constructed the data misfit measure using only the survey. Now we have specifically broken this piece up into a forward <code>Simulation</code> object, and a <code>Data</code> object. This mimics the definition of the classic data misfit measure. &lt;img width="198" alt="image" src="https://user-images.githubusercontent.com/16258927/83070396-a8d6b200-a028-11ea-9a7c-7600526ec378.png"&gt; The <code>Simulation</code> class handles the forward operation, &lt;img width="14" alt="image" src="https://user-images.githubusercontent.com/16258927/83070609-f81ce280-a028-11ea-87f6-2a2a938860e0.png"&gt;, and the <code>Data</code> class handles the noise, &lt;img width="108" alt="image" src="https://user-images.githubusercontent.com/16258927/83070437-b5f3a100-a028-11ea-8957-61fc6801a9fe.png"&gt;, and the observed data, &lt;img width="26" alt="image" src="https://user-images.githubusercontent.com/16258927/83070484-c7d54400-a028-11ea-8c68-801029afcaf6.png"&gt;. See the documentation for the <code>SimPEG.data_misfit.L2DataMisfit</code> for all of the details. Previously, <pre><code># Survey knows how to predict data, knows the observed data, # and its standard deviation dmis = DataMisfit.l2_DataMisfit(survey) </code></pre> Now, <pre><code># Create a data misfit # The data class now knows the observed data and its standard deviation. # The simulation knows how to create data from a model. dmis = data_misfit.L2DataMisfit(simulation=sim, data=data) </code></pre> Dask We have begun a concerted effort to incorporate <code>dask</code> as a means to allow SimPEG to scale to larger computers (and take advantage of parallelism). Checkout the <code>dask</code> docs at https://docs.dask.org/en/latest/. This feature is experimental at the moment and can be toggled on like so, <pre><code>import SimPEG.dask </code></pre> which will then enable parallel operations for a few modules. It will specifically replace these functions with <code>dask</code> versions, <code>SimPEG.potential_fields.BasePFSimulation.linear_operator</code> <code>SimPEG.potential_fields.magnetics.Simulation3DIntegral.getJtJdiag</code> <code>SimPEG.potential_fields.gravity.Simulation3DIntegral.getJtJdiag</code> <code>SimPEG.electromagnetics.static.resistivity.simulation.BaseDCSimulation.getJ</code> <code>SimPEG.electromagnetics.static.resistivity.simulation.BaseDCSimulation.getJtJdiag</code> <code>SimPEG.electromagnetics.static.induced_polarization.simulation.BaseDCSimulation.getJ</code> <code>SimPEG.electromagnetics.static.induced_polarization.simulation.BaseDCSimulation.getJtJdiag</code> Changelog As can be expected, there are many changes in this release, and we hope to identify most of them here (or at least point you in the right direction). Renamed Modules We have taken steps to rename the modules of SimPEG to a more PEP 8 friendly system. The previous locations do not exist. <code>EM</code> → <code>electromagnetics</code> <code>EM.FDEM</code> → <code>electromagnetics.frequency_domain</code> <code>EM.TDEM</code> → <code>electromagnetics.time_domain</code> <code>EM.NSEM</code> → <code>electromagnetics.natural_source</code> <code>EM.Static</code> → <code>electromagnetics.static</code> <code>EM.Static.DC</code> → <code>electromagnetics.static.resistivity</code> <code>EM.Static.DC.Utils</code> → <code>electromagnetics.static.resistivity.utils</code> <code>EM.Static.IP</code> → <code>electromagnetics.static.induced_polarization</code> <code>EM.Static.SIP</code> → <code>electromagnetics.static.spectral_induced_polarization</code> <code>EM.Static.Utils</code> → <code>electromagnetics.static.utils</code> <code>EM.Utils</code> → <code>electromagnetics.utils</code> <code>VRM</code> → <code>electromagnetics.viscous_remanent_magnetization</code> <code>FLOW</code> → <code>flow</code> <code>SEIS</code> → <code>seismic</code> <code>PF</code> → <code>potential_fields</code> <code>PF.Gravity</code> → <code>potential_fields.gravity</cod