Re: [Axiom-developer] [axiom-developer] What do diagrams in bookvol10.3 mean?

[daly]

On Thu, 2011-09-22 at 12:18 +0400, Dmitry Semikin wrote:
> Hi, axiom-developers,
> 
> 
> I'm new to axiom and just getting aquainted to it, trying to solve my
> problems using it, so please, forgive me, if I ask questions with
> obvious answers.
> 
> 
> The one thing, which confused me is what do diagrams in bookvol10.3
> (Domains reference) mean.

These diagrams are subgraphs of the whole "support lattice". 

Each domain requires a lot of other domains before it can be compiled.
If you create a lattice and place each domain in the lattice such that
everything it depends upon is below it you will find a "highest"
precondition domain. If you try to place Symbol in this lattice you 
will find that StringCategory is the "highest" required domain. 
This is a compile constraint, not an algebra constraint.

StringCategory is in layer 9 and will be compiled before anything in
layer 10 of the support graph. Symbol is in layer 10 because it 
depends upon StringCategory.

The complete support lattice is documented in the Makefile
(src/algebra/Makefile.pamphlet). 

There is a complication in the case of SYMBOL and some other domains.

If the support lattice was a pure lattice then we could compile the
algebra from scratch. Unfortunately, this is not the case. The algebra
forms a graph. At the bottom of the lattice is a clique of files that
all depend on each other. These files have to be compiled before any
other files. So SYMBOL has to be compiled before STRCAT. But we just
figured out that STRCAT has to be compiled before SYMBOL. This is
called the "bootstrap set".

In the past Axiom always needed a running Axiom to compile the algebra.
Since a running Axiom already contained the algebra, SYMBOL and STRCAT
already existed. This was never a problem when I worked at IBM since
I always had a running Axiom available.

When I got the Axiom sources I was not given permission to distribute
a running Axiom from NAG. That means that you could not build Axiom
entirely from the source code. Since the whole point of an open source
project is that anyone can build it from source I needed to figure out
a way to build the algebra from scratch.

One of the most difficult tasks was to discover the support lattice,
find the "bootstrap set", and set up a "precompile phase" which compiled
the algebra from the lisp sources rather than the spad sources. Note
that spad is really just syntactic sugar over common lisp so this is
always possible. It turns out that there are 85 algebra files in the
bootstrap set (see LAYER0BOOTSTRAP in src/algebra/Makefile.pamphlet).
SYMBOL is a member of the bootstrap set.

So the process is:
 (LAYER0BOOTSTRAP) compile these algebra files from lisp sources
 (LAYER0 - LAYERn) compile these algebra files from spad
 (LAYER0COPY) recompile these algebra files from spad
this happens because of the ORDER variable
(see ORDER= in src/algebra/Makefile.pamphlet)

Once this bootstrap problem was solved I could build the rest of the
algebra lattice.

> 
> 
> The first question is what is the legend? It seems to me, that green
> boxes are domains and blue ones are categories. But there are some
> other colors and shapes. What do they mean? Is some kind of legend
> given anywhere?

This is explained in the section "Adding new algebra" in 
src/algebra/Makefile.pamphlet

The color and the shape carry the same information.
  #4488FF == category (bookvol10.2) box
  #88FF44 == domain   (bookvol10.3) ellipse
  #FF4488 == package  (bookvol10.4) circle
  #444488 == numeric  (bookvol10.5)

I apologize for the horrid choice of colors (I am partially color
blind). You'll notice that they are just rotations of the hex codes.

In the books (10.2, 10.3, 10.4, 10.5) I have a chunk that enables
me to recreate the support lattice. The information for each 
domain includes the subgraph. The image is created from this
tiny specification and is a subgraph of the full graph.
(axiom-developer.org/axiom-website/bookvol10.2full.html)
(axiom-developer.org/axiom-website/bookvol10.2abb.html)
If you click on a node it will take you to the appropriate
book. I plan to make this link to the proper section of the
book but have not done that yet.

Actually, I do not draw the full graph. All of the full graph
information is documented in src/algebra/Makefile.pamphlet but
the actual graph is HUGE. You will see that most of the links
are comments. I have tried several different ways to make this
graph available. I wrote a few graphing tools to do tricks 
like force-based node expansion but I never published the results.

Ultimately I plan to make the graph have links to the domains
in the books. Those domains will have documentation of the theory
(some exist), the algebra (exists), the test cases (some exist), 
the help file (some exist), proofs (in plan but not published), etc.

All of this takes time and most of my time these days involve
treeshaking and documenting the interpreter and compiler. 



> 
> 
> The second question is what kind of relation is depicted on those
> diagrams? E.g. for the category Symbol we have diagram with arrow
> pointing to STRICAT (StringCategory) category. But if I look at the
> code bellow (in the same section of the bookvol10.3) or browse
> documentation of the Symbol in the HyperDoc, I cannot find any
> reference to StringCategory. So, what is the relation, depicted in the
> diagram in the bookvol 10.3? (Note: similar situation presents for
> other domains eiher).

The relationship in the support lattice is NOT the same as the
algebraic relationships. The support lattice documents the compile
time constraints.

I have a plan to document the algebraic support lattice but I have
not done it yet.

Tim Daly