sals users’ manual (version 2.5) - olab.is.s.u...

SALS USERS’ MANUAL(version 2.5)

Yoshio OyanagiDepartment of Information Science, University of Tokyo

Hongo 7-3-1, Bunkyo, Tokyo, 113-0033 JAPAN

Toru NakagawaOsaka Gakuin University

Kishibe Minami 2-36-1, Suita, 564-8511 JAPAN

December 1, 1981March 1, 1993March 1, 2000

Contents

i

Forword

SALS is a general-purpose system for ”Statistical Analysis with Least Squares fitting.”SALS has its origin in a cooperative work of experts in computer and statistics and usersin physics and chemistry.

The diversity of the fields in which the least squares method is used necessitated astandard software system, while the complexity of the problem demanded capabilitiesnot available in any existing packages. The new system which was developed to meetthis need has proven to be of general usefulness, and responsibility for its continuedsupport and further development has been assumed by the SALS group.

As the system evolved, many people contributed ideas and assisted with program-ming. They include Professor Hayato Togawa of Nihon University, Dr. Kunio Tanabeof Institute for Mathematical Statistics, Mr. Masanori Rikihisa of Waseda University,Dr. Tetsuzo Ito of the Institute of Physical and Chemical Research, Professor MasaakiSibuya of Keio University, Professor Takeo Yamamoto of University of Library and In-formation, Professor Hajime Ohiwa of Toyahahi Technical Science University, Dr. AkioTakenaka of Tokyo Institute of Technology, Professor Katsunosuke Machida of the Uni-versity of Kyoto, and Professor Isao Suzuki of University of Tsukuba. Miss Sumie Ueda,Mr. Yukio Yanagisawa, Mr. Mamoru Hirajima, Mr. Hisao Matsuda and Miss AyakoKawamata assisted in coding and debugging. Miss Reiko Toda, Miss Hisaka Okamoto,Miss Kumi Takemura, Mrs. Masako Nakagawa helped in secretarial work. ProfessorMasashi Okamaoto of Osaka University and Professor Kozo Kuchitsu of the Universityof Tokyo gave advices and encouraged the project. Dr. Yukihiko Karaki and Miss SanaeTakahashi of the Computer Centre of the University of Tokyo gave administrative help.

This work was partially supported by Laboratory of Application Programs, Com-puter Center, The University of Tokyo (1975— ) and by the Grant of Research ProjectNo. 310228: ”Studies on Statistical Program Package,” belonging to the Special Project”Formation Process of Information System and Organization of Scientific Informations”sponsored by the Ministry of Education of Japan (1976-1978).

ii

Chapter 1

Basic Features of SALS

SALS is a general-purpose program package for statistical analysis with least squaresfitting with broad range of capabilities. It frees users from concern with the details ofthe linear and non-linear algorithms and of the statistical calculations.

Many applications, which previously would have required extensive special programdevelopment, can be handled by the system with a few user-coded subroutines.

Basic features of SALS include:

• Wide applicability

• Reliable algorithms

• Staitstics and diagnostics

• User-oritented input/output

• Easyan flexible control

• Portability and maintainability.

1.1 Wide applicability

SALS system is widely applicable to data fitting in various fields of experimental andobservational sciences. Various theoretical models coded by users are acceptable, in-cluding those large-scale, complicated, and nonlinear with respect to the parameters tobe adjusted. If the user subroutine does not calculate the first derivatives or Jacobiananalytically, they are calculated numerically in the SALS system.

Numbers of variable parameters and observed data are sometimes very small, e.g. afew variables against a few tens of observations, but sometimes they are very large, e.g.100 variables against several thousands of observations: SALS system adjusts its arraysizes automatically corresponding to the numbers of parameters and observations andto the algorithms to be used.

1

Forword 2

1.2 Reliable algorithms

Since highly precise observed data are obtainable in modern experimental sciences, andsince users always want to determine more and more parameters in their theoreticalmodels, SALS system supplies fitting algorithms of high precision and high reliability.

Five selected algorithms for the linear least-squares calculation are installed; theykeep high precision even in ill-conditioned cases and are prepared for the cases of rankdeficiency. Linear algorithms which transform the Jacobian matrix directly withoutsetting up the normal-equation matrix are introduced as the standard options. Thesingular value decomposition method is adapted to get a minimum-norm solution incase of rank deficiency.

For the purpose of nonlinear least-squares fitting, various algorithms are introducedto cover the shortage of the simple Gauss-Newton method. Criteria for terminating theiteration and for checking the convergence in nonlinear algorithms were set after varioustests. Any of these linear and nonlinear algorithms is available by a simple specificationinput without any change in user’s program.

1.3 Statistics and diagnosis

In case of non equivalent uncertainties in the observed data, proper weights of theobservations can be introduced by the user. Furthermore, in order to protect againstany unrecognized error in measurement or in data handling, robust estimation methodcan also be used in place of the ordinary least squares estimation; the system tries toestimate the model parameters by decreasing the weights of such ”erroneous” data andrelying on the most others.

After estimating the model parameters, SALS system evaluates their uncertaintiesand correlations. These uncertainties are further used to estimate the uncertainties inthe calculated values corresponding to the observed ones.

Various diagnostics are outputted to check the goodness of the fit, to find possibilitiesof further improvement of the model, and to select the best among a number of models.

1.4 User-oriented input/output

SALS provides easy and flexible input/output methods which meet various demandsfrom users: Some users, who handle with smaller-scale problems, want convenient I/Oroutines installed in the system, while others, who struggle with larger-scale problems,want to use their own specialized I/O routines. Thus, in order to match these diverseneeds, SALS contains standard I/O routines which may or may not be replaced by user-coded I/O routines. An ambitious user can choose to code all the I/O subroutineshimself so that the input and output can be done in a format suited to his specificapplications.

Several sets of observed data, variable parameters and algorithms are acceptable atone time without repeating the common inputs.

The inputs are always checked against occasional errors and improper ways of con-trolling the system. If an error is detected, SALS system outputs an error message, andeither stops or goes ahead after assuming defaults.

Forword 3

Various types and levels of output and statistical treatments can be done by SALS:For a routine work of fitting, a simple output of the final result and its statisticalinformation can be obtained. In case of analyzing a new problem of considerable size,however, detailed output of the fitting process is desirable at first in order to check thecorrectness of his treatment and to recognize any difficulty in the problem. Then, ata stage of trial and error in fitting, outputs to monitor the way of convergence and todiagnose the result would be sufficient. At the last stage of a fitting work, detailedoutputs of the final result and its statistical information can be obtained.

1.5 Easy and flexible control

SALS system provides easy-to-handle commands for users to control and optimize variousalgoriths flexibly for their own problems. The linear and nonlinear fitting algorithmsand statistical treatments can be taylored by use of these commands. At the same time,users may not be bothered in specifying every detail of them, because all these algorithmcontrol commands except one are omissible. For the omitted commands, SALS suppliesproper default values in a hierarchical scheme.

1.6 Portability maintainability

SALS system is designed to be adaptable to a variety of circumstances at present and inthe future. For this purpose, SALS system is highly modular and built up as a systemof hierarchically organized subroutines. It is written in machine-independent standardFORTRAN IV in a way easy to understand and easy to modify. The machine dependentcodes are isolated in a few modules so that the system is easily transportable. Eventhough SALS is made of about 10,000 steps, it has proved to be widely portable to varioustypes of computers.

Forword 4

1.7 Organisation of the SALS system

The block structure of the SALS system is illustrated below. Each block consists ofseveral subroutines, and the system consists of about 140 subroutines.

user’s main program∗∗

⇓SALS system management ⇒ input subroutines∗

⇓preparation of fit ⇒ test of derivatives(default setting andwork area allocation)

⇓weight adjustment control of fit ⇒ Utilities

⇓management of nonlinear algorithm ⇒ Utilities⇓ ⇓ ⇓

Gauss-Newton Marquardt hybrid⇓ ⇓ ⇓

management of linear algorithms ⇒ Utilities⇓ ⇓

without normal eq. with normal eq.⇓ ⇓ ⇓ ⇓ ⇓

Gram- House- S.V.D. Cholesky E.V.D.Schmidt holder

Utilities statistical calculationoutput subroutines∗

linkage to user’s model subroutine⇓

user’s model subroutine∗

** to be provided by useruser can add his own subroutines

1.8 Guide to users

First look at the example in 2.1 and read 3.2 - 3.5. That will be enough for simpleproblems. After you have been used to the system, read the rest of the manual.

In order to recall the SALS commands, see 5.1.

Chapter 2

How to Get Access to SALS

The FORTRAN source program of the SALS system is open to users under the regulationof Licence Agreements as described in Appendix B.1.

In usual cases, object or load module is also available. The way to access the SALS

system, however, depends on how SALS is installed in your computer. In the followingwe will suppose a hypothetical computer of IBM mainframe type. In this computer,

source program is stored in SYS1.SALS.FORT (DSORG=PO)andload module is stored in SYS1.SALS.LOAD.

A few examples are demonstrated in this chapter to give basic ideas of SALS.

2.1 How to run SALS

As an exapmle we would like to analyse the data in the next page in terms of a modelcomposed of a Lorentzian peak plus linear background.

The model function would be

F(q) = X(3) * X(2)**2 / ((q-X(1))**2 + X(2)**2 )

+ X(4) + X(5) * q,

where

X(1) position of the peakX(2) half widthX(3) height of the peakX(4) constant term of the backgroundX(5) slope of the background.

5

CHAPTER 2. HOW TO GET ACCESS TO SALS 6

| *| *| *

F || *|| *|| *||| *| *||| * *|||* *| *

5 +|* * **| ** *| ** * *

* | * * *|

* |* |

* |* * |* |

* * |* *** |

* * |** ** |

**** ||

* |||||||||||

.____.____.____.____.____.____.____.____.____.____.-10 0 10

q

A batch job stream would be as follows:

// JOB .....


// EXEC FORTCG,LIB=’SYS1.SALS.LOAD’//FORT.SYSIN DD *

CALL SALS(4000)STOPENDSUBROUTINE MODELF(N,M,NC,X,Q,FO,F,R)DIMENSION X(N),Q(M),FO(M),F(M),R(M)DO 10 I=1,MF(I)=X(3)*X(2)**2/((Q(I)-X(1))**2+X(2)**2)1 + X(4) + X(5)*Q(I)

10 R(I)=FO(I)-F(I)RETURNEND

//GO.SYSIN DD *PROBLEM 1. 5. 3. 5. 4. 5.PARA 5.POSITION 2.4 0.2WIDTH 2.0 0.2HIGHT 6.0 1.0A0 3.5 1.0A1 0.1 0.02

