%+
% Name:
%   memo_cti_correction_5.8.tex
%
% Usage:
%   latex memo_cti_correction_5.8.tex
%
% Description:
%   This document describes the specification for a CTI correction.
%
% Input:
%
% Output:
%
% Notes:
%
% History:
%   03 Apr 01, created, Glenn E. Allen
%   07 May 01, modified to include the decisions made at the CTI meeting, GEA
%   15 May 01, extensive modifications, GEA
%   04 Jun 01, reverted to power-law algorithm from table look-up to save
%     space in the ARD, GEA
%   29 Oct 01, removed the CHIPY portion of the computation of DELTAPHAY
%     since the CHIPY component is built into the trap density map, GEA
%   02 Nov 01, changed a VOLUME_Y to VOLUME, GEA
%   14 Dec 01, changed two occurrences of PHAS to PHAS_ADJ, GEA
%   17 Dec 01, changed occurrences of PHAS to PHAS_ADJ for serial CTI, GEA
%   09 Sep 02, updated header, GEA
%   02 May 03, added table (v4.8), GEA
%   13 Apr 04, fixed Table 2 (v4.9), GEA
%   28 Oct 05, added comments about CHIPY_TARG (v4.10), GEA
%   06 Dec 05, switched the order of the serial and parallel CTI adjustments
%     and dropped the PHAS - PHAS_ADJ from DIFF_X/Y (v5.0), GEA
%   07 Dec 05, added DIFF_X/Y_PREV and removed PHAS_INT (v5.1), GEA
%   13 Dec 05, fixed a typo in eqn. 25 (v5.2), GEA
%   16 Dec 05, elaborated on the conditions in steps 5-8 (v5.3), GEA
%   19 Dec 05, removed most of the cases were DIFF_X/Y is set to zero
%     (v5.4), GEA
%   13 Jan 06, fixed node edges for serial CTI adjustment (v5.5), GEA
%   17 Jan 06, fixed a bug with the serial CTI adjustment (v5.6), GEA
%   25 Jan 06, changed the dynamic split threshold test to an initial split
%     threshold test (v5.7), GEA
%   02 Feb 06, fixed a comment below eqn. 11 (v5.8), GEA
%-

\documentclass{article}

\usepackage{changebar}
\usepackage{cxo-memo-logo}
\usepackage[dvips]{graphics}
\usepackage{gea}
\usepackage{epsfig}
\usepackage{pstricks}

\newrgbcolor{blue}{0 0 1}

\newcommand{\bit}{20}
\newcommand{\chipxmax}{{\rm CHIPX\_HI}}
\newcommand{\chipxmin}{{\rm CHIPX\_LO}}
\newcommand{\chipymax}{{\rm CHIPY\_HI}}
\newcommand{\chipymin}{{\rm CHIPY\_LO}}
\newcommand{\cticonverg}{cti\_converge}
\newcommand{\deltphax}{{\rm DELTPHAX}}
\newcommand{\deltphay}{{\rm DELTPHAY}}
\newcommand{\deltphas}{0.1~{\rm adu}}
\newcommand{\devmap}{{\rm DEV\_MAP}n}
\newcommand{\diffx}{{\rm DIFF\_X}}
\newcommand{\diffxprev}{{\rm DIFF\_X\_PREV}}
\newcommand{\diffy}{{\rm DIFF\_Y}}
\newcommand{\diffyprev}{{\rm DIFF\_Y\_PREV}}
\newcommand{\keyword}{CTIFILE}
\newcommand{\keywordtwo}{CTI\_CORR}
\newcommand{\nodeid}{{\rm NODE\_ID}}
\newcommand{\norm}{{\rm NORM}}
\newcommand{\newcol}{{\rm PHAS\_ADJ}}
\newcommand{\numiter}{max\_cti\_iter}
\newcommand{\phas}{{\rm PHAS}}
\newcommand{\phastmp}{{\rm PHAS\_TMP}}
\newcommand{\phazero}{{\rm PHA}_{\rm no}}
\newcommand{\shldx}{{\rm FRCTRLX}}
\newcommand{\shldy}{{\rm FRCTRLY}}
\newcommand{\switch}{{\rm apply\_cti}}
\newcommand{\tool}{acis\_process\_events}
\newcommand{\trapdens}{{\rm TRAPDENS}}
\newcommand{\vol}{{\rm VOLUME}}
\newcommand{\volx}{{\rm VOLUME\_X}}
\newcommand{\voly}{{\rm VOLUME\_Y}}
\newcommand{\xccd}{x_{\rm CCD}}
\newcommand{\yccd}{y_{\rm CCD}}

\begin{document}

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

% 1. Header

