Dusk 🌑 is a minimal dependency Go library for calculating the most opinimum time to observe various astronomical objects by utilising paramaters such as astronomical twilight, the lunar phase and the rise and set times of the moon and sun.
Make sure you have Go installed (download). Version 1.17 or higher is required for this package.
Initialize your project by creating a folder and then running go mod init github.com/your/repo (learn more) inside the folder. Then install Dusk with the go get command:
go get -u github.com/observerly/duskThe basic usage of this package is to use the GetLocalTwilight() func, this provides the Sun rise and Sun set times (in datetime format, as local time), it also provides the "duration" between these two datetimes. The local time is calculated from a UTC date for the speicif latitude and longitude coordiantes provided.
package main
import (
"time"
"github.com/observerly/dusk/pkg/dusk"
)
func main() {
// datetime of observation:
datetime := time.Date(2022, 2, 17, 0, 0, 0, 0, time.UTC)
// observer's longitude, in degrees (*west of the Greenwhich meridian is negative, east is positive):
longitude := -155.8246
// observer's latitude, in degrees (*south of the equator is negative, north is positive):
latitude := 20.0046
// observaer's elevation above mean sea level, in meteres:
elevation := 4207.0
// specify the twilight to be defined as a set number of degrees *below* the horizon (e.g, civil twilight is designated as being 6 degrees below horizon):
degreesBelowHorizon := -6.0
twilight, location, err := dusk.GetLocalTwilight(datetime, longitude, latitude, elevation, degreesBelowHorizon)
}There are three wrapper functions which allow for an easy calculation of civil, nautical and astronomical twilight.
For civil twilight, the degreesBelowHorizon for the Sun needs to be -6°.
twilight, location, err := dusk.GetLocalCivilTwilight(datetime, longitude, latitude, elevation)For nautical twilight, the degreesBelowHorizon for the Sun needs to be -12°.
twilight, location, err := dusk.GetLocalNauticalTwilight(datetime, longitude, latitude, elevation)For astronomical twilight, the degreesBelowHorizon for the Sun needs to be -18°.
twilight, location, err := dusk.GetLocalAstronomicalTwilight(datetime, longitude, latitude, elevation)To calculate the rise and set of the moon, it is neccessary to calculate the equatorial position of the moon at zero HH:mm:ss, e.g., midnight, for the +/-1 day for the day you want to calculate for, e.g., d-1, d and d+1.
This library supplies the following function to calculate the equatorial position of the moon (in degrees):
package main
import (
"fmt"
"time"
"github.com/observerly/dusk/pkg/dusk"
)
func main() {
// datetime of observation:
datetime := time.Date(2022, 2, 17, 14, 55, 0, 0, time.UTC)
eq := dusk.GetLunarEquatorialPosition(datetime)
fmt.Printf("The Moon is at the following equatorial coordinate:\n")
fmt.Printf("Right Ascension: %e°\n", eq.ra)
fmt.Printf("Declination: %e°\n", eq.dec)
}To calculate the moon phase, it is neccessary to calculate the ecliptic position of the moon at the datetime required, as well as the knowing some longitude of an observer.
This library supplies the following function to calculate the phase of the moon:
package main
import (
"fmt"
"time"
"github.com/observerly/dusk/pkg/dusk"
)
func main() {
// datetime of observation:
datetime := time.Date(2022, 2, 17, 14, 55, 0, 0, time.UTC)
// some longitude, in degrees (*west of the Greenwhich meridian is negative, east is positive):
lonmgitude := -155.8246
// get the ecliptic coordinate of the Moon for the datetime:
ec := dusk.GetLunarEclipticPosition(datetime)
// calculate the phase for the datetime, longitude and ecliptic coordinate:
phase := dusk.GetMoonPhase(datetime, longitude, ec)
}N.B. The equatorial coordinate system is a celestial coordinate system widely used to specify the positions of celestial objects. It may be implemented in spherical or rectangular coordinates, both defined by an origin at the centre of Earth, a fundamental plane consisting of the projection of Earth's equator onto the celestial sphere (forming the celestial equator), a primary direction towards the vernal equinox, and a right-handed convention.
Dusk is free software licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE.
The binary version of this program uses several open source libraries and components, which come with their own licensing terms. See below for an overview, and LICENSE for details.
| Library attribution | License type |
|---|---|
| zsefvlol/timezonemapper | MIT License |