The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Astro-0.78
River stage one • 1 direct dependent • 1 total dependent
/ Astro::Time

NAME

Astro::Time - Time based astronomical routines

SYNOPSIS


            

              
              
use Astro::Time;
$dayno = cal2dayno($day, $month, $year);
print "It's a leap year!\n" if (leap($year));
$lmst = mjd2lst($mjd, $longitude, $dUT1);
$turns = str2turn($string, 'H');
$str = turn2str($turn, 'D', $sig);

DESCRIPTION

Astro::Time contains an assorted set Perl routines for time based conversions, such as conversion between calendar dates and Modified Julian day and conversion of UT to local sidereal time. Include are routines for conversion between numerical and string representation of angles.

AUTHOR

Chris Phillips Chris.Phillips@csiro.au

FUNCTIONS

turn2str

            

              
              
 $str = turn2str($turn, $mode, $sig);
 $str = turn2str($turn, $mode, $sig, $strsep);
Convert fraction of a turn into string representation
  $turn   Angle in turns
  $mode   Mode of string to convert to:
           'H' for hours
           'D' for degrees
  $sig    number of significant figures
  $strsep String separator (override for default $Astro::Time::StrSep)
Note:
The behavior can be modified by the following two variables:
 $Astro::Time::StrZero   Minimum number of leading digits (zero padded 
                         if needed)
 $Astro::Time::StrSep    (Overridden by optional fourth argument)
   Deliminator used in string (Default ':')
   This may also equal one of a number of special values:
     'HMS'           12H45M12.3S or 170D34M56.2S
     'hms'           12h45m12.3s or 170d34m56.2s
     'deg'           170d34'56.2"
deg2str

            

              
              
 $str=deg2str($deg, $mode, $sig);
Convert degrees into string representation
  $deg   angle in degrees
  $mode  mode of string to convert to:
          'H' for hours
          'D' for degrees
  $sig   number of significant figures
See note for turn2str
rad2str

            

              
              
 $str=rad2str($rad, $mode, $sig);
Convert radians into string representation
  $rad    angle in radians
  $mode   mode of string to convert to:
           'H' for hours
           'D' for degrees
  $sig is number of significant figures
See note for turn2str
str2turn

            

              
              
 $turns = str2turn($string,$mode);
Convert angle from string representation into fraction of a turn
  $string    a : or space delimited angle
  $mode      type of angle
              'H' if $string is in hours,min,sec
              'D' if $string is in deg,arcmin,arcsec
The format of $string can be fairly flexible e.g.:
   12.2
   12:34
   12:34:45.1
  -23 34 12.3
  -34 34.3
Note: You cannot mix spaces and :
str2deg

            

              
              
 $degrees=str2deg($string,$mode);
Convert angle from string representation into degrees
  $string   a : or space delimited angle
  $mode     'H' if $string is in hours,min,sec
            'D' if $string is in deg,arcmin,arcsec
See note for str2turn
str2rad

            

              
              
 $radians=str2rad($string,$mode);
Convert angle from string representation into radians
  $string   a : or space delimited angle
  $mode     'H' if $string is in hours,min,sec
            'D' if $string is in deg,arcmin,arcsec
See note for str2turn
hms2time

            

              
              
 ($time) = hms2time($hour, $minute, $second);
 ($time) = hms2time($hour, $minute, $second, $mode);
Returns the day fraction given hours minutes and seconds (or degrees)
  $time        Day fraction
  $hour        Hours
  $minutes     Minutes
  $second      Seconds
  $mode        'H' or 'D' to interpret as hours or degrees (default 
               hours)
time2hms

            

              
              
 ($sign, $hour, $minute, $second) = time2hms($time, $mode, $sig);
Returns hours (or degrees), minutes and seconds given the day fraction
  $sign      Sign of angle ('+' or '-')
  $hour      Hours
  $minutes   Minutes
  $second    Seconds
  $time      Day fraction
  $mode      Return degrees or Hours?
              'H' for hours
              'D' for degrees
  $sig       Number of significant digits for $second
deg2rad

            

              
              
 $rad=deg2rad($deg);
Convert degrees to radians
rad2deg

            

              
              
 $deg=rad2deg($rad);
Convert radians to degrees
turn2rad

            

              
              
 $rad=turn2rad($turn);
Convert turns to radians
rad2turn

            

              
              
 $turn=rad2turn($rad);
