| | |
- POINTER(...)
- aberration(position, vel_earth, lighttime)
- Correct the position vector for aberration of light, including
relativistic terms.
Parameters
----------
position : tuple of floats, of length 3
Position vector, referred to origin at center of mass of the
Earth, components in AU.
vel_earth : tuple of floats, of length 3
Velocity vector of center of mass of the Earth, referred to
origin at solar system barycenter, components in AU/day.
lighttime : float
Light time from object to Earth in days.
Returns
-------
position : tuple of floats, of length 3
Position vector, referred to origin at center of mass of the
Earth, corrected for aberration, components in AU.
Notes
-----
.. [N1] If 'lighttime' = 0 on input, this function will compute it.
References
----------
.. [R1] Murray, C. A. (1981) Mon. Notices Royal Ast. Society 195,
639-648.
- addressof(...)
- addressof(C instance) -> integer
Return the address of the C instance internal buffer
- alignment(...)
- alignment(C type) -> integer
alignment(C instance) -> integer
Return the alignment requirements of a C instance
- app_planet(jd_tt, ss_body, accuracy=0)
- Compute the apparent place of a planet or other solar system body.
Parameters
----------
jd_tt : float
TT Julian date for apparent place.
ss_body : Object
Instance of Object type object containing the body designation
for the solar system body.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec, dis) : tuple of floats
Apparent (right ascension in hours, declination in degrees,
...),
referred to true equator and equinox of date, and true
(..., ..., distance in AU) from Earth to solar system body at
'jd_tt'.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C67.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- app_star(jd_tt, star, accuracy=0)
- Computes the apparent place of a star at 'date', given its catalog
mean place, proper motion, parallax, and radial velocity.
Parameters
----------
jd_tt : float
TT Julian date for apparent place.
star : CatEntry
Instance of CatEntry type object containing catalog data for
the object in the ICRS.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec) : tuple of floats
Apparent (right ascension in hours, declination in degrees),
referred to true equator and equinox of date 'jd_tt'.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C61.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- astro_planet(jd_tt, ss_body, accuracy=0)
- Compute the astrometric place of a planet or other solar system
body.
Parameters
----------
jd_tt : float
TT Julian date for astrometric place.
ss_body : Object
Instance of Object type object containing the body designation
for the solar system body.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec, dis) : tuple of floats
Astrometric (right ascension in hours, declination in degrees,
...), referred to the ICRS without light deflection or
aberration, and true (..., ..., distance in AU) from Earth to
solar system body.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C73.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- astro_star(jd_tt, star, accuracy=0)
- Computes the astrometric place of a star at 'date', given its
catalog mean place, proper motion, parallax, and radial velocity.
Parameters
----------
jd_tt : float
TT Julian date for astrometric place.
star : CatEntry
Instance of CatEntry type object containing catalog data for
the object in the ICRS.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec) : tuple of floats
Astrometric (right ascension in hours, declination in degrees),
referred to the ICRS without light deflection or aberration.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C66.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- bary2obs(pos, pos_obs)
- Transform the origin from the solar system barycenter to the
observer (or the geocenter); i.e., correct for parallax
(annual+geocentric or just annual).
Parameters
----------
pos : tuple of floats, of length 3
Position vector, referred to origin at solar system barycenter,
components in AU.
pos_obs : tuple of floats, of length 3
Position vector of observer (or the geocenter), with respect to
origin at solar system barycenter, components in AU.
Returns
-------
(position, lighttime) : tuple of tuple and float
Position vector, referred to origin at center of mass of the
Earth, components in AU, and lighttime of object from Earth in
days.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C17, C109.
- byref(...)
- byref(C instance[, offset=0]) -> byref-object
Return a pointer lookalike to a C instance, only usable
as function argument
- cal_date(day)
- Return the Gregorian date for a given Julian day.
Parameters
----------
day : float
Julian day.
Returns
-------
date : tuple of three ints and a float
The elements are year, month, day and hour.
Notes
-----
.. [N1] This routine valid for any 'jd' greater than zero.
.. [N2] Input Julian date can be based on any UT-like time scale
(UTC, UT1, TT, etc.) -- output time value will have same basis.
References
----------
.. [R1] Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11,
No. 10, October 1968, p. 657.
- cel2ter(jd_ut1_high, jd_ut1_low, delta_t, xp, yp, vec1, method=0, option=0, accuracy=0)
- Rotates a vector from the celestial to the terrestrial system.
Specifically, transforms a vector in the GCRS (a local space-fixed
system) to the ITRS (a rotating earth-fixed system) by applying
rotations for the GCRS-to-dynamical frame tie, precession, nutation,
Earth rotation, and polar motion.
Parameters
----------
jd_ut1_high : float
High-order part of UT1 Julian date.
jd_ut1_low : float
Low-order part of UT1 Julian date.
delta_t : float
Value of Delta T (= TT - UT1) at the input UT1 Julian date.
xp : float
Conventionally-defined X coordinate of celestial intermediate
pole with respect to ITRS pole, in arcseconds.
yp : float
Conventionally-defined Y coordinate of celestial intermediate
pole with respect to ITRS pole, in arcseconds.
vec1 : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to GCRS axes (celestial system) or with respect to the
equator and equinox of date, depending on 'option'.
method : {0, 1}, optional
Selection for method
= 0 ... CIO-based method (default)
= 1 ... equinox-based method
option : {0, 1}, optional
Selection for reference axes
= 0 ... The output vector is referred to GCRS axes.
(default)
= 1 ... The output vector is produced with respect to the
equator and equinox of date. See Note 2 below.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
vec2 : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to ITRS axes (terrestrial system) in the normal case
where 'option' = 0.
Notes
-----
.. [N1] 'xp' = 'yp' = 0 means no polar motion transformation.
.. [N2] The 'option' flag only works for the equinox-based method.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C54.
.. [R2] Kaplan, G. H. (2003), 'Another Look at Non-Rotating
Origins', Proceedings of IAU XXV Joint Discussion 16.
- cel_pole(tjd, type, dpole1, dpole2)
- This function allows for the specification of celestial pole
offsets for high-precision applications. Each set of offsets is
a correction to the modeled position of the pole for a specific
date, derived from observations and published by the IERS.
Parameters
----------
tjd : float
TDB or TT Julian day for pole offsets.
type : {1, 2}
Type of pole offset.
= 1 for corrections to angular coordinates of modeled pole
referred to mean ecliptic of date, that is,
delta-delta-psi and delta-delta-epsilon.
= 2 for corrections to components of modeled pole unit
vector referred to GCRS axes, that is, dx and dy.
dpole1 : float
Value of celestial pole offset in first coordinate,
(delta-delta-psi or dx) in milliarcseconds.
dpole2 : float
Value of celestial pole offset in second coordinate,
(delta-delta-epsilon or dy) in milliarcseconds.
Notes
-----
.. [N1] This function sets the values of global variables 'PSI_COR'
and 'EPS_COR' declared at the top of file 'novas.c'. These
global variables are used only in NOVAS function 'e_tilt'.
.. [N2] This function, if used, should be called before any other
NOVAS functions for a given date. Values of the pole offsets
specified via a call to this function will be used until
explicitly changed.
.. [N3] 'tjd' is used only for 'type' = 2, to transform dx and dy to
the equivalent delta-delta-psi and delta-delta-epsilon values.
.. [N4] For 'type' = 2, dx and dy are unit vector component
corrections, but are expressed in milliarcseconds simply by
multiplying by 206264806, the number of milliarcseconds in one
radian.
References
----------
.. [R1] Kaplan, G. (2005), US Naval Observatory Circular 179.
.. [R2] Kaplan, G. (2003), USNO/AA Technical Note 2003-03.
- cio_basis(jd_tdb, ra_cio, system, accuracy=0)
- Compute the orthonormal basis vectors, with respect to the GCRS
(geocentric ICRS), of the celestial intermediate system defined by
the celestial intermediate pole (CIP) (in the z direction) and the
celestial intermediate origin (CIO) (in the x direction). A TDB
Julian date and the right ascension of the CIO at that date is
required as input. The right ascension of the CIO can be with
respect to either the GCRS origin or the true equinox of date --
different algorithms are used in the two cases.
Parameters
----------
jd_tdb : float
TDB Julian date of epoch.
ra_cio : float
Right ascension of the CIO at epoch in hours.
system : {1, 2}, optional
Reference system in which right ascension is given (output
from function 'cio_location')
= 1 ... GCRS
= 2 ... True equator and equinox of date
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(x, y, z) : tuple of floats
Unit vector toward (the CIO, the y-direction, north celestial
pole (CIP)), equatorial rectangular coordinates, referred to
the GCRS
Notes
-----
.. [N1] This function effectively constructs the matrix C in eq. (3)
of the reference.
References
----------
.. [R1] Kaplan, G. (2005), US Naval Observatory Circular 179.
- cio_location(jd_tdb, accuracy=0)
- cio_ra(jd_tt, accuracy=0)
- Returns the true right ascension of the celestial intermediate
origin (CIO) at a given TT Julian date. This is -(equation of the
origins).
Parameters
----------
jd_tt : float
TT Julian day.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
ra_cio : float
Right ascension of the CIO, with respect to the true equinox
of date, in hours (+ or -).
References
----------
.. [R1] Kaplan, G. (2005), US Naval Observatory Circular 179.
- d_light(pos_star, pos_obs)
- Computes the difference in light-time, for a star, between the
barycenter of the solar system and the observer (or the geocenter).
Parameters
----------
pos_star : tuple of floats, of length 3
Position vector of star, with respect to origin at solar system
barycenter.
pos_obs : tuple of floats, of length 3
Position vector of observer (or the geocenter), with respect
to origin at solar system barycenter, components in AU.
Returns
-------
diflt : float
Difference in light time, in the sense star to barycenter minus
star to earth, in days.
Notes
-----
.. [N1] Alternatively, this function returns the light-time from the
observer (or the geocenter) to a point on a light ray that is
closest to a specific solar system body. For this purpose, 'pos1'
is the position vector toward observed object, with respect to
origin at observer (or the geocenter); 'pos_obs' is the position
vector of solar system body, with respect to origin at observer
(or the geocenter), components in AU; and the returned value is
the light time to point on line defined by 'pos1' that is closest
to solar system body (positive if light passes body before hitting
observer, i.e., if 'pos1' is within 90 degrees of 'pos_obs').
- e_tilt(jd_tdb, accuracy=0)
- Computes quantities related to the orientation of the Earth's
rotation axis at the given Julian day.
Parameters
----------
jd_tdb : float
TDB Julian date.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output quantities.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(mobl, tobl, ee, dpsi, deps) : tuple of five floats
mobl = mean obliquity of the ecliptic in degrees.
tobl = true obliquity of the ecliptic in degrees.
ee = equation of the equinoxes in seconds of time.
dpsi = nutation in longitude in arcseconds.
deps = nutation in obliquity in arcseconds.
Notes
-----
.. [N1] Values of the celestial pole offsets 'PSI_COR' and 'EPS_COR'
are set using function 'cel_pole', if desired. See the docstring
for 'cel_pole' for details.
- ecl2equ_vec(jd_tt, position, coord_sys=2, accuracy=0)
- Converts an ecliptic position vector to an equatorial position
vector.
Parameters
----------
jd_tt : float
TT Julian date of equator, equinox, and ecliptic used for
coordinates.
position : tuple of floats, of length 3
Position vector, referred to specified ecliptic and equinox of
date. If 'system' = 2, 'position' must be on mean ecliptic and
equinox of J2000.0; see Note [N1]_ below.
coord_sys : {0, 1, 2}, optional
= 0 ... mean equator and equinox of date
= 1 ... true equator and equinox of date
= 2 ... ICRS (ecliptic is always the mean plane) (default)
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
position2 : tuple of floats, of length 3
Position vector, referred to specified ecliptic and equinox of
date.
Notes
-----
.. [N1] To convert an ecliptic vector (mean ecliptic and equinox of
J2000.0 only) to an ICRS vector, set 'system' = 2; the value
of 'jd_tt' can be set to anything, since J2000.0 is assumed.
Except for the output from this case, all vectors are assumed to
be with respect to a dynamical system.
- ee_ct(jd_tt_high, jd_tt_low, accuracy=0)
- To compute the "complementary terms" of the equation of the
equinoxes.
Parameters
----------
jd_tt_high : float
High-order (integer) part of TT Julian day.
jd_tt_low : float
Low-order (fractional) part of TT Julian day.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the terms.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
comp_terms : float
Complementary terms, in radians.
Notes
-----
.. [N1] The series used in this function was derived from the first
reference. This same series was also adopted for use in the
IAU's Standards of Fundamental Astronomy (SOFA) software (i.e.,
subroutine eect00.for and function eect00.c).
.. [N2] The low-accuracy series used in this function is a simple
implementation derived from the first reference, in which terms
smaller than 2 microarcseconds have been omitted.
References
----------
.. [R1] Capitaine, N., Wallace, P.T., and McCarthy, D.D. (2003).
Astron. & Astrophys. 406, p. 1135-1149. Table 3.
.. [R2] IERS Conventions (2010), Chapter 5, p. 60, Table 5.2e.
(Table 5.2e presented in the printed publication is a truncated
series. The full series, which is used in NOVAS, is available
on the IERS Conventions Center website in file tab5.2e.txt.)
ftp://tai.bipm.org/iers/conv2010/chapter5/
- ephemeris(jd, ss_body, origin=1, accuracy=0)
- Retrieves the position and velocity of a solar system body from
a fundamental ephemeris.
Parameters
----------
jd : tuple of floats, of length 2
TDB Julian date split into two parts, where the sum jd[0] +
jd[1] is the TDB Julian date.
ss_body : Object
Instance of Object type object containing the designation of
the body of interest.
origin : {0, 1}, optional
= 0 ... solar system barycenter
= 1 ... center of mass of the Sun (default)
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position and
velocity.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(pos, vel) : tuple of tuples of three floats
pos is position vector of the body at 'jd_tdb'; equatorial
rectangular coordinates in AU referred to the ICRS.
vel is the velocity vector of the body at 'jd_tdb'; equatorial
rectangular system referred the ICRS, in AU/Day.
- equ2ecl(jd_tt, ra, dec, coord_sys=2, accuracy=0)
- Convert equatorial position to ecliptic position
Parameters
----------
jd_tt : float
TT Julian date of equator, equinox, and ecliptic used for
coordinates.
ra : float
Right ascension in hours, referred to specified equator and
equinox of date.
dec : float
Declination in degrees, referred to specified equator and
equinox of date.
coord_sys : {0, 1, 2}, optional
= 0 ... mean equator and equinox of date
= 1 ... true equator and equinox of date
= 2 ... ICRS (ecliptic is always the mean plane) (default)
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(elon, elat) : tuple of floats
Ecliptic (longitude, latitude) in degrees, referred to specified
ecliptic and equinox of date.
Notes
-----
.. [N1] To convert ICRS RA and dec to ecliptic coordinates (mean
ecliptic and equinox of J2000.0), set 'system' = 2; the value
of 'jd_tt' can be set to anything, since J2000.0 is assumed.
Except for the input to this case, all input coordinates are
dynamical.
- equ2ecl_vec(jd_tt, position, coord_sys=2, accuracy=0)
- Convert an equatorial position vector to an ecliptic position
vector.
Parameters
----------
jd_tt : float
TT Julian date of equator, equinox, and ecliptic used for
coordinates.
position : tuple of floats, of length 3
Position vector, referred to specified equator and equinox of
date.
coord_sys : {0, 1, 2}, optional
= 0 ... mean equator and equinox of date
= 1 ... true equator and equinox of date
= 2 ... ICRS (ecliptic is always the mean plane) (default)
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
position : tuple of floats, of length 3
Position vector, referred to specified ecliptic and equinox of
date.
Notes
-----
.. [N1] To convert an ICRS vector to an ecliptic vector (mean
ecliptic and equinox of J2000.0 only), set 'system' = 2; the
value of 'jd_tt' can be set to anything, since J2000.0 is
assumed. Except for the input to this case, all vectors are
assumed to be with respect to a dynamical system.
- equ2gal(rai, deci)
- Convert ICRS equatorial position to galactic position
Parameters
----------
ra : float
ICRS right ascension in hours.
dec : float
ICRS declination in degrees.
Returns
-------
(glon, glat) : tuple of floats
Galactic (longitude, latitude) in degrees.
References
----------
.. [R1] Hipparcos and Tycho Catalogues, Vol. 1, Section 1.5.3.
- equ2hor(jd_ut1, delta_t, xp, yp, location, ra, dec, ref_option=0, accuracy=0)
- This function transforms topocentric right ascension and declination
to zenith distance and azimuth. It uses a method that properly
accounts for polar motion, which is significant at the sub-arcsecond
level. This function can also adjust coordinates for atmospheric
refraction.
Parameters
----------
jd_ut1 : float
UT1 Julian date.
delta_t : float
Difference TT-UT1 at 'jd_ut1', in seconds.
xp : float
Conventionally-defined x coordinate of celestial intermediate
pole with respect to ITRS reference pole, in arcseconds.
yp : float
Conventionally-defined y coordinate of celestial intermediate
pole with respect to ITRS reference pole, in arcseconds.
location : OnSurface
Instance of OnSurface type object containing observer's
location.
ra : float
Topocentric right ascension of object of interest, in hours,
referred to true equator and equinox of date.
dec : float
Topocentric declination of object of interest, in hours,
referred to true equator and equinox of date.
ref_option : {0, 1, 2}, optional
= 0 ... no refraction (default)
= 1 ... include refraction, using 'standard' atmospheric
conditions.
= 2 ... include refraction, using atmospheric parameters
input in the 'location' object.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(zd, az) : tuple of floats
Topocentric (zenith distance, azimuth) in degrees. Zenith
distance is affected by refraction if 'ref_option', is non-zero.
Azimuth is measured east from north.
(rar, decr) : tuple of floats
Topocentric (right ascension in hours, declination in degrees)
of object of interest, referred to true equator and equinox of
date, affected by refraction if 'ref_option' is non-zero.
Notes
-----
.. [N1] 'xp' and 'yp' can be set to zero if sub-arcsecond accuracy
is not needed. 'ra' and 'dec' can be obtained from functions
'topo_star' or 'topo_planet'.
.. [N2] The directions 'zd'= 0 (zenith) and 'az'= 0 (North) are here
considered fixed in the terrestrial system. Specifically, the
zenith is along the geodetic normal, and North is toward
the ITRS pole.
.. [N3] If 'ref_option'= 0, then 'rar'='ra' and 'decr'='dec'.
References
----------
.. [R1] Kaplan, G. (2008). USNO/AA Technical Note of 28 Apr 2008,
"Refraction as a Vector."
- era(jd_ut1_high, jd_ut1_low=0.0)
- Compute the Earth Rotation Angle (theta) for a given UT1 Julian
date. The expression used is taken from the note to IAU Resolution
B1.8 of 2000[R1]_.
Parameters
----------
jd_ut1_high : float
High-order part of UT1 Julian date.
jd_ut1_low : float (optional)
Low-order part of UT1 Julian date.
Returns
-------
theta : float
The Earth Rotation Angle in degrees.
Notes
-----
.. [N1] The algorithm used here is equivalent to the canonical
theta = 0.7790572732640 + 1.00273781191135448 * t,
where t is the time in days from J2000 (t = jd_ut1_high +
jd_ut1_low - T0), but it avoids many two-PI 'wraps' that
decrease precision (adopted from SOFA Fortran routine iau_era00;
see also expression at top of page 35 of IERS Conventions
(1996)).
References
----------
.. [R1] IAU Resolution B1.8, adopted at the 2000 IAU General
Assembly, Manchester, UK.
.. [R2] Kaplan, G. (2005), US Naval Observatory Circular 179.
- frame_tie(position, direction=0)
- Transform a vector from the dynamical reference system to the
International Celestial Reference System (ICRS), or vice versa. The
dynamical reference system is based on the dynamical mean equator
and equinox of J2000.0. The ICRS is based on the space-fixed ICRS
axes defined by the radio catalog positions of several hundred
extragalactic objects.
Parameters
----------
position : tuple of floats, of length 3
Position vector in equatorial rectangular coordinates.
direction : {0, -1}, optional
= 0 ... ICRS to dynamical (default)
= -1 ... dynamical to ICRS
Returns
-------
position : tuple of floats, of length 3
Position vector in equatorial rectangular coordinates.
Notes
-----
.. [N1] For geocentric coordinates, the same transformation is used
between the dynamical reference system and the GCRS.
References
----------
.. [R1] Hilton, J. and Hohenkerk, C. (2004), Astronomy and
Astrophysics 413, 765-770, eq. (6) and (8).
.. [R2] IERS (2003) Conventions, Chapter 5.
- fund_args(time)
- To compute the fundamental arguments (mean elements) of the Sun and
Moon.
Parameters
----------
time : float
TDB time in Julian centuries since J2000.0
Returns
-------
(l, l', F, D, omega) : tuple
l = mean anomaly of the Moon
l' = mean anomaly of the Sun
F = mean argument of the latitude of the Moon
D = mean elongation of the Moon from the Sun
omega = mean longitude of the Moon's ascending node;
from Simon section 3.4(b.3),
precession = 5028.8200 arcsec/cy
References
----------
.. [R1] Simon et al. (1994) Astronomy and Astrophysics 282, 663-683,
esp. Sections 3.4-3.5.
- gcrs2equ(jd_tt, rag, decg, coord_sys=1, accuracy=0)
- Convert GCRS right ascension and declination to coordinates with
respect to the equator of date (mean or true). For coordinates with
respect to the true equator of date, the origin of right ascension
can be either the true equinox or the celestial intermediate origin
(CIO).
Parameters
----------
jd_tt : float
TT Julian date of equator to be used for output coordinates.
rag : float
GCRS right ascension in hours.
decg : float
GCRS declination in degrees.
coord_sys : {0, 1, 2}, optional
= 0 ... mean equator and equinox of date
= 1 ... true equator and equinox of date (default)
= 2 ... true equator and CIO of date
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec) : tuple of floats
(Right ascension in hours, declination in degrees), referred to
specified equator (and right ascension origin, for 'ra') of
date.
Notes
-----
.. [N1] Set input value of 'accuracy' equal to any short int if
'coord_sys' equals 0 or 1. It is not used in these cases.
.. [N2] This function only supports the CIO-based method.
- geo_posvel(jd_tt, delta_t, observer, accuracy=0)
- Compute the geocentric position and velocity of an observer on the
surface of the earth or on a near-earth spacecraft. The final
vectors are expressed in the GCRS.
Parameters
----------
jd_tt : float
TT Julian date.
delta_t : float
Value of Delta T (=TT-UT1) at 'date'.
observer : Observer
Instance of Observer type object specifying the location of
the observer.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position and
velocity.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(position, velocity) : tuple of tuple of floats, of length 3
Position vector of observer, with respect to origin at
geocenter, referred to GCRS axes, components in AU and AU/day,
respectively.
- get_errno(...)
- grav_def(jd_tdb, pos_obj, pos_obs, location, accuracy=0)
- Compute the total gravitational deflection of light for the observed
object due to the major gravitating bodies in the solar system. This
function valid for an observed body within the solar system as well
as for a star.
Parameters
----------
jd_tdb : float
TDB Julian date of observation.
pos_obj : tuple of floats, of length 3
Position vector of observed object, with respect to origin at
observer (or the geocenter), referred to ICRS axes, components
in AU.
pos_obs : tuple of floats, of length 3
Position vector of observer (or the geocenter), with respect to
origin at solar system barycenter, referred to ICRS axes,
components in AU.
location : {0, 1}, optional
Code for location of observer, determining whether the
gravitational deflection due to the earth itself is applied.
= 0 ... No earth deflection (normally means observer is at
geocenter)
= 1 ... Add in earth deflection (normally means observer is
on or above surface of earth, including earth orbit)
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
positon : tuple of floats, of length 3
Position vector of observed object, with respect to origin at
observer (or the geocenter), referred to ICRS axes, corrected
for gravitational deflection, components in AU.
Notes
-----
.. [N1] If 'accuracy' is set to zero (full accuracy), three bodies
(Sun, Jupiter, and Saturn) are used in the calculation. If
the reduced-accuracy option is set, only the Sun is used in the
calculation. In both cases, if the observer is not at the
geocenter, the deflection due to the Earth is included.
.. [N2] The number of bodies used at full and reduced accuracy can
be set by making a change to the code in this function as indicated
in the comments.
References
----------
.. [R1] Klioner, S. (2003), Astronomical Journal 125, 1580-1597,
Section 6.
- grav_vec(pos_obj, pos_obs, pos_body, rmass)
- Correct the position vector for the deflection of light in the
gravitational field of an arbitrary body. This function valid for an
observed body within the solar system as well as for a star.
Parameters
----------
pos_obj : tuple of floats, of length 3
Position vector of observed object, with respect to origin at
observer (or the geocenter), components in AU.
pos_obs : tuple of floats, of length 3
Position vector of observer (or the geocenter), with respect
to origin at solar system barycenter, components in AU.
pos_body : tuple of floats, of length 3
Position vector of gravitating body, with respect to origin
at solar system barycenter, components in AU.
rmass : float
Reciprocal mass of gravitating body in solar mass units,
that is, Sun mass / body mass.
Returns
-------
position : tuple of floats, of length 3
Position vector of observed object, with respect to origin at
observer (or the geocenter), corrected for gravitational
deflection, components in AU.
References
----------
.. [R1] Murray, C.A. (1981) Mon. Notices Royal Ast. Society 195,
639-648.
.. [R2] See also formulae in Section B of the Astronomical Almanac,
or Kaplan, G. et al. (1989) Astronomical Journal 97, 1197-1210,
section iii f.
- ira_equinox(jd_tdb, equinox, accuracy=0)
- To compute the intermediate right ascension of the equinox at
the input Julian date, using an analytical expression for the
accumulated precession in right ascension. For the true equinox,
the result is the equation of the origins.
Parameters
----------
jd_tdb : float
TDB Julian day.
equinox : {0, 1}, optional
= 0 ... mean equinox
= 1 ... true equinox
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
ira_eq : float
Intermediate right ascension of the equinox, in hours (+ or -).
If 'equinox' = 1 (i.e. true equinox), then the returned value is
the equation of the origins.
References
----------
.. [R1] Capitaine, N. et al. (2003), Astronomy and Astrophysics 412,
567-586, eq. (42).
- julian_date(year, month, day, hour=0.0)
- This function will compute the Julian date for a given calendar
date (year, month, day, hour).
Parameters
----------
year : integer
Year.
month : integer
Month number.
day : integer
Day-of-month.
hour : float, optional
Hour-of-day.
Returns
-------
jd : float
Julian day.
Notes
-----
.. [N1] This function makes no checks for a valid input calendar
date.
.. [N2] Input calendar date must be Gregorian.
.. [N3] Input time value can be based on any UT-like time scale
(UTC, UT1, TT, etc.) -- output Julian date will have the same
basis.
References
----------
.. [R1] Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11,
No. 10, October 1968, p. 657.
- light_time(jd_tdb, ss_object, pos_obs, estimate=0.0, accuracy=0)
- Compute the geocentric position of a solar system body, as antedated
for light-time.
Parameters
----------
jd_tdb : float
TDB Julian date of observation.
ss_object : Object
Instance of Object type object containing the designation for
the solar system body.
pos_obs : tuple of floats, of length 3
Position vector of observer (or the geocenter), with respect to
origin at solar system barycenter, referred to ICRS axes,
components in AU.
estimate : float (optional)
First approximation to light-time, in days (can be set to 0.0
if unknown).
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position and
time.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(position, time) : tuple of tuple of floats, of length 3, and float
Position vector of body, with respect to origin at observer (or
the geocenter), referred to ICRS axes, components in AU and
final light-time, in days.
- limb_angle(pos_obj, pos_obs)
- Compute the angle of an object above or below the Earth's limb
(horizon). The geometric limb is computed, assuming the Earth to be
an airless sphere (no refraction or oblateness is included). The
observer can be on or above the Earth. For an observer on the
surface of the Earth, this function returns the approximate
unrefracted altitude.
Parameters
----------
pos_obj : tuple of floats, of length 3
Position vector of observed object, with respect to origin at
geocenter, components in AU.
pos_obs : tuple of floats, of length 3
Position vector of observer, with respect to origin at
geocenter, components in AU.
Returns
-------
(limb_angle, nadir_angle) : tuple of floats
Angle of observed object above (+) or below (-) limb in degrees
and nadir angle of observed object as a fraction of apparent
radius of limb where: < 1.0, below the limb; = 1.0, on the limb;
> 1.0, above the limb
- local_planet(jd_tt, delta_t, ss_body, position, accuracy=0)
- Computes the local place of a solar system body.
Parameters
----------
jd_tt : float
TT Julian date for local place.
delta_t : float
Difference TT-UT1 at 'date', in seconds of time.
ss_body : Object
Instance of Object type object containing the body designation
for solar system body.
position : OnSurface
Instance of OnSurface type object specifying the position of
the observer.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec, dis) : tuple of floats
Local (right ascension in hours, declination in degrees, ...),
referred to the 'local GCRS', and true (..., ..., distance in
AU) from Earth to solar system body at 'jd_tt'.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C72-C72.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- local_star(jd_tt, delta_t, star, position, accuracy=0)
- Computes the local place of a star at date 'date', given its
catalog mean place, proper motion, parallax, and radial velocity.
Parameters
----------
jd_tt : float
TT Julian date for local place.
delta_t : float
Difference TT-UT1 at 'date', in seconds of time.
star : CatEntry
Instance of CatEntry type object containing catalog data for
the object in the ICRS.
position : OnSurface
Instance of OnSurface type object specifying the position of
the observer.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec) : tuple of floats
Local (right ascension in hours, declination in degrees),
referred to the 'local GCRS'.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C65.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- make_cat_entry(star_name, catalog, star_num, ra, dec, pm_ra, pm_dec, parallax, rad_vel)
- Create an instance of CatEntry containing catalog data for a star or
"star-like" object.
Parameters
----------
star_name : string
Object name. Max length determined by SIZE_OF_OBJ_NAME defined
in ``novas.h``; defaults to 50.
catalog : string
Catalog identifier (e.g. HIP = Hipparcos, TY2 = Tycho-2). Max
length determined by SIZE_OF_CAT_NAME defined in ``novas.h``;
defaults to 3.
star_num : integer
Object number in the catalog.
ra : float
Right ascension of the object (hours).
dec : float
Declination of the object (degrees).
pm_ra : float (optional)
Proper motion in right ascension (milliarcseconds/year).
pm_dec : float (optional)
Proper motion in declination (milliarcseconds/year).
parallax : float (optional)
Parallax (milliarcseconds).
rad_vel : float (optional)
Radial velocity (kilometers/second).
Returns
-------
star : CatEntry
Instance of CatEntry type object containing the input data.
Notes
-----
.. [N1] This function is equivalent to calling the object with
arguments,e.g., CatEntry(star_name, catalog, star_num, ...);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_in_space(position, velocity)
- Makes an instance of InSpace, specifying the position and velocity
of an observer situated on a near-Earth spacecraft.
Parameters
----------
position : tuple of floats, of length 3
Geocentric position vector (x, y, z) in km.
velocity : tuple of floats, of length 3
Geocentric velocity vector (x_dot, y_dot, z_dot) in km/s.
Returns
-------
object : InSpace
Instance of InSpace type object containing the position and
velocity of an observer situated on a near-Earth spacecraft.
Notes
-----
.. [N1] Both input vector tuples are with respect to true equator
and equinox of date.
.. [N2] This function is equivalent to calling the object with
arguments, e.g., InSpace(sc_pos, sc_vel);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_object(type, number, name, star_data)
- Makes an instance of Object--specifying a celestial object--based on
the input parameters.
Parameters
----------
type : integer
Type of object
= 0 ... major planet, Sun, or Moon
= 1 ... minor planet
= 2 ... object located outside the solar system (i.e. star,
galaxy, nebula, etc.)
number : integer
For 'type' = 0: Mercury = 1, ..., Pluto = 9, Sun = 10, Moon = 11
For 'type' = 1: minor planet number
For 'type' = 2: set to 0 (zero)
name : string
Name of the object. Max length determined by SIZE_OF_OBJ_NAME
defined in ``novas.h``; defaults to 50.
star_data : CatEntry (or None if 'type' = 0 or 'type' = 1; see [N1]_)
Instance of CatEntry type object containing basic astrometric
data for any celestial object located outside the solar system;
the catalog data for a star.
Returns
-------
object : Object
Instance of Object type object containing the object definition.
Notes
-----
.. [N1] If 'type' = 0 or 'type' = 1, None may be given for
'star_data'; in this case, a dummy star CatEntry will be
constructed for 'star_data' automatically.
.. [N2] This function is equivalent to calling the object with
arguments, e.g., Object(type, number, name, star_data);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_observer(location, obs_surface, obs_space)
- Makes an instance of Observer, specifying the location of the
observer.
Parameters
----------
location : {0, 1, 2}
= 0 ... observer at geocenter
= 1 ... observer on surface of Earth
= 2 ... observer on near-earth spacecraft
obs_surface : OnSurface (or None if 'location' != 1; see [N1]_)
Instance of OnSurface type object containing data for an
observer's location on the surface of the Earth; used when
'location' = 1.
obs_space : InSpace (or None if 'location' != 2; see [N1]_)
Instance of InSpace type object containing data for an
observer's location on a near-earth spacecraft; used when
'location' = 2.
Returns
-------
observer : Observer
Instance of Observer type object specifying the location of
the observer.
Notes
-----
.. [N1] If 'location' = 0 or 'location' = 2, None may be given for
'obs_surface'; likewise, if 'location' = 0 or 'location' = 1,
None may be given for 'in_space'. This also means that if
'location' = 0, None may be given for both 'obs_surface' and
'in_space'.
.. [N2] This function is equivalent to calling the object with
arguments, e.g., Observer(obs_surface, in_space, location);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_observer_at_geocenter()
- Makes an instance of Observer, specifying an observer at the
geocenter.
Parameters
----------
None
Returns
-------
observer : Observer
Instance of Observer type object specifying the location of
the observer at the geocenter.
Notes
-----
.. [N1] This function is equivalent to calling the object with
arguments, e.g., Observer(0, None, None);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_observer_in_space(position, velocity)
- Makes an instance of Observer, specifying the position and velocity
of observer situated on a near-Earth spacecraft.
Parameters
----------
position : tuple of floats, of length 3
Geocentric position vector (x, y, z) in km.
velocity : tuple of floats, of length 3
Geocentric velocity vector (x_dot, y_dot, z_dot) in km/s.
Returns
-------
observer : Observer
Instance of Observer type object containing the position and
velocity of an observer situated on a near-Earth spacecraft.
Notes
-----
.. [N1] Both input vector tuples are with respect to true equator
and equinox of date.
.. [N2] This function is equivalent to calling the object with
arguments, e.g., Observer(2, None, obs_space);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_observer_on_surface(latitude, longitude, height, temperature, pressure)
- Makes an instance of Observer, specifying the location of and
weather for an observer on the surface of the Earth.
Parameters
----------
latitude : float
Geodetic (ITRS) latitude in degrees; north positive.
longitude : float
Geodetic (ITRS) longitude in degrees; east positive.
height : float
Height of the observer (meters).
temperature : float
Temperature (degrees Celcius).
pressure : float
Atmospheric pressure (millibars).
Returns
-------
observer : Observer
Instance of Observer type object containing the location of and
weather for an observer on the surface of the Earth.
Notes
-----
.. [N1] This function is equivalent to calling the object with
arguments, e.g., Observer(1, obs_surface, None);
this function exists for the purpose of direct compatibility
with NOVAS C.
- make_on_surface(latitude, longitude, height, temperature, pressure)
- Makes an instance of OnSurface, specifying the location of and
weather for an observer on the surface of the Earth.
Parameters
----------
latitude : float
Geodetic (ITRS) latitude in degrees; north positive.
longitude : float
Geodetic (ITRS) longitude in degrees; east positive.
height : float
Height of the observer (meters).
temperature : float
Temperature (degrees Celcius).
pressure : float
Atmospheric pressure (millibars).
Returns
-------
location : OnSurface
Instance of OnSurface type object containing the location of and
weather for an observer on the surface of the Earth.
Notes
-----
.. [N1] This function is equivalent to calling the object with
arguments, e.g., OnSurface(latitude, longitude, height,
temperature, pressure); this function exists for the purpose of
direct compatibility with NOVAS C.
- mean_obliq(jd_tdb)
- Return the mean obliquity of the ecliptic.
Parameters
----------
jd_tdb : float
TDB Julian date.
Returns
-------
epsilon : float
Mean obliquity of the ecliptic in arcseconds.
References
----------
.. [R1] Capitaine et al. (2003), Astronomy and Astrophysics 412,
567-586.
- mean_star(jd_tt, ra, dec, accuracy=0)
- Computes the ICRS position of a star, given its apparent place
at 'date'. Proper motion, parallax, and radial velocity are assumed
to be zero.
Parameters
----------
jd_tt : float
TT Julian date of apparent place.
ra : float
Apparent right ascension in hours, referred to true equator and
equinox of date.
dec : float
Apparent declination in degrees, referred to true equator and
equinox of date.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ira, idec) : tuple of floats
ICRS (right ascension in hours, declination in degrees).
References
----------
.. [R1] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- norm_ang(angle)
- Normalize angle into the range 0 <= angle < (2 * pi).
Parameters
----------
angle : float
Input angle in radians.
Returns
-------
norm_angle : float
The input angle, normalized as described above, in radians.
- nutation(jd_tdb, position, direction=0, accuracy=0)
- Nutates equatorial rectangular coordinates from mean equator and
equinox of epoch to true equator and equinox of epoch. Inverse
transformation may be applied by setting flag 'direction'.
Parameters
----------
jd_tdb : float
TDB Julian date of epoch.
position : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to mean equator and equinox of epoch.
direction : {0, 1}, optional
= 0 ... transform from mean to true (default)
= 1 ... transform from true to mean
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
position : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to true equator and equinox of epoch.
References
----------
.. [R1] Explanatory Supplement To The Astronomical Almanac, pp.
114-115.
- nutation_angles(time, accuracy=0)
- This function returns the values for nutation in longitude and
nutation in obliquity for a given TDB Julian date. The nutation
model selected depends upon the input value of 'accuracy'. See
notes below for important details.
Parameters
----------
time : float
TDB time in Julian centuries since J2000.0
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output nutation.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(dpsi, deps) : tuple of floats
Nutation in (longitude, obliquity) in arcseconds.
Notes
-----
.. [N1] This function selects the nutation model depending first
upon the input value of 'accuracy'. If 'accuracy' = 0 (full
accuracy), the IAU 2000A nutation model is used. If 'accuracy'
= 1 (reduced accuracy, the model used depends upon the value of
local variable 'low_acc_choice', which is set in 'novas.c'.
.. [N2] If local variable 'low_acc_choice' = 1 (the default), a
specially truncated version of IAU 2000A, called 'NU2000K' is
used. If 'low_acc_choice' = 2, the IAU 2000B nutation model is
used.
.. [N3] See the docstrings of the nutation functions in
novas.nutation for details concerning the models.
References
----------
.. [R1] Kaplan, G. (2005), US Naval Observatory Circular 179.
- place(jd_tt, delta_t, cel_object, location, coord_sys, accuracy=0)
- This function computes the apparent direction of a star or solar
system body at a specified time and in a specified coordinate
system.
Parameters
----------
jd_tt : float
TT Julian date for place.
delta_t : float
Difference TT-UT1 at 'jd_tt', in seconds of time.
cel_object : Object
Instance of Object type object specifying the celestial object
of interest.
location : Observer
Instance of Observer type object specifying the location of
the observer.
coord_sys : {0, 1, 2, 3}, optional
Code specifying coordinate system of the output position.
= 0 ... GCRS or "local GCRS"
= 1 ... true equator and equinox of date
= 2 ... true equator and CIO of date
= 3 ... astrometric coordinates, i.e., without light
deflection of aberration
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
output : SkyPos
Instance of SkyPos type object specifying object's place on the
sky at time 'jd_tt', with respect to the specified output
coordinate system.
Notes
-----
.. [N1] Values of 'location.where' and 'coord_sys' dictate the
various standard kinds of place:
location.where = 0 and system = 1: apparent place
location.where = 1 and system = 1: topocentric place
location.where = 0 and system = 0: virtual place
location.where = 1 and system = 0: local place
location.where = 0 and system = 3: astrometric place
location.where = 1 and system = 3: topocentric astrometric
place
.. [N2] Input value of 'delta_t' is used only when 'location.where'
equals 1 or 2 (observer is on surface of Earth or in a
near-Earth satellite).
References
----------
.. [R1] Kaplan, G. et al. (1989), Astronomical Journal 97,
1197-1210.
.. [R2] Klioner, S. (2003), Astronomical Journal 125, 1580-1597.
- pointer(...)
- precession(jd_tdb1, position, jd_tdb2)
- Precesses equatorial rectangular coordinates from one epoch to
another. One of the two epochs must be J2000.0. The coordinates
are referred to the mean dynamical equator and equinox of the two
respective epochs.
Parameters
----------
jd_tdb1 : float
TDB Julian date of first epoch. See Note [N1]_ below.
position : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to mean dynamical equator and equinox of first epoch.
jd_tdb2 : float
TDB Julian date of second epoch. See Note [N1]_ below.
Returns
-------
position : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to mean dynamical equator and equinox of second epoch.
Notes
-----
.. [N1] Either 'date' or 'newdate' must be 2451545.0 (J2000.0) TDB.
References
----------
.. [R1] Explanatory Supplement To The Astronomical Almanac, pp.
103-104.
.. [R2] Capitaine, N. et al. (2003), Astronomy And Astrophysics 412,
pp. 567-586.
.. [R3] Hilton, J. L. et al. (2006), IAU WG report, Celest. Mech.,
94, pp. 351-367.
- proper_motion(jd_tdb1, position, velocity, jd_tdb2)
- Applies proper motion, including foreshortening effects, to a star's
position.
Parameters
----------
jd_tdb1 : float
TDB Julian date of first epoch.
position : tuple of floats, of length 3
Position vector at first epoch.
velocity : tuple of floats, of length 3
Velocity vector at first epoch.
jd_tdb2 : float
TDB Julian date of second epoch.
Returns
-------
position : tuple of floats, of length 3
Position vector at second epoch.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C16.
- rad_vel(cel_object, pos, vel, vel_obs, distance_geo, distance_sun, distance_obj_sun)
- Predicts the radial velocity of the observed object as it would be
measured by spectroscopic means. Radial velocity is here defined as
the radial velocity measure (z) times the speed of light. For a
solar system body, it applies to a fictitious emitter at the center
of the observed object, assumed massless (no gravitational red
shift), and does not in general apply to reflected light. For stars,
it includes all effects, such as gravitational red shift, contained
in the catalog barycentric radial velocity measure, a scalar derived
from spectroscopy. Nearby stars with a known kinematic velocity
vector (obtained independently of spectroscopy) can be treated like
solar system objects.
Parameters
----------
cel_object : Object
Specifies the celestial object of interest.
pos : tuple of floats, of length 3
Geometric position vector of object with respect to observer,
corrected for light-time, in AU.
vel : tuple of floats, of length 3
Velocity vector of object with respect to solar system
barycenter, in AU/day.
vel_obs : tuple of floats, of length 3
Velocity vector of observer with respect to solar system
barycenter, in AU/day.
distance_geo : float
Distance from observer to geocenter, in AU.
distance_sun : float
Distance from observer to Sun, in AU.
distance_obj_sun : float
Distance from object to Sun, in AU.
Returns
-------
rv : float
The observed radial velocity measure times the speed of light,
in kilometers/second.
Notes
-----
.. [N1] All the input arguments are BCRS quantities, expressed
with respect to the ICRS axes. 'vel' and 'vel_obs' are
kinematic velocities - derived from geometry or dynamics, not
spectroscopy.
.. [N2] If the object is outside the solar system, the algorithm
used will be consistent with the IAU definition of stellar
radial velocity, specifically, the barycentric radial velocity
measure, which is derived from spectroscopy. In that case,
the vector 'vel' can be very approximate -- or, for distant
stars or galaxies, zero -- as it will be used only for a small
geometric correction that is proportional to proper motion.
.. [N3] Any of the distances (last three input arguments) can be set
to zero (0.0) if the corresponding general relativistic
gravitational potential term is not to be evaluated. These terms
generally are important only at the meter/second level. If
'distance_geo' and 'distance_sun' are both zero, an average
value will be used for the relativistic term for the observer,
appropriate for an observer on the surface of the Earth.
'distance_sun', if given, is used only for solar system objects.
References
----------
.. [R1] Lindegren & Dravins (2003), Astronomy & Astrophysics 401,
1185-1201.
- radec2vector(ra, dec, distance)
- Converts equatorial spherical coordinates to a vector (equatorial
rectangular coordinates).
Parameters
----------
ra : float
Right ascension in hours.
dec : float
Declination in degrees.
distance : float
Distance in AU.
Returns
-------
position : tuple of floats, of length 3
Position vector, equatorial rectangular coordinates in AU.
- refract(location, zd_obs, atmosphere=1)
- This function computes atmospheric refraction in zenith
distance. This version computes approximate refraction for
optical wavelengths.
Parameters
----------
location : OnSurface
Instance of OnSurface type object containing observer's
location. This structure also contains weather data (optional)
for the observer's location.
zenith : float
Observed zenith distance, in degrees.
atmosphere : {1, 2}, optional
= 1 ... use 'standard' atmospheric conditions (default)
= 2 ... use atmospheric parameters input in the 'location'
object.
Returns
-------
refraction : float
Atmospheric refraction, in degrees.
Notes
-----
.. [N1] This function can be used for planning observations or
telescope pointing, but should not be used for the reduction
of precise observations.
References
----------
.. [R1] Explanatory Supplement to the Astronomical Almanac, p. 144.
.. [R2] Bennett, G. (1982), Journal of Navigation (Royal Institute)
35, pp. 255-259.
- resize(...)
- Resize the memory buffer of a ctypes instance
- set_conversion_mode(...)
- set_conversion_mode(encoding, errors) -> (previous-encoding, previous-errors)
Set the encoding and error handling ctypes uses when converting
between unicode and strings. Returns the previous values.
- set_errno(...)
- sidereal_time(jd_high, jd_low, delta_t, gst_type=1, method=0, accuracy=0)
- Computes the Greenwich sidereal time, either mean or apparent, at
Julian date 'jd_high' + 'jd_low'.
Parameters
----------
jd_high : float
High-order part of UT1 Julian date.
jd_low : float
Low-order part of UT1 Julian date.
delta_t float
Difference TT-UT1 at 'jd_high' + 'jd_low', in seconds of time.
gst_type : {0, 1}, optional
= 0 ... compute Greenwich mean sidereal time
= 1 ... compute Greenwich apparent sidereal time (default)
method : {0, 1}, optional
Selection for method.
= 0 ... CIO-based method (default)
= 1 ... equinox-based method
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output time.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
gst : float
Greenwich (mean or apparent) sidereal time, in hours.
Notes
-----
.. [N1] The Julian date may be split at any point, but for highest
precision, set 'jd_high' to be the integral part of the Julian
date, and set 'jd_low' to be the fractional part.
References
----------
.. [R1] Kaplan, G. (2005), US Naval Observatory Circular 179.
- sizeof(...)
- sizeof(C type) -> integer
sizeof(C instance) -> integer
Return the size in bytes of a C instance
- spin(angle, pos1)
- This function transforms a vector from one coordinate system to
another with same origin and axes rotated about the z-axis.
Parameters
----------
angle : float
Angle of coordinate system rotation, positive counterclockwise
when viewed from +z, in degrees.
position : tuple of floats, of length 3
Position vector.
Returns
-------
position : tuple of floats, of length 3
Position vector expressed in new coordinate system rotated
about z by 'angle'.
- starvectors(star)
- Converts angular quantities for stars to vectors.
Parameters
----------
star : CatEntry
Instance of CatEntry type object containing ICRS catalog data.
Returns
-------
(position, velocity) : tuple of tuple of floats, of length 3
Position and velocity vectors in equatorial rectangular
coordinates. Components are in AU and AU/day.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C16, C113.
- tdb2tt(tdb_jd)
- Computes the Terrestrial Time (TT) or Terrestrial Dynamical Time
(TDT) Julian date corresponding to a Barycentric Dynamical Time
(TDB) Julian date.
Parameters
----------
tdb_jd : float
TDB Julian date.
Returns
-------
(tt_jd, secdiff) : tuple of float
tt_jd = TT Julian date, secdiff = difference 'tdb_jd' - 'tt_jd',
in seconds.
Notes
-----
.. [N1] Expression used in this function is a truncated form of a
longer and more precise series given in the first reference
[R1]_. The result is good to about 10 microseconds.
References
----------
.. [R1] Fairhead, L. & Bretagnon, P. (1990) Astron. & Astrophys.
229, 240.
.. [R2] Kaplan, G. (2005), US Naval Observatory Circular 179.
- ter2cel(jd_ut1_high, jd_ut1_low, delta_t, xp, yp, vec1, method=0, option=0, accuracy=0)
- This function rotates a vector from the terrestrial to the
celestial system. Specifically, it transforms a vector in the
ITRS (rotating earth-fixed system) to the GCRS (a local space-
fixed system) by applying rotations for polar motion, Earth
rotation, nutation, precession, and the dynamical-to-GCRS
frame tie.
Parameters
----------
jd_ut1_high : float
High-order part of UT1 Julian date.
jd_ut1_low : float
Low-order part of UT1 Julian date.
delta_t : float
Value of Delta T (=TT-UT1) at the input UT1 Julian date.
xp : float
Conventionally-defined X coordinate of celestial intermediate
pole with respect to ITRS pole, in arcseconds.
yp : float
Conventionally-defined Y coordinate of celestial intermediate
pole with respect to ITRS pole, in arcseconds.
vec1 : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to ITRS axes (terrestrial system) in the normal case
where 'option' = 0.
method : {0, 1}, optional
Selection for method.
= 0 ... CIO-based method (default)
= 1 ... equinox-based method
option : {0, 1}, optional
Selection for reference axes
= 0 ... The output vector is referred to GCRS axes.
(default)
= 1 ... The output vector is produced with respect to the
equator and equinox of date. See Note [N2]_ below.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
vec2 : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to GCRS axes (celestial system) or with respect to
the equator and equinox of date, depending on 'option'.
Notes
-----
.. [N1] 'xp' = 'yp' = 0 means no polar motion transformation.
.. [N2] The 'option' flag only works for the equinox-based method.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C53-C54.
.. [R2] Kaplan, G. H. (2003), 'Another Look at Non-Rotating
Origins', Proceedings of IAU XXV Joint Discussion 16.
- terra(location, time)
- Computes the position and velocity vectors of a terrestrial observer
with respect to the center of the Earth.
Parameters
----------
location : OnSurface
Instance of OnSurface type object containing observer's
location.
time : float
Local apparent sidereal time at reference meridian in hours.
Returns
-------
(position, velocity) : tuple of tuple of floats, of length 3
Position and velocity vector of observer with respect to center
of Earth in equatorial rectangular coordinates, referred to true
equator and equinox of date. Components in AU and AU/day.
Notes
-----
.. [N1] If reference meridian is Greenwich and st=0, 'pos' is
effectively referred to equator and Greenwich.
.. [N2] This function ignores polar motion, unless the
observer's longitude and latitude have been corrected for it,
and variation in the length of day (angular velocity of earth).
.. [N3] The true equator and equinox of date do not form an
inertial system. Therefore, with respect to an inertial system,
the very small velocity component (several meters/day) due to
the precession and nutation of the Earth's axis is not accounted
for here.
- topo_planet(jd_tt, delta_t, ss_body, position, accuracy=0)
- Computes the topocentric place of a solar system body.
Parameters
----------
jd_tt : float
TT Julian date for topocentric place.
delta_t : float
Difference TT-UT1 at 'date', in seconds of time.
ss_body : Object
Instance of Object type object containing the body designation
for solar system body.
position : OnSurface
Instance of OnSurface type object specifying the position of
the observer.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec, dis) : tuple of floats
Topocentric (right ascension in hours, declination in degrees,
...), referred to true equator and equinox of date, and true
(..., ..., distance in AU) from Earth to solar system body at
'jd_tt'.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C68-C69.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- topo_star(jd_tt, delta_t, star, position, accuracy=0)
- Computes the topocentric place of a star at 'date', given its
catalog mean place, proper motion, parallax, and radial velocity.
Parameters
----------
jd_tt : float
TT Julian date for topocentric place.
delta_t : float
Difference TT-UT1 at 'date', in seconds of time.
star : CatEntry
Instance of CatEntry type object containing catalog data for
the object in the ICRS.
position : OnSurface
Instance of OnSurface type object specifying the position of
the observer.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec) : tuple of floats
Topocentric (right ascension in hours, declination in degrees),
referred to true equator and equinox of date 'jd_tt'.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C62-C63.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- transform_cat(option, date_incat, incat, date_newcat, newcat_id)
- To transform a star's catalog quantities for a change of epoch
and/or equator and equinox. Also used to rotate catalog
quantities on the dynamical equator and equinox of J2000.0 to the
ICRS or vice versa.
Parameters
----------
option : {1, 2, 3, 4, 5}
Transformation option
= 1 ... change epoch; same equator and equinox
= 2 ... change equator and equinox; same epoch
= 3 ... change equator and equinox and epoch
= 4 ... change equator and equinox J2000.0 to ICRS
= 5 ... change ICRS to equator and equinox of J2000.0
date_incat : float
TT Julian date, or year, of input catalog data.
incat : CatEntry
Instance of CatEntry type object containing an entry from the
input catalog, with units as given in the type definition.
date_newcat : float
TT Julian date, or year, of transformed catalog data.
newcat_id : string
Abbreviated name of the transformed catalog. Max length
determined by SIZE_OF_CAT_NAME defined in ``novas.h``; defaults
to 3.
Returns
-------
newcat : CatEntry
Instance of CatEntry type object containing the transformed
catalog entry, with units as given in the type definition.
Notes
-----
.. [N1] 'date_incat' and 'date_newcat' may be specified either as a
Julian date (e.g., 2433282.5) or a Julian year and fraction
(e.g., 1950.0). Values less than 10000 are assumed to be years.
For 'option' = 2 or 'option' = 3, either 'date_incat' or
'date_newcat' must be 2451545.0 or 2000.0 (J2000.0). For
'option' = 4 and 'option' = 5, 'date_incat' and 'date_newcat'
are ignored.
.. [N2] 'option' = 1 updates the star's data to account for the
star's space motion between the first and second dates, within a
fixed reference frame.
'option' = 2 applies a rotation of the reference frame
corresponding to precession between the first and second dates,
but leaves the star fixed in space.
'option' = 3 provides both transformations.
'option' = 4 and 'option' = 5 provide a a fixed rotation
about very small angles (<0.1 arcsecond) to take data from the
dynamical system of J2000.0 to the ICRS ('option' = 4) or vice
versa ('option' = 5).
.. [N3] For 'option' = 1, input data can be in any fixed reference
system. for 'option' = 2 or 'option' = 3, this function assumes
the input data is in the dynamical system and produces output in
the dynamical system. for 'option' = 4, the input data must be
on the dynamical equator and equinox of J2000.0. for
'option' = 5, the input data must be in the ICRS.
.. [N4] This function cannot be properly used to bring data from
old star catalogs into the modern system, because old catalogs
were compiled using a set of constants that are
incompatible with modern values. In particular, it should not
be used for catalogs whose positions and proper motions were
derived by assuming a precession constant significantly
different from the value implicit in function 'precession'.
- transform_hip(hipparcos)
- To convert Hipparcos catalog data at epoch J1991.25 to epoch
J2000.0, for use within NOVAS. To be used only for Hipparcos or
Tycho stars with linear space motion. Both input and output data
is in the ICRS.
Parameters
----------
hipparcos : CatEntry
Instance of CatEntry type object containing an entry from
the Hipparcos catalog, at epoch J1991.25, with all members
having Hipparcos catalog units. See Note [N1]_ below.
Returns
-------
hip_2000 : CatEntry
Instance of CatEntry type object containing the transformed
input entry, at epoch J2000.0. See Note [N2]_ below.
Notes
-----
.. [N1] Input (Hipparcos catalog) epoch and units:
Epoch: J1991.25
Right ascension (RA): degrees
Declination (Dec): degrees
Proper motion in RA: milliarcseconds per year
Proper motion in Dec: milliarcseconds per year
Parallax: milliarcseconds
Radial velocity: kilometers per second (not in catalog)
.. [N2] Output (modified Hipparcos) epoch and units:
Epoch: J2000.0
Right ascension: hours
Declination: degrees
Proper motion in RA: milliarcseconds per year
Proper motion in Dec: milliarcseconds per year
Parallax: milliarcseconds
Radial velocity: kilometers per second
- vector2radec(position)
- Converts an vector in equatorial rectangular coordinates to
equatorial spherical coordinates.
Parameters
----------
position : tuple of floats, of length 3
Position vector, equatorial rectangular coordinates.
Returns
-------
(rightascension, declination) : tuple of floats
(Right ascension in hours, declination in degrees)
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C38-C39.
- virtual_planet(jd_tt, ss_body, accuracy=0)
- Compute the virtual place of a planet or other solar system body.
Parameters
----------
jd_tt : float
TT Julian date for virtual place.
ss_body : Object
Instance of Object type object containing the body designation
for the solar system body.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec, dis) : tuple of floats
Virtual (right ascension in hours, declination in degrees, ...),
referred to the GCRS, and true (..., ..., distance in AU)
from Earth to solar system body.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C70.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- virtual_star(jd_tt, star, accuracy=0)
- Computes the virtual place of a star at 'date', given its catalog
mean place, proper motion, parallax, and radial velocity.
Parameters
----------
jd_tt : float
TT Julian date for virtual place.
star : CatEntry
Instance of CatEntry type object containing catalog data for
the object in the ICRS.
accuracy : {0, 1}, optional
Code specifying the relative accuracy of the output position.
= 0 ... full accuracy (default)
= 1 ... reduced accuracy
Returns
-------
(ra, dec) : tuple of floats
Virtual (right ascension in hours, declination in degrees),
referred to the GCRS.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C64.
.. [R2] Explanatory Supplement to the Astronomical Almanac (1992),
Chapter 3.
- wobble(tjd, x, y, position, direction=0)
- Corrects a vector in the ICRS (rotating Earth-fixed system) for
polar motion, and also corrects the longitude origin (by a tiny
amount) to the Terrestrial Intermediate Origin (TIO). The ICRS
vector is thereby transformed to the system based on the true
(rotational) equator and TIO. Since the true equator is the plane
orthogonal to the direction of the Celestial Intermediate Pole
(CIP), the components of the output vector are referred to Z and X
axes toward the CIP and TIO, respectively.
Parameters
----------
tjd : float
TT or UT1 Julian date.
xp : float
Conventionally-defined X coordinate of Celestial Intermediate
Pole with respect to ICRS pole, in arcseconds.
yp : float
Conventionally defined Y coordinate of Celestial Intermediate
Pole with respect to ICRS pole, in arcseconds.
position : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to ITRF axes.
direction: short int
Flag determining 'direction' of transformation;
direction = 0 transformation applied, ICRS to terrestrial
intermediate system (default)
direction != 0 inverse transformation applied, terrestrial
intermediate system to ICRS
Returns
-------
position : tuple of floats, of length 3
Position vector, geocentric equatorial rectangular coordinates,
referred to true equator and TIO.
References
----------
.. [R1] Bangert, J. et. al. (2011), 'User's Guide to NOVAS Version
C3.1', C23, C110, C111, C113, C114.
.. [R2] Lambert & Bizouard (2002), Astronomy and Astrophysics 394,
317-321.
|