From 3ad7c7d9ece9567ff01574a4f8af4775e7c41730 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Wed, 17 Jul 2019 20:17:04 -0400 Subject: [PATCH] Python: Documented moon quarter type and functions. --- generate/template/astronomy.py | 51 ++++++++++++++++++++++++ source/python/README.md | 71 ++++++++++++++++++++++++++++++++++ source/python/astronomy.py | 51 ++++++++++++++++++++++++ 3 files changed, 173 insertions(+) diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 33bde099..44c6c99d 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -2023,11 +2023,46 @@ def SearchMoonPhase(targetLon, startTime, limitDays): return Search(_moon_offset, targetLon, t1, t2, 1.0) class MoonQuarter: + """A lunar quarter event along with its date and time. + + An object of this type represents one of the four major + lunar phases that appear on calendars: + new moon, first quarter, full moon, or third quarter. + Along with the `quarter` attribute that specifies the + type of quarter, it contains a `time` field that indicates + when the lunar quarter event happens. + + Attributes + ---------- + quarter : int + 0=new moon, 1=first quarter, 2=full moon, 3=third quarter. + time : Time + The date and time of the lunar quarter. + """ def __init__(self, quarter, time): self.quarter = quarter self.time = time def SearchMoonQuarter(startTime): + """Finds the first lunar quarter after the specified date and time. + + A lunar quarter is one of the following four lunar phase events: + new moon, first quarter, full moon, third quarter. + This function finds the lunar quarter that happens soonest + after the specified date and time. + + To continue iterating through consecutive lunar quarters, call this function once, + followed by calls to #NextMoonQuarter as many times as desired. + + Parameters + ---------- + startTime : Time + The date and time at which to start the search. + + Returns + ------- + #MoonQuarter + """ angle = MoonPhase(startTime) quarter = int(1 + math.floor(angle / 90.0)) % 4 time = SearchMoonPhase(90.0 * quarter, startTime, 10.0) @@ -2037,6 +2072,22 @@ def SearchMoonQuarter(startTime): return MoonQuarter(quarter, time) def NextMoonQuarter(mq): + """Continues searching for lunar quarters from a previous search. + + After calling #Astronomy_SearchMoonQuarter, this function can be called + one or more times to continue finding consecutive lunar quarters. + This function finds the next consecutive moon quarter event after + the one passed in as the parameter `mq`. + + Parameters + ---------- + mq : MoonQuarter + A value returned by a prior call to #SearchMoonQuarter or #NextMoonQuarter. + + Returns + ------- + #MoonQuarter + """ # Skip 6 days past the previous found moon quarter to find the next one. # This is less than the minimum possible increment. # So far I have seen the interval well contained by the range (6.5, 8.3) days. diff --git a/source/python/README.md b/source/python/README.md index 8a25f87d..08279fb0 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -138,6 +138,29 @@ a celestial body crossing a certain hour angle as seen by a specified topocentri +--- + + +### class MoonQuarter + +**A lunar quarter event along with its date and time.** + +An object of this type represents one of the four major +lunar phases that appear on calendars: +new moon, first quarter, full moon, or third quarter. +Along with the `quarter` attribute that specifies the +type of quarter, it contains a `time` field that indicates +when the lunar quarter event happens. + + +| Type | Attribute | Description | +| --- | --- | --- | +| `int` | `quarter` | 0=new moon, 1=first quarter, 2=full moon, 3=third quarter. | +| [`Time`](#Time) | `time` | The date and time of the lunar quarter. | + + + + --- @@ -787,6 +810,29 @@ Certain values of the angle have conventional definitions: +--- + + +### NextMoonQuarter(mq) + +**Continues searching for lunar quarters from a previous search.** + +After calling #Astronomy_SearchMoonQuarter, this function can be called +one or more times to continue finding consecutive lunar quarters. +This function finds the next consecutive moon quarter event after +the one passed in as the parameter `mq`. + + +| Type | Parameter | Description | +| --- | --- | --- | +| [`MoonQuarter`](#MoonQuarter) | `mq` | A value returned by a prior call to #SearchMoonQuarter or #NextMoonQuarter. | + +### Returns: #MoonQuarter + + + + + --- @@ -915,6 +961,31 @@ This function is useful for finding general phase angles outside those four quar +--- + + +### SearchMoonQuarter(startTime) + +**Finds the first lunar quarter after the specified date and time.** + +A lunar quarter is one of the following four lunar phase events: +new moon, first quarter, full moon, third quarter. +This function finds the lunar quarter that happens soonest +after the specified date and time. +To continue iterating through consecutive lunar quarters, call this function once, +followed by calls to #NextMoonQuarter as many times as desired. + + +| Type | Parameter | Description | +| --- | --- | --- | +| [`Time`](#Time) | `startTime` | The date and time at which to start the search. | + +### Returns: #MoonQuarter + + + + + --- diff --git a/source/python/astronomy.py b/source/python/astronomy.py index bd2fe5b5..1b3128ff 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -4084,11 +4084,46 @@ def SearchMoonPhase(targetLon, startTime, limitDays): return Search(_moon_offset, targetLon, t1, t2, 1.0) class MoonQuarter: + """A lunar quarter event along with its date and time. + + An object of this type represents one of the four major + lunar phases that appear on calendars: + new moon, first quarter, full moon, or third quarter. + Along with the `quarter` attribute that specifies the + type of quarter, it contains a `time` field that indicates + when the lunar quarter event happens. + + Attributes + ---------- + quarter : int + 0=new moon, 1=first quarter, 2=full moon, 3=third quarter. + time : Time + The date and time of the lunar quarter. + """ def __init__(self, quarter, time): self.quarter = quarter self.time = time def SearchMoonQuarter(startTime): + """Finds the first lunar quarter after the specified date and time. + + A lunar quarter is one of the following four lunar phase events: + new moon, first quarter, full moon, third quarter. + This function finds the lunar quarter that happens soonest + after the specified date and time. + + To continue iterating through consecutive lunar quarters, call this function once, + followed by calls to #NextMoonQuarter as many times as desired. + + Parameters + ---------- + startTime : Time + The date and time at which to start the search. + + Returns + ------- + #MoonQuarter + """ angle = MoonPhase(startTime) quarter = int(1 + math.floor(angle / 90.0)) % 4 time = SearchMoonPhase(90.0 * quarter, startTime, 10.0) @@ -4098,6 +4133,22 @@ def SearchMoonQuarter(startTime): return MoonQuarter(quarter, time) def NextMoonQuarter(mq): + """Continues searching for lunar quarters from a previous search. + + After calling #Astronomy_SearchMoonQuarter, this function can be called + one or more times to continue finding consecutive lunar quarters. + This function finds the next consecutive moon quarter event after + the one passed in as the parameter `mq`. + + Parameters + ---------- + mq : MoonQuarter + A value returned by a prior call to #SearchMoonQuarter or #NextMoonQuarter. + + Returns + ------- + #MoonQuarter + """ # Skip 6 days past the previous found moon quarter to find the next one. # This is less than the minimum possible increment. # So far I have seen the interval well contained by the range (6.5, 8.3) days.