GeoCotrans.jl

Coordinate systems, transformations, and geomagnetic field models.

Coordinate systems

• GEO: Geocentric Geographic (cartesian) (GEO) coordinate system (x [𝐋], y [𝐋], z [𝐋]).
• GSM: Geocentric Solar Magnetospheric (GSM) coordinate system.
• GSE: Geocentric Solar Ecliptic (GSE) coordinate system.
• GEI: Geocentric Equatorial Inertial (GEI) coordinate system.
• GDZ: Geodetic (GDZ) coordinate system (altitude [km], latitude [deg], longitude [deg]).
• MAG: Geomagnetic (MAG) coordinate system.
• SPH: Geocentric Geographic (spherical) (SPH) coordinate system (r [𝐋], θ [deg], φ [deg]).

Coordinate transformations

• geo2gei, gei2geo: Transform between GEO and GEI coordinate systems.
• geo2gsm, gsm2geo: Transform between GEO and GSM coordinate systems.
• gei2gsm, gsm2gei: Transform between GEI and GSM coordinate systems.
• gse2gsm, gsm2gse: Transform between GSE and GSM coordinate systems.

References

• Coordinate transformations between geocentric systems

International Geomagnetic Reference Field (IGRF)

The International Geomagnetic Reference Field (IGRF) is a standard mathematical description of the Earth's main magnetic field. It is used widely in studies of the Earth's deep interior, crust, ionosphere, and magnetosphere.

Functions

• igrf_B: Compute the geomagnetic field (IGRF-14, dipole model)

Examples

r, θ, φ = 6500., 30., 4.
t = Date(2021, 3, 28)
Br, Bθ, Bφ = igrf_Bd(r, θ, φ, t)

# Input position in geodetic coordinates, output magnetic field in East-North-Up (ENU) coordinates
Be, Bn, Bu = igrf_B(GDZ(0, 60.39299, 5.32415), t)

References

• IAGA - NOAA/NCEI
• IGRF-14 Evaluation

Elsewhere

• SatelliteToolboxGeomagneticField.jl: Models to compute the geomagnetic field (IGRF-13, dipole model)
• ppigrf: Pure Python code to calculate IGRF model predictions.
• geopack: Python code to calculate IGRF model predictions.

Geodetic (GDZ) coordinate system (altitude [km], latitude [deg], longitude [deg]).

Defined using a reference ellipsoid. Both the altitude and latitude depend on the ellipsoid used. GeoCotrans uses the WGS84 reference ellipsoid.

Geocentric Equatorial Inertial (GEI) coordinate system.

Geocentric Geographic (cartesian) (GEO) coordinate system (x [𝐋], y [𝐋], z [𝐋]).

Geocentric Solar Magnetospheric (GSM) coordinate system.

X points sunward from Earth's center. The X-Z plane is defined to contain Earth's dipole axis (positive North).

Geocentric Solar Ecliptic (GSE) coordinate system.

Geomagnetic (MAG) coordinate system.

Solar Magnetic (SM) coordinate system.

Geocentric Geographic (spherical) (SPH) coordinate system (r [𝐋], θ [deg], φ [deg]).

Coordinate systems, transformations, and geomagnetic field models.

Coordinate systems

• GEO: Geocentric Geographic (cartesian) (GEO) coordinate system (x [𝐋], y [𝐋], z [𝐋]).
• GSM: Geocentric Solar Magnetospheric (GSM) coordinate system.
• GSE: Geocentric Solar Ecliptic (GSE) coordinate system.
• GEI: Geocentric Equatorial Inertial (GEI) coordinate system.
• GDZ: Geodetic (GDZ) coordinate system (altitude [km], latitude [deg], longitude [deg]).
• MAG: Geomagnetic (MAG) coordinate system.
• SPH: Geocentric Geographic (spherical) (SPH) coordinate system (r [𝐋], θ [deg], φ [deg]).

Coordinate transformations

• geo2gei, gei2geo: Transform between GEO and GEI coordinate systems.
• geo2gsm, gsm2geo: Transform between GEO and GSM coordinate systems.
• gei2gsm, gsm2gei: Transform between GEI and GSM coordinate systems.
• gse2gsm, gsm2gse: Transform between GSE and GSM coordinate systems.

References

• Coordinate transformations between geocentric systems