Convert radians to turns
turn2deg

            

              
              
 $deg=turn2deg($turn);
Convert turns to radians
deg2turn

            

              
              
 $turn=deg2turn($deg);
Convert degrees to turns
cal2dayno

            

              
              
 $dayno = cal2dayno($day, $month, $year);
Returns the day number corresponding to $day of $month in $year.
dayno2cal

            

              
              
 ($day, $month) = dayno2cal($dayno, $year);
Return the $day and $month corresponding to $dayno of $year.
leap

            

              
              
 $isleapyear = leap($year);
Returns true if $year is a leap year.
  $year    year in full
yesterday

            

              
              
 ($dayno, $year) = yesterday($dayno, $year);
 ($day, $month, $year) = yesterday($day, $month, $year);
Winds back the day number by one, taking account of year wraps.
  $dayno       Day number of year
  $year        Year
  $month       Month
  $day         Day of month
tomorrow

            

              
              
 ($dayno, $year) = tomorrow($dayno, $year);
 ($day, $month, $year) = tomorrow($day, $month, $year);
Advances the day number by one, taking account of year wraps.
  $dayno       Day number of year
  $year        Year
  $month       Month
  $day         Day of month
mjd2cal

            

              
              
 ($day, $month, $year, $ut) = mjd2cal($mjd);
Converts a modified Julian day number into calendar date (universal 
time). (based on the slalib routine sla_djcl).
   $mjd     Modified Julian day (JD-2400000.5)
   $day     Day of the month.
   $month   Month of the year.
   $year    Year
   $ut      UT day fraction
cal2mjd

            

              
              
 $mjd = cal2mjd($day, $month, $year, $ut);
Converts a calendar date (universal time) into modified Julian day 
number.
   $day     Day of the month.
   $month   Month of the year.
   $year    Year
   $ut      UT dayfraction
   $mjd     Modified Julian day (JD-2400000.5)
mjd2dayno

            

              
              
 ($dayno, $year, $ut) = mjd2dayno($mjd);
Converts a modified Julian day number into year and dayno (universal 
time).
   $mjd     Modified Julian day (JD-2400000.5)
   $year    Year
   $dayno   Dayno of year
dayno2mjd

            

              
              
 $mjd = dayno2mjd($dayno, $year, $ut);
Converts a dayno and year to modified Julian day
   $mjd     Modified Julian day (JD-2400000.5)
   $year    Year
   $dayno   Dayno of year
now2mjd

            

              
              
$mjd = now2mjd()
jd2mjd

            

              
              
 $mjd = jd2mjd($jd);
Converts a Julian day to Modified Julian day
   $jd      Julian day
   $mjd     Modified Julian day
mjd2jd

            

              
              
 $jd = mjd2jd($mjd);
Converts a Modified Julian day to Julian day
   $mjd     Modified Julian day
   $jd      Julian day
mjd2time

            

              
              
 $str = mjd2time($mjd);
 $str = mjd2time($mjd, $np);
Converts a Modified Julian day to a formatted string
   $mjd     Modified Julian day
   $str     Formatted time
   $np      Number of significant digits for fraction of a sec. Default 0
mjd2vextime

            

              
              
 $str = mjd2vextime($mjd);
 $str = mjd2vextime($mjd, $np);
Converts a Modified Julian day to a vex formatted string
   $mjd     Modified Julian day
   $str     Formatted time
   $np      Number of significant digits for fraction of a sec. Default 0
mjd2epoch

            

              
              
 $time = mjd2epoch($mjd);
Converts a Modified Julian day to unix Epoch (seconds sinve 1 Jan 1970)
Rounded to the nearest second
   $mjd     Modified Julian day
   $tie     Seconds since 1 Jan 1970
gst

            

              
              
 $gst  = gst($mjd);
 $gmst = gst($mjd, $dUT1);
 $gtst = gst($mjd, $dUT1, $eqenx);
Converts a modified Julian day number to Greenwich sidereal time
  $mjd     modified Julian day (JD-2400000.5)
  $dUT1    difference between UTC and UT1 (UT1 = UTC + dUT1) (seconds)
  $eqenx   Equation of the equinoxes (not yet supported)
  $gst     Greenwich sidereal time (turns)
  $gmst    Greenwich mean sidereal time (turns)
  $gtst    Greenwich true sidereal time (turns)
