PCHCM(3)

SYNOPSIS
SUBROUTINE PCHCM (N, X, F, D, INCFD, SKIP, ISMON, IERR)

NAME
pchcm - Check a cubic Hermite function for monotonicity.

LIBRARY
SLATEC (PCHIP)

CATEGORY
E3

TYPE
SINGLE PRECISION (PCHCM-S, DPCHCM-D)

KEYWORDS
CUBIC HERMITE INTERPOLATION, MONOTONE INTERPOLATION, PCHIP, PIECEWISE CUBIC INTERPOLATION, UTILITY ROUTINE

AUTHOR
Fritsch, F. N., (LLNL) Computing & Mathematics Research Division Lawrence Livermore National Laboratory P.O. Box 808 (L-316) Livermore, CA 94550 FTS 532-4275, (510) 422-4275

DESCRIPTION
*Usage: PARAMETER (INCFD = ...) INTEGER N, ISMON(N), IERR REAL X(N), F(INCFD,N), D(INCFD,N) LOGICAL SKIP CALL PCHCM (N, X, F, D, INCFD, SKIP, ISMON, IERR) *Arguments: N:IN is the number of data points. (Error return if N.LT.2 .) X:IN is a real array of independent variable values. The elements of X must be strictly increasing: X(I-1) .LT. X(I), I = 2(1)N. (Error return if not.) F:IN is a real array of function values. F(1+(I-1)*INCFD) is the value corresponding to X(I). D:IN is a real array of derivative values. D(1+(I-1)*INCFD) is the value corresponding to X(I). INCFD:IN is the increment between successive values in F and D. (Error return if INCFD.LT.1 .) SKIP:INOUT is a logical variable which should be set to preceding parameters, or to .FALSE. otherwise. This will save time in case these checks have already been performed. SKIP will be set to .TRUE. on normal return. ISMON:OUT is an integer array indicating on which intervals the PCH function defined by N, X, F, D is monotonic. For data interval [X(I),X(I+1)], ISMON(I) = -3 if function is probably decreasing; ISMON(I) = -1 if function is strictly decreasing; ISMON(I) = 0 if function is constant; ISMON(I) = 1 if function is strictly increasing; ISMON(I) = 2 if function is non-monotonic; ISMON(I) = 3 if function is probably increasing. If ABS(ISMON)=3, this means that the D-values are near the boundary of the monotonicity region. A small increase produces non-monotonicity; decrease, strict monotonicity. The above applies to I=1(1)N-1. ISMON(N) indicates whether the entire function is monotonic on [X(1),X(N)]. IERR:OUT is an error flag. Normal return: IERR = 0 (no errors). "Recoverable" errors: IERR = -1 if N.LT.2 . IERR = -2 if INCFD.LT.1 . IERR = -3 if the X-array is not strictly increasing. (The ISMON-array has not been changed in any of these cases.) NOTE: The above errors are checked in the order listed, and following arguments have **NOT** been validated. *Description: PCHCM: Piecewise Cubic Hermite -- Check Monotonicity. Checks the piecewise cubic Hermite function defined by N,X,F,D for monotonicity. To provide compatibility with PCHIM and PCHIC, includes an increment between successive values of the F- and D-arrays. *Cautions: This provides the same capability as old PCHMC, except that a new output value, -3, was added February 1989. (Formerly, -3 and +3 were lumped together in the single value 3.) Codes that flag nonmonotonicity by "IF (ISMON.EQ.2)" need not be changed. Codes that check via "IF (ISMON.GE.3)" should change the test to "IF (IABS(ISMON).GE.3)". Codes that declare monotonicity via "IF (ISMON.LE.1)" should change to "IF (IABS(ISMON).LE.1)".

REFERENCES
F. N. Fritsch and R. E. Carlson, Monotone piecewise cubic interpolation, SIAM Journal on Numerical Ana- lysis 17, 2 (April 1980), pp. 238-246.

ROUTINES CALLED
CHFCM, XERMSG

REVISION HISTORY (YYMMDD)
820518 DATE WRITTEN
820804 Converted to SLATEC library version.
831201 Reversed order of subscripts of F and D, so that the routine will work properly when INCFD.GT.1 . (Bug!!)
870707 Minor cosmetic changes to prologue.
890208 Added possible ISMON value of -3 and modified code so that 1,3,-1 produces ISMON(N)=2, rather than 3.
890306 Added caution about changed output.
890407 Changed name from PCHMC to PCHCM, as requested at the March 1989 SLATEC CML meeting, and made a few other minor modifications necessitated by this change.
890407 Converted to new SLATEC format.
890407 Modified DESCRIPTION to LDOC format.
900315 CALLs to XERROR changed to CALLs to XERMSG. (THJ)
920429 Revised format and order of references. (WRB,FNF)