Documentation update
1. Make the documentation build with Sphinx 1.2
2. Update the documentation for IterationSummary to
be Sphinx friendly.
Change-Id: I93c374987bc0597e854fbcb5a4a25dd2058607f5
diff --git a/docs/source/_themes/armstrong/globaltoc.html b/docs/source/_themes/armstrong/globaltoc.html
index 20d8641..68d82fa 100644
--- a/docs/source/_themes/armstrong/globaltoc.html
+++ b/docs/source/_themes/armstrong/globaltoc.html
@@ -8,4 +8,4 @@
:license: BSD, see LICENSE for details.
#}
<h3><a href="{{ pathto(master_doc) }}">{{ _('Ceres Solver') }}</a></h3>
-{{ toctree() }}
+{{ toctree(includehidden=True) }}
diff --git a/docs/source/solving.rst b/docs/source/solving.rst
index 1ab3dba..4492c00 100644
--- a/docs/source/solving.rst
+++ b/docs/source/solving.rst
@@ -1542,95 +1542,121 @@
.. class:: IterationSummary
- :class:`IterationSummary` describes the state of the optimizer
- after each iteration of the minimization. Note that all times are
- wall times.
+ :class:`IterationSummary` describes the state of the minimizer at
+ the end of each iteration.
- .. code-block:: c++
+.. member:: int32 IterationSummary::iteration
- struct IterationSummary {
- // Current iteration number.
- int32 iteration;
+ Current iteration number.
- // Step was numerically valid, i.e., all values are finite and the
- // step reduces the value of the linearized model.
- //
- // Note: step_is_valid is false when iteration = 0.
- bool step_is_valid;
+.. member:: bool IterationSummary::step_is_valid
- // Step did not reduce the value of the objective function
- // sufficiently, but it was accepted because of the relaxed
- // acceptance criterion used by the non-monotonic trust region
- // algorithm.
- //
- // Note: step_is_nonmonotonic is false when iteration = 0;
- bool step_is_nonmonotonic;
+ Step was numerically valid, i.e., all values are finite and the
+ step reduces the value of the linearized model.
- // Whether or not the minimizer accepted this step or not. If the
- // ordinary trust region algorithm is used, this means that the
- // relative reduction in the objective function value was greater
- // than Solver::Options::min_relative_decrease. However, if the
- // non-monotonic trust region algorithm is used
- // (Solver::Options:use_nonmonotonic_steps = true), then even if the
- // relative decrease is not sufficient, the algorithm may accept the
- // step and the step is declared successful.
- //
- // Note: step_is_successful is false when iteration = 0.
- bool step_is_successful;
+ **Note**: :member:`IterationSummary::step_is_valid` is `false`
+ when :member:`IterationSummary::iteration` = 0.
- // Value of the objective function.
- double cost;
+.. member:: bool IterationSummary::step_is_nonmonotonic
- // Change in the value of the objective function in this
- // iteration. This can be positive or negative.
- double cost_change;
+ Step did not reduce the value of the objective function
+ sufficiently, but it was accepted because of the relaxed
+ acceptance criterion used by the non-monotonic trust region
+ algorithm.
- // Infinity norm of the gradient vector.
- double gradient_max_norm;
+ **Note**: :member:`IterationSummary::step_is_nonmonotonic` is
+ `false` when when :member:`IterationSummary::iteration` = 0.
- // 2-norm of the gradient vector.
- double gradient_norm;
+.. member:: bool IterationSummary::step_is_successful
- // 2-norm of the size of the step computed by the optimization
- // algorithm.
- double step_norm;
+ Whether or not the minimizer accepted this step or not.
- // For trust region algorithms, the ratio of the actual change in
- // cost and the change in the cost of the linearized approximation.
- double relative_decrease;
+ If the ordinary trust region algorithm is used, this means that the
+ relative reduction in the objective function value was greater than
+ :member:`Solver::Options::min_relative_decrease`. However, if the
+ non-monotonic trust region algorithm is used
+ (:member:`Solver::Options:use_nonmonotonic_steps` = `true`), then
+ even if the relative decrease is not sufficient, the algorithm may
+ accept the step and the step is declared successful.
- // Size of the trust region at the end of the current iteration. For
- // the Levenberg-Marquardt algorithm, the regularization parameter
- // mu = 1.0 / trust_region_radius.
- double trust_region_radius;
+ **Note**: :member:`IterationSummary::step_is_successful` is `false`
+ when when :member:`IterationSummary::iteration` = 0.
- // For the inexact step Levenberg-Marquardt algorithm, this is the
- // relative accuracy with which the Newton(LM) step is solved. This
- // number affects only the iterative solvers capable of solving
- // linear systems inexactly. Factorization-based exact solvers
- // ignore it.
- double eta;
+.. member:: double IterationSummary::cost
- // Step sized computed by the line search algorithm.
- double step_size;
+ Value of the objective function.
- // Number of function evaluations used by the line search algorithm.
- int line_search_function_evaluations;
+.. member:: double IterationSummary::cost_change
- // Number of iterations taken by the linear solver to solve for the
- // Newton step.
- int linear_solver_iterations;
+ Change in the value of the objective function in this
+ iteration. This can be positive or negative.
- // Time (in seconds) spent inside the minimizer loop in the current
- // iteration.
- double iteration_time_in_seconds;
+.. member:: double IterationSummary::gradient_max_norm
- // Time (in seconds) spent inside the trust region step solver.
- double step_solver_time_in_seconds;
+ Infinity norm of the gradient vector.
- // Time (in seconds) since the user called Solve().
- double cumulative_time_in_seconds;
- };
+.. member:: double IterationSummary::gradient_norm
+
+ 2-norm of the gradient vector.
+
+.. member:: double IterationSummary::step_norm
+
+ 2-norm of the size of the step computed in this iteration.
+
+.. member:: double IterationSummary::relative_decrease
+
+ For trust region algorithms, the ratio of the actual change in cost
+ and the change in the cost of the linearized approximation.
+
+ This field is not used when a linear search minimizer is used.
+
+.. member:: double IterationSummary::trust_region_radius
+
+ Size of the trust region at the end of the current iteration. For
+ the Levenberg-Marquardt algorithm, the regularization parameter is
+ 1.0 / member::`IterationSummary::trust_region_radius`.
+
+.. member:: double IterationSummary::eta
+
+ For the inexact step Levenberg-Marquardt algorithm, this is the
+ relative accuracy with which the step is solved. This number is
+ only applicable to the iterative solvers capable of solving linear
+ systems inexactly. Factorization-based exact solvers always have an
+ eta of 0.0.
+
+.. member:: double IterationSummary::step_size
+
+ Step sized computed by the line search algorithm.
+
+ This field is not used when a trust region minimizer is used.
+
+.. member:: int IterationSummary::line_search_function_evaluations
+
+ Number of function evaluations used by the line search algorithm.
+
+ This field is not used when a trust region minimizer is used.
+
+.. member:: int IterationSummary::linear_solver_iterations
+
+ Number of iterations taken by the linear solver to solve for the
+ trust region step.
+
+ Currently this field is not used when a line search minimizer is
+ used.
+
+.. member:: double IterationSummary::iteration_time_in_seconds
+
+ Time (in seconds) spent inside the minimizer loop in the current
+ iteration.
+
+.. member:: double IterationSummary::step_solver_time_in_seconds
+
+ Time (in seconds) spent inside the trust region step solver.
+
+.. member:: double IterationSummary::cumulative_time_in_seconds
+
+ Time (in seconds) since the user called Solve().
+
.. class:: IterationCallback
