CPOLAR SHORT USER MANUAL Andrei Berdyugin Jan -01 Program CPOLAR reduces data obtained with TurPol in the CIRCULAR polarization mode (lambda/4 plate, circular polarization). The program normally runs under MS-DOS (as it has been originally written for this operational system). You can, nevertheless, run it under Windows, and usually it works, depending on system configuration. If you experience program crashes, or problems with the display under Windows, restart in the DOS mode. program components: cpolar.exe - program code wpview.exe - external viewer (you can use it to view data file withing the program) ned.com - external editor (you can use it to edit data file, if necessary, withing the program) install.cfg - configuration file (see later) You must have all these files in the folder where your data files are located. *Note: Do not use long names for files and folders (more that 8 symbols) as they are not supported under DOS. Do not use symbols other than alphanumeric (like _, /, \ ' ') in the names, program does not like these either. You can start the program by typing 'cpolar'. What you see is the Main Menu with several available options. Check configuration file at first by choosing 'Setup' and 'Change setup' options. The 'UT correction' normally must be set to 0.0 as the computer at the NOT on which PP program runs is set to UT. 'CPA corrections' values can be arbitrary, as CPOLAR does not actually use them. You can 'Save setup on disk' for later use. You don't need to use option 'Constants' if the data file was obtained with the NOT. 'File' option allows you to start data reductions by 'loading data file'. The Program shows you the full path to the folder you are working in. You can type in file name directly, or type its extension, otherwise program will display the full content of the current folder. Choose the file you want to reduce by using arrow keys or PageDown/PageUp, if needed. As you press 'Enter', program loads the file you selected. Before doing that you may want to 'Check', 'View' or 'Edit' this file. Data file must have an appropriate format to be reduced (see TurPol manual). Option 'Check' (F5 key) tests the file for the most common errors like missing data strings, wrong string lenght, etc. It is not able to find EVERY possible error which can potentialy crash the program. If you see the message 'No errors were detected' but program crashes, inspect the file carefully using 'Edit' option. *Note: Sometimes 'Check' tells you the message 'wrong string lenght' but string looks OK. It happens because some text editors put 'end-of-line' symbol or 'blank' at the end of string. Usualy this symbol is not displayed, so you cannot see it. If this happens, just ignore this message. Option 'View' (F3) allows you to view data file, while 'Edit' (F4) allows you to edit and save it on disk after editing. Withing the editor, Help is available by pressing F1 key, to explain the editor's commands. Usually you quit from the editor by pressing F3 and E (exit-with-save). When you load a data file, program displays its contents in the 'File content' window. You see it as a table with several entries,- star number, observation start time, exposure, filter/diaphragm used, and the number of measurements. *Note: The number of different objects (stars) in a single data file must not exceed 16, otherwise the program cannot display the above mentioned window. It does not limit the number of measurements for a single object, but you cannot have in one file more than 16 stars with different unique numbers. If it happens, just split your file in two (or more) parts. Remember, all these parts/files must have an appropriate format! In the 'File Content' window you can choose the star you want to reduce by using UP or DOWN arrow keys and pressing 'Enter'. When you press 'Enter', the program extracts the data strings for the chosen star from the data file and stores them on the disk in a separate file which has a name star_number.str. You can load as many stars as you have in the data file: use arrow keys and press 'Enter' repeatedly. When you have this finished, press 'Esc' to escape from the file window. The program uses the following strategy: choose file, - choose star (stars),- reduce one star,- (another one,..),- choose next file,- and so on. *Note: If you have the same star (with the same fixed number) in many data files the program will overwrite its str file any time you load the new data file. All .str files are stored in the current folder. Then you can reduce them one by one using 'Star file reducing' option. You see a window which shows you all str files you have in the folder. It looks much the same as the 'load data file' window. You choose the str file by using arrow keys and pressing 'Enter'. You can also use 'View' and 'Edit' options, if needed. When you press 'Enter', program calculates polarization for the selected star. Here you can choose and reduce only one star in a time. The next step is to go to the 'Display' option which allows you to view the computed polarization on the screen. You can display either 'Polarization' or 'Magnitude and counts'. The second option simply displays the instrumental magnitudes calculated from the photon counts. When you choose 'Polarization', display switches to the DOS graphical mode, which always runs in full screen. It may take some noticeable time for program to switch, and you may also experience display problems. If it happens, run program under DOS. This is very seldom needed, normally it is even possible to switch to other Windows applications by using ALT-TAB. What you immediately see after that is the circular polarization points calculated from the raw data. They are plotted as a function of the Julian Day (JD). The vertical bars are the errors. *Note: The errors you see on the screen are calculated from the dispersion, not from the photon statistic. You may wonder, what is a dispersion for the single polarization measurement. Actually, every 'single' measurement of circular polarization (eight strings in data file) consists of four individual measurements as the lambda/4 plates makes two rotation cycles and withing each cycle circular polarization is measured twice! For this reason in circular polarization mode the measuring efficiency of TurPol is the highest. *Note: The screen looks pretty odd at the first sight as it shows two identical plots. This is a "rudiment" from the ancestor program POLAR, upon which CPOLAR is based. POLAR reduces linear polarization and displays two Stokes parameters Px and Py in two separate plots. Only ONE Stokes parameter is required to describe circular polarization, and you can disregard the second plot. The Program precalculates the scale and margins to display polarization points properly for all passbands and in the same scale. In most cases it works fine, but if you see the message 'The value of Pc is out of margins' or if you don't like precalculated scale/margins you can change them by using "Hot keys" (these letters are highlighted on the screen with bright green). In the pop-up window you can type in the values you want. To move withing the input field use LEFT/RIGHT arrows, to jump from one field to another one in forward direction- TAB key, to jump in reverse direction - BACKSPACE key. When you press 'Enter' the new values are taken and program redraws the screen. To switch between the active passbands use UP and DOWN arrows. By changing scale and margins you alter the plot for all passbands. By pressing 'Esc' you exit from 'Display' sub-menu (it works exactly in the same way with other sub-menus available in graphical mode). In the graphical mode you have 5 options (sub-menus) to choose from: Display, Marker, Reduce, Save results and Exit. If you don't need to make any corrections to your polarization data file you can go directly to 'Save results', choose 'Single measurements', give the name for the ouput file and all individual measurements for the chosen star will be saved on disk. After that you can Exit from the graphical mode, reduce another star file (or load another data file), or Quit the program. Remember, the computed polarization values are kept in the program memory until you reduce a new star file. All str files are kept in the current folder if you quit by choosing the option 'Keep *.str files'. You can get rid of them by choosing 'Delete *.str files'. Program offers you some tools which you can apply on the polarization data in graphical mode. Option 'Marker' activates marker cursor you can use to move from one point to another. In the Info Window at the screen bottom program displays polarization value with error and the moment of Julian Date at which it was measured. If you suspect that some point(s) are spurious (clouds etc.) you can delete them by pressing the DELETE key. These points still will be saved in the output file as single measurements, but they are not used when you compute the average polarization (see later). Discarded point is shown by empty blinking circle which appears as you put the marker on its former place. If you deside to restore previously discarded point, put marker on it and press INSERT key. It will reappear on screen (and in the polarization data array). Option 'Reduce' allows you to calculate average polarization from the individual polarization values. Withing 'Reduce' you can calculate averages for all bands at once ('a' hot key), or for the active band only ('f' hot key). In latter case you must go to the 'Display' option, change the passband and repeat reduction process. This way could be useful if the accuracy of observations and data point scatter differ strongly from one passband to another. When program computes average values, it displays the value for the active band by horizontal line on the screen and shows its numerical value in the info window. *Note: The program computes average polarization as a weighted mean, using inverse square errors as the weights. Actually the program always computes two errors even for a single polarization point: theoretical (as expected from the photon statistic) and the error calculated from the scatter. In ideal conditions these errors are supposed to be equal, in real life the latter is usually larger. In the file where you save your results, these two errors are labeled as ep1 and ep2. The ratio of these errors is a measure of the polarization data quality: if ep2 exceeds ep1 by several times, something was wrong during the measurements (star has been too far from the diaphragm center, clouds, etc.). When computing average polarization, program uses the largest one (ep1 or ep2) for inverse square weighting. If the object you have observed is a periodic variable, you can calculate the phase. Use hot key 'i' to input Period and To at first, then press 'p'. program computes phase for the every individual polarization point and displays the average phase in the info window. Computed phase will be included in the resulting file. In the 'Display' option you can view the polarization as a function of a phase (it makes a sense if the period is short, of course). To switch between JD and phase use 's' hot key. *Note: The given Period and To are kept in the program memory untill you input new ones, or quit from the program. If you reduce the same star observed withing many data files, you don't need to reinput P and To every time when you load a new file, just press 'p' to calculate the new phase. Option 'Save results' allows you to save results of the reductions you have done. You can save into the same file both the individual polarization points and the average values ('b' hot key), or save only averages/only single points ('a' or 's' hot keys). *Note: If you didn't compute averages before saving, the resulting file will contain zero average values. How to use the 'Sky' option, available at the main menu: This option gives you a possibility to interpolate the sky. In the data file, star integrations are always preceded by sky which is subtracted from the star counts. Normally, program takes the closest preceding sky and subtracts it from the star integrations which come after, until a new sky integration is found. Then this new sky is subtracted from the star integrations which come next and so on. Sometimes, you may want to interpolate the sky, e.g. the star is very faint (comparable with sky in brightness) and you were observing at sunrise/sunset. In order to do that, you must have the str file already extracted and stored in the current folder (see 'load data file'). Then you choose 'Load star file' from the 'Sky' menu and pick up the star file exactly in the same way as you do it for polarization reductions. Then use 'Display' sub-menu and the program will switch to the graphical mode showing on the screen the sky counts in both channels. The graphical menu has the following sub-menus: 'Display', 'Marker', 'Reduce' and 'Exit'. The first two and the last one works exactly like in the 'Display' polarization mode. 'Reduce' option allows you to do the following: 1) to level the sky - program calculates the average value from two channels. 2) to approximate the sky linearly 3) to interpolate sky with cubic spline. 1) can be used in combination with 2) and 3). To go from one passband to another, change the active band in 'Display' sub-menu. When you finish with that, 'exit' from the graphical mode. The next thing to do is to choose 'smooting' and press 'enter'. Program subtracts the interpolated sky and makes the new str file: s_star_number.str which is stored in current folder and can be reduced exactly in the same way as the ordinary str file. *Note: Do not expect any significant improvements from this procedure if the star is much brighter than the sky or if the sky variations are small. In such case you can hardly find any difference. The output file for reduced data has the following format: ------------------------------------------------------------------------------ star 2047 date 17: 7: 1 J.D. Pc ep1 ep2 mag counts Phase U - band 2452108.5342 0.107 0.099 0.153 6.822 129185 0.8683334 2452108.5365 0.131 0.098 0.081 6.802 131567 0.8729399 2452108.5388 -0.119 0.100 0.118 6.841 126883 0.8775464 2452108.5411 -0.027 0.099 0.156 6.819 129598 0.8821528 2452108.5448 0.167 0.098 0.126 6.808 130899 0.8896066 2452108.5471 0.033 0.098 0.119 6.802 131562 0.8942130 2452108.5494 0.027 0.097 0.198 6.774 135032 0.8988195 2452108.5517 0.016 0.097 0.202 6.776 134773 0.9034260 2452108.5549 0.092 0.097 0.108 6.784 133727 0.9098381 2452108.5572 0.086 0.097 0.129 6.782 134087 0.9144445 2452108.5595 -0.060 0.097 0.162 6.772 135316 0.9190510 2452108.5618 -0.094 0.097 0.137 6.768 135736 0.9236575 2452108.5651 -0.041 0.096 0.143 6.756 137295 0.9302779 2452108.5674 0.217 0.096 0.095 6.754 137539 0.9348612 2452108.5697 0.120 0.096 0.150 6.748 138230 0.9394677 2452108.5720 -0.038 0.096 0.133 6.746 138520 0.9440742 2452108.5758 -0.012 0.096 0.098 6.751 137972 0.9515510 2452108.5781 0.043 0.096 0.114 6.763 136421 0.9561575 2452108.5804 0.040 0.096 0.070 6.759 136867 0.9607409 2452108.5827 -0.128 0.096 0.102 6.759 136938 0.9653474 B - band 2452108.5342 0.032 0.044 0.104 5.054 658090 0.8683334 2452108.5365 0.081 0.043 0.096 5.038 668282 0.8729399 2452108.5388 -0.029 0.044 0.068 5.072 647224 0.8775464 2452108.5411 -0.035 0.044 0.072 5.054 658335 0.8821528 2452108.5448 0.094 0.044 0.036 5.045 663638 0.8896066 2452108.5471 0.074 0.043 0.087 5.043 665130 0.8942130 2452108.5494 0.105 0.043 0.095 5.017 681386 0.8988195 2452108.5517 0.012 0.043 0.120 5.020 679422 0.9034260 2452108.5549 0.113 0.043 0.069 5.027 674793 0.9098381 2452108.5572 0.081 0.043 0.083 5.027 674814 0.9144445 2452108.5595 0.093 0.043 0.053 5.020 679421 0.9190510 2452108.5618 0.101 0.043 0.073 5.017 680905 0.9236575 2452108.5651 0.036 0.043 0.093 5.006 687729 0.9302779 2452108.5674 -0.049 0.043 0.040 5.007 687619 0.9348612 2452108.5697 -0.037 0.043 0.069 5.003 689633 0.9394677 2452108.5720 -0.006 0.043 0.071 5.001 690920 0.9440742 2452108.5758 -0.068 0.043 0.085 5.003 689881 0.9515510 2452108.5781 0.070 0.043 0.079 5.013 683873 0.9561575 2452108.5804 0.007 0.043 0.065 5.011 684894 0.9607409 2452108.5827 0.030 0.043 0.060 5.011 684560 0.9653474 V - band 2452108.5342 0.014 0.049 0.088 5.293 528104 0.8683334 2452108.5365 0.007 0.049 0.068 5.281 533965 0.8729399 2452108.5388 0.064 0.049 0.067 5.310 520186 0.8775464 2452108.5411 0.079 0.049 0.055 5.293 528396 0.8821528 2452108.5448 0.040 0.049 0.102 5.288 530718 0.8896066 2452108.5471 0.016 0.049 0.072 5.284 532503 0.8942130 2452108.5494 0.031 0.048 0.076 5.265 541910 0.8988195 2452108.5517 0.005 0.048 0.059 5.268 540469 0.9034260 2452108.5549 0.046 0.048 0.089 5.276 536502 0.9098381 2452108.5572 -0.024 0.048 0.073 5.276 536698 0.9144445 2452108.5595 0.152 0.048 0.037 5.267 540780 0.9190510 2452108.5618 0.030 0.048 0.105 5.268 540715 0.9236575 2452108.5651 0.093 0.048 0.057 5.257 545835 0.9302779 2452108.5674 -0.015 0.048 0.069 5.256 546421 0.9348612 2452108.5697 0.021 0.048 0.053 5.257 546241 0.9394677 2452108.5720 0.056 0.048 0.049 5.256 546535 0.9440742 2452108.5758 0.043 0.048 0.081 5.255 546941 0.9515510 2452108.5781 0.178 0.048 0.053 5.262 543641 0.9561575 2452108.5804 0.022 0.048 0.035 5.262 543290 0.9607409 2452108.5827 0.001 0.048 0.076 5.262 543297 0.9653474 R - band 2452108.5342 0.004 0.028 0.057 4.105 1578102 0.8683334 2452108.5365 -0.014 0.028 0.042 4.094 1593451 0.8729399 2452108.5388 0.029 0.028 0.058 4.114 1564675 0.8775464 2452108.5411 -0.063 0.028 0.034 4.109 1572162 0.8821528 2452108.5448 0.021 0.028 0.056 4.105 1577122 0.8896066 2452108.5471 0.020 0.028 0.061 4.098 1588362 0.8942130 2452108.5494 0.029 0.028 0.053 4.089 1601538 0.8988195 2452108.5517 0.004 0.028 0.065 4.090 1600131 0.9034260 2452108.5549 0.043 0.028 0.070 4.095 1592855 0.9098381 2452108.5572 -0.007 0.028 0.061 4.098 1587364 0.9144445 2452108.5595 0.006 0.028 0.035 4.084 1607785 0.9190510 2452108.5618 0.029 0.028 0.031 4.090 1599895 0.9236575 2452108.5651 -0.006 0.028 0.049 4.083 1609427 0.9302779 2452108.5674 0.011 0.028 0.049 4.076 1620366 0.9348612 2452108.5697 -0.012 0.028 0.052 4.084 1608992 0.9394677 2452108.5720 -0.023 0.028 0.079 4.080 1615087 0.9440742 2452108.5758 -0.047 0.028 0.053 4.079 1615748 0.9515510 2452108.5781 0.031 0.028 0.080 4.085 1606992 0.9561575 2452108.5804 -0.037 0.028 0.048 4.085 1606368 0.9607409 2452108.5827 0.010 0.028 0.066 4.083 1610009 0.9653474 I - band 2452108.5342 0.059 0.033 0.052 4.416 1185113 0.8683334 2452108.5365 -0.038 0.032 0.042 4.408 1193221 0.8729399 2452108.5388 0.014 0.033 0.051 4.424 1175571 0.8775464 2452108.5411 -0.049 0.033 0.039 4.418 1181966 0.8821528 2452108.5448 0.013 0.033 0.060 4.416 1184350 0.8896066 2452108.5471 -0.007 0.033 0.048 4.413 1187512 0.8942130 2452108.5494 0.002 0.032 0.072 4.406 1195609 0.8988195 2452108.5517 0.047 0.032 0.050 4.409 1192626 0.9034260 2452108.5549 -0.024 0.033 0.057 4.411 1190154 0.9098381 2452108.5572 -0.062 0.033 0.048 4.414 1186649 0.9144445 2452108.5595 0.027 0.032 0.033 4.405 1196676 0.9190510 2452108.5618 -0.014 0.032 0.060 4.408 1193985 0.9236575 2452108.5651 -0.029 0.032 0.050 4.399 1203312 0.9302779 2452108.5674 0.065 0.032 0.060 4.398 1204088 0.9348612 2452108.5697 -0.027 0.032 0.049 4.403 1198441 0.9394677 2452108.5720 -0.020 0.032 0.062 4.402 1199798 0.9440742 2452108.5758 -0.055 0.032 0.047 4.401 1200989 0.9515510 2452108.5781 -0.042 0.032 0.067 4.403 1199125 0.9561575 2452108.5804 -0.043 0.032 0.051 4.402 1200001 0.9607409 2452108.5827 -0.050 0.032 0.037 4.401 1201443 0.9653474 AVERAGE star 2047 date 17: 7: 1 J.D. 2452108.5584 Phase: 0.9168253 Fil Pc e0 e1 mag err counts err n U 0.033 0.022 0.022 6.779 0.028 134407 3388 20 B 0.035 0.010 0.013 5.024 0.020 676527 12467 20 V 0.050 0.011 0.013 5.272 0.015 538657 7538 20 R -0.001 0.006 0.007 4.091 0.011 1597822 15615 20 I -0.013 0.007 0.009 4.408 0.007 1193531 7893 20 ----------------------------------------------------------------------------- Single measurements: Star- star number, date- calendar date, U, B, V, R and I- the passbands, JD - Julian Date calculated at the moment of observation, Pc - circular polarization in percents, ep1 - statistical error, ep2 - error from the dispersion, Mag - magnitude in instrumental system, Counts - the photon counts, Phase - phase, if computed (otherwise - blank). Average: Star- star number, date- calendar data, JD - average Julian Date, Phase - average phase (if computed) Fil - passband, Pc - average circular polarization, in percents, e0 - statistical error of the average polarization, e1 - error of the average from the dispersion, mag - average magnitude, counts - average photon counts. n - total number of single measurements. Final note: Any comments, suggestions and bug reports are welcomed, send them to andrei@astro.utu.fi