Scientific Software System ( S^{3} )

Reference Manual

(Incomplete Preliminary Version)

Version 1.0

September 29, 2005

John Burton Larry Gordley

G & A Technical Software

28 Research Drive Hampton, VA. 23666

(804)–865–7491

\begin{matrix}c \\ ◯ \end{matrix} Copyright 1992 by G & A Technical Software, Inc., 28 Research Drive, Hampton. Virginia, 23666.

All Rights Reserved. No part of this publication or software may be reproduced, stored

in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of

G & A Technical Software, Inc.

Version  i  GATS, Inc.

Contents

List of Figures iii

List of Tables iv

1 S^{3} User’s Guide 1

1.1 Basic Design Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1.1 PDT - Parameter Definition Table . . . . . . . . . . . . . . . . . . . . . . 2 1.1.2 PCT - Process Configuration Tables . . . . . . . . . . . . . . . . . . . . . 4 1.1.3 PCP - Process Control Program . . . . . . . . . . . . . . . . . . . . . . . 5

2 S^{3} Reference Manual 8

2.1 PDT Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.2 Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.3 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.1.4 Dataset Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.1.5 Static Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.2 PCT Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3 PCP Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.4 S^{3} Based Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.4.1 Initial Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.4.2 Creating S^{3} Application Programs . . . . . . . . . . . . . . . . . . . . . . 18 2.4.3 Adding User Defined Routines . . . . . . . . . . . . . . . . . . . . . . . . 18

Version  ii  GATS, Inc.

2.4.4 Running S^{3} Application Programs . . . . . . . . . . . . . . . . . . . . . . 19 A S^{3} Example 20

A.1 Example PDT configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 A.2 Example PCT configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

B S^{3} Utility Routines 29

Version  iii  GATS, Inc.

List of Figures

1 Example of a simple PDT file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2 Example of a simple PCT file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3 Executing an S^{3} Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4 Creation of an S^{3} Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5 PCT Structure for S^{3} Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 6 Constant, String, and Double segment of PDT for S^{3} Example - safire.pdt …. 23 7 Real segment of PDT for S^{3} Example - safire.pdt . . . . . . . . . . . . . . . . . . 24 8 Integer segment of PDT for S^{3} Example - safire.pdt . . . . . . . . . . . . . . . . 25 9 Primary PCT for S^{3} Example - safire.pct . . . . . . . . . . . . . . . . . . . . . . 26 10 Forward Radiance Calculation for S^{3} Example - forward.pct . . . . . . . . . . . . 27 11 Apodization Calculation for S^{3} Example - apodize.pct . . . . . . . . . . . . . . . 27 12 Interpolation Calculation for S^{3} Example - interpolate.pct . . . . . . . . . . . . . 28 13 Interferogram Calculation for S^{3} Example - interferogrm.pct . . . . . . . . . . . . 28

Version  iv  GATS, Inc.

List of Tables

1 Correspondence of Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2 Correspondence of Dimensioning Constructs . . . . . . . . . . . . . . . . . . . . . 9

Version  v  GATS, Inc.

S^{3} User’s Guide

1 S^{3} User’s Guide

There are many facets to remote sensing data processing. Most require complicated mathematical procedures that will be be refined through research efforts in coming years. These efforts will involve scientists and software developers from a variety of research centers. The purpose of the Scientific Software System ( S^{3} ) is to provide a flexible basis for the analysis of remote sensing data that can be rapidly adapted to the needs of the individual researcher, including the simple incorporation of new processing techniques.

Most remote sensing instruments require two distinct phases (or levels) of data processing to infer geophysical information. Level I processing conditions the measurement data by removing undesirable instrument effects and calibrating to scientific units. Level II processing involves an iterative modification of the assumed geophysical state to allow the measurement model to match the measurement data. Occasionally when processing the data produced by particular instruments, the above distinction becomes somewhat blurred. Part of the Level I signal conditioning may need to be included in the iterative modification of the geophysical model. The S^{3} package provides the necessary flexibility to enable the researcher to process data using whatever methodology he or she desires.

1.1 Basic Design Overview

S^{3} Objectives:

1. Easy and reliable modification of system.

2. Modification without high level code change, aiding in configuration control.

3. Easy maintenance of modularity throughout code evolution.

4. Simple use of complex modules.

5. Easy incorporation of new analysis techniques.

6. Simple interface to graphical analysis tools.

7. Encouragement of structured programming methodologies.

These objectives can be accomplished with strict definition and control of data flow and module interface, and flexible definition of processing logic and data structures. The method used to achieve these goals is based on three major components; the Parameter Definition Table (PDT), the Process Configuration Tables (PCTs), and the Process Control Program (PCP). The PDT defines the constants and datasets that will be used by the system. Similarly, the PCTs define the order in which procedures are executed and which datasets are passed to a given procedure. The PCP is the program that ties everything together. It controls the operation of S^{3} based on the information provided by the PDT and PCT’s. The use of this architecture provides additional desirable research features:

1. Module execution can be easily reconfigured, either before or during execution by simply modifying the PCT’s.

2. Program control can be exercised from any module in the system.

3. Interactive graphical control can be realized simply by inserting independently developed and tested graphics modules.

4. The user can install his own routines by simply linking to the main program and modifying the appropriate PCT file(s) before execution.

1.1.1 PDT - Parameter Definition Table

The PDT is initialized during the program (PCP) start up by reading a PDT file. By default the PDT filename is program.pdt where program is the name of the executable program created during the make process. The PDT file contains information defining the type of data, number of dimensions, and size of each dimension for all datasets defined. A dataset must be defined in the PDT file before it can be used by the program. The PDT can be thought of as a large (FORTRAN) common block of global data structures, but with critical distinctions:

1. The data structures are held in a file, eliminating the necessity of code change to a common block.

2. The data structures can be accessed only through the calling parameters associated with routines specified in the PCT’s.

