Changeset 284
- Timestamp:
- Mar 22, 2004, 7:21:01 PM (22 years ago)
- File:
-
- 1 edited
-
trunk/doc/pslib/psLibSDRS.tex (modified) (62 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/pslib/psLibSDRS.tex
r276 r284 10 10 \organization{Institute for Astronomy} 11 11 \version{DR} 12 \docnumber{PSDC- xxx-xxx}12 \docnumber{PSDC-430-007} 13 13 % note the use of the docnumber & version number: 14 14 % the complete PSDC document number is given by … … 24 24 \RevisionsStart 25 25 % version Date Description 26 \theversion & 2003 Mar 11 & Hacking\\26 \theversion & 2003 Mar 11-- & Draft \\ 27 27 \RevisionsEnd 28 28 … … 38 38 %a regular \code{\label}, but defines the hyperlink too). 39 39 40 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %41 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %42 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %40 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 41 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 42 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 43 43 44 44 \section{\PS{} Library (PSLib)} … … 58 58 \end{itemize} 59 59 60 Below we sketch out approximately 120APIs which specify the required60 Below we sketch out approximately 200~APIs which specify the required 61 61 capabilities. 62 62 63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %65 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 65 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 66 66 67 67 \section{System Utilities} … … 73 73 74 74 The \PS{} software system will need a level of memory management 75 placed between the operating system ( malloc/free) and the high level76 routines (e.g.\code{psMetaDataAlloc}).75 placed between the operating system (\code{malloc}/\code{free}) and 76 the high level routines (e.g.\ \code{psMetaDataAlloc}). 77 77 78 78 This layer is in addition to the possibility that specific heavily … … 80 80 but as we have specified that all user-level objects be allocated via 81 81 \code{typeAlloc/typeFree} functions, we will easily be able to 82 implement such functionality without impacting onthe facilities82 implement such functionality without impacting the facilities 83 83 described here. 84 84 … … 103 103 104 104 \item 105 We need to provide a mechanism for tracking and fixing memory 106 leaks. While it is possible to do this by linking with external107 libraries (\tbd{reference}), it is convenient to do so within the108 \PS{} framework.105 We need to provide a mechanism for tracking and fixing memory leaks. 106 While it is possible to do this by linking with external libraries 107 (e.g.\ Electric Fence, \href{gnu.org}), it is convenient to do so 108 within the \PS{} framework. 109 109 110 110 \item … … 126 126 The previous section laid out a number of desiderata for a memory 127 127 management system. Rather than implement our own heap-manager at this 128 stage of the project, I propose that we put in place a sufficient129 set of data structures and APIs, but initially implement only 130 a simple subset (e.g. that we not implement a multi-bucket memory 131 manager that takes in 100Mb chunks from the system and performs 132 sophisticateddefragmentation and garbage collection).128 stage of the project, we propose to put in place a sufficient set of 129 data structures and APIs, but initially implement only a simple subset 130 (e.g.\ that we not implement a multi-bucket memory manager that takes 131 in 100Mb chunks from the system and performs sophisticated 132 defragmentation and garbage collection). 133 133 134 134 Subject to agreement with the IfA, some of the functions proposed … … 184 184 The types and function prototypes for the part of the memory API 185 185 concerned with allocating and freeing memory are given in table 186 \ref{tabUsageAPI} ).186 \ref{tabUsageAPI}. 187 187 188 188 N.b. 189 189 \begin{itemize} 190 190 \item 191 The functions \code{psAlloc}, \code{psRealloc}, and 192 \code{psFree} are defined, and are required to be equivalent to193 \code{p_ps Alloc}, \code{p_psRealloc}, and \code{p_psFree}194 with the final two arguments \code{"(unknown)"} and \code{0}.191 The functions \code{psAlloc}, \code{psRealloc}, and \code{psFree} 192 are defined, and are required to be equivalent to \code{p_psAlloc}, 193 \code{p_psRealloc}, and \code{p_psFree} with the final two arguments 194 \code{__FILE__} and \code{__LINE__}. 195 195 196 196 In the descriptions that follow, I shall not distinguish between the … … 211 211 \item 212 212 In all cases, application code will call 213 \ code{p_\{psAlloc,psRealloc,psFree\}}via the macros defined above.213 \CODE|p_{psAlloc,psRealloc,psFree}| via the macros defined above. 214 214 215 215 \item … … 229 229 230 230 \item 231 Where practical and efficient, the memory manager shall call 232 the routine registered using the \code{psMemProblemSetCB}233 (see section \ref{secMemAdvanced})234 whenever a corrupted block of memory is discovered. For example,235 doubly-freed blocks can be detected bychecking \code{psMemBlock.refcntr}.231 Where practical and efficient, the memory manager shall call the 232 routine registered using the \code{psMemProblemSetCB} (see section 233 \ref{secMemAdvanced}) whenever a corrupted block of memory is 234 discovered. For example, doubly-freed blocks can be detected by 235 checking \code{psMemBlock.refcntr}. 236 236 237 237 \item 238 238 There is no \code{psCalloc} function. Initialisation of data is 239 239 almost always more complex than setting all bytes to 0. 240 Correspondingly, the system call \code{calloc} should be disabled 241 using the pre-processor. 240 242 \end{itemize} 241 243 … … 284 286 \begin{tabular}{ll|l} 285 287 \textbf{type} & \textbf{Name} & \textbf{Function of callback} \\ 286 psMemProblemCallback & psMemProblemSetCB&288 \code{psMemProblemCallback} & \code{psMemProblemSetCB} & 287 289 Called when a problem is detected with data being managed on the heap \\ 288 psMemExhaustedCallback & psMemExhaustedSetCB&290 \code{psMemExhaustedCallback} & \code{psMemExhaustedSetCB} & 289 291 Called when \code{psAlloc} is unable to satisfy a memory request. \\ 290 psMemCallback & psMemAllocateSetCB&292 \code{psMemCallback} & \code{psMemAllocateSetCB} & 291 293 Callback is called when the \code{psMemBlock} with a specified ID is 292 294 allocated. \\ 293 psMemCallback & psMemFreeSetCB&295 \code{psMemCallback} & \code{psMemFreeSetCB} & 294 296 Callback is called when the \code{psMemBlock} with a specified ID is 295 297 freed. \\ … … 310 312 311 313 \item 312 \code{psMemGetId} returns the current value of \code{psMemBlock.id}. 314 \code{psMemGetId} returns the next identification number to be 315 assigned to a \code{psMemBlock.id}. 313 316 314 317 \item … … 414 417 } 415 418 \end{verbatim} 416 \begin{caption}{An example of reference counting} 417 \hlabel{tabReferenceCounting} 418 An example of using reference counting 419 \end{caption} 419 \caption{An example of reference counting} 420 420 \end{table} 421 421 … … 443 443 \subsection{Tracing and Logging} 444 444 445 This documentdefines the \PS{} Tracing and Logging APIs; the former445 This section defines the \PS{} Tracing and Logging APIs; the former 446 446 refers to debug information that we wish to be able to turn on and off 447 447 without recompiling (although it will \emph{not} be available in … … 683 683 The fields included in the log message may be controlled using \code{psSetLogFormat} which 684 684 expects a string consisting of the letters \code{H} (host), \code{L} (level), \code{M} (message), 685 \code{N} (name), and \code{T} (time). The default is \code{ HLMNT}.686 687 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %685 \code{N} (name), and \code{T} (time). The default is \code{THLNM}, as shown above. 686 687 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 688 688 689 689 \section{Data Containers} … … 768 768 If \code{psDlistFree}'s argument \code{elemFree} is NULL, the 769 769 list should be deleted, but not the elements on it (although their 770 \code{refcounter} 's should be decremented).770 \code{refcounter}s should be decremented). 771 771 772 772 Iteration over all elements of the list is provided by the functions: … … 781 781 many iteration cursors should be used; it must currently always be \code{0}. 782 782 783 Explicit traversal of the list using the \code{psDlistElem} 's783 Explicit traversal of the list using the \code{psDlistElem}s 784 784 \code{prev} and \code{next} pointers is also supported. 785 785 … … 793 793 \subsection{The \PS{} Array types} 794 794 795 \begin{table}796 \begin{verbatim}797 \end{verbatim}798 \begin{caption}{The array creation macros defined in \file{psArray.h}}799 \hlabel{tabPsArray}800 \end{caption}801 \end{table}802 803 795 \subsubsection{Arrays of Simple Types} 804 796 805 Any \PS /datatype \code{psType} may be associated with an array type797 Any \PS{} datatype \code{psType} may be associated with an array type 806 798 \code{psTypeArray}: 807 799 \begin{verbatim} … … 825 817 from \file{psArray.h} (table \ref{tabPsArray}), 826 818 \code{PS_DECLARE_ARRAY_TYPE(psType)} and 827 \code{PS_CREATE_ARRAY_TYPE(psType)}. The former defines the typedef819 \code{PS_CREATE_ARRAY_TYPE(psType)}. The former defines the \code{typedef} 828 820 and declares the prototypes (and is thus suitable for use in a 829 821 header file); the latter generates the code for the three functions 830 \code{psType(Alloc|Realloc|Free } (and should thus appear in exactly one822 \code{psType(Alloc|Realloc|Free)} (and should thus appear in exactly one 831 823 source file for a given type). 832 824 … … 866 858 declares the prototypes (and is thus suitable for use in a header 867 859 file) and the latter generates the code for the three functions 868 \code{psType(Alloc|Realloc|Free } (and should thus appear in exactly one860 \code{psType(Alloc|Realloc|Free)} (and should thus appear in exactly one 869 861 source file for a given type). 870 862 … … 881 873 \hlabel{secArrayVoidPtr} 882 874 883 Arrays of \code{void *} are different, as the need an explicitly-specified875 Arrays of \code{void *} are different, as they need an explicitly-specified 884 876 destructor. 885 877 886 \file{psArray.h} shall specify a type \code{psVoidPtrArray} that 887 behaves in all respectsas if it had been created with:878 We require a type \code{psVoidPtrArray} that behaves in all respects 879 as if it had been created with: 888 880 \begin{verbatim} 889 881 typedef void *psVoidPtr; … … 1011 1003 1012 1004 The routine \code{psHashInsert} must provide a non-NULL \code{itemFree} 1013 argument if it wishes to change the value previously inserted keys;1005 argument if it wishes to change the value for previously inserted keys; 1014 1006 if \code{itemFree} is NULL attempting to insert a pre-existing key 1015 1007 is an error, and the routine will return NULL. If \code{psHashInsert} … … 1023 1015 1024 1016 \subsection{Miscellaneous Utilities} 1025 1026 The API for miscellaneous \PS{} utilities is provided by \file{psMisc.h}1027 which shall be included by \file{psUtils.h}.1028 1017 1029 1018 \begin{table} … … 1053 1042 \code{psStringCopy} shall allocate and return a copy of the input string. 1054 1043 1055 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1056 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1057 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1044 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1045 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1046 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1058 1047 1059 1048 \section{Data manipulation} … … 1072 1061 \end{itemize} 1073 1062 1074 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1063 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1075 1064 1076 1065 \subsection{Bit masks} … … 1103 1092 \begin{itemize} 1104 1093 \item Set a bit; 1105 \item Check if a bit is set; 1106 \item \code{OR} two bit masks; and 1107 \item \code{AND} two bit masks. 1094 \item Check if a bit is set; and 1095 \item \code{OR}, \code{AND} and \code{XOR} two bit masks. 1108 1096 \end{itemize} 1109 1097 The corresponding APIs are defined below. … … 1136 1124 \end{verbatim} 1137 1125 1138 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1126 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1139 1127 1140 1128 \subsection{Vector and Image Arithmetic} 1141 1129 1142 1130 We will need to be able to perform various operations on vectors and 1143 matrices, e.g.\ dividing one image by another, subtracting a vector1131 images, e.g.\ dividing one image by another, subtracting a vector 1144 1132 from an image, etc. Both binary operations and unary operations are 1145 1133 required. … … 1173 1161 1174 1162 It is desirable to use the same functions for both vectors and 1175 matrices, so inputs are \code{void*}; this necessitates that vectors1176 and matrices each have a type element at a pre-determined and constant1163 images, so inputs are \code{void*}; this necessitates that vectors 1164 and images each have a type element at a pre-determined and constant 1177 1165 location in the \code{struct}. It is further desirable to allow 1178 1166 scalar values to be used within these functions, which requires the … … 1216 1204 Note that the \code{psUnaryOp} is performed on \code{B} in-place. 1217 1205 1218 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1206 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1219 1207 1220 1208 \subsection{Sorting} … … 1243 1231 \end{verbatim} 1244 1232 1245 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1246 1247 \subsection{Statistics} 1233 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1234 1235 \subsection{Statistics Functions} 1236 1237 \subsubsection{Array Statistics} 1248 1238 1249 1239 We require a very general statistics function, which, given an array … … 1284 1274 \end{verbatim} 1285 1275 1276 The \code{psStats} structure is defined with entries for each of the 1277 desired statistical quantities: 1278 1279 \begin{verbatim} 1280 /** generic statistics structure */ 1281 typedef struct { 1282 double sampleMean; //<! formal mean of sample 1283 double sampleMedian; //<! formal median of sample 1284 double sampleMode; //!< Formal mode of sample 1285 double sampleStdev; //<! standard deviation of sample 1286 double sampleUQ; //<! upper quartile of sample 1287 double sampleLQ; //<! lower quartile of sample 1288 double robustMean; //<! robust mean of array 1289 double robustMeanError; //<! error on robust mean 1290 int robustMeanNvalues; //<! number of measurements used for robust mean 1291 double robustMedian; //<! robust median of array 1292 double robustMedianError; //<! error on robust median 1293 int robustMedianNvalues; //<! number of measurements used for robust median 1294 double robustMode; //!< Robust mode of array 1295 double robustModeErr; //!< Error in robust mode 1296 int robustModeNvalues; //!< Number of measurements used for robust mode 1297 double robustStdev; //<! robust standard deviation of array 1298 double robustUQ; //<! robust upper quartile 1299 double robustLQ; //<! robust lower quartile 1300 double clippedMean; //<! Nsigma clipped mean 1301 double clippedMeanError; //<! error on clipped mean 1302 int clippedMeanNvalues; //<! number of data points used for clipped mean 1303 double clippedStdev; //!< standard deviation after clipping 1304 double clipSigma; //<! Nsigma used for clipping; user input 1305 int clipIter; //!< Number of clipping iterations; user input 1306 double min; //<! minimum data value in array 1307 double max; //<! maximum data value in array 1308 int nValues; //<! number of data values in array 1309 psStatsOptions options; //<! bitmask of calculated values 1310 } psStats; 1311 \end{verbatim} 1312 1313 \subsubsection{Histograms} 1286 1314 1287 1315 We also require to be able to generate histograms, given a list of … … 1331 1359 \end{verbatim} 1332 1360 1333 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1361 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1334 1362 1335 1363 \subsection{Matrix operations and linear algebra} … … 1419 1447 and column operations. 1420 1448 1421 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1449 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1422 1450 1423 1451 \subsection{(Fast) Fourier Transforms} … … 1452 1480 \end{verbatim} 1453 1481 1454 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1482 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1455 1483 1456 1484 \subsection{General functions} … … 1535 1563 1536 1564 \begin{verbatim} 1537 /** Evaluate 3D polynomial (double precision) */1565 /** Evaluate 2D polynomial (double precision) */ 1538 1566 double 1539 psEvalDPolynomial 3D(double x, //!< Value x at which to evaluate1567 psEvalDPolynomial2D(double x, //!< Value x at which to evaluate 1540 1568 double y, //!< Value y at which to evaluate 1541 double z, //!< Value z at which to evaluate 1542 const psDPolynomial3D *restrict myPoly //!< Coefficients for the polynomial 1569 const psDPolynomial2D *restrict myPoly //!< Coefficients for the polynomial 1543 1570 ); 1544 1571 \end{verbatim} 1545 1572 1546 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1573 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1547 1574 1548 1575 \subsection{Minimisation and fitting routines} … … 1551 1578 specifically minimise $\chi^2$ given a list of data with associated 1552 1579 errors, and a function that will analytically determine the polynomial 1553 that goes through all the specified points. The APIs are:1580 fit by least-squares. The APIs are: 1554 1581 1555 1582 \begin{verbatim} … … 1583 1610 \end{verbatim} 1584 1611 1585 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1586 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1587 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %1612 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1613 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1614 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1588 1615 1589 1616 \section{Astronomy-Specific Functions} … … 1607 1634 These are each dealt with below. 1608 1635 1609 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1610 1636 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1611 1637 \subsection{Image handling} 1612 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%1613 1614 \subsection{Basic Images}1615 1638 1616 1639 The most important data product produced by the telescope is an image. … … 1680 1703 \end{verbatim} 1681 1704 1682 Free the memory associated with a specific image. \note{does this 1683 free the input structure or just the allocated elements?} Free the 1684 children of the image if they exist. 1705 Free the memory associated with a specific image, including the pixel 1706 data. Free the children of the image if they exist. 1685 1707 \begin{verbatim} 1686 1708 void 1687 psImageFree (psImage *image) ///< free this image 1688 \end{verbatim} 1689 1690 Free the memory associated with the children of a specific image. 1709 psImageFree(psImage *restrict image ///< free this image 1710 ); 1711 \end{verbatim} 1712 1713 Free only the pixels for a specified image. 1714 \begin{verbatim} 1715 psImage * 1716 psImageFreePixels(psImage *restrict image //!< Image whose pixels are to be freed 1717 ); 1718 \end{verbatim} 1719 1720 Free the memory associated with the children of a specific image, 1721 returning the number of children freed. 1691 1722 \begin{verbatim} 1692 1723 int 1693 psImageFreeChildren (psImage *image) ///< free children of this image 1724 psImageFreeChildren(const psImage *image ///< free children of this image 1725 ); 1694 1726 \end{verbatim} 1695 1727 … … 1726 1758 width \code{dw} about this vector. The input region is collapsed in 1727 1759 the perpendicular direction, and each element of the output vector 1728 represents apixel-sized boxes, where the value is derived from the1760 represents pixel-sized boxes, where the value is derived from the 1729 1761 statistics of the pixels interpolated along the perpendicular 1730 1762 direction. The statistic used to derive the output vector value is … … 1768 1800 1769 1801 Rebin image to new scale. A new image is constructed in which the 1770 dimensions are reduced by a factor of \code{scale} . The output image1771 represents a one-to-one mapping of the pixels in the input image, 1772 except for edge effects. Each pixel in the output image is derived 1773 from the statistics of the corresponding input image pixels based on 1774 the statistics specified by \code{psStats stats}. 1775 \tbd{interpolation?}1802 dimensions are reduced by a factor of \code{scale} $\le 1$ (it is an 1803 error for \code{scale} $> 1$). The output image represents a 1804 one-to-one mapping of the pixels in the input image, except for edge 1805 effects. Each pixel in the output image is derived from the 1806 statistics of the corresponding input image pixels based on the 1807 statistics specified by \code{psStats stats}. \tbd{interpolation?} 1776 1808 \begin{verbatim} 1777 1809 psImage * … … 1786 1818 pixels should be set of \tbd{value}. The center of rotation is always 1787 1819 the center pixel of the image. The rotation is specified in the sense 1788 that a positive value is a clock-wise rotation.1820 that a positive angle is an anti-clockwise rotation. 1789 1821 \begin{verbatim} 1790 1822 psImage * … … 1795 1827 Shift image by an arbitrary number of pixels (\code{dx,dy}) in either 1796 1828 direction. If the shift values are fractional, the output pixel 1797 values shoul interpolate between the input pixel values. The output1829 values should interpolate between the input pixel values. The output 1798 1830 image has the same dimensions as the input image. Pixels which fall 1799 1831 off the edge of the output image are loast. Newly exposed pixels are … … 1853 1885 1854 1886 Read an image or subimage from a named file. This function is a 1855 wrapper to the FITS library function. The input parameters allow or a 1856 subimage to be read. The starting pixel of the region is specified by 1857 \code{x,y}, while the dimensions of the requested region are specified 1858 by \code{nx,ny}. A value of -1 for these two parameters specifies the 1859 full array of the requested image. If the native image is a cube, the 1860 value of z specifies the requested slice of the image. The data is 1861 read from the extension specified by extname (matching the EXTNAME 1862 keyword) or by the extnum value (with -1 representing the PHU, 0 the 1863 first extension, etc). This function must return an error if any of 1864 the specified parameters are out of range for the data in the image 1865 file, if the specified image file does not exist. \tbd{what do we do 1866 with a 0D or 1D image?} 1887 wrapper to the FITS library function. The input parameters allow a 1888 full image or a subimage to be read. The starting pixel of the region 1889 is specified by \code{x,y}, while the dimensions of the requested 1890 region are specified by \code{nx,ny}. A value of -1 for these two 1891 parameters specifies the full array of the requested image. If the 1892 native image is a cube, the value of z specifies the requested slice 1893 of the image. The data is read from the extension specified by 1894 extname (matching the EXTNAME keyword) or by the extnum value (with -1 1895 representing the PHU, 0 the first extension, etc). This function must 1896 generate an error and return \code{NULL} if any of the specified 1897 parameters are out of range for the data in the image file, if the 1898 specified image file does not exist, or the image on disk is zero- or 1899 one-dimensional. 1867 1900 \begin{verbatim} 1868 1901 psImage * … … 1893 1926 \end{verbatim} 1894 1927 1928 \TBD{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} 1929 1895 1930 Write an image section to named file, which may exist. This 1896 1931 operatation may write a portion of an image over the existing bytes of 1897 1932 an existing image. If the file does not exist, it should be created. 1898 If the specified exten tion does not exist, it should be created. If1933 If the specified extension does not exist, it should be created. If 1899 1934 an extension is specified and no PHU exists, a basic PHU should be 1900 1935 created. … … 1905 1940 int y, ///< starting y coord of region 1906 1941 int z, ///< plane of interest 1907 char *extname, ///< MEF extension name ("PHU" for primary header) 1942 char *extname, ///< MEF extension name ("PHU" for primary header) 1908 1943 char *filename) ///< file to write data to 1909 1944 \end{verbatim} … … 1920 1955 \end{verbatim} 1921 1956 1957 \TBD{The use of \code{FILE*} to carry around the file descriptor is to be reviewed.} 1958 1922 1959 Read header data from a FITS image file into a \code{psMetaData} 1923 1960 structure. If the named extension does not exist, the function should … … 1941 1978 \end{verbatim} 1942 1979 1943 Perform a 2-D FFT on the specified image. 1980 Perform a 2-D FFT on the specified image. The returned image is of 1981 type \code{psComplex}. 1944 1982 \begin{verbatim} 1945 1983 psImage * … … 1960 1998 \end{verbatim} 1961 1999 1962 Clip NaN image pixels to given value. Pixels with NaN or Inf values 1963 are set to the specified value. 2000 Clip NaN image pixels to given value. Pixels with NaN, +Inf or -Inf 2001 values are set to the specified value. Returns the number of clipped 2002 pixels. 1964 2003 \begin{verbatim} 1965 2004 int … … 2045 2084 Plane is a four-dimensional polynomial, in order to account for any 2046 2085 possible dependencies in the astrometry on the stellar magnitude and 2047 colour; the latter serves as a check for charge transfer2086 colour; the former serves as a check for charge transfer 2048 2087 inefficiencies, while the latter will correct chromatic refraction, 2049 2088 both through the atmosphere and the corrector lenses. … … 2058 2097 2059 2098 A frame is the result of a single read of a cell (or a portion 2060 thereof). It contains a pointer to the data pixels with a2061 separate pointer to the overscan pixels, and additional pointers to 2062 the objects found in the frame, and the frame metadata. It also 2063 contains the offset from the lower-left corner of the chip, in the 2064 case that the CCD waswindowed.2099 thereof). It contains a pointer to the pixel data, a separate pointer 2100 to the overscan pixels, and additional pointers to the objects found 2101 in the frame, and the frame metadata. It also contains the offset 2102 from the lower-left corner of the chip, in the case that the CCD was 2103 windowed. 2065 2104 2066 2105 \begin{verbatim} … … 2619 2658 on both). 2620 2659 2621 We are using the standard \PS{} doubly-linked list types \code{psDlist} and \code{psHash} 2622 (see \href{file:utils#psDlist}{utils.pdf:psDlist} and \href{file:utils#psHash}{utils.pdf:psHash} for details). 2623 For example: 2660 We are using the standard \PS{} doubly-linked list types 2661 \code{psDlist} and \code{psHash}. For example: 2624 2662 \begin{verbatim} 2625 2663 for (int i = 0; i < 10; i += 5) { … … 2655 2693 2656 2694 The \code{psMetaDataItem} struct includes a name. This name should be of 2657 the form \code{name1.name2.name3 $\cdots$}, e.g.\hfil\break2695 the form \code{name1.name2.name3}$\cdots$, e.g.\hfil\break 2658 2696 \null\qquad\qquad\code{IPP.phase1.ota12.biassec}. 2659 2697 … … 2732 2770 /** A point in 2-D space, with errors. 2733 2771 */ 2734 typedef struct { 2735 union { 2736 double x; //!< x position 2737 double r; //!< x position 2738 } x; 2739 union { 2740 double xErr; //!< Error in x position 2741 double rErr; //!< Error in x position 2742 } dx; 2743 union { 2744 double y; //!< y position 2745 double d; //!< y position 2746 } y; 2747 union { 2748 double yErr; //!< Error in y position 2749 double dErr; //!< Error in y position 2750 } dy; 2772 typedef union { 2773 struct { 2774 double x; //!< x position 2775 double y; //!< y position 2776 double xErr; //!< Error in x position 2777 double yErr; //!< Error in y position 2778 } xy; 2779 struct { 2780 double r; //!< RA 2781 double d; //!< Dec 2782 double rErr; //!< Error in RA 2783 double dErr; //!< Error in Dec 2784 } rd; 2751 2785 } psCoord; 2752 2786 \end{verbatim} … … 2811 2845 psGetOffset(const psCoord *restrict position1, //!< Position 1 2812 2846 const psCoord *restrict position2, //!< Position 2 2813 c har *system)2814 ;2847 const char *type //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc 2848 ); 2815 2849 \end{verbatim} 2816 2850 … … 2820 2854 psApplyOffset(const psCoord *restrict position, //!< Position 2821 2855 const psCoord *restrict offset, //!< Offset 2822 c har *system)2823 ;2856 const char *type //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc 2857 ); 2824 2858 \end{verbatim} 2825 2859 … … 2904 2938 2905 2939 2906 Photometric observations are performed in a photometric system, and 2907 are must be related to other photometric systems. We require a data 2908 structure which defines a photometric system, as well as a structure 2909 to define the transformation between photometric systems. 2940 Photometric observations are performed in an instrumental photometric 2941 system, and must be related to other photometric systems. We 2942 require a data structure which defines a photometric system, as well 2943 as a structure to define the transformation between photometric 2944 systems. 2910 2945 2911 2946 The photometric system is defined by the psPhotSystem structure. … … 2920 2955 \begin{verbatim} 2921 2956 typedef struct { 2922 int ID; 2923 char *name; 2924 char *camera; 2925 char *filter; 2926 char *detector; 2957 int ID; //!< ID number for this photometric system 2958 char *name; //!< Name of photometric system 2959 char *camera; //!< Camera for photometric system 2960 char *filter; //!< Filter used for photometric system 2961 char *detector; //!< Detector used for photometric system 2927 2962 } psPhotSystem; 2928 2963 \end{verbatim} … … 2932 2967 \begin{verbatim} 2933 2968 typedef struct { 2934 psPhotSystem src; 2935 psPhotSystem dst; 2936 psPhotSystem pP, pM; ///< Colour reference2937 psPhotSystem sP, sM; ///< Colour reference2938 float pA, sA; ///<2939 psPolynomial3D transform; 2969 psPhotSystem src; //!< Source photometric system 2970 psPhotSystem dst; //!< Destination photometric system 2971 psPhotSystem pP, pM; ///< Primary colour reference 2972 psPhotSystem sP, sM; ///< Secondary colour reference 2973 float pA, sA; ///< Colour offset for primary and secondary references 2974 psPolynomial3D transform; //!< Transformation from source to destination 2940 2975 } psPhotTransform; 2941 2976 \end{verbatim} … … 2944 2979 airmass of the observation and on the colors of the object of 2945 2980 interest. For a specific observation, such a transformations can be 2946 defined as a polynomial function of the color the star and the airmass2947 of the observations. If sufficient data exists, the transformation 2948 between the photometric systems may include more than one color, 2949 constraining the curvature of the stellar spectral energy2981 defined as a polynomial function of the color of the star and the 2982 airmass of the observations. If sufficient data exists, the 2983 transformation between the photometric systems may include more than 2984 one color, constraining the curvature of the stellar spectral energy 2950 2985 distributions. This latter term may be significant for stars which 2951 2986 are highly reddened, for example. Derived photometric quantities may … … 2963 2998 $M_{\rm pM}$, $M_{\rm sP}$, $M_{\rm sM}$, observed at an airmass of 2964 2999 $z$, the magnitude of the star in the target system $M_{\rm dst}$ is 2965 given by: 2966 $M_{\rm dst} = M_{\rm src} + transform(z, M_{\rm pP} - M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$ 3000 given by: $M_{\rm dst} = M_{\rm src} + transform(z, M_{\rm pP} - 3001 M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$. 2967 3002 2968 3003 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Note:
See TracChangeset
for help on using the changeset viewer.
