Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 366) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 367) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.27 2004-04-01 09:42:39 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.28 2004-04-01 09:44:17 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -1479,38 +1479,28 @@ \end{verbatim} +The following function populates the histogram bins from the specified +array (\code{myArray}), the number of entries less than \code{minVal} +(\code{minNum}), and the number of entries greater than \code{maxVal} +(\code{maxNum}). It alters and returns the \code{psHistogram} +structure. + +\begin{verbatim} +/** Calculate a histogram \ingroup MathGroup **/ +psHistogram * +psGetArrayHistogram(psHistogram *restrict myHist, ///< Histogram data + const psFloatArray *restrict myArray ///< Array to analyse + ); +\end{verbatim} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Matrix operations and linear algebra} -We require the ability to perform basic linear algebra on matrices, in -order to solve equations: - -\begin{verbatim} -/** A matrix */ -typedef struct { - int xSize, ySize; ///< Dimensions in x and y - float *restrict *restrict value; ///< Values in matrix -} psMatrix; -\end{verbatim} - -Constructor and destructor are: - -\begin{verbatim} -/** Constructor */ -psMatrix * -psMatrixAlloc(int Xdimen, ///< x dimension of new matrix - int Ydimen ///< y dimension of new matrix - ); -\end{verbatim} - -\begin{verbatim} -/** Destructor */ -void -psMatrixFree(psMatrix *restrict myMatrix ///< Matrix to destroy - ); -\end{verbatim} - -We require the following basic matrix operations: +In addition to the ability to perform image arithmetic (\S\ref{sec:arithmetic}), +we also require the ability to perform basic linear algebra on matrices, in order +to solve equations. We use \code{psImage} as a matrix, since it has the correct +form, and we define the following basic matrix operations: \begin{itemize} +\item $LU$ Decompose a matrix, and solve for $x$ in $Ax = b$; \item Invert a matrix; \item Calculate a matrix determinant; @@ -1519,5 +1509,27 @@ \item Convert a matrix to a vector. \end{itemize} -The corresponding APIs are: +The corresponding APIs follow. + +\begin{verbatim} +/** LU Decomposition of a matrix */ +psImage * +psMatrixLUD(psImage *out, ///< Matrix to return, or NULL + psImage *myMatrix ///< Matrix to decompose + ); + +/** LU Solution. Solves for and returns x in the equation Ax = b */ +psVector * +psMatrixLUSolve(psVector *out, ///< Vector to return, or NULL + const psImage *luMatrix, ///< LU-decomposed matrix + const psVector *rhsVector ///< right-hand-side of the equation + ); +\end{verbatim} + +The above functions decompose a matrix, \code{myMatrix}, into its $LU$ +representation (\code{psMatrixLUD}, which returns the decomposed +matrix), and uses the decomposed matrix to solve for $x$ in the +equation $Ax = b$. In this case, the $LU$ decomposed matrix $A$ is +specified as \code{luMatrix}, and $b$ is \code{rhsVector}; the +solution for $x$ is returned. \begin{verbatim} @@ -1530,4 +1542,11 @@ \end{verbatim} +\code{psMatrixInvert} returns the inverse of the specified matrix +(\code{myMatrix}), along with the \code{determinant}, if non-NULL. + +The matrix determinant may be calculated using +\code{psMatrixDeterminant}, which simply returns the determinant for +the specified matrix, \code{myMatrix}. + \begin{verbatim} /** Matrix determinant */ @@ -1536,4 +1555,13 @@ ); \end{verbatim} + +Matrix arithmetic is supported through \code{psMatrixOp}. Note that +\code{psMatrixOp} differs from \code{psBinaryOp} in that +multiplication with \code{psBinaryOp} acts on corresponding elements, +while \code{psMatrixOp} performs classical matrix multiplication +involving row and column operations. Addition and subtraction by +\code{psMatrixOp} are identical to that for \code{psBinaryOp} (since +that is how matrix addition is defined). Matrix division is not +defined. \begin{verbatim} @@ -1547,4 +1575,7 @@ \end{verbatim} +The transpose of an input matrix, \code{myMatrix}, is returned by +\code{psMatrixTranspose}. + \begin{verbatim} /** Transpose Matrix */ @@ -1555,4 +1586,9 @@ \end{verbatim} +Finally, we specify two functions to convert between matrices and +vectors. This allows the use of vectors in matrix arithmetic, since +a vector can be converted to a matrix, utilised, and the result can +be converted back to a vector if required. + \begin{verbatim} /** Convert matrix to vector. Intended for a 1-d matrix. */ @@ -1568,8 +1604,4 @@ \end{verbatim} -Note that \code{psMatrixOp} differs from \code{psBinaryOp} in that -\code{psBinaryOp} acts on each element independently, while -\code{psMatrixOp} performs classical matrix arithmetic, involving row -and column operations. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1594,11 +1626,12 @@ \end{verbatim} -The \code{p_psFFTDetails *details} entry allows us to wrap the -external library in the event that it carries information around from -one transform to the next (as is the case for FFTW). The intent is -that every function that employs a FFT will act on a \code{psFFT}. A -user will create a \code{psFFT} by stuffing it with the real data, -perform operations in Fourier space using the \code{psFFT}, and then -extract the output as an image when done. +The \code{*details} entry allows us to wrap the external library in +the event that it carries information around from one transform to the +next (as is the case for FFTW), and hence it is +implementation-dependent. The intent is that every function that +employs a FFT will act on a \code{psFFT}. A user will create a +\code{psFFT} by stuffing it with the real data, perform operations in +Fourier space using the \code{psFFT}, and then extract the output as +an image when done. We specify two constructors --- one for use with images, and the other @@ -1624,5 +1657,6 @@ \end{verbatim} -The forward and reverse Fourier transforms may be calculated: +The forward and reverse Fourier transforms may be calculated, +returning the altered \code{psFFT}: \begin{verbatim} @@ -1639,5 +1673,12 @@ The data in Fourier space may be filtered using functions that return -a multiplicative factor for a given position in Fourier space: +a multiplicative factor for a given position in Fourier space. These +function return the altered \code{psFFT}. If the filter function +specified for \code{psFFTFilter()} returns a real value, $r$, then the +corresponding value in the Fourier plane should be multiplied by $r$. +If the real and imaginary filter functions specified for +\code{psFFTFilterComplex()} return the values $r$ and $s$, +respectively, then the corresponding value in the Fourier plane should +be multiplied by the complex number $r + si$. \begin{verbatim} @@ -1667,5 +1708,6 @@ \end{verbatim} -The power spectrum is calculated from the Fourier transform: +The power spectrum is calculated from the Fourier transform, returning +an array of floating-point values containing the power spectrum. \begin{verbatim} @@ -1676,5 +1718,6 @@ \end{verbatim} -In convolution, two Fourier transforms are multiplied. +In convolution, two Fourier transforms are multiplied, and the resultant +\code{psFFT} is returned. \begin{verbatim} @@ -1687,5 +1730,8 @@ And finally, the user may extract both the real data and the complex -Fourier space data (without needing to destroy the \code{psFFT}). +Fourier space data as \code{psImage}s (without needing to destroy the +\code{psFFT}). For \code{psFFTGetFT}, note that the output image will be of +type \code{complex float}, since it extracts the data in the Fourier plane, +which is complex. \begin{verbatim} @@ -1783,5 +1829,6 @@ \end{verbatim} -And the polynomials may be evaluated: +And the polynomials may be evaluated, returning the value of the +polynomial at the specified coordinates: \begin{verbatim} @@ -1794,5 +1841,5 @@ \end{verbatim} -\tbd{generate a Gaussian deviate vector} +\tbd{Generate a Gaussian deviate vector} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1802,6 +1849,6 @@ We require a general minimization routine, a routine that will specifically minimize $\chi^2$ given a list of data with associated -errors, and a function that will analytically determine the polynomial -fit by least-squares. The APIs are: +errors, and a function that will analytically determine the best +polynomial fit by minimizing $\chi^2$. The APIs are: \begin{verbatim} @@ -1812,4 +1859,10 @@ ); \end{verbatim} + +\code{psMinimize} determines and returns the parameters that minimizes +the specified function. It takes as input a function, +\code{myFunction}, an initial guess for the parameters that minimize +the function, \code{initialGuess}, and an optional mask for the +parameters to minimize, \code{paramMask}. \begin{verbatim} @@ -1827,4 +1880,12 @@ \end{verbatim} +\code{psMinimizeChi2} fits a model to observations by minimizing +$\chi^2$, returing the best-fit parameters. The input parameters are +a function that evaluates the model for a specified domain, given the +parameters, \code{evalModel}; a list of observations, (\code{domain}, +\code{data}, and \code{errors}); an initial guess at the best-fit +parameters, \code{initialGuess}, and an optional mask specifying which +parameters are to be fit, \code{paramMask}. + \begin{verbatim} /** Derive a polynomial that goes through the points --- can be done analytically */ @@ -1834,4 +1895,13 @@ ); \end{verbatim} + +\code{psGetArrayPolynomial} calculates analytically and returns the +polynomial that best fits the observations. The input parameters are +a polynomial that specifies the fit order, \code{myPoly}, which will +be altered and returned with the best-fit coefficients; and the +observations, \code{x}, \code{y} and \code{yErr}. + +\TBD{Higher-order (primarily 2D) polynomial fits may also be specified +in the future.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2140,4 +2210,5 @@ \subsection{Vector and Image Arithmetic} +\label{sec:arithmetic} We will need to be able to perform various operations on vectors and