view release on metacpan or  search on metacpan

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

-*- encoding: utf-8; indent-tabs-mode:nil -*-

=encoding utf-8

=head1 Document Status

This text is published under the I<Creative Commons> license
CC-BY-ND.

Copyright (c) 2017-2021 Jean Forget. All rights reserved.

I must precise that I am not a professional astronomer. The text
below may contain errors, be aware of this. I will not be held
responsible for any consequences of your reading of this text.
The "NO WARRANTY" paragraphs from the GPL and the Artistic License
apply not only to Perl code, but also to English (and French)
texts.

The text is often (but irregularly) updated on Github. There are
a French version and an English version. Since I am more at ease
discussing astronomical subjects in French, the English version
will lag behind the French one.

This text is an integral part of the module's distribution package.
So you can read it on web pages generated from CPAN
(for example L<https://metacpan.org>).
But it is not used during the module installation process.
So, I guess it will not appear in C<.deb> or C<.rpm> packages.

Although this text  is stored in the  L<Astro::Sunrise> repository, it
also  documents the  L<DateTime::Event::Sunrise> module,  which has  a
very  similar core  (astronomical computations)  and a  different API.
Since both  modules move at different  speeds, it may happen  that the
text you  are reading is  not synchronised with  the L<Astro::Sunrise>
module.

=head1 Why This Text? For Whom?

The main purpose of this text is to explain how the sunrises
and sunsets are computed. These explanations are much too long
to be included into the module's POD section.

=head2 For Whom? For My Teddy Bear

Have you read
L<brian's Guide to Solving Any Perl Problem|http://www252.pair.com/~comdog/brian's_guide.pod>?
While most advices deal with debugging Perl code, a few advices have
a broader scope and apply to any intellectual problem.
One of these advices consists in "talking to the teddy-bear".
And do not pretend to talk while just forming sentences in your
mind. You must really talk in a clear voice in front of your
teddy-bear, with syntactically correct sentences.
Actually, in the present case, the topic is so big that I skipped to the next level and
I prefer writing (on GitHub) for my teddy-bear.

I write this text to tell my teddy-bear which problems I have
encountered while maintaining this module and how I fixed them.
But mainly, I write this to give him a detailed description of the
precise iterative algorithm, because 
L<Paul Schlyter's explanations|https://www.stjarnhimlen.se/comp/riset.html#3>
are not detailed enough for my taste and there is no
compilable source available to check this algorithm (unlike the 
L<simple version without iteration|https://www.stjarnhimlen.se/comp/sunriset.c>).

=head2 For Whom? For The Next Module Maintainer

Actually, my teddy-bear understands French, so the present
English version is not for him.
The second person for whom I write is the next module maintainer. I have read
L<Neil Bowers' message|http://codeverge.com/perl.module-authors/the-module-authors-pledge/744969>
about I<the module authors pledge>. I agree with him and I declare that
should I stop maintaining my modules for whatever reason, I accept that 
any volunteer can take charge of them.

What Neil did not explain, is that the new maintainer must obey a few
criteria and must have three available resources to take over a module maintenance:
be competent in Perl programming, have enough available time to work on
the module and be enthusiastic enough to get around to it.

In the case of astronomical module, the competence in Perl programming is
not enough, you must also be competent in astronomy. So, if you think you might
maintain this module, first read the present text. If you understand why I bother
about such and such question, if you can follow my train of thought without being
lost, then you are competent enough. If you think I am playing
L<Captain Obvious|https://tvtropes.org/pmwiki/pmwiki.php/Main/CaptainObvious>
and if you have instant answers to my questions, then you are the ideal
person that could maintain this module. If you do not understand what all
this is about, and if sines and cosines put you off, do not consider

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

=back

Actually, in both cases, these are approximate values for variable phenomena.
The radius of the sun disk varies between 0.271° (or 16'16") on 3rd January, when
the sun is closest from the Earth, and 0.262° (or 15'44") on 3rd July, when it is
farthest from the Earth.

And the deviation caused by refraction is highly dependent on the temperature
profile in the atmosphere, therefore dependent on the current weather.

You can refine the computation by using value -0.583 for the C<alt> parameter and
giving a true value to the C<upper_limb>) parameter (usually 1). In this case, the
radius of the sun disk is computed anew for each day. On the other hand, there is
no way within the module to refine the computation of the refraction. The answer
can only come from outside the module computing sunrises and sunsets.

Q: So using a parameter C<alt> with -0.583 and a parameter C<upper_limb> with 0 is stupid?

A: No, it is just unusual. As stated by Paul Schlyter
L<in his website|http://www.stjarnhimlen.se/comp/riset.html#2>, 
the Swedish national almanacs define sunrise and sunset as the instants when the I<centre>
of the sun disk reaches the optical horizon, not the instants when the I<upper limb> of
the sun disk reaches the optical horizon.

Q: On the other hand, using a parameter C<alt> with -0.833 and a parameter C<upper_limb> with 1 is stupid?

A: I would say neither "stupid" nor "unusual", but "suspicious". Actually, the usual -0.833 value comes from
three elements:

=over 4

=item * 0 for the position of the observer relative to the surrounding landscape,

=item * -0.583° or -35' for the refraction,

=item * -0.25° or -15' for the radius of the solar disk, or 0 if you give a true value to C<upper_limb>.

=back

But if you are at the top of a 60-meter tower, the horizon line no longer
coincides with the horizontal plane, but with a cone making a 0.25° angle with the
horizontal direction. In this case, we have:

=over 4

=item * -0.25° for the position of the observer relative to the surrounding landscape,

=item * -0.583° for the refraction,

=item * 0° for the radius of the solar disk if you give a true value to C<upper_limb>, or -0.25° for a false value.

=back

So this parameter combination is valid, but it is suspicious because it does not correspond
to a usual and mundane situation.

Q: After your explanation about the C<precise> parameter, is there a significant
difference between C<< alt => -0.833, upper_limb => 0 >> and
C<< alt => -0.583, upper_limb => 1 >>?

A: You guessed, it, there is nearly no difference. The example I will take is sunset
at Fairbanks on 3rd January 2020. I take 3rd January because it is the time of the year
when the sun is at its largest. According to Stellarium, the diameter is 32'32", so the
radius is 16'16". And I take Fairbanks, because near a polar circle, the course of the sun
at sunset is much shallower than near the equator. So, for 
C<< alt => -0.833, upper_limb => 0 >> the sunset occurs when the
center of the sun dist is at -50' and for 
C<< alt => -0.583, upper_limb => 1 >> it occurs when the center of the sun disk is at -51'16".
Stellarium gives 15:59:12 in the first case and 15:59:37 in the second case.
A meagre 25-second difference.

On the other hand, let us move a few hundred kilometers to the North,
to 68°01'46" N, 147°42'59" W, beyond the polar circle. The computation with 
C<< alt => -0.833, upper_limb => 0 >> shows that the sun
stays below the horizon and neither rises nor sets, while the computation with
C<< alt => -0.583, upper_limb => 1 >> gives a sunrise at 12:45:11 and a
sunset at 13:05:53.

=head2 C<year> Parameter

Q: Why does L<Astro::Sunrise> need the year to compute sunrise and sunset?
I have seen an algorithm which only needs the month and the day.

A: Let us compute the sunset at the Greenwich observatory at the end
of February and at the beginning of March. The times are respectively:

  .     26/02     27/02     28/02     29/02     01/03     02/03     03/03
  2015 17:46:17  17:35:43  17:37:29            17:39:15  17:41:01  17:42:47
  2016 17:47:36  17:35:17  17:37:03  17:38:49  17:40:35  17:42:21  17:44:06
  2017 17:47:11  17:36:37  17:38:24            17:40:10  17:41:55  17:43:41
  2018 17:46:45  17:36:12  17:37:58            17:39:44  17:41:30  17:43:15
  2019 17:46:20  17:35:46  17:37:32            17:39:18  17:41:04  17:42:49
  2020 17:47:39  17:35:20  17:37:06  17:38:52  17:40:38  17:42:24  17:44:09
  2021 17:47:13  17:36:40  17:38:26            17:40:12  17:41:58  17:43:44
  2022 17:46:48  17:36:14  17:38:01            17:39:47  17:41:32  17:43:18
  2023 17:46:23  17:35:48  17:37:35            17:39:21  17:41:07  17:42:52

As you can see in this table, when we go forward by 365 days, the sunset
time decreases by about 25 seconds. When we go forward by 366 days, the
sunset time increases by about 1 mn 20 s. And if we go forward by one
civil year, the sunset time seesaws. So, for the 28th of February,
which result should your yearless algorithm give? 17:37:03? Or 17:38:26?

Q: That means that my algorithm is bad.

A: No. If you want to know the precise instant when the Sun disappear
from our field of view, your algorithm is wrong indeed. On the other hand; if you are only interested
in the level of light, your algorithm is OK. I know a person who uses
a yearless algorithm to activate automated lights in his living room.
For him, turning on the lights at 17:37:03 or 17:38:26 has no importance.
Under our latitudes, the light variation in two minutes is negligible.
Actually, the weather may have a much important effect. If you have a clear
sky or a heavy layer of black thunder clouds, you will have to light
later or sooner than the computed time.

Q: By the way, you seem to say that a yearless algorithm would be sufficient
to compute twilight times? So why use an algorithm requiring the year?

A: Firstly, because the basic algorithm was already coded and a slightly worse
algorithm would be redundant. Then because I do not know which licenses
apply to these yearless algorithms, while at the same time, Paul Schlyter's
algorithm is in the public domain.

Q: Another thing, how did you get the seconds in the table? L<Astro::Sunrise>
does not provide the seconds.

A: Because I have used L<DateTime::Event::Sunrise> instead of L<Astro::Sunrise>,
which produces L<DateTime> objects, complete with seconds.

Q: Could we modify L<Astro::Sunrise> to give C<"hh:mm:ss"> results instead
of C<"hh:mm">?

A: We could. But would this precision be meaningful? According to Paul 
Schlyter, the algorithm precision is about 1 or 2 minutes, except at the
beginning and the end of the Polar Day period when the precision is much
worse. So it is not worth adding the seconds to the results produced by
L<Astro::Sunrise>.

Q: And in the discussion above, why did you keep the seconds, if they
are not significant?

A: Because I think that if there is an error, it will be the same error
for similar dates, that is, end-February and beg-March within a decade.
For instance, we may have a S<+45 s> bias on 2015-02-28 and a S<-50 s>
bias on 2015-10-28 and on 2050-02-28, but for all the dates similar
to 2015-02-28 in both a YYYY fashion and a MM-DD fashion, the bias will
be approximately the same as 2015-02-28. Maybe S<+43 s> or S<+46 s> instead
of S<+45 s>, but surely not S<-50 s>. So I can make comparisons with a
granularity of 1 second. By the way, the bias values I gave above are
complete guesses, they are not the result of a precise computation.

TO BE COMPLETED

=head1 Annex: Politically Correct Explanations

=head2 Policitally Correct Analemma

First, let us deal with observers located north of the Arctic Polar Circle.
They just have to know that the analemma and the pseudo-analemma cross the horizon
and are partly hidden by the ground. The hidden part, more or less important depending
on the observer's latitude, corresponds to the year period when the I<polar night> is
in effect. You can find an example of the arctic pseudo-analemma in the 
paragraph about the C<precise> parameter.

For observers between the Tropic of Capricorn and the Antarctic Polar Circle,
this is more strange. True solar noon corresponds to a right ascension of 0°,
when the Sun is exactly northward. As the observer must face north instead of south,
he sees the sun crossing the sky in the direction E → N → W, that is, in the 
direction of I<decreasing> right ascension values. So, when the true solar noon is
ahead of the mean solar noon, the point on the analemma will be to the left of the Y-axis,
and when the true solar noon is later than the mean solar noon, the point on the analemma
will be to the right of the Y-axis.

On the same time, for the pseudo-analemma, there is no reason to change the way
the time of day is represented on the abscisses, that is, left to right. Therefore,
the analemma and the pseudo-analemma will be more or less superposable, without
an intervening symmetry. 

For observer to the south of the Antarctic Polar Circle, the situation is the same,
with the additional provision that the analemma and the pseudo-analemma will be partly
hidden by the ground.

And what about observers located between both tropics? An observer facing south
cannot see the whole analemma, he would miss the part around 21st of June,
which is located behind his back. And if he faces north, he will miss the
part around 21st of December. What to do then? Just lie on the ground. If the 
observer lies with the head to the north and the feet to the south, the observed
analemma will be similar to the curve seen by an observer north of the Tropic of Cancer.
If the observer lies with the head to the south and the feet to the north, the situation
will be similar to an observer on the south of the Tropic of Capricorn and facing north.

TO BE COMPLETED