geopack-ts

A pure TypeScript port of N.A. Tsyganenko's GEOPACK-2008 Fortran library for coordinate transformations, IGRF geomagnetic field calculations, empirical magnetospheric field models, and field line tracing. The port adds a modern TypeScript API with tree-shakeable entry points and updated IGRF-14 coefficients (valid until 2030).

What This Package Provides

The original Fortran GEOPACK-2008 code by N.A. Tsyganenko provides coordinate transformations between geophysical reference frames, IGRF internal field calculations, empirical magnetospheric field models (T89, T96, T01, TS04), and field line tracing. The Python tsyganenko wrapper by John Coxon and Sebastien de Larquier served as inspiration for the high-level API design.

This TypeScript port contributes:

• Line-by-line port of all Fortran subroutines to idiomatic TypeScript
• Updated IGRF-14 coefficients (the original Fortran uses IGRF-12; this port includes IGRF-14, valid until 2030)
• High-level TypeScript API with typed state objects, plain-object transforms, and a Python-like convert module
• Tree-shakeable entry points for core, basic (IGRF-free), and THREE.js wrappers
• Optional THREE.js integration with frame orientation quaternions and position transforms for 3D rendering

Features

• Pure TypeScript -- no WebAssembly, no native dependencies
• Coordinate transforms: GEI, GEO, GSE, GSM/GSW, SM, MAG
• IGRF-14: full spherical harmonic internal field model (updated from IGRF-12 in the original Fortran)
• Tsyganenko external field models: T89, T96, T01, TS04
• Field line tracing: Runge-Kutta integration with magnetopause detection
• Dipole tilt & sun position: subsolar point, GMST, geodetic/geocentric conversion
• Tree-shakeable: separate entry points for core, basic (IGRF-free), and THREE.js wrappers
• Optional THREE.js integration: frame orientation quaternions and position transforms for 3D rendering

Installation

npm install geopack-ts

Entry Points

| Import path | Description | Includes IGRF | |-------------|-------------|:-------------:| | geopack-ts | High-level transforms using plain objects | Yes | | geopack-ts/core | Full low-level GEOPACK API | Yes | | geopack-ts/core/basic | Sun, GMST, GEI/GEO/GSE only | No | | geopack-ts/three | THREE.js Vector3/Quaternion wrappers | Yes | | geopack-ts/models/t89 | T89 model only | No | | geopack-ts/models/t96 | T96 model only | No | | geopack-ts/models/t01 | T01 model only | No | | geopack-ts/models/ts04 | TS04 model only | No |

Usage

High-Level API (plain objects)

import { transformPositionPlain, getGeopackStateForGSM } from 'geopack-ts';

// Initialize state for a given date/time and solar wind
const state = getGeopackStateForGSM(new Date('2024-06-21T12:00:00Z'));

// Transform a position from GEO to GSM
const gsmPos = transformPositionPlain(
  { x: 6.6, y: 0, z: 0 },
  'GEO', 'GSM',
  state
);

Core API

import { Geopack, recalc, geoGsw, igrfGsw, trace } from 'geopack-ts/core';

// Class-based interface
const gp = new Geopack();
gp.recalc(2024, 180, 12, 0, 0, -400, 0, 0);
const gsw = gp.geoToGsw(1, 0, 0);
const field = gp.igrfGsw(6, 0, 0);

// Or use standalone functions
const state = recalc(2024, 180, 12, 0, 0, -400, 0, 0);
const [xGsw, yGsw, zGsw] = geoGsw([6.6, 0, 0], 1, state);
const [bx, by, bz] = igrfGsw(xGsw, yGsw, zGsw, state);

Convert Module (Python-like API)

import { convert } from 'geopack-ts/core';

const gp = convert.recalc(new Date('2024-06-21T12:00:00Z'), -400, 0, 0);
const [xGsw, yGsw, zGsw] = convert.coordinates(gp, 1, 0, 0, 'geo', 'gsw');

Field Line Tracing

import { recalc, trace, t89c } from 'geopack-ts/core';

const state = recalc(2024, 180, 12, 0, 0, -400, 0, 0);

const result = trace(
  -6.6, 0, 0,         // start position in GSW (Re)
  -1,                   // direction: -1 = toward Earth
  0.05,                 // step size (Re)
  25,                   // max distance (Re)
  2.0,                  // stop at r = 2 Re
  state,
  t89c,                 // external field model
  { iopt: 3 }           // Kp level (1-7)
);

console.log(`Footpoint: ${result.xf}, ${result.yf}, ${result.zf}`);
console.log(`Arc length: ${result.length} Re`);

External Field Models

import { t89c, t96, t01, ts04 } from 'geopack-ts/core';

