edu.nrao.sss.measure
Class LocalSiderealTime

java.lang.Object
  edu.nrao.sss.measure.LocalSiderealTime

All Implemented Interfaces:

Cloneable, Comparable<LocalSiderealTime>

public class LocalSiderealTime
extends Object
implements Cloneable, Comparable<LocalSiderealTime>

Local sidereal time (LST). See Wikipedia or other places on the web for more information.

Note that this LST functions as a date/time, like the Date class, not as a dateless time, like the TimeOfDay class. This means, for example, that two LSTs of 12:34:56.789 on different days are not equal. Clients who wish to work only with the LST time-of-day may get a TimeOfDay instance from the toTimeOfDay() method.

Currently this class represents local mean sidereal time; it could be upgraded to allow for the calculation of local apparent sidereal time in the future, if clients find that useful.

The LST may be constructed for any location, but by default is set up to use the VLA's longitude (-107d 37' 03.819").

Version Info:

$Revision: 1669 $

$Date: 2008-11-05 11:08:04 -0700 (Wed, 05 Nov 2008) $

$Author: dharland $ (last person to modify)

Since:

2007-08-02

Author:

David M. Harland

Constructor Summary

LocalSiderealTime()
Creates a new local sidereal time based on the current solar time and the longitude and time zone of the VLA.

LocalSiderealTime(Date gregorianCalendarDate)
Creates a new local sidereal time based on the given solar time and the longitude and time zone of the VLA.

LocalSiderealTime(Date gregorianCalendarDate, Longitude longitude, TimeZone timeZone)
Creates a new local sidereal time based on the given parameters

LocalSiderealTime(int localSiderealDay, TimeOfDay localSiderealTime)

LocalSiderealTime(JulianDate julianDate)
Creates a new local sidereal time based on the given solar time and the longitude and time zone of the VLA.

Method Summary

LocalSiderealTime	addSidereal(TimeDuration siderealDuration) Increments this LST by the given amount of sidereal time.
LocalSiderealTime	addSolar(TimeDuration solarDuration) Increments this LST by the given amount of solar time.
LocalSiderealTime	advanceTo(TimeOfDay lstTimeOfDay) Advances this LST to the given time of day.
LocalSiderealTime	clone() Returns a copy of this LST.
int	compareTo(LocalSiderealTime other)
boolean	equals(Object o) Returns true if o is equal to this LST.
int	getDayNumber() Returns the VLA-scheduling day number for this LST.
Longitude	getHourAngle(Longitude rightAscension) Returns the hour angle for the given right ascension at this LST.
Longitude	getLocation() Returns a copy of the location on which this LST is based.
Longitude	getRightAscension(Longitude hourAngle) Returns the right ascension for the given hour angle at this LST.
TimeZone	getTimeZone() Returns a copy of the time zone on which this LST is based.
int	hashCode() Returns a hash code value for this LST.
boolean	isAfter(LocalSiderealTime other) Returns true if this LST is later than other.
boolean	isBefore(LocalSiderealTime other) Returns true if this LST is earlier than other.
LocalSiderealTime	set(int year, int month, int day, int lstHour, int lstMinute, BigDecimal lstSecond) Sets the local solar calendar date and the local sidereal time.
LocalSiderealTime	set(int year, int month, int day, int lstHour, int lstMinute, String lstSecond) Sets the local solar calendar date and the local sidereal time.
LocalSiderealTime	setLocationAndTimeZone(Longitude newLongitude, TimeZone newTimeZone) Changes the location and time zone for which this LST is valid.
LocalSiderealTime	setSiderealTime(int localSiderealDay, TimeOfDay localSiderealTime) Sets this LST to the given day and time of day.
LocalSiderealTime	setSiderealTime(TimeOfDay lst) Sets this LST to the given day and time of day.
LocalSiderealTime	setSolarTime() Sets the solar time on which this LST is based to the current system time.
LocalSiderealTime	setSolarTime(Date gregorianCalendarDate) Sets the solar time on which this LST is based to the given time.
LocalSiderealTime	setSolarTime(JulianDate julianDate) Sets the solar time on which this LST is based to the given time.
TimeDuration	siderealTimeUntil(Date otherSolar) Returns a duration, in sidereal time, from this LST to otherSolar.
TimeDuration	siderealTimeUntil(JulianDate otherSolar) Returns a duration, in sidereal time, from this LST to otherSolar.
TimeDuration	siderealTimeUntil(LocalSiderealTime otherSidereal) Returns a duration, in sidereal time, from this LST to otherSidereal.
static TimeDuration	siderealToSolar(TimeDuration siderealDuration) Returns a duration in solar time that is equivalent to the given sidereal duration.
TimeDuration	solarTimeUntil(Date otherSolar) Returns a duration, in solar time, from this LST to otherSolar.
TimeDuration	solarTimeUntil(JulianDate otherSolar) Returns a duration, in solar time, from this LST to otherSolar.
TimeDuration	solarTimeUntil(LocalSiderealTime otherSidereal) Returns a duration, in solar time, from this LST to otherSidereal.
static TimeDuration	solarToSidereal(TimeDuration solarDuration) Returns a duration in sidereal time that is equivalent to the given solar duration.
LocalSiderealTime	subtractSidereal(TimeDuration siderealDuration) Decrements this LST by the given amount of sidereal time.
LocalSiderealTime	subtractSolar(TimeDuration solarDuration) Decrements this LST by the given amount of solar time.
Date	toDate() Returns a copy of the solar date and time corresponding to this LST.
JulianDate	toJulianDate() Returns a copy of the Julian Date corresponding to this LST.
String	toString()
TimeOfDay	toTimeOfDay() Returns this LST as a dateless object.
TimeOfDay	toTimeOfDaySolar() Returns the local solar time of day for this LST.
TimeOfDay	toTimeOfDayUtc() Returns the UTC solar time of day for this LST.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LocalSiderealTime

