Changeset 2337 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Nov 10, 2004, 6:03:24 PM (22 years ago)

Author:

Paul Price

Message:

Changed return type of psTraceReset, psLogSetFormat,
psMetadataSetIterator, psMetadataItemPrint to return type bool, so
that errors won't be lost (bug 161). psImageRebin input types
restricted; bug 198. Fixed up the LM minimization specification; bug
203.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (13 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.147 2004-11-09 03:45:07 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.148 2004-11-11 04:03:24 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -849 +849 @@
 of the code is compiled.  This can be implemented via macro front-ends
 to private versions of the user APIs.  In addition, a function
-\code{void psTraceReset(void)} will set all trace levels to 0.
+\code{bool psTraceReset(void)} will set all trace levels to 0.
 
 
@@ -931 +931 @@
 %
 \begin{verbatim}
-void psLogSetFormat(const char *fmt);
+bool psLogSetFormat(const char *fmt);
 \end{verbatim}
 %
@@ -1452 +1452 @@
    psListElem *tail;                   ///< last element on list (may be NULL)
    unsigned int nIter;                 ///< number of iterators
-   psListIterator **iter;              ///< iteration cursors
+   psArray *iter;                      ///< array of psListIterator: iteration cursors
    pthread_mutex_t lock;               ///< mutex to lock a node during changes
 } psList;
@@ -2319 +2319 @@
 \subsubsection{Levenberg-Marquardt}
 
-Consider a function of a collection of parameters, \code{params}, and
-(possibly several) coordinate vectors (which we represent as an array
-of vectors), \code{coord}, which returns a single floating point value
-which is the value of the function given the parameters and coordinate
-vectors, along with the derivatives of the function with respect to
-each of the parameters:
-\begin{verbatim}
-typedef float (*psMinimizeLMFunc)(psVector *deriv, const psVector *params, const psArray *coords);
-\end{verbatim}
-An example may help here.  We say that the coordinate vectors may be
-several (and hence use a \code{psArray} for \code{coords}), since
-often one will want to minimize $\chi^2$, given a data set consisting
-of vectors for $x$, $y$ and $\sigma_y$.
-
-Then \code{psMinimizeLM} shall mimimize the specified function,
-\code{func}, using the Levenberg-Marquardt method:
-
-\begin{verbatim}
-bool psMinimizeLM(psMinimization *min, psImage *covar, psVector *params, const psVector *paramMask,
-                  const psArray *coords, psMinimizeLMFunc func);
+Consider a function of a collection of parameters, \code{params},
+which is evaluated at a position, \code{x}, which returns a single
+floating point value which is the value of the function given the
+parameters and coordinate vectors, along with the derivatives of the
+function with respect to each of the parameters, \code{deriv}:
+\begin{verbatim}
+typedef float (*psMinimizeLMChi2Func)(psVector *deriv, const psVector *params, const psVector *x);
+\end{verbatim}
+
+Then \code{psMinimizeLMChi2} shall fit the specified function,
+\code{func}, to a set of measurements, \code{x,y,yErr}, using the
+Levenberg-Marquardt method:
+
+\begin{verbatim}
+bool psMinimizeLMChi2(psMinimization *min, psImage *covar, psVector *params,
+                      const psVector *paramMask, const psArray *x, const psVector *y,
+                      const psVector *yErr, psMinimizeLMChi2Func func);
 \end{verbatim}
 
@@ -2348 +2345 @@
 the values appropriate from the minimization.
 
-On calling the minimizer, \code{params} shall consist of a ``best
-guess'' for the parameters that minimize the input function,
+On calling the minimizer, the \code{params} vector shall consist of a
+``best guess'' for the parameters that minimize the model function,
 \code{func}.  On successful completion, the input parameters,
 \code{params}, shall be updated with the values that minimize the
 input function.  The function shall also update the covariance matrix,
 \code{covar}, in the event that it is non-\code{NULL}.  The function
-shall generate in error in the event that \code{covar} is not a square
-matrix with size matching that of \code{params}.
+shall generate in error in the event that \code{covar} is
+non-\code{NULL} and is not a square matrix with size matching that of
+\code{params}.
 
 Parameters that have a corresponding \code{paramMask} entry of
@@ -2361 +2359 @@
 for \code{paramMask} not to be of the same dimension as \code{params}.
 
-The \code{coords} are not handled by the minimizer, except to be
-passed to the function as additional input, and it is the
-responsibility of the function to interpret these.
+The measurement ordinates, \code{x}, shall consist of multiple
+vectors, each of which may be passed to the model \code{func}.  If the
+measurement coordinates, \code{y}, and errors, \code{yErr}, are not of
+the same length as the ordinates array, \code{x}, then the function
+shall generate a warning, and truncate the longest of the
+array/vectors to match the length of the shortest.  The vectors
+contained within the \code{x} array, and the \code{y} and \code{yErr}
+vectors must be of type \code{psF32}.  The \code{yErr} vector may be
+\code{NULL}, in which case the errors shall be assumed to be
+identical.
 
 \code{paramMask} must be of type \code{psU8}, while \code{params} must
