diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 6c57ec35..0f02b8d2 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -2274,6 +2274,31 @@ def _mag_slope(body, time): return (y2.mag - y1.mag) / dt def SearchPeakMagnitude(body, startTime): + """Searches for the date and time Venus will next appear brightest as seen from the Earth. + + This function searches for the date and time Venus appears brightest as seen from the Earth. + Currently only Venus is supported for the `body` parameter, though this could change in the future. + Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see + from the Earth, so peak magnitude events have little practical value for that planet. + Planets other than Venus and Mercury reach peak magnitude at opposition, which can + be found using #SearchRelativeLongitude. + The Moon reaches peak magnitude at full moon, which can be found using + #SearchMoonQuarter or #SearchMoonPhase. + The Sun reaches peak magnitude at perihelion, which occurs each year in January. + However, the difference is minor and has little practical value. + + Parameters + ---------- + body : Body + Currently only `Body.Venus` is allowed. Any other value results in an exception. + See remarks above for more details. + startTime : Time + The date and time to start searching for the next peak magnitude event. + + Returns + ------- + #IlluminationInfo + """ # s1 and s2 are relative longitudes within which peak magnitude of Venus can occur. s1 = 10.0 s2 = 30.0 diff --git a/source/python/README.md b/source/python/README.md index 7c366118..6bad8be5 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -868,6 +868,31 @@ followed by calls to #NextMoonQuarter as many times as desired. --- + +### SearchPeakMagnitude(body, startTime) + +**Searches for the date and time Venus will next appear brightest as seen from the Earth.** + +This function searches for the date and time Venus appears brightest as seen from the Earth. +Currently only Venus is supported for the `body` parameter, though this could change in the future. +Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see +from the Earth, so peak magnitude events have little practical value for that planet. +Planets other than Venus and Mercury reach peak magnitude at opposition, which can +be found using #SearchRelativeLongitude. +The Moon reaches peak magnitude at full moon, which can be found using +#SearchMoonQuarter or #SearchMoonPhase. +The Sun reaches peak magnitude at perihelion, which occurs each year in January. +However, the difference is minor and has little practical value. + +| Type | Parameter | Description | +| --- | --- | --- | +| [`Body`](#Body) | `body` | Currently only `Body.Venus` is allowed. Any other value results in an exception. See remarks above for more details. | +| [`Time`](#Time) | `startTime` | The date and time to start searching for the next peak magnitude event. | + +### Returns: #IlluminationInfo + +--- + ### SearchRelativeLongitude(body, targetRelLon, startTime) diff --git a/source/python/astronomy.py b/source/python/astronomy.py index c0e1357b..9189f130 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -4335,6 +4335,31 @@ def _mag_slope(body, time): return (y2.mag - y1.mag) / dt def SearchPeakMagnitude(body, startTime): + """Searches for the date and time Venus will next appear brightest as seen from the Earth. + + This function searches for the date and time Venus appears brightest as seen from the Earth. + Currently only Venus is supported for the `body` parameter, though this could change in the future. + Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see + from the Earth, so peak magnitude events have little practical value for that planet. + Planets other than Venus and Mercury reach peak magnitude at opposition, which can + be found using #SearchRelativeLongitude. + The Moon reaches peak magnitude at full moon, which can be found using + #SearchMoonQuarter or #SearchMoonPhase. + The Sun reaches peak magnitude at perihelion, which occurs each year in January. + However, the difference is minor and has little practical value. + + Parameters + ---------- + body : Body + Currently only `Body.Venus` is allowed. Any other value results in an exception. + See remarks above for more details. + startTime : Time + The date and time to start searching for the next peak magnitude event. + + Returns + ------- + #IlluminationInfo + """ # s1 and s2 are relative longitudes within which peak magnitude of Venus can occur. s1 = 10.0 s2 = 30.0