Index: /trunk/doc/design/specs.tex
===================================================================
--- /trunk/doc/design/specs.tex	(revision 528)
+++ /trunk/doc/design/specs.tex	(revision 529)
@@ -1,3 +1,3 @@
-%%% $Id: specs.tex,v 1.6 2004-04-23 21:57:43 eugene Exp $
+%%% $Id: specs.tex,v 1.7 2004-04-27 18:38:31 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -63,4 +63,17 @@
 limited by network bandwidth.
 
+\subsubsection{Definitions}
+
+\paragraph{``Must''}  When used in this specification, the word
+``must'' refers to an explicit requirement of a system component or
+the complete system.
+
+\paragraph{``Should''}  When used in this specification, the word
+``should'' refers to a desired chracteristic of a system component or
+the complete system.
+
+\paragraph{``Will''}  When used in this specification, the word
+``will'' provides information about a characteristic of a related
+system component or a complete related system.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -79,33 +92,36 @@
 \section{Requirements} 
 
-\subsection{Required States and Modes}
-
-The IPP has 3 states: active, paused, and interactive.
-
-\begin{itemize}
-
-\item {\bf active state} In active state, the IPP shall accept images
-  and metadata from OATS and automatically perform the complete set of
-  image processing tasks, including both calibration and science image
-  processing.  The IPP will respond to requests for data from the
-  client science pipelines \tbd{and IPP monitoring team}.
-
-\item {\bf paused state}  In paused state, the IPP shall refuse data and
-  metadata from OATS and data requests from the client science
-  pipelines.
-
-\item {\bf interactive state}  In interactive state, the IPP shall
-  accept data and metadata from OATS, but will not automatically
-  process the data.  The IPP shall respond to user commands to
-  initiate portions of the data analysis.
-\end{itemize}
-
-\tbd{what is a mode?}
+\subsection{Required States}
+
+The IPP must have 3 states: active, paused, and interactive.
+
+\subsubsection{Active State} 
+\label{req:active-state}
+
+In active state, the IPP must accept images and metadata from OATS and
+automatically perform the complete set of image processing tasks,
+including both calibration and science image processing.  The IPP must
+respond to requests for data from the client science pipelines
+\tbd{and IPP monitoring team}.
+
+\subsubsection{Paused State} 
+\label{req:paused-state}
+
+In paused state, the IPP must refuse data and metadata from OATS and
+data requests from the client science pipelines.
+
+\subsubsection{Interactive State} 
+\label{req:interactive-state}
+
+In interactive state, the IPP must accept data and metadata from OATS,
+but must not automatically process the data.  The IPP must respond to
+user commands to initiate portions of the data analysis.
 
 \subsection{System Capability Requirements}
-
-The IPP shall:
-
-\begin{itemize}
+\label{req:system-capabilities}
+
+The IPP must perform the following tasks:
+
+\begin{enumerate}
 
 \item Accept raw images from OATS at a sustained rate of 1 exposure
@@ -115,5 +131,5 @@
 
 \item Produce high-quality calibration images from the raw calibration
-  images.  The calibration images shall not introduce systematic
+  images.  The calibration images must not introduce systematic
   uncertainties greater than \tbd{0.2\%}.  \tbd{Requirements on the
   speed of processing the calibration images.}
@@ -131,8 +147,8 @@
 \item Excise the significant transients and outliers from the
   pre-processed science images and merge the cleaned images into the
-  static sky image
+  static sky image.
 
 \item Detect objects on the four types of images: pre-processed
-  images, the merged image, the difference image, and the static sky
+  images, the stacked image, the difference image, and the static sky
   image.
 
@@ -147,17 +163,17 @@
 \item Produce a high-quality astrometric reference catalog from the
   extracted objects on a time-scale of 6 months.  The astrometric
-  reference shall have an absolute accuracy of \tbd{30 mas} and a
-  local relative accuracy of \tbd{10 mas}.  Proper motions of all
-  nearly stationary objects shall be determined with an accuracy of
-  \tbd{XXX mas / year}. 
+  reference must have an absolute accuracy of \tbd{30 mas} and a local
+  relative accuracy of \tbd{10 mas}.  Proper motions of all nearly
+  stationary objects must be determined with an accuracy of \tbd{XXX
+  mas / year}.
 
 \item Produce a high-quality photometric reference catalog from the
   extracted objects on a time-scale of 6 months.  The photometric
