ERFA/SOFA JS functions (auto converted)

This JS library is a conversion from liberfa (by NumFOCUS Foundation), which is in turn a derived work from IAU SOFA (by Standards Of Fundamental Astronomy Board of the International Astronomical Union).

Converted 2022-06-23 by Marcel Greter (Version 2.0.0 / RELEASE 20210512).

• The conversion is done by a custom hacked perl script.
• Automatically generates QUnit tests for all functions.

If you encounter problems with this work, please open an issue on github.

Preface

The original SOFA distribution by the IAU SOFA Board consists of 244 C (or Fortran) functions (SOFA release 15 2019-07-22). But we use ERFA instead, which it is a direct derivate under a more permissive license. All function are converted to JS by a custom hacked perl script with a lot of regex magic. JS and C are surprisingly similar in their basic syntax, if you leave out most of the C modifiers.

The main obstacles involved:

• Converting structs to objects
• Converting C arrays to JS arrays
• Support C integer calculations

Future ERFA/SOFA releases may or may not work without modifications to the converter script. For some cases I took a shortcut and added specific regular expressions for the correct conversion. The script is really just a hack that gets the job done. I have no intention to expand it into a complete C99 or even C++ to JS converter.

How does it work

<script src="dist/sofa.min.js"></script>

Due to fundamental differences between C and JS I had to adopt the way how output values work. The original C functions use pointers to doubles or integers to be filled by the invoked function. JS doesn't have a directly equivalent feature. We could pass an array or object to be altered by the invoked function. But I opted to return an array directly with all output values (if more than one is returned).

Output values consist of the C function return value (ignored if the C function return type is void) and all values passed as pointers to the C function (structs are handled the same). The return from the JS function is not wrapped in an array if there is only one output value (either the return value from the C function or one "pointer" value).

Usage Examples:

rv = ERFA.era00(dj1, dj2);
rc2i = ERFA.c2i00a(date1, date2);
[dr, dd] = ERFA.g2icrs(dl, db);

C to JS convert example:

Illustrating a function call (stripped down):

int eraJdcalf(int ndp, double dj1, double dj2, int iymdf[4]) {
  /* Convert to Gregorian calendar. */
  js = eraJd2cal(d1, d2, &iymdf[0], &iymdf[1], &iymdf[2], &f);
  iymdf[3] = (int) (f * denom);
  return j;
}

function eraJdcalf(ndp, dj1, dj2) {
  var iymdf = [0,0,0,0];
  /* Convert to Gregorian calendar. */
  js = ~~((_rv1 = eraJd2cal(d1, d2))[0]);
  iymdf[0] = _rv1[1];
  iymdf[1] = _rv1[2];
  iymdf[2] = _rv1[3];
  f = _rv1[4];
  iymdf[3] = ~~(f * denom);
  return [ j, iymdf ];
}

Value types

There are only a few value types beside the primitives (int, double) and the more complex struct "objects". All of them map nicely to JS arrays (V3, MAT33) or JS objects (ASTROM, LDBODY). Following a few examples of how the most basic types are mapped between C and JS:

v3[3] => [ 0, 0, 0 ]
pv3[2][3] => [ v3, v3 ]
mat33[3][3] => [ v3, v3, v3 ]

QUnit tests

For each function the converter generates a C program that produces the test data for the unit tests. This is done by calling the original C functions from the SOFA distribution. This is manually configured in the converter script for every function, since I needed to control how many results are generated and over which ranges (fine-tuning needed).

• https://www.ocbnet.ch/thrastro/sofa.js/test/index.html

Function list

The list below and the linked documentations are extracted from the ERFA source files provided by NumFOCUS Foundation.

Canonical:

