      SUBROUTINE XXXXXX( OPTION, MODE, NF, FC, NX, X, NDX, XC, XINC,
CIO                      I       I     I   I   I   I  I    I   I
     +                   NDX1, XC1, XINC1, NDX2, XC2, XINC2,
CIO                      I     I    I      I     I    I
     +                   IVAL, CVAL, F, DF, D2F, ISTAT )
CIO                      O     O     IO IO  O    O
C
      INTEGER            NF, FC, NX, NDX, XC(NDX), NDX1, XC1(NDX1),
     +                   NDX2, XC2(NDX2), IVAL, ISTAT
      CHARACTER*(*)      OPTION, MODE, CVAL
      DOUBLE PRECISION   X(NX), XINC(NDX), XINC1(NDX1), XINC2(NDX2),
     +                   F, DF(NDX), D2F(NDX1,NDX2)
C-----------------------------------------------------------------------
C  PART OF:  PROBAN
C
C  This is a template - to be used for functions called by PROBAN.
C  This template is to be used with onedimensional functions that
C  provide both first and second order derivatives.
C
C  PURPOSE:  <Enter a short description of the routine here>
C
C
C  RESTRICTIONS:
C
C  INPUT:
C    OPTION  Determines what must be passed back to the calling routine:
C            = 'FUNCVAL'    : Return F = value of the function
C            = 'DFUNC'      : Return DF(1..NDX) = gradients of the
C                             function wrt. the arguments specified in
C                             XC(1..NDX).  F is input in this case.
C            = 'D2FUNC'     : Return D2F(1..NDX1,1..NDX2) = second
C                             order derivative of the function wrt. the
C                             arguments specified in XC1(1..NDX1) and
C                             XC2(1..NDX2).  F and DF(1..NDX) are
C                             input in this case.
C            = 'FUNCNAME'   : Return CVAL = Name of the function
C            = 'FUNCDESC'   : Return CVAL = Description of the function
C            = 'FUNCNCOORD' : Return IVAL = Dimension of the function.
C                             This MUST be 1 in this case.
C            = 'FUNCNARG'   : Return IVAL = Number of arguments in the
C                             function. Return IVAL = 0 if this number
C                             is given as input by the user
C            = 'ARGNAME'    : Return CVAL = Name of the argument in the
C                             function specified by XC(1).
C            = 'ARGDESC'    : Return CVAL = Description of the argument
C                             in the function specified by XC(1).
C            = 'FUNCTYPE'   : Return CVAL = Type of the function
C                             'INDEX'      If it jumps from -1 to 1 at a
C                                          single value
C                             'INDICATOR'  If it jumps from 0 to 1 at a
C                                          single value
C                             'NON-CONT'   If it is not continuous (and
C                                          not one of the above)
C                             'CONT'       If it is continuous but not
C                                          differentiable everywhere
C                             'DIFF-1'     If it is differentiable
C                                          everywhere, but not twice
C                                          differentiable everywhere
C                             else:        The function is assumed to
C                                          be twice differentiable
C                                          everywhere.
C            = 'FUNCGRAD'   : Return IVAL = gradient calculation
C                             capability of the function
C                             = 0: The function cannot return gradients
C                             = 1: The function can return first order
C                                  gradients
C                             = 2: The function can return first and
C                                  second order gradients
C            = 'NOPT'       : Return IVAL = number of sets of options
C            = 'OPTNAME'    : Return CVAL = name of option set no. XC(1)
C            = 'OPTINF'       : Return IVAL = option type returned in XC(1)
C                             >0 : Number of options in menu of options
C                             -1 : Text option
C                             -2 : Double precision option
C                             -3 : Integer option
C                             -4 : File name
C            = 'OPTMENU'    : Return CVAL = Option no. XC(2) in option
C                             set XC(1)
C            = 'OPTDEF'     : Return option defaults.
C                             If menu, return index of default option
C                             in IVAL.
C                             If text option, return default value
C                             in CVAL.
C                             If double precision option, return of default
C                             value in F(1).
C                             If integer option, return default value
C                             in IVAL.
C                             If file name, return default file name
C                             in CVAL.
C    MODE    Mode of calculation. Only used when function calculation
C            is required:
C            = 'FIRST CALL' : This is the first entry during an analysis
C                             into the function for a given variable.
C                             The variable name is passed in CVAL.
C            = 'DESIGN POINT' : Function is called with design point
C                               value as input (FORM/SORM only)
C    NF      Not used.
C    FC      Not used.
C    NX      Number of arguments in function
C    X       Function arguments if calculation is required
C    NDX     Number of arguments active for first order differentiation
C            if this is required
C    XC      Indices of arguments active for first order differentiation
C            if this is required. XC(1) is also used to identify an
C            argument to get name and description.
C    XINC    Suggested increment values for numerical first order
C            differentiation.
C    NDX1    Number of first arguments in second order differentation
C            if this is required
C    XC1     Indices of arguments active for second order differentiation
C            if this is required.
C    XINC1   Suggested increment values for numerical second order
C            differentiation.
C    NDX2    Number of second arguments in second order differentation
C            if this is required
C    XC2     Indices of arguments active for second order differentiation
C            if this is required.
C    XINC2   Suggested increment values for numerical second order
C            differentiation.
C    F       Function value if differentiation is required
C    DF      Gradients wrt. the arguments in XC if second order
C            differentiation is required
C
C  OUTPUT:
C    IVAL    Varies, depending on OPTION
C    CVAL    Varies, depending on OPTION
C            CVAL may also be used to pass a one line error message
C            back to PROBAN. If any ISTAT value is not = 0, the
C            contents of CVAL will be presented as an error message if
C            CVAL is not empty (CVAL will always be empty on input).
C    F       Function value             (See OPTION = 'FUNCVAL' above)
C    DF      Gradient(s)                (See OPTION = 'DFUNC' above)
C    D2F     Second order derivative(s) (See OPTION = 'D2FUNC' above)
C    ISTAT   Return status:
C            = 0 : OK.
C            = 1 : Numerical or other error, cancel further calculations
C            =-1 : Numerical error, X yields F < 0
C            =-2 : Numerical error, X yields F = 0
C            =-3 : Numerical error, X yields F > 0
C
C  CODED BY:
C    Robert Olesen, VSS, November 1991
C
C  REVISIONS:
C
C  COPYRIGHT (C) 1991, VERITAS SESAM SYSTEMS
C
C-----------------------------------------------------------------------
C
      INTEGER  I, J, IX, JX, IX1, IX2
