Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PRBEM/IRBEM/llms.txt

Use this file to discover all available pages before exploring further.

IRBEM provides routines to transform positions between 15 geophysical and heliospheric coordinate systems, covering everything from Earth-centered frames (GEO, GSM, GSE, SM) to deep-space heliospheric frames (HEE, HAE, HEEQ). Because the orientations of most frames depend on the Sun–Earth geometry and Earth’s rotation, all transforms are time-dependent — every routine requires the year, day of year, and universal time in seconds.

​
COORD_TRANS_VEC — Generic Vectorized Transform

COORD_TRANS_VEC is the recommended entry point for batch transforms. It converts an array of ntime positions from any input coordinate system to any output coordinate system in a single call.

​
Parameters

​
ntime
integer
required
Number of time points to transform.
​
sysaxesIN
integer
required
Key identifying the input coordinate system. See the coordinate systems reference for allowed values and string aliases.
​
sysaxesOUT
integer
required
Key identifying the output coordinate system.
​
iyear
integer[ntime]
required
Year for each time point.
​
idoy
integer[ntime]
required
Day of year for each time point. January 1st is idoy = 1.
​
UT
double[ntime]
required
Universal time in seconds of day for each time point.
​
xIN
double[3, ntime]
required
Position array in the input coordinate system.

​
Output

​
xOUT
double[3, ntime]
Position array in the output coordinate system, with the same units as xIN (Re for geocentric systems, AU for heliospheric systems).

​
Call Sequences

call coord_trans_vec1(ntime, sysaxesIN, sysaxesOUT, iyr, idoy, secs, xIN, xOUT)

​
Python — Coords.transform

The Python Coords class wraps coord_trans_vec1 with an idiomatic interface that accepts datetime objects and coordinate system name strings directly. 
from IRBEM import Coords
c = Coords()
pos_out = c.transform(time, pos_in, sysaxesIn, sysaxesOut)
​
time
datetime | list[datetime]
required
A single datetime.datetime object or a list/array of them, one per position point.
​
pos
array-like
required
Position(s) in the input coordinate system. For a single point, a length-3 list or array. For multiple points, shape (nT, 3).
​
sysaxesIn
str | int
required
Input coordinate system name string (e.g. 'GEO', 'GSM', 'GDZ') or integer key.
​
sysaxesOut
str | int
required
Output coordinate system name string or integer key.

​
Available coordinate system identifiers

KeyNameDescription
0GDZGeodetic — altitude (km), latitude (deg), East longitude (deg)
1GEOGeographic cartesian (Re)
2GSMGeocentric Solar Magnetospheric cartesian (Re)
3GSEGeocentric Solar Ecliptic cartesian (Re)
4SMSolar Magnetic cartesian (Re)
5GEIGeocentric Equatorial Inertial cartesian (Re)
6MAGGeomagnetic cartesian (Re)
7SPHGeographic spherical — radial distance (Re), latitude (deg), East longitude (deg)
8RLLRadial–latitude–longitude (Re, deg, deg) — preferred over SPH

​
Example

from IRBEM import Coords
import datetime

c = Coords()

# Single-point transform: GEO → GSM
t = datetime.datetime(2015, 2, 2, 6, 12, 43)
pos_geo = [3.0, 0.0, 0.0]          # [x, y, z] in GEO (Re)
pos_gsm = c.transform(t, pos_geo, 'GEO', 'GSM')
print(pos_gsm)                      # array of shape (1, 3)

# Multi-point transform: GEO → GDZ
times = [datetime.datetime(2015, 2, 2, i, 0, 0) for i in range(6)]
positions = [[3.0 + i*0.1, 0.0, 0.0] for i in range(6)]
pos_gdz = c.transform(times, positions, 'GEO', 'GDZ')
Coords.coords_transform() is deprecated. Use Coords.transform() instead.

​
Geographic Pair Transforms

The following single-point routines convert between specific pairs of coordinate systems. They are lower-level primitives; for multi-point batch work prefer COORD_TRANS_VEC.
All single-point routines accept scalar iyr, idoy, and UT inputs and return a single transformed position. For time-series inputs use COORD_TRANS_VEC (Fortran/IDL) or Coords.transform (Python).

​
GEO ↔ GSM

