readme

"What matters the most is what you do for free" -- John Gorka

"...even more important, for the progress of mathematics in the computer
 age, is the beaver, who will build the needed infrastructure of computer
 mathematics, that would eventually enable us to solve many outstanding
 open problems, and many new ones. Consequently, the developers of computer
 algebra systems, and creators of algorithms, are even more important than
 both birds and frogs." --Doron Zeilberger
  (http://www.math.rutgers.edu/~zeilberg/Opinion95.html)

Listening to computer scientists argue, it seems that the standards of
proof is I've had two beers and there is this anecdote about a tribe
in New Guinea from one of Scott Birkins books that seems to be applicable.

The debate is hindered by low standards of proof.
-- Greg Wilson "What We Actually Know About Software Development"
https://vimeo.com/9270320

Thinking, analyzing, and inventing are not anomalous acts; they
are the normal respiration of the intelligence.
-- Zero HP Lovecraft (The Gig Economy)
https://zerohplovecraft.wordpress.com/2018/05/11/the-gig-economy-2
 
When you teach, you do something useful.
When you do research, most days you don't.
-- June Huh IAS Princeton 

Therapist: So you're afraid that you're letting down people
you've never met and who you've given something for free?
Me: Yeah, basically
-- Matthew Garrett

Only those who aren't trying to make money can afford to advance a
technology that doesn't pay.
-- Robert X. Cringely

You've unpacked the Axiom source code to some directory. In this
document we'll call that directory /home/me/axiom. Note that the path
cannot contain spaces. 

=======================================================================
================= MAKING AXIOM ========================================
=======================================================================

Axiom builds a system-specific version based on a string we'll call
the SYSNAME. Currently recognized SYSNAME strings can be found on the
Axiom website at:
<http://axiom.axiom-developer.org/axiom-website/download.html>

Replace SYSNAME below with the likely name of your system.

We also assume that you downloaded AXIOM to someplace. Suppose
that place is /home/me/axiom, then:

cd /home/me/axiom                         << where you unpacked the sources
export AXIOM=/home/me/axiom/mnt/SYSNAME   << which axiom to build
export PATH=$AXIOM/bin:$PATH
make                                      << build the system

A recent cause of likely build failures is SELinux.
See the faq file for possible solutions.

When the make completes you'll have an executable called $AXIOM/bin/axiom

=======================================================================
================= INSTALLING AXIOM ====================================
=======================================================================

You can install Axiom on your system by typing (as root):

make install

This will put Axiom into /usr/local/axiom 
and the axiom command in /usr/local/bin/axiom

You can change these defaults to anything thus:

make INSTALL=/home/me/myaxiom COMMAND=/home/me/bin/myaxiom install


=====================================================================

Documentation can be found at various places in the system or on the
Axiom website: <http://axiom.axiom-developer.org>

There is a book (available on Amazon.com):
Jenks, Richard D. and Sutor, Robert S. "Axiom, The Scientific Computation
System" Springer-Verlag, NY, 1992, ISBN 0-387-97855-0

The book is automatically built as part of the make and lives in:

(yourpath)/axiom/mnt/(sysname)/doc/bookvol0.pdf

In general every directory will contain a Makefile.dvi file.
These files document facts about how Axiom is built.
The directory mnt/linux/doc will contain .dvi files as they are written.

Axiom is free and open source software. It is copyrighted code that
is released under the Modified BSD license. Much debate about this
topic has already been archived on the axiom-legal and axiom-developer
mailing lists. The mail archives are available at the Axiom website:
http://savannah.gnu.org/projects/axiom

For the purposes of copyright, Axiom is to be considered 
"Joint Work". Specifically:

 "A joint work is a work prepared by two or more individuals, with the
 intention that their separate contributions be merged into a single work.
 A joint author can also be an organization or a corporation under the
 definition of "work for hire." A person who has merely contributed ideas
 without actually documenting those ideas generally cannot be considered
 an author.

 Authors own the work jointly and equally, unless the authors make an
 agreement otherwise. Each joint author has the right to exercise any or all 
 of the exclusive rights inherent in the joint work. Each author may:
   * Grant thirds parties permission to use the work on a nonexclusive
     basis without the consent of the other joint authors
   * Transfer his or her entire ownership interest to another person without
     the other joint author's consent
   * Update the work for his or her own purpose

 Additionally, each joint author must account to the other joint authors
 for any profits received from licensing their joint work."

(http://copyright.universityofcalifornia.edu/ownership/joint-works.html)

Questions and comments should be sent to:
axiom-developer@nongnu.org

Tim Daly
daly@axiom-developer.org

=====================================================================

Philosophy

Scratchpad was a large, general purpose computer algebra system that
was originally developed by IBM under the direction of Richard Jenks.
The project started in 1971 and evolved slowly.  Barry Trager was key
to the technical direction of the project. Scratchpad developed over a
20 year stretch and was basically considered as a research platform
for developing new ideas in computational mathematics. In the 1990s,
as IBM's fortunes slid, the Scratchpad project was renamed to Axiom,
sold to the Numerical Algorithms Group (NAG) in England and became a
commercial system.  As part of the Scratchpad project at IBM in
Yorktown I worked on all aspects of the system and eventually helped
transfer the product to NAG. For a variety of reasons it never became
a financial success and NAG withdrew it from the market in October,
2001.

NAG agreed to release Axiom as free software. The basic motivation was
that Axiom represents something different from other programs in a lot
of ways. Primarily because of its foundation in mathematics the Axiom
system will potentially be useful 30 years from now.  In its current
state it represents about 30 years and 300 man-years of research
work. To strive to keep such a large collection of knowledge alive
seems a worthwhile goal.

However, keeping Axiom alive means more than just taking the source
code and dumping it onto a public server. There are a lot of things
about the system that need to change if it is going to survive and
thrive for the next 30 years.

The system is complex and difficult to build. There are few people who
know how it is structured and why it is structured that way. Somehow
it needs to be documented deeply so others can contribute.

The mathematics is difficult. Unlike other free software you can't
just reach for the old saying ``read the source code''.  The source
code is plain, clear and about as close to the mathematical theory as
is practical. Unfortunately the mathematical theory is enshrined in
some research library where few people will have access. Somehow this
must change. The research work, the mathematics, the published papers,
and the source code have all got to be kept together for the next
generation to read, understand and modify.

The mathematics is narrow and very focused. This was due to the fact
that, while Axiom is a great research platform, we only had a limited
number of visitors at IBM Research. So there is very little in the way
of, say, infinite group theory in Axiom. We can add it. Doing so will
show up shortcomings in the system.  For example, how do you represent
an infinite object? There are many possible representations and they
depend on your goals. The system will have to change, expand, and,
hopefully, become cleaner as more thought is applied. Scratchpad
changed continuously while it was being used for research and we
expect Axiom to do the same.

The language (spad) is designed to let you write algorithms that are
very close to the mathematics. However, the algorithms as presented in
the current system have never been shown or proven (an important
distinction) to be correct.  It is vital that we undertake the huge
effort of verifying and validating the code. How else can we trust the
results and of what use is a system this complex without trust?
Somehow we have to extend the system to integrate program proof
techniques.  That is, we have to make computational mathematics hold
to the same standard as the rest of mathematics.

All of which seems to integrate into a requirement for better
documentation. The key change which developers of Axiom will find with
this version is that the documentation is primary and the code is
secondary. Taking direction from Knuth and Dijkstra the system is now
in a literate programming style. The hope is that the next generation
of developers and users will be able to understand, maintain and
extend the system gracefully. And that eventually papers submitted to
journals (an Axiom Journal?) will be easily imported into the system
with their running code made available automatically.

There is no guarantee that this attempt to change the culture of
computational mathematicians is going to succeed. But it is our firm
belief that current systems have reached a complexity plateau and we
need to find new techniques to push the envelope.

In general, we need to consider changes to the system with a 30 year
horizon rather than the current write-ship-debug mentality of software
development. This is, after all, mathematics, the queen of the
sciences. It deserves all of the time, talent and attention we can
bring to bear on the subject.

Tim Daly -- September 3, 2002

Contributions

All of these people have, in some way or other, been associated with
Scratchpad and Axiom. If you contribute, add your name.  The names are
in alphabetical order as we make no attempt to quantify the relative
merit of the contributions.

In books/bookvol5.pamphlet is a variable called credits
which contains this list. Typing 
)credits 
at the axiom command prompt will prettyprint the list.

"An alphabetical listing of contributors to AXIOM:"
Roy Adler              Christian Aistleitner  Michael Albaugh
Cyril Alberga          Jason Allen            Richard Anderson
George Andrews         Jerry Archibald        S.J. Atkins
Jeremy Avigad          Brent Baccala          Knut Bahr
Henry Baker            Martin Baker           Stephen Balzac
Yurij Baransky         David R. Barton        Thomas Baruchel
Gerald Baumgartner     Gilbert Baumslag       Michael Becker
Nelson H. F. Beebe     Jay Belanger           Siddharth Bhat
David Bindel           Fred Blair             Vladimir Bondarenko
Ed Borasky             Mark Botch             Raoul Bourquin
Alexandre Bouyer       Karen Braman           Wolfgang Brehm
Peter A. Broadbery     Martin Brock           Manuel Bronstein
Christopher Brown      Stephen Buchwald       Florian Bundschuh
Luanne Burns           William Burge          Ralph Byers
Quentin Carpent        Jacques Carette        Pierre Casteran
Robert Cavines         Pablo Cayuela          Bruce Char
Ondrej Certik          Tzu-Yi Chen            Bobby Cheng
Cheekai Chin           David V. Chudnovsky    Gregory V. Chudnovsky
Mark Clements          Roland Coeurjoly       Emil Cohen
Hirsh Cohen            Josh Cohen             James Cloos
Jia Zhao Cong          Christophe Conil       Don Coppersmith
George Corliss         Robert Corless         Gary Cornell
Frank Costa            Meino Cramer           Karl Crary
Jeremy Du Croz         David Cyganski         Nathaniel Daly
Timothy Daly Sr.       Timothy Daly Jr.       James H. Davenport
David Day              James Demmel           Didier Deshommes
Michael Dewar          Inderjit Dhillon       Jack Dongarra
Jean Della Dora        Gabriel Dos Reis       Claire DiCrescendo
Sam Dooley             Pierre Doucy           Nicolas James Doye
Zlatko Drmac           Lionel Ducos           Iain Duff
Lee Duhem              Martin Dunstan         Brian Dupee
Dominique Duval        Robert Edwards         Hans-Dieter Ehrich
Heow Eide-Goodman      Alexandra Elbakyan     Carl Engelman
Lars Erickson          Mark Fahey             William Farmer
Richard Fateman        Bertfried Fauser       Stuart Feldman
John Fletcher          Brian Ford             Albrecht Fortenbacher
George Frances         Constantine Frangos    Timothy Freeman
Korrinn Fu             Marc Gaetano           Rudiger Gebauer
Van de Geijn           Kathy Gerber           Patricia Gianni
Eitan Gurari           Gustavo Goertkin       Samantha Goldrich
Max Goldstein          Holger Gollan          Teresa Gomez-Diaz
Ralph Gomory           Laureano Gonzalez-Vega Stephen Gortler
Johannes Grabmeier     Matt Grayson           Martin Griss
Andrey G. Grozin       Klaus Ebbe Grue        James Griesmer
Vladimir Grinberg      Oswald Gschnitzer      Ming Gu
Fred Gustavson         Jocelyn Guidry         Gaetan Hache
Steve Hague            Satoshi Hamaguchi      Sven Hammarling
Mike Hansen            Richard Hanson         Richard Harke
Joseph Harry           Bill Hart              Vilya Harvey
Martin Hassner         Arthur S. Hathaway     Dan Hatton
Waldek Hebisch         Karl Hegbloom          Ralf Hemmecke
Tony Hearn             Henderson              Antoine Hersen
Nicholas J. Higham     Lou Hodes              Alan Hoffman
Hoon Hong              Roger House            Joris van der Hoeven
Gernot Hueber          Pietro Iglio           Joan Jaffe
Alejandro Jakubi       Richard Jenks          Bo Kagstrom
William Kahan          Kyriakos Kalorkoti     Kai Kaminski
Matt Kaufmann          Grant Keady            Tom Kelsey
Wilfrid Kendall        Tony Kennedy           David Kincaid
Keshav Kini            Knut Korsvold          Ted Kosan
Paul Kosinski          Igor Kozachenko        Fred Krogh
Klaus Kusche           Bernhard Kutzler       Tim Lahey
Larry Lambe            Magnus Larsson         Kaj Laurson
Charles Lawson         George L. Legendre     Franz Lehner
Frederic Lehobey       Michel Levaud          Howard Levy
J. Lewis               Ren-Cang Li            Xin Li
John Lipson            Rudiger Loos           Craig Lucas
Michael Lucks          Richard Luczak         Camm Maguire
Dave Mainey            Francois Maltey        William Martin
Ursula Martin          Dan Martins            Osni Marques
Alasdair McAndrew      Bob McElrath           Michael McGettrick
Roland McGrath         Paul McJones           Bob McNeill
Edi Meier              Ian Meikle             David Mentre
Simon Michael          Jonathan Millen        Victor S. Miller
Gerard Milmeister      William Miranker       Mohammed Mobarak
H. Michael Moeller     Michael Monagan        Marc Moreno-Maza
Scott Morrison         Joel Moses             Mark Murray
William Naylor         Patrice Naudin         C. Andrew Neff
John Nelder            Godfrey Nolan          Arthur Norman
Jinzhong Niu           Michael O'Connor       Summat Oemrawsingh
Kostas Oikonomou       Humberto Ortiz-Zuazaga Julian A. Padget
Bill Page              David Parnas           Igor Pashev
Norm Pass              Susan Pelzel           Michel Petitot
Didier Pinchon         Ayal Pinkus            Frederick H. Pitts
Frank Pfenning         Erik Poll              Jose Alfredo Portes
E. Quintana-Orti       Gregorio Quintana-Orti Beresford Parlett
A. Petitet             Andre Platzer          Peter Poromaas
Greg Puhak             Claude Quitte          Arthur C. Ralfs
Norman Ramsey          Anatoly Raportirenko   Guilherme Reis
Huan Ren               Albert D. Rich         Michael Richardson
Jason Riedy            Renaud Rioboo          Robert Risch
Wilken Rivera          Jean Rivlin            Nicolas Robidoux
Simon Robinson         Raymond Rogers         Michael Rothstein
Martin Rubey           Jeff Rutter            R.W Ryniker II
Philip Santas          Grigory Sarnitskiy     David Saunders
Aleksej Saushev        Alfred Scheerhorn      William Schelter
Gerhard Schneider      Martin Schoenert       Marshall Schor
Frithjof Schulze       Fritz Schwartz         Jens Axel Segaard
Steven Segletes        Srinivasan Seshan      V. Sima
Nick Simicich          Peter Simons           William Sit
Elena Smirnova         Jacob Nyffeler Smith   Matthieu Sozeau
Richard Stallman       Ken Stanley            William Stein
Jonathan Steinbach     Alexander Stepanov     Doug Stewart
Fabio Stumbo           Christine Sundaresan   Ben Collins-Sussman
Klaus Sutner           Robert Sutor           Moss E. Sweedler
Eugene Surowitz        Yong Kiam Tan          Max Tegmark
T. Doug Telford        James Thatcher         Laurent Thery
Balbir Thomas          Mike Thomas            Carol Thompson
Simon Thompson         Dylan Thurston         Francoise Tisseur
Steve Toleque          Dick Toupin            Raymond Toy
Barry Trager           Hale Trotter           Themos T. Tsikas
Gregory Vanuxem        Kresimir Veselic       Christof Voemel
E.G. Wagner            Bernhard Wall          Justin Walker
Paul Wang              Stephen Watt           Andreas Weber
Jaap Weel              Al Weis                Juergen Weiss
M. Weller              Mark Wegman            James Wen
Thorsten Werther       Michael Wester         R. Clint Whaley
James T. Wheeler       John M. Wiley          Berhard Will
Clifton J. Williamson  Stephen Wilson         Shmuel Winograd
Robert Wisbauer        Sandra Wityak          Waldemar Wiwianka
Knut Wolf              Hans Peter Wuermli     Yanyang Xiao
Liu Xiaojun            Clifford Yapp          David Yun
Qian Yun               Vadim Zhytnikov        Paul Zimmermann
Richard Zippel         Wolfgang Zocher        Evelyn Zoernack
Bruno Zuercher         Dan Zwillinger  

Pervasive Literate Programming

I think David Diamond said it best (Datamation, June 1976, pg 134):

The fellow who designed it is working far away.
The spec's not been updated for many a livelong day.
The guy who implemented it is promoted up the line.
And some of the enhancements didn't match to the design.
They haven't kept the flowcharts, the manual's a mess.
And most of what you need to know, you'll simply have to guess.

and with respect to Axiom:

The research that it's based on is no longer to be had.
And the theory that it's based on has changed by just a tad.
If we keep it all together then at least there is a hope.
That the people who maintain it will have a chance to cope.

To quote Fred Brooks, "The Mythical Man-month"

  "A basic principle of data processing teaches the folly of trying to
   maintain independent files in synchronization... Yet our practice in
   programming documentation violates our own teaching. We typically
   attempt to maintain a machine-readable form of a program and an
   independent set of human-readable documentation, consisting of prose
   and flowcharts ... The solution, I think, is to merge the files, to
   incorporate the documentation in the source program."


   "A common fallacy is to assume authors of incomprehensilbe code
    will somehow be able to express themselves lucidly and clearly
    in comments." -- Kevlin Henney

   "A programmer who cannot explain their ideas clearly in natural
    language is incapable of writing readable code." -- Tim Daly

As you can already see from this document the whole of the Axiom
effort is structured around literate programs. Every directory has a
Makefile.pamphlet file which explains details of that directory. The
whole source tree hangs from the Makefile tree. (Some of the
Makefile.pamphlet files contain only text if executable code is not
needed).  Every source file is embedded in a pamphlet file.

Which begs the question: ``What is a pamphlet file?''.  Basically it
is a tex document with some additional markup tags that surround
source code. Pamphlet files are intended to document one particular
subject. Pamphlet files can be later combined into ``booklet'' files
as one would embed chapters into books.

Which begs the question: ``Why bother with pamphlet files?''.  Clearly
you didn't read the philosophy rant above. In more detail there have
been two traditional methods of documenting source code. The first is
to sprinkle random comments into the code.  This suffers from the
problem that the comments assume you already understand the purpose of
the code and why an enlightened comment like ``This oughta work'' is
perfectly clear and compelling. The second method is to write a
document as a separate file. They get written half-heartedly because
the lack of source code allows you to skip over explaining ugly
implementation details (where all of the real confusion lies). This
form of documentation never gets updated and gradually becomes
uninteresting history.

Pamphlet files overcome neither of these limitations if you don't make
the effort to do it right. Ask yourself the question ``What would
Knuth do?'' or ``Will this be clear 30 years from now?''.

Which begs the question: ``Why go to all this trouble?''.  Because
you're having a conversation with people who are far removed from you
in time, space, and understanding.  Because someone else will have to
maintain your code.  Because you are part of a community of
mathematicians who hold you to high standards. Because if you can't
explain it clearly maybe YOU don't understand it or it isn't as clear
as you think it is.

Lets imagine that we'd like to receive a pamphlet file from a
colleague. It contains a new theory and spiffy new algorithm.  We'd
like to be able to put the pamphlet file into the system and have
everything magically happen to integrate the new pamphlet into the
system. What would that imply? Well, lets assume that the pamphlet
file has certain required sections. We'd like to get more than the
technical paper and the code. We'd also like to see the help
information, test cases, example code, cross-references to other
pamphlets that would get automatically included, have the proof
available and automatically checkable, etc. In the best of all
possible worlds we have a front-end system that knows nothing except
how to deconstruct and integrate properly formed pamphlet files. If
this were true we could be sure that all of the mathematics is
documented and external to the system. There are no ``rabbits'' (as
Dijkstra called surprises or special knowledge) that we pull out of
our hat. Conceptually, given an underlying Lisp system, it is clear we
can built such a system.

The General Directory Structure

The Top Level directory structure contains 7 directories which are
explained in detail below. Three of the directories (license, zips,
and lsp) are not part of the essential core of Axiom.

The other four directories (src, int, obj, and mnt) comprise the
system build environment. Each directory has a specific purpose. Lets
look at the essential directories first.

$AXIOM
  license
  lsp
    GCL
  src
    include
    lib
    scripts
  int
    doc
  obj
    tmp
    noweb
    SYS=(linux,...)
  mnt
    SYS=(linux,...)
  zips

The src directory consists of human-written, system-independent
code. You can copy this directory (and the top-level makefiles) and
have a complete build system. Nothing in this directory is ever
changed by the Makefiles and it can be mounted in a read-only fashion
during the build process. An example file would be the lisp source
files.

The int directory consists of machine-generated, system-independent
code. Consider this directory as a cache. Nothing in this directory is
necessary for a clean system build but once the build completes the
information in this directory can significantly shorten rebuilds.
Since this information is system-independent we can use the cache no
matter what architecture we target. An example file would be the dvi
files generated from the tex sources.

The obj directory consists of machine-generated, system-dependent
code. This directory is "scratch" space for the compiler and other
tools. Nothing in this directory is useful once the system is
built. An example file would be the .o files from the C compiler.

The mnt directory consists of machine-generated, system-dependent code
that will comprise the "shipped system". You can copy this directory
and have a complete, running Axiom system. If the end user will see it
or need it in any way it belongs here. Executables are generally built
in obj and moved here. Example files would be the final executable
images, the input files, etc.

The four directories above make it possible to do a system build for
one system (say, a linux system) which will fill in the int
subdirectory. Then you can NFS mount the src and int directories
read-only on a Solaris machine and do a solaris system build.  The
original Axiom could build across many different architectures,
compilers, and operating systems.

The license directory

The license directory collects all of the licenses for material that
is included in this distribution. Source files contain a line that
refers to one of these license files. Some people are of the belief
that including the full license text in every source file magically
strengthens the license but this is not so.  Imagine including the
full text of the copyright at the beginning of every section of a book.

The LICENSE.AXIOM file is a Modified BSD-style license that covers all
of the files released as part of this distribution except as noted in
particular files. Copyright information that might have shown up in
source files that were released from NAG are also collected here and
noted at the top of the files they cover.

The zips directory

The zips directory contains particular distributions of
network-available software that is known to work with this release of
Axiom. Newer versions may work and, if so, should be added to this
directory. The makefiles that handle these files will unpack them into
the correct locations in the src directory tree. These files exist to
increase the stability of the distribution so we can guarantee that
the code works. We encourage testing the latest distributions so that
we can remain with the leading edge and give feedback to the
individual package developers if problems arise.

The lsp directory

Axiom lives on top of Common Lisp, specifically Gnu Common Lisp (GCL)

Steps to build Axiom

The Initial Distribution files

The initial distribution contains several top level files. These are:

1) Makefile.pamphlet
     This is the noweb source for the Makefile file. All changes to
     the Makefile should occur here and the

3) Makefile This is the actual Makefile that will create Axiom. 

In general the distribution will contain the pamphlet files for each
source file and the source file itself. Modifications should be made
and explained in the pamphlet files. The document command should be
run to rebuild the source file and the dvi file.

Steps in the build process

The sequence of steps necessary to build a clean Axiom is simply:

  export AXIOM=(path-including-this-directory)/mnt/SYSNAME
  export PATH=$AXIOM/bin:$PATH
  make

If this fails check the FAQ for possible problems and their fixes.