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 _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
