Improve javadoc for iterative linear solvers with preconditioners
-----------------------------------------------------------------
Key: MATH-771
URL: https://issues.apache.org/jira/browse/MATH-771
Project: Commons Math
Issue Type: Improvement
Affects Versions: 3.1
Reporter: Sébastien Brisard
Assignee: Sébastien Brisard
Preconditioning is the replacement of the linear system {{A * x = b}} with {{A
* M^(-1) * y = b}}, followed by {{x = M^(-1) * y}}, where {{M}} approximates in
some sense {{A}}. There is no consensus in the literature as to whether {{M}}
of {{M^(-1)}} should be called the preconditioner.
In {{o.a.c.m3.linear}}, the Javadoc currently states that {{M}} is the
preconditioner. However, following MATH-735, the solver must be passed
{{M^(-1)}} (not {{M}}!) as a {{RealLinearOperator}}. This makes the whole
Javadoc a bit obscure. It would be logical to call preconditioning the
replacement of the initial system with {{A * M * y = b}}, where {{M}}
approximates in some sense {{A^(-1)}} and will be called the preconditioner.
Such a change will make the javadoc more readable. However, it requires careful
review of the existing Javadoc for the following classes
* {{PreconditionedIterativeLinearSolver}},
* {{ConjugateGradient}},
* {{SymmLQ}},
* {{JacobiPreconditioner}},
Also, in {{PreconditionedIterativeLinearSolver}} (and its concrete
implementations), the parameter {{minv}} in {{solve()}} should be renamed {{m}}.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
