Py ERFA:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- PyERFA v2.0.0.1 »
- erfa Package »
- pvstar

# pvstar

erfa.pvstar(pv)

  Convert star position+velocity vector to catalog coordinates.

  Parameters
    pv double array
  Returns
    ra double array
    dec double array
    pmr double array
    pmd double array
    px double array
    rv double array

  Notes

  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

      Notes:

      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,
         effect.

         (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
         declinations.

      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.

      Called:
         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

      Reference:

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

      This revision:  2021 May 11

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