GEO2GSM — transforms Geographic (GEO) to Geocentric Solar Magnetospheric (GSM) coordinates. Returns the position and the dipole tilt angle psi.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year (January 1st = 1).
​
UT
double
required
Time in seconds of day.
​
xGEO
double[3]
required
Cartesian position in GEO (Re).
​
psi
double
Dipole tilt angle for the GSM system (rad).
​
xGSM
double[3]
Cartesian position in GSM (Re).
call geo2gsm1(iyr, idoy, secs, psi, xGEO, xGSM)
GSM2GEO — transforms GSM to GEO coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year (January 1st = 1).
​
UT
double
required
Time in seconds of day.
​
xGSM
double[3]
required
Cartesian position in GSM (Re).
​
psi
double
Dipole tilt angle (rad).
​
xGEO
double[3]
Cartesian position in GEO (Re).
call gsm2geo1(iyr, idoy, secs, psi, xGSM, xGEO)

​
GEO ↔ GSE

GEO2GSE — transforms GEO to Geocentric Solar Ecliptic (GSE) coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGEO
double[3]
required
Cartesian position in GEO (Re).
​
xGSE
double[3]
Cartesian position in GSE (Re).
call geo2gse1(iyr, idoy, secs, xGEO, xGSE)
GSE2GEO — transforms GSE to GEO coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGSE
double[3]
required
Cartesian position in GSE (Re).
​
xGEO
double[3]
Cartesian position in GEO (Re).
call gse2geo1(iyr, idoy, secs, xGSE, xGEO)

​
GEO ↔ GDZ

GEO2GDZ — converts GEO Cartesian to Geodetic (GDZ: altitude, latitude, longitude). Note: this routine takes individual scalar coordinates rather than a 3-vector.
​
xx
double
required
x component of GEO position (Re).
​
yy
double
required
y component of GEO position (Re).
​
zz
double
required
z component of GEO position (Re).
​
lati
double
Geodetic latitude (deg).
​
longi
double
East longitude (deg).
​
alti
double
Altitude above the WGS84 ellipsoid (km).
call geo_gdz(xx, yy, zz, lati, longi, alti)
GDZ2GEO — converts Geodetic to GEO Cartesian.
​
lati
double
required
Geodetic latitude (deg).
​
longi
double
required
East longitude (deg).
​
alti
double
required
Altitude (km).
​
xx
double
x in GEO (Re).
​
yy
double
y in GEO (Re).
​
zz
double
z in GEO (Re).
call gdz_geo(lati, longi, alti, xx, yy, zz)

​
GEO ↔ SM

GEO2SM — transforms GEO to Solar Magnetic (SM) coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGEO
double[3]
required
Cartesian position in GEO (Re).
​
xSM
double[3]
Cartesian position in SM (Re).
call geo2sm1(iyr, idoy, secs, xGEO, xSM)
SM2GEO — transforms SM to GEO coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xSM
double[3]
required
Cartesian position in SM (Re).
​
xGEO
double[3]
Cartesian position in GEO (Re).
call sm2geo1(iyr, idoy, secs, xSM, xGEO)

​
GEO ↔ GEI

GEO2GEI — transforms GEO to Geocentric Equatorial Inertial (GEI) coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGEO
double[3]
required
Cartesian position in GEO (Re).
​
xGEI
double[3]
Cartesian position in GEI (Re).
call geo2gei1(iyr, idoy, secs, xGEO, xGEI)
GEI2GEO — transforms GEI to GEO coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGEI
double[3]
required
Cartesian position in GEI (Re).
​
xGEO
double[3]
Cartesian position in GEO (Re).
call gei2geo1(iyr, idoy, secs, xGEI, xGEO)

​
GEO ↔ MAG

GEO2MAG — transforms GEO to Geomagnetic (MAG) coordinates. This transform depends only on the year (epoch of the dipole model), not on UT.
​
iyr
integer
required
Year (used to define the geomagnetic pole position).
​
xGEO
double[3]
required
Cartesian position in GEO (Re).
​
xMAG
double[3]
Cartesian position in MAG (Re).
call geo2mag1(iyr, xGEO, xMAG)
MAG2GEO — transforms MAG to GEO coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xMAG
double[3]
required
Cartesian position in MAG (Re).
​
xGEO
double[3]
Cartesian position in GEO (Re).
call mag2geo1(iyr, xMAG, xGEO)

