update to cohprods docs and change nnzohp/ind to inout

man/man3/cutest_cohprods.3

@@ -13,7 +13,7 @@ For real rather than double precision arguments, instead
 .HP 1i
 CALL CUTEST_cohprods_s( ... )
 .SH DESCRIPTION
-The CUTEST_cohprods subroutine forms the product of a vector with 
+The CUTEST_cohprods subroutine forms the product of a vector with
 the Hessian matrix of the objective function
 .EQ
 f(x)
@@ -83,7 +83,7 @@ the number of variables for the problem,
 a logical variable which specifies whether the second derivatives of
 the groups and elements, and the indexing information held in IND
 (see below) have already been set (goth = .TRUE.) or if
-this information should be computed (goth = .FALSE.),
+this information should be computed (goth = .FALSE.).
 .TP
 .B X \fP[in] - real/double precision
 when goth = .FALSE., the Hessians will be evaluated at X. Otherwise
@@ -95,7 +95,9 @@ required,
 .TP
 .B nnzohp \fP[out] - integer
 the total number of nonzero entries required to store the product of the
-objective Hessian with a vector.
+objective Hessian with a vector. This should be the value obtained
+from the last call to the subroutine if goth = .TRUE., but need not be
+set otherwise.
 .TP
 .B lohp \fP[in] - integer
 a variable that specifies the declared lengths of IND and RESULT.
@@ -111,6 +113,8 @@ stored in RESULT(1:nnzohp).
 an array that gives the indices of the nonzeros in the result obtained by
 multiplying the objective Hessian by VECTOR. The indices
 are stored in IND(1:nnzohp), and will match the values stored in RESULT.
+This array should be passed unchanged from the last call to the subroutine
+if goth = .TRUE., but need not be set otherwise.
 .LP
 .SH NOTE
 goth should be set to .TRUE. only when

man/man3/cutest_cohprods_threaded.3

@@ -5,7 +5,7 @@ CUTEST_cohprods_threaded \- CUTEst tool to form the matrix-vector product
 of a vector with the Hessian matrix of the objective function.
 .SH SYNOPSIS
 .HP 1i
