Index: trunk/doc/pslib/psLibSDRS.tex
===================================================================
--- trunk/doc/pslib/psLibSDRS.tex	(revision 4945)
+++ trunk/doc/pslib/psLibSDRS.tex	(revision 4982)
@@ -1,3 +1,3 @@
-%%% $Id: psLibSDRS.tex,v 1.333 2005-09-02 22:29:08 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.334 2005-09-09 18:30:23 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -3405,5 +3405,5 @@
 
 \begin{prototype}
-bool psVectorInit(psVector *image, ...);
+bool psVectorInit(psVector *vector, ...);
 \end{prototype}
 
@@ -3423,4 +3423,15 @@
 value of the \code{input} vector at the specified \code{position}.  A
 negative \code{position} means index from the end.
+
+\begin{prototype}
+psVector psVectorCreate(psVector *input, double lower, double upper, double delta, psElemType type);
+\end{prototype}
+
+This function creates a new vector, or reallocates the provided vector
+if \code{input} is not \code{NULL}.  The created vector consists of
+the data range starting at \code{lower}, running to \code{upper}, in
+steps of \code{delta}.  The upper-end value is {\em exclusive}; the
+sequence is equivalent to \code{for (x = lower; x < upper; x +=
+  delta)}.  
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -4378,4 +4389,12 @@
 \end{prototype}
 
+\begin{prototype}
+long psVectorCountPixelMask (psVector *mask, psMaskValue value);
+\end{prototype}
+This function returns the number of pixels in the \code{vector} which
+satisfy any of the mask bits.  An error (eg, invalid vector) results
+in a return value of -1.  The vector must be of the same type as
+psMaskValue.
+
 \subsubsection{Histograms}
 \label{sec:histograms}
@@ -4640,14 +4659,27 @@
 We specify two minimization engines, Levenberg-Marquardt and Powell,
 since the former is relatively robust, but requires derivatives to be
-known, while the latter does not always obtain the best fit but does
-not require derivatives to be known.
-
-In both cases, we need to be able to set the maximum number of
-iterations (\code{maxIter}) and the maximum tolerance (\code{tol}) for
-convergence, in addition to having some basic information on the
-results and quality of the minimization: the value of the function at
-the minimum (\code{value}), the number of iterations performed
-(\code{iter}) and last change in tolerance before returning
-(\code{lastDelta}).
+known, while the latter does not require derivatives to be known, but
+since it needs to calculate the derivatives on the fly, is more
+computationally intensive.  
+
+We define the structure \code{psMinimization} to carry in user-defined
+limits on the minimization process, and to carry out information about
+the minimization analysis.  The maximum number of iterations is
+specified by \code{maxIter}, while the maximum tolerance for
+convergence is \code{tol}.  Four parameter vectors describe the
+behavior of individual parameters.  The \code{paramMask} vector
+defines the free (0) or frozen (not 0) parameters.  The
+\code{paramMin} defines the minimum allowed value for each parameter,
+while \code{paramMax} defines the maximum allowed value for each
+parameter.  During the analysis, parameters which would trend beyond
+these limits saturate to the limit.  The \code{paramDelta} specifies
+the maximum allowed absolute value of the swing of a given parameter.
+If the delta for a specific parameter would be larger than this, the
+swing is saturated to the limit (with the correct sign).  Any of these
+parameter vectors may be set to \code{NULL}, in which case the concept
+is ignored in the analysis.  The output information carried by the
+structure consists of the value of the function at the minimum
+(\code{value}), the number of iterations performed (\code{iter}) and
+last change in tolerance before returning (\code{lastDelta}).
 
 \begin{datatype}
@@ -4658,4 +4690,8 @@
     int iter;                           ///< Actual number of iterations performed
     float lastDelta;                    ///< Last change before quitting
+    psVector *paramMask;                ///< valid / invalid parameters
+    psVector *paramMax;                 ///< max allowed parameters
+    psVector *paramMin;                 ///< min allowed parameters
+    psVector *paramDelta;               ///< max allowed param swing
 } psMinimization;
 \end{datatype}
@@ -4665,4 +4701,5 @@
 psMinimization *psMinimizationAlloc(int maxIter, float tol);
 \end{prototype}
+and the parameter vectors are initially set to \code{NULL}.  
 
 \subsubsection{Levenberg-Marquardt}
@@ -4685,5 +4722,4 @@
                       psImage *covar, 
                       psVector *params,
-                      const psVector *paramMask, 
                       const psArray  *x, 
                       const psVector *y,
