SLATEC Routines --- DBOLS ---
*DECK DBOLS
SUBROUTINE DBOLS (W, MDW, MROWS, NCOLS, BL, BU, IND, IOPT, X,
+ RNORM, MODE, RW, IW)
C***BEGIN PROLOGUE DBOLS
C***PURPOSE Solve the problem
C E*X = F (in the least squares sense)
C with bounds on selected X values.
C***LIBRARY SLATEC
C***CATEGORY K1A2A, G2E, G2H1, G2H2
C***TYPE DOUBLE PRECISION (SBOLS-S, DBOLS-D)
C***KEYWORDS BOUNDS, CONSTRAINTS, INEQUALITY, LEAST SQUARES, LINEAR
C***AUTHOR Hanson, R. J., (SNLA)
C***DESCRIPTION
C
C **** All INPUT and OUTPUT real variables are DOUBLE PRECISION ****
C
C The user must have dimension statements of the form:
C
C DIMENSION W(MDW,NCOLS+1), BL(NCOLS), BU(NCOLS),
C * X(NCOLS+NX), RW(5*NCOLS)
C INTEGER IND(NCOLS), IOPT(1+NI), IW(2*NCOLS)
C
C (Here NX=number of extra locations required for option 4; NX=0
C for no options; NX=NCOLS if this option is in use. Here NI=number
C of extra locations required for options 1-6; NI=0 for no
C options.)
C
C INPUT
C -----
C
C --------------------
C W(MDW,*),MROWS,NCOLS
C --------------------
C The array W(*,*) contains the matrix [E:F] on entry. The matrix
C [E:F] has MROWS rows and NCOLS+1 columns. This data is placed in
C the array W(*,*) with E occupying the first NCOLS columns and the
C right side vector F in column NCOLS+1. The row dimension, MDW, of
C the array W(*,*) must satisfy the inequality MDW .ge. MROWS.
C Other values of MDW are errors. The values of MROWS and NCOLS
C must be positive. Other values are errors. There is an exception
C to this when using option 1 for accumulation of blocks of
C equations. In that case MROWS is an OUTPUT variable ONLY, and the
C matrix data for [E:F] is placed in W(*,*), one block of rows at a
C time. MROWS contains the number of rows in the matrix after
C triangularizing several blocks of equations. This is an OUTPUT
C parameter ONLY when option 1 is used. See IOPT(*) CONTENTS
C for details about option 1.
C
C ------------------
C BL(*),BU(*),IND(*)
C ------------------
C These arrays contain the information about the bounds that the
C solution values are to satisfy. The value of IND(J) tells the
C type of bound and BL(J) and BU(J) give the explicit values for
C the respective upper and lower bounds.
C
C 1. For IND(J)=1, require X(J) .ge. BL(J).
C (the value of BU(J) is not used.)
C 2. For IND(J)=2, require X(J) .le. BU(J).
C (the value of BL(J) is not used.)
C 3. For IND(J)=3, require X(J) .ge. BL(J) and
C X(J) .le. BU(J).
C 4. For IND(J)=4, no bounds on X(J) are required.
C (the values of BL(J) and BU(J) are not used.)
C
C Values other than 1,2,3 or 4 for IND(J) are errors. In the case
C IND(J)=3 (upper and lower bounds) the condition BL(J) .gt. BU(J)
C is an error.
C
C -------
C IOPT(*)
C -------
C This is the array where the user can specify nonstandard options
C for DBOLSM( ). Most of the time this feature can be ignored by
C setting the input value IOPT(1)=99. Occasionally users may have
C needs that require use of the following subprogram options. For
C details about how to use the options see below: IOPT(*) CONTENTS.
C
C Option Number Brief Statement of Purpose
C ------ ------ ----- --------- -- -------
C 1 Return to user for accumulation of blocks
C of least squares equations.
C 2 Check lengths of all arrays used in the
C subprogram.
C 3 Standard scaling of the data matrix, E.
C 4 User provides column scaling for matrix E.
C 5 Provide option array to the low-level
C subprogram DBOLSM( ).
C 6 Move the IOPT(*) processing pointer.
C 99 No more options to change.
C
C ----
C X(*)
C ----
C This array is used to pass data associated with option 4. Ignore
C this parameter if this option is not used. Otherwise see below:
C IOPT(*) CONTENTS.
C
C OUTPUT
C ------
C
C ----------
C X(*),RNORM
C ----------
C The array X(*) contains a solution (if MODE .ge.0 or .eq.-22) for
C the constrained least squares problem. The value RNORM is the
C minimum residual vector length.
C
C ----
C MODE
C ----
C The sign of MODE determines whether the subprogram has completed
C normally, or encountered an error condition or abnormal status. A
C value of MODE .ge. 0 signifies that the subprogram has completed
C normally. The value of MODE (.GE. 0) is the number of variables
C in an active status: not at a bound nor at the value ZERO, for
C the case of free variables. A negative value of MODE will be one
C of the cases -37,-36,...,-22, or -17,...,-2. Values .lt. -1
C correspond to an abnormal completion of the subprogram. To
C understand the abnormal completion codes see below: ERROR
C MESSAGES for DBOLS( ). AN approximate solution will be returned
C to the user only when max. iterations is reached, MODE=-22.
C Values for MODE=-37,...,-22 come from the low-level subprogram
C DBOLSM(). See the section ERROR MESSAGES for DBOLSM() in the
C documentation for DBOLSM().
C
C -----------
C RW(*),IW(*)
C -----------
C These are working arrays with 5*NCOLS and 2*NCOLS entries.
C (normally the user can ignore the contents of these arrays,
C but they must be dimensioned properly.)
C
C IOPT(*) CONTENTS
C ------- --------
C The option array allows a user to modify internal variables in
C the subprogram without recompiling the source code. A central
C goal of the initial software design was to do a good job for most
C people. Thus the use of options will be restricted to a select
C group of users. The processing of the option array proceeds as
C follows: a pointer, here called LP, is initially set to the value
C 1. This value is updated as each option is processed. At the
C pointer position the option number is extracted and used for
C locating other information that allows for options to be changed.
C The portion of the array IOPT(*) that is used for each option is
C fixed; the user and the subprogram both know how many locations
C are needed for each option. A great deal of error checking is
C done by the subprogram on the contents of the option array.
C Nevertheless it is still possible to give the subprogram optional
C input that is meaningless. For example option 4 uses the
C locations X(NCOLS+IOFF),...,X(NCOLS+IOFF+NCOLS-1) for passing
C scaling data. The user must manage the allocation of these
C locations.
C
C 1
C -
C This option allows the user to solve problems with a large number
C of rows compared to the number of variables. The idea is that the
C subprogram returns to the user (perhaps many times) and receives
C new least squares equations from the calling program unit.
C Eventually the user signals "that's all" and then computes the
C solution with one final call to subprogram DBOLS( ). The value of
C MROWS is an OUTPUT variable when this option is used. Its value
C is always in the range 0 .le. MROWS .le. NCOLS+1. It is equal to
C the number of rows after the triangularization of the entire set
C of equations. If LP is the processing pointer for IOPT(*), the
C usage for the sequential processing of blocks of equations is
C
C IOPT(LP)=1
C Move block of equations to W(*,*) starting at
C the first row of W(*,*).
C IOPT(LP+3)=# of rows in the block; user defined
C
C The user now calls DBOLS( ) in a loop. The value of IOPT(LP+1)
C directs the user's action. The value of IOPT(LP+2) points to
C where the subsequent rows are to be placed in W(*,*).
C
C .DBOLSM, DCOPY, DNRM2, DROT, DROTG, IDAMAX, XERMSG
C***REVISION HISTORY (YYMMDD)
C 821220 DATE WRITTEN
C 891006 Cosmetic changes to prologue. (WRB)
C 891006 REVISION DATE from Version 3.2
C 891214 Prologue converted to Version 4.0 format. (BAB)
C 900510 Convert XERRWV calls to XERMSG calls. (RWC)
C 920501 Reformatted the REFERENCES section. (WRB)
C***END PROLOGUE DBOLS