• ERFA.eform - Earth reference ellipsoids.
• ERFA.taitt - International Atomic Time, TAI, to Terrestrial Time, TT.
• ERFA.taiut1 - International Atomic Time, TAI, to Universal Time, UT1.
• ERFA.taiutc - International Atomic Time, TAI, to Coordinated Universal Time, UTC.
• ERFA.tcbtdb - Barycentric Coordinate Time, TCB, to Barycentric Dynamical Time,...
• ERFA.tcgtt - Geocentric Coordinate Time, TCG, to Terrestrial Time, TT.
• ERFA.tdbtcb - Barycentric Dynamical Time, TDB, to Barycentric Coordinate Time,...
• ERFA.tdbtt - Barycentric Dynamical Time, TDB, to Terrestrial Time, TT.
• ERFA.tttai - Terrestrial Time, TT, to International Atomic Time, TAI.
• ERFA.tttcg - Terrestrial Time, TT, to Geocentric Coordinate Time, TCG.
• ERFA.tttdb - Terrestrial Time, TT, to Barycentric Dynamical Time, TDB.
• ERFA.ttut1 - Terrestrial Time, TT, to Universal Time, UT1.
• ERFA.ut1tai - Universal Time, UT1, to International Atomic Time, TAI.
• ERFA.ut1tt - Universal Time, UT1, to Terrestrial Time, TT.
• ERFA.ut1utc - Universal Time, UT1, to Coordinated Universal Time, UTC.
• ERFA.utctai - Coordinated Universal Time, UTC, to International Atomic Time, TAI.
• ERFA.utcut1 - Coordinated Universal Time, UTC, to Universal Time, UT1.

Canonical model:

