%% Part of Stellarium User Guide 0.20.4+
%% History:
%% 2020-12-17 New chapter.
%% !!!!!!!!!! Please ask GZ before editing this file. !!!!!!!!!!!!!!!


\newpage
\section{Calendars Plugin}
\label{sec:plugin:Calendars}
\sectionauthor*{Georg Zotti}



\subsection{Introduction}
\label{sec:plugin:Calendars:Introduction}

The calendar dates in the main program behave like most other astronomical software titles:

\begin{itemize}
\item Dates are given in the Gregorian calendar for all dates
  beginning with October 15, 1582.
\item All earlier dates are given in the Julian Calendar in its
  finalized form by \name{Augustus}. Historically, only dates
  beginning with March 1st, 4 A.D. coincide with historically recorded
  dates: the Roman priesthood messed up the 4-year count introduced by
  \name[Julius]{Caesar} and counted leap years every third
  year. \name{Augustus} decreed to omit leap days from 12~B.C. to
  4~A.D. to move the seasons to where \name[Julius]{Caesar} had placed
  them.
\item Given the errors in the Julian calendar, simulation in early
  prehistory will provide non-intuitive calendar dates for the
  seasons' beginnings.
\item Astronomical counting of years includes a year zero and negative
  years. Historical calendars don't have a year zero. 1~A.D. is
  preceded by 1~B.C. Therefore a negative year in Stellarium may look
  uncommon to historians who may think Stellarium is one year off.
\end{itemize}

\noindent Since earliest times people all over the world have observed the sky
and used its phenomena to structure their lives, agree on future events
(``we shall meet here again and exchange goods at the third Full Moon from now''),
record and measure time.
Over millennia, various systematic calendars evolved. A classic and often-cited
presentation of calendars from the pre-computer era is still the
monumental work by Ginzel (\citeyear{Ginzel:ChronologieI, Ginzel:ChronologieII,
  Ginzel:ChronologieIII}).  The next challenge was then to describe the
systematic of these algorithmically and make them available for
computer programs.  \citet{Reingold-Dershowitz:2018} have presented a
modern masterpiece of this kind and are our preferred source of
algorithms. This plugin\newFeature{0.20.4} will evolve over the next
time to bring a good sample of calendars into Stellarium.

In the configuration panel you can select which calendars you want to
display in the lower right corner of the screen, and you can also directly
interact with some of them.

The calendars displayed in this plugin come with their own
logic. Historically, when a calendar was introduced, dates which
precede its starting point (era) were of little interest to its users,
therefore if a date bears negative years (or negative units of its
largest component) those dates may not be useful.

Note that in some calendars the day did not begin at midnight, but for
example at sunrise, sunset, or dawn. This cannot be reflected in this
plugin. Dates should be correct at noon, and may be one day off
dependent on these aspects.\footnote{At the current point of
  implementation I cannot exclude further errors! The plugin
  reproduces the given sample dates, but we cannot give any guarantee
  about the accuracy of historical dates. If you are more familiar
  with any of the non-European calendars, you are invited to identify
  errors or at least additions to this documentation, e.g. variants to
  the schemes used.}

\subsection{The Calendars}
\subsubsection{Lunisolar European calendars}
\begin{description}
\item[Julian] \name[Julius]{Caesar} introduced this calendar, advised
  by the Egyptian astronomer \name{Sosigenes}. Every 4th year is a
  leap year of 366 instead of 365 days, yielding a mean length of the
  year of 365.25 days.

  In contrast to the default calendar display of Stellarium, this
  implementation utilizes historical year counting, i.e., has no year
  zero. Years are marked A.D. or B.C., respectively.  The omission of
  year zero makes negative leap years break the simple 4-year
  count. Now they are 1~B.C., 5~B.C., 9~B.C.\ etc. However, note that
  before 8~A.D.\ leap years are just counted proleptic, but the Romans
  did not keep the leap years commanded by \name[Julius]{Caesar} until
  \name{Augustus} put things back in order. This means, displayed
  dates before 8~A.D.\ may be off by up to 3 days from historical
  accounts written by contemporaries.
