Index: /trunk/doc/pslib/psLibSDRS.tex
===================================================================
--- /trunk/doc/pslib/psLibSDRS.tex	(revision 373)
+++ /trunk/doc/pslib/psLibSDRS.tex	(revision 374)
@@ -1,3 +1,3 @@
-%%% $Id: psLibSDRS.tex,v 1.28 2004-04-01 09:44:17 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.29 2004-04-01 10:09:25 price Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -1232,7 +1232,6 @@
 /** Set a bit mask */
 psBitMask *
-psBitMaskSet(psBitMask *outMask,        ///< Output bit mask or NULL
-             const psBitMask *myMask,   ///< Input bit mask
-             int bit                    ///< Bit to set
+psBitMaskSet(psBitMask *myMask,		///< Input bit mask
+	     int bit			///< Bit to set
     );
 \end{verbatim}
@@ -1341,12 +1340,12 @@
 
 \begin{verbatim}
-/** Do Statistics on an array.  Returns a status value. */
+/** Do Statistics on an array.  Returns a status value. \ingroup MathGroup */
 psStats *
 psArrayStats(const psFloatArray *restrict myArray, ///< Array to be analysed
-             const psIntArray *restrict maskArray, ///< Ignore elements where (maskArray & maskVal) != 0
-                                                   ///< May be NULL
-             unsigned int maskVal,      ///< Only mask elements with one of these bits set in maskArray
-             psStats *stats             ///< stats structure defines stats to be calculated and how
-             );
+	     const psIntArray *restrict maskArray, ///< Ignore elements where (maskArray & maskVal) != 0
+						   ///< May be NULL
+	     unsigned int maskVal,	///< Only mask elements with one of these bits set in maskArray
+	     psStats *stats		///< stats structure defines stats to be calculated and how
+    );
 \end{verbatim}
 %
@@ -1570,5 +1569,5 @@
 psMatrixOp(psMatrix *out,               ///< Matrix to return, or NULL
            const psMatrix *matrix1,     ///< Matrix 1
-           const char *op,              ///< Operation to perform
+           const char *op,              ///< Operation to perform: "+", "-", "*"
            const psMatrix *matrix2      ///< Matrix 2
            );
@@ -1594,5 +1593,6 @@
 /** Convert matrix to vector.  Intended for a 1-d matrix. */
 psVector *