ENDPARADATA 51. 1. 1. 0.1DATA 1 -10.0 2.00DATA 2 -9.6 2.25DATA 3 -9.2 2.27DATA 4 -8.8 2.27DATA 5 -8.4 2.27DATA 6 -8.0 2.48DATA 7 -7.6 2.50DATA 8 -7.2 2.63DATA 9 -6.8 2.45DATA 10 -6.4 2.51DATA 11 -6.0 2.66DATA 12 -5.6 2.70DATA 13 -5.2 2.90DATA 14 -4.8 2.84DATA 15 -4.4 2.77DATA 16 -4.0 2.82DATA 17 -3.6 2.93DATA 18 -3.2 3.08DATA 19 -2.8 3.34DATA 20 -2.4 3.42DATA 21 -2.0 3.32DATA 22 -1.6 3.67DATA 23 -1.2 3.73DATA 24 -0.8 4.05DATA 25 -0.4 4.42DATA 26 0.0 4.66DATA 27 0.4 5.35DATA 28 0.8 5.80DATA 29 1.2 6.51DATA 30 1.6 7.25DATA 31 2.0 7.94DATA 32 2.4 8.37


DATA 33 2.8 8.13DATA 34 3.2 7.68DATA 35 3.6 6.92DATA 36 4.0 6.27DATA 37 4.4 5.74DATA 38 4.8 5.37DATA 39 5.2 5.09DATA 40 5.6 4.65DATA 41 6.0 4.48DATA 42 6.4 4.53DATA 43 6.8 4.56DATA 44 7.2 4.36DATA 45 7.6 4.21DATA 46 8.0 4.50DATA 47 8.4 4.16DATA 48 8.8 4.32DATA 49 9.2 4.09DATA 50 9.6 4.23DATA 51 10.0 4.17

ENDDATAENDSALS//

The first line is the JOB statement valid in your computer center.The next line is the EXEC statement to call a FORTRAN compiler and a loader

using the SALS load module as a library.The first three lines of the FORT.SYSIN file form the user’s main program and the

rest is the user’s model subroutine MODELF, which may be self-explanatory. Pleasenote that the residuals R(I) need to be calculated in the user’s model function subroutine.

Various control parameters in the SALS system are given as a FORTRAN inputdata. The specifications are given in Chapter 3. The first line should be a PROBLEM”command”, usually followed by a parameter block, which is usually followed by ameasurement data block.

2.2 How to read SALS

The source program of SALS is divided into 10 members. Each member consists of 5-20subroutines. The names of the members are as follows:

Member NO. 1. SALS (control of SALS) Subroutines in this member read the com-mands and data and then control the whole job of SALS system.

Member NO. 2. SALSEX (SALS execution) Subroutines in this member set thecontrol data and prepare the working areas to be used in the fitting.

Member NO. 3. LSF (least-squares fitting) Subroutines in this member controlthe least-squares fitting by adjusting the weights, calling the nonlinear least-squares fitting algorithms, and printing out the final results and statistical in-formation.


Member NO. 4. NONLIN (nonlinear least-squares fitting algorithms) Subroutinesin this member are the algorithms for solving nonlinear least-squares problems.This member contains three algorithms,

1. Gauss-Newton method with a damping option.

2. Fletcher’s modification of Marquardt method.

3. Powell’s hybrid method(not ready yet).

Member NO. 5. LINLS (control of linear least-squares method) Subroutines inthis member control the flow in solving a linear least-squares problem. This mem-ber contains two methods:

1. Linear least-squares solution by direct decomposit1ion of the Jacobian matrixwithout setting up the normal equation.

2. Linear least-squares solution by use of the normal equation.

Member NO. 6. LINEAR (linear least-squares algorithms) Subroutines in thismember contain five algorithms for linear least-squares solution.

1. Modified Gram-Schmidt method to obtain the QR decomposition.

2. Householder method to obtain the QR decomposition.

3. Singular value decomposition method.

4. Cholesky method for solving the normal equation.

5. Eigenvalue decomposition method for solving the normal equation.

Member NO. 7. MODL (model functions) Subroutines in this member controlthe calls of the user-coded model subroutines, and include a check system of theuser-coded model subroutines.

Member NO. 8. STAT (statistics) Subroutines in this member calculate and out-put various statistical information.

Member NO. 9. OUT (output subroutines) Subroutines in this member are calledto output final or intermediate results in the fitting. Most of them are designedto be general.

Member NO. 10. DFCHEK (check of Jacobian matrix) Subroutines in this mem-ber are utility routines for checking the correctness of the Jacobian matrix codedby user in subroutine MODELD.

In order to print out the source program, you may call a system print utility, forexample

// EXEC PRINT,DSN=’SYS1.SALS.FORT(LINLS)’

or

// EXEC PRINT,DSN=’SYS1.SALS.FORT’,PARM=ALL

In the second example, all the members of the source program are printed. The lineprinter output may amount nearly to 200 pages.


2.3 Member GUIDE

In the dataset of the source program, an additional member GUIDE is also included.The member GUIDE contains a short description of the system and all the subrou-

tines.

2.4 Compile and run of SALS

If you would like to recompile a part of SALS for the sake of debugging etc., a batch jobstream would be as follows:

// JOB ....

// EXEC FORTCG,LIB=’SYS1.SALS.LOAD’,PARM.FORT=’DEBUG’

//FORT.SYSLIB DD DSN=’SYS1.SALS.FORT’,DISP=SHR

//FORT.SYSIN DD *

CALL SALS(4000)

STOP

END

SUBROUTINE MODELF(N,M,NC,X,Q,FO,F,R)

......

......

END

*STARTC LINEAR

//GO.SYSIN DD *

PROBLEM ......

.

.

.

//

In this case member LINEAR is recompiled with DEBUG option.

Chapter 3

Commands and Data

All the inputs relevant to the fitting procedure are read by the SALS system as the ordi-nary input data to a FORTRAN program. The inputs are divided into two categories:

• SALS commands

• data (in a narrower sense)

3.1 Commands

The SALS commands are listed below. All commands have the same syntax. Eachconsists of a command name followed by a number of control data, not exceeding six.They should be given in a fixed format: (A10,6F10.0). The command name shouldbegin in column 1. Only the first four characters of a command name are necessary forrecognition, e.g. PROBLEM can be abbreviated as PROB. The control data may be ineither the integer or real type. It is recommended to give the decimal point explicitlyas 5.0, even when the value is an integer, since otherwise the decimal point would beassumed at the right end of the field. If a field is left blank or contains value 0 or 0.0, adefault is assumed.

An overview of the commands will be presented in this section, the detailed usageof most commands being reserved for later description.

******* COMMANDS ********(The commands with * in this list are indispensable,

while others are optional and can be omitted.)

1. Commands which control the problem

* PROBLEM initializes the SALS system and specifies global control.

TITLE specifies the number of the title cards ( ¡ 6),which follow this command.

MESSAGE specifies the level of message from SALS control.

OUTPUT specifies the output file.

MODLCHECK check the user-coded model subroutine.

11

CHAPTER 3. COMMANDS AND DATA 12

INITIATE calls user-coded subroutine INITIA.

FINISH calls user-coded subroutine FINISH.

END ends a problem block.

* ENDSALS terminates the processing in the SALS system and returns the controlto the user’s main program.

2. Algorithm commands

METHOD begins a method block.

SALS selects a fitting algorithm as a default.

LINEAR linear fitting.

GAUNEW Gauss-Newton method with a damping option.

MARQUARDT Marquardt method modified by Fletcher.

HYBRID hybrid method by Powell (not yet available).

ENDALG ends an algorithm block.

ENDMETHOD ends a method block.

3. Algorithm specification commands

LLS specifies a linear least squares algorithm used in linear/nonlinear methods.

TOLERANCE specifies the criterions for convergence in nonlinear algorithm.

W-ADJUST specifies the weight adjustment method in robust estimation.

PRINT specifies the level of print-out of the results.

MONITOR specifies the level of monitoring outputs in nonlinear algorithm.

TRACE specifies the level of trace in the first iteration in nonlinear algorithm.

DUMP specifies the level of the dump subroutines.

AINITIATE calls user-coded subroutine AINI at the beginning of the algorithmblock.

AFINISH calls user-coded subroutine AFIN at the end of the algorithm block.

4. Commands which control the parameter inputs

PIO controls the I/O of the parameters.

* PARAMETER gives the upper limit of the number of parameters, etc., usuallyfollowed by the input of the parameters.

ENDPARA ends a parameter input.

5. Commands which control the measurement data input

DIO controls the I/O of the measurement data.


ENDSALS * return to user’s main program

Note that only the METHOD command leading the second or later method blocksis indispensable.

3.3 Elementary control

Fitting procedure in SALS allows a lot of options, which are specified by various SALScommands. In most cases, however, it is sufficient to specify the six control data in thePROBLEM command. The control of algorithm and output has a hierarchical structureand if a subordinate command is omitted or a control data in a command is blank orzero, a default value is assumed depending upon a parent control data.

command name control data in 6F10.0

in A10

* PROBLEM LMODEL, LALGO, LCYCLE, LWADJ0, LOUT0, LSTAT0

---------------------------------------------------------

control value specification

data

LMODEL user-coded model function subroutine is:

1 MODELF

2 MODELD

4 MODELN

(note that 3 is not used)

LALGO algorithm is:

1 linear (well-behaved)

2 linear with high precision algorithm

3 nonlinear, Gauss-Newton (well-behaved)

4 nonlinear, Gauss-Newton

(with high precision linear algorithm)

5 nonlinear, Gauss-Newton

(with high nonlinearity)

6 nonlinear, Marquardt method

modified by Fletcher

7 nonlinear, hybrid method by Powell

(not yet available)

LCYCLE maximum number of iteration

in nonlinear algorithm:

-1 no iteration (calculation at the initial

value only)

1 1


2 3

3 10

4 50

5 200

(4 and 5 are inappropriate for LWADJ0 > 2)

LWADJ0 control of weight adjustment (default is 5).

1 simple least squares with no weight adjustment

2 least squares with a cut-off

3 Huber’s method

4 biweight method by Tukey

5 dynamical biweight method of SALS

LOUT0 level of outputs (default is 4).

1 the final results only

2 (1) + results of each weight adjustment cycle

3 (2) + simple monitoring of nonlinear algorithm

4 (3) + monitoring of nonlinear algorithm

5 (4) + detailed trace of the first iterative

cycle in nonlinear algorithm

6 (4) + monitoring of all cycles in nonlinear

algorithm

7 (5) + (6) with high message level

8 (7) + outputs for debugging

