Home

HPIC User`s Manual

1. int hpic conv int nest hpic int xmap int hpic conv int ring hpic int map 2 6 3 Resolution The following functions convert a map to a new NSIDE resolution The functions return a pointer to a newly allocated map The old map is not freed The new map has the same name units and ordering but has an NSIDE equal to the newnside 19 HPIC CHAPTER 2 C REFERENCE parameter If the original map is being degraded then each pixel of the new map will be an average of the high resolution pixel values that lie within it Pixel values equal to HPIC_NULL or HPIC_INT_NULL will not be included in the average If the original map is being prograded then each pixel of the new map will have the same value as the low resolution pixel that it lies within hpic hpic conv xgrade hpic map size t newnside hpic float hpic conv float xgrade hpic float map size t newnside hpic int hpic conv int xgrade hpic int map size t newnside 2 7 Map Math It is often useful to perform simple mathematical operations on a map The fol lowing tools abstract this process as much as possible to allow for a more intuitive useage 2 7 1 Scaling and Offsets The scale functions listed below will multiply every pixel in the map by the value specified in the val parameter In the case of the integer map the resulting product is truncated The offset functions add the val parameter to all pixels in the map Note that NULL pixels are no
2. To free a map structure after it has been allocated simply use the appropriate free command below int hpic free hpic map int hpic float free hpic float map int hpic int free hpic int map 2 4 3 Parameter Access The following functions can be used to set and retrieve various parameter values stored in a map structure To access the values of the unchangeable map param eters NSIDE number of pixels ordering coordinate system that were set when the map was allocated use the appropriate version double float or int of the following functions size t hpic nside get hpic xmap size t hpic float nside get hpic float map size t hpic int nside get hpic int xmap 13 HPIC CHAPTER 2 C REFERENCE size t hpic_npix_get hpic map size t hpic float npix get hpic float xmap size t hpic int npix get hpic int xmap int hpic order get hpic map int hpic float order get hpic float map int hpic int order get hpic int xmap int hpic coord get hpic map int hpic float coord get hpic float map int hpic int coord get hpic int xmap It is not absolutely necessary to give each map a name but if a name exists it will become the column title if the map is printed to a FITS file To set or get the map name use the following functions Note that the get functions return a pointer to the char array that exists inside the map structure This returned pointer is suitable for use i
3. fmap map get pix fmap map setall val Sfmapcopy fmap gt map_copy Sfmap gt map_scale val Sfmap gt map_offset S val Sdmap Sfmap gt to_double Simap fmap gt to_int fmap nestcopy Sfmap gt ringcopy Sfmap gt nest Sfmap gt ring Sfmapgrade fmap gt xgrade newnside Sfmap gt printf int map Simap new HPIC hpic_int nside order coord Smem Simap gt DESTROY Simap gt map_mem_set men Smem Simap gt map_mem_get Simap gt map_name_set Sname Simap gt map_units_set Sunits name imap map name get Sunits imap map units get Snside imap map nside get Snpix Simap gt map_npix_get Sorder imap map order get Scoord imap map coord get X imap map set pix val val S imap map get S pix ap map setall val imapcopy Simap gt map_copy imap gt map_scale val zac eel ap Simap gt to_double map Simap gt to_float imap gt nestcopy p d En NS 3 QU Ur Ur Ur X Y Y Ur H B 3 38 HPIC CHAPTER 3 PERL REFERENCE imap gt ringcopy imap gt nest imap gt ring imapgrade imap gt xgrade newnside imap printf Xr ur ur ou ur 3 3 Vectors The vector structures in Perl have also been wrapped into classes The listing below shows the
4. 2 11 CMB Specific Functions The field of Cosmic Microwave Background CMB research has obviously been one of the major application areas of the healpix algorithms I have attempted to separate functions that are CMB specific from those that are generally applicable to pixelized functions on the sphere 2 11 1 Projection As a special case of vector field projection you can use the hpic cmb proj QU function to project the Q and U stokes parameter components of a polarization field onto a projection structure Since this quantity is a headless vector it is irrelevant which end is considered the head or tail int hpic cmb proj QU hpic proj proj hpic Qmap hpic Umap size t pnside double maxmag hpic vec index xheadx hpic vec index heady hpic vec index tailx 31 HPIC CHAPTER 2 C REFERENCE male wee mindez secret ily 8 2 11 2 Specialized FITS I O Since there are already certain common FITS formats in use in the CMB commu nity it is convenient to have some reading and writing functions that deal specif ically with these formats instead of always having to use the general functions NOTE When writing FITS files the column names and units in the output file are set from the names and units of the input maps To write a single full sky map use the hpic cmb write full function All the parameters have the usual definitions see the general FITS section for more info To read a file such as this use the hp
5. Each key line consists of a comment character a word specifying the key type SKEY FKEY or IKEY the key name the key value and the rest of the line is treated as the key comment For example to generate a vector fits file with one column I might use a text file like this 3 1 2049 SKEY CHANNEL B145W1 Simulated Beam for B145W1 FKEY AZFWHM 9 75 Beam azimuth FWHM in arcmin FKEY ELFWHM 9 93 Beam elevation FWHM in arcmin 1 000000 0 999997 0 999991 0 999982 0 999970 0 999955 To build a cut sphere map file I might use a text file like this 6 4 86098 SKEY CHANNE B145w1 Channel of Observation SKEY RELEASE 1 0 Data Release 47 HPIC CHAPTER 4 COMMAND LINE TOOLS SKEY TARGET CMB SKEY OBJECT IKEY SHOT 1 IKEY OBS NPIX 2348362 2348363 2348364 2348365 2348366 2348367 2348368 jad kek d pudo k jmd 000000e 00 000000e 00 000000e 00 000000e 00 000000e 00 000000e 00 000000e 00 86098 78 72 72 72 72 12 60 Observed Target PARTIAL Sky coverage represented by data Shot of this target Number of pixels observed 9 715862e 04 7 337384e 04 9 687704e 04 9 399473 e 04 9 749437 e 04 9 362744e 04 1 017587e 03 4 2 Simple Math Tools These four programs take the sum difference product or quotient of two maps The first file is backed up and overwritten with the result of the operation die sum OR
6. size t xelem size t yelem int hpic proj setall hpic proj proj double val ES SNS Mokle proj Leur 3rpexesbeEdE I bd iO Moire proj HDD 22 HPIC CHAPTER 2 C REFERENCE sisas wote proj inio priat norte oroj 0603 8 2 8 4 Projecting Maps and Vectors To project the data of a single map onto a projection structure simply call the hpic_proj_map function The rest of the projection functions do not actually write any data to the array contained in the projection structure Instead they use the projection structure to obtain the type size and range of the projection These functions return vectors of pixel indices These index vectors must be allocated when you pass them to the functions but their size is not important they will be resized by the function In the case of hpic_proj_points a set of ordered pairs of theta phi values is projected into a set of ordered pairs of x and y pixel coordinates The x and y vectors will contain the projection array coordinates of all the points lying within the range of the projection Note that the length of the x and y vectors will be different than the length of the input vectors unless all the theta phi values lie inside the range of the projection The hpic_proj_pixels function takes a list of map pixel indices at a certain NSIDE and ordering and returns a list of projection array pixel coordinates that fall within the specified map pixels The hpic_proj_vec
7. This is the new file that will be created mapnum lt map number to process gt The zero based number of the input signal map upper lt upper threshold gt All pixels with a value higher than this number will be cut set to HPIC_NULL lower lt lower threshold gt All pixels with a value lower than this number will ns cue SEE o BEIC NULL outval optionally set all in range pixels to this value If specified all output pixels lying between upper and lower will be set to this value 45 HPIC CHAPTER 4 COMMAND LINE TOOLS The hpic outline program reads in a single map from a FITS file and finds all non null pixels that border with a side or vertex all null valued pixels These pixels are written to a new file and optionally set to a new value If the input contains no null valued pixels then the output map will be empty hpic_outline in lt input FITS file gt ls e Ems rile to zeae sin SOU Solowe IES Tiles This is the new file that will be created mapnum lt map number to process gt The zero based number of the input signal map outval optionally set all border pixels to this value If specified all output pixels will be set to this value The hpic_2ascii program reads in any supported FITS file map or vector and dumps the contents to stdout dile 2asoll lt siajoyblie PIES ales The hpic_2fits program reads a specially formatted te
8. is an implementation of the healpix algorithms originally developed by Gorski Wandelt Hivon Banday and others 1 2 3 4 5 I would like to thank and acknowledge the original HEALPrx authors for their hard work de veloping the theoretical framework upon which this project is based Throughout this document when I mention healpix I am refering to the algorithms them selves When I refer to a specific implementation of these algorithms I will write them as HPIC or HEALPIx In mid September of 2005 version 2 00 of HEALPrx was released Unlike previous releases this one was licensed under the GPL For the first time HPIC and HEALPIx were legally allowed to share code Hopefully this development will lead to a fruitful and peaceful coexistence between the two projects 1 1 Overview The HPIC package contains a number of different components an object oriented C library a Perl interface to the C library and command line utilities for manipulating and operating on FITS files So why create another software library when one already exists Let me first say that I believe choice is a good thing Secondly I wanted to have an object oriented set of tools which I could use in C C and Perl programs An original consideration was also that the HEALPrx license was incompatible with the GPL This has changed with the release of version 2 00 of HEALPIX I have attempted to make the HPIC library as intuitive as possible Although function name
9. nside char ordering int compat read healpix map char infile long nside char coordsys char ordering float map int compat write healpix map float signal long nside char filename char nest char coordsys void compat read fits cut4 char filename int x pixel float signal int xn obs float serror char channel char coordsys int nside int obs_npix char ordering char target int xshot char xunits int compat write fits cut4 int pixel float signal int n obs float serror char channel char coordsys int nside int obs npix char ordering char target int shot char xunits char filename char xcreator char xrelease 34 HPIC CHAPTER 3 PERL REFERENCE Chapter 3 Perl Reference In order to provide a Perl interface to the HPIC library I have made extensive use of SWIG Simplified Wrapper and Interface Generator to build a Perl module that wraps the C library After building and installing the module you can use it in your programs just like any other module use Hele Since Perl supports object oriented programming better than C I have incorporated many of the functions into the types they operate on This changes the calling se quence somewhat but the interface is much cleaner Aside from this change the Perl interface is so similar to the C interface that I will not go into great detail about the parameters of each function See the corresponding sect
10. of the projection ote proj moie proj elles te me Edy ny int hpic_proj_free hpic_proj proj 2 8 2 Parameter Access When a projection is allocated it defaults to a cartesian projection You can set or get the type of the projection with the functions below Valid values of the type parameter are HPIC_PROJ_CAR and HPIC_PROJ_SIN You can set or get the maximum and minimum range values of the projection by using the range functions below See the earlier diagram for a description of what these range values mean Note that setting the type or range of the projection also clears all of the projection data int hpic_proj_type_get hpic_proj x proj int hpic proj type set hpic proj proj int type int hpic proj range get hpic proj proj double mintheta double maxtheta double minphi double maxphi int hpic proj range set hpic proj proj double mintheta double maxtheta double minphi double maxphi 2 8 3 Data Access To set or get a specific value from the projection array use the set and get functions below The xelem and yelem parameters specify the array coordinates of the value you are changing or retrieving You can also set all array elements with the setall command To print the size type and range values of the projection to a file or stdout you can use the print functions below int hpic proj set hpic proj proj size t xelem size t yelem double val double hpic proj get hpic proj proj
11. of writing a FITS file you easily add keywords to the structure before calling the writing routine and all the keywords in the structure will be written to the FITS file To allocate free and clear remove all keys from a keys structure use the following functions hpic_keys hpic_keys_alloc int hpic_keys_free hpic_keys keys int hpic_keys_clear hpic_keys keys To add or delete keys from an hpic_keys structure use the functions below The keyname parameter is a string containing the name of the key The keyval param eter is the value of the key Note that you must use the correct function depending on the type of key you are adding string integer or float The string parameter keycom is the comment for the key int hpic_keys_sadd hpic_keys x keys char keyname char keyval char keycom int hpic_keys_iadd hpic_keys keys char xkeyname int keyval char keycom int hpic keys fadd hpic keys x keys char keyname float keyval char keycom int hpic keys del hpic keys keys char keyname 26 HPIC CHAPTER 2 C REFERENCE To retrieve a key value from the structure you can use the key name and one of the find routines below The value of the key and the comment string are returned If the find routine is successful the return value of the function is zero Otherwise the function returns a value of 1 Obviously for the integer and floating point functions the keyval parameter should be the address of an e
12. only needs to deal with a few pixel operations etc If you are operating on many pixels then hopefully you will find the higher level routines easier to use HPIC CHAPTER 2 C REFERENCE 2 3 1 General Tools Here are a few very simple functions They are so simple that I won t waste much time on them The following functions return 1 if their argument is null and 0 if itis non null For the double and float versions the argument is considered null if it lies within HPIC_EPSILON of HPIC_NULL For the integer version the argument is considered null if it is equal to HPIC_INT_NULL int hpic_is_dnull double val int hpic_is_fnull float val int hpic is inull int val It is sometimes useful to dynamically allocate an array of strings These functions allocate and free an array of strings that each have length HPIC_STRNL ehari hpic strarr alloc size t nstring int hpic strarr free char xarray size t nstring 2 3 2 Pixel Tools These functions handle basic pixel manipulation Roughly speaking this includes converting between RING and NESTED pixel numbers converting between angu lar coordinates and pixel number converting between rectangular coordinates and pixel number and degrading a pixel number to a lower NSIDE value The first function below returns one if the value of nside is invalid The other two functions simply convert between an NSIDE value and the total number of pixels in the map N PI
13. proj range set mintheta Smaxtheta minphi maxphi Sproj gt proj_set xelem yelem val Sval Sproj gt proj_get S xelem yelem proj proj setall val proj printf mote pog qwosEs Speoj Sumets Spa Sx Syw s mate 903 qubels Speoj Smsice Soles Suxels Se Sw ote qox mejo mapik mate 9 07 swexexabeudbel Sm eoj Sunesracoma Sialcone pieder Smaxmag Sheadx heady tailx Staily 3 6 Transforms and Filtering Since the C functions are not implemented yet the Perl wrappers certainly don t work 37 FITS VO The steps for reading and writing FITS files in Perl are analogous to those in C You must still allocate space for the maps vectors the map vector array and the optional keys See the test pl file for an example of how to put all these pieces together array of float maps Smaps new RPIC 22 apie ilcexse gn Smaps gt DESTROY Smaps gt array_set elem map Smap maps gt array_get S elem 41 HPIC CHAPTER 3 PERL REFERENCE array of float vectors Swees me PICs mile vee EE SETE gmn Svecs gt DESTROY Svecs gt array_set elem vec Svec vecs gt array_get Selem FITS keys Skeys new HPIC hpic_keys Skeys gt DESTROY Skeys gt keys_clear Skeys gt keys_sadd keyname keyval keycom Skeys gt keys_iadd keyname keyval keycom Skeys gt keys_fadd keyname keyval key
14. returned The new map has exactly the same name units ordering etc as the old map When converting from a floating point type to an int map the map data is truncated rounded down 18 HPIC CHAPTER 2 C REFERENCE hpic_float hpic_double2float hpic map hpic_int hpic_double2int hpic map hpicx hpic_float2double hpic_float xmap Woie ines moie i lone iia pole loar smaa hpic hpic int2double hpic int xmap hpic float hpic int2float hpic int xmap 2 6 2 Ordering The fastest way to convert the ordering of a map is to make a temporary map that has the new ordering and then convert all the pixels Unfortunately this requires more memory The following functions do an out of place conversion that makes use of a temporary copy of the map int hpic conv nestcopy hpic xmap int hpic conv ringcopy hpic map int hpic conv float nestcopy hpic float map int hpic conv float ringcopy hpic float map int hpic conv int nestcopy hpic int map int hpic conv int ringcopy hpic int map To save memory at the price of speed it is also possible to do an in place con version I am still working on the most efficient way of implementing this As of right now these functions perform an out of place conversion This will be fixed soon int hpic conv nest hpic map int hpic conv ring hpic xmap int hpic conv float nest hpic float map int hpic conv float ring hpic float map
15. syntax of their use double vector Sewee mew KIPIC 2193c vec Sin dvec gt DESTROY n Sdvec gt vec_n_get Sdvec gt vec_set Selem val Sval dvec gt vec_get Selem dvec vec setall val Sdveccopy dvec gt vec_copy Sdvec gt vec_resize Snewn Sdvec gt vec_append S val float vector Sfvec new HPIC hpic_vec_float n Sfvec gt DESTROY n Sfvec gt vec_n_get Sfvec gt vec_set Selem val Sval fvec vec get S elem Sfvec gt vec_setall S val Sfveccopy fvec gt vec_copy Sfvec gt vec_resize Snewn S fvec vec append val int vector sec new PIC gt gt hopie vee inton ivec gt DESTROY pivec vec m Cer ivec gt vec_set elem val val ivec gt vec_get elem ivec gt vec_setall val iveccopy Sivec gt vec_copy ivec vec resize newn ivec gt vec_append val e cope pa Ups Ups Ups Cup Un Un GUps StS 39 HPIC CHAPTER 3 PERL REFERENCE index size_t vector Sie Ce new RIO eM vee mece Sa Sxvec gt DESTROY n xvec vec n get xvec vec set elem val Sval xvec gt vec_get Selem xvec vec setall val xveccopy xvec gt vec_copy xvec vec resize newn xvec vec append val 3 4 Math and Miscellany These functions are grouped together because they are basi
16. the values of individual pixels you should use the following func tions The pix parameter is the pixel number in the ordering of the map which you wish to set or get To set a pixel to a NULL value simply set it to ei ther HPIC NULL or HPIC INT NULL depending on whether the map is a floating point or integer type int hpic set hpic map size t pix double val int hpic float set hpic float map size t pix float val int hpic int set hpic int map size t pix int val double hpic get hpic map size t pix float hpic float get hpic float map size t pix int hpic int get hpic int map size t pix To set all of the map elements to a certain value use the following functions Cau tion if your map is set to type HPIC TREE and you set all pixels to a non NULL value then memory for the ENTIRE tree will be allocated This will use many times more memory than a standard C vector If your map is set to type HPIC AUTO then it will be converted to a standard C vector on the fly as soon as it is more beneficial from a memory perspective int hpic setall hpic map double val int hpic float setall hpic float xmap float val int hpic int setall hpic int xmap int val 2 4 4 Basic Operations There are several simple operations that can be performed on map structures To create a copy of a map use the copy functions below These will allocate a new map structure and fill it with the contents of the original Both the orig
17. uses full sphere maps HPIC_FITS_CUT FITS map file uses cut sphere maps HPIC_FITS_BIN 0 FITS file uses a binary extension HPIC_FITS_ASCII FITS file uses an ascii extension HPIC_FITS_VEC 0 FITS file uses floating point vectors HPIC_FITS_VEC_INDX FITS file uses an index vector HPIC_NULL 1 6375e30 Floating point NULL value in a map HPIC_EPSILON 0 0001e30 Range around HPIC_NULL equal to NULL HPIC_INT_NULL 2147483646 Integer NULL value in a map 2 2 Error Handling The HPIC library contains a global pointer to an error handling function Most functions in the HPIC library will call this error handler if they encounter a problem and then return an error code The following error codes are defined Error Code Value Meaning HPIC_ERR_NONE 0 No error HPIC_ERR_ALLOC all Memory allocation error HPIC_ERR_FREE 2 Memory freeing error HPIC_ERR_NSIDE 3 Illegal NSIDE value HPIC_ERR_ORDER 4 Illegal ORDER value HPIC ERR COORD 5 Illegal COORDINATE value HPIC ERR RANGE 6 Value is out of range HPIC ERR ACCESS 7 Memory is not accessible HPIC ERR PROJ 8 Projection error HPIC ERR FITS 9 FITS error If the global error handling pointer is NULL which is the initial value then the default error handler is called This default handler prints an error message to HPIC CHAPTER 2 C REFERENCE stderr and then terminates the program with abort If you would like to use the error handling in your programs you can call the hpic_error
18. x y and z components of the point on the sphere int hpic vec2ang double xcomp double ycomp double zcomp doublex theta doublex phi int hpic ang2vec double theta double phi doublex xcomp doublex ycomp doublex zcomp The following functions convert between pixel number and 3D cartesian compo nents When converting from pixel number to rectangular coordinates the coordi nates of the pixel center are returned int hpic pix2vec ring size t nside size t pix double xcomp doublex ycomp doublex zcomp int hpic pix2vec nest size t nside size t pix double xcomp doublex ycomp doublex zcomp int hpic vec2pix ring size t nside double xcomp double ycomp double zcomp size t pix int hpic vec2pix nest size t nside double xcomp double ycomp double zcomp size t pix To degrade a pixel number at one NSIDE to a new pixel number at a smaller NSIDE use the following functions int hpic degrade nest size t oldnside size t oldpix size t newnside size t x newpix int hpic degrade ring size t oldnside size t oldpix size t newnside size t x newpix 10 HPIC CHAPTER 2 C REFERENCE 2 3 3 Projection Tools When displaying maps it is often necessary to project spherical coordinates onto a rectangular image The following functions do forward and reverse projections of points to and from a rectangular projection of size xmax by ymax The range of the projection in spherical coordinates is speci
19. C_FITS_VECc if the file contains only floating point vectors or HPIC_FITS_VEC_INDX if the file has an integer index vector The returned 29 HPIC CHAPTER 2 C REFERENCE tabtype parameter will equal HPIC_FITS_BIN or HPIC FITS ASCII If you need more information about the file use hpic_fits_vec_info int hpic_fits_vec_test char filename size t nvecs size t length int filetype int xtabtype int hpic fits vec info char filename size_t nvecs size t x length int filetype int tabtype char creator char extname char xxnames char units hpic keys x keys Note that a full sphere healpix map format FITS file is also a valid healpix vector format FITS file If you are unsure what kind of file you have first check to see if it is a map format file As with the map functions that read or write any number of data columns to a FITS file the vector FITS functions also require the user to allocate all necessary vectors ahead of time and to then pass an array of vector pointers to the reading and writing functions The hpic vec fltarr structure is used to store these pointers and functions the same way as the hpic fltarr structure ote yes sr itar r lopotie wee acdbieeweie I uA 5 veces gt int hpic vec fltarr free hpic vec fltarr array EEA 18 noe yee leeis in ger sie yes els i array ae mola vee rlrearr ser ale ves E lireueies Array size t elem hpic vec float vec mole vee loss ho
20. HPIC HPIC Pixelization In C Theodore Kisner November 11 2005 HPIC CONTENTS Contents 1 Introduction 3 Jd QOVETVIEW cs a a e a Sw 3 1 2 Current SiS 2o sooo a a we ED N 4 1 5 Puture Roadmap i be bd do RES 4 1 4 Converting Programs that Currently use CHEALPix 5 2 C Reference 6 DA Constans uer pipare kyd e eh A be ea eR ele a 6 22 ror Handli s s coe ne sa ee RAE Aw we a 7 2 3 Low Level Functions 0 o o 8 230 General lols 2 2 4 4 42 ee daa ES 9 23 Pixel TOOS o 2 46 24 5 58 oR ade Rad ba edb bs 9 2 2 9 Projection Tools 1222 sau Ga dae de dba ce ok 11 2 3 4 Location Tools o xo cs Roos 12 24 Maps ke oars xx a Ra eek Eo de e 12 241 Allocation vox 9e ie we Ap meom 12 242 Parameter Access 6 o9 o a hed os aes dea 13 2413 Data ACCESS uoo ck a ae we we a 15 244 Basic Operations osas a we a 15 213 VOOS doudnon Be Po te veux OR You te ee ee Ae 16 23d ANGGON a s ie et eR am Aw Bea e BAR AO ek eS 16 252 Data ACCESS sama aoa Go doe sw wg rac ke eam eS 17 2 5 9 Basic Operaions x3 39099 0x m y 2a bo ga ees 17 2 6 Map Conversion 624 a be t ee Ee ee a 18 ON NV PES SS ee ee EN ele do 18 262 Olden iu nouo du ede x ERR Aw ex o 19 2 0 3 Resolution usos o we ee qok dee wo ey o 19 2 4 Map Math si 24 2442 rd obe qu b 20 2 4 1 Scaling and Offsets eq e o 24 ed REL 20 HPIC CONTENTS 2 7 2 il uuo ek os he lk ah ee ek i 20 2 8 JPEGIeCUOB oor eee a we Sox vow
21. HPIC NEST The hpic loc dist function returns the an gular distance in radians between the centers of the two pixel indices The hpic neighbors function returns the pixel indices of the surrounding pixels The vector of indices is resized to the proper length The first four elements of the index vector contain the pixel numbers of neighbors that share a side with the specified pixel The remaining indices in the vector are pixels that share a vertex with the specified pixel double hpic loc dist size t nside int order size t pixl size t pix2 int hpic neighbors size t nside int ordering size t pixel hpic vec index parray 2 4 Maps The HPIC library provides map types for double float and int maps These struc tures and their associated functions provide an easy way to manipulate whole maps and perform complex operations In addition to the data map structures also store parameters associated with the map NSIDE name units ordering coordinate sys tem etc Because the underlying structure may change as new features are added you should always use the provided access functions to change and retrieve these parameters 2 4 1 Allocation These functions allocate a map of double float or int values and return a pointer to anew hpic hpic float Orhpic int structure respectively All maps are ini tialized to either HPIC NULL for double and float maps or HPIC INT NULL for 12 HPIC CHAPTER 2 C REFERENCE integer ma
22. X 12 NSIDE int hpic nsidecheck size t nside size t hpic nside2npix size t nside size t hpic npix2nside size t npix These functions convert between RING and NESTED pixel numbers For the re turn value you should obviously pass a pointer to an existing data structure int hpic nest2ring size t nside size t pnest size t pring int hpic ring2nest size t nside size t pring size t xpnest To convert between angular coordinates on the sphere and pixel number use the following functions The values of theta and phi are in radians with theta mea sured from the North pole and phi measured in a right handed sense from the prime meridian In the functions ang2pix ring and ang2pix nest the angles are first converted to a pixel number with NSIDE set to HPIC NSIDE MAX This pixel HPIC CHAPTER 2 C REFERENCE number is then degraded to the desired NSIDE This ensures that rounding errors are consistently treated for all NSIDE values int hpic pix2ang ring size t nside size t pix double theta double xphi int hpic pix2ang nest size t nside size t pix double theta double xphi int hpic ang2pix ring size t nside double theta double phi size t pix int hpic ang2pix nest size t nside double theta double phi size t pix To convert between spherical coordinates on the sphere and their 3D cartesian equivalents you can use the following functions The xcomp ycomp and zcomp variables are the
23. cally identical to their C counterparts and there is not much to say about them For completeness here is how they look in Perl but there is nothing new here map comparison Sresult hpic comp dmapl dmap2 Sresult hpic_float_comp fmapl Sfmap2 Siasullic mie time Cema Ssameyoil imapa s pixel location Scier pre loe chet Sneaice Sock Sex Somsz s Serr hpic_neighbors nside Sorder pixel Sparray math hpic_add first second mode hpic_float_add first second Smode mode inc acei rirse Sseconel Smode hpic_subtract first second Smode ate lone subtract rirse Sseconcl Smack mote ime sulou raCIE Sieiiesic Sseconcl Smode hpic_multiply first second Smode mote cloar mileiaoly Sriirsc Sseconmel Smode hpic int multiply first second mode hpic divide first second mode hpic float divide S first second mode hpic int divide first second mode 40 HPIC CHAPTER 3 PERL REFERENCE 3 5 Projection Projection of maps points etc is straightforward in Perl The projection structure has been wrapped into a class and the functions that do the the projection are basically the same as in C projection pro mem RPIC lt 2 mpile pro Has I Sproj gt DESTROY Stype proj gt proj_type_get Sproj gt proj_type_set type Serr Smintheta maxtheta Sminphi Smaxphi proj proj range get proj
24. com S keys keys del S keyname total keys keys total Serr result keyval S keycom Serr result keyval S keycom Serr result keyval S keycom Skeys gt keys_printf Skeys gt keys_sfind Skeyname keys keys ifind keyname Skeys keys ffind S keyname map FITS functions Serr result nside Sorder coord Stype Snmaps hpic_fits_map_test filename Serr result nside order coord type nmaps hpic_fits_map_info filename creator Sextname Snames Sunits Skeys hpic_fits_full_write filename creator Sextname Scomment Smaps S keys hpic_fits_cut_write filename creator Sextname Scomment pixels Shits Serrs Smaps Skeys hpic_fits_full_read filename creator extname Smaps Skeys hpic_fits_cut_read filename creator extname pixels Siulies Serre Sueps S VISUS Sfmap hpic_fits_read_one filename mapnum creator Skeys vector FITS functions Serr Sresult nvecs length filetype Stabtype hpic fits vec test S filename Serr result nvecs length filetype Stabtype glo ies yes ito srl lema Sexe SEyxiemewe 42 HPIC CHAPTER 3 PERL REFERENCE names Sunits keys hpic fits vec write filename tabtype creator Sextname Scomment vecs vecnames Svecunits Skeys hpic_fits_vecindx_write filename creator Sextname Scomment Sindx vecs Svecnames Svecun
25. ddition to these FITS files that are designed to store maps there are also various types of FITS files in use that store general vectors I have created a specification that encompasses these vector FITS files as well 1 Vectors must be stored in the first extension HDU 2 and not in the primary image 25 HPIC CHAPTER 2 C REFERENCE 2 The extension which contains the vectors may be either an ASCII table or a binary table 3 The extension may contain any number of optional keywords 4 All vectors must have the same length 5 If the vectors are stored in an ASCII table then the table may consist of one or more columns of floating point numbers where each column is a vector 6 If the vectors are stored in a binary table then the table may consist of either columns of floating point numbers or a single integer column of index values followed by columns of floating point numbers 2 10 2 Optional Keys All of the FITS file formats allow the user to specify optional keywords To make this process relatively easy the hpic_keys structure is used to hold any number of string integer and floating point keywords After allocating an hpic_keys struc ture you pass a pointer to this structure to the FITS reading or writing routines In the case of reading a FITS file the keys structure will be populated by all the non required keywords found in the file You can then access any keyword values within the structure In the case
26. elow to resize a vector The parameter newn is the new size of the vector If the new size is smaller than the current size the vector 1s truncated If the new size is larger than the current size additional elements are added to the end of the vector and set to zero Resizing a vector to size zero is NOT the same as freeing the vector int hpic vec resize hpic vec vec size t newn int hpic vec float resize hpic vec float vec size t newn int hpic vec int resize hpic vec int vec size t newn int hpic vec index resize hpic vec index vec size t newn To append a single element to a vector use the following functions The vector size is increased by one and the new element is set to the value specified by the val parameter int hpic vec append hpic vec vec double val int hpic vec float append hpic vec float vec float val int hpic vec int append hpic vec int vec int val int hpic vec index append hpic vec index vec size t val 2 6 Map Conversion There are several different sorts of conversion operations one might want to do on a map Besides converting between different types double float and int it is also desirable to convert between RING and NESTED ordering schemes and to be able to degrade and prograde a map 2 6 1 Types The following functions take a map of one type allocate a map of the new type and copy the contents from the old to the new The old map is NOT freed A pointer to the new map is
27. fied by the parameters mintheta maxtheta minphi and maxphi Note that since theta increases from North to South the maximum theta value is actually at the bottom of the projection Here is a diagram of the various projection parameters and the functions to do cartesian and sinusoidal projections are below Note that if the projection of theta phi falls outside the range of the projection then HPIC_NULL will be returned for values of x and y North ymax mintheta e theta phi x y minphi maxphi maxtheta 0 0 xmax int hpic proj car double mintheta double maxtheta double minphi double maxphi double xmax double ymax double theta double phi double x double xy int hpic proj sin double mintheta double maxtheta double minphi double maxphi double xmax double ymax double theta double phi double x double xy 11 HPIC CHAPTER 2 C REFERENCE int hpic proj rev car double mintheta double maxtheta double minphi double maxphi double xmax double ymax double x double y double theta double xphi int hpic proj rev sin double mintheta double maxtheta double minphi double maxphi double xmax double ymax double x double y double theta double xphi 2 3 4 Location Tools For some of the higher level functions it is useful to have low level tools that deal with pixel locations In these functions the order parameter should be ei ther HPIC RING or
28. field function takes two maps specifying the theta and phi components of a vector field It returns four index vectors giving the projection array coordinates of the heads and tails of the vectors The pnside parameter is the NSIDE of the vector field projection If this is different from the NSIDE of the component maps the components will be degraded to the desired NSIDE be fore projecting The maxmag parameter specifies the magnitude of a vector which should approximately span the size of one pixel at pnside resolution int hpic_proj_map hpic_proj proj hpic map int hpic_proj_points hpic_proj proj hpic_vec xtheta hpic_vec phi hpic_vec_index xx hpic_vec_index xy int hpic proj pixels hpic proj proj size t nside int order hpic vec index pixels hpic vec index xx hpic vec index xy int hpic proj vecfield hpic proj proj hpic thetacomp hpic phicomp size t pnside double maxmag hpic vec index xheadx 23 HPIC CHAPTER 2 C REFERENCE hpic vec index x heady hpic vec index tailx me WAC mece seal ily TS 2 9 Transforms and Filtering This section is the area of current active work Now that the basic pixel and map operations are implemented the next phase of development includes implementing harmonic transforms and various types of filtering Look for more info in future releases 2 10 FITS Reading and Writing The FITS standard provides an incredibly flexible framework for storing data in a p
29. function directly or use one of the provided Macros void hpic error int errcode const char file int line const char msg HPIC ERROR errcode msg HPIC ERROR VAL errcode msg value HPIC ERROR VOID errcode msg The Macros call hpic error with the given error code and automatically pass in the values ofthe current line and file __LINE__and__F ILE__ Then the Macros exit the function returning either the error code a specified value or nothing de pending on which Macro is used Since it is not generally good to have library functions aborting programs directly the user can define his or her own error han dling function You may wish for example to call hpic_error_default to print error message but then NOT abort the program until it has done some further clean up Here is an example of how you could do this custom error handler example void my handler int errcode const char file int line const char msg x handle errors sf return keep pointer to old error handler hpic_error_handler_t oldhandler oldhandler hpic_set_error_handler amp my_handler If you wish to switch back to the default error handler simply pass a NULL pointer to hpic_set_error_handler 2 3 Low Level Functions There are many low level functions which can be used independently and upon which higher level functions are based These functions may be useful if you are writing custom software that
30. functions is intended to be used as a transitional step for software projects that have been using the CHEALPIx tools and wish to start using the HPIC library These functions are wrappers around the standard HPIC functions so they may be slower than calling the native functions The goal is to allow the user to do several regular expression substitution operations on a source tree and simply recompile 2 12 1 Pixel Tools The compatibility pixel tools should have exactly the same calling sequence as those in CHEALPix The only difference is that the functions begin with the com pat_ character sequence void compat_ang2pix_nest const long nside double theta double phi long ipix void compat ang2pix ring const long nside double theta double phi long ipix void compat pix2ang nest long nside long ipix double theta double xphi void compat pix2ang ring long nside long ipix double theta double xphi void compat nest2ring long nside long ipnest long ipring void compat ring2nest long nside long ipring long ipnest long compat nside2npix const long nside 33 HPIC CHAPTER 2 C REFERENCE 2 12 2 Legacy FITS VO These functions support the simple full sky FITS format found in CHEALPIX as well as the cut sky format used in Boomerang and other experiments Again the only difference is the compat_ string prepended to the function names long compat get fits size char filename long
31. ic fits read one function discussed previously int hpic cmb write full char filename hpic float data char comment char xcreator hpic keys xkeys To read and write a set of full sky T Q and U maps use the following functions int hpic cmb write fullTQU char filename hpic float x tdata ieu En oati edaran hpic_float udata char comment char creator hpic keys keys int hpic cmb read fullTQU char filename hpic float xtdata hpic float qdata hpic float udata char creator hpic keys keys To read and write a single cut sky map use the following functions int hpic cmb write cut char filename hpic int pix hpic float xdata hpic int xhits hpic float xerrs char comment char creator hpic keys xkeys int hpic cmb read cut char filename hpic int xpix ale Flog Sal GST More dime AULES s hpic float errs char creator hpic keys xkeys To read and write a set of cut sky T Q and U maps use the following functions int hpic cmb write cutTQU char filename hpic int pix 32 HPIC CHAPTER 2 C REFERENCE pick data hpic float qdata hpic float udata hpic int xhits hpic float errs char comment char creator hpic keys xkeys int hpic cmb read cutTQU char filename hpic int pix hpic float tdata hpic float qdata Inoue lose Meara lalo me ales a hpic float errs char creator hpic_keys xkeys 2 12 Compatibility Wrappers This set of
32. inal and the new maps will need to be freed with the appropriate function after use hpic hpic copy hpic map hpic float hpic float copy hpic float xmap hpic_int hpic int copy hpic int smeo 15 HPIC CHAPTER 2 C REFERENCE It is often useful to be able to compare two maps to see if they are equal The following functions return 0 if the two maps are equal They return 1 if the map data is equal but the map parameters are different A return value of 2 indicates that neither the parameters nor the data are equal int hpic comp hpic xmapl hpic map2 int hpic float comp hpic float xmapl hpic float map2 int hpic int comp hpic int xmapl hpic int map2 For debugging and informational purposes it can be useful to display some basic information about the contents of a map The functions below print the map pa rameters and the first and last elements of the map data to either a file pointer or stdout int hpic info fprintf FILE fp hpic map int hpic float info fprintf FILE fp hpic float xmap int hpic int info fprintf FILE fp hpic int map int hpic info printf hpic map int hpic float info printf hpic float xmap Sas moie ime inro rra aos ime smaa 2 5 Vectors Although many different vector structures exist in various C libraries I wanted to have a vector type that was entirely contained within the HPIC library The following types can be used to store and manipulate a vector of doub
33. ion of the C reference for more details This chapter will focus on the differences between the Perl and C interfaces The Perl interface may change in the future as I become more knowl edgeable about converting types between C and Perl For example it would be nice to have HPIC vectors mapped directly to Perl arrays and vice versa Right now this is not a very high priority since the current scheme works even if it is a bit clumsy For examples of many of the following functions see the test pl program in the src perl subdirectory 3 1 Constants and Low Level Functions All of the constants defined in the C library are available under Perl as read only variables For example to print the value of PI you could do print HPIC_PI n 35 HPIC CHAPTER 3 PERL REFERENCE The low level functions work the same as the C version The only difference is that the function return values are returned as an array The following listing shows how these functions should be called Sresulic morc ig _clowilil Swalwue 3 Sresult hpic is fnull value Siesullic haie is inv Sa laie T Sresult hpic_nsidecheck nside Snpix hpic nside2npix nside Snside hpic_npix2nside npix Spring hpic nest2ring nside Spnest Spnest hpic ring2nest nside Spring Sert Sulaera Salma Ser Suascrta Salma SDE Siren Sex Selecta Hama hpic_ang2pix_ring nside hpic_ang2pix_nest n
34. its keys hpic_fits_vec_read filename creator extname vecs Svecnames vecunits S keys hpic fits vecindx read filename creator extname Sindx vecs vecnames vecunits Skeys 3 8 CMB Specific The Perl CMB functions are identical to the C functions They are listed below for completeness hpic cmb proj QU proj Qmap Umap Spnside Smaxmag Sineach Singachy Seems Siceulily s hpic_cmb_write_full filename data comment creator Skeys hpic_cmb_write_fullTOU filename tdata Sqdata Sudata Scomment creator keys hpic_cmb_write_cut filename pix Sdata Shits Serrs Scomment creator keys mole cno write cwuETQU Sirilemeuxe Soixz Sols Separa Sudata Shits Serrs comment Senses MESS hpic cmb read fullTQU S filename tdata Sqdata Sudata Screator Skeys male emo eea cue S illenaae pix Selmum Sales Series Screator Skeys hpic_cmb_read_cutTQU filename Spix tdata S qdata Sudata Shits Serrs creator Skeys 43 HPIC CHAPTER 4 COMMAND LINE TOOLS Chapter 4 Command Line Tools Although the HPIC library allows the user to manipulate healpix data in a variety of ways some operations are very common I have written a set of programs that perform many of the common tasks needed when working with healpix format FITS files 4 1 General Tools These functions are used to modify the data in a healpix FITS file The hpic_scale
35. le float int or size_t values I refer to the size_t vectors as index vectors since they are usually used to store a vector of indices 2 5 1 Allocation Use one of these functions to allocate a vector of the appropriate type The n parameter is the size of the vector Note that it is possible to allocate a vector of zero size useful if you plan to append data or resize later hpic_vec x hpic vec alloc size t n hpic vec float mole vec float alloc size t n ate ves ilintes lola yes me mul TL exe Xt e ia hpic_vec_indexx hpic vec index alloc size t n After you are finished with a vector you can free the memory with one of the following commands 16 HPIC CHAPTER 2 C REFERENCE int hpic vec free hpic vec vec int hpic vec float free hpic vec float vec int hpic vec int free hpic vec int vec int hpic vec index free hpic vec index vec 2 5 2 Data Access To find the size of a vector that has already been allocated use the function below that corresponds to the type of the vector size t hpic vec n get hpic vec xvec size t hpic vec float n get hpic vec float xvec size t hpic vec int n get hpic vec int x vec size t hpic vec index n get hpic vec index vec To set a vector element to a given value use one of these functions The elem parameter is the index of the element you wish to change The val parameter is the new value to assign to the element int hpic vec
36. le map Soho c me ERCE mgle Saslice Some Secserze Smen gt dmap gt DESTROY Sdmap gt map_mem_set men Smem dmap map mem get Sdmap gt map_name_set name Sdmap gt map_units_set S units name dmap map name get Sunits dmap map units get Snside dmap map nside get Snpix Sdmap gt map_npix_get Sorder dmap map order get Scoord dmap map coord get Sdm Sva Sdm Sdm Sdm Sdm Sfm Sim Sdm Sdm Sdm Sdm Sdm Sdm ap gt map_set Spix val 1 Sdmap gt map_get Spix ap map setall val apcopy dmap map copy ap map scale val ap map offset val ap dmap to float ap dmap to int ap nestcopy ap gt ringcopy ap gt nest ap ring apgrade dmap gt xgrade newnside ap printf float map fm fm fm ap new HPIC hpic float nside Sorder coord mem ap gt DESTROY ap gt map_mem_set men Smem fmap map mem get fm ap map name set name 37 CHAPTER 3 PERL REFERENCE HPIC CHAPTER 3 PERL REFERENCE Sfmap gt map_units_set S units name fmap map name get Sunits Sfmap gt map_units_get Snside fmap map nside get Snpix fmap map npix get Sorder fmap map order get Scoord fmap map coord get fmap map set S pix val Sval
37. le vece rlrarr get hoile _waec_tltares array size_t elem To read and write a standard vector FITS file containing any number of floating point columns use the following functions The tabtype parameter is the desired type of the FITS table The vecnames and vecunits parameters are arrays of strings containing the names and units of the vectors These labels will be written to or read from the FITS file You can allocate these arrays of strings using the hpic_strarr_alloc function if you wish int hpic fits vec write char filename int tabtype char creator char extname char comment hpic vec fltarr vecs char xx vecnames char xvecunits hpic keys xkeys int hpic fits vec read char filename char xcreator 30 HPIC CHAPTER 2 C REFERENCE char extname hpic vec fltarr vecs char vecnames char xxvecunits hpic keys keys To read and write vector FITS files that also contain an initial index column use the functions below Since this type of FITS file can only be constructed using a binary table there is no parameter to specify the table type int hpic fits vecindx write char filename char creator char extname char comment hpic vec int indx hpic vec fltarr vecs char vecnames char vecunits hpic keys xkeys int hpic fits vecindx read char filename char creator char extname hpic vec int xindx hpic vec fltarr vecs char vecnames char xvecunits hpic keys keys
38. loe cert OR lalo oroe OR lola eje first This this will sisse Ste WIS ENES is the first file to use A backup of file will be created and the original be overwritten by the result fmap map number to use in first file gt The zero based signal map to use second second FITS file smap map number to The zero based signal map to use from The second FITS fil the second file er use in second file gt union keep union of maps If specified keep the union of the non NULL map values Default is to keep the intersection 48 HPIC REFERENCES References 1 Krzysztof M Gorski Eric Hivon and Benjamin D Wandelt Analysis issues for large cmb data sets In Proceedings of the MPA ESO Cosmology Confer ence 1999 3 2 Krzysztof M G rski Eric Hivon Benjamin D Wandelt Frode K Hansen and Anthony J Banday The HEALPix Primer 1 10 edition March 2000 3 3 B D Wandelt E Hivon and K M Gorski Topological analysis of high resolution cmb maps In Fundamental Parameters in Cosmology Proceedings of the 23rd Rencontres de Moriond 1998 Astro ph 9803317 3 4 Frode K Hansen Benjamin D Wandelt Krzysztof M G rski Anthony J Banday and Eric Hivon HEALPix Fortran Facility Users Guide 1 10 edition March 2000 3 5 Frode K Hansen Benjamin D Wandelt Krzysztof M Gorski Eric Hivon and Anthony J Banday HEALPix Fortran90 Subroutines Over
39. n functions like strcpy etc int hpic name set hpic map const char xname int hpic float name set hpic float map const char xname int hpic int name set hpic int map const char xname charx hpic name get hpic xmap char hpic float name get hpic float xmap char hpic int name get hpic int map Another optional map parameter is the units of the map This parameter is used to set the name of the units field when printing a map to a FITS file To set and get the map units use these functions int hpic units set hpic map const char xunits int hpic float units set hpic float map const char xunits int hpic int units set hpic int map const char xunits char hpic units get hpic map char hpic float units get hpic float map char hpic int units get hpic int map The internal memory format of the data may be changed after a map is allocated If the new memory format is not compatible with the current state of the data the data will be remapped into either a standard C array or a tree structure You can use the following functions to change or return the memory structure of a map int hpic mem set hpic xmap int mem int hpic float mem set hpic float map int mem 14 HPIC CHAPTER 2 C REFERENCE int hpic_int_mem_set hpic_int map int mem int hpic mem get hpic xmap int hpic float mem get hpic float xmap int hpic int mem get hpic int map 2 4 5 Data Access To set or return
40. oordinate system is implied 7 The extension should have the string keyword INDXSCHM which can take values of IMPLICIT or EXPLICIT If this keyword is not present a value of IMPLICIT is assumed 8 The extension should contain the integer keyword GRAIN If it does not a value of zero is assumed 9 All maps in the table must have the same NSIDE ORDERING and CO ORDSYS values 10 In addition to the required keywords any number of optional keywords are allowed 11 A full sphere FITS file should have INDXSCHM IMPLICIT and GRAIN 0 12 A full sphere FITS file has one or more columns where each column is a list of floating point pixel values for every pixel in a map 13 If a full sphere FITS file has NSIDE gt 8 then the columns MAY be 1024 elements wide 14 A full sphere FITS file MIGHT contain only a contiguous portion of a map Such a file MUST contain the keywords NPIX FIRSTPIX and LASTPIX 15 A cut sphere FITS file should have INDXSCHM EXPLICIT and GRAIN gt 1 16 The first column of a cut sphere FITS file is a list of pixel indices After that follows one or more floating point columns containing map values at the indicated pixels After the data columns is an integer column of hits obser vations The last column is a floating point column of error values Note that there is no requirement on the actual name or units of the hits and error columns only their type matters In a
41. ortable file Over the years there have been many different formats used to store healpix style data The goal of this portion of the HPIC library is to provide an extensible easy to use set of tools to allow the reading and writing of all known healpix FITS formats as well as allow the development of new formats as needed 2 10 1 Format Specifications Since there is no official standard for what constitutes a healpix FITS file I have attempted to create a standard which encompasses all known existing types Ob viously compatibility with all the different codes in use is important By making some minimal assumptions I claim that this is a tractable problem Note that these rules have changed slightly over time to accomodate new formats Here is a list of requirements that a healpix map file must follow 1 Maps must be contained in the first extension HDU 2 and not in the primary image 2 The extension which contains the maps must be a binary table 3 The extension must contain the string keyword PIXTYPE and the value of this keyword must be HEALPIX 4 The extension must contain the integer keyword NSIDE and this must have a value that corresponds to the NSIDE of the maps 5 The extension must contain the string keyword ORDERING which can take values of either RING or NESTED 24 HPIC CHAPTER 2 C REFERENCE 6 The extension should have the string keyword COORDSYS If it does not a celestial equatorial c
42. program applies a scale factor and or an overall offset to one of the signal maps in a healpix FITS file The command line options are shown below hpic_scale file lt FITS file gt This is the FITS file on which to operate map lt map number to modify in file gt This is the zero base number of the signal map to be modified scale lt factor by which to multiply map gt Each pixel value in the signal map is multiplied by this number SOLESSE KOSS CO acia t9 mejo gt This number is added to each pixel value in the signal map 44 HPIC CHAPTER 4 COMMAND LINE TOOLS The hpic_convert program reads in one healpix map file converts all maps to new NSIDE and or ordering and writes the converted maps to a new file hpic_convert INN Us Tiles Unis de tae rile to reac im 02 lt table PIES iile This is the new file to be created nside lt new nside value gt This is the new NSIDE that all the maps will be converted to order ordering 0 RING 1 NEST gt This is the new ordering that all maps will be Comsweited tO The hpic thresh program reads in a single map from a FITS file and cuts all pixels that lie outside a specified range The remaining pixels are written to a new file and optionally set to a new value If no upper or lower bound is set then all pixels are kept hpic_thresh n lt anpuie PINS Tiles Wals e cine Fale ue zeae sin SOME conne WMS e
43. ps The order parameter can be either HPIC_NEST or HPIC_RING The coord parameter can take on values of HPIC COORD C HPIC COORD G HPIC COORD E or HPIC COORD O Currently the coordinate system variable is not used for anything except when writing the map to a FITS file where it is printed as a keyword The mem parameter specifies the internal memory structure in which to store the data If this is set to HPIC STND then the data will always be stored in a standard C array If setto HPIC TREE then the data will always be stored in a nested tree structure This tree storage is slower but greatly reduces the memory requirements when working with high resolution maps that have only a small coverage area Of course if you have a high coverage fraction in your map then tree storage will actually use more memory If the mem parameter is set to HPIC AUTO then the storage format will be automatically switched between the standard and tree formats to conserve memory NOTE tree based storage is not yet implemented all options currently have the behaviour of HPIC STND A newly allocated map has all of its elements set to HPIC NULL in the case of double or float maps or HET C INT NULL in the case of integer maps I hpic hpic alloc size t nside int order int coord int mem hpic float hpic float alloc size t nside int order int coord int mem hpic int hpic int alloc size t nside int order int coord int mem
44. rams The first step is to include the HPIC header file include lt hpic h gt When linking the program you will also need to link to the math and CFITSIO libraries i e Im Icfitsio Ihpic For examples of how to use the following functions see the hpictest program in the src test directory 2 1 Constants There are many constants that are defined and used throughout the HPIC library HPIC CHAPTER 2 C REFERENCE Constant Name Value Meaning HPIC_PI 3 14159265358979 The value of T HPIC_INVPI 0 318309886183791 The value of 1 7 HPIC_PISO 9 86960440108936 The value of 7 HPIC_HALFPI 1 5707963267949 The value of m 2 HPIC NSIDE MAX 8192 The maximum NSIDE value HPIC STRNL 200 The maximum string length HPIC DEBUG 0 or Whether to print debug messages HPIC RING 0 ndicates RING ordering of a map HPIC NEST ndicates NESTED ordering of a map HPIC COORD C 0 Map in celestial equatorial coordinates HPIC COORD G Map in galactic coordinates HPIC COORD E 2 Map in ecliptic coordinates HPIC_COORD_O 3 Map in other coordinates HPIC_STND 0 Map always kept in a standard C array HPIC_TREE Map always kept in a pixel tree HPIC_AUTO 2 Map switched between standard tree HPIC_VECBUF 10 Realloc buffer for vector resizing HPIC_PROJ_CAR 0 Cartesian projection HPIC_PROJ_SIN Sinusoidal projection HPIC_INTERSECT 0 Take the intersection of maps HPIC_UNION Take the union of maps HPIC_FITS_FULL 0 FITS map file
45. s are long and descriptive they are constructed in a uniform way according to what they do and what type of data they operate on I have tried to loosely model the calling format after that of the GNU Science Library GSL HPIC CHAPTER 1 INTRODUCTION 1 2 Current Status As of version 0 50 the HPIC tools are already quite useful Although there is still much functionality to implement the features that are implemented have been tested as much as possible I already make extensive use of these tools in other projects A partial list of working features include e Basic single pixel operations order conversion projection degrade prograde etc e Basic map operations order conversion arithmetic degrade prograde com parison etc e A set of useful vector types that can be easily resized e Cartesian and sinusoidal projection of maps pixel vectors point vectors and vector fields onto a 2D grid e FITS reading writing of full sphere cut sphere and vector formats e Perl interface to the C library e Command line utilities for simple math and conversion operations on FITS files e Compatibility functions for legacy programs that currently use the CHEALPIx tools Despite all these useful features keep in mind the version number I think that the existing functional interfaces are fairly stable but alas I cannot make too many promises at this stage The latest version of the HPIC tools can be found on the project website ht
46. s of the columns or values of keys in the header you can use the hpic fits map info function int hpic fits map info char filename size t nside int order int coord int xtype size t nmaps char creator char xextname char xx names char units hpic keys xkeys 27 HPIC CHAPTER 2 C REFERENCE To quickly read a single signal map from a file use the hpic_fits_read_one function A new float map is allocated and returned by the function The keys pa rameter should point to an existing structure allocated with hpic_keys_alloc After the function call any optional keywords in the file will be stored in the keys structure The mapnum parameter is the zero based number of the map you want to retrieve The creator parameter returns the creator string found in the file hpic float hpic fits read one char filename size t mapnum char creator hpic keys xkeys The FITS reading and writing functions below are as general as possible and work with files containing any number of signal columns This generality comes at the cost of ease of use If you are only working with one of the currently existing formats used in CMB research you will probably prefer to use the cmb specific FITS functions in the next section Before reading or writing general map FITS files you will need to allocate enough maps to hold the data in the file The pointers to these maps are then stored inside a special structure which is passed to
47. set hpic vec vec size t elem double val int hpic vec float set hpic vec float vec size t elem float val int hpic vec int set hpic vec int vec size t elem int val int hpic vec index set hpic vec index vec size t elem size t val In a similar fashion you can retrieve the value of a vector element using one of these functions double hpic vec get hpic vec vec size t elem float hpic vec float get hpic vec float vec size t elem int hpic vec int get hpic vec int vec size t elem size t hpic vec index get hpic vec index vec size t elem To set all elements of a vector to a certain value use one of the setall functions below int hpic vec setall hpic vec vec double val int hpic vec float setall hpic vec float xvec float val int hpic vec int setall hpic vec int vec int val int hpic vec index setall hpic vec index vec size t val 2 5 3 Basic Operations There are several simple operations that can be performed on a vector To create a copy of a vector use one of the following commands You should use the appro 17 HPIC CHAPTER 2 C REFERENCE priate free command on both the original and the copy after you are finished using them hpic_vec hpic_vec_copy hpic_vec vec mate vas lores lila ves Flog SITE LLES wee Flog ves hpic_vec_int hpic vec int copy hpic vec int x vec hpic vec index hpic vec index copy hpic vec index x vec Use the functions b
48. side np Stheta Stheta hpic_pix2ang_ring Snside ic_pix2ang_nest nside hpic_vec2ang xcomp pix pix Sphi Sphi Sycomp zcomp Serr Scania eco Hacen Morc aAng2vec Steta SPNL Serr xcomp ycomp zcomp hpic pix2vec ring nside pix Serr xcomp ycomp zcomp hpic_pix2vec_nest nside pix Spix mole vec pug onside SLcamp SYCON ze op Sol lle vecgale est eue Seow T Saucon Snewpix hpic_degrade_nest Soldnside Soldpix newnside Snewpix hpic_degrade_ring Soldnside Soldpix newnside Serie Sx Sy mole Epro Sean omine Ne eor Simasicineica nbl Smaxphai EET otheta Sphi Serr x y hpic proj sin mintheta Smaxtheta minphi maxphi xmax ymax Stheta phi Serr theta phi hpic proj rev car S mintheta maxtheta minphi Smaxphi SMS MA Sx Ey Serr Stheta phi hpic proj rev sin mintheta S maxtheta minphi Smaxphi Sax yw Sx Sy 36 HPIC 3 2 Maps In Perl the HPIC map structures have been wrapped into classes and many of the functions that operate on the structures are now part of the class This means that the calling sequence and names of most of the functions have changed slightly It should still be clear which Perl function corresponds to a certain C function The listing below includes the three map classes and their functions Note how a new map is allocated and destroyed doub
49. t affected by these functions they remain NULL int hpic_scale hpic map double val int hpic_float_scale hpic_float map double val int hpic_int_scale hpic_int map double val int hpic_offset hpic map double val int hpic_float_offset hpic_float map float val int hpic int offset hpic int xmap int val 2 7 3 Arithmetic The functions listed below are used to add subtract multiply or divide two maps of the same type double float or int In all cases the data in the first map is replaced by the result of the operation If the second map has a different ordering or NSIDE value it is automatically converted to the same NSIDE and ordering as the first map before doing the operation The mode parameter can take values of HPIC INTERSECT Or HPIC UNION If the intersection is requested then only 20 HPIC CHAPTER 2 C REFERENCE pixels which are non NULL in both maps will appear in the output the rest of the output pixels will be set to NULL If the union is requested then all pixels that are non NULL in any map will be included in the output In the case of a union operation pixels that exist in one map but not the other will be unmodified in the output int hpic add hpic first hpic second int mode int hpic float add hpic float x first hpic float second int mode int hpic int add hpic int first hpic int second int mode int hpic subtract hpic first hpic second int mode int wo
50. te float subtract hpic float siirast hpic float second int mode int hpic int subtract hpic int first hpic int second int mode int hpic multiply hpic first hpic second int mode sas Imposte lose alcoy age rlbexenE S hpic_float second int mode sas moie ime mileigoly lhnpic tme sees mole ine seconel int mode int hpic_divide hpic first hpic second int mode ae mole loar Chividelhpic loci Sedes hoic float second int mode int hpic int divide hpic int first hpic int second int mode 2 8 Projection The projection types and routines found in HPIC are designed to allow easy projec tion of maps sets of maps vectorfields sets of points and sets of pixels onto a bitmap These functions work but add an extra step if you have to then copy this projection to another image for display purposes If you are developing software to display or print healpix maps you are probably better off creating functions that project a healpix map directly onto a display buffer etc Nevertheless these func tions at least show one way to implement projections of whole maps In order to do this I have defined a structure hpic proj which contains the bitmap and various parameters associated with the projection 21 HPIC CHAPTER 2 C REFERENCE 2 8 1 Allocation To allocate or free the projection structure use the functions below The nx and ny parameters are the dimensions in pixels
51. the reading and writing functions This is somewhat awkward and is necessary for two reasons 1 C cannot easily handle a variable number of function arguments 2 When wrapping C code with SWIG for use in scripting languages it is much more difficult to pass an array of struct pointers than a single struct pointer For map FITS files the hpic fltarr structure is used to pass an array of hpic floats values to the FITS I O routines To allocate and manipulate this simple structure you can use the following functions lose EE SETE injoute iE iliceere callo Exp 1 maes 3 fas Imposte iiheeiwie ose lapie 3bldbeeuevess array SAS 1 Jmppgne s iflbeese 3m aer ape frliteue sauce 2 int hpic fltarr set hpic fltarr array size t elem hpic float map mole locus Ta lean est TVR E LEER mueve size t elem Note that this structure is just a container for holding map pointers it does not handle the allocation or freeing of the maps themselves The exact use of this structure will become more clear if you examine its use in the src test hpictest c test file 28 HPIC CHAPTER 2 C REFERENCE To write or read a file containing full sphere maps use the following functions As previously mentioned the user is responsible for allocating and populating the hpic fltarr structure with pointers to maps that have been allocated The keys parameter should also already be allocated NOTE When writing FITS files the column names and uni
52. tp cmb phys cwru edu hpic 1 3 Future Roadmap There are a few known problems with the current HPIC library that will be ad dressed in future releases Also the most useful tools spherical harmonic trans forms filtering etc have yet to be implemented Here is a list of things to do Implement in place order conversion of maps e Finish implementing tree based map structure e Normal and spin weighted harmonic transforms Standard types of map filtering HPIC CHAPTER 1 INTRODUCTION 1 4 Converting Programs that Currently use CHEALPix If your program currently uses the C library included with the HEALPIx software suite it is trivial to convert it to use HPIC You can either modify your function calls to pass the types that HPIC expects or you can simply prepend a compat prefix to each function call and recompile Of course there are many ways of automating this for example the one line perl command gt perl i p e s ang2pix ring compat ang2pix ring g x will replace all calls to ang2pix ring with the compatibility wrapper version in all files in the current directory The only other changes needed are to include the hpic h header file instead of chealpix h and link with Ihpic instead of Ichealpix HPIC CHAPTER 2 C REFERENCE Chapter 2 C Reference The following chapter outlines how to use the HPIC library in your own software projects You should be able to link this library to both C and C prog
53. ts in the output file are set from the names and units of the input maps int hpic fits full write char filename char xcreator char extname char comment hpic fltarr maps hpic keys xkeys int hpic fits full read char filename char creator char extname hpic fltarr maps hpic keys xkeys To write or read a file containing cut sphere maps use the functions below In addition to the array of signal maps the user also specifies maps for the pixel indices hits and errors The hits errors and all signal maps are cut based on the contents of the index map Every pixel in the index map equal to HPIC INT NULL will be cut in the final output file All non null pixels will be included in the output file int hpic fits cut write char filename char creator char xextname char xcomment ole alme Houses lupe slime ES Moile close lt errs hpic_fltarr maps hpic keys xkeys int hpic fits cut read char filename char creator char extname hpic int pixels mole de Hikes assi cloar Seres hpic_fltarr maps hpic_keys xkeys 2 10 4 Vector FITS I O To test an existing FITS file to see if it is compatible with the healpix vector specifi cation use the hpic_fits_vec_test function This function returns the number of floating point vector columns the length of the vectors number of rows in the table the type of the file and the type of the table The returned filetype pa rameter will equal HPI
54. view 1 10 edition March 2000 3 49
55. x eR A a a 21 28 1 Allo 2 4 54 20 ede md a cm teo 22 2 8 2 Parameter ACCESS oo e c ec mov is ed dws 22 2 8 9 Data ACCESS o xo 9 a o e m N 22 2 8 4 Projecting Maps and Vectors 23 2 9 Transforms and Filtering gt gt ssas sws ee ed eae es 24 2 10 FITS Reading and Writing 0 24 2 10 1 Format Specifications s s e es sce eae o om 24 2 10 2 Optional Keys imm mk Remy mm al O R 26 210 3 Map FITS TO lt uc io a omm deese cm 8 27 2104 Vector FITS IO 1 2 ea a we Xm 29 2 11 CMB Specife Functions scu so wa eu m ewe a eG 31 211 1 Projection oo ae a a we BR ee Be ew a 31 241 2 Specialized FITS UO i zuo a4 be 24 eke Re eo 32 2 12 Compatibility Wrappers on sr oe Park de ea bare Ps 33 2 12 1 Pixel TOO S lt lt olor dia ee a ek ee 33 2122 Legacy PIRS I O ad de a a 34 3 Perl Reference 35 3 1 Constants and Low Level Functions 35 A Maps cees eae fo dd OS a Dae ee eS a de dex 37 So Veto isos rior 6 Sex doa Bard He eS ae e 39 3 4 Mathand Miscellany o RRR R a 40 3 9 o R poo sp Xe BS ee hee Xu ae a 41 3 6 Transforms and Filtering o 41 3 PITS UO ooo sir a a a A mox Oe G 41 35 8 CMB Specife 4 nao 22248254 o dra ab 43 4 Command Line Tools 44 4 1 General Tools s eco cre x oe Ba oR Ro eee eee ee d 44 42 Simple Math Tools os seee s Rok Rer ee eS 48 References 49 HPIC CHAPTER 1 INTRODUCTION Chapter 1 Introduction This software package
56. xisting variable To find out the total number of keys of all types stored in a structure use the hpic_keys_total function int hpic keys total hpic keys keys int hpic keys sfind hpic keys keys char keyname char keyval char keycom int hpic keys ifind hpic keys x keys char keyname int keyval char keycom int hpic keys ffind hpic keys x keys char keyname float keyval char x keycom It is sometimes useful to print the contents of a keys structure to a file or stdout This can be accomplished by the two functions below int hpic keys fprintf FILE fp hpic keys keys int hpic keys printf hpic keys keys 2 10 3 Map FITS I O To test an existing FITS file to see if it is compatible with the healpix map specifica tion use the hpic fits map test function This function returns the NSIDE ordering coordinate system and type of the file as well as the number of sig nal maps in the file for example a four column cut sphere file has only one signal map The returned t ype parameter will have a value equal to either HPIC FITS FULL HPIC FITS CHUNK Or HPIC FITS CUT The return value of the function will be equal to 1 if the file is a supported type and zero if it is not recognized int hpic fits map test char filename size t nside int xorder int coord int type size t xnmaps If you want to check file s compatibility but need slightly more information about the file such as the name
57. xt file and creates a valid healpix FITS file impo rab out output FITS file The name of the FITS file to generat vec build vector FITS file vecindx build indexed vector FITS file full build full sphere map FITS file cut build cut sphere map FITS file These 4 options specify what type of file you wish to build You must specify exactly one of these options nside nside of maps If you are building a map FITS file then this is the NSIDE value of the maps order lt 0 NESTED 1 RING gt If you are building a map FITS file then this 46 HPIC CHAPTER 4 COMMAND LINE TOOLS is the ordering of the maps table lt 0 BINARY 1 ASCII gt If you are building a non index vector FITS file then this specifies the type of table to use SUMES cuum e The units of the signal columns coord coordsys eg C G 0 gt If you are building a map FITS file then this is the coordinate system to use input text file properly formatted The final argument is the name of the input text file The formatting of the text file is as follows the first line contains a comment character the first word of the line is ignored followed by three numbers The first number is the number of optional keys The second number is the total number of columns The third number is the length of the columns After the first line are a number of lines specifying optional key values

HPIC User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents