%+
% Name:
%    memo_cti_correction_4.8.tex
%
% Usage:
%    latex memo_cti_correction_4.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 occurances of PHAS to PHAS_ADJ, GEA
%    17 Dec 01, changed occurances of PHAS to PHAS_ADJ for serial CTI, GEA
%    09 Sep 02, updated header, GEA
%    02 May 03, added table (v4.8), GEA
%-

\documentclass{article}

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

\newrgbcolor{blue}{0 0 1}

\newcommand{\bit}{20}
\newcommand{\chipxmax}{{\rm CHIPXMAX}}
\newcommand{\chipxmin}{{\rm CHIPXMIN}}
\newcommand{\chipymax}{{\rm CHIPYMAX}}
\newcommand{\chipymin}{{\rm CHIPYMIN}}
\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{\diffy}{{\rm DIFF\_Y}}
\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{
   Martin Elvis, SDS Group Leader }{
   Glenn E.\ Allen, SDS, for the CTI task group }{
   Adjusting ACIS Event Data to Compensate for CTI }{
   4.8 }{
   http://space.mit.edu/CXC/docs/docs.html\#cti }{
   /nfs/cxc/h2/gea/sds/docs/memos/memo\_cti\_correction\_4.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 
charge-transfer inefficiency (CTI) of the \fsi\ CCDs.
% and for the parallel and serial CTI of the \bsi\ CCDs.  
To achieve this improvement, charge is added to each 3~pixel $\times$
3~pixel event island and the charge within the event island is
redistributed.  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 tool \tool\
includes the algorithm described in section~\ref{proc}, which can be 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.  Once the values of \newcol\ are computed,
the values of FLTGRADE, GRADE, PHA, ENERGY, and PI are computed using the
column \newcol. At the present, the calibration data is only appropriate for
data obtained using some of the front-side--illuminated CCDs 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,a,``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 estimate the
distribution of the charge deposited in the detector.  We suggest that the
maximum number of iterations be limited to the range of 1--20.  The default
convergence criterion is set to 0.1~adu because this is the default value
used for the PSU CTI-adjustment tool.  Since the utility of using values
smaller than 0.1~adu is questionable, the minimum value for the parameter
cti\_converge is 0.1~adu. A maximum value of 1~adu seems reasonable for the
convergence parameter.

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

\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 the present Level 1 or 2 ACIS event files except that the file 
includes the additional column ``\newcol'' (if specified as part of the
eventdef) and the additional keywords ``\keyword'' an ``\keywordtwo'' ($=
{\rm T}$). The new column contains the real (not integer) CTI-adjusted
values of the charge distribution in the event island.  The column named
PHAS contains the original, unadjusted values of PHAS (\ie\ the bias and
overclock-subtracted values of PHAS obtained before any CTI adjustment is
performed).  The keyword \keyword\ contains the name of the CTI ARD file
used to process the data.  If ${\rm \switch} = {\rm ``no}$,'' no CTI
adjustment is applied, the column \newcol\ is not created, the column PHAS
contains the unadjusted values of PHAS, ${\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}$,'' the column \newcol\ is created and 
populated with the values of the CTI-adjusted contents of PHAS.  The column 
PHAS contains the unadjusted PHAS information.  The original PHAS 
information is retained to ensure that users can analyze the unadjusted 
distribution of charge in the event island and to provide the input required
if users want to rerun \tool\ with an updated CTI ARD file at a later time.
The algorithm used to compute the CTI-adjusted values of \newcol\ is 
described later in this section.  After the values of \newcol\ are computed,
the values of FLTGRADE, GRADE, PHA, ENERGY, and PI are computed from the
column \newcol\ not PHAS (see Tables~1 and 2).  The
column PHA has integer values whether the CTI-adjustment is applied or not.


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{fig1} with $i$ and $j
\in [1,3]$.  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. These sixteen pixels have
identically the same values in the columns \newcol\ and \phas.

If ${\rm \switch} = {\rm ``yes}$,'' the following steps describe how to 
apply the CTI adjustment.  The adjustment is applied to every event in the 
input ACIS event-data file.  For an event detected on $\ccdid = n$ at a 
location $\chipx = \xccd$, and $\chipy = \yccd$,

\begin{enumerate}

\item
Copy the contents of PHAS to \newcol.

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

\item
\label{step3}
For the bottom row of the $3 \times 3$~pixel event island, compute the 
effects of parallel CTI.  Steps~\ref{step3}--\ref{step5} 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{fig1}).  If 
$\newcol[i,1] \ge {\rm the\ split\ threshold}$, then
%
\begin{eqnarray}
\diffy[i,1]
   & =
   & \deltphay_{i,1} +
   \nonumber \\
\
   & 
   & \phas[i,1] - \newcol[i,1].
\label{eqn1}
\end{eqnarray}
%
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.  