\memobasic{
   Jonathan McDowell, SDS Group Leader }{
   Glenn E.\ Allen, SDS }{
   Adjusting ACIS Event Data to Compensate for CTI }{
   5.8 }{
   http://space.mit.edu/CXC/docs/docs.html\#cti }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_cti\_correction\_5.8.tex }

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

% 2. Introduction

\vspace*{0.3in}
%
The ACIS instrument teams at PSU and MIT have shown that a significant
improvement in the energy resolution of existing ACIS event data can be
obtained by compensating for some of the effects of the parallel and serial
charge-transfer inefficiencies (CTIs) of the CCDs. To achieve this
improvement, charge is added to each 3~pixel $\times$ 3~pixel event island.
While some pixels in the island gain charge, others may lose charge.  Yet,
the net change for an event is alway positive. The amount of charge added to
each event is based on an estimate of the average amount of charge that is
lost as charge packets are clocked across the charge traps on the ACIS
detectors.  The average amount of charge lost depends on the density of
charge traps on the detector, the location of the event on the CCD, and the
number of traps that have already been filled by ``precursor events'' in the
same CCD column (\ie\ on how many empty traps an event must cross to get to
the read out).  The algorithm described in section~\ref{proc} is used to
compute the CTI-adjusted values of PHAS.  These adjusted values are
contained in a new column called \newcol.  The original, unadjusted values
are retained in the column PHAS.  Note that only the column PHAS is written
to the output file by default.  The column \newcol\ can be included if the
parameter eventdef includes ``f:phas\_adj.'' Once the values of \newcol\ are
computed for an event, these values are used to compute the values of
FLTGRADE, GRADE, PHA, ENERGY and PI for the event. At the present, the
parallel CTI is calibrated for all but ACIS-S1 and the serial CTI is
calibrated for only ACIS-S3.  These calibration data are appropriate for
observations with frame times of about 3.2~s.

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

% 3. Changes to acis_process_events

\section{Changes to \tool}
\label{ape}

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

\subsection{Additional Parameters}

\begin{enumerate}

\item
\switch,b,h,``yes'',``no'',``yes'',``Apply CTI adjustment?'' 

\item
ctifile,s,h,``CALDB'',,,``ACIS CTI ARD file (NONE | none | CALDB | 
   $<$filename$>$)'' 

\item
\numiter,i,h,15,1,20,``Maximum number of iterations for the CTI 
   adjustment of each event''

\item
cti\_converge,r,h,0.1,0.1,1.0,``The convergence criterion for each 
   CTI-adjusted pixel in adu''
   
\end{enumerate}

When Catherine Grant tested the PSU CTI-adjustment tool, she found that the
median number of iterations required to satisfy a convergence criterion of
0.1~adu is four.  No event required more than ten iterations.  Therefore, a
default maximum of fifteen iterations should be sufficient to determine the
values of \newcol.  The default convergence criterion is 0.1~adu because
this is the default value used for the PSU CTI-adjustment tool.  

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

\subsection{Additional Input}

The tool \tool\ must read the CTI ARD file in addition to the other files it
already reads.  The format of the CTI ARD file is summarized in 
section~\ref{ard}.

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

\subsection{Additional Output}

If ${\rm \switch} = {\rm ``yes}$,'' the output event file has the same 
format as a Level 1 or Level 2 ACIS event file except that the file includes
the the additional keywords ``\keyword'' and ``\keywordtwo'' and may also
include the additional column ``\newcol.'' The keyword \keyword\ contains
the name of the CTI ARD file used to process the data. The keyword ${\rm
\keywordtwo} = {\rm T}$. If the parameter event includes, for example,
``f:phas\_adj,'' then the values of \newcol\ are written to the output file.
The column named PHAS contains the original, unadjusted values of the charge
distributions of the event islands. 

If ${\rm \switch} = {\rm ``no}$,'' no CTI adjustment is applied, ${\rm
\keyword} = {\rm ``NONE}$,'' and ${\rm \keywordtwo} = {\rm F}$''.

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

\subsection{Processing}
\label{proc}

The tool should produce a warning if TIMEDEL is not in the range specified
by the corresponding calibration-boundary (``CBD'') keyword.

If ${\rm \switch} = {\rm ``yes}$,'' then the algorithm described hereafter
is used to compute the real-valued, CTI-adjusted values of a pulse-height
event island \newcol.  The column PHAS contains the unadjusted pulse-height
information.  The values of FLTGRADE, GRADE, PHA, ENERGY, and PI are based
on the values of \newcol, not PHAS (see Tables~1 and 2).  The column PHA has
integer values whether the CTI-adjustment is applied or not.

By default, only the values of PHAS are written to the output file. This
information is retained to ensure that users can rerun \tool\ to recompute
the pulse-height information using an updated CTI ARD file or to remove the
CTI adjustments.

The columns \newcol\ and PHAS are arrays.  For TIMED FAINT-mode
observations, the relative CHIPX and CHIPY coordinates associated with
\newcol$_{i,j}$ are distributed as shown in figure~\ref{fig01} with $i$ and
$j \in [1,3]$.  For example, if a TIMED FAINT-mode event occurs at ${\rm
(CHIPX, CHIPY)} = (960,571)$, then \newcol$_{1,2}$ corresponds to the CCD
coordinates (959,571) and \newcol$_{2,3}$ corresponds to the CCD coordinates
(960,572).  The algorithm described below applies only to a 3~pixel $\times$
3~pixel event island.  For TIMED VFAINT-mode observations, $i$ and $j \in
[1,5]$ and the appropriate 3~pixel $\times$ 3~pixel region to use is the
central nine pixels of the 5~pixel $\times$ 5~pixel event island (\ie\ the
region associated with \phas$_{i,j}$, where $i$ and $j \in [2,4]$ instead of
$i$ and $j \in [1,5]$).  The outer sixteen pixels of the $5 \times 5$ island
are not modified by the CTI-adjustment algorithm.  The values of \newcol\
are identically the same as the values of \phas\ for these sixteen pixels.

If ${\rm \switch} = {\rm ``yes}$,'' the following steps describe how to 
apply the CTI adjustment.  For an event detected on $\ccdid = n$ at a 
location $(\chipx, \chipy) = (\xccd, \yccd)$\footnote{If the values of
$\xccd$ and $\yccd$ are real numbers instead of integers, they should be
rounded to the nearest integer before proceeding.},

\begin{enumerate}

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

\item
\label{itm01}
%
Copy the contents of PHAS to \newcol.

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

\item
\label{itm02}
%
Set the arrays ${\rm \diffx} = 0$ and ${\rm \diffy} = 0$.

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

\item
\label{itm03}
%
Copy the values of \diffx\ to \diffxprev\ and the values of \diffy\ to
\diffyprev. 

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

\item
\label{itm04}
%
Copy the values of \newcol\ (not PHAS) to \phastmp.

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

\item
\label{itm05}
%
For the column of a 3~pixel $\times$ 3~pixel event island that is closest to
the serial read-out node, compute the effects of serial CTI.
Steps~\ref{itm05} and \ref{itm06} should be performed only if the
appropriate serial-CTI trap-density map exists for $\ccdid = n$.  The CTI
ARD may not contain some serial-CTI trap-density maps if the effects of
serial CTI are not fully calibrated.

\begin{itemize}

\item[i.]
\label{itm05a}
%
For $\nodeid = 0$, $i = 1$ and $j \in [1,3]$.  
If $\phas_{1,j} \ge {\rm the\ split\ threshold}$, then
%
\begin{equation}
  \diffx_{1,j} 
    = 
    \deltphax_{1,j}.
  \label{eqn01}
\end{equation}
%

\item[ii.]
\label{itm05b}
%
For $\nodeid = 1$, $i = 3$ and $j \in [1,3]$.  
If $\phas_{3,j} \ge {\rm the\ split\ threshold}$, then
%
\begin{equation}
  \diffx_{3,j}
    =
    \deltphax_{3,j}.
  \label{eqn02}
\end{equation}
%

\item[iii.]
\label{itm05c}
%
For $\nodeid = 2$, $i = 1$ and $j \in [1,3]$.  
If $\phas_{1,j} \ge {\rm the\ split\ threshold}$, then
%
\begin{equation}
  \diffx_{1,j}
    =
    \deltphax_{1,j}.
  \label{eqn03}
\end{equation}
%

\item[iv.]
\label{itm05d}
%
For $\nodeid = 3$, $i = 3$ and $j \in [1,3]$.  
If $\phas_{3,j} \ge {\rm the\ split\ threshold}$, then
%
\begin{equation}
  \diffx_{3,j}
    =
    \deltphax_{3,j}.
  \label{eqn04}
\end{equation}
%

\end{itemize}

The quantity $\diffx_{i,j}$ is an estimate of the amount of charge that
should be added to pixel $(i,j)$.  (\diffxprev\ is the same thing except
from the previous iteration.) The quantity $\deltphax_{i,j}$ represents the
amount of charge lost from pixel $(i,j)$ due to the effects of serial CTI
and is a function of the CCD used, the location of an event on the CCD, and
the charge deposited on the CCD.  

The value of $\deltphax_{i,j}$ used in equations~\ref{eqn01}, \ref{eqn02},
\ref{eqn03} and \ref{eqn04} is computed as follows.

\begin{itemize}
\item[i.]
\label{itm05e}
%
Find the row $m$ in HDU~1 of the appropriate CTI ARD file that satisfies the
conditions
\begin{eqnarray}
\ccdid_{m}
   & =
   & n,
   \label{eqn05}
   \\
\chipxmin_{m}
   & \le \xccd \le
   & \chipxmax_{m},\ {\rm and}
   \label{eqn06}
   \\
\chipymin_{m}
   & \le \yccd \le
   & \chipymax_{m},
   \label{eqn07}
\end{eqnarray}
where \ccdid, \chipxmin, \chipxmax, \chipymin, and \chipymax\ are the
names of columns in the CTI ARD file (see sec.~\ref{ard}).  Note that the
values of $\xccd$ and $\yccd$ should be rounded to the nearest integer if
they are not integers.

\item[ii.]
\label{itm05f}
%
For row $m$, find the two non-zero (real!) values ${\rm PHA}_{k}$ and ${\rm
PHA}_{k+1}$ such that
\begin{equation}
  0
    < {\rm PHA}_{k}
    \le \left( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} \right)
    < {\rm PHA}_{k+1},
  \label{eqn08}