public LocalSiderealTime()

Creates a new local sidereal time based on the current solar time and the longitude and time zone of the VLA.

LocalSiderealTime

public LocalSiderealTime(Date gregorianCalendarDate)

Creates a new local sidereal time based on the given solar time and the longitude and time zone of the VLA.

Parameters:

gregorianCalendarDate - a solar time based on the Gregorian calendar. A value of null will be intrepeted as the current system time.

LocalSiderealTime

public LocalSiderealTime(JulianDate julianDate)

Creates a new local sidereal time based on the given solar time and the longitude and time zone of the VLA.

Parameters:

julianDate - a solar time in Julian Date form. A value of null will be intrepeted as the current system time.

LocalSiderealTime

public LocalSiderealTime(int localSiderealDay,
                         TimeOfDay localSiderealTime)

Parameters:

localSiderealDay -

localSiderealTime -

LocalSiderealTime

public LocalSiderealTime(Date gregorianCalendarDate,
                         Longitude longitude,
                         TimeZone timeZone)

Creates a new local sidereal time based on the given parameters

Parameters:

gregorianCalendarDate - a solar time based on the Gregorian calendar. A value of null will be intrepeted as the current system time.

longitude - the longitude for which this LST applies. A value of null will result in a NullPointerException.

timeZone - the time zone at the location for which this LST applies. A value of null will result in a NullPointerException.

Method Detail

setLocationAndTimeZone

public LocalSiderealTime setLocationAndTimeZone(Longitude newLongitude,
                                                TimeZone newTimeZone)

Changes the location and time zone for which this LST is valid.

Parameters:

newLongitude - the new location on which this LST is based. A value of null will result in a NullPointerException.

newTimeZone - the time zone corresponding to the new location. A value of null will result in a NullPointerException.

Returns:

this LST.

setSolarTime

public LocalSiderealTime setSolarTime()

Sets the solar time on which this LST is based to the current system time.

Returns:

this LST.

setSolarTime