International Geomagnetic Reference Field (IGRF)

The International Geomagnetic Reference Field (IGRF) is a standard mathematical description of the Earth's main magnetic field. It is used widely in studies of the Earth's deep interior, crust, ionosphere, and magnetosphere.

Functions

• igrf_B: Compute the geomagnetic field (IGRF-14, dipole model)

Examples

r, θ, φ = 6500., 30., 4.
t = Date(2021, 3, 28)
Br, Bθ, Bφ = igrf_Bd(r, θ, φ, t)

# Input position in geodetic coordinates, output magnetic field in East-North-Up (ENU) coordinates
Be, Bn, Bu = igrf_B(GDZ(0, 60.39299, 5.32415), t)

References

• IAGA - NOAA/NCEI
• IGRF-14 Evaluation

Elsewhere

• SatelliteToolboxGeomagneticField.jl: Models to compute the geomagnetic field (IGRF-13, dipole model)
• ppigrf: Pure Python code to calculate IGRF model predictions.
• geopack: Python code to calculate IGRF model predictions.

CoordinateVector{C, T}

3-element FieldVector in a specific coordinate system C.

Geodetic (GDZ) coordinate system (altitude [km], latitude [deg], longitude [deg]).

Defined using a reference ellipsoid. Both the altitude and latitude depend on the ellipsoid used. GeoCotrans uses the WGS84 reference ellipsoid.

GDZ(x, y, z)

Construct a CoordinateVector in GDZ coordinates.

GDZ(𝐫)

Construct a CoordinateVector in GDZ coordinates.

Geocentric Equatorial Inertial (GEI) coordinate system.

GEI(x, y, z)

Construct a CoordinateVector in GEI coordinates.

GEI(𝐫)

Construct a CoordinateVector in GEI coordinates.

Geocentric Geographic (cartesian) (GEO) coordinate system (x [𝐋], y [𝐋], z [𝐋]).

GEO(x, y, z)

Construct a CoordinateVector in GEO coordinates.

GEO(𝐫)

Construct a CoordinateVector in GEO coordinates.

Geocentric Solar Ecliptic (GSE) coordinate system.

GSE(x, y, z)

Construct a CoordinateVector in GSE coordinates.

GSE(𝐫)

Construct a CoordinateVector in GSE coordinates.

Geocentric Solar Magnetospheric (GSM) coordinate system.

X points sunward from Earth's center. The X-Z plane is defined to contain Earth's dipole axis (positive North).

GSM(x, y, z)

Construct a CoordinateVector in GSM coordinates.

GSM(𝐫)

Construct a CoordinateVector in GSM coordinates.

Geomagnetic (MAG) coordinate system.

MAG(x, y, z)

Construct a CoordinateVector in MAG coordinates.

MAG(𝐫)

Construct a CoordinateVector in MAG coordinates.

Solar Magnetic (SM) coordinate system.

SM(x, y, z)

Construct a CoordinateVector in SM coordinates.

SM(𝐫)

Construct a CoordinateVector in SM coordinates.

Geocentric Geographic (spherical) (SPH) coordinate system (r [𝐋], θ [deg], φ [deg]).

SPH(x, y, z)

Construct a CoordinateVector in SPH coordinates.

SPH(𝐫)

Construct a CoordinateVector in SPH coordinates.

gdz2sph(alt, lat, lon)

Convert (alt [km], lat [deg], lon [deg]) in Geodetic coordinate to Spherical geocentric coordinate.

gei2geo(x, t)

Transforms x vector from Geocentric Equatorial Inertial (GEI) to Geographic (GEO) coordinates at time t.

gei2gsm(x, t)

Transforms x vector from Geocentric Equatorial Inertial (GEI) to Geocentric Solar Magnetic (GSM) coordinates at time t.

geo2gei(x, t)

Transforms x vector from Geographic (GEO) to Geocentric Equatorial Inertial (GEI) coordinates at time t.

geo2gsm(x, t)

Transforms x vector from Geographic (GEO) to Geocentric Solar Magnetic (GSM) coordinates at time t.

get_igrf_coeffs(time)

Get IGRF-14 coefficients for a given time.

Similar to IRBEM implementation, but with higher precision (IRBEM uses year as the time unit).

See also: gse2gsm_mat

