Source code for choclo.dipole._forward

# Copyright (c) 2022 The Choclo Developers.
# Distributed under the terms of the BSD 3-Clause License.
# SPDX-License-Identifier: BSD-3-Clause
#
# This code is part of the Fatiando a Terra project (https://www.fatiando.org)
#
import numpy as np
from numba import jit

from ..constants import VACUUM_MAGNETIC_PERMEABILITY


[docs]@jit(nopython=True) def magnetic_field( easting_p, northing_p, upward_p, easting_q, northing_q, upward_q, magnetic_moment_east, magnetic_moment_north, magnetic_moment_up, ): r""" Magnetic field due to a dipole Returns the three components of the magnetic field due to a single dipole a single computation point. .. note:: Use this function when all the three component of the magnetic fields are needed. Running this function is faster than computing each component separately. Use one of :func:`magnetic_e`, :func:`magnetic_n`, :func:`magnetic_u` if you need only one of them. Parameters ---------- easting_p : float Easting coordinate of the observation point in meters. northing_p : float Northing coordinate of the observation point in meters. upward_p : float Upward coordinate of the observation point in meters. easting_q : float Easting coordinate of the dipole in meters. northing_q : float Northing coordinate of the dipole in meters. upward_q : float Upward coordinate of the dipole in meters. magnetic_moment_east : float The East component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_north : float The North component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_up : float The upward component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. Returns ------- b : array Array containing the three components of the magnetic field generated by the dipole on the observation point in :math:`\text{T}`. The components are returned in the following order: ``b_e``, ``b_n``, ``b_u``. Notes ----- Returns the three components of the magnetic field :math:`\mathbf{B}` on the observation point :math:`\mathbf{p} = (x_p, y_p, z_p)` generated by a single dipole located in :math:`\mathbf{q} = (x_q, y_q, z_q)` and magnetic moment :math:`\mathbf{m}=(m_x, m_y, m_z)`. .. math:: \mathbf{B}(\mathbf{p}) = \frac{\mu_0}{4\pi} \left[ \frac{ 3 (\mathbf{m} \cdot \mathbf{r}) \mathbf{r} }{ \lVert r \rVert^5 } - \frac{ \mathbf{m} }{ \lVert r \rVert^3 } \right] where :math:`\mathbf{r} = \mathbf{p} - \mathbf{q}`, :math:`\lVert \cdot \rVert` refer to the :math:`L_2` norm and :math:`\mu_0` is the vacuum magnetic permeability. """ r_e = easting_p - easting_q r_n = northing_p - northing_q r_u = upward_p - upward_q distance = np.sqrt(r_e**2 + r_n**2 + r_u**2) dotproduct = ( magnetic_moment_east * r_e + magnetic_moment_north * r_n + magnetic_moment_up * r_u ) c_m = VACUUM_MAGNETIC_PERMEABILITY / 4 / np.pi b_e = c_m * ( 3 * dotproduct * r_e / distance**5 - magnetic_moment_east / distance**3 ) b_n = c_m * ( 3 * dotproduct * r_n / distance**5 - magnetic_moment_north / distance**3 ) b_u = c_m * ( 3 * dotproduct * r_u / distance**5 - magnetic_moment_up / distance**3 ) return b_e, b_n, b_u
[docs]@jit(nopython=True) def magnetic_e( easting_p, northing_p, upward_p, easting_q, northing_q, upward_q, magnetic_moment_east, magnetic_moment_north, magnetic_moment_up, ): r""" Easting component of the magnetic field due to a dipole Returns the easting component of the magnetic field by a single dipole on a single computation point Parameters ---------- easting_p : float Easting coordinate of the observation point in meters. northing_p : float Northing coordinate of the observation point in meters. upward_p : float Upward coordinate of the observation point in meters. easting_q : float Easting coordinate of the dipole in meters. northing_q : float Northing coordinate of the dipole in meters. upward_q : float Upward coordinate of the dipole in meters. magnetic_moment_east : float The East component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_north : float The North component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_up : float The upward component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. Returns ------- b_e : float Easting component of the magnetic field generated by the dipole on the observation point in :math:`\text{T}`. Notes ----- Returns the easting component :math:`B_x(\mathbf{p})` of the magnetic field :math:`\mathbf{B}` on the observation point :math:`\mathbf{p} = (x_p, y_p, z_p)` generated by a single dipole located in :math:`\mathbf{q} = (x_q, y_q, z_q)` and magnetic moment :math:`\mathbf{m}=(m_x, m_y, m_z)`. .. math:: B_x(\mathbf{p}) = \frac{\mu_0}{4\pi} \left[ \frac{ 3 (\mathbf{m} \cdot \mathbf{r}) x }{ \lVert r \rVert^5 } - \frac{ m_x }{ \lVert r \rVert^3 } \right] where :math:`\mathbf{r} = \mathbf{p} - \mathbf{q}`, :math:`\lVert \cdot \rVert` refer to the :math:`L_2` norm and :math:`\mu_0` is the vacuum magnetic permeability. """ r_e = easting_p - easting_q r_n = northing_p - northing_q r_u = upward_p - upward_q distance = np.sqrt(r_e**2 + r_n**2 + r_u**2) dotproduct = ( magnetic_moment_east * r_e + magnetic_moment_north * r_n + magnetic_moment_up * r_u ) result = 3 * dotproduct * r_e / distance**5 - magnetic_moment_east / distance**3 return VACUUM_MAGNETIC_PERMEABILITY / 4 / np.pi * result
[docs]@jit(nopython=True) def magnetic_n( easting_p, northing_p, upward_p, easting_q, northing_q, upward_q, magnetic_moment_east, magnetic_moment_north, magnetic_moment_up, ): r""" Northing component of the magnetic field due to a dipole Returns the northing component of the magnetic field by a single dipole on a single computation point Parameters ---------- easting_p : float Easting coordinate of the observation point in meters. northing_p : float Northing coordinate of the observation point in meters. upward_p : float Upward coordinate of the observation point in meters. easting_q : float Easting coordinate of the dipole in meters. northing_q : float Northing coordinate of the dipole in meters. upward_q : float Upward coordinate of the dipole in meters. magnetic_moment_east : float The East component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_north : float The North component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_up : float The upward component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. Returns ------- b_n : float Northing component of the magnetic field generated by the dipole on the observation point in :math:`\text{T}`. Notes ----- Returns the northing component :math:`B_y(\mathbf{p})` of the magnetic field :math:`\mathbf{B}` on the observation point :math:`\mathbf{p} = (x_p, y_p, z_p)` generated by a single dipole located in :math:`\mathbf{q} = (x_q, y_q, z_q)` and magnetic moment :math:`\mathbf{m}=(m_x, m_y, m_z)`. .. math:: B_y(\mathbf{p}) = \frac{\mu_0}{4\pi} \left[ \frac{ 3 (\mathbf{m} \cdot \mathbf{r}) y }{ \lVert r \rVert^5 } - \frac{ m_y }{ \lVert r \rVert^3 } \right] where :math:`\mathbf{r} = \mathbf{p} - \mathbf{q}`, :math:`\lVert \cdot \rVert` refer to the :math:`L_2` norm and :math:`\mu_0` is the vacuum magnetic permeability. """ r_e = easting_p - easting_q r_n = northing_p - northing_q r_u = upward_p - upward_q distance = np.sqrt(r_e**2 + r_n**2 + r_u**2) dotproduct = ( magnetic_moment_east * r_e + magnetic_moment_north * r_n + magnetic_moment_up * r_u ) result = ( 3 * dotproduct * r_n / distance**5 - magnetic_moment_north / distance**3 ) return VACUUM_MAGNETIC_PERMEABILITY / 4 / np.pi * result
[docs]@jit(nopython=True) def magnetic_u( easting_p, northing_p, upward_p, easting_q, northing_q, upward_q, magnetic_moment_east, magnetic_moment_north, magnetic_moment_up, ): r""" Upward component of the magnetic field due to a dipole Returns the upward component of the magnetic field by a single dipole on a single computation point Parameters ---------- easting_p : float Easting coordinate of the observation point in meters. northing_p : float Northing coordinate of the observation point in meters. upward_p : float Upward coordinate of the observation point in meters. easting_q : float Easting coordinate of the dipole in meters. northing_q : float Northing coordinate of the dipole in meters. upward_q : float Upward coordinate of the dipole in meters. magnetic_moment_east : float The East component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_north : float The North component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. magnetic_moment_up : float The upward component of the magnetic moment vector of the dipole. Must be in :math:`A m^2`. Returns ------- b_u : float Upward component of the magnetic field generated by the dipole on the observation point in :math:`\text{T}`. Notes ----- Returns the upward component :math:`B_z(\mathbf{p})` of the magnetic field :math:`\mathbf{B}` on the observation point :math:`\mathbf{p} = (x_p, y_p, z_p)` generated by a single dipole located in :math:`\mathbf{q} = (x_q, y_q, z_q)` and magnetic moment :math:`\mathbf{m}=(m_x, m_y, m_z)`. .. math:: B_z(\mathbf{p}) = \frac{\mu_0}{4\pi} \left[ \frac{ 3 (\mathbf{m} \cdot \mathbf{r}) z }{ \lVert r \rVert^5 } - \frac{ m_z }{ \lVert r \rVert^3 } \right] where :math:`\mathbf{r} = \mathbf{p} - \mathbf{q}`, :math:`\lVert \cdot \rVert` refer to the :math:`L_2` norm and :math:`\mu_0` is the vacuum magnetic permeability. """ r_e = easting_p - easting_q r_n = northing_p - northing_q r_u = upward_p - upward_q distance = np.sqrt(r_e**2 + r_n**2 + r_u**2) dotproduct = ( magnetic_moment_east * r_e + magnetic_moment_north * r_n + magnetic_moment_up * r_u ) result = 3 * dotproduct * r_u / distance**5 - magnetic_moment_up / distance**3 return VACUUM_MAGNETIC_PERMEABILITY / 4 / np.pi * result