-psMatrixToVector(psMatrix *myMatrix     ///< Matrix to convert
+psMatrixToVector(psVector *out,		///< Vector to return, or NULL
+		 psImage *myMatrix	///< Matrix to convert
     );
 
@@ -1619,19 +1619,24 @@
 /** Fast Fourier Transform */
 typedef struct {
-    p_psFFTDetails *details;            //!< Details on FFT implementation (private)
-    int nx, ny;                         //!< Size in x and y
-    float **real;                       //!< Data in real space
-    void *fourier;                      //!< Data in fourier space; implementation dependent
+    p_psFFTDetails *details;		///< Details on FFT implementation (private)
+    int nx, ny;				///< Size in x and y
+    float *real;			///< Data in real space: a 2D array using the [nx*y + x] stuff
+    void *fourier;			///< Data in fourier space; implementation dependent
 } psFFT;
 \end{verbatim}
 
-The \code{*details} entry allows us to wrap the external library in
-the event that it carries information around from one transform to the
+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.
+implementation-dependent.  The size of the data in real space are
+stored in \code{nx} and \code{ny}, and the data is stored as a
+Fortran-style array, \code{real}.  Since different libraries store the
+data in the Fourier space differently, \code{fourier}, we have
+specified it as of type \code{void*}.
+
+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
@@ -1663,11 +1668,11 @@
 /** Forward FFT: from real to fourier space */
 psFFT *
-psFFTForwardTransform(psFFT *fft        //!< FFT to apply
-                      );
+psFFTForward(psFFT *fft			///< FFT to apply (input and output)
+	     );
 
 /** Reverse FFT: from fourier to real space */
 psFFT *
-psFFTReverseTransform(psFFT *fft        //!< FFT to apply
-                      );
+psFFTReverse(psFFT *fft			///< FFT to apply (input and output)
+	     );
 \end{verbatim}
 
@@ -1701,5 +1706,7 @@
 
 \begin{verbatim}
-/** Calculate cross-correlation function */
+/** Calculate FFT of the cross-correlation.  Multiplication of the first FFT with the complex conjugate of
+ *  the second.
+ */
 psFFT *
 psFFTCrossCorrelate(psFFT *out          //!< Output FFT (or NULL)
@@ -1708,4 +1715,15 @@
 \end{verbatim}
 
+In convolution, two Fourier transforms are multiplied, and the resultant
+\code{psFFT} is returned.
+
+\begin{verbatim}
+/** Calculate FFT of the convolution.  Straight multiplication of the FFTs */
+psFFT *
+psFFTConvolve(psFFT *out,		///< Output FFT (or NULL)
+	      const psFFT *fft1, const psFFT *fft2 ///< FFTs to multiply
+	      );
+\end{verbatim}
+
 The power spectrum is calculated from the Fourier transform, returning
 an array of floating-point values containing the power spectrum.
@@ -1713,18 +1731,7 @@
 \begin{verbatim}
 /** Calculate power spectrum */
-psFFT *
-psFFTPowerSpec(psFFT *fft               //!< FFT to use (input and output)
-               );
-\end{verbatim}
-
-In convolution, two Fourier transforms are multiplied, and the resultant
-\code{psFFT} is returned.
-
-\begin{verbatim}
-/** Multiply two Fourier transforms, as for convolution */
-psFFT *
-psFFTMultiplyFT(psFFT *out,             //!< Output FFT (or NULL)
-                const psFFT *fft1, const psFFT *fft2 //!< FFTs to multiply
-                );
+psFloatArray *
+psFFTPowerSpec(psFFT *fft		///< FFT to use (input and output)
+	       );
 \end{verbatim}
 
@@ -1757,5 +1764,5 @@
 
 \begin{verbatim}
-/** evaluate a non-normalized Gaussian with the given mean and sigma at the given coordianate.  Note that this
+/** Evaluate a non-normalized Gaussian with the given mean and sigma at the given coordianate.  Note that this
     is not a Gaussian deviate.  The evaluated Gaussian is: \f[ exp(-\frac{(x-mean)^2}{2\sigma^2}) \f] */
 float
@@ -1841,5 +1848,5 @@
 \end{verbatim}
 
-\tbd{Generate a Gaussian deviate vector}
+\tbd{Generate a vector of random Gaussian deviates}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1853,9 +1860,10 @@
 
 \begin{verbatim}
-/** Minimize a particular function */
+/** Minimize a particular non-linear function */
 psFloatArray *
-psMinimize(float (*myFunction)(const psFloatArray *restrict),   ///< Function to minimize
-           psFloatArray *restrict initialGuess ///< Initial guess
-           );
+psMinimize(float (*myFunction)(const psFloatArray *restrict), ///< Function to minimize
+	   psFloatArray *restrict initialGuess,	///< Initial guess
+	   psIntArray *restrict paramMask //!< 1 = fit for parameter, 0 = hold parameter constant
+	   );
 \end{verbatim}
 
@@ -1870,12 +1878,11 @@
 psFloatArray *
 psMinimizeChi2(float (*evalModel)(const psFloatArray *restrict,
-                                  const psFloatArray *restrict), ///< Model to fit; receives domain and
-                                                                 ///< parameters
-               const psFloatArray *restrict domain, ///< The domain values for the corresponding measurements
-               const psFloatArray *restrict data, ///< Data to fit
-               const psFloatArray *restrict errors, ///< Errors in the data
-               psFloatArray *restrict initialGuess, ///< Initial guess
-               const psIntArray *restrict guessMask ///< 1 = fit for parameter, 0 = hold parameter constant
-               );
+				  const psFloatArray *restrict), ///< Model to fit; (domain and params)
+	       const psFloatArray *restrict domain, ///< The domain values for the corresponding measurements
+	       const psFloatArray *restrict data, ///< Data to fit
+	       const psFloatArray *restrict errors, ///< Errors in the data
+	       psFloatArray *restrict initialGuess, ///< Initial guess
+	       const psIntArray *restrict paramMask ///< 1 = fit for parameter, 0 = hold parameter constant
+    );
 \end{verbatim}
 
@@ -1889,8 +1896,10 @@
 
 \begin{verbatim}
-/** Derive a polynomial that goes through the points --- can be done analytically */
-psFloatArray *
-psGetArrayPolynomial(const psFloatArray *restrict ord, ///< Ordinates (or NULL to just use the indices)
-                     const psFloatArray *restrict coord ///< Coordinates
+/** Derive a polynomial fit by chi^2 minimisation --- can be done analytically */
+psPolynomial1D *
+psGetArrayPolynomial(psPolynomial1D myPoly, ///< Polynomial to fit
+		     const psFloatArray *restrict x, ///< Ordinates (or NULL to just use the indices)
+		     const psFloatArray *restrict y, ///< Coordinates
+		     const psFloatArray *restrict yErr ///< Errors in coordinates, or NULL
     );
 \end{verbatim}