org.jscience.astronomy.solarsystem
Class JulianTime

java.lang.Object
  extended by org.jscience.astronomy.solarsystem.JulianTime

public class JulianTime
extends java.lang.Object

The JulianTime class stores Julian Day (minus 2450000 d) and allows setting and retrieval of time in various forms. The stored time is UT rather than TT, TD, ET or TAI. See the DeltaT method for the difference between these time scales.

While GST (Greenwich Sidereal Time) is a time proper, LST (local sidereal time) is part of the parametrisation of your location. It is not dealt with by this class.

The storage of time is as JD minus 2450000 d. This means UT 2000-01-01-12:00:00 is stored as 1545.0. The numeric precision should be good enough for 1200 centuries either side of J2000 to represent time to a millisecond. While for internal consumption within the software we always use JD-2450000, when writing the JD to terminal or file and when reading it from the command line, we use JD itself.

Copyright: © 2002-2003 Horst Meyerdierks.

This programme is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This programme is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this programme; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

$Id: JulianTime.java,v 1.3 2007/10/21 21:07:05 virtualcall Exp $

2.10: 2002/09/15 hme
Package review.
2.7: 2002/09/15 hme
Fix bug whereby in years -3 to -1 the JD to date conversion was wrong by one day.
2.6: 2002/09/15 hme
Review, setUniversalTime may raise exception now.
2.4: 2002/09/15 hme
Make init() independent of SetUTSystem().
2.3: 2002/09/15 hme
Change copy() interface to make it overridable.
2.2: 2002/09/15 hme
Methods that change the time no longer final.
1.15: 2002/07/13 hme
Consolidate documentation.
1.14: 2002/07/02 hme
copy() method.
1.13: 2002/06/23 hme
Move CommandTime() to Telescope subclass.
1.10: 2002/06/15 hme
Move CommandShow() to Station subclass.
1.8: 2002/06/14 hme
add() and subtract() methods.
1.6: 2002/06/09 hme
Translated from C++ after Times class was finalised in the prospective version 2 of Sputnik.

See Also:
org.jscience.astronomy.solarsystem

Constructor Summary
JulianTime()
          Set the time from the system clock.
JulianTime(double aJD)
          Set the time to the given Julian Day (UT).
JulianTime(JulianTime aTime)
           
 
Method Summary
 void add(double aTimeStep)
          Add to the time.
 double[] getDate()
          Return date (UT) as triplet.
 double getGreenwichSideralTime()
          Return Greenwich Sidereal Time.
 double[] getGreenwichSideralTimehms()
          Return Greenwich Sidereal Time as triplet.
 double getJulianDay()
          Return the Julian Day (UT).
 double getJulianEphemerisDay()
          Return the Julian Ephemeris Day (TT).
 double getJulianEpoch()
          Return the Julian Epoch.
 double getTerrestrialTime()
          Return Terrestrial Time.
 double[] getTerrestrialTimeDate()
          Return date (TT) as triplet.
 double[] getTerrestrialTimehms()
          Return Terrestrial Time as triplet.
 double getUniversalTime()
          Return Universal Time.
 double[] getUniversalTimehms()
          Return Universal Time as triplet.
 void setTerrestrialTime(int aYear, int aMonth, int aDay, double anHour, double aMinute, double aSecond)
          Set the time to the given date and time (TT).
 void setUniversalTime(int aYear, int aMonth, int aDay, double aHour, double aMinute, double aSecond)
          Set the time to the given date and time (UT).
 void showToFile(java.io.PrintStream aFile)
          Display the time in various representations.
 double subtract(JulianTime aTime)
          Return difference between two times.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JulianTime

public JulianTime()
Set the time from the system clock.

This obtains UTC from the system clock. This is assumed to be UT and converted to JD, which is the native storage form.


JulianTime

public JulianTime(double aJD)
Set the time to the given Julian Day (UT).

This takes the JD (minus 2450000 days) and stores it. The given Julian Day therefore must be UT and not TT.

See setUniversalTime for information about the relationship between calendars and Julian Day.

Parameters:
aJD - The Julian Day minus 2.45 million days that is to be stored.

JulianTime

public JulianTime(JulianTime aTime)
Method Detail

add

public void add(double aTimeStep)
Add to the time.

Adds the given time difference (in days) to the time in this instance of the class.

Parameters:
aTimeStep - The time increment to apply.

subtract

public double subtract(JulianTime aTime)
Return difference between two times.

Returns the time difference (in days) between this instance of the class and the given instance of the class (this minus given).

Parameters:
aTime - The other time, which is to be subtracted from the time stored in this instance of the class.

getDate

public double[] getDate()
Return date (UT) as triplet.

