Document title: Source code documentation for NDADS DE PWI data Project: DE NDADS Datatype: PWI Super-EID: DOCUMENT There may be other documents also identified by this super-EID. NDADS filename: DOCUMENT_PWI_SSCDOC.SFD TRF entry B46588.txt in NSSDC's controlled digital document library. Feb. 1998. Document text follows: ---------------------- TYPE_OF_FILE_NAME: PWI SOURCE_CODE_ORGANIZATION: The source code file consists of three files: PWI.FOR, UTIL.FOR, and LIBR.FOR. The contents of each of these files are listed below. All functions and subroutines contained in each file are ordered alphabetically. SOURCE CODE FILE CONTENTS: file name purpose functions and/or subroutines PWI.FOR specify type This is the main program. of data and This program will prompt the time interval user for the desired time desired by interval and type of data the user and will call UTIL.FOR and LIBR.FOR for all subroutines and functions necessary to extract and calibrate the PWI data. UTIL.FOR contains the I4BITS,I4FLIP,OPNDAT, functions used OPNUSE by the PWI software which utilize intrinsic, nonstandard functions LIBR.FOR contains all CALGAI,CALLFC,CALMAG,CALPHA, subroutines CALSDB,CALSFC,DOIT,GETB,GETBW, and functions GETDAT,GETDC,GETELN,GETFRQ, (all written GETLFC,GETNAD,GETORB,GETPER, in standard GETSFR,GETSTP,GETSTS,SINFIT, FORTRAN 77) TIMADD,TIMCMP,TIMDIF,TIMNRM, necessary to TIMSTR,VCROSS,VINNER extract and calibrate PWI data MAIN PROGRAM DESCRIPTION: PWI will prompt the user for the type of data desired: amplitude data from the Step Frequency Receiver (SFR), amplitude data from the Low Frequency Correlator (LFC), SFR phase data, LFC phase data, or DC electric field data. In addition, PWI will prompt the user for the selected time interval and the full file specification for the output file to be written. The program will call the DOIT subroutine to open the input and the user-specified output files, and will call one of four subroutines (CALPHA, GETDC, GETLFC, or GETSFR) to extract and calibrate the desired electric, magnetic or phase data. Output will be to the user-designated file and will contain an array of calibrated electric or magnetic field values, or computed phase angles between signals from two antennas and the associated time tags and orbit parameters. Link with UTIL and LIBR. This program will also caution the user that PWI has the potential to produce large amounts of data. A selected time interval of 40 minutes for SFR amplitude data will produce an output file of 2.6 MB. Input parameters should be chosen carefully. FUNCTIONS CONTAINED IN UTIL.FOR: The following functions are contained in UTIL.FOR. They utilize nonstandard intrinsic functions and keywords which may not be provided by the user's system. If these intrinsic functions and keywords are not available on the user's system, the user must provide these functions and keywords to fit the following specifications. I4BITS This function will extract a bit field from a given four byte integer. name type description input arguments: NUMBER INT the integer containing the bit field BITS INT the number of bits in the field OFFSET INT the offset (0 relative) from the least significant bit (0-31) returns: I4BITS INT the positive integer value contained in the specified bit field This function uses the following nonstandard, intrinsic functions, which are described below in SOURCE_CODE_OPERATION: IAND(integer,mask) and ISHFT(integer, left-shift). calling sequence: I4BITS(NUMBER,BITS,OFFSET) I4FLIP This function will look at the passed data record and see if the byte order needs to be changed on this system. If it does, it will swap the order of the bytes and check the record again to see if the byte reordering was successful. name type description input argument: RECORD INT DE PWI data record read from the optical disk output argument RECORD INT the DE PWI data record with the bytes reordered, as necessary returns: I4FLIP INT a status return value. A value of 1 indicates successful completion, a value of 0 indicates an error. This function uses the following nonstandard, intrinsic functions, which are described below in SOURCE_CODE_OPERATION: IAND(integer,mask); IOR(integer1,integer2); and ISHFT(integer,left-shift). calling sequence: I4FLIP(RECORD) OPNDAT This function will open a specified DE PWI data file and return the FORTRAN unit number to the calling procedure. name type description input argument: FILNAM CHAR name of the file to be opened returns: OPNDAT INT the FORTRAN unit number of the opened file This function uses the following nonstandard keywords in the OPEN statement (necessary for compilation under VMS FORTRAN): SHARED; READONLY, RECORDTYPE = 'FIXED'. If the user is not running under a VMS-operating system, it will be necessary for the user to determine the appropriate keywords for the OPEN statement. These keywords are fully described under SOURCE_CODE_OPERATION below. In addition, it may be necessary for the user to change the unit number used in this function if it conflicts with a unit number predefined by the user's FORTRAN compiler. calling sequence: OPNDAT(FILNAM) OPNUSE This function will open a user-specified output file and return the FORTRAN unit number to the calling procedure. name type description input argument: FILNAM CHAR the name of the file to be opened returns: OPNUSE INT the FORTRAN unit number of the opened file It may be necessary for the user to change the unit number used in this function if it conflicts with a unit number predefined by the user's FORTRAN compiler. calling sequence: OPNUSE(FILNAM) FUNCTIONS AND SUBROUTINES CONTAINED IN LIBR.FOR: The functions and subroutines listed below are contained in LIBR.FOR in alphabetical order. All of these functions and subroutines have been written in standard FORTRAN 77. Complete descriptions of these functions and subroutines are included with the source code. GETBW This function will return the bandwidth corresponding to a given mode. name type description input arguments: CHAN INT the correlator or receiver channel (0-5), as follows: SFR Channel 0, SFR Channel 1, SFR Channel 2, SFR Channel 3, LFC High Band (4), and LFC Low Band (5). STEP INT the step or channel in the given mode as indicated in the instrument status data: for the SFR (0-31 allowed); for the LFC (0- 3 allowed) returns: CALBW DP the bandwidth of the givenmode expressed in hertz calling sequence: CALBW(CHAN,STEP) CALELN This function will return the AC electrical length of the given antenna. name type description input argument: ANT INT the integer value (0-3) of a given antenna: Es (0), Ez (1), Ex (2) and Magnetic (3) returns: CALELN DP the AC electrical length of the given antenna, expressed in meters. The electrical length of the magnetic antennas are set to 1.0m for convenience. calling sequence: CALELN(ANT) CALFRQ This function will return the frequency corresponding to a given correlator and step or channel. name type description input arguments: CHAN INT the correlator or receiver channel (0-5), as follows: SFR Channel 0, SFR Channel 1, SFR Channel 2, SFR Channel 3, LFC High Band (4), and LFC Low Band (5). STEP INT the step or channel in the given mode as indicated in the instrument status data: for the SFR (0-31 allowed); for the LFC (0- 3 allowed) returns: CALFRQ DP the frequency of the given mode, expressed in hertz calling sequence: CALFRQ(CHAN,STEP) CALGAI This function will correct the given data value for the current gain setting as determined by the current mode of the instrument. name type description input arguments: CHAN INT channel (0,1,2,3) corresponding to the four SFR channels OFFSET INT the offset of the byte in the word, counting from zero at the most significant byte (0-3) STATUS INT the array of 27 instrument status words returned by GETSTS VALUE DP data value to be corrected for the gain setting returns: CALGAI DP the data value corrected for the gain setting calling sequence: CALGAI(CHAN,OFFSET,STATUS,VALUE) CALLFC This function will calibrate one LFC data value and return the calibrated data value in volts. name type description input arguments: BAND INT the LFC band, as follows: 0, LFC High Band; 1, LFC Low Band CHAN INT the channel in each band (0-3 allowed) VALUE INT the uncalibrated data value (0-255 allowed) returns: CALLFC DP the calibrated LFC data value expressed in volts calling sequence: CALLFC(BAND,CHAN,VALUE) CALMAG This function will convert the calibrated amplitude values (expressed in volts) to magnetic field strength (expressed in gammas). name type description input arguments: MODE INT the instrument mode (0- 5), as follows: SFR Channel 0, SFR Channel 1, SFR Channel 2, SFR Channel 3, LFC High Band (4), LFC Low Band (5). STEP INT the step or channel in the given mode as indicated in the instrument status data: for the SFR (0-31 allowed); for the LFC (0- 3 allowed) VALUE DP the amplitude data value expressed in volts returns: CALMAG DP the calibrated magnetic a field strength expressed in gammas calling sequence: CALMAG(MODE,STEP,VALUE) CALPHA This function will return the SFC phase correction, expressed in degrees, for the specified point in the tables. name type description input arguments: CHAN INT channel (0,1,2,3) corresponding to the four SFR channels I INT an indication of the desired SFR-B amplitude from the table J INT an indication of the desired SFR-A amplitude from the table K INT an indication of the desired step value from the table returns: CALPHA DP the phase correction expressed in degrees calling sequence: CALPHA(CHAN,I,J,K) CALSDB This function will calibrate one SFR data point and return the calibrated data value from the specified receiver in dBs. name type description input arguments: RECV INT the receiver with which the data was taken, as follows: 0 (SFR A) and 1 (SFR B) CHAN INT the channel (0,1,2,3) corresponding to the four SFR channels VALUE INT the uncalibrated data value (0-255 allowed) returns: CALSDB INT the calibrated SFR data value expressed in dBs calling sequence: CALSDB(RECV,CHAN,VALUE) CALSFR This function will calibrate one SFR data point and return the calibrated data value in volts. name type description input arguments: CHAN INT the SFR channel (0-3), as follows: Channel 0, Channel 1, Channel 2, Channel 3 VALUE INT the uncalibrated data value (0-255 allowed) returns: CALSFR DP the calibrated SFR data value expressed in volts calling sequence: CALSFR(CHAN,VALUE) DOIT This subroutine will process the requested DE PWI data and write a user-specified output file containing the calibrated data. name type description input arguments: USEBEG INT an integer array containing the start time of the desired interval, as follows: the date in the form YYDDD; and the millisecond of the day (0-86399999) USEEND INT an integer array containing the stop time of the desired interval, as follows: the date in the form YYDDD; and the millisecond of the day (0-86399999) TYPE INT the type of data desired SFR amplitudes (0); LFC amplitudes (1); SFR phase (2); LFC phase (3); and DC electric fields (4) RECV INT the desired receiver for SFR and LFC data, as follows: Receiver A (0) and Receiver B (1) OUTFIL CHAR the name of the output file designated by the user calling sequence: DOIT(USEBEG,USEEND,TYPE,RECV,OUTFIL) GETB This subroutine will calculate the local magnetic field using the MAGSAT model. The code was originally derived from the ONEMAG program described in document NSSDC 72- 12 from the National Space Science Data Center. The code was modified to use the MAGSAT coefficients by Dr. Daniel R. Weimer in February 1984. The secular variation coefficients are from the IGRF 1980 model. name type description input arguments: DATE INT the date expressed as YYDDD POS DP the GEI satellite position vector expressed in km LAT DP the geocentric latitude of the spacecraft expressed in degrees LONG DP the east longitude of the spacecraft expressed in degrees output argument: B DP the rectangular GEI components of the local magnetic field expressed in gauss calling sequence: GETB(DATE,POS,LAT,LONG,B) GETDAT This subroutine will read the timestamp from the DE PWI data record and return it in an array of integer numbers. name type description input argument: RECORD INT DE PWI data record output argument: TIME INT the timestamp, an array of eight integer values corresponding to the date in YYDDD, milliseconds of day (0-86399999), year, day of year (January 1 = 1), hour (0-23), minute (0-59), second (0-59) and millisecond (0-999) calling sequence: GETDAT(RECORD, TIME) GETDC This subroutine will read the DC electric field data from a DE PWI record, calibrate it, remove the effects of the spacecraft spin, and return the DC electric field data values in arrays of double precision numbers. name type description input arguments: RECORD INT a DE PWI data record output arguments: EPER DP the component of the DC electric field measured in the spin plane that is perpendicular to the projection of the local magnetic field on the spin plane, expressed in volts/meter EPAR DP the component of the DC electric field measured in the spin plane that is parallel to the projection of the local magnetic field on the spin plane, expressed in volts/meter CHI DP an indication of the quality of the data taken from the Ex antenna EZAVE DP the average DC electric field measured by the Ez antenna, expressed in volts/meter SDEV DP the standard deviation of the electric field measured by the Ez antenna calling sequence: GETDC(RECORD,EPER,EPAR,CHI,EZAVE,SDEV) GETLFC This subroutine will read the LFC data from the DE PWI record, calibrate it, and return it in arrays of double precision numbers. name type description input arguments: RECORD INT a DE PWI data record RECV INT the desired LFC receiver (0,1), as follows: Receiver A (0) and Receiver B (1) output arguments: ANT INT the antenna (0-3) connected to the designated LFC receiver, as follows: Es (0), Ez (1), Ex (2) and search coil H (3) LFCHI DP the calibrated LFC high band data expressed in the appropriate units of spectral density LFCLO DP the calibrated LFC low band data expressed in the appropriate units of spectral density FRQHI DP the frequency of the LFC high band data in the LFCHI array expressed in hertz FRQLO DP the frequency of the LFC low band data in the LFCLO array expressed in hertz calling sequence: GETLFC(RECORD,CHAN,ANT,LFCHI,LFCLO,FRQHI,FRQLO) GETNAD This subroutine will read the nadir times from the DE PWI data record and return the number found and the nadir times in an array of integer numbers. name type description input argument: RECORD INT DE PWI data record output arguments: NUM INT the number of nadir times contained in the record TIME INT integer array for each nadir time, containing the date in the form YYDDD and milliseconds of day (0-86399999) calling sequence: GETNAD(RECORD,NUM,TIME) GETORB This subroutine will read the orbit data from the DE PWI data record and return it in an array of double precision floating point numbers. A complete description of the orbit data values (ORBIT(36)) is provided in the source code. name type description input argument: RECORD INT a DE PWI data record output argument: ORBIT DP an array of double precision floating point numbers for the orbit data contained in a single DE PWI data record calling sequence: GETORB(RECORD,ORBIT) GETPER This function will calculate the current best estimate of the spin period based on the nadir times returned by GETNAD. This function expects to see all of the DE PWI data records in order to maintain the best possible estimate of the spin period. name type description input argument: RECORD INT a DE PWI data record returns: GETPER INT the spin period expressed in milliseconds calling sequence: GETPER(RECORD) GETPHL This subroutine will read the LFC phase data from the DE PWI data record, calibrate it, and return it in arrays of double precision numbers. name type description input argument: RECORD INT a DE PWI data record output arguments: ANTA INT the antenna (0-3) connected to Receiver A of the Low Frequency Correlator (LFC), as follows: Es (0); Ez (1); Ex (2); and H (3) ANTB INT the antenna (0-3) connected to Receiver B of the Low Frequency Correlator (LFC), as follows: Es (0); Ez (1); Ex (2); and H (3) LFCHI DP the calibrated LFC high band phase data, expressed in degrees LFCLO DP the calibrated LFC low band phase data, expressed in degrees CORHI DP the correlation of the measured LFC high band phase data. A value of -1.0 indicates that the corresponding phase could not be determined. CORLO DP the correlation of the measured LFC low band phase data. A value of -1.0 indicates that the corresponding phase could not be determined. FRQHI DP the frequencies of the data in the LFCHI array, expressed in Hertz FRQLO DP the frequencies of the data in the LFCLO array, expressed in Hertz calling sequence: GETPHL(RECORD,ANTA,ANTB,LFCHI,LFCLO,CORHI,CORLO,FRQHI,FRQLO) GETPHS This subroutine will read the SFR phase data from the DE PWI record, calibrate it, and return it in arrays of double precision numbers. name type description input argument: RECORD INT a DE PWI data record output arguments: ANTA INT the antenna (0-3) connected to Receiver A of the Step Frequency Receiver (SFR), as follows: Es (0); Ez (1); Ex (2); and B (3) ANTB INT the antenna (0-3) connected to Receiver B of the Step Frequency Receiver (SFR), as follows: Es (0); Ez (1); Ex (2); and B (3) SFRPHA DP the calibrated SFR phase data, expressed in degrees CORPHA DP the correlation of the measured SFR phase data FREQ DP the frequencies of the data in the SFRPHA array, expressed in Hertz calling sequence: GETPHS(RECORD,ANTA,ANTB,SFRPHA,CORPHA,FREQ) GETSFR This subroutine will read the SFR data from the DE PWI record, calibrate it, and return it in arrays of double precision numbers. name type description input arguments: RECORD INT a DE PWI data record RECV INT the SFR receiver (0 or 1), as follows: Receiver A (0) or Receiver B (1) output arguments: ANT INT the antenna connected to the designated receiver (0-3), as follows: Es (0), Ez (1), Ex (2) and B (3) SFR DP the calibrated SFR data, four values for each of the 32 frequency steps, expressed in the appropriate units of spectral density FREQ DP the frequencies corresponding to the data in the SFR arrays, expressed in Hertz calling sequence: GETSFR(RECORD,RECV,ANT,SFR,FREQ) GETSTP This function will return the SFR step value corresponding to the specified time and byte offset, taking into account the various modes of the instrument. name type description input arguments: TIME INT the time since the start of the record (0-7), in seconds OFFSET INT the offset of the byte in the word, counting from zero at the most significant byte (0-3 allowed) STATUS INT the array of instrument status words returned by GETSTS returns: GETSTP INT the SFR step value (0-31) calling sequence: GETSTP(TIME,OFFSET,STATUS) GETSTS This subroutine will read the instrument status words from the DE PWI data record and return them in an array of integer numbers. A complete listing of the PWI status words (STATUS(27)) is provided in the source code. name type description input argument: RECORD INT a DE PWI data record output argument: STATUS INT integer array of the 27 status words contained in a single DE PWI data record calling sequence: GETSTS(RECORD,STATUS) PHACAL This subroutine will take the given correlation coefficients and the information about the mode of the instrument and return the calibrated phase and the correlation coefficient. name type description input arguments: SFRFLG INT the correlator from which the data was obtained (0 or 1), as follows: LFC (0); SFR (1) S INT the in-phase correlation coefficient C INT the quadrature-phase correlation coefficient MODE INT the current mode of the instrument (0-2), as follows: Ex/Ez antenna combination (0); Ez/ Magnetic antenna combination (1); and Ex/Magnetic antenna combination (2) CHAN INT the SFR channel (0-3), as follows: Channel 0, Channel 1, Channel 2, Channel 3 STEP INT the SFR step counter as indicated in the instrument status data (0-31 allowed) output arguments: PHASE DP the raw phase derived from the correlation coefficients, expressed in degrees (0.0-360.0) CORR DP the correlation coefficient of the phase measurement (0.0 - SQRT (2.0)) STEP and CHAN are only used if SFRFLG is equal to 1. calling sequence: PHACAL(SFRFLG,S,C,MODE,CHAN,STEP,PHASE,CORR) PHAFIX This function will correct the raw SFR phase for known amplitude and frequency-dependent instrumental effects. name type description input arguments: CHAN INT the SFR channel (0-3), as follows: Channel 0, Channel 1, Channel 2, Channel 3 STEP INT the SFR step counter as indicated in the instrument status data (0-31 allowed) SFRA INT the raw SFR-A amplitude (0-255 allowed) SFRB INT the raw SFR-B amplitude (0-255 allowed) PHASE DP the SFR phase expressed in degrees (0.0-360.0) returns: PHAFIX DP the raw phase corrected for known instrumental effects calling sequence: PHAFIX(CHAN,STEP,SFRA,SFRB,PHASE) SINFIT This subroutine will perform a least-squares fit of the input data to a function of the form: EX(I) = S(1) + S(2) * COS (THETA(I) * COS (S(3)) + S(2) * SIN (THETA(I) * SIN (S(3)) Complete descriptions of the equation, the transformation of the equation, and the coefficients are given in the source code. name type description input arguments: NPTS INT the number of data points passed THETA DP the angular value (in radians) at which the measurement was taken EX DP the value of the measurement output argument: S DP the calculated least- squares coefficients calling sequence: SINFIT(NPTS,THETA,EX,S) TIMADD This subroutine will add the specified number of milliseconds to the supplied time and return the normalized time. name type description input arguments: INTIME INT a two-word integer array containing the input time: the date (in the form YYDDD) and the millisecond of the day (0-86399999) MSEC INT the number of milliseconds to add, in the range (-86400000 - 86400000) output arguments: OUTTIM INT a two-word integer array containing the output time: the date (in the form YYDDD) and the millisecond of the day (0-86399999) IERR INT a status return value. A value of 1 indicates successful completion. A value of 0 indicates an error. calling sequence: TIMADD(INTIME,MSEC,OUTTIM,IERR) TIMCMP This function will compare the two specified times and determine which one is later. name type description input arguments: TIME1 INT a two-word integer array for the first time, in the following form: the date (YYDDD) and the millisecond of the day (0-86399999) TIME2 INT a two-word integer array for the second time, in the following form: the date (YYDDD) and the millisecond of the day (0-86399999) returns: TIMCMP INT an indication of which time is later. A value of 1 indicates that the first time is later; a value of -1 indicates that the second time is later; a value of 0 indicates that the two times are the same. calling sequence: TIMCMP(TIME1,TIME2) TIMDIF This subroutine will calculate the difference between two specified times and returns the difference expressed in days and milliseconds, as well as an indication of which time is later. name type description input arguments: TIME1 INT a two-word integer array for the first time, in the following form: the date (YYDDD) and the millisecond of the day (0-86399999) TIME2 INT a two-word integer array for the second time, in the following form: the date (YYDDD) and the millisecond of the day (0-86399999) output arguments: DIFF INT an integer array of the difference between the two times, as follows: the number of whole days between the two times; the additional milliseconds between the two times; and an indication of which time is later. A value of 1 indicates that the first time is later; a value of -1 indicates that the second time is later; and a value of 0 indicates that the two times are the same. IERR INT a status return value. A value of 1 indicates successful completion; a value of 0 indicates an error. calling sequence: TIMDIF(TIME1,TIME2,DIFF,IERR) TIMNRM This subroutine will convert the given number of milliseconds to normalized time and return it in an array of integer numbers. name type description input argument: MSEC INT millisecond of day (0- 86399999) output argument: TIME INT an integer array of four normalized time values corresponding to the specified millisecond of day: hour (0-23); minute (0-59); second (0-59) and millisecond (0-999) calling sequence: TIMNRM(MSEC,TIME) TIMSTR This subroutine will convert the given number of milliseconds to a normalized time string and return it in a 12-character string. name type description input argument: MSEC INT millisecond of day (0- 86399999) output argument: TIME CHAR normalized time string (HH:MM:SS.MMM) calling sequence: TIMSTR(MSEC,TIME) VCROSS This subroutine will calculate the vector cross product of two vectors supplied by the user. name type description input arguments: A DP the first vector B DP the second vector output argument: C DP the vector cross product of A and B calling sequence: VCROSS(A,B,C) VINNER This function will calculate the vector inner product of two vectors supplied by the user. name type description input arguments: A DP the first vector B DP the second vector returns: VINNER DP the vector inner product of A and B calling sequence: VINNER(A,B) SOURCE_CODE_TRANSFORMATIONS: The software source code included in each archival volume has four main functions: 1) to calibrate LFC (0-100 Hz) electric and magnetic field data; 2) to calibrate SFR (100 Hz - 410 kHz) electric and magnetic field data; 3) to calculate the phase between signals from a given pair of antennas; and 4) to calculate the DC electric field values (1-8 Hz) both parallel and perpendicular to the projection of the ambient magnetic field vector in the spacecraft spin plane. The main program PWI.FOR will utilize the subroutines necessary to do these calibrations depending on the selections which the user will make from the main menu provided by the software. SOURCE_CODE_INPUT_DATA: The program will prompt the user for information on the type of data desired and will create a user-specified output file containing this data. The inputs which the user will be asked to provide are: 1) the type of data desired: SFR amplitude data (100 Hz - 410 kHz); LFC amplitude data (1.8 Hz - 100 Hz); SFR phase data; LFC phase data; or DC electric field data (less than 8 Hz) 2) the start and stop times of the desired data interval in the form: YYDDD HHMMSS YYDDD HHMMSS where YYDDD is the two-digit year and three-digit day number (January 1 = 1) for the start and stop times and HHMMSS is the two-digit hour, minute and second of the start and stop times 3) the full name of the output file to be written The specified time interval will be contained in a primary data file(s) named PWI_YYDDD.DAT, included in each archival volume. For example, data from December 26, 1981 (Day 360) will be found in the file software_PWI_81360.DAT. SOURCE_CODE_OUTPUT_DATA: Depending on the type of data which the user selects from the menu, he/she will generate one of the following types of output data: 1) SFR Amplitude Data (100 Hz - 410 kHz) from Receiver A 2) SFR Amplitude Data (100 Hz - 410 kHz) from Receiver B 3) LFC Amplitude Data (1.8 Hz - 100 Hz) from Receiver A 4) LFC Amplitude Data (1.8 Hz - 100 Hz) from Receiver B 5) SFR Phase Data (100 Hz - 410 kHz) 6) LFC Phase Data (1.8 Hz - 100 Hz) 7) DC Electric Fields (less than 8 Hz) The Step Frequency Receivers (SFR) sample the electric/magnetic fields four times per second for a given frequency value; all four data values are displayed in the output file. The Low Frequency Correlator (LFC) samples the data eight times per second for a given frequency value; all eight data values are displayed in the output file. The SFR and LFC amplitude data output files are ASCII files which contain one record for each electric or magnetic field data measurement. Each record in the amplitude output files contains the following information: name type units description YYDDD INT year and a two-digit year and a three- day digit day number (January 1 = number 1) MSOD INT msec millisecond of day FREQ REAL Hertz frequency SD REAL V**2/m**2/Hz spectral density or gammas**2/Hz ANT CHAR Es, Ez, Ex, antenna connected to selected STRG B, or H receiver: Es, short electric antenna deployed in spin plane; Ez, tubular electric antenna deployed along the spin axis; Ex, long wire electric antenna deployed in the spin plane; B, magnetic loop antenna measuring the spin modulated component of the magnetic field parallel to Ex (100 Hz - 410 kHz); and H, magnetic search coil measuring non-spin modulated component of the magnetic field parallel to the spin axis R REAL RE geocentric radial distance L REAL L-shell value MLT REAL hour magnetic local time MLAT REAL degrees magnetic latitude The Step Frequency Correlator has 128 frequency steps logarithmically- spaced from 100 Hz to 410 kHz with approximately a 1% bandwidth, which is constant for each of the four channels. The Low Frequency Correlator has 8 frequency filters from 1.8 Hz to 100 Hz with a 15% bandwidth. The resolution of either amplitude measurement is a logarithmic function of the level being measured. The amplitude compressor tables, found in LFC_AMP.CAL and SFR_AMP.CAL, have 256 levels. The effective resolution at any given amplitude will be the difference between two counts at that level. The SFR and LFC phase data output files are ASCII files which contain one record for each phase data measurement. Each record in the phase output files contains the following information: name type units description YYDDD INT year and a two-digit year and a three- day digit day number (January 1 = number 1) MSOD INT msec millisecond of day FREQ REAL Hertz frequency PHA REAL degrees phase angle (0-360) CORR REAL correlation coefficient (0 - 1.47). A value of 1 is good. ANT1 CHAR Ez, Ex, antenna connected to first STRG B, or H receiver: Ez, tubular electric antenna deployed along the spin axis; Ex, long wire electric antenna deployed in the spin plane; B, magnetic loop antenna measuring the spin modulated component of the magnetic field parallel to Ex (100 Hz - 410 kHz); and H, magnetic search coil measuring non-spin modulated component of the magnetic field parallel to the spin axis ANT2 CHAR Ez, Ex, antenna connected to second STRG B, or H receiver: Ez, tubular electric antenna deployed along the spin axis; Ex, long wire electric antenna deployed in the spin plane; B, magnetic loop antenna measuring the spin modulated component of the magnetic field parallel to Ex (100 Hz - 410 kHz); and H, magnetic search coil measuring non-spin modulated component of the magnetic field parallel to the spin axis R REAL RE geocentric radial distance L REAL L-shell value MLT REAL hour magnetic local time MLAT REAL degrees magnetic latitude The phase correlations provide a measurement of the phase to within 5 degrees and a measurement of the normalized correlation coefficients to within 5% between signals from two selected antennas. The DC electric field data output files are ASCII files which contain two records for each DC data measurement one for the field measured in the spin plane and one for the field measured perpendicular to the spin plane. The first record contains the following information: name type units description YYDDD INT year and a two-digit year and a three- day digit day number (January 1 = number 1) MSOD INT msec millisecond of day E(PERP) REAL V/m DC electric field component perpendicular to the projection of the magnetic field vector in the spacecraft spin plane E(PARA) REAL V/m DC electric field component parallel to the projection of the magnetic field vector in the spacecraft spin plane CHI REAL "chi" error calculated with the least-square-error fit, an indication of the reliability of the measurement. The range is from 0 to infinity with the smaller numbers indicating a better fit. ANT CHAR Ex long wire electric antenna STRG deployed in the spin plane R REAL RE geocentric radial distance L REAL L-shell value MLT REAL hour magnetic local time MLAT REAL degrees magnetic latitude The second record contains the following information: name type units description YYDDD INT year and a two-digit year and a three- day digit day number (January 1 = number 1) MSOD INT msec millisecond of day EZ REAL V/m DC electric field component parallel to the spacecraft spin axis BLANK REAL a fill value of 0.00 which is used to preserve the order of the array SDEV REAL standard deviation calculated for each averaging interval of 6 seconds as an indicator of the noise present. All values are positive numbers with the smaller values indicating most reliable data values. ANT CHAR Ez tubular electric antenna STRG deployed along the spin axis R REAL RE geocentric radial distance L REAL L-shell value MLT REAL hour magnetic local time MLAT REAL degrees magnetic latitude The analog-to-digital converter is designed to have a full-scale digital output of 256 counts with an analog input of 5.12 volts. In order to measure both positive and negative DC electric fields, a nominal voltage offset of 2.56 volts has been added to the outputs of the DC amplifiers so that counts of 0 and 255 correspond to respective voltage measurements of -2.54 volts and +2.54 volts. The effective resolution of the raw DC data value is typically .002 V/m for the DC data measurements perpendicular to the spin plane and .0005 V/m for the DC data measurements in the spin plane. In some cases, when very strong fields are present, the resolution can degrade to .02 V/m. The Ez component of the DC electric field exhibits interference due to the differential charging of the spacecraft skin. The magnitude of the interference is dependent on the ambient plasma density in such a way that, at altitudes of the Dynamics Explorer spacecraft, the true Ez field is completely masked. This interference severely limits the utility of the DC electric field measurements with the Ez antenna. Consequently, DC data analysis has been concentrated on the measurements with the long wire Ex antenna. SOURCE_CODE_OPERATION: If you are not running under a VMS-operating system, the user will need to alter the functions described in UTIL.FOR. The user will need to provide the following functions, utilized by the functions in UTIL.FOR, if these functions are not provided by the user's sytem: IAND(NUM1,NUM2). This integer function is a nonstandard intrinsic function that returns the bitwise AND (a logical AND on corresponding bits) of the two integer arguments, NUM1 and NUM2. If the user's FORTRAN compiler does not supply this intrinsic function, the user will have to provide a version with the given calling sequence. IOR(NUM1,NUM2). This integer function is a nonstandard intrinsic function that returns the bitwise OR (an inclusive OR on corresponding bits) of the two integer arguments, NUM1 and NUM2. If the user's FORTRAN compiler does not supply this intrinsic function, the user will have to provide a version with the given calling sequence. ISHFT(NUM,BITS). This function returns a bitwise shift of the first integer argument NUM (logically shifted left by BITS bits). The second integer argument BITS may be positive or negative -- positive corresponds to a left shift and negative corresponds to a right shift. The archived software does not make any assumptions about the state of the high order bits after a right shift. Therefore, this function may safely ignore these upper bits. If the user's FORTRAN compiler does not supply this intrinsic function, the user will have to provide a version with the given calling sequence. The user must determine the appropriate keywords for the open statement in OPNDAT (in UTIL.FOR) if the user is not running on a VMS system. These nonstandard keywords are used to open the data files located on the optical disk. The keywords are fully described below: READONLY necessary to open a file on a read-only device (optical disk) under the VMS operating system RECORDTYPE = 'FIXED' describes the record structure of the file under the VMS operating system SHARED allows multiple users to read the files simultaneously under the VMS operating system If you are not compiling the code under the VMS operating system, it will be necessary to omit these keywords from the OPEN statement in the function OPNDAT. Alternatively, you may replace these keywords with those keywords appropriate for your operating system. For additional assistance with the PWI software, please contact: Scott Allendorf Department of Physics and Astronomy University of Iowa Iowa City, Iowa 52242 319/335-1960 NSI/DECnet IOWAVE::ALLENDORF INTERNET allendorf@iowave.physics.uiowa.edu SAMPLE_INPUT_DATA_SET: The sample input data set is located in the data file named Software_PWI_81360.DAT, which is located on each archival volume. The format of this file is fully described in FORMAT.SFD, also located on each archival volume. When running PWI.FOR, the user must specify the following start and stop times: 81360 010000 81360 010100 In order for the user to duplicate the sample output files, the user must further specify: type of data (input) receiver (input) corresponding output data SFR Amplitude A electric or magnetic field measurements (depending on the antenna connected to Receiver A) from 100 Hz - 410 kHz SFR Amplitude B electric or magnetic field measurements (depending on the antenna connected to Receiver B) from 100 Hz - 410 kHz LFC Amplitude A electric or magnetic field measurements (depending on the antenna connected to Receiver A) from 1.8 Hz - 100 Hz LFC Amplitude B electric or magnetic field measurements (depending on the antenna connected to Receiver B) from 1.8 Hz - 100 Hz SFC Phase phase measurements from 100 Hz - 410 kHz LFC Phase phase measurements from 1.8 Hz - 100 Hz DC Electric Fields DC electric field measurements both in the spin plane and along the spin axis (less than 8 Hz) The user must also supply a full file specification for his/her own output file. OUTPUT_FROM_SAMPLE_INPUT: The sample output files contained in each archival volume and the corresponding type of data contained in each output file are listed below: output filename type of output data TEST_SFRA_AMP.DAT SFR Amplitude Data from Receiver A TEST_SFRB_AMP.DAT SFR Amplitude Data from Receiver B TEST_LFCA_AMP.DAT LFC Amplitude Data from Receiver A TEST_LFCB_AMP.DAT LFC Amplitude Data from Receiver B TEST_SFR_PHA.DAT SFR Phase Data TEST_LFC_PHA.DAT LFC Phase Data TEST_DC.DAT DC Electric Fields