Convert star position+velocity vector to catalog coordinates.

pvdouble array
radouble array
decdouble array
pmrdouble array
pmddouble array
pxdouble array
rvdouble array


Wraps ERFA function eraPvstar. The ERFA documentation is:

- - - - - - - - - -
 e r a P v s t a r
- - - - - - - - - -

Convert star position+velocity vector to catalog coordinates.

Given (Note 1):
   pv     double[2][3]   pv-vector (au, au/day)

Returned (Note 2):
   ra     double         right ascension (radians)
   dec    double         declination (radians)
   pmr    double         RA proper motion (radians/year)
   pmd    double         Dec proper motion (radians/year)
   px     double         parallax (arcsec)
   rv     double         radial velocity (km/s, positive = receding)

Returned (function value):
          int            status:
                            0 = OK
                           -1 = superluminal speed (Note 5)
                           -2 = null position vector


1) The specified pv-vector is the coordinate direction (and its rate
   of change) for the date at which the light leaving the star
   reached the solar-system barycenter.

2) The star data returned by this function are "observables" for an
   imaginary observer at the solar-system barycenter.  Proper motion
   and radial velocity are, strictly, in terms of barycentric
   coordinate time, TCB.  For most practical applications, it is
   permissible to neglect the distinction between TCB and ordinary
   "proper" time on Earth (TT/TAI).  The result will, as a rule, be
   limited by the intrinsic accuracy of the proper-motion and
   radial-velocity data;  moreover, the supplied pv-vector is likely
   to be merely an intermediate result (for example generated by the
   function eraStarpv), so that a change of time unit will cancel
   out overall.

   In accordance with normal star-catalog conventions, the object's
   right ascension and declination are freed from the effects of
   secular aberration.  The frame, which is aligned to the catalog
   equator and equinox, is Lorentzian and centered on the SSB.

   Summarizing, the specified pv-vector is for most stars almost
   identical to the result of applying the standard geometrical
   "space motion" transformation to the catalog data.  The
   differences, which are the subject of the Stumpff paper cited
   below, are:

   (i) In stars with significant radial velocity and proper motion,
   the constantly changing light-time distorts the apparent proper
   motion.  Note that this is a classical, not a relativistic,

   (ii) The transformation complies with special relativity.

3) Care is needed with units.  The star coordinates are in radians
   and the proper motions in radians per Julian year, but the
   parallax is in arcseconds; the radial velocity is in km/s, but
   the pv-vector result is in au and au/day.

4) The proper motions are the rate of change of the right ascension
   and declination at the catalog epoch and are in radians per Julian
   year.  The RA proper motion is in terms of coordinate angle, not
   true angle, and will thus be numerically larger at high

5) Straight-line motion at constant speed in the inertial frame is
   assumed.  If the speed is greater than or equal to the speed of
   light, the function aborts with an error status.

6) The inverse transformation is performed by the function eraStarpv.

   eraPn        decompose p-vector into modulus and direction
   eraPdp       scalar product of two p-vectors
   eraSxp       multiply p-vector by scalar
   eraPmp       p-vector minus p-vector
   eraPm        modulus of p-vector
   eraPpp       p-vector plus p-vector
   eraPv2s      pv-vector to spherical
   eraAnp       normalize angle into range 0 to 2pi


   Stumpff, P., 1985, Astron.Astrophys. 144, 232-240.

This revision:  2023 May 4

Copyright (C) 2013-2023, NumFOCUS Foundation.
Derived, with permission, from the SOFA library.  See notes at end of file.