C
      INTEGER           OPTNUM,OPTINF,OPTINT,INFO
      DOUBLE PRECISION  OPTDBL
      CHARACTER*80      OPTTXT
C
C-----------------------------------------------------------------------
C  METHOD:  
C
C  INTERNAL VARIABLES:
C
C  COMMON VARIABLES:
C  Var:   IO  Type Common/File  Description
C
C-----------------------------------------------------------------------
C
C---- Initialize status value
C
      ISTAT = 0
C
C-------------------------- Function value ------------------------------
C
      IF( OPTION.EQ.'FUNCVAL') THEN
C
C----   Return function value
C
C NB:   Check the function arguments. In case of error, leave an error
C NB:   message in CVAL, change ISTAT (see OUTPUT: above) and return.
C
        F = <value of function>
C
C NB:   In case of error, leave an error message in CVAL and change the
C NB:   value of ISTAT (see OUTPUT: above)
C
C----------------------- First order derivative -------------------------
C
      ELSE IF( OPTION.EQ.'DFUNC') THEN
C
C----   Return first order derivatives.
C       Note that the function value F is input in this case.
C
C NB:   Check the function arguments. In case of error, leave an error
C NB:   message in CVAL, change the value of ISTAT and return.
C
C----   Loop over the arguments on which differentiation is requested
C
        DO 1200 I=1,NDX
