Calendrical.Lunisolar
(Calendrical v0.3.0)
Copy Markdown
Shared base implementation for Calendrical's lunisolar calendars.
A lunisolar calendar approximates the tropical year using lunar months, inserting an intercalary (leap) month roughly every three years to keep the calendar aligned with the seasons. Calendrical implements three lunisolar calendars on top of this module:
Calendrical.Chinese— observation point Beijing.Calendrical.Korean(Dangi) — observation point Seoul.Calendrical.LunarJapanese— observation point Tokyo.
Each implementation is a thin wrapper that supplies its epoch and an
observation-location function (latitude, longitude, altitude, time-zone
offset). All of the astronomical heavy lifting — winter solstice, mean and
true new moon, leap-month detection, sexagesimal cycle calculations — is
delegated to Astro and lives in this module.
This module is not intended to be called directly from application code.
Use one of the lunisolar calendar modules above and the standard Date and
Calendar APIs.
Naming conventions
Several "year" and "month" concepts coexist in a lunisolar calendar. To keep the code unambiguous, this module uses the following names consistently:
yearis the calendar year, counted as the number of years since the calendar's epoch.cyclical_yearis the position within the 60-year sexagesimal cycle (1..60).cycleis the number of completed sexagesimal cycles since the epoch.monthis the ordinal month of the calendar year — 1..12 in an ordinary year and 1..13 in a leap year. This is the value theCalendarbehaviour expects.lunar_monthis the traditional month number, 1..12 in all years, with leap months represented as{month, :leap}. This is the value users see in cultural contexts and the form returned byCalendrical.localize/3.
References
Reingold and Dershowitz, Calendrical Calculations: The Ultimate Edition, 4th ed., chapters on the Chinese, Korean and Japanese calendars.
The accompanying Common Lisp source distributed with the same book.
Summary
Functions
Return iso_days of Lunar New Year at location for a
Gregorian year.
Return last Chinese major solar term (zhongqi) before
iso_days.
Return last minor solar term (jieqi) before iso_days.
Return sexagesimal name for date, date.
Return iso_days of latest date on or before iso_days, that has Chinese name, name.
Return iso_days, in the location zone, of winter solstice
on or before iso_days.
Returns the Gregorian date for the lunar month and day in a given Gregorian year.
Return true if there is a Lunar leap month on or after lunar
month starting on m_prime and at or before
lunar month starting at m.
Returns the leap month number for a given year or nil if its not a leap year.
Approximately every three years (7 times in 19 years), a leap month is added to the Chinese calendar.
Returns if the given year is a leap year.
Return moment at location of the first major
solar term (zhongqi) on or after iso_days. The
major terms begin when the sun's longitude is a
multiple of 30 degrees.
Return Universal time of (clock) midnight at start of iso_days,
at location.
Return moment at location of the first minor solar
term (jieqi) on or after iso_days. The minor terms
begin when the sun's longitude is an odd multiple of 15 degrees.
Return sexagesimal name for month, month, of Chinese year, year.
Return the number of names from Lunar name c_name1 to the next occurrence of Lunar name c_name2.
Create a new date in the lunisolar calendar.
Return iso_day at location of first new moon
before iso_days.
Return iso_day at location of first new moon on or after
iso_days.
Return iso_day of Lunar New Year in sui
(period from solstice to solstice)
containing iso_days.
Return iso_day of Lunar New Year on or
before iso_days at location.
Return true if lunar month starting on iso_days
at location has no major solar term.
Return moment at location of the first date on or after
iso_days when the solar longitude
will be 'lambda' degrees.
Return the name of the Lunar sexagesimal cycle.
Types
@type cycle() :: pos_integer()
A sexigesimal cycle number
@type lunar_month() :: Calendar.month() | {Calendar.month(), :leap}
A lunar month
Functions
Return iso_days of Lunar New Year at location for a
Gregorian year.
Return last Chinese major solar term (zhongqi) before
iso_days.
Return last minor solar term (jieqi) before iso_days.
Return sexagesimal name for date, date.
Return iso_days of latest date on or before iso_days, that has Chinese name, name.
Return iso_days, in the location zone, of winter solstice
on or before iso_days.
Returns the Gregorian date for the lunar month and day in a given Gregorian year.
Return true if there is a Lunar leap month on or after lunar
month starting on m_prime and at or before
lunar month starting at m.
Returns the leap month number for a given year or nil if its not a leap year.
Approximately every three years (7 times in 19 years), a leap month is added to the Chinese calendar.
To determine when, find the number of new moons between the 11th month in one year and the 11th month in the following year.
A leap month is inserted if there are 13 New Moons from the start of the 11th month in the first year to the start of the 11th month in the next year.
The Chinese calendar uses a solar term system that has 12 principal terms to indicate when the Sun's longitude is a multiple of 30 degrees.
Unlike all other months, the leap month does not contain a principal term (Zhongqi).
Returns if the given year is a leap year.
Leap years have 13 months. To determine if a year is a leap year, calculate the number of new moons between the 11th month in one year (i.e., the month containing the Winter Solstice) and the 11th month in the following year.
If there are 13 new moons from the start of the 11th month in the first year to the start of the 11th month in the second year, a leap month must be inserted.
In leap years, at least one month does not contain a Principal Term. The first such month is the leap month.
The additional complexity is that a leap year is calculated for the solar year, but the calendar is managed in lunar years and months. Therefore when a leap year is detected, the leap month could be in the current lunar year or the next lunar year.
Return moment at location of the first major
solar term (zhongqi) on or after iso_days. The
major terms begin when the sun's longitude is a
multiple of 30 degrees.
Return Universal time of (clock) midnight at start of iso_days,
at location.
Return moment at location of the first minor solar
term (jieqi) on or after iso_days. The minor terms
begin when the sun's longitude is an odd multiple of 15 degrees.
Return sexagesimal name for month, month, of Chinese year, year.
Return the number of names from Lunar name c_name1 to the next occurrence of Lunar name c_name2.
Create a new date in the lunisolar calendar.
Arguments
yearis a year in the lunisolar calendar.monthis a month in the lunisolar calendar as either a positive integer or a tuple of the form{month, :leap}representing the leap month.dayis a day of month.epochis the epoch in iso days for the lunisolar calendar.location_funis a 1-arity function that returns the tuple of the form{latitude, longitude, altitude, hour_offset}for the lunisolar calendar.
Returns
iso_daysbegin the iso_days for the given date in based upon the given location.
Return iso_day at location of first new moon
before iso_days.
Return iso_day at location of first new moon on or after
iso_days.
Return iso_day of Lunar New Year in sui
(period from solstice to solstice)
containing iso_days.
Return iso_day of Lunar New Year on or
before iso_days at location.
Return true if lunar month starting on iso_days
at location has no major solar term.
@spec solar_longitude_on_or_after(Astro.angle(), number(), function()) :: Astro.Time.time()
Return moment at location of the first date on or after
iso_days when the solar longitude
will be 'lambda' degrees.
Return the name of the Lunar sexagesimal cycle.