coordinates  module for coordinate transforms¶
Implementation of Coords class functions for coordinate transformations
The coordinate systems supported by this module cover the most commonly used geophysical and magnetospheric systems. The naming conventions can follow the names used by the popular IRBEM library, but for inertial systems we use a more consistent, finegrained naming convention that clarifies the different systems.
Earthcentered Inertial Systems¶
ECI2000 Earthcentered Inertial, J2000 epoch
ECIMOD Earthcentered Inertial, meanofdate
ECITOD Earthcentered Inertial, trueofdate
GEI Geocentric Equatorial Inertial (IRBEM approximation of TOD)
Magnetospheric Systems¶
GSM Geocentric Solar Magnetospheric
GSE Geocentric Solar Ecliptic
SM Solar Magnetic
MAG Geomagnetic Coordinate System (aka CDMAG)
Earthfixed Systems¶
GEO Geocentric geographic, aka Earthcentered Earthfixed
GDZ Geodetic coordinates
By convention all systems are treated as natively Cartesian except geodetic (GDZ), which is defined in [altitude, latitude, longitude] where altitude is relative to a reference ellipsoid. Similarly, distance units are assumed to be Earth radii (Re) in all systems except GDZ, where altitude is given in km. Conversions to GDZ will output altitude in km regardless of the input distance units and conversions from GDZ will output in Re regardless of input units. In all other cases, the distance units will be preserved.
Changed in version 0.3.0.
The new CTrans backend was added, which includes support for the names
ECI2000
,ECIMOD
,ECITOD
, andCDMAG
. With the exception ofECIMOD
, these can be used with the existing IRBEM backend, and will be converted to their closest equivalents.Changed in version 0.4.0.
The default backend for coordinate transformations was changed from IRBEM to the CTransbased SpacePy backend.
Notes on differences between representations¶
IRBEM’s coordinate transformations are lowaccuracy and were written for a library with a driving philosophy of speed and robustness as priorities. The coordinate transformations are therefore approximate. Further, most of the geophysical systems (e.g., GSE, SM) are derived from an inertial system. It is standard practice to use ECIMOD as this system. However, IRBEM does not currently make ECIMOD available as one of its inertial systems. IRBEM’s default inertial system (called GEI) is consistent with an approximation of ECITOD. Hence there will be small differences between IRBEM’s transformations and those using SpacePy’s CTrans backend. Further sources of difference include: IRBEM uses a loworder approximation to the sidereal time and other parameters; the calculation of the EarthSun vector differs between the representations; the definitions of an Earth radius differ (SpacePy = 6378.137km; IRBEM = 6371.2 km). SpacePy’s inbuilt representation is higher accuracy and is comprehensively tested, including tests for consistency with other high accuracy packages such as LANLGeoMag and AstroPy. However, for use cases where the required precision is of order 1 percent the output can be considered equivalent.
Setting options for coordinate transformation¶
The backend for coordinate transformations can be provided at
instantiation of a Coords
object using a keyword
argument. However, for convenience and flexibility the options can be
set at the module level. Configurable options include the backend used
(irbempy
or SpacePy’s ctrans
) and the
reference ellipsoid (only configurable for the SpacePy backend). A
warning will be raised if the backend is not set (either through the
defaults or the keyword argument). The final configurable option
(itol
) is the maximum separation, in seconds, for which the
coordinate transformations will not be recalculated. To force all
transformations to use an exact transform for the time, set itol
to zero. Values between 10s and 60s are recommended for speed while
also preserving accuracy, though different applications will require
different accuracies. For example, assuming this module has been
imported as spc
, to set the SpacePy backend as the default and set
itol
to 5 seconds:
>>> spc.DEFAULTS.set_values(use_irbem=False, itol=5)
Authors: Steven Morley and Josef Koller Institution: Los ALamos National Laboratory Contact: smorley@lanl.gov
Copyright 20102016 Los Alamos National Security, LLC.
Classes

A class holding spatial coordinates and enabling transformation between coordinate systems. 
Functions

Coordinate transformation from Cartesian to spherical 

Coordinate transformation from spherical to Cartesian 

Given quaternions and vectors, return the vectors rotated by the quaternions 

Given an input quaternion (or array of quaternions), return the unit quaternion 

Given quaternions, return the product, i.e. Qin1*Qin2. 

Given an input quaternion (or array of quaternions), return the conjugate 

Given an input rotation matrix, return the equivalent quaternion 

Given an input quaternion, return the equivalent rotation matrix. 