C
C----     Extract the argument on which derivation is requested
C
          IX = XC(I)
C
C----     Calculate the derivative of F wrt. X(IX)
C
          IF (IX.EQ.1) THEN
            DF(I) = <derivative of function wrt. argument number 1>
          ELSE IF (IX.EQ.2) THEN
            DF(I) = <derivative of function wrt. argument number 2>
          etc...
          END IF
C NB:     In case of error, leave an error message in CVAL, change the
C NB:     value of ISTAT (see OUTPUT: above) and return.
C
 1200   CONTINUE
C
C---------------------- Second order derivative -------------------------
C
      ELSE IF( OPTION.EQ.'D2FUNC') THEN
C
C----   Return second order derivatives
C       Note that the function value F is input in this case.
C       Note that the function derivative(s) of F wrt. the argument(s)
C       specified in XC(1:NDX) are input in this case as DF(1:NDX)
C
C NB:   Check the function arguments. In case of error, leave an error
C NB:   message in CVAL, change the value of ISTAT and return.
C
C----   Loop over both sets of arguments
C
        DO 1600 I=1,NDX1
C
C----     Extract the first argument on which derivation is requested
C
          IX = XC1(I)
C
          DO 1500 J=1,NDX2
C
C----       Extract the second argument on which derivation is requested
C
            JX = XC2(J)
C
C----       Calculate the derivative of F wrt. X(IX) and X(JX)
C
            D2F(I,J) = <second order derivative of function
                        wrt. argument IX and JX>
C NB:       In case of error, leave an error message in CVAL, change
C NB:       the value of ISTAT (see OUTPUT: above) and return.
C
 1500     CONTINUE
C
 1600   CONTINUE
C
C----------------------- Function properties ---------------------------
C
      ELSE IF (OPTION.EQ.'FUNCNAME') THEN
C
C----   Return name of function
C       The name must contain alphanumeric characters or hyphens ('-')
C       and can be at most 12 characters long.
C       eg: 'X22yyy' or: 'Func-Name'
C
        CVAL = <enter name of function here>
C
      ELSE IF (OPTION.EQ.'FUNCDESC') THEN
C
C----   Return description of function
C       The description should not be longer than 50 characters    
C
        CVAL = <enter description of function here>
C
      ELSE IF( OPTION.EQ.'FUNCTYPE' )THEN
C
C----   Return the type of a function
C       'INDEX'        If it jumps from -1 to 1 at a single value
C       'INDICATOR'    If it jumps from 0 to 1 at a single value
C       'NON-CONT'     If it is not continuous (and not one of the above)
C       'CONT'         If it is continuous but not differentiable
C                      everywhere
C       'DIFF-1'       If it is differentiable everywhere, but not twice
C                      differentiable everywhere
C       anything else: The function is assumed to be twice differentiable
C                      everywhere.
C
        CVAL = 'DUMMY'
C
      ELSE IF( OPTION.EQ.'FUNCGRAD') THEN
C
C----   Return gradient calculation status:
C         0: No gradients are provided
C         1: First order gradients are provided
C         2: First and second order gradients are provided
C
          IVAL = 2
C
      ELSE IF (OPTION.EQ.'FUNCNCOORD') THEN
C
C----   Return number of coordinates in the function. This MUST be
C       set to 1 because this template only applies to onedimensiona;
C       functions.
C
        IVAL = 1
C
      ELSE IF (OPTION.EQ.'FUNCNARG') THEN
C
C----   Return number of arguments in function
C       Set this number to 0 if it is to be input by the user
C
        IVAL = <enter number of arguments here>
C
      ELSE IF (OPTION.EQ.'ARGNAME') THEN
C
C----   Return name of argument XC(1) in function.
C
        IX = XC(1)
C
C----   Branch on the arguments and return the proper name
C----   The name must obey the same restrictions as the function name
C
        IF (IX.EQ.1) THEN
          CVAL = <enter name of argument 1 here>
        ELSE IF (IX.EQ.2) THEN
          CVAL = <enter name of argument 2 here>
        etc...
        END IF
