\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