LSTAT0 level of statistical calculation and output.

0 depend on LOUT0 (default)

1 basic statistics for the final results only

2 (1) + error and correlation matrices, eigen

values and eigen vectors of the error

matrix for final results

3 (2) + estimated error for the model prediction

for the final results

4 (1) + basic statistics for every weight

adjustment cycle


adjustment cycle


adjustment cycle

7 (6) + error matrix for every weight adjustment

cycle and for the first iterative cycle

These control data specify the defaults in all the algorithm and algorithm specifica-tion commands, as is described in 5.3.

LMODEL ---> MODLCHECK


| one of the algorithm commands

LALGO ---> | LLS

| TOLERANCE

LCYCLE ----------> (NCYCLE)

LWADJ0 ---> W-ADJUST

| MESSAGE

| PRINT

LOUT0 ---> | MONITOR

| TRACE

| DUMP

LSTAT0 ---> STATISTICS

3.4 Input of parameters

The input of parameters should be given as follows. The PIO command is optional andshould precede the PARAMETER command.


in A10

PIO LPARIN, LINP, LPOUT

* PARAMETER MPARA, LSTEPD

(parameter X0(j), LFIX(j), SIGX0(j), STEPX0(j), TOLX(j)

name) j=1, NPARA (NPARA <= MPARA)

ENDPARA (none)

==========================================================


data

LPARIN parameter input is done:

0 by SALS (default)

1 by user-coded subroutine PARAIN

LINP 0-99 file reference number for parameter input.

(default is 5)

LPOUT Output of parameters for final result is done:

0 by SALS (default)

1 by user-coded subroutine PAROUT

LOUTP file reference number to be used in PAROUT.


(e.g. 7 for punch output)

__________________________________________________________

MPARA maximum number of parameters to be inputted

LSTEPD increment of parameters in finite

differentiation:

1 is given by STEPX0(j) for each parameter

2 is given by SALS except for the first iteration

_________________________________________________________________

input of parameters

parameter not exceeding 10 characters. (The first four

name characters should not be identical to those of

any SALS command names. It is recommended to

begin the name with one blank.)

X0(j) initial guess for the j-th parameter.

LFIX(j) the j-th parameter is:

0 to be varied freely in the fit

1 bound around X0(j) with standard deviation

SIGX0(j)

2 fixed at the initial value X0(j)

SIGX0(j) the standard deviation of X(j) for LFIX(j)=1.

STEPX0(j) increment of X(j) for finite differentiation.

TOLX(j) convergence criterion for X(j),

valid only when LTOLX=1.

_________________________________________________________________

Standard parameter input by the SALS system (LPARIN=0) should follow imme-diately the PARAMETER command. One record corresponds to one parameter. Theinput data have the same syntax as the SALS command, command name replaced by pa-rameter name. The ENDPARA command terminates the parameter input. The numberof parameters (NPARA) should not exceed MPARA given in the PARAMETER com-mand, since the memory space for parameter input is allocated according to MPARA.MPARA may be larger than the actual number of parameters. The data are packed inthe memory if NPARA < MPARA.

The input may be placed on a separate file(LINP) e.g. on a disk. In this case thefile should be allocated as to be read by FORTRAN READ statement. A job controlfor file allocation (DTF, DD, FD, allocate etc.) is necessary before the SALS system isinvoked. The file reference number LINP should be given in the PIO command. TheENDPARA command should be placed on this file at the end of the input.

A user-coded parameter input subroutine PARAIN is called if LPARIN=1 is givenin the PIO command. Input in an arbitrary format and/or any preprocessing is allowed


in PARAIN. The specification of PARAIN is shown in Section 4.5. When this option ischosen, it is the user’s responsibility to find the end of the parameter input data.

3.5 Input of measurement data

The input of measurement data should be given as follows. The DIO command isoptional and should precede the DATA command.


in A10

DIO LDATIN, LIND, LDOUT, LCOUT

* DATA MDATA, NC, LWEIT, FSIG0

(data name) (COORD(i,ic), ic=1,NC), FOBS(i), FSIG(i),

WEIGHT(i),

i=1, NDATA (NDATA <= MDATA)

END (none)

==================================================================


data

LDATIN measurement data are inputted:

0 by SALS (default)

1 by user-coded subroutine DATAIN

LIND 0-99 file reference number for measurement data input

(default is 5)

LDOUT echo of measurement data input is provided by

0 by SALS (default)

1 by user-coded subroutine DATOUT

LCOUT comparative output of measurement and model

prediction is provided:

0 by SALS (default)

1 by user-coded subroutine CALOUT

________________________________________________________________

MDATA maximum number of measurement data to be inputted

NC number of "control variables" or abscissae of the

measurement data. Usually NC is 1, 2 or 3.

NC larger than 3 is allowed if DATAIN, DATOUT and

CALOUT are provided by the user. Default is 1.

LWEIT measurement error is given:


1 in standard deviation FSIG0 for all i

2 in standard deviation FSIG(i) for each i

3 in weight WEIGHT(i),

i.e. FSIG(i) = FSIG0/SQRT(WEIGHT(i))

FSIG0 standard error, i.e. error for which weight is 1.

________________________________________________________________

input of measurement data

data name not exceeding 10 characters. The first four

should not be identical to those of any SALS

command name. It is recommended to begin the name

with one blank.

COORD(i,ic) values for abscissae for this measurement point

ic= 1, NC

FOBS(i) measured value

FSIG(i) measurement error in standard deviation

(valid when LWEIT=2)

WEIGHT(i) measurement error in statistical weight

(valid when LWEIT=3. FSIG0 should be given)

________________________________________________________________

Standard input of the measurement data of the SALS system (LDATIN=0) shouldimmediately follow the DATA command. Each record corresponds to one measurementpoint. It has the same syntax as the SALS command, command name being replacedby a data name. The ENDDATA command terminates the measurement data input.The number of measurement data (NDATA) should not exceed MDATA given in theDATA command, since the memory space for the measurement data input is allocatedaccording to MDATA. MDATA may be larger than the actual number of measurementdata. The data is packed in the memory if NDATA ¡ MDATA.

The input may be placed on a separate file LIND, e.g. on a disk. In this case the fileshould be allocated as to be read by FORTRAN READ statement. A job control for fileallocation (DTF, DD, FD, allocate etc.) is needed before the SALS system is invoked.The file reference number should be given in the DIO command. The ENDDATAcommand should be placed on this file at the end of the input.

User-coded parameter input subroutine DATAIN is called if LDATIN=1 is given inthe DIO command. Input in an arbitrary format and/or any preprocessing are allowedin DATAIN. When this option is chosen it is the user’s responsibility to find the end ofthe measurement data input.

Output concerning the measurement can be performed by user-coded subroutinesDATOUT and CALOUT in a format suited to the user’s specific application.

Chapter 4

Program Interface to SALS

This chapter describes the program interface to SALS. There are two levels at which usersoftware may be interfaced. One is the provision of user processors to tailor the standardsystem, including the provision of user’s model subroutine. The second interface levelis the invocation of SALS utility subroutines from user-written main- or subprograms.Common applications of this type include random number generators and SALS memorydump routines.

4.1 System common blocks

There are more than 50 system common blocks with labels which begin with SC (SalsCommon). In most cases user need not access those commons. Common block labelswhich begin with SC are reserved by the SALS system and should not be used by userfor his own purpose.

The unlabeled common block contains the system work space for arrays, whose sizemay vary according to the number of parameters and observables and to the algorithmsto be used.

It may be necessary to increase its size for applications involving large problems.This is done by increasing the dimension of WK. It is assumed that the size of theunlabeled common block can be actually enlarged by defining it with larger space in themain program, say

COMMON/ /MAXWK, NWKMAX, WK(10000)

while the unlabled commons in the subroutines are left unchanged.

4.2 System subroutines

The SALS system consists of about 140 subroutines. Except those subroutines whichare described in this manual, the name of all ”inner” subroutines begin with Z. User isrecommended to avoid naming a subroutine Z... for his own purpose. It might cause anunexpected error in execution.

20

CHAPTER 4. PROGRAM INTERFACE TO SALS 21

4.3 Main program

SALS system is to be invoked by user’s main program.The entry to SALS is as follows,

SUBROUTINE SALS(MAXWK0)

where MAXWK0 is the dimension of WK in the user’s main program. Since WKis defined as WK(4000) in the SALS system, the main program for a problem of smallscale may be

CALL SALS(4000)

STOP

END

while, for a large problem which requires more work space, large blank commonspace should be provided in user’s main program, e.g.

COMMON / / MAXWK, NMAXWK, WK(10000)

CALL SALS(10000)

STOP

END

4.4 Model subroutines

The model which is to be fitted to the measurement data should be given as a subroutineby user. Three types of subroutines MODELF, MODELD, MODELN are allowed inSALS.

MODELF calculates model prediction F and residual RES

MODELD calculates model prediction F and residual RES as well as the Jacobian matrix,i.e. the partial derivative of F with respect to X.

MODELN calculates F, RES and the normal equation.

The first control data LMODEL in the PROBLEM command specifies which subroutineis provided by user. The entry to model subroutines is as followes.

SUBROUTINE MODELF(NPARA, NDATA, NC, X, COORD, FOBS, F,RES)

DIMENSION X(NPARA), COORD(NDATA, NC), FOBS(NDATA),

1 F(NDATA), RES(NDATA)

SUBROUTINE MODELD(LCALCD, NPARA, NDATA, NC, X, COORD,FOBS,

1 F, RES, DF, LFIX, MDF)


1 F(NDATA), RES(NDATA), DF(MDF, NPARA),LFIX(NPARA)

SUBROUTINE MODELN(LCALCN, NPARA, NDATA, NC, X, COORD,FOBS,


1 F, RES, AWA, AWY, LFIX, FSIE)


1 F(NDATA), RES(NDATA), AWA(NPARA, NPARA),

2 AWY(NPARA), LFIX(NPARA), FSIE(NDATA)

Arguments

NPARA Input number of parameters, including those fixed

NDATA Input number of measurement data, including those

with zero weight

NC Input number of control variables of measurement data

X Input array holding the current parameter values

COORD Input array holding the control variables

FOBS Input array holding the measurement values

F Output array holding the model prediction

in terms of X

RES Output array holding the residual.

Note that RES(i) = FOBS(i) - F(i).

LCALCD flag on calculation of the derivatives DF

Input -1 should not overwrite DF

0 may or may not calculate derivative

1 should calculate derivative DF

Output -1 input was -1

0 have not calculated the derivative

1 have calculated the derivative

DF Output array holding the derivatives

LFIX Input array holding the information on parameter

