Astro::Coord::ECI::VSOP87D::_Superior(3pm)

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 can be obtained as part of a tarball from <https://www.iausofa.org/2023-10-11c>.

  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://github.com/trwyant/perl-Astro-Coord-ECI-VSOP87D/issues> or in electronic mail to the author.

AUTHOR
Thomas R. Wyant, III harryfmudd at comcast dot net

COPYRIGHT AND LICENSE
Copyright (C) 2018-2022, 2024-2026 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 files LICENSE-Artistic and LICENSE-GPL.

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.