More docs and user-friendliness

[timholy]

Thanks for the package! I was attracted to it because of performance benchmarks that have been posted. However, I've found it a bit rough to get going. Here's a wish-list of things I would have liked while learning this package:

• docstrings: when specializing API methods, more detail on precisely what those methods are supposed to return.
• documentation on variable blocks: does one subtype anything to define variables? That's implied, yet the only variable-related type I see exported is EuclideanVector. Looking at the source code, it seems the variable type is specified by NLLSsolver.NLLSProblem{MyVarType, MyCostType}() but this is not clear from the docs.
• varindices: suppose my problem is a function of two vectors each of length d. Should varindices(::MyProb) return StaticVector(1, 2) or 1:2d?
• information about how to extract the minimum and minimizer from NLLSResult and/or NLLSProblem
• errors like AssertionError: Problem with ndeps() are insufficiently informative
• if I have a variable that's a Matrix, I have to write my own update function. This was surprising because of the statement "For example, 3D rotations can be represented as a 9 parameter SO(3) matrix," which made me think that matrix variables should be supported. In implementing my own update, I was surprised to discover that updatevec can be a vector of dual numbers, and there is no description of how to handle that. Is updatevec a step (i.e., added to original value) or a new value (i.e., replacing the new value)?

I've never used Ceres before, and I suspect that some of these might not be issues for people who have.

[ojwoodford]

Hi @timholy

Many thanks for the interest and input. Yes, documentation is woeful. Would love to fix that, but some interest in the package and help from collaborators would really help there. I have zero experience with docstrings or any web-based documentation systems.

I'll look to improve the specific areas you mentioned, when I get back to maintaining the package. I haven't touched it in over a year, and actually don't know if or how it runs with Julia 1.11.

varindices(::MyCostType) takes as input a cost or residual block, not the problem. It should return the indices to the variables required to compute that cost. So if you have two variables (with indexes 1 and 2), then the varindices function for a cost block that uses both variables should return StaticVector(1, 2).

Here's an example of an SO3 type and its update function. updatevec is a step.

The variables are updated in-place, and their values at the end of the optimization will be the optimal values found. The minimum cost (bestcost), along with lots of other useful info, can be found in NLLSResult.

If you'd like a bit of help setting up your problem, please feel free to send me a gist of what you have so far. I'll be happy to take a look.