fixing

0, 1 or 2 as given in the parameter data input

MDF Input range of the first index of DF

LCALCN Input/ flag on calculation of the normal equation

Output same as LCALCD

AWA Output array holding the coefficient matrix of the

normal equation

AWY Output array holding the right-hand side of the normal

equation

FSIE Input array holding the inverse of the effective

error, i.e. FSIE(i) = SQRT(WADJ(i)) / FSIG(i)

Arguments only for input should not be overwritten in the model subroutine.Note:

1. SALS system requires that user’s model subroutine must calculate the residualsRES, where RES(i) = FOBS(i) - F(i). When the model is very precise, FOBS andF are quite close and there may be a big rounding-off error in this subtraction. Usercan cope with this situation, for instance, by applying double precision calculation


inside the user’s subroutine. The whole calculation including finite differentiationin the SALS system is performed in terms of the residual RES and not of F.

2. If NC=1, COORD can be defined as COORD(NDATA).

3. LCALCD is overwritten in the user’s model subroutine only when the derivativeDF is calculated for LCALCD=0. This option should be chosen in case that thederivatives DF can be calculated together with model prediction F without muchextra computing time. Otherwise MODELD should calculate the derivative DFonly for LCALCD=1.

4. It is not necessary to calculate DF(i, j) for such j as LFIX(j) is 2.

4.5 Parameter input subroutine PARAIN

User-coded subroutine PARAIN is called when LPARIN is 1 in the in this subroutine,e.g. PIO command, as deseribed in section 3.4. User can do whatever he likes in thissubroutine, e.g. input in an arbitrary format from any file or any preprocessing. Thespecification is as follows:

SUBROUTINE PARAIN(NAMEX, X0, ALFIX, SIGX0, STEPX0, TOLX,

1 MPARA, NPARA)

DIMENSION NAMEX(3, MPARA), X0(MPARA), ALFIX(MPARA),

1 SIGX0(MPARA), STEPX0(MPARA), TOLX(MPARA)

COMMON /SCPIO / LPARIN, LINP, LPOUT, LOUTP, LEOFP

COMMON /SCPARA/ LSTEPD

Arguments

NAMEX Output array holding the names of parameters

N(1,i) holds the first four characters

N(2,i) holds the second four characters

N(3,i) holds the last two characters

X0 Output array holding the intial values of parameters

ALFIX Output array holding the indices for parameter fixing

in real type, corresponding to LFIX

SIGX0 Output array holding standard deviation for bound

parameters, i.e. those X(i) with ALFIX(i)=1.0.

It is not necessary to output SIGX0(i) for

such i that ALFIX(i) = 0.0 or 2.0.

STEPX0 Output array holding the value of increments for

finite differentiation

TOLX Output array holding the values for tolerance of

convergence in the nonlinear algorithm

MPARA Input maximum number of parameters as given in

PARAMETER command

NPARA Output actual number of parameters.


NPARA <= MPARA

LINP Input as given in PIO command

LSTEPD Input as given in PARAMETER command

Note:

1. These COMMON statements are necessary only when their variables are referredto in this subroutine

2. NPARA should be outputted even when NPARA = MPARA.

4.6 Measurement data input subroutine DATAIN

User-coded subroutine DATAIN is called when LDATIN is 1 in the DIO command, asdescribed in Section 3.5. User can do whatever he likes in this subroutine, e.g. input inan arbitrary format from any file or any preprocessing. The specification is as follows:

SUBROUTINE DATAIN(NAMED, FOBS, FSIG, WEIGHT, COORD, MDATA,

1 NDATA, NC)

DIMENSION NAMED(3, MDATA), FOBS(MDATA), FSIG(MDATA),

1 WEIGHT(MDATA), COORD(MDATA, NC)

COMMON /SCDIO / LDATIN, LIND, LDOUT, LCOUT, LEOFD

COMMON /SCDATA/ FSIG0, LWEIT

Arguments

NAMED Output array holding the names of measurement data

NAMED(1,i) holds the first four characters

NAMED(2,i) holds the second four characters

NAMED(3,i) holds the last two characters

FOBS Output array holding the values for measurement data

(or observables)

FSIG Output array holding the standard deviation for

measurement data, valid when LWEIT=2.

WEIGHT Output array holding the statistical weight for

measurement data, valid when LWEIG=3.

COORD Output array holding the value for the control

variables of the measurement data

MDATA Input maximum number of measurement data, given in

DATA command

NDATA Output actual number of the measurement data

NDATA <= MDATA

NC Input number of control variables, given in the

DATA command

LIND Input as given in the DIO command

FSIG0 Input as given in the DATA command

LWEIT Input as given in the DATA command


Note:

1. These COMMON statements are necessary only when the variables in them arereferred to in this subroutine.

2. NDATA should be outputted even when NDATA = MDATA.

4.7 Measurement data output subroutine DATOUT

User-coded subroutine DATOUT is called when LDOUT=1 is given in the DIO com-mand. The function of this subroutine is to output the measurement data just as givenin the measurement data block. This option may be chosen when the standard outputsubroutine in SALS is inappropriate, e.g. NC ¿ 3. The specification is as follows:

SUBROUTINE DATOUT(NAMED, FOBS, FSIG, FSIGI, COORD, NC,

1 NDATA)

DIMENSION NAMED(3, NDATA), FOBS(NDATA), FSIG(NDATA),

1 FSIGI(NDATA), COORD(NDATA, NC)

COMMON /SCOUT / LOUT, LOUT1, NCHAR


Arguments

(Since all arguments are for input only, they should not be

overwritten in this subroutine.)

NAMED array holding data names

FOBS, FSIG, COORD, NC, NDATA as shown in Section 4.6.

FSIGI array holding the inverse of the standard deviation

= 1/FSIG0 for LWEIT = 1

= 1/FSIG(i) for LWEIT = 2

= SQRT(WEIGHT(i))/FSIG0 for LWEIT = 3

NCHAR number of characters in one line of the output file

"LOUT", as given in the OUTPUT command

Note:

1. Measurement weight WEIGHT(i) cannot be referred to in this subroutine, evenwhen LWEIT = 3. It can be reconstructed by the formula

WEIGHT(i) = (FSIG0 * FSIGI(i) ) ** 2

4.8 Parameter output subroutine PAROUT

This is a user-coded subroutine for the output of the final parameter values to be usedwhen LPOUT=1 in the PIO command. The standard output by the SALS system isretained even when PAROUT is called. This subroutine may be useful for the followingpurposes:


• to output the parameter values on punch cards or disk as can be re-inputted inthe next job by SALS

• to predict some their quantities and their uncertainties in terms of the fitted pa-rameters and error matrix

• to perform simulation using parameter values.

The specification is as follows:

SUBROUTINE PAROUT(NAMEX, XEXT, XSIG, H, LFIX, NPARA, NPIN)

DIMENSION NAMEX(3,NPARA), XEXT(NPARA), XSIG(NPIN),

1 H(NPIN, NPIN), LFIX(NPARA)


Arguments



NAMEX array holding parameter names. See Section 4.5.

XEXT array holding the final parameter values

XSIG array holding the errors for the unfixed parameters

H array holding the lower triangular part of the error

matrix for the unfixed parameters

LFIX array holding the indices on parameter fixing

NPARA number of parameters

NPIN number of unfixed parameters

LOUTP file reference number for PAROUT as given in the PIO

command

Note:

1. This COMMON statement is necessary only when LOUTP is referred to in thissubroutine.

2. ”Unfixed parameters” is the parameters X(j) for which LFIX(j)=0 or 1. Theyare numbered as j = 1 to NPIN, while all the parameters are numbered as j = 1to NPARA. NAMEX, XEXT and LFIX are defined for all the parameters whileXSIG and H are for the unfixed parameters only.

3. The off-diagonal part of the error matrix is given in H(i,j) for i ¿ j. The diagonalcomponents is obtained by the formula XSIG(i) ** 2. User is reminded here againnot to overwrite on H.

4. In case of rank deficiency, some components in XSIG and H may be zero.


4.9 Output subroutine CALOUT for measurement

and prediction

User-coded subroutine CALOUT is called instead of SALS standard system output sub-routine when LCOUT=1 in the DIO command. The specification is as follows:

SUBROUTINE CALOUT(NAMED, COORD, FOBS, FSIG, F, RES, FSIGI,

1 FSIE, SIGF, NDATA, NC, LSIGFI)

DIMENSION NAMED(3, NDATA), COORD(NDATA, NC), FOBS(NDATA),

1 FSIG(NDATA), F(NDATA), RES(NDATA), FSIGI(NDATA),

2 FSIE(NDATA), SIGF(NDATA)



Arguments



NAMED array holding data names, see Section 4.6.

COORD array holding control variables, see Section 4.6.

FOBS array holding measurement data, see Section 4.6.

FSIG array holding the standard deviation for measurement

data

F array holding the model prediction calculated by user’s

model subroutine in terms of the best fit parameters

RES array holding the residual corresponding to F

FSIGI array holding the inverse of the standard deviation,

see Section 4.7.

FSIE array holding the effective FSIGI used in the robust

estimation

SIGF array holding the predicted error for the model

prediction, valid only when LSIGFI = 1.

NDATA number of measurement data

NC number of control variables

LSIGFI flag for SIGF. LSIGFI=1 when SIGF is available.

LOUT file reference number for standard output given by

OUTPUT command

NCHAR number of characters in one line of the file "LOUT"

FSIG0 standard error given by the DATA command

LWEIT see Section 3.5.

Note:

1. These COMMON blocks are necessary when variables in them are referred in thissubroutine.

2. The statistical weight is not stored in the system. If it is necessary, calculate


WT = (FSIG0 * FSIGI(i)) ** 2 weight given by user

WTE = (FSIG0 * FSIE (i)) ** 2 effective weight in

robust estimation

4.10 Nonstandard pre- and post-processings

In this section the following four commands and their related user-coded subroutinesare described. They are optional and supposed to make arbitrary nonstandard pre- andpost-processings.

command name control data

in A10 in 6F10.0

AINITIATE (DAINI(i), i=1,6)

AFINISH (DAFIN(i), i=1,6)

INITIATE (DINIT(i), i=1,6)

FINISH (DFINI(i), i=1,6)

AINITIATE If this command is specified in an algorithm block, CALL AINI(DAINI) isexecuted at the beginning of this algorithm block. User should provide a subrou-tine AINI.

AFINISH If this command is specified in an algorithm block, CALL AFIN(DAFIN)is executed at the end of this algorithm block. It is not executed, however, ifan abnormal termination occurs in the algorithm block. User should provide asubroutine AFIN.

