\def\pagenumbers{\footline={\hss\tenrm\folio\hss}} \magnification=\magstephalf % 1.1 magnification \lineskip=2 truept % minimum interline clearance \parindent=0pt %\baselineskip=15 truept plus .2 truept % 3.428 lines/inch \parskip=18 truept plus 5 truept minus 2 truept % paragraph skip one line \hsize=6.2 truein % page width \vsize=9 truein % page height \font\figfont=cmr8 \font\mainfont=cmr12 \def\figa#1{\centerline{\hbox{\figfont{ #1}}}} \def\figb#1{{\leftskip=2.5 truecm\rightskip=1 truecm\noindent \figfont{\smallskip #1\smallskip}}} \settabs 3 \columns \pageno=1 \input verbatim \startverbatim %\mainfont \centerline{\bf MKBSD User Guide (Version 1.2 -- 16/3/92).} {\bf 1. Introduction.} MKBSD is part of the post-launch analysis software for the BCS experiment on SOLAR-A. It is written as far as possible in ANSII standard FORTRAN77. It allows the user to control the accumulation of data sets from a BDA file ( containing the BCS reformatted data) and produce a spectral data (BSD) file. The BSD file is used as input to the other BCS post-launch software routines which are described in the ``BCS Data Analysis Software Summary''. For further information see also MKBSD programmer's guide. MKBSD allows the user to specify the channels to be used and a time period of interest within the data contained in the BDA file. The accumulation of spectra within the period of interest can be controlled by specifying either the accumulation time per spectrum or the minimum number of total counts measured in a selected channel. The accumulated (BSD) spectra are stored in the BSD file in the form count rate per unit bin (see appendix A). MKBSD can be run either interactively or in unsupervised mode. The unsupervised mode is intended for batch processing. The values of various parameters and options may be set up beforehand in a control file which is an ASCII file produced by running MKBSD in interactive mode. A description of each of the commands in MKBSD in interactive mode is given in appendix G or may be obtained by using the Help (command name) facility within MKBSD. The user may choose to : \bigskip {\parskip=0pt \parindent=40 pt\rightskip=40 pt \item{$\bullet$} correct count rates for dead-time losses in the detector electronics (default is to apply correction, see Appendix E); \item{$\bullet$} correct bin positions for bin non-uniformity and crystal curvature (default is to apply correction); \item{$\bullet$} correct for variations in pointing between the BDA spectra within a BSD spectrum (default is no correction); \item{$\bullet$} degroup or resample the data (default is no degrouping, see Appendix D)). } {\bf 2. Running MKBSD.} MKBSD may be used in either interactive or unsupervised mode. Under VMS, for interactive mode type : | RUN REXE_DIR:MKBSD | and for batch mode (using the example command file MKBSD.COM and the test control file MKBSD.CFL) type : | @REXE_DIR:MKBSD REXE_DIR:MKBSD.CFL | Note that this assumes that the relevant logical names have been set up by running : | @DISK$USER1:[SOLAR_A.BCS]DEFINE-SOLARA-LOGICALS. | This will normally have been executed automatically on login to ISASXA (BCS computer at ISAS) but may need to be run explicitly elsewhere. Batch mode operation, using the above VMS command file, produces the file MKBSD.OUT and the BSD file in the user's login directory. In both modes the user is first prompted for the name of a control file. If a control file name is given the program then runs in unsupervised mode using the parameters and options from the control file. This allows the control file name to be entered, as in the above, as the argument of a VMS command file and then defined as the standard input stream so that the program can be run in batch mode. If no control file name is given in response to the control file input prompt then the program enters interactive mode. A menu is then displayed giving the codes for changing parameter and option settings and for displaying some information on the BDA file specified for processing. The user may read in an existing control file or use pre-set values for the parameter and option defaults. Some commands are provided to give information on the currently defined BDA file : \bigskip {\parskip=0pt \parindent=40 pt\rightskip=40 pt \item{$\bullet$} HD displays some of the information contained in the header, quasi-static index and optional data header sections of the BDA file; \item{$\bullet$} SU displays a summary of the data contained in the spectral data sets in the BDA file; \item{$\bullet$} CK uses the currently defined parameters to perform a dummy spectral accumulation, allowing the user to check the output produced. } The quantity of information displayed is controlled by the Verboseness (V) option in the menu section. During execution of the main part of the program this controls whether information on each individual spectrum within an accumulation is displayed; whether information on each accumulated spectrum is displayed or whether only a summary of the accumulated spectra produced is displayed. Typing Halt output (H) after the appropriate prompt returns the user to the menu display. An on-line help facility is provided giving a brief description of each command, parameter or option. This is invoked by typing, for example : | Help Accumulation time ( or H A ) | On using the command EXIT (EX) or Quit (Q) to leave the menu section the user may specify a new control file name to store the current parameter and option settings. Note that EXit and some of the other commands in the menu section require a valid BDA file to have been specified since they check that the BDA file can be opened and read from and also that the BSD file can be opened. The command Quit ends execution of the program but still gives the user the option of saving the new parameters in a control file. On EXiting the menu section the program goes on to perform the spectra accumulations. After each page of output the user is prompted for further display. Entering Halt output (H) turns off the output to the terminal but continues operation. {\bf 3. MKBSD example run.} To run MKBSD under VMS type : | RUN REXE_DIR:MKBSD | The program prompts for a control file name. Pressing RETURN puts the program into interactive mode where the following menu is displayed : | CURRENT PARAMETER SETTINGS ARE := CODE BDA FILE NAME = bda000000.0000 F BEGIN TIME = 00:00:00:000 01/01/1979 B END TIME = 00:00:00:000 01/01/1979 E MIN. NO. OF SPECTRA = 0 S CHANNELS TO BE USED = 1, 2, 3, 4 C ACCUMULATION PERIOD = 20.000 SECS A MINIMUM COUNT LEVEL = 0 CL COUNT CHANNEL = 1 CC POINTING CONSISTENCY = 0.10000 ARCMINS FLARE OFFSET FO BDA FILE HEADER SECTION INFO HD SUMMARY OF SPECTRA SU READ NEW CONTROL FILE R CHECK PARAMETERS CK DISPLAY OPTIONS O HELP FACILITY H QUIT PROGRAM Q EXIT INTERACTIVE SESSION EX | The parameter settings displayed are the default settings. Entering the command O gives the default option settings. | CURRENT OPTION SETTINGS ARE ( 0 = OFF ) :- CODE DEADTIME CORRECTION = 1 DC CRYSTAL CURVATURE = 1 CV STATISTICAL ERRORS = 0 SE VERBOSE OUTPUT = 0 V RELATIVE POINTING CORRECTION = 0 PC DEGROUP DATA = 0 DG | Pressing RETURN brings back the main menu display. To access a BDA file enter the command F and give the BFA file name in reply to the prompt i.e. | > F > REXE_DIR:920209.1545 | The program will open and read the BDA file and also attempt to open the corresponding BSD file. The begin and end times of the period of interest default to the start of the first and end of the last spectrum in the BDA file. The command SU provides information on the spectra within the BDA file : | SUMMARY OF SPECTRA IN BDA FILE READING ROAD-MAP SECTION OF BDA FILE NUMBER OF DATA SETS IN FILE = 1830 SUMMARY OF ROAD-MAP SECTION OF BDA FILE TIME OF FIRST SPECTRA = 15:40:22:398 09/02/1992 TIME OF LAST SPECTRA = 23:56:39:327 09/02/1992 SUM OF DATA GATHER INTERVALS (SECS) = 5743.0 TOTAL ELAPSED TIME (SECS) = 29777. NUMBER OF REJECTED DATA SETS = 9 SUM OF TOTAL COUNTS IN EACH CHANNEL : CHANNEL 1 = 227220 CHANNEL 2 = 398710 CHANNEL 3 = 890680 CHANNEL 4 = 6834130 TIME OF PEAK RATE SPECTRA = 22:06:37:346 09/02/1992 TOTAL COUNTS IN PEAK RATE SPECTRA :- CHANNEL 1 = 100 CHANNEL 2 = 330 CHANNEL 3 = 1290 CHANNEL 4 = 7280 READING OPTIONAL DATA SECTION OF BDA FILE NUMBER OF OPTIONAL DATA RECORDS IN FILE = 7912 SUMMARY OF OPTIONAL DATA SECTION OF BDA FILE TIME OF FIRST SPECTRA = 15:45:37:148 09/02/1992 TIME OF LAST SPECTRA = 23:56:39:081 09/02/1992 SUM OF ACCUMULATION INTERVALS (SECS)= 23776 TOTAL ELAPSED TIME (SECS) = 29462. | The information displayed by the SUmmary command is gleaned from the road-map and optional data sections of the BDA file (see BDA file format documentation). BDA spectra data sets are rejected if they have ${\rm MODEID}\ne1$ or ${\rm BLOKID}>1$ i.e have undefined grouping plan or are not real data. The optional data section contains count rate information used for electronic deadtime correction. The user may then choose to select a period of interest around the peak rate spectrum (rate is counts/data gather interval). Entering the command B prompts for the start of the period of interest and the command E prompts for the end of the period of interest. The level of output may be changed by the command V i.e. | > B > 22 5 0 (program puts in a default date) > E > 22 10 0 > V > 1 | The command SU then gives more detailed information on the data within the period of interest : {\hsize=8 truein | READING ROAD-MAP SECTION OF BDA FILE REC. TIME MODE BLCK DGI COUNTS 1063 22:05:01:346 09/02/1992 1 0 3.000 80 340 1190 7000 1064 22:05:04:346 09/02/1992 1 0 3.000 110 340 1210 7010 " " " " " " " " " 1092 22:06:28:346 09/02/1992 1 0 3.000 100 290 1220 7160 1093 22:06:31:346 09/02/1992 1 0 3.000 100 320 1160 7080 READING OPTIONAL DATA SECTION OF BDA FILE REC.NO. TIME DPRATE ACCUMULATION INTERVALS (SECS) 6153 22:05:01:092 09/02/1992 4 1 1 6154 22:05:03:092 09/02/1992 4 1 1 " " " " " 6187 22:06:09:091 09/02/1992 4 1 1 6188 22:06:11:091 09/02/1992 4 1 1 | } The user may choose to change the default accumulation time for BSD spectra with the command A, change the level of output to 0 and then proceed with the accumlation using the command EX i.e. | > A > 120 > V > 0 > EX | The program will prompt for a control file name to save the current parameters and options and then continues execution. The control file for the above is given in MKBSD.CFL . The program output during execution is controlled by the verbosity level. For each BSD spectra accumulation the program runs through the BDA file road-map section to decide how many BDA spectra will be included in the accumulation. The program then runs through the data section of the BDA file extracting the data and applying optional corrections. The BSD spectra is then written to the BSD file. Output with the above control file (V=0) is : {\hsize=8 truein | **************************************** * BEGIN SPECTRA ACCUMULATION * **************************************** SPECTRUM TIME SPECTRA SPECTRA TOTAL COUNTS IN EACH NO. INCLUDED REJECTED SPECTRUM 1 22:05:01:346 09/02/1992 40 0 4190 12690 48870 283560 2 22:07:01:346 09/02/1992 23 0 1970 5740 25710 157470 3 22:09:04:339 09/02/1992 40 0 2960 8300 44630 285760 **************************************** * END SPECTRA ACCUMULATION * **************************************** SUMMARY OF ACCUMULATED SPECTRA NUMBER OF ACCUMULATED SPECTRA = 3 TIME OF START OF ACCUMULATION = 22:05:01:346 09/02/1992 TIME OF END OF ACCUMULATION = 22:11:04:339 09/02/1992 | } {\bf Appendices.} {\bf A. Accumulation of spectra.} The spectral data is stored in the BSD file in the form of count rate per unit bin at a specified bin position. The bin position corresponds to the position of the rightmost boundary of the bin. The spectra are arranged so that increasing wavelength corresponds to increasing bin position. The dispersion and wavelength offset (dw and wo) are also stored for each spectrum. The wavelength corresponding to the right hand side of each bin is then given by : $${\rm wavelength}= {\rm wo}+{\rm dw}*{\rm bin\ position}$$ Within an accumulation, MKBSD searches through the BDA file until it finds the next valid spectrum ( a valid spectrum is one which starts within the period of interest defined in the control file and which satisfies various data quality checks). Accumulation of valid spectra then continues within an accumulation time interval of the first valid spectrum until both the accumulation time is exceeded and sufficient counts, as defined by the count level requirement, are accumulated. The elapsed time of an accumulation is the period between the start of the first and the end of the last spectrum in the accumulation. For contiguous spectra this should be equal to the sum of the data gather intervals of the spectra in the accumulation. Spectra accumulations continue until both the end of the last spectrum in the previous accumulation is outside the period of interest defined in the control file and sufficient accumulated spectra, as defined by the the number of spectra requirement, are produced. {\bf B. Pointing offset and flare offset correction.} The BCS instrument points approximately at sun centre. The offset of the incoming light caused by the offset of the flare from sun centre and by pointing offsets from sun centre have the effect of shifting the observed spectra in wavelength. A one arcmin offset shifts the spectra by approximately 0.001 Angstroms or 5-10 detector bins (exact values depend on channel). It is expected that the absolute pointing accuracy of the spacecraft will be in the region of a few arcmins and the short term control stability will be a few arcsecs. The eventual accuracy to which pointing is known should be within 1-2 arcsecs. The average pointing during an accumulation is monitored by MKBSD and passed on to the BSD file for each accumulated spectrum. The flare offset may be entered in the control file or during the interactive session and will be passed on to the BSD file. No correction is made within MKBSD for the absolute pointing offset or flare offset. The resulting wavelength of the spectrum is determined by subsequent programs. For accumulation periods of the order of ten minutes the variation of pointing within an accumulation may introduce significant blurring of the spectrum. The option exists within MKBSD to correct each individual spectrum within an accumulation for the pointing offset relative to the average pointing offset. The user specifies a pointing variation threshold; if the pointing variation during an accumulated spectrum is greater than the threshold then the individual spectra are corrected for their relative pointing offsets. {\bf C. Crystal curvature and non-uniformity correction.} The BCS detectors have slightly non-uniform bin sizes so that the physical bins map into different sized wavelength intervals and have different sensitivities. The crystal curvature effect also means that the wavelength interval spanned by a bin changes across the detector. These effects can be corrected in MKBSD using calibration tables and result in non-integer values for the bin positions in the BSD file. The calibration tables contain the value for the dispersion used by MKBSD followed by the $\sin(\theta)$ values of the centre of each bin and the calculated values for the relative number of counts received by each bin in a flat field (including both bin size variation and crystal curvature effects). The detector calibration tables are pointed to by the logical names : calfil1, calfil2, calfil3, calfil4. {\bf D. Degrouping of data.} The spectral data contained in the BDA file are grouped within a spectrum according to a grouping plan chosen from one of the pre-set grouping plans hardwired into the BCS microcomputer or entered from ground control prior to taking data. The grouping plan determines how the data in the physical detector bins are combined on the spacecraft to give the spectrum samples. The pre-set grouping plans consist simply of one bin per sample or two bins per sample for all the samples in a given channel (or no data for the channel). However, more complex grouping plans may be entered by ground control. The default is to pass the data to the BSD file with the same bin grouping as in the BDA file. However, the user may choose to degroup the data in the BSD file down to physical bins or to resample the data on unit bin boundaries. If the spectra within an accumulation are corrected for relative pointing variation then the data will automatically be resampled on unit bin boundaries. {\bf E. Deadtime correction.} There are deadtime effects associated with the detector electronics which result in proportionally less events being detected at high count rates than at low count rates. A correction factor can be calculated from the data contained in the DP synchronous part of the BDA file and optionally applied to the individual spectra before accumulation. {\bf F. Warnings.} Various warning messages may be output by MKBSD giving the user notice of discrepancies in the data or processing and actions taken. MKBSD will continue execution as best as it can. {\bf G. Command summary.} H : HELP Gives a brief description of function of command. Enter Help Followed by code i.e. ''H CK'' . F : CHANGE FILE ID This allows the user to specify a new BDA file. Enter the new BDA file ID as : ''DDMMYY.HHMM'' OR ''[DIRECTORY]BDADDMMYY.HHMM'' The BSD file is derived from this by appending the file ID to ''BSD''. B : CHANGE START TIME OF PERIOD OF INTEREST This allows the user to enter a new start time for the period of interest. Enter time as integer values on a single line separated by spaces or commas in the order : HOURS MINUTES SECONDS MILLISECS DAY MONTH YEAR. The program attempts to supply defaults if values are omitted. When a new BDA file is specified, the start time defaults to the time of the first spectrum in the file. E : CHANGE STOP TIME OF PERIOD OF INTEREST This allows the user to enter a new end time for the period of interest. Enter time as integer values on a single line separated by spaces or commas in the order : HOURS MINUTES SECONDS MILLISECS DAY MONTH YEAR. The program attempts to supply defaults if values are omitted. When a new BDA file is specified, the end time defaults to the end of the last spectrum in the file. S : CHANGE MINIMUM NUMBER OF SPECTRA This allows the user to define a minimum number of spectra that will be produced. The accumulation of spectra will not cease until both the minimum spectra requirement and the end time of the period of interest criteria have been met. C : CHANGE CHANNELS FOR PROCESSING This allows the user to change the channels processed. The user should enter the channel numbers required as integer values on the same line separated by spaces or commas. The BCS channels are : | Channel 1 = Fe XXVI Channel 2 = Fe XXV Channel 3 = Ca XIX Channel 4 = S XV | A : CHANGE ACCUMULATION TIME This allows the user to change the accumulation time of the spectra. The time in seconds should be entered as a real or integer value. Timing starts from the time of the first spectrum used in the accumulation. The spectra will be accumulated until the elapsed time (i.e start time of current spectrum - time of first spectrum) exceeds the specified accumulation time and the total counts in the count channel exceed the count level criterion. CL : CHANGE CHANNEL COUNT LEVEL REQUIRED This allows the user to specify a minimum number of total counts which must be reached in a particular channel during an accumulation. The accumulation will stop when this level is exceeded and the elapsed time exceeds the accumulation time criterion. CC : CHANGE CHANNEL FOR COUNT LEVEL REQUIREMENT This allows the user to change the channel used for the count level requirement. See command CL. HD : DISPLAY BDA FILE INFORMATION This command displays information contained in the header, quasi-static and optional data header sections of the current BDA file. The amount of information given depends on the verbosity level. The verbosity level can be changed using the V command. SU : PRINT SUMMARY OF SPECTRA. This command prints out information contained in the road-map and optional data sections of the current BDA file. The amount of information given depends on the verbosity level. The verbosity level can be changed using the V command. H : HELP FACILITY Typing ''H'' followed by the appropriate code displays some information on the command. R : READ NEW CONTROL FILE This allows the user to read a control file to supply default parameter values and options for MKBSD. Q : QUIT PROGRAM This allows the user to save the parameter and option settings in a control file before terminating execution of the program. V : PRODUCE VERBOSE OUTPUT This allows the user to specify the level of print-out produced by the program. The minimum level outputs relevant information about the accumulated spectra. The full level also outputs information about the individual spectra within the accumulations. The debug level outputs most of the information available to the program. EX : EXIT INTERACTIVE SESSION AND PROCEED This command exits the interactive session checking that the BDA and BSD files are valid and closing any files opened during the session. The values of the control file parameters and options may be saved in a control file if desired. The program then continues operation without further user supervision. FO : ENTER FLARE OFFSET This allows the user to enter a value for the flare offset. The value should be entered in the form of latitude and longitude in arcmins on the solar disk. The values should be entered in real or integer format on the same line separated by spaces or a comma. These are not used, at present, by MKBSD but are passed on to the spectral data (BSD) file. CK : CHECK PARAMETERS This command uses the header and road-map sections of the BDA file to check that the parameter and option values are sensible. Using the road-map section the program performs a dummy run of the spectra accumulations, displaying information on the spectra that will be produced. O : DISPLAY OPTION SETTINGS AND CODES This displays the current settings of the options and the codes for changing them. The codes may also be used from the main menu display. DC : TOGGLE DEADTIME CORRECTION This changes a flag indicating whether or not a deadtime correction should be applied to the data. CV : TOGGLE DETECTOR NON-LINEARITY CORRECTION This changes a flag indicating whether or not corrections for non-linear dispersion (crystal curvature) and non-uniform bin size are applied to the data. SE : TOGGLE STATISTICAL ERRORS This changes a flag indicating whether or not the statistical errors are written to the BSD file. PC : ENTER RELATIVE POINTING CORRECTION OPTION NOT CURRENTLY IMPLEMENTED This allows the user to specify whether of not individual BDA spectra are corrected for relative pointing offsets when the pointing variation exceeds a specified limit. The user will be prompted to specify whether the wavelength range used in the accumulated spectra is the union or intersection of the wavelength ranges of the individual spectra. {\hsize=8 truein | 0 = NO RELATIVE POINTING CORRECTION 1 = RELATIVE POINTING CORRECTION USING OVERLAPPING WAVELENGTH RANGE 2 = RELATIVE POINTING CORRECTION USING FULL WAVELENGTH RANGE | } The user will also be prompted to specify a pointing variation threshold for the accumulated spectra below which the pointing will not be corrected. A negative value for the pointing variation threshold will result in all accumulated BSD spectra being corrected for the relative pointing variation. A pointing variation of one arcmin will produce a shift in the spectra, in units of detector bins, of approximately : | 6.5 bins for channel 1, 4.1 bins for channel 2, 11.7 bins for channel 3, 6.4 bins for channel 4. | DG : DEGROUP DATA This command changes a flag indicating whether or not the spectra are degrouped into single bins in the accumulated BSD spectra. Note that the spectra will always be degrouped into unit bins if the BDA spectra are corrected for relative pointing variation. | 0 = BSD spectra not degrouped. 1 = BSD spectra degrouped into physical (non-uniform) bins. 2 = BSD spectra degrouped into unit (uniform) bins. | AC : ABSOLUTE POINTING AND FLARE CORRECTION NOT CURRENTLY IMPLEMENTED This changes a flag indicating whether or not the accumulated BSD spectra are corrected for absolute pointing offset. The absolute flare offset is also corrected for if a value for the flare offset has been given. \endverbatim \bye