\end{equation}
where ${\rm PHA}_{k}$ and ${\rm PHA}_{k+1}$ are elements of the column PHA
in the CTI ARD file.

\item[iii.]
\label{itm05g}
%
Compute the effective ``\vol'' occupied by the charge in pixel $(i,j)$ using
the linear interpolation
%
\begin{eqnarray}
  \vol_{i,j}
    & =
    & \left( \frac{( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} ) - 
        {\rm PHA}_{k}}{{\rm PHA}_{k+1} - 
        {\rm PHA}_{k}} \right) \times
      \nonumber \\
  \
    &
    & \left( \volx_{k+1} - \volx_{k} \right) + \volx_{k},
  \label{eqn09}
\end{eqnarray}
%
where $\volx_{k}$ and $\volx_{k+1}$ are the $k^{\rm th}$ and $(k+1)^{\rm
th}$ elements of the column \volx\ in the CTI ARD file (see sec.~\ref{ard}).
This formula is valid if and only if $1 \le k < {\rm NPOINTS}$ (\ie\ if
${\rm PHA}_{1} \le ( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} ) <
{\rm PHA}_{\rm NPOINTS}$, where ${\rm PHA}_{1}$ and ${\rm PHA}_{\rm
NPOINTS}$ are the smallest and largest values of the vector PHA for row $m$,
respectively).  