​
GSM ↔ SM

GSM2SM — transforms GSM to SM coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGSM
double[3]
required
Cartesian position in GSM (Re).
​
xSM
double[3]
Cartesian position in SM (Re).
call gsm2sm1(iyr, idoy, secs, xGSM, xSM)
SM2GSM — transforms SM to GSM coordinates.
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xSM
double[3]
required
Cartesian position in SM (Re).
​
xGSM
double[3]
Cartesian position in GSM (Re).
call sm2gsm1(iyr, idoy, secs, xSM, xGSM)

​
Spherical / RLL Utilities

SPH2CAR — converts spherical coordinates (r, latitude, East longitude) to Cartesian.
​
r
double
required
Radial distance in arbitrary units.
​
lati
double
required
Latitude (deg).
​
longi
double
required
East longitude (deg).
​
x
double[3]
Cartesian coordinates in the same units as r.
call SPH_CAR(r, lati, longi, x)
CAR2SPH — converts Cartesian to spherical coordinates.
​
x
double[3]
required
Cartesian coordinates.
​
r
double
Radial distance.
​
lati
double
Latitude (deg).
​
longi
double
East longitude (deg).
call CAR_SPH(x, r, lati, longi)
RLL2GDZ — converts Radial–latitude–longitude (RLL, Re) to Geodetic altitude (km), keeping latitude and longitude unchanged.
​
r
double
required
Geocentric radial distance (Re).
​
lati
double
required
Latitude (deg).
​
longi
double
required
East longitude (deg).
​
alti
double
Geodetic altitude (km).
call RLL_GDZ(r, lati, longi, alti)

​
Heliospheric Transforms

The routines below convert between geocentric and heliospheric frames, and between heliospheric frames. Positions in heliospheric frames are in AU; geocentric positions remain in Re.

​
GSE ↔ HEE

GSE2HEE — transforms Geocentric Solar Ecliptic (GSE) to Heliocentric Earth Ecliptic (HEE, also known as Heliospheric Solar Ecliptic, HSE).
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xGSE
double[3]
required
Cartesian position in GSE (Re).
​
xHEE
double[3]
Cartesian position in HEE (AU).
call gse2hee1(iyr, idoy, UT, xGSE, xHEE)
HEE2GSE — transforms HEE back to GSE.
​
xHEE
double[3]
required
Cartesian position in HEE (AU).
​
xGSE
double[3]
Cartesian position in GSE (Re).
call hee2gse1(iyr, idoy, UT, xHEE, xGSE)

​
HEE ↔ HAE

HEE2HAE — transforms Heliocentric Earth Ecliptic (HEE) to Heliocentric Aries Ecliptic (HAE, also known as Heliospheric Solar Ecliptic, HSE).
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xHEE
double[3]
required
Cartesian position in HEE (AU).
​
xHAE
double[3]
Cartesian position in HAE (AU).
call hee2hae1(iyr, idoy, UT, xHEE, xHAE)
HAE2HEE — transforms HAE to HEE.
​
xHAE
double[3]
required
Cartesian position in HAE (AU).
​
xHEE
double[3]
Cartesian position in HEE (AU).
call hae2hee1(iyr, idoy, UT, xHAE, xHEE)

​
HAE ↔ HEEQ

HAE2HEEQ — transforms HAE to Heliocentric Earth Equatorial (HEEQ, also known as Heliospheric Solar, HS).
​
iyr
integer
required
Year.
​
idoy
integer
required
Day of year.
​
UT
double
required
Time in seconds.
​
xHAE
double[3]
required
Cartesian position in HAE (AU).
​
xHEEQ
double[3]
Cartesian position in HEEQ (AU).
call hae2heeq1(iyr, idoy, UT, xHAE, xHEEQ)
HEEQ2HAE — transforms HEEQ to HAE.
​
xHEEQ
double[3]
required
Cartesian position in HEEQ (AU).
​
xHAE
double[3]
Cartesian position in HAE (AU).
call heeq2hae1(iyr, idoy, UT, xHEEQ, xHAE)

Build docs developers (and LLMs) love

Get started for freeTalk to us