NAME

Astro::Coord::ECI::Sun - Compute the position of the Sun.

SYNOPSIS

 my $sun = Astro::Coord::ECI::Sun->new ();
 my $sta = Astro::Coord::ECI->
     universal (time ())->
     geodetic ($lat, $long, $alt);
 my ($time, $rise) = $sta->next_elevation ($sun);
 print "Sun @{[$rise ? 'rise' : 'set']} is ",
     scalar localtime $time;

DESCRIPTION

This module implements the position of the Sun as a function of time, as described in Jean Meeus' ``Astronomical Algorithms,'' second edition. It is a subclass of Astro::Coord::ECI, with the id, name, and diameter attributes initialized appropriately, and the time_set() method overridden to compute the position of the Sun at the given time.

Methods

The following methods should be considered public:

$sun = Astro::Coord::ECI::Sun->new();

This method instantiates an object to represent the coordinates of the Sun. This is a subclass of Astro::Coord::ECI, with the id and name attributes set to 'Sun', and the diameter attribute set to 1392000 km per Jean Meeus' ``Astronomical Algorithms'', 2nd Edition, Appendix I, page 407.

Any arguments are passed to the set() method once the object has been instantiated. Yes, you can override the ``hard-wired'' id, name, and so forth in this way.

If $Astro::Coord::ECI::Sun::Singleton is true, you get a singleton object; that is, only one object is instantiated and subsequent calls to new() just return that object. This only works if Scalar::Util exports weaken(). If it does not, the setting of $Astro::Coord::ECI::Sun::Singleton is silently ignored. The default is true if Scalar::Util can be loaded and exports weaken(), and false otherwise.

@almanac = $sun->almanac($location, $start, $end);

This method produces almanac data for the Sun for the given location, between the given start and end times. The location is assumed to be Earth-Fixed - that is, you can't do this for something in orbit.

The start time defaults to the current time setting of the $sun object, and the end time defaults to a day after the start time.

The almanac data consists of a list of list references. Each list reference points to a list containing the following elements:

 [0] => time
 [1] => event (string)
 [2] => detail (integer)
 [3] => description (string)

The @almanac list is returned sorted by time.

The following events, details, and descriptions are at least potentially returned:

 horizon: 0 = Sunset, 1 = Sunrise;
 transit: 0 = local midnight, 1 = local noon;
 twilight: 0 = end twilight, 1 = begin twilight;
 quarter: 0 = spring equinox, 1 = summer solstice,
          2 = fall equinox, 3 = winter solstice.

Twilight is calculated based on the current value of the twilight attribute of the $sun object.

$longitude = $sun->ecliptic_longitude();

This method returns the ecliptic longitude of the sun at its current time setting, in radians. It's really just a convenience method, since it is equivalent to ($sun->ecliptic)[1], and in fact that is how it is implemented.

$long = $sun->geometric_longitude()

This method returns the geometric longitude of the Sun in radians at the last time set.

($time, $quarter, $desc) = $sun->next_quarter($want);

This method calculates the time of the next equinox or solstice after the current time setting of the $sun object. The return is the time, which equinox or solstice it is as a number from 0 (vernal equinox) to 3 (winter solstice), and a string describing the equinox or solstice. If called in scalar context, you just get the time.

The optional $want argument says which equinox or solstice you want.

As a side effect, the time of the $sun object ends up set to the returned time.

The method of calculation is successive approximation, and actually returns the second after the calculated equinox or solstice.

Since we only calculate the Sun's position to the nearest 0.01 degree, the calculated solstice or equinox may be in error by as much as 15 minutes.

$period = $sun->period()

Although this method is attached to an object that represents the Sun, what it actually returns is the sidereal period of the Earth, per Appendix I (pg 408) of Jean Meeus' ``Astronomical Algorithms,'' 2nd edition.

$sun->time_set ()

This method sets coordinates of the object to the coordinates of the Sun at the object's currently-set universal time. The velocity components are arbitrarily set to 0.

Although there's no reason this method can't be called directly, it exists to take advantage of the hook in the Astro::Coord::ECI object, to allow the position of the Sun to be computed when the object's time is set.

The algorithm comes from Jean Meeus' ``Astronomical Algorithms'', 2nd Edition, Chapter 25, pages 163ff.

ACKNOWLEDGMENTS

The author wishes to acknowledge Jean Meeus, whose book ``Astronomical Algorithms'' (second edition) formed the basis for this module.

AUTHOR

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

COPYRIGHT

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.

Astro::Coord::ECI::Sun - Compute the position of the Sun.