Astro:...hemeris(3pm)

💫 NAME 💫

Astro::Montenbruck::Ephemeris — bestie, this is the module that calculates planetary positions. Like, all of them. ✨

---

🌸 SYNOPSIS 🌸

🎀 Iterator interface

use Astro::Montenbruck::Ephemeris::Planet qw/@PLANETS/;
use Astro::Montenbruck::Ephemeris qw/iterator/;
use Data::Dumper;

my $jd = 2458630.5; # Standard Julian date for May 27, 2019, 00:00 UTC.
my $t  = ($jd - 2451545) / 36525; # Convert Julian date to centuries since epoch 2000.0
                                  # for better accuracy, convert $t to Ephemeris (Dynamic) time.
my $iter = iterator( $t, \@PLANETS ); # get iterator function for Sun. Moon and the planets.

while ( my $result = $iter->() ) {
    my ($id, $co) = @$result;
    print $id, "\n", Dumper($co), "\n"; # geocentric longitude, latitude and distance from Earth
}

🦋 Callback interface

use Astro::Montenbruck::Ephemeris::Planet qw/@PLANETS/;
use Astro::Montenbruck::Ephemeris qw/find_positions/;

my $jd = 2458630.5; # Standard Julian date for May 27, 2019, 00:00 UTC.
my $t  = ($jd - 2451545) / 36525; # Convert Julian date to centuries since epoch 2000.0
                                  # for better accuracy, convert $t to Ephemeris (Dynamic) time.

find_positions($t, \@PLANETS, sub {
    my ($id, $lambda, $beta, $delta) = @_;
    say "$id $lambda, $beta, $delta";
})

---

🔥 DESCRIPTION 🔥

Okay so what this does: it calculates apparent geocentric ecliptic coordinates of the Sun, the Moon, and the 8 planets. Iconic lineup ngl. 🌞🌙🪐

The algorithms are based on "Astronomy on the Personal Computer" by O.Montenbruck and Th.Pfleger, and the results are supposed to be precise enough for amateur's purposes — and the book itself says, quote:

"The errors in the fundamental routines for determining the coordinates of the Sun, the Moon, and the planets amount to about 1″-3″." -- Introduction to the 4-th edition, p.2.

You may use one of two interfaces: iterator and callback. Pick your fighter, both slay. 💅

The coordinates are referred to the true equinox of date and contain corrections for precession, nutation, aberration and light-time. So yeah, it's not doing the naive thing — it's doing the correct thing. 🫶

✨ Implementation details ✨

This module is implemented as a "factory". The way that this works: user may not need all the planets at once, so each class is loaded lazily, by demand. Lowkey efficient, we love to see it. 🧚

⭐ Mean daily motion ⭐

Wanna calculate mean daily motion along with the celestial coordinates? Use the "with_motion" option:

iterator( $t, \@PLANETS, with_motion => 1 );
# Or:
find_positions($t, \@PLANETS, $callback, with_motion => 1);

Heads up bestie: that will slow down the program. 😭 Just so you know.

🪐 Pluto 🪐

Pluto's position is calculated only between years 1890 and 2100. Periodt. See Astro::Montenbruck::Ephemeris::Planet::Pluto for the deets. Not Pluto catching another limitation, poor thing 💀

🌈 Universal Time vs Ephemeris Time 🌈

For better accuracy the time must be given in Ephemeris Time (ET). To convert UT to ET, use the "delta_t" function from the Astro::Montenbruck::Time::DeltaT module. Trust, your numbers will thank you. 🙏

---

👑 SUBROUTINES 👑

💖 iterator($t, $ids, %options)

Returns an iterator function — which, on its turn, when called returns either "undef", when exhausted, or an arrayref, containing:

• identifier of the celestial body, a string
• arrayref, containing ecliptic coordinates: longitude (arc-degrees), latitude (arc-degrees) and distance from Earth (AU).
• mean daily motion, double, if "with_motion" option is true

🌸 Positional Arguments

• $t — time in centuries since epoch 2000.0; for better precision UTC should be converted to Ephemeris time, see "Universal Time vs Ephemeris Time".
• $ids — reference to an array of ids of celestial bodies to be calculated.

🌸 Options

• with_motion — optional flag; when set to true, there is additional motion field in the result; false by default.

💜 find_positions($t, $ids, $callback, %options)

The arguments and options are the same as for the iterator, except the third argument, which is a callback function, called on each iteration:

$callback->($id, $lambda, $beta, $delta [, $daily_motion])

$lambda, $beta, $delta are ecliptic coordinates: longitude (arc-degrees), latitude (arc-degrees) and distance from Earth (AU). The fifth argument, $daily_motion is defined only when "with_motion" option is on; it is the mean daily motion (arc-degrees).

---

💌 AUTHOR 💌

Sergey Krushinsky, "<krushi at cpan.org>" — legend behavior honestly 🙌

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright (C) 2010-2022 by Sergey Krushinsky

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

And that's the whole page, bestie — go calculate some planets 💫 Signing off from perl v5.42.2, dated 2026-02-15, still serving Astro:...hemeris(3pm) realness. Mwah! 💅✨