Merge branch 'main' into add_asa_tilt

.gitignore

@@ -12,6 +12,7 @@ doc/_build
 doc/api/generated
 doc/gallery
 doc/sample_data
+doc/sg_execution_times.rst
 .ipynb_checkpoints
 *.egg-info
 MANIFEST

doc/api/index.rst

@@ -81,7 +81,6 @@ Magnetic fields:
  :toctree: generated/
 
  dipole_magnetic
- dipole_magnetic_component
  prism_magnetic
 
 Layers and meshes:

doc/conf.py

@@ -130,7 +130,9 @@
 # HTML output configuration
 # -----------------------------------------------------------------------------
 html_title = f'{project} <span class="project-version">{version}</span>'
-html_logo = "_static/harmonica-logo.png"
+# Don't use the logo since it gets in the way of the project name and is
+# repeated in the front page.
+# html_logo = "_static/harmonica-logo.png"
 html_favicon = "_static/favicon.png"
 html_last_updated_fmt = "%b %d, %Y"
 html_copy_source = True

doc/index.rst

@@ -21,7 +21,7 @@
 
  .. image:: ./_static/harmonica-logo.svg
  :width: 200px
- :class: sd-m-auto
+ :class: sd-m-auto dark-light
 
 **Harmonica** is a Python library for processing and modeling gravity and
 magnetic data.

doc/install.rst

@@ -3,20 +3,48 @@
 Installing
 ==========
 
+There are different ways to install Harmonica:
+
+.. tab-set::
+
+ .. tab-item:: pip
+
+ Using the `pip package manager <https://pypi.org/project/pip/>`__:
+
+ .. code:: bash
+
+ pip install harmonica
+
+ .. tab-item:: conda/mamba
+
+ Using the `conda package manager <https://conda.io/>`__ (or ``mamba``)
+ that comes with the Anaconda/Miniconda distribution:
+
+ .. code:: bash
+
+ conda install harmonica --channel conda-forge
+
+ .. tab-item:: Development version
+
+ You can use ``pip`` to install the latest **unreleased** version from
+ GitHub (**not recommended** in most situations):
+
+ .. code:: bash
+
+ python -m pip install --upgrade git+https:/fatiando/harmonica
+
+.. note::
+
+ The commands above should be executed in a terminal. On Windows, use the
+ ``cmd.exe`` or the "Anaconda Prompt" app if you’re using Anaconda.
+
+
 Which Python?
 -------------
 
 You'll need **Python 3.8 or greater**.
 See :ref:`python-versions` if you require support for older versions.
 
-We recommend using the
-`Anaconda Python distribution <https://www.anaconda.com/download>`__
-to ensure you have all dependencies installed and the ``conda`` package manager
-available.
-Installing Anaconda does not require administrative rights to your computer and
-doesn't interfere with any other Python installations in your system.
-
-
 Dependencies
 ------------
 
@@ -56,53 +84,3 @@ The examples in the :ref:`gallery` also use:
 * `ensaio <http://www.fatiando.org/ensaio/>`__ for downloading sample datasets
 * `pygmt <https://www.pygmt.org/>`__ for plotting maps
 * `pyproj <https://jswhit.github.io/pyproj/>`__ for cartographic projections
-
-
-
-Installing with conda
----------------------
-
-You can install Harmonica using the `conda package manager
-<https://conda.io/>`__ that comes with the Anaconda distribution::
-
- conda install harmonica --channel conda-forge
-
-
-Installing with pip
--------------------
-
-Alternatively, you can also use the `pip package manager
-<https://pypi.org/project/pip/>`__::
-
- pip install harmonica
-
-
-Installing the latest development version
------------------------------------------
-
-You can use ``pip`` to install the latest source from Github::
-
- pip install git+https:/fatiando/harmonica
-
-Alternatively, you can clone the git repository locally and install from
-there::
-
- git clone https:/fatiando/harmonica.git
- cd harmonica
- pip install .
-
-
-Testing your install
---------------------
-
-We ship a full test suite with the package.
-To run the tests, you'll need to install some extra dependencies first:
-
-* `pytest <https://docs.pytest.org/>`__
-* `boule <http://www.fatiando.org/boule/>`__
-
-After that, you can test your installation by running the following inside
-a Python interpreter::
-
- import harmonica
- harmonica.test()

doc/user_guide/forward_modelling/dipole.rst

@@ -4,11 +4,7 @@ Magnetic dipoles
 ================
 
 We can compute the magnetic field generated by dipole sources through