INITIATE This command should occur at the beginning of a measurement data block.If it occurs, CALL INITIA(DINIT) is executed immediately. User should providea subroutine INITIA.

FINISH This command should occur at the end of a measurement data block. If itoccurs, CALL FINISH(DFINI) is executed immediately, even if the algorithm wasterminated abnormally. User should provide a subroutine FINISH.

The use of these four commands are flexible and user can do whatever he likes, solong as the SALS system is not disturbed by them. Information on the details of theinternal structure of the SALS system is necessary to use these subroutines.

Since the standard processing capability of SALS is also very large, user is recom-mended to consider the use of one of the following standard methods, before thinkingof AINITIATE etc.

1. Pre- or post-processing in a different step or job. SALS can input/output variousdata from/to external files (see 3.4 and 3.5).

2. Pre- or post-processing in user’s main program. User’s COMMON blocks, whichshould not be a blank COMMON or a COMMON block with name SC...., can beused to communicate with other user subroutines (see 4.1).


3. Pre-processing in user-coded input subroutine PARAIN or DATAIN (see 4.5 and4.6).

4. Any processing in user-coded model function subroutine MODELF, MODELDand MODELN (see 4.4).

5. Post-processing in user-coded output subroutine PAROUT (see 4.8).

6. Post-processing in user-coded output subroutine CALOUT (see 4.9).

Chapter 5

Structure of the SALS Input

5.1 SALS commands and data — a quick look-up

command control data

PROBLEM LMODEL, LALGO, LCYCLE, LWADJ0, LOUT0, LSTAT0

TITLE NTITLE

MESSAGE LMESS, LPCOMD, LPPD, LPWORK, LPFLOW, LPCLOK

OUTPUT LOUT, NCHAR

MODLCHECK LDFCH, LNUMD

METHOD (none)

SALS NCYCLE

LINEAR NCYCLE

GAUNEW NCYCLE, NFCALL, NREDUC, NFAIL

MARQUARDT NCYCLE, NFCALL, LDADD, AL0, ALAMMX, LNMMQ

HYBRID (not available yet)

LLS LINSOL, LIMP, LRANK

TOLERANCE TOLF, LTOLX, TOLXA, TOLAF, TOLLAM

W-ADJUST LWADJ, CWADJ, NWCYCL, WCONV, SWMIN

PRINT LPRINT, LPPARA, LPCALC, LRESPL, LPROPL

MONITOR LMONIT, LMFLOW, LMPARA, LMCALC, LMRES, NMCYCL

TRACE LTRACE, LPXX, LPMODL, LPA, LPLIN, LPNOL

DUMP LDUMP, LDUMPC, LDUMPW

STATISTICS LSTAT, LSTAT1, LCOVAR, LSIGXD, LSIGF

PIO LPARIN, LINP, LPOUT, LOUTP

PARAMETER MPARA, LSTEPD

(parameter X0(j), LFIX(j), SIGX0(j), STEPX0(j), TOLX(j)

name) j=1, NPARA (NPARA <= MPARA)

ENDPARA (none)

DIO LDATIN, LIND, LDOUT, LCOUT

30

CHAPTER 5. STRUCTURE OF THE SALS INPUT 31

DATA MDATA, NC, LWEIT, FSIG0

(data name) (COORD(i,ic), ic=1,NC), FOBS(i), FSIG(i),

WEIGHT(i), i=1, NDATA (NDATA <= MDATA)

ENDDATA (none)

END (none)

ENDSALS (none)

Model subroutines

SUBROUTINE MODELF(NPARA, NDATA, NC, X, COORD, FOBS, F,RES)


1 F(NDATA), RES(NDATA)

SUBROUTINE MODELD(LCALCD, NPARA, NDATA, NC, X, COORD,FOBS,

1 F, RES, DF, LFIX, MDF)


1 F(NDATA), RES(NDATA), DF(MDF, NPARA),LFIX(NPARA)

SUBROUTINE MODELN(LCALCN, NPARA, NDATA, NC, X, COORD,FOBS,

1 F, RES, AWA, AWY, LFIX, FSIE)


1 F(NDATA), RES(NDATA), AWA(NPARA, NPARA),

2 AWY(NPARA), LFIX(NPARA), FSIE(NDATA)

User subroutines (optional)

SUBROUTINE PARAIN(NAMEX, X0, ALFIX, SIGX0, STEPX0, TOLX,

1 MPARA, NPARA)

DIMENSION NAMEX(3, MPARA), X0(MPARA), ALFIX(MPARA),

1 SIGX0(MPARA), STEPX0(MPARA), TOLX(MPARA)



SUBROUTINE DATAIN(NAMED, FOBS, FSIG, WEIGHT, COORD, MDATA,

1 NDATA, NC)

DIMENSION NAMED(3, MDATA), FOBS(MDATA), FSIG(MDATA),

1 WEIGHT(MDATA), COORD(MDATA, NC)

COMMON /SCDIO / LDATIN, LIND, LDOUT, LCOUT, LEOFD


SUBROUTINE DATOUT(NAMED, FOBS, FSIG, FSIGI, COORD, NC,

1 NDATA)

DIMENSION NAMED(3, NDATA), FOBS(NDATA), FSIG(NDATA),

1 FSIGI(NDATA), COORD(NDATA, NC)




SUBROUTINE PAROUT(NAMEX, XEXT, XSIG, H, LFIX, NPARA, NPIN)

DIMENSION NAMEX(3,NPARA), XEXT(NPARA), XSIG(NPIN),

1 H(NPIN, NPIN), LFIX(NPARA)



SUBROUTINE CALOUT(NAMED, COORD, FOBS, FSIG, F, RES, FSIGI,

1 FSIE, SIGF, NDATA, NC, LSIGFI)

DIMENSION NAMED(3, NDATA), COORD(NDATA, NC), FOBS(NDATA),

1 FSIG(NDATA), F(NDATA), RES(NDATA), FSIGI(NDATA),

2 FSIE(NDATA), SIGF(NDATA)



5.2 Block structure of the SALS input

SALS input data has the following block structure.

1. SALS input consists of

• one or more problem block(s), followed by

• ENDSALS command.

Different problem blocks are independent and processed sequentially.

2. A problem block consists of

• PROBLEM∗ command, followed by

• specification block (if any), followed by

• zero or more algorithm specification commands valid in all method blocks inthis problem block, followed by

• one or more method block(s), followed by

• one or more parameter block(s), followed by

• one or more measurement data block(s), followed by

• END command

Note that the order is fixed. The fitting is performed for all the combinations ofthe method blocks, parameter blocks and measurement data blocks.

3. A specification block consists of the following four commands.

• TITLE followed by title input data

• MESSAGE


• OUTPUT

• MODLCHEK

They can be given in any order and are all omissible.

4. A method block consists of

• METHOD command, followed by

• zero or more algorithm specification commands, valid in this method block,followed by

• one or more algorithm blocks, followed by

• ENDMETHOD command.

Each method block specifies a sequence of least squares algorithms which executesa fitting procedure with the initial parameter values given by the user. If thereare more than one method blocks, the METHOD command leading the secondor latter method blocks cannot be omitted. ENDMETHOD command is nominaland usually omitted.

5. An algorithm block consists of

• an algorithm command, followed by

• zero or more algorithm specification command(s), followed by,

• ENDALG command

If no algorithm command is explicitly given, ”SALS” is assumed. The ENDALGcommand is nominal and usually omitted.

An algorithm specification command can occur in three levels:

(a) at the top part of a problem block. It is valid for all the algorithm commandsin the problem block.

(b) at the top part of a method block. It is valid for all the algorithm commandsin the method block.

(c) in an algorithm block. It is valid only for this algorithm command.

If an algorithm specification command is given doubly or triply for a certain algo-rithm command, the command in the lowest (or inner-most) level is valid.

6. A parameter block consists of

• PIO command, followed by

• PARAMETER∗ command, followed by

• parameter data input, followed by

• ENDPARA command.

7. A measurement data block consists of


• INITIATE command, followed by

• DIO command, followed by

• DATA command, followed by

• measurement data input, followed by

• ENDDATA command, follwed by

• FINISH command.

The order is fixed. When INITIATE or FINISH command occurs, SALS imme-diately calls a user-coded subroutine INITIA or FINISH, in which user can dowhatever he likes, e.g. file manipulation etc., so long as the SALS system is notdisturbed by them.

5.3 Default setting

The SALS commands and their control data which specify algorithms and outputs havea hierarchical structure bearing the control data of the PROBLEM command at thetop, and if one of them is omitted, it is defaulted according to the one in a higher level.The hierarchy of the commands are:

LMODEL ---> MODLCHECK

| one of the algorithm commands

LALGO ---> | LLS

| TOLERANCE

LCYCLE ----------> (NCYCLE)

LWADJ0 ---> W-ADJUST

| MESSAGE

| PRINT

LOUT0 ---> | MONITOR

| TRACE

| DUMP

LSTAT0 ---> STATISTICS

Algorithm commands are subordinate to LALGO and LCYCLE in the PROBLEMcommand, as shown in 3.3. LCYCLE determines the default value of NCYCLE. IfLCYCLE is not given, it is defaulted according to LALGO.

Most algorithm specification commands (W-ADJUST, STATISTICS, MESSGAGE,PRINT, MONITOR, TRACE, and DUMP) have main control data as the first controldata of the command (LWADJ, LSTAT, LMESS, LPRINT, LMONIT, LTRACE, andLDUMP). The other control data in these commands are subordinate to the main controldata and if one of them is missing, it is defaulted according to the main control data ofthe command. The main control data are further subordinate to LWADJ0 (LWADJ),LSTAT0 (LSTAT) and LOUT0 (LMESS, LPRINT, LMONIT, LTRACE and LDUMP)


in the PROBLEM command. If LSTAT0 is missing its default value is determined interms of LOUT0.

In most cases, user need not specify these algorithm specification commands. Thecontrol data in the PROBLEM command provide sufficient flexibility of control. Evenif user want to give those commands, only the main control data may be enough tospecify a desired control. This hierarchical structure of the default setting will makeuser’s control much easier.

The details of the default settings of various commands and their data are describedin the following chapters 6 to 9.

Chapter 6

Commands in Specification Block

A specification block consists of the following commands:


in A10

TITLE NTITLE

MESSAGE LMESS, LPCOMD, LPPD, LPWORK, LPFLOW, LPCLOK

OUTPUT LOUT, NCHAR

MODLCHECK LDFCH, LNUMD

6.1 TITLE command

This command gives the number of ”title cards”, which follow the TITLE command.The title is printed as a heading in the output of SALS. When the TITLE command isomitted, no title will be printed.


