From 7721f7a7353a8a1e981bb93d85c5f6cc610ab6ba Mon Sep 17 00:00:00 2001 From: Don Cross Date: Sat, 13 Jul 2019 17:02:39 -0400 Subject: [PATCH] Python: added documentation for function SearchRelativeLongitude. --- generate/template/astronomy.py | 50 ++++++++++++++++++++++++++++++++++ source/python/README.md | 45 ++++++++++++++++++++++++++++++ source/python/astronomy.py | 50 ++++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+) diff --git a/generate/template/astronomy.py b/generate/template/astronomy.py index 41be5afd..2cc7c6a9 100644 --- a/generate/template/astronomy.py +++ b/generate/template/astronomy.py @@ -1699,6 +1699,56 @@ def _rlon_offset(body, time, direction, targetRelLon): return _LongitudeOffset(diff - targetRelLon) def SearchRelativeLongitude(body, targetRelLon, startTime): + """Searches for when the Earth and another planet are separated by a certain ecliptic longitude. + + Searches for the time when the Earth and another planet are separated by a specified angle + in ecliptic longitude, as seen from the Sun. + + A relative longitude is the angle between two bodies measured in the plane of the + Earth's orbit (the ecliptic plane). The distance of the bodies above or below the ecliptic + plane is ignored. If you imagine the shadow of the body cast onto the ecliptic plane, + and the angle measured around that plane from one body to the other in the direction + the planets orbit the Sun, you will get an angle somewhere between 0 and 360 degrees. + This is the relative longitude. + + Given a planet other than the Earth in `body` and a time to start the search in `startTime`, + this function searches for the next time that the relative longitude measured from the + planet to the Earth is `targetRelLon`. + + Certain astronomical events are defined in terms of relative longitude between + the Earth and another planet: + + - When the relative longitude is 0 degrees, it means both planets are in the same + direction from the Sun. For planets that orbit closer to the Sun (Mercury and Venus), + this is known as *inferior conjunction*, a time when the other planet becomes very + difficult to see because of being lost in the Sun's glare. + (The only exception is in the rare event of a transit, when we see the silhouette + of the planet passing between the Earth and the Sun.) + + - When the relative longitude is 0 degrees and the other planet orbits farther from the Sun, + this is known as *opposition*. Opposition is when the planet is closest to the Earth, + and also when it is visible for most of the night, so it is considered the best time + to observe the planet. + + - When the relative longitude is 180 degrees, it means the other planet is on the opposite + side of the Sun from the Earth. This is called *superior conjunction*. Like inferior + conjunction, the planet is very difficult to see from the Earth. + Superior conjunction is possible for any planet other than the Earth. + + Parameters + ---------- + body : Body + A planet other than the Earth. If `body` is not a planet, or if it is `Body.Earth`, an error occurs. + targetRelLon : float + The desired relative longitude, expressed in degrees. Must be in the range [0, 360). + startTime : Time + The date and time at which to begin the search. + + Returns + ------- + Time + The date and time of the relative longitude event. + """ if body == Body.Earth: raise EarthNotAllowedError() if body == Body.Moon or body == Body.Sun: diff --git a/source/python/README.md b/source/python/README.md index e99a4417..13dcdaa7 100644 --- a/source/python/README.md +++ b/source/python/README.md @@ -722,6 +722,51 @@ dt_tolerance_seconds : float +--- + + +### SearchRelativeLongitude(body, targetRelLon, startTime) + +**Searches for when the Earth and another planet are separated by a certain ecliptic longitude.** + +Searches for the time when the Earth and another planet are separated by a specified angle +in ecliptic longitude, as seen from the Sun. +A relative longitude is the angle between two bodies measured in the plane of the +Earth's orbit (the ecliptic plane). The distance of the bodies above or below the ecliptic +plane is ignored. If you imagine the shadow of the body cast onto the ecliptic plane, +and the angle measured around that plane from one body to the other in the direction +the planets orbit the Sun, you will get an angle somewhere between 0 and 360 degrees. +This is the relative longitude. +Given a planet other than the Earth in `body` and a time to start the search in `startTime`, +this function searches for the next time that the relative longitude measured from the +planet to the Earth is `targetRelLon`. +Certain astronomical events are defined in terms of relative longitude between +the Earth and another planet: +- When the relative longitude is 0 degrees, it means both planets are in the same + direction from the Sun. For planets that orbit closer to the Sun (Mercury and Venus), + this is known as *inferior conjunction*, a time when the other planet becomes very + difficult to see because of being lost in the Sun's glare. + (The only exception is in the rare event of a transit, when we see the silhouette + of the planet passing between the Earth and the Sun.) +- When the relative longitude is 0 degrees and the other planet orbits farther from the Sun, + this is known as *opposition*. Opposition is when the planet is closest to the Earth, + and also when it is visible for most of the night, so it is considered the best time + to observe the planet. +- When the relative longitude is 180 degrees, it means the other planet is on the opposite + side of the Sun from the Earth. This is called *superior conjunction*. Like inferior + conjunction, the planet is very difficult to see from the Earth. + Superior conjunction is possible for any planet other than the Earth. + + +| Type | Parameter | Description | +| --- | --- | --- | +| [`Body`](#Body) | `body` | A planet other than the Earth. If `body` is not a planet, or if it is `Body.Earth`, an error occurs. | +| `float` | `targetRelLon` | The desired relative longitude, expressed in degrees. Must be in the range [0, 360). | +| [`Time`](#Time) | `startTime` | The date and time at which to begin the search. | + + + + --- diff --git a/source/python/astronomy.py b/source/python/astronomy.py index 3a7ca746..96517bd8 100644 --- a/source/python/astronomy.py +++ b/source/python/astronomy.py @@ -3760,6 +3760,56 @@ def _rlon_offset(body, time, direction, targetRelLon): return _LongitudeOffset(diff - targetRelLon) def SearchRelativeLongitude(body, targetRelLon, startTime): + """Searches for when the Earth and another planet are separated by a certain ecliptic longitude. + + Searches for the time when the Earth and another planet are separated by a specified angle + in ecliptic longitude, as seen from the Sun. + + A relative longitude is the angle between two bodies measured in the plane of the + Earth's orbit (the ecliptic plane). The distance of the bodies above or below the ecliptic + plane is ignored. If you imagine the shadow of the body cast onto the ecliptic plane, + and the angle measured around that plane from one body to the other in the direction + the planets orbit the Sun, you will get an angle somewhere between 0 and 360 degrees. + This is the relative longitude. + + Given a planet other than the Earth in `body` and a time to start the search in `startTime`, + this function searches for the next time that the relative longitude measured from the + planet to the Earth is `targetRelLon`. + + Certain astronomical events are defined in terms of relative longitude between + the Earth and another planet: + + - When the relative longitude is 0 degrees, it means both planets are in the same + direction from the Sun. For planets that orbit closer to the Sun (Mercury and Venus), + this is known as *inferior conjunction*, a time when the other planet becomes very + difficult to see because of being lost in the Sun's glare. + (The only exception is in the rare event of a transit, when we see the silhouette + of the planet passing between the Earth and the Sun.) + + - When the relative longitude is 0 degrees and the other planet orbits farther from the Sun, + this is known as *opposition*. Opposition is when the planet is closest to the Earth, + and also when it is visible for most of the night, so it is considered the best time + to observe the planet. + + - When the relative longitude is 180 degrees, it means the other planet is on the opposite + side of the Sun from the Earth. This is called *superior conjunction*. Like inferior + conjunction, the planet is very difficult to see from the Earth. + Superior conjunction is possible for any planet other than the Earth. + + Parameters + ---------- + body : Body + A planet other than the Earth. If `body` is not a planet, or if it is `Body.Earth`, an error occurs. + targetRelLon : float + The desired relative longitude, expressed in degrees. Must be in the range [0, 360). + startTime : Time + The date and time at which to begin the search. + + Returns + ------- + Time + The date and time of the relative longitude event. + """ if body == Body.Earth: raise EarthNotAllowedError() if body == Body.Moon or body == Body.Sun: