Re: [Axiom-developer] Re: A modest proposal (PLEQN documentation)

[William Sit]

Ralf Hemmecke wrote:
> [sniped]
> I don't quite know whether Tim wants to have both kinds of documentation
> in the Axiom project. If I understood correctly, that is the "facets of
> the crystal" view. Yes, Axiom should be a big monster which not only
> contains code.
> 
> It should be a collection of
> 1 code,
> 2 API descriptions (this is what the +++ comments are)
> 3 explanation of
>      motivations,
>      tricks that were used in the implementation,
>      things that are not used in the code (and the reason for it)
> 4 informal description of why the code is there
> 5 informal overall description of how some piece of code works
> 6 formal descriptions of the theory behind the code
> 7 proofs that the code fulfils its specification (its API)
> 8 test scripts that tests the code (we don't have automated
>    program verification yet)
> (This list is certainly not complete.)
> 
> William (I have not actually looked at your code so excuse me if I am
> wrong), what you contributed was/is in the code and API part and maybe
> in the test and formal description part (1,2,6,8). But what I think is
> very important is also the interconnection between all of this. Can you
> point me to some text in current Axiom that explains *why* (4) you have
> designed your contribution as it is now?

The code for PLEQN (parametric linear equations) was my
first Axiom code and I must admit that there are rooms for
improvement (even the variable names there weren't good).
But I did spend some time in designing the user interface
(or function interfaces for "psolve"). Bronstein complained
once that there were too many options (overloading psolve),
but he did not say which ones should be deleted. The code
was developed on and for an IBM main frame when memory was
at a premium (16MB). The code (even the algorithm) is not
efficient (even though it may be theoretically orders of
magnitude better than Gaussian elimination methods -- see
Section 9 of paper) and that is the reason for the options
to save partial computations to disk and this is possible
because the algorithm is by nature very parallel (which is
also the source of inefficiency; there is an efficiency
related open problem stated in the paper and so far I have
heard nothing new).

My paper has a long section on implementation issues,
(Section 7, although it is not Axiom specific, as required
by the journal referees) and SCRATCHPAD (former Axiom)
examples to use the code (Section 8). If you read these two
sections, you will find it is very close to the ideal of
literate programming (I didn't know what LP was at the
time). Interestingly, my submitted version interwined the
theory with the code but the referees wanted me to separate
them! Both the algorithm (and documentation) can be improved
to give better results (but not necessarily more efficient)
using another package QALGSET I developed about 6 years
later (1998). I have always wanted to rewrite the packages
but trying to do it taking in all the aspects (1 to 8) above
(of course I meant similar standards in different words) is
a big, big project, even for me. I fell behind when Axiom
changed to A# (former Aldor) and there are packages that
were dead code and I am even more behind currently. As a
researcher, my immediate concerns were (still are) to
produce new results (not necessarily related to Axiom), not
revisiting old code or even bringing them up to date
whenever the platform changes (Spad to A# to Aldor). But
actually, the days when I may refresh the packages is
getting closer because of applications to differential
equations.

> 
> I agree that some people are not interested in the code and in the
> description of the code, but for developers who maintain code it is very
> important to know about design issues. That is a different issue from
> the actual mathematical theory and it is important for maintainers of
> the code.
> 
> Axiom should have everything and it should be able to show to some
> person exactly the amount of detail s/he wants to see. If someone is
> only interested in the theory, extract something that doesn't show the
> implementation details. But some people would not only like to see the
> theory, but they want to see a "running theory", they want an
> interactive paper where they see the theory and can compute with the
> algorithms implemented by the paper. Other people like to see the actual
> algorithm in a specific programming language. Some people are not
> interested to be distracted by a lot of text and want to concentrate on
> more focused details of the implementation. Axiom should be able to
> extract all these different forms in nicely human readable formats. All
> that should be provided by a (or several) pamphlet(s).
> 
> The important thing is that the information is there. I am not so sure
> that we already have a good format of how a pamphlet should look like.

This is exactly my objections to the pamphlet format. It
would be easier from the author's viewpoint to create
different files for different uses, with cross-references
among them. It would be much harder to design one single
file that captures all possible views in a coherent way and
still be able to be unraveled as readable for various
separate views. To do the former you need a lot of "glue"
and the "glue" cannot be simply removed without
disconnecting the flow for individual views. To use a
compiler analogy, you need a lot of "ifdef"s and this
complicates the creative process as well as the logical flow
and reduces clarity because logical blocks may be dissected
into small chunks that spread across many pages.

> 
> I also agree that it is hard to actually write good LP documents. I made
> my experience with Aldor-Combinat. Look at it at
> http://www.risc.uni-linz.ac.at/people/hemmecke/AldorCombinat/ .
> It has a lot of documentation. But I myself would not say that it is a
> proper literate program. Try it out, read it. I guess, you will not be
> able to understand the overall project goals. I have not written that
> but still the program is working. Now, if I would require proper LP
> documentation, I would never be able to release this code at all. I try
> hard to add a lot of design decisions, but all that is still not enough.
> 
> And that Aldor-Combinat experience lets me think that it is better to
> release code even if it is not properly documented. So in this sense I
> do not fully agree with Tim. I find it better if I throw something at
> the public and have referees that tell me, hey there is something wrong,
> this and that is not understandable. So I have a chance to extend
> code+documentation at places where people complain. I am committed to
> LP, but I also have only limited time so it's better if there is really
> a community develepment. I am all for feedback. That should be our
> "quality assurance" way of makeing Axiom incrementally better.
> 

I just skipped through AldorCombinat and except for the
theory behind species, your documentation for the code and
usage is quite extensive. I am however overwhelmed by the
hundreds of chunks and occasionally the extra link
information can be distracting (of course they are useful
for debugging and code changes). Just one question: In
Section 8.1, just before the bottom ToDo, the two formulae
at the end of lines, do you mean $\cup_{U \subseteq L, U
finite} \{U\}$ (and similarly for F[U])?

We all have limited time and that is why the priority of the
Axiom project should be to increase user base. If there are
more users, Axiom will be used at more universities
(especially if a fully functioning Windows version is
available) and even commercial houses (but they don't
"count" in my books); we will have more students who can do
a lot of work such as documentation (writing pamphlets if
that is the standard) as undergraduate or master theses.
Doctoral students can develop better models, new and newer
algorithms for Axiom's foundation and implement them. 

William