data

NTITLE 1-5 number of the title cards to follow.

The title should be given in columns 1-70 in the title cards.

6.2 MESSAGE command

This command specifies the level of message from SALS control, e.g. command echoing,default setting, work area allocation, flow output etc.


data

LMESS main control data of this command

1 minimum output

2 standard output

36

CHAPTER 6. COMMANDS IN SPECIFICATION BLOCK 37

3 detailed output

LPCOMD control of output of inputted commands and

default setting

1 no echoing. Command image will be outputted

only after default setting is done.

2 command image will be outputted both before and

after default setting

3 more detailed output

LPPD control of output of parameter input and

measurement data

1 no output

2 only parameter input will be outputted

3 only measurement data will be outputted

4 (2) + (3)

LPWORK control of message on work area allocation

1 minimum output

2 standard output (given as a compact table)

3 detailed output

LPFLOW control of output on the flow

1 minimum output

2 standard output

3 detailed output

LPCLOK control output on elapsed time

1 minimum output

2 standard output

3 detaied output

The defaults are determined in two steps.

1. When the main control data LMESS is zero, it is defaulted according to LOUT0in the PROBLEM command as follows:

LOUT0 --> LMESS

1, 2 1

3, 4, 6 2

5, 7, 8 3

2. When a control data in the MESSAGE command is zero, it is defaulted accordingto LMESS

LMESS --> LPCOMD LPPD LPWORK LPFLOW LPCLOK

1 1 2 1 1 1

2 2 4 2 2 2

3 3 4 3 3 2


6.3 OUTPUT command

This command specifies the output files. It is used mainly when SALS is invoked in aTSS job or session. The SALS system uses two output files, LOUT and LOUT1 as wellas LOUT.

The file whose reference number is LOUT is the main output file. Messages on thecontrol and flow are outputted to LOUT1.


data

LOUT 1-99 file reference number of the main output

(default = LOUT1)

NCHAR 80-136 number of characters in one line of LOUT.

(default = 132)

In the present version NCHAR is only valid

for the output of one- and two-dimensional

arrays.)

For more details, see A.1 TSS Usage of SALS.

6.4 MODLCHECK command

This command specifies a special option to test the Jacobian or derivative matrix cal-culated by user-coded subroutine MODELD, comparing with those calculated in termsof finite differentiation. Two different tests are provided. By setting LDFCH = 1, 2 or3, user obtains a table which compares the Jacobian calculated by MODELD with thatcalculated by SALS using finite differetiation. In this case no fitting is done.

On the other hand by setting LNUMD = 1, user can try a fitting using finite differ-entiation, when MODELD or MODELN is provided by user.

These two options should not be specified at the same time.

control value specfication

data

LDFCH specifies derivative check option

-1 no testing, normal fitting (default)

1 finite differentiation with a forward step

2 finite differentiation between forward and

backward steps

3 (2) + estimation of the second derivative

D**2 F(i) / D X(j)**2

LNUMD -1 normal fitting using the derivatives given by

user

1 fitting is done using the derivatives calculated


by SALS in terms of finite differentiation

For LMODEL = 1 (MODELF), MODLCHECK command is ignored.

(LDFCH = -1 and LNUMD = -1)

For LMODEL = 4 (MODELN), LDFCH should always be -1.

For LMODEL = 2 (MODELD) and LDFCH > 0, LNUMD should always

be -1.

Chapter 7

Algorithm Commands

The following five algorithm commands are provided. They specify a nonlinear ( andlinear) least-squares algorithms.


in A10

SALS NCYCLE

LINEAR NCYCLE

GAUNEW NCYCLE, NFCALL, NREDUC, NFAIL

MARQUARDT NCYCLE, NFCALL, LDADD, AL0, ALAMMX, LNMMQ

HYBRID (not available yet)

The control data NCYCLE is common in all algorithm commands. It specifies themaximum number of iterations in nonlinear least squares algorithm. Even if the conver-gence criteria are not satisfied, nonlinear iteration is abandoned after NCYCLE times.

The value NCYCLE = -1 means no fitting. In this case SALS calculates modelfunction in terms of the initial parameter values and outputs a table of measured andcalculated values.

If NCYCLE is not specified, it is defaulted according to LCYCLE in the PROBLEMcommand as follows:

LCYCLE --> NCYCLE

-1 -1

1 1

2 3

3 10

4 50

5 200

The control data NFCALL is the maximum number of calls of the model functionsubroutine in an algorithm block. In the present version, however, NFCALL is not used.

7.1 SALS command

This is a dummy algorithm command. If this command is given, the SALS systemselects a suitable algorithm. If no algorithm command occurs in a method block, SALS

40

CHAPTER 7. ALGORITHM COMMANDS 41

is assumed.In the present version, an algorithm is selected according to LALGO in the PROB-

LEM command.

LALGO effective algorithm command

1 LINEAR without iterative improvement

2 LINEAR with iterative improvement

3 GAUNEW without linear improvement and damping

4 GAUNEW with linear improvement but no damping

5 GAUNEW with damping but no linear improvement

6 MARQUARDT

7 HYBRID

If LALGO is not specified in PROBLEM command, it is defaulted according toLMODEL as follows.

LMODEL --> LALGO

1 5 (GAUNEW) (7, in future version)

2,4 5 (GAUNEW)

7.2 LINEAR command

This command specifies linear least squares method. Detailed specifications are givenby LLS command.

LINEAR command is valid only when LALGO = 1 or 2. Otherwise an error messageis printed. In this case the command is neglected and SALS is assumed.

7.3 GAUNEW command1

This command specifies Gauss-Newton algorithm with a damping option. Nonlinearleast squares problem is solved by iterative linear approximation.

The processing for the LINEAR command is included in the Gauss-Newton algorithmas a special case.


data

NREDUC >= 0 "Failure" occurs if better parameter value

is not found after NREDUC times of

step reduction.

NFAIL >= 0 The iteration is abandoned after NFAIL

times of "failure".

In each cycle, partial derivative matrix (Jacobian) is calculated either by MODELDor by finite differentiation, and the displacement or step to the minimum point in theparameter space is predicted on linearity assumption. Model function is evaluated at

CHAPTER 7. ALGORITHM COMMANDS 42

this point. If the sum of squares decreases as compared with that in the last cycle,this cycle is ”success”. Otherwise, the displacement is halved and the model functionsis re-evaluated at the new point. The step will be halved up to NREDUC times (i.e.damping factor = 2**(-NREDUC) ) until smaller sum of squares is found. If no sum ofsquares is found which is smaller than the last one, this cycle is a ”failure”. In this casethe next cycle starts with the point after the NREDUC times of reduction.

If ”failure” occurs NFAIL times, the iteration is abandoned.If NREDUC or NFAIL is not specified, it is defaulted according to LALGO as follows:

LALGO --> NREDUC NFAIL

1,2 0 1

3,4 1 1

5,6,7 4 3

7.4 MARQUARDT command

This command specifies modified Marquardt algorithm with Fletcher’s modification.Instead of damping the parameter changes in the Gauss-Newton algorithm, the diagonalelements of the coefficient matrix of the normal equation are increased in a particularway. The details will be given in a later chapter.


data

LDADD The addition to the diagonal element is

proportinal to:

1 unit matrix

2 diagonal part of the coefficient matrix

3 (1) + (2)

AL0 initial value for lambda

(not used in the present version)

ALAMMX criterion to abandon the algorithm in case of

very large lambda

LNMMQ definition of the norm of a matrix in the

Marquardt algorithm

1 trace norm

2 smaller one among trace and uniform norm

It is recommended to leave all the above control data unspecified. The definitionand default may be changed in a future version of SALS.

7.5 HYBRID command

Not yet available.

Chapter 8

Algorithm Specification Commands

Algorithm specification commands specify detailed control of an algorithm command.As shown in Section 5.2, they can occur in three levels,

1. at the top part of a problem block

2. at the top part of a method block

3. in an algorithm block


in A10

LLS LINSOL, LIMP, LRANK

TOLERANCE TOLF, LTOLX, TOLXA, TOLAF, TOLLAM

W-ADJUST LWADJ, CWADJ, NWCYCL, WCONV, SWMIN

PRINT LPRINT, LPPARA, LPCALC, LRESPL, LPROPL

MONITOR LMONIT, LMFLOW, LMPARA, LMCALC, LMRES, NMCYCL

TRACE LTRACE, LPXX, LPMODL, LPA, LPLIN, LPNOL

DUMP LDUMP, LDUMPC, LDUMPW

STATISTICS LSTAT, LSTAT1, LCOVAR, LSIGXD, LSIGF

AINITIATE DAINI(1), ..... DAINI(6)

AFINISH DAFIN(1), ..... DAFIN(6)

PRINT, MONITOR, TRACE, DUMP and STATISTICS commands, which controlthe output, are described in Chapter 9.

8.1 LLS command

This command specifies linear least squares algorithms used in each (nonlinear or linear)algorithm.

43

CHAPTER 8. ALGORITHM SPECIFICATION COMMANDS 44


data

LINSOL specifies linear least squares method

1 modified Gram-Schmidt method

2 Householder method

3 singular value decomposition method

4 Cholesky method

5 eigenvalue decomposition method

(LINSOL=4 and 5 use normal equation,

while 1, 2 and 3 do not.)

LIMP specifies iterative improvement in linear least

squares method

1 no improvement

2 apply improvement only in the NCYCLE-th cycle or

near convergence

3 apply improvement in each cycle

LRANK specifies the procedure when rank deficiency is

detected

1 search a solution in a subspace, killing several

parameters which were not selected as pivots.

The linear least squares method is not changed.

2 change the method to singular value decomposi

tion from modified Gram-Schmidt or Householder,

or to eigenvalue decomposition from Cholesky.

Search a solution in a subspace, killing small

singular values or eigenvalues.

3 same as (2). If rank deficiency is found again

in the singular value or eigenvalue

decomposition, the iteration is abandoned.

4 the iteration is abandoned at once.

If LLS command or some control data in it are missing, the default values are deter-mined as follows:

In case of LMODEL=1 or 2 or LMODEL=4 with LNUMD=1:

algorithm LALGO --> LINSOL LRANK LIMP

LINEAR 1 1 3 1

2 1 1 3

GAUNEW 3 ( 1) 1 3 1

4 ( 2) 1 1 2

5 (>5) 1 1 1

MARQUARDT (1,3) 1 1 1


6(4,5,7) 1 1 1

HYBRID 7 (not yet available)

In case of LMODEL=4 with LNUMD=0:

algorithm LALGO --> LINSOL LRANK LIMP