If $0 < ( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} ) < {\rm
PHA}_{1}$, then use the linear extrapolation
%
\begin{eqnarray}
  \vol_{i,j}
    & =
    & \left( \frac{( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} ) - 
        {\rm PHA}_{1}}{{\rm PHA}_{2} - {\rm PHA}_{1}} \right) \times
    \nonumber \\
 \
    &
    & \left( \volx_{2} - \volx_{1} \right) + \volx_{1}.
  \label{eqn10}
\end{eqnarray}
%
Note that if $\vol_{i,j} < 0$, then set $\vol_{i,j} = 0$.

If $( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} ) \ge {\rm PHA}_{\rm
NPOINTS}$, then use the linear extrapolation
%
\begin{eqnarray}
  \vol_{i,j}
    & =
    & \left( \frac{( \phas_{i,j} + \diffxprev_{i,j} + \diffyprev_{i,j} ) - 
        {\rm PHA}_{{\rm NPOINTS}-1}}{
        {\rm PHA}_{\rm NPOINTS} - {\rm PHA}_{{\rm NPOINTS}-1}} \right) \times
    \nonumber \\
  \
    &
    & \left( \volx_{\rm NPOINTS} - \volx_{{\rm NPOINTS}-1} \right) +
    \nonumber \\
  \
    &
    & \volx_{{\rm NPOINTS}-1}.
  \label{eqn11}
\end{eqnarray}

\begin{changebar}
If $\vol_{i,j} < 0$, then set $\vol_{i,j} = 0$.
\end{changebar}

\item[iv.]
\label{itm05h}
%
Find the HDU in the CTI ARD file that has the serial-CTI trap-density map
for $\ccdid = n$ (see sec.~\ref{ard}).  Set $\trapdens_{i,j}$ equal to the
value of the map at the position $(\chipx,\chipy) = (x_{i},y_{i})$, where
$x_{i} = \xccd - 1$, $\xccd$, and $\xccd + 1$ for $i = 1$, 2, and 3 and
$y_{i} = \yccd - 1$, $\yccd$, and $\yccd + 1$ for $j = 1$, 2, and 3.

\item[v.]
\label{itm05i}
%
Compute the value of $\deltphax_{i,j}$:
%
\begin{eqnarray}
  \deltphax_{i,j}
    & =
    & \trapdens_{i,j} \times
      \vol_{i,j}.
  \label{eqn12}
\end{eqnarray}
%

\end{itemize}

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

\item
\label{itm06}
%
For the two columns of a $3 \times 3$~pixel event island that are farthest
from the serial read-out node, compute the effects of serial CTI.

\begin{itemize}

\item[i.]
\label{itm06a}
%
For $\nodeid = 0$, $i \in [2,3]$ and $j \in [1,3]$.
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$ and $(\phas_{i-1,j} <
{\rm the\ split\ threshold})]$ or $[({\rm CHIPX} = 256)$ and $(i = 3)$ and 
$(\phas_{i,j} \ge {\rm the\ split\ threshold})]$,
then
%
\begin{equation}
  \diffx_{i,j} 
    =  
    \deltphax_{i,j}.
  \label{eqn13}