This forces preservation of modularity while permitting rearrangement of logic and data structures with little or no code change.

The syntax of the PDT file allows the definition of constants which, can be later used to dimension datasets. Each dataset can have zero or more dimensions, with zero dimensions indicating a simple (as opposed to an array) dataset. Additionally each dataset can be initialized within the PDT file. An example PDT file, shown in figure 1, demonstrates the basic syntax of a PDT file. Further details concerning the syntax of a PDT file are provided in section 2.1

!
! Constants used to dimension the datasets
!
CONST:  m1     =       5;
CONST:  m2     =       4;
CONST:  m3     =       3;
!
! Definition and initialization of a single dimensioned array
!
DREAL:  arr1     : m1 = {0.0,1.0,2.0,3.0,4.0};
!
! Definition and initialization of a two dimensional array
!
REAL:   arr2     : m1,m2 = {0.0,0.1,0.2,0.3,0.4,
                            1.0,1.1,1.2,1.3,1.4,
                            2.0,2.1,2.2,2.3,2.4,
                            3.0,3.1,3.2,3.3,3.4};
!
! Definition and initialization of a three dimensional array
!
REAL:   arr3     : m1,m2,m3 = {0.00,0.01,0.02,0.03,0.04,0.10,0.11,0.12,0.13,0.14,
                               0.20,0.21,0.22,0.23,0.24,0.30,0.31,0.32,0.33,0.34,
                               1.00,1.01,1.02,1.03,1.04,1.10,1.11,1.12,1.13,1.14,
                               1.20,1.21,1.22,1.23,1.24,1.30,1.31,1.32,1.33,1.34,
                               2.00,2.01,2.02,2.03,2.04,2.10,2.11,2.12,2.13,2.13,
                               2.20,2.21,2.22,2.23,2.24,2.30,2.31,2.32,2.33,2.34};
!
GROUP:agroup:arr1,arr2,arr3,m1;

Figure 1: Example of a simple PDT file

One construct that should be noted in the example PDT file, figure 1, is the GROUP construct. GROUP associates a name with an ordered group of datasets and / or constants, which can later be used to pass those datasets / constants to an executable module.

1.1.2 PCT - Process Configuration Tables

In contrast to the PDT, which remains unchanged after initialization, the PCT’s are actively involved in the control of the program’s execution. Each PCT consists of an Execution Order List (EOL), an Execution Order Index (EOI) and an Execution Entry List (EEL). Each Execution Entry either specifies a call to an executable module or transfer of control to another PCT. This structure is analogous to the multi-level menu interfaces used by many popular software packages. In these packages, each menu option either performs some operation or produces a sub–menu. The order in which the entries of a PCT are executed is controlled by the EOL and EOI. To provide flexibility, the EOL and EOI for any PCT can be modified at any time during PCP execution. Like the PDT, the PCT’s are initialized from the appropriate PCT files during PCP startup.

 "Testing the memory thing...";  ! verbal description of PCT
bacadz;                          ! Execution Order List (EOL)
0;                               ! Execution Order Index (EOI)
a:FS:FILLARRAY    :arr1,arr2,arr3,m1,m2,m3;
b:FS:FPRINTARRAY  :agroup,m2,m3;
c:CS:CPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
d:CS:DUMP         :arr1,arr2,arr3,m1,m2,m3;

Figure 2: Example of a simple PCT file

The example PCT file given in figure 2 shows the the basic syntax of a simple PCT file. The PCT file contains a verbal description of the purpose of the PCT, the EOL, the EOI, and a list of entries. The EEL is constructed from the list of entries on program startup. The characters comprising the EOL correspond to the first letter in each line of the list of entries. This first character is referred to as the entry label. The letter “z” is used to indicate that execution in this PCT should be halted at this point and control should be passed to the calling or parent PCT. If there is no parent PCT then execution of the program is halted. The EOI is an index into the EOL, with zero (0) being the index of the first character in the EOL. The example in figure 2 will execute the specified routines in the following order:

FPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
FILLARRAY    :arr1,arr2,arr3,m1,m2,m3;
CPRINTARRAY  :arr1,arr2,arr3,m1,m2,m3;
FILLARRAY    :arr1,arr2,arr3,m1,m2,m3;
DUMP         :arr1,arr2,arr3,m1,m2,m3;

The next set of characters after the entry label specify what type of routine each entry is. In the example, FPRINTARRAY and FILLARRAY are FORTRAN Subroutines, and CPRINTARRAY and DUMP are C Subroutines. Other possibilities are described in section 2.2.

It should be noted that when a group name is encountered in a PCT, the PCP (described below) simply substitutes the datasets / constants associated with that group (in the order given in the PDT file) and then passes them to the executable module.

1.1.3 PCP - Process Control Program

The Process Control Program is the system manager. The PCP consists of two primary routines, one to initialize the environment which:

1. Parses the command line options to determine the operating mode of the system.

2. Reads the PDT file and creates the required datasets.

3. Reads the PCT files and organizes the PCT’s into a tree structure consisting of PCT’s nodes and executable modules.

The second primary routine traverses the PCT tree created during initialization in the order specified by the EOL and EOI, and executes the appropriate modules.

For example, assuming we have an S^{3} application program named example and the PDT and PCT files shown in figures 1 and 2 are named example.pdt and example.pct respectively, a typical invocation of the program

example -b

would result in the following actions:

1. Set the operating mode for example to check for dataset bounds violations (see section 2.3 for more about operating modes).

2. Read PDT file example.pdt :

(a) Create constant entries for m1, m2, and m3.

(b) Create dataset entries for arr1, arr1, and arr3.

(c) Allocate memory for datasets arr1, arr2, and arr3.

(d) Initialize arr1, arr2, and arr3 to the specified value.

3. Read PCT file example.pct: and create a PCT tree containing 1 PCT entry and 4 executable entries.

4. Start executing example.pct. Repeat the following until EOL(EOI) equals “z”.

(a) Get the character EOL(EOI).

(b) Call routine with label given by EOL(EOI).

(c) Check datasets for bounds violations.

(d) Increment EOI.

This is shown diagrammatically in figure 3.

Figure 3: Executing an S^{3} Program

The creation of the executable program example, as shown in figure 4, is accomplished by simply typing make which in turn performs a three step process. First the setup utility program reads the PDT and PCT files to obtain certain information about the routines fillarray, fprintarray, cprintarray, and dump. Next, this information is inserted into the main program (PCP) file which is then compiled along with the files fillarray.f, fprintarray.f, cprintarray.c, and dump.c. Finally, these five files are linked together along with the S^{3} library to create an executable program. These steps are all controlled by the file Makefile which controls the make process.

Once the executable program has been created, the user has a limited freedom to modify how the program executes without having to recreate (re-make) the program. The user may:

• Change the EOL or EOI line of the PCT file, modifying the order in which the routines are executed, or which routines are executed.

S^{3} User’s Guide

Figure 4: Creation of an S^{3} Program

• Remove a routine from the PCT file.

• Change the parameters being passed to a routine. Any other modifications will generally require a re-make.

Version  7  GATS, Inc.

S^{3} Reference Manual

2 S^{3} Reference Manual

2.1 PDT Syntax

There are three basic quantities defined in the PDT configuration file, constants, datasets, and groups, all of which must be defined prior to use. 2.1.1 Constants A constant is specified using the syntax

CONST: < name >=< ivalue >; [< comment >]

where:

< name > ≡ the name of the constant
< ivalue > ≡ the integer value expression to be assigned to < name >
< comment > ≡ anything between the semi–colon and the end of the line.

Anything enclosed in square brackets [ ] is considered optional, and the user need not include it in the PDT or PCT file. < ivalue > is an expression that evaluates to an integer value, and can include the following arithmetic operations:

+ ≡ integer addition
- ≡ integer subtraction
* ≡ integer multiplication
/ ≡ integer division
% ≡ integer modulus
** ≡ integer exponentiation

2.1.2 Datasets The definition of a dataset is accomplished via

S^{3} Reference Manual

< type >: < namelist > [ : < dimlist >] [ = < ivalue >] ; [ < comment >] where:

< type > ≡ the data type contained by the dataset(s) in < namelist >
< namelist > ≡ the list of one or more dataset names
< dimlist > ≡ list of zero or more values indicating the size of each dimension
< ivalue > ≡ the initial value(s) of the dataset
< comment > ≡ anything between the semi-colon and the end of the line.

The < type > of the dataset can be one of BYTE, STRING, INT, REAL, DREAL, COMP, and DCOMP. The correspondence of these type to the data types found in FORTRAN and C are given in table 1

S^{3} PCT FORTRAN  C
BYTE INTEGER*1 unsigned char
STRING CHARACTER*(*) char *
INT  INTEGER*4  int
REAL  REAL*4  float
DREAL REAL*8  double
COMP COMPLEX*8  struct{ float imag, real }
DCOMP COMPLEX*16  struct{ double imag, real }

Table 1: Correspondence of Data Types

Each dataset can have multiple dimensions, the size of each dimension is defined by the corresponding < dim >, which can be either the name of a previously defined constant or an integer value. The correspondence of the dimensioning of S^{3} datasets to FORTRAN and C is given in table 2 for example datasets ARR1, ARR2, and ARR3, which are real arrays of 1, 2, and 3 dimensions respectively.

S^{3} PCT  FORTRAN  C
REAL:ARR1:6  REAL ARR1(6)  float arr1[6]
REAL:ARR2:6,4 REAL ARR2(6,4) float arr2[4][6]
REAL:ARR3:6,4,3 REAL ARR3(6,4,3) float arr3[3][4][6]

Table 2: Correspondence of Dimensioning Constructs 2.1.3 Groups

Often in a large software package, many executable modules operate on the same sets of information. If the information set consists of several datasets and constants, it can be tedious to write the executable entries for these modules in the PCTs. One method to make this process faster and more comprehensible is through the use of groups. Basically a group is defined by associating a name with an group of datasets and / or constants as shown below. When used in the parameter list of an executable entry in a PCT, the group is expanded to the list of datasets / constants in the order defined. A group is specified using the syntax

GROUP: < name >:< namelist >; [< comment >]

where:

< name > ≡ the name to be associated with the group of datasets.
< namelist > ≡ the list of one or more previously defined dataset names
< comment > ≡ anything between the semi–colon and the end of the line.

2.1.4 Dataset Initialization

Initialization of a dataset is accomplished using the < ivalue > construct, where

< ivalue >≡ { < value list > }

and

< value list >≡< value1 >, < value2 >, …, < valueM >,

for datasets of any types or

< ivalue >≡ “character string ”

for datasets of type STRING. < valueM > is either a single character / numeric value, or a single character / numeric value with a repeat factor as shown in the following example:

REAL : ARR1 : 20 = {14 ∗ 27.59, 12.3, 5 ∗ 1.223};

The PDT configuration file given in Appendix A shows clearly how datasets can be initialized.

2.1.5 Static Datasets

By default a dataset will reside on the heap, the portion of memory that is used by C when dynamically allocating memory to a routine. This provides the ability to tailor, at runtime, the amount of memory used by an application. The drawback to this scheme is that it does require a small amount of overhead to initially allocate the dataset memory. Normally this overhead is not noticeable but in certain instances, such as attempting to allocate individual datasets that approach the size of primary memory, this overhead can become substantial. In these instances it is generally more efficient to statically allocate the dataset, which places it on the runtime stack. This will reduce the startup time at the expense of not being able to modify the size of the dataset during program execution. Statically allocating a dataset is accomplished using the following construct.

STATIC : < name1 >, < name2 >, ⋯, < nameN >;

where < name1 >, ⋯, < nameN > are the name of datasets that have been previously defined.