public LocalSiderealTime setSolarTime(Date gregorianCalendarDate)

Sets the solar time on which this LST is based to the given time.

Parameters:

gregorianCalendarDate - a solar time based on the Gregorian calendar.

Returns:

this LST.

setSolarTime

public LocalSiderealTime setSolarTime(JulianDate julianDate)

Sets the solar time on which this LST is based to the given time.

Parameters:

julianDate - a solar time in Julian Date form.

Returns:

this LST.

setSiderealTime

public final LocalSiderealTime setSiderealTime(int localSiderealDay,
                                               TimeOfDay localSiderealTime)

Sets this LST to the given day and time of day.

Parameters:

localSiderealDay - the sidereal day to which this LST should be set. Remember that this class is similar to java's Date class in that it is real a date/timestamp class. This value is based on the VLA LST-day concept, but is not specific to that longitude. The UTC corresponding to local sidereal day zero and local sidereal time zero varies with longitude, but is on December 6 or 7 of 1840, arrived at empirically. Day / time zero is just an arbitrary epoch for beginning a count of sidereal time.

localSiderealTime - the local sidereal time of day.

Returns:

this LST.

Since:

2008-09-25

setSiderealTime

public final LocalSiderealTime setSiderealTime(TimeOfDay lst)

Sets this LST to the given day and time of day. The local sidereal day will not be changed.

Parameters:

lst - the local sidereal time of day.

Returns:

this LST.

Since:

2008-09-25

set

public LocalSiderealTime set(int year,
                             int month,
                             int day,
                             int lstHour,
                             int lstMinute,
                             BigDecimal lstSecond)

Sets the local solar calendar date and the local sidereal time.

Date Parameters
The year, month, and day parameters all refer to our standard notion of a calendar date, such as February 22, 2008. This is a solar, not sidereal, date and is understood to refer to a date for the current time zone of this instance. (See setLocationAndTimeZone(Longitude, TimeZone).) The parameters follow the conventions set forth in Calendar.set(int, int, int). This method will not check the values of these parameters, but will instead delegate that job to the Calendar.set method.

Time Parameters
The lstHour, lstMinute, and lstSecond parameters are all local sidereal time values. This method will use TimeOfDay.set(int, int, BigDecimal) to validate these values and will rethrow any exceptions encountered.

Example
Let's say you want to configure an instance of this class so that it is set to LST 12:34:56.789 on July 3, 2008 for the VLA. The default location and time zone for instances of this class are those of the VLA, so you need do nothing regarding longitude and time zone. The code set the date and time given above is:

   LocalSiderealTime schedTime = new LocalSiderealTime();
   schedTime.set(2008, 6, 3, 12, 34, 56.789);

Note that July is 6, not 7, due to the conventions of the Calendar class. If you were then to write this code:

   System.out.println(schedTime.toDate());

You should see that if the date is expressed as a Mountain Daylight Time value, the date is July 3, 2008 and that the time of day is some value that in all likelihood is not 12:34:56.789.

Days That Contain Two of the Given LST Values
Since a sidereal day is shorter than a solar day by about four minutes, there are about four minutes of an LST day that show up twice per solar day. This method will always return the earlier of these two times.

Parameters:

year - the calendar year.

month - the calendar month. This is a zero-based value.

day - the day of the calendar month.

lstHour - the local sidereal hour.

lstMinute - the local sidereal minute.

lstSecond - the local sidereal second.

Returns:

this LST after the values have been set.

Throws:

IllegalArgumentException - if there are problems with the parameter values.

set

public LocalSiderealTime set(int year,
                             int month,
                             int day,
                             int lstHour,
                             int lstMinute,
                             String lstSecond)

Sets the local solar calendar date and the local sidereal time. See set(int, int, int, int, int, BigDecimal) for more details.

Returns:

this LST after the values have been set.

getLocation

public Longitude getLocation()

Returns a copy of the location on which this LST is based.

Returns:

a copy of the location on which this LST is based.

getTimeZone

public TimeZone getTimeZone()

