/ 
Astro-Coord-ECI-VSOP87D-0.005
River stage zero No dependents
/ Astro::Coord::ECI::VSOP87D::_Superior

NAME

Astro::Coord::ECI::VSOP87D::_Superior - VSOP87D superior planets

SYNOPSIS

This abstract Perl class is not intended to be invoked directly by the user.

DESCRIPTION

This abstract Perl class represents the VSOP87D model of an superior planet. It is a subclass of Astro::Coord::ECI.

METHODS

This class supports the following public methods in addition to those inherited from the superclass.

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.

If the second argument is a scalar, it is expected to be a number, and a model cutoff is generated consisting of all terms whose coefficient ('A' in Meeus' terminology) is equal to or greater than the number.

If the second argument is a code reference, this code is expected to return a reference to a valid model cutoff hash as described two paragraphs previously. Its arguments are the individual series hashes, extracted from the model. Each hash will have the following keys:

series

The name of the series (e.g. 'L0').

terms

An array reference containing the terms of the series. Each term is a reference to an array containing in order, in Meeus' terms, values 'A', 'B', and 'C'.

next_quarter

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

This method calculates the time of the next quarter event after the current time setting of the $body object. The return is the time, which event it is as a number from 0 to 3, and a string describing the event. If called in scalar context, you just get the time.

Quarters are defined as positions in the orbit, not phases. This is the usage throughout the Astro::Coord::ECI hierarchy, even the Moon. The name 'quarter' seems ill-chosen, but it is probably too late to do anything about it now.

Specifically, for superior planets the quarters are:

0 - conjunction
1 - east quadrature
2 - opposition
3 - west quadrature

The optional $want argument says which event you want.

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

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

nutation

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

This 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 attribute.

The model itself is the IAU 1980 nutation model. Later models exist, but this was chosen because of the desire to be compatible with Meeus' examples. The implementation itself actually 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.

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.

period

$self->period()

This method returns the sidereal period of the object, 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.

synodic_period

$self->synodic_period()

This method returns the synodic period of the object -- that is to say the mean interval between oppositions or conjunctions of superior planets or between corresponding conjunctions of inferior planets.

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 object, 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

Astro::Coord::ECI::VSOP87D

SUPPORT

Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-Coord-ECI-VSOP87D, https://github.com/trwyant/perl-Astro-Coord-ECI-VSOP87D/issues, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2018-2021 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.