@@ -4694,4 +4730,6 @@
 The function shall return \code{false} in the event that there was an
 error (bad input, too many iterations), and also call \code{psError}.
+It is not an error for the minimization to reach one of the parameter
+limits.  
 
 The minimization specification, \code{min}, shall be modified with the
@@ -4741,8 +4779,8 @@
 the goodness of a fit.  This function returns the distances of the
 current parameter set from the minimization parameters expected from
-Gauss-Newton minimization.  The arguments are identical to those of
-\code{psMinimizeLMChi2}, except only the single vector \code{delta},
-consisting of the distances, is returned.  This vector must be
-pre-allocated to the dimenstions of \code{params}.
+Gauss-Newton minimization.  The arguments have the same meaning as for
+\code{psMinimizeLMChi2}.  The returned vector, \code{delta}, consists
+of the distances.  This vector must be pre-allocated to the
+dimenstions of \code{params}.
 
 %% \subsubsubsection{Pre-defined Functions for LM}
@@ -4785,11 +4823,14 @@
 
 \begin{prototype}
-bool psMinimizePowell(psMinimization *min, psVector *params, const psVector *paramMask,
-                      const psArray *coords, psMinimizePowellFunc func);
+bool psMinimizePowell(psMinimization *min, 
+                      psVector *params, 
+                      const psVector *paramMask,
+                      const psArray *coords, 
+                      psMinimizePowellFunc func);
 \end{prototype}
 
 The inputs and general behavior of this function is the same as for
 \code{psMinimizeLM}, except for the absence of the covariance matrix,
-\code{covar}.
+\code{covar} \note{why does this not have a covar matrix?}
 
 \subsubsubsection{Minimizing $\chi^2$ with Powell}
@@ -4803,6 +4844,10 @@
 
 \begin{prototype}
-bool psMinimizeChi2Powell(psMinimization *min, psVector *params, const psVector *paramMask,
-                          const psArray *coords, const psVector *value, const psVector *error,
+bool psMinimizeChi2Powell(psMinimization *min, 
+                          psVector *params, 
+			  const psVector *paramMask,
+                          const psArray *coords, 
+			  const psVector *value, 
+			  const psVector *error,
                           psMinimizeChi2PowellFunc model);
 \end{prototype}
@@ -4812,4 +4857,8 @@
 instead of being provided the function to be minimized, it is provided
 a model to fit and must calculate the $\chi^2$ to be minimized itself.
+
+\note{why does this not have a covar matrix?}
+
+\note{unify the param names with psMinimizeLMChi2Func?}
 
 For this purpose, \code{value} shall contain measured values at the
@@ -5009,4 +5058,19 @@
 
 \begin{prototype}
+psVector *psImageRow(psVector *out, 
+                     const psImage *input,
+		     psU32 row);
+psVector *psImageCol(psVector *out, 
+                     const psImage *input,
+		     psU32 column);
+\end{prototype}
+
+These two functions extract a single complete \code{row} or
+\code{column} from the \code{image} and return it to the provided
+\code{vector}, allocating it if it is \code{NULL}.  These are provided
+as fast, simple implementations of data extraction.  For more
+sophisticated operations, the following two functions should be used. 
+
+\begin{prototype}
 psVector *psImageSlice(psVector *out, 
                        psPixels *coords,
@@ -5257,4 +5321,11 @@
 following types: \code{psS8}, \code{psU16}, \code{psF32},
 \code{psF64}.
+
+\begin{prototype}
+long psImageCountPixelMask (psImage *mask, psRegion region, psMaskValue value);
+\end{prototype}
+This function returns the number of pixels in the image region which
+satisfy any of the mask bits.  An error (eg, invalid image, invalid
+region) results in a return value of -1.
 
 \begin{prototype}
@@ -6230,4 +6301,5 @@
 bool psTimerStart(char *name);
 psF64 psTimerMark(char *name);
+psF64 psTimerClear(char *name);
 psF64 psTimerStop(void);
 \end{prototype}
@@ -6236,8 +6308,7 @@
 timers, under the supplied \code{name}.  \code{psTimerMark} shall
 return the elapsed time, in seconds, for the timer specified by
-\code{name}.  \code{psTimerStop} shall free all memory associated with
-the timers, so that no memory is leaked, and return the maximum time
-expended.
-
+\code{name}.  \code{psTimerClear} resets the named timer.
+\code{psTimerStop} shall free all memory associated with all timers,
+so that no memory is leaked, and return the maximum time expended.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%