view release on metacpan or  search on metacpan

doc/astronomical-notes.pod  view on Meta::CPAN

Then we apply both Earth's spin (360.9856 degrees per day) and 
the movement of a VHS ("virtual homocinetic sun"), that is, 0.9856 degrees per
day. The result is a combined rotational speed of 360 degrees per day, that is,
15 degrees per hour. And sunset happens when the VHS reaches the target altitude.

So on 4th Jan, the angle between noon and sunset is 59.9746° (59° 58' 28"). 
We need 3.9983 hours (3 h 59 mn 53 s) to run this angle and the sunset for
the VHS occurs at 16:04:50.

=head2 Implementation of Precise Algorithm

With the precise algorithm, we keep separate Earth's spin (360.9856 degrees
per day) and the Sun's rotational speed around Earth. In addition, this
rotational speed is the real speed, spanning from 0.9552 to 1.0166 
degree per day.

First iteration. We start from the true solar noon at 12:04:56 and we apply Earth's spin
(15.04107 degrees per hour). The first result, a very approximate one, is the
instant when Earth's spin brings the Sun to the target altitude.
On 4th Jan, this first value is 16:04:11.

For iteration 2, we determine the virtual solar noon that corresponds to the
Sun's position at 16:04:11. This virtual solar noon occurs at 12:05:01.
With this reference, we apply the Earth's rotation and we get a second
value for sunset, 16:04:23 (16.0731615074431 in decimal hours).

For iteration 3, we determine the virtual solar noon 
that corresponds to the Sun's position at 16:04:23. This new virtual solar
noon occurs at 12:05:01. And one more time we apply the Earth's rotation
and we obtain a third value for sunset, 16:04:23, differing from the previous
value by less than a second: 16.0731642391519 instead of 16.0731615074431.
The difference is 2,73e-6 hours, that is 9 ms, so we leave the computation loop.

This is one way to describe the algorithm: the Sun reaches by anticipation
its position in the evening and stays there, waiting for the spinning Earth
to spin until the Sun disappears below the horizon. Another way to describe
the algorithm is as follows:

During iteration 2, between the real solar noon 12:04:56 and the time given
by iteration 1, 16:04:11, the Sun orbitates with its real speed of 1.0166 degree per day
while the Earth spins at 360.9856 degrees per day.
Then, at 16:04:11, the Sun freezes in its track and after that, we adjust the
position with only the Earth's spin to reach the required altitude.
And the sunset occurs at 16:04:23.

During iteration 3, between the real solar noon 12:04:56 and the time given
by iteration 2, 16:04:23, the Sun orbitates with its real speed 1.0166 degree per day.
Then at 16:04:23, it freezes, letting the Earth continue its spin. And sunset 
happens 9 milliseconds later, at 16:04:23. So, there are 3 h 59 mn 27 s when we use
the Sun's real orbital speed and 9 milliseconds when we use an obviously wrong orbital
speed. In the end, it is better than the basic algorithm, which uses an approximate
but still wrong orbital speed, but for the whole span of 3 h, 59 mn and 57 s.

=head2 What Happened in Spring 2020?

Let us look a bit farther into  the past. In January 2019, I published
version  0.98   of  L<Astro::Sunrise>,  with  the   precise  algorithm
implemented as explained in the  preceding paragraph. For test data, I
did not know how to cross-check  with authoritative sources, so I just
checked  they  looked plausible  and  that  the iterative  computation
stopped after  a few iterations. At  this time, I did  not synchronise
L<DateTime::Event::Sunrise> with L<Astro::Sunrise>, because it was not
the proper time yet.

Then in  April 2020, a user  created an RT ticket,  explaining that he
had   compared  the   results   of  L<DateTime::Event::Sunrise>   with
authoritative websites and  that the results were  not precise enough.
Of course  the results were  not precise,  I had not  yet synchronised
L<DateTime::Event::Sunrise>  with L<Astro::Sunrise>.  Yet this  ticket
gave  me two  things: first,  a  website which  would provide  precise
day-after-day computations of sunrise, sunset and real solar noon, and
second a few round tuits to upgrade L<DateTime::Event::Sunrise> to the
same level as L<Astro::Sunrise>, with real tests values.

There   was   a   glitch.    The   precise   algorithm   copied   from
L<Astro::Sunrise> and  the test  data from the  NOAA website  were not
matching. After  tweaking the algorithm  and asking for advice  on the
DateTime mailing-list
(L<https://www.nntp.perl.org/group/perl.datetime/2020/06/msg8241.html>),
I had to  admit that using a 15-degree-per-hour spin  speed was giving
better results  than the  normal 15.04107-degree-per-hour value.  So I
coded the  C<15> value in L<DateTime::Event::Sunrise>  and I published
the module.

=head3 What Went Wrong?

I still think my explanations of  the precise algorithm are correct. I
think that  the error  lies in the  implementation of  this algorithm.
Using as an example the values above, during iteration 2 we should use
the  Sun  at its  16:04:11  position  and  not moving.  Without  being
certain, I think that actually, the program computes the virtual solar
noon for 16:04:11,  which is 12:05:01 and that after  that it uses the
Sun at its 12:05:01 position.

How can I check  this hypothesis? I need to "create"  a new fixed star
at the 16:04:11 position of the Sun. And  I do not know how to do that
in  Stellarium. A  few  months  later, I  read  the documentation  for
Stellarium 0.20.1-1.  In chapter  13, I  found that  the user  can add
unofficial  novas  to   the  novas  coming  from   the  official  star
catalogues. This  would answer  my need.  The problem  is that  I have
Stellarium 0.18.0 and that I did  not succeed in creating "my" nova in
this  version. So  for  the  moment, it  is  impossible  to check  the
implementation of the precise algorithm.

=head1 More About The Parameters

Below, I give some detailed explanations about the parameter used when
calling the module's functions. These explanations would have been too 
long if they had been included in the module's POD and a casual doc reader
would have been drowned in a deluge of informations.

=head2 Choosing The Algorithm, C<precise> Parameter

Q: When should I choose the precise algorithm?

A: The short answer is "Never". The long answer is the following:

=over 4

=item *