%+
% Name:
%    memo_time_keywords_proposal_1.2.tex
%
% Usage:
%    latex memo_time_keywords_proposal_1.2.tex
%
% Description:
%    This document describes a proposal to change some of the time header
%    keywords.
%
% Input:
%
% Output:
%
% Notes:
%
% History:
%    27 Jul 00, created, Glenn E. Allen
%    24 May 01, added DTYCYCLE to DTCOR for secondary frames, Glenn E. Allen
%    03 May 02, fixed the DTCOR spec, GEA
%-

\documentclass{article}

\usepackage{cxo-memo-logo}
\usepackage[dvips]{graphics}
\usepackage{psfig}

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 1. Header

\memobasic{
   Martin Elvis, SDS Group Leader}{
   Glenn Allen, SDS, and Peter Ford, ACIS}{
   ACIS Time Keywords Proposal}{
   1.2}{
   http://space.mit.edu/\~{}gea/docs/memo\_time\_keywords\_proposal\_1.2.ps}{
   /nfs/wiwaxia/h2/gea/sds/docs/memos/memo\_time\_keywords\_proposal\_1.2.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 2. Body

\vspace*{0.3in}
The computation of the FITS header keywords TIMEDEL (including TIMEDELA and 
TIMEDELB) and DTCOR is inaccurate for interleaved mode observations.  Since 
${\rm LIVTIME}n$ ($= {\rm EXPOSUR}n)$ and ${\rm LIVETIME}$ ($= {\rm 
EXPOSURE})$ are derived from DTCOR, the values assigned to these keywords
are also inaccurate for interleaved mode observations. This memo describes 
how TIMEDELA, TIMEDELB, TIMEDEL, DTCOR, ONTIME$n$, ONTIME, LIVTIME$n$, and 
LIVETIME are computed presently and outlines a new set of algorithms that 
can be used to accurately compute these keywords for all of the timed-exposure 
(and continuous-clocking) observing modes.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 3. Present Computation Algorithms

\section{Present Computation Algorithms}

At the moment, for interleaved mode observations:

\begin{itemize}

\item[]
${\rm TIMEDELA} = {\rm the}$ difference between the times reported for 
the primary frame and the first secondary frame.  Since ${\rm TIMEPIXR} = 
0.5$, ${\rm TIMEDELA} = \frac{1}{2} T_{\rm A} + \frac{1}{2} T_{\rm B} + 
T_{\rm FB}$, where $T_{\rm A} = {\rm the}$ duration of the primary frame 
(including the frame-shift time of 0.04104~s), $T_{\rm B} = {\rm the}$ 
duration of each secondary frame (including the frame-shift time of 
0.04104~s), and $T_{\rm FB} = {\rm the}$ duration of the flush proceeding the 
secondary frame(s).

\item[]
${\rm TIMEDELB} = {\rm the}$ difference between the times reported for 
the last secondary frame of a cycle and the following primary frame.  Since 
${\rm TIMEPIXR} = 0.5$, ${\rm TIMEDELB} = \frac{1}{2} T_{\rm A} + \frac{1}{2} 
T_{\rm B} + T_{\rm FA}$, where $T_{\rm FA} = {\rm the}$ duration of the flush 
proceeding the primary frame.

\item[]
${\rm TIMEDEL} = {\rm TIMEDELA} + ({\rm DTYCYCLE} - 1) \times {\rm TIMEDELB}$,
where ${\rm DTYCYCLE} = {\rm the}$ number of secondary frames.

\item[]
${\rm DTCOR} = ( 0.1 \times {\rm EXPTIMEA} + {\rm DTYCYCLE} \times 0.1 \times 
{\rm EXPTIMEB} ) / {\rm TIMEDEL}$, where EXPTIMEA and EXPTIMEB are the 
commanded durations of the primary and secondary frames (which are quantized 
in units of 0.1~s).

\item[]
${\rm ONTIME} = \sum_{i} {\rm GTI}_{i}$.  

\item[]
${\rm LIVETIME} = {\rm EXPOSURE} = {\rm DTCOR} \times {\rm ONTIME}$

\end{itemize}

As an example, consider an observation using ACIS-S with three (${\rm 
DTYCYCLE} = 3$) secondary frames of 3.2~s for each 0.3~s primary frame.  If 
the flush time is 3.12928 s and ${\rm ONTIME} = 10$~ks, the results are 
listed in table~1.

\begin{table}
\begin{center}
\begin{tabular}{l r r }
\multicolumn{3}{c}{Table 1. Example of the Problem}
  \\
\hline
\hline
\multicolumn{1}{c}{Keyword}
  & \multicolumn{1}{c}{Value in Header}
  & \multicolumn{1}{c}{Actual Value}
  \\
\hline
EXPTIMEA
  & 3 ($\times 0.1$~s)
  & 3 ($\times 0.1$~s)
  \\
EXPTIMEB
  & 32 ($\times 0.1$~s)
  & 32 ($\times 0.1$~s)
  \\
TIMEDELA
  & 1.79104~s
  & 0.34104~s
  \\
TIMEDELB
  & 4.92032~s
  & 3.24104~s
  \\
TIMEDEL
  & 11.63168~s
  & 13.19344~s
  \\
DTCOR
  & 0.85112
  & 0.75037
  \\
LIVETIME
  & 851.12~s
  & 750.37~s
  \\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 4. Proposed Computation Algorithms

\section{Proposed Computation Algorithms}
\label{pro}

A set of algorithms that can be used to accurately determine the values of 
the keywords for interleaved mode observations as well as regular 
timed-exposure observations is:

\begin{itemize}

\item[]
${\rm TIMEDELA} = 0.1\ {\rm s} \times {\rm EXPTIMEA} + 0.04104$~s.  

\item[]
${\rm TIMEDELB} = 0.1\ {\rm s} \times {\rm EXPTIMEB} + 0.04104$~s.

\item[]
${\rm TIMEDEL} = {\rm TIMEDELA}$ or TIMEDELB, as appropriate, for all but 
Level 0 ACIS data products.  Otherwise, tools designed to read TIMEDEL and 
TIMEPIXR can produce inaccurate results.  For the evt0 and exr0 data products, 
${\rm TIMEDEL} = {\rm TIMEDELA} + {\rm FLSHTIMA} + {\rm DTYCYCLE} \times 
({\rm TIMEDELB} + {\rm FLSHTIMB})$ (i.e.\ the total cycle time of one set of 
primary and secondary frames and the associated flushes).

\item[]
FLSHTIMA and FLSHTIMB are new keywords describing the duration of the 
pre-flush before the primary (FLSHTIMA) and secondary (FLSHTIMB) frames.  

\item[]
${\rm FLSHTIME} = {\rm FLSHTIMA}$ or FLSHTIMB, as appropriate.  This keyword is
also new.

\item[]
${\rm ONTIME}n = \sum_{i} {\rm GTI}_{i}$ for ${\rm CCD\_ID} = n$.  ${\rm
ONTIME} = {\rm ONTIME}m$, where $m$ is the CCD\_ID number of the CCD at the 
aim point.  ONTIME includes time intervals for frames during which no events 
are reported, time intervals during which there are flushes, and the 0.04104~s 
intervals during which frames are shifted.  ONTIME does not include time 
intervals during which frames are dropped and the flushes associated with 
these frames.  For interleaved mode observations, ONTIME$n$ and ONTIME are 
computed separately for the primary- and secondary-frame data products.  To 
avoid double counting the time interval associated with each frame, the 
values of ${\rm ONTIME}n$ and ONTIME for the primary-frame data products do 
not include the time intervals associated with the secondary frames and the 
values of ${\rm ONTIME}n$ and ONTIME for the secondary-frame data products 
do not include the time intervals associated with the primary frames.  

\item[]
The GTI boundaries are derived from the data in the exposure records file.
For events that occur during a timed-exposure frame whose time ${\rm 
TIME}_{\rm exr} = t$, the GTI boundaries are given by $t - {\rm TIMEPIXR}_{\rm
exr} \times {\rm TIMEDEL} - {\rm FLSHTIME}_{\rm exr}$ and $t + (1 - {\rm
TIMEPIXR}_{\rm exr}) \times {\rm TIMEDEL}$, where ${\rm TIMEDEL}$, ${\rm 
TIMEPIXR}_{\rm exr}$, and ${\rm FLSHTIME}_{\rm exr}$ are keywords in the 
exposure records file.  Therefore, timed-exposure GTIs are integer multiples 
of ${\rm TIMEDEL} + {\rm FLSHTIME}$.  For events that occur during a
continuous-clocking frame whose time ${\rm TIME}_{\rm exr} = t$, the
boundaries are given by $t - {\rm TIMEPIXR}_{\rm exr} \times {\rm TIMEDEL}$
and $t + (512 - {\rm TIMEPIXR}_{\rm exr}) \times {\rm TIMEDEL}$.  Therefore
continuous-clocking GTIs are integer multiples of $512 \times {\rm 
TIMEDEL}$.

\item[]
DTCOR is computed separately for the data products containing events from the
primary and secondary frames.  For the primary frames,
%
\begin{equation}
{\rm DTCOR} 
   = 
   \frac{
   0.1\ {\rm s} \times {\rm EXPTIMEA}
   }{
   {\rm TIMEDELA} + {\rm FLSHTIMA} 
   }
\end{equation}
%
For the secondary frames,
%
\begin{equation}
{\rm DTCOR} 
   = 
   \frac{
   0.1\ {\rm s} \times {\rm EXPTIMEB}  
   }{
   {\rm TIMEDELB} + {\rm FLSHTIMB}.
   }
\end{equation}
%

\item[]
${\rm LIVTIME}n = {\rm EXPOSUR}n = {\rm DTCOR} \times {\rm ONTIME}n$.
${\rm LIVETIME} = {\rm EXPOSURE} = {\rm EXPOSUR}m$, where $m$ is the CCD\_ID 
number of the CCD at the aim point.  LIVTIME$n$ and LIVETIME are computed 
separately for the data products containing events from the primary and 
secondary frames. 

\end{itemize}

The timed-exposure ACIS data products evt1, evt1a, and evt2 should include 
the keywords ${\rm TIMEDEL} = {\rm TIMEDELA}$ (or TIMEDELB), ${\rm EXPTIME} 
= 0.1 \times {\rm EXPTIMEA}$ (or EXPTIMEB), ${\rm FLSHTIME} = {\rm FLSHTIMA}$ 
(or FLSHTIMB), ONTIME$n$, ONTIME, DTCOR, LIVTIME$n$, LIVETIME, EXPOSUR$n$, 
and EXPOSURE.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 5. Continuous-Clocking Observations

\section{Continuous-Clocking Observations}

Observations using continuous-clocking modes have ${\rm TIMEDEL}$
(e.g.\ ${\rm TIMEDEL} = 0.00285$~s) and ${\rm DTCOR} = 1.0$.  The 
values of ONTIME$n$, ONTIME, LIVTIME$n$, LIVETIME, EXPOSUR$n$, and EXPOSURE 
are computed as described in section~\ref{pro}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 6. Illustration

\section{Illustration}

The attached figure illustrates some ACIS clocking sequences.  The first 
example illustrates the clocking sequence used for a timed-exposure observation 
that has only one frame time.  The time intervals during which a CCD is 
collecting charge and the charge is not being clocked to the frame-store 
region (i.e.\ the ``static integration times'') are indicated by the arrows.  
The duration of this interval $\Delta t = {\rm EXPTIMEA}$.  The static 
integration time includes intervals during which the detector is idle (I), 
the frame-store is being flushed (Fs), and the data from the previous frame 
is being processed (Readout).  The integrated charge is clocked to the 
frame-store region during the intervals indicated by the label ``Fl.''  In 
this example, EXPTIMEA might be 3.2~s, ${\rm Fl} = 0.04104$~s, ${\rm TIMEDEL} 
= {\rm EXPTIMEA} + {\rm Fl} = 3.24104$~s, and ${\rm FLSHTIME} = 0$.

The second example illustrates the clocking sequence used for a timed-exposure
observation that has only one frame time and each frame is preceeded by a
``flush.''  Again the static integration times are indicated by the intervals
marked with the arrows.  Here, ${\rm TIMEDEL} = {\rm EXPTIMEA} + {\rm Fl}$ 
and FLSHTIME is the interval that includes the sequece ${\rm Fl} + {\rm I} + 
{\rm Fs} + {\rm I} + {\rm Readout}$ or, equivalently, ${\rm Fl} + {\rm I} + 
{\rm Fs} + {\rm Readout} + {\rm I}$.

The third example illustrates the clocking sequence used for a timed-exposure
observation with interleaved frames.  The primary frame (EXPTIMEA) is
preceeded by a ``flush'' (FLSHTIMA) of duration ${\rm Fl} + {\rm I} + {\rm Fs} 
+ {\rm I} + {\rm Readout}$ and the secondary frame (EXPTIMEB) has no proceeding
flush (${\rm FLSHTIMB} = 0$).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 7. Figure

\hbox{\psfig{file=memo_time_keywords_proposal_fig1.ps}}

\end{document}
