Methods

$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. If higher-accuracy subclasses are ever implemented, there will be one singleton for each class.

The singleton logic 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( $station, $start, $end );

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

The $station argument may be omitted if the "station" attribute has been set. That is, this method can also be called as

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

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. This attribute is inherited from Astro::Coord::ECI, and documented there.

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

This convenience method wraps $sun->almanac(), but returns a list of hash references, sort of like Astro::Coord::ECI::TLE->pass() does. The hashes contain the following keys:

  {almanac} => {
    {event} => the event type;
    {detail} => the event detail (typically 0 or 1);
    {description} => the event description;
  }
  {body} => the original object ($sun);
  {station} => the observing station;
  {time} => the time the quarter occurred.
    

The {time}, {event}, {detail}, and {description} keys correspond to elements 0 through 3 of the list returned by almanac().

$coord2 = $coord->clone ();

If singleton objects are enabled, this override of the superclass' method simply returns the invocant. Otherwise it does a deep clone of an object, producing a different but identical object.

Prior to version 0.099_01 it always returned a clone. Yes, this is a change in long-standing functionality, but a long-standing bug is still a bug.

$elevation = $tle->correct_for_refraction( $elevation )

This override of the superclass' method simply returns the elevation passed to it. I have no algorithm for refraction at the surface of the photosphere or anywhere else in the environs of the Sun, and explaining why I make no correction at all seemed easier than explaining why I make an incorrect correction.

See the Astro::Coord::ECI "azel()" and "azel_offset()" documentation for whether this class' "correct_for_refraction()" method is actually called by those methods.

$long = $sun->geometric_longitude ()

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

$sun->get( ... )

This method has been overridden to return the invocant as the 'sun' attribute.

($point, $intens, $central) = $sun->magnitude ($theta, $omega);

This method returns the magnitude of the Sun at a point $theta radians from the center of its disk, given that the disk's angular radius (not diameter) is $omega radians. The returned $point is the magnitude at the given point (undef if $theta > $omega), $intens is the ratio of the intensity at the given point to the central intensity (0 if $theta > $omega), and $central is the central magnitude.

If this method is called in scalar context, it returns $point, the point magnitude.

If the $omega argument is omitted or undefined, it is calculated based on the geocentric range to the Sun at the current time setting of the object.

If the $theta argument is omitted or undefined, the method returns the average magnitude of the Sun, which is taken to be -26.8.

The limb-darkening algorithm and the associated constants come from <https://en.wikipedia.org/wiki/Limb_darkening>.

For consistency's sake, an observing station can optionally be passed as the first argument (i.e. before $theta). This is currently ignored.

($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 (March equinox) to 3 (December solstice), and a string describing the equinox or solstice. If called in scalar context, you just get the time.

If the "station" attribute is not set or set to a location on or north of the Equator, the descriptor strings are

 0 - Spring equinox
 1 - Summer solstice
 2 - Fall equinox
 3 - Winter solstice
    

If the "station" attribute is set to a location south of the Equator, the descriptor strings are

 0 - Fall equinox
 1 - Winter solstice
 2 - Spring equinox
 3 - Summer solstice
    

The optional $want argument says which equinox or solstice you want, as a number from 0 through 3.

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

As of version 0.088_01, the algorithm given in Jean Meeus' "Astronomical Algorithms", 2nd Edition, Chapter 27 ("Equinoxes and Solstices"), pages 278ff is used. This should be good for the range -1000 to 3000 Gregorian, and good to within a minute or so within the range 1951 to 2050 Gregorian, but the longitude of the Sun at the calculated time may be as much as 0.01 degree off the exact time for the event.

If you take the United States Naval Observatory's times (given to the nearest minute) as the standard, the maximum deviation from that standard in the range 1700 to 2100 is 226 seconds. I have no information on this algorithm's accuracy outside that range. Caveat user..

In version 0.088 and before, this calculation was done by successive approximation based on the position of the Sun, and was good to about 15 minutes.

If you want the old iterative version back, set attribute "iterate_for_quarters" to a true value.

$hash_reference = $sun->next_quarter_hash($want);

This convenience method wraps $sun->next_quarter(), but returns the data in a hash reference, sort of like Astro::Coord::ECI::TLE->pass() does. The hash contains the following keys:

  {body} => the original object ($sun);
  {almanac} => {
    {event} => 'quarter',
    {detail} => the quarter number (0 through 3);
    {description} => the quarter description;
  }
  {time} => the time the quarter occurred.
    

The {time}, {detail}, and {description} keys correspond to elements 0 through 2 of the list returned by next_quarter().

$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->set( ... )

This method has been overridden to silently ignore any attempt to set the 'sun' attribute.

$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. The 'equinox_dynamical' attribute is set to the object's currently-set dynamical time.

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.

Attributes

iterate_for_quarters (Boolean)

If this attribute is true, the "next_quarter()" method uses the old (pre-0.088_01) algorithm.

If this attribute is false, the new algorithm is used.

The default is "undef", i.e. false, because I believe the new algorithm to be more accurate for reasonably-current times.

This attribute is new with version 0.088_01.

Historical Calculations

Historical calculations will need to use a 64-bit Perl, or at least one with 64-bit integers, to represent times more than about 38 years from the system epoch.

In addition, you will need to be careful how you do input and output conversions.

Time::Local is a core module and an obvious choice, but it only does Gregorian dates. Historical calculations prior to 1587 typically use the Julian calendar. For this you will need to go to something like DateTime::Calendar::Julian, or DateTime::Calendar::Christian which does either Julian or Gregorian as needed.

Should you decide to use Time::Local, you should be aware that its "timegm()" and "timelocal()" interpret the year argument strangely: years in the range "0 - 999" inclusive are not interpreted as Gregorian years, though years outside that range are so interpreted. Beginning with version 1.27 (released July 9 2018), additional subroutines "timegm_modern()" and "timelocal_modern()" were added. These always interpret the year argument as a Gregorian year.