Document DumpLinearLeastSquaresProblem Add documentation on the output of DumpLinearLeastSquaresProblem. This is to clarify confusion brought up on #608 Change-Id: I935cacee1e4345a1d0250aaac322ca2f8e794e66
diff --git a/docs/source/nnls_solving.rst b/docs/source/nnls_solving.rst index 236af8e..3d58a70 100644 --- a/docs/source/nnls_solving.rst +++ b/docs/source/nnls_solving.rst
@@ -1987,15 +1987,35 @@ * ``TEXTFILE`` Write out the linear least squares problem to the directory pointed to by :member:`Solver::Options::trust_region_problem_dump_directory` as - text files which can be read into ``MATLAB/Octave``. The Jacobian - is dumped as a text file containing :math:`(i,j,s)` triplets, the - vectors :math:`D`, `x` and `f` are dumped as text files - containing a list of their values. + text files which can be read into ``MATLAB/Octave``. The + following files are created: + + * ``A.txt``: The Jacobian matrix :math:`J` in (i, j, s) triplet format. + * ``b.txt``: The residuals vector :math:`f`. + * ``D.txt``: The diagonal scaling/regularizer matrix. + * ``x.txt``: The computed step vector. A ``MATLAB/Octave`` script called ``ceres_solver_iteration_???.m`` is also output, which can be used to parse and load the problem into memory. + .. NOTE:: + **Understanding the dumped ``x.txt`` vector:** + + The content of ``x.txt`` depends on the + :member:`Solver::Options::trust_region_strategy_type` being + used. This is because the dumping occurs *inside* the + strategy's implementation to gain access to the :math:`D` + matrix: + + * If the strategy is ``LEVENBERG_MARQUARDT``, ``x.txt`` + contains the **damped trust region step** (the solution + to the scaled problem). + * If the strategy is ``DOGLEG``, ``x.txt`` contains the + **pure, un-damped Gauss-Newton step**. This is *not* + necessarily the final step taken by the optimizer, as it + has not yet been limited by the trust region radius. + .. member:: bool Solver::Options::check_gradients Default: ``false``