The value of $\deltphay_{i,j}$ used in equation~\ref{eqn1} is computed as
follows.
\begin{itemize}
\item[i.]
Find the row $m$ in HDU~1 of the appropriate CTI ARD file that satisfies the 
conditions
\begin{eqnarray}
\ccdid_{m}
   & = 
   & n, 
   \\
\chipxmin_{m}
   & \le \xccd \le
   & \chipxmax_{m},\ {\rm and} 
   \\
\chipymin_{m}
   & \le \yccd \le
   & \chipymax_{m},
\end{eqnarray}
where \ccdid, \chipxmin, \chipxmax, \chipymin, and \chipymax\ are the
names of columns in the CTI ARD file (see sec.~\ref{ard}).

\item[ii.]
For the row that satisfies these conditions, find the two non-zero (real!)
values ${\rm PHA}_{k}$ and ${\rm PHA}_{k+1}$ such that
\begin{equation}
0
   < {\rm PHA}_{k}
   \le \newcol[i,j]
   < {\rm PHA}_{k+1},
\end{equation}
where ${\rm PHA}_{k}$ and ${\rm PHA}_{k+1}$ are elements of the column PHA 
in the CTI ARD file.

\item[iii.]
Compute the effective ``\vol'' occupied by the charge in pixel $[i,j]$ using 
the linear interpolation 
%
\begin{eqnarray}
\vol_{i,j}
    & =
    & \frac{\newcol[i,j] - {\rm PHA}_{k}}{{\rm PHA}_{k+1} - {\rm PHA}_{k}}
    \times \bigl(
    \voly_{k+1} - \voly_{k}
    \bigr) +
    \nonumber \\
\
    &
     & \voly_{k},
\end{eqnarray}
%
where $\voly_{k}$ and $\voly_{k+1}$ are the $k^{\rm th}$ and $(k+1)^{\rm th}$ 
elements of the column \voly\ 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 \newcol[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 < \newcol[i,j] < {\rm PHA}_{1}$, 
then use the linear extrapolation
%
\begin{eqnarray}
\vol_{i,j}
   & =
   & \frac{\newcol[i,j] - {\rm PHA}_{1}}{{\rm PHA}_{2} - {\rm PHA}_{1}}
   \times \bigl(
   \voly_{2} - \voly_{1}
   \bigr) +
   \nonumber \\
\
   &
   & \voly_{1}.
\end{eqnarray}
%
If $\newcol[i,j] \ge {\rm PHA}_{\rm NPOINTS}$, then use the linear 
extrapolation
%
\begin{eqnarray}
\vol_{i,j}
   & =
   & \frac{\newcol[i,j] - {\rm PHA}_{{\rm NPOINTS}-1}}{
      {\rm PHA}_{\rm NPOINTS} - {\rm PHA}_{{\rm NPOINTS}-1}} \times
   \nonumber \\
\
   &
   & \bigl(
   \voly_{\rm NPOINTS} - \voly_{{\rm NPOINTS}-1}
   \bigr) +
   \nonumber \\
\
   &
   & \voly_{{\rm NPOINTS}-1}.
\end{eqnarray}
If $\newcol[i,j] \le 0$, then $\vol_{i,j} = 0$.

\item[iv.]
Find the HDU in the CTI ARD file that has the parallel-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.]
Compute the value of $\deltphay_{i,j}$:
%
\begin{eqnarray}
\deltphay_{i,j}
    & =
    & \trapdens_{i,j} \times 
    \vol_{i,j}.
\end{eqnarray}
%

\end{itemize}

\item
For the middle and top rows of the $3 \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{fig1}).  
If $\newcol[i,j] \ge {\rm the\ split\ threshold} > \newcol[i,j-1]$, then
%
\begin{eqnarray}
\diffy[i,j]
   & =
   & \deltphay_{i,j} +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%
If $\newcol[i,j] \ge \newcol[i,j-1] \ge {\rm the\ split\ threshold}$, then
%
\begin{eqnarray}
\diffy[i,j]
   & =
   & ( \deltphay_{i,j} - \deltphay_{i,j-1} ) +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%
If $\newcol[i,j-1] > \newcol[i,j] \ge {\rm the\ split\ threshold}$, then
%
\begin{eqnarray}
\diffy[i,j]
   & =
   & \shldy{n} \times ( \deltphay_{i,j} - \deltphay_{i,j-1} ) +
   \nonumber \\ 
\
   &  
   & \phas[i,j] - \newcol[i,j],
\end{eqnarray}
%
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{step5}
Use the estimate of the effects of parallel CTI to adjust the $3 \times 
3$~pixel event island \newcol.  For $i$ and $j \in [1,3]$,
%
\begin{equation}
\newcol[i,j]
   =
   \newcol[i,j] + \diffy[i,j].