\item[Gregorian] This implementation acts like Stellarium with respect
  to year counting and counts signed negative and positive years, with a year
  zero between them. It shows dates in a \emph{Proleptic Gregorian}
  calendar for dates before October 15, 1582. Given its improved rules
  for leap years which provide a mean length of the year of 365.2425 days,
  it keeps the seasons' beginnings closer to the
  commonly known dates, at least for many more centuries in the past
  than the Julian calendar commonly used by historians.
\item[Revised Julian Calendar] (also named \textbf{Milankovi\'c
  Calendar})\newFeature{0.22.0} In 1923, the Serbian scientist
  \name[Milutin]{Milankovi\'c} (1879--1958) proposed a calendar which
  should overcome the then 13-day calendar gap between the Eastern
  European Orthodox churches who still adhered to the Julian calendar
  and the rest of the world which followed the Gregorian calendar.  It
  amends the 4-year Julian leap year cycle by omitting century years
  except for those where division by 900 leaves a remainder of 200 or
  600.  Therefore the mean length of the year is 365.242\={2} days, 24
  seconds less than the Gregorian and within 2 seconds of the correct
  length of the mean tropical year.  For a synchronisation with the
  Gregorian, October 1-13 1923 were omitted.  Between March 1600 and
  February 2800 the calendar dates are identical to those in the
  Gregorian calendar.  The calendar was adopted by several but not all
  Eastern Orthodox churches, although date of Easter is still computed
  according to the Julian calendar\footnote{More details can be found on
    \url{https://en.wikipedia.org/wiki/Revised_Julian_calendar}}.

  In historical context giving dates in the Revised Julian calendar
  for years before the dates of religious festivals were defined in
  the calendar makes no sense. Its idea was to have a continuous
  calendar as it was in use at the concile of Nicaea in
  A.D.325. Therefore dates before A.D.325 are displayed like in the
  traditional Julian calendar.
\item[ISO Week] The International Standards Organization describes
  weeks in the Gregorian calendar from Monday (Day 1) to Sunday (Day
  7). Week 1 of each year contains the first Thursday of the
  year. Years may have a week 53, where the last days already belong
  to the next Gregorian year.
\item[Icelandic calendar] Since 1700, this counts weeks in summer and
  winter seasons, 12 months of 30 days with a few extra days and the
  occasional leap week after the third month of summer. Year numbers
  concur with the Gregorian, but start with summer in late April.
\item[Roman calendar] This presents the Roman way of writing calendar
  dates in the Julian calendar and provides dates \emph{ab urbe condita} (A.U.C.).
\item[Olympic calendar] Another way to write the years in the Julian
  calendar uses the Greek Olympiads, a 4-year cycle starting in 776
  B.C.E. The Olympic games of antiquity were held in year 1 of each cycle.
\end{description}

\subsubsection{Near Eastern Solar calendars}
Several calendars with 12 months of 30 days plus 5 (6 for leap years
in some calendars) \emph{epagomenae} days, with different \emph{calendar eras}.
\begin{description}
\item[Egyptian] A 365 day year without leap days. Following the
  tradition of \name{Ptolemy}, we use the \emph{era of Nabonassar}.
\item[Armenian] also has no leap days.
\item[Zoroastrian] also has no leap days. This uses different names
  for each day of the month and for each \emph{epagomenae} day. Month
  names are from \citet[\S69]{Ginzel:ChronologieI} with
  transliteration adapted to \citet{Reingold-Dershowitz:2018}.
\item[Coptic] uses Month names derived from the Egyptian calendar, but observes
  leap years every 4th year. Its \emph{era martyrum} is also called
  \emph{Diocletian era}.
%\item[Ethiopic] is Parallel to the Coptic calendar, just with different
%  year numbers, counted from the \emph{ethiopic era of mercy}.
\item[Ethiopic] like the Coptic calendar, just with different
  year numbers, counted from the \emph{ethiopic era of mercy}.
\item[Persian] a Solar calendar adopted in 1925,\newFeature{0.21.0}
  but based on the earlier Jal\=al\=\i\ calendar of the 11th century
  A.D. Years begin at the Vernal equinox (\emph{nowruz}) and follow a
  complicated leap year cycle of 2820 years. Days begin at midnight
  (zone time). An identical calendar with different month names was
  adopted in Afghanistan in 1957.

  Stellarium provides both versions:\newFeature{0.22.0} the algorithmic version and the
  astronomically specified one. They occasionally deviate from each
  other by 1 day.
\item[Bahá’í] is a Solar calendar with years beginning on the day of
  Vernal equinox. \newFeature{1.2} In the algorithmic version used in
  the West, March 21 in the Gregorian calendar was used, but the
  astronomical version used since 2015 uses Tehran as reference
  location.  Days begin at sunset. The calendar uses a 7-day week but
  is else based on cycles of the number 19: 19 named months of 19
  named days plus 4-5 additional days after month 18. In addition,
  years are structured in named 19-years (\emph{Vā\d{h}id}, ``unity'') and
  numbered $19^2=361$-years (\emph{Kull-i-shay}) cycles.
\end{description}

\subsubsection{Near Eastern calendars}
Several more calendars\newFeature{0.21.0} have been worked out in algorithmic forms:
\begin{description}
\item[Islamic] is a strict Lunar calendar without observance of
  seasons. Days begin at sunset, but we cannot currently show
  this. The date should be correct at Noon. The week begins on
  Sunday. Note that this algorithmic solution may deviate from the
  dates given by religious authorities on basis of observation.
\item[Hebrew] is a Lunisolar calendar with strict Lunar months, but
  adherence to the seasons. It has 12 or 13 months, and 353-355 or
  383-385 days per year. The algorithmic form was introduced in the
  mid-4th century A.D.
\end{description}


\subsubsection{Asian calendars}
\begin{description}
\item[Old Hindu Solar] used before about 1100 A.D. The implementation
  follows the (First) \emph{\=Arya Siddh\=anta} of \=Aryabha\d{t}a
  (499 C.E.), as amended by Lalla (circa 720--790 C.E.).  The year is
  split into 12 months (\emph{saura}) of equal length.  Days begin
  with sunrise, simplified as 6~am. Years are counted as \emph{elapsed years} (starting at 0) from the
  \emph{Kali Yuga} (Iron Age) epoch (Feb. 18., 3102~B.C. jul.).
\item[Old Hindu Lunisolar] used before about 1100~A.D. 
  This implementation shows the south-Indian method 
  with months starting at New Moon (\emph{am\=anta} scheme). 
  (In the north, the \emph{p\=ur\d{n}im\=anta} scheme describes months 
  starting with Full Moon. There are also some local differences.) 
  It also shows the K.Y. day count (\emph{aharga\d{n}a}), i.e., days elapsed since the K.Y. epoch.
\item[New Hindu Solar and Lunisolar] This is the Hindu
  calendar\newFeature{0.22.0} from the \emph{S\=urya-Siddh\=anta}
  (ca.~1000~A.D.). It is based on epicyclical motions of the Sun and
  Moon around the Earth. While still an approximation, this provides
  more accurate models of the motions at cost of much more complicated
  computation.  The Solar month begins when the Sun enters a sign on
  the \indexterm[zodiac!sidereal]{Sidereal Zodiac}. Months are
  therefore 29 to 32 days long. Solar days begin at sunrise, and the
  zodiacal position of the sun at sunrise in Ujjain, India, decides on
  the date.
  %
  Years given for the Solar calendar are counted from the \emph{Saka}
  era (A.D.~78).
  
  The lunar month name is determined by the (first) zodiacal sign
  entered by the sun during the month. When no sign is entered, the
  month is ``leap'' (\emph{adhika}) and named after the following
  month. When a Solar month passes without a New Moon, a lunar month
  can also be skipped (\emph{kshaya}).  The Lunisolar year has 12 or
  13 months, of which up to 2 can be leap and one skipped!

  A lunar day varies in length from 21.5 to 26.2 hours, and therefore
  may occasionally have to be repeated (here the second day is the
  leap day or \emph{adhika}), or skipped.

  Years are given in the \emph{Vikrama era} which began in
  58~B.C. Both months schemes share the same 12 names.

  Also this calendar is shown in the \emph{am\=anta} scheme, i.e.,
  months start at New Moon. There are again several local variants,
  and of course a longitude difference to the reference location may
  also lead to deviations.

  In addition to the New Hindu Lunisolar date, the Hindu \emph{panchang} is shown, a 5-part description of the day consisting of
  \begin{description}
  \item[Tithi] (lunar day)
  \item[Weekday]
  \item[Nak\d{s}atra] the part of the ecliptic the Moon is in at time of sunrise (in Ujjain).
  \item[Yoga] a cycle of 27 names resulting from the ``addition'' of
    Solar and Lunar longitudes.\footnote{For technical reasons this
      is currently shown for midnight UTC. It is currently unclear if
      \emph{yoga} should be given for the time of sunrise or for the
      current moment.}
  \item[Kara\d{n}a] a count of 60 lunar half-days resulting in 11
    names. The \emph{kara\d{n}a} at time of sunrise (in Ujjain)
    governs the \emph{kara\d{n}a} for the day \footnote{Again, this is
      unconfirmed. If you know better, please tell us!}.
  \end{description}
  
\item[Hindu Astronomical Solar and Lunisolar] These are similar to the
  New Hindu calendars,\newFeature{0.22.0} but with even more accurate
  positional computations from the \emph{S\=urya-Siddh\=anta} for
  Solar and Lunar positions.
\item[Tibetan calendar] is actually only one of several calendars%
  \newFeature{0.22.0} used in Tibet. We show the date in the official
  \emph{Phuglugs} (or \emph{Phug-pa}, \emph{Phukluk}) version of the
  \emph{K\=alacakra} calendar, derived from the \emph{K\=alacakra
    Tantra} which was translated from Sanskrit to Tibetan in the 11th
  century, and has been sanctioned by the Dalai Lama. It is similar to
  the Hindu Lunisolar calendar, but has also regional variants where
  astronomical events are computed in local time. In Tibet, the actual
  calendar is issued only annually (after empirical corrections) by
  the Tibetan School for Astro and Medicine and may diverge from the
  calendar shown here.

  Months are 29 or 30 days long and numbered 1 to 12. Leap months
  precede their ``regular'' counterparts but else have the same name.

  Years are counted from the date of ascension of the first Yarlung
  king, \name[Nyatri]{Tsenpo}, in 128~B.C. (We write ``A.T.'' for Anno
  Tibetorum.) However, it is more common to designate years in a cycle
  of 60 years, with 5 elements which label two consecutive years which
  are further named ``male'' and ``female'', and a parallel cycle of
  12 animal totems. This cycle has been synchronized with the similar
  Chinese 60-years cycle.
  
\item[Balinese Pawukon] is a 10-part sequence of day names with cycle
  lengths of 2 to 10, which can also be written as numbers or
  symbols. Some numbers repeat in simple cycles, while others follow
  more complicated rules. A full cycle takes 210 days.  Due to space
  reasons this needs two lines on the display. Formatting may improve
  in later versions.
\end{description}

\subsubsection{Chinese calendars}\newFeature{1.2}
The Chinese calendar (and related Japanese, Korean and Vietnamese)
is a Lunisolar calendar based on astronomical events.
Days begin at midnight. Lunar months begin on the day of New Moon.
The position of the Sun along the Zodiac is given by Major (\emph{zh\={o}ngqì})
and Minor (\emph{jiéqì}) Solar Terms.

\begin{description}
\item[Chinese] The version here is the 1645 version. Earlier dates may be wrong.
  The calendar's location for astronomical computations is Beijing.
\item[Japanese] The same principles of the Chinese calendar have been
  followed since 1844, but with Tokyo as reference location. The years
  given are in the \emph{kigen} count (years from 660~BCE).
\item[Korean] Korea adopted the Gregorian calendar in 1896, but the
  older Chinese-based calendar is still used for traditional
  purposes. The reference location for computing Solar longitudes and
  lunar phases is Seoul City Hall. Years are counted in the Danki
  system starting in 2333~BCE.
\item[Vietnamese] From 1813-1967 the Chinese calendar was used
  directly. The currently used traditional calendar parallels the
  Chinese, but with Saigon as reference location. Years are not counted, only named.
  It also seems that Solar terms are not used.
\end{description}

\subsubsection{Mesoamerican calendars}
\begin{description}
\item[Maya Long Count] is a 5-part sequence of numbers, conventionally 
  written with dot separators. Just like most
  modern people write numbers in the decimal system (base 10), and the
  Mesopotamians developed a scheme with base 60 still used today for
  angular and temporal minutes and seconds, the Maya used base 20 as their
  unit. However, this count uses a mixed-base system. The lowest
  (rightmost) number (\emph{kin}) runs from 0 to 19, the second-lowest
  (\emph{uinal}) from 0 to 17, the others from 0 to 19 again. It is
  assumed these lowest places of $18\times20=360$ days have been used
  to approximate the solar year, so that the third number from the
  right (\emph{tun}) increases about once per year. The higher places
  are called \emph{katun} and \emph{baktun}. Most scientists agree
  that the zero point of the long count corresponds to Monday,
  September 6, 3114 B.C. (Julian), but in many sources dates in the
  proleptic Gregorian calendar are listed, where this date is given as
  August 11, -3113. This plugin finally allows the use of both
  systems, and of Long Count dates directly.

  In December of 2012 some people were afraid that the switchover from
  \emph{baktun} 12 to 13 (something which occurs about every 400
  years) would cause Armageddon, just as other people prefer to be
  afraid of turns of centuries or millennia of the Christian year
  count.
\item[Maya Haab] is a calendar of 18 ``months'' of 20 days each
  (counted 1 to 20), plus 5 days (\emph{Uayeb}) at the end, providing
  ``years'' of 365 days. Years are not counted, but you can use
  buttons in the calendar interface to move forth and back to the
  previous or next, respectively, day with the same Haab name.
\item[Maya Tzolkin] is described as ritual calendar consisting of two
  cycles with 13 day numbers (1 to 13) and 20 names. Each day both
  counters are advanced. Date names repeat after 260 days. Usually
  Haab and Tzolkin calendars were both used to define a unique date
  which repeats only after a \emph{calendar round} of 52 Haab years,
  corresponding to 73 Tzolkin cycles.
\item[Aztec Xihuitl] is similar to the Maya Haab, consisting of 18
  ``months'' of 20 days, plus 5 \emph{nemontemi} (worthless
  days). Days are counted from 1 to 20. The Aztecs may have used
  intercalation, but details have been lost. The correlation in use
  here is based on the recorded Aztec date of the fall of their empire
  to \name[Hern\'an]{Cort\'es} in 1521 and should provide correct dates in the
  early 16th century.
\item[Aztec Tonalpohualli] is similar in structure to the Mayan
  Tzolkin. Also an Aztec date is usually given by both systems.
\end{description}

\subsubsection{French Revolution calendar}
The French Revolution of 1789 brought also a calendar reform. After a
few years with different year count only, a new calendar was
introduced effective on November 24, 1793 (4. Frimaire, II).\newFeature{0.22.0} This was
based on an astronomical determination of the autumnal equinox at
Paris, which marked the start of the years.

The calendar has 12 months of $3\times 10$ days (\emph{d\'ecades}), plus
5 (in leap years: 6) extra days at the end of the year. These 10-day
``weeks'' made it pretty unpopular. The months were given names that
alluded to the climate or vegetation.

In 1795,\newFeature{0.21.0} an arithmetic version was proposed which
got rid of the difficult astronomical computation with a leap year
scheme similar to the Gregorian. However, this version of the calendar
never came into use.  Stellarium also shows this calendar, which
may be off from the original by 1 day.

With the end of Gregorian year 1805, the calendar was abolished, but
re-introduced for a few days in May 1871.

\subsection{Scripting}

Advanced users who have the book at hand may find it useful
that\newFeature{0.22.0} almost all functions from
\citet{Reingold-Dershowitz:2018} are available as scripting functions
(as far as the implementation of the described calendars has
come). Whenever a location is needed, the current location is used, or
you can use a location from the location database by giving its name
like ``Vienna, Austria'' or ``Madrid, Western Europe''. This should
also work for user-specified locations. Take care to use a ``real''
name for the timezone, or specify an UTC based zone exactly like
``UTC+03:15'', else timezone will be read as zero. Full documentation
for this can be found at
\url{https://stellarium.org/doc/head/group__calendars.html}.

\subsection{Configuration Options}
\label{sec:plugin:Calendars:configuration}

The configuration dialog allows the selection of the calendars which are
of interest to you, and also provides direct interaction with the calendars.
The Mayan and Aztec calendars allow moving to the previous or next date of that respective name. 

\subsection*{Section \big[Calendars\big] in config.ini file}

Apart from changing settings using the plugin configuration dialog,
you can also edit the \file{config.ini} file to change
settings for the Calendars plugin -- just make it carefully!

{\footnotesize
\begin{longtable}{l@{\,}|@{\,}l@{\,}|@{\,}l@{\,}||@{\,}l@{\,}|@{\,}l@{\,}|@{\,}l}\toprule
  \emph{ID}                      &\emph{Type} & \emph{Default}  &
  \emph{ID}                      &\emph{Type} & \emph{Default}  \\\midrule
show                         &bool & true\\\midrule
flag\_text\_color\_override  &bool & false &
text\_color                  &R,G,B& \ccbox{0.5,0.5,0.7}  \\
show\_julian                 &bool & true&
show\_gregorian              &bool & true\\
show\_revised\_julian        &bool & false&
show\_iso                    &bool & true\\
show\_icelandic              &bool & false\\\midrule
show\_roman                  &bool & false&
show\_olympic                &bool & false\\\midrule
show\_egyptian               &bool & false\\
show\_armenian               &bool & false&
show\_zoroastrian            &bool & false\\
show\_coptic                 &bool & false&
show\_ethiopic               &bool & false\\
show\_persian\_astronomical  &bool & false&
show\_persian\_arithmetic    &bool & false\\
show\_bahai\_astronomical    &bool & false&
show\_bahai\_arithmetic      &bool & false\\\midrule
show\_islamic                &bool & true&
show\_hebrew                 &bool & true\\\midrule
show\_old\_hindu\_solar      &bool & false&
show\_old\_hindu\_lunar      &bool & false\\
show\_new\_hindu\_solar      &bool & true&
show\_new\_hindu\_lunar      &bool & true\\
show\_astro\_hindu\_solar    &bool & false&
show\_astro\_hindu\_lunar    &bool & false\\
show\_tibetan                &bool & false&
show\_balinese\_pawukon      &bool & false\\\midrule
show\_chinese                &bool & false&
show\_japanese               &bool & false\\
show\_korean                 &bool & false&
show\_vietnamese             &bool & false\\\midrule
show\_maya\_long\_count      &bool & true\\
show\_maya\_haab             &bool & false&
show\_maya\_tzolkin          &bool & false\\
show\_aztec\_tonalpohualli   &bool & false&
show\_aztec\_xihuitl         &bool & false\\\midrule
show\_french\_astronomical   &bool & false&
show\_french\_arithmetic     &bool & false\\\bottomrule
%show\_chinese                &bool & false\\
\end{longtable}
}

\subsection{Further development}
The plugin is still in development. More calendars will be added in
later versions, and formatting and setting options may be
improved. Members of non-European cultures who are actually using the
output and can judge its correctness are invited to report errors or
suggest better formatting for their respective calendars.

For example, our source book \citep{Reingold-Dershowitz:2018}
describes one solution for the ``New Hindu'' calendars, but notes
several variants, which are in fact also location dependent. We cannot
show every variant here, but hope to have the version described in the
book correct. If you know what you are doing: we are accepting
improvements and extensions in form of working code plus documentation
where this variant is used. Not just a few example dates, but an
algorithmic solution.

\subsection{Acknowledgments}

If you are using this plugin in scientific publications, please cite \citet{Zotti-etal:JSA2020.6.2}.


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "guide"
%%% End: 

