Source code for irfpy.cena.cena_time

''' CENA time module.

Module related to CENA's time.
This provides methods as follows:

- Accumulation time, or time resoultion in other word
    (:func:`accumulation_time` and identical method :func:`time_resolution`.)
'''

import warnings
import datetime


def accumulation_time(outfmt=None):
    ''' Return the accumulation time of CENA.

    The accumulation time of CENA in seconds, i.e. 4.0.

    :param outfmt: If format is in ``datetime.timedelta``,
        the returned format is in ``datetime.timedelta``.
    :type outfmt: ``None`` or ``datetime.timedelta``.
    :returns: The time of accumulation in seconds.
    :rtype: ``Float`` or ``datetime.timedelta`` up to outfmt parameter.
    '''
    if outfmt is None:
        return 4.0
    elif outfmt == datetime.timedelta:
        return datetime.timedelta(seconds=4)
    else:
        raise RuntimeError('Unknown outfmt [%s]. %s' %
                           (outfmt, '(None or datetime.timedelta is accepted)'))


def time_resolution(outfmt=None):
    ''' An alias to the :meth:`accumulation_time()` function.
    '''
    return accumulation_time(outfmt=outfmt)

def dead_time(outfmt=None):
    ''' Dead time during one slot.  This is constantly 25% of :meth:`slot_time`.

    :param outfmt: If format is in ``datetime.timedelta``,
        the returned format is in ``datetime.timedelta``.
    :type outfmt: ``None`` or ``datetime.timedelta``.
    :returns: The dead time, i.e. 0.078125 in float.

    >>> print('%.7f' % dead_time())
    0.0078125
    >>> print(dead_time(outfmt=datetime.timedelta))
    0:00:00.007812
    '''
    if outfmt is None:
        return 31.25e-3 * 0.25
    elif outfmt == datetime.timedelta:
        warnings.warn("deat_time method for timedelta instance has suffered by rounding.")
        return datetime.timedelta(microseconds=31250*0.25)
    else:
        raise RuntimeError('Unknown outfmt [%s]. %s' %
                           (outfmt, '(None or datetime.timedelta is accepted)'))

def slot_time(outfmt=None):
    ''' Time step changing the energy setting.

    CENA changes energy setting every 31.25 msec.
    This returns the value in seconds in ``float`` or ``datetime.timedelta``.

    :param outfmt: If format is in ``datetime.timedelta``,
        the returned format is in ``datetime.timedelta``.
    :type outfmt: ``None`` or ``datetime.timedelta``.
    :returns: The slot time, i.e. 0.03125 in float.
    :rtype: ``Float`` or ``datetime.timedelta`` up to outfmt parameter.
    '''
    if outfmt is None:
        return 31.25e-3
    elif outfmt == datetime.timedelta:
        return datetime.timedelta(microseconds=31250)
    else:
        raise RuntimeError('Unknown outfmt [%s]. %s' %
                           (outfmt, '(None or datetime.timedelta is accepted)'))


def duty_time(outfmt=None):
    r''' Duty time for CENA for single energy step.

    CENA duty time for each channel is
    :math:`4 \mathrm{s} \div 8 \mathrm{[energy~step]} \times 75\% = 375 \mathrm{ms}`.
    This returns the value in seconds in ``float`` or ``datetime.timedelta``.

    :param outfmt: If format is in ``datetime.timedelta``,
        the returned format is in ``datetime.timedelta``.
    :type outfmt: ``None`` or ``datetime.timedelta``.
    :returns: The slot time, i.e. 0.375 in float.
    :rtype: ``Float`` or ``datetime.timedelta`` up to outfmt parameter.
    '''
    if outfmt is None:
        return 0.375
    elif outfmt == datetime.timedelta:
        return datetime.timedelta(microseconds=375000)
    else:
        raise RuntimeError('Unknown outfmt [%s]. %s' %
                           (outfmt, '(None or datetime.timedelta is accepted)'))

def deltaT(outfmt=None):
    r''' Time interval for CENA for single energy step.

    :math:`4 \mathrm{s} \div 8 \mathrm{[energy~step]} = 500 \mathrm{ms}`.
    This returns the value in seconds in ``float`` or ``datetime.timedelta``.

    :param outfmt: If format is in ``datetime.timedelta``,
        the returned format is in ``datetime.timedelta``.
    :type outfmt: ``None`` or ``datetime.timedelta``.
    :returns: The slot time, i.e. 0.5 in float.
    :rtype: ``Float`` or ``datetime.timedelta`` up to outfmt parameter.
    '''
    if outfmt is None:
        return 0.5
    elif outfmt == datetime.timedelta:
        return datetime.timedelta(microseconds=500000)
    else:
        raise RuntimeError('Unknown outfmt [%s]. %s' %
                           (outfmt, '(None or datetime.timedelta is accepted)'))