\end{equation}
%
For $\nodeid = 0$, $i \in [2,3]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i-1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) \ge (\phas_{i-1,j} + \diffxprev_{i-1,j} +
\diffyprev_{i-1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j} 
    =  
    \deltphax_{i,j} - \deltphax_{i-1,j}.
  \label{eqn14}
\end{equation}
%
Do not use equation~\ref{eqn14} if $({\rm CHIPX} = 256)$ and $(i = 3)$.

For $\nodeid = 0$, $i \in [2,3]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i-1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) < (\phas_{i-1,j} + \diffxprev_{i-1,j} +
\diffyprev_{i-1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j} 
    = 
    \shldx{n} \times 
    \left( \deltphax_{i,j} - \deltphax_{i-1,j} \right).
  \label{eqn15}
\end{equation}
%
Do not use equation~\ref{eqn15} if $({\rm CHIPX} = 256)$ and $(i = 3)$.

\item[ii.]
\label{itm06b}
%
For $\nodeid = 1$, $i \in [1,2]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$ and $(\phas_{i+1,j} <
{\rm the\ split\ threshold})]$ or $[({\rm CHIPX} = 257)$ and $(i = 1)$ and
$(\phas_{i,j} \ge {\rm the\ split\ threshold})]$ or $[({\rm CHIPX} = 512)$
and $(i = 2)$ and $(\phas_{i,j} \ge {\rm the\ split\ threshold})]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \deltphax_{i,j}.
  \label{eqn16}
\end{equation}
%
For $\nodeid = 1$, $i \in [1,2]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i+1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) \ge (\phas_{i+1,j} + \diffxprev_{i+1,j} +
\diffyprev_{i+1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \deltphax_{i,j} - \deltphax_{i+1,j}.
  \label{eqn17}
\end{equation}
%
Do not use equation~\ref{eqn17} if $[({\rm CHIPX} = 257)$ and $(i = 1)]$ or
$[({\rm CHIPX} = 512)$ and $(i = 2)]$.

For $\nodeid = 1$, $i \in [1,2]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i+1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) < (\phas_{i+1,j} + \diffxprev_{i+1,j} +
\diffyprev_{i+1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \shldx{n} \times 
    \left( \deltphax_{i,j} - \deltphax_{i+1,j} \right).
  \label{eqn18}
\end{equation}
%
Do not use equation~\ref{eqn18} if $[({\rm CHIPX} = 257)$ and $(i = 1)]$ or
$[({\rm CHIPX} = 512)$ and $(i = 2)]$.

\item[iii.]
\label{itm06c}
%
For $\nodeid = 2$, $i \in [2,3]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$ and $(\phas_{i-1,j} <
{\rm the\ split\ threshold})]$ or $[({\rm CHIPX} = 513)$ and $(i = 2)$ and
$(\phas_{i,j} \ge {\rm the\ split\ threshold})]$ or $[({\rm CHIPX} = 768)$
and $(i = 3)$ and $(\phas_{i,j} \ge {\rm the\ split\ threshold})]$, 
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \deltphax_{i,j}.
  \label{eqn19}
\end{equation}
%
For $\nodeid = 2$, $i \in [2,3]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i-1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) \ge (\phas_{i-1,j} + \diffxprev_{i-1,j} +
\diffyprev_{i-1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \deltphax_{i,j} - \deltphax_{i-1,j}.
  \label{eqn20}
\end{equation}
%
Do not use equation~\ref{eqn20} if $[({\rm CHIPX} = 513)$ and $(i = 2)]$ or
$[({\rm CHIPX} = 768)$ and $(i = 3)]$.

For $\nodeid = 2$, $i \in [2,3]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i-1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) < (\phas_{i-1,j} + \diffxprev_{i-1,j} +
\diffyprev_{i-1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \shldx{n} \times 
    \left( \deltphax_{i,j} - \deltphax_{i-1,j} \right).
  \label{eqn21}
\end{equation}
%
Do not use equation~\ref{eqn21} if $[({\rm CHIPX} = 513)$ and $(i = 2)]$ or
$[({\rm CHIPX} = 768)$ and $(i = 3)]$.

\item[iv.]
\label{itm06d}
%
For $\nodeid = 3$, $i \in [1,2]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$ and $(\phas_{i+1,j} <
{\rm the\ split\ threshold})]$ or $[({\rm CHIPX} = 769)$ and $(i = 1)$ and
$(\phas_{i,j} \ge {\rm the\ split\ threshold})]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \deltphax_{i,j}.
  \label{eqn22}
\end{equation}
%
For $\nodeid = 3$, $i \in [1,2]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i+1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) \ge (\phas_{i+1,j} + \diffxprev_{i+1,j} +
\diffyprev_{i+1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \deltphax_{i,j} - \deltphax_{i+1,j}.
  \label{eqn23}
\end{equation}
%
Do not use equation~\ref{eqn23} if $({\rm CHIPX} = 769)$ and $(i = 1)$.

For $\nodeid = 3$, $i \in [1,2]$ and $j \in [1,3]$.  
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i+1,j} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j}) < (\phas_{i+1,j} + \diffxprev_{i+1,j} +
\diffyprev_{i+1,j}))]$,
then
%
\begin{equation}
  \diffx_{i,j}
    =
    \shldx{n} \times 
    \left( \deltphax_{i,j} - \deltphax_{i+1,j} \right).
  \label{eqn24}
\end{equation}
%
where $\shldx{n}$ is the name of a keyword in the CTI ARD file (see
sec.~\ref{ard}) and represents the fraction of the trapped charge that is
released in the first pixel following the pixel which lost the charge.
Do not use equation~\ref{eqn24} if $({\rm CHIPX} = 769)$ and $(i = 1)$.

\end{itemize}

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

