Template:Selune phase/doc

This template computes the phase of Selûne on a particular day. Input is a Gregorian calendar day in the format YYYY-MM-DD or it will default to the current day (as determined by ). If you set daysSinceLeap to an integer, it will use that instead. The Calendar of Harptos exactly maps to the Gregorian calendar for the number of days, including leap years (Shieldmeet), so January 1 = Hammer 1 and December 31 = Nightal 30. According to the Forgotten Realms Campaign Setting 3rd edition, Selûne is full at midnight on Hammer 1 of every leap year, giving us a 48-month lunar cycle. For lycanthropes and other people who depend on the phases of the moon, each primary phase has a length of 3 days. For example, the moon is considered "full" one day before and one day after the mathematically determined "full" date. On top of that, the hour of the day the moon rises determines when the phase starts, and could move the phase an additional day backward.

Usage
There are a number of ways to use this template to produce informative results. Here is the basic invocation: (Defaults to the current date) or          (You may specify a particular date) or (Chose one of the various output modes) Where MODE can be absent, or one of the following:
 * symbol: The template will output the symbol representing the moon phase on the date:
 * phase: The template will output a phrase representing the phase of the moon:
 * info: The template outputs a sentence describing Selûne's state on the date:


 * infoPast: Same as for info except in past tense:
 * verbose: The template will output a whole paragraph about Selûne and the calendar:

If mode is unspecified or unrecognized, the template prints out the phase and symbol like so:
 * fivePhases: This is a special output used by Module:FRCalendar to create a calendar widget that has the phases of the moon properly placed on the correct dates. It is a comma-separated list of 5 integers representing the number of days since January 1 (Hammer 1) of the most recent leap year. It looks like this:
 * debug: This spits out the value of all the important internal variables used in calculating the phases of Selûne. We believe all the bugs have been worked out, but if a discrepancy is found, this is probably the place to start looking.

The other way to use this template is to give it the number of days since the first day of the previous leap year using the daysSinceLeap parameter. This will be an integer ranging from 0 to 1460. The usual way to get a number like this is from the Date number template which takes a day, month, and year on the Calendar of Harptos as input, like so: (Integer 0–1460) or or (Info mode) Executing the last line gives:

Under the Hood
The algorithm used by this template divides the four-year Selûnian phase cycle into 48 lunar months, starting from midnight of 1 Hammer of the last leap year before the given date (a full moon). It also divides each lunar month into four equal segments, corresponding to the exact dates and times of each principal phase (third quarter, new moon, and first quarter). It then performs two calculations:


 * 1) It takes the received date and calculates the last phase change to happen before that date, as well as how many principal phases have occurred since the last full moon. This will be the exact date and time the current phase started, as well as which phase it is.
 * 2) It then performs the same calculation for two days in the future. The purpose of this extra step is to calculate whether the current phase is sufficiently close to another change as to be considered the next phase.

Once these two calculations have been performed, the algorithm determines if the current phase of Selûne corresponds to the nearest principal phase or if it is an intermediate phase (waning gibbous, waning crescent, waxing crescent, or waxing gibbous). The criterion we adopted is the following:


 * For any non-full principal phase, Selûne will be within its range one day before and one day after the exact date of change. For example, if a change to first quarter happened at any time in 3 Ches, then the range between 2 and 4 Ches will consider that Selûne is in first quarter phase. Dates beyond this range (and outside of the ranges of adjacent principal phases) will be considered intermediate phases (waxing crescent before 2 Ches and waxing gibbous after 4 Ches).
 * The full moon case is different because it is the only principal phase that is above the horizon when the date changes (note that only a full moon is highest in the sky around midnight). For this reason, the date range is computed in a slightly different way:
 * If the moon becomes full between 6 AM and midnight, the same range for other phases is applied: one day before and one day after.
 * If the moon becomes full between midnight and 6 AM, the date range starts two days before that date and ends on that same date. This reflects the fact that if the moon becomes full while it is above the horizon, it can be considered that it rose already full on that day. For example, the full moon that happens at midnight, 1 Hammer every leap year is considered full between 29 Nightal and 1 Hammer. Note that the full moon of 1 Hammer rose on 30 Nightal.

In order to determine whether the current phase is a principal or an intermediate phase, the algorithm first determines if the current date is still within the date range of the last phase change, according to the criteria above. It then performs the same check for the phase change two days in the future, in order to determine if the current date is already within the date range of the next phase change, using the same criteria.

Finally, the algorithm determines when the next principal phase will happen, by adding one quarter of a lunar month to the specified date. On this step, it only calculates the exact time of change, disregarding intervals.