# NAME

Astro::Coord::ECI::Utils - Utility routines for astronomical calculations

# SYNOPSIS

`````` use Astro::Coord::ECI::Utils qw{:all};
my \$now = time ();
print "The current Julian day is ", julianday (\$now);``````

# DESCRIPTION

This module was written to provide a home for all the constants and utility subroutines used by Astro::Coord::ECI and its descendents. What ended up here was anything that was essentially a subroutine, not a method.

This package exports nothing by default. But all the constants and subroutines documented below are exportable, and the :all tag gets you all of them.

The following constants are exportable:

`````` AU = number of kilometers in an astronomical unit
LIGHTYEAR = number of kilometers in a light year
PARSEC = number of kilometers in a parsec
PERL2000 = January 1 2000, 12 noon universal, in Perl time
PI = the circle ratio, computed as atan2 (0, -1)
PIOVER2 = half the circle ratio
SECSPERDAY = the number of seconds in a day
TWOPI = twice the circle ratio``````

In addition, the following subroutines are exportable:

\$angle = acos (\$value)

This subroutine calculates the arc in radians whose cosine is the given value.

\$angle = asin (\$value)

This subroutine calculates the arc in radians whose sine is the given value.

\$magnitude = atmospheric_extinction (\$elevation, \$height);

This subroutine calculates the typical atmospheric extinction in magnitudes at the given elevation above the horizon in radians and the given height above sea level in kilometers.

The algorithm comes from Daniel W. E. Green's article "Magnitude Corrections for Atmospheric Extinction", which was published in the July 1992 issue of "International Comet Quarterly", and is available online at http://www.cfa.harvard.edu/icq/ICQExtinct.html. The text of this article makes it clear that the actual value of the atmospheric extinction can vary greatly from the typical values given even in the absence of cloud cover.

This subroutine converts degrees to radians.

\$value = distsq (\@coord1, \@coord2)

This subroutine calculates the square of the distance between the two sets of Cartesian coordinates. We do not take the square root here because of cases (e.g. the law of cosines) where we would just have to square the result again.

\$seconds = equation_of_time (\$time);

This method returns the equation of time at the given dynamical time.

The algorithm is from W. S. Smart's "Text-Book on Spherical Astronomy", as reported in Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 28, page 185.

\$difference = intensity_to_magnitude (\$ratio)

This method converts a ratio of light intensities to a difference in stellar magnitudes. The algorithm comes from Jean Meeus' "Astronomical Algorithms", Second Edition, Chapter 56, Page 395.

Note that, because of the way magnitudes work (a more negative number represents a brighter star) you get back a positive result for an intensity ratio less than 1, and a negative result for an intensity ratio greater than 1.

\$century = jcent2000 (\$time);

Several of the algorithms in Jean Meeus' "Astronomical Algorithms" are expressed in terms of the number of Julian centuries from epoch J2000.0 (e.g equations 12.1, 22.1). This subroutine encapsulates that calculation.

\$jd = jday2000 (\$time);

This subroutine converts a Perl date to the number of Julian days (and fractions thereof) since Julian 2000.0. This quantity is used in a number of the algorithms in Jean Meeus' "Astronomical Algorithms".

The computation makes use of information from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 7, page 62.

\$jd = julianday (\$time);

This subroutine converts a Perl date to a Julian day number.

The computation makes use of information from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 7, page 62.

\$theta = mod2pi (\$theta)

This subrouting reduces the given angle in radians to the range 0 <= \$theta < TWOPI.

\$delta_psi = nutation_in_longitude (\$time)

This subroutine calculates the nutation in longitude (delta psi) for the given dynamical time.

The algorithm comes from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 22, pages 143ff. Meeus states that it is good to 0.5 seconds of arc.

\$delta_epsilon = nutation_in_obliquity (\$time)

This subroutine calculates the nutation in obliquity (delta epsilon) for the given dynamical time.

The algorithm comes from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 22, pages 143ff. Meeus states that it is good to 0.1 seconds of arc.

\$epsilon = obliquity (\$time)

This subroutine calculates the obliquity of the ecliptic in radians at the given dynamical time.

The algorithm comes from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 22, pages 143ff. The conversion from universal to dynamical time comes from chapter 10, equation 10.2 on page 78.

This subroutine calculates the ecliptic longitude of the ascending node of the Moon's mean orbit at the given dynamical time.

The algorithm comes from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 22, pages 143ff.

This subroutine converts the given angle in radians to its equivalent in degrees.

\$value = tan (\$angle)

This subroutine computes the tangent of the given angle in radians.

\$value = theta0 (\$time);

This subroutine returns the Greenwich hour angle of the mean equinox at 0 hours universal on the day whose time is given (i.e. the argument is a standard Perl time).

\$value = thetag (\$time);

This subroutine returns the Greenwich hour angle of the mean equinox at the given time.

The algorithm comes from Jean Meeus' "Astronomical Algorithms", 2nd Edition, equation 12.4, page 88.

# ACKNOWLEDGEMENTS

The author wishes to acknowledge Jean Meeus, whose book "Astronomical Algorithms" (second edition) published by Willmann-Bell Inc (http://www.willbell.com/) provided several of the algorithms implemented herein.

# BUGS

Bugs can be reported to the author by mail, or through http://rt.cpan.org/.

# AUTHOR

Thomas R. Wyant, III (wyant at cpan dot org)