diff --git a/docs/source/conf.py b/docs/source/conf.py index c9afebddb..a6198fd51 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # General information about the project. project = u'Ceres Solver' -copyright = u'2014 Google Inc' +copyright = u'2015 Google Inc' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -185,7 +185,7 @@ latex_elements = { # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'CeresSolver.tex', u'Ceres Solver', - u'Sameer Agarwal \\& Keir Mierle', 'manual'), + u'Sameer Agarwal, Keir Mierle & Others', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -215,7 +215,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'ceressolver', u'Ceres Solver', - [u'Sameer Agarwal & Keir Mierle'], 1) + [u'Sameer Agarwal, Keir Mierle & Others'], 1) ] # If true, show URL addresses after external links. @@ -229,7 +229,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ ('index', 'CeresSolver', u'Ceres Solver', - u'Sameer Agarwal & Keir Mierle', 'CeresSolver', 'One line description of project.', + u'Sameer Agarwal, Keir Mierle & Others', 'CeresSolver', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst index d851038ea..fd35ac5e1 100644 --- a/docs/source/faqs.rst +++ b/docs/source/faqs.rst @@ -66,6 +66,54 @@ Modeling automatic and numeric differentiation. See :class:`CostFunctionToFunctor`. +#. When using Quaternions, consider using :class:`QuaternionParameterization`. + + `Quaternions `_ are a + four dimensional parameterization of the space of three dimensional + rotations :math:`SO(3)`. However, the :math:`SO(3)` is a three + dimensional set, and so is the tangent space of a + Quaternion. Therefore, it is sometimes (not always) benefecial to + associate a local parameterization with parameter blocks + representing a Quaternion. Assuming that the order of entries in + your parameter block is :math:`w,x,y,z`, you can use + :class:`QuaternionParameterization`. + + If however, you are using `Eigen's Quaternion + `_ + object, whose layout is :math:`x,y,z,w`, then we recommend you use + Lloyd Hughes's `Ceres Extensions + `_. + +#. How do I solve problems with general linear & non-linear + **inequality** constraints with Ceres Solver? + + Currently, Ceres Solver only supports upper and lower bounds + constraints on the parameter blocks. + + A crude way of dealing with inequality constraints is have one or + more of your cost functions check if the inequalities you are + interested in are satisfied, and if not return false instead of + true. This will prevent the solver from ever stepping into an + infeasible region. + + This requires that the starting point for the optimization be a + feasible point. You also risk pre-mature convergence using this + method. + +#. How do I solve problems with general linear & non-linear **equality** + constraints with Ceres Solver? + + There is no built in support in ceres for solving problems with + equality constraints. Currently, Ceres Solver only supports upper + and lower bounds constraints on the parameter blocks. + + The trick described above for dealing with inequality + constraints will **not** work for equality constraints. + +#. How do I set one or more components of a parameter block constant? + + Using :class:`SubsetParameterization`. + #. Putting `Inverse Function Theorem `_ to use. @@ -112,17 +160,14 @@ Modeling Eigen::Matrix3d ecef_to_lla_jacobian; lla_to_ecef_jacobian.computeInverseWithCheck(ecef_to_lla_jacobian, invertible); -#. When using Quaternions, use :class:`QuaternionParameterization`. - - TBD - -#. How to choose a parameter block size? - - TBD Solving ======= +#. How do I evaluate the Jacobian for a solver problem? + + Using :func:`Problem::Evaluate`. + #. Choosing a linear solver. When using the ``TRUST_REGION`` minimizer, the choice of linear diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst index 038684d10..f7c1c72f8 100644 --- a/docs/source/nnls_modeling.rst +++ b/docs/source/nnls_modeling.rst @@ -364,6 +364,12 @@ the corresponding accessors. This information will be verified by the `_ can be used. + .. NOTE :: + + TODO(sameeragarwal): Add documentation for the constructor and for + NumericDiffOptions. Update DynamicNumericDiffOptions in a similar + manner. + .. code-block:: c++ template - ::set_num_residuals(num_residuals); - } - - options_.relative_step_size = relative_step_size; - } - ~NumericDiffCostFunction() { if (ownership_ != TAKE_OWNERSHIP) { functor_.release(); diff --git a/include/ceres/solver.h b/include/ceres/solver.h index 318cf48cb..f53760e6c 100644 --- a/include/ceres/solver.h +++ b/include/ceres/solver.h @@ -701,10 +701,20 @@ class CERES_EXPORT Solver { // this number, then the jacobian for that cost term is dumped. double gradient_check_relative_precision; - // Relative shift used for taking numeric derivatives. For finite - // differencing, each dimension is evaluated at slightly shifted - // values; for the case of central difference, this is what gets - // evaluated: + // WARNING: This option only applies to the to the numeric + // differentiation used for checking the user provided derivatives + // when when Solver::Options::check_gradients is true. If you are + // using NumericDiffCostFunction and are interested in changing + // the step size for numeric differentiation in your cost + // function, please have a look at + // include/ceres/numeric_diff_options.h. + // + // Relative shift used for taking numeric derivatives when + // Solver::Options::check_gradients is true. + // + // For finite differencing, each dimension is evaluated at + // slightly shifted values; for the case of central difference, + // this is what gets evaluated: // // delta = numeric_derivative_relative_step_size; // f_initial = f(x)