@@ -2375 +2380 @@
 
 \begin{verbatim}
-psMinimizeLMFunc psMinimizeLMChi2Gauss1D;
-psMinimizeLMFunc psMinimizeLMChi2Gauss2D;
-\end{verbatim}
-
-\code{psMinimizeChi2LMGauss1D} shall take, as \code{params}, the
-normalization, center, and standard deviation of a Gaussian to be fit
-to the data.  The data in the \code{coords} shall consist of vectors
-for each of \code{x}, \code{y}, and \code{yErr}.  If the \code{yErr}
-is missing, or \code{NULL}, then the errors shall be taken to be
-unity, for the purpose of fitting where the errors are all identical
-(and possibly unknown).  If the \code{x}, \code{y} or \code{yErr} (if
-supplied) vectors are of differing lengths, the function shall
-generate a warning and truncate the lengths to match the shortest.
-
-\code{psMinimizeLMChi2Gauss1D} shall return the $\chi^2$ value for the
-specified Gaussian as a model for the supplied data, along with the
-derivatives of the $\chi^2$ with respect to each of the parameters.
+psMinimizeLMChi2Func psMinimizeLMChi2Gauss1D;
+psMinimizeLMChi2Func psMinimizeLMChi2Gauss2D;
+\end{verbatim}
+
+\code{psMinimizeChi2LMGauss1D} shall take as \code{params}, the
+normalization, center, and standard deviation of a Gaussian to be fit,
+and as \code{x}, a vector containing a single value.  It shall return
+the value of the Gaussian at the value, and the derivatives
+(\code{deriv}) with respect to each of the parameters.
 
 \code{psMinimizeChi2LMGauss2D} shall take, as \code{params}, the
 normalization, center (two values), standard deviation (two values)
-and position angle of a 2-dimensional Gaussian to be fit to the data.
-The data in the \code{coords} shall consist of vectors for each of
-\code{x}, \code{y}, \code{z} and \code{zErr}.  If the \code{zErr} is
-missing, or \code{NULL}, then the errors shall be taken to be unity,
-for the purpose of fitting where the errors are all identical (and
-possibly unknown).  If the \code{x}, \code{y}, \code{z} or \code{zErr}
-(if supplied) vectors are of differing lengths, the function shall
-generate a warning and truncate the lengths to match the shortest.
-
-\code{psMinimizeLMChi2Gauss2D} shall return the $\chi^2$ value for the
-specified Gaussian as a model for the supplied data, along with the
-derivatives of the $\chi^2$ with respect to each of the parameters.
+and position angle of a 2-dimensional Gaussian, and as \code{x}, a
+vector containing a position, $(x,y)$.  It shall return the value of
+the 2-dimensional Gaussian at the specified point, along with the
+derivatives with respect to each of the parameters.
 
 \subsubsection{Powell}
@@ -2688 +2677 @@
 \code{mask} is non-\code{NULL}, pixels for which the corresponding
 \code{mask} pixel matches \code{maskVal} are excluded from operations.
-This function must be defined for the following types: \code{psU8},
-\code{psU16}, \code{psS8}, \code{psS16}, \code{psF32}, \code{psF64},
-\code{psC32}, \code{psC64}.
+This function must be defined for the following types: \code{psS8},
+\code{psU16}, \code{psF32} and \code{psF64}.
 
 \begin{verbatim}
@@ -3154 +3142 @@
 \end{verbatim}
 
-The output from a FFT and power spectrum must be of the same size as
-the input.  In the future, if this adversely affects performance, this
-will be revised so that the redundant information will be neglected.
+The output from a FFT must be of the same size as the input, and the
+size of the power spectrum equal to $N/2 + 1$, where $N$ is the number
+of elements in the input.  In the future, if this adversely affects
+performance, this will be revised so that the redundant information
+will be neglected.
 
 In analogy with the vector FFT operations, we also define matching
@@ -3251 +3241 @@
 
 If the vectors are not all of the same number of elements, then the
-function shall generate a warning shall be generated, following which,
-the longer vector trimmed to the length of the shorter, and the
-function shall continue.
+function shall generate an error and return \code{NULL}.
 
 \subsubsection{Convolve an image with the kernel}
@@ -3889 +3877 @@
 which follows the conventions of the \code{psList} iterators.
 \begin{verbatim}
-void psMetadataSetIterator(psMetadata *md, int iterator, int location);
+bool psMetadataSetIterator(psMetadata *md, int iterator, int location);
 psMetadataItem *psMetadataGetNext(psMetadata *md, const char *match, int iterator);
 psMetadataItem *psMetadataGetPrevious(psMetadata *md, const char *match, int iterator);
@@ -3903 +3891 @@
 data type, printing is not allowed.
 \begin{verbatim}
-void psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *md);
+bool psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *md);
 \end{verbatim}