Changeset 490


Ignore:
Timestamp:
Aug 24, 2005 6:20:52 PM (14 years ago)
Author:
claird
Message:

Modified the text in all the options and added
a method to RegisteredOptions? to print options
in latex format for documentation.

Location:
branches/dev
Files:
25 edited

Legend:

Unmodified
Added
Removed
  • branches/dev/Algorithm/IpAdaptiveMuUpdate.cpp

    r465 r490  
    5353      "Maximum value for barrier parameter.",
    5454      0.0, true, 1e10,
    55       "This option allows to speficy and upper bound on the adaptively chosen "
    56       "barrier parameter.");
     55      "This option specifies an upper bound on the barrier parameter in the "
     56      "adaptive mu selection mode.");
    5757    roptions->AddLowerBoundedNumberOption(
    5858      "mu_min",
    5959      "Minimum value for barrier parameter ",
    6060      0.0, true, 1e-9,
    61       "This option allows to specify a lower bound on the adaptively chosen "
    62       "barrier parameter. By default, it is set to "
     61      "This option specifies the lower bound on the barrier parameter in the "
     62      "adaptive mu selection mode. By default, it is set to "
    6363      "min(\"tol\",\"compl_inf_tol\")/(\"barrier_tol_factor\"+1), which "
    6464      "should be a very reasonable value.");
     65    std::string prev_cat = roptions->RegisteringCategory();
     66    roptions->SetRegisteringCategory("Undocumented");
    6567    roptions->AddLowerBoundedNumberOption(
    6668      "adaptive_mu_safeguard_factor",
    6769      "ToDo: This option should probably be deleted!",
    6870      0.0, false, 0.0);
     71    roptions->SetRegisteringCategory(prev_cat);
    6972
    7073    roptions->AddStringOption3(
    7174      "adaptive_mu_globalization",
    72       "Globalization strategy for non-monotone mode",
     75      "Globalization strategy for the adaptive mu selection mode",
    7376      "obj-constr-filter",
    7477      "kkt-error", "nonmonotone decrease of kkt-error",
     
    7679      "never-monotone-mode", "disables globalization",
    7780      "To achieve global convergence of the adaptive version, the algorithm "
    78       "has to swtich to the monotone mode (Fiacco-McCormick approach) when "
    79       "convergence does not seem to appear.  This option determines the "
    80       "criterion to be used to decide when to switch to the monotone mode.");
     81      "has to switch to the monotone mode (Fiacco-McCormick approach) when "
     82      "convergence does not seem to appear.  This option sets the "
     83      "criterion used to decide when to do this switch.");
    8184
    8285    roptions->AddLowerBoundedIntegerOption(
    8386      "adaptive_mu_kkterror_red_iters",
    84       "Specifying maximal number of iterations in which sufficient progress in kkt-error globalization must be made.",
     87      "Maximum number of iterations requiring sufficient progress.",
    8588      0, 4,
    86       "For the \"kkt-error\" based globalization strategy, this "
    87       "determines after maximal how many iterations sufficient progress must "
    88       "be made.  If that number of iterations is exceeded, the "
     89      "For the \"kkt-error\" based globalization strategy, sufficient "
     90      "progress must be made for \"adaptive_mu_kkterror_red_iters\" "
     91      "iterations. If this number of iterations is exceeded, the "
    8992      "globalization strategy switches to the monotone mode.");
    9093
    9194    roptions->AddBoundedNumberOption(
    9295      "adaptive_mu_kkterror_red_fact",
    93       "Factor specifying sufficient decrease in kkt-error globalization strategy",
     96      "Sufficient decrease factor for \"kkt-error\" globalization strategy.",
    9497      0.0, true, 1.0, true,
    9598      0.9999,
    96       "For the \"kkt-error\" based globalization strategy, this "
    97       "determines by how much the error has to be decrease to be deemed "
    98       "sufficient.");
     99      "For the \"kkt-error\" based globalization strategy, the error "
     100      "must decrease by this factor to be deemed sufficient decrease.");
    99101
    100102    roptions->AddBoundedNumberOption(
     
    103105      0.0, true, 1.0, true,
    104106      1e-5,
    105       "The definition of sufficient progress for the adaptive globalization "
    106       "strategy \"obj-constr-filter\" for a filter entry is defined as "
     107      "When using the adaptive globalization strategy, \"obj-constr-filter\", "
     108      "sufficient progress for a filter entry is defined as "
    107109      "follows: (new obj) < (filter obj) - filter_margin_fact*(new "
    108110      "constr-voil) OR (new constr-viol) < (filter constr-viol) - "
     
    111113    roptions->AddLowerBoundedNumberOption(
    112114      "filter_max_margin",
    113       "Maximal width of margin.in *-filter adaptive globalization strategies.",
     115      "Maximum width of margin in *-filter adaptive globalization strategies.",
    114116      0.0, true,
    115117      1.0,
    116       "ToDo: Detailed description later.");
     118      // ToDo Detailed description later
     119      "");
    117120    roptions->AddStringOption2(
    118121      "adaptive_mu_restore_previous_iterate",
    119       "Determines whether the previous iterate should be restore if the monotone mode is entered.",
     122      "Should the previous iterate be restored if the monotone mode is entered.",
    120123      "no",
    121124      "no", "don't restore accepted iterate",
    122125      "yes", "restore accepted iterate",
    123126      "When the globalization strategy for the adaptive barrier algorithm "
    124       "switches to the monotone mode, it can either start that mode "
    125       "from the most recent iterate (no), or from the most previous "
    126       "iterate, which had been accepted (yes).");
     127      "switches to the monotone mode, it can either start "
     128      "from the most recent iterate (no), or from the last "
     129      "iterate that was accepted (yes).");
    127130
    128131    roptions->AddLowerBoundedNumberOption(
     
    132135      "When the globalization strategy for the adaptive barrier algorithm "
    133136      "switches to the monotone mode, the barrier parameter is set to the "
    134       "current average complementarity times the value of this parameter.");
     137      "current average complementarity times the value of "
     138      "\"adaptive_mu_monotone_init_factor\".");
    135139
    136140    roptions->AddStringOption4(
     
    143147      "2-norm", "use 2-norm",
    144148      "When computing the KKT error for the globalization strategies, the "
    145       "norm specified with this option is used.  [This options is also used "
    146       "in QualityFunctionMuOracle]");
     149      "norm to be used is specified with this option. Note, this options is also used "
     150      "in the QualityFunctionMuOracle.");
    147151
    148152  }
  • branches/dev/Algorithm/IpAlgBuilder.cpp

    r477 r490  
    5252  void AlgorithmBuilder::RegisterOptions(SmartPtr<RegisteredOptions> roptions)
    5353  {
    54     roptions->SetRegisteringCategory("Linear Solver");
     54    roptions->SetRegisteringCategory("Undocumented");
    5555    roptions->AddStringOption3(
    5656      "linear_solver",
     
    6161      "taucs", "use TAUCS package",
    6262      "Determines which linear algebra package is to be used for the "
    63       "solution of the linear system from which the search directions is "
    64       "obtained.  Note that depending on your Ipopt installation, not all "
    65       "options might be available.");
     63      "solution of the augmented linear system (obtaining the search directions) "
     64      "Note that depending on your Ipopt installation, not all "
     65      "options may be available.");
     66    roptions->SetRegisteringCategory("Linear Solver");
    6667    roptions->AddStringOption2(
    6768      "linear_system_scaling",
     
    7071      "none", "no scaling will be performed",
    7172      "mc19", "use the Harwell routine mc19",
    72       "Determines which method should be use to compute symmetric scaling "
    73       "factors for the augmented system.");
     73      "Determines the method used to compute symmetric scaling "
     74      "factors for the augmented system. This scaling will be done "
     75      "in addition to any NLP problem scaling.");
    7476
    7577    roptions->SetRegisteringCategory("Mu Update");
     
    8082      "monotone", "use the monotone (Fiacco-McCormick) strategy",
    8183      "adaptive", "use the adaptive update strategy",
    82       "Determines which barrier parameter strategy is to be used.");
     84      "Determines which barrier parameter update strategy is to be used.");
    8385    roptions->AddStringOption3(
    8486      "mu_oracle",
  • branches/dev/Algorithm/IpDefaultIterateInitializer.cpp

    r465 r490  
    2626    reg_options->AddLowerBoundedNumberOption(
    2727      "bound_push",
    28       "Desired minimal absolute distance of initial point to bound",
     28      "Desired minimum absolute distance from the initial point to bound",
    2929      0.0, true, 0.01,
    30       "Determines (together with \"bound_frac\") by how much the initial "
    31       "point might have to be modified in order to be sufficiently inside "
    32       "the bounds.");
     30      "Determines how much the initial point might have to "
     31      "be modified in order to be sufficiently inside "
     32      "the bounds (together with \"bound_frac\").");
    3333    reg_options->AddBoundedNumberOption(
    3434      "bound_frac",
    35       "Desired minimal relative distance of initial point to bound",
     35      "Desired minimum relative distance from the initial point to bound",
    3636      0, true, 0.5, false, 0.01,
    37       "Determines (together with \"bound_push\") by how much the initial "
    38       "point might have to be modified in order to be sufficiently inside "
    39       "the bounds.");
     37      "Determines how much the initial point might have to "
     38      "be modified in order to be sufficiently inside "
     39      "the bounds (together with \"bound_push\").");
    4040    reg_options->AddLowerBoundedNumberOption(
    4141      "constr_mult_init_max",
    42       "Maximal allowed least-square guess of constraint multipliers.",
     42      "Maximum allowed least-square guess of constraint multipliers.",
    4343      0, false, 1e3,
    4444      "Determines how large the initial least-square guesses of the contraint "
    45       "multipliers (in max-norm) are allowed to be. If the guess is larger "
     45      "multipliers are allowed to be (in max-norm). If the guess is larger "
    4646      "than this value, it is discarded and all constraint multipliers are "
    47       "set to zero.  This options is also used in the classes "
    48       "\"RestoIterateInitializer\".  By default, "
    49       "\"resto.constr_mult_init_max\" (the one "
     47      "set to zero.  This options is also used when initializing the "
     48      "restoration phase. By default, \"resto.constr_mult_init_max\" (the one "
    5049      "used in RestoIterateInitializer) is set to zero.");
    5150    reg_options->AddLowerBoundedNumberOption(
  • branches/dev/Algorithm/IpFilterLineSearch.cpp

    r488 r490  
    7373    roptions->AddLowerBoundedNumberOption(
    7474      "theta_min_fact",
    75       "Determines constraint violation threshold in switching rule.",
     75      "Determines constraint violation threshold in the switching rule.",
    7676      0.0, true, 1e-4,
    77       "The algorithmic parameter theta_min is determined as theta_max_fact "
     77      "The algorithmic parameter theta_min is determined as theta_min_fact "
    7878      "times the maximum of 1 and the constraint violation at initial point.  "
    79       "The switching rules treats an iteration as h-type iteration whenever "
     79      "The switching rules treats an iteration as an h-type iteration whenever "
    8080      "the current constraint violation is larger than theta_min (see "
    8181      "paragraph before Eqn. (19) in implementation paper).");
     
    8686      "(See Eqn. (20) in implementation paper)");
    8787    roptions->AddLowerBoundedNumberOption(
    88       "delta", "Multiplier for constraint violation in switching rule.",
     88      "delta", "Multiplier for constraint violation in the switching rule.",
    8989      0.0, true, 1.0,
    9090      "(See Eqn. (19) in implementation paper)");
    9191    roptions->AddLowerBoundedNumberOption(
    9292      "s_phi",
    93       "Exponent for linear barrier function model in switching rule.",
     93      "Exponent for linear barrier function model in the switching rule.",
    9494      1.0, true, 2.3,
    9595      "(See Eqn. (19) in implementation paper)");
    9696    roptions->AddLowerBoundedNumberOption(
    9797      "s_theta",
    98       "Exponent for current constraint violation in switching rule.",
     98      "Exponent for current constraint violation in the switching rule.",
    9999      1.0, true, 1.1,
    100100      "(See Eqn. (19) in implementation paper)");
    101101    roptions->AddBoundedNumberOption(
    102102      "gamma_phi",
    103       "Relaxation factor in filter margin for barrier function.",
     103      "Relaxation factor in the filter margin for the barrier function.",
    104104      0.0, true, 1.0, true, 1e-8,
    105105      "(See Eqn. (18a) in implementation paper)");
    106106    roptions->AddBoundedNumberOption(
    107107      "gamma_theta",
    108       "Relaxation factor in filter margin for constraint violation.",
     108      "Relaxation factor in the filter margin for the constraint violation.",
    109109      0.0, true, 1.0, true, 1e-5,
    110110      "(See Eqn. (18b) in implementation paper)");
    111111    roptions->AddBoundedNumberOption(
    112112      "alpha_min_frac",
    113       "Safety factor for minimal step size (switch to restoration phase).",
     113      "Safety factor for the minimal step size (before switching to restoration phase).",
    114114      0.0, true, 1.0, true, 0.05,
    115115      "(This is gamma_alpha in Eqn. (20) in implementation paper)");
    116116    roptions->AddBoundedNumberOption(
    117117      "alpha_red_factor",
    118       "Fractional reduction of trial step size in the backtracking line search.",
     118      "Fractional reduction of the trial step size in the backtracking line search.",
    119119      0.0, true, 1.0, true, 0.5,
    120       "Determines the fraction by how much the trial step size is reduced in "
    121       "every step of the backtracking line search.");
     120      "At every step of the backtracking line search, the trial step size is "
     121      "reduced by this factor.");
    122122    roptions->AddLowerBoundedIntegerOption(
    123123      "max_soc",
    124       "Maximal number of second order correction trial steps.",
     124      "Maximum number of second order correction trial steps at each iteration.",
    125125      0, 4,
    126       "Determines the maximal number of second order correction trial steps "
    127       "that should be performed.  Choosing 0 disables the second order "
     126      "Choosing 0 disables the second order "
    128127      "corrections. (This is p^{max} of Step A-5.9 of "
    129128      "Algorithm A in implementation paper.)");
    130129    roptions->AddLowerBoundedNumberOption(
    131130      "kappa_soc",
    132       "Factor in sufficient reduction rule for second order correction.",
     131      "Factor in the sufficient reduction rule for second order correction.",
    133132      0.0, true, 0.99,
    134       "Determines by how much a second order correction step must reduce the "
     133      "This option determines how much a second order correction step must reduce the "
    135134      "constraint violation so that further correction steps are attempted.  "
    136135      "(See Step A-5.9 of Algorithm A in implementation paper.)");
    137136    roptions->AddLowerBoundedNumberOption(
    138137      "obj_max_inc",
    139       "Determines upper bound on acceptable increase of barrier objective function.",
     138      "Determines the upper bound on the acceptable increase of barrier objective function.",
    140139      1.0, true, 5.0,
    141       "A trial point leading to more orders of magnitude increase in the "
    142       "barrier objective function are rejected.");
     140      "Trial points are rejected if they lead to anincrease in the "
     141      "barrier objective function by more than obj_max_inc orders "
     142      "of magnitude.");
     143     
     144    std::string prev_category = roptions->RegisteringCategory();
     145    roptions->SetRegisteringCategory("Undocumented");
    143146    roptions->AddStringOption2(
    144147      "magic_steps",
     
    148151      "yes", "take magic steps",
    149152      "DOESN'T REALLY WORK YET!");
     153    roptions->SetRegisteringCategory(prev_category);
    150154    roptions->AddStringOption3(
    151155      "corrector_type",
    152       "Type of corrector steps.",
     156      "The type of corrector steps that should be taken.",
    153157      "none",
    154158      "none", "no corrector",
    155159      "affine", "corrector step towards mu=0",
    156160      "primal-dual", "corrector step towards current mu",
    157       "Determines what kind of corrector steps should be tried.");
     161      "If \"mu_strategy\" is \"adaptive\", this option determines "
     162      "what kind of corrector steps should be tried.");
    158163
    159164    roptions->AddStringOption2(
     
    163168      "no", "don't skip",
    164169      "yes", "skip",
    165       "The corrector step is not tried if during the computation of "
    166       "the search direction in the current iteration negative curvature has "
    167       "been encountered.");
     170      "The corrector step is not tried if negative curvature has been "
     171      "encountered during the computation of the search direction in "
     172      "the current iteration. This option is only used if \"mu_strategy\" is "
     173      "\"adaptive\".");
    168174
    169175    roptions->AddStringOption2(
     
    174180      "yes", "skip",
    175181      "The corrector step is not tried if the algorithm is currently in the "
    176       "monotone mode (see also option \"barrier_strategy\").");
     182      "monotone mode (see also option \"barrier_strategy\")."
     183      "This option is only used if \"mu_strategy\" is \"adaptive\".");
    177184
    178185    roptions->AddStringOption2(
    179186      "accept_every_trial_step",
    180       "always accept the frist trial step",
     187      "Always accept the frist trial step.",
    181188      "no",
    182189      "no", "don't arbitrarily accept the full step",
     
    187194    roptions->AddStringOption7(
    188195      "alpha_for_y",
    189       "Step size for constraint multipliers.",
     196      "Method to determine the step size for constraint multipliers.",
    190197      "primal",
    191198      "primal", "use primal step size",
     
    196203      "min_dual_infeas", "choose step size minimizing new dual infeasibility",
    197204      "safe_min_dual_infeas", "like \"min_dual_infeas\", but safeguarded by \"min\" and \"max\"",
    198       "Determines which step size (alpha_y) should be used to update the "
     205      "This option determines how the step size (alpha_y) will be calculated when updating the "
    199206      "constraint multipliers.");
    200207
    201208    roptions->AddLowerBoundedNumberOption(
    202209      "corrector_compl_avrg_red_fact",
    203       "Complementarity tolerance factor for accepting corrector step",
     210      "Complementarity tolerance factor for accepting corrector step.",
    204211      0.0, true, 1.0,
    205       "Determines the factor by which complementarity is allowed to increase "
     212      "This option determines the factor by which complementarity is allowed to increase "
    206213      "for a corrector step to be accepted.");
    207214
     
    220227    roptions->AddLowerBoundedNumberOption(
    221228      "expect_infeasible_problem_ctol",
    222       "Threshold for disabling \"expect_infeasible_problem\" option",
     229      "Threshold for disabling \"expect_infeasible_problem\" option.",
    223230      0.0, false, 1e-3,
    224       "If the constraint violation becomes small than this threshold, "
     231      "If the constraint violation becomes smaller than this threshold, "
    225232      "the \"expect_infeasible_problem\" heuristics in the filter line "
    226       "search will are disabled. If the problem is square, this is set to 0.");
     233      "search are disabled. If the problem is square, this is set to 0.");
    227234    roptions->AddLowerBoundedNumberOption(
    228235      "soft_resto_pderror_reduction_factor",
    229       "Required reduction in primal-dual error in soft restoration phase.",
     236      "Required reduction in primal-dual error in the soft restoration phase.",
    230237      0.0, false, (1.0 - 1e-4),
    231       "For the soft restoration phase (which attempts to reduce the "
    232       "primal-dual error with regular steps), this indicates by which "
    233       "factor the primal-dual error has to be reduced in order to continue "
    234       "with the soft restoration phase. If the regular primal-dual step, "
    235       "damped onl to satisfty the fraction-to-the-boundary rule, is not "
    236       "decreasing the error by this factor, then the regular restoration "
    237       "phase is called.  Choosing \"0\" here disables the soft "
     238      "The soft restoration phase attempts to reduce the "
     239      "primal-dual error with regular steps. If the damped "
     240      "primal-dual step (damped only to satisfy the "
     241      "fraction-to-the-boundary rule) is not decreasing the primal-dual error "
     242      "by at least this factor, then the regular restoration phase is called. "
     243      "Choosing \"0\" here disables the soft "
    238244      "restoration phase.");
    239245    roptions->AddStringOption2(
     
    243249      "no", "don't force start in restoration phase",
    244250      "yes", "force start in restoration phase",
    245       "Setting this option to yes forces the algorithm to switch to the "
    246       "restoration phase in the first iteration. If the initial point "
     251      "Setting this option to \"yes\" forces the algorithm to switch to the "
     252      "feasibility restoration phase. If the initial point "
    247253      "is feasible, the algorithm will abort with a failure.");
    248254    roptions->AddLowerBoundedNumberOption(
     
    251257      0.0, false, 10.0*std::numeric_limits<double>::epsilon(),
    252258      "If the search direction in the primal variables (x and s) is, in "
    253       "relative terms for each component, less than this values, the "
     259      "relative terms for each component, less than this value, the "
    254260      "algorithm accepts the full step without line search.  The default "
    255261      "value is 10 times machine precision.");
     
    264270    roptions->AddLowerBoundedIntegerOption(
    265271      "watchdog_trial_iter_max",
    266       "Maximal number of watchdog iterations.",
     272      "Maximum number of watchdog iterations.",
    267273      1, 3,
    268       "Determines the number of trial iterations before the watchdog "
     274      "This option determines the number of trial iterations "
     275      "allowed before the watchdog "
    269276      "procedure is aborted and the algorithm returns to the stored point.");
    270277  }
  • branches/dev/Algorithm/IpGradientScaling.cpp

    r460 r490  
    2626  {
    2727    roptions->AddLowerBoundedNumberOption(
    28       "nlp_scaling_max_gradient", "maximum gradient after scaling",
     28      "nlp_scaling_max_gradient", "Maximum gradient after scaling.",
    2929      0, true, 100.0,
    3030      "This is the gradient scaling cut-off. If the maximum"
    3131      " gradient is above this value, then gradient based scaling"
    32       " will be performed. Scaling parameters will scale the maximum"
    33       " gradient back to this value. Note: This option is only used"
    34       " if \"nlp_scaling_method\" is chosen as \"gradient_based\".");
     32      " will be performed. Scaling parameters are calculated to"
     33      " scale the maximum gradient back to this value. Note: This"
     34      " option is only used if \"nlp_scaling_method\" is chosen as"
     35      " \"gradient_based\".");
    3536  }
    3637
  • branches/dev/Algorithm/IpIpoptAlg.cpp

    r487 r490  
    5252    roptions->AddLowerBoundedNumberOption(
    5353      "kappa_sigma",
    54       "Factor limiting deviation of dual variables from primal estimates.",
     54      "Factor limiting the deviation of dual variables from primal estimates.",
    5555      0, true, 1e10,
    56       "(see Eqn. (16) in the implementation paper.) Setting to value less than "
    57       "one disables correction.");
     56      "If the dual variables deviate from their primal estimates, a correction "
     57      "is performed. (See Eqn. (16) in the implementation paper.)"
     58      "Setting the to value less than one disables the correction.");
    5859  }
    5960
  • branches/dev/Algorithm/IpIpoptCalculatedQuantities.cpp

    r477 r490  
    162162      0.0, false,
    163163      pow(std::numeric_limits<double>::epsilon(), 0.75),
    164       "Due to numercal issues or lack of interior, the slack variables might "
     164      "Due to numerical issues or the lack of an interior, the slack variables might "
    165165      "become very small.  If a slack becomes very small compared to machine "
    166       "precision, the corresponding bound is moved a little.  This parameter "
    167       "determines how large the perturbation should be.  Its default value is "
     166      "precision, the corresponding bound is moved slightly.  This parameter "
     167      "determines how large the move should be.  Its default value is "
    168168      "mach_eps^{3/4}.  (See also end of Section 3.5 in implementation paper "
    169169      "- but actual implementation might be somewhat different.)");
     
    177177      "max-norm", "use the infinity norm",
    178178      "Determines which norm should be used when the algorithm computes the "
    179       "constraint violation, for example for the line search.");
     179      "constraint violation (for example, in the line search).");
    180180  }
    181181
  • branches/dev/Algorithm/IpIpoptData.cpp

    r465 r490  
    4848      "Desired convergence tolerance (relative).",
    4949      0.0, true,  1e-8,
    50       "Determines the convergence tolerance for the algorthim.  The "
     50      "Determines the convergence tolerance for the algorithm.  The "
    5151      "algorithm terminates successfully, if the (scaled) NLP error "
    5252      "becomes smaller than this value, and if the (absolute) criteria "
    5353      "according to \"dual_inf_tol\", \"primal_inf_tol\", and "
    5454      "\"cmpl_inf_tol\" are met.  (This is epsilon_tol in Eqn. (6) in "
    55       "implementation paper).  [Some other algorithmic features also use "
    56       "this quantity.]");
     55      "implementation paper). Note, some other algorithmic features also use "
     56      "this quantity.");
    5757  }
    5858
  • branches/dev/Algorithm/IpMonotoneMuUpdate.cpp

    r465 r490  
    5252      "This option determines the initial value for the barrier parameter "
    5353      "(mu).  It is only relevant in the monotone, Fiacco-McCormick "
    54       "version of the algorithm., i.e., if \"mu_strategy\" is chosen "
    55       "as \"monotone\"");
     54      "version of the algorithm. (i.e., if \"mu_strategy\" is chosen "
     55      "as \"monotone\")");
    5656    roptions->AddLowerBoundedNumberOption(
    5757      "barrier_tol_factor",
     
    6060      10.0,
    6161      "The convergence tolerance for each barrier problem in the montone mode "
    62       "is the value of the barrier parameter times this value. This option is "
    63       "also used in class \"AdaptiveMuUpdate\" during the monotone mode. "
    64       "(This is kappa_epsilon in implementation paper).");
     62      "is the value of the barrier parameter times \"barrier_tol_factor\". "
     63      "This option is also used in the adaptive mu strategy during the "
     64      "monotone mode. (This is kappa_epsilon in implementation paper).");
    6565    roptions->AddBoundedNumberOption(
    6666      "mu_linear_decrease_factor",
     
    7171      "is obtained by taking the minimum of mu*\"mu_linear_decrease_factor\" "
    7272      "and mu^\"superlinear_decrease_power\".  (This is kappa_mu in "
    73       "implementation paper.) [This option is also used in "
    74       "AdaptiveMuUpdate]");
     73      "implementation paper.) This option is also used in the adaptive mu "
     74      "strategy during the monotone mode.");
    7575    roptions->AddBoundedNumberOption(
    7676      "mu_superlinear_decrease_power",
     
    8181      "is obtained by taking the minimum of mu*\"mu_linear_decrease_factor\" "
    8282      "and mu^\"superlinear_decrease_power\".  (This is theta_mu in "
    83       "implementation paper.) [This option is also used in "
    84       "AdaptiveMuUpdate]");
     83      "implementation paper.) This option is also used in the adaptive mu "
     84      "strategy during the monotone mode.");
    8585    roptions->AddBoundedNumberOption(
    8686      "tau_min",
     
    8888      0.0, true, 1.0, true,
    8989      0.99,
    90       "(This is tau_min in implementation paper.) [This option is also "
    91       "used in AdaptiveMuUpdate]");
     90      "(This is tau_min in implementation paper.)  This option is also used "
     91      "in the adaptive mu strategy during the monotone mode.");
    9292  }
    9393
  • branches/dev/Algorithm/IpNLPScaling.cpp

    r465 r490  
    187187      "Scaling factor for the objective function.",
    188188      1.,
    189       "This option allows to set a scaling factor for the objective function "
    190       "that is used to scale the problem that is seen internally by "
    191       "Ipopt. If additional scaling parameters are computed "
    192       "(e.g. user-scaling or gradient-based), this factor is multiplied "
    193       "in addition. If this value is chosen to be negative, Ipopt will "
    194       "maximize the objective function.");
     189      "This option sets a scaling factor for the objective function. "
     190      "The scaling is seen internally by Ipopt but the unscaled objective is "
     191      "reported in the console output. "
     192      "If additional scaling parameters are computed "
     193      "(e.g. user-scaling or gradient-based), both factors are multiplied. "
     194      "If this value is chosen to be negative, Ipopt will "
     195      "maximize the objective function instead of minimizing it.");
    195196  }
    196197
  • branches/dev/Algorithm/IpOptErrorConvCheck.cpp

    r465 r490  
    2828      0, 3000,
    2929      "The algorithm terminates with an error message if the number of "
    30       "iterations exceeded this number. [Also used in RestoFilterConvCheck]");
     30      "iterations exceeded this number. This option is also used in the "
     31      "restoration phase.");
    3132    roptions->AddLowerBoundedNumberOption(
    3233      "dual_inf_tol",
     
    5253    roptions->AddLowerBoundedIntegerOption(
    5354      "acceptable_iter",
    54       "Number of acceptable iterates to trigger termination.",
     55      "Number of acceptable iterates before triggering termination.",
    5556      0, 15,
    56       "If the algorithm encounters so many successive acceptable iterates "
     57      "If the algorithm encounters this many successive acceptable iterates "
    5758      "(see \"acceptable_tol\"), it terminates, assuming that the problem "
    5859      "has been solved to best possible accuracy given round-off.  If it is "
  • branches/dev/Algorithm/IpOrigIpoptNLP.cpp

    r489 r490  
    7070      1e-8,
    7171      "Before start of the optimization, the bounds given by the user are "
    72       "relaxed.  This option determines the factor by how much.  If it "
    73       "is set to zero, then this option is disabled.  (See Eqn.(35) in "
    74       "implmentation paper.)");
     72      "relaxed.  This option sets the factor for this relaxation.  If it "
     73      "is set to zero, then then bounds relaxation is disabled. "
     74      "(See Eqn.(35) in implmentation paper.)");
    7575  }
    7676
  • branches/dev/Algorithm/IpOrigIterationOutput.cpp

    r485 r490  
    3434  OrigIterationOutput::RegisterOptions(SmartPtr<RegisteredOptions> roptions)
    3535  {
     36    std::string prev_cat = roptions->RegisteringCategory();
     37    roptions->SetRegisteringCategory("Undocumented");
    3638    roptions->AddStringOption2(
    3739      "print_info_string",
     
    4143      "yes", "print string at end of each iteration output",
    4244      "This string contains some insider information about the current iteration.");
     45    roptions->SetRegisteringCategory(prev_cat);
    4346  }
    4447
  • branches/dev/Algorithm/IpPDFullSpaceSolver.cpp

    r465 r490  
    3939      "Minimum number of iterative refinement steps per linear system solve.",
    4040      0, 1,
    41       "Iterative refinement (on the unsymmetric full system) is performed for "
    42       "each right hand side.  This option determines the minimal number "
    43       "of iterative refinements, i.e., by setting it to 1 at least one "
    44       "iterative refinement step per right hand side is enforce.");
     41      "Iterative refinement (on the full unsymmetric system) is performed for "
     42      "each right hand side.  This option determines the minimum number "
     43      "of iterative refinements (i.e. at least \"min_refinement_steps\" "
     44      "iterative refinement steps are enforced per right hand side.)");
    4545    roptions->AddLowerBoundedIntegerOption(
    4646      "max_refinement_steps",
    47       "Maximal number of iterative refinement steps per linear system solve.",
     47      "Maximum number of iterative refinement steps per linear system solve.",
    4848      0, 10,
    49       "Iterative refinement (on the unsymmetric full system) is performed for "
    50       "each right hand side.  This option determines the maximal number "
    51       "of iterative refinements.");
     49      "Iterative refinement (on the full unsymmetric system) is performed for "
     50      "each right hand side.  This option determines the maximum number "
     51      "of iterative refinement steps.");
    5252    roptions->AddLowerBoundedNumberOption(
    5353      "residual_ratio_max",
  • branches/dev/Algorithm/IpPDPerturbationHandler.cpp

    r488 r490  
    4949    roptions->AddLowerBoundedNumberOption(
    5050      "min_hessian_perturbation",
    51       "Smallest value by which Hessian block is perturbed.",
     51      "Smallest perturbation of the Hessian block.",
    5252      0., false, 1e-20,
    53       "The size of the perturbation of the Hessian block is never chosen "
     53      "The size of the perturbation of the Hessian block is never selected "
    5454      "smaller than this value, unless no perturbation is necessary. (This "
    5555      "is delta_w^min in implementation paper.)");
     
    6060      "The factor by which the perturbation is increased when a trial value "
    6161      "was not sufficient - this value is used for the computation of the "
    62       "very first perturbation. (This is bar_kappa_w^+ in implementation "
    63       "paper.)");
     62      "very first perturbation and allows a different value for for the first "
     63      "perturbation than that used for the remaining perturbations. "
     64      "(This is bar_kappa_w^+ in implementation paper.)");
    6465    roptions->AddLowerBoundedNumberOption(
    6566      "perturb_inc_fact",
     
    6869      "The factor by which the perturbation is increased when a trial value "
    6970      "was not sufficient - this value is used for the computation of "
    70       "later perturbations. (This is kappa_w^+ in implementation paper.)");
     71      "all perturbations except for the first. "
     72      "(This is kappa_w^+ in implementation paper.)");
    7173    roptions->AddBoundedNumberOption(
    7274      "perturb_dec_fact",
     
    7880    roptions->AddLowerBoundedNumberOption(
    7981      "first_hessian_perturbation",
    80       "First size of first x-s perturbation tried.",
     82      "Size of first x-s perturbation tried.",
    8183      0., true, 1e-4,
    82       "The first value for an x-s perturbation factors tried. "
     84      "The first value tried for the x-s perturbation. "
    8385      "(This is delta_0 in implementation paper.)");
    8486    roptions->AddLowerBoundedNumberOption(
  • branches/dev/Algorithm/IpQualityFunctionMuOracle.cpp

    r465 r490  
    5858    roptions->AddLowerBoundedNumberOption(
    5959      "sigma_max",
    60       "Maximal value of centering parameter.",
     60      "Maximum value of the centering parameter.",
    6161      0.0, true, 1e2);
    6262    roptions->AddStringOption4(
     
    7070    roptions->AddStringOption4(
    7171      "quality_function_centrality",
    72       "Determines whether a penalty term for centrality is included quality function.",
     72      "The penalty term for centrality that is included quality function.",
    7373      "none",
    7474      "none", "no penalty term is added",
     
    7676      "reciprocal", "complementarity * the reciprocal of the centrality measure",
    7777      "cubed-reciprocal", "complementarity * the reciprocal of the centrality measure cubed",
    78       "This determines whether a term penalizing deviation from centrality "
    79       "with respect to complementarity is added the quality function.  The "
     78      "This determines whether a term is added to the quality function to "
     79      "penalizing deviation from centrality with respect to complementarity.  The "
    8080      "complementarity measure here is the xi in the Loqo update rule.");
    8181    roptions->AddStringOption2(
    8282      "quality_function_balancing_term",
    83       "Determines whether a balancing term for centrality is included in quality function.",
     83      "The balancing term included in the quality function for centrality.",
    8484      "none",
    8585      "none", "no balancing term is added",
    8686      "cubic", "Max(0,Max(dual_ing,primal_inf)-compl)^3",
    87       "This determines whether a term penalizing stuations there the "
    88       "complementality is much smaller than dual and primal "
    89       "infeasibilities is added to the quality function.");
     87      "This determines whether a term is added to the quality function that"
     88      "penalizing situations where the complementality is much smaller "
     89      "than dual and primal infeasibilities.");
    9090    roptions->AddLowerBoundedIntegerOption(
    9191      "max_bisection_steps",
    92       "Maximal number of search steps during direct search procedure determining optimal centering parameter.",
     92      "Maximum number of search steps during direct search procedure "
     93      "determining the optimal centering parameter.",
    9394      0, 8);
    9495    roptions->AddBoundedNumberOption(
    9596      "bisection_tol",
    96       "Tolerance for the bisection search procedure determining optimal centering parameter.",
     97      "Tolerance for the bisection search procedure determining "
     98      "the optimal centering parameter.",
    9799      0.0, true, 1.0, true,
    98100      1e-3);
  • branches/dev/Algorithm/IpRestoFilterConvCheck.cpp

    r465 r490  
    4343    roptions->AddBoundedNumberOption(
    4444      "required_infeasibility_reduction",
    45       "Required reduction of infeasibility before restoration phase is left.",
     45      "Required reduction of infeasibility before leaving restoration phase.",
    4646      0.0, false, 1.0, true,
    4747      0.9,
  • branches/dev/Algorithm/IpRestoMinC_1Nrm.cpp

    r488 r490  
    3636    roptions->AddLowerBoundedNumberOption(
    3737      "bound_mult_reset_threshold",
    38       "Threshold for resetting bound multipliers after restoration phase.",
     38      "Threshold for resetting bound multipliers after the restoration phase.",
    3939      0.0, false,
    4040      1e3,
  • branches/dev/Algorithm/IpWarmStartIterateInitializer.cpp

    r465 r490  
    4242    roptions->AddLowerBoundedNumberOption("warm_start_mult_bound_push", "same as mult_bound_push for the regular initializer",
    4343                                          0.0, true, 1e-3);
    44     roptions->AddNumberOption("warm_start_mult_init_max", "(No Range?) max initial value for the equality multipliers",
     44    roptions->AddNumberOption("warm_start_mult_init_max", "Maximum initial value for the equality multipliers",
    4545                              1e6);
    46     roptions->AddNumberOption("warm_start_target_mu", "(No range?) - default value in code was 0e-3 ???",
     46    roptions->AddNumberOption("warm_start_target_mu", "(No range?) default value in code was 0e-3 ???",
    4747                              0e-3);
    4848  }
  • branches/dev/Common/IpRegOptions.cpp

    r478 r490  
    103103    std::string latex_name;
    104104    MakeValidLatexString(name_, latex_name);
    105     jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
    106                  "\\paragraph{%s} $\\;$ \\\\\n",  latex_name.c_str());
    107 
    108105    std::string latex_desc;
    109106    MakeValidLatexString(short_description_, latex_desc);
    110     jnlst.PrintStringOverLines(J_SUMMARY, J_DOCUMENTATION, 0, 50,
    111                                latex_desc.c_str());
     107    jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
     108                 "\\paragraph{%s:} %s $\\;$ \\\\\n", 
     109                 latex_name.c_str(),
     110                 latex_desc.c_str());
     111
     112    //    Index length = name_.length() + short_description_.length();
     113    //    DBG_ASSERT(length <= 80);
     114    //    jnlst.PrintStringOverLines(J_SUMMARY, J_DOCUMENTATION, 0, 50,
     115    //                               latex_desc.c_str());
     116
    112117    if (long_description_ != "") {
    113118      latex_desc = "";
     
    121126      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
    122127                     " The valid range for this real option is \n$");
     128      std::string buff;
    123129      if (has_lower_) {
    124         jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%g", lower_);
     130        buff = MakeValidLatexNumber(lower_);
     131        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%s", buff.c_str());
    125132      }
    126133      else {
     
    145152
    146153      if (has_upper_) {
    147         jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%g", upper_);
     154        buff = MakeValidLatexNumber(upper_);
     155        jnlst.Printf(J_SUMMARY, J_DOCUMENTATION, "%s", buff.c_str());
    148156      }
    149157      else {
     
    151159      }
    152160
     161      buff = MakeValidLatexNumber(default_number_);
    153162      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
    154                    "$\nand its default value is %g.\n\n", default_number_);
     163                   "$\nand its default value is $%s$.\n\n", buff.c_str());
    155164     
    156165    }
     
    175184
    176185      jnlst.Printf(J_SUMMARY, J_DOCUMENTATION,
    177                    "$\nand its default value is %d.\n\n",
     186                   "$\nand its default value is $%d$.\n\n",
    178187                   (Index)default_number_);
    179188    }
     
    214223      }
    215224    }
     225  }
     226
     227  std::string RegisteredOption::MakeValidLatexNumber(Number value) const
     228  {
     229    char buffer[256];
     230    sprintf(buffer, "%g", value);
     231    std::string source = buffer;
     232    std::string dest;
     233
     234    std::string::iterator c;
     235    bool found_e = false;
     236    for (c=source.begin(); c!=source.end(); c++) {
     237      if (*c == 'e') {
     238        found_e = true;
     239        dest.append(" \\cdot 10^{");
     240      }
     241      else {
     242        dest.push_back(*c);
     243      }
     244    }
     245    if (found_e) {
     246      dest.append("}");
     247    }
     248
     249    return dest;
    216250  }
    217251
     
    791825  }
    792826
    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;
     827  void RegisteredOptions::OutputLatexOptionDocumentation(
     828        const Journalist& jnlst,
     829        std::list<std::string>& options_to_print)
     830  {
     831   
     832    if (!options_to_print.empty()) {
     833      std::list<std::string>::iterator coption;
     834      for (coption = options_to_print.begin();
     835           coption != options_to_print.end();
     836           coption++) {
     837        //      std::map <std::string, SmartPtr<RegisteredOption> >::iterator option;
     838        SmartPtr<RegisteredOption> option = registered_options_[*coption];
     839        DBG_ASSERT(IsValid(option));
     840        option->OutputLatexDescription(jnlst);
     841      }
     842    }
     843    else {
    799844      std::map <std::string, SmartPtr<RegisteredOption> >::iterator option;
    800845      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 
     846           option != registered_options_.end();
     847           option++) {
     848        option->second->OutputLatexDescription(jnlst);
     849      }
     850    }
     851  }
    814852} // namespace Ipopt
  • branches/dev/Common/IpRegOptions.hpp

    r478 r490  
    357357
    358358    void MakeValidLatexString(std::string source, std::string& dest) const;
     359    std::string MakeValidLatexNumber(Number value) const;
    359360
    360361    /** Compare two strings and return true if they are equal (case
     
    413414      current_registering_category_ = registering_category;
    414415    }
     416   
     417    /** retrieve the value of the current registering category */
     418    std::string RegisteringCategory()
     419    {
     420      return current_registering_category_;
     421    }
     422
    415423    /** Add a Number option (with no restrictions) */
    416424    void AddNumberOption(const std::string& name,
  • branches/dev/Docs/documentation.tex

    r483 r490  
    19831983
    19841984
    1985 
    1986 
    1987 
    1988 \begin{verbatim}
    1989 
    1990 \paragraph{tol} $\;$ \\
    1991 The desired relative convergence tolerance. The algorithm terminates
    1992 successfully, if the (scaled) NLP error becomes smaller than this
    1993 value, and if the (absolute) criteria according to "dual\_inf\_tol",
    1994 "primal\_inf\_tol", and "cmpl\_inf\_tol" are met.  (This is
    1995 epsilon\_tol in Eqn. (6) in implementation paper). Other
    1996 algorithmic features rely on this quantity. The valid range is $0 <
    1997 tol < +{\tt inf}$ and the default value is $1 \cdot 10^{-8}$.
    1998 
    1999 \paragraph{max\_iter} $\;$ \\
    2000 The maximum number of iterations allowed.  The algorithm terminates with an error
    2001 message if the number of iterations exceeds this number. Also used
    2002 in the convergence check for the restoratin phase.
    2003 The valid range for this option is $0 \le
    2004 {\tt max_iter} < +{\tt inf}$ and the default value is $3000$.
    2005 
    2006 
    2007 \paragraph{dual\_inf\_tol} $\;$ \\
    2008 Absolute tolerance on
    2009 the dual infesaibility. Successful termination requires that the
    2010 (unscaled) dual infeasibility is less than this threshold. The valid
    2011 range is $0 < {\tt dual\_inf\_tol} < +{\tt inf}$ and the default value
    2012 is $1\cdot 10^{-4}$.
    2013 
    2014 
    2015 * constr_viol_tol                        0 <  (     0.0001) <  +inf     
    2016    Desired threshold for the constraint violation.
    2017      Absolute tolerance on the constraint violation. Successful termination
    2018      requires that the (unscaled) constraint violation is less than this
    2019      threshold.
    2020 
    2021 * compl_inf_tol                          0 <  (     0.0001) <  +inf     
    2022    Desired threshold for the complementarity conditions.
    2023      Absolute tolerance on the complementarity. Successful termination
    2024      requires that the (unscaled) complementarity is less than this threshold.
    2025 
    2026 * acceptable_tol                         0 <  (      1e-06) <  +inf     
    2027    Acceptable convergence tolerance (relative).
    2028      Determines which (scaled) overall optimality error is considered to be
    2029      acceptable. If the algorithm encounters "acceptable_iter" iterations in a
    2030      row that are considered "acceptable", it will terminate before the
    2031      desired convergence tolerance ("tol", "dual_inf_tol", etc) is met.
    2032 
    2033 * acceptable_dual_inf_tol                0 <  (       0.01) <  +inf     
    2034    Acceptance threshold for the dual infeasibility.
    2035      Absolute tolerance on the dual infesaibility. Acceptable termination
    2036      requires that the (unscaled) dual infeasibility is less than this
    2037      threshold.
    2038 
    2039 * acceptable_constr_viol_tol             0 <  (       0.01) <  +inf     
    2040    Acceptance threshold for the constraint violation.
    2041      Absolute tolerance on the constraint violation. Acceptable termination
    2042      requires that the (unscaled) constraint violation is less than this
    2043      threshold.
    2044 
    2045 * acceptable_compl_inf_tol               0 <  (       0.01) <  +inf     
    2046    Acceptance threshold for the complementarity conditions.
    2047      Absolute tolerance on the complementarity. Acceptable termination
    2048      requires that the (unscaled) complementarity is less than this threshold.
    2049 
    2050 ### NLP Scaling ###
    2051 
    2052 * nlp_scaling_method            ("gradient_based")
    2053    Select the technique used for scaling the NLP
    2054      Selects the technique used for scaling the problem before it is solved.
    2055      For user-scaling, the parameters come from the NLP. If you are using
    2056      AMPL, they can be specified through suffixes (scaling_factor)
    2057    Possible values:
    2058     - none                    [no problem scaling will be performed]
    2059     - user_scaling            [scaling parameters will come from the user]
    2060     - gradient_based          [scale the problem so the maximum gradient at
    2061                                the starting point is scaling_max_gradient]
    2062 
    2063 * obj_scaling_factor                  -inf <  (          1) <  +inf     
    2064    Scaling factor for the objective function.
    2065      This option allows to set a scaling factor for the objective function
    2066      that is used to scale the problem that is seen internally by Ipopt. If
    2067      additional scaling parameters are computed (e.g. user-scaling or
    2068      gradient-based), this factor is multiplied in addition. If this value is
    2069      chosen to be negative, Ipopt will maximize the objective function.
    2070 
    2071 * nlp_scaling_max_gradient               0 <  (        100) <  +inf     
    2072    maximum gradient after scaling
    2073      This is the gradient scaling cut-off. If the maximum gradient is above
    2074      this value, then gradient based scaling will be performed. Scaling
    2075      parameters will scale the maximum gradient back to this value. Note: This
    2076      option is only used if "nlp_scaling_method" is chosen as "gradient_based".
    2077 
    2078 ### Mu Update ###
    2079 
    2080 * mu_strategy                   ("monotone")
    2081    Update strategy for barrier parameter.
    2082      Determines which barrier parameter strategy is to be used.
    2083    Possible values:
    2084     - monotone                [use the monotone (Fiacco-McCormick) strategy]
    2085     - adaptive                [use the adaptive update strategy]
    2086 
    2087 * mu_oracle                     ("probing")
    2088    Oracle for a new barrier parameter in the adaptive strategy
    2089      Determines how a new barrier parameter is computed in each "free-mode"
    2090      iteration of the adaptive barrier parameter strategy. (Only considered if
    2091      "adaptive" is selected for option "mu_strategy".
    2092    Possible values:
    2093     - probing                 [Mehrotra's probing heuristic]
    2094     - loqo                    [LOQO's centrality rule]
    2095     - quality_function        [minimize a quality function]
    2096 
    2097 * mu_init                                0 <  (        0.1) <  +inf     
    2098    Initial value for the barrier parameter.
    2099      This option determines the initial value for the barrier parameter (mu).
    2100      It is only relevant in the monotone, Fiacco-McCormick version of the
    2101      algorithm., i.e., if "mu_strategy" is chosen as "monotone"
    2102 
    2103 ### Line Search ###
    2104 
    2105 * max_soc                                0 <= (          4) <  +inf     
    2106    Maximal number of second order correction trial steps.
    2107      Determines the maximal number of second order correction trial steps that
    2108      should be performed.  Choosing 0 disables the second order corrections.
    2109      (This is p^{max} of Step A-5.9 of Algorithm A in implementation paper.)
    2110 
    2111 * corrector_type                ("none")
    2112    Type of corrector steps.
    2113      Determines what kind of corrector steps should be tried.
    2114    Possible values:
    2115     - none                    [no corrector]
    2116     - affine                  [corrector step towards mu=0]
    2117     - primal-dual             [corrector step towards current mu]
    2118 
    2119 * alpha_for_y                   ("primal")
    2120    Step size for constraint multipliers.
    2121      Determines which step size (alpha_y) should be used to update the
    2122      constraint multipliers.
    2123    Possible values:
    2124     - primal                  [use primal step size]
    2125     - bound_mult              [use step size for the bound multipliers]
    2126     - min                     [use the min of primal and bound multipliers]
    2127     - max                     [use the max of primal and bound multipliers]
    2128     - full                    [take a full step of size one]
    2129     - min_dual_infeas         [choose step size minimizing new dual
    2130                                infeasibility]
    2131     - safe_min_dual_infeas    [like "min_dual_infeas", but safeguarded by
    2132                                "min" and "max"]
    2133 * expect_infeasible_problem     ("no")
    2134    Enable heuristics to quickly detect an infeasible problem.
    2135      This options is meant to activate heuristics that may speed up the
    2136      infeasibility determination if you expect the problem to be infeasible.
    2137      In the filter line search procedure, the restoration phase is called more
    2138      qucikly than usually, and more reduction in the constraint violation is
    2139      enforced. If the problem is square, this is enabled automatically.
    2140    Possible values:
    2141     - no                      [the problem probably be feasible]
    2142     - yes                     [the problem has a good chance to be infeasible]
    2143 
    2144 ### Initialization ###
    2145 
    2146 * bound_push                             0 <  (       0.01) <  +inf     
    2147    Desired minimal absolute distance of initial point to bound
    2148      Determines (together with "bound_frac") by how much the initial point
    2149      might have to be modified in order to be sufficiently inside the bounds.
    2150 
    2151 * bound_frac                             0 <  (       0.01) <= 0.5       
    2152    Desired minimal relative distance of initial point to bound
    2153      Determines (together with "bound_push") by how much the initial point
    2154      might have to be modified in order to be sufficiently inside the bounds.
    2155 
    2156 * constr_mult_init_max                   0 <= (       1000) <  +inf     
    2157    Maximal allowed least-square guess of constraint multipliers.
    2158      Determines how large the initial least-square guesses of the contraint
    2159      multipliers (in max-norm) are allowed to be. If the guess is larger than
    2160      this value, it is discarded and all constraint multipliers are set to
    2161      zero.  This options is also used in the classes
    2162      "RestoIterateInitializer".  By default, "resto.constr_mult_init_max" (the
    2163      one used in RestoIterateInitializer) is set to zero.
    2164 
    2165 * bound_mult_init_val                    0 <  (          1) <  +inf     
    2166    Initial value for the bound multipliers
    2167      All dual variables corresponding to bound constraints are initialized to
    2168      this value.
    2169 
    2170 ### Step Calculation ###
    2171 
    2172 * min_refinement_steps                   0 <= (          1) <  +inf     
    2173    Minimum number of iterative refinement steps per linear system solve.
    2174      Iterative refinement (on the unsymmetric full system) is performed for
    2175      each right hand side.  This option determines the minimal number of
    2176      iterative refinements, i.e., by setting it to 1 at least one iterative
    2177      refinement step per right hand side is enforce.
    2178 
    2179 * max_refinement_steps                   0 <= (         10) <  +inf     
    2180    Maximal number of iterative refinement steps per linear system solve.
    2181      Iterative refinement (on the unsymmetric full system) is performed for
    2182      each right hand side.  This option determines the maximal number of
    2183      iterative refinements.
    2184 
    2185 
    2186 ### NLP ###
    2187 
    2188 * bound_relax_factor                     0 <= (      1e-08) <  +inf     
    2189    Factor for initial relaxation of the bounds.
    2190      Before start of the optimization, the bounds given by the user are
    2191      relaxed.  This option determines the factor by how much.  If it is set to
    2192      zero, then this option is disabled.  (See Eqn.(35) in implmentation
    2193      paper.)
    2194 
    2195 
    2196 ### MA27 Linear Solver ###
    2197 
    2198 * pivtol                                 0 <  (      1e-08) <  1         
    2199    pivot tolerance for the linear solver. smaller number - pivot for sparsity,
    2200    larger number - pivot for stability
    2201 
    2202 * pivtolmax                              0 <  (     0.0001) <  1         
    2203    maximum pivot tolerance. IPOPT may increase pivtol as high as pivtolmax to
    2204    get a more accurate solution to the linear system
    2205 \end{verbatim}
     1985\paragraph{print\_level:} Output verbosity level. $\;$ \\
     1986 Sets the default verbosity level for console
     1987output. The larger this value the more detailed
     1988is the output. The valid range for this integer option is
     1989$0 \le {\tt print\_level } \le 10$
     1990and its default value is $3$.
     1991
     1992
     1993\paragraph{pivtol:} Pivot tolerance for the linear solver. $\;$ \\
     1994 A smaller number pivots for sparsity, a larger
     1995number pivots for stability. The valid range for this real option is
     1996$0 <  {\tt pivtol } <  1$
     1997and its default value is $1 \cdot 10^{-08}$.
     1998
     1999
     2000\paragraph{pivtolmax:} Maximum pivot tolerance. $\;$ \\
     2001 IPOPT may increase pivtol as high as pivtolmax to
     2002get a more accurate solution to the linear system The valid range for this real option is
     2003$0 <  {\tt pivtolmax } <  1$
     2004and its default value is $0.0001$.
     2005
     2006
     2007\paragraph{tol:} Desired convergence tolerance (relative). $\;$ \\
     2008 Determines the convergence tolerance for the
     2009algorithm.  The algorithm terminates
     2010successfully, if the (scaled) NLP error becomes
     2011smaller than this value, and if the (absolute)
     2012criteria according to "dual\_inf\_tol",
     2013"primal\_inf\_tol", and "cmpl\_inf\_tol" are met.
     2014 (This is epsilon\_tol in Eqn. (6) in
     2015implementation paper). Note, some other
     2016algorithmic features also use this quantity. The valid range for this real option is
     2017$0 <  {\tt tol } <  {\tt +inf}$
     2018and its default value is $1 \cdot 10^{-08}$.
     2019
     2020
     2021\paragraph{compl\_inf\_tol:} Desired threshold for the complementarity conditions. $\;$ \\
     2022 Absolute tolerance on the complementarity.
     2023Successful termination requires that the
     2024(unscaled) complementarity is less than this
     2025threshold. The valid range for this real option is
     2026$0 <  {\tt compl\_inf\_tol } <  {\tt +inf}$
     2027and its default value is $0.0001$.
     2028
     2029
     2030\paragraph{dual\_inf\_tol:} Desired threshold for the dual infeasibility. $\;$ \\
     2031 Absolute tolerance on the dual infesaibility.
     2032Successful termination requires that the
     2033(unscaled) dual infeasibility is less than this
     2034threshold. The valid range for this real option is
     2035$0 <  {\tt dual\_inf\_tol } <  {\tt +inf}$
     2036and its default value is $0.0001$.
     2037
     2038
     2039\paragraph{constr\_mult\_init\_max:} Maximum allowed least-square guess of constraint multipliers. $\;$ \\
     2040 Determines how large the initial least-square
     2041guesses of the contraint multipliers are allowed
     2042to be (in max-norm). If the guess is larger than
     2043this value, it is discarded and all constraint
     2044multipliers are set to zero.  This options is
     2045also used when initializing the restoration
     2046phase. By default,
     2047"resto.constr\_mult\_init\_max" (the one used in
     2048RestoIterateInitializer) is set to zero. The valid range for this real option is
     2049$0 \le {\tt constr\_mult\_init\_max } <  {\tt +inf}$
     2050and its default value is $1000$.
     2051
     2052
     2053\paragraph{constr\_viol\_tol:} Desired threshold for the constraint violation. $\;$ \\
     2054 Absolute tolerance on the constraint violation.
     2055Successful termination requires that the
     2056(unscaled) constraint violation is less than this
     2057threshold. The valid range for this real option is
     2058$0 <  {\tt constr\_viol\_tol } <  {\tt +inf}$
     2059and its default value is $0.0001$.
     2060
     2061
     2062\paragraph{mu\_strategy:} Update strategy for barrier parameter. $\;$ \\
     2063 Determines which barrier parameter update
     2064strategy is to be used.\\
     2065Possible values:
     2066\begin{itemize}
     2067   \item monotone: use the monotone (Fiacco-McCormick) strategy
     2068   \item adaptive: use the adaptive update strategy
     2069\end{itemize}
     2070
     2071\paragraph{mu\_init:} Initial value for the barrier parameter. $\;$ \\
     2072 This option determines the initial value for the
     2073barrier parameter (mu).  It is only relevant in
     2074the monotone, Fiacco-McCormick version of the
     2075algorithm. (i.e., if "mu\_strategy" is chosen as
     2076"monotone") The valid range for this real option is
     2077$0 <  {\tt mu\_init } <  {\tt +inf}$
     2078and its default value is $0.1$.
     2079
     2080
     2081\paragraph{mu\_oracle:} Oracle for a new barrier parameter in the adaptive strategy $\;$ \\
     2082 Determines how a new barrier parameter is
     2083computed in each "free-mode" iteration of the
     2084adaptive barrier parameter strategy. (Only
     2085considered if "adaptive" is selected for option
     2086"mu\_strategy".\\
     2087Possible values:
     2088\begin{itemize}
     2089   \item probing: Mehrotra's probing heuristic
     2090   \item loqo: LOQO's centrality rule
     2091   \item quality\_function: minimize a quality function
     2092\end{itemize}
     2093
     2094\paragraph{corrector\_type:} The type of corrector steps that should be taken. $\;$ \\
     2095 If "mu\_strategy" is "adaptive", this option
     2096determines what kind of corrector steps should be
     2097tried.\\
     2098Possible values:
     2099\begin{itemize}
     2100   \item none: no corrector
     2101   \item affine: corrector step towards mu=0
     2102   \item primal-dual: corrector step towards current mu
     2103\end{itemize}
     2104
     2105\paragraph{obj\_scaling\_factor:} Scaling factor for the objective function. $\;$ \\
     2106 This option sets a scaling factor for the
     2107objective function. The scaling is seen
     2108internally by Ipopt but the unscaled objective is
     2109reported in the console output. If additional
     2110scaling parameters are computed (e.g.
     2111user-scaling or gradient-based), both factors are
     2112multiplied. If this value is chosen to be
     2113negative, Ipopt will maximize the objective
     2114function instead of minimizing it. The valid range for this real option is
     2115${\tt -inf} <  {\tt obj\_scaling\_factor } <  {\tt +inf}$
     2116and its default value is $1$.
     2117
     2118
     2119\paragraph{nlp\_scaling\_method:} Select the technique used for scaling the NLP $\;$ \\
     2120 Selects the technique used for scaling the
     2121problem before it is solved. For user-scaling,
     2122the parameters come from the NLP. If you are
     2123using AMPL, they can be specified through
     2124suffixes (scaling\_factor)\\
     2125Possible values:
     2126\begin{itemize}
     2127   \item none: no problem scaling will be performed
     2128   \item user\_scaling: scaling parameters will come from the user
     2129   \item gradient\_based: scale the problem so the maximum gradient at
     2130the starting point is scaling\_max\_gradient
     2131\end{itemize}
     2132
     2133\paragraph{nlp\_scaling\_max\_gradient:} Maximum gradient after scaling. $\;$ \\
     2134 This is the gradient scaling cut-off. If the
     2135maximum gradient is above this value, then
     2136gradient based scaling will be performed. Scaling
     2137parameters are calculated to scale the maximum
     2138gradient back to this value. Note: This option is
     2139only used if "nlp\_scaling\_method" is chosen as
     2140"gradient\_based". The valid range for this real option is
     2141$0 <  {\tt nlp\_scaling\_max\_gradient } <  {\tt +inf}$
     2142and its default value is $100$.
     2143
     2144
     2145\paragraph{bound\_frac:} Desired minimum relative distance from the initial point to bound $\;$ \\
     2146 Determines how much the initial point might have
     2147to be modified in order to be sufficiently inside
     2148the bounds (together with "bound\_push"). The valid range for this real option is
     2149$0 <  {\tt bound\_frac } \le 0.5$
     2150and its default value is $0.01$.
     2151
     2152
     2153\paragraph{bound\_mult\_init\_val:} Initial value for the bound multipliers $\;$ \\
     2154 All dual variables corresponding to bound
     2155constraints are initialized to this value. The valid range for this real option is
     2156$0 <  {\tt bound\_mult\_init\_val } <  {\tt +inf}$
     2157and its default value is $1$.
     2158
     2159
     2160\paragraph{bound\_push:} Desired minimum absolute distance from the initial point to bound $\;$ \\
     2161 Determines how much the initial point might have
     2162to be modified in order to be sufficiently inside
     2163the bounds (together with "bound\_frac"). The valid range for this real option is
     2164$0 <  {\tt bound\_push } <  {\tt +inf}$
     2165and its default value is $0.01$.
     2166
     2167
     2168\paragraph{bound\_relax\_factor:} Factor for initial relaxation of the bounds. $\;$ \\
     2169 Before start of the optimization, the bounds
     2170given by the user are relaxed.  This option sets
     2171the factor for this relaxation.  If it is set to
     2172zero, then then bounds relaxation is disabled.
     2173(See Eqn.(35) in implmentation paper.) The valid range for this real option is
     2174$0 \le {\tt bound\_relax\_factor } <  {\tt +inf}$
     2175and its default value is $1 \cdot 10^{-08}$.
     2176
     2177
     2178\paragraph{acceptable\_compl\_inf\_tol:} Acceptance threshold for the complementarity conditions. $\;$ \\
     2179 Absolute tolerance on the complementarity.
     2180Acceptable termination requires that the
     2181(unscaled) complementarity is less than this
     2182threshold. The valid range for this real option is
     2183$0 <  {\tt acceptable\_compl\_inf\_tol } <  {\tt +inf}$
     2184and its default value is $0.01$.
     2185
     2186
     2187\paragraph{acceptable\_constr\_viol\_tol:} Acceptance threshold for the constraint violation. $\;$ \\
     2188 Absolute tolerance on the constraint violation.
     2189Acceptable termination requires that the
     2190(unscaled) constraint violation is less than this
     2191threshold. The valid range for this real option is
     2192$0 <  {\tt acceptable\_constr\_viol\_tol } <  {\tt +inf}$
     2193and its default value is $0.01$.
     2194
     2195
     2196\paragraph{acceptable\_dual\_inf\_tol:} Acceptance threshold for the dual infeasibility. $\;$ \\
     2197 Absolute tolerance on the dual infesaibility.
     2198Acceptable termination requires that the
     2199(unscaled) dual infeasibility is less than this
     2200threshold. The valid range for this real option is
     2201$0 <  {\tt acceptable\_dual\_inf\_tol } <  {\tt +inf}$
     2202and its default value is $0.01$.
     2203
     2204
     2205\paragraph{acceptable\_tol:} Acceptable convergence tolerance (relative). $\;$ \\
     2206 Determines which (scaled) overall optimality
     2207error is considered to be acceptable. If the
     2208algorithm encounters "acceptable\_iter"
     2209iterations in a row that are considered
     2210"acceptable", it will terminate before the
     2211desired convergence tolerance ("tol",
     2212"dual\_inf\_tol", etc) is met. The valid range for this real option is
     2213$0 <  {\tt acceptable\_tol } <  {\tt +inf}$
     2214and its default value is $1 \cdot 10^{-06}$.
     2215
     2216
     2217\paragraph{alpha\_for\_y:} Method to determine the step size for constraint multipliers. $\;$ \\
     2218 This option determines how the step size
     2219(alpha\_y) will be calculated when updating the
     2220constraint multipliers.\\
     2221Possible values:
     2222\begin{itemize}
     2223   \item primal: use primal step size
     2224   \item bound\_mult: use step size for the bound multipliers
     2225   \item min: use the min of primal and bound multipliers
     2226   \item max: use the max of primal and bound multipliers
     2227   \item full: take a full step of size one
     2228   \item min\_dual\_infeas: choose step size minimizing new dual
     2229infeasibility
     2230   \item safe\_min\_dual\_infeas: like "min\_dual\_infeas", but safeguarded by
     2231"min" and "max"
     2232\end{itemize}
     2233
     2234\paragraph{expect\_infeasible\_problem:} Enable heuristics to quickly detect an infeasible problem. $\;$ \\
     2235 This options is meant to activate heuristics that
     2236may speed up the infeasibility determination if
     2237you expect the problem to be infeasible.  In the
     2238filter line search procedure, the restoration
     2239phase is called more qucikly than usually, and
     2240more reduction in the constraint violation is
     2241enforced. If the problem is square, this is
     2242enabled automatically.\\
     2243Possible values:
     2244\begin{itemize}
     2245   \item no: the problem probably be feasible
     2246   \item yes: the problem has a good chance to be infeasible
     2247\end{itemize}
     2248
     2249\paragraph{max\_iter:} Maximum number of iterations. $\;$ \\
     2250 The algorithm terminates with an error message if
     2251the number of iterations exceeded this number.
     2252This option is also used in the restoration phase. The valid range for this integer option is
     2253$0 \le {\tt max\_iter } <  {\tt +inf}$
     2254and its default value is $3000$.
     2255
     2256
     2257\paragraph{max\_refinement\_steps:} Maximum number of iterative refinement steps per linear system solve. $\;$ \\
     2258 Iterative refinement (on the full unsymmetric
     2259system) is performed for each right hand side.
     2260This option determines the maximum number of
     2261iterative refinement steps. The valid range for this integer option is
     2262$0 \le {\tt max\_refinement\_steps } <  {\tt +inf}$
     2263and its default value is $10$.
     2264
     2265
     2266\paragraph{max\_soc:} Maximum number of second order correction trial steps at each iteration. $\;$ \\
     2267 Choosing 0 disables the second order corrections.
     2268(This is p\^{max} of Step A-5.9 of Algorithm A in
     2269implementation paper.) The valid range for this integer option is
     2270$0 \le {\tt max\_soc } <  {\tt +inf}$
     2271and its default value is $4$.
     2272
     2273
     2274\paragraph{min\_refinement\_steps:} Minimum number of iterative refinement steps per linear system solve. $\;$ \\
     2275 Iterative refinement (on the full unsymmetric
     2276system) is performed for each right hand side.
     2277This option determines the minimum number of
     2278iterative refinements (i.e. at least
     2279"min\_refinement\_steps" iterative refinement
     2280steps are enforced per right hand side.) The valid range for this integer option is
     2281$0 \le {\tt min\_refinement\_steps } <  {\tt +inf}$
     2282and its default value is $1$.
     2283
     2284
     2285\paragraph{output\_file:} File name of desired output file (leave unset for no file output) $\;$ \\
     2286 NOTE: This option only works when read from
     2287PARAMS.DAT options file! An output file with this
     2288name will be written (leave unset for no file
     2289output).  The verbosity level is by default,
     2290"print\_level", or but can be overridden with
     2291"file\_print\_level".\\
     2292Possible values:
     2293\begin{itemize}
     2294   \item *: Any acceptable standard file name
     2295\end{itemize}
     2296
     2297\paragraph{file\_print\_level:} Verbosity level for output file. $\;$ \\
     2298 NOTE: This option only works when read from
     2299PARAMS.DAT options file! Determines the verbosity
     2300level for the file specified by "output\_file".
     2301By defauly it is the same as "print\_level". The valid range for this integer option is
     2302$0 \le {\tt file\_print\_level } \le 10$
     2303and its default value is $3$.
    22062304
    22072305\subsection{Detailed Installation Information}\label{ExpertInstall}
  • branches/dev/Interfaces/IpIpoptApplication.cpp

    r478 r490  
    116116                             print_options_documentation, "");
    117117      if (print_options_documentation) {
    118         std::list<std::string> categories;
    119         categories.push_back("Output");
    120         categories.push_back("Main Algorithm");
    121         categories.push_back("Convergence");
    122         categories.push_back("NLP Scaling");
    123         categories.push_back("Mu Update");
    124         categories.push_back("Line Search");
    125         categories.push_back("Initialization");
    126         categories.push_back("Linear Solver");
    127         categories.push_back("Step Calculation");
    128         categories.push_back("Restoration");
    129         categories.push_back("NLP");
    130         categories.push_back("Warm Start");
    131         categories.push_back("MA27 Linear Solver");
    132         categories.push_back("Uncategorized");
    133118        bool latex;
    134119        options_->GetBoolValue("print_options_latex_mode", latex, "");
    135120        if (latex) {
    136           reg_options->OutputLatexOptionDocumentation(*jnlst_, categories);
     121          std::list<std::string> options_to_print;
     122          options_to_print.push_back("print_level");
     123          options_to_print.push_back("pivtol");
     124          options_to_print.push_back("pivtolmax");
     125          options_to_print.push_back("tol");
     126          options_to_print.push_back("compl_inf_tol");
     127          options_to_print.push_back("dual_inf_tol");
     128          options_to_print.push_back("constr_mult_init_max");
     129          options_to_print.push_back("constr_viol_tol");
     130          options_to_print.push_back("mu_strategy");
     131          options_to_print.push_back("mu_init");
     132          options_to_print.push_back("mu_oracle");
     133          options_to_print.push_back("corrector_type");
     134          options_to_print.push_back("obj_scaling_factor");
     135          options_to_print.push_back("nlp_scaling_method");
     136          options_to_print.push_back("nlp_scaling_max_gradient");
     137          options_to_print.push_back("bound_frac");
     138          options_to_print.push_back("bound_mult_init_val");
     139          options_to_print.push_back("bound_push");
     140          options_to_print.push_back("bound_relax_factor");
     141          options_to_print.push_back("acceptable_compl_inf_tol");
     142          options_to_print.push_back("acceptable_constr_viol_tol");
     143          options_to_print.push_back("acceptable_dual_inf_tol");
     144          options_to_print.push_back("acceptable_tol");
     145          options_to_print.push_back("alpha_for_y");
     146          options_to_print.push_back("expect_infeasible_problem");
     147          options_to_print.push_back("max_iter");
     148          options_to_print.push_back("max_refinement_steps");
     149          options_to_print.push_back("max_soc");
     150          options_to_print.push_back("min_refinement_steps");
     151          options_to_print.push_back("output_file");
     152          options_to_print.push_back("file_print_level");
     153
     154          reg_options->OutputLatexOptionDocumentation(*jnlst_, options_to_print);
    137155        }
    138156        else {
     157          std::list<std::string> categories;
     158          categories.push_back("Output");
     159          categories.push_back("Main Algorithm");
     160          categories.push_back("Convergence");
     161          categories.push_back("NLP Scaling");
     162          categories.push_back("Mu Update");
     163          categories.push_back("Line Search");
     164          categories.push_back("Initialization");
     165          categories.push_back("Linear Solver");
     166          categories.push_back("Step Calculation");
     167          categories.push_back("Restoration");
     168          categories.push_back("NLP");
     169          categories.push_back("Warm Start");
     170          categories.push_back("MA27 Linear Solver");
     171          categories.push_back("Uncategorized");
    139172          reg_options->OutputOptionDocumentation(*jnlst_, categories);
    140173        }
     
    174207      "Output verbosity level.",
    175208      0, J_LAST_LEVEL-1, J_SUMMARY,
    176       "Sets the default verbosity level, in particular to screen. The "
     209      "Sets the default verbosity level for console output. The "
    177210      "larger this value the more detailed is the output.");
    178211
    179212    roptions->AddStringOption1(
    180213      "output_file",
    181       "File name of an output file (leave unset for no file output)",
     214      "File name of desired output file (leave unset for no file output)",
    182215      "",
    183216      "*", "Any acceptable standard file name",
    184217      "NOTE: This option only works when read from PARAMS.DAT options file! "
    185218      "An output file with this name will be written (leave unset for no "
    186       "file output).  The verbosity level is either \"print_level\", or "
    187       "\"file_print_level\" if that is given.");
     219      "file output).  The verbosity level is by default, \"print_level\", or "
     220      "but can be overridden with \"file_print_level\".");
    188221    roptions->AddBoundedIntegerOption(
    189222      "file_print_level",
     
    195228    roptions->AddStringOption2(
    196229      "print_options_documentation",
    197       "Switch to print list all algorithmic options",
     230      "Switch to print all algorithmic options",
    198231      "no",
    199232      "no", "don't print list",
Note: See TracChangeset for help on using the changeset viewer.