==============================================================================
CLUSTER FGM software (SPARC/Solaris-2) for generating high resolution 
or averaged magnetic field vectors in GSE coordinates
==============================================================================
Content of this document:
  I. Introduction
 II. Generic INSTRUCTIONS for the data processing
III. Testing the program
 IV. Files included in this distribution (fgmdp version 1.0):
==============================================================================

 The Cluster FGM software is a flexible tool which allows systematic daily 
 data processing in data centers or direct processing from a CDROM.

 In both cases an environment variable FGMPATH must be set. It should point  
 to the directory containing the 'const.fgm' file and the calibration files 
 *.fgmcal.
 
 The daily processing supposes additional preprocessing steps, which are 
 not needed if processing directly from a CDROM.
 The necessary input files are summarized in Fig_1.pdf and a schematic data 
 flow is shown in Fig_2.pdf.

 INPUT files are (using name patterns from CDROM written in lower case):
 *fn*, *fb*, *ga*, *ta*, *ba* and the already mentionend 'const.fgm' & *.fgmcal.
 
 OUTPUT is written to a binary or to an ASCII file (option '-x') named 
 C#_yyyymmdd_sys.igm, resp. C#_yyyymmdd_sys.txt. Use option '-o' <outf>
 to define your own output filenames.
 It contains: time, cartesian components of the magnetic field and
 of the satellite position in GSE. The binary structure is called
 fgmtrec_t and is described in the Data Processing Handbook.
 If option '-w' is used the vector components are averaged over 1 spin period 
 per default, or over a user defined time interval <float> seconds.
 Output can be produced from the whole input data or for a user defined 
 time interval (options '-b' & '-e').
 
 Please consult the HELP page to see all the options, by typing: 
        
        fgmdp -h
    
 Find more details on the software in the 'fgmdp.ps' document file and
 in the 'FGM Data Processing Handbook'.

==============================================================================
Generic INSTRUCTIONS for the data processing
==============================================================================
1. Set the environment once at the beginning of a session.
   At least FGMPATH must be defined. 
   For systematic daily processing set the environment variables 
   FGMPATH, SATTPATH, ORBITPATH and define aliases for fgmdp, putsatt, putstof:
   
     source config_fgm.bash (in bash or corresponding scripts in other shells) 

2.  Preprocessing steps:

 a. Copy the STEF file from the CDROM and rename it to stef.cl# 
    
     cp CDROM/cluster#/aux_#/*ta* $SATTPATH/stef.cl# (#=1,2,3,4) 
    
    or use option '-E' for explicitly given STEF (*ta*) file.
       
 b. Update the satt.cl# file with the CDROM SATT file by appending it 
     after the removal of the DDS-headers 
     
     putsatt CDROM/cluster#/aux_#/*ga* $SATTPATH/satt.cl#

    or use option '-a' for explicitly given SATT (*ga*) file.

 c. Update the stof.cl# file with the CDROM STOF file by appending it 
     after the removal of the DDS-headers 
     
     putsatt CDROM/cluster#/aux_#/*ba* $SATTPATH/stof.cl#

    or use option '-p' for explicitly given STOF (*ba*) file.

3. Processing:

     fgmdp CDROM/cluster#/nsd_#/*fn* CDROM/cluster#/bsd_#/*fb* [-o [<outf>]]
  
==============================================================================
Testing the program
==============================================================================
Example I.
----------
Since preprocessing results are already in the corresponding directories,
you have to execute only instructions 1 and 3.

1.    source config_fgm.bash 
2.    fgmdp examples/test.rdm -x -w 0.5 -b T15:03:00 -e T15:04:00 [-o <outfile>] 

You obtain a listing of magnetic field and position vectors in GSE coordinates 
averaged over 0.5 seconds.

2.    fgmdp examples/test.rdm -x -i -w 2.0 [-o <outfile>]

gives a listing of magnetic field and position vectors in GSE coordinates 
averaged over 2 second, with appended column names & calfilename info.

You may compare your results with the listings in the "examples/test"
directory: "out1.gse", "out2.gse". 

Example II.
-----------
Take CDROM000115_1_1A, for example.
If you didn't already set the environment, then execute 1.

2.  cp CDROM000115_1_1A/cluster4/aux_4/000115ta.1a4 $SATTPATH/stef.cl4

    putsatt CDROM000115_1_1A/cluster4/aux_4/000115ga.1a4 

    putstof CDROM000115_1_1A/cluster4/aux_4/000115ba.1a4 