-CALL CUTEST_cohprods_threaded( status, goth, X, VECTOR, 
+CALL CUTEST_cohprods_threaded( status, goth, X, VECTOR,
 nnzohp, lohp, RESULT, IND, thread )
 
 .HP 1i
@@ -96,7 +96,9 @@ required,
 .TP
 .B nnzohp \fP[out] - integer
 the total number of nonzero entries required to store the product of the
-objective Hessian with a vector.
+objective Hessian with a vector. This should be the value obtained
+from the last call to the subroutine if goth = .TRUE., but need not be
+set otherwise.
 .TP
 .B lohp \fP[in] - integer
 a variable that specifies the declared lengths of IND and RESULT.
@@ -112,6 +114,8 @@ stored in RESULT(1:nnzohp).
 an array that gives the indices of the nonzeros in the result obtained by
 multiplying the objective Hessian by VECTOR. The indices
 are stored in IND(1:nnzohp), and will match the values stored in RESULT.
+This array should be passed unchanged from the last call to the subroutine
+if goth = .TRUE., but need not be set otherwise.
 .TP
 .B thread \fP[out] - integer
 thread chosen for the evaluation; threads are numbered

man/man3/makedocs

@@ -136,7 +136,9 @@
 
 #foreach pack ( cutest_cdhj cutest_cdhj_threaded )
 
-foreach pack ( cutest_chjprod cutest_chjprod_threaded )
+#foreach pack ( cutest_chjprod cutest_chjprod_threaded )
+
+foreach pack ( cutest_cohprods cutest_cohprods_threaded )
 
 #foreach pack ( cutest_cdimohp cutest_cdimsg \
 #               cutest_chjprod cutest_chjprod_threaded \

src/tools/cohprods.F90

@@ -20,18 +20,20 @@ SUBROUTINE CUTEST_Cint_cohprods_r( status, n, goth, X, VECTOR,           &
 !  dummy arguments
 
       INTEGER ( KIND = ip_ ), INTENT( IN ) :: n, lohp
-      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status, nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( INOUT ) :: nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status
       LOGICAL ( KIND = C_Bool ), INTENT( IN ) :: goth
       REAL ( KIND = rp_ ), INTENT( IN ), DIMENSION( n ) :: X, VECTOR
-      INTEGER ( KIND = ip_ ), INTENT( OUT ), DIMENSION( lohp ) :: IND
+      INTEGER ( KIND = ip_ ), INTENT( INOUT ), DIMENSION( lohp ) :: IND
       REAL ( KIND = rp_ ), INTENT( OUT ), DIMENSION( lohp ) :: RESULT
 
 !  ---------------------------------------------------------------------------
-!  compute the matrix-vector product H(x) between the Hessian matrices H(x) 
-!  of the objective function for the problem and a given vector v stored in 
+!  compute the matrix-vector product H(x) between the Hessian matrices H(x)
+!  of the objective function for the problem and a given vector v stored in
 !  VECTOR. The nonzero entries of the resulting products H(x) v and their
-!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE. 
-!  the second derivatives are assumed to have already been computed.
+!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE.
+!  the second derivatives are assumed to have already been computed, and
+!  that nnzohp and IND have been set by a previous call at X.
 !  If the user is unsure, set goth = .FALSE. the first time a product is
 !  required with the Hessians evaluated at X. X is not used if goth = .TRUE.
 !  ---------------------------------------------------------------------------
@@ -63,18 +65,20 @@ SUBROUTINE CUTEST_cohprods_r( status, n, goth, X, VECTOR,                &
 !  dummy arguments
 
       INTEGER ( KIND = ip_ ), INTENT( IN ) :: n, lohp
-      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status, nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( INOUT ) :: nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status
       LOGICAL, INTENT( IN ) :: goth
       REAL ( KIND = rp_ ), INTENT( IN ), DIMENSION( n ) :: X, VECTOR
       INTEGER ( KIND = ip_ ), INTENT( OUT ), DIMENSION( lohp ) :: IND
       REAL ( KIND = rp_ ), INTENT( OUT ), DIMENSION( lohp ) :: RESULT
 
 !  ---------------------------------------------------------------------------
-!  compute the matrix-vector product H(x) between the Hessian matrices H(x) 
-!  of the objective function for the problem and a given vector v stored in 
+!  compute the matrix-vector product H(x) between the Hessian matrices H(x)
+!  of the objective function for the problem and a given vector v stored in
 !  VECTOR. The nonzero entries of the resulting products H(x) v and their
-!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE. 
-!  the second derivatives are assumed to have already been computed.
+!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE.
+!  the second derivatives are assumed to have already been computed, and
+!  that nnzohp and IND have been set by a previous call at X.
 !  If the user is unsure, set goth = .FALSE. the first time a product is
 !  required with the Hessians evaluated at X. X is not used if goth = .TRUE.
 !  ---------------------------------------------------------------------------
@@ -97,26 +101,28 @@ END SUBROUTINE CUTEST_cohprods_r
 !  History -
 !   moden fortran version released in CUTEst, 29th October 2023
 
-      SUBROUTINE CUTEST_cohprods_threaded_r( status, n, goth, X, VECTOR,      &
+      SUBROUTINE CUTEST_cohprods_threaded_r( status, n, goth, X, VECTOR,       &
                                              nnzohp, lohp, RESULT, IND, thread )
       USE CUTEST_KINDS_precision
       USE CUTEST_precision
 
 !  dummy arguments
 
       INTEGER ( KIND = ip_ ), INTENT( IN ) :: n, lohp, thread
-      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status, nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( INOUT ) :: nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status
       LOGICAL, INTENT( IN ) :: goth
       REAL ( KIND = rp_ ), INTENT( IN ), DIMENSION( n ) :: X, VECTOR
       INTEGER ( KIND = ip_ ), INTENT( OUT ), DIMENSION( lohp ) :: IND
       REAL ( KIND = rp_ ), INTENT( OUT ), DIMENSION( lohp ) :: RESULT
 
 !  ---------------------------------------------------------------------------
-!  compute the matrix-vector product H(x) between the Hessian matrices H(x) 
-!  of the objective function for the problem and a given vector v stored in 
+!  compute the matrix-vector product H(x) between the Hessian matrices H(x)
+!  of the objective function for the problem and a given vector v stored in
 !  VECTOR. The nonzero entries of the resulting products H(x) v and their
-!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE. 
-!  the second derivatives are assumed to have already been computed.
+!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE.
+!  the second derivatives are assumed to have already been computed, and
+!  that nnzohp and IND have been set by a previous call at X.
 !  If the user is unsure, set goth = .FALSE. the first time a product is
 !  required with the Hessians evaluated at X. X is not used if goth = .TRUE.
 !  ---------------------------------------------------------------------------
@@ -161,18 +167,20 @@ SUBROUTINE CUTEST_cohprods_threadsafe_r( data, work, status, n, goth,    &
       TYPE ( CUTEST_data_type ), INTENT( IN ) :: data
       TYPE ( CUTEST_work_type ), INTENT( INOUT ) :: work
       INTEGER ( KIND = ip_ ), INTENT( IN ) :: n, lohp
-      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status, nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( INOUT ) :: nnzohp
+      INTEGER ( KIND = ip_ ), INTENT( OUT ) :: status
       LOGICAL, INTENT( IN ) :: goth
       REAL ( KIND = rp_ ), INTENT( IN ), DIMENSION( n ) :: X, VECTOR
       INTEGER ( KIND = ip_ ), INTENT( OUT ), DIMENSION( lohp ) :: IND
       REAL ( KIND = rp_ ), INTENT( OUT ), DIMENSION( lohp ) :: RESULT
 
 !  ---------------------------------------------------------------------------
-!  compute the matrix-vector product H(x) between the Hessian matrices H(x) 
-!  of the objective function for the problem and a given vector v stored in 
+!  compute the matrix-vector product H(x) between the Hessian matrices H(x)
+!  of the objective function for the problem and a given vector v stored in
 !  VECTOR. The nonzero entries of the resulting products H(x) v and their
-!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE. 
-!  the second derivatives are assumed to have already been computed.
+!  indices occur in RESULT(k),IND(k), k = 1,...,nnzohp. If goth is .TRUE.
+!  the second derivatives are assumed to have already been computed, and
+!  that nnzohp and IND have been set by a previous call at X.
 !  If the user is unsure, set goth = .FALSE. the first time a product is
 !  required with the Hessians evaluated at X. X is not used if goth = .TRUE.
 !  ---------------------------------------------------------------------------
@@ -462,7 +470,7 @@ SUBROUTINE CUTEST_cohprods_threadsafe_r( data, work, status, n, goth,    &
 
 !  copy the nonzeros back to the sparse array, and reset W_ws to zero
 
-      RESULT( 1 : nnzohp ) = work%W_ws( IND( 1 : nnzohp ) ) 
+      RESULT( 1 : nnzohp ) = work%W_ws( IND( 1 : nnzohp ) )
       work%W_ws( IND( 1 : nnzohp ) ) = 0.0_rp_
 
 !  update the counters for the report tool
@@ -494,5 +502,3 @@ SUBROUTINE CUTEST_cohprods_threadsafe_r( data, work, status, n, goth,    &
 !  end of subroutine CUTEST_cohprods_threadsafe_r
 
       END SUBROUTINE CUTEST_cohprods_threadsafe_r
-
-