// T89: parameterized by Kp index (iopt 1-7)
const [bx, by, bz] = t89c(3, [0,0,0,0,0,0,0,0,0,0], ps, x, y, z);

// T96: parameterized by Pdyn, Dst, By, Bz
const b96 = t96(0, [2.0, -30, 1, -5, 0,0,0,0,0,0], ps, x, y, z);

// TS04: parameterized by Pdyn, Dst, By, Bz, W1-W6
const bts04 = ts04(0, [2.0, -30, 1, -5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5], ps, x, y, z);

Basic Transforms (no IGRF)

import { recalcBasic, geiGeo, sun } from 'geopack-ts/core/basic';

// Only GEI, GEO, GSE transforms -- no IGRF coefficient loading
const state = recalcBasic(2024, 180, 12, 0, 0);
const [xGeo, yGeo, zGeo] = geiGeo([1, 0, 0], 1, state);

THREE.js Integration

import { transformPosition, getFrameOrientationToGEI } from 'geopack-ts/three';
import { Vector3 } from 'three';

const pos = transformPosition(new Vector3(6.6, 0, 0), 'GEO', 'GSM', state);
const orientation = getFrameOrientationToGEI('GSM', state);
// orientation.quaternion can be applied to a THREE.js Object3D

Coordinate Systems

| System | Full Name | Description | |--------|-----------|-------------| | GEI | Geocentric Equatorial Inertial | Earth-centered, equatorial plane, X toward vernal equinox | | GEO | Geographic | Earth-centered, co-rotating with Earth | | GSE | Geocentric Solar Ecliptic | X toward Sun, Z toward ecliptic north pole | | GSM/GSW | Geocentric Solar Magnetospheric/Wind | X toward Sun (GSM) or anti-solar-wind (GSW), Z in plane containing dipole | | SM | Solar Magnetic | Z along dipole axis, Y perpendicular to Sun-Earth line | | MAG | Geomagnetic | Z along dipole axis, co-rotating with Earth |

References

GEOPACK and Coordinate Systems

1. Russell, C. T. (1971), Geophysical Coordinate Transformations, Cosmic Electrodynamics, 2, 184-196.

IGRF

2. Alken, P., Thebault, E., Beggan, C. D., et al. (2021), International Geomagnetic Reference Field: the thirteenth generation, Earth Planets Space, 73, 49, doi:10.1186/s40623-020-01288-x.

Tsyganenko Magnetospheric Field Models

3. Tsyganenko, N. A. (1989), A Magnetospheric Magnetic Field Model with a Warped Tail Current Sheet, Planet. Space Sci., 37, 5-20, doi:10.1016/0032-0633(89)90066-4.

4. Tsyganenko, N. A. (1995), Modeling the Earth's Magnetospheric Magnetic Field Confined within a Realistic Magnetopause, J. Geophys. Res., 100, 5599-5612, doi:10.1029/94JA03193.

5. Tsyganenko, N. A. and Stern, D. P. (1996), Modeling the Global Magnetic Field of the Large-Scale Birkeland Current Systems, J. Geophys. Res., 101, 27187-27198, doi:10.1029/96JA02735.

6. Tsyganenko, N. A. (2002a), A model of the near magnetosphere with a dawn-dusk asymmetry -- 1. Mathematical Structure, J. Geophys. Res., 107, A8, doi:10.1029/2001JA000219.

7. Tsyganenko, N. A. (2002b), A model of the near magnetosphere with a dawn-dusk asymmetry -- 2. Parameterization and fitting to observations, J. Geophys. Res., 107, A7, doi:10.1029/2001JA000220.

8. Tsyganenko, N. A., Singer, H. J. and Kasper, J. C. (2003), Storm-time distortion of the inner magnetosphere: How severe can it get?, J. Geophys. Res., 108, A5, doi:10.1029/2002JA009808.

9. Tsyganenko, N. A. and Sitnov, M. I. (2005), Modeling the dynamics of the inner magnetosphere during strong geomagnetic storms, J. Geophys. Res., 110, A3, doi:10.1029/2004JA010798.

Magnetopause Models

10. Shue, J.-H., et al. (1998), Magnetopause location under extreme solar wind conditions, J. Geophys. Res., 103, 17691-17700, doi:10.1029/98JA01103.

License

MIT License -- see LICENSE for details.

Acknowledgments

• Nikolai A. Tsyganenko (and co-authors) -- Original Fortran GEOPACK-2008 code and all empirical magnetospheric field models
• John C. Coxon, Sebastien de Larquier -- Python tsyganenko wrapper, which served as inspiration for the API design
• IAGA Division V-MOD -- IGRF model and coefficients