A Standard Input Format for Computer Codes Which Solve Stochastic Programs with Recourse and a Library of Utilities to Simplify its Use

NOT FOR QUOTATION WITHOUT PERMISSION

OF THE AUTHOR

A STANDARD

INPUT

M)R16AT

FDR COMPUTER CODES

WDCH

SOLVE SrOCHASIlC

_PROGRAMS

WITH RECOURSE AND A LIBRARY OF

WILITES

TO

_SIKPIJFY ITS USE

Jonathan Edwards John Birge

Alan King Larry Nazareth

January 1985 WP-85-03

Working Papers a r e interim reports on work of t h e International Institute for Applied Systems Analysis and have received only limited review. Views o r opinions expressed herein do not necessarily represent those of t h e Institute o r of i t s National Member Organizations.

INTERNATIONAL INSTITUTE FOR APPLIED SYSTEMS ANALYSIS 2361 Laxenburg. Austria

We explain our suggestions for standardizing input formats for computer codes which solve stochastic programs with recourse. The main reason t o s e t some conventions is t o allow programs implementing different methods of solution t o be u s e d interchangeably. The general philosophy behind our design is a ) t o remain fairly faithful t o the de f a c t o standard for t h e statement of LP problems established by IBM for use with M P S X a n d subsequently adopted by t h e authors of MINOS, b) t o provide sufficient flexibility so t h a t a variety of problems may be expressed in t h e standard format, c) t o allow problems originally formulated as deter- ministic LP t o be converted t o stochastic problems with a minimum of effort, d) t o permit new options t o be added as t h e need arises, and e) t o provide some routines t o facilitate t h e task of reading files specified in t h e standard format.

Developing methodology and tools for optimal decision making under u n c e r t a i n t y was always a major p a r t of r e s e a r c h in System a n d Decision Sciences Area. For t h e l a s t two years, t h e Adaptation a n d Optimization P r o j e c t was involved in developing methods and computer implementa- tions for one of t h e important p a r t s of s u c h methodology -- stochastic programming.

This paper is among those which describes one of t h e r e s u l t s of t h e s e efforts -- t h e collection of r o u t i n e s designed t o solve stochastic programming problems. I t contains a description of standardized input formats f o r some of t h e routines of t h i s collection, a n d a l i b r a r y of utili- t i e s t o simplify i t s use.

AB. Kurzhanski Chairman

System a n d Decision Sciences Program

Introduction

Over t h e past six months, the Adaptive Optimization project of t h e Systems and Decision Sciences program a t t h e International Institute for Applied Sys- tems Analysis has collected a number of computer programs written t o solve various problems in stochastic programming. Our goal h a s been to organize these codes so t h a t they may be distributed on magnetic t a p e to researchers, who might benefit from having several algorithms with which t o experiment.

However, we have come t o realize t h a t t h e process of tinkering with t h e various methods will be greatly complicated because each program h a s its own format for input ,data. We have therefore developed a standard input format for sto- chastic programs with recourse. To encourage and simplify i t s use, we have based i t on t h e input format developed by IBM for t h e extended Mathematical Programming Subsystem

(MPSX)

(IBM, 1972) and adopted by t h e authors of the Modular In-core Nonlinear Optimization System (MINOS) (Murtagh and Saunders, 1977) and we have written a number of low level subroutines t o read files written in t h e standard format.

The Problem

The general form of t h e stochastic program with recourse is taken to be

minimize cx

+

^{Q(z) (1)}

subject to

where

$x$ and $y$ denote t h e decision and recourse variables, respectively, $chi$

denotes an event, T($chi$) and W($chi$) denote t h e technology and recourse matrices, respectively. and $ roman

E

s u b chi $ denotes expectation. In subse- quent references t o t h e technology matrix, t h e recourse matrix, t h e stochastic right hand side, $p( chi )$, a n d t h e penalty function, $q(y, chi )$, we omit t h e arguments $y$ and $chi$.

Organization of the Data: Control, Core. a n d Stochastics Files

The data required by a program written t o solve t h e stochastic program in (1) can be divided logically into t h r e e files: a control file, a "core" file, and a

"stochastics" file. Roughly speaking, t h e control file contains a n y data particu- lar to t h e program and t h e core and stochastics files contain t h e data t h a t define t h e problem.

As its name implies, t h e control file contains a n y information t h a t is used t o guide t h e execution of t h e program. For example, t h e control file might include a limit on t h e n u m b e r of steps permitted a n d a tolerance for conver- gence if the algorithm implemented in t h e program were iterative in nature, file name and unit number assignments if the program required several files, or upper limits on t h e a m o u n t of storage needed if t h e program allocated array space "dynamically." The control file also contains any information t h a t m u s t be read before t h e program profitably can read t h e contents of t h e matrices

and vectors t h a t appear in t h e problem, e.g., t h e dimensions of those struc- tures. Because t h e contents of the control file depend heavily on the algorithm employed and t h e m a n n e r in which i t is implemented, we have not included a standard format for control files. Indeed, t h e rigid structure of the format we propose (particularly its strict use of specific columns as field delimiters) makes it unsuitable for application to files whose contents are liable to change frequently.

The core flle contains the bounds on the decision vector, $x$, t h e contents of the matrices by which it is multiplied, and t h e contents and ranges of t h e rows of the deterministic right hand side vector, $b$. The core file for a sto- chastic LP thus corresponds in large measure t o the data file t h a t MPSX or MINOS would require t o solve t h e equivalent nonstochastic LP (i.e., t h e same problem with $Q(x)$ removed).

The stochastics file defines t h e technology matrix, T, t h e distribution of the rows of t h e stochastic right hand side vector, $p$, the contents of t h e recourse matrix, W, and the function $q$. We have chosen to partition t h e input in this fashion so t h a t a problem originally formulated as a linear pro- gram and expressed in standard MPSX format may be augmented later by a sto- c h a s t i c ~ file, thereby permitting certain elements (e.g., t h e right hand side) to be stochastic.

Overview of the Standard Input Format

The proposed format is quite similar to t h e MPSX format, which is described on pages 199 through 209 of (IBM, 1972), although t h e r e a r e some differences. As in t h e MPSX format. each data file contains a number of sec- tions, some of which a r e optional. A "header line" (or "header") marks t h e beginning of each sectiont. Most sections contain data lines. A data line is divided into six fields, some of which may be empty. Specific columns delineate field boundaries. There a r e t h r e e n a m e fields, two numeric field., and a code field- The columns t h a t constitute these fields a r e

-

^columns 2 a n d 3: code field

-

columns 5 through 12:

&st

name field

-

^columns 15 through 22: second name field

-

columns 25 through 36: flrst numeric field

-

columns 40 through 47: t h i r d name field

-

columns 50 through 61: second numeric field

(all column ranges a r e inciusive). Comment lines contain an asterisk (*) in the first column and m a y appear anywhere.

Unlike t h e MPSX format, names may contain imbedded blanks o r leading blanks (although this last is n o t recommended). The contents of the name fields are interpreted a s c h a r a c t e r strings, so names may begin with a digit. All lower case l e t t e r s in t h e code and name fields are translated to their upper case equivalents. Values in t h e numeric fields must contain a decimal point.

The

MPSX

convention concerning comments following a dollar sign ($) in t h e first column of t h e second or t h i r d name fields has not been adopted a s part of t h e standard format.

Following are descriptions of each of t h e data files. Each description con- tains a list of t h e sections t h a t constitute t h e corresponding data file. These

t