LINEAR 1 4 3 1

2 4 1 3

GAUNEW 3 ( 1) 4 3 1

4 ( 2) 4 1 2

5 (>5) 4 1 1

MARQUARDT 6 (1-5,7) 4 1 1

8.2 TOLERANCE command

This command specifies convergence criteria in a nonlinear least squares algorithm.


data

TOLF tolerance for relative change in the weighted

sum of squares

LTOLX 1-5 specifies the criterion for the change in

parameter values X

TOLXA tolerance common in all X.

valid only for LTOLX = 2 - 5.

TOLAF tolerance for the absolute value of sum of

squares

TOLLAM tolerance for lambda in Marquardt algorithm

Convergence criterion is that conditions a) and b) are both satisfied or condition c)is satisfied.

a) Relative change of the weighted sum of squares at k-th cycle S(k) satisfies

S(k − 1) ≥ S(k) > (1− TOLF ) ∗ S(k − 1).

Even if S(k) increases slightly,

(1 + TOLF ) ∗ S(k − 1) > S(k) > S(k − 1),

the SALS system regards that this condition a) is satisfied. In this case, a warningmessage is printed saying that the increase may be due to round-off error andtolerable.


b) Changes XX(j) in parameter values satisfy one of the following conditions, as speci-

fied by LTOLX:

LTOLX criterion1 |XX(j)| < TOLX(j) for j = 1, ...NPARA.

TOLX(j) is given by parameter input data, see 3.4.2 |XX(j)| < TOLXA ∗ (1 + |X(j)|) for j = 1, ...NPARA.3 |XX(j)| < max(TOLXA ∗XSIG(j), EPS ∗ |X(j)|).

XSIG(j) is the uncertainty of X(j) estimated interms of linearized least squares method.EPS is the relative precision of floating number.

4∑ |XX(j)| < TOLXA ∗∑ |X(j)|

5∑XX(j)2 < TOLXA2 ∗∑X(j)2

c) Weighted sum of squares becomes nearly zero,

S(k) < TOLAF

In the Marquardt algorithm, if λ is larger than TOLLAM ∗ ‖(ATWA)−1‖ (or some-thing similar), a warning message is printed after the convergence is detected.

Nonlinear iteration is abandoned in the following cases, even if convergence criteriaare not satisfied:

d) Number of iterative cycle > NCY CLE.

e) Number of model subroutine calls > NFCALL. (not used in the present version).

In case LINEAR command is given explicitly or implicitly, TOLERANCE commandis neglected.

If TOLERANCE command or some control data in it are missing, the followingdefault values are assumed.

TOLF = 0 or < 10−6 ⇒ TOLF = max(√EPS, 10−4)

LTOLX = 0 ⇒ LTOLX = 3for LTOLX = 3, TOLXA = 0 or < 10−3 ⇒ TOLXA = 10−2

for LTOLX 6= 3, TOLXA = 0 or < 10−6 ⇒ TOLXA = 10−4

TOLAF = 0 or < 10−6 ⇒ TOLAF = 10−4

TOLLAM = 0 or< 1.0⇒ TOLLAM = 10.0

8.3 W-ADJUST command

SALS applies various robust estimations in order to find a good set of parameters evenif the measurement data and/or user’s model are incomplete. Robust estimation isperformed by changing the weights of measurement data dynamically, suppressing thosedata points whose residuals are large. The adjusted weights are kept unchanged during anonlinear iteration. The weights are re-adjusted according to the residuals correspondingto the final result of the last nonlinear least squares algorithm. This procedure (called asweight adjustment cycle) is repeated up to NWCYCL times iteratively until the changesin weights become small enough.


Five or less W-ADJUST commands can occur sequentially in an algorithm block. Ifmultiple W-ADJUST commands are given, iteration of weight adjustment correspond-ing to each W-ADJUST command is performed sequentially. Multiple W-ADJUSTcommands are allowed also in higher levels.

Following is the notation used in the explanation

FSIG(i) estimated error of the i-th measurement(given by user in measurement data block)

FSIG0 standard error (error corresponding to unit weight)RES(i) residual for the i-th measurement

RES(i) = FOBS(i)− F (i)F (i) is calculated by the user’s model subroutine

Z(i) normalized residualZ(i) = RES(i)/FSIG(i)

SW median of the moduli of Z(i)WEIGHT(i) user’s weight

WEIGHT (i) = FSIG02/FSIG(i)2

WADJ(i) weight adjustment faction in robust estimationWEFF(i) effective weight in robust estimation

WEFF (i) = WEIGHT (i) ∗WADJ(i)


data

LWADJ specifies the method of weight adjustment

1 simple least-squares with no weight adjustment

WADJ(i) = 1.0

2 least-squares with cut-off:

WADJ(i) = 1.0 if |Z(i)| =< CWADJ * SW,

WADJ(i) = 0.0 otherwise

3 Huber’s estimation:

WADJ(i) = 1.0 if |Z(i)| =< CWADJ * SW,

WADJ(i) = CWADJ * SW / |Z(i)| otherwise

4 Tukey’s biweight method

WADJ(i) = (1 - (Z(i)/(CWADJ*SW))**2) ** 2

if |Z(i)| =< CWADJ * SW

WADJ(i) = 0.0 otherwise.

5 dynamical robust estimation: selects the value

of CWADJ in the Tukey’s biweight methods

according to SW at each weight adjustment

cycle.

SW =< 5 biweight method with CWADJ=6.0

5 < SW =< 100 biweight method with CWADJ=10.0

100 < SW biweight method with CWADJ=20.0

CWADJ gives reference scale for weight adjustment.


no meaning for LWADJ=1 or 5.

NWCYCL maximum number of weight cycles.

WCONV convergence criterion for the weight adjustment:

sum of |WEFF(i) - last WEFF(i)|

< WCONV * sum of WEFF(i)

SWMIN The parameter refinement will be quitted if

SW < SWMIN.

The default values for the control data of the weight adjustment are determined asfollows:

1) If LWADJ0=0 in the PROBLEM command, it is defaulted to 5.

2) If W-ADJUST command is missing, the following sequence of W-ADJUST com-mands is assumed according to LWADJ0.

LWADJ0 seq. LWADJ CWADJ NWCYCL WCONV SWMIN1 (1) 1 — 1 0.005 0.012 (1) 2 1000.0 1 0.02 0.01

(2) 2 100.0 3 0.005 0.013 (1) 3 100.0 1 0.02 0.01

(2) 3 10.0 4 0.005 0.014 (1) 4 100.0 1 0.02 0.01

(2) 4 10.0 4 0.005 0.015 (1) 5 — 5 0.005 0.01

3) If some control data in a W-ADJUST command are missing or given improperly,they are defaulted as follows:

If LWADJ = 0 then LWADJ = LWADJ0.

If CWADJ ≤ 3.0 or NWCY CL ≤ 0 or WCONV ≤ 10−4 or SWMIN ≤ 10−4,then

LWADJ → CWADJ NWCYCL WCONV SWMIN1 — 1 0.02 0.012 (*) 1000.0 1 0.02 0.01

100.0 3 0.02 0.013 (*) 100.0 1 0.02 0.01

10.0 4 0.02 0.014 (*) 100.0 1 0.02 0.01

10.0 4 0.02 0.015 — 5 0.02 0.01

The default values with (*) in the above table are applied only to the first ofmultiply given W-ADJUST commands.

Chapter 9

Commands which Control Outputs

PRINT, MONITOR, TRACE and DUMP commands as well as MESSAGE specify theoutput levels of the SALS system. The default values for the control data are determinedby the main control data, and the default of the main control data is determined byLOUT0 in the PROBLEM command, as follows:

LOUT0 --> LMESS LPRINT LMONIT LTRACE LDUMP

1 1 1 -1 -1 -1

2 1 3 1 -1 -1

3 2 3 3 -1 -1

4 2 3 6 -1 -1

5 3 3 6 1 -1

6 2 3 8 -1 -1

7 3 3 8 1 -1

8 3 3 8 2 1

The MESSAGE command is described in 6.2.STATISTICS command controls statistical outputs. The defaults of this command

are specified by the control data LSTAT0 of PROBLEM command.

9.1 PRINT command

This command specifies the level of output of the final results, including parametervalues, table of measurement data and calculated values, residual plot and normal prob-ability plot.


data

LPRINT main control data of this command

1 output at the final stage only

2 (1) + normal probability plot at the final stage

3 output at every weight adjustment cycle

LPPARA controls parameter outputs

1 at the final stage only

49

CHAPTER 9. COMMANDS WHICH CONTROL OUTPUTS 50

2 at every weight adjustment cycle

LPCALC controls the outputs of the table of measurement

data and calculated values


2 at every weight cycle

LRESPL controls residual plot (or histogram)

-1 no output



LPROPL controls normal probability plot

-1 no output



If a control data of PRINT command is zero or missing, it is defaulted according tothe main control data LPRINT:

LPRINT --> LPPARA LPCALC LRESPL LPROPL

1 1 1 1 -1

2 1 1 1 1

3 2 2 2 1

9.2 MONITOR command

This command controls the monitoring of the intermediate results in nonlinear fitting:i.e. flow controls inside nonlinear algorithm, residual sum of squares (RSS), parametervalues (X), table of measurement data (FOBS) and calculated values (F), residuals(RES), and residual plot or histogram.


data

LMONIT main control data of the command

-1 no monitoring, except convergence or abandonment

messages

1 minimum monitoring. RSS at every cycle.

2 simple monitoring (RSS and X) at every NMCYCL-th

cycle

3 simple monitoring at every cycle

4 medium monitoring (RSS, X and RES) at every

NMCYCL-th cycle

5 medium monitoring at every cycle

6 residual plot (plus RSS and X) at every

NMCYCL-th cycle


7 resudual plot (plus RSS and X) at every cycle

8 detailed monitoring (RSS, X, FOBS-F table and

residual plot) at every NMCYCL-th cycle

LMFLOW specifies the monitor of the flow in nonlinear

algorithm

-1 no output, except convergence or abadonment

messages

1 RSS at every cycle

2 RSS and control parameters at every cycle

LMPARA specifies the monitor of parameter values (X) in

nonlinear algorithm

-1 no output

1 simple output at every NMCYCL-th cycle

2 simple output at every cycle

3 detailed output at every NMCYCLE-th cycle,

and simple output at other cycles

4 detailed output at every cycle

LMCALC specifies the output of the table of FOBS-F-RES

in nonlinear algorithm

-1 no output

1 RES only at every NMCYCL-th cycle

2 RES only at every cycle

3 Table of FOBS-F-RES at every NMCYCL-th cycle