This returns the calendar date (UT) as a triplet of year, month (1-12) and day (1-31). The calendar used is Julian before 1582-10-15, Gregorian after. All three values are integer, though their storage type is double precision floating point.

See setUniversalTime for information about the two calendars and their relationship with Julian Day.

Returns:
The returned triplet of year, month and day.

getGreenwichSideralTime

public double getGreenwichSideralTime()
Return Greenwich Sidereal Time.

This returns the Greenwich Sidereal Time (sidereal time since previous culmination of the mean equinox at the longitude of Greenwich) in hours. The value is calculated based on the expression given by USNO/RGO, 1990, The Astronomical Almanach for the Year 1992, U.S. Government Printing Office, Washington DC, Her Majesty's Stationery Office, London, p.B6, but where only the fraction of a full rotation is carried forward in each step.

u = JD - JD(midnight)

t = [JD(midnight) - 2451545] / 36525 d

GST = 6.69737456 h + 100 d * t + 2.1390378E-3 d * t
+ 1.07759E-6 d * t2 - 7.1759E-11 d * t3 + 1.00273791 * u


getGreenwichSideralTimehms

public double[] getGreenwichSideralTimehms()
Return Greenwich Sidereal Time as triplet.

This returns the Greenwich Sidereal Time as a triplet of hours (0-23), minutes (0-59) and seconds (0-60.0).

See getGreenwichSiderealTime for more information on GST.

Returns:
The returned triplet of hours, minutes and seconds.

getJulianDay

public double getJulianDay()
Return the Julian Day (UT).

This returns the Julian Day (JD, UT) minus 2450000 days. The value is of course in days.

See setUniversalTime for information about the relationship between the calendars and Julian Day.


getJulianEphemerisDay

public double getJulianEphemerisDay()
Return the Julian Ephemeris Day (TT).

This returns the Julian Ephemeris Day (JDE, TT) minus 2450000 days. The value is of course in days.

See setUniversalTime for information about the relationship between the calendars and Julian Day. See DeltaT for information about the difference between Universal Time (UT) and Terrestrial Time (TT), Temps Dynamique (TD) and Ephemeris Time (ET).


getJulianEpoch

public double getJulianEpoch()
Return the Julian Epoch.

This returns the Julian Epoch in years. This is always TT and not UT. The unit is Julian years (365.25 d) and the fix point is such that J2000.0 is TT 2000-01-01.5 or JDE 2451545.0.

Ep = 2000 + (JDE - 2451545) / 365.25

