Use subsections instead of an enumeration for FAQs Change-Id: I37c1256417240bf7decec1f756df8a8402f5c586
diff --git a/docs/source/modeling_faqs.rst b/docs/source/modeling_faqs.rst index 0d23de4..b51380a 100644 --- a/docs/source/modeling_faqs.rst +++ b/docs/source/modeling_faqs.rst
@@ -8,81 +8,76 @@ Modeling ======== -#. Use analytical/automatic derivatives. +Use analytical/automatic derivatives +==================================== - This is the single most important piece of advice we can give to - you. It is tempting to take the easy way out and use numeric - differentiation. This is a bad idea. Numeric differentiation is - slow, ill-behaved, hard to get right, and results in poor - convergence behaviour. +This is the single most important piece of advice we can give to you. It is +tempting to take the easy way out and use numeric differentiation. This is a bad +idea. Numeric differentiation is slow, ill-behaved, hard to get right, and +results in poor convergence behaviour. - Ceres allows the user to define templated functors which will - be automatically differentiated. For most situations this is enough - and we recommend using this facility. In some cases the derivatives - are simple enough or the performance considerations are such that - the overhead of automatic differentiation is too much. In such - cases, analytic derivatives are recommended. +Ceres allows the user to define templated functors which will be automatically +differentiated. For most situations this is enough and we recommend using this +facility. In some cases the derivatives are simple enough or the performance +considerations are such that the overhead of automatic differentiation is too +much. In such cases, analytic derivatives are recommended. - The use of numerical derivatives should be a measure of last - resort, where it is simply not possible to write a templated - implementation of the cost function. +The use of numerical derivatives should be a measure of last resort, where it is +simply not possible to write a templated implementation of the cost function. - In many cases it is not possible to do analytic or automatic - differentiation of the entire cost function, but it is generally - the case that it is possible to decompose the cost function into - parts that need to be numerically differentiated and parts that can - be automatically or analytically differentiated. +In many cases it is not possible to do analytic or automatic differentiation of +the entire cost function, but it is generally the case that it is possible to +decompose the cost function into parts that need to be numerically +differentiated and parts that can be automatically or analytically +differentiated. - To this end, Ceres has extensive support for mixing analytic, - automatic and numeric differentiation. See - :class:`CostFunctionToFunctor`. +To this end, Ceres has extensive support for mixing analytic, automatic and +numeric differentiation. See :class:`CostFunctionToFunctor`. -#. When using Quaternions, consider using :class:`QuaternionManifold`. +When using Quaternions, consider using :class:`QuaternionManifold` +================================================================== - `Quaternions <https://en.wikipedia.org/wiki/Quaternion>`_ 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) beneficial 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:`QuaternionManifold`. +`Quaternions <https://en.wikipedia.org/wiki/Quaternion>`_ 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) beneficial 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:`QuaternionManifold`. - .. NOTE:: +.. NOTE:: - If you are using `Eigen's Quaternion - <http://eigen.tuxfamily.org/dox/classEigen_1_1Quaternion.html>`_ - object, whose layout is :math:`x,y,z,w`, then you should use - :class:`EigenQuaternionManifold`. + If you are using `Eigen's Quaternion + <http://eigen.tuxfamily.org/dox/classEigen_1_1Quaternion.html>`_ + object, whose layout is :math:`x,y,z,w`, then you should use + :class:`EigenQuaternionManifold`. -#. How do I solve problems with general linear & non-linear - **inequality** constraints with Ceres Solver? +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. +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. +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. +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? +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. +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. +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? +How do I set one or more components of a parameter block constant? +================================================================== - Using :class:`SubsetManifold`. +Using :class:`SubsetManifold`.