-  reference shall have an consistency across the sky of \tbd{5
+  reference must have an consistency across the sky of \tbd{5
   millimag} and an absolute calibration to the external system defined
   by \tbd{SDSS} of \tbd{10 millimag}.
 
 \item Publish the static sky images to the Pan-STARRS published static
-sky server on a time-scale of \tbd{1 month}.
+  sky server on a time-scale of \tbd{1 month}.
 
 \item Publish the detected objects to the Pan-STARRS published object
@@ -168,33 +184,35 @@
   processed.  
 
-\end{itemize}
+\end{enumerate}
 
 \subsubsection{Software Coding Requirements}
 
 \paragraph{Languages}
-
-Source code shall be in C.  All source code shall be compiled with
-`gcc' version v2.95 or higher.
-
-Scripting language shall be in \tbd{Python, version TBD}. 
+\label{req:languages}
+
+Source code must be in C.  All source code must be compiled with `gcc'
+version v2.95 or higher.
+
+Scripting language must be \tbd{Python, version TBD}.
 
 \paragraph{Interfaces}
-
-Access to low-level Library functions shall be provided via C APIs
+\label{req:interfaces}
+
+Access to low-level Library functions must be provided via C APIs
 consisting of the function calls and the defined data structures and
-other data types.  Access to high-level functions shall be provided
+other data types.  Access to high-level functions must be provided
 via C APIs as well as SWIG interfaces, where specified.  Access to
-processing jobs shall be available via the UNIX shell.
+processing jobs must be available via the UNIX shell.
 
 \paragraph{Coding Standards} 
 
-The C code shall comply with ANSI Standard C99.  Because the delivered
-code is required to run on UNIX machines, the delivered code shall be
+The C code must comply with ANSI Standard C99.  Because the delivered
+code is required to run on UNIX machines, the delivered code must be
 in compliance with the language-independent UNIX operating system
 standard POSIX (Open Group Based Specifications Issue 6, IEEE Std
-1003.1, 2003).  Source code files shall use the UNIX line-break
-convention (line-feed only).  C coding style shall adhere to the
+1003.1, 2003).  Source code files must use the UNIX line-break
+convention (line-feed only).  C coding style must adhere to the
 standard defined in the document 'Pan-STARRS C-coding standard'