(IBM. 1972, p. 199) uses the term "indicator card" rather than header.

sections m u s t appear in t h e data 6 l e in t h e s a m e o r d e r a s t h e y a p p e a r in t h e list, although sections marked "optional" need not appear a t all.

The Core m e

The core file specifies

-

t h e linear portion of t h e objective, c ,

-

t h e c o n t e n t s of t h e constraint m a t r i x , A, a n d possibly t h e c o n t e n t s of t h e technology matrix, T, a n d of t h e recourse matrix,

W,

-

t h e deterministic right h a n d side, b ,

-

t h e bounds on t h e decision vector, z , a n d

-

t h e ranges on t h e r i g h t h a n d side.

The core file contains t h e following sections: "NAME." "ROWS," "COLUMNS,"

"RHS," "RANGES," "BOUNDS," a n d "ENDATA" These s e c t i o n s a s s u m e m o r e o r less t h e s a m e role in t h e s t a n d a r d f o r m a t a s they do in t h e

MPSX

f o r m a t . Therefore, we give only an abbreviated description of t h e s e s e c t i o n s a n d n o t e differences between t h e s t a n d a r d format a n d t h e MPSX format.

1.

NAME -

This is a n informative h e a d e r line ( t h e s e c t i o n contains n o d a t a lines). The u s e r m a y e n t e r a n y c h a r a c t e r s desired in c o l u m n s 15 t h r o u g h 72 ( t h e MPSX format r e s t r i c t s n a m e s t o eight a l p h a n u m e r i c c h a r a c t e r s ) . 2.

ROWS -

As in t h e MPSX format, t h i s section specifies t h e n a m e s of t h e rows

