Py ERFA:docs

- Index
- Modules

### Navigation

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

# starpv

erfa.starpv(ra, dec, pmr, pmd, px, rv)

  Convert star catalog coordinates to position+velocity vector.

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

  Notes

  Wraps ERFA function `eraStarpv`. The ERFA documentation is:

      - - - - - - - - - -
       e r a S t a r p v
      - - - - - - - - - -

      Convert star catalog coordinates to position+velocity vector.

      Given (Note 1):
         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 (arcseconds)
         rv     double        radial velocity (km/s, positive = receding)

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

      Returned (function value):
                int           status:
                                  0 = no warnings
                                  1 = distance overridden (Note 6)
                                  2 = excessive speed (Note 7)
                                  4 = solution didn't converge (Note 8)
                               else = binary logical OR of the above

      Notes:

      1) The star data accepted 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 pv-vector is likely to be
         merely an intermediate result, so that a change of time unit
         would 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.

      2) The resulting position and velocity pv-vector is with respect to
         the same frame and, like the catalog coordinates, is freed from
         the effects of secular aberration.  Should the "coordinate
         direction", where the object was located at the catalog epoch, be
         required, it may be obtained by calculating the magnitude of the
         position vector pv[0][0-2] dividing by the speed of light in
         au/day to give the light-time, and then multiplying the space
         velocity pv[1][0-2] by this light-time and adding the result to
         pv[0][0-2].

         Summarizing, the pv-vector returned is for most stars almost
         identical to the result of applying the standard geometrical
         "space motion" transformation.  The differences, which are the
         subject of the Stumpff paper referenced 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 RA proper motion is in terms of coordinate angle, not true
         angle.  If the catalog uses arcseconds for both RA and Dec proper
         motions, the RA proper motion will need to be divided by cos(Dec)
         before use.

      5) Straight-line motion at constant speed, in the inertial frame,
         is assumed.

      6) An extremely small (or zero or negative) parallax is interpreted
         to mean that the object is on the "celestial sphere", the radius
         of which is an arbitrary (large) value (see the constant PXMIN).
         When the distance is overridden in this way, the status,
         initially zero, has 1 added to it.

      7) If the space velocity is a significant fraction of c (see the
         constant VMAX), it is arbitrarily set to zero.  When this action
         occurs, 2 is added to the status.

      8) The relativistic adjustment involves an iterative calculation.
         If the process fails to converge within a set number (IMAX) of
         iterations, 4 is added to the status.

      9) The inverse transformation is performed by the function
         eraPvstar.

      Called:
         eraS2pv      spherical coordinates to pv-vector
         eraPm        modulus of p-vector
         eraZp        zero p-vector
         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
         eraPpp       p-vector plus p-vector

      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.