NAME

Astro::Coord::ECI::VSOP87D::Sun - VSOP87D model of the position of the Sun

SYNOPSIS

 use Astro::Coord::ECI::VSOP87D::Sun;
 use Astro::Coord::ECI::Utils qw{ deg2rad };
 use POSIX qw{ strftime };
 use Time::Local qw{ localtime };
 
 my $station = Astro::Coord::ECI->new(
     name => 'White House',
 )->geodetic(
     deg2rad( 38.899 ),  # radians
     deg2rad( -77.038 ), # radians
     16.68/1000,         # Kilometers
 );
 my $sun = Astro::Coord::ECI::VSOP87D::Sun->new(
     station => $station,
 );
 my $today = timelocal( 0, 0, 0, ( localtime )[ 3 .. 5 ] );
 foreach my $item ( $sun->almanac( $today, $today + 86400 ) ) {
     local $\ = "\n";
     print strftime( '%d-%b-%Y %H:%M:%S', localtime $item->[0] ),
         $item->[3];
 }

DESCRIPTION

This Perl class computes the position of the Sun using the VSOP87D model. It is a subclass of Astro::Coord::ECI::Sun.

METHODS

This class supports the following public methods in addition to those of its superclass:

geometric_longitude

This method returns the geometric longitude of the body. This is after conversion to FK5.

model_cutoff_definition

This method reports, creates, and deletes model cutoff definitions.

The first argument is the name of the model cutoff. If this is the only argument, a reference to a hash defining the named model cutoff is returned. This return is a deep clone of the actual definition.

If the second argument is undef, the named model cutoff is deleted. If the model cutoff does not exist, the call does nothing. It is an error to try to delete built-in cutoffs 'none' and 'Meeus'.

If the second argument is a reference to a hash, this defines or redefines a model cutoff. The keys to the hash are the names of VSOP87D series ('L0' through 'L5', 'B0' through 'B5', and 'R0' through 'R5'), and the value of each key is the number of terms of that series to use. If one of the keys is omitted or has a false value, that series is not used.

next_quarter

This override of the superclass' method ignores the value of the 'iterate_for_quarters' attribute, and always iterates. The superclass uses an algorithm from Meeus if this attribute is false.

nutation

 my ( $delta_psi, $delta_epsilon ) =
     $self->nutation( $dynamical_time, $cutoff );

This subroutine (not method) calculates the nutation in ecliptic longitude ($delta_psi) and latitude ($delta_epsilon) at the given dynamical time in seconds since the epoch (i.e. Perl time), according to the IAU 1980 model.

The $time argument is optional, and defaults to the object's current dynamical time.

The $cutoff argument is optional; if specified as a number larger than 0, terms whose amplitudes are smaller than the nutation cutoff (in milli arc seconds) are ignored. The Meeus version of the algorithm is specified by a value of 3. The default is specified by the nutation_cutoff() value.

The model itself comes from Meeus chapter 22. The model parameters were not transcribed from that source, however, but were taken from the source IAU C reference implementation of the algorithm, src/nut80.c, with the minimum modifications necessary to make the C code into Perl code. This file is contained in http://www.iausofa.org/2018_0130_C/sofa_c-20180130.tar.gz.

This method is exportable, either by name or via the :mixin or :sun tags.

obliquity

 $epsilon = $self->obliquity( $time );

This method calculates the obliquity of the ecliptic in radians at the given dynamical time. If the time is omitted or specified as undef, the current dynamical time of the object is used.

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

order

 say 'Order from Sun: ', $self->order();

This method returns the order of the body from the Sun, with the Sun itself being 0. The number 3 is skipped, since that would represent the Earth.

In fewer words, this method returns 0.

period

 $self->period()

This method returns the sidereal period of the Earth, calculated from the coefficient of its first L1 term.

The algorithm is the author's, and is a first approximation. That is. it is just the tropical period plus however long it takes the object to cover the amount of precession during the tropical year.

time_set

 $self->time_set()

This method is not normally called by the user. It is called by Astro::Coord::ECI to compute the position once the time has been set.

It returns the invocant.

year

 $self->year()

This method returns the length of the tropical year of the Earth, calculated from the coefficient of its first L1 term.

ATTRIBUTES

This class has the following attributes in addition to those of its superclass:

model_cutoff

This attribute specifies how to truncate the calculation. Valid values are:

'none' specifies no model cutoff (i.e. the full series);
'Meeus' specifies the Meeus Appendix III series.

The default is 'Meeus'.

nutation_cutoff

The nutation_cutoff value specifies how to truncate the nutation calculation. All terms whose magnitudes are less than the nutation cutoff are ignored. The value is in terms of 0.0001 seconds of arc, and must be a non-negative number.

The default is 3, which is the value Meeus uses.

SEE ALSO

Astro::Coord::ECI::Sun

Astro::Coord::ECI::VSOP87D

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2018-2019 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

Software Routines from the IAU SOFA Collection were used. Copyright (C) International Astronomical Union Standards of Fundamental Astronomy (http://www.iausofa.org)