C
      ELSE IF (OPTION.EQ.'ARGDESC') THEN
C
C----   Return description of argument XC(1) in function.
C
        IX = XC(1)
C
C----   Branch on the arguments and return the proper description
C----   The description should not use more than 50 characters
C
        IF (IX.EQ.1) THEN
          CVAL = <enter description of argument 1 here>
        ELSE IF (IX.EQ.2) THEN
          CVAL = <enter description of argument 2 here>
        etc...
        END IF
C
C------------------------ Function Options -----------------------------
C
C---- Function options are used to pass non-random information to
C     functions (through the ASSIGN FUNCTION-OPTION command).
C     The information can be an integer value, a numerical value,
C     a text value, a selection in a menu of alternatives or a file name
C     Function options are numbered consequtively from 1 and upwards
C     when referenced inside this routine, but have names when
C     referred by the user through the ASSIGN FUNCTION-OPTION command.
C
C---- To access function options in this routine, GTFUOP must be called.
C     The syntax is:
C
C     CALL GTFUOP( OPTNUM, OPTINF, OPTINT, OPTDBL, OPTTXT, INFO )
C     INPUT:   OPTNUM  INT Index of the option that is accessed
C     OUTPUT:  OPTINF  INT Type of value returned:
C                             = 1: Menu index             (in OPTINT)
C                             =-1: Text value             (in OPTTXT)
C                             =-2: Double precision value (in OPTDBL)
C                             =-3: Integer value          (in OPTINT)
C                             =-4: File name              (in OPTTXT)
C              INFO    INT  Return status:
C                             = 0 : OK
C                             = 1 : OPTNUM out of range
C
      ELSE IF( OPTION.EQ.'NOPT') THEN
C
C----   Return number of options available for this function.
C       Keep the 0 value if no options are used. In this case no
C       changes will be needed below this point.
C
        IVAL = 0
C
      ELSE IF( OPTION.EQ.'OPTNAME') THEN
C
C----   Return name of option number XC(1)
C
        IX = XC(1)
C
C       The name must contain alphanumeric characters or hyphens ('-')
C       and can be at most 25 characters long (However, in some cases
C       only the first 12 characters are printed).
C       The user will identify/select the option through this name.
C
        IF (IX.EQ.1) THEN
C NB:     Return the name of option 1 in   CVAL
        ELSE IF (IX.EQ.2) THEN
C NB:     Return the name of option 2 in   CVAL
C NB:   etc.
        END IF
C
      ELSE IF( OPTION.EQ.'OPTINF') THEN
C
C----   Return information about the type of option number XC(1)
C
        IX = XC(1)
C
C       Return the information in IVAL:
C          >0: The option is a menu with the number of choices given here
C          -1: The option is a text
C          -2: The option is a double precision value
C          -3: The option is an integer
C          -4: The option is a file name
C
        IF (IX.EQ.1) THEN
C NB:     Return the information about option 1 in   IVAL
        ELSE IF (IX.EQ.2) THEN
C NB:     Return the information about option 2 in   IVAL
C NB:   etc.
        END IF
C
      ELSE IF( OPTION.EQ.'OPTMENU') THEN
C
C----   Return information about the contents of all menus
C       Return the name of alternative number XC(2) in option XC(1)
C       The name must contain alphanumeric characters or hyphens ('-')
C
        IX1 = XC(1)
        IX2 = XC(2)
C
C NB:   Return the name of alternative IX2 in menu IX1 in    CVAL
C
      ELSE IF( OPTION.EQ.'OPTDEF') THEN
C
C----   Return default value for option number XC(1)
C
        IX1 = XC(1)
C
C NB:      Return default file name in              CVAL
C NB:   or Return default text value in             CVAL
C NB:   or Return default integer value in          IVAL
C NB:   or Return default menu choice in            IVAL
C NB:   or Return default double precision value in F(1)
C
      END IF
C
      RETURN
C  End of XXXXXX
      END