\end{equation}
%
Pixels whose amount of charge $<$ the split threshold are not modified.  
These pixels have the same values in the columns PHAS and \newcol. 

\item
\label{step6}
For the column of a $3 \times 3$~pixel event island that is closest to the 
serial read-out node, compute the effects of serial CTI.
Steps~\ref{step6}--\ref{step8} 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.]
For $\nodeid = 0$, $i = 1$ and $j \in [1,3]$.  If $\newcol[1,j] \ge {\rm the\ 
split\ threshold}$, then 
%
\begin{eqnarray}
\diffx[1,j]
   & =
   & \deltphax_{1,j} +
   \nonumber \\
\
   &  
   & \phas[1,j] - \newcol[1,j].
\end{eqnarray}

\item[ii.]
For $\nodeid = 1$, $i = 3$ and $j \in [1,3]$.  If $\newcol[3,j] \ge {\rm the\ 
split\ threshold}$, then 
%
\begin{eqnarray}
\diffx[3,j]
   & =
   & \deltphax_{3,j} +
   \nonumber \\
\
   &
   & \phas[3,j] - \newcol[3,j].
\end{eqnarray}

\item[iii.]
For $\nodeid = 2$, $i = 1$ and $j \in [1,3]$.  If $\newcol[1,j] \ge {\rm the\ 
split\ threshold}$, then 
%
\begin{eqnarray}
\diffx[1,j]
   & =
   & \deltphax_{1,j} +
   \nonumber \\
\
   &
   & \phas[1,j] - \newcol[1,j].
\end{eqnarray}

\item[iv.]
For $\nodeid = 3$, $i = 3$ and $j \in [1,3]$.  If $\newcol[3,j] \ge {\rm the\ 
split\ threshold}$, then 
%
\begin{eqnarray}
\diffx[3,j]
   & =
   & \deltphax_{3,j} +
   \nonumber \\
\
   & \
   & \phas[3,j] - \newcol[3,j].
\end{eqnarray}

\end{itemize}

The quantity $\diffx[i,j]$ is an estimate of the amount of charge that 
should be added to pixel $[i,j]$.  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.  This quantity is computed using the 
same linear interpolation (and extrapolation) method used to compute 
$\deltphay_{i,j}$, where \voly\ is replaced with \volx\ and the parallel-CTI
trap-density map for $\ccdid = n$ is replaced with the serial-CTI trap-density 
map for the CCD.

\item
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.]
For $\nodeid = 0$, $i \in [2,3]$ and $j \in [1,3]$.  If $\newcol[i,j] \ge
\newcol[i-1,j] \ge {\rm the\ split\ threshold}$, then
%    
\begin{eqnarray}
\diffx[i,j]
   & =
   & ( \deltphax_{i,j} - \deltphax_{i-1,j} ) +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%
If $\newcol[i,j] \ge {\rm the\ split\ threshold}$ and $\newcol[i,j] <
\newcol[i-1,j]$, then
%
\begin{eqnarray}
\diffx[i,j]
   & =
   & \shldx{n} \times ( \deltphax_{i,j} - \deltphax_{i-1,j} ) +
   \nonumber \\ 
\
   &  
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%

\item[ii.]
For $\nodeid = 1$, $i \in [1,2]$ and $j \in [1,3]$.  If $\newcol[i,j] \ge
\newcol[i+1,j] \ge {\rm the\ split\ threshold}$, then
%    
\begin{eqnarray}
\diffx[i,j]
   & =
   & ( \deltphax_{i,j} - \deltphax_{i+1,j} ) +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%
If $\newcol[i,j] \ge {\rm the\ split\ threshold}$ and $\newcol[i,j] <
\newcol[i+1,j]$, then
%
\begin{eqnarray}
\diffx[i,j]
   & =
   & \shldx{n} \times ( \deltphax_{i,j} - \deltphax_{i+1,j} ) +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%

\item[iii.]
For $\nodeid = 2$, $i \in [2,3]$ and $j \in [1,3]$.  If $\newcol[i,j] \ge
\newcol[i-1,j] \ge {\rm the\ split\ threshold}$, then
%    
\begin{eqnarray}
\diffx[i,j]
   & =
   & ( \deltphax_{i,j} - \deltphax_{i-1,j} ) +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%
If $\newcol[i,j] \ge {\rm the\ split\ threshold}$ and $\newcol[i,j] <
\newcol[i-1,j]$, then
%
\begin{eqnarray}
\diffx[i,j]
   & =
   & \shldx{n} \times ( \deltphax_{i,j} - \deltphax_{i-1,j} ) +
   \nonumber \\ 
\
   &  
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%

\item[iv.]
For $\nodeid = 3$, $i \in [1,2]$ and $j \in [1,3]$.  If $\newcol[i,j] \ge
\newcol[i+1,j] \ge {\rm the\ split\ threshold}$, then
%    
\begin{eqnarray}
\diffx[i,j]
   & =
   & ( \deltphax_{i,j} - \deltphax_{i+1,j} ) +
   \nonumber \\
