Rename spontaneous potential to self potential (#1422)

Deprecate the `spontaneous_potential` module and replace it by the new
`self_potential`. Raise warning when importing the deprecated module.
Add tests that check the warning and if all modules in `self_potential`
are made available also in the deprecated module. Update API reference
to apply the replacement.

Closes  #1408

---------

Co-authored-by: Santiago Soler <santisoler@fastmail.com>
Co-authored-by: Joseph Capriotti <josephrcapriotti@gmail.com>

docs/content/api/SimPEG.electromagnetics.rst

@@ -10,7 +10,7 @@ Things about electromagnetics
   SimPEG.electromagnetics.static.induced_polarization
   SimPEG.electromagnetics.static.resistivity
   SimPEG.electromagnetics.static.spectral_induced_polarization
-  SimPEG.electromagnetics.static.spontaneous_potential
+  SimPEG.electromagnetics.static.self_potential
   SimPEG.electromagnetics.frequency_domain
   SimPEG.electromagnetics.natural_source
   SimPEG.electromagnetics.time_domain

docs/content/api/SimPEG.electromagnetics.static.self_potential.rst

@@ -0,0 +1 @@
+.. automodule:: SimPEG.electromagnetics.static.self_potential

simpeg/electromagnetics/static/__init__.py

@@ -1,4 +1,5 @@
 from . import resistivity
 from . import induced_polarization
+from . import self_potential
 from . import spectral_induced_polarization
 from . import utils

simpeg/electromagnetics/static/self_potential/__init__.py

@@ -0,0 +1,52 @@
+"""
+============================================================================================
+Self Potential (:mod:`simpeg.electromagnetics.static.self_potential`)
+============================================================================================
+.. currentmodule:: simpeg.electromagnetics.static.self_potential
+
+
+Simulations
+===========
+.. autosummary::
+  :toctree: generated/
+
+  Simulation3DCellCentered
+
+Receivers
+=========
+This module makes use of the receivers in :mod:`simpeg.electromagnetics.static.resistivity`
+
+Sources
+=======
+.. autosummary::
+  :toctree: generated/
+
+  sources.StreamingCurrents
+
+Surveys
+=======
+.. autosummary::
+  :toctree: generated/
+
+  Survey
+
+Maps
+====
+The self potential simulation provides two specialized maps to extend to inversions
+with different types of model sources.
+
+.. autosummary::
+  :toctree: generated/
+
+  CurrentDensityMap
+  HydraulicHeadMap
+
+"""
+
+from .simulation import (
+    Simulation3DCellCentered,
+    Survey,
+    CurrentDensityMap,
+    HydraulicHeadMap,
+)
+from . import sources

simpeg/electromagnetics/static/spontaneous_potential/simulation.py → simpeg/electromagnetics/static/self_potential/simulation.py

@@ -8,12 +8,12 @@
 
 
 class Simulation3DCellCentered(dc.Simulation3DCellCentered):
-    r"""A Spontaneous potential simulation.
+    r"""A self potential simulation.
 
     Parameters
     ----------
     mesh : discretize.base.BaseMesh
-    survey : spontaneous_potential.Survey
+    survey : simpeg.electromagnetics.static.self_potential.Survey
     sigma, rho : float or array_like
         The conductivity/resistivity model of the subsurface.
     q : float, array_like, optional
@@ -27,7 +27,7 @@ class Simulation3DCellCentered(dc.Simulation3DCellCentered):
 
     Notes
     -----
-    The charge density accumulation rate, :math:`q`, is related to the spontaneous
+    The charge density accumulation rate, :math:`q`, is related to the self
     electric potential, :math:`\phi`, with the same PDE, that relates current
     sources to potential in the resistivity case.
 

simpeg/electromagnetics/static/spontaneous_potential/__init__.py

@@ -4,6 +4,10 @@
 ============================================================================================
 .. currentmodule:: simpeg.electromagnetics.static.spontaneous_potential
 
+.. admonition:: important
+
+  This module will be deprecated in favour of ``simpeg.electromagnetics.static.self_potential``
+
 
 Simulations
 ===========
@@ -43,10 +47,23 @@
 
 """
 
-from .simulation import (
+import warnings
+
+warnings.warn(
+    (
+        "The 'spontaneous_potential' module has been renamed to 'self_potential'. "
+        "Please use the 'self_potential' module instead. "
+        "The 'spontaneous_potential' module will be removed in SimPEG 0.23."
+    ),
+    FutureWarning,
+    stacklevel=2,
+)
+
+from ..self_potential.simulation import (
     Simulation3DCellCentered,
     Survey,
     CurrentDensityMap,
     HydraulicHeadMap,
 )
-from . import sources
+from ..self_potential import sources
+from ..self_potential import simulation

tests/em/static/test_SPjvecjtvecadj.py

@@ -1,6 +1,6 @@
 import pytest
 import numpy as np
-import simpeg.electromagnetics.static.spontaneous_potential as sp
+import simpeg.electromagnetics.static.self_potential as sp
 import simpeg.electromagnetics.static.resistivity as dc
 import discretize
 from simpeg import utils
@@ -117,3 +117,29 @@ def test_clears():
     sim.qMap = maps.ExpMap()
     assert sim.deleteTheseOnModelUpdate == ["_Jmatrix", "_gtgdiag"]
     assert sim.clean_on_model_update == []
+
+
+def test_deprecations():
+    """
+    Test warning after importing deprecated `spontaneous_potential` module
+    """
+    msg = (
+        "The 'spontaneous_potential' module has been renamed to 'self_potential'. "
+        "Please use the 'self_potential' module instead. "
+        "The 'spontaneous_potential' module will be removed in SimPEG 0.23."
+    )
+    with pytest.warns(FutureWarning, match=msg):
+        import simpeg.electromagnetics.static.spontaneous_potential  # noqa: F401
+
+
+def test_imported_objects_on_deprecated_module():
+    """
+    Test if the new `self_potential` module and the deprecated `spontaneous
+    potential` have the same members.
+    """
+    import simpeg.electromagnetics.static.spontaneous_potential as spontaneous
+
+    members_self = set([m for m in dir(sp) if not m.startswith("_")])
+    members_spontaneous = set([m for m in dir(spontaneous) if not m.startswith("_")])
+    difference = members_self - members_spontaneous
+    assert not difference