4 Table of FOBS-F-RES at every cycle

LMRES specifies the output of the residual plot or

histogram in nonlinear algorithm

-1 no output

1 at every NMCYCL-th cycle

2 at every cycle

NMCYCL specifies the period of monitoring. "At every

NMCYCL-th cycle" includes the first and

(n*NMCYCL+1)-th cycles and the cycle of

convergence or abandonment.

If a control data in MONITOR command is zero or missing, it is defaulted accordingto the main control data LMONIT:

LMONIT --> LMFLOW LMPARA LMCALC LMRES

-1 -1 -1 -1 -1

1 1 -1 -1 -1

2 1 1 -1 -1

3 1 2 -1 -1

4 2 3 1 -1


5 2 3 2 -1

6 2 3 -1 1

7 2 3 -1 2

8 3 3 3 1

9 3 4 4 2

NMCYCL=5 if NCYCLE =< 20,

NMCYCL=10 otherwise.

9.3 TRACE command

This command specifies the detailed traing of the intermediate results of the linear (orlinearized) least squares calculation in the early iterative cycles, i.e. the solution of thelinear least squares method, iterative improvement, parameter values and residals at acall of user’s model function subroutine, Jacobian matrix or normal equation, decom-posed matrices (Q, R, U, ... ) in linear algorithm, internal parameter in a nonlinearalgorithm.


data

LTRACE main control data of the command.

-1 no trace output.

1 simple trace at the first cycle

(IWADJ=1, IWCYCL=1 and ICYCLE=1).

2 detailed trace at the first cycle.

3 simple trace at the first two cycles

(IWADJ=1, IWCYCLE=1 and ICYCLE=1,2).

4 detailed trace at the first two cycles.

5 simple trace at the first cycle of every weight

adjustment cycle (ICYCL=1).

6 detailed trace at the first cycle of every

weight adjustment cycle.

7 simple trace at every cycle.

8 detailed trace at every cycle.

LPXX -1 to 8 simple trace: linear solution XX.

detailed trace: XX and iterative improvement

XD.

LPMODL -1 to 8 simple trace: parameter values (XEXT) at

every call of model subroutine.

detailed trace: XEXT and residuals RES.

LPA -1 to 8 simple trace: Jacobian DFIN or normal

equation AWA0 given by user.

detailed trace: DFIN or AWA0 and weighted


Jacobian or normal equation.

LPLIN -1 to 8 simple trace: condition number in linear

solution.

detailed trace: plus Q, R etc.

LPNOL -1 to 8 simple trace: sequence of RSS in a nonlinear

cycle.

detailed trace: not yet available.

All the defaults of the control data are equal to LTRACE.

9.4 DUMP command

This command releases SALS debug dump utilities. FORTRAN statements

CALL DUMPC(i) and/or CALL DUMPWK(i)

can be inserted at any place, whether in the SALS system or in user’s program. Theyare not effective if DUMP command is not given. These statements, used with DUMPcommand, dump out the following control parameters and work areas in a suitableformat.

CALL DUMPC(1) : COMMON variables related to command

analysis and data input.

CALL DUMPC(2) : COMMON variables related to work space

allocation.

CALL DUMPC(3) : COMMON variables related to output

control.

CALL DUMPC(4) : COMMON variables related to weight

adjustment, algorithm and statistics.

CALL DUMPWK(1) : one-dimentional arrays with size NPARA.

CALL DUMPWK(2) : one-dimentional arrays with size NDATA.

CALL DUMPWK(3) : two-dimensional arrays with size

(NPARA * NPARA).

CALL DUMPWK(4) : two-dimensional arrays with size

(NDATA * NPARA).


data

LDUMP main control data of the command

-1 no dump. DUMPC and DUMPWK do not work.

1 only DUMPC is released.

2 both DUMPC and DUMPWK are released.

LDUMPC control of DUMPC utility.


-1 DUMPC does not work.

1 CALL DUMPC(1) is released.




10 CALL DUMPC(i) i=1 to 4 is released.

LDUMPW control of DUMPWK utility.

-1 DUMPWK does not work.

1 CALL DUMPWK(1) is released.




10 CALL DUMPWK(i) i=1 to 4 is released.

The default values of the control data are:

LDUMP --> LDUMPC LDUMPW

-1 -1 -1

1 10 -1

2 10 10

9.5 STATISTICS command

STATISTICS command controls the statistical outputs including standard deviation,AIC, error matrix of the parameters, and the prediction error in the calculated value F.


data

LSTAT main control data of this command

1 basic statistics for the final results only

2 (1) + error and correlation matrices of the

parameters, its eigen values and eigen

vectors for the final results

3 (2) + estimated error in the model prediction

SIGF for the final results


adjustment cycle amd SIGF for the final

results.


adjustment cycle and SIGF for the final

results.


adjustment cycle

7 (5) + error and correlation matrices


for the first iterative cycle

LSTAT1 specifies the output of basic statistics

(number of data, number of parameters, degrees

of freedom, standard deviation, AIC etc.)


2 (1) + at every weight adjustment cycle

3 (2) + at the first cycle

(i.e. IWADJ=1, IWCYCL=1, ICYCLE=1)

LCOVAR specifies output of error and correlation

matrices for the parameters

-1 no output

1 to 3 same as LSTAT1

LSIGXD specifies output of the eigenvalues and

eigenvectors of the error matrix.

-1 to 3 same as LCOVAR

LSIGF specifies output of the predicted error for F

-1 to 3 same as LCOVAR

If STATICTICS command is missing or some control data are zero, the default valuesare assumed as follows:

1) IF LSTAT0=0 in the PROBLEM command, it is defaulted according to LOUT0.

LOUT0 --> LSTAT0

1 2

2 5

3,4,6 5

5,7,8 7

2) If LSTAT=0 , it is defaulted as LSTAT = LSTAT0.

3) The control data are defaulted according to LSTAT

LSTAT --> LSTAT1 LCOVAR LSIGXD LSIGF

1 1 -1 -1 -1

2 1 1 1 -1

3 1 1 1 1

4 2 -1 -1 -1

5 2 1 1 -1

6 2 1 1 1

7 3 3 1 1

Appendices

A.1 TSS Usage of SALS

SALS is originally designed to be used in a batch job. Howerver, it can also be used ina TSS job. A TSS job is characterized by the following features:

• Large input is difficult and often mistakable.

• Large output takes a lot of time.

• In many cases, the width of the output is 80 characters.

• Hard copy is not available when using a video terminal.

In order to cover these defects, SALS provides various capabilities even though fullyinteractive processing is not provided in the present version. Needless to say, they arealso valid in a batch job.

A1.1 Input from separate files (or datasets)

In the example in 2.1, parameters and measurement data are given in the input datastream together with the SALS command. If those input data are provided beforehandin a separate dataset, it can be referred to by SALS.

For this purpose user can specify the file reference number byLINP control data in the PIO command and/orLIND control data in the DIO command.

For example,

allocate dd(FT08F001) dsn(PARA1.DATA) shr

allocate dd(FT09F001) dsn(DATA1.DATA) shr

loadgo MODEL(PROG1) lib(’SYS1.SALS.LOAD’) fortlib

PROB 1. 5. ....

PIO 8.

PARA 5.

DIO 9.

DATA 50.

ENDSALS

In this case, user’s main program and model subroutine are stored as object modulesin MODEL.OBJ(PROG1), and datasets PARA1 and DATA1 include the parameterinput data and measurement data in the standard format of SALS.

56

Appendices 57

ENDPARA and ENDDATA commands are not effective unless they appear in thespecified files.

In this case, all the output of SALS will come to the terminal. See the next sectionto obtain only the messages on the terminal and print the results by a line printer.

A1.2 Separation of outputs

SALS has two kinds of output which are allocated to the file reference numbers LOUTand LOUT1. While the standard values are

LOUT1 = 6 and LOUT = 6,LOUT can be changed by the OUTPUT command (see 6.3).The output to LOUT contains the whole set of outputs including the messages,

intermediate print outs, and the final results. The output to LOUT1 is done only whenLOUT1 = LOUT, and it contains only processing messages, error messages, and finalparameter values. Bulky outputs are given in LOUT only.

When SALS is invoked in a TSS job, it may be usefule to allocate LOUT to a lineprinter and LOUT1 to the terminal, for example,

attribute IN INPUT

allocate dd(FT08F001) dsn(SALS.DATA(PARA1)) shr using(IN)

allocate dd(FT09F001) dsn(SALS.DATA(DATA1)) shr using(IN)

allocate dd(FT01F001) sysout(T)

loadgo MODEL(PROG1) lib(’SYS1.SALS.LOAD’) fortlib

PROB 1. 5. ....

OUTPUT 1.

PIO 8.

PARA 5.

DIO 9.

DATA 50.

ENDSALS

A1.3 Output width

In some cases, user may want to output all the results on his terminal regardlers to itslength. The line size of most terminals are 80 characters. Since the output from SALS

make the best use of the full line printer width (usually 132), one line may be dividedinto two lines on the terminal so that the output is hardly readable. To cope with thisdifficulty, SALS provides a function to specify the line size of LOUT file. In the presentversion, vectors and matrices are outputted with adjustable width but messages andgraphs are not.

The width can be given as the first control data of the OUTPUT command (NCHAR)and may take the value between 80 and 136 (default is 132).

Appendices 58

B.1 Licence Agreement of SALS System

SALS Group has agreed to grant the USER Institution a non-exclusive licence to makeuse of SALS System subject to the following terms and conditions.

1. Program System SALS (Statistical Analysis with Least-Squares Fitting) is copy-righted by SALS Group, and is distributed by SALS Group in accordance with theapproval of The Computer Centre of the University of Tokyo.

2. SALS Group supplies the source program and a set of documents of SALS Systemto the USER Institution.

3. SALS System will be used only for academic and/or educational purposes, and willnot be used for commercial and/or military purposes.

4. SALS Group accepts no responsibility for conversion, maintenance, or usage ofSALS System in the USER Institution.

5. The source program of SALS System will be open to the users in the USER Insti-tution for the purpose of keeping the academic reliability.

6. If the USER Institution and its users find any error in SALS System, they willnotify it to SALS Group.

7. The USER Institution and its users may modify, if necessary, SALS System fortheir own use. In this case, they will notify the modification to SALS Group bysending the source listing of the modification together with its explanation.

8. The USER Institution and its users will neither sub-license nor transfer SALS

System and/or its modifications to any other party.

9. The users of SALS System will cite the program name and its authors of SALS

System in case of publishing any result obtained by use of SALS System and/or itsmodifications.

sals users’ manual (version 2.5) - olab.is.s.u...

Documents