\   
   & 
   & \phas[i,j] - \newcol[i,j].
\end{eqnarray}
%
If $\newcol[i,j] \ge {\rm the\ split\ threshold}$ and $\newcol[i,j] <
\newcol[i+1,j]$, then
%
\begin{eqnarray}
\diffx[i,j]
   & =
   & \shldx{n} \times ( \deltphax_{i,j} - \deltphax_{i+1,j} ) +
   \nonumber \\
\
   &
   & \phas[i,j] - \newcol[i,j],
\end{eqnarray}
%
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.

\end{itemize}

\item   
\label{step8}
Use the estimate of the effects of serial CTI to adjust the $3 \times
3$~pixel event island \newcol.  For $i$ and $j \in [1,3]$,
%
\begin{equation}
\newcol[i,j]
   =
   \newcol[i,j] + \diffx[i,j].
\end{equation}
%    
Pixels whose amount of charge $<$ the split threshold are not modified.  
These pixels have the same values in the columns PHAS and \newcol. 

\item
Repeat steps \ref{ite1}--\ref{step8} 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 \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{ite1}--\ref{step8} 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
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}[h]
\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
  & C
  & C
  & C
  & DNC
  & DNC
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & $\langle {\rm gain\_cti} \rangle$
  \\
6
  & C
  & C
  & C
  & DNC
  & DNC
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & $\langle {\rm gain\_cti} \rangle$
  \\
7
  & C
  & DNC
  & DNC
  & DNC
  & DNC
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & copy
  \\
8
  & C
  & DNC
  & DNC
  & DNC
  & DNC
  & set
  & T
  & $\langle {\rm cti} \rangle$
  & copy
  \\
9
  & C
  & C
  & C
  & C
  & C
  & copy
  & F$^{i}$
  & copy$^{j}$
  & $\langle {\rm gain} \rangle^{k}$
  \\
{\blue 10$^{l}$}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue C}
  & {\blue copy}
  & {\blue F$^{i}$}
  & {\blue ``NONE''}
  & {\blue $\langle {\rm gain} \rangle$}
  \\
11
  & C
  & DNC
  & DNC
  & C
  & C
  & copy
  & F$^{i}$
  & copy$^{j}$
  & copy
  \\
12
  & DNC
  & DNC
  & DNC
  & C
  & C
  & copy
  & T
  & copy
  & copy
  \\
13
  & DNC
  & C
  & C
  & DNC
  & DNC
  & copy
  & F$^{i}$
  & copy$^{j}$
  & $\langle {\rm gain} \rangle$
  \\
14
  & DNC
  & C
  & C
  & DNC
  & DNC
  & copy
  & T
  & copy
  & $\langle {\rm gain\_cti} \rangle$
  \\
15
  & DNC
  & DNC
  & DNC
  & DNC
  & DNC
  & copy
  & F$^{i}$
  & copy$^{j}$
  & 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 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
computed or recomputed 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
converveged after performing the specified maximum number of trials.  To
make sure this is true, STATUS bit 20 should be set to zero first before
performing the CTI adjustment.}

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

\parbox{6.5in}{$^{e}$ Compute or recompute.}

\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}$ Copy if appropriate.  Do not compute.}

\parbox{6.5in}{$^{i}$ In these cases, the output column PHAS\_ADJ, if it
exists, should be set to zero.}

\parbox{6.5in}{$^{j}$ If it exists.}

\parbox{6.5in}{$^{k}$ 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}{$^{l}$ Remove the effects of the CTI adjustment.}

\end{table}
%

\item
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
\shldx$n$

\item
\shldy$n$

\end{itemize}

The keywords $\shldx{n}$ and $\shldy{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.  The pulse-height--dependent effects of parallel CTI are tabulated 
for each region in the columns PHA and \voly.  The column \volx\ is a
place-holder in case the effects of serial CTI are calibrated.  It is unused
at the present.  Each row of HDU~1 corresponds to one region of an ACIS CCD
and has NPOINTS PHA, \volx, and \voly\ elements.

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

\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.  (Only
parallel maps exist at the present).  These maps are recorded separately for
each CCD.  The trap density of each of the $1024 \times 1024$ pixels in a
parallel CTI map is the mean trap density for the pixel multiplied by the
\chipy\ coordinate of the pixel (\ie\ the integrated trap density along the
column associated with the pixel).  The trap densities are stored as
two-byte integers with appropriate keywords BZERO and BSCALE in the headers
of each extension. (The trap ${\rm density} = {\rm BZERO} + {\rm BSCALE}
\times {\rm the}$ value of the trap density in the 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{fig1}}
\end{figure}

\vfill

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

% 7. Finish

\end{document}