mjd2lst

            

              
              
 $lst = mjd2lst($mjd, $longitude);
 $lmst = mjd2lst($mjd, $longitude, $dUT1);
 $ltst = mjd2lst($mjd, $longitude, $dUT1, $eqenx);
Converts a modified Julian day number into local sidereal time (lst),
local mean sidereal time (lmst) or local true sidereal time (ltst).
Unless high precisions is required dUT1 can be omitted (it will always 
be in the range -0.5 to 0.5 seconds).
  $mjd         Modified Julian day (JD-2400000.5)
  $longitude   Longitude for which the LST is required (turns)
  $dUT1        Difference between UTC and UT1 (UT1 = UTC + dUT1)(seconds)
  $eqenx       Equation of the equinoxes (not yet supported)
  $lst         Local sidereal time (turns)
  $lmst        Local mean sidereal time (turns)
  $ltst        Local true sidereal time (turns)
cal2lst

            

              
              
 $lst = cal2lst($day, $month, $year, $ut, $longitude);
 $lmst = cal2lst($day, $month, $year, $ut, $longitude, $dUT1);
 $ltst = cal2lst($day, $month, $year, $ut, $longitude, $dUT1, $eqenx);
Wrapper to mjd2lst using calendar date rather than mjd
dayno2lst

            

              
              
 $lst = dayno2lst($dayno, $year, $ut, $longitude);
 $lmst = dayno2lst($dayno, $year, $ut, $longitude, $dUT1);
 $ltst = dayno2lst($dayno, $year, $ut, $longitude, $dUT1, $eqenx);
Wrapper to mjd2lst using calendar date rather than mjd
rise

            

              
              
 ($lst_rise, $lst_set) = rise($ra, $dec, $obslat, $el_limit);
Return the lst rise and set time of the given source
  $lst_rise, $lst_set  Rise and set time (turns)
  $ra, $dec            RA and Dec of source (turns)
  $obslat              Latitude of observatory (turns)
  $el_limit            Elevation limit of observatory
                                         (turns, 0 horizontal)
Returns 'Circumpolar'  if source circumpolar
Returns  undef         if source never rises
Uses the formula:
  cos $z_limit = sin $obslat * sin $dec + cos $obslat * cos $dec 
                 * cos $HA
  where:
   $z_limit is the zenith angle limit corresponding to $el_limit
   $HA is the Hour Angle of the source
NOTE: For maximum accuracy source coordinated should be precessed to
     the current date.
lst2mjd

            

              
              
$mjd = lst2mjd($lmst, $dayno, $year, $longitude);
$mjd = lst2mjd($lmst, $dayno, $year, $longitude, $dUT1);
This routine calculates the modified Julian day number corresponding
to the local mean sidereal time $lmst at $longitude, on a given UT
day number ($dayno).  Unless high precision is required dUT1 can be
omitted.
The required inputs are :
  $lmst      - The local mean sidereal time (turns)
  $dayno     - The UT day of year for which to do the conversion
  $year      - The year for which to do the conversion
  $longitude - The longitude of the observatory (turns)
  $dUT1      - Difference between UTC and UT1 (UT1 = UTC + dUT1) 
                                                              (seconds)
  $mjd         The modified Julian day corresponding to $lmst on $dayno
month2str

            

              
              
$monthstr = month2str($month);
$longmonthstr = month2str($month,1);
This routine returns the name of the given month (as a number 1..12), 
where 1 is January. The default is a 3 character version of the month
('Jan', 'Feb', etc) in the second form the full month is returned
The required inputs are :
  $month      - The month in question with 1 == January.
mjd2weekday

            

              
              
 $weekday = mjd2weekday($mjd);
Returns the weekday correspondig to the given MJD.
0 ==> Monday. May not work for historical dates.
   $mjd     Modified Julian day (JD-2400000.5)
mjd2weekdaystr

            

              
              
 $weekdaystr = mjd2weekdaystr($mjd);
Returns the name of the weekday correspondig to the given MJD.
May not work for historical dates.
   $mjd     Modified Julian day (JD-2400000.5)
str2month

            

              
              
$month = month2str($monthstr);
Given the name of a month (in English), this routine returns the
an integer between 1 and 12, where 1 is January. Full month names of
3 character abbreviations are acceptable. Minumum matching (e.g. "Marc")
is not supported.
The required inputs are :
  $month      - Name of the month ('Jan', 'January', 'Feb', 'February' etc)

1 POD Error

The following errors were encountered while parsing the POD:

Around line 139:

=over without closing =back