3.  fgmdp CDROM000115_1_1A/cluster4/nsd_4/000115fn.1a4 

The same result can be obtained without preprocessing, by typing:

   fgmdp    CDROM000115_1_1A/cluster4/nsd_4/000115fn.1a4 
         -E CDROM000115_1_1A/cluster4/aux_4/000115ta.1a4
         -a CDROM000115_1_1A/cluster4/aux_4/000115ga.1a4
         -p CDROM000115_1_1A/cluster4/aux_4/000115ba.1a4

Unfortunately the orbit file is not correct (julian date doesn't correspond to
date, so all you get is an error message.

==============================================================================
Files included in this distribution (version 1.0):
==============================================================================
README          this file
config_fgm.*    shell script for setting the environment for FGM-DP software
att/            subdirectory with attitude file produced from CDROM(SATT) 
bin/            subdirectory with binary executables
cal/            subdirectory with ground calibration files & 'const.fgm'
doc/            subdirectory with documents
examples/       subdirectory with example files
orb/            subdirectory with orbit file produced from CDROM(STOF)

Files in subdirectory "att":
-----------------------------------------------------------------------
satt.cl#        attitude (SATT) file from CDROM
stef.cl1        short term event (STEF) file renamed from 
                           CDROM/cluster1/aux_1/*ta*
ltef.cl1        downloaded from ESOC  

Files in subdirectory "bin":
-----------------------------------------------------------------------
fgmdp           main executable
ddscut          internally used executable
ddshrm          internally used executable
ddsmrg          internally used executable
fgmav           internally used executable
fgmcal          internally used executable
fgmhrt          internally used executable
fgmpos          internally used executable
fgmtel          internally used executable
igmvec          internally used executable
mrgatt          internally used executable
putsatt         executable for handling auxiliary files
putstof         symbolic link to putsatt

Files in subdirectory "cal":
-----------------------------------------------------------------------
const.fgm       FGM constants file
C#.fgmcal       ground calibration files  #=1,2,3,4 - satellite number

Files in subdirectory "doc":
-----------------------------------------------------------------------
Fig_1.pdf       schematic diagram of the data processing
Fig_2.pdf       flowchart of the FGM raw data processing
fgmpeace.ps     postscript document of the FGM PSDS data processing for PEACE

Files in subdirectory "examples":
-----------------------------------------------------------------------
test.rdm        test FGM raw data file
test/           subdirectory with test files

Files in subdirectory "examples/test":
-----------------------------------------------------------------------
out1.gse       1 minute of ASCII processing output of test raw data file, 
               GSE coordinates, averaged over 0.5 s 
out2.gse       ASCII processing output of test raw data file, GSE coordinates,
               averaged over 2 s

Files in subdirectory "orb":
-----------------------------------------------------------------------
stof.cl1        short term orbit (STOF) file produced by putstof from 
                           CDROM/cluster1/aux_1/*ba*

==============================================================================
Changes since CLUSTER I 
==============================================================================

1. The software modules have been changed to match the new structure
   of the calibration file.

2. Calibration file naming convention changed:
   C#.fgmcal              for ground calibration files
   C#_yyyymmdd_Vvv.fgmcal for daily in-flight calibration files
   #=1,2,3,4 : satellite number, vv : version number (01,02,..)

3. Additional INPUT files: const.fgm and STEF(LTEF) files. 
   The STEF(LTEF) files are used to avoid processing during eclipse.
   They are chosen automatically by the software. They must rezide in
   the same directory as the preprocessed attitude files( satt.cl#), 
   pointed at by the FGMPATH environment variable. If no stef.cl# 
   files available then the predicted ltef.cl# will be taken. 
   Using option '-E' the unrenamed *ta* file can be input.

4. Additional option "-l" <logf> to redirect the stderr to a logfile.
   If '-l' but no <logf> specified, default name 'logfile' will be used.  

5. Additional option "-E" <eclf> to allow explicitly given STEF/LTEF files.  

6. Additional option "-i" to append the used calfile-name to the output, 
   since the software picks out automatically the "right" calibration file. 
   If no daily calfile available, the ground calibration file will be chosen.
   Default is to have the calfilename info written in the file "cal.log".
   A tailstring with the column titles is appended too.

==============================================================================
Address for comments, bug reports, etc.:
==============================================================================

eg@mpe.mpg.de