\item
\label{itm07} 
%
For the bottom row of the 3~pixel $\times$ 3~pixel event island, compute the
effects of parallel CTI.  Steps~\ref{itm07} and \ref{itm08} should be
performed only if the appropriate parallel-CTI trap-density map exists for
$\ccdid = n$.  The CTI ARD may not contain some parallel-CTI trap-density
maps if the effects of parallel CTI are not fully calibrated. The bottom row
of $\phas_{i,j}$ is given by $i \in [1,3], j = 1$ (fig.~\ref{fig01}).
If $\phas_{i,1} \ge {\rm the\ split\ threshold}$, 
then
%
\begin{equation}
  \diffy_{i,1}
    =
    \deltphay_{i,1}.
  \label{eqn25}
\end{equation}
%
The quantity $\diffy_{i,j}$ is an estimate of the amount of charge that
should be added to pixel $(i,j)$ of the event island.  The quantity
$\deltphay_{i,j}$ represents the amount of charge lost from pixel $(i,j)$
due to parallel CTI and is a function of the CCD used, the location of an
event on the CCD, and the charge deposited on the CCD. This quantity is
computed using the same linear interpolation (and extrapolation) method used
to compute $\deltphax_{i,j}$, where $( \phas_{i,j} + \diffxprev_{i,j} +
\diffyprev_{i,j} )$ is replaced by $( \phas_{i,j} + \diffx_{i,j} +
\diffyprev_{i,j} )$, \volx\ is replaced with \voly\ and the serial-CTI
trap-density map for $\ccdid = n$ is replaced with the parallel-CTI
trap-density map for the CCD.

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

\item
\label{itm08}
%
For the middle and top rows of the 3~pixel $\times$ 3~pixel event island,
compute the effects of parallel CTI.  The middle and top rows of
$\phas_{i,j}$ are given by $i \in [1,3]$, $j \in [2,3]$ (fig.~\ref{fig01}).
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$ and $(\phas_{i,j-1} <
{\rm the\ split\ threshold})]$,
then
%
\begin{equation}
  \diffy_{i,j}
    =
    \deltphay_{i,j}.
  \label{eqn26}
\end{equation}
%
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i,j-1} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffx_{i,j} +
\diffyprev_{i,j}) \ge (\phas_{i,j-1} + \diffx_{i,j-1} +
\diffyprev_{i,j-1}))]$,
then
%
\begin{equation}
  \diffy_{i,j}
    =
    \deltphay_{i,j} - \deltphay_{i,j-1}.
  \label{eqn27}
\end{equation}
%
If $[(\phas_{i,j} \ge {\rm the\ split\ threshold})$, $(\phas_{i,j-1} \ge
{\rm the\ split\ threshold})$ and $((\phas_{i,j} + \diffx_{i,j} +
\diffyprev_{i,j}) < (\phas_{i,j-1} + \diffx_{i,j-1} +
\diffyprev_{i,j-1}))]$,
then
%
\begin{equation}
  \diffy_{i,j}
    =
    \shldy{n} \times 
      \left( \deltphay_{i,j} - \deltphay_{i,j-1} \right).
  \label{eqn28}
\end{equation}
%
where $\shldy{n}$ is the name of a keyword in the CTI ARD file (see
sec.~\ref{ard}) and represents the fraction of the trapped charge that is
released in the first pixel following the pixel which lost the charge.

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

\item
\label{itm09}
%
Use the estimate of the effects of serial and parallel CTI to adjust the
3~pixel $\times$ 3~pixel event island \phas.  For $i$ and $j \in [1,3]$,
%
\begin{equation}
  \newcol_{i,j}
     =
     \phas_{i,j} + \diffx_{i,j} + \diffy_{i,j}.
  \label{eqn29}
\end{equation}
%
Pixels whose amount of charge $<$ the split threshold are not modified.

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

\item
\label{itm10}
%
Repeat steps \ref{itm03}--\ref{itm09} until the absolute values of
$\newcol_{i,j} - \phastmp_{i,j}$ are less than the value of the parameter
\cticonverg\ for all pixels in the 3~pixel $\times$ 3~pixel event island
(\ie\ until the changes in each of the values of $\newcol_{i,j}$ from one
iteration to the next are less than the value of the parameter \cticonverg).
The maximum number of times that steps \ref{itm03}--\ref{itm09} should be
performed is specified by the parameter \numiter.  If the CTI-adjustment
process does not converge after \numiter\ iterations, set the values of
\newcol\ to be the values obtained during the last iteration and set STATUS
bit \bit\ (of bits 0--31) equal to one.

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

\item
\label{itm11}
%
Based on the input conditions shown in Table~1, compute the values of PHA,
ENERGY, PI, FLTGRADE, GRADE, etc.\ as shown in Table~2.
%
\begin{table}[t]
\begin{center}
\begin{tabular}{c c c c c}
\multicolumn{5}{c}{Table~1. Input Conditions} \\
\hline
\hline
\
  & Parameter
  & Parameter
  & Parameter
  & Keyword
  \\
Case
  & apply\_cti$^{a}$
  & doevtgrade
  & calculate\_pi
  & CTI\_CORR
  \\