2.2 PCT Syntax

The PCT configuration file establishes which routines will be used, the order in which they will be used, and the parameters that are to be passed to each. The syntax of the PCT file is as follows:

< T itle >; [ < comment >]
< EOL >; [ < comment >]
< EOI >; [ < comment >]
< Entry >; [ < comment >]
⋮  ⋮
< Entry >; [ < comment >]

where:

< T itle > ≡ Title of this PCT
< comment > ≡ anything between the semi–colon and the end of the line.
< EOL > ≡ Execution Order List
< EOI > ≡ Execution Order Index

When parsing the PCT file, the PCP assumes that the first line of the PCT file is the title, the second line is the execution order list, the third line is the execution order index, and the remaining lines are the entries.

< Entry >=< key >: < type >: < name >: < param list >; [ < comment >]

where:

< key > ≡ Unique character identifier for EOL
< type > ≡ One of : PN, CF, CS, FF, FS, DF, DS
PN ≡ Process Configuration Table (PCT)
CF ≡ “C” Function
CS ≡ “C” Subroutine
FF ≡ “FORTRAN” Function
FS ≡ “FORTRAN” Subroutine
DF ≡ “DataSet” Function
DS ≡ “DataSet” Subroutine
< name > ≡ Name of the executable module or PCT
< param list > ≡ < parameter > | < parameter > , < param list > | < fname >
< parameter > ≡ | < identifier > | < ivalue > | < string >
< identifier > ≡ Name of a dataset or constant defined in the PDT
< ivalue > ≡ Integer value to be passed to < name >
< string > ≡ Quote enclosed character string to be passed to < name >
< fname > ≡ Name of PCT file defining PCT < name >

The use of the vertical bar (|) indicates “or”, i.e.

< parameter >≡ | < identifier > | < ivalue > | < string >

means that < parameter > is equal to (can be replaced by) an < identifier > or an < ivalue > or a < string >.

An entry can be one of two major types, a PCT (which is a recursive definition: a PCT can contain a PCT , which can contain a PCT ...), or an Executable. A PCT is identified by < type >= PN. It also has only one “parameter” in its parameter list, which is the name of the file containing the configuration information for that PCT node. An Executable node can be classified as one of several types depending on the way parameters are to be passed, via C language passing mechanism (“C”), via FORTRAN language passing mechanism (“F”), or the routine expects the dataset data structure to be passed (“D”), and if it returns a value (function “F”) or not (subroutine “S”).

The C language parameter passing mechanism implies that the routine is written in C according to the following conventions:

• Parameters are passed by reference, not by value, so the C routine should expect a pointer to the data object, not the data object itself.

• Each additional dimension, after the first, on a multidimensional array requires an additional level of indirection. i.e. if the dataset to be passed to a C routine has been declared REAL: arr3: m1,m2,m3 then within the C routine it should be declared as float ***arr3;. Subsequent manipulation can be accomplished as though the declaration had been float arr3[m3][m2][m1]. Note the reversed dimension declarations. This is necessary because C uses row–major ordering for multi-dimensional arrays, where FORTRAN uses column–major ordering. The array declaration syntax for the PDT file was designed to be consistent with the FORTRAN convention, column–major ordering.

• Strings are NULL terminated, BLANK filled character arrays whose length is specified in the PDT file.

The parameter passing mechanism for S^{3} attempts to make interfacing FORTRAN routines as simple and straight forward as possible. For the most part a standard FORTRAN approach with some minor restrictions was used to handle parameter passing. Specifically the FORTRAN routine should:

• Declare strings passed as parameters to have “previously defined limits”, i.e. the size of the string was declared in the calling program. This declaration is accomplished via

CHARACTER*(*) string.

• Declare arrays as predefined (similar to the string declaration) or explicitly include the array’s dimensioning information in the parameter list. Dimensioning arrays within a routine to a different size (particularly a larger size) than was declared in the PDT file will lead to unpredictable results. (Note: there is a run time option that will perform runtime bounds checking upon exit from each routine call from a PCT)

Each dataset that is declared in the PDT and subsequently used in a PCT has associated with it some bookkeeping information that is maintained by the S^{3} program. This includes such information as the name of the dataset, the type of the data, the number of dimensions, the size of each dimension, and a pointer (memory address) to the beginning of the data. Most of the time the user does not need to access this information and will simply want the data (or rather a pointer to the data - FORTRAN passes parameters by reference to the data by default), which is what a routine declared as “C” or “F” will have passed to it. On the other hand, a routine declared as “D” will have the entire dataset data structure passed to it. Such a routine can then modify any of the bookkeeping information about the dataset. Care should be taken when modifying dataset information in this way, since such modifications could have unpredictable results.

In general, routines written in FORTRAN will be either “FF” or “FS”, routines written in C will be either “CF” or “CS”. The “DF” and “DS” types are used only when it is necessary to manipulate the entire dataset data structure instead of just the data.

An executable classified as a function (“F”) is expected to return an integer value. This value is in turn used to modify how the system is functioning. A return value of zero (0) indicates that the PCT should continue executing according to the Execution Order List and Execution Order Index. A return value of one (1) indicates that the PCT should halt at this point and return control to the calling or parent PCT node. The next time the child PCT node is called, it will pick up where it left off by starting to execute at the next routine indicated in the Execution Order List. A return value of greater than one (1) specifies how many levels of PCTs to ascend. (A return value of 2 would mean to halt this PCT and the parent PCT, 3 would mean to halt this PCT, the parent PCT, and the grandparent PCT, etc.)

2.3 PCP Syntax

The Process Control Program performs two major functions. First it creates and initializes the S^{3} runtime environment, and then it calls (executes) the appropriate routines as specified by the PCT files. The PCP has several command line options that affect overall execution. The user can specify an alternate base name for the primary PCT and PDT files, i.e. if the user specifies a base name of foo then the PCP will look for the two files foo.pdt and foo.pct. Otherwise the PCP will look for the two files program.pdt andprogram.pct. Execution of the PCP will then continue based on the files specified. The user has a choice of several operating modes;

