view release on metacpan or  search on metacpan

lib/Astro/Coord/ECI/TLE.pm  view on Meta::CPAN

object at the given time, using the revised SGP4 model. The universal
time of the object is set to $time, and the 'equinox_dynamical'
attribute is set to the current value of the 'epoch_dynamical'
attribute.

The result is the original object reference. See the L</DESCRIPTION>
heading above for how to retrieve the coordinates you just calculated.

The algorithm for this model comes from "Revisiting Spacetrack Report
Number 3" (see L<ACKNOWLEDGMENTS|/ACKNOWLEDGMENTS>). That report
considers the algorithm to be a correction and extension of SGP4
(merging it with SDP4), and simply calls the algorithm SGP4. I have
appended the "r" (for 'revised' or 'revisited', take your pick) because
I have preserved the original algorithm as well.

B<Note well> that this algorithm depends on the setting of the
'gravconst_r' attribute. The default setting of that attribute in this
module is 84, but the test data that comes with "Revisiting Spacetrack
Report #3" uses 72.

This algorithm is also (currently) the only one that returns a useful
value in the model_error attribute, as follows:

 0 = success
 1 = mean eccentricity < 0 or > 1, or a < .95
 2 = mean motion < 0.0
 3 = instantaneous eccentricity < 0 or > 1
 4 = semi-latus rectum < 0
 5 = epoch elements are sub-orbital
 6 = satellite has decayed

These errors are dualvars if your Scalar::Util supports these. That is,
they are interpreted as numbers in numeric context and the
corresponding string in string context. The string is generally the
explanation, except for 0, which is '' in string context. If your
Scalar::Util does not support dualvar, the numeric value is returned.

Currently, errors 1 through 4 cause an explicit exception to be thrown
after setting the model_error attribute. Exceptions will also be thrown
if the TLE eccentricity is negative or greater than one, or the TLE mean
motion is negative.

Errors 5 and 6 look more like informational errors to me. Error 5
indicates that the perigee is less than the radius of the earth. This
could very well happen if the TLE represents a coasting arc of a
spacecraft being launched or preparing for re-entry. Error 6 means the
actual computed position was underground. Maybe this should be an
exception, though I have never needed this kind of exception previously.

B<Note> that this first release of the 'Revisiting Spacetrack Report #3'
functionality should be considered alpha code. That is to say, I may
need to change the way it behaves, especially in the matter of what is
an exception and what is not.

=cut

#	What follows (down to, but not including, the 'end sgp4unit.for'
#	comment) is the Fortran code from sgp4unit.for, translated into
#	Perl by the custom for2pl script, with conversion specification
#	sgp4unit.spec. No hand-edits have been applied. The preferred
#	way to modify this code is to enhance for2pl (which is _not_
#	included in the CPAN kit) or to modify sgp4unit.for (ditto),
#	since that way further modifications can be easily incorporated
#	into this module.
#
#	Comments in the included file are those from the original
#	Fortran unless preceded by '>>>>trw'. The latter are comments
#	introduced by the conversion program to remove unwanted Fortran.
#
#	IMPLEMENTATION NOTES:
#
#	The original Space Track Report Number 3 code used a custom
#	function called FMOD2P to reduce an angle to the range 0 <=
#	angle < 2*PI. This is translated to Astro::Coord::ECI::Utils
#	function mod2pi. But the Revisiting Spacetrack Report #3 code
#	used the Fortran intrinsic function DMOD, which produces
#	negative results for a negative divisor. So instead of using
#	mod2pi, sgp4r() and related code use the POSIX fmod function,
#	which has the same behaviour.
#
#	Similarly, the original code used a custom function ACTAN to
#	produce an arc in the range 0 <= arc < 2*PI from its two
#	arguments and the single-argument ATAN intrinsic. The
#	translation into Perl ended up with an _actan function at that
#	point. But the revised code simply uses atan2.
#
#	The included file processed from sgp4unit.for begins here.

use constant SGP4R_ERROR_0 => dualvar (0, '');  # guaranteed false
use constant SGP4R_ERROR_MEAN_ECCEN =>
    'Sgp4r 1: Mean eccentricity < 0 or > 1, or a < .95';
use constant SGP4R_ERROR_1 => dualvar (1, SGP4R_ERROR_MEAN_ECCEN);
use constant SGP4R_ERROR_MEAN_MOTION =>
    'Sgp4r 2: Mean motion < 0.0';
use constant SGP4R_ERROR_2 => dualvar (2, SGP4R_ERROR_MEAN_MOTION);
use constant SGP4R_ERROR_INST_ECCEN =>
    'Sgp4r 3: Instantaneous eccentricity < 0 or > 1';
use constant SGP4R_ERROR_3 => dualvar (3, SGP4R_ERROR_INST_ECCEN);
use constant SGP4R_ERROR_LATUSRECTUM =>
    'Sgp4r 4: Semi-latus rectum < 0';
use constant SGP4R_ERROR_4 => dualvar (4, SGP4R_ERROR_LATUSRECTUM);
use constant SGP4R_ERROR_5 => dualvar (5,
    'Sgp4r 5: Epoch elements are sub-orbital');
use constant SGP4R_ERROR_6 => dualvar (6,
    'Sgp4r 6: Satellite has decayed');

#*   -------------------------------------------------------------------
#*
#*                               sgp4unit.for
#*
#*    this file contains the sgp4 procedures for analytical propagation
#*    of a satellite. the code was originally released in the 1980 and 1986
#*    spacetrack papers. a detailed discussion of the theory and history
#*    may be found in the 2006 aiaa paper by vallado, crawford, hujsak,
#*    and kelso.
#*
#*                            companion code for
#*               fundamentals of astrodynamics and applications
#*                                    2007
#*                              by david vallado
#*