-(PSDC-430-004).  \tbd{Python coding shall follow the Python standard
+(PSDC-430-004).  \tbd{Python coding must follow the Python standard
 defined in the document TBD}.
 
@@ -229,5 +247,5 @@
 
 When defining a function to convert from one type to another, the name
-should be of the form \code{psOldToAlloc}, e.g.\hfil\break
+must be of the form \code{psOldToAlloc}, e.g.\hfil\break
 \code{psEquatorialToEcliptic} (\emph{not}
 \code{psEquatorial2Ecliptic}).
@@ -235,5 +253,5 @@
 \paragraph{C Programming Guidelines}
 
-Functions that assign to a variable should list that argument
+Functions that assign to a variable must list that argument
 \textit{first}, following the pattern of \code{strcpy}; e.g.
 \begin{verbatim}
@@ -264,5 +282,5 @@
 
 \item The destructor must handle being passed \code{NULL} by simply
-returning immediately. This should not be treated as an error
+returning immediately. This must not be treated as an error
 condition.
 
@@ -274,29 +292,29 @@
 \paragraph{Commenting and Documentation}
 
-Commenting of delivered C and Python code shall follow the C and
-Python coding standards and shall provide tags for Doxygen
+Commenting of delivered C and Python code must follow the C and
+Python coding standards and must provide tags for Doxygen
 interpretation of the comments and program structures.
 
 Documentation for the IPP consists of source code documentation and
-user documentation.  Source code documentation shall be generated with
-Doxygen from the in-line comments and shall be provided as HTML,
+user documentation.  Source code documentation must be generated with
+Doxygen from the in-line comments and must be provided as HTML,
 Latex, and man pages.  User documentation includes the API usage for
 the modules and library functions as well as user interface
 description for the higher-level architectural systems.  User
-documentation shall be delivered as PDF documents.
+documentation must be delivered as PDF documents.
 
 \paragraph{Version Control}
 
-Source code version control shall be implemented with CVS.  
+Source code version control must be implemented with CVS.  
 
 \paragraph{CSCI Deliverable}
 
 All final source code generated for the IPP is to be delivered via
-CVS, including the test code.  CVS revision history shall be included
+CVS, including the test code.  CVS revision history must be included
 and made available via CVS.
 
 \paragraph{Platform architectures and operating systems}
 
-Makefiles shall be provided with appropriate flags set so that all
+Makefiles must be provided with appropriate flags set so that all
 code compiles without warnings under 'gcc -Wall' for the following
 platform architectures and operating systems:
@@ -346,9 +364,9 @@
   as needed to perform the analysis specified above.
 
-\item {\bf Analysis Stages:}  Specific programs are required to
-  perform the processing steps listed above.  These can be divided
-  into well-defined analysis stages, each of which operates on a
-  particular unit of data, such as a single OTA image or a colletion
-  of astronomical objets. 
+\item {\bf Analysis Stages:} Specific programs are required to perform
+  the processing steps listed above.  These can be divided into
+  well-defined analysis stages, each of which operates on a particular
+  unit of data, such as a single OTA image or a collection of
+  astronomical objets.
 
 \item {\bf Controller:} In order to perform the analysis stages
@@ -384,29 +402,29 @@
 store all of the images needed by the IPP for the length of time they
 are required; total data volume is specified in detail in the hardware
-summary, but is in the vicinity of \tbd{700 GB}.
+summary, but is in the vicinity of \tbd{700 TB}.
 
 The IPP Pixel Server must maintain a record of all images currently
 available in the repository \tbd{and all no longer available}.  This
-record shall include the image name, location (which machine), the
+record must include the image name, location (which machine), the
 state of the image (available, deleted), the image size, the image
-type, and the existence and location of secondary copies of the
-image.  This information need not include other metadata such as the
-image summary statistics or the state of the image processing for the
-image.
-
-The IPP Pixel Server shall store images as FITS files on disk.  Raw
-images from the telescope shall be stored as individual OTA images for
+type, and the existence and location of secondary copies of the image.
+This information need not include other metadata such as the image
+summary statistics or the state of the image processing for the image,
+as these aspects are included in the Metadata DB.
+
+The IPP Pixel Server must store images as FITS files on disk.  Raw
+images from the telescope must be stored as individual OTA images for
 each file, with multiple Cell images per file as well as video
-sequences from the guide stars.  Images of the Static Sky shall be
+sequences from the guide stars.  Images of the Static Sky must be
 stored in the form of \tbd{triangular segments} to minimize the total
 data volume and pixel overlap. 
 
-The IPP Pixel Server shall distribute images across a cluster of
-machines.  The IPP Pixel Server shall be capable of honoring requests
+The IPP Pixel Server must distribute images across a cluster of
+machines.  The IPP Pixel Server must be capable of honoring requests
 to store an image on a specific machine.  If such a request cannot be
-honored, the IPP Pixel Server shall select an appropriate machine and
+honored, the IPP Pixel Server must select an appropriate machine and
 notify the requesting agent of the new locations.  The IPP Pixel
-Server shall provide a mechanism to maintain multiple (at least two)
-copies of a single known image.
+Server must provide a mechanism to maintain multiple (at least two)
+copies of each image.
 
 The IPP Pixel Server must interface with other subsystems of the IPP.
@@ -417,11 +435,11 @@
 Pixel Server.  It must have a mechanism to accept or retrieve an image
 from another Pan-STARRS subsystem, in particular OATS.  Communication
-of messages between the IPP Pixel Server and other subsystem shall be
+of messages between the IPP Pixel Server and other subsystem must be
 via \tbd{XML messages} passed via \tbd{some transport}.
 
 The IPP Pixel Server must accept images at the telescope maximum rate
 of 1 full-camera image every 30 seconds.  The IPP Pixel Server must
-accept notifications and process retrievals at a rate of 128 raw OTAs
-per 60 seconds.
+therefore accept notifications and process retrievals at a rate of 64
+raw OTAs in 30 seconds.
 
 \tbd{O/S, language, SQL, ODBC requirements?}
@@ -445,7 +463,7 @@
 derived from specific images from any of the analysis stages.  It must
 be possible to determine and locate (perhaps via interactions with the
-pixel server) the image from which a specific detection was derved.
+pixel server) the image from which a specific detection was derived.
 It must also be possible to extract all detections derived from a
-specific images.  These associations must include descriptive
+specific image.  These associations must include descriptive
 information including the coordinates of the detection on the image.
 
@@ -454,11 +472,11 @@
 objects will be present, each of which must be handled correctly.
 
-First, the distant stars will have nearly fixed locations relative to
-other nearby stars, with only small deviations for individual
-measurements.  The association between multiple detections of such
-objects must be made on the basis of their coincident positions.  The
-PnA Database must be able to determine the average position of the
-object and the deviations of the individual detections from that
-average.  
+First, the most distant stars, compact galaxies, and QSOs will have
+nearly fixed locations relative to other nearby stars, with only small
+deviations for individual measurements.  The association between
+multiple detections of such objects must be made on the basis of their
+coincident positions.  The PnA Database must be able to determine the
+average position of the object and the deviations of the individual
+detections from that average.
 
 Second, solar system objects do not have a fixed location and
@@ -468,9 +486,11 @@
 determination of this association is the responsibility of the MOPS
 and must be communicated to the IPP PnA Database on \tbd{some
-  timescale}.  The PnD Database must be able to retrieve the
-detections associated with the object and to provide the object
-associated with the specific detections.  This association must
-include descriptive information such as the offset of the detection
-from the predicted location of the detection based on the orbit.
+timescale}.  The PnD Database must be able to retrieve the detections
+associated with the object and to provide the object associated with
+the specific detections.  This association must include descriptive
+information such as the offset of the detection from the predicted
+location of the detection based on the orbit.  This functionality is
+required to allow the PnA Database to ignore known moving object
+detections from other types of queries.
 
 Third, stars in the general vicinity of the solar system fall in