Returns a copy of the time zone on which this LST is based.

Returns:

a copy of the time zone on which this LST is based.

getDayNumber

public int getDayNumber()

Returns the VLA-scheduling day number for this LST. This concept is not universal, but is specific to the VLA. We probably will not need it once we completely replace the VLA with the EVLA.

Returns:

the VLA scheduler's idea of an LST day number.

isBefore

public boolean isBefore(LocalSiderealTime other)

Returns true if this LST is earlier than other. (Remember that this class treats LST as a date/time, not a dateless time.)

Parameters:

other - the LST to be tested against this one.

Returns:

true if this LST is earlier than other.

isAfter

public boolean isAfter(LocalSiderealTime other)

Returns true if this LST is later than other. (Remember that this class treats LST as a date/time, not a dateless time.)

Parameters:

other - the LST to be tested against this one.

Returns:

true if this LST is later than other.

getHourAngle

public Longitude getHourAngle(Longitude rightAscension)

Returns the hour angle for the given right ascension at this LST.

Parameters:

rightAscension - the right ascension for which an hour angle is desired.

Returns:

an hour angle that is equal to this LST minus rightAscension.

getRightAscension

public Longitude getRightAscension(Longitude hourAngle)

Returns the right ascension for the given hour angle at this LST.

Parameters:

hourAngle - the hour angle for which a right ascension is desired.

Returns:

a right ascension that is equal to this LST minus hourAngle.

toJulianDate

public JulianDate toJulianDate()

Returns a copy of the Julian Date corresponding to this LST.

Returns:

a copy of the Julian Date corresponding to this LST.

toDate

public Date toDate()

Returns a copy of the solar date and time corresponding to this LST.

Returns:

a copy of the solar date and time corresponding to this LST.

toTimeOfDay

public TimeOfDay toTimeOfDay()

Returns this LST as a dateless object. The returned time of day is in sidereal units, with a 24 sidereal hour length of day. The returned time of day is not referenced by this LST, so changes made to it will not be reflected herein.

Returns:

the time portion of this LST.

toTimeOfDaySolar

public TimeOfDay toTimeOfDaySolar()

Returns the local solar time of day for this LST.

Returns:

the local solar time of day for this LST.

Since:

2008-08-14

toTimeOfDayUtc

public TimeOfDay toTimeOfDayUtc()

Returns the UTC solar time of day for this LST.

Returns:

the UTC solar time of day for this LST.

Since:

2008-08-14

toString

public String toString()

Overrides:

toString in class Object

advanceTo

public LocalSiderealTime advanceTo(TimeOfDay lstTimeOfDay)

Advances this LST to the given time of day.

Immediately after this call a call to toTimeOfDay() should return the same time of day as lstTimeOfDay, and a call to getDayNumber() should show that either the day number is the same as it was prior to calling this method, or it has advanced by one day.

Attempting to advance to the current time of day of this LST will leave this LST unchanged. For example, the following code would not change the state of myLst:

   myLst.advanceTo(myLst.toTimeOfDay());

Parameters:

lstTimeOfDay - the new time of day for this LST date/time object.

Returns:

this LST, after the advancement.

addSidereal

public LocalSiderealTime addSidereal(TimeDuration siderealDuration)

Increments this LST by the given amount of sidereal time.

Parameters:

siderealDuration - the amount of solar time by which to increment this LST.

Returns:

this LST, after the addition.

See Also:

addSolar(TimeDuration)

subtractSidereal

public LocalSiderealTime subtractSidereal(TimeDuration siderealDuration)

Decrements this LST by the given amount of sidereal time.

Parameters:

siderealDuration - the amount of solar time by which to decrement this LST.

Returns:

this LST, after the subtraction.

See Also:

subtractSolar(TimeDuration)

addSolar

public LocalSiderealTime addSolar(TimeDuration solarDuration)

Increments this LST by the given amount of solar time.

Parameters:

solarDuration - the amount of solar time by which to increment this LST.

