Archive Software User's Guide

Software Copyright and License

The Ulysses/SWICS Archive Software is Copyright (C) 1999 by Physikalisches Institut of the University of Bern. as the archive programs do not contain any third party components or libraries, the programs are open source software - you can redistribute it and/or modify it under the terms of the GNU General Public License Version 2 as published by the Free Software Foundation.
These programs are distributed in the hope to be useful, but they come with ABSOLUTELY NO WARRANTY, without even the implied warranty of FITNESS FOR A PARTICULAR PURPOSE or MERCHANTABILITY.

Ulysses/SWICS Archive Software Installation

To install the Ulysses/SWICS Archive Software copy the sapro.exe (on UNIX systems: sapro) file for the processor (CPU) and operating system (OS) you are using from the appropriate /bin/<cpu>/<os> directory to a directory on your harddisk where you have read/write/execute permissions. Write permission is required, because the archived CDF files are in compressed format and need automatically be decompressed into a temporary file before the CDF file content can be read.

Ulysses/SWICS Archive Data Generator (SAGEN)

The SAGEN application is used to extract the SWICS instrument data from the transmitted raw data. Additionally SAGEN assembles the corresponding meta-data and generates the CDF files to be stored in the archive. As the Physics Institute of the University of Berne maintains and generates these archive files, the ordinary Ulysses/SWICS Archive user does not need to use the SAGEN program.

Ulysses/SWICS Archive Data Processor (SAPRO)

The SAPRO application is used to read the Ulysses/SWICS Archive CDF files and to extract and calibrate the SWICS instrument Matrix Rate (MR) data. The MR count rates are utilized to calculate the density, speed and thermal speed of selected solar wind ions. The results are presented in a table and written to an ASCII output file.
The User Interface for the SAPRO application is a simple command-line interface, which has the advantage to easily use SAPRO for batch processing tasks or web scripting applications. The general usage syntax is as follows (entries which are optional are depicted within brackets [ ]):

The executable name (sapro) has to be followed by exactly one command prefixed with a dash (-). The only exception to this rule is the default command which can be omitted. Most commands can be abbreviated by a single character. Some of the commands may be followed by a command-value separated by a colon (:).
Some commands have one or several additional command-options also prefixed with dash (-). Again some of the command-options may be followed by a command-option-value separated by a colon (:). The order in which the different command-options are entered is irrelevant.
Some commands additionally also have one or several command-variables, which are typically used for specifying directory or file names. Command-variables are not prefixed and their order on the command-line is of importance.
The particular commands and command-options supported by SAPRO are listed in the following table:

An abbreviated version of the above usage table can also be shown in the command window by simply entering sapro on the command-line.

SAPRO Usage Examples

This paragraph shows some examples of how to use the SAGEN program with the command-line options listed in the previous paragraph. The examples assume your current directory is where you copied the sagen executable and that the Ulysses/SWICS Archive CD-ROM is in drive R: of your computer. (If you are using a UNIX system the characters for drive and path separator have to be adjusted accordingly.)

• To process and calibrate all archive data of 1995 and save it to the ASCII output file data.asc, you would enter the following command:
  > sapro r:\data\1995\*.cdf data.asc
  
  
• To show but not process all archive files contained on the Ulysses/SWICS CD-ROM, you enter the following command:
  > sapro -sub r:\data\ data.asc -fake
  
  
• To process and calibrate the archive data from the first 100 days of 1996, you enter the following command:
  > sapro -sub -start:19960101 -end:1996100 r:\data\ data.asc
  
  
• To process and calibrate all archive data starting from May 1996 until the end of the available data in the archive, you enter the following command:
  > sapro -sub -start:19960501 r:\data\ data.asc

SAPRO Configuration Parameters

To further customize the archive software, many parameters can be specified within a configuration file. The default configuration file SAPRO is looking for, is named sagen.cfg. If no such file is found in the current directory, default values are used for all configuration parameters. (If the configuration file has a different name or is in an other directory, the command-option -cfg:<filename.cfg> can be used.)
The general syntax for a configuration file starts with a configuration section name ([<filter name>]) followed by one or several configuration parameter value pairs (<configuration parameter> = <parameter value>).
The configuration parameters most used for the SAPRO application are shown in the following listing along with their default parameter values:

[SWICS CALIBRATION]
CalibrationStart =         # Calibration Start Time (YYYYMMDDHHMM)
CalibrationEnd =           # Calibration End Time   (YYYYMMDDHHMM)
AccumulationCount = 32     # Accumulation Cycle Count [cycles]
AccumulationTime = 24.0    # Accumulation Time  [hours]
CalibrationMR1 = true      # (He2+) Calibration
CalibrationMR5 = true      # (C4+)-(C5+) Calibration
CalibrationMR6 = true      # (C6+) Calibration
CalibrationMR8 = true      # (O6+) Calibration
CalibrationMR9 = true      # (O7+)-(O8+) Calibration
CalibrationMR11 = true     # (Mg6+)-(Mg8+) Calibration
CalibrationMR12 = true     # (Mg9+)-(Mg10+) Calibration
CalibrationMR13 = true     # (Si7+)-(Si8+) Calibration
CalibrationMR14 = true     # (Si9+)-(Si12+) Calibration
CalibrationMR16 = true     # (Fe6+)-(Fe9+) Calibration
CalibrationMR17 = true     # (Fe10+)-(Fe16+) Calibration
      

The first two parameters control how many Deflection Voltage Cycles (DVC) are accumulated to determine the MR count rates. You either can accumulate a predefined number of DVC using the AccumulationCount parameter, or you can accumulate for a certain time period using the AccumulationTime parameter ([hours]). You normally use just one of these parameters at the same time (if both are specified AccumulationTime is used).
The remaining SWICS calibration parameters are used to specify which ion rates are to be calibrated and to be written into the output file. Each parameter value can either be true or false. The SAPRO application has some more configuration parameters which usually should not need to be changed by the archive user.