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


 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;


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.


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.

@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 siderial 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.


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


The Astro-MoonPhase package by Brett Hamilton, which contains a function-based module to compute the current phase, distance and angular diameter of the Moon, as well as the angular diameter and distance of the Sun.

The Astro-Sunrise package by Ron Hill, which contains a function-based module to compute sunrise and sunset for the given day and location.

The Astro-SunTime package by Rob Fugina, which provides functionality similar to Astro-Sunrise.


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


Copyright 2005, 2006 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 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.