Returns:

this LST, after the addition.

See Also:

addSidereal(TimeDuration)

subtractSolar

public LocalSiderealTime subtractSolar(TimeDuration solarDuration)

Decrements this LST by the given amount of solar time.

Parameters:

solarDuration - the amount of solar time by which to decrement this LST.

Returns:

this LST, after the subtraction.

See Also:

subtractSidereal(TimeDuration)

siderealTimeUntil

public TimeDuration siderealTimeUntil(LocalSiderealTime otherSidereal)

Returns a duration, in sidereal time, from this LST to otherSidereal. If this LST is after the other time, the returned duration will have zero length. (Remember that this LST is really a date/time, not a time-of-day.)

To get behavior similar to TimeOfDay.timeUntil(TimeOfDay), use this pattern:

   TimeDuration lstDur = myLst.toTimeOfDay().timeUntil(yourLst.timeOfDay());

Parameters:

otherSidereal - another point in time, expressed in sidereal time.

Returns:

the amount of sidereal time from this LST to otherSidereal.

siderealTimeUntil

public TimeDuration siderealTimeUntil(Date otherSolar)

Returns a duration, in sidereal time, from this LST to otherSolar. If this LST is after the other time, the returned duration will have zero length. (Remember that this LST is really a date/time, not a time-of-day.)

Parameters:

otherSolar - another point in time, expressed in solar time.

Returns:

the amount of sidereal time from this LST to otherSolar.

siderealTimeUntil

public TimeDuration siderealTimeUntil(JulianDate otherSolar)

Returns a duration, in sidereal time, from this LST to otherSolar. If this LST is after the other time, the returned duration will have zero length. (Remember that this LST is really a date/time, not a time-of-day.)

Parameters:

otherSolar - another point in time, expressed in solar time.

Returns:

the amount of sidereal time from this LST to otherSolar.

solarTimeUntil

public TimeDuration solarTimeUntil(LocalSiderealTime otherSidereal)

Returns a duration, in solar time, from this LST to otherSidereal. If this LST is after the other time, the returned duration will have zero length. (Remember that this LST is really a date/time, not a time-of-day.)

Parameters:

otherSidereal - another point in time, expressed in sidereal time.

Returns:

the amount of solar time from this LST to otherSidereal.

solarTimeUntil

public TimeDuration solarTimeUntil(Date otherSolar)

Returns a duration, in solar time, from this LST to otherSolar. If this LST is after the other time, the returned duration will have zero length. (Remember that this LST is really a date/time, not a time-of-day.)

Parameters:

otherSolar - another point in time, expressed in solar time.

Returns:

the amount of solar time from this LST to otherSolar.

solarTimeUntil

public TimeDuration solarTimeUntil(JulianDate otherSolar)

Returns a duration, in solar time, from this LST to otherSolar. If this LST is after the other time, the returned duration will have zero length. (Remember that this LST is really a date/time, not a time-of-day.)

Parameters:

otherSolar - another point in time, expressed in solar time.

Returns:

the amount of solar time from this LST to otherSolar.

solarToSidereal

public static TimeDuration solarToSidereal(TimeDuration solarDuration)

Returns a duration in sidereal time that is equivalent to the given solar duration.

Parameters:

solarDuration - a duration whose units are based on solar time.

Returns:

a duration whose units are based on sidereal time and whose length is equivalent to that of solarDuration.

siderealToSolar

public static TimeDuration siderealToSolar(TimeDuration siderealDuration)

Returns a duration in solar time that is equivalent to the given sidereal duration.

Parameters:

siderealDuration - a duration whose units are based on sidereal time.

Returns:

a duration whose units are based on solar time and whose length is equivalent to that of siderealDuration.

clone

public LocalSiderealTime clone()

Returns a copy of this LST.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this LST.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this LST.

Overrides:

hashCode in class Object

compareTo

public int compareTo(LocalSiderealTime other)

Specified by:

compareTo in interface Comparable<LocalSiderealTime>