From 2eab30c403b01018e94824ee7d7a2aa47ce2621a Mon Sep 17 00:00:00 2001
From: zaikunzhang <zaikunzhang@gmail.com>
Date: Tue, 9 Apr 2024 12:16:51 +0800
Subject: [PATCH] 240409.121651.HKT update the comments about `problem.f0` and
 `problem.nlconstr0`

---
 c/examples/cobyla/cobyla_example.c |  2 ++
 c/include/prima/prima.h            | 13 +++++++++----
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/c/examples/cobyla/cobyla_example.c b/c/examples/cobyla/cobyla_example.c
index 0e4652d188..b6d08e35e5 100644
--- a/c/examples/cobyla/cobyla_example.c
+++ b/c/examples/cobyla/cobyla_example.c
@@ -48,6 +48,8 @@ int main(int argc, char * argv[])
     problem.calcfc = &fun;
     // Provide the initial values of the objective function and the nonlinear constraints.
     // This is OPTIONAL, and end users should NOT do it in general. Here, we do it for testing.
+    // problme.f0 and problem.nlconstr0 are used when interfacing with Python and Julia etc.
+    // They are not designed for C users.See the documentation of `prima_problem_t` for details.
 #if PROVIDE_INITIAL_F_AND_NLCONSTR
     double nlconstr0[M_NLCON] = {0};
     fun(x0, &(problem.f0), nlconstr0, NULL);
diff --git a/c/include/prima/prima.h b/c/include/prima/prima.h
index 6a041816d8..d8dac7fd26 100644
--- a/c/include/prima/prima.h
+++ b/c/include/prima/prima.h
@@ -165,15 +165,20 @@ typedef struct {
     double *Aeq;
     double *beq;
 
-    // m_nlcon: number of nonlinear constraints
+    // m_nlcon: number of nonlinear constraints defined by calcfc
     // Should be 0 for UOBYQA, NEWUOA, BOBYQA, and LINCOA
     // Default: 0
     int m_nlcon;
 
     // f0, nlconstr0: initial objective function value and constraint values (COBYLA only)
-    // Should ONLY be used when interfacing with MATLAB/Python/Julia/R, where we need to evaluate
-    // the constraints at the initial point to get m_nlcon
-    // C end users should leave them as the default, i.e., f0 = NAN and nlconstr0 = NULL.
+    // It should ONLY be used when interfacing with high-level languages such as MATLAB/Python/
+    // Julia/R. In these languages, instead of asking the user to provide m_nlcon, we should
+    // evaluate the constraints at the initial point to get m_nlcon; we evaluate the objective
+    // function at the initial point as well to keep the objective and constraint evaluations
+    // synchronized; after this, we pass the initial object and constraint values to the solver
+    // via f0 and nlconstr0 to avoid re-evaluating them, as the evaluations are expensive.
+    // C end users should leave f0 and nlconstr0 as the default set by prima_init_problem and
+    // set m_nlcon to the number of nonlinear constraints.
     // Default: f0 = NAN and nlconstr0 = NULL
     double f0;
     double *nlconstr0;