UMAG
This routine handles MATH/LIBRARY and STAT/LIBRARY type REAL and double precision options.
Required Arguments
PRODNM — Product name. Use either “MATH” or “STAT.” (Input)
ICHP — Chapter number of the routine that uses the options. (Input)
IACT — 1 if user desires to “get” or read options, or 2 if user desires to “put” or write options. (Input)
IOPTS — Integer array of size NUMOPT containing the option numbers to “get” or “put.” (Input)
SVALS — Array containing the option values. These values are arrays corresponding to the individual options in IOPTS in sequential order. The size of SVALS is the sum of the sizes of the individual options. (Input/Output)
Optional Arguments
NUMOPT — Size of IOPTS. (Input)
Default: NUMOPT = size (IOPTS,1).
FORTRAN 90 Interface
Generic: CALL UMAG (PRODNM, ICHP, IACT, IOPTS, SVALS [, …])
Specific: The specific interface names are S_UMAG and D_UMAG.
FORTRAN 77 Interface
Single: CALL SUMAG (PRODNM, ICHP, IACT, NUMOPT, IOPTS, SVALS)
Double: The double precision name is DUMAG.
Description
The Options Manager routine SUMAG reads or writes REAL data for some MATH/LIBRARY and STAT/LIBRARY codes. See Atchison and Hanson (1991) for more complete details. There are MATH/LIBRARY routines in Chapters 1 and 5 that now use SUMAG to communicate optional data from the user.
Comments
1. Users can normally avoid reading about options when first using a routine that calls SUMAG.
2. Let I be any value between 1 and NUMOPT. A negative value of IOPTS(I) refers to option number ‑IOPTS(I) but with a different effect: For a “get” operation, the default values are returned in SVALS. For a “put” operation, the default values replace the current values. In the case of a “put,” entries of SVALS are not allocated by the user and are not used by SUMAG.
3. Both positive and negative values of IOPTS can be used.
4. Floating Point Options
1 This value is used for testing the installation of SUMAG by other IMSL software.
Default value is 3.0E0.
Example
The rank determination tolerance for the constrained least squares solver
LCLSQ that calls
L2LSQ is changed from the default value of
SQRT(
AMACH(4)) to the value 0.01. The default value is restored after the call to
LCLSQ. This change has no effect on the solution. It is used only for illustration. The first two arguments required for the call to
SUMAG are defined by the product name, “MATH,” and chapter number, 1, where
LCLSQ is documented. The argument
IACT denotes a write or “put” operation. There is one option to change so
NUMOPT has the value 1. The arguments for the option number, 2, and the new value, 0.01E+0, are defined by reading the documentation for
LCLSQ.
USE UMAG_INT
USE LCLSQ_INT
USE UMACH_INT
USE SNRM2_INT
IMPLICIT NONE
!
! Solve the following in the least squares sense:
! 3x1 + 2x2 + x3 = 3.3
! 4x1 + 2x2 + x3 = 2.3
! 2x1 + 2x2 + x3 = 1.3
! x1 + x2 + x3 = 1.0
!
! Subject to: x1 + x2 + x3 <= 1
! 0 <= x1 <= .5
! 0 <= x2 <= .5
! 0 <= x3 <= .5
!
! ----------------------------------------------------------------------
! Declaration of variables
!
INTEGER ICHP, IPUT, LDA, LDC, MCON, NCA, NEWTOL, NRA, NUMOPT
PARAMETER (ICHP=1, IPUT=2, MCON=1, NCA=3, NEWTOL=2, NRA=4, &
NUMOPT=1, LDA=NRA, LDC=MCON)
!
INTEGER IOPT(1), IRTYPE(MCON), NOUT
REAL A(LDA,NCA), B(NRA), BC(MCON), C(LDC,NCA), RES(NRA), &
RESNRM, SVAL(1), XLB(NCA), XSOL(NCA), XUB(NCA)
! Data initialization
!
DATA A/3.0E0, 4.0E0, 2.0E0, 1.0E0, 2.0E0, 2.0E0, 2.0E0, 1.0E0, &
1.0E0, 1.0E0, 1.0E0, 1.0E0/, B/3.3E0, 2.3E0, 1.3E0, 1.0E0/, &
C/3*1.0E0/, BC/1.0E0/, IRTYPE/1/, XLB/3*0.0E0/, XUB/3*.5E0/
! ----------------------------------------------------------------------
!
! Reset the rank determination
! tolerance used in the solver.
! The value 2 is the option number.
! The value 0.01 is the new tolerance.
!
IOPT(1) = NEWTOL
SVAL(1) = 0.01E+0
CALL UMAG ('math', ICHP, IPUT, IOPT, SVAL)
! -------------------------------------
! ---------------------------------
!
! Solve the bounded, constrained
! least squares problem.
!
CALL LCLSQ (A, B, C, BC, BC, IRTYPE, XLB, XUB, XSOL, RES=RES)
! Compute the 2-norm of the residuals.
RESNRM = SNRM2(NRA,RES,1)
! Print results
CALL UMACH (2, NOUT)
WRITE (NOUT,99999) XSOL, RES, RESNRM
! -------------------------------------
! ---------------------------------
! Reset the rank determination
! tolerance to its default value.
! This is not required but is
! recommended programming practice.
IOPT(1) = -IOPT(1)
CALL UMAG ('math', ICHP, IPUT, IOPT, SVAL)
! -------------------------------------
! ---------------------------------
!
99999 FORMAT (' The solution is ', 3F9.4, //, ' The residuals ', &
'evaluated at the solution are ', /, 18X, 4F9.4, //, &
' The norm of the residual vector is ', F8.4)
!
END
Output
The solution is 0.5000 0.3000 0.2000
The residuals evaluated at the solution are
-1.0000 0.5000 0.5000 0.0000
The norm of the residual vector is 1.2247