• Normal mode (default) displays no information about the execution progress.

• Bounds check mode (-b command line option) checks for dataset bounds violations (modifying memory beyond the limits of a dataset) after each routine called at the PCT level.

• Profile mode (-p command line option) displays cumulative execution statistics concerning how many times each routine was called and the total time spent in each routine.

• Verbose mode (-v command line option) displays information concerning which routine is currently executing and how much time was required for that routine to execute.

Extensions to the capabilities of the PCP are primarily added via the S^{3} utilities library. The current utilities library provides PCT looping constructs DSZ (decrement and skip if zero) and ISE (increment and skip if equal), conditional branching (if then else), file copying, and creation of child processes via a system call. These routines are discussed in greater detail in the Appendices.

2.4 S^{3} Based Implementation

To create an S^{3} based program the user needs to determine which routines will be called, what order they will be called in, and the type, size and dimensionality of each parameter required by the particular routine. The user then creates PDT and PCT files based on this information. The PDT file is used to define the size, type, and dimensionality of each variable that will be passed to the various routines. The PCT files are used to define which routines are called, what order they are called in, and which parameters are passed to them. As a starting point, in addition to the S^{3} library and PCP main routine, the S^{3} package includes a basic set of routines for analyzing data generated by the SAFIRE instrument. These routines are supplied in two libraries, the GATS LINECAL library of limb line-by-line radiance profile routines, and the SDAS library of data analysis routines specifically tailored for the SAFIRE instrument data.

In many situations the S^{3} library (and PCP main routine) combined with the SDAS data analysis routines will satisfy the researcher’s processing and analysis needs. In other situations the researcher will want to include their own routines in the S^{3} hierarchy for a particular aspect of processing. Both situations are discussed in greater detail below.

2.4.1 Initial Installation

Before an S^{3} program can be created, the S^{3} package must be installed. The S^{3} software package is currently supported only on AIX 3.1.5 (IBM’s version of UNIX) running on the IBM RS/6000 architecture. Work is in progress to port S^{3} to Sun OS 4.1.1 running on the Sun Sparc architecture. To be installed on a particular system, the S^{3} package requires the system to have both a FORTRAN 77 compiler and a C compiler (preferably ANSI C compliant). The S^{3} Reference Manual S^{3} software package is supplied in UNIX tar file format. To install S^{3} on a UNIX system simply follow the steps given below.

1. Create a temporary directory for use during the installation process. Although the directory can have any legal name, for purposes of these instructions it will be called TEMP.

2. Place the S3.tar file in TEMP.

3. Type tar -xvf S3.tar >& tar.log

4. After the tar command finishes, the following files should be in TEMP:

   (a) Makefile
   (b) Manifest
   (c) README
   (d) Version
   (e) tar.log

and the following subdirectories:

   (a) Linecal

(b) S3

   (c) SDAS

5. Compare Manifest to tar.log. They should contain the same filenames. If not, you should contact G & A Technical Software.

6. Decide where various files needed by the S^{3} package will be located:

(a) Set the environmental variable S3SRCDIR to the directory that will contain the

       S^{3} PCP source file (s3main.c) (for example setenv S3SRCDIR /usr/local/src ).

(b) Set the environmental variable S3INCDIR to the directory that will contain the S^{3} include (header) files (for example setenv S3INCDIR /usr/local/include ).

(c) Set the environmental variable S3LIBDIR to the directory that will contain the S^{3} , SDAS, and LINECAL libraries (for example setenv S3LIBDIR /usr/local/lib ).

(d) Set the environmental variable S3BINDIR to the directory that will contain the

       S^{3} setup utility program (for example setenv S3BINDIR /usr/local/bin ).