gse2gsm(x, t)

Transforms x vector from Geocentric Solar Ecliptic (GSE) to Geocentric Solar Magnetic (GSM) coordinates at time t.

gsm2gei(x, t)

Transforms x vector from Geocentric Solar Magnetic (GSM) to Geocentric Equatorial Inertial (GEI) coordinates at time t.

gsm2geo(x, t)

Transforms x vector from Geocentric Solar Magnetic (GSM) to Geographic (GEO) coordinates at time t.

gsm2gse(x, t)

Transforms x vector from Geocentric Solar Magnetic (GSM) to Geocentric Solar Ecliptic (GSE) coordinates at time t.

igrf_B(r, θ, φ, t; max_degree=IGRF_degree) -> (Br, Bθ, Bφ)

Calculate IGRF model components in geocentric coordinates (r [km], θ [rad], φ [rad]) at time t.

Parameters

• r: radius [km]
• θ: colatitude [rad]
• φ: longitude [rad], positive east
• maxdegree: highest degree of expansion (1 <= maxdegree <= 13)

igrf_B(𝐫::CoordinateVector{GDZ}, t; max_degree=IGRF_degree) -> (Be, Bn, Bu)

Calculate IGRF model components in east, north, up (ENU) coordinates for geodetic coordinates 𝐫 at time t.

igrf_Bd(r, θ, φ, t; max_degree=IGRF_degree) -> (Br, Bθ, Bφ)

Calculate IGRF model components in geocentric coordinates (r [km], θ [deg], φ [deg]) at time t.

Parameters

• r: radius [km]
• θ: colatitude [deg]
• φ: longitude [deg]
• maxdegree: highest degree of expansion (1 <= maxdegree <= 13)

Schmidt_normalization(l, m)

Compute Schmidt normalization factor for degree l and order m.

Reference: Geomagnetism and Schmidt quasi-normalization

calc_dipole_angle(g10, g11, h11)

Calculate dipole angle (θ, φ) and dipole strength (b0) from spherical harmonic coefficients g10, g11, h11.

θ: dipole tilt angle (radians) φ: dipole longitude/phase (radians) b0: dipole strength (nT)

calc_dipole_geo(time)

Compute dipole direction in GEO coordinates. [IRBEM]

calc_sun_gei(ra, dec)

Calculate sun direction vector in GEI given right ascension ra and declination dec.

calculate_gst(time)

Calculate Greenwich sidereal time (GST) in radians from the given time.

Reference: https://aa.usno.navy.mil/faq/GAST, https://github.com/JuliaAstro/AstroLib.jl/blob/main/src/ct2lst.jl

calculate_gst_alt(time)

Alternative implementation of Greenwich sidereal time calculation based on the reference algorithm from pyspedas.cotrans_tools.csundir_vect.

car2sph(x, y, z)

Convert (x, y, z) in Cartesian coordinate to (r, colat [deg], lon [deg]) in spherical coordinate.

cdipdir(time)

Compute dipole direction in GEO coordinates. [PySPEDAS]

References

• https://pyspedas.readthedocs.io/en/latest/coords.html#pyspedas.cotranstools.cotranslib.cdipdir

csundir(time) -> (gst, ra, dec, elong, obliq)

Calculate the direction of the sun, returns a tuple of (gst, ra, dec, elong, obliq) in radians.

• gst: Greenwich mean sidereal time
• ra: Right ascension
• dec: Declination of the sun
• elong: ecliptic longitude
• obliq: Inclination of Earth's axis

See also AstroLib.sunpos.

gei2gsm_mat(time)

Compute the GEI to GSM transformation matrix.

First axis: sun direction (xS, yS, zS) Second axis: y-axis (cross product of dipole and sun, normalized) Third axis: z-axis (cross product of sun and y-axis, normalized)

get_dipole_terms(g, h)

Compute dipole parameters (θ, φ, x0, y0, z0, b0) from IGRF coefficients.

Returns a named tuple: (θ, φ, x0, y0, z0, b0)

gse2gsm_mat(time)

Compute the GSE to GSM transformation matrix T3 = <- psi,X>, where the rotation angle psi is the GSE-GSM angle.

This transformation is a rotation in the GSE YZ plane from the GSE Z axis to the GSM Z axis.

Format into matrix form (l, m)