@@ -545,6 +565,6 @@
 
 If analysis results are exchanged via the metadata database, it must
-provide access to the queried data on timescales of $<2 sec$ to avoid
-slowing down the analysis systems. 
+provide access to the queried data on timescales of $<2$ seconds to
+avoid slowing down the analysis systems.
 
 \tbd{volume requirements}
@@ -587,16 +607,16 @@
 responds to commands from the controller and may be used for tasks
 subject to other constraints.  If it is {\tt dead}, the computer is
-not responsive and should not be used for executing tasks.  The
+not responsive and must not be used for executing tasks.  The
 controller must identify computers which have died and occasionally
 test them to see if they are {\tt alive} again.  Computers which are
-{\tt off} are not available for tests and should not be tested.
+{\tt off} are not available for tests and must not be tested.
 Computers may be set to the {\tt off} or {\tt dead} states by external
-subsystems; it is the responsibility of the Controller to move a
-computer to the {\tt alive} state if possible.  
+subsystems; it is the responsibility of the Controller to return a
+computer to the {\tt alive} state if possible.
 
 Computers which are in the {\tt alive} state may be in one of two
 modes: {\tt busy} and {\tt free}.  A computer which is {\tt busy}
 currently has a task assigned to it.  The controller may only assign
-one task to one computer at a time\footnote{a physical piece of
+one task to one computer at a time\footnote{A physical piece of
 hardware may be defined to the Controller as multiple computers to
 allow multi-processor nodes to execute more than one simultaneous
@@ -606,5 +626,5 @@
 may have a list of allowed tasks which may include {\tt all} tasks,
 {\tt none} of the tasks, or specified task names.  The controller must
-only execute the allowed tasks on a machine.  
+only execute the allowed tasks on a machine.
 
 The Controller must accept tasks from other IPP subsystems.  The task
@@ -615,5 +635,5 @@
 node on which the task is executed.  Input and output data resources
 must be unique where necessary to avoid conflicts.  Tasks must be
-given an identified, which must be returned to the requesting agent,
+given an identifier, which must be returned to the requesting agent,
 to be used to control the specific task.
 
@@ -650,8 +670,8 @@
 and also change its priority.
 
-The controller must honor requests to change the mode of any computing
-node on demand between {\tt off} and {\tt dead}.  It must also be able
-to change the list of allowed tasks as requested by external
-commands.  
+The controller must honor requests (normally from the users) to change
+the mode of any computing node on demand between {\tt off} and {\tt
+dead}.  It must also be able to change the list of allowed tasks as
+requested by external commands.
 
 The controller must respond to informational requests regarding the
@@ -661,9 +681,10 @@
 the controller must respond to three top-level commands: {\tt finish},
 {\tt stop} and {\tt abort}.  When {\tt finish} is requested, no more
-new tasks are accepted, and when all tasks have completed, the
-controller must exti.  When {\tt stop} is requested, the currently
-executing tasks must be completed at which point the controller must
-exti.  When {\tt abort} is issued, the controller immediately kills
-all executing tasks and exits.
+new tasks are accepted on the stack of task, and when all tasks in the
+stack have completed, the controller must exit.  When {\tt stop} is
+requested, the currently executing tasks must be completed at which
+point the controller must exit, but tasks remaining in the stack which
+have not been started are flushed.  When {\tt abort} is issued, the
+controller immediately kills all executing tasks and exits.
 
 \paragraph{Scheduler}
@@ -687,8 +708,8 @@
 The Scheduler must send commands to the Controller for execution.  It
 is the Controller's responsibility to manage the specific analysis
-jobs executing on a given processing node.  These analysis may include
+jobs executing on a given processing node.  These analyses may include
 the process of copying of moving data from OATS to the pixel server
 nodes, or it may involve image processing stages performed on the
-science images by the apporpriate processing nodes, or it may involve
+science images by the appropriate processing nodes, or it may involve
 analysis of the data in the PnA object database.  In order to isolate
 and encapsulate the responsibilities of the Scheduler and the
@@ -725,5 +746,7 @@
 different time-scales.  The time-scale range from 2 times per minute
 to once or twice a year, as noted in the list above.  The Scheduler
-must make use of the human input to manage such choices.  
+must also make use of the human input in managing such choices.  The
+human users must be able to specify that a particular task or set of
+tasks is of higher or lower priority than the norm.
 
 The Scheduler must maintain a set of rules defining the dependency of
@@ -733,13 +756,13 @@
 dependency and initiate the required analysis needed to perform other
 analysis tasks.  The Scheduler must have the ability to decide between
-postponing an analysis task until the depending data are available or
-to initial the task using a lower-quality or less appropriate
-substitute.  For example, a science image should not be processed
-until the corresponding detrend frame has been produced.  However, it
-such a frame is unlikely to appear and the pressure to process the
-science image it too high, then the frame could be processed with an
-older detrend frame of known lower quality.  The Scheduler must have
-the ability to choose the best, if not ideal, reference data for a
-particular circumstance.
+postponing an analysis task until the required data are available or
+to initiate the task using a lower-quality or less appropriate
+substitute.  For example, in normal circumstances, a science image
+must not be processed until the corresponding detrend frame has been
+produced.  However, if such a frame is unlikely to appear soon, and
+the pressure to process the science image is sufficiently high, then
+the frame could be processed with an older detrend frame of known
+lower quality.  The Scheduler must have the ability to choose the
+best, if not ideal, reference data for a particular circumstance.
 
 The Scheduler is responsible for setting the operating mode of the
@@ -751,10 +774,11 @@
 the requested actions and not attempt to perform the other
 normally-required actions.  The only exception to this exclusion is
-that, in the interactive mode, data must still be copyed from the
+that, in the interactive mode, data must still be copied from the
 summit system.  A human-sent command must be able to change the
-Scheduler priorities from the automatic to the interactive modes.  An
-additional IPP mode is the {\em paused mode}, in which case the
-Scheulder does not perform even the data copy tasks.  Every task is
-performed on demand by the user.
+Scheduler priorities from the automatic to the interactive modes
+\tbd{with a CLI or GUI}.  An additional IPP mode is the {\em paused
+mode}, intended for tests or maintenance, in which case the Scheduler
+does not perform even the data copy tasks.  Every task is performed on
+demand by the user.
 
 \subsubsection{Analysis Stages}
@@ -769,10 +793,10 @@
 
 Depending on the task, the basic data unit may be individual images,
-collections of images, or derived data products such as collection of
+collections of images, or derived data products such as a collection of
 detections of astronomical objects.  Because of the granularity of
 these data units, many of the analysis tasks can be performed in
 parallel because, for example, the intial analysis of an OTA in one
 image does not depend on the results from another OTA.  We define the
-term 'analysis stage' to refer to the largest complete analysis task
+term `analysis stage' to refer to the largest complete analysis task
 which may be performed on a single data item.  The analysis stages are
 divided into three categories, and further subdivided as follows:
@@ -785,5 +809,6 @@
  \begin{itemize}
   \item {\bf Phase 1:} The image processing preparation phase, in
-  which a basic analysis of the complete FPA image is performed.
+  which basic astrometric analysis of the complete FPA image is
+  performed.
 
   \item {\bf Phase 2:} The image reduction phase, in which the
@@ -797,5 +822,5 @@
 
   \item {\bf Phase 4:} The image combination phase, in which several
-  difference exposures of the same part of the sky are combined to
+  different exposures of the same part of the sky are combined to
   produce high-quality difference and summed images.
  \end{itemize}
@@ -803,5 +828,7 @@
  \item {\bf Calibration Image Analysis} is required to generate the
  calibration images used in the science image analysis.  There are
- three types of calibration images which are produced.
+ three types of calibration images which are produced. \tbd{make this
+ consistent with other sections which use the basic / other
+ calibration distinction}
 
  \begin{enumerate}
@@ -904,6 +931,6 @@
 distortion model and table of nominal OTA positions and rotations,
 combined with the guide star pixel and celestial coordinates, to
-determine the correct telescope bore-site, field rotation and
-magnification.  The astrometric accurate required from this analysis
+determine the correct telescope bore-sight, field rotation and
+magnification.  The astrometric accuracy required from this analysis
 stage is \tbd{2 arcsec} across the field, sufficient to match the vast
 majority of reference stars with their detections.
@@ -911,10 +938,11 @@
 In some circumstances, science images may have no guide stars.  This
 may occur if the detectors are not run in OTA mode, especially for
-short snapshot images.  In such a circumstance, the Phase 1 stage must
-perform extremely basic object detection, determining the detector
-coordinates for stars which are not excessively saturated and which
-are significantly above the background level.  The threshold levels
-for this object detection stage must be configurable.  The object
-extraction must be performed in less than \tbd{3 seconds}.
+short snapshot images of if IPP is being run on non-Pan-STARRS data.
+In such a circumstance, the Phase 1 stage must perform extremely basic
+object detection, determining the detector coordinates for stars which
+are not excessively saturated and which are significantly above the
+background level.  The threshold levels for this object detection
+stage must be configurable.  The object extraction must be performed
+in less than \tbd{3 seconds}.
 
 In order for astrometry of an image to succeed, it is necessary that
@@ -932,9 +960,10 @@
 because of the astrometric error at this phase.  It is acceptable for
 a small number of invalid overlaps to be identified as these will be
-excluded in Phase 4.
+excluded in Phase 4.  Sky cells which do not have sufficient science
+image overlap \tbd{$< 10\%$} need not be processed.
 
 It is not unusual that an image be obtained with invalid coordinates
 or without any valid stars.  For example, the telescope control system
-may make an error an report the wrong time or coordinates.  Or, the
+may make an error and report the wrong time or coordinates.  Or, the
 image may be obtained in exceptionally poor conditions with no
 detected stars.  Phase 1 must fail gracefully in these conditions,
@@ -985,10 +1014,10 @@
 bad.  Note that bad pixels which are charge traps need to be grown by
 the extent of the OT convolution kernel, while those pixels above a
-charge trap (i.e.\ bad colums) should not be grown, since they were
-not affected by pixel shifting, but only became bad at read-out.
-
-Pixels saturated in the A/D converter should also be masked, and this
-area should be grown by an additional pixel to mask excess charge
-spillover.  
+charge trap (i.e.\ bad colums) must not be grown, since they were not
+affected by pixel shifting, but only became bad at read-out.
+
+Pixels saturated in the A/D converter must also be masked, and this
+area must be grown by an additional pixel to mask excess charge
+spillover.
 
 The bad pixel mask must be carried with the science images.  Different
@@ -1010,7 +1039,7 @@
 single constant, all of the overscan pixel values are used in the
 calculation of this statistic.  In the case of the 1D functional
-representation, the input values to the fit should represent the
+representation, the input values to the fit must represent the
 coordinate along the overscan, with the statistic derived from the
-pixel in the perpedicular direction at each location.  Sigma-clipping
+pixels in the perpedicular direction at each location.  Sigma-clipping
 on the input data values must be an option.  \tbd{accuracy of the bias
 subtraction?}
@@ -1021,14 +1050,14 @@
 the overscan and any pre-scan pixels, along with those pixels near the
 edges that have been compromised due to OT operation.  The definition
-of the imaging area of the detector must optionally be determined from
-the camera configuration data or from the metadata associated with the
-image.
+of the imaging area of the detector must be determined from the camera
+configuration data or from the metadata associated with the image,
+with the choice a user-configurable option.  
 
 \subparagraph{Correct for non-linearity}
 
-The object image (after bias correction) must be optionally corrected
-for the effects of non-linearity through a provided polynomial fit to
-the pixel data values.  \tbd{what IPP component produces the
-non-linear correction function?}
+If required, the object image (after bias correction) must be
+corrected for the effects of non-linearity through a provided
+polynomial fit to the pixel data values.  The choice to apply the
+correction must be set by the user.
 
 \subparagraph{Flat-field correction}
@@ -1048,20 +1077,20 @@
 (technically, foreground) variations which are not celestial but
 generated in the atmosphere or by more localized scattering.  This
-background subtraction does not address the artefacts generated by
+background subtraction does not address the artifacts generated by
 bright stars: bleeding columns, ghosts, or other localized reflection
 effects.  The background subtraction must remove the variations with
-an accuracy such that the residual variations do not introduce on
-average more than \tbd{0.2\%} photometric scatter or more than
+an accuracy such that the residual variations do not introduce, on
+average, more than \tbd{0.2\%} photometric scatter or more than
 \tbd{1\%} extremely deviant outlier stars (stars for which the
-photometry is in error by more than 3\%.  \tbd{what is the requirement
-on galaxy photometry? morphology determinations?}  \tbd{What is
-allowed power-spectrum of background variations?}
-
-\subparagraph{Identify 'cosmic rays'}
+photometry is in error by more than 3\%).  \tbd{what is the
+requirement on galaxy photometry? morphology determinations?}
+\tbd{What is allowed power-spectrum of background variations?}
+
+\subparagraph{Identify `cosmic rays'}
 
 Charged particles in the detector frequently cause features which do
 not have the morphology of astronomical objects.  In a well-sampled
 image, these may be easily identified by the sharpness of the image.
-In a near critically-sampled image, these 'cosmic rays' may be
+In a near critically-sampled image, these `cosmic rays' may be
 indistinguishable from stellar objects.  The IPP must have the
 capability of making the morphological identification of cosmic rays
@@ -1083,7 +1112,7 @@
 which are inconsistent, and objects which are saturated.  The
 resulting collection of detected objects must be saved along with the
-relevant image metadata (\ie, filter, exposure time, etc).
-
-\subparagraph{astrometry}
+relevant image metadata (\ie filter, exposure time, etc).
+
+\subparagraph{Astrometry}
 
 Objects detected in Phase~2 must be matched with known astrometric
@@ -1093,8 +1122,9 @@
 stage, a user-defined collection of OTA astrometry parameters must be
 fitted on the basis of the matched stars.  The Cell astrometric
-parameters must not be allowed to flow at this stage.  The fit must be
-robust, rejecting outlier matches, either stars with poorly determined
-proper motion or spurious matches.  The resulting astrometric solution
-must be consistent across the OTA field to within \tbd{0.2 arcsec}.  
+parameters must not be allowed to vary at this stage.  The fit must be
+robust, rejecting outlier matches (either stars with poorly determined
+proper motion or spurious matches).  The resulting astrometric
+solution must be consistent across the OTA field to within \tbd{0.2
+arcsec}.
 
 \subparagraph{Postage Stamps}
@@ -1113,12 +1143,12 @@
 
 Phase 3 must use the objects detected in Phase 2, matched with an
-appropriate reference catalog, to determine the image zero point and
-zero-point variations across the field.  If zero-point variations are
-significant \tbd{level TBD}, the zero-point variations must be modeled
-with an up-to 3rd order chebychev polynomial correction.  The complete
-FPA image must be categorized as photometric or not \tbd{numerical
-scale?} on the basis of the zero-point consistency, the transparency
-compared with recent long-term measurements in the filter, and the
-external indicators of photometricity.
+appropriate reference catalog, to determine the image photometric zero
+point and zero-point variations across the field.  If zero-point
+variations are significant \tbd{level TBD}, the zero-point variations
+must be modeled with a chebychev polynomial correction of order 3 or
+less.  The complete FPA image must be categorized as photometric or
+not \tbd{numerical scale?} on the basis of the zero-point consistency,
+the transparency compared with recent long-term measurements in the
+filter, and the external indicators of photometricity.
 
 Phase 3 must use the objects detected in Phase 2, matched with an
@@ -1134,5 +1164,5 @@
 sky image.  Phase 4 operates on the smallest data unit of the static
 sky, the sky cell, along with the associated pixels from a collection
-of image which have been processed through phases 1 - 3.  For each sky
+of images which have been processed through phases 1--3.  For each sky
 cell, the corresponding pixels are extracted from the exposures being
 processed and mapped to the projection of the sky cell. The pixels
@@ -1142,5 +1172,5 @@
 difference image, above a threshold are detected and excised from the
 original cleaned image.  The remaining pixels are added to the
-existing static sky image.  Object detection must be performed of the
+existing static sky image.  Object detection must be performed on the
 difference and cleaned images.  \tbd{when is static sky object
 detection \& classification performed?}  Phase 4 naturally divides
@@ -1152,6 +1182,6 @@
 determined and extracted from the input images.  This process must use
 the astrometric information for each OTA and Cell to determine the
-overlaps.  It must not miss any pixels, and it must read no more than
-20\% more pixels than necessary from the input images.
+exact overlaps.  It must not miss any pixels, and it must read no more
+than 20\% more pixels than necessary from the input images.
 
 \subparagraph{Transform pixel coordinates}
@@ -1166,14 +1196,10 @@
 \tbd{interpolation method?}
 
-\subparagraph{PSF matching}
-
-The multiple input images must have their PSF mutually matched to
-allow for proper image subtraction.
-
 \subparagraph{Flux matching}
 
-The multiple input images must have their object fluxes mutually
-matched by intercomparison of the stars measured in Phase 2 in order
-to properly combine them photometrically. 
+The multiple input images must have their object fluxes intercompared
+using the stars measured in Phase 2 in order to determine the
+appropriate photometry scaling factors needed to properly combine them
+photometrically.
 
 \subparagraph{Image outlier pixel rejection}
@@ -1186,10 +1212,15 @@
 obtained over a wide range of times.
 
+\subparagraph{PSF matching}
+
+The multiple input images must have their PSF mutually matched to
+allow for proper image subtraction.
+
 \subparagraph{Image Subtraction}
 
-The static sky image must be subtracted from the merged, cleaned
+The static sky image must be subtracted from the stacked, cleaned
 image.  All objects in the difference image must be detected and the
-pixels flagged in the input image.  Object detection at this stage is
-the same as that used for Phase 2.  
+pixels belonging to variable sources flagged in the input image.
+Object detection at this stage is the same as that used for Phase 2.
 
 \subparagraph{Cleaned Input Image}
@@ -1214,5 +1245,6 @@
 telescopes, with the (old) static sky added;
 \item Metadata about the quality of each of these images; and
-\item A catalogue of variable sources.
+\item A catalog of variable sources.
+\item A catalog of sources from the combined image.
 \end{enumerate}
 
@@ -1237,8 +1269,8 @@
 photometric and astrometric accuracies:
 \begin{itemize}
-\item Relative photometric accuracy better than 0.005 mag {\bf [???]}.
-\item Absolute photometric accuracy better than 0.02 mag {\bf [???]}.
-\item Relative astrometric accuracy better than 0.02 arcsec {\bf [???]}.
-\item Absolute astrometric accuracy better than 0.2 arcsec {\bf [???]}.
+\item Relative photometric accuracy better than \tbd{0.005 mag}
+\item Absolute photometric accuracy better than \tbd{0.02 mag}
+\item Relative astrometric accuracy better than \tbd{0.01 arcsec}
+\item Absolute astrometric accuracy better than \tbd{0.2 arcsec}
 \end{itemize}
 
@@ -1251,4 +1283,5 @@
 
 \paragraph{Calibration Stages}
+\label{mkcal}
 
 The Calibration analysis stages may be performed on whatever
@@ -1263,15 +1296,15 @@
 \paragraph{Basic Calibration Stages}
 
-The IPP must generate basic calibration images using the raw
-flat-field, bias and dark images obtained by the telescope as the
-input.  The analysis of these images requires relatively simple
-stacking of the input set of images.  Outlier rejection, both of
-complete input images as well as pixels within the input stack, must
-be performed.  In addition, each type of image requires an appropriate
-normalization which may depend on the data levels in other detectors
-in the input set.  Each of these calibration stages must be able to
-determine from the input stack if the relevant calibration image needs
-to be updated and perform an initial test to see which input images
-are consistent and valid. 
+The IPP must generate basic calibration images using the raw bias,
+dark, and flat-field (dome or twilight) images obtained by the
+telescope as the input.  The analysis of these images requires
+relatively simple stacking of the input set of images.  Outlier
+rejection, both of complete input images as well as pixels within the
+input stack, must be performed.  In addition, each type of image
+requires an appropriate normalization which may depend on the data
+levels in other detectors in the input set.  Each of these calibration
+stages must be able to determine from the input stack if the relevant
+calibration image needs to be updated and perform an initial test to
+see which input images are consistent and valid.
 
 \subparagraph{bias images}
@@ -1332,5 +1365,5 @@
 flat-field images and identify pixels which are repeatedly
 inconsistent from image to image.  If too many pixels are
-inconsistent, an error should be raised. 
+inconsistent, an error must be raised. 
 
 \subparagraph{fringe frames}
@@ -1367,4 +1400,13 @@
 which are placed at a variety of locations on the detector in a
 sequence of images. 
+
+\subparagraph{Non-linearity correction frames}
+
+The IPP must have the capability of constructing non-linear correction
+frames.  These frames are constructed from exposures of a uniform
+source with a range of exposure times.  The non-linearity correction
+frames provide polynomial correction coefficients as a function of
+pixel to convert the observed pixel counts to the expected pixel count
+from a linear detector.  
 
 \paragraph{Reference Catalog Creation}
@@ -2032,6 +2074,6 @@
 \section{Test Verification}
 
-A testing regime shall be implemented to demonstrate the working state
-of the provided software.  Certain tests as specified shall be
+A testing regime must be implemented to demonstrate the working state
+of the provided software.  Certain tests as specified must be
 performed by MHPCC, with code release contingent on success.  Other
 specified tests will be performed by IfA to verify the validity of the
@@ -2042,5 +2084,5 @@
 \subsection{Software Configuration Tests}
 
-MHPCC shall test the validity of the software configuration,
+MHPCC must test the validity of the software configuration,
 specifically to check that the code can be compiled on the specified
 platforms and that the compilation produces no errors or warnings,
@@ -2049,16 +2091,16 @@
 \subsection{Software Integrity Tests}
 
-MHPCC shall test the integrity of the software, specifically to check
+MHPCC must test the integrity of the software, specifically to check
 that the code does not produce memory leaks, segmentation faults.
 
 \subsection{Basic Unit Tests}
 
-MHPCC shall perform basic unit tests with sample input data and known
+MHPCC must perform basic unit tests with sample input data and known
 output results, including invalid input data to test error handling.
-These tests should exercise the complete range of module options.
+These tests must exercise the complete range of module options.
 
 \subsection{Detailed Functional Analysis}
 
-IfA shall perform detailed tests with a wide range of input data and
+IfA must perform detailed tests with a wide range of input data and
 compare the results with existing software system.
 
@@ -2078,2 +2120,21 @@
 \end{document}
 
+Requirements Trace Matrix
+
+active state \ref{req:active-state}
+paused state \ref{req:paused-state}
+interactive state \ref{req:interactive-state}
+
+system capabilities
+
+C for source code \ref{req:languages}
+Python for scripts \ref{req:languages}
+
+SWIG interfaces
+C APIs
+
+POSIX
+Pan-STARRS Coding Standard
+
+Naming Conventions
+