\hline 
{\blue 1$^{b}$}
  & {\blue yes}
  & {\blue yes}
  & {\blue yes}
  & {\blue F}
  \\
2
  & yes
  & yes
  & yes
  & T
  \\
3
  & yes
  & yes
  & no
  & F
  \\
4
  & yes
  & yes
  & no
  & T
  \\
5
  & yes
  & no
  & yes
  & F
  \\
6
  & yes
  & no
  & yes
  & T
  \\
7
  & yes
  & no
  & no
  & F
  \\
8
  & yes
  & no
  & no
  & T
  \\
9
  & no
  & yes
  & yes
  & F
  \\
{\blue 10}
  & {\blue no}
  & {\blue yes}
  & {\blue yes}
  & {\blue T}
  \\
11
  & no
  & yes
  & no
  & F
  \\
12
  & no
  & yes
  & no
  & T
  \\
13
  & no
  & no
  & yes
  & F
  \\
14
  & no
  & no
  & yes
  & T
  \\
15
  & no
  & no
  & no
  & F
  \\
16
  & no
  & no
  & no
  & T
  \\
\hline
\hline
\end{tabular}

\parbox{3.8in}{$^{a}$ If DATAMODE = GRADED, GRADED\_HISTO, CC\_GRADED, or
CC33\_GRADED, then follow the instructions for apply\_cti=no because it is
not possible to perform a CTI adjustment.} 

\parbox{3.8in}{$^{b}$ This case is appropriate for standard pipeline 
processing.}

\end{center}
\end{table}
%
\begin{table}[h]
\hspace*{-0.25in}
{\small
\begin{tabular}{c c c c c c c c c c}
\multicolumn{10}{c}{Table~2. Output$^{a}$} \\
\hline
\hline
\
  & Column
  & Column
  & Column
  & Column
  & Column
  & STATUS
  & Keyword
  & Keyword
  & Keyword
  \\
Case
  & PHA$^{b}$
  & ENERGY
  & PI
  & FLTGRADE$^{b}$
  & GRADE
  & bit 20$^{c}$
  & CTI\_CORR
  & CTIFILE
  & GAINFILE
  \\
\hline
{\blue 1$^{d}$}
  & {\blue C$^{e}$}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue set}
  & {\blue T}
  & {\blue $\langle {\rm cti} \rangle^{f}$}
  & {\blue $\langle {\rm gain\_cti} \rangle^{g}$}
  \\
2
  & C
  & C
  & C
  & C
  & C
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & $\langle {\rm gain\_cti} \rangle$
  \\
3
  & C
  & DNC$^{h}$
  & DNC
  & C
  & C
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & copy
  \\
4
  & C
  & DNC
  & DNC
  & C
  & C
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & copy
  \\
5
  & DNC
  & C
  & C
  & DNC
  & DNC
  & unset
  & F
  & ``NONE''
  & $\langle {\rm gain} \rangle^{i}$
  \\
6
  & DNC
  & C
  & C
  & DNC
  & DNC
  & copy
  & T
  & copy
  & $\langle {\rm gain\_cti} \rangle$
  \\
7
  & DNC
  & DNC
  & DNC
  & DNC
  & DNC
  & unset
  & F
  & ``NONE''
  & copy
  \\
8
  & DNC
  & DNC
  & DNC
  & DNC
  & DNC
  & copy
  & T
  & copy
  & copy
  \\
9
  & C
  & C
  & C
  & C
  & C
  & unset
  & F
  & ``NONE''
  & $\langle {\rm gain} \rangle$
  \\
{\blue 10$^{j}$}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue unset}
  & {\blue F}
  & {\blue ``NONE''}
  & {\blue $\langle {\rm gain} \rangle$}
  \\
11
  & C
  & DNC
  & DNC
  & C
  & C
  & unset
  & F
  & ``NONE''
  & copy
  \\
12
  & C
  & DNC
  & DNC
  & C
  & C
  & unset
  & F
  & ``NONE''
  & copy
  \\
13
  & DNC
  & C
  & C
  & DNC
  & DNC
  & unset
  & F
  & ``NONE''
  & $\langle {\rm gain} \rangle$
  \\
14
  & DNC
  & C
  & C
  & DNC
  & DNC
  & copy
  & T
  & copy
  & $\langle {\rm gain\_cti} \rangle$
  \\
15
  & DNC
  & DNC
  & DNC
  & DNC
  & DNC
  & unset
  & F
  & ``NONE''
  & copy
  \\
16
  & DNC
  & DNC
  & DNC
  & DNC
  & DNC
  & copy
  & T
  & copy
  & copy
  \\
\hline
\hline
\end{tabular}
}

\parbox{6.5in}{$^{a}$ In all cases, the PHAS values in the output file are
the unadjusted values of the pulse heights in the 3~pixel $\times$ 3~pixel
(or 5~pixel $\times$ 5~pixel) event islands.  The values of \newcol\ are
only (re)computed if apply\_cti=yes.}

