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.

$rad = deg2rad ($degr)

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 = dynamical_delta ($time);

This method returns the difference between dynamical and universal time at the given universal time. That is,

 $dynamical = $time + dynamical_delta ($time)

if $time is universal time.

The algorithm is from Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 10, page 78.

$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.

$time = find_first_true ($start, $end, \&test, $limit);

This function finds the first time between $start and $end for which test ($time) is true. The resolution is $limit, which defaults to 1 if not specified. If the times are reversed (i.e. the start time is after the end time) the time returned is the last time test ($time) is true.

The test () function is assumed to be false for the first part of the interval, and true for the rest. If this assumption is violated, the result of this subroutine should be considered meaningless.

The calculation is done by, essentially, a binary search; the interval is repeatedly split, the function is evaluated at the midpoint, and a new interval selected based on whether the result is true or false.

Actually, nothing in this function says the independent variable has to be time.

$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 subroutine 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.

$radians = omega ($time);

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.

$degrees = rad2deg ($radians)

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.

ACKNOWLEDGMENTS

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)

COPYRIGHT

Copyright 2005, 2006, 2007 by Thomas R. Wyant, III (wyant at cpan dot org). All rights reserved.

This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself. Please see http://perldoc.perl.org/index-licence.html for the current licenses.

This software is provided without any warranty of any kind, express or implied. The author will not be liable for any damages of any sort relating in any way to this software.