[math] SYMMLQ implementation notes

[Sébastien Brisard <se...@m4x.org>]

Hi,
I've spent quite a lot of time going through Pr. Saunders' FORTRAN
implementation of this algorithm, and the Java port is almost ready.
This algorithm is quite difficult to read, because some quantities
required at iteration k can be computed only in iteration (k+1). So
one must be careful in managing the loops, and especially moving
around some pieces of code. I feel that for maintenance purposes in
the future (for example, when we will be ready to introduce custom
stopping criteria), it would be useful to have detailed implementation
notes, where the correspondance between Java variables and the
mathematical variables of the original paper (including the index of
the iteration!) would be clearly stated.

I've taken some notes for myself, it would be useful if those notes
were actually shipped with the code (or would it?). Considering the
recent posts on the sine cardinal, Javadoc are *definitely* not the
place where I should put these notes. Where should these go
  - separate document (LaTeX), which would go in a linear/doc-files
subdirectory in order to be copied with the javadoc (which could point
at that document)
  - html page in the website (User Guide? But this is really intended
for developers)
  - any other option?

In any case, the notes would benefit from a little bit of mathematical
formatting. My preferred option would be LaTeX, but I can live with an
HTML page with embedded MathML (provided the Commons-Math site
resulting from mvn site:site can support MathML -- anyone ever
tried?).

Do you think that these notes should really be attached to the CM
library? If yes, any suggestion as to where and how?

Thanks!
Sébastien

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [math] SYMMLQ implementation notes

[Ted Dunning <te...@gmail.com>]

2011/10/8 Sébastien Brisard <se...@m4x.org>

> FURTHER QUESTION: do you think that this reformatting of the code
> (plus renaming of some variables) could be offensive to the original
> developer? Should I be careful with that? His original contribution is
> fully aknowledged anyway.
>

I have never seen an instance of an original author getting upset about
this.

Re: [math] SYMMLQ implementation notes

[Phil Steitz <ph...@gmail.com>]

On 10/8/11 9:20 AM, Sébastien Brisard wrote:
>> I would encourage you, though, to add as much inline, class and
>> javadoc documentation as possible, since that is what developers
>> looking at the source will see immediately.
>>
> Yes, I had second thoughts on putting the notes in an external file...
> The main benefit being mathematical formatting... I guess something
> like alpha[k] instead of $\alpha_k$ would still be readable (and
> understandable), and could be inlined in the code. It's probably the
> best option. My worry is, as I said, the fact that in iteration k+1 of
> the loop, we compute gamma[k-1], but also alpha[k]... It's all a bit
> confusing, one has to be very careful about indices... Saunders did a
> marvelous job, and the code works brilliantly in Java now (passes all
> original tests by Saunders, plus additional ones, plus very large
> test-cases at work). However, it was written in a very linear fashion,
> with a rather large main loop. I've tried to break up the code in
> smaller pieces, factor out some duplicate code, reduce the scope of
> variables... But one still has to be *very* careful about these
> painful mixed indices... I do think that maintenance would benefit
> from additional notes, so I'll wait a while before I commit it.
>
> FURTHER QUESTION: do you think that this reformatting of the code
> (plus renaming of some variables) could be offensive to the original
> developer? Should I be careful with that? His original contribution is
> fully aknowledged anyway.

The only reason to preserve original names is to make comparison
with the original easier.  Same applies to formatting and
structure.  We should be aiming for maintainable Java code, with as
clear documentation as we can get of how the algorithm works and how
the code implements the algorithm.  Fortran structure, naming, etc.,
should (with great care, incrementally, etc.) be replaced by what
developers expect to see in Java (preserving performance and accuracy).

Phil
>
> Sébastien
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [math] SYMMLQ implementation notes

[Sébastien Brisard <se...@m4x.org>]

>
> I would encourage you, though, to add as much inline, class and
> javadoc documentation as possible, since that is what developers
> looking at the source will see immediately.
>
Yes, I had second thoughts on putting the notes in an external file...
The main benefit being mathematical formatting... I guess something
like alpha[k] instead of $\alpha_k$ would still be readable (and
understandable), and could be inlined in the code. It's probably the
best option. My worry is, as I said, the fact that in iteration k+1 of
the loop, we compute gamma[k-1], but also alpha[k]... It's all a bit
confusing, one has to be very careful about indices... Saunders did a
marvelous job, and the code works brilliantly in Java now (passes all
original tests by Saunders, plus additional ones, plus very large
test-cases at work). However, it was written in a very linear fashion,
with a rather large main loop. I've tried to break up the code in
smaller pieces, factor out some duplicate code, reduce the scope of
variables... But one still has to be *very* careful about these
painful mixed indices... I do think that maintenance would benefit
from additional notes, so I'll wait a while before I commit it.

FURTHER QUESTION: do you think that this reformatting of the code
(plus renaming of some variables) could be offensive to the original
developer? Should I be careful with that? His original contribution is
fully aknowledged anyway.

Sébastien

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [math] SYMMLQ implementation notes

[Phil Steitz <ph...@gmail.com>]

On 10/8/11 7:44 AM, Sébastien Brisard wrote:
> Hi,
> I've spent quite a lot of time going through Pr. Saunders' FORTRAN
> implementation of this algorithm, and the Java port is almost ready.
> This algorithm is quite difficult to read, because some quantities
> required at iteration k can be computed only in iteration (k+1). So
> one must be careful in managing the loops, and especially moving
> around some pieces of code. I feel that for maintenance purposes in
> the future (for example, when we will be ready to introduce custom
> stopping criteria), it would be useful to have detailed implementation
> notes, where the correspondance between Java variables and the
> mathematical variables of the original paper (including the index of
> the iteration!) would be clearly stated.
>
> I've taken some notes for myself, it would be useful if those notes
> were actually shipped with the code (or would it?). Considering the
> recent posts on the sine cardinal, Javadoc are *definitely* not the
> place where I should put these notes.

Things that impact the contract of the API - i.e., what is being
computed, what algorithm is being used, exceptions, boundary cases,
etc., should all be covered in the javadoc.  You can link to
external documents to describe algorithms, but the javadoc needs to
fully document the API.  How the implementation works is a different
matter.  See below.

>  Where should these go
>   - separate document (LaTeX), which would go in a linear/doc-files
> subdirectory in order to be copied with the javadoc (which could point
> at that document)
>   - html page in the website (User Guide? But this is really intended
> for developers)
>   - any other option?
>
> In any case, the notes would benefit from a little bit of mathematical
> formatting. My preferred option would be LaTeX, but I can live with an
> HTML page with embedded MathML (provided the Commons-Math site
> resulting from mvn site:site can support MathML -- anyone ever
> tried?).
>
> Do you think that these notes should really be attached to the CM
> library? If yes, any suggestion as to where and how?

This is a good question and one that applies to lots of other things
that are not too well documented now.   I would be fine with adding
a section to the web site on implementation notes, using pdf as
publication format, TeX as source format, assuming there is no maven
plugin to create pdfs from TeX source on the fly, storing both in
svn, and including the pdfs with the user guide - only site shipped
with the binary distro.

An alternative would be to publish the notes externally and link to
them.  Its a lot of work, but there are probably quite a few
interesting (free access!) articles that could be written based on
things already in [math].

I would encourage you, though, to add as much inline, class and
javadoc documentation as possible, since that is what developers
looking at the source will see immediately.

Phil
>
> Thanks!
> Sébastien
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org