of A, t h e n a m e of t h e row in t h e COLUMNS s e c t i o n t h a t contains t h e ele- m e n t s of c , and t h e type of c o n s t r a i n t (equality o r inequality) r e p r e s e n t e d by e a c h row. In s o m e cases, t h i s section also specifies t h e n a m e s of t h e rows of T. Rows formed by a l i n e a r combination of two o t h e r rows (type

"Do

rows) a n d scaling of rows ( u s e of t h e "'SCALE"' keyword) a r e s u p p o r t e d in t h e

MPSX

format b u t a r e n o t p e r m i t t e d in t h e s t a n d a r d format.

3.

COLUMNS

- As in t h e MPSX f o r m a t , this section specifies t h e n a m e s of t h e columns of A and of c a n d contains t h e values of t h e n o n z e r o e l e m e n t s of A a n d of c . In some cases, t h i s section also specifies t h e n a m e s of t h e columns of W, contains t h e n o n z e r o e l e m e n t s of W, and/or c o n t a i n s t h e nonzero e l e m e n t s of T. Scaling of columns ( u s e of t h e "'SCALE"' keyword) i s supported in t h e MPSX f o r m a t b u t is n o t p e r m i t t e d in t h e s t a n d a r d for- mat.

4.

RHS -

This section specifies t h e names of t h e rows of b a n d c o n t a i n s t h e values of t h e nonzero e l e m e n t s of b . This section is identical t o i t s coun- t e r p a r t i n t h e MPSX format.

5 .

RANGES

(optional)

-

This section specifies the r a n g e s on t h e rows of b

.

This section i s identical t o i t s c o u n t e r p a r t in t h e MPSX format.

6 .

BOUNDS

(optional)

-

This section specifies t h e bounds on t h e rows of t h e decision vector, z. This section i s identical t o i t s c o u n t e r p a r t in t h e MPSX format.

7.

ENDATA -

This line m a r k s t h e e n d of t h e core file ( t h e section c o n t a i n s n o d a t a lines) a n d i s identical t o i t s c o u n t e r p a r t i n t h e

MPSX

format.

The

Stochastics Kle

The stochastics file specifies

-

t h e c o n t e n t s of t h e technology matrix, T,

- t h e distribution of t h e stochastic r i g h t h a n d side, p ,

-

t h e c o n t e n t s of t h e recourse matrix, W, a n d

-

t h e form of t h e penalty function, q .

The stochastics file contains t h e following sections: "NAME," "TECHNOLOGY,"

"DISTRIBUTIONS," "RECOURSE," "OBJECTIVES," a n d "ENDATA." After t h e "OBJEC- TIVES" section additional sections may appear containing d a t a particular to a given algorithm. A program should r e a d only those sections i t needs from t h e file and should ignore t h e rest.

Most sections m a y take one of several forms, and t h e u s e r m u s t e n t e r t h e n a m e of one of t h e m beginning in column 15 of t h e h e a d e r line. A description of each of t h e sections, t h e forms they m a y assume, a n d t h e i r c o n t e n t s follows.

1. NAME - This is an informative h e a d e r line ( t h e section contains no d a t a lines). The u s e r may e n t e r any c h a r a c t e r s desired in columns 1 5 through 72.

2.

TECHNOLOGY -

This section specifies t h e c o n t e n t s of T. The section m a y take o n e of t h e forms whose n a m e s follow:

DETERMINISTIC ( t h e elements of T follow)

-

The technology m a t r i x is given by t h e d a t a following t h e section header. The format of t h e d a t a is identi- cal t o t h a t of t h e COLUMNS section of t h e core file, i.e., t h e c o n t e n t s of t h e m a t r i x a r e specified in column order. The first n a m e field on a line (columns 5 through 12) contains t h e n a m e of t h e column. The remaining n a m e / n u m e r i c field pairs (columns 1 5 through 22/25 t h r o u g h 36 and 40 through 47/50 through 61) specify a row n a m e and t h e c o n t e n t s of t h e m a t r i x a t t h e position given by t h e row a n d column names. The row n a m e s form a subset of t h e row n a m e s in t h e ROWS section of t h e core file.

CORE ( t h e e l e m e n t s of T appear in t h e c o r e file)

-

The data consists of a list of n a m e s which form a subset of t h e n a m e s specified in t h e ROWS section of t h e c o r e file. The contents of t h e s e rows (as specified in t h e COLUMNS sec- tion of t h e core file) constitute t h e technology matrix. One n a m e appears p e r line, in t h e first n a m e field (columns 5 through 12).

STOCHASTIC (the e l e m e n t s of T a r e supplied by a subroutine) - The d a t a consists of a list of t h e n a m e s of t h e rows of t h e technology matrix. Each row n a m e h a s associated with it one o r m o r e column names. The column n a m e s specify t h e active columns within t h e given row a n d form a subset of t h e column n a m e s specified in t h e COLUMNS section of t h e core file. The values for t h e technology matrix do n o t appear in e i t h e r d a t a file but are supplied by a subroutine written by t h e user. The row n a m e s appear in t h e first n a m e field of a line (columns 5 through 12) a n d t h e o t h e r two n a m e fields (columns 15 through 22 a n d 40 through 47) a r e available for t h e column narnes.

NONE (no data)

-

There is n o data. The u s e r m u s t decide where a n d how t o obtain t h e necessary values.

3. DmRIBUTIONS - This section specifies t h e distribution of t h e rows of p . The section m a y t a k e one of t h e forms whose n a m e s follow:

DISCRETE (each row is independently distributed)

-

Each row of p may take one of a fixed n u m b e r of values. The d a t a for t h i s form consists of a n u m b e r of "definitions," which a r e analogous to t h e "vectors" in t h e

RANGES a n d BOUNDS sections of t h e core file (see IBM, 1972). Each definition specifies t h e distribution of every row of p a n d consists of a n u m b e r of s e t s of e n t r i e s of the form "defname rowname value probabil- ity." Within a given definition, t h e r e is one such s e t for each of t h e rows n a m e d in t h e TECHNOLOGY section. "defname" is t h e n a m e of t h e definition t o which t h e e n t r y belongs; i t occupies t h e first name field on a line ( c o l u m n s 5 t h r o u g h 12). "rowname" is t h e n a m e of t h e row associated with t h e e n t r y ; i t occupies t h e second n a m e field on a line (columns 15 through 22). "value" a n d "probability" a r e a value for t h e row and i t s likelihood, respectively. They occupy t h e first and second n u m e r i c fields (columns 25 t h r o u g h 36 a n d 50 through 61), respectively.

The s u m of t h e probabilities for a given row m u s t be unity. The values specified for a given row m u s t be distinct. Entries for different rows or different definitions m u s t n o t be mixed together i n t h e input file.

As an example, l e t t h e T m a t r i x have two rows, TROW1 a n d TROW2, a n d define two distributions for t h e rows of p a s follows:

with probability

Row 2

= t

9 with probability

^1::

0.3 with probability Row 2

=

2 with probability 1.0

.

The c o n t e n t s of t h e n a m e a n d numeric fields for t h e s e distributions a r e shown in table 1. The u s e r specifies which is t h e desired definition (our definition n a m e s "DIST1" a n d "DIST2" were chosen arbitrarily) when t h e appropriate i n p u t utility i s called. Note t h a t every value contains a decimal point.

Table 1. Contents of a sample DISCRETE DISTRIBUTIONS section.

SIMULATION (the rows a r e supplied by a subroutine)

-

There a r e n o d a t a lines in t h i s case. The program obtains i t s values from a subroutine writ- t e n by t h e user.

First Name Field DISTl DISTl DISTl DISTl DISTl DISTl DISTl DIST2 DIST2 DIST2

PIECEWISE (piecewise c o n s t a n t pdf)

-

Each row of p t a k e s a value within one of a finite n u m b e r of ranges. Within a range, all values a r e equally likely. However. within a s e t of ranges. all r a n g e s a r e n o t equally likely.

The data for this form consists of a n u m b e r of "definitions," which a r e analogous t o t h e "vectors" in t h e RANGES a n d BOUNDS sections of t h e core file ( s e e IBM. 1972). Each definition specifies t h e distribution of every row of p and consists of a n u m b e r of s e t s of e n t r i e s of t h r e e lines e a c h . Within a given definition, t h e r e is one s u c h s e t for e a c h of t h e rows n a m e d in t h e TECHNOLOGY section. Each t h r e e line e n t r y within a s e t describes a r a n g e for t h e row associated with t h e set. The first line in a n e n t r y contains t h e l e t t e r s "PC" in t h e code field ( c o l u m n s 2 a n d 3), t h e n a m e of t h e definition t o which t h e e n t r y belongs in t h e first n a m e field ( c o l u m n s 5 through 12), t h e n a m e of t h e row with which t h i s r a n g e is associated in t h e second n a m e field (columns 15 through 22), a n d t h e probability t h a t t h e row t a k e s a value within t h e r a n g e in t h e first n u m e r i c field ( c o l u m n s 25 through 36).

The second a n d t h i r d lines in a n e n t r y specify t h e u p p e r a n d lower bounds of t h e range. For both bounds, t h e code field c o n t a i n s t h e l e t t e r s "BD", t h e first n a m e field contains t h e n a m e of t h e definition t o which t h e e n t r y belongs, t h e second n a m e field c o n t a i n s t h e n a m e of t h e row with which t h e r a n g e is associated, a n d t h e f i r s t n u m e r i c field c o n t a i n s t h e bound value.

Second Name

Field TROW1 TROW1 TROW1 TROW1 TROW2 TROW2 TROW2 TROW1 TROW1 TROW2

First Numeric

Field 1.0 2.0 3.0 4.0 8.0 9.0 0.0 2.0 4.0 2.0

The s u m of t h e probabilities for t h e ranges for a given row m u s t be unity.

Entries for different rows, different ranges, o r different definitions m u s t n o t be mixed t o g e t h e r in t h e i n p u t file.

Second Numeric

I

Field 1 0.4 0.2 0.2 0.2 0.6 0.3 0.1 0.5 0.5 1.0

As a n example, l e t t h e

T

m a t r i x have two rows, TROWl a n d TROW2, a n d define two distributions for t h e rows of p a s follows:

Row 1 i n with probability

[5,71 0.7

[1,3] with probability

[ o I 11

[2141

Row

'

^{i n} [[5,9] with probability Row 2 in [2,3] with probability 1.0

.

The c o n t e n t s of t h e code, n a m e a n d n u m e r i c fields for t h e s e distributions a r e shown in table 2. The u s e r specifies which i s t h e desired definition (our definition n a m e s "DIST1" a n d "DISTZ" were c h o s e n arbitrarily) when t h e appropriate i n p u t utility i s called. Note t h a t every value contains a decimal point.

Table 2. Contents of a sample PIECEWISE DISTRIBUTIONS section.

BD BD PC BD BD PC BD BD PC BD BD PC BD BD

SCENARIOS ( t h e value of p is defined by a sample of vectors)

-

The p vector m a y take one of a finite n u m b e r of values. The d a t a for this form consists of a n u m b e r of "definitions," which a r e analogous t o t h e "vectors" i n t h e RANGES and BOUNDS sections of t h e core file (see IBM, 1972). Each definition provides a sample of v e c t o r s a n d consists of s e t s of e n t r i e s giving a value for p a n d t h e probability t h a t p takes t h a t value. The first line in each e n t r y contains t h e l e t t e r s "SC" in t h e code field (columns 2 and 3), t h e n a m e of t h e definition t o mrhich t h e e n t r y belongs in t h e first n a m e field (columns 5 through 12), a n a m e identifying t h e s c e n a r i o in t h e second n a m e field (columns 15 t h r o u g h 22), a n d t h e probability t h a t p t a k e s t h e value associated with t h i s s c e n a r i o in t h e first n u m e r i c field (columns 25 t h r o u g h 36). Subsequent lines specify t h e values t h a t t h e rows of p a s s u m e under t h e scenario. There m u s t be one of t h e s e lines for e a c h row

DISTl DISTl DISTl DISTl DISTl DIST2 DIST2 DIST2 DIST2 DIST2 DIST2 DIST2 DIST2 DIST2

TROW2 TROW2 TROW2 TROW2 TROW2 TROW1 TROW1 TROW1 TROW1 TROW1 TROW1 TROW2 TROW2 TROW2

1.0 3.0 0.2 0.0 1.0 0.5 2.0 4.0 0.5 5.0 9.0 1.0 2.0 3.0

named in the TECHNOLOGY section. The code field of t h e s e lines contains t h e l e t t e r s "RV", t h e first n a m e field contains t h e n a m e of t h e defninition t o which t h e e n t r y belongs, t h e second n a m e field c o n t a i n s t h e n a m e of t h e row whose value t h e line specifies, and t h e first n u m e r i c field c o n t a i n s t h e value.

The s u m of t h e probabilities for the scenarios in a given definition m u s t be unity. Entries for different scenarios or different definitions m u s t not be mixed together in t h e input file.

As a n example. let the T m a t r i x have two rows, TROW1 a n d TROW2, a n d define two distributions of t h e vector p as follows:

Vector

=

{[3 41 with probability 10.3

a n d

Vector

=

with probability

The contents of t h e code, n a m e and n u m e r i c fields for t h e s e distributions a r e shown in table 3. The u s e r specifies which is t h e desired definition ( o u r definition names "SAMPI" a n d "SAMP2" were c h o s e n arbitrarily) when t h e appropriate input utility is called. The scenario n a m e s "SCEN1," "SCEN2,"

a n d "SCEN3" where c h o s e n arbitrarily. Note t h a t every v a l u e c o n t a i n s a decimal point.

NONE (no data)

-

There i s n o data. The user m u s t decide where a n d how t o obtain t h e n e c e s s a r y values.

4.

RECOURSE -

This section specifies t h e c o n t e n t s of W. The s e c t i o n m a y take one of t h e forms whose n a m e s follow:

SIMPLE (simple r e c o u r s e )

-

There a r e no d a t a lines i n t h i s case. The recourse m a t r i x is a s s u m e d t o be [I,-I], where I h a s ra:lk e q u a l t o t h e n u m b e r of rows in t h e technology matrix.

DETERMINISTIC ( t h e e l e m e n t s of W follow)

-

The r e c o u r s e m a t r i x i s given by t h e d a t a following t h e s e c t i o n header. The f o r m a t of t h e d a t a is identical t o t h a t of t h e COLUMNS section of t h e core file, i.e.. t h e c o n t e n t s of t h e matrix a r e specified in column order. The first n a m e field on a line (columns 5 through 12) c o n t a i n s t h e n a m e of t h e column. The remaining narne/numeric field p a i r s (columns 15 through 22/25 t h r o u g h 36 a n d 40 through 47/50 t h r o u g h 61) specify a row n a m e a n d t h e c o n t e n t s of t h e matrix a t the position given by t h e row a n d column names. The row n a m e s form a subset of t h e row n a m e s i n t h e TECHNOLOGY section.

CORE ( t h e e l e m e n t s of W appear in t h e core file)

-

The d a t a c o n s i s t s of a list of n a m e s which form a s u b s e t of the column n a m e s specified in t h e COLUMNS section of t h e core file. The c o n t e n t s of those c o l u m n s ( a s specified in t h e COLUMNS section of t h e core file) c o n s t i t u t e t h e r e c o u r s e matrix. One n a m e a p p e a r s per line, i n t h e first n a m e field (columns 5

Table 3. Contents of a sample SCENARIOS DISTRIBUTIONS section.

Code Field SC RV RV SC RV RV SC RV RV

t h r o u g h 12).

STOCHASTIC ( t h e e l e m e n t s of W a r e supplied by a subroutine) - The d a t a consists of a list of t h e n a m e s of t h e rows of t h e recourse matrix. Associ- a t e d with e a c h n a m e is o n e o r m o r e column names. These column n a m e s specify t h e active columns within t h e given row and form a s u b s e t of t h e c o l u m n n a m e s specified in t h e COLUMNS section of t h e c o r e file. The values for t h e r e c o u r s e m a t r i x do not appear in e i t h e r data file b u t a r e sup- plied by a subroutine written by t h e user. The row n a m e s appear in t h e first n a m e field of a line (columns 5 through 12) and t h e o t h e r two n a m e fields ( c o l u m n s 15 through 22 a n d 40 through 47) a r e available for t h e c o l u m n n a m e s .

First Name

Field SAMP1 SAMP1 SAMP1 SAMPI SAMP1 SAMP1 SAMP1 SAMPI SAMP1

NONE (no d a t a )

-

There i s n o data. The user m u s t decide where a n d how t o obtain t h e n e c e s s a r y values.

5. OaTECTIYES - This section specifies t h e f o r m of q . The section m a y take one of t h e f o r m s whose n a m e s follow:

LINEAR (q is a linear function)

-

The recourse objective is given by q (y)

=

4y, where q is given by t h e d a t a following t h e section h e a d e r . The d a t a for t h i s form consists of a n u m b e r of "definitions," which a r e analo- gous t o t h e "vectors" in t h e RANGES a n d BOUNDS sections of t h e c o r e file (see IBM, 1972). Each definition specifies t h e e l e m e n t s of q a n d consists of e n t r i e s of t h e f o r m "defname n a m e value," where "defname" i s t h e n a m e of t h e definition t o which t h e e n t r y belongs, "name" is t h e n a m e of a column of W (or of a row of

T;

s e e below) a n d "value" is t h e value for t h e corresponding row of q . "defname" occupies t h e f i s t n a m e field on a line

Second Name

Field SCENl TROW1 TROW2 SCEN2 TROW1 TROW2 SCEN3 TROW1 TROW2

First Numeric

Field 0.5 1.0 2.0 0.3 3.0 4.0 0.2 5.0 5.0

( c o l u m n s 5 through 12), "name" occupies t h e second n a m e field ( c o l u m n s 15 t h r o u g h 22) a n d "value" occupies t h e first n u m e r i c field ( c o l u m n s 25 t h r o u g h 36).

E n t r i e s for different definitions m u s t n o t be mixed t o g e t h e r in t h e i n p u t file.

As a n example, let t h e W m a t r i x have two columns, W C O L l a n d WCOL2, a n d define two vectors q a s follows:

a n d

The c o n t e n t s of t h e n a m e a n d n u m e r i c fields for t h e s e vectors a r e shown in table 4. The u s e r specifies which i s t h e desired definition ( o u r definition n a m e s "VEC1" a n d "VECZ" were chosen arbitrarily) when t h e appropriate i n p u t utility is called. Note t h a t every value c o n t a i n s a decimal point.

Table 4. Contents of a sample LINEAR OBJECTIVES section.

First Name

K e l d VEC1 VEC1 VEC2 VEC2

PIECEWISE (q is two-piece linear) - T h e r e c o u r s e objective is a s s u m e d t o be two-piece continuous a b o u t zero, i.e.

The d a t a for t h i s form consists of a n u m b e r of "definitions," which a r e analogous t o t h e "vectors" in t h e RANGES a n d BOUNDS sections of t h e c o r e file (see IBM, 1972). Each definition specifies t h e values of qi+ a n d q,- for all i a n d consists of e n t r i e s of t h e form "defname n a m e value value", where

"defname" i s t h e n a m e of t h e definition t o which t h e e n t r y belongs, "name"

i s t h e n a m e of a column of W ( o r of a row of T; s e e below), t h e first value gives t h e corresponding value of q + , a n d t h e second value gives t h e corresponding value of q - . The n a m e s occupy t h e first a n d second n a m e fields on a line (columns 5 through 12 a n d 15 t h r o u g h 22) a n d t h e values occupy t h e first and second n u m e r i c fields (columns 25 through 36 a n d 50 t h r o u g h 61).

Second Name

Field WCOLl WCOLZ WCOLl WCOLZ

E n t r i e s for different definitions m u s t n o t be mixed t o g e t h e r in t h e i n p u t file.

First Numeric

F i

el d 7.0 9.0 3.0 3.0

As an example, let t h e W matrix have two columns, WCOLl and WCOL2, and define two vectors q as follows:

The contents of t h e n a m e and numeric fields for these vectors a r e shown in table 5. The user specifies which is t h e desired definition (our definition names "VEC1" and "VECZ" were chosen arbitrarily) when t h e appropriate input utility is called. Note t h a t every value contains a decimal point and t h a t the values of q,' a r e positive.

Table 5. Contents of a sample OBJECTIVES (PIECEWISE) section.

NONE (no data)

-

There i s n o data. The user m u s t decide where and how t o obtain t h e necessary values.

Note

-

if t h e recourse matrix is simple (i.e., if t h e r e are n o column names for W), row n a m e s of T a r e substituted for column names of W in t h e OBJEC- TIVES section.

6. ENDATA

-

This line m a r k s the end of the stochastics file ( t h e section con- tains no d a t a lines).

I t is clear t h a t we have covered only a few of t h e possibilities for most of t h e above sections. However, t h e format is such t h a t new forms can be added a s t h e need arises.

Standard Data Structures

One of t h e benefits of a standard format is t h a t a library of routines t o facilitate the task of reading files specified in t h e format may be written. f e now describe some special data s t r u c t u r e s used by our utilities.

Packed Vectors and Matrices

The matrices and vectors t h a t appear in a stochastic program with recourse are often sparse. Our utilities therefore a t t e m p t to conserve memory by saving only the nonzero elements of a matrix or vector. We call this a

"packed" representation and refer t o matrices or vectors stored in this fashion as "packed matrices" and "packed vectors." respectively.

A packed vector consists of two arrays?. One contains t h e nonzero vector elements. The o t h e r holds t h e row or column indices of t h e nonzero vector ele- ments. We call these arrays t h e "values" array and t h e "indices" array, respec- tively. If t h e nonzero e l e m e n t s of a vector are [vil,

. . .

,vin] and a r e ordered so t h a t ij<ij+l, t h e n t h e jth e l e m e n t of the values a r r a y contains t h e value of v . and t h e jth element of t h e indices array contains t h e value of i,. The values 9 and indices arrays for t h e vector [1,0,4,0.0.5] a r e shown in figure 1.

values indices

Figure 1. Packed representation of t h e vector [1,0,4,0,0,5]

J u s t as an ordinary m a t r i x may be viewed as a collection of vectors, a packed matrix may be thought of a s a collection of packed vectors. A packed matrix consists of t h r e e arrays. One contains t h e t h e nonzero matrix ele- ments. Another holds t h e row indices of t h e nonzero matrix elements. These two arrays a r e analogous t o t h e values and indices arrays mentioned in the preceding paragraph and so a r e called t h e values array and t h e indices array, respectively. The third a r r a y organizes t h e matrix by column: t h e ith element of this a r r a y is t h e location in t h e values and indices arrays where t h e entries for t h e i t h column of t h e m a t r i x begin. Because t h e elements of t h e third array

"point" t o t h e matrix columns, we call this a r r a y t h e "pointers" array. If a matrix h a s n columns, t h e ( n + l ) t h element of t h e pointers a r r a y contains the index of t h e element in t h e values a r r a y immediately following t h e last nonzero matrix element (i.e., t h e ( n + l ) t h element points to t h e space immediately fol- lowing t h e matrix entries). The values, indices, and pointers arrays for t h e 6 x 5 matrix

t

Throughout this paper, we use t h e t e r m "array' t o refer t o "a nonempty sequence of data"

(ANSI, 1078, p. 5-1) within t h e computer's memory. An array may have several d i m a s i o n s

a r e shown in figure 2. The double lines in t h a t figure m a r k t h e beginning of t h e e n t r i e s for each column. Note t h a t the third column v e c t o r of t h e m a t r i x is identical t o t h e vector whose packed representation is shown in figure 1 a n d as a r e s u l t t h a t t h e portions of t h e values a n d indices a r r a y s t h a t contain t h e e n t r i e s for t h a t v e c t o r in figure 2 a r e identical t o t h e values a n d indices a r r a y s in figure 1. Note also t h a t the value of t h e first e l e m e n t of t h e pointers a r r a y is always 1.

values indices pointers

Figure 2. Packed representation of a 6x5 m a t r i x

I t

i s difficult t o obtain a single row vector from t h e d a t a s t r u c t u r e shown in figure 2. To p e r m i t rapid access t o row vectors, we add t h r e e a r r a y s t o a packed m a t r i x a n d produce an "augmented packed matrix." The t h r e e a r r a y s a r e called t h e "augmented pointers" array, t h e "augmented indices" a r r a y , a n d t h e

"map" array. The augmented pointers a r r a y a n d the a u g m e n t e d indices a r r a y a r e analogous t o t h e indices a n d pointers a r r a y s of t h e packed matrix. The aug- m e n t e d indices a r r a y contains t h e column indices of t h e nonzero m a t r i x ele- m e n t s a n d t h e a u g m e n t e d pointers a r r a y holds pointers to t h e beginning of t h e e n t r i e s for e a c h row. However, t h e r e is a small complication. The c o n t e n t s of t h e a u g m e n t e d p o i n t e r s a r r a y c a n n o t be used t o access t h e values a r r a y directly s i n c e t h e e n t r i e s in t h e values a r r a y a r e organized by column. The or only one dimension. We reserve the word "matrix" to refer to the mat-ices in the prob-

lem, i.e.,A,T.and W.

function of t h e map a r r a y is to map t h e augmented pointer a r r a y and the aug- mented indices a r r a y onto t h e values array (hence its name). Each element in t h e map array is t h e location in t h e values array of t h e matrix element whose row and column indices a r e defined by t h e appropriate e n t r i e s in the aug- mented pointers a r r a y and t h e augmented indices array. Figure 3 shows t h e augmented pointers, augmented indices, map, and values a r r a y s for the matrix used t o provide t h e example in figure 2. The double lines in figure 3 mark t h e beginning of t h e e n t r i e s for each row. Like the pointers array, t h e augmented pointers a r r a y always has t h e value 1 in its first element.

augmented pointers

augmented

indices values

Figure 3.

Arrays for rapid access of row vectors in t h e packed representation of a 6x5 matrix

The reader may be forgiven for wondering how t h e use of six arrays t o represent a single matrix can possibly save space. Indeed, i t might appear t h a t t h e density of the matrix would have t o be less t h a n 0.16 for s u c h an approach t o conserve memory. The t r u e picture is brighter because only t h e values a r r a y need be capable of expressing real numbers. The contents of t h e auxili- a r y arrays (indices, pointers, etc.) are integers. In t h e utilities we have writ- ten, t h e values a r r a y is double precision and t h e auxiliary arrays a r e half integer

integer*^).

Table 6 shows t h e densities a t which i t becomes uneconom- ical t o use t h e various packed representations.

Table 6. Critical densities for packed data structures.

Representation packed vector packed matrix augmented matrix

Since many of our input utilities use packed representations exclusively, we have provided routines t o convert packed structures to their unpacked equivalents and vice versa. I t is possible to write subroutines t h a t use t h e s e utilities and t h e standard input utilities to read dense matrices without per- manently consuming the additional memory t h a t t h e packed representation requires. For example, to read t h e contents of an mxn matrix,

M,

whose density is g r e a t e r t h a n 0.73, into an mxn array, A, t h e user writes a subroutine and passes i t t h e address of A (i.e., '"call subroutine(A ,...)"). The subroutine

-

declares t h e pointers, indices, and values arrays for a packed matrix, - calls t h e appropriate input utility to read the contents of

M

into t h e packed

matrix, and

-

calls t h e "expand matrix" utility, directing i t t o transfer t h e contents of t h e packed m a t r i x into k

The effect of t h e s e operations i s t o place t h e elements of

M

into A The arrays used t o represent t h e packed matrix disappear when the subroutine executes i t s "return" statement.

Unpacked Dimensions

n rnxn rnxn

Stochastic Vectors

The stochastic right hand side vector, p , cannot easily be represented as a single packed vector. The DISTRIBUTIONS section (which defines p ) may appear in several forms, e a c h of which provides different information. Accordingly, t h e r e a r e t h r e e s e p a r a t e (but similar) data s t r u c t u r e s to describe t h e distribu- tion of t h e stochastic right hand side.

The t h r e e data s t r u c t u r e s share a common organization: each has a

"pointers" array, a "probabilities" array, and a t least one "values" array. The c o n t e n t s of these arrays a r e interpreted differently for each data s t r u c t u r e .

For t h e DISCRETE form of t h e DISTRIBUTIONS section, t h e values a r r a y con- tains t h e values t h a t each row m a y assume and each e n t r y in t h e probabilities a r r a y contains t h e likelihood t h a t t h e row assumes the corresponding value. In t h i s case, t h e pointers array plays a role similar t o the augmented pointers a r r a y in an augmented packed matrix: i t organizes t h e values and probabilities arrays by row. The i t h e n t r y in t h e pointers array is the location in t h e values a n d probabilities arrays where t h e e n t r i e s for t h e ith row begin. Like t h e last element of t h e pointers a r r a y in a packed matrix, t h e last element of t h e pointers a r r a y in a stochastic vector points t o t h e first "empty" e n t r y in t h e values and probabilities arrays. The pointers, values, and probabilities arrays for t h e vector whose rows have t h e distribution

I1 lo.

⁴

Savings realized if density <

Exact Approx. %

-

8 10

---

8 2 2 10 lorn lorn

--

^{8 2(n+m) 4}

14 14mn 14mn

0 0 73 46

6

^0.1

Row 2

=

6 with probability 0.7 10.2

with probability

lo

0:5 Row 4

=

3 wit.h probability 1.0

a r e shown in figure 4. The double lines in t h a t figure m a r k t h e beginning of t h e e n t r i e s for e a c h row.

pointers values

'

=

proba- bilities

1

-

Flgure 4.

Representation of a s t o c h a s t i c vector (DISCRETE DISTRIBUTIONS).

The s i t u a t i o n is quite similar for t h e PIECEWISE form of t h e DISTRIBUTIONS section, except t h a t two values arrays a r e needed. One ( t h e "high values"

a r r a y ) c o n t a i n s t h e upper endpoint for e a c h interval. The o t h e r ( t h e "low values" a r r a y ) contains t h e lower endpoint for e a c h interval. Each e n t r y in t h e probabilities a r r a y contains t h e likelihood t h a t t h e appropriate row a s s u m e s a value in t h e corresponding interval. The pointers a r r a y again organizes t h e o t h e r a r r a y s by row. The pointers, high a n d low values, a n d probabilities a r r a y s for t h e v e c t o r whose rows have t h e distribution .

Row 1 in with probability

[5,5.3] 0.1

[6,6.3] with probability 0.7

[7,7.3] lo..

"th probability

[:::

Row 4 in [3,3.2] with probability 1.0

a r e shown in figure 5. The double lines in t h a t figure m a r k the beginning of t h e e n t r i e s for each row. Note t h a t t h e ranges were obtained by taking t h e values from t h e example shown in figure 4 a s the lower bounds for t h e intervals and t h u s t h a t the pointers and probabilities arrays a r e t h e same as in figure 4 and t h a t t h e low values array is t h e same as t h e values array in figure 4.

low pointers values

m

high proba-

values bilities

Figure 5.

Representation of a stochastic vector (PIECEWISE DISTRIBUTIONS).

The data s t r u c t u r e for t h e SCENARIOS form of t h e DISTRTBLTIONS section is quite different from t h a t for t h e DISCRETE and PIECEWISE forms. The values array. as always, contains t h e values t h a t each row may assume. However, t h e values a r e grouped by scenario: t h e ith element of t h e pointers a r r a y is the location in the values a r r a y where t h e entries for t h e i t h observation of t h e vec- t o r begin and the ith element of t h e probabilities a r r a y contains t h e likelihood t h a t t h e vector assumes t h e corresponding value. If there a r e n observations, t h e ( n + l ) t h e n t r y in the pointers a r r a y is t h e index of t h e first unused element in t h e values array. The pointers, values, and probabilities arrays for t h e vec- t o r whose distribution is

with probability

a r e shown in figure 6. The double lines in t h a t figure m a r k t h e beginning of t h e

e n t r i e s for each scenario.

pointers

proba-

bilities values

1

-

Figure 6.

Representation of a stochastic vector (SCENARIOS DISTRIBUTION).

Since e a c h observation h a s t h e same number of elements (i.e., t h e number of rows in p ) , t h e pointers a r r a y is not strictly necessary. We have included i t t o provide some uniformity in t h e components of t h e data s t r u c t u r e s for each form of t h e stochastic right hand side.

Simple Lists and Hash Tables

Lists play a n i m p o r t a n t role in t h e s t a n d a r d input format. Some sections (e.g., t h e ROWS section and t h e CORE form of t h e TECHNOLOGY section) a r e lit- tle more than a list of names. Other sections (e.g., t h e COLUMNS section and t h e OBJECTIVES section) require t h a t a list of names be searched. Our input utilities a r e able t o r e p r e s e n t these lists in e i t h e r of two d a t a s t r u c t u r e s .

A list of n a m e s may be kept in a "simple list" or i n a "hash table" (Knuth, 1973). A simple list is essentially a one-dimensional a r r a y of c h a r a c t e r strings.

New entries a r e placed in the first available element and t h e list is searched sequentially. The hashing process uses a function t o assign an index t o each name; t h e name is then placed in t h e corresponding element of t h e hash table.

Searches a r e therefore faster when a hash table is used, but a hash table requires more space t h a n a simple List. The simple list and a hash table gen- erated when t h e names "row00001," "row00002,"

....

"row00006" are entered in order a r e shown in figure 7. Also shown is t h e location where t h e name

"row00007" would be entered. The hash function used t o generate t h e indices for the hash table appears in our "pchash" utility.

simple hash

list table

Figure 7. Simple list and hash table Packed Matrices and User-Written Routines

To use t h e STOCHASTIC form of t h e TECHNOLOGY and t h e RECOURSE sec- tions or t h e SIMULATIONS form of t h e DISTRIBUTIONS section of t h e stochastics file, t h e u s e r m u s t write a routine to supply t h e values of t h e active elements of t h e corresponding matrix or vector. By convention, t h e first parameter passed t o this routine is t h e values array for t h e appropriate s t r u c t u r e . All t h e user's routine need do is e n t e r its data in column order into this array. It is t h e cal- ling routine's responsibility to establish t h e contents of any auxiliary arrays.

Overview of the Utilities

Nazareth (1982) discusses t h e development of subroutines which m a y be used "as t h e primitives or basic operators of a language for implementing LP algorithms." His t h e s i s is t h a t a m a t h e m a t i c i a n should develop algorithms t o solve problems, n o t g r i n d out FORTw r o u t i n e s t o r e a d input files. The purpose of o u r utilities is t o free t h e program a u t h o r f r o m t h e t y r a n n y of m i n u t i a e a n d t o allow t h e r e s e a r c h e r t o c o n c e n t r a t e on m e t h o d s r a t h e r t h a n on means.

The a n c e s t o r s of o u r routines a r e t h e modules in t h e LPKlT collection (Nazareth, 1982). Accordingly, we have adopted LPKIT's naming conventions.

"Problem o r i e n t e d modules" have n a m e s which begin with t h e l e t t e r "p." Our problem o r i e n t e d modules read t h e sections defined in t h e s t a n d a r d i n p u t for- m a t a n d perform various o t h e r chores. "Algorithm oriented modules" have n a m e s which begin with t h e l e t t e r "a." The algorithm oriented modules in o u r collection o p e r a t e on packed d a t a s t r u c t u r e s ; t h e s e subroutines t h e r e f o r e have n a m e s which begin with t h e l e t t e r s "ad." Tables 7 through 10 c o n t a i n a s u m - m a r y of o u r utilities.

Table 7. Routines t h a t manipulate packed data s t r u c t u r e s Subroutine

a d c m a t

adcvec

a d x m a t

adxvec

adrn kax

Function

Produce a packed m a t r i x from a m a t r i x of full r a n k (i.e., remove zeros)

Produce a packed vector from a v e c t o r of full rank (i.e., remove zeros)

Produce a m a t r i x of full r a n k from a packed ma- t r i x (i.e.. r e s t o r e zeros) Produce a v e c t o r of full r a n k f r o m a packed vector (i.e.. r e s t o r e zeros)

Produce a n a u g m e n t e d packed m a t r i x from a packed m a t r i x (i.e., gen- e r a t e auxiliary a r r a y s )

Table 8. Routines t h a t read specific sections in the standard format Subroutine

prcrow prcbou prsdis prsdpc

prsdsc

Function

Read t h e ROWS section of a core file Read the BOUNDS section of a core file Read the DISCRETE form of t h e DISTRI- BUTIONS section of a stochastics file Read the PIECEWISE form of t h e DIS- TRIBUTIONS section of a stochastics file

Read the SCENARIOS form of the DIS- TRIBUTIONS section of a stochastics A1 e

Table 4. General input routines Subroutine

prfmat prfnam prfv ec prssvc prfget pflush

Function

Read a matrix from a specified file Read a list of names from a specified file Read a vector from a specified file

Read lines from a specified file until a noncomment line is encountered

Read lines from a specified file until a section header is encountered

Table 10. Miscellaneous utilities Subroutine

paroll pchsrc pctsrc pntsrc p n t s t l pntst2 pchash pckbnd pireal pirint pstrip PuPPer

Caveats

Although we have attempted to provide a comprehensive set of 1/0 handlers as well a s several useful .data s t r u c t u r e manipulation routines, we realize t h a t our collection is incomplete. We hope to enlarge i t in t h e next few months. Furthermore, while a programmer will find i t possible t o read data expressed in the standard input format using some combination of our utilities, he or she may also discover mistakes in t h e logic of some routines. Our library is woefully untested. In most cases, however, i t should prove a simple task t o correct any errors. Finally, we would like to remind t h e reader t h a t this paper is a proposal and t h a t nothing is graven in stone.

Function Reorder t h e contents of an a r r a y

Search a character hash table for a specified key Search a c h a r a c t e r simple list for a specified key

Insert a specified key in t h e proper position in an ordered numeric simple list

Hash a string of eight c h a r a c t e r s Check a name against a s e t of bounds

Convert a c h a r a c t e r string t o t h e real number i t represents Convert a c h a r a c t e r string t o t h e integer i t represents Remove leading blanks from a c h a r a c t e r string

Convert lower case l e t t e r s in a c h a r a c t e r string t o t h e i r upper case equivalents

Utility Descriptions

We now give a s h o r t summary of each of t h e utilities. We describe t h e basic function of each routine, specify the options t h a t are available, and discuss how each routine might be u s e d A detailed description of t h e p a r a m e t e r s taken by each routine and their meanings appears in comments t o t h e source code, which is available from IlASA. Interested parties should contact

Project Secretary SDS/ADO

International Institute for Applied Systems Analysis A-236 1 Laxenburg

Austria ADCMAT

'Illis subroutine g e n e r a t e s t h e packed representation of matrix of full rank, i.e., removes elements t h a t are zero. The caller may direct

ADCMAT

t o t r e a t as zero any element whose absolute value is less than a specified toler- ance.

This subroutine g e n e r a t e s t h e packed representation of a v e c t o r of full rank, i.e., removes e l e m e n t s t h a t a r e zero. The caller m a y d i r e c t ADCVEC t o t r e a t as z e r o a n y e l e m e n t whose absolute value is less t h a n a specified toler- ance.

ADMKAX

This subroutine produces a r r a y s t o p e r m i t access t o row vectors in a packed m a t r i x , i.e., g e n e r a t e s t h e a u g m e n t e d pointers, a u g m e n t e d indices, a n d m a p arrays.

ADxblAT

This subroutine g e n e r a t e s a m a t r i x of full r a n k from

a

packed matrix, i.e., r e s t o r e s e l e m e n t s t h a t a r e zero.

A D m c

This subroutine g e n e r a t e s a v e c t o r of full r a n k f r o m a packed vector, i.e., r e s t o r e s rows o r columns containing zero.

PAROLL

This subroutine adjusts t h e c o n t e n t s of one, two, o r t h r e e a r r a y s s o t h a t a given e l e m e n t moves t o t h e top of t h e array(s) while t h e relative order of t h e a r r a y e n t r i e s r e m a i n s unchanged. It is u s e d by o t h e r Library r o u t i n e s t o e n s u r e t h a t e n t r i e s in s t o c h a s t i c vectors a p p e a r in s t r i c t row order.

PCHASH

This subroutine calculates t h e initial index a n d offset used by t h e method of double hashing for a n eight c h a r a c t e r key.

PCHSRC

This subroutine i s adapted f r o m

L.

Nazareth's HASH. PCHSRC s e a r c h e s a hash table for a given eight c h a r a c t e r key. It uses double hashing for collision resolution.

PCKBND

This s u b r o u t i n e s e a r c h e s a s u b s e t of a given list o r table of n a m e s for a given e i g h t c h a r a c t e r key. It is u s e d by o t h e r library routines t o s e a r c h a list when a u s e r wishes t o r e s t r i c t h i s o r h e r attention t o a c e r t a i n submatrix or subvector in a n i n p u t file.

PcrsRC

This subroutine s e a r c h e s a simple list for a specified eight c h a r a c t e r key.

mum

This subroutine r e a d s lines from a n i n p u t file until a n o n c o m m e n t line whose first c h a r a c t e r is nonblank is found.

I t

r e t u r n s t h e c o n t e n t s of t h a t line t o t h e caller.

The c a l l e r may direct t h i s subroutine to convert any lower c a s e c h a r a c t e r s in columns 1 t h r o u g h 12, 15 t h r o u g h 22, a n d 40 through 47 ( t h e code field, t h e t h r e e n a m e fields, a n d t h e first a n d f o u r t h columns) t o t h e i r upper case equivalents.

This subroutine essentially skips to t h e next section h e a d e r in t h e i n p u t when called. It c a n t h e r e f o r e be used t o bypass unused sections in t h e stochas- tics or core files or t o "flush" a n y lines t h a t may r e m a i n in a s e c t i o n a f t e r t h e appropriate data h a s been read.

PIREAL

This subroutine c o n v e r t s t h e first sequence of nonblank c h a r a c t e r s i t finds in a given string into t h e real n u m b e r t h a t sequence represents. The sequence m u s t contain a decimal point a n d only t h e first 15 c h a r a c t e r s in t h e sequence a r e significant. PIREAL removes t h e c h a r a c t e r sequence from t h e beginning of t h e string.

PIRINT

This subroutine converts t h e first sequence of nonblank c h a r a c t e r s i t finds in a given string into t h e i n t e g e r value t h a t sequence represents. The sequence m u s t n o t contain a decimal point a n d only t h e first 10 c h a r a c t e r s in t h e sequence a r e significant. PIRINT removes t h e c h a r a c t e r s e q u e n c e f r o m t h e beginning of t h e string.

This subroutine s e a r c h e s for a given key in an ordered n u m e r i c simple list using a binary search. The list i s a s s u m e d t o be in ascending order. It is used by o t h e r routines in t h e library t o d e t e r m i n e whether a c e r t a i n n a m e h a s o r h a s n o t been e n o u n t e r e d previously i n t h e input file.

PNTSTl and

PNTSlZ

These subroutines i n s e r t a given key i n t o a simple list using insertion sort.

The routines assume t h e list i s in one-to-one correspondence with a n o t h e r a r r a y a n d adjust this a r r a y so t h a t t h e values remain s t r i c t l y associated with t h e list e n t r i e s ( t h e associated a r r a y is assumed t o be double precision in PNTSTl a n d half i n t e g e r i n PNTSTZ).

PNTSTl a n d PNTSTZ a r e u s e d by o t h e r routines in t h e library t o e n s u r e t h a t t h e c o n t e n t s of packed v e c t o r s a p p e a r in s t r i c t row order.

PRCBOU

This subroutine is adapted from M. Saunders' MINOS a n d L. Nazareth's PREADB. PRCBOU reads t h e BOUNDS section of a core file. It a s s u m e s t h a t t h e BOUNDS section header h a s been r e a d by t h e calling routine.

I t

t e r m i n a t e s when it e n c o u n t e r s a n o n c o m m e n t c a r d or line with a c h a r a c t e r i n the first column o r if it e n c o u n t e r s e n d of file. Values in t h e n u m e r i c fields must con- t a i n a decimal point i n o r d e r t o be i n t e r p r e t e d properly.

The caller provides PRCBOU a l i s t of names. Each time PRCBOU reads a c o l u m n name, it s e a r c h e s t h i s list. If t h e column n a m e is n o t i n t h e list, a n e r r o r is generated.

Several options a r e available:

- The caller may specify t h a t t h e acceptable column n a m e s a r e in a hash table r a t h e r t h a n in a s i m p l e list.

-

The caller m a y d i r e c t PRCBOU t o take its first input from a c h a r a c t e r string r a t h e r t h a n from t h e s o u r c e file.

- The caller may direct PRCBOU t o e n t e r only t h e bounds on some s e t of columns into t h e arrays t h a t hold them.

-

The caller may inhibit output of diagnostic messages, of t h e bounds t h e m - selves, or of both.

Several checks a r e performed on t h e input data.

This subroutine is adapted from M. Saunders' MINOS and L. Nazareth's PREADR. PRCROW reads t h e ROWS section of a core file. It assumes t h a t t h e ROWS section header has been read by t h e calling routine. It t e r m i n a t e s when i t encounters a noncomment c a r d or line with a character in t h e first column or if it encounters end of file. PRCROW ignores 'D' type rows.

There a r e several options available:

-

The caller may direct PRCROW to construct a simple list or t o c o n s t r u c t a hash table t o hold t h e row names.

-

The caller may direct PRCROW t o take its first input from a c h a r a c t e r string r a t h e r than from t h e source file.

-

The caller may inhibit output of diagnostic messages, of t h e row n a m e s and types themselves, or of both.

Several checks are performed on t h e input data.

This subroutine reads lines from an input file until a noncomment, non- blank line is found.

I t

r e t u r n s t h e contents of t h e line to t h e caller.

The caller may direct this subroutine to convert a n y lower case c h a r a c t e r s in columns 1 through 12, 15 through 22, and 40 through 47 ( t h e code field, t h e t h r e e n a m e fields, and t h e first and fourth columns) t o t h e i r upper case equivalents.

This subroutine essentially r e t u r n s t h e next "interesting" line in t h e i n p u t file.

PRFIfAT

This subroutine is adapted from M. Saunders' MINOS and L. Nazareth's PREADC. PRFMAT reads matrix entries into a packed matrix. It c a n be used t o read t h e COLUMNS section of t h e core file, t h e DETERMINISTIC and STOCHASTIC forms of t h e RECOURSE section of t h e stochastic file, and, in conjunction with ADMKAX, t h e STOCHASTIC form of t h e TEXHNOLOGY section of t h e stochastics file.

I t

assumes t h a t the header card of t h e c u r r e n t section has been read by t h e calling routine. It terminates when i t encounters a noncomment c a r d or line with a character in t h e first column or if i t encounters end of file.

Only nonzero elements of t h e a r r a y a r e entered into t h e packed matrix a n d values in t h e numeric fields musf contain a decimal point in order t o be inter- p r e t e d properly.

The caller passes PRFMAT a List of names. Each time PRFMAT reads a row name, i t searches this list. If t h e row name is not in t h e list, an e r r o r is gen- erated.

Several options a r e available:

-

The caller may direct PRFMAT to construct a simple list o r to construct a hash table to hold t h e column names.

- The caller may specify t h a t the acceptable row names a r e in a hash table r a t h e r than in a simple list.

-

The caller may direct PRFMAT to take its first input from a c h a r a c t e r string r a t h e r than from the source file.

-

The caller may direct PRFMAT t o read only a fixed number of columns from t h e source file.

-

The caller may direct PRFMAT t o e n t e r only t h e elements for some set of rows into the packed matrix.

-

The caller may direct PRFMAT to t r e a t all values whose absolute value is less than or equal to some tolerance as zero.

-

The caller may direct PRFMAT to e n t e r all values i t encounters, including zeros, into the packed matrix.

-

The caller may inhibit output of diagnostic messages, of t h e matrix con- t e n t s themselves, or of both.

Several checks a r e performed on the input data.

PRFNAM

This subroutine reads a list of names from a file into a simple list.

I t

assumes t h a t there is one name per line, in the first name field (columns 5 through 12). I t terminates when it encounters a noncomment card or line with a character in t h e first column or if i t encounters end of file. I t can be used to read the CORE form of t h e TECHNOLOGY and RECOURSE sections of t h e stochas- tics file.

Several options a r e available:

-

The caller may direct PRFNAM to construct a hash table r a t h e r t h a n a sim- ple list.

-

The caller may specify t h a t a name m u s t be unique or t h a t a name may appear more than once in t h e source file.

-

The caller may pass PRFNAM a s e t of names, specifying t h a t every n a m e in t h e source file m u s t appear in this set.

-

The caller may direct PRFNAM to take its first input from a c h a r a c t e r string rather than from t h e source file.

-

The caller may direct PRFNAM to read only a fixed number of names from t h e source file.

-

The caller may inhibit output of diagnostic messages, of t h e names them- selves, or of both.

Several checks a r e performed on the input data.

PRFYEC

This subroutine is adapted from M. Saunders' MINOS and L. Nazareth's PREADC. PRFVEC a row or column vector from a file into a packed vector. I t assumes that t h e row or column names appear in t h e second and/or third n a m e fields (columns 15 through 22 and 40 through 47, respectively) and t h a t t h e associated values a r e in t h e first and second numeric fields (columns 25 through 36 and 50 through 61. respectively). The subroutine terminates when it encounters a noncomment card or line with a nonblank c h a r a c t e r in t h e f i s t column o r if it encounters e n d of file. I t can be used to read t h e RHS and