pchcm.f
SUBROUTINE PCHCM (N, X, F, D, INCFD, SKIP, ISMON, IERR)
C***BEGIN PROLOGUE PCHCM
C***PURPOSE Check a cubic Hermite function for monotonicity.
C***LIBRARY SLATEC (PCHIP)
C***CATEGORY E3
C***TYPE SINGLE PRECISION (PCHCM-S, DPCHCM-D)
C***KEYWORDS CUBIC HERMITE INTERPOLATION, MONOTONE INTERPOLATION,
C PCHIP, PIECEWISE CUBIC INTERPOLATION, UTILITY ROUTINE
C***AUTHOR Fritsch, F. N., (LLNL)
C Computing & Mathematics Research Division
C Lawrence Livermore National Laboratory
C P.O. Box 808 (L-316)
C Livermore, CA 94550
C FTS 532-4275, (510) 422-4275
C***DESCRIPTION
C
C *Usage:
C
C PARAMETER (INCFD = ...)
C INTEGER N, ISMON(N), IERR
C REAL X(N), F(INCFD,N), D(INCFD,N)
C LOGICAL SKIP
C
C CALL PCHCM (N, X, F, D, INCFD, SKIP, ISMON, IERR)
C
C *Arguments:
C
C N:IN is the number of data points. (Error return if N.LT.2 .)
C
C X:IN is a real array of independent variable values. The
C elements of X must be strictly increasing:
C X(I-1) .LT. X(I), I = 2(1)N.
C (Error return if not.)
C
C F:IN is a real array of function values. F(1+(I-1)*INCFD) is
C the value corresponding to X(I).
C
C D:IN is a real array of derivative values. D(1+(I-1)*INCFD) is
C the value corresponding to X(I).
C
C INCFD:IN is the increment between successive values in F and D.
C (Error return if INCFD.LT.1 .)
C
C SKIP:INOUT is a logical variable which should be set to
C .TRUE. if the user wishes to skip checks for validity of
C preceding parameters, or to .FALSE. otherwise.
C This will save time in case these checks have already
C been performed.
C SKIP will be set to .TRUE. on normal return.
C
C ISMON:OUT is an integer array indicating on which intervals the
C PCH function defined by N, X, F, D is monotonic.
C For data interval [X(I),X(I+1)],
C ISMON(I) = -3 if function is probably decreasing;
C ISMON(I) = -1 if function is strictly decreasing;
C ISMON(I) = 0 if function is constant;
C ISMON(I) = 1 if function is strictly increasing;
C ISMON(I) = 2 if function is non-monotonic;
C ISMON(I) = 3 if function is probably increasing.
C If ABS(ISMON)=3, this means that the D-values are near
C the boundary of the monotonicity region. A small
C increase produces non-monotonicity; decrease, strict
C monotonicity.
C The above applies to I=1(1)N-1. ISMON(N) indicates whether
C the entire function is monotonic on [X(1),X(N)].
C
C IERR:OUT is an error flag.
C Normal return:
C IERR = 0 (no errors).
C "Recoverable" errors:
C IERR = -1 if N.LT.2 .
C IERR = -2 if INCFD.LT.1 .
C IERR = -3 if the X-array is not strictly increasing.
C (The ISMON-array has not been changed in any of these cases.)
C NOTE: The above errors are checked in the order listed,
C and following arguments have **NOT** been validated.
C
C *Description:
C
C PCHCM: Piecewise Cubic Hermite -- Check Monotonicity.
C
C Checks the piecewise cubic Hermite function defined by N,X,F,D
C for monotonicity.
C
C To provide compatibility with PCHIM and PCHIC, includes an
C increment between successive values of the F- and D-arrays.
C
C *Cautions:
C This provides the same capability as old PCHMC, except that a
C new output value, -3, was added February 1989. (Formerly, -3
C and +3 were lumped together in the single value 3.) Codes that
C flag nonmonotonicity by "IF (ISMON.EQ.2)" need not be changed.
C Codes that check via "IF (ISMON.GE.3)" should change the test to
C "IF (IABS(ISMON).GE.3)". Codes that declare monotonicity via
C "IF (ISMON.LE.1)" should change to "IF (IABS(ISMON).LE.1)".
C
C***REFERENCES F. N. Fritsch and R. E. Carlson, Monotone piecewise
C cubic interpolation, SIAM Journal on Numerical Ana-
C lysis 17, 2 (April 1980), pp. 238-246.
C***ROUTINES CALLED CHFCM, XERMSG
C***REVISION HISTORY (YYMMDD)
C 820518 DATE WRITTEN
C 820804 Converted to SLATEC library version.
C 831201 Reversed order of subscripts of F and D, so that the
C routine will work properly when INCFD.GT.1 . (Bug!!)
C 870707 Minor cosmetic changes to prologue.
C 890208 Added possible ISMON value of -3 and modified code so
C that 1,3,-1 produces ISMON(N)=2, rather than 3.
C 890306 Added caution about changed output.
C 890407 Changed name from PCHMC to PCHCM, as requested at the
C March 1989 SLATEC CML meeting, and made a few other
C minor modifications necessitated by this change.
C 890407 Converted to new SLATEC format.
C 890407 Modified DESCRIPTION to LDOC format.
C 900315 CALLs to XERROR changed to CALLs to XERMSG. (THJ)
C 920429 Revised format and order of references. (WRB,FNF)
C***END PROLOGUE PCHCM