Source code for irfpy.swim.SwimTime

'''SWIM observation time related class
'''
import datetime

def duty_time():
    ''' Returns SWIM duty time for each measurement (1 energy step and 1 deflection scan), i.e. 0.03125 sec.

    >>> print(duty_time())
    0.03125
    '''
    return 0.03125

def duty_time_timedelta():
    ''' Returns SWIM duty time (31.25 msec) as in datetime.timedelta instance
    
    See also :func:`duty_time`

    >>> print(duty_time_timedelta())
    0:00:00.031250
    '''
    return datetime.timedelta(0, 0, 31250)

def time_resolution():
    ''' Returns SWIM measurement cycle.  It is 8 sec.

    >>> print(time_resolution())
    8.0
    '''
    return 8.0

def time_resoultion_timedelta():
    ''' Returns SWIM measurement cycle in datetime.timedelta instance.

    >>> print(time_resoultion_timedelta())
    0:00:08
    '''
    return datetime.timedelta(0, 8)

def time_offset(ae, ad):
    ''' Returns the offset of the measurement of the specified energy step and the specified deflection bins.

    Args:
        ae: Energy step bins.  0..15
        ad: Deflection bins.  0..15
    Returns:
        offset: offset in sec with relative to the start of measurement

    The scan of the measurement takes time, so, correction is needed to know the exact timing.
    The scanning mechanism is as follows.
    The deflection scan is first, and energy follows.
    In case of SWIM, the maximum energy step is 16 and deflection bins is 16.
    Because of historical reasons, the scan is like follows:
    (0,0) (0,2) (0,4) ... (0,14) (0,1) (0,3) ... (0,13) (0,15) (1,0) (1,2) ... (1,13) (1,15) ...,
    where each value is expressed as (ae,ad).
    Each scan takes 31.25 msec (duty_time()).

    .. todo::

        Check whether getUtc in libsadppac obtains the 'start' or 'end' of the time observed?

    >>> print(time_offset(0, 0))
    0.0
    >>> print(time_offset(0, 1))
    0.25
    >>> print(time_offset(0, 2))
    0.03125
    >>> print(time_offset(7, 15))
    3.96875
    '''

    order = ae*16 + (ad>>1) + 8*(ad&1)

    return order*duty_time();

def time_offset_timedelta(ae, ad):
    ''' Returns the offset of the measurement of the specified energy step and the specified deflection bins as timedelta instance.

    See also :func:`time_offset`

    >>> print(time_offset_timedelta(0, 0))
    0:00:00
    >>> print(time_offset_timedelta(0, 1))
    0:00:00.250000
    >>> print(time_offset_timedelta(0, 2))
    0:00:00.031250
    >>> print(time_offset_timedelta(7, 15))
    0:00:03.968750
    '''
    dt = time_offset(ae, ad)
    return datetime.timedelta(0, dt)