updated user manual

LLNL · Feb 5, 2024 · 61ffca5 · 61ffca5
1 parent f4d0d46
commit 61ffca5
Show file tree

Hide file tree

Showing 6 changed files with 17 additions and 21 deletions.
diff --git a/doc/hiop_usermanual.pdf b/doc/hiop_usermanual.pdf
diff --git a/doc/src/hiop.bib b/doc/src/hiop.bib
@@ -12,7 +12,7 @@ @Article{ipopt_impl
 }
 
 @article{petra2019memory,
-  title={A memory-distributed quasi-Newton solver for nonlinear programming problems with a small number of general constraints},
+  title={A memory-distributed quasi-{N}ewton solver for nonlinear programming problems with a small number of general constraints},
   author={Petra, Cosmin G},
   journal={Journal of Parallel and Distributed Computing},
   volume={133},
@@ -21,14 +21,3 @@ @article{petra2019memory
   publisher={Elsevier}
 }
 
-@TECHREPORT{petra_hiop,
-  author = {Cosmin G. Petra},
-  title = {A memory-distributed quasi-{N}ewton solver for
-nonlinear programming problems with a small number
-of general constraints},
-  year = {2017},
-  number = {LLNL-JRNL-739001},
-  month = {October},
-  institution = {Lawrence Livermore National Laboratory}
-}
-
diff --git a/doc/src/petra.bib b/doc/src/petra.bib
@@ -3213,7 +3213,7 @@ @article{ByrdKhalfanSchnabel_96_SR1
 
 @Article{ByrdNocedalSchnabel_94_quasiNewtonRepres,
 author="Byrd, Richard H. and Nocedal, Jorge and Schnabel, Robert B.",
-title="Representations of quasi-Newton matrices and their use in limited memory methods",
+title="Representations of quasi-{N}ewton matrices and their use in limited memory methods",
 journal="Mathematical Programming",
 year="1994",
 volume="63",

diff --git a/doc/src/sections/solver_options.tex b/doc/src/sections/solver_options.tex
@@ -131,7 +131,13 @@ \subsubsection{Line search and step computation}
 \noindent \textbf{tau\_min}: fraction-to-the-boundary parameter used in the line-search to back-off from the boundary (eqn. (8) in~\cite{waecther_05_ipopt0}). Double values in $[0.9, 0.99999]$. Default value: $0.99$. 
 \medskip
 
-\noindent \textbf{accept\_every\_trial\_stepduals}: disable the line-search and take the close-to-boundary step. String values: ``no'' (default) and ``yes''.
+\noindent \textbf{accept\_every\_trial\_step}: Disables the filter line-search and take the close-to-boundary step. This step can be further controlled (while the filter line-search remains disabled) using options \textit{moving\_lim\_abs} and \textit{moving\_lim\_abs}. This option takes the string values: ``no'' (default) and ``yes''.
+\medskip
+
+\noindent \textbf{moving\_lim\_abs}: Controls the maximum allowed update of the $x$ primal variables during the line-search. Primal step-length may be reduced to ensure that the inf norm of the ``$\Delta x$'' update/direction is less than or equal with the option's value. It can be used with \textit{accept\_every\_trial\_step}. Numerical range is $[0,10^8]$. A zero value will disable this option. Default value: 0. 
+\medskip
+
+\noindent \textbf{moving\_lim\_rel}: Controls the maximum allowed update of the primal variables \textit{relative} to close-to-boundary step. With this option the line-search will be started using the close-to-boundary step \textit{scaled} by the option's value. Default value: 0 (disabled). It can be used with \textit{accept\_every\_trial\_step}. Numerical range is $[0,1]$. A zero value will disable this option. Default value: 0. 
 \medskip
 
 \noindent \textbf{duals\_init}: type of the update for the initialization of Lagrange multipliers corresponding to the equality constraints. Possible values one of the the strings ``lsq'' (least-square (LSQ) solve initialization) and ``zero'' (multipliers are set identically to zero). Default value: is ``lsq''.

diff --git a/doc/src/techrep_main.tex b/doc/src/techrep_main.tex
@@ -133,7 +133,7 @@
 \vspace{3cm}
 
   {\huge\bfseries \Hi\ -- User Guide} \\[14pt]
-  {\large\bfseries version 1.0}
+  {\large\bfseries version 1.03}
 
 \vspace{3cm}
 
@@ -155,7 +155,7 @@
 \vspace{4.75cm}
 
  \textcolor{violet}{{\large\bfseries Oct 15, 2017} \\
-{\large\bfseries Updated Sep 7, 2023}}
+{\large\bfseries Updated Feb 5, 2024}}
 
 \vspace{0.75cm}
 
@@ -242,7 +242,7 @@ \section{Introduction}
 \end{itemize}
 
 This document includes instructions on how to obtain and
-build \Hi and a description of its interface, user options, and use as an optimization library. Guidelines on how is best to use the solver for parallel computations are also provided. The document generally targets users of \Hi, but also contains information relevant to potential developers or advanced users; these are strongly encouraged to also read the paper on the computational approach implemented in \Hi~\cite{petra_hiop}.
+build \Hi and a description of its interface, user options, and use as an optimization library. Guidelines on how is best to use the solver for parallel computations are also provided. The document generally targets users of \Hi, but also contains information relevant to potential developers or advanced users; these are strongly encouraged to also read the paper on the computational approach implemented in \Hi~\cite{petra2019memory}.
 
 
 While the MPI quasi-Newton solver of \texttt{Hiop} targets DAE- and PDE-constrained optimization problems formulated in a ``reduced-space'' approach, it can be used for general nonconvex nonlinear optimization as well. For efficiency considerations, it is recommended to \textit{use quasi-Newton \texttt{Hiop} for NLPs that have a relatively small number of general constraints}, say less than $100$; note that there are no restrictions on the number of bounds constraints, \textit{e.g.}, one can specify simple bounds on any, and potentially all the decision variables without affecting the computational efficiency. The minimizers computed by \Hi satisfies \textit{local} first-order optimality conditions.

diff --git a/src/Utils/hiopOptions.cpp b/src/Utils/hiopOptions.cpp
@@ -689,13 +689,14 @@ void hiopOptionsNLP::register_options()
                         "Minimum step size allowed in line-search (default 1e-16). If step size is less than this number, " 
                         "feasibility restoration problem is activated.");
 
-    auto d_abs = "Max allowed update of the 'x' primal variables after the line-search. Primal step-length may be reduced "
-                 "so that the inf norm of the 'x' update is less or equal with the option's value. Default value: 0 (disabled).";
-    register_num_option("moving_lim_abs", 0, 0.0, 1e+8, d_abs);
+    auto d_abs = "Max allowed update of the 'x' primal variables during the line-search. Primal step-length may be reduced "
+                 "so that the inf norm of the 'x' update is less than or equal with the option's value. Default value: "
+                 "0 (disabled).";
+    register_num_option("moving_lim_abs", 0., 0., 1e+8, d_abs);
 
     auto d_rel = "Max allowed update of the primal variables relative to fraction-to-boundary (FTB) step. Line-search "
                  "will be started using the FTB step scaled by the option's value. Default value: 0 (disabled).";
-    register_num_option("moving_lim_rel", 0, 0.0, 1., d_rel);
+    register_num_option("moving_lim_rel", 0., 0., 1., d_rel);
 
     register_num_option("theta_max_fact",
                         1e+4,