Cassini MAG
Data Processing Software:
CAL02 User Guide
Prepared by
Joyce Wolf, JPL
May 13, 2005
6.1 Sample CAL02 Console Window
6.3 Calibrated FGM Output File Description
6.3.1 Calibrated FGM Output File Format
6.3.2 FGMStatus Bit Field Structure
6.4 Calibrated VHM Output File Description
6.4.1 Calibrated VHM Output File Format
6.4.2 VHMStatus Bit Field Structure
6.5 Sample Calibrated VHM Text Header File
8.1 CAL02 Source Code File Descriptions
This document is a guide to CAL02, the data processing application that calibrates magnetic field vector measurements obtained by the FGM (Fluxgate Magnetometer) and VHM (Vector Helium Magnetometer) sensors of the MAG experiment on Cassini. This document explains what CAL02 does, how to install it, and how to use it. Examples are provided.
This document is included in the DOCUMENT/CAL02_GUIDE directory of each MAG Archive volume. See Section 4.6 of reference below.
MAG Standard Data Products Archive Volume Software Interface Specification, Document IO-AR-020, N. Achilleos, S. Kellock, A. Hitchman and S. Joy, 2004 (revised 2005).
CAL02 reads uncalibrated magnetic field vectors from FGM or VHM data files. These data files are Standard Products in the MAG Archive REDR (Reformatted Experimenter Data Record) data set, as described in Sec. 4.5 of the reference. The data files are of the type known as "UCLA Flatfiles"; they are binary files consisting of fixed length records and have accompanying descriptive text header files (Sec. 4.5.2 of reference). Each record of an FGM or VHM data file contains time (Spacecraft Clock), X, Y and Z components of the uncalibrated field vector, and two status words (Tables 24 and 25 of reference). The second status word includes either a 2-bit field that specifies the range of the FGM or a 1-bit field that specifies the range of the VHM.
The calibration process consists of subtracting zero levels, multiplying by an Orthogonality-Sensitivity matrix, rotating from the sensor coordinate system to the spacecraft coordinate system, and subtracting internal spacecraft field. The zero levels and Orthogonality-Sensitivity matrices are different for each range of the sensors; the FGM has four ranges and the VHM has two. (See Sec. 5.2.6 of the reference.) All the calibration values (zero levels, O/S matrices, rotation matrix, and spacecraft field) may vary with time. The calibration values are stored in calibration files, which are Standard Products in the CALIB directory described in Sec. 4.3 and Table 11 of the reference. For the contents and format of the FGM and VHM calibration files, see Tables 22 and 23 of the reference.
CAL02 writes the calibrated magnetic field vectors into output files of the same type as the input files. Each record of the output file contains time (unchanged from input value), X, Y and Z components of the calibrated field vector in the spacecraft coordinate system, and two status words. The first status word is not changed, but some bit fields of the second status word are updated. The output flatfile header file (the accompanying text file) contains added information regarding the calibration processing.
CAL02 also generates a report file that lists the names of the input file and the calibration file, indications of range changes encountered during the processing, and the number of data records calibrated.
CAL02 was developed in Microsoft Visual C/C++, running under Windows NT, according to the requirements specified by the MAG Principal Investigator. For MS Windows systems, the application file CAL02.EXE may simply be copied into a convenient directory. Alternatively, one may open MS Visual C/C++, create a new project, add to the project the CAL02 source code files, and compile and build a new executable. See Table 1 in Appendix of this document for description of source code files.
CAL02 could with some changes be compiled and run on other operating systems. It does not explicitly call any system-dependent functions but uses flatfile functions available in the UCLA source code files FF_IGPP and TIME_IGPP. The UCLA source code is designed to be used with Unix, MacOS, and Linux, in addition to Windows, by means of appropriate DEFINE statements.
CAL02 is a Win32 Console Application. This means that when CAL02 is launched, by double-clicking on the application icon or a shortcut, a DOS-type window will appear, in which the user types answers to various questions. (Console applications may also be launched by opening the Command Prompt window and typing the name of the application. This is convenient because the properties of the Command Window can be customized.)
The user is asked for the name of the input data file, whether the data is FGM or VHM, and whether byte-swapping needs to be applied. (Byte swapping is required for compatibility between PC and Unix systems; standard uncalibrated data files use Unix representation, so byte swapping is required for the input data file.) Next, the user is asked for the name of the output data file; the default is the name of the input data file with the suffix _C. Note that the filenames required are the flatfile names without the extensions ffh or ffd. The user then chooses whether byte-swapping is to be applied to the output data file. Then the user is asked for the name of the file in which the report will be written, and may simply press Enter if the default is satisfactory. After notifying the user that the files have been successfully opened, CAL02 asks for its last input, the name of the calibration flatfile. After the processing is completed, CAL02 displays the number of records written and the number of invalid data records.
The report file includes the user inputs, indications of range changes encountered during the processing of the data records, and the number of data records calibrated and not calibrated.
When CAL02 is run interactively as described above, the user will be given the choice of re-entering names of files that cannot be opened. If batch processing is being used, that is, if the standard input has been assigned to a file instead of a device, a file that cannot be opened will cause CAL02 to exit after writing an error message.
6.1 Sample CAL02 Console Window
C:\cassini\y99archive>cal02
Cal02 Ver 041206
Input FlatFile:
Enter full flatfile name: 99238_mrdcd_hkvhmc
Cannot open 99238_mrdcd_hkvhmc
Enter 1 to try again, 0 to exit: 1
Enter Input Flatfile name: 99238_mrdcd_hkvhmn
Enter 0 if input is FGM, 1 if VHM: 1
Enter 1 to SWAP BYTES on INPUT flatfile, 0 not to swap: 1
Output FlatFile,Default is 99238_mrdcd_hkvhmn_C
Enter full flatfile name:
Enter 1 to SWAP BYTES on OUTPUT flatfile, 0 not to swap: 1
Default Report File: 99238_mrdcd_hkvhmn_C_Rpt.txt
Enter Report filename:
Opened Report File 99238_mrdcd_hkvhmn_C_Rpt.txt
Opened Input Flatfile 99238_mrdcd_hkvhmn
NCOLS 6 RECL 28
Enter Calibration Flatfile name: vhm_esb05_cal
Data Recs Written = 10714
Invalid Data Recs Not Calibrated = 0
Flatfiles Closed
Press Enter to Exit
CAL02 ver041206 Report
Opened Input Flatfile: 99238_mrdcd_hkvhmn
Sensor: VHM
Input Byte Swapping is ON
Opened Output Flatfile 99238_mrdcd_hkvhmn_C
Output Byte Swapping is ON
Calibration File = vhm_esb05_cal.ffd
Rec 1, Range 0
Rec 10714, Range 0
Data Recs Written = 10714
Data Recs Calibrated = 10714
Invalid Data Recs Not Calibrated = 0
Flatfiles Closed
End of CAL02 Report.
6.3 Calibrated FGM Output File Description
The calibrated FGM output file has the same structure as the input FGM data file; that is, each record of the binary data file contains time, XYZ components of the field, and the two status words MAGStatus and FGMStatus. In the following file structure tables, Type T refers to UCLA Time (8-byte double-precision representation of SCLK count), Type R means 4-byte float, and Type I means 4-byte integer. As with all flatfiles, the file structure information is included in the accompanying ASCII text header file, along with other information about the data.
6.3.1 Calibrated FGM Output File Format
|
Column Name |
Data Type |
Start Byte |
Description |
|
001 SCLK(1958) |
T |
0 |
SCLK count relative to epoch Jan 1 1958 00:00:00 |
|
002 BX_FGM_SC |
R |
8 |
Calibrated magnetic field component along S/C X axis in nT |
|
003 BY_FGM_SC |
R |
12 |
Calibrated magnetic field component along S/C Y axis in nT |
|
004 BZ_FGM_SC |
R |
16 |
Calibrated magnetic field component along S/C Z axis in nT |
|
005 MAGStatus |
I |
20 |
Array of bits containing information about active MAG modes, packet type, etc. |
|
006 FGMStatus |
I |
24 |
Array of bits containing status information about FGM |
The first status word, MAGStatus, is simply copied from the input FGM data file by CAL02. Information in MAGStatus includes type of packet, fixed or running averaging, sensor power flags, exponent of number of samples in average, and other instrument status flags. A description of MAGStatus bit field structure is available elsewhere. The following table describes the second status word, FGMStatus.
6.3.2 FGMStatus Bit Field Structure
(Bit 31 = most significant bit)
|
Range |
FGM Range (0,1,2,3) |
31-30 |
2 |
|
IFCFlag |
1 = IFC Flag On |
29 |
1 |
|
Autorange |
1 = AutoRange On |
28 |
1 |
|
TimeStatus |
Time quality status flag |
27-24 |
4 |
|
Sparebyte |
Spare bits |
23-16 |
8 |
|
CalibID |
Calibration ID = Calibration File Record Number (mod 256) |
15-8 |
8 |
|
CoordID |
Coordinate System ID = 03 Hex (Spacecraft) |
7-0 |
8 |
6.4 Calibrated VHM Output File Description
The calibrated VHM output file has the same structure as the input VHM data file; that is, each record of the binary data file contains time, XYZ components of the field, and the two status words MAGStatus and VHMStatus. In the following file structure tables, Type T refers to UCLA Time (8-byte double-precision representation of SCLK count), Type R means 4-byte float, and Type I means 4-byte integer. As with all flatfiles, the file structure information is included in the accompanying ASCII text header file, along with other information about the data.
6.4.1 Calibrated VHM Output File Format
|
Column Name |
Data Type |
Start Byte |
Description |
|
001 SCLK(1958) |
T |
0 |
SCLK count relative to epoch Jan 1 1958 00:00:00 |
|
002 BX_VHM_SC |
R |
8 |
Calibrated magnetic field component along S/C X axis in nT |
|
003 BY_VHM_SC |
R |
12 |
Calibrated magnetic field component along S/C Y axis in nT |
|
004 BZ_VHM_SC |
R |
16 |
Calibrated magnetic field component along S/C Z axis in nT |
|
005 MAGStatus |
I |
20 |
Array of bits containing information about active MAG modes, packet type, etc. |
|
006 VHMStatus |
I |
24 |
Array of bits containing status information about VHM |
The first status word, MAGStatus, is simply copied by CAL02 from the VHM input data file to the calibrated VHM output file. (See preceding description of the calibrated FGM output file.) The following table describes the structure of the second status word, VHMStatus.
6.4.2 VHMStatus Bit Field Structure
(Bit 31 = most significant bit)
|
Range |
VHM Range (0,1) |
31 |
1 |
|
TimeStatus |
Time quality status flag |
30-27 |
4 |
|
Sparebits |
Spare bits |
26-24 |
3 |
|
DigStatus |
VHM Digital Status Word |
23-16 |
8 |
|
CalibId |
Calibration ID = Calibration File Record Number (mod 256) |
15-8 |
8 |
|
CoordId |
Coordinate System ID = 03 Hex (Spacecraft) |
7-0 |
8 |
6.5 Sample Calibrated VHM Text Header File
DATA =
99238_mrdcd_hkvhmn_C.ffd
CDATE = 2005 132 MAY 12 09:50:07
RECL = 28
NCOLS = 6
NROWS = 10714
OPSYS = WINDOWS
EPOCH = Y1958
# NAME UNITS SOURCE TYPE LOC
001 SCLK(1958)COUNT CA_HK_RG_VHM T 0
002 X_VHM nT CA_HK_RG_VHM R 8
003 Y_VHM nT CA_HK_RG_VHM R 12
004 Z_VHM nT CA_HK_RG_VHM R 16
005 MAGStatus b CA_HK_RG_VHM I 20
006 VHMStatus b CA_HK_RG_VHM I 24
ABSTRACT
FIRST TIME = 99 238 AUG 26 00:07:16.761
LAST TIME = 99 239 AUG 27 00:07:14.058
OWNER = MAG_TEAM
MISSING DATA FLAG = 1.00000E+034
AVERAGE INTERVAL = 00:00:00.064
#########
CASSINI ABSTRACT
#########
INPUT FILE: 99238_mrdcd
FLAT FILE MAKER: caspre2ff v1.5 SUN
COMPILATION DATE : 03/10/05-15:05:59
wTime0 and MCI determine dt between vectors except for channel data
Use Configuration File : F --- Use IFC Table : F
User defined wtime0 : F --- User defined MCI : F
Default wTime0 : 125.00000
Default MCI : 62.47700
Time for channel data is extracted from the Tertiary data
SCET (Jan 1, 1958 00:00:00) 99 238 AUG 26 00:00:20.977 1314316820.977
SCLK (Jan 1, 1958 00:00:00) 99 238 AUG 26 00:07:13.105 1314317233.105
Flatfile times are SCLK based t0 = Jan 1 1958 00:00:00
TIMEOFFSET 0.000000 SCLKDIFFFLAT 0.000000
CASSINI SCLK (1958)= FLATFILE (1966)+ SCLKDIFFFLAT
Start/Stop times are approximate SCLK Convertions
#########
Calibration: Cal02 v041206
Input Flatfile = 99238_mrdcd_hkvhmn
Sensor = VHM
Calibration Source File = vhm_esb05_cal.ffd
Output Byte Swapping was ON
Number of records not calibrated = 0
Output Times are left unchanged
END
Uncalibrated magnetic field vectors are calibrated according to the following algorithm:
B = T * OS(r) * (U - Z(r)) - S,
where
B = calibrated field vector in nT,
U = uncalibrated field vector from FGM or VHM in engineering units,
Z(r) = range-dependent zero-level (offset) vector,
OS(r) = range-dependent Orthogonality-Sensitivity matrix,
T = transformation matrix from sensor (FGM or VHM) coordinate system to Cassini coordinate system,
S = spacecraft field vector,
r = 0, 1, 2, or 3 for the FGM, and,
r = 0 or 1 for the VHM.
Notes
1. r is given by the two most significant bits of FGMStatus in the uncalibrated FGM flatfile record or the most significant bit of VHMStatus in the uncalibrated VHM flatfile record.
2. Z(r), OS(r), T, and S are from the record in the FGM or VHM calibration file whose start and stop times correspond to the time of the uncalibrated vector. (Times in the calibration files are also in SCLK counts.)
CAL02 uses the UCLA routine ff_open to open the input FGM or VHM flatfile and to open a new output flatfile with the same number of columns and record length as the input flatfile. Column descriptor records are copied from the input flatfile header file to the output flatfile header file.
Each input data record is read, optionally byte-swapped, and if valid, calibrated. Two validity checks are performed in this version: (1) Is the sensor power on? (2) Are the component values within scale for the range?
If the calibration file is not already open, the user is queried for the name of the calibration file, the calibration file is opened, and the first record is read. If the data time is later than the stop time of the calibration record, a new calibration record is read. If there are no more calibration records in the calibration file, a warning is written to the report file, and the data continues to be processed with the values from the last calibration record. See Tables 22 and 23 of the reference for the format of the FGM and VHM calibration files.
The range information is obtained from either the first two bits of FGMStatus or the first bit of VHMStatus. The calibration is then performed on the data vector as follows: (1) Zero levels for the appropriate range are subtracted from the vector components. Zero levels for Range 0, which may vary from day to day, are calculated by interpolating between the previous and current calibration records. (2) The resulting vector is multiplied by the Orthogonality-Sensitivity matrix for the appropriate range. (3) The resulting vector is then multiplied by the FGM-to-Spacecraft or VHM-to-Spacecraft coordinate transformation matrix. (4) The spacecraft field is subtracted from the resulting vector.
If the data vector passed the validity checks and was calibrated, the 8 bits of the CalibID subfield of the sensor status word (FGMStatus or VHMStatus) are changed to the calibration record number (mod 256). If the data vector was not calibrated, CalibID is not changed. The time value is not changed. After optional byte-swapping, the data record is written to the output flatfile.
When all the data records have been processed, the text header records in the Abstract are copied from the input header file to the output header file. FIRST_TIME and LAST_TIME are not copied from the input header file but are the actual first time and last time of the output data file. Processing information from CAL02 is added to the Abstract section of the output header file. Finally, the UCLA routine ff_close is called to update the number of records in the flatfile and to close the files.
8.1 CAL02 Source Code File Descriptions
|
Description |
|
|
CAL02.EXE |
Application |
|
CAL02.cpp |
C++ Source, Main Program |
|
CalFunc02.cpp |
C++ Source, Calibration Functions |
|
CalFunc02.h |
C Header File, Calibration Function Declarations |
|
cal_mag.h |
C Header File, Calibration File type definitions |
|
ff_igpp.c |
C Source, UCLA Flatfile procedures |
|
ff_igpp.h |
C Header File, UCLA Flatfile Typedefs |
|
time_igpp.c |
C Source, UCLA Time Functions |
|
time_igpp.h |
C Header File, UCLA Time Typedefs |
|
time_igppp.h |
C Header File, UCLA Time defintions |