sidereal.py: Internal maintenance specification

Given a datetime.datetime instance dt, this method returns the Greenwich Sidereal Time at the UTC time represented by dt. In Duffett-Smith, this is section 12. Constant C is defined as “1.002 738”.

# - - -   S i d e r e a l T i m e . f r o m D a t e t i m e

    SIDEREAL_C  =  1.002738

#   @staticmethod
    def fromDatetime ( dt ):
        """Convert civil time to Greenwich Sidereal.

          [ dt is a datetime.datetime instance ->
              if  dt has time zone information ->
                return the GST at the UTC equivalent to dt
              else ->
                return the GST assuming dt is UTC ]
        """

First we have to convert dt to UTC. This involves finding out whether dt is naive (devoid of time zone information) or aware (fully supplied with time zone information).

According to the documentation for Python's datetime module, the test for awareness has two parts: the instance's tzinfo attribute must be not None, and dt.tzinfo.utcoffset(dt) must not be None.

If both these conditions are true, the value returned by dt.tzinfo.utcoffset(dt) is the difference between UTC and the local time: positive for local times east of Greenwich, negative for west. The value may be either a number expressed in minutes, or a datetime.timedelta instance, with the shift expressed in minutes. In either case, we can subtract the value from dt to get the UTC as a new datetime.datetime instance.

        #-- 1 --
        # [ if  dt is naive ->
        #     utc  :=  dt
        #   else ->
        #     utc  :=  the UTC time equivalent to dt ]
        utc  =  dt
        tz  =  dt.tzinfo
        if  tz is not None:
            offset  =  tz.utcoffset ( dt )
            if  offset is not None:
                utc  =  dt - offset

Step 1 in Duffett-Smith says: “Find the number of days between January 0.0 and the date in question.” See Section 9.5, “dayNo(): Date to day number”.

        #-- 2 --
        # [ nDays  :=  number of days between January 0.0 and utc ]
        nDays  =  dayNo ( utc )

In steps 2-3, we compute T₀ as (nDays×A-B). For constant A, see Section 8.5, “SIDEREAL_A: Sidereal time conversion factor”. Factor B is a function of the year number, and is computed in Section 14.4, “SiderealTime.factorB(): Compute sidereal time factor B (static method)”.

        #-- 3 --
        t0  =  ( nDays * SIDEREAL_A -
                 SiderealTime.factorB ( utc.year ) )

Step 4: “Convert GMT to decimal hours.” This conversion uses Section 11, “dmsUnits: Mixed-units converter”.

        #-- 4 --
        # [ decUTC  :=  utc as decimal hours ]
        floatSec  =  utc.second + float ( utc.microsecond ) / 1e6
        decUTC  =  dmsUnits.mixToSingle (
                       (utc.hour, utc.minute, floatSec) )

Step 5: “Multiply by constant C.”, which is defined as “1.002 738”.

Step 6: “Add this to T₀,” which, normalized to the interval [0,24), is the GST in hours. The result is returned as a SiderealTime instance.

        #-- 4 --
        # [ gst  :=  (decUTC * C + t0), normalized to interval [0,24) ]
        gst  =  ( decUTC * SiderealTime.SIDEREAL_C + t0) % 24.0

        #-- 5 --
        return SiderealTime ( gst )

This is a static method.

    fromDatetime  =  staticmethod ( fromDatetime )