-:func:`harmonica.dipole_magnetic` and
-:func:`harmonica.dipole_magnetic_component` functions.
-The former computes the three components of the magnetic field generated by
-a set of dipoles on every observation point, while the latter computes only
-a single component.
+the :func:`harmonica.dipole_magnetic` function.
 
 Each dipole can be defined as a tuple containing its coordinates in the
 following order: *easting*, *northing*, *upward* (in Cartesian coordinates and
@@ -27,36 +23,37 @@ Define the dipole and its magnetic moment vector:
 .. jupyter-execute::
 
  dipole = (20, 40, -50)
- magnetic_moment = [100, 100, 100]
+ magnetic_moment = (100, 100, 100)
 
 Define the observation point above it:
 
 .. jupyter-execute::
 
  coordinates = (20, 40, 10)
 
-And compute the three components of the magnetic field the dipole generates:
+And compute the three components of the magnetic field the dipole generates by
+choosing ``field="b"``:
 
 .. jupyter-execute::
 
- b_e, b_n, b_u = hm.dipole_magnetic(coordinates, dipole, magnetic_moment)
+ b_e, b_n, b_u = hm.dipole_magnetic(coordinates, dipole, magnetic_moment, field="b")
  print(b_e, b_n, b_u)
 
-We can use :func:`harmonica.dipole_magnetic_component` to compute just a single
-component:
+We can compute just a single component with ``field`` set to ``"b_e"``,
+``"b_n"`` or ``"b_u"``:
 
 .. jupyter-execute::
 
- b_u = hm.dipole_magnetic_component(
- coordinates, dipole, magnetic_moment, component="upward"
+ b_u = hm.dipole_magnetic(
+ coordinates, dipole, magnetic_moment, field="b_u"
  )
  print(b_u)
 
 
 Multiple dipoles
 ----------------
 
-These two functions also allow us to compute the magnetic fields of multiple
+We can also use this function to compute the magnetic fields of multiple
 dipoles on multiple observation points.
 
 Let's define a regular grid of observation points:
@@ -83,19 +80,17 @@ And a set of dipoles with their magnetic moments:
  upward = [-200, -100, -300, -150]
  dipoles = (easting, northing, upward)
 
- magnetic_moments = np.array([
- [1e3, 1e3, 1e3],
- [2e3, 2e3, 2e3],
- [500, 500, 500],
- [2e3, 2e3, 2e3],
- ])
+ mag_e = [1e3, 2e3, 500, 2e3]
+ mag_n = [1e3, 2e3, 500, 2e3]
+ mag_u = [1e3, 2e3, 500, 2e3]
+ magnetic_moments = (mag_e, mag_n, mag_u)
 
 Now, let's compute the magnetic field components that the dipoles generate on
 every observation point:
 
 .. jupyter-execute::
 
- b_e, b_n, b_u = hm.dipole_magnetic(coordinates, dipoles, magnetic_moments)
+ b_e, b_n, b_u = hm.dipole_magnetic(coordinates, dipoles, magnetic_moments, field="b")
 
 .. jupyter-execute::
 

env/requirements-docs.txt

@@ -1,10 +1,10 @@
 # Documentation building requirements
-sphinx==4.5.*
-sphinx-book-theme==0.2.*
-sphinx-gallery==0.10.*
-sphinx-design==0.2.*
+sphinx==7.2.*
+sphinx-book-theme==1.1.*
+sphinx-gallery==0.15.*
+sphinx-design==0.5.*
 sphinx-copybutton==0.5.*
-jupyter-sphinx==0.4.*
+jupyter-sphinx==0.5.*
 ipykernel
 boule
 pyproj

environment.yml

@@ -27,12 +27,12 @@ dependencies:
  - coverage
  - boule
  # Documentation requirements
- - sphinx==4.5.*
- - sphinx-book-theme==0.2.*
- - sphinx-gallery==0.10.*
- - sphinx-design==0.2.*
+ - sphinx==7.2.*
+ - sphinx-book-theme==1.1.*
+ - sphinx-gallery==0.15.*
+ - sphinx-design==0.5.*
  - sphinx-copybutton==0.5.*
- - jupyter-sphinx==0.4.*
+ - jupyter-sphinx==0.5.*
  - ipykernel
  - pyproj
  - matplotlib

harmonica/__init__.py

@@ -9,7 +9,7 @@
 from ._equivalent_sources.cartesian import EquivalentSources
 from ._equivalent_sources.gradient_boosted import EquivalentSourcesGB
 from ._equivalent_sources.spherical import EquivalentSourcesSph
-from ._forward.dipole import dipole_magnetic, dipole_magnetic_component
+from ._forward.dipole import dipole_magnetic
 from ._forward.point import point_gravity
 from ._forward.prism_gravity import prism_gravity
 from ._forward.prism_layer import DatasetAccessorPrismLayer, prism_layer
@@ -35,51 +35,3 @@
 
 # Append a leading "v" to the generated version by setuptools_scm
 __version__ = f"v{__version__}"
-
-
-def test(doctest=True, verbose=True, coverage=False, figures=False):
- """
- Run the test suite.
-
- Uses `py.test <http://pytest.org/>`__ to discover and run the tests.
-
- Parameters
- ----------
-
- doctest : bool
- If ``True``, will run the doctests as well (code examples that start
- with a ``>>>`` in the docs).
- verbose : bool
- If ``True``, will print extra information during the test run.
- coverage : bool
- If ``True``, will run test coverage analysis on the code as well.
- Requires ``pytest-cov``.
- figures : bool
- If ``True``, will test generated figures against saved baseline
- figures. Requires ``pytest-mpl`` and ``matplotlib``.
-
- Raises
- ------
-
- AssertionError
- If pytest returns a non-zero error code indicating that some tests have
- failed.
-
- """
- import pytest
-
- package = __name__
- args = []
- if verbose:
- args.append("-vv")
- if coverage:
- args.append("--cov={}".format(package))
- args.append("--cov-report=term-missing")
- if doctest:
- args.append("--doctest-modules")
- if figures:
- args.append("--mpl")
- args.append("--pyargs")
- args.append(package)
- status = pytest.main(args)
- assert status == 0, "Some tests have failed."