sidereal.py: Internal maintenance specification

This method finds the first or only time on a given date when self's Greenwich Sidereal Time (GST) occurs. The date is provided as a datetime.date instance. In Duffett-Smith, this is section 13.

# - - -   S i d e r e a l T i m e . u t c

    def utc ( self, date ):
        """Convert GST to UTC.

          [ date is a UTC date as a datetime.date instance ->
              return the first or only time at which self's GST
              occurs at longitude 0 ]
        """

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

        #-- 1 --
        # [ nDays  :=  number of days between Jan. 0 of year
        #       (date.year) and date ]
        nDays  =  dayNo ( date )

Step 2 is to multiply that by constant A, which in this script is defined in Section 8.5, “SIDEREAL_A: Sidereal time conversion factor”. Step 3 is to subtract factor B, which is a function of the year number; for the computation of this factor, see Section 14.4, “SiderealTime.factorB(): Compute sidereal time factor B (static method)”. Normalize the result of step 3 to range [0,24). This is factor T₀.

        #-- 2 --
        # [ t0  :=  (nDays * A - B(date.year)), normalized to
        #           interval [0,24) ]
        t0  =  ( ( nDays * SIDEREAL_A -
                   SiderealTime.factorB ( date.year ) ) % 24.0 )

Step 4 is to convert the GST to decimal hours. Step 5 is subtract T₀, and renormalize to the interval [0,24).

        #-- 3 --
        # [ t1  :=  ((self in decimal hours)-t0), normalized to
        #           the interval [0,24) ]
        t1  =  ( radiansToHours ( self.radians ) - t0 ) % 24.0

Step 6: “Multiply by constant D (0.997 270). This is the GMT in hours.”

        #-- 4 --
        gmtHours  =  t1 * 0.997270

The result is to be expressed as a datetime.datetime instance. The date portion of this result is just a copy of the date argument. We'll use dmsUnits (see Section 11, “dmsUnits: Mixed-units converter”) to convert whole hours to hours, minutes, and seconds, then break out the microseconds as required by datetime.datetime.

        #-- 5 --
        # [ dt  :=  a datetime.datetime instance whose date comes
        #           from (date) and whose time is (gmtHours)
        #           decimal hours ]
        hour, minute, floatSec  =  dmsUnits.singleToMix ( gmtHours )
        wholeSec, fracSec  =  divmod ( floatSec, 1.0 )
        second  =  int ( wholeSec )
        micros  =  int ( fracSec * 1e6 )
        dt  =  datetime.datetime ( date.year, date.month,
                   date.day, hour, minute, second, micros )
        
        #-- 6 --
        return  dt