Note that the difference between TT and UT is only on the order of 0.0014 d or 0.000004 year. But the epoch is normally used in the context of the Solar System or stellar proper motion, not where we care about the rotation state of the Earth. So to base it on TT is more natural. Standard UT epochs are (USNO/RGO, 1990, The Astronomical Almanach for the Year 1992, U.S. Government Printing Office, Washington DC, Her Majesty's Stationery Office, London, p.B4):

1900.0 UT 1900-01-00.5JD 2415020.000
B1950.0 UT 1950-01-00.923JD 2433282.423
J2000.0 UT 2000-01-01.5JD 2451545.0
  UT 1970-01-01.0JD 2440587.5


getTerrestrialTime

public double getTerrestrialTime()
Return Terrestrial Time.

This returns the Terrestrial Time (the time since previous midnight TT) in hours.

See DeltaT for more information about Terrestrial Time (TT), Temps Dynamique (TD) and Ephemeris Time (ET), and their difference to Universal Time (UT).


getTerrestrialTimeDate

public double[] getTerrestrialTimeDate()
Return date (TT) as triplet.

This returns the calendar date (TT) as a triplet of year, month (1-12) and day (1-31). The calendar used is Julian before 1582-10-15, Gregorian after. All three values are integer, though their storage type is double precision floating point.

See setUniversalTime for information about the two calendars and their relationship with Julian Day.

Returns:
The returned triplet of year, month and day.

getTerrestrialTimehms

public double[] getTerrestrialTimehms()
Return Terrestrial Time as triplet.

This returns the Terrestrial Time (the time since previous midnight TT) as a triplet of hours (0-23), minutes (0-59) and seconds (0-60.0).

See DeltaT for more information about Terrestrial Time (TT), Temps Dynamique (TD) and Ephemeris Time (ET), and their difference to Universal Time (UT).

Returns:
The returned triplet of hours, minutes and seconds.

getUniversalTime

public double getUniversalTime()
Return Universal Time.

This returns the Universal Time (the time since previous midnight UT) in hours.


getUniversalTimehms

public double[] getUniversalTimehms()
Return Universal Time as triplet.

This returns the Universal Time (the time since previous midnight UT) as a triplet of hours (0-23), minutes (0-59) and seconds (0-60.0).

Returns:
The returned triplet of hours, minutes and seconds.

setTerrestrialTime

public void setTerrestrialTime(int aYear,
                               int aMonth,
                               int aDay,
                               double anHour,
                               double aMinute,
                               double aSecond)
                        throws java.lang.Exception
Set the time to the given date and time (TT).

This takes a time (TT) in the form of year, month, day, hour, minute and second, converts it to JDE and then to JD (UT), which is the native storage form. Since TT - UT is defined as a function of UT and not of TT, this is not entirely precise. A second order approximation is used in the conversion.

This method uses setUniversalTime, which may run into trouble to to with the transition between Julian and Gregorian calendars.

See setUniversalTime for the relationship between the calendars and Julian Day. See DeltaT for the difference between TT and UT.

Parameters:
aYear - The calendar year.
aMonth - The calendar month.
aDay - The calendar day.
anHour - The TT hour.
aMinute - The TT minute.
aSecond - The TT second.
Throws:
java.lang.Exception

setUniversalTime

public void setUniversalTime(int aYear,
                             int aMonth,
                             int aDay,
                             double aHour,
                             double aMinute,
                             double aSecond)
                      throws java.lang.Exception
Set the time to the given date and time (UT).

This takes a time (UT) in the form of year, month, day, hour, minute and second and converts it to JD, which is the native storage form. There is the possibility of failure, if the time is close to the Gregorian calendar reform (1582-10-15) and if the day of the month is given out of range. It is then possible that the wrong calendar is assumed to be in force. The routine will spot this after the fact; it will throw an exception in this event and will set the time to 1582-10-15-00:00:00.

A 1st of March in the Gregorian and Julian calendars convert to Julian Day as

JD(G Y-03-01) = 2445643.5 + 365 (Y - 1985) + [Y/4] - [Y/100] + [Y/400]

JD(J Y-03-01) = 2445641.5 + 365 (Y - 1985) + [Y/4]

The square brackets indicate the floor() function.

The calendar we use is Gregorian, which is an imprecise statement (Jean Meeus, 1991, Astronomical Algorithms, Willmann-Bell, Richmond VA, p.59ff). Before 1582-10-04 the calendar coincides roughly with the Julian calendar, i.e. there is a leap day in every year that is divisible by 4, including the year 4, 0, -4, -8 etc. The Julian calendar was introduced only with the year -44, was miscalculated until -7 and corrected only by the year +8 (István Hahn, 1989, Sonnentage - Mondjahre, Über Kalendersysteme und Zeitrechnung, Urania, Leipzig, Jena, Berlin, p. 55). Here we ignore such details, and this seems to be confirmed by a test that J -4712-01-01-12:00:00 is indeed calculated as JD 0.0. 1582-10-04-23:59:60 is followed immediately by 1582-10-15-00:00:00 (JD 2299160.5) and from then on 1700, 1800 and 1900 have not been leap years (1600 and 2000 have been leap years). In fact, the change to the new calendar was made at different times in different countries, because it was instigated by the Catholic church. The Protestant Länder in Germany waited until 1700-02-19, England converted in 1753, Russia in January 1918. Red Hat GNU/Linux shows 1752-09-02 being followed by 1752-09-14. Apparently this is based on BSD Unix and we have to assume that this is a US convention. The difference between the two calendars in 1582 was 10 days and in 1900 increased to 13 days.

Before Christ there is a difference of one between the historical and the astronomical year count. Historians have the year 1 AD preceded by the year 1 BC, which to astronomers is the year 0. So, for example, the year -4 is also called 5 BC.

Some important UT times are (USNO/RGO, 1990, The Astronomical Almanach for the Year 1992, U.S. Government Printing Office, Washington DC, Her Majesty's Stationery Office, London, p.B4):

1900.0 UT 1900-01-00.5JD 2415020.000
B1950.0 UT 1950-01-00.923JD 2433282.423
J2000.0 UT 2000-01-01.5JD 2451545.0
  UT 1970-01-01.0JD 2440587.5
  UT 1582-10-15.0JD 2299160.5
  UT -4712-01-01.5JD 0.0

Parameters:
aYear - The calendar year.
aMonth - The calendar month.
aDay - The calendar day.
aHour - The UT hour.
aMinute - The UT minute.
aSecond - The UT second.
Throws:
java.lang.Exception

showToFile

public void showToFile(java.io.PrintStream aFile)
Display the time in various representations.

This writes information about the currently stored time to the given open file. The format is

 UT: 1987-04-10-19:21:00.0 (JD  2446896.306250)
 TT: 1987-04-10-19:22:27.1 (JDE 2446896.307258)
 Ep: 1987.272572919
 GST 08:34:57.1 = 128.737874 deg
 

Parameters:
aFile - The output stream to which to write the information.