Astro::Time(3pm)

📦
version 0.78 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

Astro::Time 💫

okay bestie, gather round, because we're about to get into Astro::Time — that's the Astro::Time(3pm) page from the User Contributed Perl Documentation, and she is gorgeous. it's a whole little toolkit of time-based astronomy routines and honestly? iconic. 💅

✨ NAME ✨

Astro::Time — time based astronomical routines 🕰️🌟

✨ SYNOPSIS ✨

the vibe check, in code form:

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);

like, look at her. she does so much with so little. 🫶

✨ DESCRIPTION ✨

so Astro::Time is a little grab-bag of assorted Perl routines for time based conversions — the ones you actually need, fr fr. we're talking conversion between calendar dates and Modified Julian day, conversion of UT to local sidereal time, that whole situation. 🌈

and she doesn't stop there: also included are routines for conversion between numerical and string representation of angles. so you can go number → pretty string → number again and never lose your mind about it. slay. ✨

✨ AUTHOR ✨

Chris Phillips — Chris.Phillips@csiro.au 💌

✨ FUNCTIONS ✨

this is the main character section, no cap. 👑

turn2str

$str = turn2str($turn, $mode, $sig);
$str = turn2str($turn, $mode, $sig, $strsep);

takes a fraction of a turn and turns it into a string representation. glow-up for numbers. ✨

  • $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);

converts 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 👆 (the whole StrZero / StrSep situation still applies, bestie)

rad2str

$str=rad2str($rad, $mode, $sig);

converts 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 again — same energy. 💜

str2turn

$turns = str2turn($string,$mode);

takes an angle from string representation and gives you back a fraction of a turn. the reverse glow-up. 🦋

  • $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 : — pick a lane, bestie. 😭

str2deg

$degrees=str2deg($string,$mode);

converts an 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 (yes, the no-mixing-spaces-and-colons rule, it follows you everywhere 💀)

str2rad

$radians=str2rad($string,$mode);

converts an 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 — same rules, same energy. 🫶

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. the un-glow-up, but make it precise. ✨

  • $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. cute, quick, does exactly what it says. 🎀

rad2deg

$deg=rad2deg($rad);

Convert radians to degrees. the other direction, bestie. 🦋

turn2rad

$rad=turn2rad($turn);

Convert turns to radians. 🌸

rad2turn

$turn=rad2turn($rad);

Convert radians to turns. 💫

turn2deg

$deg=turn2deg($turn);

Convert turns to radians. (yes, that's what the page says — we report, we don't correct 💀)

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. going back in time but responsibly. ⏪

  • $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. main character energy, always moving forward. ⏩

  • $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()

that's it, that's the whole thing — no args, no notes, just vibes. 🫶

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. the reverse, obviously. 🎀

  • $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. she's just doing a little outfit change before the party. 🎀

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. same wrapper energy, different entry point. 💜

rise

($lst_rise, $lst_set) = rise($ra, $dec, $obslat, $el_limit);

💖 and that's where this part of the page wraps, bestie — more is coming, so don't go anywhere. ✨

Okay so next up we have the little function that hands you the rise and set times for a source. 🌅 It's giving very much "astronomy bestie checks the sky for you" energy.

It wants all of this from you:

  • $lst_rise, $lst_set — the rise and set time, in turns
  • $ra, $dec — RA and Dec of the source, in turns
  • $obslat — latitude of the observatory, in turns
  • $el_limit — elevation limit of the observatory, in turns, and 0 means horizontal

And what it gives back? 👀

  • It returns 'Circumpolar' if the source is circumpolar — she never sets, iconic, main character 💅
  • It returns undef if the source never rises at all — tragic, not a single appearance 😭

The math it's running on is this:

cos $z_limit = sin $obslat * sin $dec + cos $obslat * cos $dec
               * cos $HA

where:

  • $z_limit is the zenith angle limit that corresponds to $el_limit
  • $HA is the Hour Angle of the source
NOTE: For maximum accuracy, source coordinates should be precessed to the current date. No cap, if you skip this your accuracy is lowkey gonna suffer.

lst2mjd

Two ways to call her:

$mjd = lst2mjd($lmst, $dayno, $year, $longitude);
$mjd = lst2mjd($lmst, $dayno, $year, $longitude, $dUT1);

This one figures out the modified Julian day number that matches the local mean sidereal time $lmst at $longitude, on a given UT day number ($dayno). And unless you genuinely need high precision, you can just leave dUT1 out. Fr fr, it's optional. 🙈

The required inputs are:

  • $lmst — the local mean sidereal time (turns)
  • $dayno — the UT day of year you're converting for
  • $year — the year you're converting for
  • $longitude — the longitude of the observatory (turns)
  • $dUT1 — the difference between UTC and UT1 (UT1 = UTC + dUT1), in seconds
  • $mjd — the modified Julian day corresponding to $lmst on $dayno

month2str

$monthstr = month2str($month);
$longmonthstr = month2str($month,1);

Give her a month as a number 1..12, where 1 is January, and she gives you the name back. 🎀 Default behaviour is the 3-character version ('Jan', 'Feb', etc.) — but hit her with that second form and you get the whole full-length month name. Glow up. ✨

The required input is:

  • $month — the month in question, with 1 == January

mjd2weekday

$weekday = mjd2weekday($mjd);

Hand it an MJD, it hands you back the weekday. 0 ==> Monday. 🗓️

Careful bestie: it may not work for historical dates. Like, it's not gonna be reliable going way back, okay?

The input:

  • $mjd — modified Julian day (JD-2400000.5)

mjd2weekdaystr

$weekdaystr = mjd2weekdaystr($mjd);

Same vibe as the one above, except you get the actual name of the weekday instead of a number. Cute. 🌸

Same warning tho: may not work for historical dates.

The input:

  • $mjd — modified Julian day (JD-2400000.5)

str2month

$month = month2str($monthstr);

Give her the name of a month (in English) and she returns an integer between 1 and 12, where 1 is January. Full month names are fine, 3-character abbreviations are fine — she's flexible like that. 🦋

Not supported: minimum matching. So like "Marc" is not gonna work. Don't try it. 💀

The required input is:

  • $month — name of the month ('Jan', 'January', 'Feb', 'February' etc.)

And that's the whole page, bestie. 🫶 This one came straight out of perl v5.38.2, dated 2024-05-15, filed under Astro::Time(3pm) — she's been around, she's still serving, and she's absolutely gonna keep your orbital math looking flawless. Periodt. 👑🌈

📦 where this page comes from