TsyganenkoModels
Modeling of Earth's Magnetosphere Using Spacecraft Magnetometer Data.
Features
- Magnetic field model (native Julia implementations)
- [x] T89: A magnetospheric magnetic field model with a warped tail current sheet
- [x] T96: Effects of the solar wind conditions on the global magnetospheric configuration
- [x] T01/T02: A model of the near magnetosphere with a dawn-dusk asymmetry
- [x] TS05/TS04: a dynamical empirical model of the inner storm-time magnetosphere
- [x] TA16: An empirical RBF model of the magnetosphere parameterized by interplanetary and ground-based drivers
IRBEM.jl is a Julia wrapper for the IRBEM Fortran library that exposes magnetic field computation via GET_FIELD_MULTI and supports more Tsyganenko models, but may be outdated and slower than the native Julia implementations.
Quickstart
The model interface allows you to configure a model once and use it for multiple field calculations:
using Pkg; Pkg.add("TsyganenkoModels")
using TsyganenkoModels
using Dates
# Create model configurations
model_t89 = T89(2) # Kp level 2
param = (; pdyn=2.0, dst=-87.0, byimf=2.0, bzimf=-5.0)
# pdyn: Solar wind dynamic pressure [nPa]
# dst: Dst index [nT]
# byimf: IMF By [nT]
# bzimf: IMF Bz [nT]
# Calculate fields at position
t = DateTime("1970-01-01T00:01:40")
𝐫 = [1, 2, 3]
ps = -0.533585131 # dipole tilt angle [radians]
# Using dipole tilt angle
B_t89 = model_t89(𝐫, ps)3-element GeoCotrans.CoordinateVector{GSM, GeoCotrans.Cartesian3, Float64} with indices SOneTo(3):
5.367416991592773
-3.448905444772822
-17.29126736398316julia> # Compare with other models B_t96 = T96(param)(𝐫, ps)3-element GeoCotrans.CoordinateVector{GSM, GeoCotrans.Cartesian3, Float64} with indices SOneTo(3): 39.34888430483173 -9.327382852681387 -90.39880058124456julia> B_t01 = T01(param)(𝐫, ps)3-element GeoCotrans.CoordinateVector{GSM, GeoCotrans.Cartesian3, Float64} with indices SOneTo(3): 25.017949640018685 -4.606333569227005 -66.8231718353742julia> B_ts04 = TS04(param)(𝐫, ps)3-element GeoCotrans.CoordinateVector{GSM, GeoCotrans.Cartesian3, Float64} with indices SOneTo(3): 13.497153297097455 -0.139162093284399 -24.92850356717416julia> # Using time (auto-calculates dipole tilt) T89(3)(𝐫, t)3-element GeoCotrans.CoordinateVector{GSM, GeoCotrans.Cartesian3, Float64} with indices SOneTo(3): 7.173912838762307 -3.7801244076567895 -19.92771236869731julia> # Using `TsyIGRF` to combine IGRF14 model and one Tsyganenko model (default T89) TsyIGRF()(𝐫, t)3-element StaticArraysCore.SVector{3, Float64} with indices SOneTo(3): -541.7175541219175 -576.5916824426614 -339.77872971789793julia> # This is equivalent to IGRF()(GSM(𝐫), t) .+ T89(3)(𝐫, t)3-element StaticArraysCore.SVector{3, Float64} with indices SOneTo(3): -541.7175541219175 -576.5916824426614 -339.7787297178979
Comparison with geopack
using TsyganenkoModels
using GeoCotrans
using Test
using Geopack
using Dates
t = DateTime("1970-01-01T00:01:40")
𝐫 = [1, 2, 3]
# using geopack
xgsm, ygsm, zgsm = 𝐫
opt = 2
ut = datetime2unix(t)
ps = Geopack.recalc(ut)
db_py = Geopack.t89(opt, ps, xgsm, ygsm, zgsm)
# using TsyganenkoModels
db_jl = T89(opt)(𝐫, ps)
@test db_py ≈ db_jlTest PassedModel Result Comparison
# T01 model comparison
pdyn = 2.0 # Solar wind dynamic pressure [nPa]
dst = -87.0 # Dst index [nT]
byimf = 2.0 # IMF By [nT]
bzimf = -5.0 # IMF Bz [nT]
g1 = 0.0
g2 = 0.0
parmod = [pdyn, dst, byimf, bzimf, g1, g2]
db_t96_py = Geopack.t96(parmod, ps, xgsm, ygsm, zgsm)
db_t96_jl = T96(; pdyn, dst, byimf, bzimf)(𝐫, ps)
@test db_t96_jl ≈ db_t96_py rtol = 1e-6
db_t01_py = Geopack.t01(parmod, ps, xgsm, ygsm, zgsm)
db_t01_jl = T01(; pdyn, dst, byimf, bzimf)(𝐫, ps)
@test db_t01_jl ≈ db_t01_py rtol = 1e-6Test PassedThe internal magnetic field could be computed using igrf from GeoCotrans.
Here we verify the result with igrf_gsm from Geopack.
julia> using GeoCotransjulia> b0_py = Geopack.igrf_gsm(xgsm, ygsm, zgsm)3-element StaticArraysCore.SVector{3, Float64} with indices SOneTo(3): -548.892407931754 -572.8105422196072 -319.8493868519125julia> b0_jl = GeoCotrans.igrf(GSM(𝐫), t)3-element StaticArraysCore.SVector{3, Float64} with indices SOneTo(3): -548.8914669606798 -572.8115580350046 -319.85101734920056julia> @test b0_jl ≈ b0_py rtol = 1e-5Test Passedjulia> @test GeoCotrans.get_igrf_coeffs(t)[1] ≈ Geopack.load_igrf(ut)[1]Test Passed
Performance Benchmarks
julia> using Chairmarksjulia> @b TsyganenkoModels.T89(2)($𝐫, $ps), Geopack.t89(2, $ps, $𝐫...)(140.000 ns, 34.292 μs (26 allocs: 640 bytes))julia> @b TsyganenkoModels.T96($pdyn, $dst, $byimf, $bzimf)($𝐫, $ps), Geopack.t96([$pdyn, $dst, $byimf, $bzimf, 0, 0], $ps, $𝐫...)(3.155 μs, 834.476 μs (99 allocs: 2.656 KiB))julia> @b TsyganenkoModels.T01(; pdyn, dst, byimf, bzimf)($𝐫, $ps), Geopack.t01([pdyn, dst, byimf, bzimf, 0, 0], $ps, $𝐫...)(7.552 μs (5 allocs: 208 bytes), 1.754 ms (157 allocs: 4.219 KiB))julia> @b GeoCotrans.igrf(GSM($𝐫), t), Geopack.igrf_gsm($𝐫...)(661.000 ns (2 allocs: 64 bytes), 90.656 μs (13 allocs: 240 bytes))
API
TsyganenkoModels.DrivenTsyganenkoModels.OMNITsyganenkoModels.T01TsyganenkoModels.T89TsyganenkoModels.T96TsyganenkoModels.TA16TsyganenkoModels.TS04TsyganenkoModels.TsyIGRFTsyganenkoModels.TsyganenkoModelTsyganenkoModels.cartharmTsyganenkoModels.t01TsyganenkoModels.t89TsyganenkoModels.t96
TsyganenkoModels.Driven — Type
Driven(M, source = OMNI())Model M evaluated at time t as M(inputs(m, t)).
TsyganenkoModels.OMNI — Type
OMNI()Parameters from 5-min (and, for Kp and Dst, hourly) OMNI data:
pdyn = ρV²withρ = 1.16 mₚN(He/H = 0.04); gaps of at most 3 hours linearly interpolated, as Tsyganenko prepares TS05 inputs.T89:ioptfrom Kp.T01,TS04: SYM-H asdst, the index their fits used.T96: Dst and the means of the validpdyn,byimf,bzimfsamples over the UT hour containingt, as its fit tagged each field average with the concurrent hourly OMNI values (Tsyganenko, 1996; Tsyganenko, 2002b, ¶6).T01: other inputs at the 5-min sample containingt, the resolution of its fit, andg1,g2averaged over the valid samples in the hour ending there.TS04:w1–w6accumulated from 13 days beforet, when the slowest memory (W3) has decayed belowe⁻¹⁰; samples in unfilled gaps contribute nothing. Tsyganenko's yearly files instead restart the sums after each gap at the first 2-hour quiet period, and on January 1, discarding the decayed memory of earlier driving that the exponential kernel models.TA16:pdynat the 5-min sample containingt;symhc, the mean of the valid0.8 SYM-H - 13√pdynsamples within ±15 min;xindandbyimf, the means of the valid Newell N-index and By samples in the 30 min ending there (Tsyganenko & Andreeva, 2016, eq. 9 and §4);vgse, the velocity at that sample with Earth's orbital 29.78 km/s added back to OMNI's Vy, defining the model's GSW frame, in which the IMF is taken. Tsyganenko's driver files use OMNI's Vy as is, which fits later THEMIS and Van Allen Probes magnetometer data worse.
TsyganenkoModels.T01 — Type
T01(; pdyn, dst, byimf, bzimf, g1=0.0, g2=0.0)Tsyganenko 01 model with solar wind parameters.
Parameters
pdyn: Solar wind dynamic pressure [nPa]dst: Dst index [nT]byimf: IMF By component [nT]bzimf: IMF Bz component [nT]g1: G1 index (default: 0.0)g2: G2 index (default: 0.0)
Usage
model = T01(pdyn=2.0, dst=-87.0, byimf=2.0, bzimf=-5.0)
B = model([1, 2, 3], ps) # Compute field at positionModel Description
Data-based model of the external magnetospheric magnetic field, calibrated by:
- Solar wind pressure PDYN (nanopascals)
- Dst (nanotesla)
- IMF By and Bz (nanotesla)
- G1 and G2 indices
ATTENTION: The model is based on data taken sunward from X=-15 Re, and hence becomes invalid at larger tailward distances.
References
- Tsyganenko, N.A., JGR, 2002
TsyganenkoModels.T89 — Type
T89(iopt::Integer)Tsyganenko 89 model with Kp-dependent parameters.
Parameters
iopt: Ground disturbance level index (1-7)- 1: Kp = 0, 0+
- 2: Kp = 1-, 1, 1+
- 3: Kp = 2-, 2, 2+
- 4: Kp = 3-, 3, 3+
- 5: Kp = 4-, 4, 4+
- 6: Kp = 5-, 5, 5+
- 7: Kp ≥ 6-
Model Description
Valid up to geocentric distances of 70 RE. Based on merged IMP-A through J (1966-1974), HEOS-1 and -2 (1969-1974), and ISEE-1 and -2 spacecraft data.
Usage
model = T89(2) # Kp level 2
B = model([1, 2, 3], ps) # Compute field at positionReferences
- Tsyganenko, N.A., "A magnetospheric magnetic field model with a warped tail current sheet", Planet. Space Sci., 37, 5-20, 1989.
- Fortran implementation
TsyganenkoModels.T96 — Type
T96(; pdyn, dst, byimf, bzimf)Tsyganenko 96 model with solar wind parameters.
Parameters
pdyn: Solar wind dynamic pressure [nPa]dst: Dst index [nT]byimf: IMF By component [nT]bzimf: IMF Bz component [nT]
Usage
model = T96(pdyn=2.0, dst=-87.0, byimf=2.0, bzimf=-5.0)
B = model([1, 2, 3], ps) # Compute field at positionModel Description
Data-based model calibrated by solar wind pressure, Dst index, and IMF By/Bz components. Includes realistic magnetopause, Region 1 and 2 Birkeland current systems, and IMF penetration.
Valid parameter ranges (caution needed outside these ranges):
- Pdyn: 0.5 to 10 nPa
- Dst: -100 to +20 nT
- ByIMF and BzIMF: -10 to +10 nT
References
- Tsyganenko & Stern, JGR, v.101, p.27187-27198, 1996
- Tsyganenko, JGR, v.100, p.5599-5612, 1995
TsyganenkoModels.TA16 — Type
TA16(; pdyn, symhc, xind, byimf, vgse = nothing)Tsyganenko-Andreeva 2016 RBF model: the field of 1296 radial basis functions and their mirror images in the SM equatorial plane, warped with dipole tilt.
The model is fitted in the aberrated GSW frame, GSW(vgse); vgse = nothing takes GSM.
Parameters
pdyn: Solar wind dynamic pressure [nPa]symhc: Corrected SYM-H [nT], the 30-min centered sliding average of0.8 SYM-H - 13 √pdynxind: Newell et al. (2007) coupling index as normalized by Tsyganenko & Andreeva (2015), averaged over the preceding 30 min; typically 0 (quiet) to 2 (strongly disturbed)byimf: IMF By [nT] in the model frame, averaged over the preceding 30 minvgse: solar wind velocity relative to Earth (GSE) [km/s], seeGSW
Valid only sunward of X = -15 Re.
References
- Tsyganenko, N. A., and Andreeva, V. A. (2016), An empirical RBF model of the magnetosphere parameterized by interplanetary and ground-based drivers, J. Geophys. Res. Space Physics, https://doi.org/10.1002/2016JA023217.
- Andreeva, V. A., and Tsyganenko, N. A. (2016), Reconstructing the magnetosphere from data using radial basis functions, J. Geophys. Res. Space Physics, https://doi.org/10.1002/2015JA022242.
TsyganenkoModels.TS04 — Type
TS04(; pdyn, dst, byimf, bzimf, w1=0.0, w2=0.0, w3=0.0, w4=0.0, w5=0.0, w6=0.0)Tsyganenko-Sitnov 04 model with solar wind parameters and W indices.
Parameters
pdyn: Solar wind dynamic pressure [nPa]dst: Dst index [nT]byimf: IMF By component [nT]bzimf: IMF Bz component [nT]w1-w6: Time integrals of the driving variables (time integrals from the beginning of a storm, see reference for definitions)
Usage
model = TS04(pdyn=2.0, dst=-87.0, byimf=2.0, bzimf=-5.0, w1=0.5)
B = model([1, 2, 3], ps) # Compute field at positionReferences
- Tsyganenko, N. A., and Sitnov, M. I. (2005), Modeling the dynamics of the inner magnetosphere during strong geomagnetic storms, J. Geophys. Res., 110, A03208, https://doi.org/10.1029/2004JA010798.
- TS05 magnetic field model
- Fortran implementation (TS04c.for)
TsyganenkoModels.TsyIGRF — Type
TsyIGRF(model = T89(iopt=3); name=nothing)Create a composite Earth magnetic field model combining internal IGRF and external Tsyganenko field model.
Example
model = TsyIGRF(T89(iopt=3))
t = Date(2020, 6, 21) # Summer solstice 2020
B = model(6.6, 0.0, 0.0, t) # GSM (x, y, z) [Re] -> (Bx, By, Bz) [nT]TsyganenkoModels.TsyganenkoModel — Type
(m::TsyganenkoModel)(x, y, z, ps, args...; kw...) -> (Bx, By, Bz)Compute GSM components of the external magnetic field [nT] using Tsyganenko model m, given position in GSM coordinates (x, y, z) [Earth radii] and geodipole tilt angle [radians] ps.
TsyganenkoModels.cartharm — Method
cartharm(c, p, r, x, y, z, parallel) -> (Bx, By, Bz)Evaluate the Cartesian-harmonic field B = Σ c(i,k) ∇Uᵢₖ, where Uᵢₖ = -exp(x√(1/pᵢ² + 1/rₖ²)) cos(y/pᵢ) f(z/rₖ). p and r are spatial scales along y and z; parallel selects f = cos (Bx even, Bz odd in z), otherwise f = sin (Bx odd, Bz even). Each potential satisfies Laplace's equation. Fitted coefficients provide magnetopause shielding or IMF penetration (Tsyganenko 1995, JGR 100, 5599).
TsyganenkoModels.t01 — Function
t01(x, y, z, ps, pdyn, dst, byimf, bzimf, g1 = 0.0, g2 = 0.0) -> (Bx, By, Bz)Compute GSM components of the external magnetic field using the Tsyganenko 01 model.
TsyganenkoModels.t89 — Method
t89(𝐫, ps, iopt; cache=nothing) -> GSM(Bx, By, Bz)
t89(x, y, z, ps, iopt)
t89(x, y, z, t::AbstractTime, iopt)Compute GSM components of the magnetic field [nT] produced by extraterrestrial current systems in the geomagnetosphere using the Tsyganenko 89 model, given the position 𝐫 or x, y, z in GSM coordinates [Earth radii], the geodipole tilt angle ps [radians] / time t.
TsyganenkoModels.t96 — Method
t96(x, y, z, ps, pdyn, dst, byimf, bzimf) -> (Bx, By, Bz)Compute GSM components of the external magnetic field using the Tsyganenko 96 model.