Source code for gtsimulation.magnetic_field.magnetosphere._dipole

import datetime
from collections.abc import Sequence
from pathlib import Path

import numpy as np
from numba import njit

from gtsimulation.common import Units, Regions
from gtsimulation.magnetic_field import AbsBfield


[docs] class Dipole(AbsBfield): """ Static magnetic dipole field. Parameters ---------- B_eq : float or None, optional Equatorial field at the reference radius, in nT. If None, use the Earth normalization: 30100 nT, or the coefficient fit for date. Default is None. reference_radius : float, optional Radius at which B_eq is specified, in metres. Default is Units.RE. direction : array-like, shape (3,), optional Nonzero magnetic moment direction, normalized automatically. Default is (0, 0, -1), matching the Earth dipole polarity. center : array-like, shape (3,), optional Dipole center in metres. Default is (0, 0, 0). name : str or None, optional Object name for the GT logger. If None, use "Earth" when B_eq is omitted, otherwise "Custom dipole". Default is None. date : datetime.datetime or None, optional Date for the Earth normalization fit (1900--2021), used when B_eq is omitted. None selects the fixed 30100 nT value. Default is None. Notes ----- calc_field accepts coordinates in units of reference_radius and returns magnetic field components in nT. The reference radius sets the field normalization, not a surface boundary. """ to_meters = Units.RE2m def __init__(self, B_eq: float | None = None, reference_radius: float = Units.RE2m, direction: Sequence[float] | np.ndarray = (0, 0, -1), center: Sequence[float] | np.ndarray = (0, 0, 0), name: str | None = None, date: datetime.datetime | None = None) -> None: super().__init__() self.Region = Regions.Magnetosphere self.ModelName = "Dipole" self.to_meters = reference_radius self.direction = np.array(direction, dtype=float) self.direction /= np.linalg.norm(self.direction) self.center = np.array(center, dtype=float) self.name = name or ("Earth" if B_eq is None else "Custom dipole") self.Date = date self.B_eq = 30100.0 if B_eq is None else B_eq self._earth_normalization = B_eq is None if date is not None: self.update_state(date)
[docs] def calc_field(self, x, y, z): return self._calc_field(x - self.center[0] / self.to_meters, y - self.center[1] / self.to_meters, z - self.center[2] / self.to_meters, self.B_eq, self.direction)
@staticmethod @njit(fastmath=True) def _calc_field(x, y, z, B_eq, direction): r2 = x * x + y * y + z * z scale = B_eq / (r2 * np.sqrt(r2)) projection = (direction[0] * x + direction[1] * y + direction[2] * z) / r2 return (scale * (3 * projection * x - direction[0]), scale * (3 * projection * y - direction[1]), scale * (3 * projection * z - direction[2]))
[docs] def update_state(self, new_date: datetime.datetime): self.Date = new_date if self._earth_normalization: assert 1900 <= new_date.year <= 2021 coefs = np.load(Path(__file__).parent / "Data" / "HarmonicCoeffsIGRF.npy", allow_pickle=True).item() # Retain the original decimal-year convention for the Earth fit. days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] if new_date.year % 4 == 0: days[1] = 29 year = new_date.year + (new_date.day + sum(days[:new_date.month - 1]) - 0.5) / sum(days) self.B_eq = np.sqrt(sum(np.polyval(coefs[key], year) ** 2 for key in ("g11_fit", "h11_fit", "g10_fit")))
def __str__(self): return ( "Dipole\n" f"\tObject: {self.name}\n" f"\tEquatorial field: {self.B_eq:g} nT\n" f"\tReference radius: {self.to_meters:g} m\n" f"\tMoment direction: {self.direction}\n" f"\tCenter: {self.center} m" )