• ERFA.bi00 - Frame bias components of IAU 2000 precession-nutation models (part...
• ERFA.bp00 - Frame bias and precession, IAU 2000.
• ERFA.ee00 - The equation of the equinoxes, compatible with IAU 2000 resolution...
• ERFA.eect00 - Equation of the equinoxes complementary terms, consistent with I...
• ERFA.eqeq94 - Equation of the equinoxes, IAU 1994 model.
• ERFA.era00 - Earth rotation angle (IAU 2000 model).
• ERFA.fad03 - Fund'Args IERS(2003): mean elongation of the Moon from the Sun.
• ERFA.fae03 - Fund'Args IERS(2003): mean longitude of Earth.
• ERFA.faf03 - Fund'Args IERS(2003): mean longitude of the Moon minus mean longi...
• ERFA.faju03 - Fund'Args IERS(2003): mean longitude of Jupiter.
• ERFA.fal03 - Fund'Args IERS(2003): mean anomaly of the Moon.
• ERFA.falp03 - Fund'Args IERS(2003): mean anomaly of the Sun.
• ERFA.fama03 - Fund'Args IERS(2003): mean longitude of Mars.
• ERFA.fame03 - Fund'Args IERS(2003): mean longitude of Mercury.
• ERFA.fane03 - Fund'Args IERS(2003): mean longitude of Neptune.
• ERFA.faom03 - Fund'Args IERS(2003): mean longitude of the Moon's ascending node.
• ERFA.fapa03 - Fund'Args IERS(2003): general accumulated precession in longitude.
• ERFA.fasa03 - Fund'Args IERS(2003): mean longitude of Saturn.
• ERFA.faur03 - Fund'Args IERS(2003): mean longitude of Uranus.
• ERFA.fave03 - Fund'Args IERS(2003): mean longitude of Venus.
• ERFA.gmst00 - Greenwich mean sidereal time (model consistent with IAU 2000 res...
• ERFA.gmst06 - Greenwich mean sidereal time (consistent with IAU 2006 precession).
• ERFA.gmst82 - Universal Time to Greenwich mean sidereal time (IAU 1982 model).
• ERFA.gst00a - Greenwich apparent sidereal time (consistent with IAU 2000 resol...
• ERFA.gst06a - Greenwich apparent sidereal time (consistent with IAU 2000 and 2...
• ERFA.nut00a - Nutation, IAU 2000A model (MHB2000 luni-solar and planetary nuta...
• ERFA.nut00b - Nutation, IAU 2000B model.
• ERFA.nut06a - IAU 2000A nutation with adjustments to match the IAU 2006 preces...
• ERFA.nut80 - Nutation, IAU 1980 model.
• ERFA.obl06 - Mean obliquity of the ecliptic, IAU 2006 precession model.
• ERFA.obl80 - Mean obliquity of the ecliptic, IAU 1980 model.
• ERFA.pfw06 - Precession angles, IAU 2006 (Fukushima-Williams 4-angle formulati...
• ERFA.pr00 - Precession-rate part of the IAU 2000 precession-nutation models (p...
• ERFA.prec76 - IAU 1976 precession model.
• ERFA.s00 - The CIO locator s, positioning the Celestial Intermediate Origin on...
• ERFA.s06 - The CIO locator s, positioning the Celestial Intermediate Origin on...
• ERFA.sp00 - The TIO locator s', positioning the Terrestrial Intermediate Origi...
• ERFA.xy06 - X,Y coordinates of celestial intermediate pole from series based o...

Canonical models:

• ERFA.p06e - Precession angles, IAU 2006, equinox based.

Canonical transformation:

• ERFA.gc2gd - Transform geocentric coordinates to geodetic using the specified ...
• ERFA.gd2gc - Transform geodetic coordinates to geocentric using the specified ...

Support function:

• ERFA.ab - Apply aberration to transform natural direction into proper direction.
• ERFA.ae2hd - Horizon to equatorial coordinates: transform azimuth and altitude...
• ERFA.af2a - Convert degrees, arcminutes, arcseconds to radians.
• ERFA.apcg - For a geocentric observer, prepare star-independent astrometry par...
• ERFA.apcg13 - For a geocentric observer, prepare star-independent astrometry p...
• ERFA.apci - For a terrestrial observer, prepare star-independent astrometry pa...
• ERFA.apci13 - For a terrestrial observer, prepare star-independent astrometry ...
• ERFA.apco - For a terrestrial observer, prepare star-independent astrometry pa...
• ERFA.apco13 - For a terrestrial observer, prepare star-independent astrometry ...
• ERFA.apcs - For an observer whose geocentric position and velocity are known, ...
• ERFA.apcs13 - For an observer whose geocentric position and velocity are known...
• ERFA.aper - In the star-independent astrometry parameters, update only the Ear...
• ERFA.aper13 - In the star-independent astrometry parameters, update only the E...
• ERFA.apio - For a terrestrial observer, prepare star-independent astrometry pa...
• ERFA.apio13 - For a terrestrial observer, prepare star-independent astrometry ...
• ERFA.atci13 - Transform ICRS star data, epoch J2000.0, to CIRS.
• ERFA.atciq - Quick ICRS, epoch J2000.0, to CIRS transformation, given precompu...
• ERFA.atciqn - Quick ICRS, epoch J2000.0, to CIRS transformation, given precomp...
• ERFA.atciqz - Quick ICRS to CIRS transformation, given precomputed star- indep...
• ERFA.atco13 - ICRS RA,Dec to observed place. The caller supplies UTC, site coo...
• ERFA.atic13 - Transform star RA,Dec from geocentric CIRS to ICRS astrometric.
• ERFA.aticq - Quick CIRS RA,Dec to ICRS astrometric place, given the star- inde...
• ERFA.aticqn - Quick CIRS to ICRS astrometric place transformation, given the s...
• ERFA.atio13 - CIRS RA,Dec to observed place. The caller supplies UTC, site coo...
• ERFA.atioq - Quick CIRS to observed place transformation.
• ERFA.atoc13 - Observed place at a groundbased site to to ICRS astrometric RA,D...
• ERFA.atoi13 - Observed place to CIRS. The caller supplies UTC, site coordinate...
• ERFA.atoiq - Quick observed place to CIRS, given the star-independent astromet...
• ERFA.bp06 - Frame bias and precession, IAU 2006.
• ERFA.bpn2xy - Extract from the bias-precession-nutation matrix the X,Y coordin...
• ERFA.c2i00a - Form the celestial-to-intermediate matrix for a given date using...
• ERFA.c2i00b - Form the celestial-to-intermediate matrix for a given date using...
• ERFA.c2i06a - Form the celestial-to-intermediate matrix for a given date using...
• ERFA.c2ibpn - Form the celestial-to-intermediate matrix for a given date given...
• ERFA.c2ixy - Form the celestial to intermediate-frame-of-date matrix for a giv...
• ERFA.c2ixys - Form the celestial to intermediate-frame-of-date matrix given th...
• ERFA.c2t00a - Form the celestial to terrestrial matrix given the date, the UT1...
• ERFA.c2t00b - Form the celestial to terrestrial matrix given the date, the UT1...
• ERFA.c2t06a - Form the celestial to terrestrial matrix given the date, the UT1...
• ERFA.c2tcio - Assemble the celestial to terrestrial matrix from CIO-based comp...
• ERFA.c2teqx - Assemble the celestial to terrestrial matrix from equinox-based ...
• ERFA.c2tpe - Form the celestial to terrestrial matrix given the date, the UT1,...
• ERFA.c2txy - Form the celestial to terrestrial matrix given the date, the UT1,...
• ERFA.cal2jd - Gregorian Calendar to Julian Date.
• ERFA.d2dtf - Format for output a 2-part Julian Date (or in the case of UTC a q...
• ERFA.dat - For a given UTC date, calculate Delta(AT) = TAI-UTC.
• ERFA.dtf2d - Encode date and time fields into 2-part Julian Date (or in the ca...
• ERFA.eceq06 - Transformation from ecliptic coordinates (mean equinox and eclip...
• ERFA.ecm06 - ICRS equatorial to ecliptic rotation matrix, IAU 2006.
• ERFA.ee00a - Equation of the equinoxes, compatible with IAU 2000 resolutions.
• ERFA.ee00b - Equation of the equinoxes, compatible with IAU 2000 resolutions b...
• ERFA.ee06a - Equation of the equinoxes, compatible with IAU 2000 resolutions a...
• ERFA.eo06a - Equation of the origins, IAU 2006 precession and IAU 2000A nutation.
• ERFA.eors - Equation of the origins, given the classical NPB matrix and the qu...
• ERFA.epb - Julian Date to Besselian Epoch.
• ERFA.epb2jd - Besselian Epoch to Julian Date.
• ERFA.epj - Julian Date to Julian Epoch.
• ERFA.epj2jd - Julian Epoch to Julian Date.
• ERFA.epv00 - Earth position and velocity, heliocentric and barycentric, with r...
• ERFA.eqec06 - Transformation from ICRS equatorial coordinates to ecliptic coor...
• ERFA.fk425 - Convert B1950.0 FK4 star catalog data to J2000.0 FK5.
• ERFA.fk45z - Convert a B1950.0 FK4 star position to J2000.0 FK5, assuming zero...
• ERFA.fk524 - Convert J2000.0 FK5 star catalog data to B1950.0 FK4.
• ERFA.fk52h - Transform FK5 (J2000.0) star data into the Hipparcos system.
• ERFA.fk54z - Convert a J2000.0 FK5 star position to B1950.0 FK4, assuming zero...
• ERFA.fk5hip - FK5 to Hipparcos rotation and spin.
• ERFA.fk5hz - Transform an FK5 (J2000.0) star position into the system of the H...
• ERFA.fw2m - Form rotation matrix given the Fukushima-Williams angles.
• ERFA.fw2xy - CIP X,Y given Fukushima-Williams bias-precession-nutation angles.
• ERFA.gc2gde - Transform geocentric coordinates to geodetic for a reference ell...
• ERFA.gd2gce - Transform geodetic coordinates to geocentric for a reference ell...
• ERFA.gst00b - Greenwich apparent sidereal time (consistent with IAU 2000 resol...
• ERFA.gst06 - Greenwich apparent sidereal time, IAU 2006, given the NPB matrix.
• ERFA.gst94 - Greenwich apparent sidereal time (consistent with IAU 1982/94 res...
• ERFA.h2fk5 - Transform Hipparcos star data into the FK5 (J2000.0) system.
• ERFA.hd2ae - Equatorial to horizon coordinates: transform hour angle and decli...
• ERFA.hd2pa - Parallactic angle for a given hour angle and declination.
• ERFA.hfk5z - Transform a Hipparcos star position into FK5 J2000.0, assuming ze...
• ERFA.jd2cal - Julian Date to Gregorian year, month, day, and fraction of a day.
• ERFA.jdcalf - Julian Date to Gregorian Calendar, expressed in a form convenien...
• ERFA.ld - Apply light deflection by a solar-system body, as part of transformi...
• ERFA.ldn - For a star, apply light deflection by multiple solar-system bodies,...
• ERFA.ldsun - Deflection of starlight by the Sun.
• ERFA.lteceq - Transformation from ecliptic coordinates (mean equinox and eclip...
• ERFA.ltecm - ICRS equatorial to ecliptic rotation matrix, long-term.
• ERFA.lteqec - Transformation from ICRS equatorial coordinates to ecliptic coor...
• ERFA.ltp - Long-term precession matrix.
• ERFA.ltpb - Long-term precession matrix, including ICRS frame bias.
• ERFA.ltpecl - Long-term precession of the ecliptic.
• ERFA.ltpequ - Long-term precession of the equator.
• ERFA.num00a - Form the matrix of nutation for a given date, IAU 2000A model.
• ERFA.num00b - Form the matrix of nutation for a given date, IAU 2000B model.
• ERFA.num06a - Form the matrix of nutation for a given date, IAU 2006/2000A model.
• ERFA.numat - Form the matrix of nutation.
• ERFA.nutm80 - Form the matrix of nutation for a given date, IAU 1980 model.
• ERFA.pb06 - This function forms three Euler angles which implement general pre...
• ERFA.plan94 - Approximate heliocentric position and velocity of a nominated ma...
• ERFA.pmat00 - Precession matrix (including frame bias) from GCRS to a specifie...
• ERFA.pmat06 - Precession matrix (including frame bias) from GCRS to a specifie...
• ERFA.pmat76 - Precession matrix from J2000.0 to a specified date, IAU 1976 model.
• ERFA.pmpx - Proper motion and parallax.
• ERFA.pmsafe - Star proper motion: update star catalog data for space motion, w...
• ERFA.pn00 - Precession-nutation, IAU 2000 model: a multi-purpose function, sup...
• ERFA.pn00a - Precession-nutation, IAU 2000A model: a multi-purpose function, s...
• ERFA.pn00b - Precession-nutation, IAU 2000B model: a multi-purpose function, s...
• ERFA.pn06 - Precession-nutation, IAU 2006 model: a multi-purpose function, sup...
• ERFA.pn06a - Precession-nutation, IAU 2006/2000A models: a multi-purpose funct...
• ERFA.pnm00a - Form the matrix of precession-nutation for a given date (includi...
• ERFA.pnm00b - Form the matrix of precession-nutation for a given date (includi...
• ERFA.pnm06a - Form the matrix of precession-nutation for a given date (includi...
• ERFA.pnm80 - Form the matrix of precession/nutation for a given date, IAU 1976...
• ERFA.pom00 - Form the matrix of polar motion for a given date, IAU 2000.
• ERFA.pvstar - Convert star position+velocity vector to catalog coordinates.
• ERFA.pvtob - Position and velocity of a terrestrial observing station.
• ERFA.refco - Determine the constants A and B in the atmospheric refraction mod...
• ERFA.s00a - The CIO locator s, positioning the Celestial Intermediate Origin o...
• ERFA.s00b - The CIO locator s, positioning the Celestial Intermediate Origin o...
• ERFA.s06a - The CIO locator s, positioning the Celestial Intermediate Origin o...
• ERFA.starpm - Star proper motion: update star catalog data for space motion.
• ERFA.starpv - Convert star catalog coordinates to position+velocity vector.
• ERFA.tf2a - Convert hours, minutes, seconds to radians.
• ERFA.tf2d - Convert hours, minutes, seconds to days.
• ERFA.tpors - In tangent plane, given the rectangular coordinates of a star and...
• ERFA.tporv - In tangent plane, given the rectangular coordinates of a star and...
• ERFA.tpsts - In tangent plane, given the star's rectangular coordinates and th...
• ERFA.tpstv - In tangent plane, given the star's rectangular coordinates and th...
• ERFA.tpxes - In tangent plane, given celestial spherical coordinates for a sta...
• ERFA.tpxev - In tangent plane, given celestial direction cosines for a star an...
• ERFA.xys00a - For a given TT date, compute the X,Y coordinates of the Celestia...
• ERFA.xys00b - For a given TT date, compute the X,Y coordinates of the Celestia...
• ERFA.xys06a - For a given TT date, compute the X,Y coordinates of the Celestia...

Support routine:

• ERFA.dtdb - An approximation to TDB-TT, the difference between barycentric dyn...
• ERFA.g2icrs - Transformation from Galactic Coordinates to ICRS.
• ERFA.icrs2g - Transformation from ICRS to Galactic Coordinates.

Vector/matrix support function:

• ERFA.a2af - Decompose radians into degrees, arcminutes, arcseconds, fraction.
• ERFA.a2tf - Decompose radians into hours, minutes, seconds, fraction.
• ERFA.anp - Normalize angle into the range 0 <= a < 2pi.
• ERFA.anpm - Normalize angle into the range -pi <= a < +pi.
• ERFA.c2s - P-vector to spherical coordinates.
• ERFA.cp - Copy a p-vector.
• ERFA.cpv - Copy a position/velocity vector.
• ERFA.cr - Copy an r-matrix.
• ERFA.d2tf - Decompose days to hours, minutes, seconds, fraction.
• ERFA.ir - Initialize an r-matrix to the identity matrix.
• ERFA.p2pv - Extend a p-vector to a pv-vector by appending a zero velocity.
• ERFA.p2s - P-vector to spherical polar coordinates.
• ERFA.pap - Position-angle from two p-vectors.
• ERFA.pas - Position-angle from spherical coordinates.
• ERFA.pdp - p-vector inner (=scalar=dot) product.
• ERFA.pm - Modulus of p-vector.
• ERFA.pmp - P-vector subtraction.
• ERFA.pn - Convert a p-vector into modulus and unit vector.
• ERFA.ppp - P-vector addition.
• ERFA.ppsp - P-vector plus scaled p-vector.
• ERFA.pv2p - Discard velocity component of a pv-vector.
• ERFA.pv2s - Convert position/velocity from Cartesian to spherical coordinates.
• ERFA.pvdpv - Inner (=scalar=dot) product of two pv-vectors.
• ERFA.pvm - Modulus of pv-vector.
• ERFA.pvmpv - Subtract one pv-vector from another.
• ERFA.pvppv - Add one pv-vector to another.
• ERFA.pvu - Update a pv-vector.
• ERFA.pvup - Update a pv-vector, discarding the velocity component.
• ERFA.pvxpv - Outer (=vector=cross) product of two pv-vectors.
• ERFA.pxp - p-vector outer (=vector=cross) product.
• ERFA.rm2v - Express an r-matrix as an r-vector.
• ERFA.rv2m - Form the r-matrix corresponding to a given r-vector.
• ERFA.rx - Rotate an r-matrix about the x-axis.
• ERFA.rxp - Multiply a p-vector by an r-matrix.
• ERFA.rxpv - Multiply a pv-vector by an r-matrix.
• ERFA.rxr - Multiply two r-matrices.
• ERFA.ry - Rotate an r-matrix about the y-axis.
• ERFA.rz - Rotate an r-matrix about the z-axis.
• ERFA.s2c - Convert spherical coordinates to Cartesian.
• ERFA.s2p - Convert spherical polar coordinates to p-vector.
• ERFA.s2pv - Convert position/velocity from spherical to Cartesian coordinates.
• ERFA.s2xpv - Multiply a pv-vector by two scalars.
• ERFA.sepp - Angular separation between two p-vectors.
• ERFA.seps - Angular separation between two sets of spherical coordinates.
• ERFA.sxp - Multiply a p-vector by a scalar.
• ERFA.sxpv - Multiply a pv-vector by a scalar.
• ERFA.tr - Transpose an r-matrix.
• ERFA.trxp - Multiply a p-vector by the transpose of an r-matrix.
• ERFA.trxpv - Multiply a pv-vector by the transpose of an r-matrix.
• ERFA.zp - Zero a p-vector.
• ERFA.zpv - Zero a pv-vector.
• ERFA.zr - Initialize an r-matrix to the null matrix.

License

This work is released under the same terms as erfa.