The particular directories specified above are examples for installing the S^{3} package on a system where multiple users will be using the package and would probably require help from the Systems Administrator (the installation process needs write access to the specified directories). For a single user, simply set the environmental variables to specify directories within the users directory structure. The environmental variables specified will be used both during the installation process and every time the S^{3} based program is reconfigured, so it is advisable to make them a permanent part of the environment (i.e. have them set during the login process via either the .cshrc or .login files for the csh or tcsh user shell, or the .profile file for the sh or ksh user shell.

7. Once the environmental variables have been set, make sure you are in the TEMP directory and type make >& make.log. This process compiles and creates the libraries that are used by the S^{3} system and will take several minutes to complete.

8. Once the make process has been successfully completed (check make.log for any error messages), now type make install >& install.log. The install process will copy the appropriate files to the directories specified by S3SRCDIR, S3INCDIR, S3LIBDIR, and S3BINDIR (requires write access to these directories).

The initial installation is now complete.

2.4.2 Creating S^{3} Application Programs

Once the S^{3} package has been installed, the user can begin to create application programs. As a first step copy the file Makefile.s3 from the S3SRCDIR and rename it Makefile(i.e. cp S3SRCDIR/Makefile.s3 Makefile). As mentioned previously, the S^{3} package provides the appropriate routines to perform basic limb profile retrievals. To create an S^{3} program example2 that will only use routines in the SDAS or LINECAL libraries, the user will need to create a PDT example2.pdt file defining the required parameters and a primary PCT file example2.pct defining the routines used, the parameters to be passed to them, the order in which they are called, and any secondary PCT files that are to be used. The user must also create any secondary PCT files required. Modify the the line in Makefile that reads NAME = safire to read NAME = example2. Now simply type make and if no errors are encountered, an executable program file named example2 will be created in the current directory. This process of S^{3} program creation is shown diagrammatically in figure 4, where the make process is represented by the thick lined box.

Since for this example, all the executable routines are provided with the S^{3} package, once the program has been created, the only time that it would be necessary to do a make is when:

1. Adding a new routine to a PCT file (i.e. adding a routine that is not in one of the PCT files).

2. Changing the name, size, type or dimensionality of a dataset that is declared STATIC in the PDT file.

Adding routines that are not provided with the S^{3} package, i.e. user defined routines, is covered in the reference section 2.4.3.

2.4.3 Adding User Defined Routines

Adding a user defined / created routine to an S^{3} based program is accomplished by:

1. Specifying the user routine in the appropriate PCT file(s).

2. Defining the required datasets in the PDT file.

3. Specifying the location of the user routine in Makefile.

4. Typing make

The Makefile assumes that the user routine will be available in one of two forms, source code (FORTRAN or C) in a file in the current directory, or in a previously compiled library (see figure 4) To include a routine that is in a source file, simply modify the USROBJS = line in the Makefile to include the name of the source file with a .o extension (i.e. if the source code is in a file named routine.f, modify the USROBJS = line to read USROBJS = routine.o). This will cause make to compile the source file and link it to the S^{3} program. Anytime the source file is modified, a make should be performed. To include a routine that is in a precompiled library, simply modify the USRLIBS = line in the Makefile to include the pathname of the library (i.e.

if the library is /u/jcburt/lib/libjunk.a, modify the USRLIBS = line to read USRLIBS =

/u/jcburt/lib/libjunk.a). In this case, the user is responsible for ensuring that the specified library is current, make will not be able to determine if the library is up-to-date.

2.4.4 Running S^{3} Application Programs

To run an S^{3} based program, simply type in its name followed by any command line switches. If we wanted a verbose execution of example with a execution profile displayed at the end,

simply type example -v -p. example will then read the files example.pdt and example.pct,

and then perform the operations specified in the PCT file(s) (see figure 3). If a new routine was added with out subsequently performing a make the S^{3} program will halt with an error message indicating that it can’t find the routine. If this occurs, simply run make which should correct the problem.

\underline{S^{3} Example}

A S^{3} Example

\underline{S^{3} Example}

Figure 5: PCT Structure for S^{3} Example

A.1 Example PDT configuration file

;
; Constants used by the Safire system
;
CONST:  nl     =    9000;
CONST:  mir    =      10;
CONST:  ml     =      32;
CONST:  mr     =      64;
CONST:  mgg    =      20;
CONST:  mgs    =       4;
CONST:  mpts   =  200000;
CONST:  msiz   = 6000000;
CONST:  mqmix  =     128;   (ml * mgs)
CONST:  mpmass =    8192;   (ml * ml * mgs * 2)
CONST:  mtbs   =    2048;   (ml * ml * 2)
CONST:  natmos =       8;
;
; Definition of the datasets used by the Safire system
;
;
; Datasets of type STRING
;
STRING: control  : 64 = "consaf.dat" ;
STRING: atmos    : natmos ;
STRING: nam      : mgg,8;
STRING: name     : mgs,8;
STRING: filen    : ml,32;
;
; Datasets of type DOUBLE (DREAL)
;
DREAL:  vs1      ;
DREAL:  vs2      ;

Figure 6: Constant, String, and Double segment of PDT for S^{3} Example - safire.pdt

;
; Datasets of type REAL
;
REAL:   dvel     := {0.0};
REAL:   hires    : mpts;
REAL:   temp     := {0.0};
REAL:   za       : ml ;
REAL:   re       ;
REAL:   xlat     ;
REAL:   qg       : 2,mqmix;
REAL:   zt       : ml;
REAL:   pt       : ml;
REAL:   tt       : ml;
REAL:   qmix     : mqmix;
REAL:   wnmax    := {20.0};
REAL:   zr       : mr;
REAL:   pr       : mr;
REAL:   tr       : mr;
REAL:   tgr      : 2,mr;
REAL:   gr       : 2,mr;
REAL:   q        : mr,mgg;
REAL:   qgr      : 2,mr,mgg;
REAL:   odmin    := {0.1E-09};
REAL:   resmax   := {0.0};
REAL:   resfc    := {0.3};
REAL:   pmw      : ml;
REAL:   tmw      : ml;
REAL:   tbs      : mtbs;
REAL:   pb       : ml;
REAL:   gasb     : mqmix;
REAL:   pmass    : mpmass;
REAL:   fact     :1 = {0.0};

Figure 7: Real segment of PDT for S^{3} Example - safire.pdt

;
; Datasets of type INTEGER
;
INT:    iblk     ;
INT:    iblko    :={0};
INT:    icnt     :={1};
INT:    icwrt    :={0};
INT:    iwrt     ;
INT:    ifrst    ;
INT:    iunit    : ml;
INT:    istatus  ;
INT:    idg      : mgs;
INT:    isc      := {1};
INT:    isco     := {0};
INT:    iopt     := {1};
INT:    icalc    := {2};
INT:    ioptt    := {1};
INT:    ir       : mir ;
INT:    iri      ;
INT:    irf      := {1};
INT:    imr      := {2};
INT:    iflag    := {2};
INT:    iopto    : ml;
INT:    igas     : mgs;
INT:    igs      : mgs;
INT:    igm      : mgs;
INT:    jtype    := {1};
INT:    nir      := mir;
INT:    ncel     ;
INT:    ngas     ;
INT:    npts     :=mpts;
INT:    nr       ;
INT:    nrun     ;
INT:    nsr      :={1};
INT:    nmr      :={60};
INT:    ngg      ;

Figure 8: Integer segment of PDT for S^{3} Example - safire.pdt

A.2 Example PCT configuration files

"
Safire Main Menu"        ;
abcdefghijklmpoanz              ;
0                         ;
a:FS:OPENFILES    :"consaf.dat",iflag,lcon,lpr,lout,lafg,lbug,\
                   lapd,lntrp,lifg;
b:FS:READCON      :iblk,vs1,vs2,ncel,za,temp,ngas,idg,ir,nir;
c:FS:READDATA     :atmos,re,xlat,mr,nr,ngg,nam,igs,zr,\
                  pr,tr,tgr,q,qgr,temp;
d:FS:SETOPT1      :ngg,ngas,igm,nam,name,idg,igs,igas;
e:DF:GET_ELEMENT1 :iri,ir,icnt;
f:PN:FORWARD      :forward.pct;
g:DF:SET_EOI      :"FORWARD",3;
h:PN:APODIZE      :apodize.pct;
i:DF:SET_EOI      :"APODIZE",0;
j:PN:INTERPOLATE  :interpolate.pct;
k:DF:SET_EOI      :"INTERPOLATE",0;
l:PN:INTERFEROGRM :interferogrm.pct;
m:DF:SET_EOI      :"INTERFEROGRM",0;
n:DF:ISE          :icnt,nir,4;
o:FS:CLOSEFILES   :;
p:CS:CALL_SYS     :"xterm -e idl";

Figure 9: Primary PCT for S^{3} Example - safire.pct

"
Forward Radiance Calculation"        ;
abcdefz              ;
0                         ;
a:FS:AFGLSET      :jtype,idg,ngas,vs1,vs2,wnmax;
b:FS:MASS         :ncel,nr,irf,imr,nsr,ncel,igm,ngas,isc,re,\
                   za,zr,pr,tr,tgr,q,qgr,zt,pt,tt,gr,qmix,qg,\
                   pmw,tmw,tbs,pb,gasb,pmass,fact;
c:FS:CROSS        :nrun,iopt,icalc,ncel,ncel,idg,ngas,vs1,vs2,\
                   wnmax,resfc,resmax,odmin,nsr,ncel,zt,pb,tmw,\
                   gasb,pmass,icwrt,iwrt,ifrst,iunit,istatus,filen;
d:FS:INGRATE      :icalc,iopt,iopto,iwrt,iunit,ncel,ncel,igas,\
                   ngas,vs1,vs2,dvel,iri,iri,tbs,pmass;
e:FS:GETHIRES     :npts,bpwn,epwn,resmin,hires;
f:FS:SPECWRITE    :lout,iflag,iri,npts,bpwn,epwn,resmin,hires,zt;

Figure 10: Forward Radiance Calculation for S^{3} Example - forward.pct

"
Generate the Apodized Spectra" ;
abcdefghijklmz ;
0 ;
a:FS:GETSPC        :nrd2,npts,hires,rad,crad,k3;
b:FS:ARRAY         :rad,radd,nrd2,nrd1,1;
c:FS:FOUR1         :radd,nrd2,1;
d:FS:CALC_NPSF_RES :npsf,res,flaser,ssp,lm;
e:FS:CALC_J1_J2_NP :j1,j2,np,npts,resmin,res,nrd2;
f:FS:CMPX          :crad,radd,nrd2,nrd1,1;
g:FS:CUT           :crad,j1,j2,nrd2;
;g:FS:CUT           :crad,0,131072,nrd2;
h:FS:CMPX          :crad,radd,nrd2,nrd1,-1;
i:FS:FOUR1         :radd,nrd2,-1;
j:FS:NORM2         :radd,nrd1;
k:FS:ARRAY         :rad,radd,nrd2,nrd1,-1;
l:FS:RADPF         :rad,rad1,nrd2,npts,k3;
m:FS:SPECWRITE     :lapd,iflag,iri,npts,bpwn,epwn,resmin,rad1,zt;

Figure 11: Apodization Calculation for S^{3} Example - apodize.pct

"
Generate the Interpolated (low resolution) Spectra" ;
abcz ;
0 ;
a:FS:CALC_R0    :r0,rad;
b:FS:SSINTERP   :np,npts,res,resmin,rad1,a,r0,r0;
c:FS:SPECWRITE  :lntrp,iflag,iri,np,bpwn,epwn,res,a,zt;

Figure 12: Interpolation Calculation for S^{3} Example - interpolate.pct

"
Generate the Simulated Interferogram" ;
abcdez ;
0 ;
a:FS:MIRROR     :radfull,a,npsf,np,res;
b:FS:COSFT      :radfull,npsf,-1;
c:FS:NORM2      :radfull,npsf;
d:FS:INTF       :radfull,r,npsf,nnk;
e:FS:SPECWRITE  :lifg,iflag,iri,nnk,bpwn,epwn,res,r,zt;

Figure 13: Interferogram Calculation for S^{3} Example - interferogrm.pct S^{3} Utility Routines

B S^{3} Utility Routines

The following pages contain descriptions of the S^{3} utility routines. The primary purpose of these routines is to provide the user access to the Execution Order Control information stored in the Process Control Table(s), and to perform some simple operations on datasets.

\underline{get eol}

Purpose Gets the current Execution Order List (EOL) for the specified Process Control Table (PCT).

C Syntax #include "defs.h" #include "safire.h"

char *get eol ( char *PCTname )

FORTRAN Syntax

CHARACTER*64 FGET EOL(PCTNAME) CHARACTER PCTNAME*32

PDT Entry STRING : PCTname : 32 ; STRING : EOL : 64 ;

PCT Entry a : DS : GET EOL : PCTname, EOL ;

Remarks get eol gets the current Execution Order List (EOL)for the PCT specified by PCTname. The returned value is a NULL terminated character string. If PCTname is not a valid PCT name, get eol aborts the program and returns an error message.

See Also set eol, get eoi, set eoi

Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{get eoi}

Purpose Gets the current Execution Order Index (EOI) for the specified Process Control Table (PCT).

C Syntax #include "defs.h" #include "safire.h"

int get eoi ( char *PCTname )

FORTRAN Syntax

INTEGER*4 FGET EOI(PCTNAME) CHARACTER*(*) PCTNAME

PDT Entry STRING : PCTname : N ; INT : EOI ;

PCT Entry a : DS : GET EOI : PCTname , EOI ;

Remarks get eoi gets the current Execution Order Index (EOI) for the PCT specified by PCTname. The returned integer value is an index into EOL for PCTname indicating the next entry in the PCT PCTname to be executed. If PCTname is not a valid PCT name, get eoi aborts the program and returns an error message. NOTE: EOL is a array of characters with array locations starting at 0 in accordance with C syntax (as opposed to FOR-TRAN syntax where character arrays start at location 1). This means that values returned by get eoi start at 0 for the 1st location, 1 for the second location, etc.

See Also set eoi, get eol, set eol

Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{set eol} Purpose Sets the current Execution Order List (EOL) for the specified Process Con-

trol Table (PCT).

C Syntax #include "defs.h" #include "safire.h" void set eol ( char *PCTname, char *EOL )

FORTRAN Syntax

CHARACTER PCTname*32, EOL*64 FSET EOL(PCTname, EOL)

PDT Entry STRING : PCTname : 32 ;

STRING : EOL : 64 ;

PCT Entry a : DS : SET EOL : PCTname, EOL ; Remarks set eol sets the current Execution Order List (EOL) for the PCT specified

by PCTname to the string specified by EOL. If PCTname is not a valid PCT name, set eol aborts the program and returns an error message.

See Also get eol, get eoi, set eoi Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{set eoi}

Purpose Sets the current Execution Order Index (EOI) for the specified Process Control Table (PCT).

C Syntax #include "defs.h" #include "safire.h"

void set eoi ( char *PCTname, int EOI )

FORTRAN Syntax

CHARACTER PCTNAME*32 INTEGER*4 EOI FSET EOI(PCTNAME, EOI)

PDT Entry STRING : PCTname : 32 ; INT : EOI ;

PCT Entry a : DS : SET EOI : PCTname, EOI ;

Remarks set eoi sets the current Execution Order Index (EOI) for the PCT specified by PCTname to the value specified by EOI. If PCTname is not a valid PCT name, set eol aborts the program and returns an error message.

See Also get eoi, get eol, set eol

Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{incr} Purpose Increments the value contained in dataset DSname by amount INCby. This

routine is to be used as a PCT entry only.

PDT Entry INT : DSname ;

INT : INCby = {10} ;

PCT Entry a : DS : INCR : DSname, INCby ; Remarks DSname must be a zero dimensional integer dataset (i.e. a simple variable).

INCby can be a zero dimensional integer dataset, a constant (as declared in the PDT configuration file) or an integer numeric value.

See Also decr Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{decr} Purpose Decrementss the value contained in dataset DSname by amount DECby.

This routine is to be used as a PCT entry only.

PDT Entry INT : DSname ;

INT : DECby = {10} ;

PCT Entry a : DS : DECR : DSname, DECby ; Remarks DSname must be a zero dimensional integer dataset (i.e. a simple variable).

DECby can be a zero dimensional integer dataset, a constant (as declared in the PDT configuration file) or an integer numeric value.

See Also incr Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{resize}

Purpose Alters the size of a multi-dimensional (i.e. 1 or more dimensions) dataset by modifying the value of the declared dimension size(s).

PDT Entry DREAL : DSname : oldsize1, oldsize2 ;

PCT Entry a : DS : RESIZE : DSname : newsize1, newsize2 ;

Remarks Currently RESIZE only modifies the value of the dimension size(s), no new space is allocated (perhaps in version 2.0 ?). What this means is that newsize ≤ oldsize, otherwise a memory (segmentation) fault will occur when trying to access the “additional” memory.

Author John Burton, G & A Technical Software Inc. 07/08/91 \underline{ise}

Purpose Provides a looping construct within a PCT node via Increment and Skip when Equal.

PDT Entry INT : Count; INT : End ; INT : Index;

PCT Entry a : DS : ISE : Count, End, Index ;

Remarks ise compares the value of Count to End. If Count is less than End then ise sets the EOI for the current PCT to Index and increments Count by one. If em Count is greater than or equal to End then ise simply returns.

See Also dsz

Author John Burton, G & A Technical Software Inc. 10/09/91 \underline{dsz} Purpose Provides a looping construct within a PCT node via Decrement and Skip

when Zero.

PDT Entry INT : Count; INT : End ; INT : Index;

PCT Entry a : DS : DSZ : Count, Index ; Remarks dsz decrements the value of Count by one. If Count is equal to zero then

dsz sets the EOI for the current PCT to Index.

See Also ise Author John Burton, G & A Technical Software Inc. 10/09/91 \underline{if then else} Purpose Provides a conditional branching construct within a PCT via If-Then-Else. PDT Entry INT : Test ;

INT : Tindex; INT : Findex;

PCT Entry a : DS : IF THEN ELSE : Test, Tindex, Findex ; Remarks if then else conditionally branches based on the value of Test. If (Test !=

0) then set the EOI for the current PCT to Tindex. If (Test == 0) then set the EOI for the current PCT to Findex.

Author John Burton, G & A Technical Software Inc. 10/09/91 \underline{call sys} Purpose Provides access to operating system commands and programs external to

the S^{3} program.

PDT Entry STRING : command : 32; PCT Entry a : DS : CALL SYS : command ; Remarks call sys causes a process to be spawned by the S^{3} program. The child

process can either block or not block the parent S^{3} program. The spawned process will execute the program or command command.

Author John Burton, G & A Technical Software Inc. 10/09/91 \underline{copyf}

Purpose Copies a file from pathname file1 to pathname file2 using the UNIX cp command.

PDT Entry STRING : file1 : N; STRING : file2 : N;

PCT Entry a : DF : COPYF : file1, file2 ;

Remarks copyf copies the source file or source directory named by the file1 parameter to the target file or target directory named by the file2 parameter. file1 and file2 can be either a full pathname or a relative pathname. file1 may contain wildcard characters, em file2 should not contain wildcard characters.

Author John Burton, G & A Technical Software Inc. 10/09/91