# dpchcm.f

          SUBROUTINE DPCHCM (N, X, F, D, INCFD, SKIP, ISMON, IERR)
    C***BEGIN PROLOGUE  DPCHCM
    C***PURPOSE  Check a cubic Hermite function for monotonicity.
    C***LIBRARY   SLATEC (PCHIP)
    C***CATEGORY  E3
    C***TYPE      DOUBLE 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        DOUBLE PRECISION  X(N), F(INCFD,N), D(INCFD,N)
    C        LOGICAL  SKIP
    C
    C        CALL  DPCHCM (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*8 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*8 array of function values.  F(1+(I-1)*INCFD) is
    C           the value corresponding to X(I).
    C
    C     D:IN  is a real*8 array of derivative values.  D(1+(I-1)*INCFD) is
    C           is 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          DPCHCM:  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 DPCHIM and DPCHIC, includes an
    C     increment between successive values of the F- and D-arrays.
    C
    C *Cautions:
    C     This provides the same capability as old DPCHMC, 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  DCHFCM, 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  Corrected XERROR calls for d.p. name(s).
    C   890206  Corrected XERROR calls.
    C   890209  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 DPCHMC to DPCHCM, 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  DPCHCM