Changeset 478


Ignore:
Timestamp:
Aug 23, 2005 6:11:44 PM (14 years ago)
Author:
claird
Message:

Added the ability to output option documentation
in latex mode.

Location:
branches/dev
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • branches/dev/Algorithm/LinearSolvers/IpMa27TSolverInterface.cpp

    r465 r478  
    7575  void Ma27TSolverInterface::RegisterOptions(SmartPtr<RegisteredOptions> roptions)
    7676  {
    77     roptions->AddBoundedNumberOption("pivtol", "pivot tolerance for the linear solver. smaller number - pivot for sparsity, larger number - pivot for stability",
    78                                      0.0, true, 1.0, true, 1e-8);
    79     roptions->AddBoundedNumberOption("pivtolmax", "maximum pivot tolerance. IPOPT may increase pivtol as high as pivtolmax to get a more accurate solution to the linear system",
    80                                      0.0, true, 1.0, true, 1e-4);
    81     roptions->AddLowerBoundedNumberOption("liw_init_factor", "integer workspace memory = liw_init_factor * memory required by unfactored system",
    82                                           1.0, false, 5.0);
    83     roptions->AddLowerBoundedNumberOption("la_init_factor", "real workspace memory = la_init_factor * memory required by unfactored system",
    84                                           1.0, false, 5.0);
    85     roptions->AddLowerBoundedNumberOption("meminc_factor", "if workspace is not large enough, IPOPT will increase the size by this factor",
    86                                           1.0, false, 10.0);
     77    roptions->AddBoundedNumberOption("pivtol", "Pivot tolerance for the linear solver.",
     78                                     0.0, true, 1.0, true, 1e-8,
     79                                     "A smaller number pivots for sparsity, "
     80                                     "a larger number pivots for stability.");
     81    roptions->AddBoundedNumberOption("pivtolmax", "Maximum pivot tolerance.",
     82                                     0.0, true, 1.0, true, 1e-4,
     83                                     "IPOPT may increase pivtol as high as pivtolmax "
     84                                     "to get a more accurate solution to the linear system");
     85    roptions->AddLowerBoundedNumberOption("liw_init_factor", "Integer workspace memory.",
     86                                          1.0, false, 5.0,
     87                                          "The initial integer workspace memory = liw_init_factor * memory "
     88                                          "required by unfactored system. IPOPT will increase the workspace size by "
     89                                          "meminc_factor if required.");
     90    roptions->AddLowerBoundedNumberOption("la_init_factor", "Real workspace memory",
     91                                          1.0, false, 5.0,
     92                                          "The initial real workspace memory = la_init_factor * memory "
     93                                          "required by unfactored system. IPOPT will increase the workspace size by "
     94                                          "meminc_factor if required.");
     95    roptions->AddLowerBoundedNumberOption("meminc_factor", "Increment factor for workspace size.",
     96                                          1.0, false, 10.0,
     97                                          "If the integer or real workspace is not large enough, "
     98                                          "IPOPT will increase its size by this factor");
    8799  }
    88100
  • branches/dev/Common/IpRegOptions.cpp

    r465 r478  
    9696      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "Default: \"%s\"\n",
    9797                   default_string_.c_str());
     98    }
     99  }
     100
     101  void RegisteredOption::OutputLatexDescription(const Journalist& jnlst) const
     102  {
     103    std::string latex_name;
     104    MakeValidLatexString(name_, latex_name);
     105    jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
     106                 "\\paragraph{%s} $\\;$ \\\\\n",  latex_name.c_str());
     107
     108    std::string latex_desc;
     109    MakeValidLatexString(short_description_, latex_desc);
     110    jnlst.PrintStringOverLines(J_SUMMARY, J_DOCUMENTATION, 0, 50,
     111                               latex_desc.c_str());
     112    if (long_description_ != "") {
     113      latex_desc = "";
     114      MakeValidLatexString(long_description_, latex_desc);     
     115      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " ");
     116      jnlst.PrintStringOverLines(J_SUMMARY, J_DOCUMENTATION, 0, 50,
     117                                 latex_desc.c_str());
     118    }
     119
     120    if (type_ == OT_Number) {
     121      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
     122                     " The valid range for this real option is \n$");
     123      if (has_lower_) {
     124        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%g", lower_);
     125      }
     126      else {
     127        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%s", "{\\tt -inf}");
     128      }
     129
     130      if (has_lower_ && !lower_strict_) {
     131        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " \\le ");
     132      }
     133      else {
     134        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " <  ");
     135      }
     136
     137      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "{\\tt %s }", latex_name.c_str());
     138
     139      if (has_upper_ && !upper_strict_) {
     140        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " \\le ");
     141      }
     142      else {
     143        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " <  ");
     144      }
     145
     146      if (has_upper_) {
     147        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%g", upper_);
     148      }
     149      else {
     150        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%s", "{\\tt +inf}");
     151      }
     152
     153      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
     154                   "$\nand its default value is %g.\n\n", default_number_);
     155     
     156    }
     157    else if (type_ == OT_Integer) {
     158      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
     159                     " The valid range for this integer option is\n$");
     160      if (has_lower_) {
     161        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%d \\le ", (Index)lower_);
     162      }
     163      else {
     164        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%s <  ", "{\\tt -inf}");
     165      }
     166
     167      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "{\\tt %s }", latex_name.c_str());
     168
     169      if (has_upper_) {
     170        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " \\le %d", (Index)upper_);
     171      }
     172      else {
     173        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, " <  %s", "{\\tt +inf}");
     174      }
     175
     176      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
     177                   "$\nand its default value is %d.\n\n",
     178                   (Index)default_number_);
     179    }
     180    else if (type_ == OT_String) {
     181      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "\\\\ \nPossible values:\n");
     182      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "\\begin{itemize}\n");
     183      for (std::vector<string_entry>::const_iterator
     184           i = valid_strings_.begin();
     185           i != valid_strings_.end(); i++) {
     186        std::string latex_value;
     187        MakeValidLatexString((*i).value_, latex_value);
     188        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "   \\item %s: ",
     189                     latex_value.c_str());
     190
     191        std::string latex_desc;
     192        MakeValidLatexString((*i).description_, latex_desc);
     193        jnlst.PrintStringOverLines(J_SUMMARY, J_DOCUMENTATION, 0, 48,
     194                                   latex_desc.c_str());
     195        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "\n");
     196      }
     197      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "\\end{itemize}\n");
     198    }
     199    jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "\n");
     200  }
     201
     202  void RegisteredOption::MakeValidLatexString(std::string source, std::string& dest) const
     203  {
     204    std::string::iterator c;
     205    for (c=source.begin(); c!=source.end(); c++) {
     206      if (*c == '_') {
     207        dest.append("\\_");
     208      }
     209      else if (*c == '^') {
     210        dest.append("\\^");
     211      }
     212      else {
     213        dest.push_back(*c);
     214      }
    98215    }
    99216  }
     
    673790    }
    674791  }
     792
     793  void RegisteredOptions::OutputLatexOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories)
     794  {
     795    std::list
     796    <std::string>::iterator i;
     797    for (i = categories.begin(); i != categories.end(); i++) {
     798      std::map<Index, SmartPtr<RegisteredOption> > class_options;
     799      std::map <std::string, SmartPtr<RegisteredOption> >::iterator option;
     800      for (option = registered_options_.begin();
     801           option != registered_options_.end(); option++) {
     802        if (option->second->RegisteringCategory() == (*i)) {
     803
     804          class_options[option->second->Counter()] = option->second;
     805        }
     806      }
     807      std::map<Index, SmartPtr<RegisteredOption> >::const_iterator co;
     808      for (co = class_options.begin(); co != class_options.end(); co++) {
     809        co->second->OutputLatexDescription(jnlst);
     810      }
     811    }
     812  }
     813
    675814} // namespace Ipopt
  • branches/dev/Common/IpRegOptions.hpp

    r470 r478  
    338338    /** output a more concise version */
    339339    void OutputShortDescription(const Journalist& jnlst) const;
     340    /** output a latex version */
     341    void OutputLatexDescription(const Journalist& jnlst) const;
    340342
    341343  private:
     
    353355    Number upper_;
    354356    Number default_number_;
     357
     358    void MakeValidLatexString(std::string source, std::string& dest) const;
    355359
    356360    /** Compare two strings and return true if they are equal (case
     
    556560     *  etc. */
    557561    void OutputOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories);
     562
     563    /** Output documentation in Latex format to include in a latex file */
     564    void OutputLatexOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories);
    558565    //@}
    559566
  • branches/dev/Docs/documentation.tex

    r477 r478  
    13981398successful. Finally, we free the memory and return from {\tt main}.
    13991399
    1400 \section{Ipopt Options}
     1400\section{Ipopt Options}\label{sec.options}
    14011401Ipopt has many (maybe too many) options that can be adjusted for the
    14021402algorithm.  Options are all identified by a string name and their
     
    14291429
    14301430Options can also be set in code. Have a look at the examples to see
    1431 how this is done. Note, the PARAMS.DAT file is given preference when
    1432 setting options. This way, you can easily override any options set in
    1433 a particular executable by creating PARAMS.DAT.
     1431how this is done.
     1432
     1433A subset of Ipopt options are available through AMPL. To set options
     1434through AMPL, use the internal AMPL command {\tt options}.  For
     1435example, \\
     1436{\tt options ipopt ``nlp\_scaling\_method=none mu\_init=1e-2
     1437max\_iter=500''} \\
     1438is a valid options command in AMPL. The most common
     1439options are referenced in Appendix \ref{app.options_ref}. These are also
     1440the options that are available through AMPL using the {\tt options}
     1441command. To specify other options when using AMPL, you can always
     1442create {\tt PARAMS.DAT}.  Note, the {\tt PARAMS.DAT} file is given
     1443preference when setting options. This way, you can easily override any
     1444options set in a particular executable or AMPL model by specifying new
     1445values in {\tt PARAMS.DAT}.
    14341446
    14351447For a short list of the valid options, see the Appendix
    14361448\ref{app.options_ref}. You can print the documentation for all Ipopt
    1437 options by adding the option, \\
    1438 {\tt print\_options\_documentation yes} \\
    1439 and running Ipopt (like the Ampl executable, for instance). This will
    1440 output all of the options documentation to the console.
     1449options by adding the option, \\ {\tt print\_options\_documentation
     1450yes} \\ and running Ipopt (like the Ampl executable, for
     1451instance). This will output all of the options documentation to the
     1452console.
    14411453
    14421454\section*{Acknowledgement}
     
    15571569
    15581570\section{Options Reference} \label{app.options_ref}
     1571Options can be set using {\tt PARAMS.DAT}, through your own code, or through the
     1572AMPL {\tt options} command. See Section \ref{sec.options} for an explanation of
     1573how to use these commands.
     1574Shown here is a short list of the most common options for Ipopt. To view
     1575the full list of options, run the ipopt executable with the option,
    15591576\begin{verbatim}
    1560 * print_options_documentation   ("no")
    1561    Switch to print list all algorithmic options
    1562      If selected, the algorithm will print the list of all available
    1563      algorithmic options with some documentation before solving the
    1564      optimization problem.
    1565    Possible values:
    1566     - no                      [don't print list]
    1567     - yes                     [print list]
    1568 
    1569 
    1570 ### Convergence ###
    1571 
    1572 *tol                                    0 <  (      1e-08) <  +inf     
    1573    Desired convergence tolerance (relative).
    1574      Determines the convergence tolerance for the algorthim.  The algorithm
    1575      terminates successfully, if the (scaled) NLP error becomes smaller than
    1576      this value, and if the (absolute) criteria according to "dual_inf_tol",
    1577      "primal_inf_tol", and "cmpl_inf_tol" are met.  (This is epsilon_tol in
    1578      Eqn. (6) in implementation paper).  [Some other algorithmic features also
    1579      use this quantity.]
    1580 
    1581 * max_iter                               0 <= (       3000) <  +inf     
    1582    Maximum number of iterations.
    1583      The algorithm terminates with an error message if the number of
    1584      iterations exceeded this number. [Also used in RestoFilterConvCheck]
    1585 
    1586 * dual_inf_tol                           0 <  (     0.0001) <  +inf     
    1587    Desired threshold for the dual infeasibility.
    1588      Absolute tolerance on the dual infesaibility. Successful termination
    1589      requires that the (unscaled) dual infeasibility is less than this
    1590      threshold.
     1577print_options_documentation yes
     1578\end{verbatim}
     1579
     1580The most common options are:
     1581
     1582
     1583
     1584
     1585
     1586\begin{verbatim}
     1587
     1588\paragraph{tol} $\;$ \\
     1589The desired relative convergence tolerance. The algorithm terminates
     1590successfully, if the (scaled) NLP error becomes smaller than this
     1591value, and if the (absolute) criteria according to "dual\_inf\_tol",
     1592"primal\_inf\_tol", and "cmpl\_inf\_tol" are met.  (This is
     1593epsilon\_tol in Eqn. (6) in implementation paper). Other
     1594algorithmic features rely on this quantity. The valid range is $0 <
     1595tol < +{\tt inf}$ and the default value is $1 \cdot 10^{-8}$.
     1596
     1597\paragraph{max\_iter} $\;$ \\
     1598The maximum number of iterations allowed.  The algorithm terminates with an error
     1599message if the number of iterations exceeds this number. Also used
     1600in the convergence check for the restoratin phase.
     1601The valid range for this option is $0 \le
     1602{\tt max_iter} < +{\tt inf}$ and the default value is $3000$.
     1603
     1604
     1605\paragraph{dual\_inf\_tol} $\;$ \\
     1606Absolute tolerance on
     1607the dual infesaibility. Successful termination requires that the
     1608(unscaled) dual infeasibility is less than this threshold. The valid
     1609range is $0 < {\tt dual\_inf\_tol} < +{\tt inf}$ and the default value
     1610is $1\cdot 10^{-4}$.
     1611
    15911612
    15921613* constr_viol_tol                        0 <  (     0.0001) <  +inf     
  • branches/dev/Interfaces/IpIpoptApplication.cpp

    r477 r478  
    131131        categories.push_back("MA27 Linear Solver");
    132132        categories.push_back("Uncategorized");
    133         reg_options->OutputOptionDocumentation(*jnlst_, categories);
     133        bool latex;
     134        options_->GetBoolValue("print_options_latex_mode", latex, "");
     135        if (latex) {
     136          reg_options->OutputLatexOptionDocumentation(*jnlst_, categories);
     137        }
     138        else {
     139          reg_options->OutputOptionDocumentation(*jnlst_, categories);
     140        }
    134141      }
    135142
     
    219226      " For user-scaling, the parameters come from the NLP. If you are using "
    220227      "AMPL, they can be specified through suffixes (scaling_factor)");
     228
     229    roptions->SetRegisteringCategory("Undocumented Options");
     230    roptions->AddStringOption2(
     231                               "print_options_latex_mode",
     232                               "Undocumented", "no",
     233                               "no", "Undocumented",
     234                               "yes", "Undocumented",
     235                               "Undocumented"
     236                               );
    221237  }
    222238
Note: See TracChangeset for help on using the changeset viewer.