\parbox{6.5in}{$^{b}$ If apply\_cti=yes, then the values of PHAS\_ADJ are
used to compute the values of PHA and FLTGRADE.  If apply\_cti=no, then the
values of PHAS are used to compute the values of PHA and FLTGRADE.  The
values of PHA are integers in both cases.}

\parbox{6.5in}{$^{c}$ If apply\_cti=yes, then STATUS bit 20 (of 0--31) is
set to one for an event only if the PHAS adjustments for the event have not
converged after performing the specified maximum number of trials.  STATUS
bit 20 should be (re)set to zero first before performing the CTI
adjustment.}

\parbox{6.5in}{$^{d}$ This case is used for standard pipeline processing.}

\parbox{6.5in}{$^{e}$ (Re)computed.}

\parbox{6.5in}{$^{f}$ The name of the CTI ARD file used to perform the CTI
adjustments.}

\parbox{6.5in}{$^{g}$ The name of the gain ARD file used to compute ENERGY
from PHA.  This file is appropriate for CTI-adjusted data.}

\parbox{6.5in}{$^{h}$ Copied, not (re)computed.}

\parbox{6.5in}{$^{i}$ The name of the gain ARD file used to compute ENERGY
from PHA.  This file is appropriate for data that has not had the CTI
adjustment applied.}

\parbox{6.5in}{$^{j}$ The effects of the CTI adjustment are removed.}

\end{table}
%

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

\item
\label{itm12}
%
Write out the results. 

\end{enumerate}

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

% 4. New CTI ARD

\section{New CTI ARD}
\label{ard}

Since the effects of CTI are temperature dependent, a different CTI ARD file
is required for each of the different focal-plane temperatures.  The CTI ARD
files have the following structure.

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

\subsection{HDU 1 Keywords}

\begin{itemize}

\item
\shldy$n$

\item
\shldx$n$

\end{itemize}

The keywords $\shldy{n}$ and $\shldx{n}$ represent the fraction of the 
trapped charge that is released in the first pixel following the pixel which
lost the charge.  

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

\subsection{HDU 1 Columns}

\begin{itemize}

\item
\ccdid

\item
\chipxmin

\item
\chipxmax

\item
\chipymin

\item
\chipymax

\item
NPOINTS

\item
PHA (a vector with NPOINTS elements)

\item
\volx\ (a vector with NPOINTS elements)

\item
\voly\ (a vector with NPOINTS elements)

\end{itemize}

The columns \ccdid, \chipxmin, \chipxmax, \chipymin, and \chipymax\ are 
used to define a complete set of spatially-separate regions on the ACIS
CCDs. Each row of HDU~1 corresponds to one region of an ACIS CCD and
includes the vectors PHA, \volx, and \voly.  Each vector has NPOINTS
elements.  The vectors \volx\ and \voly\ are used for serial and parallel
CTI, respectively.

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

\subsection{HDUs $\ge$ 2}

Each one of these extensions (up to a maximum of twenty) contains either a
parallel or serial trap-density map for one of the ten ACIS CCDs.  The
values in the trap-density maps represent the number of traps integrated
along the read-out direction.  For example, the value in the parallel
trap-density map for ACIS-I3 at location $(i, j)$ is the mean number of
traps across which an event at $({\rm CHIPX}, {\rm CHIPY}) = (i, j)$ is
clocked when it is read-out in the parallel direction. The scaled values of
the integrated trap densities are stored as two-byte integers.  The scaling
parameters are specified in each trap-density extension using the keywords
BZERO and BSCALE: the trap ${\rm density} = {\rm BZERO} + {\rm BSCALE}
\times {\rm the}$ value in the trap-density image. The use of two-byte
integers instead of four-byte real numbers helps reduce the size of the ARD
file.  

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

\subsection{Size of File}

The CTI ARD files are relatively large.  Each row of HDU~1 has six two-byte 
integers and three four-byte real vectors with NPOINTS elements each.  If 
the CTI ARD contains information for one region (the entire CCD) on each of 
the ten ACIS CCDs and if ${\rm NPOINTS} = 100$, the binary table of HDU~1 
comprises $10 \times 1 \times (6 \times 2 + 3 \times 4 \times 100)\ {\rm 
bytes} = 12.1$~kb of information.  The size of each of the twenty
trap-density maps is 2.1~Mb (\ie\ $1024 \times 1024\ {\rm pixels} \times 2\
{\rm bytes/ pixel}$).  Unless the number of regions per CCD becomes much
larger than one, the size of HDU~1 is much smaller than the size of the
trap-density maps and the size of one CTI ARD file can be as large as 42~Mb
(\ie\ $20\ {\rm hdus} \times 2.1$~Mb/hdu).

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

% 5. Figures

\begin{figure}
\hfil
\hbox{\psfig{file=memo_cti_correction_fig1.eps2,width=5.50in}}
\hfil
%
\caption{The relative CHIPX and CHIPY coordinates of the nine elements of a
$3 \times 3$ ACIS event island (\ie\ the nine elements of PHAS and \newcol\
for TIMED FAINT-mode events).
%
\label{fig01}}
\end{figure}

\vfill

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

% 7. Finish

\end{document}
