irfpy.util.dipole

Dipole fields, such as electric or magnetic fields.

Code author: Yoshifumi Futaana

See also irfpy.util.fields.DipoleField to obtain the 3-D field (vector at a specific position).

A dipole is expressed by the following equations. (Look at any text book for derivation.) The sample is for magnetic field.

\[\vec{B} = \frac{\mu_0}{4\pi} \Bigl[\frac{3\vec{r}(\vec{r}\cdot\vec{m})- r^2\vec{m}}{r^5} + \frac{8\pi}{3}\vec{m}\delta^3(\vec{r})\Bigr]\]

If you change the first coefficient \(\frac{\mu_0}{4\pi}\) to \(\frac{1}{4\pi\epsilon_0}\), it expresses the electric dipole.

The above equation can be expressed in the polar coordinate system very simply.

\[\begin{split}B_r = \frac{\mu_0 m}{4\pi}\frac{2\cos\theta}{r^3} \\ B_\theta = \frac{\mu_0 m}{4\pi}\frac{\sin\theta}{r^3}\end{split}\]

For L-value calculation, use lvalue().

irfpy.util.dipole.fieldline(crossing, dipole_vector=array([0, 0, 1]), ndiv=181)[source]

Calculate the field line in 3-D space.

Calculate the filed line that crosses the crossing point.

Parameters:

  • crossing – A numpy array shape=(3,) specifying the crossing point.

  • dipole_vector – A dipole vector (np.array with shape (3,) placed at the origin.

  • ndiv – Resolution.

Returns:

np.array in (3, ndiv) shaped coordinates of the field line.

See YF-Bnote 130304 for derivation.

irfpy.util.dipole.fieldline_rt(l, ndiv=181)[source]

With a specific L-value, list of the coordinate system is returned.

Parameters:

  • l – The L-value. You may use lvalue() to derive the L-value of the arbitrary position.

  • ndiv – Resolution. Returned array will have a shape of (ndiv)

Returns:

Tuple of numpy array, (r, t), where r is the radius and t is the angle in radians.

For this function, a dipole moment is assumed to align z-axis.

The field line is (see lvalue()) expressed by

\[r = L \sin^2\theta\]
>>> rlist, thlist = fieldline_rt(1.)
>>> print('%.2f %.2f' % (rlist[90], thlist[90]))   # 90 deg.
1.00 1.57
>>> print('%.2f %.2f' % (rlist[45], thlist[45]))   # 45 deg.
0.50 0.79
irfpy.util.dipole.lvalue_rt(r, t)[source]

Return the L-value in the polar coordinates.

Parameters:

  • r – The (list of) distance.

  • t – The (list of) angle in degrees from the dipole vector direction.

>>> print(lvalue_rt([1, 2, 3], [45, 90, 135]))   
[2.  2.  6.]
irfpy.util.dipole.lvalue(x, z)[source]

Return the L-value.

Return the L-value. Consider the magnetic dipole (or equivalent), \(\vec{m}\), along z-axis. The field line starting position of (x, z) hit the z=0 is so-called L-value.

Parameters:

  • x – The (list of) position.

  • z – The (list of) position.

Returns l:

The (list of) L-value.

>>> print(lvalue(5.0, 0.0))
5.0

>>> print(lvalue([5.0, 5.0], [0.0, 5.0]))    
[  5.          14.14213562]

>>> print(lvalue(5.0, -5.0))
14.142135623730951

The field line can be traced by the equation

\[\frac{B_r}{dr} = \frac{B_\theta}{rd\theta}\]

This can be rewritten as

\[\frac{dr}{r} = 2\frac{\cos\theta}{\sin\theta}d\theta\]

Integration will give us

\[\ln r = 2 \ln|\sin\theta| + C\]

or

\[r = L \sin^2\theta\]
irfpy.util.dipole.distance_along(theta0, theta1, lvalue)[source]

Calculate distance between the specified angles.

On the same l-value, the distance between the latitudes \(\theta_0\) and \(\theta_1\) can be calculated, and returned.

Parameters:

  • theta0 – Angle in degrees.

  • theta1 – Angle in degrees.

  • lvalue – The L-value.

For L=10, the distance between the pole and the equator is

>>> print('%.3f' % distance_along(0, 90, 10.0))
13.802

The distance between the poles are >>> print(‘%.3f’ % distance_along(0, 180, 10.0)) 27.603

Numpy array can be given for angles.

>>> l0, l1, l2 = distance_along([0, 0, 90], [0, 90, 180], [5.0, 5.0, 20.0])
>>> print('%.3f' % l0)
0.000
>>> print('%.3f' % l1)
6.901
>>> print('%.3f' % l2)
27.603

Derivation

\[\begin{split}x &=& r \sin\theta \\ z &=& r \cos\theta \\ l &=& \int d\theta\sqrt{\dot{x}^2+\dot{z}^2} \\\end{split}\]

Here the dot specifies the differentiation by \(\theta\), and therefore

\[\begin{split}\dot{x} &=& L\sin^3\theta \\ \dot{z} &=& L\sin^2\theta\cos\theta \\\end{split}\]

Substituting to \(l\) and proceed the calculation, you will get

\[l &=& L \int d\theta \sqrt{\sin^2\theta(1 + 3 \cos^2\theta)}\]

Using \(t=\cos\theta\),

\[l &=& -L \int dt \sqrt{1+3t^2}\]

With a help of Mathematica :) you get

\[l &=& -L \Bigl(\frac{1}{6}(3t\sqrt{3t^2+1}+\sqrt{3}\mathrm{arcsinh}(\sqrt{3}t))\Bigr)\]

Here, arcsinh is the inverse-hyperbolic-sin function. This forumulation is valid for the angle between 0 and 180 degrees.

irfpy.util.dipole.doctests()[source]