Changeset 534 for trunk/doc/pslib/psLibSDRS.tex
- Timestamp:
- Apr 27, 2004, 2:27:24 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/pslib/psLibSDRS.tex (modified) (37 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/pslib/psLibSDRS.tex
r518 r534 1 %%% $Id: psLibSDRS.tex,v 1.3 8 2004-04-27 00:33:18 eugene Exp $1 %%% $Id: psLibSDRS.tex,v 1.39 2004-04-28 00:27:24 price Exp $ 2 2 \documentclass[panstarrs]{panstarrs} 3 3 … … 1083 1083 example, if $x$ were a vector of 100 elements, but $y$ were a vector 1084 1084 of 1000 elements, the meaning of the operation $x + y$ is unclear. 1085 This type of operation should be invalid .1085 This type of operation should be invalid and should generate an error. 1086 1086 1087 1087 Given that some functions should be able to operate equivalently (or … … 1115 1115 PS_DIMEN_VECTOR, ///< A vector 1116 1116 PS_DIMEN_TRANSV, ///< A transposed vector 1117 PS_DIMEN_ MATRIX, ///< A matrix1117 PS_DIMEN_IMAGE, ///< An image (matrix) 1118 1118 PS_DIMEN_OTHER ///< Something else that's not supported for arithmetic 1119 1119 } psDimen; … … 1137 1137 \end{verbatim} 1138 1138 We discuss the application of \code{psType} in more detail in 1139 section~\ref{ math}.1139 section~\ref{arithmetic}. 1140 1140 1141 1141 \subsection{Arrays of Simple Types} 1142 1142 1143 1143 We require several types of basic one-dimensional arrays: arrays of 1144 values of type \code{int}, \code{float}, \code{double}, \code{complex float},1145 and \code{void *}. We have defined structures for these types1144 values of type \code{int}, \code{float}, \code{double}, \code{complex 1145 float}, and \code{void *}. We have defined structures for these types 1146 1146 which are all equivalent. We illustrate them with the example of 1147 1147 \code{psFloatArray}: … … 1150 1150 typedef struct { 1151 1151 psType type; ///< Type of data. Must be first element 1152 int n alloc; ///< Total number of elements available1152 int nAlloc; ///< Total number of elements available 1153 1153 int n; ///< Number of elements in use 1154 1154 float *arr; ///< The array data … … 1157 1157 % 1158 1158 In this structure, the argument \code{n} is the length of the array 1159 (the number of elements); \code{ size} is the number of elements1159 (the number of elements); \code{nAlloc} is the number of elements 1160 1160 allocated ($s \ge n$). The allocated memory is available at 1161 1161 \code{arr}. The data type is defined by the first element, … … 1164 1164 % 1165 1165 \begin{verbatim} 1166 psFloatArray *psFloatArrayAlloc(int n alloc);1167 psFloatArray *psFloatArrayRealloc(psFloatArray *myArray, int n alloc);1166 psFloatArray *psFloatArrayAlloc(int nAlloc); 1167 psFloatArray *psFloatArrayRealloc(psFloatArray *myArray, int nAlloc); 1168 1168 void psFloatArrayFree(psFloatArray *restrict myArray); 1169 1169 \end{verbatim} 1170 1170 % 1171 In these functions, \code{n alloc} is the number of elements to1171 In these functions, \code{nAlloc} is the number of elements to 1172 1172 allocate. For \code{psFloatArrayAlloc}, the value of 1173 1173 \code{psFloatArray.n} is set to 0. For \code{psFloatArrayRealloc}, if 1174 the value of \code{n alloc} is smaller than the current value of1174 the value of \code{nAlloc} is smaller than the current value of 1175 1175 \code{psFloatArray.n}, then \code{psFloatArray.n} is set to 1176 \code{n alloc}, the array is adjusted down to match \code{nalloc}, and1177 the extra elements are lost. If \code{n alloc} is larger than the1176 \code{nAlloc}, the array is adjusted down to match \code{nAlloc}, and 1177 the extra elements are lost. If \code{nAlloc} is larger than the 1178 1178 current value of \code{psFloatArray.n}, \code{psFloatArray.n} is left 1179 1179 intact. If the value of \code{myArray} is \code{NULL}, then … … 1185 1185 appropriate type. Thus we have: 1186 1186 \begin{verbatim} 1187 psIntArray *psIntArrayAlloc(int n alloc);1188 psFloatArray *psFloatArrayAlloc(int n alloc);1189 psDoubleArray *psDoubleArrayAlloc(int n alloc);1190 psComplexArray *psComplexArrayAlloc(int n alloc);1187 psIntArray *psIntArrayAlloc(int nAlloc); 1188 psFloatArray *psFloatArrayAlloc(int nAlloc); 1189 psDoubleArray *psDoubleArrayAlloc(int nAlloc); 1190 psComplexArray *psComplexArrayAlloc(int nAlloc); 1191 1191 \end{verbatim} 1192 1192 and so on for the other functions. The collection of structures and … … 1204 1204 typedef struct { 1205 1205 psType type; ///< Type of data. Must be first element 1206 int n alloc; ///< Total number of elements available1206 int nAlloc; ///< Total number of elements available 1207 1207 int n; ///< Number of elements in use 1208 1208 void **arr; ///< The array data … … 1213 1213 % 1214 1214 \begin{verbatim} 1215 psVoidPtrArray *psVoidPtrArrayAlloc(int n alloc);1216 psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *myArray, int n alloc);1215 psVoidPtrArray *psVoidPtrArrayAlloc(int nAlloc); 1216 psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *myArray, int nAlloc); 1217 1217 void psVoidPtrArrayFree(psVoidPtrArray *restrict myArray, void (*elemFree)(void *)); 1218 1218 \end{verbatim} … … 1509 1509 psBitset * 1510 1510 psBitsetSet(psBitset *restrict myBits, ///< Input bitset 1511 int bit///< Bit to set1511 int bit ///< Bit to set 1512 1512 ); 1513 1513 \end{verbatim} … … 1619 1619 psStats * 1620 1620 psArrayStats(const psFloatArray *restrict myArray, ///< Array to be analysed 1621 1622 1623 unsigned int maskVal,///< Only mask elements with one of these bits set in maskArray1624 psStats *stats///< stats structure defines stats to be calculated and how1621 const psIntArray *restrict maskArray, ///< Ignore elements where (maskArray & maskVal) != 0 1622 ///< May be NULL 1623 unsigned int maskVal, ///< Only mask elements with one of these bits set in maskArray 1624 psStats *stats ///< stats structure defines stats to be calculated and how 1625 1625 ); 1626 1626 \end{verbatim} … … 1637 1637 /** generic statistics structure */ 1638 1638 typedef struct { 1639 double sampleMean; 1640 double sampleMedian; 1641 double sampleStdev; 1642 double sampleUQ; 1643 double sampleLQ; 1644 double robustMean; 1645 int robustMeanNvalues; 1646 double robustMedian; 1647 int robustMedianNvalues; 1648 double robustMode; 1649 int robustModeNvalues; 1650 double robustStdev; 1651 double robustUQ; 1652 double robustLQ; 1653 double clippedMean; 1654 int clippedMeanNvalues; 1655 double clippedStdev; 1656 double clipSigma; 1657 int clipIter; 1658 double min; 1659 double max; 1660 int nValues; 1661 psStatsOptions options; 1639 double sampleMean; ///< formal mean of sample 1640 double sampleMedian; ///< formal median of sample 1641 double sampleStdev; ///< standard deviation of sample 1642 double sampleUQ; ///< upper quartile of sample 1643 double sampleLQ; ///< lower quartile of sample 1644 double robustMean; ///< robust mean of array 1645 int robustMeanNvalues; ///< number of measurements used for robust mean 1646 double robustMedian; ///< robust median of array 1647 int robustMedianNvalues; ///< number of measurements used for robust median 1648 double robustMode; ///< Robust mode of array 1649 int robustModeNvalues; ///< Number of measurements used for robust mode 1650 double robustStdev; ///< robust standard deviation of array 1651 double robustUQ; ///< robust upper quartile 1652 double robustLQ; ///< robust lower quartile 1653 double clippedMean; ///< Nsigma clipped mean 1654 int clippedMeanNvalues; ///< number of data points used for clipped mean 1655 double clippedStdev; ///< standard deviation after clipping 1656 double clipSigma; ///< Nsigma used for clipping; user input 1657 int clipIter; ///< Number of clipping iterations; user input 1658 double min; ///< minimum data value in array 1659 double max; ///< maximum data value in array 1660 int nValues; ///< number of data values in array 1661 psStatsOptions options; ///< bitmask of calculated values 1662 1662 } psStats; 1663 1663 \end{verbatim} … … 1671 1671 PS_STAT_SAMPLE_MEDIAN = 0x000002, 1672 1672 PS_STAT_SAMPLE_STDEV = 0x000004, 1673 PS_STAT_SAMPLE_UQ 1674 PS_STAT_SAMPLE_LQ 1673 PS_STAT_SAMPLE_UQ = 0x000008, 1674 PS_STAT_SAMPLE_LQ = 0x000010, 1675 1675 PS_STAT_ROBUST_MEAN = 0x000020, 1676 1676 PS_STAT_ROBUST_MEAN_NVALUES = 0x000040, … … 1680 1680 PS_STAT_ROBUST_MODE_NVALUES = 0x000400, 1681 1681 PS_STAT_ROBUST_STDEV = 0x000800, 1682 PS_STAT_ROBUST_UQ 1683 PS_STAT_ROBUST_LQ 1682 PS_STAT_ROBUST_UQ = 0x001000, 1683 PS_STAT_ROBUST_LQ = 0x002000, 1684 1684 PS_STAT_CLIPPED_MEAN = 0x004000, 1685 1685 PS_STAT_CLIPPED_MEAN_NVALUES = 0x008000, 1686 1686 PS_STAT_CLIPPED_MEAN_NSIGMA = 0x010000, 1687 1687 PS_STAT_CLIPPED_STDEV = 0x020000, 1688 PS_STAT_MAX 1689 PS_STAT_MIN 1690 PS_STAT_NVALUES 1691 } psStatsOptions; 1688 PS_STAT_MAX = 0x040000, 1689 PS_STAT_MIN = 0x080000, 1690 PS_STAT_NVALUES = 0x100000 1691 } psStatsOptions; 1692 1692 \end{verbatim} 1693 1693 … … 1697 1697 /** Constructor */ 1698 1698 psStats * 1699 psStatsAlloc(psStatsOptions options 1699 psStatsAlloc(psStatsOptions options ///< Statistics to measure 1700 1700 ); 1701 1701 1702 1702 /** Destructor */ 1703 1703 void 1704 psStatsFree(psStats *restrict stats 1704 psStatsFree(psStats *restrict stats ///< Stats structure to destroy 1705 1705 ); 1706 1706 \end{verbatim} … … 1764 1764 psHistogram * 1765 1765 psGetArrayHistogram(psHistogram *restrict myHist, ///< Histogram data 1766 1766 const psFloatArray *restrict myArray ///< Array to analyse 1767 1767 ); 1768 1768 \end{verbatim} … … 1772 1772 \subsection{Matrix operations and linear algebra} 1773 1773 1774 In addition to the ability to perform image arithmetic (\S\ref{sec:arithmetic}), 1775 we also require the ability to perform basic linear algebra on matrices, in order 1776 to solve equations. We use \code{psImage} as a matrix, since it has the correct 1777 form, and we define the following basic matrix operations: 1774 In addition to the ability to perform image arithmetic 1775 (\S\ref{sec:arithmetic}), we also require the ability to perform basic 1776 linear algebra on matrices, in order to solve equations. We use 1777 \code{psImage} as a matrix, since it has the correct form; similarly, 1778 we define a vector, \code{psVector} to be an array of floating-point 1779 numbers, \code{psFloatArray}. We define the following basic matrix 1780 operations: 1778 1781 \begin{itemize} 1779 1782 \item $LU$ Decompose a matrix, and solve for $x$ in $Ax = b$; … … 1789 1792 /** LU Decomposition of a matrix */ 1790 1793 psImage * 1791 psMatrixLUD(psImage *out, 1792 psImage *myMatrix///< Matrix to decompose1793 1794 psMatrixLUD(psImage *out, ///< Matrix to return, or NULL 1795 psImage *myMatrix ///< Matrix to decompose 1796 ); 1794 1797 1795 1798 /** LU Solution. Solves for and returns x in the equation Ax = b */ 1796 1799 psVector * 1797 psMatrixLUSolve(psVector *out, 1798 1799 1800 1800 psMatrixLUSolve(psVector *out, ///< Vector to return, or NULL 1801 const psImage *luMatrix, ///< LU-decomposed matrix 1802 const psVector *rhsVector ///< right-hand-side of the equation 1803 ); 1801 1804 \end{verbatim} 1802 1805 … … 1810 1813 \begin{verbatim} 1811 1814 /** Invert matrix. Not using restrict, to allow inversion to be done in-place */ 1812 ps Matrix*1813 psMatrixInvert(ps Matrix*out, ///< Matrix to return, or NULL1814 const ps Matrix*myMatrix, ///< Matrix to be inverted1815 psImage * 1816 psMatrixInvert(psImage *out, ///< Matrix to return, or NULL 1817 const psImage *myMatrix, ///< Matrix to be inverted 1815 1818 float *restrict determinant ///< Determinant to return, or NULL 1816 1819 ); … … 1827 1830 /** Matrix determinant */ 1828 1831 float 1829 psMatrixDeterminant(const ps Matrix*restrict myMatrix //!< Matrix to get determinant for1832 psMatrixDeterminant(const psImage *restrict myMatrix //!< Matrix to get determinant for 1830 1833 ); 1831 1834 \end{verbatim} … … 1842 1845 \begin{verbatim} 1843 1846 /** Matrix operations */ 1844 ps Matrix*1845 psMatrixOp(ps Matrix*out, ///< Matrix to return, or NULL1846 const ps Matrix*matrix1, ///< Matrix 11847 psImage * 1848 psMatrixOp(psImage *out, ///< Matrix to return, or NULL 1849 const psImage *matrix1, ///< Matrix 1 1847 1850 const char *op, ///< Operation to perform: "+", "-", "*" 1848 const ps Matrix*matrix2 ///< Matrix 21851 const psImage *matrix2 ///< Matrix 2 1849 1852 ); 1850 1853 \end{verbatim} … … 1855 1858 \begin{verbatim} 1856 1859 /** Transpose Matrix */ 1857 ps Matrix*1858 psMatrixTranspose(ps Matrix*out, ///< Matrix to return, or NULL1859 const ps Matrix*myMatrix ///< Matrix to transpose1860 psImage * 1861 psMatrixTranspose(psImage *out, ///< Matrix to return, or NULL 1862 const psImage *myMatrix ///< Matrix to transpose 1860 1863 ); 1861 1864 \end{verbatim} … … 1869 1872 /** Convert matrix to vector. Intended for a 1-d matrix. */ 1870 1873 psVector * 1871 psMatrixToVector(psVector *out, 1872 psImage *myMatrix///< Matrix to convert1874 psMatrixToVector(psVector *out, ///< Vector to return, or NULL 1875 psImage *myMatrix ///< Matrix to convert 1873 1876 ); 1874 1877 … … 1895 1898 /** Fast Fourier Transform */ 1896 1899 typedef struct { 1897 p_psFFTDetails *details; 1898 int nx, ny; 1899 float *real; 1900 void *fourier; 1900 p_psFFTDetails *details; ///< Details on FFT implementation (private) 1901 int nx, ny; ///< Size in x and y 1902 float *real; ///< Data in real space: a 2D array using the [nx*y + x] stuff 1903 void *fourier; ///< Data in fourier space; implementation dependent 1901 1904 } psFFT; 1902 1905 \end{verbatim} … … 1944 1947 /** Forward FFT: from real to fourier space */ 1945 1948 psFFT * 1946 psFFTForward(psFFT *fft 1947 1949 psFFTForward(psFFT *fft ///< FFT to apply (input and output) 1950 ); 1948 1951 1949 1952 /** Reverse FFT: from fourier to real space */ 1950 1953 psFFT * 1951 psFFTReverse(psFFT *fft 1952 1954 psFFTReverse(psFFT *fft ///< FFT to apply (input and output) 1955 ); 1953 1956 \end{verbatim} 1954 1957 … … 1997 2000 /** Calculate FFT of the convolution. Straight multiplication of the FFTs */ 1998 2001 psFFT * 1999 psFFTConvolve(psFFT *out, 2000 2001 2002 psFFTConvolve(psFFT *out, ///< Output FFT (or NULL) 2003 const psFFT *fft1, const psFFT *fft2 ///< FFTs to multiply 2004 ); 2002 2005 \end{verbatim} 2003 2006 … … 2008 2011 /** Calculate power spectrum */ 2009 2012 psFloatArray * 2010 psFFTPowerSpec(psFFT *fft 2011 2013 psFFTPowerSpec(psFFT *fft ///< FFT to use (input and output) 2014 ); 2012 2015 \end{verbatim} 2013 2016 … … 2139 2142 psFloatArray * 2140 2143 psMinimize(float (*myFunction)(const psFloatArray *restrict), ///< Function to minimize 2141 psFloatArray *restrict initialGuess,///< Initial guess2142 2143 2144 psFloatArray *restrict initialGuess, ///< Initial guess 2145 psIntArray *restrict paramMask //!< 1 = fit for parameter, 0 = hold parameter constant 2146 ); 2144 2147 \end{verbatim} 2145 2148 … … 2154 2157 psFloatArray * 2155 2158 psMinimizeChi2(float (*evalModel)(const psFloatArray *restrict, 2156 2157 2158 2159 2160 2161 2159 const psFloatArray *restrict), ///< Model to fit; (domain and params) 2160 const psFloatArray *restrict domain, ///< The domain values for the corresponding measurements 2161 const psFloatArray *restrict data, ///< Data to fit 2162 const psFloatArray *restrict errors, ///< Errors in the data 2163 psFloatArray *restrict initialGuess, ///< Initial guess 2164 const psIntArray *restrict paramMask ///< 1 = fit for parameter, 0 = hold parameter constant 2162 2165 ); 2163 2166 \end{verbatim} … … 2175 2178 psPolynomial1D * 2176 2179 psGetArrayPolynomial(psPolynomial1D myPoly, ///< Polynomial to fit 2177 2178 2179 2180 const psFloatArray *restrict x, ///< Ordinates (or NULL to just use the indices) 2181 const psFloatArray *restrict y, ///< Coordinates 2182 const psFloatArray *restrict yErr ///< Errors in coordinates, or NULL 2180 2183 ); 2181 2184 \end{verbatim} … … 2203 2206 int x0, y0; ///< data region relative to parent 2204 2207 union { 2205 psF32 **rows; ///< == rows_f322206 psS8 **rows_s8; ///< pointers to psS8 data2207 psS16 **rows_s16; ///< pointers to psS16 data2208 psS32 **rows_s32; ///< pointers to psS32 data2209 psU8 **rows_u8; ///< pointers to psU8 data2210 psU16 **rows_u16; ///< pointers to psU16 data2211 psU32 **rows_u32; ///< pointers to psU32 data2212 psF32 **rows_f32; ///< pointers to psF32 data2213 psF64 **rows_f64; ///< pointers to psF64 data2214 psComplex **rows_complex; ///< pointers to psComplexdata2208 float **rows; ///< Pointers to floating-point data (default) 2209 short int **rows_si; ///< Pointers to short-integer data 2210 int **rows_i; ///< Pointers to integer data 2211 long int **rows_li; ///< Pointers to long-integer data 2212 unsigned short int **rows_usi; ///< Pointers to unsigned-short-integer data 2213 unsigned int **rows_ui; ///< Pointers to unsigned-integer data 2214 unsigned long int **rows_uli; ///< Pointers to unsigned-long-integer data 2215 float **rows_f; ///< Pointers to floating-point data 2216 double **rows_d; ///< Pointers to double-precision data 2217 complex float **rows_complex; ///< Pointers to complex floating-point data 2215 2218 } rows; 2216 psImage *parent;///< parent, if a subimage2219 struct psImage *parent; ///< parent, if a subimage 2217 2220 int Nchildren; ///< number of subimages 2218 psImage *children;///< children of this region; array of Nchildren pointers2221 struct psImage *children; ///< children of this region; array of Nchildren pointers 2219 2222 } psImage; 2220 2223 \end{verbatim} … … 2223 2226 pixels. The size of this array is given by the elements \code{(nx, 2224 2227 ny)}. The data type of the pixel is defined by the \code{psType type} 2225 entry (see \ref{TBD}). (n.b. that for FITS images, these values are 2226 restricted to the datatypes equivalent to the valid BITPIX values 8, 2227 16, 32, -32, -64). The image represented in the data structure may 2228 represent a subset of the pixels in a complete array, in which case 2229 the image is considered to be the child of that parent array. The 2230 offset of the \code{(0,0)} pixel in this array relative to the parent 2231 array is given by the elements \code{(x0,y0)}. The structure may 2232 include references to subrasters (\code{children, Nchildren}) and/or 2233 to a containing array (\code{parent}). Unless this is image is a 2234 child of another image (represents a subset of the pixels of another 2235 image), the image data is allocated in a contiguous block. 2228 entry (see \ref{arithmetic}). (n.b. that for FITS images, these 2229 values are restricted to the datatypes equivalent to the valid BITPIX 2230 values 8, 16, 32, -32, -64). The image represented in the data 2231 structure may represent a subset of the pixels in a complete array, in 2232 which case the image is considered to be the child of that parent 2233 array. The offset of the \code{(0,0)} pixel in this array relative to 2234 the parent array is given by the elements \code{(x0,y0)}. The 2235 structure may include references to subrasters (\code{children, 2236 Nchildren}) and/or to a containing array (\code{parent}). Unless this 2237 is image is a child of another image (represents a subset of the 2238 pixels of another image), the image data is allocated in a contiguous 2239 block. 2236 2240 2237 2241 We require a variety of functions to manipulate these image … … 2511 2515 expected that the implementation of these functions will employ 2512 2516 pre-processor macros to perform the onerous task of creating the 2513 loops. Also note that \code{psVectors} is equivalent to 2514 \code{psFloatArray}. 2517 loops. Also note that \code{psVector} is equivalent to 2518 \code{psFloatArray}. An attempt to perform an arithmetic operation on 2519 an object of dimension \code{PS_DIMEN_OTHER} should produce an error. 2515 2520 2516 2521 Binary operations between an image and a vector have a potential … … 2932 2937 /// Add item to the end of the metadata. Combines psMetadataItemAlloc and psMetadataAppendItem 2933 2938 psMetadataItem *psMetadataAppend(psMetadata *restrict md, ///< Metadata to add to 2934 2935 2936 2937 2938 2939 2940 ...///< possible arguments for name format2939 int typeFlags ///< type of this piece of metadata + flags 2940 const void *val, ///< value of new item N.b. a pointer even if the item 2941 ///< is of type e.g. int 2942 const char *comment, ///< comment associated with item 2943 const char *name, ///< name of new item of metadata (may be in sprintf 2944 ///< format) 2945 ... ///< possible arguments for name format 2941 2946 ); 2942 2947 \end{verbatim} … … 3346 3351 typedef struct { 3347 3352 int x0, y0; ///< Offset from the lower-left corner 3348 int nx, ny; 3353 int nx, ny; ///< Image binning 3349 3354 psImage *image; ///< imaging area of cell 3350 3355 psDlist *objects; ///< objects derived from cell … … 3444 3449 psChip *chips; ///< Chips in the Focal Plane Array 3445 3450 3446 psMetadata *md; ///< FPA-level metadata3451 psMetadata *md; ///< FPA-level metadata 3447 3452 psDistortion *TPtoFP; ///< Transformation term from 3448 3453 psDistortion *FPtoTP; ///< Transformation term from
Note:
See TracChangeset
for help on using the changeset viewer.
