feat: add GetLocalSiderealTime(datetime time.Time) to epoch module in @observerly/sidera.

pkg/epoch/epoch.go

@@ -11,6 +11,8 @@ package epoch
 import (
 	"math"
 	"time"
+
+	"github.com/observerly/sidera/pkg/common"
 )
 
 /*****************************************************************************************************************/
@@ -157,3 +159,32 @@ func GetGreenwichSiderealTime(datetime time.Time) float64 {
 }
 
 /*****************************************************************************************************************/
+
+/*
+the Local Sidereal Time (LST) for a given date and time at a specific geographic location.
+
+The Local Sidereal Time (LST) is the local correction applied to the Greenwich Sidereal Time
+(GST) to account for the observer's longitude. It is the angle between the observer's meridian
+and the vernal equinox, measured in sidereal hours. The Local Sidereal Time is used in astronomy
+to determine the positions of celestial objects in the sky from a specific location on Earth.
+*/
+func GetLocalSiderealTime(datetime time.Time, observer common.GeographicCoordinate) float64 {
+	// get the Greenwich Sidereal Time:
+	GST := GetGreenwichSiderealTime(datetime)
+
+	// calculate the Local Sidereal Time:
+	d := (GST + observer.Longitude/15.0) / 24.0
+
+	// apply a correction factor to account for the fractional number of hours:
+	d -= math.Floor(d)
+
+	// correct for negative hour angles (24 hours is equivalent to 360°)
+	if d < 0 {
+		d += 1
+	}
+
+	// return the Local Sidereal Time:
+	return 24.0 * d
+}
+
+/*****************************************************************************************************************/

pkg/epoch/epoch_test.go

@@ -15,6 +15,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/observerly/sidera/pkg/common"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -25,6 +26,11 @@ var datetime time.Time = time.Date(2021, 5, 14, 0, 0, 0, 0, time.UTC)
 
 /*****************************************************************************************************************/
 
+// We define the geographic coordinates of Mauna Kea, Hawaii for testing purposes:
+var longitude float64 = -155.468094
+
+/*****************************************************************************************************************/
+
 func TestGetJ1858(t *testing.T) {
 	// Test the Julian Date calculation for the J1858.0 epoch:
 	assert.Equal(t, J1858, 2400000.5)
@@ -81,3 +87,19 @@ func TestGreenwhichSiderealTime(t *testing.T) {
 }
 
 /*****************************************************************************************************************/
+
+func TestLocalSiderealTime(t *testing.T) {
+	var got float64 = GetLocalSiderealTime(datetime, common.GeographicCoordinate{
+		Latitude:  0,
+		Longitude: longitude,
+		Elevation: 0,
+	})
+
+	var want float64 = 5.099422
+
+	if math.Abs(got-want) > 0.00001 {
+		t.Errorf("got %f, wanted %f", got, want)
+	}
+}
+
+/*****************************************************************************************************************/