File: bookvol0.pamphlet

package info (click to toggle)
axiom 20170501-6
links: PTS
area: main
in suites: bullseye
size: 1,050,164 kB
sloc: javascript: 8,042; lisp: 3,600; makefile: 505; cpp: 223; ansic: 181; sh: 96
file content (89374 lines) | stat: -rw-r--r-- 2,738,661 bytes
parent folder | download | duplicates (3)
\documentclass[dvipdfmx]{book}
\newcommand{\VolumeName}{Volume 0: Axiom Jenks and Sutor}
\input{bookheader.tex}
%Original Page vii

{\Large{\bf Foreword}}
\vskip .25in

You are holding in your hands an unusual book.  Winston Churchill once
said that the empires of the future will be empires of the mind.  This
book might hold an electronic key to such an empire.

When computers were young and slow, the emerging computer science
developed dreams of Artificial Intelligence and Automatic Theorem
Proving in which theorems can be proved by machines instead of
mathematicians.  Now, when computer hardware has matured and become
cheaper and faster, there is not too much talk of putting the burden
of formulating and proving theorems on the computer's shoulders.
Moreover, even in those cases when computer programs do prove
theorems, or establish counter-examples (for example, the solution of
the four color problem, the non-existence of projective planes of
order 10, the disproof of the Mertens conjecture), humans carry most
of the burden in the form of programming and verification.

It is the language of computer programming that has turned out to be
the crucial instrument of productivity in the evolution of scientific
computing.  The original Artificial Intelligence efforts gave birth to
the first symbolic manipulation systems based on LISP.  The first
complete symbolic manipulation or, as they are called now, computer
algebra packages tried to imbed the development programming and
execution of mathematical problems into a framework of familiar
symbolic notations, operations and conventions.  In the third decade
of symbolic computations, a couple of these early systems---REDUCE and
MACSYMA---still hold their own among faithful users.

%Original Page viii

Axiom was born in the mid-70's as a system called Scratchpad
developed by IBM researchers.  Scratchpad/Axiom was born big---its
original platform was an IBM mainframe 3081, and later a 3090.  The
system was growing and learning during the decade of the 80's, and its
development and progress influenced the field of computer algebra.
During this period, the first commercially available computer algebra
packages for mini and and microcomputers made their debut.  By now,
our readers are aware of Mathematica, Maple, Derive, and Macsyma.
These systems (as well as a few special purpose computer algebra
packages in academia) emphasize ease of operation and standard
scientific conventions, and come with a prepared set of mathematical
solutions for typical tasks confronting an applied scientist or an
engineer.  These features brought a recognition of the enormous
benefits of computer algebra to the widest circles of scientists and
engineers.

The Scratchpad system took its time to blossom into the beautiful
Axiom product.  There is no rival to this powerful environment in
its scope and, most importantly, in its structure and organization.
Axiom contains the basis for any comprehensive and elaborate
mathematical development.  It gives the user all Foundation and
Algebra instruments necessary to develop a computer realization of
sophisticated mathematical objects in exactly the way a mathematician
would do it.  Axiom is also the basis of a complete scientific
cyberspace---it provides an environment for mathematical objects used
in scientific computation, and the means of controlling and
communicating between these objects.  Knowledge of only a few Axiom
language features and operating principles is all that is required to
make impressive progress in a given domain of interest.  The system is
powerful.  It is not an interactive interpretive environment operating
only in response to one line commands---it is a complete language with
rich syntax and a full compiler.  Mathematics can be developed and
explored with ease by the user of Axiom.  In fact, during
Axiom's growth cycle, many detailed mathematical domains were
constructed.  Some of them are a part of Axiom's core and are
described in this book.  For a bird's eye view of the algebra
hierarchy of Axiom, glance inside the book cover.

The crucial strength of Axiom lies in its excellent structural
features and unlimited expandability---it is open, modular system
designed to support an ever growing number of facilities with minimal
increase in structural complexity.  Its design also supports the
integration of other computation tools such as numerical software
libraries written in FORTRAN and C.  While Axiom is already a
very powerful system, the prospect of scientists using the system to
develop their own fields of Science is truly exciting---the day is
still young for Axiom.

%Original Page ix

Over the last several years Scratchpad/Axiom has scored many
successes in theoretical mathematics, mathematical physics,
combinatorics, digital signal processing, cryptography and parallel
processing.  We have to confess that we enjoyed using
Scratchpad/Axiom.  It provided us with an excellent environment for
our research, and allowed us to solve problems intractable on other
systems.  We were able to prove new diophantine results for $\pi$;
establish the Grothendieck conjecture for certain classes of linear
differential equations; study the arithmetic properties of the
uniformization of hyperelliptic and other algebraic curves; construct
new factorization algorithms based on formal groups; within
Scratchpad/Axiom we were able to obtain new identities needed for
quantum field theory (elliptic genus formula and double scaling limit
for quantum gravity), and classify period relations for CM varieties
in terms of hypergeometric series.

The Axiom system is now supported and distributed by NAG, the group
that is well known for its high quality software products for
numerical and statistical computations.  The development of Axiom
in IBM was conducted at IBM T.J. Watson Research Center at Yorktown,
New York by a symbolic computation group headed by Richard D. Jenks.
Shmuel Winograd of IBM was instrumental in the progress of symbolic
research at IBM.

This book opens the wonderful world of Axiom, guiding the reader
and user through Axiom's definitions, rules, applications and
interfaces.  A variety of fully developed areas of mathematics are
presented as packages, and the user is well advised to take advantage
of the sophisticated realization of familiar mathematics.  The
Axiom book is easy to read and the Axiom system is easy to use.
It possesses all the features required of a modern computer
environment (for example, windowing, integration of operating system
features, and interactive graphics).  Axiom comes with a detailed
hypertext interface (HyperDoc), an elaborate browser, and complete
on-line documentation.  The HyperDoc allows novices to solve their
problems in a straightforward way, by providing menus for step-by-step
interactive entry.

The appearance of Axiom in the scientific market moves symbolic
computing into a higher plane, where scientists can formulate their
statements in their own language and receive computer assistance in
their proofs.  Axiom's performance on workstations is truly
impressive, and users of Axiom will get more from them than we, the
early users, got from mainframes.  Axiom provides a powerful
scientific environment for easy construction of mathematical tools and
algorithms; it is a symbolic manipulation system, and a high
performance numerical system, with full graphics capabilities.  We
expect every (computer) power hungry scientist will want to take full
advantage of Axiom.

\vskip .25in
%\noindent
David V. Chudnovsky  \hfill             Gregory V. Chudnovsky
\vfill
\newpage
\addcontentsline{toc}{chapter}{Contributors}

The field of Computational Mathematics is here to stay as it is
the collision of computers and mathematics, both of which will
continue. As a field, we need to develop a sense of history.

Computational Mathematics is, historically speaking, quite a young
field dating as it does from the 1960s. We have access to some of the
source code from these systems. That source code forms the ``Newton's
notebooks'' of the field. Some of the source codes for these
influential systems disappeared with the company, such as Derive and
Macsyma. Some, like Maple and Mathematica, are commercial and it is
not clear if the source code will survive.  Others, like Reduce, were
publicly released but are no longer maintained. Axiom is, on all
counts, an exception.

Axiom is quite old, unlike most open source software. 
In fact, old enough to outlive the original IBM authors. 
So it is with this sense of history, made by real people,
that we record the obituaries of the original project members.

May they rest in peace.

\addcontentsline{toc}{section}{Obituary -- Richard Dimick Jenks}
\includegraphics[scale=0.75]{ps/jenks.eps}
\begin{verbatim}
+---------------------------------------------------------------------+
|                      Richard Dimick Jenks                           |
|           Axiom Developer and Computer Algebra Pioneer              |
|                                                                     |
| Richard D. Jenks was born on November 16, 1937 in Dixon, Illinois,  |
| where he grew up. During his childhood he learned to play the       |
| organ and sang in the church choir thereby developing a life-long   |
| passion for music.                                                  |
|                                                                     |
| He received his PhD in mathematics from the University of Illinois  |
| at Urbana-Champaign in 1966. The title of his dissertation was      |
| ``Quadratic Differential Systems for Mathematical Models" and was   |
| written under the supervision of Donald Gilles. After completing    |
| his PhD, he was a post-doctoral fellow at Brookhaven National       |
| Laboratory on Long Island. In 1968 he joined IBM Research where he  |
| worked until his retirement in 2002.                                |
|                                                                     |
| At IBM he was a principal architect of the Scratchpad system, one   |
| of the earliest computer algebra systems(1971). Dick always         |
| believed that natural user interfaces were essential and developed  |
| a user-friendly rule-based system for Scratchpad. Although this     |
| rule-based approach was easy to use, as algorithms for computer     |
| algebra became more complicated, he began to understand that an     |
| abstract data type approach would give sophisticated algorithm      |
| development considerably more leverage. In 1977 he began the Axiom  |
| development (originally called Scratchpad II) with the design of    |
| MODLISP, a merger of Lisp with types (modes). In 1980, with the     |
| help of many others, he completed an initial prototype design       |
| based on categories and domains that were intended to be natural    |
| for mathematically sophisticated users.                             |
|                                                                     |
| During this period many researchers in computer algebra visited     |
| IBM Research in Yorktown Heights and contributed to the development |
| of the Axiom system. All this activity made the computer algebra    |
| group at IBM one of the leading centers for research in this area   |
| and Dick was always there to organize the visits and provide a      |
| stimulating and pleasant working environment for everyone. He had   |
| a good perspective on the most important research directions and    |
| worked to attract world-renowned experts to visit and interact      |
| with his group. He was an ideal manager for whom to work, one who   |
| always put the project and the needs of the group members first.    |
| It was a joy to work in such a vibrant and stimulating environment. |
|                                                                     |
| After many years of development, a decision was made to rename      |
| Scratchpad II to Axiom and to release it as a product. Dick and     |
| Robert Sutor were the primary authors of the book Axiom: The        |
| Scientific Computation System. In the foreword of the book,         |
| written by David and Gregory Chudnovsky, it is stated that ``The    |
| Scratchpad system took its time to blossom into the beautiful       |
| Axiom product. There is no rival to this powerful environment in    |
| its scope and, most importantly, in its structure and organization. |
| Axiom was recently made available as free software.                 |
| See http://axiom-developer.org                                      |
|                                                                     |
| Dick was active in service to the computer algebra community as     |
| well. Here are some highlights. He served as Chair of ACM SIGSAM    |
| (1979-81) and Conference Co-chair (with J. A. van Hulzen) of        |
| EUROSAM '84, a precursor of the ISSAC meetings. Dick also had a     |
| long period of service on the editorial board of the Journal of     |
| Symbolic Computation. At ISSAC '95 in Montreal, Dick was elected to |
| the initial ISSAC Steering Committee and was elected as the second  |
| Chair of the Committee in 1997. He, along with David Chudnovsky,    |
| organized the highly successful meetings on Computers and           |
| Mathematics that were held at Stanford in 1986 and MIT in 1989.     |
|                                                                     |
| Dick had many interests outside of his professional pursuits        |
| including reading, travel, physical fitness, and especially music.  |
| Dick was an accomplished pianist, organist, and vocalist. At one    |
| point he was the organist and choirmaster of the Church of the Holy | 
| Communion in Mahopac, NY. In the 1980s and 1990s, he sang in choral |
| groups under the direction of Dr. Dennis Keene that performed at    |
| Lincoln Center in New York city.                                    |
|                                                                     |
| Especially important to him was his family: his eldest son Doug and |
| his wife Patricia, his son Daniel and his wife Mercedes, a daughter |
| Susan, his brother Albert and his wife Barbara, his sister Diane    |
| Alabaster and her husband Harold, his grandchildren Douglas,        |
| Valerie, Ryan, and Daniel Richard, and step-granddaughter Danielle. |
| His longtime companion, Barbara Gatje, shared his love for music,   |
| traveling, Point O'Woods, and life in general.                      |
|                                                                     |
| On December 30, 2003, Dick Jenks died at the age of 66, after an    |
| extended and courageous battle with multiple system                 |
| atrophy. Personally, Dick was warm, generous, and outgoing with     |
| many friends. He will be missed for his technical accomplishments,  |
| his artist talents, and most of all for his positive, gentle,       |
| charming spirit.                                                    |
|                                                                     |
| Prepared by Bob Caviness, Barry Trager, and Patrizia Gianni with    |
| contributions from Barbara Gatje, James H. Griesmer, Tony Hearn,    |
| Manuel Bronstein, and Erich Kaltofen.                               |
+---------------------------------------------------------------------+
\end{verbatim}
\newpage
\addcontentsline{toc}{section}{Obituary -- Manuel Bronstein}
\includegraphics{ps/bronstein.eps}
\begin{verbatim}
+-------------------------------------------------------------------------+
|                        Manuel Bronstein                                 |
|                                                                         |
| On June 6, 2005, Manuel Bronstein -- a prominent scientist whose        |
| contribution to computer algebra and many other areas of mathematics    |
| and computer science can hardly be overestimated -- died of a heart     |
| attack. He was only forty-one.                                          |
|                                                                         |
| A truly talented man, who was endlessly devoted to science, has         |
| passed away. Manuel worked with all his strength, enthusiastically,     |
| and was always researching several difficult problems simultaneously.   |
| Everyone who knew him remembers that he was witty, extremely keen in    |
| intellect, and cheerful. When not working, he could take part in        |
| discussions on diverse topics, and his partners admired him for his     |
| sudden impromptus, jokes, felicitous remarks, and unexpected            |
| viewpoints on the many little nothings of life.                         |
|                                                                         |
| Manuel was born on August 28, 1963, near Paris. His father was a        |
| physician, and his mother was a sculptor. Having graduated from         |
| school in France, he entered Berkeley University (USA, California),     |
| where, in 1987, he defended his PhD thesis under the supervision of     |
| Professor M. Rosenlicht. For three years, he worked at the IBM          |
| Research Center, then, from 1990 to 1997, and since 1997, in France,    |
| in the French National Institute for Research in Informatics and        |
| Automation (INRIA) in Sophia Antipolis.                                 |
|                                                                         |
| The dissertation defended at Berkeley was devoted to a very difficult   |
| problem related to symbolic integration (or integration in finite       |
| terms). Although the theory of integration was developed by R. Risch    |
| (another Ph.D. student of Rosenlicht) who presented in 1968 an          |
| algorithm for integration of elementary functions, it turned out        |
| that this algorithm was far from effective. Manuel significantly        |
| improved it (in particular, by generalizing B. Trager's algorithm       |
| for algebraic functions to an algorithm for the mixed case of           |
| elementary functions). While working for IBM, he implemented the        |
| integration algorithm in the Axiom system. At that time, this was the   |
| most powerful program for integration of functions. Manuel presented    |
| results of his studies in a large article published in 1990 in the      |
| Journal of Symbolic Computation. Later, he intended to write a          |
| monograph in two volumes devoted to all aspects of symbolic             |
| integration. The first volume was written and went through two          |
| editions at the Springer publishing house in 1997 and 2004. The         |
| second volume remained uncompleted.                                     |
|                                                                         |
| It was typical of Manuel to concentrate on urgent difficult problems.   |
| After the problem of integration, he studied the problem of searching   |
| for closed-form solutions to ordinary linear differential equations.    |
| In particular, in 1992, he designed a rather general algorithm for      |
| finding solutions in the field generated by the coefficients of the     |
| equation. In construction of these solutions, one usually proceeds      |
| from a tower of extensions of the basic field. However, the key point   |
| is the possibility of finding solutions in the basic field, which       |
| contains the coefficients. This demonstrates the exceptional value      |
| of this result by Manuel. Many problems of differential algebra         |
| have analogues in the difference case. It is also well known that,      |
| as a rule, these difference analogues are much more difficult to        |
| solve. Nevertheless, in 2000, Manuel developed an algorithm for         |
| searching for solutions in the field of coefficients for the case of    |
| difference equations. Moreover, he constructed a universal general      |
| algorithm that covers differential, difference, and q-difference        |
| equations as special cases. This universality was attained by           |
| considering the problem on the level of noncommutative Ore polynomials. |
| At the same time, he significantly advanced in the development of the   |
| theory of unimonomial field extensions, whose foundations were laid     |
| by M. Karr in the early 1980s. These results allowed a number of        |
| well-known algorithms for searching for various solutions of linear     |
| ordinary equations with polynomial coefficients to be generalized to    |
| much more complicated situations.                                       |
|                                                                         |
| A for the Ore polynomials, it should be emphasized that the very idea   |
| of using them in computer algebra was first proposed by Manuel          |
| (together with M. Petrovsek) in a paper published in Programming and    |
| Computer Software in 1994. This idea was important not only from the    |
| theoretical standpoint: it also demonstrated the possibility of         |
| designing universal computer programs adjustable to the differential,   |
| difference, and some other cases. This approach is widely used          |
| nowadays by developers of computer algebra algorithms and systems.      |
|                                                                         |
| The aforementioned paper devoted to this universal approach is not      |
| the only publication by Manuel in Programming and Computer Software.    |
| In 1992, he published a survey of methods for solving ordinary          |
| differential equations and integration in this journal. With the        |
| help of this survey, many specialists actively working in related       |
| scientific areas managed to penetrate into this involved subject.       |
| In 1993, Manuel was a co-editor of a special issue of Programming       |
| and Computer Software devoted to computer algebra.                      |
|                                                                         |
| Far from intending to give here a complete survey of Manuel's results,  |
| we mention only that he obtained many profound and valuable results     |
| not only on integration and ordinary differential and difference        |
| equations, but also on special functions, partial differential          |
| equations, operator factorization, and reducibility of systems of       |
| equations to special forms. He also published nice works on linear      |
| algebra, algebraic geometry, etc.                                       |
|                                                                         |
| Manual was a brilliant programmer. He artistically implemented all      |
| his algorithms in a number of computer algebra systems. Recently, he    |
| actively worked on the Aldor system and wrote a family of computer      |
| algebraic libraries for it, namely, the libaldor and Algebra            |
| libraries (which provide the user with basic data structures and        |
| their operation procedures that are necessary for spplications of       |
| computer algebra) and the Sumit library (which contains efficient       |
| programs implementing complex modern algorithms for transforming and    |
| solving linear ordinary differential and difference equations. For      |
| the Sumit library, he also developed two interactive interfaces,        |
| bernina and shasta, which made the functions of this library            |
| available from other computer algebra systems. These libraries and      |
| interactive interfaces are high-quality tools that are widely used      |
| in many research centers.                                               |
|                                                                         |
| As noted earlier, since 1997, Manuel worked at INRIA. At this           |
| institute (his last place of work), he headed a research group          |
| consisting of first-rate specialists. Each of them worked on his or     |
| her particular scientific problem, and witnesses of his discussions     |
| with collaborators were amazed by a deep insight of Manuel into all     |
| these problems and by his ability to easily pass in these discussions   |
| from one problem to another. The intellectual virtuosity that he        |
| demonstrated in these discussions was magnificent.                      |
|                                                                         |
| Manuel was a member of Editorial Boards of some leading journals and    |
| scientific series, for instance, the Journal of Symbolic Computation    |
| and the series Algorithms and Computation in Mathematics. He was a      |
| member of the program and organizing committees of several respected    |
| conferences and often chaired these committees. This particularly       |
| relates to the annual international ISSAC conference. He was also a     |
| vice-president of SIGSAM, the international group on symbolic and       |
| algebraic manipulation. In this role, he proposed and realized many     |
| fruitful ideas. For instance, for the ISSAC'05 conference, which was    |
| held in July of 2005, he had prepared a CD that contained not only      |
| texts of all the talks given at the conference but also some new        |
| software and other information valuable for everone interested in       |
| computer algebra and its applications. Unfortunately, he was not to     |
| take part in that conference. That CD was distributed to all the        |
| participants of the conferene and will remind them of Manuel.           |
|                                                                         |
| He participated fruitfully in international research projects. For      |
| instance, in the 1990s, he was one of the leaders of the European       |
| projects Cathode 1 and Cathode 2 devoted to computer-algebraic          |
| methods for solving ordinary differential equations. During the last    |
| ten years, Manuel co-headed some projects involving Russina             |
| scientists, namely, "Computer algebra and linear functional             |
| equations" (RFBR-INTAS), Direct computer-algebraic methods for          |
| explicit solution of systems of linear functional equations"            |
| (French--Russian Lyapunov Center), and "Computer algebra and            |
| (q-)hypergeomtric terms" (Eco-Net program of the French Ministry of     |
| Foreign Affairs). His last voyage abroad was to Russia on May 15-19,    |
| 2005, within the framework of the Eco-Net program.                      |
|                                                                         |
| It should be noted that Manuel was particularly interested in Russia    |
| and events there. It is appropriate to mention that his father's        |
| family had Russian roots and Manuel himself had chosen Russian as the   |
| foreign language to study at high school (he told that, on the final    |
| exam, he had to read a passage from "Second Lieutenant Kizhe" by Yu.    |
| N. Tynyanov). Later, he read scientific journals in Russian and even    |
| translated some papers. And when he met his future wife Karola in       |
| Leipzig in 1990, the Russian language helped them to communicate,       |
| although it was not a native tongue to either.                          |
|                                                                         |
| Remembering the joint work with Manuel, we would like to mention his    |
| remarkable ability to grasp instantly mathematical ideas and the        |
| extraordinary mental agility, which followed from his acute analytical  |
| sense. If a problem that arose in a discussion at the blackboard or     |
| was proposed by somebody was of interest to Manuel, he, as a rule,      |
| immediately proposed several approaches to solving it, including        |
| quite unusual and promising ones. Having outlined these approaches,     |
| he immediately started to develop them in detail. He made some          |
| calculations on the blackboard so fast that, sometimes, it was hard     |
| to follow them. As a result of such improvisation, either the question  |
| was completely answered or real obstacles for further investigation     |
| were found. And Manuel often performed such analyses without any        |
| intention to be a coauthor of the work. He was a benevolent man and     |
| readily gave detailed answers to questions of people whom he scarcely   |
| knew, who asked him for a consultation or advice during a break of a    |
| conference.                                                             |
|                                                                         |
| Of course, Manuel's scientific interests were not restricted to only    |
| difficult classical problems. Computer algebra is known to have at      |
| its disposal complete algorithms for solving a number of such problems. |
| However, the computational complexity of these algorithms is very high, |
| and they are hard to implement. Manuel was interested in consideration  |
| of special cases of these problems and in simplifying and refining      |
| algorithms by using heuristics and other methods. The results of his    |
| work in this area included a new version of the algorithm of parallel   |
| integration (the first versions of the algorithms of parallel           |
| integraion were proposed in the late 1970s and early 1980s by A.        |
| Norman, P. Moore, and J. Davenport; here, the term "parallel" does      |
| not relate to multiprocessor execution, and Manuel suggested replacing  |
| this term with "flat integration"). In general, this algorithm is not   |
| as powerful as the complete version of the Risch--Bronstein algorithm   |
| for symbolic integration; however, it may be implemented in just a      |
| hundred lines of code. A note on the algorithm of parallel integration  |
| is published in this issue of Programming and Computer Software. This   |
| note is an extended abstract of Manuel's talk at the joint seminar on   |
| computer algebra of the MSU and JINR (Joint Institute for Nuclear       |
| Reserach) in Dubna on May 18, 2005. It as submitted for publication     |
| in Programming and Computer Software on June 3, three days before his   |
| death overtook him outside his hometown, in Montpellier. He went there  |
| for a few days to discuss with biologists the possibility of describing |
| some bilogical models by recurrence relations of a special form. Manuel |
| was going to try to solve these relations using an original approach    |
| he was working on in his last days. The stock of his ideas and          |
| intentions seemed to be endless...                                      |
|                                                                         |
| Providing for his large family (he was the father of six children),     |
| he was always ready to support his friends, colleagues, and associates, |
| and helped them any time when he felt that they needed his assistance   |
| or sympathy. He never stopped being friendly to people around him.      |
|                                                                         |
| Manuel was just as benevolent and kind as he was outstandingly          |
| talented. His name and his accomplishments in computer algebra have     |
| already found their place in sciences. His death is a grevious,         |
| irreplaceable loss for everyone who was lucky to work with him or       |
| just be acquainted with him.                                            |
+-------------------------------------------------------------------------+
\end{verbatim}
Reprinted with permission of S.A. Abramov, published in \cite{Abra06}

\newpage
\addcontentsline{toc}{section}{Obituary -- Christine Jeanne O'Connor}
\includegraphics{ps/chrisoconnor.eps}
\begin{verbatim}
+-------------------------------------------------------------------------+
|                        Christine Jeanne O'Connor                        |
|                                                                         |
| Christine O'Connor, born in Chicago, Illinois, on March 17, 1951,       |
| passed away peacefully on January 18, 2008, after a year-long battle    |
| with carcinoid cancer. She was 56. Her family was with her.             |
|                                                                         |
| Christine O'Connor is survived by her loving husband, Michael O'Connor, |
| her two sons, Ken Sundaresan and Eric O'Connor, her mother, Ruth Riemer,|
| and her sister, Susan Wright.                                           |
|                                                                         |
| Christine was reared by her parents, Ed and Ruth Riemer, in the Chicago |
| area until her adolescent years, when the family moved to Champaign-    |
| Urbana, Illinois. Chris graduated from high school there and then       |
| returned to the Chicago area to attend Northwestern University, from    |
| which she received baccalaureate and masters degrees in Psychology.     |
|                                                                         |
| After graduation, Christine worked in Chicage doing medical research    |
| and founding a support and care integration group for babies suffering  |
| from Spina Bifida. She met her first husband, Dr. N. Sundaresan, and    |
| Christine was blessed with the birth of her first son, Ken Sundaresan.  |
| The family moved to New York. Several years later, Christine and Dr.    |
| Sundaresan were divorced, although they remained friends.               |
|                                                                         |
| Chris then becamse fascinated by the PC revolution, obtained a master's |
| degree in Computer Science from The Courant School of Mathematics of    |
| NYU, and started work in computer research at IBM's T.J. Watson         |
| Research Center in Yorktown Heights, New York. She met Michael O'Connor |
| there. They fell in love and were married, and Christine was blessed    |
| by the birth of her second son, Eric O'Connor.                          |
|                                                                         |
| Christine was a member of the Scratchpad group under Richard Jenks.     |
| She wrote the original draft of the User Manual on which this book      |
| is based. Both she and her husband, Michael were active contributors    |
| to Axiom.                                                               |
|                                                                         |
| Chris moved to Mahopac. She was actively involved in local historical   |
| research and in work with The Town of Carmel Historical Society. She    |
| was an avid gardener, loved flowers, and belonge to The Lake Mahopac    |
| Garden Club. She was an active member and officer of the Mahopac Hills  |
| Association. She loved to sing and sang in the choir of First           |
| Presbyterian Church. She worked in charities like Eagle Eye Too that    |
| supports the local hospital.                                            |
+-------------------------------------------------------------------------+
\end{verbatim}
From \cite{OCon08}, with modifications by Tim Daly

\newpage
\addcontentsline{toc}{section}{Obituary -- William Frederick Schelter}
\includegraphics[scale=1.0]{ps/schelter.eps}
\begin{verbatim}
+---------------------------------------------------------------------+
|                    William Frederick Schelter                       |
|           Axiom Developer and GNU Common Lisp Author                |
|                                                                     |
| William F. Schelter was born in Canada in 1947. He received a Ph.D. |
| from McGill University in 1972. His training was in computational   |
| algebra and its applications, and he was one of the pioneers of     |
| non-commutative algebraic geometry. He also worked on symbolic      |
| computational systems, compilers, and algorithms. His theses was on |
| "Rings of Quotients" under Joachim Lambek.                          |
|                                                                     |
| William was a professor of mathematics at the University of Texas   |
| at Austin. He co-authored, with Shang-Ching Chou, a paper on        |
| "Proving geometry theorems with rewrite rules" in 1987.             |
|                                                                     |
| William started with Kyoto Common Lisp (KCL) and built Austin       |
| Kyoto Common Lisp (AKCL), partially under contract to IBM with      |
| the Scratchpad project. AKCL eventually became GNU Common Lisp      |
| (GCL). GCL is still Axiom's primary Common Lisp platorm.            |
|                                                                     |
| William spent many days sharing my (Tim Daly) office at IBM. At one |
| time he found an Emacs bug, fetched the source, fixed it, created   |
| a patch, sent it off, and continued working. As a side-effect he    |
| introduced me to free software and the ability to participate.      |
|                                                                     |
| On two separate visits I returned to my office to find that all of  |
| my several hundred carefully indexed technical papers in a large    |
| pile on the floor because the shelves had failed. Oddly this never  |
| happened when he wasn't there. It became a running joke between us. |
|                                                                     |
| William and I collaborated on various aspects of AKCL, including    |
| portions of the garbage collection and tail recursion elimiation.   |
| He was a brilliant programmer and exceptionally easy to work with.  |
| We spent many phone hours designing Axiom-specific optimizations.   |
|                                                                     |
| William rescued the early source code for Macsyma, prior to the     |
| Symbolics proprietary version. He created Maxima and continued to   |
| enhance it.                                                         |
|                                                                     |
| William was the first to port the GNU C Compiler to the PC, which   |
| was used in the original Linux kernel implementation.               |
|                                                                     |
| William died on July 30, 2001 at the age of 54.                     |
|                                                                     |
| My son (Tim Daly Jr.) called me with the news. I called Barry       |
| Trager, who already knew. Barry mentioned that Axiom was taken off  |
| the market by the Numerical Algorithms Group (NAG). I contacted NAG |
| and got the Axiom source code and permission to release it as free  |
| software. So, even in death, William managed to bring Axiom to the  |
| free software world.                                                |
|                                                                     |
| William was in Russia at the time of his death with his wife, Olga, |
| whom he had recently married. He is survived by his son, John, his  |
| daughter Karen Lewis and husband Mike, and a grandson Joshua Lewis. |
|                                                                     |
+---------------------------------------------------------------------+
\end{verbatim}

\newpage
%Original Page xxi

\pseudoChapter{\Huge Contributors}
The design and development of Axiom was led by the Symbolic Computation
Group of the Mathematical Sciences Department, IBM Thomas J. Watson
Research Center, Yorktown Heights, New York. The current implemention
of Axiom is the product of many people. The primary contributors are:

{\bf Richard D. Jenks} (IBM, Yorktown) received a Ph.D. from the University
of Illinois and was a principal architect of the {\bf Scratchpad} computer
algebra system (1971). In 1977, Jenks initiated the Axiom effort with
the design of MODLISP, inspired by earlier work with R\"udiger Loos
(T\"ubingen), James Griesmer (IBM, Yorktown), and David Y. Y. Yun (Hawaii).
Joint work with David R. Barton (Berkeley, California) and James Davenport
led to the design and implementation of prototypes and the concept of
categories (1980). Mor recently, Jenks led the effort on user interface
software for Axiom.

{\bf Barry M. Trager} (IBM, Yorktown) received a Ph.D. from MIT while
working in the {\bf MACSYMA} computer algebra group. Trager's thesis
laid the groundwork for a complete theory for closed-form integration
of elementary functions and its implementation in Axiom. Trager and
Richrd Jenks are responsible for the original abstract datatype design
and implementation of the programming language with its current
MODLISP-based compiler and run-time system. Trager is also responsible
for the overall design of the current Axiom library and for the
implementation of many of its components.

{\bf Stephen M. Watt} (IBM, Yorktown) received a Ph.D. from the
University of Waterloo and is one of the original authors of the {\bf
Maple} computer algebra system. Since joining IBM in 1984, he has made
central contributions to the Axiom language and system design, as well
as numerous contributions to the library. He is the principal
architect of the new Axiom compiler, planned for Release 2.

%Original Page xxii


{\bf Robert S. Sutor} (IBM, Yorktown) received a Ph.D. in mathematics
from Princeton University and has been involved with the design and
implementation of the system interpreter, system commands, and
documentation since 1984. Sutor's contributions to the Axiom library
include factored objects, partial fractions, and the original
implementation of finite field extensions. Recently, he has devised
technology for producing automatic hard-copy and on-line documentation
from single source files.

{\bf Scott C. Morrison} (IBM, Yorktown) received an M.S. from the
University of California, Berkeley, and is a principal person
responsible for the design and implementation of the Axiom interface,
including the interpreter, HyperDoc, and applications of the computer
graphics system.

{\bf Manuel Bronstein} (ETH, Zurich) received a Ph.D. in mathematics
from the University of California, Berkeley, completing the
theoretical work on closed-form integration by Barry Trager. Bronstein
designed and implemented the algebraic structures and algorithms in
the Axiom library for integration, closed form solution of
differential equations, operator algebras, and manipulation of
top-level mathematical expressions. He also designed (with Richard
Jenks) and implemented the current pattern match facility for Axiom.

{\bf William H. Burge} (IBM, Yorktown) received a Ph.D. from Cambridge
University, implemented the Axiom parser, designed (with Stephen Watt)
and implemented the stream and power series structures, and numerous
algebraic facilities including those for data structures, power
series, and combinatorics.

{\bf Timothy P. Daly} (IBM, Yorktown) is pursuing a Ph.D. in computer
science at Brooklyn Polytechnic Institute and is responsible for
porting, testing, performance, and system support work for Axiom.

{\bf James Davenport} (Bath) received a Ph.D. from Cambridge
University, is the author of several computer algebra textbooks, and
has long recognized the need for Axiom's generality for computer
algebra. He was involved with the early prototype design of system
internals and the original category hierarchy for Axiom (with David
R. Barton). More recently, Davenport and Barry Trager designed the
algebraic category hierarchy currently used in Axiom. Davenport is
Hebron and Medlock Professor of Information Technology at Bath
University.

{\bf Michael Dewar} (Bath) received a Ph.D. from the University of
Bath for his work on the IRENA system (an interface between the {\bf
REDUCE} computer algebra system and the NAG Library of numerical
subprograms), and work on interfacing algebraic and numerical systems
in general. He has contributed code to produce FORTRAN output from
Axiom, and is currently developing a comprehensive foreign language
interface and a link to the NAG Library for release 2 of Axiom.

%Original Page xxiii


{\bf Albrecht Fortenbacher} (IBM Scientific Center, Heidelberg)
received a doctorate from the University of Karlsruhe and is a
designer and implementer of the type-inferencing code in the Axiom
interpreter. The result of research by Fortenbacher on type coercion
by rewrite rules will soon be incorporated into Axiom.

{\bf Patrizia Gianni} (Pisa) received a Laurea in mathematics from the
University of Pisa and is the prime author of the polynomial and
rational funtion component of the Axiom library. Her contributions
include algorithms for greatest common divisors, factorization,
ideals, Gr\"obner bases, solutions of polynomial systems, and linear
algebra. she is currently Associate Professor of Mathematics at the
University of Pisa.

{\bf Johannes Grabmeier} (IBM Scientific Center, Heidelberg) received a
Ph.D from University Bayreuth (Bavaria) and is responsible for many
Axiom packages, including those for representation theory (with Holger
Gollan (Essen)), permutation groups (with Gerhard Schneider (Essen)),
finite fields (with Alfred Scheerhorn), and non-associative algebra
(with Robert Wisbauer (D\"usseldorf)).

{\bf Larry Lambe} received a Ph.D. from the University of Illinois
(Chicago) and has been using Axiom for research in homological
algebra. Lambe contributed facilities for Lie ring and exterior
algebra calculations and has worked with Scott Morrison on various
graphics applications.

{\bf Michael Monagan} (ETH, Z\"urich) received a Ph.D. from the
University of Waterloo and is a principal contributor to the {\bf
Maple} computer algebra system. He designed and implemented the
category hierarchy and domains for data structures (with Stephen Watt),
multi-precision floating point arithmetic, code for polynomials modulo
a prime, and also worked on the new compiler.

{\bf William Sit} (CCNY) received a Ph.D. from Columbia University. He
has been using Axiom for research in differential algebra, and
contributed operations for differential polynomials (with Manuel
Bronstein).

{\bf Jonathan M. Steinbach} (IBM, Yorktown) received a B.A. degree
from Ohio State University and has responsibility for the Axiom
computer graphics facility. He has modified and extended this facility
from the original design by Jim Wen. Steinbach is currently involved
in the new compiler effort.

{\bf Jim Wen}, a graduate student in computer graphics at Brown
University designed and implemented the original computer graphics
system for Axiom with pop-up control panels for interactive
manipulation of graphic objects.


%Original Page xxiv


{\bf Clifton J. Williamson} (Cal Poly) received a Ph.D. in Mathematics
from the University of California, Berkeley. He implemented the power
series (with William Burge and Stephen Watt), matrix, and limit
facilities in the library and made numerous contributions to the
HyperDoc documentation and algebraic side of the computer graphics
facility. Williamson is currently an Assistant Professor of Mathematics
at California Polytechnic State University, San Luis Obispo.

Contributions to the current Axiom system were also made by: Yurig
Baransky (IBM Research, Yorktown), David R. Barton, Bruce Char
(Drexel), Korrinn Fu, R\"udiger Gebauer, Holger Gollan (Essen), Steven
J. Gortler, Michael Lucks, Victor Miller (IBM Research, Yorktown),
C. Andrew Neff (IBM Research, Yorktown), H. Michael M\"oller (Hagen),
Simon Robinson, Gerhard Schneider (Essen), Thorsten Werther (Bonn),
John M. Wiley, Waldermar Wiwianka (Paderborn), David Y. Y. Yun (Hawaii).

Other group members, visitors and contributors to Axiom include
Richard Anderson, George Andrews, Alexandre Bouyer, Martin Brock,
Florian Bundschuh, Cheekai Chin, David V. Chudnovsky, Gregory
V. Chudnovsky, Josh Cohen, Gary Cornell, Jean Della Dora, Clair Di
Cresendo, Domonique Duval, Lars Erickson, Timothy Freeman, Marc
Gaetano, Vladimir A. Grinberg, Oswald Gschnitzer, Klaus Kusche,
Bernhard Kutzler, Mohammed, Mobarak, Julian A. Padget, Michael
Rothstein, Alfred Scheerhorn, William F. Schelter, Marten Sch\"onert,
Fritz Schwarz, Christine J. Sundaresan, Moss E. Sweedler, Themos
T. Tsikas, Berhard Wall, Robert Wisbauer, and Knut Wolf.

This book has contributions from several people in addition to its
principal authors. Scott Morrison is responsible for the computer
graphics gallery and the programs in Appendix F. Jonathon Steinbach
wrote the original version of Chapter 7. Michael Dewar contributed
material on the FORTRAN interface in Chapter 4. Manuel Bronstein,
Clifton Williamson, Patricia Gianni, Johannes Grabmeier, Barry Trager,
and Stephen Watt contributed to Chapters 8 and 9 and Appendix
E. William Burge, Timothy Daly, Larry Lambe, and William Sit
contributed material to Chapter 9. The original version of the 
documentation was created and maintained by Christine Sundaresan.

The authors would like to thank the production staff at
Springer-Verlag for their guidance in the preparation of this book,
and Jean K. Rivlin of IBM Yorktown Heights for her assistance in
producing the camera-ready copy. Also, thanks to Robert F. Caviness,
James H. Davenport, Sam Dooley, Richard J. Fateman, Stuart I. Feldman,
Stephen J. Hague, John A. Nelder, Eugene J. Surowitz, Themos
T. Tsikas, James W. Thatcher, and Richard E. Zippel for their
constructive suggestions on drafts of this book.
\newpage
\pagenumbering{arabic}

%Original Page 1

\chapter{Introduction to Axiom}
%\addcontentsline{toc}{chapter}{Introduction to Axiom}
\label{ugNewIntro}
Welcome to the world of Axiom.
We call Axiom a scientific computation system:
a self-contained toolbox designed to meet
your scientific programming needs,
from symbolics, to numerics, to graphics.

This introduction is a quick overview of what Axiom offers.

\subsection{Symbolic Computation}
Axiom provides a wide range of simple commands for symbolic
mathematical problem solving.  Do you need to solve an equation, to
expand a series, or to obtain an integral?  If so, just ask Axiom
to do it.

Given $$\int\left({{\frac{1}{(x^3 \  {(a+b x)}^{1/3})}}}\right)dx$$ 
we would enter this into Axiom as:

\spadcommand{integrate(1/(x**3 * (a+b*x)**(1/3)),x)}
which would give the result:
$$
\frac{\left(
\begin{array}{@{}l}
\displaystyle
-{2 \ {b^2}\ {x^2}\ {\sqrt{3}}\ {\log 
\left({{{\root{3}\of{a}}\ {{\root{3}\of{{b \  x}+ a}}^2}}
+{{{\root{3}\of{a}}^2}\ {\root{3}\of{{b \  x}+ a}}}+ a}\right)}}+ 
\\
\\
\displaystyle
{4 \ {b^2}\ {x^2}\ {\sqrt{3}}\ {\log \left({{{{\root{3}\of{a}}^
2}\ {\root{3}\of{{b \  x}+ a}}}- a}\right)}}+ 
\\
\\
\displaystyle
{{12}\ {b^2}\ {x^2}\ {\arctan \left({\frac{{2 \ {\sqrt{3}}\ {{\root{3}\of{a}}^
2}\ {\root{3}\of{{b \  x}+ a}}}+{a \ {\sqrt{3}}}}{3 \  a}}\right)}}+
\\
\\
\displaystyle
{{\left({{12}\  b \  x}-{9 \  a}\right)}
\ {\sqrt{3}}\ {\root{3}\of{a}}\ {{\root{3}\of{{b \  x}+ a}}^2}}
\end{array}
\right)}{{18}\ {a^2}\ {x^2}\ {\sqrt{3}}\ {\root{3}\of{a}}}
$$
\returnType{Type: Union(Expression Integer,...)}

%Original Page 2

Axiom provides state-of-the-art algebraic machinery to handle your
most advanced symbolic problems.  For example, Axiom's integrator
gives you the answer when an answer exists.  If one does not, it
provides a proof that there is no answer.  Integration is just one of
a multitude of symbolic operations that Axiom provides.

\subsection{Numeric Computation}
Axiom has a numerical library that includes operations for linear
algebra, solution of equations, and special functions.  For many of
these operations, you can select any number of floating point digits
to be carried out in the computation.

Solve $x^{49}-49x^4+9$ to 49 digits of accuracy.
First we need to change the default output length of numbers:

\spadcommand{digits(49)}
and then we execute the command:

\spadcommand{solve(x**49-49*x**4+9 = 0,1.e-49)}
$$
\begin{array}{@{}l}
\displaystyle
\left[{x = -{0.6546536706904271136718122105095984761851224331
556}},  \right.
\\
\\
\displaystyle
\left.{x ={1.086921395653859508493939035954893289009213388763}},
  \right.
\\
\\
\displaystyle
\left.{x ={0.654653670725527173969468606613676483536148760766
1}}\right] 
\end{array}
$$


\returnType{Type: List Equation Polynomial Float}
The output of a computation can be converted to FORTRAN to be used
in a later numerical computation.
Besides floating point numbers, Axiom provides literally
dozens of kinds of numbers to compute with.
These range from various kinds of integers, to fractions, complex
numbers, quaternions, continued fractions, and to numbers represented
with an arbitrary base.

What is $10$ to the $90$-th power in base $32$?

\spadcommand{radix(10**90,32)}
returns:

%\noindent
{\tt FMM3O955CSEIV0ILKH820CN3I7PICQU0OQMDOFV6TP000000000000000000 }
\returnType{Type: RadixExpansion 32}

The Axiom numerical library can be enhanced with a
substantial number of functions from the NAG library of numerical and
statistical algorithms. These functions will provide coverage of a wide
range of areas including roots of functions, Fourier transforms, quadrature,
differential equations, data approximation, non-linear optimization, linear
algebra, basic statistics, step-wise regression, analysis of variance,
time series analysis, mathematical programming, and special functions.
Contact the Numerical Algorithms Group Limited, Oxford, England.

\subsection{Graphics}
You may often want to visualize a symbolic formula or draw
a graph from a set of numerical values.
To do this, you can call upon the Axiom
graphics capability.

%Original Page 3

Draw $J_0(\sqrt{x^2+y^2})$ for $-20 \leq x,y \leq 20$.

\spadcommand{draw(5*besselJ(0,sqrt(x**2+y**2)), x=-20..20, y=-20..20)}
\begin{figure}[htbp]
\includegraphics[bbllx=1, bblly=39, bburx=298, bbury=290]{ps/bessintr.ps}
\caption{$J_0(\sqrt{x^2+y^2})$ for $-20 \leq x,y \leq 20$}
\label{tpdhere}
\end{figure}

Graphs in Axiom are interactive objects you can manipulate with
your mouse.  Just click on the graph, and a control panel pops up.
Using this mouse and the control panel, you can translate, rotate,
zoom, change the coloring, lighting, shading, and perspective on the
picture.  You can also generate a PostScript copy of your graph to
produce hard-copy output.

\subsection{HyperDoc}

\begin{figure}[htbp]
%\includegraphics[bbllx=1, bblly=1, bburx=298, bbury=290]{ps/v0hroot.eps}
\includegraphics{ps/v0hroot.eps}
\caption{Hyperdoc opening menu}
\label{fig-intro-br}
\end{figure}

HyperDoc presents you windows on the world of Axiom,
offering on-line help, examples, tutorials, a browser, and reference
material.  HyperDoc gives you on-line access to this document in a
``hypertext'' format.  Words that appear in a different font (for
example, {\tt Matrix}, {\bf factor}, and
{\it category}) are generally mouse-active; if you click on one
with your mouse, HyperDoc shows you a new window for that word.

As another example of a HyperDoc facility, suppose that you want to
compute the roots of $x^{49} - 49x^4 + 9$ to 49 digits (as in our
previous example) and you don't know how to tell Axiom to do this.
The ``basic command'' facility of HyperDoc leads the way.  Through the
series of HyperDoc windows shown in \figureref{fig-intro-br} 
and the specified mouse clicks, you and
HyperDoc generate the correct command to issue to compute the answer.

\subsection{Interactive Programming }
Axiom's interactive programming language lets you define your
own functions.  A simple example of a user-defined function is one
that computes the successive Legendre polynomials.  Axiom lets
you define these polynomials in a piece-wise way.

The first Legendre polynomial.

%Original Page 4

\spadcommand{p(0) == 1}
\returnType{Type: Void}
The second Legendre polynomial.

\spadcommand{p(1) == x}
\returnType{Type: Void}
The $n$-th Legendre polynomial for $(n > 1)$.

\spadcommand{p(n) == ((2*n-1)*x*p(n-1) - (n-1) * p(n-2))/n}
\returnType{Type: Void}

%Original Page 5

In addition to letting you define simple functions like this, the
interactive language can be used to create entire application
packages.  All the graphs in the Axiom images section were created by
programs written in the interactive language.

The above definitions for $p$ do no computation---they simply
tell Axiom how to compute $p(k)$ for some positive integer
$k$.

To actually get a value of a Legendre polynomial, you ask for it.
\index{Legendre polynomials}

What is the tenth Legendre polynomial?

\spadcommand{p(10)}
\begin{verbatim}
   Compiling function p with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function p as a recurrence relation.
\end{verbatim}
$$
{{\frac{46189}{256}} \  {x \sp {10}}} 
-{{\frac{109395}{256}} \  {x \sp 8}}
+{{\frac{45045}{128}} \  {x \sp 6}} 
-{{\frac{15015}{128}} \  {x \sp 4}}
+{{\frac{3465}{256}} \  {x \sp 2}} 
-{\frac{63}{256}} 
$$
\returnType{Type: Polynomial Fraction Integer}
Axiom applies the above pieces for $p$ to obtain the value
of $p(10)$.  But it does more: it creates an optimized, compiled
function for $p$.  The function is formed by putting the pieces
together into a single piece of code.  By {\it compiled}, we mean that
the function is translated into basic machine-code.  By {\it
optimized}, we mean that certain transformations are performed on that
code to make it run faster.  For $p$, Axiom actually
translates the original definition that is recursive (one that calls
itself) to one that is iterative (one that consists of a simple loop).

What is the coefficient of $x^{90}$ in $p(90)$?

\spadcommand{coefficient(p(90),x,90)}
$$
\frac{5688265542052017822223458237426581853561497449095175}
{77371252455336267181195264} 
$$
\returnType{Type: Polynomial Fraction Integer}

In general, a user function is type-analyzed and compiled on first use.
Later, if you use it with a different kind of object, the function
is recompiled if necessary.

\subsection{Data Structures}

A variety of data structures are available for interactive use.  These
include strings, lists, vectors, sets, multisets, and hash tables.  A
particularly useful structure for interactive use is the infinite
stream:

Create the infinite stream of derivatives of Legendre polynomials.

\spadcommand{[D(p(i),x) for i in 1..]}
$$
\begin{array}{@{}l}
\displaystyle
\left[ 1, {3 \  x}, 
{{{\frac{15}{2}}\ {x^2}}-{\frac{3}{2}}},
{{{\frac{35}{2}}\ {x^3}}-{{\frac{15}{2}}\  x}}, 
{{{\frac{315}{8}}\ {x^4}}-{{\frac{105}{4}}\ {x^2}}+{\frac{15}{8}}},  \right.
\\
\\
\displaystyle
\left.{{{\frac{693}{8}}\ {x^5}}-{{\frac{315}{4}}\ {x^3}}
+{{\frac{105}{8}}\  x}}, 
{{{\frac{3003}{16}}\ {x^6}}-{{\frac{3465}{16}}\ {x^4}}
+{{\frac{945}{16}}\ {x^2}}-{\frac{35}{16}}},  \right.
\\
\\
\displaystyle
\left.{{{\frac{6435}{16}}\ {x^7}}-{{\frac{9009}{16}}\ {x^5}}+
{{\frac{3465}{16}}\ {x^3}}-{{\frac{315}{16}}\  x}},  \right.
\\
\\
\displaystyle
\left.{{{\frac{109395}{128}}\ {x^8}}-{{\frac{45045}{32}}\ {x^6}}
+{{\frac{45045}{64}}\ {x^4}}-{{\frac{3465}{32}}\ {x^2}}
+{\frac{315}{128}}},  \right.
\\
\\
\displaystyle
\left.{{{\frac{230945}{128}}\ {x^9}}-{{\frac{109395}{32}}\ {x^7}}
+{{\frac{135135}{64}}\ {x^5}}-{{\frac{15015}{32}}\ {x^3}}+
{{\frac{3465}{128}}\  x}},  \ldots \right] 
\end{array}
$$
\returnType{Type: Stream Polynomial Fraction Integer}


Streams display only a few of their initial elements.  Otherwise, they
are ``lazy'': they only compute elements when you ask for them.

%Original Page 6

Data structures are an important component for building application
software. Advanced users can represent data for applications in
optimal fashion.  In all, Axiom offers over forty kinds of
aggregate data structures, ranging from mutable structures (such as
cyclic lists and flexible arrays) to storage efficient structures
(such as bit vectors).  As an example, streams are used as the
internal data structure for power series.

What is the series expansion
of $\log(\cot(x))$
about $x=\pi/2$?
%NOTE: The book has a different answer (see p6)

\spadcommand{series(log(cot(x)),x = \%pi/2)}
$$
\begin{array}{@{}l}
\displaystyle
{\log \left({\frac{-{2 \  x}+ \pi}{2}}\right)}+
{{\frac{1}{3}}\ {{\left(x -{\frac{\pi}{2}}\right)}^2}}+
{{\frac{7}{90}}\ {{\left(x -{\frac{\pi}{2}}\right)}^4}}+ 
{{\frac{62}{2835}}\ {{\left(x -{\frac{\pi}{2}}\right)}^6}}+
\\
\\
\displaystyle
{{\frac{127}{18900}}\ {{\left(x -{\frac{\pi}{2}}\right)}^8}}+
{{\frac{146}{66825}}\ {{\left(x -{\frac{\pi}{2}}\right)}^{10}}}+ 
{O \left({{\left(x -{\frac{\pi}{2}}\right)}^{11}}\right)}
\end{array}
$$
\returnType{Type: GeneralUnivariatePowerSeries(Expression Integer,x,pi/2)}

Series and streams make no attempt to compute {\it all} their
elements!  Rather, they stand ready to deliver elements on demand.

What is the coefficient of the $50$-th
term of this series?

\spadcommand{coefficient(\%,50)}
$$
\frac{44590788901016030052447242300856550965644}
{7131469286438669111584090881309360354581359130859375} 
$$
\returnType{Type: Expression Integer}

\subsection{Mathematical Structures}
Axiom also has many kinds of mathematical structures.  These
range from simple ones (like polynomials and matrices) to more
esoteric ones (like ideals and Clifford algebras).  Most structures
allow the construction of arbitrarily complicated ``types.''

Even a simple input expression can
result in a type with several levels.

\spadcommand{matrix [ [x + \%i,0], [1,-2] ]}
$$
\left[
\begin{array}{cc}
\displaystyle{}
{x+\%{\rm i}} & 0 \\ 
1 & -2 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Complex Integer}

The Axiom interpreter builds types in response to user input.
Often, the type of the result is changed in order to be applicable to
an operation.

The inverse operation requires that elements of the above matrices
are fractions.

\spadcommand{inverse(\%)}
$$
\left[
\begin{array}{cc}
\displaystyle{\frac{1}{x+\%{\rm i}}} & 0 \\ 
\displaystyle{\frac{1}{{2 \  x}+{2 \%{\rm i}}}} & -{\frac{1}{2}} 
\end{array}
\right]
$$
\returnType{Type: Union(Matrix Fraction Polynomial Complex Integer,...)}

\subsection{Pattern Matching}

%Original Page 7

A convenient facility for symbolic computation is ``pattern
matching.''  Suppose you have a trigonometric expression and you want
to transform it to some equivalent form.  Use a $rule$ command to
describe the transformation rules you \index{rule} need.  Then give
the rules a name and apply that name as a function to your
trigonometric expression.

Introduce two rewrite rules.

\spadcommand{sinCosExpandRules := rule\\
\ \ sin(x+y) == sin(x)*cos(y) + sin(y)*cos(x)\\
\ \  cos(x+y) == cos(x)*cos(y) - sin(x)*sin(y)\\
\ \  sin(2*x) == 2*sin(x)*cos(x)\\
\ \  cos(2*x) == cos(x)**2 - sin(x)**2
}

\begin{verbatim}
   {sin(y + x) == cos(x)sin(y) + cos(y)sin(x),
    cos(y + x) == - sin(x)sin(y) + cos(x)cos(y), 
    sin(2x) == 2cos(x)sin(x),
                       2         2
    cos(2x) == - sin(x)  + cos(x) }
\end{verbatim}
\returnType{Type: Ruleset(Integer,Integer,Expression Integer)}

Apply the rules to a simple trigonometric expression.

\spadcommand{sinCosExpandRules(sin(a+2*b+c))}
$$
\begin{array}{@{}l}
\displaystyle
{{\left(-{{\cos \left({a}\right)}\ {{\sin \left({b}\right)}^2}}-
{2 \ {\cos \left({b}\right)}\ {\sin \left({a}\right)}\ {\sin 
\left({b}\right)}}+{{\cos \left({a}\right)}\ {{\cos \left({b}\right)}^
2}}\right)}\ {\sin \left({c}\right)}}- 
\\
\\
\displaystyle
{{\cos \left({c}\right)}\ {\sin \left({a}\right)}\ {{\sin \left({b}\right)}^
2}}+{2 \ {\cos \left({a}\right)}\ {\cos \left({b}\right)}\ {\cos 
\left({c}\right)}\ {\sin \left({b}\right)}}+ 
\\
\\
\displaystyle
{{{\cos \left({b}\right)}^2}\ {\cos \left({c}\right)}\ {\sin 
\left({a}\right)}}
\end{array}
$$
\returnType{Type: Expression Integer}


Using input files, you can create your own library of transformation
rules relevant to your applications, then selectively apply the rules
you need.

\subsection{Polymorphic Algorithms}
All components of the Axiom algebra library are written in the
Axiom library language.  This language is similar to the
interactive language except for protocols that authors are obliged to
follow.  The library language permits you to write ``polymorphic
algorithms,'' algorithms defined to work in their most natural
settings and over a variety of types.

Define a system of polynomial equations $S$.

\spadcommand{S := [3*x**3 + y + 1 = 0,y**2 = 4]}
$$
\left[
{{y+{3 \  {x \sp 3}}+1}=0},  {{y \sp 2}=4} 
\right]
$$
\returnType{Type: List Equation Polynomial Integer}

%Original Page 8

Solve the system $S$ using rational number arithmetic and
30 digits of accuracy.

\spadcommand{solve(S,1/10**30)}
$$
\left[
{\left[ {y=-2}, {x={
\frac{1757879671211184245283070414507}{2535301200456458802993406410752}}}
\right]},
 {\left[ {y=2},  {x=-1} 
\right]}
\right]
$$
\returnType{Type: List List Equation Polynomial Fraction Integer}

Solve $S$ with the solutions expressed in radicals.

\spadcommand{radicalSolve(S)}
$$
\begin{array}{@{}l}
\displaystyle
\left[{\left[{y = 2}, {x = - 1}\right]}, {\left[{y = 2}, 
{x ={\frac{-{\sqrt{- 3}}+ 1}{2}}}\right]},  \right.
\\
\\
\displaystyle
\left.{\left[{y = 2}, {x ={\frac{{\sqrt{- 3}}+ 1}{2}}}\right]},
 {\left[{y = - 2}, {x ={\frac{1}{\root{3}\of{3}}}}\right]},
  \right.
\\
\\
\displaystyle
\left.{\left[{y = - 2}, 
{x ={\frac{{{\sqrt{- 1}}\ {\sqrt{3}}}- 1}{2 \ {\root{3}\of{3}}}}}\right]}, 
{\left[{y = - 2}, 
{x ={\frac{-{{\sqrt{- 1}}\ {\sqrt{3}}}- 1}{2 \ {\root{3}\of{3}}}}}\right]}
\right] 
\end{array}
$$
\returnType{Type: List List Equation Expression Integer}

While these solutions look very different, the results were produced
by the same internal algorithm!  The internal algorithm actually works
with equations over any ``field.''  Examples of fields are the
rational numbers, floating point numbers, rational functions, power
series, and general expressions involving radicals.

\subsection{Extensibility}

Users and system developers alike can augment the Axiom library,
all using one common language.  Library code, like interpreter code,
is compiled into machine binary code for run-time efficiency.

Using this language, you can create new computational types and new
algorithmic packages.  All library code is polymorphic, described in
terms of a database of algebraic properties.  By following the
language protocols, there is an automatic, guaranteed interaction
between your code and that of colleagues and system implementers.
\vfill\eject

%Original Page 9

\pseudoChapter{\Huge A Technical Introduction}
\label{ugTechIntro}
Axiom has both an {\it interactive language} for user
interactions and a {\it programming language} for building library
modules.  Like Modula 2, \index{Modula 2} PASCAL, \index{PASCAL}
FORTRAN, \index{FORTRAN} and Ada, \index{Ada} the programming language
emphasizes strict type-checking.  Unlike these languages, types in
Axiom are dynamic objects: they are created at run-time in
response to user commands.

Here is the idea of the Axiom programming language in a
nutshell.  Axiom types range from algebraic ones (like
polynomials, matrices, and power series) to data structures (like
lists, dictionaries, and input files).  Types combine in any
meaningful way.  You can build polynomials of matrices, matrices of
polynomials of power series, hash tables with symbolic keys and
rational function entries, and so on.

{\it Categories} define algebraic properties to ensure mathematical
correctness. They ensure, for example, that matrices of polynomials
are OK, but matrices of input files are not.  Through categories,
programs can discover that polynomials of continued fractions have a
commutative multiplication whereas polynomials of matrices do not.

%Original Page 10

Categories allow algorithms to be defined in their most natural
setting. For example, an algorithm can be defined to solve polynomial
equations over {\it any} field.  Likewise a greatest common divisor
can compute the ``gcd'' of two elements from {\it any} Euclidean
domain.  Categories foil attempts to compute meaningless ``gcds'', for
example, of two hashtables.  Categories also enable algorithms to be
compiled into machine code that can be run with arbitrary types.

The Axiom interactive language is oriented towards ease-of-use.
The Axiom interpreter uses type-inferencing to deduce the type
of an object from user input.  Type declarations can generally be
omitted for common types in the interactive language.

So much for the nutshell.
Here are these basic ideas described by ten design principles:

\chapter{A Technical Introduction to Axiom}
\section{Types are Defined by Abstract Datatype Programs}

Basic types are called {\it domains of computation}, or,
simply, {\it domains.}
\index{domain}
Domains are defined by Axiom programs of the form:

\begin{verbatim}
Name(...): Exports == Implementation
\end{verbatim}

Each domain has a capitalized {\tt Name} that is used to refer to the
class of its members.  For example, {\tt Integer} denotes ``the
class of integers,'' {\tt Float}, ``the class of floating point
numbers,'' and {\tt String}, ``the class of strings.''

The ``{\tt ...}'' part following {\tt Name} lists zero or more
parameters to the constructor. Some basic ones like {\tt Integer} take
no parameters.  Others, like {\tt Matrix}, {\tt Polynomial} and 
{\tt List}, take a single parameter that again must be a domain.  For
example, {\tt Matrix(Integer)} denotes ``matrices over the integers,''
{\tt Polynomial (Float)} denotes ``polynomial with floating point
coefficients,'' and {\tt List (Matrix (Polynomial (Integer)))} denotes
``lists of matrices of polynomials over the integers.''  There is no
restriction on the number or type of parameters of a domain
constructor.

SquareMatrix(2,Integer) is an example of a domain constructor that accepts
both a particular data value as well as an integer. In this case the
number 2 specifies the number of rows and columns the square matrix
will contain. Elements of the matricies are integers.

The {\tt Exports} part specifies operations for creating and
manipulating objects of the domain.  For example, type
{\tt Integer} exports constants $0$ and $1$, and
operations \spadopFrom{+}{Integer}, \spadopFrom{-}{Integer}, and
\spadopFrom{*}{Integer}.  While these operations are common, others
such as \spadfunFrom{odd?}{Integer} and \spadfunFrom{bit?}{Integer}
are not. In addition the Exports section can contain symbols that
represent properties that can be tested. For example, the Category
{\tt EntireRing} has the symbol {\tt noZeroDivisors} which asserts
that if a product is zero then one of the factors must be zero.

The {\tt Implementation} part defines functions that implement the
exported operations of the domain.  These functions are frequently
described in terms of another lower-level domain used to represent the
objects of the domain. Thus the operation of adding two vectors of
real numbers can be described and implemented using the addition
operation from {\tt Float}. 

\section{The Type of Basic Objects is a Domain or Subdomain}

%Original Page 11

Every Axiom object belongs to a {\it unique} domain.  The domain
of an object is also called its {\it type.}  Thus the integer $7$
has type {\tt Integer} and the string {\tt "daniel"} has type
{\tt String}.

The type of an object, however, is not unique.  The type of integer
$7$ is not only {\tt Integer} but {\tt NonNegativeInteger},
{\tt PositiveInteger}, and possibly, in general, any other
``subdomain'' of the domain {\tt Integer}.  A {\it subdomain}
\index{subdomain} is a domain with a ``membership predicate''.
{\tt PositiveInteger} is a subdomain of {\tt Integer} with the
predicate ``is the integer $> 0$?''.

Subdomains with names are defined by abstract datatype programs
similar to those for domains.  The {\it Export} part of a subdomain,
however, must list a subset of the exports of the domain.  The {\tt
Implementation} part optionally gives special definitions for
subdomain objects.

\section{Domains Have Types Called Categories}

Domains and subdomains in Axiom are themselves objects that have
types.  The type of a domain or subdomain is called a {\it category}.
\index{category} Categories are described by programs of the form:

\begin{verbatim}
Name(...): Category == Exports
\end{verbatim}
The type of every category is the distinguished symbol {\tt Category.}
The category {\tt Name} is used to designate the class of domains of
that type.  For example, category {\tt Ring} designates the class
of all rings.  Like domains, categories can take zero or more
parameters as indicated by the ``{\tt ...}'' part following {\tt
Name.}  Two examples are {\tt Module(R)} and
{\tt MatrixCategory(R,Row,Col)}.

The {\tt Exports} part defines a set of operations.  For example,
{\tt Ring} exports the operations \spadopFrom{0}{Ring},
\spadopFrom{1}{Ring}, \spadopFrom{+}{Ring}, \spadopFrom{-}{Ring}, and
\spadopFrom{*}{Ring}.  Many algebraic domains such as
{\tt Integer} and {\tt Polynomial (Float)} are rings.
{\tt String} and {\tt List (R)} (for any domain $R$)
are not.

Categories serve to ensure the type-correctness.  The definition of
matrices states {\tt Matrix(R: Ring)} requiring its single parameter
$R$ to be a ring.  Thus a ``matrix of polynomials'' is allowed,
but ``matrix of lists'' is not.

Categories say nothing about representation. Domains, which are
instances of category types, specify representations.

\section{Operations Can Refer To Abstract Types}

All operations have prescribed source and target types.  Types can be
denoted by symbols that stand for domains, called ``symbolic
domains.''  The following lines of Axiom code use a symbolic
domain $R$:

\begin{verbatim}
R: Ring
power: (R, NonNegativeInteger): R -> R
power(x, n) == x ** n
\end{verbatim}

%Original Page 12

Line 1 declares the symbol $R$ to be a ring.  Line 2 declares the
type of $power$ in terms of $R$.  From the definition on
line 3, $power(3,2)$ produces 9 for $x = 3$ and $R =$
{\tt Integer}.  Also, $power(3.0,2)$ produces $9.0$ for
$x = 3.0$ and $R =$ {\tt Float}.
$power("oxford",2)$ however fails since $"oxford"$ has type
{\tt String} which is not a ring.

Using symbolic domains, algorithms can be defined in their most
natural or general setting.

\section{Categories Form Hierarchies}

Categories form hierarchies (technically, directed-acyclic graphs).  A
simplified hierarchical world of algebraic categories is shown below.
At the top of this world is {\tt SetCategory}, the class of
algebraic sets.  The notions of parents, ancestors, and descendants is
clear.  Thus ordered sets (domains of category {\tt OrderedSet})
and rings are also algebraic sets.  Likewise, fields and integral
domains are rings and algebraic sets.  However fields and integral
domains are not ordered sets.

\begin{verbatim}
SetCategory +---- Ring       ---- IntegralDomain ---- Field
            |
            +---- Finite     ---+
            |                    \
            +---- OrderedSet -----+ OrderedFinite
\end{verbatim}
\begin{center}
Figure 1.  A  simplified category hierarchy.
\end{center}

%Original Page 13

\section{Domains Belong to Categories by Assertion}

A category designates a class of domains.  Which domains?  You might
think that {\tt Ring} designates the class of all domains that
export $0$, $1$, \spadopFrom{+}{Integer},
\spadopFrom{-}{Integer}, and \spadopFrom{*}{Integer}.  But this is not
so.  Each domain must {\it assert} which categories it belongs to.

The {\tt Export} part of the definition for {\tt Integer} reads,
for example:

\begin{verbatim}
Join(OrderedSet, IntegralDomain,  ...) with ...
\end{verbatim}

This definition asserts that {\tt Integer} is both an ordered set
and an integral domain.  In fact, {\tt Integer} does not
explicitly export constants $0$ and $1$ and operations
\spadopFrom{+}{Ring}, \spadopFrom{-}{Ring} and \spadopFrom{*}{Ring} at
all: it inherits them all from $Ring$!  Since
{\tt IntegralDomain} is a descendant of $Ring$,
{\tt Integer} is therefore also a ring.

Assertions can be conditional.  For example, {\tt Complex(R)}
defines its exports by:

\begin{verbatim}
Ring with ... if R has Field then Field ...
\end{verbatim}
Thus {\tt Complex(Float)} is a field but {\tt Complex(Integer)}
is not since {\tt Integer} is not a field.

You may wonder: ``Why not simply let the set of operations determine
whether a domain belongs to a given category?''.  Axiom allows
operation names (for example, {\bf norm}) to have very different
meanings in different contexts.  The meaning of an operation in
Axiom is determined by context.  By associating operations with
categories, operation names can be reused whenever appropriate or
convenient to do so.  As a simple example, the operation {\tt <}
might be used to denote lexicographic-comparison in an algorithm.
However, it is wrong to use the same {\tt <} with this definition
of absolute-value: $$abs(x) == if\ x < 0\  then -x\ else\ x$$ Such a
definition for {\tt abs} in Axiom is protected by context:
argument $x$ is required to be a member of a domain of category
{\tt OrderedSet}.

\section{Packages Are Clusters of Polymorphic Operations}

In Axiom, facilities for symbolic integration, solution of
equations, and the like are placed in ``packages''.  A {\it package}
\index{package} is a special kind of domain: one whose exported
operations depend solely on the parameters of the constructor and/or
explicit domains. Packages, unlike Domains, do not specify the
representation.

If you want to use Axiom, for example, to define some algorithms
for solving equations of polynomials over an arbitrary field $F$,
you can do so with a package of the form:

\begin{verbatim}
MySolve(F: Field): Exports == Implementation
\end{verbatim}

%Original Page 14

where {\tt Exports} specifies the {\bf solve} operations
you wish to export from the domain and the {\tt Implementation}
defines functions for implementing your algorithms.  Once Axiom has
compiled your package, your algorithms can then be used for any {\tt F}:
floating-point numbers, rational numbers, complex rational functions,
and power series, to name a few.

\section{The Interpreter Builds Domains Dynamically}

The Axiom interpreter reads user input then builds whatever types
it needs to perform the indicated computations.
For example, to create the matrix
\[M=\left(\begin{array}{cc}
x^2+1 & 0\\
0 & x/2
\end{array}\right)\]
using the command:

\spadcommand{M = [ [x**2+1,0],[0,x / 2] ]::Matrix(POLY(FRAC(INT)))}
$$
M={\left[ 
\begin{array}{cc}
x^2+1 & 0 \\ 
0 & x/2
\end{array}
\right]}
$$
\returnType{Type: Matrix Polynomial Fraction Integer}
the interpreter first loads the modules {\tt Matrix},
{\tt Polynomial}, {\tt Fraction}, and {\tt Integer}
from the library, then builds the {\it domain tower} ``matrices of
polynomials of rational numbers (i.e. fractions of integers)''.

You can watch the loading process by first typing 

\spadcommand{)set message autoload on}
In addition to the named
domains above many additional domains and categories are loaded.
Most systems are preloaded with such common types. For efficiency
reasons the most common domains are preloaded but most (there are
more than 1100 domains, categories, and packages) are not. Once these
domains are loaded they are immediately available to the interpreter.

Once a domain tower is built, it contains all the operations specific
to the type. Computation proceeds by calling operations that exist in
the tower.  For example, suppose that the user asks to square the
above matrix.  To do this, the function \spadopFrom{*}{Matrix} from
{\tt Matrix} is passed the matrix $M$ to compute $M * M$.  
The function is also passed an environment containing $R$
that, in this case, is {\tt Polynomial (Fraction (Integer))}.
This results in the successive calling of the \spadopFrom{*}{Fraction}
operations from {\tt Polynomial}, then from {\tt Fraction},
and then finally from {\tt Integer}.

Categories play a policing role in the building of domains.  Because
the argument of {\tt Matrix} is required to be a {\tt Ring},
Axiom will not build nonsensical types such as ``matrices of
input files''.

\section{Axiom Code is Compiled}

Axiom programs are statically compiled to machine code, then
placed into library modules.  Categories provide an important role in
obtaining efficient object code by enabling:
\begin{itemize}
\item static type-checking at compile time;
\item fast linkage to operations in domain-valued parameters;
\item optimization techniques to be used for partially specified types
(operations for ``vectors of $R$'', for instance, can be open-coded even
though {\tt R} is unknown).
\end{itemize}

\section{Axiom is Extensible}

Users and system implementers alike use the Axiom language to
add facilities to the Axiom library.  The entire Axiom
library is in fact written in the Axiom source code and
available for user modification and/or extension.

%Original Page 15

Axiom's use of abstract datatypes clearly separates the exports
of a domain (what operations are defined) from its implementation (how
the objects are represented and operations are defined).  Users of a
domain can thus only create and manipulate objects through these
exported operations.  This allows implementers to ``remove and
replace'' parts of the library safely by newly upgraded (and, we hope,
correct) implementations without consequence to its users.

Categories protect names by context, making the same names available
for use in other contexts.  Categories also provide for code-economy.
Algorithms can be parameterized categorically to characterize their
correct and most general context.  Once compiled, the same machine
code is applicable in all such contexts.

Finally, Axiom provides an automatic, guaranteed interaction
between new and old code.  For example:
\begin{itemize}
\item if you write a new algorithm that requires a parameter to be a
field, then your algorithm will work automatically with every field
defined in the system; past, present, or future.
\item if you introduce a new domain constructor that produces a field,
then the objects of that domain can be used as parameters to any algorithm
using field objects defined in the system; past, present, or future.
\end{itemize}

These are the key ideas.  For further information, we particularly
recommend your reading chapters 11, 12, and 13, where these ideas are
explained in greater detail.

\section{Using Axiom as a Pocket Calculator}
At the simplest level Axiom can be used as a pocket calculator
where expressions involving numbers and operators are entered 
directly in infix notation. In this sense the more advanced
features of the calculator can be regarded as operators (e.g 
{\bf sin}, {\bf cos}, etc).

\subsection{Basic Arithmetic}
An example of this might be to calculate the cosine of 2.45 (in radians).
To do this one would type:

\spadcommand{(1) -> cos 2.45}
$$
-{0.7702312540 473073417} 
$$
\returnType{Type: Float}

Before proceeding any further it would be best to explain the previous 
three lines. Firstly the text ``(1) {\tt ->} '' is part of the prompt that the
Axiom system provides when in interactive mode. The full prompt has other 
text preceding this but it is not relevant here. The number in parenthesis
is the step number of the input which may be used to refer to the 
{\sl results} of previous calculations. The step number appears at the start
of the second line to tell you which step the result belongs to. Since the
interpreter probably loaded numberous libraries to calculate the result given
above and listed each one in the prcess, there could easily be several pages
of text between your input and the answer.

The last line contains the type of the result. The type {\tt Float} is used
to represent real numbers of arbitrary size and precision (where the user is
able to define how big arbitrary is -- the default is 20 digits but can be
as large as your computer system can handle). The type of the result can help
track down mistakes in your input if you don't get the answer you expected.

Other arithmetic operations such as addition, subtraction, and multiplication
behave as expected:

\spadcommand{6.93 * 4.1328}
$$
28.640304 
$$
\returnType{Type: Float}

\spadcommand{6.93 / 4.1328}
$$
1.6768292682 926829268 
$$
\returnType{Type: Float}

but integer division isn't quite so obvious. For example, if one types:

\spadcommand{4/6}
$$
\frac{2}{3}
$$
\returnType{Type: Fraction Integer}

a fractional result is obtained. The function used to display fractions
attempts to produce the most readable answer. In the example:

\spadcommand{4/2}
$$
2 
$$
\returnType{Type: Fraction Integer}

the result is stored as the fraction 2/1 but is displayed as the integer 2.
This fraction could be converted to type {\tt Integer} with no loss of
information but Axiom will not do so automatically.

\subsection{Type Conversion}
To obtain the floating point value of a fraction one must convert 
({\bf conversions} are applied by the user and 
{\bf coercions} are applied automatically by the interpreter) the result
to type {\tt Float} using the ``::'' operator as follows: 

\spadcommand{(23/5)::Float}
$$
4.6 
$$
\returnType{Type: Float}

Although Axiom can convert this back to a fraction it might not be the
same fraction you started with as due to rounding errors. For example, the
following conversion appears to be without error but others might not:

\spadcommand{\%::Fraction Integer}
$$
\frac{23}{5}
$$
\returnType{Type: Fraction Integer}

where ``\%'' represents the previous {\it result} (not the calculation).

Although Axiom has the ability to work with floating-point numbers to
a very high precision it must be remembered that calculations with these
numbers are {\bf not} exact. Since Axiom is a computer algebra package and
not a numerical solutions package this should not create too many problems.
The idea is that the user should use Axiom to do all the necessary symbolic
manipulation and only at the end should actual numerical results be extracted.

If you bear in mind that Axiom appears to store expressions just as you have
typed them and does not perform any evalutation of them unless forced to then
programming in the system will be much easier. It means that anything you
ask Axiom to do (within reason) will be carried out with complete accuracy.

In the previous examples the ``::'' operator was used to convert values from
one type to another. This type conversion is not possible for all values.
For instance, it is not possible to convert the number 3.4 to an integer
type since it can't be represented as an integer. The number 4.0 can be 
converted to an integer type since it has no fractional part.

Conversion from floating point values to integers is performed using the 
functions {\bf round} and {\bf truncate}. The first of these rounds a 
floating point number to the nearest integer while the other truncates
(i.e. removes the fractional part). Both functions return the result as a
{\bf floating point} number. To extract the fractional part of a floating
point number use the function {\bf fractionPart} but note that the sign
of the result depends on the sign of the argument. Axiom obtains the
fractional part of $x$ using $x - truncate(x)$:

\spadcommand{round(3.77623)}
$$
4.0 
$$
\returnType{Type: Float}

\spadcommand{round(-3.77623)}
$$
-{4.0} 
$$
\returnType{Type: Float}

\spadcommand{truncate(9.235)}
$$
9.0 
$$
\returnType{Type: Float}

\spadcommand{truncate(-9.654)}
$$
-{9.0} 
$$
\returnType{Type: Float}

\spadcommand{fractionPart(-3.77623)}
$$
-{0.77623} 
$$
\returnType{Type: Float}

\subsection{Useful Functions}
To obtain the absolute value of a number the {\bf abs} function can be used.
This takes a single argument which is usually an integer or a floating point
value but doesn't necessarily have to be. The sign of a value can be obtained
via the {\bf sign} function which rturns $-1$, $0$, or $1$ depending on the 
sign of the argument.

\spadcommand{abs(4)}
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{abs(-3)}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{abs(-34254.12314)}
$$
34254.12314 
$$
\returnType{Type: Float}

\spadcommand{sign(-49543.2345346)}
$$
-1 
$$
\returnType{Type: Integer}

\spadcommand{sign(0)}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

\spadcommand{sign(234235.42354)}
$$
1 
$$
\returnType{Type: PositiveInteger}

Tests on values can be done using various functions which are generally more
efficient than using relational operators such as $=$ particularly if the 
value is a matrix. Examples of some of these functions are:

\spadcommand{positive?(-234)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{negative?(-234)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{zero?(42)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{one?(1)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{odd?(23)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{odd?(9.435)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{even?(-42)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{prime?(37)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{prime?(-37)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Some other functions that are quite useful for manipulating numerical values
are:

\begin{verbatim}
sin(x)         Sine of x
cos(x)         Cosine of x
tan(x)         Tangent of x
asin(x)        Arcsin of x
acos(x)        Arccos of x
atan(x)        Arctangent of x
gcd(x,y)       Greatest common divisor of x and y
lcm(x,y)       Lowest common multiple of x and y
max(x,y)       Maximum of x and y
min(x,y)       Minimum of x and y
factorial(x)   Factorial of x
factor(x)      Prime factors of x
divide(x,y)    Quotient and remainder of x/y
\end{verbatim}

Some simple infix and prefix operators:
\begin{verbatim}
+      Addition             -      Subtraction
-      Numerical Negation   ~      Logical Negation
/\     Conjunction (AND)    \/     Disjunction (OR)
and    Logical AND (/\)     or     Logical OR (\/)
not    Logical Negation     **     Exponentiation
*      Multiplication       /      Division
quo    Quotient             rem    Remainder
<      less than            >      greater than
<=     less than or equal   >=     greater than or equal
\end{verbatim}

Some useful Axiom macros:
\begin{verbatim}
%i              The square root of -1
%e              The base of the natural logarithm
%pi             Pi
%infinity       Infinity
%plusInfinity   Positive Infinity
%minusInfinity  Negative Infinity
\end{verbatim}

\section{Using Axiom as a Symbolic Calculator}
In the previous section all the examples involved numbers and simple
functions. Also none of the expressions entered were assigned to anything.
In this section we will move on to simple algebra (i.e. expressions involving
symbols and other features available on more sophisticated calculators).

\subsection{Expressions Involving Symbols}
Expressions involving symbols are entered just as they are written down,
for example:

\spadcommand{xSquared := x**2}
$$
x \sp 2 
$$
\returnType{Type: Polynomial Integer}

where the assignment operator ``:='' represents immediate assignment. Later
it will be seen that this form of assignment is not always desirable and
the use of the delayed assignment operator ``=='' will be introduced. The
type of the result is {\tt Polynomial Integer} which is used to represent
polynomials with integer coefficients. Some other examples along similar
lines are:

\spadcommand{xDummy := 3.21*x**2}
$$
{3.21} \  {x \sp 2} 
$$
\returnType{Type: Polynomial Float}

\spadcommand{xDummy := x**2.5}
$$
{x \sp 2} \  {\sqrt {x}} 
$$
\returnType{Type: Expression Float}

\spadcommand{xDummy := x**3.3}
$$
{x \sp 3} \  {{\root {{10}} \of {x}} \sp 3} 
$$
\returnType{Type: Expression Float}

\spadcommand{xyDummy := x**2 - y**2}
$$
-{y \sp 2}+{x \sp 2} 
$$
\returnType{Type: Polynomial Integer}

Given that we can define expressions involving symbols, how do we actually
compute the result when the symbols are assigned values? The answer is to
use the {\bf eval} function which takes an expression as its first argument
followed by a list of assignments. For example, to evaluate the expressions
{\bf xDummy} and {\bf xyDummy} resulting from their respective assignments 
above we type:

\spadcommand{eval(xDummy,x=3)}
$$
37.5405075985 29552193 
$$
\returnType{Type: Expression Float}

\spadcommand{eval(xyDummy, [x=3, y=2.1])}
$$
4.59 
$$
\returnType{Type: Polynomial Float}

\subsection{Complex Numbers}
For many scientific calculations real numbers aren't sufficient and support
for complex numbers is also required. Complex numbers are handled in an
intuitive manner and Axiom, which uses the {\bf \%i} macro to represent
the square root of $-1$. Thus expressions involving complex numbers are
entered just like other expressions.

\spadcommand{(2/3 + \%{\rm i})**3}
$$
-{\frac{46}{27}}+{{\frac{1}{3}} \%{\rm i}} 
$$
\returnType{Type: Complex Fraction Integer}

The real and imaginary parts of a complex number can be extracted using 
the {\bf real} and {\bf imag} functions and the complex conjugate of a
number can be obtained using {\bf conjugate}:

\spadcommand{real(3 + 2*\%{\rm i})}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{imag(3+ 2*\%{\rm i})}
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{conjugate(3 + 2*\%{\rm i})}
$$
3 -{2 \%{\rm i}} 
$$
\returnType{Type: Complex Integer}

The function {\bf factor} can also be applied to complex numbers but the
results aren't quite so obvious as for factoring integer:

\spadcommand{144 + 24*\%{\rm i}}
$$
{144}+{{24} \%{\rm i}} 
$$
\returnType{Type: Complex Integer}

\spadcommand{factor \%}
$$
\displaystyle \%{\rm i} (1 + \%{\rm i})^6\ \  3(6 + \%{\rm i})
$$
\returnType{Type: Factored Complex Integer}

We can see that this multiplies out to the original value by expanding
the factored expression:

\spadcommand{expand \%}
$$
{144}+{{24} \%{\rm i}} 
$$
\returnType{Type: Complex Integer}

\subsection{Number Representations}
By default all numerical results are displayed in decimal with real numbers
shown to 20 significant figures. If the integer part of a number is longer
than 20 digits then nothing after the decimal point is shown and the integer
part is given in full. To alter the number of digits shown the function
{\bf digits} can be called. The result returned by this function is the
previous setting. For example, to find the value of $\pi$ to 40 digits
we type:

\spadcommand{digits(40)}
$$
20 
$$
\returnType{Type: PositiveInteger}

\spadcommand{\%pi::Float}
$$
3.1415926535\ 8979323846\ 2643383279\ 502884197 
$$
\returnType{Type: Float}

As can be seen in the example above, there is a gap after every ten digits.
This can be changed using the {\bf outputSpacing} function where the argument
is the number of digits to be displayed before a space is inserted. If no
spaces are desired then use the value $0$. Two other functions controlling
the appearance of real numbers are {\bf outputFloating} and {\bf outputFixed}.
The former causes Axiom to display floating-point values in exponent notation
and the latter causes it to use fixed-point notation. For example:

\spadcommand{outputFloating(); \%}
$$
0.3141592653 5897932384 6264338327 9502884197 {\rm\ E\ } 1 
$$
\returnType{Type: Float}

\spadcommand{outputFloating(3); 0.00345}
$$
0.345 {\rm\ E\ } -2 
$$
\returnType{Type: Float}

\spadcommand{outputFixed(); \%}
$$
0.00345 
$$
\returnType{Type: Float}

\spadcommand{outputFixed(3); \%}
$$
0.003 
$$
\returnType{Type: Float}

\spadcommand{outputGeneral(); \%}
$$
0.00345 
$$
\returnType{Type: Float}

Note that the semicolon ``;'' in the examples above allows several
expressions to be entered on one line. The result of the last expression
is displayed. Remember also that the percent symbol ``\%'' is used to
represent the result of a previous calculation.

To display rational numbers in a base other than 10 the function {\bf radix}
is used. The first argument of this function is the expression to be 
displayed and the second is the base to be used.

\spadcommand{radix(10**10,32)}
$$
{\rm 9A0NP00 }
$$
\returnType{Type: RadixExpansion 32}

\spadcommand{radix(3/21,5)}
$$
0.{\overline {032412}} 
$$
\returnType{Type: RadixExpansion 5}

Rational numbers can be represented as a repeated decimal expansion using
the {\bf decimal} function or as a continued fraction using 
{\bf continuedFraction}. Any attempt to call these functions with irrational
values will fail.

\spadcommand{decimal(22/7)}
$$
3.{\overline {142857}} 
$$
\returnType{Type: DecimalExpansion}

\spadcommand{continuedFraction(6543/210)}
$$
{31}+ \zag{1}{6}+ \zag{1}{2}+ \zag{1}{1}+ \zag{1}{3} 
$$
\returnType{Type: ContinuedFraction Integer}

Finally, partial fractions in compact and expanded form are available via the
functions {\bf partialFraction} and {\bf padicFraction} respectively. The
former takes two arguments, the first being the numerator of the fraction
and the second being the denominator. The latter function takes a fraction
and expands it further while the function {\bf compactFraction} does the
reverse:

\spadcommand{partialFraction(234,40)}
$$
6 -{\frac{3}{2 \sp 2}}+{\frac{3}{5}} 
$$
\returnType{Type: PartialFraction Integer}

\spadcommand{padicFraction(\%)}
$$
6 -{\frac{1}{2}} -{\frac{1}{2 \sp 2}}+{\frac{3}{5}} 
$$
\returnType{Type: PartialFraction Integer}

\spadcommand{compactFraction(\%)}
$$
6 -{\frac{3}{2 \sp 2}}+{\frac{3}{5}} 
$$
\returnType{Type: PartialFraction Integer}

\spadcommand{padicFraction(234/40)}
$$
\frac{117}{20} 
$$
\returnType{Type: PartialFraction Fraction Integer}

To extract parts of a partial fraction the function {\bf nthFractionalTerm}
is available and returns a partial fraction of one term. To decompose this
further the numerator can be obtained using {\bf firstNumer} and the 
denominator with {\bf firstDenom}. The whole part of a partial fraction can
be retrieved using {\bf wholePart} and the number of fractional parts can
be found using the function {\bf numberOfFractionalTerms}:

\spadcommand{t := partialFraction(234,40)}
$$
6 -{\frac{3}{2 \sp 2}}+{\frac{3}{5}} 
$$
\returnType{Type: PartialFraction Integer}

\spadcommand{wholePart(t)}
$$
6 
$$
\returnType{Type: PositiveInteger}

\spadcommand{numberOfFractionalTerms(t)}
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{p := nthFractionalTerm(t,1)}
$$
-{\frac{3}{2 \sp 2}} 
$$
\returnType{Type: PartialFraction Integer}

\spadcommand{firstNumer(p)}
$$
-3 
$$
\returnType{Type: Integer}

\spadcommand{firstDenom(p)}
$$
2 \sp 2 
$$
\returnType{Type: Factored Integer}

\subsection{Modular Arithmetic}
By using the type constructor {\tt PrimeField} it is possible to do 
arithmetic modulo some prime number. For example, arithmetic module $7$
can be performed as follows:

\spadcommand{x : PrimeField 7 := 5}
$$
5 
$$
\returnType{Type: PrimeField 7}

\spadcommand{x**5 + 6}
$$
2 
$$
\returnType{Type: PrimeField 7}

\spadcommand{1/x}
$$
3 
$$
\returnType{Type: PrimeField 7}

The first example should be read as:
\begin{center}
{\tt Let $x$ be of type PrimeField(7) and assign to it the value $5$}
\end{center}

Note that it is only possible to invert non-zero values if the arithmetic
is performed modulo a prime number. Thus arithmetic modulo a non-prime
integer is possible but the reciprocal operation is undefined and will
generate an error. Attempting to use the {\tt PrimeField} type constructor
with a non-prime argument will generate an error. An example of non-prime
modulo arithmetic is:

\spadcommand{y : IntegerMod 8 := 11}
$$
3 
$$
\returnType{Type: IntegerMod 8}

\spadcommand{y*4 + 27}
$$
7 
$$
\returnType{Type: IntegerMod 8}

Note that polynomials can be constructed in a similar way:

\spadcommand{(3*a**4 + 27*a - 36)::Polynomial PrimeField 7}
$$
{3 \  {a \sp 4}}+{6 \  a}+6 
$$
\returnType{Type: Polynomial PrimeField 7}

\section{General Points about Axiom}
\subsection{Computation Without Output}
It is sometimes desirable to enter an expression and prevent Axiom from
displaying the result. To do this the expression should be terminated with
a semicolon ``;''. In a previous section it was mentioned that a set of 
expressions separated by semicolons would be evaluated and the result
of the last one displayed. Thus if a single expression is followed by a
semicolon no output will be produced (except for its type):

\spadcommand{2 + 4*5;}
\returnType{Type: PositiveInteger}

\subsection{Accessing Earlier Results}
The ``\%'' macro represents the result of the previous computation. The 
``\%\%'' macro is available which takes a single integer argument. If the
argument is positive then it refers to the step number of the calculation
where the numbering begins from one and can be seen at the end of each
prompt (the number in parentheses). If the argument is negative then it
refers to previous results counting backwards from the last result. That is,
``\%\%(-1)'' is the same as ``\%''. The value of ``\%\%(0)'' is not defined and
will generate an error if requested.

\subsection{Splitting Expressions Over Several Lines}
Although Axiom will quite happily accept expressions that are longer than
the width of the screen (just keep typing without pressing the {\bf Return}
key) it is often preferable to split the expression being entered at a point
where it would result in more readable input. To do this the underscore
``\_'' symbol is placed before the break point and then the {\bf Return}
key is pressed. The rest of the expression is typed on the next line,
can be preceeded by any number of whitespace chars, for example:
\begin{verbatim}
2_
+_
3
\end{verbatim}
$$
5 
$$
\returnType{Type: PositiveInteger}

The underscore symbol is an escape character and its presence alters the
meaning of the characters that follow it. As mentions above whitespace
following an underscore is ignored (the {\bf Return} key generates a
whitespace character). Any other character following an underscore loses
whatever special meaning it may have had. Thus one can create the
identifier ``a+b'' by typing ``a\_+b'' although this might lead to confusions.
Also note the result of the following example:

\spadcommand{ThisIsAVeryLong\_\\
VariableName}
$$
ThisIsAVeryLongVariableName 
$$
\returnType{Type: Variable ThisIsAVeryLongVariableName}

\subsection{Comments and Descriptions}
Comments and descriptions are really only of use in files of Axiom code but
can be used when the output of an interactive session is being spooled to
a file (via the system command {\bf )spool}). A comment begins with two
dashes ``- -'' and continues until the end of the line. Multi-line
comments are only possible if each individual line begins with two dashes.

Descriptions are the same as comments except that the Axiom compiler will 
include them in the object files produced and make them availabe to the
end user for documentation purposes.

A description is placed {\bf before} a calculation begins with three
``+'' signs (i.e. ``+++'') and a description placed after a calculation
begins with two plus symbols (i.e.``++''). The so-called ``plus plus''
comments are used within the algebra files and are processed by the
compiler to add to the documentation. The so-called ``minus minus''
comments are ignored everywhere.

\subsection{Control of Result Types}
In earlier sections the type of an expression was converted to another
via the ``::'' operator. However, this is not the only method for
converting between types and two other operators need to be introduced
and explained. 

The first operator is ``\$'' and is used to specify the package to be
used to calculate the result. Thus:

\spadcommand{(2/3)\$Float}
$$
0.6666666666\ 6666666667 
$$
\returnType{Type: Float}

tells Axiom to use the ``/'' operator from the {\tt Float} package to
evaluate the expression $2/3$. This does not necessarily mean that the
result will be of the same type as the domain from which the operator
was taken. In the following example the {\bf sign} operator is taken
from the {\tt Float} package but the result is of type {\tt Integer}.

\spadcommand{sign(2.3)\$Float}
$$
1 
$$
\returnType{Type: Integer}

The other operator is ``@'' which is used to tell Axiom what the desired
type of the result of the calculation is. In most situations all three
operators yield the same results but the example below should help 
distinguish them.

\spadcommand{(2 + 3)::String}
$$
\mbox{\tt "5"} 
$$
\returnType{Type: String}

\spadcommand{(2 + 3)@String}
\begin{verbatim}
An expression involving @ String actually evaluated to one of 
   type PositiveInteger . Perhaps you should use :: String .
\end{verbatim}

\spadcommand{(2 + 3)\$String}
\begin{verbatim}
   The function + is not implemented in String .
\end{verbatim}

If an expression {\sl X} is converted using one of the three operators to 
type {\sl T} the interpretations are:

{\bf ::} means explicitly convert {\sl X} to type {\sl T} if possible.

{\bf \$} means use the available operators for type {\sl T} to compute {\sl X}.

{\bf @} means choose operators to compute {\sl X} so that the result is of
type {\sl T}.

\section{Data Structures in Axiom}
This chapter is an overview of {\sl some} of the data structures provided
by Axiom.
\subsection{Lists}
The Axiom {\tt List} type constructor is used to create homogenous lists of
finite size. The notation for lists and the names of the functions that 
operate over them are similar to those found in functional languages such
as ML.

Lists can be created by placing a comma separated list of values inside
square brackets or if a list with just one element is desired then the
function {\bf list} is available:

\spadcommand{[4]}
$$
\left[
4 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{list(4)}
$$
\left[
4 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{[1,2,3,5,7,11]}
$$
\left[
1,  2,  3,  5,  7,  {11} 
\right]
$$
\returnType{Type: List PositiveInteger}

The function {\bf append} takes two lists as arguments and returns the list
consisting of the second argument appended to the first. A single element
can be added to the front of a list using {\bf cons}:

\spadcommand{append([1,2,3,5],[7,11])}
$$
\left[
1,  2,  3,  5,  7,  {11} 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{cons(23,[65,42,19])}
$$
\left[
{23},  {65},  {42},  {19} 
\right]
$$
\returnType{Type: List PositiveInteger}

Lists are accessed sequentially so if Axiom is asked for the value of the
twentieth element in the list it will move from the start of the list over
nineteen elements before it reaches the desired element. Each element of a 
list is stored as a node consisting of the value of the element and a pointer
to the rest of the list. As a result the two main operations on a list are
called {\bf first} and {\bf rest}. Both of these functions take a second
optional argument which specifies the length of the first part of the list:

\spadcommand{first([1,5,6,2,3])}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{first([1,5,6,2,3],2)}
$$
\left[
1,  5 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{rest([1,5,6,2,3])}
$$
\left[
5,  6,  2,  3 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{rest([1,5,6,2,3],2)}
$$
\left[
6,  2,  3 
\right]
$$
\returnType{Type: List PositiveInteger}

Other functions are {\bf empty?} which tests to see if a list contains no
elements, {\bf member?} which tests to see if the first argument is a member
of the second, {\bf reverse} which reverses the order of the list, {\bf sort}
which sorts a list, and {\bf removeDuplicates} which removes any duplicates.
The length of a list can be obtained using the ``\#'' operator.

\spadcommand{empty?([7,2,-1,2])}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{member?(-1,[7,2,-1,2])}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{reverse([7,2,-1,2])}
$$
\left[
2,  -1,  2,  7 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{sort([7,2,-1,2])}
$$
\left[
-1,  2,  2,  7 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{removeDuplicates([1,5,3,5,1,1,2])}
$$
\left[
1,  5,  3,  2 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{\#[7,2,-1,2]}
$$
4 
$$
\returnType{Type: PositiveInteger}

Lists in Axiom are mutable and so their contents (the elements and the links)
can be modified in place. Functions that operate over lists in this way have
names ending in the symbol ``!''. For example, {\bf concat!} takes two lists
as arguments and appends the second argument to the first (except when the
first argument is an empty list) and {\bf setrest!} changes the link 
emanating from the first argument to point to the second argument:

\spadcommand{u := [9,2,4,7]}
$$
\left[
9,  2,  4,  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{concat!(u,[1,5,42]); u}
$$
\left[
9,  2,  4,  7,  1,  5,  {42} 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{endOfu := rest(u,4)}
$$
\left[
1,  5,  {42} 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{partOfu := rest(u,2)}
$$
\left[
4,  7,  1,  5,  {42} 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{setrest!(endOfu,partOfu); u}
$$
\left[
9,  2,  {\overline {4,  7,  1}} 
\right]
$$
\returnType{Type: List PositiveInteger}

From this it can be seen that the lists returned by {\bf first} and {\bf rest}
are pointers to the original list and {\sl not} a copy. Thus great care must
be taken when dealing with lists in Axiom.

Although the {\sl n}th element of the list {\sl l} can be obtained by 
applying the {\bf first} function to $n-1$ applications of {\bf rest}
to {\sl l}, Axiom provides a more useful access method in the form of
the ``.'' operator:

\spadcommand{u.3}
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{u.5}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{u.6}
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{first rest rest u -- Same as u.3}
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{u.first}
$$
9 
$$
\returnType{Type: PositiveInteger}

\spadcommand{u(3)}
$$
4 
$$
\returnType{Type: PositiveInteger}

The operation {\sl u.i} is referred to as {\sl indexing into u} or 
{\sl elting into u}. The latter term comes from the {\bf elt} function
which is used to extract elements (the first element of the list is at
index $1$).

\spadcommand{elt(u,4)}
$$
7 
$$
\returnType{Type: PositiveInteger}

If a list has no cycles then any attempt to access an element beyond the
end of the list will generate an error. However, in the example above there
was a cycle starting at the third element so the access to the sixth
element wrapped around to give the third element. Since lists are mutable it
is possible to modify elements directly:

\spadcommand{u.3 := 42; u}
$$
\left[
9,  2,  {\overline {{42},  7,  1}} 
\right]
$$
\returnType{Type: List PositiveInteger}

Other list operations are:
\spadcommand{L := [9,3,4,7]; \#L}
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{last(L)}
$$
7 
$$
\returnType{Type: PositiveInteger}

\spadcommand{L.last}
$$
7 
$$
\returnType{Type: PositiveInteger}

\spadcommand{L.(\#L - 1)}
$$
4 
$$
\returnType{Type: PositiveInteger}

Note that using the ``\#'' operator on a list with cycles causes Axiom to
enter an infinite loop.

Note that any operation on a list {\sl L} that returns a list ${\sl L}L^{'}$
will, in general, be such that any changes to ${\sl L}L^{'}$ will have the
side-effect of altering {\sl L}. For example:

\spadcommand{m := rest(L,2)}
$$
\left[
4,  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{m.1 := 20; L}
$$
\left[
9,  3,  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{n := L}
$$
\left[
9,  3,  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{n.2 := 99; L}
$$
\left[
9,  {99},  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{n}
$$
\left[
9,  {99},  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

Thus the only safe way of copying lists is to copy each element from one to
another and not use the assignment operator:

\spadcommand{p := [i for i in n] -- Same as `p := copy(n)'}
$$
\left[
9,  {99},  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{p.2 := 5; p}
$$
\left[
9,  5,  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{n}
$$
\left[
9,  {99},  {20},  7 
\right]
$$
\returnType{Type: List PositiveInteger}

In the previous example a new way of constructing lists was given. This is
a powerful method which gives the reader more information about the contents
of the list than before and which is extremely flexible. The example

\spadcommand{[i for i in 1..10]}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10} 
\right]
$$
\returnType{Type: List PositiveInteger}

should be read as

\begin{center}
``Using the expression {\sl i}, generate each element of the list by
iterating the symbol {\sl i} over the range of integers [1,10]''
\end{center}

To generate the list of the squares of the first ten elements we just use:

\spadcommand{[i**2 for i in 1..10]}
$$
\left[
1,  4,  9,  {16},  {25},  {36},  {49},  {64},  {81},  {100} 
\right]
$$
\returnType{Type: List PositiveInteger}

For more complex lists we can apply a condition to the elements that are to
be placed into the list to obtain a list of even numbers between 0 and 11:

\spadcommand{[i for i in 1..10 | even?(i)]}
$$
\left[
2,  4,  6,  8,  {10} 
\right]
$$
\returnType{Type: List PositiveInteger}

This example should be read as:
\begin{center}
``Using the expression {\sl i}, generate each element of the list
by iterating the symbol {\sl i} over the range of integers [1,10] such that 
{\sl i} is even''
\end{center}

The following achieves the same result:

\spadcommand{[i for i in 2..10 by 2]}
$$
\left[
2,  4,  6,  8,  {10} 
\right]
$$
\returnType{Type: List PositiveInteger}

\subsection{Segmented Lists}
A segmented list is one in which some of the elements are ranges of values.
The {\bf expand} function converts lists of this type into ordinary lists:

\spadcommand{[1..10]}
$$
\left[
{1..{10}} 
\right]
$$
\returnType{Type: List Segment PositiveInteger}

\spadcommand{[1..3,5,6,8..10]}
$$
\left[
{1..3},  {5..5},  {6..6},  {8..{10}} 
\right]
$$
\returnType{Type: List Segment PositiveInteger}

\spadcommand{expand(\%)}
$$
\left[
1,  2,  3,  5,  6,  8,  9,  {10} 
\right]
$$
\returnType{Type: List Integer}

If the upper bound of a segment is omitted then a different type of 
segmented list is obtained and expanding it will produce a stream (which
will be considered in the next section):

\spadcommand{[1..]}
$$
\left[
{1..} 
\right]
$$
\returnType{Type: List UniversalSegment PositiveInteger}

\spadcommand{expand(\%)}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

\subsection{Streams}
Streams are infinite lists which have the ability to calculate the next
element should it be required. For example, a stream of positive integers
and a list of prime numbers can be generated by:

\spadcommand{[i for i in 1..]}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10},  \ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

\spadcommand{[i for i in 1.. | prime?(i)]}
$$
\left[
2,  3,  5,  7,  {11},  {13},  {17},  {19},  {23},  {29},  
\ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

In each case the first few elements of the stream are calculated for display
purposes but the rest of the stream remains unevaluated. The value of items
in a stream are only calculated when they are needed which gives rise to
their alternative name of ``lazy lists''.

Another method of creating streams is to use the {\bf generate(f,a)} function.
This applies its first argument repeatedly onto its second to produce the
stream \\
$[a,f(a),f(f(a)),f(f(f(a)))\ldots]$. Given that the function
{\bf nextPrime} returns the lowest prime number greater than its argument we
can generate a stream of primes as follows:

\spadcommand{generate(nextPrime,2)\$Stream Integer}
$$
\left[
2,  3,  5,  7,  {11},  {13},  {17},  {19},  {23},  {29},  
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

As a longer example a stream of Fibonacci numbers will be computed. The
Fibonacci numbers start at $1$ and each following number is the addition
of the two numbers that precede it so the Fibonacci sequence is:
$$1,1,2,3,5,8,\ldots$$. 

Since the generation of any Fibonacci number only relies on knowing the 
previous two numbers we can look at the series through a window of two
elements. To create the series the window is placed at the start over
the values $[1,1]$ and their sum obtained. The window is now shifted to 
the right by one position and the sum placed into the empty slot of the
window; the process is then repeated. To implement this we require a 
function that takes a list of two elements (the current view of the window),
adds them, and outputs the new window. The result is the function
$[a,b]$~{\tt ->}~$[b,a+b]$:
\spadcommand{win : List Integer -> List Integer}
\returnType{Type: Void}

\spadcommand{win(x) == [x.2, x.1 + x.2]}
\returnType{Type: Void}

\spadcommand{win([1,1])}
$$
\left[
1,  2 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{win(\%)}
$$
\left[
2,  3 
\right]
$$
\returnType{Type: List Integer}

Thus it can be seen that by repeatedly applying {\bf win} to the {\sl results}
of the previous invocation each element of the series is obtained. Clearly
{\bf win} is an ideal function to construct streams using the {\bf generate}
function:
\spadcommand{fibs := [generate(win,[1,1])]}
$$
\left[
{\left[ 1,  1 
\right]},
 {\left[ 1,  2 
\right]},
 {\left[ 2,  3 
\right]},
 {\left[ 3,  5 
\right]},
 {\left[ 5,  8 
\right]},
 {\left[ 8,  {13} 
\right]},
 {\left[ {13},  {21} 
\right]},
 {\left[ {21},  {34} 
\right]},
 {\left[ {34},  {55} 
\right]},
 {\left[ {55},  {89} 
\right]},
 \ldots 
\right]
$$
\returnType{Type: Stream List Integer}

This isn't quite what is wanted -- we need to extract the first element of
each list and place that in our series:
\spadcommand{fibs := [i.1 for i in [generate(win,[1,1])] ]}
$$
\left[
1,  1,  2,  3,  5,  8,  {13},  {21},  {34},  {55},  
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

Obtaining the 200th Fibonacci number is trivial:
\spadcommand{fibs.200}
$$
280571172992510140037611932413038677189525 
$$
\returnType{Type: PositiveInteger}

One other function of interest is {\bf complete} which expands a finite
stream derived from an infinite one (and thus was still stored as an
infinite stream) to form a finite stream.

\subsection{Arrays, Vectors, Strings, and Bits}
The simplest array data structure is the {\sl one-dimensional array} which
can be obtained by applying the {\bf oneDimensionalArray} function to a list:
\spadcommand{oneDimensionalArray([7,2,5,4,1,9])}
$$
\left[
7,  2,  5,  4,  1,  9 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

One-dimensional arrays are homogenous (all elements must have the same type)
and mutable (elements can be changed) like lists but unlike lists they are
constant in size and have uniform access times (it is just as quick to read
the last element of a one-dimensional array as it is to read the first; this
is not true for lists).

Since these arrays are mutable all the warnings that apply to lists apply to
arrays. That is, it is possible to modify an element in a copy of an array
and change the original:
\spadcommand{x := oneDimensionalArray([7,2,5,4,1,9])}
$$
\left[
7,  2,  5,  4,  1,  9 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{y := x}
$$
\left[
7,  2,  5,  4,  1,  9 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{y.3 := 20 ; x}
$$
\left[
7,  2,  {20},  4,  1,  9 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

Note that because these arrays are of fixed size the {\bf concat!} function
cannot be applied to them without generating an error. If arrays of this 
type are required use the {\bf FlexibleArray} constructor.

One-dimensional arrays can be created using {\bf new} which specifies the size
of the array and the initial value for each of the elements. Other operations
that can be applied to one-dimensional arrays are {\bf map!} which applies
a mapping onto each element, {\bf swap!} which swaps two elements and
{\bf copyInto!(a,b,c)} which copies the array {\sl b} onto {\sl a} starting at
position {\sl c}.
\spadcommand{a : ARRAY1 PositiveInteger := new(10,3)}
$$
\left[
3,  3,  3,  3,  3,  3,  3,  3,  3,  3 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

(note that {\tt ARRAY1} is an abbreviation for the type 
{\tt OneDimensionalArray}.) Other types based on one-dimensional arrays are
{\tt Vector}, {\tt String}, and {\tt Bits}.

\spadcommand{map!(i +-> i+1,a); a}
$$
\left[
4,  4,  4,  4,  4,  4,  4,  4,  4,  4 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{b := oneDimensionalArray([2,3,4,5,6])}
$$
\left[
2,  3,  4,  5,  6 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{swap!(b,2,3); b}
$$
\left[
2,  4,  3,  5,  6 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{copyInto!(a,b,3)}
$$
\left[
4,  4,  2,  4,  3,  5,  6,  4,  4,  4 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{a}
$$
\left[
4,  4,  2,  4,  3,  5,  6,  4,  4,  4 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

\spadcommand{vector([1/2,1/3,1/14])}
$$
\left[
{\frac{1}{2}},  {\frac{1}{3}},  {\frac{1}{14}} 
\right]
$$
\returnType{Type: Vector Fraction Integer}

\spadcommand{"Hello, World"}
$$
\mbox{\tt "Hello, World"} 
$$
\returnType{Type: String}

\spadcommand{bits(8,true)}
$$
\mbox{\tt "11111111"} 
$$
\returnType{Type: Bits}

A vector is similar to a one-dimensional array except that if its 
components belong to a ring then arithmetic operations are provided.

\subsection{Flexible Arrays}
Flexible arrays are designed to provide the efficiency of one-dimensional
arrays while retaining the flexibility of lists. They are implemented by
allocating a fixed block of storage for the array. If the array needs to
be expanded then a larger block of storage is allocated and the contents
of the old block are copied into the new one.

There are several operations that can be applied to this type, most of
which modify the array in place. As a result these functions all have 
names ending in ``!''. The {\bf physicalLength} returns the actual length
of the array as stored in memory while the {\bf physicalLength!} allows this
value to be changed by the user.
\spadcommand{f : FARRAY INT := new(6,1)}
$$
\left[
1,  1,  1,  1,  1,  1 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{f.1:=4; f.2:=3 ; f.3:=8 ; f.5:=2 ; f}
$$
\left[
4,  3,  8,  1,  2,  1 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{insert!(42,f,3); f}
$$
\left[
4,  3,  {42},  8,  1,  2,  1 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{insert!(28,f,8); f}
$$
\left[
4,  3,  {42},  8,  1,  2,  1,  {28} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{removeDuplicates!(f)}
$$
\left[
4,  3,  {42},  8,  1,  2,  {28} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{delete!(f,5)}
$$
\left[
4,  3,  {42},  8,  2,  {28} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{g:=f(3..5)}
$$
\left[
{42},  8,  2 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{g.2:=7; f}
$$
\left[
4,  3,  {42},  8,  2,  {28} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{insert!(g,f,1)}
$$
\left[
{42},  7,  2,  4,  3,  {42},  8,  2,  {28} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{physicalLength(f)}
$$
10 
$$
\returnType{Type: PositiveInteger}

\spadcommand{physicalLength!(f,20)}
$$
\left[
{42},  7,  2,  4,  3,  {42},  8,  2,  {28} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{merge!(sort!(f),sort!(g))}
$$
\left[
2,  2,  2,  3,  4,  7,  7,  8,  {28},  {42},  {42},  
{42} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

\spadcommand{shrinkable(false)\$FlexibleArray(Integer)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

There are several things to point out concerning these
examples. First, although flexible arrays are mutable, making copies
of these arrays creates separate entities. This can be seen by the
fact that the modification of element {\sl g.2} above did not alter
{\sl f}. Second, the {\bf merge!}  function can take an extra argument
before the two arrays are merged. The argument is a comparison
function and defaults to ``{\tt <=}'' if omitted. Lastly, 
{\bf shrinkable} tells the system whether or not to let flexible arrays
contract when elements are deleted from them. An explicit package
reference must be given as in the example above.

\section{Functions, Choices, and Loops}
By now the reader should be able to construct simple one-line expressions
involving variables and different data structures. This section builds on
this knowledge and shows how to use iteration, make choices, and build
functions in Axiom. At the moment it is assumed that the reader has a rough
idea of how types are specified and constructed so that they can follow
the examples given.

From this point on most examples will be taken from input files. 

\subsection{Reading Code from a File}
Input files contain code that will be fed to the command prompt. The 
primary difference between the command line and an input file is that
indentation matters. In an input file you can specify ``piles'' of code
by using indentation. 

The names of all input files in Axiom should end in ``.input'' otherwise
Axiom will refuse to read them. 

If an input file is named {\bf foo.input} you can feed the contents of
the file to the command prompt (as though you typed them) by writing:
{\bf )read foo.input}.

It is good practice to start each input file with the {\bf )clear all}
command so that all functions and variables in the current environment
are erased. 
\subsection{Blocks}
The Axiom constructs that provide looping, choices, and user-defined
functions all rely on the notion of blocks. A block is a sequence of
expressions which are evaluated in the order that they appear except
when it is modified by control expressions such as loops. To leave a
block prematurely use an expression of the form:
{\sl BoolExpr}~{\tt =>}~{\sl Expr} 
where {\sl BoolExpr} is any Axiom expression that has type {\tt Boolean}. 
The value and type of {\sl Expr} determines the value and type returned 
by the block.

If blocks are entered at the keyboard (as opposed to reading them from
a text file) then there is only one way of creating them. The syntax is:
$$( expression1 ; expression2; \ldots ; expressionN )$$

In an input file a block can be constructed as above or by placing all the
statements at the same indentation level. When indentation is used to
indicate program structure the block is called a {\sl pile}. As an example
of a simple block a list of three integers can be constructed using
parentheses:
\spadcommand{( a:=4; b:=1; c:=9; L:=[a,b,c])}
$$
\left[
4,  1,  9 
\right]
$$
\returnType{Type: List PositiveInteger}

Doing the same thing using piles in an input file you could type:
\begin{verbatim}
L :=
  a:=4
  b:=1
  c:=9
  [a,b,c]
\end{verbatim}
$$
\left[
4, 1, 9 
\right]
$$
\returnType{Type: List PositiveInteger}

Since blocks have a type and a value they can be used as arguments to 
functions or as part of other expressions. It should be pointed out that
the following example is not recommended practice but helps to illustrate
the idea of blocks and their ability to return values:
\begin{verbatim}
sqrt(4.0 +
         a:=3.0
         b:=1.0
         c:=a + b
         c
    )
\end{verbatim}
$$
2.8284271247\ 461900976 
$$
\returnType{Type: Float}

Note that indentation is {\bf extremely} important. If the example above
had the pile starting at ``a:='' moved left by two spaces so that the
``a'' was under the ``('' of the first line then the interpreter would
signal an error. Furthermore if the closing parenthesis ``)'' is moved 
up to give
\begin{verbatim}
sqrt(4.0 +
         a:=3.0
         b:=1.0
         c:=a + b
         c)
\end{verbatim}
\begin{verbatim}
  Line   1: sqrt(4.0 +
           ....A
  Error  A: Missing mate.
  Line   2:          a:=3.0
  Line   3:          b:=1.0
  Line   4:          c:=a + b
  Line   5:          c)
           .........AB
  Error  A: (from A up to B) Ignored.
  Error  B: Improper syntax.
  Error  B: syntax error at top level
  Error  B: Possibly missing a ) 
   5 error(s) parsing 
\end{verbatim}
then the parser will generate errors. If the parenthesis is shifted right 
by several spaces so that it is in line with the ``c'' thus:
\begin{verbatim}
sqrt(4.0 +
         a:=3.0
         b:=1.0
         c:=a + b
         c
         )
\end{verbatim}
\begin{verbatim}
  Line   1: sqrt(4.0 +
           ....A
  Error  A: Missing mate.
  Line   2:          a:=3.0
  Line   3:          b:=1.0
  Line   4:          c:=a + b
  Line   5:          c
  Line   6:          )
           .........A
  Error  A: (from A up to A) Ignored.
  Error  A: Improper syntax.
  Error  A: syntax error at top level
  Error  A: Possibly missing a ) 
   5 error(s) parsing 
\end{verbatim}
a similar error will be raised. Finally, the ``)'' must be indented by 
at least one space relative to the sqrt thus:
\begin{verbatim}
sqrt(4.0 +
         a:=3.0
         b:=1.0
         c:=a + b
         c
 )
\end{verbatim}
$$
2.8284271247\ 461900976 
$$
\returnType{Type: Float}
or an error will be generated.

It can be seen that great care needs to be taken when constructing input
files consisting of piles of expressions. It would seem prudent to add
one pile at a time and check if it is acceptable before adding more,
particularly if piles are nested. However, it should be pointed out that
the use of piles as values for functions is not very readable and so
perhaps the delicate nature of their interpretation should deter programmers
from using them in these situations. Using piles should really be restricted
to constructing functions, etc. and a small amount of rewriting can remove
the need to use them as arguments. For example, the previous block could
easily be implemented as:
\begin{verbatim}
a:=3.0
b:=1.0
c:=a + b
sqrt(4.0 + c)
\end{verbatim}
\begin{verbatim}
a:=3.0
\end{verbatim}
$$
3.0
$$
\returnType{Type: Float}

\begin{verbatim}
b:=1.0
\end{verbatim}
$$
1.0
$$
\returnType{Type: Float}

\begin{verbatim}
c:=a + b
\end{verbatim}
$$
4.0
$$
\returnType{Type: Float}

\begin{verbatim}
sqrt(4.0 + c)
\end{verbatim}
$$
2.8284271247\ 461900976
$$
\returnType{Type: Float}

which achieves the same result and is easier to understand. Note that this
is still a pile but it is not as fragile as the previous version.
\subsection{Functions}
Definitions of functions in Axiom are quite simple providing two things
are observed. First, the type of the function must either be completely
specified or completely unspecified. Second, the body of the function is
assigned to the function identifier using the delayed assignment operator
``==''.

To specify the type of something the ``:'' operator is used. Thus to define
a variable {\sl x} to be of type {\tt Fraction Integer} we enter:
\spadcommand{x : Fraction Integer}
\returnType{Type: Void}

For functions the method is the same except that the arguments are
placed in parentheses and the return type is placed after the symbol
``{\tt ->}''.  Some examples of function definitions taking zero, one,
two, or three arguments and returning a list of integers are:

\spadcommand{f : () -> List Integer}
\returnType{Type: Void}

\spadcommand{g : (Integer) -> List Integer}
\returnType{Type: Void}

\spadcommand{h : (Integer, Integer) -> List Integer}
\returnType{Type: Void}

\spadcommand{k : (Integer, Integer, Integer) -> List Integer}
\returnType{Type: Void}

Now the actual function definitions might be:
\spadcommand{f() == [\ ]}
\returnType{Type: Void}

\spadcommand{g(a) == [a]}
\returnType{Type: Void}

\spadcommand{h(a,b) == [a,b]}
\returnType{Type: Void}

\spadcommand{k(a,b,c) == [a,b,c]}
\returnType{Type: Void}

with some invocations of these functions:
\spadcommand{f()}
\begin{verbatim}
   Compiling function f with type () -> List Integer 
\end{verbatim}
$$
\left[\ 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{g(4)}
\begin{verbatim}
   Compiling function g with type Integer -> List Integer 
\end{verbatim}
$$
\left[
4 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{h(2,9)}
\begin{verbatim}
   Compiling function h with type (Integer,Integer) -> List Integer 
\end{verbatim}
$$
\left[
2,  9 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{k(-3,42,100)}
\begin{verbatim}
   Compiling function k with type (Integer,Integer,Integer) -> List 
      Integer 
\end{verbatim}
$$
\left[
-3,  {42},  {100} 
\right]
$$
\returnType{Type: List Integer}

The value returned by a function is either the value of the last expression
evaluated or the result of a {\bf return} statement. For example, the
following are effectively the same:
\spadcommand{p : Integer -> Integer}
\returnType{Type: Void}

\spadcommand{p x == (a:=1; b:=2; a+b+x)}
\returnType{Type: Void}

\spadcommand{p x == (a:=1; b:=2; return(a+b+x))}
\returnType{Type: Void}

Note that a block (pile) is assigned to the function identifier {\bf p} and
thus all the rules about blocks apply to function definitions. Also there was
only one argument so the parenthese are not needed.

This is basically all that one needs to know about defining functions in 
Axiom -- first specify the complete type and then assign a block to the
function name. The rest of this section is concerned with defining more 
complex blocks than those in this section and as a result function definitions
will crop up continually particularly since they are a good way of testing
examples. Since the block structure is more complex we will use the {\bf pile}
notation and thus have to use input files to read the piles.

\subsection{Choices}
Apart from the ``{\tt =>}'' operator that allows a block to exit before the end
Axiom provides the standard {\bf if-then-else} construct. The general
syntax is:
{\center{if {\sl BooleanExpr} then {\sl Expr1} else {\sl Expr2}}}

where ``else {\sl Expr2}'' can be omitted. If the expression {\sl BooleanExpr}
evaluates to {\tt true} then {\sl Expr1} is executed otherwise {\sl Expr2}
(if present) will be executed. An example of piles and {\bf if-then-else} is:
(read from an input file)
\begin{verbatim}
h := 2.0
if h > 3.1 then
      1.0
   else
      z:= cos(h)
      max(x,0.5)
\end{verbatim}
\begin{verbatim}
h := 2.0
\end{verbatim}
$$
2.0
$$
\returnType{Type: Float}

\begin{verbatim}
if h > 3.1 then
      1.0
   else
      z:= cos(h)
      max(x,0.5)
\end{verbatim}
$$
x
$$
\returnType{Type: Polynomial Float}

Note the indentation -- the ``else'' must be indented relative to the ``if''
otherwise it will generate an error (Axiom will think there are two piles,
the second one beginning with ``else'').

Any expression that has type {\tt Boolean} can be used as {\tt BooleanExpr}
and the most common will be those involving the relational operators ``$>$'',
``$<$'', and ``=''. Usually the type of an expression involving the equality
operator ``='' will be {\bf Boolean} but in those situations when it isn't
you may need to use the ``@'' operator to ensure that it is.

\subsection{Loops}
Loops in Axiom are regarded as expressions containing another expression 
called the {\sl loop body}. The loop body is executed zero or more times
depending on the kind of loop. Loops can be nested to any depth.

\subsubsection{The {\tt repeat} loop}
The simplest kind of loop provided by Axiom is the {\bf repeat} loop. The 
general syntax of this is:
{\center{{\bf repeat} {\sl loopBody}}}

This will cause Axiom to execute {\sl loopBody} repeatedly until either a
{\bf break} or {\bf return} statement is encountered. If {\sl loopBody}
contains neither of these statements then it will loop forever. The 
following piece of code will display the numbers from $1$ to $4$:
\begin{verbatim}
i:=1
repeat
  if i > 4 then break
  output(i)
  i:=i+1
\end{verbatim}
\begin{verbatim}
i:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
repeat
  if i > 4 then break
  output(i)
  i:=i+1
 
   1
   2
   3
   4
\end{verbatim}
\returnType{Type: Void}

It was mentioned that loops will only be left when either a {\bf break} or
{\bf return} statement is encountered so why can't one use the ``{\tt =>}'' 
operator? The reason is that the ``{\tt =>}'' operator tells Axiom to leave the
current block whereas {\bf break} leaves the current loop. The {\bf return}
statement leaves the current function.

To skip the rest of a loop body and continue the next iteration of the loop
use the {\bf iterate} statement (the {\tt --} starts a comment in Axiom)
\begin{verbatim}
i := 0
repeat
  i := i + 1
  if i > 6 then break
  -- Return to start if i is odd
  if odd?(i) then iterate
  output(i)
\end{verbatim}
\begin{verbatim}
i := 0
\end{verbatim}
$$
0
$$
\returnType{Type: NonNegativeInteger}

\begin{verbatim}
repeat
  i := i + 1
  if i > 6 then break
  -- Return to start if i is odd
  if odd?(i) then iterate
  output(i)
 
   2
   4
   6
\end{verbatim}
\returnType{Type: Void}

\subsubsection{The {\tt while} loop}
The while statement extends the basic {\bf repeat} loop to place the control
of leaving the loop at the start rather than have it buried in the middle.
Since the body of the loop is still part of a {\bf repeat} loop, {\bf break}
and ``{\tt =>}'' work in the same way as in the previous section. The general
syntax of a {\bf while} loop is:
{\center{while {\sl BoolExpr} repeat {\sl loopBody}}}

As before, {\sl BoolExpr} must be an expression of type {\bf Boolean}. Before
the body of the loop is executed {\sl BoolExpr} is tested. If it evaluates to
{\tt true} then the loop body is entered otherwise the loop is terminated.
Multiple conditions can be applied using the logical operators such as 
{\bf and} or by using several {\bf while} statements before the {\bf repeat}.
\begin{verbatim}
x:=1
y:=1
while x < 4 and y < 10 repeat
  output [x,y]
  x := x + 1
  y := y + 2
\end{verbatim}
\begin{verbatim}
x:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
y:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
while x < 4 and y < 10 repeat
  output [x,y]
  x := x + 1
  y := y + 2
 
   [1,1]
   [2,3]
   [3,5]
\end{verbatim}
\returnType{Type: Void}

We could use two parallel whiles
\begin{verbatim}
x:=1
y:=1
while x < 4 while y < 10 repeat
  output [x,y]
  x := x + 1
  y := y + 2
\end{verbatim}
the {\bf )read} yields:
\begin{verbatim}
x:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
y:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
while x < 4 while y < 10 repeat
  output [x,y]
  x := x + 1
  y := y + 2
 
   [1,1]
   [2,3]
   [3,5]
\end{verbatim}
\returnType{Type: Void}

Note that the last example using two {\bf while} statements is {\sl not} a
nested loop but the following one is:
\begin{verbatim}
x:=1
y:=1
while x < 4 repeat
  while y < 10 repeat
    output [x,y]
    x := x + 1
    y := y + 2
\end{verbatim}
\begin{verbatim}
x:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
y:=1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
while x < 4 repeat
  while y < 10 repeat
    output [x,y]
    x := x + 1
    y := y + 2
 
   [1,1]
   [2,3]
   [3,5]
   [4,7]
   [5,9]
\end{verbatim}
\returnType{Type: Void}

Suppose we that, given a matrix of arbitrary size, find the position and
value of the first negative element by examining the matrix in row-major 
order:
\begin{verbatim}
m := matrix [ [ 21, 37, 53, 14 ],_
              [  8, 22,-24, 16 ],_
              [  2, 10, 15, 14 ],_
              [ 26, 33, 55,-13 ] ]

lastrow := nrows(m)
lastcol := ncols(m)
r := 1
while r <= lastrow repeat
  c := 1 -- Index of first column
  while c <= lastcol repeat
    if elt(m,r,c) < 0 then
      output [r,c,elt(m,r,c)]
      r := lastrow
      break -- Don't look any further
    c := c + 1
  r := r + 1
\end{verbatim}
\begin{verbatim}
m := matrix [ [ 21, 37, 53, 14 ],_
              [  8, 22,-24, 16 ],_
              [  2, 10, 15, 14 ],_
              [ 26, 33, 55,-13 ] ]
\end{verbatim} 
$$
\left[
\begin{array}{cccc}
{21} & {37} & {53} & {14} \\ 
8 & {22} & -{24} & {16} \\ 
2 & {10} & {15} & {14} \\ 
{26} & {33} & {55} & -{13} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

\begin{verbatim}
lastrow := nrows(m)
\end{verbatim}
$$
4
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
lastcol := ncols(m)
\end{verbatim}
$$
4
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
r := 1
\end{verbatim}
$$
1
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
while r <= lastrow repeat
  c := 1 -- Index of first column
  while c <= lastcol repeat
    if elt(m,r,c) < 0 then
      output [r,c,elt(m,r,c)]
      r := lastrow
      break -- Don't look any further
    c := c + 1
  r := r + 1
 
   [2,3,- 24]
\end{verbatim}
\returnType{Type: Void}

\subsubsection{The {\tt for} loop}
The last loop statement of interest is the {\bf for} loop. There are two
ways of creating a {\bf for} loop. The first way uses either a list or
a segment:
\begin{center}
for {\sl var} in {\sl seg} repeat {\sl loopBody}\\
for {\sl var} in {\sl list} repeat {\sl loopBody}
\end{center}
where {\sl var} is an index variable which is iterated over the values in
{\sl seg} or {\sl list}. The value {\sl seg} is a segment such as $1\ldots10$
or $1\ldots$ and {\sl list} is a list of some type. For example:
\begin{verbatim}
for i in 1..10 repeat
  ~prime?(i) => iterate
  output(i)
 
   2
   3
   5
   7
\end{verbatim}
\returnType{Type: Void}

\begin{verbatim}
for w in ["This", "is", "your", "life!"] repeat
  output(w)
 
   This
   is
   your
   life!
\end{verbatim}
\returnType{Type: Void}

The second form of the {\bf for} loop syntax includes a ``{\bf such that}''
clause which must be of type {\bf Boolean}:
\begin{center}
for {\sl var} in {\sl seg} \textbar\ {\sl BoolExpr} repeat {\sl loopBody}\\
for {\sl var} in {\sl list} \textbar\ {\sl BoolExpr} repeat {\sl loopBody}
\end{center}
Some examples are:
\begin{verbatim}
for i in 1..10 | prime?(i) repeat
  output(i)
 
   2
   3
   5
   7
\end{verbatim}
\returnType{Type: Void}

\begin{verbatim}
for i in [1,2,3,4,5,6,7,8,9,10] | prime?(i) repeat
  output(i)
 
   2
   3
   5
   7
\end{verbatim}
\returnType{Type: Void}

You can also use a {\bf while} clause:
\begin{verbatim}
for i in 1.. while i < 7 repeat
  if even?(i) then output(i)
 
   2
   4
   6
\end{verbatim}
\returnType{Type: Void}

Using the ``{\bf such that}'' clause makes this appear simpler:
\begin{verbatim}
for i in 1.. | even?(i) while i < 7 repeat
  output(i)
 
   2
   4
   6
\end{verbatim}
\returnType{Type: Void}

You can use multiple {\bf for} clauses to iterate over several sequences
in parallel:
\begin{verbatim}
for a in 1..4 for b in 5..8 repeat
  output [a,b]
 
   [1,5]
   [2,6]
   [3,7]
   [4,8]
\end{verbatim}
\returnType{Type: Void}

As a general point it should be noted that any symbols referred to in the
``{\bf such that}'' and {\bf while} clauses must be pre-defined. This 
either means that the symbols must have been defined in an outer level
(e.g. in an enclosing loop) or in a {\bf for} clause appearing before the
``{\bf such that}'' or {\bf while}. For example:
\begin{verbatim}
for a in 1..4 repeat
  for b in 7..9 | prime?(a+b) repeat
    output [a,b,a+b]
 
   [2,9,11]
   [3,8,11]
   [4,7,11]
   [4,9,13]
\end{verbatim}
\returnType{Type: Void}

Finally, the {\bf for} statement has a {\bf by} clause to specify the
step size. This makes it possible to iterate over the segment in
reverse order:
\begin{verbatim}
for a in 1..4 for b in 8..5 by -1 repeat
  output [a,b]
 
   [1,8]
   [2,7]
   [3,6]
   [4,5]
\end{verbatim}
\returnType{Type: Void}

Note that without the ``by -1'' the segment 8..5 is empty so there is
nothing to iterate over and the loop exits immediately.


\hyphenation{
multi-set
Uni-var-iate-Poly-nomial
Mul-ti-var-iate-Poly-nomial
Distributed-Mul-ti-var-iate-Poly-nomial
Homo-gen-eous-Distributed-Mul-ti-var-iate-Poly-nomial
New-Distributed-Mul-ti-var-iate-Poly-nomial
General-Distributed-Mul-ti-var-iate-Poly-nomial
}

\mainmatter
\setcounter{chapter}{0} % Chapter 1
\chapter{An Overview of Axiom}
\begin{quote}
When we start cataloging the gains in tools sitting on a computer, the 
benefits of software are amazing. But, if the benefits of software are
so great, why do we worry about making it easier -- don't the ends pay 
for the means? We worry because making such software is extraordinarily
hard and almost no one can do it -- the detail is exhausting, the 
creativity required is extreme, the hours of failure upon failure
requiring patience and persistence would tax anyone claiming to be
sane. Yet we require people with such characteristics be found and
employed and employed cheaply.

-- Christopher Alexander

(from Patterns of Software by Richard Gabriel)

\end{quote}
\label{ugIntro}

%Original Page 19

Welcome to the Axiom environment for interactive computation and
problem solving.  Consider this chapter a brief, whirlwind tour of the
Axiom world.  We introduce you to Axiom's graphics and the
Axiom language.  Then we give a sampling of the large variety of
facilities in the Axiom system, ranging from the various kinds
of numbers, to data types (like lists, arrays, and sets) and
mathematical objects (like matrices, integrals, and differential
equations).  We conclude with the discussion of system commands and an
interactive ``undo.''

Before embarking on the tour, we need to brief those readers working
interactively with Axiom on some details. 

\section{Starting Up and Winding Down}
\label{ugIntroStart}
You need to know how to start the Axiom system and how to stop it.
We assume that Axiom has been correctly installed on your
machine (as described in another Axiom document).

To begin using Axiom, issue the command {\bf axiom} to the
Axiom operating system shell.
\index{axiom @{\bf axiom}} There is a brief pause, some start-up
messages, and then one or more windows appear.

If you are not running Axiom under the X Window System, there is
only one window (the console).  At the lower left of the screen there
is a prompt that \index{prompt} looks like
\begin{verbatim}
(1) ->
\end{verbatim}

%Original Page 20

When you want to enter input to Axiom, you do so on the same
line after the prompt.  The ``1'' in ``(1)'', also called the equation
number, is the computation step number and is incremented 
\index{step number} after you enter Axiom statements.  
Note, however, that a system command such as {\tt )clear all} 
may change the step number in other ways.  We talk about step numbers 
more when we discuss system commands and the workspace history facility.

If you are running Axiom under the X Window System, there may be
two \index{X Window System} windows: the console window (as just
described) and the HyperDoc main menu.  \index{Hyper@{HyperDoc}} 
HyperDoc is a multiple-window hypertext system
that lets you \index{window} view Axiom documentation and
examples on-line, execute Axiom expressions, and generate
graphics.  If you are in a graphical windowing environment, it is
usually started automatically when Axiom begins.  If it is not
running, issue {\tt )hd} to start it.  We discuss the basics of
HyperDoc in \sectionref{ugHyper}.

To interrupt an Axiom computation, hold down the \index{interrupt} 
{\bf Ctrl} (control) key and press {\bf c}.  This brings you back to 
the Axiom prompt.

\boxer{4.6in}{
To exit from Axiom, move to the console window, \index{stopping
@{stopping Axiom}} type {\tt )quit} \index{exiting @{exiting
Axiom}} at the input prompt and press the {\bf Enter} key.
You will probably be prompted with the following
message:
\begin{center}
Please enter {\bf y} or {\bf yes} if you really want to leave the \\
interactive environment and return to the operating system
\end{center}
You should respond {\bf yes}, for example, to exit Axiom.\\
}

We are purposely vague in describing exactly what your screen looks
like or what messages Axiom displays.  Axiom runs on a number of
different machines, operating systems and window environments, and
these differences all affect the physical look of the system.  You can
also change the way that Axiom behaves via {\it system commands}
described later in this chapter and in Appendix A.
System commands are special commands, like {\tt )set}, that begin with
a closing parenthesis and are used to change your environment.  For
example, you can set a system variable so that you are not prompted
for confirmation when you want to leave Axiom.

%Original Page 21

\subsection{Clef}
\label{ugAvailCLEF}
If you are using Axiom under the X Window System, the
\index{Clef} \index{command line editor} Clef command
line editor is probably available and installed.  With this editor you
can recall previous lines with the up and down arrow keys.  To move
forward and backward on a line, use the right and left arrows.  You
can use the {\bf Insert} key to toggle insert mode on or off.  When
you are in insert mode, the cursor appears as a large block and if you
type anything, the characters are inserted into the line without
deleting the previous ones.

If you press the {\bf Home} key, the cursor moves to the beginning of
the line and if you press the {\bf End} key, the cursor moves to the
end of the line.  Pressing {\bf Ctrl-End} deletes all the text from
the cursor to the end of the line.

Clef also provides Axiom operation name completion for
\index{operation name completion} a limited set of operations.  If you
enter a few letters and then press the {\bf Tab} key, Clef tries to
use those letters as the prefix of an Axiom operation name.  If
a name appears and it is not what you want, press {\bf Tab} again to
see another name.

You are ready to begin your journey into the world of Axiom.

\section{Typographic Conventions}
\label{ugIntroTypo}
In this document we have followed these typographical conventions:
\begin{itemize}
%
\item Categories, domains and packages are displayed in this font:\\
{\tt Ring}, {\tt Integer}, {\tt DiophantineSolutionPackage}.
%
\item Prefix operators, infix operators, and punctuation symbols in 
the Axiom language are displayed in the text like this:
{\tt +}, {\tt \$}, {\tt +->}.
%
\item Axiom expressions or expression fragments are displayed in this font:\\
{\tt inc(x) == x + 1}.
%
\item For clarity of presentation, \TeX{} is often used to format expressions\\
$g(x)=x^2+1$.
%
\item Function names and HyperDoc button names are displayed in the text in
this font:
{\bf factor}, {\bf integrate},  {\bf Lighting}.
%
\item Italics are used for emphasis and for words defined in the glossary: \\
{\it category}.
\end{itemize}

This document contains over 2500 examples of Axiom input and output.  All
examples were run though Axiom and their output was created in \TeX{}
form by the Axiom {\tt TexFormat} package.  We have deleted system
messages from the example output if those messages are not important
for the discussions in which the examples appear.

%Original Page 22

\section{The Axiom Language}
\label{ugIntroExpressions}
The Axiom language is a rich language for performing interactive
computations and for building components of the Axiom library.
Here we present only some basic aspects of the language that you need
to know for the rest of this chapter.  Our discussion here is
intentionally informal, with details unveiled on an ``as needed''
basis.  For more information on a particular construct, we suggest you
consult the index.

\subsection{Arithmetic Expressions}
\label{ugIntroArithmetic}
For arithmetic expressions, use the ``{\tt +}'' and ``{\tt -}'' operator
as in mathematics.  Use ``{\tt *}'' for multiplication, and ``{\tt **}''
for exponentiation.  To create a fraction, use ``{\tt /}''.  When an
expression contains several operators, those of highest
{\it precedence} are evaluated first.  For arithmetic operators,
``{\tt **}'' has highest precedence, ``{\tt *}'' and ``{\tt /}'' have the
next highest precedence, and ``{\tt +}'' and ``{\tt -}'' have the lowest
precedence.

Axiom puts implicit parentheses around operations of higher
precedence, and groups those of equal precedence from left to right.
\spadcommand{1 + 2 - 3 / 4 * 3 ** 2 - 1}
$$
-{\frac{19}{4}} 
$$
\returnType{Type: Fraction Integer}

The above expression is equivalent to this.
\spadcommand{((1 + 2) - ((3 / 4) * (3 ** 2))) - 1}
$$
-{\frac{19}{4}} 
$$
\returnType{Type: Fraction Integer}

If an expression contains subexpressions enclosed in parentheses,
the parenthesized subexpressions are evaluated first (from left to
right, from inside out).
\spadcommand{1 + 2 - 3/ (4 * 3 ** (2 - 1))}
$$
\frac{11}{4}
$$
\returnType{Type: Fraction Integer}

\subsection{Previous Results}
\label{ugIntroPrevious}
Use the percent sign ``{\tt \%}'' to refer to the last result.
\index{result!previous} Also, use ``{\tt \%\%}' to refer to
previous results.  \index{percentpercent@{\%\%}} ``{\tt \%\%(-1)}'' is
equivalent to ``{\tt \%}'', ``{\tt \%\%(-2)}'' returns the next to
the last result, and so on.  ``{\tt \%\%(1)}'' returns the result from
step number 1, ``{\tt \%\%(2)}'' returns the result from step number 2,
and so on.  ``{\tt \%\%(0)}'' is not defined.

This is ten to the tenth power.
\spadcommand{10 ** 10}
$$
10000000000 
$$
\returnType{Type: PositiveInteger}

%Original Page 23

This is the last result minus one.
\spadcommand{\% - 1}
$$
9999999999 
$$
\returnType{Type: PositiveInteger}

This is the last result.
\spadcommand{\%\%(-1)}
$$
9999999999 
$$
\returnType{Type: PositiveInteger}

This is the result from step number 1.
\spadcommand{\%\%(1)}
$$
10000000000 
$$
\returnType{Type: PositiveInteger}

\subsection{Some Types}
\label{ugIntroTypes}
Everything in Axiom has a type.  The type determines what operations
you can perform on an object and how the object can be used.
The \sectionref{ugTypes} is dedicated to the
interactive use of types.  Several of the final chapters discuss how
types are built and how they are organized in the Axiom library.

Positive integers are given type {\bf PositiveInteger}.
\spadcommand{8}
$$
8 
$$
\returnType{Type: PositiveInteger}

Negative ones are given type {\bf Integer}.  This fine
distinction is helpful to the Axiom interpreter.

\spadcommand{-8}
$$
-8 
$$
\returnType{Type: Integer}

Here a positive integer exponent gives a polynomial result.
\spadcommand{x**8}
$$
x \sp 8 
$$
\returnType{Type: Polynomial Integer}

Here a negative integer exponent produces a fraction.
\spadcommand{x**(-8)}
$$
\frac{1}{x \sp 8} 
$$
\returnType{Type: Fraction Polynomial Integer}

\subsection{Symbols, Variables, Assignments, and Declarations}
\label{ugIntroAssign}
A {\it symbol} is a literal used for the input of things like
the ``variables'' in polynomials and power series.

%Original Page 24

We use the three symbols $x$, $y$, and $z$ in
entering this polynomial.
\spadcommand{(x - y*z)**2}
$$
{{y \sp 2} \  {z \sp 2}} -{2 \  x \  y \  z}+{x \sp 2} 
$$
\returnType{Type: Polynomial Integer}

A symbol has a name beginning with an uppercase or lowercase
alphabetic \index{symbol!naming} character, ``{\tt \%}'', or
``{\tt !}''.  Successive characters (if any) can be any of the
above, digits, or ``{\tt ?}''.  Case is distinguished: the symbol
{\tt points} is different from the symbol {\tt Points}.

A symbol can also be used in Axiom as a {\it variable}.  A variable
refers to a value.  To {\sl assign} a value to a variable,
\index{variable!naming} the operator ``{\tt :=}'' \index{assignment}
is used.\footnote{Axiom actually has two forms of assignment: 
{\it immediate} assignment, as discussed here, and {\it delayed
assignment}.  See \sectionref{ugLangAssign} for details.}  
A variable initially has no restrictions on the kinds
of \index{declaration} values to which it can refer.

This assignment gives the value $4$ (an integer) to
a variable named $x$.
\spadcommand{x := 4}
$$
4 
$$
\returnType{Type: PositiveInteger}

This gives the value $z + 3/5$ (a polynomial)  to $x$.
\spadcommand{x := z + 3/5}
$$
z+{\frac{3}{5}} 
$$
\returnType{Type: Polynomial Fraction Integer}

To restrict the types of objects that can be assigned to a variable,
use a {\it declaration}
\spadcommand{y : Integer}
\returnType{Type: Void}

After a variable is declared to be of some type, only values
of that type can be assigned to that variable.
\spadcommand{y := 89}
$$
89 
$$
\returnType{Type: Integer}

The declaration for $y$ forces values assigned to $y$ to
be converted to integer values.
\spadcommand{y := sin \%pi}
$$
0 
$$
\returnType{Type: Integer}

If no such conversion is possible,
Axiom refuses to assign a value to $y$.
\spadcommand{y := 2/3}
\begin{verbatim}
   Cannot convert right-hand side of assignment
   2
   -
   3

      to an object of the type Integer of the left-hand side.
\end{verbatim}

%Original Page 25

A type declaration can also be given together with an assignment.
The declaration can assist Axiom in choosing the correct
operations to apply.
\spadcommand{f : Float := 2/3}
$$
0.6666666666\ 6666666667 
$$
\returnType{Type: Float}

Any number of expressions can be given on input line.
Just separate them by semicolons.
Only the result of evaluating the last expression is displayed.

These two expressions have the same effect as
the previous single expression.

\spadcommand{f : Float; f := 2/3}
$$
0.6666666666\ 6666666667 
$$
\returnType{Type: Float}

The type of a symbol is either {\tt Symbol}
or {\tt Variable({\it name})} where {\it name} is the name
of the symbol.

By default, the interpreter
gives this symbol the type {\tt Variable(q)}.

\spadcommand{q}
$$
q 
$$
\returnType{Type: Variable q}

When multiple symbols are involved, {\tt Symbol} is used.
\spadcommand{[q, r]}
$$
\left[
q,  r 
\right]
$$
\returnType{Type: List OrderedVariableList [q,r]}

What happens when you try to use a symbol that is the name of a variable?
\spadcommand{f}
$$
0.6666666666\ 6666666667 
$$
\returnType{Type: Float}

Use a single quote ``{\tt '}'' before \index{quote} the name to get the symbol.

\spadcommand{'f}
$$
f 
$$
\returnType{Type: Variable f}

Quoting a name creates a symbol by preventing evaluation of the name
as a variable.  Experience will teach you when you are most likely
going to need to use a quote.  We try to point out the location of
such trouble spots.

\subsection{Conversion}
\label{ugIntroConversion}
Objects of one type can usually be ``converted'' to objects of several
other types.  To {\sl convert} an object to a new type, use the ``{\tt ::}'' 
infix operator.\footnote{Conversion is discussed in detail in
\sectionref{ugTypesConvert}.}  For example,
to display an object, it is necessary to convert the object to type
{\tt OutputForm}.

%Original Page 26

This produces a polynomial with rational number coefficients.

\spadcommand{p := r**2 + 2/3}
$$
{r \sp 2}+{\frac{2}{3}} 
$$
\returnType{Type: Polynomial Fraction Integer}

Create a quotient of polynomials with integer coefficients
by using ``{\tt ::}''.

\spadcommand{p :: Fraction Polynomial Integer }
$$
\frac{{3 \  {r \sp 2}}+2}{3}
$$
\returnType{Type: Fraction Polynomial Integer}

Some conversions can be performed automatically when Axiom tries
to evaluate your input.  Others conversions must be explicitly
requested.

\subsection{Calling Functions}
\label{ugIntroCallFun}
As we saw earlier, when you want to add or subtract two values, you
place the arithmetic operator ``{\tt +}'' or ``{\tt -}'' between the two
arguments denoting the values.  To use most other Axiom
operations, however, you use another syntax: \index{function!calling}
write the name of the operation first, then an open parenthesis, then
each of the arguments separated by commas, and, finally, a closing
parenthesis.  If the operation takes only one argument and the
argument is a number or a symbol, you can omit the parentheses.

This calls the operation {\bf factor} with the single integer argument $120$.

\spadcommand{factor(120)}
$$
{2 \sp 3} \  3 \  5 
$$
\returnType{Type: Factored Integer}

This is a call to {\bf divide} with the two integer arguments
$125$ and $7$.
\spadcommand{divide(125,7)}
$$
\left[
{quotient={17}},  {remainder=6} 
\right]
$$
\returnType{Type: Record(quotient: Integer, remainder: Integer)}

This calls {\bf quatern} with four floating-point arguments.
\spadcommand{quatern(3.4,5.6,2.9,0.1)}
$$
{3.4}+{{5.6} \  i}+{{2.9} \  j}+{{0.1} \  k} 
$$
\returnType{Type: Quaternion Float}

This is the same as {\bf factorial}(10).
\spadcommand{factorial 10}
$$
3628800 
$$
\returnType{Type: PositiveInteger}

An operations that returns a {\tt Boolean} value (that is,
{\tt true} or {\tt false}) frequently has a name suffixed with
a question mark (``?'').  For example, the {\bf even?}
operation returns {\tt true} if its integer argument is an even
number, {\tt false} otherwise.

An operation that can be destructive on one or more arguments
usually has a name ending in a exclamation point (``!'').
This actually means that it is {\it allowed} to update its
arguments but it is not {\it required} to do so. For example,
the underlying representation of a collection type may not allow
the very last element to removed and so an empty object may be
returned instead. Therefore, it is important that you use the
object returned by the operation and not rely on a physical
change having occurred within the object. Usually, destructive
operations are provided for efficiency reasons.

%Original Page 27

\subsection{Some Predefined Macros}
\label{ugIntroMacros}
Axiom provides several macros for your convenience.\footnote{See
\sectionref{ugUserMacros} for a discussion on
how to write your own macros.}  Macros are names
\index{macro!predefined} (or forms) that expand to larger expressions
for commonly used values.

\begin{center}
\begin{tabular}{ll}
{\it \%i}             &  The square root of -1. \\
{\it \%e}             &  The base of the natural logarithm. \\
{\it \%pi}            &  $\pi$. \\
{\it \%infinity}      &  $\infty$. \\
{\it \%plusInfinity}  &  $+\infty$. \\
{\it \%minusInfinity} &  $-\infty$.
\end{tabular}
\end{center}
\index{\%i}
\index{\%e}
\index{\%pi}
\index{pi@{$\pi$ (= \%pi)}}
\index{\%infinity}
\index{infinity@{$\infty$ (= \%infinity)}}
\index{\%plusInfinity}
\index{\%minusInfinity}

To display all the macros (along with anything you have
defined in the workspace), issue the system command {\tt )display all}.

\subsection{Long Lines}
\label{ugIntroLong}
When you enter Axiom expressions from your keyboard, there will
be times when they are too long to fit on one line.  Axiom does
not care how long your lines are, so you can let them continue from
the right margin to the left side of the next line.

Alternatively, you may want to enter several shorter lines and have
Axiom glue them together.  To get this glue, put an underscore
(\_) at the end of each line you wish to continue.

\begin{verbatim}
2_
+_
3
\end{verbatim}
is the same as if you had entered
\begin{verbatim}
2+3
\end{verbatim}

Axiom statements in an input file
(see \sectionref{ugInOutIn})
can use indentation to indicate the program structure.
(see \sectionref{ugLangBlocks}).

\subsection{Comments}
\label{ugIntroComments}
Comment statements begin with two consecutive hyphens or two
consecutive plus signs and continue until the end of the line.

The comment beginning with ``{\tt --}'' is ignored by Axiom.
\spadcommand{2 + 3   -- this is rather simple, no?}
$$
5 
$$
\returnType{Type: PositiveInteger}

There is no way to write long multi-line comments other than starting
each line with ``{\tt --}'' or ``{\tt ++}''.

%Original Page 29

\section{Numbers}
\label{ugIntroNumbers}
Axiom distinguishes very carefully between different kinds of
numbers, how they are represented and what their properties are.  Here
are a sampling of some of these kinds of numbers and some things you
can do with them.

Integer arithmetic is always exact.
\spadcommand{11**13 * 13**11 * 17**7 - 19**5 * 23**3}
$$
25387751112538918594666224484237298 
$$
\returnType{Type: PositiveInteger}

Integers can be represented in factored form.
\spadcommand{factor 643238070748569023720594412551704344145570763243}
$$
{{11} \sp {13}} \  {{13} \sp {11}} \  {{17} \sp 7} \  {{19} \sp 5} \  {{23} 
\sp 3} \  {{29} \sp 2} 
$$
\returnType{Type: Factored Integer}

Results stay factored when you do arithmetic.
Note that the $12$ is automatically factored for you.
\spadcommand{\% * 12}
\index{radix}
$$
{2 \sp 2} \  3 \  {{11} \sp {13}} \  {{13} \sp {11}} \  {{17} \sp 7} \  {{19} 
\sp 5} \  {{23} \sp 3} \  {{29} \sp 2} 
$$
\returnType{Type: Factored Integer}

Integers can also be displayed to bases other than 10.
This is an integer in base 11.
\spadcommand{radix(25937424601,11)}
$$
10000000000 
$$
\returnType{Type: RadixExpansion 11}

Roman numerals are also available for those special occasions.
\index{Roman numerals}

\spadcommand{roman(1992)}
$$
{\rm MCMXCII }
$$
\returnType{Type: RomanNumeral}

Rational number arithmetic is also exact.

\spadcommand{r := 10 + 9/2 + 8/3 + 7/4 + 6/5 + 5/6 + 4/7 + 3/8 + 2/9}
$$
\frac{55739}{2520} 
$$
\returnType{Type: Fraction Integer}

To factor fractions, you have to map {\bf factor} onto the numerator
and denominator.

\spadcommand{map(factor,r)}
$$
\frac{{139} \  {401}}{{2 \sp 3} \  {3 \sp 2} \  5 \  7} 
$$
\returnType{Type: Fraction Factored Integer}

{\tt SingleInteger} refers to machine word-length integers.

In English, this expression means ``$11$ as a small integer''.
\spadcommand{11@SingleInteger}
$$
11 
$$
\returnType{Type: SingleInteger}

Machine double-precision floating-point numbers are also available for
numeric and graphical applications.
\spadcommand{123.21@DoubleFloat}
$$
123.21000000000001 
$$
\returnType{Type: DoubleFloat}

%Original Page 30

The normal floating-point type in Axiom, {\tt Float}, is a
software implementation of floating-point numbers in which the
exponent and the mantissa may have any number of digits.
The types {\tt Complex(Float)} and
{\tt Complex(DoubleFloat)} are the corresponding software
implementations of complex floating-point numbers.

This is a floating-point approximation to about twenty digits.
\index{floating point} The ``{\tt ::}'' is used here to change from
one kind of object (here, a rational number) to another (a
floating-point number).

\spadcommand{r :: Float}
$$
22.1186507936 50793651 
$$
\returnType{Type: Float}

Use \spadfunFrom{digits}{Float} to change the number of digits in
the representation.
This operation returns the previous value so you can reset it
later.
\spadcommand{digits(22)}
$$
20 
$$
\returnType{Type: PositiveInteger}

To $22$ digits of precision, the number
$e^{\pi {\sqrt {163.0}}}$ appears to be an integer.
\spadcommand{exp(\%pi * sqrt 163.0)}
$$
26253741 2640768744.0 
$$
\returnType{Type: Float}

Increase the precision to forty digits and try again.
\spadcommand{digits(40);  exp(\%pi * sqrt 163.0)}
$$
26253741\ 2640768743.9999999999\ 9925007259\ 76 
$$
\returnType{Type: Float}

Here are complex numbers with rational numbers as real and
\index{complex numbers} imaginary parts.
\spadcommand{(2/3 + \%i)**3}
$$
-{\frac{46}{27}}+{{\frac{1}{3}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

The standard operations on complex numbers are available.
\spadcommand{conjugate \% }
$$
-{\frac{46}{27}} -{{\frac{1}{3}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

You can factor complex integers.
\spadcommand{factor(89 - 23 * \%i)}
$$
-{{\left( 1+i 
\right)}
\  {{\left( 2+i 
\right)}
\sp 2} \  {{\left( 3+{2 \  i} 
\right)}
\sp 2}} 
$$
\returnType{Type: Factored Complex Integer}

Complex numbers with floating point parts are also available.
\spadcommand{exp(\%pi/4.0 * \%i)}
$$
{0.7071067811\ 8654752440\ 0844362104\ 8490392849} + 
$$
$$
{{0.7071067811\ 8654752440\ 0844362104\ 8490392848} \  i} 
$$
\returnType{Type: Complex Float}

The real and imaginary parts can be symbolic.
\spadcommand{complex(u,v)}
$$
u+{v \  i} 
$$
\returnType{Type: Complex Polynomial Integer}

Of course, you can do complex arithmetic with these also.
\spadcommand{\% ** 2}
$$
-{v \sp 2}+{u \sp 2}+{2 \  u \  v \  i} 
$$
\returnType{Type: Complex Polynomial Integer}

%Original Page 31

Every rational number has an exact representation as a
repeating decimal expansion
\spadcommand{decimal(1/352)}
$$
0.{00284}{\overline {09}} 
$$
\returnType{Type: DecimalExpansion}

A rational number can also be expressed as a continued fraction.

\spadcommand{continuedFraction(6543/210)}
$$
{31}+ \zag{1}{6}+ \zag{1}{2}+ \zag{1}{1}+ \zag{1}{3} 
$$
\returnType{Type: ContinuedFraction Integer}

Also, partial fractions can be used and can be displayed in a
\index{partial fraction}
compact format
\index{fraction!partial}
\spadcommand{partialFraction(1,factorial(10))}
$$
{\frac{159}{2 \sp 8}} -{\frac{23}{3 \sp 4}} 
-{\frac{12}{5 \sp 2}}+{\frac{1}{7}} 
$$
\returnType{Type: PartialFraction Integer}

or expanded format.
\spadcommand{padicFraction(\%)}
$$
{\frac{1}{2}}+{\frac{1}{2 \sp 4}}+{\frac{1}{2 \sp 5}}+{\frac{1}{2 \sp 6}}
+{\frac{1}{2 \sp 7}}+{\frac{1}{2 \sp 8}} -{\frac{2}{3 \sp 2}} 
-{\frac{1}{3 \sp 3}} -{\frac{2}{3 \sp 4}} -{\frac{2}{5}} 
-{\frac{2}{5 \sp 2}}+{\frac{1}{7}} 
$$
\returnType{Type: PartialFraction Integer}

Like integers, bases (radices) other than ten can be used for rational
numbers.
Here we use base eight.
\spadcommand{radix(4/7, 8)}
$$
0.{\overline 4} 
$$
\returnType{Type: RadixExpansion 8}

Of course, there are complex versions of these as well.
Axiom decides to make the result a complex rational number.
\spadcommand{\% + 2/3*\%i}
$$
{\frac{4}{7}}+{{\frac{2}{3}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

You can also use Axiom to manipulate fractional powers.
\index{radical}
\spadcommand{(5 + sqrt 63 + sqrt 847)**(1/3)}
$$
\root {3} \of {{{{14} \  {\sqrt {7}}}+5}} 
$$
\returnType{Type: AlgebraicNumber}

You can also compute with integers modulo a prime.
\spadcommand{x : PrimeField 7 := 5}
$$
5 
$$
\returnType{Type: PrimeField 7}

Arithmetic is then done modulo $7$.
\spadcommand{x**3}
$$
6 
$$
\returnType{Type: PrimeField 7}

Since $7$ is prime, you can invert nonzero values.
\spadcommand{1/x}
$$
3 
$$
\returnType{Type: PrimeField 7}

%Original Page 32

You can also compute modulo an integer that is not a prime.
\spadcommand{y : IntegerMod 6 := 5}
$$
5 
$$
\returnType{Type: IntegerMod 6}

All of the usual arithmetic operations are available.
\spadcommand{y**3}
$$
5 
$$
\returnType{Type: IntegerMod 6}

Inversion is not available if the modulus is not a prime number.
Modular arithmetic and prime fields are discussed in 
\sectionref{ugxProblemFinitePrime}.

\spadcommand{1/y}
\begin{verbatim}
   There are 12 exposed and 13 unexposed library operations named / 
      having 2 argument(s) but none was determined to be applicable. 
      Use HyperDoc Browse, or issue
                                )display op /
      to learn more about the available operations. Perhaps 
      package-calling the operation or using coercions on the arguments
      will allow you to apply the operation.
 
   Cannot find a definition or applicable library operation named / 
      with argument type(s) 
                               PositiveInteger
                                IntegerMod 6
      
      Perhaps you should use "@" to indicate the required return type, 
      or "$" to specify which version of the function you need.
\end{verbatim}

This defines $a$ to be an algebraic number, that is,
a root of a polynomial equation.
\spadcommand{a := rootOf(a**5 + a**3 + a**2 + 3,a)}
$$
a 
$$
\returnType{Type: Expression Integer}

Computations with $a$ are reduced according to the polynomial equation.
\spadcommand{(a + 1)**10}
$$
-{{85} \  {a \sp 4}} -{{264} \  {a \sp 3}} -{{378} \  {a \sp 2}} -{{458} \  
a} -{287} 
$$
\returnType{Type: Expression Integer}

Define $b$ to be an algebraic number involving $a$.
\spadcommand{b := rootOf(b**4 + a,b)}
$$
b 
$$
\returnType{Type: Expression Integer}

Do some arithmetic.
\spadcommand{2/(b - 1)}
$$
\frac{2}{b -1} 
$$
\returnType{Type: Expression Integer}

To expand and simplify this, call {\it ratDenom}
to rationalize the denominator.
\spadcommand{ratDenom(\%)}
$$
\begin{array}{@{}l}
\displaystyle
{{\left({a^4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\ {b^3}}+{{\left({a^
4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\ {b^2}}+ 
\\
\\
\displaystyle
{{\left({a^4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\  b}+{a^4}-{a^
3}+{2 \ {a^2}}- a + 1 
\end{array}
$$

\returnType{Type: Expression Integer}

%Original Page 33

If we do this, we should get $b$.
\spadcommand{2/\%+1}
$$
\frac{\left(
\begin{array}{@{}l}
\displaystyle
{{\left({a^4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\ {b^3}}+{{\left({a^
4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\ {b^2}}+ 
\\
\\
\displaystyle
{{\left({a^4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\  b}+{a^4}
-{a^3}+{2 \ {a^2}}- a + 3 
\end{array}
\right)}{\left(
\begin{array}{@{}l}
\displaystyle
{{\left({a^4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\ {b^3}}+{{\left({a^
4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\ {b^2}}+ 
\\
\\
\displaystyle
{{\left({a^4}-{a^3}+{2 \ {a^2}}- a + 1 \right)}\  b}+{a^4}-{a^
3}+{2 \ {a^2}}- a + 1 
\end{array}
\right)}
$$
\returnType{Type: Expression Integer}

But we need to rationalize the denominator again.

\spadcommand{ratDenom(\%)}
$$
b 
$$
\returnType{Type: Expression Integer}

Types {\tt Quaternion} and {\tt Octonion} are also available.
Multiplication of quaternions is non-commutative, as expected.

\spadcommand{q:=quatern(1,2,3,4)*quatern(5,6,7,8) - quatern(5,6,7,8)*quatern(1,2,3,4)}
$$
-{8 \  i}+{{16} \  j} -{8 \  k} 
$$
\returnType{Type: Quaternion Integer}

\section{Data Structures}
\label{ugIntroCollect}
Axiom has a large variety of data structures available.  Many
data structures are particularly useful for interactive computation
and others are useful for building applications.  The data structures
of Axiom are organized into {\sl category hierarchies}.

A {\it list} \footnote{\domainref{List}} 
is the most commonly used data structure in
Axiom for holding objects all of the same type. The name {\it list} is
short for ``linked-list of nodes.'' Each node consists of a value
(\spadfunFrom{first}{List}) and a link (\spadfunFrom{rest}{List}) that
points to the next node, or to a distinguished value denoting the
empty list.  To get to, say, the third element, Axiom starts at the
front of the list, then traverses across two links to the third node.

Write a list of elements using square brackets with commas separating
the elements.
\spadcommand{u := [1,-7,11]}
$$
\left[
1,  -7,  {11} 
\right]
$$
\returnType{Type: List Integer}

This is the value at the third node.  Alternatively, you can say $u.3$.
\spadcommand{first rest rest u}
$$
11 
$$
\returnType{Type: PositiveInteger}

%Original Page 34

Many operations are defined on lists, such as: {\bf empty?}, to test
that a list has no elements; {\bf cons}$(x,l)$, to create a new list
with {\bf first} element $x$ and {\bf rest} $l$; {\bf reverse}, to
create a new list with elements in reverse order; and {\bf sort}, to
arrange elements in order.

An important point about lists is that they are ``mutable'': their
constituent elements and links can be changed ``in place.''
To do this, use any of the operations whose names end with the
character ``{\tt !}''.

The operation \spadfunFrom{concat!}{List}$(u,v)$ replaces the
last link of the list $u$ to point to some other list $v$.
Since $u$ refers to the original list, this change is seen by $u$.
\spadcommand{concat!(u,[9,1,3,-4]); u}
$$
\left[
1,  -7,  {11},  9,  1,  3,  -4 
\right]
$$
\returnType{Type: List Integer}

A {\it cyclic list} is a list with a ``cycle'': \index{list!cyclic} a
link pointing back to an earlier node of the list.  \index{cyclic
list} To create a cycle, first get a node somewhere down the list.
\spadcommand{lastnode := rest(u,3)}
$$
\left[
9,  1,  3,  -4 
\right]
$$
\returnType{Type: List Integer}

Use \spadfunFrom{setrest!}{List} to change the link emanating from
that node to point back to an earlier part of the list.

\spadcommand{setrest!(lastnode,rest(u,2)); u}
$$
\left[
1,  -7,  {\overline {{11},  9}} 
\right]
$$
\returnType{Type: List Integer}

A {\it stream} is a structure that (potentially) has an infinite
number of distinct elements. Think of a stream as an
``infinite list'' where elements are computed successively.
\footnote{\domainref{Stream}}

Create an infinite stream of factored integers.  Only a certain number
of initial elements are computed and displayed.

\spadcommand{[factor(i) for i in 2.. by 2]}
$$
\left[
2,  {2 \sp 2},  {2 \  3},  {2 \sp 3},  {2 \  5},  {{2 \sp 2} \  3}, 
 {2 \  7},  {2 \sp 4},  {2 \  {3 \sp 2}},  {{2 \sp 2} \  5},  
\ldots 
\right]
$$
\returnType{Type: Stream Factored Integer}

Axiom represents streams by a collection of already-computed
elements together with a function to compute the next element ``on
demand.''  Asking for the $n$-th element causes elements
$1$ through $n$ to be evaluated.
\spadcommand{\%.36}
$$
{2 \sp 3} \  {3 \sp 2} 
$$
\returnType{Type: Factored Integer}

Streams can also be finite or cyclic.
They are implemented by a linked list structure similar to lists
and have many of the same operations.
For example, {\bf first} and {\bf rest} are used to access
elements and successive nodes of a stream.

A {\it one-dimensional array} is another data structure used to hold
objects of the same type \footnote{\domainref{OneDimensionalArray}}.  
Unlike lists, one-dimensional
arrays are inflexible---they are \index{array!one-dimensional}
implemented using a fixed block of storage.  Their advantage is that
they give quick and equal access time to any element.

%Original Page 35

A simple way to create a one-dimensional array is to apply the
operation {\bf oneDimensionalArray} to a list of elements.
\spadcommand{a := oneDimensionalArray [1, -7, 3, 3/2]}
$$
\left[
1,  -7,  3,  {\frac{3}{2}} 
\right]
$$
\returnType{Type: OneDimensionalArray Fraction Integer}

One-dimensional arrays are also mutable: you can change their
constituent elements ``in place.''
\spadcommand{a.3 := 11; a}
$$
\left[
1,  -7,  {11},  {\frac{3}{2}} 
\right]
$$
\returnType{Type: OneDimensionalArray Fraction Integer}

However, one-dimensional arrays are not flexible structures.
You cannot destructively {\bf concat!} them together.
\spadcommand{concat!(a,oneDimensionalArray [1,-2])}
\begin{verbatim}
   There are 5 exposed and 0 unexposed library operations named concat!
      having 2 argument(s) but none was determined to be applicable. 
      Use HyperDoc Browse, or issue
                             )display op concat!
      to learn more about the available operations. Perhaps 
      package-calling the operation or using coercions on the arguments
      will allow you to apply the operation.
 
   Cannot find a definition or applicable library operation named 
      concat! with argument type(s) 
                    OneDimensionalArray Fraction Integer
                         OneDimensionalArray Integer
      
      Perhaps you should use "@" to indicate the required return type, 
      or "$" to specify which version of the function you need.
\end{verbatim}

Examples of datatypes similar to {\tt OneDimensionalArray}
are: {\tt Vector} (vectors are mathematical structures
implemented by one-dimensional arrays), {\tt String} (arrays
of ``characters,'' represented by byte vectors), and
{\tt Bits} (represented by ``bit vectors'').

A vector of 32 bits, each representing the {\bf Boolean} value
${\tt true}$.
\spadcommand{bits(32,true)}
$$
\mbox{\tt "11111111111111111111111111111111"} 
$$
\returnType{Type: Bits}

A {\it flexible array} \footnote{\domainref{FlexibleArray}}
is a cross between a list \index{array!flexible} and a one-dimensional
array. Like a one-dimensional array, a flexible array occupies a fixed
block of storage.  Its block of storage, however, has room to expand.
When it gets full, it grows (a new, larger block of storage is
allocated); when it has too much room, it contracts.

Create a flexible array of three elements.
\spadcommand{f := flexibleArray [2, 7, -5]}
$$
\left[
2,  7,  -5 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Insert some elements between the second and third elements.
\spadcommand{insert!(flexibleArray [11, -3],f,2)}
$$
\left[
2,  {11},  -3,  7,  -5 
\right]
$$
\returnType{Type: FlexibleArray Integer}

%Original Page 36

Flexible arrays are used to implement ``heaps.'' A {\it heap}
\footnote{\domainref{Heap}}
is an example of a data structure called a {\it priority queue}, where
elements are ordered with respect to one another. A heap
is organized so as to optimize insertion
and extraction of maximum elements.  The {\bf extract!} operation
returns the maximum element of the heap, after destructively removing
that element and reorganizing the heap so that the next maximum
element is ready to be delivered.

An easy way to create a heap is to apply the operation {\bf heap}
to a list of values.
\spadcommand{h := heap [-4,7,11,3,4,-7]}
$$
\left[
{11},  4,  7,  -4,  3,  -7 
\right]
$$
\returnType{Type: Heap Integer}

This loop extracts elements one-at-a-time from $h$ until the heap
is exhausted, returning the elements as a list in the order they were
extracted.
\spadcommand{[extract!(h) while not empty?(h)]}
$$
\left[
{11},  7,  4,  3,  -4,  -7 
\right]
$$
\returnType{Type: List Integer}

A {\it binary tree} is a ``tree'' with at most two branches
\index{tree} per node: it is either empty, or else is a node
consisting of a value, and a left and right subtree (again, binary
trees). 
Examples of binary tree types are {\tt BinarySearchTree}, 
{\tt PendantTree}, {\tt TournamentTree}, and {\tt BalancedBinaryTree}.


A {\it binary search tree} is a binary tree such that,
\index{tree!binary search} for each node, the value of the node is
\index{binary search tree} greater than all values (if any) in the
left subtree, and less than or equal all values (if any) in the right
subtree. \footnote{\domainref{BinarySearchTree}}
\spadcommand{binarySearchTree [5,3,2,9,4,7,11]}
$$
\left[
{\left[ 2,  3,  4 
\right]},
 5,  {\left[ 7,  9,  {11} 
\right]}
\right]
$$
\returnType{Type: BinarySearchTree PositiveInteger}

A {\it balanced binary tree} is useful for doing modular computations.
\footnote{\domainref{BalancedBinaryTree}}
\index{balanced binary tree} Given a list $lm$ of moduli,
\index{tree!balanced binary} {\bf modTree}$(a,lm)$ produces
a balanced binary tree with the values $a \bmod m$ at its leaves.
\spadcommand{modTree(8,[2,3,5,7])}
$$
\left[
0,  2,  3,  1 
\right]
$$
\returnType{Type: List Integer}

A {\it set} is a collection of elements where duplication and order is
irrelevant. \footnote{\domainref{Set}} 
Sets are always finite and have no
corresponding structure like streams for infinite collections.

Create sets using braces ``\{'' and ``\}'' rather than brackets.

\spadcommand{fs := set [1/3,4/5,-1/3,4/5]}
$$
\left\{
-{\frac{1}{3}},  {\frac{1}{3}},  {\frac{4}{5}} 
\right\}
$$
\returnType{Type: Set Fraction Integer}

A {\it multiset} is a set that keeps track of the number of duplicate
values. \footnote{\domainref{Multiset}}

%Original Page 37

For all the primes $p$ between 2 and 1000, find the
distribution of $p \bmod 5$.
\spadcommand{multiset [x rem 5 for x in primes(2,1000)]}
$$
\left\{
0,  {{42} \mbox{\rm : } 3},  {{40} \mbox{\rm : } 1},  {{38} \mbox{\rm : 
} 4},  {{47} \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset Integer}

A {\it table} is conceptually a set of ``key--value'' pairs and is a
generalization of a multiset. For examples of tables, see \\
{\tt AssociationList}, {\tt HashTable}, {\tt KeyedAccessFile}, \\
{\tt Library}, {\tt SparseTable}, {\tt StringTable}, and {\tt Table}.\\
The domain {\tt Table(Key, Entry)} provides a general-purpose type for
tables with {\it values} of type $Entry$ indexed by {\it keys} of type
$Key$.

Compute the above distribution of primes using tables.  First, let
$t$ denote an empty table of keys and values, each of type {\tt Integer}.
\spadcommand{t : Table(Integer,Integer) := empty()}
$$
{\rm table}() 
$$
\returnType{Type: Table(Integer,Integer)}

We define a function {\bf howMany} to return the number of values
of a given modulus $k$ seen so far.  It calls
{\bf search}$(k,t)$ which returns the number of values
stored under the key $k$ in table $t$, or {\tt "failed"}
if no such value is yet stored in $t$ under $k$.

In English, this says ``Define $howMany(k)$ as follows.
First, let $n$ be the value of {\it search}$(k,t)$.
Then, if $n$ has the value $"failed"$, return the value
$1$; otherwise return $n + 1$.''
\spadcommand{howMany(k) == (n:=search(k,t); n case "failed" => 1; n+1)}
\returnType{Type: Void}

Run through the primes to create the table, then print the table.
The expression {\tt t.m := howMany(m)} updates the value in table $t$
stored under key $m$.
\spadcommand{for p in primes(2,1000) repeat (m:= p rem 5; t.m:= howMany(m)); t}
\begin{verbatim}
   Compiling function howMany with type Integer -> Integer 
\end{verbatim}
$$
{\rm table }
\left(
{{2={47}},  {4={38}},  {1={40}},  {3={42}},  {0=1}} 
\right)
$$
\returnType{Type: Table(Integer,Integer)}

A {\it record} is an example of an inhomogeneous collection of
objects.\footnote{See \sectionref{ugTypesRecords} for details.}  
A record consists of a
set of named {\it selectors} that can be used to access its
components.  \index{Record@{\sf Record}}

Declare that $daniel$ can only be
assigned a record with two prescribed fields.
\spadcommand{daniel : Record(age : Integer, salary : Float)}
\returnType{Type: Void}

%Original Page 38

Give $daniel$ a value, using square brackets to enclose the values of
the fields.
\spadcommand{daniel := [28, 32005.12]}
$$
\left[
{age={28}},  {salary={32005.12}} 
\right]
$$
\returnType{Type: Record(age: Integer,salary: Float)}

Give $daniel$ a raise.
\spadcommand{daniel.salary := 35000; daniel}
$$
\left[
{age={28}},  {salary={35000.0}} 
\right]
$$
\returnType{Type: Record(age: Integer,salary: Float)}

A {\it union} is a data structure used when objects have multiple
types.\footnote{See \sectionref{ugTypesUnions} for details.}  
\index{Union@{\sf Union}}

Let $dog$ be either an integer or a string value.
\spadcommand{dog: Union(licenseNumber: Integer, name: String)}
\returnType{Type: Void}

Give $dog$ a name.
\spadcommand{dog := "Whisper"}
$$
\mbox{\tt "Whisper"} 
$$
\returnType{Type: Union(name: String,...)}

All told, there are over forty different data structures in Axiom.
Using the domain constructors described in \sectionref{ugDomains},
you can add your own data structure or
extend an existing one.  Choosing the right data structure for your
application may be the key to obtaining good performance.

\section{Expanding to Higher Dimensions}
\label{ugIntroTwoDim}
To get higher dimensional aggregates, you can create one-dimensional
aggregates with elements that are themselves aggregates, for example,
lists of lists, one-dimensional arrays of lists of multisets, and so
on.  For applications requiring two-dimensional homogeneous
aggregates, you will likely find {\it two-dimensional arrays}
\index{matrix} and {\it matrices} most useful.
\index{array!two-dimensional}

The entries in {\tt TwoDimensionalArray} and {\tt Matrix} objects are
all the same type, except that those for {\tt Matrix} must belong to a
{\tt Ring}.  You create and access elements in roughly the same way.
Since matrices have an understood algebraic structure, certain
algebraic operations are available for matrices but not for arrays.
Because of this, we limit our discussion here to {\tt Matrix}, that
can be regarded as an extension of {\tt TwoDimensionalArray}. See {\tt
TwoDimensionalArray} for more information about arrays.  For more
information about Axiom's linear algebra facilities, see 
\domainref{Matrix}, \domainref{Permanent}, \domainref{SquareMatrix}, 
\domainref{Vector}, \domainref{TwoDimensionalArray}, 
\sectionref{ugProblemEigen} (computation of eigenvalues and eigenvectors), 
and \sectionref{ugProblemLinPolEqn} 
(solution of linear and polynomial equations).

You can create a matrix from a list of lists, \index{matrix!creating}
where each of the inner lists represents a row of the matrix.
\spadcommand{m := matrix([ [1,2], [3,4] ])}
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
3 & 4 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

%Original Page 39

The ``collections'' construct (see \sectionref{ugLangIts}) 
is useful for creating matrices whose
entries are given by formulas.  \index{matrix!Hilbert}
\spadcommand{matrix([ [1/(i + j - x) for i in 1..4] for j in 1..4])}
$$
\left[
\begin{array}{cccc}
-{\frac{1}{x -2}}&-{\frac{1}{x -3}}&-{\frac{1}{x -4}}&-{\frac{1}{x -5}}\\ 
-{\frac{1}{x -3}}&-{\frac{1}{x -4}}&-{\frac{1}{x -5}}&-{\frac{1}{x -6}}\\ 
-{\frac{1}{x -4}}&-{\frac{1}{x -5}}&-{\frac{1}{x -6}}&-{\frac{1}{x -7}}\\ 
-{\frac{1}{x -5}}&-{\frac{1}{x -6}}&-{\frac{1}{x -7}}&-{\frac{1}{x -8}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Polynomial Integer}

Let $vm$ denote the three by three Vandermonde matrix.
\spadcommand{vm := matrix [ [1,1,1], [x,y,z], [x*x,y*y,z*z] ]}
$$
\left[
\begin{array}{ccc}
1 & 1 & 1 \\ 
x & y & z \\ 
{x \sp 2} & {y \sp 2} & {z \sp 2} 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

Use this syntax to extract an entry in the matrix.

\spadcommand{vm(3,3)}
$$
z \sp 2 
$$
\returnType{Type: Polynomial Integer}

You can also pull out a {\bf row} or a {\bf column}.

\spadcommand{column(vm,2)}
$$
\left[
1,  y,  {y \sp 2} 
\right]
$$
\returnType{Type: Vector Polynomial Integer}

You can do arithmetic.

\spadcommand{vm * vm}
$$
\left[
\begin{array}{ccc}
{{x \sp 2}+x+1} & {{y \sp 2}+y+1} & {{z \sp 2}+z+1} \\ 
{{{x \sp 2} \  z}+{x \  y}+x} & {{{y \sp 2} \  z}+{y \sp 2}+x} & {{z \sp 
3}+{y \  z}+x} \\ 
{{{x \sp 2} \  {z \sp 2}}+{x \  {y \sp 2}}+{x \sp 2}} & {{{y \sp 2} \  {z \sp 
2}}+{y \sp 3}+{x \sp 2}} & {{z \sp 4}+{{y \sp 2} \  z}+{x \sp 2}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

You can perform operations such as
{\bf transpose}, {\bf trace}, and {\bf determinant}.
\spadcommand{factor determinant vm}
$$
{\left( y -x 
\right)}
\  {\left( z -y 
\right)}
\  {\left( z -x 
\right)}
$$
\returnType{Type: Factored Polynomial Integer}

\section{Writing Your Own Functions}
\label{ugIntroYou}
Axiom provides you with a very large library of predefined
operations and objects to compute with.  You can use the Axiom
library of constructors to create new objects dynamically of quite
arbitrary complexity.  For example, you can make lists of matrices of
fractions of polynomials with complex floating point numbers as
coefficients.  Moreover, the library provides a wealth of operations
that allow you to create and manipulate these objects.

%Original Page 40

For many applications, you need to interact with the interpreter and
write some Axiom programs to tackle your application.
Axiom allows you to write functions interactively,
\index{function} thereby effectively extending the system library.
Here we give a few simple examples, leaving the details to
\sectionref{ugUser}.

We begin by looking at several ways that you can define the
``factorial'' function in Axiom.  The first way is to give a
\index{function!piece-wise definition} piece-wise definition of the
function.  \index{piece-wise function definition} This method is best
for a general recurrence relation since the pieces are gathered
together and compiled into an efficient iterative function.
Furthermore, enough previously computed values are automatically saved
so that a subsequent call to the function can pick up from where it
left off.

Define the value of {\bf fact} at $0$.
\spadcommand{fact(0) == 1}
\returnType{Type: Void}

Define the value of {\bf fact}(n) for general $n$.
\spadcommand{fact(n) == n*fact(n-1)}
\returnType{Type: Void}

Ask for the value at $50$.  The resulting function created by
Axiom computes the value by iteration.

\spadcommand{fact(50)}
\begin{verbatim}
   Compiling function fact with type Integer -> Integer 
   Compiling function fact as a recurrence relation.
\end{verbatim}
$$
30414093201713378043612608166064768844377641568960512000000000000 
$$
\returnType{Type: PositiveInteger}

A second definition uses an {\tt if-then-else} and recursion.
\spadcommand{fac(n) == if n < 3 then n else n * fac(n - 1)}
\returnType{Type: Void}

This function is less efficient than the previous version since
each iteration involves a recursive function call.
\spadcommand{fac(50)}
$$
30414093201713378043612608166064768844377641568960512000000000000 
$$
\returnType{Type: PositiveInteger}

A third version directly uses iteration.
\spadcommand{fa(n) == (a := 1; for i in 2..n repeat a := a*i; a)}
\returnType{Type: Void}

This is the least space-consumptive version.
\spadcommand{fa(50)}
\begin{verbatim}
   Compiling function fac with type Integer -> Integer 
\end{verbatim}
$$
30414093201713378043612608166064768844377641568960512000000000000 
$$
\returnType{Type: PositiveInteger}

%Original Page 41

A final version appears to construct a large list and then reduces over
it with multiplication.
\spadcommand{f(n) == reduce(*,[i for i in 2..n])}
\returnType{Type: Void}

In fact, the resulting computation is optimized into an efficient
iteration loop equivalent to that of the third version.
\spadcommand{f(50)}
\begin{verbatim}
Compiling function f with type 
   PositiveInteger -> PositiveInteger 
\end{verbatim}
$$
30414093201713378043612608166064768844377641568960512000000000000 
$$
\returnType{Type: PositiveInteger}

The library version uses an algorithm that is different from the four
above because it highly optimizes the recurrence relation definition of
{\bf factorial}.

\spadcommand{factorial(50)}
$$
30414093201713378043612608166064768844377641568960512000000000000 
$$
\returnType{Type: PositiveInteger}

You are not limited to one-line functions in Axiom.  If you place your
function definitions in {\bf .input} files \index{file!input} (see
\sectionref{ugInOutIn}), you can have multi-line
functions that use indentation for grouping.

Given $n$ elements, {\bf diagonalMatrix} creates an
$n$ by $n$ matrix with those elements down the diagonal.
This function uses a permutation matrix
that interchanges the $i$th and $j$th rows of a matrix
by which it is right-multiplied.

This function definition shows a style of definition that can be used
in {\bf .input} files.  Indentation is used to create {\sl blocks}:
sequences of expressions that are evaluated in sequence except as
modified by control statements such as {\tt if-then-else} and {\tt return}.

\begin{verbatim}
permMat(n, i, j) ==
  m := diagonalMatrix
    [(if i = k or j = k then 0 else 1)
      for k in 1..n]
  m(i,j) := 1
  m(j,i) := 1
  m
\end{verbatim}

This creates a four by four matrix that interchanges the second and third
rows.
\spadcommand{p := permMat(4,2,3)}
\begin{verbatim}
   Compiling function permMat with type (PositiveInteger,
      PositiveInteger,PositiveInteger) -> Matrix Integer 
\end{verbatim}
$$
\left[
\begin{array}{cccc}
1 & 0 & 0 & 0 \\ 
0 & 0 & 1 & 0 \\ 
0 & 1 & 0 & 0 \\ 
0 & 0 & 0 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

Create an example matrix to permute.
\spadcommand{m := matrix [ [4*i + j for j in 1..4] for i in 0..3]}
$$
\left[
\begin{array}{cccc}
1 & 2 & 3 & 4 \\ 
5 & 6 & 7 & 8 \\ 
9 & {10} & {11} & {12} \\ 
{13} & {14} & {15} & {16} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

%Original Page 42

Interchange the second and third rows of m.
\spadcommand{permMat(4,2,3) * m}
$$
\left[
\begin{array}{cccc}
1 & 2 & 3 & 4 \\ 
9 & {10} & {11} & {12} \\ 
5 & 6 & 7 & 8 \\ 
{13} & {14} & {15} & {16} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

A function can also be passed as an argument to another function,
which then applies the function or passes it off to some other
function that does.  You often have to declare the type of a function
that has functional arguments.

This declares {\bf t} to be a two-argument function that returns a
{\tt Float}.  The first argument is a function that takes one
{\tt Float} argument and returns a {\tt Float}.

\spadcommand{t : (Float -> Float, Float) -> Float}
\returnType{Type: Void}

This is the definition of {\bf t}.

\spadcommand{t(fun, x) == fun(x)**2 + sin(x)**2}
\returnType{Type: Void}

We have not defined a {\bf cos} in the workspace. The one from the
Axiom library will do.

\spadcommand{t(cos, 5.2058)}
$$
1.0 
$$
\returnType{Type: Float}

Here we define our own (user-defined) function.
\spadcommand{cosinv(y) == cos(1/y)}
\returnType{Type: Void}

Pass this function as an argument to {\bf t}.
\spadcommand{t(cosinv, 5.2058)}
$$
1.7392237241\ 8005164925\ 4147684772\ 932520785 
$$
\returnType{Type: Float}

Axiom also has pattern matching capabilities for
\index{simplification}
simplification
\index{pattern matching}
of expressions and for defining new functions by rules.
For example, suppose that you want to apply regularly a transformation
that groups together products of radicals:
$$\sqrt{a}\sqrt{b} \mapsto \sqrt{ab}, \quad
(\forall a)(\forall b)$$
Note that such a transformation is not generally correct.
Axiom never uses it automatically.

%Original Page 43

Give this rule the name {\bf groupSqrt}.
\spadcommand{groupSqrt := rule(sqrt(a) * sqrt(b) == sqrt(a*b))}
$$
{ \%C \  {\sqrt {a}} \  {\sqrt {b}}} \mbox{\rm == } { \%C \  {\sqrt {{a \  
b}}}} 
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

Here is a test expression.
\spadcommand{a := (sqrt(x) + sqrt(y) + sqrt(z))**4}
$$
\begin{array}{@{}l}
\displaystyle
{{\left({{\left({4 \  z}+{4 \  y}+{{12}\  x}\right)}\ {\sqrt{y}}}+
{{\left({4 \  z}+{{12}\  y}+{4 \  x}\right)}\ {\sqrt{x}}}\right)}\ {\sqrt{z}}}+
 
\\
\\
\displaystyle
{{\left({{12}\  z}+{4 \  y}+{4 \  x}\right)}\ {\sqrt{x}}\ {\sqrt{y}}}+
{z^2}+{{\left({6 \  y}+{6 \  x}\right)}\  z}+{y^2}+{6 \  x \  
y}+{x^2}
\end{array}
$$
\returnType{Type: Expression Integer}

The rule
{\bf groupSqrt} successfully simplifies the expression.
\spadcommand{groupSqrt a}
$$
\begin{array}{@{}l}
\displaystyle
{{\left({4 \  z}+{4 \  y}+{{12}\  x}\right)}\ {\sqrt{y \  z}}}+
{{\left({4 \  z}+{{12}\  y}+{4 \  x}\right)}\ {\sqrt{x \  z}}}+
 
\\
\\
\displaystyle
{{\left({{12}\  z}+{4 \  y}+{4 \  x}\right)}\ {\sqrt{x \  y}}}+
{z^2}+{{\left({6 \  y}+{6 \  x}\right)}\  z}+{y^2}+{6 \  x \  
y}+{x^2}
\end{array}
$$
\returnType{Type: Expression Integer}

\section{Polynomials}
\label{ugIntroVariables}
Polynomials are the commonly used algebraic types in symbolic
computation.  \index{polynomial} Interactive users of Axiom
generally only see one type of polynomial: {\tt Polynomial(R)}.
This type represents polynomials in any number of unspecified
variables over a particular coefficient domain $R$.  This type
represents its coefficients {\sl sparsely}: only terms with non-zero
coefficients are represented.

In building applications, many other kinds of polynomial
representations are useful.  Polynomials may have one variable or
multiple variables, the variables can be named or unnamed, the
coefficients can be stored sparsely or densely.  So-called
``distributed multivariate polynomials'' store polynomials as
coefficients paired with vectors of exponents.  This type is
particularly efficient for use in algorithms for solving systems of
non-linear polynomial equations.

The polynomial constructor most familiar to the interactive user
is {\tt Polynomial}.
\spadcommand{(x**2 - x*y**3 +3*y)**2}
$$
{{x \sp 2} \  {y \sp 6}} -{6 \  x \  {y \sp 4}} -{2 \  {x \sp 3} \  {y \sp 
3}}+{9 \  {y \sp 2}}+{6 \  {x \sp 2} \  y}+{x \sp 4} 
$$
\returnType{Type: Polynomial Integer}

If you wish to restrict the variables used,
{\tt UnivariatePolynomial} provides polynomials in one variable.

\spadcommand{p: UP(x,INT) := (3*x-1)**2 * (2*x + 8)}
$$
{{18} \  {x \sp 3}}+{{60} \  {x \sp 2}} -{{46} \  x}+8 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

The constructor {\tt MultivariatePolynomial} provides polynomials
in one or more specified variables.

\spadcommand{m: MPOLY([x,y],INT) := (x**2-x*y**3+3*y)**2}
$$
{x \sp 4} -{2 \  {y \sp 3} \  {x \sp 3}}+{{\left( {y \sp 6}+{6 \  y} 
\right)}
\  {x \sp 2}} -{6 \  {y \sp 4} \  x}+{9 \  {y \sp 2}} 
$$
\returnType{Type: MultivariatePolynomial([x,y],Integer)}

%Original Page 44

You can change the way the polynomial appears by modifying the variable
ordering in the explicit list.
\spadcommand{m :: MPOLY([y,x],INT)}
$$
{{x \sp 2} \  {y \sp 6}} -{6 \  x \  {y \sp 4}} -{2 \  {x \sp 3} \  {y \sp 
3}}+{9 \  {y \sp 2}}+{6 \  {x \sp 2} \  y}+{x \sp 4} 
$$
\returnType{Type: MultivariatePolynomial([y,x],Integer)}

The constructor {\tt DistributedMultivariatePolynomial} provides\\
polynomials in one or more specified variables with the monomials
ordered lexicographically.

\spadcommand{m :: DMP([y,x],INT)}
$$
{{y \sp 6} \  {x \sp 2}} -{6 \  {y \sp 4} \  x} -{2 \  {y \sp 3} \  {x \sp 
3}}+{9 \  {y \sp 2}}+{6 \  y \  {x \sp 2}}+{x \sp 4} 
$$
\returnType{Type: DistributedMultivariatePolynomial([y,x],Integer)}

The constructor
{\tt HomogeneousDistributedMultivariatePolynomial} is similar
except that the monomials are ordered by total order refined by
reverse lexicographic order.
\spadcommand{m :: HDMP([y,x],INT)}
$$
{{y \sp 6} \  {x \sp 2}} -{2 \  {y \sp 3} \  {x \sp 3}} -{6 \  {y \sp 4} \  
x}+{x \sp 4}+{6 \  y \  {x \sp 2}}+{9 \  {y \sp 2}} 
$$
\returnType{Type: HomogeneousDistributedMultivariatePolynomial([y,x],Integer)}

More generally, the domain constructor
{\tt GeneralDistributedMultivariatePolynomial} allows the user to
provide an arbitrary predicate to define his own term ordering.  These
last three constructors are typically used in Gr\"{o}bner basis
applications and
when a flat (that is, non-recursive) display is wanted and the term
ordering is critical for controlling the computation.

\section{Limits}
\label{ugIntroCalcLimits}

Axiom's {\bf limit} function is usually used to evaluate
limits of quotients where the numerator and denominator \index{limit}
both tend to zero or both tend to infinity.  To find the limit of an
expression $f$ as a real variable $x$ tends to a limit
value $a$, enter {\tt limit(f, x=a)}.  Use
{\bf complexLimit} if the variable is complex.  Additional
information and examples of limits are in 
\sectionref{ugProblemLimits}.

You can take limits of functions with parameters.
\index{limit!of function with parameters}
\spadcommand{g := csc(a*x) / csch(b*x)}
$$
\frac{\csc \left({{a \  x}} \right)}{\csch \left({{b \  x}} \right)}
$$
\returnType{Type: Expression Integer}

As you can see, the limit is expressed in terms of the parameters.
\spadcommand{limit(g,x=0)}
$$
\frac{b}{a}
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

A variable may also approach plus or minus infinity:
\spadcommand{h := (1 + k/x)**x}
$$
{\frac{x+k}{x}} \sp x 
$$
\returnType{Type: Expression Integer}

%Original Page 45

Use {\tt \%plusInfinity} and {\tt \%minusInfinity} to
denote $\infty$ and $-\infty$.
\spadcommand{limit(h,x=\%plusInfinity)}
$$
e \sp k 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

A function can be defined on both sides of a particular value, but
may tend to different limits as its variable approaches that value from the
left and from the right.

\spadcommand{limit(sqrt(y**2)/y,y = 0)}
$$
\left[
{leftHandLimit=-1},  {rightHandLimit=1} 
\right]
$$
\returnType{Type: Union(Record(leftHandLimit: Union(OrderedCompletion Expression Integer,"failed"),rightHandLimit: Union(OrderedCompletion Expression Integer,"failed")),...)}

As $x$ approaches $0$ along the real axis, {\tt exp(-1/x**2)}
tends to $0$.

\spadcommand{limit(exp(-1/x**2),x = 0)}
$$
0 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

However, if $x$ is allowed to approach $0$ along any path in the
complex plane, the limiting value of {\tt exp(-1/x**2)} depends on the
path taken because the function has an essential singularity at $x=0$.
This is reflected in the error message returned by the function.
\spadcommand{complexLimit(exp(-1/x**2),x = 0)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

\section{Series}
\label{ugIntroSeries}

Axiom also provides power series.  \index{series!power} By default,
Axiom tries to compute and display the first ten elements of a series.
Use {\tt )set streams calculate} to change the default value to
something else.  For the purposes of this document, we have used this
system command to display fewer than ten terms.  For more information
about working with series, see \sectionref{ugProblemSeries}.

You can convert a functional expression to a power series by using the
operation {\bf series}.  In this example, {\tt sin(a*x)} is
expanded in powers of $(x - 0)$, that is, in powers of $x$.
\spadcommand{series(sin(a*x),x = 0)}
$$
{a \  x} -{{\frac{a \sp 3}{6}} \  {x \sp 3}}
+{{\frac{a \sp 5}{120}} \  {x \sp 5}} 
-{{\frac{a \sp 7}{5040}} \  {x \sp 7}}
+{{\frac{a \sp 9}{362880}} \  {x \sp 9}} 
-{{\frac{a \sp {11}}{39916800}} \  {x \sp {11}}}
+{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

%Original Page 46

This expression expands {\tt sin(a*x)} in powers of {\tt (x - \%pi/4)}.
\spadcommand{series(sin(a*x),x = \%pi/4)}
$$
{\sin 
\left({{\frac{a \  \pi}{4}}}\right)}+
{a \  {\cos \left({{\frac{a \  \pi}{4}}} \right)}
\  {\left( x -{\frac{\pi}{4}} \right)}}-
\hbox{\hskip 2.0cm}
$$
$$
{{\frac{{a \sp 2} \  {\sin \left({{\frac{a \  \pi}{4}}} \right)}}{2}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 2}} -
{{\frac{{a \sp 3} \  {\cos \left({{\frac{a \  \pi}{4}}} \right)}}{6}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 3}} +
$$
$$
{{\frac{{a \sp 4} \  {\sin \left({{\frac{a \  \pi}{4}}} \right)}}{24}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 4}} +
{{\frac{{a \sp 5} \  {\cos \left({{\frac{a \  \pi}{4}}} \right)}}{120}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 5}} -
$$
$$
{{\frac{{a \sp 6} \  {\sin \left({{\frac{a \  \pi}{4}}} \right)}}{720}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 6}} -
{{\frac{{a \sp 7} \  {\cos \left({{\frac{a \  \pi}{4}}} \right)}}{5040}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 7}} +
$$
$$
{{\frac{{a \sp 8} \  {\sin \left({{\frac{a \  \pi}{4}}} \right)}}{40320}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 8}} +
{{\frac{{a \sp 9} \  {\cos \left({{\frac{a \  \pi}{4}}} \right)}}{362880}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp 9}} -
$$
$$
{{\frac{{a \sp {10}} \  {\sin \left({{\frac{a \  \pi}{4}}} \right)}}{3628800}} 
\  {{\left( x -{\frac{\pi}{4}} \right)}\sp {10}}} +
{O \left({{{\left( x -{\frac{\pi}{4}} \right)}\sp {11}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,pi/4)}

Axiom provides \index{series!Puiseux} {\it Puiseux series:}
\index{Puiseux series} series with rational number exponents.  The
first argument to {\bf series} is an in-place function that
computes the $n$-th coefficient.  (Recall that the
``{\tt +->}'' is an infix operator meaning ``maps to.'')
\spadcommand{series(n +-> (-1)**((3*n - 4)/6)/factorial(n - 1/3),x=0,4/3..,2)}
%%NOTE: the paper book shows O(x^4) but Axiom computes O(x^5)
$$
{x \sp {\frac{4}{3}}} -{{\frac{1}{6}} \  {x \sp {\frac{10}{3}}}}
+{O \left({{x \sp 5}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

Once you have created a power series, you can perform arithmetic
operations on that series.  We compute the Taylor expansion of $1/(1-x)$.
\index{series!Taylor}
\spadcommand{f := series(1/(1-x),x = 0)}
$$
1+x+{x \sp 2}+{x \sp 3}+{x \sp 4}+{x \sp 5}+{x \sp 6}+{x \sp 7}+{x \sp 8}
+{x \sp 9}+{x \sp {10}}+{O \left({{x \sp {11}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

Compute the square of the series.
\spadcommand{f ** 2}
$$
1+{2 \  x}+{3 \  {x \sp 2}}+{4 \  {x \sp 3}}+{5 \  {x \sp 4}}+{6 \  {x \sp 
5}}+{7 \  {x \sp 6}}+{8 \  {x \sp 7}}+{9 \  {x \sp 8}}+{{10} \  {x \sp 
9}}+{{11} \  {x \sp {10}}}+{O 
\left(
{{x \sp {11}}} 
\right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

The usual elementary functions
({\bf log}, {\bf exp}, trigonometric functions, and so on)
are defined for power series.
\spadcommand{f := series(1/(1-x),x = 0)}
$$
1+x+{x \sp 2}+{x \sp 3}+{x \sp 4}+{x \sp 5}+{x \sp 6}+{x \sp 7}+{x \sp 8}+{x 
\sp 9}+{x \sp {10}}+{O 
\left(
{{x \sp {11}}} 
\right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\spadcommand{g := log(f)}
$$
\begin{array}{@{}l}
x+
{{\frac{1}{2}} \  {x \sp 2}}+
{{\frac{1}{3}} \  {x \sp 3}}+
{{\frac{1}{4}} \  {x \sp 4}}+
{{\frac{1}{5}} \  {x \sp 5}}+
{{\frac{1}{6}} \  {x \sp 6}}+
{{\frac{1}{7}} \  {x \sp 7}}+
\\
\\
\displaystyle
{{\frac{1}{8}} \  {x \sp 8}}+
{{\frac{1}{9}} \  {x \sp 9}}+
{{\frac{1}{10}} \  {x \sp {10}}}+
{{\frac{1}{11}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

%Original Page 47

\spadcommand{exp(g)}
$$
1+x+{x \sp 2}+{x \sp 3}+{x \sp 4}+{x \sp 5}+{x \sp 6}+{x \sp 7}+{x \sp 8}+{x 
\sp 9}+{x \sp {10}}+{O 
\left(
{{x \sp {11}}} 
\right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

% Warning: currently there are (interpreter) problems with converting
% rational functions and polynomials to power series.

Here is a way to obtain numerical approximations of
$e$ from the Taylor series expansion of {\bf exp}(x).
First create the desired Taylor expansion.
\spadcommand{f := taylor(exp(x))}
$$
1+x
+{{\frac{1}{2}} \  {x \sp 2}}
+{{\frac{1}{6}} \  {x \sp 3}}
+{{\frac{1}{24}} \ {x \sp 4}}
+{{\frac{1}{120}} \  {x \sp 5}}
+{{\frac{1}{720}} \  {x \sp 6}} +
\hbox{\hskip 1.0cm}
$$
$$
{{\frac{1}{5040}} \  {x \sp 7}} 
+{{\frac{1}{40320}} \  {x \sp 8}}
+{{\frac{1}{362880}} \  {x \sp 9}}
+{{\frac{1}{3628800}} \  {x \sp {10}}}
+{O \left({{x \sp {11}}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,x,0)}

Evaluate the series at the value $1.0$.
% Warning: syntax for evaluating power series may change.
As you see, you get a sequence of partial sums.
\spadcommand{eval(f,1.0)}
$$
\left[
{1.0},  {2.0},  {2.5},  {2.6666666666 666666667},  \hbox{\hskip 3.0cm}
\right.
$$
$${2.7083333333 333333333},  {2.7166666666 666666667},  \hbox{\hskip 1.0cm}
$$
$${2.7180555555 555555556},  {2.7182539682 53968254},  \hbox{\hskip 1.1cm}
$$
$$\left.
{2.7182787698 412698413},  {2.7182815255 731922399},  \ldots 
\hbox{\hskip 0.4cm}
\right]
$$
\returnType{Type: Stream Expression Float}

\section{Derivatives}
\label{ugIntroCalcDeriv}

Use the Axiom function {\bf D} to differentiate an
\index{derivative} expression.  \index{differentiation}

To find the derivative of an expression $f$ with respect to a
variable $x$, enter {\bf D}(f, x).

\spadcommand{f := exp exp x}
$$
e \sp {e \sp x} 
$$
\returnType{Type: Expression Integer}

\spadcommand{D(f, x)}
$$
{e \sp x} \  {e \sp {e \sp x}} 
$$
\returnType{Type: Expression Integer}

An optional third argument $n$ in {\bf D} asks Axiom for the $n$-th
derivative of $f$.  This finds the fourth derivative of $f$ with
respect to $x$.

\spadcommand{D(f, x, 4)}
$$
{\left( {{e \sp x} \sp 4}+{6 \  {{e \sp x} \sp 3}}+{7 \  {{e \sp x} \sp 
2}}+{e \sp x} 
\right)}
\  {e \sp {e \sp x}} 
$$
\returnType{Type: Expression Integer}

You can also compute partial derivatives by specifying the order of
\index{differentiation!partial}
differentiation.
\spadcommand{g := sin(x**2 + y)}
$$
\sin 
\left(
{{y+{x \sp 2}}} 
\right)
$$
\returnType{Type: Expression Integer}

%Original Page 48

\spadcommand{D(g, y)}
$$
\cos 
\left(
{{y+{x \sp 2}}} 
\right)
$$
\returnType{Type: Expression Integer}

\spadcommand{D(g, [y, y, x, x])}
$$
{4 \  {x \sp 2} \  {\sin 
\left(
{{y+{x \sp 2}}} 
\right)}}
-{2 \  {\cos 
\left(
{{y+{x \sp 2}}} 
\right)}}
$$
\returnType{Type: Expression Integer}

Axiom can manipulate the derivatives (partial and iterated) of
\index{differentiation!formal} expressions involving formal operators.
All the dependencies must be explicit.

This returns $0$ since F (so far) does not explicitly depend on $x$.

\spadcommand{D(F,x)}
$$
0 
$$
\returnType{Type: Polynomial Integer}

Suppose that we have F a function of $x$, $y$, and $z$,
where $x$ and $y$ are themselves functions of $z$.

Start by declaring that $F$, $x$, and $y$ are operators.
\index{operator}

\spadcommand{F := operator 'F; x := operator 'x; y := operator 'y}
$$
y 
$$
\returnType{Type: BasicOperator}

You can use F, $x$, and $y$ in expressions.

\spadcommand{a := F(x z, y z, z**2) + x y(z+1)}
$$
{x 
\left(
{{y 
\left(
{{z+1}} 
\right)}}
\right)}+{F
\left(
{{x 
\left(
{z} 
\right)},
 {y 
\left(
{z} 
\right)},
 {z \sp 2}} 
\right)}
$$
\returnType{Type: Expression Integer}

Differentiate formally with respect to $z$.
The formal derivatives appearing in $dadz$ are not just formal symbols,
but do represent the derivatives of $x$, $y$, and F.

\spadcommand{dadz := D(a, z)}
$$
\begin{array}{@{}l}
\displaystyle
{2 \  z \ {{F_{, 3}}\left({{x \left({z}\right)}, {y \left({z}\right)},
 {z^2}}\right)}}+{{{y_{\ }^{,}}\left({z}\right)}\ {{F_{, 2}}\left({{x 
\left({z}\right)}, {y \left({z}\right)}, {z^2}}\right)}}+
 
\\
\\
\displaystyle
{{{x_{\ }^{,}}\left({z}\right)}\ {{F_{, 1}}\left({{x \left({z}\right)},
 {y \left({z}\right)}, {z^2}}\right)}}+{{{x_{\ }^{,}}\left({y 
\left({z + 1}\right)}\right)}\ {{y_{\ }^{,}}\left({z + 1}\right)}}
\end{array}
$$
\returnType{Type: Expression Integer}

You can evaluate the above for particular functional values of
F, $x$, and $y$.  If $x(z)$ is {\bf exp}(z) and $y(z)$ is {\bf log}(z+1), 
then evaluates {\tt dadz}.

\spadcommand{eval(eval(dadz, 'x, z +-> exp z), 'y, z +-> log(z+1))}
$$
\frac{\left(
\begin{array}{@{}l}
\displaystyle
{{\left({2 \ {z^2}}+{2 \  z}\right)}\ {{F_{, 3}}\left({{e^z},
 {\log \left({z + 1}\right)}, {z^2}}\right)}}+
\\
\\
\displaystyle
{{F_{, 2}}\left({{e^
z}, {\log \left({z + 1}\right)}, {z^2}}\right)}+ 
\\
\\
\displaystyle
{{\left(z + 1 \right)}\ {e^z}\ {{F_{, 1}}\left({{e^z}, {\log 
\left({z + 1}\right)}, {z^2}}\right)}}+ z + 1 
\end{array}
\right)}{z + 1}
$$
\returnType{Type: Expression Integer}

%Original Page 49

You obtain the same result by first evaluating $a$ and
then differentiating.

\spadcommand{eval(eval(a, 'x, z +-> exp z), 'y, z +-> log(z+1))}
$$
{F 
\left(
{{e \sp z},  {\log 
\left(
{{z+1}} 
\right)},
 {z \sp 2}} 
\right)}+z+2
$$
\returnType{Type: Expression Integer}

\spadcommand{D(\%, z)}
$$
\frac{\left(
\begin{array}{@{}l}
\displaystyle
{{\left({2 \ {z^2}}+{2 \  z}\right)}\ {{F_{, 3}}\left({{e^
z}, {\log \left({z + 1}\right)}, {z^2}}\right)}}+
\\
\\
\displaystyle
{{F_{, 2}}\left({{e^z}, {\log \left({z + 1}\right)}, {z^2}}\right)}+
\\
\\
\displaystyle
{{\left(z 
+ 1 \right)}\ {e^z}\ {{F_{, 1}}\left({{e^z}, {\log \left({z 
+ 1}\right)}, {z^2}}\right)}}+ z + 1
\end{array}
\right)}{z + 1}
$$
\returnType{Type: Expression Integer}

\section{Integration}
\label{ugIntroIntegrate}

Axiom has extensive library facilities for integration.
\index{integration}

The first example is the integration of a fraction with denominator
that factors into a quadratic and a quartic irreducible polynomial.
The usual partial fraction approach used by most other computer
algebra systems either fails or introduces expensive unneeded
algebraic numbers.

We use a factorization-free algorithm.
\spadcommand{integrate((x**2+2*x+1)/((x+1)**6+1),x)}
$$
\frac{\arctan \left({{{x \sp 3}+{3 \  {x \sp 2}}+{3 \  x}+1}} \right)}{3} 
$$
\returnType{Type: Union(Expression Integer,...)}

When real parameters are present, the form of the integral can depend on
the signs of some expressions.

Rather than query the user or make sign assumptions, Axiom returns
all possible answers.
\spadcommand{integrate(1/(x**2 + a),x)}
$$
\left[
{\frac{\log 
\left({{
\frac{{{\left( {x \sp 2} -a \right)}\  {\sqrt {-a}}}+{2 \  a \  x}}
{{x \sp 2}+a}}} \right)}{2 \  {\sqrt {-a}}}},  
{\frac{\arctan \left({{\frac{x \  {\sqrt {a}}}{a}}} \right)}{\sqrt {a}}} 
\right]
$$
\returnType{Type: Union(List Expression Integer,...)}

The {\bf integrate} operation generally assumes that all
parameters are real.  The only exception is when the integrand has
complex valued quantities.

If the parameter is complex instead of real, then the notion of sign
is undefined and there is a unique answer.  You can request this
answer by ``prepending'' the word ``complex'' to the command name:

\spadcommand{complexIntegrate(1/(x**2 + a),x)}
%%NOTE: the expression in the book is different but they differentiate
%%to exactly the same answer.
$$
\frac{{\log 
\left(
{{\frac{{x \  {\sqrt {-a}}}+a}{\sqrt {-a}}}} 
\right)}
-{\log \left({{\frac{{x \  {\sqrt {-a}}} -a}{\sqrt {-a}}}} \right)}}
{2 \  {\sqrt {-a}}} 
$$
\returnType{Type: Expression Integer}

%Original Page 50

The following two examples illustrate the limitations of table-based
approaches.  The two integrands are very similar, but the answer to
one of them requires the addition of two new algebraic numbers.

This one is the easy one.
The next one looks very similar
but the answer is much more complicated.
\spadcommand{integrate(x**3 / (a+b*x)**(1/3),x)}
$$
\frac{{\left( {{120} \  {b \sp 3} \  {x \sp 3}} 
-{{135} \  a \  {b \sp 2} \  {x \sp 2}}
+{{162} \  {a \sp 2} \  b \  x} -{{243} \  {a \sp 3}} \right)}
\  {{\root {3} \of {{{b \  x}+a}}} \sp 2}}{{440} \  {b \sp 4}} 
$$
\returnType{Type: Union(Expression Integer,...)}

Only an algorithmic approach is guaranteed to find what new constants
must be added in order to find a solution.

\spadcommand{integrate(1 / (x**3 * (a+b*x)**(1/3)),x)}
$$
\frac{\left(
\begin{array}{@{}l}
-{2 \  {b \sp 2} \  {x \sp 2} \  {\sqrt {3}} \  {\log 
\left(
{{{{\root {3} \of {a}} \  {{\root {3} \of {{{b \  x}+a}}} \sp 2}}
+{{{\root {3} \of {a}} \sp 2} \  {\root {3} \of {{{b \  x}+a}}}}+a}} 
\right)}}+
\\
\\
\displaystyle
{4\  {b \sp 2} \  {x \sp 2} \  {\sqrt {3}} \  {\log 
\left(
{{{{{\root {3} \of {a}} \sp 2} \  {\root {3} \of {{{b \  x}+a}}}} -a}} 
\right)}}+
\\
\\
\displaystyle
{{12}\  {b \sp 2} \  {x \sp 2} \  {\arctan 
\left(
{{\frac{{2 \  {\sqrt {3}} \  {{\root {3} \of {a}} \sp 2} \  
{\root {3} \of {{{b \  x}+a}}}}
+{a \  {\sqrt {3}}}}{3 \  a}}} 
\right)}}+
\\
\\
\displaystyle
{{\left(
{{12} \  b \  x} -{9 \  a} 
\right)}
\  {\sqrt {3}} \  {\root {3} \of {a}} \  {{\root {3} \of {{{b \  x}+a}}} \sp 
2}}
\end{array}
\right)}{{18} \  {a \sp 2} \  {x \sp 2} \  {\sqrt {3}} \  {\root {3} \of {a}}} 
$$
\returnType{Type: Union(Expression Integer,...)}

Some computer algebra systems use heuristics or table-driven
approaches to integration.  When these systems cannot determine the
answer to an integration problem, they reply ``I don't know.''  Axiom
uses an algorithm which is a {\sl decision procedure} for integration.
If Axiom returns the original integral that conclusively proves that
an integral cannot be expressed in terms of elementary functions.

When Axiom returns an integral sign, it has proved that no answer
exists as an elementary function.

\spadcommand{integrate(log(1 + sqrt(a*x + b)) / x,x)}
$$
\int \sp{\displaystyle x} {{\frac{\log 
\left({{{\sqrt {{b+{ \%Q \  a}}}}+1}} \right)}{\%Q}} \  {d \%Q}} 
$$
\returnType{Type: Union(Expression Integer,...)}

Axiom can handle complicated mixed functions much beyond what you
can find in tables.

Whenever possible, Axiom tries to express the answer using the
functions present in the integrand.

\spadcommand{integrate((sinh(1+sqrt(x+b))+2*sqrt(x+b)) / (sqrt(x+b) * (x + cosh(1+sqrt(x + b)))), x)}
%%NOTE: the book has the same answer with a trailing ``+4'' term.
%%This term is not generated by Axiom
$$
{2 \  {\log 
\left(
{{\frac{-{2 \  {\cosh \left({{{\sqrt {{x+b}}}+1}} \right)}}-{2 \  x}}
{{\sinh\left({{{\sqrt {{x+b}}}+1}} \right)}
-{\cosh \left({{{\sqrt {{x+b}}}+1}} \right)}}}}
\right)}}
-{2 \  {\sqrt {{x+b}}}} 
$$
\returnType{Type: Union(Expression Integer,...)}

%Original Page 51

A strong structure-checking algorithm in Axiom finds hidden algebraic
relationships between functions.

\spadcommand{integrate(tan(atan(x)/3),x)}
%%NOTE: the book has a trailing ``+16'' term in the numerator
%%This is not generated by Axiom
$$
\frac{\left(
\begin{array}{@{}l}
{8 \  {\log \left({{{3 \  {{\tan \left({{
\frac{\arctan \left({x} \right)}{3}}} \right)}
\sp 2}} -1}} 
\right)}}
-{3 \  {{\tan \left({{\frac{\arctan \left({x} \right)}{3}}} \right)} \sp 2}}+
\\
\\
\displaystyle
{{18} \  x \  {\tan \left({{\frac{\arctan \left({x} \right)}{3}}} \right)}}
\end{array}
\right)}{18} 
$$
\returnType{Type: Union(Expression Integer,...)}

The discovery of this algebraic relationship is necessary for correct
integration of this function.
Here are the details:
\begin{enumerate}
\item
If $x=\tan t$ and $g=\tan (t/3)$ then the following 
algebraic relation is true: $${g^3-3xg^2-3g+x=0}$$
\item
Integrate $g$ using this algebraic relation; this produces:
$${\frac{(24g^2 - 8)\log(3g^2 - 1) + (81x^2 + 24)g^2 + 72xg - 27x^2 - 16}
{54g^2 - 18}}$$
\item
Rationalize the denominator, producing:
$$\frac{8\log(3g^2-1) - 3g^2 + 18xg + 16}{18}$$
Replace $g$ by the initial definition
$g = \tan(\arctan(x)/3)$
to produce the final result.
\end{enumerate}

This is an example of a mixed function where
the algebraic layer is over the transcendental one.
\spadcommand{integrate((x + 1) / (x*(x + log x) ** (3/2)), x)}
$$
-{\frac{2 \  {\sqrt {{{\log \left({x} \right)}+x}}}}
{{\log \left({x} \right)}+x}}
$$
\returnType{Type: Union(Expression Integer,...)}

While incomplete for non-elementary functions, Axiom can
handle some of them.
\spadcommand{integrate(exp(-x**2) * erf(x) / (erf(x)**3 - erf(x)**2 - erf(x) + 1),x)}
$$
\frac{{{\left( {\erf \left({x} \right)}-1 \right)}\  {\sqrt {\pi}} \  {\log 
\left({{\frac{{\erf \left({x} \right)}-1}
{{\erf \left({x} \right)}+1}}}\right)}}
-{2 \  {\sqrt {\pi}}}}{{8 \  {\erf \left({x} \right)}}-8} 
$$
\returnType{Type: Union(Expression Integer,...)}

More examples of Axiom's integration capabilities are discussed in
\sectionref{ugProblemIntegration}.

%Original Page 52

\section{Differential Equations}
\label{ugIntroDiffEqns}
The general approach used in integration also carries over to the
solution of linear differential equations.

Let's solve some differential equations.
Let $y$ be the unknown function in terms of $x$.
\spadcommand{y := operator 'y}
$$
y 
$$
\returnType{Type: BasicOperator}

Here we solve a third order equation with polynomial coefficients.
\spadcommand{deq := x**3 * D(y x, x, 3) + x**2 * D(y x, x, 2) - 2 * x * D(y x, x) + 2 * y x = 2 * x**4}
$$
{{{x \sp 3} \  {{y \sb {{\ }} \sp {,,,}} 
\left(
{x} 
\right)}}+{{x
\sp 2} \  {{y \sb {{\ }} \sp {,,}} 
\left(
{x} 
\right)}}
-{2 \  x \  {{y \sb {{\ }} \sp {,}} 
\left(
{x} 
\right)}}+{2
\  {y 
\left(
{x} 
\right)}}}={2
\  {x \sp 4}} 
$$
\returnType{Type: Equation Expression Integer}

\spadcommand{solve(deq, y, x)}
%%NOTE: the book has a different solution and it appears to be 
%%less complicated than this one.
$$
\begin{array}{@{}l}
\left[
{particular={\frac{{x \sp 5} -{{10} \  {x \sp 3}}+{{20} \  {x \sp 2}}+4} 
{{15} \  x}}}, 
\right.
\\
\\
\displaystyle
\left.
{basis={\left[ {\frac{{2 \  {x \sp 3}} -{3 \  {x \sp 2}}+1}{x}},  
{\frac{{x \sp 3} -1}{x}},  
{\frac{{x \sp 3} -{3 \  {x \sp 2}} -1}{x}}
\right]}}
\right]
\end{array}
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: List Expression Integer),...)}


Here we find all the algebraic function solutions of the equation.
\spadcommand{deq := (x**2 + 1) * D(y x, x, 2) + 3 * x * D(y x, x) + y x = 0}
$$
{{{\left( {x \sp 2}+1 \right)}\  {{y \sb {{\ }} \sp {,,}} 
\left({x} \right)}}+{3\  x \  {{y \sb {{\ }} \sp {,}} 
\left({x} \right)}}+{y\left({x} \right)}}=0
$$
\returnType{Type: Equation Expression Integer}

\spadcommand{solve(deq, y, x)}
$$
\left[
{particular=0},  
{basis={\left[ {\frac{1}{\sqrt {{{x \sp 2}+1}}}},  
{\frac{\log \left({{{\sqrt {{{x \sp 2}+1}}} -x}} \right)}
{\sqrt {{{x \sp 2}+1}}}} 
\right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: List Expression Integer),...)}

Coefficients of differential equations can come from arbitrary
constant fields.  For example, coefficients can contain algebraic
numbers.

This example has solutions whose logarithmic derivative is an
algebraic function of degree two.

\spadcommand{eq := 2*x**3 * D(y x,x,2) + 3*x**2 * D(y x,x) - 2 * y x}
$$
{2 \  {x \sp 3} \  {{y \sb {{\ }} \sp {,,}} 
\left({x} \right)}}+{3\  {x \sp 2} \  {{y \sb {{\ }} \sp {,}} 
\left({x} \right)}}-{2 \  {y \left({x} \right)}}
$$
\returnType{Type: Expression Integer}

\spadcommand{solve(eq,y,x).basis}
$$
\left[
{e \sp {\left( -{\frac{2}{\sqrt {x}}} \right)}},
{e \sp {\frac{2}{\sqrt {x}}}} 
\right]
$$
\returnType{Type: List Expression Integer}

%Original Page 53

Here's another differential equation to solve.
\spadcommand{deq := D(y x, x) = y(x) / (x + y(x) * log y x)}
$$
{{y \sb {{\ }} \sp {,}} 
\left({x} \right)}
={\frac{y\left({x} \right)}
{{{y \left({x} \right)}\  {\log \left({{y \left({x} \right)}}\right)}}+x}}
$$
\returnType{Type: Equation Expression Integer}

\spadcommand{solve(deq, y, x)}
$$
\frac{{{y \left({x} \right)}\  {
{\log \left({{y \left({x} \right)}}\right)}\sp 2}} -{2 \  x}}
{2 \  {y \left({x} \right)}}
$$
\returnType{Type: Union(Expression Integer,...)}

Rather than attempting to get a closed form solution of
a differential equation, you instead might want to find an
approximate solution in the form of a series.

Let's solve a system of nonlinear first order equations and get a
solution in power series.  Tell Axiom that $x$ is also an
operator.

\spadcommand{x := operator 'x}
$$
x 
$$
\returnType{Type: BasicOperator}

Here are the two equations forming our system.
\spadcommand{eq1 := D(x(t), t) = 1 + x(t)**2}
$$
{{x \sb {{\ }} \sp {,}} 
\left(
{t} 
\right)}={{{x
\left(
{t} 
\right)}
\sp 2}+1} 
$$
\returnType{Type: Equation Expression Integer}

\spadcommand{eq2 := D(y(t), t) = x(t) * y(t)}
$$
{{y \sb {{\ }} \sp {,}} 
\left(
{t} 
\right)}={{x
\left(
{t} 
\right)}
\  {y 
\left(
{t} 
\right)}}
$$
\returnType{Type: Equation Expression Integer}

We can solve the system around $t = 0$ with the initial
conditions $x(0) = 0$ and $y(0) = 1$.  Notice that since
we give the unknowns in the order $[x, y]$, the answer is a list
of two series in the order 
$[{\rm series\ for\ }x(t), {\rm series\ for\ }y(t)]$.

\spadcommand{seriesSolve([eq2, eq1], [x, y], t = 0, [y(0) = 1, x(0) = 0])}
$$
\left[
{\ t+
{{\frac{1}{3}} \  {t \sp 3}}+
{{\frac{2}{15}} \  {t \sp 5}}+
{{\frac{17}{315}} \  {t \sp 7}}+
{{\frac{62}{2835}} \  {t \sp 9}}+
{O \left({{t \sp {11}}} \right)}},
\right. 
\hbox{\hskip 2.0cm}
$$
$$
\hbox{\hskip 0.4cm}
\left.
{1+
{{\frac{1}{2}} \  {t \sp 2}}+
{{\frac{5}{24}} \  {t \sp 4}}+
{{\frac{61}{720}} \  {t \sp 6}}+
{{\frac{277}{8064}} \  {t \sp 8}}+
{{\frac{50521}{3628800}} \  {t \sp {10}}}+
{O \left({{t \sp {11}}}\right)}}
\right]
$$
\returnType{Type: List UnivariateTaylorSeries(Expression Integer,t,0)}

\section{Solution of Equations}
\label{ugIntroSolution}
Axiom also has state-of-the-art algorithms for the solution of
systems of polynomial equations.  When the number of equations and
unknowns is the same, and you have no symbolic coefficients, you can
use {\bf solve} for real roots and {\bf complexSolve} for
complex roots.  In each case, you tell Axiom how accurate you
want your result to be.  All operations in the {\it solve} family
return answers in the form of a list of solution sets, where each
solution set is a list of equations.

%Original Page 54

A system of two equations involving a symbolic parameter $t$.
\spadcommand{S(t) == [x**2-2*y**2 - t,x*y-y-5*x + 5]}
\returnType{Type: Void}

Find the real roots of $S(19)$ with
rational arithmetic, correct to within $1/10^{20}$.
\spadcommand{solve(S(19),1/10**20)}
$$
\left[
{\left[ {y=5},  {x=-{\frac{2451682632253093442511}{295147905179352825856}}} 
\right]},
\right.
$$
$$
\left.
{\left[ {y=5},  {x={\frac{2451682632253093442511}{295147905179352825856}}} 
\right]}
\right]
$$
\returnType{Type: List List Equation Polynomial Fraction Integer}

Find the complex roots of $S(19)$ with floating
point coefficients to $20$ digits accuracy in the mantissa.

\spadcommand{complexSolve(S(19),10.e-20)}
$$
\left[
{\left[ {y={5.0}},  {x={8.3066238629 180748526}} \right]},
\right.
$$
$$
{\left[ {y={5.0}},  {x=-{8.3066238629 180748526}} \right]},
$$
$$
\left.
{\left[ {y=-{{3.0} \  i}},  {x={1.0}} \right]},
{\left[ {y={{3.0} \  i}},  {x={1.0}} \right]}
\right]
$$
\returnType{Type: List List Equation Polynomial Complex Float}

If a system of equations has symbolic coefficients and you want
a solution in radicals, try {\bf radicalSolve}.
\spadcommand{radicalSolve(S(a),[x,y])}
$$
\left[
{\left[ {x=-{\sqrt {{a+{50}}}}}, {y=5} \right]},
{\left[ {x={\sqrt {{a+{50}}}}}, {y=5} \right]},
\right.
$$
$$
\hbox{\hskip 0.7cm}
\left.
{\left[ {x=1}, {y={\sqrt {{\frac{-a+1}{2}}}}} \right]},
{\left[ {x=1}, {y=-{\sqrt {{\frac{-a+1}{2}}}}} \right]}
\right]
$$
\returnType{Type: List List Equation Expression Integer}

For systems of equations with symbolic coefficients, you can apply
{\bf solve}, listing the variables that you want Axiom to
solve for.  For polynomial equations, a solution cannot usually be
expressed solely in terms of the other variables.  Instead, the
solution is presented as a ``triangular'' system of equations, where
each polynomial has coefficients involving only the succeeding
variables. This is analogous to converting a linear system of
equations to ``triangular form''.

A system of three equations in five variables.
\spadcommand{eqns := [x**2 - y + z,x**2*z + x**4 - b*y, y**2 *z - a - b*x]}
$$
\left[
{z -y+{x \sp 2}},  {{{x \sp 2} \  z} -{b \  y}+{x \sp 4}},  {{{y \sp 2} \  
z} -{b \  x} -a} 
\right]
$$
\returnType{Type: List Polynomial Integer}

%Original Page 55

Solve the system for unknowns $[x,y,z]$,
reducing the solution to triangular form.
\spadcommand{solve(eqns,[x,y,z])}
$$
\left[
{\left[ {x=-{\frac{a}{b}}},  {y=0},  {z=-{\frac{a \sp 2}{b \sp 2}}} 
\right]},
\right.
\hbox{\hskip 10.0cm}
$$
$$
\left.
\begin{array}{@{}l}
\displaystyle
\left[
{x={\frac{{z \sp 3}+{2 \  b \  {z \sp 2}}+{{b \sp 2} \  z} -a}{b}}}, 
{y={z+b}}, 
\right.
\hbox{\hskip 7.2cm}
\\
\\
\displaystyle
{z \sp 6}+{4 \  b \  {z \sp 5}}+
{6 \  {b \sp 2} \  {z \sp 4}}+
{{\left( {4 \  {b \sp 3}} -{2 \  a} \right)}\  {z \sp 3}}+
{{\left( {b \sp 4} -{4 \  a \  b} \right)}\  {z \sp 2}}-
\left.
{2 \  a \  {b \sp 2} \  z} -{b \sp 3}+{a \sp 2}=0
\right]
\end{array}
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

\section{System Commands}
\label{ugIntroSysCmmands}
We conclude our tour of Axiom with a brief discussion of
{\it system commands}.  System commands are special statements
that start with a closing parenthesis ({\tt )}). They are used
to control or display your Axiom environment, start the
HyperDoc system, issue operating system commands and leave
Axiom.  For example, {\tt )system} is used to issue commands
to the operating system from Axiom.  Here
is a brief description of some of these commands.  For more
information on specific commands, see Appendix A 
on page~\pageref{ugSysCmd}.

Perhaps the most important user command is the {\tt )clear all}
command that initializes your environment.  Every section and
subsection in this document has an invisible {\tt )clear all} that is
read prior to the examples given in the section.  {\tt )clear all}
gives you a fresh, empty environment with no user variables defined
and the step number reset to $1$.  The {\tt )clear} command
can also be used to selectively clear values and properties of system
variables.

Another useful system command is {\tt )read}.  A preferred way to
develop an application in Axiom is to put your interactive
commands into a file, say {\bf my.input} file.  To get Axiom to
read this file, you use the system command {\tt )read my.input}.
If you need to make changes to your approach or definitions, go into
your favorite editor, change {\bf my.input}, then {\tt )read
my.input} again.

Other system commands include: {\tt )history}, to display
previous input and/or output lines; {\tt )display}, to display
properties and values of workspace variables; and {\tt )what}.

%Original Page 56

Issue {\tt )what} to get a list of Axiom objects that
contain a given substring in their name.
\spadcommand{)what operations integrate}
\begin{verbatim}

Operations whose names satisfy the above pattern(s):

HermiteIntegrate       algintegrate           complexIntegrate       
expintegrate           extendedIntegrate      fintegrate             
infieldIntegrate       integrate              internalIntegrate      
internalIntegrate0     lazyGintegrate         lazyIntegrate          
lfintegrate            limitedIntegrate       monomialIntegrate      
nagPolygonIntegrate    palgintegrate          pmComplexintegrate     
pmintegrate            primintegrate          tanintegrate           
   
To get more information about an operation such as 
limitedIntegrate , issue the command )display op limitedIntegrate
      
\end{verbatim}

\subsection{Undo}
\label{ugIntroUndo}
A useful system command is {\tt )undo}.  Sometimes while computing
interactively with Axiom, you make a mistake and enter an
incorrect definition or assignment.  Or perhaps you need to try one of
several alternative approaches, one after another, to find the best
way to approach an application.  For this, you will find the
{\it undo} facility of Axiom helpful.

System command {\tt )undo n} means ``undo back to step
$n$''; it restores the values of user variables to those that
existed immediately after input expression $n$ was evaluated.
Similarly, {\tt )undo -n} undoes changes caused by the last
$n$ input expressions.  Once you have done an {\tt )undo},
you can continue on from there, or make a change and {\bf redo} all
your input expressions from the point of the {\tt )undo} forward.
The {\tt )undo} is completely general: it changes the environment
like any user expression.  Thus you can {\tt )undo} any previous
undo.

Here is a sample dialogue between user and Axiom.

``Let me define
two mutually dependent functions $f$ and $g$ piece-wise.''
\spadcommand{f(0) == 1; g(0) == 1}
\returnType{Type: Void}

``Here is the general term for $f$.''
\spadcommand{f(n) == e/2*f(n-1) - x*g(n-1)}
\returnType{Type: Void}

``And here is the general term for $g$.''
\spadcommand{g(n) == -x*f(n-1) + d/3*g(n-1)}
\returnType{Type: Void}

%Original Page 57

``What is the value of $f(3)$?''
\spadcommand{f(3)}
$$
-{x \sp 3}+{{\left( e+{{\frac{1}{3}} \  d} \right)}
\  {x \sp 2}}
+{{\left( 
-{{\frac{1}{4}} \  {e \sp 2}} 
-{{\frac{1}{6}} \  d \  e} 
-{{\frac{1}{9}} \  {d \sp 2}} 
\right)}\  x}
+{{\frac{1}{8}} \  {e \sp 3}} 
$$
\returnType{Type: Polynomial Fraction Integer}

``Hmm, I think I want to define $f$ differently.
Undo to the environment right after I defined $f$.''
\spadcommand{)undo 2}

``Here is how I think I want $f$ to be defined instead.''
\spadcommand{f(n) == d/3*f(n-1) - x*g(n-1)}
\begin{verbatim}
   1 old definition(s) deleted for function or rule f 
\end{verbatim}
\returnType{Type: Void}

Redo the computation from expression $3$ forward.
\spadcommand{)undo )redo}
\begin{verbatim}
g(n) == -x*f(n-1) + d/3*g(n-1)
 
                                                          Type: Void
f(3)
 
   Compiling function g with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function g as a recurrence relation.

+++ |*1;g;1;G82322;AUX| redefined

+++ |*1;g;1;G82322| redefined
   Compiling function g with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function g as a recurrence relation.

+++ |*1;g;1;G82322;AUX| redefined

+++ |*1;g;1;G82322| redefined
   Compiling function f with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function f as a recurrence relation.

+++ |*1;f;1;G82322;AUX| redefined

+++ |*1;f;1;G82322| redefined
\end{verbatim}
$$
-{x \sp 3}+{d \  {x \sp 2}} 
-{{\frac{1}{3}} \  {d \sp 2} \  x}
+{{\frac{1}{27}} \  {d \sp 3}} 
$$
\returnType{Type: Polynomial Fraction Integer}

``I want my old definition of
$f$ after all. Undo the undo and restore
the environment to that immediately after $(4)$.''
\spadcommand{)undo 4}

``Check that the value of $f(3)$ is restored.''
\spadcommand{f(3)}
\begin{verbatim}
   Compiling function g with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function g as a recurrence relation.

+++ |*1;g;1;G82322;AUX| redefined

+++ |*1;g;1;G82322| redefined
   Compiling function g with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function g as a recurrence relation.

+++ |*1;g;1;G82322;AUX| redefined

+++ |*1;g;1;G82322| redefined
   Compiling function f with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function f as a recurrence relation.

+++ |*1;f;1;G82322;AUX| redefined

+++ |*1;f;1;G82322| redefined
\end{verbatim}
$$
-{x \sp 3}+{{\left( e+{{\frac{1}{3}} \  d} \right)}\  {x \sp 2}}
+{{\left( 
-{{\frac{1}{4}} \  {e \sp 2}} 
-{{\frac{1}{6}} \  d \  e} 
-{{\frac{1}{9}} \  {d \sp 2}} 
\right)}\  x}
+{{\frac{1}{8}} \  {e \sp 3}} 
$$
\returnType{Type: Polynomial Fraction Integer}

After you have gone off on several tangents, then backtracked to
previous points in your conversation using {\tt )undo}, you might
want to save all the ``correct'' input commands you issued,
disregarding those undone.  The system command {\tt )history
)write mynew.input} writes a clean straight-line program onto the file
{\bf mynew.input} on your disk.

%Original Page 28

\section{Graphics}
\label{ugIntroGraphics}
Axiom has a two- and three-dimensional drawing and rendering
\index{graphics} package that allows you to draw, shade, color,
rotate, translate, map, clip, scale and combine graphic output of
Axiom computations.  The graphics interface is capable of
plotting functions of one or more variables and plotting parametric
surfaces.  Once the graphics figure appears in a window, move your
mouse to the window and click.  A control panel appears immediately
and allows you to interactively transform the object.

This is an example of Axiom's two-dimensional plotting.
From the 2D Control Panel you can rescale the plot, turn axes and units
on and off and save the image, among other things.
This PostScript image was produced by clicking on the
{\bf PS} 2D Control Panel button.
\spadgraph{draw(cos(5*t/8), t=0..16*\%pi, coordinates==polar)}
% window was 256 x 256
%\epsffile[72 72 300 300]{ps/rose-1.ps}
\begin{figure}[htbp]
\includegraphics[bbllx=14, bblly=14, bburx=176, bbury=186]{ps/p28a.eps}
\caption{$J_0(\sqrt{x^2+y^2})$ for $-20 \leq x,y \leq 20$}
\label{tpdhere}
\end{figure}

This is an example of Axiom's three-dimensional plotting.
It is a monochrome graph of the complex arctangent
function.
The image displayed was rotated and had the ``shade'' and ``outline''
display options set from the 3D Control Panel.
The PostScript output was produced by clicking on the
{\bf save} 3D Control Panel button and then
clicking on the {\bf PS} button.
See \sectionref{ugProblemNumeric}
for more details and examples of Axiom's numeric and graphics capabilities.

\spadgraph{draw((x,y) +-> real atan complex(x,y), -\%pi..\%pi, -\%pi..\%pi, colorFunction == (x,y) +-> argument atan complex(x,y))}
% window was 256 x 256
%\epsffile[72 72 285 285]{ps/atan-1.ps}
\begin{figure}[htbp]
\includegraphics[bbllx=14, bblly=14, bburx=175, bbury=185]{ps/p28b.eps}
\caption{atan}
\label{tpdhere1}
\end{figure}

An exhibit of Axiom images is given later.  For a description of the
commands and programs that produced these figures, see
\sectionref{ugAppGraphics}.  PostScript
\index{PostScript} output is available so that Axiom images can be
printed.\footnote{PostScript is a trademark of Adobe Systems
Incorporated, registered in the United States.}  See \sectionref{ugGraph}
for more examples and details about using
Axiom's graphics facilities.

This concludes your tour of Axiom.
To disembark, issue the system command {\tt )quit} to leave Axiom
and return to the operating system.

%\setcounter{chapter}{1}

\chapter{Using Types and Modes}
\begin{quote}
Only recently have I begun to realize that the problem is not merely
one of technical mastery or the competent application of the rules 
\ldots
but that there is actually something else which is guiding these
rules. It actually involves a different level of mastery. It's quite
a different process to do it right; and every single act that you 
do can be done in that sense well or badly. But even assuming that 
you have got the technical part clear, the creation of this quality
is a much more complicated process of the most utterly absorbing and
fascinating dimensions. It is in fact a major creative or artistic 
act -- every single little thing you do -- \ldots

-- Christopher Alexander

(from Patterns of Software by Richard Gabriel)

\end{quote}
\label{ugTypes}

%Original Page 59

In this chapter we look at the key notion of {\it type} and its
generalization {\it mode}.  We show that every Axiom object has a type
that determines what you can do with the object.  In particular, we
explain how to use types to call specific functions from particular
parts of the library and how types and modes can be used to create new
objects from old.  We also look at {\tt Record} and {\tt Union} types
and the special type {\tt Any}.  Finally, we give you an idea of how
Axiom manipulates types and modes internally to resolve ambiguities.

\section{The Basic Idea}
\label{ugTypesBasic}

The Axiom world deals with many kinds of objects.  There are
mathematical objects such as numbers and polynomials, data structure
objects such as lists and arrays, and graphics objects such as points
and graphic images.  Functions are objects too.

Axiom organizes objects using the notion of domain of computation, or
simply {\it domain}.  Each domain denotes a class of objects.  The
class of objects it denotes is usually given by the name of the
domain: {\tt Integer} for the integers, {\tt Float} for floating-point
numbers, and so on.  The convention is that the first letter of a
domain name is capitalized.  Similarly, the domain 
{\tt Polynomial(Integer)} denotes ``polynomials with integer
coefficients.''  Also, {\tt Matrix(Float)} denotes ``matrices with
floating-point entries.''

Every basic Axiom object belongs to a unique domain.  The integer $3$
belongs to the domain {\tt Integer} and the polynomial $x + 3$ belongs
to the domain {\tt Polynomial(Integer)}.  The domain of an object is
also called its {\it type}.  Thus we speak of ``the type 
{\tt Integer}'' and ``the type {\tt Polynomial(Integer)}.''

%Original Page 60

After an Axiom computation, the type is displayed toward the
right-hand side of the page (or screen).
\spadcommand{-3}
$$
-3 
$$
\returnType{Type: Integer}

Here we create a rational number but it looks like the last result.
The type however tells you it is different.  You cannot identify the
type of an object by how Axiom displays the object.
\spadcommand{-3/1}
$$
-3 
$$
\returnType{Type: Fraction Integer}

When a computation produces a result of a simpler type, Axiom leaves
the type unsimplified.  Thus no information is lost.
\spadcommand{x + 3 - x}
$$
3 
$$
\returnType{Type: Polynomial Integer}

This seldom matters since Axiom retracts the answer to the
simpler type if it is necessary.
\spadcommand{factorial(\%)}
$$
6 
$$
\returnType{Type: Expression Integer}

When you issue a positive number, the type {\tt PositiveInteger} is
printed.  Surely, $3$ also has type {\tt Integer}!  The curious reader
may now have two questions.  First, is the type of an object not
unique?  Second, how is {\tt PositiveInteger} related to {\tt
Integer}?
\spadcommand{3}
$$
3 
$$
\returnType{Type: PositiveInteger}

Any domain can be refined to a {\it subdomain} by a membership 
{\tt predicate}. A {\tt predicate} is a function that, when applied to an
object of the domain, returns either {\tt true} or {\tt false}.  For
example, the domain {\tt Integer} can be refined to the subdomain 
{\tt PositiveInteger}, the set of integers $x$ such that $x > 0$, by giving
the Axiom predicate {\tt x +-> x > 0}.  Similarly, Axiom can define
subdomains such as ``the subdomain of diagonal matrices,'' ``the
subdomain of lists of length two,'' ``the subdomain of monic
irreducible polynomials in $x$,'' and so on.  Trivially, any domain is
a subdomain of itself.

While an object belongs to a unique domain, it can belong to any
number of subdomains.  Any subdomain of the domain of an object can be
used as the {\it type} of that object.  The type of $3$ is indeed both
{\tt Integer} and {\tt PositiveInteger} as well as any other subdomain
of integer whose predicate is satisfied, such as ``the prime
integers,'' ``the odd positive integers between 3 and 17,'' and so on.

%Original Page 61

\subsection{Domain Constructors}
\label{ugTypesBasicDomainCons}

In Axiom, domains are objects.  You can create them, pass them to
functions, and, as we'll see later, test them for certain properties.

In Axiom, you ask for a value of a function by applying its name
to a set of arguments.

To ask for ``the factorial of $7$'' you enter this expression to
Axiom.  This applies the function {\tt factorial} to the value $7$ to
compute the result.
\spadcommand{factorial(7)}
$$
5040 
$$
\returnType{Type: PositiveInteger}

Enter the type {\tt Polynomial (Integer)} as an expression to Axiom.
This looks much like a function call as well.  It is!  The result is
appropriately stated to be of type {\tt Domain}, which according to
our usual convention, denotes the class of all domains.
\spadcommand{Polynomial(Integer)}
$$
\mbox{\rm Polynomial Integer} 
$$
\returnType{Type: Domain}

The most basic operation involving domains is that of building a new
domain from a given one.  To create the domain of ``polynomials over
the integers,'' Axiom applies the function {\tt Polynomial} to the
domain {\tt Integer}.  A function like {\tt Polynomial} is called a
{\it domain constructor} or, \index{constructor!domain} more simply, a
{\it constructor}.  A domain constructor is a function that creates a
domain.  An argument to a domain constructor can be another domain or,
in general, an arbitrary kind of object.  {\tt Polynomial} takes a
single domain argument while {\tt SquareMatrix} takes a positive
integer as an argument to give its dimension and a domain argument to
give the type of its components.

What kinds of domains can you use as the argument to {\tt Polynomial}
or {\tt SquareMatrix} or {\tt List}?  Well, the first two are
mathematical in nature.  You want to be able to perform algebraic
operations like ``{\tt +}'' and ``{\tt *}'' on polynomials and square
matrices, and operations such as {\bf determinant} on square
matrices.  So you want to allow polynomials of integers {\it and}
polynomials of square matrices with complex number coefficients and,
in general, anything that ``makes sense.'' At the same time, you don't
want Axiom to be able to build nonsense domains such as ``polynomials
of strings!''

In contrast to algebraic structures, data structures can hold any kind
of object.  Operations on lists such as \spadfunFrom{insert}{List},
\spadfunFrom{delete}{List}, and \spadfunFrom{concat}{List} just
manipulate the list itself without changing or operating on its
elements.  Thus you can build {\tt List} over almost any datatype,
including itself.

Create a complicated algebraic domain.
\spadcommand{List (List (Matrix (Polynomial (Complex (Fraction (Integer))))))}
$$
\mbox{\rm List List Matrix Polynomial Complex Fraction Integer} 
$$
\returnType{Type: Domain}

%Original Page 62

Try to create a meaningless domain.
\spadcommand{Polynomial(String)}
\begin{verbatim}
   Polynomial String is not a valid type.
\end{verbatim}

Evidently from our last example, Axiom has some mechanism that tells
what a constructor can use as an argument.  This brings us to the
notion of {\it category}.  As domains are objects, they too have a
domain.  The domain of a domain is a category.  A category is simply a
type whose members are domains.

A common algebraic category is {\tt Ring}, the class of all domains
that are ``rings.''  A ring is an algebraic structure with constants
$0$ and $1$ and operations \spadopFrom{+}{Ring}, \spadopFrom{-}{Ring},
and \spadopFrom{*}{Ring}.  These operations are assumed ``closed''
with respect to the domain, meaning that they take two objects of the
domain and produce a result object also in the domain.  The operations
are understood to satisfy certain ``axioms,'' certain mathematical
principles providing the algebraic foundation for rings.  For example,
the {\it additive inverse axiom} for rings states: \begin{center}
Every element $x$ has an additive inverse $y$ such that $x + y = 0$.
\end{center} The prototypical example of a domain that is a ring is
the integers.  Keep them in mind whenever we mention {\tt Ring}.

Many algebraic domain constructors such as {\tt Complex}, 
{\tt Polynomial}, {\tt Fraction}, take rings as arguments and return rings
as values.  You can use the infix operator ``$has$'' to ask a domain
if it belongs to a particular category.

All numerical types are rings.  Domain constructor {\tt Polynomial}
builds ``the ring of polynomials over any other ring.''
\spadcommand{Polynomial(Integer) has Ring}
$$
{\rm true}
$$
\returnType{Type: Boolean}

Constructor {\tt List} never produces a ring.
\spadcommand{List(Integer) has Ring}
$$
{\rm false}
$$
\returnType{Type: Boolean}

The constructor {\tt Matrix(R)} builds ``the domain of all matrices
over the ring $R$.'' This domain is never a ring since the operations
``{\tt +}'', ``{\tt -}'', and ``{\tt *}'' on matrices of arbitrary
shapes are undefined.
\spadcommand{Matrix(Integer) has Ring}
$$
{\rm false}
$$
\returnType{Type: Boolean}

Thus you can never build polynomials over matrices.
\spadcommand{Polynomial(Matrix(Integer))}
\begin{verbatim}
   Polynomial Matrix Integer is not a valid type.
\end{verbatim}

%Original Page 63

Use {\tt SquareMatrix(n,R)} instead.  For any positive integer $n$, it
builds ``the ring of $n$ by $n$ matrices over $R$.''
\spadcommand{Polynomial(SquareMatrix(7,Complex(Integer)))}
$$
\mbox{\rm Polynomial SquareMatrix(7,Complex Integer)} 
$$
\returnType{Type: Domain}

Another common category is {\tt Field}, the class of all fields.
\index{field} A field is a ring with additional operations.  For
example, a field has commutative multiplication and a closed operation
\spadopFrom{/}{Field} for the division of two elements.  {\tt Integer}
is not a field since, for example, $3/2$ does not have an integer
result.  The prototypical example of a field is the rational numbers,
that is, the domain {\tt Fraction(Integer)}.  In general, the
constructor {\tt Fraction} takes an IntegralDomain, which is a ring
with additional properties, as an argument and returns a field. 
\footnote{Actually, the argument domain must have some additional
so as to belong to the category {\tt IntegralDomain}}
Other domain constructors, such as {\tt Complex}, build fields only if their
argument domain is a field.

The complex integers (often called the ``Gaussian integers'') do not form
a field.
\spadcommand{Complex(Integer) has Field}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

But fractions of complex integers do.
\spadcommand{Fraction(Complex(Integer)) has Field}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The algebraically equivalent domain of complex rational numbers is a field
since domain constructor {\tt Complex} produces a field whenever its
argument is a field.
\spadcommand{Complex(Fraction(Integer)) has Field}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The most basic category is {\tt Type}.  \index{Type} It denotes the
class of all domains and subdomains. Note carefully that {\tt Type}
does not denote the class of all types.  The type of all categories is
{\tt Category}.  The type of {\tt Type} itself is undefined.  Domain
constructor {\tt List} is able to build ``lists of elements from
domain $D$'' for arbitrary $D$ simply by requiring that $D$ belong to
category {\tt Type}.

Now, you may ask, what exactly is a category?  \index{category} Like
domains, categories can be defined in the Axiom language.  A category
is defined by three components:

\begin{enumerate}
\item a name (for example, {\tt Ring}),
used to refer to the class of domains that the category represents;
\item a set of operations, used to refer to the operations that
the domains of this class support
(for example, ``{\tt +}'', ``{\tt -}'', and ``{\tt *}'' for rings); and
\item an optional list of other categories that this category extends.
\end{enumerate}

%Original Page 64

This last component is a new idea.  And it is key to the design of
Axiom!  Because categories can extend one another, they form
hierarchies.  Detailed charts showing the category hierarchies
in Axiom are displayed in Appendix (TPDHERE).  There you see
that all categories are extensions of {\tt Type} and that {\tt Field}
is an extension of {\tt Ring}.

The operations supported by the domains of a category are called the
{\sl exports} of that category because these are the operations made
available for system-wide use.  The exports of a domain of a given
category are not only the ones explicitly mentioned by the category.
Since a category extends other categories, the operations of these
other categories---and all categories these other categories
extend---are also exported by the domains.

For example, polynomial domains belong to {\tt PolynomialCategory}.
This category explicitly mentions some twenty-nine operations on
polynomials, but it extends eleven other categories (including 
{\tt Ring}).  As a result, the current system has over one hundred
operations on polynomials.

If a domain belongs to a category that extends, say, {\tt Ring}, it is
convenient to say that the domain exports {\tt Ring}.  The name of the
category thus provides a convenient shorthand for the list of
operations exported by the category.  Rather than listing operations
such as \spadopFrom{+}{Ring} and \spadopFrom{*}{Ring} of {\tt Ring}
each time they are needed, the definition of a type simply asserts
that it exports category {\tt Ring}.

The category name, however, is more than a shorthand.  The name 
{\tt Ring}, in fact, implies that the operations exported by rings are
required to satisfy a set of ``axioms'' associated with the name 
{\tt Ring}. This subtle but important feature distinguishes Axiom from
other abstract datatype designs.

Why is it not correct to assume that some type is a ring if it exports
all of the operations of {\tt Ring}?  Here is why.  Some languages
such as {\bf APL} \index{APL} denote the {\tt Boolean} constants
{\tt true} and {\tt false} by the integers $1$ and $0$ respectively, then use
``{\tt +}'' and ``{\tt *}'' to denote the logical operators {\bf or} and
{\bf and}.  But with these definitions {\tt Boolean} is not a
ring since the additive inverse axiom is violated. That is, there is
no inverse element $a$ such that $1 + a = 0$, or, in the usual terms:
{\tt true or a = false}.  This alternative definition of {\tt Boolean}
can be easily and correctly implemented in Axiom, since {\tt Boolean}
simply does not assert that it is of category {\tt Ring}.  This
prevents the system from building meaningless domains such as 
{\tt Polynomial(Boolean)} and then wrongfully applying algorithms that
presume that the ring axioms hold.

Enough on categories. To learn more about them, see 
\sectionref{ugCategories}. We now return to our discussion of domains.

%Original Page 65

Domains {\it export} a set of operations to make them available for
system-wide use.  {\tt Integer}, for example, exports the operations
\spadopFrom{+}{Integer} and \spadopFrom{=}{Integer} given by the
signatures \spadopFrom{+}{Integer}:
\spadsig{(Integer,Integer)}{Integer} and \spadopFrom{=}{Integer}:
\spadsig{(Integer,Integer)}{Boolean}, respectively.  Each of these
operations takes two {\tt Integer} arguments.  The
\spadopFrom{+}{Integer} operation also returns an {\tt Integer} but
\spadopFrom{=}{Integer} returns a {\tt Boolean}: {\tt true} or {\tt false}.
The operations exported by a domain usually manipulate objects of the
domain---but not always.

The operations of a domain may actually take as arguments, and return
as values, objects from any domain.  For example, {\tt Fraction
(Integer)} exports the operations \spadopFrom{/}{Fraction}:
\spadsig{(Integer,Integer)}{Fraction(Integer)} and
\spadfunFrom{characteristic}{Fraction}:
\spadsig{}{NonNegativeInteger}.

Suppose all operations of a domain take as arguments and return as
values, only objects from {\it other} domains.  \index{package} This
kind of domain \index{constructor!package} is what Axiom calls a {\it
package}.

A package does not designate a class of objects at all.  Rather, a
package is just a collection of operations.  Actually the bulk of the
Axiom library of algorithms consists of packages.  The facilities for
factorization; integration; solution of linear, polynomial, and
differential equations; computation of limits; and so on, are all
defined in packages.  Domains needed by algorithms can be passed to a
package as arguments or used by name if they are not ``variable.''
Packages are useful for defining operations that convert objects of
one type to another, particularly when these types have different
parameterizations.  As an example, the package {\tt PolynomialFunction2(R,S)} 
defines operations that convert polynomials
over a domain $R$ to polynomials over $S$.  To convert an object from
{\tt Polynomial(Integer)} to {\tt Polynomial(Float)}, Axiom builds the
package {\tt PolynomialFunctions2(Integer,Float)} in order to create
the required conversion function.  (This happens ``behind the scenes''
for you: see \sectionref{ugTypesConvert}
for details on how to convert objects.)

Axiom categories, domains and packages and all their contained
functions are written in the Axiom programming language and have been
compiled into machine code.  This is what comprises the Axiom 
{\it library}.  We will show you how to use these
domains and their functions and how to write your own functions.

%Original Page 66

\section{Writing Types and Modes}
\label{ugTypesWriting}

We have already seen in the last section \sectionref{ugTypesBasic}
several examples of types.  Most of these
examples had either no arguments (for example, {\tt Integer}) or one
argument (for example, {\tt Polynomial (Integer)}).  In this section
we give details about writing arbitrary types.  We then define modes
and discuss how to write them.  We conclude the section with a
discussion on constructor abbreviations.

When might you need to write a type or mode?  You need to do so when
you declare variables.
\spadcommand{a : PositiveInteger}
\returnType{Type: Void}

You need to do so when you declare functions 
(See \sectionref{ugTypesDeclare})
\spadcommand{f : Integer -> String}
\returnType{Type: Void}

You need to do so when you convert an object from one type to another
(See \sectionref{ugTypesConvert}).
\spadcommand{factor(2 :: Complex(Integer))}
$$
-{i \  {{\left( 1+i 
\right)}
\sp 2}} 
$$
\returnType{Type: Factored Complex Integer}

\spadcommand{(2 = 3)\$Integer}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

You need to do so when you give computation target type information
(See \sectionref{ugTypesPkgCall})
\spadcommand{(2 = 3)@Boolean}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\subsection{Types with No Arguments}
\label{ugTypesWritingZero}

A constructor with no arguments can be written either
\index{type!using parentheses} with or without
\index{parentheses!using with types} trailing opening and closing
parentheses ``{\tt ()}''.

\begin{center}
{\tt Boolean()} is the same as {\tt Boolean} \\
{\tt Integer()} is the same as {\tt Integer} \\
{\tt String()} is the same as {\tt String} \\
{\tt Void()} is the same as {\tt Void} 
\end{center}

It is customary to omit the parentheses.

\subsection{Types with One Argument}
\label{ugTypesWritingOne}

A constructor with one argument can frequently be 
\index{type!using parentheses} written with no 
\index{parentheses!using with types} parentheses.  Types nest from 
right to left so that {\tt Complex Fraction Polynomial Integer} 
is the same as {\tt Complex (Fraction (Polynomial (Integer)))}.  
You need to use parentheses to force the application of a constructor 
to the correct argument, but you need not use any more than is necessary 
to remove ambiguities.

%Original Page 67

Here are some guidelines for using parentheses (they are possibly slightly
more restrictive than they need to be).

If the argument is an expression like $2 + 3$
then you must enclose the argument in parentheses.
\spadcommand{e : PrimeField(2 + 3)}
\returnType{Type: Void}

If the type is to be used with package calling
then you must enclose the argument in parentheses.
\spadcommand{content(2)\$Polynomial(Integer)}
$$
2 
$$
\returnType{Type: Integer}

Alternatively, you can write the type without parentheses
then enclose the whole type expression with parentheses.
\spadcommand{content(2)\$(Polynomial Complex Fraction Integer)}
$$
2 
$$
\returnType{Type: Complex Fraction Integer}

If you supply computation target type information 
(See \sectionref{ugTypesPkgCall})
then you should enclose the argument in parentheses.
\spadcommand{(2/3)@Fraction(Polynomial(Integer))}
$$
\frac{2}{3}
$$
\returnType{Type: Fraction Polynomial Integer}

If the type itself has parentheses around it and we are not in the
case of the first example above, then the parentheses can usually be
omitted.
\spadcommand{(2/3)@Fraction(Polynomial Integer)}
$$
\frac{2}{3}
$$
\returnType{Type: Fraction Polynomial Integer}

If the type is used in a declaration and the argument is a single-word
type, integer or symbol, then the parentheses can usually be omitted.
\spadcommand{(d,f,g) : Complex Polynomial Integer}
\returnType{Type: Void}

\subsection{Types with More Than One Argument}
\label{ugTypesWritingMore}

If a constructor \index{type!using parentheses} has more than
\index{parentheses!using with types} one argument, you must use
parentheses.  Some examples are \\

\noindent
{\tt UnivariatePolynomial(x, Float)} \\ 
{\tt MultivariatePolynomial([z,w,r], Complex Float)} \\ 
{\tt SquareMatrix(3, Integer)} \\ 
{\tt FactoredFunctions2(Integer,Fraction Integer)} 

%Original Page 68

\subsection{Modes}
\label{ugTypesWritingModes}

A {\it mode} is a type that possibly is a question mark ({\tt ?}) or
contains one in an argument position.  For example, the following are
all modes.\\

\noindent
{\tt ?} \\
{\tt Polynomial ?} \\
{\tt Matrix Polynomial ?} \\
{\tt SquareMatrix(3,?)} \\
{\tt Integer} \\
{\tt OneDimensionalArray(Float)}

As is evident from these examples, a mode is a type with a part that
is not specified (indicated by a question mark).  Only one ``{\tt ?}'' is
allowed per mode and it must appear in the most deeply nested argument
that is a type. Thus {\tt ?(Integer)}, {\tt Matrix(? (Polynomial))},
{\tt SquareMatrix(?, Integer)} (it requires a numeric argument)
and {\tt SquareMatrix(?, ?)} are all
invalid.  The question mark must take the place of a domain, not data.
This rules out, for example, the two {\tt SquareMatrix} expressions.

Modes can be used for declarations (See \sectionref{ugTypesDeclare})
and conversions (\sectionref{ugTypesConvert}).  However, you
cannot use a mode for package calling or giving target type information.

\subsection{Abbreviations}
\label{ugTypesWritingAbbr}

Every constructor has an abbreviation that
\index{abbreviation!constructor} you can freely
\index{constructor!abbreviation} substitute for the constructor name.
In some cases, the abbreviation is nothing more than the capitalized
version of the constructor name.

\boxer{4.6in}{

Aside from allowing types to be written more concisely, abbreviations
are used by Axiom to name various system files for constructors (such
as library filenames, test input files and example files).  Here are
some common abbreviations.

\begin{center}
\begin{tabular}{ll}
\small{\tt COMPLEX}   abbreviates {\tt Complex}             &
\small{\tt DFLOAT}    abbreviates {\tt DoubleFloat}         \\
\small{\tt EXPR}      abbreviates {\tt Expression}          &
\small{\tt FLOAT}     abbreviates {\tt Float}               \\
\small{\tt FRAC}      abbreviates {\tt Fraction}            &
\small{\tt INT}       abbreviates {\tt Integer}             \\
\small{\tt MATRIX}    abbreviates {\tt Matrix}              &
\small{\tt NNI}       abbreviates {\tt NonNegativeInteger}  \\
\small{\tt PI}        abbreviates {\tt PositiveInteger}     &
\small{\tt POLY}      abbreviates {\tt Polynomial}          \\
\small{\tt STRING}    abbreviates {\tt String}              &
\small{\tt UP}        abbreviates {\tt UnivariatePolynomial}\\
\end{tabular}
\end{center}
\vskip 0.1cm
}

You can combine both full constructor names and abbreviations in a
type expression.  Here are some types using abbreviations.

\begin{center}
\begin{tabular}{rcl}
{\tt POLY INT} & is the same as & {\tt Polynomial(INT)} \\
{\tt POLY(Integer)} & is the same as & {\tt Polynomial(Integer)} \\
{\tt POLY(Integer)} & is the same as & {\tt Polynomial(INT)} \\
{\tt FRAC(COMPLEX(INT))} & is the same as & {\tt Fraction Complex Integer} \\
{\tt FRAC(COMPLEX(INT))} & is the same as & {\tt FRAC(Complex Integer)} 
\end{tabular}
\end{center}

%Original Page 69

There are several ways of finding the names of constructors and their
abbreviations.  For a specific constructor, use {\tt )abbreviation
query}.  \index{abbreviation} You can also use the {\tt )what} system
command to see the names and abbreviations of constructors.
\index{what} For more information about {\tt )what}, see
\sectionref{ugSysCmdwhat}.

{\tt )abbreviation query} can be abbreviated (no pun intended) to 
{\tt )abb q}.
\spadcommand{)abb q Integer}
\begin{verbatim}
   INT abbreviates domain Integer 
\end{verbatim}

The {\tt )abbreviation query} command lists the constructor name if
you give the abbreviation.  Issue {\tt )abb q} if you want to see the
names and abbreviations of all Axiom constructors.  
\spadcommand{)abb q DMP} 
\begin{verbatim}
   DMP abbreviates domain DistributedMultivariatePolynomial 
\end{verbatim}

Issue this to see all packages whose
names contain the string ``ode''.  \index{what packages}
\spadcommand{)what packages ode}
\begin{verbatim}
---------------------- Packages -----------------------

Packages with names matching patterns:
     ode 

 EXPRODE  ExpressionSpaceODESolver     
 FCPAK1   FortranCodePackage1
 GRAY     GrayCode                     
 LODEEF   ElementaryFunctionLODESolver
 NODE1    NonLinearFirstOrderODESolver 
 ODECONST ConstantLODE
 ODEEF    ElementaryFunctionODESolver  
 ODEINT   ODEIntegration
 ODEPAL   PureAlgebraicLODE            
 ODERAT   RationalLODE
 ODERED   ReduceLODE                   
 ODESYS   SystemODESolver
 ODETOOLS ODETools
 UTSODE   UnivariateTaylorSeriesODESolver
 UTSODETL UTSodetools
\end{verbatim}

\section{Declarations}
\label{ugTypesDeclare}

A {\it declaration} is an expression used to restrict the type of
values that can be assigned to variables.  A colon ``{\tt :}'' is always
used after a variable or list of variables to be declared.

%Original Page 70

\boxer{4.6in}{
For a single variable, the syntax for declaration is
\begin{center}
{\it variableName $:$ typeOrMode}
\end{center}

For multiple variables, the syntax is
\begin{center}
{\tt ($\hbox{\it variableName}_{1}$, $\hbox{\it variableName}_{2}$, 
\ldots $\hbox{\it variableName}_{N}$): {\it typeOrMode}}
\end{center}
\vskip 0.1cm
}

You can always combine a declaration with an assignment.  When you do,
it is equivalent to first giving a declaration statement, then giving
an assignment.  For more information on assignment, see
\sectionref{ugIntroAssign} and \sectionref{ugLangAssign}.
To see how to declare your own functions, see \sectionref{ugUserDeclare}.

This declares one variable to have a type.
\spadcommand{a : Integer}
\returnType{Type: Void}

This declares several variables to have a type.
\spadcommand{(b,c) : Integer}
\returnType{Type: Void}

$a$, $b$ and $c$ can only hold integer values.
\spadcommand{a := 45}
$$
45 
$$
\returnType{Type: Integer}

If a value cannot be converted to a declared type,
an error message is displayed.
\spadcommand{b := 4/5}
\begin{verbatim}
 
   Cannot convert right-hand side of assignment
   4
   -
   5

      to an object of the type Integer of the left-hand side.
\end{verbatim}

This declares a variable with a mode.
\spadcommand{n : Complex ?}
\returnType{Type: Void}

This declares several variables with a mode.
\spadcommand{(p,q,r) : Matrix Polynomial ?}
\returnType{Type: Void}

%Original Page 71

This complex object has integer real and imaginary parts.
\spadcommand{n := -36 + 9 * \%i}
$$
-{36}+{9 \  i} 
$$
\returnType{Type: Complex Integer}

This complex object has fractional symbolic real and imaginary parts.
\spadcommand{n := complex(4/(x + y),y/x)}
$$
{\frac{4}{y+x}}+{{\frac{y}{x}} \  i} 
$$
\returnType{Type: Complex Fraction Polynomial Integer}

This matrix has entries that are polynomials with integer
coefficients.
\spadcommand{p := [ [1,2],[3,4],[5,6] ]}
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
3 & 4 \\ 
5 & 6 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

This matrix has a single entry that is a polynomial with
rational number coefficients.
\spadcommand{q := [ [x - 2/3] ]}
$$
\left[
\begin{array}{c}
{x -{\frac{2}{3}}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Fraction Integer}

This matrix has entries that are polynomials with complex integer
coefficients.

\spadcommand{r := [ [1-\%i*x,7*y+4*\%i] ]}
$$
\left[
\begin{array}{cc}
{-{i \  x}+1} & {{7 \  y}+{4 \  i}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Complex Integer}

Note the difference between this and the next example.
This is a complex object with polynomial real and imaginary parts.

\spadcommand{f : COMPLEX POLY ? := (x + y*\%i)**2}
$$
-{y \sp 2}+{x \sp 2}+{2 \  x \  y \  i} 
$$
\returnType{Type: Complex Polynomial Integer}

This is a polynomial with complex integer coefficients.  The objects
are convertible from one to the other.  See \sectionref{ugTypesConvert}
for more information.

\spadcommand{g : POLY COMPLEX ? := (x + y*\%i)**2}
$$
-{y \sp 2}+{2 \  i \  x \  y}+{x \sp 2} 
$$
\returnType{Type: Polynomial Complex Integer}

\section{Records}
\label{ugTypesRecords}

A {\tt Record} is an object composed of one or more other objects,
\index{Record} each of which is referenced \index{selector!record}
with \index{record!selector} a {\it selector}.  Components can all
belong to the same type or each can have a different type.

\boxer{4.6in}{
The syntax for writing a {\tt Record} type is \begin{center} {\tt
Record($\hbox{\it selector}_{1}$:$\hbox{\it type}_{1}$,
$\hbox{\it selector}_{2}$:$\hbox{\it type}_{2}$, \ldots,
$\hbox{\it selector}_{N}$:$\hbox{\it type}_{N}$)} \end{center} You must be
careful if a selector has the same name as a variable in the
workspace.  If this occurs, precede the selector name by a single
\index{quote} quote.\\
}

%Original Page 72

Record components are implicitly ordered.  All the components of a
record can be set at once by assigning the record a bracketed {\it
tuple} of values of the proper length. For example:
\spadcommand{r : Record(a:Integer, b: String) := [1, "two"]}  
$$
\left[
{a=1},  {b= \mbox{\tt "two"} } 
\right]
$$
\returnType{Type: Record(a: Integer,b: String)}
To access a component of a record $r$, write the name $r$, followed by
a period, followed by a selector.

The object returned by this computation is a record with two components: a
$quotient$ part and a $remainder$ part.
\spadcommand{u := divide(5,2)}
$$
\left[
{quotient=2},  {remainder=1} 
\right]
$$
\returnType{Type: Record(quotient: Integer,remainder: Integer)}

This is the quotient part.
\spadcommand{u.quotient}
$$
2 
$$
\returnType{Type: PositiveInteger}

This is the remainder part.
\spadcommand{u.remainder}
$$
1 
$$
\returnType{Type: PositiveInteger}

You can use selector expressions on the left-hand side of an assignment
to change destructively the components of a record.
\spadcommand{u.quotient := 8978}
$$
8978 
$$
\returnType{Type: PositiveInteger}

The selected component $quotient$ has the value $8978$, which is what
is returned by the assignment.  Check that the value of $u$ was
modified.
\spadcommand{u}
$$
\left[
{quotient={8978}},  {remainder=1} 
\right]
$$
\returnType{Type: Record(quotient: Integer,remainder: Integer)}

Selectors are evaluated.  Thus you can use variables that evaluate to
selectors instead of the selectors themselves.
\spadcommand{s := 'quotient}
$$
quotient 
$$
\returnType{Type: Variable quotient}

Be careful!  A selector could have the same name as a variable in the
workspace.  If this occurs, precede the selector name by a single
quote, as in $u.'quotient$.  \index{selector!quoting}
\spadcommand{divide(5,2).s}
$$
2 
$$
\returnType{Type: PositiveInteger}

Here we declare that the value of $bd$ has two components: a string,
to be accessed via {\tt name}, and an integer, to be accessed via
{\tt birthdayMonth}.
\spadcommand{bd : Record(name : String, birthdayMonth : Integer)}
\returnType{Type: Void}

You must initially set the value of the entire {\tt Record} at once.
\spadcommand{bd := ["Judith", 3]}
$$
\left[
{name= \mbox{\tt "Judith"} },  {birthdayMonth=3} 
\right]
$$
\returnType{Type: Record(name: String,birthdayMonth: Integer)}

%Original Page 73

Once set, you can change any of the individual components.
\spadcommand{bd.name := "Katie"}
$$
\mbox{\tt "Katie"} 
$$
\returnType{Type: String}

Records may be nested and the selector names can be shared at
different levels.
\spadcommand{r : Record(a : Record(b: Integer, c: Integer), b: Integer)}
\returnType{Type: Void}

The record $r$ has a $b$ selector at two different levels.
Here is an initial value for $r$.
\spadcommand{r := [ [1,2], 3 ]}
$$
\left[
{a={\left[ {b=1},  {c=2} 
\right]}},
 {b=3} 
\right]
$$
\returnType{Type: Record(a: Record(b: Integer,c: Integer),b: Integer)}

This extracts the $b$ component from the $a$ component of $r$.
\spadcommand{r.a.b}
$$
1 
$$
\returnType{Type: PositiveInteger}

This extracts the $b$ component from $r$.
\spadcommand{r.b}
$$
3 
$$
\returnType{Type: PositiveInteger}

You can also use spaces or parentheses to refer to {\tt Record}
components.  This is the same as $r.a$.
\spadcommand{r(a)}
$$
\left[
{b=1},  {c=2} 
\right]
$$
\returnType{Type: Record(b: Integer,c: Integer)}
This is the same as $r.b$.
\spadcommand{r b}
$$
3 
$$
\returnType{Type: PositiveInteger}

This is the same as $r.b := 10$.
\spadcommand{r(b) := 10}
$$
10 
$$
\returnType{Type: PositiveInteger}

Look at $r$ to make sure it was modified.
\spadcommand{r}
$$
\left[
{a={\left[ {b=1},  {c=2} 
\right]}},
 {b={10}} 
\right]
$$
\returnType{Type: Record(a: Record(b: Integer,c: Integer),b: Integer)}

\section{Unions}
\label{ugTypesUnions}

Type {\tt Union} is used for objects that can be of any of a specific
finite set of types.  \index{Union} Two versions of unions are
available, one with selectors (like records) and one without.
\index{union}

%Original Page 74

\subsection{Unions Without Selectors}
\label{ugTypesUnionsWOSel}

The declaration $x : Union(Integer, String, Float)$ states that $x$
can have values that are integers, strings or ``big'' floats.  If, for
example, the {\tt Union} object is an integer, the object is said to
belong to the {\tt Integer} {\it branch} of the {\tt Union}.  Note
that we are being a bit careless with the language here.  Technically,
the type of $x$ is always {\tt Union(Integer, String, Float)}.  If it
belongs to the {\tt Integer} branch, $x$ may be converted to an object
of type {\tt Integer}.

\boxer{4.6in}{
The syntax for writing a {\tt Union} type without selectors is
\begin{center}
{\tt Union($\hbox{\it type}_{1}$, $\hbox{\it type}_{2}$, 
\ldots, $\hbox{\it type}_{N}$)}
\end{center}
The types in a union without selectors must be distinct.\\
}

It is possible to create unions like {\tt Union(Integer, PositiveInteger)} 
but they are difficult to work with because of the overlap in the branch 
types.  See below for the rules Axiom uses for converting something into 
a union object.

The {\tt case} infix \index{case} operator returns a {\tt Boolean} and can
be used to determine the branch in which an object lies.

This function displays a message stating in which branch of the 
{\tt Union} the object (defined as $x$ above) lies.

\begin{verbatim}
sayBranch(x : Union(Integer,String,Float)) : Void  ==
  output
    x case Integer => "Integer branch"
    x case String  => "String branch"
    "Float branch"
\end{verbatim}

This tries {\bf sayBranch} with an integer.
\spadcommand{sayBranch 1}
\begin{verbatim}
Compiling function sayBranch with type Union(Integer,String,Float)
    -> Void 
 Integer branch
\end{verbatim}
\returnType{Type: Void}

This tries {\bf sayBranch} with a string.
\spadcommand{sayBranch "hello"}
\begin{verbatim}
   String branch
\end{verbatim}
\returnType{Type: Void}

This tries {\bf sayBranch} with a floating-point number.
\spadcommand{sayBranch 2.718281828}
\begin{verbatim}
   Float branch
\end{verbatim}
\returnType{Type: Void}

%Original Page 75

There are two things of interest about this particular
example to which we would like to draw your attention.
\begin{enumerate}
\item Axiom normally converts a result to the target value
before passing it to the function.
If we left the declaration information out of this function definition
then the {\bf sayBranch} call would have been attempted with an
{\tt Integer} rather than a {\tt Union}, and an error would have
resulted.
\item The types in a {\tt Union} are searched in the order given.
So if the type were given as

%\noindent
{\tt sayBranch(x: Union(String,Integer,Float,Any)): Void}

then the result would have been ``String branch'' because there
is a conversion from {\tt Integer} to {\tt String}.
\end{enumerate}

Sometimes {\tt Union} types can have extremely long names.  Axiom
therefore abbreviates the names of unions by printing the type of the
branch first within the {\tt Union} and then eliding the remaining
types with an ellipsis ({\tt ...}).

Here the {\tt Integer} branch is displayed first.  Use ``{\tt ::}'' to
create a {\tt Union} object from an object.
\spadcommand{78 :: Union(Integer,String)}
$$
78 
$$
\returnType{Type: Union(Integer,...)}

Here the {\tt String} branch is displayed first.
\spadcommand{s := "string" :: Union(Integer,String)}
$$
\mbox{\tt "string"} 
$$
\returnType{Type: Union(String,...)}

Use {\tt typeOf} to see the full and actual {\tt Union} type. \index{typeOf}
\spadcommand{typeOf s}
$$
Union(Integer,String) 
$$
\returnType{Type: Domain}

A common operation that returns a union is \spadfunFrom{exquo}{Integer}
which returns the ``exact quotient'' if the quotient is exact,
\spadcommand{three := exquo(6,2)}
$$
3 
$$
\returnType{Type: Union(Integer,...)}

and {\tt "failed"} if the quotient is not exact.
\spadcommand{exquo(5,2)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

A union with a {\tt "failed"} is frequently used to indicate the failure
or lack of applicability of an object.  As another example, assign an
integer a variable $r$ declared to be a rational number.
\spadcommand{r: FRAC INT := 3}
$$
3 
$$
\returnType{Type: Fraction Integer}

The operation \spadfunFrom{retractIfCan}{Fraction} tries to retract
the fraction to the underlying domain {\tt Integer}.  It produces a
union object.  Here it succeeds.
\spadcommand{retractIfCan(r)}
$$
3 
$$
\returnType{Type: Union(Integer,...)}

%Original Page 76

Assign it a rational number.
\spadcommand{r := 3/2}
$$
\frac{3}{2}
$$
\returnType{Type: Fraction Integer}

Here the retraction fails.
\spadcommand{retractIfCan(r)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

\subsection{Unions With Selectors}
\label{ugTypesUnionsWSel}

Like records (\sectionref{ugTypesRecords}), 
you can write {\tt Union} types \index{selector!union} with selectors.
\index{union!selector}

\boxer{4.6in}{
The syntax for writing a {\tt Union} type with selectors is
\begin{center}
{\tt Union($\hbox{\it selector}_{1}$:$\hbox{\it type}_{1}$, 
$\hbox{\it selector}_{2}$:$\hbox{\it type}_{2}$, \ldots, 
$\hbox{\it selector}_{N}$:$\hbox{\it type}_{N}$)}
\end{center}
You must be careful if a selector has the same name as a variable in
the workspace.  If this occurs, precede the selector name by a single
\index{quote} quote.  \index{selector!quoting} It is an error to use a
selector that does not correspond to the branch of the {\tt Union} in
which the element actually lies.  \\
}

Be sure to understand the difference between records and unions with
selectors.  \index{union!difference from record} Records can have more
than one component and the selectors are used to refer to the
components.  \index{record!difference from union} Unions always have
one component but the type of that one component can vary.  An object
of type {\tt Record(a: Integer, b: Float, c: String)} contains an
integer {\it and} a float {\it and} a string.  An object of type 
{\tt Union(a: Integer, b: Float, c: String)} contains an integer 
{\it or} a float {\it or} a string.

Here is a version of the {\bf sayBranch} function (cf.
\sectionref{ugTypesUnionsWOSel}) that
works with a union with selectors.  It displays a message stating in
which branch of the {\tt Union} the object lies.

\begin{verbatim}
sayBranch(x:Union(i:Integer,s:String,f:Float)):Void==
  output
    x case i => "Integer branch"
    x case s  => "String branch"
    "Float branch"
\end{verbatim}

Note that {\tt case} uses the selector name as its right-hand argument.
\index{case} If you accidentally use the branch type on the right-hand
side of {\tt case}, {\tt false} will be returned.

%Original Page 77

Declare variable $u$ to have a union type with selectors.
\spadcommand{u : Union(i : Integer, s : String)}
\returnType{Type: Void}

Give an initial value to $u$.
\spadcommand{u := "good morning"}
$$
\mbox{\tt "good morning"} 
$$
\returnType{Type: Union(s: String,...)}

Use $case$ to determine in which branch of a {\tt Union} an object lies.
\spadcommand{u case i}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{u case s}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

To access the element in a particular branch, use the selector.
\spadcommand{u.s}
$$
\mbox{\tt "good morning"} 
$$
\returnType{Type: String}

\section{The ``Any'' Domain}
\label{ugTypesAnyNone}

With the exception of objects of type {\tt Record}, all Axiom data
structures are homogenous, that is, they hold objects all of the same
type.  \index{Any} If you need to get around this, you can use type
{\tt Any}.  Using {\tt Any}, for example, you can create lists whose
elements are integers, rational numbers, strings, and even other
lists.

Declare $u$ to have type {\tt Any}.
\spadcommand{u: Any}
\returnType{Type: Void}

Assign a list of mixed type values to $u$
\spadcommand{u := [1, 7.2, 3/2, x**2, "wally"]}
$$
\left[
1,  {7.2},  {\frac{3}{2}},  {x \sp 2},  \mbox{\tt "wally"} 
\right]
$$
\returnType{Type: List Any}

When we ask for the elements, Axiom displays these types.
\spadcommand{u.1}
$$
1 
$$
\returnType{Type: PositiveInteger}

Actually, these objects belong to {\tt Any} but Axiom
automatically converts them to their natural types for you.
\spadcommand{u.3}
$$
\frac{3}{2}
$$
\returnType{Type: Fraction Integer}

%Original Page 78

Since type {\tt Any} can be anything, it can only belong to type 
{\tt Type}.  Therefore it cannot be used in algebraic domains.
\spadcommand{v : Matrix(Any)}
\begin{verbatim}
   Matrix Any is not a valid type.
\end{verbatim}

Perhaps you are wondering how Axiom internally represents objects of
type {\tt Any}.  An object of type {\tt Any} consists not only a data
part representing its normal value, but also a type part (a 
{\it badge}) giving \index{badge} its type.  For example, the value $1$ of
type {\tt PositiveInteger} as an object of type {\tt Any} internally
looks like $[1,{\tt PositiveInteger()}]$.

When should you use {\tt Any} instead of a {\tt Union} type?  For a
{\tt Union}, you must know in advance exactly which types you are
going to
allow.  For {\tt Any}, anything that comes along can be accommodated.

\section{Conversion}
\label{ugTypesConvert}

\boxer{4.6in}{
Conversion is the process of changing an object of one type into an
object of another type.  The syntax for conversion is:
$$
{\it object} {\tt ::} {\it newType}
$$
}

By default, $3$ has the type {\tt PositiveInteger}.
\spadcommand{3}
$$
3 
$$
\returnType{Type: PositiveInteger}

We can change this into an object of type {\tt Fraction Integer}
by using ``{\tt ::}''.
\spadcommand{3 :: Fraction Integer}
$$
3 
$$
\returnType{Type: Fraction Integer}

A {\it coercion} is a special kind of conversion that Axiom is allowed
to do automatically when you enter an expression.  Coercions are
usually somewhat safer than more general conversions.  The Axiom
library contains operations called {\bf coerce} and {\bf convert}.
Only the {\bf coerce} operations can be used by the interpreter to
change an object into an object of another type unless you explicitly
use a {\tt ::}.

By now you will be quite familiar with what types and modes look like.
It is useful to think of a type or mode as a pattern for what you want
the result to be.

Let's start with a square matrix of polynomials with complex rational
number coefficients. \index{SquareMatrix}
\spadcommand{m : SquareMatrix(2,POLY COMPLEX FRAC INT)}
\returnType{Type: Void}

%Original Page 79

\spadcommand{m := matrix [ [x-3/4*\%i,z*y**2+1/2],[3/7*\%i*y**4 - x,12-\%i*9/5] ]}
$$
\left[
\begin{array}{cc}
{x -{{\frac{3}{4}} \  i}} & {{{y \sp 2} \  z}+{\frac{1}{2}}} \\ 
{{{\frac{3}{7}} \  i \  {y \sp 4}} -x} & {{12} -{{\frac{9}{5}} \  i}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Polynomial Complex Fraction Integer)}

We first want to interchange the {\tt Complex} and {\tt Fraction}
layers.  We do the conversion by doing the interchange in the type
expression.
\spadcommand{m1 := m :: SquareMatrix(2,POLY FRAC COMPLEX INT)}
$$
\left[
\begin{array}{cc}
{x -{\frac{3 \  i}{4}}} & {{{y \sp 2} \  z}+{\frac{1}{2}}} \\ 
{{{\frac{3 \  i}{7}} \  {y \sp 4}} -x} & {\frac{{60} -{9 \  i}}{5}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Polynomial Fraction Complex Integer)}

Interchange the {\tt Polynomial} and the {\tt Fraction} levels.
\spadcommand{m2 := m1 :: SquareMatrix(2,FRAC POLY COMPLEX INT)}
$$
\left[
\begin{array}{cc}
{\frac{{4 \  x} -{3 \  i}}{4}} & {\frac{{2 \  {y \sp 2} \  z}+1}{2}} \\ 
{\frac{{3 \  i \  {y \sp 4}} -{7 \  x}}{7}} & {\frac{{60} -{9 \  i}}{5}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Fraction Polynomial Complex Integer)}

Interchange the {\tt Polynomial} and the {\tt Complex} levels.
\spadcommand{m3 := m2 :: SquareMatrix(2,FRAC COMPLEX POLY INT)}
$$
\left[
\begin{array}{cc}
{\frac{{4 \  x} -{3 \  i}}{4}} & {\frac{{2 \  {y \sp 2} \  z}+1}{2}} \\ 
{\frac{-{7 \  x}+{3 \  {y \sp 4} \  i}}{7}} & {\frac{{60} -{9 \  i}}{5}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Fraction Complex Polynomial Integer)}

All the entries have changed types, although in comparing the
last two results only the entry in the lower left corner looks different.
We did all the intermediate steps to show you what Axiom can do.

In fact, we could have combined all these into one conversion.
\spadcommand{m :: SquareMatrix(2,FRAC COMPLEX POLY INT)}
$$
\left[
\begin{array}{cc}
{\frac{{4 \  x} -{3 \  i}}{4}} & {\frac{{2 \  {y \sp 2} \  z}+1}{2}} \\ 
{\frac{-{7 \  x}+{3 \  {y \sp 4} \  i}}{7}} & {\frac{{60} -{9 \  i}}{5}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Fraction Complex Polynomial Integer)}

There are times when Axiom is not be able to do the conversion in one
step.  You may need to break up the transformation into several
conversions in order to get an object of the desired type.

We cannot move either {\tt Fraction} or {\tt Complex} above (or to the
left of, depending on how you look at it) {\tt SquareMatrix} because
each of these levels requires that its argument type have commutative
multiplication, whereas {\tt SquareMatrix} does not. That is because
{\tt Fraction} requires that its argument belong to the category 
{\tt IntegralDomain} and \index{category} {\tt Complex} requires that its
argument belong to {\tt CommutativeRing}. 
See \sectionref{ugTypesBasic} for a
brief discussion of categories. The {\tt Integer} level did not move
anywhere because it does not allow any arguments.  We also did not
move the {\tt SquareMatrix} part anywhere, but we could have.

%Original Page 80

Recall that $m$ looks like this.

\spadcommand{m}
$$
\left[
\begin{array}{cc}
{x -{{\frac{3}{4}} \  i}} & {{{y \sp 2} \  z}+{\frac{1}{2}}} \\ 
{{{\frac{3}{7}} \  i \  {y \sp 4}} -x} & {{12} -{{\frac{9}{5}} \  i}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Polynomial Complex Fraction Integer)}

If we want a polynomial with matrix coefficients rather than a matrix
with polynomial entries, we can just do the conversion.

\spadcommand{m :: POLY SquareMatrix(2,COMPLEX FRAC INT)}
$$
{{\left[ 
\begin{array}{cc}
0 & 1 \\ 
0 & 0 
\end{array}
\right]}
\  {y \sp 2} \  z}
+{{\left[ 
\begin{array}{cc}
0 & 0 \\ 
{{\frac{3}{7}} \  i} & 0 
\end{array}
\right]}
\  {y \sp 4}}
+{{\left[ 
\begin{array}{cc}
1 & 0 \\ 
-1 & 0 
\end{array}
\right]}
\  x}+{\left[ 
\begin{array}{cc}
-{{\frac{3}{4}} \  i} & {\frac{1}{2}} \\ 
0 & {{12} -{{\frac{9}{5}} \  i}} 
\end{array}
\right]}
$$
\returnType{Type: Polynomial SquareMatrix(2,Complex Fraction Integer)}

We have not yet used modes for any conversions.  Modes are a great
shorthand for indicating the type of the object you want.  Instead of
using the long type expression in the last example, we could have
simply said this.

\spadcommand{m :: POLY ?}
$$
{{\left[ 
\begin{array}{cc}
0 & 1 \\ 
0 & 0 
\end{array}
\right]}
\  {y \sp 2} \  z}+{{\left[ 
\begin{array}{cc}
0 & 0 \\ 
{{\frac{3}{7}} \  i} & 0 
\end{array}
\right]}
\  {y \sp 4}}+{{\left[ 
\begin{array}{cc}
1 & 0 \\ 
-1 & 0 
\end{array}
\right]}
\  x}+{\left[ 
\begin{array}{cc}
-{{\frac{3}{4}} \  i} & {\frac{1}{2}} \\ 
0 & {{12} -{{\frac{9}{5}} \  i}} 
\end{array}
\right]}
$$
\returnType{Type: Polynomial SquareMatrix(2,Complex Fraction Integer)}

We can also indicate more structure if we want the entries of the
matrices to be fractions.

\spadcommand{m :: POLY SquareMatrix(2,FRAC ?)}
$$
{{\left[ 
\begin{array}{cc}
0 & 1 \\ 
0 & 0 
\end{array}
\right]}
\  {y \sp 2} \  z}+{{\left[ 
\begin{array}{cc}
0 & 0 \\ 
{\frac{3 \  i}{7}} & 0 
\end{array}
\right]}
\  {y \sp 4}}+{{\left[ 
\begin{array}{cc}
1 & 0 \\ 
-1 & 0 
\end{array}
\right]}
\  x}+{\left[ 
\begin{array}{cc}
-{\frac{3 \  i}{4}} & {\frac{1}{2}} \\ 
0 & {\frac{{60} -{9 \  i}}{5}} 
\end{array}
\right]}
$$
\returnType{Type: Polynomial SquareMatrix(2,Fraction Complex Integer)}

\section{Subdomains Again}
\label{ugTypesSubdomains}

A {\it subdomain} {\rm S} of a domain {\rm D} is a domain consisting of
\begin{enumerate} 
\item those elements of {\rm D} that satisfy some 
{\it predicate} (that is, a test that returns {\tt true} or {\tt false}) and 
\item a subset of the operations of {\rm D}.  
\end{enumerate} 
Every domain is a subdomain of itself, trivially satisfying the
membership test: {\tt true}.

%Original Page 81

Currently, there are only two system-defined subdomains in Axiom that
receive substantial use.  {\tt PositiveInteger} and 
{\tt NonNegativeInteger} are subdomains of {\tt Integer}.  An element $x$
of {\tt NonNegativeInteger} is an integer that is greater than or
equal to zero, that is, satisfies $x >= 0$.  An element $x$ of 
{\tt PositiveInteger} is a nonnegative integer that is, in fact, greater
than zero, that is, satisfies $x > 0$.  Not all operations from 
{\tt Integer} are available for these subdomains.  For example, negation
and subtraction are not provided since the subdomains are not closed
under those operations.  When you use an integer in an expression,
Axiom assigns to it the type that is the most specific subdomain whose
predicate is satisfied.

This is a positive integer.
\spadcommand{5}
$$
5 
$$
\returnType{Type: PositiveInteger}

This is a nonnegative integer.
\spadcommand{0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

This is neither of the above.
\spadcommand{-5}
$$
-5 
$$
\returnType{Type: Integer}

Furthermore, unless you are assigning an integer to a declared variable
or using a conversion, any integer result has as type the most
specific subdomain.
\spadcommand{(-2) - (-3)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{0 :: Integer}
$$
0 
$$
\returnType{Type: Integer}

\spadcommand{x : NonNegativeInteger := 5}
$$
5 
$$
\returnType{Type: NonNegativeInteger}

When necessary, Axiom converts an integer object into one belonging to
a less specific subdomain.  For example, in $3-2$, the arguments to
\spadopFrom{-}{Integer} are both elements of {\tt PositiveInteger},
but this type does not provide a subtraction operation.  Neither does
{\tt NonNegativeInteger}, so $3$ and $2$ are viewed as elements of
{\tt Integer}, where their difference can be calculated.  The result
is $1$, which Axiom then automatically assigns the type 
{\tt PositiveInteger}.

Certain operations are very sensitive to the subdomains to which their
arguments belong.  This is an element of {\tt PositiveInteger}.
\spadcommand{2 ** 2}
$$
4 
$$
\returnType{Type: PositiveInteger}

%Original Page 82

This is an element of {\tt Fraction Integer}.
\spadcommand{2 ** (-2)}
$$
\frac{1}{4}
$$
\returnType{Type: Fraction Integer}

It makes sense then that this is a list of elements of {\tt
PositiveInteger}.
\spadcommand{[10**i for i in 2..5]}
$$
\left[
{100},  {1000},  {10000},  {100000} 
\right]
$$
\returnType{Type: List PositiveInteger}

What should the type of {\tt [10**(i-1) for i in 2..5]} be?  On one hand,
$i-1$ is always an integer greater than zero as $i$ ranges from $2$ to
$5$ and so $10**i$ is also always a positive integer.  On the other,
$i-1$ is a very simple function of $i$.  Axiom does not try to analyze
every such function over the index's range of values to determine
whether it is always positive or nowhere negative.  For an arbitrary
Axiom function, this analysis is not possible.

So, to be consistent no such analysis is done and we get this.
\spadcommand{[10**(i-1) for i in 2..5]}
$$
\left[
{10},  {100},  {1000},  {10000} 
\right]
$$
\returnType{Type: List Fraction Integer}

To get a list of elements of {\tt PositiveInteger} instead, you have
two choices.  You can use a conversion.

\spadcommand{[10**((i-1) :: PI) for i in 2..5]}
\begin{verbatim}
Compiling function G82696 with type Integer -> Boolean 
Compiling function G82708 with type NonNegativeInteger -> Boolean 
\end{verbatim}
$$
\left[
{10},  {100},  {1000},  {10000} 
\right]
$$
\returnType{Type: List PositiveInteger}

Or you can use {\tt pretend}.  \index{pretend}
\spadcommand{[10**((i-1) pretend PI) for i in 2..5]}
$$
\left[
{10},  {100},  {1000},  {10000} 
\right]
$$
\returnType{Type: List PositiveInteger}

The operation {\tt pretend} is used to defeat the Axiom type system.
The expression {\tt object pretend D} means ``make a new object
(without copying) of type {\tt D} from {\tt object}.''  If 
{\tt object} were an integer and you told Axiom to pretend it was a list,
you would probably see a message about a fatal error being caught and
memory possibly being damaged.  Lists do not have the same internal
representation as integers!

You use {\tt pretend} at your peril.  \index{peril}

Use $pretend$ with great care!  Axiom trusts you that the value is of
the specified type.

\spadcommand{(2/3) pretend Complex Integer}
$$
2+{3 \  i} 
$$
\returnType{Type: Complex Integer}

%Original Page 83

\section{Package Calling and Target Types}
\label{ugTypesPkgCall}

Axiom works hard to figure out what you mean by an expression without
your having to qualify it with type information.  Nevertheless, there
are times when you need to help it along by providing hints (or even
orders!) to get Axiom to do what you want.

We saw in \sectionref{ugTypesDeclare} that
declarations using types and modes control the type of the results
produced.  For example, we can either produce a complex object with
polynomial real and imaginary parts or a polynomial with complex
integer coefficients, depending on the declaration.

Package calling is how you tell Axiom to use a particular function
from a particular part of the library.

Use the \spadopFrom{/}{Fraction} from {\tt Fraction Integer} to create
a fraction of two integers.
\spadcommand{2/3}
$$
\frac{2}{3}
$$
\returnType{Type: Fraction Integer}

If we wanted a floating point number, we can say ``use the
\spadopFrom{/}{Float} in {\tt Float}.''
\spadcommand{(2/3)\$Float}
$$
0.6666666666 6666666667 
$$
\returnType{Type: Float}

Perhaps we actually wanted a fraction of complex integers.
\spadcommand{(2/3)\$Fraction(Complex Integer)}
$$
\frac{2}{3}
$$
\returnType{Type: Fraction Complex Integer}

In each case, Axiom used the indicated operations, sometimes first
needing to convert the two integers into objects of the appropriate type.
In these examples, ``/'' is written as an infix operator.

\boxer{4.6in}{
To use package calling with an infix operator, use the following syntax:
$$(\ arg_1{\rm \ op\ }arg_2\ )\$type$$
} 

We used, for example, $(2/3)\${\rm Float}$. The expression $2+3+4$
is equivalent to $(2+3)+4$. Therefore in the expression 
$(2+3+4)\${\rm Float}$ the second ``+'' comes from the {\rm Float}
domain. The first ``+'' comes from {\rm Float} because the package
call causes Axiom to convert $(2+3)$ and $4$ to type
{\rm Float}. Before the sum is converted, it is given a target type
of {\rm Float} by Axiom and then evaluated. The target type causes the
``+'' from {\tt Float} to be used.

%Original Page 84

\boxer{4.6in}{
For an operator written before its arguments, you must use parentheses
around the arguments (even if there is only one), and follow the closing
parenthesis by a ``\$'' and then the type.
$$ fun\ (\ arg_1, arg_2, \ldots, arg_N\ )\$type$$
}

For example, to call the ``minimum'' function from {\rm DoubleFloat} on two
integers, you could write {\bf min}(4,89){\tt \$DoubleFloat}. Another use of
package calling is to tell Axiom to use a library function rather than a
function you defined. We discuss this in \sectionref{ugUserUse}.

Sometimes rather than specifying where an operation comes from, you
just want to say what type the result should be. We say that you provide a
{\sl target type} for the expression. Instead of using a ``\$'', use a ``@''
to specify the requested target type. Otherwise, the syntax is the same.
Note that giving a target type is not the same as explicitly doing a
conversion. The first says ``try to pick operations so that the result has
such-and-such a type.'' The second says ``compute the result and then convert
to an object of such-and-such a type.''

Sometimes it makes sense, as in this expression, to say ``choose the 
operations in this expression so that the final result is {\rm Float}.
\spadcommand{(2/3)@Float}
$$
0.6666666666 6666666667 
$$
\returnType{Type: Float}

Here we used ``{\tt @}'' to say that the target type of the left-hand side
was {\tt Float}.  In this simple case, there was no real difference
between using ``{\tt \$}'' and ``{\tt @}''.  
You can see the difference if you try the following.

This says to try to choose ``{\tt +}'' so that the result is a string.
Axiom cannot do this.
\spadcommand{(2 + 3)@String}
\begin{verbatim} 
An expression involving @ String actually evaluated to one of 
   type PositiveInteger . Perhaps you should use :: String .
\end{verbatim}

This says to get the {\tt +} from {\tt String} and apply it to the two
integers.  Axiom also cannot do this because there is no {\tt +}
exported by {\tt String}.
\spadcommand{(2 + 3)\$String}
\begin{verbatim}
   The function + is not implemented in String .
\end{verbatim}

The operation \spadfunFrom{concat}{String}
is used to concatenate two strings. One can also concatenate strings
by juxtaposition. For instance, by writing
\begin{verbatim}
   "asdf" "jkl"
\end{verbatim}
\index{String}

When we have more than one operation in an expression, the difference
is even more evident.  The following two expressions show that Axiom
uses the target type to create different objects.  
The ``{\tt +}'', ``{\tt *}'' and ``{\tt **}'' operations are all 
chosen so that an object of the correct final type is created.

%Original Page 85

This says that the operations should be chosen so that the result is a
{\tt Complex} object.
\spadcommand{((x + y * \%i)**2)@(Complex Polynomial Integer)}
$$
-{y \sp 2}+{x \sp 2}+{2 \  x \  y \  i} 
$$
\returnType{Type: Complex Polynomial Integer}

This says that the operations should be chosen so that the result is a
{\tt Polynomial} object.
\spadcommand{((x + y * \%i)**2)@(Polynomial Complex Integer)}
$$
-{y \sp 2}+{2 \  i \  x \  y}+{x \sp 2} 
$$
\returnType{Type: Polynomial Complex Integer}

What do you think might happen if we left off all target type and
package call information in this last example?
\spadcommand{(x + y * \%i)**2}
$$
-{y \sp 2}+{2 \  i \  x \  y}+{x \sp 2} 
$$
\returnType{Type: Polynomial Complex Integer}

We can convert it to {\tt Complex} as an afterthought.  But this is
more work than just saying making what we want in the first place.
\spadcommand{\% :: Complex ?}
$$
-{y \sp 2}+{x \sp 2}+{2 \  x \  y \  i} 
$$
\returnType{Type: Complex Polynomial Integer}

Finally, another use of package calling is to qualify fully an
operation that is passed as an argument to a function.

Start with a small matrix of integers.
\spadcommand{h := matrix [ [8,6],[-4,9] ]}
$$
\left[
\begin{array}{cc}
8 & 6 \\ 
-4 & 9 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

We want to produce a new matrix that has for entries the
multiplicative inverses of the entries of $h$.  One way to do this is
by calling \spadfunFrom{map}{MatrixCategoryFunctions2} with the
\spadfunFrom{inv}{Fraction} function from {\tt Fraction (Integer)}.

\spadcommand{map(inv\$Fraction(Integer),h)}
$$
\left[
\begin{array}{cc}
{\frac{1}{8}} & {\frac{1}{6}} \\ 
-{\frac{1}{4}} & {\frac{1}{9}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

We could have been a bit less verbose and used abbreviations.
\spadcommand{map(inv\$FRAC(INT),h)}
$$
\left[
\begin{array}{cc}
{\frac{1}{8}} & {\frac{1}{6}} \\ 
-{\frac{1}{4}} & {\frac{1}{9}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

As it turns out, Axiom is smart enough to know what we mean anyway.
We can just say this.
\spadcommand{map(inv,h)}
$$
\left[
\begin{array}{cc}
{\frac{1}{8}} & {\frac{1}{6}} \\ 
-{\frac{1}{4}} & {\frac{1}{9}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

%Original Page 86

\section{Resolving Types}
\label{ugTypesResolve}

In this section we briefly describe an internal process by which
\index{resolve} Axiom determines a type to which two objects of
possibly different types can be converted.  We do this to give you
further insight into how Axiom takes your input, analyzes it, and
produces a result.

What happens when you enter $x + 1$ to Axiom?  Let's look at what you
get from the two terms of this expression.

This is a symbolic object whose type indicates the name.
\spadcommand{x}
$$
x 
$$
\returnType{Type: Variable x}

This is a positive integer.
\spadcommand{1}
$$
1 
$$
\returnType{Type: PositiveInteger}

There are no operations in {\tt PositiveInteger} that add positive
integers to objects of type {\tt Variable(x)} nor are there any in
{\tt Variable(x)}.  Before it can add the two parts, Axiom must come
up with a common type to which both $x$ and $1$ can be converted.  We
say that Axiom must {\it resolve} the two types into a common type.
In this example, the common type is {\tt Polynomial(Integer)}.

Once this is determined, both parts are converted into polynomials,
and the addition operation from {\tt Polynomial(Integer)} is used to
get the answer.
\spadcommand{x + 1}
$$
x+1 
$$
\returnType{Type: Polynomial Integer}

Axiom can always resolve two types: if nothing resembling the original
types can be found, then {\tt Any} is be used.  \index{Any} This is
fine and useful in some cases.

\spadcommand{["string",3.14159]}
$$
\left[
\mbox{\tt "string"} ,  {3.14159} 
\right]
$$
\returnType{Type: List Any}

In other cases objects of type {\tt Any} can't be used by the
operations you specified.
\spadcommand{"string" + 3.14159}
\begin{verbatim}
There are 11 exposed and 5 unexposed library operations named + 
  having 2 argument(s) but none was determined to be applicable. 
  Use HyperDoc Browse, or issue
                            )display op +
  to learn more about the available operations. Perhaps 
  package-calling the operation or using coercions on the 
  arguments will allow you to apply the operation.
 
Cannot find a definition or applicable library operation named + 
  with argument type(s) 
                               String
                                Float
      
  Perhaps you should use "@" to indicate the required return type, 
  or "$" to specify which version of the function you need.
\end{verbatim}

Although this example was contrived, your expressions may need to be
qualified slightly to help Axiom resolve the types involved.  You may
need to declare a few variables, do some package calling, provide some
target type information or do some explicit conversions.

We suggest that you just enter the expression you want evaluated and
see what Axiom does.  We think you will be impressed with its ability
to ``do what I mean.''  If Axiom is still being obtuse, give it some
hints.  As you work with Axiom, you will learn where it needs a little
help to analyze quickly and perform your computations.

%Original Page 87

\section{Exposing Domains and Packages}
\label{ugTypesExpose}

In this section we discuss how Axiom makes some operations available
to you while hiding others that are meant to be used by developers or
only in rare cases.  If you are a new user of Axiom, it is likely that
everything you need is available by default and you may want to skip
over this section on first reading.

Every \index{constructor!exposed} domain and package in the Axiom
library \index{constructor!hidden} is \index{exposed!constructor}
either exposed (meaning that you can use its operations without doing
anything special) or it is {\it hidden} (meaning you have to either
package call (see \sectionref{ugTypesPkgCall})
the operations it contains or
explicitly expose it to use the operations).  The initial exposure
status for a constructor is set in the file {\bf exposed.lsp} (see the
{\it Installer's Note} \index{exposed.lsp @{\bf exposed.lsp}} for
Axiom \index{file!exposed.lsp @{\bf exposed.lsp}} if you need to know
the location of this file).  Constructors are collected together in
\index{group!exposure} {\it exposure groups}.  \index{exposure!group}
Categories are all in the exposure group ``categories'' and the bulk
of the basic set of packages and domains that are exposed are in the
exposure group ``basic.''  Here is an abbreviated sample of the file
(without the Lisp parentheses):

\begin{verbatim}
basic
        AlgebraicNumber                          AN
        AlgebraGivenByStructuralConstants        ALGSC
        Any                                      ANY
        AnyFunctions1                            ANY1
        BinaryExpansion                          BINARY
        Boolean                                  BOOLEAN
        CardinalNumber                           CARD
        CartesianTensor                          CARTEN
        Character                                CHAR
        CharacterClass                           CCLASS
        CliffordAlgebra                          CLIF
        Color                                    COLOR
        Complex                                  COMPLEX
        ContinuedFraction                        CONTFRAC
        DecimalExpansion                         DECIMAL
        ...
\end{verbatim}
\begin{verbatim}
categories
        AbelianGroup                             ABELGRP
        AbelianMonoid                            ABELMON
        AbelianMonoidRing                        AMR
        AbelianSemiGroup                         ABELSG
        Aggregate                                AGG
        Algebra                                  ALGEBRA
        AlgebraicallyClosedField                 ACF
        AlgebraicallyClosedFunctionSpace         ACFS
        ArcHyperbolicFunctionCategory            AHYP
        ...
\end{verbatim}

%Original Page 88

For each constructor in a group, the full name and the abbreviation is
given.  There are other groups in {\bf exposed.lsp} but initially only
the constructors in exposure groups ``basic'' ``categories''
``naglink'' and ``anna'' are exposed.

As an interactive user of Axiom, you do not need to modify this file.
Instead, use {\tt )set expose} to expose, hide or query the exposure
status of an individual constructor or exposure group. \index{set expose} 
The reason for having exposure groups is to be able to expose
or hide multiple constructors with a single command.  For example, you
might group together into exposure group ``quantum'' a number of
domains and packages useful for quantum mechanical computations.
These probably should not be available to every user, but you want an
easy way to make the whole collection visible to Axiom when it is
looking for operations to apply.

If you wanted to hide all the basic constructors available by default,
you would issue {\tt )set expose drop group basic}.  
\index{set expose drop group} We do not recommend that you do this.  
If, however, you discover that you have hidden all the basic constructors, 
you should issue {\tt )set expose add group basic} to restore your default
environment.  \index{set expose add group}

It is more likely that you would want to expose or hide individual
constructors.  In \sectionref{ugUserTriangle}
we use several operations from 
{\tt OutputForm}, a domain usually hidden.  To avoid package calling every
operation from {\tt OutputForm}, we expose the domain and let Axiom
conclude that those operations should be used.  Use {\tt )set expose
add constructor} and {\tt )set expose drop constructor} to expose and
hide a constructor, respectively.  \index{set expose drop constructor}
You should use the constructor name, not the abbreviation.  The 
{\tt )set expose} command guides you through these options.  
\index{set expose add constructor}

If you expose a previously hidden constructor, Axiom exhibits new
behavior (that was your intention) though you might not expect the
results that you get.  {\tt OutputForm} is, in fact, one of the worst
offenders in this regard.  \index{OutputForm} This domain is meant to
be used by other domains for creating a structure that Axiom knows how
to display.  It has functions like \spadopFrom{+}{OutputForm} that
form output representations rather than do mathematical calculations.
Because of the order in which Axiom looks at constructors when it is
deciding what operation to apply, {\tt OutputForm} might be used
instead of what you expect.

This is a polynomial.
\spadcommand{x + x}
$$
2 \  x 
$$
\returnType{Type: Polynomial Integer}

%Original Page 89

Expose {\tt OutputForm}.
\spadcommand{)set expose add constructor OutputForm }
\begin{verbatim}
   OutputForm is now explicitly exposed in frame G82322 
\end{verbatim}

This is what we get when {\tt OutputForm} is automatically available.
\spadcommand{x + x}
$$
x+x 
$$
\returnType{Type: OutputForm}

Hide {\tt OutputForm} so we don't run into problems with any later examples!
\spadcommand{)set expose drop constructor OutputForm }
\begin{verbatim}
   OutputForm is now explicitly hidden in frame G82322 
\end{verbatim}

Finally, exposure is done on a frame-by-frame basis.  A {\it frame}
(see \sectionref{ugSysCmdframe})
\index{frame!exposure and} is one of possibly several logical Axiom
workspaces within a physical one, each having its own environment (for
example, variables and function definitions).  If you have several
Axiom workspace windows on your screen, they are all different frames,
automatically created for you by HyperDoc.  Frames can be manually
created, made active and destroyed by the {\tt )frame} system command.
\index{frame} They do not share exposure information, so you need to
use {\tt )set expose} in each one to add or drop constructors from
view.

\section{Commands for Snooping}
\label{ugAvailSnoop}

To conclude this chapter, we introduce you to some system commands
that you can use for getting more information about domains, packages,
categories, and operations.  The most powerful Axiom facility for
getting information about constructors and operations is the Browse
component of HyperDoc.  This is discussed in \sectionref{ugBrowse}.

Use the {\tt )what} system command to see lists of system objects
whose name contain a particular substring (uppercase or lowercase is
not significant).  \index{what}

Issue this to see a list of all operations with ``{\tt complex}'' in
their names.  \index{what operation}
\spadcommand{)what operation complex}
\begin{verbatim}

Operations whose names satisfy the above pattern(s):

complex                   complex?                          
complexEigenvalues        complexEigenvectors               
complexElementary         complexExpand                     
complexForm               complexIntegrate                  
complexLimit              complexNormalize                  
complexNumeric            complexNumericIfCan               
complexRoots              complexSolve                      
complexZeros              createLowComplexityNormalBasis    
createLowComplexityTable  doubleComplex?                    
drawComplex               drawComplexVectorField            
fortranComplex            fortranDoubleComplex              
pmComplexintegrate                
   
To get more information about an operation such as 
complexZeros, issue the command )display op complexZeros 
\end{verbatim}

%Original Page 90

If you want to see all domains with ``{\tt matrix}'' in their names,
issue this.  \index{what domain}
\spadcommand{)what domain matrix}
\begin{verbatim}
----------------------- Domains -----------------------

Domains with names matching patterns:
     matrix 

 DHMATRIX DenavitHartenbergMatrix      
 DPMM     DirectProductMatrixModule
 IMATRIX  IndexedMatrix                
 LSQM     LieSquareMatrix
 M3D      ThreeDimensionalMatrix       
 MATCAT-  MatrixCategory&
 MATRIX   Matrix                       
 RMATCAT- RectangularMatrixCategory&
 RMATRIX  RectangularMatrix            
 SMATCAT- SquareMatrixCategory&
 SQMATRIX SquareMatrix
\end{verbatim}

Similarly, if you wish to see all packages whose names contain ``{\tt
gauss}'', enter this.  \index{what packages}
\spadcommand{)what package gauss}
\begin{verbatim}
---------------------- Packages -----------------------

Packages with names matching patterns:
     gauss 

 GAUSSFAC GaussianFactorizationPackage
\end{verbatim}

This command shows all the operations that {\tt Any} provides.
Wherever {\tt \$} appears, it means ``{\tt Any}''.  \index{show}
\spadcommand{)show Any}
\begin{verbatim}
 Any  is a domain constructor
 Abbreviation for Any is ANY 
 This constructor is exposed in this frame.
 Issue )edit /usr/local/axiom/mnt/algebra/any.spad 
  to see algebra source code for ANY 

--------------------- Operations ----------------------
 ?=? : (%,%) -> Boolean                
 any : (SExpression,None) -> %
 coerce : % -> OutputForm              
 dom : % -> SExpression
 domainOf : % -> OutputForm            
 hash : % -> SingleInteger
 latex : % -> String                   
 obj : % -> None
 objectOf : % -> OutputForm            
 ?~=? : (%,%) -> Boolean
 showTypeInOutput : Boolean -> String

\end{verbatim}

This displays all operations with the name {\tt complex}.
\index{display operation}
\spadcommand{)display operation complex}
\begin{verbatim}
There is one exposed function called complex :
 [1] (D1,D1) -> D from D if D has COMPCAT D1 and D1 has COMRING
\end{verbatim}

Let's analyze this output.

%Original Page 91

First we find out what some of the abbreviations mean.
\spadcommand{)abbreviation query COMPCAT}
\begin{verbatim}
   COMPCAT abbreviates category ComplexCategory 
\end{verbatim}

\spadcommand{)abbreviation query COMRING}
\begin{verbatim}
   COMRING abbreviates category CommutativeRing 
\end{verbatim}

So if {\tt D1} is a commutative ring (such as the integers or floats) and
{\tt D} belongs to {\tt Complex\-Category D1}, then there is an operation
called {\bf complex} that takes two elements of {\tt D1} and creates an
element of {\tt D}.  The primary example of a constructor implementing
domains belonging to {\tt ComplexCategory} is {\tt Complex}.  See
\domainref{Complex} for more information on that and see
\sectionref{ugUserDeclare} for more information on function types.

%\setcounter{chapter}{2}

%Original Page 93

\chapter{Using HyperDoc}
\label{ugHyper}

\begin{figure}[htbp]
\begin{picture}(324,260)%(-54,0)
\special{psfile=ps/v0hyper.eps}
\end{picture}
\caption{The HyperDoc root window page.}
\end{figure}

HyperDoc is the gateway to Axiom.  \index{HyperDoc} It's both an
on-line tutorial and an on-line reference manual.  It also enables you
to use Axiom simply by using the mouse and filling in templates.
HyperDoc is available to you if you are running Axiom under the X
Window System.

%Original Page 94

Pages usually have active areas, marked in {\bf this font} (bold
face).  As you move the mouse pointer to an active area, the pointer
changes from a filled dot to an open circle.  The active areas are
usually linked to other pages.  When you click on an active area, you
move to the linked page.

\section{Headings}
\label{ugHyperHeadings}
Most pages have a standard set of buttons at the top of the page.
This is what they mean:

\begin{description}

\item[\HelpBitmap] Click on this to get help.  The button only appears
if there is specific help for the page you are viewing.  You can get
{\it general} help for HyperDoc by clicking the help button on the
home page.

\item[\UpBitmap] Click here to go back one page.
By clicking on this button repeatedly, you can go back several pages and
then take off in a new direction.

\item[\ReturnBitmap] Go back to the home page, that is, the page on
which you started.  Use HyperDoc to explore, to make forays into new
topics.  Don't worry about how to get back.  HyperDoc remembers where
you came from.  Just click on this button to return.

\item[\ExitBitmap] From the root window (the one that is displayed
when you start the system) this button leaves the HyperDoc program,
and it must be restarted if you want to use it again.  From any other
HyperDoc window, it just makes that one window go away.  You {\it must} 
use this button to get rid of a window.  If you use the window
manager ``Close'' button, then all of HyperDoc goes away.

\end{description}

The buttons are not displayed if they are not applicable to the page
you are viewing.  For example, there is no \ReturnBitmap button on the
top-level menu.

\section{Key Definitions}
\label{ugHyperKeys}

The following keyboard definitions are in effect throughout HyperDoc.
See \sectionref{ugHyperScroll} and \sectionref{ugHyperInput}
for some contextual key definitions.

\begin{description}
\item[F1] Display the main help page.
\item[F3] Same as \ExitBitmap{}, makes the window go away if you are not at the top-level window or quits the HyperDoc facility if you are at the top-level.
\item[F5] Rereads the HyperDoc database, if necessary (for system developers).
\item[F9] Displays this information about key definitions.
\item[F12] Same as {\bf F3}.
\item[Up Arrow] Scroll up one line.
\item[Down Arrow] Scroll down one line.
\item[Page Up] Scroll up one page.
\item[Page Down] Scroll down one page.
\end{description}

\section{Scroll Bars}
\label{ugHyperScroll}

Whenever there is too much text to fit on a page, a 
{\it scroll \index{scroll bar} bar} 
automatically appears along the right side.

With a scroll bar, your page becomes an aperture, that is, a window
into a larger amount of text than can be displayed at one time.  The
scroll bar lets you move up and down in the text to see different
parts.  It also shows where the aperture is relative to the whole
text.  The aperture is indicated by a strip on the scroll bar.

%Original Page 95

Move the cursor with the mouse to the ``down-arrow'' at the bottom of
the scroll bar and click.  See that the aperture moves down one line.
Do it several times.  Each time you click, the aperture moves down one
line.  Move the mouse to the ``up-arrow'' at the top of the scroll bar
and click.  The aperture moves up one line each time you click.

Next move the mouse to any position along the middle of the scroll bar
and click.  HyperDoc attempts to move the top of the aperture to this
point in the text.

You cannot make the aperture go off the bottom edge.  When the
aperture is about half the size of text, the lowest you can move the
aperture is halfway down.

To move up or down one screen at a time, use the \fbox{\bf PageUp} and 
\fbox{\bf PageDown} keys on your keyboard.  They move the visible part of the
region up and down one page each time you press them.

If the HyperDoc page does not contain an input area (see
\sectionref{ugHyperInput}, you can also use
the \fbox{\bf Home} and \fbox{$\uparrow$} and \fbox{$\downarrow$}
arrow keys to navigate.  When you press the \fbox{\bf Home} key, the
screen is positioned at the very top of the page.  Use the
\fbox{$\uparrow$} and \fbox{$\downarrow$} arrow keys to move the
screen up and down one line at a time, respectively.

\section{Input Areas}
\label{ugHyperInput}

Input areas are boxes where you can put data.

To enter characters, first move your mouse cursor to somewhere within
the HyperDoc page.  Characters that you type are inserted in front of
the underscore.  This means that when you type characters at your
keyboard, they go into this first input area.

The input area grows to accommodate as many characters as you type.
Use the \fbox{\bf Backspace} key to erase characters to the left.  To
modify what you type, use the right-arrow \fbox{$\rightarrow$} and
left-arrow keys \fbox{$\leftarrow$} and the keys \fbox{\bf Insert},
\fbox{\bf Delete}, \fbox{\bf Home} and \fbox{\bf End}.  These keys are
found immediately on the right of the standard IBM keyboard.

If you press the \fbox{\bf Home} key, the cursor moves to the
beginning of the line and if you press the \fbox{\bf End} key, the
cursor moves to the end of the line.  Pressing 
\fbox{\bf Ctrl}--\fbox{\bf End} deletes all the text from the 
cursor to the end of the line.

A page may have more than one input area.  Only one input area has an
underscore cursor.  When you first see apage, the top-most input area
contains the cursor.  To type information into another input area, use
the \fbox{\bf Enter} or \fbox{\bf Tab} key to move from one input area to
xanother.  To move in the reverse order, use \fbox{\bf Shift}--\fbox{\bf Tab}.

You can also move from one input area to another using your mouse.
Notice that each input area is active. Click on one of the areas.
As you can see, the underscore cursor moves to that window.

%Original Page 96

\section{Radio Buttons and Toggles}
\label{ugHyperButtons}

Some pages have {\it radio buttons} and {\it toggles}.
Radio buttons are a group of buttons like those on car radios: you can
select only one at a time.

Once you have selected a button, it appears to be inverted and
contains a checkmark.  To change the selection, move the cursor with
the mouse to a different radio button and click.

A toggle is an independent button that displays some on/off state.
When ``on'', the button appears to be inverted and contains a
checkmark.  When ``off'', the button is raised.

Unlike radio buttons, you can set a group of them any way you like.
To change toggle the selection, move the cursor with the mouse to the
button and click.

\section{Search Strings}
\label{ugHyperSearch}

A {\it search string} is used for searching some database.  To learn
about search strings, we suggest that you bring up the HyperDoc
glossary.  To do this from the top-level page of HyperDoc:
\begin{enumerate}
\item Click on Reference, bringing up the Axiom Reference page.
\item Click on Glossary, bringing up the glossary.
\end{enumerate}

The glossary has an input area at its bottom.  We review the various
kinds of search strings you can enter to search the glossary.

The simplest search string is a word, for example, {\tt operation}.  A
word only matches an entry having exactly that spelling.  Enter the
word {\tt operation} into the input area above then click on 
{\bf Search}.  As you can see, {\tt operation} matches only one entry,
namely with {\tt operation} itself.

Normally matching is insensitive to whether the alphabetic characters
of your search string are in uppercase or lowercase.  Thus 
{\tt operation} and {\tt OperAtion} both have the same effect.
%If you prefer that matching be case-sensitive, issue the command
%{\tt set HHyperName mixedCase} command to the interpreter.

You will very often want to use the wildcard ``{\tt *}'' in your search
string so as to match multiple entries in the list.  The search key
``{\tt *}'' matches every entry in the list.  You can also use ``{\tt *}''
anywhere within a search string to match an arbitrary substring.  Try
``{\tt cat*}'' for example: enter ``{\tt cat*}'' into the input area and click
on {\bf Search}.  This matches several entries.

You use any number of wildcards in a search string as long as they are
not adjacent.  Try search strings such as ``{\tt *dom*}''.  As you see,
this search string matches ``{\tt domain}'', ``{\tt domain constructor}'',
``{\tt subdomain}'', and so on.

%Original Page 97

\subsection{Logical Searches}
\label{ugLogicalSearches}

For more complicated searches, you can use ``{\tt and}'', ``{\tt or}'', and
``{\tt not}'' with basic search strings; write logical expressions using
these three operators just as in the Axiom language.  For example,
{\tt domain or package} matches the two entries {\tt domain} and 
{\tt package}.  Similarly, ``{\tt dom* and *con*}'' matches 
``{\tt domain constructor}'' and others.  Also ``{\tt not *a*}'' matches 
every entry that does not contain the letter ``{\tt a}'' somewhere.

Use parentheses for grouping.  For example, ``{\tt dom* and (not *con*)}''
matches ``{\tt domain}'' but not ``{\tt domain constructor}''.

There is no limit to how complex your logical expression can be.
For example,
\begin{center}
{\tt a* or b* or c* or d* or e* and (not *a*)}
\end{center}
is a valid expression.

\section{Example Pages}
\label{ugHyperExample}

Many pages have Axiom example commands.

Each command has an active ``button'' along the left margin.  When you
click on this button, the output for the command is ``pasted-in.''
Click again on the button and you see that the pasted-in output
disappears.

Maybe you would like to run an example?  To do so, just click on any
part of its text!  When you do, the example line is copied into a new
interactive Axiom buffer for this HyperDoc page.

Sometimes one example line cannot be run before you run an earlier one.
Don't worry---HyperDoc automatically runs all the necessary
lines in the right order!

The new interactive Axiom buffer disappears when you leave HyperDoc.
If you want to get rid of it beforehand, use the {\bf Cancel} button
of the X Window manager or issue the Axiom system command 
{\tt )close.}  \index{close}

\section{X Window Resources for HyperDoc}
\label{ugHyperResources}

You can control the appearance of HyperDoc while running under Version
11 \index{HyperDoc X Window System defaults} of the X Window System by
placing the following resources \index{X Window System} in the file
{\bf .Xdefaults} in your home directory.  \index{file!.Xdefaults} 
In what follows, {\it font} is any valid X11 font name
\index{font} (for example, {\tt Rom14}) and {\it color} is any valid
X11 color \index{color} specification (for example, {\tt NavyBlue}).
For more information about fonts and colors, refer to the X Window
documentation for your system.

\begin{description}
\item[{\tt Axiom.hyperdoc.RmFont:} {\it font}] \ \newline
This is the standard text font.  
The default value is {\tt Rom14}
\item[{\tt Axiom.hyperdoc.RmColor:} {\it color}] \ \newline
This is the standard text color.  
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.ActiveFont:} {\it font}] \ \newline
This is the font used for HyperDoc link buttons.  
The default value is {\tt Bld14}

%Original Page 98

\item[{\tt Axiom.hyperdoc.ActiveColor:} {\it color}] \ \newline
This is the color used for HyperDoc link buttons.  
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.AxiomFont:} {\it font}] \ \newline
This is the font used for active Axiom commands.
The default value is {\tt Bld14}
\item[{\tt Axiom.hyperdoc.AxiomColor:} {\it color}] \ \newline
This is the color used for active Axiom commands.
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.BoldFont:} {\it font}] \ \newline
This is the font used for bold face.  
The default value is {\tt Bld14}
\item[{\tt Axiom.hyperdoc.BoldColor:} {\it color}] \ \newline
This is the color used for bold face.  
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.TtFont:} {\it font}] \ \newline
This is the font used for Axiom output in HyperDoc.
This font must be fixed-width.  
The default value is {\tt Rom14}
\item[{\tt Axiom.hyperdoc.TtColor:} {\it color}] \ \newline
This is the color used for Axiom output in HyperDoc.
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.EmphasizeFont:} {\it font}] \ \newline
This is the font used for italics.  
The default value is {\tt Itl14}
\item[{\tt Axiom.hyperdoc.EmphasizeColor:} {\it color}] \ \newline
This is the color used for italics.  
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.InputBackground:} {\it color}] \ \newline
This is the color used as the background for input areas.
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.InputForeground:} {\it color}] \ \newline
This is the color used as the foreground for input areas.
The default value is {\tt white}
\item[{\tt Axiom.hyperdoc.BorderColor:} {\it color}] \ \newline
This is the color used for drawing border lines.
The default value is {\tt black}
\item[{\tt Axiom.hyperdoc.Background:} {\it color}] \ \newline
This is the color used for the background of all windows.
The default value is {\tt white}
\end{description}
\vfill
\eject

%\setcounter{chapter}{3}

%Original Page 99

\chapter{Input Files and Output Styles}
\label{ugInOut}

In this chapter we discuss how to collect Axiom statements
and commands into files and then read the contents into the
workspace.
We also show how to display the results of your computations in
several different styles including \TeX{}, FORTRAN and
monospace two-dimensional format.\footnote{\TeX{} is a
trademark of the American Mathematical Society.}

The printed version of this book uses the Axiom \TeX{} output formatter.
When we demonstrate a particular output style, we will need to turn
\TeX{} formatting off and the output style on so that the correct output
is shown in the text.

\section{Input Files}
\label{ugInOutIn}

In this section we explain what an {\it input file} is and
\index{file!input} why you would want to know about it.  We discuss
where Axiom looks for input files and how you can direct it to look
elsewhere.  We also show how to read the contents of an input file
into the {\it workspace} and how to use the {\it history} facility to
generate an input file from the statements you have entered directly
into the workspace.

An {\it input} file contains Axiom expressions and system commands.
Anything that you can enter directly to Axiom can be put into an input
file.  This is how you save input functions and expressions that you
wish to read into Axiom more than one time.

%Original Page 100

To read an input file into Axiom, use the {\tt )read} system command.
\index{read} For example, you can read a file in a particular
directory by issuing
\begin{verbatim}
)read /spad/src/input/matrix.input
\end{verbatim}

The ``{\bf .input}'' is optional; this also works:
\begin{verbatim}
)read /spad/src/input/matrix
\end{verbatim}

What happens if you just enter {\tt )read matrix.input} or even {\tt
)read matrix}?  Axiom looks in your current working directory for
input files that are not qualified by a directory name.  Typically,
this directory is the directory from which you invoked Axiom.

To change the current working directory, use the {\tt )cd} system
command.  The command {\tt {)cd}} by itself shows the current working
\index{directory!default for searching} directory.  \index{cd} To
change it to \index{file!input!where found} the {\tt {src/input}}
subdirectory for user ``babar'', issue
\begin{verbatim}
)cd /u/babar/src/input
\end{verbatim}
Axiom looks first in this directory for an input file.  If it is not
found, it looks in the system's directories, assuming you meant some
input file that was provided with Axiom.

\boxer{4.6in}{
If you have the Axiom history facility turned on (which it is
by default), you can save all the lines you have entered into the
workspace by entering

)history )write

\index{history )write}

Axiom tells you what input file to edit to see your statements.  The
file is in your home directory or in the directory you specified with
\index{cd} {\tt {)cd}}.\\
}

In \sectionref{ugLangBlocks} we discuss using indentation in input files to
group statements into {\it blocks.}

\section{The .axiom.input File}
\label{ugInOutSpadprof}

When Axiom starts up, it tries to read the input file {\bf
.axiom.input}\footnote{{\bf.axiom.input} used to be called 
{\bf axiom.input} in the NAG version}
from your home \index{start-up profile file}
directory. \index{file!start-up profile} It
there is no {\bf .axiom.input} in your home directory, it reads the
copy located in its own {\bf src/input} directory.
\index{file!.axiom.input @{\bf .axiom.input}} The file usually
contains system commands to personalize your Axiom environment.  In
the remainder of this section we mention a few things that users
frequently place in their {\bf .axiom.input} files.

In order to have FORTRAN output always produced from your
computations, place the system command {\tt )set output fortran on} in
{\bf .axiom.input}.  \index{quit} If you do not want to be prompted
for confirmation when you issue the {\tt )quit} system command, place
{\tt )set quit unprotected} in {\bf .axiom.input}.  
\index{set quit unprotected} 

%Original Page 101

If you then decide that you do want to be prompted, issue
{\tt )set quit protected}.  \index{set quit protected} This is the
default setting so that new users do not leave Axiom
inadvertently.\footnote{The system command {\tt )pquit} always
prompts you for confirmation.}

To see the other system variables you can set, issue {\tt {)set}}
or use the HyperDoc {\bf Settings} facility to view and change
Axiom system variables.

\section{Common Features of Using Output Formats}
\label{ugInOutOut}

In this section we discuss how to start and stop the display
\index{output formats!common features} of the different output formats
and how to send the output to the screen or to a file.
\index{file!sending output to} To fix ideas, we use FORTRAN output
format for most of the examples.

You can use the {\tt )set output} system \index{output
formats!starting} command to \index{output formats!stopping} toggle or
redirect the different kinds of output.  \index{set output} The name
of the kind of output follows ``output'' in the command.  The names are

\begin{tabular}{@{}ll}
{\bf fortran} & for FORTRAN output. \\
{\bf algebra} & for monospace two-dimensional mathematical output. \\
{\bf tex}     & for \TeX{} output. \\
{\bf script}  & for IBM Script Formula Format output.
\end{tabular}

For example, issue {\tt {)set output fortran on}} to turn on FORTRAN
format and issue {\tt {)set output fortran off}} to turn it off.  By
default, {\tt algebra} is {\tt on} and all others are {\tt off}.
\index{set output fortran} When output is started, it is sent to the
screen.  To send the output to a file, give the file name without
\index{output formats!sending to file} directory or extension.  Axiom
appends a file extension depending on the kind of output being
produced.

Issue this to redirect FORTRAN output to, for example, the file
{\bf linalg.sfort}.
\spadcommand{)set output fortran linalg}
\begin{verbatim}
   FORTRAN output will be written to file linalg.sfort .
\end{verbatim}

You must {\it also} turn on the creation of FORTRAN output.
The above just says where it goes if it is created.
\spadcommand{)set output fortran on}

In what directory is this output placed?  It goes into the directory
from which you started Axiom, or if you have used the {\tt {)cd}}
system command, the one that you specified with {\tt {)cd}}.
\index{cd} You should use {\tt )cd} before you send the output to the file.

You can always direct output back to the screen by issuing this.
\index{output formats!sending to screen}
\spadcommand{)set output fortran console}

%Original Page 102

Let's make sure FORTRAN formatting is off so that nothing we
do from now on produces FORTRAN output.
\spadcommand{)set output fortran off}

We also delete the demonstrated output file we created.
\spadcommand{)system rm linalg.sfort}

You can abbreviate the words ``{\tt on},'' ``{\tt off},'' and 
``{\tt console}'' to the minimal number of characters needed to distinguish
them.  Because of this, you cannot send output to files called 
{\bf on.sfort, off.sfort, of.sfort, console.sfort, consol.sfort} and so on.

The width of the output on the page is set by \index{output
formats!line length} {\tt )set output length} for all formats except
FORTRAN.  \index{set output length} Use {\tt )set fortran fortlength}
to change the FORTRAN line length from its default value of $72$.

\section{Monospace Two-Dimensional Mathematical Format}
\label{ugInOutAlgebra}

This is the default output format for Axiom.  
It is usually on when you start the system.  
\index{set output algebra} 
\index{output formats!monospace 2D} 
\index{monospace 2D output format}

If it is not, issue this.
\spadcommand{)set output algebra on}

Since the printed version of this book (as opposed to the HyperDoc
version) shows output produced by the \TeX{} output formatter, let us
temporarily turn off \TeX{} output.
\spadcommand{)set output tex off}

Here is an example of what it looks like.
\spadcommand{matrix [ [i*x**i + j*\%i*y**j for i in 1..2] for j in 3..4]}
\begin{verbatim}

        +     3           3     2+
        |3%i y  + x  3%i y  + 2x |
   (1)  |                        |
        |     4           4     2|
        +4%i y  + x  4%i y  + 2x +
\end{verbatim}
\returnType{Type: Matrix Polynomial Complex Integer}

Issue this to turn off this kind of formatting.
\spadcommand{)set output algebra off}

Turn \TeX{} output on again.
\spadcommand{)set output tex on}

The characters used for the matrix brackets above are rather ugly.
You get this character set when you issue \index{character set} 
{\tt )set output characters plain}.  \index{set output characters} This
character set should be used when you are running on a machine that
does not support the IBM extended ASCII character set.  If you are
running on an IBM workstation, for example, issue 
{\tt )set output characters default} to get better looking output.

%Original Page 103

\section{TeX Format}
\label{ugInOutTeX}

Axiom can produce \TeX{} output for your \index{output formats!TeX
@{\TeX{}}} expressions.  \index{TeX output format @{\TeX{}} output format}
The output is produced using macros from the \LaTeX{} document
preparation system by Leslie Lamport\cite{Lamp86}. The printed version
of this book was produced using this formatter.

To turn on \TeX{} output formatting, issue this.
\index{set output tex}
\spadcommand{)set output tex on}

Here is an example of its output.
\begin{verbatim}
matrix [ [i*x**i + j*\%i*y**j for i in 1..2] for j in 3..4]

$$
\left[
\begin{array}{cc}
{{3 \  i \  {y \sp 3}}+x} & 
{{3 \  i \  {y \sp 3}}+{2 \  {x \sp 2}}} \\ 
{{4 \  i \  {y \sp 4}}+x} & 
{{4 \  i \  {y \sp 4}}+{2 \  {x \sp 2}}} 
\end{array}
\right]
$$

\end{verbatim}
This formats as
$$
\left[
\begin{array}{cc}
{{3 \  i \  {y \sp 3}}+x} & 
{{3 \  i \  {y \sp 3}}+{2 \  {x \sp 2}}} \\ 
{{4 \  i \  {y \sp 4}}+x} &  
{{4 \  i \  {y \sp 4}}+{2 \  {x \sp 2}}} 
\end{array}
\right]
$$

To turn \TeX{} output formatting off, issue 
{\tt {)set output tex off}}.
The \LaTeX macros in the output generated by Axiom
are all standard except for the following definitions:
\begin{verbatim}
\def\csch{\mathop{\rm csch}\nolimits}

\def\erf{\mathop{\rm erf}\nolimits}

\def\zag#1#2{
  {\frac{\hfill \left. {#1} \right|}{\left| {#2} \right. \hfill}
  }
}
\end{verbatim}

%Original Page 104

\section{IBM Script Formula Format}
\label{ugInOutScript}

Axiom can \index{output formats!IBM Script Formula Format} produce IBM
Script Formula Format output for your 
\index{IBM Script Formula Format} expressions.

To turn IBM Script Formula Format on, issue this.
\index{set output script}
\spadcommand{)set output script on}

Here is an example of its output.
\begin{verbatim}
matrix [ [i*x**i + j*%i*y**j for i in 1..2] for j in 3..4]

.eq set blank @
:df.
<left lb < < < <3 @@ %i @@ <y sup 3> >+x> here < <3 @@ %i @@
<y sup 3> >+<2 @@ <x sup 2> > > > habove < < <4 @@ %i @@
<y sup 4> >+x> here < <4 @@ %i @@ <y sup 4> >+<2 @@
<x up 2> > > > > right rb>
:edf.
\end{verbatim}

To turn IBM Script Formula Format output formatting off, issue this.
\spadcommand{)set output script off}

\section{FORTRAN Format}
\label{ugInOutFortran}

In addition to turning FORTRAN output on and off and stating where the
\index{output formats!FORTRAN} output should be placed, there are many
options that control the \index{FORTRAN output format} appearance of
the generated code.  In this section we describe some of the basic
options.  Issue {\tt )set fortran} to see a full list with their
current settings.

The output FORTRAN expression usually begins in column 7.  If the
expression needs more than one line, the ampersand character {\tt \&}
is used in column 6.  Since some versions of FORTRAN have restrictions
on the number of lines per statement, Axiom breaks long expressions
into segments with a maximum of 1320 characters (20 lines of 66
characters) per segment.  \index{set fortran} If you want to change
this, say, to 660 characters, issue the system command 
\index{set fortran explength} {\tt )set fortran explength 660}.  
\index{FORTRAN output format!breaking into multiple statements} 
You can turn off the line breaking by issuing {\tt )set fortran segment off}.
\index{set fortran segment} Various code optimization levels are available.

FORTRAN output is produced after you issue this.
\index{set output fortran}
\spadcommand{)set output fortran on}

For the initial examples, we set the optimization level to 0, which is the
lowest level.
\index{set fortran optlevel}
\spadcommand{)set fortran optlevel 0}

The output is usually in columns 7 through 72, although fewer columns
are used in the following examples so that the output
\index{FORTRAN output format!line length}
fits nicely on the page.
\spadcommand{)set fortran fortlength 60}

%Original Page 105

By default, the output goes to the screen and is displayed before the
standard Axiom two-dimensional output.  In this example, an assignment
to the variable $R1$ was generated because this is the result of step 1.
\spadcommand{(x+y)**3}
\begin{verbatim}
      R1=y**3+3*x*y*y+3*x*x*y+x**3
\end{verbatim}
$$
{y \sp 3}+{3 \  x \  {y \sp 2}}+{3 \  {x \sp 2} \  y}+{x \sp 3} 
$$
\returnType{Type: Polynomial Integer}

Here is an example that illustrates the line breaking.
\spadcommand{(x+y+z)**3}
\begin{verbatim}
      R2=z**3+(3*y+3*x)*z*z+(3*y*y+6*x*y+3*x*x)*z+y**3+3*x*y
     &*y+3*x*x*y+x**3
\end{verbatim}
$$
{z \sp 3}+{{\left( {3 \  y}+{3 \  x} 
\right)}
\  {z \sp 2}}+{{\left( {3 \  {y \sp 2}}+{6 \  x \  y}+{3 \  {x \sp 2}} 
\right)}
\  z}+{y \sp 3}+{3 \  x \  {y \sp 2}}+{3 \  {x \sp 2} \  y}+{x \sp 3} 
$$
\returnType{Type: Polynomial Integer}

Note in the above examples that integers are generally converted to
\index{FORTRAN output format!integers vs. floats} floating point
numbers, except in exponents.  This is the default behavior but can be
turned off by issuing {\tt )set fortran ints2floats off}.  
\index{set fortran ints2floats} The rules governing when the conversion 
is done are:
\begin{enumerate}
\item If an integer is an exponent, convert it to a floating point
number if it is greater than 32767 in absolute value, otherwise leave it
as an integer.
\item Convert all other integers in an expression to floating point numbers.
\end{enumerate}

These rules only govern integers in expressions.\\  
Numbers generated by Axiom for $DIMENSION$ statements are also integers.

To set the type of generated FORTRAN data, 
\index{FORTRAN output format!data types}
use one of the following:
\begin{verbatim}
)set fortran defaulttype REAL
)set fortran defaulttype INTEGER
)set fortran defaulttype COMPLEX
)set fortran defaulttype LOGICAL
)set fortran defaulttype CHARACTER
\end{verbatim}

When temporaries are created, they are given a default type of {\tt REAL.}  
Also, the {\tt REAL} versions of functions are used by default.
\spadcommand{sin(x)}
\begin{verbatim}
      R3=DSIN(x)
\end{verbatim}
$$
\sin 
\left(
{x} 
\right)
$$
\returnType{Type: Expression Integer}

At optimization level 1, Axiom removes common subexpressions.
\index{FORTRAN output format!optimization level}
\index{set fortran optlevel}
\spadcommand{)set fortran optlevel 1}

%Original Page 106

\spadcommand{(x+y+z)**3}
\begin{verbatim}
      T2=y*y
      T3=x*x
      R4=z**3+(3*y+3*x)*z*z+(3*T2+6*x*y+3*T3)*z+y**3+3*x*T2+
     &3*T3*y+x**3
\end{verbatim}
$$
{z \sp 3}+{{\left( {3 \  y}+{3 \  x} 
\right)}
\  {z \sp 2}}+{{\left( {3 \  {y \sp 2}}+{6 \  x \  y}+{3 \  {x \sp 2}} 
\right)}
\  z}+{y \sp 3}+{3 \  x \  {y \sp 2}}+{3 \  {x \sp 2} \  y}+{x \sp 3} 
$$
\returnType{Type: Polynomial Integer}

This changes the precision to {\tt DOUBLE}.  \index{set fortran
precision double} Substitute {\tt single} for {\tt double}
\index{FORTRAN output format!precision} to return to single precision.  
\index{set fortran precision single}

\spadcommand{)set fortran precision double}

Complex constants display the precision.
\spadcommand{2.3 + 5.6*\%i }
\begin{verbatim}
      R5=(2.3D0,5.6D0)
\end{verbatim}
$$
{2.3}+{{5.6} \  i} 
$$
\returnType{Type: Complex Float}

The function names that Axiom generates depend on the chosen precision.
\spadcommand{sin \%e}
%%NOTE: the book shows DSIN(DEXP(1.0D0))
\begin{verbatim}
      R6=DSIN(DEXP(1))
\end{verbatim}
$$
\sin 
\left(
{e} 
\right)
$$
\returnType{Type: Expression Integer}

Reset the precision to {\tt single} and look at these two examples again.
\spadcommand{)set fortran precision single}

\spadcommand{2.3 + 5.6*\%i}
\begin{verbatim}
      R7=(2.3,5.6)
\end{verbatim}
$$
{2.3}+{{5.6} \  i} 
$$
\returnType{Type: Complex Float}

\spadcommand{sin \%e}
%%NOTE: the book shows SIN(EXP(1.))
\begin{verbatim}
      R8=SIN(EXP(1))
\end{verbatim}
$$
\sin 
\left(
{e} 
\right)
$$
\returnType{Type: Expression Integer}

%Original Page 107

Expressions that look like lists, streams, sets or matrices cause
array code to be generated.
\spadcommand{[x+1,y+1,z+1]}
\begin{verbatim}
      T1(1)=x+1
      T1(2)=y+1
      T1(3)=z+1
      R9=T1
\end{verbatim}
$$
\left[
{x+1}, {y+1}, {z+1} 
\right]
$$
\returnType{Type: List Polynomial Integer}


A temporary variable is generated to be the name of the array.
\index{FORTRAN output format!arrays} This may have to be changed in
your particular application.
\spadcommand{set[2,3,4,3,5]}
\begin{verbatim}
      T1(1)=2
      T1(2)=3
      T1(3)=4
      T1(4)=5
      R10=T1
\end{verbatim}
$$
\left\{
2,  3,  4,  5 
\right\}
$$
\returnType{Type: Set PositiveInteger}

By default, the starting index for generated FORTRAN arrays is $0$.
\spadcommand{matrix [ [2.3,9.7],[0.0,18.778] ]}
\begin{verbatim}
      T1(0,0)=2.3
      T1(0,1)=9.7
      T1(1,0)=0.0
      T1(1,1)=18.778
      T1
\end{verbatim}
$$
\left[
\begin{array}{cc}
{2.3} & {9.7} \\ 
{0.0} & {18.778} 
\end{array}
\right]
$$
\returnType{Type: Matrix Float}

To change the starting index for generated FORTRAN arrays to be $1$,
\index{set fortran startindex} issue this.  This value can only be $0$
or $1$.
\spadcommand{)set fortran startindex 1}

%Original Page 108

Look at the code generated for the matrix again.
\spadcommand{matrix [ [2.3,9.7],[0.0,18.778] ]}
\begin{verbatim}
      T1(1,1)=2.3
      T1(1,2)=9.7
      T1(2,1)=0.0
      T1(2,2)=18.778
      T1
\end{verbatim}
$$
\left[
\begin{array}{cc}
{2.3} & {9.7} \\ 
{0.0} & {18.778} 
\end{array}
\right]
$$
\returnType{Type: Matrix Float}


%\setcounter{chapter}{4}

%Original Page 

\chapter{Overview of Interactive Language}
\label{ugLang}

In this chapter we look at some of the basic components of the Axiom
language that you can use interactively.  We show how to create a {\it
block} of expressions, how to form loops and list iterations, how to
modify the sequential evaluation of a block and how to use 
{\tt if-then-else} to evaluate parts of your program conditionally.  We
suggest you first read the boxer material in each section and then
proceed to a more thorough reading of the chapter.

\section{Immediate and Delayed Assignments}
\label{ugLangAssign}

A {\it variable} in Axiom refers to a value.  A variable has a name
beginning with an uppercase or lowercase alphabetic character, 
``{\tt \%}'', or ``{\tt !}''.  Successive characters (if any) can be any of
the above, digits, or ``{\tt ?}''.  Case is distinguished.  The
following are all examples of valid, distinct variable names:

\begin{verbatim}
a             tooBig?    a1B2c3%!?
A             %j         numberOfPoints
beta6         %J         numberofpoints
\end{verbatim}

%Original Page 110

The ``{\tt :=}'' operator is the immediate {\it assignment} operator.
\index{assignment!immediate} Use it to associate a value with a
variable.  \index{immediate assignment}

\boxer{4.6in}{
The syntax for immediate assignment for a single variable is
\begin{center}
{\it variable} $:=$ {\it expression}
\end{center}
The value returned by an immediate assignment is the value of 
{\it expression}.\\
}

The right-hand side of the expression is evaluated, yielding $1$.
This value is then assigned to $a$.
\spadcommand{a := 1}
$$
1 
$$
\returnType{Type: PositiveInteger}

The right-hand side of the expression is evaluated, yielding $1$.
This value is then assigned to $b$.  Thus $a$ and $b$ both have the
value $1$ after the sequence of assignments.
\spadcommand{b := a}
$$
1 
$$
\returnType{Type: PositiveInteger}

What is the value of $b$ if $a$ is assigned the value $2$?
\spadcommand{a := 2}
$$
2 
$$
\returnType{Type: PositiveInteger}

As you see, the value of $b$ is left unchanged.
\spadcommand{b}
$$
1 
$$
\returnType{Type: PositiveInteger}

This is what we mean when we say this kind of assignment is {\it
immediate}; $b$ has no dependency on $a$ after the initial assignment.
This is the usual notion of assignment found in programming languages
such as C, \index{C language!assignment} PASCAL
\index{PASCAL!assignment} and FORTRAN.  \index{FORTRAN!assignment}

Axiom provides delayed assignment with ``{\tt ==}''.
\index{assignment!delayed} This implements a \index{delayed
assignment} delayed evaluation of the right-hand side and dependency
checking.

\boxer{4.6in}{
The syntax for delayed assignment is
\begin{center}
{\it variable} $==$ {\it expression}
\end{center}
The value returned by a delayed assignment is the unique value of {\tt Void}.\\
}

%Original Page 111

Using $a$ and $b$ as above, these are the corresponding delayed assignments.
\spadcommand{a == 1}
\returnType{Type: Void}

\spadcommand{b == a}
\returnType{Type: Void}

The right-hand side of each delayed assignment is left unevaluated
until the variables on the left-hand sides are evaluated.  Therefore
this evaluation and \ldots
\spadcommand{a}
\begin{verbatim}
Compiling body of rule a to compute value of type PositiveInteger 
\end{verbatim}
$$
1 
$$
\returnType{Type: PositiveInteger}

this evaluation seem the same as before.
\spadcommand{b}
\begin{verbatim}
Compiling body of rule b to compute value of type PositiveInteger 
\end{verbatim}
$$
1 
$$
\returnType{Type: PositiveInteger}

If we change $a$ to $2$
\spadcommand{a == 2}
\begin{verbatim}
   Compiled code for a has been cleared.
   Compiled code for b has been cleared.
   1 old definition(s) deleted for function or rule a 
\end{verbatim}
\returnType{Type: Void}

then $a$ evaluates to $2$, as expected, but
\spadcommand{a}
\begin{verbatim}
Compiling body of rule a to compute value of type PositiveInteger 

+++ |*0;a;1;G82322| redefined
\end{verbatim}
$$
2 
$$
\returnType{Type: PositiveInteger}

the value of $b$ reflects the change to $a$.
\spadcommand{b}
\begin{verbatim}
Compiling body of rule b to compute value of type PositiveInteger 

+++ |*0;b;1;G82322| redefined
\end{verbatim}
$$
2 
$$
\returnType{Type: PositiveInteger}

It is possible to set several variables at the same time
\index{assignment!multiple immediate} by using \index{multiple
immediate assignment} a {\it tuple} of variables and a tuple of
expressions. Note that a {\it tuple} is a collection of things
separated by commas, often surrounded by parentheses.

%Original Page 112

\boxer{4.6in}{
The syntax for multiple immediate assignments is
\begin{center}
{\tt ( $\hbox{\it var}_{1}$, $\hbox{\it var}_{2}$, \ldots, 
$\hbox{\it var}_{N}$ ) := ( $\hbox{\it expr}_{1}$, $\hbox{\it expr}_{2}$, 
\ldots, $\hbox{\it expr}_{N}$ ) }
\end{center}
The value returned by an immediate assignment is the value of
$\hbox{\it expr}_{N}$.\\
}

This sets $x$ to $1$ and $y$ to $2$.
\spadcommand{(x,y) := (1,2)}
$$
2 
$$
\returnType{Type: PositiveInteger}

Multiple immediate assigments are parallel in the sense that the
expressions on the right are all evaluated before any assignments on
the left are made.  However, the order of evaluation of these
expressions is undefined.

You can use multiple immediate assignment to swap the values held by
variables.
\spadcommand{(x,y) := (y,x)}
$$
1 
$$
\returnType{Type: PositiveInteger}

$x$ has the previous value of $y$.
\spadcommand{x}
$$
2 
$$
\returnType{Type: PositiveInteger}

$y$ has the previous value of $x$.
\spadcommand{y}
$$
1 
$$
\returnType{Type: PositiveInteger}

There is no syntactic form for multiple delayed assignments.  See the
discussion in \sectionref{ugUserDelay}
about how Axiom differentiates between delayed assignments and user
functions of no arguments.

\section{Blocks}
\label{ugLangBlocks}

A {\it block} is a sequence of expressions evaluated in the order that
they appear, except as modified by control expressions such as
{\tt break}, \index{break} {\tt return}, \index{return} {\tt iterate} and
\index{iterate} {\tt if-then-else} constructions.  The value of a block is
the value of the expression last evaluated in the block.

To leave a block early, use ``{\tt =>}''.  For example, {\tt i < 0 => x}.  The
expression before the ``{\tt =>}'' must evaluate to {\tt true} or {\tt false}.
The expression following the ``{\tt =>}'' is the return value for the block.

A block can be constructed in two ways:
\begin{enumerate}
\item the expressions can be separated by semicolons
and the resulting expression surrounded by parentheses, and
\item the expressions can be written on succeeding lines with each line
indented the same number of spaces (which must be greater than zero).
\index{indentation}
A block entered in this form is
called a {\it pile}.
\end{enumerate}

%Original Page 113

Only the first form is available if you are entering expressions
directly to Axiom.  Both forms are available in {\bf .input} files.

\boxer{4.6in}{
The syntax for a simple block of expressions entered interactively is
\begin{center}
{\tt ( $\hbox{\it expression}_{1}$; $\hbox{\it expression}_{2}$; \ldots; 
$\hbox{\it expression}_{N}$ )}
\end{center}
The value returned by a block is the value of an {\tt =>} expression,
or $\hbox{\it expression}_{N}$ if no {\tt =>} is encountered.\\
}

In {\bf .input} files, blocks can also be written using piles.  The
examples throughout this book are assumed to come from {\bf .input} files.

In this example, we assign a rational number to $a$ using a block
consisting of three expressions.  This block is written as a pile.
Each expression in the pile has the same indentation, in this case two
spaces to the right of the first line.
\begin{verbatim}
a :=
  i := gcd(234,672)
  i := 3*i**5 - i + 1
  1 / i
\end{verbatim}
$$
\frac{1}{23323} 
$$
\returnType{Type: Fraction Integer}

Here is the same block written on one line.  This is how you are
required to enter it at the input prompt.
\spadcommand{a := (i := gcd(234,672); i := 3*i**5 - i + 1; 1 / i)}
$$
\frac{1}{23323} 
$$
\returnType{Type: Fraction Integer}

Blocks can be used to put several expressions on one line.  The value
returned is that of the last expression.
\spadcommand{(a := 1; b := 2; c := 3; [a,b,c])}
$$
\left[
1,  2,  3 
\right]
$$
\returnType{Type: List PositiveInteger}

Axiom gives you two ways of writing a block and the preferred way in
an {\bf .input} file is to use a pile.  \index{file!input} Roughly
speaking, a pile is a block whose constituent expressions are indented
the same amount.  You begin a pile by starting a new line for the
first expression, indenting it to the right of the previous line.  You
then enter the second expression on a new line, vertically aligning it
with the first line. And so on.  If you need to enter an inner pile,
further indent its lines to the right of the outer pile.  Axiom knows
where a pile ends.  It ends when a subsequent line is indented to the
left of the pile or the end of the file.

%Original Page 114

Blocks can be used to perform several steps before an assignment
(immediate or delayed) is made.
\begin{verbatim}
d :=
   c := a**2 + b**2
   sqrt(c * 1.3)
\end{verbatim}
$$
2.5495097567 96392415 
$$
\returnType{Type: Float}

Blocks can be used in the arguments to functions.  (Here $h$ is
assigned $2.1 + 3.5$.)
\begin{verbatim}
h := 2.1 +
   1.0
   3.5
\end{verbatim}
$$
5.6 
$$
\returnType{Type: Float}

Here the second argument to {\bf eval} is $x = z$, where the value of
$z$ is computed in the first line of the block starting on the second
line.
\begin{verbatim}
eval(x**2 - x*y**2,
     z := %pi/2.0 - exp(4.1)
     x = z
   )
\end{verbatim}
$$
{{58.7694912705 67072878} \  {y \sp 2}}+{3453.8531042012 59382} 
$$
\returnType{Type: Polynomial Float}

Blocks can be used in the clauses of {\tt if-then-else} expressions 
(see \sectionref{ugLangIf}).

\spadcommand{if h > 3.1 then 1.0 else (z := cos(h); max(z,0.5))}
$$
1.0 
$$
\returnType{Type: Float}

This is the pile version of the last block.
\begin{verbatim}
if h > 3.1 then
    1.0
  else
    z := cos(h)
    max(z,0.5)
\end{verbatim}
$$
1.0 
$$
\returnType{Type: Float}

Blocks can be nested.
\spadcommand{a := (b := factorial(12); c := (d := eulerPhi(22); factorial(d));b+c)}
$$
482630400 
$$
\returnType{Type: PositiveInteger}

This is the pile version of the last block.
\begin{verbatim}
a :=
  b := factorial(12)
  c :=
    d := eulerPhi(22)
    factorial(d)
  b+c
\end{verbatim}
$$
482630400 
$$
\returnType{Type: PositiveInteger}

%Original Page 115

Since $c + d$ does equal $3628855$, $a$ has the value of $c$ and the
last line is never evaluated.
\begin{verbatim}
a :=
  c := factorial 10
  d := fibonacci 10
  c + d = 3628855 => c
  d
\end{verbatim}
$$
3628800 
$$
\returnType{Type: PositiveInteger}

\section{if-then-else}
\label{ugLangIf}

Like many other programming languages, Axiom uses the three keywords
\index{if} {\tt if}, {\tt then} \index{then} and {\tt else}
\index{else} to form \index{conditional} conditional expressions.  The
{\tt else} part of the conditional is optional.  The expression
between the {\tt if} and {\tt then} keywords is a {\it predicate}: an
expression that evaluates to or is convertible to either {\tt true} or
{\tt false}, that is, a {\tt Boolean}.  \index{Boolean}

\boxer{4.6in}{
The syntax for conditional expressions is
\begin{center}
{\tt if\ }{\it predicate} 
{\tt then\ }$\hbox{\it expression}_{1}$ 
{\tt else\ }$\hbox{\it expression}_{2}$
\end{center}
where the {\tt else} $\hbox{\it expression}_{2}$ part is optional.  The
value returned from a conditional expression is 
$\hbox{\it expression}_{1}$ if the predicate evaluates to {\tt true} and 
$\hbox{\it expression}_{2}$ otherwise.  If no {\tt else} clause is given, 
the value is always the unique value of {\tt Void}.\\
}

An {\tt if-then-else} expression always returns a value.  If the 
{\tt else} clause is missing then the entire expression returns the unique
value of {\tt Void}.  If both clauses are present, the type of the
value returned by {\tt if} is obtained by resolving the types of the
values of the two clauses.  See \sectionref{ugTypesResolve} 
for more information.

The predicate must evaluate to, or be convertible to, an object of
type {\tt Boolean}: {\tt true} or {\tt false}.  By default, the equal
sign \spadopFrom{=}{Equation} creates \index{equation} an equation.

This is an equation.  \index{Equation} In particular, it is an object
of type {\tt Equation Polynomial Integer}.

\spadcommand{x + 1 = y}
$$
{x+1}=y 
$$
\returnType{Type: Equation Polynomial Integer}

However, for predicates in {\tt if} expressions, Axiom \index{equality
testing} places a default target type of {\tt Boolean} on the
predicate and equality testing is performed.  \index{Boolean} Thus you
need not qualify the ``{\tt =}'' in any way.  In other contexts you
may need to tell Axiom that you want to test for equality rather than
create an equation.  In those cases, use ``{\tt @}'' and a target type
of {\tt Boolean}.  See \sectionref{ugTypesPkgCall} for more information.

%Original Page 116

The compound symbol meaning ``not equal'' in Axiom is
\index{inequality testing} ``{$\sim =$}''.  \index{\_notequal@$\sim =$} 
This can be used directly without a package call or a target
specification.  The expression $a$~$\sim =$~$b$ is directly translated
into {\tt not}$(a = b)$.

Many other functions have return values of type {\tt Boolean}.  These
include ``{\tt <}'', ``{\tt <=}'', ``{\tt >}'', ``{\tt >=}'', 
``{\tt $\sim$=}'' and ``{\bf member?}''.  By convention,
operations with names ending in ``{\tt ?}''  return {\tt Boolean} values.

The usual rules for piles are suspended for conditional expressions.
In {\bf .input} files, the {\tt then} and {\tt else} keywords can begin in the
same column as the corresponding {\tt if} but may also appear to the
right.  Each of the following styles of writing {\tt if-then-else}
expressions is acceptable:
\begin{verbatim}
if i>0 then output("positive") else output("nonpositive")

if i > 0 then output("positive")
  else output("nonpositive")

if i > 0 then output("positive")
else output("nonpositive")

if i > 0
then output("positive")
else output("nonpositive")

if i > 0
  then output("positive")
  else output("nonpositive")
\end{verbatim}

A block can follow the {\tt then} or {\tt else} keywords.  In the following
two assignments to {\tt a}, the {\tt then} and {\tt else} clauses each are
followed by two-line piles.  The value returned in each is the value
of the second line.
\begin{verbatim}
a :=
  if i > 0 then
    j := sin(i * pi())
    exp(j + 1/j)
  else
    j := cos(i * 0.5 * pi())
    log(abs(j)**5 + 1)

a :=
  if i > 0
    then
      j := sin(i * pi())
      exp(j + 1/j)
    else
      j := cos(i * 0.5 * pi())
      log(abs(j)**5 + 1)
\end{verbatim}

These are both equivalent to the following:
\begin{verbatim}
a :=
  if i > 0 then (j := sin(i * pi()); exp(j + 1/j))
  else (j := cos(i * 0.5 * pi()); log(abs(j)**5 + 1))
\end{verbatim}

%Original Page 117

\section{Loops}
\label{ugLangLoops}

A {\it loop} is an expression that contains another expression,
\index{loop} called the {\it loop body}, which is to be evaluated zero
or more \index{loop!body} times.  All loops contain the {\tt repeat}
keyword and return the unique value of {\tt Void}.  Loops can contain
inner loops to any depth.

\boxer{4.6in}{
The most basic loop is of the form
\begin{center}
{\tt repeat\ }{\it loopBody}
\end{center}

Unless {\it loopBody} contains a {\tt break} or {\tt return} expression, the
loop repeats forever.  The value returned by the loop is the unique
value of {\tt Void}.\\
}

\subsection{Compiling vs. Interpreting Loops}
\label{ugLangLoopsCompInt}

Axiom tries to determine completely the type of every object in a loop
and then to translate the loop body to LISP or even to machine code.
This translation is called compilation.

If Axiom decides that it cannot compile the loop, it issues a
\index{loop!compilation} message stating the problem and then the
following message:
\begin{center}
{\bf We will attempt to step through and interpret the code.}
\end{center}

It is still possible that Axiom can evaluate the loop but in {\it
interpret-code mode}.  See \sectionref{ugUserCompInt} 
where this is discussed in terms
\index{panic!avoiding} of compiling versus interpreting functions.

\subsection{return in Loops}
\label{ugLangLoopsReturn}

A {\tt return} expression is used to exit a function with
\index{loop!leaving via return} a particular value.  In particular, if
a {\tt return} is in a loop within the \index{return} function, the loop
is terminated whenever the {\tt return} is evaluated.
%> This is a bug! The compiler should never accept allow
%> Void to be the return type of a function when it has to use
%> resolve to determine it.

Suppose we start with this.
\begin{verbatim}
f() ==
  i := 1
  repeat
    if factorial(i) > 1000 then return i
    i := i + 1
\end{verbatim}
\returnType{Type: Void}

When {\tt factorial(i)} is big enough, control passes from inside the loop
all the way outside the function, returning the value of $i$ (or so we
think).
\spadcommand{f()}
\returnType{Type: Void}

%Original Page 118

What went wrong?  Isn't it obvious that this function should return an
integer?  Well, Axiom makes no attempt to analyze the structure of a
loop to determine if it always returns a value because, in general,
this is impossible.  So Axiom has this simple rule: the type of the
function is determined by the type of its body, in this case a block.
The normal value of a block is the value of its last expression, in
this case, a loop.  And the value of every loop is the unique value of
{\tt Void}!  So the return type of {\bf f} is {\tt Void}.

There are two ways to fix this.  The best way is for you to tell Axiom
what the return type of $f$ is.  You do this by giving $f$ a
declaration {\tt f:()~->~Integer} prior to calling for its value.  This
tells Axiom: ``trust me---an integer is returned.''  We'll explain
more about this in the next chapter.  Another clumsy way is to add a
dummy expression as follows.

Since we want an integer, let's stick in a dummy final expression that is
an integer and will never be evaluated.
\begin{verbatim}
f() ==
  i := 1
  repeat
    if factorial(i) > 1000 then return i
    i := i + 1
  0
\end{verbatim}
\returnType{Type: Void}

When we try {\bf f} again we get what we wanted.  See
\sectionref{ugUserBlocks} for more information.

\spadcommand{f()}
\begin{verbatim}
   Compiling function f with type () -> NonNegativeInteger 
\end{verbatim}
$$
7 
$$
\returnType{Type: PositiveInteger}

\subsection{break in Loops}
\label{ugLangLoopsBreak}

The {\tt break} keyword is often more useful \index{break} in terminating
\index{loop!leaving via break} a loop.  A {\tt break} causes control to
transfer to the expression immediately following the loop.  As loops
always return the unique value of {\tt Void}, you cannot return a
value with {\tt break}.  That is, {\tt break} takes no argument.

This example is a modification of the last example in the previous
\sectionref{ugLangLoopsReturn}.
Instead of using {\tt return}, we'll use {\tt break}.

\begin{verbatim}
f() ==
  i := 1
  repeat
    if factorial(i) > 1000 then break
    i := i + 1
  i
\end{verbatim}
\begin{verbatim}
   Compiled code for f has been cleared.
   1 old definition(s) deleted for function or rule f 
\end{verbatim}
\returnType{Type: Void}

The loop terminates when {\tt factorial(i)} gets big enough, the last line
of the function evaluates to the corresponding ``good'' value of $i$,
and the function terminates, returning that value.

\spadcommand{f()}
\begin{verbatim}
   Compiling function f with type () -> PositiveInteger 

+++ |*0;f;1;G82322| redefined
\end{verbatim}
$$
7 
$$
\returnType{Type: PositiveInteger}

%Original Page 119

You can only use {\tt break} to terminate the evaluation of one loop.
Let's consider a loop within a loop, that is, a loop with a nested
loop.  First, we initialize two counter variables.

\spadcommand{(i,j) := (1, 1)}
$$
1 
$$
\returnType{Type: PositiveInteger}

Nested loops must have multiple {\tt break} \index{loop!nested}
expressions at the appropriate nesting level.  How would you rewrite
this so {\tt (i + j) > 10} is only evaluated once?
\begin{verbatim}
repeat
  repeat
    if (i + j) > 10 then break
    j := j + 1
  if (i + j) > 10 then break
  i := i + 1
\end{verbatim}
\returnType{Type: Void}

\subsection{break vs. {\tt =>} in Loop Bodies}
\label{ugLangLoopsBreakVs}

Compare the following two loops:
\begin{verbatim}
i := 1                            i := 1
repeat                            repeat
  i := i + 1                        i := i + 1
  i > 3 => i                        if i > 3 then break
  output(i)                         output(i)
\end{verbatim}

In the example on the left, the values $2$ and $3$ for $i$ are
displayed but then the ``{\tt =>}'' does not allow control to reach the
call to \spadfunFrom{output}{OutputForm} again.  The loop will not
terminate until you run out of space or interrupt the execution.  The
variable $i$ will continue to be incremented because the ``{\tt =>}'' only
means to leave the {\it block}, not the loop.

In the example on the right, upon reaching $4$, the {\tt break} will be
executed, and both the block and the loop will terminate.  This is one
of the reasons why both ``{\tt =>}'' and {\tt break} are provided.  Using a
{\tt while} clause (see below) with the ``{\tt =>}'' \index{while} lets you
simulate the action of {\tt break}.

\subsection{More Examples of break}
\label{ugLangLoopsBreakMore}

Here we give four examples of {\tt repeat} loops that terminate when a
value exceeds a given bound.

First, initialize $i$ as the loop counter.
\spadcommand{i := 0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

Here is the first loop.  When the square of $i$ exceeds $100$, the
loop terminates.
\begin{verbatim}
repeat
  i := i + 1
  if i**2 > 100 then break
\end{verbatim}
\returnType{Type: Void}

%Original Page 120

Upon completion, $i$ should have the value $11$.
\spadcommand{i}
$$
11 
$$
\returnType{Type: NonNegativeInteger}

Do the same thing except use ``{\tt =>}'' instead an {\tt if-then} expression.

\spadcommand{i := 0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

\begin{verbatim}
repeat
  i := i + 1
  i**2 > 100 => break
\end{verbatim}
\returnType{Type: Void}

\spadcommand{i}
$$
11 
$$
\returnType{Type: NonNegativeInteger}

As a third example, we use a simple loop to compute $n!$.
\spadcommand{(n, i, f) := (100, 1, 1)}
$$
1 
$$
\returnType{Type: PositiveInteger}

Use $i$ as the iteration variable and $f$ to compute the factorial.
\begin{verbatim}
repeat
  if i > n then break
  f := f * i
  i := i + 1
\end{verbatim}
\returnType{Type: Void}

Look at the value of $f$.
\spadcommand{f}
\begin{verbatim}
 93326215443944152681699238856266700490715968264381621468_
 59296389521759999322991560894146397615651828625369792082_
 7223758251185210916864000000000000000000000000
\end{verbatim}
\returnType{Type: PositiveInteger}

Finally, we show an example of nested loops.  First define a four by
four matrix.
\spadcommand{m := matrix [ [21,37,53,14], [8,-24,22,-16], [2,10,15,14], [26,33,55,-13] ]}
$$
\left[
\begin{array}{cccc}
{21} & {37} & {53} & {14} \\ 
8 & -{24} & {22} & -{16} \\ 
2 & {10} & {15} & {14} \\ 
{26} & {33} & {55} & -{13} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

Next, set row counter $r$ and column counter $c$ to $1$.  Note: if we
were writing a function, these would all be local variables rather
than global workspace variables.
\spadcommand{(r, c) := (1, 1)}
$$
1 
$$
\returnType{Type: PositiveInteger}

%Original Page 121

Also, let {\tt lastrow} and {\tt lastcol} be the final row and column index.

\spadcommand{(lastrow, lastcol) := (nrows(m), ncols(m))}
$$
4 
$$
\returnType{Type: PositiveInteger}

Scan the rows looking for the first negative element.  We remark that
you can reformulate this example in a better, more concise form by
using a {\tt for} clause with {\tt repeat}.  See
\sectionref{ugLangLoopsForIn} for more information.

\begin{verbatim}
repeat
  if r > lastrow then break
  c := 1
  repeat
    if c > lastcol then break
    if elt(m,r,c) < 0 then
      output [r, c, elt(m,r,c)]
      r := lastrow
      break     -- don't look any further
    c := c + 1
  r := r + 1
 
   [2,2,- 24]
\end{verbatim}
\returnType{Type: Void}

\subsection{iterate in Loops}
\label{ugLangLoopsIterate}

Axiom provides an {\tt iterate} expression that \index{iterate} skips over
the remainder of a loop body and starts the next loop iteration.

We first initialize a counter.

\spadcommand{i := 0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

Display the even integers from $2$ to $5$.
\begin{verbatim}
repeat
  i := i + 1
  if i > 5 then break
  if odd?(i) then iterate
  output(i)
 
   2
   4
\end{verbatim}
\returnType{Type: Void}

\subsection{while Loops}
\label{ugLangLoopsWhile}

The {\tt repeat} in a loop can be modified by adding one or more {\tt while}
clauses.  \index{while} Each clause contains a {\it predicate}
immediately following the {\tt while} keyword.  The predicate is tested
{\it before} the evaluation of the body of the loop.  The loop body is
evaluated whenever the predicates in a {\tt while} clause are all {\tt true}.

%Original Page 122

\boxer{4.6in}{
The syntax for a simple loop using {\tt while} is
\begin{center}
{\tt while} {\it predicate} {\tt repeat} {\it loopBody}
\end{center}
The {\it predicate} is evaluated before {\it loopBody} is evaluated.
A {\tt while} loop terminates immediately when {\it predicate} evaluates
to {\tt false} or when a {\tt break} or {\tt return} expression is evaluated in
{\it loopBody}.  The value returned by the loop is the unique value of
{\tt Void}.\\
}

Here is a simple example of using {\tt while} in a loop.  We first
initialize the counter.
\spadcommand{i := 1}
$$
1 
$$
\returnType{Type: PositiveInteger}

The steps involved in computing this example are\\
(1) set $i$ to $1$,\\
(2) test the condition $i < 1$ and determine that it is not {\tt true}, and\\
(3) do not evaluate the loop body and therefore do not display $"hello"$.
\begin{verbatim}
while i < 1 repeat
  output "hello"
  i := i + 1
\end{verbatim}
\returnType{Type: Void}

If you have multiple predicates to be tested use the logical {\tt and}
operation to separate them.  Axiom evaluates these predicates from
left to right.
\spadcommand{(x, y) := (1, 1)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\begin{verbatim}
while x < 4 and y < 10 repeat
  output [x,y]
  x := x + 1
  y := y + 2
 
   [1,1]
   [2,3]
   [3,5]
\end{verbatim}
\returnType{Type: Void}

A {\tt break} expression can be included in a loop body to terminate a
loop even if the predicate in any {\tt while} clauses are not {\tt false}.
\spadcommand{(x, y) := (1, 1)}
$$
1 
$$
\returnType{Type: PositiveInteger}

This loop has multiple {\tt while} clauses and the loop terminates
before any one of their conditions evaluates to {\tt false}.
\begin{verbatim}
while x < 4 while y < 10 repeat
  if x + y > 7 then break
  output [x,y]
  x := x + 1
  y := y + 2
 
   [1,1]
   [2,3]
\end{verbatim}
\returnType{Type: Void}

%Original Page 123

Here's a different version of the nested loops that looked for the
first negative element in a matrix.
\spadcommand{m := matrix [ [21,37,53,14], [8,-24,22,-16], [2,10,15,14], [26,33,55,-13] ]}
$$
\left[
\begin{array}{cccc}
{21} & {37} & {53} & {14} \\ 
8 & -{24} & {22} & -{16} \\ 
2 & {10} & {15} & {14} \\ 
{26} & {33} & {55} & -{13} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

Initialized the row index to $1$ and get the number of rows and
columns.  If we were writing a function, these would all be local
variables.
\spadcommand{r := 1}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{(lastrow, lastcol) := (nrows(m), ncols(m))}
$$
4 
$$
\returnType{Type: PositiveInteger}

Scan the rows looking for the first negative element.
\begin{verbatim}
while r <= lastrow repeat
  c := 1  -- index of first column
  while c <= lastcol repeat
    if elt(m,r,c) < 0 then
      output [r, c, elt(m,r,c)]
      r := lastrow
      break     -- don't look any further
    c := c + 1
  r := r + 1
 
   [2,2,- 24]
\end{verbatim}
\returnType{Type: Void}

\subsection{for Loops}
\label{ugLangLoopsForIn}

Axiom provides the {\tt for} \index{for} and {\tt in} \index{in} keywords in
{\tt repeat} loops, allowing you to iterate across all \index{iteration}
elements of a list, or to have a variable take on integral values from
a lower bound to an upper bound.  We shall refer to these modifying
clauses of {\tt repeat} loops as {\tt for} clauses.  These clauses can be
present in addition to {\tt while} clauses.  As with all other types of
{\tt repeat} loops, {\tt break} can \index{break} be used to prematurely
terminate the evaluation of the loop.

%Original Page 124

\boxer{4.6in}{
The syntax for a simple loop using {\tt for} is
\begin{center}
{\tt for} {\it iterator} {\tt repeat} {\it loopBody}
\end{center}

The {\it iterator} has several forms.  Each form has an end test which
is evaluated before {\it loopBody} is evaluated.  A {\tt for} loop
terminates immediately when the end test succeeds (evaluates to 
{\tt true}) or when a {\tt break} or {\tt return} expression is evaluated
in {\it loopBody}.  The value returned by the loop is the unique value
of {\tt Void}.\\ }

\subsection{for i in n..m repeat}
\label{ugLangLoopsForInNM}

If {\tt for} \index{for} is followed by a variable name, the {\tt in}
\index{in} keyword and then an integer segment of the form $n..m$,
\index{segment} the end test for this loop is the predicate $i > m$.
The body of the loop is evaluated $m-n+1$ times if this number is
greater than 0.  If this number is less than or equal to 0, the loop
body is not evaluated at all.

The variable $i$ has the value $n, n+1, ..., m$ for successive iterations
of the loop body.The loop variable is a {\it local variable}
within the loop body: its value is not available outside the loop body
and its value and type within the loop body completely mask any outer
definition of a variable with the same name.

This loop prints the values of
${10}^3$, ${11}^3$, and $12^3$:
\spadcommand{for i in 10..12 repeat output(i**3)}
\begin{verbatim}
   1000
   1331
   1728
\end{verbatim}
\returnType{Type: Void}

Here is a sample list.
\spadcommand{a := [1,2,3]}
$$
\left[
1,  2,  3 
\right]
$$
\returnType{Type: List PositiveInteger}

Iterate across this list, using ``{\tt .}'' to access the elements of
a list and the ``{\bf \#}'' operation to count its elements.

\spadcommand{for i in 1..\#a repeat output(a.i)}
\begin{verbatim}
   1
   2
   3
\end{verbatim}
\returnType{Type: Void}

This type of iteration is applicable to anything that uses ``{\tt .}''.
You can also use it with functions that use indices to extract elements.

%Original Page 125

Define $m$ to be a matrix.
\spadcommand{m := matrix [ [1,2],[4,3],[9,0] ]}
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
4 & 3 \\ 
9 & 0 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

Display the rows of $m$.
\spadcommand{for i in 1..nrows(m) repeat output row(m,i)}
\begin{verbatim}
   [1,2]
   [4,3]
   [9,0]
\end{verbatim}
\returnType{Type: Void}

You can use {\tt iterate} with {\tt for}-loops.\index{iterate}

Display the even integers in a segment.
\begin{verbatim}
for i in 1..5 repeat
  if odd?(i) then iterate
  output(i)
 
   2
   4
\end{verbatim}
\returnType{Type: Void}

See \domainref{Segment}.

\subsection{for i in n..m by s repeat}
\label{ugLangLoopsForInNMS}

By default, the difference between values taken on by a variable in
loops such as {\tt for i in n..m repeat ...} is $1$.  It is possible to
supply another, possibly negative, step value by using the {\tt by}
\index{by} keyword along with {\tt for} and {\tt in}.  Like the upper and
lower bounds, the step value following the {\tt by} keyword must be an
integer.  Note that the loop {\tt for i in 1..2 by 0 repeat output(i)}
will not terminate by itself, as the step value does not change the
index from its initial value of $1$.

This expression displays the odd integers between two bounds.
\spadcommand{for i in 1..5 by 2 repeat output(i)}
\begin{verbatim}
   1
   3
   5
\end{verbatim}
\returnType{Type: Void}

Use this to display the numbers in reverse order.
\spadcommand{for i in 5..1 by -2 repeat output(i)}
\begin{verbatim}
   5
   3
   1
\end{verbatim}
\returnType{Type: Void}

\subsection{for i in n.. repeat}
\label{ugLangLoopsForInN}

%Original Page 126

If the value after the ``{\tt ..}''  is omitted, the loop has no end test.
A potentially infinite loop is thus created.  The variable is given
the successive values ${n}, {n+1}, {n+2}, ...$ and the loop is terminated
only if a {\tt break} or {\tt return} expression is evaluated in the loop
body.  However you may also add some other modifying clause on the
{\tt repeat} (for example, a {\tt while} clause) to stop the loop.

This loop displays the integers greater than or equal to $15$
and less than the first prime greater than $15$.
\spadcommand{for i in 15.. while not prime?(i) repeat output(i)}
\begin{verbatim}
   15
   16
\end{verbatim}
\returnType{Type: Void}

\subsection{for x in l repeat}
\label{ugLangLoopsForInXL}

Another variant of the {\tt for} loop has the form:
\begin{center}
{\it {\tt for} x {\tt in} list {\tt repeat} loopBody}
\end{center}

This form is used when you want to iterate directly over the elements
of a list.  In this form of the {\tt for} loop, the variable {\tt x} takes on
the value of each successive element in {\tt l}.  The end test is most
simply stated in English: ``are there no more {\tt x} in {\tt l}?''

If {\tt l} is this list,
\spadcommand{l := [0,-5,3]}
$$
\left[
0,  -5,  3 
\right]
$$
\returnType{Type: List Integer}

display all elements of {\tt l}, one per line.
\spadcommand{for x in l repeat output(x)}
\begin{verbatim}
   0
   - 5
   3
\end{verbatim}
\returnType{Type: Void}

Since the list constructing expression {\bf expand}{\tt [n..m]} creates the
list $[n, {n+1}, ..., m]$. Note that this list is empty if $n > m$.  You
might be tempted to think that the loops
\begin{verbatim}
for i in n..m repeat output(i)
\end{verbatim}

and
\begin{verbatim}
for x in expand [n..m] repeat output(x)
\end{verbatim}

are equivalent.  The second form first creates the list {\bf
expand}{\tt [n..m]} (no matter how large it might be) and then does
the iteration.  The first form potentially runs in much less space, as
the index variable $i$ is simply incremented once per loop and the
list is not actually created.  Using the first form is much more
efficient.

%Original Page 127

Of course, sometimes you really want to iterate across a specific list.
This displays each of the factors of $2400000$.
\spadcommand{for f in factors(factor(2400000)) repeat output(f)}
\begin{verbatim}
   [factor= 2,exponent= 8]
   [factor= 3,exponent= 1]
   [factor= 5,exponent= 5]
\end{verbatim}
\returnType{Type: Void}

\subsection{``Such that'' Predicates}
\label{ugLangLoopsForInPred}

A {\tt for} loop can be followed by a ``{\tt |}'' and then a predicate.  The
predicate qualifies the use of the values from the iterator following
the {\tt for}.  Think of the vertical bar ``{\tt |}'' as the phrase ``such
that.''

This loop expression prints out the integers $n$ in the given segment
such that $n$ is odd.
\spadcommand{for n in 0..4 | odd? n repeat output n}
\begin{verbatim}
   1
   3
\end{verbatim}
\returnType{Type: Void}

\boxer{4.6in}{
A {\tt for} loop can also be written
$$
{\rm for} {\it \ iterator\ } | {\it \ predicate\ } 
{\rm repeat} {\it \ loopBody\ }
$$

which is equivalent to:
$$
{\rm for} {\it \ iterator\ } {\rm repeat\ if}
{\it \ predicate\ } {\rm then} {\it \ loopBody\ } {\rm else\ }iterate
$$
}

The predicate need not refer only to the variable in the {\tt for} clause:
any variable in an outer scope can be part of the predicate.

In this example, the predicate on the inner {\tt for} loop uses $i$ from
the outer loop and the $j$ from the {\tt for} \index{iteration!nested}
clause that it directly modifies.
\begin{verbatim}
for i in 1..50 repeat
  for j in 1..50 | factorial(i+j) < 25 repeat
    output [i,j]
 
   [1,1]
   [1,2]
   [1,3]
   [2,1]
   [2,2]
   [3,1]
\end{verbatim}
\returnType{Type: Void}

\subsection{Parallel Iteration}
\label{ugLangLoopsPar}

The last example of the previous \sectionref{ugLangLoopsForInPred}
gives an example of {\it nested iteration}: a loop is contained
\index{iteration!nested} in another loop.  \index{iteration!parallel}
Sometimes you want to iterate across two lists in parallel, or perhaps
you want to traverse a list while incrementing a variable.

%Original Page 128

\boxer{4.6in}{
The general syntax of a repeat loop is 
$$
iterator_1\  iterator_2\  \ldots\  iterator_N {\rm \ repeat\ } loopBody
$$
where each {\it iterator} is either a {\tt for} or a {\tt while} clause.  The
loop terminates immediately when the end test of any {\it iterator}
succeeds or when a {\tt break} or {\tt return} expression is evaluated in {\it
loopBody}.  The value returned by the loop is the unique value of {\tt
Void}.\\
}

Here we write a loop to iterate across two lists, computing the sum of
the pairwise product of elements. Here is the first list.
\spadcommand{l := [1,3,5,7]}
$$
\left[
1,  3,  5,  7 
\right]
$$
\returnType{Type: List PositiveInteger}

And the second.
\spadcommand{m := [100,200]}
$$
\left[
{100},  {200} 
\right]
$$
\returnType{Type: List PositiveInteger}

The initial value of the sum counter.
\spadcommand{sum := 0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

The last two elements of $l$ are not used in the calculation because
$m$ has two fewer elements than $l$.
\begin{verbatim}
for x in l for y in m repeat
    sum := sum + x*y
\end{verbatim}
\returnType{Type: Void}

Display the ``dot product.''
\spadcommand{sum}
$$
700 
$$
\returnType{Type: NonNegativeInteger}

Next, we write a loop to compute the sum of the products of the loop
elements with their positions in the loop.
\spadcommand{l := [2,3,5,7,11,13,17,19,23,29,31,37]}
$$
\left[
2,  3,  5,  7,  {11},  {13},  {17},  {19},  {23},  {29},  
{31},  {37} 
\right]
$$
\returnType{Type: List PositiveInteger}

The initial sum.
\spadcommand{sum := 0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

Here looping stops when the list $l$ is exhausted, even though
the {\tt for i in 0..} specifies no terminating condition.

\spadcommand{for i in 0.. for x in l repeat sum := i * x}
\returnType{Type: Void}

%Original Page 129

Display this weighted sum.
\spadcommand{sum}
$$
407 
$$
\returnType{Type: NonNegativeInteger}

When ``{\tt |}'' is used to qualify any of the {\tt for} clauses in a parallel
iteration, the variables in the predicates can be from an outer scope
or from a {\tt for} clause in or to the left of a modified clause.

This is correct:
% output from following is too long to show
\begin{verbatim}
for i in 1..10 repeat
  for j in 200..300 | odd? (i+j) repeat
    output [i,j]
\end{verbatim}

This is not correct since the variable $j$ has not been defined
outside the inner loop.
\begin{verbatim}
for i in 1..10 | odd? (i+j) repeat  -- wrong, j not defined
  for j in 200..300 repeat
    output [i,j]
\end{verbatim}

\subsection{Mixing Loop Modifiers}
\label{ugLangLoopsMix}

This example shows that it is possible to mix several of the
\index{loop!mixing modifiers} forms of {\tt repeat} modifying clauses on a loop.
\begin{verbatim}
for i in 1..10
    for j in 151..160 | odd? j
      while i + j < 160 repeat
        output [i,j]
 
   [1,151]
   [3,153]
\end{verbatim}
\returnType{Type: Void}

Here are useful rules for composing loop expressions:
\begin{enumerate}
\item {\tt while} predicates can only refer to variables that
are global (or in an outer scope)
or that are defined in {\tt for} clauses to the left of the
predicate.
\item A ``such that'' predicate (something following ``{\tt |}'')
must directly follow a {\tt for} clause and can only refer to
variables that are global (or in an outer scope)
or defined in the modified {\tt for} clause
or any {\tt for} clause to the left.
\end{enumerate}

\section{Creating Lists and Streams with Iterators}
\label{ugLangIts}

%Original Page 130

All of what we did for loops in 
\sectionref{ugLangLoops} \index{iteration}
can be transformed into expressions that create lists
\index{list!created by iterator} and streams.  \index{stream!created
by iterator} The {\tt repeat}, {\tt break} or {\tt iterate} words are not used but
all the other ideas carry over.  Before we give you the general rule,
here are some examples which give you the idea.

This creates a simple list of the integers from $1$ to $10$.
\spadcommand{list := [i for i in 1..10]}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10} 
\right]
$$
\returnType{Type: List PositiveInteger}

Create a stream of the integers greater than or equal to $1$.
\spadcommand{stream := [i for i in 1..]}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10},  \ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

This is a list of the prime integers between $1$ and $10$, inclusive.
\spadcommand{[i for i in 1..10 | prime? i]}
$$
\left[
2,  3,  5,  7 
\right]
$$
\returnType{Type: List PositiveInteger}

This is a stream of the prime integers greater than or equal to $1$.
\spadcommand{[i for i in 1..   | prime? i]}
$$
\left[
2,  3,  5,  7,  {11},  {13},  {17},  {19},  {23},  {29},  
\ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

This is a list of the integers between $1$ and $10$, inclusive, whose
squares are less than $700$.
\spadcommand{[i for i in 1..10 while i*i < 700]}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10} 
\right]
$$
\returnType{Type: List PositiveInteger}

This is a stream of the integers greater than or equal to $1$
whose squares are less than $700$.
\spadcommand{[i for i in 1..   while i*i < 700]}
$$
\left[
1,  2,  3,  4,  5,  6,  7,  8,  9,  {10},  \ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

Here is the general rule.
\index{collection}

\boxer{4.6in}{
The general syntax of a collection is
\begin{center}
{\tt [ {\it collectExpression} $\hbox{\it iterator}_{1}$  
$\hbox{\it iterator}_{2}$ \ldots $\hbox{\it iterator}_{N}$ ]}
\end{center}

where each $\hbox{\it iterator}_{i}$ is either a {\tt for} or a {\tt while}
clause.  The loop terminates immediately when the end test of any
$\hbox{\it iterator}_{i}$ succeeds or when a {\tt return} expression is
evaluated in {\it collectExpression}.  The value returned by the
collection is either a list or a stream of elements, one for each
iteration of the {\it collectExpression}.\\
}

%Original Page 131

Be careful when you use {\tt while} 
\index{stream!using while @{using {\tt while}}} 
to create a stream.  By default, Axiom tries to compute and
display the first ten elements of a stream.  If the {\tt while} condition
is not satisfied quickly, Axiom can spend a long (possibly infinite)
time trying to compute \index{stream!number of elements computed} the
elements.  Use {\tt )set streams calculate} to change the default to
something else.  \index{set streams calculate} This also affects the
number of terms computed and displayed for power series.  For the
purposes of this book, we have used this system command to display
fewer than ten terms.

Use nested iterators to create lists of \index{iteration!nested} lists
which can then be given as an argument to {\bf matrix}.
\spadcommand{matrix [ [x**i+j for i in 1..3] for j in 10..12]}
$$
\left[
\begin{array}{ccc}
{x+{10}} & {{x \sp 2}+{10}} & {{x \sp 3}+{10}} \\ 
{x+{11}} & {{x \sp 2}+{11}} & {{x \sp 3}+{11}} \\ 
{x+{12}} & {{x \sp 2}+{12}} & {{x \sp 3}+{12}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

You can also create lists of streams, streams of lists and streams of
streams.  Here is a stream of streams.
\spadcommand{[ [i/j for i in j+1..] for j in 1..]}
$$
\begin{array}{@{}l}
\left[
{\left[ 2,  3,  4,  5,  6,  7,  8,  9,  {10},  {11},  
\ldots 
\right]},
 {\left[ {\frac{3}{2}},  2,  {\frac{5}{2}},  3,  {\frac{7}{2}},  4,  
{\frac{9}{2}},  5,  {\frac{11}{2}},  6,  \ldots 
\right]},
\right.
\\
\\
\displaystyle
 {\left[ {\frac{4}{3}},  {\frac{5}{3}},  2,  {\frac{7}{3}},  {\frac{8}{3}}, 
 3,  {\frac{10}{3}},  {\frac{11}{3}},  4,  {\frac{13}{3}},  
\ldots 
\right]},
 {\left[ {\frac{5}{4}},  {\frac{3}{2}},  {\frac{7}{4}},  2,  {\frac{9}{4}}, 
 {\frac{5}{2}},  {\frac{11}{4}},  3,  {\frac{13}{4}},  {\frac{7}{2}}, 
 \ldots 
\right]},
\\
\\
\displaystyle
 {\left[ {\frac{6}{5}},  {\frac{7}{5}},  {\frac{8}{5}},  {\frac{9}{5}},  2, 
 {\frac{11}{5}},  {\frac{12}{5}},  {\frac{13}{5}},  {\frac{14}{5}}, 
 3,  \ldots 
\right]},
 {\left[ {\frac{7}{6}},  {\frac{4}{3}},  {\frac{3}{2}},  {\frac{5}{3}},  
{\frac{11}{6}},  2,  {\frac{13}{6}},  {\frac{7}{3}},  {\frac{5}{2}},  
{\frac{8}{3}},  \ldots 
\right]},
\\
\\
\displaystyle
 {\left[ {\frac{8}{7}},  {\frac{9}{7}},  {\frac{10}{7}},  {\frac{11}{7}}, 
 {\frac{12}{7}},  {\frac{13}{7}},  2,  {\frac{15}{7}},  {\frac{16}{7}},
 {\frac{17}{7}},  \ldots 
\right]},
 {\left[ {\frac{9}{8}},  {\frac{5}{4}},  {\frac{11}{8}},  {\frac{3}{2}},  
 {\frac{13}{8}},  {\frac{7}{4}},  {\frac{15}{8}},  2,  {\frac{17}{8}}, 
 {\frac{9}{4}},  \ldots 
\right]},
\\
\\
\displaystyle
 {\left[ {\frac{10}{9}},  {\frac{11}{9}},  {\frac{4}{3}},  {\frac{13}{9}},
 {\frac{14}{9}},  {\frac{5}{3}},  {\frac{16}{9}},  {\frac{17}{9}}, 
  2,  {\frac{19}{9}},  \ldots 
\right]},
\\
\\
\displaystyle
\left.
 {\left[ {\frac{11}{10}},  {\frac{6}{5}},  {\frac{13}{10}},  {\frac{7}{5}},
  {\frac{3}{2}},  {\frac{8}{5}},  {\frac{17}{10}}, {\frac{9}{5}},
  {\frac{19}{10}},  2,  \ldots 
\right]},
 \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream Stream Fraction Integer}

You can use parallel iteration across lists and streams to create
\index{iteration!parallel} new lists.
\spadcommand{[i/j for i in 3.. by 10 for j in 2..]}
$$
\left[
{\frac{3}{2}},  {\frac{13}{3}},  {\frac{23}{4}},  {\frac{33}{5}},  
{\frac{43}{6}},  {\frac{53}{7}},  {\frac{63}{8}},  {\frac{73}{9}},  
{\frac{83}{10}},  {\frac{93}{11}},  \ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

Iteration stops if the end of a list or stream is reached.
\spadcommand{[i**j for i in 1..7 for j in 2.. ]}
$$
\left[
1,  8,  {81},  {1024},  {15625},  {279936},  {5764801} 
\right]
$$
\returnType{Type: Stream Integer}

%or a while condition fails.
%\spadcommand{[i**j for i in 1..  for j in 2.. while i + j < 5 ]}
%tpdhere
%   There are no library operations named swhile 
%      Use HyperDoc Browse or issue
%                               )what op swhile
%      to learn if there is any operation containing " swhile " in its 
%      name.
% 
%   Cannot find a definition or applicable library operation named 
%      swhile with argument type(s) 
%     (Record(part1: PositiveInteger,part2: PositiveInteger) -> Boolean)
%     InfiniteTuple Record(part1: PositiveInteger,part2: PositiveInteger)
%      
%      Perhaps you should use "@" to indicate the required return type, 
%      or "$" to specify which version of the function you need.

As with loops, you can combine these modifiers to make very
complicated conditions.
\spadcommand{[ [ [i,j] for i in 10..15 | prime? i] for j in 17..22 | j = squareFreePart j]}
$$
\left[
{\left[ {\left[ {11},  {17} 
\right]},
 {\left[ {13},  {17} 
\right]}
\right]},
 {\left[ {\left[ {11},  {19} 
\right]},
 {\left[ {13},  {19} 
\right]}
\right]},
 {\left[ {\left[ {11},  {21} 
\right]},
 {\left[ {13},  {21} 
\right]}
\right]},
 {\left[ {\left[ {11},  {22} 
\right]},
 {\left[ {13},  {22} 
\right]}
\right]}
\right]
$$
\returnType{Type: List List List PositiveInteger}

%Original Page 132

See \domainref{List} and \domainref{Stream} 
for more information on creating and
manipulating lists and streams, respectively.

\section{An Example: Streams of Primes}
\label{ugLangStreamsPrimes}

We conclude this chapter with an example of the creation and
manipulation of infinite streams of prime integers.  This might be
useful for experiments with numbers or other applications where you
are using sequences of primes over and over again.  As for all
streams, the stream of primes is only computed as far out as you need.
Once computed, however, all the primes up to that point are saved for
future reference.

Two useful operations provided by the Axiom library are
\spadfunFrom{prime?}{IntegerPrimesPackage} and
\spadfunFrom{nextPrime}{IntegerPrimesPackage}.  A straight-forward way
to create a stream of prime numbers is to start with the stream of
positive integers $[2,..]$ and filter out those that are prime.

Create a stream of primes.
\spadcommand{primes : Stream Integer := [i for i in 2.. | prime? i]}
$$
\left[
2,  3,  5,  7,  {11},  {13},  {17},  {19},  {23},  {29},  
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

A more elegant way, however, is to use the
\spadfunFrom{generate}{Stream} operation from {\tt Stream}.  Given an
initial value $a$ and a function $f$, \spadfunFrom{generate}{Stream}
constructs the stream $[a, f(a), f(f(a)), ...]$.  This function gives
you the quickest method of getting the stream of primes.

This is how you use \spadfunFrom{generate}{Stream} to generate an
infinite stream of primes.
\spadcommand{primes := generate(nextPrime,2)}
$$
\left[
2,  3,  5,  7,  {11},  {13},  {17},  {19},  {23},  {29},  
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

Once the stream is generated, you might only be interested in primes
starting at a particular value.
\spadcommand{smallPrimes := [p for p in primes | p > 1000]}
$$
\left[
{1009},  {1013},  {1019},  {1021},  {1031},  {1033},  {1039},  
{1049},  {1051},  {1061},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Here are the first 11 primes greater than 1000.
\spadcommand{[p for p in smallPrimes for i in 1..11]}
$$
\left[
{1009},  {1013},  {1019},  {1021},  {1031},  {1033},  {1039},  
{1049},  {1051},  {1061},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Here is a stream of primes between 1000 and 1200.
\spadcommand{[p for p in smallPrimes while p < 1200]}
$$
\left[
{1009},  {1013},  {1019},  {1021},  {1031},  {1033},  {1039},  
{1049},  {1051},  {1061},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

To get these expanded into a finite stream, you call
\spadfunFrom{complete}{Stream} on the stream.
\spadcommand{complete \%}
$$
\left[
{1009},  {1013},  {1019},  {1021},  {1031},  {1033},  {1039},  
{1049},  {1051},  {1061},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

%Original Page 133

Twin primes are consecutive odd number pairs which are prime.
Here is the stream of twin primes.
\spadcommand{twinPrimes := [ [p,p+2] for p in primes | prime?(p + 2)]}
$$
\begin{array}{@{}l}
\left[
{\left[ 3,  5 \right]},
{\left[ 5,  7 \right]},
{\left[ {11},  {13} \right]},
{\left[ {17},  {19} \right]},
{\left[ {29},  {31} \right]},
{\left[ {41},  {43} \right]},
{\left[ {59},  {61} \right]},
{\left[ {71},  {73} \right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ {101},  {103} \right]},
{\left[ {107},  {109} \right]},
 \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream List Integer}

Since we already have the primes computed we can avoid the call to
\spadfunFrom{prime?}{IntegerPrimesPackage} by using a double
iteration.  This time we'll just generate a stream of the first of the
twin primes.
\spadcommand{firstOfTwins:= [p for p in primes for q in rest primes | q=p+2]}
$$
\left[
3,  5,  {11},  {17},  {29},  {41},  {59},  {71},  {101},  
{107},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Let's try to compute the infinite stream of triplet primes, the set of
primes $p$ such that $[p,p+2,p+4]$ are primes. For example, $[3,5,7]$
is a triple prime.  We could do this by a triple {\tt for} iteration.  A
more economical way is to use {\bf firstOfTwins}.  This time however,
put a semicolon at the end of the line.

Create the stream of {\bf firstTriplets}.  Put a semicolon at the end so
that no elements are computed.
\spadcommand{firstTriplets := [p for p in firstOfTwins for q in rest firstOfTwins | q = p+2];}
\returnType{Type: Stream Integer}

What happened?  As you know, by default Axiom displays the first ten
elements of a stream when you first display it.  And, therefore, it
needs to compute them!  If you want {\it no} elements computed, just
terminate the expression by a semicolon (``{\tt ;}'').  The semi-colon
prevents the display of the result of evaluating the expression.
Since no stream elements are needed for display (or anything else, so
far), none are computed.

Compute the first triplet prime.
\spadcommand{firstTriplets.1}
$$
3 
$$
\returnType{Type: PositiveInteger}

If you want to compute another, just ask for it.  But wait a second!
Given three consecutive odd integers, one of them must be divisible by
$3$. Thus there is only one triplet prime.  But suppose that you did not
know this and wanted to know what was the tenth triplet prime.
\begin{verbatim}
firstTriples.10
\end{verbatim}

To compute the tenth triplet prime, Axiom first must compute the
second, the third, and so on.  But since there isn't even a second
triplet prime, Axiom will compute forever.  Nonetheless, this effort
can produce a useful result.  After waiting a bit, hit \fbox{\bf Ctrl-c}.
The system responds as follows.

%Original Page 134

\begin{verbatim}
   >> System error:
   Console interrupt.
   You are being returned to the top level of
   the interpreter.
\end{verbatim}

If you want to know how many primes have been computed, type:
\begin{verbatim}
numberOfComputedEntries primes
\end{verbatim}

and, for this discussion, let's say that the result is $2045$.
How big is the $2045$-th prime?
\spadcommand{primes.2045}
$$
17837 
$$
\returnType{Type: PositiveInteger}

What you have learned is that there are no triplet primes between 5
and 17837.  Although this result is well known (some might even say
trivial), there are many experiments you could make where the result
is not known.  What you see here is a paradigm for testing of
hypotheses.  Here our hypothesis could have been: ``there is more than
one triplet prime.''  We have tested this hypothesis for 17837 cases.
With streams, you can let your machine run, interrupt it to see how
far it has progressed, then start it up and let it continue from where
it left off.

%\setcounter{chapter}{5}

%Original Page 135

\chapter{User-Defined Functions, Macros and Rules}
\label{ugUser}

In this chapter we show you how to write functions and macros,
and we explain how Axiom looks for and applies them.
We show some simple one-line examples of functions, together
with larger ones that are defined piece-by-piece or through the use of
piles.

\section{Functions vs. Macros}
\label{ugUserFunMac}

A function is a program to perform some \index{function!vs. macro}
computation.  \index{macro!vs. function} Most functions have names so
that it is easy to refer to them.  A simple example of a function is
one named \spadfunFrom{abs}{Integer} which computes the absolute value
of an integer.

This is a use of the ``absolute value'' library function for integers.
\spadcommand{abs(-8)}
$$
8 
$$
\returnType{Type: PositiveInteger}

This is an unnamed function that does the same thing, using the
``maps-to'' syntax {\tt +->} that we discuss in 
\sectionref{ugUserAnon}.
\spadcommand{(x +-> if x < 0 then -x else x)(-8)}
$$
8 
$$
\returnType{Type: PositiveInteger}

%Original Page 136

Functions can be used alone or serve as the building blocks for larger
programs.  Usually they return a value that you might want to use in
the next stage of a computation, but not always (for example, see
\domainref{Exit} and \domainref{Void}.
They may also read data from your
keyboard, move information from one place to another, or format and
display results on your screen.

In Axiom, as in mathematics, functions \index{function!parameters} are
usually parameterized.  Each time you {\it call} (some people say {\it
apply} or invoke) a function, you give \index{parameters to a
function} values to the parameters (variables).  Such a value is
called an {\it argument} of \index{function!arguments} the function.
Axiom uses the arguments for the computation.  In this way you get
different results depending on what you ``feed'' the function.

Functions can have local variables or refer to global variables in the
workspace.  Axiom can often compile functions so that they execute
very efficiently.  Functions can be passed as arguments to other
functions.

Macros are textual substitutions.  They are used to clarify the
meaning of constants or expressions and to be templates for frequently
used expressions.  Macros can be parameterized but they are not
objects that can be passed as arguments to functions.  In effect,
macros are extensions to the Axiom expression parser.

\section{Macros}
\label{ugUserMacros}

A {\it macro} provides general textual substitution of \index{macro}
an Axiom expression for a name.  You can think of a macro as being a
generalized abbreviation.  You can only have one macro in your
workspace with a given name, no matter how many arguments it has.

\boxer{4.6in}{
The two general forms for macros are
\begin{center}
{\tt macro} {\it name} {\tt ==} {\it body} \\
{\tt macro} {\it name(arg1,...)} {\tt ==} {\it body}
\end{center}
where the body of the macro can be any Axiom expression.\\
}

For example, suppose you decided that you like to use {\tt df} for 
{\tt D}.  You define the macro {\tt df} like this.
\spadcommand{macro df == D}
\returnType{Type: Void}

Whenever you type {\tt df}, the system expands it to {\tt D}.
\spadcommand{df(x**2 + x + 1,x)}
$$
{2 \  x}+1 
$$
\returnType{Type: Polynomial Integer}

%Original Page 137

Macros can be parameterized and so can be used for many different
kinds of objects.
\spadcommand{macro ff(x) == x**2 + 1}
\returnType{Type: Void}

Apply it to a number, a symbol, or an expression.
\spadcommand{ff z}
$$
{z \sp 2}+1 
$$
\returnType{Type: Polynomial Integer}

Macros can also be nested, but you get an error message if you
run out of space because of an infinite nesting loop.
\spadcommand{macro gg(x) == ff(2*x - 2/3)}
\returnType{Type: Void}

This new macro is fine as it does not produce a loop.
\spadcommand{gg(1/w)}
$$
\frac{{{13} \  {w \sp 2}} -{{24} \  w}+{36}}{9 \  {w \sp 2}} 
$$
\returnType{Type: Fraction Polynomial Integer}

This, however, loops since {\tt gg} is defined in terms of {\tt ff}.
\spadcommand{macro ff(x) == gg(-x)}
\returnType{Type: Void}

The body of a macro can be a block.
\spadcommand{macro next == (past := present; present := future; future := past + present)}
\returnType{Type: Void}

Before entering {\tt next}, we need values for {\tt present} and {\tt future}.
\spadcommand{present : Integer := 0}
$$
0 
$$
\returnType{Type: Integer}

\spadcommand{future : Integer := 1}
$$
1 
$$
\returnType{Type: Integer}

Repeatedly evaluating {\tt next} produces the next Fibonacci number.
\spadcommand{next}
$$
1 
$$
\returnType{Type: Integer}

And the next one.
\spadcommand{next}
$$
2 
$$
\returnType{Type: Integer}

%Original Page 138

Here is the infinite stream of the rest of the Fibonacci numbers.
\spadcommand{[next for i in 1..]}
$$
\left[
3,  5,  8,  {13},  {21},  {34},  {55},  {89},  {144},  
{233},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Bundle all the above lines into a single macro.
\begin{verbatim}
macro fibStream ==
  present : Integer := 1
  future : Integer := 1
  [next for i in 1..] where
    macro next ==
      past := present
      present := future
      future := past + present
\end{verbatim}
\returnType{Type: Void}

Use \spadfunFrom{concat}{Stream} to start with the first two
\index{Fibonacci numbers} Fibonacci numbers.
\spadcommand{concat([1,1],fibStream)}
$$
\left[
1, 1, 2, 3, 5, 8, {13}, {21}, {34}, {55}, 
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

The library operation {\bf fibonacci} is an easier way to compute
these numbers.

\spadcommand{[fibonacci i for i in 1..]}
$$
\left[
1,  1,  2,  3,  5,  8,  {13},  {21},  {34},  {55},  
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

\section{Introduction to Functions}
\label{ugUserIntro}

Each name in your workspace can refer to a single object.  This may be
any kind of object including a function.  You can use interactively
any function from the library or any that you define in the workspace.
In the library the same name can have very many functions, but you can
have only one function with a given name, although it can have any
number of arguments that you choose.

If you define a function in the workspace that has the same name and
number of arguments as one in the library, then your definition takes
precedence.  In fact, to get the library function you must
{\sl package-call} it (see \sectionref{ugTypesPkgCall}).

To use a function in Axiom, you apply it to its arguments.  Most
functions are applied by entering the name of the function followed by
its argument or arguments.
\spadcommand{factor(12)}
$$
{2 \sp 2} \  3 
$$
\returnType{Type: Factored Integer}

%Original Page 139

Some functions like ``{\tt +}'' have {\it infix} {\it operators} as names.
\spadcommand{3 + 4}
$$
7 
$$
\returnType{Type: PositiveInteger}

The function ``{\tt +}'' has two arguments.  When you give it more than
two arguments, Axiom groups the arguments to the left.  This
expression is equivalent to $(1 + 2) + 7$.
\spadcommand{1 + 2 + 7}
$$
10 
$$
\returnType{Type: PositiveInteger}

All operations, including infix operators, can be written in prefix
form, that is, with the operation name followed by the arguments in
parentheses.  For example, $2 + 3$ can alternatively be written as
$+(2,3)$.  But $+(2,3,4)$ is an error since {\tt +} takes only two
arguments.

Prefix operations are generally applied before the infix operation.\\
Thus the form ${\bf factorial\ } 3 + 1$ means ${\bf factorial}(3) + 1$
producing $7$, and $-2 + 5$ means $(-2) + 5$ producing $3$.  An
example of a prefix operator is prefix ``{\tt -}''.  For example, $- 2 +
5$ converts to $(- 2) + 5$ producing the value $3$.  Any prefix
function taking two arguments can be written in an infix manner by
putting an ampersand ``{\tt \&}'' before the name.  Thus ${\tt D}(2*x,x)$ can
be written as $2*x\ {\tt \&D}\ x$ returning $2$.

Every function in Axiom is identified by a {\it name} and 
{\it type}. (An exception is an ``anonymous function'' discussed in
\sectionref{ugUserAnon}.)
The type of a function is always a mapping of the
form \spadsig{Source}{Target} where {\tt Source} and {\tt Target} are types.
To enter a type from the keyboard, enter the arrow by using a hyphen
``{\tt -}'' followed by a greater-than sign ``{\tt >}'', e.g. 
{\tt Integer -> Integer}.

Let's go back to ``{\tt +}''.  There are many ``{\tt +}'' functions in the
Axiom library: one for integers, one for floats, another for rational
numbers, and so on.  These ``{\tt +}'' functions have different types and
thus are different functions.  You've seen examples of this 
{\it overloading} before---using the same name for different functions.
Overloading is the rule rather than the exception.  You can add two
integers, two polynomials, two matrices or two power series.  These
are all done with the same function name but with different functions.

%Original Page 140

\section{Declaring the Type of Functions}
\label{ugUserDeclare}

In \sectionref{ugTypesDeclare} we discussed
how to declare a variable to restrict the kind of values that can be
assigned to it.  In this section we show how to declare a variable
that refers to function objects.

\boxer{4.6in}{
A function is an object of type
\begin{center}
{\sf Source $\rightarrow$ Type}
\end{center}

where {\tt Source} and {\tt Target} can be any type.  A common type
for {\tt Source} is {\tt Tuple}($\hbox{\it T}_{1}$, \ldots, 
$\hbox{\it T}_{n}$), usually written ($\hbox{\it T}_{1}$, \ldots, 
$\hbox{\it T}_{n}$), to indicate a function of $n$ arguments.\\
}

If $g$ takes an {\tt Integer}, a {\tt Float} and another {\tt Integer}, 
and returns a {\tt String}, the declaration is written:
\spadcommand{g: (Integer,Float,Integer) -> String}
\returnType{Type: Void}

The types need not be written fully; using abbreviations, the above
declaration is:
\spadcommand{g: (INT,FLOAT,INT) -> STRING}
\returnType{Type: Void}

It is possible for a function to take no arguments.  If $ h$ takes no
arguments but returns a {\tt Polynomial} {\tt Integer}, any of the
following declarations is acceptable.
\spadcommand{h: () -> POLY INT}
\returnType{Type: Void}

\spadcommand{h: () -> Polynomial INT}
\returnType{Type: Void}

\spadcommand{h: () -> POLY Integer}
\returnType{Type: Void}

\boxer{4.6in}{
Functions can also be declared when they are being defined.
The syntax for combined declaration/definition is:
\begin{center}
\frenchspacing{\tt {\it functionName}($\hbox{\it parm}_{1}$: 
$\hbox{\it parmType}_{1}$, \ldots, $\hbox{\it parm}_{N}$: 
$\hbox{\it parmType}_{N}$): {\it functionReturnType}}
\end{center}
{\ }%force a blank line 
}

The following definition fragments show how this can be done for
the functions $g$ and $h$ above.
\begin{verbatim}
g(arg1: INT, arg2: FLOAT, arg3: INT): STRING == ...

h(): POLY INT == ...
\end{verbatim}

%Original Page 141

A current restriction on function declarations is that they must
involve fully specified types (that is, cannot include modes involving
explicit or implicit ``{\tt ?}'').  For more information on declaring
things in general, see \sectionref{ugTypesDeclare}.

\section{One-Line Functions}
\label{ugUserOne}

As you use Axiom, you will find that you will write many short
functions \index{function!one-line definition} to codify sequences of
operations that you often perform.  In this section we write some
simple one-line functions.

This is a simple recursive factorial function for positive integers.
\spadcommand{fac n == if n < 3 then n else n * fac(n-1)}
\returnType{Type: Void}

\spadcommand{fac 10}
$$
3628800 
$$
\returnType{Type: PositiveInteger}

This function computes $1 + 1/2 + 1/3 + ... + 1/n$.
\spadcommand{s n == reduce(+,[1/i for i in 1..n])}
\returnType{Type: Void}

\spadcommand{s 50}
$$
\frac{13943237577224054960759}{3099044504245996706400} 
$$
\returnType{Type: Fraction Integer}

This function computes a Mersenne number, several of which are prime.
\index{Mersenne number}
\spadcommand{mersenne i == 2**i - 1}
\returnType{Type: Void}

If you type {\tt mersenne}, Axiom shows you the function definition.
\spadcommand{mersenne}
$$
mersenne \  i \  == \  {{2 \sp i} -1} 
$$
\returnType{Type: FunctionCalled mersenne}

Generate a stream of Mersenne numbers.
\spadcommand{[mersenne i for i in 1..]}
$$
\left[
1,  3,  7,  {15},  {31},  {63},  {127},  {255},  {511},  
{1023},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

%Original Page 142

Create a stream of those values of $i$ such that {\tt mersenne(i)} is prime.
\spadcommand{mersenneIndex := [n for n in 1.. | prime?(mersenne(n))]}
\begin{verbatim}
   Compiling function mersenne with type PositiveInteger -> Integer 
\end{verbatim}
$$
\left[
2,  3,  5,  7,  {13},  {17},  {19},  {31},  {61},  {89},  
\ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

Finally, write a function that returns the $n$-th Mersenne prime.
\spadcommand{mersennePrime n == mersenne mersenneIndex(n)}
\returnType{Type: Void}

\spadcommand{mersennePrime 5}
$$
8191 
$$
\returnType{Type: PositiveInteger}

\section{Declared vs. Undeclared Functions}
\label{ugUserDecUndec}

If you declare the type of a function, you can apply it to any data
that can be converted to the source type of the function.

Define {\bf f} with type {\sf Integer $\rightarrow$ Integer}.
\spadcommand{f(x: Integer): Integer == x + 1}
\begin{verbatim}
   Function declaration f : Integer -> Integer has been added to 
      workspace.
\end{verbatim}
\returnType{Type: Void}

The function {\bf f} can be applied to integers, \ldots
\spadcommand{f 9}
\begin{verbatim}
   Compiling function f with type Integer -> Integer 
\end{verbatim}
$$
10 
$$
\returnType{Type: PositiveInteger}

and to values that convert to integers, \ldots
\spadcommand{f(-2.0)}
$$
-1 
$$
\returnType{Type: Integer}

but not to values that cannot be converted to integers.
\spadcommand{f(2/3)}
\begin{verbatim}
   Conversion failed in the compiled user function f .
 
   Cannot convert from type Fraction Integer to Integer for value
   2
   -
   3
\end{verbatim}

To make the function over a wide range of types, do not declare its type.

%Original Page 143

Give the same definition with no declaration.
\spadcommand{g x == x + 1}
\returnType{Type: Void}

If $x + 1$ makes sense, you can apply {\bf g} to $x$.
\spadcommand{g 9}
\begin{verbatim}
   Compiling function g with type PositiveInteger -> PositiveInteger 
\end{verbatim}
$$
10 
$$
\returnType{Type: PositiveInteger}

A version of {\bf g} with different argument types get compiled for
each new kind of argument used.
\spadcommand{g(2/3)}
\begin{verbatim}
   Compiling function g with type Fraction Integer -> Fraction Integer 
\end{verbatim}
$$
\frac{5}{3}
$$
\returnType{Type: Fraction Integer}

Here $x+1$ for $x = ``axiom''$ makes no sense.
\spadcommand{g("axiom")}
\begin{verbatim}
   There are 11 exposed and 5 unexposed library operations named + 
      having 2 argument(s) but none was determined to be applicable. 
      Use HyperDoc Browse, or issue
                                )display op +
      to learn more about the available operations. Perhaps 
      package-calling the operation or using coercions on the arguments
      will allow you to apply the operation.
   Cannot find a definition or applicable library operation named + 
      with argument type(s) 
                                   String
                               PositiveInteger
      
      Perhaps you should use "@" to indicate the required return type, 
      or "$" to specify which version of the function you need.
   Axiom will attempt to step through and interpret the code.
   There are 11 exposed and 5 unexposed library operations named + 
      having 2 argument(s) but none was determined to be applicable. 
      Use HyperDoc Browse, or issue
                                )display op +
      to learn more about the available operations. Perhaps 
      package-calling the operation or using coercions on the arguments
      will allow you to apply the operation.
 
   Cannot find a definition or applicable library operation named + 
      with argument type(s) 
                                   String
                               PositiveInteger
      
      Perhaps you should use "@" to indicate the required return type, 
      or "$" to specify which version of the function you need.
\end{verbatim}

As you will see in \sectionref{ugCategories}, 
Axiom has a formal idea of categories for what ``makes sense.''

\section{Functions vs. Operations}
\label{ugUserDecOpers}

A function is an object that you can create, manipulate, pass to, and
return from functions (for some interesting examples of library
functions that manipulate functions, see \domainref{MappingPackage1}.
Yet, we often seem to use
the term {\it operation} and {\it function} interchangeably in Axiom.  What
is the distinction?

First consider values and types associated with some variable $n$ in
your workspace.  You can make the declaration {\tt n : Integer}, then
assign $n$ an integer value.  You then speak of the integer $n$.
However, note that the integer is not the name $n$ itself, but the
value that you assign to $n$.

%Original Page 144

Similarly, you can declare a variable $f$ in your workspace to have
type {\sf Integer $\rightarrow$ Integer}, then assign $f$, through a
definition or an assignment of an anonymous function.  You then speak
of the function $f$.  However, the function is not $f$, but the value
that you assign to $f$.

A function is a value, in fact, some machine code for doing something.
Doing what?  Well, performing some {\it operation}.  Formally, an
operation consists of the constituent parts of $f$ in your workspace,
excluding the value; thus an operation has a name and a type.  An
operation is what domains and packages export.  Thus {\tt Ring}
exports one operation ``{\tt +}''.  Every ring also exports this
operation.  Also, the author of every ring in the system is obliged
under contract (see \sectionref{ugPackagesAbstract} 
to provide an implementation for this operation.

This chapter is all about functions---how you create them
interactively and how you apply them to meet your needs.  In 
\sectionref{ugPackages} you will learn how to
create them for the Axiom library.  Then in \sectionref{ugCategories},
you will learn about categories and exported operations.

\section{Delayed Assignments vs. Functions with No Arguments}
\label{ugUserDelay}

In \sectionref{ugLangAssign} we discussed the
difference between immediate and \index{function!with no arguments}
delayed assignments.  In this section we show the difference between
delayed assignments and functions of no arguments.

A function of no arguments is sometimes called a {\it nullary function.}
\spadcommand{sin24() == sin(24.0)}
\returnType{Type: Void}

You must use the parentheses ``{\tt ()}'' to evaluate it.  Like a
delayed assignment, the right-hand-side of a function evaluation is
not evaluated until the left-hand-side is used.
\spadcommand{sin24()}
\begin{verbatim}
   Compiling function sin24 with type () -> Float 
\end{verbatim}
$$
-{0.9055783620\ 0662384514} 
$$
\returnType{Type: Float}

If you omit the parentheses, you just get the function definition.
\spadcommand{sin24}
$$
sin24 \  {\left( 
\right)}
\  == \  {\sin 
\left(
{{24.0}} 
\right)}
$$
\returnType{Type: FunctionCalled sin24}

You do not use the parentheses ``{\tt ()}'' in a delayed assignment\ldots

\spadcommand{cos24 == cos(24.0)}
\returnType{Type: Void}

%Original Page 145

nor in the evaluation.

\spadcommand{cos24}
\begin{verbatim}
   Compiling body of rule cos24 to compute value of type Float 
\end{verbatim}
$$
0.4241790073\ 3699697594 
$$
\returnType{Type: Float}

The only syntactic difference between delayed assignments
and nullary functions is that you use ``{\tt ()}'' in the latter case.

\section{How Axiom Determines What Function to Use}
\label{ugUserUse}

What happens if you define a function that has the same name as a
library function?  Well, if your function has the same name and number
of arguments (we sometimes say {\it arity}) as another function in the
library, then your function covers up the library function.  If you
want then to call the library function, you will have to {\sl package-call}
it.  Axiom can use both the functions you write and those that come
from the library.  Let's do a simple example to illustrate this.

Suppose you (wrongly!) define {\bf sin} in this way.
\spadcommand{sin x == 1.0}
\returnType{Type: Void}

The value $1.0$ is returned for any argument.
\spadcommand{sin 4.3}
\begin{verbatim}
   Compiling function sin with type Float -> Float 
\end{verbatim}
$$
1.0 
$$
\returnType{Type: Float}

If you want the library operation, we have to package-call it
(see \sectionref{ugTypesPkgCall} for more information).
\spadcommand{sin(4.3)\$Float}
$$
-{0.9161659367 4945498404} 
$$
\returnType{Type: Float}

\spadcommand{sin(34.6)\$Float}
$$
-{0.0424680347 1695010154 3} 
$$
\returnType{Type: Float}

Even worse, say we accidentally used the same name as a library
function in the function.
\spadcommand{sin x == sin x}
\begin{verbatim}
   Compiled code for sin has been cleared.
   1 old definition(s) deleted for function or rule sin 
\end{verbatim}
\returnType{Type: Void}

Then Axiom definitely does not understand us.
\spadcommand{sin 4.3}
\begin{verbatim}
Axiom cannot determine the type of sin because it cannot analyze 
   the non-recursive part, if that exists. This may be remedied 
   by declaring the function.
\end{verbatim}

%Original Page 146

Again, we could package-call the inside function.
\spadcommand{sin x == sin(x)\$Float}
\begin{verbatim}
   1 old definition(s) deleted for function or rule sin 
\end{verbatim}
\returnType{Type: Void}

\spadcommand{sin 4.3}
\begin{verbatim}
   Compiling function sin with type Float -> Float 

+++ |*1;sin;1;G82322| redefined
\end{verbatim}
$$
-{0.9161659367 4945498404} 
$$
\returnType{Type: Float}

Of course, you are unlikely to make such obvious errors.  It is more
probable that you would write a function and in the body use a
function that you think is a library function.  If you had also
written a function by that same name, the library function would be
invisible.

How does Axiom determine what library function to call?  It very much
depends on the particular example, but the simple case of creating the
polynomial $x + 2/3$ will give you an idea.
\begin{enumerate}
\item The $x$ is analyzed and its default type is
{\tt Variable(x)}.
\item The $2$ is analyzed and its default type is
{\tt PositiveInteger}.
\item The $3$ is analyzed and its default type is
{\tt PositiveInteger}.
\item Because the arguments to ``{\tt /}'' are integers, Axiom
gives the expression $2/3$ a default target type of
{\tt Fraction(Integer)}.
\item Axiom looks in {\tt PositiveInteger} for ``{\tt /}''.
It is not found.
\item Axiom looks in {\tt Fraction(Integer)} for ``{\tt /}''.
It is found for arguments of type {\tt Integer}.
\item The $2$ and $3$ are converted to objects of type
{\tt Integer} (this is trivial) and ``{\tt /}'' is applied,
creating an object of type {\tt Fraction(Integer)}.
\item No ``{\tt +}'' for arguments of types {\tt Variable(x)} and
{\tt Fraction(Integer)} are found in either domain.
\item Axiom resolves
\index{resolve}
(see \sectionref{ugTypesResolve})
the types and gets \\
{\tt Polynomial(Fraction(Integer))}.
\item The $x$ and the $2/3$ are converted to objects of this
type and {\tt +} is applied, yielding the answer, an object of type
{\tt Polynomial (Fraction (Integer))}.
\end{enumerate}

\section{Compiling vs. Interpreting}
\label{ugUserCompInt}

When possible, Axiom completely determines the type of every object in
a function, then translates the function definition to Common Lisp or
to machine code (see the next section).  This translation,
\index{function!compiler} called compilation, happens the first time
you call the function and results in a computational delay.
Subsequent function calls with the same argument types use the
compiled version of the code without delay.

%Original Page 147

If Axiom cannot determine the type of everything, the function may
still be executed \index{function!interpretation} but
\index{interpret-code mode} in interpret-code mode: each statement in
the function is analyzed and executed as the control flow indicates.
This process is slower than executing a compiled function, but it
allows the execution of code that may involve objects whose types
change.

\boxer{4.6in}{
If Axiom decides that it cannot compile the code, it issues a message
stating the problem and then the following message:
\begin{center}
{\bf We will attempt to step through and interpret the code.}
\end{center}

This is not a time to panic.  \index{panic!avoiding} Rather, it just
means that what you gave to Axiom is somehow ambiguous: either it is
not specific enough to be analyzed completely, or it is beyond Axiom's
present interactive compilation abilities.\\
}

This function runs in interpret-code mode, but it does not compile.
\begin{verbatim}
varPolys(vars) ==
  for var in vars repeat
    output(1 :: UnivariatePolynomial(var,Integer))
\end{verbatim}
\returnType{Type: Void}

For $vars$ equal to $['x, 'y, 'z]$, this function displays $1$ three times.
\spadcommand{varPolys ['x,'y,'z]}
\begin{verbatim}
Cannot compile conversion for types involving local variables. 
   In particular, could not compile the expression involving :: 
   UnivariatePolynomial(var,Integer) 
 Axiom will attempt to step through and interpret the code.
 1
 1
 1
\end{verbatim}
\returnType{Type: Void}

The type of the argument to {\bf output} changes in each iteration, so
Axiom cannot compile the function.  In this case, even the inner loop
by itself would have a problem:
\begin{verbatim}
for var in ['x,'y,'z] repeat
  output(1 :: UnivariatePolynomial(var,Integer))
\end{verbatim}
\begin{verbatim}
Cannot compile conversion for types involving local variables. 
   In particular, could not compile the expression involving :: 
   UnivariatePolynomial(var,Integer) 
 Axiom will attempt to step through and interpret the code.
 1
 1
 1
\end{verbatim}
\returnType{Type: Void}

%Original Page 148

Sometimes you can help a function to compile by using an extra
conversion or by using $pretend$.  \index{pretend} See
\sectionref{ugTypesSubdomains} for details.

When a function is compilable, you have the choice of whether it is
compiled to Common Lisp and then interpreted by the Common Lisp
interpreter or then further compiled from Common Lisp to machine code.
\index{machine code} The option is controlled via 
{\tt )set functions compile}.  
\index{set function compile} Issue {\tt )set functions compile on} 
to compile all the way to machine code.  With the default
setting {\tt )set functions compile off}, Axiom has its Common Lisp
code interpreted because the overhead of further compilation is larger
than the run-time of most of the functions our users have defined.
You may find that selectively turning this option on and off will
\index{performance} give you the best performance in your particular
application.  For example, if you are writing functions for graphics
applications where hundreds of points are being computed, it is almost
certainly true that you will get the best performance by issuing 
{\tt )set functions compile on}.

\section{Piece-Wise Function Definitions}
\label{ugUserPiece}

To move beyond functions defined in one line, we introduce in this
section functions that are defined piece-by-piece.  That is, we say
``use this definition when the argument is such-and-such and use this
other definition when the argument is that-and-that.''

\subsection{A Basic Example}
\label{ugUserPieceBasic}

There are many other ways to define a factorial function for
nonnegative integers.  You might 
\index{function!piece-wise definition} 
say \index{piece-wise function definition} factorial of
$0$ is $1$, otherwise factorial of $n$ is $n$ times factorial of
$n-1$.  Here is one way to do this in Axiom.

Here is the value for $n = 0$.
\spadcommand{fact(0) == 1}
\returnType{Type: Void}

Here is the value for $n > 0$.  The vertical bar ``{\tt |}'' means ``such
that''. \index{such that}
\spadcommand{fact(n | n > 0) == n * fact(n - 1)}
\returnType{Type: Void}

What is the value for $n = 7$?
\spadcommand{fact(7)}
\begin{verbatim}
   Compiling function fact with type Integer -> Integer 
   Compiling function fact as a recurrence relation.
\end{verbatim}
$$
5040
$$
\returnType{Type: PositiveInteger}

What is the value for $n = -3$?
\spadcommand{fact(-3)}
\begin{verbatim}
   You did not define fact for argument -3 .
\end{verbatim}

%Original Page 149

Now for a second definition.  Here is the value for $n = 0$.
\spadcommand{facto(0) == 1}
\returnType{Type: Void}

Give an error message if $n < 0$.
\spadcommand{facto(n | n < 0) == error "arguments to facto must be non-negative"}
\returnType{Type: Void}

Here is the value otherwise.
\spadcommand{facto(n) == n * facto(n - 1)}
\returnType{Type: Void}

What is the value for $n = 7$?
\spadcommand{facto(3)}
\begin{verbatim}
   Compiling function facto with type Integer -> Integer 
\end{verbatim}
$$
6 
$$
\returnType{Type: PositiveInteger}

What is the value for $n = -7$?
\spadcommand{facto(-7)}
\begin{verbatim}
   Error signalled from user code in function facto: 
      arguments to facto must be non-negative
\end{verbatim}
\returnType{Type: PositiveInteger}

To see the current piece-wise definition of a function, use 
{\tt )display value}.
\spadcommand{)display value facto}
\begin{verbatim}
   Definition:
     facto 0 == 1
     facto (n | n < 0) == 
       error(arguments to facto must be non-negative)
     facto n == n facto(n - 1)
\end{verbatim}

In general a {\it piece-wise definition} of a function consists of two
or more parts.  Each part gives a ``piece'' of the entire definition.
Axiom collects the pieces of a function as you enter them.  When you
ask for a value of the function, it then ``glues'' the pieces together
to form a function.

The two piece-wise definitions for the factorial function are examples
of recursive functions, that is, functions that are defined in terms
of themselves.  Here is an interesting doubly-recursive function.
This function returns the value $11$ for all positive integer
arguments.

Here is the first of two pieces.
\spadcommand{eleven(n | n < 1) == n + 11}
\returnType{Type: Void}

%Original Page 150

And the general case.
\spadcommand{eleven(m) == eleven(eleven(m - 12))}
\returnType{Type: Void}

Compute $elevens$, the infinite stream of values of $eleven$.
\spadcommand{elevens := [eleven(i) for i in 0..]}
$$
\left[
{11},  {11},  {11},  {11},  {11},  {11},  {11},  {11},  {11}, 
 {11},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

What is the value at $n = 200$?
\spadcommand{elevens 200}
$$
11 
$$
\returnType{Type: PositiveInteger}

What is the Axiom's definition of $eleven$?
\spadcommand{)display value eleven}
\begin{verbatim}
   Definition:
     eleven (m | m < 1) == m + 11
     eleven m == eleven(eleven(m - 12))
\end{verbatim}

\subsection{Picking Up the Pieces}
\label{ugUserPiecePicking}

Here are the details about how Axiom creates a function from its
pieces.  Axiom converts the $i$-th piece of a function definition
into a conditional expression of the form: 
{\tt if} $\hbox{\it pred}_{i}$ {\tt then} $\hbox{\it expression}_{i}$.  
If any new piece has a $\hbox{\it pred}_{i}$ that is 
identical (after all variables are uniformly named) to 
an earlier $\hbox{\it pred}_{j}$, the earlier piece is removed.  
Otherwise, the new piece is always added at the end.

\boxer{4.6in}{
If there are $n$ pieces to a function definition for $f$, the function
defined $f$ is: \newline
\hspace*{3pc}
{\tt if} $\hbox{\it pred}_{1}$ {\tt then} $\hbox{\it expression}_{1}$ {\tt else}\newline
\hspace*{6pc}. . . \newline
\hspace*{3pc}
{\tt if} $\hbox{\it pred}_{n}$ {\tt then} $\hbox{\it expression}_{n}$ {\tt else}\newline
\hspace*{3pc}
{\tt  error "You did not define f for argument <arg>."}\\
}

You can give definitions of any number of mutually recursive function
definitions, piece-wise or otherwise.  No computation is done until
you ask for a value.  When you do ask for a value, all the relevant
definitions are gathered, analyzed, and translated into separate
functions and compiled.

Let's recall the definition of {\bf eleven} from
the previous section. 
\spadcommand{eleven(n | n < 1) == n + 11}
\returnType{Type: Void}

%Original Page 151

\spadcommand{eleven(m) == eleven(eleven(m - 12))}
\returnType{Type: Void}

A similar doubly-recursive function below produces $-11$ for all
negative positive integers.  If you haven't worked out why or how 
{\bf eleven} works, the structure of this definition gives a clue.

This definition we write as a block.
\begin{verbatim}
minusEleven(n) ==
  n >= 0 => n - 11
  minusEleven (5 + minusEleven(n + 7))
\end{verbatim}
\returnType{Type: Void}

Define $s(n)$ to be the sum of plus and minus ``eleven'' functions
divided by $n$.  Since $11 - 11 = 0$, we define $s(0)$ to be $1$.
\spadcommand{s(0) == 1}
\returnType{Type: Void}

And the general term.
\spadcommand{s(n) == (eleven(n) + minusEleven(n))/n}
\returnType{Type: Void}

What are the first ten values of $s$?
\spadcommand{[s(n) for n in 0..]}
$$
\left[
1, 1, 1, 1, 1, 1, 1, 1, 1, 1, \ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

%% interpreter puts the rule at the end - should fix

% Oops! Evidently $s(0)$ should be $1$.
% Let's check the current definition of {\bf s} using {\tt )display}.

% \spadcommand{)display value s}

% Change the value at $n = 0$.

% \spadcommand{s(0) == 1}

% Now, what is the definition of {\bf s}?
% Note: {\it you can only replace a given piece if you give exactly the same
% predicate!}

% \spadcommand{)display value s}

Axiom can create infinite streams in the positive direction (for
example, for index values $0,1, \ldots$) or negative direction (for
example, for $0,-1,-2, \ldots$).  Here we would like a
stream of values of $s(n)$ that is infinite in both directions.  The
function $t(n)$ below returns the $n$-th term of the infinite stream 
$$[s(0), s(1), s(-1), s(2), s(-2), \ldots]$$ 
Its definition has three pieces.

Define the initial term.
\spadcommand{t(1) == s(0)}
\returnType{Type: Void}

The even numbered terms are the $s(i)$ for positive $i$.  We use
``{\tt quo}'' rather than ``{\tt /}'' since we want the result to be
an integer.

\spadcommand{t(n | even?(n)) == s(n quo 2)}
\returnType{Type: Void}

%Original Page 152

Finally, the odd numbered terms are the $s(i)$ for negative $i$.  In
piece-wise definitions, you can use different variables to define
different pieces. Axiom will not get confused.
\spadcommand{t(p) == s(- p quo 2)}
\returnType{Type: Void}

Look at the definition of $t$.  In the first piece, the variable $n$
was used; in the second piece, $p$.  Axiom always uses your last
variable to display your definitions back to you.
\spadcommand{)display value t}
\begin{verbatim}
   Definition:
     t 1 == s(0)
     t (p | even?(p)) == s(p quo 2)
     t p == s(- p quo 2)
\end{verbatim}

Create a series of values of $s$ applied to
alternating positive and negative arguments.
\spadcommand{[t(i) for i in 1..]}
\begin{verbatim}
   Compiling function s with type Integer -> Fraction Integer 
   Compiling function t with type PositiveInteger -> Fraction Integer 
\end{verbatim}
$$
\left[
1, 1, 1, 1, 1, 1, 1, 1, 1, 1, \ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

Evidently $t(n) = 1$ for all $i$. Check it at $n= 100$. 

\spadcommand{t(100)}
$$
1 
$$
\returnType{Type: Fraction Integer}

\subsection{Predicates}
\label{ugUserPiecePred}

We have already seen some examples of \index{function!predicate}
predicates \index{predicate!in function definition}
(\sectionref{ugUserPieceBasic}.
Predicates are {\tt Boolean}-valued expressions and Axiom uses them
for filtering collections (see \sectionref{ugLangIts}
and for placing constraints on function
arguments.  In this section we discuss their latter usage.

The simplest use of a predicate is one you don't see at all.
\spadcommand{opposite 'right == 'left}
\returnType{Type: Void}

Here is a longer way to give the ``opposite definition.''
\spadcommand{opposite (x | x = 'left) == 'right}
\returnType{Type: Void}

Try it out.
\spadcommand{for x in ['right,'left,'inbetween] repeat output opposite x}
\begin{verbatim}
Compiling function opposite with type 
   OrderedVariableList [right, left,inbetween] -> Symbol    
 left
 right
 
The function opposite is not defined for the given argument(s).
\end{verbatim}

%Original Page 153

Explicit predicates tell Axiom that the given function definition
piece is to be applied if the predicate evaluates to {\tt true} for
the arguments to the function.  You can use such ``constant''
arguments for integers, \index{function!constant argument} strings,
and quoted symbols.  \index{constant function argument} The {\tt
Boolean} values {\tt true} and {\tt false} can also be used if qualified with
``$@$'' or ``$\$$'' and {\tt Boolean}.  The following are all valid
function definition fragments using constant arguments.
\begin{verbatim}
a(1) == ...
b("unramified") == ...
c('untested) == ...
d(true@Boolean) == ...
\end{verbatim}

If a function has more than one argument, each argument can have its
own predicate.  However, if a predicate involves two or more
arguments, it must be given {\it after} all the arguments mentioned in
the predicate have been given.  You are always safe to give a single
predicate at the end of the argument list.

A function involving predicates on two arguments.
\spadcommand{inFirstHalfQuadrant(x | x > 0,y | y < x) == true}
\returnType{Type: Void}

This is incorrect as it gives a predicate on $y$ before the argument
$y$ is given.
\spadcommand{inFirstHalfQuadrant(x | x > 0 and y < x,y) == true}
\begin{verbatim}
   1 old definition(s) deleted for function or rule inFirstHalfQuadrant
\end{verbatim}
\returnType{Type: Void}

It is always correct to write the predicate at the end.
\spadcommand{inFirstHalfQuadrant(x,y | x > 0 and y < x) == true}
\begin{verbatim}
   1 old definition(s) deleted for function or rule inFirstHalfQuadrant
\end{verbatim}
\returnType{Type: Void}

Here is the rest of the definition.
\spadcommand{inFirstHalfQuadrant(x,y) == false}
\returnType{Type: Void}

Try it out.
\spadcommand{[inFirstHalfQuadrant(i,3) for i in 1..5]}
\begin{verbatim}
   Compiling function inFirstHalfQuadrant with type (PositiveInteger,
      PositiveInteger) -> Boolean 
\end{verbatim}
$$
\left[
{\tt false},  {\tt false},  {\tt false},  {\tt true},  {\tt true} 
\right]
$$
\returnType{Type: List Boolean}

\section{Caching Previously Computed Results}
\label{ugUserCache}

By default, Axiom does not save the values of any function.
\index{function!caching values} You can cause it to save values and
not to recompute unnecessarily \index{remembering function values} by
using {\tt )set functions cache}.  \index{set functions cache} This
should be used before the functions are defined or, at least, before
they are executed.  The word following ``cache'' should be $0$ to turn
off caching, a positive integer $n$ to save the last $n$ computed
values or ``all'' to save all computed values.  If you then give a
list of names of functions, the caching only affects those functions.
Use no list of names or ``all'' when you want to define the default
behavior for functions not specifically mentioned in other 
{\tt )set functions cache} statements.  If you give no list of names, all
functions will have the caching behavior.  If you explicitly turn on
caching for one or more names, you must explicitly turn off caching
for those names when you want to stop saving their values.

%Original Page 154

This causes the functions {\bf f} and {\bf g} to have the last three
computed values saved.
\spadcommand{)set functions cache 3 f g}
\begin{verbatim}
   function f will cache the last 3 values.
   function g will cache the last 3 values.
\end{verbatim}

This is a sample definition for {\bf f}.
\spadcommand{f x == factorial(2**x)}
\returnType{Type: Void}

A message is displayed stating what {\bf f} will cache.
\spadcommand{f(4)}
\begin{verbatim}
   Compiling function f with type PositiveInteger -> Integer 
   f will cache 3 most recently computed value(s).

+++ |*1;f;1;G82322| redefined
\end{verbatim}
$$
20922789888000 
$$
\returnType{Type: PositiveInteger}

This causes all other functions to have all computed values saved by default.
\spadcommand{)set functions cache all}
\begin{verbatim}
   In general, interpreter functions will cache all values.
\end{verbatim}

This causes all functions that have not been specifically cached in some way
to have no computed values saved.
\spadcommand{)set functions cache 0}
\begin{verbatim}
 In general, functions will cache no returned values.
\end{verbatim}

We also make {\bf f} and {\bf g} uncached.
\spadcommand{)set functions cache 0 f g}
\begin{verbatim}
   Caching for function f is turned off
   Caching for function g is turned off
\end{verbatim}

\boxer{4.6in}{
Be careful about caching functions that have side effects.  Such a
function might destructively modify the elements of an array or issue
a {\bf draw} command, for example.  A function that you expect to
execute every time it is called should not be cached.  Also, it is
highly unlikely that a function with no arguments should be cached.\\
}

You should also be careful about caching functions that depend on free
variables.  See \sectionref{ugUserFreeLocal} for an example.

%Original Page 155

\section{Recurrence Relations}
\label{ugUserRecur}

One of the most useful classes of function are those defined via a
``recurrence relation.''  A {\it recurrence relation} makes each
successive \index{recurrence relation} value depend on some or all of
the previous values.  A simple example is the ordinary ``factorial'' function:
\begin{verbatim}
fact(0) == 1
fact(n | n > 0) == n * fact(n-1)
\end{verbatim}

The value of $fact(10)$ depends on the value of $fact(9)$, $fact(9)$
on $fact(8)$, and so on.  Because it depends on only one previous
value, it is usually called a {\it first order recurrence relation.}
You can easily imagine a function based on two, three or more previous
values.  The Fibonacci numbers are probably the most famous function
defined by a \index{Fibonacci numbers} second order recurrence relation.

The library function {\bf fibonacci} computes Fibonacci numbers.
It is obviously optimized for speed.
\spadcommand{[fibonacci(i) for i in 0..]}
$$
\left[
0,  1,  1,  2,  3,  5,  8,  {13},  {21},  {34},  \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Define the Fibonacci numbers ourselves using a piece-wise definition.
\spadcommand{fib(1) == 1}
\returnType{Type: Void}

\spadcommand{fib(2) == 1}
\returnType{Type: Void}

\spadcommand{fib(n) == fib(n-1) + fib(n-2)}
\returnType{Type: Void}

As defined, this recurrence relation is obviously doubly-recursive.
To compute $fib(10)$, we need to compute $fib(9)$ and $fib(8)$.  And
to $fib(9)$, we need to compute $fib(8)$ and $fib(7)$.  And so on.  It
seems that to compute $fib(10)$ we need to compute $fib(9)$ once,
$fib(8)$ twice, $fib(7)$ three times.  Look familiar?  The number of
function calls needed to compute {\it any} second order recurrence
relation in the obvious way is exactly $fib(n)$.  These numbers grow!
For example, if Axiom actually did this, then $fib(500)$ requires more
than $10^{104}$ function calls.  And, given all
this, our definition of {\bf fib} obviously could not be used to
calculate the five-hundredth Fibonacci number.

%Original Page 156

Let's try it anyway.
\spadcommand{fib(500)}
\begin{verbatim}
   Compiling function fib with type Integer -> PositiveInteger 
   Compiling function fib as a recurrence relation.

13942322456169788013972438287040728395007025658769730726410_
8962948325571622863290691557658876222521294125
\end{verbatim}

\returnType{Type: PositiveInteger}

Since this takes a short time to compute, it obviously didn't do as
many as $10^{104}$ operations!  By default, Axiom transforms any
recurrence relation it recognizes into an iteration.  Iterations are
efficient.  To compute the value of the $n$-th term of a recurrence
relation using an iteration requires only $n$ function calls. Note
that if you compare the speed of our {\bf fib} function to the library
function, our version is still slower.  This is because the library
\spadfunFrom{fibonacci}{IntegerNumberTheoryFunctions} uses a
``powering algorithm'' with a computing time proportional to
$\log^3(n)$ to compute {\tt fibonacci(n)}.

To turn off this special recurrence relation compilation, issue
\index{set function recurrence}
\begin{verbatim}
)set functions recurrence off
\end{verbatim}
To turn it back on, substitute ``{\tt on}'' for ``{\tt off}''.

The transformations that Axiom uses for {\bf fib} caches the last two
values. For a more general $k$-th order recurrence relation, Axiom
caches the last $k$ values.  If, after computing a value for {\bf
fib}, you ask for some larger value, Axiom picks up the cached values
and continues computing from there.  See \sectionref{ugUserFreeLocal}
for an example of a function definition
that has this same behavior.  Also see \sectionref{ugUserCache} 
for a more general discussion of how you can cache function values.

Recurrence relations can be used for defining recurrence relations
involving polynomials, rational functions, or anything you like.
Here we compute the infinite stream of Legendre polynomials.

The Legendre polynomial of degree $0.$
\spadcommand{p(0) == 1}
\returnType{Type: Void}

The Legendre polynomial of degree $1.$
\spadcommand{p(1) == x}
\returnType{Type: Void}

The Legendre polynomial of degree $n$.
\spadcommand{p(n) == ((2*n-1)*x*p(n-1) - (n-1)*p(n-2))/n}
\returnType{Type: Void}

%Original Page 157

Compute the Legendre polynomial of degree $6.$
\spadcommand{p(6)}
\begin{verbatim}
   Compiling function p with type Integer -> Polynomial Fraction 
      Integer 
   Compiling function p as a recurrence relation.
\end{verbatim}
$$
{{\frac{231}{16}} \  {x \sp 6}} -{{\frac{315}{16}} \  {x \sp 4}}
+{{\frac{105}{16}} \  {x \sp 2}} -{\frac{5}{16}} 
$$
\returnType{Type: Polynomial Fraction Integer}

\section{Making Functions from Objects}
\label{ugUserMake}

There are many times when you compute a complicated expression and
then wish to use that expression as the body of a function.  Axiom
provides an operation called {\bf function} to do \index{function!from
an object} this. \index{function!made by function @{made by 
{\bf function}}} It creates a function object and places it into the
workspace.  There are several versions, depending on how many
arguments the function has.  The first argument to {\bf function} is
always the expression to be converted into the function body, and the
second is always the name to be used for the function.  For more
information, see \domainref{MakeFunction}.

Start with a simple example of a polynomial in three variables.
\spadcommand{p := -x + y**2 - z**3}
$$
-{z \sp 3}+{y \sp 2} -x 
$$
\returnType{Type: Polynomial Integer}

To make this into a function of no arguments that simply returns the
polynomial, use the two argument form of {\bf function}.
\spadcommand{function(p,'f0)}
$$
f0 
$$
\returnType{Type: Symbol}

To avoid possible conflicts (see below), it is a good idea to
quote always this second argument.
\spadcommand{f0}
$$
f0 \  {\left( 
\right)}
\  == \  {-{z \sp 3}+{y \sp 2} -x} 
$$
\returnType{Type: FunctionCalled f0}

This is what you get when you evaluate the function.
\spadcommand{f0()}
$$
-{z \sp 3}+{y \sp 2} -x 
$$
\returnType{Type: Polynomial Integer}

To make a function in $x$, use a version of {\bf function} that takes
three arguments.  The last argument is the name of the variable to use
as the parameter.  Typically, this variable occurs in the expression
and, like the function name, you should quote it to avoid possible confusion.
\spadcommand{function(p,'f1,'x)}
$$
f1 
$$
\returnType{Type: Symbol}

This is what the new function looks like.
\spadcommand{f1}
$$
f1 \  x \  == \  {-{z \sp 3}+{y \sp 2} -x} 
$$
\returnType{Type: FunctionCalled f1}

%Original Page 158

This is the value of {\bf f1} at $x = 3$.  Notice that the return type
of the function is {\tt Polynomial (Integer)}, the same as $p$.
\spadcommand{f1(3)}
\begin{verbatim}
   Compiling function f1 with type PositiveInteger -> Polynomial 
      Integer 
\end{verbatim}
$$
-{z \sp 3}+{y \sp 2} -3 
$$
\returnType{Type: Polynomial Integer}

To use $x$ and $y$ as parameters, use the four argument form of {\bf function}.
\spadcommand{function(p,'f2,'x,'y)}
$$
f2 
$$
\returnType{Type: Symbol}

\spadcommand{f2}
$$
f2 \  {\left( x,  y 
\right)}
\  == \  {-{z \sp 3}+{y \sp 2} -x} 
$$
\returnType{Type: FunctionCalled f2}

Evaluate $f2$ at $x = 3$ and $y = 0$.  The return type of {\bf f2} is
still {\tt Polynomial(Integer)} because the variable $z$ is still
present and not one of the parameters.
\spadcommand{f2(3,0)}
$$
-{z \sp 3} -3 
$$
\returnType{Type: Polynomial Integer}

Finally, use all three variables as parameters.  There is no five
argument form of {\bf function}, so use the one with three arguments,
the third argument being a list of the parameters.
\spadcommand{function(p,'f3,['x,'y,'z])}
$$
f3 
$$
\returnType{Type: Symbol}

Evaluate this using the same values for $x$ and $y$ as above, but let
$z$ be $-6$.  The result type of {\bf f3} is {\tt Integer}.
\spadcommand{f3}
$$
f3 \  {\left( x,  y,  z 
\right)}
\  == \  {-{z \sp 3}+{y \sp 2} -x} 
$$
\returnType{Type: FunctionCalled f3}

\spadcommand{f3(3,0,-6)}
\begin{verbatim}
   Compiling function f3 with type (PositiveInteger,NonNegativeInteger,
      Integer) -> Integer 
\end{verbatim}
$$
213 
$$
\returnType{Type: PositiveInteger}

The four functions we have defined via $p$ have been undeclared.  To
declare a function whose body is to be generated by 
\index{function!declaring} {\bf function}, issue the declaration 
{\it before} the function is created.
\spadcommand{g: (Integer, Integer) -> Float}
\returnType{Type: Void}

\spadcommand{D(sin(x-y)/cos(x+y),x)}
$$
\frac{-{{\sin \left({{y -x}} \right)}\  {\sin \left({{y+x}} \right)}}
+{{\cos\left({{y -x}} \right)}\  {\cos \left({{y+x}} \right)}}}
{{\cos \left({{y+x}} \right)}\sp 2} 
$$
\returnType{Type: Expression Integer}

%Original Page 159

\spadcommand{function(\%,'g,'x,'y)}
$$
g 
$$
\returnType{Type: Symbol}

\spadcommand{g}
$$
g \  {\left( x,  y \right)}\  == \  {\frac{-{{\sin \left({{y -x}} \right)}
\  {\sin \left({{y+x}} \right)}}+{{\cos\left({{y -x}} \right)}
\  {\cos \left({{y+x}} \right)}}}{{\cos \left({{y+x}} \right)}\sp 2}} 
$$
\returnType{Type: FunctionCalled g}

It is an error to use $g$ without the quote in the penultimate
expression since $g$ had been declared but did not have a value.
Similarly, since it is common to overuse variable names like $x$, $y$,
and so on, you avoid problems if you always quote the variable names
for {\bf function}.  In general, if $x$ has a value and you use $x$
without a quote in a call to {\bf function}, then Axiom does not know
what you are trying to do.

What kind of object is allowable as the first argument to 
{\bf function}?  Let's use the Browse facility of HyperDoc to find out.
\index{Browse@Browse} At the main Browse menu, enter the string 
{\tt function} and then click on {\bf Operations.}  The exposed operations
called {\bf function} all take an object whose type belongs to
category {\tt ConvertibleTo InputForm}.  What domains are those?  Go
back to the main Browse menu, erase {\tt function}, enter 
{\tt ConvertibleTo} in the input area, and click on {\bf categories} on the
{\tt Constructors} line.  At the bottom of the page, enter 
{\tt InputForm} in the input area following {\bf S =}.  Click on 
{\tt Cross Reference} and then on {\tt Domains}.  
The list you see contains over forty domains that belong to the 
category {\tt ConvertibleTo InputForm}.  Thus you can use {\bf function} 
for {\tt Integer}, {\tt Float}, {\tt Symbol}, {\tt Complex}, 
{\tt Expression}, and so on.

\section{Functions Defined with Blocks}
\label{ugUserBlocks}

You need not restrict yourself to functions that only fit on one line
or are written in a piece-wise manner.  The body of the function can
be a block, as discussed in \sectionref{ugLangBlocks}.

Here is a short function that swaps two elements of a list, array or vector.
\begin{verbatim}
swap(m,i,j) ==
  temp := m.i
  m.i := m.j
  m.j := temp
\end{verbatim}
\returnType{Type: Void}

The significance of {\bf swap} is that it has a destructive
effect on its first argument.
\spadcommand{k := [1,2,3,4,5]}
$$
\left[
1,  2,  3,  4,  5 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{swap(k,2,4)}
\begin{verbatim}
   Compiling function swap with type (List PositiveInteger,
      PositiveInteger,PositiveInteger) -> PositiveInteger 
\end{verbatim}
$$
2 
$$
\returnType{Type: PositiveInteger}

%Original Page 160

You see that the second and fourth elements are interchanged.
\spadcommand{k}
$$
\left[
1, 4, 3, 2, 5 
\right]
$$
\returnType{Type: List PositiveInteger}

Using this, we write a couple of different sort functions.  First, a
simple bubble sort.  \index{sort!bubble} The operation
\spadopFrom{\#}{List} returns the number of elements in an aggregate.
\begin{verbatim}
bubbleSort(m) ==
  n := #m
  for i in 1..(n-1) repeat
    for j in n..(i+1) by -1 repeat
      if m.j < m.(j-1) then swap(m,j,j-1)
  m
\end{verbatim}
\returnType{Type: Void}

Let this be the list we want to sort.
\spadcommand{m := [8,4,-3,9]}
$$
\left[
8,  4,  -3,  9 
\right]
$$
\returnType{Type: List Integer}

This is the result of sorting.
\spadcommand{bubbleSort(m)}
\begin{verbatim}
   Compiling function swap with type (List Integer,Integer,Integer) -> 
      Integer 

+++ |*3;swap;1;G82322| redefined
   Compiling function bubbleSort with type List Integer -> List Integer
\end{verbatim}
$$
\left[
-3, 4, 8, 9 
\right]
$$
\returnType{Type: List Integer}

Moreover, $m$ is destructively changed to be the sorted version.
\spadcommand{m}
$$
\left[
-3, 4, 8, 9 
\right]
$$
\returnType{Type: List Integer}

This function implements an insertion sort.  \index{sort!insertion}
The basic idea is to traverse the list and insert the $i$-th element
in its correct position among the $i-1$ previous elements.  Since we
start at the beginning of the list, the list elements before the
$i$-th element have already been placed in ascending order.
\begin{verbatim}
insertionSort(m) ==
  for i in 2..#m repeat
    j := i
    while j > 1 and m.j < m.(j-1) repeat
      swap(m,j,j-1)
      j := j - 1
  m
\end{verbatim}
\returnType{Type: Void}

As with our bubble sort, this is a destructive function.
\spadcommand{m := [8,4,-3,9]}
$$
\left[
8,  4,  -3,  9 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{insertionSort(m)}
\begin{verbatim}
   Compiling function insertionSort with type List Integer -> List 
      Integer 
\end{verbatim}
$$
\left[
-3, 4, 8, 9 
\right]
$$
\returnType{Type: List Integer}

%Original Page 161

\spadcommand{m}
$$
\left[
-3, 4, 8, 9 
\right]
$$
\returnType{Type: List Integer}

Neither of the above functions is efficient for sorting large lists
since they reference elements by asking for the $j$-th element of the
structure $m$.

Here is a more efficient bubble sort for lists.
\begin{verbatim}
bubbleSort2(m: List Integer): List Integer ==
  null m => m
  l := m
  while not null (r := l.rest) repeat
     r := bubbleSort2 r
     x := l.first
     if x < r.first then
       l.first := r.first
       r.first := x
     l.rest := r
     l := l.rest
  m

   Function declaration bubbleSort2 : List Integer -> List Integer has 
      been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Try it out.
\spadcommand{bubbleSort2 [3,7,2]}
$$
\left[
7, 3, 2 
\right]
$$
\returnType{Type: List Integer}

This definition is both recursive and iterative, and is tricky!
Unless you are {\it really} curious about this definition, we suggest
you skip immediately to the next section.

Here are the key points in the definition.  First notice that if you
are sorting a list with less than two elements, there is nothing to
do: just return the list.  This definition returns immediately if
there are zero elements, and skips the entire {\tt while} loop if there is
just one element.

The second point to realize is that on each outer iteration, the
bubble sort ensures that the minimum element is propagated leftmost.
Each iteration of the {\tt while} loop calls {\bf bubbleSort2} recursively
to sort all but the first element.  When finished, the minimum element
is either in the first or second position.  The conditional expression
ensures that it comes first.  If it is in the second, then a swap
occurs.  In any case, the {\bf rest} of the original list must be
updated to hold the result of the recursive call.

%Original Page 162

\section{Free and Local Variables}
\label{ugUserFreeLocal}

When you want to refer to a variable that is not local to your
function, use a ``{\tt free}'' declaration.  \index{free} Variables
declared to be {\tt free} \index{free variable} are assumed to be defined
globally \index{variable!free} in the \index{variable!global}
workspace.  \index{global variable}

This is a global workspace variable.
\spadcommand{counter := 0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

This function refers to the global $counter$.
\begin{verbatim}
f() ==
  free counter
  counter := counter + 1
\end{verbatim}
\returnType{Type: Void}

The global $counter$ is incremented by $1$.
\spadcommand{f()}
\begin{verbatim}
   Compiling function f with type () -> NonNegativeInteger 

+++ |*0;f;1;G82322| redefined
\end{verbatim}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{counter}
$$
1 
$$
\returnType{Type: NonNegativeInteger}


Usually Axiom can tell that you mean to refer to a global variable and
so {\tt free} isn't always necessary.  However, for clarity and the sake
of self-documentation, we encourage you to use it.

Declare a variable to be ``{\tt local}'' when you do not want to refer to
\index{variable!local} a global variable by the same name.
\index{local variable}

This function uses $counter$ as a local variable.
\begin{verbatim}
g() ==
  local counter
  counter := 7
\end{verbatim}
\returnType{Type: Void}

Apply the function.
\spadcommand{g()}
$$
7 
$$
\returnType{Type: PositiveInteger}

Check that the global value of $counter$ is unchanged.
\spadcommand{counter}
$$
1 
$$
\returnType{Type: NonNegativeInteger}

Parameters to a function are local variables in the function.  Even if
you issue a {\tt free} declaration for a parameter, it is still local.

%Original Page 163

What happens if you do not declare that a variable $x$ in the body of
your function is {\tt local} or {\tt free}?  Well, Axiom decides on this basis:
\begin{enumerate}
\item Axiom scans your function line-by-line, from top-to-bottom.
The right-hand side of an assignment is looked at before the left-hand
side.
\item If $x$ is referenced before it is assigned a value, it is a
{\tt free} (global) variable.
\item If $x$ is assigned a value before it is referenced, it is a
{\tt local} variable.
\end{enumerate}

Set two global variables to 1.
\spadcommand{a := b := 1}
$$
1 
$$
\returnType{Type: PositiveInteger}

Refer to $a$ before it is assigned a value, but assign a value to $b$
before it is referenced.
\begin{verbatim}
h() ==
  b := a + 1
  a := b + a
\end{verbatim}
\returnType{Type: Void}

Can you predict this result?
\spadcommand{h()}
\begin{verbatim}
   Compiling function h with type () -> PositiveInteger 

+++ |*0;h;1;G82322| redefined
\end{verbatim}
$$
3 
$$
\returnType{Type: PositiveInteger}

How about this one?
\spadcommand{[a, b]}
$$
\left[
3, 1 
\right]
$$
\returnType{Type: List PositiveInteger}

What happened?  In the first line of the function body for $h$, $a$ is
referenced on the right-hand side of the assignment.  Thus $a$ is a
free variable.  The variable $b$ is not referenced in that line, but
it is assigned a value.  Thus $b$ is a local variable and is given the
value $a + 1 = 2$.  In the second line, the free variable $a$ is
assigned the value $b + a$ which equals $2 + 1 = 3.$ This is the value
returned by the function.  Since $a$ was free in {\bf h}, the global
variable $a$ has value $3.$ Since $b$ was local in {\bf h}, the global
variable $b$ is unchanged---it still has the value $1$.

It is good programming practice always to declare global variables.
However, by far the most common situation is to have local variables
in your functions.  No declaration is needed for this situation, but
be sure to initialize their values.

Be careful if you use free variables and you cache the value of your
function (see \sectionref{ugUserCache}).
Caching {\it only} checks if the values of the function arguments are
the same as in a function call previously seen.  It does not check if
any of the free variables on which the function depends have changed
between function calls.

Turn on caching for {\bf p}.
\spadcommand{)set fun cache all p}
\begin{verbatim}
   function p will cache all values.
\end{verbatim}

Define {\bf p} to depend on the free variable $N$.
\spadcommand{p(i,x) == ( free N; reduce( + , [ (x-i)**n for n in 1..N ] ) )}
\returnType{Type: Void}

Set the value of $N$.
\spadcommand{N := 1}
$$
1 
$$
\returnType{Type: PositiveInteger}

Evaluate {\bf p} the first time.
\spadcommand{p(0, x)}
$$
x 
$$
\returnType{Type: Polynomial Integer}

Change the value of $N$.
\spadcommand{N := 2}
$$
2 
$$
\returnType{Type: PositiveInteger}

Evaluate {\bf p} the second time.
\spadcommand{p(0, x)}
$$
x 
$$
\returnType{Type: Polynomial Integer}

If caching had been turned off, the second evaluation would have
reflected the changed value of $N$.

Turn off caching for {\bf p}.
\spadcommand{)set fun cache 0 p}
\begin{verbatim}
   Caching for function p is turned off
\end{verbatim}

Axiom does not allow {\it fluid variables}, that is, variables
\index{variable!fluid} bound by a function $f$ that can be referenced
by functions called by $f$.  \index{fluid variable}

Values are passed to functions by {\it reference}: a pointer to the
value is passed rather than a copy of the value or a pointer to a
copy.

%Original Page 164

This is a global variable that is bound to a record object.
\spadcommand{r : Record(i : Integer) := [1]}
$$
\left[
{i=1} 
\right]
$$
\returnType{Type: Record(i: Integer)}

This function first modifies the one component of its record argument
and then rebinds the parameter to another record.
\begin{verbatim}
resetRecord rr ==
  rr.i := 2
  rr := [10]
\end{verbatim}
\returnType{Type: Void}

Pass $r$ as an argument to {\bf resetRecord}. 
\spadcommand{resetRecord r}
$$
\left[
{i={10}} 
\right]
$$
\returnType{Type: Record(i: Integer)}

The value of $r$ was changed by the expression $rr.i := 2$ but not by
$rr := [10]$.
\spadcommand{r}
$$
\left[
{i=2} 
\right]
$$
\returnType{Type: Record(i: Integer)}

To conclude this section, we give an iterative definition of
\index{Fibonacci numbers} a function that computes Fibonacci numbers.
This definition approximates the definition into which Axiom
transforms the recurrence relation definition of {\bf fib} in
\sectionref{ugUserRecur}.

Global variables {\tt past} and {\tt present} are used to hold the last
computed Fibonacci numbers.
\spadcommand{past := present := 1}
$$
1 
$$
\returnType{Type: PositiveInteger}

Global variable $index$ gives the current index of $present$.
\spadcommand{index := 2}
$$
2 
$$
\returnType{Type: PositiveInteger}

Here is a recurrence relation defined in terms of these three global
variables.
\begin{verbatim}
fib(n) ==
  free past, present, index
  n < 3 => 1
  n = index - 1 => past
  if n < index-1 then
    (past,present) := (1,1)
    index := 2
  while (index < n) repeat
    (past,present) := (present, past+present)
    index := index + 1
  present
\end{verbatim}
\returnType{Type: Void}

%Original Page 165

Compute the infinite stream of Fibonacci numbers.
\spadcommand{fibs := [fib(n) for n in 1..]}
$$
\left[
1, 1, 2, 3, 5, 8, {13}, {21}, {34}, {55},
\ldots 
\right]
$$
\returnType{Type: Stream PositiveInteger}

What is the 1000th Fibonacci number?
\spadcommand{fibs 1000}
\begin{verbatim}
  434665576869374564356885276750406258025646605173717804024_
    8172908953655541794905189040387984007925516929592259308_
    0322634775209689623239873322471161642996440906533187938_
    298969649928516003704476137795166849228875
\end{verbatim}
\returnType{Type: PositiveInteger}

As an exercise, we suggest you write a function in an iterative style
that computes the value of the recurrence relation 
$p(n) = p(n-1) - 2 \, p(n-2) + 4 \, p(n-3)$ 
having the initial values 
$p(1) = 1,\, p(2) = 3 \hbox{ and } p(3) = 9.$ 
How would you write the function using an element {\tt OneDimensionalArray} 
or {\tt Vector} to hold the previously computed values?

\section{Anonymous Functions}
\label{ugUserAnon}

\boxer{4.6in}{
An {\it anonymous function} is a function that is
\index{function!anonymous} defined \index{anonymous function} by
giving a list of parameters, the ``maps-to'' compound 
\index{+-> @{\tt +->}} symbol ``{\tt +->}'' 
(from the mathematical symbol $\mapsto$), and
by an expression involving the parameters, the evaluation of which
determines the return value of the function.

\begin{center}
{\tt ( $\hbox{\it parm}_{1}$, $\hbox{\it parm}_{2}$, \ldots, 
$\hbox{\it parm}_{N}$ ) {\tt +->} {\it expression}}
\end{center}
{\ }%force a blank line 
}

You can apply an anonymous function in several ways.
\begin{enumerate}
\item Place the anonymous function definition in parentheses
directly followed by a list of arguments.
\item Assign the anonymous function to a variable and then
use the variable name when you would normally use a function name.
\item Use ``{\tt ==}'' to use the anonymous function definition as
the arguments and body of a regular function definition.
\item Have a named function contain a declared anonymous function and
use the result returned by the named function.
\end{enumerate}

\subsection{Some Examples}
\label{ugUserAnonExamp}

Anonymous functions are particularly useful for defining functions
``on the fly.'' That is, they are handy for simple functions that are
used only in one place.  In the following examples, we show how to
write some simple anonymous functions.

%Original Page 166

This is a simple absolute value function.
\spadcommand{x +-> if x < 0 then -x else x}
$$
x \mapsto {if \  {x<0} \  {\begin{array}{l} {then \  -x} \\ 
{else \  x} 
\end{array}
}} 
$$
\returnType{Type: AnonymousFunction}

\spadcommand{abs1 := \%}
$$
x \mapsto {if \  {x<0} \  {\begin{array}{l} {then \  -x} \\ 
{else \  x} 
\end{array}
}} 
$$
\returnType{Type: AnonymousFunction}

This function returns {\tt true} if the absolute value of
the first argument is greater than the absolute value of the
second, {\tt false} otherwise.

\spadcommand{(x,y) +-> abs1(x) > abs1(y)}
$$
{\left( x,  y 
\right)}
\mapsto {{abs1 
\left(
{y} 
\right)}<{abs1
\left(
{x} 
\right)}}
$$
\returnType{Type: AnonymousFunction}

We use the above function to ``sort'' a list of integers.
\spadcommand{sort(\%,[3,9,-4,10,-3,-1,-9,5])}
$$
\left[
{10},  -9,  9,  5,  -4,  -3,  3,  -1 
\right]
$$
\returnType{Type: List Integer}

This function returns $1$ if $i + j$ is even, $-1$ otherwise.
\spadcommand{ev := ( (i,j) +-> if even?(i+j) then 1 else -1)}
$$
{\left( i,  j 
\right)}
\mapsto {if \  {even? 
\left(
{{i+j}} 
\right)}
\  {\begin{array}{l} {then \  1} \\ 
{else \  -1} 
\end{array}
}} 
$$
\returnType{Type: AnonymousFunction}

We create a four-by-four matrix containing $1$ or $-1$ depending on
whether the row plus the column index is even or not.
\spadcommand{matrix([ [ev(row,col) for row in 1..4] for col in 1..4])}
$$
\left[
\begin{array}{cccc}
1 & -1 & 1 & -1 \\ 
-1 & 1 & -1 & 1 \\ 
1 & -1 & 1 & -1 \\ 
-1 & 1 & -1 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

This function returns {\tt true} if a polynomial in $x$ has multiple
roots, {\tt false} otherwise.  It is defined and applied in the same
expression.
\spadcommand{( p +-> not one?(gcd(p,D(p,x))) )(x**2+4*x+4)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

This and the next expression are equivalent.
\spadcommand{g(x,y,z) == cos(x + sin(y + tan(z)))}
\returnType{Type: Void}

The one you use is a matter of taste.
\spadcommand{g == (x,y,z) +-> cos(x + sin(y + tan(z)))}
\begin{verbatim}
   1 old definition(s) deleted for function or rule g 
\end{verbatim}
\returnType{Type: Void}

\subsection{Declaring Anonymous Functions}
\label{ugUserAnonDeclare}

%Original Page 167

If you declare any of the arguments you must declare all of them. Thus,
\begin{verbatim}
(x: INT,y): FRAC INT +-> (x + 2*y)/(y - 1)
\end{verbatim}
is not legal.

This is an example of a fully declared anonymous function.
\index{function!declaring} \index{function!anonymous!declaring} The
output shown just indicates that the object you created is a
particular kind of map, that is, function.
\spadcommand{(x: INT,y: INT): FRAC INT +-> (x + 2*y)/(y - 1)}
$$
\mbox{theMap(...)} 
$$
\returnType{Type: ((Integer,Integer) {\tt ->} Fraction Integer)}

Axiom allows you to declare the arguments and not declare
the return type.
\spadcommand{(x: INT,y: INT) +-> (x + 2*y)/(y - 1)}
$$
\mbox{theMap(...)} 
$$
\returnType{Type: ((Integer,Integer) {\tt ->} Fraction Integer)}

The return type is computed from the types of the arguments and the
body of the function.  You cannot declare the return type if you do
not declare the arguments.  Therefore,
\begin{verbatim}
(x,y): FRAC INT +-> (x + 2*y)/(y - 1)
\end{verbatim}

is not legal. This and the next expression are equivalent.
\spadcommand{h(x: INT,y: INT): FRAC INT == (x + 2*y)/(y - 1)}
\begin{verbatim}
   Function declaration h : (Integer,Integer) -> Fraction Integer
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

The one you use is a matter of taste.
\spadcommand{h == (x: INT,y: INT): FRAC INT +-> (x + 2*y)/(y - 1)}
\begin{verbatim}
   Function declaration h : (Integer,Integer) -> Fraction Integer
      has been added to workspace.
   1 old definition(s) deleted for function or rule h 
\end{verbatim}
\returnType{Type: Void}

When should you declare an anonymous function?  
\begin{enumerate}
\item If you use an anonymous function and Axiom can't figure out what
you are trying to do, declare the function.  
\item If the function has nontrivial argument types or a nontrivial 
return type that Axiom may be able to determine eventually, but you 
are not willing to wait that long, declare the function.  
\item If the function will only be used for arguments of specific types 
and it is not too much trouble to declare the function, do so.  
\item If you are using the anonymous function as an argument to another 
function (such as {\bf map} or {\bf sort}), consider declaring the function.  
\item If you define an anonymous function inside a named function, 
you {\it must} declare the anonymous function.  
\end{enumerate}

This is an example of a named function for integers that returns a
function.
\spadcommand{addx x == ((y: Integer): Integer +-> x + y)}
\returnType{Type: Void}

We define {\bf g} to be a function that adds $10$ to its
argument.
\spadcommand{g := addx 10}
\begin{verbatim}
   Compiling function addx with type 
     PositiveInteger -> (Integer -> Integer) 
\end{verbatim}
$$
\mbox{theMap(...)} 
$$
\returnType{Type: (Integer {\tt ->} Integer)}

Try it out.
\spadcommand{g 3}
$$
13 
$$
\returnType{Type: PositiveInteger}

\spadcommand{g(-4)}
$$
6 
$$
\returnType{Type: PositiveInteger}

\index{function!anonymous!restrictions}
An anonymous function cannot be recursive: since it does not have a
name, you cannot even call it within itself!  If you place an
anonymous function inside a named function, the anonymous function
must be declared.

\section{Example: A Database}
\label{ugUserDatabase}

This example shows how you can use Axiom to organize a database of
lineage data and then query the database for relationships.

The database is entered as ``assertions'' that are really pieces of a
function definition.
\spadcommand{children("albert") == ["albertJr","richard","diane"]}
\returnType{Type: Void}

Each piece $children(x) == y$ means ``the children of $x$ are $y$''.
\spadcommand{children("richard") == ["douglas","daniel","susan"]}
\returnType{Type: Void}

This family tree thus spans four generations.
\spadcommand{children("douglas") == ["dougie","valerie"]}
\returnType{Type: Void}

%Original Page 169

Say ``no one else has children.''
\spadcommand{children(x) == []}
\returnType{Type: Void}

We need some functions for computing lineage.  Start with {\tt childOf}.
\spadcommand{childOf(x,y) == member?(x,children(y))}
\returnType{Type: Void}

To find the {\tt parentOf} someone, you have to scan the database of
people applying {\tt children}.
\begin{verbatim}
parentOf(x) ==
  for y in people repeat
    (if childOf(x,y) then return y)
  "unknown"
\end{verbatim}
\returnType{Type: Void}

And a grandparent of $x$ is just a parent of a parent of $x$.
\spadcommand{grandParentOf(x) == parentOf parentOf x}
\returnType{Type: Void}

The grandchildren of $x$ are the people $y$ such that $x$ is a
grandparent of $y$.
\spadcommand{grandchildren(x) == [y for y in people | grandParentOf(y) = x]}
\returnType{Type: Void}

Suppose you want to make a list of all great-grandparents.  Well, a
great-grandparent is a grandparent of a person who has children.

\begin{verbatim}
greatGrandParents == [x for x in people |
  reduce(_or,
    [not empty? children(y) for y in grandchildren(x)],false)]
\end{verbatim}
\returnType{Type: Void}

Define {\tt descendants} to include the parent as well.
\begin{verbatim}
descendants(x) ==
  kids := children(x)
  null kids => [x]
  concat(x,reduce(concat,[descendants(y)
    for y in kids],[]))
\end{verbatim}
\returnType{Type: Void}

Finally, we need a list of people.  Since all people are descendants
of ``albert'', let's say so.
\spadcommand{people == descendants "albert"}
\returnType{Type: Void}

We have used ``{\tt ==}'' to define the database and some functions to
query the database.  But no computation is done until we ask for some
information.  Then, once and for all, the functions are analyzed and
compiled to machine code for run-time efficiency.  Notice that no
types are given anywhere in this example.  They are not needed.

%Original Page 170

Who are the grandchildren of ``richard''?
\spadcommand{grandchildren "richard"}
\begin{verbatim}
Compiling function children with type String -> List String 
Compiling function descendants with type String -> List String 
Compiling body of rule people to compute value of type List String 
Compiling function childOf with type (String,String) -> Boolean 
Compiling function parentOf with type String -> String 
Compiling function grandParentOf with type String -> String 
Compiling function grandchildren with type String -> List String 
\end{verbatim}
$$
\left[
\mbox{\tt "dougie"} , \mbox{\tt "valerie"} 
\right]
$$
\returnType{Type: List String}

Who are the great-grandparents?
\spadcommand{greatGrandParents}
\begin{verbatim}
Compiling body of rule greatGrandParents to compute value of 
   type List String 
\end{verbatim}
$$
\left[
\mbox{\tt "albert"} 
\right]
$$
\returnType{Type: List String}

\section{Example: A Famous Triangle}
\label{ugUserTriangle}

In this example we write some functions that display Pascal's
triangle.  \index{Pascal's triangle} It demonstrates the use of
piece-wise definitions and some output operations you probably haven't
seen before.

To make these output operations available, we have to {\it expose} the
domain {\tt OutputForm}.  \index{OutputForm} See 
\sectionref{ugTypesExpose}
for more information about exposing domains and packages.
\spadcommand{)set expose add constructor OutputForm}
\begin{verbatim}
   OutputForm is now explicitly exposed in frame G82322 
\end{verbatim}

Define the values along the first row and any column $i$.
\spadcommand{pascal(1,i) == 1}
\returnType{Type: Void}

Define the values for when the row and column index $i$ are equal.
Repeating the argument name indicates that the two index values are equal.
\spadcommand{pascal(n,n) == 1}
\returnType{Type: Void}

\begin{verbatim}
pascal(i,j | 1 < i and i < j) ==
   pascal(i-1,j-1)+pascal(i,j-1)
\end{verbatim}
\returnType{Type: Void}

Now that we have defined the coefficients in Pascal's triangle, let's
write a couple of one-liners to display it. 

First, define a function that gives the $n$-th row.
\spadcommand{pascalRow(n) == [pascal(i,n) for i in 1..n]}
\returnType{Type: Void}

Next, we write the function {\bf displayRow} to display the row,
separating entries by blanks and centering.
\spadcommand{displayRow(n) == output center blankSeparate pascalRow(n)}
\returnType{Type: Void}

%Original Page 171

Here we have used three output operations.  Operation
\spadfunFrom{output}{OutputForm} displays the printable form of
objects on the screen, \spadfunFrom{center}{OutputForm} centers a
printable form in the width of the screen, and
\spadfunFrom{blankSeparate}{OutputForm} takes a list of n printable
forms and inserts a blank between successive elements.

Look at the result.
\spadcommand{for i in 1..7 repeat displayRow i}
\begin{verbatim}
   Compiling function pascal with type (Integer,Integer) -> 
      PositiveInteger 
   Compiling function pascalRow with type PositiveInteger -> List 
      PositiveInteger 
   Compiling function displayRow with type PositiveInteger -> Void 


                                   1
                                  1 1
                                 1 2 1
                                1 3 3 1
                               1 4 6 4 1
                             1 5 10 10 5 1
                            1 6 15 20 15 6 1
\end{verbatim}
\returnType{Type: Void}

Being purists, we find this less than satisfactory.  Traditionally,
elements of Pascal's triangle are centered between the left and right
elements on the line above.

To fix this misalignment, we go back and redefine {\bf pascalRow} to
right adjust the entries within the triangle within a width of four
characters.

\spadcommand{pascalRow(n) == [right(pascal(i,n),4) for i in 1..n]}
\begin{verbatim}
   Compiled code for pascalRow has been cleared.
   Compiled code for displayRow has been cleared.
   1 old definition(s) deleted for function or rule pascalRow 
\end{verbatim}
\returnType{Type: Void}

Finally let's look at our purely reformatted triangle.
\spadcommand{for i in 1..7 repeat displayRow i}
\begin{verbatim}
   Compiling function pascalRow with type PositiveInteger -> List 
      OutputForm 

+++ |*1;pascalRow;1;G82322| redefined
   Compiling function displayRow with type PositiveInteger -> Void 

+++ |*1;displayRow;1;G82322| redefined
                                     1
                                  1    1
                                1    2    1
                             1    3    3    1
                           1    4    6    4    1
                        1    5   10   10    5    1
                      1    6   15   20   15    6    1
\end{verbatim}
\returnType{Type: Void}

Unexpose {\tt OutputForm} so we don't get unexpected results later.
\spadcommand{)set expose drop constructor OutputForm}
\begin{verbatim}
   OutputForm is now explicitly hidden in frame G82322 
\end{verbatim}

\section{Example: Testing for Palindromes}
\label{ugUserPal}

In this section we define a function {\bf pal?} that tests whether its
\index{palindrome} argument is a {\it palindrome}, that is, something
that reads the same backwards and forwards.  For example, the string
``Madam I'm Adam'' is a palindrome (excluding blanks and punctuation)
and so is the number $123454321$.  The definition works for any
datatype that has $n$ components that are accessed by the indices
$1\ldots n$.

%Original Page 172

Here is the definition for {\bf pal?}.  It is simply a call to an
auxiliary function called {\bf palAux?}.  We are following the
convention of ending a function's name with {\tt ?} if the function
returns a {\tt Boolean} value.
\spadcommand{pal? s ==  palAux?(s,1,\#s)}
\returnType{Type: Void}

Here is {\bf palAux?}.  It works by comparing elements that are
equidistant from the start and end of the object.
\begin{verbatim}
palAux?(s,i,j) ==
  j > i =>
    (s.i = s.j) and palAux?(s,i+1,i-1)
  true
\end{verbatim}
\returnType{Type: Void}

Try {\bf pal?} on some examples.  First, a string.
\spadcommand{pal? "Oxford"}
\begin{verbatim}
   Compiling function palAux? with type (String,Integer,Integer) -> 
      Boolean 
   Compiling function pal? with type String -> Boolean 
\end{verbatim}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

A list of polynomials.
\spadcommand{pal? [4,a,x-1,0,x-1,a,4]}
\begin{verbatim}
   Compiling function palAux? with type (List Polynomial Integer,
      Integer,Integer) -> Boolean 
   Compiling function pal? with type List Polynomial Integer -> Boolean
\end{verbatim}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

A list of integers from the example in the last section. 
\spadcommand{pal? [1,6,15,20,15,6,1]}
\begin{verbatim}
   Compiling function palAux? with type (List PositiveInteger,Integer,
      Integer) -> Boolean 
   Compiling function pal? with type List PositiveInteger -> Boolean 
\end{verbatim}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

To use {\bf pal?} on an integer, first convert it to a string.
\spadcommand{pal?(1441::String)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Compute an infinite stream of decimal numbers, each of which is an
obvious palindrome.
\spadcommand{ones := [reduce(+,[10**j for j in 0..i]) for i in 1..]}
$$
\begin{array}{@{}l}
\left[
{11}, {111}, {1111}, {11111}, {111111}, {1111111}, 
\right.
\\
\\
\displaystyle
\left.
{11111111}, {111111111}, {1111111111}, {11111111111}, \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream PositiveInteger}

\spadcommand{)set streams calculate 9}

How about their squares?
\spadcommand{squares := [x**2 for x in ones]}
$$
\begin{array}{@{}l}
\left[
{121}, {12321}, {1234321}, {123454321}, {12345654321}, {1234567654321}, 
\right.
\\
\\
\displaystyle
{123456787654321}, {12345678987654321}, {1234567900987654321}, 
\\
\\
\displaystyle
\left.
{123456790120987654321},  \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream PositiveInteger}

Well, let's test them all.
\spadcommand{[pal?(x::String) for x in squares]}
$$
\left[
{\tt true}, {\tt true}, {\tt true}, {\tt true}, {\tt true}, 
{\tt true}, {\tt true}, {\tt true}, {\tt true}, {\tt true}, \ldots 
\right]
$$
\returnType{Type: Stream Boolean}

\spadcommand{)set streams calculate 7}

%Original Page 173

\section{Rules and Pattern Matching}
\label{ugUserRules}

A common mathematical formula is 
$$ \log(x) + \log(y) = \log(x y) \quad\forall \, x \hbox{\ and\ } y$$ 
The presence of ``$\forall$'' indicates that $x$ and $y$ can stand for
arbitrary mathematical expressions in the above formula.  You can use
such mathematical formulas in Axiom to specify ``rewrite rules''.
Rewrite rules are objects in Axiom that can be assigned to variables
for later use, often for the purpose of simplification.  Rewrite rules
look like ordinary function definitions except that they are preceded
by the reserved word $rule$.  \index{rule} For example, a rewrite rule
for the above formula is:
\begin{verbatim}
rule log(x) + log(y) == log(x * y)
\end{verbatim}

Like function definitions, no action is taken when a rewrite rule is
issued.  Think of rewrite rules as functions that take one argument.
When a rewrite rule $A = B$ is applied to an argument $f$, its meaning
is: ``rewrite every subexpression of $f$ that {\it matches} $A$ by
$B.$'' The left-hand side of a rewrite rule is called a {\it pattern};
its right-hand side is called its {\it substitution}.

Create a rewrite rule named {\bf logrule}.  The generated symbol
beginning with a ``{\tt \%}'' is a place-holder for any other terms that
might occur in the sum.
\spadcommand{logrule := rule log(x) + log(y) == log(x * y)}
$$
{{\log 
\left(
{y} 
\right)}+{\log
\left(
{x} 
\right)}+
 \%C} \mbox{\rm == } {{\log 
\left(
{{x \  y}} 
\right)}+
 \%C} 
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

Create an expression with logarithms.
\spadcommand{f := log sin x + log x}
$$
{\log 
\left(
{{\sin 
\left(
{x} 
\right)}}
\right)}+{\log
\left(
{x} 
\right)}
$$
\returnType{Type: Expression Integer}

Apply {\bf logrule} to $f$.
\spadcommand{logrule f}
$$
\log 
\left(
{{x \  {\sin 
\left(
{x} 
\right)}}}
\right)
$$
\returnType{Type: Expression Integer}

The meaning of our example rewrite rule is: ``for all expressions $x$
and $y$, rewrite $log(x) + log(y)$ by $log(x * y)$.''  Patterns
generally have both operation names (here, {\bf log} and ``{\tt +}'') and
variables (here, $x$ and $y$).  By default, every operation name
stands for itself.  Thus {\bf log} matches only ``$log$'' and not any
other operation such as {\bf sin}.  On the other hand, variables do
not stand for themselves.  Rather, a variable denotes a {\it pattern
variable} that is free to match any expression whatsoever.
\index{pattern!variables}

When a rewrite rule is applied, a process called 
{\it pattern matching} goes to work by systematically scanning
\index{pattern!matching} the subexpressions of the argument.  When a
subexpression is found that ``matches'' the pattern, the subexpression
is replaced by the right-hand side of the rule.  The details of what
happens will be covered later.

%Original Page 174

The customary Axiom notation for patterns is actually a shorthand for
a longer, more general notation.  Pattern variables can be made
explicit by using a percent ``{\tt \%}'' as the first character of the
variable name.  To say that a name stands for itself, you can prefix
that name with a quote operator ``{\tt '}''.  Although the current Axiom
parser does not let you quote an operation name, this more general
notation gives you an alternate way of giving the same rewrite rule:
\begin{verbatim}
rule log(%x) + log(%y) == log(x * y)
\end{verbatim}

This longer notation gives you patterns that the standard notation
won't handle.  For example, the rule
\begin{verbatim}
rule %f(c * 'x) ==  c*%f(x)
\end{verbatim}
means ``for all $f$ and $c$, replace $f(y)$ by $c * f(x)$ when $y$ is
the product of $c$ and the explicit variable $x$.''

Thus the pattern can have several adornments on the names that appear there.
Normally, all these adornments are dropped in the substitution on the
right-hand side.

To summarize:

\boxer{4.6in}{
To enter a single rule in Axiom, use the following syntax: \index{rule}
\begin{center}
{\tt rule {\it leftHandSide} == {\it rightHandSide}}
\end{center}

The {\it leftHandSide} is a pattern to be matched and the {\it
rightHandSide} is its substitution.  The rule is an object of type
{\tt RewriteRule} that can be assigned to a variable and applied to
expressions to transform them.\\
}

Rewrite rules can be collected
into rulesets so that a set of rules can be applied at once.
Here is another simplification rule for logarithms.
$$y \log(x) = \log(x^y) \quad\forall \, x \hbox{\ and\ } y$$
If instead of giving a single rule following the reserved word $rule$
you give a ``pile'' of rules, you create what is called a {\it
ruleset.}  \index{ruleset} Like rules, rulesets are objects in Axiom
and can be assigned to variables.  You will find it useful to group
commonly used rules into input files, and read them in as needed.

Create a ruleset named $logrules$.
\begin{verbatim}
logrules := rule
  log(x) + log(y) == log(x * y)
  y * log x       == log(x ** y)
\end{verbatim}
$$
\left\{{{{\log \left({y} \right)}
+{\log\left({x} \right)}+ \%B} 
\mbox{\rm == } 
{{\log \left({{x \  y}} \right)}+ \%B}}, 
{{y \  {\log \left({x} \right)}}
\mbox{\rm == } 
{\log \left({{x \sp y}} \right)}}\right\}
$$
\returnType{Type: Ruleset(Integer,Integer,Expression Integer)}

%Original Page 175

Again, create an expression $f$ containing logarithms.
\spadcommand{f := a * log(sin x) - 2 * log x}
$$
{a \  {\log 
\left(
{{\sin 
\left(
{x} 
\right)}}
\right)}}
-{2 \  {\log 
\left(
{x} 
\right)}}
$$
\returnType{Type: Expression Integer}

Apply the ruleset {\bf logrules} to $f$.
\spadcommand{logrules f}
$$
\log \left({{\frac{{\sin \left({x} \right)}\sp a}{x \sp 2}}} \right)
$$
\returnType{Type: Expression Integer}


We have allowed pattern variables to match arbitrary expressions in
the above examples.  Often you want a variable only to match
expressions satisfying some predicate.  For example, we may want to
apply the transformation 
$$y \log(x) = \log(x^y)$$ 
only when $y$ is an integer.

The way to restrict a pattern variable $y$ by a predicate $f(y)$
\index{pattern!variable!predicate} is by using a vertical bar ``{\tt |}'',
which means ``such that,'' in \index{such that} much the same way it
is used in function definitions.  \index{predicate!on a pattern
variable} You do this only once, but at the earliest (meaning deepest
and leftmost) part of the pattern.

This restricts the logarithmic rule to create integer exponents only.
\begin{verbatim}
logrules2 := rule
  log(x) + log(y)          == log(x * y)
  (y | integer? y) * log x == log(x ** y)
\end{verbatim}
$$
\left\{{{{\log \left({y} \right)}
+{\log\left({x} \right)}+ \%D} 
\mbox{\rm == } 
{{\log \left({{x \  y}} \right)}+ \%D}}, 
{{y \  {\log \left({x} \right)}}
\mbox{\rm == } 
{\log \left({{x \sp y}} \right)}}\right\}
$$
\returnType{Type: Ruleset(Integer,Integer,Expression Integer)}

Compare this with the result of applying the previous set of rules.
\spadcommand{f}
$$
{a \  {\log \left({{\sin \left({x} \right)}}\right)}}
-{2 \  {\log \left({x} \right)}}
$$
\returnType{Type: Expression Integer}

\spadcommand{logrules2 f}
$$
{a \  {\log \left({{\sin \left({x} \right)}}\right)}}
+{\log\left({{\frac{1}{x \sp 2}}} \right)}
$$
\returnType{Type: Expression Integer}

You should be aware that you might need to apply a function like 
{\tt integer} within your predicate expression to actually apply the test
function.

Here we use {\tt integer} because $n$ has type {\tt Expression
Integer} but {\bf even?} is an operation defined on integers.
\spadcommand{evenRule := rule cos(x)**(n | integer? n and even? integer n)==(1-sin(x)**2)**(n/2)}
$$
{{\cos \left({x} \right)}\sp n} \mbox{\rm == } 
{{\left( -{{\sin \left({x} \right)}\sp 2}+1 \right)}\sp {\frac{n}{2}}} 
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

Here is the application of the rule.
\spadcommand{evenRule( cos(x)**2 )}
$$
-{{\sin \left({x} \right)}\sp 2}+1 
$$
\returnType{Type: Expression Integer}

This is an example of some of the usual identities involving products of
sines and cosines.
\begin{verbatim}
sinCosProducts == rule
  sin(x) * sin(y) == (cos(x-y) - cos(x + y))/2
  cos(x) * cos(y) == (cos(x-y) + cos(x+y))/2
  sin(x) * cos(y) == (sin(x-y) + sin(x + y))/2
\end{verbatim}
\returnType{Type: Void}

\spadcommand{g := sin(a)*sin(b) + cos(b)*cos(a) + sin(2*a)*cos(2*a)}
$$
{{\sin \left({a} \right)}\  {\sin \left({b} \right)}}
+{{\cos\left({{2 \  a}} \right)}\  {\sin \left({{2 \  a}} \right)}}
+{{\cos\left({a} \right)}\  {\cos \left({b} \right)}}
$$
\returnType{Type: Expression Integer}

%Original Page 176

\spadcommand{sinCosProducts g}
\begin{verbatim}
   Compiling body of rule sinCosProducts to compute value of type 
      Ruleset(Integer,Integer,Expression Integer) 
\end{verbatim}
$$
\frac{{\sin \left({{4 \  a}} \right)}+{2\  {\cos \left({{b -a}} \right)}}}{2} 
$$
\returnType{Type: Expression Integer}

Another qualification you will often want to use is to allow a pattern to
match an identity element.
Using the pattern $x + y$, for example, neither $x$ nor $y$
matches the expression $0$.
Similarly, if a pattern contains a product $x*y$ or an exponentiation
$x**y$, then neither $x$ or $y$ matches $1$.

If identical elements were matched, pattern matching would generally loop.
Here is an expansion rule for exponentials.
\spadcommand{exprule := rule exp(a + b) == exp(a) * exp(b)}
$$
{e \sp {\left( b+a \right)}}
\mbox{\rm == } {{e \sp a} \  {e \sp b}} 
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

This rule would cause infinite rewriting on this if either $a$ or
$b$ were allowed to match $0$.
\spadcommand{exprule exp x}
$$
e \sp x 
$$
\returnType{Type: Expression Integer}

There are occasions when you do want a pattern variable in a sum or
product to match $0$ or $1$. If so, prefix its name
with a ``{\tt ?}'' whenever it appears in a left-hand side of a rule.
For example, consider the following rule for the exponential integral:
$$\int \left(\frac{y+e^x}{x}\right) dx = 
\int \frac{y}{x} dx + \hbox{\rm Ei}(x) \quad\forall \, x \hbox{\ and\ } y$$
This rule is valid for $y = 0$.  One solution is to create a {\tt
Ruleset} with two rules, one with and one without $y$.  A better
solution is to use an ``optional'' pattern variable.

Define rule {\tt eirule} with
a pattern variable $?y$ to indicate
that an expression may or may not occur.
\spadcommand{eirule := rule integral((?y + exp x)/x,x) == integral(y/x,x) + Ei x}
$$
{\int \sp{\displaystyle x} {{\frac{{e \sp \%M}+y}{\%M}} \  {d \%M}}} 
\mbox{\rm == } {{{{\tt '}integral} 
\left({{\frac{y}{x}}, x} \right)}+{{{\tt'}Ei} \left({x} \right)}}
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

Apply rule {\tt eirule} to an integral without this term.
\spadcommand{eirule integral(exp u/u, u)}
$$
Ei \left({u} \right)
$$
\returnType{Type: Expression Integer}

Apply rule {\tt eirule} to an integral with this term.
\spadcommand{eirule integral(sin u + exp u/u, u)}
$$
{\int \sp{\displaystyle u} {{\sin \left({ \%M} \right)}\  {d \%M}}}
+{Ei \left({u} \right)}
$$
\returnType{Type: Expression Integer}

%Original Page 177

Here is one final adornment you will find useful.  When matching a
pattern of the form $x + y$ to an expression containing a long sum of
the form $a +\ldots+ b$, there is no way to predict in advance which
subset of the sum matches $x$ and which matches $y$.  Aside from
efficiency, this is generally unimportant since the rule holds for any
possible combination of matches for $x$ and $y$.  In some situations,
however, you may want to say which pattern variable is a sum (or
product) of several terms, and which should match only a single term.
To do this, put a prefix colon ``{\tt :}'' before the pattern variable
that you want to match multiple terms.
\index{pattern!variable!matching several terms}

The remaining rules involve operators $u$ and $v$. \index{operator}
\spadcommand{u := operator 'u}
$$
u 
$$
\returnType{Type: BasicOperator}

These definitions tell Axiom that $u$ and $v$ are formal operators to
be used in expressions.
\spadcommand{v := operator 'v}
$$
v 
$$
\returnType{Type: BasicOperator}

First define {\tt myRule} with no restrictions on the pattern variables
$x$ and $y$.
\spadcommand{myRule := rule u(x + y) == u x + v y}
$$
{u \left({{y+x}} \right)}\mbox{\rm == } 
{{{{\tt '}v} \left({y} \right)}+{{{\tt'}u} \left({x} \right)}}
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

Apply {\tt myRule} to an expression.
\spadcommand{myRule u(a + b + c + d)}
$$
{v \left({{d+c+b}} \right)}+{u\left({a} \right)}
$$
\returnType{Type: Expression Integer}

Define {\tt myOtherRule} to match several terms so that the rule gets
applied recursively.
\spadcommand{myOtherRule := rule u(:x + y) == u x + v y}
$$
{u \left({{y+x}} \right)}\mbox{\rm == } 
{{{{\tt '}v} \left({y} \right)}+{{{\tt'}u} \left({x} \right)}}
$$
\returnType{Type: RewriteRule(Integer,Integer,Expression Integer)}

Apply {\tt myOtherRule} to the same expression.
\spadcommand{myOtherRule u(a + b + c + d)}
$$
{v \left({c} \right)}
+{v\left({b} \right)}
+{v\left({a} \right)}
+{u\left({d} \right)}
$$
\returnType{Type: Expression Integer}

\boxer{4.6in}{
Summary of pattern variable adornments:
\vskip .5\baselineskip
\begin{tabular}{@{}ll}
{\tt (x | predicate?(x))} &
  means that the substutution $s$ for $x$\\ &
  must satisfy {\tt predicate(s) = true.} \\
{\tt ?x} &
  means that $x$ can match an identity \\ & element (0 or 1). \\
{\tt :x} &
  means that $x$ can match several terms \\ & in a sum.
\end{tabular}\\
}

%Original Page 178

Here are some final remarks on pattern matching.  Pattern matching
provides a very useful paradigm for solving certain classes of
problems, namely, those that involve transformations of one form to
another and back.  However, it is important to recognize its
limitations.  \index{pattern!matching!caveats}

First, pattern matching slows down as the number of rules you have to
apply increases.  Thus it is good practice to organize the sets of
rules you use optimally so that irrelevant rules are never included.

Second, careless use of pattern matching can lead to wrong answers.
You should avoid using pattern matching to handle hidden algebraic
relationships that can go undetected by other programs.  As a simple
example, a symbol such as ``J'' can easily be used to represent the
square root of $-1$ or some other important algebraic quantity.  Many
algorithms branch on whether an expression is zero or not, then divide
by that expression if it is not.  If you fail to simplify an
expression involving powers of $J$ to $-1,$ algorithms may incorrectly
assume an expression is non-zero, take a wrong branch, and produce a
meaningless result.

Pattern matching should also not be used as a substitute for a domain.
In Axiom, objects of one domain are transformed to objects of other
domains using well-defined {\bf coerce} operations.  Pattern matching
should be used on objects that are all the same type.  Thus if your
application can be handled by type {\tt Expression} in Axiom and you
think you need pattern matching, consider this choice carefully.
\index{Expression} You may well be better served by extending an
existing domain or by building a new domain of objects for your
application.

%\setcounter{chapter}{6}

%Original Page 179

\chapter{Graphics}
\label{ugGraph}

\begin{figure}[htbp]
\includegraphics{ps/torusknot.ps}
\caption{Torus knot of type (15,17).}
\end{figure}

This chapter shows how to use the Axiom graphics facilities
\index{graphics} under the X Window System.  Axiom has
two-di\-men\-sion\-al and three-di\-men\-sion\-al drawing and
rendering packages that allow the drawing, coloring, transforming,
mapping, clipping, and combining of graphic output from Axiom
computations.  This facility is particularly useful for investigating
problems in areas such as topology.  The graphics package is capable
of plotting functions of one or more variables or plotting parametric
surfaces and curves.  Various coordinate systems are also available,
such as polar and spherical.

A graph is displayed in a viewport window and it has a
\index{viewport} control-panel that uses interactive mouse commands.
PostScript and other output forms are available so that Axiom
\index{PostScript} images can be printed or used by other programs.

%Original Page 180

\section{Two-Dimensional Graphics}
\label{ugGraphTwoD}

The Axiom two-di\-men\-sion\-al graphics package provides the ability
to \index{graphics!two-dimensional} display
\begin{itemize}
\item curves defined by functions of a single real variable
\item curves defined by parametric equations
\item implicit non-singular curves defined by polynomial equations
\item planar graphs generated from lists of point components.
\end{itemize}

These graphs can be modified by specifying various options, such as
calculating points in the polar coordinate system or changing the size
of the graph viewport window.

\subsection{Plotting Two-Dimensional Functions of One Variable}
\label{ugGraphTwoDPlot}

\index{curve!one variable function} The first kind of
two-di\-men\-sion\-al graph is that of a curve defined by a function
$y = f(x)$ over a finite interval of the $x$ axis.

\boxer{4.6in}{
The general format for drawing a function defined by a formula $f(x)$ is:
\begin{center}
{\tt draw(f(x), x = a..b, {\it options})}
\end{center}

where $a..b$ defines the range of $x$, and where {\it options}
prescribes zero or more options as described in
\sectionref{ugGraphTwoDOptions}.  An
example of an option is $curveColor == bright\ red().$ An alternative
format involving functions $f$ and $g$ is also available.\\
}

A simple way to plot a function is to use a formula.  The first
argument is the formula.  For the second argument, write the name of
the independent variable (here, $x$), followed by an ``{\tt =}'', and the
range of values.

%Original Page 181

Display this formula over the range $0 \leq x \leq 6$.
Axiom converts your formula to a compiled function so that the
results can be computed quickly and efficiently. 

\spadgraph{draw(sin(tan(x)) - tan(sin(x)),x = 0..6)}
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2d1vara.eps}}
\begin{center}
$sin(tan(x)) - tan(sin(x))\ \ \ x = 0 \ldots6$
\end{center}
\end{minipage}

Notice that Axiom compiled the function before the graph was put
on the screen.

Here is the same graph on a different interval.

\spadgraph{draw(sin(tan(x)) - tan(sin(x)),x = 10..16)}
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2d1varb.eps}}
\begin{center}
$sin(tan(x)) - tan(sin(x))\ \ \ x = 10 \ldots16$
\end{center}
\end{minipage}

Once again the formula is converted to a compiled function before any
points were computed.  If you want to graph the same function on
several intervals, it is a good idea to define the function first so
that the function has to be compiled only once.

This time we first define the function.
\spadcommand{f(x) == (x-1)*(x-2)*(x-3) }

%Original Page 182

To draw the function, the first argument is its name and the second is
just the range with no independent variable.
\spadgraph{draw(f, 0..4) }
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2d1vard.eps}}
\begin{center}
$f(x) == (x-1)(x-2)(x-3)$
\end{center}
\end{minipage}

\subsection{Plotting Two-Dimensional Parametric Plane Curves}
\label{ugGraphTwoDPar}

The second kind of two-di\-men\-sion\-al graph is that of
\index{parametric plane curve} curves produced by parametric
equations.  \index{curve!parametric plane} Let $x = f(t)$ and 
$y = g(t)$ be formulas or two functions $f$ and $g$ as the parameter $t$
ranges over an interval $[a,b]$.  The function {\bf curve} takes the
two functions $f$ and $g$ as its parameters.

\boxer{4.6in}{
The general format for drawing a two-di\-men\-sion\-al plane curve defined by
parametric formulas $x = f(t)$ and $y = g(t)$ is:
\begin{center}
{\tt draw(curve(f(t), g(t)), t = a..b, {\it options})}
\end{center}

where $a..b$ defines the range of the independent variable $t$, and
where {\it options} prescribes zero or more options as described in
\sectionref{ugGraphThreeDOptions}.  An
example of an option is $curveColor == bright\ red().$\\ }

Here's an example:

%Original Page 183

Define a parametric curve using a range involving $\%pi$, Axiom's way
of saying $\pi$.  For parametric curves, Axiom
compiles two functions, one for each of the functions $f$ and $g$.
\spadgraph{draw(curve(sin(t)*sin(2*t)*sin(3*t), sin(4*t)*sin(5*t)*sin(6*t)), t = 0..2*\%pi)}
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2dppca.eps}}
\begin{center}
$curve(sin(t)*sin(2t)*sin(3t), sin(4t)*sin(5t)*sin(6t))$
\end{center}
\end{minipage}

The title may be an arbitrary string and is an optional argument to
the {\bf draw} command.
\spadgraph{draw(curve(cos(t), sin(t)), t = 0..2*\%pi)}
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2dppcb.eps}}
\begin{center}
$curve(cos(t), sin(t)), \quad t = 0..2\pi$
\end{center}
\end{minipage}

If you plan on plotting $x = f(t)$, $y = g(t)$ as $t$ ranges over
several intervals, you may want to define functions $f$ and $g$ first,
so that they need not be recompiled every time you create a new graph.
Here's an example:

As before, you can first define the functions you wish to draw.
\spadcommand{f(t:DFLOAT):DFLOAT == sin(3*t/4) }
\begin{verbatim}
   Function declaration f : DoubleFloat -> DoubleFloat has been 
      added to workspace.
\end{verbatim}
\returnType{Type: Void}

Axiom compiles them to map {\tt DoubleFloat} values to {\tt DoubleFloat} 
values.
\spadcommand{g(t:DFLOAT):DFLOAT == sin(t) }
\begin{verbatim}
   Function declaration f : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

%Original Page 184

Give to {\tt curve} the names of the functions, then write the range
without the name of the independent variable.
\spadgraph{draw(curve(f,g),0..\%pi) }
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2dppcc.eps}}
\begin{center}
$curve(f,g) \quad 0..\pi$
\end{center}
\end{minipage}

Here is another look at the same curve but over a different
range. Notice that $f$ and $g$ are not recompiled.  Also note that
Axiom provides a default title based on the first function specified
in {\bf curve}.
\spadgraph{draw(curve(f,g),-4*\%pi..4*\%pi) }
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2dppce.eps}}
\begin{center}
$curve(f,g)\quad -4\pi..4\pi$
\end{center}
\end{minipage}

\subsection{Plotting Plane Algebraic Curves}
\label{ugGraphTwoDPlane}

A third kind of two-di\-men\-sion\-al graph is a non-singular
``solution curve'' \index{curve!plane algebraic} in a rectangular
region of the plane.  A solution curve is a curve defined by a
polynomial equation $p(x,y) = 0$.  \index{plane algebraic curve}
Non-singular means that the curve is ``smooth'' in that it does not
cross itself or come to a point (cusp).  Algebraically, this means
that for any point $(x,y)$ on the curve, that is, a point such that
$p(x,y) = 0$, the partial derivatives 
${\frac{\partial p}{\partial x}}(x,y)$ and 
${\frac{\partial p}{\partial y}}(x,y)$ are not both zero.
\index{curve!smooth} \index{curve!non-singular} \index{smooth curve}
\index{non-singular curve}

%Original Page 185

\boxer{4.6in}{
The general format for drawing a non-singular solution curve given by
a polynomial of the form $p(x,y) = 0$ is:
\begin{center}
{\tt draw(p(x,y) = 0, x, y, range == [a..b, c..d], {\it options})}
\end{center}

where the second and third arguments name the first and second
independent variables of $p$.  A {\tt range} option is always given to
designate a bounding rectangular region of the plane
$a \leq x \leq b, c \leq y \leq d$.
Zero or more additional options as described in
\sectionref{ugGraphTwoDOptions} may be given.
}

We require that the polynomial has rational or integral coefficients.
Here is an algebraic curve example (``Cartesian ovals''):
\index{Cartesian!ovals}
\spadcommand{p := ((x**2 + y**2 + 1) - 8*x)**2 - (8*(x**2 + y**2 + 1)-4*x-1) }
$$
{y \sp 4}+{{\left( {2 \  {x \sp 2}} -{{16} \  x} -6 
\right)}
\  {y \sp 2}}+{x \sp 4} -{{16} \  {x \sp 3}}+{{58} \  {x \sp 2}} -{{12} \  x} 
-6 
$$
\returnType{Type: Polynomial Integer}

The first argument is always expressed as an equation of the form $p = 0$
where $p$ is a polynomial.
\spadgraph{draw(p = 0, x, y, range == [-1..11, -7..7]) }
\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2dpaca.eps}}
\begin{center}
$p = 0, x, y,\quad range == [-1..11, -7..7]$
\end{center}
\end{minipage}

\subsection{Two-Dimensional Options}
\label{ugGraphTwoDOptions}

The {\bf draw} commands take an optional list of options, such as {\tt
title} shown above.  Each option is given by the syntax: 
{\it name} {\tt ==} {\it value}.  
Here is a list of the available options in the
order that they are described below.

\begin{tabular}{llll}
adaptive&clip&unit\\
clip&curveColor&range\\
toScale&pointColor&coordinates\\
\end{tabular}


%Original Page 186


The $adaptive$ option turns adaptive plotting on or off.
\index{adaptive plotting} Adaptive plotting uses an algorithm that
traverses a graph and computes more points for those parts of the
graph with high curvature.  The higher the curvature of a region is,
the more points the algorithm computes.  
\index{graphics!2D options!adaptive}

The {\tt adaptive} option is normally on.  Here we turn it off.
\spadgraph{draw(sin(1/x),x=-2*\%pi..2*\%pi, adaptive == false)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptad.eps}}
\begin{center}
$sin(1/x),x=-2\pi..2\pi,\quad adaptive == false$
\end{center}
\end{minipage}

The {\tt clip} option turns clipping on or off.  
\index{graphics!2D options!clipping} 
If on, large values are cut off according to
\spadfunFrom{clipPointsDefault}{GraphicsDefaults}.

\spadgraph{draw(tan(x),x=-2*\%pi..2*\%pi, clip == true)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptcp.eps}}
\begin{center}
$tan(x),x=-2\pi..2\pi,\quad clip == true$
\end{center}
\end{minipage}

Option {\tt toScale} does plotting to scale if {\tt true} or uses the
entire viewport if {\tt false}.  The default can be determined using
\spadfunFrom{drawToScale}{GraphicsDefaults}.  
\index{graphics!2D options!to scale}

\spadgraph{draw(sin(x),x=-\%pi..\%pi, toScale == true, unit == [1.0,1.0])}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptsc.eps}}
\begin{center}
$sin(x),x=-\pi..\pi,\quad toScale == true,\quad unit == [1.0,1.0]$
\end{center}
\end{minipage}

%Original Page 187

Option {\tt clip} with a range sets point clipping of a graph within
the \index{graphics!2D options!clip in a range} ranges specified in
the list $[x range,y range]$.  \index{clipping} If only one range is
specified, clipping applies to the y-axis.
\spadgraph{draw(sec(x),x=-2*\%pi..2*\%pi, clip == [-2*\%pi..2*\%pi,-\%pi..\%pi], unit == [1.0,1.0])}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptcpr.eps}}
\begin{center}
$sec(x),x=-2\pi..2\pi, \quad clip == [-2\pi..2\pi,-\pi..\pi], 
 unit == [1.0,1.0]$
\end{center}
\end{minipage}

Option {\tt curveColor} sets the color of the graph curves or lines to
be the \index{graphics!2D options!curve color} indicated palette color
\index{curve!color} (see \sectionref{ugGraphColor} and
\sectionref{ugGraphColorPalette}).  
\index{color!curve}

\spadgraph{draw(sin(x),x=-\%pi..\%pi, curveColor == bright red())}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptcvc.eps}}
\begin{center}
$sin(x),x=-\pi..\pi, \quad curveColor == bright red()$
\end{center}
\end{minipage}

Option {\tt pointColor} sets the color of the graph points to the
indicated \index{graphics!2D options!point color} palette color (see
\sectionref{ugGraphColor} and \sectionref{ugGraphColorPalette}).
\index{color!point}
\spadgraph{draw(sin(x),x=-\%pi..\%pi, pointColor == pastel yellow())}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptptc.eps}}
\begin{center}
$sin(x),x=-\pi..\pi, \quad pointColor == pastel yellow()$
\end{center}
\end{minipage}

%Original Page 188

Option {\tt unit} sets the intervals at which the axis units are
plotted \index{graphics!2D options!set units} according to the
indicated steps [$x$ interval, $y$ interval].
\spadgraph{draw(curve(9*sin(3*t/4),8*sin(t)), t = -4*\%pi..4*\%pi, unit == [2.0,1.0])}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptut.eps}}
\begin{center}
$9sin(3t/4),8sin(t)), t = -4\pi..4\pi, \quad unit == [2.0,1.0]$
\end{center}
\end{minipage}

Option {\tt range} sets the range of variables in a graph to be within
the ranges \index{graphics!2D options!range} for solving plane
algebraic curve plots.
\spadgraph{draw(y**2 + y - (x**3 - x) = 0, x, y, range == [-2..2,-2..1], unit==[1.0,1.0])}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptrga.eps}}
\begin{center}
$y^2 + y - (x^3 - x) = 0, x, y, range == [-2..2,-2..1], unit==[1.0,1.0]$
\end{center}
\end{minipage}

A second example of a solution plot.
\spadgraph{draw(x**2 + y**2 = 1, x, y, range == [-3/2..3/2,-3/2..3/2], unit==[0.5,0.5])}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptrgb.eps}}
\begin{center}
$x^2 + y^2 = 1, x, y, range == [-3/2..3/2,-3/2..3/2], unit==[0.5,0.5]$
\end{center}
\end{minipage}

%Original Page 189

Option $coordinates$ indicates the coordinate system in which the
graph \index{graphics!2D options!coordinates} is plotted.  The default
is to use the Cartesian coordinate system.
\index{Cartesian!coordinate system} For more details, see
\sectionref{ugGraphCoord}
{or {\tt CoordinateSystems}.}
\index{coordinate system!Cartesian}

\spadgraph{draw(curve(sin(5*t),t),t=0..2*\%pi, coordinates == polar)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/2doptplr.eps}}
\begin{center}
$sin(5t),t),t=0..2\pi,\quad coordinates == polar$
\end{center}
\end{minipage}

\subsection{Color}
\label{ugGraphColor}

The domain {\tt Color} \index{Color} provides operations for
manipulating \index{graphics!color} colors in two-di\-men\-sion\-al
graphs.  \index{color} Colors are objects of {\tt Color}.  Each color
has a {\it hue} and a {\it weight}.  \index{hue} Hues are represented
by integers that range from $1$ to the
\spadfunFrom{numberOfHues()}{Color}, normally
\index{graphics!color!number of hues} $27$.  \index{weight} Weights
are floats and have the value $1.0$ by default.

\begin{description}

\item[{\bf color}]\funArgs{integer}
creates a color of hue {\it integer} and weight $1.0$.

\item[{\bf hue}]\funArgs{color}
returns the hue of {\it color} as an integer.
\index{graphics!color!hue function}

\item[{\bf red}]\funArgs{}
\funSyntax{blue}{},
\funSyntax{green}{}, and \funSyntax{yellow}{}
\index{graphics!color!primary color functions}
create colors of that hue with weight $1.0$.

\item[$\hbox{\it color}_{1}$ {\tt +} $\hbox{\it color}_{2}$] returns the
color that results from additively combining the indicated
$\hbox{\it color}_{1}$ and $\hbox{\it color}_{2}$.
Color addition is not commutative: changing the order of the arguments
produces different results.

\item[{\it integer} {\tt *} {\it color}]
changes the weight of {\it color} by {\it integer}
without affecting its hue.
\index{graphics!color!multiply function}
For example,
$red() + 3*yellow()$ produces a color closer to yellow than to red.
Color multiplication is not associative: changing the order of grouping
\index{color!multiplication}
produces different results.
\end{description}

%Original Page 190

These functions can be used to change the point and curve colors
for two- and three-di\-men\-sion\-al graphs.
Use the {\tt pointColor} option for points.

\spadgraph{draw(x**2,x=-1..1,pointColor == green())}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/23dcola.eps}}
\begin{center}
$x^2, x=-1..1, \quad pointColor == green()$
\end{center}
\end{minipage}

Use the {\tt curveColor} option for curves.

\spadgraph{draw(x**2,x=-1..1,curveColor == color(13) + 2*blue())}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/23dcolb.eps}}
\begin{center}
$x^2, x=-1..1, \quad curveColor == color(13) + 2*blue()$
\end{center}
\end{minipage}

\subsection{Palette}
\label{ugGraphColorPalette}
\index{graphics!palette}

Domain {\tt Palette} is the domain of shades of colors:
{\bf dark}, {\bf dim}, {\bf bright}, {\bf pastel}, and {\bf light},
designated by the integers $1$ through $5$, respectively.
\index{Palette}

Colors are normally ``bright.''

\spadcommand{shade red()}
$$
3 
$$
\returnType{Type: PositiveInteger}

To change the shade of a color, apply the name of a shade to it.
\index{color!shade}
\index{shade}

\spadcommand{myFavoriteColor := dark blue() }
$$
[{ \mbox{\rm Hue: }{22}\quad \mbox{\rm Weight: }{1.0}} \mbox{\rm ] from the } 
Dark\ \mbox{\rm palette} 
$$
\returnType{Type: Palette}

The expression $shade(color)$
returns the value of a shade of $color$.

\spadcommand{shade myFavoriteColor }
$$
1 
$$
\returnType{Type: PositiveInteger}

%Original Page 191

The expression $hue(color)$ returns its hue.

\spadcommand{hue myFavoriteColor }
$$
\mbox{\rm Hue: } {22}\quad \mbox{\rm Weight: } {1.0} 
$$
\returnType{Type: Color}

Palettes can be used in specifying colors in two-di\-men\-sion\-al graphs.

\spadgraph{draw(x**2,x=-1..1,curveColor == dark blue())}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/23dpal.eps}}
\begin{center}
$x^2,x=-1..1, \quad curveColor == dark blue()$
\end{center}
\end{minipage}

\subsection{Two-Dimensional Control-Panel}
\label{ugGraphTwoDControl}

\index{graphics!2D control-panel}
Once you have created a viewport, move your mouse to the viewport and click
with your left mouse button to display a control-panel.
The panel is displayed on the side of the viewport closest to
where you clicked.  Each of the buttons which toggle on and off show the
current state of the graph.

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=1.0]{ps/2dctrl.eps}}
\begin{center}
Two-dimensional control-panel.
\end{center}
\end{minipage}

\subsubsection{Transformations}
\index{graphics!2D control-panel!transformations}

Object transformations are executed from the control-panel by mouse-activated
potentiometer windows.
%
\begin{description}
%
\item[Scale:] To scale a graph, click on a mouse button
\index{graphics!2D control-panel!scale}
within the {\bf Scale} window in the upper left corner of the control-panel.
The axes along which the scaling is to occur are indicated by setting the
toggles above the arrow.
With {\tt X On} and {\tt Y On} appearing, both axes are selected and scaling
is uniform.
If either is not selected, for example, if {\tt X Off} appears, scaling is
non-uniform.
%
\item[Translate:] To translate a graph, click the mouse in the
\index{graphics!2D control-panel!translate}
{\bf Translate} window in the direction you wish the graph to move.
This window is located in the upper right corner of the control-panel.
Along the top of the {\bf Translate} window are two buttons for selecting
the direction of translation.
Translation along both coordinate axes results when {\tt X On} and {\tt Y
On} appear or along one axis when one is on, for example, {\tt X On} and
{\tt Y Off} appear.
\end{description}

\subsubsection{Messages}
\index{graphics!2D control-panel!messages}

The window directly below the transformation potentiometer windows is
used to display system messages relating to the viewport and the control-panel.
The following format is displayed: \newline
%

%Original Page 192

\begin{center}
[scaleX, scaleY] $>$graph$<$ [translateX, translateY] \newline
\end{center}
The two values to the left show the scale factor along the {\tt X} and
{\tt Y} coordinate axes.  The two values to the right show the distance of
translation from the center in the {\tt X} and {\tt Y} directions.  The number
in the center shows which graph in the viewport this data pertains to.
When multiple graphs exist in the same viewport,
the graph must be selected (see ``Multiple Graphs,'' below) in
order for its transformation data to be shown, otherwise the number
is 1.

\subsubsection{Multiple Graphs}

\index{graphics!2D control-panel!multiple graphs}
The {\bf Graphs} window contains buttons that allow the placement
of two-di\-men\-sion\-al graphs into one of nine available slots in any other
two-di\-men\-sion\-al viewport.
In the center of the window are numeral buttons from one to nine
that show whether a graph is displayed in the viewport.
Below each number button is a button showing whether a graph
that is present is selected for application of some
transformation.
When the caret symbol is displayed, then the graph in that slot
will be manipulated.
Initially, the graph for which the viewport is created occupies
the first slot, is displayed, and is selected.
%

%%Original Page 193

\begin{description}
%
\item[Clear:]  The {\bf Clear} button deselects every viewport graph slot.
\index{graphics!2D control-panel!clear}
A graph slot is reselected by selecting the button below its number.
%
\item[Query:]  The {\bf Query} button is used to display the scale and
\index{graphics!2D control-panel!query}
translate data for the indicated graph.  When this button is selected the
message ``Click on the graph to query'' appears.  Select a slot
number button from the {\bf Graphs} window. The scaling factor and translation
offset of the graph are then displayed in the message window.
%
\item[Pick:]  The {\bf Pick} button is used to select a graph
\index{graphics!2D control-panel!pick}
to be placed or dropped into the indicated viewport.  When this button is
selected, the message ``Click on the graph to pick'' appears.
Click on the slot with the graph number of the desired
graph.  The graph information is held waiting for
you to execute a {\bf Drop} in some other graph.
%
\item[Drop:]  Once a graph has been picked up using the {\bf Pick} button,
\index{graphics!2D control-panel!drop}
the {\bf Drop} button places it into a new viewport slot.
The message ``Click on the graph to drop'' appears in the message
window when the {\bf Drop} button is selected.
By selecting one of the slot number buttons in the {\bf Graphs}
window, the graph currently being held is dropped into this slot
and displayed.
\end{description}

\subsubsection{Buttons}
\index{graphics!2D control-panel!buttons}

%
\begin{description}
%
\item[Axes] turns the coordinate axes on or off.
\index{graphics!2D control-panel!axes}
%
\item[Units] turns the units along the {\tt x}
and {\tt y} axis on or off.
\index{graphics!2D control-panel!units}
%
\item[Box] encloses the area of the viewport graph
in a bounding box, or removes the box if already enclosed.
\index{graphics!2D control-panel!box}
%
\item[Pts] turns on or off the display of points.
\index{graphics!2D control-panel!points}
%
\item[Lines] turns on or off the display
of lines connecting points.
\index{graphics!2D control-panel!lines}
%
\item[PS] writes the current viewport contents to
\index{graphics!2D control-panel!ps}
a file {\bf axiom2d.ps} or to a name specified in the user's {\bf
\index{graphics!.Xdefaults!PostScript file name}
.Xdefaults} file.
\index{file!.Xdefaults @{\bf .Xdefaults}}
The file is placed in the directory from which Axiom or the {\bf
viewalone} program was invoked.
\index{PostScript}
%
\item[Reset] resets the object transformation
characteristics and attributes back to their initial states.
\index{graphics!2D control-panel!reset}
%
\item[Hide] makes the control-panel disappear.
\index{graphics!2D control-panel!hide}
%
\item[Quit] queries whether the current viewport
\index{graphics!2D control-panel!quit}
session should be terminated.
\end{description}

\subsection{Operations for Two-Dimensional Graphics}
\label{ugGraphTwoDops}

Here is a summary of useful Axiom operations for two-di\-men\-sion\-al
graphics.
Each operation name is followed by a list of arguments.
Each argument is written as a variable informally named according
to the type of the argument (for example, {\it integer}).
If appropriate, a default value for an argument is given in
parentheses immediately following the name.


%%Original Page 194

\begin{description}
%
\item[{\bf adaptive}]\funArgs{\optArg{boolean\argDef{true}}}
\index{adaptive plotting}
sets or indicates whether graphs are plotted
\index{graphics!set 2D defaults!adaptive}
according to the adaptive refinement algorithm.
%
\item[{\bf axesColorDefault}]\funArgs{\optArg{color\argDef{dark blue()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!axes color}
axes in a two-di\-men\-sion\-al graph viewport.
%
\item[{\bf clipPointsDefault}]\funArgs{\optArg{boolean\argDef{false}}}
sets or
indicates whether point clipping is
\index{graphics!set 2D defaults!clip points}
to be applied as the default for graph plots.
%
\item[{\bf drawToScale}]\funArgs{\optArg{boolean\argDef{false}}}
sets or
indicates whether the plot of a graph
\index{graphics!set 2D defaults!to scale}
is ``to scale'' or uses the entire viewport space as the default.
%
\item[{\bf lineColorDefault}]\funArgs{\optArg{color\argDef{pastel yellow()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!line color}
lines or curves in a two-di\-men\-sion\-al graph viewport.
%
\item[{\bf maxPoints}]\funArgs{\optArg{integer\argDef{500}}}
sets or indicates
the default maximum number of
\index{graphics!set 2D defaults!max points}
possible points to be used when constructing a two-di\-men\-sion\-al graph.
%
\item[{\bf minPoints}]\funArgs{\optArg{integer\argDef{21}}}
sets or indicates the default minimum number of
\index{graphics!set 2D defaults!min points}
possible points to be used when constructing a two-di\-men\-sion\-al graph.
%
\item[{\bf pointColorDefault}]\funArgs{\optArg{color\argDef{bright red()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!point color}
points in a two-di\-men\-sion\-al graph viewport.
%
\item[{\bf pointSizeDefault}]\funArgs{\optArg{integer\argDef{5}}}
sets or indicates the default size of the
\index{graphics!set 2D defaults!point size}
dot used to plot points in a two-di\-men\-sion\-al graph.
%
\item[{\bf screenResolution}]\funArgs{\optArg{integer\argDef{600}}}
sets or indicates the default screen
\index{graphics!set 2D defaults!screen resolution}
resolution constant used in setting the computation limit of adaptively
\index{adaptive plotting}
generated curve plots.
%
\item[{\bf unitsColorDefault}]\funArgs{\optArg{color\argDef{dim green()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!units color}
unit labels in a two-di\-men\-sion\-al graph viewport.
%
\item[{\bf viewDefaults}]\funArgs{}
resets the default settings for the following
\index{graphics!set 2D defaults!reset viewport}
attributes:  point color, line color, axes color, units color, point size,
viewport upper left-hand corner position, and the viewport size.
%
\item[{\bf viewPosDefault}]\funArgs{\optArg{list\argDef{[100,100]}}}
sets or indicates the default position of the
\index{graphics!set 2D defaults!viewport position}
upper left-hand corner of a two-di\-men\-sion\-al viewport, relative to the
display root window.
The upper left-hand corner of the display is considered to be at the
(0, 0) position.

%%Original Page 195

\item[{\bf viewSizeDefault}]\funArgs{\optArg{list\argDef{[200,200]}}}
sets or
indicates the default size in which two
\index{graphics!set 2D defaults!viewport size}
dimensional viewport windows are shown.
It is defined by a width and then a height.
%
\item[{\bf viewWriteAvailable}]
\funArgs{\optArg{list\argDef{["pixmap","bitmap", "postscript", "image"]}}}
indicates the possible file types
\index{graphics!2D defaults!available viewport writes}
that can be created with the \spadfunFrom{write}{TwoDimensionalViewport} function.
%
\item[{\bf viewWriteDefault}]\funArgs{\optArg{list\argDef{[]}}}
sets or indicates the default types of files, in
\index{graphics!set 2D defaults!write viewport}
addition to the {\bf data} file, that are created when a
{\bf write} function is executed on a viewport.
%
\item[{\bf units}]\funArgs{viewport, integer\argDef{1}, string\argDef{"off"}}
turns the units on or off for the graph with index {\it integer}.
%
\item[{\bf axes}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
turns the axes on
\index{graphics!2D commands!axes}
or off for the graph with index {\it integer}.
%
\item[{\bf close}]\funArgs{viewport}
closes {\it viewport}.
\index{graphics!2D commands!close}
%
\item[{\bf connect}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
declares whether lines
\index{graphics!2D commands!connect}
connecting the points are displayed or not.
%
\item[{\bf controlPanel}]\funArgs{viewport, string\argDef{"off"}}
declares
whether the two-di\-men\-sion\-al control-panel is automatically displayed
or not.
%
\item[{\bf graphs}]\funArgs{viewport}
returns a list
\index{graphics!2D commands!graphs}
describing the state of each graph.
If the graph state is not being used this is shown by {\tt "undefined"},
otherwise a description of the graph's contents is shown.
%
\item[{\bf graphStates}]\funArgs{viewport}
displays
\index{graphics!2D commands!state of graphs}
a list of all the graph states available for {\it viewport}, giving the
values for every property.
%
\item[{\bf key}]\funArgs{viewport}
returns the process
\index{graphics!2D commands!key}
ID number for {\it viewport}.
%
\item[{\bf move}]\funArgs{viewport,
$integer_{x}$(viewPosDefault),
$integer_{y}$(viewPosDefault)}
moves {\it viewport} on the screen so that the
\index{graphics!2D commands!move}
upper left-hand corner of {\it viewport} is at the position {\it (x,y)}.
%
\item[{\bf options}]\funArgs{\it viewport}
returns a list
\index{graphics!2D commands!options}
of all the {\tt DrawOption}s used by {\it viewport}.
%
\item[{\bf points}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
specifies whether the graph points for graph {\it integer} are
\index{graphics!2D commands!points}
to be displayed or not.
%
\item[{\bf region}]\funArgs{viewport, integer\argDef{1}, string\argDef{"off"}}
declares whether graph {\it integer} is or is not to be displayed
with a bounding rectangle.

%%Original Page 196

\item[{\bf reset}]\funArgs{viewport}
resets all the properties of {\it viewport}.
%
\item[{\bf resize}]\funArgs{viewport,
$integer_{width}$,$integer_{height}$}
\index{graphics!2D commands!resize}
resizes {\it viewport} with a new {\it width} and {\it height}.
%
\item[{\bf scale}]\funArgs{viewport, $integer_{n}$\argDef{1},
$integer_{x}$\argDef{0.9}, $integer_{y}$\argDef{0.9}}
scales values for the
\index{graphics!2D commands!scale}
{\it x} and {\it y} coordinates of graph {\it n}.
%
\item[{\bf show}]\funArgs{viewport, $integer_{n}$\argDef{1},
string\argDef{"on"}}
indicates if graph {\it n} is shown or not.
%
\item[{\bf title}]\funArgs{viewport, string\argDef{"Axiom 2D"}}
designates the title for {\it viewport}.
%
\item[{\bf translate}]\funArgs{viewport,
$integer_{n}$\argDef{1},
$float_{x}$\argDef{0.0}, $float_{y}$\argDef{0.0}}
\index{graphics!2D commands!translate}
causes graph {\it n} to be moved {\it x} and {\it y} units in the respective 
directions.
%
\item[{\bf write}]\funArgs{viewport, $string_{directory}$,
\optArg{strings}}
if no third argument is given, writes the {\bf data} file onto the directory
with extension {\bf data}.
The third argument can be a single string or a list of strings with some or
all the entries {\tt "pixmap"}, {\tt "bitmap"}, {\tt "postscript"}, and
{\tt "image"}.
\end{description}

\subsection{Addendum: Building Two-Dimensional Graphs}
\label{ugGraphTwoDbuild}

In this section we demonstrate how to create two-di\-men\-sion\-al graphs from
lists of points and give an example showing how to read the lists
of points from a file.

\subsubsection{Creating a Two-Dimensional Viewport from a List of Points}

Axiom creates lists of points in a two-di\-men\-sion\-al viewport by utilizing
the {\tt GraphImage} and {\tt TwoDimensionalViewport} domains.
In this example, the \spadfunFrom{makeGraphImage}{GraphImage}
function takes a list of lists of points parameter, a list of colors for
each point in the graph, a list of colors for each line in the graph, and
a list of sizes for each point in the graph.
%

The following expressions create a list of lists of points which will be read
by Axiom and made into a two-di\-men\-sion\-al viewport.

\spadcommand{p1 := point [1,1]\$(Point DFLOAT) }
$$
\left[
{1.0},  {1.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p2 := point [0,1]\$(Point DFLOAT) }
$$
\left[
{0.0},  {1.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p3 := point [0,0]\$(Point DFLOAT) }
$$
\left[
{0.0},  {0.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p4 := point [1,0]\$(Point DFLOAT) }
$$
\left[
{1.0},  {0.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p5 := point [1,.5]\$(Point DFLOAT) }
$$
\left[
{1.0},  {0.5} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p6 := point [.5,0]\$(Point DFLOAT) }
$$
\left[
{0.5},  {0.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p7 := point [0,0.5]\$(Point DFLOAT) }
$$
\left[
{0.0},  {0.5} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p8 := point [.5,1]\$(Point DFLOAT) }
$$
\left[
{0.5},  {1.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p9 := point [.25,.25]\$(Point DFLOAT) }
$$
\left[
{0.25},  {0.25} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p10 := point [.25,.75]\$(Point DFLOAT) }
$$
\left[
{0.25},  {0.75} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p11 := point [.75,.75]\$(Point DFLOAT) }
$$
\left[
{0.75},  {0.75} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p12 := point [.75,.25]\$(Point DFLOAT) }
$$
\left[
{0.75},  {0.25} 
\right]
$$
\returnType{Type: Point DoubleFloat}

Finally, here is the list.

\spadcommand{llp := [ [p1,p2], [p2,p3], [p3,p4], [p4,p1], [p5,p6], [p6,p7], [p7,p8], [p8,p5], [p9,p10], [p10,p11], [p11,p12], [p12,p9] ]  }
$$
\begin{array}{@{}l}
\displaystyle
\left[
  {\left[ {\left[ {1.0},  {1.0} \right]},
          {\left[ {0.0},  {1.0} \right]}
   \right]},
   {\left[ {\left[ {0.0},  {1.0} \right]},
           {\left[ {0.0},  {0.0} \right]}
   \right]},
   {\left[ {\left[ {0.0},  {0.0} \right]},
           {\left[ {1.0},  {0.0} \right]}
   \right]},
   {\left[ {\left[ {1.0},  {0.0} \right]},
           {\left[ {1.0},  {1.0} \right]}
   \right]},
\right.\\
\left.
\displaystyle
   {\left[ {\left[ {1.0},  {0.5} \right]},
           {\left[ {0.5},  {0.0} \right]},
   \right]},
   {\left[ {\left[ {0.5},  {0.0} \right]},
           {\left[ {0.0},  {0.5} \right]}
   \right]},
   {\left[ {\left[ {0.0},  {0.5} \right]},
           {\left[ {0.5},  {1.0} \right]}
   \right]},
\right.\\
\left.
\displaystyle
   {\left[ {\left[ {0.5},  {1.0} \right]},
           {\left[ {1.0},  {0.5} \right]}
   \right]},
   {\left[ {\left[ {0.25},  {0.25} \right]},
           {\left[ {0.25},  {0.75} \right]},
   \right]},
   {\left[ {\left[ {0.25},  {0.75} \right]},
           {\left[ {0.75},  {0.75} \right]}
   \right]},
\right.\\
\left.
\displaystyle
   {\left[ {\left[ {0.75},  {0.75} \right]},
           {\left[ {0.75},  {0.25} \right]}
   \right]},
   {\left[ {\left[ {0.75},  {0.25} \right]},
           {\left[ {0.25},  {0.25} \right]}
   \right]}
\right]
\end{array}
$$
\returnType{Type: List List Point DoubleFloat}

Now we set the point sizes for all components of the graph.

\spadcommand{size1 := 6::PositiveInteger }
$$
6 
$$
\returnType{Type: PositiveInteger}

\spadcommand{size2 := 8::PositiveInteger }
$$
8 
$$
\returnType{Type: PositiveInteger}

\spadcommand{size3 := 10::PositiveInteger }

\spadcommand{lsize := [size1, size1, size1, size1, size2, size2, size2, size2, size3, size3, size3, size3]  }
$$
\left[
6,  6,  6,  6,  8,  8,  8,  8,  10,  10,  10,  10 
\right]
$$
\returnType{Type: List Polynomial Integer}

Here are the colors for the points.

\spadcommand{pc1 := pastel red() }
$$
[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the } 
Pastel \mbox{\rm palette} 
$$
\returnType{Type: Palette}

\spadcommand{pc2 := dim green() }
$$
[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the } 
Dim \mbox{\rm palette} 
$$
\returnType{Type: Palette}

\spadcommand{pc3 := pastel yellow() }
$$
[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the } 
Pastel \mbox{\rm palette} 
$$
\returnType{Type: Palette}

\spadcommand{lpc := [pc1, pc1, pc1, pc1, pc2, pc2, pc2, pc2, pc3, pc3, pc3, pc3]  }
$$
\begin{array}{@{}l}
\left[
{[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the } 
Pastel \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: } 
{1.0}} \mbox{\rm ] from the } Pastel \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Pastel \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Pastel \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Dim \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Dim \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Dim \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Dim \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Pastel \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Pastel \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Pastel \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Pastel \mbox{\rm palette} } 
 \right]
\end{array}
$$
\returnType{Type: List Palette}

Here are the colors for the lines.

\spadcommand{lc := [pastel blue(), light yellow(), dim green(), bright red(), light green(), dim yellow(), bright blue(), dark red(), pastel red(), light blue(), dim green(), light yellow()] }
$$
+\begin{array}{@{}l}
 \left[
 {[{ \mbox{\rm Hue: } {22} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the } 
 Pastel \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: } 
{1.0}} \mbox{\rm ] from the } Light \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Dim \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Bright \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Light \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Dim \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {22} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Bright \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Dark \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } 1 \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Pastel \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {22} \mbox{\rm Weight: }
{1.0}} \mbox{\rm ] from the } Light \mbox{\rm palette} },
\right. \\
\\
\left.
{[{ \mbox{\rm Hue: } {14} \mbox{\rm Weight: } {1.0}} \mbox{\rm ] from the }
Dim \mbox{\rm palette} },  {[{ \mbox{\rm Hue: } {11} \mbox{\rm Weight: } 
 {1.0}} \mbox{\rm ] from the } Light \mbox{\rm palette} } 
 \right]
\end{array}
$$
\returnType{Type: List Palette}

Now the {\tt GraphImage} is created according to the component
specifications indicated above.

\spadcommand{g := makeGraphImage(llp,lpc,lc,lsize)\$GRIMAGE  }

The \spadfunFrom{makeViewport2D}{TwoDimensionalViewport} function now
creates a {\tt TwoDimensionalViewport} for this graph according to the
list of options specified within the brackets.

\spadgraph{makeViewport2D(g,[title("Lines")])\$VIEW2D }

%See Figure #.#.

This example demonstrates the use of the {\tt GraphImage} functions
\spadfunFrom{component}{GraphImage} and \spadfunFrom{appendPoint}{GraphImage}
in adding points to an empty {\tt GraphImage}.

\spadcommand{)clear all }

\spadcommand{g := graphImage()\$GRIMAGE }
$$
\mbox{\rm Graph with } 0 \mbox{\rm point lists} 
$$
\returnType{Type: GraphImage}

\spadcommand{p1 := point [0,0]\$(Point DFLOAT) }
$$
\left[
{0.0},  {0.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p2 := point [.25,.25]\$(Point DFLOAT) }
$$
\left[
{0.25},  {0.25} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p3 := point [.5,.5]\$(Point DFLOAT) }
$$
\left[
{0.5},  {0.5} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p4 := point [.75,.75]\$(Point DFLOAT) }
$$
\left[
{0.75},  {0.75} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{p5 := point [1,1]\$(Point DFLOAT) }
$$
\left[
{1.0},  {1.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{component(g,p1)\$GRIMAGE}
\returnType{Type: Void}

\spadcommand{component(g,p2)\$GRIMAGE}
\returnType{Type: Void}

\spadcommand{appendPoint(g,p3)\$GRIMAGE}
\returnType{Type: Void}

\spadcommand{appendPoint(g,p4)\$GRIMAGE}
\returnType{Type: Void}

\spadcommand{appendPoint(g,p5)\$GRIMAGE}
\returnType{Type: Void}

\spadcommand{g1 := makeGraphImage(g)\$GRIMAGE  }

Here is the graph.

\spadgraph{makeViewport2D(g1,[title("Graph Points")])\$VIEW2D }

%
%See Figure #.#.
%

A list of points can also be made into a {\tt GraphImage} by using
the operation \spadfunFrom{coerce}{GraphImage}.  It is equivalent to adding
each point to $g2$ using \spadfunFrom{component}{GraphImage}.

\spadcommand{g2 := coerce([ [p1],[p2],[p3],[p4],[p5] ])\$GRIMAGE   }

Now, create an empty {\tt TwoDimensionalViewport}.

\spadcommand{v := viewport2D()\$VIEW2D }

\spadcommand{options(v,[title("Just Points")])\$VIEW2D }

Place the graph into the viewport.

\spadcommand{putGraph(v,g2,1)\$VIEW2D }

Take a look.

\spadgraph{makeViewport2D(v)\$VIEW2D }

%See Figure #.#.

\subsubsection{Creating a Two-Dimensional Viewport of a List of Points from a File}

The following three functions read a list of points from a
file and then draw the points and the connecting lines. The
points are stored in the file in readable form as floating point numbers
(specifically, {\tt DoubleFloat} values) as an alternating
stream of $x$- and $y$-values. For example,
\begin{verbatim}
0.0 0.0     1.0 1.0     2.0 4.0
3.0 9.0     4.0 16.0    5.0 25.0
\end{verbatim}

\begin{verbatim}
drawPoints(lp:List Point DoubleFloat):VIEW2D ==
  g := graphImage()$GRIMAGE
  for p in lp repeat
    component(g,p,pointColorDefault(),lineColorDefault(),
      pointSizeDefault())
  gi := makeGraphImage(g)$GRIMAGE
  makeViewport2D(gi,[title("Points")])$VIEW2D

drawLines(lp:List Point DoubleFloat):VIEW2D ==
  g := graphImage()$GRIMAGE
  component(g, lp, pointColorDefault(), lineColorDefault(),
    pointSizeDefault())$GRIMAGE
  gi := makeGraphImage(g)$GRIMAGE
  makeViewport2D(gi,[title("Points")])$VIEW2D

plotData2D(name, title) ==
  f:File(DFLOAT) := open(name,"input")
  lp:LIST(Point DFLOAT) := empty()
  while ((x := readIfCan!(f)) case DFLOAT) repeat
    y : DFLOAT := read!(f)
    lp := cons(point [x,y]$(Point DFLOAT), lp)
    lp
  close!(f)
  drawPoints(lp)
  drawLines(lp)
\end{verbatim}
%
This command will actually create the viewport and the graph if
the point data is in the file $``file.data''$.
\begin{verbatim}
plotData2D("file.data", "2D Data Plot")
\end{verbatim}

\subsection{Addendum: Appending a Graph to a Viewport Window Containing a Graph}
\label{ugGraphTwoDappend}

This section demonstrates how to append a two-di\-men\-sion\-al graph
to a viewport already containing other graphs.  The default {\bf draw}
command places a graph into the first {\tt GraphImage} slot position
of the {\tt TwoDimensionalViewport}.

This graph is in the first slot in its viewport.

\spadcommand{v1 := draw(sin(x),x=0..2*\%pi) }

So is this graph.

\spadcommand{v2 := draw(cos(x),x=0..2*\%pi, curveColor==light red()) }

The operation \spadfunFrom{getGraph}{TwoDimensionalViewport}
retrieves the {\tt GraphImage} $g1$ from the first slot position
in the viewport $v1$.

\spadcommand{g1 := getGraph(v1,1) }

Now \spadfunFrom{putGraph}{TwoDimensionalViewport}
places $g1$ into the the second slot position of $v2$.

\spadcommand{putGraph(v2,g1,2) }

Display the new {\tt TwoDimensionalViewport} containing both graphs.

\spadgraph{makeViewport2D(v2) }

%
%See Figure #.#.
%

\section{Three-Dimensional Graphics}
\label{ugGraphThreeD}

%
The Axiom three-di\-men\-sion\-al graphics package provides the ability to
\index{graphics!three-dimensional}
%
\begin{itemize}
%
\item generate surfaces defined by a function of two real variables
%
\item generate space curves and tubes defined by parametric equations
%
\item generate surfaces defined by parametric equations
\end{itemize}
These graphs can be modified by using various options, such as calculating
points in the spherical coordinate system or changing the polygon grid size
of a surface.

\subsection{Plotting Three-Dimensional Functions of Two Variables}
\label{ugGraphThreeDPlot}

\index{surface!two variable function}
The simplest three-di\-men\-sion\-al graph is that of a surface defined by a function
of two variables, $z = f(x,y)$.

%Original Page 197

\boxer{4.6in}{
The general format for drawing a surface defined by a formula $f(x,y)$
of two variables $x$ and $y$ is:
%
\begin{center}
{\tt draw(f(x,y), x = a..b, y = c..d, {\it options})}
\end{center}
where $a..b$ and $c..d$ define the range of $x$
and $y$, and where {\it options} prescribes zero or more
options as described in \sectionref{ugGraphThreeDOptions}.
An example of an option is $title == ``Title\ of\ Graph''.$
An alternative format involving a function $f$ is also
available.\\
}

The simplest way to plot a function of two variables is to use a formula.
With formulas you always precede the range specifications with
the variable name and an {\tt =} sign.

\spadgraph{draw(cos(x*y),x=-3..3,y=-3..3)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3d2vara.eps}}
\begin{center}
$cos(xy), x=-3..3, y=-3..3$
\end{center}
\end{minipage}

If you intend to use a function more than once,
or it is long and complex, then first
give its definition to Axiom.

\spadcommand{f(x,y) == sin(x)*cos(y) }
\returnType{Type: Void}

To draw the function, just give its name and drop the variables
from the range specifications.
Axiom compiles your function for efficient computation
of data for the graph.
Notice that Axiom uses the text of your function as a
default title.

\spadgraph{draw(f,-\%pi..\%pi,-\%pi..\%pi) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3d2varb.eps}}
\begin{center}
$f, -\pi..\pi, -\pi..\pi$
\end{center}
\end{minipage}

%Original Page 198

\subsection{Plotting Three-Dimensional Parametric Space Curves}
\label{ugGraphThreeDParm}

A second kind of three-di\-men\-sion\-al graph is a three-di\-men\-sion\-al space curve
\index{curve!parametric space}
defined by the parametric equations for $x(t)$, $y(t)$,
\index{parametric space curve}
and $z(t)$ as a function of an independent variable $t$.

\boxer{4.6in}{
The general format for drawing a three-di\-men\-sion\-al space curve defined by
parametric formulas $x = f(t)$, $y = g(t)$, and
$z = h(t)$ is:
%
\begin{center}
{\tt draw(curve(f(t),g(t),h(t)), t = a..b, {\it options})}
\end{center}
where $a..b$ defines the range of the independent variable
$t$, and where {\it options} prescribes zero or more options
as described in \sectionref{ugGraphThreeDOptions}.
An example of an option is $title == ``Title\ of\ Graph''.$
An alternative format involving functions $f$, $g$ and
$h$ is also available.\\
}

If you use explicit formulas to draw a space curve, always precede
the range specification with the variable name and an
{\tt =} sign.

\spadgraph{draw(curve(5*cos(t), 5*sin(t),t), t=-12..12)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dpsca.eps}}
\begin{center}
$curve(5cos(t), 5sin(t),t),\quad t=-12..12$
\end{center}
\end{minipage}

Alternatively, you can draw space curves by referring to functions.

\spadcommand{i1(t:DFLOAT):DFLOAT == sin(t)*cos(3*t/5) }
\begin{verbatim}
   Function declaration i1 : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

This is useful if the functions are to be used more than once \ldots

\spadcommand{i2(t:DFLOAT):DFLOAT == cos(t)*cos(3*t/5) }
\begin{verbatim}
   Function declaration i2 : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

or if the functions are long and complex.

\spadcommand{i3(t:DFLOAT):DFLOAT == cos(t)*sin(3*t/5) }
\begin{verbatim}
   Function declaration i3 : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

%Original Page 199

Give the names of the functions and
drop the variable name specification in the second argument.
Again, Axiom supplies a default title.

\spadgraph{draw(curve(i1,i2,i3),0..15*\%pi) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dpscb.eps}}
\begin{center}
$curve(i1,i2,i3),\quad 0..15\pi$
\end{center}
\end{minipage}

\subsection{Plotting Three-Dimensional Parametric Surfaces}
\label{ugGraphThreeDPar}

\index{surface!parametric}
A third kind of three-di\-men\-sion\-al graph is a surface defined by
\index{parametric surface}
parametric equations for $x(u,v)$, $y(u,v)$, and
$z(u,v)$ of two independent variables $u$ and $v$.

\boxer{4.6in}{
The general format for drawing a three-di\-men\-sion\-al graph defined by
parametric formulas $x = f(u,v)$, $y = g(u,v)$,
and $z = h(u,v)$ is:
%
\begin{center}
{\tt draw(surface(f(u,v),g(u,v),h(u,v)), u = a..b, v = c..d, {\it options})}
\end{center}
where $a..b$ and $c..d$ define the range of the
independent variables $u$ and $v$, and where
{\it options} prescribes zero or more options as described in
\sectionref{ugGraphThreeDOptions}.
An example of an option is $title == ``Title\ of\ Graph''.$
An alternative format involving functions $f$, $g$ and
$h$ is also available.\\
}

This example draws a graph of a surface plotted using the
parabolic cylindrical coordinate system option.
\index{coordinate system!parabolic cylindrical}
The values of the functions supplied to {\bf surface} are
\index{parabolic cylindrical coordinate system}
interpreted in coordinates as given by a {\tt coordinates} option,
here as parabolic cylindrical coordinates (see
\sectionref{ugGraphCoord}.

\spadgraph{draw(surface(u*cos(v), u*sin(v), v*cos(u)), u=-4..4, v=0..\%pi, coordinates== parabolicCylindrical)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dpsa.eps}}
\begin{center}
$surface(u cos(v), u sin(v), v cos(u)), u=-4..4, v=0..\pi, 
coordinates==parabolicCylindrical$
\end{center}
\end{minipage}

%Original Page 200

Again, you can graph these parametric surfaces using functions,
if the functions are long and complex.

Here we declare the types of arguments and values to be of type
{\tt DoubleFloat}.

\spadcommand{n1(u:DFLOAT,v:DFLOAT):DFLOAT == u*cos(v) }
\begin{verbatim}
   Function declaration n1 : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

As shown by previous examples, these declarations are necessary.

\spadcommand{n2(u:DFLOAT,v:DFLOAT):DFLOAT == u*sin(v) }
\begin{verbatim}
   Function declaration n2 : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

In either case, Axiom compiles the functions
when needed to graph a result.

\spadcommand{n3(u:DFLOAT,v:DFLOAT):DFLOAT == u }
\begin{verbatim}
   Function declaration n3 : DoubleFloat -> DoubleFloat has been added 
      to workspace.
\end{verbatim}
\returnType{Type: Void}

Without these declarations, you have to suffix floats
with $@DFLOAT$ to get a {\tt DoubleFloat} result.
However, a call here with an unadorned float produces a {\tt DoubleFloat}.

\spadcommand{n3(0.5,1.0)}
\begin{verbatim}
   Compiling function n3 with type (DoubleFloat,DoubleFloat) -> 
      DoubleFloat 
\end{verbatim}
\returnType{Type: DoubleFloat}

Draw the surface by referencing the function names, this time
choosing the toroidal coordinate system.
\index{coordinate system!toroidal}
\index{toroidal coordinate system}

\spadgraph{draw(surface(n1,n2,n3), 1..4, 1..2*\%pi, coordinates == toroidal(1\$DFLOAT)) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dpsb.eps}}
\begin{center}
$surface(n1,n2,n3), 1..4, 1..2\pi, coordinates == toroidal(1\$DFLOAT)$
\end{center}
\end{minipage}

\subsection{Axiom Images}
\newpage
{\center{\includegraphics{ps/v0page1.eps}}}

\newpage
{\center{\includegraphics{ps/v0page2.eps}}}

\newpage
{\center{\includegraphics{ps/v0page3.eps}}}

\newpage
{\center{\includegraphics{ps/v0page4.eps}}}

\newpage
{\center{\includegraphics{ps/v0page5.eps}}}

\newpage
{\center{\includegraphics{ps/v0page6.eps}}}

\newpage
{\center{\includegraphics{ps/v0page7.eps}}}

\newpage
{\center{\includegraphics{ps/v0page8.eps}}}

\newpage
\subsection{Three-Dimensional Options}
\label{ugGraphThreeDOptions}

\index{graphics!3D options}
The {\bf draw} commands optionally take an optional list of options such
as {\tt coordinates} as shown in the last example.
Each option is given by the syntax: $name$ {\tt ==} $value$.
Here is a list of the available options in the order that they are
described below:

\begin{tabular}{llll}
title&coordinates&var1Steps\\
style&tubeRadius&var2Steps\\
colorFunction&tubePoints&space\\
\end{tabular}

%Original Page 201

The option $title$ gives your graph a title.
\index{graphics!3D options!title}

\spadgraph{draw(cos(x*y),x=0..2*\%pi,y=0..\%pi,title == "Title of Graph") }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptttl.eps}}
\begin{center}
$cos(xy),x=0..2\pi,y=0..\pi,\quad title == "{\rm Title\ of\ Graph}"$
\end{center}
\end{minipage}

The $style$ determines which of four rendering algorithms is used for
\index{rendering}
the graph.
The choices are
{\tt "wireMesh"}, {\tt "solid"}, {\tt "shade"}, and {\tt "smooth"}.

\spadgraph{draw(cos(x*y),x=-3..3,y=-3..3, style=="smooth", title=="Smooth Option")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptsty.eps}}
\begin{center}
$cos(xy),x=-3..3,y=-3..3, style=="smooth", title=="{\rm Smooth\ Option}"$
\end{center}
\end{minipage}

In all but the wire-mesh style, polygons in a surface or tube plot
are normally colored in a graph according to their
$z$-coordinate value.  Space curves are colored according to their
parametric variable value.
\index{graphics!3D options!color function}
To change this, you can give a coloring function.
\index{function!coloring}
The coloring function is sampled across the range of its arguments, then
normalized onto the standard Axiom colormap.

A function of one variable  makes the color depend on the
value of the parametric variable specified for a tube plot.

\spadcommand{color1(t) == t }
\returnType{Type: Void}

%Original Page 202

\spadgraph{draw(curve(sin(t), cos(t),0), t=0..2*\%pi, tubeRadius == .3, colorFunction == color1) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptcf1.eps}}
\begin{center}
$curve(sin(t), cos(t),0), t=0..2\pi, tubeRadius== .3, colorFunction== color1$
\end{center}
\end{minipage}

A function of two variables makes the color depend on the
values of the independent variables.

\spadcommand{color2(u,v) == u**2 - v**2 }
\returnType{Type: Void}

Use the option {\tt colorFunction} for special coloring.

\spadgraph{draw(cos(u*v), u=-3..3, v=-3..3, colorFunction == color2) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptcf2.eps}}
\begin{center}
$cos(uv), u=-3..3, v=-3..3, colorFunction == color2$
\end{center}
\end{minipage}

With a three variable function, the
color also depends on the value of the function.

\spadcommand{color3(x,y,fxy) == sin(x*fxy) + cos(y*fxy) }
\returnType{Type: Void}

%Original Page 203

\spadgraph{draw(cos(x*y), x=-3..3, y=-3..3, colorFunction == color3) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptcf3.eps}}
\begin{center}
$cos(xy), x=-3..3, y=-3..3, colorFunction == color3$
\end{center}
\end{minipage}

Normally the Cartesian coordinate system is used.
\index{Cartesian!coordinate system}
To change this, use the {\tt coordinates} option.
\index{coordinate system!Cartesian}
For details, see \sectionref{ugGraphCoord}.

\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 }
\begin{verbatim}
   Function declaration m : (DoubleFloat,DoubleFloat) -> DoubleFloat 
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Use the spherical
\index{spherical coordinate system}
coordinate system.
\index{coordinate system!spherical}

\spadgraph{draw(m, 0..2*\%pi,0..\%pi, coordinates == spherical, style=="shade") }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptcrd.eps}}
\begin{center}
$m, 0..2\pi,0..\pi, coordinates == spherical, style=="shade"$
\end{center}
\end{minipage}

\index{tube}
Space curves may be displayed as tubes with polygonal cross sections.\\
Two options, {\tt tubeRadius} and {\tt tubePoints},\\  
control the size and shape of this cross section.
%

%Original Page 204

The {\tt tubeRadius} option specifies the radius of the tube that
\index{tube!radius}
encircles the specified space curve.

\spadgraph{draw(curve(sin(t),cos(t),0),t=0..2*\%pi, style=="shade", tubeRadius == .3)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptrad.eps}}
\begin{center}
$curve(sin(t),cos(t),0),t=0..2\pi, style=="shade", tubeRadius == .3$
\end{center}
\end{minipage}

The {\tt tubePoints} option specifies the number of vertices
\index{tube!points in polygon}
defining the polygon that is used to create a tube around the
specified space curve.
The larger this number is, the more cylindrical the tube becomes.

\spadgraph{draw(curve(sin(t), cos(t), 0), t=0..2*\%pi, style=="shade", tubeRadius == .25, tubePoints == 3)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptpts.eps}}
\begin{center}
$curve(sin(t),cos(t),0), t=0..2\pi, style=="shade", tubeRadius == .25, 
tubePoints == 3$
\end{center}
\end{minipage}

\index{graphics!3D options!variable steps}

Options \spadfunFrom{var1Steps}{DrawOption} and
\spadfunFrom{var2Steps}{DrawOption} specify the number of intervals into
which the grid defining a surface plot is subdivided with respect to the
first and second parameters of the surface function(s).

\spadgraph{draw(cos(x*y),x=-3..3,y=-3..3, style=="shade", var1Steps == 30, var2Steps == 30)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3doptvb.eps}}
\begin{center}
$cos(xy),x=-3..3,y=-3..3, style=="shade", var1Steps == 30, var2Steps == 30$
\end{center}
\end{minipage}

The {\tt space} option
of a {\bf draw} command lets you build multiple graphs in three space.
To use this option, first create an empty three-space object,
then use the {\tt space} option thereafter.
There is no restriction as to the number or kinds
of graphs that can be combined this way.

%Original Page 205

Create an empty three-space object.

\spadcommand{s := create3Space()\$(ThreeSpace DFLOAT) }
$$
{3-Space with }0 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 }
\begin{verbatim}
   Function declaration m : (DoubleFloat,DoubleFloat) -> DoubleFloat 
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Add a graph to this three-space object.
The new graph destructively inserts the graph
into $s$.

\spadgraph{draw(m,0..\%pi,0..2*\%pi, coordinates == spherical, space == s) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dmult1a.eps}}
\begin{center}
$m,0..\pi,0..2\pi, coordinates == spherical, space == s$
\end{center}
\end{minipage}

Add a second graph to $s$.

\spadgraph{v := draw(curve(1.5*sin(t), 1.5*cos(t),0), t=0..2*\%pi, tubeRadius == .25, space == s)  }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dmult1b.eps}}
\begin{center}
$curve(1.5 sin(t), 1.5 cos(t),0), t=0..2\pi, tubeRadius == .25, space == s$
\end{center}
\end{minipage}

A three-space object can also be obtained from an existing three-di\-men\-sion\-al viewport
using the \spadfunFrom{subspace}{ThreeSpace} command.
You can then use {\bf makeViewport3D} to create a viewport window.

Assign to $subsp$ the three-space object in viewport $v$.

\spadcommand{subsp := subspace v  }

%Original Page 206

Reset the space component of $v$ to the value of $subsp$.

\spadcommand{subspace(v, subsp)  }

Create a viewport window from a three-space object.

\spadgraph{makeViewport3D(subsp,"Graphs") }

\subsection{The makeObject Command}
\label{ugGraphMakeObject}

An alternate way to create multiple graphs is to use
{\bf makeObject}.
The {\bf makeObject} command is similar to the {\bf draw}
command, except that it returns a three-space object rather than a
{\tt ThreeDimensionalViewport}.
In fact, {\bf makeObject} is called by the {\bf draw}
command to create the {\tt ThreeSpace} then
\spadfunFrom{makeViewport3D}{ThreeDimensionalViewport} to create a
viewport window.

\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 }
\begin{verbatim}
   Function declaration m : (DoubleFloat,DoubleFloat) -> DoubleFloat 
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Do the last example a new way.
First use {\bf makeObject} to
create a three-space object $sph$.

\spadcommand{sph := makeObject(m, 0..\%pi, 0..2*\%pi, coordinates==spherical)}
\begin{verbatim}
   Compiling function m with type (DoubleFloat,DoubleFloat) -> 
      DoubleFloat 
\end{verbatim}
$$
{3-Space with }1 \mbox{\rm component} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

Add a second object to $sph$.

\spadcommand{makeObject(curve(1.5*sin(t), 1.5*cos(t), 0), t=0..2*\%pi, space == sph, tubeRadius == .25) }
\begin{verbatim}
   Compiling function %D with type DoubleFloat -> DoubleFloat 
   Compiling function %F with type DoubleFloat -> DoubleFloat 
   Compiling function %H with type DoubleFloat -> DoubleFloat 
\end{verbatim}
$$
{3-Space with }2 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

Create and display a viewport
containing $sph$.

\spadgraph{makeViewport3D(sph,"Multiple Objects") }

Note that an undefined {\tt ThreeSpace} parameter declared in a
{\bf makeObject} or {\bf draw} command results in an error.
Use the \spadfunFrom{create3Space}{ThreeSpace} function to define a
{\tt ThreeSpace}, or obtain a {\tt ThreeSpace} that has been
previously generated before including it in a command line.

\subsection{Building Three-Dimensional Objects From Primitives}
\label{ugGraphThreeDBuild}

Rather than using the {\bf draw} and {\bf makeObject} commands,
\index{graphics!advanced!build 3D objects}
you can create three-di\-men\-sion\-al graphs from primitives.
Operation \spadfunFrom{create3Space}{ThreeSpace} creates a
three-space object to which points, curves and polygons
can be added using the operations from the {\tt ThreeSpace}
domain.
The resulting object can then be displayed in a viewport using
\spadfunFrom{makeViewport3D}{ThreeDimensionalViewport}.

Create the empty three-space object $space$.

\spadcommand{space := create3Space()\$(ThreeSpace DFLOAT) }
$$
{3-Space with }0 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

Objects can be sent to this $space$ using the operations
exported by the {\tt ThreeSpace} domain.
\index{ThreeSpace}
The following examples place curves into $space$.

%Original Page 207

Add these eight curves to the space.

\spadcommand{closedCurve(space,[ [0,30,20], [0,30,30], [0,40,30], [0,40,100], [0,30,100],[0,30,110], [0,60,110], [0,60,100], [0,50,100], [0,50,30], [0,60,30], [0,60,20] ])  }
$$
{3-Space with }1 \mbox{\rm component} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{closedCurve(space,[ [80,0,30], [80,0,100], [70,0,110], [40,0,110], [30,0,100], [30,0,90], [40,0,90], [40,0,95], [45,0,100], [65,0,100], [70,0,95], [70,0,35] ])  }
$$
{3-Space with }2 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{closedCurve(space,[ [70,0,35], [65,0,30], [45,0,30], [40,0,35], [40,0,60], [50,0,60], [50,0,70], [30,0,70], [30,0,30], [40,0,20], [70,0,20], [80,0,30] ])  }
$$
{3-Space with }3 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{closedCurve(space,[ [0,70,20], [0,70,110], [0,110,110], [0,120,100], [0,120,70], [0,115,65], [0,120,60], [0,120,30], [0,110,20], [0,80,20], [0,80,30], [0,80,20] ])  }
$$
{3-Space with }4 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{closedCurve(space,[ [0,105,30], [0,110,35], [0,110,55], [0,105,60], [0,80,60], [0,80,70], [0,105,70], [0,110,75], [0,110,95], [0,105,100], [0,80,100], [0,80,20], [0,80,30] ])  }
$$
{3-Space with }5 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{closedCurve(space,[ [140,0,20], [140,0,110], [130,0,110], [90,0,20], [101,0,20],[114,0,50], [130,0,50], [130,0,60], [119,0,60], [130,0,85], [130,0,20] ])  }
$$
{3-Space with }6 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{closedCurve(space,[ [0,140,20], [0,140,110], [0,150,110], [0,170,50], [0,190,110], [0,200,110], [0,200,20], [0,190,20], [0,190,75], [0,175,35], [0,165,35],[0,150,75], [0,150,20] ])  }
$$
{3-Space with }7 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

%Original Page 208

\spadcommand{closedCurve(space,[ [200,0,20], [200,0,110], [189,0,110], [160,0,45], [160,0,110], [150,0,110], [150,0,20], [161,0,20], [190,0,85], [190,0,20] ])  }
$$
{3-Space with }8 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

Create and display the viewport using {\bf makeViewport3D}.
Options may also be given but here are displayed as a list with values
enclosed in parentheses.

\spadgraph{makeViewport3D(space, title == "Letters") }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dbuilda.eps}}
\begin{center}
$makeViewport3D(space, title == "Letters")$
\end{center}
\end{minipage}

\subsubsection{Cube Example}

As a second example of the use of primitives, we generate a cube using a
polygon mesh.
It is important to use a consistent orientation of the polygons for
correct generation of three-di\-men\-sion\-al objects.

Again start with an empty three-space object.

\spadcommand{spaceC := create3Space()\$(ThreeSpace DFLOAT) }
$$
{3-Space with }0 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

For convenience,
give {\tt DoubleFloat} values $+1$ and $-1$ names.

\spadcommand{x: DFLOAT := 1 }
$$
1.0 
$$
\returnType{Type: DoubleFloat}

\spadcommand{y: DFLOAT := -1 }
$$
-{1.0} 
$$
\returnType{Type: DoubleFloat}

Define the vertices of the cube.

\spadcommand{a := point [x,x,y,1::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
{1.0},  {1.0},  -{1.0},  {1.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{b := point [y,x,y,4::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
-{1.0},  {1.0},  -{1.0},  {4.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

%Original Page 209

\spadcommand{c := point [y,x,x,8::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
-{1.0},  {1.0},  {1.0},  {8.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{d := point [x,x,x,12::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
{1.0},  {1.0},  {1.0},  {12.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{e := point [x,y,y,16::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
{1.0},  -{1.0},  -{1.0},  {16.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{f := point [y,y,y,20::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
-{1.0},  -{1.0},  -{1.0},  {20.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{g := point [y,y,x,24::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
-{1.0},  -{1.0},  {1.0},  {24.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

\spadcommand{h := point [x,y,x,27::DFLOAT]\$(Point DFLOAT)  }
$$
\left[
{1.0},  -{1.0},  {1.0},  {27.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

Add the faces of the cube as polygons to the space using a
consistent orientation.

\spadcommand{polygon(spaceC,[d,c,g,h])  }
$$
{3-Space with }1 \mbox{\rm component} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{polygon(spaceC,[d,h,e,a])  }
$$
{3-Space with }2 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{polygon(spaceC,[c,d,a,b])  }
$$
{3-Space with }3 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{polygon(spaceC,[g,c,b,f])  }
$$
{3-Space with }4 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

%Original Page 210

\spadcommand{polygon(spaceC,[h,g,f,e])  }
$$
{3-Space with }5 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

\spadcommand{polygon(spaceC,[e,f,b,a])  }
$$
{3-Space with }6 \mbox{\rm components} 
$$
\returnType{Type: ThreeSpace DoubleFloat}

Create and display the viewport.

\spadgraph{makeViewport3D(spaceC, title == "Cube") }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dbuildb.eps}}
\begin{center}
$makeViewport3D(spaceC, title == "Cube")$
\end{center}
\end{minipage}

\subsection{Coordinate System Transformations}
\label{ugGraphCoord}
\index{graphics!advanced!coordinate systems}

The {\tt CoordinateSystems} package provides coordinate transformation
functions that map a given data point from the coordinate system specified
into the Cartesian coordinate system.
\index{CoordinateSystems}
The default coordinate system, given a triplet $(f(u,v), u, v)$, assumes
that $z = f(u, v)$, $x = u$ and $y = v$,
that is, reads the coordinates in $(z, x, y)$ order.

\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == u**2 }
\begin{verbatim}
   Function declaration m : (DoubleFloat,DoubleFloat) -> DoubleFloat 
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Graph plotted in default coordinate system.

\spadgraph{draw(m,0..3,0..5) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/defcoord.eps}}
\begin{center}
$m,0..3,0..5$
\end{center}
\end{minipage}

%Original Page 211

The $z$ coordinate comes first since the first argument of
the {\bf draw} command gives its values.
In general, the coordinate systems Axiom provides, or any
that you make up, must provide a map to an $(x, y, z)$ triplet in
order to be compatible with the
\spadfunFrom{coordinates}{DrawOption} {\tt DrawOption}.
\index{DrawOption}
Here is an example.

Define the identity function.

\spadcommand{cartesian(point:Point DFLOAT):Point DFLOAT == point }
\begin{verbatim}
   Function declaration cartesian : Point DoubleFloat -> Point 
      DoubleFloat has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Pass $cartesian$ as the \spadfunFrom{coordinates}{DrawOption}
parameter to the {\bf draw} command.

\spadgraph{draw(m,0..3,0..5,coordinates==cartesian) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/cartcoord.eps}}
\begin{center}
$m, 0..3,0..5, coordinates==cartesian$
\end{center}
\end{minipage}

What happened?  The option {\tt coordinates == cartesian} directs
Axiom to treat the dependent variable $m$ defined by $m=u^2$ as the
$x$ coordinate.  Thus the triplet of values $(m, u, v)$ is transformed
to coordinates $(x, y, z)$ and so we get the graph of $x=y^2$.

Here is another example.
The \spadfunFrom{cylindrical}{CoordinateSystems} transform takes
\index{coordinate system!cylindrical}
input of the form $(w,u,v)$, interprets it in the order
\index{cylindrical coordinate system}
($r$,$\theta$,$z$)
and maps it to the Cartesian coordinates
$x=r\cos(\theta)$, $y=r\sin(\theta)$, $z=z$
in which
$r$ is the radius,
$\theta$ is the angle and
$z$ is the z-coordinate.

An example using the \spadfunFrom{cylindrical}{CoordinateSystems}
coordinates for the constant $r = 3$.

\spadcommand{f(u:DFLOAT,v:DFLOAT):DFLOAT == 3 }
\begin{verbatim}
   Function declaration f : (DoubleFloat,DoubleFloat) -> DoubleFloat 
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

%Original Page 212

Graph plotted in cylindrical coordinates.

\spadgraph{draw(f,0..\%pi,0..6,coordinates==cylindrical) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/cylcoord.eps}}
\begin{center}
$f, 0..\pi,0..6, coordinates==cylindrical$
\end{center}
\end{minipage}

Suppose you would like to specify $z$ as a function of
$r$ and $\theta$ instead of just $r$?
Well, you still can use the {\bf cylindrical} Axiom
transformation but we have to reorder the triplet before
passing it to the transformation.

First, let's create a point to
work with and call it $pt$ with some color $col$.

\spadcommand{col := 5 }
$$
5 
$$
\returnType{Type: PositiveInteger}

\spadcommand{pt := point[1,2,3,col]\$(Point DFLOAT)  }
$$
\left[
{1.0},  {2.0},  {3.0},  {5.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

The reordering you want is
$(z,r, \theta)$ to
$(r, \theta,z)$
so that the first element is moved to the third element, while the second
and third elements move forward and the color element does not change.

Define a function {\bf reorder} to reorder the point elements.

\spadcommand{reorder(p:Point DFLOAT):Point DFLOAT == point[p.2, p.3, p.1, p.4] }
\begin{verbatim}
   Function declaration reorder : Point DoubleFloat -> Point 
      DoubleFloat has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

The function moves the second and third elements
forward but the color does not change.

\spadcommand{reorder pt }
$$
\left[
{2.0},  {3.0},  {1.0},  {5.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

The function {\bf newmap} converts our reordered version of
the cylindrical coordinate system to the standard
$(x,y,z)$ Cartesian system.

\spadcommand{newmap(pt:Point DFLOAT):Point DFLOAT == cylindrical(reorder pt)  }
\begin{verbatim}
   Function declaration newmap : Point DoubleFloat -> Point DoubleFloat
      has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

\spadcommand{newmap pt  }
$$
\left[
-{1.9799849932008908},  {0.28224001611973443},  {1.0},  {5.0} 
\right]
$$
\returnType{Type: Point DoubleFloat}

%Original Page 213

Graph the same function $f$ using the coordinate mapping of the function
$newmap$, so it is now interpreted as
$z=3$:

\spadgraph{draw(f,0..3,0..2*\%pi,coordinates==newmap) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/newmap.eps}}
\begin{center}
$f,0..3,0..2\pi,coordinates==newmap$
\end{center}
\end{minipage}

% I think this is good to say here: it shows a lot of depth. RSS
%{\sloppy
The {\tt CoordinateSystems} package exports the following
\index{coordinate system}
operations:\\
{\bf bipolar}, {\bf bipolarCylindrical}, {\bf cartesian}, \\
{\bf conical}, {\bf cylindrical}, {\bf elliptic},\\
{\bf ellipticCylindrical}, {\bf oblateSpheroidal}, {\bf parabolic},\\
{\bf parabolicCylindrical}, {\bf paraboloidal}, {\bf polar},\\
{\bf prolateSpheroidal}, {\bf spherical}, and {\bf toroidal}.\\
Use Browse or the {\tt )show} system command
\index{show}
to get more information.

\subsection{Three-Dimensional Clipping}
\label{ugGraphClip}

A three-di\-men\-sion\-al graph can be explicitly clipped within the {\bf draw}
\index{graphics!advanced!clip}
command by indicating a minimum and maximum threshold for the
\index{clipping}
given function definition.
These thresholds can be defined using the Axiom {\bf min}
and {\bf max} functions.

\begin{verbatim}
gamma(x,y) ==
  g := Gamma complex(x,y)
  point [x, y, max( min(real g, 4), -4), argument g]
\end{verbatim}

Here is an example that clips
the gamma function in order to eliminate the extreme divergence it creates.

\spadgraph{draw(gamma,-\%pi..\%pi,-\%pi..\%pi,var1Steps==50,var2Steps==50) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/clipgamma.eps}}
\begin{center}
$gamma, -\pi..\pi, -\pi..\pi, var1Steps==50, var2Steps==50$
\end{center}
\end{minipage}

\subsection{Three-Dimensional Control-Panel}
\label{ugGraphThreeDControl}

%Original Page 214

\index{graphics!3D control-panel}
Once you have created a viewport, move your mouse to the viewport
and click with your left mouse button.
This displays a control-panel on the side of the viewport
that is closest to where you clicked.

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=1.0]{ps/3dctrl.eps}}
\begin{center}
Three-dimensional control-panel.
\end{center}
\end{minipage}

\subsubsection{Transformations}

We recommend you first select the {\bf Bounds} button while
\index{graphics!3D control-panel!transformations}
executing transformations since the bounding box displayed
indicates the object's position as it changes.
%
\begin{description}
%
\item[Rotate:]  A rotation transformation occurs by clicking the mouse
\index{graphics!3D control-panel!rotate}
within the {\bf Rotate} window in the upper left corner of the
control-panel.
The rotation is computed in spherical coordinates, using the
horizontal mouse position to increment or decrement the value of
the longitudinal angle $\theta$ within the
range of 0 to 2$\pi$ and the vertical mouse position
to increment or decrement the value of the latitudinal angle
$\phi$ within the range of -$\pi$
to $\pi$.
The active mode of rotation is displayed in green on a color
monitor or in clear text on a black and white monitor, while the
inactive mode is displayed in red for color display or a mottled
pattern for black and white.
%
\begin{description}
%
\item[origin:]  The {\bf origin} button indicates that the
rotation is to occur with respect to the origin of the viewing space, that is
indicated by the axes.

%%Original Page 215

\item[object:]  The {\bf object} button indicates that the
rotation is to occur with respect to the center of volume of the object,
independent of the axes' origin position.
\end{description}
%
\item[Scale:]  A scaling transformation occurs by clicking the mouse
\index{graphics!3D control-panel!scale}
within the {\bf Scale} window in the upper center of the
control-panel, containing a zoom arrow.
The axes along which the scaling is to occur are indicated by
selecting the appropriate button above the zoom arrow window.
The selected axes are displayed in green on a color monitor or in
clear text on a black and white monitor, while the unselected axes
are displayed in red for a color display or a mottled pattern for
black and white.
%
\begin{description}
%
\item[uniform:]  Uniform scaling along the {\tt x}, {\tt y}
and {\tt z} axes occurs when all the axes buttons are selected.
%
\item[non-uniform:]  If any of the axes buttons are
not selected, non-uniform scaling occurs, that is, scaling occurs only in the
direction of the axes that are selected.
\end{description}
%
\item[Translate:]  Translation occurs by indicating with the mouse in the
\index{graphics!3D control-panel!translate}
{\bf Translate} window the direction you want the graph to move.
This window is located in the upper right corner of the
control-panel and contains a potentiometer with crossed arrows
pointing up, down, left and right.
Along the top of the {\bf Translate} window are three buttons
({\bf XY},
{\bf XZ}, and {\bf YZ}) indicating the three orthographic projection planes.
Each orientates the group as a view into that plane.
Any translation of the graph occurs only along this plane.
\end{description}

\subsubsection{Messages}

\index{graphics!3D control-panel!messages}

The window directly below the potentiometer windows for transformations is
used to display system messages relating to the viewport, the control-panel
and the current graph displaying status.

\subsubsection{Colormap}

\index{graphics!3D control-panel!color map}

Directly below the message window is the colormap range indicator
window.
\index{colormap}
The Axiom Colormap shows a sampling of the spectrum from
which hues can be drawn to represent the colors of a surface.
The Colormap is composed of five shades for each of the hues along
this spectrum.
By moving the markers above and below the Colormap, the range of
hues that are used to color the existing surface are set.
The bottom marker shows the hue for the low end of the color range
and the top marker shows the hue for the upper end of the range.
Setting the bottom and top markers at the same hue results in
monochromatic smooth shading of the graph when {\bf Smooth} mode is selected.
At each end of the Colormap are {\bf +} and {\bf -} buttons.
When clicked on, these increment or decrement the top or bottom
marker.

\subsubsection{Buttons}
\index{graphics!3D control-panel!buttons}

%Original Page 216

Below the Colormap window and to the left are located various
buttons that determine the characteristics of a graph.
The buttons along the bottom and right hand side all have special
meanings; the remaining buttons in the first row indicate the mode
or style used to display the graph.
The second row are toggles that turn on or off a property of the
graph.
On a color monitor, the property is on if green (clear text, on a
monochrome monitor) and off if red (mottled pattern, on a
monochrome monitor).
Here is a list of their functions.
%
\begin{description}
%
\item[Wire] displays surface and tube plots as a
\index{graphics!3D control-panel!wire}
wireframe image in a single color (blue) with no hidden surfaces removed,
or displays space curve plots in colors based upon their parametric variables.
This is the fastest mode for displaying a graph.
This is very useful when you
want to find a good orientation of your graph.
%
\item[Solid] displays the graph with hidden
\index{graphics!3D control-panel!solid}
surfaces removed, drawing each polygon beginning with the furthest
from the viewer.
The edges of the polygons are displayed in the hues specified by
the range in the Colormap window.
%
\item[Shade] displays the graph with hidden
\index{graphics!3D control-panel!shade}
surfaces removed and with the polygons shaded, drawing each
polygon beginning with the furthest from the viewer.
Polygons are shaded in the hues specified by the range in the
Colormap window using the Phong illumination model.
\index{Phong!illumination model}
%
\item[Smooth] displays the graph using a
\index{graphics!3D control-panel!smooth}
renderer that computes the graph one line at a time.
The location and color of the graph at each visible point on the
screen are determined and displayed using the Phong illumination
\index{Phong!illumination model}
model.
Smooth shading is done in one of two ways, depending on the range
selected in the colormap window and the number of colors available
from the hardware and/or window manager.
When the top and bottom markers of the colormap range are set to
different hues, the graph is rendered by dithering between the
\index{dithering}
transitions in color hue.
When the top and bottom markers of the colormap range are set to
the same hue, the graph is rendered using the Phong smooth shading
model.
\index{Phong!smooth shading model}
However, if enough colors cannot be allocated for this purpose,
the renderer reverts to the color dithering method until a
sufficient color supply is available.
For this reason, it may not be possible to render multiple Phong
smooth shaded graphs at the same time on some systems.
%
\item[Bounds] encloses the entire volume of the
viewgraph within a bounding box, or removes the box if previously selected.
\index{graphics!3D control-panel!bounds}
The region that encloses the entire volume of the viewport graph is displayed.

%%Original Page 217

\item[Axes] displays Cartesian
\index{graphics!3D control-panel!axes}
coordinate axes of the space, or turns them off if previously selected.
%
\item[Outline] causes
\index{graphics!3D control-panel!outline}
quadrilateral polygons forming the graph surface to be outlined in black when
the graph is displayed in {\bf Shade} mode.
%
\item[BW] converts a color viewport to black and white, or vice-versa.
\index{graphics!3D control-panel!bw}
When this button is selected the
control-panel and viewport switch to an immutable colormap composed of a range
of grey scale patterns or tiles that are used wherever shading is necessary.
%
\item[Light] takes you to a control-panel described below.
%
\item[ViewVolume] takes you to another control-panel as described below.
\index{graphics!3D control-panel!save}
%
\item[Save] creates a menu of the possible file types that can
be written using the control-panel.
The {\bf Exit} button leaves the save menu.
The {\bf Pixmap} button writes an Axiom pixmap of
\index{graphics!3D control-panel!pixmap}
the current viewport contents.  The file is called {\bf axiom3D.pixmap} and is
located in the directory from which Axiom or {\bf viewalone} was
started.
The {\bf PS} button writes the current viewport contents to
\index{graphics!3D control-panel!ps}
PostScript output rather than to the viewport window.
By default the file is called {\bf axiom3D.ps}; however, if a file
\index{file!.Xdefaults @{\bf .Xdefaults}}
name is specified in the user's {\bf .Xdefaults} file it is
\index{graphics!.Xdefaults!PostScript file name}
used.
The file is placed in the directory from which the Axiom or
{\bf viewalone} session was begun.
See also the \spadfunFrom{write}{ThreeDimensionalViewport}
function.
\index{PostScript}
%
\item[Reset] returns the object transformation
\index{graphics!3D control-panel!reset}
characteristics back to their initial states.
%
\item[Hide] causes the control-panel for the
\index{graphics!3D control-panel!hide}
corresponding viewport to disappear from the screen.
%
\item[Quit]  queries whether the current viewport
\index{graphics!3D control-panel!quit}
session should be terminated.
\end{description}

\subsubsection{Light}

\index{graphics!3D control-panel!light}

%>>>\begin{figure}[htbp]
%>>>\begin{picture}(183,252)(-125,0)
%>>>\special{psfile=ps/3dlight.ps}
%>>>\end{picture}
%>>>\caption{Three-Dimensional Lighting Panel.}
%>>>\end{figure}

The {\bf Light} button changes the control-panel into the
{\bf Lighting Control-Panel}.  At the top of this panel, the three axes
are shown with the same orientation as the object.  A light vector from
the origin of the axes shows the current position of the light source
relative to the object.  At the bottom of the panel is an {\bf Abort}
button that cancels any changes to the lighting that were made, and a
{\bf Return} button that carries out the current set of lighting changes
on the graph.
%
\begin{description}
%
\item[XY:]  The {\bf XY} lighting axes window is below the
\index{graphics!3D control-panel!move xy}
{\bf Lighting Control-Panel} title and to the left.
This changes the light vector within the {\bf XY} view plane.
%
\item[Z:]  The {\bf Z} lighting axis window is below the
\index{graphics!3D control-panel!move z}
{\bf Lighting Control-Panel} title and in the center.  This
changes the {\bf Z}
location of the light vector.
%
\item[Intensity:]
Below the {\bf Lighting Control-Panel} title
\index{graphics!3D control-panel!intensity}
and to the right is the light intensity meter.
Moving the intensity indicator down decreases the amount of
light emitted from the light source.

%Original Page 218

When the indicator is at the top of the meter the light source is
emitting at 100\% intensity.
At the bottom of the meter the light source is emitting at a level
slightly above ambient lighting.
\end{description}

\subsubsection{View Volume}

\index{graphics!3D control-panel!view volume}

The {\bf View Volume} button changes the control-panel into
the {\bf Viewing Volume Panel}.
At the bottom of the viewing panel is an {\bf Abort} button that
cancels any changes to the viewing volume that were made and a
{\it Return} button that carries out the current set of
viewing changes to the graph.
%
%>>>\begin{figure}[htbp]
%>>>\begin{picture}(183,252)(-125,0)
%>>>\special{psfile=ps/3dvolume.ps}
%>>>\end{picture}
%>>>\caption{Three-Dimensional Volume Panel.}
%>>>\end{figure}

\begin{description}

\item[Eye Reference:]  At the top of this panel is the
\index{graphics!3D control-panel!eye reference}
{\bf Eye Reference} window.
It shows a planar projection of the viewing pyramid from the eye
of the viewer relative to the location of the object.
This has a bounding region represented by the rectangle on the
left.
Below the object rectangle is the {\bf Hither} window.
By moving the slider in this window the hither clipping plane sets
\index{hither clipping plane}
the front of the view volume.
As a result of this depth clipping all points of the object closer
to the eye than this hither plane are not shown.
The {\bf Eye Distance} slider to the right of the {\bf Hither}
slider is used to change the degree of perspective in the image.
%
\item[Clip Volume:]  The {\bf Clip Volume} window is at the
\index{graphics!3D control-panel!clip volume}
bottom of the {\bf Viewing Volume Panel}.
On the right is a {\bf Settings} menu.
In this menu are buttons to select viewing attributes.
Selecting the {\bf Perspective} button computes the image using
perspective projection.
\index{graphics!3D control-panel!perspective}
The {\bf Show Region} button indicates whether the clipping region
of the
\index{graphics!3D control-panel!show clip region}
volume is to be drawn in the viewport and the {\bf Clipping On}
button shows whether the view volume clipping is to be in effect
when the image
\index{graphics!3D control-panel!clipping on}
is drawn.
The left side of the {\bf Clip Volume} window shows the clipping
\index{graphics!3D control-panel!clip volume}
boundary of the graph.
Moving the knobs along the {\bf X}, {\bf Y}, and {\bf Z} sliders
adjusts the volume of the clipping region accordingly.
\end{description}

\subsection{Operations for Three-Dimensional Graphics}
\label{ugGraphThreeDops}


Here is a summary of useful Axiom operations for three-di\-men\-sion\-al
graphics.
Each operation name is followed by a list of arguments.
Each argument is written as a variable informally named according
to the type of the argument (for example, {\it integer}).
If appropriate, a default value for an argument is given in
parentheses immediately following the name.

%
\bgroup\hbadness = 10001\sloppy
\begin{description}
%
\item[{\bf adaptive3D?}]\funArgs{}
tests whether space curves are to be plotted
\index{graphics!plot3d defaults!adaptive}
according to the
\index{adaptive plotting}
adaptive refinement algorithm.

%
\item[{\bf axes}]\funArgs{viewport, string\argDef{"on"}}
turns the axes on and off.
\index{graphics!3D commands!axes}

%Original Page 219

%
\item[{\bf close}]\funArgs{viewport}
closes the viewport.
\index{graphics!3D commands!close}

%
\item[{\bf colorDef}]\funArgs{viewport,
$\hbox{\it color}_{1}$\argDef{1}, $\hbox{\it color}_{2}$\argDef{27}}
sets the colormap
\index{graphics!3D commands!define color}
range to be from
$\hbox{\it color}_{1}$ to $\hbox{\it color}_{2}$.

%
\item[{\bf controlPanel}]\funArgs{viewport, string\argDef{"off"}}
declares whether the
\index{graphics!3D commands!control-panel}
control-panel for the viewport is to be displayed or not.

%
\item[{\bf diagonals}]\funArgs{viewport, string\argDef{"off"}}
declares whether the
\index{graphics!3D commands!diagonals}
polygon outline includes the diagonals or not.

%
\item[{\bf drawStyle}]\funArgs{viewport, style}
selects which of four drawing styles
\index{graphics!3D commands!drawing style}
are used: {\tt "wireMesh", "solid", "shade",} or {\tt "smooth".}

%
\item[{\bf eyeDistance}]\funArgs{viewport,float\argDef{500}}
sets the distance of the eye from the origin of the object
\index{graphics!3D commands!eye distance}
for use in the \spadfunFrom{perspective}{ThreeDimensionalViewport}.

%
\item[{\bf key}]\funArgs{viewport}
returns the operating
\index{graphics!3D commands!key}
system process ID number for the viewport.

%
\item[{\bf lighting}]\funArgs{viewport,
$float_{x}$\argDef{-0.5},
$float_{y}$\argDef{0.5}, $float_{z}$\argDef{0.5}}
sets the Cartesian
\index{graphics!3D commands!lighting}
coordinates of the light source.

%
\item[{\bf modifyPointData}]\funArgs{viewport,integer,point}
replaces the coordinates of the point with
\index{graphics!3D commands!modify point data}
the index {\it integer} with {\it point}.

%
\item[{\bf move}]\funArgs{viewport,
$integer_{x}$\argDef{viewPosDefault},
$integer_{y}$\argDef{viewPosDefault}}
moves the upper
\index{graphics!3D commands!move}
left-hand corner of the viewport to screen position
\allowbreak
({\small $integer_{x}$, $integer_{y}$}).

%
\item[{\bf options}]\funArgs{viewport}
returns a list of all current draw options.

%
\item[{\bf outlineRender}]\funArgs{viewport, string\argDef{"off"}}
turns polygon outlining
\index{graphics!3D commands!outline}
off or on when drawing in {\tt "shade"} mode.

%
\item[{\bf perspective}]\funArgs{viewport, string\argDef{"on"}}
turns perspective
\index{graphics!3D commands!perspective}
viewing on and off.

%
\item[{\bf reset}]\funArgs{viewport}
resets the attributes of a viewport to their
\index{graphics!3D commands!reset}
initial settings.

%
\item[{\bf resize}]\funArgs{viewport,
$integer_{width}$ \argDef{viewSizeDefault},
$integer_{height}$ \argDef{viewSizeDefault}}
resets the width and height
\index{graphics!3D commands!resize}
values for a viewport.

%
\item[{\bf rotate}]\funArgs{viewport,
$number_{\theta}$\argDef{viewThetaDefapult},
$number_{\phi}$\argDef{viewPhiDefault}}
rotates the viewport by rotation angles for longitude
({\it $\theta$}) and
latitude ({\it $\phi$}).
Angles designate radians if given as floats, or degrees if given
\index{graphics!3D commands!rotate}
as integers.

%Original Page 220

%
\item[{\bf setAdaptive3D}]\funArgs{boolean\argDef{true}}
sets whether space curves are to be plotted
\index{graphics!plot3d defaults!set adaptive}
according to the adaptive
\index{adaptive plotting}
refinement algorithm.

%
\item[{\bf setMaxPoints3D}]\funArgs{integer\argDef{1000}}
 sets the default maximum number of possible
\index{graphics!plot3d defaults!set max points}
points to be used when constructing a three-di\-men\-sion\-al space curve.

%
\item[{\bf setMinPoints3D}]\funArgs{integer\argDef{49}}
sets the default minimum number of possible
\index{graphics!plot3d defaults!set min points}
points to be used when constructing a three-di\-men\-sion\-al space curve.

%
\item[{\bf setScreenResolution3D}]\funArgs{integer\argDef{49}}
sets the default screen resolution constant
\index{graphics!plot3d defaults!set screen resolution}
used in setting the computation limit of adaptively
\index{adaptive plotting}
generated three-di\-men\-sion\-al space curve plots.

%
\item[{\bf showRegion}]\funArgs{viewport, string\argDef{"off"}}
declares whether the bounding
\index{graphics!3D commands!showRegion}
box of a graph is shown or not.
%
\item[{\bf subspace}]\funArgs{viewport}
returns the space component.
%
\item[{\bf subspace}]\funArgs{viewport, subspace}
resets the space component
\index{graphics!3D commands!subspace}
to {\it subspace}.

%
\item[{\bf title}]\funArgs{viewport, string}
gives the viewport the
\index{graphics!3D commands!title}
title {\it string}.

%
\item[{\bf translate}]\funArgs{viewport,
$float_{x}$\argDef{viewDeltaXDefault},
$float_{y}$\argDef{viewDeltaYDefault}}
translates
\index{graphics!3D commands!translate}
the object horizontally and vertically relative to the center of the viewport.

%
\item[{\bf intensity}]\funArgs{viewport,float\argDef{1.0}}
resets the intensity {\it I} of the light source,
\index{graphics!3D commands!intensity}
$0 \le I \le 1.$

%
\item[{\bf tubePointsDefault}]\funArgs{\optArg{integer\argDef{6}}}
sets or indicates the default number of
\index{graphics!3D defaults!tube points}
vertices defining the polygon that is used to create a tube around
a space curve.

%
\item[{\bf tubeRadiusDefault}]\funArgs{\optArg{float\argDef{0.5}}}
sets or indicates the default radius of
\index{graphics!3D defaults!tube radius}
the tube that encircles a space curve.

%
\item[{\bf var1StepsDefault}]\funArgs{\optArg{integer\argDef{27}}}
sets or indicates the default number of
\index{graphics!3D defaults!var1 steps}
increments into which the grid defining a surface plot is subdivided with
respect to the first parameter declared in the surface function.

%
\item[{\bf var2StepsDefault}]\funArgs{\optArg{integer\argDef{27}}}
sets or indicates the default number of
\index{graphics!3D defaults!var2 steps}
increments into which the grid defining a surface plot is subdivided with
respect to the second parameter declared in the surface function.


%%Original Page 221

\item[{\bf viewDefaults}]\funArgs{{\tt [}$integer_{point}$, 
$integer_{line}$, $integer_{axes}$,
$integer_{units}$, $float_{point}$,
\allowbreak$list_{position}$,
$list_{size}${\tt ]}}
resets the default settings for the
\index{graphics!3D defaults!reset viewport defaults}
point color, line color, axes color, units color, point size,
viewport upper left-hand corner position, and the viewport size.

%
\item[{\bf viewDeltaXDefault}]\funArgs{\optArg{float\argDef{0}}}
resets the default horizontal offset
\index{graphics!3D commands!deltaX default}
from the center of the viewport, or returns the current default offset if no argument is given.

%
\item[{\bf viewDeltaYDefault}]\funArgs{\optArg{float\argDef{0}}}
resets the default vertical offset
\index{graphics!3D commands!deltaY default}
from the center of the viewport, or returns the current default offset if no argument is given.

%
\item[{\bf viewPhiDefault}]\funArgs{\optArg{float\argDef{-$\pi$/4}}}
resets the default latitudinal view angle,
or returns the current default angle if no argument is given.
\index{graphics!3D commands!phi default}
$\phi$ is set to this value.

%
\item[{\bf viewpoint}]\funArgs{viewport, $float_{x}$,
$float_{y}$, $float_{z}$}
sets the viewing position in Cartesian coordinates.

%
\item[{\bf viewpoint}]\funArgs{viewport,
$float_{\theta}$,
$Float_{\phi}$}
sets the viewing position in spherical coordinates.

%
\item[{\bf viewpoint}]\funArgs{viewport,
$Float_{\theta}$,
$Float_{\phi}$,
$Float_{scaleFactor}$,
$Float_{xOffset}$, $Float_{yOffset}$}
sets the viewing position in spherical coordinates,
the scale factor, and offsets.
\index{graphics!3D commands!viewpoint}
$\theta$ (longitude) and
$\phi$ (latitude) are in radians.

%
\item[{\bf viewPosDefault}]\funArgs{\optArg{list\argDef{[0,0]}}}
sets or indicates the position of the upper
\index{graphics!3D defaults!viewport position}
left-hand corner of a two-di\-men\-sion\-al viewport, relative to the display root
window (the upper left-hand corner of the display is $[0, 0]$).

%
\item[{\bf viewSizeDefault}]\funArgs{\optArg{list\argDef{[400,400]}}}
sets or indicates the width and height dimensions
\index{graphics!3D defaults!viewport size}
of a viewport.

%
\item[{\bf viewThetaDefault}]\funArgs{\optArg{float\argDef{$\pi$/4}}}
resets the default longitudinal view angle,
or returns the current default angle if no argument is given.
\index{graphics!3D commands!theta default}
When a parameter is specified, the default longitudinal view angle
$\theta$ is set to this value.

%
\item[{\bf viewWriteAvailable}]\funArgs{\optArg{list\argDef{["pixmap",
"bitmap", "postscript", "image"]}}}
indicates the possible file types
\index{graphics!3D defaults!available viewport writes}
that can be created with the \spadfunFrom{write}{ThreeDimensionalViewport} function.

%
\item[{\bf viewWriteDefault}]\funArgs{\optArg{list\argDef{[]}}}
sets or indicates the default types of files
that are created in addition to the {\bf data} file when a
\spadfunFrom{write}{ThreeDimensionalViewport} command
\index{graphics!3D defaults!viewport writes}
is executed on a viewport.

%
\item[{\bf viewScaleDefault}]\funArgs{\optArg{float}}
sets the default scaling factor, or returns
\index{graphics!3D commands!scale default}
the current factor if no argument is given.


%%Original Page 222

\item[{\bf write}]\funArgs{viewport, directory, \optArg{option}}
writes the file {\bf data} for {\it viewport}
in the directory {\it directory}.
An optional third argument specifies a file type (one of {\tt
pixmap}, {\tt bitmap}, {\tt postscript}, or {\tt image}), or a
list of file types.
An additional file is written for each file type listed.

%
\item[{\bf scale}]\funArgs{viewport, float\argDef{2.5}}
specifies the scaling factor.
\index{graphics!3D commands!scale}
\index{scaling graphs}
\end{description}
\egroup

\subsection{Customization using .Xdefaults}
\label{ugXdefaults}

\index{graphics!.Xdefaults}

Both the two-di\-men\-sion\-al and three-di\-men\-sion\-al drawing facilities consult
the {\bf .Xdefaults} file for various defaults.
\index{file!.Xdefaults @{\bf .Xdefaults}}
The list of defaults that are recognized by the graphing routines
is discussed in this section.
These defaults are preceded by {\tt Axiom.3D.}
for three-di\-men\-sion\-al viewport defaults, {\tt Axiom.2D.}
for two-di\-men\-sion\-al viewport defaults, or {\tt Axiom*} (no dot) for
those defaults that are acceptable to either viewport type.

%
\begin{description}
%
\item[{\tt Axiom*buttonFont:\ \it font}] \ \newline
This indicates which
\index{graphics!.Xdefaults!button font}
font type is used for the button text on the control-panel.
{\bf Rom11}
%
\item[{\tt Axiom.2D.graphFont:\ \it font}] \quad (2D only) \newline
This indicates
\index{graphics!.Xdefaults!graph number font}
which font type is used for displaying the graph numbers and
slots in the {\bf Graphs} section of the two-di\-men\-sion\-al control-panel.
{\bf Rom22}
%
\item[{\tt Axiom.3D.headerFont:\ \it font}] \ \newline
This indicates which
\index{graphics!.Xdefaults!graph label font}
font type is used for the axes labels and potentiometer
header names on three-di\-men\-sion\-al viewport windows.
This is also used for two-di\-men\-sion\-al control-panels for indicating
which font type is used for potentionmeter header names and
multiple graph title headers.
%for example, {\tt Axiom.2D.headerFont: 8x13}.
{\bf Itl14}
%
\item[{\tt Axiom*inverse:\ \it switch}] \ \newline
This indicates whether the
\index{graphics!.Xdefaults!inverting background}
background color is to be inverted from white to black.
If {\tt on}, the graph viewports use black as the background
color.
If {\tt off} or no declaration is made, the graph viewports use a
white background.
{\bf off}
%
\item[{\tt Axiom.3D.lightingFont:\ \it font}] \quad (3D only) \newline
This indicates which font type is used for the {\bf x},
\index{graphics!.Xdefaults!lighting font}
{\bf y}, and {\bf z} labels of the two lighting axes potentiometers, and for
the {\bf Intensity} title on the lighting control-panel.
{\bf Rom10}
%
\item[{\tt Axiom.2D.messageFont, Axiom.3D.messageFont:\ \it font}] \ \newline
These indicate the font type
\index{graphics!.Xdefaults!message font}
to be used for the text in the control-panel message window.
{\bf Rom14}

%%Original Page 223

\item[{\tt Axiom*monochrome:\ \it switch}] \ \newline
This indicates whether the
\index{graphics!.Xdefaults!monochrome}
graph viewports are to be displayed as if the monitor is black and
white, that is, a 1 bit plane.
If {\tt on} is specified, the viewport display is black and white.
If {\tt off} is specified, or no declaration for this default is
given, the viewports are displayed in the normal fashion for the
monitor in use.
{\bf off}
%
\item[{\tt Axiom.2D.postScript:\ \it filename}] \ \newline
This specifies
\index{graphics!.Xdefaults!PostScript file name}
the name of the file that is generated when a 2D PostScript graph
\index{PostScript}
is saved.
{\bf axiom2d.ps}
%
\item[{\tt Axiom.3D.postScript:\ \it filename}] \ \newline
This specifies
\index{graphics!.Xdefaults!PostScript file name}
the name of the file that is generated when a 3D PostScript graph
\index{PostScript}
is saved.
{\bf axiom3D.ps}
%
\item[{\tt Axiom*titleFont \it font}] \ \newline
This
\index{graphics!.Xdefaults!title font}
indicates which font type is used
for the title text and, for three-di\-men\-sion\-al graphs,
in the lighting and viewing-volume control-panel windows.
\index{graphics!Xdefaults!2d}
{\bf Rom14}
%
\item[{\tt Axiom.2D.unitFont:\ \it font}] \quad (2D only) \newline
This indicates
\index{graphics!.Xdefaults!unit label font}
which font type is used for displaying the unit labels on
two-di\-men\-sion\-al viewport graphs.
{\bf 6x10}
%
\item[{\tt Axiom.3D.volumeFont:\ \it font}] \quad (3D only) \newline
This indicates which font type is used for the {\bf x},
\index{graphics!.Xdefaults!volume label font}
{\bf y}, and {\bf z} labels of the clipping region sliders; for the
{\bf Perspective}, {\bf Show Region}, and {\bf Clipping On} buttons under
{\bf Settings}, and above the windows for the {\bf Hither} and
{\bf Eye Distance} sliders in the {\bf Viewing Volume Panel} of the
three-di\-men\-sion\-al control-panel.
{\bf Rom8}
\end{description}

%\setcounter{chapter}{7} % Chapter 8
% viewSizeDefault [300,300]

%Original Page 227

\chapter{Advanced Problem Solving}
\label{ugProblem}

In this chapter we describe techniques useful in solving advanced problems
with Axiom.

\section{Numeric Functions}
\label{ugProblemNumeric}

%
Axiom provides two basic floating-point types: {\tt Float} and
{\tt DoubleFloat}.  This section describes how to use numerical
\index{function!numeric}
operations defined on these types and the related complex types.
\index{numeric operations}
%
As we mentioned in Chapter 
\sectionref{ugIntro}, the {\tt Float} type is a software
implementation of floating-point numbers in which the exponent and the
\index{floating-point number}
significand may have any number of digits.
\index{number!floating-point}
See \domainref{Float}
for detailed information about this domain.
The \domainref{DoubleFloat}
is usually a hardware implementation 
of floating point numbers, corresponding to machine double
precision.
The types {\tt Complex Float} and {\tt Complex DoubleFloat} are
\index{floating-point number!complex}
the corresponding software implementations of complex floating-point numbers.
\index{complex!floating-point number}
In this section the term {\it floating-point type}  means any of these
\index{number!complex floating-point}
four types.
%
The floating-point types implement the basic elementary functions.
These include (where {\tt \$} means
{\tt DoubleFloat},
{\tt Float},
{\tt Complex DoubleFloat}, or
{\tt Complex Float}):

%Original Page 228

\noindent
{\bf exp},  {\bf log}: $\$ -> \$$ \newline
{\bf sin},  {\bf cos}, {\bf tan}, {\bf cot}, {\bf sec}, {\bf csc}: $\$ -> \$$ \newline
{\bf asin}, {\bf acos}, {\bf atan}, {\bf acot}, {\bf asec}, {\bf acsc}: $\$ -> \$$  \newline
{\bf sinh},  {\bf cosh}, {\bf tanh}, {\bf coth}, {\bf sech}, {\bf csch}: $\$ -> \$$  \newline
{\bf asinh}, {\bf acosh}, {\bf atanh}, {\bf acoth}, {\bf asech}, {\bf acsch}: $\$ -> \$$  \newline
{\bf pi}: $() -> \$$  \newline
{\bf sqrt}: $\$ -> \$$ \newline
{\bf nthRoot}: $(\$, Integer) -> \$$  \newline
\spadfunFrom{**}{Float}: $(\$, Fraction Integer) -> \$$ \newline
\spadfunFrom{**}{Float}: $(\$,\$) -> \$$  \newline

The handling of roots depends on whether the floating-point type
\index{root!numeric approximation}
is real or complex: for the real floating-point types,
{\tt DoubleFloat} and {\tt Float}, if a real root exists
the one with the same sign as the radicand is returned; for the
complex floating-point types, the principal value is returned.
\index{principal value}
Also, for real floating-point types the inverse functions
produce errors if the results are not real.
This includes cases such as $asin(1.2)$, $log(-3.2)$,
$sqrt(-1.1)$.
%

The default floating-point type is {\tt Float} so to evaluate
functions using {\tt Float} or {\tt Complex Float}, just use
normal decimal notation.

\spadcommand{exp(3.1)}
$$
22.1979512814 41633405 
$$
\returnType{Type: Float}

\spadcommand{exp(3.1 + 4.5 * \%i)}
$$
-{4.6792348860 969899118} -{{21.6991659280 71731864} \  i} 
$$
\returnType{Type: Complex Float}

To evaluate functions using {\tt DoubleFloat}
or {\tt Complex DoubleFloat},
a declaration or conversion is required.

\spadcommand{r: DFLOAT := 3.1; t: DFLOAT := 4.5; exp(r + t*\%i)}
$$
-{4.6792348860969906} -{{21.699165928071732} \  i} 
$$
\returnType{Type: Complex DoubleFloat}

\spadcommand{exp(3.1::DFLOAT + 4.5::DFLOAT * \%i)}
$$
-{4.6792348860969906} -{{21.699165928071732} \  i} 
$$
\returnType{Type: Complex DoubleFloat}

A number of special functions are provided by the package
{\tt DoubleFloatSpecialFunctions} for the machine-precision
\index{special functions}
floating-point types.
\index{DoubleFloatSpecialFunctions}
The special functions provided are listed below, where $F$ stands for
the types {\tt DoubleFloat} and {\tt Complex DoubleFloat}.
The real versions of the functions yield an error if the result is not real.
\index{function!special}

\noindent
{\bf Gamma}: $F -> F$\hfill\newline
$Gamma(z)$ is the Euler gamma function,
\index{function!Gamma}
   $\Gamma(z)$,
   defined by
\index{Euler!gamma function}
   $$\Gamma(z) = \int_{0}^{\infty} t^{z-1} e^{-t} dt.$$
   

%Original Page 229

\noindent
{\bf Beta}: $F -> F$\hfill\newline
   $Beta(u, v)$ is the Euler Beta function,
\index{function!Euler Beta}
   $Beta(u,v)$, defined by
\index{Euler!Beta function}
   $$Beta(u,v) = \int_{0}^{1} t^{u-1} (1-t)^{v-1} dt.$$
   
   This is related to $\Gamma(z)$ by
   $$Beta(u,v) = \frac{\Gamma(u) \Gamma(v)}{\Gamma(u + v)}.$$

\noindent
{\bf logGamma}: $F -> F$\hfill\newline
   $logGamma(z)$ is the natural logarithm of
$\Gamma(z)$.
   This can often be computed even if $\Gamma(z)$
cannot.
%

\noindent
{\bf digamma}: $F -> F$\hfill\newline
   $digamma(z)$, also called $psi(z)$,
\index{psi @ $\psi$}
is the function $\psi(z)$,
\index{function!digamma}
   defined by $$\psi(z) = \Gamma'(z)/\Gamma(z).$$

\noindent
{\bf polygamma}: $(NonNegativeInteger, F) -> F$\hfill\newline
   $polygamma(n, z)$ is the $n$-th derivative of
\index{function!polygamma}
   $\psi(z)$, written $\psi^{(n)}(z)$.

\noindent
{\bf E1}: $(DoubleFloat) -> OnePointCompletion DoubleFloat$\hfill\newline
   E1(x) is the Exponential Integral function
   The current implementation is a piecewise approximation
   involving one poly from $-4..4$ and a second poly for $x > 4$
\index{function!E1}

\noindent
{\bf En}: $(PI, DFLOAT) -> OnePointCompletion DoubleFloat$\hfill\newline
   En(PI,R) is the nth Exponential Integral
\index{function!En}

\noindent
{\bf Ei}: $(OnePointCompletion DFLOAT) -> OnePointCompletion DFLOAT$
\hfill\newline
   Ei is the Exponential Integral function.
   This is computed using a 6 part piecewise approximation.
   DoubleFloat can only preserve about 16 digits but the
   Chebyshev approximation used can give 30 digits.
\index{function!Ei}

\noindent
{\bf Ei1}: $(DoubleFloat) -> DoubleFloat$\hfill\newline
   Ei1 is the first approximation of Ei where the result is
   $x*e^{-x}*Ei(x)$ from -infinity to -10 (preserves digits)
\index{function!Ei1}

\noindent
{\bf Ei2}: $(DoubleFloat) -> DoubleFloat$\hfill\newline
   Ei2 is the first approximation of Ei where the result is
   $x*e^{-x}*Ei(x)$ from -10 to -4 (preserves digits)
\index{function!Ei2}

\noindent
{\bf Ei3}: $(DoubleFloat) -> DoubleFloat$\hfill\newline
   Ei3 is the first approximation of Ei where the result is
   $(Ei(x)-log |x| - gamma)/x$ from -4 to 4 (preserves digits)
\index{function!Ei3}

\noindent
{\bf Ei4}: $(DoubleFloat) -> DoubleFloat$\hfill\newline
   Ei4 is the first approximation of Ei where the result is
   $x*e^{-x}*Ei(x)$ from 4 to 12 (preserves digits)
\index{function!Ei4}

\noindent
{\bf Ei5}: $(DoubleFloat) -> DoubleFloat$\hfill\newline
   Ei5 is the first approximation of Ei where the result is
   $x*e^{-x}*Ei(x)$ from 12 to 32 (preserves digits)
\index{function!Ei5}

\noindent
{\bf Ei6}: $(DoubleFloat) -> DoubleFloat$\hfill\newline
   Ei6 is the first approximation of Ei where the result is
   $x*e^{-x}*Ei(x)$ from 32 to infinity (preserves digits)
\index{function!Ei6}

\noindent
{\bf besselJ}: $(F,F) -> F$\hfill\newline
   $besselJ(v,z)$ is the Bessel function of the first kind,
\index{function!Bessel}
   $J_\nu (z)$.
   This function satisfies the differential equation
   $$z^2 w''(z) + z w'(z) + (z^2-\nu^2)w(z) = 0.$$

\noindent
{\bf besselY}: $(F,F) -> F$\hfill\newline
   $besselY(v,z)$ is the Bessel function of the second kind,
\index{function!Bessel}
   $Y_\nu (z)$.
   This function satisfies the same differential equation as
   {\bf besselJ}.
   The implementation simply uses the relation
  $$Y_\nu (z) = \frac{J_\nu (z) \cos(\nu \pi) - J_{-\nu} (z)}{\sin(\nu \pi)}.$$

\noindent
{\bf besselI}: $(F,F) -> F$\hfill\newline
   $besselI(v,z)$ is the modified Bessel function of the first kind,
\index{function!Bessel}
   $I_\nu (z)$.
   This function satisfies the differential equation
   $$z^2 w''(z) + z w'(z) - (z^2+\nu^2)w(z) = 0.$$

\noindent
{\bf besselK}: $(F,F) -> F$\hfill\newline
   $besselK(v,z)$ is the modified Bessel function of the second kind,
\index{function!Bessel}
   $K_\nu (z)$.
   This function satisfies the same differential equation as {\bf besselI}.
\index{Bessel function}
   The implementation simply uses the relation
   $$K_\nu (z) = \pi \frac{I_{-\nu} (z) - I_{\nu} (z)}{2 \sin(\nu \pi)}.$$
   

%Original Page 230

\noindent
{\bf airyAi}: $F -> F$\hfill\newline
   $airyAi(z)$ is the Airy function $Ai(z)$.
\index{function!Airy Ai}
   This function satisfies the differential equation
   $w''(z) - z w(z) = 0.$
   The implementation simply uses the relation
   $$Ai(-z) = \frac{1}{3}\sqrt{z} ( J_{-1/3} (\frac{2}{3}z^{3/2}) + J_{1/3} (\frac{2}{3}z^{3/2}) ).$$

\noindent
{\bf airyBi}: $F -> F$\hfill\newline
   $airyBi(z)$ is the Airy function $Bi(z)$.
\index{function!Airy Bi}
   This function satisfies the same differential equation as {\bf airyAi}.
\index{Airy function}
   The implementation simply uses the relation
   $$Bi(-z) = \frac{1}{3}\sqrt{3 z} ( J_{-1/3} (\frac{2}{3}z^{3/2}) - J_{1/3} (\frac{2}{3}z^{3/2}) ).$$
   
\noindent
{\bf hypergeometric0F1}: $(F,F) -> F$\hfill\newline
   $hypergeometric0F1(c,z)$ is the hypergeometric function
\index{function!hypergeometric}
   ${}_0 F_1 ( ; c; z)$.

The above special functions are defined only for small floating-point types.
If you give {\tt Float} arguments, they are converted to
{\tt DoubleFloat} by Axiom.

\spadcommand{Gamma(0.5)**2}
$$
3.14159265358979 
$$
\returnType{Type: DoubleFloat}

\spadcommand{a := 2.1; b := 1.1; besselI(a + \%i*b, b*a + 1)}
$$
{2.489481690673867} -{{2.365846713181643} \  i} 
$$
\returnType{Type: Complex DoubleFloat}

A number of additional operations may be used to compute numerical values.
These are special polynomial functions that can be evaluated for values in
any commutative ring $R$, and in particular for values in any
floating-point type.
The following operations are provided by the package
{\tt OrthogonalPolynomialFunctions}:
\index{OrthogonalPolynomialFunctions}

\noindent
{\bf chebyshevT}: $(NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $chebyshevT(n,z)$ is the $n$-th Chebyshev polynomial of the first
   kind, $T_n (z)$.  These are defined by
   $$\frac{1-t z}{1-2 t z+t^2} = \sum_{n=0}^{\infty} T_n (z) t^n.$$

\noindent
{\bf chebyshevU}: $(NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $chebyshevU(n,z)$ is the $n$-th Chebyshev polynomial of the second
   kind, $U_n (z)$. These are defined by
   $$\frac{1}{1-2 t z+t^2} = \sum_{n=0}^{\infty} U_n (z) t^n.$$

%Original Page 231

\noindent
{\bf hermiteH}:   $(NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $hermiteH(n,z)$ is the $n$-th Hermite polynomial,
   $H_n (z)$.
   These are defined by
   $$e^{2 t z - t^2} = \sum_{n=0}^{\infty} H_n (z) \frac{t^n}{n!}.$$

\noindent
{\bf laguerreL}:  $(NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $laguerreL(n,z)$ is the $n$-th Laguerre polynomial,
   $L_n (z)$.
   These are defined by
   $$\frac{e^{-\frac{t z}{1-t}}}{1-t} = \sum_{n=0}^{\infty} L_n (z) \frac{t^n}{n!}.$$

\noindent
{\bf laguerreL}:  $(NonNegativeInteger, NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $laguerreL(m,n,z)$ is the associated Laguerre polynomial,
   $L^m_n (z)$.
   This is the $m$-th derivative of $L_n (z)$.

\noindent
{\bf legendreP}:  $(NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $legendreP(n,z)$ is the $n$-th Legendre polynomial,
   $P_n (z)$.  These are defined by
   $$\frac{1}{\sqrt{1-2 t z+t^2}} = \sum_{n=0}^{\infty} P_n (z) t^n.$$

These operations require non-negative integers for the indices, but otherwise
the argument can be given as desired.

\spadcommand{[chebyshevT(i, z) for i in 0..5]}
$$
\left[
1,  z,  {{2 \  {z \sp 2}} -1},  {{4 \  {z \sp 3}} -{3 \  z}},  {{8 \  
{z \sp 4}} -{8 \  {z \sp 2}}+1},  {{{16} \  {z \sp 5}} -{{20} \  {z \sp 
3}}+{5 \  z}} 
\right]
$$
\returnType{Type: List Polynomial Integer}

The expression $chebyshevT(n,z)$ evaluates to the $n$-th Chebyshev
\index{polynomial!Chebyshev!of the first kind}
polynomial of the first kind.

\spadcommand{chebyshevT(3, 5.0 + 6.0*\%i)}
$$
-{1675.0}+{{918.0} \  i} 
$$
\returnType{Type: Complex Float}

\spadcommand{chebyshevT(3, 5.0::DoubleFloat)}
$$
485.0 
$$
\returnType{Type: DoubleFloat}

The expression $chebyshevU(n,z)$ evaluates to the $n$-th Chebyshev
\index{polynomial!Chebyshev!of the second kind}
polynomial of the second kind.

\spadcommand{[chebyshevU(i, z) for i in 0..5]}
$$
\left[
1,  {2 \  z},  {{4 \  {z \sp 2}} -1},  {{8 \  {z \sp 3}} -{4 \  z}},  
{{{16} \  {z \sp 4}} -{{12} \  {z \sp 2}}+1},  {{{32} \  {z \sp 5}} -{{32} 
\  {z \sp 3}}+{6 \  z}} 
\right]
$$
\returnType{Type: List Polynomial Integer}

%Original Page 232

\spadcommand{chebyshevU(3, 0.2)}
$$
-{0.736} 
$$
\returnType{Type: Float}

The expression $hermiteH(n,z)$ evaluates to the $n$-th Hermite
\index{polynomial!Hermite}
polynomial.

\spadcommand{[hermiteH(i, z) for i in 0..5]}
$$
\left[
1,  {2 \  z},  {{4 \  {z \sp 2}} -2},  {{8 \  {z \sp 3}} -{{12} \  z}}, 
 {{{16} \  {z \sp 4}} -{{48} \  {z \sp 2}}+{12}},  {{{32} \  {z \sp 5}} 
-{{160} \  {z \sp 3}}+{{120} \  z}} 
\right]
$$
\returnType{Type: List Polynomial Integer}

\spadcommand{hermiteH(100, 1.0)}
$$
-{0.1448706729 337934088 E 93} 
$$
\returnType{Type: Float}

The expression $laguerreL(n,z)$ evaluates to the $n$-th Laguerre
\index{polynomial!Laguerre}
polynomial.

\spadcommand{[laguerreL(i, z) for i in 0..4]}
$$
\left[
1,  {-z+1},  {{z \sp 2} -{4 \  z}+2},  {-{z \sp 3}+{9 \  {z \sp 2}} 
-{{18} \  z}+6},  {{z \sp 4} -{{16} \  {z \sp 3}}+{{72} \  {z \sp 2}} 
-{{96} \  z}+{24}} 
\right]
$$
\returnType{Type: List Polynomial Integer}

\spadcommand{laguerreL(4, 1.2)}
$$
-{13.0944} 
$$
\returnType{Type: Float}

\spadcommand{[laguerreL(j, 3, z) for j in 0..4]}
$$
\left[
{-{z \sp 3}+{9 \  {z \sp 2}} -{{18} \  z}+6},  {-{3 \  {z \sp 2}}+{{18} \  
z} -{18}},  {-{6 \  z}+{18}},  -6,  0 
\right]
$$
\returnType{Type: List Polynomial Integer}

\spadcommand{laguerreL(1, 3, 2.1)}
$$
6.57 
$$
\returnType{Type: Float}

The expression
\index{polynomial!Legendre}
$legendreP(n,z)$ evaluates to the $n$-th Legendre polynomial,

\spadcommand{[legendreP(i,z) for i in 0..5]}
$$
\left[
1,  z,  {{{\frac{3}{2}} \  {z \sp 2}} -{\frac{1}{2}}},  
{{{\frac{5}{2}} \  {z \sp 3}} -{{\frac{3}{2}} \  z}},  
{{{\frac{35}{8}} \  {z \sp 4}} -{{\frac{15}{4}} \  {z \sp 2}}+{\frac{3}{8}}},
{{{\frac{63}{8}} \  {z \sp 5}} -{{\frac{35}{4}} \  {z \sp 3}}
+{{\frac{15}{8}} \  z}} 
\right]
$$
\returnType{Type: List Polynomial Fraction Integer}

%Original Page 233

\spadcommand{legendreP(3, 3.0*\%i)}
$$
-{{72.0} \  i} 
$$
\returnType{Type: Complex Float}

Finally, three number-theoretic polynomial operations may be evaluated.
\index{number theory}
The following operations are provided by the package
{\tt NumberTheoreticPolynomialFunctions}.
\index{NumberTheoreticPolynomialFunctions}

\noindent
{\bf bernoulliB}: $(NonNegativeInteger, R) -> R$ \hbox{}\hfill\newline
   $bernoulliB(n,z)$ is the $n$-th Bernoulli polynomial,
\index{polynomial!Bernoulli}
   $B_n (z)$.  These are defined by
   $$\frac{t e^{z t}}{e^t - 1} = \sum_{n=0}^{\infty} B_n (z) \frac{t^n}{n!}.$$

\noindent
{\bf eulerE}: $(NonNegativeInteger, R) -> R$ \hbox{}\hfill\newline
   $eulerE(n,z)$ is the $n$-th Euler polynomial,
\index{Euler!polynomial}
   $E_n (z)$.  These are defined by
\index{polynomial!Euler}
   $$\frac{2 e^{z t}}{e^t + 1} = \sum_{n=0}^{\infty} E_n (z) \frac{t^n}{n!}.$$

\noindent
{\bf cyclotomic}: $(NonNegativeInteger, R) -> R$\hbox{}\hfill\newline
   $cyclotomic(n,z)$ is the $n$-th cyclotomic polynomial
   $\Phi_n (z)$.  This is the polynomial whose
   roots are precisely the primitive $n$-th roots of unity.
\index{Euler!totient function}
   This polynomial has degree given by the Euler totient function
\index{function!totient}
   $\phi(n)$.

The expression $bernoulliB(n,z)$ evaluates to the $n$-th Bernoulli
\index{polynomial!Bernouilli}
polynomial.

\spadcommand{bernoulliB(3, z)}
$$
{z \sp 3} -{{\frac{3}{2}} \  {z \sp 2}}+{{\frac{1}{2}} \  z} 
$$
\returnType{Type: Polynomial Fraction Integer}

\spadcommand{bernoulliB(3, 0.7 + 0.4 * \%i)}
$$
-{0.138} -{{0.116} \  i} 
$$
\returnType{Type: Complex Float}

The expression
\index{polynomial!Euler}
$eulerE(n,z)$ evaluates to the $n$-th Euler polynomial.

\spadcommand{eulerE(3, z)}
$$
{z \sp 3} -{{\frac{3}{2}} \  {z \sp 2}}+{\frac{1}{4}} 
$$
\returnType{Type: Polynomial Fraction Integer}

\spadcommand{eulerE(3, 0.7 + 0.4 * \%i)}
$$
-{0.238} -{{0.316} \  i} 
$$
\returnType{Type: Complex Float}

%Original Page 234

The expression
\index{polynomial!cyclotomic}
$cyclotomic(n,z)$ evaluates to the $n$-th cyclotomic polynomial.
\index{cyclotomic polynomial}

\spadcommand{cyclotomic(3, z)}
$$
{z \sp 2}+z+1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{cyclotomic(3, (-1.0 + 0.0 * \%i)**(2/3))}
$$
0.0 
$$
\returnType{Type: Complex Float}

Drawing complex functions in Axiom is presently somewhat
awkward compared to drawing real functions.
It is necessary to use the {\bf draw} operations that operate
on functions rather than expressions.

This is the complex exponential function (rotated interactively).
\index{function!complex exponential}
When this is displayed in color, the height is the value of the real part of
the function and the color is the imaginary part.
Red indicates large negative imaginary values, green indicates imaginary
values near zero and blue/violet indicates large positive imaginary values.

\spadgraph{draw((x,y)+-> real exp complex(x,y), -2..2, -2*\%pi..2*\%pi, colorFunction == (x, y) +->  imag exp complex(x,y), title=="exp(x+\%i*y)", style=="smooth")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/compexp.eps}}
\begin{center}
$(x,y)+-> real exp complex(x,y), -2..2, -2\pi..2\pi, $\\
$colorFunction == (x, y) +-> imag exp complex(x,y),  $\\
$title=="exp(x+\%i*y)", style=="smooth"$
\end{center}
\end{minipage}

This is the complex arctangent function.
\index{function!complex arctangent}
Again, the height is the real part of the function value but here
the color indicates the function value's phase.
The position of the branch cuts are clearly visible and one can
see that the function is real only for a real argument.

\spadgraph{vp := draw((x,y) +-> real atan complex(x,y), -\%pi..\%pi, -\%pi..\%pi, colorFunction==(x,y) +->argument atan complex(x,y), title=="atan(x+\%i*y)", style=="shade"); rotate(vp,-160,-45); vp}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/compatan.eps}}
\begin{center}
$(x,y) +-> real atan complex(x,y), -\pi..\pi, -\pi..\pi,$\\
$colorFunction==(x,y) +->argument atan complex(x,y), $\\
$title=="atan(x+\%i*y)", style=="shade"$
\end{center}
\end{minipage}

%Original Page 235

This is the complex Gamma function.

\spadgraph{draw((x,y) +-> max(min(real Gamma complex(x,y),4),-4), -\%pi..\%pi, -\%pi..\%pi, style=="shade", colorFunction == (x,y) +-> argument Gamma complex(x,y), title == "Gamma(x+\%i*y)", var1Steps == 50, var2Steps== 50)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/compgamma.eps}}
\begin{center}
$(x,y) +-> max(min(real Gamma complex(x,y),4),-4), -\pi..\pi, -\pi..\pi, $\\
$style=="shade", colorFunction == (x,y) +-> argument Gamma complex(x,y), $\\
$title == "Gamma(x+\%i*y)", var1Steps == 50, var2Steps== 50$
\end{center}
\end{minipage}

This shows the real Beta function near the origin.

\spadgraph{draw(Beta(x,y)/100, x=-1.6..1.7, y = -1.6..1.7, style=="shade", title=="Beta(x,y)", var1Steps==40, var2Steps==40)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/realbeta.eps}}
\begin{center}
$Beta(x,y)/100, x=-1.6..1.7, y = -1.6..1.7, $\\
$style=="shade", title=="Beta(x,y)", var1Steps==40, var2Steps==40$
\end{center}
\end{minipage}

This is the Bessel function $J_\alpha (x)$
for index $\alpha$ in the range $-6..4$ and
argument $x$ in the range $2..14$.

\spadgraph{draw((alpha,x) +-> min(max(besselJ(alpha, x+8), -6), 6), -6..4, -6..6, title=="besselJ(alpha,x)", style=="shade", var1Steps==40, var2Steps==40)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/bessel.eps}}
\begin{center}
$(alpha,x) +-> min(max(besselJ(alpha, x+8), -6), 6), -6..4, -6..6, $\\
$title=="besselJ(alpha,x)", style=="shade", var1Steps==40, var2Steps==40$
\end{center}
\end{minipage}

%Original Page 236

This is the modified Bessel function
$I_\alpha (x)$
evaluated for various real values of the index $\alpha$
and fixed argument $x = 5$.

\spadgraph{draw(besselI(alpha, 5), alpha = -12..12, unit==[5,20])}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/modbess.eps}}
\begin{center}
$besselI(alpha, 5), alpha = -12..12, unit==[5,20]$
\end{center}
\end{minipage}

This is similar to the last example
except the index $\alpha$
takes on complex values in a $6 \times 6$ rectangle  centered on the origin.

\spadgraph{draw((x,y) +-> real besselI(complex(x/20, y/20),5), -60..60, -60..60, colorFunction == (x,y)+-> argument besselI(complex(x/20,y/20),5), title=="besselI(x+i*y,5)", style=="shade")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/modbessc.eps}}
\begin{center}
$(x,y) +-> real besselI(complex(x/20, y/20),5), -60..60, -60..60, $\\
$colorFunction == (x,y)+-> argument besselI(complex(x/20,y/20),5), $\\
$title=="besselI(x+i*y,5)", style=="shade"$
\end{center}
\end{minipage}

\section{Polynomial Factorization}
\label{ugProblemFactor}

%
The Axiom polynomial factorization
\index{polynomial!factorization}
facilities are available for all polynomial types and a wide variety of
coefficient domains.
\index{factorization}
Here are some examples.

\subsection{Integer and Rational Number Coefficients}
\label{ugProblemFactorIntRat}

Polynomials with integer
\index{polynomial!factorization!integer coefficients}
coefficients can be be factored.

\spadcommand{v := (4*x**3+2*y**2+1)*(12*x**5-x**3*y+12) }
$$
-{2 \  {x \sp 3} \  {y \sp 3}}+{{\left( {{24} \  {x \sp 5}}+{24} 
\right)}
\  {y \sp 2}}+{{\left( -{4 \  {x \sp 6}} -{x \sp 3} 
\right)}
\  y}+{{48} \  {x \sp 8}}+{{12} \  {x \sp 5}}+{{48} \  {x \sp 3}}+{12} 
$$
\returnType{Type: Polynomial Integer}

%Original Page 237

\spadcommand{factor v }
$$
-{{\left( {{x \sp 3} \  y} -{{12} \  {x \sp 5}} -{12} 
\right)}
\  {\left( {2 \  {y \sp 2}}+{4 \  {x \sp 3}}+1 
\right)}}
$$
\returnType{Type: Factored Polynomial Integer}

Also, Axiom can factor polynomials with
\index{polynomial!factorization!rational number coefficients}
rational number coefficients.

\spadcommand{w := (4*x**3+(2/3)*x**2+1)*(12*x**5-(1/2)*x**3+12) }
$$
{{48} \  {x \sp 8}}
+{8 \  {x \sp 7}} 
-{2 \  {x \sp 6}}
+{{\frac{35}{3}} \  {x \sp 5}}
+{{\frac{95}{2}} \  {x \sp 3}}
+{8 \  {x \sp 2}}+{12} 
$$
\returnType{Type: Polynomial Fraction Integer}

\spadcommand{factor w }
$$
{48} \  {\left( {x \sp 3}
+{{\frac{1}{6}} \  {x \sp 2}}
+{\frac{1}{4}} \right)}\  {\left( {x \sp 5} 
-{{\frac{1}{24}} \  {x \sp 3}}+1 \right)}
$$
\returnType{Type: Factored Polynomial Fraction Integer}

\subsection{Finite Field Coefficients}
\label{ugProblemFactorFF}

Polynomials with coefficients in a finite field
\index{polynomial!factorization!finite field coefficients}
can be also be factored.
\index{finite field!factoring polynomial with coefficients in}

\spadcommand{u : POLY(PF(19)) :=3*x**4+2*x**2+15*x+18 }
$$
{3 \  {x \sp 4}}+{2 \  {x \sp 2}}+{{15} \  x}+{18} 
$$
\returnType{Type: Polynomial PrimeField 19}

These include the integers mod $p$, where $p$ is prime, and
extensions of these fields.

\spadcommand{factor u }
$$
3 \  {\left( x+{18} 
\right)}
\  {\left( {x \sp 3}+{x \sp 2}+{8 \  x}+{13} 
\right)}
$$
\returnType{Type: Factored Polynomial PrimeField 19}

Convert this to have coefficients in the finite
field with $19^3$ elements.
See \sectionref{ugProblemFinite} for more information about finite fields.

\spadcommand{factor(u :: POLY FFX(PF 19,3)) }
$$
3 \  {\left( x+{18} 
\right)}
\  {\left( x+{5 \  { \%I \sp 2}}+{3 \  \%I}+{13} 
\right)}
\  {\left( x+{{16} \  { \%I \sp 2}}+{{14} \  \%I}+{13} 
\right)}
\  {\left( x+{{17} \  { \%I \sp 2}}+{2 \  \%I}+{13} 
\right)}
$$
\returnType{Type: Factored Polynomial FiniteFieldExtension(PrimeField 19,3)}

\subsection{Simple Algebraic Extension Field Coefficients}
\label{ugProblemFactorAlg}

Polynomials with coefficients in simple algebraic extensions
\index{polynomial!factorization!algebraic extension field coefficients}
of the rational numbers can be factored.
\index{algebraic number}
\index{number!algebraic}

Here, $aa$ and $bb$ are symbolic roots of polynomials.

\spadcommand{aa := rootOf(aa**2+aa+1) }
$$
aa 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{p:=(x**3+aa**2*x+y)*(aa*x**2+aa*x+aa*y**2)**2 }
$$
\begin{array}{@{}l}
{{\left( -aa -1 \right)} \  {y \sp 5}}+
{{\left( {{\left( -aa -1 \right)}\  {x \sp 3}}+
{aa \  x} \right)}\  {y \sp 4}}+
\\
\\
\displaystyle
{{\left( {{\left( -{2 \  aa} -2 \right)}\  {x \sp 2}}+
{{\left( -{2 \  aa} -2 \right)}\  x} \right)}\  {y \sp 3}}+
\\
\\
\displaystyle
{{\left( {{\left( -{2 \  aa} -2 \right)}\  {x \sp 5}}+
{{\left( -{2 \  aa} -2 \right)}\  {x \sp 4}}+
{2 \  aa \  {x \sp 3}}+{2 \  aa \  {x \sp 2}} \right)}\  {y \sp 2}}+
\\
\\
\displaystyle
{{\left( {{\left( -aa -1 \right)}\  {x \sp 4}}+
{{\left( -{2 \  aa} -2 \right)}\  {x \sp 3}}+
{{\left( -aa -1 \right)}\  {x \sp 2}} \right)}\  y}+
\\
\\
\displaystyle
{{\left( -aa -1 \right)}\  {x \sp 7}}+
{{\left( -{2 \  aa} -2 \right)}\  {x \sp 6}} -
{x \sp 5}+
{2 \  aa \  {x \sp 4}}+
{aa \  {x \sp 3}} 
\end{array}
$$
\returnType{Type: Polynomial AlgebraicNumber}

Note that the second argument to factor can be a list of
algebraic extensions to factor over.

\spadcommand{factor(p,[aa]) }
%Note: this answer differs from the book but is equivalent.
$$
{\left( -aa -1 
\right)}
\  {\left( y+{x \sp 3}+{{\left( -aa -1 
\right)}
\  x} 
\right)}
\  {{\left( {y \sp 2}+{x \sp 2}+x 
\right)}
\sp 2} 
$$
\returnType{Type: Factored Polynomial AlgebraicNumber}

%Original Page 238

This factors $x**2+3$ over the integers.

\spadcommand{factor(x**2+3)}
$$
{x \sp 2}+3 
$$
\returnType{Type: Factored Polynomial Integer}

Factor the same polynomial over the field obtained by adjoining
$aa$ to the rational numbers.

\spadcommand{factor(x**2+3,[aa]) }
$$
{\left( x -{2 \  aa} -1 
\right)}
\  {\left( x+{2 \  aa}+1 
\right)}
$$
\returnType{Type: Factored Polynomial AlgebraicNumber}

Factor $x**6+108$ over the same field.

\spadcommand{factor(x**6+108,[aa]) }
$$
{\left( {x \sp 3} -{{12} \  aa} -6 
\right)}
\  {\left( {x \sp 3}+{{12} \  aa}+6 
\right)}
$$
\returnType{Type: Factored Polynomial AlgebraicNumber}

\spadcommand{bb:=rootOf(bb**3-2) }
$$
bb 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{factor(x**6+108,[bb]) }
$$
{\left( {x \sp 2} -{3 \  bb \  x}+{3 \  {bb \sp 2}} 
\right)}
\  {\left( {x \sp 2}+{3 \  {bb \sp 2}} 
\right)}
\  {\left( {x \sp 2}+{3 \  bb \  x}+{3 \  {bb \sp 2}} 
\right)}
$$
\returnType{Type: Factored Polynomial AlgebraicNumber}

Factor again over the field obtained by adjoining both $aa$
and $bb$ to the rational numbers.

\spadcommand{factor(x**6+108,[aa,bb]) }
$$
\begin{array}{@{}l}
{\left( x+{{\left( -{2 \  aa} -1 \right)}\  bb} \right)}
\  {\left( x+{{\left( -aa -2 \right)}\  bb} \right)}
\  {\left( x+{{\left( -aa+1 \right)}\  bb} \right)}
\\
\\
\displaystyle
\  {\left( x+{{\left( aa -1 \right)}\  bb} \right)}
\  {\left( x+{{\left( aa+2 \right)}\  bb} \right)}
\  {\left( x+{{\left( {2 \  aa}+1 \right)}\  bb} \right)}
\end{array}
$$
\returnType{Type: Factored Polynomial AlgebraicNumber}

\subsection{Factoring Rational Functions}
\label{ugProblemFactorRatFun}

Since fractions of polynomials form a field, every element (other than zero)
\index{rational function!factoring}
divides any other, so there is no useful notion of irreducible factors.
Thus the {\bf factor} operation is not very useful for fractions
of polynomials.

There is, instead, a specific operation {\bf factorFraction}
that separately factors the numerator and denominator and returns
a fraction of the factored results.

\spadcommand{factorFraction((x**2-4)/(y**2-4))}
$$
\frac{{\left( x -2 \right)}\  {\left( x+2 \right)}}
{{\left( y -2 \right)}\  {\left( y+2 \right)}}
$$
\returnType{Type: Fraction Factored Polynomial Integer}

You can also use {\bf map}. This expression
applies the {\bf factor} operation
to the numerator and denominator.

\spadcommand{map(factor,(x**2-4)/(y**2-4))}
$$
\frac{{\left( x -2 \right)}\  {\left( x+2 \right)}}
{{\left( y -2 \right)}\  {\left( y+2 \right)}}
$$
\returnType{Type: Fraction Factored Polynomial Integer}

%Original Page 239

\section{Manipulating Symbolic Roots of a Polynomial}
\label{ugProblemSymRoot}

%
In this section we show you how to work with one root or all roots
\index{root!symbolic}
of a polynomial.
These roots are represented symbolically (as opposed to being
numeric approximations).
See \sectionref{ugxProblemOnePol} and 
\sectionref{ugxProblemPolSys} for
information about solving for the roots of one or more polynomials.

\subsection{Using a Single Root of a Polynomial}
\label{ugxProblemSymRootOne}

Use {\bf rootOf} to get a symbolic root of a polynomial:
$rootOf(p, x)$ returns a root of $p(x)$.

This creates an algebraic number $a$.
\index{algebraic number}
\index{number!algebraic}

\spadcommand{a := rootOf(a**4+1,a) }
$$
a 
$$
\returnType{Type: Expression Integer}

To find the algebraic relation that defines $a$,
use {\bf definingPolynomial}.

\spadcommand{definingPolynomial a }
$$
{a \sp 4}+1 
$$
\returnType{Type: Expression Integer}

You can use $a$ in any further expression,
including a nested {\bf rootOf}.

\spadcommand{b := rootOf(b**2-a-1,b) }
$$
b 
$$
\returnType{Type: Expression Integer}

Higher powers of the roots are automatically reduced during
calculations.

\spadcommand{a + b }
$$
b+a 
$$
\returnType{Type: Expression Integer}

\spadcommand{\% ** 5 }
$$
{{\left( {{10} \  {a \sp 3}}+{{11} \  {a \sp 2}}+{2 \  a} -4 
\right)}
\  b}+{{15} \  {a \sp 3}}+{{10} \  {a \sp 2}}+{4 \  a} -{10} 
$$
\returnType{Type: Expression Integer}

The operation {\bf zeroOf} is similar to {\bf rootOf},
except that it may express the root using radicals in some cases.
\index{radical}

\spadcommand{rootOf(c**2+c+1,c)}
$$
c 
$$
\returnType{Type: Expression Integer}

\spadcommand{zeroOf(d**2+d+1,d)}
$$
\frac{{\sqrt {-3}} -1}{2} 
$$
\returnType{Type: Expression Integer}

\spadcommand{rootOf(e**5-2,e)}
$$
e 
$$
\returnType{Type: Expression Integer}

%Original Page 240

\spadcommand{zeroOf(f**5-2,f)}
$$
\root {5} \of {2} 
$$
\returnType{Type: Expression Integer}

\subsection{Using All Roots of a Polynomial}
\label{ugxProblemSymRootAll}

Use {\bf rootsOf} to get all symbolic roots of a polynomial:
$rootsOf(p, x)$ returns a
list of all the roots of $p(x)$.
If $p(x)$ has a multiple root of order $n$, then that root
\index{root!multiple}
appears $n$ times in the list.
\typeout{Make sure these variables are x0 etc}

Compute all the roots of $x**4 + 1$.

\spadcommand{l := rootsOf(x**4+1,x) }
$$
\left[
 \%x0,  { \%x0 \  \%x1},  - \%x0,  -{ \%x0 \  \%x1} 
\right]
$$
\returnType{Type: List Expression Integer}

As a side effect, the variables $\%x0$ and $\%x1$ are bound
to the first two roots of $x**4+1$.

\spadcommand{\%x0**5 }
$$
- \%x0 
$$
\returnType{Type: Expression Integer}

Although they all satisfy $x**4 + 1 = 0, \%x0$
and $\%x1$ are different algebraic numbers.
To find the algebraic relation that defines each of them,
use {\bf definingPolynomial}.

\spadcommand{definingPolynomial \%x0 }
$$
{ \%x0 \sp 4}+1 
$$
\returnType{Type: Expression Integer}

\spadcommand{definingPolynomial \%x1 }
$$
{ \%x1 \sp 2}+1 
$$
\returnType{Type: Expression Integer}

\spadcommand{[t1:=l.1, t2:=l.2, t3:=l.3, t4:=l.4]}
$$
\left[
 \%x0,  { \%x0 \  \%x1},  - \%x0,  -{ \%x0 \  \%x1} 
\right]
$$
\returnType{Type: List Expression Integer}

We can check that the sum and product of the roots of $x**4+1$ are
its trace and norm.

\spadcommand{t1+t2+t3+t4}
$$
0
$$
\returnType{Type: Expression Integer}

\spadcommand{t1*t2*t3*t4}
$$
1
$$
\returnType{Type: Expression Integer}

%Original Page 241

Corresponding to the pair of operations
{\bf rootOf}/{\bf zeroOf} in
\sectionref{ugxProblemOnePol}, there is
an operation {\bf zerosOf} that, like {\bf rootsOf},
computes all the roots
of a given polynomial, but which expresses some of them in terms of
radicals.

\spadcommand{zerosOf(y**4+1,y) }
$$
\left[
{\frac{{\sqrt {-1}}+1}{\sqrt {2}}},  
{\frac{{\sqrt {-1}} -1}{\sqrt {2}}},  
{\frac{-{\sqrt {-1}} -1}{\sqrt {2}}},  
{\frac{-{\sqrt {-1}}+1}{\sqrt {2}}} 
\right]
$$
\returnType{Type: List Expression Integer}

As you see, only one implicit algebraic number was created
($\%y1$), and its defining equation is this.
The other three roots are expressed in radicals.

\spadcommand{definingPolynomial \%y1 }
$$
{ \%\%var \sp 2}+1 
$$
\returnType{Type: Expression Integer}

\section{Computation of Eigenvalues and Eigenvectors}
\label{ugProblemEigen}
%
In this section we show you
some of Axiom's facilities for computing and
\index{eigenvalue}
manipulating eigenvalues and eigenvectors, also called
\index{eigenvector}
characteristic values and characteristic vectors,
\index{characteristic!value}
respectively.
\index{characteristic!vector}

\vskip 4pc

Let's first create a matrix with integer entries.

\spadcommand{m1 := matrix [ [1,2,1],[2,1,-2],[1,-2,4] ] }
$$
\left[
\begin{array}{ccc}
1 & 2 & 1 \\ 
2 & 1 & -2 \\ 
1 & -2 & 4 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

To get a list of the {\it rational} eigenvalues,
use the operation {\bf eigenvalues}.

\spadcommand{leig := eigenvalues(m1)  }
$$
\left[
5,  {\left( \%K \mid {{ \%K \sp 2} - \%K -5} 
\right)}
\right]
$$
\returnType{Type: List Union(Fraction Polynomial Integer,SuchThat(Symbol,Polynomial Integer))}

Given an explicit eigenvalue, {\bf eigenvector} computes the eigenvectors
corresponding to it.

\spadcommand{eigenvector(first(leig),m1) }
$$
\left[
{\left[ 
\begin{array}{c}
0 \\ 
-{\frac{1}{2}} \\ 
1 
\end{array}
\right]}
\right]
$$
\returnType{Type: List Matrix Fraction Polynomial Fraction Integer}

The operation {\bf eigenvectors} returns a list of pairs of values and
vectors. When an eigenvalue is rational, Axiom gives you
the value explicitly; otherwise, its minimal polynomial is given,
(the polynomial of lowest degree with the eigenvalues as roots),
together with a parametric representation of the eigenvector using the
eigenvalue.

%Original Page 242

This means that if you ask Axiom to {\bf solve}
the minimal polynomial, then you can substitute these roots
\index{polynomial!minimal}
into the parametric form of the corresponding eigenvectors.
\index{minimal polynomial}

You must be aware that unless an exact eigenvalue has been computed,
the eigenvector may be badly in error.

\spadcommand{eigenvectors(m1) }
$$
\begin{array}{@{}l}
\left[
{\left[ {eigval=5},  {eigmult=1},  {eigvec=
{\left[ 
{\left[ 
\begin{array}{c}
0 \\ 
-{\frac{1}{2}} \\ 
1 
\end{array}
\right]}
\right]}}
\right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ 
{eigval={\left( \%L \mid {{ \%L \sp 2} - \%L -5} \right)}},
{eigmult=1},  {eigvec=
{\left[ 
{\left[ 
\begin{array}{c}
 \%L \\ 
2 \\ 
1 
\end{array}
\right]}
\right]}}
\right]}
\right]
\end{array}
$$
\returnType{Type: List Record(eigval: Union(Fraction Polynomial Integer,SuchThat(Symbol,Polynomial Integer)),eigmult: NonNegativeInteger,eigvec: List Matrix Fraction Polynomial Integer)}

Another possibility is to use the operation
{\bf radicalEigenvectors}
tries to compute explicitly the eigenvectors
in terms of radicals.
\index{radical}

\spadcommand{radicalEigenvectors(m1) }
$$
\begin{array}{@{}l}
\left[
{\left[ {radval={\frac{{\sqrt {{21}}}+1}{2}}},  {radmult=1},  
{radvect={\left[ {\left[ 
\begin{array}{c}
{\frac{{\sqrt {{21}}}+1}{2}} \\ 
2 \\ 
1 
\end{array}
\right]}
\right]}}
\right]},
\right.
\\
\\
\displaystyle
 \left[ {radval={\frac{-{\sqrt {{21}}}+1}{2}}},  {radmult=1},  
{radvect={\left[ {\left[ 
\begin{array}{c}
{\frac{-{\sqrt {{21}}}+1}{2}} \\ 
2 \\ 
1 
\end{array}
\right]}
\right]}}
\right],
\\
\\
\displaystyle
\left.
 \left[ {radval=5},  {radmult=1},  
{radvect={\left[ {\left[ 
\begin{array}{c}
0 \\ 
-{\frac{1}{2}} \\ 
1 
\end{array}
\right]}
\right]}}
\right]
\right]
\end{array}
$$
\returnType{Type: List Record(radval: Expression Integer,radmult: Integer,radvect: List Matrix Expression Integer)}

Alternatively, Axiom can compute real or complex approximations to the
\index{approximation}
eigenvectors and eigenvalues using the operations {\bf realEigenvectors}
or {\bf complexEigenvectors}.
They each take an additional argument $\epsilon$
to specify the ``precision'' required.
\index{precision}
In the real case, this means that each approximation will be within
$\pm\epsilon$ of the actual
result.
In the complex case, this means that each approximation will be within
$\pm\epsilon$ of the actual result
in each of the real and imaginary parts.

%Original Page 243

The precision can be specified as a {\tt Float} if the results are
desired in floating-point notation, or as {\tt Fraction Integer} if the
results are to be expressed using rational (or complex rational) numbers.

\spadcommand{realEigenvectors(m1,1/1000) }
$$
\begin{array}{@{}l}
\left[
{\left[ {outval=5},  {outmult=1},  {outvect={\left[ {\left[ 
\begin{array}{c}
0 \\ 
-{\frac{1}{2}} \\ 
1 
\end{array}
\right]}
\right]}}
\right]},
\right.
\\
\\
\displaystyle
 {\left[ {outval={\frac{5717}{2048}}},  {outmult=1},  
{outvect={\left[ {\left[ 
\begin{array}{c}
{\frac{5717}{2048}} \\ 
2 \\ 
1 
\end{array}
\right]}
\right]}}
\right]},
\\
\\
\displaystyle
\left.
 {\left[ {outval=-{\frac{3669}{2048}}},  {outmult=1},  
{outvect={\left[ {\left[ 
\begin{array}{c}
-{\frac{3669}{2048}} \\ 
2 \\ 
1 
\end{array}
\right]}
\right]}}
\right]}
\right]
\end{array}
$$
\returnType{Type: List Record(outval: Fraction Integer,outmult: Integer,outvect: List Matrix Fraction Integer)}

If an $n$ by $n$ matrix has $n$ distinct eigenvalues (and
therefore $n$ eigenvectors) the operation {\bf eigenMatrix}
gives you a matrix of the eigenvectors.

\spadcommand{eigenMatrix(m1) }
$$
\left[
\begin{array}{ccc}
{\frac{{\sqrt {{21}}}+1}{2}} & {\frac{-{\sqrt {{21}}}+1}{2}} & 0 \\ 
2 & 2 & -{\frac{1}{2}} \\ 
1 & 1 & 1 
\end{array}
\right]
$$
\returnType{Type: Union(Matrix Expression Integer,...)}

\spadcommand{m2 := matrix [ [-5,-2],[18,7] ] }
$$
\left[
\begin{array}{cc}
-5 & -2 \\ 
{18} & 7 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

\spadcommand{eigenMatrix(m2) }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

If a symmetric matrix
\index{matrix!symmetric}
has a basis of orthonormal eigenvectors, then
\index{basis!orthonormal}
{\bf orthonormalBasis} computes a list of these vectors.
\index{orthonormal basis}

\spadcommand{m3 := matrix [ [1,2],[2,1] ] }
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
2 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

\spadcommand{orthonormalBasis(m3) }
$$
\left[
{\left[ 
\begin{array}{c}
-{\frac{1}{\sqrt {2}}} \\ 
{\frac{1}{\sqrt {2}}} 
\end{array}
\right]},
 {\left[ 
\begin{array}{c}
{\frac{1}{\sqrt {2}}} \\ 
{\frac{1}{\sqrt {2}}} 
\end{array}
\right]}
\right]
$$
\returnType{Type: List Matrix Expression Integer}

%Original Page 244

\section{Solution of Linear and Polynomial Equations}
\label{ugProblemLinPolEqn}
%
In this section we discuss the Axiom facilities for solving
systems of linear equations, finding the roots of polynomials and
\index{linear equation}
solving systems of polynomial equations.
For a discussion of the solution of differential equations, see
\sectionref{ugProblemDEQ}.

\subsection{Solution of Systems of Linear Equations}
\label{ugxProblemLinSys}

You can use the operation {\bf solve} to solve systems of linear equations.
\index{equation!linear!solving}

The operation {\bf solve} takes two arguments, the list of equations and the
list of the unknowns to be solved for.
A system of linear equations need not have a unique solution.

To solve the linear system:
$$
\begin{array}{rcrcrcr}
  x &+&   y &+&   z &=& 8 \\
3 x &-& 2 y &+&   z &=& 0 \\
  x &+& 2 y &+& 2 z &=& 17
\end{array}
$$
evaluate this expression.

\spadcommand{solve([x+y+z=8,3*x-2*y+z=0,x+2*y+2*z=17],[x,y,z])}
$$
\left[
{\left[ {x=-1},  {y=2},  {z=7} 
\right]}
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

Parameters are given as new variables starting with a percent sign and
{\tt \%} and
the variables are expressed in terms of the parameters.
If the system has no solutions then the empty list is returned.

When you solve the linear system
$$
\begin{array}{rcrcrcr}
  x&+&2 y&+&3 z&=&2 \\
2 x&+&3 y&+&4 z&=&2 \\
3 x&+&4 y&+&5 z&=&2
\end{array}
$$
with this expression
you get a solution involving a parameter.

\spadcommand{solve([x+2*y+3*z=2,2*x+3*y+4*z=2,3*x+4*y+5*z=2],[x,y,z])}
$$
\left[
{\left[ {x={ \%Q -2}},  {y={-{2 \  \%Q}+2}},  {z= \%Q} 
\right]}
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

The system can also be presented as a matrix and a vector.
The matrix contains the coefficients of the linear equations and
the vector contains the numbers appearing on the right-hand sides
of the equations.
You may input the matrix as a list of rows and the vector as a
list of its elements.

To solve the system:
$$
\begin{array}{rcrcrcr}
  x&+&  y&+&  z&=&8  \\
3 x&-&2 y&+&  z&=&0  \\
  x&+&2 y&+&2 z&=&17
\end{array}
$$
in matrix form you would evaluate this expression.

\spadcommand{solve([ [1,1,1],[3,-2,1],[1,2,2] ],[8,0,17])}
$$
\left[
{particular={\left[ -1, 2,  7\right]}},
{basis={\left[ {\left[ 0, 0, 0\right]}\right]}}
\right]
$$
\returnType{Type: Record(particular: Union(Vector Fraction Integer,"failed"),
basis: List Vector Fraction Integer)}

The solutions are presented as a {\tt Record} with two
components: the component {\it particular} contains a particular solution of the given system or
the item {\tt "failed"} if there are no solutions, the component
{\it basis} contains a list of vectors that
are a basis for the space of solutions of the corresponding
homogeneous system.
If the system of linear equations does not have a unique solution,
then the {\it basis} component contains
non-trivial vectors.

%Original Page 245

This happens when you solve the linear system
$$
\begin{array}{rcrcrcr}
  x&+&2 y&+&3 z&=&2 \\
2 x&+&3 y&+&4 z&=&2 \\
3 x&+&4 y&+&5 z&=&2
\end{array}
$$
with this command.

\spadcommand{solve([ [1,2,3],[2,3,4],[3,4,5] ],[2,2,2])}
$$
\left[
{particular={\left[ -2, 2, 0 \right]}},
{basis={\left[ {\left[ 1, -2, 1 \right]}\right]}}
\right]
$$
\returnType{Type: Record(particular: Union(Vector Fraction Integer,"failed"),
basis: List Vector Fraction Integer)}


All solutions of this system are obtained by adding the particular
solution with a linear combination of the {\it basis} vectors.

When no solution exists then {\tt "failed"} is returned as the
{\it particular} component, as follows:

\spadcommand{solve([ [1,2,3],[2,3,4],[3,4,5] ],[2,3,2])}
$$
\left[
{particular= \mbox{\tt "failed"} }, 
{basis={\left[ {\left[ 1, -2, 1\right]}\right]}}
\right]
$$
\returnType{Type: Record(particular: Union(Vector Fraction Integer,"failed"),
basis: List Vector Fraction Integer)}

When you want to solve a system of homogeneous equations (that is,
a system where the numbers on the right-hand sides of the
\index{nullspace}
equations are all zero) in the matrix form you can omit the second
argument and use the {\bf nullSpace} operation.

This computes the solutions of the following system of equations:
$$
\begin{array}{rcrcrcr}
  x&+&2 y&+&3 z&=&0  \\
2 x&+&3 y&+&4 z&=&0  \\
3 x&+&4 y&+&5 z&=&0
\end{array}
$$
The result is given as a list of vectors and
these vectors form a basis for the solution space.

\spadcommand{nullSpace([ [1,2,3],[2,3,4],[3,4,5] ])}
$$
\left[
{\left[ 1, -2, 1 \right]}
\right]
$$
\returnType{Type: List Vector Integer}

\subsection{Solution of a Single Polynomial Equation}
\label{ugxProblemOnePol}

Axiom can solve polynomial equations producing either approximate
\index{polynomial!root finding}
or exact solutions.
\index{equation!polynomial!solving}
Exact solutions are either members of the ground
field or can be presented symbolically as roots of irreducible polynomials.

This returns the one rational root along with an irreducible
polynomial describing the other solutions.

\spadcommand{solve(x**3  = 8,x)}
$$
\left[
{x=2},  {{{x \sp 2}+{2 \  x}+4}=0} 
\right]
$$
\returnType{Type: List Equation Fraction Polynomial Integer}

%Original Page 246

If you want solutions expressed in terms of radicals you would use this
instead.
\index{radical}

\spadcommand{radicalSolve(x**3  = 8,x)}
$$
\left[
{x={-{\sqrt {-3}} -1}}, {x={{\sqrt {-3}} -1}}, {x=2} 
\right]
$$
\returnType{Type: List Equation Expression Integer}

The {\bf solve} command always returns a value but
{\bf radicalSolve} returns only the solutions that it is
able to express in terms of radicals.
\index{radical}

If the polynomial equation has rational coefficients
you can ask for approximations to its real roots by calling
solve with a second argument that specifies the ``precision''
\index{precision}
$\epsilon$.
This means that each approximation will be within
$\pm\epsilon$ of the actual
result.

Notice that the type of second argument controls the type of the result.

\spadcommand{solve(x**4 - 10*x**3 + 35*x**2 - 50*x + 25,.0001)}
$$
\left[
{x={3.6180114746 09375}}, {x={1.3819885253 90625}} 
\right]
$$
\returnType{Type: List Equation Polynomial Float}

If you give a floating-point precision you get a floating-point result;
if you give the precision as a rational number you get a rational result.

\spadcommand{solve(x**3-2,1/1000)}
$$
\left[
{x={\frac{2581}{2048}}} 
\right]
$$
\returnType{Type: List Equation Polynomial Fraction Integer}

If you want approximate complex results you should use the
\index{approximation}
command {\bf complexSolve} that takes the same precision argument
$\epsilon$.

\spadcommand{complexSolve(x**3-2,.0001)}
$$
\begin{array}{@{}l}
\left[
{x={1.2599182128 90625}},
\right.
\\
\\
\displaystyle
{x={-{0.6298943279 5395613131} -{{1.0910949707 03125} \  i}}}, 
\\
\\
\displaystyle
\left.
{x={-{0.6298943279 5395613131}+{{1.0910949707 03125} \  
i}}} 
\right]
\end{array}
$$
\returnType{Type: List Equation Polynomial Complex Float}

Each approximation will be within
$\pm\epsilon$ of the actual result
in each of the real and imaginary parts.

\spadcommand{complexSolve(x**2-2*\%i+1,1/100)}
$$
\left[
{x={-{\frac{13028925}{16777216}} -{{\frac{325}{256}} \  i}}}, 
{x={{\frac{13028925}{16777216}}+{{\frac{325}{256}} \  i}}} 
\right]
$$
\returnType{Type: List Equation Polynomial Complex Fraction Integer}

Note that if you omit the {\tt =} from the first argument
Axiom generates an equation by equating the first argument to zero.
Also, when only one variable is present in the equation, you
do not need to specify the variable to be solved for, that is,
you can omit the second argument.

Axiom can also solve equations involving rational functions.
Solutions where the denominator vanishes are discarded.

\spadcommand{radicalSolve(1/x**3 + 1/x**2 + 1/x = 0,x)}
$$
\left[
{x={\frac{-{\sqrt {-3}} -1}{2}}}, {x={\frac{{\sqrt {-3}} -1}{2}}} 
\right]
$$
\returnType{Type: List Equation Expression Integer}

%Original Page 247

\subsection{Solution of Systems of Polynomial Equations}
\label{ugxProblemPolSys}

Given a system of equations of rational functions with exact coefficients:
\index{equation!polynomial!solving}
\vskip 0.1cm
$$
\begin{array}{c}
p_1(x_1, \ldots, x_n) \\ \vdots \\ p_m(x_1,\ldots,x_n)
\end{array}
$$

Axiom can find
numeric or symbolic solutions.
The system is first split into irreducible components, then for
each component, a triangular system of equations is found that reduces
the problem to sequential solution of univariate polynomials resulting
from substitution of partial solutions from the previous stage.
$$
\begin{array}{c}
q_1(x_1, \ldots, x_n) \\ \vdots \\ q_m(x_n)
\end{array}
$$

Symbolic solutions can be presented using ``implicit'' algebraic numbers
defined as roots of irreducible polynomials or in terms of radicals.
Axiom can also find approximations to the real or complex roots
of a system of polynomial equations to any user-specified accuracy.

The operation {\bf solve} for systems is used in a way similar
to {\bf solve} for single equations.
Instead of a polynomial equation, one has to give a list of
equations and instead of a single variable to solve for, a list of
variables.
For solutions of single equations see \sectionref{ugxProblemOnePol}.

Use the operation {\bf solve} if you want implicitly presented
solutions.

\spadcommand{solve([3*x**3 + y + 1,y**2 -4],[x,y])}
$$
\left[
{\left[ {x=-1}, {y=2} \right]},
{\left[ {{{x \sp 2} -x+1}=0}, {y=2} \right]},
{\left[ {{{3 \  {x \sp 3}} -1}=0}, {y=-2} \right]}
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

\spadcommand{solve([x = y**2-19,y = z**2+x+3,z = 3*x],[x,y,z])}
$$
\left[
{\left[ {x={\frac{z}{3}}}, 
{y={\frac{{3 \  {z \sp 2}}+z+9}{3}}}, 
{{{9 \  {z \sp 4}}+{6 \  {z \sp 3}}+{{55} \  {z \sp 2}}+{{15} \  z} -{90}}=0} 
\right]}
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

%Original Page 248

Use {\bf radicalSolve} if you want your solutions expressed
in terms of radicals.

\spadcommand{radicalSolve([3*x**3 + y + 1,y**2 -4],[x,y])}
$$
\begin{array}{@{}l}
\left[
{\left[ {x={\frac{{\sqrt {-3}}+1}{2}}}, {y=2} \right]},
{\left[ {x={\frac{-{\sqrt {-3}}+1}{2}}}, {y=2} \right]},
\right.
\\
\\
\displaystyle
{\left[ {x={\frac{-{{\sqrt {-1}} \  {\sqrt {3}}} -1}
{2 \  {\root {3} \of {3}}}}}, {y=-2} \right]},
{\left[ {x={\frac{{{\sqrt {-1}} \  {\sqrt {3}}} -1}
{2 \  {\root {3} \of {3}}}}}, {y=-2} \right]},
\\
\\
\displaystyle
\left.
{\left[ {x={\frac{1}{\root {3} \of {3}}}}, {y=-2} \right]},
{\left[ {x=-1}, {y=2} \right]}
\right]
\end{array}
$$
\returnType{Type: List List Equation Expression Integer}

To get numeric solutions you only need to give the list of
equations and the precision desired.
The list of variables would be redundant information since there
can be no parameters for the numerical solver.

If the precision is expressed as a floating-point number you get
results expressed as floats.

\spadcommand{solve([x**2*y - 1,x*y**2 - 2],.01)}
$$
\left[
{\left[ {y={1.5859375}}, {x={0.79296875}} \right]}
\right]
$$
\returnType{Type: List List Equation Polynomial Float}

To get complex numeric solutions, use the operation {\bf complexSolve},
which takes the same arguments as in the real case.

\spadcommand{complexSolve([x**2*y - 1,x*y**2 - 2],1/1000)}
$$
\begin{array}{@{}l}
\left[
{\left[ {y={\frac{1625}{1024}}}, {x={\frac{1625}{2048}}} \right]},
\right.
\\
\\
\displaystyle
{\left[ 
{y={-{\frac{435445573689}{549755813888}} -{{\frac{1407}{1024}} \  i}}}, 
{x={-{\frac{435445573689}{1099511627776}} -{{\frac{1407}{2048}} \  i}}} 
\right]},
\\
\\
\displaystyle
\left.
{\left[ 
{y={-{\frac{435445573689}{549755813888}}+{{\frac{1407}{1024}} \  i}}}, 
{x={-{\frac{435445573689}{1099511627776}}+{{\frac{1407}{2048}} \  i}}} 
\right]}
\right]
\end{array}
$$
\returnType{Type: List List Equation Polynomial Complex Fraction Integer}


It is also possible to solve systems of equations in rational functions
over the rational numbers.
Note that $[x = 0.0, a = 0.0]$ is not returned as a solution since
the denominator vanishes there.

\spadcommand{solve([x**2/a = a,a = a*x],.001)}
$$
\left[
{\left[ {x={1.0}}, {a=-{1.0}} \right]},
{\left[ {x={1.0}}, {a={1.0}} \right]}
\right]
$$
\returnType{Type: List List Equation Polynomial Float}


%Original Page 249

When solving equations with
denominators, all solutions where the denominator vanishes are
discarded.

\spadcommand{radicalSolve([x**2/a + a + y**3 - 1,a*y + a + 1],[x,y])}
$$
\begin{array}{@{}l}
\left[
{\left[ 
{x=-{\sqrt {{\frac{-{a \sp 4}+{2 \  {a \sp 3}}+{3 \  {a \sp 2}}+{3 \  
a}+1}{a \sp 2}}}}}, 
{y={\frac{-a -1}{a}}} 
\right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ {x={\sqrt {{\frac{-{a \sp 4}+{2 \  {a \sp 3}}+{3 \  {a \sp 2}}+{3 \  
a}+1}{a \sp 2}}}}}, 
{y={\frac{-a -1}{a}}} 
\right]}
\right]
\end{array}
$$
\returnType{Type: List List Equation Expression Integer}

\section{Limits}
\label{ugProblemLimits}

%
To compute a limit, you must specify a functional expression,
\index{limit}
a variable, and a limiting value for that variable.
If you do not specify a direction, Axiom attempts to
compute a two-sided limit.

Issue this to compute the limit
$$\lim_{x \rightarrow 1}{\frac{\displaystyle x^2 - 3x + 2}
{\displaystyle x^2 - 1}}.$$

\spadcommand{limit((x**2 - 3*x + 2)/(x**2 - 1),x = 1)}
$$
-{\frac{1}{2}} 
$$
\returnType{Type: Union(OrderedCompletion Fraction Polynomial Integer,...)}

Sometimes the limit when approached from the left is different from
the limit from the right and, in this case, you may wish to ask for a
one-sided limit.  Also, if you have a function that is only defined on
one side of a particular value, \index{limit!one-sided vs. two-sided}
you can compute a one-sided limit.

The function $log(x)$ is only defined to the right of zero, that is,
for $x > 0$.  Thus, when computing limits of functions involving
$log(x)$, you probably want a ``right-hand'' limit.

\spadcommand{limit(x * log(x),x = 0,"right")}
$$
0 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

When you do not specify ``$right$'' or ``$left$'' as the optional fourth
argument, {\bf limit} tries to compute a two-sided limit.  Here the
limit from the left does not exist, as Axiom indicates when you try to
take a two-sided limit.

\spadcommand{limit(x * log(x),x = 0)}
$$
\left[
{leftHandLimit= \mbox{\tt "failed"} }, {rightHandLimit=0} 
\right]
$$
\returnType{Type: Union(Record(leftHandLimit: 
Union(OrderedCompletion Expression Integer,"failed"),
rightHandLimit: Union(OrderedCompletion Expression Integer,"failed")),...)}

A function can be defined on both sides of a particular value, but
tend to different limits as its variable approaches that value from
the left and from the right.  We can construct an example of this as
follows: Since $\sqrt{y^2}$ is simply the absolute value of $y$, the
function $\sqrt{y^2} / y$ is simply the sign ($+1$ or $-1$) of the
nonzero real number $y$.  Therefore, $\sqrt{y^2} / y = -1$ for $y < 0$
and $\sqrt{y^2} / y = +1$ for $y > 0$.

%Original Page 250

This is what happens when we take the limit at $y = 0$.
The answer returned by Axiom gives both a
``left-hand'' and a ``right-hand'' limit.

\spadcommand{limit(sqrt(y**2)/y,y = 0)}
$$
\left[
{leftHandLimit=-1}, {rightHandLimit=1} 
\right]
$$
\returnType{Type: Union(Record(leftHandLimit: 
Union(OrderedCompletion Expression Integer,"failed"),
rightHandLimit: Union(OrderedCompletion Expression Integer,"failed")),...)}

Here is another example, this time using a more complicated function.

\spadcommand{limit(sqrt(1 - cos(t))/t,t = 0)}
$$
\left[
{leftHandLimit=-{\frac{1}{\sqrt {2}}}}, 
{rightHandLimit={\frac{1}{\sqrt {2}}}} 
\right]
$$
\returnType{Type: Union(Record(leftHandLimit: 
Union(OrderedCompletion Expression Integer,"failed"),
rightHandLimit: Union(OrderedCompletion Expression Integer,"failed")),...)}

You can compute limits at infinity by passing either 
\index{limit!at infinity} $+\infty$ or $-\infty$ as the third 
argument of {\bf limit}.

To do this, use the constants $\%plusInfinity$ and $\%minusInfinity$.

\spadcommand{limit(sqrt(3*x**2 + 1)/(5*x),x = \%plusInfinity)}
$$
\frac{\sqrt {3}}{5}
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

\spadcommand{limit(sqrt(3*x**2 + 1)/(5*x),x = \%minusInfinity)}
$$
-{\frac{\sqrt {3}}{5}} 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

You can take limits of functions with parameters.
\index{limit!of function with parameters}
As you can see, the limit is expressed in terms of the parameters.

\spadcommand{limit(sinh(a*x)/tan(b*x),x = 0)}
$$
\frac{a}{b}
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

When you use {\bf limit}, you are taking the limit of a real
function of a real variable.

When you compute this, Axiom returns $0$ because, as a function of a
real variable, $sin(1/z)$ is always between $-1$ and $1$, so 
$z * sin(1/z)$ tends to $0$ as $z$ tends to $0$.

\spadcommand{limit(z * sin(1/z),z = 0)}
$$
0 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

However, as a function of a {\it complex} variable, $sin(1/z)$ is badly
\index{limit!real vs. complex}
behaved near $0$ (one says that $sin(1/z)$ has an
\index{essential singularity}
{\it essential singularity} at $z = 0$).
\index{singularity!essential}

%Original Page 251

When viewed as a function of a complex variable, $z * sin(1/z)$
does not approach any limit as $z$ tends to $0$ in the complex plane.
Axiom indicates this when we call {\bf complexLimit}.

\spadcommand{complexLimit(z * sin(1/z),z = 0)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

Here is another example.
As $x$ approaches $0$ along the real axis, $exp(-1/x**2)$
tends to $0$.
\spadcommand{limit(exp(-1/x**2),x = 0)}
$$
0 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

However, if $x$ is allowed to approach $0$ along any path in the
complex plane, the limiting value of $exp(-1/x**2)$ depends on the
path taken because the function has an essential singularity at $x=0$.
This is reflected in the error message returned by the function.
\spadcommand{complexLimit(exp(-1/x**2),x = 0)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

You can also take complex limits at infinity, that is, limits of a
function of $z$ as $z$ approaches infinity on the Riemann sphere.  Use
the symbol $\%infinity$ to denote ``complex infinity.''

As above, to compute complex limits rather than real limits, use
{\bf complexLimit}.

\spadcommand{complexLimit((2 + z)/(1 - z),z = \%infinity)}
$$
-1 
$$
\returnType{Type: OnePointCompletion Fraction Polynomial Integer}

In many cases, a limit of a real function of a real variable exists
when the corresponding complex limit does not.  This limit exists.

\spadcommand{limit(sin(x)/x,x = \%plusInfinity)}
$$
0 
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}

But this limit does not.

\spadcommand{complexLimit(sin(x)/x,x = \%infinity)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

\section{Laplace Transforms}
\label{ugProblemLaplace}

Axiom can compute some forward Laplace transforms, mostly
\index{Laplace transform} of elementary \index{function!elementary}
functions \index{transform!Laplace} not involving logarithms, although
some cases of special functions are handled.

To compute the forward Laplace transform of $F(t)$ with respect to
$t$ and express the result as $f(s)$, issue the command
$laplace(F(t), t, s)$.

\spadcommand{laplace(sin(a*t)*cosh(a*t)-cos(a*t)*sinh(a*t), t, s)}
$$
\frac{4 \  {a \sp 3}}{{s \sp 4}+{4 \  {a \sp 4}}} 
$$
\returnType{Type: Expression Integer}

Here are some other non-trivial examples.

\spadcommand{laplace((exp(a*t) - exp(b*t))/t, t, s)}
$$
-{\log \left({{s -a}} \right)}+{\log\left({{s -b}} \right)}
$$
\returnType{Type: Expression Integer}

\spadcommand{laplace(2/t * (1 - cos(a*t)), t, s)}
$$
{\log \left({{{s \sp 2}+{a \sp 2}}} \right)}-{2 \  {\log \left({s} \right)}}
$$
\returnType{Type: Expression Integer}

%Original Page 252

\spadcommand{laplace(exp(-a*t) * sin(b*t) / b**2, t, s)}
$$
\frac{1}{{b \  {s \sp 2}}+{2 \  a \  b \  s}+{b \sp 3}+{{a \sp 2} \  b}} 
$$
\returnType{Type: Expression Integer}

\spadcommand{laplace((cos(a*t) - cos(b*t))/t, t, s)}
$$
\frac{{\log \left({{{s \sp 2}+{b \sp 2}}} \right)}-
{\log \left({{{s \sp 2}+{a \sp 2}}} \right)}}{2} 
$$
\returnType{Type: Expression Integer}

Axiom also knows about a few special functions.

\spadcommand{laplace(exp(a*t+b)*Ei(c*t), t, s)}
$$
\frac{{e \sp b} \  {\log \left({{\frac{s+c -a}{c}}} \right)}}{s -a} 
$$
\returnType{Type: Expression Integer}

\spadcommand{laplace(a*Ci(b*t) + c*Si(d*t), t, s)}
$$
\frac{{a \  {\log \left({{\frac{{s \sp 2}+{b \sp 2}}{b \sp 2}}} \right)}}+
{2\  c \  {\arctan \left({{\frac{d}{s}}} \right)}}}{2 \  s} 
$$
\returnType{Type: Expression Integer}

When Axiom does not know about a particular transform,
it keeps it as a formal transform in the answer.

\spadcommand{laplace(sin(a*t) - a*t*cos(a*t) + exp(t**2), t, s)}
$$
\frac{{{\left( {s \sp 4}+{2 \  {a \sp 2} \  {s \sp 2}}+{a \sp 4} \right)}
\  {laplace \left({{e \sp {t \sp 2}}, t, s} \right)}}+
{2\  {a \sp 3}}}{{s \sp 4}+{2 \  {a \sp 2} \  {s \sp 2}}+{a \sp 4}} 
$$
\returnType{Type: Expression Integer}

\section{Integration}
\label{ugProblemIntegration}

%
Integration is the reverse process of differentiation, that is,
\index{integration} an {\it integral} of a function $f$ with respect
to a variable $x$ is any function $g$ such that $D(g,x)$ is equal to
$f$.

The package {\tt FunctionSpaceIntegration} provides the top-level
integration operation, \spadfunFrom{integrate}{FunctionSpaceIntegration},
for integrating real-valued elementary functions.
\index{FunctionSpaceIntegration}

\spadcommand{integrate(cosh(a*x)*sinh(a*x), x)}
$$
\frac{{{\sinh \left({{a \  x}} \right)}\sp 2}+
{{\cosh \left({{a \  x}} \right)}\sp 2}} 
{4 \  a} 
$$
\returnType{Type: Union(Expression Integer,...)}

Unfortunately, antiderivatives of most functions cannot be expressed in
terms of elementary functions.

\spadcommand{integrate(log(1 + sqrt(a * x + b)) / x, x)}
$$
\int \sp{\displaystyle x} {{
\frac{\log \left({{{\sqrt {{b+{ \%M \  a}}}}+1}} \right)}{\%M}} \  {d \%M}} 
$$
\returnType{Type: Union(Expression Integer,...)}

Given an elementary function to integrate, Axiom returns a formal
integral as above only when it can prove that the integral is not
elementary and not when it cannot determine the integral.
In this rare case it prints a message that it cannot
determine if an elementary integral exists.

%Original Page 253

Similar functions may have antiderivatives \index{antiderivative}
that look quite different because the form of the antiderivative
depends on the sign of a constant that appears in the function.

\spadcommand{integrate(1/(x**2 - 2),x)}
$$
\frac{\log \left({{
\frac{{{\left( {x \sp 2}+2 \right)}\  {\sqrt {2}}} -{4 \  x}} 
{{x \sp 2} -2}}} \right)}
{2 \  {\sqrt {2}}} 
$$
\returnType{Type: Union(Expression Integer,...)}

\spadcommand{integrate(1/(x**2 + 2),x)}
$$
\frac{\arctan \left({{\frac{x \  {\sqrt {2}}}{2}}} \right)}{\sqrt {2}} 
$$
\returnType{Type: Union(Expression Integer,...)}

If the integrand contains parameters, then there may be several possible
antiderivatives, depending on the signs of expressions of the parameters.

In this case Axiom returns a list of answers that cover all the
possible cases.  Here you use the answer involving the square root of
$a$ when $a > 0$ and \index{integration!result as list of real
functions} the answer involving the square root of $-a$ when $a < 0$.

\spadcommand{integrate(x**2 / (x**4 - a**2), x)}
$$
\begin{array}{@{}l}
\displaystyle
\left[
{\frac{{\log 
\left(
{{\frac{{{\left( {x \sp 2}+a \right)}
\  {\sqrt {a}}} -{2 \  a \  x}}{{x \sp 2} -a}}} 
\right)}+
{2\  {\arctan \left({{\frac{x \  {\sqrt {a}}}{a}}} \right)}}}
{4 \  {\sqrt {a}}}}, 
\right.
\\
\\
\displaystyle
\left.
{\frac{{\log \left({{\frac{{{\left( {x \sp 2} -a \right)}
\  {\sqrt {-a}}}+{2 \  a \  x}}{{x \sp 2}+a}}} 
\right)}
-{2 \  {\arctan \left({{\frac{x \  {\sqrt {-a}}}{a}}} \right)}}}
{4 \  {\sqrt {-a}}}} 
\right]
\end{array}
$$
\returnType{Type: Union(List Expression Integer,...)}

If the parameters and the variables of integration can be complex
numbers rather than real, then the notion of sign is not defined.  In
this case all the possible answers can be expressed as one complex
function.  To get that function, rather than a list of real functions,
use \spadfunFrom{complexIntegrate}{FunctionSpaceComplexIntegration},
which is provided by the package \index{integration!result as a
complex functions} {\tt FunctionSpaceComplexIntegration}.
\index{FunctionSpaceComplexIntegration}

This operation is used for integrating complex-valued elementary
functions.

\spadcommand{complexIntegrate(x**2 / (x**4 - a**2), x)}
$$
\frac{\left(
\begin{array}{@{}l}
\displaystyle
{{\sqrt {{4 \  a}}} \  {\log 
\left(
{{\frac{{x \  {\sqrt {-{4 \  a}}}}+{2 \  a}}{\sqrt {-{4 \  a}}}}} 
\right)}} -
{{\sqrt {-{4 \  a}}} \  {\log 
\left(
{{\frac{{x \  {\sqrt {{4 \  a}}}}+{2 \  a}}{\sqrt {{4 \  a}}}}} 
\right)}}+
\\
\\
\displaystyle
{{\sqrt{-{4 \  a}}} \  {\log 
\left(
{{\frac{{x \  {\sqrt {{4 \  a}}}} -{2 \  a}}{\sqrt {{4 \  a}}}}} 
\right)}}
-{{\sqrt {{4 \  a}}} \  {\log 
\left(
{{\frac{{x \  {\sqrt {-{4 \  a}}}} -{2 \  a}}{\sqrt {-{4 \  a}}}}} 
\right)}}
\end{array}
\right)}
{2 \  {\sqrt {-{4 \  a}}} \  {\sqrt {{4 \  a}}}} 
$$
\returnType{Type: Expression Integer}

%Original Page 254

As with the real case, antiderivatives for most complex-valued
functions cannot be expressed in terms of elementary functions.

\spadcommand{complexIntegrate(log(1 + sqrt(a * x + b)) / x, x)}
$$
\int \sp{\displaystyle x} 
{{\frac{\log \left({{{\sqrt {{b+{ \%M \  a}}}}+1}} \right)}{\%M}} \  {d \%M}} 
$$
\returnType{Type: Expression Integer}

Sometimes {\bf integrate} can involve symbolic algebraic numbers
such as those returned by \spadfunFrom{rootOf}{Expression}.
To see how to work with these strange generated symbols (such as
$\%\%a0$), see \sectionref{ugxProblemSymRootAll}.

Definite integration is the process of computing the area between
\index{integration!definite}
the $x$-axis and the curve of a function $f(x)$.
The fundamental theorem of calculus states that if $f$ is
continuous on an interval $a..b$ and if there exists a function $g$
that is differentiable on $a..b$ and such that $D(g, x)$
is equal to $f$, then the definite integral of $f$
for $x$ in the interval $a..b$ is equal to $g(b) - g(a)$.

The package {\tt RationalFunctionDefiniteIntegration} provides
the top-level definite integration operation,
\spadfunFrom{integrate}{RationalFunctionDefiniteIntegration},
for integrating real-valued rational functions.

\spadcommand{integrate((x**4 - 3*x**2 + 6)/(x**6-5*x**4+5*x**2+4), x = 1..2)}
$$
\frac{{2 \  {\arctan \left({8} \right)}}+
{2\  {\arctan \left({5} \right)}}+
{2\  {\arctan \left({2} \right)}}+
{2\  {\arctan \left({{\frac{1}{2}}} \right)}}
-\pi}{2} 
$$
\returnType{Type: Union(f1: OrderedCompletion Expression Integer,...)}

Axiom checks beforehand that the function you are integrating is
defined on the interval $a..b$, and prints an error message if it
finds that this is not case, as in the following example:
\begin{verbatim}
integrate(1/(x**2-2), x = 1..2)

    >> Error detected within library code:
       Pole in path of integration
       You are being returned to the top level
       of the interpreter.
\end{verbatim}
When parameters are present in the function, the function may or may not be
defined on the interval of integration.

If this is the case, Axiom issues a warning that a pole might
lie in the path of integration, and does not compute the integral.

\spadcommand{integrate(1/(x**2-a), x = 1..2)}
$$
potentialPole 
$$
\returnType{Type: Union(pole: potentialPole,...)}

If you know that you are using values of the parameter for which
the function has no pole in the interval of integration, use the
string {\tt "noPole"} as a third argument to
\spadfunFrom{integrate}{RationalFunctionDefiniteIntegration}:

%Original Page 255

The value here is, of course, incorrect if $sqrt(a)$ is between
$1$ and $2.$

\spadcommand{integrate(1/(x**2-a), x = 1..2, "noPole")}
$$
\begin{array}{@{}l}
\left[
\displaystyle
\frac{\left(
\begin{array}{@{}l}
-{\log \left({{\frac{{{\left( -{4 \  {a \sp 2}} -{4 \  a} \right)}
\  {\sqrt {a}}}+{a \sp 3}+{6 \  {a \sp 2}}+a}{{a \sp 2} -{2 \  a}+1}}} 
\right)}+
\\
\\
\displaystyle
{\log\left({{\frac{{{\left( -{8 \  {a \sp 2}} -{{32} \  a} \right)}
\  {\sqrt {a}}}+{a \sp 3}+{{24} \  {a \sp 2}}+{{16} \  a}}{{a \sp 2} 
-{8 \  a}+{16}}}} 
\right)}
\end{array}
\right)}
{4 \  {\sqrt {a}}},
\right.
\\
\\
\displaystyle
\left. 
{\frac{-{\arctan \left({{\frac{2 \  {\sqrt {-a}}}{a}}} \right)}+
{\arctan\left({{\frac{\sqrt {-a}}{a}}} \right)}}
{\sqrt {-a}}} 
\right]
\end{array}
$$
\returnType{Type: Union(f2: List OrderedCompletion Expression Integer,...)}

\section{Working with Power Series}
\label{ugProblemSeries}
%
Axiom has very sophisticated facilities for working with power
\index{series}
series.
\index{power series}

Infinite series are represented by a list of the coefficients that
have already been determined, together with a function for computing
the additional coefficients if needed.

The system command that determines how many terms of a series is
displayed is {\tt )set streams calculate}.  For the purposes of this
book, we have used this system command to display fewer than ten
terms.  \index{set streams calculate} Series can be created from
expressions, from functions for the series coefficients, and from
applications of operations on existing series.  The most general
function for creating a series is called {\bf series}, although you
can also use {\bf taylor}, {\bf laurent} and {\bf puiseux} in
situations where you know what kind of exponents are involved.

For information about solving differential equations in terms of
power series, see \sectionref{ugxProblemDEQSeries}.

%Original Page 256

\subsection{Creation of Power Series}
\label{ugxProblemSeriesCreate}

This is the easiest way to create a power series.  This tells Axiom
that $x$ is to be treated as a power series, \index{series!creating}
so functions of $x$ are again power series.

\spadcommand{x := series 'x }
$$
x 
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

We didn't say anything about the coefficients of the power series, so
the coefficients are general expressions over the integers.  This
allows us to introduce denominators, symbolic constants, and other
variables as needed.

Here the coefficients are integers (note that the coefficients are the
Fibonacci \index{Fibonacci numbers} numbers).

\spadcommand{1/(1 - x - x**2) }
$$
1+x+
{2 \  {x \sp 2}}+
{3 \  {x \sp 3}}+
{5 \  {x \sp 4}}+
{8 \  {x \sp 5}}+
{{13} \  {x \sp 6}}+
{{21} \  {x \sp 7}}+
{{34} \  {x \sp 8}}+
{{55} \  {x \sp 9}}+
{{89} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

This series has coefficients that are rational numbers.

\spadcommand{sin(x) }
$$
x -
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{1}{120}} \  {x \sp 5}} -
{{\frac{1}{5040}} \  {x \sp 7}}+
{{\frac{1}{362880}} \  {x \sp 9}} -
{{\frac{1}{39916800}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

When you enter this expression you introduce the symbolic constants
$sin(1)$ and $cos(1).$

\spadcommand{sin(1 + x) }
$$
\begin{array}{@{}l}
\displaystyle
{\sin \left({1} \right)}+
{{\cos\left({1} \right)}\  x} -
{{\frac{\sin \left({1} \right)}{2}} \  {x \sp 2}} -
{{\frac{\cos \left({1} \right)}{6}} \  {x \sp 3}}+
{{\frac{\sin \left({1} \right)}{24}} \  {x \sp 4}}+
{{\frac{\cos \left({1} \right)}{120}} \  {x \sp 5}} -
{{\frac{\sin \left({1} \right)}{720}} \  {x \sp 6}} -
\\
\\
\displaystyle
{{\frac{\cos \left({1} \right)}{5040}} \  {x \sp 7}}+
{{\frac{\sin \left({1} \right)}{40320}} \  {x \sp 8}}+
{{\frac{\cos \left({1} \right)}{362880}} \  {x \sp 9}} -
{{\frac{\sin \left({1} \right)}{3628800}} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

When you enter the expression
the variable $a$ appears in the resulting series expansion.

\spadcommand{sin(a * x) }
$$
{a \  x} -
{{\frac{a \sp 3}{6}} \  {x \sp 3}}+
{{\frac{a \sp 5}{120}} \  {x \sp 5}} -
{{\frac{a \sp 7}{5040}} \  {x \sp 7}}+
{{\frac{a \sp 9}{362880}} \  {x \sp 9}} -
{{\frac{a \sp {11}}{39916800}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

You can also convert an expression into a series expansion.  This
expression creates the series expansion of $1/log(y)$ about $y = 1$.
For details and more examples, see \sectionref{ugxProblemSeriesConversions}.

\spadcommand{series(1/log(y),y = 1)}
$$
\begin{array}{@{}l}
\displaystyle
{{\left( y -1 \right)}\sp {\left( -1 \right)}}+
{\frac{1}{2}} -{{\frac{1}{12}} \  {\left( y -1 \right)}}+
{{\frac{1}{24}} \  {{\left( y -1 \right)}\sp 2}} -
{{\frac{19}{720}} \  {{\left( y -1 \right)}\sp 3}}+
{{\frac{3}{160}} \  {{\left( y -1 \right)}\sp 4}} -
\\
\\
\displaystyle
{{\frac{863}{60480}} \  {{\left( y -1 \right)}\sp 5}}+
{{\frac{275}{24192}} \  {{\left( y -1 \right)}\sp 6}} -
{{\frac{33953}{3628800}} \  {{\left( y -1 \right)}\sp 7}}+
\\
\\
\displaystyle
{{\frac{8183}{1036800}} \  {{\left( y -1 \right)}\sp 8}} -
{{\frac{3250433}{479001600}} \  {{\left( y -1 \right)}\sp 9}}+
{O \left({{{\left( y -1 \right)}\sp {10}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,y,1)}

You can create power series with more general coefficients.  You
normally accomplish this via a type declaration (see 
\sectionref{ugTypesDeclare}).
See \sectionref{ugxProblemSeriesFunctions} 
for some warnings about working with declared series.

%Original Page 257

We declare that $y$ is a one-variable Taylor series
\index{series!Taylor} ({\tt UTS} is the abbreviation for 
{\tt Univariate\-TaylorSeries}) in the variable $z$ with {\tt FLOAT} 
(that is, floating-point) coefficients, centered about $0.$ Then, by
assignment, we obtain the Taylor expansion of $exp(z)$ with
floating-point coefficients.  \index{UnivariateTaylorSeries}

\spadcommand{y : UTS(FLOAT,'z,0) := exp(z) }
$$
\begin{array}{@{}l}
{1.0}+z+
{{0.5} \  {z \sp 2}}+
{{0.1666666666\ 6666666667} \  {z \sp 3}}+
\\
\\
\displaystyle
{{0.0416666666\ 6666666666 7} \  {z \sp 4}}+
{{0.0083333333\ 3333333333 34} \  {z \sp 5}}+
\\
\\
\displaystyle
{{0.0013888888\ 8888888888 89} \  {z \sp 6}}+
{{0.0001984126\ 9841269841 27} \  {z \sp 7}}+
\\
\\
\displaystyle
{{0.0000248015\ 8730158730 1587} \  {z \sp 8}}+
{{0.0000027557\ 3192239858 90653} \  {z \sp 9}}+
\\
\\
\displaystyle
{{0.2755731922\ 3985890653 E -6} \  {z \sp {10}}}+
{O \left({{z \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Float,z,0.0)}

You can also create a power series by giving an explicit formula for
its $n$-th coefficient.  For details and more examples, see
\sectionref{ugxProblemSeriesFormula}.

To create a series about $w = 0$ whose $n$-th Taylor coefficient is
$1/n!$, you can evaluate this expression.  This is the Taylor
expansion of $exp(w)$ at $w = 0$.

\spadcommand{series(1/factorial(n),n,w = 0)}
$$
\begin{array}{@{}l}
\displaystyle
1+w+
{{\frac{1}{2}} \  {w \sp 2}}+
{{\frac{1}{6}} \  {w \sp 3}}+
{{\frac{1}{24}} \  {w \sp 4}}+
{{\frac{1}{120}} \  {w \sp 5}}+
{{\frac{1}{720}} \  {w \sp 6}}+
{{\frac{1}{5040}} \  {w \sp 7}}+
\\
\\
\displaystyle
{{\frac{1}{40320}} \  {w \sp 8}}+
{{\frac{1}{362880}} \  {w \sp 9}}+
{{\frac{1}{3628800}} \  {w \sp {10}}}+
{O \left({{w \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,w,0)}

\subsection{Coefficients of Power Series}
\label{ugxProblemSeriesCoefficients}

You can extract any coefficient from a power series---even one that
hasn't been computed yet.  This is possible because in Axiom, infinite
series are represented by a list of the coefficients that have already
been determined, together with a function for computing the additional
coefficients.  (This is known as {\it lazy evaluation}.) When you ask
for a \index{series!lazy evaluation} coefficient that hasn't yet been
computed, Axiom computes \index{lazy evaluation} whatever additional
coefficients it needs and then stores them in the representation of
the power series.

Here's an example of how to extract the coefficients of a power series.
\index{series!extracting coefficients}

\spadcommand{x := series(x) }
$$
x 
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\spadcommand{y := exp(x) * sin(x)  }
$$
\begin{array}{@{}l}
\displaystyle
x+
{x \sp 2}+
{{\frac{1}{3}} \  {x \sp 3}} -
{{\frac{1}{30}} \  {x \sp 5}} -
{{\frac{1}{90}} \  {x \sp 6}} -
{{\frac{1}{630}} \  {x \sp 7}}+
{{\frac{1}{22680}} \  {x \sp 9}}+
\\
\\
\displaystyle
{{\frac{1}{113400}} \  {x \sp {10}}}+
{{\frac{1}{1247400}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

%Original Page 258

This coefficient is readily available.

\spadcommand{coefficient(y,6) }
$$
-{\frac{1}{90}} 
$$
\returnType{Type: Expression Integer}

But let's get the fifteenth coefficient of $y$.

\spadcommand{coefficient(y,15)  }
$$
-{\frac{1}{10216206000}} 
$$
\returnType{Type: Expression Integer}

If you look at $y$ then you see that the coefficients up to order $15$
have all been computed.

\spadcommand{y }
$$
\begin{array}{@{}l}
\displaystyle
x+
{x \sp 2}+
{{\frac{1}{3}} \  {x \sp 3}} -
{{\frac{1}{30}} \  {x \sp 5}} -
{{\frac{1}{90}} \  {x \sp 6}} -
{{\frac{1}{630}} \  {x \sp 7}}+
{{\frac{1}{22680}} \  {x \sp 9}}+
{{\frac{1}{113400}} \  {x \sp {10}}}+
\\
\\
\displaystyle
{{\frac{1}{1247400}} \  {x \sp {11}}} -
{{\frac{1}{97297200}} \  {x \sp {13}}} -
{{\frac{1}{681080400}} \  {x \sp {14}}} -
{{\frac{1}{10216206000}} \  {x \sp {15}}}+
{O \left({{x \sp {16}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\subsection{Power Series Arithmetic}
\label{ugxProblemSeriesArithmetic}

You can manipulate power series using the usual arithmetic operations
\index{series!arithmetic}
$+$, $-$, $*$, and $/$ (from UnivariatePuiseuxSeries)

The results of these operations are also power series.

\spadcommand{x := series x }
$$
x 
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\spadcommand{(3 + x) / (1 + 7*x)}
$$
\begin{array}{@{}l}
3 -
{{20} \  x}+
{{140} \  {x \sp 2}} -
{{980} \  {x \sp 3}}+
{{6860} \  {x \sp 4}} -
{{48020} \  {x \sp 5}}+
{{336140} \  {x \sp 6}} -
{{2352980} \  {x \sp 7}}+
\\
\\
\displaystyle
{{16470860} \  {x \sp 8}} -
{{115296020} \  {x \sp 9}}+
{{807072140} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

You can also compute $f(x) ** g(x)$, where $f(x)$ and $g(x)$
are two power series.

\spadcommand{base := 1 / (1 - x)  }
$$
1+x+
{x \sp 2}+
{x \sp 3}+
{x \sp 4}+
{x \sp 5}+
{x \sp 6}+
{x \sp 7}+
{x \sp 8}+
{x \sp 9}+
{x \sp {10}}+
{O \left({{x \sp {11}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\spadcommand{expon := x * base  }
$$
x+
{x \sp 2}+
{x \sp 3}+
{x \sp 4}+
{x \sp 5}+
{x \sp 6}+
{x \sp 7}+
{x \sp 8}+
{x \sp 9}+
{x \sp {10}}+
{x \sp {11}}+
{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

%Original Page 259

\spadcommand{base ** expon }
$$
\begin{array}{@{}l}
\displaystyle
1+
{x \sp 2}+
{{\frac{3}{2}} \  {x \sp 3}}+
{{\frac{7}{3}} \  {x \sp 4}}+
{{\frac{43}{12}} \  {x \sp 5}}+
{{\frac{649}{120}} \  {x \sp 6}}+
{{\frac{241}{30}} \  {x \sp 7}}+
{{\frac{3706}{315}} \  {x \sp 8}}+
\\
\\
\displaystyle
{{\frac{85763}{5040}} \  {x \sp 9}}+
{{\frac{245339}{10080}} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\subsection{Functions on Power Series}
\label{ugxProblemSeriesFunctions}

Once you have created a power series, you can apply transcendental
functions
(for example, {\bf exp}, {\bf log}, {\bf sin}, {\bf tan},
{\bf cosh}, etc.) to it.

To demonstrate this, we first create the power series
expansion of the rational function

$$\frac{\displaystyle x^2}{\displaystyle 1 - 6x + x^2}$$

about $x = 0$.

\spadcommand{x := series 'x }
$$
x 
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\spadcommand{rat := x**2 / (1 - 6*x + x**2)  }
$$
\begin{array}{@{}l}
{x \sp 2}+
{6 \  {x \sp 3}}+
{{35} \  {x \sp 4}}+
{{204} \  {x \sp 5}}+
{{1189} \  {x \sp 6}}+
{{6930} \  {x \sp 7}}+
{{40391} \  {x \sp 8}}+
{{235416} \  {x \sp 9}}+
\\
\\
\displaystyle
{{1372105} \  {x \sp {10}}}+
{{7997214} \  {x \sp {11}}}+
{{46611179} \  {x \sp {12}}}+
{O \left({{x \sp {13}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

If you want to compute the series expansion of

$$\sin\left(\frac{\displaystyle x^2}{\displaystyle 1 - 6x + x^2}\right)$$

you simply compute the sine of $rat$.

\spadcommand{sin(rat) }
$$
\begin{array}{@{}l}
\displaystyle
{x \sp 2}+
{6 \  {x \sp 3}}+
{{35} \  {x \sp 4}}+
{{204} \  {x \sp 5}}+
{{\frac{7133}{6}} \  {x \sp 6}}+
{{6927} \  {x \sp 7}}+
{{\frac{80711}{2}} \  {x \sp 8}}+
{{235068} \  {x \sp 9}}+
\\
\\
\displaystyle
{{\frac{164285281}{120}} \  {x \sp {10}}}+
{{\frac{31888513}{4}} \  {x \sp {11}}}+
{{\frac{371324777}{8}} \  {x \sp {12}}}+
{O \left({{x \sp {13}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\boxer{4.6in}{
\noindent {\bf Warning:}
the type of the coefficients of a power series may
affect the kind of computations that you can do with that series.
This can only happen when you have made a declaration to
specify a series domain with a certain type of coefficient.\\
}

If you evaluate then you have declared that $y$ is a one variable
Taylor series \index{series!Taylor} ({\tt UTS} is the abbreviation for
{\tt UnivariateTaylorSeries}) in the variable $y$ with {\tt FRAC INT}
(that is, fractions of integer) coefficients, centered about $0$.

\spadcommand{y : UTS(FRAC INT,y,0) := y }
$$
y 
$$
\returnType{Type: UnivariateTaylorSeries(Fraction Integer,y,0)}

%Original Page 260

You can now compute certain power series in $y$, {\it provided} that
these series have rational coefficients.

\spadcommand{exp(y) }
$$
\begin{array}{@{}l}
\displaystyle
1+y+
{{\frac{1}{2}} \  {y \sp 2}}+
{{\frac{1}{6}} \  {y \sp 3}}+
{{\frac{1}{24}} \  {y \sp 4}}+
{{\frac{1}{120}} \  {y \sp 5}}+
{{\frac{1}{720}} \  {y \sp 6}}+
{{\frac{1}{5040}} \  {y \sp 7}}+
{{\frac{1}{40320}} \  {y \sp 8}}+
\\
\\
\displaystyle
{{\frac{1}{362880}} \  {y \sp 9}}+
{{\frac{1}{3628800}} \  {y \sp {10}}}+
{O \left({{y \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Fraction Integer,y,0)}

You can get examples of such series by applying transcendental
functions to series in $y$ that have no constant terms.

\spadcommand{tan(y**2) }
$$
{y \sp 2}+
{{\frac{1}{3}} \  {y \sp 6}}+
{{\frac{2}{15}} \  {y \sp {10}}}+
{O \left({{y \sp {11}}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Fraction Integer,y,0)}

\spadcommand{cos(y + y**5) }
$$
1 -
{{\frac{1}{2}} \  {y \sp 2}}+
{{\frac{1}{24}} \  {y \sp 4}} -
{{\frac{721}{720}} \  {y \sp 6}}+
{{\frac{6721}{40320}} \  {y \sp 8}} -
{{\frac{1844641}{3628800}} \  {y \sp {10}}}+
{O \left({{y \sp {11}}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Fraction Integer,y,0)}

Similarly, you can compute the logarithm of a power series with rational
coefficients if the constant coefficient is $1.$

\spadcommand{log(1 + sin(y)) }
$$
\begin{array}{@{}l}
\displaystyle
y -
{{\frac{1}{2}} \  {y \sp 2}}+
{{\frac{1}{6}} \  {y \sp 3}} -
{{\frac{1}{12}} \  {y \sp 4}}+
{{\frac{1}{24}} \  {y \sp 5}} -
{{\frac{1}{45}} \  {y \sp 6}}+
{{\frac{61}{5040}} \  {y \sp 7}} -
{{\frac{17}{2520}} \  {y \sp 8}}+
{{\frac{277}{72576}} \  {y \sp 9}} -
\\
\\
\displaystyle
{{\frac{31}{14175}} \  {y \sp {10}}}+
{O \left({{y \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Fraction Integer,y,0)}

If you wanted to apply, say, the operation {\bf exp} to a power series
with a nonzero constant coefficient $a_0$, then the constant
coefficient of the result would be $e^{a_0}$, which is {\it not} a
rational number.  Therefore, evaluating $exp(2 + tan(y))$ would
generate an error message.

If you want to compute the Taylor expansion of $exp(2 + tan(y))$, you
must ensure that the coefficient domain has an operation {\bf exp}
defined for it.  An example of such a domain is {\tt Expression
Integer}, the type of formal functional expressions over the integers.

When working with coefficients of this type,

\spadcommand{z : UTS(EXPR INT,z,0) := z }
$$
z 
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,z,0)}

this presents no problems.

\spadcommand{exp(2 + tan(z)) }
$$
\begin{array}{@{}l}
\displaystyle
{e \sp 2}+
{{e \sp 2} \  z}+
{{\frac{e \sp 2}{2}} \  {z \sp 2}}+
{{\frac{e \sp 2}{2}} \  {z \sp 3}}+
{{\frac{3 \  {e \sp 2}}{8}} \  {z \sp 4}}+
{{\frac{{37} \  {e \sp 2}}{120}} \  {z \sp 5}}+
{{\frac{{59} \  {e \sp 2}}{240}} \  {z \sp 6}}+
{{\frac{{137} \  {e \sp 2}}{720}} \  {z \sp 7}}+
\\
\\
\displaystyle
{{\frac{{871} \  {e \sp 2}}{5760}} \  {z \sp 8}}+
{{\frac{{41641} \  {e \sp 2}}{362880}} \  {z \sp 9}}+
{{\frac{{325249} \  {e \sp 2}}{3628800}} \  {z \sp {10}}}+
{O \left({{z \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,z,0)}

Another way to create Taylor series whose coefficients are expressions
over the integers is to use {\bf taylor} which works similarly to
\index{series!Taylor} {\bf series}.

%Original Page 261

This is equivalent to the previous computation, except that now we
are using the variable $w$ instead of $z$.

\spadcommand{w := taylor 'w }
$$
w 
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,w,0)}

\spadcommand{exp(2 + tan(w)) }
$$
\begin{array}{@{}l}
\displaystyle
{e \sp 2}+
{{e \sp 2} \  w}+
{{\frac{e \sp 2}{2}} \  {w \sp 2}}+
{{\frac{e \sp 2}{2}} \  {w \sp 3}}+
{{\frac{3 \  {e \sp 2}}{8}} \  {w \sp 4}}+
{{\frac{{37} \  {e \sp 2}}{120}} \  {w \sp 5}}+
{{\frac{{59} \  {e \sp 2}}{240}} \  {w \sp 6}}+
{{\frac{{137} \  {e \sp 2}}{720}} \  {w \sp 7}}+
\\
\\
\displaystyle
{{\frac{{871} \  {e \sp 2}}{5760}} \  {w \sp 8}}+
{{\frac{{41641} \  {e \sp 2}}{362880}} \  {w \sp 9}}+
{{\frac{{325249} \  {e \sp 2}}{3628800}} \  {w \sp {10}}}+
{O \left({{w \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,w,0)}

\subsection{Converting to Power Series}
\label{ugxProblemSeriesConversions}

The {\tt ExpressionToUnivariatePowerSeries} package provides
operations for computing series expansions of functions.
\index{ExpressionToUnivariatePowerSeries}

Evaluate this to compute the Taylor expansion of $sin(x)$ about
\index{series!Taylor} $x = 0$.  The first argument, $sin(x)$,
specifies the function whose series expansion is to be computed and
the second argument, $x = 0$, specifies that the series is to be
expanded in power of $(x - 0)$, that is, in power of $x$.

\spadcommand{taylor(sin(x),x = 0)}
$$
x -
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{1}{120}} \  {x \sp 5}} -
{{\frac{1}{5040}} \  {x \sp 7}}+
{{\frac{1}{362880}} \  {x \sp 9}}+
{O \left({{x \sp {11}}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,x,0)}

Here is the Taylor expansion of $sin x$ about $x = \frac{\pi}{6}$:

\spadcommand{taylor(sin(x),x = \%pi/6)}
$$
\begin{array}{@{}l}
\displaystyle
{\frac{1}{2}}+
{{\frac{\sqrt {3}}{2}} \  {\left( x -{\frac{\pi}{6}} \right)}}
-{{\frac{1}{4}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 2}} -
{{\frac{\sqrt {3}}{12}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 3}}+
{{\frac{1}{48}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 4}}+
\\
\\
\displaystyle
{{\frac{\sqrt {3}}{240}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 5}} -
{{\frac{1}{1440}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 6}} -
{{\frac{\sqrt {3}}{10080}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 7}}+
{{\frac{1}{80640}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 8}}+
\\
\\
\displaystyle
{{\frac{\sqrt {3}}{725760}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp 9}} -
{{\frac{1}{7257600}} \  {{\left( x -{\frac{\pi}{6}} \right)}\sp {10}}}+
{O \left({{{\left( x -{\frac{\pi}{6}} \right)}\sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,x,pi/6)}


The function to be expanded into a series may have variables other
than \index{series!multiple variables} the series variable.

%Original Page 262

For example, we may expand $tan(x*y)$ as a Taylor series in $x$

\spadcommand{taylor(tan(x*y),x = 0)}
$$
{y \  x}+
{{\frac{y \sp 3}{3}} \  {x \sp 3}}+
{{\frac{2 \  {y \sp 5}}{15}} \  {x \sp 5}}+
{{\frac{{17} \  {y \sp 7}}{315}} \  {x \sp 7}}+
{{\frac{{62} \  {y \sp 9}}{2835}} \  {x \sp 9}}+
{O \left({{x \sp {11}}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,x,0)}

or as a Taylor series in $y$.

\spadcommand{taylor(tan(x*y),y = 0)}
$$
{x \  y}+
{{\frac{x \sp 3}{3}} \  {y \sp 3}}+
{{\frac{2 \  {x \sp 5}}{15}} \  {y \sp 5}}+
{{\frac{{17} \  {x \sp 7}}{315}} \  {y \sp 7}}+
{{\frac{{62} \  {x \sp 9}}{2835}} \  {y \sp 9}}+
{O \left({{y \sp {11}}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,y,0)}

A more interesting function is 
$$\frac{\displaystyle t e^{x t}}{\displaystyle e^t - 1}$$ 
When we expand this function as a Taylor
series in $t$ the $n$-th order coefficient is the $n$-th Bernoulli
\index{Bernoulli!polynomial} polynomial \index{polynomial!Bernoulli}
divided by $n!$.

\spadcommand{bern := taylor(t*exp(x*t)/(exp(t) - 1),t = 0) }
$$
\begin{array}{@{}l}
\displaystyle
1+
{{\frac{{2 \  x} -1}{2}} \  t}+
{{\frac{{6 \  {x \sp 2}} -{6 \  x}+1}{12}} \  {t \sp 2}}+
{{\frac{{2 \  {x \sp 3}} -{3 \  {x \sp 2}}+x}{12}} \  {t \sp 3}}+
\\
\\
\displaystyle
{{\frac{{{30} \  {x \sp 4}} -{{60} \  {x \sp 3}}+{{30} \  {x \sp 2}} -1} 
{720}} \  {t \sp 4}}+
{{\frac{{6 \  {x \sp 5}} -{{15} \  {x \sp 4}}+{{10} \  {x \sp 
3}} -x}{720}} \  {t \sp 5}}+
\\
\\
\displaystyle
{{\frac{{{42} \  {x \sp 6}} -{{126} \  {x \sp 5}}+{{105} \  {x \sp 4}} -{{21} 
\  {x \sp 2}}+1}{30240}} \  {t \sp 6}}+
{{\frac{{6 \  {x \sp 7}} -{{21} \  {x \sp 6}}+{{21} \  {x \sp 5}} -{7 \  {x 
\sp 3}}+x}{30240}} \  {t \sp 7}}+
\\
\\
\displaystyle
{{\frac{{{30} \  {x \sp 8}} -{{120} \  {x \sp 7}}+{{140} \  {x \sp 6}} -
{{70} \  {x \sp 4}}+{{20} \  {x \sp 2}} -1}{1209600}} \  {t \sp 8}}+
\\
\\
\displaystyle
{{\frac{{{10} \  {x \sp 9}} -{{45} \  {x \sp 8}}+{{60} \  {x \sp 7}} -
{{42} \  {x \sp 5}}+{{20} \  {x \sp 3}} -{3 \  x}} 
{3628800}} \  {t \sp 9}}+
\\
\\
\displaystyle
{{\frac{{{66} \  {x \sp {10}}} -{{330} \  {x \sp 9}}+{{495} \  {x \sp 8}} -
{{462} \  {x \sp 6}}+{{330} \  {x \sp 4}} -{{99} \  {x \sp 2}}+5} 
{239500800}} \  {t \sp {10}}}+
{O \left({{t \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,t,0)}

Therefore, this and the next expression produce the same result.

\spadcommand{factorial(6) * coefficient(bern,6) }
$$
\frac{{{42} \  {x \sp 6}} -
{{126} \  {x \sp 5}}+
{{105} \  {x \sp 4}} -
{{21} \  {x \sp 2}}+1}
{42} 
$$
\returnType{Type: Expression Integer}

\spadcommand{bernoulliB(6,x)}
$$
{x \sp 6} -
{3 \  {x \sp 5}}+
{{\frac{5}{2}} \  {x \sp 4}} -
{{\frac{1}{2}} \  {x \sp 2}}+
{\frac{1}{42}} 
$$
\returnType{Type: Polynomial Fraction Integer}

Technically, a series with terms of negative degree is not considered
to be a Taylor series, but, rather, a \index{series!Laurent} 
{\it Laurent series}.  \index{Laurent series} If you try to compute a
Taylor series expansion of $\frac{x}{\log x}$ at $x = 1$ via
$taylor(x/log(x),x = 1)$ you get an error message.  The reason is that
the function has a {\it pole} at $x = 1$, meaning that its series
expansion about this point has terms of negative degree.  A series
with finitely many terms of negative degree is called a Laurent
series.

%Original Page 263

You get the desired series expansion by issuing this.

\spadcommand{laurent(x/log(x),x = 1)}
$$
\begin{array}{@{}l}
\displaystyle
{{\left( x -1 \right)}\sp {\left( -1\right)}}+
{\frac{3}{2}}+
{{\frac{5}{12}} \  {\left( x -1 \right)}}
-{{\frac{1}{24}} \  {{\left( x -1 \right)}\sp 2}}+
{{\frac{11}{720}} \  {{\left( x -1 \right)}\sp 3}} -
{{\frac{11}{1440}} \  {{\left( x -1 \right)}\sp 4}}+
\\
\\
\displaystyle
{{\frac{271}{60480}} \  {{\left( x -1 \right)}\sp 5}} -
{{\frac{13}{4480}} \  {{\left( x -1 \right)}\sp 6}}+
{{\frac{7297}{3628800}} \  {{\left( x -1 \right)}\sp 7}} -
{{\frac{425}{290304}} \  {{\left( x -1 \right)}\sp 8}}+
\\
\\
\displaystyle
{{\frac{530113}{479001600}} \  {{\left( x -1 \right)}\sp 9}}+
{O \left({{{\left( x -1 \right)}\sp {10}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateLaurentSeries(Expression Integer,x,1)}

Similarly, a series with terms of fractional degree is neither a
Taylor series nor a Laurent series.  Such a series is called a
\index{series!Puiseux} {\it Puiseux series}.  \index{Puiseux series}
The expression $laurent(sqrt(sec(x)),x = 3 * \%pi/2)$ results in an
error message because the series expansion about this point has terms
of fractional degree.

However, this command produces what you want.

\spadcommand{puiseux(sqrt(sec(x)),x = 3 * \%pi/2)}
$$
{{\left( x -{\frac{3 \  \pi}{2}} \right)}\sp {\left( -{\frac{1}{2}} \right)}}+
{{\frac{1}{12}} \  {{\left( x -{\frac{3 \  \pi}{2}} \right)}\sp 
{\frac{3}{2}}}}+
{{\frac{1}{160}} \  {{\left( x -{\frac{3 \  \pi}{2}} \right)}\sp 
{\frac{7}{2}}}}+
{O \left({{{\left( x -{\frac{3 \  \pi}{2}} \right)}\sp 5}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,(3*pi)/2)}

Finally, consider the case of functions that do not have Puiseux
expansions about certain points.  An example of this is $x^x$ about $x
= 0$.  $puiseux(x**x,x=0)$ produces an error message because of the
type of singularity of the function at $x = 0$.

The general function {\bf series} can be used in this case.
Notice that the series returned is not, strictly speaking, a power series
because of the $log(x)$ in the expansion.

\spadcommand{series(x**x,x=0)}
$$
\begin{array}{@{}l}
\displaystyle
1+
{{\log \left({x} \right)}\  x}+
{{\frac{{\log \left({x} \right)}\sp 2}{2}} \  {x \sp 2}}+
{{\frac{{\log \left({x} \right)}\sp 3}{6}} \  {x \sp 3}}+
{{\frac{{\log \left({x} \right)}\sp 4}{24}} \  {x \sp 4}}+
{{\frac{{\log \left({x} \right)}\sp 5}{120}} \  {x \sp 5}}+
{{\frac{{\log \left({x} \right)}\sp 6}{720}} \  {x \sp 6}}+
\\
\\
\displaystyle
{{\frac{{\log \left({x} \right)}\sp 7}{5040}} \  {x \sp 7}}+
{{\frac{{\log \left({x} \right)}\sp 8}{40320}} \  {x \sp 8}}+
{{\frac{{\log \left({x} \right)}\sp 9}{362880}} \  {x \sp 9}}+
{{\frac{{\log \left({x} \right)}\sp {10}}{3628800}} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: GeneralUnivariatePowerSeries(Expression Integer,x,0)}

\boxer{4.6in}{
The operation {\bf series} returns the most general type of
infinite series.
The user who is not interested in distinguishing
between various types of infinite series may wish to use this operation
exclusively.\\
}

\subsection{Power Series from Formulas}
\label{ugxProblemSeriesFormula}

The {\tt GenerateUnivariatePowerSeries} package enables you to
\index{series!giving formula for coefficients} create power series
from explicit formulas for their $n$-th coefficients.  In what
follows, we construct series expansions for certain transcendental
functions by giving formulas for their coefficients.  You can also
compute such series expansions directly simply by specifying the
function and the point about which the series is to be expanded.
\index{GenerateUnivariatePowerSeries} See
\sectionref{ugxProblemSeriesConversions} for more information.

%Original Page 264

Consider the Taylor expansion of $e^x$ \index{series!Taylor}
about $x = 0$:

$$
\begin{array}{ccl}
e^x &=& \displaystyle 1 + x + \frac{x^2}{2} + \frac{x^3}{6} + \cdots \\ \\
    &=& \displaystyle\sum_{n=0}^\infty \frac{x^n}{n!}
\end{array}
$$

The $n$-th Taylor coefficient is $1/n!$.

This is how you create this series in Axiom.

\spadcommand{series(n +-> 1/factorial(n),x = 0)}
$$
\begin{array}{@{}l}
\displaystyle
1+x+
{{\frac{1}{2}} \  {x \sp 2}}+
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{1}{24}} \  {x \sp 4}}+
{{\frac{1}{120}} \  {x \sp 5}}+
{{\frac{1}{720}} \  {x \sp 6}}+
{{\frac{1}{5040}} \  {x \sp 7}}+
{{\frac{1}{40320}} \  {x \sp 8}}+
\\
\\
\displaystyle
{{\frac{1}{362880}} \  {x \sp 9}}+
{{\frac{1}{3628800}} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

The first argument specifies a formula for the $n$-th coefficient by
giving a function that maps $n$ to $1/n!$.  The second argument
specifies that the series is to be expanded in powers of $(x - 0)$,
that is, in powers of $x$.  Since we did not specify an initial
degree, the first term in the series was the term of degree 0 (the
constant term).  Note that the formula was given as an anonymous
function.  These are discussed in \sectionref{ugUserAnon}.

Consider the Taylor expansion of $log x$ about $x = 1$:

$$
\begin{array}{ccl}
\log(x) &=& \displaystyle (x - 1) - \frac{(x - 1)^2}{2} + \frac{(x - 1)^3}{3} - \cdots \\ \\
        &=& \displaystyle\sum_{n = 1}^\infty (-1)^{n-1} \frac{(x - 1)^n}{n}
\end{array}$$

If you were to evaluate the expression 
$series(n +-> (-1)**(n-1) / n, x = 1)$ 
you would get an error message because Axiom would try to
calculate a term of degree $0$ and therefore divide by $0.$

Instead, evaluate this.
The third argument, $1..$, indicates that only terms of degree
$n = 1, ...$ are to be computed.

\spadcommand{series(n +-> (-1)**(n-1)/n,x = 1,1..)}
$$
\begin{array}{@{}l}
\displaystyle
{\left( x -1 \right)}
-{{\frac{1}{2}} \  {{\left( x -1 \right)}\sp 2}}+
{{\frac{1}{3}} \  {{\left( x -1 \right)}\sp 3}} -
{{\frac{1}{4}} \  {{\left( x -1 \right)}\sp 4}}+
{{\frac{1}{5}} \  {{\left( x -1 \right)}\sp 5}} -
{{\frac{1}{6}} \  {{\left( x -1 \right)}\sp 6}}+
\\
\\
\displaystyle
{{\frac{1}{7}} \  {{\left( x -1 \right)}\sp 7}} -
{{\frac{1}{8}} \  {{\left( x -1 \right)}\sp 8}}+
{{\frac{1}{9}} \  {{\left( x -1 \right)}\sp 9}} -
{{\frac{1}{10}} \  {{\left( x -1 \right)}\sp {10}}}+
{{\frac{1}{11}} \  {{\left( x -1 \right)}\sp {11}}}+
\\
\\
\displaystyle
{O \left({{{\left( x -1 \right)}\sp {12}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,1)}

%Original Page 265

Next consider the Taylor expansion of an odd function, say, $sin(x)$:

$$\sin(x) = x - \frac{x^3}{3!} + \frac{x^5}{5!} - \cdots$$

Here every other coefficient is zero and we would like to give an
explicit formula only for the odd Taylor coefficients.

This is one way to do it.  The third argument, $1..$, specifies that
the first term to be computed is the term of degree 1.  The fourth
argument, $2$, specifies that we increment by $2$ to find the degrees
of subsequent terms, that is, the next term is of degree $1 + 2$, the
next of degree $1 + 2 + 2$, etc.

\spadcommand{series(n +-> (-1)**((n-1)/2)/factorial(n),x = 0,1..,2)}
$$
x -
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{1}{120}} \  {x \sp 5}} -
{{\frac{1}{5040}} \  {x \sp 7}}+
{{\frac{1}{362880}} \  {x \sp 9}} -
{{\frac{1}{39916800}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

The initial degree and the increment do not have to be integers.
For example, this expression produces a series expansion of
$\sin(x^{\frac{1}{3}})$.

\spadcommand{series(n +-> (-1)**((3*n-1)/2)/factorial(3*n),x = 0,1/3..,2/3)}
$$
{x \sp {\frac{1}{3}}} -
{{\frac{1}{6}} \  x}+
{{\frac{1}{120}} \  {x \sp {\frac{5}{3}}}} -
{{\frac{1}{5040}} \  {x \sp {\frac{7}{3}}}}+
{{\frac{1}{362880}} \  {x \sp 3}} -
{{\frac{1}{39916800}} \  {x \sp {\frac{11}{3}}}}+
{O \left({{x \sp 4}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

While the increment must be positive, the initial degree may be
negative.  This yields the Laurent expansion of $csc(x)$ at $x = 0$.
(bernoulli(numer(n+1)) is necessary because bernoulli takes integer
arguments.)

\spadcommand{cscx := series(n +-> (-1)**((n-1)/2) * 2 * (2**n-1) * bernoulli(numer(n+1)) / factorial(n+1), x=0, -1..,2) }
$$
{x \sp {\left( -1 \right)}}+
{{\frac{1}{6}} \  x}+
{{\frac{7}{360}} \  {x \sp 3}}+
{{\frac{31}{15120}} \  {x \sp 5}}+
{{\frac{127}{604800}} \  {x \sp 7}}+
{{\frac{73}{3421440}} \  {x \sp 9}}+
{O \left({{x \sp {10}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

Of course, the reciprocal of this power series is the Taylor expansion
of $sin(x)$.

\spadcommand{1/cscx }
$$
x -
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{1}{120}} \  {x \sp 5}} -
{{\frac{1}{5040}} \  {x \sp 7}}+
{{\frac{1}{362880}} \  {x \sp 9}} -
{{\frac{1}{39916800}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

As a final example,here is the Taylor expansion of $asin(x)$ about $x = 0$.

\spadcommand{asinx := series(n +-> binomial(n-1,(n-1)/2)/(n*2**(n-1)),x=0,1..,2) }
$$
x+
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{3}{40}} \  {x \sp 5}}+
{{\frac{5}{112}} \  {x \sp 7}}+
{{\frac{35}{1152}} \  {x \sp 9}}+
{{\frac{63}{2816}} \  {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

When we compute the $sin$ of this series, we get $x$
(in the sense that all higher terms computed so far are zero).

\spadcommand{sin(asinx) }
$$
x+{O \left({{x \sp {12}}} \right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}

\boxer{4.6in}{
Axiom isn't sufficiently ``symbolic'' in the sense we might wish. It
is an open problem to decide that ``x'' is the only surviving
term. Two attacks on the problem might be:

(1) Notice that all of the higher terms are identically zero but
Axiom can't decide that from the information it knows. Presumably
we could attack this problem by looking at the sin function as
a taylor series around x=0 and seeing the term cancellation occur.
This uses a term-difference mechanism.

(2) Notice that there is no way to decide that the stream for asinx
is actually the definition of asin(x). But we could recognize that
the stream for asin(x) has a generator term and so will a taylor
series expansion of sin(x). From these two generators it may be
possible in certain cases to decide that the application of one
generator to the other will yield only ``x''. This trick involves
finding the correct inverse for the stream functions. If we can
find an inverse for the ``remaining tail'' of the stream we could
conclude cancellation and thus turn an infinite stream into a
finite object.

In general this is the zero-equivalence problem and is undecidable.\\
}

As we discussed in \sectionref{ugxProblemSeriesConversions},
you can also use
the operations {\bf taylor}, {\bf laurent} and {\bf puiseux} instead
of {\bf series} if you know ahead of time what kind of exponents a
series has.  You can't go wrong using {\bf series}, though.

%Original Page 266

\subsection{Substituting Numerical Values in Power Series}
\label{ugxProblemSeriesSubstitute}

Use \spadfunFrom{eval}{UnivariatePowerSeriesCategory}
\index{approximation} to substitute a numerical value for a variable
in \index{series!numerical approximation} a power series.  For
example, here's a way to obtain numerical approximations of $\%e$ from
the Taylor series expansion of $exp(x)$.

First you create the desired Taylor expansion.

\spadcommand{f := taylor(exp(x)) }
$$
\begin{array}{@{}l}
\displaystyle
1+x+
{{\frac{1}{2}} \  {x \sp 2}}+
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{1}{24}} \  {x \sp 4}}+
{{\frac{1}{120}} \  {x \sp 5}}+
{{\frac{1}{720}} \  {x \sp 6}}+
{{\frac{1}{5040}} \  {x \sp 7}}+
\\
\\
\displaystyle
{{\frac{1}{40320}} \  {x \sp 8}}+
{{\frac{1}{362880}} \  {x \sp 9}}+
{{\frac{1}{3628800}} \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,x,0)}


Then you evaluate the series at the value $1.0$.
The result is a sequence of the partial sums.

\spadcommand{eval(f,1.0)}
$$
\begin{array}{@{}l}
\left[
{1.0}, 
{2.0}, 
{2.5}, 
{2.6666666666\ 666666667}, 
{2.7083333333\ 333333333},
\right.
\\
\\
\displaystyle
{2.7166666666\ 666666667},
{2.7180555555\ 555555556},
{2.7182539682\ 53968254},
\\
\\
\displaystyle
\left.
{2.7182787698\ 412698413},
{2.7182815255\ 731922399},
\ldots 
\right]
\end{array}
$$
\returnType{Type: Stream Expression Float}

\subsection{Example: Bernoulli Polynomials and Sums of Powers}
\label{ugxProblemSeriesBernoulli}

Axiom provides operations for computing definite and
\index{summation!definite} indefinite sums.
\index{summation!indefinite}

You can compute the sum of the first ten fourth powers by evaluating
this.  This creates a list whose entries are $m^4$ as $m$ ranges from
1 to 10, and then computes the sum of the entries of that list.

\spadcommand{reduce(+,[m**4 for m in 1..10])}
$$
25333 
$$
\returnType{Type: PositiveInteger}

You can also compute a formula for the sum of the first $k$ fourth
powers, where $k$ is an unspecified positive integer.

\spadcommand{sum4 := sum(m**4, m = 1..k) }
$$
\frac{{6 \  {k \sp 5}}+{{15} \  {k \sp 4}}+{{10} \  {k \sp 3}} -k}{30} 
$$
\returnType{Type: Fraction Polynomial Integer}

This formula is valid for any positive integer $k$.  For instance, if
we replace $k$ by 10, \index{summation!definite} we obtain the number
we computed earlier.

\spadcommand{eval(sum4, k = 10) }
$$
25333 
$$
\returnType{Type: Fraction Polynomial Integer}

You can compute a formula for the sum of the first $k$ $n$-th powers
in a similar fashion.  Just replace the $4$ in the definition of 
{\bf sum4} by any expression not involving $k$.  Axiom computes these
formulas using Bernoulli polynomials; \index{Bernoulli!polynomial} we
\index{polynomial!Bernoulli} use the rest of this section to describe
this method.

%Original Page 267

First consider this function of $t$ and $x$.

\spadcommand{f := t*exp(x*t) / (exp(t) - 1) }
$$
\frac{t \  {e \sp {\left( t \  x \right)}}}{{e \sp t} -1} 
$$
\returnType{Type: Expression Integer}

Since the expressions involved get quite large, we tell
Axiom to show us only terms of degree up to $5.$

\spadcommand{)set streams calculate 5 }

\index{set streams calculate}

If we look at the Taylor expansion of $f(x, t)$ about $t = 0,$
we see that the coefficients of the powers of $t$ are polynomials
in $x$.

\spadcommand{ff := taylor(f,t = 0)  }
$$
\begin{array}{@{}l}
\displaystyle
1+
{{\frac{{2 \  x} -1}{2}} \  t}+
{{\frac{{6 \  {x \sp 2}} -{6 \  x}+1}{12}} \  {t \sp 2}}+
{{\frac{{2 \  {x \sp 3}} -{3 \  {x \sp 2}}+x}{12}} \  {t \sp 3}}+
\\
\\
\displaystyle
{{\frac{{{30} \  {x \sp 4}} -{{60} \  {x \sp 3}}+{{30} \  {x \sp 2}} -1}
{720}} \  {t \sp 4}}+
{{\frac{{6 \  {x \sp 5}} -{{15} \  {x \sp 4}}+{{10} \  {x \sp 
3}} -x}{720}} \  {t \sp 5}}+
{O \left({{t \sp 6}} \right)}
\end{array}
$$

                         Type: UnivariateTaylorSeries(Expression Integer,t,0)


In fact, the $n$-th coefficient in this series is essentially the
$n$-th Bernoulli polynomial: the $n$-th coefficient of the series is
${\frac{1}{n!}} B_n(x)$, where $B_n(x)$ is the $n$-th Bernoulli
polynomial.  Thus, to obtain the $n$-th Bernoulli polynomial, we
multiply the $n$-th coefficient of the series $ff$ by $n!$.

For example, the sixth Bernoulli polynomial is this.

\spadcommand{factorial(6) * coefficient(ff,6) }
$$
\frac{{{42} \  {x \sp 6}} -{{126} \  {x \sp 5}}+{{105} \  {x \sp 4}} -
{{21} \  {x \sp 2}}+1}{42} 
$$
\returnType{Type: Expression Integer}

We derive some properties of the function $f(x,t)$.
First we compute $f(x + 1,t) - f(x,t)$.

\spadcommand{g := eval(f, x = x + 1) - f  }
$$
\frac{{t \  {e \sp {\left( {t \  x}+t \right)}}}
-{t \  {e \sp {\left( t \  x \right)}}}}
{{e \sp t} -1} 
$$
\returnType{Type: Expression Integer}

If we normalize $g$, we see that it has a particularly simple form.

\spadcommand{normalize(g) }
$$
t \  {e \sp {\left( t \  x \right)}}
$$
\returnType{Type: Expression Integer}

From this it follows that the $n$-th coefficient in the Taylor
expansion of $g(x,t)$ at $t = 0$ is $${\frac{1}{(n-1)!}}x^{n-1}$$.

%Original Page 268

If you want to check this, evaluate the next expression.

\spadcommand{taylor(g,t = 0) }
$$
t+
{x \  {t \sp 2}}+
{{\frac{x \sp 2}{2}} \  {t \sp 3}}+
{{\frac{x \sp 3}{6}} \  {t \sp 4}}+
{{\frac{x \sp 4}{24}} \  {t \sp 5}}+
{O \left({{t \sp 6}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,t,0)}

However, since 
$$g(x,t) = f(x+1,t)-f(x,t)$$
it follows that the $n$-th coefficient is 
$${\frac{1}{n!}}(B_n(x+1)-B_n(x))$$ Equating
coefficients, we see that 
$${\frac{1}{(n-1)!}}x^{n-1} = {\frac{1}{n!}}(B_n(x + 1) - B_n(x))$$ 
and, therefore, 
$$x^{n-1} = {\frac{1}{n}}(B_n(x + 1) - B_n(x))$$

Let's apply this formula repeatedly, letting $x$ vary between two
integers $a$ and $b$, with $a < b$:

$$
\begin{array}{lcl}
  a^{n-1}       & = & {\frac{1}{n}}   (B_n(a + 1) - B_n(a))       \\
  (a + 1)^{n-1} & = & {\frac{1}{n}}   (B_n(a + 2) - B_n(a + 1))   \\
  (a + 2)^{n-1} & = & {\frac{1}{n}}   (B_n(a + 3) - B_n(a + 2))   \\
  & \vdots &                                                    \\
  (b - 1)^{n-1} & = & {\frac{1}{n}}   (B_n(b) - B_n(b - 1))       \\
  b^{n-1}       & = & {\frac{1}{n}}   (B_n(b + 1) - B_n(b))
\end{array}
$$

When we add these equations we find that the sum of the left-hand
sides is 
$$\sum_{m=a}^{b} m^{n-1},$$ 
the sum of the
$$(n-1)^{\hbox{\small\rm st}}$$ 
powers from $a$ to $b$.  The sum of the right-hand sides is a 
``telescoping series.''  After cancellation, the sum is simply 
$${\frac{1}{n}}(B_n(b + 1) - B_n(a))$$

Replacing $n$ by $n + 1$, we have shown that
$$
\sum_{m = a}^{b} m^n = {\frac{1}{\displaystyle n + 1}} 
(B_{n+1}(b + 1) - B_{n+1}(a))
$$

Let's use this to obtain the formula for the sum of fourth powers.

First we obtain the Bernoulli polynomial $B_5$.

\spadcommand{B5 := factorial(5) * coefficient(ff,5)  }
$$
\frac{{6 \  {x \sp 5}} -{{15} \  {x \sp 4}}+{{10} \  {x \sp 3}} -x}{6} 
$$
\returnType{Type: Expression Integer}

To find the sum of the first $k$ 4th powers,
we multiply $1/5$ by $B_5(k+1) - B_5(1)$.

\spadcommand{1/5 * (eval(B5, x = k + 1) - eval(B5, x = 1)) }
$$
\frac{{6 \  {k \sp 5}}+{{15} \  {k \sp 4}}+{{10} \  {k \sp 3}} -k}{30} 
$$
\returnType{Type: Expression Integer}

This is the same formula that we obtained via $sum(m**4, m = 1..k)$.

\spadcommand{sum4 }
$$
\frac{{6 \  {k \sp 5}}+{{15} \  {k \sp 4}}+{{10} \  {k \sp 3}} -k}{30} 
$$
\returnType{Type: Fraction Polynomial Integer}

%Original Page 269

At this point you may want to do the same computation, but with an
exponent other than $4.$ For example, you might try to find a formula
for the sum of the first $k$ 20th powers.

\section{Solution of Differential Equations}
\label{ugProblemDEQ}

In this section we discuss Axiom's facilities for
\index{equation!differential!solving} solving \index{differential
equation} differential equations in closed-form and in series.

Axiom provides facilities for closed-form solution of
\index{equation!differential!solving in closed-form} single
differential equations of the following kinds:
\begin{itemize}
\item linear ordinary differential equations, and
\item non-linear first order ordinary differential equations
when integrating factors can be found just by integration.
\end{itemize}

For a discussion of the solution of systems of linear and polynomial
equations, see \sectionref{ugProblemLinPolEqn}.

\subsection{Closed-Form Solutions of Linear Differential Equations}
\label{ugxProblemLDEQClosed}

A {\it differential equation} is an equation involving an unknown 
{\it function} and one or more of its derivatives.  
\index{differential equation} The equation is called {\it ordinary} 
if derivatives with respect to \index{equation!differential} only 
one dependent variable appear in the equation (it is called 
{\it partial} otherwise).  The package {\tt ElementaryFunctionODESolver} 
provides the top-level operation {\bf solve} for finding closed-form 
solutions of ordinary differential equations.  
\index{ElementaryFunctionODESolver}

To solve a differential equation, you must first create an operator
for \index{operator} the unknown function.

We let $y$ be the unknown function in terms of $x$.

\spadcommand{y := operator 'y }
$$
y 
$$
\returnType{Type: BasicOperator}

You then type the equation using {\tt D} to create the
derivatives of the unknown function $y(x)$ where $x$ is any
symbol you choose (the so-called {\it dependent variable}).

This is how you enter
the equation $y'' + y' + y = 0$.

\spadcommand{deq := D(y x, x, 2) + D(y x, x) + y x = 0}
$$
{{{y \sb {{\ }} \sp {,,}} \left({x} \right)}+
{{y \sb {{\ }} \sp {,}} \left({x} \right)}+
{y \left({x} \right)}}=0
$$
\returnType{Type: Equation Expression Integer}

The simplest way to invoke the {\bf solve} command is with three
arguments.
\begin{itemize}
\item the differential equation,
\item the operator representing the unknown function,
\item the dependent variable.
\end{itemize}

%Original Page 270

So, to solve the above equation, we enter this.

\spadcommand{solve(deq, y, x) }
$$
\left[
{particular=0},  {basis={\left[ 
{{\cos \left({{\frac{x \  {\sqrt {3}}}{2}}} \right)}
\  {e \sp {\left( -{\frac{x}{2}} \right)}}},
{{e \sp {\left( -{\frac{x}{2}} \right)}}
\  {\sin \left({{\frac{x \  {\sqrt {3}}}{2}}} \right)}}\right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: 
List Expression Integer),...)}

Since linear ordinary differential equations have infinitely many
solutions, {\bf solve} returns a {\it particular solution} $f_p$ and a
basis $f_1,\dots,f_n$ for the solutions of the corresponding
homogenuous equation.  Any expression of the form 
$$f_p + c_1 f_1 + \dots c_n f_n$$ 
where the $c_i$ do not involve the dependent variable
is also a solution.  This is similar to what you get when you solve
systems of linear algebraic equations.

A way to select a unique solution is to specify {\it initial
conditions}: choose a value $a$ for the dependent variable and specify
the values of the unknown function and its derivatives at $a$.  If the
number of initial conditions is equal to the order of the equation,
then the solution is unique (if it exists in closed form!) and {\bf
solve} tries to find it.  To specify initial conditions to {\bf
solve}, use an {\tt Equation} of the form $x = a$ for the third
parameter instead of the dependent variable, and add a fourth
parameter consisting of the list of values $y(a), y'(a), ...$.

To find the solution of $y'' + y = 0$ satisfying $y(0) = y'(0) = 1$,
do this.

\spadcommand{deq := D(y x, x, 2) + y x }
$$
{{y \sb {{\ }} \sp {,,}} \left({x} \right)}+{y\left({x} \right)}
$$
\returnType{Type: Expression Integer}

You can omit the $= 0$ when you enter the equation to be solved.

\spadcommand{solve(deq, y, x = 0, [1, 1]) }
$$
{\sin \left({x} \right)}+{\cos\left({x} \right)}
$$
\returnType{Type: Union(Expression Integer,...)}

Axiom is not limited to linear differential equations with constant
coefficients.  It can also find solutions when the coefficients are
rational or algebraic functions of the dependent variable.
Furthermore, Axiom is not limited by the order of the equation.

Axiom can solve the following third order equations with
polynomial coefficients.

\spadcommand{deq := x**3 * D(y x, x, 3) + x**2 * D(y x, x, 2) - 2 * x * D(y x, x) + 2 * y x = 2 * x**4 }
$$
{{{x \sp 3} \  {{y \sb {{\ }} \sp {,,,}} \left({x} \right)}}+
{{x\sp 2} \  {{y \sb {{\ }} \sp {,,}} \left({x} \right)}}-
{2 \  x \  {{y \sb {{\ }} \sp {,}} \left({x} \right)}}+
{2\  {y \left({x} \right)}}}=
{2\  {x \sp 4}} 
$$
\returnType{Type: Equation Expression Integer}

%Original Page 271

\spadcommand{solve(deq, y, x) }
$$
\begin{array}{@{}l}
\displaystyle
\left[
{particular={\frac{{x \sp 5} -{{10} \  {x \sp 3}}+{{20} \  {x \sp 2}}+4} 
{{15} \  x}}}, 
\right.
\\
\\
\displaystyle
\left.
{basis={\left[ 
{\frac{{2 \  {x \sp 3}} -{3 \  {x \sp 2}}+1}{x}},  
{\frac{{x \sp 3} -1}{x}},  
{\frac{{x \sp 3} -{3 \  {x \sp 2}} -1}{x}} 
\right]}}
\right]
\end{array}
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: 
List Expression Integer),...)}

Here we are solving a homogeneous equation.

\spadcommand{deq := (x**9+x**3) * D(y x, x, 3) + 18 * x**8 * D(y x, x, 2) - 90 * x * D(y x, x) - 30 * (11 * x**6 - 3) * y x }
$$
{{\left( {x \sp 9}+{x \sp 3} \right)}\  {{y \sb {{\ }} \sp {,,,}} 
\left({x} \right)}}+
{{18}\  {x \sp 8} \  {{y \sb {{\ }} \sp {,,}} \left({x} \right)}}-
{{90} \  x \  {{y \sb {{\ }} \sp {,}} \left({x} \right)}}+
{{\left(-{{330} \  {x \sp 6}}+{90} \right)}\  {y \left({x} \right)}}
$$
\returnType{Type: Expression Integer}

\spadcommand{solve(deq, y, x) }
$$
\left[
{particular=0}, 
{basis={\left[ 
{\frac{x}{{x \sp 6}+1}}, 
{\frac{x \  {e \sp {\left( -{{\sqrt {{91}}} \  
{\log \left({x} \right)}}\right)}}}{{x \sp 6}+1}}, 
{\frac{x \  {e \sp {\left( {\sqrt {{91}}} \  {\log \left({x} \right)}\right)}}}
{{x \sp 6}+1}} 
\right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: 
List Expression Integer),...)}

On the other hand, and in contrast with the operation {\bf integrate},
it can happen that Axiom finds no solution and that some closed-form
solution still exists.  While it is mathematically complicated to
describe exactly when the solutions are guaranteed to be found, the
following statements are correct and form good guidelines for linear
ordinary differential equations:
\begin{itemize}
\item If the coefficients are constants, Axiom finds a complete basis
of solutions (i,e. all solutions).
\item If the coefficients are rational functions in the dependent variable,
Axiom at least finds all solutions that do not involve algebraic
functions.
\end{itemize}

Note that this last statement does not mean that Axiom does not find
the solutions that are algebraic functions.  It means that it is not
guaranteed that the algebraic function solutions will be found.

This is an example where all the algebraic solutions are found.

\spadcommand{deq := (x**2 + 1) * D(y x, x, 2) + 3 * x * D(y x, x) + y x = 0 }
$$
{{{\left( {x \sp 2}+1 \right)}\  {{y \sb {{\ }} \sp {,,}} \left({x} \right)}}+
{3\  x \  {{y \sb {{\ }} \sp {,}} \left({x} \right)}}+
{y\left({x} \right)}}=0
$$
\returnType{Type: Equation Expression Integer}

%Original Page 272

\spadcommand{solve(deq, y, x) }
$$
\left[
{particular=0}, 
{basis={\left[ {\frac{1}{\sqrt {{{x \sp 2}+1}}}}, 
{\frac{\log \left({{{\sqrt {{{x \sp 2}+1}}} -x}} \right)}
{\sqrt {{{x \sp 2}+1}}}} \right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: 
List Expression Integer),...)}

\subsection{Closed-Form Solutions of Non-Linear Differential Equations}
\label{ugxProblemNLDEQClosed}

This is an example that shows how to solve a non-linear first order
ordinary differential equation manually when an integrating factor can
be found just by integration.  At the end, we show you how to solve it
directly.

Let's solve the differential equation $y' = y / (x + y log y)$.

Using the notation $m(x, y) + n(x, y) y' = 0$, we have $m = -y$ and 
$n = x + y log y$.

\spadcommand{m := -y }
$$
-y 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{n := x + y * log y }
$$
{y \  {\log \left({y} \right)}}+x
$$
\returnType{Type: Expression Integer}

We first check for exactness, that is, does $dm/dy = dn/dx$?

\spadcommand{D(m, y) - D(n, x) }
$$
-2 
$$
\returnType{Type: Expression Integer}

This is not zero, so the equation is not exact.  Therefore we must
look for an integrating factor: a function $mu(x,y)$ such that 
$d(mu m)/dy = d(mu n)/dx$.  Normally, we first search for $mu(x,y)$
depending only on $x$ or only on $y$.

Let's search for such a $mu(x)$ first.

\spadcommand{mu := operator 'mu }
$$
mu 
$$
\returnType{Type: BasicOperator}

\spadcommand{a := D(mu(x) * m, y) - D(mu(x) * n, x) }
$$
{{\left( -{y \  {\log \left({y} \right)}}-x \right)}
\  {{mu \sb {{\ }} \sp {,}} \left({x} \right)}}-
{2 \  {mu \left({x} \right)}}
$$
\returnType{Type: Expression Integer}

%Original Page 273

If the above is zero for a function $mu$ that does {\it not} depend on
$y$, then $mu(x)$ is an integrating factor.

\spadcommand{solve(a = 0, mu, x) }
$$
\left[
{particular=0}, 
{basis={\left[ 
{\frac{1} 
{{{y \sp 2} \  {{\log \left({y} \right)}\sp 2}}+
{2 \  x \  y \  {\log \left({y} \right)}}+
{x\sp 2}}} \right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: 
List Expression Integer),...)}

The solution depends on $y$, so there is no integrating factor that
depends on $x$ only.

Let's look for one that depends on $y$ only.

\spadcommand{b := D(mu(y) * m, y) - D(mu(y) * n, x) }
$$
-{y \  {{mu \sb {{\ }} \sp {,}} \left({y} \right)}}-
{2 \  {mu \left({y} \right)}}
$$
\returnType{Type: Expression Integer}

\spadcommand{sb := solve(b = 0, mu, y) }
$$
\left[
{particular=0}, 
{basis={\left[ {\frac{1}{y \sp 2}} \right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: List Expression Integer),...)}

\noindent
We've found one!

The above $mu(y)$ is an integrating factor.  We must multiply our
initial equation (that is, $m$ and $n$) by the integrating factor.

\spadcommand{intFactor := sb.basis.1 }
$$
\frac{1}{y \sp 2} 
$$
\returnType{Type: Expression Integer}

\spadcommand{m := intFactor * m }
$$
-{\frac{1}{y}} 
$$
\returnType{Type: Expression Integer}

\spadcommand{n := intFactor * n }
$$
\frac{{y \  {\log \left({y} \right)}}+x}{y \sp 2} 
$$
\returnType{Type: Expression Integer}

Let's check for exactness.

\spadcommand{D(m, y) - D(n, x) }
$$
0 
$$
\returnType{Type: Expression Integer}

We must solve the exact equation, that is, find a function $s(x,y)$
such that $ds/dx = m$ and $ds/dy = n$.

%Original Page 274

We start by writing $s(x, y) = h(y) + integrate(m, x)$ where $h(y)$ is
an unknown function of $y$.  This guarantees that $ds/dx = m$.

\spadcommand{h := operator 'h }
$$
h 
$$
\returnType{Type: BasicOperator}

\spadcommand{sol := h y + integrate(m, x) }
$$
\frac{{y \  {h \left({y} \right)}}-x}{y} 
$$
\returnType{Type: Expression Integer}

All we want is to find $h(y)$ such that $ds/dy = n$.

\spadcommand{dsol := D(sol, y) }
$$
\frac{{{y \sp 2} \  {{h \sb {{\ }} \sp {,}} 
\left({y} \right)}}+x}{y \sp 2} 
$$
\returnType{Type: Expression Integer}

\spadcommand{nsol := solve(dsol = n, h, y) }
$$
\left[
{particular={\frac{{\log \left({y} \right)}\sp 2}{2}}}, 
{basis={\left[ 1 \right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,basis: 
List Expression Integer),...)}

The above particular solution is the $h(y)$ we want, so we just replace
$h(y)$ by it in the implicit solution.

\spadcommand{eval(sol, h y = nsol.particular) }
$$
\frac{{y \  {{\log \left({y} \right)}\sp 2}} -{2 \  x}}{2 \  y} 
$$
\returnType{Type: Expression Integer}

A first integral of the initial equation is obtained by setting this
result equal to an arbitrary constant.

Now that we've seen how to solve the equation ``by hand,'' we show you
how to do it with the {\bf solve} operation.

First define $y$ to be an operator.

\spadcommand{y := operator 'y }
$$
y 
$$
\returnType{Type: BasicOperator}

Next we create the differential equation.

\spadcommand{deq := D(y x, x) = y(x) / (x + y(x) * log y x) }
$$
{{y \sb {{\ }} \sp {,}} \left({x} \right)}=
{\frac{y\left({x} \right)} 
{{{y \left({x} \right)}\  {\log \left({{y \left({x} \right)}}\right)}}+x}}
$$
\returnType{Type: Equation Expression Integer}

Finally, we solve it.

\spadcommand{solve(deq, y, x) }
$$
\frac{{{y \left({x} \right)}\  
{{\log \left({{y \left({x} \right)}}\right)}\sp 2}}-
{2 \  x}}{2 \  {y \left({x} \right)}}
$$
\returnType{Type: Union(Expression Integer,...)}

%Original Page 275

\subsection{Power Series Solutions of Differential Equations}
\label{ugxProblemDEQSeries}

The command to solve differential equations in power
\index{equation!differential!solving in power series} series
\index{power series} around \index{series!power} a particular initial
point with specific initial conditions is called {\bf seriesSolve}.
It can take a variety of parameters, so we illustrate its use with
some examples.

Since the coefficients of some solutions are quite large, we reset the
default to compute only seven terms.

\spadcommand{)set streams calculate 7 }

You can solve a single nonlinear equation of any order. For example,
we solve 
$$y''' = sin(y'') * exp(y) + cos(x)$$ subject to 
$$y(0) = 1, y'(0) = 0, y''(0) = 0$$

We first tell Axiom that the symbol $'y$ denotes a new operator.

\spadcommand{y := operator 'y }
$$
y 
$$
\returnType{Type: BasicOperator}

Enter the differential equation using $y$ like any system function.

\spadcommand{eq := D(y(x), x, 3) - sin(D(y(x), x, 2))*exp(y(x)) = cos(x)}
$$
{{{y \sb {{\ }} \sp {,,,}} \left({x} \right)}-
{{e \sp {y \left({x} \right)}}\  
{\sin \left({{{y \sb {{\ }} \sp {,,}} \left({x} \right)}}\right)}}}=
{\cos\left({x} \right)}
$$
\returnType{Type: Equation Expression Integer}

Solve it around $x = 0$ with the initial conditions
$y(0) = 1, y'(0) = y''(0) = 0$.

\spadcommand{seriesSolve(eq, y, x = 0, [1, 0, 0])}
$$
1+
{{\frac{1}{6}} \  {x \sp 3}}+
{{\frac{e}{24}} \  {x \sp 4}}+
{{\frac{{e \sp 2} -1}{120}} \  {x \sp 5}}+
{{\frac{{e \sp 3} -{2 \  e}}{720}} \  {x \sp 6}}+
{{\frac{{e \sp 4} -{8 \  {e \sp 2}}+{4 \  e}+1}{5040}} \  {x \sp 7}}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateTaylorSeries(Expression Integer,x,0)}

You can also solve a system of nonlinear first order equations.  For
example, we solve a system that has $tan(t)$ and $sec(t)$ as
solutions.

We tell Axiom that $x$ is also an operator.

\spadcommand{x := operator 'x}
$$
x 
$$
\returnType{Type: BasicOperator}

Enter the two equations forming our system.

\spadcommand{eq1 := D(x(t), t) = 1 + x(t)**2}
$$
{{x \sb {{\ }} \sp {,}} \left({t} \right)}=
{{{x\left({t} \right)}\sp 2}+1} 
$$
\returnType{Type: Equation Expression Integer}

\spadcommand{eq2 := D(y(t), t) = x(t) * y(t)}
$$
{{y \sb {{\ }} \sp {,}} \left({t} \right)}=
{{x\left({t} \right)}\  {y \left({t} \right)}}
$$
\returnType{Type: Equation Expression Integer}

%Original Page 276

Solve the system around $t = 0$ with the initial conditions $x(0) = 0$
and $y(0) = 1$.  Notice that since we give the unknowns in the order
$[x, y]$, the answer is a list of two series in the order 
$$[{\rm series\ for\ } x(t), {\rm \ series\ for\ }y(t)]$$

\spadcommand{seriesSolve([eq2, eq1], [x, y], t = 0, [y(0) = 1, x(0) = 0])}
\begin{verbatim}
   Compiling function %BZ with type List UnivariateTaylorSeries(
      Expression Integer,t,0) -> UnivariateTaylorSeries(Expression 
      Integer,t,0) 
   Compiling function %CA with type List UnivariateTaylorSeries(
      Expression Integer,t,0) -> UnivariateTaylorSeries(Expression 
      Integer,t,0) 
\end{verbatim}
$$
\left[
{t+
{{\frac{1}{3}} \  {t \sp 3}}+
{{\frac{2}{15}} \  {t \sp 5}}+
{{\frac{17}{315}} \  {t \sp 7}}+
{O \left({{t \sp 8}} \right)}},
{1+{{\frac{1}{2}} \  {t \sp 2}}+
{{\frac{5}{24}} \  {t \sp 4}}+
{{\frac{61}{720}} \  {t \sp 6}}+
{O \left({{t \sp 8}} \right)}}
\right]
$$
\returnType{Type: List UnivariateTaylorSeries(Expression Integer,t,0)}

\noindent
The order in which we give the equations and the initial conditions
has no effect on the order of the solution.

\section{Finite Fields}
\label{ugProblemFinite}

A {\it finite field} (also called a {\it Galois field}) is a finite
algebraic structure where one can add, multiply and divide under the
same laws (for example, commutativity, associativity or
distributivity) as apply to the rational, real or complex numbers.
Unlike those three fields, for any finite field there exists a
positive prime integer $p$, called the {\bf characteristic}, such that
$p\ x = 0$ for any element $x$ in the finite field.  In fact, the
number of elements in a finite field is a power of the characteristic
and for each prime $p$ and positive integer $n$ there exists exactly
one finite field with $p^n$ elements, up to isomorphism.\footnote{For
more information about the algebraic structure and properties of
finite fields, see, for example, S.  Lang, {\it Algebra}, Second
Edition, New York: Addison-Wesley Publishing Company, Inc., 1984, ISBN
0 201 05487 6; or R.  Lidl, H.  Niederreiter, {\it Finite Fields},
Encyclopedia of Mathematics and Its Applications, Vol.  20, Cambridge:
Cambridge Univ.  Press, 1983, ISBN 0 521 30240 4.}

When $n = 1,$ the field has $p$ elements and is called a {\it prime
field}, discussed in the next section.  There are several ways of
implementing extensions of finite fields, and Axiom provides quite a
bit of freedom to allow you to choose the one that is best for your
application.  Moreover, we provide operations for converting among the
different representations of extensions and different extensions of a
single field.  Finally, note that you usually need to package-call
operations from finite fields if the operations do not take as an
argument an object of the field.  See 
\sectionref{ugTypesPkgCall} for more information on package-calling.

\subsection{Modular Arithmetic and Prime Fields}
\label{ugxProblemFinitePrime}
\index{finite field}
\index{Galois!field}
\index{field!finite!prime}
\index{field!prime}
\index{field!Galois}
\index{prime field}
\index{modular arithmetic}
\index{arithmetic!modular}

Let $n$ be a positive integer.  It is well known that you can get the
same result if you perform addition, subtraction or multiplication of
integers and then take the remainder on dividing by $n$ as if you had
first done such remaindering on the operands, performed the arithmetic
and then (if necessary) done remaindering again.  This allows us to
speak of arithmetic {\it modulo} $n$ or, more simply {\it mod} $n$.

%Original Page 277

In Axiom, you use {\tt IntegerMod} to do such arithmetic.

\spadcommand{(a,b) : IntegerMod 12 }
\returnType{Type: Void}

\spadcommand{(a, b) := (16, 7) }
$$
7 
$$
\returnType{Type: IntegerMod 12}

\spadcommand{[a - b, a * b] }
$$
\left[
9, 4 
\right]
$$
\returnType{Type: List IntegerMod 12}

If $n$ is not prime, there is only a limited notion of reciprocals and
division.

\spadcommand{a / b }
\begin{verbatim}
   There are 12 exposed and 13 unexposed library operations named / 
      having 2 argument(s) but none was determined to be applicable. 
      Use HyperDoc Browse, or issue
                                )display op /
      to learn more about the available operations. Perhaps 
      package-calling the operation or using coercions on the arguments
      will allow you to apply the operation.
 
   Cannot find a definition or applicable library operation named / 
      with argument type(s) 
                                IntegerMod 12
                                IntegerMod 12
      
      Perhaps you should use "@" to indicate the required return type, 
      or "$" to specify which version of the function you need.
\end{verbatim}

\spadcommand{recip a }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

Here $7$ and $12$ are relatively prime, so $7$ has a multiplicative
inverse modulo $12$.

\spadcommand{recip b }
$$
7 
$$
\returnType{Type: Union(IntegerMod 12,...)}

If we take $n$ to be a prime number $p$, then taking inverses and,
therefore, division are generally defined.

Use {\tt PrimeField} instead of {\tt IntegerMod} for $n$ prime.

\spadcommand{c : PrimeField 11 := 8 }
$$
8 
$$
\returnType{Type: PrimeField 11}

\spadcommand{inv c }
$$
7 
$$
\returnType{Type: PrimeField 11}

You can also use $1/c$ and $c**(-1)$ for the inverse of $c$.

\spadcommand{9/c }
$$
8 
$$
\returnType{Type: PrimeField 11}

%Original Page 278

{\tt PrimeField} (abbreviation {\tt PF}) checks if its argument is
prime when you try to use an operation from it.  If you know the
argument is prime (particularly if it is large), {\tt InnerPrimeField}
(abbreviation {\tt IPF}) assumes the argument has already been
verified to be prime.  If you do use a number that is not prime, you
will eventually get an error message, most likely a division by zero
message.  For computer science applications, the most important finite
fields are {\tt PrimeField 2} and its extensions.

In the following examples, we work with the finite field with 
$p = 101$ elements.

\spadcommand{GF101 := PF 101  }
$$
\mbox{\rm PrimeField 101} 
$$
\returnType{Type: Domain}

Like many domains in Axiom, finite fields provide an operation for
returning a random element of the domain.

\spadcommand{x := random()\$GF101 }
$$
8 
$$
\returnType{Type: PrimeField 101}

\spadcommand{y : GF101 := 37 }
$$
37 
$$
\returnType{Type: PrimeField 101}

\spadcommand{z := x/y }
$$
63 
$$
\returnType{Type: PrimeField 101}

\spadcommand{z * y - x }
$$
0 
$$
\returnType{Type: PrimeField 101}

The element $2$ is a {\it primitive element} of this field,
\index{primitive element}
\index{element!primitive}

\spadcommand{pe := primitiveElement()\$GF101 }
$$
2 
$$
\returnType{Type: PrimeField 101}

in the sense that its powers enumerate all nonzero elements.

\spadcommand{[pe**i for i in 0..99] }
$$
\begin{array}{@{}l}
\left[
1, 2, 4, 8, {16}, {32}, {64}, {27}, {54}, 7, {14}, {28}, {56}, 
{11}, {22}, {44}, {88}, {75}, {49}, {98}, 
\right.
\\
\displaystyle
{95}, {89}, {77}, {53}, 5, {10}, {20}, {40}, {80}, {59}, {17}, 
{34}, {68}, {35}, {70}, {39}, {78}, {55}, 9, 
\\
\displaystyle
{18}, {36}, {72}, {43}, {86}, {71}, {41}, {82}, {63}, {25}, 
{50}, {100}, {99}, {97}, {93}, {85}, {69}, {37}, 
\\
\displaystyle
{74}, {47}, {94}, {87}, {73}, {45}, {90}, {79}, {57}, {13}, 
{26}, {52}, 3, 6, {12}, {24}, {48}, {96}, {91}, 
\\
\displaystyle
{81}, {61}, {21}, {42}, {84}, {67}, {33}, {66}, {31}, {62}, 
{23}, {46}, {92}, {83}, {65}, {29}, {58}, {15}, {30}, 
\\
\displaystyle
\left.
{60}, {19}, {38}, {76}, {51} 
\right]
\end{array}
$$
\returnType{Type: List PrimeField 101}

%Original Page 279

If every nonzero element is a power of a primitive element, how do you
determine what the exponent is?  Use \index{discrete logarithm} 
{\bf discreteLog}.  \index{logarithm!discrete}

\spadcommand{ex := discreteLog(y) }
$$
56 
$$
\returnType{Type: PositiveInteger}

\spadcommand{pe ** ex }
$$
37 
$$
\returnType{Type: PrimeField 101}

The {\bf order} of a nonzero element $x$ is the smallest positive
integer $t$ such $x^t = 1$.

\spadcommand{order y }
$$
25 
$$
\returnType{Type: PositiveInteger}

The order of a primitive element is the defining $p-1$.

\spadcommand{order pe }
$$
100 
$$
\returnType{Type: PositiveInteger}

\subsection{Extensions of Finite Fields}
\label{ugxProblemFiniteExtensionFinite}
\index{finite field}
\index{field!finite!extension of}

When you want to work with an extension of a finite field in Axiom,
you have three choices to make:
\begin{enumerate}
\item Do you want to generate an extension of the prime field
(for example, {\tt PrimeField 2}) or an extension of a given field?
\item Do you want to use a representation that is particularly
efficient for multiplication, exponentiation and addition but uses a
lot of computer memory (a representation that models the cyclic group
structure of the multiplicative group of the field extension and uses
a Zech logarithm table), one that \index{Zech logarithm} uses a normal
basis for the vector space structure of the field extension, or one
that performs arithmetic modulo an irreducible polynomial?  The cyclic
group representation is only usable up to ``medium'' (relative to your
machine's performance) sized fields.  If the field is large and the
normal basis is relatively simple, the normal basis representation is
more efficient for exponentiation than the irreducible polynomial
representation.
\item Do you want to provide a polynomial explicitly, a root of which
``generates'' the extension in one of the three senses in (2), or do
you wish to have the polynomial generated for you?
\end{enumerate}

This illustrates one of the most important features of Axiom: you can
choose exactly the right data-type and representation to suit your
application best.

We first tell you what domain constructors to use for each case above,
and then give some examples.

%Original Page 280

\hangafter=1\hangindent=2pc
Constructors that automatically generate extensions of the prime field:
\newline
{\tt FiniteField} \newline
{\tt FiniteFieldCyclicGroup} \newline
{\tt FiniteFieldNormalBasis}

\hangafter=1\hangindent=2pc
Constructors that generate extensions of an arbitrary field:
\newline
{\tt FiniteFieldExtension} \newline
{\tt FiniteFieldExtensionByPolynomial} \newline
{\tt FiniteFieldCyclicGroupExtension} \newline
{\tt FiniteFieldCyclicGroupExtensionByPolynomial} \newline
{\tt FiniteFieldNormalBasisExtension} \newline
{\tt FiniteFieldNormalBasisExtensionByPolynomial}

\hangafter=1\hangindent=2pc
Constructors that use a cyclic group representation:
\newline
{\tt FiniteFieldCyclicGroup} \newline
{\tt FiniteFieldCyclicGroupExtension} \newline
{\tt FiniteFieldCyclicGroupExtensionByPolynomial}

\hangafter=1\hangindent=2pc
Constructors that use a normal basis representation:
\newline
{\tt FiniteFieldNormalBasis} \newline
{\tt FiniteFieldNormalBasisExtension} \newline
{\tt FiniteFieldNormalBasisExtensionByPolynomial}

\hangafter=1\hangindent=2pc
Constructors that use an irreducible modulus polynomial representation:
\newline
{\tt FiniteField} \newline
{\tt FiniteFieldExtension} \newline
{\tt FiniteFieldExtensionByPolynomial}

\hangafter=1\hangindent=2pc
Constructors that generate a polynomial for you:
\newline
{\tt FiniteField} \newline
{\tt FiniteFieldExtension} \newline
{\tt FiniteFieldCyclicGroup} \newline
{\tt FiniteFieldCyclicGroupExtension} \newline
{\tt FiniteFieldNormalBasis} \newline
{\tt FiniteFieldNormalBasisExtension}

\hangafter=1\hangindent=2pc
Constructors for which you provide a polynomial:
\newline
{\tt FiniteFieldExtensionByPolynomial} \newline
{\tt FiniteFieldCyclicGroupExtensionByPolynomial} \newline
{\tt FiniteFieldNormalBasisExtensionByPolynomial}

These constructors are discussed in the following sections where we
collect together descriptions of extension fields that have the same
underlying representation.\footnote{For more information on the
implementation aspects of finite fields, see J. Grabmeier,
A. Scheerhorn, {\it Finite Fields in Axiom,} Technical Report, IBM
Heidelberg Scientific Center, 1992.}

%Original Page 281

If you don't really care about all this detail, just use {\tt
FiniteField}.  As your knowledge of your application and its Axiom
implementation grows, you can come back and choose an alternative
constructor that may improve the efficiency of your code.  Note that
the exported operations are almost the same for all constructors of
finite field extensions and include the operations exported by {\tt
PrimeField}.

\subsection{Irreducible Modulus Polynomial Representations}
\label{ugxProblemFiniteModulus}

All finite field extension constructors discussed in this
\index{finite field} section \index{field!finite!extension of} use a
representation that performs arithmetic with univariate (one-variable)
polynomials modulo an irreducible polynomial.  This polynomial may be
given explicitly by you or automatically generated.  The ground field
may be the prime field or one you specify.  See
\sectionref{ugxProblemFiniteExtensionFinite} 
for general information about finite field extensions.

For {\tt FiniteField} (abbreviation {\tt FF}) you provide a prime
number $p$ and an extension degree $n$.  This degree can be 1.

Axiom uses the prime field {\tt PrimeField(p)}, here {\tt PrimeField 2}, 
and it chooses an irreducible polynomial of degree $n$, here 12,
over the ground field.

\spadcommand{GF4096 := FF(2,12); }
\returnType{Type: Domain}

The objects in the generated field extension are polynomials of degree
at most $n-1$ with coefficients in the prime field.  The polynomial
indeterminate is automatically chosen by Axiom and is typically
something like $\%A$ or $\%D$.  These (strange) variables are 
{\it only} for output display; there are several ways to construct 
elements of this field.

The operation {\bf index} enumerates the elements of the field
extension and accepts as argument the integers from 1 to $p ^ n$.

The expression $index(p)$ always gives the indeterminate.

\spadcommand{a := index(2)\$GF4096 }
$$
\%A 
$$
\returnType{Type: FiniteField(2,12)}

You can build polynomials in $a$ and calculate in $GF4096$.

\spadcommand{b := a**12 - a**5 + a }
$$
{ \%A \sp 5}+{ \%A \sp 3}+ \%A+1 
$$
\returnType{Type: FiniteField(2,12)}

\spadcommand{b ** 1000 }
$$
{ \%A \sp {10}}+
{ \%A \sp 9}+
{ \%A \sp 7}+
{ \%A \sp 5}+
{ \%A \sp 4}+
{  \%A \sp 3}+ 
\%A 
$$
\returnType{Type: FiniteField(2,12)}

%Original Page 282

\spadcommand{c := a/b }
$$
{ \%A \sp {11}}+
{ \%A \sp 8}+
{ \%A \sp 7}+
{ \%A \sp 5}+
{ \%A \sp 4}+
{  \%A \sp 3}+
{ \%A \sp 2} 
$$
\returnType{Type: FiniteField(2,12)}

Among the available operations are {\bf norm} and {\bf trace}.

\spadcommand{norm c }
$$
1 
$$
\returnType{Type: PrimeField 2}

\spadcommand{trace c }
$$
0 
$$
\returnType{Type: PrimeField 2}

Since any nonzero element is a power of a primitive element, how do we
discover what the exponent is?

The operation {\bf discreteLog} calculates \index{discrete logarithm}
the exponent and, \index{logarithm!discrete} if it is called with only
one argument, always refers to the primitive element returned by {\bf
primitiveElement}.

\spadcommand{dL := discreteLog a }
$$
1729 
$$
\returnType{Type: PositiveInteger}

\spadcommand{g ** dL }
$$
g \sp {1729} 
$$
\returnType{Type: Polynomial Integer}

{\tt FiniteFieldExtension} (abbreviation {\tt FFX}) is similar to \\
{\tt FiniteField} except that the ground-field for \\
{\tt FiniteFieldExtension} is arbitrary and chosen by you.

In case you select the prime field as ground field, there is
essentially no difference between the constructed two finite field
extensions.

\spadcommand{GF16 := FF(2,4); }
\returnType{Type: Domain}

\spadcommand{GF4096 := FFX(GF16,3); }
\returnType{Type: Domain}

\spadcommand{r := (random()\$GF4096) ** 20 }
$$
{{\left( { \%B \sp 2}+1 \right)}\  { \%C \sp 2}}+
{{\left( { \%B \sp 3}+{ \%B \sp 2}+1 \right)}\  \%C}+
{ \%B \sp 3}+
{ \%B \sp 2}+ 
\%B+1 
$$
\returnType{Type: FiniteFieldExtension(FiniteField(2,4),3)}

\spadcommand{norm(r) }
$$
{ \%B \sp 2}+ \%B 
$$
\returnType{Type: FiniteField(2,4)}

{\tt FiniteFieldExtensionByPolynomial} (abbreviation {\tt FFP})
is similar to {\tt FiniteField} and {\tt FiniteFieldExtension}
but is more general.

%Original Page 283

\spadcommand{GF4 := FF(2,2); }
\returnType{Type: Domain}

\spadcommand{f := nextIrreduciblePoly(random(6)\$FFPOLY(GF4))\$FFPOLY(GF4) }
$$
{? \sp 6}+
{{\left( \%D+1 \right)}\  {? \sp 5}}+
{{\left( \%D+1 \right)}\  {? \sp 4}}+
{{\left( \%D+1 \right)}\  ?}+1 
$$
\returnType{Type: Union(SparseUnivariatePolynomial FiniteField(2,2),...)}

For {\tt FFP} you choose both the ground field and the irreducible
polynomial used in the representation.  The degree of the extension is
the degree of the polynomial.

\spadcommand{GF4096 := FFP(GF4,f); }
\returnType{Type: Domain}

\spadcommand{discreteLog random()\$GF4096 }
$$
582 
$$
\returnType{Type: PositiveInteger}

\subsection{Cyclic Group Representations}
\label{ugxProblemFiniteCyclic}
\index{finite field}
\index{field!finite!extension of}

In every finite field there exist elements whose powers are all the
nonzero elements of the field.  Such an element is called a 
{\it primitive element}.

In {\tt FiniteFieldCyclicGroup} (abbreviation {\tt FFCG})
\index{group!cyclic} the nonzero elements are represented by the
powers of a fixed primitive \index{element!primitive} element
\index{primitive element} of the field (that is, a generator of its
cyclic multiplicative group).  Multiplication (and hence
exponentiation) using this representation is easy.  To do addition, we
consider our primitive element as the root of a primitive polynomial
(an irreducible polynomial whose roots are all primitive).  See
\sectionref{ugxProblemFiniteUtility}
for examples of how to compute such a polynomial.

To use {\tt FiniteFieldCyclicGroup} you provide a prime number and an
extension degree.
\spadcommand{GF81 := FFCG(3,4); }
\returnType{Type: Domain}

Axiom uses the prime field, here {\tt PrimeField 3}, as the ground
field and it chooses a primitive polynomial of degree $n$, here 4,
over the prime field.

\spadcommand{a := primitiveElement()\$GF81 }
$$
 \%F \sp 1 
$$
\returnType{Type: FiniteFieldCyclicGroup(3,4)}

You can calculate in $GF81$.

\spadcommand{b  := a**12 - a**5 + a }
$$
 \%F \sp {72} 
$$
\returnType{Type: FiniteFieldCyclicGroup(3,4)}

%Original Page 284

In this representation of finite fields the discrete logarithm of an
element can be seen directly in its output form.

\spadcommand{b }
$$
 \%F \sp {72} 
$$
\returnType{Type: FiniteFieldCyclicGroup(3,4)}

\spadcommand{discreteLog b }
$$
72 
$$
\returnType{Type: PositiveInteger}

{\tt FiniteFieldCyclicGroupExtension} (abbreviation {\tt FFCGX}) is
similar to\\ 
{\tt FiniteFieldCyclicGroup} except that the ground field for\\ 
{\tt FiniteFieldCyclicGroupExtension} is arbitrary and chosen by
you.  In case you select the prime field as ground field, there is
essentially no difference between the constructed two finite field
extensions.

\spadcommand{GF9 := FF(3,2); }
\returnType{Type: Domain}

\spadcommand{GF729 := FFCGX(GF9,3); }
\returnType{Type: Domain}

\spadcommand{r := (random()\$GF729) ** 20 }
$$
 \%H \sp {420} 
$$
\returnType{Type: FiniteFieldCyclicGroupExtension(FiniteField(3,2),3)}

\spadcommand{trace(r) }
$$
0 
$$
\returnType{Type: FiniteField(3,2)}

{\tt FiniteFieldCyclicGroupExtensionByPolynomial} (abbreviation 
{\tt FFCGP}) is similar to \\
{\tt FiniteFieldCyclicGroup} and 
{\tt FiniteFieldCyclicGroupExtension} \\
but is more general.  For \\
{\tt FiniteFieldCyclicGroupExtensionByPolynomial} you choose both the
ground field and the irreducible polynomial used in the
representation.  The degree of the extension is the degree of the
polynomial.

\spadcommand{GF3  := PrimeField 3; }
\returnType{Type: Domain}

%Original Page 285

We use a utility operation to generate an irreducible primitive
polynomial (see \sectionref{ugxProblemFiniteUtility}).
The polynomial has one variable that is ``anonymous'': 
it displays as a question mark.

\spadcommand{f := createPrimitivePoly(4)\$FFPOLY(GF3) }
$$
{? \sp 4}+?+2 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 3}

\spadcommand{GF81 := FFCGP(GF3,f); }
\returnType{Type: Domain}

Let's look at a random element from this field.

\spadcommand{random()\$GF81 }
$$
 \%K \sp {13} 
$$
\returnType{Type: 
FiniteFieldCyclicGroupExtensionByPolynomial(PrimeField 3,?**4+?+2)}

\subsection{Normal Basis Representations}
\label{ugxProblemFiniteNormal}
\index{finite field}
\index{field!finite!extension of}
\index{basis!normal}
\index{normal basis}

Let $K$ be a finite extension of degree $n$ of the finite field $F$
and let $F$ have $q$ elements.  An element $x$ of $K$ is said to be
{\it normal} over $F$ if the elements

$$1, x^q, x^{q^2}, \ldots, x^{q^{n-1}}$$

form a basis of $K$ as a vector space over $F$.  Such a basis is
called a {\it normal basis}.\footnote{This agrees with the general
definition of a normal basis because the $n$ distinct powers of the
automorphism $x \mapsto x^q$ constitute the Galois group of $K/F$.}

If $x$ is normal over $F$, its minimal \index{polynomial!minimal}
polynomial is also said to be {\it normal} over $F$.  
\index{minimal polynomial} 
There exist normal bases for all finite extensions of arbitrary 
finite fields.

In {\tt FiniteFieldNormalBasis} (abbreviation {\tt FFNB}), the
elements of the finite field are represented by coordinate vectors
with respect to a normal basis.

You provide a prime $p$ and an extension degree $n$.

\spadcommand{K := FFNB(3,8) }
$$
FiniteFieldNormalBasis(3,8) 
$$
\returnType{Type: Domain}

Axiom uses the prime field {\tt PrimeField(p)}, here {\tt PrimeField
3}, and it chooses a normal polynomial of degree $n$, here 8, over the
ground field.  The remainder class of the indeterminate is used as the
normal element.  The polynomial indeterminate is automatically chosen
by Axiom and is typically something like $\%A$ or $\%D$.  These
(strange) variables are only for output display; there are several
ways to construct elements of this field.  The output of the basis
elements is something like $\%A^{q^i}.$

\spadcommand{a := normalElement()\$K }
$$
 \%I 
$$
\returnType{Type: FiniteFieldNormalBasis(3,8)}

%Original Page 286

You can calculate in $K$ using $a$.

\spadcommand{b  := a**12 - a**5 + a }
$$
{2 \  { \%I \sp {q \sp 7}}}+{ \%I \sp {q \sp 5}}+{ \%I \sp q} 
$$
\returnType{Type: FiniteFieldNormalBasis(3,8)}

{\tt FiniteFieldNormalBasisExtension} (abbreviation {\tt FFNBX}) is
similar to \\
{\tt FiniteField\-NormalBasis} except that the groundfield
for \\
{\tt FiniteFieldNormalBasisExtension} is arbitrary and chosen by
you.  In case you select the prime field as ground field, there is
essentially no difference between the constructed two finite field
extensions.

\spadcommand{GF9 := FFNB(3,2); }
\returnType{Type: Domain}

\spadcommand{GF729 := FFNBX(GF9,3); }
\returnType{Type: Domain}

\spadcommand{r := random()\$GF729 }
$$
2 \  \%K \  { \%L \sp q} 
$$
\returnType{Type: 
FiniteFieldNormalBasisExtension(FiniteFieldNormalBasis(3,2),3)}

\spadcommand{r + r**3 + r**9 + r**27 }
$$
{2 \  \%K \  { \%L \sp {q \sp 2}}}+
{{\left( {2 \  { \%K \sp q}}+{2 \   \%K} \right)}\  { \%L \sp q}}+
{2 \  { \%K \sp q} \  \%L} 
$$
\returnType{Type: 
FiniteFieldNormalBasisExtension(FiniteFieldNormalBasis(3,2),3)}

{\tt FiniteFieldNormalBasisExtensionByPolynomial} (abbreviation 
{\tt FFNBP})\\ 
is similar to {\tt FiniteFieldNormalBasis} and\\
{\tt FiniteFieldNormalBasisExtension} but is more general.  For\\
{\tt FiniteFieldNormalBasisExtensionByPolynomial} you choose both the
ground field and the irreducible polynomial used in the representation.  
The degree of the extension is the degree of the polynomial.

\spadcommand{GF3 := PrimeField 3; }
\returnType{Type: Domain}

%Original Page 287

We use a utility operation to generate an irreducible normal
polynomial (see \sectionref{ugxProblemFiniteUtility}).  p
The polynomial has
one variable that is ``anonymous'': it displays as a question mark.

\spadcommand{f := createNormalPoly(4)\$FFPOLY(GF3) }
$$
{? \sp 4}+{2 \  {? \sp 3}}+2 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 3}

\spadcommand{GF81 := FFNBP(GF3,f); }
\returnType{Type: Domain}

Let's look at a random element from this field.

\spadcommand{r := random()\$GF81 }
$$
{ \%M \sp {q \sp 2}}+{2 \  { \%M \sp q}}+{2 \  \%M} 
$$
\returnType{Type: 
FiniteFieldNormalBasisExtensionByPolynomial(PrimeField 3,?**4+2*?**3+2)}

\spadcommand{r * r**3 * r**9 * r**27 }
$$
{2 \  { \%M \sp {q \sp 3}}}+
{2 \  { \%M \sp {q \sp 2}}}+
{2 \  { \%M \sp q}}+
{2 \  \%M} 
$$
\returnType{Type: 
FiniteFieldNormalBasisExtensionByPolynomial(PrimeField 3,?**4+2*?**3+2)}

\spadcommand{norm r }
$$
2 
$$
\returnType{Type: PrimeField 3}

\subsection{Conversion Operations for Finite Fields}
\label{ugxProblemFiniteConversion}
\index{field!finite!conversions}

Let $K$ be a finite field.

\spadcommand{K := PrimeField 3 }
$$
\mbox{\rm PrimeField 3} 
$$
\returnType{Type: Domain}

An extension field $K_m$ of degree $m$ over $K$ is a subfield of an
extension field $K_n$ of degree $n$ over $K$ if and only if $m$
divides $n$.

\begin{center}
\begin{tabular}{ccc}
$K_n$ \\
$|$ \\
$K_m$ & $\Longleftrightarrow$ & $m | n$ \\
$|$ \\
K
\end{tabular}
\end{center}

{\tt FiniteFieldHomomorphisms} provides conversion operations between
different extensions of one fixed finite ground field and between
different representations of these finite fields.

%Original Page 288

Let's choose $m$ and $n$,

\spadcommand{(m,n) := (4,8) }
$$
8 
$$
\returnType{Type: PositiveInteger}

build the field extensions,

\spadcommand{Km := FiniteFieldExtension(K,m) }
$$
\mbox{\rm FiniteFieldExtension(PrimeField 3,4)} 
$$
\returnType{Type: Domain}

and pick two random elements from the smaller field.

\spadcommand{Kn := FiniteFieldExtension(K,n) }
$$
\mbox{\rm FiniteFieldExtension(PrimeField 3,8)} 
$$
\returnType{Type: Domain}

\spadcommand{a1 := random()\$Km }
$$
{2 \  { \%A \sp 3}}+{ \%A \sp 2} 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 3,4)}

\spadcommand{b1 := random()\$Km }
$$
{ \%A \sp 3}+{ \%A \sp 2}+{2 \  \%A}+1 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 3,4)}

Since $m$ divides $n$,
$K_m$ is a subfield of $K_n$.

\spadcommand{a2 := a1 :: Kn }
$$
 \%B \sp 4 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 3,8)}

Therefore we can convert the elements of $K_m$
into elements of $K_n$.

\spadcommand{b2 := b1 :: Kn }
$$
{2 \  { \%B \sp 6}}+{2 \  { \%B \sp 4}}+{ \%B \sp 2}+1 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 3,8)}

To check this, let's do some arithmetic.

\spadcommand{a1+b1 - ((a2+b2) :: Km) }
$$
0 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 3,4)}

\spadcommand{a1*b1 - ((a2*b2) :: Km) }
$$
0 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 3,4)}

There are also conversions available for the situation, when $K_m$ and
$K_n$ are represented in different ways (see
\sectionref{ugxProblemFiniteExtensionFinite}).  For example let's choose
$K_m$ where the representation is 0 plus the cyclic multiplicative
group and $K_n$ with a normal basis representation.

%Original Page 289

\spadcommand{Km := FFCGX(K,m) }
$$
\mbox{\rm FiniteFieldCyclicGroupExtension(PrimeField 3,4)} 
$$
\returnType{Type: Domain}

\spadcommand{Kn := FFNBX(K,n) }
$$
\mbox{\rm FiniteFieldNormalBasisExtension(PrimeField 3,8)} 
$$
\returnType{Type: Domain}

\spadcommand{(a1,b1) := (random()\$Km,random()\$Km) }
$$
 \%C \sp {13} 
$$
\returnType{Type: FiniteFieldCyclicGroupExtension(PrimeField 3,4)}

\spadcommand{a2 := a1 :: Kn }
$$
{2 \  { \%D \sp {q \sp 6}}}+
{2 \  { \%D \sp {q \sp 5}}}+
{2 \  { \%D \sp {q \sp 4}}}+
{2 \  { \%D \sp {q \sp 2}}}+
{2 \  { \%D \sp q}}+
{2 \  \%D} 
$$
\returnType{Type: FiniteFieldNormalBasisExtension(PrimeField 3,8)}

\spadcommand{b2 := b1 :: Kn }
$$
{2 \  { \%D \sp {q \sp 7}}}+
{ \%D \sp {q \sp 6}}+
{ \%D \sp {q \sp 5}}+
{ \%D \sp {q \sp 4}}+
{2 \  { \%D \sp {q \sp 3}}}+
{ \%D \sp {q \sp 2}}+
{ \%D \sp q}+ 
\%D 
$$
\returnType{Type: FiniteFieldNormalBasisExtension(PrimeField 3,8)}

Check the arithmetic again.

\spadcommand{a1+b1 - ((a2+b2) :: Km) }
$$
0 
$$
\returnType{Type: FiniteFieldCyclicGroupExtension(PrimeField 3,4)}

\spadcommand{a1*b1 - ((a2*b2) :: Km) }
$$
0 
$$
\returnType{Type: FiniteFieldCyclicGroupExtension(PrimeField 3,4)}

\subsection{Utility Operations for Finite Fields}
\label{ugxProblemFiniteUtility}

{\tt FiniteFieldPolynomialPackage} (abbreviation {\tt FFPOLY})
provides operations for generating, counting and testing polynomials
over finite fields. Let's start with a couple of definitions:
\begin{itemize}
\item A polynomial is {\it primitive} if its roots are primitive
\index{polynomial!primitive}
elements in an extension of the coefficient field of degree equal
to the degree of the polynomial.
\item A polynomial is {\it normal} over its coefficient field
\index{polynomial!normal}
if its roots are linearly independent
elements in an extension of the coefficient field of degree equal
to the degree of the polynomial.
\end{itemize}

In what follows, many of the generated polynomials have one
``anonymous'' variable.  This indeterminate is displayed as a question
mark ({\tt "?"}).

%Original Page 290

To fix ideas, let's use the field with five elements for the first
few examples.

\spadcommand{GF5 := PF 5; }
\returnType{Type: Domain}

You can generate irreducible polynomials of any (positive) degree
\index{polynomial!irreducible} (within the storage capabilities of the
computer and your ability to wait) by using
\spadfunFrom{createIrreduciblePoly}{FiniteFieldPolynomialPackage}.

\spadcommand{f := createIrreduciblePoly(8)\$FFPOLY(GF5) }
$$
{? \sp 8}+{? \sp 4}+2 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

Does this polynomial have other important properties? Use
{\bf primitive?} to test whether it is a primitive polynomial.

\spadcommand{primitive?(f)\$FFPOLY(GF5) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Use {\bf normal?} to test whether it is a normal polynomial.

\spadcommand{normal?(f)\$FFPOLY(GF5) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\noindent
Note that this is actually a trivial case, because a normal polynomial
of degree $n$ must have a nonzero term of degree $n-1$.  We will refer
back to this later.

To get a primitive polynomial of degree 8 just issue this.

\spadcommand{p := createPrimitivePoly(8)\$FFPOLY(GF5) }
$$
{? \sp 8}+{? \sp 3}+{? \sp 2}+?+2 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

\spadcommand{primitive?(p)\$FFPOLY(GF5) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

This polynomial is not normal,

\spadcommand{normal?(p)\$FFPOLY(GF5) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

but if you want a normal one simply write this.

\spadcommand{n := createNormalPoly(8)\$FFPOLY(GF5)  }
$$
{? \sp 8}+{4 \  {? \sp 7}}+{? \sp 3}+1 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

This polynomial is not primitive!

\spadcommand{primitive?(n)\$FFPOLY(GF5) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

This could have been seen directly, as the constant term is 1 here,
which is not a primitive element up to the factor ($-1$) raised to the
degree of the polynomial.\footnote{Cf. Lidl, R. \& Niederreiter, H.,
{\it Finite Fields,} Encycl. of Math. 20, (Addison-Wesley, 1983),
p.90, Th. 3.18.}

%Original Page 291

What about polynomials that are both primitive and normal?  The
existence of such a polynomial is by no means obvious.
\footnote{The existence of such polynomials is proved in
Lenstra, H. W. \& Schoof, R. J., {\it Primitive
Normal Bases for Finite Fields,} Math. Comp. 48, 1987, pp. 217-231.}
%

If you really need one use either
\spadfunFrom{createPrimitiveNormalPoly}{FiniteFieldPolynomialPackage} or
\spadfunFrom{createNormalPrimitivePoly}{FiniteFieldPolynomialPackage}.

\spadcommand{createPrimitiveNormalPoly(8)\$FFPOLY(GF5) }
$$
{? \sp 8}+{4 \  {? \sp 7}}+{2 \  {? \sp 5}}+2 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

If you want to obtain additional polynomials of the various types
above as given by the {\bf create...} operations above, you can use
the {\bf next...} operations.  For instance,
\spadfunFrom{nextIrreduciblePoly}{FiniteFieldPolynomialPackage} yields
the next monic irreducible polynomial with the same degree as the
input polynomial.  By ``next'' we mean ``next in a natural order using
the terms and coefficients.''  This will become more clear in the
following examples.

This is the field with five elements.

\spadcommand{GF5 := PF 5; }
\returnType{Type: Domain}

Our first example irreducible polynomial, say of degree 3, must be
``greater'' than this.

\spadcommand{h := monomial(1,8)\$SUP(GF5) }
$$
? \sp 8 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

You can generate it by doing this.

\spadcommand{nh := nextIrreduciblePoly(h)\$FFPOLY(GF5) }
$$
{? \sp 8}+2 
$$
\returnType{Type: Union(SparseUnivariatePolynomial PrimeField 5,...)}

Notice that this polynomial is not the same as the one
\spadfunFrom{createIrreduciblePoly}{FiniteFieldPolynomialPackage}.

\spadcommand{createIrreduciblePoly(3)\$FFPOLY(GF5) }
$$
{? \sp 3}+?+1 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

You can step through all irreducible polynomials of degree 8 over
the field with 5 elements by repeatedly issuing this.

\spadcommand{nh := nextIrreduciblePoly(nh)\$FFPOLY(GF5) }
$$
{? \sp 8}+3 
$$
\returnType{Type: Union(SparseUnivariatePolynomial PrimeField 5,...)}

You could also ask for the total number of these.

\spadcommand{numberOfIrreduciblePoly(5)\$FFPOLY(GF5) }
$$
624 
$$
\returnType{Type: PositiveInteger}

%Original Page 292

We hope that ``natural order'' on polynomials is now clear: first we
compare the number of monomials of two polynomials (``more'' is
``greater''); then, if necessary, the degrees of these monomials
(lexicographically), and lastly their coefficients (also
lexicographically, and using the operation {\bf lookup} if our field
is not a prime field).  Also note that we make both polynomials monic
before looking at the coefficients: multiplying either polynomial by a
nonzero constant produces the same result.

The package {\tt FiniteFieldPolynomialPackage} also provides similar
operations for primitive and normal polynomials. With the exception of
the number of primitive normal polynomials; we're not aware of any
known formula for this.

\spadcommand{numberOfPrimitivePoly(3)\$FFPOLY(GF5) }
$$
20 
$$
\returnType{Type: PositiveInteger}

Take these,

\spadcommand{m := monomial(1,1)\$SUP(GF5) }
$$
? 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

\spadcommand{f := m**3 + 4*m**2 + m + 2 }
$$
{? \sp 3}+{4 \  {? \sp 2}}+?+2 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

and then we have:

\spadcommand{f1 := nextPrimitivePoly(f)\$FFPOLY(GF5) }
$$
{? \sp 3}+{4 \  {? \sp 2}}+{4 \  ?}+2 
$$
\returnType{Type: Union(SparseUnivariatePolynomial PrimeField 5,...)}

What happened?

\spadcommand{nextPrimitivePoly(f1)\$FFPOLY(GF5) }
$$
{? \sp 3}+{2 \  {? \sp 2}}+3 
$$
\returnType{Type: Union(SparseUnivariatePolynomial PrimeField 5,...)}

Well, for the ordering used in
\spadfunFrom{nextPrimitivePoly}{FiniteFieldPolynomialPackage} we use
as first criterion a comparison of the constant terms of the
polynomials.  Analogously, in
\spadfunFrom{nextNormalPoly}{FiniteFieldPolynomialPackage} we first
compare the monomials of degree 1 less than the degree of the
polynomials (which is nonzero, by an earlier remark).

\spadcommand{f := m**3 + m**2 + 4*m + 1  }
$$
{? \sp 3}+{? \sp 2}+{4 \  ?}+1 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 5}

\spadcommand{f1 := nextNormalPoly(f)\$FFPOLY(GF5) }
$$
{? \sp 3}+{? \sp 2}+{4 \  ?}+3 
$$
\returnType{Type: Union(SparseUnivariatePolynomial PrimeField 5,...)}

%Original Page 293

\spadcommand{nextNormalPoly(f1)\$FFPOLY(GF5) }
$$
{? \sp 3}+{2 \  {? \sp 2}}+1 
$$
\returnType{Type: Union(SparseUnivariatePolynomial PrimeField 5,...)}

\noindent
We don't have to restrict ourselves to prime fields.

Let's consider, say, a field with 16 elements.

\spadcommand{GF16 := FFX(FFX(PF 2,2),2);  }
\returnType{Type: Domain}

We can apply any of the operations described above.

\spadcommand{createIrreduciblePoly(5)\$FFPOLY(GF16) }
$$
{? \sp 5}+ \%G 
$$
\returnType{Type: SparseUnivariatePolynomial 
FiniteFieldExtension(FiniteFieldExtension(PrimeField 2,2),2)}

Axiom also provides operations for producing random polynomials of a
given degree

\spadcommand{random(5)\$FFPOLY(GF16) }
$$
\begin{array}{@{}l}
{? \sp 5}+
{{\left( { \%F \  \%G}+1 \right)}\  {? \sp 4}}+
{ \%F \  \%G \  {? \sp 3}}+
{{\left( \%G+ \%F+1 \right)}\  {? \sp 2}}+
\\
\\
\displaystyle
{{\left( {{\left( \%F+1 \right)}\  \%G}+ \%F \right)}\  ?}+1 
\end{array}
$$
\returnType{Type: SparseUnivariatePolynomial 
FiniteFieldExtension(FiniteFieldExtension(PrimeField 2,2),2)}

or with degree between two given bounds.

\spadcommand{random(3,9)\$FFPOLY(GF16) }
$$
{? \sp 3}+
{{\left( { \%F \  \%G}+1 \right)}\  {? \sp 2}}+
{{\left( \%G+ \%F+1 \right)}\  ?}+1 
$$
\returnType{Type: SparseUnivariatePolynomial 
FiniteFieldExtension(FiniteFieldExtension(PrimeField 2,2),2)}

{\tt FiniteFieldPolynomialPackage2} (abbreviation {\tt FFPOLY2})
exports an operation {\bf rootOf\-IrreduciblePoly} for finding one root
of an irreducible polynomial $f$ \index{polynomial!root of} in an
extension field of the coefficient field.  The degree of the extension
has to be a multiple of the degree of $f$.  It is not checked whether
$f$ actually is irreducible.

To illustrate this operation, we fix a ground field $GF$

\spadcommand{GF2 := PrimeField 2; }
\returnType{Type: Domain}

and then an extension field.

\spadcommand{F := FFX(GF2,12) }
$$
\mbox{\rm FiniteFieldExtension(PrimeField 2,12)} 
$$
\returnType{Type: Domain}

We construct an irreducible polynomial over $GF2$.

\spadcommand{f := createIrreduciblePoly(6)\$FFPOLY(GF2) }
$$
{? \sp 6}+?+1 
$$
\returnType{Type: SparseUnivariatePolynomial PrimeField 2}

%Original Page 293

We compute a root of $f$.

\spadcommand{root := rootOfIrreduciblePoly(f)\$FFPOLY2(F,GF2) }
$$
{ \%H \sp {11}}+{ \%H \sp 8}+{ \%H \sp 7}+{ \%H \sp 5}+ \%H+1 
$$
\returnType{Type: FiniteFieldExtension(PrimeField 2,12)}

and check the result
\spadcommand{eval(f, monomial(1,1)\$SUP(F) = root) }
$$
0 
$$
\returnType{Type: SparseUnivariatePolynomial 
FiniteFieldExtension(PrimeField 2,12)}

\section{Primary Decomposition of Ideals}
\label{ugProblemIdeal}

Axiom provides a facility for the primary decomposition
\index{ideal!primary decomposition} of \index{primary decomposition of
ideal} polynomial ideals over fields of characteristic zero.  The
algorithm
%is discussed in \cite{gtz:gbpdpi} and
works in essentially two steps:
\begin{enumerate}
\item the problem is solved for 0-dimensional ideals by ``generic''
projection on the last coordinate
\item a ``reduction process'' uses localization and ideal quotients
to reduce the general case to the 0-dimensional one.
\end{enumerate}
The Axiom constructor {\tt PolynomialIdeals} represents ideals with
coefficients in any field and supports the basic ideal operations,
including intersection, sum and quotient.  {\tt Ideal\-DecompositionPackage} 
contains the specific operations for the
primary decomposition and the computation of the radical of an ideal
with polynomial coefficients in a field of characteristic 0 with an
effective algorithm for factoring polynomials.

The following examples illustrate the capabilities of this facility.

First consider the ideal generated by
$x^2 + y^2 - 1$
(which defines a circle in the $(x,y)$-plane) and the ideal
generated by $x^2 - y^2$ (corresponding to the
straight lines $x = y$ and $x = -y$.

\spadcommand{(n,m) : List DMP([x,y],FRAC INT) }
\returnType{Type: Void}

\spadcommand{m := [x**2+y**2-1]  }
$$
\left[
{{x \sp 2}+{y \sp 2} -1} 
\right]
$$
\returnType{Type: List 
DistributedMultivariatePolynomial([x,y],Fraction Integer)}

\spadcommand{n := [x**2-y**2]  }
$$
\left[
{{x \sp 2} -{y \sp 2}} 
\right]
$$
\returnType{Type: List 
DistributedMultivariatePolynomial([x,y],Fraction Integer)}

We find the equations defining the intersection of the two loci.
This correspond to the sum of the associated ideals.

\spadcommand{id := ideal m  + ideal n  }
$$
\left[
{{x \sp 2} -{\frac{1}{2}}}, {{y \sp 2} -{\frac{1}{2}}} 
\right]
$$
\returnType{Type: PolynomialIdeals(Fraction Integer,
DirectProduct(2,NonNegativeInteger),OrderedVariableList [x,y],
DistributedMultivariatePolynomial([x,y],Fraction Integer))}

%Original Page 295

We can check if the locus contains only a finite number of points,
that is, if the ideal is zero-dimensional.

\spadcommand{zeroDim? id }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{zeroDim?(ideal m) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{dimension ideal m }
$$
1 
$$
\returnType{Type: PositiveInteger}

We can find polynomial relations among the generators ($f$ and $g$ are
the parametric equations of the knot).

\spadcommand{(f,g):DMP([x,y],FRAC INT) }
\returnType{Type: Void}

\spadcommand{f := x**2-1  }
$$
{x \sp 2} -1 
$$
\returnType{Type: DistributedMultivariatePolynomial([x,y],Fraction Integer)}

\spadcommand{g := x*(x**2-1)  }
$$
{x \sp 3} -x 
$$
\returnType{Type: DistributedMultivariatePolynomial([x,y],Fraction Integer)}

\spadcommand{relationsIdeal [f,g] }
$$
{\left[ {-{ \%B \sp 2}+{ \%A \sp 3}+{ \%A \sp 2}} \right]}
\mid 
{\left[ { \%A={{x \sp 2} -1}}, { \%B={{x \sp 3} -x}} \right]}
$$
\returnType{Type: SuchThat(List Polynomial Fraction Integer,
List Equation Polynomial Fraction Integer)}

We can compute the primary decomposition of an ideal.

\spadcommand{l: List DMP([x,y,z],FRAC INT) }
\returnType{Type: Void}

\spadcommand{l:=[x**2+2*y**2,x*z**2-y*z,z**2-4]  }
$$
\left[
{{x \sp 2}+{2 \  {y \sp 2}}}, {{x \  {z \sp 2}} -{y \  z}}, {{z \sp 2} -4} 
\right]
$$
\returnType{Type: List 
DistributedMultivariatePolynomial([x,y,z],Fraction Integer)}

%Original Page 296

\spadcommand{ld:=primaryDecomp ideal l  }
$$
\left[
{\left[ {x+{{\frac{1}{2}} \  y}}, {y \sp 2}, {z+2} \right]},
{\left[ {x -{{\frac{1}{2}} \  y}}, {y \sp 2}, {z -2} \right]}
\right]
$$
\returnType{Type: List PolynomialIdeals(Fraction Integer,
DirectProduct(3,NonNegativeInteger),
OrderedVariableList [x,y,z],
DistributedMultivariatePolynomial([x,y,z],Fraction Integer))}

We can intersect back.

\spadcommand{reduce(intersect,ld) }
$$
\left[
{x -{{\frac{1}{4}} \  y \  z}}, {y \sp 2}, {{z \sp 2} -4} 
\right]
$$
\returnType{Type: PolynomialIdeals(Fraction Integer,
DirectProduct(3,NonNegativeInteger),
OrderedVariableList [x,y,z],
DistributedMultivariatePolynomial([x,y,z],Fraction Integer))}

We can compute the radical of every primary component.

\spadcommand{reduce(intersect,[radical ld.i for i in 1..2]) }
$$
\left[
x, y, {{z \sp 2} -4} 
\right]
$$
\returnType{Type: PolynomialIdeals(Fraction Integer,
DirectProduct(3,NonNegativeInteger),
OrderedVariableList [x,y,z],
DistributedMultivariatePolynomial([x,y,z],Fraction Integer))}

Their intersection is equal to the radical of the ideal of $l$.

\spadcommand{radical ideal l }
$$
\left[x, y, {{z \sp 2} -4} \right]
$$
\returnType{Type: PolynomialIdeals(Fraction Integer,
DirectProduct(3,NonNegativeInteger),
OrderedVariableList [x,y,z],
DistributedMultivariatePolynomial([x,y,z],Fraction Integer))}

\section{Computation of Galois Groups}
\label{ugProblemGalois}

As a sample use of Axiom's algebraic number facilities,
\index{group!Galois}
we compute
\index{Galois!group}
the Galois group of the polynomial
$p(x) = x^5 - 5 x + 12$.

\spadcommand{p := x**5 - 5*x + 12 }
$$
{x \sp 5} -{5 \  x}+{12} 
$$
\returnType{Type: Polynomial Integer}

We would like to construct a polynomial $f(x)$ such that the splitting
\index{field!splitting} field \index{splitting field} of $p(x)$ is
generated by one root of $f(x)$.  First we construct a polynomial 
$r = r(x)$ such that one root of $r(x)$ generates the field generated by
two roots of the polynomial $p(x)$.  (As it will turn out, the field
generated by two roots of $p(x)$ is, in fact, the splitting field of
$p(x)$.)

From the proof of the primitive element theorem we know that if $a$
and $b$ are algebraic numbers, then the field ${\bf Q}(a,b)$ is equal
to ${\bf Q}(a+kb)$ for an appropriately chosen integer $k$.  In our
case, we construct the minimal polynomial of $a_i - a_j$, where $a_i$
and $a_j$ are two roots of $p(x)$.  We construct this polynomial using
{\bf resultant}.  The main result we need is the following: If $f(x)$
is a polynomial with roots $a_i \ldots a_m$ and $g(x)$ is a polynomial
with roots $b_i \ldots b_n$, then the polynomial $h(x) =
resultant(f(y), g(x-y), y)$ is a polynomial of degree $m*n$ with roots
$a_i + b_j, i = 1 \ldots m, j = 1 \ldots n$.

%Original Page 297

For $f(x)$ we use the polynomial $p(x)$.  For $g(x)$ we use the
polynomial $-p(-x)$.  Thus, the polynomial we first construct is
$resultant(p(y), -p(y-x), y)$.

\spadcommand{q := resultant(eval(p,x,y),-eval(p,x,y-x),y)  }
$$
\begin{array}{@{}l}
{x \sp {25}} -
{{50} \  {x \sp {21}}} -
{{2375} \  {x \sp {17}}}+
{{90000} \  {x \sp {15}}} -
{{5000} \  {x \sp {13}}}+
{{2700000} \  {x \sp {11}}}+
{{250000} \  {x \sp 9}}+
\\
\\
\displaystyle
{{18000000} \  {x \sp 7}}+
{{64000000} \  {x \sp 5}} 
\end{array}
$$
\returnType{Type: Polynomial Integer}

The roots of $q(x)$ are $a_i - a_j, i \leq 1, j \leq 5$.  Of course,
there are five pairs $(i,j)$ with $i = j$, so $0$ is a 5-fold root of
$q(x)$.

Let's get rid of this factor.

\spadcommand{q1 := exquo(q, x**5)  }
$$
\begin{array}{@{}l}
{x \sp {20}} -
{{50} \  {x \sp {16}}} -
{{2375} \  {x \sp {12}}}+
{{90000} \  {x \sp {10}}} -
{{5000} \  {x \sp 8}}+
{{2700000} \  {x \sp 6}}+
\\
\\
\displaystyle
{{250000} \  {x \sp 4}}+
{{18000000} \  {x \sp 2}}+
{64000000} 
\end{array}
$$
\returnType{Type: Union(Polynomial Integer,...)}

Factor the polynomial $q1$.

\spadcommand{factoredQ := factor q1  }
$$
\begin{array}{@{}l}
{\left( 
{x \sp {10}} -
{{10} \  {x \sp 8}} -
{{75} \  {x \sp 6}}+
{{1500} \  {x \sp 4}} -
{{5500} \  {x \sp 2}}+
{16000} 
\right)} *
\\
\\
\displaystyle
{\left( 
{x \sp {10}}+
{{10} \  {x \sp 8}}+
{{125} \  {x \sp 6}}+
{{500} \  {x \sp 4}}+
{{2500} \  {x \sp 2}}+
{4000} 
\right)}
\end{array}
$$
\returnType{Type: Factored Polynomial Integer}

We see that $q1$ has two irreducible factors, each of degree $10$.
(The fact that the polynomial $q1$ has two factors of degree $10$ is
enough to show that the Galois group of $p(x)$ is the dihedral group
of order $10$.\footnote{See McKay, Soicher, Computing Galois Groups
over the Rationals, Journal of Number Theory 20, 273-281 (1983).  We
do not assume the results of this paper, however, and we continue with
the computation.}  Note that the type of $factoredQ$ is {\tt FR POLY
INT}, that is, {\tt Factored Polynomial Integer}.  \index{Factored}
This is a special data type for recording factorizations of
polynomials with integer coefficients.

We can access the individual factors using the operation
\spadfunFrom{nthFactor}{Factored}.

\spadcommand{r := nthFactor(factoredQ,1)  }
$$
{x \sp {10}} -{{10} \  {x \sp 8}} -{{75} \  {x \sp 6}}+{{1500} \  {x \sp 4}} 
-{{5500} \  {x \sp 2}}+{16000} 
$$
\returnType{Type: Polynomial Integer}

Consider the polynomial $r = r(x)$.  This is the minimal polynomial of
the difference of two roots of $p(x)$.  Thus, the splitting field of
$p(x)$ contains a subfield of degree $10$.  We show that this subfield
is, in fact, the splitting field of $p(x)$ by showing that $p(x)$
factors completely over this field.

%Original Page 298

First we create a symbolic root of the polynomial $r(x)$.  (We
replaced $x$ by $b$ in the polynomial $r$ so that our symbolic root
would be printed as $b$.)

\spadcommand{beta:AN := rootOf(eval(r,x,b))  }
$$
b 
$$
\returnType{Type: AlgebraicNumber}

We next tell Axiom to view $p(x)$ as a univariate polynomial in $x$
with algebraic number coefficients.  This is accomplished with this
type declaration.

\spadcommand{p := p::UP(x,INT)::UP(x,AN)  }
$$
{x \sp 5} -{5 \  x}+{12} 
$$
\returnType{Type: UnivariatePolynomial(x,AlgebraicNumber)}

Factor $p(x)$ over the field ${\bf Q}(\beta)$.
(This computation will take some time!)

\spadcommand{algFactors := factor(p,[beta])  }
$$
\begin{array}{@{}l}
{\left( 
x+
{\frac{\left(
\begin{array}{@{}l}
-{{85} \  {b \sp 9}} -
{{116} \  {b \sp 8}}+
{{780} \  {b \sp 7}}+
{{2640} \  {b \sp 6}}+
{{14895} \  {b \sp 5}} -
\\
\\
\displaystyle
{{8820} \  {b \sp 4}} -
{{127050} \  {b \sp 3}} -
{{327000} \  {b \sp 2}} -
{{405200} \  b}+
{2062400}
\end{array}
\right)}{1339200}}
\right)}
\\
\\
\displaystyle
{\left( 
x+
{\frac{-{{17} \  {b \sp 8}}+
{{156} \  {b \sp 6}}+
{{2979} \  {b \sp 4}} -
{{25410} \  {b \sp 2}} -
{14080}}{66960}} 
\right)}
\\
\\
\displaystyle
\  {\left( 
x+
{\frac{{{143} \  {b \sp 8}} -
{{2100} \  {b \sp 6}} -
{{10485} \  {b \sp 4}}+
{{290550} \  {b \sp 2}} -
{{334800} \  b} -
{960800}} 
{669600}} 
\right)}
\\
\\
\displaystyle
\  {\left( 
x+
{\frac{{{143} \  {b \sp 8}} -
{{2100} \  {b \sp 6}} -
{{10485} \  {b \sp 4}}+
{{290550} \  {b \sp 2}}+
{{334800} \  b} -
{960800}} 
{669600}} 
\right)}
\\
\\
\displaystyle
{\left( 
x+
{\frac{\left(
\begin{array}{@{}l}
{{85} \  {b \sp 9}} -
{{116} \  {b \sp 8}} -
{{780} \  {b \sp 7}}+
{{2640} \  {b \sp 6}} -
{{14895} \  {b \sp 5}} -
\\
\\
\displaystyle
{{8820} \  {b \sp 4}}+
{{127050} \  {b \sp 3}} -
{{327000} \  {b \sp 2}}+
{{405200} \  b}+
{2062400}
\end{array}
\right)}
{1339200}}
\right)}
\end{array}
$$
\returnType{Type: Factored UnivariatePolynomial(x,AlgebraicNumber)}

When factoring over number fields, it is important to specify the
field over which the polynomial is to be factored, as polynomials have
different factorizations over different fields.  When you use the
operation {\bf factor}, the field over which the polynomial is
factored is the field generated by

%Original Page 299

\begin{enumerate}
\item the algebraic numbers that appear
in the coefficients of the polynomial, and
\item the algebraic numbers that
appear in a list passed as an optional second argument of the operation.
\end{enumerate}
In our case, the coefficients of $p$
are all rational integers and only $beta$
appears in the list, so the field is simply
${\bf Q}(\beta)$.

It was necessary to give the list $[beta]$ as a second argument of the
operation because otherwise the polynomial would have been factored
over the field generated by its coefficients, namely the rational
numbers.

\spadcommand{factor(p) }
$$
{x \sp 5} -{5 \  x}+{12} 
$$
\returnType{Type: Factored UnivariatePolynomial(x,AlgebraicNumber)}

We have shown that the splitting field of $p(x)$ has degree $10$.
Since the symmetric group of degree 5 has only one transitive subgroup
of order $10$, we know that the Galois group of $p(x)$ must be this
group, the dihedral group \index{group!dihedral} of order $10$.
Rather than stop here, we explicitly compute the action of the Galois
group on the roots of $p(x)$.

First we assign the roots of $p(x)$ as the values of five \index{root}
variables.

We can obtain an individual root by negating the constant coefficient of
one of the factors of $p(x)$.

\spadcommand{factor1 := nthFactor(algFactors,1)  }
$$
x+
{
\frac{\left(
\begin{array}{@{}l}
-{{85} \  {b \sp 9}} -
{{116} \  {b \sp 8}}+
{{780} \  {b \sp 7}}+
{{2640} \  {b \sp 6}}+
{{14895} \  {b \sp 5}} -
\\
\\
\displaystyle
{{8820} \  {b \sp 4}} -
{{127050} \  {b \sp 3}} -
{{327000} \  {b \sp 2}} -
{{405200} \  b}+
{2062400}
\end{array}
\right)}{1339200}} 
$$
\returnType{Type: UnivariatePolynomial(x,AlgebraicNumber)}

\spadcommand{root1 := -coefficient(factor1,0)  }
$$
\frac{\left(
\begin{array}{@{}l}
{{85} \  {b \sp 9}}+
{{116} \  {b \sp 8}} -
{{780} \  {b \sp 7}} -
{{2640} \  {b \sp 6}} -
{{14895} \  {b \sp 5}}+
\\
\\
\displaystyle
{{8820} \  {b \sp 4}}+
{{127050} \  {b \sp 3}}+
{{327000} \  {b \sp 2}}+
{{405200} \  b} -
{2062400}
\end{array}
\right)}{1339200} 
$$
\returnType{Type: AlgebraicNumber}

%Original Page 300

We can obtain a list of all the roots in this way.

\spadcommand{roots := [-coefficient(nthFactor(algFactors,i),0) for i in 1..5]  }
$$
\begin{array}{@{}l}
\displaystyle
\left[
\frac{\left(
\begin{array}{@{}l}
{{85} \  {b \sp 9}}+
{{116} \  {b \sp 8}} -
{{780} \  {b \sp 7}} -
{{2640} \  {b \sp 6}} -
{{14895} \  {b \sp 5}}+
{{8820} \  {b \sp 4}}+
\\
\\
\displaystyle
{{127050} \  {b \sp 3}}+
{{327000} \  {b \sp 2}}+
{{405200} \  b} -
{2062400}
\end{array}
\right)}{1339200},
\right.
\\
\\
\displaystyle
{\frac{{{17} \  {b \sp 8}} -
{{156} \  {b \sp 6}} -
{{2979} \  {b \sp 4}}+
{{25410} \  {b \sp 2}}+
{14080}}{66960}},
\\
\\
\displaystyle
{\frac{-{{143} \  {b \sp 8}}+
{{2100} \  {b \sp 6}}+
{{10485} \  {b \sp 4}} -
{{290550} \  {b \sp 2}}+
{{334800} \  b}+
{960800}}{669600}}, 
\\
\\
\displaystyle
{\frac{-{{143} \  {b \sp 8}}+
{{2100} \  {b \sp 6}}+
{{10485} \  {b \sp 4}} -
{{290550} \  {b \sp 2}} -
{{334800} \  b}+{960800}}{669600}}, 
\\
\\
\displaystyle
\left.
\frac{\left(
\begin{array}{@{}l}
-{{85} \  {b \sp 9}}+
{{116} \  {b \sp 8}}+
{{780} \  {b \sp 7}} -
{{2640} \  {b \sp 6}}+
{{14895} \  {b \sp 5}}+
{{8820} \  {b \sp 4}} -
\\
\\
\displaystyle
{{127050} \  {b \sp 3}}+
{{327000} \  {b \sp 2}}-
{{405200} \  b} -
{2062400}
\end{array}
\right)}{1339200}
\right]
\end{array}
$$
\returnType{Type: List AlgebraicNumber}

The expression
\begin{verbatim}
- coefficient(nthFactor(algFactors, i), 0)
\end{verbatim}
is the $i $-th root of $p(x)$ and the elements of $roots$ are the 
$i$-th roots of $p(x)$ as $i$ ranges from $1$ to $5$.

Assign the roots as the values of the variables $a1,...,a5$.

\spadcommand{(a1,a2,a3,a4,a5) := (roots.1,roots.2,roots.3,roots.4,roots.5)  }
$$
\frac{\left(
\begin{array}{@{}l}
-{{85} \  {b \sp 9}}+
{{116} \  {b \sp 8}}+
{{780} \  {b \sp 7}} -
{{2640} \  {b \sp 6}}+
{{14895} \  {b \sp 5}}+
{{8820} \  {b \sp 4}} -
\\
\\
\displaystyle
{{127050} \  {b \sp 3}}+
{{327000} \  {b \sp 2}}-
{{405200} \  b} -
{2062400}
\end{array}
\right)}{1339200}
$$
\returnType{Type: AlgebraicNumber}

%Original Page 301

Next we express the roots of $r(x)$ as polynomials in $beta$.  We
could obtain these roots by calling the operation {\bf factor}:
$factor(r, [beta])$ factors $r(x)$ over ${\bf Q}(\beta)$.  However,
this is a lengthy computation and we can obtain the roots of $r(x)$ as
differences of the roots $a1,...,a5$ of $p(x)$.  Only ten of these
differences are roots of $r(x)$ and the other ten are roots of the
other irreducible factor of $q1$.  We can determine if a given value
is a root of $r(x)$ by evaluating $r(x)$ at that particular value.
(Of course, the order in which factors are returned by the operation
{\bf factor} is unimportant and may change with different
implementations of the operation.  Therefore, we cannot predict in
advance which differences are roots of $r(x)$ and which are not.)

Let's look at four examples (two are roots of $r(x)$ and
two are not).

\spadcommand{eval(r,x,a1 - a2) }
$$
0 
$$
\returnType{Type: Polynomial AlgebraicNumber}

\spadcommand{eval(r,x,a1 - a3) }
$$
\frac{\left(
\begin{array}{@{}l}
{{47905} \  {b \sp 9}}+
{{66920} \  {b \sp 8}} -
{{536100} \  {b \sp 7}} -
{{980400} \  {b \sp 6}} -
{{3345075} \  {b \sp 5}} -
{{5787000} \  {b \sp 4}}+
\\
\\
\displaystyle
{{75572250} \  {b \sp 3}}+
{{161688000} \  {b \sp 2}} -
{{184600000} \  b} -
{710912000}
\end{array}
\right)}{4464} 
$$
\returnType{Type: Polynomial AlgebraicNumber}

\spadcommand{eval(r,x,a1 - a4) }
$$
0 
$$
\returnType{Type: Polynomial AlgebraicNumber}

\spadcommand{eval(r,x,a1 - a5) }
$$
\frac{{{405} \  {b \sp 8}}+
{{3450} \  {b \sp 6}} -
{{19875} \  {b \sp 4}} -
{{198000} \  {b \sp 2}} -
{588000}}{31} 
$$
\returnType{Type: Polynomial AlgebraicNumber}

Take one of the differences that was a root of $r(x)$ and assign it to
the variable $bb$.

For example, if $eval(r,x,a1 - a4)$ returned $0$, you would enter this.

\spadcommand{bb := a1 - a4  }
$$
\frac{\left(
\begin{array}{@{}l}
{{85} \  {b \sp 9}}+
{{402} \  {b \sp 8}} -
{{780} \  {b \sp 7}} -
{{6840} \  {b \sp 6}} -
{{14895} \  {b \sp 5}} -
{{12150} \  {b \sp 4}}+
\\
\\
\displaystyle
{{127050} \  {b \sp 3}}+
{{908100} \  {b \sp 2}}+
{{1074800} \  b} -
{3984000}
\end{array}
\right)}{1339200} 
$$
\returnType{Type: AlgebraicNumber}

Of course, if the difference is, in fact, equal to the root $beta$,
you should choose another root of $r(x)$.

%Original Page 302

Automorphisms of the splitting field are given by mapping a generator
of the field, namely $beta$, to other roots of its minimal polynomial.
Let's see what happens when $beta$ is mapped to $bb$.

We compute the images of the roots $a1,...,a5$ under this automorphism:

\spadcommand{aa1 := subst(a1,beta = bb)  }
$$
\frac{-{{143} \  {b \sp 8}}+
{{2100} \  {b \sp 6}}+
{{10485} \  {b \sp 4}}-
{{290550} \  {b \sp 2}}+
{{334800} \  b}+
{960800}}{669600} 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{aa2 := subst(a2,beta = bb)  }
$$
\frac{\left(
\begin{array}{@{}l}
-{{85} \  {b \sp 9}}+
{{116} \  {b \sp 8}}+
{{780} \  {b \sp 7}} -
{{2640} \  {b \sp 6}}+
{{14895} \  {b \sp 5}}+
{{8820} \  {b \sp 4}} -
\\
\\
\displaystyle
{{127050} \  {b \sp 3}}+
{{327000} \  {b \sp 2}} -
{{405200} \  b} -
{2062400}
\end{array}
\right)}{1339200} 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{aa3 := subst(a3,beta = bb)  }
$$
\frac{\left(
\begin{array}{@{}l}
{{85} \  {b \sp 9}}+
{{116} \  {b \sp 8}} -
{{780} \  {b \sp 7}} -
{{2640} \  {b \sp 6}} -
{{14895} \  {b \sp 5}}+
{{8820} \  {b \sp 4}}+
\\
\\
\displaystyle
{{127050} \  {b \sp 3}}+
{{327000} \  {b \sp 2}}+
{{405200} \  b} -
{2062400} 
\end{array}
\right)}{1339200} 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{aa4 := subst(a4,beta = bb)  }
$$
\frac{-{{143} \  {b \sp 8}}+
{{2100} \  {b \sp 6}}+
{{10485} \  {b \sp 4}}-
{{290550} \  {b \sp 2}} -
{{334800} \  b}+
{960800}}{669600} 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{aa5 := subst(a5,beta = bb)  }
$$
\frac{{{17} \  {b \sp 8}} -
{{156} \  {b \sp 6}} -
{{2979} \  {b \sp 4}}+
{{25410} \  {b \sp 2}}+
{14080}}{66960} 
$$
\returnType{Type: AlgebraicNumber}

Of course, the values $aa1,...,aa5$ are simply a permutation of the values
$a1,...,a5$.

Let's find the value of $aa1$ (execute as many of the following five commands
as necessary).

\spadcommand{(aa1 = a1) :: Boolean }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{(aa1 = a2) :: Boolean }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

%Original Page 303

\spadcommand{(aa1 = a3) :: Boolean }
$$
{\tt true}
$$
\returnType{Type: Boolean}

\spadcommand{(aa1 = a4) :: Boolean }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{(aa1 = a5) :: Boolean }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Proceeding in this fashion, you can find the values of
$aa2,...aa5$. You have represented the automorphism $beta -> bb$ as a
permutation of the roots $a1,...,a5$.  If you wish, you can repeat
this computation for all the roots of $r(x)$ and represent the Galois
group of $p(x)$ as a subgroup of the symmetric group on five letters.

Here are two other problems that you may attack in a similar fashion:
\begin{enumerate}
\item Show that the Galois group of
$p(x) = x^4 + 2 x^3 - 2 x^2 - 3 x + 1$
is the dihedral group of order eight. \index{group!dihedral}
(The splitting field of this polynomial is the Hilbert class field
\index{Hilbert class field} of \index{field!Hilbert class} the quadratic field
${\bf Q}(\sqrt{145})$.)
\item Show that the Galois group of
$p(x) = x^6 + 108$
has order 6 and is isomorphic to $S_3,$ the symmetric group on three letters.
\index{group!symmetric} (The splitting field of this polynomial is the 
splitting field of $x^3 - 2$.)
\end{enumerate}

\section{Non-Associative Algebras and Modelling Genetic Laws}
\label{ugProblemGenetic}

Many algebraic structures of mathematics and Axiom have a
multiplication operation {\tt *} that satisfies the associativity law
\index{associativity law} $a*(b*c) = (a*b)*c$ for all $a$, $b$ and
$c$.  The octonions are a well known exception.  There are many other
interesting non-associative structures, such as the class of
\index{Lie algebra} Lie algebras.\footnote{Two Axiom implementations
of Lie algebras are {\tt LieSquareMatrix} and {\tt FreeNilpotentLie}.}
Lie algebras can be used, for example, to analyse Lie symmetry
algebras of \index{symmetry} partial differential \index{differential
equation!partial} equations.  \index{partial differential equation} In
this section we show a different application of non-associative
algebras, \index{non-associative algebra} the modelling of genetic
laws.  \index{algebra!non-associative}

The Axiom library contains several constructors for creating
non-assoc\-i\-a\-tive structures, ranging from the categories 
{\tt Monad}, {\tt NonAssociativeRng}, and {\tt FramedNonAssociativeAlgebra}, 
to the domains {\tt AlgebraGivenByStructuralConstants} and 
{\tt GenericNonAssociativeAlgebra}.  Furthermore, the package 
{\tt AlgebraPackage} provides operations for analysing the structure of
such algebras.\footnote{% The interested reader can learn more about
these aspects of the Axiom library from the paper ``Computations in
Algebras of Finite Rank,'' by Johannes Grabmeier and Robert Wisbauer,
Technical Report, IBM Heidelberg Scientific Center, 1992.}

%Original Page 304

Mendel's genetic laws are often written in a form like

$$Aa \times Aa = {\frac{1}{4}}AA + {\frac{1}{2}}Aa + {\frac{1}{4}}aa$$

The implementation of general algebras in Axiom allows us to
\index{Mendel's genetic laws} use this as the definition for
multiplication in an algebra.  \index{genetics} Hence, it is possible
to study questions of genetic inheritance using Axiom.  To demonstrate
this more precisely, we discuss one example from a monograph of
A. W\"orz-Busekros, where you can also find a general setting of this
theory.\footnote{% W\"{o}rz-Busekros, A., {\it Algebras in Genetics},
Springer Lectures Notes in Biomathematics 36, Berlin e.a. (1980).  In
particular, see example 1.3.}

We assume that there is an infinitely large random mating population.
Random mating of two gametes $a_i$ and $a_j$ gives zygotes
\index{zygote} $a_ia_j$, which produce new gametes.  \index{gamete} In
classical Mendelian segregation we have 
$a_ia_j = {\frac{1}{2}}a_i+{\frac{1}{2}}a_j$.  In general, we have

$$a_ia_j = \sum_{k=1}^n \gamma_{i,j}^k\ a_k.$$

%{$ai aj = gammaij1 a1 + gammaij2 a2 + ... + gammaijn an$}

The segregation rates $\gamma_{i,j}$ are the structural constants of
an $n$-dimensional algebra.  This is provided in Axiom by the
constructor {\tt AlgebraGivenByStructuralConstants} (abbreviation 
{\tt ALGSC}).

Consider two coupled autosomal loci with alleles $A$, $a$, $B$, and
$b$, building four different gametes $a_1 = AB, a_2 = Ab, a_3 = aB,$
and $a_4 = ab$ {$a1 := AB, a2 := Ab, a3 := aB,$ and $a4 := ab$}.  The
zygotes $a_ia_j$ produce gametes $a_i$ and $a_j$ with classical
Mendelian segregation.  Zygote $a_1a_4$ undergoes transition to
$a_2a_3$ and vice versa with probability 
$0 \le \theta \le {\frac{1}{2}}$.

%Original Page 305

Define a list $[(\gamma_{i,j}^k) 1 \le k \le 4]$ of four four-by-four
matrices giving the segregation rates.  We use the value $1/10$ for
$\theta$.

\spadcommand{segregationRates : List SquareMatrix(4,FRAC INT) := [matrix [ [1, 1/2, 1/2, 9/20], [1/2, 0, 1/20, 0], [1/2, 1/20, 0, 0], [9/20, 0, 0, 0] ], matrix [ [0, 1/2, 0, 1/20], [1/2, 1, 9/20, 1/2], [0, 9/20, 0, 0], [1/20, 1/2, 0, 0] ], matrix [ [0, 0, 1/2, 1/20], [0, 0, 9/20, 0], [1/2, 9/20, 1, 1/2], [1/20, 0, 1/2, 0] ], matrix [ [0, 0, 0, 9/20], [0, 0, 1/20, 1/2], [0, 1/20, 0, 1/2], [9/20, 1/2, 1/2, 1] ] ] }
$$
\begin{array}{@{}l}
\left[
{\left[ 
\begin{array}{cccc}
1 & {\frac{1}{2}} & {\frac{1}{2}} & {\frac{9}{20}} \\ 
{\frac{1}{2}} & 0 & {\frac{1}{20}} & 0 \\ 
{\frac{1}{2}} & {\frac{1}{20}} & 0 & 0 \\ 
{\frac{9}{20}} & 0 & 0 & 0 
\end{array}
\right]},
{\left[ 
\begin{array}{cccc}
0 & {\frac{1}{2}} & 0 & {\frac{1}{20}} \\ 
{\frac{1}{2}} & 1 & {\frac{9}{20}} & {\frac{1}{2}} \\ 
0 & {\frac{9}{20}} & 0 & 0 \\ 
{\frac{1}{20}} & {\frac{1}{2}} & 0 & 0 
\end{array}
\right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ 
\begin{array}{cccc}
0 & 0 & {\frac{1}{2}} & {\frac{1}{20}} \\ 
0 & 0 & {\frac{9}{20}} & 0 \\ 
{\frac{1}{2}} & {\frac{9}{20}} & 1 & {\frac{1}{2}} \\ 
{\frac{1}{20}} & 0 & {\frac{1}{2}} & 0 
\end{array}
\right]},
{\left[ 
\begin{array}{cccc}
0 & 0 & 0 & {\frac{9}{20}} \\ 
0 & 0 & {\frac{1}{20}} & {\frac{1}{2}} \\ 
0 & {\frac{1}{20}} & 0 & {\frac{1}{2}} \\ 
{\frac{9}{20}} & {\frac{1}{2}} & {\frac{1}{2}} & 1 
\end{array}
\right]}
\right]
\end{array}
$$
\returnType{Type: List SquareMatrix(4,Fraction Integer)}

Choose the appropriate symbols for the basis of gametes,

\spadcommand{gametes := ['AB,'Ab,'aB,'ab]  }
$$
\left[
AB, Ab, aB, ab 
\right]
$$
\returnType{Type: List OrderedVariableList [AB,Ab,aB,ab]}

Define the algebra.

\spadcommand{A := ALGSC(FRAC INT, 4, gametes, segregationRates)}
$$
\begin{array}{@{}l}
{\rm AlgebraGivenByStructuralConstants(Fraction Integer, 4, }
\\
\displaystyle
{\rm [AB,Ab,aB,ab], [MATRIX,MATRIX,MATRIX,MATRIX])}
\end{array}
$$
\returnType{Type: Domain}

What are the probabilities for zygote $a_1a_4$ to produce the
different gametes?

\spadcommand{a := basis()\$A}
$$
\left[
AB, Ab, aB, ab 
\right]
$$
\returnType{Type: Vector 
AlgebraGivenByStructuralConstants(Fraction Integer,4,[AB,Ab,aB,ab],
[MATRIX,MATRIX,MATRIX,MATRIX])}

\spadcommand{a.1*a.4}
$$
{{\frac{9}{20}} \  ab}+
{{\frac{1}{20}} \  aB}+
{{\frac{1}{20}} \  Ab}+
{{\frac{9}{20}} \  AB} 
$$
\returnType{Type: 
AlgebraGivenByStructuralConstants(Fraction Integer,4,[AB,Ab,aB,ab],
[MATRIX,MATRIX,MATRIX,MATRIX])}

Elements in this algebra whose coefficients sum to one play a
distinguished role.  They represent a population with the distribution
of gametes reflected by the coefficients with respect to the basis of
gametes.

Random mating of different populations $x$ and $y$ is described by
their product $x*y$.

This product is commutative only if the gametes are not sex-dependent,
as in our example.

\spadcommand{commutative?()\$A }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%Original Page 306

In general, it is not associative.

\spadcommand{associative?()\$A }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Random mating within a population $x$ is described by $x*x$.  The next
generation is $(x*x)*(x*x)$.

Use decimal numbers to compare the distributions more easily.

\spadcommand{x : ALGSC(DECIMAL, 4, gametes, segregationRates) :=  convert [3/10, 1/5, 1/10, 2/5]}
$$
{{0.4} \  ab}+{{0.1} \  aB}+{{0.2} \  Ab}+{{0.3} \  AB} 
$$
\returnType{Type: 
AlgebraGivenByStructuralConstants(DecimalExpansion,4,[AB,Ab,aB,ab],
[MATRIX,MATRIX,MATRIX,MATRIX])}

To compute directly the gametic distribution in the fifth generation,
we use {\bf plenaryPower}.

\spadcommand{plenaryPower(x,5) }
$$
{{0.{36561}} \  ab}+{{0.{13439}} \  aB}+{{0.{23439}} \  Ab}+{{0.{26561}} \  
AB} 
$$
\returnType{Type: 
AlgebraGivenByStructuralConstants(DecimalExpansion,4,[AB,Ab,aB,ab],
[MATRIX,MATRIX,MATRIX,MATRIX])}

We now ask two questions: Does this distribution converge to an
equilibrium state?  What are the distributions that are stable?

This is an invariant of the algebra and it is used to answer the first
question.  The new indeterminates describe a symbolic distribution.

\spadcommand{q := leftRankPolynomial()\$GCNAALG(FRAC INT, 4, gametes, segregationRates) :: UP(Y, POLY FRAC INT)}
$$
\begin{array}{@{}l}
{Y \sp 3}+
{{\left( 
-{{\frac{29}{20}} \  \%x4} -
{{\frac{29}{20}} \  \%x3} -
{{\frac{29}{20}} \  \%x2} -
{{\frac{29}{20}} \  \%x1} 
\right)}\  {Y \sp 2}}+
\\
\\
\displaystyle
{
\left(
\begin{array}{@{}l}
\left( {{\frac{9}{20}} \  { \%x4 \sp 2}}+
{{\left( 
{{\frac{9}{10}} \  \%x3}+
{{\frac{9}{10}} \  \%x2}+
{{\frac{9}{10}} \  \%x1} 
\right)}\  \%x4}+
\right.
\\
\\
\displaystyle
{{\frac{9}{20}} \  { \%x3 \sp 2}}+
{{\left( {{\frac{9}{10}} \   \%x2}+{{\frac{9}{10}} \  \%x1} \right)}\  \%x3}+
{{\frac{9}{20}} \  { \%x2 \sp 2}}+
\\
\\
\displaystyle
\left.
{{\frac{9}{10}} \  \%x1 \   \%x2}+
{{\frac{9}{20}} \  { \%x1 \sp 2}} 
\right)
\end{array}
\right)
\  Y} 
\end{array}
$$
\returnType{Type: UnivariatePolynomial(Y,Polynomial Fraction Integer)}


Because the coefficient ${\frac{9}{20}}$ has absolute value less than 1,
all distributions do converge, by a theorem of this theory.

\spadcommand{factor(q :: POLY FRAC INT) }
$$
\begin{array}{@{}l}
{\left( Y - \%x4 - \%x3 - \%x2 - \%x1 \right)} *
\\
\\
\displaystyle
{\left( 
Y -
{{\frac{9}{20}} \  \%x4} -
{{\frac{9}{20}} \  \%x3} -
{{\frac{9}{20}} \  \%x2} -
{{\frac{9}{20}} \  \%x1} 
\right)}
\  Y 
\end{array}
$$
\returnType{Type: Factored Polynomial Fraction Integer}

%Original Page 307

The second question is answered by searching for idempotents in the algebra.

\spadcommand{cI := conditionsForIdempotents()\$GCNAALG(FRAC INT, 4, gametes, segregationRates) }
$$
\begin{array}{@{}l}
\left[
{{{\frac{9}{10}} \  \%x1 \  \%x4}+
{{\left( {{\frac{1}{10}} \  \%x2}+ \%x1 \right)}\  \%x3}+
{ \%x1 \  \%x2}+
{ \%x1 \sp 2} -
\%x1},
\right.
\\
\\
\displaystyle
{{{\left( \%x2+{{\frac{1}{10}} \  \%x1} \right)}\  \%x4}+
{{\frac{9}{10}} \  \%x2 \  \%x3}+
{ \%x2 \sp 2}+
{{\left( \%x1 -1 \right)}\  \%x2}},
\\
\\
\displaystyle
{{{\left( \%x3+{{\frac{1}{10}} \  \%x1} \right)}\  \%x4}+
{ \%x3 \sp 2}+
{{\left( {{\frac{9}{10}} \  \%x2}+ \%x1 -1 \right)}\  \%x3}},
\\
\\
\displaystyle
\left.
{{ \%x4 \sp 2}+
{{\left( \%x3+ \%x2+{{\frac{9}{10}} \  \%x1} -1 \right)}\  \%x4}+
{{\frac{1}{10}} \  \%x2 \  \%x3}} 
\right]
\end{array}
$$
\returnType{Type: List Polynomial Fraction Integer}

Solve these equations and look at the first solution.

\spadcommand{gbs:= groebnerFactorize cI}
$$
\begin{array}{@{}l}
\left[
\begin{array}{@{}l}
\left[ { \%x4+ \%x3+ \%x2+ \%x1 -1}, 
\right.
\\
\displaystyle
\left.
\ \ {{{\left( \%x2+ \%x1 \right)}\  \%x3}+
{ \%x1 \  \%x2}+{ \%x1 \sp 2} - \%x1} 
\right],
\end{array}
\right.
\\
\\
\displaystyle
{\left[ 1 \right]},
{\left[ { \%x4+ \%x3 -1}, \%x2, \%x1 \right]},
\\
\\
\displaystyle
{\left[ { \%x4+ \%x2 -1}, \%x3, \%x1 \right]},
{\left[ \%x4, \%x3, \%x2, \%x1 \right]},
\\
\\
\displaystyle
\left.
{\left[ { \%x4 -1}, \%x3, \%x2, \%x1 \right]},
{\left[ { \%x4 -{\frac{1}{2}}}, { \%x3 -{\frac{1}{2}}}, \%x2, \%x1 \right]}
\right]
\end{array}
$$
\returnType{Type: List List Polynomial Fraction Integer}

\spadcommand{gbs.1}
$$
\begin{array}{@{}l}
\left[
{ \%x4+ \%x3+ \%x2+ \%x1 -1}, 
\right.
\\
\displaystyle
\left.
{{{\left( \%x2+ \%x1 \right)}\  \%x3}+{ \%x1 \  \%x2}+{ \%x1 \sp 2} - \%x1} 
\right]
\end{array}
$$
\returnType{Type: List Polynomial Fraction Integer}


Further analysis using the package {\tt PolynomialIdeals} shows that
there is a two-dimensional variety of equilibrium states and all other
solutions are contained in it.

Choose one equilibrium state by setting two indeterminates to concrete
values.

\spadcommand{sol := solve concat(gbs.1,[\%x1-1/10,\%x2-1/10]) }
$$
\left[
{\left[ 
{ \%x4={\frac{2}{5}}}, 
{ \%x3={\frac{2}{5}}}, 
{ \%x2={\frac{1}{10}}}, 
{ \%x1={\frac{1}{10}}} 
\right]}
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

\spadcommand{e : A := represents reverse (map(rhs, sol.1) :: List FRAC INT) }
$$
{{\frac{2}{5}} \  ab}+
{{\frac{2}{5}} \  aB}+
{{\frac{1}{10}} \  Ab}+
{{\frac{1}{10}} \  AB} 
$$
\returnType{Type: 
AlgebraGivenByStructuralConstants(Fraction Integer,4,[AB,Ab,aB,ab],
[MATRIX,MATRIX,MATRIX,MATRIX])}

Verify the result.

\spadcommand{e*e-e }
$$
0 
$$
\returnType{Type: 
AlgebraGivenByStructuralConstants(Fraction Integer,4,[AB,Ab,aB,ab],
[MATRIX,MATRIX,MATRIX,MATRIX])}


%Original Page 309

%%\setcounter{chapter}{9} % Chapter 10
\chapter{Some Examples of Domains and Packages}
In this chapter we show examples of many of the most commonly used
Axiom domains and packages. The sections are organized by constructor
names.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{ApplicationProgramInterface}

The ApplicationProgramInterface exposes Axiom internal functions
which might be useful for understanding, debugging, or creating tools.

The getDomains function takes the name of a category and returns
a set of domains which inherit from that category:
\begin{verbatim}
  getDomains 'Collection

   {AssociationList, Bits, CharacterClass, DataList, EqTable, 
    FlexibleArray, GeneralPolynomialSet, GeneralSparseTable, 
    GeneralTriangularSet, HashTable, IndexedBits, 
    IndexedFlexibleArray, IndexedList, IndexedOneDimensionalArray,
    IndexedString, IndexedVector, InnerTable, KeyedAccessFile, 
    Library, List, ListMultiDictionary, Multiset, OneDimensionalArray, 
    Point, PrimitiveArray, RegularChain, RegularTriangularSet, 
    Result, RoutinesTable, Set, SparseTable, 
    SquareFreeRegularTriangularSet, Stream, String, StringTable, 
    Table, Vector, WuWenTsunTriangularSet}
                                                             
\end{verbatim}
\returnType{Type: Set Symbol}
This can be used to form the set-difference of two categories:
\begin{verbatim}
  difference(getDomains 'IndexedAggregate, getDomains 'Collection)

   {DirectProduct, DirectProductMatrixModule, DirectProductModule,
    HomogeneousDirectProduct, OrderedDirectProduct,
    SplitHomogeneousDirectProduct}
                                                             
\end{verbatim}
\returnType{Type: Set Symbol}
The credits function prints a list of the people who have contributed
to the development of Axiom. This is equivalent to the )credits command.

The summary function prints a short list of useful console commands.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{ArrayStack}

An ArrayStack object is represented as a list ordered by last-in,
first-out. It operates like a pile of books, where the ``next'' book is
the one on the top of the pile.

Here we create an array stack of integers from a list. Notice that the
order in the list is the order in the stack.
\begin{verbatim}
   a:ArrayStack INT:= arrayStack [1,2,3,4,5]
      [1,2,3,4,5]
\end{verbatim}
We can remove the top of the stack using pop!:
\begin{verbatim}
   pop! a
      1
\end{verbatim}
Notice that the use of pop! is destructive (destructive operations
in Axiom usually end with ! to indicate that the underylying data
structure is changed).
\begin{verbatim}
   a
      [2,3,4,5]
\end{verbatim}
The extract! operation is another name for the pop! operation and
has the same effect. This operation treats the stack as a BagAggregate:
\begin{verbatim}
   extract! a
      2
\end{verbatim}
and you can see that it also has destructively modified the stack:
\begin{verbatim}
   a
      [3,4,5]
\end{verbatim}
Next we push a new element on top of the stack:
\begin{verbatim}
   push!(9,a)
      9
\end{verbatim}
Again, the push! operation is destructive so the stack is changed:
\begin{verbatim}
   a
      [9,3,4,5]
\end{verbatim}
Another name for push! is insert!, which treats the stack as a BagAggregate:
\begin{verbatim}
   insert!(8,a)
      [8,9,3,4,5]
\end{verbatim}
and it modifies the stack:
\begin{verbatim}
   a
      [8,9,3,4,5]
\end{verbatim}
The inspect function returns the top of the stack without modification,
viewed as a BagAggregate:
\begin{verbatim}
   inspect a
      8
\end{verbatim}
The empty? operation returns true only if there are no element on the
stack, otherwise it returns false:
\begin{verbatim}
   empty? a
      false
\end{verbatim}
The top operation returns the top of stack without modification, viewed
as a Stack:
\begin{verbatim}
   top a
      8
\end{verbatim}
The depth operation returns the number of elements on the stack:
\begin{verbatim}
   depth a
      5
\end{verbatim}
which is the same as the \# (length) operation:
\begin{verbatim}
   #a
       5
\end{verbatim}
The less? predicate will compare the stack length to an integer:
\begin{verbatim}
   less?(a,9)
        true
\end{verbatim}
The more? predicate will compare the stack length to an integer:
\begin{verbatim}
   more?(a,9)
        false
\end{verbatim}
The size? operation will compare the stack length to an integer:
\begin{verbatim}
   size?(a,#a)
        true
\end{verbatim}
and since the last computation must alwasy be true we try:
\begin{verbatim}
   size?(a,9)
        false
\end{verbatim}
The parts function will return  the stack as a list of its elements:
\begin{verbatim}
   parts a
        [8,9,3,4,5]
\end{verbatim}
If we have a BagAggregate of elements we can use it to construct a stack.
Notice that the elements are pushed in reverse order:
\begin{verbatim}
   bag([1,2,3,4,5])$ArrayStack(INT)
        [5,4,3,2,1]
\end{verbatim}
The empty function will construct an empty stack of a given type:
\begin{verbatim}
   b:=empty()$(ArrayStack INT)
        []
\end{verbatim}
and the empty? predicate allows us to find out if a stack is empty:
\begin{verbatim}
   empty? b
        true
\end{verbatim}
The sample function returns a sample, empty stack:
\begin{verbatim}
   sample()$ArrayStack(INT)
        []
\end{verbatim}
We can copy a stack and it does not share storage so subsequent
modifications of the original stack will not affect the copy:
\begin{verbatim}
   c:=copy a
        [8,9,3,4,5]
\end{verbatim}
The eq? function is only true if the lists are the same reference,
so even though c is a copy of a, they are not the same:
\begin{verbatim}
   eq?(a,c)
        false
\end{verbatim}
However, a clearly shares a reference with itself:
\begin{verbatim}
   eq?(a,a)
        true
\end{verbatim}
But we can compare a and c for equality:
\begin{verbatim}
   (a=c)@Boolean
        true
\end{verbatim}
and clearly a is equal to itself:
\begin{verbatim}
   (a=a)@Boolean
        true
\end{verbatim}
and since a and c are equal, they are clearly NOT not-equal:
\begin{verbatim}
   a~=c
        false
\end{verbatim}
We can use the any? function to see if a predicate is true for any element:
\begin{verbatim}
   any?(x+->(x=4),a)
        true
\end{verbatim}
or false for every element:
\begin{verbatim}
   any?(x+->(x=11),a)
        false
\end{verbatim}
We can use the every? function to check every element satisfies a predicate:
\begin{verbatim}
   every?(x+->(x=11),a)
        false
\end{verbatim}
We can count the elements that are equal to an argument of this type:
\begin{verbatim}
   count(4,a)
        1
\end{verbatim}
or we can count against a boolean function:
\begin{verbatim}
   count(x+->(x>2),a)
        5
\end{verbatim}
You can also map a function over every element, returning a new stack:
\begin{verbatim}
   map(x+->x+10,a)
        [18,19,13,14,15]
\end{verbatim}
Notice that the orignal stack is unchanged:
\begin{verbatim}
   a
        [8,9,3,4,5]
\end{verbatim}
You can use map! to map a function over every element and change
the original stack since map! is destructive:
\begin{verbatim}
   map!(x+->x+10,a)
       [18,19,13,14,15]
\end{verbatim}
Notice that the orignal stack has been changed:
\begin{verbatim}
   a
       [18,19,13,14,15]
\end{verbatim}
The member function can also get the element of the stack as a list:
\begin{verbatim}
   members a
       [18,19,13,14,15]
\end{verbatim}
and using member? we can test if the stack holds a given element:
\begin{verbatim}
   member?(14,a)
       true
\end{verbatim}
Also see \domainref{Stack}, \domainref{Queue}, \domainref{Dequeue} and
\domainref{Heap}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{AssociationList}

The {\tt AssociationList} constructor provides a general structure for
associative storage.  This type provides association lists in which
data objects can be saved according to keys of any type.  For a given
association list, specific types must be chosen for the keys and
entries.  You can think of the representation of an association list
as a list of records with key and entry fields.

Association lists are a form of table and so most of the operations
available for {\tt Table} are also available for {\tt AssociationList}.  
They can also be viewed as lists and can be manipulated accordingly.

This is a {\tt Record} type with age and gender fields.

\spadcommand{Data := Record(monthsOld : Integer, gender : String)}
$$
\mbox{\rm Record(monthsOld: Integer,gender: String)} 
$$
\returnType{Type: Domain}

%Original Page 310

In this expression, {\tt al} is declared to be an association
list whose keys are strings and whose entries are the above records.

\spadcommand{al : AssociationList(String,Data)}
\returnType{Type: Void}

The \spadfunFrom{table}{AssociationList} operation is used to create
an empty association list.

\spadcommand{al := table()}
$$
table() 
$$
\returnType{Type: 
AssociationList(String,Record(monthsOld: Integer,gender: String))}

You can use assignment syntax to add things to the association list.

\spadcommand{al."bob" := [407,"male"]\$Data}
$$
\left[
{monthsOld={407}}, {gender= \mbox{\tt "male"} } 
\right]
$$
\returnType{Type: Record(monthsOld: Integer,gender: String)}

\spadcommand{al."judith" := [366,"female"]\$Data}
$$
\left[
{monthsOld={366}}, {gender= \mbox{\tt "female"} } 
\right]
$$
\returnType{Type: Record(monthsOld: Integer,gender: String)}

\spadcommand{al."katie" := [24,"female"]\$Data}
$$
\left[
{monthsOld={24}}, {gender= \mbox{\tt "female"} } 
\right]
$$
\returnType{Type: Record(monthsOld: Integer,gender: String)}

Perhaps we should have included a species field.

\spadcommand{al."smokie" := [200,"female"]\$Data}
$$
\left[
{monthsOld={200}}, {gender= \mbox{\tt "female"} } 
\right]
$$
\returnType{Type: Record(monthsOld: Integer,gender: String)}

Now look at what is in the association list.  Note that the last-added
(key, entry) pair is at the beginning of the list.

\spadcommand{al}
$$
\begin{array}{@{}l}
table 
\left(
{ \mbox{\tt "smokie"} =
{\left[ {monthsOld={200}}, {gender= \mbox{\tt "female"} } \right]}},
\right.
\\
\\
\displaystyle
\ \ \ \ \ \ \ \ { \mbox{\tt "katie"} =
{\left[ {monthsOld={24}}, {gender= \mbox{\tt "female"} } \right]}},
\\
\\
\displaystyle
\ \ \ \ \ \ \ \ { \mbox{\tt "judith"} =
{\left[ {monthsOld={366}}, {gender= \mbox{\tt "female"} } \right]}},
\\
\\
\displaystyle
\left.
\ \ \ \ \ \ \ \ { \mbox{\tt "bob"} =
{\left[ {monthsOld={407}}, {gender= \mbox{\tt "male"} } \right]}}
\right)
\end{array}
$$
\returnType{Type: 
AssociationList(String,Record(monthsOld: Integer,gender: String))}

You can reset the entry for an existing key.

\spadcommand{al."katie" := [23,"female"]\$Data}
$$
\left[
{monthsOld={23}}, {gender= \mbox{\tt "female"} } 
\right]
$$
\returnType{Type: Record(monthsOld: Integer,gender: String)}

Use \spadfunFrom{delete!}{AssociationList} to destructively remove an
element of the association list.  Use
\spadfunFrom{delete}{AssociationList} to return a copy of the
association list with the element deleted.  The second argument is the
index of the element to delete.

\spadcommand{delete!(al,1)}
$$
\begin{array}{@{}l}
table 
\left(
{ \mbox{\tt "katie"} =
{\left[ {monthsOld={23}}, {gender= \mbox{\tt "female"} } \right]}},
\right.
\\
\\
\displaystyle
\ \ \ \ \ \ \ \ { \mbox{\tt "judith"} =
{\left[ {monthsOld={366}}, {gender= \mbox{\tt "female"} } \right]}},
\\
\\
\displaystyle
\left.
\ \ \ \ \ \ \ \ { \mbox{\tt "bob"} =
{\left[ {monthsOld={407}}, {gender= \mbox{\tt "male"} } \right]}}
\right)
\end{array}
$$
\returnType{Type: 
AssociationList(String,Record(monthsOld: Integer,gender: String))}

For more information about tables, see \domainref{Table}.
For more information about lists, see \domainref{List}.

%Original Page 311

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{BalancedBinaryTree}

{\tt BalancedBinaryTrees(S)} is the domain of balanced binary trees
with elements of type {\tt S} at the nodes.  A binary tree is either
{\tt empty} or else consists of a {\tt node} having a {\tt value} and
two branches, each branch a binary tree.  A balanced binary tree is
one that is balanced with respect its leaves.  One with $2^k$ leaves
is perfectly ``balanced'': the tree has minimum depth, and the {\tt
left} and {\tt right} branch of every interior node is identical in
shape.

Balanced binary trees are useful in algebraic computation for
so-called ``divide-and-conquer'' algorithms.  Conceptually, the data
for a problem is initially placed at the root of the tree.  The
original data is then split into two subproblems, one for each
subtree.  And so on.  Eventually, the problem is solved at the leaves
of the tree.  A solution to the original problem is obtained by some
mechanism that can reassemble the pieces.  In fact, an implementation
of the Chinese Remainder Algorithm using balanced binary trees was
first proposed by David Y. Y.  Yun at the IBM T. J.  Watson Research
Center in Yorktown Heights, New York, in 1978.  It served as the
prototype for polymorphic algorithms in Axiom.

In what follows, rather than perform a series of computations with a
single expression, the expression is reduced modulo a number of
integer primes, a computation is done with modular arithmetic for each
prime, and the Chinese Remainder Algorithm is used to obtain the
answer to the original problem.  We illustrate this principle with the
computation of $12^2 = 144$.

A list of moduli.

\spadcommand{lm := [3,5,7,11]}
$$
\left[
3, 5, 7,  {11} 
\right]
$$
\returnType{Type: List PositiveInteger}

The expression {\tt modTree(n, lm)} creates a balanced binary tree
with leaf values {\tt n mod m} for each modulus {\tt m} in {\tt lm}.

\spadcommand{modTree(12,lm)}
$$
\left[
0, 2, 5, 1 
\right]
$$
\returnType{Type: List Integer}

Operation {\tt modTree} does this using operations on balanced binary
trees.  We trace its steps.  Create a balanced binary tree {\tt t} of
zeros with four leaves.

\spadcommand{t := balancedBinaryTree(\#lm, 0)}
$$
\left[
{\left[ 0, 0, 0 \right]}, 0, {\left[ 0, 0, 0\right]}
\right]
$$
\returnType{Type: BalancedBinaryTree NonNegativeInteger}

The leaves of the tree are set to the individual moduli.

\spadcommand{setleaves!(t,lm)}
$$
\left[
{\left[ 3, 0, 5\right]}, 0, {\left[ 7, 0, {11} \right]}
\right]
$$
\returnType{Type: BalancedBinaryTree NonNegativeInteger}

%Original Page 312

Use {\tt mapUp!} to do a bottom-up traversal of {\tt t}, setting each
interior node to the product of the values at the nodes of its
children.

\spadcommand{mapUp!(t,\_*)}
$$
1155 
$$
\returnType{Type: PositiveInteger}

The value at the node of every subtree is the product of the moduli
of the leaves of the subtree.

\spadcommand{t}
$$
\left[
{\left[ 3, {15}, 5\right]}, {1155}, {\left[ 7, {77}, {11} \right]}
\right]
$$
\returnType{Type: BalancedBinaryTree NonNegativeInteger}

Operation {\tt mapDown!}{\tt (t,a,fn)} replaces the value {\tt v} at
each node of {\tt t} by {\tt fn(a,v)}.

\spadcommand{mapDown!(t,12,\_rem)}
$$
\left[
{\left[ 0, {12}, 2\right]}, {12}, {\left[ 5, {12}, 1 \right]}
\right]
$$
\returnType{Type: BalancedBinaryTree NonNegativeInteger}

The operation {\tt leaves} returns the leaves of the resulting tree.
In this case, it returns the list of {\tt 12 mod m} for each modulus
{\tt m}.

\spadcommand{leaves \%}
$$
\left[
0, 2, 5, 1 
\right]
$$
\returnType{Type: List NonNegativeInteger}

Compute the square of the images of {\tt 12} modulo each {\tt m}.

\spadcommand{squares := [x**2 rem m for x in \% for m in lm]}
$$
\left[
0, 4, 4, 1 
\right]
$$
\returnType{Type: List NonNegativeInteger}

Call the Chinese Remainder Algorithm to get the answer for $12^2$.

\spadcommand{chineseRemainder(\%,lm)}
$$
144 
$$
\returnType{Type: PositiveInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{BasicOperator}

A basic operator is an object that can be symbolically applied to a
list of arguments from a set, the result being a kernel over that set
or an expression.  In addition to this section, please see
\domainref{Expression} and \domainref{Kernel} for additional
information and examples.

You create an object of type {\tt BasicOperator} by using the
\spadfunFrom{operator}{BasicOperator} operation.  This first form of
this operation has one argument and it must be a symbol.  The symbol
should be quoted in case the name has been used as an identifier to
which a value has been assigned.

A frequent application of {\tt BasicOperator} is the creation of an
operator to represent the unknown function when solving a differential
equation.

Let {\tt y} be the unknown function in terms of {\tt x}.

\spadcommand{y := operator 'y}
$$
y 
$$
\returnType{Type: BasicOperator}

This is how you enter the equation {\tt y'' + y' + y = 0}.

\spadcommand{deq := D(y x, x, 2) + D(y x, x) + y x = 0}
$$
{{{y \sb {{\ }} \sp {,,}} \left({x} \right)}+
{{y\sb {{\ }} \sp {,}} \left({x} \right)}+
{y\left({x} \right)}}=0
$$
\returnType{Type: Equation Expression Integer}

To solve the above equation, enter this.

\spadcommand{solve(deq, y, x)}
$$
\left[
{particular=0}, 
{basis={\left[ {{\cos \left({{\frac{x \  {\sqrt {3}}}{2}}} \right)}
\  {e \sp {\left( -{\frac{x}{2}} \right)}}},
{{e \sp {\left( -{\frac{x}{2}} \right)}}
\  {\sin \left({{\frac{x \  {\sqrt {3}}}{2}}} \right)}}
\right]}}
\right]
$$
\returnType{Type: Union(Record(particular: Expression Integer,
basis: List Expression Integer),...)}

See \sectionref{ugProblemDEQ}
for this kind of use of {\tt BasicOperator}.

Use the single argument form of \spadfunFrom{operator}{BasicOperator}
(as above) when you intend to use the operator to create functional
expressions with an arbitrary number of arguments

{\it Nary} means an arbitrary number of arguments can be used
in the functional expressions.

\spadcommand{nary? y}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{unary? y}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Use the two-argument form when you want to restrict the number of
arguments in the functional expressions created with the operator.

This operator can only be used to create functional expressions
with one argument.

\spadcommand{opOne := operator('opOne, 1)}
$$
opOne 
$$
\returnType{Type: BasicOperator}

\spadcommand{nary? opOne}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{unary? opOne}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Use \spadfunFrom{arity}{BasicOperator} to learn the number of arguments 
that can be used.  It returns {\tt "false"} if the operator is nary.

\spadcommand{arity opOne}
$$
1 
$$
\returnType{Type: Union(NonNegativeInteger,...)}

Use \spadfunFrom{name}{BasicOperator} to learn the name of an operator.

\spadcommand{name opOne}
$$
opOne 
$$
\returnType{Type: Symbol}

Use \spadfunFrom{is?}{BasicOperator} to learn if an operator has a
particular name.

\spadcommand{is?(opOne, 'z2)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

You can also use a string as the name to be tested against.

\spadcommand{is?(opOne, "opOne")}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

You can attached named properties to an operator.  These are rarely
used at the top-level of the Axiom interactive environment but are
used with Axiom library source code.

By default, an operator has no properties.

\spadcommand{properties y}
$$
table() 
$$
\returnType{Type: AssociationList(String,None)}

The interface for setting and getting properties is somewhat awkward
because the property values are stored as values of type {\tt None}.

Attach a property by using \spadfunFrom{setProperty}{BasicOperator}.

\spadcommand{setProperty(y, "use", "unknown function" :: None )}
$$
y 
$$
\returnType{Type: BasicOperator}

\spadcommand{properties y}
$$
table 
\left(
{{ \mbox{\tt "use"} =NONE}} 
\right)
$$
\returnType{Type: AssociationList(String,None)}

We {\it know} the property value has type {\tt String}.

\spadcommand{property(y, "use") :: None pretend String}
$$
\mbox{\tt "unknown function"} 
$$
\returnType{Type: String}

Use \spadfunFrom{deleteProperty!}{BasicOperator} to destructively
remove a property.

\spadcommand{deleteProperty!(y, "use")}
$$
y 
$$
\returnType{Type: BasicOperator}

\spadcommand{properties y}
$$
table() 
$$
\returnType{Type: AssociationList(String,None)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{BinaryExpansion}

All rational numbers have repeating binary expansions.  Operations to
access the individual bits of a binary expansion can be obtained by
converting the value to {\tt RadixExpansion(2)}.  More examples of
expansions are available in \domainref{DecimalExpansion},\\ 
\domainref{HexadecimalExpansion}, and \domainref{RadixExpansion}.

The expansion (of type {\tt BinaryExpansion}) of a rational number
is returned by the \spadfunFrom{binary}{BinaryExpansion} operation.

\spadcommand{r := binary(22/7)}
$$
{11}.{\overline {001}} 
$$
\returnType{Type: BinaryExpansion}

Arithmetic is exact.

\spadcommand{r + binary(6/7)}
$$
100 
$$
\returnType{Type: BinaryExpansion}

%Original Page 313

The period of the expansion can be short or long \ldots

\spadcommand{[binary(1/i) for i in 102..106] }
$$
\begin{array}{@{}l}
\left[
{0.0{\overline {00000101}}}, 
{0.{\overline {000000100111110001000101100101111001110010010101001}}},
\right.
\\
\\
\displaystyle
{0.{000}{\overline {000100111011}}},
{0.{\overline {000000100111}}},
\\
\\
\displaystyle
\left.
{0.0{\overline {0000010011010100100001110011111011001010110111100011}}} 
\right]
\end{array}
$$
\returnType{Type: List BinaryExpansion}

or very long.

\spadcommand{binary(1/1007) }
$$
\begin{array}{@{}l}
0.
\overline 
{000000000100000100010100100101111000001111110000101111110010110001111101}
\\
\displaystyle
\ \ \overline 
{000100111001001100110001100100101010111101101001100000000110000110011110}
\\
\displaystyle
\ \ \overline 
{111000110100010111101001000111101100001010111011100111010101110011001010}
\\
\displaystyle
\ \ \overline 
{010111000000011100011110010000001001001001101110010101001110100011011101}
\\
\displaystyle
\ \ \overline 
{101011100010010000011001011011000000101100101111100010100000101010101101}
\\
\displaystyle
\ \ \overline 
{011000001101101110100101011111110101110101001100100001010011011000100110}
\\
\displaystyle
\ \ \overline 
{001000100001000011000111010011110001}
\end{array}
$$
\returnType{Type: BinaryExpansion}

These numbers are bona fide algebraic objects.

\spadcommand{p := binary(1/4)*x**2 + binary(2/3)*x + binary(4/9)}
$$
{{0.{01}} \  {x \sp 2}}+{{0.{\overline {10}}} \  x}+{0.{\overline {011100}}} 
$$
\returnType{Type: Polynomial BinaryExpansion}

\spadcommand{q := D(p, x)}
$$
{{0.1} \  x}+{0.{\overline {10}}} 
$$
\returnType{Type: Polynomial BinaryExpansion}

\spadcommand{g := gcd(p, q)}
$$
x+{1.{\overline {01}}} 
$$
\returnType{Type: Polynomial BinaryExpansion}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{BinarySearchTree}

{\tt BinarySearchTree(R)} is the domain of binary trees with elements
of type {\tt R}, ordered across the nodes of the tree.  A non-empty
binary search tree has a value of type {\tt R}, and {\tt right} and
{\tt left} binary search subtrees.  If a subtree is empty, it is
displayed as a period (``.'').

Define a list of values to be placed across the tree.  The resulting
tree has {\tt 8} at the root; all other elements are in the left
subtree.

\spadcommand{lv := [8,3,5,4,6,2,1,5,7]}
$$
\left[
8, 3, 5, 4, 6, 2, 1, 5, 7 
\right]
$$
\returnType{Type: List PositiveInteger}

%Original Page 311314

A convenient way to create a binary search tree is to apply the
operation {\tt binarySearchTree} to a list of elements.

\spadcommand{t := binarySearchTree lv}
$$
\left[
{\left[ {\left[ 1, 2, . \right]}, 3, 
{\left[ 4, 5, {\left[ 5, 6, 7 \right]}\right]}
\right]},
8, . 
\right]
$$
\returnType{Type: BinarySearchTree PositiveInteger}

Another approach is to first create an empty binary search tree of integers.

\spadcommand{emptybst := empty()\$BSTREE(INT)}
$$
[\ ] 
$$
\returnType{Type: BinarySearchTree Integer}

Insert the value {\tt 8}.  This establishes {\tt 8} as the root of the
binary search tree.  Values inserted later that are less than {\tt 8}
get stored in the {\tt left} subtree, others in the {\tt right} subtree.

\spadcommand{t1 := insert!(8,emptybst)}
$$
8 
$$
\returnType{Type: BinarySearchTree Integer}

Insert the value {\tt 3}. This number becomes the root of the {\tt
left} subtree of {\tt t1}.  For optimal retrieval, it is thus
important to insert the middle elements first.

\spadcommand{insert!(3,t1)}
$$
\left[3, 8, . \right]
$$
\returnType{Type: BinarySearchTree Integer}

We go back to the original tree {\tt t}.  The leaves of the binary
search tree are those which have empty {\tt left} and {\tt right} subtrees.

\spadcommand{leaves t}
$$
\left[
1, 4, 5, 7 
\right]
$$
\returnType{Type: List PositiveInteger}

The operation {\tt split}{\tt (k,t)} returns a \index{record}
containing the two subtrees: one with all elements ``less'' than 
{\tt k}, another with elements ``greater'' than {\tt k}.

\spadcommand{split(3,t)}
$$
\left[
{less={\left[ 1, 2, . \right]}},
{greater={\left[ {\left[ ., 3, 
{\left[ 4, 5, 
{\left[ 5, 6, 7 \right]}
\right]}
\right]},
8, . 
\right]}}
\right]
$$
\returnType{Type: 
Record(less: BinarySearchTree PositiveInteger,greater: 
BinarySearchTree PositiveInteger)}

Define {\tt insertRoot} to insert new elements by creating a new node.

\spadcommand{insertRoot: (INT,BSTREE INT) -> BSTREE INT}
\returnType{Type: Void}

The new node puts the inserted value between its ``less'' tree and
``greater'' tree.

\begin{verbatim}
insertRoot(x, t) ==
    a := split(x, t)
    node(a.less, x, a.greater)
\end{verbatim}

Function {\tt buildFromRoot} builds a binary search tree from a list
of elements {\tt ls} and the empty tree {\tt emptybst}.

\spadcommand{buildFromRoot ls == reduce(insertRoot,ls,emptybst)}
\returnType{Type: Void}

Apply this to the reverse of the list {\tt lv}.

\spadcommand{rt := buildFromRoot reverse lv}
$$
\left[
{\left[ {\left[ 1, 2, . \right]}, 3, 
{\left[ 4, 5, {\left[ 5, 6, 7\right]}\right]}
\right]},
8, . 
\right]
$$
\returnType{Type: BinarySearchTree Integer}

%Original Page 315

Have Axiom check that these are equal.

\spadcommand{(t = rt)@Boolean}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{CardinalNumber}

The {\tt CardinalNumber} domain can be used for values indicating the
cardinality of sets, both finite and infinite.  For example, the
\spadfunFrom{dimension}{VectorSpace} operation in the category 
{\tt VectorSpace} returns a cardinal number.

The non-negative integers have a natural construction as cardinals
\begin{verbatim}
0 = #{ }, 1 = {0}, 2 = {0, 1}, ..., n = {i | 0 <= i < n}.
\end{verbatim}

The fact that {\tt 0} acts as a zero for the multiplication of cardinals is
equivalent to the axiom of choice.

Cardinal numbers can be created by conversion from non-negative integers.

\spadcommand{c0 := 0 :: CardinalNumber}
$$
0 
$$
\returnType{Type: CardinalNumber}

\spadcommand{c1 := 1 :: CardinalNumber}
$$
1 
$$
\returnType{Type: CardinalNumber}

\spadcommand{c2 := 2 :: CardinalNumber}
$$
2 
$$
\returnType{Type: CardinalNumber}

\spadcommand{c3 := 3 :: CardinalNumber}
$$
3 
$$
\returnType{Type: CardinalNumber}

They can also be obtained as the named cardinal {\tt Aleph(n)}.

\spadcommand{A0 := Aleph 0}
$$
Aleph 
\left(
{0} 
\right)
$$
\returnType{Type: CardinalNumber}

\spadcommand{A1 := Aleph 1}
$$
Aleph 
\left(
{1} 
\right)
$$
\returnType{Type: CardinalNumber}

The \spadfunFrom{finite?}{CardinalNumber} operation tests whether a
value is a finite cardinal, that is, a non-negative integer.

\spadcommand{finite? c2}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%Original Page 316

\spadcommand{finite? A0}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Similarly, the \spadfunFrom{countable?}{CardinalNumber}
operation determines whether a value is
a countable cardinal, that is, finite or {\tt Aleph(0)}.

\spadcommand{countable? c2}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{countable? A0}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{countable? A1}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Arithmetic operations are defined on cardinal numbers as follows:
If {\tt x = \#X}  and  {\tt y = \#Y} then

\noindent
$
\begin{array}{lr}
{\tt x+y  = \#(X+Y)}  & cardinality of the disjoint union\\
{\tt x-y  = \#(X-Y)}  & cardinality of the relative complement \\
{\tt x*y  = \#(X*Y)}  & cardinality of the Cartesian product \\
{\tt x**y = \#(X**Y)} & 
cardinality of the set of maps from {\tt Y} to {\tt X} \\
\end{array}
$

Here are some arithmetic examples.

\spadcommand{[c2 + c2, c2 + A1]}
$$
\left[4, {Aleph \left({1} \right)}\right]
$$
\returnType{Type: List CardinalNumber}

\spadcommand{[c0*c2, c1*c2, c2*c2, c0*A1, c1*A1, c2*A1, A0*A1]}
$$
\left[
0, 2, 4, 0, {Aleph \left({1} \right)},
{Aleph \left({1} \right)},
{Aleph \left({1} \right)}
\right]
$$
\returnType{Type: List CardinalNumber}

\spadcommand{[c2**c0, c2**c1, c2**c2, A1**c0, A1**c1, A1**c2]}
$$
\left[
1, 2, 4, 1, {Aleph \left({1} \right)},
{Aleph \left({1} \right)}
\right]
$$
\returnType{Type: List CardinalNumber}

Subtraction is a partial operation: it is not defined
when subtracting a larger cardinal from a smaller one, nor
when subtracting two equal infinite cardinals.

\spadcommand{[c2-c1, c2-c2, c2-c3, A1-c2, A1-A0, A1-A1]}
$$
\left[
1, 0, \mbox{\tt "failed"} , {Aleph \left({1} \right)},
{Aleph \left({1} \right)},
\mbox{\tt "failed"} 
\right]
$$
\returnType{Type: List Union(CardinalNumber,"failed")}

The generalized continuum hypothesis asserts that
\begin{verbatim}
2**Aleph i = Aleph(i+1)
\end{verbatim}

%Original Page 317

and is independent of the axioms of set theory.\footnote{Goedel,
{\it The consistency of the continuum hypothesis,}
Ann. Math. Studies, Princeton Univ. Press, 1940.}

The {\tt CardinalNumber} domain provides an operation to assert
whether the hypothesis is to be assumed.

\spadcommand{generalizedContinuumHypothesisAssumed true}

When the generalized continuum hypothesis
is assumed, exponentiation to a transfinite power is allowed.

\spadcommand{[c0**A0, c1**A0, c2**A0, A0**A0, A0**A1, A1**A0, A1**A1]}
$$
\left[
0, 1, {Aleph \left({1} \right)},
{Aleph \left({1} \right)},
{Aleph \left({2} \right)},
{Aleph \left({1} \right)},
{Aleph \left({2} \right)}
\right]
$$
\returnType{Type: List CardinalNumber}

Three commonly encountered cardinal numbers are

\noindent
$
\begin{array}{lr}
{\tt a = \#}{\bf Z} & countable infinity  \\
{\tt c = \#}{\bf R} & the continuum       \\
{\tt f = \#\{g| g: [0,1] -> {\bf R}\}}    \\
\end{array}
$

In this domain, these values are obtained under the generalized
continuum hypothesis in this way.

\spadcommand{a := Aleph 0}
$$
Aleph \left({0} \right)
$$
\returnType{Type: CardinalNumber}

\spadcommand{c := 2**a}
$$
Aleph \left({1} \right)
$$
\returnType{Type: CardinalNumber}

\spadcommand{f := 2**c}
$$
Aleph \left({2} \right)
$$
\returnType{Type: CardinalNumber}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{CartesianTensor}

{\tt CartesianTensor(i0,dim,R)} provides Cartesian tensors with
components belonging to a commutative ring {\tt R}.  Tensors can be
described as a generalization of vectors and matrices.  This gives a
concise {\it tensor algebra} for multilinear objects supported by the
{\tt CartesianTensor} domain.  You can form the inner or outer product
of any two tensors and you can add or subtract tensors with the same
number of components.  Additionally, various forms of traces and
transpositions are useful.

The {\tt CartesianTensor} constructor allows you to specify the
minimum index for subscripting.  In what follows we discuss in detail
how to manipulate tensors.

%Original Page 318

Here we construct the domain of Cartesian tensors of dimension 2 over the
integers, with indices starting at 1.

\spadcommand{CT := CARTEN(i0 := 1, 2, Integer)}
$$
CartesianTensor(1,2,Integer) 
$$
\returnType{Type: Domain}

\subsubsection{Forming tensors}

Scalars can be converted to tensors of rank zero.

\spadcommand{t0: CT := 8}
$$
8 
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{rank t0}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

Vectors (mathematical direct products, rather than one dimensional array
structures) can be converted to tensors of rank one.

\spadcommand{v: DirectProduct(2, Integer) := directProduct [3,4]}
$$
\left[
3, 4 
\right]
$$
\returnType{Type: DirectProduct(2,Integer)}

\spadcommand{Tv: CT := v}
$$
\left[
3, 4 
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

Matrices can be converted to tensors of rank two.

\spadcommand{m: SquareMatrix(2, Integer) := matrix [ [1,2],[4,5] ]}
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
4 & 5 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{Tm: CT := m}
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
4 & 5 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{n: SquareMatrix(2, Integer) := matrix [ [2,3],[0,1] ]}
$$
\left[
\begin{array}{cc}
2 & 3 \\ 
0 & 1 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{Tn: CT := n}
$$
\left[
\begin{array}{cc}
2 & 3 \\ 
0 & 1 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

%Original Page 319

In general, a tensor of rank {\tt k} can be formed by making a list of
rank {\tt k-1} tensors or, alternatively, a {\tt k}-deep nested list
of lists.

\spadcommand{t1: CT := [2, 3]}
$$
\left[
2, 3 
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{rank t1}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{t2: CT := [t1, t1]}
$$
\left[
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{t3: CT := [t2, t2]}
$$
\left[
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]},
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{tt: CT := [t3, t3]; tt := [tt, tt]}
$$
\left[
{\left[ 
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
\end{array}
\right]},
{\left[ 
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
2 & 3 \\ 
2 & 3 
\end{array}
\right]}
\end{array}
\right]}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{rank tt}
$$
5 
$$
\returnType{Type: PositiveInteger}

\subsubsection{Multiplication}

Given two tensors of rank {\tt k1} and {\tt k2}, the outer
\spadfunFrom{product}{CartesianTensor} forms a new tensor of rank 
{\tt k1+k2}. Here

$$T_{mn}(i,j,k,l) = T_m(i,j) \  T_n(k,l)$$

\spadcommand{Tmn := product(Tm, Tn)}
$$
\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
0 & 1 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
4 & 6 \\ 
0 & 2 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
8 & {12} \\ 
0 & 4 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
{10} & {15} \\ 
0 & 5 
\end{array}
\right]}
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

The inner product (\spadfunFrom{contract}{CartesianTensor}) forms a
tensor of rank {\tt k1+k2-2}.  This product generalizes the vector dot
product and matrix-vector product by summing component products along
two indices.

%Original Page 320

Here we sum along the second index of $T_m$ and the first index of
$T_v$.  Here 

$$T_{mv} = \sum_{j=1}^{\hbox{\tiny\rm dim}} T_m(i,j) \ T_v(j)$$

\spadcommand{Tmv := contract(Tm,2,Tv,1)}
$$
\left[
{11}, {32} 
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

The multiplication operator \spadopFrom{*}{CartesianTensor} is scalar
multiplication or an inner product depending on the ranks of the arguments.

If either argument is rank zero it is treated as scalar multiplication.
Otherwise, {\tt a*b} is the inner product summing the last index of
{\tt a} with the first index of {\tt b}.

\spadcommand{Tm*Tv}
$$
\left[
{11}, {32} 
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

This definition is consistent with the inner product on matrices
and vectors.

\spadcommand{Tmv = m * v}
$$
{\left[ {11}, {32} \right]}=
{\left[{11}, {32} \right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\subsubsection{Selecting Components}

For tensors of low rank (that is, four or less), components can be selected
by applying the tensor to its indices.

\spadcommand{t0()}
$$
8 
$$
\returnType{Type: PositiveInteger}

\spadcommand{t1(1+1)}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{t2(2,1)}
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{t3(2,1,2)}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{Tmn(2,1,2,1)}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

A general indexing mechanism is provided for a list of indices.

\spadcommand{t0[]}
$$
8 
$$
\returnType{Type: PositiveInteger}

%Original Page 321

\spadcommand{t1[2]}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{t2[2,1]}
$$
2 
$$
\returnType{Type: PositiveInteger}

The general mechanism works for tensors of arbitrary rank, but is
somewhat less efficient since the intermediate index list must be created.

\spadcommand{t3[2,1,2]}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{Tmn[2,1,2,1]}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

\subsubsection{Contraction}

A ``contraction'' between two tensors is an inner product, as we have
seen above.  You can also contract a pair of indices of a single
tensor.  This corresponds to a ``trace'' in linear algebra.  The
expression {\tt contract(t,k1,k2)} forms a new tensor by summing the
diagonal given by indices in position {\tt k1} and {\tt k2}.

This is the tensor given by
$$xT_{mn} = \sum_{k=1}^{\hbox{\tiny\rm dim}} T_{mn}(k,k,i,j)$$

\spadcommand{cTmn := contract(Tmn,1,2)}
$$
\left[
\begin{array}{cc}
{12} & {18} \\ 
0 & 6 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

Since {\tt Tmn} is the outer product of matrix {\tt m} and matrix {\tt n},
the above is equivalent to this.

\spadcommand{trace(m) * n}
$$
\left[
\begin{array}{cc}
{12} & {18} \\ 
0 & 6 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

In this and the next few examples, we show all possible contractions
of {\tt Tmn} and their matrix algebra equivalents.

\spadcommand{contract(Tmn,1,2) = trace(m) * n}
$$
{\left[ 
\begin{array}{cc}
{12} & {18} \\ 
0 & 6 
\end{array}
\right]}={\left[
\begin{array}{cc}
{12} & {18} \\ 
0 & 6 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\spadcommand{contract(Tmn,1,3) = transpose(m) * n}
$$
{\left[ 
\begin{array}{cc}
2 & 7 \\ 
4 & {11} 
\end{array}
\right]}={\left[
\begin{array}{cc}
2 & 7 \\ 
4 & {11} 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

%Original Page 322

\spadcommand{contract(Tmn,1,4) = transpose(m) * transpose(n)}
$$
{\left[ 
\begin{array}{cc}
{14} & 4 \\ 
{19} & 5 
\end{array}
\right]}={\left[
\begin{array}{cc}
{14} & 4 \\ 
{19} & 5 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\spadcommand{contract(Tmn,2,3) = m * n}
$$
{\left[ 
\begin{array}{cc}
2 & 5 \\ 
8 & {17} 
\end{array}
\right]}={\left[
\begin{array}{cc}
2 & 5 \\ 
8 & {17} 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\spadcommand{contract(Tmn,2,4) = m * transpose(n)}
$$
{\left[ 
\begin{array}{cc}
8 & 2 \\ 
{23} & 5 
\end{array}
\right]}={\left[
\begin{array}{cc}
8 & 2 \\ 
{23} & 5 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\spadcommand{contract(Tmn,3,4) = trace(n) * m}
$$
{\left[ 
\begin{array}{cc}
3 & 6 \\ 
{12} & {15} 
\end{array}
\right]}={\left[
\begin{array}{cc}
3 & 6 \\ 
{12} & {15} 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\subsubsection{Transpositions}

You can exchange any desired pair of indices using the
\spadfunFrom{transpose}{CartesianTensor} operation.

Here the indices in positions one and three are exchanged, that is,
$$
tT_{mn}(i,j,k,l) = T_{mn}(k,j,i,l).
$$

\spadcommand{tTmn := transpose(Tmn,1,3)}
$$
\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 3 \\ 
8 & {12} 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
4 & 6 \\ 
{10} & {15} 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
0 & 1 \\ 
0 & 4 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
0 & 2 \\ 
0 & 5 
\end{array}
\right]}
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

If no indices are specified, the first and last index are exchanged.

\spadcommand{transpose Tmn}
$$
\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 8 \\ 
0 & 0 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
4 & {10} \\ 
0 & 0 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
3 & {12} \\ 
1 & 4 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
6 & {15} \\ 
2 & 5 
\end{array}
\right]}
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

This is consistent with the matrix transpose.

\spadcommand{transpose Tm = transpose m}
$$
{\left[ 
\begin{array}{cc}
1 & 4 \\ 
2 & 5 
\end{array}
\right]}={\left[
\begin{array}{cc}
1 & 4 \\ 
2 & 5 
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

If a more complicated reordering of the indices is required, then the
\spadfunFrom{reindex}{CartesianTensor} operation can be used.
This operation allows the indices to be arbitrarily permuted.

%Original Page 323

This defines $rT_{mn}(i,j,k,l) = \allowbreak T_{mn}(i,l,j,k).$

\spadcommand{rTmn := reindex(Tmn, [1,4,2,3])}
$$
\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 0 \\ 
4 & 0 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
3 & 1 \\ 
6 & 2 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
8 & 0 \\ 
{10} & 0 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
{12} & 4 \\ 
{15} & 5 
\end{array}
\right]}
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\subsubsection{Arithmetic}

Tensors of equal rank can be added or subtracted so arithmetic
expressions can be used to produce new tensors.

\spadcommand{tt := transpose(Tm)*Tn - Tn*transpose(Tm)}
$$
\left[
\begin{array}{cc}
-6 & -{16} \\ 
2 & 6 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{Tv*(tt+Tn)}
$$
\left[
-4, -{11} 
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\spadcommand{reindex(product(Tn,Tn),[4,3,2,1])+3*Tn*product(Tm,Tm)}
$$
\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
{46} & {84} \\ 
{174} & {212} 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
{57} & {114} \\ 
{228} & {285} 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
{18} & {24} \\ 
{57} & {63} 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
{17} & {30} \\ 
{63} & {76} 
\end{array}
\right]}
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

\subsubsection{Specific Tensors}

Two specific tensors have properties which depend only on the
dimension.

The Kronecker delta satisfies
\begin{verbatim}
             +-
             |   1  if i  = j
delta(i,j) = |
             |   0  if i ^= j
             +-
\end{verbatim}

\spadcommand{delta:  CT := kroneckerDelta()}
$$
\left[
\begin{array}{cc}
1 & 0 \\ 
0 & 1 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

This can be used to reindex via contraction.

\spadcommand{contract(Tmn, 2, delta, 1) = reindex(Tmn, [1,3,4,2])}
$$
{\left[ 
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 4 \\ 
3 & 6 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
0 & 0 \\ 
1 & 2 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
8 & {10} \\ 
{12} & {15} 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
0 & 0 \\ 
4 & 5 
\end{array}
\right]}
\end{array}
\right]}={\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
2 & 4 \\ 
3 & 6 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
0 & 0 \\ 
1 & 2 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
8 & {10} \\ 
{12} & {15} 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
0 & 0 \\ 
4 & 5 
\end{array}
\right]}
\end{array}
\right]}
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

%Original Page 324

The Levi Civita symbol determines the sign of a permutation of indices.

\spadcommand{epsilon:CT := leviCivitaSymbol()}
$$
\left[
\begin{array}{cc}
0 & 1 \\ 
-1 & 0 
\end{array}
\right]
$$
\returnType{Type: CartesianTensor(1,2,Integer)}

Here we have:
\begin{verbatim}
epsilon(i1,...,idim)
     = +1  if i1,...,idim is an even permutation of i0,...,i0+dim-1
     = -1  if i1,...,idim is an  odd permutation of i0,...,i0+dim-1
     =  0  if i1,...,idim is not   a permutation of i0,...,i0+dim-1
\end{verbatim}

This property can be used to form determinants.

\spadcommand{contract(epsilon*Tm*epsilon, 1,2) = 2 * determinant m}
$$
-6=-6 
$$
\returnType{Type: Equation CartesianTensor(1,2,Integer)}

\subsubsection{Properties of the CartesianTensor domain}

{\tt GradedModule(R,E)} denotes ``{\tt E}-graded {\tt R}-module'',
that is, a collection of {\tt R}-modules indexed by an abelian monoid
{\tt E.}  An element {\tt g} of {\tt G[s]} for some specific {\tt s}
in {\tt E} is said to be an element of {\tt G} with
\spadfunFrom{degree}{GradedModule} {\tt s}.  Sums are defined in each
module {\tt G[s]} so two elements of {\tt G} can be added if they have
the same degree.  Morphisms can be defined and composed by degree to
give the mathematical category of graded modules.

{\tt GradedAlgebra(R,E)} denotes ``{\tt E}-graded {\tt R}-algebra.''
A graded algebra is a graded module together with a degree preserving
{\tt R}-bilinear map, called the \spadfunFrom{product}{GradedAlgebra}.

\begin{verbatim}
degree(product(a,b))    = degree(a) + degree(b)

product(r*a,b)          = product(a,r*b) = r*product(a,b)
product(a1+a2,b)        = product(a1,b) + product(a2,b)
product(a,b1+b2)        = product(a,b1) + product(a,b2)
product(a,product(b,c)) = product(product(a,b),c)
\end{verbatim}

The domain {\tt CartesianTensor(i0, dim, R)} belongs to the category
{\tt GradedAlgebra(R, NonNegativeInteger)}.  The non-negative integer
\spadfunFrom{degree}{GradedAlgebra} is the tensor rank and the graded
algebra \spadfunFrom{product}{GradedAlgebra} is the tensor outer
product.  The graded module addition captures the notion that only
tensors of equal rank can be added.

If {\tt V} is a vector space of dimension {\tt dim} over {\tt R},
then the tensor module {\tt T[k](V)} is defined as
\begin{verbatim}
T[0](V) = R
T[k](V) = T[k-1](V) * V
\end{verbatim}
where {\tt *} denotes the {\tt R}-module tensor
\spadfunFrom{product}{GradedAlgebra}.  {\tt CartesianTensor(i0,dim,R)}
is the graded algebra in which the degree {\tt k} module is {\tt
T[k](V)}.

%Original Page 325

\subsubsection{Tensor Calculus}

It should be noted here that often tensors are used in the context of
tensor-valued manifold maps.  This leads to the notion of covariant
and contravariant bases with tensor component functions transforming
in specific ways under a change of coordinates on the manifold.  This
is no more directly supported by the {\tt CartesianTensor} domain than
it is by the {\tt Vector} domain.  However, it is possible to have the
components implicitly represent component maps by choosing a
polynomial or expression type for the components.  In this case, it is
up to the user to satisfy any constraints which arise on the basis of
this interpretation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Character}

The members of the domain {\tt Character} are values
representing letters, numerals and other text elements.
For more information on related topics, see
\domainref{CharacterClass} and \domainref{String}.

Characters can be obtained using {\tt String} notation.

\spadcommand{chars := [char "a", char "A", char "X", char "8", char "+"]}
$$
\left[
a, A, X, 8, + 
\right]
$$
\returnType{Type: List Character}

Certain characters are available by name.
This is the blank character.

\spadcommand{space()}
$$
\  
$$
\returnType{Type: Character}

This is the quote that is used in strings.

\spadcommand{quote()}
$$
\mbox{\tt "} 
$$
\returnType{Type: Character}

This is the escape character that allows quotes and other characters
within strings.

\spadcommand{escape()}
$$
\_ 
$$
\returnType{Type: Character}

Characters are represented as integers in a machine-dependent way.
The integer value can be obtained using the
\spadfunFrom{ord}{Character} operation.  It is always true that {\tt
char(ord c) = c} and {\tt ord(char i) = i}, provided that {\tt i} is
in the range {\tt 0..size()\$Character-1}.

\spadcommand{[ord c for c in chars]}
$$
\left[
{97}, {65}, {88}, {56}, {43} 
\right]
$$
\returnType{Type: List Integer}
 
The \spadfunFrom{lowerCase}{Character} operation converts an upper
case letter to the corresponding lower case letter.  If the argument
is not an upper case letter, then it is returned unchanged.

\spadcommand{[upperCase c for c in chars]}
$$
\left[
A, A, X, 8, + 
\right]
$$
\returnType{Type: List Character}

%Original Page 326

Likewise, the \spadfunFrom{upperCase}{Character} operation converts lower
case letters to upper case.

\spadcommand{[lowerCase c for c in chars] }
$$
\left[
a, a, x, 8, + 
\right]
$$
\returnType{Type: List Character}

A number of tests are available to determine whether characters
belong to certain families.

\spadcommand{[alphabetic? c for c in chars] }
$$
\left[
{\tt true}, {\tt true}, {\tt true}, {\tt false}, {\tt false} 
\right]
$$
\returnType{Type: List Boolean}

\spadcommand{[upperCase? c for c in chars] }
$$
\left[
{\tt false}, {\tt true}, {\tt true}, {\tt false}, {\tt false} 
\right]
$$
\returnType{Type: List Boolean}

\spadcommand{[lowerCase? c for c in chars] }
$$
\left[
{\tt true}, {\tt false}, {\tt false}, {\tt false}, {\tt false} 
\right]
$$
\returnType{Type: List Boolean}

\spadcommand{[digit? c for c in chars] }
$$
\left[
{\tt false}, {\tt false}, {\tt false}, {\tt true}, {\tt false} 
\right]
$$
\returnType{Type: List Boolean}

\spadcommand{[hexDigit? c for c in chars] }
$$
\left[
{\tt true}, {\tt true}, {\tt false}, {\tt true}, {\tt false} 
\right]
$$
\returnType{Type: List Boolean}

\spadcommand{[alphanumeric? c for c in chars] }
$$
\left[
{\tt true}, {\tt true}, {\tt true}, {\tt true}, {\tt false} 
\right]
$$
\returnType{Type: List Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{CharacterClass}

The {\tt CharacterClass} domain allows classes of characters to be
defined and manipulated efficiently.
 
Character classes can be created by giving either a string or a list
of characters.

\spadcommand{cl1 := charClass [char "a", char "e", char "i", char "o", char "u", char "y"] }
$$
\mbox{\tt "aeiouy"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{cl2 := charClass "bcdfghjklmnpqrstvwxyz" }
$$
\mbox{\tt "bcdfghjklmnpqrstvwxyz"} 
$$
\returnType{Type: CharacterClass}

%Original Page 327

A number of character classes are predefined for convenience.

\spadcommand{digit()}
$$
\mbox{\tt "0123456789"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{hexDigit()}
$$
\mbox{\tt "0123456789ABCDEFabcdef"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{upperCase()}
$$
\mbox{\tt "ABCDEFGHIJKLMNOPQRSTUVWXYZ"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{lowerCase()}
$$
\mbox{\tt "abcdefghijklmnopqrstuvwxyz"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{alphabetic()}
$$
\mbox{\tt "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{alphanumeric()}
$$
\mbox{\tt "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"} 
$$
\returnType{Type: CharacterClass}

You can quickly test whether a character belongs to a class.

\spadcommand{member?(char "a", cl1) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{member?(char "a", cl2) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Classes have the usual set operations because the {\tt CharacterClass}
domain belongs to the category {\tt FiniteSetAggregate(Character)}.

\spadcommand{intersect(cl1, cl2)  }
$$
\mbox{\tt "y"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{union(cl1,cl2)       }
$$
\mbox{\tt "abcdefghijklmnopqrstuvwxyz"} 
$$
\returnType{Type: CharacterClass}

%Original Page 328

\spadcommand{difference(cl1,cl2)  }
$$
\mbox{\tt "aeiou"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{intersect(complement(cl1),cl2)  }
$$
\mbox{\tt "bcdfghjklmnpqrstvwxz"} 
$$
\returnType{Type: CharacterClass}

You can modify character classes by adding or removing characters.

\spadcommand{insert!(char "a", cl2) }
$$
\mbox{\tt "abcdfghjklmnpqrstvwxyz"} 
$$
\returnType{Type: CharacterClass}

\spadcommand{remove!(char "b", cl2) }
$$
\mbox{\tt "acdfghjklmnpqrstvwxyz"} 
$$
\returnType{Type: CharacterClass}
 
For more information on related topics, see 
\domainref{Character} and \domainref{String}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{CliffordAlgebra}

\noindent

{\tt CliffordAlgebra(n,K,Q)} defines a vector space of dimension $2^n$
over the field $K$ with a given quadratic form {\tt Q}.  If $\{e_1,
\ldots, e_n\}$ is a basis for $K^n$ then
\begin{verbatim}
{ 1,
  e(i) 1 <= i <= n,
  e(i1)*e(i2) 1 <= i1 < i2 <=n,
  ...,
  e(1)*e(2)*...*e(n) }
\end{verbatim}
is a basis for the Clifford algebra. The algebra is defined by the relations
\begin{verbatim}
e(i)*e(i) = Q(e(i))
e(i)*e(j) = -e(j)*e(i),  i ^= j
\end{verbatim}
Examples of Clifford Algebras are
gaussians (complex numbers), quaternions,
exterior algebras and spin algebras.

%Original Page 329

\subsection{The Complex Numbers as a Clifford Algebra}

This is the field over which we will work, rational functions with
integer coefficients.

\spadcommand{K := Fraction Polynomial Integer }
$$
\mbox{\rm Fraction Polynomial Integer} 
$$
\returnType{Type: Domain}

We use this matrix for the quadratic form.

\spadcommand{m := matrix [ [-1] ] }
$$
\left[
\begin{array}{c}
-1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

We get complex arithmetic by using this domain.

\spadcommand{C := CliffordAlgebra(1, K, quadraticForm m) }
$$
\mbox{\rm CliffordAlgebra(1,Fraction Polynomial Integer,MATRIX)} 
$$
\returnType{Type: Domain}

Here is {\tt i}, the usual square root of {\tt -1.}

\spadcommand{i: C := e(1)   }
$$
e \sb {1} 
$$
\returnType{Type: CliffordAlgebra(1,Fraction Polynomial Integer,MATRIX)}

Here are some examples of the arithmetic.

\spadcommand{x := a + b * i }
$$
a+{b \  {e \sb {1}}} 
$$
\returnType{Type: CliffordAlgebra(1,Fraction Polynomial Integer,MATRIX)}

\spadcommand{y := c + d * i }
$$
c+{d \  {e \sb {1}}} 
$$
\returnType{Type: CliffordAlgebra(1,Fraction Polynomial Integer,MATRIX)}

See \domainref{Complex}
for examples of Axiom's constructor implementing complex numbers.

\spadcommand{x * y }
$$
-{b \  d}+{a \  c}+{{\left( {a \  d}+{b \  c} 
\right)}
\  {e \sb {1}}} 
$$
\returnType{Type: CliffordAlgebra(1,Fraction Polynomial Integer,MATRIX)}

\subsection{The Quaternion Numbers as a Clifford Algebra}

This is the field over which we will work, rational functions with
integer coefficients.

\spadcommand{K := Fraction Polynomial Integer }
$$
\mbox{\rm Fraction Polynomial Integer} 
$$
\returnType{Type: Domain}

%Original Page 330

We use this matrix for the quadratic form.

\spadcommand{m := matrix [ [-1,0],[0,-1] ] }
$$
\left[
\begin{array}{cc}
-1 & 0 \\ 
0 & -1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

The resulting domain is the quaternions.

\spadcommand{H  := CliffordAlgebra(2, K, quadraticForm m) }
$$
\mbox{\rm CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)} 
$$
\returnType{Type: Domain}

We use Hamilton's notation for {\tt i},{\tt j},{\tt k}.

\spadcommand{i: H  := e(1) }
$$
e \sb {1} 
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\spadcommand{j: H  := e(2) }
$$
e \sb {2} 
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\spadcommand{k: H  := i * j }
$$
{e \sb {1}} \  {e \sb {2}} 
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\spadcommand{x := a + b * i + c * j + d * k }
$$
a+{b \  {e \sb {1}}}+{c \  {e \sb {2}}}+{d \  {e \sb {1}} \  {e \sb {2}}} 
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\spadcommand{y := e + f * i + g * j + h * k }
$$
e+{f \  {e \sb {1}}}+{g \  {e \sb {2}}}+{h \  {e \sb {1}} \  {e \sb {2}}} 
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\spadcommand{x + y }
$$
e+a+{{\left( f+b 
\right)}
\  {e \sb {1}}}+{{\left( g+c 
\right)}
\  {e \sb {2}}}+{{\left( h+d 
\right)}
\  {e \sb {1}} \  {e \sb {2}}} 
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\spadcommand{x * y }
$$
\begin{array}{@{}l}
-{d \  h} -
{c \  g} -
{b \  f}+
{a \  e}+
{{\left( {c \  h} -{d \  g}+{a \  f}+{b \  e} \right)}\  {e \sb {1}}}+
\\
\\
\displaystyle
{{\left( -{b \  h}+{a \  g}+{d \  f}+{c \  e} \right)}\  {e \sb {2}}}+
{{\left( {a \  h}+{b \  g} -{c \  f}+{d \  e} \right)}
\  {e \sb {1}} \  {e \sb {2}}} 
\end{array}
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

%Original Page 331

See \domainref{Quaternion}
for examples of Axiom's constructor implementing quaternions.

\spadcommand{y * x }
$$
\begin{array}{@{}l}
-{d \  h} -{c \  g} -{b \  f}+{a \  e}+
{{\left( -{c \  h}+{d \  g}+{a \  f}+{b \  e} \right)}\  {e \sb {1}}}+
\\
\\
\displaystyle
{{\left( {b \  h}+{a \  g} -{d \  f}+{c \  e} \right)}\  {e \sb {2}}}+
{{\left( {a \  h} -
{b \  g}+{c \  f}+{d \  e} \right)}\  {e \sb {1}} \  {e \sb {2}}} 
\end{array}
$$
\returnType{Type: CliffordAlgebra(2,Fraction Polynomial Integer,MATRIX)}

\subsection{The Exterior Algebra on a Three Space}

This is the field over which we will work, rational functions with
integer coefficients.

\spadcommand{K := Fraction Polynomial Integer }
$$
\mbox{\rm Fraction Polynomial Integer} 
$$
\returnType{Type: Domain}

If we chose the three by three zero quadratic form, we obtain
the exterior algebra on {\tt e(1),e(2),e(3)}.

\spadcommand{Ext := CliffordAlgebra(3, K, quadraticForm 0) }
$$
\mbox{\rm CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)} 
$$
\returnType{Type: Domain}

This is a three dimensional vector algebra.
We define {\tt i}, {\tt j}, {\tt k} as the unit vectors.

\spadcommand{i: Ext := e(1) }
$$
e \sb {1} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

\spadcommand{j: Ext := e(2) }
$$
e \sb {2} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

\spadcommand{k: Ext := e(3) }
$$
e \sb {3} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

Now it is possible to do arithmetic.

\spadcommand{x := x1*i + x2*j + x3*k }
$$
{x1 \  {e \sb {1}}}+{x2 \  {e \sb {2}}}+{x3 \  {e \sb {3}}} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

\spadcommand{y := y1*i + y2*j + y3*k }
$$
{y1 \  {e \sb {1}}}+{y2 \  {e \sb {2}}}+{y3 \  {e \sb {3}}} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

\spadcommand{x + y         }
$$
{{\left( y1+x1 
\right)}
\  {e \sb {1}}}+{{\left( y2+x2 
\right)}
\  {e \sb {2}}}+{{\left( y3+x3 
\right)}
\  {e \sb {3}}} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

%Original Page 332

\spadcommand{x * y + y * x }
$$
0 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

On an {\tt n} space, a grade {\tt p} form has a dual {\tt n-p} form.
In particular, in three space the dual of a grade two element identifies
{\tt e1*e2->e3, e2*e3->e1, e3*e1->e2}.

\spadcommand{dual2 a == coefficient(a,[2,3]) * i + coefficient(a,[3,1]) * j + coefficient(a,[1,2]) * k }
\returnType{Type: Void}

The vector cross product is then given by this.

\spadcommand{dual2(x*y) }
\begin{verbatim}
   Compiling function dual2 with type CliffordAlgebra(3,Fraction 
      Polynomial Integer,MATRIX) -> CliffordAlgebra(3,Fraction 
      Polynomial Integer,MATRIX) 
\end{verbatim}
$$
{{\left( {x2 \  y3} -{x3 \  y2} 
\right)}
\  {e \sb {1}}}+{{\left( -{x1 \  y3}+{x3 \  y1} 
\right)}
\  {e \sb {2}}}+{{\left( {x1 \  y2} -{x2 \  y1} 
\right)}
\  {e \sb {3}}} 
$$
\returnType{Type: CliffordAlgebra(3,Fraction Polynomial Integer,MATRIX)}

\subsection{The Dirac Spin Algebra}

In this section we will work over the field of rational numbers.

\spadcommand{K := Fraction Integer }
$$
\mbox{\rm Fraction Integer} 
$$
\returnType{Type: Domain}

We define the quadratic form to be the Minkowski space-time metric.

\spadcommand{g := matrix [ [1,0,0,0], [0,-1,0,0], [0,0,-1,0], [0,0,0,-1] ] }
$$
\left[
\begin{array}{cccc}
1 & 0 & 0 & 0 \\ 
0 & -1 & 0 & 0 \\ 
0 & 0 & -1 & 0 \\ 
0 & 0 & 0 & -1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

We obtain the Dirac spin algebra used in Relativistic Quantum Field Theory.

\spadcommand{D := CliffordAlgebra(4,K, quadraticForm g) }
$$
\mbox{\rm CliffordAlgebra(4,Fraction Integer,MATRIX)} 
$$
\returnType{Type: Domain}

The usual notation for the basis is $\gamma$ with a superscript.  For
Axiom input we will use {\tt gam(i)}:

\spadcommand{gam := [e(i)\$D for i in 1..4] }
$$
\left[
{e \sb {1}}, {e \sb {2}}, {e \sb {3}}, {e \sb {4}} 
\right]
$$
\returnType{Type: List CliffordAlgebra(4,Fraction Integer,MATRIX)}

\noindent
There are various contraction identities of the form
\begin{verbatim}
g(l,t)*gam(l)*gam(m)*gam(n)*gam(r)*gam(s)*gam(t) =
      2*(gam(s)gam(m)gam(n)gam(r) + gam(r)*gam(n)*gam(m)*gam(s))
\end{verbatim}
where a sum over {\tt l} and {\tt t} is implied.

%Original Page 333

Verify this identity for particular values of {\tt m,n,r,s}.

\spadcommand{m := 1; n:= 2; r := 3; s := 4; }
\returnType{Type: PositiveInteger}

\spadcommand{lhs := reduce(+, [reduce(+, [ g(l,t)*gam(l)*gam(m)*gam(n)*gam(r)*gam(s)*gam(t) for l in 1..4]) for t in 1..4]) }
$$
-{4 \  {e \sb {1}} \  {e \sb {2}} \  {e \sb {3}} \  {e \sb {4}}} 
$$
\returnType{Type: CliffordAlgebra(4,Fraction Integer,MATRIX)}

\spadcommand{rhs := 2*(gam s * gam m*gam n*gam r + gam r*gam n*gam m*gam s) }
$$
-{4 \  {e \sb {1}} \  {e \sb {2}} \  {e \sb {3}} \  {e \sb {4}}} 
$$
\returnType{Type: CliffordAlgebra(4,Fraction Integer,MATRIX)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Complex}

The {\tt Complex} constructor implements complex objects over a
commutative ring {\tt R}.  Typically, the ring {\tt R} is {\tt Integer}, 
{\tt Fraction Integer}, {\tt Float} or {\tt DoubleFloat}.
{\tt R} can also be a symbolic type, like {\tt Polynomial Integer}.
For more information about the numerical and graphical aspects of
complex numbers, see \sectionref{ugProblemNumeric}.

Complex objects are created by the \spadfunFrom{complex}{Complex} operation.

\spadcommand{a := complex(4/3,5/2) }
$$
{\frac{4}{3}}+{{\frac{5}{2}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

\spadcommand{b := complex(4/3,-5/2) }
$$
{\frac{4}{3}} -{{\frac{5}{2}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

The standard arithmetic operations are available.

\spadcommand{a + b }
$$
\frac{8}{3} 
$$
\returnType{Type: Complex Fraction Integer}

\spadcommand{a - b }
$$
5 \  i 
$$
\returnType{Type: Complex Fraction Integer}

\spadcommand{a * b }
$$
\frac{289}{36} 
$$
\returnType{Type: Complex Fraction Integer}

%Original Page 334

If {\tt R} is a field, you can also divide the complex objects.

\spadcommand{a / b }
$$
-{\frac{161}{289}}+{{\frac{240}{289}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

Use a conversion (see \sectionref{ugTypesConvert})
to view the last object as a fraction of complex integers.

\spadcommand{\% :: Fraction Complex Integer }
$$
\frac{-{15}+{8 \  i}}{{15}+{8 \  i}} 
$$
\returnType{Type: Fraction Complex Integer}

The predefined macro {\tt \%i} is defined to be {\tt complex(0,1)}.

\spadcommand{3.4 + 6.7 * \%i}
$$
{3.4}+{{6.7} \  i} 
$$
\returnType{Type: Complex Float}

You can also compute the \spadfunFrom{conjugate}{Complex} and
\spadfunFrom{norm}{Complex} of a complex number.

\spadcommand{conjugate a }
$$
{\frac{4}{3}} -{{\frac{5}{2}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

\spadcommand{norm a }
$$
\frac{289}{36} 
$$
\returnType{Type: Fraction Integer}

The \spadfunFrom{real}{Complex} and \spadfunFrom{imag}{Complex} operations
are provided to extract the real and imaginary parts, respectively.

\spadcommand{real a }
$$
\frac{4}{3} 
$$
\returnType{Type: Fraction Integer}

\spadcommand{imag a }
$$
\frac{5}{2} 
$$
\returnType{Type: Fraction Integer}

The domain {\tt Complex Integer} is also called the Gaussian integers.
If {\tt R} is the integers (or, more generally, a {\tt EuclideanDomain}), 
you can compute greatest common divisors.

\spadcommand{gcd(13 - 13*\%i,31 + 27*\%i)}
$$
5+i 
$$
\returnType{Type: Complex Integer}

You can also compute least common multiples.

\spadcommand{lcm(13 - 13*\%i,31 + 27*\%i)}
$$
{143} -{{39} \  i} 
$$
\returnType{Type: Complex Integer}

%Original Page 335

You can \spadfunFrom{factor}{Complex} Gaussian integers.

\spadcommand{factor(13 - 13*\%i)}
$$
-{{\left( 1+i 
\right)}
\  {\left( 2+{3 \  i} 
\right)}
\  {\left( 3+{2 \  i} 
\right)}}
$$
\returnType{Type: Factored Complex Integer}

\spadcommand{factor complex(2,0)}
$$
-{i \  {{\left( 1+i 
\right)}
\sp 2}} 
$$
\returnType{Type: Factored Complex Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{ContinuedFraction}

Continued fractions have been a fascinating and useful tool in
mathematics for well over three hundred years.  Axiom implements
continued fractions for fractions of any Euclidean domain.  In
practice, this usually means rational numbers.  In this section we
demonstrate some of the operations available for manipulating both
finite and infinite continued fractions.  It may be helpful if you
review \domainref{Stream} to remind 
yourself of some of the operations with streams.

The {\tt ContinuedFraction} domain is a field and therefore you can
add, subtract, multiply and divide the fractions.

The \spadfunFrom{continuedFraction}{ContinuedFraction} operation
converts its fractional argument to a continued fraction.

\spadcommand{c := continuedFraction(314159/100000) }
$$
3+ \zag{1}{7}+ \zag{1}{{15}}+ \zag{1}{1}+ \zag{1}{{25}}+ \zag{1}{1}+ 
\zag{1}{7}+ \zag{1}{4} 
$$
\returnType{Type: ContinuedFraction Integer}

This display is a compact form of the bulkier
\begin{verbatim}
        3 +                 1
            -------------------------------
            7 +               1
                ---------------------------
                15 +            1
                     ----------------------
                     1 +          1
                         ------------------
                         25 +       1
                              -------------
                              1 +     1
                                  ---------
                                  7 +   1
                                      -----
                                        4
\end{verbatim}

You can write any rational number in a similar form.  The fraction
will be finite and you can always take the ``numerators'' to be {\tt 1}.
That is, any rational number can be written as a simple, finite
continued fraction of the form

\begin{verbatim}
        a(1) +           1
               -------------------------
               a(2) +          1
                      --------------------
                      a(3) +
                             .
                              .
                               .
                                     1
                               -------------
                               a(n-1) +  1
                                        ----
                                        a(n)
\end{verbatim}

%Original Page 336

The $a_i$ are called partial quotients and the operation
\spadfunFrom{partialQuotients}{ContinuedFraction} creates a stream of them.

\spadcommand{partialQuotients c }
$$
\left[
3, 7, {15}, 1, {25}, 1, 7, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

By considering more and more of the fraction, you get the
\spadfunFrom{convergents}{ContinuedFraction}.  For example, the first
convergent is $a_1$, the second is $a_1 + 1/a_2$ and so on.

\spadcommand{convergents c }
$$
\left[
3, {\frac{22}{7}}, {\frac{333}{106}}, {\frac{355}{113}}, 
{\frac{9208}{2931}}, {\frac{9563}{3044}}, {\frac{76149}{24239}}, 
\ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

Since this is a finite continued fraction, the last convergent is the
original rational number, in reduced form.  The result of
\spadfunFrom{approximants}{ContinuedFraction} is always an infinite
stream, though it may just repeat the ``last'' value.

\spadcommand{approximants c }
$$
\left[
3, {\frac{22}{7}}, {\frac{333}{106}}, {\frac{355}{113}}, 
{\frac{9208}{2931}}, {\frac{9563}{3044}}, {\frac{76149}{24239}}, 
\ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

Inverting {\tt c} only changes the partial quotients of its fraction
by inserting a {\tt 0} at the beginning of the list.

\spadcommand{pq := partialQuotients(1/c) }
$$
\left[
0, 3, 7, {15}, 1, {25}, 1, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Do this to recover the original continued fraction from this list of
partial quotients.  The three-argument form of the
\spadfunFrom{continuedFraction}{ContinuedFraction} operation takes an
element which is the whole part of the fraction, a stream of elements
which are the numerators of the fraction, and a stream of elements
which are the denominators of the fraction.

\spadcommand{continuedFraction(first pq,repeating [1],rest pq) }
$$
\zag{1}{3}+ \zag{1}{7}+ \zag{1}{{15}}+ \zag{1}{1}+ \zag{1}{{25}}+ \zag{1}{1}+ 
\zag{1}{7}+\ldots 
$$
\returnType{Type: ContinuedFraction Integer}

The streams need not be finite for
\spadfunFrom{continuedFraction}{ContinuedFraction}.  Can you guess
which irrational number has the following continued fraction?  See the
end of this section for the answer.

\spadcommand{z:=continuedFraction(3,repeating [1],repeating [3,6]) }
$$
3+ \zag{1}{3}+ \zag{1}{6}+ \zag{1}{3}+ \zag{1}{6}+ \zag{1}{3}+ \zag{1}{6}+ 
\zag{1}{3}+\ldots 
$$
\returnType{Type: ContinuedFraction Integer}

In 1737 Euler discovered the infinite continued fraction expansion
\begin{verbatim}
        e - 1             1
        ----- = ---------------------
          2     1 +         1
                    -----------------
                    6 +       1
                        -------------
                        10 +    1
                             --------
                             14 + ...
\end{verbatim}

We use this expansion to compute rational and floating point
approximations of {\tt e}.\footnote{For this and other interesting
expansions, see C. D. Olds, {\it Continued Fractions,} New
Mathematical Library, (New York: Random House, 1963), pp.  134--139.}

%Original Page 337

By looking at the above expansion, we see that the whole part is {\tt 0}
and the numerators are all equal to {\tt 1}.  This constructs the
stream of denominators.

\spadcommand{dens:Stream Integer := cons(1,generate((x+->x+4),6)) }
$$
\left[
1, 6, {10}, {14}, {18}, {22}, {26}, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Therefore this is the continued fraction expansion for
$(e - 1) / 2$.

\spadcommand{cf := continuedFraction(0,repeating [1],dens) }
$$
\zag{1}{1}+ \zag{1}{6}+ \zag{1}{{10}}+ \zag{1}{{14}}+ \zag{1}{{18}}+ 
\zag{1}{{22}}+ \zag{1}{{26}}+\ldots 
$$
\returnType{Type: ContinuedFraction Integer}

These are the rational number convergents.

\spadcommand{ccf := convergents cf }
$$
\left[
0, 1, {\frac{6}{7}}, {\frac{61}{71}}, {\frac{860}{1001}}, 
{\frac{15541}{18089}}, {\frac{342762}{398959}}, \ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

You can get rational convergents for {\tt e} by multiplying by {\tt 2} and
adding {\tt 1}.

\spadcommand{eConvergents := [2*e + 1 for e in ccf] }
$$
\left[
1, 3, {\frac{19}{7}}, {\frac{193}{71}}, {\frac{2721}{1001}}, 
{\frac{49171}{18089}}, {\frac{1084483}{398959}}, \ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

You can also compute the floating point approximations to these convergents.

\spadcommand{eConvergents :: Stream Float }
$$
\begin{array}{@{}l}
\left[
{1.0}, {3.0}, {2.7142857142 857142857}, {2.7183098591 549295775}, 
\right.
\\
\\
\displaystyle
{2.7182817182 817182817}, {2.7182818287 356957267}, 
\\
\\
\displaystyle
\left.
{2.7182818284\ 585634113}, \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream Float}

Compare this to the value of {\tt e} computed by the
\spadfunFrom{exp}{Float} operation in {\tt Float}.

\spadcommand{exp 1.0}
$$
2.7182818284\ 590452354 
$$
\returnType{Type: Float}

In about 1658, Lord Brouncker established the following expansion
for $4 / \pi$,
\begin{verbatim}
        1 +            1
            -----------------------
            2 +          9
                -------------------
                2 +        25
                    ---------------
                    2 +      49
                        -----------
                        2 +    81
                            -------
                            2 + ...
\end{verbatim}

%Original Page 338

Let's use this expansion to compute rational and floating point
approximations for $\pi$.

\spadcommand{cf := continuedFraction(1,[(2*i+1)**2 for i in 0..],repeating [2])}
$$
1+ \zag{1}{2}+ \zag{9}{2}+ \zag{{25}}{2}+ \zag{{49}}{2}+ \zag{{81}}{2}+ 
\zag{{121}}{2}+ \zag{{169}}{2}+\ldots 
$$
\returnType{Type: ContinuedFraction Integer}

\spadcommand{ccf := convergents cf }
$$
\left[
1, {\frac{3}{2}}, {\frac{15}{13}}, {\frac{105}{76}}, {\frac{315}{263}}, 
{\frac{3465}{2578}}, {\frac{45045}{36979}}, \ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

\spadcommand{piConvergents := [4/p for p in ccf] }
$$
\left[
4, {\frac{8}{3}}, {\frac{52}{15}}, {\frac{304}{105}}, 
{\frac{1052}{315}}, {\frac{10312}{3465}}, {\frac{147916}{45045}}, 
\ldots 
\right]
$$
\returnType{Type: Stream Fraction Integer}

As you can see, the values are converging to
$\pi = 3.14159265358979323846...$,
but not very quickly.

\spadcommand{piConvergents :: Stream Float }
$$
\begin{array}{@{}l}
\left[
{4.0}, {2.6666666666\ 666666667}, {3.4666666666\ 666666667}, 
\right.
\\
\\
\displaystyle
{2.8952380952\ 380952381}, {3.3396825396\ 825396825}, 
\\
\\
\displaystyle
\left.
{2.9760461760\ 461760462}, {3.2837384837\ 384837385}, \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream Float}

You need not restrict yourself to continued fractions of integers.
Here is an expansion for a quotient of Gaussian integers.

\spadcommand{continuedFraction((- 122 + 597*\%i)/(4 - 4*\%i))}
$$
-{90}+{{59} \  i}+ \zag{1}{{1 -{2 \  i}}}+ \zag{1}{{-1+{2 \  i}}} 
$$
\returnType{Type: ContinuedFraction Complex Integer}

This is an expansion for a quotient of polynomials in one variable
with rational number coefficients.

\spadcommand{r : Fraction UnivariatePolynomial(x,Fraction Integer) }
\returnType{Type: Void}

\spadcommand{r := ((x - 1) * (x - 2)) / ((x-3) * (x-4)) }
$$
\frac{{x \sp 2} -{3 \  x}+2}{{x \sp 2} -{7 \  x}+{12}} 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{continuedFraction r }
$$
1+ \zag{1}{{{{\frac{1}{4}} \  x} -{\frac{9}{8}}}}+ 
\zag{1}{{{{\frac{16}{3}} \  x} 
-{\frac{40}{3}}}} 
$$
\returnType{Type: ContinuedFraction UnivariatePolynomial(x,Fraction Integer)}

To conclude this section, we give you evidence that
\begin{verbatim}
    z = 3 +            1
            -----------------------
            3 +          1
                -------------------
                6 +        1
                    ---------------
                    3 +      1
                        -----------
                        6 +    1
                            -------
                            3 + ...
\end{verbatim}

%Original Page 339

is the expansion of $\sqrt{11}$.

\spadcommand{[i*i for i in convergents(z) :: Stream Float] }
$$
\begin{array}{@{}l}
\left[
{9.0}, {11.1111111111\ 11111111}, {10.9944598337\ 9501385}, 
\right.
\\
\\
\displaystyle
{11.0002777777\ 77777778}, {10.9999860763\ 98799786}, 
\\
\\
\displaystyle
\left.
{11.0000006979\ 29731039}, {10.9999999650\ 15834446}, \ldots 
\right]
\end{array}
$$
\returnType{Type: Stream Float}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{CycleIndicators}

This section is based upon the paper J. H. Redfield, ``The Theory of
Group-Reduced Distributions'', American J. Math.,49 (1927) 433-455,
and is an application of group theory to enumeration problems.  It is
a development of the work by P. A. MacMahon on the application of
symmetric functions and Hammond operators to combinatorial theory.

The theory is based upon the power sum symmetric functions
$s_i$ which are the sum of the $i$-th powers of the
variables.  The cycle index of a permutation is an expression that
specifies the sizes of the cycles of a permutation, and may be
represented as a partition.  A partition of a non-negative integer
{\tt n} is a collection of positive integers called its parts whose
sum is {\tt n}.  For example, the partition $(3^2 \ 2 \ 1^2)$ will be
used to represent $s^2_3 s_2 s^2_1$ and will indicate that the
permutation has two cycles of length 3, one of length 2 and two of
length 1.  The cycle index of a permutation group is the sum of the
cycle indices of its permutations divided by the number of
permutations.  The cycle indices of certain groups are provided.

The operation {\tt complete} returns the cycle index of the
symmetric group of order {\tt n} for argument {\tt n}.
Alternatively, it is the $n$-th complete homogeneous symmetric
function expressed in terms of power sum symmetric functions.

\spadcommand{complete 1}
$$
\left(
1 
\right)
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

\spadcommand{complete 2}
$$
{{\frac{1}{2}} \  {\left( 2 \right)}}+{{\frac{1}{2}} \  
{\left( 1 \sp 2 \right)}}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

%Original Page 340

\spadcommand{complete 3}
$$
{{\frac{1}{3}} \  {\left( 3 \right)}}
+{{\frac{1}{2}} \  {\left( {2 \sp {\ }} \  1 \right)}}
+{{\frac{1}{6}} \  {\left( 1 \sp 3 \right)}}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

\spadcommand{complete 7}
$$
\begin{array}{@{}l}
{{\frac{1}{7}} \  {\left( 7 \right)}}+
{{\frac{1}{6}} \  {\left( {6 \sp {\ }} \  1 \right)}}+
{{\frac{1}{10}} \  {\left( {5 \sp {\ }} \  2 \right)}}+
{{\frac{1}{10}} \  {\left( {5 \sp {\ }} \  {1 \sp 2} \right)}}+
{{\frac{1}{12}} \  {\left( {4 \sp {\ }} \  3 \right)}}+
{{\frac{1}{8}} \  {\left( {4 \sp {\ }} \  {2 \sp {\ }} \  1 \right)}}+
\\
\\
\displaystyle
{{\frac{1}{24}} \  {\left( {4 \sp {\ }} \  {1 \sp 3} \right)}}+
{{\frac{1}{18}} \  {\left( {3 \sp 2} \  1 \right)}}+
{{\frac{1}{24}} \  {\left( {3 \sp {\ }} \  {2 \sp 2} \right)}}+
{{\frac{1}{12}} \  {\left( {3 \sp {\ }} \  {2 \sp {\ }} \  {1 \sp 2} \right)}}+
{{\frac{1}{72}} \  {\left( {3 \sp {\ }} \  {1 \sp 4} \right)}}+
\\
\\
\displaystyle
{{\frac{1}{48}} \  {\left( {2 \sp 3} \  1 \right)}}+
{{\frac{1}{48}} \  {\left( {2 \sp 2} \  {1 \sp 3} \right)}}+
{{\frac{1}{240}} \  {\left( {2 \sp {\ }} \  {1 \sp 5} \right)}}+
{{\frac{1}{5040}} \  {\left( 1 \sp 7 \right)}}
\end{array}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

%Original Page 

The operation {\tt elementary} computes the $n$-th
elementary symmetric function for argument {\tt n.}

\spadcommand{elementary 7}
$$
\begin{array}{@{}l}
{{\frac{1}{7}} \  {\left( 7 \right)}}
-{{\frac{1}{6}} \  {\left( {6 \sp {\ }} \  1 \right)}}
-{{\frac{1}{10}} \  {\left( {5 \sp {\ }} \  2 \right)}}+
{{\frac{1}{10}} \  {\left( {5 \sp {\ }} \  {1 \sp 2} \right)}}
-{{\frac{1}{12}} \  {\left( {4 \sp {\ }} \  3 \right)}}+
{{\frac{1}{8}} \  {\left( {4 \sp {\ }} \  {2 \sp {\ }} \  1 \right)}}
\\
\\
\displaystyle
-{{\frac{1}{24}} \  {\left( {4 \sp {\ }} \  {1 \sp 3} \right)}}+
{{\frac{1}{18}} \  {\left( {3 \sp 2} \  1 \right)}}+
{{\frac{1}{24}} \  {\left( {3 \sp {\ }} \  {2 \sp 2} \right)}}
-{{\frac{1}{12}} \  {\left( {3 \sp {\ }} \  {2 \sp {\ }} \  {1 \sp 2} \right)}}
+{{\frac{1}{72}} \  {\left( {3 \sp {\ }} \  {1 \sp 4} \right)}}
\\
\\
\displaystyle
-{{\frac{1}{48}} \  {\left( {2 \sp 3} \  1 \right)}}+
{{\frac{1}{48}} \  {\left( {2 \sp 2} \  {1 \sp 3} \right)}}
-{{\frac{1}{240}} \  {\left( {2 \sp {\ }} \  {1 \sp 5} \right)}}+
{{\frac{1}{5040}} \  {\left( 1 \sp 7 \right)}}
\end{array}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

The operation {\tt alternating} returns the cycle index of the alternating 
group having an even number of even parts in each cycle partition.

\spadcommand{alternating 7}
$$
\begin{array}{@{}l}
{{\frac{2}{7}} \  {\left( 7 \right)}}+
{{\frac{1}{5}} \  {\left( {5 \sp {\ }} \  {1 \sp 2} \right)}}+
{{\frac{1}{4}} \  {\left( {4 \sp {\ }} \  {2 \sp {\ }} \  1 \right)}}+
{{\frac{1}{9}} \  {\left( {3 \sp 2} \  1 \right)}}+
{{\frac{1}{12}} \  {\left( {3 \sp {\ }} \  {2 \sp 2} \right)}}+
{{\frac{1}{36}} \  {\left( {3 \sp {\ }} \  {1 \sp 4} \right)}}+
\\
\\
\displaystyle
{{\frac{1}{24}} \  {\left( {2 \sp 2} \  {1 \sp 3} \right)}}+
{{\frac{1}{2520}} \  {\left( 1 \sp 7 \right)}}
\end{array}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

The operation {\tt cyclic} returns the cycle index of the cyclic group.

\spadcommand{cyclic 7}
$$
{{\frac{6}{7}} \  {\left( 7 \right)}}+
{{\frac{1}{7}} \  {\left( 1 \sp 7 \right)}}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

%Original Page 341

The operation {\tt dihedral} is the cycle index of the
dihedral group.

\spadcommand{dihedral 7}
$$
{{\frac{3}{7}} \  {\left( 7 \right)}}+
{{\frac{1}{2}} \  {\left( {2 \sp 3} \  1 \right)}}+
{{\frac{1}{14}} \  {\left( 1 \sp 7 \right)}}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

The operation {\tt graphs} for argument {\tt n} returns the cycle
index of the group of permutations on the edges of the complete graph
with {\tt n} nodes induced by applying the symmetric group to the
nodes.

\spadcommand{graphs 5}
$$
\begin{array}{@{}l}
{{\frac{1}{6}} \  {\left( {6 \sp {\ }} \  {3 \sp {\ }} \  1 \right)}}+
{{\frac{1}{5}} \  {\left( 5 \sp 2 \right)}}+
{{\frac{1}{4}} \  {\left( {4 \sp 2} \  2 \right)}}+
{{\frac{1}{6}} \  {\left( {3 \sp 3} \  1 \right)}}+
{{\frac{1}{8}} \  {\left( {2 \sp 4} \  {1 \sp 2} \right)}}+
\\
\\
\displaystyle
{{\frac{1}{12}} \  {\left( {2 \sp 3} \  {1 \sp 4} \right)}}+
{{\frac{1}{120}} \  {\left( 1 \sp {10} \right)}}
\end{array}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

The cycle index of a direct product of two groups is the product of
the cycle indices of the groups.  Redfield provided two operations on
two cycle indices which will be called ``cup'' and ``cap'' here.  The
{\tt cup} of two cycle indices is a kind of scalar product that
combines monomials for permutations with the same cycles.  The {\tt
cap} operation provides the sum of the coefficients of the result of
the {\tt cup} operation which will be an integer that enumerates what
Redfield called group-reduced distributions.

We can, for example, represent {\tt complete 2 * complete 2} as the
set of objects {\tt a a b b} and 
{\tt complete 2 * complete 1 * complete 1} as {\tt c c d e.}

This integer is the number of different sets of four pairs.

\spadcommand{cap(complete 2**2, complete 2*complete 1**2)}
$$
4 
$$
\returnType{Type: Fraction Integer}

For example,
\begin{verbatim}
a a b b     a a b b    a a b b   a a b b
c c d e     c d c e    c e c d   d e c c
\end{verbatim}

This integer is the number of different sets of four pairs no two
pairs being equal.

\spadcommand{cap(elementary 2**2, complete 2*complete 1**2)}
$$
2 
$$
\returnType{Type: Fraction Integer}

For example,
\begin{verbatim}
a a b b    a a b b
c d c e    c e c d
\end{verbatim}
In this case the configurations enumerated are easily constructed,
however the theory merely enumerates them providing little help in
actually constructing them.

%Original Page 342

Here are the number of 6-pairs, first from {\tt a a a b b c,} second
from {\tt d d e e f g.}

\spadcommand{cap(complete 3*complete 2*complete 1,complete 2**2*complete 1**2)}
$$
24 
$$
\returnType{Type: Fraction Integer}

Here it is again, but with no equal pairs.

\spadcommand{cap(elementary 3*elementary 2*elementary 1,complete 2**2*complete 1**2)}
$$
8 
$$
\returnType{Type: Fraction Integer}

\spadcommand{cap(complete 3*complete 2*complete 1,elementary 2**2*elementary 1**2)}
$$
8 
$$
\returnType{Type: Fraction Integer}

The number of 6-triples, first from {\tt a a a b b c,} second from
{\tt d d e e f g,} third from {\tt h h i i j j.}

\spadcommand{eval(cup(complete 3*complete 2*complete 1, cup(complete 2**2*complete 1**2,complete 2**3)))}
$$
1500 
$$
\returnType{Type: Fraction Integer}

The cycle index of vertices of a square is dihedral 4.

\spadcommand{square:=dihedral 4}
$$
{{\frac{1}{4}} \  {\left( 4 \right)}}+
{{\frac{3}{8}} \  {\left( 2 \sp 2 \right)}}+
{{\frac{1}{4}} \  {\left( {2 \sp {\ }} \  {1 \sp 2} \right)}}+
{{\frac{1}{8}} \  {\left( 1 \sp 4 \right)}}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

The number of different squares with 2 red vertices and 2 blue vertices.

\spadcommand{cap(complete 2**2,square)}
$$
2 
$$
\returnType{Type: Fraction Integer}

The number of necklaces with 3 red beads, 2 blue beads and 2 green beads.

\spadcommand{cap(complete 3*complete 2**2,dihedral 7)}
$$
18 
$$
\returnType{Type: Fraction Integer}

The number of graphs with 5 nodes and 7 edges.

\spadcommand{cap(graphs 5,complete 7*complete 3)}
$$
4 
$$
\returnType{Type: Fraction Integer}

The cycle index of rotations of vertices of a cube.

\spadcommand{s(x) == powerSum(x)}
\returnType{Type: Void}

\spadcommand{cube:=(1/24)*(s 1**8+9*s 2**4 + 8*s 3**2*s 1**2+6*s 4**2)}
\begin{verbatim}
   Compiling function s with type PositiveInteger -> 
      SymmetricPolynomial Fraction Integer 
\end{verbatim}
$$
{{\frac{1}{4}} \  {\left( 4 \sp 2 \right)}}+
{{\frac{1}{3}} \  {\left( {3 \sp 2} \  {1 \sp 2} \right)}}+
{{\frac{3}{8}} \  {\left( 2 \sp 4 \right)}}+
{{\frac{1}{24}} \  {\left( 1 \sp 8 \right)}}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

%Original Page 343

The number of cubes with 4 red vertices and 4 blue vertices.

\spadcommand{cap(complete 4**2,cube)}
$$
7 
$$
\returnType{Type: Fraction Integer}

The number of labeled graphs with degree sequence {\tt 2 2 2 1 1}
with no loops or multiple edges.

\spadcommand{cap(complete 2**3*complete 1**2,wreath(elementary 4,elementary 2))}
$$
7 
$$
\returnType{Type: Fraction Integer}

Again, but with loops allowed but not multiple edges.

\spadcommand{cap(complete 2**3*complete 1**2,wreath(elementary 4,complete 2))}
$$
17 
$$
\returnType{Type: Fraction Integer}

Again, but with multiple edges allowed, but not loops

\spadcommand{cap(complete 2**3*complete 1**2,wreath(complete 4,elementary 2))}
$$
10 
$$
\returnType{Type: Fraction Integer}

Again, but with both multiple edges and loops allowed

\spadcommand{cap(complete 2**3*complete 1**2,wreath(complete 4,complete 2))}
$$
23 
$$
\returnType{Type: Fraction Integer}

Having constructed a cycle index for a configuration we are at liberty
to evaluate the $s_i$ components any way we please.  For example we
can produce enumerating generating functions.  This is done by
providing a function {\tt f} on an integer {\tt i} to the value
required of $s_i$, and then evaluating {\tt eval(f, cycleindex)}.

\spadcommand{x: ULS(FRAC INT,'x,0) := 'x }
$$
x 
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

\spadcommand{ZeroOrOne: INT -> ULS(FRAC INT, 'x, 0) }
\returnType{Type: Void}

\spadcommand{Integers: INT -> ULS(FRAC INT, 'x, 0) }
\returnType{Type: Void}

%Original Page 344

For the integers 0 and 1, or two colors.

\spadcommand{ZeroOrOne n == 1+x**n }
\returnType{Type: Void}

\spadcommand{ZeroOrOne 5 }
\begin{verbatim}
   Compiling function ZeroOrOne with type Integer -> 
      UnivariateLaurentSeries(Fraction Integer,x,0) 
\end{verbatim}
$$
1+{x \sp 5} 
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

For the integers {\tt 0, 1, 2, ...} we have this.

\spadcommand{Integers n == 1/(1-x**n) }
\returnType{Type: Void}

\spadcommand{Integers 5 }
\begin{verbatim}
   Compiling function Integers with type Integer -> 
      UnivariateLaurentSeries(Fraction Integer,x,0) 
\end{verbatim}
$$
1+{x \sp 5}+{O 
\left(
{{x \sp 8}} 
\right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The coefficient of $x^n$ is the number of graphs with 5 nodes and {\tt n}
edges. 

Note that there is an eval function that takes two arguments. It has the 
signature:
\begin{verbatim}
((Integer -> D1),SymmetricPolynomial Fraction Integer) -> D1
  from EvaluateCycleIndicators D1 if D1 has ALGEBRA FRAC INT
\end{verbatim}
This function is not normally exposed (it will not normally be considered
in the list of eval functions) as it is only useful for this particular
domain. To use it we ask that it be considered thus:

\spadcommand{)expose EVALCYC}

and now we can use it:

\spadcommand{eval(ZeroOrOne, graphs 5) }
$$
1+x+
{2 \  {x \sp 2}}+
{4 \  {x \sp 3}}+
{6 \  {x \sp 4}}+
{6 \  {x \sp 5}}+
{6 \  {x \sp 6}}+
{4 \  {x \sp 7}}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The coefficient of $x^n$ is the number of necklaces with
{\tt n} red beads and {\tt n-8} green beads.

\spadcommand{eval(ZeroOrOne,dihedral 8) }
$$
1+x+
{4 \  {x \sp 2}}+
{5 \  {x \sp 3}}+
{8 \  {x \sp 4}}+
{5 \  {x \sp 5}}+
{4 \  {x \sp 6}}+
{x \sp 7}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The coefficient of $x^n$ is the number of partitions of {\tt n} into 4
or fewer parts.

\spadcommand{eval(Integers,complete 4) }
$$
1+x+
{2 \  {x \sp 2}}+
{3 \  {x \sp 3}}+
{5 \  {x \sp 4}}+
{6 \  {x \sp 5}}+
{9 \  {x \sp 6}}+
{{11} \  {x \sp 7}}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The coefficient of $x^n$ is the number of partitions of {\tt n} into 4
boxes containing ordered distinct parts.

\spadcommand{eval(Integers,elementary 4) }
$$
{x \sp 6}+
{x \sp 7}+
{2 \  {x \sp 8}}+
{3 \  {x \sp 9}}+
{5 \  {x \sp {10}}}+
{6 \  {x \sp {11}}}+
{9 \  {x \sp {12}}}+
{{11} \  {x \sp {13}}}+
{O \left({{x \sp {14}}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The coefficient of $x^n$ is the number of different cubes with {\tt n}
red vertices and {\tt 8-n} green ones.

\spadcommand{eval(ZeroOrOne,cube) }
$$
1+x+
{3 \  {x \sp 2}}+
{3 \  {x \sp 3}}+
{7 \  {x \sp 4}}+
{3 \  {x \sp 5}}+
{3 \  {x \sp 6}}+
{x \sp 7}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The coefficient of $x^n$ is the number of different cubes with integers
on the vertices whose sum is {\tt n.}

\spadcommand{eval(Integers,cube) }
$$
1+x+
{4 \  {x \sp 2}}+
{7 \  {x \sp 3}}+
{{21} \  {x \sp 4}}+
{{37} \  {x \sp 5}}+
{{85} \  {x \sp 6}}+
{{151} \  {x \sp 7}}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

%Original Page 345

The coefficient of $x^n$ is the number of graphs with 5 nodes and with
integers on the edges whose sum is {\tt n.}  In other words, the
enumeration is of multigraphs with 5 nodes and {\tt n} edges.

\spadcommand{eval(Integers,graphs 5) }
$$
1+x+
{3 \  {x \sp 2}}+
{7 \  {x \sp 3}}+
{{17} \  {x \sp 4}}+
{{35} \  {x \sp 5}}+
{{76} \  {x \sp 6}}+
{{149} \  {x \sp 7}}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

Graphs with 15 nodes enumerated with respect to number of edges.

\spadcommand{eval(ZeroOrOne ,graphs 15) }
$$
1+x+
{2 \  {x \sp 2}}+
{5 \  {x \sp 3}}+
{{11} \  {x \sp 4}}+
{{26} \  {x \sp 5}}+
{{68} \  {x \sp 6}}+
{{177} \  {x \sp 7}}+
{O \left({{x \sp 8}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

Necklaces with 7 green beads, 8 white beads, 5 yellow beads and 10
red beads.

\spadcommand{cap(dihedral 30,complete 7*complete 8*complete 5*complete 10)}
$$
49958972383320 
$$
\returnType{Type: Fraction Integer}

The operation {\tt SFunction} is the S-function or Schur function of a
partition written as a descending list of integers expressed in terms
of power sum symmetric functions.

In this case the argument partition represents a tableau shape.  For
example {\tt 3,2,2,1} represents a tableau with three boxes in the
first row, two boxes in the second and third rows, and one box in the
fourth row.  {\tt SFunction [3,2,2,1]} counts the number of different
tableaux of shape {\tt 3, 2, 2, 1} filled with objects with an
ascending order in the columns and a non-descending order in the rows.

\spadcommand{sf3221:= SFunction [3,2,2,1] }
$$
\begin{array}{@{}l}
{{\frac{1}{12}} \  {\left( {6 \sp {\ }} \  2 \right)}}
-{{\frac{1}{12}} \  {\left( {6 \sp {\ }} \  {1 \sp 2} \right)}}
-{{\frac{1}{16}} \  {\left( 4 \sp 2 \right)}}+
{{\frac{1}{12}} \  {\left( {4 \sp {\ }} \  {3 \sp {\ }} \  1 \right)}}+
{{\frac{1}{24}} \  {\left( {4 \sp {\ }} \  {1 \sp 4} \right)}}
-{{\frac{1}{36}} \  {\left( {3 \sp 2} \  2 \right)}}+
\\
\\
\displaystyle
{{\frac{1}{36}} \  {\left( {3 \sp 2} \  {1 \sp 2} \right)}}
-{{\frac{1}{24}} \  {\left( {3 \sp {\ }} \  {2 \sp 2} \  1 \right)}}
-{{\frac{1}{36}} \  {\left( {3 \sp {\ }} \  {2 \sp {\ }} \  {1 \sp 3} \right)}}
-{{\frac{1}{72}} \  {\left( {3 \sp {\ }} \  {1 \sp 5} \right)}}
-{{\frac{1}{192}} \  {\left( 2 \sp 4 \right)}}+
\\
\\
\displaystyle
{{\frac{1}{48}} \  {\left( {2 \sp 3} \  {1 \sp 2} \right)}}+
{{\frac{1}{96}} \  {\left( {2 \sp 2} \  {1 \sp 4} \right)}}
-{{\frac{1}{144}} \  {\left( {2 \sp {\ }} \  {1 \sp 6} \right)}}+
{{\frac{1}{576}} \  {\left( 1 \sp 8 \right)}}
\end{array}
$$
\returnType{Type: SymmetricPolynomial Fraction Integer}

This is the number filled with {\tt a a b b c c d d.}

\spadcommand{cap(sf3221,complete 2**4) }
$$
3 
$$
\returnType{Type: Fraction Integer}

The configurations enumerated above are:
\begin{verbatim}
a a b    a a c    a a d
b c      b b      b b
c d      c d      c c
d        d        d
\end{verbatim}

This is the number of tableaux filled with {\tt 1..8.}

\spadcommand{cap(sf3221, powerSum 1**8)}
$$
70 
$$
\returnType{Type: Fraction Integer}

%Original Page 346

The coefficient of $x^n$ is the number of column strict reverse plane
partitions of {\tt n} of shape {\tt 3 2 2 1.}

\spadcommand{eval(Integers, sf3221)}
$$
{x \sp 9}+
{3 \  {x \sp {10}}}+
{7 \  {x \sp {11}}}+
{{14} \  {x \sp {12}}}+
{{27} \  {x \sp {13}}}+
{{47} \  {x \sp {14}}}+
{O \left({{x \sp {15}}} \right)}
$$
\returnType{Type: UnivariateLaurentSeries(Fraction Integer,x,0)}

The smallest is
\begin{verbatim}
0 0 0
1 1
2 2
3
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{DeRhamComplex}

The domain constructor {\tt DeRhamComplex} creates the class of
differential forms of arbitrary degree over a coefficient ring.  The
De Rham complex constructor takes two arguments: a ring, {\tt
coefRing,} and a list of coordinate variables.

This is the ring of coefficients.

\spadcommand{coefRing := Integer }
$$
Integer 
$$
\returnType{Type: Domain}

These are the coordinate variables.

\spadcommand{lv : List Symbol := [x,y,z] }
$$
\left[
x, y, z 
\right]
$$
\returnType{Type: List Symbol}

This is the De Rham complex of Euclidean three-space using coordinates
{\tt x, y} and {\tt z.}

\spadcommand{der := DERHAM(coefRing,lv) }
$$
DeRhamComplex(Integer,[x,y,z]) 
$$
\returnType{Type: Domain}
 
This complex allows us to describe differential forms having
expressions of integers as coefficients.  These coefficients can
involve any number of variables, for example, {\tt f(x,t,r,y,u,z).}
As we've chosen to work with ordinary Euclidean three-space,
expressions involving these forms are treated as functions of 
{\tt x, y} and {\tt z} with the additional arguments {\tt t, r} 
and {\tt u} regarded as symbolic constants.

Here are some examples of coefficients.

\spadcommand{R := Expression coefRing }
$$
\mbox{\rm Expression Integer} 
$$
\returnType{Type: Domain}

\spadcommand{f : R := x**2*y*z-5*x**3*y**2*z**5 }
$$
-{5 \  {x \sp 3} \  {y \sp 2} \  {z \sp 5}}+{{x \sp 2} \  y \  z} 
$$
\returnType{Type: Expression Integer}

%Original Page 347

\spadcommand{g : R := z**2*y*cos(z)-7*sin(x**3*y**2)*z**2 }
$$
-{7 \  {z \sp 2} \  {\sin \left({{{x \sp 3} \  {y \sp 2}}} \right)}}+
{y\  {z \sp 2} \  {\cos \left({z} \right)}}
$$
\returnType{Type: Expression Integer}

\spadcommand{h : R :=x*y*z-2*x**3*y*z**2 }
$$
-{2 \  {x \sp 3} \  y \  {z \sp 2}}+{x \  y \  z} 
$$
\returnType{Type: Expression Integer}

We now define the multiplicative basis elements for the exterior
algebra over {\tt R}.

\spadcommand{dx : der := generator(1) }
$$
dx 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

\spadcommand{dy : der := generator(2)}
$$
dy 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

\spadcommand{dz : der := generator(3)}
$$
dz 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

This is an alternative way to give the above assignments.

\spadcommand{[dx,dy,dz] := [generator(i)\$der for i in 1..3] }
$$
\left[
dx, dy, dz 
\right]
$$
\returnType{Type: List DeRhamComplex(Integer,[x,y,z])}

Now we define some one-forms.

\spadcommand{alpha : der := f*dx + g*dy + h*dz }
$$
\begin{array}{@{}l}
{{\left( -{2 \  {x \sp 3} \  y \  {z \sp 2}}+{x \  y \  z} \right)}\  dz}+
\\
\\
\displaystyle
{{\left( 
-{7 \  {z \sp 2} \  {\sin \left({{{x \sp 3} \  {y \sp 2}}} \right)}}+
{y\  {z \sp 2} \  {\cos \left({z} \right)}}
\right)}\  dy}+
\\
\\
\displaystyle
{{\left( -{5 \  {x \sp 3} \  {y \sp 2} \  {z \sp 5}}+{{x \sp 2} \  y \  z} 
\right)}\  dx} 
\end{array}
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

\spadcommand{beta  : der := cos(tan(x*y*z)+x*y*z)*dx + x*dy }
$$
{x \  dy}+
{{\cos 
\left({{{\tan \left({{x \  y \  z}} \right)}+{x\  y \  z}}} \right)}
\  dx} 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

A well-known theorem states that the composition of
\spadfunFrom{exteriorDifferential}{DeRhamComplex} with itself is the
zero map for continuous forms.  Let's verify this theorem for {\tt alpha}.

\spadcommand{exteriorDifferential alpha }
$$
\begin{array}{@{}l}
{{\left( 
{y \  {z \sp 2} \  {\sin \left({z} \right)}}+
{{14}\  z \  {\sin \left({{{x \sp 3} \  {y \sp 2}}} \right)}}
-{2 \  y \  z \  {\cos \left({z} \right)}}
-{2 \  {x \sp 3} \  {z \sp 2}}+{x \  z} \right)}\  dy \  dz}+
\\
\\
\displaystyle
{{\left( 
{{25} \  {x \sp 3} \  {y \sp 2} \  {z \sp 4}} -
{6 \  {x \sp 2} \  y \  {z \sp 2}}+
{y \  z} -
{{x \sp 2} \  y} 
\right)}\  dx \  dz}+
\\
\\
\displaystyle
{{\left( 
-{{21} \  {x \sp 2} \  {y \sp 2} \  {z \sp 2} \  
{\cos \left({{{x \sp 3} \  {y \sp 2}}} \right)}}+
{{10}\  {x \sp 3} \  y \  {z \sp 5}} -{{x \sp 2} \  z} \right)}\  dx \  dy} 
\end{array}
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

%Original Page 348

We see a lengthy output of the last expression, but nevertheless, the
composition is zero.

\spadcommand{exteriorDifferential \% }
$$
0 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

Now we check that \spadfunFrom{exteriorDifferential}{DeRhamComplex}
is a ``graded derivation'' {\tt D,} that is, {\tt D} satisfies:
\begin{verbatim}
D(a*b) = D(a)*b + (-1)**degree(a)*a*D(b)
\end{verbatim}

\spadcommand{gamma := alpha * beta }
$$
\begin{array}{@{}l}
{{\left( 
{2 \  {x \sp 4} \  y \  {z \sp 2}} -
{{x \sp 2} \  y \  z} 
\right)}\  dy \  dz}+
\\
\\
\displaystyle
{{\left( 
{2 \  {x \sp 3} \  y \  {z \sp 2}} -{x \  y \  z} 
\right)}
\  {\cos 
\left(
{{{\tan \left({{x \  y \  z}} \right)}+
{x\  y \  z}}} 
\right)}\  dx \  dz}+
\\
\\
\displaystyle
\left( 
{{\left( 
{7 \  {z \sp 2} \  {\sin \left({{{x \sp 3} \  {y \sp 2}}} \right)}}
-{y \  {z \sp 2} \  {\cos \left({z} \right)}}
\right)}
\  {\cos \left({{{\tan \left({{x \  y \  z}} \right)}+{x\  y \  z}}} \right)}}-
\right.
\\
\\
\left.
\displaystyle
{5 \  {x \sp 4} \  {y \sp 2} \  {z \sp 5}}+
{{x \sp 3} \  y \  z} 
\right)\  dx \  dy
\end{array}
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

We try this for the one-forms {\tt alpha} and {\tt beta}.

\spadcommand{exteriorDifferential(gamma) - (exteriorDifferential(alpha)*beta - alpha * exteriorDifferential(beta)) }
$$
0 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

Now we define some ``basic operators'' (see \domainref{Operator}).

\spadcommand{a : BOP := operator('a) }
$$
a 
$$
\returnType{Type: BasicOperator}

\spadcommand{b : BOP := operator('b) }
$$
b 
$$
\returnType{Type: BasicOperator}

\spadcommand{c : BOP := operator('c) }
$$
c 
$$
\returnType{Type: BasicOperator}

We also define some indeterminate one- and two-forms using these
operators.

\spadcommand{sigma := a(x,y,z) * dx + b(x,y,z) * dy + c(x,y,z) * dz }
$$
{{c \left({x, y, z} \right)}\  dz}+
{{b \left({x, y, z} \right)}\  dy}+
{{a \left({x, y, z} \right)}\  dx} 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

\spadcommand{theta  := a(x,y,z) * dx * dy + b(x,y,z) * dx * dz + c(x,y,z) * dy * dz }
$$
{{c \left({x, y, z} \right)}\  dy \  dz}+
{{b \left({x, y, z} \right)}\  dx \  dz}+
{{a \left({x, y, z} \right)}\  dx \  dy} 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

%Original Page 349

This allows us to get formal definitions for the ``gradient'' \ldots

\spadcommand{totalDifferential(a(x,y,z))\$der }
$$
{{{a \sb {{,3}}} \left({x, y, z} \right)}\  dz}+
{{{a \sb {{,2}}} \left({x, y, z} \right)}\  dy}+
{{{a \sb {{,1}}} \left({x, y, z} \right)}\  dx} 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

the ``curl'' \ldots

\spadcommand{exteriorDifferential sigma }
$$
\begin{array}{@{}l}
{{\left( 
{{c \sb {{,2}}} \left({x, y, z} \right)}
-{{b \sb {{,3}}} \left({x, y, z} \right)}
\right)}\  dy \  dz}+
\\
\\
\displaystyle
{{\left( 
{{c \sb {{,1}}} \left({x, y, z} \right)}
-{{a \sb {{,3}}} \left({x, y, z} \right)}
\right)}\  dx \  dz}+
\\
\\
\displaystyle
{{\left( 
{{b \sb {{,1}}} \left({x, y, z} \right)}
-{{a \sb {{,2}}} \left({x, y, z} \right)}
\right)}\  dx \  dy} 
\end{array}
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

and the ``divergence.''

\spadcommand{exteriorDifferential theta }
$$
{\left( 
{{c \sb {{,1}}} \left({x, y, z} \right)}
-{{b \sb {{,2}}} \left({x, y, z} \right)}+
{{a\sb {{,3}}} \left({x, y, z} \right)}
\right)}\  dx \  dy \  dz 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

Note that the De Rham complex is an algebra with unity.  This element
{\tt 1} is the basis for elements for zero-forms, that is, functions
in our space.

\spadcommand{one : der := 1 }
$$
1 
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

To convert a function to a function lying in the De Rham complex,
multiply the function by ``one.''

\spadcommand{g1 : der := a([x,t,y,u,v,z,e]) * one }
$$
a 
\left(
{x, t, y, u, v, z, e} 
\right)
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

A current limitation of Axiom forces you to write functions with more
than four arguments using square brackets in this way.

\spadcommand{h1 : der := a([x,y,x,t,x,z,y,r,u,x]) * one }
$$
a 
\left(
{x, y, x, t, x, z, y, r, u, x} 
\right)
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

Now note how the system keeps track of where your coordinate functions
are located in expressions.

\spadcommand{exteriorDifferential g1 }
$$
\begin{array}{@{}l}
{{{a \sb {{,6}}} \left({x, t, y, u, v, z, e} \right)}\  dz}+
\\
\\
\displaystyle
{{{a \sb {{,3}}} \left({x, t, y, u, v, z, e} \right)}\  dy}+
\\
\\
\displaystyle
{{{a \sb {{,1}}} \left({x, t, y, u, v, z, e} \right)}\  dx} 
\end{array}
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

%Original Page 350

\spadcommand{exteriorDifferential h1 }
$$
\begin{array}{@{}l}
{{{a \sb {{,6}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}\  dz}+
\\
\\
\displaystyle
\begin{array}{@{}l}
\left( {{a \sb {{,7}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}+
\right.
\\
\\
\displaystyle
\left.
{{a\sb {{,2}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}
\right)\  dy+
\end{array}
\\
\\
\displaystyle
\begin{array}{@{}l}
\left( {{a \sb {{,{10}}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}+
\right.
\\
\\
\displaystyle
{{a\sb {{,5}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}+
\\
\\
\displaystyle
{{a\sb {{,3}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}+
\\
\\
\displaystyle
\left.
{{a\sb {{,1}}} 
\left({x, y, x, t, x, z, y, r, u, x} \right)}
\right)\  dx 
\end{array}
\end{array}
$$
\returnType{Type: DeRhamComplex(Integer,[x,y,z])}

In this example of Euclidean three-space, the basis for the De Rham complex
consists of the eight forms: {\tt 1}, {\tt dx}, {\tt dy}, {\tt dz},
{\tt dx*dy}, {\tt dx*dz}, {\tt dy*dz}, and {\tt dx*dy*dz}.

\spadcommand{coefficient(gamma, dx*dy) }
$$
\begin{array}{@{}l}
{{\left( {7 \  {z \sp 2} \  {\sin \left({{{x \sp 3} \  {y \sp 2}}} \right)}}
-{y \  {z \sp 2} \  {\cos \left({z} \right)}}\right)}\  {\cos 
\left(
{{{\tan \left({{x \  y \  z}} \right)}+
{x\  y \  z}}} 
\right)}}
\\
\\
\displaystyle
-{5 \  {x \sp 4} \  {y \sp 2} \  {z \sp 5}}+
{{x \sp 3} \  y \  z} 
\end{array}
$$
\returnType{Type: Expression Integer}

\spadcommand{coefficient(gamma, one) }
$$
0 
$$
\returnType{Type: Expression Integer}

\spadcommand{coefficient(g1,one) }
$$
a 
\left(
{x, t, y, u, v, z, e} 
\right)
$$
\returnType{Type: Expression Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{DecimalExpansion}

All rationals have repeating decimal expansions.  Operations to access
the individual digits of a decimal expansion can be obtained by
converting the value to {\tt RadixExpansion(10)}.  More examples of
expansions are available in \domainref{BinaryExpansion},\\ 
\domainref{HexadecimalExpansion}, and \domainref{RadixExpansion}.

The operation \spadfunFrom{decimal}{DecimalExpansion} is used to create
this expansion of type {\tt DecimalExpansion}.

\spadcommand{r := decimal(22/7) }
$$
3.{\overline {142857}} 
$$
\returnType{Type: DecimalExpansion}

%Original Page 351

Arithmetic is exact.

\spadcommand{r + decimal(6/7) }
$$
4 
$$
\returnType{Type: DecimalExpansion}

The period of the expansion can be short or long \ldots

\spadcommand{[decimal(1/i) for i in 350..354] }
$$
\begin{array}{@{}l}
\left[
{0.{00}{\overline {285714}}}, 
{0.{\overline {002849}}}, 
{0.{00284}{\overline {09}}}, 
{0.{\overline {00283286118980169971671388101983}}}, 
\right.
\\
\\
\displaystyle
\left.
{0.0{\overline {0282485875706214689265536723163841807909604519774011299435}}} 
\right]
\end{array}
$$
\returnType{Type: List DecimalExpansion}

or very long.

\spadcommand{decimal(1/2049) }
$$
\begin{array}{@{}l}
0.{\overline 
{000488042947779404587603709126403123474865788189360663738408979990239}}
\\
\\
\displaystyle
\ \ {\overline{
141044411908247925817471937530502684236212786725231820400195217179111}}
\\
\\
\displaystyle
\ \ {\overline{
761835041483650561249389946315275744265495363591996095656417764763299}}
\\
\\
\displaystyle
\ \ {\overline{
170326988775012201073694485114690092728160078086871644704734016593460}}
\\
\\
\displaystyle
\ \ {\overline{
22449975597852611029770619814543679843826256710590531966813079551}}
\end{array}
$$
\returnType{Type: DecimalExpansion}

These numbers are bona fide algebraic objects.

\spadcommand{p := decimal(1/4)*x**2 + decimal(2/3)*x + decimal(4/9)  }
$$
{{0.{25}} \  {x \sp 2}}+{{0.{\overline 6}} \  x}+{0.{\overline 4}} 
$$
\returnType{Type: Polynomial DecimalExpansion}

\spadcommand{q := differentiate(p, x) }
$$
{{0.5} \  x}+{0.{\overline 6}} 
$$
\returnType{Type: Polynomial DecimalExpansion}

\spadcommand{g := gcd(p, q) }
$$
x+{1.{\overline 3}} 
$$
\returnType{Type: Polynomial DecimalExpansion}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Dequeue}

A Dequeue is a double-ended queue so elements can be added to either end.

Here we create an dequeue of integers from a list. Notice that the
order in the list is the order in the dequeue.
\begin{verbatim}
   a:Dequeue INT:= dequeue [1,2,3,4,5]
      [1,2,3,4,5]
\end{verbatim}
We can remove the top of the dequeue using dequeue!:
\begin{verbatim}
   dequeue! a
      1
\end{verbatim}
Notice that the use of dequeue! is destructive (destructive operations
in Axiom usually end with ! to indicate that the underylying data
structure is changed).
\begin{verbatim}
   a
      [2,3,4,5]
\end{verbatim}
The extract! operation is another name for the dequeue! operation and
has the same effect. This operation treats the dequeue as a BagAggregate:
\begin{verbatim}
   extract! a
      2
\end{verbatim}
and you can see that it also has destructively modified the dequeue:
\begin{verbatim}
   a
      [3,4,5]
\end{verbatim}
Next we use enqueue! to add a new element to the end of the dequeue:
\begin{verbatim}
   enqueue!(9,a)
      9
\end{verbatim}
Again, the enqueue! operation is destructive so the dequeue is changed:
\begin{verbatim}
   a
      [3,4,5,9]
\end{verbatim}
Another name for enqueue! is insert!, which treats the dequeue as a 
BagAggregate:
\begin{verbatim}
   insert!(8,a)
      [3,4,5,9,8]
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [3,4,5,9,8]
\end{verbatim}
The front operation returns the item at the front of the dequeue:
\begin{verbatim}
   front a
      3
\end{verbatim}
The back operation returns the item at the back of the dequeue:
\begin{verbatim}
   back a
      8
\end{verbatim}
The bottom! operation returns the item at the back of the dequeue:
\begin{verbatim}
   bottom! a
      8
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [3,4,5,9]
\end{verbatim}
The depth function returns the number of elements in the dequeue:
\begin{verbatim}
   depth a
      4
\end{verbatim}
The height function returns the number of elements in the dequeue:
\begin{verbatim}
   height a
      4
\end{verbatim}
The insertBottom! function adds the element at the end:
\begin{verbatim}
   insertBottom!(6,a)
      6
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [3,4,5,9,6]
\end{verbatim}
The extractBottom! function removes the element at the end:
\begin{verbatim}
   extractBottom! a
      6
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [3,4,5,9]
\end{verbatim}
The insertTop! function adds the element at the top:
\begin{verbatim}
   insertTop!(7,a)
      7
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [7,3,4,5,9]
\end{verbatim}
The extractTop! function adds the element at the top:
\begin{verbatim}
   extractTop! a
      7
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [3,4,5,9]
\end{verbatim}
The top function returns the top element:
\begin{verbatim}
   top a
      3
\end{verbatim}
and it does not modifies the dequeue:
\begin{verbatim}
   a
      [3,4,5,9]
\end{verbatim}
The top! function returns the top element:
\begin{verbatim}
   top! a
      3
\end{verbatim}
and it modifies the dequeue:
\begin{verbatim}
   a
      [4,5,9]
\end{verbatim}
The reverse! operation destructively reverses the elements of the dequeue:
\begin{verbatim}
   reverse! a
      [9,5,4]
\end{verbatim}
The rotate! operation moves the top element to the bottom:
\begin{verbatim}
   rotate! a
      [5,4,9]
\end{verbatim}
The inspect function returns the top of the dequeue without modification,
viewed as a BagAggregate:
\begin{verbatim}
   inspect a
      5
\end{verbatim}
The empty? operation returns true only if there are no element on the
dequeue, otherwise it returns false:
\begin{verbatim}
   empty? a
      false
\end{verbatim}
The \# (length) operation:
\begin{verbatim}
   #a
       3
\end{verbatim}
The length operation does the same thing:
\begin{verbatim}
   length a
       3
\end{verbatim}
The less? predicate will compare the dequeue length to an integer:
\begin{verbatim}
   less?(a,9)
        true
\end{verbatim}
The more? predicate will compare the dequeue length to an integer:
\begin{verbatim}
   more?(a,9)
        false
\end{verbatim}
The size? operation will compare the dequeue length to an integer:
\begin{verbatim}
   size?(a,#a)
        true
\end{verbatim}
and since the last computation must alwasy be true we try:
\begin{verbatim}
   size?(a,9)
        false
\end{verbatim}
The parts function will return  the dequeue as a list of its elements:
\begin{verbatim}
   parts a
        [5,4,9]
\end{verbatim}
If we have a BagAggregate of elements we can use it to construct a dequeue:
\begin{verbatim}
   bag([1,2,3,4,5])$Dequeue(INT)
        [1,2,3,4,5]
\end{verbatim}
The empty function will construct an empty dequeue of a given type:
\begin{verbatim}
   b:=empty()$(Dequeue INT)
        []
\end{verbatim}
and the empty? predicate allows us to find out if a dequeue is empty:
\begin{verbatim}
   empty? b
        true
\end{verbatim}
The sample function returns a sample, empty dequeue:
\begin{verbatim}
   sample()$Dequeue(INT)
        []
\end{verbatim}
We can copy a dequeue and it does not share storage so subsequent
modifications of the original dequeue will not affect the copy:
\begin{verbatim}
   c:=copy a
        [5,4,9]
\end{verbatim}
The eq? function is only true if the lists are the same reference,
so even though c is a copy of a, they are not the same:
\begin{verbatim}
   eq?(a,c)
        false
\end{verbatim}
However, a clearly shares a reference with itself:
\begin{verbatim}
   eq?(a,a)
        true
\end{verbatim}
But we can compare a and c for equality:
\begin{verbatim}
   (a=c)@Boolean
        true
\end{verbatim}
and clearly a is equal to itself:
\begin{verbatim}
   (a=a)@Boolean
        true
\end{verbatim}
and since a and c are equal, they are clearly NOT not-equal:
\begin{verbatim}
   a~=c
        false
\end{verbatim}
We can use the any? function to see if a predicate is true for any element:
\begin{verbatim}
   any?(x+->(x=4),a)
        true
\end{verbatim}
or false for every element:
\begin{verbatim}
   any?(x+->(x=11),a)
        false
\end{verbatim}
We can use the every? function to check every element satisfies a predicate:
\begin{verbatim}
   every?(x+->(x=11),a)
        false
\end{verbatim}
We can count the elements that are equal to an argument of this type:
\begin{verbatim}
   count(4,a)
        1
\end{verbatim}
or we can count against a boolean function:
\begin{verbatim}
   count(x+->(x>2),a)
        3
\end{verbatim}
You can also map a function over every element, returning a new dequeue:
\begin{verbatim}
   map(x+->x+10,a)
        [15,14,19]
\end{verbatim}
Notice that the orignal dequeue is unchanged:
\begin{verbatim}
   a
        [5,4,9]
\end{verbatim}
You can use map! to map a function over every element and change
the original dequeue since map! is destructive:
\begin{verbatim}
   map!(x+->x+10,a)
       [15,14,19]
\end{verbatim}
Notice that the orignal dequeue has been changed:
\begin{verbatim}
   a
       [15,14,19]
\end{verbatim}
The member function can also get the element of the dequeue as a list:
\begin{verbatim}
   members a
       [15,14,19]
\end{verbatim}
and using member? we can test if the dequeue holds a given element:
\begin{verbatim}
   member?(14,a)
       true
\end{verbatim}

See \domainref{Stack}, \domainref{ArrayStack}, \domainref{Queue},
\domainref{Dequeue}, \domainref{Heap}.

%Original Page 352

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{DistributedMultivariatePolynomial}

\hyphenation{Homo-gen-eous-Dis-tributed-Multi-var-i-ate-Pol-y-nomial}

{\tt DistributedMultivariatePolynomial} which is abbreviated as {\tt DMP}\\
and {\tt Homogeneous\-Distributed\-MultivariatePolynomial},\\ 
which is abbreviated
as {\tt HDMP}, are very similar to {\tt Multivariate\-Polynomial} except that 
they are represented and displayed in a non-recursive manner.

\spadcommand{(d1,d2,d3) : DMP([z,y,x],FRAC INT) }
\returnType{Type: Void}

The constructor {\tt DMP} orders its monomials lexicographically while
{\tt HDMP} orders them by total order refined by reverse lexicographic
order.

\spadcommand{d1 := -4*z + 4*y**2*x + 16*x**2 + 1 }
$$
-{4 \  z}+{4 \  {y \sp 2} \  x}+{{16} \  {x \sp 2}}+1 
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

\spadcommand{d2 := 2*z*y**2 + 4*x + 1 }
$$
{2 \  z \  {y \sp 2}}+{4 \  x}+1 
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

\spadcommand{d3 := 2*z*x**2 - 2*y**2 - x }
$$
{2 \  z \  {x \sp 2}} -{2 \  {y \sp 2}} -x 
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

These constructors are mostly used in Gr\"{o}bner basis calculations.

\spadcommand{groebner [d1,d2,d3] }
$$
\begin{array}{@{}l}
\displaystyle
\left[
{z -
{{\frac{1568}{2745}} \  {x \sp 6}} -
{{\frac{1264}{305}} \  {x \sp 5}}+
{{\frac{6}{305}} \  {x \sp 4}}+
{{\frac{182}{549}} \  {x \sp 3}} 
-{{\frac{2047}{610}} \  {x \sp 2}} -
{{\frac{103}{2745}} \  x} -
{\frac{2857}{10980}}}, 
\right.
\\
\\
\displaystyle
{{y \sp 2}+
{{\frac{112}{2745}} \  {x \sp 6}} -
{{\frac{84}{305}} \  {x \sp 5}} -
{{\frac{1264}{305}} \  {x \sp 4}} -
{{\frac{13}{549}} \  {x \sp 3}}+
{{\frac{84}{305}} \  {x \sp 2}}+
{{\frac{1772}{2745}} \  x}+
{\frac{2}{2745}}}, 
\\
\\
\displaystyle
\left.
{{x \sp 7}+
{{\frac{29}{4}} \  {x \sp 6}} -
{{\frac{17}{16}} \  {x \sp 4}} -
{{\frac{11}{8}} \  {x \sp 3}}+
{{\frac{1}{32}} \  {x \sp 2}}+
{{\frac{15}{16}} \  x}+
{\frac{1}{4}}} 
\right]
\end{array}
$$
\returnType{Type: List DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

\spadcommand{(n1,n2,n3) : HDMP([z,y,x],FRAC INT) }
\returnType{Type: Void}

\spadcommand{n1 := d1 }
$$
{4 \  {y \sp 2} \  x}+{{16} \  {x \sp 2}} -{4 \  z}+1 
$$
\returnType{Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

\spadcommand{n2 := d2 }
$$
{2 \  z \  {y \sp 2}}+{4 \  x}+1 
$$
\returnType{Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

\spadcommand{n3 := d3 }
$$
{2 \  z \  {x \sp 2}} -{2 \  {y \sp 2}} -x 
$$
\returnType{Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

%Original Page 353

Note that we get a different Gr\"{o}bner basis when we use the 
{\tt HDMP} polynomials, as expected.

\spadcommand{groebner [n1,n2,n3] }
$$
\begin{array}{@{}l}
\displaystyle
\left[
{{y \sp 4}+
{2 \  {x \sp 3}} -
{{\frac{3}{2}} \  {x \sp 2}}+
{{\frac{1}{2}} \  z} -
{\frac{1}{8}}}, 
\right.
\\
\\
\displaystyle
{{x \sp 4}+
{{\frac{29}{4}} \  {x \sp 3}} -
{{\frac{1}{8}} \  {y \sp 2}} -
{{\frac{7}{4}} \  z \  x} -
{{\frac{9}{16}} \  x} -
{\frac{1}{4}}}, 
\\
\\
\displaystyle
{{z \  {y \sp 2}}+
{2 \  x}+
{\frac{1}{2}}}, 
\\
\\
\displaystyle
{{{y \sp 2} \  x}+
{4 \  {x \sp 2}} -
z+
{\frac{1}{4}}},
\\
\\
\displaystyle
{{z \  {x \sp 2}} -
{y \sp 2} -
{{\frac{1}{2}} \  x}},
\\
\\
\displaystyle
\left.
{{z \sp 2} -
{4 \  {y \sp 2}}+
{2 \  {x \sp 2}} -
{{\frac{1}{4}} \  z} -
{{\frac{3}{2}} \  x}} 
\right]
\end{array}
$$
\returnType{Type: List HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

{\tt GeneralDistributedMultivariatePolynomial} is somewhat
more flexible in the sense that as well as accepting a list of
variables to specify the variable ordering, it also takes a
predicate on exponent vectors to specify the term ordering.
With this polynomial type the user can experiment with the effect
of using completely arbitrary term orderings.
This flexibility is mostly important for algorithms such as
Gr\"{o}bner basis calculations which can be very
sensitive to term ordering.

For more information on related topics, see\\
\sectionref{ugIntroVariables},
\sectionref{ugTypesConvert},\\
\domainref{Polynomial}, \domainref{UnivariatePolynomial},\\ 
and \domainref{MultivariatePolynomial}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{DoubleFloat}

Axiom provides two kinds of floating point numbers.  The domain 
{\tt Float} (abbreviation {\tt FLOAT}) implements a model of arbitrary
precision floating point numbers.  The domain {\tt DoubleFloat}
(abbreviation {\tt DFLOAT}) is intended to make available hardware
floating point arithmetic in Axiom.  The actual model of floating
point {\tt DoubleFloat} that provides is system-dependent.  For
example, on the IBM system 370 Axiom uses IBM double precision which
has fourteen hexadecimal digits of precision or roughly sixteen
decimal digits.  Arbitrary precision floats allow the user to specify
the precision at which arithmetic operations are computed.  Although
this is an attractive facility, it comes at a cost. Arbitrary-precision 
floating-point arithmetic typically takes twenty to two hundred times 
more time than hardware floating point.

The usual arithmetic and elementary functions are available for 
{\tt DoubleFloat}.  Use {\tt )show DoubleFloat} to get a list of operations
or the HyperDoc browse facility to get more extensive documentation
about {\tt DoubleFloat}.

By default, floating point numbers that you enter into Axiom are of
type {\tt Float}.

\spadcommand{2.71828}
$$
2.71828 
$$
\returnType{Type: Float}

You must therefore tell Axiom that you want to use {\tt DoubleFloat}
values and operations.  The following are some conservative guidelines
for getting Axiom to use {\tt DoubleFloat}.

To get a value of type {\tt DoubleFloat}, use a target with {\tt @}, \ldots

\spadcommand{2.71828@DoubleFloat}
$$
2.71828 
$$
\returnType{Type: DoubleFloat}

a conversion, \ldots

\spadcommand{2.71828 :: DoubleFloat}
$$
2.71828 
$$
\returnType{Type: DoubleFloat}

or an assignment to a declared variable.  It is more efficient if you
use a target rather than an explicit or implicit conversion.

\spadcommand{eApprox : DoubleFloat := 2.71828 }
$$
2.71828 
$$
\returnType{Type: DoubleFloat}

You also need to declare functions that work with {\tt DoubleFloat}.

\spadcommand{avg : List DoubleFloat -> DoubleFloat }
\returnType{Type: Void}

\begin{verbatim}
avg l ==
  empty? l => 0 :: DoubleFloat
  reduce(_+,l) / #l
\end{verbatim}
\returnType{Type: Void}

%\spadcommand{avg [] }
% this complains but succeeds

\spadcommand{avg [3.4,9.7,-6.8] }
\begin{verbatim}
   Compiling function avg with type List Float -> DoubleFloat 

\end{verbatim}
$$
2.1 
$$
\returnType{Type: DoubleFloat}

Use package-calling for operations from {\tt DoubleFloat} unless
the arguments themselves are already of type {\tt DoubleFloat}.

\spadcommand{cos(3.1415926)\$DoubleFloat}
$$
-{0.999999999999999} 
$$
\returnType{Type: DoubleFloat}

\spadcommand{cos(3.1415926 :: DoubleFloat)}
$$
-{0.999999999999999} 
$$
\returnType{Type: DoubleFloat}

By far, the most common usage of {\tt DoubleFloat} is for functions to
be graphed.  For more information about Axiom's numerical and
graphical facilities, see Section
\sectionref{ugGraph}, \sectionref{ugProblemNumeric}, and \domainref{Float}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{EqTable} 

The {\tt EqTable} domain provides tables where the keys are compared
using \spadfunFrom{eq?}{EqTable}.  Keys are considered equal only if
they are the same instance of a structure.  This is useful if the keys
are themselves updatable structures.  Otherwise, all operations are
the same as for type {\tt Table}.  See 
\domainref{Table} for general information about tables.

The operation \spadfunFrom{table}{EqTable} is here used to create a table
where the keys are lists of integers.

\spadcommand{e: EqTable(List Integer, Integer) := table() }
$$
table() 
$$
\returnType{Type: EqTable(List Integer,Integer)}

%Original Page 354

These two lists are equal according to \spadopFrom{=}{List}, but not
according to \spadfunFrom{eq?}{List}.

\spadcommand{l1 := [1,2,3] }
$$
\left[
1, 2, 3 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{l2 := [1,2,3] }
$$
\left[
1, 2, 3 
\right]
$$
\returnType{Type: List PositiveInteger}

Because the two lists are not \spadfunFrom{eq?}{List}, separate values
can be stored under each.

\spadcommand{e.l1 := 111    }
$$
111 
$$
\returnType{Type: PositiveInteger}

\spadcommand{e.l2 := 222    }
$$
222 
$$
\returnType{Type: PositiveInteger}

\spadcommand{e.l1}
$$
111 
$$
\returnType{Type: PositiveInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Equation}

The {\tt Equation} domain provides equations as mathematical objects.
These are used, for example, as the input to various
\spadfunFrom{solve}{TransSolvePackage} operations.

Equations are created using the equals symbol, \spadopFrom{=}{Equation}.

\spadcommand{eq1 := 3*x + 4*y = 5 }
$$
{{4 \  y}+{3 \  x}}=5 
$$
\returnType{Type: Equation Polynomial Integer}

\spadcommand{eq2 := 2*x + 2*y = 3 }
$$
{{2 \  y}+{2 \  x}}=3 
$$
\returnType{Type: Equation Polynomial Integer}

The left- and right-hand sides of an equation are accessible using
the operations \spadfunFrom{lhs}{Equation} and \spadfunFrom{rhs}{Equation}.

\spadcommand{lhs eq1 }
$$
{4 \  y}+{3 \  x} 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{rhs eq1 }
$$
5 
$$
\returnType{Type: Polynomial Integer}

%Original Page 355

Arithmetic operations are supported and operate on both sides of the
equation.

\spadcommand{eq1 + eq2   }
$$
{{6 \  y}+{5 \  x}}=8 
$$
\returnType{Type: Equation Polynomial Integer}

\spadcommand{eq1 * eq2   }
$$
{{8 \  {y \sp 2}}+{{14} \  x \  y}+{6 \  {x \sp 2}}}={15} 
$$
\returnType{Type: Equation Polynomial Integer}

\spadcommand{2*eq2 - eq1 }
$$
x=1 
$$
\returnType{Type: Equation Polynomial Integer}

Equations may be created for any type so the arithmetic operations
will be defined only when they make sense.  For example, exponentiation 
is not defined for equations involving non-square matrices.

\spadcommand{eq1**2 }
$$
{{{16} \  {y \sp 2}}+{{24} \  x \  y}+{9 \  {x \sp 2}}}={25} 
$$
\returnType{Type: Equation Polynomial Integer}

Note that an equals symbol is also used to {\it test} for equality of
values in certain contexts.  For example, {\tt x+1} and {\tt y} are
unequal as polynomials.

\spadcommand{if x+1 = y then "equal" else "unequal"}
$$
\mbox{\tt "unequal"} 
$$
\returnType{Type: String}

\spadcommand{eqpol := x+1 = y }
$$
{x+1}=y 
$$
\returnType{Type: Equation Polynomial Integer}

If an equation is used where a {\tt Boolean} value is required, then
it is evaluated using the equality test from the operand type.

\spadcommand{if eqpol then "equal" else "unequal" }
$$
\mbox{\tt "unequal"} 
$$
\returnType{Type: String}

If one wants a {\tt Boolean} value rather than an equation, all one
has to do is ask!

\spadcommand{eqpol::Boolean }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{EuclideanGroebnerBasisPackage}

Example to call euclideanGroebner:
\begin{verbatim}
  a1:DMP([y,x],INT):= (9*x**2 + 5*x - 3)+ y*(3*x**2 + 2*x + 1)
  a2:DMP([y,x],INT):= (6*x**3 - 2*x**2 - 3*x +3) + y*(2*x**3 - x - 1)
  a3:DMP([y,x],INT):= (3*x**3 + 2*x**2) + y*(x**3 + x**2)
  an:=[a1,a2,a3]
  euclideanGroebner(an)
\end{verbatim}
This will return the weak euclidean Groebner basis set.
All reductions are total reductions.

You can get more information by providing a second argument.
To get the reduced critical pairs do:
\begin{verbatim}
  euclideanGroebner(an,"redcrit")
\end{verbatim}
You can get other information by calling:
\begin{verbatim}
  euclideanGroebner(an,"info")
\end{verbatim}
which returns:
\begin{verbatim}
   ci  =>  Leading monomial  for critpair calculation
   tci =>  Number of terms of polynomial i
   cj  =>  Leading monomial  for critpair calculation
   tcj =>  Number of terms of polynomial j
   c   =>  Leading monomial of critpair polynomial
   tc  =>  Number of terms of critpair polynomial
   rc  =>  Leading monomial of redcritpair polynomial
   trc =>  Number of terms of redcritpair polynomial
   tH  =>  Number of polynomials in reduction list H
   tD  =>  Number of critpairs still to do
\end{verbatim}
The three argument form returns all of the information:
\begin{verbatim}
  euclideanGroebner(an,"info","redcrit")
\end{verbatim}

The term ordering is determined by the polynomial type used. 
Suggested types include
\begin{verbatim}
   DistributedMultivariatePolynomial
   HomogeneousDistributedMultivariatePolynomial
   GeneralDistributedMultivariatePolynomial
\end{verbatim} 

See 
\domainref{EuclideanGroebnerBasisPackage},\\
\domainref{DistributedMultivariatePolynomial},\\
\domainref{HomogeneousDistributedMultivariatePolynomial},\\
\domainref{GeneralDistributedMultivariatePolynomial},\\ 
and \domainref{GroebnerPackage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Exit}

A function that does not return directly to its caller has {\tt Exit}
as its return type.  The operation {\tt error} is an example of one
which does not return to its caller.  Instead, it causes a return to
top-level.

\spadcommand{n := 0 }
$$
0 
$$
\returnType{Type: NonNegativeInteger}

%Original Page 356

The function {\tt gasp} is given return type {\tt Exit} since it is
guaranteed never to return a value to its caller.

\begin{verbatim}
gasp(): Exit ==
    free n
    n := n + 1
    error "Oh no!"
 
Function declaration gasp : () -> Exit has been added to workspace.

\end{verbatim}
\returnType{Type: Void}

The return type of {\tt half} is determined by resolving the types of
the two branches of the {\tt if}.

\begin{verbatim}
half(k) ==
  if odd? k then gasp()
  else k quo 2
\end{verbatim}

Because {\tt gasp} has the return type {\tt Exit}, the type of 
{\tt if} in {\tt half} is resolved to be {\tt Integer}.

\spadcommand{half 4 }
\begin{verbatim}
   Compiling function gasp with type () -> Exit 
   Compiling function half with type PositiveInteger -> Integer 
\end{verbatim}
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{half 3 }
\begin{verbatim}
   Error signalled from user code in function gasp: 
      Oh no!
\end{verbatim}

\spadcommand{n }
$$
1 
$$
\returnType{Type: NonNegativeInteger}

For functions which return no value at all, use {\tt Void}. 
\domainref{Void} for more information.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Expression}

{\tt Expression} is a constructor that creates domains whose objects
can have very general symbolic forms.  Here are some examples:

This is an object of type {\tt Expression Integer}.

\spadcommand{sin(x) + 3*cos(x)**2}
$$
{\sin \left({x} \right)}+{3\  {{\cos \left({x} \right)}\sp 2}} 
$$
\returnType{Type: Expression Integer}

This is an object of type {\tt Expression Float}.

\spadcommand{tan(x) - 3.45*x}
$$
{\tan \left({x} \right)}-{{3.45} \  x} 
$$
\returnType{Type: Expression Float}

This object contains symbolic function applications, sums,
products, square roots, and a quotient.

\spadcommand{(tan sqrt 7 - sin sqrt 11)**2 / (4 - cos(x - y))}
$$
\frac{-{{\tan \left({{\sqrt {7}}} \right)}\sp 2}+
{2 \  {\sin \left({{\sqrt {{11}}}} \right)}
\  {\tan \left({{\sqrt {7}}} \right)}}
-{{\sin \left({{\sqrt {{11}}}} \right)}\sp 2}} 
{{\cos \left({{y -x}} \right)}-4} 
$$
\returnType{Type: Expression Integer}

As you can see, {\tt Expression} actually takes an argument domain.
The {\it coefficients} of the terms within the expression belong to
the argument domain.  {\tt Integer} and {\tt Float}, along with 
{\tt Complex Integer} and {\tt Complex Float} are the most common
coefficient domains.

The choice of whether to use a {\tt Complex} coefficient domain or not
is important since Axiom can perform some simplifications on
real-valued objects

\spadcommand{log(exp  x)@Expression(Integer)} 
$$
x 
$$
\returnType{Type: Expression Integer}

... which are not valid on complex ones.

\spadcommand{log(exp  x)@Expression(Complex Integer)} 
$$
\log \left({{e \sp x}} \right)
$$
\returnType{Type: Expression Complex Integer}

Many potential coefficient domains, such as {\tt AlgebraicNumber}, are
not usually used because {\tt Expression} can subsume them.

\spadcommand{sqrt 3 + sqrt(2 + sqrt(-5)) }
$$
{\sqrt {{{\sqrt {-5}}+2}}}+{\sqrt {3}} 
$$
\returnType{Type: AlgebraicNumber}

\spadcommand{\% :: Expression Integer }
$$
{\sqrt {{{\sqrt {-5}}+2}}}+{\sqrt {3}} 
$$
\returnType{Type: Expression Integer}

Note that we sometimes talk about ``an object of type {\tt
Expression}.'' This is not really correct because we should say, for
example, ``an object of type {\tt Expression Integer}'' or ``an object
of type {\tt Expression Float}.''  By a similar abuse of language,
when we refer to an ``expression'' in this section we will mean an
object of type {\tt Expression R} for some domain {\tt R}.

The Axiom documentation contains many examples of the use of {\tt
Expression}.  For the rest of this section, we'll give you some
pointers to those examples plus give you some idea of how to
manipulate expressions.

It is important for you to know that {\tt Expression} creates domains
that have category {\tt Field}.  Thus you can invert any non-zero
expression and you shouldn't expect an operation like {\tt factor} to
give you much information.  You can imagine expressions as being
represented as quotients of ``multivariate'' polynomials where the
``variables'' are kernels (see \domainref{Kernel}.  A kernel can
either be a symbol such as {\tt x} or a symbolic function application
like {\tt sin(x + 4)}.  The second example is actually a nested kernel
since the argument to {\tt sin} contains the kernel {\tt x}.

\spadcommand{height mainKernel sin(x + 4)}
$$
2 
$$
\returnType{Type: PositiveInteger}

Actually, the argument to {\tt sin} is an expression, and so the
structure of {\tt Expression} is recursive.  
\domainref{Kernel} demonstrates how to extract the kernels in an expression.

Use the HyperDoc Browse facility to see what operations are applicable
to expression.  At the time of this writing, there were 262 operations
with 147 distinct name in {\tt Expression Integer}.  For example,
\spadfunFrom{numer}{Expression} and \spadfunFrom{denom}{Expression}
extract the numerator and denominator of an expression.

\spadcommand{e := (sin(x) - 4)**2 / ( 1 - 2*y*sqrt(- y) ) }
$$
\frac{-{{\sin \left({x} \right)}\sp 2}+
{8 \  {\sin \left({x} \right)}}
-{16}}{{2 \  y \  {\sqrt {-y}}} -1} 
$$
\returnType{Type: Expression Integer}

\spadcommand{numer e }
$$
-{{\sin \left({x} \right)}\sp 2}+
{8 \  {\sin \left({x} \right)}}
-{16} 
$$
\returnType{Type: 
SparseMultivariatePolynomial(Integer,Kernel Expression Integer)}

\spadcommand{denom e }
$$
{2 \  y \  {\sqrt {-y}}} -1 
$$
\returnType{Type: 
SparseMultivariatePolynomial(Integer,Kernel Expression Integer)}

Use \spadfunFrom{D}{Expression} to compute partial derivatives.

\spadcommand{D(e, x) }
$$
\frac{{{\left( 
{4 \  y \  {\cos \left({x} \right)}\  {\sin \left({x} \right)}}-
{{16} \  y \  {\cos \left({x} \right)}}\right)}\  {\sqrt {-y}}} -
{2 \  {\cos \left({x} \right)}\  {\sin \left({x} \right)}}+
{8\  {\cos \left({x} \right)}}}
{{4 \  y \  {\sqrt {-y}}}+{4 \  {y \sp 3}} -1} 
$$
\returnType{Type: Expression Integer}

See \sectionref{ugIntroCalcDeriv}
for more examples of expressions and derivatives.

\spadcommand{D(e, [x, y], [1, 2]) }
$$
\frac{\left(
\begin{array}{@{}l}
{{\left( {{\left( -{{2304} \  {y \sp 7}}+{{960} \  {y \sp 4}} \right)}
\  {\cos \left({x} \right)}\  {\sin \left({x} \right)}}+
{{\left({{9216} \  {y \sp 7}} -{{3840} \  {y \sp 4}} \right)}
\  {\cos \left({x} \right)}}\right)}\  {\sqrt {-y}}}+
\\
\\
\displaystyle
{{\left( -{{960} \  {y \sp 9}}+{{2160} \  {y \sp 6}} -{{180} \  {y \sp 3}} -3 
\right)}\  {\cos \left({x} \right)}\  {\sin \left({x} \right)}}+
\\
\\
\displaystyle
{{\left(
{{3840} \  {y \sp 9}} -{{8640} \  {y \sp 6}}+{{720} \  {y \sp 3}}+{12} 
\right)}\  {\cos \left({x} \right)}}
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
{{\left( {{256} \  {y \sp {12}}} -{{1792} \  {y \sp 9}}+{{1120} \  {y 
\sp 6}} -{{112} \  {y \sp 3}}+1 \right)}\  {\sqrt {-y}}} -
\\
\\
\displaystyle
{{1024} \  {y \sp {11}}}+{{1792} \  {y \sp 8}} -{{448} \  
{y \sp 5}}+{{16} \  {y \sp 2}} 
\end{array}
\right)}
$$
\returnType{Type: Expression Integer}

See 
\sectionref{ugIntroCalcLimits} and 
\sectionref{ugIntroSeries} for more examples of expressions and
calculus.  Differential equations involving expressions are discussed
in \sectionref{ugProblemDEQ} on page~\pageref{ugProblemDEQ}.
Chapter 8 has many advanced examples: see
\sectionref{ugProblemIntegration}
for a discussion of Axiom's integration facilities.

When an expression involves no ``symbol kernels'' (for example, 
{\tt x}), it may be possible to numerically evaluate the expression.

If you suspect the evaluation will create a complex number, use 
{\tt complexNumeric}.

\spadcommand{complexNumeric(cos(2 - 3*\%i))}
$$
-{4.1896256909\ 688072301}+{{9.1092278937\ 55336598} \  i} 
$$
\returnType{Type: Complex Float}

If you know it will be real, use {\tt numeric}.

\spadcommand{numeric(tan 3.8)}
$$
0.7735560905\ 0312607286 
$$
\returnType{Type: Float}

The {\tt numeric} operation will display an error message if the
evaluation yields a calue with an non-zero imaginary part.  Both of
these operations have an optional second argument {\tt n} which
specifies that the accuracy of the approximation be up to {\tt n}
decimal places.

When an expression involves no ``symbolic application'' kernels, it
may be possible to convert it a polynomial or rational function in the
variables that are present.

\spadcommand{e2 := cos(x**2 - y + 3) }
$$
\cos \left({{y -{x \sp 2} -3}} \right)
$$
\returnType{Type: Expression Integer}

\spadcommand{e3 := asin(e2) - \%pi/2 }
$$
-y+{x \sp 2}+3 
$$
\returnType{Type: Expression Integer}

\spadcommand{e3 :: Polynomial Integer }
$$
-y+{x \sp 2}+3 
$$
\returnType{Type: Polynomial Integer}

This also works for the polynomial types where specific variables
and their ordering are given.

\spadcommand{e3 :: DMP([x, y], Integer) }
$$
{x \sp 2} -y+3 
$$
\returnType{Type: DistributedMultivariatePolynomial([x,y],Integer)}

Finally, a certain amount of simplication takes place as expressions
are constructed.

\spadcommand{sin \%pi}
$$
0 
$$
\returnType{Type: Expression Integer}

\spadcommand{cos(\%pi / 4)}
$$
\frac{\sqrt {2}}{2} 
$$
\returnType{Type: Expression Integer}

For simplications that involve multiple terms of the expression, use
{\tt simplify}.

\spadcommand{tan(x)**6 + 3*tan(x)**4 + 3*tan(x)**2 + 1 }
$$
{{\tan \left({x} \right)}\sp 6}+
{3 \  {{\tan \left({x} \right)}\sp 4}}+
{3 \  {{\tan \left({x} \right)}\sp 2}}+1 
$$
\returnType{Type: Expression Integer}

\spadcommand{simplify \% }
$$
\frac{1}{{\cos \left({x} \right)}\sp 6} 
$$
\returnType{Type: Expression Integer}

See \sectionref{ugUserRules} for
examples of how to write your own rewrite rules for expressions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Factored}

{\tt Factored} creates a domain whose objects are kept in factored
form as long as possible.  Thus certain operations like
\spadopFrom{*}{Factored} (multiplication) and
\spadfunFrom{gcd}{Factored} are relatively easy to do.  Others, such
as addition, require somewhat more work, and the result may not be
completely factored unless the argument domain {\tt R} provides a
\spadfunFrom{factor}{Factored} operation.  Each object consists of a
unit and a list of factors, where each factor consists of a member of
{\tt R} (the {\em base}), an exponent, and a flag indicating what is
known about the base.  A flag may be one of ``{\tt nil}'', ``{\tt sqfr}'',
``{\tt irred}'' or ``{\tt prime}'', which mean that nothing is known about
the base, it is square-free, it is irreducible, or it is prime,
respectively.  The current restriction to factored objects of integral
domains allows simplification to be performed without worrying about
multiplication order.

%Original Page 357

\subsection{Decomposing Factored Objects}

In this section we will work with a factored integer.

\spadcommand{g := factor(4312) }
$$
{2 \sp 3} \  {7 \sp 2} \  {11} 
$$
\returnType{Type: Factored Integer}

Let's begin by decomposing {\tt g} into pieces.  The only possible
units for integers are {\tt 1} and {\tt -1}.

\spadcommand{unit(g) }
$$
1 
$$
\returnType{Type: PositiveInteger}

There are three factors.

\spadcommand{numberOfFactors(g) }
$$
3 
$$
\returnType{Type: PositiveInteger}

We can make a list of the bases, \ldots

\spadcommand{[nthFactor(g,i) for i in 1..numberOfFactors(g)] }
$$
\left[
2, 7, {11} 
\right]
$$
\returnType{Type: List Integer}

and the exponents, \ldots

\spadcommand{[nthExponent(g,i) for i in 1..numberOfFactors(g)] }
$$
\left[
3, 2, 1 
\right]
$$
\returnType{Type: List Integer}

and the flags.  You can see that all the bases (factors) are prime.

\spadcommand{[nthFlag(g,i) for i in 1..numberOfFactors(g)] }
$$
\left[
\mbox{\tt "prime"} , \mbox{\tt "prime"} , \mbox{\tt "prime"} 
\right]
$$
\returnType{Type: List Union("nil","sqfr","irred","prime")}

A useful operation for pulling apart a factored object into a list
of records of the components is \spadfunFrom{factorList}{Factored}.

\spadcommand{factorList(g) }
$$
\begin{array}{@{}l}
\left[
{\left[ {flg= \mbox{\tt "prime"} }, {fctr=2}, {xpnt=3} \right]},
\right.
\\
\\
\displaystyle
{\left[ {flg= \mbox{\tt "prime"} }, {fctr=7}, {xpnt=2} \right]},
\\
\\
\left.
\displaystyle
{\left[ {flg= \mbox{\tt "prime"} }, {fctr={11}}, {xpnt=1} \right]}
\right]
\end{array}
$$
\returnType{Type: 
List Record(flg: Union("nil","sqfr","irred","prime"),
fctr: Integer,xpnt: Integer)}

%Original Page 358

If you don't care about the flags, use \spadfunFrom{factors}{Factored}.

\spadcommand{factors(g) }
$$
\begin{array}{@{}l}
\left[
{\left[ {factor=2}, {exponent=3} \right]},
\right.
\\
\\
\displaystyle
{\left[ {factor=7}, {exponent=2} \right]},
\\
\\
\displaystyle
\left.
{\left[ {factor={11}}, {exponent=1} \right]}
\right]
\end{array}
$$
\returnType{Type: List Record(factor: Integer,exponent: Integer)}

Neither of these operations returns the unit.

\spadcommand{first(\%).factor }
$$
2 
$$
\returnType{Type: PositiveInteger}

\subsection{Expanding Factored Objects}

Recall that we are working with this factored integer.

\spadcommand{g := factor(4312) }
$$
{2 \sp 3} \  {7 \sp 2} \  {11} 
$$
\returnType{Type: Factored Integer}

To multiply out the factors with their multiplicities, use
\spadfunFrom{expand}{Factored}.

\spadcommand{expand(g) }
$$
4312 
$$
\returnType{Type: PositiveInteger}

If you would like, say, the distinct factors multiplied together but
with multiplicity one, you could do it this way.

\spadcommand{reduce(*,[t.factor for t in factors(g)]) }
$$
154 
$$
\returnType{Type: PositiveInteger}

\subsection{Arithmetic with Factored Objects}

We're still working with this factored integer.

\spadcommand{g := factor(4312) }
$$
{2 \sp 3} \  {7 \sp 2} \  {11} 
$$
\returnType{Type: Factored Integer}

We'll also define this factored integer.

\spadcommand{f := factor(246960) }
$$
{2 \sp 4} \  {3 \sp 2} \  5 \  {7 \sp 3} 
$$
\returnType{Type: Factored Integer}

%Original Page 359

Operations involving multiplication and division are particularly
easy with factored objects.

\spadcommand{f * g }
$$
{2 \sp 7} \  {3 \sp 2} \  5 \  {7 \sp 5} \  {11} 
$$
\returnType{Type: Factored Integer}

\spadcommand{f**500 }
$$
{2 \sp {2000}} \  {3 \sp {1000}} \  {5 \sp {500}} \  {7 \sp {1500}} 
$$
\returnType{Type: Factored Integer}

\spadcommand{gcd(f,g) }
$$
{2 \sp 3} \  {7 \sp 2} 
$$
\returnType{Type: Factored Integer}

\spadcommand{lcm(f,g) }
$$
{2 \sp 4} \  {3 \sp 2} \  5 \  {7 \sp 3} \  {11} 
$$
\returnType{Type: Factored Integer}

If we use addition and subtraction things can slow down because
we may need to compute greatest common divisors.

\spadcommand{f + g }
$$
{2 \sp 3} \  {7 \sp 2} \  {641} 
$$
\returnType{Type: Factored Integer}

\spadcommand{f - g }
$$
{2 \sp 3} \  {7 \sp 2} \  {619} 
$$
\returnType{Type: Factored Integer}

Test for equality with {\tt 0} and {\tt 1} by using
\spadfunFrom{zero?}{Factored} and \spadfunFrom{one?}{Factored},
respectively.

\spadcommand{zero?(factor(0))}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{zero?(g) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{one?(factor(1))}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{one?(f) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Another way to get the zero and one factored objects is to use
package calling (see \sectionref{ugTypesPkgCall}).

\spadcommand{0\$Factored(Integer)}
$$
0 
$$
\returnType{Type: Factored Integer}

%Original Page 360

\spadcommand{1\$Factored(Integer)}
$$
1 
$$
\returnType{Type: Factored Integer}

\subsection{Creating New Factored Objects}

The \spadfunFrom{map}{Factored} operation is used to iterate across
the unit and bases of a factored object.  See \domainref{FactoredFunctions2}
for a discussion of \spadfunFrom{map}{Factored}.

The following four operations take a base and an exponent and create a
factored object.  They differ in handling the flag component.

\spadcommand{nilFactor(24,2) }
$$
{24} \sp 2 
$$
\returnType{Type: Factored Integer}

This factor has no associated information.

\spadcommand{nthFlag(\%,1) }
$$
\mbox{\tt "nil"} 
$$
\returnType{Type: Union("nil",...)}

This factor is asserted to be square-free.

\spadcommand{sqfrFactor(30,2) }
$$
{30} \sp 2 
$$
\returnType{Type: Factored Integer}

This factor is asserted to be irreducible.

\spadcommand{irreducibleFactor(13,10) }
$$
{13} \sp {10} 
$$
\returnType{Type: Factored Integer}

This factor is asserted to be prime.

\spadcommand{primeFactor(11,5) }
$$
{11} \sp 5 
$$
\returnType{Type: Factored Integer}

A partial inverse to \spadfunFrom{factorList}{Factored} is
\spadfunFrom{makeFR}{Factored}.

\spadcommand{h := factor(-720) }
$$
-{{2 \sp 4} \  {3 \sp 2} \  5} 
$$
\returnType{Type: Factored Integer}

The first argument is the unit and the second is a list of records as
returned by \spadfunFrom{factorList}{Factored}.

\spadcommand{h - makeFR(unit(h),factorList(h)) }
$$
0 
$$
\returnType{Type: Factored Integer}

%Original Page 361

\subsection{Factored Objects with Variables}

Some of the operations available for polynomials are also available
for factored polynomials.

\spadcommand{p := (4*x*x-12*x+9)*y*y + (4*x*x-12*x+9)*y + 28*x*x - 84*x + 63 }
$$
{{\left( {4 \  {x \sp 2}} -{{12} \  x}+9 
\right)}
\  {y \sp 2}}+{{\left( {4 \  {x \sp 2}} -{{12} \  x}+9 
\right)}
\  y}+{{28} \  {x \sp 2}} -{{84} \  x}+{63} 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{fp := factor(p) }
$$
{{\left( {2 \  x} -3 
\right)}
\sp 2} \  {\left( {y \sp 2}+y+7 
\right)}
$$
\returnType{Type: Factored Polynomial Integer}

You can differentiate with respect to a variable.

\spadcommand{D(p,x) }
$$
{{\left( {8 \  x} -{12} 
\right)}
\  {y \sp 2}}+{{\left( {8 \  x} -{12} 
\right)}
\  y}+{{56} \  x} -{84} 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{D(fp,x) }
$$
4 \  {\left( {2 \  x} -3 
\right)}
\  {\left( {y \sp 2}+y+7 
\right)}
$$
\returnType{Type: Factored Polynomial Integer}

\spadcommand{numberOfFactors(\%) }
$$
3 
$$
\returnType{Type: PositiveInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{FactoredFunctions2}

The {\tt FactoredFunctions2} package implements one operation,
\spadfunFrom{map}{FactoredFunctions2}, for applying an operation to every
base in a factored object and to the unit.

\spadcommand{double(x) == x + x }
\returnType{Type: Void}

\spadcommand{f := factor(720) }
$$
{2 \sp 4} \  {3 \sp 2} \  5 
$$
\returnType{Type: Factored Integer}

Actually, the \spadfunFrom{map}{FactoredFunctions2} operation used
in this example comes from {\tt Factored} itself, since {\tt double} 
takes an integer argument and returns an integer result.

\spadcommand{map(double,f) }
$$
2 \  {4 \sp 4} \  {6 \sp 2} \  {10} 
$$
\returnType{Type: Factored Integer}

%Original Page 362

If we want to use an operation that returns an object that has a type
different from the operation's argument,
the \spadfunFrom{map}{FactoredFunctions2} in {\tt Factored}
cannot be used and we use the one in {\tt FactoredFunctions2}.

\spadcommand{makePoly(b) == x + b }
\returnType{Type: Void}

In fact, the ``2'' in the name of the package means that we might
be using factored objects of two different types.

\spadcommand{g := map(makePoly,f) }
$$
{\left( x+1 \right)}
\  {{\left( x+2 \right)}\sp 4} 
\  {{\left( x+3 \right)}\sp 2} 
\  {\left( x+5 \right)}
$$
\returnType{Type: Factored Polynomial Integer}

It is important to note that both versions of
\spadfunFrom{map}{FactoredFunctions2} destroy any information known
about the bases (the fact that they are prime, for instance).

The flags for each base are set to ``nil'' in the object returned
by \spadfunFrom{map}{FactoredFunctions2}.

\spadcommand{nthFlag(g,1) }
$$
\mbox{\tt "nil"} 
$$
\returnType{Type: Union("nil",...)}

For more information about factored objects and their use, see
\domainref{Factored} and \sectionref{ugProblemGalois}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{File}

The {\tt File(S)} domain provides a basic interface to read and
write values of type {\tt S} in files.

Before working with a file, it must be made accessible to Axiom with
the \spadfunFrom{open}{File} operation.

\spadcommand{ifile:File List Integer:=open("/tmp/jazz1","output")  }
$$
\mbox{\tt "/tmp/jazz1"} 
$$
\returnType{Type: File List Integer}

The \spadfunFrom{open}{File} function arguments are a {\tt FileName}
and a {\tt String} specifying the mode.  If a full pathname is not
specified, the current default directory is assumed.  The mode must be
one of ``{\tt input}'' or ``{\tt output}''.  If it is not specified, 
``{\tt input}'' is assumed.  Once the file has been opened, you can read or
write data.

The operations \spadfunFrom{read}{File} and \spadfunFrom{write}{File} are
provided.

\spadcommand{write!(ifile, [-1,2,3])}
$$
\left[
-1, 2, 3 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{write!(ifile, [10,-10,0,111])}
$$
\left[
{10}, -{10}, 0, {111} 
\right]
$$
\returnType{Type: List Integer}

%Original Page 363

\spadcommand{write!(ifile, [7])}
$$
\left[
7 
\right]
$$
\returnType{Type: List Integer}

You can change from writing to reading (or vice versa) by reopening a file.

\spadcommand{reopen!(ifile, "input")}
$$
\mbox{\tt "/tmp/jazz1"} 
$$
\returnType{Type: File List Integer}

\spadcommand{read! ifile}
$$
\left[
-1, 2, 3 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{read! ifile}
$$
\left[
{10}, -{10}, 0, {111} 
\right]
$$
\returnType{Type: List Integer}

The \spadfunFrom{read}{File} operation can cause an error if one tries
to read more data than is in the file.  To guard against this
possibility the \spadfunFrom{readIfCan}{File} operation should be
used.

\spadcommand{readIfCan! ifile  }
$$
\left[
7 
\right]
$$
\returnType{Type: Union(List Integer,...)}

\spadcommand{readIfCan! ifile  }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

You can find the current mode of the file, and the file's name.

\spadcommand{iomode ifile}
$$
\mbox{\tt "input"} 
$$
\returnType{Type: String}

\spadcommand{name ifile}
$$
\mbox{\tt "/tmp/jazz1"} 
$$
\returnType{Type: FileName}

When you are finished with a file, you should close it.

\spadcommand{close! ifile}
$$
\mbox{\tt "/tmp/jazz1"} 
$$
\returnType{Type: File List Integer}

\spadcommand{)system rm /tmp/jazz1}

A limitation of the underlying LISP system is that not all values can
be represented in a file.  In particular, delayed values containing
compiled functions cannot be saved.

For more information on related topics, see 
\domainref{TextFile}, \domainref{KeyedAccessFile}, 
\domainref{Library}, and \domainref{FileName}.

%Original Page 364

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{FileName}
 
The {\tt FileName} domain provides an interface to the computer's file
system.  Functions are provided to manipulate file names and to test
properties of files.
 
The simplest way to use file names in the Axiom interpreter is to rely
on conversion to and from strings.  The syntax of these strings
depends on the operating system.

\spadcommand{fn: FileName }
\returnType{Type: Void}

On Linux, this is a proper file syntax:

\spadcommand{fn := "/tmp/fname.input" }
$$
\mbox{\tt "/tmp/fname.input"} 
$$
\returnType{Type: FileName}

Although it is very convenient to be able to use string notation
for file names in the interpreter, it is desirable to have a portable
way of creating and manipulating file names from within programs.

A measure of portability is obtained by considering a file name
to consist of three parts: the {\it directory}, the {\it name},
and the {\it extension}.

\spadcommand{directory fn }
$$
\mbox{\tt "/tmp"} 
$$
\returnType{Type: String}

\spadcommand{name fn }
$$
\mbox{\tt "fname"} 
$$
\returnType{Type: String}

\spadcommand{extension fn }
$$
\mbox{\tt "input"} 
$$
\returnType{Type: String}

The meaning of these three parts depends on the operating system.
For example, on CMS the file ``{\tt SPADPROF INPUT M}''
would have directory ``{\tt M}'', name ``{\tt SPADPROF}'' and
extension ``{\tt INPUT}''.
 
It is possible to create a filename from its parts.

\spadcommand{fn := filename("/u/smwatt/work", "fname", "input") }
$$
\mbox{\tt "/u/smwatt/work/fname.input"} 
$$
\returnType{Type: FileName}

%Original Page 365

When writing programs, it is helpful to refer to directories via
variables.

\spadcommand{objdir := "/tmp" }
$$
\mbox{\tt "/tmp"} 
$$
\returnType{Type: String}

\spadcommand{fn := filename(objdir, "table", "spad") }
$$
\mbox{\tt "/tmp/table.spad"} 
$$
\returnType{Type: FileName}

If the directory or the extension is given as an empty string, then
a default is used.  On AIX, the defaults are the current directory
and no extension.

\spadcommand{fn := filename("", "letter", "") }
$$
\mbox{\tt "letter"} 
$$
\returnType{Type: FileName}
 
Three tests provide information about names in the file system.

The \spadfunFrom{exists?}{FileName} operation tests whether the named
file exists.

\spadcommand{exists? "/etc/passwd"}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The operation \spadfunFrom{readable?}{FileName} tells whether the named file
can be read.  If the file does not exist, then it cannot be read.

\spadcommand{readable? "/etc/passwd"}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{readable? "/etc/security/passwd"}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{readable? "/ect/passwd"}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Likewise, the operation \spadfunFrom{writable?}{FileName} tells
whether the named file can be written.  If the file does not exist,
the test is determined by the properties of the directory.

\spadcommand{writable? "/etc/passwd"}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{writable? "/dev/null"}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{writable? "/etc/DoesNotExist"}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

%Original Page 366

\spadcommand{writable? "/tmp/DoesNotExist"}
$$
{\tt true} 
$$
\returnType{Type: Boolean}
 
The \spadfunFrom{new}{FileName} operation constructs the name of a new
writable file.  The argument sequence is the same as for
\spadfunFrom{filename}{FileName}, except that the name part is
actually a prefix for a constructed unique name.

The resulting file is in the specified directory
with the given extension, and the same defaults are used.

\spadcommand{fn := new(objdir, "xxx", "yy") }
$$
\mbox{\tt "/tmp/xxx82404.yy"} 
$$
\returnType{Type: FileName}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{FlexibleArray}

The {\tt FlexibleArray} domain constructor creates one-dimensional
arrays of elements of the same type.  Flexible arrays are an attempt
to provide a data type that has the best features of both
one-dimensional arrays (fast, random access to elements) and lists
(flexibility).  They are implemented by a fixed block of storage.
When necessary for expansion, a new, larger block of storage is
allocated and the elements from the old storage area are copied into
the new block.

Flexible arrays have available most of the operations provided by 
{\tt OneDimensionalArray} (see 
\domainref{OneDimensionalArray} and \domainref{Vector}).
Since flexible arrays are also of category 
{\tt ExtensibleLinearAggregate}, they have operations {\tt concat!}, 
{\tt delete!}, {\tt insert!}, {\tt merge!}, {\tt remove!}, 
{\tt removeDuplicates!}, and {\tt select!}.  In addition, the operations
{\tt physicalLength} and {\tt physicalLength!} provide user-control
over expansion and contraction.

A convenient way to create a flexible array is to apply the operation
{\tt flexibleArray} to a list of values.

\spadcommand{flexibleArray [i for i in 1..6]}
$$
\left[
1, 2, 3, 4, 5, 6 
\right]
$$
\returnType{Type: FlexibleArray PositiveInteger}

Create a flexible array of six zeroes.

\spadcommand{f : FARRAY INT := new(6,0)}
$$
\left[
0, 0, 0, 0, 0, 0 
\right]
$$
\returnType{Type: FlexibleArray Integer}

For $i=1\ldots 6$ set the $i$-th element to $i$.  Display {\tt f}.

\spadcommand{for i in 1..6 repeat f.i := i; f}
$$
\left[
1, 2, 3, 4, 5, 6 
\right]
$$
\returnType{Type: FlexibleArray Integer}

%Original Page 367

Initially, the physical length is the same as the number of elements.

\spadcommand{physicalLength f}
$$
6 
$$
\returnType{Type: PositiveInteger}

Add an element to the end of {\tt f}.

\spadcommand{concat!(f,11)}
$$
\left[
1, 2, 3, 4, 5, 6, {11} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

See that its physical length has grown.

\spadcommand{physicalLength f}
$$
10 
$$
\returnType{Type: PositiveInteger}

Make {\tt f} grow to have room for {\tt 15} elements.

\spadcommand{physicalLength!(f,15)}
$$
\left[
1, 2, 3, 4, 5, 6, {11} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Concatenate the elements of {\tt f} to itself.  The physical length
allows room for three more values at the end.

\spadcommand{concat!(f,f)}
$$
\left[
1, 2, 3, 4, 5, 6, {11}, 1, 2, 3, 4, 5, 6, 
{11} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Use {\tt insert!} to add an element to the front of a flexible array.

\spadcommand{insert!(22,f,1)}
$$
\left[
{22}, 1, 2, 3, 4, 5, 6, {11}, 1, 2, 3, 4, 
5, 6, {11} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Create a second flexible array from {\tt f} consisting of the elements
from index 10 forward.

\spadcommand{g := f(10..)}
$$
\left[
2, 3, 4, 5, 6, {11} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Insert this array at the front of {\tt f}.

\spadcommand{insert!(g,f,1)}
$$
\left[
2, 3, 4, 5, 6, {11}, {22}, 1, 2, 3, 4, 5, 
6, {11}, 1, 2, 3, 4, 5, 6, {11} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Merge the flexible array {\tt f} into {\tt g} after sorting each in place.

\spadcommand{merge!(sort! f, sort! g)}
$$
\left[
1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 
4, 5, 5, 5, 5, 6, 6, 6, 6, {11}, {11}, {11}, 
{11}, {22} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

Remove duplicates in place.

\spadcommand{removeDuplicates! f}
$$
\left[
1, 2, 3, 4, 5, 6, {11}, {22} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

%Original Page 368

Remove all odd integers.

\spadcommand{select!(i +-> even? i,f)}
$$
\left[
2, 4, 6, {22} 
\right]
$$
\returnType{Type: FlexibleArray Integer}

All these operations have shrunk the physical length of {\tt f}.

\spadcommand{physicalLength f}
$$
8 
$$
\returnType{Type: PositiveInteger}

To force Axiom not to shrink flexible arrays call the {\tt shrinkable}
operation with the argument {\tt false}.  You must package call this
operation.  The previous value is returned.

\spadcommand{shrinkable(false)\$FlexibleArray(Integer)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Float}

Axiom provides two kinds of floating point numbers.  The domain 
{\tt Float} (abbreviation {\tt FLOAT}) implements a model of arbitrary
precision floating point numbers.  The domain {\tt DoubleFloat}
(abbreviation {\tt DFLOAT}) is intended to make available hardware
floating point arithmetic in Axiom.  The actual model of floating
point that {\tt DoubleFloat} provides is system-dependent.  For
example, on the IBM system 370 Axiom uses IBM double precision which
has fourteen hexadecimal digits of precision or roughly sixteen
decimal digits.  Arbitrary precision floats allow the user to specify
the precision at which arithmetic operations are computed.  Although
this is an attractive facility, it comes at a cost.
Arbitrary-precision floating-point arithmetic typically takes twenty
to two hundred times more time than hardware floating point.

For more information about Axiom's numeric and graphic facilities, see
\sectionref{ugGraph}, \sectionref{ugProblemNumeric}, and
\domainref{DoubleFloat}.

\subsection{Introduction to Float}

Scientific notation is supported for input and output of floating
point numbers.  A floating point number is written as a string of
digits containing a decimal point optionally followed by the letter
``{\tt E}'', and then the exponent.

We begin by doing some calculations using arbitrary precision floats.
The default precision is twenty decimal digits.

\spadcommand{1.234}
$$
1.234 
$$
\returnType{Type: Float}

%Original Page 369

A decimal base for the exponent is assumed, so the number 
{\tt 1.234E2} denotes $1.234 \cdot 10^2$.

\spadcommand{1.234E2}
$$
123.4 
$$
\returnType{Type: Float}

The normal arithmetic operations are available for floating point numbers.

\spadcommand{sqrt(1.2 + 2.3 / 3.4 ** 4.5)}
$$
1.0996972790\ 671286226 
$$
\returnType{Type: Float}

\subsection{Conversion Functions}

You can use conversion (\sectionref{ugTypesConvert}) to
go back and forth between {\tt Integer}, {\tt Fraction Integer} and
{\tt Float}, as appropriate.

\spadcommand{i := 3 :: Float }
$$
3.0 
$$
\returnType{Type: Float}

\spadcommand{i :: Integer }
$$
3 
$$
\returnType{Type: Integer}

\spadcommand{i :: Fraction Integer }
$$
3 
$$
\returnType{Type: Fraction Integer}

Since you are explicitly asking for a conversion, you must take
responsibility for any loss of exactness.

\spadcommand{r := 3/7 :: Float }
$$
0.4285714285\ 7142857143 
$$
\returnType{Type: Float}

\spadcommand{r :: Fraction Integer }
$$
\frac{3}{7} 
$$
\returnType{Type: Fraction Integer}

This conversion cannot be performed: use \spadfunFrom{truncate}{Float}
or \spadfunFrom{round}{Float} if that is what you intend.

\spadcommand{r :: Integer }
\begin{verbatim}
   Cannot convert from type Float to Integer for value
   0.4285714285 7142857143
\end{verbatim}

The operations \spadfunFrom{truncate}{Float} and \spadfunFrom{round}{Float}
truncate  \ldots

\spadcommand{truncate 3.6}
$$
3.0 
$$
\returnType{Type: Float}

%Original Page 370

and round to the nearest integral {\tt Float} respectively.

\spadcommand{round 3.6}
$$
4.0 
$$
\returnType{Type: Float}

\spadcommand{truncate(-3.6)}
$$
-{3.0} 
$$
\returnType{Type: Float}

\spadcommand{round(-3.6)}
$$
-{4.0} 
$$
\returnType{Type: Float}

The operation \spadfunFrom{fractionPart}{Float} computes the
fractional part of {\tt x}, that is, {\tt x - truncate x}.

\spadcommand{fractionPart 3.6}
$$
0.6 
$$
\returnType{Type: Float}

The operation \spadfunFrom{digits}{Float} allows the user to set the
precision.  It returns the previous value it was using.

\spadcommand{digits 40 }
$$
20 
$$
\returnType{Type: PositiveInteger}

\spadcommand{sqrt 0.2}
$$
0.4472135954\ 9995793928\ 1834733746\ 2552470881 
$$
\returnType{Type: Float}

\spadcommand{pi()\$Float }
$$
3.1415926535\ 8979323846\ 2643383279\ 502884197 
$$
\returnType{Type: Float}

The precision is only limited by the computer memory available.
Calculations at 500 or more digits of precision are not difficult.

\spadcommand{digits 500 }
$$
40 
$$
\returnType{Type: PositiveInteger}

\spadcommand{pi()\$Float }
$$
\begin{array}{@{}l}
3.1415926535\ 8979323846\ 2643383279\ 5028841971\ 6939937510\ 5820974944 
\\
\displaystyle
\ \ 5923078164\ 0628620899\ 8628034825\ 3421170679\ 8214808651\ 3282306647
\\
\displaystyle
\ \ 0938446095\ 5058223172\ 5359408128\ 4811174502\ 8410270193\ 8521105559
\\
\displaystyle
\ \ 6446229489\ 5493038196\ 4428810975\ 6659334461\ 2847564823\ 3786783165
\\
\displaystyle
\ \ 2712019091\ 4564856692\ 3460348610\ 4543266482\ 1339360726\ 0249141273
\\
\displaystyle
\ \ 7245870066\ 0631558817\ 4881520920\ 9628292540\ 9171536436\ 7892590360
\\
\displaystyle
\ \ 0113305305\ 4882046652\ 1384146951\ 9415116094\ 3305727036\ 5759591953
\\
\displaystyle
\ \ 0921861173\ 8193261179\ 3105118548\ 0744623799\ 6274956735\ 1885752724
\\
\displaystyle
\ \ 8912279381\ 830119491 
\end{array}
$$
\returnType{Type: Float}

%Original Page 371

Reset \spadfunFrom{digits}{Float} to its default value.

\spadcommand{digits 20}
$$
500 
$$
\returnType{Type: PositiveInteger}

Numbers of type {\tt Float} are represented as a record of two
integers, namely, the mantissa and the exponent where the base of the
exponent is binary.  That is, the floating point number {\tt (m,e)}
represents the number $m \cdot 2^e$.  A consequence of using a binary
base is that decimal numbers can not, in general, be represented
exactly.

\subsection{Output Functions}

A number of operations exist for specifying how numbers of type 
{\tt Float} are to be displayed.  By default, spaces are inserted every ten
digits in the output for readability.\footnote{Note that you cannot
include spaces in the input form of a floating point number, though
you can use underscores.}

Output spacing can be modified with the \spadfunFrom{outputSpacing}{Float} 
operation.  This inserts no spaces and then displays the value of {\tt x}.

\spadcommand{outputSpacing 0; x := sqrt 0.2 }
$$
0.44721359549995793928 
$$
\returnType{Type: Float}

Issue this to have the spaces inserted every {\tt 5} digits.

\spadcommand{outputSpacing 5; x }
$$
0.44721\ 35954\ 99957\ 93928 
$$
\returnType{Type: Float}

By default, the system displays floats in either fixed format
or scientific format, depending on the magnitude of the number.

\spadcommand{y := x/10**10 }
$$
0.44721\ 35954\ 99957\ 93928\ {\rm E\ }-10 
$$
\returnType{Type: Float}

A particular format may be requested with the operations
\spadfunFrom{outputFloating}{Float} and \spadfunFrom{outputFixed}{Float}.

\spadcommand{outputFloating(); x  }
$$
0.44721\ 35954\ 99957\ 93928\ {\rm E\ }0 
$$
\returnType{Type: Float}

\spadcommand{outputFixed(); y  }
$$
0.00000\ 00000\ 44721\ 35954\ 99957\ 93928 
$$
\returnType{Type: Float}

Additionally, you can ask for {\tt n} digits to be displayed after the
decimal point.

\spadcommand{outputFloating 2; y  }
$$
0.45\ {\rm E\ } -10 
$$
\returnType{Type: Float}

%Original Page 372

\spadcommand{outputFixed 2; x  }
$$
0.45 
$$
\returnType{Type: Float}

This resets the output printing to the default behavior.

\spadcommand{outputGeneral()}
\returnType{Type: Void}

\subsection{An Example: Determinant of a Hilbert Matrix}
\label{ugxFloatHilbert}

Consider the problem of computing the determinant of a {\tt 10} by
{\tt 10} Hilbert matrix.  The $(i,j)$-th entry of a Hilbert
matrix is given by {\tt 1/(i+j+1)}.

First do the computation using rational numbers to obtain the
exact result.

\spadcommand{a: Matrix Fraction Integer := matrix [ [1/(i+j+1) for j in 0..9] for i in 0..9] }
$$
\left[
\begin{array}{cccccccccc}
1 & {\frac{1}{2}} & {\frac{1}{3}} & {\frac{1}{4}} & {\frac{1}{5}} & 
{\frac{1}{6}} & 
{\frac{1}{7}} & {\frac{1}{8}} & {\frac{1}{9}} & {\frac{1}{10}} \\ 
{\frac{1}{2}} & {\frac{1}{3}} & {\frac{1}{4}} & {\frac{1}{5}} & 
{\frac{1}{6}} & 
{\frac{1}{7}} & {\frac{1}{8}} & {\frac{1}{9}} & {\frac{1}{10}} & 
{\frac{1}{11}} \\ 
{\frac{1}{3}} & {\frac{1}{4}} & {\frac{1}{5}} & {\frac{1}{6}} & 
{\frac{1}{7}} & 
{\frac{1}{8}} & {\frac{1}{9}} & {\frac{1}{10}} & {\frac{1}{11}} & 
{\frac{1}{12}} \\ 
{\frac{1}{4}} & {\frac{1}{5}} & {\frac{1}{6}} & {\frac{1}{7}} & 
{\frac{1}{8}} & 
{\frac{1}{9}} & {\frac{1}{10}} & {\frac{1}{11}} & {\frac{1}{12}} & 
{\frac{1}{13}} \\ 
{\frac{1}{5}} & {\frac{1}{6}} & {\frac{1}{7}} & {\frac{1}{8}} & 
{\frac{1}{9}} & 
{\frac{1}{10}} & {\frac{1}{11}} & {\frac{1}{12}} & {\frac{1}{13}} & 
{\frac{1}{14}} \\ 
{\frac{1}{6}} & {\frac{1}{7}} & {\frac{1}{8}} & {\frac{1}{9}} & 
{\frac{1}{10}} & 
{\frac{1}{11}} & {\frac{1}{12}} & {\frac{1}{13}} & {\frac{1}{14}} & 
{\frac{1}{15}} \\ 
{\frac{1}{7}} & {\frac{1}{8}} & {\frac{1}{9}} & {\frac{1}{10}} & 
{\frac{1}{11}} & 
{\frac{1}{12}} & {\frac{1}{13}} & {\frac{1}{14}} & {\frac{1}{15}} & 
{\frac{1}{16}} \\ 
{\frac{1}{8}} & {\frac{1}{9}} & {\frac{1}{10}} & {\frac{1}{11}} & 
{\frac{1}{12}} 
& {\frac{1}{13}} & {\frac{1}{14}} & {\frac{1}{15}} & {\frac{1}{16}} & 
{\frac{1}{17}} \\ 
{\frac{1}{9}} & {\frac{1}{10}} & {\frac{1}{11}} & {\frac{1}{12}} & 
{\frac{1}{13}} & {\frac{1}{14}} & {\frac{1}{15}} & {\frac{1}{16}} & 
{\frac{1}{17}} & {\frac{1}{18}} \\ 
{\frac{1}{10}} & {\frac{1}{11}} & {\frac{1}{12}} & {\frac{1}{13}} & 
{\frac{1}{14}} & {\frac{1}{15}} & {\frac{1}{16}} & {\frac{1}{17}} & 
{\frac{1}{18}} & {\frac{1}{19}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

This version of \spadfunFrom{determinant}{Matrix} uses Gaussian elimination.

\spadcommand{d:= determinant a }
$$
\frac{1}{46206893947914691316295628839036278726983680000000000} 
$$
\returnType{Type: Fraction Integer}

\spadcommand{d :: Float }
$$
0.21641\ 79226\ 43149\ 18691\ {\rm E\ } -52 
$$
\returnType{Type: Float}

Now use hardware floats. Note that a semicolon (;) is used to prevent
the display of the matrix.

\spadcommand{b: Matrix DoubleFloat := matrix [ [1/(i+j+1\$DoubleFloat) for j in 0..9] for i in 0..9]; }
\returnType{Type: Matrix DoubleFloat}

%Original Page 373

The result given by hardware floats is correct only to four
significant digits of precision.  In the jargon of numerical analysis,
the Hilbert matrix is said to be ``ill-conditioned.''

\spadcommand{determinant b }
$$
2.1643677945721411e-53 
$$
\returnType{Type: DoubleFloat}

Now repeat the computation at a higher precision using {\tt Float}.

\spadcommand{digits 40 }
$$
20 
$$
\returnType{Type: PositiveInteger}

\spadcommand{c: Matrix Float := matrix [ [1/(i+j+1\$Float) for j in 0..9] for i in 0..9];  }
\returnType{Type: Matrix Float}

\spadcommand{determinant c }
$$
0.21641\ 79226\ 43149\ 18690\ 60594\ 98362\ 26174\ 36159\ {\rm E\ } -52 
$$
\returnType{Type: Float}

Reset \spadfunFrom{digits}{Float} to its default value.

\spadcommand{digits 20}
$$
40 
$$
\returnType{Type: PositiveInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Fraction}

The {\tt Fraction} domain implements quotients.  The elements must
belong to a domain of category {\tt IntegralDomain}: multiplication
must be commutative and the product of two non-zero elements must not
be zero.  This allows you to make fractions of most things you would
think of, but don't expect to create a fraction of two matrices!  The
abbreviation for {\tt Fraction} is {\tt FRAC}.

Use \spadopFrom{/}{Fraction} to create a fraction.

\spadcommand{a := 11/12 }
$$
\frac{11}{12} 
$$
\returnType{Type: Fraction Integer}

\spadcommand{b := 23/24 }
$$
\frac{23}{24} 
$$
\returnType{Type: Fraction Integer}

The standard arithmetic operations are available.

\spadcommand{3 - a*b**2 + a + b/a }
$$
\frac{313271}{76032} 
$$
\returnType{Type: Fraction Integer}

%Original Page 374

Extract the numerator and denominator by using
\spadfunFrom{numer}{Fraction} and \spadfunFrom{denom}{Fraction},
respectively.

\spadcommand{numer(a) }
$$
11 
$$
\returnType{Type: PositiveInteger}

\spadcommand{denom(b) }
$$
24 
$$
\returnType{Type: PositiveInteger}

Operations like \spadfunFrom{max}{Fraction},
\spadfunFrom{min}{Fraction}, \spadfunFrom{negative?}{Fraction},
\spadfunFrom{positive?}{Fraction} and \spadfunFrom{zero?}{Fraction}
are all available if they are provided for the numerators and
denominators.  
See \domainref{Integer} for examples.

Don't expect a useful answer from \spadfunFrom{factor}{Fraction},
\spadfunFrom{gcd}{Fraction} or \spadfunFrom{lcm}{Fraction} if you apply
them to fractions.

\spadcommand{r := (x**2 + 2*x + 1)/(x**2 - 2*x + 1) }
$$
\frac{{x \sp 2}+{2 \  x}+1}{{x \sp 2} -{2 \  x}+1} 
$$
\returnType{Type: Fraction Polynomial Integer}

Since all non-zero fractions are invertible, these operations have trivial
definitions.

\spadcommand{factor(r) }
$$
\frac{{x \sp 2}+{2 \  x}+1}{{x \sp 2} -{2 \  x}+1} 
$$
\returnType{Type: Factored Fraction Polynomial Integer}

Use \spadfunFrom{map}{Fraction} to apply \spadfunFrom{factor}{Fraction} to
the numerator and denominator, which is probably what you mean.

\spadcommand{map(factor,r) }
$$
\frac{{\left( x+1 \right)}\sp 2}{{\left( x -1 \right)}\sp 2} 
$$
\returnType{Type: Fraction Factored Polynomial Integer}

Other forms of fractions are available.  Use {\tt continuedFraction}
to create a continued fraction.

\spadcommand{continuedFraction(7/12)}
$$
\zag{1}{1}+ \zag{1}{1}+ \zag{1}{2}+ \zag{1}{2} 
$$
\returnType{Type: ContinuedFraction Integer}

Use {\tt partialFraction} to create a partial fraction.
See \domainref{ContinuedFraction} and and \domainref{PartialFraction}
for additional information and examples.

\spadcommand{partialFraction(7,12)}
$$
1 -{\frac{3}{2 \sp 2}}+{\frac{1}{3}} 
$$
\returnType{Type: PartialFraction Integer}

Use conversion to create alternative views of fractions with objects
moved in and out of the numerator and denominator.

\spadcommand{g := 2/3 + 4/5*\%i }
$$
{\frac{2}{3}}+{{\frac{4}{5}} \  i} 
$$
\returnType{Type: Complex Fraction Integer}

%Original Page 375

Conversion is discussed in detail in \sectionref{ugTypesConvert}.

\spadcommand{g :: FRAC COMPLEX INT }
$$
\frac{{10}+{{12} \  i}}{15} 
$$
\returnType{Type: Fraction Complex Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{FullPartialFractionExpansion}

The domain {\tt FullPartialFractionExpansion} implements
factor-free conversion of quotients to full partial fractions.

Our examples will all involve quotients of univariate polynomials
with rational number coefficients.

\spadcommand{Fx := FRAC UP(x, FRAC INT) }
$$
\mbox{\rm Fraction UnivariatePolynomial(x,Fraction Integer)} 
$$
\returnType{Type: Domain}

Here is a simple-looking rational function.

\spadcommand{f : Fx := 36 / (x**5-2*x**4-2*x**3+4*x**2+x-2) }
$$
\frac{36}{{x \sp 5} -{2 \  {x \sp 4}} -{2 \  {x \sp 3}}+{4 \  {x \sp 2}}+x -2} 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

We use \spadfunFrom{fullPartialFraction}{FullPartialFractionExpansion}
to convert it to an object of type\\ 
{\tt FullPartialFractionExpansion}.

\spadcommand{g := fullPartialFraction f }
$$
{\frac{4}{x -2}} -{\frac{4}{x+1}}+
{\sum \sb{\displaystyle {{{ \%A \sp 2} -1}=0}} 
{\frac{-{3 \  \%A} -6}{{\left( x - \%A \right)}\sp 2}}} 
$$
\returnType{Type: FullPartialFractionExpansion(Fraction Integer,UnivariatePolynomial(x,Fraction Integer))}

Use a coercion to change it back into a quotient.

\spadcommand{g :: Fx }
$$
\frac{36}{{x \sp 5} -{2 \  {x \sp 4}} -{2 \  {x \sp 3}}+{4 \  {x \sp 2}}+x -2} 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

Full partial fractions differentiate faster than rational functions.

\spadcommand{g5 := D(g, 5) }
$$
-{\frac{480}{{\left( x -2 \right)}\sp 6}}+
{\frac{480}{{\left( x+1 \right)}\sp 6}}+
{\sum \sb{\displaystyle {{{ \%A \sp 2} -1}=0}} 
{\frac{{{2160} \   \%A}+{4320}}{{\left( x - \%A \right)}\sp 7}}} 
$$
\returnType{Type: FullPartialFractionExpansion(Fraction Integer,UnivariatePolynomial(x,Fraction Integer))}

\spadcommand{f5 := D(f, 5) }
$$
\frac{\left(
\begin{array}{@{}l}
-{{544320} \  {x \sp {10}}}+
{{4354560} \  {x \sp 9}} -
{{14696640} \  {x \sp 8}}+
{{28615680} \  {x \sp 7}} -
\\
\\
\displaystyle
{{40085280} \  {x \sp 6}}+
{{46656000} \  {x \sp 5}} -
{{39411360} \  {x \sp 4}}+
{{18247680} \  {x \sp 3}} -
\\
\\
\displaystyle
{{5870880} \  {x \sp 2}}+
{{3317760} \  x}+{246240}
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
{x \sp {20}} -
{{12} \  {x \sp {19}}}+
{{53} \  {x \sp {18}}} -
{{76} \  {x \sp {17}}} -
{{159} \  {x \sp {16}}}+
{{676} \  {x \sp {15}}} -
{{391} \  {x \sp {14}}} -
\\
\\
\displaystyle
{{1596} \  {x \sp {13}}}+
{{2527} \  {x \sp {12}}}+
{{1148} \  {x \sp {11}}} -
{{4977} \  {x \sp {10}}}+
{{1372} \  {x \sp 9}}+
\\
\\
\displaystyle
{{4907} \  {x \sp 8}} -
{{3444} \  {x \sp 7}} 
-{{2381} \  {x \sp 6}}+
{{2924} \  {x \sp 5}}+
{{276} \  {x \sp 4}} -
\\
\\
\displaystyle
{{1184} \  {x \sp 3}}+
{{208} \  {x \sp 2}}+
{{192} \  x} -
{64} 
\end{array}
\right)}
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

We can check that the two forms represent the same function.

\spadcommand{g5::Fx - f5 }
$$
0 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

Here are some examples that are more complicated.

\spadcommand{f : Fx := (x**5 * (x-1)) / ((x**2 + x + 1)**2 * (x-2)**3) }
$$
\frac{{x \sp 6} -{x \sp 5}} 
{{x \sp 7} -
{4 \  {x \sp 6}}+
{3 \  {x \sp 5}}+
{9 \  {x \sp 3}} -
{6 \  {x \sp 2}} -
{4 \  x} - 8}
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{g := fullPartialFraction f }
$$
\begin{array}{@{}l}
\displaystyle
{\frac{\frac{1952}{2401}}{x -2}}+
{\frac{\frac{464}{343}}{{\left( x -2 \right)}\sp 2}}+
{\frac{\frac{32}{49}}{{\left( x -2 \right)}\sp 3}}+
\\
\\
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2}+ \%A+1}=0}} 
{\frac{-{{\frac{179}{2401}} \  \%A}+{\frac{135}{2401}}}{x - \%A}}}+
\\
\\
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2}+ \%A+1}=0}} 
{\frac{{{\frac{37}{1029}} \   \%A}+
{\frac{20}{1029}}}{{\left( x - \%A \right)}\sp 2}}} 
\end{array}
$$
\returnType{Type: FullPartialFractionExpansion(Fraction Integer,UnivariatePolynomial(x,Fraction Integer))}

\spadcommand{g :: Fx - f }
$$
0 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{f : Fx := (2*x**7-7*x**5+26*x**3+8*x) / (x**8-5*x**6+6*x**4+4*x**2-8) }
$$
\frac{{2 \  {x \sp 7}} -{7 \  {x \sp 5}}+{{26} \  {x \sp 3}}+{8 \  x}} 
{{x \sp 8} -{5 \  {x \sp 6}}+{6 \  {x \sp 4}}+{4 \  {x \sp 2}} -8} 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{g := fullPartialFraction f }
$$
\begin{array}{@{}l}
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2} -2}=0}} 
{\frac{\frac{1}{2}}{x -  \%A}}}+
\\
\\
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2} -2}=0}} 
{\frac{1}{{\left( x -  \%A \right)}\sp 3}}}+
\\
\\
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2}+1}=0}} 
{\frac{\frac{1}{2}}{x - \%A}}} 
\end{array}
$$
\returnType{Type: FullPartialFractionExpansion(Fraction Integer,UnivariatePolynomial(x,Fraction Integer))}

\spadcommand{g :: Fx - f }
$$
0 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{f:Fx := x**3 / (x**21 + 2*x**20 + 4*x**19 + 7*x**18 + 10*x**17 + 17*x**16 + 22*x**15 + 30*x**14 + 36*x**13 + 40*x**12 + 47*x**11 + 46*x**10 + 49*x**9 + 43*x**8 + 38*x**7 + 32*x**6 + 23*x**5 + 19*x**4 + 10*x**3 + 7*x**2 + 2*x + 1)}
$$
\frac{x \sp 3} 
{\left(
\begin{array}{@{}l}
{x \sp {21}}+
{2 \  {x \sp {20}}}+
{4 \  {x \sp {19}}}+
{7 \  {x \sp {18}}}+
{{10} \  {x \sp {17}}}+
{{22} \  {x \sp {15}}}+
{{30} \  {x \sp {14}}}+
\\
\\
\displaystyle
{{36} \  {x \sp {13}}}+
{{40} \  {x \sp {12}}}+
{{47} \  {x \sp {11}}}+
{{46} \  {x \sp {10}}}+
{{49} \  {x \sp 9}}+
{{43} \  {x \sp 8}}+
{{38} \  {x \sp 7}}+
\\
\\
\displaystyle
{{32} \  {x \sp 6}}+
{{23} \  {x \sp 5}}+
{{19} \  {x \sp 4}}+
{{10} \  {x \sp 3}}+
{7 \  {x \sp 2}}+
{2 \  x}+
1
\end{array}
\right)}
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{g := fullPartialFraction f }
$$
\begin{array}{@{}l}
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2}+1}=0}} 
{\frac{{\frac{1}{2}} \  \%A}{x - \%A}}}+
{\sum \sb{\displaystyle {{{ \%A \sp 2}+ \%A+1}=0}} 
{\frac{{{\frac{1}{9}} \   \%A} -{\frac{19}{27}}}{x - \%A}}}+
\\
\\
\displaystyle
{\sum \sb{\displaystyle {{{ \%A \sp 2}+ \%A+1}=0}} 
{\frac{{{\frac{1}{27}} \  \%A} -{\frac{1}{27}}} 
{{\left( x - \%A \right)}\sp 2}}}+
\\
\\
\displaystyle
\sum \sb{\displaystyle {{{ \%A \sp 5}+{ \%A \sp 2}+1}=0}}
\displaystyle
\frac{\left(
\begin{array}{@{}l}
\displaystyle
-{{\frac{96556567040}{912390759099}} \  { \%A \sp 4}}+
{{\frac{420961732891}{912390759099}} \  { \%A \sp 3}} -
\\
\\
\displaystyle
{{\frac{59101056149}{912390759099}} \  { \%A \sp 2}} -
{{\frac{373545875923}{912390759099}} \   \%A}+
\\
\\
\displaystyle
{\frac{529673492498}{912390759099}}
\end{array}
\right)}
{x - \%A}+
\\
\\
\displaystyle
\sum \sb{\displaystyle {{{ \%A \sp 5}+{ \%A \sp 2}+1}=0}}
\displaystyle
\frac{\left(
\begin{array}{@{}l}
\displaystyle
-{{\frac{5580868}{94070601}} \  { \%A \sp 4}} -
{{\frac{2024443}{94070601}} \  { \%A \sp 3}}+
{{\frac{4321919}{94070601}} \  { \%A \sp 2}} -
\\
\\
\displaystyle
{{\frac{84614}{1542141}} \  \%A} -
{\frac{5070620}{94070601}} 
\end{array}
\right)}
{{\left( x - \%A \right)}\sp 2}+
\\
\\
\displaystyle
\sum \sb{\displaystyle {{{ \%A \sp 5}+{ \%A \sp 2}+1}=0}} 
\displaystyle
\frac{\left(
\begin{array}{@{}l}
\displaystyle
{{\frac{1610957}{94070601}} \  { \%A \sp 4}}+
{{\frac{2763014}{94070601}} \  { \%A \sp 3}} -
{{\frac{2016775}{94070601}} \  { \%A \sp 2}}+
\\
\\
\displaystyle
{{\frac{266953}{94070601}} \  \%A}+
{\frac{4529359}{94070601}}
\end{array}
\right)}
{{\left( x - \%A \right)}\sp 3} 
\end{array}
$$
\returnType{Type: FullPartialFractionExpansion(Fraction Integer,UnivariatePolynomial(x,Fraction Integer))}

This verification takes much longer than the conversion to
partial fractions.

\spadcommand{g :: Fx - f }
$$
0 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Fraction Integer)}

For more information, see the paper: Bronstein, M and Salvy, B.
``Full Partial Fraction Decomposition of Rational Functions,'' 
{\it Proceedings of ISSAC'93, Kiev}, ACM Press.  Also see
\domainref{PartialFraction} for standard partial fraction decompositions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{GeneralDistributedMultivariatePolynomial}

{\tt DistributedMultivariatePolynomial} which is abbreviated as DMP and 
{\tt Homogeneous\-DistributedMultivariatePolynomial}, which is abbreviated
as HDMP, are very similar to MultivariatePolynomial except that 
they are represented and displayed in a non-recursive manner.
\begin{verbatim}
  (d1,d2,d3) : DMP([z,y,x],FRAC INT) 
\end{verbatim}
\returnType{Type: Void}
The constructor DMP orders its monomials lexicographically while
HDMP orders them by total order refined by reverse lexicographic
order.
\begin{verbatim}
  d1 := -4*z + 4*y**2*x + 16*x**2 + 1 
\end{verbatim}
$$
{4 \ z}+{4 \ {y^2} \ x}+{{16} \ {x^2}}+1
$$
\returnType{Type: DistributeMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  d2 := 2*z*y**2 + 4*x + 1 
\end{verbatim}
$$
{2 \ z \ {y^2}}+{4 \ x}+1
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}

\begin{verbatim}
  d3 := 2*z*x**2 - 2*y**2 - x 
\end{verbatim}
$$
{2 \ z \ {x^2}} -{2 \ {y^2}} -x
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
These constructors are mostly used in Groebner basis calculations.
\begin{verbatim}
  groebner [d1,d2,d3]
        1568  6   1264  5    6   4   182  3   2047  2    103      2857
   [z - ---- x  - ---- x  + --- x  + --- x  - ---- x  - ---- x - -----,
        2745       305      305      549       610      2745     10980
     2    112  6    84  5   1264  4    13  3    84  2   1772       2
    y  + ---- x  - --- x  - ---- x  - --- x  + --- x  + ---- x + ----,
         2745      305       305      549      305      2745     2745
     7   29  6   17  4   11  3    1  2   15     1
    x  + -- x  - -- x  - -- x  + -- x  + -- x + -]
          4      16       8      32      16     4
\end{verbatim}
$$
\begin{array}{@{}l}
\displaystyle
\left[
{z - {{ \frac{{1568}}{{2745}} \ {x^6}} - {{ \frac{{1264}}{{305}}} \
{x^5}}+{{ \frac{6}{{305}}} \ {x^4}}+{{ \frac{{182}}{{549}}} \ {x^3}} - {{
\frac{{2047}}{{610}}} \ {x^2}} - {{ \frac{{103}}{{2745}}} \ x} -{
\frac{{2857}}{{10980}}}}},
\right.
\\
\displaystyle
\left.
\: {{y^2}+{{ \frac{{112}}{{2745}}} \ {x^6}} -{{
\frac{{84}}{{305}}} \ {x^5}} -{{ \frac{{1264}}{{305}}} \ {x^4}} -{{
\frac{{13}}{{549}}} \ {x^3}}+{{ \frac{{84}}{{305}}} \ {x^2}}+{{
\frac{{1772}}{{2745}}} \ x}+{ \frac{2}{{2745}}}},
\right.
\\
\displaystyle
\left.
\: {{x^7}}+{{
\frac{{29}}{{4}} \ {x^6}} -{{ \frac{{17}}{{16}}} \ {x^4}} -{{
\frac{{11}}{8}} \ {x^3}}+{{ \frac{1}{{32}}} \ {x^2}}+{{ \frac{{15}}{{16}}}
\ x}+{ \frac{1}{4}}}
\right]
\end{array}
$$
\returnType{
Type: List DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  (n1,n2,n3) : HDMP([z,y,x],FRAC INT)
\end{verbatim}
\returnType{Type: Void}
\begin{verbatim}
  n1 := d1
\end{verbatim}
$$
{4 \ {y^2} \ x}+{{16} \ {x^2}} -{4 \ z}+1
$$
\returnType{
Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  n2 := d2
\end{verbatim}
$$
{2 \ z \ {y^2}}+{4 \ x}+1
$$
\returnType{
Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  n3 := d3
\end{verbatim}
$$
{2 \ z \ {x^2}} -{2 \ {y^2}} -x
$$
\returnType{
Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
Note that we get a different Groebner basis when we use the HDMP
polynomials, as expected.
\begin{verbatim}
  groebner [n1,n2,n3]
\end{verbatim}
$$
\begin{array}{@{}l}
\displaystyle
\left[
{{y^4}+{2 \ {x^3}} -{{ \frac{3}{2}} \ {x^2}}+{{ \frac{1}{2}} \ z} -{
\frac{1}{8}}},
\: {{x^4}+{{ \frac{{29}}{4}} \ {x^3}} -{{ \frac{1}{8}} \
{y^2}} -{{ \frac{7}{4}} \ z \ x} -{{ \frac{9}{{16}}} \ x} -{
\frac{1}{4}}},
\right.
\\
\displaystyle
\left.
\: {{z \ {y^2}}+{2 \ x}+{ \frac{1}{2}}}, \: {{{y^2} \ x}+{4
\ {x^2}} -z+{ \frac{1}{4}}},
\right.
\\
\displaystyle
\left.
\: {{z \ {x^2}} -{y^2} -{{ \frac{1}{2}} \
x}}, \: {{z^2} -{4 \ {y^2}}+{2 \ {x^2}} -{{ \frac{1}{4}} \ z} -{{
\frac{3}{2}} \ x}}
\right]
\end{array}
$$
\returnType{
Type: List HomogeneousDistributedMultivariatePolynomial([z,y,x],
Fraction Integer)}
{\tt GeneralDistributedMultivariatePolynomial} is somewhat more flexible in
the sense that as well as accepting a list of variables to specify the
variable ordering, it also takes a predicate on exponent vectors to
specify the term ordering.  With this polynomial type the user can
experiment with the effect of using completely arbitrary term orderings.  
This flexibility is mostly important for algorithms such as Groebner 
basis calculations which can be very sensitive to term ordering.

See 
\domainref{Polynomial}\\
\domainref{UnivariatePolynomial}\\
\domainref{MultivariatePolynomial}\\
\domainref{HomogeneousDistributedMultivariatePolynomial}, and\\
\domainref{DistributedMultivariatePolynomial}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{GeneralSparseTable}

Sometimes when working with tables there is a natural value to use as
the entry in all but a few cases.  The {\tt GeneralSparseTable}
constructor can be used to provide any table type with a default value
for entries.  See \domainref{Table} for general information about tables.  

Suppose we launched a fund-raising campaign to raise fifty thousand dollars.
To record the contributions, we want a table with strings as keys
(for the names) and integer entries (for the amount).
In a data base of cash contributions, unless someone
has been explicitly entered, it is reasonable to assume they have made
a zero dollar contribution.

This creates a keyed access file with default entry {\tt 0}.

\spadcommand{patrons: GeneralSparseTable(String, Integer, KeyedAccessFile(Integer), 0) := table() ; }
\returnType{Type: GeneralSparseTable(String,Integer,KeyedAccessFile Integer,0)}


Now {\tt patrons} can be used just as any other table.
Here we record two gifts.

\spadcommand{patrons."Smith" := 10500 }
$$
10500 
$$
\returnType{Type: PositiveInteger}

\spadcommand{patrons."Jones" := 22000 }
$$
22000 
$$
\returnType{Type: PositiveInteger}

Now let us look up the size of the contributions from Jones and Stingy.

\spadcommand{patrons."Jones"  }
$$
22000 
$$
\returnType{Type: PositiveInteger}

\spadcommand{patrons."Stingy" }
$$
0 
$$
\returnType{Type: NonNegativeInteger}

Have we met our seventy thousand dollar goal?

\spadcommand{reduce(+, entries patrons) }
$$
32500 
$$
\returnType{Type: PositiveInteger}

%Original Page 376

So the project is cancelled and we can delete the data base:

\spadcommand{)system rm -r kaf*.sdata }

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{GroebnerFactorizationPackage}

Solving systems of polynomial equations with the Gr\"{o}bner basis
algorithm can often be very time consuming because, in general, the
algorithm has exponential run-time.  These systems, which often come
from concrete applications, frequently have symmetries which are not
taken advantage of by the algorithm.  However, it often happens in
this case that the polynomials which occur during the Gr\"{o}bner
calculations are reducible.  Since Axiom has an excellent polynomial
factorization algorithm, it is very natural to combine the Gr\"{o}bner
and factorization algorithms.

{\tt GroebnerFactorizationPackage} exports the
\spadfunFrom{groebnerFactorize}{GroebnerFactorizationPackage}
operation which implements a modified Gr\"{o}bner basis algorithm.  In
this algorithm, each polynomial that is to be put into the partial
list of the basis is first factored.  The remaining calculation is
split into as many parts as there are irreducible factors.  Call these
factors $p_1, \ldots,p_n.$ In the branches corresponding to $p_2,
\ldots,p_n,$ the factor $p_1$ can be divided out, and so on.  This
package also contains operations that allow you to specify the
polynomials that are not zero on the common roots of the final
Gr\"{o}bner basis.

Here is an example from chemistry.  In a theoretical model of the
cyclohexan ${\rm C}_6{\rm H}_{12}$, the six carbon atoms each sit in
the center of gravity of a tetrahedron that has two hydrogen atoms and
two carbon atoms at its corners.  We first normalize and set the
length of each edge to 1.  Hence, the distances of one fixed carbon
atom to each of its immediate neighbours is 1.  We will denote the
distances to the other three carbon atoms by $x$, $y$ and $z$.

A.~Dress developed a theory to decide whether a set of points
and distances between them can be realized in an $n$-dimensional space.
Here, of course, we have $n = 3$.

\spadcommand{mfzn : SQMATRIX(6,DMP([x,y,z],Fraction INT)) := [ [0,1,1,1,1,1], [1,0,1,8/3,x,8/3], [1,1,0,1,8/3,y], [1,8/3,1,0,1,8/3], [1,x,8/3,1,0,1], [1,8/3,y,8/3,1,0] ] }
$$
\left[
\begin{array}{cccccc}
0 & 1 & 1 & 1 & 1 & 1 \\ 
1 & 0 & 1 & {\frac{8}{3}} & x & {\frac{8}{3}} \\ 
1 & 1 & 0 & 1 & {\frac{8}{3}} & y \\ 
1 & {\frac{8}{3}} & 1 & 0 & 1 & {\frac{8}{3}} \\ 
1 & x & {\frac{8}{3}} & 1 & 0 & 1 \\ 
1 & {\frac{8}{3}} & y & {\frac{8}{3}} & 1 & 0 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(6,DistributedMultivariatePolynomial([x,y,z],Fraction Integer))}

%Original Page 377

For the cyclohexan, the distances have to satisfy this equation.

\spadcommand{eq := determinant mfzn }
$$
\begin{array}{@{}l}
\displaystyle
-{{x \sp 2} \  {y \sp 2}}+
{{\frac{22}{3}} \  {x \sp 2} \  y} -
{{\frac{25}{9}} \  {x \sp 2}}+
{{\frac{22}{3}} \  x \  {y \sp 2}} -
{{\frac{388}{9}} \  x \  y} -
\\
\\
\displaystyle
{{\frac{250}{27}} \  x} -
{{\frac{25}{9}} \  {y \sp 2}} -
{{\frac{250}{27}} \  y}+
{\frac{14575}{81}} 
\end{array}
$$
\returnType{Type: DistributedMultivariatePolynomial([x,y,z],Fraction Integer)}

They also must satisfy the equations
given by cyclic shifts of the indeterminates.

\spadcommand{groebnerFactorize [eq, eval(eq, [x,y,z], [y,z,x]), eval(eq, [x,y,z], [z,x,y])] }
$$
\begin{array}{@{}l}
\left[

\begin{array}{@{}l}
\displaystyle
\left[ 
{x \  y}+
{x \  z} -
{{\frac{22}{3}} \  x}+
{y \  z} -
{{\frac{22}{3}} \  y} -
{{\frac{22}{3}} \  z}+
{\frac{121}{3}}, 
\right.
\\
\\
\displaystyle
{x \  {z \sp 2}} -
{{\frac{22}{3}} \  x \  z}+
{{\frac{25}{9}} \  x}+
{y \  {z \sp 2}} -
{{\frac{22}{3}} \ y \  z}+
{{\frac{25}{9}} \  y} -
{{\frac{22}{3}} \  {z \sp 2}}+
{{\frac{388}{9}} \  z}+
{\frac{250}{27}}, 
\\
\\
\displaystyle
\left.
\begin{array}{@{}l}
\displaystyle
{{y \sp 2} \  {z \sp 2}} -
{{\frac{22}{3}} \  {y \sp 2} \  z}+
{{\frac{25}{9}} \  {y \sp 2}} -
{{\frac{22}{3}} \  y \  {z \sp 2}}+
{{\frac{388}{9}} \  y \  z}+
{{\frac{250}{27}} \  y}+
\\
\\
\displaystyle
{{\frac{25}{9}} \  {z \sp 2}}+
{{\frac{250}{27}} \  z} -
{\frac{14575}{81}}
\end{array}
\right],
\end{array}
\right.
\\
\\
\displaystyle
{\left[ 
{x+y -{\frac{21994}{5625}}}, 
{{y \sp 2} -{{\frac{21994}{5625}} \  y}+{\frac{4427}{675}}}, 
{z -{\frac{463}{87}}} 
\right]},
\\
\\
\displaystyle
{\left[ 
{{x \sp 2} -
{{\frac{1}{2}} \  x \  z} -
{{\frac{11}{2}} \  x} -
{{\frac{5}{6}} \  z}+
{\frac{265}{18}}}, 
{y -z}, 
{{z \sp 2} -{{\frac{38}{3}} \  z}+{\frac{265}{9}}} 
\right]},
\\
\\
\displaystyle
{\left[ 
{x -{\frac{25}{9}}}, 
{y -{\frac{11}{3}}}, 
{z -{\frac{11}{3}}} \right]},
\\
\\
\displaystyle
{\left[ 
{x -{\frac{11}{3}}}, 
{y -{\frac{11}{3}}}, 
{z -{\frac{11}{3}}} 
\right]},
\\
\\
\displaystyle
{\left[ 
{x+{\frac{5}{3}}}, 
{y+{\frac{5}{3}}}, 
{z+{\frac{5}{3}}} 
\right]},
\\
\\
\displaystyle
\left.
{\left[ 
{x -{\frac{19}{3}}}, 
{y+{\frac{5}{3}}}, 
{z+{\frac{5}{3}}} 
\right]}
\right]
\end{array}
$$
\returnType{Type: List List 
DistributedMultivariatePolynomial([x,y,z],Fraction Integer)}

The union of the solutions of this list is the solution of our
original problem.  If we impose positivity conditions, we get two
relevant ideals.  One ideal is zero-dimensional, namely $x = y = z = 11/3$, 
and this determines the ``boat'' form of the cyclohexan.  The
other ideal is one-dimensional, which means that we have a solution
space given by one parameter.  This gives the ``chair'' form of the
cyclohexan.  The parameter describes the angle of the ``back of the
chair.''

\spadfunFrom{groebnerFactorize}{GroebnerFactorizationPackage} has an
optional {\tt Boolean}-valued second argument.  When it is {\tt true}
partial results are displayed, since it may happen that the
calculation does not terminate in a reasonable time.  See the source
code for {\tt GroebnerFactorizationPackage} in {\bf groebf.input} 
for more details about the algorithms used.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{GroebnerPackage}

Example to call groebner:
\begin{verbatim}
  s1:DMP[w,p,z,t,s,b]RN:= 45*p + 35*s - 165*b - 36
  s2:DMP[w,p,z,t,s,b]RN:= 35*p + 40*z + 25*t - 27*s
  s3:DMP[w,p,z,t,s,b]RN:= 15*w + 25*p*s + 30*z - 18*t - 165*b**2
  s4:DMP[w,p,z,t,s,b]RN:= -9*w + 15*p*t + 20*z*s
  s5:DMP[w,p,z,t,s,b]RN:= w*p + 2*z*t - 11*b**3
  s6:DMP[w,p,z,t,s,b]RN:= 99*w - 11*b*s + 3*b**2
  s7:DMP[w,p,z,t,s,b]RN:= b**2 + 33/50*b + 2673/10000

  sn7:=[s1,s2,s3,s4,s5,s6,s7]

  groebner(sn7,info)
\end{verbatim}
groebner calculates a minimal Groebner Basis
all reductions are TOTAL reductions

To get the reduced critical pairs do:
\begin{verbatim}
  groebner(sn7,"redcrit")
\end{verbatim}
You can get other information by calling:
\begin{verbatim}
  groebner(sn7,"info")
\end{verbatim}
which returns:
\begin{verbatim}
      ci  =>  Leading monomial  for critpair calculation
      tci =>  Number of terms of polynomial i
      cj  =>  Leading monomial  for critpair calculation
      tcj =>  Number of terms of polynomial j
      c   =>  Leading monomial of critpair polynomial
      tc  =>  Number of terms of critpair polynomial
      rc  =>  Leading monomial of redcritpair polynomial
      trc =>  Number of terms of redcritpair polynomial
      tF  =>  Number of polynomials in reduction list F
      tD  =>  Number of critpairs still to do
\end{verbatim} 
See 
\domainref{GroebnerPackage}\\
\domainref{DistributedMultivariatePolynomial}\\
\domainref{HomogeneousDistributedMultivariatePolynomial}\\
\domainref{EuclideanGroebnerBasisPackage}

%Original Page 378

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Heap}

The domain {\tt Heap(S)} implements a priority queue of objects of
type {\tt S} such that the operation {\tt extract!} removes and
returns the maximum element.  The implementation represents heaps as
flexible arrays (see \domainref{FlexibleArray}.)
The representation and algorithms give complexity of $O(\log(n))$ 
for insertion and extractions, and $O(n)$ for construction.

Create a heap of six elements.

\spadcommand{h := heap [-4,9,11,2,7,-7]}
$$
\left[
{11}, 7, 9, -4, 2, -7 
\right]
$$
\returnType{Type: Heap Integer}

Use {\tt insert!} to add an element.

\spadcommand{insert!(3,h)}
$$
\left[
{11}, 7, 9, -4, 2, -7, 3 
\right]
$$
\returnType{Type: Heap Integer}

The operation {\tt extract!} removes and returns the maximum element.

\spadcommand{extract! h}
$$
11 
$$
\returnType{Type: PositiveInteger}

The internal structure of {\tt h} has been appropriately adjusted.

\spadcommand{h}
$$
\left[
9, 7, 3, -4, 2, -7 
\right]
$$
\returnType{Type: Heap Integer}

Now {\tt extract!} elements repeatedly until none are left, collecting
the elements in a list.

\spadcommand{[extract!(h) while not empty?(h)]}
$$
\left[
9, 7, 3, 2, -4, -7 
\right]
$$
\returnType{Type: List Integer}

Another way to produce the same result is by defining a {\tt heapsort}
function.

\spadcommand{heapsort(x) == (empty? x => []; cons(extract!(x),heapsort x))}
\returnType{Type: Void}

Create another sample heap.

\spadcommand{h1 := heap [17,-4,9,-11,2,7,-7]}
$$
\left[
{17}, 2, 9, -{11}, -4, 7, -7 
\right]
$$
\returnType{Type: Heap Integer}

%Original Page 379

Apply {\tt heapsort} to present elements in order.

\spadcommand{heapsort h1}
$$
\left[
{17}, 9, 7, 2, -4, -7, -{11} 
\right]
$$
\returnType{Type: List Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{HexadecimalExpansion}

All rationals have repeating hexadecimal expansions.  The operation
\spadfunFrom{hex}{HexadecimalExpansion} returns these expansions of
type {\tt HexadecimalExpansion}.  Operations to access the individual
numerals of a hexadecimal expansion can be obtained by converting the
value to {\tt RadixExpansion(16)}.  More examples of expansions are
available in the 
\domainref{DecimalExpansion}, \domainref{BinaryExpansion}, and
\domainref{RadixExpansion}.

This is a hexadecimal expansion of a rational number.

\spadcommand{r := hex(22/7) }
$$
3.{\overline {249}} 
$$
\returnType{Type: HexadecimalExpansion}

Arithmetic is exact.

\spadcommand{r + hex(6/7) }
$$
4 
$$
\returnType{Type: HexadecimalExpansion}

The period of the expansion can be short or long \ldots

\spadcommand{[hex(1/i) for i in 350..354] }
$$
\begin{array}{@{}l}
\left[
{0.0{\overline {\rm 0BB3EE721A54D88}}}, 
{0.{\overline {\rm 00BAB6561}}}, 
{0.{00}{\overline {\rm BA2E8}}}, 
\right.
\\
\\
\displaystyle
\left.
{0.{\overline {\rm 00B9A7862A0FF465879D5F}}}, 
{0.0{\overline {\rm 0B92143FA36F5E02E4850FE8DBD78}}} 
\right]
\end{array}
$$
\returnType{Type: List HexadecimalExpansion}

or very long!

\spadcommand{hex(1/1007) }
$$
\begin{array}{@{}l}
0.{\overline 
{\rm 0041149783F0BF2C7D13933192AF6980619EE345E91EC2BB9D5CC}}
\\
\displaystyle
\ \ {\overline
{\rm A5C071E40926E54E8DDAE24196C0B2F8A0AAD60DBA57F5D4C8}}
\\
\displaystyle
\ \ {\overline
{\rm 536262210C74F1}}
\end{array}
$$
\returnType{Type: HexadecimalExpansion}

These numbers are bona fide algebraic objects.

\spadcommand{p := hex(1/4)*x**2 + hex(2/3)*x + hex(4/9)  }
$$
{{0.4} \  {x \sp 2}}+{{0.{\overline {\rm A}}} \  x}+{0.{\overline {\rm 71C}}} 
$$
\returnType{Type: Polynomial HexadecimalExpansion}

\spadcommand{q := D(p, x) }
$$
{{0.8} \  x}+{0.{\overline {\rm A}}} 
$$
\returnType{Type: Polynomial HexadecimalExpansion}

\spadcommand{g := gcd(p, q)}
$$
x+{1.{\overline 5}} 
$$
\returnType{Type: Polynomial HexadecimalExpansion}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{HomogeneousDistributedMultivariatePolynomial}

{\tt DistributedMultivariatePolynomial} which is abbreviated as DMP and 
{\tt Homogeneous\-DistributedMultivariatePolynomial}, which is abbreviated
as HDMP, are very similar to MultivariatePolynomial except that 
they are represented and displayed in a non-recursive manner.
\begin{verbatim}
  (d1,d2,d3) : DMP([z,y,x],FRAC INT) 
\end{verbatim}
\returnType{Type: Void}
The constructor DMP orders its monomials lexicographically while
HDMP orders them by total order refined by reverse lexicographic
order.
\begin{verbatim}
  d1 := -4*z + 4*y**2*x + 16*x**2 + 1 
\end{verbatim}
$$
-{4 \ z}+{4 \ {y^2} \ x}+{{16} \ {x^2}}+1
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  d2 := 2*z*y**2 + 4*x + 1 
\end{verbatim}
$$
{2 \ z \ {y^2}}+{4 \ x}+1
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  d3 := 2*z*x**2 - 2*y**2 - x 
\end{verbatim}
$$
{2 \ z \ {x^2}} -{2 \ {y^2}} -x
$$
\returnType{Type: DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
These constructors are mostly used in Groebner basis calculations.
\begin{verbatim}
  groebner [d1,d2,d3]
\end{verbatim}
$$
\begin{array}{@{}l}
\displaystyle
\left[
{z -{{ \frac{{1568}}{2745}}} \ {x^6}} -{{ \frac{{1264}}{{305}} \
{x^5}}+{{ \frac{6}{{305}}} \ {x^4}}+{{ \frac{{182}}{{549}}} \ {x^3}} -{{
\frac{{2047}}{{610}}} \ {x^2}} -{{ \frac{{103}}{{2745}}} \ x} -{
\frac{{2857}}{{10980}}}},
\right.
\\
\displaystyle
\left.
\: {{y^2}+{{ \frac{{112}}{{2745}}} \ {x^6}} -{{
\frac{{84}}{{305}}} \ {x^5}} -{{ \frac{{1264}}{{305}}} \ {x^4}} -{{
\frac{{13}}{{549}}} \ {x^3}}+{{ \frac{{84}}{{305}}} \ {x^2}}+{{
\frac{{1772}}{{2745}}} \ x}+{ \frac{2}{{2745}}}},
\right.
\\
\displaystyle
\left.
\: {{x^7}+{{
\frac{{29}}{4}} \ {x^6}} -{{ \frac{{17}}{{16}}} \ {x^4}} -{{
\frac{{11}}{8}} \ {x^3}}+{{ \frac{1}{{32}}} \ {x^2}}+{{ \frac{{15}}{{16}}}
\ x}+{ \frac{1}{4}}}
\right]
\end{array}
$$
\returnType{
Type: List DistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  (n1,n2,n3) : HDMP([z,y,x],FRAC INT)
\end{verbatim}
\returnType{Type: Void}
\begin{verbatim}
  n1 := d1
\end{verbatim}
$$
{4 \ {y^2} \ x}+{{16} \ {x^2}} -{4 \ z}+1
$$
\returnType{
Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  n2 := d2
\end{verbatim}
$$
{2 \ z \ {y^2}}+{4 \ x}+1
$$
\returnType{
Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
  n3 := d3
\end{verbatim}
$$
{2 \ z \ {x^2}} -{2 \ {y^2}} -x
$$
\returnType{
Type: HomogeneousDistributedMultivariatePolynomial([z,y,x],Fraction Integer)}
\begin{verbatim}
Note that we get a different Groebner basis when we use the HDMP
polynomials, as expected.
\begin{verbatim}
  groebner [n1,n2,n3]
\end{verbatim}
$$
\begin{array}{@{}l}
\displaystyle
\left[
{{y^4}+{2 \ {x^3}} -{{ \frac{3}{2}} \ {x^2}}+{{ \frac{1}{2}} \ z} -{
\frac{1}{8}}},
\: {{x^4}+{{ \frac{{29}}{4}} \ {x^3}} -{{ \frac{1}{8}} \
{y^2}} -{{ \frac{7}{4}} \ z \ x} -{{ \frac{9}{{16}}} \ x} -{
\frac{1}{4}}},
\right.
\\
\displaystyle
\left.
\: {{z \ {y^2}}+{2 \ x}+{ \frac{1}{2}}}, \: {{{y^2} \ x}+{4
\ {x^2}} -z+{ \frac{1}{4}}},
\right.
\\
\displaystyle
\left.
\: {{z \ {x^2}} -{y^2} -{{ \frac{1}{2}} \
x}}, \: {{z^2} -{4 \ {y^2}}+{2 \ {x^2}} -{{ \frac{1}{4}} \ z} -{{
\frac{3}{2}} \ x}}
\right]
\end{array}
$$
\returnType{
Type: List HomogeneousDistributedMultivariatePolynomial([z,y,x],
Fraction Integer)}
{\tt GeneralDistributedMultivariatePolynomial} is somewhat more flexible in
the sense that as well as accepting a list of variables to specify the
variable ordering, it also takes a predicate on exponent vectors to
specify the term ordering.  With this polynomial type the user can
experiment with the effect of using completely arbitrary term orderings.  
This flexibility is mostly important for algorithms such as Groebner 
basis calculations which can be very sensitive to term ordering.

See 
\domainref{Polynomial},\\
\domainref{UnivariatePolynomial},\\
\domainref{MultivariatePolynomial},\\
\domainref{DistributedMultivariatePolynomial}, and\\
\domainref{GeneralDistributedMultivariatePolynomial}

%Original Page 380

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Integer}

Axiom provides many operations for manipulating arbitrary precision
integers.  In this section we will show some of those that come from
{\tt Integer} itself plus some that are implemented in other packages.
More examples of using integers are in the following sections:
\sectionref{ugIntroNumbers},
\domainref{IntegerNumberTheoryFunctions},
\domainref{DecimalExpansion}, \domainref{BinaryExpansion}, 
\domainref{HexadecimalExpansion}, and \domainref{RadixExpansion}.

\subsection{Basic Functions}

The size of an integer in Axiom is only limited by the amount of
computer storage you have available.  The usual arithmetic operations
are available.

\spadcommand{2**(5678 - 4856 + 2 * 17)}
$$
\begin{array}{@{}l}
48048107704350081471815409251259243912395261398716822634738556100
\\
\displaystyle
88084200076308293086342527091412083743074572278211496076276922026
\\
\displaystyle
43343568752733498024953930242542523045817764949544214392905306388
\\
\displaystyle
478705146745768073877141698859815495632935288783334250628775936
\end{array}
$$
\returnType{Type: PositiveInteger}

There are a number of ways of working with the sign of an integer.
Let's use this {\tt x} as an example.

\spadcommand{x := -101 }
$$
-{101} 
$$
\returnType{Type: Integer}

First of all, there is the absolute value function.

\spadcommand{abs(x) }
$$
101 
$$
\returnType{Type: PositiveInteger}

The \spadfunFrom{sign}{Integer} operation returns {\tt -1} if its argument
is negative, {\tt 0} if zero and {\tt 1} if positive.

\spadcommand{sign(x) }
$$
-1 
$$
\returnType{Type: Integer}

%Original Page 381

You can determine if an integer is negative in several other ways.

\spadcommand{x < 0 }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{x <= -1 }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{negative?(x) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Similarly, you can find out if it is positive.

\spadcommand{x > 0 }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{x >= 1 }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{positive?(x) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

This is the recommended way of determining whether an integer is zero.

\spadcommand{zero?(x) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\boxer{4.6in}{
Use the \spadfunFrom{zero?}{Integer} operation whenever you are
testing any mathematical object for equality with zero.  This is
usually more efficient that using {\tt =} (think of matrices: it is
easier to tell if a matrix is zero by just checking term by term than
constructing another ``zero'' matrix and comparing the two matrices
term by term) and also avoids the problem that {\tt =} is usually used
for creating equations.\\
}

This is the recommended way of determining whether an integer is equal
to one.

\spadcommand{one?(x) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

%Original Page 382

This syntax is used to test equality using \spadopFrom{=}{Integer}.
It says that you want a {\tt Boolean} ({\tt true} or {\tt false})
answer rather than an equation.

\spadcommand{(x = -101)@Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The operations \spadfunFrom{odd?}{Integer} and
\spadfunFrom{even?}{Integer} determine whether an integer is odd or
even, respectively.  They each return a {\tt Boolean} object.

\spadcommand{odd?(x) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{even?(x) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

The operation \spadfunFrom{gcd}{Integer} computes the greatest common
divisor of two integers.

\spadcommand{gcd(56788,43688)}
$$
4 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{lcm}{Integer} computes their least common multiple.

\spadcommand{lcm(56788,43688)}
$$
620238536 
$$
\returnType{Type: PositiveInteger}

To determine the maximum of two integers, use \spadfunFrom{max}{Integer}.

\spadcommand{max(678,567)}
$$
678 
$$
\returnType{Type: PositiveInteger}

To determine the minimum, use \spadfunFrom{min}{Integer}.

\spadcommand{min(678,567)}
$$
567 
$$
\returnType{Type: PositiveInteger}

The {\tt reduce} operation is used to extend binary operations to more
than two arguments.  For example, you can use {\tt reduce} to find the
maximum integer in a list or compute the least common multiple of all
integers in the list.

\spadcommand{reduce(max,[2,45,-89,78,100,-45])}
$$
100 
$$
\returnType{Type: PositiveInteger}

\spadcommand{reduce(min,[2,45,-89,78,100,-45])}
$$
-{89} 
$$
\returnType{Type: Integer}

\spadcommand{reduce(gcd,[2,45,-89,78,100,-45])}
$$
1 
$$
\returnType{Type: PositiveInteger}

%Original Page 383

\spadcommand{reduce(lcm,[2,45,-89,78,100,-45])}
$$
1041300 
$$
\returnType{Type: PositiveInteger}

The infix operator ``/'' is {\it not} used to compute the quotient of
integers.  Rather, it is used to create rational numbers as described
in \domainref{Fraction}.

\spadcommand{13 / 4}
$$
\frac{13}{4} 
$$
\returnType{Type: Fraction Integer}

The infix operation \spadfunFrom{quo}{Integer} computes the integer
quotient.

\spadcommand{13 quo 4}
$$
3 
$$
\returnType{Type: PositiveInteger}

The infix operation \spadfunFrom{rem}{Integer} computes the integer
remainder.

\spadcommand{13 rem 4}
$$
1 
$$
\returnType{Type: PositiveInteger}

One integer is evenly divisible by another if the remainder is zero.
The operation \spadfunFrom{exquo}{Integer} can also be used.  See
\sectionref{ugTypesUnions} for an example.

\spadcommand{zero?(167604736446952 rem 2003644)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The operation \spadfunFrom{divide}{Integer} returns a record of the
quotient and remainder and thus is more efficient when both are needed.

\spadcommand{d := divide(13,4) }
$$
\left[
{quotient=3}, {remainder=1} 
\right]
$$
\returnType{Type: Record(quotient: Integer,remainder: Integer)}

\spadcommand{d.quotient }
$$
3 
$$
\returnType{Type: PositiveInteger}

Records are discussed in detail in \sectionref{ugTypesRecords}.

\spadcommand{d.remainder }
$$
1 
$$
\returnType{Type: PositiveInteger}

\subsection{Primes and Factorization}

Use the operation \spadfunFrom{factor}{Integer} to factor integers.
It returns an object of type {\tt Factored Integer}.
See \domainref{Factored} 
for a discussion of the manipulation of factored objects.

\spadcommand{factor 102400}
$$
{2 \sp {12}} \  {5 \sp 2} 
$$
\returnType{Type: Factored Integer}

%Original Page 384

The operation \spadfunFrom{prime?}{Integer} returns {\tt true} or 
{\tt false} depending on whether its argument is a prime.

\spadcommand{prime? 7}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{prime? 8}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

The operation \spadfunFrom{nextPrime}{IntegerPrimesPackage} returns the
least prime number greater than its argument.

\spadcommand{nextPrime 100}
$$
101 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{prevPrime}{IntegerPrimesPackage} returns
the greatest prime number less than its argument.

\spadcommand{prevPrime 100}
$$
97 
$$
\returnType{Type: PositiveInteger}

To compute all primes between two integers (inclusively), use the
operation \spadfunFrom{primes}{IntegerPrimesPackage}.

\spadcommand{primes(100,175)}
$$
\left[
{173}, {167}, {163}, {157}, {151}, {149}, {139}, {137}, 
{131}, {127}, {113}, {109}, {107}, {103}, {101} 
\right]
$$
\returnType{Type: List Integer}

You might sometimes want to see the factorization of an integer
when it is considered a {\it Gaussian integer}.
See \domainref{Complex} for more details.

\spadcommand{factor(2 :: Complex Integer)}
$$
-{i \  {{\left( 1+i 
\right)}
\sp 2}} 
$$
\returnType{Type: Factored Complex Integer}

\subsection{Some Number Theoretic Functions}

Axiom provides several number theoretic operations for integers.
More examples are in \domainref{IntegerNumberTheoryFunctions}.


The operation \spadfunFrom{fibonacci}{IntegerNumberTheoryFunctions}
computes the Fibonacci numbers.  The algorithm has running time
$O\,(\log^3(n))$ for argument {\tt n}.

\spadcommand{[fibonacci(k) for k in 0..]}
$$
\left[
0, 1, 1, 2, 3, 5, 8, {13}, {21}, {34}, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

The operation \spadfunFrom{legendre}{IntegerNumberTheoryFunctions}
computes the Legendre symbol for its two integer arguments where the
second one is prime.  If you know the second argument to be prime, use
\spadfunFrom{jacobi}{IntegerNumberTheoryFunctions} instead where no
check is made.

\spadcommand{[legendre(i,11) for i in 0..10]}
$$
\left[
0, 1, -1, 1, 1, 1, -1, -1, -1, 1, -1 
\right]
$$
\returnType{Type: List Integer}

%Original Page 385

The operation \spadfunFrom{jacobi}{IntegerNumberTheoryFunctions}
computes the Jacobi symbol for its two integer arguments.  By
convention, {\tt 0} is returned if the greatest common divisor of the
numerator and denominator is not {\tt 1}.

\spadcommand{[jacobi(i,15) for i in 0..9]}
$$
\left[
0, 1, 1, 0, 1, 0, 0, -1, 1, 0 
\right]
$$
\returnType{Type: List Integer}

The operation \spadfunFrom{eulerPhi}{IntegerNumberTheoryFunctions}
computes the values of Euler's $\phi$-function where $\phi(n)$ equals
the number of positive integers less than or equal to {\tt n} that are
relatively prime to the positive integer {\tt n}.

\spadcommand{[eulerPhi i for i in 1..]}
$$
\left[
1, 1, 2, 2, 4, 2, 6, 4, 6, 4, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

The operation \spadfunFrom{moebiusMu}{IntegerNumberTheoryFunctions}
computes the M\"{o}bius $\mu$ function.

\spadcommand{[moebiusMu i for i in 1..]}
$$
\left[
1, -1, -1, 0, -1, 1, -1, 0, 0, 1, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

Although they have somewhat limited utility, Axiom provides Roman numerals.

\spadcommand{a := roman(78) }
$$
{\rm LXXVIII }
$$
\returnType{Type: RomanNumeral}

\spadcommand{b := roman(87) }
$$
{\rm LXXXVII }
$$
\returnType{Type: RomanNumeral}

\spadcommand{a + b }
$$
{\rm CLXV }
$$
\returnType{Type: RomanNumeral}

\spadcommand{a * b }
$$
{\rm MMMMMMDCCLXXXVI }
$$
\returnType{Type: RomanNumeral}

\spadcommand{b rem a }
$$
{\rm IX }
$$
\returnType{Type: RomanNumeral}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{IntegerLinearDependence}

The elements $v_1, \dots,v_n$ of a module {\tt M} over a ring {\tt R}
are said to be {\it linearly dependent over {\tt R}} if there exist
$c_1,\dots,c_n$ in {\tt R}, not all $0$, such that $c_1 v_1 +
\dots c_n v_n = 0$.  If such $c_i$'s exist, they form what is called a
{\it linear dependence relation over {\tt R}} for the $v_i$'s.

The package {\tt IntegerLinearDependence} provides functions
for testing whether some elements of a module over the integers are
linearly dependent over the integers, and to find the linear
dependence relations, if any.

%Original Page 386

Consider the domain of two by two square matrices with integer entries.

\spadcommand{M := SQMATRIX(2,INT) }
$$
SquareMatrix(2,Integer) 
$$
\returnType{Type: Domain}

Now create three such matrices.

\spadcommand{m1: M := squareMatrix matrix [ [1, 2], [0, -1] ] }
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
0 & -1 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{m2: M := squareMatrix matrix [ [2, 3], [1, -2] ] }
$$
\left[
\begin{array}{cc}
2 & 3 \\ 
1 & -2 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{m3: M := squareMatrix matrix [ [3, 4], [2, -3] ] }
$$
\left[
\begin{array}{cc}
3 & 4 \\ 
2 & -3 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

This tells you whether {\tt m1}, {\tt m2} and {\tt m3} are linearly
dependent over the integers.

\spadcommand{linearlyDependentOverZ? vector [m1, m2, m3] }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Since they are linearly dependent, you can ask for the dependence relation.

\spadcommand{c := linearDependenceOverZ vector [m1, m2, m3] }
$$
\left[
1, -2, 1 
\right]
$$
\returnType{Type: Union(Vector Integer,...)}

This means that the following linear combination should be {\tt 0}.

\spadcommand{c.1 * m1 + c.2 * m2 + c.3 * m3 }
$$
\left[
\begin{array}{cc}
0 & 0 \\ 
0 & 0 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

When a given set of elements are linearly dependent over {\tt R}, this
also means that at least one of them can be rewritten as a linear
combination of the others with coefficients in the quotient field of
{\tt R}.

To express a given element in terms of other elements, use the operation
\spadfunFrom{solveLinearlyOverQ}{IntegerLinearDependence}.

\spadcommand{solveLinearlyOverQ(vector [m1, m3], m2) }
$$
\left[
{\frac{1}{2}}, {\frac{1}{2}} 
\right]
$$
\returnType{Type: Union(Vector Fraction Integer,...)}

%Original Page 387

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{IntegerNumberTheoryFunctions}

The {\tt IntegerNumberTheoryFunctions} package contains a variety of
operations of interest to number theorists.  Many of these operations
deal with divisibility properties of integers.  (Recall that an
integer {\tt a} divides an integer {\tt b} if there is an integer 
{\tt c} such that {\tt b = a * c}.)

The operation \spadfunFrom{divisors}{IntegerNumberTheoryFunctions}
returns a list of the divisors of an integer.

\spadcommand{div144 := divisors(144) }
$$
\left[
1, 2, 3, 4, 6, 8, 9, {12}, {16}, {18}, {24}, 
{36}, {48}, {72}, {144} 
\right]
$$
\returnType{Type: List Integer}

You can now compute the number of divisors of {\tt 144} and the sum of
the divisors of {\tt 144} by counting and summing the elements of the
list we just created.

\spadcommand{\#(div144) }
$$
15 
$$
\returnType{Type: PositiveInteger}

\spadcommand{reduce(+,div144) }
$$
403 
$$
\returnType{Type: PositiveInteger}

Of course, you can compute the number of divisors of an integer 
{\tt n}, usually denoted {\tt d(n)}, and the sum of the divisors of an
integer {\tt n}, usually denoted {\tt $\sigma$(n)}, without ever
listing the divisors of {\tt n}.

In Axiom, you can simply call the operations
\spadfunFrom{numberOfDivisors}{IntegerNumberTheoryFunctions} and
\spadfunFrom{sumOfDivisors}{IntegerNumberTheoryFunctions}.

\spadcommand{numberOfDivisors(144)}
$$
15 
$$
\returnType{Type: PositiveInteger}

\spadcommand{sumOfDivisors(144)}
$$
403 
$$
\returnType{Type: PositiveInteger}

The key is that {\tt d(n)} and {\tt $\sigma$(n)} are ``multiplicative
functions.''  This means that when {\tt n} and {\tt m} are relatively
prime, that is, when {\tt n} and {\tt m} have no prime factor in
common, then {\tt d(nm) = d(n) d(m)} and {\tt $\sigma$(nm) =
$\sigma$(n) $\sigma$(m)}.  Note that these functions are trivial to
compute when {\tt n} is a prime power and are computed for general
{\tt n} from the prime factorization of {\tt n}.  Other examples of
multiplicative functions are {\tt $\sigma_k$(n)}, the sum of the
$k$-th powers of the divisors of {\tt n} and $\varphi(n)$, the
number of integers between 1 and {\tt n} which are prime to {\tt n}.
The corresponding Axiom operations are called
\spadfunFrom{sumOfKthPowerDivisors}{IntegerNumberTheoryFunctions} and
\spadfunFrom{eulerPhi}{IntegerNumberTheoryFunctions}.

An interesting function is {\tt $\mu$(n)}, the M\"{o}bius $\mu$
function, defined as follows: {\tt $\mu$(1) = 1}, {\tt $\mu$(n) = 0},
when {\tt n} is divisible by a square, and {\tt $\mu = {(-1)}^k$, when
{\tt n} is the product of {\tt k} distinct primes.  The corresponding
Axiom operation is \spadfunFrom{moebiusMu}{IntegerNumberTheoryFunctions}.  

This function occurs in the following theorem:

%Original Page 388

\noindent

{\bf Theorem} (M\"{o}bius Inversion Formula): \newline Let {\tt f(n)}
be a function on the positive integers and let {\tt F(n)} be defined
by 
\[F(n) = \sum_{d \mid n} f(n)\] sum of {\tt f(n)} over
{\tt d | n}} where the sum is taken over the positive divisors of 
{\tt n}.  Then the values of {\tt f(n)} can be recovered from the values of
{\tt F(n)}: 
\[f(n) = \sum_{d \mid n} \mu(n) F({\frac{n}{d}})\]
where again the sum is taken over the positive divisors of {\tt n}.

When {\tt f(n) = 1}, then {\tt F(n) = d(n)}.  Thus, if you sum $\mu(d)
\cdot d(n/d)$ over the positive divisors {\tt d} of {\tt n}, you
should always get {\tt 1}.

\spadcommand{f1(n) == reduce(+,[moebiusMu(d) * numberOfDivisors(quo(n,d)) for d in divisors(n)]) }
\returnType{Type: Void}

\spadcommand{f1(200) }
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{f1(846) }
$$
1 
$$
\returnType{Type: PositiveInteger}

Similarly, when {\tt f(n) = n}, then {\tt F(n) = $\sigma$(n)}.  Thus,
if you sum {\tt $\mu$(d) $\cdot$ $\sigma$(n/d)} over the positive
divisors {\tt d} of {\tt n}, you should always get {\tt n}.

\spadcommand{f2(n) == reduce(+,[moebiusMu(d) * sumOfDivisors(quo(n,d)) for d in divisors(n)]) }
\returnType{Type: Void}

\spadcommand{f2(200) }
$$
200 
$$
\returnType{Type: PositiveInteger}

\spadcommand{f2(846) }
$$
846 
$$
\returnType{Type: PositiveInteger}

The M\"obius inversion formula is derived from the multiplication of
formal Dirichlet series. A Dirichlet series is an infinite series of
the form:
\[\sum_{n=1}^\infty a(n)n^{-s}\]

%Original Page 389

When
\[\sum_{n=1}^\infty a(n)n^{-s} \cdot \sum_{n=1}^\infty b(n)n^{-s} =
  \sum_{n=1}^\infty c(n)n^{-s} \]
then 
\[c(n) = \sum_{d \mid n} a(d)b(n/d)\]
Recall that the Riemann $\zeta$ function is defined by
\[
\zeta(s) = \prod_p (1-p^{-s})^{-1} = \sigma_{n=1}^\infty n^{-s}
\]
where the product is taken over the set of (positive) primes. Thus,
\[
\zeta(s)^{-1} = \prod_p(1-p^{-s}) = \sigma_{n=1}^\infty\mu(n)n^{-s}
\]
Now if 
\[
F(n) = \sum_{(d \mid n)}f(d)
\]
then
\[
\sum{f(n)n^{-s}} \cdot \zeta(s) = \sum{F(n)n^{-s}}
\]
thus
\[
\zeta(s)^{-1} \cdot \sum{F(n)n^{-s}} = \sum{f(n)n^{-s}}
\]
and
\[
f(n) = \sum_{(d \mid n)} \mu(d)F(n/d)
\]

The Fibonacci numbers are defined by $F(1) = F(2) = 1$ and
$F(n) = F(n-1) + F(n-2)$ for $n = 3,4,\ldots$.

The operation \spadfunFrom{fibonacci}{IntegerNumberTheoryFunctions}
computes the $n$-th Fibonacci number.

\spadcommand{fibonacci(25)}
$$
75025 
$$
\returnType{Type: PositiveInteger}

\spadcommand{[fibonacci(n) for n in 1..15]}
$$
\left[
1, 1, 2, 3, 5, 8, {13}, {21}, {34}, {55}, {89}, 
{144}, {233}, {377}, {610} 
\right]
$$
\returnType{Type: List Integer}

Fibonacci numbers can also be expressed as sums of binomial coefficients.

\spadcommand{fib(n) == reduce(+,[binomial(n-1-k,k) for k in 0..quo(n-1,2)]) }
\returnType{Type: Void}

\spadcommand{fib(25) }
$$
75025 
$$
\returnType{Type: PositiveInteger}

\spadcommand{[fib(n) for n in 1..15] }
$$
\left[
1, 1, 2, 3, 5, 8, {13}, {21}, {34}, {55}, {89}, 
{144}, {233}, {377}, {610} 
\right]
$$
\returnType{Type: List Integer}

%Original Page 390

Quadratic symbols can be computed with the operations
\spadfunFrom{legendre}{IntegerNumberTheoryFunctions} and
\spadfunFrom{jacobi}{IntegerNumberTheoryFunctions}.  The Legendre
symbol $\left({\frac{a}{p}}\right)$ is defined for integers $a$ and
$p$ with $p$ an odd prime number.  By definition, 
$\left({\frac{a}{p}}\right)$ = +1, when $a$ is a square $({\rm mod\ }p)$,
$\left({\frac{a}{p}}\right)$ = -1, when $a$ is not a square $({\rm mod\ }p)$,
and $\left({\frac{a}{p}}\right)$ = 0, when $a$ is divisible by $p$.

You compute $\left({\frac{a}{p}}\right)$ via the command {\tt legendre(a,p)}.

\spadcommand{legendre(3,5)}
$$
-1 
$$
\returnType{Type: Integer}

\spadcommand{legendre(23,691)}
$$
-1 
$$
\returnType{Type: Integer}

The Jacobi symbol $\left({\frac{a}{n}}\right)$ is the usual extension of
the Legendre symbol, where {\tt n} is an arbitrary integer.  The most
important property of the Jacobi symbol is the following: if {\tt K}
is a quadratic field with discriminant {\tt d} and quadratic character
$\chi$, then $\chi(n) = (d/n)$.  Thus, you can use the Jacobi symbol
to compute, say, the class numbers of imaginary quadratic fields from
a standard class number formula.

This function computes the class number of the imaginary quadratic
field with discriminant {\tt d}.

\spadcommand{h(d) == quo(reduce(+, [jacobi(d,k) for k in 1..quo(-d, 2)]), 2 - jacobi(d,2)) }
\returnType{Type: Void}

\spadcommand{h(-163) }   
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{h(-499) }   
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{h(-1832) }
$$
26 
$$
\returnType{Type: PositiveInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Kernel}

A {\it kernel} is a symbolic function application (such as {\tt sin(x+ y)}) 
or a symbol (such as {\tt x}).  More precisely, a non-symbol
kernel over a set {\it S} is an operator applied to a given list of
arguments from {\it S}.  The operator has type {\tt BasicOperator}
(see \domainref{BasicOperator}
and the kernel object is usually part of an expression object (see 
\domainref{Expression}.

Kernels are created implicitly for you when you create expressions.

\spadcommand{x :: Expression Integer}
$$
x 
$$
\returnType{Type: Expression Integer}

You can directly create a ``symbol'' kernel by using the
\spadfunFrom{kernel}{Kernel} operation.

\spadcommand{kernel x}
$$
x 
$$
\returnType{Type: Kernel Expression Integer}

This expression has two different kernels.

\spadcommand{sin(x) + cos(x) }
$$
{\sin 
\left(
{x} 
\right)}+{\cos
\left(
{x} 
\right)}
$$
\returnType{Type: Expression Integer}

The operator \spadfunFrom{kernels}{Expression} returns a list of the
kernels in an object of type {\tt Expression}.

\spadcommand{kernels \% }
$$
\left[
{\sin 
\left(
{x} 
\right)},
{\cos 
\left(
{x} 
\right)}
\right]
$$
\returnType{Type: List Kernel Expression Integer}

This expression also has two different kernels.

\spadcommand{sin(x)**2 + sin(x) + cos(x) }
$$
{{\sin 
\left(
{x} 
\right)}
\sp 2}+{\sin 
\left(
{x} 
\right)}+{\cos
\left(
{x} 
\right)}
$$
\returnType{Type: Expression Integer}

The {\tt sin(x)} kernel is used twice.

\spadcommand{kernels \% }
$$
\left[
{\sin 
\left(
{x} 
\right)},
{\cos 
\left(
{x} 
\right)}
\right]
$$
\returnType{Type: List Kernel Expression Integer}

An expression need not contain any kernels.

\spadcommand{kernels(1 :: Expression Integer)}
$$
\left[\ 
\right]
$$
\returnType{Type: List Kernel Expression Integer}

If one or more kernels are present, one of them is
designated the {\it main} kernel.

\spadcommand{mainKernel(cos(x) + tan(x))}
$$
\tan 
\left(
{x} 
\right)
$$
\returnType{Type: Union(Kernel Expression Integer,...)}

Kernels can be nested. Use \spadfunFrom{height}{Kernel} to determine
the nesting depth.

\spadcommand{height kernel x}
$$
1 
$$
\returnType{Type: PositiveInteger}

This has height 2 because the {\tt x} has height 1 and then we apply
an operator to that.

\spadcommand{height mainKernel(sin x)}
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{height mainKernel(sin cos x)}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{height mainKernel(sin cos (tan x + sin x))}
$$
4 
$$
\returnType{Type: PositiveInteger}

Use the \spadfunFrom{operator}{Kernel} operation to extract the
operator component of the kernel.  The operator has type {\tt BasicOperator}.

\spadcommand{operator mainKernel(sin cos (tan x + sin x))}
$$
\sin 
$$
\returnType{Type: BasicOperator}

Use the \spadfunFrom{name}{Kernel} operation to extract the name of
the operator component of the kernel.  The name has type {\tt Symbol}.
This is really just a shortcut for a two-step process of extracting
the operator and then calling \spadfunFrom{name}{BasicOperator} on
the operator.

\spadcommand{name mainKernel(sin cos (tan x + sin x))}
$$
\sin 
$$
\returnType{Type: Symbol}

Axiom knows about functions such as {\tt sin}, {\tt cos} and so on and
can make kernels and then expressions using them.  To create a kernel
and expression using an arbitrary operator, use
\spadfunFrom{operator}{BasicOperator}.

Now {\tt f} can be used to create symbolic function applications.

\spadcommand{f := operator 'f }
$$
f 
$$
\returnType{Type: BasicOperator}

\spadcommand{e := f(x, y, 10) }
$$
f 
\left(
{x, y, {10}} 
\right)
$$
\returnType{Type: Expression Integer}

Use the \spadfunFrom{is?}{Kernel} operation to learn if the
operator component of a kernel is equal to a given operator.

\spadcommand{is?(e, f) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

You can also use a symbol or a string as the second argument to
\spadfunFrom{is?}{Kernel}.

\spadcommand{is?(e, 'f) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Use the \spadfunFrom{argument}{Kernel} operation to get a list containing
the argument component of a kernel.

\spadcommand{argument mainKernel e }
$$
\left[
x, y, {10} 
\right]
$$
\returnType{Type: List Expression Integer}

Conceptually, an object of type {\tt Expression} can be thought of a
quotient of multivariate polynomials, where the ``variables'' are
kernels.  The arguments of the kernels are again expressions and so
the structure recurses.  See \domainref{Expression} for examples of
using kernels to take apart expression objects.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{KeyedAccessFile}

The domain {\tt KeyedAccessFile(S)} provides files which can be used
as associative tables.  Data values are stored in these files and can
be retrieved according to their keys.  The keys must be strings so
this type behaves very much like the {\tt StringTable(S)} domain.  The
difference is that keyed access files reside in secondary storage
while string tables are kept in memory.  For more information on
table-oriented operations, see the description of {\tt Table}.

%Original Page 391

Before a keyed access file can be used, it must first be opened.
A new file can be created by opening it for output.

\spadcommand{ey: KeyedAccessFile(Integer) := open("/tmp/editor.year", "output")  }
$$
\mbox{\tt "/tmp/editor.year"} 
$$
\returnType{Type: KeyedAccessFile Integer}

Just as for vectors, tables or lists, values are saved in a keyed access file
by setting elements.

\spadcommand{ey."Char"     := 1986 }
$$
1986 
$$
\returnType{Type: PositiveInteger}

\spadcommand{ey."Caviness" := 1985 }
$$
1985 
$$
\returnType{Type: PositiveInteger}

\spadcommand{ey."Fitch"    := 1984 }
$$
1984 
$$
\returnType{Type: PositiveInteger}

Values are retrieved using application, in any of its syntactic forms.

\spadcommand{ey."Char"}
$$
1986 
$$
\returnType{Type: PositiveInteger}

\spadcommand{ey("Char")}
$$
1986 
$$
\returnType{Type: PositiveInteger}

\spadcommand{ey "Char"}
$$
1986 
$$
\returnType{Type: PositiveInteger}

Attempting to retrieve a non-existent element in this way causes an error.
If it is not known whether a key exists, you should use the
\spadfunFrom{search}{KeyedAccessFile} operation.

\spadcommand{search("Char", ey)   }
$$
1986 
$$
\returnType{Type: Union(Integer,...)}

\spadcommand{search("Smith", ey)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

%Original Page 392

When an entry is no longer needed, it can be removed from the file.

\spadcommand{remove!("Char", ey)  }
$$
1986 
$$
\returnType{Type: Union(Integer,...)}

The \spadfunFrom{keys}{KeyedAccessFile} operation returns a list of all the
keys for a given file.

\spadcommand{keys ey  }
$$
\left[
\mbox{\tt "Fitch"} , \mbox{\tt "Caviness"} 
\right]
$$
\returnType{Type: List String}

The \spadfunFrom{\#}{KeyedAccessFile} operation gives the
number of entries.

\spadcommand{\#ey}
$$
2 
$$
\returnType{Type: PositiveInteger}

The table view of keyed access files provides safe operations.  That
is, if the Axiom program is terminated between file operations, the
file is left in a consistent, current state.  This means, however,
that the operations are somewhat costly.  For example, after each
update the file is closed.

Here we add several more items to the file, then check its contents.

\spadcommand{KE := Record(key: String, entry: Integer)  }
$$
\mbox{\rm Record(key: String,entry: Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{reopen!(ey, "output")  }
$$
\mbox{\tt "/tmp/editor.year"} 
$$
\returnType{Type: KeyedAccessFile Integer}

If many items are to be added to a file at the same time, then
it is more efficient to use the \spadfunFrom{write}{KeyedAccessFile} operation.

\spadcommand{write!(ey, ["van Hulzen", 1983]\$KE)  }
$$
\left[
{key= \mbox{\tt "van Hulzen"} }, {entry={1983}} 
\right]
$$
\returnType{Type: Record(key: String,entry: Integer)}

\spadcommand{write!(ey, ["Calmet", 1982]\$KE)}
$$
\left[
{key= \mbox{\tt "Calmet"} }, {entry={1982}} 
\right]
$$
\returnType{Type: Record(key: String,entry: Integer)}

\spadcommand{write!(ey, ["Wang", 1981]\$KE)}
$$
\left[
{key= \mbox{\tt "Wang"} }, {entry={1981}} 
\right]
$$
\returnType{Type: Record(key: String,entry: Integer)}

\spadcommand{close! ey}
$$
\mbox{\tt "/tmp/editor.year"} 
$$
\returnType{Type: KeyedAccessFile Integer}

%Original Page 393

The \spadfunFrom{read}{KeyedAccessFile} operation is also available
from the file view, but it returns elements in a random order.  It is
generally clearer and more efficient to use the
\spadfunFrom{keys}{KeyedAccessFile} operation and to extract elements
by key.

\spadcommand{keys ey}
$$
\left[
\mbox{\tt "Wang"} , \mbox{\tt "Calmet"} , \mbox{\tt "van Hulzen"} , 
\mbox{\tt "Fitch"} , \mbox{\tt "Caviness"} 
\right]
$$
\returnType{Type: List String}

\spadcommand{members ey}
$$
\left[
{1981}, {1982}, {1983}, {1984}, {1985} 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{)system rm -r /tmp/editor.year}

For more information on related topics, see 
\domainref{File}, \domainref{TextFile}, and \domainref{Library}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LexTriangularPackage}

The {\tt LexTriangularPackage} package constructor provides an
implementation of the {\em lexTriangular} algorithm (D. Lazard
``Solving Zero-dimensional Algebraic Systems'', J. of Symbol. Comput.,
1992).  This algorithm decomposes a zero-dimensional variety into
zero-sets of regular triangular sets.  Thus the input system must have
a finite number of complex solutions.  Moreover, this system needs to
be a lexicographical Groebner basis.

This package takes two arguments: the coefficient-ring {\bf R} of the
polynomials, which must be a {\tt GcdDomain} and their set of
variables given by {\bf ls} a {\tt List Symbol}.  The type of the
input polynomials must be\\ 
{\tt NewSparseMultivariatePolynomial(R,V)}
where {\bf V} is {\tt OrderedVariableList(ls)}.  The abbreviation for
{\tt LexTriangularPackage} is {\tt LEXTRIPK}.  The main operations are
\spadfunFrom{lexTriangular}{LexTriangularPackage} and
\spadfunFrom{squareFreeLexTriangular}{LexTriangularPackage}.  The
later provide decompositions by means of square-free regular
triangular sets, built with the {\tt SREGSET} constructor, whereas the
former uses the {\tt REGSET} constructor.  Note that these
constructors also implement another algorithm for solving algebraic
systems by means of regular triangular sets; in that case no
computations of Groebner bases are needed and the input system may
have any dimension (i.e. it may have an infinite number of solutions).

The implementation of the {\em lexTriangular} algorithm provided in
the {\tt LexTriangularPackage} constructor differs from that reported
in ``Computations of gcd over algebraic towers of simple extensions'' by
M. Moreno Maza and R. Rioboo (in proceedings of AAECC11, Paris, 1995).
Indeed, the \spadfunFrom{squareFreeLexTriangular}{LexTriangularPackage} 
operation removes all multiplicities of the solutions (i.e. the computed
solutions are pairwise different) and the
\spadfunFrom{lexTriangular}{LexTriangularPackage} operation may keep
some multiplicities; this later operation runs generally faster than
the former.

The interest of the {\em lexTriangular} algorithm is due to the
following experimental remark.  For some examples, a triangular
decomposition of a zero-dimensional variety can be computed faster via
a lexicographical Groebner basis computation than by using a direct
method (like that of {\tt SREGSET} and {\tt REGSET}).  This happens
typically when the total degree of the system relies essentially on
its smallest variable (like in the {\em Katsura} systems).  When this
is not the case, the direct method may give better timings (like in
the {\em Rose} system).

Of course, the direct method can also be applied to a lexicographical
Groebner basis.  However, the {\em lexTriangular} algorithm takes
advantage of the structure of this basis and avoids many unnecessary
computations which are performed by the direct method.

For this purpose of solving algebraic systems with a finite number of
solutions, see also the {\tt ZeroDimensionalSolvePackage}.  It allows
to use both strategies (the lexTriangular algorithm and the direct
method) for computing either the complex or real roots of a system.

Note that the way of understanding triangular decompositions is
detailed in the example of the {\tt RegularTriangularSet} constructor.

Since the {\tt LEXTRIPK} package constructor is limited to
zero-dimensional systems, it provides a
\spadfunFrom{zeroDimensional?}{LexTriangularPackage} operation to
check whether this requirement holds.  There is also a
\spadfunFrom{groebner}{LexTriangularPackage} operation to compute the
lexicographical Groebner basis of a set of polynomials with type {\tt
NewSparseMultivariatePolynomial(R,V)}.  The elimination ordering is
that given by {\bf ls} (the greatest variable being the first element
of {\bf ls}).  This basis is computed by the {\em FLGM} algorithm
(Faugere et al. ``Efficient Computation of Zero-Dimensional Groebner
Bases by Change of Ordering'' , J. of Symbol. Comput., 1993)
implemented in the {\tt LinGroebnerPackage} package constructor.
Once a lexicographical Groebner basis is computed,
then one can call the operations 
\spadfunFrom{lexTriangular}{LexTriangularPackage}
and \spadfunFrom{squareFreeLexTriangular}{LexTriangularPackage}.
Note that these operations admit an optional argument
to produce normalized triangular sets.
There is also a \spadfunFrom{zeroSetSplit}{LexTriangularPackage} operation
which does all the job from the input system;
an error is produced if this system is not zero-dimensional.

Let us illustrate the facilities of the {\tt LEXTRIPK} constructor
by a famous example, the {\em cyclic-6 root} system.

Define the coefficient ring.

\spadcommand{R := Integer }
$$
Integer 
$$
\returnType{Type: Domain}

Define the list of variables,

\spadcommand{ls : List Symbol := [a,b,c,d,e,f] }
$$
\left[
a, b, c, d, e, f 
\right]
$$
\returnType{Type: List Symbol}

and make it an ordered set.

\spadcommand{V := OVAR(ls)  }
$$
\mbox{\rm OrderedVariableList [a,b,c,d,e,f]} 
$$
\returnType{Type: Domain}

Define the polynomial ring.

\spadcommand{P := NSMP(R, V)}
$$
\mbox{\rm NewSparseMultivariatePolynomial(Integer,OrderedVariableList 
[a,b,c,d,e,f])} 
$$
\returnType{Type: Domain}

Define the polynomials.

\spadcommand{p1: P :=  a*b*c*d*e*f - 1  }
$$
{f \  e \  d \  c \  b \  a} -1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

\spadcommand{p2: P := a*b*c*d*e +a*b*c*d*f +a*b*c*e*f +a*b*d*e*f +a*c*d*e*f +b*c*d*e*f   }
$$
{{\left( {{\left( {{\left( {{\left( e+f 
\right)}
\  d}+{f \  e} 
\right)}
\  c}+{f \  e \  d} 
\right)}
\  b}+{f \  e \  d \  c} 
\right)}
\  a}+{f \  e \  d \  c \  b} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

\spadcommand{p3: P :=  a*b*c*d + a*b*c*f + a*b*e*f + a*d*e*f + b*c*d*e + c*d*e*f  }
$$
{{\left( {{\left( {{\left( d+f 
\right)}
\  c}+{f \  e} 
\right)}
\  b}+{f \  e \  d} 
\right)}
\  a}+{e \  d \  c \  b}+{f \  e \  d \  c} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

\spadcommand{p4: P := a*b*c + a*b*f + a*e*f + b*c*d + c*d*e + d*e*f   }
$$
{{\left( {{\left( c+f 
\right)}
\  b}+{f \  e} 
\right)}
\  a}+{d \  c \  b}+{e \  d \  c}+{f \  e \  d} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

\spadcommand{p5: P := a*b + a*f + b*c + c*d + d*e + e*f  }
$$
{{\left( b+f 
\right)}
\  a}+{c \  b}+{d \  c}+{e \  d}+{f \  e} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

\spadcommand{p6: P := a + b + c + d + e + f   }
$$
a+b+c+d+e+f 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

\spadcommand{lp := [p1, p2, p3, p4, p5, p6]}
$$
\begin{array}{@{}l}
\left[
{{f \  e \  d \  c \  b \  a} -1}, 
\right.
\\
\\
\displaystyle
{{{\left( 
{{\left( 
{{\left( 
{{\left( e+f \right)}
\  d}+{f \  e} 
\right)}
\  c}+{f \  e \  d} 
\right)}
\  b}+{f \  e \  d \  c} 
\right)}
\  a}+{f \  e \  d \  c \  b}}, 
\\
\\
\displaystyle
{{{\left( 
{{\left( 
{{\left( d+f 
\right)}
\  c}+{f \  e} 
\right)}
\  b}+{f \  e \  d} 
\right)}
\  a}+{e \  d \  c \  b}+{f \  e \  d \  c}}, 
\\
\\
\displaystyle
{{{\left( 
{{\left( c+f 
\right)}
\  b}+{f \  e} 
\right)}
\  a}+{d \  c \  b}+{e \  d \  c}+{f \  e \  d}},
\\
\\
\displaystyle
{{{\left( b+f 
\right)}
\  a}+{c \  b}+{d \  c}+{e \  d}+{f \  e}}, 
\\
\\
\displaystyle
\left.
{a+b+c+d+e+f} 
\right]
\end{array}
$$
\returnType{Type: List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

Now call {\tt LEXTRIPK} .

\spadcommand{lextripack :=  LEXTRIPK(R,ls)}
$$
LexTriangularPackage(Integer,[a,b,c,d,e,f]) 
$$
\returnType{Type: Domain}

Compute the lexicographical Groebner basis of the system.
This may take between 5 minutes and one hour, depending on your machine.

\spadcommand{lg := groebner(lp)\$lextripack}

$$
\left[
{a+b+c+d+e+f}, 
\right.
$$
$$
\begin{array}{@{}l}
{{3968379498283200} \  {b \sp 2}}+
{{15873517993132800} \  f \  b}+
\\
\displaystyle
{{3968379498283200} \  {d \sp 2}}+
{{15873517993132800} \  f \  d}+
\\
\displaystyle
{{3968379498283200} \  {f \sp 3} \  {e \sp 5}} -
{{15873517993132800} \  {f \sp 4} \  {e \sp 4}}+
\\
\displaystyle
{{23810276989699200} \  {f \sp 5} \  {e \sp 3}}+
\left( 
{{206355733910726400} \  {f \sp 6}}+
\right.
\\
\displaystyle
\left.
{230166010900425600} 
\right)\  {e \sp 2}+
\left( 
-{{729705987316687} \  {f \sp {43}}}+
\right.
\\
\displaystyle
{{1863667496867205421} \  {f \sp {37}}}+
{{291674853771731104461} \  {f \sp {31}}}+
\\
\displaystyle
{{365285994691106921745} \  {f \sp {25}}}+
{{549961185828911895} \  {f \sp {19}}} -
\\
\displaystyle
{{365048404038768439269} \  {f \sp {13}}} -
{{292382820431504027669} \  {f \sp 7}} -
\\
\displaystyle
\left.
{{2271898467631865497} \  f} 
\right)\  e -
{{3988812642545399} \  {f \sp {44}}}+
\\
\displaystyle
{{10187423878429609997} \  {f \sp {38}}}+
{{1594377523424314053637} \  {f \sp {32}}}+
\\
\displaystyle
{{1994739308439916238065} \  {f \sp {26}}}+
{{1596840088052642815} \  {f \sp {20}}} -
\\
\displaystyle
{{1993494118301162145413} \  {f \sp {14}}} -
{{1596049742289689815053} \  {f \sp 8}} -
\\
\displaystyle
{{11488171330159667449} \  {f \sp 2}}, \hbox{\hskip 8.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{23810276989699200} \  c} -
{{23810276989699200} \  f} 
\right)\  b+
\\
\displaystyle
{{23810276989699200} \  {c \sp 2}}+
{{71430830969097600} \  f \  c} -
\\
\displaystyle
{{23810276989699200} \  {d \sp 2}} -
{{95241107958796800} \  f \  d} -
\\
\displaystyle
{{55557312975964800} \  {f \sp 3} \  {e \sp 5}}+
{{174608697924460800} \  {f \sp 4} \  {e \sp 4}} -
\\
\displaystyle
{{174608697924460800} \  {f \sp 5} \  {e \sp 3}}+
\left( 
-{{2428648252949318400} \  {f \sp 6}} -
\right.
\\
\displaystyle
\left.
{2611193709870345600} 
\right)\  {e \sp 2}+
\left( 
{{8305444561289527} \  {f \sp {43}}} -
\right.
\\
\displaystyle
{{21212087151945459641} \  {f \sp {37}}} -
{{3319815883093451385381} \  {f \sp {31}}} -
\\
\displaystyle
{{4157691646261657136445} \  {f \sp {25}}} -
{{6072721607510764095} \  {f \sp {19}}}+
\\
\displaystyle
{{4154986709036460221649} \  {f \sp {13}}}+
{{3327761311138587096749} \  {f \sp 7}}+
\\
\displaystyle
\left.
{{25885340608290841637} \  f} 
\right)\  e+
{{45815897629010329} \  {f \sp {44}}} -
\\
\displaystyle
{{117013765582151891207} \  {f \sp {38}}} -
{{18313166848970865074187} \  {f \sp {32}}}-
\\
\displaystyle
{{22909971239649297438915} \  {f \sp {26}}} -
{{16133250761305157265} \  {f \sp {20}}}+
\\
\displaystyle
{{22897305857636178256623} \  {f \sp {14}}}+
{{18329944781867242497923} \  {f \sp 8}}+
\\
\displaystyle
{{130258531002020420699} \  {f \sp 2}}, \hbox{\hskip 8.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{7936758996566400} \  d} -
{{7936758996566400} \  f} 
\right)\  b -
\\
\displaystyle
{{7936758996566400} \  f \  d} -
{{7936758996566400} \  {f \sp 3} \  {e \sp 5}}+
\\
\displaystyle
{{23810276989699200} \  {f \sp 4} \  {e \sp 4}} -
{{23810276989699200} \  {f \sp 5} \  {e \sp 3}}+
\\
\displaystyle
\left( 
-{{337312257354072000} \  {f \sp 6}} -
{369059293340337600} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( 
{{1176345388640471} \  {f \sp {43}}} -
{{3004383582891473073} \  {f \sp {37}}} -
\right.
\\
\displaystyle
{{470203502707246105653} \  {f \sp {31}}} -
{{588858183402644348085} \  {f \sp {25}}} -
\\
\displaystyle
{{856939308623513535} \  {f \sp {19}}}+
{{588472674242340526377} \  {f \sp {13}}}+
\\
\displaystyle
\left.
{{471313241958371103517} \  {f \sp 7}}+
{{3659742549078552381} \  f} 
\right)\  e+
\\
\displaystyle
{{6423170513956901} \  {f \sp {44}}} -
{{16404772137036480803} \  {f \sp {38}}} -
\\
\displaystyle
{{2567419165227528774463} \  {f \sp {32}}} -
{{3211938090825682172335} \  {f \sp {26}}} -
\\
\displaystyle
{{2330490332697587485} \  {f \sp {20}}}+
{{3210100109444754864587} \  {f \sp {14}}}+
\\
\displaystyle
{{2569858315395162617847} \  {f \sp 8}}+
{{18326089487427735751} \  {f \sp 2}}, \hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{11905138494849600} \  e} -
{{11905138494849600} \  f} 
\right)\  b -
\\
\displaystyle
{{3968379498283200} \  {f \sp 3} \  {e \sp 5}}+
{{15873517993132800} \  {f \sp 4} \  {e \sp 4}} -
\\
\displaystyle
{{27778656487982400} \  {f \sp 5} \  {e \sp 3}}+
\left( 
-{{208339923659868000} \  {f \sp 6}} -
\right.
\\
\displaystyle
\left.
{240086959646133600} 
\right)\  {e \sp 2}+
\left( 
{{786029984751110} \  {f \sp {43}}} -
\right.
\\
\displaystyle
{{2007519008182245250} \  {f \sp {37}}} -
{{314188062908073807090} \  {f \sp {31}}} -
\\
\displaystyle
{{393423667537929575250} \  {f \sp {25}}} -
{{550329120654394950} \  {f \sp {19}}}+
\\
\displaystyle
{{393196408728889612770} \  {f \sp {13}}}+
{{314892372799176495730} \  {f \sp 7}}+
\\
\displaystyle
\left.
{{2409386515146668530} \  f} 
\right)\  e+
{{4177638546747827} \  {f \sp {44}}} -
\\
\displaystyle
{{10669685294602576381} \  {f \sp {38}}} -
{{1669852980419949524601} \  {f \sp {32}}} -
\\
\displaystyle
{{2089077057287904170745} \  {f \sp {26}}} -
{{1569899763580278795} \  {f \sp {20}}}+
\\
\displaystyle
{{2087864026859015573349} \  {f \sp {14}}}+
{{1671496085945199577969} \  {f \sp 8}}+
\\
\displaystyle
{{11940257226216280177} \  {f \sp 2}}, \hbox{\hskip 8.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{11905138494849600} \  {f \sp 6}} -{11905138494849600} 
\right)\  b -
\\
\displaystyle
{{15873517993132800} \  {f \sp 2} \  {e \sp 5}}+
{{39683794982832000} \  {f \sp 3} \  {e \sp 4}} -
\\
\displaystyle
{{39683794982832000} \  {f \sp 4} \  {e \sp 3}}+
\left( -{{686529653202993600} \  {f \sp {11}}} -
\right.
\\
\displaystyle
\left.
{{607162063237329600} \  {f \sp 5}} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( {{65144531306704} \  {f \sp {42}}} -
{{166381280901088652} \  {f \sp {36}}} -
\right.
\\
\displaystyle
{{26033434502470283472} \  {f \sp {30}}} -
{{31696259583860650140} \  {f \sp {24}}}+
\\
\displaystyle
{{971492093167581360} \  {f \sp {18}}}+
{{32220085033691389548} \  {f \sp {12}}}+
\\
\displaystyle
\left.
{{25526177666070529808} \  {f \sp 6}}+
{138603268355749244} 
\right)\  e+
\\
\displaystyle
{{167620036074811} \  {f \sp {43}}} -
{{428102417974791473} \  {f \sp {37}}} -
\\
\displaystyle
{{66997243801231679313} \  {f \sp {31}}} -
{{83426716722148750485} \  {f \sp {25}}}+
\\
\displaystyle
{{203673895369980765} \  {f \sp {19}}}+
{{83523056326010432457} \  {f \sp {13}}}+
\\
\displaystyle
{{66995789640238066937} \  {f \sp 7}}+
{{478592855549587901} \  f}, \hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
{{801692827936} \  {c \sp 3}}+
{{2405078483808} \  f \  {c \sp 2}} -
\\
\displaystyle
{{2405078483808} \  {f \sp 2} \  c} -
{{13752945467} \  {f \sp {45}}}+
\\
\displaystyle
{{35125117815561} \  {f \sp {39}}}+
{{5496946957826433} \  {f \sp {33}}}+
\\
\displaystyle
{{6834659447749117} \  {f \sp {27}}} -
{{44484880462461} \  {f \sp {21}}} -
\\
\displaystyle
{{6873406230093057} \  {f \sp {15}}} -
{{5450844938762633} \  {f \sp 9}}+
\\
\displaystyle
{{1216586044571} \  {f \sp 3}},\hbox{\hskip 9.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( {{23810276989699200} \  d} -
{{23810276989699200} \  f} 
\right)\  c+
\\
\displaystyle
{{23810276989699200} \  {d \sp 2}}+
{{71430830969097600} \  f \  d}+
\\
\displaystyle
{{7936758996566400} \  {f \sp 3} \  {e \sp 5}} -
{{31747035986265600} \  {f \sp 4} \  {e \sp 4}}+
\\
\displaystyle
{{31747035986265600} \  {f \sp 5} \  {e \sp 3}}+
\left( {{404774708824886400} \  {f \sp 6}}+
\right.
\\
\displaystyle
\left.
{396837949828320000} 
\right)\  {e \sp 2}+
\left( 
-{{1247372229446701} \  {f \sp {43}}}+
\right.
\\
\displaystyle
{{3185785654596621203} \  {f \sp {37}}}+
{{498594866849974751463} \  {f \sp {31}}}+
\\
\displaystyle
{{624542545845791047935} \  {f \sp {25}}}+
{{931085755769682885} \  {f \sp {19}}} -
\\
\displaystyle
{{624150663582417063387} \  {f \sp {13}}} -
{{499881859388360475647} \  {f \sp 7}} -
\\
\displaystyle
\left.
{{3926885313819527351} \  f} 
\right)\  e -
{{7026011547118141} \  {f \sp {44}}}+
\\
\displaystyle
{{17944427051950691243} \  {f \sp {38}}}+
{{2808383522593986603543} \  {f \sp {32}}}+
\\
\displaystyle
{{3513624142354807530135} \  {f \sp {26}}}+
{{2860757006705537685} \  {f \sp {20}}} -
\\
\displaystyle
{{3511356735642190737267} \  {f \sp {14}}} -
{{2811332494697103819887} \  {f \sp 8}} -
\\
\displaystyle
{{20315011631522847311} \  {f \sp 2}}, \hbox{\hskip 8.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{7936758996566400} \  e} -{{7936758996566400} \  f} 
\right)\  c+
\\
\displaystyle
\left( 
-{{4418748183673} \  {f \sp {43}}}+
\right.
\\
\displaystyle
{{11285568707456559} \  {f \sp {37}}}+
{{1765998617294451019} \  {f \sp {31}}}+
\\
\displaystyle
{{2173749283622606155} \  {f \sp {25}}} -
{{55788292195402895} \  {f \sp {19}}} -
\\
\displaystyle
{{2215291421788292951} \  {f \sp {13}}} -
{{1718142665347430851} \  {f \sp 7}}+
\\
\displaystyle
\left.
{{30256569458230237} \  f} 
\right)\  e+
{{4418748183673} \  {f \sp {44}}} -
\\
\displaystyle
{{11285568707456559} \  {f \sp {38}}} -
{{1765998617294451019} \  {f \sp {32}}} -
\\
\displaystyle
{{2173749283622606155} \  {f \sp {26}}}+
{{55788292195402895} \  {f \sp {20}}}+
\\
\displaystyle
{{2215291421788292951} \  {f \sp {14}}}+
{{1718142665347430851} \  {f \sp 8}} -
\\
\displaystyle
{{30256569458230237} \  {f \sp 2}}, \hbox{\hskip 9.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{72152354514240} \  {f \sp 6}} -
{72152354514240} 
\right)\  c+
\\
\displaystyle
{{40950859449} \  {f \sp {43}}} -
{{104588980990367} \  {f \sp {37}}} -
\\
\displaystyle
{{16367227395575307} \  {f \sp {31}}} -
{{20268523416527355} \  {f \sp {25}}}+
\\
\displaystyle
{{442205002259535} \  {f \sp {19}}}+
{{20576059935789063} \  {f \sp {13}}}+
\\
\displaystyle
{{15997133796970563} \  {f \sp 7}} -
{{275099892785581} \  f}, \hbox{\hskip 5.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
{{1984189749141600} \  {d \sp 3}}+
{{5952569247424800} \  f \  {d \sp 2}} -
\\
\displaystyle
{{5952569247424800} \  {f \sp 2} \  d} -
{{3968379498283200} \  {f \sp 4} \  {e \sp 5}}+
\\
\displaystyle
{{15873517993132800} \  {f \sp 5} \  {e \sp 4}}+
{{17857707742274400} \  {e \sp 3}}+
\\
\displaystyle
\left( 
-{{148814231185620000} \  {f \sp 7}} -
{{162703559429611200} \  f} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( 
-{{390000914678878} \  {f \sp {44}}}+
{{996062704593756434} \  {f \sp {38}}}+
\right.
\\
\displaystyle
{{155886323972034823914} \  {f \sp {32}}}+
{{194745956143985421330} \  {f \sp {26}}}+
\\
\displaystyle
{{6205077595574430} \  {f \sp {20}}} -
{{194596512653299068786} \  {f \sp {14}}} -
\\
\displaystyle
\left.
{{155796897940756922666} \  {f \sp 8}} -
{{1036375759077320978} \  {f \sp 2}} 
\right)\  e -
\\
\displaystyle
{{374998630035991} \  {f \sp {45}}}+
{{957747106595453993} \  {f \sp {39}}}+
\\
\displaystyle
{{149889155566764891693} \  {f \sp {33}}}+
{{187154171443494641685} \  {f \sp {27}}} -
\\
\displaystyle
{{127129015426348065} \  {f \sp {21}}} -
{{187241533243115040417} \  {f \sp {15}}} -
\\
\displaystyle
{{149719983567976534037} \  {f \sp 9}} -
{{836654081239648061} \  {f \sp 3}}, \hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{5952569247424800} \  e} -
{{5952569247424800} \  f} 
\right)\  d -
\\
\displaystyle
{{3968379498283200} \  {f \sp 3} \  {e \sp 5}}+
{{9920948745708000} \  {f \sp 4} \  {e \sp 4}} -
\\
\displaystyle
{{3968379498283200} \  {f \sp 5} \  {e \sp 3}}+
\left( 
-{{148814231185620000} \  {f \sp 6}} -
\right.
\\
\displaystyle
\left.
{150798420934761600} 
\right)\  {e \sp 2}+
\left( 
{{492558110242553} \  {f \sp {43}}} -
\right.
\\
\displaystyle
{{1257992359608074599} \  {f \sp {37}}} -
{{196883094539368513959} \  {f \sp {31}}} -
\\
\displaystyle
{{246562115745735428055} \  {f \sp {25}}} -
{{325698701993885505} \  {f \sp {19}}}+
\\
\displaystyle
{{246417769883651808111} \  {f \sp {13}}}+
{{197327352068200652911} \  {f \sp 7}}+
\\
\displaystyle
\left.
{{1523373796389332143} \  f} 
\right)\  e+
{{2679481081803026} \  {f \sp {44}}} -
\\
\displaystyle
{{6843392695421906608} \  {f \sp {38}}} -
{{1071020459642646913578} \  {f \sp {32}}} -
\\
\displaystyle
{{1339789169692041240060} \  {f \sp {26}}} -
{{852746750910750210} \  {f \sp {20}}}+
\\
\displaystyle
{{1339105101971878401312} \  {f \sp {14}}}+
{{1071900289758712984762} \  {f \sp 8}}+
\\
\displaystyle
{{7555239072072727756} \  {f \sp 2}}, \hbox{\hskip 8.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{11905138494849600} \  {f \sp 6}} -
{11905138494849600} 
\right)\  d -
\\
\displaystyle
{{7936758996566400} \  {f \sp 2} \  {e \sp 5}}+
{{31747035986265600} \  {f \sp 3} \  {e \sp 4}} -
\\
\displaystyle
{{31747035986265600} \  {f \sp 4} \  {e \sp 3}}+
\\
\displaystyle
\left( -{{420648226818019200} \  {f \sp {11}}} -
{{404774708824886400} \  {f \sp 5}} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( 
{{15336187600889} \  {f \sp {42}}} -
{{39169739565161107} \  {f \sp {36}}} -
\right.
\\
\displaystyle
{{6127176127489690827} \  {f \sp {30}}} -
{{7217708742310509615} \  {f \sp {24}}}+
\\
\displaystyle
{{538628483890722735} \  {f \sp {18}}}+
{{7506804353843507643} \  {f \sp {12}}}+
\\
\displaystyle
\left.
{{5886160769782607203} \  {f \sp 6}}+
{63576108396535879} 
\right)\  e+
\\
\displaystyle
{{71737781777066} \  {f \sp {43}}} -
{{183218856207557938} \  {f \sp {37}}} -
\\
\displaystyle
{{28672874271132276078} \  {f \sp {31}}} -
{{35625223686939812010} \  {f \sp {25}}}+
\\
\displaystyle
{{164831339634084390} \  {f \sp {19}}}+
{{35724160423073052642} \  {f \sp {13}}}+
\\
\displaystyle
{{28627022578664910622} \  {f \sp 7}}+
{{187459987029680506} \  f}, \hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
{{1322793166094400} \  {e \sp 6}} -
{{3968379498283200} \  f \  {e \sp 5}}+
\\
\displaystyle
{{3968379498283200} \  {f \sp 2} \  {e \sp 4}} -
{{5291172664377600} \  {f \sp 3} \  {e \sp 3}}+
\\
\displaystyle
\left( -{{230166010900425600} \  {f \sp {10}}} -
{{226197631402142400} \  {f \sp 4}} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( 
-{{152375364610443885} \  {f \sp {47}}}+
{{389166626064854890415} \  {f \sp {41}}}+
\right.
\\
\displaystyle
{{60906097841360558987335} \  {f \sp {35}}}+
{{76167367934608798697275} \  {f \sp {29}}}+
\\
\displaystyle
{{27855066785995181125} \  {f \sp {23}}} -
{{76144952817052723145495} \  {f \sp {17}}} -
\\
\displaystyle
\left.
{{60933629892463517546975} \  {f \sp {11}}} -
{{411415071682002547795} \  {f \sp 5}} 
\right)\  e -
\\
\displaystyle
{{209493533143822} \  {f \sp {42}}}+
{{535045979490560586} \  {f \sp {36}}}+
\\
\displaystyle
{{83737947964973553146} \  {f \sp {30}}}+
{{104889507084213371570} \  {f \sp {24}}}+
\\
\displaystyle
{{167117997269207870} \  {f \sp {18}}} -
{{104793725781390615514} \  {f \sp {12}}} -
\\
\displaystyle
{{83842685189903180394} \  {f \sp 6}} -
{569978796672974242}, \hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( {{25438330117200} \  {f \sp 6}}+
{25438330117200} 
\right)\  {e \sp 3}+
\\
\displaystyle
\left( {{76314990351600} \  {f \sp 7}}+
{{76314990351600} \  f} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( -{{1594966552735} \  {f \sp {44}}}+
{{4073543370415745} \  {f \sp {38}}}+
\right.
\\
\displaystyle
{{637527159231148925} \  {f \sp {32}}}+
{{797521176113606525} \  {f \sp {26}}}+
\\
\displaystyle
{{530440941097175} \  {f \sp {20}}} -
{{797160527306433145} \  {f \sp {14}}} -
\\
\displaystyle
\left.
{{638132320196044965} \  {f \sp 8}} -
{{4510507167940725} \  {f \sp 2}} 
\right)\  e -
\\
\displaystyle
{{6036376800443} \  {f \sp {45}}}+
{{15416903421476909} \  {f \sp {39}}}+
\\
\displaystyle
{{2412807646192304449} \  {f \sp {33}}}+
{{3017679923028013705} \  {f \sp {27}}}+
\\
\displaystyle
{{1422320037411955} \  {f \sp {21}}} -
{{3016560402417843941} \  {f \sp {15}}} -
\\
\displaystyle
{{2414249368183033161} \  {f \sp 9}} -
{{16561862361763873} \  {f \sp 3}}, \hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{1387545279120} \  {f \sp {12}}} -
{1387545279120} 
\right)\  {e \sp 2}+
\\
\displaystyle
\left( {{4321823003} \  {f \sp {43}}} -
{{11037922310209} \  {f \sp {37}}} -
\right.
\\
\displaystyle
{{1727510711947989} \  {f \sp {31}}} -
{{2165150991154425} \  {f \sp {25}}} -
\\
\displaystyle
{{5114342560755} \  {f \sp {19}}}+
{{2162682824948601} \  {f \sp {13}}}+
\\
\displaystyle
\left.
{{1732620732685741} \  {f \sp 7}}+
{{13506088516033} \  f} 
\right)\  e+
\\
\displaystyle
{{24177661775} \  {f \sp {44}}} -
{{61749727185325} \  {f \sp {38}}} -
\\
\displaystyle
{{9664106795754225} \  {f \sp {32}}} -
{{12090487758628245} \  {f \sp {26}}} -
\\
\displaystyle
{{8787672733575} \  {f \sp {20}}}+
{{12083693383005045} \  {f \sp {14}}}+
\\
\displaystyle
{{9672870290826025} \  {f \sp 8}}+
{{68544102808525} \  {f \sp 2}}, \hbox{\hskip 5.0cm}
\end{array}
$$
$$
\left.
\begin{array}{@{}l}
{f \sp {48}} -
{{2554} \  {f \sp {42}}} -
{{399710} \  {f \sp {36}}}-
{{499722} \  {f \sp {30}}}+
\\
\displaystyle
{{499722} \  {f \sp {18}}}+
{{399710} \  {f \sp {12}}}+
{{2554} \  {f \sp 6}} -
1 \hbox{\hskip 6.0cm}
\end{array}
\right]
$$
\returnType{Type: List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

Apply lexTriangular to compute a decomposition into regular triangular sets.
This should not take more than 5 seconds.

\spadcommand{lexTriangular(lg,false)\$lextripack}
$$
\begin{array}{@{}l}
\left[
\begin{array}{@{}l}
\left\{ 
{{f \sp 6}+1}, 
{{e \sp 6} -
{3 \  f \  {e \sp 5}}+
{3 \  {f \sp 2} \  {e \sp 4}} -
{4 \  {f \sp 3} \  {e \sp 3}}+
{3 \  {f \sp 4} \  {e \sp 2}} -
{3 \  {f \sp 5} \  e} -1}, 
\right.
\\
\displaystyle
{{3 \  d}+{{f \sp 2} \  {e \sp 5}} -
{4 \  {f \sp 3} \  {e \sp 4}}+
{4 \  {f \sp 4} \  {e \sp 3}} -
{2 \  {f \sp 5} \  {e \sp 2}} -
{2 \  e}+{2 \  f}}, 
{c+f}, 
\\
\displaystyle
{{3 \  b}+
{2 \  {f \sp 2} \  {e \sp 5}} -
{5 \  {f \sp 3} \  {e \sp 4}}+
{5 \  {f \sp 4} \  {e \sp 3}} -
{{10} \  {f \sp 5} \  {e \sp 2}} -
{4 \  e}+{7 \  f}}, 
\\
\displaystyle
\left.
{a -{{f \sp 2} \  {e \sp 5}}+
{3 \  {f \sp 3} \  {e \sp 4}} -
{3 \  {f \sp 4} \  {e \sp 3}}+
{4 \  {f \sp 5} \  {e \sp 2}}+
{3 \  e} -{3 \  f}} 
\right\},
\end{array}
\right.
\\
\\
\displaystyle
\left\{ 
{{f \sp 6} -1}, 
{e -f}, 
{d -f}, 
{{c \sp 2}+
{4 \  f \  c}+
{f \sp 2}}, 
{{{\left( 
c -f 
\right)}\  b} -
{f \  c} -
{5 \  {f \sp 2}}}, 
{a+b+c+{3 \  f}} 
\right\},
\\
\\
\displaystyle
\left\{ 
{{f \sp 6} -1}, 
{e -f}, 
{d -f}, 
{c -f}, 
{{b \sp 2}+
{4 \  f \  b}+
{f \sp 2}}, 
{a+b+{4 \  f}} 
\right\},
\\
\\
\displaystyle
\left\{ 
{{f \sp 6} -1}, 
{e -f}, 
{{d \sp 2}+
{4 \  f \  d}+
{f \sp 2}}, 
{{{\left( d -f \right)}\  c} -
{f \  d} -
{5 \  {f \sp 2}}}, 
{b -f}, 
{a+c+d+{3 \  f}} 
\right\},
\\
\\
\displaystyle
\begin{array}{@{}l}
\left\{ 
{{f \sp {36}} -
{{2554} \  {f \sp {30}}} -
{{399709} \  {f \sp {24}}} -
{{502276} \  {f \sp {18}}} -
{{399709} \  {f \sp {12}}} -
{{2554} \  {f \sp 6}}+1}, 
\right.
\\
\displaystyle
\left( 
{{161718564} \  {f \sp {12}}} -
{161718564} 
\right)\  {e \sp 2}+
\left( 
-{{504205} \  {f \sp {31}}}+
{{1287737951} \  {f \sp {25}}}+
\right.
\\
\displaystyle
\left.
{{201539391380} \  {f \sp {19}}}+
{{253982817368} \  {f \sp {13}}}+
{{201940704665} \  {f \sp 7}}+
{{1574134601} \  f} 
\right)\  e -
\\
\displaystyle
{{2818405} \  {f \sp {32}}}+
{{7198203911} \  {f \sp {26}}}+
{{1126548149060} \  {f \sp {20}}}+
\\
\displaystyle
{{1416530563364} \  {f \sp {14}}}+
{{1127377589345} \  {f \sp 8}}+
{{7988820725} \  {f \sp 2}},  
\\
\displaystyle
\left( 
{{693772639560} \  {f \sp 6}} -
{693772639560} 
\right)\  d -
{{462515093040} \  {f \sp 2} \  {e \sp 5}}+
\\
\displaystyle
{{1850060372160} \  {f \sp 3} \  {e \sp 4}} -
{{1850060372160} \  {f \sp 4} \  {e \sp 3}}+
\left( 
-{{24513299931120} \  {f \sp {11}}} -
\right.
\\
\displaystyle
\left.
{{23588269745040} \  {f \sp 5}} 
\right)\  {e \sp 2}+
\left( 
-{{890810428} \  {f \sp {30}}}+
{{2275181044754} \  {f \sp {24}}}+
\right.
\\
\displaystyle
{{355937263869776} \  {f \sp {18}}}+
{{413736880104344} \  {f \sp {12}}}+
{{342849304487996} \  {f \sp 6}}+
\\
\displaystyle
\left.
{3704966481878} 
\right)\  e -
{{4163798003} \  {f \sp {31}}}+
{{10634395752169} \  {f \sp {25}}}+
\\
\displaystyle
{{1664161760192806} \  {f \sp {19}}}+
{{2079424391370694} \  {f \sp {13}}}+
{{1668153650635921} \  {f \sp 7}}+
\\
\displaystyle
{{10924274392693} \  f}, 
\left( 
{{12614047992} \  {f \sp 6}} -
{12614047992} 
\right)\  c -
\\
\displaystyle
{{7246825} \  {f \sp {31}}}+
{{18508536599} \  {f \sp {25}}}+
{{2896249516034} \  {f \sp {19}}}+
\\
\displaystyle
{{3581539649666} \  {f \sp {13}}}+
{{2796477571739} \  {f \sp 7}} -
{{48094301893} \  f}, 
\\
\displaystyle
\left( 
{{693772639560} \  {f \sp 6}} -
{693772639560} 
\right)\  b -
{{925030186080} \  {f \sp 2} \  {e \sp 5}}+
\\
\displaystyle
{{2312575465200} \  {f \sp 3} \  {e \sp 4}} -
{{2312575465200} \  {f \sp 4} \  {e \sp 3}}+
\left( 
-{{40007555547960} \  {f \sp {11}}} -
\right.
\\
\displaystyle
\left.
{{35382404617560} \  {f \sp 5}} 
\right)\  {e \sp 2}+
\left( 
-{{3781280823} \  {f \sp {30}}}+
{{9657492291789} \  {f \sp {24}}}+
\right.
\\
\displaystyle
{{1511158913397906} \  {f \sp {18}}}+
{{1837290892286154} \  {f \sp {12}}}+
{{1487216006594361} \  {f \sp 6}}+
\\
\displaystyle
\left.
{8077238712093} 
\right)\  e -
{{9736390478} \  {f \sp {31}}}+
{{24866827916734} \  {f \sp {25}}}+
\\
\displaystyle
{{3891495681905296} \  {f \sp {19}}}+
{{4872556418871424} \  {f \sp {13}}}+
{{3904047887269606} \  {f \sp 7}}+
\\
\displaystyle
\left.
{{27890075838538} \  f}, 
{a+b+c+d+e+f} 
\right\},
\end{array}
\\
\\
\displaystyle
\left.
\left\{ 
{{f \sp 6} -1}, 
{{e \sp 2}+
{4 \  f \  e}+
{f \sp 2}},  
{{{\left( e -f \right)}\  d} -
{f \  e} -
{5 \  {f \sp 2}}}, 
{c -f}, 
{b -f}, 
{a+d+e+{3 \  f}} 
\right\}

\right]
\end{array}
$$
\returnType{Type: List RegularChain(Integer,[a,b,c,d,e,f])}

Note that the first set of the decomposition is normalized (all
initials are integer numbers) but not the second one (normalized
triangular sets are defined in the description of the 
{\tt NormalizedTriangularSetCategory} constructor).

So apply now lexTriangular to produce normalized triangular sets.

\spadcommand{lts := lexTriangular(lg,true)\$lextripack   }
$$
\begin{array}{@{}l}
\left[
\begin{array}{@{}l}
\left\{ 
{{f \sp 6}+1}, 
{{e \sp 6} -
{3 \  f \  {e \sp 5}}+
{3 \  {f \sp 2} \  {e \sp 4}} -
{4 \  {f \sp 3} \  {e \sp 3}}+
{3 \  {f \sp 4} \  {e \sp 2}} -
{3 \  {f \sp 5} \  e} -1}, 
\right.
\\
\displaystyle
{{3 \  d}+
{{f \sp 2} \  {e \sp 5}} -
{4 \  {f \sp 3} \  {e \sp 4}}+
{4 \  {f \sp 4} \  {e \sp 3}} -
{2 \  {f \sp 5} \  {e \sp 2}} -
{2 \  e}+{2 \  f}}, 
{c+f}, 
\\
\displaystyle
{{3 \  b}+
{2 \  {f \sp 2} \  {e \sp 5}}-
{5 \  {f \sp 3} \  {e \sp 4}}+
{5 \  {f \sp 4} \  {e \sp 3}} -
{{10} \  {f \sp 5} \  {e \sp 2}} -
{4 \  e}+{7 \  f}}, 
\\
\displaystyle
\left.
{a -{{f \sp 2} \  {e \sp 5}}+
{3 \  {f \sp 3} \  {e \sp 4}} -
{3 \  {f \sp 4} \  {e \sp 3}}+
{4 \  {f \sp 5} \  {e \sp 2}}+
{3 \  e} -
{3 \  f}} 
\right\},
\end{array}
\right.
\\
\\
\displaystyle
{\left\{ {{f \sp 6} -1}, {e -f}, {d -f}, {{c \sp 2}+{4 \  f \  
c}+{f \sp 2}}, {b+c+{4 \  f}}, {a -f} 
\right\}},
\\
\\
\displaystyle
{\left\{ {{f \sp 6} -1}, {e -f}, {d -f}, {c -f}, {{b \sp 2}+{4 
\  f \  b}+{f \sp 2}}, {a+b+{4 \  f}} 
\right\}},
\\
\\
\displaystyle
{\left\{ {{f \sp 6} -1}, {e -f}, {{d \sp 2}+{4 \  f \  d}+{f \sp 
2}}, {c+d+{4 \  f}}, {b -f}, {a -f} 
\right\}},
\\
\\
\displaystyle
\begin{array}{@{}l}
\left\{ 
{{f \sp {36}} -
{{2554} \  {f \sp {30}}} -
{{399709} \  {f \sp {24}}} -
{{502276} \  {f \sp {18}}} -
{{399709} \  {f \sp {12}}} -
{{2554} \  {f \sp 6}}+
1},
\right.
\\
\displaystyle
{{1387545279120} \  {e \sp 2}}+
\left( 
{{4321823003} \  {f \sp {31}}} -
{{11037922310209} \  {f \sp {25}}} -
\right.
\\
\displaystyle
{{1727506390124986} \  {f \sp {19}}} -
{{2176188913464634} \  {f \sp {13}}} -
{{1732620732685741} \  {f \sp 7}} -
\\
\displaystyle
\left.
{{13506088516033} \  f} 
\right)\  e+
{{24177661775} \  {f \sp {32}}} -
{{61749727185325} \  {f \sp {26}}} -
\\
\displaystyle
{{9664082618092450} \  {f \sp {20}}} -
{{12152237485813570} \  {f \sp {14}}} -
{{9672870290826025} \  {f \sp 8}} -
\\
\displaystyle
{{68544102808525} \  {f \sp 2}}, 
\\
\displaystyle
{{1387545279120} \  d}+
\left( 
-{{1128983050} \  {f \sp {30}}}+
{{2883434331830} \  {f \sp {24}}}+
\right.
\\
\displaystyle
{{451234998755840} \  {f \sp {18}}}+
{{562426491685760} \  {f \sp {12}}}+
{{447129055314890} \  {f \sp 6}} -
\\
\displaystyle
\left.
{165557857270} 
\right)\  e -
{{1816935351} \  {f \sp {31}}}+
{{4640452214013} \  {f \sp {25}}}+
\\
\displaystyle
{{726247129626942} \  {f \sp {19}}}+
{{912871801716798} \  {f \sp {13}}}+
{{726583262666877} \  {f \sp 7}}+
\\
\displaystyle
{{4909358645961} \  f}, 
\\
\displaystyle
{{1387545279120} \  c}+
{{778171189} \  {f \sp {31}}} -
{{1987468196267} \  {f \sp {25}}} -
\\
\displaystyle
{{310993556954378} \  {f \sp {19}}} -
{{383262822316802} \  {f \sp {13}}} -
{{300335488637543} \  {f \sp 7}}+
\\
\displaystyle
{{5289595037041} \  f}, 
\\
\displaystyle
{{1387545279120} \  b}+
\left( 
{{1128983050} \  {f \sp {30}}} -
{{2883434331830} \  {f \sp {24}}} -
\right.
\\
\displaystyle
{{451234998755840} \  {f \sp {18}}}-
{{562426491685760} \  {f \sp {12}}} -
{{447129055314890} \  {f \sp 6}}+
\\
\displaystyle
\left.
{165557857270} 
\right)\  e -
{{3283058841} \  {f \sp {31}}}+
{{8384938292463} \  {f \sp {25}}}+
\\
\displaystyle
{{1312252817452422} \  {f \sp {19}}}+
{{1646579934064638} \  {f \sp {13}}}+
{{1306372958656407} \  {f \sp 7}}+
\\
\displaystyle
{{4694680112151} \  f}, 
\\
\displaystyle
{{1387545279120} \  a}+
{{1387545279120} \  e}+
{{4321823003} \  {f \sp {31}}} -
\\
\displaystyle
{{11037922310209} \  {f \sp {25}}} -
{{1727506390124986} \  {f \sp {19}}} -
{{2176188913464634} \  {f \sp {13}}} -
\\
\displaystyle
\left.
{{1732620732685741} \  {f \sp 7}} -
{{13506088516033} \  f} 
\right\},
\end{array}
\\
\\
\displaystyle
\left.
\left\{ 
{{f \sp 6} -1}, 
{{e \sp 2}+{4 \  f \  e}+{f \sp 2}}, 
{d+e+{4 \  f}}, 
{c -f}, 
{b -f}, 
{a -f} 
\right\}
\right]
\end{array}
$$
\returnType{Type: List RegularChain(Integer,[a,b,c,d,e,f])}

We check that all initials are constant.

\spadcommand{[ [init(p) for p in (ts :: List(P))] for ts in lts]  }
$$
\begin{array}{@{}l}
\left[
{\left[ 1, 3, 1, 3, 1, 1 \right]},
{\left[ 1, 1, 1, 1, 1, 1 \right]},
{\left[ 1, 1, 1, 1, 1, 1 \right]},
{\left[ 1, 1, 1, 1, 1, 1 \right]},
\right.
\\
\displaystyle
\left[ {1387545279120}, {1387545279120}, {1387545279120}, 
\right.
\\
\displaystyle
\left.
{1387545279120}, {1387545279120}, 1 \right],
\\
\displaystyle
\left.
{\left[ 1, 1, 1, 1, 1, 1\right]}
\right]
\end{array}
$$
\returnType{Type: List List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f])}

Note that each triangular set in {\bf lts} is a lexicographical
Groebner basis.  Recall that a point belongs to the variety associated
with {\bf lp} if and only if it belongs to that associated with one
triangular set {\bf ts} in {\bf lts}.

By running the \spadfunFrom{squareFreeLexTriangular}{LexTriangularPackage} 
operation, we retrieve the above decomposition.

\spadcommand{squareFreeLexTriangular(lg,true)\$lextripack  }
$$
\begin{array}{@{}l}
\left[
\left\{ 
{{f \sp 6}+1}, 
{{e \sp 6} -
{3 \  f \  {e \sp 5}}+
{3 \  {f \sp 2} \  {e \sp 4}} -
{4 \  {f \sp 3} \  {e \sp 3}}+
{3 \  {f \sp 4} \  {e \sp 2}} -
{3 \  {f \sp 5} \  e} -1}, 
\right.
\right.
\\
\displaystyle
{{3 \  d}+
{{f \sp 2} \  {e \sp 5}} -
{4 \  {f \sp 3} \  {e \sp 4}}+
{4 \  {f \sp 4} \  {e \sp 3}} -
{2 \  {f \sp 5} \  {e \sp 2}} -
{2 \  e}+
{2 \  f}}, 
\\
\displaystyle
{c+f}, 
{{3 \  b}+
{2 \  {f \sp 2} \  {e \sp 5}} -
{5 \  {f \sp 3} \  {e \sp 4}}+
{5 \  {f \sp 4} \  {e \sp 3}} -
{{10} \  {f \sp 5} \  {e \sp 2}} -
{4 \  e}+{7 \  f}}, 
\\
\displaystyle
\left.
{a -
{{f \sp 2} \  {e \sp 5}}+
{3 \  {f \sp 3} \  {e \sp 4}} -
{3 \  {f \sp 4} \  {e \sp 3}}+
{4 \  {f \sp 5} \  {e \sp 2}}+
{3 \  e} -{3 \  f}} 
\right\},\hbox{\hskip 4.0cm}
\end{array}
$$
$$
\left\{ 
{{f \sp 6} -1}, 
{e -f}, 
{d -f}, 
{{c \sp 2}+
{4 \  f \  c}+
{f \sp 2}}, 
{b+c+{4 \  f}}, 
{a -f} 
\right\},\hbox{\hskip 3.5cm}
$$
$$
\left\{ 
{{f \sp 6} -1}, 
{e -f}, 
{d -f}, 
{c -f}, 
{{b \sp 2}+
{4 \  f \  b}+
{f \sp 2}}, 
{a+b+{4 \  f}} 
\right\},\hbox{\hskip 3.5cm}
$$
$$
\left\{ 
{{f \sp 6} -1}, 
{e -f}, 
{{d \sp 2}+
{4 \  f \  d}+
{f \sp 2}}, 
{c+d+{4 \  f}}, 
{b -f}, 
{a -f} 
\right\},\hbox{\hskip 3.5cm}
$$
$$
\begin{array}{@{}l}
\left\{ 
{{f \sp {36}} -
{{2554} \  {f \sp {30}}} -
{{399709} \  {f \sp {24}}} -
{{502276} \  {f \sp {18}}} -
{{399709} \  {f \sp {12}}} -
{{2554} \  {f \sp 6}}+1}, 
\right.
\\
\displaystyle
{{1387545279120} \  {e \sp 2}}+
\left( {{4321823003} \  {f \sp {31}}} -
{{11037922310209} \  {f \sp {25}}} -
\right.
\\
\displaystyle
{{1727506390124986} \  {f \sp {19}}} -
{{2176188913464634} \  {f \sp {13}}} -
{{1732620732685741} \  {f \sp 7}} -
\\
\displaystyle
\left.
{{13506088516033} \  f} 
\right)\  e+
{{24177661775} \  {f \sp {32}}} -
{{61749727185325} \  {f \sp {26}}}-
\\
\displaystyle
{{9664082618092450} \  {f \sp {20}}} -
{{12152237485813570} \  {f \sp {14}}} -
{{9672870290826025} \  {f \sp 8}} -
\\
\displaystyle
{{68544102808525} \  {f \sp 2}}, 
\\
\displaystyle
{{1387545279120} \  d}+
\left( -{{1128983050} \  {f \sp {30}}}+
{{2883434331830} \  {f \sp {24}}}+
\right.
\\
\displaystyle
{{451234998755840} \  {f \sp {18}}}+
{{562426491685760} \  {f \sp {12}}}+
{{447129055314890} \  {f \sp 6}} -
\\
\displaystyle
\left.
{165557857270} 
\right)\  e -
{{1816935351} \  {f \sp {31}}}+
{{4640452214013} \  {f \sp {25}}}+
\\
\displaystyle
{{726247129626942} \  {f \sp {19}}}+
{{912871801716798} \  {f \sp {13}}}+
{{726583262666877} \  {f \sp 7}}+
\\
\displaystyle
{{4909358645961} \  f},
\\
\displaystyle
{{1387545279120} \  c}+
{{778171189} \  {f \sp {31}}} -
{{1987468196267} \  {f \sp {25}}} -
\\
\displaystyle
{{310993556954378} \  {f \sp {19}}} -
{{383262822316802} \  {f \sp {13}}} -
{{300335488637543} \  {f \sp 7}}+
\\
\displaystyle
{{5289595037041} \  f}, 
\\
\displaystyle
{{1387545279120} \  b}+
\left( 
{{1128983050} \  {f \sp {30}}} -
{{2883434331830} \  {f \sp {24}}} -
\right.
\\
\displaystyle
{{451234998755840} \  {f \sp {18}}} -
{{562426491685760} \  {f \sp {12}}} -
{{447129055314890} \  {f \sp 6}}+
\\
\displaystyle
\left.
{165557857270} 
\right)\  e -
{{3283058841} \  {f \sp {31}}}+
{{8384938292463} \  {f \sp {25}}}+
\\
\displaystyle
{{1312252817452422} \  {f \sp {19}}}+
{{1646579934064638} \  {f \sp {13}}}+
{{1306372958656407} \  {f \sp 7}}+
\\
\displaystyle
{{4694680112151} \  f}, 
{{1387545279120} \  a}+
{{1387545279120} \  e}+
\\
\displaystyle
{{4321823003} \  {f \sp {31}}} -
{{11037922310209} \  {f \sp {25}}} -
{{1727506390124986} \  {f \sp {19}}} -
\\
\displaystyle
\left.
{{2176188913464634} \  {f \sp {13}}} -
{{1732620732685741} \  {f \sp 7}} -
{{13506088516033} \  f} 
\right\},\hbox{\hskip 1.5cm}
\end{array}
$$
$$
\left.
\left\{ 
{{f \sp 6} -1}, 
{{e \sp 2}+
{4 \  f \  e}+
{f \sp 2}}, 
{d+e+{4 \  f}}, 
{c -f}, 
{b -f}, 
{a -f} 
\right\}
\right]\hbox{\hskip 3.5cm}
$$
\returnType{Type: List SquareFreeRegularTriangularSet(Integer,IndexedExponents OrderedVariableList [a,b,c,d,e,f],OrderedVariableList [a,b,c,d,e,f],NewSparseMultivariatePolynomial(Integer,OrderedVariableList [a,b,c,d,e,f]))}

Thus the solutions given by {\bf lts} are pairwise different.

We count them as follows.

\spadcommand{reduce(+,[degree(ts) for ts in lts]) }
$$
156 
$$
\returnType{Type: PositiveInteger}

We can investigate the triangular decomposition {\bf lts} by using the
{\tt ZeroDimensionalSolve\-Package}.

This requires to add an extra variable (smaller than the others) as follows.

\spadcommand{ls2 : List Symbol := concat(ls,new()\$Symbol)  }
$$
\left[
a, b, c, d, e, f, \%A 
\right]
$$
\returnType{Type: List Symbol}

Then we call the package.

\spadcommand{zdpack := ZDSOLVE(R,ls,ls2)    }
$$
ZeroDimensionalSolvePackage(Integer,[a,b,c,d,e,f],[a,b,c,d,e,f,%A]) 
$$
\returnType{Type: Domain}

We compute a univariate representation of the variety associated with
the input system as follows.

\spadcommand{concat [univariateSolve(ts)\$zdpack for ts in lts]  }
$$
\begin{array}{@{}l}
\left[
\left[ 
{complexRoots={{? \sp 4} -{{13} \  {? \sp 2}}+{49}}}, 
\right.
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{7 \  a}+{ \%A \sp 3} -{6 \  \%A}}, 
{{{21} \  b}+{  \%A \sp 3}+ \%A}, 
\right.
\\
\displaystyle
{{{21} \  c} -{2 \  { \%A \sp 3}}+{{19} \  \%A}}, 
{{7 \  d} -{ \%A \sp 3}+{6 \  \%A}}, 
{{{21} \  e} -{ \%A \sp 3} - \%A}, 
\\
\displaystyle
\left.
\left.
{{{21} \  f}+{2 \  { \%A \sp 3}} -{{19} \  \%A}} 
\right]
\right],\hbox{\hskip 7.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4}+{{11} \  {? \sp 2}}+{49}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{35} \  a}+{3 \  { \%A \sp 3}}+{{19} \  \%A}}, 
{{{35} \  b}+{ \%A \sp 3}+{{18} \  \%A}}, 
{{{35} \  c} -{2 \  { \%A \sp 3}} - \%A}, 
\right.
\\
\displaystyle
\left.
\left.
{{{35} \  d} -{3 \  { \%A \sp 3}} -{{19} \  \%A}}, 
{{{35} \  e} -{ \%A \sp 3} -{{18} \  \%A}}, 
{{{35} \  f}+{2 \  { \%A \sp 3}}+ \%A} 
\right]
\right],\hbox{\hskip 2.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{? \sp 8} -{{12} \  {? \sp 7}}+{{58} \  {? \sp 6}} -{{120} \  {? \sp 5}}+
\right.
\\
\displaystyle
{{207} \  {? \sp 4}} -
{{360} \  {? \sp 3}}+
{{802} \  {? \sp 2}} -
{{1332} \  ?}+{1369}, 
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{43054532} \  a}+{{33782} \  { \%A \sp 7}} -
{{546673} \  { \%A \sp 6}}+
{{3127348} \  { \%A \sp 5}} -{{6927123} \  { \%A \sp 4}}+
\right.
\\
\displaystyle
{{4365212} \  { \%A \sp 3}} -
{{25086957} \  { \%A \sp 2}}+
{{39582814} \  \%A} -{107313172}, 
\\
\displaystyle
{{43054532} \  b} -{{33782} \  { \%A \sp 7}}+
{{546673} \  { \%A \sp 6}} -
{{3127348} \  { \%A \sp 5}}+
\\
\displaystyle
{{6927123} \  { \%A \sp 4}} -
{{4365212} \  { \%A \sp 3}}+
{{25086957} \  { \%A \sp 2}} -
\\
\displaystyle
{{39582814} \  \%A}+{107313172}, 
\\
\displaystyle
{{21527266} \  c} -{{22306} \  { \%A \sp 7}}+
{{263139} \  { \%A \sp 6}} -
{{1166076} \  { \%A \sp 5}}+{{1821805} \  { \%A \sp 4}} -
\\
\displaystyle
{{2892788} \  { \%A \sp 3}}+
{{10322663} \  { \%A \sp 2}} -
{{9026596} \  \%A}+{12950740}, 
\\
\displaystyle
{{43054532} \  d}+
{{22306} \  { \%A \sp 7}} -
{{263139} \  { \%A \sp 6}}+
\\
\displaystyle
{{1166076} \  { \%A \sp 5}} -
{{1821805} \  { \%A \sp 4}}+
{{2892788} \  { \%A \sp 3}} -
\\
\displaystyle
{{10322663} \  { \%A \sp 2}}+
{{30553862} \  \%A} -{12950740}, 
\\
\displaystyle
{{43054532} \  e} -
{{22306} \  { \%A \sp 7}}+
{{263139} \  { \%A \sp 6}} -
\\
\displaystyle
{{1166076} \  { \%A \sp 5}}+
{{1821805} \  { \%A \sp 4}} -
{{2892788} \  { \%A \sp 3}}+
\\
\displaystyle
{{10322663} \  { \%A \sp 2}} -
{{30553862} \  \%A}+{12950740}, 
\\
\displaystyle
{{21527266} \  f}+
{{22306} \  { \%A \sp 7}} -
{{263139} \  { \%A \sp 6}}+
\\
\displaystyle
{{1166076} \  { \%A \sp 5}} -
{{1821805} \  { \%A \sp 4}}+
{{2892788} \  { \%A \sp 3}} -
\\
\displaystyle
\left.
\left.
{{10322663} \  { \%A \sp 2}}+
{{9026596} \  \%A} -{12950740} 
\right]
\right],\hbox{\hskip 5.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{? \sp 8}+
{{12} \  {? \sp 7}}+
{{58} \  {? \sp 6}}+
{{120} \  {? \sp 5}}+
\right.
\\
\displaystyle
{{207} \  {? \sp 4}}+
{{360} \  {? \sp 3}}+
{{802} \  {? \sp 2}}+
{{1332} \  ?}+{1369}, 
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{43054532} \  a}+
{{33782} \  { \%A \sp 7}}+
{{546673} \  { \%A \sp 6}}+
{{3127348} \  { \%A \sp 5}}+
\right.
\\
\displaystyle
{{6927123} \  { \%A \sp 4}}+
{{4365212} \  { \%A \sp 3}}+
{{25086957} \  { \%A \sp 2}}+
{{39582814} \  \%A}+{107313172}, 
\\
\displaystyle
{{43054532} \  b} -
{{33782} \  { \%A \sp 7}} -
{{546673} \  { \%A \sp 6}} -
{{3127348} \  { \%A \sp 5}} -
\\
\displaystyle
{{6927123} \  { \%A \sp 4}} -
{{4365212} \  { \%A \sp 3}} -
{{25086957} \  { \%A \sp 2}} -
{{39582814} \  \%A} -
{107313172}, 
\\
\displaystyle
{{21527266} \  c} -
{{22306} \  { \%A \sp 7}} -
{{263139} \  { \%A \sp 6}} -
{{1166076} \  { \%A \sp 5}} -
\\
\displaystyle
{{1821805} \  { \%A \sp 4}} -
{{2892788} \  {  \%A \sp 3}} -
{{10322663} \  { \%A \sp 2}} -
{{9026596} \  \%A} -
{12950740}, 
\\
\displaystyle
{{43054532} \  d}+
{{22306} \  { \%A \sp 7}}+
{{263139} \  { \%A \sp 6}}+
{{1166076} \  { \%A \sp 5}}+
\\
\displaystyle
{{1821805} \  { \%A \sp 4}}+
{{2892788} \  {  \%A \sp 3}}+
{{10322663} \  { \%A \sp 2}}+
{{30553862} \  \%A}+
{12950740}, 
\\
\displaystyle
{{43054532} \  e} -
{{22306} \  { \%A \sp 7}} -
{{263139} \  { \%A \sp 6}} -
{{1166076} \  { \%A \sp 5}} -
\\
\displaystyle
{{1821805} \  { \%A \sp 4}} -
{{2892788} \  {  \%A \sp 3}} -
{{10322663} \  { \%A \sp 2}} -
{{30553862} \  \%A} -
{12950740}, 
\\
\displaystyle
{{21527266} \  f}+
{{22306} \  { \%A \sp 7}}+
{{263139} \  { \%A \sp 6}}+
{{1166076} \  { \%A \sp 5}}+
\\
\displaystyle
\left.
\left.
{{1821805} \  { \%A \sp 4}}+
{{2892788} \  {  \%A \sp 3}}+
{{10322663} \  { \%A \sp 2}}+
{{9026596} \  \%A}+
{12950740}
\right]
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 4} -{? \sp 2}+1}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ 
{a - \%A}, 
{b+{ \%A \sp 3} - \%A}, 
{c+{ \%A \sp 3}}, 
{d+ \%A}, 
{e -{ \%A \sp 3}+ \%A}, 
{f -{ \%A \sp 3}} 
\right]
\right],\hbox{\hskip 1.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 8}+{4 \  {? \sp 6}}+{{12} \  {? \sp 4}}+{{16} \  {? \sp 2}}+4}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{4 \  a} -
{2 \  { \%A \sp 7}} -
{7 \  { \%A \sp 5}} -
{{20} \  { \%A \sp 3}} -
{{22} \  \%A}}, 
\right.
\\
\displaystyle
{{4 \  b}+
{2 \  { \%A \sp 7}}+
{7 \  { \%A \sp 5}}+
{{20} \  { \%A \sp 3}}+
{{22} \   \%A}}, 
\\
\displaystyle
{{4 \  c}+
{ \%A \sp 7}+
{3 \  { \%A \sp 5}}+
{{10} \  { \%A \sp 3}}+
{{10} \  \%A}}, 
\\
\displaystyle
{{4 \  d}+{ \%A \sp 7}+
{3 \  { \%A \sp 5}}+{{10} \  {  \%A \sp 3}}+
{6 \  \%A}},
\\
\displaystyle
{{4 \  e} -
{ \%A \sp 7} -
{3 \  { \%A \sp 5}} -
{{10} \  { \%A \sp 3}} -
{6 \  \%A}}, 
\\
\displaystyle
\left.
\left.
{{4 \  f} -
{ \%A \sp 7} -
{3 \  { \%A \sp 5}} -
{{10} \  { \%A \sp 3}} -
{{10} \  \%A}} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4}+{6 \  {? \sp 3}}+{{30} \  {? \sp 2}}+{{36} \  ?}+{36}},
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{30} \  a} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\right.
\\
\displaystyle
{{6 \  b}+{ \%A \sp 3}+{5 \  {  \%A \sp 2}}+{{24} \  \%A}+6}, 
\\
\displaystyle
{{{30} \  c} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -6}, 
\\
\displaystyle
{{{30} \  d} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\\
\displaystyle
{{{30} \  e} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  f} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4} -{6 \  {? \sp 3}}+{{30} \  {? \sp 2}} -{{36} \  ?}+{36}},
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{30} \  a} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\right.
\\
\displaystyle
{{6 \  b}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{24} \  \%A} -6}, 
\\
\displaystyle
{{{30} \  c} -{ \%A \sp 3}+{5 \  { \%A \sp 2}}+6}, 
\\
\displaystyle
{{{30} \  d} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
{{{30} \  e} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  f} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2}+{6 \  ?}+6}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ 
{a+1}, {b - \%A -5}, {c+ \%A+1}, {d+1}, {e+1}, {f+1} 
\right]
\right],\hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{6 \  ?}+6}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ 
{a -1}, {b - \%A+5}, {c+ \%A -1}, {d -1}, {e -1}, {f -1} 
\right]
\right],\hbox{\hskip 4.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4}+{6 \  {? \sp 3}}+{{30} \  {? \sp 2}}+{{36} \  ?}+{36}},
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{6 \  a}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{24} \  \%A}+6}, 
\right.
\\
\displaystyle
{{{30} \  b} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -6}, 
\\
\displaystyle
{{{30} \  c} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \   \%A} -6}, 
\\
\displaystyle
{{{30} \  d} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\\
\displaystyle
{{{30} \  e} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  f} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4} -{6 \  {? \sp 3}}+{{30} \  {? \sp 2}} -{{36} \  ?}+{36}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{6 \  a}+{ \%A \sp 3} -{5 \  {  \%A \sp 2}}+{{24} \  \%A} -6}, 
\right.
\\
\displaystyle
{{{30} \  b} -{ \%A \sp 3}+{5 \  { \%A \sp 2}}+6}, 
\\
\displaystyle
{{{30} \  c} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
{{{30} \  d} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
{{{30} \  e} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  f} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2}+{6 \  ?}+6}, 
\right.
\\
\displaystyle
\left.
coordinates=
\left[ 
{a - \%A -5}, {b+ \%A+1}, {c+1}, {d+1}, {e+1}, {f+1} 
\right]
\right],\hbox{\hskip 2.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{6 \  ?}+6}, 
\right.
\\
\displaystyle
\left.
coordinates=
\left[ 
{a - \%A+5}, {b+ \%A -1}, {c -1}, {d -1}, {e -1}, {f -1} 
\right]
\right],\hbox{\hskip 2.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4}+{6 \  {? \sp 3}}+{{30} \  {? \sp 2}}+{{36} \  ?}+{36}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{30} \  a} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\right.
\\
\displaystyle
{{{30} \  b} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\\
\displaystyle
{{6 \  c}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{24} \  \%A}+6}, 
\\
\displaystyle
{{{30} \  d} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -6}, 
\\
\displaystyle
{{{30} \  e} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  f} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4} -{6 \  {? \sp 3}}+{{30} \  {? \sp 2}} -{{36} \  ?}+{36}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{30} \  a} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\right.
\\
\displaystyle
{{{30} \  b} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
{{6 \  c}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{24} \  \%A} -6}, 
\\
\displaystyle
{{{30} \  d} -{ \%A \sp 3}+{5 \  { \%A \sp 2}}+6}, 
\\
\displaystyle
{{{30} \  e} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  f} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6} 
\right]
\right],\hbox{\hskip 6.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2}+{6 \  ?}+6}, 
\right.
\\
\displaystyle
\left.
coordinates=
\left[ 
{a+1}, {b+1}, {c - \%A -5}, {d+ \%A+1}, {e+1}, {f+1} 
\right]
\right],\hbox{\hskip 2.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{6 \  ?}+6}, 
\right.
\\
\displaystyle
\left.
coordinates=
\left[ 
{a -1}, {b -1}, {c - \%A+5}, {d+ \%A -1}, {e -1}, {f -1} 
\right]
\right],\hbox{\hskip 2.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{? \sp 8}+
{6 \  {? \sp 7}}+
{{16} \  {? \sp 6}}+
{{24} \  {? \sp 5}}+
{{18} \  {? \sp 4}} -
{8 \  {? \sp 2}}+
4, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{2 \  a}+
{2 \  { \%A \sp 7}}+
{9 \  { \%A \sp 6}}+
{{18} \  { \%A \sp 5}}+
{{19} \  { \%A \sp 4}}+
{4 \  { \%A \sp 3}} -
{{10} \  { \%A \sp 2}} -
{2 \  \%A}+
4, 
\right.
\\
\displaystyle
{2 \  b}+
{2 \  { \%A \sp 7}}+
{9 \  { \%A \sp 6}}+
{{18} \  { \%A \sp 5}}+
{{19} \  { \%A \sp 4}}+
{4 \  { \%A \sp 3}} -
{{10} \  { \%A \sp 2}} -
{4 \  \%A}+
4, 
\\
\displaystyle
{2 \  c} -
{ \%A \sp 7} -
{4 \  { \%A \sp 6}} -
{8 \  { \%A \sp 5}} -
{9 \  { \%A \sp 4}} -
{4 \  { \%A \sp 3}} -
{2 \   \%A} -
4, 
\\
\displaystyle
{2 \  d}+
{ \%A \sp 7}+
{4 \  { \%A \sp 6}}+
{8 \  { \%A \sp 5}}+
{9 \  { \%A \sp 4}}+
{4 \  { \%A \sp 3}}+
{2 \  \%A}+
4, 
\\
\displaystyle
{2 \  e} -
{2 \  { \%A \sp 7}} -
{9 \  { \%A \sp 6}} -
{{18} \  { \%A \sp 5}} -
{{19} \  { \%A \sp 4}} -
{4 \  { \%A \sp 3}}+
{{10} \  { \%A \sp 2}}+
{4 \  \%A} -
4, 
\\
\displaystyle
\left.
\left.
{2 \  f} -
{2 \  { \%A \sp 7}} -
{9 \  { \%A \sp 6}} -
{{18} \  { \%A \sp 5}} -
{{19} \  { \%A \sp 4}} -
{4 \  { \%A \sp 3}}+
{{10} \  { \%A \sp 2}}+
{2 \  \%A} -
4 
\right]
\right],\hbox{\hskip 1.0cm} %mmmm
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
\right.
\\
\displaystyle
{? \sp 8}+{{12} \  {? \sp 7}}+
{{64} \  {? \sp 6}}+
{{192} \  {? \sp 5}}+
{{432} \  {? \sp 4}}+
{{768} \  {? \sp 3}}+
{{1024} \  {? \sp 2}}+
{{768} \  ?}+
{256}, 
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{1408} \  a} -
{{19} \  { \%A \sp 7}} -
{{200} \  { \%A \sp 6}} -
{{912} \  { \%A \sp 5}} -
{{2216} \  { \%A \sp 4}} -
\right.
\\
\displaystyle
{{4544} \  { \%A \sp 3}} -
{{6784} \  { \%A \sp 2}} -
{{6976} \  \%A} -
{1792}, 
\\
\displaystyle
{{1408} \  b} -
{{37} \  { \%A \sp 7}} -
{{408} \  { \%A \sp 6}} -
{{1952} \  { \%A \sp 5}} -
{{5024} \  { \%A \sp 4}} -
\\
\displaystyle
{{10368} \  { \%A \sp 3}} -
{{16768} \  { \%A \sp 2}} -
{{17920} \  \%A} -
{5120}, 
\\
\displaystyle
{{1408} \  c}+
{{37} \  { \%A \sp 7}}+
{{408} \  { \%A \sp 6}}+
{{1952} \  { \%A \sp 5}}+
{{5024} \  { \%A \sp 4}}+
\\
\displaystyle
{{10368} \  { \%A \sp 3}}+
{{16768} \  { \%A \sp 2}}+
{{17920} \  \%A}+
{5120}, 
\\
\displaystyle
{{1408} \  d}+
{{19} \  { \%A \sp 7}}+
{{200} \  { \%A \sp 6}}+
{{912} \  { \%A \sp 5}}+
{{2216} \  { \%A \sp 4}}+
\\
\displaystyle
{{4544} \  { \%A \sp 3}}+
{{6784} \  { \%A \sp 2}}+
{{6976} \  \%A}+
{1792}, 
\\
\displaystyle
{{2 \  e}+ \%A}, 
\\
\displaystyle
\left.
\left.
{{2 \  f} - \%A} 
\right]
\right],\hbox{\hskip 10.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 8}+
{4 \  {? \sp 6}}+
{{12} \  {? \sp 4}}+
{{16} \  {? \sp 2}}+
4}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{4 \  a} -
{ \%A \sp 7} -
{3 \  { \%A \sp 5}} -
{{10} \  { \%A \sp 3}} -
{6 \  \%A}}, 
\right.
\\
\displaystyle
{{4 \  b} -
{  \%A \sp 7} -
{3 \  { \%A \sp 5}} -
{{10} \  { \%A \sp 3}} -
{{10} \  \%A}}, 
\\
\displaystyle
{{4 \  c} -
{2 \  { \%A \sp 7}} -
{7 \  { \%A \sp 5}} -
{{20} \  { \%A \sp 3}} -
{{22} \  \%A}}, 
\\
\displaystyle
{{4 \  d}+
{2 \  { \%A \sp 7}}+
{7 \  { \%A \sp 5}}+
{{20} \  { \%A \sp 3}}+
{{22} \  \%A}}, 
\\
\displaystyle
{{4 \  e}+
{ \%A \sp 7}+
{3 \  { \%A \sp 5}}+
{{10} \  { \%A \sp 3}}+
{{10} \  \%A}}, 
\\
\displaystyle
\left.
\left.
{{4 \  f}+
{ \%A \sp 7}+
{3 \  {  \%A \sp 5}}+
{{10} \  { \%A \sp 3}}+
{6 \  \%A}} 
\right]
\right],\hbox{\hskip 5.9cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 8}+{{16} \  {? \sp 6}} -{{96} \  {? \sp 4}}+
{{256} \  {? \sp 2}}+{256}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{512} \  a} -
{  \%A \sp 7} -
{{12} \  { \%A \sp 5}}+
{{176} \  { \%A \sp 3}} -
{{448} \  \%A}}, 
\right.
\\
\displaystyle
{{{128} \  b} -
{ \%A \sp 7} -
{{16} \  { \%A \sp 5}}+
{{96} \  { \%A \sp 3}} 
-{{256} \  \%A}}, 
\\
\displaystyle
{{{128} \  c}+
{ \%A \sp 7}+
{{16} \  { \%A \sp 5}} -
{{96} \  { \%A \sp 3}}+
{{256} \  \%A}}, 
\\
\displaystyle
{{{512} \  d}+
{ \%A \sp 7}+
{{12} \  {  \%A \sp 5}} -
{{176} \  { \%A \sp 3}}+
{{448} \  \%A}}, 
\\
\displaystyle
{{2 \  e}+ \%A}, 
\\
\displaystyle
\left.
\left.
{{2 \  f} - \%A} 
\right]
\right],\hbox{\hskip 10.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
\right.
\\
\displaystyle
{{? \sp 8} -
{{12} \  {? \sp 7}}+
{{64} \  {? \sp 6}} -
{{192} \  {? \sp 5}}+
{{432} \  {? \sp 4}} -
{{768} \  {? \sp 3}}+
{{1024} \  {? \sp 2}} -
{{768} \  ?}+
{256}}, 
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{1408} \  a} -
{{19} \  { \%A \sp 7}}+
{{200} \  { \%A \sp 6}} -
{{912} \  { \%A \sp 5}}+
{{2216} \  { \%A \sp 4}} -
\right.
\\
\displaystyle
{{4544} \  { \%A \sp 3}}+
{{6784} \  { \%A \sp 2}} -
{{6976} \  \%A}+
{1792}, 
\\
\displaystyle
{{1408} \  b} -
{{37} \  { \%A \sp 7}}+
{{408} \  { \%A \sp 6}} -
{{1952} \  { \%A \sp 5}}+
{{5024} \  { \%A \sp 4}} -
\\
\displaystyle
{{10368} \  { \%A \sp 3}}+
{{16768} \  { \%A \sp 2}} -
{{17920} \   \%A}+
{5120}, 
\\
\displaystyle
{{1408} \  c}+
{{37} \  { \%A \sp 7}} -
{{408} \  { \%A \sp 6}}+
{{1952} \  { \%A \sp 5}} -
{{5024} \  { \%A \sp 4}}+
\\
\displaystyle
{{10368} \  { \%A \sp 3}} -
{{16768} \  { \%A \sp 2}}+
{{17920} \  \%A} -
{5120}, 
\\
\displaystyle
{{1408} \  d}+
{{19} \  { \%A \sp 7}} -
{{200} \  { \%A \sp 6}}+
{{912} \  { \%A \sp 5}} -
{{2216} \  { \%A \sp 4}}+
\\
\displaystyle
{{4544} \  { \%A \sp 3}} -
{{6784} \  { \%A \sp 2}}+
{{6976} \  \%A} -
{1792}, 
\\
\displaystyle
{{2 \  e}+ \%A}, 
\\
\displaystyle
\left.
\left.
{{2 \  f} - \%A} 
\right]
\right],\hbox{\hskip 10.0cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 8} -
{6 \  {? \sp 7}}+
{{16} \  {? \sp 6}} -
{{24} \  {? \sp 5}}+
{{18} \  {? \sp 4}} -
{8 \  {? \sp 2}}+
4}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{2 \  a}+
{2 \  { \%A \sp 7}} -
{9 \  { \%A \sp 6}}+
{{18} \  { \%A \sp 5}} -
{{19} \  { \%A \sp 4}}+
{4 \  { \%A \sp 3}}+
{{10} \  { \%A \sp 2}} -
{2 \  \%A} -
4},
\right.
\\
\displaystyle
{{2 \  b}+
{2 \  { \%A \sp 7}} -
{9 \  { \%A \sp 6}}+
{{18} \  { \%A \sp 5}} -
{{19} \  { \%A \sp 4}}+
{4 \  { \%A \sp 3}}+
{{10} \  { \%A \sp 2}} -
{4 \  \%A} -
4},
\\
\displaystyle
{{2 \  c} -
{ \%A \sp 7}+
{4 \  { \%A \sp 6}} -
{8 \  { \%A \sp 5}}+
{9 \  { \%A \sp 4}} -
{4 \  { \%A \sp 3}} -
{2 \   \%A}+
4}, 
\\
\displaystyle
{{2 \  d}+
{ \%A \sp 7} -
{4 \  { \%A \sp 6}}+
{8 \  { \%A \sp 5}} -
{9 \  { \%A \sp 4}}+
{4 \  { \%A \sp 3}}+
{2 \  \%A} -
4}, 
\\
\displaystyle
{{2 \  e} -
{2 \  { \%A \sp 7}}+
{9 \  { \%A \sp 6}} -
{{18} \  { \%A \sp 5}}+
{{19} \  { \%A \sp 4}} -
{4 \  { \%A \sp 3}} -
{{10} \  { \%A \sp 2}}+
{4 \  \%A}+
4},
\\
\displaystyle
\left.
\left.
{{2 \  f} -
{2 \  { \%A \sp 7}}+
{9 \  { \%A \sp 6}} -
{{18} \  { \%A \sp 5}}+
{{19} \  {  \%A \sp 4}} -
{4 \  { \%A \sp 3}} -
{{10} \  { \%A \sp 2}}+
{2 \  \%A}+
4} 
\right]
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 4}+{{12} \  {? \sp 2}}+{144}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{12} \  a} -{ \%A \sp 2} -{12}}, 
{{{12} \  b} -{  \%A \sp 2} -{12}}, 
{{{12} \  c} -{ \%A \sp 2} -{12}}, 
\right.
\\
\displaystyle
\left.
\left.
{{{12} \  d} -{  \%A \sp 2} -{12}}, 
{{6 \  e}+{ \%A \sp 2}+{3 \  \%A}+{12}}, 
{{6 \  f}+{  \%A \sp 2} -{3 \  \%A}+{12}} 
\right]
\right],\hbox{\hskip 2.4cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 4}+{6 \  {? \sp 3}}+{{30} \  {? \sp 2}}+{{36} \  ?}+{36}},
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{6 \  a} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{24} \  \%A} -6}, 
{{{30} \  b}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{30} \  \%A}+6}, 
\right.
\\
\displaystyle
{{{30} \  c}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{30} \  \%A}+6}, 
{{{30} \  d}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{30} \  \%A}+6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  e}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{30} \   \%A}+6}, 
{{{30} \  f}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+6} 
\right]
\right],\hbox{\hskip 2.4cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots=
{{? \sp 4} -{6 \  {? \sp 3}}+{{30} \  {? \sp 2}}-{{36} \  ?}+{36}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{6 \  a} -{ \%A \sp 3}+{5 \  {  \%A \sp 2}} -{{24} \  \%A}+6}, 
{{{30} \  b}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{30} \  \%A} -6}, 
\right.
\\
\displaystyle
{{{30} \  c}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{30} \  \%A} -6}, 
{{{30} \  d}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{30} \  \%A} -6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  e}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{30} \  \%A} -6}, 
{{{30} \  f}+{ \%A \sp 3} -{5 \  { \%A \sp 2}} -6} 
\right]
\right],\hbox{\hskip 2.4cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 4}+{{12} \  {? \sp 2}}+{144}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{12} \  a}+{ \%A \sp 2}+{12}}, {{{12} \  b}+{ \%A \sp 2}+{12}}, 
{{{12} \  c}+{ \%A \sp 2}+{12}}, {{{12} \  d}+{ \%A \sp 2}+{12}}, 
\right.
\\
\displaystyle
\left.
\left.
{{6 \  e} -{ \%A \sp 2}+{3 \  \%A} -{12}}, 
{{6 \  f} -{ \%A \sp 2} -{3 \  \%A} -{12}} 
\right]
\right],\hbox{\hskip 3.7cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{12}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ {a -1}, {b -1}, {c -1}, {d -1}, {{2 \  e}+ \%A+4}, {{2 \  f} - \%A+4} 
\right]
\right],\hbox{\hskip 3.7cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2}+{6 \  ?}+6}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ {a+  \%A+5}, {b -1}, {c -1}, {d -1}, {e -1}, {f - \%A -1} 
\right]
\right],\hbox{\hskip 3.9cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{6 \  ?}+6}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ 
{a+ \%A -5}, {b+1}, {c+1}, {d+1}, {e+1}, {f - \%A+1} 
\right]
\right],\hbox{\hskip 3.9cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{12}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ {a+1}, {b+1}, {c+1}, {d+1}, {{2 \  e}+ \%A -4}, {{2 \  f} - \%A -4} 
\right]
\right],\hbox{\hskip 3.3cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 4}+{6 \  {? \sp 3}}+{{30} \  {? \sp 2}}+{{36} \  ?}+{36}},
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{30} \  a} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
{{{30} \  b} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
\right.
\\
\displaystyle
{{{30} \  c} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6}, 
{{6 \  d}+{ \%A \sp 3}+{5 \  { \%A \sp 2}}+{{24} \  \%A}+6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  e} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -6}, 
{{{30} \  f} -{ \%A \sp 3} -{5 \  { \%A \sp 2}} -{{30} \  \%A} -6} 
\right]
\right],\hbox{\hskip 1.7cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 4} -{6 \  {? \sp 3}}+{{30} \  {? \sp 2}} -{{36} \  ?}+{36}}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{{30} \  a} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
{{{30} \  b} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
\right.
\\
\displaystyle
{{{30} \  c} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6}, 
{{6 \  d}+{ \%A \sp 3} -{5 \  { \%A \sp 2}}+{{24} \   \%A} -6}, 
\\
\displaystyle
\left.
\left.
{{{30} \  e} -{ \%A \sp 3}+{5 \  { \%A \sp 2}}+6}, 
{{{30} \  f} -{ \%A \sp 3}+{5 \  { \%A \sp 2}} -{{30} \  \%A}+6} 
\right]
\right],\hbox{\hskip 1.7cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2}+{6 \  ?}+6}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ 
{a+1}, {b+1}, {c+1}, {d - \%A -5}, {e+ \%A+1}, {f+1} 
\right]
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\left.
\begin{array}{@{}l}
\left[ 
complexRoots={{? \sp 2} -{6 \  ?}+6}, 
\right.
\\
\displaystyle
coordinates=
\\
\displaystyle
\left.
\left[ {a -1}, {b -1}, {c -1}, {d - \%A+5}, {e+ \%A -1}, {f -1} 
\right]
\right]\hbox{\hskip 3.5cm}
\end{array}
\right]
$$
\returnType{Type: List Record(complexRoots: SparseUnivariatePolynomial Integer,coordinates: List Polynomial Integer)}

Since the \spadfunFrom{univariateSolve}{ZeroDimensionalSolvePackage}
operation may split a regular set, it returns a list. This explains
the use of \spadfunFrom{concat}{List}.

Look at the last item of the result. It consists of two parts.  For
any complex root {\bf ?} of the univariate polynomial in the first
part, we get a tuple of univariate polynomials (in {\bf a}, ..., 
{\bf f} respectively) by replacing {\bf \%A} by {\bf ?} in the second part.
Each of these tuples {\bf t} describes a point of the variety
associated with {\bf lp} by equaling to zero the polynomials in {\bf t}.

Note that the way of reading these univariate representations is explained also
in the example illustrating the {\tt ZeroDimensionalSolvePackage} constructor.

Now, we compute the points of the variety with real coordinates.

\spadcommand{concat [realSolve(ts)\$zdpack for ts in lts]  }
$$
\left[
{\left[ 
{ \%B{23}}, { \%B{23}}, { \%B{23}}, { \%B{27}}, 
{-{ \%B{27}} -{4 \  { \%B{23}}}}, { \%B{23}} 
\right]},
\right.\hbox{\hskip 3.5cm}
$$
$$
{\left[ 
{ \%B{23}}, { \%B{23}}, { \%B{23}}, { \%B{28}}, 
{-{  \%B{28}} -{4 \  { \%B{23}}}}, { \%B{23}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ 
{ \%B{24}}, { \%B{24}}, { \%B{24}}, { \%B{25}}, 
{-{  \%B{25}} -{4 \  { \%B{24}}}}, { \%B{24}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ 
{ \%B{24}}, { \%B{24}}, { \%B{24}}, { \%B{26}}, 
{-{  \%B{26}} -{4 \  { \%B{24}}}}, { \%B{24}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{29}}, { \%B{29}}, { \%B{29}}, { \%B{29}}, 
{  \%B{33}}, {-{ \%B{33}} -{4 \  { \%B{29}}}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ 
{ \%B{29}}, { \%B{29}}, { \%B{29}}, { \%B{29}}, 
{  \%B{34}}, {-{ \%B{34}} -{4 \  { \%B{29}}}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{30}}, { \%B{30}}, { \%B{30}}, { \%B{30}}, 
{  \%B{31}}, {-{ \%B{31}} -{4 \  { \%B{30}}}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{30}}, { \%B{30}}, { \%B{30}}, { \%B{30}}, 
{  \%B{32}}, {-{ \%B{32}} -{4 \  { \%B{30}}}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{35}}, { \%B{35}}, { \%B{39}}, 
{-{ \%B{39}} -{4 \  {  \%B{35}}}}, { \%B{35}}, { \%B{35}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{35}}, { \%B{35}}, { \%B{40}}, {-{ \%B{40}} -{4 \  { 
 \%B{35}}}}, { \%B{35}}, { \%B{35}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{36}}, { \%B{36}}, { \%B{37}}, {-{ \%B{37}} -{4 \  { 
 \%B{36}}}}, { \%B{36}}, { \%B{36}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{36}}, { \%B{36}}, { \%B{38}}, {-{ \%B{38}} -{4 \  { 
 \%B{36}}}}, { \%B{36}}, { \%B{36}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{41}}, 
\right.
\\
\displaystyle
{ \%B{51}}, 
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{41}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{41}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{41}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{41}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{41}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{41}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{41}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{41}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{41}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{41}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{41}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{41}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{41}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{41}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{41}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{41}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{41}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{41}}}, 
\\
\\
\displaystyle
-{ \%B{51}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{41}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{41}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{41}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{41}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{41}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{41}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{41}}, { \%B{52}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{41}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{41}} \sp {25}}} -
{{\frac{25769893181}{49235160}} \  {{ \%B{41}} \sp {19}}} -
\\
\\
\displaystyle
{{\frac{1975912990729}{3003344760}} \  {{ \%B{41}} \sp {13}}} -
{{\frac{1048460696489}{2002229840}} \  {{ \%B{41}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{41}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{41}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{41}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{41}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{41}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{41}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{41}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{41}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{41}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{41}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{41}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{41}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{41}}}, 
\\
\\
\displaystyle
-{ \%B{52}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{41}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{41}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{41}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{41}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{41}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{41}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{42}}, { \%B{49}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{42}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{42}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{42}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{42}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{42}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{42}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{42}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{42}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{42}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{42}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{42}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{42}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{42}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{42}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{42}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{42}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{42}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{42}}}, 
\\
\\
\displaystyle
-{ \%B{49}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{42}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{42}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{42}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{42}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{42}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{42}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{42}}, { \%B{50}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{42}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{42}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{42}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{42}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{42}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{42}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{42}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{42}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{42}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{42}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{42}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{42}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{42}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{42}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{42}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{42}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{42}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{42}}}, 
\\
\\
\displaystyle
-{ \%B{50}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{42}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{42}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{42}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{42}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{42}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{42}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{43}}, { \%B{47}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{43}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{43}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{43}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{43}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{43}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{43}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{43}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{43}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{43}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{43}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{43}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{43}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{43}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{43}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{43}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{43}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{43}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{43}}}, 
\\
\\
\displaystyle
-{ \%B{47}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{43}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{43}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{43}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{43}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{43}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{43}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{43}}, { \%B{48}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{43}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{43}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{43}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{43}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{43}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{43}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{43}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{43}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{43}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{43}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{43}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{43}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{43}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{43}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{43}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{43}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{43}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{43}}}, 
\\
\\
\displaystyle
-{ \%B{48}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{43}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{43}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{43}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{43}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{43}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{43}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{44}}, { \%B{45}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{44}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{44}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{44}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{44}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{44}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{44}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{44}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{44}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{44}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{44}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{44}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{44}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{44}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{44}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{44}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{44}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{44}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{44}}}, 
\\
\\
\displaystyle
-{ \%B{45}} -{{\frac{4321823003}{1387545279120}} \  {{ \%B{44}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{44}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{44}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{44}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{44}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{44}}}
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{44}}, { \%B{46}}, 
\right.
\\
\\
\displaystyle
{{\frac{7865521}{6006689520}} \  {{ \%B{44}} \sp {31}}} -
{{\frac{6696179241}{2002229840}} \  {{ \%B{44}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{25769893181}{49235160}} \  {{ \%B{44}} \sp {19}}} -
{{\frac{1975912990729}{3003344760}} \  {{ \%B{44}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{1048460696489}{2002229840}} \  {{ \%B{44}} \sp 7}} -
{{\frac{21252634831}{6006689520}} \  { \%B{44}}}, 
\\
\\
\displaystyle
-{{\frac{778171189}{1387545279120}} \  {{ \%B{44}} \sp {31}}}+
{{\frac{1987468196267}{1387545279120}} \  {{ \%B{44}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{155496778477189}{693772639560}} \  {{ \%B{44}} \sp {19}}}+
{{\frac{191631411158401}{693772639560}} \  {{ \%B{44}} \sp {13}}}+
\\
\\
\displaystyle
{{\frac{300335488637543}{1387545279120}} \  {{ \%B{44}} \sp 7}} -
{{\frac{755656433863}{198220754160}} \  { \%B{44}}}, 
\\
\\
\displaystyle
{{\frac{1094352947}{462515093040}} \  {{ \%B{44}} \sp {31}}} -
{{\frac{2794979430821}{462515093040}} \  {{  \%B{44}} \sp {25}}} -
\\
\\
\displaystyle
{{\frac{218708802908737}{231257546520}} \  {{ \%B{44}} \sp {19}}} -
{{\frac{91476663003591}{77085848840}} \  {{ \%B{44}} \sp {13}}} -
\\
\\
\displaystyle
{{\frac{145152550961823}{154171697680}} \  {{ \%B{44}} \sp 7}} -
{{\frac{1564893370717}{462515093040}} \  { \%B{44}}}, 
\\
\\
\displaystyle
-{ \%B{46}} -
{{\frac{4321823003}{1387545279120}} \  {{ \%B{44}} \sp {31}}}+
{{\frac{180949546069}{22746643920}} \  {{ \%B{44}} \sp {25}}}+
\\
\\
\displaystyle
{{\frac{863753195062493}{693772639560}} \  {{ \%B{44}} \sp {19}}}+
{{\frac{1088094456732317}{693772639560}} \  {{ \%B{44}} \sp {13}}}+
\\
\\
\displaystyle
\left.
{{\frac{1732620732685741}{1387545279120}} \  {{ \%B{44}} \sp 7}}+
{{\frac{13506088516033}{1387545279120}} \  { \%B{44}}} 
\right],\hbox{\hskip 3.5cm}
\end{array}
$$
$$
{\left[ { \%B{53}}, { \%B{57}}, {-{ \%B{57}} -{4 \  { \%B{53}}}}, 
{ \%B{53}}, { \%B{53}}, { \%B{53}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{53}}, { \%B{58}}, {-{ \%B{58}} -{4 \  { \%B{53}}}}, 
{ \%B{53}}, { \%B{53}}, { \%B{53}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
{\left[ { \%B{54}}, { \%B{55}}, {-{ \%B{55}} -{4 \  { \%B{54}}}}, 
{ \%B{54}}, { \%B{54}}, { \%B{54}} 
\right]},\hbox{\hskip 3.5cm}
$$
$$
\left.
{\left[ { \%B{54}}, { \%B{56}}, {-{ \%B{56}} -{4 \  { \%B{54}}}}, 
{ \%B{54}}, { \%B{54}}, { \%B{54}} 
\right]}\hbox{\hskip 3.5cm}
\right]
$$
\returnType{Type: List List RealClosure Fraction Integer}

We obtain 24 points given by lists of elements in the {\tt RealClosure} 
of {\tt Fraction} of {\bf R}.  In each list, the first value corresponds 
to the indeterminate {\bf f}, the second to {\bf e} and so on.  See 
{\tt ZeroDimensionalSolvePackage} to learn more about the 
\spadfunFrom{realSolve}{ZeroDimensionalSolvePackage} operation.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LazardSetSolvingPackage}

The {\tt LazardSetSolvingPackage} package constructor solves
polynomial systems by means of Lazard triangular sets.  However one
condition is relaxed: Regular triangular sets whose saturated ideals
have positive dimension are not necessarily normalized.

The decompositions are computed in two steps.  First the algorithm of
Moreno Maza (implemented in the {\tt RegularTriangularSet} domain
constructor) is called.  Then the resulting decompositions are
converted into lists of square-free regular triangular sets and the
redundant components are removed.  Moreover, zero-dimensional regular
triangular sets are normalized.

Note that the way of understanding triangular decompositions 
is detailed in the example of the {\tt RegularTriangularSet}
constructor.

The {\tt LazardSetSolvingPackage} constructor takes six arguments.
The first one, {\bf R}, is the coefficient ring of the polynomials; it
must belong to the category {\tt GcdDomain}.  The second one, {\bf E},
is the exponent monoid of the polynomials; it must belong to the
category {\tt OrderedAbelianMonoidSup}.  the third one, {\bf V}, is
the ordered set of variables; it must belong to the category {\tt
OrderedSet}.  The fourth one is the polynomial ring; it must belong to
the category {\tt RecursivePolynomialCategory(R,E,V)}.  The fifth one
is a domain of the category {\tt RegularTriangularSetCategory(R,E,V,P)} 
and the last one is a domain of
the category {\tt SquareFreeRegularTriangularSetCategory(R,E,V,P)}.
The abbreviation for {\tt LazardSetSolvingPackage} is {\tt LAZM3PK}.

{\bf N.B.} For the purpose of solving zero-dimensional algebraic systems,
see also\\ {\tt LexTriangular\-Package}
and {\tt ZeroDimensionalSolvePackage}.
These packages are easier to call than {\tt LAZM3PK}.
Moreover, the {\tt ZeroDimensionalSolvePackage} 
package  provides operations
to compute either the complex roots or the real roots.

We illustrate now the use of the {\tt LazardSetSolvingPackage} package 
constructor with two examples (Butcher and Vermeer).

Define the coefficient ring.

\spadcommand{R := Integer}
$$
Integer 
$$
\returnType{Type: Domain}

Define the list of variables,

\spadcommand{ls : List Symbol := [b1,x,y,z,t,v,u,w] }
$$
\left[
b1, x, y, z, t, v, u, w 
\right]
$$
\returnType{Type: List Symbol}

and make it an ordered set:

\spadcommand{V := OVAR(ls)}
$$
\mbox{\rm OrderedVariableList [b1,x,y,z,t,v,u,w]} 
$$
\returnType{Type: Domain}

then define the exponent monoid.

\spadcommand{E := IndexedExponents V  }
$$
\mbox{\rm IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w]} 
$$
\returnType{Type: Domain}

Define the polynomial ring.

\spadcommand{P := NSMP(R, V)}
$$
\begin{array}{@{}l}
{\rm NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList [b1,x,y,z,t,v,u,w])} 
\end{array}
$$
\returnType{Type: Domain}

Let the variables be polynomial.

\spadcommand{b1: P := 'b1}
$$
b1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{x: P := 'x  }
$$
x 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{y: P := 'y  }
$$
y 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{z: P := 'z}
$$
z 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{t: P := 't}
$$
t 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{u: P := 'u}
$$
u 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{v: P := 'v}
$$
v 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{w: P := 'w}
$$
w 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

Now call the {\tt RegularTriangularSet} domain constructor.

\spadcommand{T := REGSET(R,E,V,P)}
$$
\begin{array}{@{}l}
{\rm RegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList[b1,x,y,z,t,v,u,w]))}
\end{array}
$$
\returnType{Type: Domain}

Define a polynomial system (the Butcher example).

\spadcommand{p0 := b1 + y + z - t - w}
$$
b1+y+z -t -w 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p1 := 2*z*u + 2*y*v + 2*t*w - 2*w**2 - w - 1}
$$
{2 \  v \  y}+{2 \  u \  z}+{2 \  w \  t} -{2 \  {w \sp 2}} -w -1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p2 := 3*z*u**2 + 3*y*v**2 - 3*t*w**2 + 3*w**3 + 3*w**2 - t + 4*w}
$$
{3 \  {v \sp 2} \  y}+{3 \  {u \sp 2} \  z}+{{\left( -{3 \  {w \sp 2}} -1 
\right)}
\  t}+{3 \  {w \sp 3}}+{3 \  {w \sp 2}}+{4 \  w} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p3 := 6*x*z*v - 6*t*w**2 + 6*w**3 - 3*t*w + 6*w**2 - t + 4*w}
$$
{6 \  v \  z \  x}+{{\left( -{6 \  {w \sp 2}} -{3 \  w} -1 
\right)}
\  t}+{6 \  {w \sp 3}}+{6 \  {w \sp 2}}+{4 \  w} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p4 := 4*z*u**3+ 4*y*v**3+ 4*t*w**3- 4*w**4 - 6*w**3+ 4*t*w- 10*w**2- w- 1}
$$
{4 \  {v \sp 3} \  y}+{4 \  {u \sp 3} \  z}+{{\left( {4 \  {w \sp 3}}+{4 \  
w} 
\right)}
\  t} -{4 \  {w \sp 4}} -{6 \  {w \sp 3}} -{{10} \  {w \sp 2}} -w -1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p5 := 8*x*z*u*v +8*t*w**3 -8*w**4 +4*t*w**2 -12*w**3 +4*t*w -14*w**2 -3*w -1}
$$
{8 \  u \  v \  z \  x}+{{\left( {8 \  {w \sp 3}}+{4 \  {w \sp 2}}+{4 \  w} 
\right)}
\  t} -{8 \  {w \sp 4}} -{{12} \  {w \sp 3}} -{{14} \  {w \sp 2}} -{3 \  w} 
-1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p6 := 12*x*z*v**2+12*t*w**3 -12*w**4 +12*t*w**2 -18*w**3 +8*t*w -14*w**2 -w -1}
$$
{{12} \  {v \sp 2} \  z \  x}+{{\left( {{12} \  {w \sp 3}}+{{12} \  {w \sp 
2}}+{8 \  w} 
\right)}
\  t} -{{12} \  {w \sp 4}} -{{18} \  {w \sp 3}} -{{14} \  {w \sp 2}} -w -1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{p7 := -24*t*w**3 + 24*w**4 - 24*t*w**2 + 36*w**3 - 8*t*w + 26*w**2 + 7*w + 1}
$$
{{\left( -{{24} \  {w \sp 3}} -{{24} \  {w \sp 2}} -{8 \  w} 
\right)}
\  t}+{{24} \  {w \sp 4}}+{{36} \  {w \sp 3}}+{{26} \  {w \sp 2}}+{7 \  w}+1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{lp := [p0, p1, p2, p3, p4, p5, p6, p7]}
$$
\begin{array}{@{}l}
\left[
{b1+y+z -t -w}, 
\right.
\\
\displaystyle
{{2 \  v \  y}+
{2 \  u \  z}+
{2 \  w \  t} -
{2 \  {w \sp 2}} -
w -
1},
\\
\displaystyle
{{3 \  {v \sp 2} \  y}+
{3 \  {u \sp 2} \  z}+
{{\left( -{3 \  {w \sp 2}} -1 \right)}\  t}+
{3 \  {w \sp 3}}+
{3 \  {w \sp 2}}+
{4 \  w}},
\\
\displaystyle
{{6 \  v \  z \  x}+
{{\left( -{6 \  {w \sp 2}} -
{3 \  w} -1 \right)}\  t}+
{6 \  {w \sp 3}}+
{6 \  {w \sp 2}}+
{4 \  w}},
\\
\displaystyle
{{4 \  {v \sp 3} \  y}+
{4 \  {u \sp 3} \  z}+
{{\left( {4 \  {w \sp 3}}+{4 \  w} \right)}\  t} -
{4 \  {w \sp 4}} -
{6 \  {w \sp 3}} -
{{10} \  {w \sp 2}} -
w -
1},
\\
\displaystyle
{{8 \  u \  v \  z \  x}+
{{\left( {8 \  {w \sp 3}}+{4 \  {w \sp 2}}+{4 \  w} \right)}\  t} -
{8 \  {w \sp 4}} -
{{12} \  {w \sp 3}} -
{{14} \  {w \sp 2}} -
{3 \  w} 
-1},
\\
\displaystyle
{{{12} \  {v \sp 2} \  z \  x}+
{{\left( {{12} \  {w \sp 3}}+{{12} \  {w \sp 2}}+{8 \  w} \right)}\  t} -
{{12} \  {w \sp 4}} -
{{18} \  {w \sp 3}} -
{{14} \  {w \sp 2}} -
w -
1},
\\
\displaystyle
\left.
{{{\left( -{{24} \  {w \sp 3}} -{{24} \  {w \sp 2}} -{8 \  w} \right)}\  t}+
{{24} \  {w \sp 4}}+
{{36} \  {w \sp 3}}+
{{26} \  {w \sp 2}}+
{7 \  w}+
1} 
\right]
\end{array}
$$
\returnType{Type: List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

First of all, let us solve this system in the sense of Lazard by means
of the {\tt REGSET} constructor:

\spadcommand{lts := zeroSetSplit(lp,false)\$T}
$$
\begin{array}{@{}l}
\left[
{\left\{ {w+1}, u, v, {t+1}, {b1+y+z+2} \right\}},
{\left\{ {w+1}, v, {t+1}, z, {b1+y+2} \right\}},
\right.
\\
\displaystyle
{\left\{ {w+1}, {t+1}, z, y, {b1+2} \right\}},
{\left\{ {w+1}, {v -u}, {t+1}, {y+z}, x, {b1+2} \right\}},
\\
\displaystyle
{\left\{ {w+1}, u, {t+1}, y, x, {b1+z+2} \right\}},
\\
\displaystyle
\left\{ 
{{{144} \  {w \sp 5}}+{{216} \  {w \sp 4}}+{{96} \  {w \sp 3}}+{6 
\  {w \sp 2}} -{{11} \  w} -1}, 
\right.
\\
\displaystyle
{{{\left( {{12} \  {w \sp 2}}+{9 \  w}+1 \right)}\  u} -
{{72} \  {w \sp 5}} -
{{108} \  {w \sp 4}} -
{{42} \  {w \sp 3}} -
{9 \  {w \sp 2}} -
{3 \  w}}, 
\\
\displaystyle
{{{\left( {{12} \  {w \sp 2}}+{9 \  w}+1 \right)}\  v}+
{{36} \  {w \sp 4}}+
{{54} \  {w \sp 3}}+
{{18} \  {w \sp 2}}}, 
\\
\displaystyle
{{{\left( {{24} \  {w \sp 3}}+{{24} \  {w \sp 2}}+{8 \  w} \right)}\  t} -
{{24} \  {w \sp 4}} -
{{36} \  {w \sp 3}} -
{{26} \  {w \sp 2}} -
{7 \  w} -1}, 
\\
\displaystyle
{{\left( {{12} \  u \  v} -{{12} \  {u \sp 2}} \right)}\  z}+
{{\left( {{12} \  w \  v}+{{12} \  {w \sp 2}}+4 \right)}\  t}+
{{\left( {3 \  w} -5 \right)}\  v}+
\\
\displaystyle
\ \ {{36} \  {w \sp 4}}+
{{42} \  {w \sp 3}}+
{6 \  {w \sp 2}} -
{{16} \  w}, 
\\
\displaystyle
{{2 \  v \  y}+
{2 \  u \  z}+
{2 \  w \  t} -
{2 \  {w \sp 2}} -
w -1}, 
\\
\displaystyle
\left.
\left.
{{6 \  v \  z \  x}+
{{\left( -{6 \  {w \sp 2}} -{3 \  w} -1 \right)}\  t}+
{6 \  {w \sp 3}}+
{6 \  {w \sp 2}}+
{4 \  w}}, 
{b1+y+z -t -w} 
\right\}
\right]
\end{array}
$$
\returnType{Type: List 
RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],
OrderedVariableList [b1,x,y,z,t,v,u,w],
NewSparseMultivariatePolynomial(
Integer,OrderedVariableList [b1,x,y,z,t,v,u,w]))}

We can get the dimensions of each component
of a decomposition as follows.

\spadcommand{[coHeight(ts) for ts in lts] }
$$
\left[
3, 3, 3, 2, 2, 0 
\right]
$$
\returnType{Type: List NonNegativeInteger}

The first five sets have a simple shape.  However, the last one, which
has dimension zero, can be simplified by using Lazard triangular sets.

Thus we call the {\tt SquareFreeRegularTriangularSet} domain constructor,

\spadcommand{ST := SREGSET(R,E,V,P)}
$$
\begin{array}{@{}l}
{\rm SquareFreeRegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList[b1,x,y,z,t,v,u,w]))} 
\end{array}
$$
\returnType{Type: Domain}

and set the {\tt LAZM3PK} package constructor to our situation.

\spadcommand{pack := LAZM3PK(R,E,V,P,T,ST)}
$$
\begin{array}{@{}l}
{\rm LazardSetSolvingPackage(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList[b1,x,y,z,t,v,u,w]),}
\\
\displaystyle
{\rm \ \ RegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList[b1,x,y,z,t,v,u,w])),}
\\
\displaystyle
{\rm \ \ SquareFreeRegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [b1,x,y,z,t,v,u,w],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList[b1,x,y,z,t,v,u,w])))} 
\end{array}
$$
\returnType{Type: Domain}

We are ready to solve the system by means of Lazard triangular sets:

\spadcommand{zeroSetSplit(lp,false)\$pack}
$$
\begin{array}{@{}l}
\left[
{\left\{ {w+1}, {t+1}, z, y, {b1+2} \right\}},
\right.
\\
\displaystyle
{\left\{ {w+1}, v, {t+1}, z, {b1+y+2} \right\}},
\\
\displaystyle
{\left\{ {w+1}, u, v, {t+1}, {b1+y+z+2} \right\}},
\\
\displaystyle
{\left\{ {w+1}, {v -u}, {t+1}, {y+z}, x, {b1+2} \right\}},
\\
\displaystyle
{\left\{ {w+1}, u, {t+1}, y, x, {b1+z+2} \right\}},
\\
\displaystyle
\left\{ 
{{{144} \  {w \sp 5}}+
{{216} \  {w \sp 4}}+
{{96} \  {w \sp 3}}+
{6 \  {w \sp 2}} -
{{11} \  w} -1}, 
\right.
\\
\displaystyle
{u -{{24} \  {w \sp 4}} -
{{36} \  {w \sp 3}} -
{{14} \  {w \sp 2}}+w+1}, 
\\
\displaystyle
{{3 \  v} -{{48} \  {w \sp 4}} -
{{60} \  {w \sp 3}} -
{{10} \  {w \sp 2}}+
{8 \  w}+2}, 
\\
\displaystyle
{t -{{24} \  {w \sp 4}} -
{{36} \  {w \sp 3}} -
{{14} \  {w \sp 2}} -w+1}, 
{{486} \  z} -
{{2772} \  {w \sp 4}} -
\\
\displaystyle
\ \ {{4662} \  {w \sp 3}} -
{{2055} \  {w \sp 2}}+
{{30} \  w}+{127}, 
\\
\displaystyle
{{{2916} \  y} -
{{22752} \  {w \sp 4}} -
{{30312} \  {w \sp 3}} -
{{8220} \  {w \sp 2}}+
{{2064} \  w}+{1561}}, 
\\
\displaystyle
{{{356} \  x} -
{{3696} \  {w \sp 4}} -
{{4536} \  {w \sp 3}} -
{{968} \  {w \sp 2}}+
{{822} \  w}+{371}}, 
\\
\displaystyle
\left.
\left.
{{{2916} \  b1} -
{{30600} \  {w \sp 4}} -
{{46692} \  {w \sp 3}} -
{{20274} \  {w \sp 2}} -
{{8076} \  w}+{593}} 
\right\}
\right]
\end{array}
$$
\returnType{Type: List 
SquareFreeRegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],
OrderedVariableList [b1,x,y,z,t,v,u,w],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [b1,x,y,z,t,v,u,w]))}

We see the sixth triangular set is {\em nicer} now: each one of its
polynomials has a constant initial.

We follow with the Vermeer example. The ordering is the usual one
for this system.

Define the polynomial system.

\spadcommand{f0 := (w - v) ** 2 + (u - t) ** 2 - 1}
$$
{t \sp 2} -{2 \  u \  t}+{v \sp 2} -{2 \  w \  v}+{u \sp 2}+{w \sp 2} -1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{f1 := t ** 2 - v ** 3}
$$
{t \sp 2} -{v \sp 3} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{f2 := 2 * t * (w - v) + 3 * v ** 2 * (u - t)}
$$
{{\left( -{3 \  {v \sp 2}} -{2 \  v}+{2 \  w} 
\right)}
\  t}+{3 \  u \  {v \sp 2}} 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{f3 := (3 * z * v ** 2 - 1) * (2 * z * t - 1)}
$$
{6 \  {v \sp 2} \  t \  {z \sp 2}}+{{\left( -{2 \  t} -{3 \  {v \sp 2}} 
\right)}
\  z}+1 
$$
\returnType{Type: NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

\spadcommand{lf := [f0, f1, f2, f3]}
$$
\begin{array}{@{}l}
\left[
{{t \sp 2} -{2 \  u \  t}+{v \sp 2} -{2 \  w \  v}+{u \sp 2}+{w \sp 2} -1}, 
\right.
\\
\displaystyle
{{t \sp 2} -{v \sp 3}}, 
\\
\displaystyle
{{{\left( -{3 \  {v \sp 2}} -{2 \  v}+{2 \  w} \right)}\  t}+
{3 \  u \  {v \sp 2}}}, 
\\
\displaystyle
\left.
{{6 \  {v \sp 2} \  t \  {z \sp 2}}+
{{\left( -{2 \  t} -{3 \  {v \sp 2}}\right)}\  z}+1} 
\right]
\end{array}
$$
\returnType{Type: List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [b1,x,y,z,t,v,u,w])}

First of all, let us solve this system in the sense of Kalkbrener by
means of the {\tt REGSET} constructor:

\spadcommand{zeroSetSplit(lf,true)\$T}
$$
\begin{array}{@{}l}
\left[
\left\{ 
{{729} \  {u \sp 6}}+
{{\left( 
-{{1458} \  {w \sp 3}}+
{{729} \  {w \sp 2}} -
{{4158} \  w} -{1685} 
\right)}\  {u \sp 4}}+
\right.
\right.
\\
\displaystyle
{{\left( {{729} \  {w \sp 6}} -
{{1458} \  {w \sp 5}} -{{2619} \  {w \sp 4}} -
{{4892} \  {w \sp 3}} -{{297} \  {w \sp 2}}+
{{5814} \  w}+{427} 
\right)}\  {u \sp 2}}+
\\
\displaystyle
{{729} \  {w \sp 8}}+
{{216} \  {w \sp 7}} -
{{2900} \  {w \sp 6}} -
{{2376} \  {w \sp 5}}+
{{3870} \  {w \sp 4}}+
\\
\displaystyle
\ \ {{4072} \  {w \sp 3}} -
{{1188} \  {w \sp 2}} -
{{1656} \  w}+{529}, 
\\
\displaystyle
\left( 
{{2187} \  {u \sp 4}}+
\left( 
-{{4374} \  {w \sp 3}} -
{{972} \  {w \sp 2}} -
{{12474} \  w} 
-{2868} 
\right)\  {u \sp 2}+
\right.
\\
\displaystyle
\left.
{{2187} \  {w \sp 6}} -
{{1944} \  {w \sp 5}} -
{{10125} \  {w \sp 4}} -
{{4800} \  {w \sp 3}}+
{{2501} \  {w \sp 2}}+
{{4968} \  w} -{1587} 
\right)\  v+
\\
\displaystyle
\left( 
{{1944} \  {w \sp 3}} -
{{108} \  {w \sp 2}} 
\right)\  {u \sp 2}+
\\
\displaystyle
{{972} \  {w \sp 6}}+
{{3024} \  {w \sp 5}} -
{{1080} \  {w \sp 4}}+
{{496} \  {w \sp 3}}+
{{1116} \  {w \sp 2}}, 
\\
\displaystyle
{{{\left( 
{3 \  {v \sp 2}}+
{2 \  v} -
{2 \  w} 
\right)}\  t} -
{3 \  u \  {v \sp 2}}}, 
\\
\displaystyle
\left.
\left.
\left( 
\left( 
{4 \  v} -{4 \  w} 
\right)\  t -
{6 \  u \  {v \sp 2}} 
\right)\  {z \sp 2}+
\left( 
{2 \  t}+
{3 \  {v \sp 2}} 
\right)
\  z -1 
\right\}
\right]
\end{array}
$$
\returnType{Type: List 
RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],
OrderedVariableList [b1,x,y,z,t,v,u,w],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [b1,x,y,z,t,v,u,w]))}

We have obtained one regular chain (i.e. regular triangular set) with
dimension 1.  This set is in fact a characterist set of the (radical
of) of the ideal generated by the input system {\bf lf}.  Thus we have
only the {\em generic points} of the variety associated with {\bf lf}
(for the elimination ordering given by {\bf ls}).

So let us get now a full description of this variety.

Hence, we solve this system in the sense of Lazard by means of the {\tt REGSET}
constructor:

\spadcommand{zeroSetSplit(lf,false)\$T}
$$
\begin{array}{@{}l}
\left[
\left\{ 
{{729} \  {u \sp 6}}+
\left( 
-{{1458} \  {w \sp 3}}+
{{729} \  {w \sp 2}} -
{{4158} \  w} -
{1685} 
\right)\  {u \sp 4}+
\right.
\right.
\\
\displaystyle
\left( 
{{729} \  {w \sp 6}} -
{{1458} \  {w \sp 5}} -
{{2619} \  {w \sp 4}} -
{{4892} \  {w \sp 3}} -
{{297} \  {w \sp 2}}+
{{5814} \  w}+
{427} 
\right)\  {u \sp 2}+
\\
\displaystyle
{{729} \  {w \sp 8}}+
{{216} \  {w \sp 7}} -
{{2900} \  {w \sp 6}} -
{{2376} \  {w \sp 5}}+
{{3870} \  {w \sp 4}}+
{{4072} \  {w \sp 3}} -
\\
\displaystyle
{{1188} \  {w \sp 2}} -
{{1656} \  w}+
{529}, 
\\
\displaystyle
\left( 
{{2187} \  {u \sp 4}}+
\left( 
-{{4374} \  {w \sp 3}} -
{{972} \  {w \sp 2}} -
{{12474} \  w} -
{2868} 
\right)\  {u \sp 2}+
\right.
\\
\displaystyle
\left.
{{2187} \  {w \sp 6}} -
{{1944} \  {w \sp 5}} -
{{10125} \  {w \sp 4}} -
{{4800} \  {w \sp 3}}+
{{2501} \  {w \sp 2}}+
{{4968} \  w} -
{1587} 
\right)\  v+
\\
\displaystyle
\left( 
{{1944} \  {w \sp 3}} -
{{108} \  {w \sp 2}} 
\right)\  {u \sp 2}+
\\
\displaystyle
{{972} \  {w \sp 6}}+
{{3024} \  {w \sp 5}} -
{{1080} \  {w \sp 4}}+
{{496} \  {w \sp 3}}+
{{1116} \  {w \sp 2}}, 
\\
\displaystyle
\left( 
{3 \  {v \sp 2}}+
{2 \  v} -
{2 \  w} 
\right)\  t -
{3 \  u \  {v \sp 2}}, 
\\
\displaystyle
\left.
\left( 
\left( 
{4 \  v} -
{4 \  w} 
\right)\  t -
{6 \  u \  {v \sp 2}} 
\right)\  {z \sp 2}+
\left( 
{2 \  t}+
{3 \  {v \sp 2}} 
\right)
\  z -1
\right\},
\\
\displaystyle
\left\{ 
{{27} \  {w \sp 4}}+
{4 \  {w \sp 3}} -
{{54} \  {w \sp 2}} -
{{36} \  w}+
{23}, 
\right.
\\
\displaystyle
u, 
\\
\displaystyle
\left( 
{{12} \  w}+
2 
\right)\  v -
{9 \  {w \sp 2}} -
{2 \  w}+
9, 
\\
\displaystyle
{6 \  {t \sp 2}} -
{2 \  v} -
{3 \  {w \sp 2}}+
{2 \  w}+3, 
\\
\displaystyle
\left.
{{2 \  t \  z} -1}
\right\},
\\
\displaystyle
\left\{ 
{{{59049} \  {w \sp 6}}+
{{91854} \  {w \sp 5}} -
{{45198} \  {w \sp 4}}+
{{145152} \  {w \sp 3}}+
{{63549} \  {w \sp 2}}+
{{60922} \  w}+{21420}}, 
\right.
\\
\displaystyle
\left( 
{{31484448266904} \  {w \sp 5}} -
{{18316865522574} \  {w \sp 4}}+
{{23676995746098} \  {w \sp 3}}+
{{6657857188965} \  {w \sp 2}}+
\right.
\\
\displaystyle
\left.
{{8904703998546} \  w}+
{3890631403260} 
\right)\  {u \sp 2}+
{{94262810316408} \  {w \sp 5}} -
{{82887296576616} \  {w \sp 4}}+
\\
\displaystyle
{{89801831438784} \  {w \sp 3}}+
{{28141734167208} \  {w \sp 2}}+
{{38070359425432} \  w}+
{16003865949120},
\\
\displaystyle
\left( 
{{243} \  {w \sp 2}}+
{{36} \  w}+
{85} 
\right)\  {v \sp 2}+
\left( 
-{{81} \  {u \sp 2}} -
{{162} \  {w \sp 3}}+
{{36} \  {w \sp 2}}+
{{154} \  w}+
{72} 
\right)\  v -
{{72} \  {w \sp 3}}+
{4 \  {w \sp 2}}, 
\\
\displaystyle
\left( 
{3 \  {v \sp 2}}+
{2 \  v} -
{2 \  w} 
\right)\  t -
{3 \  u \  {v \sp 2}}, 
\\
\displaystyle
\left.
\left( 
\left( 
{4 \  v} -
{4 \  w} 
\right)\  t -
{6 \  u \  {v \sp 2}} 
\right)\  {z \sp 2}+
\left( {2 \  t}+
{3 \  {v \sp 2}} 
\right)\  z
-1
\right\},
\\
\displaystyle
\left\{ 
{{{27} \  {w \sp 4}}+
{4 \  {w \sp 3}} -
{{54} \  {w \sp 2}} -
{{36} \  w}+
{23}}, u, 
\right.
\\
\displaystyle
{{{\left( 
{{12} \  w}+
2 
\right)}\  v} -
{9 \  {w \sp 2}} -
{2 \  w}+9}, 
\\
\displaystyle
{{6 \  {t \sp 2}} -
{2 \  v} -{3 \  {w \sp 2}}+
{2 \  w}+
3}, 
\\
\displaystyle
\left.
\left.
{{3 \  {v \sp 2} \  z} 
-1}
\right\}
\right]
\end{array}
$$
\returnType{Type: List 
RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],
OrderedVariableList [b1,x,y,z,t,v,u,w],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [b1,x,y,z,t,v,u,w]))}

We retrieve our regular chain of dimension 1 and we get three regular
chains of dimension 0 corresponding to the {\em degenerated cases}.
We want now to simplify these zero-dimensional regular chains by using
Lazard triangular sets.  Moreover, this will allow us to prove that
the above decomposition has no redundant component.  {\bf N.B.}
Generally, decompositions computed by the {\tt REGSET} constructor do
not have redundant components.  However, to be sure that no redundant
component occurs one needs to use the {\tt SREGSET} or {\tt LAZM3PK}
constructors.

So let us solve the input system in the sense of Lazard by means of
the {\tt LAZM3PK} constructor:

\spadcommand{zeroSetSplit(lf,false)\$pack  }
$$
\begin{array}{@{}l}
\left[
\left\{ 
{{729} \  {u \sp 6}}+
\left( 
-{{1458} \  {w \sp 3}}+
{{729} \  {w \sp 2}} -
{{4158} \  w} -
{1685} 
\right)\  {u \sp 4}+
\right.
\right.
\\
\displaystyle
\ \ \left( 
{{729} \  {w \sp 6}} -
{{1458} \  {w \sp 5}} -
{{2619} \  {w \sp 4}} -
{{4892} \  {w \sp 3}} -
{{297} \  {w \sp 2}}+
{{5814} \  w}+{427} 
\right)\  {u \sp 2}+
\\
\displaystyle
\ \ {{729} \  {w \sp 8}}+
{{216} \  {w \sp 7}} -
{{2900} \  {w \sp 6}} -
{{2376} \  {w \sp 5}}+
{{3870} \  {w \sp 4}}+
{{4072} \  {w \sp 3}} -
\\
\displaystyle
\ \ {{1188} \  {w \sp 2}} -
{{1656} \  w}+{529}, 
\\
\displaystyle
\left( 
{{2187} \  {u \sp 4}}+
\left( 
-{{4374} \  {w \sp 3}} -
{{972} \  {w \sp 2}} -
{{12474} \  w} 
-{2868} 
\right)\  {u \sp 2}+
\right.
\\
\displaystyle
\left.
\ \ {{2187} \  {w \sp 6}} -
{{1944} \  {w \sp 5}} -
{{10125} \  {w \sp 4}} -
{{4800} \  {w \sp 3}}+
{{2501} \  {w \sp 2}}+
{{4968} \  w} -
{1587} 
\right)\  v+
\\
\displaystyle
\left( 
{{1944} \  {w \sp 3}} -
{{108} \  {w \sp 2}} 
\right)\  {u \sp 2}+
{{972} \  {w \sp 6}}+
{{3024} \  {w \sp 5}} -
{{1080} \  {w \sp 4}}+
{{496} \  {w \sp 3}}+
{{1116} \  {w \sp 2}}, 
\\
\displaystyle
\left( 
{3 \  {v \sp 2}}+
{2 \  v} -
{2 \  w} 
\right)\  t -
{3 \  u \  {v \sp 2}}, 
\\
\displaystyle
\left.
\left( 
\left( 
{4 \  v} -
{4 \  w} 
\right)\  t -
{6 \  u \  {v \sp 2}} 
\right)\  {z \sp 2}+
\left( 
{2 \  t}+
{3 \  {v \sp 2}} 
\right)\  z -1 
\right\},
\\
\displaystyle
\left\{ 
{{81} \  {w \sp 2}}+
{{18} \  w}+
{28}, 
{{729} \  {u \sp 2}} -
{{1890} \  w} -
{533}, 
{{81} \  {v \sp 2}}+
\left( 
-{{162} \  w}+
{27} 
\right)\  v -
\right.
\\
\displaystyle
{{72} \  w} -
{112}, 
\\
\displaystyle
{{{11881} \  t}+
\left( {{972} \  w}+{2997} 
\right)\  u \  v+
{{\left( -{{11448} \  w} -{11536} 
\right)}\  u}}, 
\\
\displaystyle
{{641237934604288} \  {z \sp 2}}+
\left( 
\left( 
\left( 
{{78614584763904} \  w}+
{26785578742272} 
\right)\  u+
\right.
\right.
\\
\displaystyle
\left.
\ \ {{236143618655616} \  w}+
{70221988585728} 
\right)\  v+
\left( 
{{358520253138432} \  w}+
\right.
\\
\displaystyle
\left.
\left.
\ \ {101922133759488} 
\right)\  u+
{{142598803536000} \  w}+
{54166419595008} 
\right)\  z+
\\
\displaystyle
\ \ \left( 
{{32655103844499} \  w} -
{44224572465882} 
\right)\  u \  v+
\\
\displaystyle
\left.
\left( 
{{43213900115457} \  w} -
{32432039102070} 
\right)\  u 
\right\},
\\
\displaystyle
\left\{ 
{{27} \  {w \sp 4}}+
{4 \  {w \sp 3}} -
{{54} \  {w \sp 2}} -
{{36} \  w}+
{23}, 
u, 
{{218} \  v} -
{{162} \  {w \sp 3}}+
{3 \  {w \sp 2}}+
{{160} \  w}+
{153}, 
\right.
\\
\displaystyle
\ \ {{109} \  {t \sp 2}} -
{{27} \  {w \sp 3}} -
{{54} \  {w \sp 2}}+
{{63} \  w}+
{80}, 
\\
\displaystyle
\left.
\ \ {{1744} \  z}+
\left( 
-{{1458} \  {w \sp 3}}+
{{27} \  {w \sp 2}}+
{{1440} \  w}+
{505} 
\right)\  t 
\right\},
\\
\displaystyle
\left\{ 
{{27} \  {w \sp 4}}+
{4 \  {w \sp 3}} -
{{54} \  {w \sp 2}} -
{{36} \  w}+{23}, 
u, 
{{218} \  v} -
{{162} \  {w \sp 3}}+
{3 \  {w \sp 2}}+
{{160} \  w}+
{153}, 
\right.
\\
\displaystyle
\left.
\ \ {{109} \  {t \sp 2}} -
{{27} \  {w \sp 3}} -
{{54} \  {w \sp 2}}+
{{63} \  w}+{80}, 
{{1308} \  z}+
{{162} \  {w \sp 3}} -
{3 \  {w \sp 2}} -
{{814} \  w} -
{153} 
\right\},
\\
\displaystyle
\left\{ 
{{729} \  {w \sp 4}}+
{{972} \  {w \sp 3}} -
{{1026} \  {w \sp 2}}+
{{1684} \  w}+
{765}, 
{{81} \  {u \sp 2}}+
{{72} \  {w \sp 2}}+
{{16} \  w} -{72}, 
\right.
\\
\displaystyle
\ \ {{702} \  v} -
{{162} \  {w \sp 3}} -
{{225} \  {w \sp 2}}+
{{40} \  w} -
{99}, 
\\
\displaystyle
\ \ {{11336} \  t}+
\left( 
{{324} \  {w \sp 3}} -
{{603} \  {w \sp 2}} -
{{1718} \  w} -
{1557} 
\right)\  u, 
\\
\displaystyle
\ \ {{595003968} \  {z \sp 2}}+
\left( 
\left( 
-{{963325386} \  {w \sp 3}} -
{{898607682} \  {w \sp 2}}+
{{1516286466} \  w} -
\right.
\right.
\\
\displaystyle
\left.
\ \ {3239166186} 
\right)\  u -
{{1579048992} \  {w \sp 3}} -
{{1796454288} \  {w \sp 2}}+
{{2428328160} \  w} -
\\
\displaystyle
\left.
{4368495024} 
\right)\  z+
\left( 
{{9713133306} \  {w \sp 3}}+
{{9678670317} \  {w \sp 2}} -
{{16726834476} \  w}+
\right.
\\
\displaystyle
\left.
\left.
\left.
{28144233593} 
\right)\  u
\right\}
\right]
\end{array}
$$
\returnType{Type: List 
SquareFreeRegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [b1,x,y,z,t,v,u,w],
OrderedVariableList [b1,x,y,z,t,v,u,w],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [b1,x,y,z,t,v,u,w]))}

Due to square-free factorization, we obtained now four
zero-dimensional regular chains.  Moreover, each of them is normalized
(the initials are constant).  Note that these zero-dimensional
components may be investigated further with the \\
{\tt ZeroDimensionalSolvePackage} package constructor.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Library}
 
The {\tt Library} domain provides a simple way to store Axiom values
in a file.  This domain is similar to {\tt KeyedAccessFile} but fewer
declarations are needed and items of different types can be saved
together in the same file.

To create a library, you supply a file name.

\spadcommand{stuff := library "/tmp/Neat.stuff" }
$$
\mbox{\tt "/tmp/Neat.stuff"} 
$$
\returnType{Type: Library}

Now values can be saved by key in the file.
The keys should be mnemonic, just as the field names are for records.
They can be given either as strings or symbols.

\spadcommand{stuff.int := 32**2}
$$
1024 
$$
\returnType{Type: PositiveInteger}

\spadcommand{stuff."poly" := x**2 + 1}
$$
{x \sp 2}+1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{stuff.str := "Hello"}
$$
\mbox{\tt "Hello"} 
$$
\returnType{Type: String}

You obtain the set of available keys using the 
\spadfunFrom{keys}{Library} operation.

\spadcommand{keys stuff}
$$
\left[
\mbox{\tt "str"} , \mbox{\tt "poly"} , \mbox{\tt "int"} 
\right]
$$
\returnType{Type: List String}

%Original Page 394

You extract values  by giving the desired key in this way.

\spadcommand{stuff.poly}
$$
{x \sp 2}+1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{stuff("poly")}
$$
{x \sp 2}+1 
$$
\returnType{Type: Polynomial Integer}

When the file is no longer needed, you should remove it from the
file system.

\spadcommand{)system rm -rf /tmp/Neat.stuff  }
 
For more information on related topics, see 
\domainref{File}, \domainref{TextFile}, and \domainref{KeyedAccessFile}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LieExponentials}

\spadcommand{ a: Symbol := 'a }
$$
a 
$$
\returnType{Type: Symbol}

\spadcommand{ b: Symbol := 'b }
$$
b 
$$
\returnType{Type: Symbol}

Declarations of domains

\spadcommand{ coef     := Fraction(Integer) }
$$
\mbox{\rm Fraction Integer} 
$$
\returnType{Type: Domain}

\spadcommand{ group    := LieExponentials(Symbol, coef, 3)  }
$$
\mbox{\rm LieExponentials(Symbol,Fraction Integer,3)} 
$$
\returnType{Type: Domain}

\spadcommand{ lpoly    := LiePolynomial(Symbol, coef)  }
$$
\mbox{\rm LiePolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{ poly     := XPBWPolynomial(Symbol, coef)  }
$$
\mbox{\rm XPBWPolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

Calculations

\spadcommand{ ea := exp(a::lpoly)\$group}
$$
e \sp {\left[ a 
\right]}
$$
\returnType{Type: LieExponentials(Symbol,Fraction Integer,3)}

\spadcommand{ eb := exp(b::lpoly)\$group}
$$
e \sp {\left[ b 
\right]}
$$
\returnType{Type: LieExponentials(Symbol,Fraction Integer,3)}

\spadcommand{ g: group := ea*eb}
$$
{e \sp {\left[ b 
\right]}}
\  {e \sp {\left( {\frac{1}{2}} \  {\left[ a \  {b \sp 2} 
\right]}
\right)}}
\  {e \sp {\left[ a \  b 
\right]}}
\  {e \sp {\left( {\frac{1}{2}} \  {\left[ {a \sp 2} \  b 
\right]}
\right)}}
\  {e \sp {\left[ a 
\right]}}
$$
\returnType{Type: LieExponentials(Symbol,Fraction Integer,3)}

\spadcommand{ g :: poly  }
$$
\begin{array}{@{}l}
1+
{\left[ a \right]}+
{\left[b \right]}+
{{\frac{1}{2}} \  {\left[ a \right]}\  {\left[ a \right]}}+
{\left[a \  b \right]}+
{{\left[b \right]}\  {\left[ a \right]}}+
{{\frac{1}{2}} \  {\left[ b \right]}\  {\left[ b \right]}}+
{{\frac{1}{6}} \  {\left[ a \right]}\  {\left[ a \right]}\  
{\left[ a \right]}}+
{{\frac{1}{2}} \  {\left[ {a \sp 2} \  b \right]}}+
\\
\\
\displaystyle
{{\left[a \  b \right]}\  {\left[ a \right]}}+
{{\frac{1}{2}} \  {\left[ a \  {b \sp 2} \right]}}+
{{\frac{1}{2}} \  {\left[ b \right]}\  {\left[ a \right]}\  
{\left[ a \right]}}+
{{\left[b \right]}\  {\left[ a \  b \right]}}+
{{\frac{1}{2}} \  {\left[ b \right]}\  {\left[ b \right]}\  
{\left[ a \right]}}+
{{\frac{1}{6}} \  {\left[ b \right]}\  {\left[ b \right]}\  {\left[ b \right]}}
\end{array}
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{ log(g)\$group  }
$$
{\left[ a 
\right]}+{\left[
b 
\right]}+{{\frac{1}{2}} \  {\left[ a \  b 
\right]}}+{{\frac{1}{12}} \  {\left[ {a \sp 2} \  b 
\right]}}+{{\frac{1}{12}} \  {\left[ a \  {b \sp 2} 
\right]}}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{ g1: group := inv(g)   }
$$
{e \sp {\left( -{\left[ b 
\right]}
\right)}}
\  {e \sp {\left( -{\left[ a 
\right]}
\right)}}
$$
\returnType{Type: LieExponentials(Symbol,Fraction Integer,3)}

\spadcommand{ g*g1  }
$$
1 
$$
\returnType{Type: LieExponentials(Symbol,Fraction Integer,3)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LiePolynomial}

Declaration of domains

\spadcommand{RN    := Fraction Integer }
$$
\mbox{\rm Fraction Integer} 
$$
\returnType{Type: Domain}

\spadcommand{Lpoly := LiePolynomial(Symbol,RN)  }
$$
\mbox{\rm LiePolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{Dpoly := XDPOLY(Symbol,RN)  }
$$
\mbox{\rm XDistributedPolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{Lword := LyndonWord Symbol }
$$
\mbox{\rm LyndonWord Symbol} 
$$
\returnType{Type: Domain}

Initialisation

\spadcommand{a:Symbol := 'a }
$$
a 
$$
\returnType{Type: Symbol}

\spadcommand{b:Symbol := 'b }
$$
b 
$$
\returnType{Type: Symbol}

\spadcommand{c:Symbol := 'c }
$$
c 
$$
\returnType{Type: Symbol}

\spadcommand{aa: Lpoly := a   }
$$
\left[
a 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{bb: Lpoly := b   }
$$
\left[
b 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{cc: Lpoly := c   }
$$
\left[
c 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{p : Lpoly := [aa,bb]}
$$
\left[
a \  b 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{q : Lpoly := [p,bb]}
$$
\left[
a \  {b \sp 2} 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

All the Lyndon words of order 4

\spadcommand{liste : List Lword := LyndonWordsList([a,b], 4)}
$$
\left[
{\left[ a 
\right]},
{\left[ b 
\right]},
{\left[ a \  b 
\right]},
{\left[ {a \sp 2} \  b 
\right]},
{\left[ a \  {b \sp 2} 
\right]},
{\left[ {a \sp 3} \  b 
\right]},
{\left[ {a \sp 2} \  {b \sp 2} 
\right]},
{\left[ a \  {b \sp 3} 
\right]}
\right]
$$
\returnType{Type: List LyndonWord Symbol}

\spadcommand{r: Lpoly := p + q + 3*LiePoly(liste.4)\$Lpoly}
$$
{\left[ a \  b 
\right]}+{3
\  {\left[ {a \sp 2} \  b 
\right]}}+{\left[
a \  {b \sp 2} 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{s:Lpoly := [p,r]}
$$
-{3 \  {\left[ {a \sp 2} \  b \  a \  b 
\right]}}+{\left[
a \  b \  a \  {b \sp 2} 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{t:Lpoly  := s  + 2*LiePoly(liste.3) - 5*LiePoly(liste.5)}
$$
{2 \  {\left[ a \  b 
\right]}}
-{5 \  {\left[ a \  {b \sp 2} 
\right]}}
-{3 \  {\left[ {a \sp 2} \  b \  a \  b 
\right]}}+{\left[
a \  b \  a \  {b \sp 2} 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{degree t }
$$
5 
$$
\returnType{Type: PositiveInteger}

\spadcommand{mirror t }
$$
-{2 \  {\left[ a \  b 
\right]}}
-{5 \  {\left[ a \  {b \sp 2} 
\right]}}
-{3 \  {\left[ {a \sp 2} \  b \  a \  b 
\right]}}+{\left[
a \  b \  a \  {b \sp 2} 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

Jacobi Relation

\spadcommand{Jacobi(p: Lpoly, q: Lpoly, r: Lpoly): Lpoly == [ [p,q]\$Lpoly, r] + [ [q,r]\$Lpoly, p] + [ [r,p]\$Lpoly, q]  }
\begin{verbatim}
Function declaration Jacobi : (
  LiePolynomial(Symbol,  Fraction Integer),
  LiePolynomial(Symbol,Fraction Integer),
  LiePolynomial(Symbol,Fraction Integer)) -> 
    LiePolynomial(Symbol,Fraction Integer) 
  has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

Tests

\spadcommand{test: Lpoly := Jacobi(a,b,b)  }
$$
0 
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{test: Lpoly := Jacobi(p,q,r)  }
$$
0 
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{test: Lpoly := Jacobi(r,s,t)  }
$$
0 
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

Evaluation

\spadcommand{eval(p, a, p)\$Lpoly}
$$
\left[
a \  {b \sp 2} 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{eval(p, [a,b], [2*bb, 3*aa])\$Lpoly }
$$
-{6 \  {\left[ a \  b 
\right]}}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{r: Lpoly := [p,c]  }
$$
{\left[ a \  b \  c 
\right]}+{\left[
a \  c \  b 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{r1: Lpoly := eval(r, [a,b,c], [bb, cc, aa])\$Lpoly  }
$$
-{\left[ a \  b \  c 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{r2: Lpoly := eval(r, [a,b,c], [cc, aa, bb])\$Lpoly  }
$$
-{\left[ a \  c \  b 
\right]}
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{r + r1 + r2 }
$$
0 
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LinearOrdinaryDifferentialOperator}

{\tt LinearOrdinaryDifferentialOperator(A, diff)} is the domain of
linear ordinary differential operators with coefficients in a ring
{\tt A} with a given derivation.

\subsection{Differential Operators with Series Coefficients}

\noindent
{\bf Problem:}
Find the first few coefficients of {\tt exp(x)/x**i} of {\tt Dop phi} where
\begin{verbatim}
Dop := D**3 + G/x**2 * D + H/x**3 - 1
phi := sum(s[i]*exp(x)/x**i, i = 0..)
\end{verbatim}

\noindent
{\bf Solution:}

Define the differential.

\spadcommand{Dx: LODO(EXPR INT, f +-> D(f, x)) }
\returnType{Type: Void}

\spadcommand{Dx := D() }
$$
D 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator(Expression Integer,theMap NIL)}

Now define the differential operator {\tt Dop}.

\spadcommand{Dop:= Dx**3 + G/x**2*Dx + H/x**3 - 1 }
$$
{D \sp 3}+{{\frac{G}{x \sp 2}} \  D}+{\frac{-{x \sp 3}+H}{x \sp 3}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator(Expression Integer,theMap NIL)}

\spadcommand{n == 3 }
\returnType{Type: Void}

\spadcommand{phi == reduce(+,[subscript(s,[i])*exp(x)/x**i for i in 0..n]) }
\returnType{Type: Void}

\spadcommand{phi1 ==  Dop(phi) / exp x }
\returnType{Type: Void}

\spadcommand{phi2 == phi1 *x**(n+3) }
\returnType{Type: Void}

\spadcommand{phi3 == retract(phi2)@(POLY INT) }
\returnType{Type: Void}

\spadcommand{pans == phi3 ::UP(x,POLY INT) }
\returnType{Type: Void}

\spadcommand{pans1 == [coefficient(pans, (n+3-i) :: NNI) for i in 2..n+1] }
\returnType{Type: Void}

\spadcommand{leq == solve(pans1,[subscript(s,[i]) for i in 1..n]) }
\returnType{Type: Void}

Evaluate this for several values of {\tt n}.

\spadcommand{leq }
\begin{verbatim}
   Compiling body of rule n to compute value of type PositiveInteger 
   Compiling body of rule phi to compute value of type Expression 
      Integer 
   Compiling body of rule phi1 to compute value of type Expression 
      Integer 
   Compiling body of rule phi2 to compute value of type Expression 
      Integer 
   Compiling body of rule phi3 to compute value of type Polynomial 
      Integer 
   Compiling body of rule pans to compute value of type 
      UnivariatePolynomial(x,Polynomial Integer) 
   Compiling body of rule pans1 to compute value of type List 
      Polynomial Integer 
   Compiling body of rule leq to compute value of type List List 
      Equation Fraction Polynomial Integer 
   Compiling function G83347 with type Integer -> Boolean 
\end{verbatim}

\spadcommand{n==4 }
$$
\begin{array}{@{}l}
\left[
\left[ 
{{s \sb {1}}={\frac{{s \sb {0}} \  G}{3}}}, 
{{s \sb {2}}=
{\frac{{3 \  {s \sb {0}} \  H}+
{{s \sb {0}} \  {G \sp 2}}+
{6 \  {s \sb {0}} \  G}}{18}}}, 
\right.
\right.
\\
\\
\displaystyle
\left.
\left.
{{s \sb {3}}=
{\frac{{{\left( {9 \  {s \sb {0}} \  G}+
{{54} \  {s \sb {0}}} \right)}\  H}+
{{s \sb {0}} \  {G \sp 3}}+
{{18} \  {s \sb {0}} \  {G \sp 2}}+
{{72} \  {s \sb {0}} \  G}}{162}}} 
\right]
\right]
\end{array}
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

\spadcommand{leq }
$$
\begin{array}{@{}l}
\left[
\left[ 
{{s \sb {1}}={\frac{{s \sb {0}} \  G}{3}}}, 
{{s \sb {2}}=
{\frac{{3 \  {s \sb {0}} \  H}+
{{s \sb {0}} \  {G \sp 2}}+{6 \  {s \sb {0}} \  G}}{18}}}, 
\right.
\right.
\\
\\
\displaystyle
\left.
\left.
{{s \sb {3}}=
{\frac{{{\left( {9 \  {s \sb {0}} \  G}+
{{54} \  {s \sb {0}}} \right)}\  H}+
{{s \sb {0}} \  {G \sp 3}}+
{{18} \  {s \sb {0}} \  {G \sp 2}}+
{{72} \  {s \sb {0}} \  G}}{162}}} 
\right]
\right]
\end{array}
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

\spadcommand{n==7 }
\begin{verbatim}
   Compiled code for n has been cleared.
   Compiled code for leq has been cleared.
   Compiled code for pans1 has been cleared.
   Compiled code for phi2 has been cleared.
   Compiled code for phi has been cleared.
   Compiled code for phi3 has been cleared.
   Compiled code for phi1 has been cleared.
   Compiled code for pans has been cleared.
   1 old definition(s) deleted for function or rule n 
\end{verbatim}
\returnType{Type: Void}

\spadcommand{leq }
\begin{verbatim}
Compiling body of rule n to compute value of type PositiveInteger 

+++ |*0;n;1;G82322| redefined
Compiling body of rule phi to compute value of type Expression 
  Integer 

+++ |*0;phi;1;G82322| redefined
Compiling body of rule phi1 to compute value of type Expression 
  Integer 

+++ |*0;phi1;1;G82322| redefined
Compiling body of rule phi2 to compute value of type Expression 
  Integer 

+++ |*0;phi2;1;G82322| redefined
Compiling body of rule phi3 to compute value of type Polynomial 
  Integer 

+++ |*0;phi3;1;G82322| redefined
Compiling body of rule pans to compute value of type 
  UnivariatePolynomial(x,Polynomial Integer) 

+++ |*0;pans;1;G82322| redefined
Compiling body of rule pans1 to compute value of type List 
  Polynomial Integer 

+++ |*0;pans1;1;G82322| redefined
Compiling body of rule leq to compute value of type List List 
  Equation Fraction Polynomial Integer 

+++ |*0;leq;1;G82322| redefined
\end{verbatim}
$$
\left[
\left[ 
{{s \sb {1}}={\frac{{s \sb {0}} \  G}{3}}}, 
\right.
\right.\hbox{\hskip 10.0cm}
$$
$$
{s \sb {2}}=
{{3 \  {s \sb {0}} \  H}+
{{s \sb {0}} \  {G \sp 2}}+
\frac{6 \  {s \sb {0}} \  G}{18}}, \hbox{\hskip 8.0cm}
$$
$$
{s \sb {3}}=
{\left( 
{9 \  {s \sb {0}} \  G}+
{{54} \  {s \sb {0}}} 
\right)\  H+
{{s \sb {0}} \  {G \sp 3}}+
{{18} \  {s \sb {0}} \  {G \sp 2}}+
\frac{{72} \  {s \sb {0}} \  G}{162}}, \hbox{\hskip 6.0cm}
$$
$$
{s \sb {4}}=
{\frac{\left(
\begin{array}{@{}l}
{{27} \  {s \sb {0}} \  {H \sp 2}}+
\left( 
{{18} \  {s \sb {0}} \  {G \sp 2}}+
{{378} \  {s \sb {0}} \  G}+
{{1296} \  {s \sb {0}}} 
\right)\  H+
\\
\\
\displaystyle
{{s \sb {0}} \  {G \sp 4}}+
{{36} \  {s \sb {0}} \  {G \sp 3}}+
{{396} \  {s \sb {0}} \  {G \sp 2}}+
{{1296} \  {s \sb {0}} \  G}
\end{array}
\right)}
{1944}}, \hbox{\hskip 4.0cm}
$$
$$
{s \sb {5}}=
{\frac{\left(
\begin{array}{@{}l}
\left( 
{{135} \  {s \sb {0}} \  G}+
{{2268} \  {s \sb {0}}} 
\right)\  {H \sp 2}+
\\
\\
\displaystyle
\left( 
{{30} \  {s \sb {0}} \  {G \sp 3}}+
{{1350} \  {s \sb {0}} \  {G \sp 2}}+
{{16416} \  {s \sb {0}} \  G}+
{{38880} \  {s \sb {0}}} 
\right)\  H+
\\
\\
\displaystyle
{{s \sb {0}} \  {G \sp 5}}+
{{60} \  {s \sb {0}} \  {G \sp 4}}+
{{1188} \  {s \sb {0}} \  {G \sp 3}}+
{{9504} \  {s \sb {0}} \  {G \sp 2}}+
{{25920} \  {s \sb {0}} \  G} 
\end{array}
\right)}
{29160}}, \hbox{\hskip 2.0cm}
$$
$$
{s \sb {6}}=
{\frac{\left(
\begin{array}{@{}l}
{{405} \  {s \sb {0}} \  {H \sp 3}}+
\\
\\
\displaystyle
{{\left( {{405} \  {s \sb {0}} \  {G \sp 2}}+
{{18468} \  {s \sb {0}} \  G}+
{{174960} \  {s \sb {0}}} \right)}\  {H \sp 2}}+
\\
\\
\displaystyle
\left( 
{{45} \  {s \sb {0}} \  {G \sp 4}}+
{{3510} \  {s \sb {0}} \  {G \sp 3}}+
{{88776} \  {s \sb {0}} \  {G \sp 2}}+
{{777600} \  {s \sb {0}} \  G}+
\right.
\\
\displaystyle
\left.
{{1166400} \  {s \sb {0}}} 
\right)\  H+
\\
\\
\displaystyle
{{s \sb {0}} \  {G \sp 6}}+
{{90} \  {s \sb {0}} \  {G \sp 5}}+
{{2628} \  {s \sb {0}} \  {G \sp 4}}+
{{27864} \  {s \sb {0}} \  {G \sp 3}}+
{{90720} \  {s \sb {0}} \  {G \sp 2}} 
\end{array}
\right)}
{524880}}, \hbox{\hskip 1.0cm}
$$
$$
\left.
\left.
{s \sb {7}}=
{\frac{\left(
\begin{array}{@{}l}
\left( 
{{2835} \  {s \sb {0}} \  G}+
{{91854} \  {s \sb {0}}} 
\right)\  {H \sp 3}+
\\
\\
\displaystyle
\left( 
{{945} \  {s \sb {0}} \  {G \sp 3}}+
{{81648} \  {s \sb {0}} \  {G \sp 2}}+
{{2082996} \  {s \sb {0}} \  G}+
{{14171760} \  {s \sb {0}}} 
\right)\  {H \sp 2}+
\\
\\
\displaystyle
\left( 
{{63} \  {s \sb {0}} \  {G \sp 5}}+
{{7560} \  {s \sb {0}} \  {G \sp 4}}+
{{317520} \  {s \sb {0}} \  {G \sp 3}}+
{{5554008} \  {s \sb {0}} \  {G \sp 2}}+
\right.
\\
\displaystyle
\left.
{{34058880} \  {s \sb {0}} \  G} 
\right)\  H+
\\
\\
\displaystyle
{{s \sb {0}} \  {G \sp 7}}+
{{126} \  {s \sb {0}} \  {G \sp 6}}+
{{4788} \  {s \sb {0}} \  {G \sp 5}}+
{{25272} \  {s \sb {0}} \  {G \sp 4}} -
{{1744416} \  {s \sb {0}} \  {G \sp 3}} -
\\
\displaystyle
{{26827200} \  {s \sb {0}} \  {G \sp 2}} -
{{97977600} \  {s \sb {0}} \  G} 
\end{array}
\right)}
{11022480}}
\right]
\right]
$$
\returnType{Type: List List Equation Fraction Polynomial Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LinearOrdinaryDifferentialOperator1}

{\tt LinearOrdinaryDifferentialOperator1(A)} is the domain of linear
ordinary differential operators with coefficients in the differential ring
{\tt A}.

%Original Page 396

\subsection{Differential Operators with Rational Function Coefficients}

This example shows differential operators with rational function
coefficients.  In this case operator multiplication is non-commutative and,
since the coefficients form a field, an operator division algorithm exists.

We begin by defining {\tt RFZ} to be the rational functions in
{\tt x} with integer coefficients and {\tt Dx} to be the differential
operator for {\tt d/dx}.

\spadcommand{RFZ := Fraction UnivariatePolynomial('x, Integer) }
$$
\mbox{\rm Fraction UnivariatePolynomial(x,Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{x : RFZ := 'x }
$$
x 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Integer)}

\spadcommand{Dx : LODO1 RFZ := D()}
$$
D 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

Operators are created using the usual arithmetic operations.

\spadcommand{b : LODO1 RFZ := 3*x**2*Dx**2 + 2*Dx + 1/x  }
$$
{3 \  {x \sp 2} \  {D \sp 2}}+{2 \  D}+{\frac{1}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

\spadcommand{a : LODO1 RFZ := b*(5*x*Dx + 7)}
$$
{{15} \  {x \sp 3} \  {D \sp 3}}+{{\left( {{51} \  {x \sp 2}}+{{10} \  x} 
\right)}
\  {D \sp 2}}+{{29} \  D}+{\frac{7}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

Operator multiplication corresponds to functional composition.

\spadcommand{p := x**2 + 1/x**2 }
$$
\frac{{x \sp 4}+1}{x \sp 2} 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Integer)}

Since operator coefficients depend on {\tt x}, the multiplication is
not commutative.

\spadcommand{(a*b - b*a) p }
$$
\frac{-{{75} \  {x \sp 4}}+{{540} \  x} -{75}}{x \sp 4} 
$$
\returnType{Type: Fraction UnivariatePolynomial(x,Integer)}

%Original Page 397

When the coefficients of operator polynomials come from a field, as in
this case, it is possible to define operator division.  Division on
the left and division on the right yield different results when the
multiplication is non-commutative.

The results of
\spadfunFrom{leftDivide}{LinearOrdinaryDifferentialOperator1} and
\spadfunFrom{rightDivide}{LinearOrdinaryDifferentialOperator1} are
quotient-remainder pairs satisfying: \newline

{\tt leftDivide(a,b) = [q, r]} such that  {\tt a = b*q + r} \newline
{\tt rightDivide(a,b) = [q, r]} such that  {\tt a = q*b + r} \newline

In both cases, the
\spadfunFrom{degree}{LinearOrdinaryDifferentialOperator1} of the
remainder, {\tt r}, is less than the degree of {\tt b}.

\spadcommand{ld := leftDivide(a,b) }
$$
\left[
{quotient={{5 \  x \  D}+7}}, {remainder=0} 
\right]
$$
\returnType{Type: 
Record(quotient: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer),
remainder: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer))}

\spadcommand{a = b * ld.quotient + ld.remainder }
$$
\begin{array}{@{}l}
{{{15} \  {x \sp 3} \  {D \sp 3}}+
{{\left( 
{{51} \  {x \sp 2}}+
{{10} \  x} 
\right)}
\  {D \sp 2}}+
{{29} \  D}+
{\frac{7}{x}}}=
\\
\\
\displaystyle
{{{15} \  {x \sp 3} \  {D \sp 3}}+
{{\left( {{51} \  {x \sp 2}}+
{{10} \  x} 
\right)}
\  {D \sp 2}}+
{{29} \  D}+{\frac{7}{x}}} 
\end{array}
$$
\returnType{Type: 
Equation LinearOrdinaryDifferentialOperator1 
Fraction UnivariatePolynomial(x,Integer)}

The operations of left and right division
are so-called because the quotient is obtained by dividing
{\tt a} on that side by {\tt b}.

\spadcommand{rd := rightDivide(a,b) }
$$
\left[
{quotient={{5 \  x \  D}+7}}, {remainder={{{10} \  D}+{\frac{5}{x}}}} 
\right]
$$
\returnType{Type: 
Record(quotient: 
LinearOrdinaryDifferentialOperator1 Fraction 
UnivariatePolynomial(x,Integer),
remainder: 
LinearOrdinaryDifferentialOperator1 Fraction 
UnivariatePolynomial(x,Integer))}

%Original Page 398

\spadcommand{a = rd.quotient * b + rd.remainder }
$$
\begin{array}{@{}l}
{{{15} \  {x \sp 3} \  {D \sp 3}}+
{{\left( {{51} \  {x \sp 2}}+{{10} \  x} 
\right)}
\  {D \sp 2}}+
{{29} \  D}+
{\frac{7}{x}}}=
\\
\\
\displaystyle
{{{15} \  {x \sp 3} \  {D \sp 3}}+
{{\left( {{51} \  {x \sp 2}}+
{{10} \  x} 
\right)}
\  {D \sp 2}}+
{{29} \  D}+
{\frac{7}{x}}} 
\end{array}
$$
\returnType{Type: Equation 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

Operations
\spadfunFrom{rightQuotient}{LinearOrdinaryDifferentialOperator1} and
\spadfunFrom{rightRemainder}{LinearOrdinaryDifferentialOperator1} are
available if only one of the quotient or remainder are of interest to
you.  This is the quotient from right division.

\spadcommand{rightQuotient(a,b) }
$$
{5 \  x \  D}+7 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

This is the remainder from right division.
The corresponding ``left'' functions
\spadfunFrom{leftQuotient}{LinearOrdinaryDifferentialOperator1} and
\spadfunFrom{leftRemainder}{LinearOrdinaryDifferentialOperator1}
are also available.

\spadcommand{rightRemainder(a,b) }
$$
{{10} \  D}+{\frac{5}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

For exact division, the operations
\spadfunFrom{leftExactQuotient}{LinearOrdinaryDifferentialOperator1} and
\spadfunFrom{rightExactQuotient}{LinearOrdinaryDifferentialOperator1} are supplied.
These return the quotient but only if the remainder is zero.
The call {\tt rightExact\-Quotient(a,b)} would yield an error.

\spadcommand{leftExactQuotient(a,b) }
$$
{5 \  x \  D}+7 
$$
\returnType{Type: 
Union(LinearOrdinaryDifferentialOperator1 
Fraction UnivariatePolynomial(x,Integer),...)}

The division operations allow the computation of left and right greatest
common divisors (\spadfunFrom{leftGcd}{LinearOrdinaryDifferentialOperator1} and
\spadfunFrom{rightGcd}{LinearOrdinaryDifferentialOperator1}) via remainder
sequences, and consequently the computation of left and right least common
multiples (\spadfunFrom{rightLcm}{LinearOrdinaryDifferentialOperator1} and
\spadfunFrom{leftLcm}{LinearOrdinaryDifferentialOperator1}).

\spadcommand{e := leftGcd(a,b) }
$$
{3 \  {x \sp 2} \  {D \sp 2}}+{2 \  D}+{\frac{1}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

Note that a greatest common divisor doesn't necessarily divide {\tt a}
and {\tt b} on both sides.  Here the left greatest common divisor does
not divide {\tt a} on the right.

\spadcommand{leftRemainder(a, e) }
$$
0 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

\spadcommand{rightRemainder(a, e) }
$$
{{10} \  D}+{\frac{5}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

Similarly, a least common multiple is not necessarily divisible from
both sides.

%Original Page 399

% NOTE: the book has a different answer
\spadcommand{f := rightLcm(a,b) }
$$
{{15} \  {x \sp 3} \  {D \sp 3}}+
{{\left( 
{{51} \  {x \sp 2}}+
{{10} \  x} 
\right)}
\  {D \sp 2}}+
{{29} \  D}+{\frac{7}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

% NOTE: the book has a different answer
\spadcommand{rightRemainder(f, b) }
$$
{{10} \  D}+{\frac{5}{x}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

% NOTE: the book has a different answer
\spadcommand{leftRemainder(f, b) }
$$
0 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator1 Fraction UnivariatePolynomial(x,Integer)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LinearOrdinaryDifferentialOperator2}

{\tt LinearOrdinaryDifferentialOperator2(A, M)} is the domain of
linear ordinary differential operators with coefficients in the
differential ring {\tt A} and operating on {\tt M}, an {\tt A}-module.
This includes the cases of operators which are polynomials in {\tt D}
acting upon scalar or vector expressions of a single variable.  The
coefficients of the operator polynomials can be integers, rational
functions, matrices or elements of other domains.

\subsection{Differential Operators with Constant Coefficients}

This example shows differential operators with rational
number coefficients operating on univariate polynomials.

We begin by making type assignments so we can conveniently refer
to univariate polynomials in {\tt x} over the rationals.

\spadcommand{Q  := Fraction Integer }
$$
\mbox{\rm Fraction Integer} 
$$
\returnType{Type: Domain}

\spadcommand{PQ := UnivariatePolynomial('x, Q) }
$$
\mbox{\rm UnivariatePolynomial(x,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{x: PQ := 'x }
$$
x 
$$
\returnType{Type: UnivariatePolynomial(x,Fraction Integer)}

Now we assign {\tt Dx} to be the differential operator
\spadfunFrom{D}{LinearOrdinaryDifferentialOperator2}
corresponding to {\tt d/dx}.

\spadcommand{Dx: LODO2(Q, PQ) := D() }
$$
D 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
Fraction Integer,
UnivariatePolynomial(x,Fraction Integer))}

%Original Page 399

New operators are created as polynomials in {\tt D()}.

\spadcommand{a := Dx  + 1 }
$$
D+1 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
Fraction Integer,
UnivariatePolynomial(x,Fraction Integer))}

\spadcommand{b := a + 1/2*Dx**2 - 1/2 }
$$
{{\frac{1}{2}} \  {D \sp 2}}+D+{\frac{1}{2}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
Fraction Integer,
UnivariatePolynomial(x,Fraction Integer))}

To apply the operator {\tt a} to the value {\tt p} the usual function
call syntax is used.

\spadcommand{p := 4*x**2 + 2/3 }
$$
{4 \  {x \sp 2}}+{\frac{2}{3}} 
$$
\returnType{Type: UnivariatePolynomial(x,Fraction Integer)}

\spadcommand{a p }
$$
{4 \  {x \sp 2}}+{8 \  x}+{\frac{2}{3}} 
$$
\returnType{Type: UnivariatePolynomial(x,Fraction Integer)}

Operator multiplication is defined by the identity {\tt (a*b) p = a(b(p))}

\spadcommand{(a * b) p = a b p }
$$
{{2 \  {x \sp 2}}+{{12} \  x}+{\frac{37}{3}}}={{2 \  {x \sp 2}}+{{12} \  
x}+{\frac{37}{3}}} 
$$
\returnType{Type: Equation UnivariatePolynomial(x,Fraction Integer)}

Exponentiation follows from multiplication.

\spadcommand{c := (1/9)*b*(a + b)**2 }
$$
{{\frac{1}{72}} \  {D \sp 6}}
+{{\frac{5}{36}} \  {D \sp 5}}
+{{\frac{13}{24}} \  {D \sp 4}}
+{{\frac{19}{18}} \  {D \sp 3}}
+{{\frac{79}{72}} \  {D \sp 2}}
+{{\frac{7}{12}} \  D}
+{\frac{1}{8}} 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
Fraction Integer,
UnivariatePolynomial(x,Fraction Integer))}

Finally, note that operator expressions may be applied directly.

\spadcommand{(a**2 - 3/4*b + c) (p + 1) }
$$
{3 \  {x \sp 2}}+{{\frac{44}{3}} \  x}+{\frac{541}{36}} 
$$
\returnType{Type: UnivariatePolynomial(x,Fraction Integer)}

%Original Page 401

\subsection{
Differential Operators with Matrix Coefficients Operating on Vectors}

This is another example of linear ordinary differential operators with
non-commutative multiplication.  Unlike the rational function case,
the differential ring of square matrices (of a given dimension) with
univariate polynomial entries does not form a field.  Thus the number
of operations available is more limited.

%Original Page 402

In this section, the operators have three by three
matrix coefficients with polynomial entries.

\spadcommand{PZ   := UnivariatePolynomial(x,Integer)}
$$
UnivariatePolynomial(x,Integer) 
$$
\returnType{Type: Domain}

\spadcommand{x:PZ := 'x }
$$
x 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

\spadcommand{Mat  := SquareMatrix(3,PZ)}
$$
SquareMatrix(3,UnivariatePolynomial(x,Integer)) 
$$
\returnType{Type: Domain}

The operators act on the vectors considered as a {\tt Mat}-module.

\spadcommand{Vect := DPMM(3, PZ, Mat, PZ)}
$$
\begin{array}{@{}l}
{\rm DirectProductMatrixModule(3,}
\\
\displaystyle
{\rm \ \ UnivariatePolynomial(x,Integer),}
\\
\displaystyle
{\rm \ \ SquareMatrix(3,UnivariatePolynomial(x,Integer)),}
\\
\displaystyle
{\rm \ \ UnivariatePolynomial(x,Integer))}
\end{array}
$$
\returnType{Type: Domain}

\spadcommand{Modo := LODO2(Mat, Vect)}
$$
\begin{array}{@{}l}
{\rm LinearOrdinaryDifferentialOperator2(}
\\
\displaystyle
{\rm \ \ SquareMatrix(3,UnivariatePolynomial(x,Integer)),}
\\
\displaystyle
{\rm \ \ DirectProductMatrixModule(3,}
\\
\displaystyle
{\rm \ \ UnivariatePolynomial(x,Integer),}
\\
\displaystyle
{\rm \ \ SquareMatrix(3,UnivariatePolynomial(x,Integer)),}
\\
\displaystyle
{\rm \ \ UnivariatePolynomial(x,Integer)))}
\end{array}
$$
\returnType{Type: Domain}

The matrix {\tt m} is used as a coefficient and the vectors {\tt p}
and {\tt q} are operated upon.

\spadcommand{m:Mat := matrix [ [x**2,1,0],[1,x**4,0],[0,0,4*x**2] ]}
$$
\left[
\begin{array}{ccc}
{x \sp 2} & 1 & 0 \\ 
1 & {x \sp 4} & 0 \\ 
0 & 0 & {4 \  {x \sp 2}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(3,UnivariatePolynomial(x,Integer))}

\spadcommand{p:Vect := directProduct [3*x**2+1,2*x,7*x**3+2*x]}
$$
\left[
{{3 \  {x \sp 2}}+1}, {2 \  x}, {{7 \  {x \sp 3}}+{2 \  x}} 
\right]
$$
\returnType{Type: 
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer))}

\spadcommand{q: Vect := m * p}
$$
\left[
{{3 \  {x \sp 4}}+{x \sp 2}+{2 \  x}}, {{2 \  {x \sp 5}}+{3 \  {x \sp 
2}}+1}, {{{28} \  {x \sp 5}}+{8 \  {x \sp 3}}} 
\right]
$$
\returnType{Type: 
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer))}

%Original Page 403

Now form a few operators.

\spadcommand{Dx : Modo := D()}
$$
D 
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
SquareMatrix(3,UnivariatePolynomial(x,Integer)),
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer)))}

\spadcommand{a : Modo := Dx  + m}
$$
D+{\left[ 
\begin{array}{ccc}
{x \sp 2} & 1 & 0 \\ 
1 & {x \sp 4} & 0 \\ 
0 & 0 & {4 \  {x \sp 2}} 
\end{array}
\right]}
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
SquareMatrix(3,UnivariatePolynomial(x,Integer)),
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer)))}

\spadcommand{b : Modo := m*Dx  + 1}
$$
{{\left[ 
\begin{array}{ccc}
{x \sp 2} & 1 & 0 \\ 
1 & {x \sp 4} & 0 \\ 
0 & 0 & {4 \  {x \sp 2}} 
\end{array}
\right]}
\  D}+{\left[ 
\begin{array}{ccc}
1 & 0 & 0 \\ 
0 & 1 & 0 \\ 
0 & 0 & 1 
\end{array}
\right]}
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer)))}

\spadcommand{c := a*b }
$$
\begin{array}{@{}l}
{{\left[ 
\begin{array}{ccc}
{x \sp 2} & 1 & 0 \\ 
1 & {x \sp 4} & 0 \\ 
0 & 0 & {4 \  {x \sp 2}} 
\end{array}
\right]}
\  {D \sp 2}}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{ccc}
{{x \sp 4}+{2 \  x}+2} & {{x \sp 4}+{x \sp 2}} & 0 \\ 
{{x \sp 4}+{x \sp 2}} & {{x \sp 8}+{4 \  {x \sp 3}}+2} & 0 \\ 
0 & 0 & {{{16} \  {x \sp 4}}+{8 \  x}+1} 
\end{array}
\right]}
\  D}+
\\
\\
\displaystyle
{\left[ 
\begin{array}{ccc}
{x \sp 2} & 1 & 0 \\ 
1 & {x \sp 4} & 0 \\ 
0 & 0 & {4 \  {x \sp 2}} 
\end{array}
\right]}
\end{array}
$$
\returnType{Type: 
LinearOrdinaryDifferentialOperator2(
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer)))}

%Original Page 404

These operators can be applied to vector values.

\spadcommand{a p }
$$
\left[
{{3 \  {x \sp 4}}+{x \sp 2}+{8 \  x}}, {{2 \  {x \sp 5}}+{3 \  {x \sp 
2}}+3}, {{{28} \  {x \sp 5}}+{8 \  {x \sp 3}}+{{21} \  {x \sp 2}}+2} 
\right]
$$
\returnType{Type: 
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer))}

\spadcommand{b p }
$$
\left[
{{6 \  {x \sp 3}}+{3 \  {x \sp 2}}+3}, {{2 \  {x \sp 4}}+{8 \  x}}, 
{{{84} \  {x \sp 4}}+{7 \  {x \sp 3}}+{8 \  {x \sp 2}}+{2 \  x}} 
\right]
$$
\returnType{Type: 
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer))}

\spadcommand{(a + b + c) (p + q) }
$$
\begin{array}{@{}l}
\left[
{{{10} \  {x \sp 8}}+
{{12} \  {x \sp 7}}+
{{16} \  {x \sp 6}}+
{{30} \  {x \sp 5}}+
{{85} \  {x \sp 4}}+
{{94} \  {x \sp 3}}+
{{40} \  {x \sp 2}}+
{{40} \  x}+
{17}}, 
\right.
\\
\\
\displaystyle
{{10} \  {x \sp {12}}}+
{{10} \  {x \sp 9}}+
{{12} \  {x \sp 8}}+
{{92} \  {x \sp 7}}+
{6 \  {x \sp 6}}+
{{32} \  {x \sp 5}}+
{{72} \  {x \sp 4}}+
{{28} \  {x \sp 3}}+
{{49} \  {x \sp 2}}+
\\
\displaystyle
{{32} \  x}+
{19}, 
\\
\\
\displaystyle
\left.
{{{2240} \  {x \sp 8}}+
{{224} \  {x \sp 7}}+
{{1280} \  {x \sp 6}}+
{{3508} \  {x \sp 5}}+
{{492} \  {x \sp 4}}+
{{751} \  {x \sp 3}}+
{{98} \  {x \sp 2}}+
{{18} \  x}+
4} 
\right]
\end{array}
$$
\returnType{Type: 
DirectProductMatrixModule(3,
UnivariatePolynomial(x,Integer),
SquareMatrix(3,
UnivariatePolynomial(x,Integer)),
UnivariatePolynomial(x,Integer))}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{List}

A \index{list} is a finite collection of elements in a specified
order that can contain duplicates.  A list is a convenient structure
to work with because it is easy to add or remove elements and the
length need not be constant.  There are many different kinds of lists
in Axiom, but the default types (and those used most often) are
created by the {\tt List} constructor.  For example, there are objects
of type {\tt List Integer}, {\tt List Float} and {\tt List Polynomial
Fraction Integer}.  Indeed, you can even have {\tt List List List
Boolean} (that is, lists of lists of lists of Boolean values).  You
can have lists of any type of Axiom object.

%Original Page 405

\subsection{Creating Lists}

The easiest way to create a list with, for example, the elements
{\tt 2, 4, 5, 6} is to enclose the elements with square
brackets and separate the elements with commas.

The spaces after the commas are optional, but they do improve the
readability.

\spadcommand{[2, 4, 5, 6]}
$$
\left[
2, 4, 5, 6 
\right]
$$
\returnType{Type: List PositiveInteger}

To create a list with the single element {\tt 1}, you can use
either {\tt [1]} or the operation \spadfunFrom{list}{List}.

\spadcommand{[1]}
$$
\left[
1 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{list(1)}
$$
\left[
1 
\right]
$$
\returnType{Type: List PositiveInteger}

Once created, two lists {\tt k} and {\tt m} can be concatenated by
issuing {\tt append(k,m)}.  \spadfunFrom{append}{List} does {\it not}
physically join the lists, but rather produces a new list with the
elements coming from the two arguments.

\spadcommand{append([1,2,3],[5,6,7])}
$$
\left[
1, 2, 3, 5, 6, 7 
\right]
$$
\returnType{Type: List PositiveInteger}

Use \spadfunFrom{cons}{List} to append an element onto the front of a
list.

\spadcommand{cons(10,[9,8,7])}
$$
\left[
{10}, 9, 8, 7 
\right]
$$
\returnType{Type: List PositiveInteger}

\subsection{Accessing List Elements}

To determine whether a list has any elements, use the operation
\spadfunFrom{empty?}{List}.

\spadcommand{empty? [x+1]}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

Alternatively, equality with the list constant \spadfunFrom{nil}{List} can
be tested.

\spadcommand{([] = nil)@Boolean}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

We'll use this in some of the following examples.

\spadcommand{k := [4,3,7,3,8,5,9,2] }
$$
\left[
4, 3, 7, 3, 8, 5, 9, 2 
\right]
$$
\returnType{Type: List PositiveInteger}

%Original Page 406

Each of the next four expressions extracts the \spadfunFrom{first}{List}
element of {\tt k}.

\spadcommand{first k }
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{k.first }
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{k.1 }
$$
4 
$$
\returnType{Type: PositiveInteger}

\spadcommand{k(1) }
$$
4 
$$
\returnType{Type: PositiveInteger}

The last two forms generalize to {\tt k.i} and {\tt k(i)},
respectively, where $ 1 \leq i \leq n$ and {\tt n} equals the length
of {\tt k}.

This length is calculated by \spadopFrom{\#}{List}.

\spadcommand{n := \#k }
$$
8 
$$
\returnType{Type: PositiveInteger}

Performing an operation such as {\tt k.i} is sometimes referred to as
{\it indexing into k} or {\it elting into k}.  The latter phrase comes
about because the name of the operation that extracts elements is
called \spadfunFrom{elt}{List}.  That is, {\tt k.3} is just
alternative syntax for {\tt elt(k,3)}.  It is important to remember
that list indices begin with 1.  If we issue {\tt k := [1,3,2,9,5]}
then {\tt k.4} returns {\tt 9}.  It is an error to use an index that
is not in the range from {\tt 1} to the length of the list.

The last element of a list is extracted by any of the
following three expressions.

\spadcommand{last k }
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{k.last }
$$
2 
$$
\returnType{Type: PositiveInteger}

This form computes the index of the last element and then extracts the
element from the list.

\spadcommand{k.(\#k) }
$$
2 
$$
\returnType{Type: PositiveInteger}

%Original Page 407

\subsection{Changing List Elements}

We'll use this in some of the following examples.

\spadcommand{k := [4,3,7,3,8,5,9,2] }
$$
\left[
4, 3, 7, 3, 8, 5, 9, 2 
\right]
$$
\returnType{Type: List PositiveInteger}

List elements are reset by using the {\tt k.i} form on the left-hand
side of an assignment.  This expression resets the first element of
{\tt k} to {\tt 999}.

\spadcommand{k.1 := 999 }
$$
999 
$$
\returnType{Type: PositiveInteger}

As with indexing into a list, it is an error to use an index that is
not within the proper bounds.  Here you see that {\tt k} was modified.

\spadcommand{k }
$$
\left[
{999}, 3, 7, 3, 8, 5, 9, 2 
\right]
$$
\returnType{Type: List PositiveInteger}

The operation that performs the assignment of an element to a
particular position in a list is called \spadfunFrom{setelt}{List}.
This operation is {\it destructive} in that it changes the list.  In
the above example, the assignment returned the value {\tt 999} and
{\tt k} was modified.  For this reason, lists are called
\index{mutable} objects: it is possible to change part of a list
(mutate it) rather than always returning a new list reflecting the
intended modifications.

Moreover, since lists can share structure, changes to one list can
sometimes affect others.

\spadcommand{k := [1,2] }
$$
\left[
1, 2 
\right]
$$
\returnType{Type: List PositiveInteger}

\spadcommand{m := cons(0,k) }
$$
\left[
0, 1, 2 
\right]
$$
\returnType{Type: List Integer}

Change the second element of {\tt m}.

\spadcommand{m.2 := 99 }
$$
99 
$$
\returnType{Type: PositiveInteger}

See, {\tt m} was altered.

\spadcommand{m }
$$
\left[
0, {99}, 2 
\right]
$$
\returnType{Type: List Integer}

But what about {\tt k}?  It changed too!

\spadcommand{k  }
$$
\left[
{99}, 2 
\right]
$$
\returnType{Type: List PositiveInteger}

%Original Page 408

\subsection{Other Functions}

An operation that is used frequently in list processing is that
which returns all elements in a list after the first element.

\spadcommand{k := [1,2,3] }
$$
\left[
1, 2, 3 
\right]
$$
\returnType{Type: List PositiveInteger}

Use the \spadfunFrom{rest}{List} operation to do this.

\spadcommand{rest k }
$$
\left[
2, 3 
\right]
$$
\returnType{Type: List PositiveInteger}

To remove duplicate elements in a list {\tt k}, use
\spadfunFrom{removeDuplicates}{List}.

\spadcommand{removeDuplicates [4,3,4,3,5,3,4]}
$$
\left[
4, 3, 5 
\right]
$$
\returnType{Type: List PositiveInteger}

To get a list with elements in the order opposite to those in
a list {\tt k}, use \spadfunFrom{reverse}{List}.

\spadcommand{reverse [1,2,3,4,5,6]}
$$
\left[
6, 5, 4, 3, 2, 1 
\right]
$$
\returnType{Type: List PositiveInteger}

To test whether an element is in a list, use
\spadfunFrom{member?}{List}: {\tt member?(a,k)} returns {\tt true} or
{\tt false} depending on whether {\tt a} is in {\tt k} or not.

\spadcommand{member?(1/2,[3/4,5/6,1/2])}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{member?(1/12,[3/4,5/6,1/2])}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

As an exercise, the reader should determine how to get a list
containing all but the last of the elements in a given non-empty list
{\tt k}.\footnote{{\tt reverse(rest(reverse(k)))} works.}

\subsection{Dot, Dot}

Certain lists are used so often that Axiom provides an easy way of
constructing them.  If {\tt n} and {\tt m} are integers, then 
{\tt expand [n..m]} creates a list containing {\tt n, n+1, ... m}.  If 
{\tt n > m} then the list is empty.  It is actually permissible to leave
off the {\tt m} in the dot-dot construction (see below).

The dot-dot notation can be used more than once in a list construction
and with specific elements being given.  Items separated by dots are
called {\it segments.}

\spadcommand{[1..3,10,20..23]}
$$
\left[
{1..3}, {{10}..{10}}, {{20}..{23}} 
\right]
$$
\returnType{Type: List Segment PositiveInteger}

%Original Page 409

Segments can be expanded into the range of items between the
endpoints by using \spadfunFrom{expand}{Segment}.

\spadcommand{expand [1..3,10,20..23]}
$$
\left[
1, 2, 3, {10}, {20}, {21}, {22}, {23} 
\right]
$$
\returnType{Type: List Integer}

What happens if we leave off a number on the right-hand side of
\spadopFrom{..}{UniversalSegment}?

\spadcommand{expand [1..]}
$$
\left[
1, 2, 3, 4, 5, 6, 7, 8, 9, {10}, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

What is created in this case is a {\tt Stream} which is a
generalization of a list.  See \domainref{Stream} for more information.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{LyndonWord}

Initialisations

\spadcommand{a:Symbol :='a }
$$
a 
$$
\returnType{Type: Symbol}

\spadcommand{b:Symbol :='b }
$$
b 
$$
\returnType{Type: Symbol}

\spadcommand{c:Symbol :='c }
$$
c 
$$
\returnType{Type: Symbol}

\spadcommand{lword:= LyndonWord(Symbol) }
$$
\mbox{\rm LyndonWord Symbol} 
$$
\returnType{Type: Domain}

\spadcommand{magma := Magma(Symbol) }
$$
\mbox{\rm Magma Symbol} 
$$
\returnType{Type: Domain}

\spadcommand{word   := OrderedFreeMonoid(Symbol) }
$$
\mbox{\rm OrderedFreeMonoid Symbol} 
$$
\returnType{Type: Domain}

All Lyndon words of with a, b, c to order 3

\spadcommand{LyndonWordsList1([a,b,c],3)\$lword     }
$$
\begin{array}{@{}l}
\left[
{\left[ 
{\left[ a \right]},
{\left[ b \right]},
{\left[ c \right]}
\right]},
{\left[ 
{\left[ a \  b \right]}, {\left[ a \  c \right]},{\left[ b \  c \right]}
\right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ {\left[ {a \sp 2} \  b 
\right]},
{\left[ {a \sp 2} \  c 
\right]},
{\left[ a \  {b \sp 2} 
\right]},
{\left[ a \  b \  c 
\right]},
{\left[ a \  c \  b 
\right]},
{\left[ a \  {c \sp 2} 
\right]},
{\left[ {b \sp 2} \  c 
\right]},
{\left[ b \  {c \sp 2} 
\right]}
\right]}
\right]
\end{array}
$$
\returnType{Type: OneDimensionalArray List LyndonWord Symbol}

All Lyndon words of with a, b, c to order 3 in flat list

\spadcommand{LyndonWordsList([a,b,c],3)\$lword}
$$
\begin{array}{@{}l}
\left[
{\left[ a \right]},
{\left[ b \right]},
{\left[ c \right]},
{\left[ a \  b \right]},
{\left[ a \  c \right]},
{\left[ b \  c \right]},
{\left[ {a \sp 2} \  b \right]},
{\left[ {a \sp 2} \  c \right]},
{\left[ a \  {b \sp 2} \right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ a \  b \  c \right]},
{\left[ a \  c \  b \right]},
{\left[ a \  {c \sp 2} \right]},
{\left[ {b \sp 2} \  c \right]},
{\left[ b \  {c \sp 2} \right]}
\right]
\end{array}
$$
\returnType{Type: List LyndonWord Symbol}

All Lyndon words of with a, b to order 5

\spadcommand{lw := LyndonWordsList([a,b],5)\$lword    }
$$
\begin{array}{@{}l}
\left[
\displaystyle
{\left[ a \right]},
{\left[ b \right]},
{\left[ a \  b \right]},
{\left[ {a \sp 2} \  b \right]},
{\left[ a \  {b \sp 2} \right]},
{\left[ {a \sp 3} \  b \right]},
{\left[ {a \sp 2} \  {b \sp 2} \right]},
{\left[ a \  {b \sp 3} \right]},
{\left[ {a \sp 4} \  b \right]},
\right.
\\
\\
\displaystyle
\left.
{\left[ {a \sp 3} \  {b \sp 2} \right]},
{\left[ {a \sp 2} \  b \  a \  b \right]},
{\left[ {a \sp 2} \  {b \sp 3} \right]},
{\left[ a \  b \  a \  {b \sp 2} \right]},
{\left[ a \  {b \sp 4} \right]}
\right]
\end{array}
$$
\returnType{Type: List LyndonWord Symbol}

\spadcommand{w1 : word := lw.4 :: word   }
$$
{a \sp 2} \  b 
$$
\returnType{Type: OrderedFreeMonoid Symbol}

\spadcommand{w2 : word := lw.5 :: word   }
$$
a \  {b \sp 2} 
$$
\returnType{Type: OrderedFreeMonoid Symbol}

Let's try factoring

\spadcommand{factor(a::word)\$lword }
$$
\left[
{\left[ a 
\right]}
\right]
$$
\returnType{Type: List LyndonWord Symbol}

\spadcommand{factor(w1*w2)\$lword }
$$
\left[
{\left[ {a \sp 2} \  b \  a \  {b \sp 2} 
\right]}
\right]
$$
\returnType{Type: List LyndonWord Symbol}

\spadcommand{factor(w2*w2)\$lword }
$$
\left[
{\left[ a \  {b \sp 2} 
\right]},
{\left[ a \  {b \sp 2} 
\right]}
\right]
$$
\returnType{Type: List LyndonWord Symbol}

\spadcommand{factor(w2*w1)\$lword }
$$
\left[
{\left[ a \  {b \sp 2} 
\right]},
{\left[ {a \sp 2} \  b 
\right]}
\right]
$$
\returnType{Type: List LyndonWord Symbol}

Checks and coercions

\spadcommand{lyndon?(w1)\$lword }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{lyndon?(w1*w2)\$lword }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{lyndon?(w2*w1)\$lword }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{lyndonIfCan(w1)\$lword }
$$
\left[
{a \sp 2} \  b 
\right]
$$
\returnType{Type: Union(LyndonWord Symbol,...)}

\spadcommand{lyndonIfCan(w2*w1)\$lword }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

\spadcommand{lyndon(w1)\$lword }
$$
\left[
{a \sp 2} \  b 
\right]
$$
\returnType{Type: LyndonWord Symbol}

\spadcommand{lyndon(w1*w2)\$lword }
$$
\left[
{a \sp 2} \  b \  a \  {b \sp 2} 
\right]
$$
\returnType{Type: LyndonWord Symbol}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Magma}

Initialisations

\spadcommand{x:Symbol :='x }
$$
x 
$$
\returnType{Type: Symbol}

\spadcommand{y:Symbol :='y }
$$
y 
$$
\returnType{Type: Symbol}

\spadcommand{z:Symbol :='z }
$$
z 
$$
\returnType{Type: Symbol}

\spadcommand{word := OrderedFreeMonoid(Symbol) }
$$
\mbox{\rm OrderedFreeMonoid Symbol} 
$$
\returnType{Type: Domain}

\spadcommand{tree := Magma(Symbol) }
$$
\mbox{\rm Magma Symbol} 
$$
\returnType{Type: Domain}

Let's make some trees

\spadcommand{a:tree := x*x  }
$$
\left[
x, x 
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{b:tree := y*y  }
$$
\left[
y, y 
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{c:tree := a*b  }
$$
\left[
{\left[ x, x 
\right]},
{\left[ y, y 
\right]}
\right]
$$
\returnType{Type: Magma Symbol}

Query the trees

\spadcommand{left c }
$$
\left[
x, x 
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{right c }
$$
\left[
y, y 
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{length c }
$$
4 
$$
\returnType{Type: PositiveInteger}

Coerce to the monoid

\spadcommand{c::word }
$$
{x \sp 2} \  {y \sp 2} 
$$
\returnType{Type: OrderedFreeMonoid Symbol}

Check ordering

\spadcommand{a < b }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{a < c }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{b < c }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Navigate the tree

\spadcommand{first c }
$$
x 
$$
\returnType{Type: Symbol}

\spadcommand{rest c }
$$
\left[
x, {\left[ y, y 
\right]}
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{rest rest c  }
$$
\left[
y, y 
\right]
$$
\returnType{Type: Magma Symbol}

Check ordering

\spadcommand{ax:tree := a*x  }
$$
\left[
{\left[ x, x 
\right]},
x 
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{xa:tree := x*a  }
$$
\left[
x, {\left[ x, x 
\right]}
\right]
$$
\returnType{Type: Magma Symbol}

\spadcommand{xa < ax }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{lexico(xa,ax) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{MakeFunction}

It is sometimes useful to be able to define a function given by
the result of a calculation.

Suppose that you have obtained the following expression after several
computations and that you now want to tabulate the numerical values of
{\tt f} for {\tt x} between {\tt -1} and {\tt +1} with increment 
{\tt 0.1}.

\spadcommand{expr := (x - exp x + 1)**2 * (sin(x**2) * x + 1)**3 }
$$
\begin{array}{@{}l}
{{\left( 
{{x \sp 3} \  {{e \sp x} \sp 2}}+
{{\left( -{2 \  {x \sp 4}} -{2 \ {x \sp 3}} 
\right)}\  {e \sp x}}+
{x \sp 5}+
{2 \  {x \sp 4}}+
{x \sp 3} 
\right)}\  {{\sin 
\left(
{{x \sp 2}} 
\right)}\sp 3}}+
\\
\\
\displaystyle
{{\left( 
{3 \  {x \sp 2} \  {{e \sp x} \sp 2}}+
{{\left( -{6 \  {x \sp 3}} -
{6 \  {x \sp 2}} 
\right)}\  {e \sp x}}+
{3 \  {x \sp 4}}+
{6 \  {x \sp 3}}+
{3 \  {x \sp 2}} 
\right)}
\  {{\sin 
\left(
{{x \sp 2}} 
\right)}\sp 2}}+
\\
\\
\displaystyle
{{\left( 
{3 \  x \  {{e \sp x} \sp 2}}+
{{\left( -{6 \  {x \sp 2}} -{6\  x} 
\right)}\  {e \sp x}}+
{3 \  {x \sp 3}}+
{6 \  {x \sp 2}}+
{3 \  x} 
\right)}\  {\sin 
\left(
{{x \sp 2}} 
\right)}}+
{{e\sp x} \sp 2}+
\\
\\
\displaystyle
{{\left( 
-{2 \  x} -
2 
\right)}\  {e \sp x}}+
{x \sp 2}+{2 \  x}+
1 
\end{array}
$$
\returnType{Type: Expression Integer}

You could, of course, use the function \spadfunFrom{eval}{Expression}
within a loop and evaluate {\tt expr} twenty-one times, but this would
be quite slow.  A better way is to create a numerical function {\tt f}
such that {\tt f(x)} is defined by the expression {\tt expr} above,
but without retyping {\tt expr}!  The package {\tt MakeFunction}
provides the operation \spadfunFrom{function}{MakeFunction} which does
exactly this.

Issue this to create the function {\tt f(x)} given by {\tt expr}.

\spadcommand{function(expr, f, x) }
$$
f 
$$
\returnType{Type: Symbol}

To tabulate {\tt expr}, we can now quickly evaluate {\tt f} 21 times.

\spadcommand{tbl := [f(0.1 * i - 1) for i in 0..20]; }
$$
\begin{array}{@{}l}
\left[
{0.0005391844\ 0362701574}, 
{0.0039657551\ 1844206653}, 
\right.
\\
\displaystyle
{0.0088545187\ 4833983689\ 2}, 
{0.0116524883\ 0907069695}, 
\\
\displaystyle
{0.0108618220\ 9245751364\ 5}, 
{0.0076366823\ 2120869965\ 06}, 
\\
\displaystyle
{0.0040584985\ 7597822062\ 55},  
{0.0015349542\ 8910500836\ 48}, 
\\
\displaystyle
{0.0003424903\ 1549879905\ 716},  
{0.0000233304\ 8276098819\ 6001}, 
\\
\displaystyle
{0.0},
{0.0000268186\ 8782862599\ 4229}, 
\\
\displaystyle
{0.0004691571\ 3720051642\ 621}, 
{0.0026924576\ 5968519586\ 08}, 
\\
\displaystyle
{0.0101486881\ 7369135148\ 8}, 
{0.0313833725\ 8543810564\ 3},
\\
\displaystyle
{0.0876991144\ 5154615297\ 9},
{0.2313019789\ 3439968362},
\\
\displaystyle
{0.5843743955\ 958098772},
{1.4114930171\ 992819197},
\\
\displaystyle
\left.
{3.2216948276\ 75164252} 
\right]
\end{array}
$$
\returnType{Type: List Float}

%Original Page 410

Use the list {\tt [x1,...,xn]} as the
third argument to \spadfunFrom{function}{MakeFunction}
to create a multivariate function {\tt f(x1,...,xn)}.

\spadcommand{e := (x - y + 1)**2 * (x**2 * y + 1)**2 }
$$
\begin{array}{@{}l}
{{x \sp 4} \  {y \sp 4}}+
{{\left( 
-{2 \  {x \sp 5}} -
{2 \  {x \sp 4}}+
{2 \  {x \sp 2}} 
\right)}\  {y \sp 3}}+
{{\left( 
{x \sp 6}+
{2 \  {x \sp 5}}+
{x \sp 4} -
{4 \  {x \sp 3}} -
{4 \  {x \sp 2}}+
1 
\right)}\  {y \sp 2}}+
\\
\\
\displaystyle
{{\left( {2 \  {x \sp 4}}+
{4 \  {x \sp 3}}+
{2 \  {x \sp 2}} -
{2 \  x} -
2 
\right)}\  y}+
{x \sp 2}+
{2 \  x}+
1 
\end{array}
$$
\returnType{Type: Polynomial Integer}

\spadcommand{function(e, g, [x, y]) }
$$
g 
$$
\returnType{Type: Symbol}

In the case of just two variables, they can be given as arguments
without making them into a list.

\spadcommand{function(e, h, x, y) }
$$
h 
$$
\returnType{Type: Symbol}

Note that the functions created by \spadfunFrom{function}{MakeFunction}
are not limited to floating point numbers, but can be applied to any type
for which they are defined.

\spadcommand{m1 := squareMatrix [ [1, 2], [3, 4] ] }
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
3 & 4 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{m2 := squareMatrix [ [1, 0], [-1, 1] ] }
$$
\left[
\begin{array}{cc}
1 & 0 \\ 
-1 & 1 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{h(m1, m2) }
$$
\left[
\begin{array}{cc}
-{7836} & {8960} \\ 
-{17132} & {19588} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

For more information, see \sectionref{ugUserMake}.

%Original Page 411

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{MappingPackage1}

Function are objects of type {\tt Mapping}.  In this section we
demonstrate some library operations from the packages 
{\tt MappingPackage1}, {\tt MappingPackage2}, and {\tt MappingPackage3}
that manipulate and create functions.  Some terminology: a 
{\it nullary} function takes no arguments, a {\it unary} function takes 
one argument, and a {\it binary} function takes two arguments.

We begin by creating an example function that raises a
rational number to an integer exponent.

\spadcommand{power(q: FRAC INT, n: INT): FRAC INT == q**n }
\begin{verbatim}
Function declaration power : (Fraction Integer,Integer) -> 
   Fraction Integer has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

\spadcommand{power(2,3) }
\begin{verbatim}
Compiling function power with type (Fraction Integer,Integer) -> 
   Fraction Integer 
\end{verbatim}
$$
8 
$$
\returnType{Type: Fraction Integer}

The \spadfunFrom{twist}{MappingPackage3} operation transposes the
arguments of a binary function.  Here {\tt rewop(a, b)} is 
{\tt power(b, a)}.

\spadcommand{rewop := twist power }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: ((Integer,Fraction Integer) -> Fraction Integer)}

This is $2^3.$

\spadcommand{rewop(3, 2) }
$$
8 
$$
\returnType{Type: Fraction Integer}

Now we define {\tt square} in terms of {\tt power}.

\spadcommand{square: FRAC INT -> FRAC INT }
\returnType{Type: Void}

The \spadfunFrom{curryRight}{MappingPackage3} operation creates a
unary function from a binary one by providing a constant argument on
the right.

\spadcommand{square:= curryRight(power, 2) }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: (Fraction Integer -> Fraction Integer)}

Likewise, the \spadfunFrom{curryLeft}{MappingPackage3} operation
provides a constant argument on the left.

\spadcommand{square 4 }
$$
16 
$$
\returnType{Type: Fraction Integer}

The \spadfunFrom{constantRight}{MappingPackage3} operation creates
(in a trivial way) a binary function from a unary one:
{\tt constantRight(f)} is the function {\tt g} such that
{\tt g(a,b)= f(a).}

\spadcommand{squirrel:= constantRight(square)\$MAPPKG3(FRAC INT,FRAC INT,FRAC INT) }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: ((Fraction Integer,Fraction Integer) -> Fraction Integer)}

%Original Page 412

Likewise, {\tt constantLeft(f)} is the function {\tt g} such that 
{\tt g(a,b)= f(b).}

\spadcommand{squirrel(1/2, 1/3) }
$$
\frac{1}{4} 
$$
\returnType{Type: Fraction Integer}

The \spadfunFrom{curry}{MappingPackage2} operation makes a unary
function nullary.

\spadcommand{sixteen := curry(square, 4/1) }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: (() -> Fraction Integer)}

\spadcommand{sixteen() }
$$
16 
$$
\returnType{Type: Fraction Integer}

The \spadopFrom{*}{MappingPackage3} operation constructs composed
functions.

\spadcommand{square2:=square*square }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: (Fraction Integer -> Fraction Integer)}

\spadcommand{square2  3 }
$$
81 
$$
\returnType{Type: Fraction Integer}

Use the \spadopFrom{**}{MappingPackage1} operation to create functions
that are {\tt n}-fold iterations of other functions.

\spadcommand{sc(x: FRAC INT): FRAC INT == x + 1 }
\begin{verbatim}
Function declaration sc : Fraction Integer -> 
   Fraction Integer has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

This is a list of {\tt Mapping} objects.

\spadcommand{incfns := [sc**i for i in 0..10] }
$$
\begin{array}{@{}l}
\left[
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\right.
\\
\displaystyle
\left.
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)}, 
\mbox{theMap(...)} 
\right]
\end{array}
$$
\returnType{Type: List (Fraction Integer -> Fraction Integer)}

This is a list of applications of those functions.

\spadcommand{[f 4 for f in incfns] }
$$
\left[
4, 5, 6, 7, 8, 9, {10}, {11}, {12}, {13}, {14} 
\right]
$$
\returnType{Type: List Fraction Integer}

%Original Page 413

Use the \spadfunFrom{recur}{MappingPackage1}
operation for recursion:

{\tt g := recur f} means {\tt g(n,x) == f(n,f(n-1,...f(1,x))).}

\spadcommand{times(n:NNI, i:INT):INT == n*i }
\begin{verbatim}
Function declaration times : (NonNegativeInteger,Integer) -> 
   Integer has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

\spadcommand{r := recur(times) }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: ((NonNegativeInteger,Integer) -> Integer)}

This is a factorial function.

\spadcommand{fact := curryRight(r, 1) }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: (NonNegativeInteger -> Integer)}

\spadcommand{fact 4 }
$$
24 
$$
\returnType{Type: PositiveInteger}

Constructed functions can be used within other functions.

\begin{verbatim}
mto2ton(m, n) ==
  raiser := square**n
  raiser m
\end{verbatim}
\returnType{Type: Void}

This is $3^{2^3}.$

\spadcommand{mto2ton(3, 3) }
\begin{verbatim}
   Compiling function mto2ton with type (PositiveInteger,
      PositiveInteger) -> Fraction Integer 
\end{verbatim}
$$
6561 
$$
\returnType{Type: Fraction Integer}

Here {\tt shiftfib} is a unary function that modifies its argument.

\begin{verbatim}
shiftfib(r: List INT) : INT ==
  t := r.1
  r.1 := r.2
  r.2 := r.2 + t
  t

Function declaration shiftfib : List Integer -> Integer 
   has been added to workspace.
\end{verbatim}
\returnType{Type: Void}

By currying over the argument we get a function with private state.

\spadcommand{fibinit: List INT := [0, 1] }
$$
\left[
0, 1 
\right]
$$
\returnType{Type: List Integer}

%Original Page 414

\spadcommand{fibs := curry(shiftfib, fibinit) }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: (() -> Integer)}

\spadcommand{[fibs() for i in 0..30] }
$$
\begin{array}{@{}l}
\left[
0, 1, 1, 2, 3, 5, 8, {13}, {21}, {34}, {55}, 
{89}, {144}, {233}, {377}, {610}, {987}, {1597}, 
\right.
\\
\displaystyle
{2584}, {4181}, {6765}, {10946}, {17711}, {28657}, {46368}, 
{75025}, {121393}, {196418}, 
\\
\displaystyle
\left.
{317811}, {514229}, {832040} 
\right]
\end{array}
$$
\returnType{Type: List Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Matrix}

The {\tt Matrix} domain provides arithmetic operations on matrices
and standard functions from linear algebra.
This domain is similar to the {\tt TwoDimensionalArray} domain, except
that the entries for {\tt Matrix} must belong to a {\tt Ring}.

\subsection{Creating Matrices}

There are many ways to create a matrix from a collection of values or
from existing matrices.

If the matrix has almost all items equal to the same value, use
\spadfunFrom{new}{Matrix} to create a matrix filled with that value
and then reset the entries that are different.

\spadcommand{m : Matrix(Integer) := new(3,3,0) }
$$
\left[
\begin{array}{ccc}
0 & 0 & 0 \\ 
0 & 0 & 0 \\ 
0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

To change the entry in the second row, third column to {\tt 5}, use
\spadfunFrom{setelt}{Matrix}.

\spadcommand{setelt(m,2,3,5) }
$$
5 
$$
\returnType{Type: PositiveInteger}

An alternative syntax is to use assignment.

\spadcommand{m(1,2) := 10 }
$$
10 
$$
\returnType{Type: PositiveInteger}

The matrix was {\it destructively modified}.

\spadcommand{m }
$$
\left[
\begin{array}{ccc}
0 & {10} & 0 \\ 
0 & 0 & 5 \\ 
0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

%Original Page 415

If you already have the matrix entries as a list of lists, use
\spadfunFrom{matrix}{Matrix}.

\spadcommand{matrix [ [1,2,3,4],[0,9,8,7] ]}
$$
\left[
\begin{array}{cccc}
1 & 2 & 3 & 4 \\ 
0 & 9 & 8 & 7 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

If the matrix is diagonal, use \spadfunFrom{diagonalMatrix}{Matrix}.

\spadcommand{dm := diagonalMatrix [1,x**2,x**3,x**4,x**5] }
$$
\left[
\begin{array}{ccccc}
1 & 0 & 0 & 0 & 0 \\ 
0 & {x \sp 2} & 0 & 0 & 0 \\ 
0 & 0 & {x \sp 3} & 0 & 0 \\ 
0 & 0 & 0 & {x \sp 4} & 0 \\ 
0 & 0 & 0 & 0 & {x \sp 5} 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

Use \spadfunFrom{setRow}{Matrix} and \spadfunFrom{setColumn}{Matrix}
to change a row or column of a matrix.

\spadcommand{setRow!(dm,5,vector [1,1,1,1,1]) }
$$
\left[
\begin{array}{ccccc}
1 & 0 & 0 & 0 & 0 \\ 
0 & {x \sp 2} & 0 & 0 & 0 \\ 
0 & 0 & {x \sp 3} & 0 & 0 \\ 
0 & 0 & 0 & {x \sp 4} & 0 \\ 
1 & 1 & 1 & 1 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

\spadcommand{setColumn!(dm,2,vector [y,y,y,y,y]) }
$$
\left[
\begin{array}{ccccc}
1 & y & 0 & 0 & 0 \\ 
0 & y & 0 & 0 & 0 \\ 
0 & y & {x \sp 3} & 0 & 0 \\ 
0 & y & 0 & {x \sp 4} & 0 \\ 
1 & y & 1 & 1 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

Use \spadfunFrom{copy}{Matrix} to make a copy of a matrix.

\spadcommand{cdm := copy(dm) }
$$
\left[
\begin{array}{ccccc}
1 & y & 0 & 0 & 0 \\ 
0 & y & 0 & 0 & 0 \\ 
0 & y & {x \sp 3} & 0 & 0 \\ 
0 & y & 0 & {x \sp 4} & 0 \\ 
1 & y & 1 & 1 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

This is useful if you intend to modify a matrix destructively but
want a copy of the original.

\spadcommand{setelt(dm,4,1,1-x**7) }
$$
-{x \sp 7}+1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{[dm,cdm] }
$$
\left[
{\left[ 
\begin{array}{ccccc}
1 & y & 0 & 0 & 0 \\ 
0 & y & 0 & 0 & 0 \\ 
0 & y & {x \sp 3} & 0 & 0 \\ 
{-{x \sp 7}+1} & y & 0 & {x \sp 4} & 0 \\ 
1 & y & 1 & 1 & 1 
\end{array}
\right]},
{\left[ 
\begin{array}{ccccc}
1 & y & 0 & 0 & 0 \\ 
0 & y & 0 & 0 & 0 \\ 
0 & y & {x \sp 3} & 0 & 0 \\ 
0 & y & 0 & {x \sp 4} & 0 \\ 
1 & y & 1 & 1 & 1 
\end{array}
\right]}
\right]
$$
\returnType{Type: List Matrix Polynomial Integer}

%Original Page 416

Use \spadfunFrom{subMatrix}{Matrix} to extract part of an existing
matrix.  The syntax is {\tt subMatrix({\it m, firstrow, lastrow,
firstcol, lastcol})}.

\spadcommand{subMatrix(dm,2,3,2,4) }
$$
\left[
\begin{array}{ccc}
y & 0 & 0 \\ 
y & {x \sp 3} & 0 
\end{array}
\right]
$$
\returnType{Type: Matrix Polynomial Integer}

To change a submatrix, use \spadfunFrom{setsubMatrix}{Matrix}.

\spadcommand{d := diagonalMatrix [1.2,-1.3,1.4,-1.5] }
$$
\left[
\begin{array}{cccc}
{1.2} & {0.0} & {0.0} & {0.0} \\ 
{0.0} & -{1.3} & {0.0} & {0.0} \\ 
{0.0} & {0.0} & {1.4} & {0.0} \\ 
{0.0} & {0.0} & {0.0} & -{1.5} 
\end{array}
\right]
$$
\returnType{Type: Matrix Float}

If {\tt e} is too big to fit where you specify, an error message is
displayed.  Use \spadfunFrom{subMatrix}{Matrix} to extract part of
{\tt e}, if necessary.

\spadcommand{e := matrix [ [6.7,9.11],[-31.33,67.19] ] }
$$
\left[
\begin{array}{cc}
{6.7} & {9.11} \\ 
-{31.33} & {67.19} 
\end{array}
\right]
$$
\returnType{Type: Matrix Float}

This changes the submatrix of {\tt d} whose upper left corner is
at the first row and second column and whose size is that of {\tt e}.

\spadcommand{setsubMatrix!(d,1,2,e) }
$$
\left[
\begin{array}{cccc}
{1.2} & {6.7} & {9.11} & {0.0} \\ 
{0.0} & -{31.33} & {67.19} & {0.0} \\ 
{0.0} & {0.0} & {1.4} & {0.0} \\ 
{0.0} & {0.0} & {0.0} & -{1.5} 
\end{array}
\right]
$$
\returnType{Type: Matrix Float}

\spadcommand{d }
$$
\left[
\begin{array}{cccc}
{1.2} & {6.7} & {9.11} & {0.0} \\ 
{0.0} & -{31.33} & {67.19} & {0.0} \\ 
{0.0} & {0.0} & {1.4} & {0.0} \\ 
{0.0} & {0.0} & {0.0} & -{1.5} 
\end{array}
\right]
$$
\returnType{Type: Matrix Float}

Matrices can be joined either horizontally or vertically to make
new matrices.

\spadcommand{a := matrix [ [1/2,1/3,1/4],[1/5,1/6,1/7] ] }
$$
\left[
\begin{array}{ccc}
\displaystyle {\frac{1}{2}} & \displaystyle {\frac{1}{3}} & 
\displaystyle {\frac{1}{4}} \\ 
\\
\displaystyle {\frac{1}{5}} & \displaystyle {\frac{1}{6}} & 
\displaystyle {\frac{1}{7}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

%Original Page 417

\spadcommand{b := matrix [ [3/5,3/7,3/11],[3/13,3/17,3/19] ] }
$$
\left[
\begin{array}{ccc}
{\displaystyle \frac{3}{5}} & \displaystyle {\frac{3}{7}} & 
 \displaystyle {\frac{3}{11}} \\ 
\\
 \displaystyle {\frac{3}{13}} & \displaystyle {\frac{3}{17}} & 
 \displaystyle {\frac{3}{19}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

Use \spadfunFrom{horizConcat}{Matrix} to append them side to side.
The two matrices must have the same number of rows.

\spadcommand{horizConcat(a,b) }
$$
\left[
\begin{array}{cccccc}
 \displaystyle {\frac{1}{2}} & \displaystyle {\frac{1}{3}} & 
 \displaystyle {\frac{1}{4}} & \displaystyle {\frac{3}{5}} & 
 \displaystyle {\frac{3}{7}} & \displaystyle {\frac{3}{11}} \\ 
\\
 \displaystyle {\frac{1}{5}} & \displaystyle {\frac{1}{6}} & 
 \displaystyle {\frac{1}{7}} & \displaystyle {\frac{3}{13}} & 
 \displaystyle {\frac{3}{17}} & \displaystyle {\frac{3}{19}}
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

Use \spadfunFrom{vertConcat}{Matrix} to stack one upon the other.
The two matrices must have the same number of columns.

\spadcommand{vab := vertConcat(a,b) }
$$
\left[
\begin{array}{ccc}
\displaystyle 
{\displaystyle \frac{1}{2}} & \displaystyle {\frac{1}{3}} & 
 \displaystyle {\frac{1}{4}} \\ 
\\
{\displaystyle \frac{1}{5}} & \displaystyle {\frac{1}{6}} & 
 \displaystyle {\frac{1}{7}} \\ 
\\
{\displaystyle \frac{3}{5}} & \displaystyle {\frac{3}{7}} & 
 \displaystyle {\frac{3}{11}} \\ 
\\
{\displaystyle \frac{3}{13}} & \displaystyle {\frac{3}{17}} & 
 \displaystyle {\frac{3}{19}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

The operation \spadfunFrom{transpose}{Matrix} is used to create a new
matrix by reflection across the main diagonal.

\spadcommand{transpose vab }
$$
\left[
\begin{array}{cccc}
{\displaystyle \frac{1}{2}} & \displaystyle {\frac{1}{5}} & 
 \displaystyle {\frac{3}{5}} & \displaystyle {\frac{3}{13}} \\ 
\\
{\displaystyle \frac{1}{3}} & \displaystyle {\frac{1}{6}} & 
 \displaystyle {\frac{3}{7}} & \displaystyle {\frac{3}{17}} \\ 
\\
{\displaystyle \frac{1}{4}} & \displaystyle {\frac{1}{7}} & 
 \displaystyle {\frac{3}{11}} & \displaystyle {\frac{3}{19}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

\subsection{Operations on Matrices}

Axiom provides both left and right scalar multiplication.

\spadcommand{m := matrix [ [1,2],[3,4] ] }
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
3 & 4 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

\spadcommand{4 * m * (-5)}
$$
\left[
\begin{array}{cc}
-{20} & -{40} \\ 
-{60} & -{80} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

You can add, subtract, and multiply matrices provided, of course, that
the matrices have compatible dimensions.  If not, an error message is
displayed.

\spadcommand{n := matrix([ [1,0,-2],[-3,5,1] ]) }
$$
\left[
\begin{array}{ccc}
1 & 0 & -2 \\ 
-3 & 5 & 1 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

%Original Page 418

This following product is defined but {\tt n * m} is not.

\spadcommand{m * n }
$$
\left[
\begin{array}{ccc}
-5 & {10} & 0 \\ 
-9 & {20} & -2 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

The operations \spadfunFrom{nrows}{Matrix} and
\spadfunFrom{ncols}{Matrix} return the number of rows and columns of a
matrix.  You can extract a row or a column of a matrix using the
operations \spadfunFrom{row}{Matrix} and \spadfunFrom{column}{Matrix}.
The object returned is a {\tt Vector}.

Here is the third column of the matrix {\tt n}.

\spadcommand{vec := column(n,3)  }
$$
\left[
-2, 1 
\right]
$$
\returnType{Type: Vector Integer}

You can multiply a matrix on the left by a ``row vector'' and on the right
by a ``column vector.''

\spadcommand{vec * m }
$$
\left[
1, 0 
\right]
$$
\returnType{Type: Vector Integer}

Of course, the dimensions of the vector and the matrix must be compatible
or an error message is returned.

\spadcommand{m * vec }
$$
\left[
0, -2 
\right]
$$
\returnType{Type: Vector Integer}

The operation \spadfunFrom{inverse}{Matrix} computes the inverse of a
matrix if the matrix is invertible, and returns {\tt "failed"} if not.

This Hilbert matrix is invertible.

\spadcommand{hilb := matrix([ [1/(i + j) for i in 1..3] for j in 1..3]) }
$$
\left[
\begin{array}{ccc}
\displaystyle
{\frac{1}{2}} & \displaystyle {\frac{1}{3}} & \displaystyle {\frac{1}{4}} \\
\\ 
\displaystyle
{\frac{1}{3}} & \displaystyle {\frac{1}{4}} & \displaystyle {\frac{1}{5}} \\ 
\\
\displaystyle
{\frac{1}{4}} & \displaystyle {\frac{1}{5}} & \displaystyle {\frac{1}{6}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}

\spadcommand{inverse(hilb) }
$$
\left[
\begin{array}{ccc}
{72} & -{240} & {180} \\ 
-{240} & {900} & -{720} \\ 
{180} & -{720} & {600} 
\end{array}
\right]
$$
\returnType{Type: Union(Matrix Fraction Integer,...)}

This matrix is not invertible.

\spadcommand{mm := matrix([ [1,2,3,4], [5,6,7,8], [9,10,11,12], [13,14,15,16] ]) }
$$
\left[
\begin{array}{cccc}
1 & 2 & 3 & 4 \\ 
5 & 6 & 7 & 8 \\ 
9 & {10} & {11} & {12} \\ 
{13} & {14} & {15} & {16} 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

\spadcommand{inverse(mm) }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

%Original Page 419

The operation \spadfunFrom{determinant}{Matrix} computes the
determinant of a matrix provided that the entries of the matrix belong
to a {\tt CommutativeRing}.

The above matrix {\tt mm} is not invertible and, hence, must have
determinant {\tt 0}.

\spadcommand{determinant(mm) }
$$
0 
$$
\returnType{Type: NonNegativeInteger}

The operation \spadfunFrom{trace}{SquareMatrix} computes the trace of
a {\em square} matrix.

\spadcommand{trace(mm) }
$$
34 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{rank}{Matrix} computes the {\it rank} of a
matrix: the maximal number of linearly independent rows or columns.

\spadcommand{rank(mm) }
$$
2 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{nullity}{Matrix} computes the {\it nullity} of
a matrix: the dimension of its null space.

\spadcommand{nullity(mm) }
$$
2 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{nullSpace}{Matrix} returns a list
containing a basis for the null space of a matrix.  Note that the
nullity is the number of elements in a basis for the null space.

\spadcommand{nullSpace(mm) }
$$
\left[
{\left[ 1, -2, 1, 0 
\right]},
{\left[ 2, -3, 0, 1 
\right]}
\right]
$$
\returnType{Type: List Vector Integer}

The operation \spadfunFrom{rowEchelon}{Matrix} returns the row echelon
form of a matrix.  It is easy to see that the rank of this matrix is
two and that its nullity is also two.

\spadcommand{rowEchelon(mm) }
$$
\left[
\begin{array}{cccc}
1 & 2 & 3 & 4 \\ 
0 & 4 & 8 & {12} \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: Matrix Integer}

For more information on related topics, see 
\sectionref{ugIntroTwoDim}, 
\sectionref{ugProblemEigen},\\
\sectionref{ugxFloatHilbert},
\domainref{Permanent}, 
\domainref{Vector},\\ 
\domainref{OneDimensionalArray},
and \domainref{TwoDimensionalArray}.

%Original Page 420

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Multiset}

The domain {\tt Multiset(R)} is similar to {\tt Set(R)} except that
multiplicities (counts of duplications) are maintained and displayed.
Use the operation \spadfunFrom{multiset}{Multiset} to create multisets
from lists.  All the standard operations from sets are available for
multisets.  An element with multiplicity greater than one has the
multiplicity displayed first, then a colon, and then the element.

Create a multiset of integers.

\spadcommand{s := multiset [1,2,3,4,5,4,3,2,3,4,5,6,7,4,10]}
$$
\left\{
7, {2 \mbox{\rm : } 5}, {3 \mbox{\rm : } 3}, 1, {10}, 6, {4 
\mbox{\rm : } 4}, {2 \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset PositiveInteger}

The operation {\tt insert!} adds an element to a multiset.

\spadcommand{insert!(3,s)}
$$
\left\{
7, {2 \mbox{\rm : } 5}, {4 \mbox{\rm : } 3}, 1, {10}, 6, {4 
\mbox{\rm : } 4}, {2 \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset PositiveInteger}

Use {\tt remove!} to remove an element.  If a third argument is
present, it specifies how many instances to remove. Otherwise all
instances of the element are removed.  Display the resulting multiset.

\spadcommand{remove!(3,s,1); s}
$$
\left\{
7, {2 \mbox{\rm : } 5}, {3 \mbox{\rm : } 3}, 1, {10}, 6, {4 
\mbox{\rm : } 4}, {2 \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset PositiveInteger}

\spadcommand{remove!(5,s); s}
$$
\left\{
7, {3 \mbox{\rm : } 3}, 1, {10}, 6, {4 \mbox{\rm : } 4}, {2 
\mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset PositiveInteger}

The operation {\tt count} returns the number of copies of a given value.

\spadcommand{count(5,s)}
$$
0 
$$
\returnType{Type: NonNegativeInteger}

A second multiset.

\spadcommand{t := multiset [2,2,2,-9]}
$$
\left\{
-9, {3 \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset Integer}

The {\tt union} of two multisets is additive.

\spadcommand{U := union(s,t)}
$$
\left\{
7, {3 \mbox{\rm : } 3}, 1, -9, {10}, 6, {4 \mbox{\rm : } 
4}, {5 \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset Integer}

The {\tt intersect} operation gives the elements that are in
common, with additive multiplicity.

\spadcommand{I := intersect(s,t)}
$$
\left\{
{5 \mbox{\rm : } 2} 
\right\}
$$
\returnType{Type: Multiset Integer}

The {\tt difference} of {\tt s} and {\tt t} consists of the elements
that {\tt s} has but {\tt t} does not.  Elements are regarded as
indistinguishable, so that if {\tt s} and {\tt t} have any element in
common, the {\tt difference} does not contain that element.

\spadcommand{difference(s,t)}
$$
\left\{
7, {3 \mbox{\rm : } 3}, 1, {10}, 6, {4 \mbox{\rm : } 4} 
\right\}
$$
\returnType{Type: Multiset Integer}

The {\tt symmetricDifference} is the {\tt union} of {\tt difference(s, t)} 
and {\tt difference(t, s)}.

\spadcommand{S := symmetricDifference(s,t)}
$$
\left\{
7, {3 \mbox{\rm : } 3}, 1, -9, {10}, 6, {4 \mbox{\rm : } 4} 
\right\}
$$
\returnType{Type: Multiset Integer}

%Original Page 421

Check that the {\tt union} of the {\tt symmetricDifference} and
the {\tt intersect} equals the {\tt union} of the elements.

\spadcommand{(U = union(S,I))@Boolean}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Check some inclusion relations.

\spadcommand{t1 := multiset [1,2,2,3]; [t1 < t, t1 < s, t < s, t1 <= s]}
$$
\left[
{\tt false}, {\tt true}, {\tt false}, {\tt true} 
\right]
$$
\returnType{Type: List Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{MultivariatePolynomial}

The domain constructor {\tt MultivariatePolynomial} is similar to {\tt
Polynomial} except that it specifies the variables to be used.  {\tt
Polynomial} are available for {\tt MultivariatePolynomial}.  The
abbreviation for {\tt MultivariatePolynomial} is {\tt MPOLY}.  The
type expressions\\ \centerline{{{\tt MultivariatePolynomial([x,y],Integer)}}} 
and\\ \centerline{{{\tt MPOLY([x,y],INT)}}} refer to the domain of 
multivariate polynomials in the variables {\tt x} and {\tt y} where the 
coefficients are restricted to be integers.  The first variable specified 
is the main variable and the display of the polynomial reflects this.

This polynomial appears with terms in descending powers of the
variable {\tt x}.

\spadcommand{m : MPOLY([x,y],INT) := (x**2 - x*y**3 +3*y)**2 }
$$
{x \sp 4} -{2 \  {y \sp 3} \  {x \sp 3}}+{{\left( {y \sp 6}+{6 \  y} 
\right)}
\  {x \sp 2}} -{6 \  {y \sp 4} \  x}+{9 \  {y \sp 2}} 
$$
\returnType{Type: MultivariatePolynomial([x,y],Integer)}

It is easy to see a different variable ordering by doing a conversion.

\spadcommand{m :: MPOLY([y,x],INT) }
$$
{{x \sp 2} \  {y \sp 6}} -{6 \  x \  {y \sp 4}} -{2 \  {x \sp 3} \  {y \sp 
3}}+{9 \  {y \sp 2}}+{6 \  {x \sp 2} \  y}+{x \sp 4} 
$$
\returnType{Type: MultivariatePolynomial([y,x],Integer)}

You can use other, unspecified variables, by using {\tt Polynomial} in
the coefficient type of {\tt MPOLY}.

\spadcommand{p : MPOLY([x,y],POLY INT) }
\returnType{Type: Void}

\spadcommand{p := (a**2*x - b*y**2 + 1)**2 }
$$
{{a \sp 4} \  {x \sp 2}}+
{{\left( 
-{2 \  {a \sp 2} \  b \  {y \sp 2}}+
{2 \  {a \sp 2}} 
\right)}\  x}+
{{b \sp 2} \  {y \sp 4}} -
{2 \  b \  {y \sp 2}}+
1 
$$
\returnType{Type: MultivariatePolynomial([x,y],Polynomial Integer)}

Conversions can be used to re-express such polynomials in terms of
the other variables.  For example, you can first push all the
variables into a polynomial with integer coefficients.

\spadcommand{p :: POLY INT }
$$
{{b \sp 2} \  {y \sp 4}}+
{{\left( 
-{2 \  {a \sp 2} \  b \  x} -
{2 \  b} 
\right)}\  {y \sp 2}}+
{{a \sp 4} \  {x \sp 2}}+
{2 \  {a \sp 2} \  x}+
1 
$$
\returnType{Type: Polynomial Integer}

%Original Page 422

Now pull out the variables of interest.

\spadcommand{\% :: MPOLY([a,b],POLY INT) }
$$
{{x \sp 2} \  {a \sp 4}}+
{{\left( 
-{2 \  x \  {y \sp 2} \  b}+
{2 \  x} 
\right)}\  {a \sp 2}}+
{{y \sp 4} \  {b \sp 2}} -
{2 \  {y \sp 2} \  b}+
1 
$$
\returnType{Type: MultivariatePolynomial([a,b],Polynomial Integer)}

\boxer{4.6in}{
\noindent {\bf Restriction:}
\begin{quotation}\noindent
Axiom does not allow you to create types where\\
{\tt Multivariate\-Polynomial} is contained in the coefficient type of
{\tt Polynomial}. Therefore,\\
{\tt MPOLY([x,y],POLY INT)} is legal but
{\tt POLY MPOLY([x,y],INT)} is not.
\end{quotation}
.
}

Multivariate polynomials may be combined with univariate polynomials
to create types with special structures.

\spadcommand{q : UP(x, FRAC MPOLY([y,z],INT)) }
\returnType{Type: Void}

This is a polynomial in {\tt x} whose coefficients are quotients of
polynomials in {\tt y} and {\tt z}.

\spadcommand{q := (x**2 - x*(z+1)/y +2)**2 }
$$
{x \sp 4}+{{\frac{-{2 \  z} -2}{y}} \  {x \sp 3}}+
{{\frac{{4 \  {y \sp 2}}+{z \sp 2}+{2 \  z}+1}{y \sp 2}} \  {x \sp 2}}+
{{\frac{-{4 \  z} -4}{y}} \  x}+4 
$$
\returnType{Type: 
UnivariatePolynomial(x,Fraction MultivariatePolynomial([y,z],Integer))}

Use conversions for structural rearrangements.  {\tt z} does not
appear in a denominator and so it can be made the main variable.

\spadcommand{q :: UP(z, FRAC MPOLY([x,y],INT)) }
$$
{{\frac{x \sp 2}{y \sp 2}} \  {z \sp 2}}+
{{\frac{-{2 \  y \  {x \sp 3}}+{2 \  {x \sp 2}} -
{4 \  y \  x}}{y \sp 2}} \  z}+
{\frac{{{y \sp 2} \  {x \sp 4}} -
{2 \  y \  {x \sp 3}}+{{\left( {4 \  {y \sp 2}}+1 
\right)}\  {x \sp 2}} -{4 \  y \  x}+{4 \  {y \sp 2}}}{y \sp 2}} 
$$
\returnType{Type: 
UnivariatePolynomial(z,Fraction MultivariatePolynomial([x,y],Integer))}

Or you can make a multivariate polynomial in {\tt x} and {\tt z}
whose coefficients are fractions in polynomials in {\tt y}.

\spadcommand{q :: MPOLY([x,z], FRAC UP(y,INT)) }
$$
\begin{array}{@{}l}
{x \sp 4}+{{\left( -{{\frac{2}{y}} \  z} -{\frac{2}{y}} \right)}
\  {x \sp 3}}+{{\left( 
{{\frac{1}{y \sp 2}} \  {z \sp 2}}+
{{\frac{2}{y \sp 2}} \  z}+
{\frac{{4 \  {y \sp 2}}+1}{y \sp 2}} 
\right)}\  {x \sp 2}}+
\\
\\
\displaystyle
{{\left( -{{\frac{4}{y}} \  z} -{\frac{4}{y}} \right)}\  x}+4 
\end{array}
$$
\returnType{Type: 
MultivariatePolynomial([x,z],Fraction UnivariatePolynomial(y,Integer))}

A conversion like {\tt q :: MPOLY([x,y], FRAC UP(z,INT))} is not
possible in this example because {\tt y} appears in the denominator of
a fraction.  As you can see, Axiom provides extraordinary flexibility
in the manipulation and display of expressions via its conversion
facility.

For more information on related topics, see \domainref{Polynomial},\\ 
\domainref{UnivariatePolynomial}, and\\
\domainref{DistributedMultivariatePolynomial}.

%Original Page 423

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{None}

The {\tt None} domain is not very useful for interactive work but it
is provided nevertheless for completeness of the Axiom type system.

Probably the only place you will ever see it is if you enter an
empty list with no type information.

\spadcommand{[ ]}
$$
\left[\ 
\right]
$$
\returnType{Type: List None}
Such an empty list can be converted into an empty list
of any other type.

\spadcommand{[ ] :: List Float}
$$
\left[\ 
\right]
$$
\returnType{Type: List Float}

If you wish to produce an empty list of a particular
type directly, such as {\tt List NonNegative\-Integer}, do it this way.

\spadcommand{[ ]\$List(NonNegativeInteger)}
$$
\left[\ 
\right]
$$
\returnType{Type: List NonNegativeInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{NottinghamGroup}

If F is a finite field with $p^n$  elements, then we may form the group
of all formal power series $\{t(1+a_1 t+a_2 t+...)\}$ where $u(0)=0$ and 
$u^{'}(0)=1$ and $a_i \in F$.
The group operation is substitution (composition).
This is called the Nottingham Group. 

The Nottingham Group is the projective limit of finite p-groups.
Every finite p-group can be embedded in the Nottingham Group.
\begin{verbatim}
x:=monomial(1,1)$UFPS PF 1783
\end{verbatim}
$$
x
$$
\returnType{Type: UnivariateFormalPowerSeries(PrimeField(1783))}
\begin{verbatim}
s:=retract(sin x)$NOTTING PF 1783
\end{verbatim}
$$
x+{{297} \ {x^3}}+{{1679} \ {x^5}}+{{427} \ {x^7}}+{{316} \ {x^9}}+{O
\left(
{{x^{11}}}
\right)}
$$
\returnType{Type: NottinghamGroup(PrimeField(1783))}
\begin{verbatim}
s^2
\end{verbatim}
$$
x+{{594} \ {x^3}}+{{535} \ {x^5}}+{{1166} \ {x^7}}+{{1379} \ {x^9}}+{O
\left({{x^{11}}}
\right)}
$$
\returnType{Type: NottinghamGroup(PrimeField(1783))}
\begin{verbatim}
s^-1
\end{verbatim}
$$
x+{{1486} \ {x^3}}+{{847} \ {x^5}}+{{207} \ {x^7}}+{{1701} \ {x^9}}+{O
\left(
{{x^{11}}}
\right)}
$$
\returnType{Type: NottinghamGroup(PrimeField(1783))}
\begin{verbatim}
s^-1*s
\end{verbatim}
$$
x+{O
\left(
{{x^{11}}}
\right)}
$$
\returnType{Type: NottinghamGroup(PrimeField(1783))}
\begin{verbatim}
s*s^-1
\end{verbatim}
$$
x+{O
\left(
{{x^{11}}}
\right)}
$$
\returnType{Type: NottinghamGroup(PrimeField(1783))}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Octonion}

The Octonions, also called the Cayley-Dixon algebra, defined over a
commutative ring are an eight-dimensional non-associative algebra.
Their construction from quaternions is similar to the construction
of quaternions from complex numbers (see \domainref{Quaternion}).

As {\tt Octonion} creates an eight-dimensional algebra, you have to
give eight components to construct an octonion.

\spadcommand{oci1 := octon(1,2,3,4,5,6,7,8) }
$$
1+{2 \  i}+{3 \  j}+{4 \  k}+{5 \  E}+{6 \  I}+{7 \  J}+{8 \  K} 
$$
\returnType{Type: Octonion Integer}

\spadcommand{oci2 := octon(7,2,3,-4,5,6,-7,0) }
$$
7+{2 \  i}+{3 \  j} -{4 \  k}+{5 \  E}+{6 \  I} -{7 \  J} 
$$
\returnType{Type: Octonion Integer}

Or you can use two quaternions to create an octonion.

\spadcommand{oci3 := octon(quatern(-7,-12,3,-10), quatern(5,6,9,0)) }
$$
-7 -{{12} \  i}+{3 \  j} -{{10} \  k}+{5 \  E}+{6 \  I}+{9 \  J} 
$$
\returnType{Type: Octonion Integer}

You can easily demonstrate the non-associativity of multiplication.

\spadcommand{(oci1 * oci2) * oci3 - oci1 * (oci2 * oci3) }
$$
{{2696} \  i} -{{2928} \  j} -{{4072} \  k}+{{16} \  E} -{{1192} \  I}+{{832} 
\  J}+{{2616} \  K} 
$$
\returnType{Type: Octonion Integer}

%Original Page 424

As with the quaternions, we have a real part, the imaginary parts {\tt
i}, {\tt j}, {\tt k}, and four additional imaginary parts {\tt E},
{\tt I}, {\tt J} and {\tt K}.  These parts correspond to the canonical
basis {\tt (1,i,j,k,E,I,J,K)}.

For each basis element there is a component operation to extract
the coefficient of the basis element for a given octonion.

\spadcommand{[real oci1, imagi oci1, imagj oci1, imagk oci1, imagE oci1, imagI oci1, imagJ oci1, imagK oci1] }
$$
\left[
1, 2, 3, 4, 5, 6, 7, 8 
\right]
$$
\returnType{Type: List PositiveInteger}

A basis with respect to the quaternions is given by {\tt (1,E)}.
However, you might ask, what then are the commuting rules?  To answer
this, we create some generic elements.

We do this in Axiom by simply changing the ground ring from {\tt
Integer} to {\tt Polynomial Integer}.

\spadcommand{q : Quaternion Polynomial Integer := quatern(q1, qi, qj, qk) }
$$
q1+{qi \  i}+{qj \  j}+{qk \  k} 
$$
\returnType{Type: Quaternion Polynomial Integer}

\spadcommand{E : Octonion Polynomial Integer:= octon(0,0,0,0,1,0,0,0) }
$$
E 
$$
\returnType{Type: Octonion Polynomial Integer}

Note that quaternions are automatically converted to octonions in the
obvious way.

\spadcommand{q * E }
$$
{q1 \  E}+{qi \  I}+{qj \  J}+{qk \  K} 
$$
\returnType{Type: Octonion Polynomial Integer}

\spadcommand{E * q }
$$
{q1 \  E} -{qi \  I} -{qj \  J} -{qk \  K} 
$$
\returnType{Type: Octonion Polynomial Integer}

\spadcommand{q * 1\$(Octonion Polynomial Integer) }
$$
q1+{qi \  i}+{qj \  j}+{qk \  k} 
$$
\returnType{Type: Octonion Polynomial Integer}

\spadcommand{1\$(Octonion Polynomial Integer) * q }
$$
q1+{qi \  i}+{qj \  j}+{qk \  k} 
$$
\returnType{Type: Octonion Polynomial Integer}

Finally, we check that the \spadfunFrom{norm}{Octonion}, defined as
the sum of the squares of the coefficients, is a multiplicative map.

\spadcommand{o : Octonion Polynomial Integer := octon(o1, oi, oj, ok, oE, oI, oJ, oK) }
$$
o1+{oi \  i}+{oj \  j}+{ok \  k}+{oE \  E}+{oI \  I}+{oJ \  J}+{oK \  K} 
$$
\returnType{Type: Octonion Polynomial Integer}

%Original Page 425

\spadcommand{norm o }
$$
{ok \sp 2}+{oj \sp 2}+{oi \sp 2}+{oK \sp 2}+{oJ \sp 2}+{oI \sp 2}+{oE \sp 
2}+{o1 \sp 2} 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{p : Octonion Polynomial Integer := octon(p1, pi, pj, pk, pE, pI, pJ, pK) }
$$
p1+{pi \  i}+{pj \  j}+{pk \  k}+{pE \  E}+{pI \  I}+{pJ \  J}+{pK \  K} 
$$
\returnType{Type: Octonion Polynomial Integer}

Since the result is {\tt 0}, the norm is multiplicative.

\spadcommand{norm(o*p)-norm(p)*norm(o) }
$$
0 
$$
\returnType{Type: Polynomial Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{OneDimensionalArray}

The {\tt OneDimensionalArray} domain is used for storing data in a
one-dimensional indexed data structure.  Such an array is a
homogeneous data structure in that all the entries of the array must
belong to the same Axiom domain.  Each array has a fixed length
specified by the user and arrays are not extensible.  The indexing of
one-dimensional arrays is one-based.  This means that the ``first''
element of an array is given the index {\tt 1}.  See also
\domainref{Vector} and \domainref{FlexibleArray}.

To create a one-dimensional array, apply the operation 
{\tt oneDimensionalArray} to a list.

\spadcommand{oneDimensionalArray [i**2 for i in 1..10]}
$$
\left[
1, 4, 9, {16}, {25}, {36}, {49}, {64}, {81}, {100} 
\right]
$$
\returnType{Type: OneDimensionalArray PositiveInteger}

Another approach is to first create {\tt a}, a one-dimensional array
of 10 {\tt 0}'s.  {\tt OneDimensional\-Array} has the convenient
abbreviation {\tt ARRAY1}.

\spadcommand{a : ARRAY1 INT := new(10,0)}
$$
\left[
0, 0, 0, 0, 0, 0, 0, 0, 0, 0 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

Set each {\tt i}th element to i, then display the result.

\spadcommand{for i in 1..10 repeat a.i := i; a}
$$
\left[
1, 2, 3, 4, 5, 6, 7, 8, 9, {10} 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

Square each element by mapping the function $i \mapsto i^2$ onto each
element.

\spadcommand{map!(i +-> i ** 2,a); a}
$$
\left[
1, 4, 9, {16}, {25}, {36}, {49}, {64}, {81}, {100} 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

%Original Page 426

Reverse the elements in place.

\spadcommand{reverse! a}
$$
\left[
{100}, {81}, {64}, {49}, {36}, {25}, {16}, 9, 4, 1 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

Swap the {\tt 4}th and {\tt 5}th element.

\spadcommand{swap!(a,4,5); a}
$$
\left[
{100}, {81}, {64}, {36}, {49}, {25}, {16}, 9, 4, 1 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

Sort the elements in place.

\spadcommand{sort! a }
$$
\left[
1, 4, 9, {16}, {25}, {36}, {49}, {64}, {81}, {100} 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

Create a new one-dimensional array {\tt b} containing the last 5
elements of {\tt a}.

\spadcommand{b := a(6..10)}
$$
\left[
{36}, {49}, {64}, {81}, {100} 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

Replace the first 5 elements of {\tt a} with those of {\tt b}.

\spadcommand{copyInto!(a,b,1)}
$$
\left[
{36}, {49}, {64}, {81}, {100}, {36}, {49}, {64}, 
{81}, {100} 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Operator}

Given any ring {\tt R}, the ring of the {\tt Integer}-linear operators
over {\tt R} is called {\tt Operator(R)}.  To create an operator over
{\tt R}, first create a basic operator using the operation 
{\tt operator}, and then convert it to {\tt Operator(R)} for the {\tt R}
you want.

We choose {\tt R} to be the two by two matrices over the integers.

\spadcommand{R := SQMATRIX(2, INT)}
$$
SquareMatrix(2,Integer) 
$$
\returnType{Type: Domain}

Create the operator {\tt tilde} on {\tt R}.

\spadcommand{t := operator("tilde") :: OP(R) }
$$
tilde 
$$
\returnType{Type: Operator SquareMatrix(2,Integer)}

Since {\tt Operator} is unexposed we must either package-call operations
from it, or expose it explicitly.  For convenience we will do the latter.

Expose {\tt Operator}.

\spadcommand{)set expose add constructor Operator }
\begin{verbatim}
   Operator is now explicitly exposed in frame G82322 
\end{verbatim}

To attach an evaluation function (from {\tt R} to {\tt R}) to an
operator over {\tt R}, use {\tt evaluate(op, f)} where {\tt op} is an
operator over {\tt R} and {\tt f} is a function {\tt R -> R}.  This
needs to be done only once when the operator is defined.  Note that
{\tt f} must be {\tt Integer}-linear (that is, 
{\tt f(ax+y) = a f(x) + f(y)} for any integer {\tt a}, and any {\tt x} 
and {\tt y} in {\tt R}).

We now attach the transpose map to the above operator {\tt t}.

\spadcommand{evaluate(t, m +-> transpose m)}
$$
tilde 
$$
\returnType{Type: Operator SquareMatrix(2,Integer)}

%Original Page 427

Operators can be manipulated formally as in any ring: {\tt +} is
the pointwise addition and {\tt *} is composition.  Any element
{\tt x} of {\tt R} can be converted to an operator 
$op_x$ over {\tt R}, and the evaluation function of
$op_x$ is left-multiplication by {\tt x}.

Multiplying on the left by this matrix swaps the two rows.

\spadcommand{s : R := matrix [ [0, 1], [1, 0] ]}
$$
\left[
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

Can you guess what is the action of the following operator?

\spadcommand{rho := t * s}
$$
tilde \  {\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}
$$
\returnType{Type: Operator SquareMatrix(2,Integer)}

Hint: applying {\tt rho} four times gives the identity, so
{\tt rho**4-1} should return 0 when applied to any two by two matrix.

\spadcommand{z := rho**4 - 1}
$$
-1+{tilde \  {\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}
\  tilde \  {\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}
\  tilde \  {\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}
\  tilde \  {\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}}
$$
\returnType{Type: Operator SquareMatrix(2,Integer)}

Now check with this matrix.

\spadcommand{m:R := matrix [ [1, 2], [3, 4] ]}
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
3 & 4 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{z m}
$$
\left[
\begin{array}{cc}
0 & 0 \\ 
0 & 0 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

As you have probably guessed by now, {\tt rho} acts on matrices
by rotating the elements clockwise.

\spadcommand{rho m}
$$
\left[
\begin{array}{cc}
3 & 1 \\ 
4 & 2 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{rho rho m}
$$
\left[
\begin{array}{cc}
4 & 3 \\ 
2 & 1 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

\spadcommand{(rho**3) m}
$$
\left[
\begin{array}{cc}
2 & 4 \\ 
1 & 3 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}

%Original Page 428

Do the swapping of rows and transposition commute?  We can check by
computing their bracket.

\spadcommand{b := t * s - s * t}
$$
-{{\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}
\  tilde}+{tilde \  {\left[ 
\begin{array}{cc}
0 & 1 \\ 
1 & 0 
\end{array}
\right]}}
$$
\returnType{Type: Operator SquareMatrix(2,Integer)}

Now apply it to {\tt m}.

\spadcommand{b m }
$$
\left[
\begin{array}{cc}
1 & -3 \\ 
3 & -1 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Integer)}
 
Next we demonstrate how to define a differential operator on a
polynomial ring.

This is the recursive definition of the {\tt n}-th Legendre polynomial.

\begin{verbatim}
L n ==
  n = 0 => 1
  n = 1 => x
  (2*n-1)/n * x * L(n-1) - (n-1)/n * L(n-2)
\end{verbatim}
\returnType{Type: Void}

Create the differential operator $\frac{d}{dx}$ on polynomials in {\tt x} 
over the rational numbers.

\spadcommand{dx := operator("D") :: OP(POLY FRAC INT) }
$$
D 
$$
\returnType{Type: Operator Polynomial Fraction Integer}

Now attach the map to it.

\spadcommand{evaluate(dx, p +-> D(p, 'x)) }
$$
D 
$$
\returnType{Type: Operator Polynomial Fraction Integer}

This is the differential equation satisfied by the {\tt n}-th
Legendre polynomial.

\spadcommand{E n == (1 - x**2) * dx**2 - 2 * x * dx + n*(n+1) }
\returnType{Type: Void}

Now we verify this for {\tt n = 15}.  Here is the polynomial.

\spadcommand{L 15 }
$$
\begin{array}{@{}l}
{{\frac{9694845}{2048}} \  {x \sp {15}}} -
{{\frac{35102025}{2048}} \  {x \sp {13}}}+
{{\frac{50702925}{2048}} \  {x \sp {11}}} -
{{\frac{37182145}{2048}} \  {x \sp 9}}+
{{\frac{14549535}{2048}} \  {x \sp 7}} -
\\
\\
\displaystyle
{{\frac{2909907}{2048}} \  {x \sp 5}}+
{{\frac{255255}{2048}} \  {x \sp 3}} -
{{\frac{6435}{2048}} \  x} 
\end{array}
$$
\returnType{Type: Polynomial Fraction Integer}

Here is the operator.

\spadcommand{E 15 }
$$
{240} -{2 \  x \  D} -{{\left( {x \sp 2} -1 
\right)}
\  {D \sp 2}} 
$$
\returnType{Type: Operator Polynomial Fraction Integer}

Here is the evaluation.

\spadcommand{(E 15)(L 15) }
$$
0 
$$
\returnType{Type: Polynomial Fraction Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{OrderedVariableList}

The domain {\tt OrderedVariableList} provides symbols which are
restricted to a particular list and have a definite ordering. Those
two features are specified by a {\tt List Symbol} object that is the
argument to the domain.

This is a sample ordering of three symbols.

\spadcommand{ls:List Symbol:=['x,'a,'z] }
$$
\left[
x, a, z 
\right]
$$
\returnType{Type: List Symbol}

Let's build the domain

\spadcommand{Z:=OVAR ls  }
$$
\mbox{\rm OrderedVariableList [x,a,z]} 
$$
\returnType{Type: Domain}

How many variables does it have?

\spadcommand{size()\$Z }
$$
3 
$$
\returnType{Type: NonNegativeInteger}

They are (in the imposed order)

\spadcommand{lv:=[index(i::PI)\$Z for i in 1..size()\$Z] }
$$
\left[
x, a, z 
\right]
$$
\returnType{Type: List OrderedVariableList [x,a,z]}

Check that the ordering is right

\spadcommand{sorted?(>,lv) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%Original Page 429

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{OrderlyDifferentialPolynomial}

Many systems of differential equations may be transformed to
equivalent systems of ordinary differential equations where the
equations are expressed polynomially in terms of the unknown
functions.  In Axiom, the domain constructors 
{\tt OrderlyDifferentialPolynomial} (abbreviated {\tt ODPOL}) and 
{\tt SequentialDifferentialPolynomial} (abbreviation {\tt SDPOL}) implement
two domains of ordinary differential polynomials over any differential
ring.  In the simplest case, this differential ring is usually either
the ring of integers, or the field of rational numbers.  However,
Axiom can handle ordinary differential polynomials over a field of
rational functions in a single indeterminate.

The two domains {\tt ODPOL} and {\tt SDPOL} are almost identical, the
only difference being the choice of a different ranking, which is an
ordering of the derivatives of the indeterminates.  The first domain
uses an orderly ranking, that is, derivatives of higher order are
ranked higher, and derivatives of the same order are ranked
alphabetically.  The second domain uses a sequential ranking, where
derivatives are ordered first alphabetically by the differential
indeterminates, and then by order.  A more general domain constructor,\\
{\tt DifferentialSparseMultivariatePolynomial} (abbreviation 
{\tt DSMP})\\ 
allows both a user-provided list of differential indeterminates
as well as a user-defined ranking.  We shall illustrate 
{\tt ODPOL(FRAC INT)}, which constructs a domain of ordinary differential
polynomials in an arbitrary number of differential indeterminates with
rational numbers as coefficients.

\spadcommand{dpol:= ODPOL(FRAC INT) }
$$
\mbox{\rm OrderlyDifferentialPolynomial Fraction Integer} 
$$
\returnType{Type: Domain}

A differential indeterminate {\tt w} may be viewed as an infinite
sequence of algebraic indeterminates, which are the derivatives of
{\tt w}.  To facilitate referencing these, Axiom provides the
operation \spadfunFrom{makeVariable}{OrderlyDifferentialPolynomial} to
convert an element of type {\tt Symbol} to a map from the natural
numbers to the differential polynomial ring.

\spadcommand{w := makeVariable('w)\$dpol }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: 
(NonNegativeInteger -> OrderlyDifferentialPolynomial Fraction Integer)}

%Original Page 430

\spadcommand{z := makeVariable('z)\$dpol }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: 
(NonNegativeInteger -> OrderlyDifferentialPolynomial Fraction Integer)}

The fifth derivative of {\tt w} can be obtained by applying the map
{\tt w} to the number {\tt 5.}  Note that the order of differentiation
is given as a subscript (except when the order is 0).

\spadcommand{w.5 }
$$
w \sb {5} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

\spadcommand{w 0 }
$$
w 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

The first five derivatives of {\tt z} can be generated by a list.

\spadcommand{[z.i for i in 1..5] }
$$
\left[
{z \sb {1}}, {z \sb {2}}, {z \sb {3}}, {z \sb {4}}, {z \sb {5}} 
\right]
$$
\returnType{Type: List OrderlyDifferentialPolynomial Fraction Integer}

The usual arithmetic can be used to form a differential polynomial from
the derivatives.

\spadcommand{f:= w.4 - w.1 * w.1 * z.3 }
$$
{w \sb {4}} -{{{w \sb {1}} \sp 2} \  {z \sb {3}}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

\spadcommand{g:=(z.1)**3 * (z.2)**2 - w.2 }
$$
{{{z \sb {1}} \sp 3} \  {{z \sb {2}} \sp 2}} -{w \sb {2}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

The operation \spadfunFrom{D}{OrderlyDifferentialPolynomial}
computes the derivative of any differential polynomial.

\spadcommand{D(f) }
$$
{w \sb {5}} -{{{w \sb {1}} \sp 2} \  {z \sb {4}}} -{2 \  {w \sb {1}} \  {w 
\sb {2}} \  {z \sb {3}}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

The same operation can compute higher derivatives, like the
fourth derivative.

\spadcommand{D(f,4) }
$$
\begin{array}{@{}l}
{w \sb {8}} -
{{{w \sb {1}} \sp 2} \  {z \sb {7}}} -
{8 \  {w \sb {1}} \  {w \sb {2}} \  {z \sb {6}}}+
{{\left( 
-{{12} \  {w \sb {1}} \  {w \sb {3}}} -
{{12} \  {{w \sb {2}} \sp 2}} 
\right)}\  {z \sb {5}}} -
{2 \  {w \sb {1}} \  {z \sb {3}} \  {w \sb {5}}}+
\\
\\
\displaystyle
{{\left( 
-{8 \  {w \sb {1}} \  {w \sb {4}}} -
{{24} \  {w \sb {2}} \  {w \sb {3}}} 
\right)}
\  {z \sb {4}}} -
{8 \  {w \sb {2}} \  {z \sb {3}} \  {w \sb {4}}} -
{6 \  {{w \sb {3}} \sp 2} \  {z \sb {3}}} 
\end{array}
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

The operation \spadfunFrom{makeVariable}{OrderlyDifferentialPolynomial}
creates a map to facilitate referencing the derivatives of {\tt f},
similar to the map {\tt w}.

\spadcommand{df:=makeVariable(f)\$dpol }
$$
\mbox{theMap(...)} 
$$
\returnType{Type: 
(NonNegativeInteger -> OrderlyDifferentialPolynomial Fraction Integer)}

%Original Page 431

The fourth derivative of f may be referenced easily.

\spadcommand{df.4 }
$$
\begin{array}{@{}l}
{w \sb {8}} -
{{{w \sb {1}} \sp 2} \  {z \sb {7}}} -
{8 \  {w \sb {1}} \  {w \sb {2}} \  {z \sb {6}}}+
{{\left( 
-{{12} \  {w \sb {1}} \  {w \sb {3}}} -
{{12} \  {{w \sb {2}} \sp 2}} 
\right)}
\  {z \sb {5}}} -
{2 \  {w \sb {1}} \  {z \sb {3}} \  {w \sb {5}}}+
\\
\\
\displaystyle
{{\left( 
-{8 \  {w \sb {1}} \  {w \sb {4}}} -
{{24} \  {w \sb {2}} \  {w \sb {3}}} 
\right)}\  {z \sb {4}}} -
{8 \  {w \sb {2}} \  {z \sb {3}} \  {w \sb {4}}} -
{6 \  {{w \sb {3}} \sp 2} \  {z \sb {3}}} 
\end{array}
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

The operation \spadfunFrom{order}{OrderlyDifferentialPolynomial}
returns the order of a differential polynomial, or the order
in a specified differential indeterminate.

\spadcommand{order(g)  }
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{order(g, 'w)  }
$$
2 
$$
\returnType{Type: PositiveInteger}

The operation
\spadfunFrom{differentialVariables}{OrderlyDifferentialPolynomial} returns
a list of differential indeterminates occurring in a differential polynomial.

\spadcommand{differentialVariables(g)  }
$$
\left[
z, w 
\right]
$$
\returnType{Type: List Symbol}

The operation \spadfunFrom{degree}{OrderlyDifferentialPolynomial} returns
the degree, or the degree in the differential indeterminate specified.

\spadcommand{degree(g) }
$$
{{z \sb {2}} \sp 2} \  {{z \sb {1}} \sp 3} 
$$
\returnType{Type: IndexedExponents OrderlyDifferentialVariable Symbol}

\spadcommand{degree(g, 'w)  }
$$
1 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{weights}{OrderlyDifferentialPolynomial} returns
a list of weights of differential monomials appearing in differential
polynomial, or a list of weights in a specified differential
indeterminate.

\spadcommand{weights(g)  }
$$
\left[
7, 2 
\right]
$$
\returnType{Type: List NonNegativeInteger}

\spadcommand{weights(g,'w) }
$$
\left[
2 
\right]
$$
\returnType{Type: List NonNegativeInteger}

The operation \spadfunFrom{weight}{OrderlyDifferentialPolynomial} returns
the maximum weight of all differential monomials appearing in the
differential polynomial.

\spadcommand{weight(g)  }
$$
7 
$$
\returnType{Type: PositiveInteger}

%Original Page 432

A differential polynomial is {\em isobaric} if the weights of all
differential monomials appearing in it are equal.

\spadcommand{isobaric?(g) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

To substitute {\em differentially}, use
\spadfunFrom{eval}{OrderlyDifferentialPolynomial}.  Note that we must
coerce {\tt 'w} to {\tt Symbol}, since in {\tt ODPOL}, differential
indeterminates belong to the domain {\tt Symbol}.  Compare this result
to the next, which substitutes {\em algebraically} (no substitution is
done since {\tt w.0} does not appear in {\tt g}).

\spadcommand{eval(g,['w::Symbol],[f]) }
$$
-{w \sb {6}}+
{{{w \sb {1}} \sp 2} \  {z \sb {5}}}+
{4 \  {w \sb {1}} \  {w \sb {2}} \  {z \sb {4}}}+
{{\left( {2 \  {w \sb {1}} \  {w \sb {3}}}+
{2 \  {{w \sb {2}} \sp 2}} 
\right)}
\  {z \sb {3}}}+
{{{z \sb {1}} \sp 3} \  {{z \sb {2}} \sp 2}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

\spadcommand{eval(g,variables(w.0),[f]) }
$$
{{{z \sb {1}} \sp 3} \  {{z \sb {2}} \sp 2}} -{w \sb {2}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

Since {\tt OrderlyDifferentialPolynomial} belongs to
{\tt PolynomialCategory}, all the operations defined in the latter
category, or in packages for the latter category, are available.

\spadcommand{monomials(g) }
$$
\left[
{{{z \sb {1}} \sp 3} \  {{z \sb {2}} \sp 2}}, -{w \sb {2}} 
\right]
$$
\returnType{Type: List OrderlyDifferentialPolynomial Fraction Integer}

\spadcommand{variables(g) }
$$
\left[
{z \sb {2}}, {w \sb {2}}, {z \sb {1}} 
\right]
$$
\returnType{Type: List OrderlyDifferentialVariable Symbol}

\spadcommand{gcd(f,g) }
$$
1 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

\spadcommand{groebner([f,g]) }
$$
\left[
{{w \sb {4}} -
{{{w \sb {1}} \sp 2} \  {z \sb {3}}}}, 
{{{{z \sb {1}} \sp 3} \  {{z \sb {2}} \sp 2}} -
{w \sb {2}}} 
\right]
$$
\returnType{Type: List OrderlyDifferentialPolynomial Fraction Integer}

The next three operations are essential for elimination procedures in
differential polynomial rings.  The operation
\spadfunFrom{leader}{OrderlyDifferentialPolynomial} returns the leader
of a differential polynomial, which is the highest ranked derivative
of the differential indeterminates that occurs.

\spadcommand{lg:=leader(g)  }
$$
z \sb {2} 
$$
\returnType{Type: OrderlyDifferentialVariable Symbol}

%Original Page 433

The operation \spadfunFrom{separant}{OrderlyDifferentialPolynomial} returns
the separant of a differential polynomial, which is the partial derivative
with respect to the leader.

\spadcommand{sg:=separant(g)  }
$$
2 \  {{z \sb {1}} \sp 3} \  {z \sb {2}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

The operation \spadfunFrom{initial}{OrderlyDifferentialPolynomial} returns
the initial, which is the leading coefficient when the given differential
polynomial is expressed as a polynomial in the leader.

\spadcommand{ig:=initial(g)  }
$$
{z \sb {1}} \sp 3 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

Using these three operations, it is possible to reduce {\tt f} modulo
the differential ideal generated by {\tt g}.  The general scheme is to
first reduce the order, then reduce the degree in the leader.  First,
eliminate {\tt z.3} using the derivative of {\tt g}.

\spadcommand{g1 := D g }
$$
{2 \  {{z \sb {1}} \sp 3} \  {z \sb {2}} \  {z \sb {3}}} -
{w \sb {3}}+
{3 \  {{z \sb {1}} \sp 2} \  {{z \sb {2}} \sp 3}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

Find its leader.

\spadcommand{lg1:= leader g1 }
$$
z \sb {3} 
$$
\returnType{Type: OrderlyDifferentialVariable Symbol}

Differentiate {\tt f} partially with respect to this leader.

\spadcommand{pdf:=D(f, lg1) }
$$
-{{w \sb {1}} \sp 2} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

Compute the partial remainder of {\tt f} with respect to {\tt g}.

\spadcommand{prf:=sg * f- pdf * g1 }
$$
{2 \  {{z \sb {1}} \sp 3} \  {z \sb {2}} \  {w \sb {4}}} -
{{{w \sb {1}} \sp 2} \  {w \sb {3}}}+
{3 \  {{w \sb {1}} \sp 2} \  {{z \sb {1}} \sp 2} \  {{z \sb {2}} \sp 3}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

Note that high powers of {\tt lg} still appear in {\tt prf}.  Compute
the leading coefficient of {\tt prf} as a polynomial in the leader of
{\tt g}.

\spadcommand{lcf:=leadingCoefficient univariate(prf, lg) }
$$
3 \  {{w \sb {1}} \sp 2} \  {{z \sb {1}} \sp 2} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

Finally, continue eliminating the high powers of {\tt lg} appearing in
{\tt prf} to obtain the (pseudo) remainder of {\tt f} modulo {\tt g}
and its derivatives.

\spadcommand{ig * prf - lcf * g * lg }
$$
{2 \  {{z \sb {1}} \sp 6} \  {z \sb {2}} \  {w \sb {4}}} -
{{{w \sb {1}} \sp 2} \  {{z \sb {1}} \sp 3} \  {w \sb {3}}}+
{3 \  {{w \sb {1}} \sp 2} \  {{z \sb {1}} \sp 2} 
\  {w \sb {2}} \  {z \sb {2}}} 
$$
\returnType{Type: OrderlyDifferentialPolynomial Fraction Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{PartialFraction}

A {\it partial fraction} is a decomposition of a quotient into a sum
of quotients where the denominators of the summands are powers of
primes.\footnote{Most people first encounter partial fractions when
they are learning integral calculus.  For a technical discussion of
partial fractions, see, for example, Lang's {\it Algebra.}} For
example, the rational number {\tt 1/6} is decomposed into {\tt 1/2-1/3}.  

%Original Page 434

You can compute partial fractions of quotients of objects from
domains belonging to the category {\tt EuclideanDomain}.  For example,
{\tt Integer}, {\tt Complex Integer}, and 
{\tt Univariate\-Polynomial(x, Fraction Integer)} 
all belong to {\tt EuclideanDomain}.  In the
examples following, we demonstrate how to decompose quotients of each
of these kinds of object into partial fractions.  Issue the system
command {\tt )show PartialFraction} to display the full list of
operations defined by {\tt PartialFraction}.

It is necessary that we know how to factor the denominator when we
want to compute a partial fraction.  Although the interpreter can
often do this automatically, it may be necessary for you to include a
call to {\tt factor}.  In these examples, it is not necessary to
factor the denominators explicitly.

The main operation for computing partial fractions is called
\spadfunFrom{partialFraction}{PartialFraction} and we use this to
compute a decomposition of {\tt 1 / 10!}.  The first argument to
\spadfunFrom{partialFraction}{PartialFraction} is the numerator of the
quotient and the second argument is the factored denominator.

\spadcommand{partialFraction(1,factorial 10) }
$$
{\frac{159}{2 \sp 8}} -{\frac{23}{3 \sp 4}} -{\frac{12}{5 \sp 2}}
+{\frac{1}{7}} 
$$
\returnType{Type: PartialFraction Integer}

Since the denominators are powers of primes, it may be possible
to expand the numerators further with respect to those primes. Use the
operation \spadfunFrom{padicFraction}{PartialFraction} to do this.

\spadcommand{f := padicFraction(\%) }
$$
{\frac{1}{2}}+{\frac{1}{2 \sp 4}}+{\frac{1}{2 \sp 5}}+{\frac{1}{2 \sp 6}}
+{\frac{1}{2 \sp 7}}+{\frac{1}{2 \sp 8}} -{\frac{2}{3 \sp 2}} 
-{\frac{1}{3 \sp 3}} -{\frac{2}{3 \sp 4}} -{\frac{2}{5}} 
-{\frac{2}{5 \sp 2}}+{\frac{1}{7}} 
$$
\returnType{Type: PartialFraction Integer}

The operation \spadfunFrom{compactFraction}{PartialFraction} returns
an expanded fraction into the usual form.  The compacted version is
used internally for computational efficiency.

\spadcommand{compactFraction(f) }
$$
{\frac{159}{2 \sp 8}} -{\frac{23}{3 \sp 4}} -{\frac{12}{5 \sp 2}}
+{\frac{1}{7}} 
$$
\returnType{Type: PartialFraction Integer}

You can add, subtract, multiply and divide partial fractions.  In
addition, you can extract the parts of the decomposition.
\spadfunFrom{numberOfFractionalTerms}{PartialFraction} computes the
number of terms in the fractional part.  This does not include the
whole part of the fraction, which you get by calling
\spadfunFrom{wholePart}{PartialFraction}.  In this example, the whole
part is just {\tt 0}.

\spadcommand{numberOfFractionalTerms(f) }
$$
12 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{nthFractionalTerm}{PartialFraction} returns
the individual terms in the decomposition.  Notice that the object
returned is a partial fraction itself.
\spadfunFrom{firstNumer}{PartialFraction} and
\spadfunFrom{firstDenom}{PartialFraction} extract the numerator and
denominator of the first term of the fraction.

%Original Page 435

\spadcommand{nthFractionalTerm(f,3) }
$$
\frac{1}{2 \sp 5} 
$$
\returnType{Type: PartialFraction Integer}

Given two gaussian integers (see \domainref{Complex}), you can
decompose their quotient into a partial fraction.

\spadcommand{partialFraction(1,- 13 + 14 * \%i) }
$$
-{\frac{1}{1+{2 \  i}}}+{\frac{4}{3+{8 \  i}}} 
$$
\returnType{Type: PartialFraction Complex Integer}

To convert back to a quotient, simply use a conversion.

\spadcommand{\% :: Fraction Complex Integer }
$$
-{\frac{i}{{14}+{{13} \  i}}} 
$$
\returnType{Type: Fraction Complex Integer}

To conclude this section, we compute the decomposition of
\begin{verbatim}
                   1
     -------------------------------
                   2       3       4
     (x + 1)(x + 2) (x + 3) (x + 4)
\end{verbatim}

The polynomials in this object have type
{\tt UnivariatePolynomial(x, Fraction Integer)}.

We use the \spadfunFrom{primeFactor}{Factored} operation (see
\domainref{Factored}) to create the denominator in factored form directly.

\spadcommand{u : FR UP(x, FRAC INT) := reduce(*,[primeFactor(x+i,i) for i in 1..4]) }
$$
{\left( x+1 \right)}
\  {{\left( x+2 \right)}\sp 2} 
\  {{\left( x+3 \right)}\sp 3} 
\  {{\left( x+4 \right)}\sp 4} 
$$
\returnType{Type: Factored UnivariatePolynomial(x,Fraction Integer)}

These are the compact and expanded partial fractions for the quotient.

\spadcommand{partialFraction(1,u) }
$$
\begin{array}{@{}l}
\displaystyle
{\frac{\frac{1}{648}}{x+1}}+
{\frac{{{\frac{1}{4}} \  x}+
{\frac{7}{16}}}{{\left( x+2 \right)}\sp 2}}+
{\frac{-{{\frac{17}{8}} \  {x \sp 2}} -{{12} \  x} -
{\frac{139}{8}}}{{\left( x+3 \right)}\sp 3}}+
\\
\\
\displaystyle
{\frac{{{\frac{607}{324}} \  {x \sp 3}}+
{{\frac{10115}{432}} \  {x \sp 2}}+
{{\frac{391}{4}} \  x}+
{\frac{44179}{324}}} 
{{\left( x+4 \right)}\sp 4}} 
\end{array}
$$
\returnType{Type: PartialFraction UnivariatePolynomial(x,Fraction Integer)}

%Original Page 436

\spadcommand{padicFraction \% }
$$
\begin{array}{@{}l}
\displaystyle
{\frac{\frac{1}{648}}{x+1}}+
{\frac{\frac{1}{4}}{x+2}} -
{\frac{\frac{1}{16}}{{\left( x+2 \right)}\sp 2}} -
{\frac{\frac{17}{8}}{x+3}}+
{\frac{\frac{3}{4}}{{\left( x+3 \right)}\sp 2}} -
{\frac{\frac{1}{2}}{{\left( x+3 \right)}\sp 3}}+
{\frac{\frac{607}{324}}{x+4}}+
\\
\\
\displaystyle
{\frac{\frac{403}{432}}{{\left( x+4 \right)}\sp 2}}+
{\frac{\frac{13}{36}}{{\left( x+4 \right)}\sp 3}}+
{\frac{\frac{1}{12}}{{\left( x+4 \right)}\sp 4}} 
\end{array}
$$
\returnType{Type: PartialFraction UnivariatePolynomial(x,Fraction Integer)}

All see \domainref{FullPartialFractionExpansion} for examples of
factor-free conversion of quotients to full partial fractions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Permanent}

The package {\tt Permanent} provides the function
\spadfunFrom{permanent}{Permanent} for square matrices.  The
\spadfunFrom{permanent}{Permanent} of a square matrix can be computed
in the same way as the determinant by expansion of minors except that
for the permanent the sign for each element is {\tt 1}, rather than
being {\tt 1} if the row plus column indices is positive and {\tt -1}
otherwise.  This function is much more difficult to compute
efficiently than the \spadfunFrom{determinant}{Matrix}.  An example of
the use of \spadfunFrom{permanent}{Permanent} is the calculation of
the $n$-th derangement number, defined to be the number of
different possibilities for {\tt n} couples to dance but never with
their own spouse.

Consider an {\tt n} by {\tt n} matrix with entries {\tt 0} on the
diagonal and {\tt 1} elsewhere.  Think of the rows as one-half of each
couple (for example, the males) and the columns the other half.  The
permanent of such a matrix gives the desired derangement number.

\begin{verbatim}
kn n ==
  r : MATRIX INT := new(n,n,1)
  for i in 1..n repeat
    r.i.i := 0
  r
\end{verbatim}
\returnType{Type: Void}

Here are some derangement numbers, which you see grow quite fast.

\spadcommand{permanent(kn(5) :: SQMATRIX(5,INT)) }
\begin{verbatim}
Compiling function kn with type PositiveInteger -> Matrix Integer 
\end{verbatim}
$$
44 
$$
\returnType{Type: PositiveInteger}

\spadcommand{[permanent(kn(n) :: SQMATRIX(n,INT)) for n in 1..13] }
\begin{verbatim}
Cannot compile conversion for types involving local variables. 
   In particular, could not compile the expression involving 
   :: SQMATRIX(n,INT) 
Axiom will attempt to step through and interpret the code.
\end{verbatim}
$$
\begin{array}{@{}l}
\left[
0, 1, 2, 9, {44}, {265}, {1854}, {14833}, {133496}, 
\right.
\\
\displaystyle
\left.
{1334961}, {14684570}, {176214841}, {2290792932} 
\right]
\end{array}
$$
\returnType{Type: List NonNegativeInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Permutation}


We represent a permutation as two lists of equal length representing preimages
and images of moved points. Fixed points do not occur in either of these
lists. This enables us to compute the set of fixed points and the set of moved
points easily.
\begin{verbatim} 
  p := coercePreimagesImages([ [1,2,3],[1,2,3] ])
    1
                      Type: Permutation PositiveInteger
\end{verbatim}
\begin{verbatim}
  movedPoints p
    {}
                      Type: Set PositiveInteger
\end{verbatim}
\begin{verbatim}
  even? p
    true
                       Type: Boolean
\end{verbatim}
\begin{verbatim}
  p := coercePreimagesImages([ [0,1,2,3],[3,0,2,1] ])$PERM ZMOD 4
    (1 0 3)
                       Type: Permutation IntegerMod 4
\end{verbatim}
\begin{verbatim}
  fixedPoints p
    {2}
                       Type: Set IntegerMod 4
\end{verbatim}
\begin{verbatim}
  q := coercePreimagesImages([ [0,1,2,3],[1,0] ])$PERM ZMOD 4
    (1 0)
                       Type: Permutation IntegerMod 4
\end{verbatim}
\begin{verbatim}
  fixedPoints(p*q)
    {2,0}
                       Type: Set IntegerMod 4
\end{verbatim}
\begin{verbatim}
  even?(p*q)
    false
                       Type: Boolean
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Polynomial}

The domain constructor {\tt Polynomial} (abbreviation: {\tt POLY})
provides polynomials with an arbitrary number of unspecified
variables.

%Original Page 437

It is used to create the default polynomial domains in Axiom.
Here the coefficients are integers.

\spadcommand{x + 1}
$$
x+1 
$$
\returnType{Type: Polynomial Integer}

Here the coefficients have type {\tt Float}.

\spadcommand{z - 2.3}
$$
z -{2.3} 
$$
\returnType{Type: Polynomial Float}

And here we have a polynomial in two variables with coefficients which
have type {\tt Fraction Integer}.

\spadcommand{y**2 - z + 3/4}
$$
-z+{y \sp 2}+{\frac{3}{4}} 
$$
\returnType{Type: Polynomial Fraction Integer}

The representation of objects of domains created by {\tt Polynomial}
is that of recursive univariate polynomials.\footnote{The term
{\tt univariate} means ``one variable.'' {\tt multivariate} means
``possibly more than one variable.''}

This recursive structure is sometimes obvious from the display of
a polynomial.

\spadcommand{y **2 + x*y + y }
$$
{y \sp 2}+{{\left( x+1 
\right)}
\  y} 
$$
\returnType{Type: Polynomial Integer}

In this example, you see that the polynomial is stored as a polynomial
in {\tt y} with coefficients that are polynomials in {\tt x} with
integer coefficients.  In fact, you really don't need to worry about
the representation unless you are working on an advanced application
where it is critical.  The polynomial types created from {\tt
DistributedMultivariatePolynomial} and\\
{\tt NewDistributedMultivariatePolynomial} (discussed in\\
\domainref{DistributedMultivariatePolynomial}) are stored and
displayed in a non-recursive manner.

You see a ``flat'' display of the above polynomial by converting to
one of those types.

\spadcommand{\% :: DMP([y,x],INT) }
$$
{y \sp 2}+{y \  x}+y 
$$
\returnType{Type: DistributedMultivariatePolynomial([y,x],Integer)}

We will demonstrate many of the polynomial facilities by using two
polynomials with integer coefficients.

By default, the interpreter expands polynomial expressions, even if they
are written in a factored format.

\spadcommand{p := (y-1)**2 * x * z }
$$
{\left( {x \  {y \sp 2}} -{2 \  x \  y}+x 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

See \domainref{Factored} to see how to create objects in 
factored form directly.

\spadcommand{q := (y-1) * x * (z+5) }
$$
{{\left( {x \  y} -x 
\right)}
\  z}+{5 \  x \  y} -{5 \  x} 
$$
\returnType{Type: Polynomial Integer}

%Original Page 438

The fully factored form can be recovered by using
\spadfunFrom{factor}{Polynomial}.

\spadcommand{factor(q) }
$$
x \  {\left( y -1 
\right)}
\  {\left( z+5 
\right)}
$$
\returnType{Type: Factored Polynomial Integer}

This is the same name used for the operation to factor integers.  Such
reuse of names is called \index{overloading} and makes it much easier
to think of solving problems in general ways.  Axiom facilities for
factoring polynomials created with {\tt Polynomial} are currently
restricted to the integer and rational number coefficient cases.
There are more complete facilities for factoring univariate
polynomials: see \sectionref{ugProblemFactor}.

The standard arithmetic operations are available for polynomials.

\spadcommand{p - q**2}
$$
\begin{array}{@{}l}
{{\left( 
-{{x \sp 2} \  {y \sp 2}}+
{2 \  {x \sp 2} \  y} -
{x \sp 2} 
\right)}\  {z \sp 2}}+
\\
\\
\displaystyle
{{\left( 
{{\left( 
-{{10} \  {x \sp 2}}+x 
\right)}\  {y \sp 2}}+
{{\left( 
{{20} \  {x \sp 2}} -
{2 \  x} 
\right)}\  y} 
-{{10} \  {x \sp 2}}+
x 
\right)}\  z} -
\\
\\
\displaystyle
{{25} \  {x \sp 2} \  {y \sp 2}}+
{{50} \  {x \sp 2} \  y} -
{{25} \  {x \sp 2}} 
\end{array}
$$
\returnType{Type: Polynomial Integer}

The operation \spadfunFrom{gcd}{Polynomial} is used to compute the
greatest common divisor of two polynomials.

\spadcommand{gcd(p,q) }
$$
{x \  y} -x 
$$
\returnType{Type: Polynomial Integer}

In the case of {\tt p} and {\tt q}, the gcd is obvious from their
definitions.  We factor the gcd to show this relationship better.

\spadcommand{factor \% }
$$
x \  {\left( y -1 
\right)}
$$
\returnType{Type: Factored Polynomial Integer}

The least common multiple is computed by using \spadfunFrom{lcm}{Polynomial}.

\spadcommand{lcm(p,q) }
$$
{{\left( {x \  {y \sp 2}} -{2 \  x \  y}+x 
\right)}
\  {z \sp 2}}+{{\left( {5 \  x \  {y \sp 2}} -{{10} \  x \  y}+{5 \  x} 
\right)}
\  z} 
$$
\returnType{Type: Polynomial Integer}

Use \spadfunFrom{content}{Polynomial} to compute the greatest common
divisor of the coefficients of the polynomial.

\spadcommand{content p }
$$
1 
$$
\returnType{Type: PositiveInteger}

Many of the operations on polynomials require you to specify a
variable.  For example, \spadfunFrom{resultant}{Polynomial} requires
you to give the variable in which the polynomials should be expressed.

%Original Page 439

This computes the resultant of the values of {\tt p} and {\tt q},
considering them as polynomials in the variable {\tt z}.  They do not
share a root when thought of as polynomials in {\tt z}.

\spadcommand{resultant(p,q,z) }
$$
{5 \  {x \sp 2} \  {y \sp 3}} -{{15} \  {x \sp 2} \  {y \sp 2}}+{{15} \  {x 
\sp 2} \  y} -{5 \  {x \sp 2}} 
$$
\returnType{Type: Polynomial Integer}

This value is {\tt 0} because as polynomials in {\tt x} the polynomials
have a common root.

\spadcommand{resultant(p,q,x) }
$$
0 
$$
\returnType{Type: Polynomial Integer}

The data type used for the variables created by {\tt Polynomial} is
{\tt Symbol}.  As mentioned above, the representation used by {\tt
Polynomial} is recursive and so there is a main variable for
nonconstant polynomials.

The operation \spadfunFrom{mainVariable}{Polynomial} returns this
variable.  The return type is actually a union of {\tt Symbol} and
{\tt "failed"}.

\spadcommand{mainVariable p }
$$
z 
$$
\returnType{Type: Union(Symbol,...)}

The latter branch of the union is be used if the polynomial has no
variables, that is, is a constant.

\spadcommand{mainVariable(1 :: POLY INT)}
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

You can also use the predicate \spadfunFrom{ground?}{Polynomial} to test
whether a polynomial is in fact a member of its ground ring.

\spadcommand{ground? p }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{ground?(1 :: POLY INT)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The complete list of variables actually used in a particular
polynomial is returned by \spadfunFrom{variables}{Polynomial}.  For
constant polynomials, this list is empty.

\spadcommand{variables p }
$$
\left[
z, y, x 
\right]
$$
\returnType{Type: List Symbol}

The \spadfunFrom{degree}{Polynomial} operation returns the
degree of a polynomial in a specific variable.

\spadcommand{degree(p,x) }
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{degree(p,y) }
$$
2 
$$
\returnType{Type: PositiveInteger}

%Original Page 440

\spadcommand{degree(p,z) }
$$
1 
$$
\returnType{Type: PositiveInteger}

If you give a list of variables for the second argument, a list
of the degrees in those variables is returned.

\spadcommand{degree(p,[x,y,z]) }
$$
\left[
1, 2, 1 
\right]
$$
\returnType{Type: List NonNegativeInteger}

The minimum degree of a variable in a polynomial is computed using
\spadfunFrom{minimumDegree}{Polynomial}.

\spadcommand{minimumDegree(p,z) }
$$
1 
$$
\returnType{Type: PositiveInteger}

The total degree of a polynomial is returned by
\spadfunFrom{totalDegree}{Polynomial}.

\spadcommand{totalDegree p }
$$
4 
$$
\returnType{Type: PositiveInteger}

It is often convenient to think of a polynomial as a leading monomial plus
the remaining terms.

\spadcommand{leadingMonomial p }
$$
x \  {y \sp 2} \  z 
$$
\returnType{Type: Polynomial Integer}

The \spadfunFrom{reductum}{Polynomial} operation returns a polynomial
consisting of the sum of the monomials after the first.

\spadcommand{reductum p }
$$
{\left( -{2 \  x \  y}+x 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

These have the obvious relationship that the original polynomial
is equal to the leading monomial plus the reductum.

\spadcommand{p - leadingMonomial p - reductum p }
$$
0 
$$
\returnType{Type: Polynomial Integer}

The value returned by \spadfunFrom{leadingMonomial}{Polynomial}
includes the coefficient of that term.  This is extracted by using
\spadfunFrom{leadingCoefficient}{Polynomial} on the original
polynomial.

\spadcommand{leadingCoefficient p }
$$
1 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{eval}{Polynomial} is used to substitute a value
for a variable in a polynomial.

\spadcommand{p  }
$$
{\left( {x \  {y \sp 2}} -{2 \  x \  y}+x 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

This value may be another variable, a constant or a polynomial.

\spadcommand{eval(p,x,w) }
$$
{\left( {w \  {y \sp 2}} -{2 \  w \  y}+w 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

%Original Page 441

\spadcommand{eval(p,x,1) }
$$
{\left( {y \sp 2} -{2 \  y}+1 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

Actually, all the things being substituted are just polynomials,
some more trivial than others.

\spadcommand{eval(p,x,y**2 - 1) }
$$
{\left( {y \sp 4} -{2 \  {y \sp 3}}+{2 \  y} -1 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

Derivatives are computed using the \spadfunFrom{D}{Polynomial} operation.

\spadcommand{D(p,x) }
$$
{\left( {y \sp 2} -{2 \  y}+1 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

The first argument is the polynomial and the second is the variable.

\spadcommand{D(p,y) }
$$
{\left( {2 \  x \  y} -{2 \  x} 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

Even if the polynomial has only one variable, you must specify it.

\spadcommand{D(p,z) }
$$
{x \  {y \sp 2}} -{2 \  x \  y}+x 
$$
\returnType{Type: Polynomial Integer}

Integration of polynomials is similar and the
\spadfunFrom{integrate}{Polynomial} operation is used.

Integration requires that the coefficients support division.
Consequently, Axiom converts polynomials over the integers to
polynomials over the rational numbers before integrating them.

\spadcommand{integrate(p,y) }
$$
{\left( {{\frac{1}{3}} \  x \  {y \sp 3}} -{x \  {y \sp 2}}+{x \  y} 
\right)}
\  z 
$$
\returnType{Type: Polynomial Fraction Integer}

It is not possible, in general, to divide two polynomials.  In our
example using polynomials over the integers, the operation
\spadfunFrom{monicDivide}{Polynomial} divides a polynomial by a monic
polynomial (that is, a polynomial with leading coefficient equal to
1).  The result is a record of the quotient and remainder of the
division.

You must specify the variable in which to express the polynomial.

\spadcommand{qr := monicDivide(p,x+1,x) }
$$
\left[
{quotient={{\left( {y \sp 2} -{2 \  y}+1 
\right)}
\  z}}, {remainder={{\left( -{y \sp 2}+{2 \  y} -1 
\right)}
\  z}} 
\right]
$$
\returnType{Type: Record(quotient: Polynomial Integer,remainder: Polynomial Integer)}

The selectors of the components of the record are {\tt quotient} and
{\tt remainder}.  Issue this to extract the remainder.

\spadcommand{qr.remainder }
$$
{\left( -{y \sp 2}+{2 \  y} -1 
\right)}
\  z 
$$
\returnType{Type: Polynomial Integer}

%Original Page 442

Now that we can extract the components, we can demonstrate the
relationship among them and the arguments to our original expression
{\tt qr := monicDivide(p,x+1,x)}.

\spadcommand{p - ((x+1) * qr.quotient + qr.remainder) }
$$
0 
$$
\returnType{Type: Polynomial Integer}

If the \spadopFrom{/}{Fraction} operator is used with polynomials, a
fraction object is created.  In this example, the result is an object
of type {\tt Fraction Polynomial Integer}.

\spadcommand{p/q }
$$
\frac{{\left( y -1 \right)}\  z}{z+5} 
$$
\returnType{Type: Fraction Polynomial Integer}

If you use rational numbers as polynomial coefficients, the\\
resulting object is of type {\tt Polynomial Fraction Integer}.

\spadcommand{(2/3) * x**2 - y + 4/5 }
$$
-y+{{\frac{2}{3}} \  {x \sp 2}}+{\frac{4}{5}} 
$$
\returnType{Type: Polynomial Fraction Integer}

This can be converted to a fraction of polynomials and back again, if
required.

\spadcommand{\% :: FRAC POLY INT }
$$
\frac{-{{15} \  y}+{{10} \  {x \sp 2}}+{12}}{15} 
$$
\returnType{Type: Fraction Polynomial Integer}

\spadcommand{\% :: POLY FRAC INT }
$$
-y+{{\frac{2}{3}} \  {x \sp 2}}+{\frac{4}{5}} 
$$
\returnType{Type: Polynomial Fraction Integer}

To convert the coefficients to floating point, map the {\tt numeric}
operation on the coefficients of the polynomial.

\spadcommand{map(numeric,\%) }
$$
-{{1.0} \  y}+{{0.6666666666 6666666667} \  {x \sp 2}}+{0.8} 
$$
\returnType{Type: Polynomial Float}

For more information on related topics, see
\domainref{UnivariatePolynomial}, \domainref{MultivariatePolynomial}, and
\domainref{DistributedMultivariatePolynomial}.  You can also issue
the system command {\tt )show Polynomial} to display the full list
of operations defined by {\tt Polynomial}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Quaternion}

The domain constructor {\tt Quaternion} implements quaternions over
commutative rings.  For information on related topics, see
\domainref{Complex} and \domainref{Octonion}.
You can also issue the system command
{\tt )show Quaternion} to display the full list of operations
defined by {\tt Quaternion}.

The basic operation for creating quaternions is
\spadfunFrom{quatern}{Quaternion}.
This is a quaternion over the rational numbers.

\spadcommand{q := quatern(2/11,-8,3/4,1) }
$$
{\frac{2}{11}} -{8 \  i}+{{\frac{3}{4}} \  j}+k 
$$
\returnType{Type: Quaternion Fraction Integer}

%Original Page 443

The four arguments are the real part, the {\tt i} imaginary part, the
{\tt j} imaginary part, and the {\tt k} imaginary part, respectively.

\spadcommand{[real q, imagI q, imagJ q, imagK q] }
$$
\left[
{\frac{2}{11}}, -8, {\frac{3}{4}}, 1 
\right]
$$
\returnType{Type: List Fraction Integer}

Because {\tt q} is over the rationals (and nonzero), you can invert it.

\spadcommand{inv q }
$$
{\frac{352}{126993}}+{{\frac{15488}{126993}} \  i} 
-{{\frac{484}{42331}} \  j} -{{\frac{1936}{126993}} \  k} 
$$
\returnType{Type: Quaternion Fraction Integer}

The usual arithmetic (ring) operations are available

\spadcommand{q**6 }
$$
-{\frac{2029490709319345}{7256313856}} -
{{\frac{48251690851}{1288408}} \  i}+
{{\frac{144755072553}{41229056}} \  j}+
{{\frac{48251690851}{10307264}} 
\  k} 
$$
\returnType{Type: Quaternion Fraction Integer}

\spadcommand{r := quatern(-2,3,23/9,-89); q + r }
$$
-{\frac{20}{11}} -{5 \  i}+{{\frac{119}{36}} \  j} -{{88} \  k} 
$$
\returnType{Type: Quaternion Fraction Integer}

In general, multiplication is not commutative.

\spadcommand{q * r - r * q}
$$
-{{\frac{2495}{18}} \  i} -{{1418} \  j} -{{\frac{817}{18}} \  k} 
$$
\returnType{Type: Quaternion Fraction Integer}

There are no predefined constants for the imaginary {\tt i, j},
and {\tt k} parts, but you can easily define them.

\spadcommand{i:=quatern(0,1,0,0); j:=quatern(0,0,1,0); k:=quatern(0,0,0,1) }
$$
k 
$$
\returnType{Type: Quaternion Integer}

These satisfy the normal identities.

\spadcommand{[i*i, j*j, k*k, i*j, j*k, k*i, q*i] }
$$
\left[
-1, -1, -1, k, i, j, {8+{{\frac{2}{11}} \  i}+j -{{\frac{3}{4}} \  k}} 
\right]
$$
\returnType{Type: List Quaternion Fraction Integer}

The norm is the quaternion times its conjugate.

\spadcommand{norm q }
$$
\frac{126993}{1936} 
$$
\returnType{Type: Fraction Integer}

\spadcommand{conjugate q  }
$$
{\frac{2}{11}}+{8 \  i} -{{\frac{3}{4}} \  j} -k 
$$
\returnType{Type: Quaternion Fraction Integer}

\spadcommand{q * \% }
$$
\frac{126993}{1936} 
$$
\returnType{Type: Quaternion Fraction Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Queue}

A queue is an aggregate structure which allows insertion at the back of
the queue, deletion at the front of the queue and inspection of the
front element. Queues are similar to a line of people where you can
join the line at the back, leave the line at the front, or see the
person in the front of the line.

Queues can be created from a list of elements using the {\bf queue}
function.

\spadcommand{a:Queue INT:= queue [1,2,3,4,5]}
$$
[1,2,3,4,5]
$$
\returnType{Type: Queue Integer}

An empty queue can be created using the {\bf empty} function. 

\spadcommand{a:Queue INT:= empty()}
$$
[]
$$
\returnType{Type: Queue Integer}

The {\bf empty?} function will return {\tt true} if the queue contains
no elements.

\spadcommand{empty? a}
$$
true
$$
\returnType{Type: Boolean}

Queues modify their arguments so they use the exclamation mark ``!''
as part of the function name.

The {\bf dequeue!} operation removes the front element of the queue and
returns it.  The queue is one element smaller. The {\bf extract!} does
the same thing with a different name.

\spadcommand{a:Queue INT:= queue [1,2,3,4,5]}
$$ 
[1,2,3,4,5]
$$
\returnType{Type: Queue Integer}

\spadcommand{dequeue! a}
$$
1
$$
\returnType{Type: PositiveInteger}

\spadcommand{a}
$$
[2,3,4,5]
$$
\returnType{Type: Queue Integer}

The {\bf enqueue!} function adds a new element to the back of the
queue and returns the element that was pushed. The queue is one
element larger.  The {\bf insert!} function does the same thing with a
different name.

\spadcommand{a:Queue INT:= queue [1,2,3,4,5]}
$$
[1,2,3,4,5]
$$
\returnType{Type: Queue Integer}

\spadcommand{enqueue!(9,a)}
$$
9
$$
\returnType{Type: PositiveInteger}

\spadcommand{a}
$$
[1,2,3,4,5,9]
$$
\returnType{Type: Queue Integer}

To read the top element without changing the queue use the {\bf front}
function.

\spadcommand{a:Queue INT:= queue [1,2,3,4,5]}
$$
[1,2,3,4,5]
$$
\returnType{Type: Queue Integer}

\spadcommand{front a}
$$
1
$$
\returnType{Type: PositiveInteger}

\spadcommand{a}
$$
[1,2,3,4,5]
$$
\returnType{Type: Queue Integer}

For more information on related topics, see Stack
\sectionref{Stack}.

%Original Page 444

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{RadixExpansion}

It possible to expand numbers in general bases.

Here we expand {\tt 111} in base {\tt 5}.
This means
$$10^2+10^1+10^0 = 4 \cdot 5^2+2 \cdot 5^1 + 5^0$$

\spadcommand{111::RadixExpansion(5)}
$$
421 
$$
\returnType{Type: RadixExpansion 5}

You can expand fractions to form repeating expansions.

\spadcommand{(5/24)::RadixExpansion(2)}
$$
0.{001}{\overline {10}} 
$$
\returnType{Type: RadixExpansion 2}

\spadcommand{(5/24)::RadixExpansion(3)}
$$
0.0{\overline {12}} 
$$
\returnType{Type: RadixExpansion 3}

\spadcommand{(5/24)::RadixExpansion(8)}
$$
0.1{\overline {52}} 
$$
\returnType{Type: RadixExpansion 8}

\spadcommand{(5/24)::RadixExpansion(10)}
$$
0.{208}{\overline 3} 
$$
\returnType{Type: RadixExpansion 10}

For bases from 11 to 36 the letters A through Z are used.

\spadcommand{(5/24)::RadixExpansion(12)}
$$
0.{26} 
$$
\returnType{Type: RadixExpansion 12}

\spadcommand{(5/24)::RadixExpansion(16)}
$$
0.3{\overline 5} 
$$
\returnType{Type: RadixExpansion 16}

\spadcommand{(5/24)::RadixExpansion(36)}
$$
0.{\rm 7I} 
$$
\returnType{Type: RadixExpansion 36}

%Original Page 445

For bases greater than 36, the ragits are separated by blanks.

\spadcommand{(5/24)::RadixExpansion(38)}
$$
0 \  . \  7 \  {34} \  {31} \  {\overline {{25} \  {12}}} 
$$
\returnType{Type: RadixExpansion 38}

The {\tt RadixExpansion} type provides operations to obtain the
individual ragits.  Here is a rational number in base {\tt 8}.

\spadcommand{a := (76543/210)::RadixExpansion(8) }
$$
{554}.3{\overline {7307}} 
$$
\returnType{Type: RadixExpansion 8}

The operation \spadfunFrom{wholeRagits}{RadixExpansion} returns a list of the
ragits for the integral part of the number.

\spadcommand{w := wholeRagits a }
$$
\left[
5, 5, 4 
\right]
$$
\returnType{Type: List Integer}

The operations \spadfunFrom{prefixRagits}{RadixExpansion} and
\spadfunFrom{cycleRagits}{RadixExpansion} return lists of the initial
and repeating ragits in the fractional part of the number.

\spadcommand{f0 := prefixRagits a }
$$
\left[
3 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{f1 := cycleRagits a }
$$
\left[
7, 3, 0, 7 
\right]
$$
\returnType{Type: List Integer}

You can construct any radix expansion by giving the whole, prefix and
cycle parts.  The declaration is necessary to let Axiom know the base
of the ragits.

\spadcommand{u:RadixExpansion(8):=wholeRadix(w)+fractRadix(f0,f1) }
$$
{554}.3{\overline {7307}} 
$$
\returnType{Type: RadixExpansion 8}

If there is no repeating part, then the list {\tt [0]} should be used.

\spadcommand{v: RadixExpansion(12) := fractRadix([1,2,3,11], [0]) }
$$
0.{\rm 123B}{\rm {\overline 0}}
$$
\returnType{Type: RadixExpansion 12}

If you are not interested in the repeating nature of the expansion,
an infinite stream of ragits can be obtained using
\spadfunFrom{fractRagits}{RadixExpansion}.

\spadcommand{fractRagits(u) }
$$
\left[
3, 7, {\overline {3, 0, 7, 7}} 
\right]
$$
\returnType{Type: Stream Integer}

Of course, it's possible to recover the fraction representation:

\spadcommand{a :: Fraction(Integer) }
$$
\frac{76543}{210} 
$$
\returnType{Type: Fraction Integer}

More examples of expansions are available in
\domainref{DecimalExpansion},\\ 
\domainref{BinaryExpansion}, and
\domainref{HexadecimalExpansion}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{RealClosure}

The Real Closure 1.0 package provided by Renaud Rioboo
(Renaud.Rioboo@lip6.fr) consists of different packages, categories and
domains :

\begin{list}{}
\item The package {\tt RealPolynomialUtilitiesPackage}\\ 
which needs a
{\tt Field} {\em F} and a {\tt Univariate\-PolynomialCategory} domain
with coefficients in {\em F}. It computes some simple functions such
as Sturm and Sylvester sequences\\
(\spadfunFrom{sturmSequence}{RealPolynomialUtilitiesPackage},\\
\spadfunFrom{sylvesterSequence}{RealPolynomialUtilitiesPackage}).

\item The category {\tt RealRootCharacterizationCategory} provides abstract
functions to work with ``real roots'' of univariate polynomials. These
resemble variables with some functionality needed to compute important
operations.

\item The category {\tt RealClosedField} provides common operations
available over real closed fiels. These include finding all the roots
of a univariate polynomial, taking square (and higher) roots, ...

\item The domain {\tt RightOpenIntervalRootCharacterization}\\ 
is the main code that provides the functionality of \\
{\tt RealRootCharacterizationCategory} for the case of archimedean
fields. Abstract roots are encoded with a left closed right open
interval containing the root together with a defining polynomial for
the root.

\item The {\tt RealClosure} domain is the end-user code. It provides
usual arithmetic with real algebraic numbers, along with the
functionality of a real closed field. It also provides functions to
approximate a real algebraic number by an element of the base
field. This approximation may either be absolute
(\spadfunFrom{approximate}{RealClosure}) or relative
(\spadfunFrom{relativeApprox}{RealClosure}).

\end{list}

\centerline{CAVEATS}

Since real algebraic expressions are stored as depending on ``real
roots'' which are managed like variables, there is an ordering on
these. This ordering is dynamical in the sense that any new algebraic
takes precedence over older ones. In particular every creation
function raises a new ``real root''. This has the effect that when you
type something like {\tt sqrt(2) + sqrt(2)} you have two new variables
which happen to be equal. To avoid this name the expression such as in
{\tt s2 := sqrt(2) ; s2 + s2}

Also note that computing times depend strongly on the ordering you
implicitly provide. Please provide algebraics in the order which seems
most natural to you.

\centerline{LIMITATIONS}

This packages uses algorithms which are published in [1] and [2] which
are based on field arithmetics, in particular for polynomial gcd
related algorithms. This can be quite slow for high degree polynomials
and subresultants methods usually work best. Beta versions of the
package try to use these techniques in a better way and work
significantly faster. These are mostly based on unpublished algorithms
and cannot be distributed. Please contact the author if you have a
particular problem to solve or want to use these versions.

Be aware that approximations behave as post-processing and that all
computations are done exactly. They can thus be quite time consuming when
depending on several ``real roots''.

\centerline{REFERENCES}


[1]  R. Rioboo : Real Algebraic Closure of an ordered Field : Implementation 
     in Axiom. 
     In proceedings of the ISSAC'92 Conference, Berkeley 1992 pp. 206-215.

[2]  Z. Ligatsikas, R. Rioboo, M. F. Roy : Generic computation of the real
     closure of an ordered field.
     In Mathematics and Computers in Simulation Volume 42, Issue 4-6,
     November 1996.

\centerline{EXAMPLES}

We shall work with the real closure of the ordered field of 
rational numbers.

\spadcommand{Ran := RECLOS(FRAC INT) }
$$
\mbox{\rm RealClosure Fraction Integer} 
$$
\returnType{Type: Domain}

Some simple signs for square roots, these correspond to an extension
of degree 16 of the rational numbers. Examples provided by J. Abbot.

\spadcommand{fourSquares(a:Ran,b:Ran,c:Ran,d:Ran):Ran == sqrt(a)+sqrt(b) - sqrt(c)-sqrt(d)  }
\begin{verbatim}
Function declaration fourSquares : (RealClosure Fraction Integer,
   RealClosure Fraction Integer,RealClosure Fraction Integer,
   RealClosure Fraction Integer) -> RealClosure Fraction Integer has
   been added to workspace.
\end{verbatim}
\returnType{Type: Void}

These produce values very close to zero.

\spadcommand{squareDiff1 := fourSquares(73,548,60,586) }
$$
-{\sqrt {{586}}} -{\sqrt {{60}}}+{\sqrt {{548}}}+{\sqrt {{73}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff1)}
$$
\begin{array}{@{}l}
\displaystyle
{{\left( 
{{\left( 
{{54602} \  {\sqrt {{548}}}}+
{{149602} \  {\sqrt {{73}}}} 
\right)}
\  {\sqrt {{60}}}}+
{{49502} \  {\sqrt {{73}}} \  {\sqrt {{548}}}}+
{9900895} 
\right)}
\  {\sqrt {{586}}}}+
\\
\\
\displaystyle
{{\left( {{154702} \  {\sqrt {{73}}} \  {\sqrt {{548}}}}+
{30941947} 
\right)}
\  {\sqrt {{60}}}}+{{10238421} \  {\sqrt {{548}}}}+
{{28051871} \  {\sqrt {{73}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff1)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{squareDiff2 := fourSquares(165,778,86,990) }
$$
-{\sqrt {{990}}} -{\sqrt {{86}}}+{\sqrt {{778}}}+{\sqrt {{165}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff2)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
{{556778} \  {\sqrt {{778}}}}+
{{1209010} \  {\sqrt {{165}}}} 
\right)\  {\sqrt {{86}}}+
\right.
\\
\\
\displaystyle
\left.
{{401966} \  {\sqrt {{165}}} \  {\sqrt {{778}}}}+
{144019431} 
\right)\  {\sqrt {{990}}}+
\\
\\
\displaystyle
{{\left( {{1363822} \  {\sqrt {{165}}} \  {\sqrt {{778}}}}+
{488640503} 
\right)}
\  {\sqrt {{86}}}}+
\\
\\
\displaystyle
{{162460913} \  {\sqrt {{778}}}}+
{{352774119} \  {\sqrt {{165}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff2)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{squareDiff3 := fourSquares(217,708,226,692) }
$$
-{\sqrt {{692}}} -{\sqrt {{226}}}+{\sqrt {{708}}}+{\sqrt {{217}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff3)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
-{{34102} \  {\sqrt {{708}}}} -
{{61598} \  {\sqrt {{217}}}} 
\right)\  {\sqrt {{226}}} -
\right.
\\
\\
\displaystyle
\left.
{{34802} \  {\sqrt {{217}}} \  {\sqrt {{708}}}} -
{13641141} 
\right)\  {\sqrt {{692}}}+
\\
\\
\displaystyle
\left( -
{{60898} \  {\sqrt {{217}}} \  {\sqrt {{708}}}} -
{23869841} 
\right)\  {\sqrt {{226}}} -
\\
\\
\displaystyle
{{13486123} \  {\sqrt {{708}}}} -
{{24359809} \  {\sqrt {{217}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff3)}
$$
-1 
$$
\returnType{Type: Integer}

\spadcommand{squareDiff4 := fourSquares(155,836,162,820)  }
$$
-{\sqrt {{820}}} -{\sqrt {{162}}}+{\sqrt {{836}}}+{\sqrt {{155}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff4)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
-{{37078} \  {\sqrt {{836}}}} -
{{86110} \  {\sqrt {{155}}}} 
\right)\  {\sqrt {{162}}} -
\right.
\\
\\
\displaystyle
\left.
{{37906} \  {\sqrt {{155}}} \  {\sqrt {{836}}}} -
{13645107} 
\right)\  {\sqrt {{820}}}+
\\
\\
\displaystyle
\left( -{{85282} \  {\sqrt {{155}}} \  {\sqrt {{836}}}} -
{30699151} 
\right)\  {\sqrt {{162}}} -
\\
\\
\displaystyle
{{13513901} \  {\sqrt {{836}}}} -
{{31384703} \  {\sqrt {{155}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff4)}
$$
-1 
$$
\returnType{Type: Integer}

\spadcommand{squareDiff5 := fourSquares(591,772,552,818) }
$$
-{\sqrt {{818}}} -{\sqrt {{552}}}+{\sqrt {{772}}}+{\sqrt {{591}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff5)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
{{70922} \  {\sqrt {{772}}}}+
{{81058} \  {\sqrt {{591}}}} 
\right)\  {\sqrt {{552}}}+
\right.
\\
\\
\displaystyle
\left.
{{68542} \  {\sqrt {{591}}} \  {\sqrt {{772}}}}+
{46297673} 
\right)\  {\sqrt {{818}}}+
\\
\\
\displaystyle
\left( 
{{83438} \  {\sqrt {{591}}} \  {\sqrt {{772}}}}+
{56359389} 
\right)\  {\sqrt {{552}}}+
\\
\\
\displaystyle
{{47657051} \  {\sqrt {{772}}}}+
{{54468081} \  {\sqrt {{591}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff5)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{squareDiff6 := fourSquares(434,1053,412,1088) }
$$
-{\sqrt {{1088}}} -
{\sqrt {{412}}}+
{\sqrt {{1053}}}+
{\sqrt {{434}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff6)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
{{115442} \  {\sqrt {{1053}}}}+
{{179818} \  {\sqrt {{434}}}} 
\right)\  {\sqrt {{412}}}+
\right.
\\
\\
\displaystyle
\left.
{{112478} \  {\sqrt {{434}}} \  {\sqrt {{1053}}}}+
{76037291} 
\right)\  {\sqrt {{1088}}}+
\\
\\
\displaystyle
\left( 
{{182782} \  {\sqrt {{434}}} \  {\sqrt {{1053}}}}+
{123564147} 
\right)\  {\sqrt {{412}}}+
\\
\\
\displaystyle
{{77290639} \  {\sqrt {{1053}}}}+
{{120391609} \  {\sqrt {{434}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff6)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{squareDiff7 := fourSquares(514,1049,446,1152) }
$$
-{\sqrt {{1152}}} -{\sqrt {{446}}}+{\sqrt {{1049}}}+{\sqrt {{514}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff7)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
{{349522} \  {\sqrt {{1049}}}}+
{{499322} \  {\sqrt {{514}}}} 
\right)\  {\sqrt {{446}}}+
\right.
\\
\\
\displaystyle
\left.
{{325582} \  {\sqrt {{514}}} \  {\sqrt {{1049}}}}+
{239072537} 
\right)\  {\sqrt {{1152}}}+
\\
\\
\displaystyle
\left( 
{{523262} \  {\sqrt {{514}}} \  {\sqrt {{1049}}}}+
{384227549} 
\right)\  {\sqrt {{446}}}+
\\
\\
\displaystyle
{{250534873} \  {\sqrt {{1049}}}}+
{{357910443} \  {\sqrt {{514}}}} 
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff7)}
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{squareDiff8 := fourSquares(190,1751,208,1698) }
$$
-{\sqrt {{1698}}} -
{\sqrt {{208}}}+
{\sqrt {{1751}}}+
{\sqrt {{190}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{recip(squareDiff8)}
$$
\begin{array}{@{}l}
\displaystyle
\left( 
\left( 
-{{214702} \  {\sqrt {{1751}}}} -
{{651782} \  {\sqrt {{190}}}} 
\right)\  {\sqrt {{208}}} -
\right.
\\
\\
\displaystyle
\left.
{{224642} \  {\sqrt {{190}}} \  {\sqrt {{1751}}}} 
-{129571901} 
\right)\  {\sqrt {{1698}}}+
\\
\\
\displaystyle
\left( 
-{{641842} \  {\sqrt {{190}}} \  {\sqrt {{1751}}}} -
{370209881} 
\right)\  {\sqrt {{208}}} -
\\
\\
\displaystyle
{{127595865} \  {\sqrt {{1751}}}} -
{{387349387} \  {\sqrt {{190}}}}
\end{array}
$$
\returnType{Type: Union(RealClosure Fraction Integer,...)}

\spadcommand{sign(squareDiff8)}
$$
-1 
$$
\returnType{Type: Integer}

This should give three digits of precision

\spadcommand{relativeApprox(squareDiff8,10**(-3))::Float }
$$
-{0.2340527771\ 5937700123 E -10} 
$$
\returnType{Type: Float}

The sum of these 4 roots is 0

\spadcommand{l := allRootsOf((x**2-2)**2-2)\$Ran  }
$$
\left[
{ \%A{33}}, { \%A{34}}, { \%A{35}}, { \%A{36}} 
\right]
$$
\returnType{Type: List RealClosure Fraction Integer}

Check that they are all roots of the same polynomial

\spadcommand{removeDuplicates map(mainDefiningPolynomial,l) }
$$
\left[
{{? \sp 4} -{4 \  {? \sp 2}}+2} 
\right]
$$
\returnType{Type: 
List Union(SparseUnivariatePolynomial RealClosure Fraction Integer,"failed")}

We can see at a glance that they are separate roots

\spadcommand{map(mainCharacterization,l) }
$$
\left[
{{[-2}, {-1[}}, {{[-1}, {0[}}, {{[0}, {1[}}, {{[1}, 
{2[}} 
\right]
$$
\returnType{Type: 
List Union(
RightOpenIntervalRootCharacterization(
RealClosure Fraction Integer,
SparseUnivariatePolynomial RealClosure Fraction Integer),
"failed")}

Check the sum and product

\spadcommand{[reduce(+,l),reduce(*,l)-2] }
$$
\left[
0, 0 
\right]
$$
\returnType{Type: List RealClosure Fraction Integer}

A more complicated test that involve an extension of degree 256.
This is a way of checking nested radical identities.

\spadcommand{(s2, s5, s10) := (sqrt(2)\$Ran, sqrt(5)\$Ran, sqrt(10)\$Ran) }
$$
\sqrt {{10}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{eq1:=sqrt(s10+3)*sqrt(s5+2) - sqrt(s10-3)*sqrt(s5-2) = sqrt(10*s2+10) }
$$
{-{{\sqrt {{{\sqrt {{10}}} -3}}} 
\  {\sqrt {{{\sqrt {5}} -2}}}}+
{{\sqrt {{{\sqrt {{10}}}+3}}} 
\  {\sqrt {{{\sqrt {5}}+2}}}}}=
{\sqrt {{{{10} \  {\sqrt {2}}}+{10}}}} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{eq1::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{eq2:=sqrt(s5+2)*sqrt(s2+1) - sqrt(s5-2)*sqrt(s2-1) = sqrt(2*s10+2)}
$$
{-{{\sqrt {{{\sqrt {5}} -2}}} 
\  {\sqrt {{{\sqrt {2}} -1}}}}+
{{\sqrt {{{\sqrt {5}}+2}}} 
\  {\sqrt {{{\sqrt {2}}+1}}}}}=
{\sqrt {{{2 \  {\sqrt {{10}}}}+2}}} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{eq2::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

Some more examples from J. M. Arnaudies

\spadcommand{s3 := sqrt(3)\$Ran }
$$
\sqrt {3} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{s7:= sqrt(7)\$Ran }
$$
\sqrt {7} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{e1 := sqrt(2*s7-3*s3,3)   }
$$
\root {3} \of {{{2 \  {\sqrt {7}}} -{3 \  {\sqrt {3}}}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{e2 := sqrt(2*s7+3*s3,3)   }
$$
\root {3} \of {{{2 \  {\sqrt {7}}}+{3 \  {\sqrt {3}}}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

This should be null

\spadcommand{e2-e1-s3   }
$$
0 
$$
\returnType{Type: RealClosure Fraction Integer}

A quartic polynomial

\spadcommand{pol : UP(x,Ran) := x**4+(7/3)*x**2+30*x-(100/3)  }
$$
{x \sp 4}+{{\frac{7}{3}} \  {x \sp 2}}+{{30} \  x} -{\frac{100}{3}} 
$$
\returnType{Type: UnivariatePolynomial(x,RealClosure Fraction Integer)}

Add some cubic roots

\spadcommand{r1 := sqrt(7633)\$Ran }
$$
\sqrt {{7633}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{alpha := sqrt(5*r1-436,3)/3  }
$$
{\frac{1}{3}} \  {\root {3} \of {{{5 \  {\sqrt {{7633}}}} -{436}}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{beta := -sqrt(5*r1+436,3)/3  }
$$
-{{\frac{1}{3}} \  {\root {3} \of {{{5 \  {\sqrt {{7633}}}}+{436}}}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

this should be null

\spadcommand{pol.(alpha+beta-1/3)   }
$$
0 
$$
\returnType{Type: RealClosure Fraction Integer}

A quintic polynomial

\spadcommand{qol : UP(x,Ran) := x**5+10*x**3+20*x+22 }
$$
{x \sp 5}+{{10} \  {x \sp 3}}+{{20} \  x}+{22} 
$$
\returnType{Type: UnivariatePolynomial(x,RealClosure Fraction Integer)}

Add some cubic roots

\spadcommand{r2 := sqrt(153)\$Ran }
$$
\sqrt {{153}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{alpha2 := sqrt(r2-11,5) }
$$
\root {5} \of {{{\sqrt {{153}}} -{11}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{beta2 := -sqrt(r2+11,5) }
$$
-{\root {5} \of {{{\sqrt {{153}}}+{11}}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

this should be null

\spadcommand{qol(alpha2+beta2) }
$$
0 
$$
\returnType{Type: RealClosure Fraction Integer}

Finally, some examples from the book Computer Algebra by 
Davenport, Siret and Tournier (page 77).
The last one is due to Ramanujan.

\spadcommand{dst1:=sqrt(9+4*s2)=1+2*s2 }
$$
{\sqrt {{{4 \  {\sqrt {2}}}+9}}}={{2 \  {\sqrt {2}}}+1} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{dst1::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{s6:Ran:=sqrt 6 }
$$
\sqrt {6} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{dst2:=sqrt(5+2*s6)+sqrt(5-2*s6) = 2*s3 }
$$
{{\sqrt {{-{2 \  {\sqrt {6}}}+5}}}+{\sqrt {{{2 \  {\sqrt {6}}}+5}}}}={2 \  
{\sqrt {3}}} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{dst2::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{s29:Ran:=sqrt 29 }
$$
\sqrt {{29}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{dst4:=sqrt(16-2*s29+2*sqrt(55-10*s29)) = sqrt(22+2*s5)-sqrt(11+2*s29)+s5 }
$$
{\sqrt {{{2 \  {\sqrt {{-{{10} \  {\sqrt {{29}}}}+{55}}}}} -
{2 \  {\sqrt {{29}}}}+
{16}}}}=
{-{\sqrt {{{2 \  {\sqrt {{29}}}}+{11}}}}+
{\sqrt {{{2 \  {\sqrt {5}}}+
{22}}}}+{\sqrt {5}}} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{dst4::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{dst6:=sqrt((112+70*s2)+(46+34*s2)*s5) = (5+4*s2)+(3+s2)*s5 }
$$
{\sqrt {{{{\left( {{34} \  {\sqrt {2}}}+{46} 
\right)}
\  {\sqrt {5}}}+{{70} \  {\sqrt {2}}}+{112}}}}={{{\left( {\sqrt {2}}+3 
\right)}
\  {\sqrt {5}}}+{4 \  {\sqrt {2}}}+5} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{dst6::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{f3:Ran:=sqrt(3,5) }
$$
\root {5} \of {3} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{f25:Ran:=sqrt(1/25,5) }
$$
\root {5} \of {{\frac{1}{25}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{f32:Ran:=sqrt(32/5,5) }
$$
\root {5} \of {{\frac{32}{5}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{f27:Ran:=sqrt(27/5,5) }
$$
\root {5} \of {{\frac{27}{5}}} 
$$
\returnType{Type: RealClosure Fraction Integer}

\spadcommand{dst5:=sqrt((f32-f27,3)) = f25*(1+f3-f3**2)}
$$
{\root {3} \of {{-{\root {5} \of {{\frac{27}{5}}}}+{\root {5} \of 
{{\frac{32}{5}}}}}}}=
{{\left( -{{\root {5} \of {3}} \sp 2}+{\root {5} \of {3}}+1 \right)}
\  {\root {5} \of {{\frac{1}{25}}}}} 
$$
\returnType{Type: Equation RealClosure Fraction Integer}

\spadcommand{dst5::Boolean }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{RealSolvePackage}
\begin{verbatim}
p := 4*x^3 - 3*x^2 + 2*x - 4
\end{verbatim}
$$
{4 \ {x^3}} -{3 \ {x^2}}+{2 \ x} -4
$$
\returnType{Type: Polynomial(Integer)}
\begin{verbatim}
ans1 := solve(p,0.01)$REALSOLV
\end{verbatim}
$$
\left[
{1.11328125}
\right]
$$
\returnType{Type: List(Float)}
\begin{verbatim}
ans2 := solve(p::POLY(FRAC(INT)),0.01)$REALSOLV
\end{verbatim}
$$
\left[
{1.11328125}
\right]
$$
\returnType{Type: List(Float)}
\begin{verbatim}
R := Integer
\end{verbatim}
$$
Integer
$$
\returnType{Type: Domain}
\begin{verbatim}
ls : List Symbol := [x,y,z,t]
\end{verbatim}
$$
\left[
x, \: y, \: z, \: t
\right]
$$
\returnType{Type: List(Symbol)}
\begin{verbatim}
ls2 : List Symbol := [x,y,z,t,new()$Symbol]
\end{verbatim}
$$
\left[
x, \: y, \: z, \: t, \: \%A
\right]
$$
\returnType{Type: List(Symbol)}
\begin{verbatim}
pack := ZDSOLVE(R,ls,ls2)
\end{verbatim}
$$
ZeroDimensionalSolvePackage(Integer,[x,y,z,t],[x,y,z,t,\%A])
$$
\returnType{Type: Domain}
\begin{verbatim}
p1 := x**2*y*z + y*z
\end{verbatim}
$$
{\left( {x^2}+1
\right)}
\ y \ z
$$
\returnType{Type: Polynomial(Integer)}
\begin{verbatim}
p2 := x**2*y**2*z + x + z
\end{verbatim}
$$
{{\left({{x^2} \ {y^2}}+1
\right)}
\ z}+x
$$
\returnType{Type: Polynomial(Integer)}
\begin{verbatim}
p3 := x**2*y**2*z**2 +  z + 1
\end{verbatim}
$$
{{x^2} \ {y^2} \ {z^2}}+z+1
$$
\returnType{Type: Polynomial(Integer)}
\begin{verbatim}
lp := [p1, p2, p3]
\end{verbatim}
$$
\left[
{{\left( {x^2}+1
\right)}
\ y \ z}, \: {{{\left( {{x^2} \ {y^2}}+1
\right)}
\ z}+x}, \: {{{x^2} \ {y^2} \ {z^2}}+z+1}
\right]
$$
\returnType{Type: List(Polynomial(Integer))}
\begin{verbatim}
lsv:List(Symbol):=[x,y,z]
\end{verbatim}
$$
\left[
x, \: y, \: z
\right]
$$
\returnType{Type: List(Symbol)}
\begin{verbatim}
ans3 := realSolve(lp,lsv,0.01)$REALSOLV
\end{verbatim}
$$
\left[
{\left[ {1.0}, \: {0.0}, \: -{1.0}
\right]}
\right]
$$
\returnType{Type: List(List(Float))}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{RegularTriangularSet}

The {\tt RegularTriangularSet} domain constructor implements regular
triangular sets.  These particular triangular sets were introduced by
M. Kalkbrener (1991) in his PhD Thesis under the name regular chains.
Regular chains and their related concepts are presented in the paper
``On the Theories of Triangular sets'' By P. Aubry, D. Lazard and
M. Moreno Maza (to appear in the Journal of Symbolic Computation).
The {\tt RegularTriangularSet} constructor also provides a new method
(by the third author) for solving polynomial system by means of
regular chains.  This method has two ways of solving.  One has the
same specifications as Kalkbrener's algorithm (1991) and the other is
closer to Lazard's method (Discr. App. Math, 1991).  Moreover, this
new method removes redundant component from the decompositions when
this is not {\em too expensive}.  This is always the case with
square-free regular chains.  So if you want to obtain decompositions
without redundant components just use the {\tt
SquareFreeRegularTriangularSet} domain constructor or the {\tt
LazardSetSolvingPackage} package constructor.  See also the {\tt
LexTriangularPackage} and {\tt ZeroDimensionalSolvePackage} for the
case of algebraic systems with a finite number of (complex) solutions.

One of the main features of regular triangular sets is that they
naturally define towers of simple extensions of a field.
This allows to perform with multivariate polynomials the 
same kind of operations as one can do in an {\tt EuclideanDomain}.

The {\tt RegularTriangularSet} constructor takes four arguments.  The
first one, {\bf R}, is the coefficient ring of the polynomials; it
must belong to the category {\tt GcdDomain}.  The second one, {\bf E},
is the exponent monoid of the polynomials; it must belong to the
category {\tt OrderedAbelianMonoidSup}.  the third one, {\bf V}, is
the ordered set of variables; it must belong to the category 
{\tt OrderedSet}.  The last one is the polynomial ring; it must belong to
the category \\
{\tt RecursivePolynomialCategory(R,E,V)}.  The
abbreviation for {\tt RegularTriangularSet} is {\tt REGSET}.  See also
the constructor {\tt RegularChain} which only takes two arguments, the
coefficient ring and the ordered set of variables; in that case,
polynomials are necessarily built with the 
{\tt NewSparseMultivariatePolynomial} domain constructor.

We shall explain now how to use the constructor {\tt REGSET} and how
to read the decomposition of a polynomial system by means of regular
sets.

Let us give some examples.  We start with an easy one
(Donati-Traverso) in order to understand the two ways of solving
polynomial systems provided by the {\tt REGSET} constructor.

Define the coefficient ring.

\spadcommand{R := Integer }
$$
Integer 
$$
\returnType{Type: Domain}

Define the list of variables,

\spadcommand{ls : List Symbol := [x,y,z,t] }
$$
\left[
x, y, z, t 
\right]
$$
\returnType{Type: List Symbol}

and make it an ordered set;

\spadcommand{V := OVAR(ls)  }
$$
\mbox{\rm OrderedVariableList [x,y,z,t]} 
$$
\returnType{Type: Domain}

then define the exponent monoid.

\spadcommand{E := IndexedExponents V  }
$$
\mbox{\rm IndexedExponents OrderedVariableList [x,y,z,t]} 
$$
\returnType{Type: Domain}

Define the polynomial ring.

\spadcommand{P := NSMP(R, V)   }
$$
\mbox{\rm NewSparseMultivariatePolynomial(Integer,OrderedVariableList 
[x,y,z,t])} 
$$
\returnType{Type: Domain}

Let the variables be polynomial.

\spadcommand{x: P := 'x  }
$$
x 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t])}

\spadcommand{y: P := 'y  }
$$
y 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t])}

\spadcommand{z: P := 'z  }
$$
z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t])}

\spadcommand{t: P := 't  }
$$
t 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t])}

Now call the {\tt RegularTriangularSet} domain constructor.

\spadcommand{T := REGSET(R,E,V,P)}
$$
\begin{array}{@{}l}
{\rm RegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t]))} 
\end{array}
$$
\returnType{Type: Domain}

Define a polynomial system.

\spadcommand{p1 := x ** 31 - x ** 6 - x - y   }
$$
{x \sp {31}} -{x \sp 6} -x -y 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{p2 := x ** 8  - z   }
$$
{x \sp 8} -z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{p3 := x ** 10 - t   }
$$
{x \sp {10}} -t 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t])}

\spadcommand{lp := [p1, p2, p3]    }
$$
\left[
{{x \sp {31}} -{x \sp 6} -x -y}, {{x \sp 8} -z}, {{x \sp {10}} -t} 
\right]
$$
\returnType{Type: 
List NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t])}

First of all, let us solve this system in the sense of Kalkbrener.

\spadcommand{zeroSetSplit(lp)\$T  }
$$
\left[
{\left\{ 
{{z \sp 5} -
{t \sp 4}}, 
{{t \  z \  {y \sp 2}}+
{2 \  {z \sp 3} \  y} -
{t \sp 8}+
{2 \  {t \sp 5}}+
{t \sp 3} -
{t \sp 2}}, 
{{{\left( {t \sp 4} 
-t 
\right)}\  x} -
{t \  y} -
{z \sp 2}} 
\right\}}
\right]
$$
\returnType{Type: 
List RegularTriangularSet(
Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t]))}

And now in the sense of Lazard (or Wu and other authors).

\spadcommand{lts := zeroSetSplit(lp,false)\$T   }
$$
\begin{array}{@{}l}
\left[
{\left\{ 
{{z \sp 5} -
{t \sp 4}}, 
{{t \  z \  {y \sp 2}}+
{2 \  {z \sp 3} \  y} -
{t \sp 8}+
{2 \  {t \sp 5}}+
{t \sp 3} -
{t \sp 2}}, 
{{{\left( 
{t \sp 4} -t 
\right)}\  x} -
{t \  y} -
{z \sp 2}} 
\right\}},
\right.
\\
\\
\displaystyle
\left.
{\left\{ 
{{t \sp 3} -1}, 
{{z \sp 5} -t}, 
{{t \  z \  {y \sp 2}}+
{2 \  {z \sp 3} \  y}+1}, 
{{z \  {x \sp 2}} -t} 
\right\}},
{\left\{ 
t, z, y, x 
\right\}}
\right]
\end{array}
$$
\returnType{Type: 
List RegularTriangularSet(
Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(
Integer,
OrderedVariableList [x,y,z,t]))}

We can see that the first decomposition is a subset of the second.
So how can both be correct ?

Recall first that polynomials from a domain of the category 
{\tt RecursivePolynomialCategory} are regarded as univariate polynomials in
their main variable.  For instance the second polynomial in the first
set of each decomposition has main variable {\bf y} and its initial
(i.e. its leading coefficient w.r.t. its main variable) is {\bf t z}.

Now let us explain how to read the second decomposition.  Note that
the non-constant initials of the first set are $t^4-t$ and $t z$.
Then the solutions described by this first set are the common zeros of
its polynomials that do not cancel the polynomials $t^4-t$ and $ty z$.
Now the solutions of the input system {\bf lp} satisfying these
equations are described by the second and the third sets of the
decomposition.  Thus, in some sense, they can be considered as
degenerated solutions.  The solutions given by the first set are
called the generic points of the system; they give the general form of
the solutions.  The first decomposition only provides these generic
points.  This latter decomposition is useful when they are many
degenerated solutions (which is sometimes hard to compute) and when
one is only interested in general informations, like the dimension of
the input system.

We can get the dimensions of each component
of a decomposition as follows.

\spadcommand{[coHeight(ts) for ts in lts] }
$$
\left[
1, 0, 0 
\right]
$$
\returnType{Type: List NonNegativeInteger}

Thus the first set has dimension one.  Indeed {\bf t} can take any
value, except {\bf 0} or any third root of {\bf 1}, whereas {\bf z} is
completely determined from {\bf t}, {\bf y} is given by {\bf z} and
{\bf t}, and finally {\bf x} is given by the other three variables.
In the second and the third sets of the second decomposition the four
variables are completely determined and thus these sets have dimension
zero.

We give now the precise specifications of each decomposition.  This
assume some mathematical knowledge.  However, for the non-expert user,
the above explanations will be sufficient to understand the other
features of the {\tt RSEGSET} constructor.

The input system {\bf lp} is decomposed in the sense of Kalkbrener as
finitely many regular sets {\bf T1,...,Ts} such that the radical ideal
generated by {\bf lp} is the intersection of the radicals of the
saturated ideals of {\bf T1,...,Ts}.  In other words, the affine
variety associated with {\bf lp} is the union of the closures
(w.r.t. Zarisky topology) of the regular-zeros sets of 
{\bf T1,...,Ts}.

{\bf N. B.} The prime ideals associated with the radical of the
saturated ideal of a regular triangular set have all the same
dimension; moreover these prime ideals can be given by characteristic
sets with the same main variables.  Thus a decomposition in the sense
of Kalkbrener is unmixed dimensional.  Then it can be viewed as a {\em
lazy} decomposition into prime ideals (some of these prime ideals
being merged into unmixed dimensional ideals).

Now we explain the other way of solving by means of regular triangular
sets.  The input system {\bf lp} is decomposed in the sense of Lazard
as finitely many regular triangular sets {\bf T1,...,Ts} such that the
affine variety associated with {\bf lp} is the union of the
regular-zeros sets of {\bf T1,...,Ts}.  Thus a decomposition in the
sense of Lazard is also a decomposition in the sense of Kalkbrener;
the converse is false as we have seen before.

When the input system has a finite number of solutions, both ways of
solving provide similar decompositions as we shall see with this
second example (Caprasse).

Define a polynomial system.

\spadcommand{f1 := y**2*z+2*x*y*t-2*x-z     }
$$
{{\left( {2 \  t \  y} -2 
\right)}
\  x}+{z \  {y \sp 2}} -z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{f2 :=   -x**3*z+ 4*x*y**2*z+ 4*x**2*y*t+ 2*y**3*t+ 4*x**2- 10*y**2+ 4*x*z- 10*y*t+ 2 }
$$
-{z \  {x \sp 3}}+
{{\left( 
{4 \  t \  y}+4 
\right)}\  {x \sp 2}}+
{{\left( 
{4 \  z \  {y \sp 2}}+
{4 \  z} 
\right)}\  x}+
{2 \  t \  {y \sp 3}} -
{{10} \  {y \sp 2}} -
{{10} \  t \  y}+2 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{f3 :=  2*y*z*t+x*t**2-x-2*z }
$$
{{\left( 
{t \sp 2} -1 
\right)}\  x}+
{2 \  t \  z \  y} -
{2 \  z} 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{f4 :=   -x*z**3+ 4*y*z**2*t+ 4*x*z*t**2+ 2*y*t**3+ 4*x*z+ 4*z**2-10*y*t- 10*t**2+2}
$$
{{\left( -{z \sp 3}+{{\left( {4 \  {t \sp 2}}+4 
\right)}
\  z} 
\right)}
\  x}+{{\left( {4 \  t \  {z \sp 2}}+{2 \  {t \sp 3}} -{{10} \  t} 
\right)}
\  y}+{4 \  {z \sp 2}} -{{10} \  {t \sp 2}}+2 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{lf := [f1, f2, f3, f4]}
$$
\begin{array}{@{}l}
\left[
{{{\left( 
{2 \  t \  y} -2 
\right)}\  x}+
{z \  {y \sp 2}} -z}, 
\right.
\\
\\
\displaystyle
{-{z \  {x \sp 3}}+
{{\left( 
{4 \  t \  y}+4 
\right)}\  {x \sp 2}}+
{{\left( 
{4 \  z \  {y \sp 2}}+
{4 \  z} 
\right)}\  x}+
{2 \  t \  {y \sp 3}} -
{{10} \  {y \sp 2}} -
{{10} \  t \  y}+2}, 
\\
\\
\displaystyle
{{{\left( 
{t \sp 2} -1 
\right)}\  x}+
{2 \  t \  z \  y} -
{2 \  z}}, 
\\
\\
\displaystyle
\left.
{{{\left( 
-{z \sp 3}+
{{\left( 
{4 \  {t \sp 2}}+4 
\right)}\  z} 
\right)}\  x}+
{{\left( 
{4 \  t \  {z \sp 2}}+
{2 \  {t \sp 3}} -
{{10} \  t} 
\right)}\  y}+
{4 \  {z \sp 2}} -
{{10} \  {t \sp 2}}+2} 
\right]
\end{array}
$$
\returnType{Type: List 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

First of all, let us solve this system in the sense of Kalkbrener.

\spadcommand{zeroSetSplit(lf)\$T  }
$$
\begin{array}{@{}l}
\left[
{\left\{ 
{{t \sp 2} -1}, 
{{z \sp 8} -{{16} \  {z \sp 6}}+{{256} \  {z \sp 2}} -{256}}, 
{{t \  y} -1}, 
{{{\left( {z \sp 3} -{8 \  z} \right)}\  x} -{8 \  {z \sp 2}}+{16}} 
\right\}},
\right.
\\
\\
\displaystyle
{\left\{ {{3 \  {t \sp 2}}+1}, 
{{z \sp 2} -{7 \  {t \sp 2}} -1},
{y+t}, 
{x+z} 
\right\}},
\\
\\
\displaystyle
{\left\{ {{t \sp 8} -{{10} \  {t \sp 6}}+{{10} \  {t \sp 2}} -1},
z,
{{{\left( {t \sp 3} -{5 \  t} \right)}\  y} -{5 \  {t \sp 2}}+1}, 
x 
\right\}},
\\
\\
\displaystyle
\left.
{\left\{ {{t \sp 2}+3}, 
{{z \sp 2} -4}, 
{y+t}, 
{x -z} 
\right\}}
\right]
\end{array}
$$
\returnType{Type: 
List RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

And now in the sense of Lazard (or Wu and other authors).

\spadcommand{lts2 := zeroSetSplit(lf,false)\$T   }
$$
\begin{array}{@{}l}
\left[
{\left\{ 
{{t \sp 8} -{{10} \  {t \sp 6}}+{{10} \  {t \sp 2}} -1}, 
z,  
{{{\left( {t \sp 3} -{5 \  t} \right)}\  y} -{5 \  {t \sp 2}}+1}, 
x 
\right\}},
\right.
\\
\\
\displaystyle
{\left\{ 
{{t \sp 2} -1}, 
{{z \sp 8} -{{16} \  {z \sp 6}}+{{256} \  {z \sp 2}} -{256}}, 
{{t \  y} -1}, 
{{{\left( {z \sp 3} -{8 \  z} \right)}\  x} -{8 \  {z \sp 2}}+{16}} 
\right\}},
\\
\\
\displaystyle
{\left\{ 
{{3 \  {t \sp 2}}+1}, 
{{z \sp 2} -{7 \  {t \sp 2}} -1},  
{y+t}, 
{x+z} 
\right\}},
\\
\\
\displaystyle
\left.
{\left\{ {{t \sp 2}+3}, 
{{z \sp 2} -4}, 
{y+t}, 
{x -z} 
\right\}}
\right]
\end{array}
$$
\returnType{Type: 
List RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

Up to the ordering of the components, both decompositions are identical.

Let us check that each component has a finite number of solutions.

\spadcommand{[coHeight(ts) for ts in lts2] }
$$
\left[
0, 0, 0, 0 
\right]
$$
\returnType{Type: List NonNegativeInteger}

Let us count the degrees of each component,

\spadcommand{degrees := [degree(ts) for ts in lts2]  }
$$
\left[
8, {16}, 4, 4 
\right]
$$
\returnType{Type: List NonNegativeInteger}

and compute their sum.

\spadcommand{reduce(+,degrees) }
$$
32 
$$
\returnType{Type: PositiveInteger}

We study now the options of the {\tt zeroSetSplit} operation.  As we
have seen yet, there is an optional second argument which is a boolean
value. If this value is {\tt true} (this is the default) then the
decomposition is computed in the sense of Kalkbrener, otherwise it is
computed in the sense of Lazard.

There is a second boolean optional argument that can be used (in that
case the first optional argument must be present).  This second option
allows you to get some information during the computations.

Therefore, we need to understand a little what is going on during the
computations.  An important feature of the algorithm is that the
intermediate computations are managed in some sense like the processes
of a Unix system.  Indeed, each intermediate computation may generate
other intermediate computations and the management of all these
computations is a crucial task for the efficiency.  Thus any
intermediate computation may be suspended, killed or resumed,
depending on algebraic considerations that determine priorities for
these processes.  The goal is of course to go as fast as possible
towards the final decomposition which means to avoid as much as
possible unnecessary computations.

To follow the computations, one needs to set to {\tt true} the second
argument.  Then a lot of numbers and letters are displayed.  Between a
{\tt [} and a {\tt ]} one has the state of the processes at a given
time.  Just after {\tt [} one can see the number of processes.  Then
each process is represented by two numbers between {\tt <} and 
{\tt >}.  A process consists of a list of polynomial {\bf ps} and a
triangular set {\bf ts}; its goal is to compute the common zeros of
{\bf ps} that belong to the regular-zeros set of {\bf ts}.  After the
processes, the number between pipes gives the total number of
polynomials in all the sets {\tt ps}.  Finally, the number between
braces gives the number of components of a decomposition that are
already computed. This number may decrease.

Let us take a third example (Czapor-Geddes-Wang) to see how this
information is displayed.

Define a polynomial system.

\spadcommand{u : R := 2   }
$$
2 
$$
\returnType{Type: Integer}

\spadcommand{q1 := 2*(u-1)**2+ 2*(x-z*x+z**2)+ y**2*(x-1)**2- 2*u*x+ 2*y*t*(1-x)*(x-z)+ 2*u*z*t*(t-y)+ u**2*t**2*(1-2*z)+ 2*u*t**2*(z-x)+ 2*u*t*y*(z-1)+ 2*u*z*x*(y+1)+ (u**2-2*u)*z**2*t**2+ 2*u**2*z**2+ 4*u*(1-u)*z+ t**2*(z-x)**2}
$$
\begin{array}{@{}l}
{{\left( 
{y \sp 2} -{2 \  t \  y}+{t \sp 2} 
\right)}\  {x \sp 2}}+
\\
\\
\displaystyle
{{\left( 
-{2 \  {y \sp 2}}+
{{\left( {{\left( {2 \  t}+4 
\right)}\  z}+
{2 \  t} 
\right)}\  y}+
{{\left( 
-{2 \  {t \sp 2}}+2 
\right)}\  z} -
{4 \  {t \sp 2}} -2 
\right)}\  x}+
\\
\\
\displaystyle
{y \sp 2}+
{{\left( 
-{2 \  t \  z} -
{4 \  t} 
\right)}\  y}+
{{\left( 
{t \sp 2}+
{10} 
\right)}\  {z \sp 2}} -
{8 \  z}+
{4 \  {t \sp 2}}+
2 
\end{array}
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{q2 := t*(2*z+1)*(x-z)+ y*(z+2)*(1-x)+ u*(u-2)*t+ u*(1-2*u)*z*t+ u*y*(x+u-z*x-1)+ u*(u+1)*z**2*t}
$$
{{\left( 
-{3 \  z \  y}+
{2 \  t \  z}+
t 
\right)}\  x}+
{{\left( 
z+4 
\right)}\  y}+
{4 \  t \  {z \sp 2}} -
{7 \  t \  z} 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{q3 := -u**2*(z-1)**2+ 2*z*(z-x)-2*(x-1)}
$$
{{\left( 
-{2 \  z} -2 
\right)}\  x} -
{2 \  {z \sp 2}}+
{8 \  z} -
2 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{q4 :=   u**2+4*(z-x**2)+3*y**2*(x-1)**2- 3*t**2*(z-x)**2 +3*u**2*t**2*(z-1)**2+u**2*z*(z-2)+6*u*t*y*(z+x+z*x-1)}
$$
\begin{array}{@{}l}
{{\left( 
{3 \  {y \sp 2}} -
{3 \  {t \sp 2}} -
4 
\right)}\  {x \sp 2}}+
{{\left( 
-{6 \  {y \sp 2}}+
{{\left( {{12} \  t \  z}+
{{12} \  t} 
\right)}\  y}+
{6 \  {t \sp 2} \  z} 
\right)}\  x}+
{3 \  {y \sp 2}}+
\\
\\
\displaystyle
{{\left( 
{{12} \  t \  z} -
{{12} \  t} 
\right)}\  y}+
{{\left( 
{9 \  {t \sp 2}}+
4 
\right)}\  {z \sp 2}}+
{{\left( 
-{{24} \  {t \sp 2}} -
4 
\right)}\  z}+
{{12} \  {t \sp 2}}+
4 
\end{array}
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{lq := [q1, q2, q3, q4]}
$$
\begin{array}{@{}l}
\left[
\left( 
{y \sp 2} -{2 \  t \  y}+{t \sp 2} \right)\  {x \sp 2}+
\right.
\\
\\
\displaystyle
\left( -{2 \  {y \sp 2}}+
\left( 
\left( {2 \  t}+4 
\right)\  z+{2 \  t} 
\right)\  y+
\left( -{2 \  {t \sp 2}}+2 
\right)\  z -{4 \  {t \sp 2}} -2 
\right)\  x+{y \sp 2}+
\\
\\
\displaystyle
\left( -{2 \  t \  z} -{4 \  t} 
\right)\  y+
\left( {t \sp 2}+{10} 
\right)\  {z \sp 2} -
{8 \  z}+
{4 \  {t \sp 2}}+
2, 
\\
\\
\displaystyle
\left( -{3 \  z \  y}+{2 \  t \  z}+t 
\right)\  x+
\left( z+4 
\right)\  y+
{4 \  t \  {z \sp 2}} -{7 \  t \  z},
\\
\\
\displaystyle
\left( -{2 \  z} -2 
\right)\  x -{2 \  {z \sp 2}}+{8 \  z} -2, 
\left( {3 \  {y \sp 2}} -{3 \  {t \sp 2}} -4 
\right)\  {x \sp 2}+
\\
\\
\displaystyle
\left( -{6 \  {y \sp 2}}+
\left( {{12} \  t \  z}+{{12} \  t} 
\right)\  y+{6 \  {t \sp 2} \  z} 
\right)\  x+{3 \  {y \sp 2}}+
\\
\\
\displaystyle
\left.
\left( {{12} \  t \  z} -{{12} \  t} 
\right)\  y+
\left( {9 \  {t \sp 2}}+4 
\right)\  {z \sp 2}+
\left( -{{24} \  {t \sp 2}} -4 
\right)\  z+{{12} \  {t \sp 2}}+4
\right]
\end{array}
$$
\returnType{Type: 
List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

Let us try the information option.  N.B. The timing should be between
1 and 10 minutes, depending on your machine.

\spadcommand{zeroSetSplit(lq,true,true)\$T  }
\begin{verbatim}
[1 <4,0> -> |4|; {0}]W[2 <5,0>,<3,1> -> |8|; {0}][2 <4,1>,<3,1> -> |7|; 
{0}][1 <3,1> -> |3|; {0}]G[2 <4,1>,<4,1> -> |8|; {0}]W[3 <5,1>,<4,1>,
<3,2> -> |12|; {0}]GI[3 <4,2>,<4,1>,<3,2> -> |11|; {0}]GWw[3 <4,1>,
<3,2>,<5,2> -> |12|; {0}][3 <3,2>,<3,2>,<5,2> -> |11|; {0}]GIwWWWw
[4 <3,2>,<4,2>,<5,2>,<2,3> -> |14|; {0}][4 <2,2>,<4,2>,<5,2>,<2,3> -> 
|13|; {0}]Gwww[5 <3,2>,<3,2>,<4,2>,<5,2>,<2,3> -> |17|; {0}]Gwwwwww
[8 <3,2>,<4,2>,<4,2>,<4,2>,<4,2>,<4,2>,<5,2>,<2,3> -> |30|; {0}]Gwwwwww
[8 <4,2>,<4,2>,<4,2>,<4,2>,<4,2>,<4,2>,<5,2>,<2,3> -> |31|; {0}][8 
<3,3>,<4,2>,<4,2>,<4,2>,<4,2>,<4,2>,<5,2>,<2,3> -> |30|; {0}][8 <2,3>,
\end{verbatim}
\begin{verbatim}
<4,2>,<4,2>,<4,2>,<4,2>,<4,2>,<5,2>,<2,3> -> |29|; {0}][8 <1,3>,<4,2>,
<4,2>,<4,2>,<4,2>,<4,2>,<5,2>,<2,3> -> |28|; {0}][7 <4,2>,<4,2>,<4,2>,
<4,2>,<4,2>,<5,2>,<2,3> -> |27|; {0}][6 <4,2>,<4,2>,<4,2>,<4,2>,<5,2>,
<2,3> -> |23|; {0}][5 <4,2>,<4,2>,<4,2>,<5,2>,<2,3> -> |19|; {0}]
GIGIWwww[6 <5,2>,<4,2>,<4,2>,<5,2>,<3,3>,<2,3> -> |23|; {0}][6 <4,3>,
<4,2>,<4,2>,<5,2>,<3,3>,<2,3> -> |22|; {0}]GIGI[6 <3,4>,<4,2>,<4,2>,
<5,2>,<3,3>,<2,3> -> |21|; {0}][6 <2,4>,<4,2>,<4,2>,<5,2>,<3,3>,<2,3> 
-> |20|; {0}]GGG[5 <4,2>,<4,2>,<5,2>,<3,3>,<2,3> -> |18|; {0}]GIGIWwwwW
[6 <5,2>,<4,2>,<5,2>,<3,3>,<3,3>,<2,3> -> |22|; {0}][6 <4,3>,<4,2>,
<5,2>,<3,3>,<3,3>,<2,3> -> |21|; {0}]GIwwWwWWWWWWWwWWWWwwwww[8 <4,2>,
\end{verbatim}
\begin{verbatim}
<5,2>,<3,3>,<3,3>,<4,3>,<2,3>,<3,4>,<3,4> -> |27|; {0}][8 <3,3>,<5,2>,
<3,3>,<3,3>,<4,3>,<2,3>,<3,4>,<3,4> -> |26|; {0}][8 <2,3>,<5,2>,<3,3>,
<3,3>,<4,3>,<2,3>,<3,4>,<3,4> -> |25|; {0}]Gwwwwwwwwwwwwwwwwwwww[9 
<5,2>,<3,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,4>,<3,4> -> |29|; {0}]
GI[9 <4,3>,<3,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,4>,<3,4> -> |28|; 
{0}][9 <3,3>,<3,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,4>,<3,4> -> |27|; 
{0}][9 <2,3>,<3,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,4>,<3,4> -> |26|; 
{0}]GGwwwwwwwwwwwwWWwwwwwwww[11 <3,3>,<3,3>,<3,3>,<3,3>,<4,3>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |33|; {0}][11 <2,3>,<3,3>,<3,3>,<3,3>,
<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |32|; {0}][11 <1,3>,<3,3>,
\end{verbatim}
\begin{verbatim}
<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |31|; {0}]
GGGwwwwwwwwwwwww[12 <2,3>,<2,3>,<3,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,
<3,3>,<3,3>,<3,4>,<3,4> -> |34|; {0}]GGwwwwwwwwwwwww[13 <3,3>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> 
|38|; {0}]Gwwwwwwwwwwwww[13 <2,3>,<3,3>,<4,3>,<3,3>,<4,3>,<3,3>,<3,3>,
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |39|; {0}]GGGwwwwwwwwwwwww[15 
<3,3>,<4,3>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,
<3,3>,<3,4>,<3,4> -> |46|; {0}][14 <4,3>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,
<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |43|; {0}]GIGGGGIGGI
[14 <3,4>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,
\end{verbatim}
\begin{verbatim}
<3,3>,<3,4>,<3,4> -> |42|; {0}]GGG[14 <2,4>,<3,3>,<3,3>,<3,3>,<3,3>,
<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |41|; {0}]
[14 <1,4>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,
<3,3>,<3,4>,<3,4> -> |40|; {0}]GGG[13 <3,3>,<3,3>,<3,3>,<3,3>,<3,3>,
<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |39|; {0}]
Gwwwwwwwwwwwww[15 <3,3>,<3,3>,<4,3>,<4,3>,<4,3>,<3,3>,<3,3>,<4,3>,
<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |48|; {0}]Gwwwwwwwwwwwww
[15 <4,3>,<4,3>,<3,3>,<4,3>,<4,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,3>,
<3,3>,<3,3>,<3,4>,<3,4> -> |49|; {0}]GIGI[15 <3,4>,<4,3>,<3,3>,<4,3>,
<4,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> 
\end{verbatim}
\begin{verbatim}
|48|; {0}]G[14 <4,3>,<3,3>,<4,3>,<4,3>,<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |45|; {0}][13 <3,3>,<4,3>,<4,3>,
<3,3>,<4,3>,<3,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |41|; 
{0}]Gwwwwwwwwwwwww[13 <4,3>,<4,3>,<4,3>,<3,3>,<3,3>,<4,3>,<3,3>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |42|; {0}]GIGGGGIGGI[13 <3,4>,<4,3>,
<4,3>,<3,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> 
|41|; {0}]GGGGGGGG[13 <2,4>,<4,3>,<4,3>,<3,3>,<3,3>,<4,3>,<3,3>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |40|; {0}][13 <1,4>,<4,3>,<4,3>,<3,3>,
<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |39|; {0}]
[13 <0,4>,<4,3>,<4,3>,<3,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,
\end{verbatim}
\begin{verbatim}
<3,4>,<3,4> -> |38|; {0}][12 <4,3>,<4,3>,<3,3>,<3,3>,<4,3>,<3,3>,
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |38|; {1}][11 <4,3>,<3,3>,
<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |34|; {1}]
[10 <3,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> 
|30|; {1}][10 <2,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,
<3,4> -> |29|; {1}]GGGwwwwwwwwwwwww[11 <3,3>,<3,3>,<4,3>,<3,3>,
<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |33|; {1}]
GGGwwwwwwwwwwwww[12 <4,3>,<3,3>,<4,3>,<3,3>,<3,3>,<4,3>,
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |38|; {1}]Gwwwwwwwwwwwww
[12 <3,3>,<4,3>,<5,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,
\end{verbatim}
\begin{verbatim}
<3,4>,<3,4> -> |39|; {1}]GGwwwwwwwwwwwww[13 <5,3>,<4,3>,<4,3>,
<4,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> 
|44|; {1}]GIGGGGIGGIW[13 <4,4>,<4,3>,<4,3>,<4,3>,<3,3>,<3,3>,
<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |43|; {1}]GGW[13 
<3,4>,<4,3>,<4,3>,<4,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,
<3,4>,<3,4> -> |42|; {1}]GGG[12 <4,3>,<4,3>,<4,3>,<3,3>,<3,3>,<4,3>,
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |39|; {1}]Gwwwwwwwwwwwww[12 
<4,3>,<4,3>,<5,3>,<3,3>,<4,3>,<3,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,
<3,4> -> |40|; {1}]Gwwwwwwwwwwwww[13 <5,3>,<5,3>,<4,3>,<5,3>,<3,3>,
<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |46|; {1}]GIGIW
\end{verbatim}
\begin{verbatim}
[13 <4,4>,<5,3>,<4,3>,<5,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,
<3,3>,<3,4>,<3,4> -> |45|; {1}][13 <3,4>,<5,3>,<4,3>,<5,3>,<3,3>,
<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |44|; {1}][13 
<2,4>,<5,3>,<4,3>,<5,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,
<3,4>,<3,4> -> |43|; {1}]GG[12 <5,3>,<4,3>,<5,3>,<3,3>,<3,3>,<4,3>,
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |41|; {1}]GIGGGGIGGIW[12 
<4,4>,<4,3>,<5,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,
<3,4> -> |40|; {1}]GGGGGGW[12 <3,4>,<4,3>,<5,3>,<3,3>,<3,3>,<4,3>,
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |39|; {1}][12 <2,4>,<4,3>,
<5,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |38|; 
\end{verbatim}
\begin{verbatim}
{1}][12 <1,4>,<4,3>,<5,3>,<3,3>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,
<3,4>,<3,4> -> |37|; {1}]GGG[11 <4,3>,<5,3>,<3,3>,<3,3>,<4,3>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |36|; {1}][10 <5,3>,<3,3>,<3,3>,
<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |32|; {1}][9 <3,3>,
<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |27|; {1}]W[9 
<2,4>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |26|; {1}]
[9 <1,4>,<3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |25|; 
{1}][8 <3,3>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |24|; {1}]
W[8 <2,4>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |23|; {1}][8 
<1,4>,<4,3>,<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |22|; {1}][7 <4,3>,
\end{verbatim}
\begin{verbatim}
<2,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |21|; {1}]w[7 <3,4>,<2,3>,
<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |20|; {1}][7 <2,4>,<2,3>,<3,3>,
<3,3>,<3,3>,<3,4>,<3,4> -> |19|; {1}][7 <1,4>,<2,3>,<3,3>,<3,3>,
<3,3>,<3,4>,<3,4> -> |18|; {1}][6 <2,3>,<3,3>,<3,3>,<3,3>,<3,4>,
<3,4> -> |17|; {1}]GGwwwwww[7 <3,3>,<3,3>,<3,3>,<3,3>,<3,3>,<3,4>,
<3,4> -> |21|; {1}]GIW[7 <2,4>,<3,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> 
-> |20|; {1}]GG[6 <3,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |18|; {1}]
Gwwwwww[7 <4,3>,<4,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |23|; {1}]
GIW[7 <3,4>,<4,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |22|; {1}][6 
<4,3>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |19|; {1}]GIW[6 <3,4>,<3,3>,
\end{verbatim}
\begin{verbatim}
<3,3>,<3,3>,<3,4>,<3,4> -> |18|; {1}]GGW[6 <2,4>,<3,3>,<3,3>,<3,3>,
<3,4>,<3,4> -> |17|; {1}][6 <1,4>,<3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> 
|16|; {1}]GGG[5 <3,3>,<3,3>,<3,3>,<3,4>,<3,4> -> |15|; {1}]GIW[5 
<2,4>,<3,3>,<3,3>,<3,4>,<3,4> -> |14|; {1}]GG[4 <3,3>,<3,3>,<3,4>,
<3,4> -> |12|; {1}][3 <3,3>,<3,4>,<3,4> -> |9|; {1}]W[3 <2,4>,<3,4>,
<3,4> -> |8|; {1}][3 <1,4>,<3,4>,<3,4> -> |7|; {1}]G[2 <3,4>,<3,4> 
-> |6|; {1}]G[1 <3,4> -> |3|; {1}][1 <2,4> -> |2|; {1}][1 <1,4> -> 
|1|; {1}]
\end{verbatim}
\begin{verbatim}
   *** QCMPACK Statistics ***
      Table     size:  36
      Entries reused:  255

   *** REGSETGCD: Gcd Statistics ***
      Table     size:  125
      Entries reused:  0

   *** REGSETGCD: Inv Set Statistics ***
      Table     size:  30
      Entries reused:  0
\end{verbatim}
$$
\begin{array}{@{}l}
\left[
\left\{ 
{{960725655771966} \  {t \sp {24}}}+
{{386820897948702} \  {t \sp {23}}}+
\right.
\right.\hbox{\hskip 4.0cm}
\\
\displaystyle
{{8906817198608181} \  {t \sp {22}}}+
{{2704966893949428} \  {t \sp {21}}}+
\\
\displaystyle
{{37304033340228264} \  {t \sp {20}}}+
{{7924782817170207} \  {t \sp {19}}}+
\\
\displaystyle
{{93126799040354990} \  {t \sp {18}}}+
{{13101273653130910} \  {t \sp {17}}}+
\\
\displaystyle
{{156146250424711858} \  {t \sp {16}}}+
{{16626490957259119} \  {t \sp {15}}}+
\\
\displaystyle
{{190699288479805763} \  {t \sp {14}}}+
{{24339173367625275} \  {t \sp {13}}}+
\\
\displaystyle
{{180532313014960135} \  {t \sp {12}}}+
{{35288089030975378} \  {t \sp {11}}}+
\end{array}
$$
$$
\begin{array}{@{}l}
{{135054975747656285} \  {t \sp {10}}}+
{{34733736952488540} \  {t \sp 9}}+\hbox{\hskip 3.7cm}
\\
\displaystyle
{{75947600354493972} \  {t \sp 8}}+
{{19772555692457088} \  {t \sp 7}}+
\\
\displaystyle
{{28871558573755428} \  {t \sp 6}}+
{{5576152439081664} \  {t \sp 5}}+
\\
\displaystyle
{{6321711820352976} \  {t \sp 4}}+
{{438314209312320} \  {t \sp 3}}+
\\
\displaystyle
{{581105748367008} \  {t \sp 2}} -
{{60254467992576} \  t}+
\\
\displaystyle
{1449115951104}, 
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{26604210869491302385515265737052082361668474181372891857784} 
\  {t \sp {23}}}+
\right.
\\
\displaystyle
{{443104378424686086067294899528296664238693556855017735265295} 
\  {t \sp {22}}}+
\\
\displaystyle
{{279078393286701234679141342358988327155321305829547090310242} 
\  {t \sp {21}}}+
\\
\displaystyle
{{3390276361413232465107617176615543054620626391823613392185226} 
\  {t \sp {20}}}+
\\
\displaystyle
{{941478179503540575554198645220352803719793196473813837434129} 
\  {t \sp {19}}}+
\\
\displaystyle
{{11547855194679475242211696749673949352585747674184320988144390} 
\  {t \sp {18}}}+
\\
\displaystyle
{{1343609566765597789881701656699413216467215660333356417241432} 
\  {t \sp {17}}}+
\\
\displaystyle
{{23233813868147873503933551617175640859899102987800663566699334} 
\  {t \sp {16}}}+
\\
\displaystyle
{{869574020537672336950845440508790740850931336484983573386433} 
\  {t \sp {15}}}+
\\
\displaystyle
{{31561554305876934875419461486969926554241750065103460820476969} 
\  {t \sp {14}}}+
\end{array}
$$
$$
\begin{array}{@{}l}
{{1271400990287717487442065952547731879554823889855386072264931} 
\  {t \sp {13}}}+
\\
\displaystyle
{{31945089913863736044802526964079540198337049550503295825160523} 
\  {t \sp {12}}}+
\\
\displaystyle
{{3738735704288144509871371560232845884439102270778010470931960} 
\  {t \sp {11}}}+
\\
\displaystyle
{{25293997512391412026144601435771131587561905532992045692885927} 
\  {t \sp {10}}}+
\\
\displaystyle
{{5210239009846067123469262799870052773410471135950175008046524} 
\  {t \sp 9}}+
\\
\displaystyle
{{15083887986930297166259870568608270427403187606238713491129188} 
\  {t \sp 8}}+
\\
\displaystyle
{{3522087234692930126383686270775779553481769125670839075109000} 
\  {t \sp 7}}+
\\
\displaystyle
{{6079945200395681013086533792568886491101244247440034969288588} 
\  {t \sp 6}}+
\\
\displaystyle
{{1090634852433900888199913756247986023196987723469934933603680} 
\  {t \sp 5}}+
\\
\displaystyle
{{1405819430871907102294432537538335402102838994019667487458352} 
\  {t \sp 4}}+
\end{array}
$$
$$
\begin{array}{@{}l}
{{88071527950320450072536671265507748878347828884933605202432} 
\  {t \sp 3}}+
\\
\displaystyle
{{135882489433640933229781177155977768016065765482378657129440} 
\  {t \sp 2}} -
\\
\displaystyle
{{13957283442882262230559894607400314082516690749975646520320} 
\  t}+
\\
\displaystyle
\left.
{334637692973189299277258325709308472592117112855749713920} 
\right)\  z+
\\
\displaystyle
{{8567175484043952879756725964506833932149637101090521164936} 
\  {t \sp {23}}}+
\\
\displaystyle
{{149792392864201791845708374032728942498797519251667250945721} 
\  {t \sp {22}}}+
\\
\displaystyle
{{77258371783645822157410861582159764138123003074190374021550} 
\  {t \sp {21}}}+
\\
\displaystyle
{{1108862254126854214498918940708612211184560556764334742191654} 
\  {t \sp {20}}}+
\\
\displaystyle
{{213250494460678865219774480106826053783815789621501732672327} 
\  {t \sp {19}}}+
\end{array}
$$
$$
\begin{array}{@{}l}
{{3668929075160666195729177894178343514501987898410131431699882} 
\  {t \sp {18}}}+
\\
\displaystyle
{{171388906471001872879490124368748236314765459039567820048872} 
\  {t \sp {17}}}+
\\
\displaystyle
{{7192430746914602166660233477331022483144921771645523139658986} 
\  {t \sp {16}}} -
\\
\displaystyle
{{128798674689690072812879965633090291959663143108437362453385} 
\  {t \sp {15}}}+
\\
\displaystyle
{{9553010858341425909306423132921134040856028790803526430270671} 
\  {t \sp {14}}} -
\\
\displaystyle
{{13296096245675492874538687646300437824658458709144441096603} 
\  {t \sp {13}}}+
\\
\displaystyle
{{9475806805814145326383085518325333106881690568644274964864413} 
\  {t \sp {12}}}+
\\
\displaystyle
{{803234687925133458861659855664084927606298794799856265539336} 
\  {t \sp {11}}}+
\\
\displaystyle
{{7338202759292865165994622349207516400662174302614595173333825} 
\  {t \sp {10}}}+
\\
\displaystyle
{{1308004628480367351164369613111971668880538855640917200187108} 
\  {t \sp 9}}+
\end{array}
$$
$$
\begin{array}{@{}l}
{{4268059455741255498880229598973705747098216067697754352634748} 
\  {t \sp 8}}+
\\
\displaystyle
{{892893526858514095791318775904093300103045601514470613580600} 
\  {t \sp 7}}+
\\
\displaystyle
{{1679152575460683956631925852181341501981598137465328797013652} 
\  {t \sp 6}}+
\\
\displaystyle
{{269757415767922980378967154143357835544113158280591408043936} 
\  {t \sp 5}}+
\\
\displaystyle
{{380951527864657529033580829801282724081345372680202920198224} 
\  {t \sp 4}}+
\\
\displaystyle
{{19785545294228495032998826937601341132725035339452913286656} 
\  {t \sp 3}}+
\\
\displaystyle
{{36477412057384782942366635303396637763303928174935079178528} 
\  {t \sp 2}} -
\\
\displaystyle
{{3722212879279038648713080422224976273210890229485838670848} 
\  t}+
\\
\displaystyle
{89079724853114348361230634484013862024728599906874105856}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{{{\left( 
{3 \  {z \sp 3}} -
{{11} \  {z \sp 2}}+
{8 \  z}+4 
\right)}\  y}+
{2 \  t \  {z \sp 3}}+
{4 \  t \  {z \sp 2}} -
{5 \  t \  z} -t}, : 
\\
\\
\displaystyle
\left.
\left.
\left( 
z+1 
\right)\  x+
{z \sp 2} -
{4 \  z}+1 
\right\}
\right]
\end{array}
$$
\returnType{Type: 
List RegularTriangularSet(
Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

Between a sequence of processes, thus between a {\tt ]} and a {\tt [}
you can see capital letters {\tt W, G, I} and lower case letters 
{\tt i, w}. Each time a capital letter appears a non-trivial computation
has be performed and its result is put in a hash-table.  Each time a
lower case letter appears a needed result has been found in an
hash-table.  The use of these hash-tables generally speed up the
computations.  However, on very large systems, it may happen that
these hash-tables become too big to be handle by your Axiom
configuration.  Then in these exceptional cases, you may prefer
getting a result (even if it takes a long time) than getting nothing.
Hence you need to know how to prevent the {\tt RSEGSET} constructor
from using these hash-tables.  In that case you will be using the 
{\tt zeroSetSplit} with five arguments.  The first one is the input system
{\bf lp} as above.  The second one is a boolean value {\tt hash?}
which is {\tt true} iff you want to use hash-tables.  The third one is
boolean value {\tt clos?} which is {\tt true} iff you want to solve
your system in the sense of Kalkbrener, the other way remaining that
of Lazard.  The fourth argument is boolean value {\tt info?} which is
{\tt true} iff you want to display information during the
computations.  The last one is boolean value {\tt prep?} which is 
{\tt true} iff you want to use some heuristics that are performed on the
input system before starting the real algorithm.  The value of this
flag is {\tt true} when you are using {\tt zeroSetSplit} with less
than five arguments.  Note that there is no available signature for
{\tt zeroSetSplit} with four arguments.

We finish this section by some remarks about both ways of solving, in
the sense of Kalkbrener or in the sense of Lazard.  For problems with
a finite number of solutions, there are theoretically equivalent and
the resulting decompositions are identical, up to the ordering of the
components.  However, when solving in the sense of Lazard, the
algorithm behaves differently.  In that case, it becomes more
incremental than in the sense of Kalkbrener. That means the
polynomials of the input system are considered one after another
whereas in the sense of Kalkbrener the input system is treated more
globally.

This makes an important difference in positive dimension.  Indeed when
solving in the sense of Kalkbrener, the {\em Primeidealkettensatz} of
Krull is used.  That means any regular triangular containing more
polynomials than the input system can be deleted.  This is not
possible when solving in the sense of Lazard.  This explains why
Kalkbrener's decompositions usually contain less components than those
of Lazard.  However, it may happen with some examples that the
incremental process (that cannot be used when solving in the sense of
Kalkbrener) provide a more efficient way of solving than the global
one even if the {\em Primeidealkettensatz} is used.  Thus just try
both, with the various options, before concluding that you cannot
solve your favorite system with {\tt zeroSetSplit}.  There exist more
options at the development level that are not currently available in
this public version.  

%Original Page 446

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{RomanNumeral}

The Roman numeral package was added to Axiom in MCMLXXXVI for use in
denoting higher order derivatives.

For example, let {\tt f} be a symbolic operator.

\spadcommand{f := operator 'f }
$$
f 
$$
\returnType{Type: BasicOperator}

This is the seventh derivative of {\tt f} with respect to {\tt x}.

\spadcommand{D(f x,x,7) }
$$
{f \sb {{\ }} \sp {{\left( vii 
\right)}}}
\left(
{x} 
\right)
$$
\returnType{Type: Expression Integer}

You can have integers printed as Roman numerals by declaring variables to
be of type {\tt RomanNumeral} (abbreviation {\tt ROMAN}).

\spadcommand{a := roman(1978 - 1965) }
$$
XIII 
$$
\returnType{Type: RomanNumeral}

This package now has a small but devoted group of followers that claim
this domain has shown its efficacy in many other contexts.  They claim
that Roman numerals are every bit as useful as ordinary integers.

In a sense, they are correct, because Roman numerals form a ring and you
can therefore construct polynomials with Roman numeral coefficients,
matrices over Roman numerals, etc..

\spadcommand{x : UTS(ROMAN,'x,0) := x }
$$
x 
$$
\returnType{Type: UnivariateTaylorSeries(RomanNumeral,x,0)}

Was Fibonacci Italian or ROMAN?

\spadcommand{recip(1 - x - x**2) }
$$
\begin{array}{@{}l}
I+x+
{II \  {x \sp 2}}+
{III \  {x \sp 3}}+
{V \  {x \sp 4}}+
{VIII \  {x \sp 5}}+
{XIII \  {x \sp 6}}+
{XXI \  {x \sp 7}}+
\\
\\
\displaystyle
{XXXIV \  {x \sp 8}}+
{LV \  {x \sp 9}}+
{LXXXIX \  {x \sp {10}}}+
{O \left({{x \sp {11}}} \right)}
\end{array}
$$
\returnType{Type: Union(UnivariateTaylorSeries(RomanNumeral,x,0),...)}

You can also construct fractions with Roman numeral numerators and
denominators, as this matrix Hilberticus illustrates.

\spadcommand{m : MATRIX FRAC ROMAN }
\returnType{Type: Void}

%Original Page 447

\spadcommand{m := matrix [ [1/(i + j) for i in 1..3] for j in 1..3]  }
$$
\left[
\begin{array}{ccc}
{\frac{I}{II}} & {\frac{I}{III}} & {\frac{I}{IV}} \\ 
{\frac{I}{III}} & {\frac{I}{IV}} & {\frac{I}{V}} \\ 
{\frac{I}{IV}} & {\frac{I}{V}} & {\frac{I}{VI}} 
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction RomanNumeral}

Note that the inverse of the matrix has integral {\tt ROMAN} entries.

\spadcommand{inverse m }
$$
\left[
\begin{array}{ccc}
LXXII & -CCXL & CLXXX \\ 
-CCXL & CM & -DCCXX \\ 
CLXXX & -DCCXX & DC 
\end{array}
\right]
$$
\returnType{Type: Union(Matrix Fraction RomanNumeral,...)}

Unfortunately, the spoil-sports say that the fun stops when the
numbers get big---mostly because the Romans didn't establish
conventions about representing very large numbers.

\spadcommand{y := factorial 10 }
$$
3628800 
$$
\returnType{Type: PositiveInteger}

You work it out!

\spadcommand{roman y }
$$
\begin{array}{@{}l}
{\rm ((((I))))((((I))))((((I))))(((I)))(((I)))(((I)))(((I)))}
\\
\displaystyle
{\rm (((I)))(((I))) ((I))((I)) MMMMMMMMDCCC} 
\end{array}
$$
\returnType{Type: RomanNumeral}

Issue the system command {\tt )show RomanNumeral} to display the full
list of operations defined by {\tt RomanNumeral}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Segment}

The {\tt Segment} domain provides a generalized interval type.

Segments are created using the {\tt ..} construct by indicating the
(included) end points.

\spadcommand{s := 3..10 }
$$
3..{10} 
$$
\returnType{Type: Segment PositiveInteger}

The first end point is called the \spadfunFrom{lo}{Segment} and the
second is called \spadfunFrom{hi}{Segment}.

\spadcommand{lo s }
$$
3 
$$
\returnType{Type: PositiveInteger}

These names are used even though the end points might belong to an
unordered set.

\spadcommand{hi s }
$$
10 
$$
\returnType{Type: PositiveInteger}

%Original Page 448

In addition to the end points, each segment has an integer ``increment.''
An increment can be specified using the ``{\tt by}'' construct.

\spadcommand{t := 10..3 by -2 }
$$
{{10}..3} \mbox{\rm\ by\ } -2 
$$
\returnType{Type: Segment PositiveInteger}

This part can be obtained using the \spadfunFrom{incr}{Segment} function.

\spadcommand{incr s }
$$
1 
$$
\returnType{Type: PositiveInteger}

Unless otherwise specified, the increment is {\tt 1}.

\spadcommand{incr t }
$$
-2 
$$
\returnType{Type: Integer}

A single value can be converted to a segment with equal end points.
This happens if segments and single values are mixed in a list.

\spadcommand{l := [1..3, 5, 9, 15..11 by -1] }
$$
\left[
{1..3}, {5..5}, {9..9}, {{{15}..{11}} \mbox{\rm by } -1} 
\right]
$$
\returnType{Type: List Segment PositiveInteger}

If the underlying type is an ordered ring, it is possible to perform
additional operations.  The \spadfunFrom{expand}{Segment} operation
creates a list of points in a segment.

\spadcommand{expand s }
$$
\left[
3, 4, 5, 6, 7, 8, 9, {10} 
\right]
$$
\returnType{Type: List Integer}

If {\tt k > 0}, then {\tt expand(l..h by k)} creates the list
{\tt [l, l+k, ..., lN]} where {\tt lN <= h < lN+k}.
If {\tt k < 0}, then {\tt lN >= h > lN+k}.

\spadcommand{expand t }
$$
\left[
{10}, 8, 6, 4 
\right]
$$
\returnType{Type: List Integer}

It is also possible to expand a list of segments.  This is equivalent
to appending lists obtained by expanding each segment individually.

\spadcommand{expand l }
$$
\left[
1, 2, 3, 5, 9, {15}, {14}, {13}, {12}, {11} 
\right]
$$
\returnType{Type: List Integer}

For more information on related topics, see
\domainref{SegmentBinding} and \\
\domainref{UniversalSegment}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{SegmentBinding}

The {\tt SegmentBinding} type is used to indicate a range for a named
symbol.

First give the symbol, then an {\tt =} and finally a segment of values.

\spadcommand{x = a..b}
$$
x={a..b} 
$$
\returnType{Type: SegmentBinding Symbol}

%Original Page 449

This is used to provide a convenient syntax for arguments to certain
operations.

\spadcommand{sum(i**2, i = 0..n)}
$$
\frac{{2 \  {n \sp 3}}+{3 \  {n \sp 2}}+n}{6} 
$$
\returnType{Type: Fraction Polynomial Integer}

\spadcommand{draw(x**2, x = -2..2)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/p449.eps}}
\begin{center}
$x^2, x = -2..2$
\end{center}
\end{minipage}

The left-hand side must be of type {\tt Symbol} but the
right-hand side can be a segment over any type.

\spadcommand{sb := y = 1/2..3/2 }
$$
y={{\left( \frac{1}{2} \right)}..{\left(\frac{3}{2} \right)}}
$$
\returnType{Type: SegmentBinding Fraction Integer}

The left- and right-hand sides can be obtained using the
\spadfunFrom{variable}{SegmentBinding} and
\spadfunFrom{segment}{SegmentBinding} operations.

\spadcommand{variable(sb) }
$$
y 
$$
\returnType{Type: Symbol}

\spadcommand{segment(sb)  }
$$
{\left( \frac{1}{2} \right)}..{\left(\frac{3}{2} \right)}
$$
\returnType{Type: Segment Fraction Integer}

For more information on related topics, see
\domainref{Segment} and \domainref{UniversalSegment}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Set}

The {\tt Set} domain allows one to represent explicit finite sets of values.
These are similar to lists, but duplicate elements are not allowed.

Sets can be created by giving a fixed set of values \ldots

\spadcommand{s := set [x**2-1, y**2-1, z**2-1] }
$$
\left\{
{{x \sp 2} -1}, {{y \sp 2} -1}, {{z \sp 2} -1} 
\right\}
$$
\returnType{Type: Set Polynomial Integer}

%Original Page 450

or by using a collect form, just as for lists.  In either case, the
set is formed from a finite collection of values.

\spadcommand{t := set [x**i - i+1 for i in 2..10 | prime? i] }
$$
\left\{
{{x \sp 2} -1}, {{x \sp 3} -2}, {{x \sp 5} -4}, {{x \sp 7} -6} 
\right\}
$$
\returnType{Type: Set Polynomial Integer}

The basic operations on sets are \spadfunFrom{intersect}{Set},
\spadfunFrom{union}{Set}, \spadfunFrom{difference}{Set}, and
\spadfunFrom{symmetricDifference}{Set}.

\spadcommand{i := intersect(s,t)}
$$
\left\{
{{x \sp 2} -1} 
\right\}
$$
\returnType{Type: Set Polynomial Integer}

\spadcommand{u := union(s,t)}
$$
\left\{
{{x \sp 2} -1}, {{x \sp 3} -2}, {{x \sp 5} -4}, {{x \sp 7} -6}, 
{{y \sp 2} -1}, {{z \sp 2} -1} 
\right\}
$$
\returnType{Type: Set Polynomial Integer}

The set {\tt difference(s,t)} contains those members of {\tt s} which
are not in {\tt t}.

\spadcommand{difference(s,t)}
$$
\left\{
{{y \sp 2} -1}, {{z \sp 2} -1} 
\right\}
$$
\returnType{Type: Set Polynomial Integer}

The set {\tt symmetricDifference(s,t)} contains those elements which are
in {\tt s} or {\tt t} but not in both.

\spadcommand{symmetricDifference(s,t)}
$$
\left\{
{{x \sp 3} -2}, {{x \sp 5} -4}, {{x \sp 7} -6}, {{y \sp 2} -1}, 
{{z \sp 2} -1} 
\right\}
$$
\returnType{Type: Set Polynomial Integer}

Set membership is tested using the \spadfunFrom{member?}{Set} operation.

\spadcommand{member?(y, s)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{member?((y+1)*(y-1), s)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

The \spadfunFrom{subset?}{Set} function determines whether one set is
a subset of another.

\spadcommand{subset?(i, s)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{subset?(u, s)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

When the base type is finite, the absolute complement of a set is
defined.  This finds the set of all multiplicative generators of 
{\tt PrimeField 11}---the integers mod {\tt 11.}

\spadcommand{gs := set [g for i in 1..11 | primitive?(g := i::PF 11)] }
$$
\left\{
2, 6, 7, 8 
\right\}
$$
\returnType{Type: Set PrimeField 11}

%Original Page 451

The following values are not generators.

\spadcommand{complement gs }
$$
\left\{
1, 3, 4, 5, 9, {10}, 0 
\right\}
$$
\returnType{Type: Set PrimeField 11}

Often the members of a set are computed individually; in addition,
values can be inserted or removed from a set over the course of a
computation.

There are two ways to do this:

\spadcommand{a := set [i**2 for i in 1..5] }
$$
\left\{
1, 4, 9, {16}, {25} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

One is to view a set as a data structure and to apply updating operations.

\spadcommand{insert!(32, a) }
$$
\left\{
1, 4, 9, {16}, {25}, {32} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

\spadcommand{remove!(25, a) }
$$
\left\{
1, 4, 9, {16}, {32} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

\spadcommand{a }
$$
\left\{
1, 4, 9, {16}, {32} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

The other way is to view a set as a mathematical entity and to
create new sets from old.

\spadcommand{b := b0 := set [i**2 for i in 1..5] }
$$
\left\{
1, 4, 9, {16}, {25} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

\spadcommand{b := union(b, {32})}
$$
\left\{
1, 4, 9, {16}, {25}, {32} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

\spadcommand{b := difference(b, {25})}
$$
\left\{
1, 4, 9, {16}, {32} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

\spadcommand{b0 }
$$
\left\{
1, 4, 9, {16}, {25} 
\right\}
$$
\returnType{Type: Set PositiveInteger}

For more information about lists, see \domainref{List}.

%Original Page 453

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{SingleInteger}

The {\tt SingleInteger} domain is intended to provide support in Axiom
for machine integer arithmetic.  It is generally much faster than
(bignum) {\tt Integer} arithmetic but suffers from a limited range of
values.  Since Axiom can be implemented on top of various dialects of
Lisp, the actual representation of small integers may not correspond
exactly to the host machines integer representation.

In the CCL implementation of Axiom (Release 2.1 onwards) the underlying
representation of {\tt SingleInteger} is the same as {\tt Integer}.  
The underlying Lisp primitives treat machine-word sized computations
specially.

You can discover the minimum and maximum values in your implementation
by using \spadfunFrom{min}{SingleInteger} and \spadfunFrom{max}{SingleInteger}.

\spadcommand{min()\$SingleInteger}
$$
-{134217728} 
$$
\returnType{Type: SingleInteger}

%Original Page 454

\spadcommand{max()\$SingleInteger}
$$
134217727 
$$
\returnType{Type: SingleInteger}

To avoid confusion with {\tt Integer}, which is the default type for
integers, you usually need to work with declared variables
(\sectionref{ugTypesDeclare}).
\ldots

\spadcommand{a := 1234 :: SingleInteger }
$$
1234 
$$
\returnType{Type: SingleInteger}

or use package calling (\sectionref{ugTypesPkgCall}).

\spadcommand{b := 124\$SingleInteger }
$$
124 
$$
\returnType{Type: SingleInteger}

You can add, multiply and subtract {\tt SingleInteger} objects,
and ask for the greatest common divisor ({\tt gcd}).

\spadcommand{gcd(a,b) }
$$
2 
$$
\returnType{Type: SingleInteger}

The least common multiple ({\tt lcm}) is also available.

\spadcommand{lcm(a,b) }
$$
76508 
$$
\returnType{Type: SingleInteger}

Operations \spadfunFrom{mulmod}{SingleInteger},
\spadfunFrom{addmod}{SingleInteger},
\spadfunFrom{submod}{SingleInteger}, and
\spadfunFrom{invmod}{SingleInteger} are similar---they provide
arithmetic modulo a given small integer.
Here is $5 * 6 {\tt mod} 13$.

\spadcommand{mulmod(5,6,13)\$SingleInteger}
$$
4 
$$
\returnType{Type: SingleInteger}

To reduce a small integer modulo a prime, use
\spadfunFrom{positiveRemainder}{SingleInteger}.

\spadcommand{positiveRemainder(37,13)\$SingleInteger}
$$
11 
$$
\returnType{Type: SingleInteger}

Operations
\spadfunFrom{And}{SingleInteger},
\spadfunFrom{Or}{SingleInteger},
\spadfunFrom{xor}{SingleInteger},
and \spadfunFrom{Not}{SingleInteger}
provide bit level operations on small integers.

\spadcommand{And(3,4)\$SingleInteger}
$$
0 
$$
\returnType{Type: SingleInteger}

Use {\tt shift(int,numToShift)} to shift bits, where {\tt i} is
shifted left if {\tt numToShift} is positive, right if negative.

\spadcommand{shift(1,4)\$SingleInteger}
$$
16 
$$
\returnType{Type: SingleInteger}

\spadcommand{shift(31,-1)\$SingleInteger}
$$
15 
$$
\returnType{Type: SingleInteger}

Many other operations are available for small integers, including many
of those provided for {\tt Integer}.  To see the other operations, use
the Browse HyperDoc facility (\sectionref{ugBrowse})

%Original Page 455

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{SparseTable}

The {\tt SparseTable} domain provides a general purpose table type
with default entries.

Here we create a table to save strings under integer keys.  The value
{\tt "Try again!"} is returned if no other value has been stored for a
key.

\spadcommand{t: SparseTable(Integer, String, "Try again!") := table() }
$$
table() 
$$
\returnType{Type: SparseTable(Integer,String,Try again!)}

Entries can be stored in the table.

\spadcommand{t.3 := "Number three" }
$$
\mbox{\tt "Number three"} 
$$
\returnType{Type: String}

\spadcommand{t.4 := "Number four" }
$$
\mbox{\tt "Number four"} 
$$
\returnType{Type: String}

These values can be retrieved as usual, but if a look up fails the
default entry will be returned.

\spadcommand{t.3 }
$$
\mbox{\tt "Number three"} 
$$
\returnType{Type: String}

\spadcommand{t.2 }
$$
\mbox{\tt "Try again!"} 
$$
\returnType{Type: String}

To see which values are explicitly stored, the
\spadfunFrom{keys}{SparseTable} and \spadfunFrom{entries}{SparseTable}
functions can be used.

\spadcommand{keys t }
$$
\left[
4, 3 
\right]
$$
\returnType{Type: List Integer}

\spadcommand{entries t }
$$
\left[
\mbox{\tt "Number four"} , \mbox{\tt "Number three"} 
\right]
$$
\returnType{Type: List String}

If a specific table representation is required, the 
{\tt GeneralSparseTable} constructor should be used.  The domain 
{\tt SparseTable(K, E, dflt)} is equivalent to\\
{\tt GeneralSparseTable(K, E, Table(K,E), dflt)}.  
For more information, see \domainref{Table} and \domainref{GeneralSparseTable}.

%Original Page 456

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{SquareMatrix}
 
The top level matrix type in Axiom is {\tt Matrix} (see
\domainref{Matrix}, which provides
basic arithmetic and linear algebra functions.  However, since the
matrices can be of any size it is not true that any pair can be added
or multiplied.  Thus {\tt Matrix} has little algebraic structure.
 
Sometimes you want to use matrices as coefficients for polynomials
or in other algebraic contexts.  In this case, {\tt SquareMatrix}
should be used.  The domain {\tt SquareMatrix(n,R)} gives the ring of
{\tt n} by {\tt n} square matrices over {\tt R}.
 
Since {\tt SquareMatrix} is not normally exposed at the top level,
you must expose it before it can be used.

\spadcommand{)set expose add constructor SquareMatrix }
\begin{verbatim}
   SquareMatrix is now explicitly exposed in frame G82322 
\end{verbatim}

Once {\tt SQMATRIX} has been exposed, values can be created using the
\spadfunFrom{squareMatrix}{SquareMatrix} function.

\spadcommand{m := squareMatrix [ [1,-\%i],[\%i,4] ] }
$$
\left[
\begin{array}{cc}
1 & -i \\ 
i & 4 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Complex Integer)}

The usual arithmetic operations are available.

\spadcommand{m*m - m }
$$
\left[
\begin{array}{cc}
1 & -{4 \  i} \\ 
{4 \  i} & {13} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Complex Integer)}

Square matrices can be used where ring elements are required.
For example, here is a matrix with matrix entries.

\spadcommand{mm := squareMatrix [ [m, 1], [1-m, m**2] ] }
$$
\left[
\begin{array}{cc}
{\left[ 
\begin{array}{cc}
1 & -i \\ 
i & 4 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
1 & 0 \\ 
0 & 1 
\end{array}
\right]}
\\ 
{\left[ 
\begin{array}{cc}
0 & i \\ 
-i & -3 
\end{array}
\right]}
& {\left[ 
\begin{array}{cc}
2 & -{5 \  i} \\ 
{5 \  i} & {17} 
\end{array}
\right]}
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,SquareMatrix(2,Complex Integer))}

Or you can construct a polynomial with  square matrix coefficients.

\spadcommand{p := (x + m)**2 }
$$
{x \sp 2}+{{\left[ 
\begin{array}{cc}
2 & -{2 \  i} \\ 
{2 \  i} & 8 
\end{array}
\right]}
\  x}+{\left[ 
\begin{array}{cc}
2 & -{5 \  i} \\ 
{5 \  i} & {17} 
\end{array}
\right]}
$$
\returnType{Type: Polynomial SquareMatrix(2,Complex Integer)}

This value can be converted to a square matrix with polynomial coefficients.

\spadcommand{p::SquareMatrix(2, ?) }
$$
\left[
\begin{array}{cc}
{{x \sp 2}+{2 \  x}+2} & {-{2 \  i \  x} -{5 \  i}} \\ 
{{2 \  i \  x}+{5 \  i}} & {{x \sp 2}+{8 \  x}+{17}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Polynomial Complex Integer)}
 
For more information on related topics, see
\sectionref{ugTypesWritingModes}, \sectionref{ugTypesExpose},
and \domainref{Matrix}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{SquareFreeRegularTriangularSet}

The {\tt SquareFreeRegularTriangularSet} domain constructor implements
square-free regular triangular sets.  See the 
{\tt RegularTriangularSet} domain constructor for general regular
triangular sets.  Let {\em T} be a regular triangular set consisting
of polynomials {\em t1, ..., tm} ordered by increasing main variables.
The regular triangular set {\em T} is square-free if {\em T} is empty
or if {\em t1, ..., tm-1} is square-free and if the polynomial 
{\em tm} is square-free as a univariate polynomial with coefficients in the
tower of simple extensions associated with {\em t1, ..., tm-1}.

The main interest of square-free regular triangular sets is that their
associated towers of simple extensions are product of fields.
Consequently, the saturated ideal of a square-free regular triangular
set is radical.  This property simplifies some of the operations
related to regular triangular sets.  However, building square-free
regular triangular sets is generally more expensive than building
general regular triangular sets.

As the {\tt RegularTriangularSet} domain constructor, the 
{\tt SquareFreeRegularTriangular\-Set} domain constructor also implements a
method for solving polynomial systems by means of regular triangular
sets.  This is in fact the same method with some adaptations to take
into account the fact that the computed regular chains are
square-free.  Note that it is also possible to pass from a
decomposition into general regular triangular sets to a decomposition
into square-free regular triangular sets.  This conversion is used
internally by the {\tt LazardSetSolvingPackage} package constructor.

{\bf N.B.} When solving polynomial systems with the 
{\tt SquareFreeRegularTriangularSet} domain constructor or the 
{\tt LazardSetSolvingPackage} package constructor, decompositions have no
redundant components.  See also {\tt LexTriangularPackage} and 
{\tt ZeroDimensional\-SolvePackage} for the case of algebraic systems with a
finite number of (complex) solutions.

We shall explain now how to use the constructor 
{\tt SquareFreeRegularTriangularSet}.

This constructor takes four arguments.
The first one, {\bf R}, is the coefficient ring of the polynomials;
it must belong to the category {\tt GcdDomain}.
The second one, {\bf E}, is the exponent monoid of the polynomials;
it must belong to the category {\tt OrderedAbelianMonoidSup}.
the third one, {\bf V}, is the ordered set of variables;
it must belong to the category {\tt OrderedSet}.
The last one is the polynomial ring;
it must belong to the category \\
{\tt RecursivePolynomialCategory(R,E,V)}.
The abbreviation for \\
{\tt SquareFreeRegularTriangularSet} is
{\tt SREGSET}.

Note that the way of understanding triangular decompositions 
is detailed in the example of the {\tt RegularTriangularSet}
constructor.

Let us illustrate the use of this constructor with one example
(Donati-Traverso).  Define the coefficient ring.

\spadcommand{R := Integer }
$$
Integer 
$$
\returnType{Type: Domain}

Define the list of variables,

\spadcommand{ls : List Symbol := [x,y,z,t] }
$$
\left[
x, y, z, t 
\right]
$$
\returnType{Type: List Symbol}

and make it an ordered set;

\spadcommand{V := OVAR(ls)  }
$$
\mbox{\rm OrderedVariableList [x,y,z,t]} 
$$
\returnType{Type: Domain}

then define the exponent monoid.

\spadcommand{E := IndexedExponents V  }
$$
\mbox{\rm IndexedExponents OrderedVariableList [x,y,z,t]} 
$$
\returnType{Type: Domain}

Define the polynomial ring.

\spadcommand{P := NSMP(R, V)}
$$
\mbox{\rm NewSparseMultivariatePolynomial(Integer,OrderedVariableList 
[x,y,z,t])} 
$$
\returnType{Type: Domain}

Let the variables be polynomial.

\spadcommand{x: P := 'x  }
$$
x 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{y: P := 'y  }
$$
y 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{z: P := 'z  }
$$
z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{t: P := 't  }
$$
t 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

Now call the {\tt SquareFreeRegularTriangularSet} domain constructor.

\spadcommand{ST := SREGSET(R,E,V,P)}
$$
\begin{array}{@{}l}
{\rm SquareFreeRegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t]))} 
\end{array}
$$
\returnType{Type: Domain}

Define a polynomial system.

\spadcommand{p1 := x ** 31 - x ** 6 - x - y}
$$
{x \sp {31}} -{x \sp 6} -x -y 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{p2 := x ** 8  - z}
$$
{x \sp 8} -z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{p3 := x ** 10 - t}
$$
{x \sp {10}} -t 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{lp := [p1, p2, p3]}
$$
\left[
{{x \sp {31}} -{x \sp 6} -x -y}, {{x \sp 8} -z}, {{x \sp {10}} -t} 
\right]
$$
\returnType{Type: 
List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

First of all, let us solve this system in the sense of Kalkbrener.

\spadcommand{zeroSetSplit(lp)\$ST}
$$
\left[
{\left\{ {{z \sp 5} -{t \sp 4}}, {{t \  z \  {y \sp 2}}+{2 \  {z \sp 3} \  
y} -{t \sp 8}+{2 \  {t \sp 5}}+{t \sp 3} -{t \sp 2}}, {{{\left( {t \sp 4} 
-t 
\right)}
\  x} -{t \  y} -{z \sp 2}} 
\right\}}
\right]
$$
\returnType{Type: 
List SquareFreeRegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

And now in the sense of Lazard (or Wu and other authors).

\spadcommand{zeroSetSplit(lp,false)\$ST}
$$
\begin{array}{@{}l}
\left[
{\left\{ 
{{z \sp 5} -{t \sp 4}}, 
{{t \  z \  {y \sp 2}}+
{2 \  {z \sp 3} \  y} -
{t \sp 8}+
{2 \  {t \sp 5}}+
{t \sp 3} -
{t \sp 2}}, 
{{{\left( {t \sp 4} -t \right)}\  x} -{t \  y} -{z \sp 2}} \right\}},
\right.
\\
\\
\displaystyle
\left.
{\left\{ {{t \sp 3} -1}, {{z \sp 5} -t}, {{t \  y}+{z \sp 2}}, 
{{z \  {x \sp 2}} -t} \right\}},
{\left\{ t, z, y, x \right\}}
\right]
\end{array}
$$
\returnType{Type: 
List SquareFreeRegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

Now to see the difference with the {\tt RegularTriangularSet} domain
constructor, we define:

\spadcommand{T := REGSET(R,E,V,P)}
$$
\begin{array}{@{}l}
{\rm RegularTriangularSet(Integer,}
\\
\displaystyle
{\rm IndexedExponents OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm OrderedVariableList [x,y,z,t]))} 
\end{array}
$$
\returnType{Type: Domain}

and compute:

\spadcommand{lts := zeroSetSplit(lp,false)\$T}
$$
\begin{array}{@{}l}
\displaystyle
\left[
{\left\{ {{z \sp 5} -{t \sp 4}}, 
{{t \  z \  {y \sp 2}}+
{2 \  {z \sp 3} \  y} -
{t \sp 8}+
{2 \  {t \sp 5}}+
{t \sp 3} -
{t \sp 2}}, 
{{{\left( {t \sp 4} -t \right)}\  x} -{t \  y} -{z \sp 2}} \right\}},
\right.
\\
\\
\displaystyle
\left.
{\left\{ {{t \sp 3} -1}, {{z \sp 5} -t}, 
{{t \  z \  {y \sp 2}}+{2 \  {z \sp 3} \  y}+1}, 
{{z \  {x \sp 2}} -t} \right\}},
{\left\{ t, z, y, x \right\}}
\right]
\end{array}
$$
\returnType{Type: 
List RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

If you look at the second set in both decompositions in the sense of Lazard,
you will see that the polynomial with main variable {\bf y} is not the same.

Let us understand what has happened.

We define:

\spadcommand{ts := lts.2}
$$
\left\{
{{t \sp 3} -1}, {{z \sp 5} -t}, {{t \  z \  {y \sp 2}}+{2 \  {z \sp 3} 
\  y}+1}, {{z \  {x \sp 2}} -t} 
\right\}
$$
\returnType{Type: 
RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

\spadcommand{pol := select(ts,'y)\$T}
$$
{t \  z \  {y \sp 2}}+{2 \  {z \sp 3} \  y}+1 
$$
\returnType{Type: 
Union(
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]),...)}

\spadcommand{tower := collectUnder(ts,'y)\$T}
$$
\left\{
{{t \sp 3} -1}, {{z \sp 5} -t} 
\right\}
$$
\returnType{Type: 
RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

\spadcommand{pack := RegularTriangularSetGcdPackage(R,E,V,P,T)}
$$
\begin{array}{@{}l}
{\rm RegularTriangularSetGcdPackage(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t]),}
\\
\displaystyle
{\rm \ \ RegularTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t])))} 
\end{array}
$$
\returnType{Type: Domain}

Then we compute:

\spadcommand{toseSquareFreePart(pol,tower)\$pack}
$$
\left[
{\left[ 
{val={{t \  y}+{z \sp 2}}}, 
{tower={\left\{ {{t \sp 3} -1}, {{z \sp 5} -t} \right\}}}
\right]}
\right]
$$
\returnType{Type: 
List Record(val: 
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]),
tower: RegularTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t])))}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Stack}

A stack is an aggregate structure which allows insertion, deletion, and
inspection of the ``top'' element. Stacks are similar to any pile of
paper where you can only add to the pile, remove the top paper from
the pile, or read the top paper. 

Stacks can be created from a list of elements using the {\bf stack}
function.

\spadcommand{a:Stack INT:= stack [1,2,3,4,5]}
$$
[1,2,3,4,5]
$$
\returnType{Type: Stack Integer}

An empty stack can be created using the {\bf empty} function. 

\spadcommand{a:Stack INT:= empty()}
$$
[]
$$
\returnType{Type: Stack Integer}

The {\bf empty?} function will return {\tt true} if the stack contains
no elements.

\spadcommand{empty? a}
$$
true
$$
\returnType{Type: Boolean}

Stacks modify their arguments so they use the exclamation mark ``!''
as part of the function name.

The {\bf pop!} function removes the top element of the stack and
returns it.  The stack is one element smaller. The {\bf extract!}
function does the same thing with a different name.

\spadcommand{a:Stack INT:= stack [1,2,3,4,5]}
$$ 
[1,2,3,4,5]
$$
\returnType{Type: Stack Integer}

\spadcommand{pop! a}
$$
1
$$
\returnType{Type: PositiveInteger}

\spadcommand{a}
$$
[2,3,4,5]
$$
\returnType{Type: Stack Integer}

The {\bf push!} operation adds a new top element to the stack and returns
the element that was pushed. The stack is one element larger. 
The {\bf insert!} does the same thing with a different name.

\spadcommand{a:Stack INT:= stack [1,2,3,4,5]}
$$
[1,2,3,4,5]
$$
\returnType{Type: Stack Integer}

\spadcommand{push!(9,a)}
$$
9
$$
\returnType{Type: PositiveInteger}

\spadcommand{a}
$$
[9,1,2,3,4,5]
$$
\returnType{Type: Stack Integer}

To read the top element without changing the stack use the {\bf top}
function.

\spadcommand{a:Stack INT:= stack [1,2,3,4,5]}
$$
[1,2,3,4,5]
$$
\returnType{Type: Stack Integer}

\spadcommand{top a}
$$
1
$$
\returnType{Type: PositiveInteger}

\spadcommand{a}
$$
[1,2,3,4,5]
$$
\returnType{Type: Stack Integer}

For more information on related topics, see Queue
\sectionref{Queue}.

%Original Page 457

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Stream}

A {\tt Stream} object is represented as a list whose last element
contains the wherewithal to create the next element, should it ever be
required.

Let {\tt ints} be the infinite stream of non-negative integers.

\spadcommand{ints := [i for i in 0..] }
$$
\left[
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, \ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

By default, ten stream elements are calculated.  This number may be
changed to something else by the system command {\tt )set streams
calculate}.  For the display purposes of this book, we have chosen a
smaller value.

More generally, you can construct a stream by specifying its initial
value and a function which, when given an element, creates the next element.

\spadcommand{f : List INT -> List INT }
\returnType{Type: Void}

\spadcommand{f x == [x.1 + x.2, x.1] }
\returnType{Type: Void}

\spadcommand{fibs := [i.2 for i in [generate(f,[1,1])]] }
\begin{verbatim}
   Compiling function f with type List Integer -> List Integer 
\end{verbatim}
$$
\left[
1, 1, 2, 3, 5, 8, {13}, {21}, {34}, {55}, 
\ldots 
\right]
$$
\returnType{Type: Stream Integer}

You can create the stream of odd non-negative integers by either filtering
them from the integers, or by evaluating an expression for each integer.

\spadcommand{[i for i in ints | odd? i] }
$$
\left[
1, 3, 5, 7, 9, {11}, {13}, {15}, {17}, {19}, 
\ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

\spadcommand{odds := [2*i+1 for i in ints]}
$$
\left[
1, 3, 5, 7, 9, {11}, {13}, {15}, {17}, {19}, 
\ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

You can accumulate the initial segments of a stream using the
\spadfunFrom{scan}{StreamFunctions2} operation.

\spadcommand{scan(0,+,odds) }
$$
\left[
1, 4, 9, {16}, {25}, {36}, {49}, {64}, {81}, 
{100}, \ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

The corresponding elements of two or more streams can be combined in
this way.

\spadcommand{[i*j for i in ints for j in odds] }
$$
\left[
0, 3, {10}, {21}, {36}, {55}, {78}, {105}, {136}, 
{171}, \ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

%Original Page 458

\spadcommand{map(*,ints,odds)}
$$
\left[
0, 3, {10}, {21}, {36}, {55}, {78}, {105}, {136}, 
{171}, \ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

Many operations similar to those applicable to lists are available for
streams.

\spadcommand{first ints }
$$
0 
$$
\returnType{Type: NonNegativeInteger}

\spadcommand{rest ints }
$$
\left[
1, 2, 3, 4, 5, 6, 7, 8, 9, {10}, \ldots 
\right]
$$
\returnType{Type: Stream NonNegativeInteger}

\spadcommand{fibs 20 }
$$
6765 
$$
\returnType{Type: PositiveInteger}

The packages {\tt StreamFunctions1}, {\tt StreamFunctions2} and 
{\tt StreamFunctions3} export some useful stream manipulation operations.
For more information, see \sectionref{ugLangIts},
\sectionref{ugProblemSeries},
\domainref{ContinuedFraction}, and \domainref{List}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{String}

The type {\tt String} provides character strings.  Character strings
provide all the operations for a one-dimensional array of characters,
plus additional operations for manipulating text.  For more
information on related topics, see 
\domainref{Character} and \domainref{CharacterClass}.
You can also issue the system command
{\tt )show String} to display the full list of operations defined
by {\tt String}.

String values can be created using double quotes.

\spadcommand{hello := "Hello, I'm Axiom!" }
$$
\mbox{\tt "Hello, I'm Axiom!"} 
$$
\returnType{Type: String}

Note, however, that double quotes and underscores must be preceded by
an extra underscore.

\spadcommand{said  := "Jane said, \_"Look!\_"" }
$$
\mbox{\tt "Jane said, "Look!""} 
$$
\returnType{Type: String}

\spadcommand{saw   := "She saw exactly one underscore: \_\_." }
$$
\mbox{\tt "She saw exactly one underscore: \_."} 
$$
\returnType{Type: String}

%Original Page 459

It is also possible to use \spadfunFrom{new}{String} to create a
string of any size filled with a given character.  Since there are
many {\tt new} functions it is necessary to indicate the desired type.

\spadcommand{gasp: String := new(32, char "x") }
$$
\mbox{\tt "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"} 
$$
\returnType{Type: String}

The length of a string is given by \spadopFrom{\#}{List}.

\spadcommand{\#gasp }
$$
32 
$$
\returnType{Type: PositiveInteger}

Indexing operations allow characters to be extracted or replaced in strings.
For any string {\tt s}, indices lie in the range {\tt 1..\#s}.

\spadcommand{hello.2 }
$$
e 
$$
\returnType{Type: Character}

Indexing is really just the application of a string to a subscript,
so any application syntax works.

\spadcommand{hello 2  }
$$
e 
$$
\returnType{Type: Character}

\spadcommand{hello(2) }
$$
e 
$$
\returnType{Type: Character}

If it is important not to modify a given string, it should be copied
before any updating operations are used.

\spadcommand{hullo := copy hello }
$$
\mbox{\tt "Hello, I'm Axiom!"} 
$$
\returnType{Type: String}

\spadcommand{hullo.2 := char "u"; [hello, hullo] }
$$
\left[
\mbox{\tt "Hello, I'm Axiom!"} , \mbox{\tt "Hullo, I'm Axiom!"} 
\right]
$$
\returnType{Type: List String}

Operations are provided to split and join strings.  The
\spadfunFrom{concat}{String} operation allows several strings to be
joined together.

\spadcommand{saidsaw := concat ["alpha","---","omega"] }
$$
\mbox{\tt "alpha---omega"} 
$$
\returnType{Type: String}

There is a version of \spadfunFrom{concat}{String} that works with
two strings.

\spadcommand{concat("hello ","goodbye")}
$$
\mbox{\tt "hello goodbye"} 
$$
\returnType{Type: String}

Juxtaposition can also be used to concatenate strings.

\spadcommand{"This " "is " "several " "strings " "concatenated."}
$$
\mbox{\tt "This is several strings concatenated."} 
$$
\returnType{Type: String}

%Original Page 460

Substrings are obtained by giving an index range.

\spadcommand{hello(1..5) }
$$
\mbox{\tt "Hello"} 
$$
\returnType{Type: String}

\spadcommand{hello(8..) }
$$
\mbox{\tt "I'm Axiom!"} 
$$
\returnType{Type: String}

A string can be split into several substrings by giving a separation
character or character class.

\spadcommand{split(hello, char " ")}
$$
\left[
\mbox{\tt "Hello,"} , \mbox{\tt "I'm"} , \mbox{\tt "Axiom!"} 
\right]
$$
\returnType{Type: List String}

\spadcommand{other := complement alphanumeric(); }
\returnType{Type: CharacterClass}

\spadcommand{split(saidsaw, other)}
$$
\left[
\mbox{\tt "alpha"} , \mbox{\tt "omega"} 
\right]
$$
\returnType{Type: List String}

Unwanted characters can be trimmed from the beginning or end of a string
using the operations \spadfunFrom{trim}{String}, \spadfunFrom{leftTrim}{String}
and \spadfunFrom{rightTrim}{String}.

\spadcommand{trim("\#\# ++ relax ++ \#\#", char "\#")}
$$
\mbox{\tt " ++ relax ++ "} 
$$
\returnType{Type: String}

Each of these functions takes a string and a second argument to specify
the characters to be discarded.

\spadcommand{trim("\#\# ++ relax ++ \#\#", other) }
$$
\mbox{\tt "relax"} 
$$
\returnType{Type: String}

The second argument can be given either as a single character or as a
character class.

\spadcommand{leftTrim ("\#\# ++ relax ++ \#\#", other) }
$$
\mbox{\tt "relax ++ \#\#"} 
$$
\returnType{Type: String}

\spadcommand{rightTrim("\#\# ++ relax ++ \#\#", other) }
$$
\mbox{\tt "\#\# ++ relax"} 
$$
\returnType{Type: String}

Strings can be changed to upper case or lower case using the
operations \spadfunFrom{upperCase}{String}, and
\spadfunFrom{lowerCase}{String}.

\spadcommand{upperCase hello }
$$
\mbox{\tt "HELLO, I'M Axiom!"} 
$$
\returnType{Type: String}

%Original Page 461

The versions with the exclamation mark change the original string,
while the others produce a copy.

\spadcommand{lowerCase hello }
$$
\mbox{\tt "hello, i'm axiom!"} 
$$
\returnType{Type: String}

Some basic string matching is provided.  The function
\spadfunFrom{prefix?}{String} tests whether one string is an initial
prefix of another.

\spadcommand{prefix?("He", "Hello")}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{prefix?("Her", "Hello")}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

A similar function, \spadfunFrom{suffix?}{String}, tests for suffixes.

\spadcommand{suffix?("", "Hello")}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{suffix?("LO", "Hello")}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

The function \spadfunFrom{substring?}{String} tests for a substring
given a starting position.

\spadcommand{substring?("ll", "Hello", 3)}
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{substring?("ll", "Hello", 4)}
$$
{\tt false} 
$$
\returnType{Type: Boolean}

A number of \spadfunFrom{position}{String} functions locate things in strings.
If the first argument to position is a string, then {\tt position(s,t,i)}
finds the location of {\tt s} as a substring of {\tt t} starting the
search at position {\tt i}.

\spadcommand{n := position("nd", "underground",   1) }
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{n := position("nd", "underground", n+1)  }
$$
10 
$$
\returnType{Type: PositiveInteger}

If {\tt s} is not found, then {\tt 0} is returned ({\tt minIndex(s)-1}
in {\tt IndexedString}).

\spadcommand{n := position("nd", "underground", n+1) }
$$
0 
$$
\returnType{Type: NonNegativeInteger}

%Original Page 462

To search for a specific character or a member of a character class,
a different first argument is used.

\spadcommand{position(char "d", "underground", 1)}
$$
3 
$$
\returnType{Type: PositiveInteger}

\spadcommand{position(hexDigit(), "underground", 1)}
$$
3 
$$
\returnType{Type: PositiveInteger}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{StringTable}

This domain provides a table type in which the keys are known to be
strings so special techniques can be used.  Other than performance,
the type {\tt StringTable(S)} should behave exactly the same way as
{\tt Table(String,S)}.  See \domainref{Table}
for general information about tables.

This creates a new table whose keys are strings.

\spadcommand{t: StringTable(Integer) := table()  }
$$
table() 
$$
\returnType{Type: StringTable Integer}

The value associated with each string key is the number of characters
in the string.

\begin{verbatim}
for s in split("My name is Ian Watt.",char " ")
  repeat
    t.s := #s
\end{verbatim}
\returnType{Type: Void}

\spadcommand{for key in keys t repeat output [key, t.key] }
\begin{verbatim}
   ["Ian",3]
   ["My",2]
   ["Watt.",5]
   ["name",4]
   ["is",2]
\end{verbatim}
\returnType{Type: Void}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Symbol}
 
Symbols are one of the basic types manipulated by Axiom.  The 
{\tt Symbol} domain provides ways to create symbols of many varieties.

The simplest way to create a symbol is to ``single quote'' an identifier.

\spadcommand{X: Symbol := 'x }
$$
x 
$$
\returnType{Type: Symbol}

%Original Page 463

This gives the symbol even if {\tt x} has been assigned a value.  If
{\tt x} has not been assigned a value, then it is possible to omit the
quote.

\spadcommand{XX: Symbol := x}
$$
x 
$$
\returnType{Type: Symbol}

Declarations must be used when working with symbols, because otherwise
the interpreter tries to place values in a more specialized type 
{\tt Variable}.

\spadcommand{A := 'a}
$$
a 
$$
\returnType{Type: Variable a}

\spadcommand{B := b}
$$
b 
$$
\returnType{Type: Variable b}

The normal way of entering polynomials uses this fact.

\spadcommand{x**2 + 1}
$$
{x \sp 2}+1 
$$
\returnType{Type: Polynomial Integer}

Another convenient way to create symbols is to convert a string.
This is useful when the name is to be constructed by a program.

\spadcommand{"Hello"::Symbol}
$$
Hello 
$$
\returnType{Type: Symbol}

Sometimes it is necessary to generate new unique symbols, for example,
to name constants of integration.  The expression {\tt new()}
generates a symbol starting with {\tt \%}.

\spadcommand{new()\$Symbol}
$$
 \%A 
$$
\returnType{Type: Symbol}

Successive calls to \spadfunFrom{new}{Symbol} produce different symbols.

\spadcommand{new()\$Symbol}
$$
 \%B 
$$
\returnType{Type: Symbol}

The expression {\tt new("s")} produces a symbol starting with {\tt \%s}.

\spadcommand{new("xyz")\$Symbol}
$$
 \%xyz0 
$$
\returnType{Type: Symbol}

A symbol can be adorned in various ways.  The most basic thing is
applying a symbol to a list of subscripts.

\spadcommand{X[i,j] }
$$
x \sb {i, j} 
$$
\returnType{Type: Symbol}

Somewhat less pretty is to attach subscripts, superscripts or arguments.

\spadcommand{U := subscript(u, [1,2,1,2]) }
$$
u \sb {1, 2, 1, 2} 
$$
\returnType{Type: Symbol}

%Original Page 464

\spadcommand{V := superscript(v, [n]) }
$$
v \sp {n} 
$$
\returnType{Type: Symbol}

\spadcommand{P := argscript(p, [t]) }
$$
{p \sb {}} 
\left(
{t} 
\right)
$$
\returnType{Type: Symbol}

It is possible to test whether a symbol has scripts using the
\spadfunFrom{scripted?}{Symbol} test.

\spadcommand{scripted? U }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{scripted? X }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

If a symbol is not scripted, then it may be converted to a string.

\spadcommand{string X }
$$
\mbox{\tt "x"} 
$$
\returnType{Type: String}

The basic parts can always be extracted using the
\spadfunFrom{name}{Symbol} and \spadfunFrom{scripts}{Symbol}
operations.

\spadcommand{name U }
$$
u 
$$
\returnType{Type: Symbol}

\spadcommand{scripts U }
$$
\left[
{sub={\left[ 1, 2, 1, 2 
\right]}},
{sup={\left[ 
\right]}},
{presup={\left[ 
\right]}},
{presub={\left[ 
\right]}},
{args={\left[ 
\right]}}
\right]
$$
\returnType{Type: 
Record(
sub: List OutputForm,
sup: List OutputForm,
presup: List OutputForm,
presub: List OutputForm,
args: List OutputForm)}

\spadcommand{name X }
$$
x 
$$
\returnType{Type: Symbol}

\spadcommand{scripts X }
$$
\left[
{sub={\left[ 
\right]}},
{sup={\left[ 
\right]}},
{presup={\left[ 
\right]}},
{presub={\left[ 
\right]}},
{args={\left[ 
\right]}}
\right]
$$
\returnType{Type: 
Record(
sub: List OutputForm,
sup: List OutputForm,
presup: List OutputForm,
presub: List OutputForm,
args: List OutputForm)}

%Original Page 465

The most general form is obtained using the
\spadfunFrom{script}{Symbol} operation.  This operation takes an
argument which is a list containing, in this order, lists of
subscripts, superscripts, presuperscripts, presubscripts and arguments
to a symbol.

\spadcommand{M := script(Mammoth, [ [i,j],[k,l],[0,1],[2],[u,v,w] ]) }
$$
{{} \sb {2} \sp {{0, 1}}Mammoth \sb {{i, j}} \sp {{k, l}}} 
\left(
{u, v, w} 
\right)
$$
\returnType{Type: Symbol}

\spadcommand{scripts M }
$$
\left[
{sub={\left[ i, j 
\right]}},
{sup={\left[ k, l 
\right]}},
{presup={\left[ 0, 1 
\right]}},
{presub={\left[ 2 
\right]}},
{args={\left[ u, v, w 
\right]}}
\right]
$$
\returnType{Type: 
Record(
sub: List OutputForm,
sup: List OutputForm,
presup: List OutputForm,
presub: List OutputForm,
args: List OutputForm)}

If trailing lists of scripts are omitted, they are assumed to be empty.

\spadcommand{N := script(Nut, [ [i,j],[k,l],[0,1] ]) }
$$
{} \sp {{0, 1}}Nut \sb {{i, j}} \sp {{k, l}} 
$$
\returnType{Type: Symbol}

\spadcommand{scripts N }
$$
\left[
{sub={\left[ i, j 
\right]}},
{sup={\left[ k, l 
\right]}},
{presup={\left[ 0, 1 
\right]}},
{presub={\left[ 
\right]}},
{args={\left[ 
\right]}}
\right]
$$
\returnType{Type: 
Record(
sub: List OutputForm,
sup: List OutputForm,
presup: List OutputForm,
presub: List OutputForm,
args: List OutputForm)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Table}

The {\tt Table} constructor provides a general structure for
associative storage.  This type provides hash tables in which data
objects can be saved according to keys of any type.  For a given
table, specific types must be chosen for the keys and entries.

In this example the keys to the table are polynomials with integer
coefficients.  The entries in the table are strings.

\spadcommand{t: Table(Polynomial Integer, String) := table() }
$$
table() 
$$
\returnType{Type: Table(Polynomial Integer,String)}

To save an entry in the table, the \spadfunFrom{setelt}{Table}
operation is used.  This can be called directly, giving the table a
key and an entry.

\spadcommand{setelt(t, x**2 - 1, "Easy to factor") }
$$
\mbox{\tt "Easy to factor"} 
$$
\returnType{Type: String}

Alternatively, you can use assignment syntax.

\spadcommand{t(x**3 + 1) := "Harder to factor" }
$$
\mbox{\tt "Harder to factor"} 
$$
\returnType{Type: String}

%Original Page 466

\spadcommand{t(x) := "The easiest to factor" }
$$
\mbox{\tt "The easiest to factor"} 
$$
\returnType{Type: String}

Entries are retrieved from the table by calling the
\spadfunFrom{elt}{Table} operation.

\spadcommand{elt(t, x) }
$$
\mbox{\tt "The easiest to factor"} 
$$
\returnType{Type: String}

This operation is called when a table is ``applied'' to a key using
this or the following syntax.

\spadcommand{t.x }
$$
\mbox{\tt "The easiest to factor"} 
$$
\returnType{Type: String}

\spadcommand{t x }
$$
\mbox{\tt "The easiest to factor"} 
$$
\returnType{Type: String}

Parentheses are used only for grouping.  They are needed if the key is
an infixed expression.

\spadcommand{t.(x**2 - 1) }
$$
\mbox{\tt "Easy to factor"} 
$$
\returnType{Type: String}

Note that the \spadfunFrom{elt}{Table} operation is used only when the
key is known to be in the table---otherwise an error is generated.

\spadcommand{t (x**3 + 1) }
$$
\mbox{\tt "Harder to factor"} 
$$
\returnType{Type: String}

You can get a list of all the keys to a table using the
\spadfunFrom{keys}{Table} operation.

\spadcommand{keys t }
$$
\left[
x, {{x \sp 3}+1}, {{x \sp 2} -1} 
\right]
$$
\returnType{Type: List Polynomial Integer}

If you wish to test whether a key is in a table, the
\spadfunFrom{search}{Table} operation is used.  This operation returns
either an entry or {\tt "failed"}.

\spadcommand{search(x, t) }
$$
\mbox{\tt "The easiest to factor"} 
$$
\returnType{Type: Union(String,...)}

\spadcommand{search(x**2, t) }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

The return type is a union so the success of the search can be tested
using {\tt case}.  

\spadcommand{search(x**2, t) case "failed" }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

%Original Page 467

The \spadfunFrom{remove!}{Table} operation is used to delete values from a
table.

\spadcommand{remove!(x**2-1, t)  }
$$
\mbox{\tt "Easy to factor"} 
$$
\returnType{Type: Union(String,...)}

If an entry exists under the key, then it is returned.  Otherwise
\spadfunFrom{remove}{Table} returns {\tt "failed"}.

\spadcommand{remove!(x-1, t) }
$$
\mbox{\tt "failed"} 
$$
\returnType{Type: Union("failed",...)}

The number of key-entry pairs can be found using the
\spadfunFrom{\#}{Table} operation.

\spadcommand{\#t }
$$
2 
$$
\returnType{Type: PositiveInteger}

Just as \spadfunFrom{keys}{Table} returns a list of keys to the table,
a list of all the entries can be obtained using the
\spadfunFrom{members}{Table} operation.

\spadcommand{members t }
$$
\left[
\mbox{\tt "The easiest to factor"} , \mbox{\tt "Harder to factor"} 
\right]
$$
\returnType{Type: List String}

A number of useful operations take functions and map them on to the
table to compute the result.  Here we count the entries which
have ``{\tt Hard}'' as a prefix.

\spadcommand{count(s: String +-> prefix?("Hard", s), t) }
$$
1 
$$
\returnType{Type: PositiveInteger}

Other table types are provided to support various needs.
\indent
\begin{list}{}
\item {\tt AssociationList} gives a list with a table view.
This allows new entries to be appended onto the front of the list
to cover up old entries.
This is useful when table entries need to be stacked or when
frequent list traversals are required.
See \domainref{AssociationList} for more information.
\item {\tt EqTable} gives tables in which keys are considered
equal only when they are in fact the same instance of a structure.
See \domainref{EqTable} for more information.
\item {\tt StringTable} should be used when the keys are known to
be strings.
See \domainref{StringTable} for more information.
\item {\tt SparseTable} provides tables with default
entries, so
lookup never fails.  The {\tt General\-SparseTable} constructor
can be used to make any table type behave this way.
See \domainref{SparseTable} for more information.
\item {\tt KeyedAccessFile} allows values to be saved in a file,\\
accessed as a table.
See \domainref{KeyedAccessFile} for more information.
\end{list}
\noindent

%Original Page 468

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{TextFile}

The domain {\tt TextFile} allows Axiom to read and write
character data and exchange text with other programs.
This type behaves in Axiom much like a {\tt File} of strings,
with additional operations to cause new lines.
We give an example of how to produce an upper case copy of a file.

This is the file from which we read the text.

\spadcommand{f1: TextFile := open("/etc/group", "input")   }
$$
\mbox{\tt "/etc/group"} 
$$
\returnType{Type: TextFile}

This is the file to which we write the text.

\spadcommand{f2: TextFile := open("/tmp/MOTD", "output")  }
$$
\mbox{\tt "/tmp/MOTD"} 
$$
\returnType{Type: TextFile}

Entire lines are handled using the \spadfunFrom{readLine}{TextFile} and
\spadfunFrom{writeLine}{TextFile} operations.

\spadcommand{l := readLine! f1 }
$$
\mbox{\tt "root:x:0:root"} 
$$
\returnType{Type: String}

\spadcommand{writeLine!(f2, upperCase l) }
$$
\mbox{\tt "ROOT:X:0:ROOT"} 
$$
\returnType{Type: String}

Use the \spadfunFrom{endOfFile?}{TextFile} operation to check if you
have reached the end of the file.

\begin{verbatim}
while not endOfFile? f1 repeat
    s := readLine! f1
    writeLine!(f2, upperCase s)
\end{verbatim}
\returnType{Type: Void}

The file {\tt f1} is exhausted and should be closed.

\spadcommand{close! f1  }
$$
\mbox{\tt "/etc/group"} 
$$
\returnType{Type: TextFile}

It is sometimes useful to write lines a bit at a time.  The
\spadfunFrom{write}{TextFile} operation allows this.

\spadcommand{write!(f2, "-The-")  }
$$
\mbox{\tt "-The-"} 
$$
\returnType{Type: String}

\spadcommand{write!(f2, "-End-")  }
$$
\mbox{\tt "-End-"} 
$$
\returnType{Type: String}

This ends the line.  This is done in a machine-dependent manner.

\spadcommand{writeLine! f2}
$$
\mbox{\tt ""} 
$$
\returnType{Type: String}

%Original Page 469

\spadcommand{close! f2}
$$
\mbox{\tt "/tmp/MOTD"} 
$$
\returnType{Type: TextFile}

Finally, clean up.

\spadcommand{)system rm /tmp/MOTD}

For more information on related topics,  see
\domainref{File}, \domainref{KeyedAccessFile}, and \domainref{Library}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{TwoDimensionalArray}

The {\tt TwoDimensionalArray} domain is used for storing data in a
two dimensional data structure indexed by row and by column.  Such an array
is a homogeneous data structure in that all the entries of the array
must belong to the same Axiom domain (although see
\sectionref{ugTypesAnyNone}. Each
array has a fixed number of rows and columns specified by the user and
arrays are not extensible.  In Axiom, the indexing of two-dimensional
arrays is one-based.  This means that both the ``first'' row of an
array and the ``first'' column of an array are given the index 
{\tt 1}.  Thus, the entry in the upper left corner of an array is in
position {\tt (1,1)}.

The operation \spadfunFrom{new}{TwoDimensionalArray} creates an array
with a specified number of rows and columns and fills the components
of that array with a specified entry.  The arguments of this operation
specify the number of rows, the number of columns, and the entry.

This creates a five-by-four array of integers, all of whose entries are
zero.

\spadcommand{arr : ARRAY2 INT := new(5,4,0) }
$$
\left[
\begin{array}{cccc}
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

The entries of this array can be set to other integers using the
operation \spadfunFrom{setelt}{TwoDimensionalArray}.

Issue this to set the element in the upper left corner of this array to
{\tt 17}.

\spadcommand{setelt(arr,1,1,17) }
$$
17 
$$
\returnType{Type: PositiveInteger}

%Original Page 470

Now the first element of the array is {\tt 17.}

\spadcommand{arr }
$$
\left[
\begin{array}{cccc}
{17} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

Likewise, elements of an array are extracted using the operation
\spadfunFrom{elt}{TwoDimensionalArray}.

\spadcommand{elt(arr,1,1) }
$$
17 
$$
\returnType{Type: PositiveInteger}

Another way to use these two operations is as follows.  This sets the
element in position {\tt (3,2)} of the array to {\tt 15}.

\spadcommand{arr(3,2) := 15 }
$$
15 
$$
\returnType{Type: PositiveInteger}

This extracts the element in position {\tt (3,2)} of the array.

\spadcommand{arr(3,2) }
$$
15 
$$
\returnType{Type: PositiveInteger}

The operations \spadfunFrom{elt}{TwoDimensionalArray} and
\spadfunFrom{setelt}{TwoDimensionalArray} come equipped with an error
check which verifies that the indices are in the proper ranges.  For
example, the above array has five rows and four columns, so if you ask
for the entry in position {\tt (6,2)} with {\tt arr(6,2)} Axiom
displays an error message.  If there is no need for an error check,
you can call the operations \spadfunFrom{qelt}{TwoDimensionalArray}
and \spadfunFrom{qsetelt}{TwoDimensionalArray} which provide the same
functionality but without the error check.  Typically, these
operations are called in well-tested programs.

The operations \spadfunFrom{row}{TwoDimensionalArray} and
\spadfunFrom{column}{TwoDimensionalArray} extract rows and columns,
respectively, and return objects of {\tt OneDimensionalArray} with the
same underlying element type.

\spadcommand{row(arr,1) }
$$
\left[
{17}, 0, 0, 0 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

\spadcommand{column(arr,1) }
$$
\left[
{17}, 0, 0, 0, 0 
\right]
$$
\returnType{Type: OneDimensionalArray Integer}

You can determine the dimensions of an array by calling the operations
\spadfunFrom{nrows}{TwoDimensionalArray} and
\spadfunFrom{ncols}{TwoDimensionalArray}, which return the number of
rows and columns, respectively.

\spadcommand{nrows(arr) }
$$
5 
$$
\returnType{Type: PositiveInteger}

%Original Page 471

\spadcommand{ncols(arr) }
$$
4 
$$
\returnType{Type: PositiveInteger}

To apply an operation to every element of an array, use
\spadfunFrom{map}{TwoDimensionalArray}.  This creates a new array.
This expression negates every element.

\spadcommand{map(-,arr) }
$$
\left[
\begin{array}{cccc}
-{17} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & -{15} & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

This creates an array where all the elements are doubled.

\spadcommand{map((x +-> x + x),arr) }
$$
\left[
\begin{array}{cccc}
{34} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & {30} & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

To change the array destructively, use
\spadfunFrom{map}{TwoDimensionalArray} instead of
\spadfunFrom{map}{TwoDimensionalArray}.  If you need to make a copy of
any array, use \spadfunFrom{copy}{TwoDimensionalArray}.

\spadcommand{arrc := copy(arr) }
$$
\left[
\begin{array}{cccc}
{17} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & {15} & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

\spadcommand{map!(-,arrc) }
$$
\left[
\begin{array}{cccc}
-{17} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & -{15} & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

\spadcommand{arrc }
$$
\left[
\begin{array}{cccc}
-{17} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & -{15} & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

%Original Page 472

\spadcommand{arr  }
$$
\left[
\begin{array}{cccc}
{17} & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & {15} & 0 & 0 \\ 
0 & 0 & 0 & 0 \\ 
0 & 0 & 0 & 0 
\end{array}
\right]
$$
\returnType{Type: TwoDimensionalArray Integer}

Use \spadfunFrom{member?}{TwoDimensionalArray} to see if a given element
is in an array.

\spadcommand{member?(17,arr) }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

\spadcommand{member?(10317,arr) }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

To see how many times an element appears in an array, use
\spadfunFrom{count}{TwoDimensionalArray}.

\spadcommand{count(17,arr) }
$$
1 
$$
\returnType{Type: PositiveInteger}

\spadcommand{count(0,arr) }
$$
18 
$$
\returnType{Type: PositiveInteger}

For more information about the operations available for {\tt
TwoDimensionalArray}, issue {\tt )show TwoDimensionalArray}.  For
information on related topics, see 
\domainref{Matrix} and \domainref{OneDimensionalArray}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{TwoDimensionalViewport}

We want to graph $x^3 * (a+b*x)$ on the interval $x=-1..1$
so we clear out the workspace.

We assign values to the constants
\begin{verbatim}
a:=0.5
\end{verbatim}
$$
0.5
$$
\returnType{Type: Float}
\begin{verbatim}
b:=0.5
\end{verbatim}
$$
0.5
$$
\returnType{Type: Float}

We draw the first case of the graph
\begin{verbatim}
y1:=draw(x^3*(a+b*x),x=-1..1,title=="2.2.10 explicit")
\end{verbatim}
$$
\mbox{\rm TwoDimensionalViewport: } \mbox{\tt "2.2.10 explicit"}
$$
\returnType{Type: TwDimensionalViewport}
which results in the image:\\
\includegraphics[scale=2.00]{ps/v0plot1.eps}

We fetch the graph of the first object
\begin{verbatim}
g1:=getGraph(y1,1)
\end{verbatim}
$$
\mbox{\rm Graph with } 1 \mbox{\rm point list}
$$
\returnType{Type: GraphImage}
We extract its points
\begin{verbatim}
pointLists g1
\end{verbatim}
$$
\begin{array}{@{}l}
\left[\left[\right.\right.\\
\quad{}{\left[ -{1.0}, {0.0}, {1.0}, {3.0} \right]}, \\
\quad{}{\left[ -{0.95833333333333337}, -{1.8336166570216028E-2}, {1.0},{3.0} \right]},\\
\quad{}{\left[ -{0.91666666666666674}, -{3.2093942901234518E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.87500000000000011}, -{4.18701171875E-2}, {1.0},  {3.0}\right]},\\
\quad{}{\left[ -{0.83333333333333348}, -{4.8225308641975301E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.79166666666666685}, -{5.1683967496141986E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.75000000000000022}, -{5.2734375E-2}, {1.0},  {3.0}\right]},\\
\quad{}{\left[ -{0.70833333333333359}, -{5.1828643422067916E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.66666666666666696}, -{4.9382716049382741E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.62500000000000033}, -{4.5776367187500042E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.5833333333333337}, -{4.1353202160493867E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.54166666666666707}, -{3.6420657310956832E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.50000000000000044}, -{3.1250000000000056E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.45833333333333376}, -{2.6076328607253136E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.41666666666666707}, -{2.1098572530864244E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.37500000000000039}, -{1.6479492187500042E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.3333333333333337}, -{1.2345679012345713E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.29166666666666702}, -{8.7875554591049648E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.25000000000000033}, -{5.8593750000000208E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.20833333333333368}, -{3.5792221257716214E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.16666666666666702}, -{1.9290123456790237E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{0.12500000000000036}, -{8.5449218750000705E-4}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ -{8.3333333333333703E-2}, -{2.6523919753086765E-4},{1.0},{3.0}\right]},\\
\quad{}{\left[ -{4.1666666666667039E-2},-{3.4661940586420673E-5},{1.0}, {3.0}\right]},\\
\quad{}{\left[ -{3.7470027081099033E-16},-{2.630401389437233E-47},{1.0},{3.0}\right]},\\
\quad{}{\left[ {4.166666666666629E-2,3}. {7676022376542178E-5}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {8.3333333333332954E-2}, {3.1346450617283515E-4}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.12499999999999961}, {1.0986328124999894E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.16666666666666627}, {2.7006172839505972E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.20833333333333293}, {5.463023244598731E-3}, {1.0},  {3.0}\right]},\\
\quad{}{\left[ {0.24999999999999958}, {9.765624999999948E-3}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.29166666666666624}, {1.6024365837191284E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.33333333333333293}, {2.469135802469126E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.37499999999999961}, {3.6254882812499882E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.4166666666666663}, {5.1239390432098617E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.45833333333333298}, {7.0205500096450435E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.49999999999999967}, {9.3749999999999792E-2}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.5416666666666663}, {0.12250584731867258}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.58333333333333293}, {0.15714216820987617}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.62499999999999956}, {0.1983642578124995}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.66666666666666619}, {0.24691358024691298}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.70833333333333282}, {0.30356776861496837}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.74999999999999944}, {0.369140624999999}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.79166666666666607}, {0.44448212046681984}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.8333333333333327}, {0.530478395061727}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.87499999999999933}, {0.62805175781249845}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.91666666666666596}, {0.73816068672839308}, {1.0}, {3.0}\right]},\\
\quad{}{\left[ {0.95833333333333259}, {0.86179982880015205}, {1.0}, {3.0}\right]}, \\
\quad{}{\left[ {1.0}, {1.0}, {1.0}, {3.0}\right]}\\
\left.\left.\right]\right]
\end{array}
$$
\returnType{Type: List List Point DoubleFloat}
Now we create a second graph with a changed parameter
\begin{verbatim}
b:=1.0
\end{verbatim}
$$
1.0
$$
\returnType{Type: Float}
We draw it
\begin{verbatim}
y2:=draw(x^3*(a+b*x),x=-1..1)
\end{verbatim}
$$
\mbox{\rm TwoDimensionalViewport: } \mbox{\tt "Axiom2D"}
$$
\returnType{Type: TwoDimensionalViewport}
which results in the image:\\
\includegraphics[scale=2.00]{ps/v0plot2.eps}

We fetch this new graph
\begin{verbatim}
g2:=getGraph(y2,1)
\end{verbatim}
$$
\mbox{\rm Graph with } 1 \mbox{\rm point list}
$$
\returnType{Type: GraphImage}
We get the points from this graph
\begin{verbatim}
  pointLists g2
\end{verbatim}
$$
\begin{array}{l}
\left[\left[\right.\right.\\
\quad{}{\left[ -{1.0}, {0.5}, {1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.95833333333333337}, {0.40339566454475323}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.91666666666666674}, {0.32093942901234584}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.87500000000000011}, {0.25122070312500017}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.83333333333333348}, {0.19290123456790137}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.79166666666666685}, {0.14471510898919768}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.75000000000000022}, {0.10546875000000019}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.70833333333333359}, {7.404091917438288E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.66666666666666696}, {4.938271604938288E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.62500000000000033}, {3.0517578125000125E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.5833333333333337}, {1.6541280864197649E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.54166666666666707}, {6.6219376929013279E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.50000000000000044}, {5.5511151231257827E-17}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.45833333333333376}, -{4.011742862654287E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.41666666666666707}, -{6.0281635802469057E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.37500000000000039}, -{6.5917968750000035E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.3333333333333337}, -{6.1728395061728461E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.29166666666666702}, -{5.1691502700617377E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.25000000000000033}, -{3.9062500000000104E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.20833333333333368}, -{2.6373215663580349E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.16666666666666702}, -{1.543209876543218E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{0.12500000000000036}, -{7.3242187500000564E-4}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{8.3333333333333703E-2}, -{2.4112654320987957E-4}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{4.1666666666667039E-2}, -{3.315489969135889E-5}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[-{3.7470027081099033E-16}, -{2.6304013894372324E-47}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{4.166666666666629E-2}, {3.9183063271603852E-5}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{8.3333333333332954E-2}, {3.3757716049382237E-4}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.12499999999999961}, {1.2207031249999879E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.16666666666666627}, {3.0864197530863957E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.20833333333333293}, {6.4049238040123045E-3}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.24999999999999958}, {1.1718749999999934E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.29166666666666624}, {1.9642771026234473E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.33333333333333293}, {3.0864197530864071E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.37499999999999961}, {4.6142578124999847E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.4166666666666663}, {6.6309799382715848E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.45833333333333298}, {9.2270085841049135E-2}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.49999999999999967}, {0.12499999999999971}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.5416666666666663}, {0.16554844232253049}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.58333333333333293}, {0.21503665123456736}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.62499999999999956}, {0.27465820312499928}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.66666666666666619}, {0.3456790123456781}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.70833333333333282}, {0.42943733121141858}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.74999999999999944}, {0.52734374999999845}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.79166666666666607}, {0.64088119695215873}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.8333333333333327}, {0.77160493827160281}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.87499999999999933}, {0.92114257812499756}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.91666666666666596}, {1.0911940586419722}, {1.0}, 
{3.0}\right]},\\
\quad{}{\left[{0.95833333333333259}, {1.2835316599151199}, {1.0}, 
{3.0}\right]}, \\
\quad{}{\left[{1.0}, {1.5}, {1.0}, {3.0}\right]}\\
\left.\left.\right]\right]
\end{array}
$$
\returnType{Type: List List Point DoubleFloat}
and we put these points, g2 onto the first graph y1 as graph 2
\begin{verbatim}
putGraph(y1,g2,2)
\end{verbatim}
\returnType{Type: Void}
And now we do the whole sequence again
\begin{verbatim}
b:=2.0
\end{verbatim}
$$
2.0
$$
\returnType{Type: Float}
\begin{verbatim}
y3:=draw(x^3*(a+b*x),x=-1..1)
\end{verbatim}
$$
\mbox{\rm TwoDimensionalViewport: } \mbox{\tt "Axiom2D"}
$$
\returnType{\rm TwoDimensionalViewport}
which results in the image:\\
\includegraphics[scale=2.00]{ps/v0plot3.eps}

\begin{verbatim}
g3:=getGraph(y3,1)
\end{verbatim}
$$
\mbox{\rm Graph with } 1 \mbox{\rm point list}
$$
\returnType{Type: GraphImage}
\vfill
\begin{verbatim}
pointLists g3
\end{verbatim}
$$
\begin{array}{l}
\left[\left[\right.\right.\\
\quad{}{\left[-{1.0}, {1.5}, {1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.95833333333333337}, {1.2468593267746917}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.91666666666666674}, {1.0270061728395066}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.87500000000000011}, {0.83740234375000044}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.83333333333333348}, {0.67515432098765471}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.79166666666666685}, {0.53751326195987703}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.75000000000000022}, {0.42187500000000056}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.70833333333333359}, {0.32578004436728447}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.66666666666666696}, {0.24691358024691412}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.62500000000000033}, {0.18310546875000044}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.5833333333333337}, {0.1323302469135807}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.54166666666666707}, {9.2707127700617648E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.50000000000000044}, {6.2500000000000278E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.45833333333333376}, {4.0117428626543411E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.41666666666666707}, {2.4112654320987775E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.37500000000000039}, {1.3183593750000073E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.3333333333333337}, {6.1728395061728877E-3}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.29166666666666702}, {2.0676601080247183E-3}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[-{0.25000000000000033}, {1.0408340855860843E-17}, 
{1.0},{3.0}\right]},\\
\quad{}{\left[-{0.20833333333333368}, -{7.5352044753086191E-4}, 
{1.0},{3.0}\right]},\\
\quad{}{\left[-{0.16666666666666702}, -{7.7160493827160663E-4}, 
{1.0},{3.0}\right]},\\
\quad{}{\left[-{0.12500000000000036}, -{4.8828125000000282E-4}, 
{1.0},{3.0}\right]},\\
\quad{}{\left[-{8.3333333333333703E-2}, -{1.9290123456790339E-4}, 
{1.0},{3.0}\right]},\\
\quad{}{\left[-{4.1666666666667039E-2}, -{3.0140817901235325E-5}, 
{1.0},{3.0}\right]},\\
\quad{}{\left[-{3.7470027081099033E-16},-{2.6304013894372305E-47},
{1.0},{3.0}\right]},\\
\quad{}{\left[{4.166666666666629E-2}, {4.21971450617272E-5}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{8.3333333333332954E-2}, {3.8580246913579681E-4}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.12499999999999961}, {1.4648437499999848E-3}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.16666666666666627}, {3.8580246913579933E-3}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.20833333333333293}, {8.2887249228394497E-3}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.24999999999999958}, {1.562499999999991E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.29166666666666624}, {2.6879581404320851E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.33333333333333293}, {4.3209876543209694E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.37499999999999961}, {6.5917968749999764E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.4166666666666663}, {9.6450617283950296E-2}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.45833333333333298}, {0.13639925733024652}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.49999999999999967}, {0.18749999999999956}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.5416666666666663}, {0.25163363233024633}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.58333333333333293}, {0.33082561728394977}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.62499999999999956}, {0.42724609374999883}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.66666666666666619}, {0.5432098765432084}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.70833333333333282}, {0.68117645640431912}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.74999999999999944}, {0.84374999999999756}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.79166666666666607}, {1.0336793499228365}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.8333333333333327}, {1.2538580246913544}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.87499999999999933}, {1.507324218749996}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.91666666666666596}, {1.7972608024691306}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{0.95833333333333259}, {2.1269953221450555}, 
{1.0}, {3.0}\right]},\\
\quad{}{\left[{1.0}, {2.5}, {1.0}, {3.0}\right]}\\
\left.\left.\right]\right]
\end{array}
$$
\returnType{Type: List List Point DoubleFloat}
and put the third graphs points g3 onto the first graph y1 as graph 3
\begin{verbatim}
putGraph(y1,g3,3)
\end{verbatim}
\returnType{Type: Void}
Finally we show the combined result
\begin{verbatim}
vp:=makeViewport2D(y1)
\end{verbatim}
$$
\mbox{\rm TwoDimensionalViewport: } \mbox{\tt "2.2.10 explicit"}
$$
\returnType{Type: TwoDimensionalViewport}
which results in the image:\\
\includegraphics[scale=2.00]{ps/v0plot4.eps}\\
which shows all of the graphs in a single image.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{UnaryRecursiveAggregate}

A unary-recursive aggregate is a one where nodes may have either
0 or 1 children. This aggregate models, though not precisely, a linked
list possibly with a single cycle.

A node with one children models a non-empty list, with the value of the 
list designating the head, or first, of the list, and the child 
designating the tail, or rest, of the list. A node with no child then 
designates the empty list. Since these aggregates are recursive aggregates, 
they may be cyclic.

{\bf ELEMENT ACCESS}

You can get the first element by either

\spadcommand{first [1,4,2,-6,0,3,5,4,2,3]}
$$
1
$$
\returnType{Type: PositiveInteger}

or using the subscript form
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1.first}
$$
1
$$
\returnType{Type: PositiveInteger}

You can get multiple elements with
\spadcommand{first([1,4,2,-6,0,3,5,4,2,3],3)}
$$
[1,4,2]
$$
\returnType{Type: List(Integer)}

Similary, you can get the all-but-first elements with
\spadcommand{rest [1,4,2,-6,0,3,5,4,2,3]}
$$
[4,2,- 6,0,3,5,4,2,3]
$$
\returnType{Type: List(Integer)}

or in subscript notation
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1.rest}
$$
[2,3]
$$
\returnType{Type: List(PositiveInteger)}
   
and all-but-n elements with
\spadcommand{rest([1,4,2,-6,0,3,5,4,2,3],3)}
$$
[- 6,0,3,5,4,2,3]
$$
\returnType{Type: List(Integer)}

The last element is available in function form as
\spadcommand{last [1,4,2,-6,0,3,5,4,2,3]}
$$
3
$$
\returnType{Type: PositiveInteger}
or subscript form
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1.last}
$$
3
$$
\returnType{Type: PositiveInteger}
and the last-but-n elements with
\spadcommand{last([1,4,2,-6,0,3,5,4,2,3],3)}
$$
[4,2,3]
$$
\returnType{Type: List(Integer)}

You can get the last element as an aggregate with
\spadcommand{tail [1,4,2,-6,0,3,5,4,2,3]}
$$
[3]
$$
\returnType{Type: List(Integer)}

Specific elements are named with
\spadcommand{second [1,4,2,-6,0,3,5,4,2,3]}
$$
4
$$
\returnType{Type: PositiveInteger}
\spadcommand{third [1,4,2,-6,0,3,5,4,2,3]}
$$
2
$$
\returnType{Type: PositiveInteger}

{\bf AGGREGATION}

We can destructively set positions in the aggregate in function form
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{setfirst!(t1,7)}
$$
7
$$
\returnType{Type: PositiveInteger}
\spadcommand{t1}
$$
[7,2,3]
$$
\returnType{Type: List(PositiveInteger)}
or in subscript form
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1.first:=7}
$$
7
$$
\returnType{Type: PositiveInteger}
\spadcommand{t1}
$$
[7,2,3]
$$
\returnType{Type: List(PositiveInteger)}

We can destructively set the all-but-first to a new aggregate
in function form
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{setrest!(t1,[4,5,6])}
$$
[4,5,6]
$$
\returnType{Type: PositiveInteger}
\spadcommand{t1}
$$
[1,4,5,6]
$$
\returnType{Type: List(PositiveInteger)}
or subscript form
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1.rest:=[4,5,6]}
$$
[4,5,6]
$$
\returnType{Type: PositiveInteger}
\spadcommand{t1}
$$
[1,4,5,6]
$$
\returnType{Type: List(PositiveInteger)}

We can destructively modify the last of the aggregate in function form
\spadcommand{t1:=[1,4,2,-6,0,3,5,4,2,3]}
$$
[1,4,2,- 6,0,3,5,4,2,3]
$$
\returnType{Type: List(Integer)}
\spadcommand{setlast!(t1,7)}
$$
7
$$
\returnType{Type: PositiveInteger}
\spadcommand{t1}
$$
[1,4,2,- 6,0,3,5,4,2,7]
$$
\returnType{Type: List(Integer)}

{\bf CONCATENATION}

The concat function has two forms. It accepts two aggregates
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2:=concat(t1,t1)}
$$
[1,2,3,1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2}
$$
[1,2,3,1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
or it accepts an aggregate element and an aggregate
\spadcommand{t2:=concat(4,t1)}
$$
[4,1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2}
$$
[4,1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
In both cases the operation is non-destructive to t1

There is a destructive form of concatenation of aggregates
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2:=[4,5,6]}
$$
[4,5,6]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{concat!(t1,t2)}
$$
[1,2,3,4,5,6]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1}
$$
[1,2,3,4,5,6]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2}
$$
[4,5,6]
$$
\returnType{Type: List(PositiveInteger)}
and a destructive form for elements
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{concat!(t1,7)}
$$
[1,2,3,7]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t1}
$$
[1,2,3,7]
$$
\returnType{Type: List(PositiveInteger)}

{\bf SPLITTING}

We can destructively split an aggregate into two aggregates with
\spadcommand{t1:=[1,4,2,-6,0,3,5,4,2,3]}
$$
[1,4,2,- 6,0,3,5,4,2,3]
$$
\returnType{Type: List(Integer)}
\spadcommand{t2:=split!(t1,4)}
$$
[0,3,5,4,2,3]
$$
\returnType{Type: List(Integer)}
\spadcommand{t1}
$$
[1,4,2,- 6]
$$
\returnType{Type: List(Integer)}
\spadcommand{t2}
$$
[0,3,5,4,2,3]
$$
\returnType{Type: List(Integer)}

{\bf CYCLES}

Destructive operations can create cycles in lists.
Here t1 contains t1 and we can get the start of the cycle:
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2:=concat!(t1,t1)}
$$
[\overline{1,2,3}]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{cycleEntry t2}
$$
[\overline{1,2,3}]
$$
\returnType{Type: List(PositiveInteger)}
and its length
\spadcommand{cycleLength t2}
$$
3
$$
\returnType{Type: PositiveInteger}
and its tail
\spadcommand{cycleTail t2}
$$
[\overline{3,1,2}]
$$
\returnType{Type: List(PositiveInteger)}

We can also destructively break apart at the cycle start with
\spadcommand{t1:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t2:=concat!(t1,t1)}
$$
[\overline{1,2,3}]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t3:=[1,2,3]}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t4:=concat!(t3,t2)}
$$
[1,2,3,\overline{1,2,3}]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t5:=cycleSplit!(t4)}
$$
[\overline{1,2,3}]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t4}
$$
[1,2,3]
$$
\returnType{Type: List(PositiveInteger)}
\spadcommand{t5}
$$
[\overline{1,2,3}]
$$
\returnType{Type: List(PositiveInteger)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{UnivariatePolynomial}

The domain constructor {\tt UnivariatePolynomial} (abbreviated {\tt
UP}) creates domains of univariate polynomials in a specified
variable.  For example, the domain {\tt UP(a1,POLY FRAC INT)} provides
polynomials in the single variable {\tt a1} whose coefficients are
general polynomials with rational number coefficients.

\boxer{4.6in}{
\noindent {\bf Restriction:}
\begin{quotation}\noindent
Axiom does not allow you to create types where\\
{\tt UnivariatePolynomial} is contained in the coefficient type of\\
{\tt Polynomial}. Therefore,
{\tt UP(x,POLY INT)} is legal but {\tt POLY UP(x,INT)} is not.
\end{quotation}
.
}

%Original Page 473

{\tt UP(x,INT)} is the domain of polynomials in the single
variable {\tt x} with integer coefficients.

\spadcommand{(p,q) : UP(x,INT) }
\returnType{Type: Void}

\spadcommand{p := (3*x-1)**2 * (2*x + 8) }
$$
{{18} \  {x \sp 3}}+{{60} \  {x \sp 2}} -{{46} \  x}+8 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

\spadcommand{q := (1 - 6*x + 9*x**2)**2 }
$$
{{81} \  {x \sp 4}} -{{108} \  {x \sp 3}}+{{54} \  {x \sp 2}} -{{12} \  x}+1 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

The usual arithmetic operations are available for univariate polynomials.

\spadcommand{p**2 + p*q  }
$$
{{1458} \  {x \sp 7}}+{{3240} \  {x \sp 6}} -{{7074} \  {x \sp 5}}+{{10584} \  
{x \sp 4}} -{{9282} \  {x \sp 3}}+{{4120} \  {x \sp 2}} -{{878} \  x}+{72} 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

The operation \spadfunFrom{leadingCoefficient}{UnivariatePolynomial}
extracts the coefficient of the term of highest degree.

\spadcommand{leadingCoefficient p }
$$
18 
$$
\returnType{Type: PositiveInteger}

The operation \spadfunFrom{degree}{UnivariatePolynomial} returns
the degree of the polynomial.
Since the polynomial has only one variable, the variable is not supplied
to operations like \spadfunFrom{degree}{UnivariatePolynomial}.

\spadcommand{degree p }
$$
3 
$$
\returnType{Type: PositiveInteger}

The reductum of the polynomial, the polynomial obtained by subtracting
the term of highest order, is returned by
\spadfunFrom{reductum}{UnivariatePolynomial}.

\spadcommand{reductum p }
$$
{{60} \  {x \sp 2}} -{{46} \  x}+8 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

The operation \spadfunFrom{gcd}{UnivariatePolynomial} computes the
greatest common divisor of two polynomials.

\spadcommand{gcd(p,q) }
$$
{9 \  {x \sp 2}} -{6 \  x}+1 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

The operation \spadfunFrom{lcm}{UnivariatePolynomial} computes the
least common multiple.

\spadcommand{lcm(p,q) }
$$
{{162} \  {x \sp 5}}+{{432} \  {x \sp 4}} -{{756} \  {x \sp 3}}+{{408} \  {x 
\sp 2}} -{{94} \  x}+8 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

The operation \spadfunFrom{resultant}{UnivariatePolynomial} computes
the resultant of two univariate polynomials.  In the case of {\tt p}
and {\tt q}, the resultant is {\tt 0} because they share a common
root.

\spadcommand{resultant(p,q) }
$$
0 
$$
\returnType{Type: NonNegativeInteger}

%Original Page 474

To compute the derivative of a univariate polynomial with respect to its
variable, use \spadfunFrom{D}{UnivariatePolynomial}.

\spadcommand{D p }
$$
{{54} \  {x \sp 2}}+{{120} \  x} -{46} 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

Univariate polynomials can also be used as if they were functions.  To
evaluate a univariate polynomial at some point, apply the polynomial
to the point.

\spadcommand{p(2) }
$$
300 
$$
\returnType{Type: PositiveInteger}

The same syntax is used for composing two univariate polynomials, i.e.
substituting one polynomial for the variable in another.  This
substitutes {\tt q} for the variable in {\tt p}.

\spadcommand{p(q) }
$$
\begin{array}{@{}l}
\displaystyle
{{9565938} \  {x \sp {12}}} -
{{38263752} \  {x \sp {11}}}+
{{70150212} \  {x \sp {10}}} -
{{77944680} \  {x \sp 9}}+
{{58852170} \  {x \sp 8}} -
\\
\\
\displaystyle
{{32227632} \  {x \sp 7}}+
{{13349448} \  {x \sp 6}} -
{{4280688} \  {x \sp 5}}+
{{1058184} \  {x \sp 4}} -
\\
\\
\displaystyle
{{192672} \  {x \sp 3}}+
{{23328} \  {x \sp 2}} -
{{1536} \  x}+
{40} 
\end{array}
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

This substitutes {\tt p} for the variable in {\tt q}.

\spadcommand{q(p) }
$$
\begin{array}{@{}l}
\displaystyle
{{8503056} \  {x \sp {12}}}+
{{113374080} \  {x \sp {11}}}+
{{479950272} \  {x \sp {10}}}+
{{404997408} \  {x \sp 9}} -
\\
\\
\displaystyle
{{1369516896} \  {x \sp 8}} -
{{626146848} \  {x \sp 7}}+
{{2939858712} \  {x \sp 6}} -
{{2780728704} \  {x \sp 5}}+
\\
\\
\displaystyle
{{1364312160} \  {x \sp 4}} -
{{396838872} \  {x \sp 3}}+
{{69205896} \  {x \sp 2}} -
{{6716184} \  x}+
{279841} 
\end{array}
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

To obtain a list of coefficients of the polynomial, use
\spadfunFrom{coefficients}{UnivariatePolynomial}.

\spadcommand{l := coefficients p }
$$
\left[
{18}, {60}, -{46}, 8 
\right]
$$
\returnType{Type: List Integer}

From this you can use \spadfunFrom{gcd}{UnivariatePolynomial} and
\spadfunFrom{reduce}{List} to compute the content of the polynomial.

\spadcommand{reduce(gcd,l) }
$$
2 
$$
\returnType{Type: PositiveInteger}

Alternatively (and more easily), you can just call
\spadfunFrom{content}{UnivariatePolynomial}.

\spadcommand{content p }
$$
2 
$$
\returnType{Type: PositiveInteger}

Note that the operation
\spadfunFrom{coefficients}{UnivariatePolynomial} omits the zero
coefficients from the list.  Sometimes it is useful to convert a
univariate polynomial to a vector whose $i$-th position contains the
degree {\tt i-1} coefficient of the polynomial.

%Original Page 475

\spadcommand{ux := (x**4+2*x+3)::UP(x,INT) }
$$
{x \sp 4}+{2 \  x}+3 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

To get a complete vector of coefficients, use the operation
\spadfunFrom{vectorise}{UnivariatePolynomial}, which takes a
univariate polynomial and an integer denoting the length of the
desired vector.

\spadcommand{vectorise(ux,5) }
$$
\left[
3, 2, 0, 0, 1 
\right]
$$
\returnType{Type: Vector Integer}

It is common to want to do something to every term of a polynomial,
creating a new polynomial in the process.

This is a function for iterating across the terms of a polynomial,
squaring each term.

\spadcommand{squareTerms(p) ==   reduce(+,[t**2 for t in monomials p])}
\returnType{Type: Void}

Recall what {\tt p} looked like.

\spadcommand{p }
$$
{{18} \  {x \sp 3}}+{{60} \  {x \sp 2}} -{{46} \  x}+8 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

We can demonstrate {\tt squareTerms} on {\tt p}.

\spadcommand{squareTerms p }
\begin{verbatim}
Compiling function squareTerms with type 
  UnivariatePolynomial(x,Integer) -> 
    UnivariatePolynomial(x,Integer) 
\end{verbatim}
$$
{{324} \  {x \sp 6}}+{{3600} \  {x \sp 4}}+{{2116} \  {x \sp 2}}+{64} 
$$
\returnType{Type: UnivariatePolynomial(x,Integer)}

When the coefficients of the univariate polynomial belong to a
field,\footnote{For example, when the coefficients are rational
numbers, as opposed to integers.  The important property of a field is
that non-zero elements can be divided and produce another element. The
quotient of the integers 2 and 3 is not another integer.}  it is
possible to compute quotients and remainders.

\spadcommand{(r,s) : UP(a1,FRAC INT) }
\returnType{Type: Void}

\spadcommand{r := a1**2 - 2/3  }
$$
{a1 \sp 2} -{\frac{2}{3}} 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

%Original Page 476

\spadcommand{s := a1 + 4}
$$
a1+4 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

When the coefficients are rational numbers or rational expressions, the
operation \spadfunFrom{quo}{UnivariatePolynomial} computes the quotient
of two polynomials.

\spadcommand{r quo s }
$$
a1 -4 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

The operation \spadfunFrom{rem}{UnivariatePolynomial} computes the
remainder.

\spadcommand{r rem s }
$$
\frac{46}{3} 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

The operation \spadfunFrom{divide}{UnivariatePolynomial} can be used to
return a record of both components.

\spadcommand{d := divide(r, s) }
$$
\left[
{quotient={a1 -4}}, {remainder={\frac{46}{3}}} 
\right]
$$
\returnType{Type: 
Record(
quotient: UnivariatePolynomial(a1,Fraction Integer),
remainder: UnivariatePolynomial(a1,Fraction Integer))}

Now we check the arithmetic!

\spadcommand{r - (d.quotient * s + d.remainder) }
$$
0 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

It is also possible to integrate univariate polynomials when the
coefficients belong to a field.

\spadcommand{integrate r }
$$
{{\frac{1}{3}} \  {a1 \sp 3}} -{{\frac{2}{3}} \  a1} 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

\spadcommand{integrate s }
$$
{{\frac{1}{2}} \  {a1 \sp 2}}+{4 \  a1} 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Integer)}

One application of univariate polynomials is to see expressions in terms
of a specific variable.

We start with a polynomial in {\tt a1} whose coefficients
are quotients of polynomials in {\tt b1} and {\tt b2}.

\spadcommand{t : UP(a1,FRAC POLY INT) }
\returnType{Type: Void}

Since in this case we are not talking about using multivariate
polynomials in only two variables, we use {\tt Polynomial}.
We also use {\tt Fraction} because we want fractions.

\spadcommand{t := a1**2 - a1/b2 + (b1**2-b1)/(b2+3) }
$$
{a1 \sp 2} -{{\frac{1}{b2}} \  a1}+{\frac{{b1 \sp 2} -b1}{b2+3}} 
$$
\returnType{Type: UnivariatePolynomial(a1,Fraction Polynomial Integer)}

%Original Page 477

We push all the variables into a single quotient of polynomials.

\spadcommand{u : FRAC POLY INT := t }
$$
\frac{{{a1 \sp 2} \  {b2 \sp 2}}+{{\left( {b1 \sp 2} -b1+{3 \  {a1 \sp 2}} -a1 
\right)}\  b2} -{3 \  a1}}{{b2 \sp 2}+{3 \  b2}} 
$$
\returnType{Type: Fraction Polynomial Integer}

Alternatively, we can view this as a polynomial in the variable
This is a {\it mode-directed} conversion: you indicate
as much of the structure as you care about and let Axiom
decide on the full type and how to do the transformation.

\spadcommand{u :: UP(b1,?) }
$$
{{\frac{1}{b2+3}} \  {b1 \sp 2}} -{{\frac{1}{b2+3}} \  b1}
+{\frac{{{a1 \sp 2} \  b2} -a1}{b2}} 
$$
\returnType{Type: UnivariatePolynomial(b1,Fraction Polynomial Integer)}

See \sectionref{ugProblemFactor} 
for a discussion of the factorization facilities
in Axiom for univariate polynomials.
For more information on related topics, see
\sectionref{ugIntroVariables},
\sectionref{ugTypesConvert},
\domainref{Polynomial}, \domainref{MultivariatePolynomial}, and
\domainref{DistributedMultivariatePolynomial}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{UnivariateSkewPolynomial}

Skew or Ore polynomial rings provide a unified framework to
compute with differential and difference equations.

In the following, let A be an integral domain, equipped with two
endomorphisms $\sigma$ and $\delta$ where:
\begin{itemize}
\item $\sigma$: A $->$ A is an injective ring endomorphism
\item $\delta$: A $->$ A, the pseudo-derivation with respect to $\sigma$, 
is an additive endomorphism with 
$$
     \delta(ab) = \sigma(a)\delta(b) + \delta(a)b
$$    
for all $a,b$ in A
\end{itemize}

The skew polynomial ring $[\Delta;\sigma,\delta]$ is the ring of 
polynomials in $\Delta$ with coefficients in A, with the usual addition,
while the product is given by
$$
 \Delta a = \sigma(a)\Delta + \delta(a)\quad{}{\rm\ for\ a\ in\ A}
$$
The two most important examples of skew polynomial rings are:
\begin{itemize}
\item $K(x)[D,1,\delta]$, where 1 is the identity on $K$ and $\delta$ is 
the usual derviative, is the ring of differential polynomials
\item $K_n [E,n,\mapsto n+1,0]$ is the ring of linear recurrence operators
with polynomial coefficients
\end{itemize}

The UnivariateSkewPolynomialCategory (OREPCAT) provides a unified
framework for polynomial rings in a non-central indeterminate over
some coefficient ring R. The commutation relations between the
indeterminate $x$ and the coefficient $t$ is given by 
$$ 
x r = \sigma(r) x + \delta(r)
$$
where $\sigma$ is a ring endomorphism of R
and $\delta$ is a $\sigma$-derivation of R
which is an additive map from R to R such that
$$  
\delta(rs) = \sigma(r) \delta(s) + \delta(r) s
$$
In case $\sigma$ is the identity map on R, a $\sigma$-derivation of R
is just called a derivation. Here are some examples

We start with a linear ordinary differential operator. First, we
define the coefficient ring to be expressions in one variable $x$
with fractional coefficients:

\spadcommand{F:=EXPR(FRAC(INT))}

Define Dx to be a derivative d/dx:

\spadcommand{Dx:F->F:=f+->D(f,['x])}

Define a skew polynomial ring over F with identity endomorphism as
$\sigma$ and derivation d/dx as $\delta$:

\spadcommand{D0:=OREUP('d,F,1,Dx)}

\spadcommand{u:D0:=(operator 'u)(x)}
$$
u 
\left(
{x} 
\right)
$$

\spadcommand{d:D0:='d}
$$
d 
$$

\spadcommand{a:D0:=u**3*d**3+u**2*d**2+u*d+1}
$$
{{{u 
\left(
{x} 
\right)}^3}
\  {d^3}}+{{{u 
\left(
{x} 
\right)}^2}
\  {d^2}}+{{u 
\left(
{x} 
\right)}
\  d}+1 
$$

\spadcommand{b:D0:=(u+1)*d**2+2*d}
$$
{{\left( {u 
\left(
{x} 
\right)}+1
\right)}
\  {d^2}}+{2 \  d} 
$$

\spadcommand{r:=rightDivide(a,b)}
$$
\left[
\begin{array}{c}
\displaystyle
{quotient={{{ \frac{{{u 
\left(
{x} 
\right)}^3}}{{{u
\left(
{x} 
\right)}+1}}}
\  d}+{ \frac{{-{{{u 
\left(
{x} 
\right)}^3}
\  {{u \sb {{\ }} \sp {,}} 
\left(
{x} 
\right)}}
-{{u 
\left(
{x} 
\right)}^3}+{{u
\left(
{x} 
\right)}^2}}}{{{{u
\left(
{x} 
\right)}^2}+{2
\  {u 
\left(
{x} 
\right)}}+1}}}}},\\
\displaystyle
\: {remainder={{{ \frac{{{2 \  {{u 
\left(
{x} 
\right)}^3}
\  {{u \sb {{\ }} \sp {,}} 
\left(
{x} 
\right)}}+{3
\  {{u 
\left(
{x} 
\right)}^3}}+{u
\left(
{x} 
\right)}}}{{{{u
\left(
{x} 
\right)}^2}+{2
\  {u 
\left(
{x} 
\right)}}+1}}}
\  d}+1}}
\end{array}
\right]
$$

\spadcommand{r.quotient}
$$
{{ \frac{{{u 
\left(
{x} 
\right)}^3}}{{{u
\left(
{x} 
\right)}+1}}}
\  d}+{ \frac{{-{{{u 
\left(
{x} 
\right)}^3}
\  {{u \sb {{\ }} \sp {,}} 
\left(
{x} 
\right)}}
-{{u 
\left(
{x} 
\right)}^3}+{{u
\left(
{x} 
\right)}^2}}}{{{{u
\left(
{x} 
\right)}^2}+{2
\  {u 
\left(
{x} 
\right)}}+1}}}
$$

\spadcommand{r.remainder}
$$
{{ \frac{{{2 \  {{u 
\left(
{x} 
\right)}^3}
\  {{u \sb {{\ }} \sp {,}} 
\left(
{x} 
\right)}}+{3
\  {{u 
\left(
{x} 
\right)}^3}}+{u
\left(
{x} 
\right)}}}{{{{u
\left(
{x} 
\right)}^2}+{2
\  {u 
\left(
{x} 
\right)}}+1}}}
\  d}+1 
$$

\subsection{A second example}
)clear all
 
As a second example, we consider the so-called Weyl algebra.

Define the coefficient ring to be an ordinary polynomial over integers
in one variable $t$
\begin{verbatim}
R:=UP('t,INT)
\end{verbatim}
Define a skew polynomial ring over R with identity map as $\sigma$
and derivation d/dt as $\delta$. The resulting algebra is then called
a Weyl algebra. This is a simple ring over a division ring that is
non-commutative, similar to the ring of matrices.

\spadcommand{R:=UP('t,INT)}

\spadcommand{W:=OREUP('x,R,1,D)}

\spadcommand{t:W:='t}
$$
t 
$$

\spadcommand{x:W:='x}
$$
x 
$$

Let 

\spadcommand{a:W:=(t-1)*x**4+(t**3+3*t+1)*x**2+2*t*x+t**3}
$$
{{\left( t -1 
\right)}
\  {x^4}}+{{\left( {t^3}+{3 \  t}+1 
\right)}
\  {x^2}}+{2 \  t \  x}+{t^3} 
$$

\spadcommand{b:W:=(6*t**4+2*t**2)*x**3+3*t**2*x**2}
$$
{{\left( {6 \  {t^4}}+{2 \  {t^2}} 
\right)}
\  {x^3}}+{3 \  {t^2} \  {x^2}} 
$$

Then

\spadcommand{a*b}
$$
\begin{array}{l}
{{\left( {6 \  {t^5}} -{6 \  {t^4}}+{2 \  {t^3}} -{2 \  {t^2}} 
\right)}
\  {x^7}}+{{\left( {{96} \  {t^4}} -{{93} \  {t^3}}+{{13} \  {t^2}} -{{16} \  
t} 
\right)}
\  {x^6}}+\\
{{\left( {6 \  {t^7}}+{{20} \  {t^5}}+{6 \  {t^4}}+{{438} \  {t^3}} 
-{{406} \  {t^2}} -{24} 
\right)}
\  {x^5}}+\\
{{\left( {{48} \  {t^6}}+{{15} \  {t^5}}+{{152} \  {t^4}}+{{61} \  
{t^3}}+{{603} \  {t^2}} -{{532} \  t} -{36} 
\right)}
\  {x^4}}+\\
{{\left( {6 \  {t^7}}+{{74} \  {t^5}}+{{60} \  {t^4}}+{{226} \  
{t^3}}+{{116} \  {t^2}}+{{168} \  t} -{140} 
\right)}
\  {x^3}}+\\
{{\left( {3 \  {t^5}}+{6 \  {t^3}}+{{12} \  {t^2}}+{{18} \  t}+6 
\right)}
\  {x^2}} 
\end{array}
$$

\spadcommand{a**3}
$$
\begin{array}{l}
{{\left( {t^3} -{3 \  {t^2}}+{3 \  t} -1 
\right)}
\  {x^{12}}}+{{\left( {3 \  {t^5}} -{6 \  {t^4}}+{{12} \  {t^3}} -{{15} \  
{t^2}}+{3 \  t}+3 
\right)}
\  {x^{10}}}+\\
{{\left( {6 \  {t^3}} -{{12} \  {t^2}}+{6 \  t} 
\right)}
\  {x^9}}+{{\left( {3 \  {t^7}} -{3 \  {t^6}}+{{21} \  {t^5}} -{{18} \  
{t^4}}+{{24} \  {t^3}} -{9 \  {t^2}} -{{15} \  t} -3 
\right)}
\  {x^8}}+\\
{{\left( {{12} \  {t^5}} -{{12} \  {t^4}}+{{36} \  {t^3}} -{{24} \  
{t^2}} -{{12} \  t} 
\right)}
\  {x^7}}+\\
{{\left( {t^9}+{{15} \  {t^7}} -{3 \  {t^6}}+{{45} \  {t^5}}+{6 \  
{t^4}}+{{36} \  {t^3}}+{{15} \  {t^2}}+{9 \  t}+1 
\right)}
\  {x^6}}+\\
{{\left( {6 \  {t^7}}+{{48} \  {t^5}}+{{54} \  {t^3}}+{{36} \  
{t^2}}+{6 \  t} 
\right)}
\  {x^5}}+\\
{{\left( {3 \  {t^9}}+{{21} \  {t^7}}+{3 \  {t^6}}+{{39} \  
{t^5}}+{{18} \  {t^4}}+{{39} \  {t^3}}+{{12} \  {t^2}} 
\right)}
\  {x^4}}+\\
{{\left( {{12} \  {t^7}}+{{36} \  {t^5}}+{{12} \  {t^4}}+{8 \  
{t^3}} 
\right)}
\  {x^3}}+\\
{{\left( {3 \  {t^9}}+{9 \  {t^7}}+{3 \  {t^6}}+{{12} \  {t^5}} 
\right)}
\  {x^2}}+{6 \  {t^7} \  x}+{t^9} 
\end{array}
$$


\subsection{A third example}
)clear all

As a third example, we construct a difference operator algebra over
the ring of EXPR(INT) by using an automorphism S defined by a
``shift'' operation S:EXPR(INT) $->$ EXPR(INT)
$$
   s(e)(n) = e(n+1)
$$
and an S-derivation defined by DF:EXPR(INT) $->$ EXPR(INT) as
$$
   DF(e)(n) = e(n+1)-e(n)
$$
Define S to be a ``shift'' operator, which acts on expressions with 
the discrete variable $n$:

\spadcommand{S:EXPR(INT)->EXPR(INT):=e+->eval(e,[n],[n+1])}

Define DF to be a ``difference'' operator, which acts on expressions
with a discrete variable $n$:

\spadcommand{DF:EXPR(INT)->EXPR(INT):=e+->eval(e,[n],[n+1])-e}

Then define the difference operator algebra D0:

\spadcommand{D0:=OREUP('D,EXPR(INT),morphism S,DF)}

\spadcommand{u:=(operator 'u)[n]}
$$
u 
\left(
{n} 
\right)
$$

\spadcommand{L:D0:='D+u}
$$
D+{u 
\left(
{n} 
\right)}
$$

\spadcommand{L**2}
$$
{D^2}+{2 \  {u 
\left(
{n} 
\right)}
\  D}+{{u 
\left(
{n} 
\right)}^2}
$$

\subsection{A fourth example}
)clear all

As a fourth example, we construct a skew polynomial ring by using an
inner derivation $\delta$ induced by a fixed $y$ in R:
$$
   \delta(r) = yr - ry
$$
First we should expose the constructor SquareMatrix so it is visible
in the interpreter:
\begin{verbatim}
)set expose add constructor SquareMatrix
\end{verbatim}

Define R to be the square matrix with integer entries:

\spadcommand{R:=SQMATRIX(2,INT)}
$$
SquareMatrix(2,Integer) 
$$

\spadcommand{y:R:=matrix [ [1,1],[0,1] ]}
$$
\left[
\begin{array}{cc}
1 & 1 \\ 
0 & 1 
\end{array}
\right]
$$

Define the inner derivative $\delta$:

\spadcommand{delta:R->R:=r+->y*r-r*y}

Define S to be a skew polynomial determined by $\sigma = 1$
and $\delta$ as an inner derivative:

\spadcommand{S:=OREUP('x,R,1,delta)}

\spadcommand{x:S:='x}
$$
x 
$$

\spadcommand{a:S:=matrix [ [2,3],[1,1] ]}
$$
\left[
\begin{array}{cc}
2 & 3 \\ 
1 & 1 
\end{array}
\right]
$$

\spadcommand{x**2*a}
$$
{{\left[ 
\begin{array}{cc}
2 & 3 \\ 
1 & 1 
\end{array}
\right]}
\  {x^2}}+{{\left[ 
\begin{array}{cc}
2 & -2 \\ 
0 & -2 
\end{array}
\right]}
\  x}+{\left[ 
\begin{array}{cc}
0 & -2 \\ 
0 & 0 
\end{array}
\right]}
$$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{UniversalSegment}

The {\tt UniversalSegment} domain generalizes {\tt Segment}
by allowing segments without a ``hi'' end point.

\spadcommand{pints := 1..}
$$
1.. 
$$
\returnType{Type: UniversalSegment PositiveInteger}

\spadcommand{nevens := (0..) by -2 }
$$
{0..} \mbox{\rm\ by\ } -2 
$$
\returnType{Type: UniversalSegment NonNegativeInteger}

Values of type {\tt Segment} are automatically converted to
type {\tt UniversalSegment} when appropriate.

\spadcommand{useg: UniversalSegment(Integer) := 3..10 }
$$
3..{10} 
$$
\returnType{Type: UniversalSegment Integer}

The operation \spadfunFrom{hasHi}{UniversalSegment} is used to test
whether a segment has a {\tt hi} end point.

\spadcommand{hasHi pints  }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

\spadcommand{hasHi nevens }
$$
{\tt false} 
$$
\returnType{Type: Boolean}

%Original Page 478

\spadcommand{hasHi useg   }
$$
{\tt true} 
$$
\returnType{Type: Boolean}

All operations available on type {\tt Segment} apply to {\tt
UniversalSegment}, with the proviso that expansions produce streams
rather than lists.  This is to accommodate infinite expansions.

\spadcommand{expand pints }
$$
\left[
1, 2, 3, 4, 5, 6, 7, 8, 9, {10}, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

\spadcommand{expand nevens }
$$
\left[
0, -2, -4, -6, -8, -{10}, -{12}, -{14}, -{16}, 
-{18}, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

\spadcommand{expand [1, 3, 10..15, 100..]}
$$
\left[
1, 3, {10}, {11}, {12}, {13}, {14}, {15}, {100}, 
{101}, \ldots 
\right]
$$
\returnType{Type: Stream Integer}

For more information on related topics, see 
\domainref{Segment}, \domainref{SegmentBinding}, \domainref{List}, and
\domainref{Stream}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Vector}

The {\tt Vector} domain is used for storing data in a one-dimensional
indexed data structure.  A vector is a homogeneous data structure in
that all the components of the vector must belong to the same Axiom
domain.  Each vector has a fixed length specified by the user; vectors
are not extensible.  This domain is similar to the 
{\tt OneDimensionalArray} domain, except that when the components of a 
{\tt Vector} belong to a {\tt Ring}, arithmetic operations are provided.
For more examples of operations that are defined for both {\tt Vector}
and {\tt OneDimensionalArray}, see \domainref{OneDimensionalArray}.

As with the {\tt OneDimensionalArray} domain, a {\tt Vector} can
be created by calling the operation \spadfunFrom{new}{Vector}, its components
can be accessed by calling the operations \spadfunFrom{elt}{Vector} and
\spadfunFrom{qelt}{Vector}, and its components can be reset by calling the
operations \spadfunFrom{setelt}{Vector} and
\spadfunFrom{qsetelt}{Vector}.

This creates a vector of integers of length {\tt 5} all of whose
components are {\tt 12}.

\spadcommand{u : VECTOR INT := new(5,12) }
$$
\left[
{12}, {12}, {12}, {12}, {12} 
\right]
$$
\returnType{Type: Vector Integer}

%Original Page 479

This is how you create a vector from a list of its components.

\spadcommand{v : VECTOR INT := vector([1,2,3,4,5]) }
$$
\left[
1, 2, 3, 4, 5 
\right]
$$
\returnType{Type: Vector Integer}

Indexing for vectors begins at {\tt 1}.  The last element has index
equal to the length of the vector, which is computed by
\spadopFrom{\#}{Vector}.

\spadcommand{\#(v) }
$$
5 
$$
\returnType{Type: PositiveInteger}

This is the standard way to use \spadfunFrom{elt}{Vector} to extract
an element.  Functionally, it is the same as if you had typed {\tt
elt(v,2)}.

\spadcommand{v.2 }
$$
2 
$$
\returnType{Type: PositiveInteger}

This is the standard way to use \spadfunFrom{setelt}{Vector} to change
an element.  It is the same as if you had typed {\tt setelt(v,3,99)}.

\spadcommand{v.3 := 99 }
$$
99 
$$
\returnType{Type: PositiveInteger}

Now look at {\tt v} to see the change.  You can use
\spadfunFrom{qelt}{Vector} and \spadfunFrom{qsetelt}{Vector} (instead
of \spadfunFrom{elt}{Vector} and \spadfunFrom{setelt}{Vector},
respectively) but {\it only} when you know that the index is within
the valid range.

\spadcommand{v }
$$
\left[
1, 2, {99}, 4, 5 
\right]
$$
\returnType{Type: Vector Integer}

When the components belong to a {\tt Ring}, Axiom provides arithmetic
operations for {\tt Vector}.  These include left and right scalar
multiplication.

\spadcommand{5 * v }
$$
\left[
5, {10}, {495}, {20}, {25} 
\right]
$$
\returnType{Type: Vector Integer}

\spadcommand{v * 7 }
$$
\left[
7, {14}, {693}, {28}, {35} 
\right]
$$
\returnType{Type: Vector Integer}

\spadcommand{w : VECTOR INT := vector([2,3,4,5,6]) }
$$
\left[
2, 3, 4, 5, 6 
\right]
$$
\returnType{Type: Vector Integer}

Addition and subtraction are also available.

\spadcommand{v + w }
$$
\left[
3, 5, {103}, 9, {11} 
\right]
$$
\returnType{Type: Vector Integer}

Of course, when adding or subtracting, the two vectors must have the same
length or an error message is displayed.

\spadcommand{v - w }
$$
\left[
-1, -1, {95}, -1, -1 
\right]
$$
\returnType{Type: Vector Integer}

For more information about other aggregate domains, see the following:
\domainref{List}, \domainref{Matrix}, \domainref{OneDimensionalArray},
\domainref{Set}, \domainref{Table}, and \domainref{TwoDimensionalArray}.
Issue the system command {\tt )show Vector} to display the full list of
operations defined by {\tt Vector}.

%Original Page 480

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{Void}

When an expression is not in a value context, it is given type 
{\tt Void}.  For example, in the expression 
\begin{verbatim} 
  r := (a; b; if c then d else e; f) 
\end{verbatim} 
values are used only from the
subexpressions {\tt c} and {\tt f}: all others are thrown away.  The
subexpressions {\tt a}, {\tt b}, {\tt d} and {\tt e} are evaluated for
side-effects only and have type {\tt Void}.  There is a unique value
of type {\tt Void}.

You will most often see results of type {\tt Void} when you
declare a variable.

\spadcommand{a : Integer}
\returnType{Type: Void}

Usually no output is displayed for {\tt Void} results.
You can force the display of a rather ugly object by issuing
{\tt )set message void on}.

\spadcommand{)set message void on}

\spadcommand{b : Fraction Integer}
$$
\mbox{\tt "()"} 
$$
\returnType{Type: Void}

\spadcommand{)set message void off}

All values can be converted to type {\tt Void}.

\spadcommand{3::Void }
\returnType{Type: Void}

Once a value has been converted to {\tt Void}, it cannot be recovered.

\spadcommand{\% :: PositiveInteger }
\begin{verbatim}
Cannot convert from type Void to PositiveInteger for value "()"
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{WuWenTsunTriangularSet}

The {\tt WuWenTsunTriangularSet} domain constructor implements the
characteristic set method of Wu Wen Tsun.  This algorithm computes a
list of triangular sets from a list of polynomials such that the
algebraic variety defined by the given list of polynomials decomposes
into the union of the regular-zero sets of the computed triangular
sets.  The constructor takes four arguments.  The first one, {\bf R},
is the coefficient ring of the polynomials; it must belong to the
category {\tt IntegralDomain}.  The second one, {\bf E}, is the
exponent monoid of the polynomials; it must belong to the category
{\tt OrderedAbelianMonoidSup}.  The third one, {\bf V}, is the ordered
set of variables; it must belong to the category {\tt OrderedSet}.
The last one is the polynomial ring; it must belong to the category
{\tt RecursivePolynomialCategory(R,E,V)}.  The abbreviation for 
{\tt WuWenTsunTriangularSet} is {\tt WUTSET}.

Let us illustrate the facilities by an example.

Define the coefficient ring.

\spadcommand{R := Integer }
$$
Integer 
$$
\returnType{Type: Domain}

Define the list of variables,

\spadcommand{ls : List Symbol := [x,y,z,t] }
$$
\left[
x, y, z, t 
\right]
$$
\returnType{Type: List Symbol}

and make it an ordered set;

\spadcommand{V := OVAR(ls)}
$$
\mbox{\rm OrderedVariableList [x,y,z,t]} 
$$
\returnType{Type: Domain}

then define the exponent monoid.

\spadcommand{E := IndexedExponents V}
$$
\mbox{\rm IndexedExponents OrderedVariableList [x,y,z,t]} 
$$
\returnType{Type: Domain}

Define the polynomial ring.

\spadcommand{P := NSMP(R, V)}
$$
\mbox{\rm NewSparseMultivariatePolynomial(Integer,OrderedVariableList 
[x,y,z,t])} 
$$
\returnType{Type: Domain}

Let the variables be polynomial.

\spadcommand{x: P := 'x}
$$
x 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{y: P := 'y}
$$
y 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{z: P := 'z}
$$
z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{t: P := 't}
$$
t 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

Now call the {\tt WuWenTsunTriangularSet} domain constructor.

\spadcommand{T := WUTSET(R,E,V,P)}
$$
\begin{array}{@{}l}
{\rm WuWenTsunTriangularSet(Integer,}
\\
\displaystyle
{\rm \ \ IndexedExponents OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t],}
\\
\displaystyle
{\rm \ \ NewSparseMultivariatePolynomial(Integer,}
\\
\displaystyle
{\rm \ \ OrderedVariableList [x,y,z,t]))} 
\end{array}
$$
\returnType{Type: Domain}

Define a polynomial system.

\spadcommand{p1 := x ** 31 - x ** 6 - x - y}
$$
{x \sp {31}} -{x \sp 6} -x -y 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{p2 := x ** 8  - z}
$$
{x \sp 8} -z 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{p3 := x ** 10 - t}
$$
{x \sp {10}} -t 
$$
\returnType{Type: 
NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

\spadcommand{lp := [p1, p2, p3]}
$$
\left[
{{x \sp {31}} -{x \sp 6} -x -y}, {{x \sp 8} -z}, {{x \sp {10}} -t} 
\right]
$$
\returnType{Type: 
List NewSparseMultivariatePolynomial(Integer,OrderedVariableList [x,y,z,t])}

Compute a characteristic set of the system.

\spadcommand{characteristicSet(lp)\$T}
$$
\begin{array}{@{}l}
\left\{
{{z \sp 5} -{t \sp 4}}, 
\right.
\\
\\
\displaystyle
{{{t \sp 4} \  {z \sp 2} \  {y \sp 2}}+
{2 \  {t \sp 3} \  {z \sp 4} \  y}+
{{\left( -{t \sp 7}+{2 \  {t \sp 4}} -t \right)}\  {z \sp 6}}+
{{t \sp 6} \  z}}, 
\\
\\
\displaystyle
\left.
\left( 
{t \sp 3} -1 
\right)\  {z \sp 3} \  x -
{{z \sp 3} \  y} -
{t \sp 3} 
\right\}
\end{array}
$$
\returnType{Type: 
Union(
WuWenTsunTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t])),...)}

Solve the system.

\spadcommand{zeroSetSplit(lp)\$T}
$$
\begin{array}{@{}l}
\left[
{\left\{ t, z, y, x \right\}},
{\left\{ 
{{t \sp 3} -1}, 
{{z \sp 5} -{t \sp 4}}, 
{{{z \sp 3} \  y}+{t \sp 3}}, 
{{z \  {x \sp 2}} -t} 
\right\}},
\right.
\\
\\
\displaystyle
\left\{ 
{{z \sp 5} -{t \sp 4}}, 
{{t \sp 4} \  {z \sp 2} \  {y \sp 2}}+
{2 \  {t \sp 3} \  {z \sp 4} \  y}+
\left( 
-{t \sp 7}+{2 \  {t \sp 4}} -t 
\right)\  {z \sp 6}+
{{t \sp 6} \  z}, 
\right.
\\
\\
\displaystyle
\left.
\left.
\left( 
{t \sp 3} -1 \right)\  {z \sp 3} \  x -
{{z \sp 3} \  y} -{t \sp 3} 
\right\}
\right]
\end{array}
$$
\returnType{Type: 
List WuWenTsunTriangularSet(Integer,
IndexedExponents OrderedVariableList [x,y,z,t],
OrderedVariableList [x,y,z,t],
NewSparseMultivariatePolynomial(Integer,
OrderedVariableList [x,y,z,t]))}

The {\tt RegularTriangularSet} and {\tt SquareFreeRegularTriangularSet}\\ 
domain constructors, the {\tt LazardSetSolvingPackage} package\\ constructors as well as, {\tt SquareFreeRegularTriangularSet} and\\
{\tt ZeroDimensionalSolvePackage} package constructors also provide\\
operations to compute triangular decompositions of algebraic varieties.  

These five constructor use a special kind of
characteristic sets, called regular triangular sets.  These special
characteristic sets have better properties than the general ones.
Regular triangular sets and their related concepts are presented in
the paper ``On the Theories of Triangular sets'' By P. Aubry, D. Lazard
and M. Moreno Maza (to appear in the Journal of Symbolic Computation).
The decomposition algorithm (due to the third author) available in the
four above constructors provide generally better timings than the
characteristic set method.  In fact, the {\tt WUTSET} constructor
remains interesting for the purpose of manipulating characteristic
sets whereas the other constructors are more convenient for solving
polynomial systems.

Note that the way of understanding triangular decompositions 
is detailed in the example of the {\tt RegularTriangularSet}
constructor.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{XPBWPolynomial}

Initialisations

\spadcommand{a:Symbol := 'a }
$$
a 
$$
\returnType{Type: Symbol}

\spadcommand{b:Symbol := 'b }
$$
b 
$$
\returnType{Type: Symbol}

\spadcommand{RN := Fraction(Integer) }
$$
\mbox{\rm Fraction Integer} 
$$
\returnType{Type: Domain}

\spadcommand{word   := OrderedFreeMonoid Symbol }
$$
\mbox{\rm OrderedFreeMonoid Symbol} 
$$
\returnType{Type: Domain}

\spadcommand{lword := LyndonWord(Symbol) }
$$
\mbox{\rm LyndonWord Symbol} 
$$
\returnType{Type: Domain}

\spadcommand{base  := PoincareBirkhoffWittLyndonBasis Symbol }
$$
\mbox{\rm PoincareBirkhoffWittLyndonBasis Symbol} 
$$
\returnType{Type: Domain}

\spadcommand{dpoly := XDistributedPolynomial(Symbol, RN)  }
$$
\mbox{\rm XDistributedPolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{rpoly := XRecursivePolynomial(Symbol, RN)  }
$$
\mbox{\rm XRecursivePolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{lpoly := LiePolynomial(Symbol, RN)  }
$$
\mbox{\rm LiePolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{poly  := XPBWPolynomial(Symbol, RN)  }
$$
\mbox{\rm XPBWPolynomial(Symbol,Fraction Integer)} 
$$
\returnType{Type: Domain}

\spadcommand{liste : List lword := LyndonWordsList([a,b], 6)  }
$$
\begin{array}{@{}l}
\left[
{\left[ a \right]},
{\left[ b \right]},
{\left[ a \  b \right]},
{\left[ {a \sp 2} \  b \right]},
{\left[ a \  {b \sp 2} \right]},
{\left[ {a \sp 3} \  b \right]},
{\left[ {a \sp 2} \  {b \sp 2} \right]},
{\left[ a \  {b \sp 3} \right]},
{\left[ {a \sp 4} \  b \right]},
\right.
\\
\\
\displaystyle
{\left[ {a \sp 3} \  {b \sp 2} \right]},
{\left[ {a \sp 2} \  b \  a \  b \right]},
{\left[ {a \sp 2} \  {b \sp 3} \right]},
{\left[ a \  b \  a \  {b \sp 2} \right]},
{\left[ a \  {b \sp 4} \right]},
{\left[ {a \sp 5} \  b \right]},
{\left[ {a \sp 4} \  {b \sp 2} \right]},
\\
\\
\displaystyle
\left.
{\left[ {a \sp 3} \  b \  a \  b \right]},
{\left[ {a \sp 3} \  {b \sp 3} \right]},
{\left[ {a \sp 2} \  b \  a \  {b \sp 2} \right]},
{\left[ {a \sp 2} \  {b \sp 2} \  a \  b \right]},
{\left[ {a \sp 2} \  {b \sp 4} \right]},
{\left[ a \  b \  a \  {b \sp 3} \right]},
{\left[ a \  {b \sp 5} \right]}
\right]
\end{array}
$$
\returnType{Type: List LyndonWord Symbol}

Let's make some polynomials

\spadcommand{0\$poly }
$$
0 
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{1\$poly }
$$
1 
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{p : poly := a  }
$$
\left[
a 
\right]
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{q : poly := b  }
$$
\left[
b 
\right]
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{pq: poly := p*q  }
$$
{\left[ a \  b 
\right]}+{{\left[
b 
\right]}
\  {\left[ a 
\right]}}
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

Coerce to distributed polynomial

\spadcommand{pq :: dpoly }
$$
a \  b 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Fraction Integer)}

Check some polynomial operations

\spadcommand{mirror pq }
$$
{\left[ b 
\right]}
\  {\left[ a 
\right]}
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{listOfTerms pq }
$$
\left[
{\left[ {k={{\left[ b 
\right]}
\  {\left[ a 
\right]}}},
{c=1} 
\right]},
{\left[ {k={\left[ a \  b 
\right]}},
{c=1} 
\right]}
\right]
$$
\returnType{Type: 
List Record(k: PoincareBirkhoffWittLyndonBasis Symbol,c: Fraction Integer)}

\spadcommand{reductum pq }
$$
\left[
a \  b 
\right]
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{leadingMonomial pq }
$$
{\left[ b 
\right]}
\  {\left[ a 
\right]}
$$
\returnType{Type: PoincareBirkhoffWittLyndonBasis Symbol}

\spadcommand{coefficients pq }
$$
\left[
1, 1 
\right]
$$
\returnType{Type: List Fraction Integer}

\spadcommand{leadingTerm pq }
$$
\left[
{k={{\left[ b 
\right]}
\  {\left[ a 
\right]}}},
{c=1} 
\right]
$$
\returnType{Type: 
Record(k: PoincareBirkhoffWittLyndonBasis Symbol,c: Fraction Integer)}

\spadcommand{degree pq }
$$
2 
$$
\returnType{Type: PositiveInteger}

\spadcommand{pq4:=exp(pq,4)  }
$$
\begin{array}{@{}l}
1+
{\left[ a \  b \right]}+
{{\left[b \right]}\  
{\left[ a \right]}}+
{{\frac{1}{2}} \  {\left[ a \  b \right]}\  
{\left[ a \  b \right]}}+
{{\frac{1}{2}} \  {\left[ a \  {b \sp 2} \right]}\  
{\left[ a \right]}}+
{{\frac{1}{2}} \  {\left[ b \right]}\  
{\left[ {a \sp 2} \  b \right]}}+
\\
\\
\displaystyle
{{\frac{3}{2}} \  {\left[ b \right]}\  
{\left[ a \  b \right]}\  
{\left[ a \right]}}+
{{\frac{1}{2}} \  {\left[ b \right]}\  
{\left[ b \right]}\  
{\left[ a \right]}\  
{\left[ a \right]}}
\end{array}
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{log(pq4,4) - pq  }
$$
0 
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

Calculations with verification in {\tt XDistributedPolynomial}.

\spadcommand{lp1 :lpoly := LiePoly liste.10  }
$$
\left[
{a \sp 3} \  {b \sp 2} 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{lp2 :lpoly := LiePoly liste.11  }
$$
\left[
{a \sp 2} \  b \  a \  b 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{lp  :lpoly := [lp1, lp2]  }
$$
\left[
{a \sp 3} \  {b \sp 2} \  {a \sp 2} \  b \  a \  b 
\right]
$$
\returnType{Type: LiePolynomial(Symbol,Fraction Integer)}

\spadcommand{lpd1: dpoly := lp1  }
$$
{{a \sp 3} \  {b \sp 2}} -{2 \  {a \sp 2} \  b \  a \  b} -{{a \sp 2} \  {b 
\sp 2} \  a}+{4 \  a \  b \  a \  b \  a} -{a \  {b \sp 2} \  {a \sp 2}} -{2 
\  b \  a \  b \  {a \sp 2}}+{{b \sp 2} \  {a \sp 3}} 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Fraction Integer)}

\spadcommand{lpd2: dpoly := lp2  }
$$
\begin{array}{@{}l}
{{a \sp 2} \  b \  a \  b} -
{{a \sp 2} \  {b \sp 2} \  a} -
{3 \  a \  b \  {a \sp 2} \  b}+
{4 \  a \  b \  a \  b \  a} -
\\
\\
\displaystyle
{a \  {b \sp 2} \  {a \sp 2}}+
{2 \  b \  {a \sp 3} \  b} -
{3 \  b \  {a \sp 2} \  b \  a}+
{b \  a \  b \  {a \sp 2}} 
\end{array}
$$
\returnType{Type: XDistributedPolynomial(Symbol,Fraction Integer)}

\spadcommand{lpd : dpoly := lpd1 * lpd2 - lpd2 * lpd1  }
$$
\begin{array}{@{}l}
{{a \sp 3} \  {b \sp 2} \  {a \sp 2} \  b \  a \  b} -
{{a \sp 3} \  {b \sp 2} \  {a \sp 2} \  {b \sp 2} \  a} -
{3 \  {a \sp 3} \  {b \sp 2} \  a \  b \  {a \sp 2} \  b}+
{4 \  {a \sp 3} \  {b \sp 2} \  a \  b \  a \  b \  a} -
\\
\displaystyle
{{a \sp 3} \  {b \sp 2} \  a \  {b \sp 2} \  {a \sp 2}}+
{2 \  {a \sp 3} \  {b \sp 3} \  {a \sp 3} \  b} -
{3 \  {a \sp 3} \  {b \sp 3} \  {a \sp 2} \  b \  a}+
{{a \sp 3} \  {b \sp 3} \  a \  b \  {a \sp 2}} -
\\
\displaystyle
{{a \sp 2} \  b \  a \  b \  {a \sp 3} \  {b \sp 2}}+
{3 \  {a \sp 2} \  b \  a \  b \  {a \sp 2} \  {b \sp 2} \  a}+
{6 \  {a \sp 2} \  b \  a \  b \  a \  b \  {a \sp 2} \  b} -
{{12} \  {a \sp 2} \  b \  a \  b \  a \  b \  a \  b \  a}+
\\
\displaystyle
{3 \  {a \sp 2} \  b \  a \  b \  a \  {b \sp 2} \  {a \sp 2}} -
{4 \  {a \sp 2} \  b \  a \  {b \sp 2} \  {a \sp 3} \  b}+
{6 \  {a \sp 2} \  b \  a \  {b \sp 2} \  {a \sp 2} \  b \  a} -
{{a \sp 2} \  b \  a \  {b \sp 3} \  {a \sp 3}}+
\\
\displaystyle
{{a \sp 2} \  {b \sp 2} \  {a \sp 4} \  {b \sp 2}} -
{3 \  {a \sp 2} \  {b \sp 2} \  {a \sp 3} \  b \  a \  b}+
{3 \  {a \sp 2} \  {b \sp 2} \  {a \sp 2} \  b \  {a \sp 2} \  b} -
{2 \  {a \sp 2} \  {b \sp 2} \  a \  b \  {a \sp 3} \  b}+
\\
\displaystyle
{3 \  {a \sp 2} \  {b \sp 2} \  a \  b \  {a \sp 2} \  b \  a} -
{3 \  {a \sp 2} \  {b \sp 2} \  a \  b \  a \  b \  {a \sp 2}}+
{{a \sp 2} \  {b \sp 2} \  a \  {b \sp 2} \  {a \sp 3}}+
{3 \  a \  b \  {a \sp 2} \  b \  {a \sp 3} \  {b \sp 2}} -
\\
\displaystyle
{6 \  a \  b \  {a \sp 2} \  b \  {a \sp 2} \  b \  a \  b} -
{3 \  a \  b \  {a \sp 2} \  b \  {a \sp 2} \  {b \sp 2} \  a}+
{{12} \  a \  b \  {a \sp 2} \  b \  a \  b \  a \  b \  a} -
{3 \  a \  b \  {a \sp 2} \  b \  a \  {b \sp 2} \  {a \sp 2}} -
\\
\displaystyle
{6 \  a \  b \  {a \sp 2} \  {b \sp 2} \  a \  b \  {a \sp 2}}+
{3 \  a \  b \  {a \sp 2} \  {b \sp 3} \  {a \sp 3}} -
{4 \  a \  b \  a \  b \  {a \sp 4} \  {b \sp 2}}+
{{12} \  a \  b \  a \  b \  {a \sp 3} \  b \  a \  b} -
\\
\displaystyle
{{12} \  a \  b \  a \  b \  {a \sp 2} \  b \  {a \sp 2} \  b}+
{8 \  a \  b \  a \  b \  a \  b \  {a \sp 3} \  b} -
{{12} \  a \  b \  a \  b \  a \  b \  {a \sp 2} \  b \  a}+
\\
\displaystyle
{{12} \  a \  b \  a \  b \  a \  b \  a \  b \  {a \sp 2}} -
{4 \  a \  b \  a \  b \  a \  {b \sp 2} \  {a \sp 3}}+
{a \  {b \sp 2} \  {a \sp 5} \  {b \sp 2}} -
{3 \  a \  {b \sp 2} \  {a \sp 4} \  b \  a \  b}+
\\
\displaystyle
{3 \  a \  {b \sp 2} \  {a \sp 3} \  b \  {a \sp 2} \  b} -
{2 \  a \  {b \sp 2} \  {a \sp 2} \  b \  {a \sp 3} \  b}+
{3 \  a \  {b \sp 2} \  {a \sp 2} \  b \  {a \sp 2} \  b \  a} -
{3 \  a \  {b \sp 2} \  {a \sp 2} \  b \  a \  b \  {a \sp 2}}+
\\
\displaystyle
{a \  {b \sp 2} \  {a \sp 2} \  {b \sp 2} \  {a \sp 3}} -
{2 \  b \  {a \sp 3} \  b \  {a \sp 3} \  {b \sp 2}}+
{4 \  b \  {a \sp 3} \  b \  {a \sp 2} \  b \  a \  b}+
{2 \  b \  {a \sp 3} \  b \  {a \sp 2} \  {b \sp 2} \  a} -
\\
\displaystyle
{8 \  b \  {a \sp 3} \  b \  a \  b \  a \  b \  a}+
{2 \  b \  {a \sp 3} \  b \  a \  {b \sp 2} \  {a \sp 2}}+
{4 \  b \  {a \sp 3} \  {b \sp 2} \  a \  b \  {a \sp 2}} -
{2 \  b \  {a \sp 3} \  {b \sp 3} \  {a \sp 3}}+
\\
\displaystyle
{3 \  b \  {a \sp 2} \  b \  {a \sp 4} \  {b \sp 2}} -
{6 \  b \  {a \sp 2} \  b \  {a \sp 3} \  b \  a \  b} -
{3 \  b \  {a \sp 2} \  b \  {a \sp 3} \  {b \sp 2} \  a}+
{{12} \  b \  {a \sp 2} \  b \  {a \sp 2} \  b \  a \  b \  a} -
\\
\displaystyle
{3 \  b \  {a \sp 2} \  b \  {a \sp 2} \  {b \sp 2} \  {a \sp 2}} -
{6 \  b \  {a \sp 2} \  b \  a \  b \  a \  b \  {a \sp 2}}+
{3 \  b \  {a \sp 2} \  b \  a \  {b \sp 2} \  {a \sp 3}} -
{b \  a \  b \  {a \sp 5} \  {b \sp 2}}+
\\
\displaystyle
{3 \  b \  a \  b \  {a \sp 4} \  {b \sp 2} \  a}+
{6 \  b \  a \  b \  {a \sp 3} \  b \  {a \sp 2} \  b} -
{{12} \  b \  a \  b \  {a \sp 3} \  b \  a \  b \  a}+
{3 \  b \  a \  b \  {a \sp 3} \  {b \sp 2} \  {a \sp 2}} -
\\
\displaystyle
{4 \  b \  a \  b \  {a \sp 2} \  b \  {a \sp 3} \  b}+
{6 \  b \  a \  b \  {a \sp 2} \  b \  {a \sp 2} \  b \  a} -
{b \  a \  b \  {a \sp 2} \  {b \sp 2} \  {a \sp 3}}+
{{b \sp 2} \  {a \sp 5} \  b \  a \  b} -
\\
\displaystyle
{{b \sp 2} \  {a \sp 5} \  {b \sp 2} \  a} -
{3 \  {b \sp 2} \  {a \sp 4} \  b \  {a \sp 2} \  b}+
{4 \  {b \sp 2} \  {a \sp 4} \  b \  a \  b \  a} -
{{b \sp 2} \  {a \sp 4} \  {b \sp 2} \  {a \sp 2}}+
\\
\displaystyle
{2 \  {b \sp 2} \  {a \sp 3} \  b \  {a \sp 3} \  b} -
{3 \  {b \sp 2} \  {a \sp 3} \  b \  {a \sp 2} \  b \  a}+
{{b \sp 2} \  {a \sp 3} \  b \  a \  b \  {a \sp 2}} 
\end{array}
$$
\returnType{Type: XDistributedPolynomial(Symbol,Fraction Integer)}

\spadcommand{lp :: dpoly - lpd }
$$
0 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Fraction Integer)}

Calculations with verification in {\tt XRecursivePolynomial}.

\spadcommand{p := 3 * lp  }
$$
3 \  {\left[ {a \sp 3} \  {b \sp 2} \  {a \sp 2} \  b \  a \  b 
\right]}
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{q := lp1  }
$$
\left[
{a \sp 3} \  {b \sp 2} 
\right]
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{pq:= p * q  }
$$
3 \  
{\left[ {a \sp 3} \  {b \sp 2} \  {a \sp 2} \  b \  a \  b 
\right]}\  
{\left[ {a \sp 3} \  {b \sp 2} 
\right]}
$$
\returnType{Type: XPBWPolynomial(Symbol,Fraction Integer)}

\spadcommand{pr:rpoly := p :: rpoly  }
$$
\begin{array}{@{}l}
a \  
\left( a \  
\left( a \  b \  b \  
\left( a \  
\left( a \  b \  
\left( a \  b \  3+b \  a \  
\left( -3 
\right)
\right)+b\  
\right.
\right.
\right.
\right.
\\
\displaystyle
\left.
\left( a \  
\left( a \  b \  
\left( -9 
\right)+b\  a \  {12} 
\right)+b\  a \  a \  
\left( -3 
\right)
\right)
\right)+b\  a \  
\\
\displaystyle
\left.
\left( a \  
\left( a \  b \  6+b \  a \  
\left( -9 
\right)
\right)+b\  a \  a \  3
\right)
\right)+b\  
\left( a \  b \  
\left( a \  
\left( a \  
\right.
\right.
\right.
\\
\displaystyle
\left( a \  b \  b \  
\left( -3 
\right)+b\  b \  a \  9
\right)+b\  
\left( a \  
\left( a \  b \  {18}+b \  a \  
\left( -{36} 
\right)
\right)+b\  a \  a \  9
\right.
\\
\displaystyle
\left.
\left.
\right)
\right)+b\  
\left( a \  a \  
\left( a \  b \  
\left( -{12} 
\right)+b\  a \  {18}
\right)+b\  a \  a \  a \  
\left( -3 
\right)
\right)
\\
\displaystyle
\left.
\right)+b\  a \  
\left( a \  
\left( a \  
\left( a \  b \  b \  3+b \  a \  b \  
\left( -9 
\right)
\right)+b\  a \  a \  b \  9
\right)+b\  
\left( a \  
\right.
\right.
\\
\displaystyle
\left.
\left.
\left( a \  
\left( a \  b \  
\left( -6 
\right)+b\  a \  9
\right)+b\  a \  a \  
\left( -9 
\right)
\right)+b\  a \  a \  a \  3
\right)
\right)
\\
\displaystyle
\left.
\left.
\right)
\right)+b\  
\left( a \  
\left( a \  b \  
\left( a \  
\left( a \  
\left( a \  b \  b \  9+b \  
\left( a \  b \  
\left( -{18} 
\right)+b\  a \  
\right.
\right.
\right.
\right.
\right.
\right.
\\
\displaystyle
\left.
\left.
\left.
\left( -9 
\right)
\right)
\right)+b\  
\left( a \  b \  a \  {36}+b \  a \  a \  
\left( -9 
\right)
\right)
\right)+b\  
\left( a \  b \  a \  a \  
\right.
\\
\displaystyle
\left.
\left.
\left( -{18} 
\right)+b\  a \  a \  a \  9
\right)
\right)+b\  a \  
\left( a \  
\left( a \  
\left( a \  b \  b \  
\left( -{12} 
\right)+b\  a \  b \  {36}
\right)+b\  a \  a \  b \  
\right.
\right.
\\
\displaystyle
\left.
\left( -{36} 
\right)
\right)+b\  
\left( a \  
\left( a \  
\left( a \  b \  {24}+b \  a \  
\left( -{36} 
\right)
\right)+b\  a \  a \  {36}
\right)+b\  a \  a \  a \  
\right.
\\
\displaystyle
\left.
\left.
\left.
\left( -{12} 
\right)
\right)
\right)
\right)+b\  a \  a \  
\left( a \  
\left( a \  
\left( a \  b \  b \  3+b \  a \  b \  
\left( -9 
\right)
\right.
\right.
\right.
\\
\displaystyle
\left.
\left.
\right)+b\  a \  a \  b \  9
\right)+b\  
\left( a \  
\left( a \  
\left( a \  b \  
\left( -6 
\right)+b\  a \  9
\right)+b\  a \  a \  
\left( -9 
\right)
\right.
\right.
\\
\displaystyle
\left.
\left.
\left.
\left.
\left.
\right)+b\  a \  a \  a \  3
\right)
\right)
\right)
\right)+b\  
\left( a \  
\left( a \  
\left( a \  b \  
\left( a \  
\left( a \  
\right.
\right.
\right.
\right.
\right.
\\
\displaystyle
\left( a \  b \  b \  
\left( -6 
\right)+b\  
\left( a \  b \  {12}+b \  a \  6
\right)
\right)+b\  
\left( a \  b \  a \  
\left( -{24} 
\right)+b\  a \  a \  6
\right)
\\
\displaystyle
\left.
\left.
\right)+b\  
\left( a \  b \  a \  a \  {12}+b \  a \  a \  a \  
\left( -6 
\right)
\right)
\right)+b\  a \  
\left( a \  
\left( a \  
\left( a \  b \  b \  9+b \  
\left( a \  b \  
\left( -{18} 
\right.
\right.
\right.
\right.
\right.
\\
\displaystyle
\left.
\left.
\left.
\left.
\right)+b\  a \  
\left( -9 
\right)
\right)
\right)+b\  
\left( a \  b \  a \  {36}+b \  a \  a \  
\left( -9 
\right)
\right)
\right)+b\  
\left( a \  b \  a \  a \  
\right.
\\
\displaystyle
\left.
\left.
\left.
\left( -{18} 
\right)+b\  a \  a \  a \  9
\right)
\right)
\right)+b\  a \  a \  
\left( a \  
\left( a \  
\left( a \  b \  b \  
\left( -3 
\right)+b\  b \  a \  9
\right.
\right.
\right.
\\
\displaystyle
\left.
\left.
\right)+b\  
\left( a \  
\left( a \  b \  {18}+b \  a \  
\left( -{36} 
\right)
\right)+b\  a \  a \  9
\right)
\right)+b\  
\left( a \  a \  
\left( a \  b \  
\right.
\right.
\\
\displaystyle
\left.
\left.
\left.
\left.
\left( -{12} 
\right)+b\  a \  {18} 
\right)+b\  a \  a \  a \  
\left( -3 
\right)
\right)
\right)
\right)+b\  a \  a \  a \  
\left( a \  
\right.
\\
\displaystyle
\left( a \  b \  
\left( a \  b \  3+b \  a \  
\left( -3 
\right)
\right)+b\  
\left( a \  
\left( a \  b \  
\left( -9 
\right)+b\  a \  {12}
\right)+b\  a \  a \  
\right.
\right.
\\
\displaystyle
\left.
\left.
\left.
\left.
\left( -3 
\right)
\right)
\right)+b\  a \  
\left( a \  
\left( a \  b \  6+b \  a \  
\left( -9 
\right)
\right)+b\  a \  a \  3
\right)
\right)
\right)
\end{array}
$$
\returnType{Type: XRecursivePolynomial(Symbol,Fraction Integer)}

\spadcommand{qr:rpoly := q :: rpoly  }
$$
\begin{array}{@{}l}
a \  
\left( a \  
\left( a \  b \  b \  1+b \  
\left( a \  b \  
\left( -2 
\right)+b\  a \  
\left( -1 
\right)
\right)
\right)+
\right.
\\
\\
\displaystyle
\left.
b\  
\left( a \  b \  a \  4+b \  a \  a \  
\left( -1 
\right)
\right)
\right)+
\\
\\
\displaystyle
b\  
\left( a \  b \  a \  a \  
\left( -2 
\right)+b\  a \  a \  a \  1 
\right)
\end{array}
$$
\returnType{Type: XRecursivePolynomial(Symbol,Fraction Integer)}

\spadcommand{pq :: rpoly - pr*qr  }
$$
0 
$$
\returnType{Type: XRecursivePolynomial(Symbol,Fraction Integer)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{XPolynomial}

The {\tt XPolynomial} domain constructor implements multivariate
polynomials whose set of variables is {\tt Symbol}.  These variables
do not commute.  The only parameter of this construtor is the
coefficient ring which may be non-commutative.  However, coefficients
and variables commute.  The representation of the polynomials is
recursive.  The abbreviation for {\tt XPolynomial} is {\tt XPOLY}.

Constructors like {\tt XPolynomialRing}, {\tt XRecursivePolynomial}\\ 
as well as {\tt XDistributedPolynomial}, {\tt LiePolynomial} and\\ 
{\tt XPBWPolynomial} implement multivariate polynomials in\\ 
non-commutative variables.

We illustrate now some of the facilities of the 
{\tt XPOLY} domain constructor.

Define a polynomial ring over the integers.

\spadcommand{poly := XPolynomial(Integer) }
$$
\mbox{\rm XPolynomial Integer} 
$$
\returnType{Type: Domain}

Define a first polynomial,

\spadcommand{pr: poly := 2*x + 3*y-5   }
$$
-5+{x \  2}+{y \  3} 
$$
\returnType{Type: XPolynomial Integer}

and a second one.

\spadcommand{pr2: poly := pr*pr   }
$$
{25}+{x \  {\left( -{20}+{x \  4}+{y \  6} 
\right)}}+{y
\  {\left( -{30}+{x \  6}+{y \  9} 
\right)}}
$$
\returnType{Type: XPolynomial Integer}

Rewrite {\bf pr} in a distributive way,

\spadcommand{pd  := expand pr}
$$
-5+{2 \  x}+{3 \  y} 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Integer)}

compute its square,

\spadcommand{pd2 := pd*pd    }
$$
{25} -{{20} \  x} -{{30} \  y}+{4 \  {x \sp 2}}+{6 \  x \  y}+{6 \  y \  
x}+{9 \  {y \sp 2}} 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Integer)}

and checks that:

\spadcommand{expand(pr2) - pd2  }
$$
0 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Integer)}

We define:

\spadcommand{qr :=  pr**3  }
$$
\begin{array}{@{}l}
-{125}+{x \  
{\left( {150}+{x \  
{\left( -{60}+{x \  8}+{y \  {12}} 
\right)}}+{y\  
{\left( -{90}+{x \  {12}}+{y \  {18}} 
\right)}}
\right)}}+
\\
\\
\displaystyle
{y\  
{\left( {225}+{x \  
{\left( -{90}+{x \  {12}}+{y \  {18}} 
\right)}}+{y\  
{\left( -{135}+{x \  {18}}+{y \  {27}} 
\right)}}
\right)}}
\end{array}
$$
\returnType{Type: XPolynomial Integer}

and:

\spadcommand{qd :=  pd**3  }
$$
\begin{array}{@{}l}
-{125}+
{{150} \  x}+
{{225} \  y} -
{{60} \  {x \sp 2}} -
{{90} \  x \  y} -
{{90} \  y \  x} -
{{135} \  {y \sp 2}}+
{8 \  {x \sp 3}}+
{{12} \  {x \sp 2} \  y}+
\\
\\
\displaystyle
{{12} \  x \  y \  x}+
{{18} \  x \  {y \sp 2}}+
{{12} \  y \  {x \sp 2}}+
{{18} \  y \  x \  y}+
{{18} \  {y \sp 2} \  x}+
{{27} \  {y \sp 3}} 
\end{array}
$$
\returnType{Type: XDistributedPolynomial(Symbol,Integer)}

We truncate {\bf qd} at degree {\bf 3}:

\spadcommand{ trunc(qd,2) }
$$
-{125}+{{150} \  x}+{{225} \  y} -{{60} \  {x \sp 2}} -{{90} \  x \  y} 
-{{90} \  y \  x} -{{135} \  {y \sp 2}} 
$$
\returnType{Type: XDistributedPolynomial(Symbol,Integer)}

The same for {\bf qr}:

\spadcommand{trunc(qr,2) }
$$
-{125}+{x \  {\left( {150}+{x \  {\left( -{60} 
\right)}}+{y
\  {\left( -{90} 
\right)}}
\right)}}+{y
\  {\left( {225}+{x \  {\left( -{90} 
\right)}}+{y
\  {\left( -{135} 
\right)}}
\right)}}
$$
\returnType{Type: XPolynomial Integer}

We define:

\spadcommand{Word := OrderedFreeMonoid Symbol }
$$
\mbox{\rm OrderedFreeMonoid Symbol} 
$$
\returnType{Type: Domain}

and:

\spadcommand{w: Word := x*y**2  }
$$
x \  {y \sp 2} 
$$
\returnType{Type: OrderedFreeMonoid Symbol}

We can compute the right-quotient of {\bf qr} by {\bf r}:

\spadcommand{rquo(qr,w)  }
$$
18 
$$
\returnType{Type: XPolynomial Integer}

and the shuffle-product of {\bf pr} by {\bf r}:

\spadcommand{sh(pr,w::poly)  }
$$
{x \  {\left( {x \  y \  y \  4}+{y \  {\left( {x \  y \  2}+{y \  {\left( 
-5+{x \  2}+{y \  9} 
\right)}}
\right)}}
\right)}}+{y
\  x \  y \  y \  3} 
$$
\returnType{Type: XPolynomial Integer}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{XPolynomialRing}

The {\tt XPolynomialRing} domain constructor implements generalized
polynomials with coefficients from an arbitrary {\tt Ring} (not
necessarily commutative) and whose exponents are words from an
arbitrary {\tt OrderedMonoid} (not necessarily commutative too).  Thus
these polynomials are (finite) linear combinations of words.

This constructor takes two arguments.  The first one is a {\tt Ring}
and the second is an {\tt OrderedMonoid}.  The abbreviation for 
{\tt XPolynomialRing} is {\tt XPR}.

Other constructors like {\tt XPolynomial}, {\tt XRecursivePolynomial}\\
{\tt XDistributedPolynomial}, {\tt LiePolynomial} and\\ 
{\tt XPBWPolynomial} implement multivariate polynomials in\\ 
non-commutative variables.

We illustrate now some of the facilities of the {\tt XPR} domain constructor.

Define the free ordered monoid generated by the symbols.

\spadcommand{Word := OrderedFreeMonoid(Symbol) }
$$
\mbox{\rm OrderedFreeMonoid Symbol} 
$$
\returnType{Type: Domain}

Define the linear combinations of these words with integer coefficients.

\spadcommand{poly:= XPR(Integer,Word)  }
$$
\mbox{\rm XPolynomialRing(Integer,OrderedFreeMonoid Symbol)} 
$$
\returnType{Type: Domain}

Then we define a first element from {\bf poly}.

\spadcommand{p:poly := 2 * x - 3 * y + 1  }
$$
1+{2 \  x} -{3 \  y} 
$$
\returnType{Type: XPolynomialRing(Integer,OrderedFreeMonoid Symbol)}

And a second one.

\spadcommand{q:poly := 2 * x + 1  }
$$
1+{2 \  x} 
$$
\returnType{Type: XPolynomialRing(Integer,OrderedFreeMonoid Symbol)}

We compute their sum,

\spadcommand{p + q}
$$
2+{4 \  x} -{3 \  y} 
$$
\returnType{Type: XPolynomialRing(Integer,OrderedFreeMonoid Symbol)}

their product,

\spadcommand{p * q}
$$
1+{4 \  x} -{3 \  y}+{4 \  {x \sp 2}} -{6 \  y \  x} 
$$
\returnType{Type: XPolynomialRing(Integer,OrderedFreeMonoid Symbol)}

and see that variables do not commute.

\spadcommand{(p+q)**2-p**2-q**2-2*p*q}
$$
-{6 \  x \  y}+{6 \  y \  x} 
$$
\returnType{Type: XPolynomialRing(Integer,OrderedFreeMonoid Symbol)}

Now we define a ring of square matrices,

\spadcommand{M := SquareMatrix(2,Fraction Integer)  }
$$
\mbox{\rm SquareMatrix(2,Fraction Integer)} 
$$
\returnType{Type: Domain}

and the linear combinations of words with these  matrices as coefficients.

\spadcommand{poly1:= XPR(M,Word)   }
$$
\begin{array}{@{}l}
{\rm XPolynomialRing(SquareMatrix(2,Fraction Integer),}
\\
\displaystyle
{\rm \ \ OrderedFreeMonoid Symbol)} 
\end{array}
$$
\returnType{Type: Domain}

Define a first matrix,

\spadcommand{m1:M := matrix [ [i*j**2 for i in 1..2] for j in 1..2]  }
$$
\left[
\begin{array}{cc}
1 & 2 \\ 
4 & 8 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Fraction Integer)}

a second one,

\spadcommand{m2:M := m1 - 5/4   }
$$
\left[
\begin{array}{cc}
-{\frac{1}{4}} & 2 \\ 
4 & {\frac{27}{4}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Fraction Integer)}

and a third one.

\spadcommand{m3: M := m2**2   }
$$
\left[
\begin{array}{cc}
{\frac{129}{16}} & {13} \\ 
{26} & {\frac{857}{16}} 
\end{array}
\right]
$$
\returnType{Type: SquareMatrix(2,Fraction Integer)}

Define a polynomial,

\spadcommand{pm:poly1   := m1*x + m2*y + m3*z - 2/3     }
$$
{\left[ 
\begin{array}{cc}
-{\frac{2}{3}} & 0 \\ 
0 & -{\frac{2}{3}} 
\end{array}
\right]}+{{\left[
\begin{array}{cc}
1 & 2 \\ 
4 & 8 
\end{array}
\right]}
\  x}+{{\left[ 
\begin{array}{cc}
-{\frac{1}{4}} & 2 \\ 
4 & {\frac{27}{4}} 
\end{array}
\right]}
\  y}+{{\left[ 
\begin{array}{cc}
{\frac{129}{16}} & {13} \\ 
{26} & {\frac{857}{16}} 
\end{array}
\right]}
\  z} 
$$
\returnType{Type: 
XPolynomialRing(
SquareMatrix(2,Fraction Integer),
OrderedFreeMonoid Symbol)}

a second one,

\spadcommand{qm:poly1 := pm - m1*x   }
$$
{\left[ 
\begin{array}{cc}
-{\frac{2}{3}} & 0 \\ 
0 & -{\frac{2}{3}} 
\end{array}
\right]}+{{\left[
\begin{array}{cc}
-{\frac{1}{4}} & 2 \\ 
4 & {\frac{27}{4}} 
\end{array}
\right]}
\  y}+{{\left[ 
\begin{array}{cc}
{\frac{129}{16}} & {13} \\ 
{26} & {\frac{857}{16}} 
\end{array}
\right]}
\  z} 
$$
\returnType{Type: 
XPolynomialRing(
SquareMatrix(2,Fraction Integer),
OrderedFreeMonoid Symbol)}

and the following power.

\spadcommand{qm**3 }
$$
\begin{array}{@{}l}
{\left[ 
\begin{array}{cc}
-{\frac{8}{27}} & 0 \\ 
0 & -{\frac{8}{27}} 
\end{array}
\right]}+
{{\left[
\begin{array}{cc}
-{\frac{1}{3}} & {\frac{8}{3}} \\ 
{\frac{16}{3}} & 9 
\end{array}
\right]}\  y}+
{{\left[ 
\begin{array}{cc}
{\frac{43}{4}} & {\frac{52}{3}} \\ 
{\frac{104}{3}} & {\frac{857}{12}} 
\end{array}
\right]}\  z}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{cc}
-{\frac{129}{8}} & -{26} \\ 
-{52} & -{\frac{857}{8}} 
\end{array}
\right]}\  {y \sp 2}}+
{{\left[ 
\begin{array}{cc}
-{\frac{3199}{32}} & -{\frac{831}{4}} \\ 
-{\frac{831}{2}} & -{\frac{26467}{32}} 
\end{array}
\right]}\  y \  z}+
{{\left[ 
\begin{array}{cc}
-{\frac{3199}{32}} & -{\frac{831}{4}} \\ 
-{\frac{831}{2}} & -{\frac{26467}{32}} 
\end{array}
\right]}\  z \  y}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{cc}
-{\frac{103169}{128}} & -{\frac{6409}{4}} \\ 
-{\frac{6409}{2}} & -{\frac{820977}{128}} 
\end{array}
\right]}\  {z \sp 2}}+
{{\left[ 
\begin{array}{cc}
{\frac{3199}{64}} & {\frac{831}{8}} \\ 
{\frac{831}{4}} & {\frac{26467}{64}} 
\end{array}
\right]}\  {y \sp 3}}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{cc}
{\frac{103169}{256}} & {\frac{6409}{8}} \\ 
{\frac{6409}{4}} & {\frac{820977}{256}} 
\end{array}
\right]}\  {y \sp 2} \  z}+
{{\left[ 
\begin{array}{cc}
{\frac{103169}{256}} & {\frac{6409}{8}} \\ 
{\frac{6409}{4}} & {\frac{820977}{256}} 
\end{array}
\right]}\  y \  z \  y}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{cc}
{\frac{3178239}{1024}} & {\frac{795341}{128}} \\ 
{\frac{795341}{64}} & {\frac{25447787}{1024}} 
\end{array}
\right]}\  y \  {z \sp 2}}+
{{\left[ 
\begin{array}{cc}
{\frac{103169}{256}} & {\frac{6409}{8}} \\ 
{\frac{6409}{4}} & {\frac{820977}{256}} 
\end{array}
\right]}\  z \  {y \sp 2}}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{cc}
{\frac{3178239}{1024}} & {\frac{795341}{128}} \\ 
{\frac{795341}{64}} & {\frac{25447787}{1024}} 
\end{array}
\right]}\  z \  y \  z}+
{{\left[ 
\begin{array}{cc}
{\frac{3178239}{1024}} & {\frac{795341}{128}} \\ 
{\frac{795341}{64}} & {\frac{25447787}{1024}} 
\end{array}
\right]}\  {z \sp 2} \  y}+
\\
\\
\displaystyle
{{\left[ 
\begin{array}{cc}
{\frac{98625409}{4096}} & {\frac{12326223}{256}} \\ 
{\frac{12326223}{128}} & {\frac{788893897}{4096}} 
\end{array}
\right]}\  {z \sp 3}} 
\end{array}
$$
\returnType{Type: XPolynomialRing(SquareMatrix(2,Fraction Integer),OrderedFreeMonoid Symbol)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\domainhead{ZeroDimensionalSolvePackage}

The {\tt ZeroDimensionalSolvePackage} package constructor provides
operations for computing symbolically the complex or real roots of
zero-dimensional algebraic systems.

The package provides {\bf no} multiplicity information (i.e. some
returned roots may be double or higher) but only distinct roots are
returned.

Complex roots are given by means of univariate representations of
irreducible regular chains.  These representations are computed by the
\spadfunFrom{univariateSolve}{ZeroDimensionalSolvePackage} operation
(by calling the {\tt InternalRationalUnivariateRepresentationPackage}
package constructor which does the job).

Real roots are given by means of tuples of coordinates lying in the
{\tt RealClosure} of the coefficient ring.  They are computed by the
\spadfunFrom{realSolve}{ZeroDimensionalSolvePackage} and
\spadfunFrom{positiveSolve}{ZeroDimensionalSolvePackage} operations.
The former computes all the solutions of the input system with real
coordinates whereas the later concentrate on the solutions with
(strictly) positive coordinates.  In both cases, the computations are
performed by the {\tt RealClosure} constructor.

Both computations of complex roots and real roots rely on triangular
decompositions.  These decompositions can be computed in two different
ways.  First, by a applying the
\spadfunFrom{zeroSetSplit}{RegularTriangularSet} operation from the
{\tt REGSET} domain constructor.  In that case, no Groebner bases are
computed.  This strategy is used by default.  Secondly, by applying
the \spadfunFrom{zeroSetSplit}{LexTriangularPackage} from 
{\tt LEXTRIPK}.  To use this later strategy with the operations
\spadfunFrom{univariateSolve}{ZeroDimensionalSolvePackage},
\spadfunFrom{realSolve}{ZeroDimensionalSolvePackage} and
\spadfunFrom{positiveSolve}{ZeroDimensionalSolvePackage} one just
needs to use an extra boolean argument.

Note that the way of understanding triangular decompositions 
is detailed in the example of the {\tt RegularTriangularSet}
constructor.

The {\tt ZeroDimensionalSolvePackage} constructor takes three
arguments.  The first one {\bf R} is the coefficient ring; it must
belong to the categories {\tt OrderedRing}, {\tt EuclideanDomain},
{\tt CharacteristicZero} and {\tt RealConstant}.  This means
essentially that {\bf R} is {\tt Integer} or {\tt Fraction(Integer)}.
The second argument {\bf ls} is the list of variables involved in the
systems to solve.  The third one MUST BE {\bf concat(ls,s)} where 
{\bf s} is an additional symbol used for the univariate representations.
The abbreviation for {\tt ZeroDimensionalSolvePackage} is {\tt ZDSOLVE}.

We illustrate now how to use the constructor {\tt ZDSOLVE} by two
examples: the {\em Arnborg and Lazard} system and the {\em L-3} system
(Aubry and Moreno Maza).  Note that the use of this package is also
demonstrated in the example of the {\tt LexTriangularPackage}
constructor.

Define the coefficient ring.

\spadcommand{R := Integer }
$$
Integer 
$$
\returnType{Type: Domain}

Define the lists of variables:

\spadcommand{ls : List Symbol := [x,y,z,t] }
$$
\left[
x, y, z, t 
\right]
$$
\returnType{Type: List Symbol}

and:

\spadcommand{ls2 : List Symbol := [x,y,z,t,new()\$Symbol] }
$$
\left[
x, y, z, t, \%A 
\right]
$$
\returnType{Type: List Symbol}

Call the package:

\spadcommand{pack := ZDSOLVE(R,ls,ls2)}
$$
ZeroDimensionalSolvePackage(Integer,[x,y,z,t],[x,y,z,t,%A]) 
$$
\returnType{Type: Domain}

Define a polynomial system (Arnborg-Lazard)

\spadcommand{p1 := x**2*y*z + x*y**2*z + x*y*z**2 + x*y*z + x*y + x*z + y*z }
$$
{x \  y \  {z \sp 2}}+{{\left( {x \  {y \sp 2}}+{{\left( {x \sp 2}+x+1 
\right)}
\  y}+x 
\right)}
\  z}+{x \  y} 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{p2 := x**2*y**2*z + x*y**2*z**2 + x**2*y*z + x*y*z + y*z + x + z }
$$
{x \  {y \sp 2} \  {z \sp 2}}+{{\left( {{x \sp 2} \  {y \sp 2}}+{{\left( {x 
\sp 2}+x+1 
\right)}
\  y}+1 
\right)}
\  z}+x 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{p3 := x**2*y**2*z**2 + x**2*y**2*z + x*y**2*z + x*y*z + x*z + z + 1 }
$$
{{x \sp 2} \  {y \sp 2} \  {z \sp 2}}+{{\left( {{\left( {x \sp 2}+x 
\right)}
\  {y \sp 2}}+{x \  y}+x+1 
\right)}
\  z}+1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{lp := [p1, p2, p3]}
$$
\begin{array}{@{}l}
\left[
{{x \  y \  {z \sp 2}}+{{\left( {x \  {y \sp 2}}+{{\left( {x \sp 2}+x+1 
\right)}
\  y}+x 
\right)}
\  z}+{x \  y}}, 
\right.
\\
\\
\displaystyle
{{x \  {y \sp 2} \  {z \sp 2}}+{{\left( {{x \sp 2} \  {y 
\sp 2}}+{{\left( {x \sp 2}+x+1 
\right)}
\  y}+1 
\right)}
\  z}+x}, 
\\
\\
\displaystyle
\left.
{{{x \sp 2} \  {y \sp 2} \  {z \sp 2}}+{{\left( {{\left( {x \sp 
2}+x 
\right)}
\  {y \sp 2}}+{x \  y}+x+1 
\right)}
\  z}+1} 
\right]
\end{array}
$$
\returnType{Type: List Polynomial Integer}

Note that these polynomials do not involve the variable {\bf t};
we will use it in the second example.

First compute a decomposition into regular chains (i.e. regular
triangular sets).

\spadcommand{triangSolve(lp)\$pack  }
$$
\begin{array}{@{}l}
\left[
\left\{ 
{z \sp {20}} -
{6 \  {z \sp {19}}} -
{{41} \  {z \sp {18}}}+
{{71} \  {z \sp {17}}}+
{{106} \  {z \sp {16}}}+
{{92} \  {z \sp {15}}}+
{{197} \  {z \sp {14}}}+
\right.
\right.
\\
\\
\displaystyle
{{145} \  {z \sp {13}}}+
{{257} \  {z \sp {12}}}+
{{278} \  {z \sp {11}}}+
{{201} \  {z \sp {10}}}+
{{278} \  {z \sp 9}}+
{{257} \  {z \sp 8}}+
{{145} \  {z \sp 7}}+
\\
\\
\displaystyle
{{197} \  {z \sp 6}}+
{{92} \  {z \sp 5}}+
{{106} \  {z \sp 4}}+
{{71} \  {z \sp 3}} -
{{41} \  {z \sp 2}} -
{6 \  z}+1,
\\
\\
\displaystyle
\left( {{14745844} \  {z \sp {19}}}+
{{50357474} \  {z \sp {18}}} -
{{130948857} \  {z \sp {17}}} -
{{185261586} \  {z \sp {16}}} -
\right.
\\
\\
\displaystyle
{{180077775} \  {z \sp {15}}} -
{{338007307} \  {z \sp {14}}} -
{{275379623} \  {z \sp {13}}} -
{{453190404} \  {z \sp {12}}} -
\\
\\
\displaystyle
{{474597456} \  {z \sp {11}}} -
{{366147695} \  {z \sp {10}}} -
{{481433567} \  {z \sp 9}} -
{{430613166} \  {z \sp 8}} -
\\
\\
\displaystyle
{{261878358} \  {z \sp 7}} -
{{326073537} \  {z \sp 6}} -
{{163008796} \  {z \sp 5}} -
{{177213227} \  {z \sp 4}} -
\\
\\
\displaystyle
\left.
{{104356755} \  {z \sp 3}}+
{{65241699} \  {z \sp 2}}+
{{9237732} \  z} -
{1567348} 
\right)\  y+
\\
\\
\displaystyle
{{1917314} \  {z \sp {19}}}+
{{6508991} \  {z \sp {18}}} -
{{16973165} \  {z \sp {17}}} -
{{24000259} \  {z \sp {16}}} -
\\
\\
\displaystyle
{{23349192} \  {z \sp {15}}} -
{{43786426} \  {z \sp {14}}} -
{{35696474} \  {z \sp {13}}} -
{{58724172} \  {z \sp {12}}} -
\\
\\
\displaystyle
{{61480792} \  {z \sp {11}}} -
{{47452440} \  {z \sp {10}}} -
{{62378085} \  {z \sp 9}} -
{{55776527} \  {z \sp 8}} -
\\
\\
\displaystyle
{{33940618} \  {z \sp 7}} -
{{42233406} \  {z \sp 6}} -
{{21122875} \  {z \sp 5}} -
{{22958177} \  {z \sp 4}} -
\\
\\
\displaystyle
{{13504569} \  {z \sp 3}}+
{{8448317} \  {z \sp 2}}+
{{1195888} \  z} -
{202934}, 
\\
\\
\displaystyle
\left.
\left.
\left( 
\left( {z \sp 3} -{2 \  z} 
\right)\  {y \sp 2}+
\left( -{z \sp 3} -
{z \sp 2} -
{2 \  z} -
1 
\right)\  y -
{z \sp 2} -z+1 
\right)\  x+
{z \sp 2} -1 
\right\}
\right]
\end{array}
$$
\returnType{Type: List RegularChain(Integer,[x,y,z,t])}

We can see easily from this decomposition (consisting of a single
regular chain) that the input system has 20 complex roots.

Then we compute a univariate representation of this regular chain.

\spadcommand{univariateSolve(lp)\$pack}
$$
\begin{array}{@{}l}
\left[
\left[ 
complexRoots=
{? \sp {12}} -
{{12} \  {? \sp {11}}}+
{{24} \  {? \sp {10}}}+
{4 \  {? \sp 9}} -
{9 \  {? \sp 8}}+
{{27} \  {? \sp 7}} -
\right.
\right.
\\
\\
\displaystyle
{{21} \  {? \sp 6}}+
{{27} \  {? \sp 5}} -
{9 \  {? \sp 4}}+
{4 \  {? \sp 3}}+
{{24} \  {? \sp 2}} -
{{12} \  ?}+1, 
\\
\\
\displaystyle
coordinates=
\\
\displaystyle
\left[ 
{{63} \  x}+
{{62} \  { \%A \sp {11}}} -
{{721} \  { \%A \sp {10}}}+
{{1220} \  { \%A \sp 9}}+
{{705} \  {  \%A \sp 8}} -
{{285} \  { \%A \sp 7}}+
\right.
\\
\\
\displaystyle
{{1512} \  { \%A \sp 6}} -
{{735} \  {  \%A \sp 5}}+
{{1401} \  { \%A \sp 4}} -
{{21} \  { \%A \sp 3}}+
{{215} \  { \%A \sp 2}}+
{{1577} \  \%A} -{142}, 
\\
\\
\displaystyle
{63} \  y -
{{75} \  { \%A \sp {11}}}+
{{890} \  { \%A \sp {10}}} -
{{1682} \  { \%A \sp 9}} -
{{516} \  { \%A \sp 8}}+
{{588} \  { \%A \sp 7}} -
{{1953} \  { \%A \sp 6}}+
\\
\\
\displaystyle
{{1323} \  { \%A \sp 5}} -
{{1815} \  { \%A \sp 4}}+
{{426} \  { \%A \sp 3}} -
{{243} \  { \%A \sp 2}} -
{{1801} \  \%A}+{679}, 
\\
\\
\displaystyle
\left.
\left.
{z - \%A} 
\right]
\right],
\\
\\
\displaystyle
\left[ 
complexRoots={{? \sp 6}+{? \sp 5}+{? \sp 4}+{? \sp 3}+{? \sp 2}+?+1}, 
\right.
\\
\displaystyle
\left.
\left.
{coordinates=
{\left[ {x -{ \%A \sp 5}}, {y -{ \%A \sp 3}},  {z - \%A} 
\right]}}
\right],
\right.
\\
\\
\displaystyle
\left.
\left.
{\left[ 
{complexRoots={{? \sp 2}+{5 \  ?}+1}}, 
{coordinates={\left[ {x -1}, {y -1}, {z - \%A} 
\right]}}
\right]}
\right]
\right.
\end{array}
$$
\returnType{Type: 
List Record(
complexRoots: SparseUnivariatePolynomial Integer,
coordinates: List Polynomial Integer)}

We see that the zeros of our regular chain are split into three components.
This is due to the use of univariate polynomial factorization.

Each of these components consist of two parts.  The first one is an
irreducible univariate polynomial {\bf p(?)} which defines a simple
algebraic extension of the field of fractions of {\bf R}.  The second
one consists of multivariate polynomials {\bf pol1(x,\%A)}, 
{\bf pol2(y,\%A)} and {\bf pol3(z,\%A)}.  Each of these polynomials involve
two variables: one is an indeterminate {\bf x}, {\bf y} or {\bf z} of
the input system {\bf lp} and the other is {\bf \%A} which represents
any root of {\bf p(?)}.  Recall that this {\bf \%A} is the last
element of the third parameter of {\tt ZDSOLVE}.  Thus any complex
root {\bf ?} of {\bf p(?)} leads to a solution of the input system
{\bf lp} by replacing {\bf \%A} by this {\bf ?} in {\bf pol1(x,\%A)},
{\bf pol2(y,\%A)} and {\bf pol3(z,\%A)}.  Note that the polynomials
{\bf pol1(x,\%A)}, {\bf pol2(y,\%A)} and {\bf pol3(z,\%A)} have degree
one w.r.t. {\bf x}, {\bf y} or {\bf z} respectively.  This is always
the case for all univariate representations.  Hence the operation 
{\bf univariateSolve} replaces a system of multivariate polynomials by a
list of univariate polynomials, what justifies its name.  Another
example of univariate representations illustrates the 
{\tt LexTriangularPackage} package constructor.

We now compute the solutions with real coordinates:

\spadcommand{lr := realSolve(lp)\$pack   }
$$
\begin{array}{@{}l}
\left[
\left[ 
{ \%B1}, 
\right.
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B1} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B1} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B1} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B1} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B1} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B1} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B1} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B1} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B1} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B1} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B1} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B1} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B1} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B1} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B1} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B1} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B1} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B1} \sp 2}} -
{{\frac{8270}{343}} \  { \%B1}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B1} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B1} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B1} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B1} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B1} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B1} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B1} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B1} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B1} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B1} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B1} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B1} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B1} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B1} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B1} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B1} \sp 4}} -
\\
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B1} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B1} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B1}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B2}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B2} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B2} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B2} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B2} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B2} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B2} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B2} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B2} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B2} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B2} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B2} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B2} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B2} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B2} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B2} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B2} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B2} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B2} \sp 2}} -
{{\frac{8270}{343}} \  { \%B2}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B2} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B2} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B2} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B2} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B2} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B2} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B2} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B2} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B2} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B2} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B2} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B2} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B2} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B2} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B2} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B2} \sp 4}} -
\\
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B2} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B2} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B2}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B3}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B3} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B3} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B3} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B3} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B3} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B3} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B3} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B3} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B3} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B3} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B3} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B3} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B3} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B3} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B3} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B3} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B3} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B3} \sp 2}} -
{{\frac{8270}{343}} \  { \%B3}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B3} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B3} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B3} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B3} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B3} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B3} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B3} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B3} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B3} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B3} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B3} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B3} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B3} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B3} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B3} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B3} \sp 4}} -
\\
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B3} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B3} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B3}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B4}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B4} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B4} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B4} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B4} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B4} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B4} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B4} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B4} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B4} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B4} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B4} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B4} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B4} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B4} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B4} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B4} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B4} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B4} \sp 2}} -
{{\frac{8270}{343}} \  { \%B4}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B4} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B4} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B4} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B4} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B4} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B4} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B4} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B4} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B4} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B4} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B4} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B4} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B4} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B4} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B4} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B4} \sp 4}} -
\\
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B4} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B4} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B4}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B5}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B5} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B5} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B5} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B5} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B5} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B5} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B5} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B5} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B5} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B5} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B5} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B5} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B5} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B5} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B5} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B5} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B5} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B5} \sp 2}} -
{{\frac{8270}{343}} \  { \%B5}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B5} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B5} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B5} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B5} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B5} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B5} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B5} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B5} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B5} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B5} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B5} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B5} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B5} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B5} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B5} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B5} \sp 4}} -
\\
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B5} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B5} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B5}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B6}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B6} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B6} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B6} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B6} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B6} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B6} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B6} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B6} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B6} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B6} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B6} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B6} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B6} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B6} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B6} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B6} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B6} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B6} \sp 2}} -
{{\frac{8270}{343}} \  { \%B6}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B6} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B6} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B6} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B6} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B6} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B6} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B6} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B6} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B6} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B6} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B6} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B6} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B6} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B6} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B6} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B6} \sp 4}} -
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B6} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B6} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B6}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B7}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B7} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B7} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B7} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B7} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B7} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B7} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B7} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B7} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B7} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B7} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B7} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B7} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B7} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B7} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B7} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B7} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B7} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B7} \sp 2}} -
{{\frac{8270}{343}} \  { \%B7}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B7} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B7} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B7} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B7} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B7} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B7} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B7} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B7} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B7} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B7} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B7} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B7} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B7} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B7} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B7} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B7} \sp 4}} -
\\
\\
\displaystyle
\left.
{{\frac{801511}{26117}} \  {{ \%B7} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B7} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B7}}+
{\frac{377534}{705159}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B8}, 
\right.
\\
\\
\displaystyle
{{\frac{1184459}{1645371}} \  {{ \%B8} \sp {19}}} -
{{\frac{2335702}{548457}} \  {{ \%B8} \sp {18}}} -
{{\frac{5460230}{182819}} \  {{ \%B8} \sp {17}}}+
{{\frac{79900378}{1645371}} \  {{ \%B8} \sp {16}}}+
\\
\\
\displaystyle
{{\frac{43953929}{548457}} \  {{ \%B8} \sp {15}}}+
{{\frac{13420192}{182819}} \  {{ \%B8} \sp {14}}}+
{{\frac{553986}{3731}} \  {{ \%B8} \sp {13}}}+
{{\frac{193381378}{1645371}} \  {{ \%B8} \sp {12}}}+
\\
\\
\displaystyle
{{\frac{35978916}{182819}} \  {{ \%B8} \sp {11}}}+
{{\frac{358660781}{1645371}} \  {{  \%B8} \sp {10}}}+
{{\frac{271667666}{1645371}} \  {{ \%B8} \sp 9}}+
{{\frac{118784873}{548457}} \  {{ \%B8} \sp 8}}+
\\
\\
\displaystyle
{{\frac{337505020}{1645371}} \  {{ \%B8} \sp 7}}+
{{\frac{1389370}{11193}} \  {{ \%B8} \sp 6}}+
{{\frac{688291}{4459}} \  {{ \%B8} \sp 5}}+
{{\frac{3378002}{42189}} \  {{ \%B8} \sp 4}}+
\\
\\
\displaystyle
{{\frac{140671876}{1645371}} \  {{ \%B8} \sp 3}}+
{{\frac{32325724}{548457}} \  {{ \%B8} \sp 2}} -
{{\frac{8270}{343}} \  { \%B8}} -
{\frac{9741532}{1645371}}, 
\\
\\
\displaystyle
-{{\frac{91729}{705159}} \  {{  \%B8} \sp {19}}}+
{{\frac{487915}{705159}} \  {{ \%B8} \sp {18}}}+
{{\frac{4114333}{705159}} \  {{ \%B8} \sp {17}}} -
{{\frac{1276987}{235053}} \  {{ \%B8} \sp {16}}} -
\\
\\
\displaystyle
{{\frac{13243117}{705159}} \  {{ \%B8} \sp {15}}} -
{{\frac{16292173}{705159}} \  {{ \%B8} \sp {14}}} -
{{\frac{26536060}{705159}} \  {{ \%B8} \sp {13}}} -
{{\frac{722714}{18081}} \  {{ \%B8} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{5382578}{100737}} \  {{ \%B8} \sp {11}}} -
{{\frac{15449995}{235053}} \  {{ \%B8} \sp {10}}} -
{{\frac{14279770}{235053}} \  {{  \%B8} \sp 9}} -
{{\frac{6603890}{100737}} \  {{ \%B8} \sp 8}} -
\\
\\
\displaystyle
{{\frac{409930}{6027}} \  {{ \%B8} \sp 7}} -
{{\frac{37340389}{705159}} \  {{ \%B8} \sp 6}} -
{{\frac{34893715}{705159}} \  {{ \%B8} \sp 5}} -
{{\frac{26686318}{705159}} \  {{ \%B8} \sp 4}} -
\\
\\
\displaystyle
\left.
\left.
{{\frac{801511}{26117}} \  {{ \%B8} \sp 3}} -
{{\frac{17206178}{705159}} \  {{ \%B8} \sp 2}} -
{{\frac{4406102}{705159}} \  { \%B8}}+
{\frac{377534}{705159}} 
\right]
\right]
\end{array}
$$
\returnType{Type: List List RealClosure Fraction Integer}
The number of real solutions for the input system is:

\spadcommand{\# lr }
$$
8 
$$
\returnType{Type: PositiveInteger}

Each of these real solutions is given by a list of elements in 
{\tt RealClosure(R)}.  In these 8 lists, the first element is a value of
{\bf z}, the second of {\bf y} and the last of {\bf x}.  This is
logical since by setting the list of variables of the package to 
{\bf [x,y,z,t]} we mean that the elimination ordering on the variables is
{\bf t < z < y < x }.  Note that each system treated by the 
{\tt ZDSOLVE} package constructor needs only to be zero-dimensional
w.r.t. the variables involved in the system it-self and not
necessarily w.r.t. all the variables used to define the package.

We can approximate these real numbers as follows. 
This computation takes between 30 sec. and 5 min, depending on your machine.

\spadcommand{[ [approximate(r,1/1000000) for r in point] for point in lr] }
$$
\begin{array}{@{}l}
\left[
\left[ 
\displaystyle
-{\frac{10048059}{2097152}}, 
\right.
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
450305731698538794352439791383896641459673197621176821933588120838
\\
\displaystyle
551631405892456717609142362969577740309983336076104889822891657813
\\
\displaystyle
709430983859733113720258484693913237615701950676035760116591745498
\\
\displaystyle
681538209878909485152342039281129312614132985654697714546466149548
\\
\displaystyle
782591994118844704172244049192156726354215802806143775884436463441
\\
\displaystyle
0045253024786561923163288214175
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
450305728302524548851651180698582663508310069375732046528055470686
\\
\displaystyle
564494957750991686720188943809040835481793171859386279762455151898
\\
\displaystyle
357079304877442429148870882984032418920030143612331486020082144373
\\
\displaystyle
379075531124363291986489542170422894957129001611949880795702366386
\\
\displaystyle
544306939202714897968826671232335604349152343406892427528041733857
\\
\displaystyle
4817381189277066143312396681216,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
210626076882347507389479868048601659624960714869068553876368371502
\\
\displaystyle
063968085864965079005588950564689330944709709993780218732909532589
\\
\displaystyle
878524724902071750498366048207515661873872451468533306001120296463
\\
\displaystyle
516638135154325598220025030528398108683711061484230702609121129792
\\
\displaystyle
987689628568183047905476005638076266490561846205530604781619178201
\\
\displaystyle
15887037891389881895
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
210626060949846419247211380481647417534196295329643410241390314236
\\
\displaystyle
875796768527388858559097596521177886218987288195394364024629735706
\\
\displaystyle
195981232610365979902512686325867656720234210687703171018424748418
\\
\displaystyle
142328892183768123706270847029570621848592886740077193782849920092
\\
\displaystyle
376059331416890100066637389634759811822855673103707202647449677622
\\
\displaystyle
83837629939232800768
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
-{\frac{2563013}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
-261134617679192778969861769323775771923825996306354178192275233
\\
\displaystyle
044018989966807292833849076862359320744212592598673381593224350480
\\
\displaystyle
9294837523030237337236806668167446173001727271353311571242897
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
11652254005052225305839819160045891437572266102768589900087901348
\\
\displaystyle
199149409224137539839713940195234333204081399281531888294957554551
\\
\displaystyle
63963417619308395977544797140231469234269034921938055593984,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
3572594550275917221096588729615788272998517054675603239578198141
\\
\displaystyle
006034091735282826590621902304466963941971038923304526273329316373
\\
\displaystyle
7574500619789892286110976997087250466235373
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
10395482693455989368770712448340260558008145511201705922005223665
\\
\displaystyle
917594096594864423391410294529502651799899601048118758225302053465
\\
\displaystyle
051315812439017247289173865014702966308864
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
-{\frac{1715967}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
-421309353378430352108483951797708239037726150396958622482899843
\\
\displaystyle
660603065607635937456481377349837660312126782256580143620693951995
\\
\displaystyle
146518222580524697287410022543952491
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
94418141441853744586496920343492240524365974709662536639306419607
\\
\displaystyle
958058825854931998401916999176594432648246411351873835838881478673
\\
\displaystyle
4019307857605820364195856822304768,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
7635833347112644222515625424410831225347475669008589338834162172
\\
\displaystyle
501904994376346730876809042845208919919925302105720971453918982731
\\
\displaystyle
3890725914035
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
26241887640860971997842976104780666339342304678958516022785809785
\\
\displaystyle
037845492057884990196406022669660268915801035435676250390186298871
\\
\displaystyle
4128491675648
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
-{\frac{437701}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
1683106908638349588322172332654225913562986313181951031452750161
\\
\displaystyle
441497473455328150721364868355579646781603507777199075077835213366
\\
\displaystyle
48453365491383623741304759
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
16831068680952133890017099827059136389630776687312261111677851880
\\
\displaystyle
049074252262986803258878109626141402985973669842648879989083770687
\\
\displaystyle
9999845423381649008099328,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
4961550109835010186422681013422108735958714801003760639707968096
\\
\displaystyle
64691282670847283444311723917219104249213450966312411133
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
49615498727577383155091920782102090298528971186110971262363840408
\\
\displaystyle
2937659261914313170254867464792718363492160482442215424
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
{\frac{222801}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
-899488488040242826510759512197069142713604569254197827557300186
\\
\displaystyle
521375992158813771669612634910165522019514299493229913718324170586
\\
\displaystyle
7672383477
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
11678899986650263721777651006918885827089699602299347696908357524
\\
\displaystyle
570777794164352094737678665077694058889427645877185424342556259924
\\
\displaystyle
56372224,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
-238970488813315687832080154437380839561277150920849101984745299
\\
\displaystyle
188550954651952546783901661359399969388664003628357055232115503787
\\
\displaystyle
1291458703265
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
53554872736450963260904032866899319059882254446854114332215938336
\\
\displaystyle
811929575628336714686542903407469936562859255991176021204461834431
\\
\displaystyle
45479421952
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
{\frac{765693}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
8558969219816716267873244761178198088724698958616670140213765754
\\
\displaystyle
322002303251685786118678330840203328837654339523418704917749518340
\\
\displaystyle
772512899000391009630373148561
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
29414424455330107909764284113763934998155802159458569179064525354
\\
\displaystyle
957230138568189417023302287798901412962367211381542319972389173221
\\
\displaystyle
567119652444639331719460159488,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
-205761823058257210124765032486024256111130258154358880884392366
\\
\displaystyle
276754938224165936271229077761280019292142057440894808519374368858
\\
\displaystyle
27622246433251878894899015
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
26715982033257355380979523535014502205763137598908350970917225206
\\
\displaystyle
427101987719026671839489062898637147596783602924839492046164715377
\\
\displaystyle
77775324180661095366656
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
{\frac{5743879}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
1076288816968906847955546394773570208171456724942618614023663123
\\
\displaystyle
574768960850434263971398072546592772662158833449797698617455397887
\\
\displaystyle
562900072984768000608343553189801693408727205047612559889232757563
\\
\displaystyle
830528688953535421809482771058917542602890060941949620874083007858
\\
\displaystyle
36666945350176624841488732463225
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
31317689570803179466484619400235520441903766134585849862285496319
\\
\displaystyle
161966016162197817656155325322947465296482764305838108940793745664
\\
\displaystyle
607578231468885811955560292085152188388832003186584074693994260632
\\
\displaystyle
605898286123092315966691297079864813198515719429272303406229340239
\\
\displaystyle
234867030420681530440845099008,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\frac{\left(
\begin{array}{@{}l}
-211328669918575091836412047556545843787017248986548599438982813
\\
\displaystyle
533526444466528455752649273493169173140787270143293550347334817207
\\
\displaystyle
609872054584900878007756416053431789468836611952973998050294416266
\\
\displaystyle
855009812796195049621022194287808935967492585059442776850225178975
\\
\displaystyle
8706752831632503615
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
16276155849379875802429066243471045808891444661684597180431538394
\\
\displaystyle
083725255333098080703636995855022160112110871032636095510260277694
\\
\displaystyle
140873911481262211681397816825874380753225914661319399754572005223
\\
\displaystyle
498385689642856344480185620382723787873544601061061415180109356172
\\
\displaystyle
051706396253618176
\end{array}
\right)}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
\displaystyle
{\frac{19739877}{2097152}}, 
\right.
\\
\\
\displaystyle
\frac{\left(
\begin{array}{@{}l}
-299724993683270330379901580486152094921504038750070717770128576
\\
\displaystyle
672019253057942247895356602435986014310154780163808277161116037221
\\
\displaystyle
287484777803580987284314922548423836585801362934170532170258233335
\\
\displaystyle
091800960178993702398593530490046049338987383703085341034708990888
\\
\displaystyle
081485398113201846458245880061539477074169948729587596021075021589
\\
\displaystyle
194881447685487103153093129546733219013370267109820090228230051075
\\
\displaystyle
18607185928457030277807397796525813862762239286996106809728023675
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
23084332748522785907289100811918110239065041413214326461239367948
\\
\displaystyle
739333192706089607021381934176478983606202295191766329376317868514
\\
\displaystyle
550147660272062590222525055517418236888968838066366025744317604722
\\
\displaystyle
402920931967294751602472688341211418933188487286618444349272872851
\\
\displaystyle
128970807675528648950565858640331785659103870650061128015164035227
\\
\displaystyle
410373609905560544769495270592270708095930494912575195547088792595
\\
\displaystyle
9552929920110858560812556635485429471554031675979542656381353984,
\end{array}
\right)}
\end{array}
$$
$$
\begin{array}{@{}l}
\left.
\left.
\frac{\left(
\begin{array}{@{}l}
-512818926354822848909627639786894008060093841066308045940796633
\\
\displaystyle
584500926410949052045982531625008472301004703502449743652303892581
\\
\displaystyle
895928931293158470135392762143543439867426304729390912285013385199
\\
\displaystyle
069649023156609437199433379507078262401172758774998929661127731837
\\
\displaystyle
229462420711653791043655457414608288470130554391262041935488541073
\\
\displaystyle
594015777589660282236457586461183151294397397471516692046506185060
\\
\displaystyle
376287516256195847052412587282839139194642913955
\end{array}
\right)}
{\left(
\begin{array}{@{}l}
22882819397784393305312087931812904711836310924553689903863908242
\\
\displaystyle
435094636442362497730806474389877391449216077946826538517411890917
\\
\displaystyle
117418681451149783372841918224976758683587294866447308566225526872
\\
\displaystyle
092037244118004814057028371983106422912756761957746144438159967135
\\
\displaystyle
026293917497835900414708601277523729964886277426724876224800632688
\\
\displaystyle
088893248918508424949343473376030759399802682084829048596781777514
\\
\displaystyle
4465749979827872616963053217673201717237252096
\end{array}
\right)}
\right]
\right]
\end{array}
$$
\returnType{Type: List List Fraction Integer}

We can also concentrate on the solutions with real (strictly) positive
coordinates:

\spadcommand{lpr := positiveSolve(lp)\$pack   }
$$
\left[
\right]
$$
\returnType{Type: List List RealClosure Fraction Integer}

Thus we have checked that the input system has no solution with
strictly positive coordinates.

Let us define another polynomial system ({\em L-3}).

\spadcommand{f0 := x**3 + y + z + t- 1 }
$$
z+y+{x \sp 3}+t -1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{f1 := x + y**3 + z + t -1 }
$$
z+{y \sp 3}+x+t -1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{f2 := x + y + z**3 + t-1 }
$$
{z \sp 3}+y+x+t -1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{f3 := x + y + z + t**3 -1 }
$$
z+y+x+{t \sp 3} -1 
$$
\returnType{Type: Polynomial Integer}

\spadcommand{lf := [f0, f1, f2, f3]}
$$
\begin{array}{@{}l}
\left[
{z+y+{x \sp 3}+t -1}, 
{z+{y \sp 3}+x+t -1}, 
\right.
\\
\\
\displaystyle
\left.
{{z \sp 3}+y+x+t -1},  
{z+y+x+{t \sp 3} -1} 
\right]
\end{array}
$$
\returnType{Type: List Polynomial Integer}

First compute a decomposition into regular chains (i.e. regular
triangular sets).

\spadcommand{lts := triangSolve(lf)\$pack   }
$$
\begin{array}{@{}l}
\left[
\left\{ {{t \sp 2}+t+1}, {{z \sp 3} -z -{t \sp 3}+t}, 
\left( {3 \  z}+{3 \  {t \sp 3}} -3 
\right)\  {y \sp 2}+
\left( {3 \  {z \sp 2}}+
\left( {6 \  {t \sp 3}} -6 
\right)\  z+
{3 \  {t \sp 6}} -
\right.
\right.
\right.
\\
\displaystyle
\left.
{6 \  {t \sp 3}}+3 
\right)\  y+
{{\left( {3 \  {t \sp 3}} -3 
\right)}\  {z \sp 2}}+
{{\left( {3 \  {t \sp 6}} -{6 \  {t \sp 3}}+3 
\right)}\  z}+
{t \sp 9} -
{3 \  {t \sp 6}}+
{5 \  {t \sp 3}} -
{3 \  t}, 
\\
\displaystyle
\left.
{x+y+z} 
\right\},
\left\{ 
{t \sp {16}} 
-{6 \  {t \sp {13}}}+
{9 \  {t \sp {10}}}+
{4 \  {t \sp 7}}+
{{15} \  {t \sp 4}} -
{{54} \  {t \sp 2}}+
{27}, 
\right.
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{4907232} \  {t \sp {15}}}+
{{40893984} \  {t \sp {14}}} -
{{115013088} \  {t \sp {13}}}+
{{22805712} \  {t \sp {12}}}+
{{36330336} \  {t \sp {11}}}+
\right.
\\
\displaystyle
{{162959040} \  {t \sp {10}}} -
{{159859440} \  {t \sp 9}} -
{{156802608} \  {t \sp 8}}+
{{117168768} \  {t \sp 7}}+
\\
\displaystyle
{{126282384} \  {t \sp 6}} -
{{129351600} \  {t \sp 5}}+
{{306646992} \  {t \sp 4}}+
{{475302816} \  {t \sp 3}} -
\\
\displaystyle
\left.
{{1006837776} \  {t \sp 2}} -
{{237269088} \  t}+
{480716208} 
\right)\  z+
\end{array}
$$
$$
\begin{array}{@{}l}
{{48} \  {t \sp {54}}} -
{{912} \  {t \sp {51}}}+
{{8232} \  {t \sp {48}}} -
{{72} \  {t \sp {46}}} -
{{46848} \  {t \sp {45}}}+
{{1152} \  {t \sp {43}}}+
{{186324} \  {t \sp {42}}} -\hbox{\hskip 1.0cm}
\\
\displaystyle
{{3780} \  {t \sp {40}}} -
{{543144} \  {t \sp {39}}} -
{{3168} \  {t \sp {38}}} -
{{21384} \  {t \sp {37}}}+
{{1175251} \  {t \sp {36}}}+
{{41184} \  {t \sp {35}}}+
\\
\displaystyle
{{278003} \  {t \sp {34}}}-
{{1843242} \  {t \sp {33}}} -
{{301815} \  {t \sp {32}}} -
{{1440726} \  {t \sp {31}}}+
{{1912012} \  {t \sp {30}}}+
\\
\displaystyle
{{1442826} \  {t \sp {29}}}+
{{4696262} \  {t \sp {28}}} -
{{922481} \  {t \sp {27}}} -
{{4816188} \  {t \sp {26}}} -
{{10583524} \  {t \sp {25}}} -
\\
\displaystyle
{{208751} \  {t \sp {24}}}+
{{11472138} \  {t \sp {23}}}+
{{16762859} \  {t \sp {22}}} -
{{857663} \  {t \sp {21}}} -
{{19328175} \  {t \sp {20}}} -
\\
\displaystyle
{{18270421} \  {t \sp {19}}}+
{{4914903} \  {t \sp {18}}}+
{{22483044} \  {t \sp {17}}}+
{{12926517} \  {t \sp {16}}} -
{{8605511} \  {t \sp {15}}} -
\\
\displaystyle
{{17455518} \  {t \sp {14}}} -
{{5014597} \  {t \sp {13}}}+
{{8108814} \  {t \sp {12}}}+
{{8465535} \  {t \sp {11}}}+
{{190542} \  {t \sp {10}}} -
\\
\displaystyle
{{4305624} \  {t \sp 9}} -
{{2226123} \  {t \sp 8}}+
{{661905} \  {t \sp 7}}+
{{1169775} \  {t \sp 6}}+
{{226260} \  {t \sp 5}} -
\\
\displaystyle
{{209952} \  {t \sp 4}} -
{{141183} \  {t \sp 3}}+
{{27216} \  t}, 
\end{array}
$$
$$
\begin{array}{@{}l}
\left( {3 \  z}+{3 \  {t \sp 3}} -3 \right)\  {y \sp 2}+
\left( {3 \  {z \sp 2}}+
\left( {6 \  {t \sp 3}} -6 \right)\  z+
{3 \  {t \sp 6}} -{6 \  {t \sp 3}}+3 \right)\  y+
\left( {3 \  {t \sp 3}} -3 \right)\  {z \sp 2}+
\\
\displaystyle
\left.
\left( {3 \  {t \sp 6}} -{6 \  {t \sp 3}}+3 \right)\  z+
{t \sp 9} -{3 \  {t \sp 6}}+{5 \  {t \sp 3}} -{3 \  t}, 
{x+y+z+{t \sp 3} -1} 
\right\},
\\
\displaystyle
{\left\{ t, {z -1}, {{y \sp 2} -1}, {x+y} \right\}},
{\left\{ {t -1}, z, {{y \sp 2} -1}, {x+y} \right\}},
{\left\{ {t -1}, {{z \sp 2} -1}, {{z \  y}+1}, x \right\}},
\\
\displaystyle
\left\{ 
{t \sp {16}} -{6 \  {t \sp {13}}}+
{9 \  {t \sp {10}}}+
{4 \  {t \sp 7}}+
{{15} \  {t \sp 4}} -
{{54} \  {t \sp 2}}+
{27}, 
\right.
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{4907232} \  {t \sp {29}}}+
{{40893984} \  {t \sp {28}}} -
{{115013088} \  {t \sp {27}}} -
{{1730448} \  {t \sp {26}}} -
{{168139584} \  {t \sp {25}}}+
\right.
\\
\displaystyle
{{738024480} \  {t \sp {24}}} -
{{195372288} \  {t \sp {23}}}+
{{315849456} \  {t \sp {22}}} -
{{2567279232} \  {t \sp {21}}}+
\\
\displaystyle
{{937147968} \  {t \sp {20}}}+
{{1026357696} \  {t \sp {19}}}+
{{4780488240} \  {t \sp {18}}} -
{{2893767696} \  {t \sp {17}}} -
\\
\displaystyle
{{5617160352} \  {t \sp {16}}} -
{{3427651728} \  {t \sp {15}}}+
{{5001100848} \  {t \sp {14}}}+
{{8720098416} \  {t \sp {13}}}+
\\
\displaystyle
{{2331732960} \  {t \sp {12}}} -
{{499046544} \  {t \sp {11}}} -
{{16243306272} \  {t \sp {10}}} -
{{9748123200} \  {t \sp 9}}+
\\
\displaystyle
{{3927244320} \  {t \sp 8}}+
{{25257280896} \  {t \sp 7}}+
{{10348032096} \  {t \sp 6}} -
{{17128672128} \  {t \sp 5}} -
\\
\displaystyle
{{14755488768} \  {t \sp 4}}+
{{544086720} \  {t \sp 3}}+
{{10848188736} \  {t \sp 2}}+
{{1423614528} \  t} -
\\
\displaystyle
\left.
{2884297248} 
\right) z -
\end{array}
$$
$$
\begin{array}{@{}l}
{{48} \  {t \sp {68}}}+
{{1152} \  {t \sp {65}}} -
{{13560} \  {t \sp {62}}}+
{{360} \  {t \sp {60}}}+
{{103656} \  {t \sp {59}}} -
{{7560} \  {t \sp {57}}} -
{{572820} \  {t \sp {56}}}+
\\
\displaystyle
{{71316} \  {t \sp {54}}}+
{{2414556} \  {t \sp {53}}}+
{{2736} \  {t \sp {52}}} -
{{402876} \  {t \sp {51}}} -
{{7985131} \  {t \sp {50}}} -
{{49248} \  {t \sp {49}}}+
\\
\displaystyle
{{1431133} \  {t \sp {48}}}+
{{20977409} \  {t \sp {47}}}+
{{521487} \  {t \sp {46}}} -
{{2697635} \  {t \sp {45}}} -
{{43763654} \  {t \sp {44}}} -
\\
\displaystyle
{{3756573} \  {t \sp {43}}} -
{{2093410} \  {t \sp {42}}}+
{{71546495} \  {t \sp {41}}}+
{{19699032} \  {t \sp {40}}}+
{{35025028} \  {t \sp {39}}} -
\\
\displaystyle
{{89623786} \  {t \sp {38}}} -
{{77798760} \  {t \sp {37}}} -
{{138654191} \  {t \sp {36}}}+
{{87596128} \  {t \sp {35}}}+
{{235642497} \  {t \sp {34}}}+
\\
\displaystyle
{{349607642} \  {t \sp {33}}} 
-{{93299834} \  {t \sp {32}}} -
{{551563167} \  {t \sp {31}}} -
{{630995176} \  {t \sp {30}}}+
\\
\displaystyle
{{186818962} \  {t \sp {29}}}+
{{995427468} \  {t \sp {28}}}+
{{828416204} \  {t \sp {27}}} -
{{393919231} \  {t \sp {26}}} -
\\
\displaystyle
{{1076617485} \  {t \sp {25}}} -
{{1609479791} \  {t \sp {24}}}+
{{595738126} \  {t \sp {23}}}+
{{1198787136} \  {t \sp {22}}}+
\\
\displaystyle
{{4342832069} \  {t \sp {21}}} -
{{2075938757} \  {t \sp {20}}} -
{{4390835799} \  {t \sp {19}}} 
-{{4822843033} \  {t \sp {18}}}+
\\
\displaystyle
{{6932747678} \  {t \sp {17}}}+
{{6172196808} \  {t \sp {16}}}+
{{1141517740} \  {t \sp {15}}} -
{{4981677585} \  {t \sp {14}}} -
\\
\displaystyle
{{9819815280} \  {t \sp {13}}} -
{{7404299976} \  {t \sp {12}}} -
{{157295760} \  {t \sp {11}}}+
{{29124027630} \  {t \sp {10}}}+
\\
\displaystyle
{{14856038208} \  {t \sp 9}} -
{{16184101410} \  {t \sp 8}} -
{{26935440354} \  {t \sp 7}} -
{{3574164258} \  {t \sp 6}}+
\\
\displaystyle
{{10271338974} \  {t \sp 5}}+
{{11191425264} \  {t \sp 4}}+
{{6869861262} \  {t \sp 3}} -
{{9780477840} \  {t \sp 2}} -
\\
\displaystyle
{{3586674168} \  t}+
{2884297248}, 
\end{array}
$$
$$
\begin{array}{@{}l}
\left( {3 \  {z \sp 3}}+
{{\left( {6 \  {t \sp 3}} -6 
\right)}\  {z \sp 2}}+
\left( {6 \  {t \sp 6}} -{{12} \  {t \sp 3}}+3 
\right)\  z+{2 \  {t \sp 9}} -{6 \  {t \sp 6}}+{t \sp 3}+{3 \  t} 
\right)\  y+
\hbox{\hskip 1.0cm}
\\
\\
\displaystyle
{{\left( {3 \  {t \sp 3}} -3 \right)}\  {z \sp 3}}+
{{\left( {6 \  {t \sp 6}} -{{12} \  {t \sp 3}}+6 \right)}\  {z \sp 2}}+
{{\left( {4 \  {t \sp 9}} -{{12} \  {t \sp 6}}+{{11} \  {t \sp 3}} -3 
\right)}\  z}+
\\
\\
\displaystyle
\left.
{t \sp {12}} -
{4 \  {t \sp 9}}+
{5 \  {t \sp 6}} -
{2 \  {t \sp 3}}, 
{x+y+z+{t \sp 3} -1} 
\right\},
\\
\\
\displaystyle
\left\{ {t -1}, {{z \sp 2} -1}, y, {x+z} \right\},
\left\{ 
{t \sp 8}+
{t \sp 7}+
{t \sp 6} -
{2 \  {t \sp 5}} -
{2 \  {t \sp 4}} -
{2 \  {t \sp 3}}+
{{19} \  {t \sp 2}}+
{{19} \  t} -8, 
\right.
\end{array}
$$
$$
\begin{array}{@{}l}
\left( 
{{2395770} \  {t \sp 7}}+
{{3934440} \  {t \sp 6}} -
{{3902067} \  {t \sp 5}} -
{{10084164} \  {t \sp 4}} -
{{1010448} \  {t \sp 3}}+
{{32386932} \  {t \sp 2}}+
\right.
\\
\\
\displaystyle
\left.
{{22413225} \  t} -
{10432368} 
\right)\  z -
{{463519} \  {t \sp 7}}+
{{3586833} \  {t \sp 6}}+
{{9494955} \  {t \sp 5}} -
{{8539305} \  {t \sp 4}} -
\\
\\
\displaystyle
{{33283098} \  {t \sp 3}}+
{{35479377} \  {t \sp 2}}+
{{46263256} \  t} -
{17419896}, 
\end{array}
$$
$$
\begin{array}{@{}l}
\left( {3 \  {z \sp 4}}+
\left( {9 \  {t \sp 3}} -9 \right)\  {z \sp 3}+
\left( {{12} \  {t \sp 6}} -{{24} \  {t \sp 3}}+9 \right)\  {z \sp 2}+
\left( -{{152} \  {t \sp 3}}+{{219} \  t} -{67} \right)\  z -
\right.
\\
\\
\displaystyle
\left.
{{41} \  {t \sp 6}}+{{57} \  {t \sp 4}}+{{25} \  {t \sp 3}} -{{57} \  t}+{16} 
\right)\  y+
{{\left( {3 \  {t \sp 3}} -3 \right)}\  {z \sp 4}}+
{{\left( {9 \  {t \sp 6}} -{{18} \  {t \sp 3}}+9 \right)}\  {z \sp 3}}+
\\
\\
\displaystyle
{{\left( -{{181} \  {t \sp 3}}+{{270} \  t} -{89} \right)}\  {z \sp 2}}+
{{\left( -{{92} \  {t \sp 6}}+{{135} \  {t \sp 4}}+
{{49} \  {t \sp 3}} -{{135} \  t}+{43} \right)}\  z}+
\\
\\
\displaystyle
\left.
{{27} \  {t \sp 7}} -
{{27} \  {t \sp 6}} -
{{54} \  {t \sp 4}}+
{{396} \  {t \sp 3}} -
{{486} \  t}+{144}, 
{x+y+z+{t \sp 3} -1} 
\right\},
\\
\\
\displaystyle
{\left\{ t, {z -{t \sp 3}+1}, {y -1}, {x -1} \right\}},
{\left\{ {t -1}, z, y, x \right\}},
{\left\{ t, {z -1}, y, x \right\}},
{\left\{ t, z, {y -1}, x \right\}},
\\
\\
\displaystyle
\left.
{\left\{ t, z, y, {x -1} \right\}}
\right]
\end{array}
$$
\returnType{Type: List RegularChain(Integer,[x,y,z,t])}

Then we compute a univariate representation.

\spadcommand{univariateSolve(lf)\$pack  }
$$
\begin{array}{@{}l}
\left[
{\left[ {complexRoots=?}, {coordinates=
\left[ {x -1}, {y -1}, 
{z+1}, {t - \%A} 
\right]}
\right]},
\right.
\\
\displaystyle
{\left[ {complexRoots=?}, {coordinates={\left[ x, {y -1}, z, 
{t - \%A} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={? -1}}, {coordinates={\left[ x, y, z, 
{t - \%A} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots=?}, {coordinates={\left[ {x -1}, y, z, 
{t - \%A} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots=?}, {coordinates={\left[ x, y, {z -1}, 
{t - \%A} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={? -2}}, {coordinates={\left[ {x -1}, {y+1}, 
z, {t -1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots=?}, {coordinates={\left[ {x+1}, {y -1}, z, 
{t -1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={? -1}}, {coordinates={\left[ {x -1}, {y+1}, 
{z -1}, t 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={?+1}}, {coordinates={\left[ {x+1}, {y -1}, 
{z -1}, t 
\right]}}
\right]},
\\
\displaystyle
\left[ {complexroots={{? \sp 6} -{2 \  {? \sp 3}}+{3 \  {? \sp 2}} -3}}, 
coordinates=
\left[ {{2 \  x}+{ \%A \sp 3}+ \%A -1}, 
\right.
\right.
\\
\displaystyle
\left.
\left.
{{2 \  y}+{ \%A \sp 3}+ \%A -1}, {z - \%A}, {t - \%A} 
\right]
\right],
\\
\displaystyle
\left[ 
{complexRoots={{? \sp 5}+{3 \  {? \sp 3}} -{2 \  {? \sp 2}}+{3 \  ?} -3}}, 
coordinates=
\left[ {x - \%A}, 
\right.
\right.
\\
\displaystyle
\left.
\left.
{y - \%A}, {z+{ \%A \sp 3}+{2 \  \%A} -1}, {t - \%A} 
\right]
\right],
\\
\displaystyle
\left[ 
{complexRoots={{? \sp 4} -{? \sp 3} -{2 \  {? \sp 2}}+3}}, 
coordinates=
\left[ {x+{ \%A \sp 3} - \%A -1}, 
\right.
\right.
\\
\displaystyle
\left.
\left.
{y+{ \%A \sp 3} - \%A -1}, 
{z -{ \%A \sp 3}+{2 \  \%A}+1}, 
{t - \%A} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots={?+1}}, coordinates=
\left[ {x -1}, {y -1}, z, {t - \%A} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots={{? \sp 6}+{2 \  {? \sp 3}}+{3 \  {? \sp 2}} -3}}, 
coordinates=
\left[ 
{{2 \  x} -{ \%A \sp 3} - \%A -1}, 
\right.
\right.
\\
\displaystyle
\left.
\left.
{y+ \%A}, 
{{2 \  z} -{ \%A \sp 3} - \%A -1}, {t+ \%A} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots={{? \sp 6}+{{12} \  {? \sp 4}}+{{20} \  {? \sp 3}} 
-{{45} \  {? \sp 2}} -{{42} \  ?} -{953}}}, 
coordinates=
\right.
\\
\displaystyle
\left.
\left[ 
{{{12609} \  x}+
{{23} \  { \%A \sp 5}}+
{{49} \  { \%A \sp 4}} -
{{46} \  { \%A \sp 3}}+
{{362} \  { \%A \sp 2}} -
{{5015} \  \%A} -{8239}}, 
\right.
\right.
\\
\displaystyle
{{{25218} \  y}+
{{23} \  { \%A \sp 5}}+
{{49} \  { \%A \sp 4}} -
{{46} \  { \%A \sp 3}}+
{{362} \  { \%A \sp 2}}+
{{7594} \  \%A} -
{8239}}, 
\\
\displaystyle
{{{25218} \  z}+
{{23} \  { \%A \sp 5}}+
{{49} \  { \%A \sp 4}} -
{{46} \  { \%A \sp 3}}+
{{362} \  { \%A \sp 2}}+
{{7594} \  \%A} -{8239}}, 
\\
\displaystyle
\left.
\left.
{{{12609} \  t}+
{{23} \  { \%A \sp 5}}+
{{49} \  { \%A \sp 4}} -
{{46} \  { \%A \sp 3}}+
{{362} \  { \%A \sp 2}} -
{{5015} \  \%A} -
{8239}} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots=
{{? \sp 5}+{{12} \  {? \sp 3}} -{{16} \  {? \sp 2}}+{{48} \  ?} -{96}}}, 
coordinates=
\left[ {8 \  x}+{ \%A \sp 3}+
\right.
\right.
\\
\displaystyle
\left.
\left.
{8 \   \%A} -8, {{2 \  y} - \%A}, {{2 \  z} - \%A}, {{2 \  t} - \%A} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots=
{{? \sp 5}+{? \sp 4} -{5 \  {? \sp 3}} -{3 \  {? \sp 2}}+{9 \  ?}+3}}, 
coordinates=
\left[ {2 \  x} -{ \%A \sp 3}+
\right.
\right.
\\
\displaystyle
\left.
\left.
{2 \  \%A} -1, 
{{2 \  y}+{ \%A \sp 3} -{4 \  \%A}+1}, {{2 \  z} -{ \%A \sp 3}+
{2 \  \%A} -1}, {{2 \  t} -{ \%A \sp 3}+{2 \  \%A} -1} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots=
{{? \sp 4} -{3 \  {? \sp 3}}+{4 \  {? \sp 2}} -{6 \  ?}+{13}}}, 
coordinates=
\left[ {9 \  x} -{2 \  { \%A \sp 3}}+
\right.
\right.
\\
\displaystyle
{4 \  { \%A \sp 2}} - \%A+2, 
{9 \  y}+{ \%A \sp 3} -
{2 \  { \%A \sp 2}}+
{5 \  \%A} -1, 
{9 \  z}+
{ \%A \sp 3} -
{2 \  { \%A \sp 2}}+
\\
\displaystyle
\left.
\left.
{5 \  \%A} -1, {{9 \  t}+{ \%A \sp 3} -{2 \  { \%A \sp 2}} -{4 \  \%A} -1} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots={{? \sp 4} -{{11} \  {? \sp 2}}+{37}}}, 
coordinates=
\left[ {{3 \  x} -{ \%A \sp 2}+7}, {6 \  y}+{ \%A \sp 2}+
\right.
\right.
\\
\displaystyle
\left.
\left.
{3 \  \%A} -7, {{3 \  z} -{ \%A \sp 2}+7}, 
{{6 \  t}+{ \%A \sp 2} -{3 \   \%A} -7} 
\right]
\right],
\\
\displaystyle
{\left[ {complexRoots={?+1}}, {coordinates=
{\left[ {x -1}, y, {z 
-1}, {t+1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={?+2}}, {coordinates=
{\left[ x, {y -1}, {z -1}, {t+1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={? -2}}, {coordinates=
{\left[ x, {y -1}, {z+1}, {t -1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots=?}, {coordinates=
{\left[ x, {y+1}, {z -1}, {t -1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots={? -2}}, {coordinates=
{\left[ {x -1}, y, {z+1}, {t -1} 
\right]}}
\right]},
\\
\displaystyle
{\left[ {complexRoots=?}, {coordinates=
{\left[ {x+1}, y, {z -1}, {t -1} 
\right]}}
\right]},
\\
\displaystyle
\left[ {complexRoots=
{{? \sp 4}+{5 \  {? \sp 3}}+{{16} \  {? \sp 2}}+{{30} \  ?}+{57}}}, 
coordinates=
\left[ {{{151} \  x}+{15} \  { \%A \sp 3}}+
\right.
\right.
\\
\displaystyle
{{54} \  { \%A \sp 2}}+
{{104} \  \%A}+{93}, 
{{{151} \  y} -{{10} \  { \%A \sp 3}} -
{{36} \  { \%A \sp 2}} -{{19} \  \%A} -
{62}}, 
\\
\displaystyle
\left.
\left.
{{{151} \  z} -{5 \  { \%A \sp 3}} -
{{18} \  { \%A \sp 2}} -{{85} \  \%A} -
{31}}, 
{{{151} \  t} -{5 \  { \%A \sp 3}} -
{{18} \  { \%A \sp 2}} -{{85} \  \%A} 
-{31}} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots={{? \sp 4} -{? \sp 3} -{2 \  {? \sp 2}}+3}}, 
coordinates=
\left[ {x -{ \%A \sp 3}+{2 \  \%A}+1}, 
\right.
\right.
\\
\displaystyle
\left.
\left.
{y+{ \%A \sp 3} - \%A -1}, {z - \%A}, {t+{ \%A \sp 3} - \%A -1} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots=
{{? \sp 4}+{2 \  {? \sp 3}} -{8 \  {? \sp 2}}+{48}}}, 
coordinates=
\left[ {{8 \  x} -{ \%A \sp 3}+{4 \  \%A} -8}, 
\right.
\right.
\\
\displaystyle
\left.
\left.
{{2 \  y}+ \%A}, {{8 \  z}+{ \%A \sp 3} -{8 \  \%A}+8}, 
{{8 \  t} -{ \%A \sp 3}+{4 \  \%A} -8} 
\right]
\right],
\\
\displaystyle
\left[ {complexRoots=
{{? \sp 5}+{? \sp 4} -{2 \  {? \sp 3}} -{4 \  {? \sp 2}}+{5 \  ?}+8}}, 
\right.
\\
\displaystyle
\left.
coordinates=
\left[ 
{{3 \  x}+{ \%A \sp 3} -1}, 
{{3 \  y}+{ \%A \sp 3} -1}, 
{{3 \  z}+{ \%A \sp 3} -1}, 
{t - \%A} 
\right]
\right],
\\
\displaystyle
\left.
\left[ 
{complexRoots={{? \sp 3}+{3 \  ?} -1}}, 
coordinates=
\left[ {x - \%A}, {y - \%A}, {z - \%A}, {t - \%A} 
\right]
\right]
\right]
\end{array}
$$
\returnType{Type: 
List Record(
complexRoots: SparseUnivariatePolynomial Integer,
coordinates: List Polynomial Integer)}

Note that this computation is made from the input system {\bf lf}.

However it is possible to reuse a pre-computed regular chain as follows:

\spadcommand{ts := lts.1  }
$$
\begin{array}{@{}l}
\left\{
{{t \sp 2}+t+1}, 
{{z \sp 3} -z -{t \sp 3}+t}, 
\right.
\\
\\
\displaystyle
\left( {3 \  z}+{3 \  {t \sp 3}} -3 
\right)\  {y \sp 2}+
\left( {3 \  {z \sp 2}}+
\left( {6 \  {t \sp 3}} -6 
\right)\  z+{3 \  {t \sp 6}} -{6 \  {t \sp 3}}+3 
\right)\  y+
\\
\\
\displaystyle
\left.
\left( {3 \  {t \sp 3}} -3 
\right)\  {z \sp 2}+
\left( {3 \  {t \sp 6}} -{6 \  {t \sp 3}}+3 
\right)\  z+
{t \sp 9} -{3 \  {t \sp 6}}+{5 \  {t \sp 3}} -{3 \  t}, 
{x+y+z} 
\right\}
\end{array}
$$
\returnType{Type: RegularChain(Integer,[x,y,z,t])}

\spadcommand{univariateSolve(ts)\$pack  }
$$
\begin{array}{@{}l}
\left[
\left[ 
{complexRoots=
{{? \sp 4}+{5 \  {? \sp 3}}+{{16} \  {? \sp 2}}+{{30} \  ?}+{57}}}, 
p\right.
\right.
\\
\displaystyle
coordinates=
\left[ 
{{{151} \  x}+
{{15} \  { \%A \sp 3}}+
{{54} \  { \%A \sp 2}}+
{{104} \  \%A}+{93}}, 
\right.
\\
\displaystyle
{{151} \  y} -
{{10} \  { \%A \sp 3}} -
{{36} \  { \%A \sp 2}} -
{{19} \  \%A} -{62}, 
\\
\displaystyle
{{{151} \  z} -
{5 \  {  \%A \sp 3}} -
{{18} \  { \%A \sp 2}} -
{{85} \  \%A} -{31}}, 
\\
\displaystyle
\left.
\left.
{{{151} \  t} -
{5 \  { \%A \sp 3}} -
{{18} \  { \%A \sp 2}} -
{{85} \  \%A} -{31}} 
\right]
\right],
\\
\\
\displaystyle
\left[ {complexRoots={{? \sp 4} -{? \sp 3} -{2 \  {? \sp 2}}+3}}, 
\right.
\\
\displaystyle
coordinates=
\left[ 
{x -{ \%A \sp 3}+{2 \  \%A}+1}, 
{y+{ \%A \sp 3} - \%A -1}, 
\right.
\\
\displaystyle
\left.
\left.
{z - \%A}, 
{t+{ \%A \sp 3} - \%A -1} 
\right]
\right],
\\
\\
\displaystyle
\left[ 
{complexRoots={{? \sp 4}+{2 \  {? \sp 3}} -{8 \  {? \sp 2}}+{48}}}, 
\right.
\\
\displaystyle
coordinates=
\left[ 
{{8 \  x} -{ \%A \sp 3}+{4 \  \%A} -8}, 
{{2 \  y}+ \%A}, 
\right.
\\
\displaystyle
\left.
\left.
\left.
{{8 \  z}+{ \%A \sp 3} -{8 \  \%A}+8}, 
{{8 \  t} -{  \%A \sp 3}+{4 \  \%A} -8} 
\right]
\right]
\right]
\end{array}
$$
\returnType{Type: List Record(
complexRoots: SparseUnivariatePolynomial Integer,
coordinates: List Polynomial Integer)}

\spadcommand{realSolve(ts)\$pack   }
$$
\left[
\right]
$$
\returnType{Type: List List RealClosure Fraction Integer}

We compute now the full set of points with real coordinates:

\spadcommand{lr2 := realSolve(lf)\$pack    }
$$
\begin{array}{@{}l}
\left[
{\left[ 0, -1, 1, 1 \right]},
{\left[ 0, 0, 1, 0 \right]},
{\left[ 1, 0, 0, 0 \right]},
{\left[ 0, 0, 0, 1 \right]},
{\left[ 0, 1, 0, 0 \right]},\hbox{\hskip 4.5cm}
\right.
\\
\\
\displaystyle
{\left[ 1, 0, { \%B{37}}, -{ \%B{37}} \right]},
{\left[ 1, 0, { \%B{38}}, -{ \%B{38}} \right]},
\\
\\
\displaystyle
{\left[ 0, 1, { \%B{35}}, -{ \%B{35}} \right]},
{\left[ 0, 1, { \%B{36}}, -{ \%B{36}} \right]},
{\left[ -1, 0, 1, 1 \right]},
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{32}}, 
{{\frac{1}{27}} \  {{ \%B{32}} \sp {15}}}+
{{\frac{2}{27}} \  {{ \%B{32}} \sp {14}}}+
{{\frac{1}{27}} \  {{ \%B{32}} \sp {13}}} -
{{\frac{4}{27}} \  {{ \%B{32}} \sp {12}}} -
{{\frac{11}{27}} \  {{  \%B{32}} \sp {11}}} -
\right.
\\
\\
\displaystyle
{{\frac{4}{27}} \  {{ \%B{32}} \sp {10}}}+
{{\frac{1}{27}} \  {{ \%B{32}} \sp 9}}+
{{\frac{14}{27}} \  {{ \%B{32}} \sp 8}}+
{{\frac{1}{27}} \  {{ \%B{32}} \sp 7}}+
{{\frac{2}{9}} \  {{ \%B{32}} \sp 6}}+
\\
\\
\displaystyle
{{\frac{1}{3}} \  {{ \%B{32}} \sp 5}}+
{{\frac{2}{9}} \  {{ \%B{32}} \sp 4}}+
{{  \%B{32}} \sp 3}+
{{\frac{4}{3}} \  {{ \%B{32}} \sp 2}} -
{ \%B{32}} 
-2, 
\end{array}
$$
$$
\begin{array}{@{}l}
-{{\frac{1}{54}} \  {{ \%B{32}} \sp {15}}} -\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{32}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{32}} \sp {13}}}+
{{\frac{2}{27}} \  {{  \%B{32}} \sp {12}}}+
{{\frac{11}{54}} \  {{ \%B{32}} \sp {11}}}+
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{32}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{32}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{32}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{32}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{32}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{32}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{32}} \sp 4}} -
{{ \%B{32}} \sp 3} -{{\frac{2}{3}} \  
{{  \%B{32}} \sp 2}}+
{{\frac{1}{2}} \  { \%B{32}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
-{{\frac{1}{54}} \  {{ \%B{32}} \sp {15}}} -\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{32}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{32}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{32}} \sp {12}}}+
{{\frac{11}{54}} \  {{ \%B{32}} \sp {11}}}+
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{  \%B{32}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{32}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{32}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{32}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{32}} \sp 6}} -
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{32}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{32}} \sp 4}} -
{{ \%B{32}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{32}} \sp 2}}+
{{\frac{1}{2}} \  { \%B{32}}}+
{\frac{3}{2}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{33}}, 
{{\frac{1}{27}} \  {{ \%B{33}} \sp {15}}}+
{{\frac{2}{27}} \  {{ \%B{33}} \sp {14}}}+
{{\frac{1}{27}} \  {{ \%B{33}} \sp {13}}} -
{{\frac{4}{27}} \  {{ \%B{33}} \sp {12}}} -
{{\frac{11}{27}} \  {{  \%B{33}} \sp {11}}} -
\right.
\\
\\
\displaystyle
{{\frac{4}{27}} \  {{ \%B{33}} \sp {10}}}+
{{\frac{1}{27}} \  {{ \%B{33}} \sp 9}}+
{{\frac{14}{27}} \  {{ \%B{33}} \sp 8}}+
{{\frac{1}{27}} \  {{ \%B{33}} \sp 7}}+
{{\frac{2}{9}} \  {{ \%B{33}} \sp 6}}+
\\
\\
\displaystyle
{{\frac{1}{3}} \  {{ \%B{33}} \sp 5}}+
{{\frac{2}{9}} \  {{ \%B{33}} \sp 4}}+
{{  \%B{33}} \sp 3}+
{{\frac{4}{3}} \  {{ \%B{33}} \sp 2}} -
{ \%B{33}} -2, 
\end{array}
$$
$$
\begin{array}{@{}l}
-{{\frac{1}{54}} \  {{ \%B{33}} \sp {15}}} -\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{33}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{33}} \sp {13}}}+
{{\frac{2}{27}} \  {{  \%B{33}} \sp {12}}}+
{{\frac{11}{54}} \  {{ \%B{33}} \sp {11}}}+
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{33}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{33}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{33}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{33}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{33}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{33}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{33}} \sp 4}} -
{{ \%B{33}} \sp 3} -
{{\frac{2}{3}} \  {{  \%B{33}} \sp 2}}+
{{\frac{1}{2}} \  { \%B{33}}}+{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
-{{\frac{1}{54}} \  {{ \%B{33}} \sp {15}}} -\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{33}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{33}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{33}} \sp {12}}}+
{{\frac{11}{54}} \  {{ \%B{33}} \sp {11}}}+
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{  \%B{33}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{33}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{33}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{33}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{33}} \sp 6}} -
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{33}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{33}} \sp 4}} -
{{ \%B{33}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{33}} \sp 2}}+
{{\frac{1}{2}} \  { \%B{33}}}+
{\frac{3}{2}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{34}}, 
{{\frac{1}{27}} \  {{ \%B{34}} \sp {15}}}+
{{\frac{2}{27}} \  {{ \%B{34}} \sp {14}}}+
{{\frac{1}{27}} \  {{ \%B{34}} \sp {13}}} -
{{\frac{4}{27}} \  {{ \%B{34}} \sp {12}}} -
{{\frac{11}{27}} \  {{  \%B{34}} \sp {11}}} -
\right.
\\
\\
\displaystyle
{{\frac{4}{27}} \  {{ \%B{34}} \sp {10}}}+
{{\frac{1}{27}} \  {{ \%B{34}} \sp 9}}+
{{\frac{14}{27}} \  {{ \%B{34}} \sp 8}}+
{{\frac{1}{27}} \  {{ \%B{34}} \sp 7}}+
{{\frac{2}{9}} \  {{ \%B{34}} \sp 6}}+
\\
\\
\displaystyle
{{\frac{1}{3}} \  {{ \%B{34}} \sp 5}}+
{{\frac{2}{9}} \  {{ \%B{34}} \sp 4}}+
{{  \%B{34}} \sp 3}+
{{\frac{4}{3}} \  {{ \%B{34}} \sp 2}} -
{ \%B{34}} -2, 
\end{array}
$$
$$
\begin{array}{@{}l}
-{{\frac{1}{54}} \  {{ \%B{34}} \sp {15}}} -\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{34}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{34}} \sp {13}}}+
{{\frac{2}{27}} \  {{  \%B{34}} \sp {12}}}+
{{\frac{11}{54}} \  {{ \%B{34}} \sp {11}}}+
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{34}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{34}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{34}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{34}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{34}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{34}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{34}} \sp 4}} -
{{ \%B{34}} \sp 3} -
{{\frac{2}{3}} \  {{  \%B{34}} \sp 2}}+
{{\frac{1}{2}} \  { \%B{34}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
-{{\frac{1}{54}} \  {{ \%B{34}} \sp {15}}} -\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{34}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{34}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{34}} \sp {12}}}+
{{\frac{11}{54}} \  {{ \%B{34}} \sp {11}}}+
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{  \%B{34}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{34}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{34}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{34}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{34}} \sp 6}} -
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{34}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{34}} \sp 4}} -
{{ \%B{34}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{34}} \sp 2}}+
{{\frac{1}{2}} \  { \%B{34}}}+
{\frac{3}{2}}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
{\left[ -1, 1, 0, 1 \right]},
{\left[ -1, 1, 1, 0 \right]},
\\
\\
\displaystyle
\left[ 
{ \%B{23}}, 
-{{\frac{1}{54}} \  {{ \%B{23}} \sp {15}}} -
{{\frac{1}{27}} \  {{ \%B{23}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{23}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{23}} \sp {12}}}+
{{\frac{11}{54}} \  {{  \%B{23}} \sp {11}}}+
\right.
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{23}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{23}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{23}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{23}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{23}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{23}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{23}} \sp 4}} -
{{  \%B{23}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{23}} \sp 2}}+
{{\frac{1}{2}} \  {  \%B{23}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{ \%B{30}}, 
-{ \%B{30}}+
{{\frac{1}{54}} \  {{  \%B{23}} \sp {15}}}+\hbox{\hskip 1.0cm}
{{\frac{1}{27}} \  {{ \%B{23}} \sp {14}}}+
{{\frac{1}{54}} \  {{ \%B{23}} \sp {13}}} -
{{\frac{2}{27}} \  {{ \%B{23}} \sp {12}}} -
{{\frac{11}{54}} \  {{ \%B{23}} \sp {11}}} -
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{23}} \sp {10}}}+
{{\frac{1}{54}} \  {{ \%B{23}} \sp 9}}+
{{\frac{7}{27}} \  {{ \%B{23}} \sp 8}}+
{{\frac{1}{54}} \  {{ \%B{23}} \sp 7}}+
{{\frac{1}{9}} \  {{ \%B{23}} \sp 6}}+
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{23}} \sp 5}}+
{{\frac{1}{9}} \  {{ \%B{23}} \sp 4}}+
{{\frac{2}{3}} \  {{ \%B{23}} \sp 2}} -
{{\frac{1}{2}} \  { \%B{23}}} -
{\frac{1}{2}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{23}}, 
-{{\frac{1}{54}} \  {{ \%B{23}} \sp {15}}} -
{{\frac{1}{27}} \  {{ \%B{23}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{23}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{23}} \sp {12}}}+
{{\frac{11}{54}} \  {{  \%B{23}} \sp {11}}}+
\right.
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{23}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{23}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{23}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{23}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{23}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{23}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{23}} \sp 4}} -
{{  \%B{23}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{23}} \sp 2}}+
{{\frac{1}{2}} \  {  \%B{23}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{ \%B{31}}, 
-{ \%B{31}}+{{\frac{1}{54}} \  {{  \%B{23}} \sp {15}}}+
{{\frac{1}{27}} \  {{ \%B{23}} \sp {14}}}+
{{\frac{1}{54}} \  {{ \%B{23}} \sp {13}}} -
{{\frac{2}{27}} \  {{ \%B{23}} \sp {12}}} -
\\
\\
\displaystyle
{{\frac{11}{54}} \  {{ \%B{23}} \sp {11}}} -
{{\frac{2}{27}} \  {{ \%B{23}} \sp {10}}}+
{{\frac{1}{54}} \  {{ \%B{23}} \sp 9}}+
{{\frac{7}{27}} \  {{ \%B{23}} \sp 8}}+
{{\frac{1}{54}} \  {{ \%B{23}} \sp 7}}+
\\
\\
\displaystyle
\left.
{{\frac{1}{9}} \  {{ \%B{23}} \sp 6}}+
{{\frac{1}{6}} \  {{ \%B{23}} \sp 5}}+
{{\frac{1}{9}} \  {{ \%B{23}} \sp 4}}+
{{\frac{2}{3}} \  {{ \%B{23}} \sp 2}} -
{{\frac{1}{2}} \  { \%B{23}}} -
{\frac{1}{2}} 
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{24}}, 
-{{\frac{1}{54}} \  {{ \%B{24}} \sp {15}}} -
{{\frac{1}{27}} \  {{ \%B{24}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{24}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{24}} \sp {12}}}+
{{\frac{11}{54}} \  {{  \%B{24}} \sp {11}}}+
\right.
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{24}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{24}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{24}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{24}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{24}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{24}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{24}} \sp 4}} -
{{  \%B{24}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{24}} \sp 2}}+
{{\frac{1}{2}} \  {  \%B{24}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{ \%B{28}}, 
-{ \%B{28}}+{{\frac{1}{54}} \  {{  \%B{24}} \sp {15}}}+
{{\frac{1}{27}} \  {{ \%B{24}} \sp {14}}}+
{{\frac{1}{54}} \  {{ \%B{24}} \sp {13}}} -
{{\frac{2}{27}} \  {{ \%B{24}} \sp {12}}} -
{{\frac{11}{54}} \  {{ \%B{24}} \sp {11}}} -
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{24}} \sp {10}}}+
{{\frac{1}{54}} \  {{ \%B{24}} \sp 9}}+
{{\frac{7}{27}} \  {{ \%B{24}} \sp 8}}+
{{\frac{1}{54}} \  {{ \%B{24}} \sp 7}}+
{{\frac{1}{9}} \  {{ \%B{24}} \sp 6}}+
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{24}} \sp 5}}+
{{\frac{1}{9}} \  {{ \%B{24}} \sp 4}}+
{{\frac{2}{3}} \  {{ \%B{24}} \sp 2}} -
{{\frac{1}{2}} \  { \%B{24}}} -
{\frac{1}{2}}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{24}}, 
-{{\frac{1}{54}} \  {{ \%B{24}} \sp {15}}} -
{{\frac{1}{27}} \  {{ \%B{24}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{24}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{24}} \sp {12}}}+
{{\frac{11}{54}} \  {{  \%B{24}} \sp {11}}}+
\right.
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{24}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{24}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{24}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{24}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{24}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{24}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{24}} \sp 4}} -
{{  \%B{24}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{24}} \sp 2}}+
{{\frac{1}{2}} \  {  \%B{24}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{ \%B{29}}, 
-{ \%B{29}}+
{{\frac{1}{54}} \  {{  \%B{24}} \sp {15}}}+
{{\frac{1}{27}} \  {{ \%B{24}} \sp {14}}}+
{{\frac{1}{54}} \  {{ \%B{24}} \sp {13}}} -
{{\frac{2}{27}} \  {{ \%B{24}} \sp {12}}} -
{{\frac{11}{54}} \  {{ \%B{24}} \sp {11}}} -
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{24}} \sp {10}}}+
{{\frac{1}{54}} \  {{ \%B{24}} \sp 9}}+
{{\frac{7}{27}} \  {{ \%B{24}} \sp 8}}+
{{\frac{1}{54}} \  {{ \%B{24}} \sp 7}}+
{{\frac{1}{9}} \  {{ \%B{24}} \sp 6}}+
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{24}} \sp 5}}+
{{\frac{1}{9}} \  {{ \%B{24}} \sp 4}}+
{{\frac{2}{3}} \  {{ \%B{24}} \sp 2}} -
{{\frac{1}{2}} \  { \%B{24}}} -
{\frac{1}{2}}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{25}}, 
-{{\frac{1}{54}} \  {{ \%B{25}} \sp {15}}} -
{{\frac{1}{27}} \  {{ \%B{25}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{25}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{25}} \sp {12}}}+
{{\frac{11}{54}} \  {{  \%B{25}} \sp {11}}}+
\right.
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{25}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{25}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{25}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{25}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{25}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{25}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{25}} \sp 4}} -
{{  \%B{25}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{25}} \sp 2}}+
{{\frac{1}{2}} \  {  \%B{25}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{ \%B{26}}, 
-{ \%B{26}}+
{{\frac{1}{54}} \  {{  \%B{25}} \sp {15}}}+
{{\frac{1}{27}} \  {{ \%B{25}} \sp {14}}}+
{{\frac{1}{54}} \  {{ \%B{25}} \sp {13}}} -
{{\frac{2}{27}} \  {{ \%B{25}} \sp {12}}} -
{{\frac{11}{54}} \  {{ \%B{25}} \sp {11}}} -
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{25}} \sp {10}}}+
{{\frac{1}{54}} \  {{ \%B{25}} \sp 9}}+
{{\frac{7}{27}} \  {{ \%B{25}} \sp 8}}+
{{\frac{1}{54}} \  {{ \%B{25}} \sp 7}}+
{{\frac{1}{9}} \  {{ \%B{25}} \sp 6}}+
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{25}} \sp 5}}+
{{\frac{1}{9}} \  {{ \%B{25}} \sp 4}}+
{{\frac{2}{3}} \  {{ \%B{25}} \sp 2}} -
{{\frac{1}{2}} \  { \%B{25}}} -
{\frac{1}{2}}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
\left[ 
{ \%B{25}}, 
-{{\frac{1}{54}} \  {{ \%B{25}} \sp {15}}} -
{{\frac{1}{27}} \  {{ \%B{25}} \sp {14}}} -
{{\frac{1}{54}} \  {{ \%B{25}} \sp {13}}}+
{{\frac{2}{27}} \  {{ \%B{25}} \sp {12}}}+
{{\frac{11}{54}} \  {{  \%B{25}} \sp {11}}}+
\right.
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{25}} \sp {10}}} -
{{\frac{1}{54}} \  {{ \%B{25}} \sp 9}} -
{{\frac{7}{27}} \  {{ \%B{25}} \sp 8}} -
{{\frac{1}{54}} \  {{ \%B{25}} \sp 7}} -
{{\frac{1}{9}} \  {{ \%B{25}} \sp 6}} -
\\
\\
\displaystyle
{{\frac{1}{6}} \  {{ \%B{25}} \sp 5}} -
{{\frac{1}{9}} \  {{ \%B{25}} \sp 4}} -
{{  \%B{25}} \sp 3} -
{{\frac{2}{3}} \  {{ \%B{25}} \sp 2}}+
{{\frac{1}{2}} \  {  \%B{25}}}+
{\frac{3}{2}}, 
\end{array}
$$
$$
\begin{array}{@{}l}
{ \%B{27}}, 
-{ \%B{27}}+
{{\frac{1}{54}} \  {{  \%B{25}} \sp {15}}}+
{{\frac{1}{27}} \  {{ \%B{25}} \sp {14}}}+
{{\frac{1}{54}} \  {{ \%B{25}} \sp {13}}} -
{{\frac{2}{27}} \  {{ \%B{25}} \sp {12}}} -
{{\frac{11}{54}} \  {{ \%B{25}} \sp {11}}} -
\\
\\
\displaystyle
{{\frac{2}{27}} \  {{ \%B{25}} \sp {10}}}+
{{\frac{1}{54}} \  {{ \%B{25}} \sp 9}}+
{{\frac{7}{27}} \  {{ \%B{25}} \sp 8}}+
{{\frac{1}{54}} \  {{ \%B{25}} \sp 7}}+
{{\frac{1}{9}} \  {{ \%B{25}} \sp 6}}+
\\
\\
\displaystyle
\left.
{{\frac{1}{6}} \  {{ \%B{25}} \sp 5}}+
{{\frac{1}{9}} \  {{ \%B{25}} \sp 4}}+
{{\frac{2}{3}} \  {{ \%B{25}} \sp 2}} -
{{\frac{1}{2}} \  { \%B{25}}} -
{\frac{1}{2}}
\right],
\end{array}
$$
$$
\begin{array}{@{}l}
{\left[ 1, { \%B{21}}, -{ \%B{21}}, 0 \right]},
{\left[ 1, { \%B{22}}, -{ \%B{22}}, 0 \right]},
{\left[ 1, { \%B{19}}, 0, -{ \%B{19}} \right]},
{\left[ 1, { \%B{20}}, 0, -{ \%B{20}} \right]},
\\
\\
\displaystyle
\left[ 
{ \%B{17}}, 
-{{\frac{1}{3}} \  {{ \%B{17}} \sp 3}}+{\frac{1}{3}}, 
-{{\frac{1}{3}} \  {{ \%B{17}} \sp 3}}+{\frac{1}{3}}, 
-{{\frac{1}{3}} \  {{ \%B{17}} \sp 3}}+{\frac{1}{3}}
\right],
\\
\\
\displaystyle
\left.
\left[ 
{ \%B{18}}, 
{-{{\frac{1}{3}} \  {{ \%B{18}} \sp 3}}+{\frac{1}{3}}}, 
{-{{\frac{1}{3}} \  {{ \%B{18}} \sp 3}}+{\frac{1}{3}}}, 
{-{{\frac{1}{3}} \  {{ \%B{18}} \sp 3}}+{\frac{1}{3}}} 
\right]
\right]
\end{array}
$$
\returnType{Type: List List RealClosure Fraction Integer}

The number of real solutions for the input system is:

\spadcommand{\#lr2 }
$$
27 
$$
\returnType{Type: PositiveInteger}

Another example of computation of real solutions illustrates the 
{\tt LexTriangularPackage} package constructor.

We concentrate now on the solutions with real (strictly) positive
coordinates:

\spadcommand{lpr2 := positiveSolve(lf)\$pack   }
$$
\left[
{\left[ { \%B{40}}, {-{{\frac{1}{3}} \  {{ \%B{40}} \sp 3}}+{\frac{1}{3}}}, 
{-{{\frac{1}{3}} \  {{ \%B{40}} \sp 3}}+{\frac{1}{3}}}, {-{{\frac{1}{3}} \  {{ 
 \%B{40}} \sp 3}}+{\frac{1}{3}}} 
\right]}
\right]
$$
\returnType{Type: List List RealClosure Fraction Integer}

Finally, we approximate the coordinates of this point with 20 exact digits:

\spadcommand{[approximate(r,1/10**21)::Float for r in lpr2.1] }
$$
\begin{array}{@{}l}
\left[
{0.3221853546\ 2608559291}, 
{0.3221853546\ 2608559291}, 
\right.
\\
\displaystyle
\left.
{0.3221853546\ 2608559291}, 
{0.3221853546 2608559291} 
\right]
\end{array}
$$
\returnType{Type: List Float}


%Original Page 483

\chapter{Interactive Programming}
\label{ugIntProg}

Programming in the interpreter is easy.
So is the use of Axiom's graphics facility.
Both are rather flexible and allow you to use them for many
interesting applications.
However, both require learning some basic ideas and skills.

All graphics examples in the gallery section are either
produced directly by interactive commands or by interpreter
programs.
Four of these programs are introduced here.
By the end of this chapter you will know enough about graphics and
programming in the interpreter to not only understand all these
examples, but to tackle interesting and difficult problems on your
own.
The appendix on graphics lists all the remaining commands and
programs used to create these images.

\section{Drawing Ribbons Interactively}
\label{ugIntProgDrawing}

We begin our discussion of interactive graphics with the creation
of a useful facility: plotting ribbons of two-graphs in
three-space.
Suppose you want to draw the two-di\-men\-sion\-al graphs of $n$
functions $f_i(x), 1 \leq i \leq n,$ all over some fixed range of $x$.
One approach is to create a two-di\-men\-sion\-al graph for each one, then
superpose one on top of the other.
What you will more than likely get is a jumbled mess.
Even if you make each function a different color, the result is
likely to be confusing.

A better approach is to display each of the $f_i(x)$ in three
\index{ribbon}
dimensions as a ``ribbon'' of some appropriate width along the
$y$-direction, laying down each  ribbon next to the
previous one.
A ribbon is simply a function of $x$ and $y$ depending
only on $x$.

%Original Page 484

We illustrate this for $f_i(x)$ defined as simple powers of
$x$ for $x$ ranging between $-1$ and $1$.

Draw the ribbon for $z = x^2$.

\spadgraph{draw(x**2,x=-1..1,y=0..1)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbon1.eps}}
\begin{center}
$x^2,x=-1..1,y=0..1$
\end{center}
\end{minipage}

Now that was easy!
What you get is a ``wire-mesh'' rendition of the ribbon.
That's fine for now.
Notice that the mesh-size is small in both the $x$ and the
$y$ directions.
Axiom normally computes points in both these directions.
This is unnecessary.
One step is all we need in the $y$-direction.
To have Axiom economize on $y$-points, we re-draw the
ribbon with option $var2Steps == 1$.

Re-draw the ribbon, but with option $var2Steps == 1$
so that only $1$ step is computed in the
$y$ direction.

\spadgraph{vp := draw(x**2,x=-1..1,y=0..1,var2Steps==1) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbon2.eps}}
\begin{center}
$x^2, x=-1..1,y=0..1, var2Steps==1$
\end{center}
\end{minipage}

The operation has created a viewport, that is, a graphics window
on your screen.
We assigned the viewport to $vp$ and now we manipulate
its contents.


Graphs are objects, like numbers and algebraic expressions.
You may want to do some experimenting with graphs.
For example, say
\begin{verbatim}
showRegion(vp, "on")
\end{verbatim}
to put a bounding box around the ribbon.
Try it!
Issue $rotate(vp, -45, 90)$ to rotate the
figure $-45$ longitudinal degrees and $90$ latitudinal
degrees.

%Original Page 485

Here is a different rotation.
This turns the graph so you can view it along the $y$-axis.

\spadcommand{rotate(vp, 0, -90)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbon2r.eps}}
\begin{center}
$rotate(vp, 0, -90)$
\end{center}
\end{minipage}

There are many other things you can do.
In fact, most everything you can do interactively using the
three-di\-men\-sion\-al control panel (such as translating, zooming, resizing,
coloring, perspective and lighting selections) can also be done
directly by operations (see \sectionref{ugGraph} for more details).

When you are done experimenting, say $reset(vp)$ to restore the
picture to its original position and settings.


Let's add another ribbon to our picture---one
for $x^3$.
Since $y$ ranges from $0$ to $1$ for the
first ribbon, now let $y$ range from $1$ to
$2$.
This puts the second ribbon next to the first one.

How do you add a second ribbon to the viewport?
One method is
to extract the ``space'' component from the
viewport using the operation
\spadfunFrom{subspace}{ThreeDimensionalViewport}.
You can think of the space component as the object inside the
window (here, the ribbon).
Let's call it $sp$.
To add the second ribbon, you draw the second ribbon using the
option $space == sp$.

Extract the space component of $vp$.

\spadcommand{sp := subspace(vp)}

%Original Page 486

Add the ribbon for
$x^3$ alongside that for
$x^2$.

\spadgraph{vp := draw(x**3,x=-1..1,y=1..2,var2Steps==1, space==sp)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbons.eps}}
\begin{center}
$x^3, x=-1..1, y=1..2, var2Steps==1, space==sp$
\end{center}
\end{minipage}

Unless you moved the original viewport, the new viewport covers
the old one.
You might want to check that the old object is still there by
moving the top window.

Let's show quadrilateral polygon outlines on the ribbons and then
enclose the ribbons in a box.

Show quadrilateral polygon outlines.

\spadcommand{drawStyle(vp,"shade");outlineRender(vp,"on")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbons2.eps}}
\begin{center}
$drawStyle(vp,"shade");outlineRender(vp,"on")$
\end{center}
\end{minipage}

Enclose the ribbons in a box.

\spadcommand{rotate(vp,20,-60); showRegion(vp,"on")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbons2b.eps}}
\begin{center}
$rotate(vp,20,-60); showRegion(vp,"on")$
\end{center}
\end{minipage}

%Original Page 487

This process has become tedious!
If we had to add two or three more ribbons, we would have to
repeat the above steps several more times.
It is time to write an interpreter program to help us take care of
the details.
\vfill
\newpage
\section{A Ribbon Program}
\label{ugIntProgRibbon}

The above approach creates a new viewport for each additional ribbon.
A better approach is to build one object composed of all ribbons
before creating a viewport.  To do this, use {\bf makeObject} rather
than {\bf draw}.  The operations have similar formats, but {\bf draw}
returns a viewport and {\bf makeObject} returns a space object.

We now create a function {\bf drawRibbons} of two arguments:
$flist$, a list of formulas for the ribbons you want to draw,
and $xrange$, the range over which you want them drawn.
Using this function, you can just say
\begin{verbatim}
drawRibbons([x**2, x**3], x=-1..1)
\end{verbatim}
to do all of the work required in the last section.
Here is the {\bf drawRibbons} program.
Invoke your favorite editor and create a file called {\bf ribbon.input}
containing the following program.

\begin{figure}
\line(1,0){380}
\begin{verbatim}
drawRibbons(flist, xrange) ==
  sp := createThreeSpace()                     Create empty space $sp$.
  y0 := 0                                      The initial ribbon position.
  for f in flist repeat                        For each function $f$,
    makeObject(f, xrange, y=y0..y0+1,          create and add a ribbon
       space==sp, var2Steps == 1)              for $f$ to the space $sp$.
    y0 := y0 + 1                               The next ribbon position.
  vp := makeViewport3D(sp, "Ribbons")          Create viewport.
  drawStyle(vp, "shade")                       Select shading style.
  outlineRender(vp, "on")                      Show polygon outlines.
  showRegion(vp,"on")                          Enclose in a box.
  n := # flist                                 The number of ribbons
  zoom(vp,n,1,n)                               Zoom in x- and z-directions.
  rotate(vp,0,75)                              Change the angle of view.
  vp                                           Return the viewport.
\end{verbatim}
\caption{The first {\bf drawRibbons} function.}
\label{fig-ribdraw1}
\line(1,0){380}
\end{figure}

Here are some remarks on the syntax used in the {\bf drawRibbons} function
(consult \sectionref{ugUser} for more details).
Unlike most other programming languages which use semicolons,
parentheses, or {\it begin}--{\it end} brackets to delineate the
structure of programs, the structure of an Axiom program is
determined by indentation.
The first line of the function definition always begins in column 1.
All other lines of the function are indented with respect to the first
line and form a {\it pile} (see \sectionref{ugLangBlocks}).

%Original Page 488

The definition of {\bf drawRibbons}
consists of a pile of expressions to be executed one after
another.
Each expression of the pile is indented at the same level.
Lines 4-7 designate one single expression:
since lines 5-7 are indented with respect to the others, these
lines are treated as a continuation of line 4.
Also since lines 5 and 7 have the same indentation level, these
lines designate a pile within the outer pile.

The last line of a pile usually gives the value returned by the
pile.
Here it is also the value returned by the function.
Axiom knows this is the last line of the function because it
is the last line of the file.
In other cases, a new expression beginning in column one signals
the end of a function.

The line {\bf drawStyle}{\tt (vp,"shade")} is given after the viewport
has been created to select the draw style.
We have also used the \spadfunFrom{zoom}{ThreeDimensionalViewport}
option.
Without the zoom, the viewport region would be scaled equally in
all three coordinate directions.

Let's try the function {\bf drawRibbons}.
First you must read the file to give Axiom the function definition.

Read the input file.

\spadcommand{)read ribbon }

Draw ribbons for $x, x^2,\dots, x^5$
for $-1 \leq x \leq 1$

\spadgraph{drawRibbons([x**i for i in 1..5],x=-1..1) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/ribbons5.eps}}
\begin{center}
$[x^i {rm\ for\ i\ in\ 1..5}], x=-1..1$
\end{center}
\end{minipage}

\section{Coloring and Positioning Ribbons}
\label{ugIntProgColor}
%

Before leaving the ribbon example, we  make two improvements.
Normally, the color given to each point in the space is a
function of its height within a bounding box.
The points at the bottom of the
box are red, those at the top are purple.

To change the normal coloring, you can give
an option $colorFunction == {\it function}$.
When Axiom goes about displaying the data, it
determines the range of colors used for all points within the box.
Axiom then distributes these numbers uniformly over the number of hues.
Here we use the simple color function
$(x,y) \mapsto i$ for the
$i$-th ribbon.

Also, we add an argument $yrange$ so you can give the range of
$y$ occupied by the ribbons.
For example, if the $yrange$ is given as
$y=0..1$ and there are $5$ ribbons to be displayed, each
ribbon would have width $0.2$ and would appear in the
range $0 \leq y \leq 1$.

Refer to lines 4-9.
Line 4 assigns to $yVar$ the variable part of the
$yrange$ (after all, it need not be $y$).
Suppose that $yrange$ is given as $t = a..b$ where $a$ and
$b$ have numerical values.
Then line 5 assigns the value of $a$ to the variable $y0$.
Line 6 computes the width of the ribbon by dividing the difference of
$a$ and $b$ by the number, $num$, of ribbons.
The result is assigned to the variable $width$.
Note that in the for-loop in line 7, we are iterating in parallel; it is
not a nested loop.

%Original Page 489

\begin{figure}
\line(1,0){380}
\begin{verbatim}
drawRibbons(flist, xrange, yrange) ==
  sp := createThreeSpace()                     Create empty space $sp$.
  num := # flist                               The number of ribbons.
  yVar := variable yrange                      The ribbon variable.
  y0:Float    := lo segment yrange             The first ribbon coordinate.
  width:Float := (hi segment yrange - y0)/num  The width of a ribbon.
  for f in flist for color in 1..num repeat    For each function $f$,
    makeObject(f, xrange, yVar = y0..y0+width, create and add ribbon to
      var2Steps == 1, colorFunction == (x,y) +-> color, _
      space == sp)                             $sp$ of a different color.
    y0 := y0 + width                           The next ribbon coordinate.
  vp := makeViewport3D(sp, "Ribbons")          Create viewport.
  drawStyle(vp, "shade")                       Select shading style.
  outlineRender(vp, "on")                      Show polygon outlines.
  showRegion(vp, "on")                         Enclose in a box.
  vp                                           Return the viewport.
\end{verbatim}
\hrule
\caption{The final {\bf drawRibbons} function.}
\label{fig-ribdraw2}
\line(1,0){380}
\end{figure}

\section{Points, Lines, and Curves}
\label{ugIntProgPLC}
%
What you have seen so far is a high-level program using the
graphics facility.
We now turn to the more basic notions of points, lines, and curves
in three-di\-men\-sion\-al graphs.
These facilities use small floats (objects
of type {\tt DoubleFloat}) for data.
Let us first give names to the small float values $0$ and
$1$.

The small float 0.

\spadcommand{zero := 0.0@DFLOAT }

The small float 1.

\spadcommand{one  := 1.0@DFLOAT }

The {\tt @} sign means ``of the type.'' Thus $zero$ is
$0.0$ of the type {\tt DoubleFloat}.
You can also say $0.0::DFLOAT$.

%Original Page 490

Points can have four small float components: $x, y, z$ coordinates and an
optional color.
A ``curve'' is simply a list of points connected by straight line
segments.

Create the point $origin$ with color zero, that is, the lowest color
on the color map.

\spadcommand{origin := point [zero,zero,zero,zero] }

Create the point $unit$ with color zero.

\spadcommand{unit := point [one,one,one,zero] }

Create the curve (well, here, a line) from
$origin$ to $unit$.

\spadcommand{line := [origin, unit]  }


We make this line segment into an arrow by adding an arrowhead.
The arrowhead extends to,
say, $p3$ on the left, and to, say, $p4$ on the right.
To describe an arrow, you tell Axiom to draw the two curves
$[p1, p2, p3]$ and $[p2, p4].$
We also decide through experimentation on
values for $arrowScale$, the ratio of the size of
the arrowhead to the stem of the arrow, and $arrowAngle$,
the angle between the arrowhead and the arrow.

Invoke your favorite editor and create
an input file called {\bf arrows.input}.

This input file first defines the values of
%$origin$,$unit$,
$arrowAngle$ and $arrowScale$, then
defines the function {\bf makeArrow}$(p_1, p_2)$ to
draw an arrow from point $p_1$ to $p_2$.

\line(1,0){380}
\begin{verbatim}
arrowAngle := %pi-%pi/10.0@DFLOAT              The angle of the arrowhead.
arrowScale := 0.2@DFLOAT                       The size of the arrowhead
                                               relative to the stem.
makeArrow(p1, p2) ==
  delta := p2 - p1                             The arrow.
  len := arrowScale * length delta             length of the arrowhead.
  theta := atan(delta.1, delta.2)              angle from the x-axis
  c1 := len*cos(theta + arrowAngle)            x-coord of left endpoint
  s1 := len*sin(theta + arrowAngle)            y-coord of left endpoint
  c2 := len*cos(theta - arrowAngle)            x-coord of right endpoint
  s2 := len*sin(theta - arrowAngle)            y-coord of right endpoint
  z  := p2.3*(1 - arrowScale)                  z-coord of both endpoints
  p3 := point [p2.1 + c1, p2.2 + s1, z, p2.4]  left endpoint of head
  p4 := point [p2.1 + c2, p2.2 + s2, z, p2.4]  right endpoint of head
  [ [p1, p2, p3], [p2, p4] ]                   arrow as a list of curves
\end{verbatim}
\line(1,0){380}

%Original Page 491

Read the file and then create
an arrow from the point $origin$ to the point $unit$.

Read the input file defining {\bf makeArrow}.

\spadcommand{)read arrows}

Construct the arrow (a list of two curves).

\spadcommand{arrow := makeArrow(origin,unit)}
\[
\left[
 \left[
  \left[0.0, 0.0, 0.0, 0.0\right],
  \left[1.0, 1.0, 1.0, 1.0\right],
 \right.
\right.
\]
\[
\left.
 \left.
  \left[0.69134628604607973, 
        0.842733077659504,
        0.80000000000000004,
        0.0
  \right]
 \right],
\right.
\]
\[
\left.
 \left[
  \left[1.0, 1.0, 1.0, 1.0
  \right],
  \left[0.842733077659504,
        0.69134628604607973,
        0.80000000000000004, 
        0.0
  \right]
 \right]
\right]
\]
\returnType{Type: List List Point DoubleFloat}

Create an empty object $sp$ of type $ThreeSpace$.

\spadcommand{sp := createThreeSpace()}
\returnType{Type: ThreeSpace DoubleFloat}

Add each curve of the arrow to the space $sp$.

\spadcommand{for a in arrow repeat sp := curve(sp,a)}
\returnType{Type: Void}

Create a three-di\-men\-sion\-al viewport containing that space.

\spadgraph{vp := makeViewport3D(sp,"Arrow")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/arrow.eps}}
\begin{center}
$makeViewport3D(sp,"Arrow")$
\end{center}
\end{minipage}

Here is a better viewing angle.

\spadcommand{rotate(vp,200,-60)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/arrowr.eps}}
\begin{center}
$rotate(vp,200,-60)$
\end{center}
\end{minipage}

%Original Page 492

\section{A Bouquet of Arrows}
\label{ugIntProgColorArr}

%Axiom gathers up all the points of a graph and looks at the range
%of color values given as integers.
%If theses color values range from a minimum value of $a$ to a maximum
%value of $b$, then the $a$ values are colored red (the
%lowest color in our spectrum), and $b$ values are colored
%purple (the highest color), and those in the middle are colored
%green.
%When all the points are the same color as above, Axiom
%chooses green.

Let's draw a ``bouquet'' of arrows.
Each arrow is identical. The arrowheads are
uniformly placed on a circle parallel to the $xy$-plane.
Thus the position of each arrow differs only
by the angle $\theta$,
$0 \leq \theta < 2\pi$,
between the arrow and
the $x$-axis on the $xy$-plane.

Our bouquet is rather special: each arrow has a different
color (which won't be evident here, unfortunately).
This is arranged by letting the color of each successive arrow be
denoted by $\theta$.
In this way, the color of arrows ranges from red to green to violet.
Here is a program to draw a bouquet of $n$ arrows.

\line(1,0){380}
\begin{verbatim}
drawBouquet(n,title) ==
  angle := 0.0@DFLOAT                          The initial angle
  sp := createThreeSpace()                     Create empty space $sp$
  for i in 0..n-1 repeat                       For each index i, create:
    start := point [0.0@DFLOAT,0.0@DFLOAT,0.0@DFLOAT,angle] 
                                               the point at base of arrow;
    end   := point [cos angle, sin angle, 1.0@DFLOAT, angle]
                                               the point at tip of arrow;
    arrow := makeArrow(start,end)              the $i$th arrow
    for a in makeArrow(start,end) repeat       For each arrow component,
      curve(sp,a)                              add the component to $sp$
    angle := angle + 2*%pi/n                   The next angle
  makeViewport3D(sp,title)                     Create the viewport from $sp$
\end{verbatim}
\line(1,0){380}

Read the input file.

\spadcommand{)read bouquet}

A bouquet of a dozen arrows.

\spadgraph{drawBouquet(12,"A Dozen Arrows")}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/bouquet.eps}}
\begin{center}
$drawBouquet(12,"A\ Dozen\ Arrows")$
\end{center}
\end{minipage}

\section{Diversion: When Things Go Wrong}
\label{ugIntProgDivTwo}
%
%Up to now, if you have typed in all the programs exactly as they are in
%the book, you have encountered no errors.
%In practice, however, it is easy to make mistakes.
%Computers are unforgiving: your program must be letter-for-letter correct
%or you will encounter some error.
%
%One thing that can go wrong is that you can create a syntactically
%incorrect program.
%As pointed out in Diversion 1, the meaning of Axiom programs is
%affected by indentation.
%
%The Axiom parser will ensure that all parentheses, brackets, and
%braces balance, and that commas and operators appear in the correct
%context.
%For example, change line ??
%to ??
%and run.
%
%A common mistake is to misspell an identifier or operation name.
%These are generally easy to spot since the interpreter will tell you the
%name of the operation together with the type and number of arguments which
%it is trying to find.
%
%Another mistake is to either to omit an argument or to give too many.
%Again Axiom will notify you of the offending operation.
%
%Indentation makes your programs more readable.
%However there are several ways to create a syntactically valid program.
%A most common problem occurs when a line is either indented improperly.
%% either or what?
%If this is a first line of a pile, then all the other lines will act as an
%inner pile to the first line.
%If it is a line of the pile other than the first line, Axiom then
%thinks that this line is a continuation of the previous line.
%More frequently than not, a syntactically correct expression is created.
%Almost never however will this be a semantically correct.
%Only when the program is run will an error be discovered.
%For example, change line ??
%to ??
%and run.

%Original Page 493

\section{Drawing Complex Vector Fields}
\label{ugIntProgVecFields}

We now put our arrows to good use drawing complex vector fields.
These vector fields give a representation of complex-valued
functions of complex variables.
Consider a Cartesian coordinate grid of points $(x, y)$ in
the plane, and some complex-valued function $f$ defined on
this grid.
At every point on this grid, compute the value of $f(x +
iy)$ and call it $z$.
Since $z$ has both a real and imaginary value for a given
$(x,y)$ grid point, there are four dimensions to plot.
What do we do?
We represent the values of $z$ by arrows planted at each
grid point.
Each arrow represents the value of $z$ in polar coordinates
$(r,\theta)$.
The length of the arrow is proportional to $r$.
Its direction is given by $\theta$.

The code for drawing vector fields is in the file {\bf vectors.input}.
We discuss its contents from top to bottom.

Before showing you the code, we have two small
matters to take care of.
First, what if the function has large spikes, say, ones that go off
to infinity?
We define a variable $clipValue$ for this purpose. When
$r$ exceeds the value of $clipValue$, then the value of
$clipValue$ is used instead of that for $r$.
For convenience, we define a function $clipFun(x)$ which uses
$clipValue$ to ``clip'' the value of $x$.

\line(1,0){380}
\begin{verbatim}
clipValue : DFLOAT := 6                          Maximum value allowed
clipFun(x) == min(max(x,-clipValue),clipValue)
\end{verbatim}
\line(1,0){380}

Notice that we identify $clipValue$ as a small float but do
not declare the type of the function {\bf clipFun}.
As it turns out, {\bf clipFun} is called with a
small float value.
This declaration ensures that {\bf clipFun} never does a
conversion when it is called.

The second matter concerns the possible ``poles'' of a
function, the actual points where the spikes have infinite
values.

%Original Page 494

Axiom uses normal {\tt DoubleFloat} arithmetic  which
does not directly handle infinite values.
If your function has poles, you must adjust your step size to
avoid landing directly on them (Axiom calls {\bf error}
when asked to divide a value by $0$, for example).

We set the variables $realSteps$ and $imagSteps$ to
hold the number of steps taken in the real and imaginary
directions, respectively.
Most examples will have ranges centered around the origin.
To avoid a pole at the origin, the number of points is taken
to be odd.

\line(1,0){380}
\begin{verbatim}
realSteps: INT := 25      Number of real steps
imagSteps: INT := 25      Number of imaginary steps
)read arrows
\end{verbatim}
\line(1,0){380}

Now define the function {\bf drawComplexVectorField} to draw the arrows.
It is good practice to declare the type of the main function in
the file.
This one declaration is usually sufficient to ensure that other
lower-level functions are compiled with the correct types.

\line(1,0){380}
\begin{verbatim}
C := Complex DoubleFloat
S := Segment DoubleFloat
drawComplexVectorField: (C -> C, S, S) -> VIEW3D
\end{verbatim}
\line(1,0){380}

The first argument is a function mapping complex small floats into
complex small floats.
The second and third arguments give the range of real and
imaginary values as segments like $a..b$.
The result is a three-di\-men\-sion\-al viewport.
Here is the full function definition:

\line(1,0){380}
\begin{verbatim}
drawComplexVectorField(f, realRange,imagRange) ==
  -- The real step size
  delReal := (hi(realRange)-lo(realRange))/realSteps 
  -- The imaginary step size
  delImag := (hi(imagRange)-lo(imagRange))/imagSteps 
  sp := createThreeSpace()                       Create empty space $sp$
  real := lo(realRange)                          The initial real value
  for i in 1..realSteps+1 repeat                 Begin real iteration
    imag := lo(imagRange)                        initial imaginary value
    for j in 1..imagSteps+1 repeat               Begin imaginary iteration
      z := f complex(real,imag)                  value of $f$ at the point
      arg := argument z                          direction of the arrow
      len := clipFun sqrt norm z                 length of the arrow
      p1 :=  point [real, imag, 0.0@DFLOAT, arg] base point of the arrow
      scaleLen := delReal * len                  scaled length of the arrow
      p2 := point [p1.1 + scaleLen*cos(arg),     tip point of the arrow
                   p1.2 + scaleLen*sin(arg),0.0@DFLOAT, arg]
      arrow := makeArrow(p1, p2)                 Create the arrow
      for a in arrow repeat curve(sp, a)         Add arrow to space $sp$
      imag := imag + delImag                     The next imaginary value
    real := real + delReal                       The next real value
  makeViewport3D(sp, "Complex Vector Field")     Draw it
\end{verbatim}
\line(1,0){380}

%Original Page 495

As a first example, let us draw $f(z) == sin(z)$.
There is no need to create a user function: just pass the
\spadfunFrom{sin}{Complex DoubleFloat} from {\tt Complex DoubleFloat}.

Read the file.

\spadcommand{)read vectors }

Draw the complex vector field of $sin(x)$.

\spadgraph{drawComplexVectorField(sin,-2..2,-2..2) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/vectorsin.eps}}
\begin{center}
$drawBouquet(12,"A\ Dozen\ Arrows")$
\end{center}
\end{minipage}

\section{Drawing Complex Functions}
\label{ugIntProgCompFuns}

Here is another way to graph a complex function of complex
arguments.
For each complex value $z$, compute $f(z)$, again
expressing the value in polar coordinates $(r,\theta{})$.
We draw the complex valued function, again considering the
$(x,y)$-plane as the complex plane, using $r$ as the
height (or $z$-coordinate) and $\theta$ as the color.
This is a standard plot---we learned how to do this in
\sectionref{ugGraph} ---
but here we write a new program to illustrate
the creation of polygon meshes, or grids.

Call this function {\bf drawComplex}.
It displays the points using the ``mesh'' of points.
The function definition is in three parts.

\line(1,0){380}
\begin{verbatim}
drawComplex: (C -> C, S, S) -> VIEW3D
drawComplex(f, realRange, imagRange) ==                
  -- The real step size
  delReal := (hi(realRange)-lo(realRange))/realSteps   
  -- The imaginary step size
  delImag := (hi(imagRange)-lo(imagRange))/imagSteps   
  -- Initial list of list of points $llp$
  llp:List List Point DFLOAT := []
\end{verbatim}
\line(1,0){380}

Variables $delReal$ and $delImag$ give the step
sizes along the real and imaginary directions as computed by the values
of the global variables $realSteps$ and $imagSteps$.
The mesh is represented by a list of lists of points $llp$,
initially empty.
Now $[ ]$ alone is ambiguous, so
to set this initial value
you have to tell Axiom what type of empty list it is.
Next comes the loop which builds $llp$.

\line(1,0){380}
\begin{verbatim}
  real := lo(realRange)                  The initial real value
  for i in 1..realSteps+1 repeat         Begin real iteration
    imag := lo(imagRange)                initial imaginary value
    lp := []$(List Point DFLOAT)         initial list of points $lp$
    for j in 1..imagSteps+1 repeat       Begin imaginary iteration
      z := f complex(real,imag)          value of $f$ at the point
      pt := point [real,imag, 
                   clipFun sqrt norm z,  Create a point
                   argument z]
      lp := cons(pt,lp)                  Add the point to $lp$
      imag := imag + delImag             The next imaginary value
    real := real + delReal               The next real value
    llp := cons(lp, llp)                 Add $lp$ to $llp$
\end{verbatim}
\line(1,0){380}

%Original Page 496

The code consists of both an inner and outer loop.
Each pass through the inner loop adds one list $lp$ of points
to the list of lists of points $llp$.
The elements of $lp$ are collected in reverse order.

\line(1,0){380}
\begin{verbatim}
  makeViewport3D(mesh(llp), "Complex Function")    Create a mesh and display
\end{verbatim}
\line(1,0){380}

The operation {\bf mesh} then creates an object of type
{\tt ThreeSpace(DoubleFloat)} from the list of lists of points.
This is then passed to {\bf makeViewport3D} to display the
image.

Now add this function directly to your {\bf vectors.input}
file and re-read the file using read vectors.
We try {\bf drawComplex} using
a user-defined function $f$.

Read the file.

\spadcommand{)read vectors }

This one has a pole at $z=0$.

\spadcommand{f(z) == exp(1/z)}

Draw it with an odd number of steps to avoid the pole.

\spadgraph{drawComplex(f,-2..2,-2..2)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/complexexp.eps}}
\begin{center}
$drawComplex(f,-2..2,-2..2)$
\end{center}
\end{minipage}

%Original Page 497

\section{Functions Producing Functions}
\label{ugIntProgFunctions}

In \sectionref{ugUserMake},
you learned how to use the operation
{\bf function} to create a function from symbolic formulas.
Here we introduce a similar operation which not only
creates functions, but functions from functions.

The facility we need is provided by the package
{\tt MakeUnaryCompiledFunction(E,S,T)}.
\index{MakeUnaryCompiledFunction}
This package produces a unary (one-argument) compiled
function from some symbolic data
generated by a previous computation.\footnote{%
{\tt MakeBinaryCompiledFunction} is available for binary
functions.}
\index{MakeBinaryCompiledFunction}
The $E$ tells where the symbolic data comes from;
the $S$ and $T$ give Axiom the
source and target type of the function, respectively.
The compiled function produced  has type
\spadsig{$S$}{$T$}.
To produce a compiled function with definition $p(x) == expr$, call
$compiledFunction(expr, x)$ from this package.
The function you get has no name.
You must to assign the function to the variable $p$ to give it that name.
%

Do some computation.

\spadcommand{(x+1/3)**5}

Convert this to an anonymous function of $x$.
Assign it to the variable $p$ to give the function a name.

\spadcommand{p := compiledFunction(\%,x)\$MakeUnaryCompiledFunction(POLY FRAC INT,DFLOAT,DFLOAT)}

Apply the function.

\spadcommand{p(sin(1.3))}

For a more sophisticated application, read on.

\section{Automatic Newton Iteration Formulas}
\label{ugIntProgNewton}

This setting is needed to get Newton's iterations to converge.

\spadcommand{)set streams calculate 10}

We resume
our continuing saga of arrows and complex functions.
Suppose we want to investigate the behavior of Newton's iteration function
\index{Newton iteration}
in the complex plane.
Given a function $f$, we want to find the complex values
$z$ such that $f(z) = 0$.

The first step is to produce a Newton iteration formula for
a given $f$:
$x_{n+1} = x_n - {\frac{f(x_n)}{f'(x_n)}}.$
We represent this formula by a function $g$
that performs the computation on the right-hand side, that is,
$x_{n+1} = {g}(x_n)$.

The type {\tt Expression Integer} (abbreviated {\tt EXPR
INT}) is used to represent general symbolic expressions in
Axiom.
\index{Expression}
To make our facility as general as possible, we assume
$f$ has this type.
Given $f$, we want
to produce a Newton iteration function $g$ which,
given a complex point $x_n$, delivers the next
Newton iteration point $x_{n+1}$.

%Original Page 498

This time we write an input file called {\bf newton.input}. We need to\\ 
import {\tt MakeUnaryCompiledFunction} (discussed in the last section),\\ 
call it with appropriate types, and then define the function $newtonStep$\\ 
which references it. Here is the function $newtonStep$:

\line(1,0){380}
\begin{verbatim}
C := Complex DoubleFloat                       The complex numbers
complexFunPack:=MakeUnaryCompiledFunction(EXPR INT,C,C)
                                               Package for making functions

newtonStep(f) ==                               Newton's iteration function
  fun  := complexNumericFunction f             Function for $f$
  deriv := complexDerivativeFunction(f,1)      Function for $f'$
  (x:C):C +->                                  Return the iterator function
    x - fun(x)/deriv(x)                        

complexNumericFunction f ==                    Turn an expression $f$ into a
  v := theVariableIn f                         function
  compiledFunction(f, v)$complexFunPack

complexDerivativeFunction(f,n) ==              Create an nth derivative
  v := theVariableIn f                         function
  df := D(f,v,n)
  compiledFunction(df, v)$complexFunPack

theVariableIn f ==                             Returns the variable in $f$
  vl := variables f                            The list of variables
  nv := # vl                                   The number of variables
  nv > 1 => error "Expression is not univariate."
  nv = 0 => 'x                                 Return a dummy variable
  first vl
\end{verbatim}
\line(1,0){380}

Do you see what is going on here?
A formula $f$ is passed into the function {\bf newtonStep}.
First, the function turns $f$ into a compiled program mapping
complex numbers into complex numbers.  Next, it does the same thing
for the derivative of $f$.  Finally, it returns a function which
computes a single step of Newton's iteration.

The function {\bf complexNumericFunction} extracts the variable
from the expression $f$ and then turns $f$ into a function
which maps complex numbers into complex numbers. The function
{\bf complexDerivativeFunction} does the same thing for the
derivative of $f$.  The function {\bf theVariableIn}
extracts the variable from the expression $f$, calling the function
{\bf error} if $f$ has more than one variable.
It returns the dummy variable $x$ if $f$ has no variables.

Let's now apply {\bf newtonStep} to the formula for computing
cube roots of two.

%Original Page 499

Read the input file with the definitions.

\spadcommand{)read newton}

\spadcommand{)read vectors }

The cube root of two.

\spadcommand{f := x**3 - 2}

Get Newton's iteration formula.

\spadcommand{g := newtonStep f}

Let $a$ denote the result of
applying Newton's iteration once to the complex number $1 + \%i$.

\spadcommand{a := g(1.0 + \%i)}

Now apply it repeatedly. How fast does it converge?

\spadcommand{[(a := g(a)) for i in 1..]}

Check the accuracy of the last iterate.

\spadcommand{a**3}

%Original Page 500

In MappingPackage1, we show how functions can be
manipulated as objects in Axiom.
A useful operation to consider here is $*$, which means
composition.
For example $g*g$ causes the Newton iteration formula
to be applied twice.
Correspondingly, $g**n$ means to apply the iteration formula
$n$ times.

Apply $g$ twice to the point $1 + \%i$.
\spadcommand{(g*g) (1.0 + \%i)}

Apply $g$ 11 times.

\spadcommand{(g**11) (1.0 + \%i)}

Look now at the vector field and surface generated
after two steps of Newton's formula for the cube root of two.
The poles in these pictures represent bad starting values, and the
flat areas are the regions of convergence to the three roots.
%

The vector field.

\spadgraph{drawComplexVectorField(g**3,-3..3,-3..3)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/vectorroot.eps}}
\begin{center}
$drawComplexVectorField(g^3,-3..3,-3..3)$
\end{center}
\end{minipage}

The surface.

\spadgraph{drawComplex(g**3,-3..3,-3..3)}

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/complexroot.eps}}
\begin{center}
$drawComplex(g^3,-3..3,-3..3)$
\end{center}
\end{minipage}

%\setcounter{chapter}{10} % Chapter 11

\hyphenation{
In-dexed-Aggre-gate
Lin-ear-Aggre-gate
shallowly-Mutable
draw-Vector-Field
set-Real-Steps
set-Imag-Steps
set-Clip-Value
}

Here and throughout the book we should use the terminology
``type of a function'', rather than talking about source and target.
A function is just an object that has a mapping type.

%Original Page 501

\chapter{Packages}
\label{ugPackages}

Packages provide the bulk of
\index{package}
Axiom's algorithmic library, from numeric packages for computing
special functions to symbolic facilities for
\index{constructor!package}
differential equations, symbolic integration, and limits.
\index{package!constructor}

In \sectionref{ugIntProg},
we developed several useful functions for drawing
vector fields and complex functions.
We now show you how you can add these functions to the
Axiom library to make them available for general use.

The way we created the functions in \sectionref{ugIntProg} 
is typical of how
you, as an advanced Axiom user, may interact with Axiom.
You have an application.
You go to your editor and create an input file defining some
functions for the application.
Then you run the file and try the functions.
Once you get them all to work, you will often want to extend them,
add new features, perhaps write additional functions.

Eventually, when you have a useful set of functions for your application,
you may want to add them to your local Axiom library.
To do this, you embed these function definitions in a package and add
that package to the library.

To introduce new packages, categories, and domains into the system,
you need to use the Axiom compiler to convert the constructors
into executable machine code.
An existing compiler in Axiom is available on an ``as-is''
basis.
A new, faster compiler will be available in version 2.0
of Axiom.

\begin{figure}
\line(1,0){380}
\label{pak-cdraw}
\begin{verbatim}
C      ==> Complex DoubleFloat            All constructors used in a file
S      ==> Segment DoubleFloat            must be spelled out in full
INT    ==> Integer                        unless abbreviated by macros
DFLOAT ==> DoubleFloat                    like these at the top of
VIEW3D ==> ThreeDimensionalViewport       a file
CURVE  ==> List List Point DFLOAT

)abbrev package DRAWCX DrawComplex        Identify kinds and abbreviations
                                          Type definition begins here
DrawComplex(): Exports == Implementation where 

  Exports == with                                    Export part begins
    drawComplex: (C -> C,S,S,Boolean) -> VIEW3D      Exported Operations
    drawComplexVectorField: (C -> C,S,S) -> VIEW3D
    setRealSteps: INT -> INT
    setImagSteps: INT -> INT
    setClipValue: DFLOAT-> DFLOAT

  -- Implementation part begins
  Implementation == add
    arrowScale : DFLOAT := (0.2)::DFLOAT --relative size Local variable 1
    arrowAngle : DFLOAT := pi()-pi()/(20::DFLOAT)        Local variable 2
    realSteps  : INT := 11 --# real steps                Local variable 3
    imagSteps  : INT := 11 --# imaginary steps           Local variable 4
    clipValue  : DFLOAT  := 10::DFLOAT --maximum vector length
                                                         Local variable 5

    setRealSteps(n) == realSteps := n        Exported function definition 1
    setImagSteps(n) == imagSteps := n        Exported function definition 2
    setClipValue(c) == clipValue := c        Exported function definition 3

    clipFun: DFLOAT -> DFLOAT --Clip large magnitudes.
    clipFun(x) == min(max(x, -clipValue), clipValue)
                                             Local function definition 1

    makeArrow: (Point DFLOAT,Point DFLOAT,DFLOAT,DFLOAT) -> CURVE
    makeArrow(p1, p2, len, arg) == ...       Local function definition 2

    drawComplex(f, realRange, imagRange, arrows?) == ...
                                          Exported function definition 4
\end{verbatim}
\caption{The DrawComplex package.}
\label{fig-pak-cdraw}
\line(1,0){380}
\end{figure}

%Original Page 502

\section{Names, Abbreviations, and File Structure}
\label{ugPackagesNames}
%
Each package has a name and an abbreviation.
For a package of the complex draw functions from
\sectionref{ugIntProg}, we choose the name {\tt DrawComplex}
and
\index{abbreviation!constructor}
abbreviation {\tt DRAWCX}.\footnote{An abbreviation can be any string
of
\index{constructor!abbreviation}
between two and seven capital letters and digits, beginning with a letter.
See \sectionref{ugTypesWritingAbbr} for more information.}
To be sure that you have not chosen a name or abbreviation already used by
the system, issue the system command {\tt )show} for both the name and
the abbreviation.
\index{show}

Once you have named the package and its abbreviation, you can choose any new
filename you like with extension ``{\bf .spad}'' to hold the
definition of your package.
We choose the name {\bf drawpak.spad}.
If your application involves more than one package, you
can put them all in the same file.
Axiom assumes no relationship between the name of a library file, and
the name or abbreviation of a package.

%Original Page 503

Near the top of the ``{\bf .spad}'' file, list all the
abbreviations for the packages
using {\tt )abbrev}, each command beginning in column one.
Macros giving names to Axiom expressions can also be placed near the
top of the file.
The macros are only usable from their point of definition until the
end of the file.

Consider the definition of
{\tt DrawComplex} in \figureref{fig-pak-cdraw}.
After the macro
\index{macro}
definition
\begin{verbatim}
S      ==> Segment DoubleFloat
\end{verbatim}
the name
{\tt S} can be used in the file as a
shorthand for {\tt Segment DoubleFloat}.\footnote{The interpreter also allows
{\tt macro} for macro definitions.}
The abbreviation command for the package
\begin{verbatim}
)abbrev package DRAWCX DrawComplex
\end{verbatim}
is given after the macros (although it could precede them).

\section{Syntax}
\label{ugPackagesSyntax}
%
The definition of a package has the syntax:
\begin{center}
\frenchspacing{\it PackageForm {\tt :} 
Exports\quad{\tt ==}\quad Implementation}
\end{center}
The syntax for defining a package constructor is the same as that
\index{syntax}
for defining any function in Axiom.
In practice, the definition extends over many lines so that this syntax is
not practical.
Also, the type of a package is expressed by the operator $with$
\index{with}
followed by an explicit list of operations.
A preferable way to write the definition of a package is with a $where$
\index{where}
expression:

The definition of a package usually has the form: \newline
{\tt%
{\it PackageForm} : Exports  ==  Implementation where \newline
\hspace*{.75pc} {\it optional type declarations}\newline
\hspace*{.75pc} Exports  ==   with \newline
\hspace*{2.0pc}   {\it list of exported operations}\newline
\hspace*{.75pc} Implementation == add \newline
\hspace*{2.0pc}   {\it list of function definitions for exported operations}
}

The {\tt DrawComplex} package takes no parameters and exports five
operations, each a separate item of a {\it pile}.
Each operation is described as a {\it declaration}: a name, followed
by a colon ({\tt :}), followed by the type of the operation.
All operations have types expressed as mappings with
the syntax

%Original Page 504

\begin{center}
{\it
source\quad{\tt ->}\quad target
}
\end{center}

\section{Abstract Datatypes}
\label{ugPackagesAbstract}

A constructor as defined in Axiom is called an {\it abstract
datatype} in the computer science literature.
Abstract datatypes separate ``specification'' (what operations are
provided) from ``implementation'' (how the operations are implemented).
The {\tt Exports} (specification) part of a constructor 
is said to be ``public'' (it
provides the user interface to the package) whereas the {\tt Implementation}
part is ``private'' (information here is effectively hidden---programs
cannot take advantage of it).

The {\tt Exports} part specifies what operations the package provides to users.
As an author of a package, you must ensure that
the {\tt Implementation} part provides a function for each
operation in the {\tt Exports} part.\footnote{The {\tt DrawComplex}
package enhances the facility
described in \sectionref{ugIntProgCompFuns} by allowing a
complex function to have
arrows emanating from the surface to indicate the direction of the
complex argument.}

An important difference between interactive programming and the
use of packages is in the handling of global variables such as
$realSteps$ and $imagSteps$.
In interactive programming, you simply change the values of
variables by {\it assignment}.
With packages, such variables are local to the package---their
values can only be set using functions exported by the package.
In our example package, we provide two functions
{\bf setRealSteps} and {\bf setImagSteps} for
this purpose.

Another local variable is $clipValue$ which can be changed using
the exported operation {\bf setClipValue}.
This value is referenced by the internal function {\bf clipFun} that
decides whether to use the computed value of the function at a point or,
if the magnitude of that value is too large, the
value assigned to $clipValue$ (with the
appropriate sign).

\section{Capsules}
\label{ugPackagesCapsules}
%
The part to the right of {\tt add} in the {\tt Implementation}
\index{add}
part of the definition is called a {\it capsule}.
The purpose of a capsule is:
\begin{itemize}
\item to define a function for each exported operation, and
\item to define a {\it local environment} for these functions to run.
\end{itemize}

%Original Page 505

What is a local environment?
First, what is an environment?
\index{environment}
Think of the capsule as an input file that Axiom reads from top to
bottom.
Think of the input file as having a {\bf )clear all} at the top
so that initially no variables or functions are defined.
When this file is read, variables such as $realSteps$ and
$arrowSize$ in {\tt DrawComplex} are set to initial values.
Also, all the functions defined in the capsule are compiled.
These include those that are exported (like $drawComplex$), and
those that are not (like $makeArrow$).
At the end, you get a set of name-value pairs:
variable names (like $realSteps$ and $arrowSize$)
are paired with assigned values, while
operation names (like $drawComplex$ and $makeArrow$)
are paired with function values.

This set of name-value pairs is called an {\it environment}.
Actually, we call this environment the ``initial environment'' of a package:
it is the environment that exists immediately after the package is
first built.
Afterwards, functions of this capsule can
access or reset a variable in the environment.
The environment is called {\it local} since any changes to the value of a
variable in this environment can be seen {\it only} by these functions.

Only the functions from the package can change the variables in the local
environment.
When two functions are called successively from a package,
any changes caused by the first function called
are seen by the second.

Since the environment is local to the package, its names
don't get mixed
up with others in the system or your workspace.
If you happen to have a variable called $realSteps$ in your
workspace, it does not affect what the
{\tt DrawComplex} functions do in any way.

The functions in a package are compiled into machine code.
Unlike function definitions in input files that may be compiled repeatedly
as you use them with varying argument types,
functions in packages have a unique type (generally parameterized by
the argument parameters of a package) 
and a unique compilation residing on disk.

The capsule itself is turned into a compiled function.
This so-called {\it capsule function} is what builds the initial environment
spoken of above.
If the package has arguments (see below), then each call to the package
constructor with a distinct pair of arguments
builds a distinct package, each with its own local environment.

\section{Input Files vs. Packages}
\label{ugPackagesInputFiles}
%
A good question at this point would 
be ``Is writing a package more difficult than
writing an input file?''

The programs in input files are designed for flexibility and ease-of-use.
Axiom can usually work out all of your types as it reads your program
and does the computations you request.
Let's say that you define a one-argument function without giving its type.
When you first apply the function to a value, this
value is understood by Axiom as identifying the type for the
argument parameter.
Most of the time Axiom goes through the body of your function and
figures out the target type that you have in mind.
Axiom sometimes fails to get it right.
Then---and only then---do you need a declaration to tell Axiom what
type you want.

%Original Page 506

Input files are usually written to be read by Axiom---and by you.
\index{file!input!vs. package}
Without suitable documentation and declarations, your input files
\index{package!vs. input file}
are likely incomprehensible to a colleague---and to you some
months later!

Packages are designed for legibility, as well as
run-time efficiency.
There are few new concepts you need to learn to write
packages. Rather, you just have to be explicit about types
and type conversions.
The types of all functions are pre-declared so that Axiom---and the reader---
knows precisely what types of arguments can be passed to and from
the functions (certainly you don't want a colleague to guess or to
have to work this out from context!).
The types of local variables are also declared.
Type conversions are explicit, never automatic.\footnote{There
is one exception to this rule: conversions from a subdomain to a
domain are automatic.
After all, the objects both have the domain as a common type.}

In summary, packages are more tedious to write than input files.
When writing input files, you can casually go ahead, giving some
facts now, leaving others for later.
Writing packages requires forethought, care and discipline.

\section{Compiling Packages}
\label{ugPackagesPackages}
%

Once you have defined the package {\tt DrawComplex},
you need to compile and test it.
To compile the package, issue the system command {\tt )compile drawpak}.
Axiom reads the file {\bf drawpak.spad}
and compiles its contents into machine binary.
If all goes well, the file {\tt DRAWCX.nrlib} is created in your
local directory for the package.
To test the package, you must load the package before trying an
operation.

Compile the package.

\spadcommand{)compile drawpak }

Expose the package.

\spadcommand{)expose DRAWCX }

Use an odd step size to avoid
a pole at the origin.

\spadcommand{setRealSteps 51 }

%Original Page 507

\spadcommand{setImagSteps 51 }

Define {\bf f} to be the Gamma function.

\spadcommand{f(z) == Gamma(z) }

Clip values of function with magnitude larger than 7.

\spadcommand{setClipValue 7}

Draw the {\bf Gamma} function.

\spadgraph{drawComplex(f,-\%pi..\%pi,-\%pi..\%pi, false) }

\begin{minipage}{\linewidth}
 \makebox[\linewidth]{\includegraphics[scale=0.5]{ps/3dgamma11.eps}}
\begin{center}
$f, -\pi..\pi, -\pi..\pi, false$
\end{center}
\end{minipage}

\section{Parameters}
\label{ugPackagesParameters}
%
The power of packages becomes evident when packages have parameters.
Usually these parameters are domains and the exported operations have types
involving these parameters.

In \sectionref{ugTypes}, you learned that categories denote classes of
domains.  Although we cover this notion in detail in the next chapter,
we now give you a sneak preview of its usefulness.

In \sectionref{ugUserBlocks}, we defined functions $bubbleSort(m)$ and
$insertionSort(m)$ to sort a list of integers.  If you look at the
code for these functions, you see that they may be used to sort {\it
any} structure $m$ with the right properties.  Also, the functions can
be used to sort lists of {\it any} elements---not just integers.  Let
us now recall the code for $bubbleSort$.

\begin{verbatim}
bubbleSort(m) ==
  n := #m
  for i in 1..(n-1) repeat
    for j in n..(i+1) by -1 repeat
      if m.j < m.(j-1) then swap!(m,j,j-1)
  m
\end{verbatim}

%Original Page 508

What properties of ``lists of integers'' are assumed by the sorting
algorithm?
In the first line, the operation {\bf \#} computes the maximum index of
the list.
The first obvious property is that $m$ must have a finite number of
elements.
In Axiom, this is done
by your telling Axiom that $m$ has
the ``attribute'' {\bf finiteAggregate}.
An {\it attribute} is a property
that a domain either has or does not have.
As we show later in \sectionref{ugCategoriesAttributes}, programs\\ 
can query domains as to the presence or absence of an attribute.

The operation {\bf swap} swaps elements of $m$. Using Browse, you find\\ 
that {\bf swap} requires its elements to come from a domain of category\\
{\tt IndexedAggregate} with attribute {\tt shallowlyMutable}.

This attribute means that you can change the internal components of\\
$m$ without changing its external structure. Shallowly-mutable data\\ 
structures include lists, streams, one- and two-dimensional arrays,\\ 
vectors, and matrices.

The category {\tt IndexedAggregate} designates the class of
aggregates whose elements can be accessed by the notation
$m.s$ for suitable selectors $s$.
The category {\tt IndexedAggregate} takes two arguments:
$Index$, a domain of selectors for the aggregate, and
$Entry$, a domain of entries for the aggregate.
Since the sort functions access elements by integers, we must
choose $Index = ${\tt Integer}.
The most general class of domains for which $bubbleSort$ and
$insertionSort$ are defined are those of
category {\tt IndexedAggregate(Integer,Entry)} with the two
attributes {\bf shallowlyMutable} and
{\bf finiteAggregate}.

Using Browse, you can also discover that Axiom has many kinds of domains
with attribute {\bf shallowlyMutable}.
Those of class {\tt IndexedAggregate(Integer,Entry)} include
{\tt Bits}, {\tt FlexibleArray}, {\tt OneDimensionalArray},
{\tt List}, {\tt String}, and {\tt Vector}, and also
{\tt HashTable} and {\tt EqTable} with integer keys.
Although you may never want to sort all such structures, we
nonetheless demonstrate Axiom's
ability to do so.

Another requirement is that {\tt Entry} has an
operation {\tt <}.
One way to get this operation is to assume that
{\tt Entry} has category {\tt OrderedSet}.
By definition, will then export a {\tt <} operation.
A more general approach is to allow any comparison function
$f$ to be used for sorting.
This function will be passed as an argument to the sorting
functions.

Our sorting package then takes two arguments: a domain $S$
of objects of {\it any} type, and a domain $A$, an aggregate
of type {\tt IndexedAggregate(Integer, S)} with the above
two attributes.
Here is its definition using what are close to the original
definitions of $bubbleSort$ and $insertionSort$ for
sorting lists of integers.
The symbol {\tt !} is added to the ends of the operation
names.
This uniform naming convention is used for Axiom operation
names that destructively change one or more of their arguments.

%Original Page 509

\line(1,0){380}
\begin{verbatim}
SortPackage(S,A) : Exports == Implementation where
  S: Object
  A: IndexedAggregate(Integer,S)
    with (finiteAggregate; shallowlyMutable)

  Exports == with
    bubbleSort!: (A,(S,S) -> Boolean) -> A
    insertionSort!: (A, (S,S) -> Boolean) -> A

  Implementation == add
    bubbleSort!(m,f) ==
      n := #m
      for i in 1..(n-1) repeat
        for j in n..(i+1) by -1 repeat
          if f(m.j,m.(j-1)) then swap!(m,j,j-1)
      m
    insertionSort!(m,f) ==
      for i in 2..#m repeat
        j := i
        while j > 1 and f(m.j,m.(j-1)) repeat
          swap!(m,j,j-1)
          j := (j - 1) pretend PositiveInteger
      m
\end{verbatim}
\line(1,0){380}

\section{Conditionals}
\label{ugPackagesConds}
%
When packages have parameters, you can say that an operation is or is not
\index{conditional}
exported depending on the values of those parameters.
When the domain of objects $S$ has an {\tt <}
operation, we can supply one-argument versions of
$bubbleSort$ and $insertionSort$ which use this operation
for sorting.
The presence of the
operation {\tt <} is guaranteed when $S$ is an ordered set.

\line(1,0){380}
\begin{verbatim}
Exports == with
    bubbleSort!: (A,(S,S) -> Boolean) -> A
    insertionSort!: (A, (S,S) -> Boolean) -> A

    if S has OrderedSet then
      bubbleSort!: A -> A
      insertionSort!: A -> A
\end{verbatim}
\line(1,0){380}

In addition to exporting the one-argument sort operations
\index{sort!bubble}
conditionally, we must provide conditional definitions for the
\index{sort!insertion}
operations in the {\tt Implementation} part.
This is easy: just have the one-argument functions call the
corresponding two-argument functions with the operation
{\tt <} from $S$.

\line(1,0){380}
\begin{verbatim}
  Implementation == add
       ...
    if S has OrderedSet then
      bubbleSort!(m) == bubbleSort!(m,<$S)
      insertionSort!(m) == insertionSort!(m,<$S)
\end{verbatim}
\line(1,0){380}

%Original Page 510

In \sectionref{ugUserBlocks}, we give an alternative definition of
{\bf bubbleSort} using \spadfunFrom{first}{List} and
\spadfunFrom{rest}{List} that is more efficient for a list (for
which access to any element requires traversing the list from its
first node).
To implement a more efficient algorithm for lists, we need the
operation {\bf setelt} which allows us to destructively change
the {\bf first} and {\bf rest} of a list.
Using Browse, you find that these operations come from category
{\tt UnaryRecursiveAggregate}.
Several aggregate types are unary recursive aggregates including
those of {\tt List} and {\tt AssociationList}.
We provide two different implementations for
{\bf bubbleSort!} and {\bf insertionSort!}: one
for list-like structures, another for array-like structures.

\line(1,0){380}
\begin{verbatim}
Implementation == add
        ...
    if A has UnaryRecursiveAggregate(S) then
      bubbleSort!(m,fn) ==
        empty? m => m
        l := m
        while not empty? (r := l.rest) repeat
           r := bubbleSort! r
           x := l.first
           if fn(r.first,x) then
             l.first := r.first
             r.first := x
           l.rest := r
           l := l.rest
         m
       insertionSort!(m,fn) ==
          ...
\end{verbatim}
\line(1,0){380}

The ordering of definitions is important.
The standard definitions come first and
then the predicate
\begin{verbatim}
A has UnaryRecursiveAggregate(S)
\end{verbatim}
is evaluated.
If {\tt true}, the special definitions cover up the standard ones.

Another equivalent way to write the capsule is to use an
$if-then-else$ expression:
\index{if}

\line(1,0){380}
\begin{verbatim}
     if A has UnaryRecursiveAggregate(S) then
        ...
     else
        ...
\end{verbatim}
\line(1,0){380}

%Original Page 511

\section{Testing}
\label{ugPackagesCompiling}
%
Once you have written the package, embed it in a file, for example, {\bf
sortpak.spad}.
\index{testing}
Be sure to include an {\bf )abbrev} command at the top of the file:
\begin{verbatim}
)abbrev package SORTPAK SortPackage
\end{verbatim}
Now compile the file (using {\tt )compile sortpak.spad}).

Expose the constructor.
You are then ready to begin testing.

\spadcommand{)expose SORTPAK}

Define a list.

\spadcommand{l := [1,7,4,2,11,-7,3,2]}

Since the integers are an ordered set,
a one-argument operation will do.

\spadcommand{bubbleSort!(l)}

Re-sort it using ``greater than.''

\spadcommand{bubbleSort!(l,(x,y) +-> x > y)}

Now sort it again using {\tt <} on integers.

\spadcommand{bubbleSort!(l, <\$Integer)}

A string is an aggregate of characters so we can sort them as well.

\spadcommand{bubbleSort! "Mathematical Sciences"}

Is {\tt <} defined on booleans?

\spadcommand{false < true}

Good! Create a bit string representing ten consecutive
boolean values {\tt true}.

\spadcommand{u : Bits := new(10,true)}

Set bits 3 through 5 to {\tt false}, then display the result.

\spadcommand{u(3..5) := false; u}

%Original Page 512

Now sort these booleans.

\spadcommand{bubbleSort! u}

Create an ``eq-table'', a
table having integers as keys
and strings as values.

\spadcommand{t : EqTable(Integer,String) := table()}

Give the table a first entry.

\spadcommand{t.1 := "robert"}

And a second.

\spadcommand{t.2 := "richard"}

What does the table look like?

\spadcommand{t}

Now sort it.

\spadcommand{bubbleSort! t}

\section{How Packages Work}
\label{ugPackagesHow}
%
Recall that packages as abstract datatypes are compiled independently
and put into the library.
The curious reader may ask: ``How is the interpreter able to find an
operation such as {\bf bubbleSort!}?
Also, how is a single compiled function such as {\bf bubbleSort!} able
to sort data of different types?''

After the interpreter loads the package {\tt SortPackage}, the four
operations from the package become known to the interpreter.
Each of these operations is expressed as a {\it modemap} in which the type
\index{modemap}
of the operation is written in terms of symbolic domains.

See the modemaps for {\bf bubbleSort!}.

\spadcommand{)display op bubbleSort! }

\begin{verbatim}
There are 2 exposed functions called bubbleSort! :

   [1] D1 -> D1 from SortPackage(D2,D1)
         if D2 has ORDSET and D2 has OBJECT and D1 has
         IndexedAggregate(Integer, D2) with
              finiteAggregate
              shallowlyMutable

   [2] (D1,((D3,D3) -> Boolean)) -> D1 from SortPackage(D3,D1)
         if D3 has OBJECT and D1 has
         IndexedAggregate(Integer,D3) with
              finiteAggregate
              shallowlyMutable
\end{verbatim}

%Original Page 513

What happens if you ask for $bubbleSort!([1,-5,3])$?
There is a unique modemap for an operation named
{\bf bubbleSort!} with one argument.
Since $[1,-5,3]$ is a list of integers, the symbolic domain
$D1$ is defined as {\tt List(Integer)}.
For some operation to apply, it must satisfy the predicate for
some $D2$.
What $D2$?
The third expression of the {\tt and} requires {\tt D1 has
IndexedAggregate(Integer, D2) with} two attributes.
So the interpreter searches for an {\tt IndexedAggregate}
among the ancestors of {\tt List (Integer)} (see
\sectionref{ugCategoriesHier}).
It finds one: {\tt IndexedAggregate(Integer, Integer)}.
The interpreter tries defining $D2$ as {\tt Integer}.
After substituting for $D1$ and $D2$, the predicate
evaluates to {\tt true}.
An applicable operation has been found!

Now Axiom builds the package
{\tt SortPackage(List(Integer), Integer)}.
According to its definition, this package exports the required
operation: {\bf bubbleSort!}: \spadsig{List Integer}{List
Integer}.
The interpreter then asks the package for a function implementing
this operation.
The package gets all the functions it needs (for example,
{\bf rest} and {\bf swap}) from the appropriate
domains and then it
returns a {\bf bubbleSort!} to the interpreter together with
the local environment for {\bf bubbleSort!}.
The interpreter applies the function to the argument $[1,-5,3]$.
The {\bf bubbleSort!} function is executed in its local
environment and produces the result.


%\setcounter{chapter}{11} % Chapter 12

%Original Page 515

\chapter{Categories}
\label{ugCategories}

This chapter unravels the mysteries of categories---what
\index{category}
they are, how they are related to domains and packages,
\index{category!constructor}
how they are defined in Axiom, and how you can extend the
\index{constructor!category}
system to include new categories of your own.

We assume that you have read the introductory material on domains
and categories in \sectionref{ugTypesBasicDomainCons}.
There you learned that the notion of packages covered in the
previous chapter are special cases of domains.
While this is in fact the case, it is useful here to regard domains
as distinct from packages.

Think of a domain as a datatype, a collection of objects (the
objects of the domain).
From your ``sneak preview'' in the previous chapter, you might
conclude that categories are simply named clusters of operations
exported by domains.
As it turns out, categories have a much deeper meaning.
Categories are fundamental to the design of Axiom.
They control the interactions between domains and algorithmic
packages, and, in fact, between all the components of Axiom.

Categories form hierarchies as shown on the inside cover pages of
this book.
The inside front-cover pages illustrate the basic
algebraic hierarchy of the Axiom programming language.
The inside back-cover pages show the hierarchy for data
structures.

Think of the category structures of Axiom as a foundation
for a city on which superstructures (domains) are built.
The algebraic hierarchy, for example, serves as a foundation for
constructive mathematical algorithms embedded in the domains of
Axiom.
Once in place, domains can be constructed, either independently or
from one another.

%Original Page 516

Superstructures are built for quality---domains are compiled into
machine code for run-time efficiency.
You can extend the foundation in directions beyond the space
directly beneath the superstructures, then extend selected
superstructures to cover the space.
Because of the compilation strategy, changing components of the
foundation generally means that the existing superstructures
(domains) built on the changed parts of the foundation
(categories) have to be rebuilt---that is, recompiled.

Before delving into some of the interesting facts about categories, let's see
how you define them in Axiom.

\section{Definitions}
\label{ugCategoriesDefs}

A category is defined by a function with exactly the same format as
\index{category!definition}
any other function in Axiom.

The definition of a category has the syntax:
\begin{center}
{\it CategoryForm} : {\tt Category\quad{}==\quad{}} {\it Extensions} 
{\tt [ with} {\it Exports} {\tt ]}
\end{center}

The brackets {\tt [ ]} here indicate optionality.


The first example of a category definition is
{\tt SetCategory},
the most basic of the algebraic categories in Axiom.
\index{SetCategory}

\line(1,0){380}
\begin{verbatim}
SetCategory(): Category ==
   Join(Type,CoercibleTo OutputForm) with
      "=" : ($, $) -> Boolean
\end{verbatim}
\line(1,0){380}

The definition starts off with the name of the
category ({\tt SetCategory}); this is
always in column one in the source file.
%% maybe talk about naming conventions for source files? .spad or .ax?
All parts of a category definition are then indented with respect to this
\index{indentation}
first line.

In \sectionref{ugTypes}, we talked about {\tt Ring} as denoting the
class of all domains that are rings, in short, the class of all
rings.
While this is the usual naming convention in Axiom, it is also
common to use the word ``Category'' at the end of a category name for clarity.
The interpretation of the name {\tt SetCategory} is, then, ``the
category of all domains that are (mathematical) sets.''

The name {\tt SetCategory} is followed in the definition by its
formal parameters enclosed in parentheses {\tt ()}.
Here there are no parameters.
As required, the type of the result of this category function is the
distinguished name {\sf Category}.

Then comes the {\tt ==}.
As usual, what appears to the right of the {\tt ==} is a
definition, here, a category definition.
A category definition always has two parts separated by the reserved word
\index{with}
$with$.
%\footnote{Debugging hint: it is very easy to forget
%the $with$!}

%Original Page 517

The first part tells what categories the category extends.
Here, the category extends two categories: {\tt Type}, the
category of all domains, and
{\tt CoercibleTo(OutputForm)}.
%\footnote{{\tt CoercibleTo(OutputForm)}
%can also be written (and is written in the definition above) without
%parentheses.}
The operation $Join$ is a system-defined operation that
\index{Join}
forms a single category from two or more other categories.

Every category other than {\tt Type} is an extension of some other
category.
If, for example, {\tt SetCategory} extended only the category
{\tt Type}, the definition here would read ``{\tt Type with
...}''.
In fact, the {\tt Type} is optional in this line; ``{\tt with
...}'' suffices.

\section{Exports}
\label{ugCategoriesExports}


To the right of the $with$ is a list of
\index{with}
all the exports of the category.
Each exported operation has a name and a type expressed by a
{\it declaration} of the form
``{\frenchspacing\tt {\it name}: {\it type}}''.

Categories can export symbols, as well as
{\tt 0} and {\tt 1} which denote
domain constants.\footnote{The
numbers {\tt 0} and {\tt 1} are operation names in Axiom.}
In the current implementation, all other exports are operations with
types expressed as mappings with the syntax
\begin{center}
{\it
source\quad{\tt ->}\quad target
}
\end{center}

The category {\tt SetCategory} has a single export: the operation
$=$ whose type is given by the mapping {\tt (\$, \$) -> Boolean}.
The {\tt \$} in a mapping type always means ``the domain.'' Thus
the operation $=$ takes two arguments from the domain and
returns a value of type {\tt Boolean}.

The source part of the mapping here is given by a {\it tuple}
\index{tuple}
consisting of two or more types separated by commas and enclosed in
parentheses.
If an operation takes only one argument, you can drop the parentheses
around the source type.
If the mapping has no arguments, the source part of the mapping is either
left blank or written as {\tt ()}.
Here are examples of formats of various operations with some
contrived names.

\begin{verbatim}
someIntegerConstant  :    $
aZeroArgumentOperation:   () -> Integer
aOneArgumentOperation:    Integer -> $
aTwoArgumentOperation:    (Integer,$) -> Void
aThreeArgumentOperation:  ($,Integer,$) -> Fraction($)
\end{verbatim}

%Original Page 518

\section{Documentation}
\label{ugCategoriesDoc}

The definition of {\tt SetCategory} above is  missing
an important component: its library documentation.
\index{documentation}
Here is its definition, complete with documentation.

\line(1,0){380}
\begin{verbatim}
++ Description:
++ \bs{}axiomType\{SetCategory\} is the basic category
++ for describing a collection of elements with
++ \bs{}axiomOp\{=\} (equality) and a \bs{}axiomFun\{coerce\}
++ to \bs{}axiomType\{OutputForm\}.

SetCategory(): Category ==
  Join(Type, CoercibleTo OutputForm) with
    "=": ($, $) -> Boolean
      ++ \bs{}axiom\{x = y\} tests if \bs{}axiom\{x\} and
      ++ \bs{}axiom\{y\} are equal.
\end{verbatim}
\line(1,0){380}

Documentary comments are an important part of constructor definitions.
Documentation is given both for the category itself and for
each export.
A description for the category precedes the code.
Each line of the description begins in column one with {\tt ++}.
The description starts with the word {\tt Description:}.\footnote{Other
information such as the author's name, date of creation, and so on,
can go in this
area as well but are currently ignored by Axiom.}
All lines of the description following the initial line are
indented by the same amount.

{\sloppy
Surround the name of any constructor (with or without parameters) with an
\verb+{\bf }+.
Similarly, surround an
operator name with \verb+{\tt }+,
an Axiom operation with \verb+{\bf }+, and a
variable or Axiom expression with
\verb+$$+.
Library documentation is given in a \TeX{}-like language so that
it can be used both for hard-copy and for Browse.
These different wrappings cause operations and types to have
mouse-active buttons in Browse.
For hard-copy output, wrapped expressions appear in a different font.
The above documentation appears in hard-copy as:

}
%
\begin{quotation}
%
{\tt SetCategory} is the basic category
for describing a collection of elements with {\tt =}
(equality) and a {\bf coerce} to {\tt OutputForm}.
%
\end{quotation}
%
and
%
\begin{quotation}
%
$x = y$ tests if $x$ and $y$ are equal.
%
\end{quotation}
%

For our purposes in this chapter, we omit the documentation from further
category descriptions.

%Original Page 519

\section{Hierarchies}
\label{ugCategoriesHier}

A second example of a category is
{\tt SemiGroup}, defined by:
\index{SemiGroup}

\line(1,0){380}
\begin{verbatim}
SemiGroup(): Category == SetCategory with
      "*":  ($,$) -> $
      "**": ($, PositiveInteger) -> $
\end{verbatim}
\line(1,0){380}

This definition is as simple as that for {\tt SetCategory},
except that there are two exported operations.
Multiple exported operations are written as a {\it pile},
that is, they all begin in the same column.
Here you see that the category mentions another type,
{\tt PositiveInteger}, in a signature.
Any domain can be used in a signature.

Since categories extend one another, they form hierarchies.
Each category other than {\tt Type} has one or more parents given
by the one or more categories mentioned before the $with$ part of
the definition.
{\tt SemiGroup} extends {\tt SetCategory} and
{\tt SetCategory} extends both {\tt Type} and
{\tt CoercibleTo (OutputForm)}.
Since {\tt CoercibleTo (OutputForm)} also extends {\tt Type},
the mention of {\tt Type} in the definition is unnecessary but
included for emphasis.

\section{Membership}
\label{ugCategoriesMembership}

We say a category designates a class of domains.
What class of domains?
\index{category!membership}
That is, how does Axiom know what domains belong to what categories?
The simple answer to this basic question is key to the design of
Axiom:

\begin{center}
{\bf Domains belong to categories by assertion.}
\end{center}

When a domain is defined, it is asserted to belong to one or more
categories.
Suppose, for example, that an author of domain {\tt String} wishes to
use the binary operator $*$ to denote concatenation.
Thus \verb|"hello " * "there"| would produce the string
\verb|"hello there"| Actually, concatenation of strings in
Axiom is done by juxtaposition or by using the operation
\spadfunFrom{concat}{String}.
The expression \verb|"hello " "there"| produces the string
\verb|"hello there"|.
The author of {\tt String} could then assert that {\tt String}
is a member of {\tt SemiGroup}.
According to our definition of {\tt SemiGroup}, strings
would then also have the operation $**$ defined automatically.
Then \verb|"--" ** 4| would produce a string of eight dashes
\verb|"--------"|.
Since {\tt String} is a member of {\tt SemiGroup}, it also is
a member of {\tt SetCategory} and thus has an operation
$=$ for testing that two strings are equal.

Now turn to the algebraic category hierarchy inside the
front cover of this book.
Any domain that is a member of a
category extending {\tt SemiGroup} is a member of
{\tt SemiGroup} (that is, it {\it is} a semigroup).
In particular, any domain asserted to be a {\tt Ring} is a
semigroup since {\tt Ring} extends {\tt Monoid}, that,
in turn, extends {\tt SemiGroup}.
The definition of {\tt Integer} in Axiom asserts that
{\tt Integer} is a member of category
{\tt IntegerNumberSystem}, that, in turn, asserts that it is
a member of {\tt EuclideanDomain}.
Now {\tt EuclideanDomain} extends
{\tt PrincipalIdealDomain} and so on.
If you trace up the hierarchy, you see that
{\tt EuclideanDomain} extends {\tt Ring}, and,
therefore, {\tt SemiGroup}.
Thus {\tt Integer} is a semigroup and also exports the
operations $*$ and $**$.

%Original Page 520

\section{Defaults}
\label{ugCategoriesDefaults}

We actually omitted the last \index{category!defaults} part of the
definition of \index{default definitions} {\tt SemiGroup} in
\sectionref{ugCategoriesHier}.  Here now is its complete Axiom definition.

\line(1,0){380}
\begin{verbatim}
SemiGroup(): Category == SetCategory with
      "*": ($, $) -> $
      "**": ($, PositiveInteger) -> $
    add
      import RepeatedSquaring($)
      x: $ ** n: PositiveInteger == expt(x,n)
\end{verbatim}
\line(1,0){380}

The $add$ part at the end is used to give ``default definitions'' for
\index{add}
exported operations.
Once you have a multiplication operation $*$, you can
define exponentiation
for positive integer exponents
using repeated multiplication:

$x^n = {\underbrace{x \, x \, x \, \cdots \,
x}_{\displaystyle n \hbox{\ times}}}$

This definition for $**$ is called a {\it default} definition.
In general, a category can give default definitions for any
operation it exports.
Since {\tt SemiGroup} and all its category descendants in the hierarchy
export $**$, any descendant category may redefine $**$ as well.

A domain of category {\tt SemiGroup}
(such as {\tt Integer}) may or may not choose to
define its own $**$ operation.
If it does not, a default definition that is closest (in a ``tree-distance''
sense of the hierarchy) to the domain is chosen.

The part of the category definition following an $add$ operation
is a {\it capsule}, as discussed in
the previous chapter.
The line
\begin{verbatim}
import RepeatedSquaring($)
\end{verbatim}
references the package
{\tt RepeatedSquaring(\$)}, that is, the package
{\tt RepeatedSquaring} that takes ``this domain'' as its
parameter.
For example, if the semigroup {\tt Polynomial (Integer)}
does not define its own exponentiation operation, the
definition used may come from the package
{\tt RepeatedSquaring (Polynomial (Integer))}.
The next line gives the definition in terms of {\bf expt} from that
package.

%Original Page 521

The default definitions are collected to form a ``default
package'' for the category.
The name of the package is the same as  the category but with an
ampersand ({\tt \&}) added at the end.
A default package always takes an additional argument relative to the
category.
Here is the definition of the default package {\tt SemiGroup\&} as
automatically generated by Axiom from the above definition of
{\tt SemiGroup}.

\line(1,0){380}
\begin{verbatim}
SemiGroup_&($): Exports == Implementation where
  $: SemiGroup
  Exports == with
    "**": ($, PositiveInteger) -> $
  Implementation == add
    import RepeatedSquaring($)
    x:$ ** n:PositiveInteger == expt(x,n)
\end{verbatim}
\line(1,0){380}

\section{Axioms}
\label{ugCategoriesAxioms}

In the previous section you saw the
complete Axiom program defining \index{axiom}
{\tt SemiGroup}.
According to this definition, semigroups (that is, are sets with
the operations \spadopFrom{*}{SemiGroup} and
\spadopFrom{**}{SemiGroup}.
\index{SemiGroup}

You might ask: ``Aside from the notion of default packages, isn't
a category just a {\it macro}, that is, a shorthand
equivalent to the two operations $*$ and $**$ with
their types?'' If a category were a macro, every time you saw the
word {\tt SemiGroup}, you would rewrite it by its list of
exported operations.
Furthermore, every time you saw the exported operations of
{\tt SemiGroup} among the exports of a constructor, you could
conclude that the constructor exported {\tt SemiGroup}.

A category is {\it not} a macro and here is why.
The definition for {\tt SemiGroup} has documentation that states:

\begin{quotation}
    Category {\tt SemiGroup} denotes the class of all multiplicative
    semigroups, that is, a set with an associative operation $*$.

    \vskip .5\baselineskip
    {Axioms:}

    {\small\tt associative("*" : (\$,\$)->\$) -- (x*y)*z = x*(y*z)}
\end{quotation}

According to the author's remarks, the mere
exporting of an operation named $*$ and $**$ is not
enough to qualify the domain as a {\tt SemiGroup}.
In fact, a domain can be a semigroup only if it explicitly
exports a $**$ and
a $*$ satisfying the associativity axiom.

In general, a category name implies a set of axioms, even mathematical
theorems.
There are numerous axioms from {\tt Ring}, for example,
that are well-understood from the literature.
No attempt is made to list them all.
Nonetheless, all such mathematical facts are implicit by the use of the
name {\tt Ring}.

%Original Page 522

\section{Correctness}
\label{ugCategoriesCorrectness}

While such statements are only comments,
\index{correctness}
Axiom can enforce their intention simply by shifting the burden of
responsibility onto the author of a domain.
A domain belongs to category $Ring$ only if the
author asserts that the domain  belongs to {\tt Ring} or
to a category that extends {\tt Ring}.

This principle of assertion is important for large user-extendable
systems.
Axiom has a large library of operations offering facilities in
many areas.
Names such as {\bf norm} and {\bf product}, for example, have
diverse meanings in diverse contexts.
An inescapable hindrance to users would be to force those who wish to
extend Axiom to always invent new names for operations.
%>> I don't think disambiguate is really a word, though I like it
Axiom allows you to reuse names, and then use context to disambiguate one
from another.

Here is another example of why this is important.
Some languages, such as {\bf APL},
\index{APL}
denote the {\tt Boolean} constants {\tt true} and
{\tt false} by the integers $1$ and $0$.
You may want to let infix operators $+$ and $*$ serve as the logical
operators {\bf or} and {\bf and}, respectively.
But note this: {\tt Boolean} is not a ring.
The {\it inverse axiom} for {\tt Ring} states:
%
\begin{center}
Every element $x$ has an additive inverse $y$ such that
$x + y = 0$.
\end{center}
%
{\tt Boolean} is not a ring since {\tt true} has
no inverse---there is no inverse element $a$ such that
$1 + a = 0$ (in terms of booleans, {\tt (true or a) = false}).
Nonetheless, Axiom {\it could} easily and correctly implement
{\tt Boolean} this way.
{\tt Boolean} simply would not assert that it is of category
{\tt Ring}.
Thus the ``{\tt +}'' for {\tt Boolean} values
is not confused with the one for {\tt Ring}.
Since the {\tt Polynomial} constructor requires its argument
to be a ring, Axiom would then refuse to build the
domain {\tt Polynomial(Boolean)}. Also, Axiom would refuse to
wrongfully apply algorithms to {\tt Boolean} elements that  presume that the
ring axioms for ``{\tt +}'' hold.

\section{Attributes}
\label{ugCategoriesAttributes}

Most axioms are not computationally useful.
Those that are can be explicitly expressed by what Axiom calls an
{\it attribute}.
The attribute {\bf commutative(\verb|"*"|)}, for example, is used to assert
that a domain has commutative multiplication.
Its definition is given by its documentation:

\begingroup \parindent=1pc \narrower\noindent%
    A domain $R$ has {\bf commutative(\verb|"*"|)}
    if it has an operation "*": \spadsig{(R,R)}{R} such that $x * y = y * x$.
\par\endgroup

Just as you can test whether a domain has the category {\tt Ring}, you
can test that a domain has a given attribute.


%Original Page 523

Do polynomials over the integers
have commutative multiplication?

\spadcommand{Polynomial Integer has commutative("*")}

Do matrices over the integers
have commutative multiplication?

\spadcommand{Matrix Integer has commutative("*")}

Attributes are used to conditionally export and define operations for
a domain (see \sectionref{ugDomainsAssertions}.
Attributes can also be asserted in a category definition.

After mentioning category {\tt Ring} many times in this book,
it is high time that we show you its definition:
\index{Ring}

\line(1,0){380}
\begin{verbatim}
Ring(): Category ==
  Join(Rng,Monoid,LeftModule($: Rng)) with
      characteristic: -> NonNegativeInteger
      coerce: Integer -> $
      unitsKnown
    add
      n:Integer
      coerce(n) == n * 1$$
\end{verbatim}
\line(1,0){380}

There are only two new things here.
First, look at the {\tt \$\$} on the last line.
This is not a typographic error!
The first {\tt \$} says that the $1$ is to come from some
domain.
The second {\tt \$} says that the domain is ``this domain.''
If {\tt \$} is {\tt Fraction(Integer)}, this line reads {\tt
coerce(n) == n * 1\$Fraction(Integer)}.

The second new thing is the presence of attribute ``$unitsKnown$''.
Axiom can always distinguish an attribute from an operation.
An operation has a name and a type. An attribute has no type.
The attribute {\bf unitsKnown} asserts a rather subtle mathematical
fact that is normally taken for granted when working with
rings.\footnote{With this axiom, the units of a domain are the set of
elements $x$ that each have a multiplicative
inverse $y$ in the domain.
Thus $1$ and $-1$ are units in domain {\tt Integer}.
Also, for {\tt Fraction Integer}, the domain of rational numbers,
all non-zero elements are units.}
Because programs can test for this attribute, Axiom can
correctly handle rather more complicated mathematical structures (ones
that are similar to rings but do not have this attribute).

%Original Page 524

\section{Parameters}
\label{ugCategoriesParameters}

Like domain constructors, category constructors can also have
parameters.
For example, category {\tt MatrixCategory} is a parameterized
category for defining matrices over a ring $R$ so that the
matrix domains can have
different representations and indexing schemes.
Its definition has the form:

\line(1,0){380}
\begin{verbatim}
MatrixCategory(R,Row,Col): Category ==
    TwoDimensionalArrayCategory(R,Row,Col) with ...
\end{verbatim}
\line(1,0){380}

The category extends {\tt TwoDimensionalArrayCategory} with
the same arguments.
You cannot find {\tt TwoDimensionalArrayCategory} in the
algebraic hierarchy listing.
Rather, it is a member of the data structure hierarchy,
given inside the back cover of this book.
In particular, {\tt TwoDimensionalArrayCategory} is an extension of
{\tt HomogeneousAggregate} since its elements are all one type.

The domain {\tt Matrix(R)}, the class of matrices with coefficients
from domain $R$, asserts that it is a member of category
{\tt MatrixCategory(R, Vector(R), Vector(R))}.
The parameters of a category must also have types.
The first parameter to {\tt MatrixCategory}
$R$ is required to be a ring.
The second and third are required to be domains of category
{\tt FiniteLinearAggregate(R)}.\footnote{%
This is another extension of
{\tt HomogeneousAggregate} that you can see in
the data structure hierarchy.}
In practice, examples of categories having parameters other than
domains are rare.

Adding the declarations for parameters to the definition for
{\tt MatrixCategory}, we have:

\line(1,0){380}
\begin{verbatim}
R: Ring
(Row, Col): FiniteLinearAggregate(R)

MatrixCategory(R, Row, Col): Category ==
    TwoDimensionalArrayCategory(R, Row, Col) with ...
\end{verbatim}
\line(1,0){380}

\section{Conditionals}
\label{ugCategoriesConditionals}

\index{conditional}
\spadfunFrom{determinant}{MatrixCategory}
As categories have parameters, the actual operations exported by a\\
category can depend on these parameters. As an example, the operation\\ 
from category {\tt MatrixCategory} is only exported when the\\
underlying domain $R$ has commutative multiplication:

\begin{verbatim}
if R has commutative("*") then
   determinant: $ -> R
\end{verbatim}

Conditionals can also define conditional extensions of a category.
Here is a portion of the definition of {\tt QuotientFieldCategory}:
\index{QuotientFieldCategory}

%Original Page 525

\line(1,0){380}
\begin{verbatim}
QuotientFieldCategory(R) : Category == ... with ...
     if R has OrderedSet then OrderedSet
     if R has IntegerNumberSystem then
       ceiling: $ -> R
         ...
\end{verbatim}
\line(1,0){380}

Think of category {\tt QuotientFieldCategory(R)} as
denoting the domain {\tt Fraction(R)}, the
class of all fractions of the form $a/b$ for elements of $R$.
The first conditional means in English:
``If the elements of $R$ are totally ordered ($R$
is an {\tt OrderedSet}), then so are the fractions $a/b$''.
\index{Fraction}

The second conditional is used to conditionally export an
operation {\bf ceiling} which returns the smallest integer
greater than or equal to its argument.
Clearly, ``ceiling'' makes sense for integers but not for
polynomials and other algebraic structures.
Because of this conditional,
the domain {\tt Fraction(Integer)} exports
an operation
{\bf ceiling}: \spadsig{Fraction Integer}{Integer}, but
{\tt Fraction Polynomial Integer} does not.

Conditionals can also appear in the default definitions for the
operations of a category.
For example, a default definition for \spadfunFrom{ceiling}{Field}
within the part following the $add$ reads:

\begin{verbatim}
if R has IntegerNumberSystem then
    ceiling x == ...
\end{verbatim}

Here the predicate used is identical to the predicate in the {\tt
Exports} part.  This need not be the case.  See \sectionref{ugPackagesConds}
for a more complicated example.

\section{Anonymous Categories}
\label{ugCategoriesAndPackages}

The part of a category to the right of a {\tt with} is also regarded
as a category---an ``anonymous category.''  Thus you have already seen
a category definition \index{category!anonymous} in 
\sectionref{ugPackages}.  The {\tt Exports} part
of the package {\tt DrawComplex} (\sectionref{ugPackagesAbstract})
is an anonymous category.  This is
not necessary.  We could, instead, give this category a name:

\line(1,0){380}
\begin{verbatim}
DrawComplexCategory(): Category == with
   drawComplex: (C -> C,S,S,Boolean) -> VIEW3D
   drawComplexVectorField: (C -> C,S,S) -> VIEW3D
   setRealSteps: INT -> INT
   setImagSteps: INT -> INT
   setClipValue: DFLOAT-> DFLOAT
\end{verbatim}
\line(1,0){380}

and then define {\tt DrawComplex} by:

%%Original Page 526

\line(1,0){380}
\begin{verbatim}
DrawComplex(): DrawComplexCategory == Implementation
   where
      ...
\end{verbatim}
\line(1,0){380}

There is no reason, however, to give this list of exports a name
since no other domain or package exports it.
In fact, it is rare for a package to export a named category.
As you will see in the next chapter, however, it is very common
for the definition of domains to mention one or more category
before the {\tt with}.
\index{with}

%\setcounter{chapter}{12} % Chapter 13

\hyphenation{
Quad-rat-ic-Form
}
\spadcommand{)read alql.boot}
\spadcommand{)load DLIST ICARD DBASE QEQUAT MTHING OPQUERY )update}

%Original Page 527

\chapter{Domains}
\label{ugDomains}

We finally come to the {\it domain constructor}.
A few subtle differences between packages and
domains turn up some interesting issues.
We first discuss these differences then
describe the resulting issues by illustrating a program
for the {\tt QuadraticForm} constructor.
After a short example of an algebraic constructor,
{\tt CliffordAlgebra}, we show how you use domain constructors to build
a database query facility.

\section{Domains vs. Packages}
\label{ugPackagesDoms}
%
Packages are special cases of domains.
What is the difference between a package and a domain that is not a
package?
By definition, there is only one difference: a domain that is not a package
has the symbol {\tt \$} appearing
somewhere among the types of its exported operations.
The {\tt \$} denotes ``this domain.'' If the {\tt \$}
appears before the {\tt ->} in the type of a signature, it means
the operation takes an element from the domain as an argument.
If it appears after the {\tt ->}, then the operation returns an
element of the domain.

If no exported operations mention {\tt \$}, then evidently there is
nothing of interest to do with the objects of the domain.  You might
then say that a package is a ``boring'' domain!  But, as you saw in
\sectionref{ugPackages}, packages are a
very useful notion indeed.  The exported operations of a package
depend solely on the parameters to the package constructor and other
explicit domains.

To summarize, domain constructors are versatile structures that serve two
distinct practical purposes:
Those like {\tt Polynomial} and {\tt List}
describe classes of computational objects;
others, like {\tt SortPackage}, describe packages of useful
operations.
As in the last chapter, we focus here on the first kind.

%Original Page 528

\section{Definitions}
\label{ugDomainsDefs}
%

The syntax for defining a domain constructor is the same as for any
function in Axiom:
\begin{center}
\frenchspacing{\tt {\it DomainForm} : {\it Exports} == {\it Implementation}}
\end{center}
As this definition usually extends over many lines, a
$where$ expression is generally used instead.
\index{where}

A recommended format for the definition of a domain is:\newline
{\tt%
{\it DomainForm} : Exports  ==  Implementation where \newline
\hspace*{.75pc} {\it optional type declarations} \newline
\hspace*{.75pc} Exports  ==  [{\it Category Assertions}] with \newline
\hspace*{2.0pc}   {\it list of exported operations} \newline
\hspace*{.75pc} Implementation  ==  [{\it Add Domain}] add \newline
\hspace*{2.0pc}   [Rep := {\it Representation}] \newline
\hspace*{2.0pc}   {\it list of function definitions for exported operations}
}

\vskip 4pt
Note: The brackets {\tt [ ]} here denote optionality.

A complete domain constructor definition for {\tt QuadraticForm} is
shown in \figureref{fig-quadform}.
Interestingly, this little domain illustrates all the new concepts you
need to learn.

%Original Page 529

\begin{figure}
\line(1,0){380}
\begin{verbatim}
)abbrev domain QFORM QuadraticForm

++ Description:
++   This domain provides modest support for
++   quadratic forms.
QuadraticForm(n, K): Exports == Implementation where
    n: PositiveInteger
    K: Field

    Exports == AbelianGroup with            --The exports
      quadraticForm: SquareMatrix(n,K) -> $ --export this
        ++ \bs{}axiom\{quadraticForm(m)\} creates a quadratic
        ++ quadratic form from a symmetric,
        ++ square matrix \bs{}axiom\{m\}.
      matrix: $ -> SquareMatrix(n,K)       -- export matrix
        ++ \bs{}axiom\{matrix(qf)\} creates a square matrix
        ++ from the quadratic form \bs{}axiom\{qf\}.
      elt: ($, DirectProduct(n,K)) -> K    -- export elt
        ++ \bs{}axiom\{qf(v)\} evaluates the quadratic form
        ++ \bs{}axiom\{qf\} on the vector \bs{}axiom\{v\},
        ++ producing a scalar.

    Implementation == SquareMatrix(n,K) add --The exports
      Rep := SquareMatrix(n,K)              --representation
      quadraticForm m ==                    --definition 
        not symmetric? m => error                      
          "quadraticForm requires a symmetric matrix"
        m :: $
      matrix q == q :: Rep                  --definition 
      elt(q,v) == dot(v, (matrix q * v))    --definition 

\end{verbatim}
\caption{The {\tt QuadraticForm} domain.}\label{fig-quadform}
\line(1,0){380}
\end{figure}

A domain constructor can take any number and type of parameters.
{\tt QuadraticForm} takes a positive integer $n$ and a field
$K$ as arguments.
Like a package, a domain has a set of explicit exports and an
implementation described by a capsule.
Domain constructors are documented in the same way as package constructors.

Domain {\tt QuadraticForm(n, K)}, for a given positive integer
$n$ and domain $K$, explicitly exports three operations:
%
\begin{itemize}
\item$quadraticForm(A)$ creates a quadratic form from a matrix
$A$.
\item$matrix(q)$ returns the matrix $A$ used to create
the quadratic form $q$.
\item$q.v$ computes the scalar $v^TAv$
for a given vector $v$.
\end{itemize}

Compared with the corresponding syntax given for the definition of a
package, you see that a domain constructor has three optional parts to
its definition: {\it Category Assertions}, {\it Add Domain}, and
{\it Representation}.

\section{Category Assertions}
\label{ugDomainsAssertions}
%

The {\it Category Assertions} part of your domain constructor
definition lists those categories of which all domains created by the
constructor are unconditionally members.  The word ``unconditionally''
means that membership in a category does not depend on the values of
the parameters to the domain constructor.  This part thus defines the
link between the domains and the category hierarchies given on the
inside covers of this book.  As described in
\sectionref{ugCategoriesCorrectness}, it is this link that makes it
possible for you to pass objects of the domains as arguments to other
operations in Axiom.

Every {\tt QuadraticForm} domain is declared
to be unconditionally a member of category {\tt AbelianGroup}.
An abelian group is a collection of elements closed under
addition.
Every object {\it x} of an abelian group has an additive inverse
{\it y} such that $x + y = 0$.
The exports of an abelian group include $0$,
{\tt +}, {\tt -}, and scalar multiplication by an integer.
After asserting that {\tt QuadraticForm} domains are abelian
groups, it is possible to pass quadratic forms to algorithms that
only assume arguments to have these abelian group
properties.

%Original Page 530

In \sectionref{ugCategoriesConditionals}, you saw that {\tt Fraction(R)},\\ 
a member of {\tt QuotientFieldCategory(R)}, is a member of\\ 
{\tt OrderedSet} if $R$ is a member of {\tt OrderedSet}.  Likewise,\\
from the {\tt Exports} part of the definition of {\tt ModMonic(R, S)},

\begin{verbatim}
UnivariatePolynomialCategory(R) with
  if R has Finite then Finite
     ...
\end{verbatim}
you see that {\tt ModMonic(R, S)} is a member of
{\tt Finite} is $R$ is.

The {\tt Exports} part of a domain definition is
the same kind of
expression that can appear to the right of an
{\tt ==} in a category definition.
If a domain constructor is unconditionally a member of two or more
categories, a $Join$ form is used.
\index{Join}
The {\tt Exports} part of the definition of
{\tt FlexibleArray(S)} reads, for example:
\begin{verbatim}
Join(ExtensibleLinearAggregate(S),
     OneDimensionalArrayAggregate(S)) with...
\end{verbatim}

\section{A Demo}
\label{ugDomainsDemo}
%
Before looking at the {\it Implementation} part of {\tt QuadraticForm},
let's try some examples.

\vskip 2pc

Build a domain $QF$.

\spadcommand{QF := QuadraticForm(2,Fraction Integer)}

Define a matrix to be used to construct
a quadratic form.

\spadcommand{A := matrix [ [-1,1/2],[1/2,1] ]}

Construct the quadratic form. A package call {\tt \$QF} is necessary\\ 
since there are other {\tt QuadraticForm} domains.

\spadcommand{q : QF := quadraticForm(A)}

%Original Page 531

Looks like a matrix. Try computing
the number of rows.
Axiom won't let you.

\spadcommand{nrows q}

Create a direct product element $v$.
A package call is again necessary, but Axiom
understands your list as denoting a vector.

\spadcommand{v := directProduct([2,-1])\$DirectProduct(2,Fraction Integer)}

Compute the product $v^TAv$.

\spadcommand{q.v}

What is 3 times $q$ minus $q$ plus $q$?

\spadcommand{3*q-q+q}

\section{Browse}
\label{ugDomainsBrowse}

The Browse facility of HyperDoc is useful for
investigating
the properties of domains, packages, and categories.
From the main HyperDoc menu, move your mouse to {\bf Browse} and
click on the left mouse button.
This brings up the Browse first page.
Now, with your mouse pointer somewhere in this window, enter the
string ``quadraticform'' into the input area (all lower case
letters will do).
Move your mouse to {\bf Constructors} and click.
Up comes a page describing {\tt QuadraticForm}.

From here, click on {\bf Description}.
This gives you a page that includes a part labeled by ``{\it
Description:}''.
You also see the types for arguments $n$ and $K$
displayed as well as the fact that {\tt QuadraticForm}
returns an {\tt AbelianGroup}.
You can go and experiment a bit by selecting {\tt Field} with
your mouse.
Eventually, use the \UpBitmap{} button
several times to return to the first page on
{\tt QuadraticForm}.

Select {\bf Operations} to get a list of operations for
{\tt QuadraticForm}.
You can select an operation by clicking on it
to get an individual page with information about that operation.
Or you can select the buttons along the bottom to see alternative
views or get additional information on the operations.
Then return to the page on {\tt QuadraticForm}.

Select {\bf Cross Reference} to get another menu.
This menu has buttons for {\bf Parents}, {\bf Ancestors}, and
others.
Clicking on {\bf Parents}, you see that {\tt QuadraticForm}
has one parent {\tt AbelianMonoid}.

%Original Page 532

\section{Representation}
\label{ugDomainsRep}
%
The {\tt Implementation} part of an Axiom capsule for a
domain constructor uses the special variable $Rep$ to
\index{Rep @ {\tt Rep}}
identify the lower level data type used to represent the objects
\index{representation!of a domain}
of the domain.
\index{domain!representation}
The $Rep$ for quadratic forms is {\tt SquareMatrix(n, K)}.
This means that all objects of the domain are required to be
$n$ by $n$ matrices with elements from {\bf K}.

The code for {\tt quadraticForm} in \figureref{fig-quadform}
checks that the matrix is symmetric and then converts it to
{\tt \$}, which means, as usual, ``this domain.'' Such explicit
conversions \index{conversion} are generally required by the
compiler.
Aside from checking that the matrix is symmetric, the code for
this function essentially does nothing.
The {\frenchspacing\tt m :: \$} on line 28 coerces $m$ to a
quadratic form.
In fact, the quadratic form you created in step (3) of
\sectionref{ugDomainsDemo} is just the matrix you passed it in
disguise!
Without seeing this definition, you would not know that.
Nor can you take advantage of this fact now that you do know!
When we try in the next step of \sectionref{ugDomainsDemo} to regard
$q$ as a matrix by asking for {\bf nrows}, the number of
its rows, Axiom gives you an error message saying, in
effect, ``Good try, but this won't work!''

The definition for the \spadfunFrom{matrix}{QuadraticForm}
function could hardly be simpler:
it just returns its argument after explicitly
coercing its argument to a matrix.
Since the argument is already a matrix, this coercion does no computation.

Within the context of a capsule, an object of {\tt \$} is
regarded both as a quadratic form {\it and} as a
matrix.\footnote{In case each of {\tt \$} and $Rep$
have the same named operation available,
the one from $\$$ takes precedence.
Thus, if you want the one from {\tt Rep}, you must
package call it using a {\tt \$Rep} suffix.}
This makes the definition of $q.v$ easy---it
just calls the \spadfunFrom{dot}{DirectProduct} product from
{\tt DirectProduct} to perform the indicated operation.

\section{Multiple Representations}
\label{ugDomainsMultipleReps}
%

To write functions that implement the operations of a domain, you
want to choose the most computationally efficient
data structure to represent the elements of your domain.

A classic problem in computer algebra is the optimal choice for an
internal representation of polynomials.
If you create a polynomial, say $3x^2+ 5$, how
does Axiom hold this value internally?
There are many ways.
Axiom has nearly a dozen different representations of
polynomials, one to suit almost any purpose.
Algorithms for solving polynomial equations work most
efficiently with polynomials represented one way, whereas those for
factoring polynomials are most efficient using another.
One often-used representation is  a list of terms, each term
consisting of exponent-coefficient records written in the order
of decreasing exponents.
For example, the polynomial $3x^2+5$ is
%>> I changed the k's in next line to e's as I thought that was
%>> clearer.
represented by the list $[ [e:2, c:3], [e:0, c:5] ]$.

%Original Page 533

What is the optimal data structure for a matrix?
It depends on the application.
For large sparse matrices, a linked-list structure of records
holding only the non-zero elements may be optimal.
If the elements can be defined by a simple formula
$f(i,j)$, then a compiled function for
$f$ may be optimal.
Some programmers prefer to represent ordinary matrices as vectors
of vectors.
Others prefer to represent matrices by one big linear array where
elements are accessed with linearly computable indexes.

While all these simultaneous structures tend to be confusing,
Axiom provides a helpful organizational tool for such a purpose:
categories.
{\tt PolynomialCategory}, for example, provides a uniform user
interface across all polynomial types.
Each kind of polynomial implements functions for
all these operations, each in its own way.
If you use only the top-level operations in
{\tt PolynomialCategory} you usually do not care what kind
of polynomial implementation is used.

%>> I've often thought, though, that it would be nice to be
%>> be able to use conditionals for representations.
Within a given domain, however, you define (at most) one
representation.\footnote{You can make that representation a
{\tt Union} type, however.
See \sectionref{ugTypesUnions} for examples of unions.}
If you want to have multiple representations (that is, several
domains, each with its own representation), use a category to
describe the {\tt Exports}, then define separate domains for each
representation.

\section{Add Domain}
\label{ugDomainsAddDomain}
%

The capsule part of {\tt Implementation} defines functions that
implement the operations exported by the domain---usually only
some of the operations.
In our demo in \sectionref{ugDomainsDemo}, we asked for the value of
$3*q-q+q$.
Where do the operations {\tt *}, {\tt +}, and
{\tt -} come from?
There is no definition for them in the capsule!

The {\tt Implementation} part of a definition can
\index{domain!add}
optionally specify an ``add-domain'' to the left of an {\tt add}
\index{add}
(for {\tt QuadraticForm}, defines
{\tt SquareMatrix(n,K)} is the add-domain).
The meaning of an add-domain is simply this: if the capsule part
of the {\tt Implementation} does not supply a function for an
operation, Axiom goes to the add-domain to find the
function.
So do $*$, $+$ and $-$ (from QuadraticForm) come from
{\tt SquareMatrix(n,K)}?
%Read on!

%Original Page 534

\section{Defaults}
\label{ugDomainsDefaults}
%
In \sectionref{ugPackages}, we saw that categories can provide
default implementations for their operations.
How and when are they used?
When Axiom finds that {\tt QuadraticForm(2, Fraction
Integer)} does not implement the operations {\tt *},
{\tt +}, and {\tt -}, it goes to
{\tt SquareMatrix (2,Fraction Integer)} to find it.
As it turns out, {\tt SquareMatrix(2, Fraction Integer)} does
not implement {\it any} of these operations!

What does Axiom do then?
Here is its overall strategy.
First, Axiom looks for a function in the capsule for the domain.
If it is not there, Axiom looks in the add-domain for the
operation.
If that fails, Axiom searches the add-domain of the add-domain,
and so on.
If all those fail, it then searches the default packages for the
categories of which the domain is a member.
In the case of {\tt QuadraticForm}, it searches
{\tt AbelianGroup}, then its parents, grandparents, and
so on.
If this fails, it then searches the default packages of the
add-domain.
Whenever a function is found, the search stops immediately and the
function is returned.
When all fails, the system calls {\bf error} to report this
unfortunate news to you.
To find out the actual order of constructors searched for
{\tt QuadraticForm}, consult Browse: from the
{\tt QuadraticForm}, click on {\tt Cross Reference}, then on
{\tt Lineage}.

Let's apply this search strategy for our example $3*q-q+q$.
The scalar multiplication comes first.
Axiom finds a default implementation in
{\tt AbelianGroup\&}.
Remember from \sectionref{ugCategoriesDefaults} that
{\tt SemiGroup} provides a default definition for
$x^n$ by repeated squaring?
{\tt AbelianGroup} similarly provides a definition for
$n x$ by repeated doubling.

But the search of the defaults for {\tt QuadraticForm} fails
to find any {\tt +} or {\tt *} in the default packages for
the ancestors of {\tt QuadraticForm}.
So it now searches among those for {\tt SquareMatrix}.
Category {\tt MatrixCategory}, which provides a uniform interface
for all matrix domains,
is a grandparent of {\tt SquareMatrix} and
has a capsule defining many functions for matrices, including
matrix addition, subtraction, and scalar multiplication.
The default package {\tt MatrixCategory\&} is where the
functions for $+$ and $-$ (from QuadraticForm) come from.

You can use Browse to discover where the operations for
{\tt QuadraticForm} are implemented.
First, get the page describing {\tt QuadraticForm}.
With your mouse somewhere in this window, type a ``2'', press the
\fbox{\bf Tab} key, and then enter ``Fraction
Integer'' to indicate that you want the domain
{\tt QuadraticForm(2, Fraction Integer)}.
Now click on {\bf Operations} to get a table of operations and on
{\tt *} to get a page describing the {\tt *} operation.
Finally, click on {\bf implementation} at the bottom.

%Original Page 535

\section{Origins}
\label{ugDomainsOrigins}
%

Aside from the notion of where an operation is implemented,
\index{operation!origin}
a useful notion is  the {\it origin} or ``home'' of an operation.
When an operation (such as
\spadfunFrom{quadraticForm}{QuadraticForm}) is explicitly exported by
a domain (such as {\tt QuadraticForm}), you can say that the
origin of that operation is that domain.
If an operation is not explicitly exported from a domain, it is inherited
from, and has as origin, the (closest) category that explicitly exports it.
The operations $+$ and $-$ (from AbelianMonoid) of {\tt QuadraticForm},
for example, are inherited from {\tt AbelianMonoid}.
As it turns out, {\tt AbelianMonoid} is the origin of virtually every
{\tt +} operation in Axiom!

Again, you can use Browse to discover the origins of
operations.
From the Browse page on {\tt QuadraticForm}, click on {\bf
Operations}, then on {\bf origins} at the bottom of the page.

The origin of the operation is the {\it only} place where on-line
documentation is given.
However, you can re-export an operation to give it special
documentation.
Suppose you have just invented the world's fastest algorithm for
inverting matrices using a particular internal representation for
matrices.
If your matrix domain just declares that it exports
{\tt MatrixCategory}, it exports the {\bf inverse}
operation, but the documentation the user gets from Browse is
the standard one from {\tt MatrixCategory}.
To give your version of {\bf inverse} the attention it
deserves, simply export the operation explicitly with new
documentation.
This redundancy gives {\bf inverse} a new origin and tells
Browse to present your new documentation.

\section{Short Forms}
\label{ugDomainsShortForms}
%
In Axiom, a domain could be defined using only an add-domain
and no capsule.
Although we talk about rational numbers as quotients of integers,
there is no type {\tt RationalNumber} in Axiom.
To create such a type, you could compile the following
``short-form'' definition:

\noindent
\line(1,0){380}
\begin{verbatim}
RationalNumber() == Fraction(Integer)
\end{verbatim}
\line(1,0){380}

The {\tt Exports} part of this definition is missing and is taken
to be equivalent to that of {\tt Fraction(Integer)}.
Because of the add-domain philosophy, you get precisely
what you want.
The effect is to create a little stub of a domain.
When a user asks to add two rational numbers, Axiom would
ask {\tt RationalNumber} for a function implementing this
{\tt +}.
Since the domain has no capsule, the domain then immediately
sends its request to {\tt Fraction (Integer)}.

The short form definition for domains is used to
define such domains as {\tt Multivariate\-Polynomial}:
\index{MultivariatePolynomial}

%Original Page 536

\line(1,0){380}
\begin{verbatim}
MultivariatePolynomial(vl: List Symbol, R: Ring) ==
   SparseMultivariatePolynomial(R,
      OrderedVariableList vl)
\end{verbatim}
\line(1,0){380}

\section{Example 1: Clifford Algebra}
\label{ugDomainsClifford}
%

Now that we have {\tt QuadraticForm} available,
let's put it to use.
Given some quadratic form $Q$ described by an
$n$ by $n$ matrix over a field $K$, the domain
{\tt CliffordAlgebra(n, K, Q)} defines a vector space of
dimension $2^n$ over $K$.
This is an interesting domain since complex numbers, quaternions,
exterior algebras and spin algebras are all examples of Clifford
algebras.

The basic idea is this:
the quadratic form $Q$ defines a basis
$e_1,e_2\ldots,e_n$ for the
vector space $K^n$---the direct product of $K$
with itself $n$ times.
From this, the Clifford algebra generates a basis of
$2^n$ elements given by all the possible products
of the $e_i$ in order without duplicates, that is,

1,
$e_1$,
$e_2$,
$e_1e_2$,
$e_3$,
$e_1e_3$,
$e_2e_3$,
$e_1e_2,e_3$,
and so on.

The algebra is defined by the relations
$$
\begin{array}{lclc}
e_i \  e_i & = & Q(e_i) \\
e_i \  e_j & = & -e_j \  e_i & \hbox{for } i \neq j
\end{array}
$$

Now look at the snapshot of its definition given in \figureref{fig-clifalg}.
Lines 9-10 show part of the definitions of the
{\tt Exports}.  A Clifford algebra over a field $K$ is asserted to be
a ring, an algebra over $K$, and a vector space over $K$.  Its
explicit exports include $e(n),$ which returns the $n$-th unit
element.

The Implementation part begins by defining a local variable {\tt Qeelist}
to hold the list of all {\tt q.v} where {\tt v} runs over the unit vectors
from 1 to the dimension {\tt n}. Another local variable {\tt dim} is set
to $2^n$, computed once and for all. The representation for the domain is
{\tt PrimitiveArray(K)}, which is a basic array of elements from domain
{\tt K}. Line 18 defines {\tt New} as shorthand for a more lengthy
expression {\tt new(dim,0\$K)\$Rep}, which computes a primitive array of
length $2^n$ filled with 0's from domain {\tt K}.

Lines 19-22 define the sum of two elements {\tt x} and {\tt y}
straightforwardly. First, a new array of all 0's is created, then
filled with the sum of the corresponding elements. Indexing for primitive
arrays start at 0. The definition of the product of {\tt x} and {\tt y}
first requires the definition of a local function {\bf addMonomProd}.
Axiom knows it is local since it is not an exported function.
The types of all local functions must be declared.

%Original Page 537

\begin{figure}
\line(1,0){380}
\begin{verbatim}
NNI ==> NonNegativeInteger
PI  ==> PositiveInteger

CliffordAlgebra(n,K,q): Exports == Implementation where
    n: PI
    K: Field
    q: QuadraticForm(n, K)

    Exports == Join(Ring,Algebra(K),VectorSpace(K)) with
      e: PI -> $
          ...        

    Implementation == add
      Qeelist :=  
        [q.unitVector(i::PI) for i in 1..n]
      dim     :=  2**n
      Rep     := PrimitiveArray K
      New ==> new(dim, 0$K)$Rep
      x + y ==
        z := New
        for i in 0..dim-1 repeat z.i := x.i + y.i
        z
      addMonomProd: (K, NNI, K, NNI, $) -> $
      addMonomProd(c1, b1, c2, b2, z) ==  ...
      x * y ==
        z := New
        for ix in 0..dim-1 repeat
          if x.ix ~= 0 then for iy in 0..dim-1 repeat
            if y.iy ~= 0
            then addMonomProd(x.ix,ix,y.iy,iy,z)
          z
           ...
\end{verbatim}
\caption{Part of the {\tt CliffordAlgebra} domain.}\label{fig-clifalg}
\line(1,0){380}
\end{figure}

The {\tt Implementation} part begins by defining a local variable
$Qeelist$ to hold the list of all $q.v$ where $v$
runs over the unit vectors from 1 to the dimension $n$.
Another local variable $dim$ is set to $2^n$,
computed once and for all.
The representation for the domain is
{\tt PrimitiveArray(K)},
which is a basic array of elements from domain $K$.
Line 18 defines $New$ as shorthand for the more lengthy
expression $new(dim, 0\$K)\$Rep$, which computes a primitive
array of length $2^n$ filled with $0$'s from
domain $K$.

Lines 19-22 define the sum of two elements $x$ and $y$
straightforwardly.
First, a new array of all $0$'s is created, then filled with
the sum of the corresponding elements.
Indexing for primitive arrays starts at 0.
The definition of the product of $x$ and $y$ first requires
the definition of a local function {\bf addMonomProd}.
Axiom knows it is local since it is not an exported function.
The types of all local functions must be declared.

\section{Example 2: Building A Query Facility}
\label{ugDomsinsDatabase}
%
We now turn to an entirely different kind of application,
building a query language for a database.

Here is the practical problem to solve.
The Browse facility of Axiom has a
database for all operations and constructors which is
stored on disk and accessed by HyperDoc.
For our purposes here, we regard each line of this file as having
eight fields:
{\tt class, name, type, nargs, exposed, kind, origin,} and {\tt condition.}
Here is an example entry:

\begin{verbatim}
o`determinant`$->R`1`x`d`Matrix(R)`has(R,commutative("*"))
\end{verbatim}

In English, the entry means:
\begin{quotation}
\raggedright
The operation {\bf determinant}: \spadsig{\$}{R} with {\it 1} argument, is
{\it exposed} and is exported by {\it domain} {\tt Matrix(R)}
if {\tt R has commutative("*")}.
\end{quotation}

%Original Page 538

Our task is to create a little query language that allows us
to get useful information from this database.

\subsection{A Little Query Language}
\label{ugDomainsQueryLanguage}

First we design a simple language for accessing information from
the database.
We have the following simple model in mind for its design.
Think of the database as a box of index cards.
There is only one search operation---it
takes the name of a field and a predicate
\index{predicate}
(a boolean-valued function) defined on the fields of the
index cards.
When applied, the search operation goes through the entire box
selecting only those index cards for which the predicate is {\tt true}.
The result of a search is a new box of index cards.
This process can be repeated again and again.

The predicates all have a particularly simple form: {\it symbol}
{\tt =} {\it pattern}, where {\it symbol} designates one of the
fields, and {\it pattern} is a ``search string''---a string
that may contain a ``{\tt *}'' as a
wildcard.
Wildcards match any substring, including the empty string.
Thus the pattern {\tt "*ma*t} matches
{\tt "mat"},{\tt doormat} and {\tt smart}.

To illustrate how queries are given, we give you a sneak preview
of the facility we are about to create.

Extract the database of all Axiom operations.

\spadcommand{ops := getDatabase("o")}

How many exposed three-argument {\bf map} operations involving streams?

\spadcommand{ops.(name="map").(nargs="3").(type="*Stream*")}

As usual, the arguments of {\bf elt} ({\tt .})
associate to the left.
The first {\bf elt} produces the set of all operations with
name {\tt map}.
The second {\bf elt} produces the set of all map operations
with three arguments.
The third {\bf elt} produces the set of all three-argument map
operations having a type mentioning {\tt Stream}.

Another thing we'd like to do is to extract one field from each of
the index cards in the box and look at the result.
Here is an example of that kind of request.

What constructors explicitly export a {\bf determinant} operation?

\spadcommand{elt(elt(elt(elt(ops,name="determinant"),origin),sort),unique)}

%Original Page 539

The first {\bf elt} produces the set of all index cards with
name {\tt determinant}.
The second {\bf elt} extracts the {\tt origin} component from
each index card. Each origin component
is the name of a constructor which directly
exports the operation represented by the index card.
Extracting a component from each index card produces what we call
a {\it datalist}.
The third {\bf elt}, {\tt sort}, causes the datalist of
origins to be sorted in alphabetic
order.
The fourth, {\tt unique}, causes duplicates to be removed.

Before giving you a more extensive demo of this facility,
we now build the necessary domains and packages to implement it.
%We will introduce a few of our minor conveniences.

\subsection{The Database Constructor}
\label{ugDomainsDatabaseConstructor}

We work from the top down. First, we define a database,
our box of index cards, as an abstract datatype.
For sake of illustration and generality,
we assume that an index card is some type $S$, and
that a database is a box of objects of type $S$.
Here is the Axiom program defining the {\tt Database}
domain.

\noindent
\line(1,0){380}
\begin{verbatim}
PI ==> PositiveInteger
Database(S): Exports == Implementation where
  S: Object with 
    elt: ($, Symbol) -> String
    display: $ -> Void
    fullDisplay: $ -> Void

  Exports == with
    elt: ($,QueryEquation) -> $          Select by an equation
    elt: ($, Symbol) -> DataList String  Select by a field name
    "+": ($,$) -> $                      Combine two databases
    "-": ($,$) -> $                      Subtract one from another
    display: $ -> Void                   A brief database display
    fullDisplay: $ -> Void               A full database display
    fullDisplay: ($,PI,PI) -> Void       A selective display
    coerce: $ -> OutputForm              Display a database
  Implementation == add
      ...
\end{verbatim}
\line(1,0){380}

The domain constructor takes a parameter $S$, which
stands for the class of index cards.
We describe an index card later.
Here think of an index card as a string which has
the eight fields mentioned above.

First, we tell Axiom what operations we are going to require
from index cards.
We need an {\bf elt} to extract the contents of a field
(such as {\tt name} and {\tt type}) as a string.
For example,
$c.name$ returns a string that is the content of the
$name$ field on the index card $c$.
We need to display an index card in two ways:
{\bf display} shows only the name and type of an
operation;
{\bf fullDisplay} displays all fields.
The display operations return no useful information and thus have
return type {\tt Void}.

%Original Page 540

Next, we tell Axiom what operations the user can apply
to the database.
This part defines our little query language.
The most important operation is
{\frenchspacing\tt db . field = pattern} which
returns a new database, consisting of all index
cards of {\tt db} such that the $field$ part of the index
card is matched by the string pattern called $pattern$.
The expression {\tt field = pattern} is an object of type
{\tt QueryEquation} (defined in the next section).

Another {\bf elt} is needed to produce a {\tt DataList}
object.
Operation {\tt +} is to merge two databases together;
{\tt -} is used to subtract away common entries in a second
database from an initial database.
There are three display functions.
The {\bf fullDisplay} function has two versions: one
that prints all the records, the other that prints only a fixed
number of records.
A {\bf coerce} to {\tt OutputForm} creates a display
object.

The {\tt Implementation} part of {\tt Database} is straightforward.

\noindent
\line(1,0){380}
\begin{verbatim}
  Implementation == add
    s: Symbol
    Rep := List S
    elt(db,equation) == ...
    elt(db,key) == [x.key for x in db]::DataList(String)
    display(db) ==  for x in db repeat display x
    fullDisplay(db) == for x in db repeat fullDisplay x
    fullDisplay(db, n, m) == for x in db for i in 1..m
      repeat
        if i >= n then fullDisplay x
    x+y == removeDuplicates! merge(x,y)
    x-y == mergeDifference(copy(x::Rep),
                           y::Rep)$MergeThing(S)
    coerce(db): OutputForm == (#db):: OutputForm
\end{verbatim}
\line(1,0){380}

The database is represented by a list of elements of $S$ (index cards).
We leave the definition of the first {\bf elt} operation
(on line 4) until the next section.
The second {\bf elt} collects all the strings with field name
{\it key} into a list.
The {\bf display} function and first {\bf fullDisplay} function
simply call the corresponding functions from $S$.
The second {\bf fullDisplay} function provides an efficient way of
printing out a portion of a large list.
The {\tt +} is defined by using the existing
\spadfunFrom{merge}{List} operation defined on lists, then
removing duplicates from the result.
The {\tt -} operation requires writing a corresponding
subtraction operation.
A package {\tt MergeThing} (not shown) provides this.

The {\bf coerce} function converts the database to an
{\tt OutputForm} by computing the number of index cards.
This is a good example of the independence of
the representation of an Axiom object from how it presents
itself to the user. We usually do not want to look at a database---but
do care how many ``hits'' we get for a given query.
So we define the output representation of a database to be simply
the number of index cards our query finds.

%Original Page 541

\subsection{Query Equations}
\label{ugDomainsQueryEquations}

The predicate for our search is given by an object of type
{\tt QueryEquation}.
Axiom does not have such an object yet so we
have to invent it.

\noindent
\line(1,0){380}
\begin{verbatim}
QueryEquation(): Exports == Implementation where
  Exports == with
    equation: (Symbol, String) -> $
    variable: $ -> Symbol
    value: $ -> String

  Implementation == add
    Rep := Record(var:Symbol, val:String)
    equation(x, s) == [x, s]
    variable q == q.var
    value q == q.val
\end{verbatim}
\line(1,0){380}

Axiom converts an input expression of the form
${\it a} = {\it b}$ to $equation({\it a, b})$.
Our equations always have a symbol on the left and a string
on the right.
The {\tt Exports} part thus specifies an operation
{\bf equation} to create a query equation, and
{\bf variable} and {\bf value} to select the left- and
right-hand sides.
The {\tt Implementation} part uses {\tt Record} for a
space-efficient representation of an equation.

Here is the missing definition for the {\bf elt} function of
{\tt Database} in the last section:

\noindent
\line(1,0){380}
\begin{verbatim}
    elt(db,eq) ==
      field\  := variable eq
      value := value eq
      [x for x in db | matches?(value,x.field)]
\end{verbatim}
\line(1,0){380}

Recall that a database is represented by a list.
Line 4 simply runs over that list collecting all elements
such that the pattern (that is, $value$)
matches the selected field of the element.

\subsection{DataLists}
\label{ugDomainsDataLists}

Type {\tt DataList} is a new type invented to hold the result
of selecting one field from each of the index cards in the box.
It is useful to make datalists extensions of lists---lists that
have special {\bf elt} operations defined on them for
sorting and removing duplicates.

%Original Page 542

\noindent
\line(1,0){380}
\begin{verbatim}
DataList(S:OrderedSet) : Exports == Implementation where
  Exports == ListAggregate(S) with
    elt: ($,"unique") -> $
    elt: ($,"sort") -> $
    elt: ($,"count") -> NonNegativeInteger
    coerce: List S -> $

  Implementation ==  List(S) add
    Rep := List S
    elt(x,"unique") == removeDuplicates(x)
    elt(x,"sort") == sort(x)
    elt(x,"count") == #x
    coerce(x:List S) == x :: $
\end{verbatim}
\line(1,0){380}

The {\tt Exports} part asserts that datalists belong to the
category {\tt ListAggregate}.
Therefore, you can use all the usual list operations on datalists,
such as \spadfunFrom{first}{List}, \spadfunFrom{rest}{List}, and
\spadfunFrom{concat}{List}.
In addition, datalists have four explicit operations.
Besides the three {\bf elt} operations, there is a
{\bf coerce} operation that creates datalists from lists.

The {\tt Implementation} part needs only to define four functions.
All the rest are obtained from {\tt List(S)}.

\subsection{Index Cards}
\label{ugDomainsDatabase}

An index card comes from a file as one long string.
We define functions that extract substrings from the long
string.
Each field has a name that
is passed as a second argument to {\bf elt}.

\noindent
\line(1,0){380}
\begin{verbatim}
IndexCard() == Implementation where
  Exports == with
    elt: ($, Symbol) -> String
    display: $ -> Void
    fullDisplay: $ -> Void
    coerce: String -> $
  Implementation == String add ...
\end{verbatim}
\line(1,0){380}

We leave the {\tt Implementation} part to the reader.
All operations involve straightforward string manipulations.

\subsection{Creating a Database}
\label{ugDomainsCreating}

We must not forget one important operation: one that builds the database in the
first place!
We'll name it {\bf getDatabase} and put it in a package.
This function is implemented by calling the Common Lisp function
$getBrowseDatabase(s)$ to get appropriate information from
Browse.
This operation takes a string indicating which lines you
want from the database: ``{\tt o}'' gives you all operation
lines, and ``{\tt k}'', all constructor lines.
Similarly, ``{\tt c}'', ``{\tt d}'', and ``{\tt p}'' give
you all category, domain and package lines respectively.

%%Original Page 543

\noindent
\line(1,0){380}
\begin{verbatim}
OperationsQuery(): Exports == Implementation where
  Exports == with
    getDatabase: String -> Database(IndexCard)

  Implementation == add
    getDatabase(s) == getBrowseDatabase(s)$Lisp
\end{verbatim}
\line(1,0){380}

We do not bother creating a special name for databases of index cards.\\
{\tt Database (IndexCard)} will do. Notice that we used the package\\ 
{\tt OperationsQuery} to create, in effect, a new kind of domain:\\
{\tt Database(IndexCard)}.

\subsection{Putting It All Together}
\label{ugDomainsPutting}

To create the database facility, you put all these constructors
into one file.\footnote{You could use separate files, but we
are putting them all together because, organizationally, that is
the logical thing to do.}
At the top of the file put {\tt )abbrev} commands, giving the
constructor abbreviations you created.

\pagebreak
\noindent
\line(1,0){380}
\begin{verbatim}
)abbrev domain  ICARD   IndexCard
)abbrev domain  QEQUAT  QueryEquation
)abbrev domain  MTHING  MergeThing
)abbrev domain  DLIST   DataList
)abbrev domain  DBASE   Database
)abbrev package OPQUERY OperationsQuery
\end{verbatim}
\line(1,0){380}

With all this in {\bf alql.spad}, for example, compile it using
\index{compile}
\begin{verbatim}
)compile alql
\end{verbatim}
and then load each of the constructors:
\begin{verbatim}
)load ICARD QEQUAT MTHING DLIST DBASE OPQUERY
\end{verbatim}
\index{load}
You are ready to try some sample queries.

\subsection{Example Queries}
\label{ugDomainsExamples}

Our first set of queries give some statistics on constructors in
the current Axiom system.

How many constructors does Axiom have?

\spadcommand{ks := getDatabase "k"}

%Original Page 544

Break this down into the number of categories, domains, and packages.

\spadcommand{[ks.(kind=k) for k in ["c","d","p"] ]}

What are all the domain constructors that take no parameters?

\spadcommand{elt(ks.(kind="d").(nargs="0"),name)}

How many constructors have ``Matrix'' in their name?

\spadcommand{mk := ks.(name="*Matrix*")}

What are the names of those that are domains?

\spadcommand{elt(mk.(kind="d"),name)}

How many operations are there in the library?

\spadcommand{o := getDatabase "o"}

Break this down into categories, domains, and packages.

\spadcommand{[o.(kind=k) for k in ["c","d","p"] ]}


The query language is helpful in getting information about a
particular operation you might like to apply.
While this information can be obtained with
Browse, the use of the query database gives you data that you
can manipulate in the workspace.

%Original Page 545

How many operations have ``eigen'' in the name?

\spadcommand{eigens := o.(name="*eigen*")}

What are their names?

\spadcommand{elt(eigens,name)}

Where do they come from?

\spadcommand{elt(elt(elt(eigens,origin),sort),unique) }

The operations {\tt +} and {\tt -} are useful for
constructing small databases and combining them.
However, remember that the only matching you can do is string
matching.
Thus a pattern such as {\tt "*Matrix*"} on the type field
matches
any type containing {\tt Matrix}, {\tt MatrixCategory},
{\tt SquareMatrix}, and so on.

How many operations mention ``Matrix'' in their type?

\spadcommand{tm := o.(type="*Matrix*")}

How many operations come from constructors with ``Matrix'' in
their name?

\spadcommand{fm := o.(origin="*Matrix*")}

How many operations are in $fm$ but not in $tm$?

\spadcommand{fm-tm }

Display the operations that both mention ``Matrix'' in their type
and come from a constructor having ``Matrix'' in their name.

\spadcommand{fullDisplay(fm-\%) }

%Original Page 546

How many operations involve matrices?

\spadcommand{m := tm+fm }

Display 4 of them.

\spadcommand{fullDisplay(m, 202, 205) }

How many distinct names of operations involving matrices are there?

\spadcommand{elt(elt(elt(m,name),unique),count) }

%following definition should go into ug.sty
\gdef\aliascon#1#2{{\bf #1}}
%\setcounter{chapter}{13} % Chapter 14
%

%Original Page 547

\chapter{Browse}
\label{ugBrowse}

This chapter discusses the Browse
\index{Browse@Browse}
component of HyperDoc.
\index{HyperDoc@{HyperDoc}}
We suggest you invoke Axiom and work through this
chapter, section by section, following our examples to gain some
familiarity with Browse.

\section{The Front Page: Searching the Library}
\label{ugBrowseStart}
To enter Browse, click on {\bf Browse} on the top level page
of HyperDoc to get the {\it front page} of Browse.
%
%324pt is 4.5",180pt is 2.5",432pt is 6"=textwidth,54=(432-324)/2
%ps files are 4.5"x2.5" except source 4.5"x2.5"
%
\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-brfront.ps}
\end{picture}
\caption{The Browse front page.}
\end{figure}

To use this page, you first enter a {\it search string} into
the input area at the top, then click on one of the buttons below.
We show the use of each of the buttons by example.

%Original Page 548

\subsubsection{Constructors}

First enter the search string {\tt Matrix} into the input area and
click on {\bf Constructors}.
What you get is the {\it constructor page} for {\tt Matrix}.
We show and describe this page in detail in
\sectionref{ugBrowseDomain}.
By convention, Axiom does a case-insensitive search for a
match.
Thus {\tt matrix} is just as good as {\tt Matrix}, has the same
effect as {\tt MaTrix}, and so on.
We recommend that you generally use small letters for names
however.
A search string with only capital letters has a special meaning
(see \sectionref{ugBrowseCapitalizationConvention}).


Click on \UpBitmap{} to return to the Browse front page.

Use the symbol ``{\tt *}'' in search strings as a {\it wild
card}.
A wild card matches any substring, including the empty string.
For example, enter the search string {\tt *matrix*} into the input
area and click on {\bf Constructors}.\footnote{To get only
categories, domains, or packages, rather than all constructors,
you can click on the corresponding button to the right of {\bf
Constructors}.}
What you get is a table of all constructors whose names contain
the string ``{\tt matrix}.''

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-consearch.ps}
\end{picture}
\caption{Table of exposed constructors matching {\tt *matrix*} .}
\end{figure}

All constructors containing the string are listed, whether
exposed or unexposed.
You can hide the names of the unexposed constructors by clicking
on the {\it *=}{\bf unexposed} button in the {\it Views} panel at
the bottom of the window.
(The button will change to {\bf exposed} {\it only}.)

One of the names in this table is {\tt Matrix}.
Click on {\tt Matrix}.
What you get is again the constructor page for {\tt Matrix}.
As you see, Browse gives you a large network of
information in which there are many ways to reach the same
pages.
\index{Matrix}

Again click on the \UpBitmap{} to return to the table of constructors
whose names contain {\tt matrix}.


%Original Page 549

Below the table is a {\it Views} panel.
This panel contains buttons that let you view constructors in different
ways.
To learn about views of constructors, skip to
\sectionref{ugBrowseViewsOfConstructors}.

Click on \UpBitmap{} to return to the Browse front page.

\subsubsection{Operations}

Enter {\tt *matrix} into the input area and click on {\bf
Operations}.
This time you get a table of {\it operations} whose names end with {\tt
matrix} or {\tt Matrix}.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matrixops.ps}
\end{picture}
\caption{Table of operations matching {\tt *matrix} .}
\end{figure}

If you select an operation name, you go to a page describing all
the operations in Axiom of that name.
At the bottom of an operation page is another kind of {\it Views} panel,
one for operation pages.
To learn more about these views, skip to
\sectionref{ugBrowseViewsOfOperations}.

Click on \UpBitmap{} to return to the Browse front page.

\subsubsection{Attributes}

This button gives you a table of attribute names that match the
search string. Enter the search string {\tt *} and click on
{\bf Attributes} to get a list
of all system attributes.

Click on \UpBitmap{} to return to the Browse front page.


\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-atsearch.ps}
\end{picture}
\caption{Table of Axiom attributes.}
\end{figure}

Again there is a {\it Views} panel at the bottom with buttons that let
you view the attributes in different ways.

\subsubsection{General}

This button does a general search for all constructor, operation, and
attribute names matching the search string.
Enter the search string \allowbreak
{\tt *matrix*} into the input area.
Click on {\bf General} to find all constructs that have {\tt
matrix} as a part of their name.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-gensearch.ps}
\end{picture}
\caption{Table of all constructs matching {\tt *matrix*} .}
\end{figure}

The summary gives you all the names under a heading when the number of
entries is less than 10. 

%Original Page 550

Click on \UpBitmap{} to return to the Browse front page.

%Original Page 551

\subsubsection{Documentation}

Again enter the search key {\tt *matrix*} and this time click on
{\bf Documentation}.
This search matches any constructor, operation, or attribute
name whose documentation contains a substring matching {\tt
matrix}.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-docsearch.ps}
\end{picture}
\caption{Table of constructs with documentation matching {\tt *matrix*} .}
\end{figure}

Click on \UpBitmap{} to return to the Browse front page.

\subsubsection{Complete}

This search combines both {\bf General} and {\bf Documentation}.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-comsearch.ps}
\end{picture}
\caption{Table summarizing complete search for pattern {\tt *matrix*} .}
\end{figure}

\section{The Constructor Page}
\label{ugBrowseDomain}

In this section we look in detail at a constructor page for domain
{\tt Matrix}.
Enter {\tt matrix} into the input area on the main Browse page
and click on {\bf Constructors}.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matpage.ps}
\end{picture}
\caption{Constructor page for {\tt Matrix}.}
\end{figure}

%Original Page 552

The header part tells you that {\tt Matrix} has abbreviation
{\tt MATRIX} and one argument called {\tt R} that must be a
domain of category {\tt Ring}.
Just what domains can be arguments of {\tt Matrix}?
To find this out, click on the {\tt R} on the second line of the
heading.
What you get is a table of all acceptable domain parameter values
of {\tt R}, or a table of {\it rings} in Axiom.

%Original Page 553

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matargs.ps}
\end{picture}
\caption{Table of acceptable domain parameters to {\tt Matrix}.}
\end{figure}

Click on \UpBitmap{} to return to the constructor page for
{\tt Matrix}.
\newpage

If you have access to the source code of Axiom, the third
\index{source code}
line of the heading gives you the name of the source file
containing the definition of {\tt Matrix}.
Click on it to pop up an editor window containing the source code
of {\tt Matrix}.

\begin{figure}[htbp]
\begin{picture}(324,168)%(-54,0)
\special{psfile=ps/h-matsource.ps}
\end{picture}
\caption{Source code for {\tt Matrix}.}
\end{figure}

We recommend that you leave the editor window up while working
through this chapter as you occasionally may want to refer to it.
\newpage

%Original Page 554

\subsection{Constructor Page Buttons}
\label{ugBrowseDomainButtons}

We examine each button on this page in order.

\subsubsection{Description}

Click here to bring up a page with a brief description of
constructor {\tt Matrix}.
If you have access to system source code, note that these comments
can be found directly over the constructor definition.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matdesc.ps}
\end{picture}
\caption{Description page for {\tt Matrix}.}
\end{figure}

\subsubsection{Operations}

Click here to get a table of operations exported by
{\tt Matrix}.
You may wish to widen the window to have multiple columns as
below.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matops.ps}
\end{picture}
\caption{Table of operations from {\tt Matrix}.}
\end{figure}

If you click on an operation name, you bring up a description
page for the operations.
For a detailed description of these pages, skip to
\sectionref{ugBrowseViewsOfOperations}.

\subsubsection{Attributes}

%Original Page 555

Click here to get a table of the two attributes exported by
{\tt Matrix}:
\index{attribute}
{\bf fi\-nite\-Ag\-gre\-gate} and {\bf shallowlyMutable}.
These are two computational properties that result from
{\tt Matrix} being regarded as a data structure.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matats.ps}
\end{picture}
\caption{Attributes from {\tt Matrix}.}
\end{figure}

\subsubsection{Examples}

Click here to get an {\it examples page} with examples of operations to
create and manipulate matrices.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matexamp.ps}
\end{picture}
\caption{Example page for {\tt Matrix}.}
\end{figure}

Read through this section.
Try selecting the various buttons.
Notice that if you click on an operation name, such as
\spadfunFrom{new}{Matrix}, you bring up a description page for that
operation from {\tt Matrix}.

%Original Page 556

Example pages have several examples of Axiom commands.
Each example has an active button to its left.
Click on it!
A pre-computed answer is pasted into the page immediately following the
command.
If you click on the button a second time, the answer disappears.
This button thus acts as a toggle:
``now you see it; now you don't.''

Note also that the Axiom commands themselves are active.
If you want to see Axiom execute the command, then click on it!
A new Axiom window appears on your screen and the command is
executed.

At the end of the page is generally a menu of buttons that lead
you to further sections.
Select one of these topics to explore its contents.

\subsubsection{Exports}

Click here to see a page describing the exports of {\tt Matrix}
exactly as described by the source code.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matexports.ps}
\end{picture}
\caption{Exports of {\tt Matrix}.}
\end{figure}

As you see, {\tt Matrix} declares that it exports all the operations
and attributes exported by category
{\tt MatrixCategory(R, Row, Col)}.
In addition, two operations, {\bf diagonalMatrix} and
{\bf inverse}, are explicitly exported.

To learn a little about the structure of Axiom, we suggest you do
the following exercise.

Otherwise, go on to the next section.

{\tt Matrix} explicitly exports only two operations.
The other operations are thus exports of {\tt MatrixCategory}.
In general, operations are usually not explicitly exported by a domain.
Typically they are inherited from several
different categories.
Let's find out from where the operations of {\tt Matrix} come.

%Original Page 557

\begin{enumerate}
\item Click on {\tt MatrixCategory}, then on {\bf Exports}.\\
Here you see that {\tt MatrixCategory} explicitly exports many matrix\\
operations. Also, it inherits its operations from\\
{\tt TwoDimen\-sionalArrayCategory}.

\item Click on {\tt TwoDimensionalArrayCategory}, then on {\bf Exports}.
Here you see explicit operations dealing with rows and columns.
In addition, it inherits operations from
{\tt HomogeneousAggregate}.

%\item Click on {\tt HomogeneousAggregate}, then on {\bf Exports}.
%And so on.
%If you continue doing this, eventually you will

\item Click on \UpBitmap{} and then
click on {\tt Object}, then on {\bf Exports}, where you see
there are no exports.

\item Click on \UpBitmap{} repeatedly to return to the constructor page
for {\tt Matrix}.

\end{enumerate}

\subsubsection{Related Operations}

Click here bringing up a table of operations that are exported by
packages but not by {\tt Matrix} itself.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matrelops.ps}
\end{picture}
\caption{Related operations of {\tt Matrix}.}
\end{figure}

To see a table of such packages, use the {\bf Relatives} button on the
{\bf Cross Reference} page described next.


\subsection{Cross Reference}
\label{ugBrowseCrossReference}
Click on the {\bf Cross Reference} button on the main constructor page
for {\tt Matrix}.
This gives you a page having various cross reference information stored
under the respective buttons.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matxref.ps}
\end{picture}
\caption{Cross-reference page for {\tt Matrix}.}
\end{figure}

\subsubsection{Parents}

The parents of a domain are the same as the categories mentioned under
the {\bf Exports} button on the first page.
Domain {\tt Matrix} has only one parent but in general a domain can
have any number.

\subsubsection{Ancestors}

The ancestors of a constructor consist of its parents, the
parents of its parents, and so on.
Did you perform the exercise in the last section under {\bf Exports}?
If so, you  see here all the categories you found while ascending the
{\bf Exports} chain for {\tt Matrix}.

%Original Page 558

\subsubsection{Relatives}

The relatives of a domain constructor are package
constructors that provide operations in addition to those
exported by the domain.

Try this exercise.
\begin{enumerate}
\item Click on {\bf Relatives}, bringing up a list of
packages.

\item Click on {\tt LinearSystemMatrixPackage} bringing up its
constructor page.\footnote{You may want to widen your HyperDoc
window to make what follows more legible.}

\item Click on {\bf Operations}.
Here you see {\bf rank}, an operation also exported by
{\tt Matrix} itself.

\item Click on {\bf rank}.
This \spadfunFrom{rank}{LinearSystemMatrixPackage} has two arguments and
thus is different from the \spadfunFrom{rank}{Matrix} from
{\tt Matrix}.

\item Click on \UpBitmap{} to return to the list of operations for the
package {\bf LinearSystemMatrixPackage}.

\item Click on {\bf solve} to bring up a
\spadfunFrom{solve}{LinearSystemMatrixPackage} for linear systems of
equations.

\item Click on \UpBitmap{} several times to return to the cross
reference page for {\tt Matrix}.
\end{enumerate}

\subsubsection{Dependents}

The dependents of a constructor are those
domains or packages
that mention that
constructor either as an argument or in its exports.

If you click on {\bf Dependents} two entries may surprise you:\\
{\tt RectangularMatrix} and {\tt SquareMatrix}. This happens because\\ 
{\tt Matrix}, as it turns out, appears in signatures of operations\\ 
exported by these domains.

\subsubsection{Lineage}

%Original Page 559

The term {\it lineage} refers to the {\it search order} for
functions.
If you are an expert user or curious about how the Axiom system
works, try the following exercise.
Otherwise, you best skip this button and go on to {\bf Clients}.

Clicking on {\bf Lineage} gives you a
list of domain constructors:\\
{\tt InnerIndexedTwoDimensional\-Array},
\aliascon{MatrixCategory\&}{MATCAT-},
\aliascon{TwoDimensionalArrayCategory\&}{ARR2CAT-},
\aliascon{HomogeneousAggregate\&}{HOAGG-},
\aliascon{Aggregate\&}{AGG-}.
What are these constructors and how are they used?

We explain by an example.
Suppose you create a matrix using the interpreter, then ask for its
{\bf rank}.
Axiom must then find a function implementing the {\bf rank}
operation for matrices.
The first place Axiom looks for {\bf rank} is in the {\tt Matrix}
domain.

If not there, the lineage of {\tt Matrix} tells Axiom where
else to look.
Associated with the matrix domain are five other lineage domains.
Their order is important.
Axiom first searches the first one,
{\tt InnerIndexedTwoDimensionalArray}.
If not there, it searches the second \aliascon{MatrixCategory\&}{MATCAT-}.
And so on.

Where do these {\it lineage constructors} come from? The source code\\ 
for {\tt Matrix} contains this syntax for the {\it function body} of\\
{\tt Matrix}: {\tt InnerIndexedTwoDimensionalArray} is a special domain\\ 
implemented for matrix-like domains to provide efficient\\ 
implementations of two-di\-men\-sion\-al arrays.

For example, domains of category {\tt TwoDimensionalArrayCategory} can
have any integer as their $minIndex$. Matrices and other members of
this special ``inner'' array have their $minIndex$ defined as $1$.
\begin{verbatim}
InnerIndexedTwoDimensionalArray(R,mnRow,mnCol,Row,Col)
   add ...
\end{verbatim}
where the ``{\tt ...}'' denotes all the code that follows.
In English, this means:
``The functions for matrices are defined as those from
{\tt InnerIndexedTwoDimensionalArray} domain augmented by those
defined in `{\tt ...}','' where the latter take precedence.

This explains {\tt InnerIndexedTwoDimensionalArray}.
The other names, those with names ending with an ampersand {\tt \&} are
default packages
for categories to which {\tt Matrix} belongs.
Default packages are ordered by the notion of ``closest ancestor.''

\subsubsection{Clients}

A client of {\tt Matrix} is any constructor that uses
{\tt Matrix} in its implementation.
For example, {\tt Complex} is a client of {\tt Matrix}; it
exports several operations that take matrices as arguments or return
matrices as values.\footnote{A constructor is a client of
{\tt Matrix} if it handles any matrix.
For example, a constructor having internal (unexported) operations
dealing with matrices is also a client.}

%Original Page 560

\subsubsection{Benefactors}

A {\it benefactor} of {\tt Matrix} is any constructor that
{\tt Matrix} uses in its implementation.
This information, like that for clients, is gathered from run-time
structures.\footnote{The benefactors exclude constructors such as
{\tt PrimitiveArray} whose operations macro-expand and so vanish
from sight!}

Cross reference pages for categories have some different buttons on
them.
Starting with the constructor page of {\tt Matrix}, click on
{\tt Ring} producing its constructor page.
Click on {\bf Cross Reference},
producing the cross-reference page for {\tt Ring}.
Here are buttons {\bf Parents} and {\bf Ancestors} similar to the notion
for domains, except for categories the relationship between parent and
child is defined through {\it category extension}.

\subsubsection{Children}

Category hierarchies go both ways.
There are children as well as parents.
A child can have any number of parents, but always at least one.
Every category is therefore a descendant of exactly one category:
{\tt Object}.

\subsubsection{Descendants}

These are children, children of children, and so on.

Category hierarchies are complicated by the fact that categories take
parameters.
Where a parameterized category fits into a hierarchy {\it may} depend on
values of its parameters.
In general, the set of categories in Axiom forms a {\it directed
acyclic graph}, that is, a graph with directed arcs and no cycles.

\subsubsection{Domains}

This produces a table of all domain constructors that can possibly be
rings (members of category {\tt Ring}).
Some domains are unconditional rings.
Others are rings for some parameters and not for others.
To find out which, select the {\bf conditions} button in the views
panel.
For example, {\tt DirectProduct(n, R)} is a ring if {\tt R} is a
ring.



\subsection{Views Of Constructors}
\label{ugBrowseViewsOfConstructors}

Below every constructor table page is a {\it Views} panel.
As an example, click on {\bf Cross Reference} from
the constructor page of {\tt Matrix},
then on {\bf Benefactors} to produce a
short table of constructor names.

The {\it Views} panel is at the bottom of the page.
Two items, {\it names} and {\it conditions,} are in italics.
Others are active buttons.
The active buttons are those that give you useful alternative views
on this table of constructors.
Once you select a view, you notice that the button turns
off (becomes italicized) so that you cannot reselect it.

\subsubsection{names}

This view gives you a table of names.
Selecting any of these names brings up the constructor page for that
constructor.

%Original Page 561

\subsubsection{abbrs}

This view gives you a table of abbreviations, in the same order as the
original constructor names.
Abbreviations are in capitals and are limited to 7 characters.
They can be used interchangeably with constructor names in input areas.

\subsubsection{kinds}

This view organizes constructor names into
the three kinds: categories, domains and packages.

\subsubsection{files}

This view gives a table of file names for the source
code of the constructors in alphabetic order after removing
duplicates.

\subsubsection{parameters}

This view presents constructors with the arguments.
This view of the benefactors of {\tt Matrix} shows that
{\tt Matrix} uses as many as five different {\tt List} domains
in its implementation.

\subsubsection{filter}

This button is used to refine the list of names or abbreviations.
Starting with the {\it names} view, enter {\tt m*} into the input area
and click on {\tt filter}.
You then get a shorter table with only the names beginning with {\tt m}.

\subsubsection{documentation}

This gives you documentation for each of the constructors.

\subsubsection{conditions}

This page organizes the constructors according to predicates.
The view is not available for your example page since all constructors
are unconditional.
For a table with conditions, return to the {\bf Cross Reference} page
for {\tt Matrix}, click on {\bf Ancestors}, then on {\bf
conditions} in the view panel.
This page shows you that {\tt CoercibleTo(OutputForm)} and
{\tt SetCategory} are ancestors of {\tt Matrix(R)} only if {\tt R}
belongs to category {\tt SetCategory}.

\subsection{Giving Parameters to Constructors}
\label{ugBrowseGivingParameters}

Notice the input area at the bottom of the constructor page.
If you leave this blank, then the information you get is for the
domain constructor {\tt Matrix(R)}, that is, {\tt Matrix} for an
arbitrary underlying domain {\tt R}.

In general, however, the exports and other information {\it do} usually
depend on the actual value of {\tt R}.
For example, {\tt Matrix} exports the {\bf inverse} operation
only if the domain {\tt R} is a {\tt Field}.
To see this, try this from the main constructor page:

\begin{enumerate}
\item Enter {\tt Integer} into the input area at the bottom of the page.

\item Click on {\bf Operations}, producing a table of operations.
Note the number of operation names that appear at the top of the
page.

\item Click on \UpBitmap{} to return to the constructor page.

\item Use the
\fbox{\bf Delete}
or
\fbox{\bf Backspace}
keys to erase {\tt Integer} from the input area.

\item Click on {\bf Operations} to produce a new table of operations.
Look at the number of operations you get.
This number is greater than what you had before.
Find, for example, the operation {\bf inverse}.

%Original Page 562

\item Click on {\bf inverse} to produce a page describing the operation
{\bf inverse}.
At the bottom of the description, you notice that the {\bf
Conditions} line says ``{\tt R} has {\tt Field}.''
This operation is {\it not} exported by {\tt Matrix(Integer)} since
{\tt Integer} is not a {\it field}.

Try putting the name of a domain such as {\tt Fraction Integer}
(which is a field) into the input area, then clicking on {\bf Operations}.
As you see, the operation {\bf inverse} is exported.
\end{enumerate}

\section{Miscellaneous Features of Browse}
\label{ugBrowseMiscellaneousFeatures}

\subsection{The Description Page for Operations}
\label{ugBrowseDescription}

From the constructor page of {\tt Matrix},
click on {\bf Operations} to bring up the table of operations
for {\tt Matrix}.

Find the operation {\bf inverse} in the table and click on it.
This takes you to a page showing the documentation for this operation.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matinv.ps}
\end{picture}
\caption{Operation \spadfunFrom{inverse}{Matrix} from {\tt Matrix}.}
\end{figure}

Here is the significance of the headings you see.

\subsubsection{Arguments}

This lists each of the arguments of the operation in turn, paraphrasing
the {\it signature} of the operation.
As for signatures, a {\tt \$} is used to designate {\em this domain},
that is, {\tt Matrix(R)}.

\subsubsection{Returns}

This describes the return value for the operation, analogous to the {\bf
Arguments} part.

%Original Page 563

\subsubsection{Origin}

This tells you which domain or category explicitly exports the
operation.
In this example, the domain itself is the {\it Origin}.


\subsubsection{Conditions}

This tells you that the operation is exported by {\tt Matrix(R)} only if
``{\tt R} has {\tt Field},'' that is, ``{\tt R} is a member of
category {\tt Field}.''
When no {\bf Conditions} part is given, the operation is exported for
all values of {\tt R}.

\subsubsection{Description}

Here are the {\tt ++} comments
that appear in the source code of its {\it Origin}, here {\tt Matrix}.
You find these comments in the source code for {\tt Matrix}.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matmap.ps}
\end{picture}
\caption{Operations {\bf map} from {\tt Matrix}.}
\end{figure}

Click on \UpBitmap{} to return to the table of operations.
Click on {\bf map}.
Here you find three different operations named {\bf map}.
This should not surprise you.
Operations are identified by name and {\it signature}.
There are three operations named {\bf map}, each with
different signatures.
What you see is the {\it descriptions} view of the operations.
If you like, select the button in the heading of one of these
descriptions to get {\it only} that operation.

\subsubsection{Where}

This part qualifies domain parameters mentioned in the arguments to the
operation.

\subsection{Views of Operations}
\label{ugBrowseViewsOfOperations}

We suggest that you go to the constructor page for {\tt Matrix}
and click on {\bf Operations} to bring up a table of operations
with a {\it Views} panel at the bottom.

\subsubsection{names}

This view lists the names of the operations.
Unlike constructors, however, there may be several operations with the
same name.
The heading for the page tells you the number of unique names and the
number of distinct operations when these numbers are different.

%Original Page 564

\subsubsection{filter}

As for constructors, you can use this button to cut down the list of
operations you are looking at.
Enter, for example, {\tt m*} into the input area to the right of {\bf
filter} then click on {\bf filter}.
As usual, any logical expression is permitted.
For example, use
\begin{verbatim}
*! or *?
\end{verbatim}
to get a list of destructive operations and predicates.

\subsubsection{documentation}

This gives you the most information:
a detailed description of all the operations in the form you have seen
before.
Every other button summarizes these operations in some form.

\subsubsection{signatures}

This views the operations by showing their signatures.

\subsubsection{parameters}

This views the operations by their distinct syntactic forms with
parameters.

\subsubsection{origins}

This organizes the operations according to the constructor that
explicitly exports them.

\subsubsection{conditions}

This view organizes the operations into conditional and unconditional
operations.

\subsubsection{usage}

This button is only available if your user-level is set to {\it
\index{user-level}
development}.
The {\bf usage} button produces a table of constructors that reference this
operation.\footnote{Axiom requires an especially long time to
produce this table, so anticipate this when requesting this
information.}

\subsubsection{implementation}

This button is only available if your user-level is set to {\it
development}.
\index{user-level}
If you enter values for all domain parameters on the constructor page,
then the {\bf implementation} button appears in place of the {\bf
conditions} button.
This button tells you what domains or packages actually implement the
various operations.\footnote{This button often takes a long time; expect
a delay while you wait for an answer.}

With your user-level set to {\it development}, we suggest you try this
exercise.
Return to the main constructor page for {\tt Matrix}, then enter
{\tt Integer} into the input area at the bottom as the value of {\tt R}.
Then click on {\bf Operations} to produce a table of operations.
Note that the {\bf conditions} part of the {\it Views} table is
replaced by {\bf implementation}.
Click on {\bf implementation}.
After some delay, you get a page describing what implements each of
the matrix operations, organized by the various domains and packages.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-matimp.ps}
\end{picture}
\caption{Implementation domains for {\tt Matrix}.}
\end{figure}

\subsubsection{generalize}

This button only appears for an operation page of a constructor
involving a unique operation name.

From an operations page for {\tt Matrix}, select any
operation name, say {\bf rank}.
In the views panel, the {\bf filter} button is  replaced by
{\bf generalize}.
Click on it!
%% Replaced {\bf threshold} with 10 below.  MGR 1995oct31
What you get is a description of all Axiom operations
named {\bf rank}.\footnote{If there were more than 10
operations of the name, you get instead a page
with a {\it Views} panel at the bottom and the message to {\bf
Select a view below}.
To get the descriptions of all these operations as mentioned
above, select the {\bf description} button.}

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-allrank.ps}
\end{picture}
\caption{All operations named {\bf rank} in Axiom.}
\end{figure}

\subsubsection{all domains}

%Original Page 565


%Original Page 566

This button only appears on an operation page resulting from a
search from the front page of Browse or from selecting
{\bf generalize} from an operation page for a constructor.

Note that the {\bf filter} button in the {\it Views} panel is
replaced by {\bf all domains}.
Click on it to produce a table of {\it all} domains or packages that
export a {\bf rank} operation.

\begin{figure}[htbp]
\begin{picture}(324,180)%(-54,0)
\special{psfile=ps/h-alldoms.ps}
\end{picture}
\caption{Table of all domains that export {\bf rank}.}
\end{figure}

We note that this table specifically refers to all the {\bf rank}
operations shown in the preceding page.
Return to the descriptions of all the {\bf rank} operations and
select one of them by clicking on the button in its heading.
Select {\bf all domains}.
As you see, you have a smaller table of constructors.
When there is only one constructor, you get the
constructor page for that constructor.
\newpage

%Original Page 567

\subsection{Capitalization Convention}
\label{ugBrowseCapitalizationConvention}

When entering search keys for constructors, you can use capital
letters to search for abbreviations.
For example, enter {\tt UTS} into the input area and click on {\bf
Constructors}.
Up comes a page describing {\tt UnivariateTaylorSeries}
whose abbreviation is {\tt UTS}.

Constructor abbreviations always have three or more capital
letters.
For short constructor names (six letters or less), abbreviations
are not generally helpful as their abbreviation is typically the
constructor name in capitals.
For example, the abbreviation for {\tt Matrix} is
{\tt MATRIX}.

Abbreviations can also contain numbers.
For example, {\tt POLY2} is the abbreviation for constructor
{\tt PolynomialFunctions2}.
For default packages, the abbreviation is the same as the
abbreviation for the corresponding category with the ``\&''
replaced by ``-''.
For example, for the category default package
\aliascon{MatrixCategory\&}{MATCAT-} the abbreviation is
{\tt MATCAT-} since the corresponding category
{\tt MatrixCategory} has abbreviation {\tt MATCAT}.

%Original Page 568


%\setcounter{chapter}{14} % Chapter 15 

\chapter{What's New in Axiom Version 2.0}
\label{ugWhatsNew}

Many things have changed in this new version of Axiom and
we describe many of the more important topics here.

%------------------------------------------------------------------------
\section{Important Things to Read First}
\index{ugWhatsNewImportant}
%------------------------------------------------------------------------

If you have any private {\tt .spad} files (that is, library files
which were not shipped with Axiom) you will need to
recompile them.  For example, if you wrote the file {\tt
regress.spad} then you should issue {\tt )compile regress.spad}
before trying to use it.

The internal representation of {\tt Union}  has changed. 
This means that Axiom data saved 
with Release 1.x may not
be readable by this Release. If you cannot recreate the saved data      
by recomputing in Release 2.0, please contact NAG for assistance.       

% ----------------------------------------------------------------------
\section{The NAG Library Link}
\index{nagLinkIntro}
% ----------------------------------------------------------------------

The Nag Library link allows you to call NAG Fortran
routines from within Axiom, passing Axiom objects as parameters
and getting them back as results.

The Nag Library and, consequently, the link are divided into {\em chapters},
which cover different areas of numerical analysis.  The statistical
and sorting {\em chapters} of the Library, however, are not included in the
link and various support and utility routines (mainly the F06 and X
{\em chapters}) have been omitted.

Each {\em chapter} has a short (at most three-letter) name;
for example, the {\em chapter} devoted to the
solution of ordinary differential equations is called D02.  When
using the link via the HyperDoc interface.
you will be presented with a complete menu of these {\em chapters}. The
names of individual routines within each {\em chapter} are formed by
adding three letters to the {\em chapter} name, so for example the routine
for solving ODEs by Adams method is called
\spadfunFrom{d02cjf}{NagOrdinaryDifferentialEquationsPackage}.

% ----------------------------------------------------------------------
\subsection{Interpreting NAG Documentation}
\index{nagDocumentation}
% ----------------------------------------------------------------------

Information about using the Nag Library in general, and about using
individual routines in particular, can be accessed via HyperDoc.
This documentation refers to the Fortran routines directly; the
purpose of this subsection is to explain how this corresponds to the
Axiom routines.

For general information about the Nag Library users should consult
Essential Introduction to the NAG Foundation Library
\index{manpageXXintro}.
The documentation is in ASCII format, and a description of the conventions
used to represent mathematical symbols is given in
Introduction to NAG On-Line Documentation
\index{manpageXXonline}.
Advice about choosing a routine from a particular {\em chapter} can be found in
the Chapter Documents \index{FoundationLibraryDoc}.

% ----------------------------------------------------------------------
\subsubsection{Correspondence Between Fortran and Axiom types}
% ----------------------------------------------------------------------

The NAG documentation refers to the Fortran types of objects; in
general, the correspondence to Axiom types is as follows.
\begin{itemize}
\item Fortran INTEGER corresponds to Axiom {\tt Integer}.
\item Fortran DOUBLE PRECISION corresponds to Axiom {\tt DoubleFloat}.
\item Fortran COMPLEX corresponds to Axiom {\tt Complex DoubleFloat}.
\item Fortran LOGICAL corresponds to Axiom {\tt Boolean}.
\item Fortran CHARACTER*(*) corresponds to Axiom {\tt String}.
\end{itemize}
(Exceptionally, for NAG EXTERNAL parameters -- ASPs in link parlance\\
-- REAL and COMPLEX correspond to {\tt MachineFloat} and\\ 
{\tt MachineComplex}, respectively; see \sectionref{aspSection}.)

The correspondence for aggregates is as follows.
\begin{itemize}
\item A one-dimensional Fortran array corresponds to a
      {\tt Matrix} with one column.
\item A two-dimensional Fortran ARRAY corresponds to a
      {\tt Matrix}.
\item A three-dimensional Fortran ARRAY corresponds to a
      {\tt ThreeDimensionalMatrix}.
\end{itemize}
Higher-dimensional arrays are not currently needed for the Nag Library.

Arguments which are Fortran FUNCTIONs or SUBROUTINEs correspond
to special ASP domains in Axiom. See \sectionref{aspSection}.

% ----------------------------------------------------------------------
\subsubsection{Classification of NAG parameters}
% ----------------------------------------------------------------------

NAG parameters are classified as belonging to one (or more)
of the following categories: {\tt Input}, 
{\tt Output}, {\tt Workspace} or {\tt External} procedure.
Within {\tt External} procedures a 
similar classification is used, and parameters
may also be {\tt Dummies}, 
or {\tt User Workspace} (data structures not used by the
NAG routine but provided for the convenience of the user).

When calling a NAG routine via the link the user only provides values
for {\tt Input} and {\tt External} parameters.

The order of the parameters is, in general, different from  the order
specified in the Nag Library documentation. The Browser description
for each routine helps in determining the correspondence. As a rule of
thumb, {\tt Input} parameters come first followed by {\tt Input/Output}
parameters. The {\tt External} parameters are always found at the end.


% ----------------------------------------------------------------------
\subsubsection{IFAIL}
% ----------------------------------------------------------------------

NAG routines often return diagnostic information through a parameter called
$ifail$.  With a few exceptions, the principle is that on input
$ifail$ takes
one of the values $-1,0,1$.  This determines how the routine behaves when
it encounters an error:
\begin{itemize}
\item a value of 1 causes the NAG routine to return without printing an error
message;
\item a value of 0 causes the NAG routine to print an error message and abort;
\item a value of -1 causes the NAG routine to return and 
print an error message.
\end{itemize}

The user is STRONGLY ADVISED to set $ifail$ to $-1$ when using the link.
If $ifail$ has been set to $1$ or $-1$ on input, then its value on output
will determine the possible cause of any error.  A value of $0$ indicates
successful completion, otherwise it provides an index into a table of
diagnostics provided as part of the routine documentation (accessible via
Browse).

% ----------------------------------------------------------------------
\subsection{Using the Link}
\index{nagLinkUsage}
% ----------------------------------------------------------------------

The easiest way to use the link is via the
HyperDoc interface \index{htxl1}.
You will be presented with a set of fill-in forms where
you can specify the parameters for each call.  Initially, the forms
contain example values, demonstrating the use of each routine (these,
in fact, correspond to the standard NAG example program for the
routine in question).  For some parameters, these values can provide
reasonable defaults; others, of course, represent data.  When you
change a parameter which controls the size of an array, the data in
that array are reset to a ``neutral'' value -- usually zero.

When you are satisfied with the values entered, clicking on the
``Continue'' button will display the Axiom command needed to
run the chosen NAG routine with these values.  Clicking on the
``Do It'' button will then cause Axiom to execute this command
and return the result in the parent Axiom session, as described
below.  Note that, for some routines, multiple HyperDoc ``pages'' are
required, due to the structure of the data.  For these, returning to
an earlier page causes HyperDoc to reset the later pages (this is a
general feature of HyperDoc); in such a case, the simplest way to
repeat a call, varying a parameter on an earlier page, is probably to
modify the call displayed in the parent session.

An alternative approach is to call NAG routines directly in your
normal Axiom session (that is, using the Axiom
interpreter).  Such calls return an
object of type {\bf Result}.  As not
all parameters in the underlying NAG routine are required in the
Axiom call (and the parameter ordering may be different), before
calling a NAG routine you should consult the description of the
Axiom operation in the Browser.  (The quickest route to this
is to type the routine name, in lower case, into the Browser's
input area, then click on {\tt Operations}.)  The parameter names
used coincide with NAG's, although they will appear here in lower
case.  Of course, it is also possible to become familiar with the
Axiom form of a routine by first using it through the
HyperDoc interface \index{htxl1}.

As an example of this mode of working, we can find a zero
of a function, lying between 3 and 4, as follows:

\spadcommand{answer:=c05adf(3.0,4.0,1.0e-5,0.0,-1,sin(X)::ASP1(F)) }

By default, {\bf Result} only displays the type of returned values,
since the amount of information returned can be quite large.  Individual
components can be examined as follows:

\spadcommand{answer . x}

\spadcommand{answer . ifail}

In order to avoid conflict with names defined in the workspace, you can also
get the values by using the {\tt String} type (the interpreter automatically
coerces them to {\tt Symbol})

\spadcommand{answer "x"}

It is possible to have Axiom display the values of scalar or array
results automatically.  For more details, see the commands  
\spadfunFrom{showScalarValues}{Result}
and \spadfunFrom{showArrayValues}{Result}.

There is also a {\bf .input} file for each NAG routine, containing
Axiom interpreter commands to set up and run the standard NAG
example for that routine.

\spadcommand{)read c05adf.input}

% ----------------------------------------------------------------------
\subsection{Providing values for Argument Subprograms}
\label{aspSection}
\index{aspSection}
% ----------------------------------------------------------------------

There are a number of ways in which users can provide values for argument
subprograms (ASPs).  At the top level the user will see that NAG routines
require
an object from the {\tt Union} of a {\tt Filename} and an ASP.

For example {\bf c05adf} requires an object of type
{\tt Union}(fn: {\tt FileName},fp: {\tt Asp1 F})

\spadcommand{)display operation c05adf}


The user thus has a choice of providing the name of a file containing
Fortran source code, or of somehow generating the ASP within Axiom.
If a filename is specified, it is searched for in the {\it local} 
machine, i.e., the machine that Axiom is running on.

% ----------------------------------------------------------------------
\subsubsection{Providing ASPs via {\tt FortranExpression}}
% ----------------------------------------------------------------------

The {\tt FortranExpression} domain is used to represent expressions
which can be translated into Fortran under certain circumstances.    It is
very similar to {\tt Expression} except that only operators which exist
in Fortran can be used, and only certain variables can occur.
For
example the instantiation {\tt FortranExpression([X],[M],MachineFloat)}
is the domain of expressions containing the scalar $X$ and the array
$M$.

This allows us to create expressions like:

\spadcommand{f : FortranExpression([X],[M],MachineFloat) := sin(X)+M[3,1]}

but not

\spadcommand{f : FortranExpression([X],[M],MachineFloat) := sin(M)+Y}

Those ASPs which represent expressions usually export a {\bf coerce} from
an appropriate instantiation of {\tt FortranExpression} (or perhaps
{\tt Vector FortranExpression} etc.).  For convenience there are also
retractions from appropriate instantiations of {\tt Expression},
{\tt Polynomial} and {\tt Fraction Polynomial}.

% ----------------------------------------------------------------------
\subsubsection{Providing ASPs via {\tt FortranCode}}
% ----------------------------------------------------------------------

\index{FortranCode}
{\tt FortranCode} allows us to build arbitrarily complex ASPs via a
kind of pseudo-code.  It is described fully in
\sectionref{generalFortran}.

Every ASP exports two {\bf coerce} functions: one from
{\tt FortranCode} and one from {\tt List FortranCode}.  There
is also a {\bf coerce} from
{\tt Record( localSymbols: SymbolTable, code: List FortranCode)}
which is used for passing extra symbol information about the ASP.

So for example, to integrate the function abs(x) we could use the built-in
{\bf abs} function.  But suppose we want to get back to basics and define
it directly, then we could do the following:

\spadcommand{d01ajf(-1.0, 1.0, 0.0, 1.0e-5, 800, 200, -1, cond(LT(X,0), assign(F,-X), assign(F,X))) result }

The \spadfunFrom{cond}{FortranCode} operation creates a conditional clause
and the \spadfunFrom{assign}{FortranCode} an assignment statement.

% ----------------------------------------------------------------------
\subsubsection{Providing ASPs via {\tt FileName}}
% ----------------------------------------------------------------------

Suppose we have created the file ``asp.f'' as follows:
\begin{verbatim}
      DOUBLE PRECISION FUNCTION F(X)
      DOUBLE PRECISION X
      F=4.0D0/(X*X+1.0D0)
      RETURN
      END
\end{verbatim}
and wish to pass it to the NAG
routine {\bf d01ajf} which performs one-dimensional quadrature.
We can do this as follows:
\begin{verbatim}
d01ajf(0.0 ,1.0, 0.0, 1.0e-5, 800, 200, -1, "asp.f")
\end{verbatim}

% ----------------------------------------------------------------------
\subsection{General Fortran-generation utilities in Axiom}
\label{generalFortran}
\index{generalFortran}
% ----------------------------------------------------------------------

This section describes more advanced facilities which are available to users
who wish to generate Fortran code from within Axiom.  There are
facilities to manipulate templates, store type information, and generate
code fragments or complete programs.

% ----------------------------------------------------------------------
\subsubsection{Template Manipulation}
% ----------------------------------------------------------------------

A template is a skeletal program which is ``fleshed out'' with data when
it is processed.  It is a sequence of {\em active} and {\em passive} parts:
active parts are sequences of Axiom commands which are processed as if they
had been typed into the interpreter; passive parts are simply echoed
verbatim on the Fortran output stream.

Suppose, for example, that we have the following template, stored in
the file ``test.tem'':
\begin{verbatim}
-- A simple template
beginVerbatim
      DOUBLE PRECISION FUNCTION F(X)
      DOUBLE PRECISION X
endVerbatim
outputAsFortran("F",f)
beginVerbatim
      RETURN
      END
endVerbatim
\end{verbatim}
The passive parts lie between the two
tokens {\tt beginVerbatim} and {\tt endVerbatim}.  There
are two active statements: one which is simply an Axiom (\verb+--+)
comment, and one which produces an assignment to the current value
of {\tt f}.  We could use it as follows:
\begin{verbatim}
(4) ->f := 4.0/(1+X**2)

           4
   (4)   ------
          2
         X  + 1
                       
(5) ->processTemplate "test.tem"
      DOUBLE PRECISION FUNCTION F(X)
      DOUBLE PRECISION X
      F=4.0D0/(X*X+1.0D0)
      RETURN 
      END

   (5)  "CONSOLE"
\end{verbatim}

(A more reliable method of specifying the filename will be introduced
below.)  Note that the Fortran assignment {\tt F=4.0D0/(X*X+1.0D0)}
automatically converted 4.0 and 1 into DOUBLE PRECISION numbers; in
general, the Axiom Fortran generation facility will convert
anything which should be a floating point object into either
a Fortran REAL or DOUBLE PRECISION object.

Which alternative is used is determined by the command

\spadcommand{)set fortran precision}

It is sometimes useful to end a template before the file itself ends (e.g. to
allow the template to be tested incrementally or so that a piece of text
describing how the template works can be included).  It is of course possible
to ``comment-out'' the remainder of the file.  Alternatively, the single token
{\tt endInput} as part of an active portion of the template will cause
processing to be ended prematurely at that point.

The {\bf processTemplate} command comes in two flavours.  In the first case,
illustrated above, it takes one argument of domain {\tt FileName},
the name of the template to be processed, and writes its output on the
current Fortran output stream.  In general, a filename can be generated
from {\em directory}, {\em name} and {\em extension} components, using
the operation {\bf filename}, as in
\begin{verbatim}
processTemplate filename("","test","tem")
\end{verbatim}
There is an alternative version of {\bf processTemplate}, which
takes two arguments (both of domain {\tt FileName}).  In this case the
first argument is the name of the template to be processed, and the
second is the file in which to write the results.  Both versions return
the location of the generated Fortran code as their result
(``{\tt CONSOLE}'' in the above example).

It is sometimes useful to be able to mix active and passive parts of a
line or statement.  For example you might want to generate a Fortran
Comment describing your data set.  For this kind of application we
provide three functions as follows:

\begin{tabular}{p{1.8in}p{2.6in}}
{\bf fortranLiteral} & write string on the Fortran output stream \\
 & \\
{\bf fortranCarriageReturn} & 
writes a carriage return on the Fortran output stream \\
& \\
{\bf fortranLiteralLine} & writes a string followed by a return
on the Fortran output stream \\
\end{tabular}

So we could create our comment as follows:
\spadcommand{m := matrix [ [1,2,3],[4,5,6] ]}

\spadcommand{fortranLiteralLine concat ["C\ \ \ \ \ \ The\ Matrix\ has\ ", nrows(m)::String, "\ rows\ and\ ", ncols(m)::String, "\ columns"]}

or, alternatively:
\spadcommand{fortranLiteral "C\ \ \ \ \ \ The\ Matrix\ has\ "}

\spadcommand{fortranLiteral(nrows(m)::String)}

\spadcommand{fortranLiteral "\ rows\ and\ "}

\spadcommand{fortranLiteral(ncols(m)::String)}

\spadcommand{fortranLiteral "\ columns"}

\spadcommand{fortranCarriageReturn()}

We should stress that these functions, together with the {\bf outputAsFortran}
function are the {\em only} sure ways
of getting output to appear on the Fortran output stream.  Attempts to use
Axiom commands such as {\bf output} or {\bf writeline} may appear to give
the required result when displayed on the console, but will give the wrong
result when Fortran and algebraic output are sent to differing locations.  On
the other hand, these functions can be used to send helpful messages to the
user, without interfering with the generated Fortran.

% ----------------------------------------------------------------------
\subsubsection{Manipulating the Fortran Output Stream}
% ----------------------------------------------------------------------
\index{FortranOutputStackPackage}

Sometimes it is useful to manipulate the Fortran output stream in a program,
possibly without being aware of its current value.  The main use of this is
for gathering type declarations (see ``Fortran Types'' below) 
but it can be useful
in other contexts as well.  Thus we provide a set of commands to manipulate
a stack of (open) output streams.  Only one stream can be written to at
any given time.  The stack is never empty---its initial value is the
console or the current value of the Fortran output stream, and can be
determined using

\spadcommand{topFortranOutputStack()}

(see below).
The commands available to manipulate the stack are:

\begin{tabular}{ll}
{\bf clearFortranOutputStack} & resets the stack to the console \\
 & \\
{\bf pushFortranOutputStack} & pushes a {\tt FileName} onto the stack \\
 & \\
{\bf popFortranOutputStack} & pops the stack \\
 & \\
{\bf showFortranOutputStack} & returns the current stack \\
 & \\
{\bf topFortranOutputStack} & returns the top element of the stack \\
\end{tabular}

These commands are all part of {\tt FortranOutputStackPackage}.

% ----------------------------------------------------------------------
\subsubsection{Fortran Types}
% ----------------------------------------------------------------------

When generating code it is important to keep track of the Fortran types of
the objects which we are generating.  This is useful for a number of reasons,
not least to ensure that we are actually generating legal Fortran code.  The
current type system is built up in several layers, and we shall describe each
in turn.

% ----------------------------------------------------------------------
\subsubsection{FortranScalarType}
% ----------------------------------------------------------------------
\index{FortranScalarType}

This domain represents the simple Fortran datatypes: REAL, DOUBLE PRECISION,
COMPLEX, LOGICAL, INTEGER, and CHARACTER.
It is possible to {\bf coerce} a {\tt String} or {\tt Symbol}
into the domain, test whether two objects are equal, and also apply
the predicate functions \spadfunFrom{real?}{FortranScalarType} etc.

% ----------------------------------------------------------------------
\subsubsection{FortranType}
% ----------------------------------------------------------------------
\index{FortranType}

This domain represents ``full'' types: i.e., datatype plus array dimensions
(where appropriate) plus whether or not the parameter is an external
subprogram.  It is possible to {\bf coerce} an object of
{\tt FortranScalarType} into the domain or {\bf construct} one
from an element of {\tt FortranScalarType}, a list of
{\tt Polynomial Integer}s (which can of course be simple integers or
symbols) representing its dimensions, and
a {\tt Boolean} declaring whether it is external or not.  The list
of dimensions must be empty if the {\tt Boolean} is {\tt true}.
The functions {\bf scalarTypeOf}, {\bf dimensionsOf} and
{\bf external?} return the appropriate
parts, and it is possible to get the various basic Fortran Types via
functions like {\bf fortranReal}.

For example:
\spadcommand{type:=construct(real,[i,10],false)\$FortranType}

or
\spadcommand{type:=[real,[i,10],false]\$FortranType}

\spadcommand{scalarTypeOf type}

\spadcommand{dimensionsOf type}

\spadcommand{external?  type}

\spadcommand{fortranLogical()}

\spadcommand{construct(integer,[],true)\$FortranType}

% ----------------------------------------------------------------------
\subsubsection{SymbolTable}
% ----------------------------------------------------------------------
\index{SymbolTable}

This domain creates and manipulates a symbol table for generated Fortran code.
This is used by {\tt FortranProgram} to represent the types of objects in
a subprogram.  The commands available are:

\begin{tabular}{ll}
{\bf empty} & creates a new {\tt SymbolTable} \\
 & \\
{\bf declare} & creates a new entry in a table \\
 & \\
{\bf fortranTypeOf} & returns the type of an object in a table \\
 & \\
{\bf parametersOf} & returns a list of all the symbols in the table \\
 & \\
{\bf typeList} & returns a list of all objects of a given type \\
 & \\
{\bf typeLists} & returns a list of lists of all objects sorted by type \\
 & \\
{\bf externalList} & returns a list of all {\tt EXTERNAL} objects \\
 & \\
{\bf printTypes} & produces Fortran type declarations from a table\\
\end{tabular}

\spadcommand{symbols := empty()\$SymbolTable}

\spadcommand{declare!(X,fortranReal(),symbols)}

\spadcommand{declare!(M,construct(real,[i,j],false)\$FortranType,symbols)}

\spadcommand{declare!([i,j],fortranInteger(),symbols)}

\spadcommand{symbols}

\spadcommand{fortranTypeOf(i,symbols)}

\spadcommand{typeList(real,symbols)}

\spadcommand{printTypes symbols}

% ----------------------------------------------------------------------
\subsubsection{TheSymbolTable}
% ----------------------------------------------------------------------
\index{TheSymbolTable}

This domain creates and manipulates one global symbol table to be used, for
example, during template processing. It is
also used when
linking to external Fortran routines. The
information stored for each subprogram (and the main program segment, where
relevant) is:
\begin{itemize}
\item its name;
\item its return type;
\item its argument list;
\item and its argument types.
\end{itemize}
Initially, any information provided is deemed to be for the main program
segment.

Issuing the following command indicates that from now on all information
refers to the subprogram $F$.

\spadcommand{newSubProgram F}

It is possible to return to processing the main program segment by issuing
the command:

\spadcommand{endSubProgram()}

The following commands exist:

\begin{tabular}{p{1.6in}p{2.8in}}
{\bf returnType} & declares the return type of the current subprogram \\
 & \\
{\bf returnTypeOf} & returns the return type of a subprogram \\
 & \\
{\bf argumentList} &  declares the argument list of the current subprogram \\
 & \\
{\bf argumentListOf} &  returns the argument list of a subprogram \\
 & \\
{\bf declare} & 
provides type declarations for parameters of the current subprogram \\
 & \\
{\bf symbolTableOf} & returns the symbol table  of a subprogram \\
 & \\
{\bf printHeader} & produces the Fortran header for the current subprogram \\
\end{tabular}

In addition there are versions of these commands which are parameterised by
the name of a subprogram, and others parameterised by both the name of a
subprogram and by an instance of {\tt TheSymbolTable}.

\spadcommand{newSubProgram F}

\spadcommand{argumentList!(F,[X])}

\spadcommand{returnType!(F,real)}

\spadcommand{declare!(X,fortranReal(),F)}

\spadcommand{printHeader F}

% ----------------------------------------------------------------------
\subsubsection{Advanced Fortran Code Generation}
% ----------------------------------------------------------------------

This section describes facilities for representing Fortran statements, and
building up complete subprograms from them.

% ----------------------------------------------------------------------
\subsubsection{Switch}
% ----------------------------------------------------------------------
\index{Switch}

This domain is used to represent statements like {\tt x < y}.  Although
these can be represented directly in Axiom, it is a little cumbersome,
since Axiom evaluates the last statement, for example, to {\tt true}
(since $x$ is  lexicographically less than $y$).

Instead we have a set of operations, such as {\bf LT} to represent $<$,
to let us build such statements.  The available constructors are:

\begin{center}
\begin{tabular}{ll}
{\bf LT} & $<$ \\
{\bf GT} & $>$ \\
{\bf LE} & $\leq$ \\
{\bf GE} & $\geq$ \\
{\bf EQ} & $=$ \\
{\bf AND} & {\tt and}\\
{\bf OR} & {\tt or} \\
{\bf NOT} & {\tt not} \\
\end{tabular}
\end{center}

So for example:
\spadcommand{LT(x,y)}

% ----------------------------------------------------------------------
\subsubsection{FortranCode}
% ----------------------------------------------------------------------

This domain represents code segments or operations: currently assignments,
conditionals, blocks, comments, gotos, continues, various kinds of loops,
and return statements.

For example we can create quite a complicated conditional statement using
assignments, and then turn it into Fortran code:

\spadcommand{c := cond(LT(X,Y),assign(F,X),cond(GT(Y,Z),assign(F,Y),assign(F,Z)))}

\spadcommand{printCode c}

The Fortran code is printed
on the current Fortran output stream.

% ----------------------------------------------------------------------
\subsubsection{FortranProgram}
% ----------------------------------------------------------------------
\index{FortranProgram}

This domain is used to construct complete Fortran subprograms out of
elements of {\tt Fortran\-Code}.  It is parameterised by the name of the
target subprogram (a {\tt Symbol}), its return type (from
{\tt Union}({\tt FortranScalarType},``void'')),
its arguments (from {\tt List Symbol}), and
its symbol table (from {\tt SymbolTable}).  One can
{\bf coerce} elements of either {\tt FortranCode}
or {\tt Expression} into it.


First of all we create a symbol table:

\spadcommand{symbols := empty()\$SymbolTable}

Now put some type declarations into it:

\spadcommand{declare!([X,Y],fortranReal(),symbols)}

Then (for convenience)
we set up the particular instantiation of {\tt FortranProgram}

\spadcommand{FP := FortranProgram(F,real,[X,Y],symbols)}

Create an object of type {\tt Expression(Integer)}:

\spadcommand{asp := X*sin(Y)}

Now {\bf coerce} it into {\tt FP}, and print its Fortran form:

\spadcommand{outputAsFortran(asp::FP)}

We can generate a {\tt FortranProgram} using $FortranCode$.  For
example:

Augment our symbol table:

\spadcommand{declare!(Z,fortranReal(),symbols)}

and transform the conditional expression we prepared earlier:

\spadcommand{outputAsFortran([c,returns()]::FP)}

%------------------------------------------------------------------------
\subsection{Some technical information}
\index{nagTechnical}
%------------------------------------------------------------------------

The model adopted for the link is a server-client configuration
-- Axiom acting as a client via a local agent
(a process called {\tt nagman}). The server side is implemented
by the {\tt nagd} daemon process which may run on a different host.
The {\tt nagman} local agent is started by default whenever you
start Axiom. The {\tt nagd} server must be started separately.
Instructions for installing and running the server are supplied
in by NAG.
Use the {\tt )set naglink host} system command
to point your local agent to a server in your network.



On the Axiom side, one sees a set of {\em packages}
(ask Browse for {\em Nag*}) for each chapter, each exporting
operations with the same name as a routine in the Nag Library.
The arguments and return value of each operation belong to
standard Axiom types.

The {\tt man} pages for the Nag Library are accessible via the description
of each operation in Browse (among other places).

In the implementation of each operation, the set of inputs is passed
to the local agent {\tt nagman}, which makes a
Remote Procedure Call (RPC) to the
remote {\tt nagd} daemon process.  The local agent receives the RPC
results and forwards them to the Axiom workspace where they
are interpreted appropriately.

How are Fortran subroutines turned into RPC calls?
For each Fortran routine in the Nag Library, a C main() routine
is supplied.
Its job is to assemble the RPC input (numeric) data stream into
the appropriate Fortran data structures for the routine, call the Fortran
routine from C and serialize the results into an RPC output data stream.

Many Nag Library routines accept ASPs (Argument Subprogram Parameters).
These specify user-supplied Fortran routines (e.g. a routine to
supply values of a function is required for numerical integration).
How are they handled? There are new facilities in Axiom to help.
A set of Axiom domains has been provided to turn values in standard
 Axiom types (such as Expression Integer) into the appropriate
piece of Fortran for each case (a filename pointing to Fortran source
for the ASP can always be supplied instead).
Ask Browse for {\em Asp*} to see these domains. The Fortran fragments
are included in the outgoing RPC stream, but {\tt nagd} intercepts them,
compiles them, and links them with the main() C program before executing
the resulting program on the numeric part of the RPC stream.


%------------------------------------------------------------------------
\section{Interactive Front-end and Language}
\index{ugWhatsNewLanguage}
%------------------------------------------------------------------------

The {\tt leave} keyword has been replaced by the
{\tt break} keyword for compatibility with the new Axiom
extension language.
See \sectionref{ugLangLoopsBreak} for more information.

Curly braces are no longer used to create sets. Instead, use
{\bf set} followed by a bracketed expression. For example,

\spadcommand{set [1,2,3,4]}

Curly braces are now used to enclose a block (see section
\sectionref{ugLangBlocks} 
for more information). For compatibility, a block can still be 
enclosed by parentheses as well.

``Free functions'' created by the Aldor compiler can now be
loaded and used within the Axiom interpreter. A {\it free
function} is a library function that is implemented outside a
domain or category constructor.

New coercions to and from type {\tt Expression} have been
added. For example, it is now possible to map a polynomial
represented as an expression to an appropriate polynomial type.

Various messages have been added or rewritten for clarity.

%------------------------------------------------------------------------
\section{Library}
\index{ugWhatsNewLibrary}
%------------------------------------------------------------------------

The {\tt FullPartialFractionExpansion}
domain has been added. This domain computes factor-free full
partial fraction expansions.
See section
FullPartialFractionExpansion
for examples.

We have implemented the Bertrand/Cantor algorithm for integrals of
hyperelliptic functions. This brings a major speedup for some
classes of algebraic integrals.

We have implemented a new (direct) algorithm for integrating trigonometric
functions. This brings a speedup and an improvement in the answer
quality.

The {\sf SmallFloat} domain has been renamed
{\tt DoubleFloat} and {\sf SmallInteger} has been renamed
{\tt SingleInteger}. The new abbreviations as
{\tt DFLOAT} and {\tt SINT}, respectively.
We have defined the macro {\sf SF}, the old abbreviation for {\sf
SmallFloat}, to expand to {\tt DoubleFloat} and modified
the documentation and input file examples to use the new names
and abbreviations. You should do the same in any private Axiom
files you have.

There are many new categories, domains and packages related to the
NAG Library Link facility. See the file

src/algebra/exposed.lsp

for a list of constructors in the {\bf naglink} Axiom exposure group.

We have made improvements to the differential equation solvers
and there is a new facility for solving systems of first-order 
linear differential equations.
In particular, an important fix was made to the solver for
inhomogeneous linear ordinary differential equations that
corrected the calculation of particular solutions.
We also made improvements to the polynomial
and transcendental equation solvers including the
ability to solve some classes of systems of transcendental
equations.

The efficiency of power series have been improved and left and right
expansions of $tan(f(x))$ at $x =$ a pole of $f(x)$
can now be computed.
A number of power series bugs were fixed and the 
{\tt GeneralUnivariatePowerSeries}
domain was added.
The power series variable can appear in the coefficients and when this
happens, you cannot differentiate or integrate the series.  Differentiation
and integration with respect to other variables is supported.

A domain was added for representing asymptotic expansions of a
function at an exponential singularity.

For limits, the main new feature is the exponential expansion domain used
to treat certain exponential singularities.  Previously, such singularities
were treated in an {\it ad hoc} way and only a few cases were covered.  Now
Axiom can do things like

\begin{verbatim}
limit( (x+1)**(x+1)/x**x - x**x/(x-1)**(x-1), x = %plusInfinity)
\end{verbatim}

in a systematic way.  It only does one level of nesting, though.  In other
words, we can handle $exp(some function with a pole)$, but not
$exp(exp(some function with a pole))$.

The computation of integral bases has been improved through careful
use of Hermite row reduction. A P-adic algorithm
for function fields of algebraic curves in finite characteristic has also
been developed.

Miscellaneous:
There is improved conversion of definite and indefinite integrals to\\
{\tt InputForm}; binomial coefficients are displayed in a new way;\\
some new simplifications of radicals have been implemented;\\
the operation {\bf complexForm} for converting to rectangular\\ 
coordinates has been added; symmetric product operations have been\\ 
added to {\tt LinearOrdinaryDifferential\-Operator}.

%------------------------------------------------------------------------
\section{HyperTex}
\index{ugWhatsNewHyperDoc}
%------------------------------------------------------------------------

The buttons on the titlebar and scrollbar have been replaced
with ones which have a 3D effect. You can change the foreground and
background colors of these ``controls'' by including and modifying
the following lines in your {\bf .Xdefaults} file.
\begin{verbatim}
Axiom.hyperdoc.ControlBackground: White
Axiom.hyperdoc.ControlForeground: Black
\end{verbatim}

For various reasons, HyperDoc sometimes displays a
secondary window. You can control the size and placement of this
window by including and modifying
the following line in your {\bf .Xdefaults} file.
%
\begin{verbatim}
Axiom.hyperdoc.FormGeometry: =950x450+100+0
\end{verbatim}
%
This setting is a standard X Window System geometry specification:
you are requesting a window 950 pixels wide by 450 deep and placed in
the upper left corner.

Some key definitions have been changed to conform more closely
with the CUA guidelines. Press
F9
to see the current definitions.

Input boxes (for example, in the Browser) now accept paste-ins from
the X Window System. Use the second button to paste in something
you have previously copied or cut. An example of how you can use this
is that you can paste the type from an Axiom computation
into the main Browser input box.


%------------------------------------------------------------------------
\section{Documentation}
\index{ugWhatsNewDocumentation}
%------------------------------------------------------------------------

We describe here a few additions to the on-line
version of the Axiom book which you can read with
HyperDoc.


A section has been added to the graphics chapter, describing
how to build two-di\-men\-sion\-al graphs from lists of points. An example is
given showing how to read the points from a file.
See \sectionref{ugGraphTwoDbuild} for details.

A further section has been added to that same chapter, describing
how to add a two-di\-men\-sion\-al graph to a viewport which already
contains other graphs.
See \sectionref{ugGraphTwoDappend} for details.

Chapter 3 
and the on-line HyperDoc help have been unified.

An explanation of operation names ending in ``?'' and ``!'' has
been added to the first chapter. 
See the end of the \sectionref{ugIntroCallFun} for details.

An expanded explanation of using predicates has
been added to the sixth chapter. See the
example involving {\bf evenRule} in the middle of the 
\sectionref{ugUserRules} for details.

Documentation for the {\tt )compile}, {\tt )library} and
{\tt )load} commands has been greatly changed. This reflects
the ability of the {\tt )compile} to now invoke the Aldor
compiler, the impending deletion of the {\tt )load} command
and the new {\tt )library} command.
The {\tt )library} command replaces {\tt )load} and is
compatible with the compiled output from both the old and new
compilers.


%\setcounter{chapter}{0} % Appendix A

\appendix

%Original Page 571

\chapter{Axiom System Commands}
\label{ugSysCmd}

This chapter describes system commands, the command-line
facilities used to control the Axiom environment.
The first section is an introduction and discusses the common
syntax of the commands available.

\section{Introduction}
\label{ugSysCmdOverview}

System commands are used to perform Axiom environment
management.
Among the commands are those that display what has been defined or
computed, set up multiple logical Axiom environments
(frames), clear definitions, read files of expressions and
commands, show what functions are available, and terminate
Axiom.

Some commands are restricted: the commands
\index{set userlevel interpreter}
\index{set userlevel compiler}
\index{set userlevel development}
\begin{verbatim}
)set userlevel interpreter
)set userlevel compiler
)set userlevel development
\end{verbatim}
set the user-access level to the three possible choices.
All commands are available at {\tt development} level and the fewest
are available at {\tt interpreter} level.
The default user-level is {\tt interpreter}.
\index{user-level}
In addition to the {\tt )set} command (discussed in 
\sectionref{ugSysCmdset}
you can use the HyperDoc settings facility to change the {\it user-level.}


Each command listing begins with one or more syntax pattern descriptions
plus examples of related commands.
The syntax descriptions are intended to be easy to read and do not
necessarily represent the most compact way of specifying all
possible arguments and options; the descriptions may occasionally
be redundant.

All system commands begin with a right parenthesis which should be in
the first available column of the input line (that is, immediately
after the input prompt, if any).
System commands may be issued directly to Axiom or be
included in {\bf .input} files.
\index{file!input}

%Original Page 572

A system command {\it argument} is a word that directly
follows the command name and is not followed or preceded by a
right parenthesis.
A system command {\it option} follows the system command and
is directly preceded by a right parenthesis.
Options may have arguments: they directly follow the option.
This example may make it easier to remember what is an option and
what is an argument:

\begin{center}
{\tt )syscmd {\it arg1 arg2} )opt1 
{\it opt1arg1 opt1arg2} )opt2 {\it opt2arg1} ...}
\end{center}

In the system command descriptions, optional arguments and options are
enclosed in brackets (``\lanb'' and ``\ranb'').
If an argument or option name is in italics, it is
meant to be a variable and must have some actual value substituted
for it when the system command call is made.
For example, the syntax pattern description

\noindent
{\tt )read} {\it fileName} {\tt \lanb{})quietly\ranb{}}

\noindent
would imply that you must provide an actual file name for
{\it fileName} but need not use the {\tt )quietly} option.
Thus
\begin{verbatim}
)read matrix.input
\end{verbatim}
is a valid instance of the above pattern.

System command names and options may be abbreviated and may be in
upper or lower case.
The case of actual arguments may be significant, depending on the
particular situation (such as in file names).
System command names and options may be abbreviated to the minimum
number of starting letters so that the name or option is unique.
Thus
\begin{verbatim}
)s Integer
\end{verbatim}
is not a valid abbreviation for the {\tt )set} command,
because both {\tt )set} and {\tt )show}
begin with the letter ``s''.
Typically, two or three letters are sufficient for disambiguating names.
In our descriptions of the commands, we have used no abbreviations for
either command names or options.

In some syntax descriptions we use a vertical line ``\vertline''
to indicate that you must specify one of the listed choices.
For example, in
\begin{verbatim}
)set output fortran on | off
\end{verbatim}
only {\tt on} and {\tt off} are acceptable words for following
{\tt boot}.
We also sometimes use ``...'' to indicate that additional arguments
or options of the listed form are allowed.
Finally, in the syntax descriptions we may also list the syntax of
related commands.

\section{)abbreviation}
\index{abbreviation}


\par\noindent{\bf User Level Required:} compiler

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )abbreviation query  \lanb{}{\it nameOrAbbrev}\ranb{}}
\item {\tt )abbreviation category  {\it abbrev  fullname} \lanb{})quiet\ranb{}}
\item {\tt )abbreviation domain  {\it abbrev  fullname}   \lanb{})quiet\ranb{}}
\item {\tt )abbreviation package  {\it abbrev  fullname}  \lanb{})quiet\ranb{}}
\item {\tt )abbreviation remove  {\it nameOrAbbrev}}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to query, set and remove abbreviations for category,
domain and package constructors.
Every constructor must have a unique abbreviation.

%Original Page 573

This abbreviation is part of the name of the subdirectory
under which the components of the compiled constructor are
stored.
%% BEGIN OBSOLETE
% It is this abbreviation that is used to bring compiled code into
% Axiom with the {\tt )load} command.
%% END OBSOLETE
Furthermore, by issuing this command you
let the system know what file to load automatically if you use a new
constructor.
Abbreviations must start with a letter and then be followed by
up to seven letters or digits.
Any letters appearing in the abbreviation must be in uppercase.

When used with the {\tt query} argument,
\index{abbreviation query}
this command may be used to list the name
associated with a  particular abbreviation or the  abbreviation for a
constructor.
If no abbreviation or name is given, the names and corresponding
abbreviations for {\it all} constructors are listed.

The following shows the abbreviation for the constructor {\tt List}:
\begin{verbatim}
)abbreviation query List
\end{verbatim}
The following shows the constructor name corresponding to the
abbreviation {\tt NNI}:
\begin{verbatim}
)abbreviation query NNI
\end{verbatim}
The following lists all constructor names and their abbreviations.
\begin{verbatim}
)abbreviation query
\end{verbatim}

To add an abbreviation for a constructor, use this command with
{\tt category}, {\tt domain} or {\tt package}.
\index{abbreviation package}
\index{abbreviation domain}
\index{abbreviation category}
The following add abbreviations to the system for a
category, domain and package, respectively:
\begin{verbatim}
)abbreviation domain   SET Set
)abbreviation category COMPCAT  ComplexCategory
)abbreviation package  LIST2MAP ListToMap
\end{verbatim}
If the {\tt )quiet} option is used,
no output is displayed from this command.
You would normally only define an abbreviation in a library source file.
If this command is issued for a constructor that has already been loaded, the
constructor will be reloaded next time it is referenced.  In particular, you
can use this command to force the automatic reloading of constructors.

To remove an abbreviation, the {\tt remove} argument is used.
\index{abbreviation remove}
This is usually
only used to correct a previous command that set an abbreviation for a
constructor name.
If, in fact, the abbreviation does exist, you are prompted
for confirmation of the removal request.
Either of the following commands
will remove the abbreviation {\tt VECTOR2} and the
constructor name {\tt VectorFunctions2} from the system:
\begin{verbatim}
)abbreviation remove VECTOR2
)abbreviation remove VectorFunctions2
\end{verbatim}

\par\noindent{\bf Also See:}
{\tt )compile} \index{ugSysCmdcompile} 

\section{)browse}
\index{browse}
\par\noindent{\bf User Level Required:} interpreter
\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )browse}
\end{list}

\par\noindent{\bf Command Description:}

The browse command changes the interpreter command loop to listen
for http connections on IP address 127.0.0.1 port 8085.

In order to access the new pages start Firefox.
Assuming the path to the file rootpage.xhtml is:\\
{\tt /spad/mnt/linux/doc/hypertex/rootpage.xhtml}\\
you would visit the URL:\\
{\tt 127.0.0.1:8085/spad/mnt/linux/doc/hypertex/rootpage.xhtml}

Note that it may be necessary to install fonts into the Firefox
browser in order to see correct mathML mathematics output. See
the faq file for details.

%Original Page 574

\section{)cd}
\label{ugSysCmdcd}
\index{ugSysCmdcd}

\index{cd}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )cd} {\it directory}
\end{list}

\par\noindent{\bf Command Description:}

This command sets the Axiom working current directory.
The current directory is used for looking for
input files (for {\tt )read}),
Axiom library source files (for {\tt )compile}),
saved history environment files (for {\tt )history )restore}),
compiled Axiom library files (for {\tt )library}), and
files to edit (for {\tt )edit}).
It is also used for writing
spool files (via {\tt )spool}),
writing history input files (via {\tt )history )write}) and
history environment files (via {\tt )history )save}),and
compiled Axiom library files (via {\tt )compile}).
\index{read}
\index{compile}
\index{history )restore}
\index{edit}
\index{spool}
\index{history )write}
\index{history )save}

If issued with no argument, this command sets the Axiom
current directory to your home directory.
If an argument is used, it must be a valid directory name.
Except for the ``{\tt )}'' at the beginning of the command,
this has the same syntax as the operating system {\tt cd} command.

\par\noindent{\bf Also See:}
{\tt )compile} \index{ugSysCmdcompile},
{\tt )edit} \index{ugSysCmdedit},
{\tt )history} \index{ugSysCmdhistory},
{\tt )library} \index{ugSysCmdlibrary},
{\tt )read} \index{ugSysCmdread}, and
{\tt )spool} \index{ugSysCmdspool}.

\section{)clear}
\index{ugSysCmdclear}

\index{clear}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )clear all}
\item{\tt )clear completely}
\item{\tt )clear properties all}
\item{\tt )clear properties}  {\it obj1 \lanb{}obj2 ...\ranb{}}
\item{\tt )clear value      all}
\item{\tt )clear value}     {\it obj1 \lanb{}obj2 ...\ranb{}}
\item{\tt )clear mode       all}
\item{\tt )clear mode}      {\it obj1 \lanb{}obj2 ...\ranb{}}
\end{list}
\par\noindent{\bf Command Description:}

This command is used to remove function and variable declarations, definitions
and values  from the workspace.
To  empty the entire workspace  and reset the
step counter to 1, issue
\begin{verbatim}
)clear all
\end{verbatim}
To remove everything in the workspace but not reset the step counter, issue
\begin{verbatim}
)clear properties all
\end{verbatim}
To remove everything about the object {\tt x}, issue

%Original Page 575

\begin{verbatim}
)clear properties x
\end{verbatim}
To remove everything about the objects {\tt x, y} and {\tt f}, issue
\begin{verbatim}
)clear properties x y f
\end{verbatim}

The word {\tt properties} may be abbreviated to the single letter
``{\tt p}''.
\begin{verbatim}
)clear p all
)clear p x
)clear p x y f
\end{verbatim}
All definitions of functions and values of variables may be removed by either
\begin{verbatim}
)clear value all
)clear v all
\end{verbatim}
This retains whatever declarations the objects had.  To remove definitions and
values for the specific objects {\tt x, y} and {\tt f}, issue
\begin{verbatim}
)clear value x y f
)clear v x y f
\end{verbatim}
To remove  the declarations  of everything while  leaving the  definitions and
values, issue
\begin{verbatim}
)clear mode  all
)clear m all
\end{verbatim}
To remove declarations for the specific objects {\tt x, y} and {\tt f}, issue
\begin{verbatim}
)clear mode x y f
)clear m x y f
\end{verbatim}
The {\tt )display names} and {\tt )display properties} commands  may be used
to see what is currently in the workspace.

The command
\begin{verbatim}
)clear completely
\end{verbatim}
does everything that {\tt )clear all} does, and also clears the internal
system function and constructor caches.

\par\noindent{\bf Also See:}
{\tt )display} \index{ugSysCmddisplay},
{\tt )history} \index{ugSysCmdhistory}, and
{\tt )undo} \index{ugSysCmdundo}.

\section{)close}
\index{ugSysCmdclose}

\index{close}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )close}
\item{\tt )close )quietly}
\end{list}
\par\noindent{\bf Command Description:}

This command is used to close down interpreter client processes.
Such processes are started by HyperDoc to run Axiom examples
when you click on their text. When you have finished examining or modifying the
example and you do not want the extra window around anymore, issue
\begin{verbatim}
)close
\end{verbatim}
to the Axiom prompt in the window.

If you try to close down the last remaining interpreter client
process, Axiom will offer to close down the entire Axiom
session and return you to the operating system by displaying something
like
\begin{verbatim}
   This is the last Axiom session. Do you want to kill Axiom?
\end{verbatim}
Type ``{\tt y}'' (followed by the Return key) if this is what you had in mind.
Type ``{\tt n}'' (followed by the Return key) to cancel the command.

You can use the {\tt )quietly} option to force Axiom to
close down the interpreter client process without closing down
the entire Axiom session.

\par\noindent{\bf Also See:}
{\tt )quit} \index{ugSysCmdquit} and
{\tt )pquit} \index{ugSysCmdpquit}.

\section{)compile}
\label{ugSysCmdcompile}
\index{ugSysCmdcompile}

\index{compile}

\par\noindent{\bf User Level Required:} compiler

\par\noindent{\bf Command Syntax:}

\begin{list}{}
\item {\tt )compile}
\item {\tt )compile {\it fileName}}
\item {\tt )compile {\it fileName}.spad}
\item {\tt )compile {\it directory/fileName}.spad}
\item {\tt )compile {\it fileName} )quiet}
\item {\tt )compile {\it fileName} )noquiet}
\item {\tt )compile {\it fileName} )break}
\item {\tt )compile {\it fileName} )nobreak}
\item {\tt )compile {\it fileName} )library}
\item {\tt )compile {\it fileName} )nolibrary}
\item {\tt )compile {\it fileName} )vartrace}
\item {\tt )compile {\it fileName} )constructor} {\it nameOrAbbrev}
\end{list}

%Original Page 576

\par\noindent{\bf Command Description:}

You use this command to invoke the Axiom library compiler.  This
compiles files with file extension {\tt .spad} with the Axiom system
compiler. The command first looks in the standard system directories
for files with extension {\tt .spad}.
 
Should you not want the {\tt )library} command automatically invoked, 
call {\tt )compile} with the {\tt )nolibrary} option. For example,
\begin{verbatim} 
)compile mycode )nolibrary
\end{verbatim} 
By default, the {\tt )library} system command exposes all domains and 
categories it processes. This means that the Axiom intepreter will consider 
those domains and categories when it is trying to resolve a reference to a 
function.
Sometimes domains and categories should not be exposed. For example, a domain
may just be used privately by another domain and may not be meant for
top-level use. The {\tt )library} command should still be used, though, so 
that the code will be loaded on demand. In this case, you should use the 
{\tt )nolibrary} option on {\tt )compile} and the {\tt )noexpose} option in 
the {\tt )library} command. For
example,
\begin{verbatim} 
)compile mycode.spad )nolibrary
)library mycode )noexpose
\end{verbatim} 
Once you have established your own collection of compiled code, you may find
it handy to use the )dir option on the )library command. This causes )library
to process all compiled code in the specified directory. For example,
\begin{verbatim} 
)library )dir /u/jones/quantum
\end{verbatim} 
You must give an explicit directory after )dir, even if you want all compiled
code in the current working directory processed.
\begin{verbatim} 
)library )dir .
\end{verbatim} 
You can compile category, domain, and package constructors contained in files
with file extension {\tt .spad}. You can compile individual constructors or 
every constructor in a file.
 
The full filename is remembered between invocations of this command and 
{\tt )edit} commands. The sequence of commands
\begin{verbatim} 
)compile matrix.spad
)edit
)compile
\end{verbatim} 
will call the compiler, edit, and then call the compiler again on the file
matrix.spad. If you do not specify a directory, the working current directory
(see description of command )cd ) is searched for the file. If the file is
not found, the standard system directories are searched.
 
If you do not give any options, all constructors within a file are compiled.
Each constructor should have an {\tt )abbreviation} command in the file in 
which it is defined. We suggest that you place the {\tt )abbreviation} 
commands at the top of the file in the order in which the constructors are 
defined. The list of commands serves as a table of contents for the file.
 
The {\tt )library} option causes directories containing the compiled code 
for each constructor to be created in the working current directory. The 
name of such a directory consists of the constructor abbreviation and the 
{\tt .nrlib} file extension. For example, the directory containing the 
compiled code for the {\tt MATRIX} constructor is called {\bf MATRIX.nrlib}. 
The {\tt )nolibrary} option says that such files should not be created. 
 
The {\tt )vartrace} option causes the compiler to generate extra code for the
constructor to support conditional tracing of variable assignments. 
(see \sectionref{ugSysCmdtrace}). Without this option, this code is suppressed
and one cannot use the )vars option for the trace command.
 
The {\tt )constructor} option is used to specify a particular\\ 
constructor to compile. All other constructors in the file are\\ 
ignored. The constructor name or abbreviation follows {\tt )constructor}.\\ 
Thus either

\begin{verbatim} 
)compile matrix.spad )constructor RectangularMatrix
\end{verbatim}
or
\begin{verbatim} 
)compile matrix.spad )constructor RMATRIX
\end{verbatim}
compiles the {\tt RectangularMatrix} constructor defined in {\bf matrix.spad}.
 
The {\tt )break} and {\tt )nobreak} options determine what the compiler does
when it encounters an error. {\tt )break} is the default and it indicates that
processing should stop at the first error. The value of the {\tt )set break}
variable then controls what happens.
 
\par\noindent{\bf Also See:}
{\tt )abbreviation} \index{ugSysCmdabbreviation},
{\tt )edit} \index{ugSysCmdedit}, and
{\tt )library} \index{ugSysCmdlibrary}.

\section{)copyright}
\index{copyright}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )copyright}
\end{list}
\par\noindent{\bf Command Description:}

This command will show the text of the various licenses used
within the Axiom system.

\section{)credits}
\index{credits}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )credits}
\end{list}
\par\noindent{\bf Command Description:}

This command will show the list of names of people who have
contributed to Axiom.

\section{)describe}
\index{credits}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )describe categoryName}
\item{\tt )describe domainName}
\item{\tt )describe packageName}
\end{list}
\par\noindent{\bf Command Description:}

Given a categoryName, domainName, or a packageName it writes
some descriptive information to the console stream. For example,
\begin{verbatim}
)describe Set
A set over a domain D models the usual mathematical notion of a
finite set of elements from D. Sets are unordered collections of
distinct elements (that is, order and duplication does not matter).
The notation set [a,b,c] can be used to create a set and the usual
operations such as union and intersection are available to form new
sets. In our implementation, Language maintains the entries in sorted
order. Specifically, the parts function returns the entries as a list
in ascending order and the extract operation returns the maximum
entry. Given two sets s and t where #s = m and #t = n, the complexity
of
      s = t is O(min(n,m))
      s < t is O(max(n,m))
      union(s,t), intersect(s,t), minus(s,t),
           member(x,t) is O(n log n)
 
      insert(x,t) and remove(x,t) is O(n)
\end{verbatim}

\section{)display}
\index{ugSysCmddisplay}

\index{display}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )display all}
\item {\tt )display properties}
\item {\tt )display properties all}
\item {\tt )display properties} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}}
\item {\tt )display value all}
\item {\tt )display value} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}}
\item {\tt )display mode all}
\item {\tt )display mode} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}}
\item {\tt )display names}
\item {\tt )display operations} {\it opName}
\end{list}
\par\noindent{\bf Command Description:}

This command is  used to display the contents of  the workspace and
signatures of functions  with a  given  name.\footnote{A
{\it signature} gives the argument and return types of a
function.}

The command
\begin{verbatim}
)display names
\end{verbatim}
lists the names of all user-defined  objects in the workspace.  This is useful
if you do  not wish to see everything  about the objects and need  only be
reminded of their names.

The commands
\begin{verbatim}
)display all
)display properties
)display properties all
\end{verbatim}
all do  the same thing: show  the values and  types and declared modes  of all
variables in the  workspace.  If you have defined  functions, their signatures
and definitions will also be displayed.

To show all information about a  particular variable or user functions,
for example, something named {\tt d}, issue
\begin{verbatim}
)display properties d
\end{verbatim}
To just show the value (and the type) of {\tt d}, issue
\begin{verbatim}
)display value d
\end{verbatim}
To just show the declared mode of {\tt d}, issue

%Original Page 578

\begin{verbatim}
)display mode d
\end{verbatim}

All modemaps for a given operation  may be
displayed by using {\tt )display operations}.
A {\it modemap} is a collection of information about  a particular
reference
to an  operation.  This  includes the  types of the  arguments and  the return
value, the  location of the  implementation and  any conditions on  the types.
The modemap may contain patterns.  The following displays the modemaps for the
operation \spadfunFrom{complex}{ComplexCategory}:
\begin{verbatim}
)d op complex
\end{verbatim}

\par\noindent{\bf Also See:}
{\tt )clear} \index{ugSysCmdclear},
{\tt )history} \index{ugSysCmdhistory},
{\tt )set} \index{ugSysCmdset},
{\tt )show} \index{ugSysCmdshow}, and
{\tt )what} \index{ugSysCmdwhat}.


\section{)edit}
\index{ugSysCmdedit}

\index{edit}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )edit} \lanb{}{\it filename}\ranb{}
\end{list}
\par\noindent{\bf Command Description:}

This command is  used to edit files.
It works in conjunction  with the {\tt )read}
and {\tt )compile} commands to remember the name
of the file on which you are working.
By specifying the name fully, you  can edit any file you wish.
Thus
\begin{verbatim}
)edit /u/julius/matrix.input
\end{verbatim}
will place  you in an editor looking at the  file
{\tt /u/julius/matrix.input}.
\index{editing files}
By default, the editor is {\tt vi},
\index{vi}
but if you have an EDITOR shell environment variable defined, that editor
will be used.
When Axiom is running under the X Window System,
it will try to open a separate {\tt xterm} running your editor if
it thinks one is necessary.
\index{Korn shell}
For example, under the Korn shell, if you issue
\begin{verbatim}
export EDITOR=emacs
\end{verbatim}
then the emacs
\index{emacs}
editor will be used by {\tt )edit}.

If you do not specify a file name, the last file you edited,
read or compiled will be used.
If there is no ``last file'' you will be placed in the editor editing
an empty unnamed file.

It is possible to use the {\tt )system} command to edit a file directly.
For example,
\begin{verbatim}
)system emacs /etc/rc.tcpip
\end{verbatim}
calls {\tt emacs} to edit the file.
\index{emacs}

\par\noindent{\bf Also See:}
{\tt )system} \index{ugSysCmdsystem},
{\tt )compile} \index{ugSysCmdcompile}, and
{\tt )read} \index{ugSysCmdread}.


\section{)fin}
\index{ugSysCmdfin}

\index{fin}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )fin}
\end{list}
\par\noindent{\bf Command Description:}

%Original Page 579

This command is used by Axiom
developers to leave the Axiom system and return
to the underlying Common Lisp system.
To return to Axiom, issue the
``{\tt (\vertline{}spad\vertline{})}''
function call to Common Lisp.

\par\noindent{\bf Also See:}
{\tt )pquit} \index{ugSysCmdpquit} and
{\tt )quit} \index{ugSysCmdquit}.


\section{)frame}
\label{ugSysCmdframe}
\index{ugSysCmdframe}

\index{frame}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )frame  new  {\it frameName}}
\item{\tt )frame  drop  {\it \lanb{}frameName\ranb{}}}
\item{\tt )frame  next}
\item{\tt )frame  last}
\item{\tt )frame  names}
\item{\tt )frame  import {\it frameName} 
{\it \lanb{}objectName1 \lanb{}objectName2 ...\ranb{}\ranb{}}}
\item{\tt )set message frame on \vertline{} off}
\item{\tt )set message prompt frame}
\end{list}

\par\noindent{\bf Command Description:}

A {\it frame} can be thought of as a logical session within the
physical session that you get when you start the system.  You can
have as many frames as you want, within the limits of your computer's
storage, paging space, and so on.
Each frame has its own {\it step number}, {\it environment} and {\it history.}
You can have a variable named {\tt a} in one frame and it will
have nothing to do with anything that might be called {\tt a} in
any other frame.

Some frames are created by the HyperDoc program and these can
have pretty strange names, since they are generated automatically.
\index{frame names}
To find out the names
of all frames, issue
\begin{verbatim}
)frame names
\end{verbatim}
It will indicate the name of the current frame.

You create a new frame
\index{frame new}
``{\bf quark}'' by issuing
\begin{verbatim}
)frame new quark
\end{verbatim}
The history facility can be turned on by issuing either
{\tt )set history on} or {\tt )history )on}.
If the history facility is on and you are saving history information
in a file rather than in the Axiom environment
then a history file with filename {\bf quark.axh} will
be created as you enter commands.
If you wish to go back to what
you were doing in the
\index{frame next}
``{\bf initial}'' frame, use
\index{frame last}
\begin{verbatim}
)frame next
\end{verbatim}
or
\begin{verbatim}
)frame last
\end{verbatim}
to cycle through the ring of available frames to get back to
``{\bf initial}''.

If you want to throw
away a frame (say ``{\bf quark}''), issue
\begin{verbatim}
)frame drop quark
\end{verbatim}
If you omit the name, the current frame is dropped.
\index{frame drop}

%Original Page 580

If you do use frames with the history facility on and writing to a file,
you may want to delete some of the older history files.
\index{file!history}
These are directories, so you may want to issue a command like
{\tt rm -r quark.axh} to the operating system.

You can bring things from another frame by using
\index{frame import}
{\tt )frame import}.
For example, to bring the {\tt f} and {\tt g} from the frame ``{\bf quark}''
to the current frame, issue
\begin{verbatim}
)frame import quark f g
\end{verbatim}
If you want everything from the frame ``{\bf quark}'', issue
\begin{verbatim}
)frame import quark
\end{verbatim}
You will be asked to verify that you really want everything.

There are two {\tt )set} flags
\index{set message frame}
to make it easier to tell where you are.
\begin{verbatim}
)set message frame on | off
\end{verbatim}
will print more messages about frames when it is set on.
By default, it is off.
\begin{verbatim}
)set message prompt frame
\end{verbatim}
will give a prompt
\index{set message prompt frame}
that looks like
\begin{verbatim}
initial (1) ->
\end{verbatim}
\index{prompt!with frame name}
when you start up. In this case, the frame name and step make up the
prompt.

\par\noindent{\bf Also See:}
{\tt )history} \index{ugSysCmdhistory} and
{\tt )set} \index{ugSysCmdset}.


\section{)help}
\index{ugSysCmdhelp}

\index{help}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )help}
\item{\tt )help} {\it commandName}
\end{list}

\par\noindent{\bf Command Description:}

This command displays help information about system commands.
If you issue
\begin{verbatim}
)help
\end{verbatim}
then this very text will be shown.
You can also give the name or abbreviation of a system command
to display information about it.
For example,
\begin{verbatim}
)help clear
\end{verbatim}
will display the description of the {\tt )clear} system command.

All this material is available in the Axiom User Guide
and in HyperDoc.
In HyperDoc, choose the {\bf Commands} item from the
{\bf Reference} menu.

%Original Page 581

\section{)history}
\index{ugSysCmdhistory}
\index{history}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )history )on}
\item{\tt )history )off}
\item{\tt )history )write} {\it historyInputFileName}
\item{\tt )history )show \lanb{}{\it n}\ranb{} \lanb{}both\ranb{}}
\item{\tt )history )save} {\it savedHistoryName}
\item{\tt )history )restore} \lanb{}{\it savedHistoryName}\ranb{}
\item{\tt )history )reset}
\item{\tt )history )change} {\it n}
\item{\tt )history )memory}
\item{\tt )history )file}
\item{\tt \%}
\item{\tt \%\%({\it n})}
\item{\tt )set history on \vertline{} off}
\end{list}

\par\noindent{\bf Command Description:}

The {\it history} facility within Axiom allows you to restore your
environment to that of another session and recall previous
computational results.
Additional commands allow you to review previous
input lines and to create an {\bf .input} file of the lines typed to
\index{file!input}
Axiom.

Axiom saves your input and output if the history facility is
turned on (which is the default).
This information is saved if either of
\begin{verbatim}
)set history on
)history )on
\end{verbatim}
has been issued.
Issuing either
\begin{verbatim}
)set history off
)history )off
\end{verbatim}
will discontinue the recording of information.
\index{history )on}
\index{set history on}
\index{set history off}
\index{history )off}

Whether the facility is disabled or not,
the value of {\tt \%} in Axiom always
refers to the result of the last computation.
If you have not yet entered anything,
{\tt \%} evaluates to an object of type
{\tt Variable('\%)}.
The function {\tt \%\%} may be  used to refer
to other previous results if the history facility is enabled.
In that case,
{\tt \%\%(n)} is  the output from step {\tt n} if {\tt n > 0}.
If {\tt n < 0}, the step is computed relative to the current step.
Thus {\tt \%\%(-1)} is also the previous step,
{\tt \%\%(-2)}, is the  step before that, and so on.
If an invalid step number is given, Axiom will signal an error.

The {\it environment} information can either be saved in a file or
entirely in memory (the default).  Each frame
(\sectionref{ugSysCmdframe}) has its own history database.  When it is
kept in a file, some of it may also be kept in memory for efficiency.
When the information is saved in a file, the name of the file is of
the form {\bf FRAME.axh} where ``{\bf FRAME}'' is the name of the
current frame.  The history file is placed in the current working
directory (see \sectionref{ugSysCmdcd}).  Note that these history
database files are not text files (in fact, they are directories
themselves), and so are not in human-readable format.

The options to the {\tt )history} command are as follows:

\begin{description}
\item[{\tt )change} {\it n}]
will set the number of steps that are saved in memory to {\it n}.
This option only has effect when the history data is maintained in a
file.
If you have issued {\tt )history )memory} (or not changed the default)
there is no need to use {\tt )history )change}.
\index{history )change}

\item[{\tt )on}]
will start the recording of information.
If the workspace is not empty, you will be asked to confirm this
request.
If you do so, the workspace will be cleared and history data will begin
being saved.
You can also turn the facility on by issuing {\tt )set history on}.

%Original Page 582

\item[{\tt )off}]
will stop the recording of information.
The {\tt )history )show} command will not work after issuing this
command.
Note that this command may be issued to save time, as there is some
performance penalty paid for saving the environment data.
You can also turn the facility off by issuing {\tt )set history off}.

\item[{\tt )file}]
indicates that history data should be saved in an external file on disk.

\item[{\tt )memory}]
indicates that all history data should be kept in memory rather than
saved in a file.
Note that if you are computing with very large objects it may not be
practical to kept this data in memory.

\item[{\tt )reset}]
will flush the internal list of the most recent workspace calculations
so that the data structures may be garbage collected by the underlying
Common Lisp system.
Like {\tt )history )change}, this option only has real effect when
history data is being saved in a file.

\item[{\tt )restore} \lanb{}{\it savedHistoryName}\ranb{}]
completely clears the environment and restores it to a saved session, if
possible.
The {\tt )save} option below allows you to save a session to a file
with a given name. If you had issued
{\tt )history )save jacobi}
the command
{\tt )history )restore jacobi}
would clear the current workspace and load the contents of the named
saved session. If no saved session name is specified, the system looks
for a file called {\bf last.axh}.

\item[{\tt )save} {\it savedHistoryName}] is used to save a snapshot
of the environment in a file.  This file is placed in the current
working directory (see \sectionref{ugSysCmdcd}).  Use {\tt )history
)restore} to restore the environment to the state preserved in the
file.  This option also creates an input file containing all the lines
of input since you created the workspace frame (for example, by
starting your Axiom session) or last did a {\tt )clear all} or {\tt
)clear completely}.

\item[{\tt )show} \lanb{}{\it n}\ranb{} \lanb{}{\tt both}\ranb{}]
can show previous input lines and output results.
{\tt )show} will display up to twenty of the last input lines
(fewer if you haven't typed in twenty lines).
{\tt )show} {\it n} will display up to {\it n} of the last input lines.
{\tt )show both} will display up to five of the last input lines and
output results.
{\tt )show} {\it n} {\tt both} will display up to {\it n} of the last
input lines and output results.

\item[{\tt )write} {\it historyInputFile}]
creates an {\bf .input} file with the input lines typed since the start
of the session/frame or the last {\tt )clear all} or {\tt )clear
completely}.
If {\it historyInputFileName} does not contain a 
period (``.'') in the filename,
{\bf .input} is appended to it.
For example,
{\tt )history )write chaos}
and
{\tt )history )write chaos.input}
both write the input lines to a file called {\bf chaos.input} in your
current working directory.
If you issued one or more {\tt )undo} commands,
{\tt )history )write}
eliminates all
input lines backtracked over as a result of {\tt )undo}.
You can edit this file and then use {\tt )read} to have Axiom process
the contents.
\end{description}

\par\noindent{\bf Also See:}
{\tt )frame} \index{ugSysCmdframe},
{\tt )read} \index{ugSysCmdread},
{\tt )set} \index{ugSysCmdset}, and
{\tt )undo} \index{ugSysCmdundo}.


\section{)include}
\index{ugSysCmdinclude}
\index{include}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )include {\it filename}}
\end{list}

\par\noindent{\bf Command Description:}

The \verb|)include| command can be used in \verb|.input| files
to place the contents of another file inline with the current file.
The path can be an absolute or relative pathname.


\section{)library}
\index{ugSysCmdlibrary}
\index{library}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )library {\it libName1  \lanb{}libName2 ...\ranb{}}}
\item{\tt )library )dir {\it dirName}}
\item{\tt )library )only {\it objName1  \lanb{}objlib2 ...\ranb{}}}
\item{\tt )library )noexpose}
\end{list}

\par\noindent{\bf Command Description:}

This command replaces the {\tt )load} system command that
was available in Axiom releases before version 2.0.
The {\tt )library} command makes available to Axiom the compiled
objects in the libraries listed.

For example, if you {\tt )compile dopler.spad} in your home
directory, issue {\tt )library dopler} to have Axiom look
at the library, determine the category and domain constructors present,
update the internal database with various properties of the
constructors, and arrange for the constructors to be
automatically loaded when needed.
If the {\tt )noexpose} option has not been given, the
constructors will be exposed (that is, available) in the current
frame.

If you compiled a file with the old system compiler, you will
have an {\it nrlib} present, for example, {\it DOPLER.nrlib,}
where {\tt DOPLER} is a constructor abbreviation.
The command {\tt )library DOPLER} will then do the analysis and
database updates as above.

To tell the system about all libraries in a directory, use
{\tt )library )dir dirName} where {\tt dirName} is an explicit
directory.
You may specify ``.'' as the directory, which means the current
directory from which you started the system or the one you set
via the {\tt )cd} command. The directory name is required.

You may only want to tell the system about particular
constructors within a library. In this case, use the {\tt )only}
option. The command {\tt )library dopler )only Test1} will only
cause the {\sf Test1} constructor to be analyzed, autoloaded,
etc..

Finally, each constructor in a library  are usually automatically 
exposed when the
{\tt )library} command is used. Use the {\tt )noexpose}
option if you not want them exposed. At a later time you can use
{\tt )set expose add constructor} to expose any hidden
constructors.

{\bf Note for Axiom beta testers:} At various times this
command was called {\tt )local} and {\tt )with} before the name
{\tt )library} became the official name.

\par\noindent{\bf Also See:}
{\tt )cd} \index{ugSysCmdcd},
{\tt )compile} \index{ugSysCmdcompile},
{\tt )frame} \index{ugSysCmdframe}, and
{\tt )set} \index{ugSysCmdset}.

\section{)lisp}
\index{ugSysCmdlisp}

\index{lisp}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )lisp} {\it\lanb{}lispExpression\ranb{}}
\end{list}

\par\noindent{\bf Command Description:}

This command is used by Axiom system developers to have single
expressions evaluated by the Common Lisp system on which
Axiom is built.
The {\it lispExpression} is read by the Common Lisp reader and
evaluated.
If this expression is not complete (unbalanced parentheses, say), the reader
will wait until a complete expression is entered.

%Original Page 583

Since this command is only useful  for evaluating single expressions, the
{\tt )fin}
command may be used to  drop out  of Axiom  into Common Lisp.

\par\noindent{\bf Also See:}
{\tt )system} \index{ugSysCmdsystem},
{\tt )boot} \index{ugSysCmdboot}, and
{\tt )fin} \index{ugSysCmdfin}.

\section{)ltrace}
\label{ugSysCmdtrace}
\label{ugSysCmdltrace}
\index{ugSysCmdltrace}

\index{ltrace}

\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}

This command has the same arguments as options as the
{\tt )trace} command.

\par\noindent{\bf Command Description:}

This command is used by Axiom system developers to trace
Common Lisp functions. It is not supported for general use.

\par\noindent{\bf Also See:}
{\tt )boot} \index{ugSysCmdboot},
{\tt )lisp} \index{ugSysCmdlisp}, and
{\tt )trace} \index{ugSysCmdtrace}.

\section{)pquit}
\index{ugSysCmdpquit}

\index{pquit}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )pquit}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to terminate Axiom  and return to the
operating system.
Other than by redoing all your computations or by
using the {\tt )history )restore}
command to try to restore your working environment,
you cannot return to Axiom in the same state.

{\tt )pquit} differs from the {\tt )quit} in that it always asks for
confirmation that you want to terminate Axiom (the ``p'' is for
``protected'').
\index{quit}
When you enter the {\tt )pquit} command, Axiom responds
%
\begin{center}
Please enter {\bf y} or {\bf yes} if you really want to 
leave the interactive \\
environment and return to the operating system:
\end{center}
%
If you respond with {\tt y} or {\tt yes}, you will see the message
%
\begin{center}
You are now leaving the Axiom interactive environment. \\
Issue the command {\bf axiom} to the operating system to start a new session.
\end{center}
%
and Axiom will terminate and return you to the operating
system (or the environment from which you invoked the system).
If you responded with something other than {\tt y} or {\tt yes}, then
the message
%
\begin{center}
You have chosen to remain in the Axiom interactive environment.
\end{center}
%
will be displayed and, indeed, Axiom would still be running.

\par\noindent{\bf Also See:}
{\tt )fin} \index{ugSysCmdfin},
{\tt )history} \index{ugSysCmdhistory},
{\tt )close} \index{ugSysCmdclose},
{\tt )quit} \index{ugSysCmdquit}, and
{\tt )system} \index{ugSysCmdsystem}.


%Original Page 585

\section{)quit}
\index{ugSysCmdquit}

\index{quit}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )quit}
\item{\tt )set quit protected \vertline{} unprotected}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to terminate Axiom  and return to the
operating system.
Other than by redoing all your computations or by
using the {\tt )history )restore}
command to try to restore your working environment,
you cannot return to Axiom in the same state.

{\tt )quit} differs from the {\tt )pquit} in that it asks for
\index{pquit}
confirmation only if the command
\begin{verbatim}
)set quit protected
\end{verbatim}
has been issued.
\index{set quit protected}
Otherwise, {\tt )quit} will make Axiom terminate and return you
to the operating system (or the environment from which you invoked the
system).

The default setting is {\tt )set quit protected} so that {\tt )quit}
and {\tt )pquit} behave in the same way.
If you do issue
\begin{verbatim}
)set quit unprotected
\end{verbatim}
we
\index{set quit unprotected}
suggest that you do not (somehow) assign {\tt )quit} to be
executed when you press, say, a function key.

\par\noindent{\bf Also See:}
{\tt )fin} \index{ugSysCmdfin},
{\tt )history} \index{ugSysCmdhistory},
{\tt )close} \index{ugSysCmdclose},
{\tt )pquit} \index{ugSysCmdpquit}, and
{\tt )system} \index{ugSysCmdsystem}.


\section{)read}
\index{ugSysCmdread}

\index{read}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )read} {\it \lanb{}fileName\ranb{}}
\item {\tt )read} {\it \lanb{}fileName\ranb{}} \lanb{}
{\tt )quiet}\ranb{} \lanb{}{\tt )ifthere}\ranb{}
\end{list}
\par\noindent{\bf Command Description:}

This command is used to read {\bf .input} files into Axiom.
\index{file!input}
The command
\begin{verbatim}
)read matrix.input
\end{verbatim}
will read the contents of the file {\bf matrix.input} into
Axiom.
The ``.input'' file extension is optional.
See \sectionref{ugInOutIn} for more information about {\bf .input} files.

This command remembers the previous file you edited, read or compiled.
If you do not specify a file name, the previous file will be read.

The {\tt )ifthere} option checks to see whether the {\bf .input} file
exists.
If it does not, the  {\tt )read} command does nothing.
If you do not use this option and the file does not exist,
you are asked to give the name of an existing {\bf .input} file.

The {\tt )quiet} option suppresses output while the file is being read.

\par\noindent{\bf Also See:}
{\tt )compile} \index{ugSysCmdcompile},
{\tt )edit} \index{ugSysCmdedit}, and
{\tt )history} \index{ugSysCmdhistory}.


%Original Page 586

\section{)regress}
\index{regress}
\par\noindent{\bf User Level Required:} development
\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )regress} {\it filename}
\item {\tt )regress} {\it filename.output}
\item {\tt )regress} {\it /path/filename}
\item {\tt )regress} {\it /pathfilename.output}
\end{list}

\par\noindent{\bf Command Description:}

\begin{verbatim}
The regress command will run the regress function that was compiled
as part of the lisp image build process. This function expects an
input filename, possibly containing a path prefix. 

If the filename contains a period then we consider it a fully formed
filename, otherwise we append ``.output'', which is the default file
extension.

  )regress matrix
  )regress matrix.output
  )regress /path/to/file/matrix
  )regress /path/to/file/matrix.output
 
will test the contents of the file matrix.output.

The idea behind regression testing is to check that the results
we currently get match the results we used to get. In order to
do that we create input files with a special comment format that
contains the prior results. These are easy to create as all you
need to do is run the Axiom function, capture the results, and
turn them input specially formed comments using the -- comment.

A regression file caches the result of an Axiom function so we
can automate the testing process. It is a file of many tests,
each with their own output.

The regression file format uses the Axiom -- comment syntax to keep
a copy of the expected output from an Axiom command. This expected
output is compared character by character against the actual output.

The regression file is broken into numbered blocks, delimited by
a --S for the beginning and a --E for the end. The total number of
blocks is also given so missing or failed tests also raise an error.

There are 4 special kinds of -- comments in regression files:

  --S n of M        this is test n of M tests in this file
  --E n             this marks the end of test n
  --R any output    this marks the actual expected output line
  --I any output    this line is compared but ignored

A regression test file looks like:

  )set break resume
  )spool foo.output
  )set message type off
  )clear all

  --S 1 of 3
  2+3
  --R                     this is the exact Axiom output
  --R   (1)  5
  --E 1

  --S 2 of 3
  2+3
  --R                     this should fail to match
  --R   (2)  7
  --E 2

  --S 3 of 3
  2+3
  --R                     this fails to match but we
  --I   (3)  7            use --I to ignore this line
  --E 3

We can now run this file with

  )read foo.input

Note that when this file is run it will create a spool file called
"foo.output" because of the lines:
  
  )spool foo.output
  )spool

The "foo.output" file contains the console image of the result. 
It will look like:

  Starts dribbling to foo.output (2012/2/28, 12:25:7).
  )set message type off
  )clear all

  --S 1 of 3
  2+3
  
     (1)  5
  --R
  --R   (1)  5
  --E 1
  
  --S 2 of 3
  2+3
  
     (2)  5
  --R
  --R   (2)  7
  --E 2

  --S 3 of 3
  2+3
  
     (3)  5
  --R
  --I   (3)  7
  --E 3

  )spool

This "foo.output" file can now be checked using the )regress command.
 
When we run the )regress foo.output we see;

  testing foo
  passed foo  1 of 3
  MISMATCH
  expected:"   (2)  7"
       got:"   (2)  5"
  FAILED foo  2 of 2
  passed foo  3 of 3
  regression result FAILED 1 of 3 stanzas file foo

Tests either pass or fail. A passing test generates the message:

    passed foo  1 of 3

A failing test will give a reversed printout of the expected vs
actual output as well as a FAILED message, as in:

  MISMATCH
  expected:"   (2)  7"
       got:"   (2)  5"
  FAILED foo  2 of 3

The last line of output is a summary:

  regression result FAILED 1 of 3 stanzas file foo

\end{verbatim}

\par\noindent{\bf Also See:}
{\tt )tangle} 

\section{)savesystem}
\index{savesystem}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )savesystem {\sl filename}}
\end{list}
\par\noindent{\bf Command Description:}

This command will save the current Axiom session including
currently set variables into an executable file under the given
filename. For instance,

\begin{verbatim}
   axiom
   (1) -> t1:=4
   (1) -> )savesystem foo
\end{verbatim}
and Axiom exits. Then do
\begin{verbatim}
   ./foo
   (1) -> t1
   4
\end{verbatim}

\section{)set}
\label{ugSysCmdset}
\index{ugSysCmdset}

\index{set}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )set}
\item {\tt )set} {\it label1 \lanb{}... labelN\ranb{}}
\item {\tt )set} {\it label1 \lanb{}... labelN\ranb{} newValue}
\end{list}
\par\noindent{\bf Command Description:}

The {\tt )set} command is used to view or set system variables that
control what messages are displayed, the type of output desired, the
status of the history facility, the way Axiom user functions are
cached, and so on.
Since this collection is very large, we will not discuss them here.
Rather, we will show how the facility is used.
We urge you to explore the {\tt )set} options to familiarize yourself
with how you can modify your Axiom working environment.
There is a HyperDoc version of this same facility available from the
main HyperDoc menu.


The {\tt )set} command is command-driven with a menu display.
It is tree-structured.
To see all top-level nodes, issue {\tt )set} by itself.
\begin{verbatim}
)set
\end{verbatim}
Variables with values have them displayed near the right margin.
Subtrees of selections have ``{\tt ...}''
displayed in the value field.
For example, there are many kinds of messages, so issue
{\tt )set message} to see the choices.
\begin{verbatim}
)set message
\end{verbatim}
The current setting  for the variable that displays
\index{computation timings!displaying}
whether computation times
\index{timings!displaying}
are displayed is visible in the menu displayed by the last command.
To see more information, issue
\begin{verbatim}
)set message time
\end{verbatim}
This shows that time printing is on now.
To turn it off, issue
\begin{verbatim}
)set message time off
\end{verbatim}
\index{set message time}

As noted above, not all settings have so many qualifiers.
For example, to change the {\tt )quit} command to being unprotected
(that is, you will not be prompted for verification), you need only issue
\begin{verbatim}
)set quit unprotected
\end{verbatim}
\index{set quit unprotected}

\par\noindent{\bf Also See:}
{\tt )quit} \index{ugSysCmdquit}.


\section{)show}
\index{ugSysCmdshow}

\index{show}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )show {\it nameOrAbbrev}}
\item {\tt )show {\it nameOrAbbrev} )operations}
\item {\tt )show {\it nameOrAbbrev} )attributes}
\end{list}

\par\noindent{\bf Command Description:}
This command displays information about Axiom
domain, package and category {\it constructors}.
If no options are given, the {\tt )operations} option is assumed.

%Original Page 587

For example,
\begin{verbatim}
)show POLY
)show POLY )operations
)show Polynomial
)show Polynomial )operations
\end{verbatim}
each display basic information about the
{\tt Polynomial} domain constructor and then provide a
listing of operations.
Since {\tt Polynomial} requires a {\tt Ring} (for example,
{\tt Integer}) as argument, the above commands all refer
to a unspecified ring {\tt R}.
In the list of operations, {\tt \$} means
{\tt Polynomial(R)}.

The basic information displayed includes the {\it signature}
of the constructor (the name and arguments), the constructor
{\it abbreviation}, the {\it exposure status} of the constructor, and the
name of the {\it library source file} for the constructor.

If operation information about a specific domain is wanted,
the full or abbreviated domain name may be used.
For example,
\begin{verbatim}
)show POLY INT
)show POLY INT )operations
)show Polynomial Integer
)show Polynomial Integer )operations
\end{verbatim}
are among  the combinations that will display the operations\\ 
exported  by the domain {\tt Polynomial(Integer)} (as opposed\\ 
to the general {\it domain constructor} {\tt Polynomial}).\\
Attributes may be listed by using the {\tt )attributes} option.

\par\noindent{\bf Also See:}
{\tt )display} \index{ugSysCmddisplay},
{\tt )set} \index{ugSysCmdset}, and
{\tt )what} \index{ugSysCmdwhat}.


\section{)spool}
\index{ugSysCmdspool}

\index{spool}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )spool} \lanb{}{\it fileName}\ranb{}
\item{\tt )spool}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to save {\it (spool)} all Axiom input and output
\index{file!spool}
into a file, called a {\it spool file.}
You can only have one spool file active at a time.
To start spool, issue this command with a filename. For example,
\begin{verbatim}
)spool integrate.out
\end{verbatim}
To stop spooling, issue {\tt )spool} with no filename.

If the filename is qualified with a directory, then the output will
be placed in that directory.
If no directory information is given, the spool file will be placed in the
\index{directory!for spool files}
{\it current directory.}
The current directory is the directory from which you started
Axiom or is the directory you specified using the
{\tt )cd} command.
\index{cd}

\par\noindent{\bf Also See:}
{\tt )cd} \index{ugSysCmdcd}.


\section{)summary}
\index{summary}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )summary}
\end{list}
\par\noindent{\bf Command Description:}

\begin{verbatim}
 )credits      : list the people who have contributed to Axiom

 )help <command> gives more information
 )quit         : exit AXIOM 

 )abbreviation : query, set and remove abbreviations for constructors
 )browse       : start an Axiom http server on 127.0.0.1 port 8085
 )cd           : set working directory
 )clear        : remove declarations, definitions or values
 )close        : throw away an interpreter client and workspace
 )compile      : invoke constructor compiler
 )copyright    : show copyright and trademark information
 )describe     : show database information for a category, domain, or package 
 )display      : display Library operations and objects in your workspace
 )edit         : edit a file
 )fin          : drop into lisp, use (restart) to return to the session
 )frame        : manage interpreter workspaces
 )history      : manage aspects of interactive session
 )include      : insert a file into a .input file
 )library      : introduce new constructors 
 )lisp         : evaluate a LISP expression
 )ltrace       : trace functions
 )pquit        : ask if you really want to exit Axiom
 )quit         : exit Axiom
 )read         : execute AXIOM commands from a file
 )regress      : regression test an output spool file
 )savesystem   : save LISP image to a file
 )set          : view and set system variables
 )show         : show constructor information
 )spool        : log input and output to a file
 )synonym      : define an abbreviation for system commands
 )system       : issue shell commands
 )tangle       : extract chunks from a literate program to an input file
 )trace        : trace execution of functions
 )undo         : restore workspace to earlier state
 )what         : search for various things by name
\end{verbatim}

\section{)synonym}
\index{ugSysCmdsynonym}

\index{synonym}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )synonym}
\item{\tt )synonym} {\it synonym fullCommand}
\item{\tt )what synonyms}
\end{list}

%Original Page 588

\par\noindent{\bf Command Description:}

This command is used to create short synonyms for system command expressions.
For example, the following synonyms  might simplify commands you often
use.
\begin{verbatim}
)synonym save         history )save
)synonym restore      history )restore
)synonym mail         system mail
)synonym ls           system ls
)synonym fortran      set output fortran
\end{verbatim}
Once defined, synonyms can be
used in place of the longer  command expressions.
Thus
\begin{verbatim}
)fortran on
\end{verbatim}
is the same as the longer
\begin{verbatim}
)set fortran output on
\end{verbatim}
To list all defined synonyms, issue either of
\begin{verbatim}
)synonyms
)what synonyms
\end{verbatim}
To list, say, all synonyms that contain the substring
``{\tt ap}'', issue
\begin{verbatim}
)what synonyms ap
\end{verbatim}

\par\noindent{\bf Also See:}
{\tt )set} \index{ugSysCmdset} and
{\tt )what} \index{ugSysCmdwhat}.


\section{)system}
\index{ugSysCmdsystem}

\index{system}

\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )system} {\it cmdExpression}
\end{list}

\par\noindent{\bf Command Description:}

This command may be used to issue commands to the operating system while
remaining in Axiom.
The {\it cmdExpression} is passed to the operating system for
execution.

To get an operating system shell, issue, for example,
{\tt )system sh}.
When you enter the key combination,
\fbox{\bf Ctrl}--\fbox{\bf D}
(pressing and holding the
\fbox{\bf Ctrl} key and then pressing the
\fbox{\bf D} key)
the shell will terminate and you will return to Axiom.
We do not recommend this way of creating a shell because
Common Lisp may field some interrupts instead of the shell.
If possible, use a shell running in another window.

If you execute programs that misbehave you may not be able to return to
Axiom.
If this happens, you may have no other choice than to restart
Axiom and restore the environment via {\tt )history )restore}, if
possible.

\par\noindent{\bf Also See:}
{\tt )boot} \index{ugSysCmdboot},
{\tt )fin} \index{ugSysCmdfin},
{\tt )lisp} \index{ugSysCmdlisp},
{\tt )pquit} \index{ugSysCmdpquit}, and
{\tt )quit} \index{ugSysCmdquit}.


%Original Page 590

\section{)tangle}
\index{ugSysCmdboot}
\index{tangle}
\par\noindent{\bf User Level Required:} development
\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )tangle} {\it filename}
\item {\tt )tangle} {\it filename.output}
\item {\tt )tangle} {\it /path/filename}
\item {\tt )tangle} {\it /pathfilename.output}
\end{list}

\par\noindent{\bf Command Description:}

\begin{verbatim}
This command is used to tangle pamphlet files.
 
)tangle matrix.input.pamphlet
 
will tangle the contents of the file matrix.input.pamphlet into 
matrix.input. The ``.input.pamphlet'' is optional.
 
\end{verbatim}

\par\noindent{\bf Also See:}
{\tt )regress} 

%Original Page 584

\section{)trace}
\label{ugSysCmdtrace}
\label{ugSysCmdltrace}
\index{ugSysCmdltrace}

\index{ltrace}


\par\noindent{\bf User Level Required:} development

\par\noindent{\bf Command Syntax:}

This command has the same arguments as options as the
{\tt )trace} command.

\par\noindent{\bf Command Description:}

This command is used by Axiom system developers to trace
Common Lisp or
BOOT functions.
It is not supported for general use.

\par\noindent{\bf Also See:}
{\tt )boot} \index{ugSysCmdboot},
{\tt )lisp} \index{ugSysCmdlisp}, and
{\tt )trace} \index{ugSysCmdtrace}.


\section{)trace}
\index{ugSysCmdtrace}

\index{trace}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )trace}
\item{\tt )trace )off}

\item{\tt )trace} {\it function \lanb{}options\ranb{}}
\item{\tt )trace} {\it constructor \lanb{}options\ranb{}}
\item{\tt )trace} {\it domainOrPackage \lanb{}options\ranb{}}
\end{list}
%
where options can be one or more of
%
\begin{list}{}
\item{\tt )after} {\it S-expression}
\item{\tt )before} {\it S-expression}
\item{\tt )break after}
\item{\tt )break before}
\item{\tt )cond} {\it S-expression}
\item{\tt )count}
\item{\tt )count} {\it n}
\item{\tt )depth} {\it n}
\item{\tt )local} {\it op1 \lanb{}... opN\ranb{}}
\item{\tt )nonquietly}
\item{\tt )nt}
\item{\tt )off}
\item{\tt )only} {\it listOfDataToDisplay}
\item{\tt )ops}
\item{\tt )ops} {\it op1 \lanb{}... opN \ranb{}}
\item{\tt )restore}
\item{\tt )stats}
\item{\tt )stats reset}
\item{\tt )timer}
\item{\tt )varbreak}
\item{\tt )varbreak} {\it var1 \lanb{}... varN \ranb{}}
\item{\tt )vars}
\item{\tt )vars} {\it var1 \lanb{}... varN \ranb{}}
\item{\tt )within} {\it executingFunction}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to trace the execution of functions that make
up the Axiom system, functions defined by users,
and functions from the system library.
Almost all options are available for each type of function but
exceptions will be noted below.

To list all functions, constructors, domains and packages that are
traced, simply issue
\begin{verbatim}
)trace
\end{verbatim}
To untrace everything that is traced, issue
\begin{verbatim}
)trace )off
\end{verbatim}
When a function is traced, the default system action is to display
the arguments to the function and the return value when the
function is exited.
Note that if a function is left via an action such as a {\tt THROW}, no
return value will be displayed.
Also, optimization of tail recursion may decrease the number of
times a function is actually invoked and so may cause less trace
information to be displayed.

%Original Page 590

Other information can be displayed or collected when a function is
traced and this is controlled by the various options.
Most options will be of interest only to Axiom system
developers.
If a domain or package is traced, the default action is to trace
all functions exported.

Individual interpreter, lisp or boot
functions can be traced by listing their names after
{\tt )trace}.
Any options that are present must follow the functions to be
traced.
\begin{verbatim}
)trace f
\end{verbatim}
traces the function {\tt f}.
To untrace {\tt f}, issue
\begin{verbatim}
)trace f )off
\end{verbatim}
Note that if a function name contains a special character, it will
be necessary to escape the character with an underscore
%
\begin{verbatim}
)trace _/D_,1
\end{verbatim}
%
To trace all domains or packages that are or will be created from a particular
constructor, give the constructor name or abbreviation after
{\tt )trace}.
%
\begin{verbatim}
)trace MATRIX
)trace List Integer
\end{verbatim}
%
The first command traces all domains currently instantiated with
{\tt Matrix}.
If additional domains are instantiated with this constructor
(for example, if you have used {\tt Matrix(Integer)} and
{\tt Matrix(Float)}), they will be automatically traced.
The second command traces {\tt List(Integer)}.
It is possible to trace individual functions in a domain or
package.
See the {\tt )ops} option below.

The following are the general options for the {\tt )trace}
command.

%!! system command parser doesn't treat general s-expressions correctly,
%!! I recommand not documenting )after )before and )cond
\begin{description}
%\item[{\tt )after} {\it S-expression}]
%causes the given Common Lisp {\it S-expression} to be
%executed after exiting the traced function.

%\item[{\tt )before} {\it S-expression}]
%causes the given Common Lisp {\it S-expression} to be
%executed before entering the traced function.

\item[{\tt )break after}]
causes a Common Lisp break loop to be entered after
exiting the traced function.

\item[{\tt )break before}]
causes a Common Lisp break loop to be entered before
entering the traced function.

\item[{\tt )break}]
is the same as {\tt )break before}.

%\item[{\tt )cond} {\it S-expression}]
%causes trace information to be shown only if the given
%Common Lisp {\it S-expression} evaluates to non-NIL.  For
%example, the following command causes the system function
%{\tt resolveTT} to be traced but to have the information
%displayed only if the value of the variable
%{\tt \$reportBottomUpFlag} is non-NIL.
%\begin{verbatim}
%)trace resolveTT )cond \_\$reportBottomUpFlag}
%\end{verbatim}

\item[{\tt )count}]
causes the system to keep a count of the number of times the
traced function is entered.  The total can be displayed with
{\tt )trace )stats} and cleared with {\tt )trace )stats reset}.

\item[{\tt )count} {\it n}]
causes information about the traced function to be displayed for
the first {\it n} executions.  After the {\it n-th} execution, the
function is untraced.

\item[{\tt )depth} {\it n}]
causes trace information to be shown for only {\it n} levels of
recursion of the traced function.  The command
\begin{verbatim}
)trace fib )depth 10
\end{verbatim}
will cause the display of only 10 levels of trace information for
the recursive execution of a user function {\bf fib}.

\item[{\tt )math}]
causes the function arguments and return value to be displayed\\ 
in the Axiom monospace two-dimensional math format.

\item[{\tt )nonquietly}]
causes the display of additional messages when a function is
traced.

\item[{\tt )nt}]
This suppresses all normal trace information.  This option is
useful if the {\tt )count} or {\tt )timer} options are used and
you are interested in the statistics but not the function calling
information.

%Original Page 591

\item[{\tt )off}]
causes untracing of all or specific functions.  Without an
argument, all functions, constructors, domains and packages are
untraced.  Otherwise, the given functions and other objects
are untraced.  To
immediately retrace the untraced functions, issue {\tt )trace
)restore}.

\item[{\tt )only} {\it listOfDataToDisplay}]
causes only specific trace information to be shown.  The items are
listed by using the following abbreviations:
\begin{description}
\item[a]        display all arguments
\item[v]        display return value
\item[1]        display first argument
\item[2]        display second argument
\item[15]       display the 15th argument, and so on
\end{description}
\end{description}
\begin{description}

\item[{\tt )restore}]
causes the last untraced functions to be retraced.  If additional
options are present, they are added to those previously in effect.

\item[{\tt )stats}]
causes the display of statistics collected by the use of the
{\tt )count} and {\tt )timer} options.

\item[{\tt )stats reset}]
resets to 0 the statistics collected by the use of the
{\tt )count} and {\tt )timer} options.

\item[{\tt )timer}]
causes the system to keep a count of execution times for the
traced function.  The total can be displayed with {\tt )trace
)stats} and cleared with {\tt )trace )stats reset}.

%!! only for lisp, boot, may not work in any case, recommend removing
%\item[{\tt )varbreak}]
%causes a Common Lisp break loop to be entered after
%the assignment to any variable in the traced function.

\item[{\tt )varbreak} {\it var1 \lanb{}... varN\ranb{}}]
causes a Common Lisp break loop to be entered after
the assignment to any of the listed variables in the traced
function.

\item[{\tt )vars}] causes the display of the value of any variable
after it is assigned in the traced function.  Note that library code
must have been compiled (see \sectionref{ugSysCmdcompile} using the
{\tt )vartrace} option in order to support this option.

\item[{\tt )vars} {\it var1 \lanb{}... varN\ranb{}}] causes the
display of the value of any of the specified variables after they are
assigned in the traced function.  Note that library code must have
been compiled (see \sectionref{ugSysCmdcompile} using the {\tt
)vartrace} option in order to support this option.

\item[{\tt )within} {\it executingFunction}]
causes the display of trace information only if the traced
function is called when the given {\it executingFunction} is running.
\end{description}

The following are the options for tracing constructors, domains
and packages.

\begin{description}
\item[{\tt )local} {\it \lanb{}op1 \lanb{}... opN\ranb{}\ranb{}}]
causes local functions of the constructor to be traced.  Note that
to untrace an individual local function, you must use the fully
qualified internal name, using the escape character
{\tt \_} before the semicolon.
\begin{verbatim}
)trace FRAC )local
)trace FRAC_;cancelGcd )off
\end{verbatim}

\item[{\tt )ops} {\it op1 \lanb{}... opN\ranb{}}]
By default, all operations from a domain or package are traced
when the domain or package is traced.  This option allows you to
specify that only particular operations should be traced.  The
command
%
\begin{verbatim}
)trace Integer )ops min max _+ _-
\end{verbatim}
%
traces four operations from the domain {\tt Integer}.  Since
{\tt +} and {\tt -} are special
characters, it is necessary
to escape them with an underscore.
\end{description}

\par\noindent{\bf Also See:}
{\tt )boot} \index{ugSysCmdboot},
{\tt )lisp} \index{ugSysCmdlisp}, and
{\tt )ltrace} \index{ugSysCmdltrace}.

%Original Page 592

\section{)undo}
\index{ugSysCmdundo}

\index{undo}


\par\noindent{\bf User Level Required:} interpreter

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )undo}
\item{\tt )undo} {\it integer}
\item{\tt )undo} {\it integer \lanb{}option\ranb{}}
\item{\tt )undo} {\tt )redo}
\end{list}
%
where {\it option} is one of
%
\begin{list}{}
\item{\tt )after}
\item{\tt )before}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to
restore the state of the user environment to an earlier
point in the interactive session.
The argument of an {\tt )undo} is an integer which must designate some
step number in the interactive session.

\begin{verbatim}
)undo n
)undo n )after
\end{verbatim}
These commands return the state of the interactive
environment to that immediately after step {\tt n}.
If {\tt n} is a positive number, then {\tt n} refers to step nummber
{\tt n}. If {\tt n} is a negative number, it refers to the {\tt n}-th
previous command (that is, undoes the effects of the last $-n$
commands).

A {\tt )clear all} resets the {\tt )undo} facility.
Otherwise, an {\tt )undo} undoes the effect of {\tt )clear} with
options {\tt properties}, {\tt value}, and {\tt mode}, and
that of a previous {\tt undo}.
If any such system commands are given between steps $n$ and
$n + 1$ ($n > 0$), their effect is undone
for {\tt )undo m} for any $0 < m \leq n$..

The command {\tt )undo} is equivalent to {\tt )undo -1} (it undoes
the effect of the previous user expression).
The command {\tt )undo 0} undoes any of the above system commands
issued since the last user expression.

\begin{verbatim}
)undo n )before
\end{verbatim}
This command returns the state of the interactive
environment to that immediately before step {\tt n}.
Any {\tt )undo} or {\tt )clear} system commands
given before step {\tt n} will not be undone.

\begin{verbatim}
)undo )redo
\end{verbatim}
This command reads the file {\tt redo.input}.
created by the last {\tt )undo} command.
This file consists of all user input lines, excluding those
backtracked over due to a previous {\tt )undo}.

\par\noindent{\bf Also See:}
{\tt )history} \index{ugSysCmdhistory}.
The command {\tt )history )write} will eliminate the ``undone'' command
lines of your program.

\section{)what}
\index{ugSysCmdwhat}
\label{ugSysCmdwhat}

\index{what}


\par\noindent{\bf User Level Required:} interpreter

%Original Page 593

\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item{\tt )what categories} {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what commands  } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what domains   } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what operations} {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what packages  } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what synonym   } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )what things    } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\item{\tt )apropos        } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}}
\end{list}

\par\noindent{\bf Command Description:}

This command is used to display lists of things in the system.  The
patterns are all strings and, if present, restrict the contents of the
lists.  Only those items that contain one or more of the strings as
substrings are displayed.  For example,
\begin{verbatim}
)what synonym
\end{verbatim}
displays all command synonyms,
\begin{verbatim}
)what synonym ver
\end{verbatim}
displays all command synonyms containing the substring ``{\tt ver}'',
\begin{verbatim}
)what synonym ver pr
\end{verbatim}
displays all command synonyms
containing the substring  ``{\tt ver}'' or  the substring
``{\tt pr}''.
Output similar to the following will be displayed
\begin{verbatim}
---------------- System Command Synonyms -----------------

user-defined synonyms satisfying patterns:
      ver pr

  )apr ........................... )what things
  )apropos ....................... )what things
  )prompt ........................ )set message prompt
  )version ....................... )lisp *yearweek*
\end{verbatim}

Several other things can be listed with the {\tt )what} command:

\begin{description}
\item[{\tt categories}] displays a list of category constructors.
\index{what categories}
\item[{\tt commands}]  displays a list of  system commands available  at your
user-level.
\index{what commands}
Your user-level
\index{user-level}
is set via the  {\tt )set userlevel} command.
\index{set userlevel}
To get a description of a particular command, such as ``{\tt )what}'', issue
{\tt )help what}.
\item[{\tt domains}]   displays a list of domain constructors.
\index{what domains}
\item[{\tt operations}] displays a list of operations in  the system library.
\index{what operations}
It  is recommended that you  qualify this command with one or
more patterns, as there are thousands of operations available.  For
example, say you are looking for functions that involve computation of
eigenvalues.  To find their names, try {\tt )what operations eig}.
A rather large list of operations  is loaded into the workspace when
this command  is first issued.  This  list will be deleted  when you
clear the workspace  via {\tt )clear all} or {\tt )clear completely}.
It will be re-created if it is needed again.
\item[{\tt packages}]  displays a list of package constructors.
\index{what packages}
\item[{\tt synonym}]  lists system command synonyms.
\index{what synonym}
\item[{\tt things}]    displays all  of the  above types for  items containing
\index{what things}
the pattern strings as  substrings.
The command synonym  {\tt )apropos} is equivalent to
\index{apropos}
{\tt )what things}.
\end{description}

\par\noindent{\bf Also See:}
{\tt )display} \index{ugSysCmddisplay},
{\tt )set} \index{ugSysCmdset}, and
{\tt )show} \index{ugSysCmdshow}.

%\setcounter{chapter}{1} % Appendix B

%Original Page 595

%\twocolumn[%
\chapter{Categories}
\label{ugAppCategories}

This is a listing of all categories in the Axiom library at the
time this book was produced.
Use the Browse facility (described in \sectionref{ugBrowse})
to get more information about these constructors.

\boxer{4.6in}{
This sample entry will help you read the following table:

CategoryName{CategoryAbbreviation}:{$\hbox{{\sf Category}}_{1}$%
\ldots$\hbox{{\sf Category}}_{N}$}{\sl with }%
{$\hbox{{\rm op}}_{1}$\ldots$\hbox{{\rm op}}_{M}$}

where

\begin{tabular}{ll}
CategoryName & is the full category name, e.g., {\sf Integer}. \\
CategoryAbbreviation & is the category abbreviation, e.g., {\sf INT}. \\
$\hbox{{\sf Category}}_{i}$ & is a category to which the category belongs. \\
$\hbox{{\rm op}}_{j}$ & is an operation exported by the category.
\end{tabular}
}

\def\condata#1#2#3#4{{%
   \par\vskip 1pt%
   {\bf #2}\allowbreak\{{\tt #1}\}: {\sl #3} {\tt with }%
   {\rm #4}\par}}

\condata{ABELGRP}{AbelianGroup}{CancellationAbelianMonoid}{{\tt *} {\tt -}}
%
\condata{AMR}{AbelianMonoidRing}
{Algebra BiModule CharacteristicNonZero CharacteristicZero CommutativeRing
IntegralDomain Ring}
{{\tt /} coefficient degree leadingCoefficient leadingMonomial map 
monomial monomial? reductum}
%
\condata{ABELMON}{AbelianMonoid}{AbelianSemiGroup}{{\tt *} Zero zero?}
%
\condata{ABELSG}{AbelianSemiGroup}{SetCategory}{{\tt *} {\tt +}}
%
\condata{AGG}{Aggregate}{Object}
{{\tt \#} copy empty empty? eq? less? more? size?}
%
\condata{ACF}{AlgebraicallyClosedField}{Field RadicalCategory}
{rootOf rootsOf zeroOf zerosOf}
%
\condata{ACFS}{AlgebraicallyClosedFunctionSpace\\}
{AlgebraicallyClosedField FunctionSpace}
{rootOf rootsOf zeroOf zerosOf}
%
\condata{ALGEBRA}{Algebra}{Module Ring}{coerce}
%
\condata{AHYP}{ArcHyperbolicFunctionCategory}{}
{acosh acoth acsch asech asinh atanh}
%
\condata{ATRIG}{ArcTrigonometricFunctionCategory}{}
{acos acot acsc asec asin atan}
%
\condata{ALAGG}{AssociationListAggregate}{ListAggregate TableAggregate}{assoc}
%
\condata{ATTREG}{AttributeRegistry}{}{}
%
\condata{BGAGG}{BagAggregate}{HomogeneousAggregate}
{bag extract! insert! inspect}
%
\condata{BMODULE}{BiModule}{LeftModule RightModule}{}
%
\condata{BRAGG}{BinaryRecursiveAggregate}{RecursiveAggregate}
{elt left right setelt setleft! setright!}
%
\condata{BTCAT}{BinaryTreeCategory}{BinaryRecursiveAggregate}{node}
%
\condata{BTAGG}{BitAggregate}{OneDimensionalArrayAggregate OrderedSet}
{{\tt \^{}} and nand nor not or xor}
%
\condata{CACHSET}{CachableSet}{OrderedSet}{position setPosition}
%
\condata{CABMON}{CancellationAbelianMonoid}{AbelianMonoid}{{\tt -}}
%
\condata{CHARNZ}{CharacteristicNonZero}{Ring}{charthRoot}
%
\condata{CHARZ}{CharacteristicZero}{Ring}{}
%
\condata{KOERCE}{CoercibleTo}{}{coerce}
%
\condata{CLAGG}{Collection}{ConvertibleTo HomogeneousAggregate}
{construct find reduce remove removeDuplicates select}
%
\condata{CFCAT}{CombinatorialFunctionCategory}{}
{binomial factorial permutation}
%
\condata{COMBOPC}{CombinatorialOpsCategory}{CombinatorialFunctionCategory}
{factorials product summation}
%
\condata{COMRING}{CommutativeRing}{BiModule Ring}{}
%
\condata{COMPCAT}{ComplexCategory\\}
{CharacteristicNonZero CharacteristicZero CommutativeRing\\ 
ConvertibleTo DifferentialExtension EuclideanDomain Field\\ 
FullyEvalableOver FullyLinearlyExplicitRingOver FullyRetractableTo\\
IntegralDomain MonogenicAlgebra OrderedSet\\ 
PolynomialFactorizationExplicit RadicalCategory\\
TranscendentalFunctionCategory\\}
{abs argument complex conjugate exquo imag imaginary norm 
polarCoordinates rational rational? rationalIfCan real}
%
\condata{KONVERT}{ConvertibleTo}{}{convert}
%
\condata{DQAGG}{DequeueAggregate}
{QueueAggregate StackAggregate}
{bottom! dequeue extractBottom! extractTop! height
insertBottom! insertTop! reverse! top!}
%
\condata{DIOPS}{DictionaryOperations}{BagAggregate Collection}
{dictionary remove! select!}
%
\condata{DIAGG}{Dictionary}{DictionaryOperations}{}
%
\condata{DIFEXT}{DifferentialExtension\\}
{DifferentialRing PartialDifferentialRing Ring}
{D differentiate}
%
\condata{DPOLCAT}{DifferentialPolynomialCategory\\}
{DifferentialExtension Evalable InnerEvalable PolynomialCategory\\
RetractableTo}
{degree differentialVariables initial isobaric? leader makeVariable 
order separant weight weights}
%
\condata{DIFRING}{DifferentialRing}{Ring}{D differentiate}
%
\condata{DVARCAT}{DifferentialVariableCategory}{OrderedSet RetractableTo}
{D coerce differentiate makeVariable order variable weight}
%
\condata{DIRPCAT}{DirectProductCategory\\}
{AbelianSemiGroup Algebra BiModule CancellationAbelianMonoid\\ 
CoercibleTo CommutativeRing DifferentialExtension Finite\\ 
FullyLinearlyExplicitRingOver FullyRetractableTo IndexedAggregate\\ 
OrderedAbelianMonoidSup OrderedRing VectorSpace}
{{\tt *} directProduct dot unitVector}
%
\condata{DIVRING}{DivisionRing}{Algebra EntireRing}{{\tt **} inv}
%
\condata{DLAGG}{DoublyLinkedAggregate}{RecursiveAggregate}
{concat! head last next previous setnext! setprevious! tail}
%
\condata{ELEMFUN}{ElementaryFunctionCategory}{}{{\tt **} exp log}
%
\condata{ELTAGG}{EltableAggregate}{Eltable}{elt qelt qsetelt! setelt}
%
\condata{ELTAB}{Eltable}{}{elt}
%
\condata{ENTIRER}{EntireRing}{BiModule Ring}{}
%
\condata{EUCDOM}{EuclideanDomain}{PrincipalIdealDomain\\}
{divide euclideanSize extendedEuclidean multiEuclidean quo rem sizeLess?}
%
\condata{EVALAB}{Evalable}{}{eval}
%
\condata{ES}{ExpressionSpace}
{Evalable InnerEvalable OrderedSet RetractableTo}
{belong? box definingPolynomial distribute elt eval freeOf? height is? 
kernel kernels mainKernel map minPoly operator operators paren subst tower}
%
\condata{ELAGG}{ExtensibleLinearAggregate}{LinearAggregate\\}
{concat! delete! insert! merge! remove! removeDuplicates! select!}
%
\condata{XF}{ExtensionField}
{CharacteristicZero Field FieldOfPrimeCharacteristic RetractableTo 
VectorSpace}
{Frobenius algebraic? degree extensionDegree inGroundField? 
transcendenceDegree transcendent?}
%
\condata{FPC}{FieldOfPrimeCharacteristic}
{CharacteristicNonZero Field}{discreteLog order primeFrobenius}
%
\condata{FIELD}{Field}
{DivisionRing EuclideanDomain UniqueFactorizationDomain}{{\tt /}}
%
\condata{FILECAT}{FileCategory}{SetCategory}
{close! iomode name open read! reopen! write!}
%
\condata{FNCAT}{FileNameCategory}{SetCategory}
{coerce directory exists? extension filename name new readable? writable?}
%
\condata{FAMR}{FiniteAbelianMonoidRing}
{AbelianMonoidRing FullyRetractableTo}
{coefficients content exquo ground ground? mapExponents minimumDegree 
numberOfMonomials primitivePart}
%
\condata{FAXF}{FiniteAlgebraicExtensionField\\}
{ExtensionField FiniteFieldCategory RetractableTo\\}
{basis coordinates createNormalElement definingPolynomial degree 
extensionDegree generator minimalPolynomial norm normal? normalElement
represents trace}
%
\condata{FFIELDC}{FiniteFieldCategory}
{FieldOfPrimeCharacteristic Finite StepThrough}
{charthRoot conditionP createPrimitiveElement discreteLog 
factorsOfCyclicGroupSize order primitive? primitiveElement 
representationType tableForDiscreteLogarithm}
%
\condata{FLAGG}{FiniteLinearAggregate}{LinearAggregate OrderedSet}
{copyInto! merge position reverse reverse! sort sort!
   sorted?}
%
\condata{FINRALG}{FiniteRankAlgebra}
{Algebra CharacteristicNonZero CharacteristicZero}
{characteristicPolynomial coordinates discriminant minimalPolynomial 
norm rank regularRepresentation represents trace traceMatrix}
%
\condata{FINAALG}{FiniteRankNonAssociativeAlgebra\\}{NonAssociativeAlgebra\\}
{JacobiIdentity? JordanAlgebra? alternative? antiAssociative?\\ 
antiCommutative? associative? associatorDependence commutative?\\ 
conditionsForIdempotents coordinates flexible? jordanAdmissible?\\ 
leftAlternative? leftCharacteristicPolynomial leftDiscriminant\\ 
leftMinimalPolynomial leftNorm leftRecip leftRegularRepresentation\\ 
leftTrace leftTraceMatrix leftUnit leftUnits lieAdmissible? lieAlgebra?\\
noncommutativeJordanAlgebra? powerAssociative? rank recip represents\\ 
rightAlternative? rightCharacteristicPolynomial rightDiscriminant\\ 
rightMinimalPolynomial rightNorm rightRecip rightRegularRepresentation\\ 
rightTrace rightTraceMatrix rightUnit rightUnits someBasis\\ 
structuralConstants unit}
%
\condata{FSAGG}{FiniteSetAggregate}{Dictionary Finite SetAggregate}
{cardinality complement max min universe}
%
\condata{FINITE}{Finite}{SetCategory}{index lookup random size}
%
\condata{FPS}{FloatingPointSystem}{RealNumberSystem}
{base bits decreasePrecision digits exponent float
increasePrecision mantissa max order precision}
%
\condata{FRAMALG}{FramedAlgebra}{FiniteRankAlgebra}
{basis convert coordinates discriminant regularRepresentation
represents traceMatrix}
%
\condata{FRNAALG}{FramedNonAssociativeAlgebra\\}
{FiniteRankNonAssociativeAlgebra}
{apply basis conditionsForIdempotents convert coordinates elt 
leftDiscriminant leftRankPolynomial leftRegularRepresentation 
leftTraceMatrix represents rightDiscriminant rightRankPolynomial 
rightRegularRepresentation rightTraceMatrix structuralConstants}
%
\condata{FAMONC}{FreeAbelianMonoidCategory\\}
{CancellationAbelianMonoid RetractableTo}
{{\tt *} {\tt +} coefficient highCommonTerms mapCoef mapGen nthCoef 
nthFactor size terms}
%
\condata{FEVALAB}{FullyEvalableOver}{Eltable Evalable InnerEvalable}{map}
%
\condata{FLINEXP}{FullyLinearlyExplicitRingOver}{LinearlyExplicitRingOver}{}
%
\condata{FPATMAB}{FullyPatternMatchable}{Object PatternMatchable}{}
%
\condata{FRETRCT}{FullyRetractableTo}{RetractableTo}{}
%
\condata{FFCAT}{FunctionFieldCategory}{MonogenicAlgebra\\}
{D absolutelyIrreducible? branchPoint? branchPointAtInfinity?\\
complementaryBasis differentiate elt genus integral?\\ 
integralAtInfinity? integralBasis integralBasisAtInfinity\\
integralCoordinates integralDerivationMatrix integralMatrix\\ 
integralMatrixAtInfinity integralRepresents inverseIntegralMatrix\\ 
inverseIntegralMatrixAtInfinity nonSingularModel\\ 
normalizeAtInfinity numberOfComponents primitivePart ramified?\\ 
ramifiedAtInfinity? rationalPoint? rationalPoints\\ 
reduceBasisAtInfinity represents singular? singularAtInfinity?\\ 
yCoordinates}
%
\condata{FS}{FunctionSpace}
{AbelianGroup AbelianMonoid Algebra CharacteristicNonZero 
CharacteristicZero ConvertibleTo ExpressionSpace Field 
FullyLinearlyExplicitRingOver FullyPatternMatchable FullyRetractableTo 
Group Monoid PartialDifferentialRing Patternable RetractableTo Ring}
{{\tt **} {\tt /} applyQuote coerce convert denom denominator eval 
ground ground? isExpt isMult isPlus isPower isTimes numer numerator 
univariate variables}
%
\condata{GCDDOM}{GcdDomain}{IntegralDomain}{gcd lcm}
%
\condata{GRALG}{GradedAlgebra}{GradedModule}{One product}
%
\condata{GRMOD}{GradedModule}{RetractableTo SetCategory}
{{\tt *} {\tt +} {\tt -} Zero degree}
%
\condata{GROUP}{Group}{Monoid}{{\tt **} {\tt /} commutator conjugate inv}
%
\condata{HOAGG}{HomogeneousAggregate}{Aggregate SetCategory}
{any? count every? map map! member? members parts}
%
\condata{HYPCAT}{HyperbolicFunctionCategory}{}{cosh coth csch sech sinh tanh}
%
\condata{IXAGG}{IndexedAggregate}{EltableAggregate HomogeneousAggregate}
{entries entry? fill! first index? indices maxIndex minIndex swap!}
%
\condata{IDPC}{IndexedDirectProductCategory}{SetCategory}
{leadingCoefficient leadingSupport map monomial reductum}
%
\condata{IEVALAB}{InnerEvalable}{}{eval}
%
\condata{INS}{IntegerNumberSystem}
{CharacteristicZero CombinatorialFunctionCategory ConvertibleTo 
DifferentialRing EuclideanDomain LinearlyExplicitRingOver OrderedRing 
PatternMatchable RealConstant RetractableTo StepThrough 
UniqueFactorizationDomain}
{addmod base bit? copy dec even? hash inc invmod length mask mulmod odd? 
positiveRemainder powmod random rational rational? rationalIfCan shift 
submod symmetricRemainder}
%
\condata{INTDOM}{IntegralDomain}
{Algebra CommutativeRing EntireRing}
{associates? exquo unit? unitCanonical unitNormal}
%
\condata{KDAGG}{KeyedDictionary}{Dictionary}{key? keys remove! search}
%
\condata{LZSTAGG}{LazyStreamAggregate}{StreamAggregate}
{complete explicitEntries? explicitlyEmpty? extend frst lazy?
lazyEvaluate numberOfComputedEntries remove rst select}
%
\condata{LALG}{LeftAlgebra}{LeftModule Ring}{coerce}
%
\condata{LMODULE}{LeftModule}{AbelianGroup}{{\tt *}}
%
\condata{LNAGG}{LinearAggregate}
{Collection IndexedAggregate}
{concat delete elt insert map new setelt}
%
\condata{LINEXP}{LinearlyExplicitRingOver}{Ring}{reducedSystem}
%
\condata{LFCAT}{LiouvillianFunctionCategory}
{PrimitiveFunctionCategory TranscendentalFunctionCategory}
{Ci Ei Si dilog erf li}
%
\condata{LSAGG}{ListAggregate}
{ExtensibleLinearAggregate FiniteLinearAggregate StreamAggregate}{list}
%
\condata{MAGCDOC}{ModularAlgebraicGcdOperations}{}
{canonicalIfCan degree MPtoMPT packExps packModulus pseudoRem repack1 zero?}

\condata{MATCAT}{MatrixCategory}{TwoDimensionalArrayCategory\\}
{{\tt *} {\tt **} {\tt +} {\tt -} {\tt /} antisymmetric? coerce 
determinant diagonal? diagonalMatrix elt exquo horizConcat inverse 
listOfLists matrix minordet nullSpace nullity rank rowEchelon 
scalarMatrix setelt setsubMatrix! square? squareTop subMatrix 
swapColumns! swapRows! symmetric? transpose vertConcat zero}
%
\condata{MODULE}{Module}{BiModule}{}
%
\condata{MONADWU}{MonadWithUnit}{Monad}
{{\tt **} One leftPower leftRecip one? recip rightPower rightRecip}
%
\condata{MONAD}{Monad}{SetCategory}
{{\tt *} {\tt **} leftPower rightPower}
%
\condata{MONOGEN}{MonogenicAlgebra}
{CommutativeRing ConvertibleTo\\ 
DifferentialExtension Field Finite\\
FiniteFieldCategory FramedAlgebra\\ 
FullyLinearlyExplicitRingOver FullyRetractableTo\\}
{convert definingPolynomial derivationCoordinates generator lift reduce}
%
\condata{MLO}{MonogenicLinearOperator}{Algebra BiModule Ring}
{coefficient degree leadingCoefficient minimumDegree monomial reductum}
%
\condata{MONOID}{Monoid}{SemiGroup}{{\tt **} One one? recip}
%
\condata{MDAGG}{MultiDictionary}{DictionaryOperations}
{duplicates insert! removeDuplicates!}
%
\condata{MSAGG}{MultisetAggregate}{MultiDictionary SetAggregate}{}
%
\condata{MTSCAT}{MultivariateTaylorSeriesCategory\\}
{Evalable InnerEvalable PartialDifferentialRing\\ 
PowerSeriesCategory RadicalCategory\\ 
TranscendentalFunctionCategory\\}
{coefficient extend integrate monomial order polynomial}
%
\condata{NAALG}{NonAssociativeAlgebra}{Module NonAssociativeRng}{plenaryPower}
%
\condata{NASRING}{NonAssociativeRing}{MonadWithUnit NonAssociativeRng}
{characteristic coerce}
%
\condata{NARNG}{NonAssociativeRng}{AbelianGroup Monad\\}
{antiCommutator associator commutator}
%
\condata{OBJECT}{Object}{}{}
%
\condata{OC}{OctonionCategory}{Algebra CharacteristicNonZero\\ 
CharacteristicZero ConvertibleTo Finite FullyEvalableOver\\
FullyRetractableTo OrderedSet\\}
{abs conjugate imagE imagI imagJ imagK imagi imagj imagk inv norm 
octon rational rational? rationalIfCan real}
%
\condata{A1AGG}{OneDimensionalArrayAggregate}{FiniteLinearAggregate}{}
%
\condata{OAGROUP}{OrderedAbelianGroup\\}
{AbelianGroup OrderedCancellationAbelianMonoid}{}
%
\condata{OAMONS}{OrderedAbelianMonoidSup}
{OrderedCancellationAbelianMonoid}{sup}
%
\condata{OAMON}{OrderedAbelianMonoid}{AbelianMonoid OrderedAbelianSemiGroup}{}
%
\condata{OASGP}{OrderedAbelianSemiGroup}{AbelianMonoid OrderedSet}{}
%
\condata{OCAMON}{OrderedCancellationAbelianMonoid}
{CancellationAbelianMonoid OrderedAbelianMonoid}{}
%
\condata{ORDFIN}{OrderedFinite}{Finite OrderedSet}{}
%
\condata{ORDMON}{OrderedMonoid}{Monoid OrderedSet}{}
%
\condata{OMAGG}{OrderedMultisetAggregate}
{MultisetAggregate PriorityQueueAggregate}{min}
%
\condata{ORDRING}{OrderedRing}{OrderedAbelianGroup OrderedMonoid Ring}
{abs negative? positive? sign}
%
\condata{ORDSET}{OrderedSet}{SetCategory}{{\tt <} max min}
%
\condata{PADICCT}{PAdicIntegerCategory}{CharacteristicZero EuclideanDomain}
{approximate complete digits extend moduloP modulus order quotientByP sqrt}
%
\condata{PDRING}{PartialDifferentialRing}{Ring}{D differentiate}
%
\condata{PTRANFN}{PartialTranscendentalFunctions\\}{}
{acosIfCan acoshIfCan acotIfCan acothIfCan acscIfCan\\ 
acschIfCan asecIfCan asechIfCan asinIfCan asinhIfCan\\ 
atanIfCan atanhIfCan cosIfCan coshIfCan cotIfCan cothIfCan\\ 
cscIfCan cschIfCan expIfCan logIfCan nthRootIfCan secIfCan\\ 
sechIfCan sinIfCan sinhIfCan tanIfCan tanhIfCan}
%
\condata{PATAB}{Patternable}{ConvertibleTo Object}{}
%
\condata{PATMAB}{PatternMatchable}{SetCategory}{patternMatch}
%
\condata{PERMCAT}{PermutationCategory}{Group OrderedSet\\}
{{\tt <} cycle cycles elt eval orbit}
%
\condata{PPCURVE}{PlottablePlaneCurveCategory}{CoercibleTo\\}
{listBranches xRange yRange}
%
\condata{PSCURVE}{PlottableSpaceCurveCategory}{CoercibleTo\\}
{listBranches xRange yRange zRange}
%
\condata{PTCAT}{PointCategory}{VectorCategory}
{convert cross dimension extend length point}
%
\condata{POLYCAT}{PolynomialCategory}
{ConvertibleTo Evalable FiniteAbelianMonoidRing FullyLinearlyExplicitRingOver
GcdDomain InnerEvalable OrderedSet PartialDifferentialRing PatternMatchable 
PolynomialFactorizationExplicit RetractableTo}
{coefficient content degree discriminant isExpt isPlus isTimes 
mainVariable minimumDegree monicDivide monomial monomials multivariate 
primitiveMonomials primitivePart resultant squareFree squareFreePart 
totalDegree univariate variables}
%
\condata{PFECAT}{PolynomialFactorizationExplicit\\}{UniqueFactorizationDomain}
{charthRoot conditionP factorPolynomial factorSquareFreePolynomial\\ 
gcdPolynomial solveLinearPolynomialEquation squareFreePolynomial}
%
\condata{PSCAT}{PowerSeriesCategory}{AbelianMonoidRing}
{complete monomial pole? variables}
%
\condata{PRIMCAT}{PrimitiveFunctionCategory}{}{integral}
%
\condata{PID}{PrincipalIdealDomain}{GcdDomain}
{expressIdealMember principalIdeal}
%
\condata{PRQAGG}{PriorityQueueAggregate}{BagAggregate}{max merge merge!}
%
\condata{QUATCAT}{QuaternionCategory}
{Algebra CharacteristicNonZero CharacteristicZero ConvertibleTo
DifferentialExtension DivisionRing EntireRing FullyEvalableOver 
FullyLinearlyExplicitRingOver FullyRetractableTo OrderedSet}
{abs conjugate imagI imagJ imagK norm quatern rational rational? 
rationalIfCan real}
%
\condata{QUAGG}{QueueAggregate}{BagAggregate}
{back dequeue! enqueue! front length rotate!}
%
\condata{QFCAT}{QuotientFieldCategory\\}
{Algebra CharacteristicNonZero CharacteristicZero\\ 
ConvertibleTo DifferentialExtension Field FullyEvalableOver\\ 
FullyLinearlyExplicitRingOver FullyPatternMatchable OrderedRing\\ 
OrderedSet Patternable PolynomialFactorizationExplicit\\ 
RealConstant RetractableTo StepThrough\\}
{{\tt /} ceiling denom denominator floor fractionPart numer numerator 
random wholePart}
%
\condata{RADCAT}{RadicalCategory}{}{{\tt **} nthRoot sqrt}
%
\condata{REAL}{RealConstant}{ConvertibleTo}{}
%
\condata{RNS}{RealNumberSystem}
{CharacteristicZero ConvertibleTo Field OrderedRing PatternMatchable 
RadicalCategory RealConstant RetractableTo}
{abs ceiling floor fractionPart norm round truncate wholePart}
%
\condata{RMATCAT}{RectangularMatrixCategory\\}
{BiModule HomogeneousAggregate Module}
{{\tt /} antisymmetric? column diagonal? elt exquo listOfLists map matrix 
maxColIndex maxRowIndex minColIndex minRowIndex ncols nrows nullSpace
nullity qelt rank row rowEchelon square? symmetric?}
%
\condata{RCAGG}{RecursiveAggregate}{HomogeneousAggregate}
{children cyclic? elt leaf? leaves node? nodes setchildren! setelt 
setvalue! value}
%
\condata{RETRACT}{RetractableTo}{}{coerce retract retractIfCan}
%
\condata{RMODULE}{RightModule}{AbelianGroup}{{\tt *}}
%
\condata{RING}{Ring}{LeftModule Monoid Rng}{characteristic coerce}
%
\condata{RNG}{Rng}{AbelianGroup SemiGroup}{}
%
\condata{SEGCAT}{SegmentCategory}{SetCategory}
{BY SEGMENT convert hi high incr lo low segment}
%
\condata{SEGXCAT}{SegmentExpansionCategory}{SegmentCategory}{expand map}
%
\condata{SGROUP}{SemiGroup}{SetCategory}{{\tt *} {\tt **}}
%
\condata{SETAGG}{SetAggregate}{Collection SetCategory}
{{\tt <} brace difference intersect subset? symmetricDifference union}
%
\condata{SETCAT}{SetCategory}{CoercibleTo Object}{{\tt =}}
%
\condata{SEXCAT}{SExpressionCategory}{SetCategory}
{{\tt \#} atom? car cdr convert destruct elt eq expr float float?
integer integer? list? null? pair? string string? symbol symbol? uequal}
%
\condata{SPFCAT}{SpecialFunctionCategory}{}
{Beta Gamma abs airyAi airyBi besselI besselJ besselK besselY digamma
polygamma}
%
\condata{SMATCAT}{SquareMatrixCategory}
{Algebra BiModule DifferentialExtension FullyLinearlyExplicitRingOver
FullyRetractableTo Module RectangularMatrixCategory}
{{\tt *} {\tt **} determinant diagonal diagonalMatrix diagonalProduct 
inverse minordet scalarMatrix trace}
%
\condata{SKAGG}{StackAggregate}{BagAggregate}{depth pop! push! top}
%
\condata{STEP}{StepThrough}{SetCategory}{init nextItem}
%
\condata{STAGG}{StreamAggregate}{LinearAggregate UnaryRecursiveAggregate}
{explicitlyFinite? possiblyInfinite?}
%
\condata{SRAGG}{StringAggregate}{OneDimensionalArrayAggregate}
{coerce elt leftTrim lowerCase lowerCase! match match? position prefix? 
replace rightTrim split substring? suffix? trim upperCase upperCase!}
%
\condata{STRICAT}{StringCategory}{StringAggregate}{string}
%
\condata{TBAGG}{TableAggregate}{IndexedAggregate KeyedDictionary}
{map setelt table}
%
\condata{SPACEC}{ThreeSpaceCategory}{SetCategory}
{check closedCurve closedCurve? coerce components composite composites
copy create3Space curve curve? enterPointData lllip lllp llprop lp lprop 
merge mesh mesh? modifyPointData numberOfComponents numberOfComposites 
objects point point? polygon polygon? subspace}
%
\condata{TRANFUN}{TranscendentalFunctionCategory\\}
{ArcHyperbolicFunctionCategory ArcTrigonometricFunctionCategory\\
ElementaryFunctionCategory HyperbolicFunctionCategory\\
TrigonometricFunctionCategory}{pi}
%
\condata{TRIGCAT}{TrigonometricFunctionCategory}{}{cos cot csc sec sin tan}
%
\condata{ARR2CAT}{TwoDimensionalArrayCategory}{HomogeneousAggregate}
{column elt fill! map map! maxColIndex maxRowIndex minColIndex minRowIndex 
ncols new nrows parts qelt qsetelt! row setColumn! setRow! setelt}
%
\condata{URAGG}{UnaryRecursiveAggregate}{RecursiveAggregate}
{concat concat! cycleEntry cycleLength cycleSplit! cycleTail elt first 
last rest second setelt setfirst! setlast! setrest! split! tail third}
%
\condata{UFD}{UniqueFactorizationDomain}{GcdDomain}
{factor prime? squareFree squareFreePart}
%
\condata{ULSCAT}{UnivariateLaurentSeriesCategory\\}
{Field RadicalCategory TranscendentalFunctionCategory 
UnivariatePowerSeriesCategory}
{integrate multiplyCoefficients rationalFunction}
%
\condata{ULSCCAT}{UnivariateLaurentSeriesConstructorCategory\\}
{QuotientFieldCategory RetractableTo UnivariateLaurentSeriesCategory}
{coerce degree laurent removeZeroes taylor taylorIfCan taylorRep}
%
\condata{UPOLYC}{UnivariatePolynomialCategory\\}
{DifferentialExtension DifferentialRing Eltable EuclideanDomain
PolynomialCategory StepThrough}
{D composite differentiate discriminant divideExponents elt integrate makeSUP
monicDivide multiplyExponents order pseudoDivide pseudoQuotient 
pseudoRemainder resultant separate subResultantGcd unmakeSUP vectorise}
%
\condata{UPSCAT}{UnivariatePowerSeriesCategory\\}
{DifferentialRing Eltable PowerSeriesCategory}
{approximate center elt eval extend multiplyExponents order series 
terms truncate variable}
%
\condata{UPXSCAT}{UnivariatePuiseuxSeriesCategory\\}
{Field RadicalCategory TranscendentalFunctionCategory\\
UnivariatePowerSeriesCategory}
{integrate multiplyExponents}
%
\condata{UPXSCCA}{UnivariatePuiseuxSeriesConstructorCategory\\}{RetractableTo UnivariatePuiseuxSeriesCategory\\}
{coerce degree laurent laurentIfCan laurentRep puiseux rationalPower}
%
\condata{UTSCAT}{UnivariateTaylorSeriesCategory\\}
{RadicalCategory TranscendentalFunctionCategory\\
UnivariatePowerSeriesCategory\\}
{{\tt **} coefficients integrate multiplyCoefficients 
polynomial quoByVar series}
%
\condata{VECTCAT}{VectorCategory}{OneDimensionalArrayAggregate}
{{\tt *} {\tt +} {\tt -} dot zero}
%
\condata{VSPACE}{VectorSpace}{Module}{{\tt /} dimension}
%
%
% ----------------------------------------------------------------------



%\setcounter{chapter}{2} % Appendix C

%\twocolumn[%

%Original Page 601

\chapter{Domains}
\label{ugAppDomains}

This is a listing of all domains in the Axiom library at the
time this book was produced.
Use the Browse facility (described in \sectionref{ugBrowse})
to get more information about these constructors.

\boxer{4.6in}{
This sample entry will help you read the following table:

DomainName{DomainAbbreviation}:{$\hbox{{\sf Category}}_{1}$%
\ldots$\hbox{{\sf Category}}_{N}$}{\sl with }%
{$\hbox{{\rm op}}_{1}$\ldots$\hbox{{\rm op}}_{M}$}

where

\begin{tabular}{@{\quad}ll}
DomainName & is the full domain name, e.g., {\sf Integer}. \\
DomainAbbreviation & is the domain abbreviation, e.g., {\sf INT}. \\
$\hbox{{\sf Category}}_{i}$ & is a category to which the domain belongs. \\
$\hbox{{\rm op}}_{j}$ & is an operation exported by the domain.
\end{tabular}
}

% ----------------------------------------------------------------------
%\begin{constructorListing}
% ----------------------------------------------------------------------
\condata{ALGSC}{AlgebraGivenByStructuralConstants\\}
{FramedNonAssociativeAlgebra LeftModule}
{0 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} JacobiIdentity? 
JordanAlgebra? alternative? antiAssociative? antiCommutative? 
antiCommutator apply associative? associator associatorDependence 
basis coerce commutative? commutator conditionsForIdempotents convert
coordinates elt flexible? jordanAdmissible? leftAlternative? 
leftCharacteristicPolynomial leftDiscriminant leftMinimalPolynomial 
leftNorm leftPower leftRankPolynomial leftRecip 
leftRegularRepresentation leftTrace leftTraceMatrix leftUnit 
leftUnits lieAdmissible? lieAlgebra? noncommutativeJordanAlgebra? 
plenaryPower powerAssociative? rank recip represents 
rightAlternative? rightCharacteristicPolynomial rightDiscriminant
rightMinimalPolynomial rightNorm rightPower rightRankPolynomial 
rightRecip rightRegularRepresentation rightTrace rightTraceMatrix 
rightUnit rightUnits someBasis structuralConstants unit zero?}
%
\condata{ALGFF}{AlgebraicFunctionField}{FunctionFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D 
absolutelyIrreducible? associates? basis branchPoint? 
branchPointAtInfinity? characteristic characteristicPolynomial
charthRoot coerce complementaryBasis convert coordinates 
definingPolynomial derivationCoordinates differentiate discriminant 
divide elt euclideanSize expressIdealMember exquo extendedEuclidean 
factor gcd generator genus integral? integralAtInfinity? integralBasis 
integralBasisAtInfinity integralCoordinates integralDerivationMatrix 
integralMatrix integralMatrixAtInfinity integralRepresents inv 
inverseIntegralMatrix inverseIntegralMatrixAtInfinity knownInfBasis lcm
lift minimalPolynomial multiEuclidean nonSingularModel norm 
normalizeAtInfinity numberOfComponents one? prime? primitivePart 
principalIdeal quo ramified? ramifiedAtInfinity? rank rationalPoint? 
rationalPoints recip reduce reduceBasisAtInfinity reducedSystem 
regularRepresentation rem represents retract retractIfCan singular?
singularAtInfinity? sizeLess? squareFree squareFreePart trace 
traceMatrix unit? unitCanonical unitNormal yCoordinates zero?}
%
\condata{AN}{AlgebraicNumber}
{AlgebraicallyClosedField CharacteristicZero ConvertibleTo DifferentialRing
ExpressionSpace LinearlyExplicitRingOver RealConstant RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
associates? belong? box characteristic coerce convert 
definingPolynomial denom differentiate distribute
divide elt euclideanSize eval expressIdealMember exquo 
extendedEuclidean factor freeOf? gcd height inv is? kernel
kernels lcm mainKernel map max min minPoly multiEuclidean 
nthRoot numer one? operator operators paren prime? principalIdeal 
quo recip reduce reducedSystem rem retract retractIfCan rootOf 
rootsOf sizeLess? sqrt squareFree squareFreePart subst tower unit? 
unitCanonical unitNormal zero? zeroOf zerosOf}
%
\condata{ANON}{AnonymousFunction}{SetCategory}{{\tt =} coerce}
%
\condata{ANTISYM}{AntiSymm}{LeftAlgebra RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} characteristic
coefficient coerce degree exp generator homogeneous? 
leadingBasisTerm leadingCoefficient map one? recip reductum
retract retractIfCan retractable? zero?}
%
\condata{ANY}{Any}{SetCategory}
{{\tt =} any coerce domain domainOf obj objectOf showTypeInOutput}
%
\condata{ASTACK}{ArrayStack}{StackAggregate}
{{\tt \#} {\tt =} any? arrayStack bag coerce copy count depth empty empty?
eq? every? extract! insert! inspect less? map map! member? members more? 
parts pop! push! size? top}
%
\condata{JORDAN}{AssociatedJordanAlgebra}
{CoercibleTo\\ FiniteRankNonAssociativeAlgebra FramedNonAssociativeAlgebra\\
NonAssociativeAlgebra}
{0 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} JacobiIdentity?\\ 
JordanAlgebra? alternative? antiAssociative? antiCommutative?\\ 
antiCommutator apply associative? associator associatorDependence\\ 
basis coerce commutative? commutator conditionsForIdempotents\\ 
convert coordinates elt flexible? jordanAdmissible?\\ 
leftAlternative? leftCharacteristicPolynomial leftDiscriminant\\ 
leftMinimalPolynomial leftNorm leftPower leftRankPolynomial\\ 
leftRecip leftRegularRepresentation leftTrace leftTraceMatrix\\ 
leftUnit leftUnits lieAdmissible? lieAlgebra?\\ 
noncommutativeJordanAlgebra? plenaryPower powerAssociative?\\ 
rank recip represents rightAlternative?\\ 
rightCharacteristicPolynomial rightDiscriminant\\ 
rightMinimalPolynomial rightNorm rightPower rightRankPolynomial\\
rightRecip rightRegularRepresentation rightTrace rightTraceMatrix\\ 
rightUnit rightUnits someBasis structuralConstants unit zero?}
%
\condata{LIE}{AssociatedLieAlgebra}
{CoercibleTo\\ FiniteRankNonAssociativeAlgebra FramedNonAssociativeAlgebra\\
NonAssociativeAlgebra}
{0 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} JacobiIdentity?\\
JordanAlgebra? alternative? antiAssociative? antiCommutative?\\
antiCommutator apply associative? associator associatorDependence\\
basis coerce commutative? commutator conditionsForIdempotents\\
convert coordinates elt flexible? jordanAdmissible?\\
leftAlternative? leftCharacteristicPolynomial leftDiscriminant\\
leftMinimalPolynomial leftNorm leftPower leftRankPolynomial\\
leftRecip leftRegularRepresentation leftTrace leftTraceMatrix\\
leftUnit leftUnits lieAdmissible? lieAlgebra?\\
noncommutativeJordanAlgebra? plenaryPower powerAssociative?\\
rank recip represents rightAlternative?\\
rightCharacteristicPolynomial rightDiscriminant\\
rightMinimalPolynomial rightNorm rightPower rightRankPolynomial\\
rightRecip rightRegularRepresentation rightTrace\\
rightTraceMatrix rightUnit rightUnits someBasis\\
structuralConstants unit zero?}
%
\condata{ALIST}{AssociationList}{AssociationListAggregate}
{{\tt \#} {\tt =} any? assoc bag child? children coerce concat concat! 
construct copy copyInto! count cycleEntry cycleLength cycleSplit! 
cycleTail cyclic? delete delete! dictionary distance elt empty empty? 
entries entry? eq? every? explicitlyFinite? extract! fill! find first index?
indices insert insert! inspect key? keys last leaf? less? list map map! 
maxIndex member? members merge merge! minIndex more? new node? nodes parts 
position possiblyInfinite? qelt qsetelt! reduce remove remove! 
removeDuplicates removeDuplicates! rest reverse reverse! search second 
select select! setchildren! setelt setfirst! setlast! setrest! setvalue! 
size? sort sort! sorted? split! swap! table tail third value}
%
\condata{BBTREE}{BalancedBinaryTree}{BinaryTreeCategory}
{{\tt \#} {\tt =} any? balancedBinaryTree children coerce copy count 
cyclic? elt empty empty? eq? every? leaf? leaves left less? map map! 
mapDown! mapUp! member? members more? node node? nodes parts right 
setchildren! setelt setleaves! setleft! setright! setvalue! size? value}
%
\condata{BPADIC}{BalancedPAdicInteger}{PAdicIntegerCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} approximate associates? 
characteristic coerce complete digits divide euclideanSize 
expressIdealMember exquo extend extendedEuclidean gcd lcm moduloP 
modulus multiEuclidean one? order principalIdeal quo quotientByP recip 
rem sizeLess? sqrt unit? unitCanonical unitNormal zero?}
%
\condata{BPADICRT}{BalancedPAdicRational}{QuotientFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D approximate 
associates? characteristic coerce continuedFraction denom denominator 
differentiate divide euclideanSize expressIdealMember exquo 
extendedEuclidean factor fractionPart gcd inv lcm map multiEuclidean 
numer numerator one? prime? principalIdeal quo recip reducedSystem 
rem removeZeroes retract retractIfCan sizeLess? squareFree squareFreePart
unit? unitCanonical unitNormal wholePart zero?}
%
\condata{BOP}{BasicOperator}{OrderedSet}
{{\tt <} {\tt =} arity assert coerce comparison copy\\ 
deleteProperty! display equality has? input is? max min\\ 
name nary? nullary? operator properties property setProperties\\ 
setProperty unary? weight}
%
\condata{BINARY}{BinaryExpansion}{QuotientFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs 
associates? binary ceiling characteristic coerce convert denom denominator 
differentiate divide euclideanSize expressIdealMember exquo extendedEuclidean
factor floor fractionPart gcd init inv lcm map max min multiEuclidean
negative? nextItem numer numerator one? patternMatch positive? prime? 
principalIdeal quo random recip reducedSystem rem retract retractIfCan 
sign sizeLess? squareFree squareFreePart unit? unitCanonical unitNormal 
wholePart zero?}
%
\condata{BSTREE}{BinarySearchTree}{BinaryTreeCategory}
{{\tt \#} {\tt =} any? binarySearchTree children coerce copy count cyclic? 
elt empty empty? eq? every? insert! insertRoot! leaf? leaves left less? 
map map! member? members more? node node? nodes parts right setchildren! 
setelt setleft! setright! setvalue! size? split value}
%
\condata{BTOURN}{BinaryTournament}{BinaryTreeCategory}
{{\tt \#} {\tt =} any? binaryTournament children coerce copy
count cyclic? elt empty empty? eq? every? insert! leaf? leaves left 
less? map map! member? members more? node node? nodes parts right 
setchildren! setelt setleft! setright! setvalue! size? value}
%
\condata{BTREE}{BinaryTree}{BinaryTreeCategory}
{{\tt \#} {\tt =} any? binaryTree children coerce copy count cyclic? elt
empty empty? eq? every? leaf? leaves left less? map map! member? members 
more? node node? nodes parts right setchildren! setelt setleft! setright! 
setvalue! size? value}
%
\condata{BITS}{Bits}{BitAggregate}
{{\tt \#} {\tt <} {\tt =} {\tt \^{}} and any? bits coerce concat construct 
convert copy copyInto! count delete elt empty empty? entries entry? eq? 
every? fill! find first index? indices insert less? map map! max maxIndex 
member? members merge min minIndex more? nand new nor not or parts 
position qelt qsetelt! reduce remove removeDuplicates reverse reverse! 
select setelt size? sort sort! sorted? swap! xor}
%
\condata{BOOLEAN}{Boolean}{ConvertibleTo Finite OrderedSet}
{{\tt <} {\tt =} {\tt \^{}} and coerce convert false implies index lookup 
max min nand nor not or random size true xor}
%
\condata{CARD}{CardinalNumber}
{CancellationAbelianMonoid Monoid OrderedSet RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt <} {\tt =} Aleph coerce 
countable? finite? generalizedContinuumHypothesisAssumed  
generalizedContinuumHypothesisAssumed? max min one? recip retract 
retractIfCan zero?}
%
\condata{CARTEN}{CartesianTensor}{GradedAlgebra}
{0 1 {\tt *} {\tt +} {\tt -} {\tt =} coerce contract degree elt 
kroneckerDelta leviCivitaSymbol product rank ravel reindex retract 
retractIfCan transpose unravel}
%
\condata{CCLASS}{CharacterClass}
{ConvertibleTo FiniteSetAggregate SetCategory}
{{\tt \#} {\tt <} {\tt =} alphabetic alphanumeric any? bag brace cardinality 
charClass coerce complement construct convert copy count dictionary difference
digit empty empty? eq? every? extract! find hexDigit index insert! 
inspect intersect less? lookup lowerCase map map! max member? members min 
more? parts random reduce remove remove! removeDuplicates select select! 
size size? subset? symmetricDifference union universe upperCase}
%
\condata{CHAR}{Character}{OrderedFinite}
{{\tt <} {\tt =} alphabetic? alphanumeric? char coerce digit? escape hexDigit?
index lookup lowerCase lowerCase? max min ord quote random size space 
upperCase upperCase?}
%
\condata{CLIF}{CliffordAlgebra}{Algebra Ring VectorSpace}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} characteristic 
coefficient coerce dimension e monomial one? recip zero?}
%
\condata{COLOR}{Color}{AbelianSemiGroup}
{{\tt *} {\tt +} {\tt =} blue coerce color green hue numberOfHues red yellow}
%
\condata{COMM}{Commutator}{SetCategory}{{\tt =} coerce mkcomm}
%
\condata{COMPLEX}{Complex}{ComplexCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs acos
acosh acot acoth acsc acsch argument asec asech asin asinh associates? 
atan atanh basis characteristic characteristicPolynomial charthRoot 
coerce complex conditionP conjugate convert coordinates cos cosh cot coth
createPrimitiveElement csc csch definingPolynomial derivationCoordinates 
differentiate discreteLog discriminant divide elt euclideanSize eval exp 
expressIdealMember exquo extendedEuclidean factor factorPolynomial
factorSquareFreePolynomial factorsOfCyclicGroupSize gcd gcdPolynomial 
generator imag imaginary index init inv lcm lift log lookup map max min 
minimalPolynomial multiEuclidean nextItem norm nthRoot one? order pi 
polarCoordinates prime? primeFrobenius primitive? primitiveElement 
principalIdeal quo random rank rational rational? rationalIfCan real 
recip reduce reducedSystem regularRepresentation rem representationType 
represents retract retractIfCan sec sech sin sinh size sizeLess? 
solveLinearPolynomialEquation sqrt squareFree squareFreePart 
squareFreePolynomial tableForDiscreteLogarithm tan tanh trace 
traceMatrix unit? unitCanonical unitNormal zero?}
%
\condata{CONTFRAC}{ContinuedFraction}{Algebra Field}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} approximants\\
associates? characteristic coerce complete continuedFraction\\ 
convergents denominators divide euclideanSize expressIdealMember\\ 
exquo extend extendedEuclidean factor gcd inv lcm multiEuclidean\\ 
numerators one? partialDenominators partialNumerators\\ 
partialQuotients prime? principalIdeal quo recip\\ 
reducedContinuedFraction reducedForm rem sizeLess? squareFree\\ 
squareFreePart unit? unitCanonical unitNormal wholePart zero?}
%
\condata{DBASE}{Database}{SetCategory}
{{\tt +} {\tt -} {\tt =} coerce display elt fullDisplay}
%
\condata{DFLOAT}{DoubleFloat}
{ConvertibleTo DifferentialRing FloatingPointSystem 
TranscendentalFunctionCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs acos 
acosh acot acoth acsc acsch asec asech asin asinh associates? atan atanh 
base bits ceiling characteristic coerce convert cos cosh cot coth csc 
csch decreasePrecision differentiate digits divide euclideanSize exp 
exp1 exponent expressIdealMember exquo extendedEuclidean factor float
floor fractionPart gcd hash increasePrecision inv lcm log log10 log2 
mantissa max min multiEuclidean negative? norm nthRoot one? order 
patternMatch pi positive? precision prime? principalIdeal quo 
rationalApproximation recip rem retract retractIfCan round sec sech 
sign sin sinh sizeLess? sqrt squareFree squareFreePart tan tanh truncate 
unit? unitCanonical unitNormal wholePart zero?}
%
\condata{DLIST}{DataList}{ListAggregate}
{{\tt \#} {\tt <} {\tt =} any? children coerce concat concat! construct 
convert copy copyInto! count cycleEntry cycleLength cycleSplit! cycleTail 
cyclic? datalist delete delete! elt empty empty? entries entry? eq? 
every? explicitlyFinite? fill! find first index? indices insert insert! 
last leaf? leaves less? list map map! max maxIndex member? members merge 
merge! min minIndex more? new node? nodes parts position possiblyInfinite?
qelt qsetelt! reduce remove remove! removeDuplicates removeDuplicates! 
rest reverse reverse! second select select! setchildren! setelt setfirst! 
setlast! setrest! setvalue! size? sort sort! sorted? split! swap! tail 
third value}
%
\condata{DECIMAL}{DecimalExpansion}{QuotientFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs 
associates? ceiling characteristic coerce convert decimal denom 
denominator differentiate divide euclideanSize expressIdealMember 
exquo extendedEuclidean factor floor fractionPart gcd init inv lcm 
map max min multiEuclidean negative? nextItem numer numerator one? 
patternMatch positive? prime? principalIdeal quo random recip 
reducedSystem rem retract retractIfCan sign sizeLess? squareFree 
squareFreePart unit? unitCanonical unitNormal wholePart zero?}
%
\condata{DHMATRIX}{DenavitHartenbergMatrix}{MatrixCategory}
{{\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} antisymmetric? 
any? coerce column copy count determinant diagonal? diagonalMatrix elt 
empty empty? eq? every? exquo fill! horizConcat identity inverse less? 
listOfLists map map! matrix maxColIndex maxRowIndex member? members
minColIndex minRowIndex minordet more? ncols new nrows nullSpace 
nullity parts qelt qsetelt! rank rotatex rotatey rotatez row rowEchelon 
scalarMatrix scale setColumn! setRow! setelt setsubMatrix! size? square? 
squareTop subMatrix swapColumns! swapRows! symmetric? translate 
transpose vertConcat zero}
%
\condata{DEQUEUE}{Dequeue}{DequeueAggregate}
{{\tt \#} {\tt =} any? back bag bottom! coerce copy count depth dequeue
dequeue! empty empty? enqueue! eq? every? extract! extractBottom! 
extractTop! front height insert! insertBottom! insertTop! inspect 
length less? map map! member? members more? parts pop! push! reverse!
rotate! size? top top!}
%
\condata{DERHAM}{DeRhamComplex}{LeftAlgebra RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} characteristic
coefficient coerce degree exteriorDifferential generator 
homogeneous? leadingBasisTerm leadingCoefficient map one?
recip reductum retract retractIfCan retractable? totalDifferential zero?}
%
\condata{DSMP}{DifferentialSparseMultivariatePolynomial\\}
{DifferentialPolynomialCategory RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
associates? characteristic charthRoot coefficient coefficients coerce
conditionP content convert degree differentialVariables differentiate 
discriminant eval exquo factor factorPolynomial factorSquareFreePolynomial 
gcd gcdPolynomial ground ground? initial isExpt isPlus isTimes isobaric? 
lcm leader leadingCoefficient leadingMonomial mainVariable makeVariable 
map mapExponents max min minimumDegree monicDivide monomial monomial? 
monomials multivariate numberOfMonomials one? order patternMatch prime? 
primitiveMonomials primitivePart recip reducedSystem reductum resultant 
retract retractIfCan separant solveLinearPolynomialEquation squareFree 
squareFreePart squareFreePolynomial totalDegree unit? unitCanonical 
unitNormal univariate variables weight weights zero?}
%
\condata{DPMM}{DirectProductMatrixModule}{DirectProductCategory LeftModule}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
abs any? characteristic coerce copy count differentiate dimension 
directProduct dot elt empty empty? entries entry? eq? every? fill! 
first index index? indices less? lookup map map! max maxIndex member?
members min minIndex more? negative? one? parts positive? qelt 
qsetelt! random recip reducedSystem retract retractIfCan setelt sign 
size size? sup swap! unitVector zero?}
%
\condata{DPMO}{DirectProductModule}{DirectProductCategory LeftModule}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
abs any? characteristic coerce copy count differentiate dimension 
directProduct dot elt empty empty? entries entry? eq? every? fill! 
first index index? indices less? lookup map map! max maxIndex member? 
members min minIndex more? negative? one? parts positive? qelt qsetelt! 
random recip reducedSystem retract retractIfCan setelt sign size size? 
sup swap! unitVector zero?}
%
\condata{DIRPROD}{DirectProduct}{DirectProductCategory}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
abs any? characteristic coerce copy count differentiate dimension 
directProduct dot elt empty empty? entries entry? eq? every? fill! 
first index index? indices less? lookup map map! max maxIndex member? 
members min minIndex more? negative? one? parts positive? qelt qsetelt! 
random recip reducedSystem retract retractIfCan setelt sign size
size? sup swap! unitVector zero?}
%
\condata{DMP}{DistributedMultivariatePolynomial}{PolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D\\
associates? characteristic charthRoot coefficient coefficients\\
coerce conditionP const content convert degree differentiate\\
discriminant eval exquo factor factorPolynomial\\
factorSquareFreePolynomial gcd gcdPolynomial ground ground? isExpt\\
isPlus isTimes lcm leadingCoefficient leadingMonomial mainVariable\\
map mapExponents max min minimumDegree monicDivide monomial monomial?\\
monomials multivariate numberOfMonomials one? prime? primitiveMonomials\\
primitivePart recip reducedSystem reductum reorder resultant retract\\
retractIfCan solveLinearPolynomialEquation squareFree squareFreePart\\
squareFreePolynomial totalDegree unit? unitCanonical unitNormal\\
univariate variables zero?}
%
\condata{DROPT}{DrawOption}{SetCategory}{{\tt =} adaptive clip coerce 
colorFunction coordinate coordinates curveColor option option? pointColor 
range ranges space style title toScale tubePoints tubeRadius unit 
var1Steps var2Steps}
%
\condata{EFULS}{ElementaryFunctionsUnivariateLaurentSeries\\}
{PartialTranscendentalFunctions}
{{\tt **} acos acosIfCan acosh acoshIfCan acot acotIfCan acoth acothIfCan 
acsc acscIfCan acsch acschIfCan asec asecIfCan asech asechIfCan asin
asinIfCan asinh asinhIfCan atan atanIfCan atanh atanhIfCan cos cosIfCan 
cosh coshIfCan cot cotIfCan coth cothIfCan csc cscIfCan csch cschIfCan 
exp expIfCan log logIfCan nthRootIfCan sec secIfCan sech sechIfCan sin 
sinIfCan sinh sinhIfCan tan tanIfCan tanh tanhIfCan}
%
\condata{EFUPXS}{ElementaryFunctionsUnivariatePuiseuxSeries}
{PartialTranscendentalFunctions}
{{\tt **} acos acosIfCan acosh acoshIfCan acot acotIfCan acoth acothIfCan 
acsc acscIfCan acsch acschIfCan asec asecIfCan asech asechIfCan asin
asinIfCan asinh asinhIfCan atan atanIfCan atanh atanhIfCan cos cosIfCan 
cosh coshIfCan cot cotIfCan coth cothIfCan csc cscIfCan csch cschIfCan 
exp expIfCan log logIfCan nthRootIfCan sec secIfCan sech sechIfCan sin 
sinIfCan sinh sinhIfCan tan tanIfCan tanh tanhIfCan}
%
\condata{EQTBL}{EqTable}{TableAggregate}
{{\tt \#} {\tt =} any? bag coerce construct copy count dictionary elt empty
empty? entries entry? eq? every? extract! fill! find first index? indices 
insert! inspect key? keys less? map map! maxIndex member? members minIndex 
more? parts qelt qsetelt! reduce remove remove! removeDuplicates search select
select! setelt size? swap! table}
%
\condata{EQ}{Equation}{CoercibleTo InnerEvalable Object SetCategory}
{{\tt *} {\tt **} {\tt +} {\tt -} {\tt =} coerce equation eval lhs map rhs}
%
\condata{EMR}{EuclideanModularRing}{EuclideanDomain}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} associates? characteristic 
coerce divide euclideanSize exQuo expressIdealMember exquo 
extendedEuclidean gcd inv lcm modulus multiEuclidean one? principalIdeal 
quo recip reduce rem sizeLess? unit? unitCanonical unitNormal zero?}
%
\condata{EXIT}{Exit}{SetCategory}{{\tt =} coerce}
%
\condata{EXPR}{Expression}
{AlgebraicallyClosedFunctionSpace CombinatorialOpsCategory FunctionSpace
LiouvillianFunctionCategory RetractableTo SpecialFunctionCategory 
TranscendentalFunctionCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} Beta Ci
D Ei Gamma Si abs acos acosh acot acoth acsc acsch airyAi airyBi
applyQuote asec asech asin asinh associates? atan atanh belong?
besselI besselJ besselK besselY binomial box characteristic
charthRoot coerce commutator conjugate convert cos cosh cot coth
csc csch definingPolynomial denom denominator differentiate digamma
dilog distribute divide elt erf euclideanSize eval exp
expressIdealMember exquo extendedEuclidean factor factorial
factorials freeOf? gcd ground ground? height integral inv is?
isExpt isMult isPlus isPower isTimes kernel kernels lcm li log
mainKernel map max min minPoly multiEuclidean nthRoot numer
numerator one?  operator operators paren patternMatch permutation
pi polygamma prime? principalIdeal product quo recip reduce
reducedSystem rem retract retractIfCan rootOf rootsOf sec sech sin
sinh sizeLess? sqrt squareFree squareFreePart subst summation tan
tanh tower unit? unitCanonical unitNormal univariate variables
zero? zeroOf zerosOf}
%
\condata{EAB}{ExtAlgBasis}{OrderedSet}
{{\tt <} {\tt =} Nul coerce degree exponents max min}
%
\condata{FR}{Factored}{Algebra DifferentialExtension Eltable Evalable 
FullyEvalableOver FullyRetractableTo GcdDomain InnerEvalable IntegralDomain 
RealConstant UniqueFactorizationDomain}{0 1 {\tt *} {\tt **} {\tt +} 
{\tt -} {\tt =} D associates? characteristic coerce convert differentiate 
elt eval expand exponent exquo factor factorList factors flagFactor gcd 
irreducibleFactor lcm makeFR map nilFactor nthExponent nthFactor 
nthFlag numberOfFactors one? prime? primeFactor rational rational? 
rationalIfCan recip retract retractIfCan sqfrFactor squareFree 
squareFreePart unit unit? unitCanonical unitNormal unitNormalize zero?}
%
\condata{FNAME}{FileName}{FileNameCategory}
{{\tt =} coerce directory exists? extension filename name new readable?
   writable?}
%
\condata{FILE}{File}{FileCategory}
{{\tt =} close! coerce iomode name open read! readIfCan! reopen! write!}
%
\condata{FDIV}{FiniteDivisor}{AbelianGroup}
{0 {\tt *} {\tt +} {\tt -} {\tt =} algsplit coerce divisor finiteBasis
generator ideal lSpaceBasis mkBasicDiv principal? reduce zero?}
%
\condata{FFCGP}{FiniteFieldCyclicGroupExtensionByPolynomial}
{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius 
algebraic? associates? basis characteristic charthRoot coerce conditionP
coordinates createNormalElement createPrimitiveElement 
definingPolynomial degree dimension discreteLog divide euclideanSize 
expressIdealMember exquo extendedEuclidean extensionDegree factor 
factorsOfCyclicGroupSize gcd generator getZechTable inGroundField? 
index init inv lcm lookup minimalPolynomial multiEuclidean nextItem 
norm normal? normalElement one? order prime? primeFrobenius primitive? 
primitiveElement principalIdeal quo random recip rem representationType 
represents retract retractIfCan size sizeLess? squareFree squareFreePart 
tableForDiscreteLogarithm trace transcendenceDegree transcendent? unit? 
unitCanonical unitNormal zero?}
%
\condata{FFCGX}{FiniteFieldCyclicGroupExtension}
{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius 
algebraic? associates? basis characteristic charthRoot coerce 
conditionP coordinates createNormalElement createPrimitiveElement 
definingPolynomial degree dimension discreteLog divide euclideanSize
expressIdealMember exquo extendedEuclidean extensionDegree factor 
factorsOfCyclicGroupSize gcd generator getZechTable inGroundField? 
index init inv lcm lookup minimalPolynomial multiEuclidean nextItem 
norm normal? normalElement one? order prime? primeFrobenius primitive? 
primitiveElement principalIdeal quo random recip rem representationType
represents retract retractIfCan size sizeLess? squareFree squareFreePart 
tableForDiscreteLogarithm trace transcendenceDegree transcendent? unit? 
unitCanonical unitNormal zero?}
%
\condata{FFCG}{FiniteFieldCyclicGroup}{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius algebraic? 
associates? basis characteristic charthRoot coerce conditionP coordinates 
createNormalElement createPrimitiveElement definingPolynomial degree 
dimension discreteLog divide euclideanSize expressIdealMember exquo
extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize gcd 
generator getZechTable inGroundField? index init inv lcm lookup 
minimalPolynomial multiEuclidean nextItem norm normal? normalElement 
one? order prime? primeFrobenius primitive? primitiveElement 
principalIdeal quo random recip rem representationType represents 
retract retractIfCan size sizeLess? squareFree squareFreePart 
tableForDiscreteLogarithm trace transcendenceDegree transcendent? unit?
unitCanonical unitNormal zero?}
%
\condata{FFP}{FiniteFieldExtensionByPolynomial}
{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius algebraic? 
associates? basis characteristic charthRoot coerce conditionP coordinates
createNormalElement createPrimitiveElement definingPolynomial degree 
dimension discreteLog divide euclideanSize expressIdealMember exquo 
extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize gcd 
generator inGroundField? index init inv lcm lookup minimalPolynomial 
multiEuclidean nextItem norm normal? normalElement one? order prime?
primeFrobenius primitive? primitiveElement principalIdeal quo random 
recip rem representationType represents retract retractIfCan size 
sizeLess? squareFree squareFreePart tableForDiscreteLogarithm trace 
transcendenceDegree transcendent? unit? unitCanonical unitNormal zero?}
%
\condata{FFX}{FiniteFieldExtension}{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius\\
algebraic? associates? basis characteristic charthRoot coerce\\
conditionP coordinates createNormalElement createPrimitiveElement\\
definingPolynomial degree dimension discreteLog divide euclideanSize\\
expressIdealMember exquo extendedEuclidean extensionDegree factor\\
factorsOfCyclicGroupSize gcd generator inGroundField? index init inv\\
lcm lookup minimalPolynomial multiEuclidean nextItem norm normal?\\
normalElement one? order prime? primeFrobenius primitive?\\ 
primitiveElement principalIdeal quo random recip rem representationType\\
represents retract retractIfCan size sizeLess? squareFree squareFreePart\\
tableForDiscreteLogarithm trace transcendenceDegree transcendent?\\
unit? unitCanonical unitNormal zero?}
%
\condata{FFNBP}{FiniteFieldNormalBasisExtensionByPolynomial}
{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius 
algebraic? associates? basis characteristic charthRoot coerce conditionP
coordinates createNormalElement createPrimitiveElement definingPolynomial 
degree dimension discreteLog divide euclideanSize expressIdealMember 
exquo extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize 
gcd generator getMultiplicationMatrix getMultiplicationTable 
inGroundField? index init inv lcm lookup minimalPolynomial multiEuclidean 
nextItem norm normal? normalElement one? order prime? primeFrobenius 
primitive? primitiveElement principalIdeal quo random recip rem 
representationType represents retract retractIfCan size sizeLess?
sizeMultiplication squareFree squareFreePart tableForDiscreteLogarithm 
trace transcendenceDegree transcendent? unit? unitCanonical unitNormal zero?}
%
\condata{FFNBX}{FiniteFieldNormalBasisExtension}
{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius 
algebraic? associates? basis characteristic charthRoot coerce 
conditionP coordinates createNormalElement createPrimitiveElement 
definingPolynomial degree dimension discreteLog divide euclideanSize
expressIdealMember exquo extendedEuclidean extensionDegree factor 
factorsOfCyclicGroupSize gcd generator getMultiplicationMatrix 
getMultiplicationTable inGroundField? index init inv lcm lookup 
minimalPolynomial multiEuclidean nextItem norm normal? normalElement 
one? order prime? primeFrobenius primitive? primitiveElement
principalIdeal quo random recip rem representationType represents 
retract retractIfCan size sizeLess? sizeMultiplication squareFree 
squareFreePart tableForDiscreteLogarithm trace transcendenceDegree 
transcendent? unit? unitCanonical unitNormal zero?}
%
\condata{FFNB}{FiniteFieldNormalBasis}{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius algebraic? 
associates? basis characteristic charthRoot coerce conditionP coordinates 
createNormalElement createPrimitiveElement definingPolynomial degree 
dimension discreteLog divide euclideanSize expressIdealMember exquo
extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize 
gcd generator getMultiplicationMatrix getMultiplicationTable 
inGroundField? index init inv lcm lookup minimalPolynomial 
multiEuclidean nextItem norm normal? normalElement one? order prime? 
primeFrobenius primitive? primitiveElement principalIdeal quo random 
recip rem representationType represents retract retractIfCan size 
sizeLess? sizeMultiplication squareFree squareFreePart 
tableForDiscreteLogarithm trace transcendenceDegree transcendent? 
unit? unitCanonical unitNormal zero?}
%
\condata{FF}{FiniteField}{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius algebraic? 
associates? basis characteristic charthRoot coerce conditionP coordinates 
createNormalElement createPrimitiveElement definingPolynomial degree 
dimension discreteLog divide euclideanSize expressIdealMember exquo
extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize gcd 
generator inGroundField? index init inv lcm lookup minimalPolynomial 
multiEuclidean nextItem norm normal? normalElement one? order prime? 
primeFrobenius primitive? primitiveElement principalIdeal quo random 
recip rem representationType represents retract retractIfCan size sizeLess?
squareFree squareFreePart tableForDiscreteLogarithm trace 
transcendenceDegree transcendent? unit? unitCanonical unitNormal zero?}
%
\condata{FARRAY}{FlexibleArray}
{ExtensibleLinearAggregate\\ OneDimensionalArrayAggregate}
{{\tt \#} {\tt <} {\tt =} any? coerce concat concat! construct convert 
copy copyInto! count delete delete! elt empty empty? entries entry? eq? 
every? fill! find first flexibleArray index? indices insert insert! 
less? map map! max maxIndex member? members merge merge! min minIndex 
more? new parts physicalLength physicalLength! position qelt qsetelt! 
reduce remove remove! removeDuplicates removeDuplicates! reverse reverse! 
select select! setelt shrinkable size? sort sort! sorted? swap!}
%
\condata{FLOAT}{Float}
{CoercibleTo ConvertibleTo DifferentialRing FloatingPointSystem 
TranscendentalFunctionCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs acos 
acosh acot acoth acsc acsch asec asech asin asinh associates? atan atanh 
base bits ceiling characteristic coerce convert cos cosh cot coth csc 
csch decreasePrecision differentiate digits divide euclideanSize exp 
exp1 exponent expressIdealMember exquo extendedEuclidean factor float
floor fractionPart gcd increasePrecision inv lcm log log10 log2 
mantissa max min multiEuclidean negative? norm normalize nthRoot one? 
order outputFixed outputFloating outputGeneral outputSpacing patternMatch 
pi positive? precision prime? principalIdeal quo rationalApproximation 
recip relerror rem retract retractIfCan round sec sech shift sign sin
sinh sizeLess? sqrt squareFree squareFreePart tan tanh truncate unit? 
unitCanonical unitNormal wholePart zero?}
%
\condata{FRIDEAL}{FractionalIdeal}{Group}
{1 {\tt *} {\tt **} {\tt /} {\tt =} basis coerce commutator conjugate denom
ideal inv minimize norm numer one? randomLC recip}
%
\condata{FRAC}{Fraction}{QuotientFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs
associates? ceiling characteristic charthRoot coerce conditionP convert 
denom denominator differentiate divide elt euclideanSize eval 
expressIdealMember exquo extendedEuclidean factor factorPolynomial 
factorSquareFreePolynomial floor fractionPart gcd gcdPolynomial init 
inv lcm map max min multiEuclidean negative? nextItem numer numerator one?
patternMatch positive? prime? principalIdeal quo random recip 
reducedSystem rem retract retractIfCan sign sizeLess? 
solveLinearPolynomialEquation squareFree squareFreePart 
squareFreePolynomial unit? unitCanonical unitNormal wholePart zero?}
%
\condata{FRMOD}{FramedModule}{Monoid}
{1 {\tt *} {\tt **} {\tt =} basis coerce module norm one? recip}
%
\condata{FAGROUP}{FreeAbelianGroup}
{AbelianGroup FreeAbelianMonoidCategory Module OrderedSet}
{0 {\tt *} {\tt +} {\tt -} {\tt <} {\tt =} coefficient coerce 
highCommonTerms mapCoef mapGen max min nthCoef nthFactor retract 
retractIfCan size terms zero?}
%
\condata{FAMONOID}{FreeAbelianMonoid}{FreeAbelianMonoidCategory}
{0 {\tt *} {\tt +} {\tt -} {\tt =} coefficient coerce highCommonTerms 
mapCoef mapGen nthCoef nthFactor retract retractIfCan size terms zero?}
%
\condata{FGROUP}{FreeGroup}{Group RetractableTo}
{1 {\tt *} {\tt **} {\tt /} {\tt =} coerce commutator conjugate factors
inv mapExpon mapGen nthExpon nthFactor one? recip retract retractIfCan size}
%
\condata{FM}{FreeModule}{BiModule IndexedDirectProductCategory Module}
{0 {\tt *} {\tt +} {\tt -} {\tt =} coerce leadingCoefficient 
leadingSupport map monomial reductum zero?}
%
\condata{FMONOID}{FreeMonoid}{Monoid OrderedSet RetractableTo}
{1 {\tt *} {\tt **} {\tt <} {\tt =} coerce divide factors hclf hcrf 
lquo mapExpon mapGen max min nthExpon nthFactor one? overlap recip 
retract retractIfCan rquo size}
%
\condata{FNLA}{FreeNilpotentLie}{NonAssociativeAlgebra}
{0 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} antiCommutator associator 
coerce commutator deepExpand dimension generator leftPower rightPower 
shallowExpand zero?}
%
\condata{FUNCTION}{FunctionCalled}{SetCategory}{{\tt =} coerce name}
%
\condata{GDMP}{GeneralDistributedMultivariatePolynomial}{PolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D associates? 
characteristic charthRoot coefficient coefficients coerce conditionP const 
content convert degree differentiate discriminant eval exquo factor 
factorPolynomial factorSquareFreePolynomial gcd gcdPolynomial ground 
ground? isExpt isPlus isTimes lcm leadingCoefficient leadingMonomial 
mainVariable map mapExponents max min minimumDegree monicDivide monomial 
monomial? monomials multivariate numberOfMonomials one? prime? 
primitiveMonomials primitivePart recip reducedSystem reductum reorder 
resultant retract retractIfCan solveLinearPolynomialEquation squareFree 
squareFreePart squareFreePolynomial totalDegree unit? unitCanonical 
unitNormal univariate variables zero?}
%
\condata{GSTBL}{GeneralSparseTable}{TableAggregate}
{{\tt \#} {\tt =} any? bag coerce construct copy count dictionary elt 
empty empty? entries entry? eq? every? extract! fill! find first index? 
indices insert! inspect key? keys less? map map! maxIndex member? 
members minIndex more? parts qelt qsetelt! reduce remove remove! 
removeDuplicates search select select! setelt size? swap! table}
%
\condata{GCNAALG}{GenericNonAssociativeAlgebra\\}
{FramedNonAssociativeAlgebra LeftModule}
{0 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} JacobiIdentity? 
JordanAlgebra? alternative? antiAssociative? antiCommutative? 
antiCommutator apply associative? associator associatorDependence 
basis coerce commutative? commutator conditionsForIdempotents convert
coordinates elt flexible? generic genericLeftDiscriminant 
genericLeftMinimalPolynomial genericLeftNorm genericLeftTrace
genericLeftTraceForm genericRightDiscriminant 
genericRightMinimalPolynomial genericRightNorm genericRightTrace
genericRightTraceForm jordanAdmissible? leftAlternative? 
leftCharacteristicPolynomial leftDiscriminant leftMinimalPolynomial 
leftNorm leftPower leftRankPolynomial leftRecip leftRegularRepresentation 
leftTrace leftTraceMatrix leftUnit leftUnits lieAdmissible? lieAlgebra? 
noncommutativeJordanAlgebra? plenaryPower powerAssociative? rank recip 
represents rightAlternative? rightCharacteristicPolynomial rightDiscriminant
rightMinimalPolynomial rightNorm rightPower rightRankPolynomial 
rightRecip rightRegularRepresentation rightTrace rightTraceMatrix 
rightUnit rightUnits someBasis structuralConstants unit zero?}
%
\condata{GRIMAGE}{GraphImage}{SetCategory}
{{\tt =} appendPoint coerce component graphImage key makeGraphImage point
pointLists putColorInfo ranges units}
%
\condata{HASHTBL}{HashTable}{TableAggregate}
{{\tt \#} {\tt =} any? bag coerce construct copy count dictionary elt empty
empty? entries entry? eq? every? extract! fill! find first index? indices 
insert! inspect key? keys less? map map! maxIndex member? members minIndex 
more? parts qelt qsetelt! reduce remove remove! removeDuplicates search 
select select! setelt size? swap! table}
%
\condata{HEAP}{Heap}{PriorityQueueAggregate}
{{\tt \#} {\tt =} any? bag coerce copy count empty empty? eq? every?
extract! heap insert! inspect less? map map! max member? members merge 
merge! more? parts size?}
%
\condata{HEXADEC}{HexadecimalExpansion}{QuotientFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs 
associates? ceiling characteristic coerce convert denom denominator 
differentiate divide euclideanSize expressIdealMember exquo 
extendedEuclidean factor floor fractionPart gcd hex init inv lcm map 
max min multiEuclidean negative? nextItem numer numerator one? 
patternMatch positive? prime? principalIdeal quo random recip 
reducedSystem rem retract retractIfCan sign sizeLess? squareFree 
squareFreePart unit? unitCanonical unitNormal wholePart zero?}
%
\condata{ICARD}{IndexCard}{OrderedSet}
{{\tt <} {\tt =} coerce display elt fullDisplay max min}
%
\condata{IBITS}{IndexedBits}{BitAggregate}
{{\tt \#} {\tt <} {\tt =} And Not Or {\tt \^{}} and any? coerce concat
construct convert copy copyInto! count delete elt empty empty? entries 
entry? eq? every? fill! find first index? indices insert less? map map! 
max maxIndex member? members merge min minIndex more? nand new nor not 
or parts position qelt qsetelt! reduce remove removeDuplicates reverse 
reverse! select setelt size? sort sort! sorted? swap! xor}
%
\condata{IDPAG}{IndexedDirectProductAbelianGroup\\}
{AbelianGroup IndexedDirectProductCategory}
{0 {\tt *} {\tt +} {\tt -} {\tt =} coerce leadingCoefficient leadingSupport 
map monomial reductum zero?}
%
\condata{IDPAM}{IndexedDirectProductAbelianMonoid\\}
{AbelianMonoid IndexedDirectProductCategory}{0 {\tt *} {\tt +} {\tt =} 
coerce leadingCoefficient leadingSupport map monomial reductum zero?}
%
\condata{IDPO}{IndexedDirectProductObject\\}{IndexedDirectProductCategory}
{{\tt =} coerce leadingCoefficient leadingSupport map monomial reductum}
%
\condata{IDPOAMS}{IndexedDirectProductOrderedAbelianMonoidSup\\}
{IndexedDirectProductCategory\\ OrderedAbelianMonoidSup\\}
{0 {\tt *} {\tt +} {\tt -} {\tt <} {\tt =} coerce leadingCoefficient 
leadingSupport map max min monomial reductum sup zero?}
%
\condata{IDPOAM}{IndexedDirectProductOrderedAbelianMonoid}
{IndexedDirectProductCategory OrderedAbelianMonoid}{0 {\tt *} {\tt +} 
{\tt <} {\tt =} coerce leadingCoefficient leadingSupport map max min 
monomial reductum zero?}
%
\condata{INDE}{IndexedExponents}{IndexedDirectProductCategory\\ 
OrderedAbelianMonoidSup}{0 {\tt *} {\tt +} {\tt -} {\tt <} {\tt =} coerce 
leadingCoefficient leadingSupport map max min monomial reductum sup zero?}
%
\condata{IFARRAY}{IndexedFlexibleArray}
{ExtensibleLinearAggregate OneDimensionalArrayAggregate}
{{\tt \#} {\tt <} {\tt =} any? coerce concat concat! construct convert 
copy copyInto! count delete delete! elt empty empty? entries entry? eq?
every? fill! find first flexibleArray index? indices insert insert! 
less? map map! max maxIndex member? members merge merge! min minIndex 
more? new parts physicalLength physicalLength! position qelt qsetelt! 
reduce remove remove! removeDuplicates removeDuplicates! reverse reverse! 
select select! setelt shrinkable size? sort sort! sorted? swap!}
%
\condata{ILIST}{IndexedList}{ListAggregate}
{{\tt \#} {\tt <} {\tt =} any? child? children coerce concat concat!
construct convert copy copyInto! count cycleEntry cycleLength cycleSplit! 
cycleTail cyclic? delete delete! distance elt empty empty? entries entry? 
eq? every? explicitlyFinite? fill! find first index? indices insert 
insert! last leaf? less? list map map! max maxIndex member? members 
merge merge! min minIndex more? new node? nodes parts position 
possiblyInfinite? qelt qsetelt! reduce remove remove! removeDuplicates 
removeDuplicates! rest reverse reverse! second select select! setchildren! 
setelt setfirst! setlast! setrest! setvalue! size? sort sort! sorted? 
split! swap! tail third value}
%
\condata{IMATRIX}{IndexedMatrix}{MatrixCategory}
{{\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} antisymmetric? 
any? coerce column copy count determinant diagonal? diagonalMatrix elt 
empty empty? eq? every? exquo fill! horizConcat inverse less? listOfLists 
map map! matrix maxColIndex maxRowIndex member? members minColIndex
minRowIndex minordet more? ncols new nrows nullSpace nullity parts qelt 
qsetelt! rank row rowEchelon scalarMatrix setColumn! setRow! setelt 
setsubMatrix! size? square? squareTop subMatrix swapColumns! swapRows! 
symmetric? transpose vertConcat zero}
%
\condata{IARRAY1}{IndexedOneDimensionalArray}{OneDimensionalArrayAggregate}
{{\tt \#} {\tt <} {\tt =} any? coerce concat construct convert copy 
copyInto! count delete elt empty empty? entries entry? eq? every? fill! 
find first index? indices insert less? map map! max maxIndex member? 
members merge min minIndex more? new parts position qelt qsetelt!
reduce remove removeDuplicates reverse reverse! select setelt size? 
sort sort! sorted? swap!}
%
\condata{ISTRING}{IndexedString}{StringAggregate}
{{\tt \#} {\tt <} {\tt =} any? coerce concat construct copy copyInto!
count delete elt empty empty? entries entry? eq? every? fill! find first 
hash index? indices insert leftTrim less? lowerCase lowerCase! map map! 
match? max maxIndex member? members merge min minIndex more? new parts 
position prefix? qelt qsetelt! reduce remove removeDuplicates replace 
reverse reverse! rightTrim select setelt size? sort sort! sorted?
split substring? suffix? swap! trim upperCase upperCase!}
%
\condata{IARRAY2}{IndexedTwoDimensionalArray\\}{TwoDimensionalArrayCategory}
{{\tt \#} {\tt =} any? coerce column copy count elt empty empty? eq? every? 
fill! less? map map! maxColIndex maxRowIndex member? members minColIndex 
minRowIndex more? ncols new nrows parts qelt qsetelt! row setColumn! 
setRow! setelt size?}
%
\condata{IVECTOR}{IndexedVector}{VectorCategory}
{{\tt \#} {\tt *} {\tt +} {\tt -} {\tt <} {\tt =} any? coerce concat
construct convert copy copyInto! count delete dot elt empty empty? 
entries entry? eq? every? fill! find first index? indices insert 
less? map map! max maxIndex member? members merge min minIndex more? 
new parts position qelt qsetelt! reduce remove removeDuplicates 
reverse reverse! select setelt size? sort sort! sorted? swap! zero}
%
\condata{ITUPLE}{InfiniteTuple}{CoercibleTo}{coerce construct filterUntil 
filterWhile generate map select}
%
\condata{IFF}{InnerFiniteField}{FiniteAlgebraicExtensionField}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius algebraic? 
associates? basis characteristic charthRoot coerce conditionP coordinates 
createNormalElement createPrimitiveElement definingPolynomial degree 
dimension discreteLog divide euclideanSize expressIdealMember exquo
extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize 
gcd generator inGroundField? index init inv lcm lookup minimalPolynomial 
multiEuclidean nextItem norm normal? normalElement one? order prime? 
primeFrobenius primitive? primitiveElement principalIdeal quo random 
recip rem representationType represents retract retractIfCan size 
sizeLess? squareFree squareFreePart tableForDiscreteLogarithm trace 
transcendenceDegree transcendent? unit? unitCanonical unitNormal zero?}
%
\condata{IFAMON}{InnerFreeAbelianMonoid}{FreeAbelianMonoidCategory}
{0 {\tt *} {\tt +} {\tt -} {\tt =} coefficient coerce highCommonTerms 
mapCoef mapGen nthCoef nthFactor retract retractIfCan size terms zero?}
%
\condata{IIARRAY2}{InnerIndexedTwoDimensionalArray\\}
{TwoDimensionalArrayCategory}{\\
{\tt \#} {\tt =} any? coerce column copy count elt empty empty? eq?\\
every? fill! less? map map! maxColIndex maxRowIndex member? members\\
minColIndex minRowIndex more? ncols new nrows parts qelt qsetelt!\\
row setColumn! setRow! setelt size?}
%
\condata{IPADIC}{InnerPAdicInteger}{PAdicIntegerCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} approximate associates? 
characteristic coerce complete digits divide euclideanSize 
expressIdealMember exquo extend extendedEuclidean gcd lcm moduloP 
modulus multiEuclidean one? order principalIdeal quo quotientByP 
recip rem sizeLess? sqrt unit? unitCanonical unitNormal zero?}
%
\condata{IPF}{InnerPrimeField}
{ConvertibleTo\\ FiniteAlgebraicExtensionField FiniteFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius algebraic? 
associates? basis characteristic charthRoot coerce conditionP convert 
coordinates createNormalElement createPrimitiveElement definingPolynomial 
degree dimension discreteLog divide euclideanSize expressIdealMember 
exquo extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize 
gcd generator inGroundField? index init inv lcm lookup minimalPolynomial 
multiEuclidean nextItem norm normal? normalElement one? order prime? 
primeFrobenius primitive? primitiveElement principalIdeal quo random 
recip rem representationType represents retract retractIfCan size 
sizeLess? squareFree squareFreePart tableForDiscreteLogarithm trace
transcendenceDegree transcendent? unit? unitCanonical unitNormal zero?}
%
\condata{ITAYLOR}{InnerTaylorSeries}{IntegralDomain Ring}{0 1 {\tt *} 
{\tt **} {\tt +} {\tt -} {\tt =} associates? characteristic coefficients 
coerce exquo one? order pole? recip series unit? unitCanonical unitNormal 
zero?}
%
\condata{INFORM}{InputForm}{ConvertibleTo SExpressionCategory}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt /} {\tt =} atom? binary car 
cdr coerce compile convert declare destruct elt eq expr flatten float 
float? function integer integer? interpret lambda list? null? pair? 
string string? symbol symbol? uequal unparse}
%
\condata{ZMOD}{IntegerMod}{CommutativeRing ConvertibleTo Finite StepThrough}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} characteristic coerce convert 
index init lookup nextItem one? random recip size zero?}
%
\condata{INT}{Integer}{ConvertibleTo IntegerNumberSystem}{0 1 {\tt *} 
{\tt **} {\tt +} {\tt -} {\tt <} {\tt =} D abs addmod associates? base 
binomial bit? characteristic coerce convert copy dec differentiate 
divide euclideanSize even? expressIdealMember exquo extendedEuclidean 
factor factorial gcd hash inc init invmod lcm length mask max min mulmod
multiEuclidean negative? nextItem odd? one? patternMatch permutation 
positive? positiveRemainder powmod prime? principalIdeal quo random 
rational rational? rationalIfCan recip reducedSystem rem retract 
retractIfCan shift sign sizeLess? squareFree squareFreePart submod 
symmetricRemainder unit? unitCanonical unitNormal zero?}
%
\condata{IR}{IntegrationResult}{Module RetractableTo}{0 {\tt *} {\tt +} 
{\tt -} {\tt =} D coerce differentiate elem? integral logpart mkAnswer 
notelem ratpart retract retractIfCan zero?}
%
\condata{KERNEL}{Kernel}{CachableSet ConvertibleTo Patternable}{{\tt <} 
{\tt =} argument coerce convert height is? kernel max min name operator 
position setPosition symbolIfCan}
%
\condata{KAFILE}{KeyedAccessFile}{FileCategory TableAggregate}{{\tt \#} 
{\tt =} any? bag close! coerce construct copy count dictionary elt 
empty empty? entries entry? eq? every? extract! fill! find first 
index? indices insert! inspect iomode key? keys less? map map! 
maxIndex member? members minIndex more? name open pack! parts 
qelt qsetelt! read! reduce remove remove! removeDuplicates reopen! 
search select select! setelt size? swap! table write!}
%
\condata{LAUPOL}{LaurentPolynomial}
{CharacteristicNonZero CharacteristicZero ConvertibleTo DifferentialExtension
EuclideanDomain FullyRetractableTo IntegralDomain RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} D associates? characteristic 
charthRoot coefficient coerce convert degree differentiate divide 
euclideanSize expressIdealMember exquo extendedEuclidean gcd lcm 
leadingCoefficient monomial monomial? multiEuclidean one? order
principalIdeal quo recip reductum rem retract retractIfCan separate 
sizeLess? trailingCoefficient unit? unitCanonical unitNormal zero?}
%
\condata{LIB}{Library}{TableAggregate}{{\tt \#} {\tt =} any? bag coerce 
construct copy count dictionary elt empty empty? entries entry? eq? 
every? extract! fill! find first index? indices insert! inspect key? 
keys less? library map map! maxIndex member? members minIndex more? 
pack! parts qelt qsetelt! reduce remove remove! removeDuplicates search
select select! setelt size? swap! table}
%
\condata{LSQM}{LieSquareMatrix}
{CoercibleTo FramedNonAssociativeAlgebra SquareMatrixCategory}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D\\ 
JacobiIdentity? JordanAlgebra? alternative? antiAssociative?\\ 
antiCommutative? antiCommutator antisymmetric? any? apply\\ 
associative? associator associatorDependence basis characteristic\\ 
coerce column commutative? commutator conditionsForIdempotents\\ 
convert coordinates copy count determinant diagonal diagonal?\\
diagonalMatrix diagonalProduct differentiate elt empty empty? eq?\\ 
every? exquo flexible? inverse jordanAdmissible? leftAlternative?\\ 
leftCharacteristicPolynomial leftDiscriminant leftMinimalPolynomial\\ 
leftNorm leftPower leftRankPolynomial leftRecip\\ 
leftRegularRepresentation leftTrace leftTraceMatrix leftUnit leftUnits\\ 
less? lieAdmissible? lieAlgebra? listOfLists map map! matrix\\ 
maxColIndex maxRowIndex member? members minColIndex minRowIndex\\
minordet more? ncols noncommutativeJordanAlgebra? nrows nullSpace\\ 
nullity one? parts plenaryPower powerAssociative? qelt rank recip\\ 
reducedSystem represents retract retractIfCan rightAlternative?\\ 
rightCharacteristicPolynomial rightDiscriminant rightMinimalPolynomial\\ 
rightNorm rightPower rightRankPolynomial rightRecip\\ 
rightRegularRepresentation rightTrace rightTraceMatrix rightUnit\\ 
rightUnits row rowEchelon scalarMatrix size? someBasis square?\\
structuralConstants symmetric? trace unit zero?}
%
\condata{LODO}{LinearOrdinaryDifferentialOperator}{MonogenicLinearOperator}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} D characteristic coefficient 
coerce degree elt leadingCoefficient leftDivide leftExactQuotient leftGcd 
leftLcm leftQuotient leftRemainder minimumDegree monomial one? recip 
reductum rightDivide rightExactQuotient rightGcd rightLcm rightQuotient 
rightRemainder zero?}
%
\condata{LMOPS}{ListMonoidOps}{RetractableTo SetCategory}{\\
{\tt =} coerce leftMult listOfMonoms\\ 
makeMulti makeTerm makeUnit mapExpon mapGen nthExpon nthFactor\\ 
outputForm plus retract retractIfCan reverse reverse! rightMult size}
%
\condata{LMDICT}{ListMultiDictionary}{MultiDictionary}
{{\tt \#} {\tt =} any? bag coerce construct convert copy count dictionary 
duplicates duplicates? empty empty? eq? every? extract! find insert! 
inspect less? map map! member? members more? parts reduce remove remove! 
removeDuplicates removeDuplicates! select select! size? substitute}
%
\condata{LIST}{List}{ListAggregate}{{\tt \#} {\tt <} {\tt =} any? append 
child? children coerce concat concat! cons construct convert copy copyInto! 
count cycleEntry cycleLength cycleSplit! cycleTail cyclic? delete delete! 
distance elt empty empty? entries entry? eq? every? explicitlyFinite? 
fill! find first index? indices insert insert! last leaf? less? list map 
map! max maxIndex member? members merge merge! min minIndex more? new 
nil node? nodes null parts position possiblyInfinite? qelt qsetelt! 
reduce remove remove! removeDuplicates removeDuplicates! rest reverse 
reverse! second select select! setDifference setIntersection setUnion 
setchildren! setelt setfirst! setlast! setrest! setvalue! size? sort 
sort! sorted? split! swap! tail third value}
%
\condata{LA}{LocalAlgebra}{Algebra OrderedRing}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} abs
characteristic coerce denom max min negative? numer one? positive? 
recip sign zero?}
%
\condata{LO}{Localize}{Module OrderedAbelianGroup}
{0 {\tt *} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} coerce denom max
min numer zero?}
%
\condata{MKCHSET}{MakeCachableSet}{CachableSet CoercibleTo}
{{\tt <} {\tt =} coerce max min position setPosition}
%
\condata{MKODRING}{MakeOrdinaryDifferentialRing}{CoercibleTo DifferentialRing}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} D characteristic coerce 
differentiate one? recip zero?}
%
\condata{MATRIX}{Matrix}{MatrixCategory}{{\tt \#} {\tt *} {\tt **} {\tt +} 
{\tt -} {\tt /} {\tt =} antisymmetric? any? coerce column copy count 
determinant diagonal? diagonalMatrix elt empty empty? eq? every? exquo 
fill! horizConcat inverse less? listOfLists map map! matrix maxColIndex 
maxRowIndex member? members minColIndex minRowIndex minordet more? ncols 
new nrows nullSpace nullity parts qelt qsetelt! rank row rowEchelon 
scalarMatrix setColumn! setRow! setelt setsubMatrix! size? square? 
squareTop subMatrix swapColumns! swapRows! symmetric? transpose 
vertConcat zero}
%
\condata{MODMON}{ModMonic}{Finite UnivariatePolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} An D 
UnVectorise Vectorise associates? characteristic charthRoot coefficient 
coefficients coerce composite computePowers conditionP content degree 
differentiate discriminant divide divideExponents elt euclideanSize eval
expressIdealMember exquo extendedEuclidean factor factorPolynomial 
factorSquareFreePolynomial gcd gcdPolynomial ground ground? index init 
integrate isExpt isPlus isTimes lcm leadingCoefficient leadingMonomial 
lift lookup mainVariable makeSUP map mapExponents max min minimumDegree 
modulus monicDivide monomial monomial? monomials multiEuclidean
multiplyExponents multivariate nextItem numberOfMonomials one? order pow 
prime? primitiveMonomials primitivePart principalIdeal pseudoDivide 
pseudoQuotient pseudoRemainder quo random recip reduce reducedSystem 
reductum rem resultant retract retractIfCan separate setPoly size 
sizeLess? solveLinearPolynomialEquation squareFree squareFreePart
squareFreePolynomial subResultantGcd totalDegree unit? unitCanonical 
unitNormal univariate unmakeSUP variables vectorise zero?}
%
\condata{MODFIELD}{ModularField}{Field}{0 1 {\tt *} {\tt **} {\tt +} {\tt -} 
{\tt /} {\tt =} associates? characteristic coerce divide euclideanSize 
exQuo expressIdealMember exquo extendedEuclidean factor gcd inv lcm 
modulus multiEuclidean one? prime? principalIdeal quo recip reduce rem 
sizeLess? squareFree squareFreePart unit? unitCanonical unitNormal zero?}
%
\condata{MODRING}{ModularRing}{Ring}{0 1 {\tt *} {\tt **} {\tt +} {\tt -} 
{\tt =} characteristic coerce exQuo inv modulus one? recip reduce zero?}
%
\condata{MOEBIUS}{MoebiusTransform}{Group}{1 {\tt *} {\tt **} {\tt /} 
{\tt =} coerce commutator conjugate eval inv moebius one? recip scale shift}
%
\condata{MRING}{MonoidRing}
{Algebra CharacteristicNonZero CharacteristicZero\\ Finite RetractableTo Ring}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} characteristic charthRoot 
coefficient coefficients coerce index leadingCoefficient leadingMonomial 
lookup map monomial monomial? monomials numberOfMonomials one? random 
recip reductum retract retractIfCan size terms zero?}
%
\condata{MSET}{Multiset}{MultisetAggregate}{{\tt \#} {\tt <} {\tt =} 
any? bag brace coerce construct convert copy count dictionary difference 
duplicates empty empty? eq? every? extract! find insert! inspect intersect 
less? map map! member? members more? multiset parts reduce remove remove! 
removeDuplicates removeDuplicates! select select! size? subset? 
symmetricDifference union}
%
\condata{MPOLY}{MultivariatePolynomial}{PolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
associates? characteristic charthRoot coefficient coefficients 
coerce conditionP content convert degree differentiate discriminant 
eval exquo factor factorPolynomial factorSquareFreePolynomial gcd 
gcdPolynomial ground ground? isExpt isPlus isTimes lcm 
leadingCoefficient leadingMonomial mainVariable map mapExponents max 
min minimumDegree monicDivide monomial monomial? monomials 
multivariate numberOfMonomials one? prime? primitiveMonomials
primitivePart recip reducedSystem reductum resultant retract 
retractIfCan solveLinearPolynomialEquation squareFree squareFreePart 
squareFreePolynomial totalDegree unit? unitCanonical unitNormal 
univariate variables zero?}
%
\condata{NDP}{NewDirectProduct}{DirectProductCategory}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
abs any? characteristic coerce copy count differentiate dimension 
directProduct dot elt empty empty? entries entry? eq? every? fill! first 
index index? indices less? lookup map map! max maxIndex member? members 
min minIndex more? negative? one? parts positive? qelt qsetelt! random 
recip reducedSystem retract retractIfCan setelt sign size size? sup 
swap! unitVector zero?}
%
\condata{NDMP}{NewDistributedMultivariatePolynomial}{PolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D associates? 
characteristic charthRoot coefficient coefficients coerce conditionP const 
content convert degree differentiate discriminant eval exquo factor 
factorPolynomial factorSquareFreePolynomial gcd gcdPolynomial ground 
ground? isExpt isPlus isTimes lcm leadingCoefficient leadingMonomial 
mainVariable map mapExponents max min minimumDegree monicDivide monomial 
monomial? monomials multivariate numberOfMonomials one? prime? 
primitiveMonomials primitivePart recip reducedSystem reductum reorder 
resultant retract retractIfCan solveLinearPolynomialEquation squareFree 
squareFreePart squareFreePolynomial totalDegree unit? unitCanonical 
unitNormal univariate variables zero?}
%
\condata{NONE}{None}{SetCategory}{{\tt =} coerce}
%
\condata{NNI}{NonNegativeInteger}{Monoid OrderedAbelianMonoidSup}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt <} {\tt =}
coerce divide exquo gcd max min one? quo recip rem sup zero?}
%
\condata{OCT}{Octonion}{FullyRetractableTo OctonionCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt <} {\tt =} abs characteristic 
charthRoot coerce conjugate convert elt eval imagE imagI imagJ imagK imagi 
imagj imagk index inv lookup map max min norm octon one? random rational 
rational? rationalIfCan real recip retract retractIfCan size zero?}
%
\condata{ARRAY1}{OneDimensionalArray}{OneDimensionalArrayAggregate}
{{\tt \#} {\tt <} {\tt =} any? coerce concat construct convert copy 
copyInto! count delete elt empty empty? entries entry? eq? every? 
fill! find first index? indices insert less? map map! max maxIndex 
member? members merge min minIndex more? new oneDimensionalArray parts
   position qelt qsetelt! reduce remove removeDuplicates reverse 
reverse! select setelt size? sort sort! sorted? swap!}
%
\condata{ONECOMP}{OnePointCompletion}
{AbelianGroup FullyRetractableTo\\ OrderedRing SetCategory}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt <} {\tt =} abs\\ 
characteristic coerce finite? infinite? infinity max min\\ 
negative? one? positive? rational rational? rationalIfCan\\ 
recip retract retractIfCan sign zero?}
%
\condata{OP}{Operator}
{Algebra CharacteristicNonZero CharacteristicZero Eltable RetractableTo Ring}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt =} characteristic charthRoot 
coerce elt evaluate one? opeval recip retract retractIfCan zero?}
%
\condata{OMLO}{OppositeMonogenicLinearOperator}
{DifferentialRing MonogenicLinearOperator}{0 1 {\tt *} {\tt **} {\tt +}
{\tt -} {\tt =} D characteristic coefficient coerce degree differentiate 
leadingCoefficient minimumDegree monomial one? op po recip reductum zero?}
%
\condata{ORDCOMP}{OrderedCompletion}
{AbelianGroup FullyRetractableTo OrderedRing SetCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt <} {\tt =} abs characteristic 
coerce finite? infinite? max min minusInfinity negative? one? plusInfinity 
positive? rational rational? rationalIfCan recip retract retractIfCan sign 
whatInfinity zero?}
%
\condata{ODP}{OrderedDirectProduct}{DirectProductCategory}{0 1 {\tt \#} 
{\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs any? 
characteristic coerce copy count differentiate dimension directProduct 
dot elt empty empty? entries entry? eq? every? fill! first index index? 
indices less? lookup map map! max maxIndex member? members min minIndex 
more? negative? one? parts positive? qelt qsetelt! random recip 
reducedSystem retract retractIfCan setelt sign size size? sup swap! 
unitVector zero?}
%
\condata{OVAR}{OrderedVariableList}{ConvertibleTo OrderedFinite}{{\tt <} 
{\tt =} coerce convert index lookup max min random size variable}
%
\condata{ODPOL}{OrderlyDifferentialPolynomial}
{DifferentialPolynomialCategory RetractableTo}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
associates? characteristic charthRoot coefficient coefficients 
coerce conditionP content degree differentialVariables differentiate 
discriminant eval exquo factor factorPolynomial factorSquareFreePolynomial 
gcd gcdPolynomial ground ground? initial isExpt isPlus isTimes isobaric? 
lcm leader leadingCoefficient leadingMonomial mainVariable makeVariable 
map mapExponents max min minimumDegree monicDivide monomial monomial? 
monomials multivariate numberOfMonomials one? order prime? 
primitiveMonomials primitivePart recip reducedSystem reductum 
resultant retract retractIfCan separant solveLinearPolynomialEquation 
squareFree squareFreePart squareFreePolynomial totalDegree unit? 
unitCanonical unitNormal univariate variables weight weights zero?}
%
\condata{ODVAR}{OrderlyDifferentialVariable}{DifferentialVariableCategory}
{{\tt <} {\tt =} D coerce differentiate makeVariable max min order 
retract retractIfCan variable weight}
%
\condata{ODR}{OrdinaryDifferentialRing}{Algebra DifferentialRing Field}{
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D associates? 
characteristic coerce differentiate divide euclideanSize 
expressIdealMember exquo extendedEuclidean factor gcd inv lcm 
multiEuclidean one? prime? principalIdeal quo recip rem sizeLess? 
squareFree squareFreePart unit? unitCanonical unitNormal zero?}
%
\condata{OSI}{OrdSetInts}{OrderedSet}{{\tt <} {\tt =} coerce max min value}
%
\condata{OUTFORM}{OutputForm}{SetCategory}{{\tt *} {\tt **} {\tt +} 
{\tt -} {\tt /} {\tt <} {\tt <=} {\tt =} {\tt >} {\tt >=} D SEGMENT 
{\tt \^{}=} and assign blankSeparate box brace bracket center coerce 
commaSeparate differentiate div dot elt empty exquo hconcat height 
hspace infix infix? int label left matrix message messagePrint not 
or outputForm over overbar paren pile postfix prefix presub presuper 
prime print prod quo quote rarrow rem right root rspace scripts
semicolonSeparate slash string sub subHeight sum super superHeight 
supersub vconcat vspace width zag}
%
\condata{PADIC}{PAdicInteger}{PAdicIntegerCategory}{0 1 {\tt *} {\tt **} 
{\tt +} {\tt -} {\tt =} approximate associates? characteristic coerce 
complete digits divide euclideanSize expressIdealMember exquo extend
extendedEuclidean gcd lcm moduloP modulus multiEuclidean one? order 
principalIdeal quo quotientByP recip rem sizeLess? sqrt unit? 
unitCanonical unitNormal zero?}
%
\condata{PADICRC}{PAdicRationalConstructor}{QuotientFieldCategory}{0 1 
{\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs 
approximate associates? ceiling characteristic charthRoot coerce 
conditionP continuedFraction convert denom denominator differentiate 
divide elt euclideanSize eval expressIdealMember exquo extendedEuclidean 
factor factorPolynomial factorSquareFreePolynomial floor fractionPart 
gcd gcdPolynomial init inv lcm map max min multiEuclidean negative? 
nextItem numer numerator one? patternMatch positive? prime? 
principalIdeal quo random recip reducedSystem rem removeZeroes retract 
retractIfCan sign sizeLess? solveLinearPolynomialEquation squareFree
squareFreePart squareFreePolynomial unit? unitCanonical unitNormal 
wholePart zero?}
%
\condata{PADICRAT}{PAdicRational}{QuotientFieldCategory}{0 1 {\tt *} 
{\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D approximate associates? 
characteristic coerce continuedFraction denom denominator differentiate 
divide euclideanSize expressIdealMember exquo extendedEuclidean factor 
fractionPart gcd inv lcm map multiEuclidean numer numerator one? prime? 
principalIdeal quo recip reducedSystem rem removeZeroes retract 
retractIfCan sizeLess? squareFree squareFreePart unit? unitCanonical 
unitNormal wholePart zero?}
%
\condata{PALETTE}{Palette}{SetCategory}{{\tt =} bright coerce dark dim 
hue light pastel shade}
%
\condata{PARPCURV}{ParametricPlaneCurve}{}{coordinate curve}
%
\condata{PARSCURV}{ParametricSpaceCurve}{}{coordinate curve}
%
\condata{PARSURF}{ParametricSurface}{}{coordinate surface}
%
\condata{PFR}{PartialFraction}{Algebra Field}{0 1 {\tt *} {\tt **} 
{\tt +} {\tt -} {\tt /} {\tt =} associates? characteristic coerce 
compactFraction divide euclideanSize expressIdealMember exquo 
extendedEuclidean factor firstDenom firstNumer gcd inv lcm 
multiEuclidean nthFractionalTerm numberOfFractionalTerms one? 
padicFraction padicallyExpand partialFraction prime? principalIdeal 
quo recip rem sizeLess? squareFree squareFreePart unit? unitCanonical 
unitNormal wholePart zero?}
%
\condata{PRTITION}{Partition}{ConvertibleTo OrderedCancellationAbelianMonoid}
{0 {\tt *} {\tt +} {\tt -} {\tt <} {\tt =} coerce conjugate convert max 
min partition pdct powers zero?}
%
\condata{PATLRES}{PatternMatchListResult}{SetCategory}{{\tt =} atoms 
coerce failed failed? lists makeResult new}
%
\condata{PATRES}{PatternMatchResult}{SetCategory}{{\tt =} addMatch 
addMatchRestricted coerce construct destruct failed failed? getMatch 
insertMatch new satisfy? union}
%
\condata{PATTERN}{Pattern}{RetractableTo SetCategory}{0 1 {\tt *} {\tt **} 
{\tt +} {\tt /} {\tt =} addBadValue coerce constant? convert copy depth 
elt generic? getBadValues hasPredicate? hasTopPredicate? inR? isExpt 
isList isOp isPlus isPower isQuotient isTimes multiple? optional? 
optpair patternVariable predicates quoted? resetBadValues retract
retractIfCan setPredicates setTopPredicate symbol? topPredicate 
variables withPredicates}
%
\condata{PENDTREE}{PendantTree}{BinaryRecursiveAggregate}{{\tt \#} {\tt =} 
any? children coerce copy count cyclic? elt empty empty? eq? every? leaf? 
leaves left less? map map! member? members more? node? nodes parts ptree 
right setchildren! setelt setleft! setright! setvalue! size? value}
%
\condata{PERMGRP}{PermutationGroup}{SetCategory}{{\tt <} {\tt <=} {\tt =} 
base coerce degree elt generators initializeGroupForWordProblem member? 
movedPoints orbit orbits order permutationGroup random strongGenerators
wordInGenerators wordInStrongGenerators wordsForStrongGenerators}
%
\condata{PERM}{Permutation}{PermutationCategory}{1 {\tt *} {\tt **} 
{\tt /} {\tt <} {\tt =} coerce coerceImages coerceListOfPairs 
coercePreimagesImages commutator conjugate cycle cyclePartition 
cycles degree elt eval even? fixedPoints inv listRepresentation 
max min movedPoints numberOfCycles odd? one? orbit order recip sign sort}
%
\condata{HACKPI}{Pi}{CharacteristicZero CoercibleTo ConvertibleTo\\ 
Field RealConstant RetractableTo}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} associates?\\ 
characteristic coerce convert divide euclideanSize expressIdealMember\\
exquo extendedEuclidean factor gcd inv lcm multiEuclidean one? pi\\ 
prime? principalIdeal quo recip rem retract retractIfCan sizeLess?\\ 
squareFree squareFreePart unit? unitCanonical unitNormal zero?}
%
\condata{ACPLOT}{PlaneAlgebraicCurvePlot}{PlottablePlaneCurveCategory}{\\
coerce listBranches makeSketch refine xRange yRange}
%
\condata{PLOT3D}{Plot3D}{PlottableSpaceCurveCategory}{
adaptive3D? coerce debug3D listBranches maxPoints3D minPoints3D\\ 
numFunEvals3D plot pointPlot refine screenResolution3D setAdaptive3D\\ 
setMaxPoints3D setMinPoints3D setScreenResolution3D tRange tValues\\ 
xRange yRange zRange zoom}
%
\condata{PLOT}{Plot}{PlottablePlaneCurveCategory}{adaptive? coerce debug 
listBranches maxPoints minPoints numFunEvals parametric? plot plotPolar 
pointPlot refine screenResolution setAdaptive setMaxPoints setMinPoints 
setScreenResolution tRange xRange yRange zoom}
%
\condata{POINT}{Point}{PointCategory}{{\tt \#} {\tt *} {\tt +} {\tt -} 
{\tt <} {\tt =} any? coerce concat construct convert copy copyInto! 
count cross delete dimension dot elt empty empty? entries entry? eq? 
every? extend fill! find first index? indices insert length less? 
map map! max maxIndex member? members merge min minIndex more? new 
parts point position qelt qsetelt! reduce remove removeDuplicates 
reverse reverse! select setelt size? sort sort! sorted? swap! zero}
%
\condata{IDEAL}{PolynomialIdeals}{SetCategory}{{\tt *} {\tt **} {\tt +} 
{\tt =} backOldPos coerce contract dimension element? generalPosition 
generators groebner groebner? groebnerIdeal ideal in? inRadical? 
intersect leadingIdeal quotient relationsIdeal saturate zeroDim?}
%
\condata{PR}{PolynomialRing}{FiniteAbelianMonoidRing}{0 1 {\tt *} 
{\tt **} {\tt +} {\tt -} {\tt /} {\tt =} associates? characteristic 
charthRoot coefficient coefficients coerce content degree exquo ground 
ground? leadingCoefficient leadingMonomial map mapExponents 
minimumDegree monomial monomial? numberOfMonomials one? 
primitivePart recip reductum retract retractIfCan unit? unitCanonical 
unitNormal zero?}
%
\condata{POLY}{Polynomial}{PolynomialCategory}{0 1 {\tt *} {\tt **} 
{\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D associates? characteristic 
charthRoot coefficient coefficients coerce conditionP content convert 
degree differentiate discriminant eval exquo factor factorPolynomial 
factorSquareFreePolynomial gcd gcdPolynomial ground ground? integrate
isExpt isPlus isTimes lcm leadingCoefficient leadingMonomial 
mainVariable map mapExponents max min minimumDegree  monicDivide 
monomial monomial? monomials multivariate numberOfMonomials one? 
patternMatch prime? primitiveMonomials primitivePart recip 
reducedSystem reductum resultant retract retractIfCan 
solveLinearPolynomialEquation squareFree squareFreePart 
squareFreePolynomial totalDegree unit? unitCanonical unitNormal 
univariate variables zero?}
%
\condata{PI}{PositiveInteger}{AbelianSemiGroup Monoid OrderedSet}{1 
{\tt *} {\tt **} {\tt +} {\tt <} {\tt =} coerce gcd max min one? recip}
%
\condata{PF}{PrimeField}
{ConvertibleTo FiniteAlgebraicExtensionField FiniteFieldCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} Frobenius 
algebraic? associates? basis characteristic charthRoot coerce 
conditionP convert coordinates createNormalElement 
createPrimitiveElement definingPolynomial degree dimension 
discreteLog divide euclideanSize expressIdealMember exquo 
extendedEuclidean extensionDegree factor factorsOfCyclicGroupSize 
gcd generator inGroundField? index init inv lcm lookup 
minimalPolynomial multiEuclidean nextItem norm normal? normalElement 
one? order prime? primeFrobenius primitive? primitiveElement 
principalIdeal quo random recip rem representationType represents 
retract retractIfCan size sizeLess? squareFree squareFreePart 
tableForDiscreteLogarithm trace transcendenceDegree transcendent? 
unit? unitCanonical unitNormal zero?}
%
\condata{PRIMARR}{PrimitiveArray}{OneDimensionalArrayAggregate}{{\tt \#} 
{\tt <} {\tt =} any? coerce concat construct convert copy copyInto! count 
delete elt empty empty? entries entry? eq? every? fill! find first index? 
indices insert less? map map! max maxIndex member? members merge min 
minIndex more? new parts position qelt qsetelt! reduce remove 
removeDuplicates reverse reverse! select setelt size? sort sort! 
sorted? swap!}
%
\condata{PRODUCT}{Product}{AbelianGroup AbelianMonoid\\ 
CancellationAbelianMonoid Finite Group Monoid OrderedAbelianMonoidSup\\ 
OrderedSet SetCategory}{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /}\\ 
{\tt <} {\tt =} coerce commutator conjugate index inv lookup makeprod\\ 
max min one? random recip selectfirst selectsecond size sup zero?}
%
\condata{QFORM}{QuadraticForm}{AbelianGroup}{0 {\tt *} {\tt +} {\tt -} 
{\tt =} coerce elt matrix quadraticForm zero?}
%
\condata{QALGSET}{QuasiAlgebraicSet}{CoercibleTo SetCategory}{{\tt =} 
coerce definingEquations definingInequation empty? idealSimplify 
quasiAlgebraicSet setStatus simplify}
%
\condata{QUAT}{Quaternion}{QuaternionCategory}{0 1 {\tt *} {\tt **} {\tt +} 
{\tt -} {\tt <} {\tt =} D abs characteristic charthRoot coerce conjugate 
convert differentiate elt eval imagI imagJ imagK inv map max min norm one?
quatern rational rational? rationalIfCan real recip reducedSystem retract 
retractIfCan zero?}
%
\condata{QEQUAT}{QueryEquation}{}{equation value variable}
%
\condata{QUEUE}{Queue}{QueueAggregate}{{\tt \#} {\tt =} any? back bag coerce 
copy count dequeue! empty empty? enqueue! eq? every? extract! front insert! 
inspect length less? map map! member? members more? parts queue rotate! size?}
%
\condata{RADFF}{RadicalFunctionField}{FunctionFieldCategory}{0 1 {\tt *} 
{\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D absolutelyIrreducible? 
associates? basis branchPoint? branchPointAtInfinity? characteristic 
characteristicPolynomial   charthRoot coerce complementaryBasis 
convert coordinates definingPolynomial derivationCoordinates 
differentiate discriminant divide elt euclideanSize expressIdealMember 
exquo extendedEuclidean factor gcd generator genus integral? 
integralAtInfinity? integralBasis integralBasisAtInfinity 
integralCoordinates integralDerivationMatrix integralMatrix
integralMatrixAtInfinity integralRepresents inv inverseIntegralMatrix 
inverseIntegralMatrixAtInfinity lcm lift minimalPolynomial multiEuclidean 
nonSingularModel norm normalizeAtInfinity numberOfComponents one? prime? 
primitivePart principalIdeal quo ramified? ramifiedAtInfinity? rank 
rationalPoint? rationalPoints recip reduce reduceBasisAtInfinity
reducedSystem regularRepresentation rem represents retract retractIfCan 
singular? singularAtInfinity? sizeLess? squareFree squareFreePart trace 
traceMatrix unit? unitCanonical unitNormal yCoordinates zero?}
%
\condata{RADIX}{RadixExpansion}{QuotientFieldCategory}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D\\
abs associates? ceiling characteristic coerce convert cycleRagits\\ 
denom denominator differentiate divide euclideanSize\\
expressIdealMember exquo extendedEuclidean factor floor fractRadix\\ 
fractRagits fractionPart gcd init inv lcm map max min multiEuclidean\\ 
negative? nextItem numer numerator one? patternMatch positive?\\ 
prefixRagits prime? principalIdeal quo random recip reducedSystem\\ 
rem retract retractIfCan sign sizeLess? squareFree squareFreePart\\ 
unit? unitCanonical unitNormal wholePart wholeRadix wholeRagits zero?}
%
\condata{RMATRIX}{RectangularMatrix}{CoercibleTo\\
RectangularMatrixCategory VectorSpace}{\\
0 {\tt \#} {\tt *} {\tt +} {\tt -} {\tt /} {\tt =} antisymmetric?\\ 
any? coerce column copy count diagonal? dimension elt empty empty?\\ 
eq? every? exquo less? listOfLists map map! matrix maxColIndex\\ 
maxRowIndex member? members minColIndex minRowIndex more? ncols\\ 
nrows nullSpace nullity parts qelt rank rectangularMatrix row\\ 
rowEchelon size? square? symmetric? zero?}
%
\condata{REF}{Reference}{Object SetCategory}{{\tt =} coerce deref elt 
ref setelt setref}
%
\condata{RULE}{RewriteRule}{Eltable RetractableTo SetCategory}{{\tt =} 
coerce elt lhs pattern quotedOperators retract retractIfCan rhs rule suchThat}
%
\condata{ROMAN}{RomanNumeral}{IntegerNumberSystem}{0 1 {\tt *} {\tt **} 
{\tt +} {\tt -} {\tt <} {\tt =} D abs addmod associates? base binomial 
bit? characteristic coerce convert copy dec differentiate divide 
euclideanSize even? expressIdealMember exquo extendedEuclidean factor 
factorial gcd hash inc init invmod lcm length mask max min mulmod
multiEuclidean negative? nextItem odd? one? patternMatch permutation 
positive? positiveRemainder powmod prime? principalIdeal quo random 
rational rational? rationalIfCan recip reducedSystem rem retract 
retractIfCan roman shift sign sizeLess? squareFree squareFreePart 
submod symmetricRemainder unit? unitCanonical unitNormal zero?}
%
\condata{RULECOLD}{RuleCalled}{SetCategory}{{\tt =} coerce name}
%
\condata{RULESET}{Ruleset}{Eltable SetCategory}{{\tt =} coerce elt rules 
ruleset}
%
\condata{FORMULA1}{ScriptFormulaFormat1}{Object}{coerce}
%
\condata{FORMULA}{ScriptFormulaFormat}{SetCategory}{{\tt =} coerce convert 
display epilogue formula new prologue
   setEpilogue! setFormula! setPrologue!}
%
\condata{SEGBIND}{SegmentBinding}{SetCategory}{{\tt =} coerce equation 
segment variable}
%
\condata{SEG}{Segment}{SegmentCategory SegmentExpansionCategory}{{\tt =} 
BY SEGMENT coerce convert expand hi high incr lo low map segment}
%
\condata{SCFRAC}{SemiCancelledFraction}{ConvertibleTo QuotientFieldCategory}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D\\ 
abs associates? ceiling characteristic charthRoot coerce conditionP\\ 
convert denom denominator differentiate divide elt euclideanSize\\ 
eval expressIdealMember exquo extendedEuclidean factor\\ 
factorPolynomial factorSquareFreePolynomial floor fractionPart\\ 
gcd gcdPolynomial init inv lcm map max min multiEuclidean negative?\\
nextItem normalize numer numerator one? patternMatch positive?\\ 
prime? principalIdeal quo random recip reducedSystem rem retract\\ 
retractIfCan sign sizeLess? solveLinearPolynomialEquation squareFree\\ 
squareFreePart squareFreePolynomial unit? unitCanonical unitNormal\\ 
wholePart zero?}
%
\condata{SDPOL}{SequentialDifferentialPolynomial}
{DifferentialPolynomialCategory\\ RetractableTo}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =}D\\ 
associates? characteristic charthRoot coefficient coefficients\\ 
coerce conditionP content degree differentialVariables\\ 
differentiate discriminant eval exquo factor factorPolynomial\\
factorSquareFreePolynomial gcd gcdPolynomial ground ground?\\ 
initial isExpt isPlus isTimes isobaric? lcm leader\\ 
leadingCoefficient leadingMonomial mainVariable makeVariable\\ 
map mapExponents max min minimumDegree monicDivide monomial\\ 
monomial? monomials multivariate numberOfMonomials one? order\\ 
prime? primitiveMonomials primitivePart recip reducedSystem\\ 
reductum resultant retract retractIfCan separant\\ 
solveLinearPolynomialEquation squareFree squareFreePart\\
squareFreePolynomial totalDegree unit? unitCanonical unitNormal\\ 
univariate variables weight weights zero?}
%
\condata{SDVAR}
{SequentialDifferentialVariable}{DifferentialVariableCategory}{\\
{\tt <} {\tt =} D coerce differentiate makeVariable max min order\\ 
retract retractIfCan variable weight}
%
\condata{SET}{Set}{FiniteSetAggregate}{{\tt \#} {\tt <} {\tt =} any? bag 
brace cardinality coerce complement construct convert copy count 
dictionary difference empty empty? eq? every? extract! find index 
insert! inspect intersect less? lookup map map! max member? members 
min more? parts random reduce remove remove! removeDuplicates select 
select! size size? subset? symmetricDifference union universe}
%
\condata{SEXOF}{SExpressionOf}{SExpressionCategory}{{\tt \#} {\tt =} 
atom? car cdr coerce convert destruct elt eq expr float float? integer 
integer? list? null? pair? string string? symbol symbol? uequal}
%
\condata{SEX}{SExpression}{SExpressionCategory}{{\tt \#} {\tt =} atom? car 
cdr coerce convert destruct elt eq expr float float? integer integer? 
list? null? pair? string string? symbol symbol? uequal}
%
\condata{SAE}{SimpleAlgebraicExtension}{MonogenicAlgebra}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D\\
associates? basis characteristic characteristicPolynomial\\ 
charthRoot coerce conditionP convert coordinates\\
createPrimitiveElement definingPolynomial derivationCoordinates\\ 
differentiate discreteLog discriminant divide euclideanSize\\ 
expressIdealMember exquo extendedEuclidean factor\\ 
factorsOfCyclicGroupSize gcd generator index init inv lcm\\ 
lift lookup minimalPolynomial multiEuclidean nextItem norm one?\\ 
order prime? primeFrobenius primitive? primitiveElement\\ 
principalIdeal quo random rank recip reduce reducedSystem\\ 
regularRepresentation rem representationType represents retract\\ 
retractIfCan size sizeLess? squareFree squareFreePart\\ 
tableForDiscreteLogarithm trace traceMatrix unit? unitCanonical\\ 
unitNormal zero?}
%
\condata{SAOS}{SingletonAsOrderedSet}{OrderedSet}{{\tt <} {\tt =} coerce create max min}
%
\condata{SINT}{SingleInteger}{IntegerNumberSystem}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt <} {\tt =}\\ 
And D Not Or {\tt \^{}} abs addmod and associates? base\\ 
binomial bit? characteristic coerce convert copy dec\\ 
differentiate divide euclideanSize even? expressIdealMember\\ 
exquo extendedEuclidean factor factorial gcd hash inc init\\ 
invmod lcm length mask max min mulmod multiEuclidean\\ 
negative? nextItem not odd? one? or patternMatch permutation\\ 
positive? positiveRemainder powmod prime? principalIdeal\\ 
quo random rational rational? rationalIfCan recip\\ 
reducedSystem rem retract retractIfCan shift sign sizeLess?\\ 
squareFree squareFreePart submod symmetricRemainder unit?\\ 
unitCanonical unitNormal xor zero?}
%
\condata{SMP}{SparseMultivariatePolynomial}{PolynomialCategory}{\\
0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <}\\
{\tt =} D associates? characteristic charthRoot coefficient\\ 
coefficients coerce conditionP content convert degree\\
differentiate discriminant eval exquo factor factorPolynomial\\ 
factorSquareFreePolynomial gcd gcdPolynomial ground ground?\\ 
isExpt isPlus isTimes lcm leadingCoefficient leadingMonomial\\ 
mainVariable map mapExponents max min minimumDegree monicDivide\\ 
monomial monomial? monomials multivariate numberOfMonomials one?\\ 
patternMatch prime? primitiveMonomials primitivePart recip\\ 
reducedSystem reductum resultant retract retractIfCan\\
solveLinearPolynomialEquation squareFree squareFreePart\\ 
squareFreePolynomial totalDegree unit? unitCanonical unitNormal\\
univariate variables zero?}
%
\condata{SMTS}{SparseMultivariateTaylorSeries}{\\
MultivariateTaylorSeriesCategory}{0 1 {\tt *} {\tt **}\\ 
{\tt +} {\tt -} {\tt /} {\tt =} D acos acosh acot acoth\\ 
acsc acsch asec asech asin asinh associates? atan atanh\\ 
characteristic charthRoot coefficient coerce complete cos\\ 
cosh cot coth csc csch csubst degree differentiate eval\\ 
exp exquo extend fintegrate integrate leadingCoefficient\\ 
leadingMonomial log map monomial monomial? nthRoot one?\\ 
order pi pole? polynomial recip reductum sec sech sin sinh\\ 
sqrt tan tanh unit? unitCanonical unitNormal variables zero?}
%
\condata{STBL}{SparseTable}{TableAggregate}{{\tt \#} {\tt =}\\ 
any? bag coerce construct copy count dictionary elt empty\\
empty? entries entry? eq? every? extract! fill! find first\\ 
index? indices insert! inspect key? keys less? map map!\\
maxIndex member? members minIndex more? parts qelt qsetelt!\\ 
reduce remove remove! removeDuplicates search select select!\\ 
setelt size? swap! table}
%
\condata{SUP}{SparseUnivariatePolynomial}{UnivariatePolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D associates? 
characteristic charthRoot coefficient coefficients coerce composite 
conditionP content degree differentiate discriminant divide 
divideExponents elt euclideanSize eval expressIdealMember exquo
extendedEuclidean factor factorPolynomial factorSquareFreePolynomial 
gcd gcdPolynomial ground ground? init integrate isExpt isPlus isTimes 
lcm leadingCoefficient leadingMonomial mainVariable makeSUP map 
mapExponents max min minimumDegree monicDivide monomial monomial? 
monomials multiEuclidean multiplyExponents multivariate nextItem
numberOfMonomials one? order outputForm prime? primitiveMonomials 
primitivePart principalIdeal pseudoDivide pseudoQuotient pseudoRemainder 
quo recip reducedSystem reductum rem resultant retract retractIfCan 
separate sizeLess? solveLinearPolynomialEquation squareFree 
squareFreePart squareFreePolynomial subResultantGcd totalDegree unit?
unitCanonical unitNormal univariate unmakeSUP variables vectorise zero?}
%
\condata{SUTS}{SparseUnivariateTaylorSeries}{UnivariateTaylorSeriesCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D acos acosh acot 
acoth acsc acsch approximate asec asech asin asinh associates? atan 
atanh center characteristic charthRoot coefficient coefficients coerce 
complete cos cosh cot coth csc csch degree differentiate elt eval exp 
exquo extend integrate leadingCoefficient leadingMonomial log map 
monomial monomial? multiplyCoefficients multiplyExponents nthRoot one? 
order pi pole? polynomial quoByVar recip reductum sec sech series sin 
sinh sqrt tan tanh terms truncate unit? unitCanonical unitNormal 
variable variables zero?}
%
\condata{SQMATRIX}{SquareMatrix}{CoercibleTo SquareMatrixCategory}
{0 1 {\tt \#} {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D 
antisymmetric? any? characteristic coerce column copy count determinant 
diagonal diagonal? diagonalMatrix diagonalProduct differentiate elt empty 
empty? eq? every? exquo inverse less? listOfLists map map! matrix maxColIndex
maxRowIndex member? members minColIndex minRowIndex minordet more? ncols 
nrows nullSpace nullity one? parts qelt rank recip reducedSystem retract 
retractIfCan row rowEchelon scalarMatrix size? square? squareMatrix 
symmetric? trace transpose zero?}
%
\condata{STACK}{Stack}{StackAggregate}{{\tt \#} {\tt =} any? bag coerce 
copy count depth empty empty? eq? every? extract! insert! inspect less? 
map map! member? members more? parts pop! push! size? stack top}
%
\condata{STREAM}{Stream}{LazyStreamAggregate}{{\tt \#} {\tt =} any? child? 
children coerce complete concat concat! cons construct convert copy 
count cycleEntry cycleLength cycleSplit! cycleTail cyclic? delay delete 
distance elt empty empty? entries entry? eq? every? explicitEntries? 
explicitlyEmpty? explicitlyFinite? extend fill! filterUntil filterWhile 
find findCycle first frst generate index? indices insert last lazy? 
lazyEvaluate leaf? less? map map! maxIndex member? members minIndex 
more? new node? nodes numberOfComputedEntries output parts 
possiblyInfinite? qelt qsetelt! reduce remove removeDuplicates 
repeating repeating? rest rst second select setchildren! setelt setfirst!
setlast! setrest! setvalue! showAll? showAllElements size? split! swap! 
tail third value}
%
\condata{STRTBL}{StringTable}{TableAggregate}{{\tt \#} {\tt =} any? bag 
coerce construct copy count dictionary elt empty empty? entries entry? 
eq? every? extract! fill! find first index? indices insert! inspect key? 
keys less? map map! maxIndex member? members minIndex more? parts 
qelt qsetelt! reduce remove remove! removeDuplicates search select
select! setelt size? swap! table}
%
\condata{STRING}{String}{StringCategory}{{\tt \#} {\tt <} {\tt =} any? 
coerce concat construct copy copyInto! count delete elt empty empty? 
entries entry? eq? every? fill! find first index? indices insert 
leftTrim less? lowerCase lowerCase! map map! match? max maxIndex 
member? members merge min minIndex more? new parts position prefix? qelt
qsetelt! reduce remove removeDuplicates replace reverse reverse! 
rightTrim select setelt size? sort sort! sorted? split
string substring? suffix? swap! trim upperCase upperCase!}
%
\condata{COMPPROP}{SubSpaceComponentProperty}{SetCategory}{{\tt =} 
close closed? coerce copy new solid solid?}
%
\condata{SUBSPACE}{SubSpace}{SetCategory}{{\tt =} addPoint addPoint2 
addPointLast birth child children closeComponent coerce deepCopy 
defineProperty extractClosed extractIndex extractPoint extractProperty 
internal? leaf? level merge modifyPoint new numberOfChildren parent 
pointData root? separate shallowCopy subspace traverse}
%
\condata{SUCH}{SuchThat}{SetCategory}{{\tt =} coerce construct lhs rhs}
%
\condata{SYMBOL}{Symbol}{ConvertibleTo OrderedSet PatternMatchable}
{{\tt <} {\tt =} argscript coerce convert elt list max min name new 
patternMatch resetNew script scripted? scripts string subscript superscript}
%
\condata{SYMPOLY}{SymmetricPolynomial}{FiniteAbelianMonoidRing}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =}
associates? characteristic charthRoot coefficient coefficients coerce 
content degree exquo ground ground? leadingCoefficient leadingMonomial 
map mapExponents minimumDegree monomial monomial? numberOfMonomials one?
primitivePart recip reductum retract retractIfCan unit? unitCanonical 
unitNormal zero?}
%
\condata{TABLEAU}{Tableau}{Object}{coerce listOfLists tableau}
%
\condata{TABLE}{Table}{TableAggregate}{{\tt \#} {\tt =} any? bag coerce 
construct copy count dictionary elt empty empty? entries entry? eq? 
every? extract! fill! find first index? indices insert! inspect key? 
keys less? map map! maxIndex member? members minIndex more? parts 
qelt qsetelt! reduce remove remove! removeDuplicates search select
select! setelt size? swap! table}
%
\condata{TS}{TaylorSeries}{MultivariateTaylorSeriesCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D acos acosh 
acot acoth acsc acsch asec asech asin asinh associates? atan atanh 
characteristic charthRoot coefficient coerce complete cos cosh cot 
coth csc csch degree differentiate eval exp exquo extend fintegrate 
integrate leadingCoefficient leadingMonomial log map monomial 
monomial? nthRoot one? order pi pole? polynomial recip reductum sec
sech sin sinh sqrt tan tanh unit? unitCanonical unitNormal variables zero?}
%
\condata{TEX1}{TexFormat1}{Object}{coerce}
%
\condata{TEX}{TexFormat}{SetCategory}\\
{{\tt =} coerce convert display epilogue new prologue\\ 
setEpilogue! setPrologue! setTex! tex}
%
\condata{TEXTFILE}{TextFile}{FileCategory}{{\tt =} close! coerce 
endOfFile? iomode name open read! readIfCan! readLine!
readLineIfCan! reopen! write! writeLine!}
%
\condata{VIEW3D}{ThreeDimensionalViewport}{SetCategory}\\
{{\tt =} axes clipSurface close coerce colorDef controlPanel\\ 
diagonals dimensions drawStyle eyeDistance hitherPlane\\ 
intensity key lighting makeViewport3D modifyPointData move\\ 
options outlineRender perspective reset resize rotate\\ 
showClipRegion showRegion subspace title translate\\ 
viewDeltaXDefault viewDeltaYDefault viewPhiDefault\\ 
viewThetaDefault viewZoomDefault viewpoint viewport3D write zoom}
%
\condata{SPACE3}{ThreeSpace}{ThreeSpaceCategory}{{\tt =} check 
closedCurve closedCurve? coerce components composite composites copy 
create3Space curve curve? enterPointData lllip lllp llprop lp lprop 
merge mesh mesh? modifyPointData numberOfComponents numberOfComposites 
objects point point? polygon polygon? subspace}
%
\condata{TREE}{Tree}{RecursiveAggregate}
{{\tt \#} {\tt =} any? children coerce copy count cyclic? elt empty 
empty? eq? every? leaf? leaves less? map map! member? members more? 
node? nodes parts setchildren! setelt setvalue! size? tree value}
%
\condata{TUBE}{TubePlot}{}{closed? getCurve listLoops open? setClosed tube}
%
\condata{TUPLE}{Tuple}{CoercibleTo SetCategory}{{\tt =} coerce length select}
%
\condata{ARRAY2}{TwoDimensionalArray}{TwoDimensionalArrayCategory}
{{\tt \#} {\tt =} any? coerce column copy count elt empty empty? eq? 
every? fill! less? map map! maxColIndex maxRowIndex member? members 
minColIndex minRowIndex more? ncols new nrows parts qelt qsetelt! 
row setColumn! setRow! setelt size?}
%
\condata{VIEW2D}{TwoDimensionalViewport}{SetCategory}
{{\tt =} axes close coerce connect controlPanel dimensions
getGraph graphState graphStates graphs key makeViewport2D move options 
points putGraph region reset resize scale show
title translate units viewport2D write}
%
\condata{ULSCONS}{UnivariateLaurentSeriesConstructor}
{UnivariateLaurentSeriesConstructorCategory}{0 1 {\tt *} {\tt **}
{\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D abs acos acosh acot acoth acsc 
acsch approximate asec asech asin asinh associates? atan atanh ceiling 
center characteristic charthRoot coefficient coerce complete conditionP 
convert cos cosh cot coth csc csch degree denom denominator differentiate 
divide elt euclideanSize eval exp expressIdealMember exquo extend 
extendedEuclidean factor factorPolynomial factorSquareFreePolynomial 
floor fractionPart gcd gcdPolynomial init integrate inv laurent lcm 
leadingCoefficient leadingMonomial log map max min monomial monomial? 
multiEuclidean multiplyCoefficients multiplyExponents negative? nextItem 
nthRoot numer numerator one? order patternMatch pi pole? positive? 
prime? principalIdeal quo random rationalFunction recip reducedSystem 
reductum rem removeZeroes retract retractIfCan sec sech series sign 
sin sinh sizeLess? solveLinearPolynomialEquation sqrt squareFree 
squareFreePart squareFreePolynomial tan tanh taylor taylorIfCan 
taylorRep terms truncate unit? unitCanonical unitNormal variable
variables wholePart zero?}
%
\condata{ULS}{UnivariateLaurentSeries}
{UnivariateLaurentSeriesConstructorCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D acos acosh acot 
acoth acsc acsch approximate asec asech asin asinh associates? atan 
atanh center characteristic charthRoot coefficient coerce complete cos 
cosh cot coth csc csch degree denom denominator differentiate
divide elt euclideanSize eval exp expressIdealMember exquo extend 
extendedEuclidean factor gcd integrate inv laurent lcm leadingCoefficient 
leadingMonomial log map monomial monomial? multiEuclidean 
multiplyCoefficients multiplyExponents nthRoot numer numerator one? order 
pi pole? prime? principalIdeal quo rationalFunction recip reducedSystem 
reductum rem removeZeroes retract retractIfCan sec sech series sin sinh 
sizeLess? sqrt squareFree squareFreePart tan tanh taylor taylorIfCan 
taylorRep terms truncate unit? unitCanonical unitNormal variable 
variables zero?}
%
\condata{UP}{UnivariatePolynomial}{UnivariatePolynomialCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt <} {\tt =} D 
associates? characteristic charthRoot coefficient coefficients coerce 
composite conditionP content degree differentiate discriminant divide 
divideExponents elt euclideanSize eval expressIdealMember exquo 
extendedEuclidean factor factorPolynomial factorSquareFreePolynomial gcd 
gcdPolynomial ground ground? init integrate isExpt isPlus isTimes lcm 
leadingCoefficient leadingMonomial mainVariable makeSUP map mapExponents 
max min minimumDegree monicDivide monomial monomial? monomials 
multiEuclidean multiplyExponents multivariate nextItem numberOfMonomials 
one? order prime? primitiveMonomials primitivePart principalIdeal 
pseudoDivide pseudoQuotient pseudoRemainder quo recip reducedSystem
reductum rem resultant retract retractIfCan separate sizeLess? 
solveLinearPolynomialEquation squareFree squareFreePart 
squareFreePolynomial subResultantGcd totalDegree unit? unitCanonical 
unitNormal univariate unmakeSUP variables vectorise zero?}
%
\condata{UPXSCONS}{UnivariatePuiseuxSeriesConstructor}\\
{UnivariatePuiseuxSeriesConstructorCategory}{0 1 {\tt *} {\tt **}
{\tt +} {\tt -} {\tt /} {\tt =} D acos acosh acot acoth acsc acsch 
approximate asec asech asin asinh associates? atan atanh center 
characteristic charthRoot coefficient coerce complete cos cosh cot coth 
csc csch degree differentiate divide elt euclideanSize eval exp 
expressIdealMember exquo extend extendedEuclidean factor gcd integrate 
inv laurent laurentIfCan laurentRep lcm leadingCoefficient 
leadingMonomial log map monomial monomial? multiEuclidean
multiplyExponents nthRoot one? order pi pole? prime? principalIdeal 
puiseux quo rationalPower recip reductum rem retract retractIfCan sec 
sech series sin sinh sizeLess? sqrt squareFree squareFreePart tan tanh 
terms truncate unit? unitCanonical unitNormal variable variables zero?}
%
\condata{UPXS}{UnivariatePuiseuxSeries}\\
{UnivariatePuiseuxSeriesConstructorCategory} {0 1 {\tt *} {\tt **} {\tt +} 
{\tt -} {\tt /} {\tt =} D acos acosh acot acoth acsc acsch approximate 
asec asech asin asinh associates? atan atanh center characteristic 
charthRoot coefficient coerce complete cos cosh cot coth csc csch 
degree differentiate divide elt euclideanSize eval exp expressIdealMember 
exquo extend extendedEuclidean factor gcd integrate inv laurent laurentIfCan
laurentRep lcm leadingCoefficient leadingMonomial log map monomial 
monomial? multiEuclidean multiplyExponents nthRoot one? order pi pole? 
prime? principalIdeal puiseux quo rationalPower recip reductum rem 
retract retractIfCan sec sech series sin sinh sizeLess? sqrt squareFree 
squareFreePart tan tanh terms truncate unit? unitCanonical unitNormal
variable variables zero?}
%
\condata{UTS}{UnivariateTaylorSeries}{UnivariateTaylorSeriesCategory}
{0 1 {\tt *} {\tt **} {\tt +} {\tt -} {\tt /} {\tt =} D acos acosh acot 
acoth acsc acsch approximate asec asech asin asinh associates? atan atanh 
center characteristic charthRoot coefficient coefficients coerce 
complete cos cosh cot coth csc csch degree differentiate elt eval
evenlambert exp exquo extend generalLambert integrate invmultisect 
lagrange lambert leadingCoefficient leadingMonomial log map monomial 
monomial? multiplyCoefficients multiplyExponents multisect nthRoot 
oddlambert one? order pi pole? polynomial quoByVar recip reductum 
revert sec sech series sin sinh sqrt tan tanh terms truncate unit? 
unitCanonical unitNormal univariatePolynomial variable variables zero?}
%
\condata{UNISEG}{UniversalSegment}{SegmentCategory SegmentExpansionCategory}
{{\tt =} BY SEGMENT coerce convert expand hasHi hi high incr lo low 
map segment}
%
\condata{VARIABLE}{Variable}{CoercibleTo SetCategory}{{\tt =} coerce variable}
%
\condata{VECTOR}{Vector}{VectorCategory}{{\tt \#} {\tt *} {\tt +} {\tt -} 
{\tt <} {\tt =} any? coerce concat construct convert copy copyInto! count 
delete dot elt empty empty? entries entry? eq? every? fill! find first 
index? indices insert less? map map! max maxIndex member? members merge 
min minIndex more? new parts position qelt qsetelt! reduce remove 
removeDuplicates reverse reverse! select setelt size? sort sort! 
sorted? swap! vector zero}
%
\condata{VOID}{Void}{}{coerce void}
%
%
% ----------------------------------------------------------------------
%\end{constructorListing}
% ----------------------------------------------------------------------



%\setcounter{chapter}{3} % Appendix D

%Original Page 619

%\twocolumn[%
\chapter{Packages}
\label{ugAppPackages}

This is a listing of all packages in the Axiom library at the
time this book was produced.
Use the Browse facility (described in \sectionref{ugBrowse})
to get more information about these constructors.

\boxer{5.0in}{
This sample entry will help you read the following table:

PackageName{PackageAbbreviation}:{$\hbox{{\sf Category}}_{1}$%
\ldots$\hbox{{\sf Category}}_{N}$}{\sl with }%
{$\hbox{{\rm op}}_{1}$\ldots$\hbox{{\rm op}}_{M}$}

where

\begin{tabular}{@{\quad}ll}
PackageName & is the full package name, e.g., {\sf PadeApproximantPackage}. \\
PackageAbbreviation & is the package abbreviation, e.g., {\sf PADEPAC}.\\
$\hbox{{\sf Category}}_{i}$ & is a category to which the package belongs. \\
$\hbox{{\rm op}}_{j}$ & is an operation exported by the package.
\end{tabular}
}

% ----------------------------------------------------------------------
%\begin{constructorListing}
% ----------------------------------------------------------------------
\condata{AF}{AlgebraicFunction}{}{{\tt **} belong? definingPolynomial 
inrootof iroot minPoly operator rootOf}
%
\condata{INTHERAL}{AlgebraicHermiteIntegration}{}{HermiteIntegrate}
%
\condata{INTALG}{AlgebraicIntegrate}{}{algintegrate palginfieldint 
palgintegrate}
%
\condata{INTAF}{AlgebraicIntegration}{}{algint}
%
\condata{ALGMANIP}{AlgebraicManipulations}{}{ratDenom ratPoly rootKerSimp 
rootSimp rootSplit}
%
\condata{ALGMFACT}{AlgebraicMultFact}{}{factor}
%
\condata{ALGPKG}{AlgebraPackage}{}{basisOfCenter basisOfCentroid 
basisOfCommutingElements basisOfLeftAnnihilator basisOfLeftNucleus 
basisOfLeftNucloid basisOfMiddleNucleus basisOfNucleus 
basisOfRightAnnihilator basisOfRightNucleus basisOfRightNucloid biRank 
doubleRank leftRank radicalOfLeftTraceForm rightRank weakBiRank}
%
\condata{ALGFACT}{AlgFactor}{}{doublyTransitive? factor split}
%
\condata{ANY1}{AnyFunctions1}{}{coerce retract retractIfCan retractable?}
%
\condata{APPRULE}{ApplyRules}{}{applyRules localUnquote}
%
\condata{PMPRED}{AttachPredicates}{}{suchThat}
%
\condata{BALFACT}{BalancedFactorisation}{}{balancedFactorisation}
%
\condata{BOP1}{BasicOperatorFunctions1}{}{constantOpIfCan constantOperator 
derivative evaluate}
%
\condata{BEZOUT}{BezoutMatrix}{}{bezoutDiscriminant bezoutMatrix 
bezoutResultant}
%
\condata{BOUNDZRO}{BoundIntegerRoots}{}{integerBound}
%
\condata{CARTEN2}{CartesianTensorFunctions2}{}{map reshape}
%
\condata{CHVAR}{ChangeOfVariable}{}{chvar eval goodPoint mkIntegral 
radPoly rootPoly}
%
\condata{CHARPOL}{CharacteristicPolynomialPackage}{}{characteristicPolynomial}
%
\condata{CVMP}{CoerceVectorMatrixPackage}{}{coerce coerceP}
%
\condata{COMBF}{CombinatorialFunction}{}{{\tt **} belong? binomial 
factorial factorials iibinom iidprod iidsum iifact iiperm iipow ipow 
operator permutation product summation}
%
\condata{CDEN}{CommonDenominator}{}{clearDenominator commonDenominator 
splitDenominator}
%
\condata{COMMONOP}{CommonOperators}{}{operator}
%
\condata{COMMUPC}{CommuteUnivariatePolynomialCategory}{}{swap}
%
\condata{COMPFACT}{ComplexFactorization}{}{factor}
%
\condata{COMPLEX2}{ComplexFunctions2}{}{map}
%
\condata{CINTSLPE}{Complex\-Integer\-Solve\-Linear\-Polynomial\-Equation}{}\\
{solveLinearPolynomialEquation}
%
\condata{CRFP}{ComplexRootFindingPackage}{}{complexZeros divisorCascade 
factor graeffe norm pleskenSplit reciprocalPolynomial rootRadius 
schwerpunkt setErrorBound startPolynomial}
%
\condata{CMPLXRT}{ComplexRootPackage}{}{complexZeros}
%
\condata{ODECONST}{ConstantLODE}{}{constDsolve}
%
\condata{COORDSYS}{CoordinateSystems}{}{bipolar\\ 
bipolarCylindrical cartesian conical cylindrical\\ 
elliptic ellipticCylindrical oblateSpheroidal parabolic\\ 
parabolicCylindrical paraboloidal polar prolateSpheroidal\\ 
spherical toroidal}
%
\condata{CRAPACK}{CRApackage}{}{chineseRemainder modTree multiEuclideanTree}
%
\condata{CYCLES}{CycleIndicators}{}{SFunction alternating cap complete cup 
cyclic dihedral elementary eval graphs powerSum skewSFunction wreath}
%
\condata{CSTTOOLS}{CyclicStreamTools}{}\\
{computeCycleEntry computeCycleLength cycleElt}
%
\condata{CYCLOTOM}{CyclotomicPolynomialPackage}{}{cyclotomic 
cyclotomicDecomposition cyclotomicFactorization}
%
\condata{DEGRED}{DegreeReductionPackage}{}{expand reduce}
%
\condata{DIOSP}{DiophantineSolutionPackage}{}{dioSolve}
%
\condata{DIRPROD2}{DirectProductFunctions2}{}{map reduce scan}
%
\condata{DLP}{DiscreteLogarithmPackage}{}{shanksDiscLogAlgorithm}
%
\condata{DISPLAY}{DisplayPackage}{}{bright center copies newLine say sayLength}
%
\condata{DDFACT}{DistinctDegreeFactorize}{}{distdfact exptMod factor 
irreducible? separateDegrees separateFactors tracePowMod}
%
\condata{DBLRESP}{DoubleResultantPackage}{}{doubleResultant}
%
\condata{DRAWHACK}{DrawNumericHack}{}{coerce}
%
\condata{DROPT0}{DrawOptionFunctions0}{}{adaptive\\ 
clipBoolean coordinate curveColorPalette pointColorPalette\\ 
ranges space style title toScale tubePoints tubeRadius units\\ 
var1Steps var2Steps}
%
\condata{DROPT1}{DrawOptionFunctions1}{}{option}
%
\condata{EP}{EigenPackage}{}{characteristicPolynomial eigenvalues 
eigenvector eigenvectors inteigen}
%
\condata{ODEEF}{ElementaryFunctionODESolver}{}{solve}
%
\condata{SIGNEF}{ElementaryFunctionSign}{}{sign}
%
\condata{EFSTRUC}{ElementaryFunctionStructurePackage}{}\\
{normalize realElementary rischNormalize validExponential}
%
\condata{EFUTS}{ElementaryFunctionsUnivariateTaylorSeries}{}{{\tt **} acos 
acosh acot acoth acsc acsch asec asech asin asinh atan atanh cos cosh cot 
coth csc csch exp log sec sech sin sincos sinh sinhcosh tan tanh}
%
\condata{EF}{ElementaryFunction}{}{acos acosh acot acoth acsc acsch asec 
asech asin asinh atan atanh belong? cos cosh cot coth csc csch exp iiacos 
iiacosh iiacot iiacoth iiacsc iiacsch iiasec iiasech iiasin iiasinh 
iiatan iiatanh iicos iicosh iicot iicoth iicsc iicsch iiexp iilog iisec 
iisech iisin iisinh iitan iitanh log operator pi sec sech sin sinh
specialTrigs tan tanh}
%
\condata{INTEF}{ElementaryIntegration}{}{lfextendedint lfextlimint 
lfinfieldint lfintegrate lflimitedint}
%
\condata{RDEEF}{ElementaryRischDE}{}{rischDE}
%
\condata{ELFUTS}{EllipticFunctionsUnivariateTaylorSeries}{}{cn dn sn sncndn}
%
\condata{EQ2}{EquationFunctions2}{}{map}
%
\condata{ERROR}{ErrorFunctions}{}{error}
%
\condata{GBEUCLID}{EuclideanGroebnerBasisPackage}{}{euclideanGroebner 
euclideanNormalForm}
%
\condata{EVALCYC}{EvaluateCycleIndicators}{}{eval}
%
\condata{EXPR2}{ExpressionFunctions2}{}{map}
%
\condata{ES1}{ExpressionSpaceFunctions1}{}{map}
%
\condata{ES2}{ExpressionSpaceFunctions2}{}{map}
%
\condata{EXPRODE}{ExpressionSpaceODESolver}{}{seriesSolve}
%
\condata{EXPR2UPS}{ExpressionToUnivariatePowerSeries}{}{laurent puiseux 
series taylor}
%
\condata{EXPRTUBE}{ExpressionTubePlot}{}{constantToUnaryFunction tubePlot}
%
\condata{FR2}{FactoredFunctions2}{}{map}
%
\condata{FACTFUNC}{FactoredFunctions}{}{log nthRoot}
%
\condata{FRUTIL}{FactoredFunctionUtilities}{}{mergeFactors refine}
%
\condata{FACUTIL}{FactoringUtilities}{}{completeEval degree lowerPolynomial 
normalDeriv raisePolynomial ran variables}
%
\condata{FORDER}{FindOrderFinite}{}{order}
%
\condata{FDIV2}{FiniteDivisorFunctions2}{}{map}
%
\condata{FFF}{FiniteFieldFunctions}{}{createMultiplicationMatrix 
createMultiplicationTable createZechTable sizeMultiplication}
%
\condata{FFHOM}{FiniteFieldHomomorphisms}{}{coerce}
%
\condata{FFPOLY2}{FiniteFieldPolynomialPackage2}{}{rootOfIrreduciblePoly}
%
\condata{FFPOLY}{FiniteFieldPolynomialPackage}{}\\
{createIrreduciblePoly createNormalPoly createNormalPrimitivePoly\\ 
createPrimitiveNormalPoly createPrimitivePoly leastAffineMultiple\\ 
nextIrreduciblePoly nextNormalPoly nextNormalPrimitivePoly\\
nextPrimitiveNormalPoly nextPrimitivePoly normal?\\
numberOfIrreduciblePoly numberOfNormalPoly numberOfPrimitivePoly\\
primitive? random reducedQPowers}
%
\condata{FFSLPE}{FiniteFieldSolveLinearPolynomialEquation}{}
{solve\-Linear\-Polynomial\-Equation}
%
\condata{FLAGG2}{FiniteLinearAggregateFunctions2}{}{map reduce scan}
%
\condata{FLASORT}{FiniteLinearAggregateSort}{}{heapSort quickSort shellSort}
%
\condata{FSAGG2}{FiniteSetAggregateFunctions2}{}{map reduce scan}
%
\condata{FLOATCP}{FloatingComplexPackage}{}{complexRoots complexSolve}
%
\condata{FLOATRP}{FloatingRealPackage}{}{realRoots solve}
%
\condata{FRIDEAL2}{FractionalIdealFunctions2}{}{map}
%
\condata{FRAC2}{FractionFunctions2}{}{map}
%
\condata{FSPECF}{FunctionalSpecialFunction}{}{Beta Gamma abs airyAi airyBi 
belong? besselI besselJ besselK besselY digamma iiGamma iiabs operator 
polygamma}
%
\condata{FFCAT2}{FunctionFieldCategoryFunctions2}{}{map}
%
\condata{FFINTBAS}{FunctionFieldIntegralBasis}{}{integralBasis}
%
\condata{PMASSFS}{FunctionSpaceAssertions}{}{assert constant multiple optional}
%
\condata{PMPREDFS}{FunctionSpaceAttachPredicates}{}{suchThat}
%
\condata{FSCINT}{FunctionSpaceComplexIntegration}{}\\
{complexIntegrate internalIntegrate}
%
\condata{FS2}{FunctionSpaceFunctions2}{}{map}
%
\condata{FSINT}{FunctionSpaceIntegration}{}{integrate}
%
\condata{FSPRMELT}{FunctionSpacePrimitiveElement}{}{primitiveElement}
%
\condata{FSRED}{FunctionSpaceReduce}{}{bringDown newReduc}
%
\condata{SUMFS}{FunctionSpaceSum}{}{sum}
%
\condata{FS2UPS}{FunctionSpaceToUnivariatePowerSeries}{}{exprToGenUPS 
exprToUPS}
%
\condata{FSUPFACT}{FunctionSpaceUnivariatePolynomialFactor}{}{ffactor qfactor}
%
\condata{GAUSSFAC}{GaussianFactorizationPackage}{}{factor prime? sumSquares}
%
\condata{GHENSEL}{GeneralHenselPackage}{}{HenselLift completeHensel}
%
\condata{GENPGCD}{GeneralPolynomialGcdPackage}{}{gcdPolynomial randomR}
%
\condata{GENUPS}{GenerateUnivariatePowerSeries}{}{laurent puiseux series 
taylor}
%
\condata{GENEEZ}{GenExEuclid}{}{compBound reduction solveid tablePow 
testModulus}
%
\condata{GENUFACT}{GenUFactorize}{}{factor}
%
\condata{INTG0}{GenusZeroIntegration}{}{palgLODE0 palgRDE0 palgextint0 
palgint0 palglimint0}
%
\condata{GOSPER}{GosperSummationMethod}{}{GospersMethod}
%
\condata{GRDEF}{GraphicsDefaults}{}{adaptive clipPointsDefault\\ 
drawToScale maxPoints minPoints screenResolution}
%
\condata{GRAY}{GrayCode}{}{firstSubsetGray nextSubsetGray}
%
\condata{GBF}{GroebnerFactorizationPackage}{}{factorGroebnerBasis 
groebnerFactorize}
%
\condata{GBINTERN}{GroebnerInternalPackage}{}{credPol critB critBonD 
critM critMTonD1 critMonD1 critT critpOrder fprindINFO gbasis hMonic 
lepol makeCrit minGbasis prinb prindINFO prinpolINFO prinshINFO redPo 
redPol sPol updatD updatF virtualDegree}
%
\condata{GB}{GroebnerPackage}{}{groebner normalForm}
%
\condata{GROEBSOL}{GroebnerSolve}{}{genericPosition groebSolve testDim}
%
\condata{HB}{HallBasis}{}{generate inHallBasis? lfunc}
%
\condata{HEUGCD}{HeuGcd}{}{content contprim gcd gcdcofact gcdcofactprim 
gcdprim lintgcd}
%
\condata{IDECOMP}{IdealDecompositionPackage}{}{primaryDecomp\\ 
prime? radical zeroDimPrimary? zeroDimPrime?}
%
\condata{INCRMAPS}{IncrementingMaps}{}{increment incrementBy}
%
\condata{ITFUN2}{InfiniteTupleFunctions2}{}{map}
%
\condata{ITFUN3}{InfiniteTupleFunctions3}{}{map}
%
\condata{INFINITY}{Infinity}{}{infinity minusInfinity plusInfinity}
%
\condata{IALGFACT}{InnerAlgFactor}{}{factor}
%
\condata{ICDEN}{InnerCommonDenominator}{}{clearDenominator\\
commonDenominator splitDenominator}
%
\condata{IMATLIN}{InnerMatrixLinearAlgebraFunctions}{}{determinant 
inverse nullSpace nullity rank rowEchelon}
%
\condata{IMATQF}{InnerMatrixQuotientFieldFunctions}{}{inverse 
nullSpace nullity rank rowEchelon}
%
\condata{INMODGCD}{InnerModularGcd}{}{modularGcd reduction}
%
\condata{INNMFACT}{InnerMultFact}{}{factor}
%
\condata{INBFF}{InnerNormalBasisFieldFunctions}{}{{\tt *} {\tt **} {\tt /} 
basis dAndcExp expPot index inv lookup minimalPolynomial norm normal? 
normalElement pol qPot random repSq setFieldInfo trace xn}
%
\condata{INEP}{InnerNumericEigenPackage}{}{charpol innerEigenvectors}
%
\condata{INFSP}{InnerNumericFloatSolvePackage}{}{innerSolve innerSolve1 makeEq}
%
\condata{INPSIGN}{InnerPolySign}{}{signAround}
%
\condata{ISUMP}{InnerPolySum}{}{sum}
%
\condata{ITRIGMNP}{InnerTrigonometricManipulations}{}{F2FG\\ 
FG2F GF2FG explogs2trigs trigs2explogs}
%
\condata{INFORM1}{InputFormFunctions1}{}{interpret packageCall}
%
\condata{COMBINAT}{IntegerCombinatoricFunctions}{}{binomial factorial 
multinomial partition permutation stirling1 stirling2}
%
\condata{INTFACT}{IntegerFactorizationPackage}{}{BasicMethod 
PollardSmallFactor factor squareFree}
%
\condata{ZLINDEP}{IntegerLinearDependence}{}{linearDependenceOverZ 
linearlyDependentOverZ? solveLinearlyOverQ}
%
\condata{INTHEORY}{IntegerNumberTheoryFunctions}{}{bernoulli 
chineseRemainder divisors euler eulerPhi fibonacci harmonic jacobi 
legendre moebiusMu numberOfDivisors sumOfDivisors sumOfKthPowerDivisors}
%
\condata{PRIMES}{IntegerPrimesPackage}{}{nextPrime prevPrime prime? primes}
%
\condata{INTRET}{IntegerRetractions}{}{integer integer? integerIfCan}
%
\condata{IROOT}{IntegerRoots}{}{approxNthRoot approxSqrt perfectNthPower? 
perfectNthRoot perfectSqrt perfectSquare?}
%
\condata{IBATOOL}{IntegralBasisTools}{}{diagonalProduct idealiser leastPower}
%
\condata{IR2}{IntegrationResultFunctions2}{}{map}
%
\condata{IRRF2F}{IntegrationResultRFToFunction}{}{complexExpand\\
complexIntegrate expand integrate split}
%
\condata{IR2F}{IntegrationResultToFunction}{}{complexExpand expand split}
%
\condata{INTTOOLS}{IntegrationTools}{}{kmax ksec mkPrim union vark varselect}
%
\condata{INVLAPLA}{InverseLaplaceTransform}{}{inverseLaplace}
%
\condata{IRREDFFX}{IrredPolyOverFiniteField}{}{generateIrredPoly}
%
\condata{IRSN}{IrrRepSymNatPackage}{}
{dimensionOfIrreducibleRepresentation\\
irreducibleRepresentation}
%
\condata{KERNEL2}{KernelFunctions2}{}{constantIfCan constantKernel}
%
\condata{KOVACIC}{Kovacic}{}{kovacic}
%
\condata{LAPLACE}{LaplaceTransform}{}{laplace}
%
\condata{LEADCDET}{LeadingCoefDetermination}{}{distFact polCase}
%
\condata{LINDEP}{LinearDependence}{}{linearDependence linearlyDependent? 
solveLinear}
%
\condata{LPEFRAC}{LinearPolynomialEquationByFractions}{}\\
{solve\-Linear\-Polynomial\-Equation\-By\-Fractions}
%
\condata{LSMP}{LinearSystemMatrixPackage}{}{aSolution hasSolution? rank solve}
%
\condata{LSPP}{LinearSystemPolynomialPackage}{}{linSolve}
%
\condata{LGROBP}{LinGrobnerPackage}{}
{anticoord choosemon computeBasis\\
coordinate groebgen intcompBasis linGenPos\\ 
minPol totolex transform}
%
\condata{LF}{LiouvillianFunction}{}{Ci Ei Si belong? dilog erf integral 
li operator}
%
\condata{LIST2}{ListFunctions2}{}{map reduce scan}
%
\condata{LIST3}{ListFunctions3}{}{map}
%
\condata{LIST2MAP}{ListToMap}{}{match}
%
\condata{MKBCFUNC}{MakeBinaryCompiledFunction}{}{binaryFunction 
compiledFunction}
%
\condata{MKFLCFN}{MakeFloatCompiledFunction}{}{makeFloatFunction}
%
\condata{MKFUNC}{MakeFunction}{}{function}
%
\condata{MKRECORD}{MakeRecord}{}{makeRecord}
%
\condata{MKUCFUNC}{MakeUnaryCompiledFunction}{}{compiledFunction unaryFunction}
%
\condata{MAPPKG1}{MappingPackage1}{}{{\tt **} coerce fixedPoint id 
nullary recur}
%
\condata{MAPPKG2}{MappingPackage2}{}{const constant curry diag}
%
\condata{MAPPKG3}{MappingPackage3}{}{{\tt *} constantLeft constantRight 
curryLeft curryRight twist}
%
\condata{MAPHACK1}{MappingPackageInternalHacks1}{}{iter recur}
%
\condata{MAPHACK2}{MappingPackageInternalHacks2}{}{arg1 arg2}
%
\condata{MAPHACK3}{MappingPackageInternalHacks3}{}{comp}
%
\condata{MATCAT2}{MatrixCategoryFunctions2}{}{map reduce}
%
\condata{MCDEN}{MatrixCommonDenominator}{}{clearDenominator 
commonDenominator splitDenominator}
%
\condata{MATLIN}{MatrixLinearAlgebraFunctions}{}
{determinant inverse\\
minordet nullSpace nullity rank rowEchelon}
%
\condata{MTHING}{MergeThing}{}{mergeDifference}
%
\condata{MESH}{MeshCreationRoutinesForThreeDimensions}{}
{meshFun2Var\\
meshPar1Var meshPar2Var ptFunc}
%
\condata{MDDFACT}{ModularDistinctDegreeFactorizer}{}{ddFact exptMod 
factor gcd separateFactors}
%
\condata{MHROWRED}{ModularHermitianRowReduction}{}{rowEch rowEchelon}
%
\condata{MRF2}{MonoidRingFunctions2}{}{map}
%
\condata{MSYSCMD}{MoreSystemCommands}{}{systemCommand}
%
\condata{MPC2}{MPolyCatFunctions2}{}{map reshape}
%
\condata{MPC3}{MPolyCatFunctions3}{}{map}
%
\condata{MPRFF}{MPolyCatRationalFunctionFactorizer}{}
{factor pushdown pushdterm\\ 
pushucoef pushuconst pushup totalfract}
%
\condata{MRATFAC}{MRationalFactorize}{}{factor}
%
\condata{MFINFACT}{MultFiniteFactorize}{}{factor}
%
\condata{MMAP}{MultipleMap}{}{map}
%
\condata{MULTFACT}{MultivariateFactorize}{}{factor}
%
\condata{MLIFT}{MultivariateLifting}{}{corrPoly lifting lifting1}
%
\condata{MULTSQFR}{MultivariateSquareFree}{}{squareFree squareFreePrim}
%
\condata{NCODIV}{NonCommutativeOperatorDivision}{}{leftDivide 
leftExactQuotient leftGcd leftLcm leftQuotient leftRemainder}
%
\condata{NONE1}{NoneFunctions1}{}{coerce}
%
\condata{NODE1}{NonLinearFirstOrderODESolver}{}{solve}
%
\condata{NLINSOL}{NonLinearSolvePackage}{}{solve solveInField}
%
\condata{NPCOEF}{NPCoef}{}{listexp npcoef}
%
\condata{NFINTBAS}{NumberFieldIntegralBasis}{}{discriminant integralBasis}
%
\condata{NUMFMT}{NumberFormats}{}{FormatArabic FormatRoman 
ScanArabic ScanRoman}
%
\condata{NTPOLFN}{NumberTheoreticPolynomialFunctions}{}
{bernoulliB cyclotomic eulerE}
%
\condata{NUMODE}{NumericalOrdinaryDifferentialEquations}{}{rk4 rk4a rk4f rk4qc}
%
\condata{NUMQUAD}{NumericalQuadrature}{}\\
{aromberg asimpson atrapezoidal romberg rombergo\\ 
simpson simpsono trapezoidal trapezoidalo}
%
\condata{NCEP}{NumericComplexEigenPackage}{}{characteristicPolynomial 
complexEigenvalues complexEigenvectors}
%
\condata{NCNTFRAC}{NumericContinuedFraction}{}{continuedFraction}
%
\condata{NREP}{NumericRealEigenPackage}{}\\
{characteristicPolynomial realEigenvalues realEigenvectors}
%
\condata{NUMTUBE}{NumericTubePlot}{}{tube}
%
\condata{NUMERIC}{Numeric}{}{complexNumeric numeric}
%
\condata{OCTCT2}{OctonionCategoryFunctions2}{}{map}
%
\condata{ODEINT}{ODEIntegration}{}{expint int}
%
\condata{ODETOOLS}{ODETools}{}{particularSolution variationOfParameters 
wronskianMatrix}
%
\condata{ARRAY12}{OneDimensionalArrayFunctions2}{}{map reduce scan}
%
\condata{ONECOMP2}{OnePointCompletionFunctions2}{}{map}
%
\condata{OPQUERY}{OperationsQuery}{}{getDatabase}
%
\condata{ORDCOMP2}{OrderedCompletionFunctions2}{}{map}
%
\condata{ORDFUNS}{OrderingFunctions}{}{pureLex reverseLex totalLex}
%
\condata{ORTHPOL}{OrthogonalPolynomialFunctions}{}{ChebyshevU chebyshevT 
hermiteH laguerreL legendreP}
%
\condata{OUT}{OutputPackage}{}{output}
%
\condata{PADEPAC}{PadeApproximantPackage}{}{pade}
%
\condata{PADE}{PadeApproximants}{}{pade padecf}
%
\condata{YSTREAM}{ParadoxicalCombinatorsForStreams}{}{Y}
%
\condata{PARTPERM}{PartitionsAndPermutations}{}
{conjugate conjugates partitions\\ 
permutations sequences shuffle shufflein}
%
\condata{PATTERN1}{PatternFunctions1}{}
{addBadValue badValues predicate satisfy?\\
suchThat}
%
\condata{PATTERN2}{PatternFunctions2}{}{map}
%
\condata{PMASS}{PatternMatchAssertions}{}{assert constant multiple optional}
%
\condata{PMFS}{PatternMatchFunctionSpace}{}{patternMatch}
%
\condata{PMINS}{PatternMatchIntegerNumberSystem}{}{patternMatch}
%
\condata{PMKERNEL}{PatternMatchKernel}{}{patternMatch}
%
\condata{PMLSAGG}{PatternMatchListAggregate}{}{patternMatch}
%
\condata{PMPLCAT}{PatternMatchPolynomialCategory}{}{patternMatch}
%
\condata{PMDOWN}{PatternMatchPushDown}{}{fixPredicate patternMatch}
%
\condata{PMQFCAT}{PatternMatchQuotientFieldCategory}{}{patternMatch}
%
\condata{PATRES2}{PatternMatchResultFunctions2}{}{map}
%
\condata{PMSYM}{PatternMatchSymbol}{}{patternMatch}
%
\condata{PMTOOLS}{PatternMatchTools}{}{patternMatch patternMatchTimes}
%
\condata{PATMATCH}{PatternMatch}{}{Is is?}
%
\condata{PERMAN}{Permanent}{}{permanent}
%
\condata{PGE}{PermutationGroupExamples}{}{abelianGroup alternatingGroup 
cyclicGroup dihedralGroup janko2 mathieu11 mathieu12 mathieu22 mathieu23 
mathieu24 rubiksGroup symmetricGroup youngGroup}
%
\condata{PICOERCE}{PiCoercions}{}{coerce}
%
\condata{PLOT1}{PlotFunctions1}{}{plot plotPolar}
%
\condata{PLOTTOOL}{PlotTools}{}{calcRanges}
%
\condata{PTFUNC2}{PointFunctions2}{}{map}
%
\condata{PTPACK}{PointPackage}{}{color hue phiCoord rCoord shade 
thetaCoord xCoord yCoord zCoord}
%
\condata{PFOQ}{PointsOfFiniteOrderRational}{}{order torsion? torsionIfCan}
%
\condata{PFOTOOLS}{PointsOfFiniteOrderTools}{}{badNum doubleDisc 
getGoodPrime mix polyred}
%
\condata{PFO}{PointsOfFiniteOrder}{}{order torsion? torsionIfCan}
%
\condata{POLTOPOL}{PolToPol}{}{dmpToNdmp dmpToP ndmpToDmp ndmpToP 
pToDmp pToNdmp}
%
\condata{PGROEB}{PolyGroebner}{}{lexGroebner totalGroebner}
%
\condata{PAN2EXPR}{PolynomialAN2Expression}{}{coerce}
%
\condata{POLYLIFT}{PolynomialCategoryLifting}{}{map}
%
\condata{POLYCATQ}{PolynomialCategoryQuotientFunctions}{}{isExpt isPlus 
isPower isTimes mainVariable multivariate univariate variables}
%
\condata{PFBRU}{PolynomialFactorizationByRecursionUnivariate}{}\\
{bivariateSLPEBR factorByRecursion factorSFBRlcUnit\\
factorSquareFreeByRecursion randomR\\ 
solveLinearPolynomialEquationByRecursion}
%
\condata{PFBR}{PolynomialFactorizationByRecursion}{}\\
{bivariateSLPEBR factorByRecursion factorSFBRlcUnit\\
factorSquareFreeByRecursion randomR\\ 
solveLinearPolynomialEquationByRecursion}
%
\condata{POLY2}{PolynomialFunctions2}{}{map}
%
\condata{PGCD}{PolynomialGcdPackage}{}{gcd gcdPrimitive}
%
\condata{PINTERPA}{PolynomialInterpolationAlgorithms}{}{LagrangeInterpolation}
%
\condata{PINTERP}{PolynomialInterpolation}{}{interpolate}
%
\condata{PNTHEORY}{PolynomialNumberTheoryFunctions}{}{bernoulli 
chebyshevT chebyshevU cyclotomic euler fixedDivisor hermite laguerre legendre}
%
\condata{POLYROOT}{PolynomialRoots}{}{froot qroot rroot}
%
\condata{SOLVEFOR}{PolynomialSolveByFormulas}{}{aCubic aLinear 
aQuadratic aQuartic aSolution cubic linear mapSolve quadratic quartic solve}
%
\condata{PSQFR}{PolynomialSquareFree}{}{squareFree}
%
\condata{POLY2UP}{PolynomialToUnivariatePolynomial}{}{univariate}
%
\condata{LIMITPS}{PowerSeriesLimitPackage}{}{complexLimit limit}
%
\condata{PRIMARR2}{PrimitiveArrayFunctions2}{}{map reduce scan}
%
\condata{PRIMELT}{PrimitiveElement}{}{primitiveElement}
%
\condata{ODEPRIM}{PrimitiveRatDE}{}{denomLODE}
%
\condata{ODEPRRIC}{PrimitiveRatRicDE}{}\\
{changevar constantCoefficientRicDE denomRicDE\\ 
leadingCoefficientRicDE polyRicDE singRicDE}
%
\condata{PRINT}{PrintPackage}{}{print}
%
\condata{INTPAF}{PureAlgebraicIntegration}{}{palgLODE palgRDE palgextint 
palgint palglimint}
%
\condata{ODEPAL}{PureAlgebraicLODE}{}{algDsolve}
%
\condata{QALGSET2}{QuasiAlgebraicSet2}{}{radicalSimplify}
%
\condata{QUATCT2}{QuaternionCategoryFunctions2}{}{map}
%
\condata{QFCAT2}{QuotientFieldCategoryFunctions2}{}{map}
%
\condata{REP}{RadicalEigenPackage}{}{eigenMatrix gramschmidt normalise 
orthonormalBasis radicalEigenvalues radicalEigenvector radicalEigenvectors}
%
\condata{SOLVERAD}{RadicalSolvePackage}{}{contractSolve radicalRoots 
radicalSolve}
%
\condata{RADUTIL}{RadixUtilities}{}{radix}
%
\condata{RANDSRC}{RandomNumberSource}{}{randnum reseed size}
%
\condata{RATFACT}{RationalFactorize}{}{factor}
%
\condata{DEFINTRF}{RationalFunctionDefiniteIntegration}{}{integrate}
%
\condata{RFFACTOR}{RationalFunctionFactorizer}{}{factorFraction}
%
\condata{RFFACT}{RationalFunctionFactor}{}{factor}
%
\condata{INTRF}{RationalFunctionIntegration}{}{extendedIntegrate 
infieldIntegrate internalIntegrate limitedIntegrate}
%
\condata{LIMITRF}{RationalFunctionLimitPackage}{}{complexLimit limit}
%
\condata{SIGNRF}{RationalFunctionSign}{}{sign}
%
\condata{SUMRF}{RationalFunctionSum}{}{sum}
%
\condata{RF}{RationalFunction}{}{coerce eval mainVariable multivariate 
univariate variables}
%
\condata{INTRAT}{RationalIntegration}{}{extendedint infieldint integrate 
limitedint}
%
\condata{ODERAT}{RationalLODE}{}{ratDsolve}
%
\condata{RATRET}{RationalRetractions}{}{rational rational? rationalIfCan}
%
\condata{ODERTRIC}{RationalRicDE}{}{changevar constantCoefficientRicDE 
polyRicDE ricDsolve singRicDE}
%
\condata{RTODETLS}{RatODETools}{}{genericPolynomial}
%
\condata{REALSOLV}{RealSolvePackage}{}{realSolve solve}
%
\condata{REAL0Q}{RealZeroPackageQ}{}{realZeros refine}
%
\condata{REAL0}{RealZeroPackage}{}{midpoint midpoints realZeros refine}
%
\condata{RMCAT2}{RectangularMatrixCategoryFunctions2}{}{map reduce}
%
\condata{RDIV}{ReducedDivisor}{}{order}
%
\condata{ODERED}{ReduceLODE}{}{reduceLODE}
%
\condata{REDORDER}{ReductionOfOrder}{}{ReduceOrder}
%
\condata{REPDB}{RepeatedDoubling}{}{double}
%
\condata{REPSQ}{RepeatedSquaring}{}{expt}
%
\condata{REP1}{RepresentationPackage1}{}{antisymmetricTensors 
createGenericMatrix permutationRepresentation symmetricTensors tensorProduct}
%
\condata{REP2}{RepresentationPackage2}{}\\
{areEquivalent? completeEchelonBasis createRandomElement\\ 
cyclicSubmodule isAbsolutelyIrreducible? meatAxe\\
scanOneDimSubspaces split standardBasisOfCyclicSubmodule}
%
\condata{RESLATC}{ResolveLatticeCompletion}{}{coerce}
%
\condata{RETSOL}{RetractSolvePackage}{}{solveRetract}
%
\condata{SAERFFC}{SAERationalFunctionAlgFactor}{}{factor}
%
\condata{SEGBIND2}{SegmentBindingFunctions2}{}{map}
%
\condata{SEG2}{SegmentFunctions2}{}{map}
%
\condata{SAEFACT}{SimpleAlgebraicExtensionAlgFactor}{}{factor}
%
\condata{DFLOATSFUN}{DoubleFloatSpecialFunctions}{}{Beta Gamma airyAi 
airyBi besselI besselJ besselK besselY digamma hypergeometric0F1 logGamma 
polygamma}
%
\condata{SCACHE}{SortedCache}{}{cache clearCache enterInCache}
%
\condata{SUP2}{SparseUnivariatePolynomialFunctions2}{}{map}
%
\condata{SPECOUT}{SpecialOutputPackage}{}{outputAsFortran outputAsScript 
outputAsTex}
%
\condata{MATSTOR}{StorageEfficientMatrixOperations}{}{{\tt **} copy! 
leftScalarTimes! minus! plus! power! rightScalarTimes! times!}
%
\condata{STREAM1}{StreamFunctions1}{}{concat}
%
\condata{STREAM2}{StreamFunctions2}{}{map reduce scan}
%
\condata{STREAM3}{StreamFunctions3}{}{map}
%
\condata{STTAYLOR}{StreamTaylorSeriesOperations}{}{{\tt *} {\tt +} {\tt -} 
{\tt /} addiag coerce compose deriv eval evenlambert gderiv generalLambert 
int integers integrate invmultisect lagrange lambert lazyGintegrate 
lazyIntegrate mapdiv mapmult monom multisect nlde oddintegers 
oddlambert power powern recip revert}
%
\condata{STTF}{StreamTranscendentalFunctions}{}{{\tt **} acos acosh acot 
acoth acsc acsch asec asech asin asinh atan atanh cos cosh cot coth csc 
csch exp log sec sech sin sincos sinh sinhcosh tan tanh}
%
\condata{SUBRESP}{SubResultantPackage}{}{primitivePart subresultantVector}
%
\condata{SYMFUNC}{SymmetricFunctions}{}{symFunc}
%
\condata{SGCF}{SymmetricGroupCombinatoricFunctions}{}\\
{coleman inverseColeman listYoungTableaus makeYoungTableau\\ 
nextColeman nextLatticePermutation nextPartition\\ 
numberOfImproperPartitions subSet unrankImproperPartitions0\\ 
unrankImproperPartitions1}
%
\condata{ODESYS}{SystemODESolver}{}{solveInField triangulate}
%
\condata{SYSSOLP}{SystemSolvePackage}{}{solve triangularSystems}
%
\condata{TABLBUMP}{TableauxBumpers}{}{bat bat1 bumprow bumptab bumptab1 
inverse lex maxrow mr slex tab tab1 untab}
%
\condata{TANEXP}{TangentExpansions}{}{tanAn tanNa tanSum}
%
\condata{TOOLSIGN}{ToolsForSign}{}{direction nonQsign sign}
%
\condata{DRAWCURV}{TopLevelDrawFunctionsForAlgebraicCurves}{}{draw}
%
\condata{DRAWCFUN}{TopLevelDrawFunctionsForCompiledFunctions}{}{draw 
makeObject recolor}
%
\condata{DRAW}{TopLevelDrawFunctions}{}{draw makeObject}
%
\condata{TOPSP}{TopLevelThreeSpace}{}{createThreeSpace}
%
\condata{INTHERTR}{TranscendentalHermiteIntegration}{}{HermiteIntegrate}
%
\condata{INTTR}{TranscendentalIntegration}{}{expextendedint expintegrate 
expintfldpoly explimitedint primextendedint primextintfrac primintegrate 
primintegratefrac primintfldpoly primlimintfrac primlimitedint}
%
\condata{TRMANIP}{TranscendentalManipulations}{}\\
{cos2sec cosh2sech cot2tan cot2trig coth2tanh\\ 
coth2trigh csc2sin csch2sinh expand expandLog\\ 
expandPower htrigs removeCosSq removeCoshSq\\ 
removeSinSq removeSinhSq sec2cos sech2cosh\\ 
simplify simplifyExp sin2csc sinh2csch\\ 
tan2cot tan2trig tanh2coth tanh2trigh}
%
\condata{RDETR}{TranscendentalRischDE}{}{DSPDE SPDE baseRDE expRDE primRDE}
%
\condata{SOLVESER}{TransSolvePackageService}{}{decomposeFunc unvectorise}
%
\condata{SOLVETRA}{TransSolvePackage}{}{solve}
%
\condata{TRIMAT}{TriangularMatrixOperations}{}{LowTriBddDenomInv 
UpTriBddDenomInv}
%
\condata{TRIGMNIP}{TrigonometricManipulations}{}{complexElementary 
complexNormalize imag real real? trigs}
%
\condata{TUBETOOL}{TubePlotTools}{}{{\tt *} {\tt +} {\tt -} cosSinInfo 
cross dot loopPoints point unitVector}
%
\condata{CLIP}{TwoDimensionalPlotClipping}{}{clip clipParametric 
clipWithRanges}
%
\condata{TWOFACT}{TwoFactorize}{}{generalSqFr generalTwoFactor twoFactor}
%
\condata{UNIFACT}{UnivariateFactorize}{}{factor factorSquareFree genFact 
henselFact henselfact quadratic sqroot trueFactors}
%
\condata{ULS2}{UnivariateLaurentSeriesFunctions2}{}{map}
%
\condata{UPOLYC2}{UnivariatePolynomialCategoryFunctions2}{}{map}
%
\condata{UPCDEN}{UnivariatePolynomialCommonDenominator}{}{clearDenominator 
commonDenominator splitDenominator}
%
\condata{UP2}{UnivariatePolynomialFunctions2}{}{map}
%
\condata{UPSQFREE}{UnivariatePolynomialSquareFree}{}
{BumInSepFFE\\ 
squareFree squareFreePart}
%
\condata{UPXS2}{UnivariatePuiseuxSeriesFunctions2}{}{map}
%
\condata{UTS2}{UnivariateTaylorSeriesFunctions2}{}{map}
%
\condata{UTSODE}{UnivariateTaylorSeriesODESolver}{}{mpsode ode ode1 ode2 
stFunc1 stFunc2 stFuncN}
%
\condata{UNISEG2}{UniversalSegmentFunctions2}{}{map}
%
\condata{UDPO}{UserDefinedPartialOrdering}{}{getOrder largest less? more? 
setOrder userOrdered?}
%
\condata{UDVO}{UserDefinedVariableOrdering}{}{getVariableOrder 
resetVariableOrder setVariableOrder}
%
\condata{VECTOR2}{VectorFunctions2}{}{map reduce scan}
%
\condata{VIEWDEF}{ViewDefaultsPackage}{}
{axes\-Color\-Default line\-Color\-Default point\-Color\-Default\\
point\-Size\-Default tube\-Points\-Default tube\-Radius\-Default\\
units\-Color\-Default var1Steps\-Default var2\-StepsDefault\\ 
view\-Defaults view\-PosDefault view\-SizeDefault\\ 
view\-WriteAvailable view\-WriteDefault}
%
\condata{VIEW}{ViewportPackage}{}{coerce drawCurves graphCurves}
%
\condata{WEIER}{WeierstrassPreparation}{}{cfirst clikeUniv crest qqq 
sts2stst weierstrass}
%
\condata{WFFINTBS}{WildFunctionFieldIntegralBasis}{}{integralBasis 
listSquaredFactors}
%
%
% ----------------------------------------------------------------------
%\end{constructorListing}
% ----------------------------------------------------------------------


%\setcounter{chapter}{4} % Appendix E

%%Original Page 627

{
%\twocolumn[%
\chapter{Operations}
\label{ugAppOperations}

This appendix contains a partial list of Axiom operations
with brief descriptions.
For more details, use the Browse facility of HyperDoc:
enter the name of the operation for which you want more information
in the input area on the main Browse menu and then click on
{\bf Operations.}

\vskip \baselineskip
%]
\def\alt#1#2{{$\lbrace$#1$\mid$#2$\rbrace$}}
\def\altx#1#2#3{{$\lbrace$#1$\mid$#2$\mid$#3$\rbrace$}}
\def\opt#1{{$\,[$#1$]$}}
\def\bigLeftBrack{{\tt \[}}
\def\bigRightBrack{{\tt \]}}
\def\smallLeftBrack{{\tt \[}}
\def\smallRightBrack{{\tt \]}}
\def\optinit#1{{$[$#1$]$}}
\def\optfirst#1{{[#1]}}
\def\from#1{{From {\bf #1}.}}
\def\consultType#1{{Consult {\bf #1} using Browse for details.}}
\def\colx#1#2#3{{[#1,#2,\ldots,#3]}}
\def\col#1#2{{[#1,\ldots,]}}
\def\code#1{{\tt #1}}
\def\Script{IBM SCRIPT Formula Formatter}

\def\smallbreak{{\hfill{\break}}}
\def\newitem{{\smallbreak}}
\def\bigitem{{\medbreak}}
\def\largerbreak{{\hfill{\smallskip\break}}}
\def\medbreak{{\hfill{\medskip\break}}}
\def\bigbreak{{\hfill{\bigskip\break}}}
\long\def\bigopkey#1{{#1}}
\long\def\opkey#1{{#1}}

\def\and{{\ {\bf and}\ }}
\def\or{{\ {\bf or}\ }}
\def\mod{{\ {\bf mod}\ }}
\def\quo{{\ {\bf quo}\ }}
\def\rem{{\ {\bf rem}\ }}
\def\opLeftPren{\nobreak\,{\tt (}}
\def\opRightPren{\nobreak{\tt )}\allowbreak}

\def\seeType#1{{See {\bf #1} using Browse.}}
\def\seeAlso#1{{See also #1}.}
\def\seeOther#1{{For additional information on $#1$, consult Browse.}}
\def\sayOption#1#2{{This command may be given as a draw option: $#1 == #2$.}}
\def\seeDetails#1{{Consult {\bf #1} using Browse for details.}}

\long\def\opdataQual#1#2#3#4#5#6{{
  \opdata{#1}{#2}{#3}{#4}{#5\newitem#6}
}}

\long\def\opdata#1#2#3#4#5{{
  %#1 name  #2 number of args #3 sig  #4 con  #5 documentation
   \hyphenpenalty=1000
   \exhyphenpenalty=1000
   \par\vskip 4pt\optitle{#1}\nopagebreak\par\vskip -\parskip%
   \vskip 2pt\nopagebreak\noindent%
   {\def\TYsize{\SMTYfont}#5}\par}}

\def\mathOrSpad#1{{$#1$}}
\def\smath#1{\mathOrSpad{#1}}
\def\twodim{two-di\-men\-sion\-al}
\def\threedim{three-di\-men\-sion\-al}
\def\keydata#1#2#3#4#5{{\opdata{#1}{#2}{#3}{#4}{#5}}}
\def\keyop#1{{{\large{$#1$}}}}
\def\optitle#1{{\bf #1}}
\def\opand{\optand}
\def\optand{{\par\vskip -\parskip}}
\def\optinner#1{{[#1]}}
\def\opname#1{{\tt #1}}
\def\opoption#1#2{{{\tt #1}$== #2$}}

\long\def\xxdata#1#2#3#4#5{{}}

\def\indented#1{{#1}}
\def\spadsyscom#1{{#1}}

\sloppy\raggedright
%\input{oplist}

\fussy

\keydata{\keyop{\#}aggregate}{1}{(\$)->NonNegativeInteger}{Aggregate}
   {\smath{\# a} returns the number of items in \smath{a}.
}

\keydata{x\keyop{**}y}{2}{(\$, \$)->\$}{ElementaryFunctionCategory}
   {\smath{x**y} returns \smath{x} to the power \smath{y}.
Also, this operation returns, if \smath{x} is:
\begin{simpleList}
\item an equation: a new equation by raising both sides of 
\smath{x} to the power \smath{y}.
\item a float or small float: 
\smath{\mbox{\bf sign}\opLeftPren{}x\opRightPren{}}
\smath{\mbox{\bf exp}\opLeftPren{}y \log(|x|)\opRightPren{}}.
\end{simpleList}
See also \axiomType{InputForm} and \axiomType{OutputForm}.
}

\keydata{x\keyop{*}y}{2}{(Integer, \$)->\$}{AbelianGroup}
  {\opkey{The binary operator \smath{*} denotes multiplication.
Its meaning depends on the type of its arguments:}
\begin{simpleList}
\item if \smath{x} and \smath{y} are members of a ring (more generally, 
a domain of
category \axiomType{SemiGroup}), \smath{x*y} returns the product of 
\smath{x} and \smath{y}.
\item if \smath{r} is an integer and \smath{x} is an element of a ring, or
if \smath{r} is a scalar and \smath{x} is a vector, matrix, or direct product:
\smath{r*x} returns the left multiplication of \smath{r} by \smath{x}.
More generally, if \smath{r} is an integer and \smath{x} is a
member of a domain of category \axiomType{AbelianMonoid},
or \smath{r} is a member of domain \smath{R} and \smath{x} is a 
domain of category
\axiomType{Module(R)}, \axiomType{GradedModule}, or \axiomType{GradedAlgebra}
defined over \smath{R},
\smath{r*x} returns the left multiplication of \smath{r} by \smath{x}.
Here \smath{x} can be a vector, a matrix, or a direct product.
Similarly, \smath{x*n} returns the right integer multiple of \smath{x}.
\item if \smath{a} and \smath{b} are monad elements,
the product of \smath{a} and \smath{b} (see \axiomType{Monad}).
\item if \smath{A} and \smath{B} are matrices,
returns the product of \smath{A} and \smath{B}.
If \smath{v} is a row vector, \smath{v*A}
returns the product of \smath{v} and \smath{A}.
If \smath{v} is column vector, \smath{A*v}
returns the product of \smath{A} with column vector \smath{v}.
In each case, the operation calls \spadfun{error}
if the dimensions are incompatible.
\item if \smath{s} is an integer or float and \smath{c} is a color, 
\smath{s*c} returns
the weighted shade scaled by \smath{s}.
\item if \smath{s} and \smath{t} are Cartesian tensors,
\smath{s*t} is the inner product of the tensors \smath{s} and \smath{t}.
This contracts the last index of \smath{s} with the first index of \smath{t},
that is,
\smath{t*s = \mbox{\tt contract}(t, \mbox{\tt rank } t, s, 1)},
\smath{t*s = \sum\nolimits_{k=1}^N{t([i_1, .., i_N, k]*s[k, j_1, .., j_M])}}.
\item if \smath{eq} is an equation, \smath{r*eq}
multiplies both sides of \smath{eq} by r.
\item if \smath{I} and \smath{J} are ideals, the product of ideals.
\item See also \axiomType{OutputForm}, \axiomType{Monad},
\axiomType{LeftModule},
\axiomType{RightModule}, and
\axiomType{FreeAbelianMonoidCategory},
\end{simpleList}
See also \axiomType{InputForm} and \axiomType{OutputForm}.
}

\keydata{x\keyop{+}y}{2}{(Integer, \$)->\$}{AbelianGroup}
  {\opkey{The binary operator \smath{+} denotes addition.
Its meaning depends on the type of its arguments.
If \smath{x} and \smath{y} are:}
\begin{simpleList}
\item members of a ring (more generally,
of a domain of category \axiomType{AbelianSemiGroup}):
the sum of \smath{x} and \smath{y}.
\item matrices:
the matrix sum if \smath{x} and \smath{y} have the same dimensions,
and \spadfun{error} otherwise.
\item vectors: the component-wise sum if \smath{x} and \smath{y} have
the same length, and \spadfun{error} otherwise.
\item colors:  a color which additively mixes colors \smath{x} and \smath{y}.
\item equations: an equation created by adding the respective 
left- and right-hand
sides of \smath{x} and \smath{y}.
\item elements of graded module or algebra:
the sum of \smath{x} and \smath{y} in the module of elements
of the same degree as \smath{x} and \smath{y}.
\item ideals: the ideal generated by the union of \smath{x} and \smath{y}.
\end{simpleList}
See also \axiomType{FreeAbelianMonoidCategory},
\axiomType{InputForm} and \axiomType{OutputForm}.
}

\keydata{\optinit{x}\keyop{-}y}{1}{(\$)->\$}{AbelianGroup}
  {\smath{- x} returns the negative (additive inverse) of \smath{x},
where \smath{x} is a member of a ring
(more generally, a domain of category \axiomType{AbelianGroup}).
Also, \smath{x} may be a matrix, a vector, or a member of a graded module.
  \newitem
  \smath{x - y} returns \smath{x + (-y)}.
  \newitem
See also \axiomType{CancellationAbelianMonoid} and \axiomType{OutputForm}.
}

\keydata{x\keyop{/}y}{2}{(\$, \$)->\$}{Group}
{\opkey{The binary operator \smath{/} generally denotes binary
division.
Its precise meaning, however, depends on the type of its arguments:}
\begin{simpleList}
\item \smath{x} and \smath{y} are elements of a group: multiplies 
\smath{x} by the inverse 
\smath{\mbox{\bf inv}\opLeftPren{}y\opRightPren{}} of \smath{y}.
\item \smath{x} and \smath{y} are elements of a field: divides 
\smath{x} by \smath{y}, calling
\spadfun{error} if \smath{y=0}.
\item \smath{x} is a matrix or a vector and \smath{y} is a scalar: 
divides each element of \smath{x} by \smath{y}.
\item \smath{x} and \smath{y} are floats or small floats: divides 
\smath{x} by \smath{y}.
\item \smath{x} and \smath{y} are fractions: returns the quotient 
as another fraction.
\item \smath{x} and \smath{y} are polynomials: returns the quotient
as a fraction of polynomials.
\end{simpleList}
See also \axiomType{AbelianMonoidRing}, \axiomType{InputForm} and 
\axiomType{OutputForm}.
}

\keydata{\keyop{0}}{0}{()->\$}{AbelianMonoid}{The additive
identity element for a ring (more generally, for an
\axiomType{AbelianMonoid}).
Also, for a graded module or algebra, the zero of degree 0 (see
\axiomType{GradedModule}).
See also \axiomType{InputForm}.
}

\keydata{\keyop{1}}{0}{()->\$}{GradedAlgebra}
{The multiplicative identity element for a ring
(more generally, for a \axiomType{Monoid} and \axiomType{MonadWithUnit}).
or a graded algebra.
See also \axiomType{InputForm}.
}

\keydata{x\keyop{<}y}{2}{(\$, \$)->Boolean}{OrderedSet}
  {\opkey{The binary operator \smath{<} denotes the boolean-valued
``less than'' function.
Its meaning depends on the type of its arguments.
The operation \smath{x < y} for \smath{x} and \smath{y}:}
\begin{simpleList}
\item elements of a totally ordered set (such as integer and 
floating point numbers):
tests if \smath{x} is less than y.
\item sets: tests if all the elements of \smath{x} are also elements of y.
\item permutations: tests if \smath{x} is less than \smath{y};
see \axiomType{Permutation} for details.
Note: this order relation is total if and only
if the underlying domain is of category \axiomType{Finite} or 
\axiomType{OrderedSet}.
\item permutation groups: tests if \smath{x} is a proper subgroup of y.
\item See also \axiomType{OutputForm}.
\end{simpleList}
}

\keydata{x\keyop{=}y}{2}{(S, S)->\$}{Equation}
  {\opkey{The meaning of binary operator \smath{x = y}
depends on the value expected of the operation.
If the value is expected to be:}
\begin{simpleList}
\item a boolean: \smath{x = y} tests that \smath{x} and \smath{y} are equal.
\item an equation: \smath{x = y} creates an equation.
\item See also \axiomType{OutputForm}.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{abelianGroup}}\opLeftPren{}
{\it listOfPositiveIntegers}\opRightPren{}%
}%
}%
{1}{(List(PositiveInteger))->PermutationGroup(Integer)}
{PermutationGroupExamples}
{\smath{\mbox{\bf abelianGroup}\opLeftPren{}[p_1, 
\allowbreak{} \ldots, p_k]\opRightPren{}} constructs the abelian
group that is the direct product of cyclic groups with order
\smath{p_i}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{absolutelyIrreducible?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FunctionFieldCategory}
{\smath{\mbox{\bf absolutelyIrreducible?}\opLeftPren{}\opRightPren{}\$F} 
tests if the algebraic
function field \smath{F}
remains irreducible over the algebraic closure of the ground field.
\seeType{FunctionFieldCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{abs}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->R}{ComplexCategory}
 {\smath{\mbox{\bf abs}\opLeftPren{}x\opRightPren{}} returns the 
absolute value of \smath{x},
an element of an \axiomType{OrderedRing} or a \axiomType{Complex}, 
\axiomType{Quaternion},
or \axiomType{Octonion} value.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{acos}}\opLeftPren{}{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{acosIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex}, 
\axiomType{Float}, \axiomType{DoubleFloat}, or
  \axiomType{Expression} value or a series.}
  \newitem\smath{\mbox{\bf acos}\opLeftPren{}x\opRightPren{}} 
returns the arccosine of \smath{x}.
  \newitem\smath{\mbox{\bf acosIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf acos}\opLeftPren{}x\opRightPren{}} 
if possible, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{acosh}}\opLeftPren{}
{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{acoshIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.
}
\newitem\smath{\mbox{\bf acosh}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic arccosine of
\smath{x}.
  \newitem
\smath{\mbox{\bf acoshIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf acosh}\opLeftPren{}x\opRightPren{}} if possible, and
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{acoth}}\opLeftPren{}{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{acothIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
 {\opkey{Argument \smath{x} can be a \axiomType{Complex}, 
\axiomType{Float}, \axiomType{DoubleFloat}, or
  \axiomType{Expression} value or a series. }
  \newitem\smath{\mbox{\bf acoth}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic arccotangent of \smath{x}.
  \newitem
  \smath{\mbox{\bf acothIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf acoth}\opLeftPren{}x\opRightPren{}} if possible, and 
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{acot}}\opLeftPren{}{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{acotIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
  {\opkey{Argument \smath{x} can be a \axiomType{Complex}, 
\axiomType{Float}, \axiomType{DoubleFloat}, or
  \axiomType{Expression} value or a series. }
  \newitem\smath{\mbox{\bf acot}\opLeftPren{}x\opRightPren{}} 
returns the arccotangent of \smath{x}.
  \newitem
\smath{\mbox{\bf acotIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf acot}\opLeftPren{}x\opRightPren{}} if possible, and
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{acsch}}\opLeftPren{}{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{acschIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.
}
\newitem\smath{\mbox{\bf acsch}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic arccosecant of
\smath{x}.
  \newitem
\smath{\mbox{\bf acschIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf acsch}\opLeftPren{}x\opRightPren{}} if possible, and
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{acsc}}\opLeftPren{}{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{acscIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
  {\opkey{Argument \smath{x} can be a \axiomType{Complex}, 
\axiomType{Float}, \axiomType{DoubleFloat}, or
  \axiomType{Expression} value or a series. }
  \newitem\smath{\mbox{\bf acsc}\opLeftPren{}x\opRightPren{}} 
returns the arccosecant of \smath{x}.
  \newitem
  \smath{\mbox{\bf acscIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf acsc}\opLeftPren{}x\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{adaptive}}\opLeftPren{}
{\it \opt{boolean}}\opRightPren{}%
}%
}%
{0}{()->Boolean}{GraphicsDefaults}
 {\smath{\mbox{\bf adaptive}\opLeftPren{}\opRightPren{}} 
tests whether plotting will be done adaptively.
  \newitem
  \smath{\mbox{\bf adaptive}\opLeftPren{}true\opRightPren{}} 
turns adaptive plotting on; 
\smath{\mbox{\bf adaptive}\opLeftPren{}false\opRightPren{}} 
turns it off.
  Note: this command can be expressed by the draw option \smath{adaptive == b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{addmod}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, \$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf addmod}\opLeftPren{}a, 
\allowbreak{} b, \allowbreak{} p\opRightPren{}}, $0\le a, b<p>1$, 
means $a+b \mod p$.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{airyAi}}\opLeftPren{}
{\it complexDoubleFloat}\opRightPren{}%
\opand \mbox{\axiomFun{airyBi}}\opLeftPren{}
{\it complexDoubleFloat}\opRightPren{}%
}%
}%
{1}{(Complex(DoubleFloat))->Complex(DoubleFloat)}{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf airyAi}\opLeftPren{}x\opRightPren{}} 
is the Airy function ${\rm Ai}(x)$ satisfying the
differential equation
${\rm Ai}''(x) - x {\rm Ai}(x) = 0$.
\newitem
  \smath{\mbox{\bf airyBi}\opLeftPren{}x\opRightPren{}} 
is the Airy function ${\rm Bi}(x)$ satisfying the differential equation
${\rm Bi}''(x) - x  {\rm Bi}(x) = 0$.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{Aleph}}\opLeftPren{}
{\it nonNegativeInteger}\opRightPren{}%
}%
}%
{1}{(NonNegativeInteger)->\$}{CardinalNumber}
{\smath{\mbox{\bf Aleph}\opLeftPren{}n\opRightPren{}} provides the 
named (infinite) cardinal number.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{algebraic?}}\opLeftPren{}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{ExtensionField}
{\smath{\mbox{\bf algebraic?}\opLeftPren{}a\opRightPren{}} tests whether 
an element \smath{a} is algebraic with respect to the ground field \smath{F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{alphabetic}}\opLeftPren{}\opRightPren{}%
\opand \mbox{\axiomFun{alphabetic?}}\opLeftPren{}
{\it character}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Character}
{\smath{\mbox{\bf alphabetic}\opLeftPren{}\opRightPren{}} 
returns the class of all characters
\smath{ch} for which
\smath{\mbox{\bf alphabetic?}\opLeftPren{}ch\opRightPren{}} is \smath{true}.
  \newitem
\smath{\mbox{\bf alphabetic?}\opLeftPren{}ch\opRightPren{}} 
tests if \smath{ch} is an alphabetic
character a$\ldots$z, A$\ldots$B.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{alphanumeric}}\opLeftPren{}\opRightPren{}%
\opand \mbox{\axiomFun{alphanumeric?}}\opLeftPren{}
{\it character}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Character}
{\smath{\mbox{\bf alphanumeric}\opLeftPren{}\opRightPren{}} returns 
the class of all characters \smath{ch} for which
\smath{\mbox{\bf alphanumeric?}\opLeftPren{}ch\opRightPren{}} is \smath{true}.
  \newitem
  \smath{\mbox{\bf alphanumeric?}\opLeftPren{}ch\opRightPren{}} 
tests if \smath{ch} is either an alphabetic character a$\ldots$z, 
A$\ldots$B or digit 0$\ldots$9.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{alternating}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{ I -> SPOL RN}{}{}
  {\smath{\mbox{\bf alternating}\opLeftPren{}n\opRightPren{}} 
is the cycle index of the
   alternating group of degree \smath{n}.
See \axiomType{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{alternatingGroup}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(List(Integer))->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf alternatingGroup}\opLeftPren{}li\opRightPren{}} 
constructs the alternating group
acting on the integers in the list \smath{li}.
If \smath{n} is odd, the generators are in general the
\smath{(n-2)}-cycle \smath{(li.3, \ldots, li.n)} and the
3-cycle \smath{(li.1, li.2, li.3)}.
If \smath{n} is even, the generators are the product of the 2-cycle
\smath{(li.1, li.2)} with \smath{(n-2)}-cycle
\smath{(li.3, \ldots, li.n)} and the 3-cycle \smath{(li.1, li.2, li.3)}.
Duplicates in the list will be removed.
\newitem\smath{\mbox{\bf alternatingGroup}\opLeftPren{}n\opRightPren{}} 
constructs the alternating
group $A_n$ acting on the integers \smath{1, \ldots, n}.
If \smath{n} is odd, the generators are in general the
\smath{(n-2)}-cycle \smath{(3, \ldots, n)} and the 3-cycle \smath{(1, 2, 3)}.
If \smath{n} is even, the generators are the product of the 2-cycle
\smath{(1, 2)} with \smath{(n-2)}-cycle \smath{(3, \ldots, n)} and the 3-cycle
\smath{(1, 2, 3)} if \smath{n} is even.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{alternative?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf alternative?}\opLeftPren{}\opRightPren{}\$F} 
tests if $2 \mbox{\bf associator}(a, a, b) = 0 =
2 \mbox{\bf associator}(a, b, b)$ for all \smath{a}, \smath{b} in the algebra
\smath{F}.
Note: in general,
\smath{2 a=0} does not necessarily imply \smath{a=0}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{and}}\opLeftPren{}
{\it boolean}, \allowbreak{}{\it  boolean}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BitAggregate}
{\smath{x \and y} returns the logical {\it and} of two
\axiomType{BitAggregate}s \smath{x} and \smath{y}.
   \newitem
\smath{b_1 \and b_2} returns the logical {\it and} of Boolean
\smath{b_1} and \smath{b_2}.
\newitem\smath{si_1 \and si_2} returns the bit-by-bit logical {\it
and} of the small integers \smath{si_1} and \smath{si_2}.
\newitem See also \axiomType{OutputForm}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{approximants}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(Fraction(R))}{ContinuedFraction}
{\smath{\mbox{\bf approximants}\opLeftPren{}cf\opRightPren{}} 
returns the stream of approximants of the
continued fraction \smath{cf}.
If the continued fraction is finite, then the stream will be
infinite and periodic with period 1.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{approximate}}\opLeftPren{}
{\it series}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, Expon)->Coef}{UnivariatePowerSeriesCategory}
{\smath{\mbox{\bf approximate}\opLeftPren{}s, 
\allowbreak{} r\opRightPren{}} returns a truncated power series as an
expression in the coefficient domain of the power series.
For example, if \smath{R} is \axiomType{Fraction Polynomial Integer}
and \smath{s} is a series over \smath{R}, then approximate(s, r)
returns the power series \smath{s} truncated after the exponent
\smath{r} term.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{approximate}}\opLeftPren{}
{\it pAdicInteger}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->Integer}{PAdicIntegerCategory}
{\smath{\mbox{\bf approximate}\opLeftPren{}x, 
\allowbreak{} n\opRightPren{}}, \smath{x} a p-adic integer, returns an
integer \smath{y} such that \smath{y = x \mod p^n} when \smath{n}
is positive, and 0 otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{approxNthRoot}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(I, NonNegativeInteger)->I}{IntegerRoots}
{\smath{\mbox{\bf approxNthRoot}\opLeftPren{}n, 
\allowbreak{} p\opRightPren{}} returns an integer approximation
\smath{i} to \smath{n^{1/p}} such that \smath{-1 < i - n^{1/p} <
1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{approxSqrt}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{2}{(I, NonNegativeInteger)->I}{IntegerRoots}
{\smath{\mbox{\bf approxSqrt}\opLeftPren{}n\opRightPren{}} returns an 
integer approximation \smath{i}
to \smath{\sqrt(n)} such that \smath{-1 < i - \sqrt(n) < 1}.
A variable precision Newton iteration is used with running time
\smath{O( \log(n)^2 )}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{areEquivalent?}}\opLeftPren{}{\it listOfMatrices}, 
\allowbreak{}{\it  listOfMatrices}\allowbreak $\,[$ , \allowbreak{}
{\it  randomElements?}, \allowbreak{}{\it  numberOfTries}$]$\opRightPren{}%
}%
}%
{4}{(List(Matrix(R)), List(Matrix(R)), Boolean, Integer)->
Matrix(R)}{RepresentationPackage2}
{\smath{\mbox{\bf areEquivalent?}\opLeftPren{}lM, 
\allowbreak{} lM', \allowbreak{} b, \allowbreak{} numberOfTries\opRightPren{}} tests whether the
two lists of matrices, assumed of the same square shape, can be
simultaneously conjugated by a non-singular matrix.
If these matrices represent the same group generators, the
representations are equivalent.
The algorithm tries \smath{numberOfTries} times to create elements
in the generated algebras in the same fashion.
For details, consult HyperDoc.
  \newitem
  \smath{\mbox{\bf areEquivalent?}\opLeftPren{}aG0, 
\allowbreak{} aG1, \allowbreak{} numberOfTries\opRightPren{}} calls 
\smath{\mbox{\bf areEquivalent?}\opLeftPren{}aG0, \allowbreak{} aG1, 
\allowbreak{} true, \allowbreak{} 25\opRightPren{}}.
  \newitem
  \smath{\mbox{\bf areEquivalent?}\opLeftPren{}aG0, 
\allowbreak{} aG1\opRightPren{}} calls 
\smath{\mbox{\bf areEquivalent?}\opLeftPren{}aG0, 
\allowbreak{} aG1, \allowbreak{} true, \allowbreak{} 25\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{argscript}}\opLeftPren{}
{\it symbol}, \allowbreak{}{\it  listOfOutputForms}\opRightPren{}%
}%
}%
{2}{(\$, List(OutputForm))->\$}{Symbol}
{\smath{\mbox{\bf argscript}\opLeftPren{}f, 
\allowbreak{} [o_1, \allowbreak{} \ldots, o_n]\opRightPren{}} returns a new symbol 
with \smath{f} with scripts
\smath{o_1, \ldots, o_n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{argument}}\opLeftPren{}
{\it complexExpression}\opRightPren{}%
}%
}%
{1}{(\$)->R}{ComplexCategory}
{\smath{\mbox{\bf argument}\opLeftPren{}c\opRightPren{}} 
returns the angle made by complex expression \smath{c} with
the positive real axis.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{arity}}\opLeftPren{}
{\it basicOperator}\opRightPren{}%
}%
}%
{1}{(\$)->Union(NonNegativeInteger, \mbox{\tt "failed"})}{BasicOperator}
{\smath{\mbox{\bf arity}\opLeftPren{}op\opRightPren{}} 
returns \smath{n} if \smath{op} is
\smath{n}-ary, and \mbox{\tt "failed"} if \smath{op} has arbitrary arity.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{asec}}\opLeftPren{}
{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{asecIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.}
\newitem\smath{\mbox{\bf asec}\opLeftPren{}x\opRightPren{}} 
returns the arcsecant of \smath{x}.
\newitem\smath{\mbox{\bf asecIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf asec}\opLeftPren{}x\opRightPren{}} if possible,
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{asech}}\opLeftPren{}
{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{asechIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.}
\newitem
\smath{\mbox{\bf asech}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic arcsecant of \smath{x}.
\newitem
\smath{\mbox{\bf asechIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf asech}\opLeftPren{}x\opRightPren{}} if possible, and
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{asin}}\opLeftPren{}
{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{asinIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.
}
\newitem\smath{\mbox{\bf asin}\opLeftPren{}x\opRightPren{}} 
returns the arcsine of \smath{x}.
\newitem\smath{\mbox{\bf asinIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf asin}\opLeftPren{}x\opRightPren{}} if possible,
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{asinh}}\opLeftPren{}
{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{asinhIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.
}
\newitem\smath{\mbox{\bf asinh}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic arcsine of
\smath{x}.
\newitem\smath{\mbox{\bf asinhIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf asinh}\opLeftPren{}x\opRightPren{}} if
possible, and \mbox{\tt "failed"} otherwise.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{assign}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
  {\smath{\mbox{\bf assign}\opLeftPren{}f, \allowbreak{} g\opRightPren{}} 
creates an \axiomType{OutputForm} object
for the assignment \smath{f {\tt :=} g}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{associates?}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{IntegralDomain}
{\smath{\mbox{\bf associates?}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
tests whether \smath{x} and \smath{y} are associates, that is, that
\smath{x} and \smath{y} differ by a unit factor.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{associative?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf associative?}\opLeftPren{}\opRightPren{}\$F} tests 
if multiplication in \smath{F} is associative, where
\smath{F} is a \axiomType{FiniteRankNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{associatorDependence}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(Vector(R))}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf associatorDependence}\opLeftPren{}\opRightPren{}\$F} 
computes associator identities for
\smath{F}. \consultType{FiniteRankNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{associator}}\opLeftPren{}{\it element}, 
\allowbreak{}{\it  element}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{3}{(\$, \$, \$)->\$}{NonAssociativeRng}
  {\smath{\mbox{\bf associator}\opLeftPren{}a, \allowbreak{} b, 
\allowbreak{} c\opRightPren{}} returns \smath{(ab)c-a(bc)},
where \smath{a}, \smath{b}, and \smath{c} are all members of a domain of
category \axiomType{NonAssociateRng}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{assoc}}\opLeftPren{}{\it element}, 
\allowbreak{}{\it  associationList}\opRightPren{}%
}%
}%
{2}{(Key, \$)->Union(Record(key:Key, entry:Entry), 
\mbox{\tt "failed"})}{AssociationListAggregate}
{\smath{\mbox{\bf assoc}\opLeftPren{}k, 
\allowbreak{} al\opRightPren{}} returns the element \smath{x} in the
\axiomType{AssociationList} \smath{al}
stored under key \smath{k}, or \mbox{\tt "failed"} if no such element exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{atan}}\opLeftPren{}
{\it expression\opt{, phase}}\opRightPren{}%
 \opand \mbox{\axiomFun{atanIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ArcTrigonometricFunctionCategory}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.}
\newitem\smath{\mbox{\bf atan}\opLeftPren{}x\opRightPren{}} returns the 
arctangent of \smath{x}.
\newitem\smath{\mbox{\bf atan}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
computes the arc tangent from \smath{x}
with phase \smath{y}.
\newitem\smath{\mbox{\bf atanIfCan}\opLeftPren{}x\opRightPren{}} 
returns the \smath{\mbox{\bf atan}\opLeftPren{}x\opRightPren{}} if
possible, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{atanh}}\opLeftPren{}{\it expression}\opRightPren{}%
\opand \mbox{\axiomFun{atanhIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, \mbox{\tt "failed"})}{PartialTranscendentalFunctions}
{\opkey{Argument \smath{x} can be a \axiomType{Complex},
\axiomType{Float}, \axiomType{DoubleFloat}, or
\axiomType{Expression} value or a series.}
\newitem\smath{\mbox{\bf atanh}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic arctangent of
\smath{x}.
\newitem\smath{\mbox{\bf atanhIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf atanh}\opLeftPren{}x\opRightPren{}} if
possible, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{atom?}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}
{\smath{\mbox{\bf atom?}\opLeftPren{}s\opRightPren{}} tests if \smath{x} is
atomic, where \smath{x} is an \axiomType{SExpression} or 
\axiomType{OutputForm}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{antiCommutator}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{NonAssociativeRng}
  {\smath{\mbox{\bf antiCommutator}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} returns \smath{x y + y x},
where \smath{x} and \smath{y} are elements of a non-associative ring,
possibly without identity. \seeType{NonAssociativeRng}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{antisymmetric?}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{MatrixCategory}
{\smath{\mbox{\bf antisymmetric?}\opLeftPren{}m\opRightPren{}} 
tests if the matrix \smath{m} is square
and antisymmetric, that is, \smath{m_{i, j} = -m_{j, i}} for all
\smath{i} and \smath{j}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{antisymmetricTensors}}\opLeftPren{}
{\it matrices}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), PositiveInteger)->List(Matrix(R))}
{RepresentationPackage1}
  {\smath{\mbox{\bf antisymmetricTensors}\opLeftPren{}A, 
\allowbreak{} n\opRightPren{}},
where \smath{A} is an \smath{m} by \smath{m} matrix,
returns a matrix obtained by applying to \smath{A}
the irreducible, polynomial representation of the
general linear group \smath{GL_m} corresponding to the
partition \smath{(1, 1, \ldots, 1, 0, 0, \ldots, 0)} of \smath{n}.
A call to \spadfun{error} occurs if \smath{n} is greater than \smath{m}.
Note: this corresponds to the symmetrization of the representation
with the sign
representation of the symmetric group \smath{S_n}.
The carrier spaces of the representation are the antisymmetric
tensors of the \smath{n}-fold tensor product.
  \newitem\smath{\mbox{\bf antisymmetricTensors}\opLeftPren{}lA, 
\allowbreak{} n\opRightPren{}},
where \smath{lA} is a list of \smath{m} by \smath{m} matrices,
similarly applies the representation of \smath{GL_m} to each matrix \smath{A}
of \smath{lA}, returning a list of matrices.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{any?}}\opLeftPren{}{\it predicate}, 
\allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->Boolean}{HomogeneousAggregate}
{\smath{\mbox{\bf any?}\opLeftPren{}pred, \allowbreak{} a\opRightPren{}} 
tests if predicate \smath{\mbox{\bf pred}\opLeftPren{}x\opRightPren{}} 
is \smath{true} for any element \smath{x} of aggregate \smath{a}. 
Note: for collections, \code{any?(p, u) = reduce(or, map(p, u), false, true)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{any}}\opLeftPren{}{\it type}, \allowbreak{}
{\it  object}\opRightPren{}%
}%
}%
{2}{(SExpression, None)->\$}{Any}
{\smath{\mbox{\bf any}\opLeftPren{}type, \allowbreak{} object\opRightPren{}} 
is a technical function for creating an \smath{object} of \axiomType{Any}. 
Argument \smath{type} is a \spadgloss{LISP} form for the \smath{type} 
of \smath{object}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{append}}\opLeftPren{}{\it list}, \allowbreak{}
{\it  list}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{List}
{\smath{\mbox{\bf append}\opLeftPren{}l_1, \allowbreak{} l_2\opRightPren{}} 
appends the elements of list \smath{l_1}
onto the front of
list \smath{l_2}.
See also \spadfun{concat}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{axesColorDefault}}\opLeftPren{}
{\it \opt{palette}}\opRightPren{}%
}%
}%
{0}{()->Palette}{ViewDefaultsPackage}
{\smath{\mbox{\bf axesColorDefault}\opLeftPren{}p\opRightPren{}} sets 
the default color of the axes in a \twodim{} viewport to the palette \smath{p}.
  \newitem
  \smath{\mbox{\bf axesColorDefault}\opLeftPren{}\opRightPren{}} 
returns the default color of the axes in a \twodim{} viewport.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{back}}\opLeftPren{}{\it queue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{QueueAggregate}
{\smath{\mbox{\bf back}\opLeftPren{}q\opRightPren{}} 
returns the element at the back of the queue, or calls
\spadfun{error} if \smath{q} is empty.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bag}}\opLeftPren{}{\it \opt{bag}}\opRightPren{}%
}%
}%
{0}{()->\$}{BagAggregate}
{\smath{\mbox{\bf bag}\opLeftPren{}\colx{x}{y}{z}\opRightPren{}} 
creates a bag with elements \smath{x}, \smath{y}, $\ldots$, \smath{z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{balancedBinaryTree}}\opLeftPren{}
{\it nonNegativeInteger}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{0}{()->\$}{BagAggregate}
 {\smath{\mbox{\bf balancedBinaryTree}\opLeftPren{}n, 
\allowbreak{} s\opRightPren{}} creates a balanced binary tree with
\smath{n} nodes, each with value \smath{s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{base}}\opLeftPren{}{\it group}\opRightPren{}%
}%
}%
{0}{()->PositiveInteger}{FloatingPointSystem}
{\smath{\mbox{\bf base}\opLeftPren{}gp\opRightPren{}} returns a 
base for the group {\it gp}. \consultType{PermutationGroup}
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basis}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Vector(\$)}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf basis}\opLeftPren{}\opRightPren{}\$R} returns a 
fixed basis of \smath{R}
or a subspace of \smath{R}.
See \axiomType{FiniteAlgebraicExtensionField},
\axiomType{FramedAlgebra},
\axiomType{FramedNonAssociativeAlgebra} using HyperDoc for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basisOfCenter}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(A)}{AlgebraPackage}
{\smath{\mbox{\bf basisOfCenter}\opLeftPren{}\opRightPren{}\$R} returns a 
basis of the space of all
\smath{x} in \smath{R} satisfying \smath{\mbox{\bf commutator}\opLeftPren{}x, 
a) = 0} and
\smath{\mbox{\bf associator}\opLeftPren{}x, \allowbreak{} a, \allowbreak{} b
\opRightPren{}} = \smath{\mbox{\bf associator}\opLeftPren{}a, \allowbreak{} x, 
\allowbreak{} b\opRightPren{}} = \smath{\mbox{\bf associator}\opLeftPren{}a, 
\allowbreak{} b, \allowbreak{} x\opRightPren{}} =
0 for all \smath{a}, \smath{b} in \smath{R}.
Domain \smath{R} is a domain of category
\axiomType{FramedNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basisOfCentroid}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(Matrix(R))}{AlgebraPackage}
{\smath{\mbox{\bf basisOfCentroid}\opLeftPren{}\opRightPren{}\$R} 
returns a basis of the centroid of
\smath{R}, that is, the endomorphism ring of \smath{R} considered as
\smath{(R, R)}-bimodule.
Domain \smath{R} is a domain of category
\axiomType{FramedNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basisOfCommutingElements}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(A)}{AlgebraPackage}
{\smath{\mbox{\bf basisOfCommutingElements}\opLeftPren{}\opRightPren{}\$R} 
returns a basis of the space
of all \smath{x} of \smath{R} satisfying 
\smath{\mbox{\bf commutator}\opLeftPren{}x, \allowbreak{} a\opRightPren{}} = 0
for all \smath{a} in \smath{R}.
Domain \smath{R} is a domain of category
\axiomType{FramedNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basisOfLeftAnnihilator}}\opLeftPren{}
{\it element}\opRightPren{}%
 \opand \mbox{\axiomFun{basisOfRightAnnihilator}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(A)->List(A)}{AlgebraPackage}
{\opkey{These operations return a basis of the space of all
\smath{x} in \smath{R} of category
\axiomType{FramedNonAssociativeAlgebra}, satisfying}
\begin{simpleList}
\item\smath{\mbox{\bf basisOfLeftAnnihilator}\opLeftPren{}a\opRightPren{}}:
 \smath{0 = xa}.
\item\smath{\mbox{\bf basisOfRightAnnihilator}\opLeftPren{}a\opRightPren{}}:
  \smath{0 = ax}.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basisOfNucleus}}\opLeftPren{}\opRightPren{}%
 \optand \mbox{\axiomFun{basisOfLeftNucleus}}\opLeftPren{}\opRightPren{}%
 \optand \mbox{\axiomFun{basisOfMiddleNucleus}}\opLeftPren{}\opRightPren{}%
 \opand \mbox{\axiomFun{basisOfRightNucleus}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(A)}{AlgebraPackage}
{\opkey{Each operation returns a basis of the space of all
\smath{x} of \smath{R}, a domain of category
\axiomType{FramedNonAssociativeAlgebra}, satisfying for all
\smath{a} and \smath{b}:}
\begin{simpleList}
\item \smath{\mbox{\bf basisOfNucleus}\opLeftPren{}\opRightPren{}\$R}:
\smath{\mbox{\bf associator}\opLeftPren{}x, \allowbreak{} a, 
\allowbreak{} b\opRightPren{}} = \smath{\mbox{\bf associator}\opLeftPren{}a, 
\allowbreak{} x, \allowbreak{} b\opRightPren{}}
= \smath{\mbox{\bf associator}\opLeftPren{}a, \allowbreak{} b, 
\allowbreak{} x\opRightPren{}} = 0;
\item \smath{\mbox{\bf basisOfLeftNucleus}\opLeftPren{}\opRightPren{}\$R}:  
\smath{\mbox{\bf associator}\opLeftPren{}x, \allowbreak{} a, 
\allowbreak{} b\opRightPren{}} = 0;
\item \smath{\mbox{\bf basisOfMiddleNucleus}\opLeftPren{}\opRightPren{}\$R}: 
\smath{\mbox{\bf associator}\opLeftPren{}a, \allowbreak{} x, 
\allowbreak{} b\opRightPren{}} = 0;
\item \smath{\mbox{\bf basisOfRightNucleus}\opLeftPren{}\opRightPren{}\$R}:  
\smath{\mbox{\bf associator}\opLeftPren{}a, 
\allowbreak{} b, \allowbreak{} x\opRightPren{}} = 0.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{basisOfLeftNucloid}}\opLeftPren{}\opRightPren{}%
 \opand \mbox{\axiomFun{basisOfRightNucloid}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(Matrix(R))}{AlgebraPackage}
{\opkey{Each operation returns a basis of the space of
endomorphisms of \smath{R}, a domain of category
\axiomType{FramedNonAssociativeAlgebra}, considered as:}
\begin{simpleList}
  \item\smath{\mbox{\bf basisOfLeftNucloid}\opLeftPren{}\opRightPren{}}: 
a right module.
  \item\smath{\mbox{\bf basisOfRightNucloid}\opLeftPren{}\opRightPren{}}: 
a left module.
\end{simpleList}
Note: if \smath{R} has a unit, the left and right nucloid coincide with
the left and right nucleus.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{belong?}}\opLeftPren{}{\it operator}\opRightPren{}%
}%
}%
{1}{(BasicOperator)->Boolean}{ExpressionSpace}
{\smath{\mbox{\bf belong?}\opLeftPren{}op\opRightPren{}\$R} tests 
if \smath{op} is known as an
operator to \smath{R}.
For example, \smath{R} is an \axiomType{Expression} domain or
\axiomType{AlgebraicNumber}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bernoulli}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->Fraction(Integer)}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf bernoulli}\opLeftPren{}n\opRightPren{}} returns the 
\eth{\smath{n}} Bernoulli
number, that is, \smath{B(n, 0)} where \smath{B(n, x)} is the
\eth{\smath{n}} Bernoulli polynomial.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{besselI}}\opLeftPren{}{\it complexDoubleFloat}, 
\allowbreak{}{\it  complexDoubleFloat}\opRightPren{}%
\optand \mbox{\axiomFun{besselJ}}\opLeftPren{}{\it complexDoubleFloat}, 
\allowbreak{}{\it  complexDoubleFloat}\opRightPren{}%
\optand \mbox{\axiomFun{besselK}}\opLeftPren{}{\it complexDoubleFloat}, 
\allowbreak{}{\it  complexDoubleFloat}\opRightPren{}%
\opand \mbox{\axiomFun{besselY}}\opLeftPren{}{\it complexDoubleFloat}, 
\allowbreak{}{\it  complexDoubleFloat}\opRightPren{}%
}%
}%
{2}{(Complex(DoubleFloat), 
Complex(DoubleFloat))->Complex(DoubleFloat)}{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf besselI}\opLeftPren{}v, 
\allowbreak{} x\opRightPren{}} is the modified Bessel function of the first
kind, \smath{I(v, x)}, satisfying the differential equation
\smath{x^2 {w''(x)} + x w'(x) - (x^2+v^2)w(x) = 0}.
\bigitem\smath{\mbox{\bf besselJ}\opLeftPren{}v, 
\allowbreak{} x\opRightPren{}} is the Bessel function of the second
kind, \smath{J(v, x)},
satisfying the differential equation \smath{x^2 {w''(x)} + x w'(x)
+ (x^2-v^2)w(x) = 0}.
\bigitem\smath{\mbox{\bf besselK}\opLeftPren{}v, 
\allowbreak{} x\opRightPren{}} is the modified Bessel function of
the first kind, \smath{K(v, x)},
satisfying the differential equation \smath{x^2 {w''(x)} + x w'(x)
- (x^2+v^2)w(x) = 0}.
Note: The default implementation uses the relation
\smath{K(v, x) = \pi/2(I(-v, x) - I(v, x))/\sin(v \pi)}
so is not valid for integer values of \smath{v}.
\bigitem\smath{\mbox{\bf besselY}\opLeftPren{}v, 
\allowbreak{} x\opRightPren{}} is the Bessel function of the second
kind, \smath{Y(v, x)},
satisfying the differential equation \smath{x^2 {w''(x)} + x w'(x)
+ (x^2-v^2)w(x) = 0}.
Note: The default implementation uses the relation \smath{Y(v, x) =
(J(v, x) \cos(v \pi) - J(-v, x))/\sin(v \pi)} so is not valid for
integer values of \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{Beta}}\opLeftPren{}{\it complexDoubleFloat}, 
\allowbreak{}{\it  complexDoubleFloat}\opRightPren{}%
}%
}%
{2}{(Complex(DoubleFloat), 
Complex(DoubleFloat))->Complex(DoubleFloat)}{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf Beta}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} 
is the Euler beta function, \smath{B(x, y)}, defined by
\smath{\mbox{\bf Beta}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} $\int_0^1{t^{x-1}(1-t)^{y-1} dt}$.
Note: this function is defined by
\smath{\mbox{\bf Beta}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} $= 
{{\Gamma(x)\Gamma(y)} \over {\Gamma(x + y)}}$.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{binaryTournament}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{1}{(Fraction(Integer))->\$}{BinaryExpansion}
{\smath{\mbox{\bf binaryTournament}\opLeftPren{}ls\opRightPren{}} creates a
\axiomType{BinaryTournament} tree with the
      elements of \smath{ls} as values at the nodes.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{binaryTree}}\opLeftPren{}{\it value}\opRightPren{}%
}%
}%
{1}{(Fraction(Integer))->\$}{BinaryExpansion}
  {\smath{\mbox{\bf binaryTree}\opLeftPren{}x\opRightPren{}} creates 
a binary tree
consisting of one node for which the \spadfunFrom{value}{BinaryTree} 
is \smath{x} and
the \spadfun{left} and \spadfun{right} subtrees are empty.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{binary}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{1}{(Fraction(Integer))->\$}{BinaryExpansion}
{\smath{\mbox{\bf binary}\opLeftPren{}rn\opRightPren{}} 
converts rational number \smath{rn} to a binary expansion.
 \newitem
 \smath{\mbox{\bf binary}\opLeftPren{}op, 
\allowbreak{} [a_1, \allowbreak{} \ldots, a_n]\opRightPren{}} 
returns the input form
corresponding to  \smath{a_1 {\rm op} \ldots op a_n}, where
\smath{op} and the \smath{a_i}'s are of type \axiomType{InputForm}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{binomial}}\opLeftPren{}
{\it integerNumber}, \allowbreak{}{\it  integerNumber}\opRightPren{}%
}%
}%
{2}{(I, I)->I}{IntegerCombinatoricFunctions}
{\smath{\mbox{\bf binomial}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} returns the binomial coefficient
\smath{C(x, y) = x!/(y!
(x-y)!)}, where \texht{$x \geq y \geq 0$}{x >= y >= 0},
the number of combinations of \smath{x} objects taken
\smath{y} at a time.
Arguments \smath{x} and \smath{y} can come from any
\axiomType{Expression} or \axiomType{IntegerNumberSystem} domain.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bipolar}}\opLeftPren{}{\it x}\opRightPren{}%
 \opand \mbox{\axiomFun{bipolarCylindrical}}
\opLeftPren{}{\it x}\opRightPren{}%
}%
}%
{1}{(R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf bipolar}\opLeftPren{}a\opRightPren{}} 
returns a function for transforming bipolar
coordinates to
Cartesian coordinates; this function maps the
point \smath{(u, v)} to \smath{(x = a \sinh(v)/(\cosh(v)-\cos(u)),
y = a \sin(u)/(\cosh(v)-\cos(u)))}.
  \newitem\smath{\mbox{\bf bipolarCylindrical}
\opLeftPren{}a\opRightPren{}} returns a function for transforming
bipolar cylindrical coordinates to Cartesian coordinates; this function
maps the point \smath{(u, v, z)} to
\smath{(x = a \sinh(v)/(\cosh(v)-\cos(u)), y = a
\sin(u)/(\cosh(v)-\cos(u)), z)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{biRank}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(A)->NonNegativeInteger}{AlgebraPackage}
  {\smath{\mbox{\bf biRank}\opLeftPren{}x\opRightPren{}\$R},
where \smath{R} is a domain of
category \axiomType{FramedNonAssociativeAlgebra},
returns the number of linearly independent elements
among \smath{x}, \smath{x b_i}, \smath{b_i x}, 
\smath{b_i x b_j}, \smath{i, j=1, \ldots, n},
where \smath{b=[b_1, \ldots, b_n]} is the fixed basis for \smath{R}.
Note: if \smath{R} has a unit, then
\spadfunFrom{doubleRank}{AlgebraPackage},
\spadfunFrom{weakBiRank}{AlgebraPackage}
and \spadfunFrom{biRank}{AlgebraPackage} coincide.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bit?}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{IntegerNumberSystem}
{\smath{\mbox{\bf bit?}\opLeftPren{}i, 
\allowbreak{} n\opRightPren{}} tests if the 
\eth{\smath{n}} bit of \smath{i} is a 1.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bits}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->PositiveInteger}{FloatingPointSystem}
{\smath{\mbox{\bf bits}\opLeftPren{}\opRightPren{}} 
returns the precision of floats in
bits. Also see \spadfun{precision}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{blankSeparate}}\opLeftPren{}
{\it listOfOutputForms}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf blankSeparate}\opLeftPren{}lo\opRightPren{}},
where {\it lo} is a list of objects of type \axiomType{OutputForm}
(normally unexposed),
returns a single output form consisting of the elements
of {\it lo} separated by blanks.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{blue}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Color}{\smath{\mbox{\bf blue}\opLeftPren{}\opRightPren{}} 
returns the
position of the blue hue from total hues.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bottom!}}\opLeftPren{}{\it dequeue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{DequeueAggregate}
{\smath{\mbox{\bf bottom!}\opLeftPren{}q\opRightPren{}} removes 
then returns the element at the bottom
(back) of the dequeue q.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{box}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(List(\$))->\$}{ExpressionSpace}
{\smath{\mbox{\bf box}\opLeftPren{}e\opRightPren{}}, where \smath{e} 
is an expression, returns
\smath{e} with a box around it that prevents \smath{e} from being
evaluated when operators are applied to it.
For example, \smath{\mbox{\bf log}\opLeftPren{}1\opRightPren{}} 
returns \smath{0}, but
\smath{\mbox{\bf log}\opLeftPren{}{\mbox{\bf box}}(1)\opRightPren{}} 
returns the formal kernel
\smath{\mbox{\bf log}\opLeftPren{}1\opRightPren{}}.
\newitem
\smath{\mbox{\bf box}\opLeftPren{}f_1, \allowbreak{} \ldots, f_n
\opRightPren{}}, where the \smath{f_i} are
expressions, returns \smath{(f_1, \ldots, f_n)} with a box around
them that prevents the \smath{f_i} from being evaluated when
operators are applied to them, and makes them applicable to a
unary operator.
For example, \smath{\mbox{\bf atan}\opLeftPren{}{\mbox {\bf box}} 
[x, \allowbreak{} 2]\opRightPren{}} returns the
formal kernel \smath{\mbox{\bf atan}\opLeftPren{}x, 
\allowbreak{} 2\opRightPren{}}.
\newitem\smath{\mbox{\bf box}\opLeftPren{}o\opRightPren{}}, 
where \smath{o} is an object of type
\axiomType{OutputForm} (normally unexposed), returns an output
form enclosing \smath{o} in a box.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{brace}}\opLeftPren{}{\it outputForm}\opRightPren{}%
}%
}%
{}{}{}
  {\smath{\mbox{\bf brace}\opLeftPren{}o\opRightPren{}},
where \smath{o} is an object of type \axiomType{OutputForm}
(normally unexposed),
returns an output form enclosing \smath{o} in braces.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bracket}}\opLeftPren{}{\it outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf bracket}\opLeftPren{}o\opRightPren{}}, 
where \smath{o} is an object of type
\axiomType{OutputForm} (normally unexposed), returns an output
form enclosing \smath{o} in brackets.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{branchPoint}}\opLeftPren{}
{\it element}\opRightPren{}%
 \opand \mbox{\axiomFun{branchPointAtInfinity?}}
\opLeftPren{}\opRightPren{}%
}%
}%
{1}{(F)->Boolean}{FunctionFieldCategory}
{\smath{\mbox{\bf branchPoint?}\opLeftPren{}a\opRightPren{}\$F} 
tests if \smath{x = a} is a branch
point of the algebraic function field \smath{F}.
\newitem\smath{\mbox{\bf branchPointAtInfinity?}
\opLeftPren{}\opRightPren{}\$F} tests if the
algebraic function field \smath{F} has a branch point at infinity.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{bright}}\opLeftPren{}{\it color}\opRightPren{}%
}%
}%
{1}{(Color)->\$}{Palette}
{\smath{\mbox{\bf bright}\opLeftPren{}c\opRightPren{}} sets the shade 
of a hue, \smath{c}, above dim
but below pastel.
\newitem
\smath{\mbox{\bf bright}\opLeftPren{}ls\opRightPren{}} sets the font 
property of a list of
strings \smath{ls} to bold-face type.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cap}}\opLeftPren{}{\it symmetricPolynomial}, 
\allowbreak{}{\it  symmetricPolynomial}\opRightPren{}%
}%
}%
{ (SPOL RN, SPOL RN) -> RN}{}{}
{\smath{\mbox{\bf cap}\opLeftPren{}s_1, 
\allowbreak{} s_2\opRightPren{}}, introduced by Redfield, is the scalar
product of two cycle indices, where the \smath{s_i} are
\spadtype{SymmetricPolynomial}s with rational number coefficients.
See also \spadfun{cup}. See \spadtype{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cardinality}}\opLeftPren{}
{\it finiteSetAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{FiniteSetAggregate}
{\smath{\mbox{\bf cardinality}\opLeftPren{}u\opRightPren{}} 
returns the number of elements of
\smath{u}.
Note: \code{cardinality(u) = \#u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{car}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{SExpressionCategory}
{\smath{\mbox{\bf car}\opLeftPren{}se\opRightPren{}} 
returns \smath{a_1} when \smath{se} is the
\axiomType{SExpression} object \smath{(a_1, \ldots, a_n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cdr}}\opLeftPren{}
{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{SExpressionCategory}
{\smath{\mbox{\bf cdr}\opLeftPren{}se\opRightPren{}} 
returns \smath{(a_2, \ldots, a_n)} when \smath{se}
is the \axiomType{SExpression} object \smath{(a_1, \ldots, a_n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ceiling}}\opLeftPren{}
{\it floatOrRationalNumber}\opRightPren{}%
}%
}%
{1}{(\$)->D}{QuotientFieldCategory}
{\opkey {Argument \smath{x} is a floating point number or fraction
of numbers.}
\newitem\smath{\mbox{\bf ceiling}\opLeftPren{}x\opRightPren{}} 
returns the smallest integral element
above \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{center}}\opLeftPren{}{\it stringsOrSeries}
\opRightPren{}%
}%
}%
{1}{(\$)->Coef}{UnivariatePowerSeriesCategory}
{\smath{\mbox{\bf center}\opLeftPren{}s\opRightPren{}} returns the 
point about which the series
\smath{s} is expanded.
\newitem\smath{\mbox{\bf center}\opLeftPren{}ls, \allowbreak{} n, 
\allowbreak{} s\opRightPren{}} takes a list of strings \smath{ls},
and centers them within a list of strings which is \smath{n}
characters long.
The remaining spaces are filled with strings composed of as many
repetitions as possible of the last string parameter \smath{s}.
\newitem\smath{\mbox{\bf center}\opLeftPren{}s_1, \allowbreak{} n, 
\allowbreak{} s_2\opRightPren{}} is equivalent to
\smath{\mbox{\bf center}\opLeftPren{}[ s_1], n, s_2\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{char}}\opLeftPren{}{\it character}\opRightPren{}%
}%
}%
{1}{(Integer)->\$}{Character}
{\smath{\mbox{\bf char}\opLeftPren{}i\opRightPren{}} returns a 
\spadtype{Character} object with
integer code \smath{i}.
Note: {\bf ord(char({\it i})) \rm = \it i}.
\newitem
\smath{\mbox{\bf char}\opLeftPren{}s\opRightPren{}} returns the 
unique character of a string
\smath{s} of length one.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{characteristic}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->NonNegativeInteger}{NaiveRingInternalUseOnly}
{\smath{\mbox{\bf characteristic}\opLeftPren{}\opRightPren{}\$R} 
returns the characteristic of ring
\smath{R}: the smallest positive integer \smath{n} such that
\smath{nx=0} for all \smath{x} in the ring, or zero if no such
\smath{n} exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{characteristicPolynomial}}\opLeftPren{}
{\it matrix\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(\$)->UP}{FiniteRankAlgebra}
{\smath{\mbox{\bf characteristicPolynomial}\opLeftPren{}a\opRightPren{}} 
returns the characteristic
polynomial of the regular representation of \smath{a} with respect
to any basis.
\newitem
\smath{\mbox{\bf characteristicPolynomial}\opLeftPren{}m\opRightPren{}} 
returns the
characteristic polynomial of the matrix \smath{m} expressed as
polynomial with a new symbol as variable.
\newitem
\smath{\mbox{\bf characteristicPolynomial}\opLeftPren{}m, 
\allowbreak{} sy\opRightPren{}} is similar except
that the resulting polynomial has variable \smath{sy}.
\newitem
\smath{\mbox{\bf characteristicPolynomial}\opLeftPren{}m, 
\allowbreak{} r\opRightPren{}}, where \smath{r} is
a member of the coefficient domain of matrix \smath{m}, evaluates
the characteristic polynomial at \smath{r}.
In particular, if \smath{r} is the polynomial \smath{'x}, then it
returns the characteristic polynomial expressed as a polynomial in
\smath{'x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{charClass}}\opLeftPren{}{\it strings}\opRightPren{}%
}%
}%
{1}{(List(Character))->\$}{CharacterClass}
{\smath{\mbox{\bf charClass}\opLeftPren{}s\opRightPren{}} creates 
a character class containing exactly
the characters given in the string \smath{s}.
\newitem
\smath{\mbox{\bf charClass}\opLeftPren{}ls\opRightPren{}} creates 
a character class which contains
exactly the characters given in the list \smath{ls} of strings.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{charthRoot}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Union(\$, "failed")}{PolynomialFactorizationExplicit}
{\smath{\mbox{\bf charthRoot}\opLeftPren{}r\opRightPren{}},
where \smath{r} is an element of domain with \spadfun{characteristic}
$p \not= 0$, returns the \eth{\smath{p}} root of \smath{r}, or 
\mbox{\tt "failed"} if none exists in the domain.
\newitem\smath{\mbox{\bf charthRoot}\opLeftPren{}f\opRightPren{}\$R} 
takes the \eth{\smath{p}} root of finite field element \smath{f},
where \smath{p} is the characteristic of the finite field \smath{R}.
Note: such a root is always defined in finite fields.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{chebyshevT}}\opLeftPren{}{\it positiveInteger}, 
\allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(NonNegativeInteger, R)->R}{OrthogonalPolynomialFunctions}
{\smath{\mbox{\bf chebyshevT}\opLeftPren{}n, \allowbreak{} x\opRightPren{}} 
returns the \eth{\smath{n}} Chebyshev polynomial of the
first kind, \smath{T_n(x)}, defined by
\smath{(1-tx)/(1-2tx+t^2) = \sum\nolimits_{n=0}^\infty {T_n(x)\, t^n}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{children}}\opLeftPren{}
{\it recursiveAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{RecursiveAggregate}
{\smath{\mbox{\bf children}\opLeftPren{}u\opRightPren{}}
returns a list of the children of aggregate \smath{u}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{chineseRemainder}}\opLeftPren{}
{\it listOfElements}, \allowbreak{}{\it  listOfModuli}\opRightPren{}%
\opand \mbox{\axiomFun{chineseRemainder}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  modulus}, \allowbreak{}{\it  integer}, 
\allowbreak{}{\it  modulus}\opRightPren{}%
}%
}%
{4}{(Integer, Integer, Integer, Integer)->Integer}
{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf chineseRemainder}\opLeftPren{}lv, \allowbreak{} lm
\opRightPren{}} where \smath{lv} is a list of
values \smath{[v_1, \ldots, v_n]} and \smath{lm} is a list of moduli
\smath{[m_1, \ldots, m_n]}, returns \smath{m} such that \smath{m =
n_i \bmod p_i}; the \smath{p_i} must be relatively prime.
\newitem\smath{\mbox{\bf chineseRemainder}\opLeftPren{}n_1, 
\allowbreak{} p_1, \allowbreak{} n_2, \allowbreak{} p_2\opRightPren{}} 
is equivalent to
\smath{\mbox{\bf chineseRemainder}\opLeftPren{}[n_1, \allowbreak{} n_2], 
\allowbreak{} [p_1, \allowbreak{} p_2]\opRightPren{}}, where all arguments
are integers.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{clearDenominator}}\opLeftPren{}
{\it fraction}\opRightPren{}%
}%
}%
{1}{(A)->A}{CommonDenominator}
{\smath{\mbox{\bf clearDenominator}\opLeftPren{}\col{q_1}{q_n}\opRightPren{}}
returns \smath{\col{p_1}{p_n}}
such that \smath{q_i = p_i/d} where \smath{d} is a common denominator for 
the \smath{q_i}'s.
\newitem\smath{\mbox{\bf clearDenominator}\opLeftPren{}A\opRightPren{}}, 
where \smath{A} is a matrix of fractions,
returns matrix \smath{B} such that \smath{A = B/d} where \smath{d} is a
common denominator for the elements of \smath{A}.
\newitem\smath{\mbox{\bf clearDenominator}\opLeftPren{}p\opRightPren{}} 
returns polynomial \smath{q} such that \smath{p = q/d} where \smath{d} 
is a common denominator for the coefficients of polynomial \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{clip}}\opLeftPren{}
{\it rangeOrBoolean}\opRightPren{}%
}%
}%
{1}{(Boolean)->\$}{DrawOption}
{\smath{\mbox{\bf clip}\opLeftPren{}b\opRightPren{}} turns 
\twodim{} clipping on if \smath{b} is \smath{true}, and off if \smath{b}
is \smath{false}. \sayOption{clip}{b}
\newitem
\smath{\mbox{\bf clip}\opLeftPren{}[ a..b]\opRightPren{}} 
defines the range for user-defined clipping.
\sayOption{range}{[ a..b]}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{clipPointsDefault}}\opLeftPren{}
{\it \opt{boolean}}\opRightPren{}%
}%
}%
{0}{()->Boolean}{GraphicsDefaults}
{\smath{\mbox{\bf clipPointsDefault}\opLeftPren{}\opRightPren{}} tests if 
automatic clipping is to be done.
\newitem\smath{\mbox{\bf clipPointsDefault}\opLeftPren{}b\opRightPren{}} 
turns on automatic clipping for \smath{b=true}, and
off if \smath{b=false}. \sayOption{clip}{b}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{close}}\opLeftPren{}{\it filename}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{FileCategory}
{\smath{\mbox{\bf close}\opLeftPren{}v\opRightPren{}} 
closes the viewport window of the given \twodim{} or
\threedim{} viewport \smath{v} and terminates the 
corresponding Unix process.
Argument \smath{v} is  a member of domain
\spadtype{TwoDimensionalViewport} or
\spadtype{ThreeDimensionalViewport}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{close!}}\opLeftPren{}{\it filename}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{FileCategory}
{\smath{\mbox{\bf close!}\opLeftPren{}fn\opRightPren{}} 
returns the file \smath{fn} closed to input and output.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{closedCurve?}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{ThreeSpace}
{\smath{\mbox{\bf closedCurve?}\opLeftPren{}sp\opRightPren{}} 
tests if the \spadtype{ThreeSpace} object
\smath{sp} contains a single closed curve component.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{closedCurve}}\opLeftPren{}
{\it listsOfPoints\opt{, listOfPoints}}\opRightPren{}%
}%
}%
{1}{(List(Point(R)))->\$}{ThreeSpace}
{\smath{\mbox{\bf closedCurve}\opLeftPren{}lpt\opRightPren{}} 
returns a \spadtype{ThreeSpace} object
containing a single closed curve described by the list of points 
\smath{lpt} of the form
$[ p_0, p_1, \ldots, p_n, p_0]$.
\newitem\smath{\mbox{\bf closedCurve}\opLeftPren{}sp\opRightPren{}} 
returns a closed curve as a list of points, where
\smath{sp} must be a \spadtype{ThreeSpace} object containing
a single closed curve.
\newitem\smath{\mbox{\bf closedCurve}\opLeftPren{}sp, 
\allowbreak{} lpt\opRightPren{}} returns \spadtype{ThreeSpace} object with
the closed curve denoted by \smath{lpt} added. 
Argument \smath{lpt} is a list of points
of the form $[ p_0, p_1, \ldots, p_n, p_0]$.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coefficient}}\opLeftPren{}
{\it polynomialOrSeries}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, E)->R}{AbelianMonoidRing}
{\smath{\mbox{\bf coefficient}\opLeftPren{}p, \allowbreak{} n\opRightPren{}} 
extracts the coefficient of the monomial with exponent \smath{n} from 
polynomial \smath{p}, or returns zero if exponent is not present.
\newitem\smath{\mbox{\bf coefficient}\opLeftPren{}u, \allowbreak{} x, 
\allowbreak{} n\opRightPren{}} returns the coefficient of variable \smath{x} 
to the power
\smath{n} in \smath{u}, a multivariate polynomial or series.
\newitem\smath{\mbox{\bf coefficient}\opLeftPren{}u, \allowbreak{} 
\col{x_1}{x_k}, \col{n_1}{n_k}\opRightPren{}}
returns the coefficient of \smath{x_1^{n_1} \cdots x_k^{n_k}} in \smath{u},
a multivariate series or polynomial.
\newitem Also defined for domain \spadtype{CliffordAlgebra} and categories
\spadtype{AbelianMonoidRing},
\spadtype{FreeAbelianCategory},
and \spadtype{MonogenicLinearOperator}.
\newitem
{\smath{\mbox{\bf coefficient}\opLeftPren{}s, 
\allowbreak{} n\opRightPren{}} returns the terms of 
total degree \smath{n} of series
\smath{s} as a polynomial.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coefficients}}\opLeftPren{}
{\it polynomialOrStream}\opRightPren{}%
}%
}%
{1}{(\$)->List(R)}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf coefficients}\opLeftPren{}p\opRightPren{}} returns 
the list of non-zero coefficients of polynomial \smath{p}
starting with the coefficient of the maximum degree.
\newitem\smath{\mbox{\bf coefficients}\opLeftPren{}s\opRightPren{}} 
returns a stream of coefficients \smath{[ a_0, a_1, a_2, \ldots]}
for the stream \smath{s}:
\smath{a_0 + a_1 x + a_2 x^2 + \cdots}.
Note: the entries of the stream may be zero.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coerceImages}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{1}{(List(S))->\$}{Permutation}
{\smath{\mbox{\bf coerceImages}\opLeftPren{}ls\opRightPren{}} 
coerces the list \smath{ls} to a
permutation whose image is given by \smath{ls} and whose preimage
is fixed to be \smath{[ 1, \ldots, n]}.
Note:
\smath{\mbox{\bf coerceImages}\opLeftPren{}ls\opRightPren{}}=
\smath{coercePreimagesImages([
1, \ldots, n ], ls)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coerceListOfPairs}}\opLeftPren{}
{\it listOfPairsOfElements}\opRightPren{}%
}%
}%
{1}{(List(List(S)))->\$}{Permutation}
{\smath{\mbox{\bf coerceListOfPairs}\opLeftPren{}lls\opRightPren{}} 
coerces a list of pairs
\smath{lls} to a permutation, or calls
\smath{error} if not consistent, that is, the set of the first
elements coincides with the set of second elements.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coercePreimagesImages}}\opLeftPren{}
{\it listOfListOfElements}\opRightPren{}%
}%
}%
{1}{(List(List(S)))->\$}{Permutation}
{\smath{\mbox{\bf coercePreimagesImages}\opLeftPren{}lls\opRightPren{}} 
coerces the representation
\smath{lls} of a permutation as a list of preimages and images to
a permutation.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coleman}}\opLeftPren{}
{\it listOfIntegers}, \allowbreak{}{\it  listOfIntegers}, \allowbreak{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{3}{(List(Integer), List(Integer), List(Integer))->Matrix(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf coleman}\opLeftPren{}alpha, \allowbreak{} beta, 
\allowbreak{} pi\opRightPren{}} generates the Coleman-matrix of a
certain double coset of the symmetric group given by an
representing element \smath{pi} and \smath{alpha} and
\smath{beta}.
The matrix has nonnegative entries, row sums \smath{alpha} and
column sums \smath{beta}.
\seeDetails{SymmetricGroupCombinatoricFunctions}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{color}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->\$}{Color}
{\smath{\mbox{\bf color}\opLeftPren{}i\opRightPren{}} returns a 
color of the indicated hue \smath{i}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{colorDef}}\opLeftPren{}{\it viewPort}, 
\allowbreak{}{\it  color}, \allowbreak{}{\it  color}\opRightPren{}%
}%
}%
{1}{(Integer)->\$}{Color}
{\smath{\mbox{\bf colorDef}\opLeftPren{}v, 
\allowbreak{} c_1, \allowbreak{} c_2\opRightPren{}} 
sets the range of colors along the colormap so
that the lower end of the colormap is defined by
\smath{c_1} and the top end of the colormap is defined by \smath{c2}
for the given \threedim{} viewport \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{colorFunction}}\opLeftPren{}
{\it smallFloatFunction}\opRightPren{}%
}%
}%
{1}{((DoubleFloat)->DoubleFloat)->\$}{DrawOption}
{\smath{\mbox{\bf colorFunction}\opLeftPren{}fn\opRightPren{}} 
specifies the color for
three-dimensional plots.
Function \smath{fn} can take one to three \spadtype{DoubleFloat}
arguments and always returns a \spadtype{DoubleFloat} value.
If one argument, the color is based upon the \smath{z}-component
of plot.
If two arguments, the color is based on two parameter values.
If three arguments, the color is based on the \smath{x},
\smath{y}, and \smath{z} components.
\sayOption{colorFunction}{fn}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{column}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->Col}{RectangularMatrixCategory}
{\smath{\mbox{\bf column}\opLeftPren{}M, 
\allowbreak{} j\opRightPren{}} returns the \eth{\smath{j}} column of the
matrix or \spadtype{TwoDimensionalArrayCategory} object \smath{M},
or calls \spadfun{error} if the index is outside the proper range.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{commaSeparate}}\opLeftPren{}
{\it listOfOutputForms}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf commaSeparate}\opLeftPren{}lo\opRightPren{}}, 
where \smath{lo} is a list of objects
of type \spadtype{OutputForm} (normally unexposed), returns an
output form which separates the elements of \smath{lo} by commas.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{commonDenominator}}\opLeftPren{}
{\it fraction}\opRightPren{}%
}%
}%
{1}{(A)->R}{CommonDenominator}
{\smath{\mbox{\bf commonDenominator}\opLeftPren{}\col{q_1}{q_n}\opRightPren{}}
returns a common
denominator for the \smath{q_i}'s.
\newitem\smath{\mbox{\bf commonDenominator}\opLeftPren{}A\opRightPren{}}, 
where \smath{A} is a matrix
of fractions, returns a common denominator for the elements of
\smath{A}.
\newitem\smath{\mbox{\bf commonDenominator}\opLeftPren{}p\opRightPren{}} 
returns a common denominator
for the coefficients of polynomial \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{commutative?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf commutative?}\opLeftPren{}\opRightPren{}\$R} 
tests if multiplication in the algebra \smath{R} is commutative.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{commutator}}\opLeftPren{}
{\it groupElement}, \allowbreak{}{\it  groupElement}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{Group}
{\smath{\mbox{\bf commutator}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} computes \smath{\mbox{\bf inv}\opLeftPren{}p) * 
{\mbox {\bf inv}}(q) * p * q} where \smath{p} and
\smath{q} are members of a \spadtype{Group} domain.
\newitem
\smath{\mbox{\bf commutator}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns \smath{ab-ba} where \smath{a}
and \smath{b} are members of a \spadtype{NonAssociativeRing} domain.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{compactFraction}}\opLeftPren{}
{\it partialFraction}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{PartialFraction}
{\smath{\mbox{\bf compactFraction}\opLeftPren{}u\opRightPren{}} 
normalizes the partial fraction \smath{u} to a compact representation 
where it has only one fractional term per prime in the denominator.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{comparison}}\opLeftPren{}
{\it basicOperator}, \allowbreak{}{\it  property}\opRightPren{}%
}%
}%
{2}{(\$, (\$, \$)->Boolean)->\$}{BasicOperator}
{\smath{\mbox{\bf comparison}\opLeftPren{}op, 
\allowbreak{} p\opRightPren{}} attaches \smath{p}
as the \mbox{\tt "\%less?"} property to \smath{op}.
If \smath{op1} and \smath{op2} have the same name, and one of them
has a \mbox{\tt "\%less?"} property \smath{p}, then \smath{p(op1, op2)} is
called to decide whether \smath{op1 < op2}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{compile}}\opLeftPren{}
{\it symbol}, \allowbreak{}{\it  listOfTypes}\opRightPren{}%
}%
}%
{ (Symbol, List $) -> Symbol}{}{}
{\smath{\mbox{\bf compile}\opLeftPren{}f, 
\allowbreak{} [T_1, \allowbreak{} \ldots, T_n]\opRightPren{}} 
forces the interpreter to compile
the function with name \smath{f} with signature 
\smath{(T_1, \ldots, T_n) -> T},
where \smath{T} is a type determined by type analysis of the
function body of \smath{f}.
If the compilation is successful, the operation returns the name \smath{f}.
The operation calls \spadfun{error} if \smath{f}
is not defined beforehand in the interpreter,
or if the \smath{T_i}'s are not valid types, or if the compiler fails.
See also \spadfun{function},
\spadfun{interpret}, \spadfun{lambda}, and \spadfun{compiledFunction}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{compiledFunction}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  symbol }\allowbreak $\,[$ , \allowbreak{}
{\it  symbol}$]$\opRightPren{}%
}%
}%
{ (S, SY) -> (D -> I)}{}{}
{\opkey{Argument \smath{expression} may be of any type that is
coercible to type \spadtype{InputForm} (most commonly used types).
These functions must be package called to define the type of the
function produced.}
\newitem
\smath{\mbox{\bf compiledFunction}\opLeftPren{}expr, 
\allowbreak{} x\opRightPren{}\$P}, where \smath{P} is
\spadtype{MakeUnaryCompiledFunction(E, S, T)}, returns an anonymous
function of type \smath{S}{T} defined by defined by \smath{x
\mapsto {\rm expr}}.
The anonymous function is compiled and directly applicable to
objects of type \smath{S}.
\newitem
\smath{\mbox{\bf compiledFunction}\opLeftPren{}expr, 
\allowbreak{} x, \allowbreak{} y\opRightPren{}\$P}, where \smath{P} is
\spadtype{MakeBinaryCompiledFunction(E, A, B, T)} returns an
anonymous function of type \spadsig{(A, B)}{T} defined by
\smath{(x, y) \mapsto {\rm expr}}.
The anonymous function is compiled and is then directly applicable
to objects of type \smath{(A, B)}.
\newitem
See also \spadfun{compile}, \spadfun{function}, and
\spadfun{lambda}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complement}}\opLeftPren{}
{\it finiteSetElement}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{FiniteSetAggregate}
{\smath{\mbox{\bf complement}\opLeftPren{}u\opRightPren{}} 
returns the complement of the finite set \smath{u}, that is, the 
set of all values not in \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complementaryBasis}}\opLeftPren{}
{\it vector}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->Vector(\$)}{FunctionFieldCategory}
{\smath{\mbox{\bf complementaryBasis}\opLeftPren{}b_1, 
\allowbreak{} \ldots, b_n\opRightPren{}} returns the complementary
basis \smath{(b_1^{'}, \ldots, b_n^{'})} of \smath{(b_1, \ldots, b_n)} 
for a domain of category \spadtype{FunctionFieldCategory}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complete}}\opLeftPren{}
{\it streamOrInteger}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LazyStreamAggregate}
{\smath{\mbox{\bf complete}\opLeftPren{}u\opRightPren{}} 
causes all terms of a stream or continued
fraction \smath{u} to be computed.
If not called on a finite stream or continued fraction, this
function will compute until interrupted.
\newitem
\smath{\mbox{\bf complete}\opLeftPren{}n\opRightPren{}} 
is the \eth{\smath{n}} complete
homogeneous symmetric function expressed in terms of power sums.
Alternatively, it is the cycle index of the symmetric group of
degree \smath{n}.
See \spadtype{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{completeEchelonBasis}}\opLeftPren{}
{\it vectorOfVectors}\opRightPren{}%
}%
}%
{1}{(Vector(Vector(R)))->Matrix(R)}{RepresentationPackage2}
{\smath{\mbox{\bf completeEchelonBasis}\opLeftPren{}vv\opRightPren{}} 
returns a completed basis from \smath{vv},
a vector of vectors of domain elements. \seeDetails{RepresentationPackage2}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complex}}\opLeftPren{}{\it element}, 
\allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(R, R)->\$}{ComplexCategory}
{\smath{\mbox{\bf complex}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
creates the complex expression \smath{x} + \%i*y.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexEigenvalues}}\opLeftPren{}{\it matrix}, 
\allowbreak{}{\it  precision}\opRightPren{}%
}%
}%
{2}{(Matrix(Complex(Fraction(Integer))), Float)->List(Complex(Float))}
{NumericComplexEigenPackage}
{\smath{\mbox{\bf complexEigenvalues}\opLeftPren{}m, \allowbreak{} 
eps\opRightPren{}} computes the eigenvalues of the matrix \smath{m} 
to precision \smath{eps}, chosen as a float or a rational number 
so as to agree with the type
of the coefficients of the matrix \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexEigenvectors}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  precision}\opRightPren{}%
}%
}%
{2}{(Matrix(Complex(Fraction(Integer))), Float)->
List(Record(floatval:Complex(Float), floatmult:Integer, 
floatvect:List(Matrix(Complex(Float)))))}{NumericComplexEigenPackage}
{\smath{\mbox{\bf complexEigenvectors}\opLeftPren{}m, 
\allowbreak{} eps\opRightPren{}} (\smath{m}, a matrix) 
returns a list of records,
each containing a complex
eigenvalue, its algebraic multiplicity, and a list of associated eigenvectors.
All results are expressed as complex floats or rationals 
with precision \smath{eps}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexElementary}}\opLeftPren{}
{\it expression\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(F)->F}{TrigonometricManipulations}
{\smath{\mbox{\bf complexElementary}\opLeftPren{}e\opRightPren{}} 
rewrites \smath{e} in terms of the two fundamental complex transcendental 
elementary functions: \smath{log, exp}.
\newitem\smath{\mbox{\bf complexElementary}\opLeftPren{}e, 
\allowbreak{} x\opRightPren{}} does the same but only rewrites 
kernels of \smath{e}
involving \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexExpand}}\opLeftPren{}
{\it integrationResult}\opRightPren{}%
}%
}%
{1}{(IntegrationResult(F))->F}{IntegrationResultToFunction}
{\smath{\mbox{\bf complexExpand}\opLeftPren{}ir\opRightPren{}}, 
where \smath{ir} is an \spadtype{IntegrationResult}, 
returns the expanded complex function corresponding to \smath{ir}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexIntegrate}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  variable}\opRightPren{}%
}%
}%
{2}{(F, Symbol)->F}{FunctionSpaceComplexIntegration}
{\smath{\mbox{\bf complexIntegrate}\opLeftPren{}f, 
\allowbreak{} x\opRightPren{}} returns $\int f(x)dx$ where \smath{x} is viewed 
as a complex variable.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexLimit}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  equation}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(R)), 
Equation(Fraction(Polynomial(R))))->
OnePointCompletion(Fraction(Polynomial(R)))}{RationalFunctionLimitPackage}
{\smath{\mbox{\bf complexLimit}\opLeftPren{}f(x), 
\allowbreak{} x = a\opRightPren{}} computes the complex 
limit of \smath{f} as its argument 
\smath{x} approaches \smath{a}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexNormalize}}\opLeftPren{}
{\it expression\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(F)->F}{TrigonometricManipulations}
{\smath{\mbox{\bf complexNormalize}\opLeftPren{}e\opRightPren{}} rewrites 
\smath{e} using the least possible number of complex independent kernels.
\newitem\smath{\mbox{\bf complexNormalize}\opLeftPren{}e, 
\allowbreak{} x\opRightPren{}} rewrites \smath{e} using the least possible 
number of complex independent kernels involving \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexNumeric}}\opLeftPren{}
{\it expression\opt{, positiveInteger}}\opRightPren{}%
}%
}%
{1}{(Expression(S))->Complex(Float)}{Numeric}
{\smath{\mbox{\bf complexNumeric}\opLeftPren{}u\opRightPren{}} 
returns a complex approximation of \smath{u},
where \smath{u} is a polynomial or an expression.
\newitem\smath{\mbox{\bf complexNumeric}\opLeftPren{}u, 
\allowbreak{} n\opRightPren{}} does the same but requires accuracy to be up to
\smath{n} decimal places.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexRoots}}\opLeftPren{}
{\it rationalFunctions\opt{, options}}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(Complex(Fraction(Integer)))), Par)->
List(Complex(Par))}{FloatingComplexPackage}
{\smath{\mbox{\bf complexRoots}\opLeftPren{}rf, 
\allowbreak{} eps\opRightPren{}} finds all the complex solutions of a
univariate rational function with rational number coefficients with
precision given by \smath{eps}.
The complex solutions are returned either
as rational numbers or floats depending on whether \smath{eps}
is a rational number or a float.
\newitem\smath{\mbox{\bf complexRoots}\opLeftPren{}lrf, 
\allowbreak{} lv, \allowbreak{} eps\opRightPren{}} similarly 
finds all the complex solutions
of a list of rational functions with rational number coefficients
with respect the variables appearing in \smath{lv}.
Solutions are computed to precision \smath{eps} and returned as
a list of values corresponding to the order of variables in \smath{lv}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexSolve}}\opLeftPren{}
{\it eq}, \allowbreak{}{\it  x}\opRightPren{}%
}%
}%
{1}{(Equation(Expression(R)))->List(Equation(Expression(R)))}
{TransSolvePackage}
{See \smath{\mbox{\bf solve}\opLeftPren{}u, \allowbreak{} v\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{complexZeros}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  floatOrRationaNumber}\opRightPren{}%
}%
}%
{2}{(UP, Par)->List(Complex(Par))}{ComplexRootPackage}
{\smath{\mbox{\bf complexZeros}\opLeftPren{}poly, 
\allowbreak{} eps\opRightPren{}} finds the complex zeros of the
univariate polynomial \smath{poly} to precision \smath{eps}.
Solutions are returned either as complex floats or rationals
depending on the type of \smath{eps}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{components}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{ThreeSpace}
{\smath{\mbox{\bf components}\opLeftPren{}sp\opRightPren{}} takes the 
\spadtype{ThreeSpace} object \smath{sp}, and returns
a list of \spadtype{ThreeSpace} objects, each having a single component.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{composite}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{1}{(List(\$))->\$}{ThreeSpace}
{\smath{\mbox{\bf composite}\opLeftPren{}p, \allowbreak{} q\opRightPren{}}, 
for polynomials \smath{p} and \smath{q},
returns \smath{f} if \smath{p} = \smath{f(q)}, and \mbox{\tt "failed"} 
if no such \smath{f} exists.
\newitem
\smath{\mbox{\bf composite}\opLeftPren{}lsp\opRightPren{}}, 
where \smath{lsp} is a list
\smath{[ sp_1, sp_2, \ldots, sp_n]} of \spadtype{ThreeSpace} objects,
returns a single \spadtype{ThreeSpace} object containing
the union of all objects in the parameter list grouped as a single composite.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{composites}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{ThreeSpace}
{\smath{\mbox{\bf composites}\opLeftPren{}sp\opRightPren{}} 
takes the \spadtype{ThreeSpace} object \smath{sp}
and returns a list of \spadtype{ThreeSpace} objects, 
one for each single composite
of \smath{sp}. If \smath{sp} has no defined composites 
(composites need to be explicitly created), the list returned is empty. 
Note that not all the components need to be part of a composite.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{concat}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
\opand \mbox{\axiomFun{concat!}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(\$, S)->\$}{ExtensibleLinearAggregate}
{\smath{\mbox{\bf concat}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}} returns list \smath{u} with additional element 
\smath{x} at the end. Note: equivalent to 
\smath{\mbox{\bf concat}\opLeftPren{}u, 
\allowbreak{} [ x]\opRightPren{}}.
\newitem\smath{\mbox{\bf concat}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} returns an aggregate 
consisting of the elements of \smath{u} 
followed by the elements of \smath{v}.
\newitem\smath{\mbox{\bf concat}\opLeftPren{}u\opRightPren{}}, 
where \smath{u} is a list of aggregates \smath{[ a, b, $\ldots$, c]}, 
returns a single aggregate consisting of the elements of \smath{a} followed 
by those of \smath{b} followed $\ldots$ by the elements of \smath{c}.
\newitem\smath{\mbox{\bf concat!}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}}, where \smath{u} is 
extensible, destructively adds 
element \smath{x} to the end of aggregate \smath{u}; if \smath{u} is a stream, 
it must be finite.
\newitem\smath{\mbox{\bf concat!}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} destructively appends \smath{v} 
to the end of \smath{u}; if
\smath{u} is a stream, it must be finite.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{conditionP}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(\$))->Union(Vector(\$), "failed")}{FiniteFieldCategory}
{\smath{\mbox{\bf conditionP}\opLeftPren{}M\opRightPren{}}, 
given a matrix \smath{M} representing a
homogeneous system of equations over a field \smath{F} with
\spadfun{characteristic} \smath{p}, returns a non-zero vector
whose \eth{\smath{p}} power is a non-trivial solution to these
equations, or \mbox{\tt "failed"} if no such vector exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{conditionsForIdempotents}}
\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(Polynomial(R))}{FramedNonAssociativeAlgebra}
{\smath{\mbox{\bf conditionsForIdempotents}\opLeftPren{}\opRightPren{}}
determines a complete list of polynomial equations for the
coefficients of idempotents with respect to the \smath{R}-module
basis.
\seeAlso{\spadtype{FramedNonAssociativeAlgebra} for an alternate
definition}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{conical}}\opLeftPren{}
{\it smallFloat}, \allowbreak{}{\it  smallFloat}\opRightPren{}%
}%
}%
{2}{(R, R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf conical}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns a function of two parameters for
mapping conical coordinates to Cartesian coordinates.
The function maps the point \smath{(\lambda, \mu, \nu)} to \smath{x
= \lambda\mu\nu/(ab)}, \smath{y =
\lambda/a\sqrt((mu^2-a^2)(\nu^2-a^2)/(a^2-b^2))}, \smath{z =
\lambda/b\sqrt((mu^2-b^2)(nu^2-b^2)/(b^2-a^2))}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{conjugate}}\opLeftPren{}
{\it element\opt{, element}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ComplexCategory}
{\smath{\mbox{\bf conjugate}\opLeftPren{}u\opRightPren{}} 
returns the conjugate of a complex,
quaternion, or octonian expression \smath{u}. For example, 
if \smath{u} is the
complex expression \smath{x + \%i y}, 
\smath{\mbox{\bf conjugate}\opLeftPren{}u\opRightPren{}}
returns \smath{x - \% i y}.
\newitem\smath{\mbox{\bf conjugate}\opLeftPren{}pt\opRightPren{}} 
returns the conjugate of a partition \smath{pt}.
\seeType{PartitionsAndPermutations}
\newitem\smath{\mbox{\bf conjugate}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} returns 
\smath{\mbox{\bf inv}\opLeftPren{}q) * p * q}
for elements \smath{p} and \smath{q} of a group. Note: this operation
is called {\it right action by conjugation}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{conjugates}}\opLeftPren{}
{\it streamOfPartitions}\opRightPren{}%
}%
}%
{1}{(Stream(List(Integer)))->Stream(List(Integer))}{PartitionsAndPermutations}
{\smath{\mbox{\bf conjugates}\opLeftPren{}lp\opRightPren{}} 
is the stream of conjugates of a stream of
partitions \smath{lp}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{connect}}\opLeftPren{}
{\it twoDimensionalViewport}, \allowbreak{}
{\it  positiveInteger}, \allowbreak{}{\it  string}\opRightPren{}%
}%
}%
{3}{(Kernel(S))->Union(R, "failed")}{KernelFunctions2}
{\smath{\mbox{\bf connect}\opLeftPren{}v, 
\allowbreak{} n, \allowbreak{} s\opRightPren{}} 
displays the lines connecting the graph points in
field \smath{n} of the \twodim{} viewport \smath{v} if
\smath{s="on"},
and does not display the lines if \smath{s="off"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{constant}}\opLeftPren{}
{\it variableOrfunction}\opRightPren{}%
 \optand \mbox{\axiomFun{constantLeft}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  element}\opRightPren{}%
 \opand \mbox{\axiomFun{constantRight}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{    (()->C)       -> (A ->C)}{}{}
{\opkey{These operations add an argument to a function
and must be package-called from package \smath{P} as indicated.
See also \spadfun{curry}, \spadfun{curryLeft}, and \spadfun{curryRight}.}
\newitem
\smath{\mbox{\bf constant}\opLeftPren{}f\opRightPren{}\$P} 
returns the function \smath{g}
such that \smath{g(a)= f()}, where
function \smath{f} has type
\spadsig{}{C} and \smath{a} has type \smath{A}.
The function must be package-called from
\smath{P =} \spadtype{MappingPackage2(A, C)}.
\newitem
\smath{\mbox{\bf constantRight}\opLeftPren{}f\opRightPren{}\$P} 
returns the function \smath{g}
such that \smath{g(a, b)= f(a)}, where function \smath{f} has
type \spadsig{A}{C} and \smath{b} has type \smath{B}.
This function must be package-called from
\smath{P =} \spadtype{MappingPackage3(A, B, C)}.
\newitem
\smath{\mbox{\bf constantLeft}\opLeftPren{}f\opRightPren{}\$P} 
returns the function \smath{g}
such that \smath{g(a, b)= f(b)}, where function \smath{f} has
type \spadsig{B}{C} and \smath{a} has type \smath{A}.
The function must be package-called from
\smath{P =} \spadtype{MappingPackage3(A, B, C)}.
\newitem
\smath{\mbox{\bf constant}\opLeftPren{}x\opRightPren{}} 
tells the pattern matcher that \smath{x} should match
the symbol \smath{'x} and no other quantity, or calls 
\spadfun{error} if \smath{x} is not a symbol.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{constantOperator}}\opLeftPren{}
{\it property}\opRightPren{}%
 \opand \mbox{\axiomFun{constantOpIfCan}}\opLeftPren{}{\it f}\opRightPren{}%
}%
}%
{1}{(BasicOperator)->Union(A, "failed")}{BasicOperatorFunctions1}
{\smath{\mbox{\bf constantOperator}\opLeftPren{}f\opRightPren{}} 
returns a nullary operator op such that \smath{op()} always 
evaluate to \smath{f}.
\newitem
\smath{\mbox{\bf constantOpIfCan}\opLeftPren{}op\opRightPren{}} 
returns \smath{f} if \smath{op} is the constant nullary operator 
always returning \smath{f}, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{construct}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  ..}\opRightPren{}%
}%
}%
{1}{(List(S))->\$}{Collection}
{\smath{\mbox{\bf construct}\opLeftPren{}x, \allowbreak{} y, 
\allowbreak{} \ldots, z\opRightPren{}\$R} returns the collection of elements 
\smath{x, y, \ldots, z} from domain \smath{R} ordered as given. 
This is equivalently written
as \smath{[ x, y, \ldots, z]}. The qualification \smath{R} may be omitted 
for domains
of type \spadtype{List}.
Infinite tuples such as \smath{[ x_i \mbox{ \tt for } i \mbox{ \tt in } 1..]} 
are converted
to a \spadtype{Stream} object.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cons}}\opLeftPren{}{\it element}, \allowbreak{}
{\it  listOrStream}\opRightPren{}%
}%
}%
{2}{(S, \$)->\$}{List}
{\smath{\mbox{\bf cons}\opLeftPren{}x, \allowbreak{} u\opRightPren{}}, 
where u is a list or stream,
creates a new list or stream whose \spadfun{first} element is \smath{x}
and whose \spadfun{rest} is \smath{u}. Equivalent to 
\smath{\mbox{\bf concat}\opLeftPren{}x, \allowbreak{} u\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{content}}\opLeftPren{}
{\it polynomial\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(\$)->R}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf content}\opLeftPren{}p\opRightPren{}} 
returns the greatest common divisor (\spadfun{gcd}) of the 
coefficients of polynomial \smath{p}.
\newitem\smath{\mbox{\bf content}\opLeftPren{}p, 
\allowbreak{} v\opRightPren{}}, where \smath{p} is a multivariate 
polynomial type, returns
the \smath{gcd} of the coefficients of the polynomial \smath{p} 
viewed as a univariate polynomial with respect to the variable \smath{v}.
For example, if \smath{p = 7x^2y + 14xy^2}, the \smath{gcd} of the
coefficients with respect to \smath{x} is \smath{7y}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{continuedFraction}}\opLeftPren{}
{\it fractionOrFloat\opt{, options}}\opRightPren{}%
}%
}%
{1}{(F)->ContinuedFraction(Integer)}{NumericContinuedFraction}
{\smath{\mbox{\bf continuedFraction}\opLeftPren{}f\opRightPren{}} 
converts the floating point number \smath{f}
to a reduced continued fraction.
\newitem\smath{\mbox{\bf continuedFraction}\opLeftPren{}r\opRightPren{}} 
converts the fraction
\smath{r} with components of type \smath{R} to a continued
fraction over \smath{R}.
\newitem\smath{\mbox{\bf continuedFraction}\opLeftPren{}r, 
\allowbreak{} s, \allowbreak{} s'\opRightPren{}}, where \smath{s} and
\smath{s'} are streams over
a domain \smath{R}, constructs a continued fraction in the
following way: if \smath{s = [ a1, a2, $\ldots$]} and
\smath{s' = [ b1, b2, $\ldots$]} then the result is the
continued fraction \smath{r + a1/(b1 + a2/(b2 + $\ldots$))}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{contract}}\opLeftPren{}
{\it idealOrTensors\opt{, options}}\opRightPren{}%
}%
}%
{3}{(\$, Integer, Integer)->\$}{CartesianTensor}
{\smath{\mbox{\bf contract}\opLeftPren{}I, \allowbreak{} lvar\opRightPren{}} 
contracts the ideal \smath{I} to the
polynomial ring \smath{F[ lvar]}.
\newitem\smath{\mbox{\bf contract}\opLeftPren{}t, \allowbreak{} i, 
\allowbreak{} j\opRightPren{}} is the contraction of tensor
\smath{t} which sums along the \eth{\smath{i}} and \eth{\smath{j}}
indices.
For example, if \smath{r = contract(t, 1, 3)} for a rank 4 tensor
\smath{t}, then \smath{r} is the rank 2 \smath{(= 4 - 2)} tensor
given by \smath{r(i, j) = \sum\nolimits_{h=1}^{\rm dim}t(h, i, h, j)}.
\newitem\smath{\mbox{\bf contract}\opLeftPren{}t, 
\allowbreak{} i, \allowbreak{} s, \allowbreak{} j\opRightPren{}} 
is the inner product of tensors
\smath{s} and \smath{t} which sums along the \smath{k_1}st index
of \smath{t} and the \smath{k_2}st index of \smath{s}.
For example, if \smath{r = contract(s, 2, t, 1)} for rank 3 tensors
\smath{s} and \smath{t}, then \smath{r} is the rank 4 \smath{(= 3
+ 3 - 2)} tensor given by \smath{r(i, j, k, l) =
\sum\nolimits_{h=1}^{\rm dim} s(i, h, j)t(h, k, l)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{contractSolve}}\opLeftPren{}
{\it equation}, \allowbreak{}{\it  symbol}\opRightPren{}%
}%
}%
{1}{(Equation(Expression(R)))->List(Equation(Expression(R)))}
{TransSolvePackage}
{\smath{\mbox{\bf contractSolve}\opLeftPren{}eq, 
\allowbreak{} x\opRightPren{}} finds the solutions expressed in
terms of radicals of the equation of rational functions \smath{eq}
with respect to the symbol \smath{x}.
The result contains new symbols for common subexpressions in order
to reduce the size of the output.
Alternatively, an expression \smath{u} may be given for \smath{eq}
in which case the equation \smath{eq} is defined as \smath{u=0}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{controlPanel}}\opLeftPren{}
{\it viewport}, \allowbreak{}{\it  string}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(Fraction(R))}{ContinuedFraction}
{\smath{\mbox{\bf controlPanel}\opLeftPren{}v, 
\allowbreak{} s\opRightPren{}} displays the control panel of the given
\twodim{} or \threedim{} viewport \smath{v} if \smath{s = "on"},
or hides the
control panel if \smath{s = "off"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{convergents}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(Fraction(R))}{ContinuedFraction}
{\smath{\mbox{\bf convergents}\opLeftPren{}cf\opRightPren{}} 
returns the stream of the convergents of
the continued fraction \smath{cf}.
If the continued fraction is finite, then the stream will be
finite.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coordinate}}\opLeftPren{}
{\it curveOrSurface}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->ComponentFunction}{ParametricPlaneCurve}
{\smath{\mbox{\bf coordinate}\opLeftPren{}u, 
\allowbreak{} n\opRightPren{}} returns the \eth{\smath{n}}
coordinate function for the curve or surface \smath{u}.
See \spadtype{ParametericPlaneCurve}, \spadtype{ParametricSpaceCurve},
and \spadtype{ParametericSurface}, using HyperDoc.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coordinates}}\opLeftPren{}
{\it pointOrvector\opt{, basis}}\opRightPren{}%
}%
}%
{2}{(\$, Vector(\$))->Vector(R)}{FiniteRankAlgebra}
{\smath{\mbox{\bf coordinates}\opLeftPren{}pt\opRightPren{}} specifies a 
change of coordinate systems
of point \smath{pt}.
This option is expressed in the form \smath{coordinates == pt}.
\medbreak\opkey{The following operations return a matrix
representation of the coordinates of an argument vector \smath{v}
of the form \smath{[ v_1\ldots v_n]} with respect to
the basis a domain \smath{R}.
The coordinates of \smath{v_i} are contained in the
\eth{\smath{i}} row of the matrix returned.}
\newitem\smath{\mbox{\bf coordinates}\opLeftPren{}v{, b}\opRightPren{}} 
returns the matrix
representation with respect to the basis \smath{b} for vector
\smath{v} of elements from domain \smath{R} of category
\spadtype{FiniteRankNonAssociativeAlgebra} or
\spadtype{FiniteRankAlgebra}.
If a second argument is not given, the basis is taken to be the
fixed basis of \smath{R}.
\newitem\smath{\mbox{\bf coordinates}\opLeftPren{}v\opRightPren{}\$R}, 
returns a matrix representation
for \smath{v} with respect to a fixed basis for domain \smath{R}
of category \spadtype{FiniteAlgebraicExtensionField},
\spadtype{FramedNonAssociativeAlgebra}, or
\spadtype{FramedAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{copies}}\opLeftPren{}{\it integer}, \allowbreak{}
{\it  string}\opRightPren{}%
}%
}%
{2}{(Integer, String)->String}{DisplayPackage}
{\smath{\mbox{\bf copies}\opLeftPren{}n, \allowbreak{} s\opRightPren{}} 
returns
a string composed of \smath{n} copies of string \smath{s}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{copy}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{Aggregate}
{\smath{\mbox{\bf copy}\opLeftPren{}u\opRightPren{}} returns a 
top-level (non-recursive) copy of an aggregate \smath{u}.
Note: for lists, \code{copy(u) == [x for x in u]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{copyInto!}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  aggregate}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, \$, Integer)->\$}{FiniteLinearAggregate}
{\smath{\mbox{\bf copyInto!}\opLeftPren{}u, \allowbreak{} v, 
\allowbreak{} p\opRightPren{}} returns linear aggregate \smath{u} with
elements of \smath{u} replaced by the successive elements of \smath{v}
starting at index \smath{p}.
Arguments \smath{u} and \smath{v} can be elements of any 
\spadtype{FiniteLinearAggregate}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cos}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{cosIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{TrigonometricFunctionCategory}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float},
\spadtype{DoubleFloat}, or \spadtype{Expression} value or a series.
} \newitem\smath{\mbox{\bf cos}\opLeftPren{}x\opRightPren{}} 
returns the cosine of \smath{x}.
\newitem\smath{\mbox{\bf cosIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf cos}\opLeftPren{}x\opRightPren{}} if possible,
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cos2sec}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf cos2sec}\opLeftPren{}e\opRightPren{}} converts 
every \smath{\mbox{\bf cos}\opLeftPren{}u\opRightPren{}} appearing in
\smath{e} into \smath{1/\sec(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cosh2sech}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf cosh2sech}\opLeftPren{}e\opRightPren{}} converts 
every \smath{\mbox{\bf cosh}\opLeftPren{}u\opRightPren{}} appearing in
\smath{e} into \smath{1/\mbox{\rm sech}(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cosh}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{coshIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{HyperbolicFunctionCategory}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float},
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem\smath{\mbox{\bf cosh}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic cosine of
\smath{x}.
\newitem\smath{\mbox{\bf coshIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf cosh}\opLeftPren{}x\opRightPren{}} if possible,
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cot}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{TrigonometricFunctionCategory}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float}, 
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem\smath{\mbox{\bf cot}\opLeftPren{}x\opRightPren{}} 
returns the cotangent of \smath{x}.
\newitem\smath{\mbox{\bf cotIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf cot}\opLeftPren{}x\opRightPren{}} 
if possible, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cot2tan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf cot2tan}\opLeftPren{}expression\opRightPren{}} 
converts every \smath{\cot(u)}
appearing in \smath{e} into \smath{1/\tan(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cot2trig}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf cot2trig}\opLeftPren{}expression\opRightPren{}} 
converts every \smath{\cot(u)}
appearing in \smath{e} into \smath{\cos(u)/\sin(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coth}}\opLeftPren{}
{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{cothIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float}, 
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem\smath{\mbox{\bf coth}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic cotangent of \smath{x}.
\newitem
\smath{\mbox{\bf cothIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf coth}\opLeftPren{}x\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coth2tanh}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf coth2tanh}\opLeftPren{}expression\opRightPren{}} 
converts every \smath{\mbox{\rm
coth}(u)} appearing in \smath{e} into \smath{1/\mbox{\rm
tanh}(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{coth2trigh}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf coth2trigh}\opLeftPren{}expression\opRightPren{}} 
converts every \smath{\mbox{\rm
coth}(u)} appearing in
\smath{e} into \smath{\mbox{\rm cosh}(u)/\mbox{\rm sinh}(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{count}}\opLeftPren{}
{\it predicate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->NonNegativeInteger}{HomogeneousAggregate}
{\smath{\mbox{\bf count}\opLeftPren{}pred, \allowbreak{} u\opRightPren{}} 
returns the number of elements \smath{x} in
\smath{u} such that \smath{\mbox{\bf pred}\opLeftPren{}x\opRightPren{}} 
is \smath{true}.
For collections, \code{count(p, u) = reduce(+, [1 for x in u |
p(x)], 0)}.
\newitem\smath{\mbox{\bf count}\opLeftPren{}x, 
\allowbreak{} u\opRightPren{}} returns the number of occurrences of
\smath{x} in \smath{u}.
For collections, \code{count(x, u) = reduce(+, [x=y for y in u], 0)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{countable?}}\opLeftPren{}{\it cardinal}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{CardinalNumber}
{\smath{\mbox{\bf countable?}\opLeftPren{}u\opRightPren{}} 
tests if the cardinal number \smath{u} is
countable, that is, if $u \le $\smath{Aleph 0}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createThreeSpace}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{ThreeSpace}
{\smath{\mbox{\bf createThreeSpace}\opLeftPren{}\opRightPren{}}
{\bf \$}\spadtype{ThreeSpace(R)} creates a
\spadtype{ThreeSpace} object capable of holding point,
curve, mesh components or any combination of the three.
The ring \smath{R} is usually \spadtype{DoubleFloat}.
If you do not package call this function, \spadtype{DoubleFloat}
is assumed.
\newitem\smath{\mbox{\bf createThreeSpace}\opLeftPren{}s\opRightPren{}} 
creates a \spadtype{ThreeSpace}
object containing objects pre-defined within some
\spadtype{SubSpace} \smath{s}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createGenericMatrix}}\opLeftPren{}
{\it nonNegativeInteger}\opRightPren{}%
}%
}%
{1}{(NonNegativeInteger)->Matrix(Polynomial(R))}{RepresentationPackage1}
{\smath{\mbox{\bf createGenericMatrix}\opLeftPren{}n\opRightPren{}} 
creates a square matrix of
dimension \smath{n} whose entry at the \smath{i}-th row and
\smath{j}-th column is the indeterminate \smath{x_{i, j}} (double
subscripted).
\seeType{RepresentationPackage1}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createIrreduciblePoly}}\opLeftPren{}
{\it nonNegativeInteger}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf createIrreduciblePoly}\opLeftPren{}n\opRightPren{}}
{\bf \$}\spadtype{FFPOLY(GF)} generates
a monic irreducible polynomial of degree \smath{n} over the finite field
\smath{GF}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createNormalElement}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf createNormalElement}\opLeftPren{}\opRightPren{}\$F} 
computes a normal element over the ground field
of a finite algebraic extension field \smath{F}, that is,
an element \smath{a} such that \smath{a^{q^i}, 0 \leq i < {\mbox
{\bf extensionDegree}}()\$F} is an \smath{F}-basis, where
\smath{q} is the size of the ground field.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createNormalPrimitivePoly}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf createNormalPrimitivePoly}\opLeftPren{}n\opRightPren{}}
{\bf \$}\spadtype{FFPOLY(GF)}
generates a normal and
primitive polynomial of degree \smath{n} over the field \smath{GF}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createPrimitiveElement}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteFieldCategory}
{\smath{\mbox{\bf createPrimitiveElement}\opLeftPren{}\opRightPren{}\$F} 
computes a generator of the
(cyclic) multiplicative group of a finite
field \smath{F}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{createRandomElement}}\opLeftPren{}
{\it listOfMatrices}, \allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), Matrix(R))->Matrix(R)}{RepresentationPackage2}
{\smath{\mbox{\bf createRandomElement}\opLeftPren{}lm, 
\allowbreak{} m\opRightPren{}} creates a random element of
the group algebra generated by \smath{lm}, where \smath{lm} is a
list of matrices and \smath{m} is a matrix.
\seeType{RepresentationPackage2}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{csc2sin}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf csc2sin}\opLeftPren{}expression\opRightPren{}} 
converts every \smath{\mbox{\bf csc}\opLeftPren{}u\opRightPren{}}
appearing in \smath{f} into \smath{1/{\tt sin}(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{csch2sinh}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf csch2sinh}\opLeftPren{}expression\opRightPren{}} 
converts every \smath{\mbox{\bf csch}\opLeftPren{}u\opRightPren{}}
appearing in \smath{f} into \smath{1/{\sinh}(u)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{csch}}\opLeftPren{}
{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{cschIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float},
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series.}
\newitem\smath{\mbox{\bf csch}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic cosecant of \smath{x}.
\newitem\smath{\mbox{\bf cschIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf csch}\opLeftPren{}x\opRightPren{}} if possible,
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cscIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float},
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem
\smath{\mbox{\bf csc}\opLeftPren{}x\opRightPren{}} 
returns the cosecant of \smath{x}.
\newitem
\smath{\mbox{\bf cscIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf csc}\opLeftPren{}x\opRightPren{}} if possible,
and \mbox{\tt "failed"} otherwise.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cup}}\opLeftPren{}
{\it symmetricPolynomial}, \allowbreak{}
{\it symmetricPolynomial}\opRightPren{}%
}%
}%
{ (SPOL RN, SPOL RN) -> SPOL RN}{}{}
{\smath{\mbox{\bf cup}\opLeftPren{}s_1, 
\allowbreak{} s_2\opRightPren{}}, introduced by Redfield,
is the scalar product of two cycle indices, where the
\smath{s_i} are of type \spadtype{SymmetricPolynomial} with
rational number coefficients.
See also \spadfun{cap}. See \spadtype{CycleIndicators} for details.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{curry}}\opLeftPren{}{\it function}\opRightPren{}%
 \optand \mbox{\axiomFun{curryLeft}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  element}\opRightPren{}%
 \opand \mbox{\axiomFun{curryRight}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{   ((A, B)->C, B) -> (A ->C)}{}{}
{\opkey{These functions drop an argument from a function.}
\newitem
\smath{\mbox{\bf curry}\opLeftPren{}f, 
\allowbreak{} a\opRightPren{}} returns the function \smath{g}
such that \smath{g()= f(a)}, where function \smath{f} has type
\spadsig{A}{C} and element \smath{a} has type \smath{A}.
\newitem
\smath{\mbox{\bf curryRight}\opLeftPren{}f, 
\allowbreak{} b\opRightPren{}} returns the function \smath{g} such that
\smath{g(a) = f(a, b)}, where function \smath{f} has type
\spadsig{(A, B)}{C} and element \smath{b} has type \smath{B}.
\newitem
\smath{\mbox{\bf curryLeft}\opLeftPren{}f, 
\allowbreak{} a\opRightPren{}} is the function \smath{g}
such that \smath{g(b) = f(a, b)}, where function \smath{f} has type
\spadsig{(A, B)}{C} and element \smath{a} has type \smath{A}.
\newitem
See also \spadfun{constant}, \spadfun{constantLeft}, 
and \spadfun{constantRight}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{curve}}\opLeftPren{}
{\it listOfPoints\opt{, options}}\opRightPren{}%
}%
}%
{1}{(List(Point(R)))->\$}{ThreeSpace}
{\smath{\mbox{\bf curve}\opLeftPren{}
[ p_0, p_1, $\ldots$, p_n]\opRightPren{}} creates a
space curve defined by the list of points \smath{p_0} through
\smath{p_n} and returns a \spadtype{ThreeSpace} object whose
component is the curve.
\newitem\smath{\mbox{\bf curve}\opLeftPren{}sp\opRightPren{}} 
checks to see if the
\spadtype{ThreeSpace} object \smath{sp} is composed of a single
curve defined by a list of points; if so, the list of points
defining the curve is returned.
Otherwise, the operation calls \spadfun{error}.
\newitem\smath{\mbox{\bf curve}\opLeftPren{}c_1, 
\allowbreak{} c_2\opRightPren{}} creates a plane curve from two
component functions \smath{c_1} and \smath{c_2}.
\seeType{ComponentFunction}
\newitem\smath{curve(sp, [
[ p_0], [ p_1], $\ldots$, [
p_n]])} adds a space curve defined by a list of points
\smath{p_0} through \smath{p_n} to a \spadtype{ThreeSpace} object
\smath{sp}.
Each \smath{p_i} is from a domain 
\smath{\mbox{\bf PointDomain}\opLeftPren{}m, 
\allowbreak{} R\opRightPren{}}, where
\smath{R} is the \spadtype{Ring} over which the point elements are
defined and \smath{m} is the dimension of the points.
\newitem \smath{\mbox{\bf curve}\opLeftPren{}s, 
\allowbreak{} [ p_0, p_1, $\ldots$, p_n]\opRightPren{}} adds
the space curve component designated by the list of points
\smath{p_0} through \smath{p_n} to the \spadtype{ThreeSpace} object
\smath{sp}.
\newline \smath{\mbox{\bf curve}\opLeftPren{}c_1, \allowbreak{} c_2, 
\allowbreak{} c_3\opRightPren{}} creates a space curve from
three component functions \smath{c_1}, \smath{c_2}, and
\smath{c_3}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{curve?}}\opLeftPren{}{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{ThreeSpace}
{\smath{\mbox{\bf curve?}\opLeftPren{}sp\opRightPren{}} 
tests if the \spadtype{ThreeSpace} object \smath{sp} contains
a single curve object.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{curveColor}}\opLeftPren{}{\it float}\opRightPren{}%
}%
}%
{1}{(Float)->\$}{DrawOption}
{\smath{\mbox{\bf curveColor}\opLeftPren{}p\opRightPren{}} 
specifies a color index for \twodim{} graph
curves from the palette \smath{p}.
This option is expressed in the form \smath{curveColor ==p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycle}}\opLeftPren{}
{\it listOfPermutations}\opRightPren{}%
}%
}%
{1}{(List(S))->\$}{PermutationCategory}
{\smath{\mbox{\bf cycle}\opLeftPren{}ls\opRightPren{}} 
converts a cycle \smath{ls}, a list with no repetitions, to
the permutation, which
maps \smath{ls.i} to \smath{ls.(i+1)} (index modulo the length of the list).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycleEntry}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf cycleEntry}\opLeftPren{}u\opRightPren{}} 
returns the head of a top-level cycle
contained in aggregate \smath{u}, or 
\smath{\mbox{\bf empty}\opLeftPren{}\opRightPren{}} if none
exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycleLength}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf cycleLength}\opLeftPren{}u\opRightPren{}} 
returns the length of a top-level cycle
contained in aggregate \smath{u}, or 0 if \smath{u} has no such
cycle.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cyclePartition}}\opLeftPren{}
{\it permutation}\opRightPren{}%
}%
}%
{1}{(\$)->Partition}{Permutation}
{\smath{\mbox{\bf cyclePartition}\opLeftPren{}p\opRightPren{}} returns 
the cycle structure of a permutation \smath{p} including cycles of length 1.
The permutation is assumed to be a member of
\spadtype{Permutation(S)} where \smath{S} is a finite set.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycleRagits}}\opLeftPren{}
{\it radixExpansion}\opRightPren{}%
}%
}%
{1}{(\$)->List(Integer)}{RadixExpansion}
{\smath{\mbox{\bf cycleRagits}\opLeftPren{}rx\opRightPren{}} returns the 
cyclic part of the ragits of the fractional part of a radix expansion. 
For example, if \smath{x = 3/28 = 0.10 714285 714285 \ldots},
then \code{cycleRagits(x) = [7, 1, 4, 2, 8, 5]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycleSplit!}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf cycleSplit!}\opLeftPren{}u\opRightPren{}} 
splits the recursive aggregate (for example, a list) \smath{u} into two
aggregates by dropping off the cycle. The value returned is the cycle entry,
or \smath{nil} if none exists.
For example, if \smath{w = {\mbox {\bf concat}}(u, v)} 
is the cyclic list where \smath{v} is the
head of the cycle, \smath{\mbox{\bf cycleSplit!}
\opLeftPren{}w\opRightPren{}} will drop \smath{v} off \smath{w}. Thus
\smath{w} is destructively changed to \smath{u}, and \smath{v}
is returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycles}}\opLeftPren{}
{\it listOfListOfElements}\opRightPren{}%
}%
}%
{1}{(List(List(S)))->\$}{PermutationCategory}
{\smath{\mbox{\bf cycles}\opLeftPren{}lls\opRightPren{}} 
coerces a list of list of cycles \smath{lls}
to a permutation.
Each cycle, represented as a list \smath{ls} with no repetitions,
is coerced to the permutation, which maps \smath{ls.i} to
\smath{ls.(i+1)} (index modulo the length of the list).
These permutations are then multiplied.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cycleTail}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf cycleTail}\opLeftPren{}u\opRightPren{}} 
returns the last node in the cycle of
a recursive aggregate (for example, a list) \smath{u}, 
or empty if none exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cyclic}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{ I -> SPOL RN    --cyclic group}{}{}
{\smath{\mbox{\bf cyclic}\opLeftPren{}n\opRightPren{}} 
returns the cycle index of the
cyclic group of degree \smath{n}.
\spadtype{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cyclic?}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{RecursiveAggregate}
{\smath{\mbox{\bf cyclic?}\opLeftPren{}u\opRightPren{}} tests if
recursive aggregate (for example, a list) \smath{u} has a cycle.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cyclicGroup}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(List(Integer))->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf cyclicGroup}\opLeftPren{}
[ i_1, \ldots, i_k]\opRightPren{}} constructs
the cyclic group of order \smath{k} acting on the list of integers
\smath{i_1}, \ldots, \smath{i_k}.
Note: duplicates in the list will be removed.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cyclicGroup}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf cyclicGroup}\opLeftPren{}n\opRightPren{}} 
constructs the cyclic group of order
\smath{n} acting on the integers 1, \ldots, \smath{n}, \smath{n >
0}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cyclicSubmodule}}\opLeftPren{}
{\it listOfMatrices}, \allowbreak{}{\it  vector}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), Vector(R))->Vector(Vector(R))}{RepresentationPackage2}
{\smath{\mbox{\bf cyclicSubmodule}\opLeftPren{}lm, 
\allowbreak{} v\opRightPren{}}, where \smath{lm} is a list of
\smath{n} by \smath{n} square matrices and \smath{v} is a vector
of size \smath{n}, generates a basis in echelon form.
\seeDetails{RepresentationPackage2}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{cylindrical}}\opLeftPren{}{\it point}\opRightPren{}%
}%
}%
{1}{(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf cylindrical}\opLeftPren{}pt\opRightPren{}} 
transforms \smath{pt} from polar
coordinates to Cartesian coordinates,
by mapping the point \smath{(r, theta, z)} to
\smath{x = r \cos(theta)}, \smath{y = r  \sin(theta)}, \smath{z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{D}}\opLeftPren{}
{\it expression\opt{, options}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{DifferentialRing}
{\smath{\mbox{\bf D}\opLeftPren{}x\opRightPren{}} returns the 
derivative of \smath{x}.
This function is a simple differential operator where no variable
needs to be specified.
\newitem\smath{\mbox{\bf D}\opLeftPren{}x, \allowbreak{} [ s_1, 
\ldots s_n]\opRightPren{}} computes
successive partial derivatives, that is, \smath{D(\ldots {\bf
D}(x, s_1)\ldots, s_n)}.
\newitem\smath{\mbox{\bf D}\opLeftPren{}u, \allowbreak{} x\opRightPren{}} 
computes the partial derivative of
\smath{u} with respect to \smath{x}.
\newitem\smath{\mbox{\bf D}\opLeftPren{}u, \allowbreak{} 
deriv\optinner{, n}\opRightPren{}} differentiates \smath{u}
\smath{n} times using a derivation which extends \smath{deriv} on
\smath{R}.
Argument \smath{n} defaults to 1.
\newitem\smath{\mbox{\bf D}\opLeftPren{}p, \allowbreak{} d, 
\allowbreak{} x'\opRightPren{}} extends the \smath{R}-derivation
\smath{d} to an extension \smath{R} in \smath{R[ x]}
where \smath{Dx} is given by \smath{x'}, and returns \smath{Dp}.
\newitem\smath{D(x, [ s_1, \ldots, s_n], [
n_1, \ldots, n_m])} computes multiple partial derivatives,
that is, \smath{\mbox{\bf D}\opLeftPren{}\ldots {\bf D}(x, s_1, n_1)\ldots, 
s_n, n_m\opRightPren{}}.
\newitem\smath{\mbox{\bf D}\opLeftPren{}u, \allowbreak{} x, 
\allowbreak{} n\opRightPren{}} computes multiple partial derivatives,
that is, \eth{\smath{n}} derivative of \smath{u} with respect to
\smath{x}.
\newitem \smath{\mbox{\bf D}\opLeftPren{}of\optinner{, n}\opRightPren{}}, 
where \smath{of} is an object
of type \spadtype{OutputForm} (normally unexposed), returns an
output form for the \eth{\smath{n}} derivative of \smath{f}, for
example, \smath{f'}, \smath{f''}}, \smath{f'''}, \smath{f^{{\tt
iv}}}, and so on.
\newitem \smath{\mbox{\bf D}\opLeftPren{}\opRightPren{}\$A} 
provides the operator corresponding to the
derivation in the differential ring \smath{A}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dark}}\opLeftPren{}{\it color}\opRightPren{}%
}%
}%
{1}{(Color)->\$}{Palette}
{\smath{\mbox{\bf dark}\opLeftPren{}color\opRightPren{}} returns 
the shade of the indicated hue of \smath{color} to its lowest value.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ddFact}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  primeInteger}\opRightPren{}%
}%
}%
{2}{(U, Integer)->List(Record(factor:U, degree:Integer))}
{ModularDistinctDegreeFactorizer}
{\smath{\mbox{\bf ddFact}\opLeftPren{}q, \allowbreak{} p\opRightPren{}} 
computes a distinct degree factorization of the polynomial 
\smath{q} modulo the prime \smath{p}, that is, such that each factor is a 
product of irreducibles of the same degrees.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{decimal}}\opLeftPren{}
{\it rationalNumber}\opRightPren{}%
}%
}%
{1}{(Fraction(Integer))->\$}{DecimalExpansion}
{\smath{\mbox{\bf decimal}\opLeftPren{}rn\opRightPren{}} 
converts a rational number \smath{rn} to a decimal expansion.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{declare}}\opLeftPren{}
{\it listOfInputForms}\opRightPren{}%
}%
}%
{ List $   -> Symbol}{}{}
{\smath{\mbox{\bf declare}\opLeftPren{}t\opRightPren{}} 
returns a name f such that f has been
declared to the interpreter to be of type t, but has
not been assigned a value yet.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{decreasePrecision}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->PositiveInteger}{FloatingPointSystem}
{\smath{\mbox{\bf decreasePrecision}\opLeftPren{}n\opRightPren{}\$R} 
decreases the current
\spadfunFrom{precision}{FloatingPointSystem} by \smath{n} decimal digits.}




% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{definingPolynomial}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->UP}{MonogenicAlgebra}
{\smath{\mbox{\bf definingPolynomial}\opLeftPren{}\opRightPren{}\$R} 
returns the minimal polynomial for
a \spadtype{MonogenicAlgebra} domain \smath{R}, that is, one which 
\smath{\mbox{\bf generator}\opLeftPren{}\opRightPren{}\$R} satisfies.
\newitem\smath{\mbox{\bf definingPolynomial}\opLeftPren{}x\opRightPren{}} 
returns an expression \smath{p} such that \smath{p(x) = 0}, 
where \smath{x} is an \spadtype{AlgebraicNumber} 
or an object of type \spadtype{Expression}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{degree}}\opLeftPren{}
{\it polynomial\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(\$)->E}{AbelianMonoidRing}
{\opkey{The meaning of degree(u\optinner{, s}) depends on the type of 
\smath{u}.}
\begin{simpleList}
\item if \smath{u} is a polynomial:
\smath{\mbox{\bf degree}\opLeftPren{}u, \allowbreak{} x\opRightPren{}} 
returns the degree of polynomial \smath{u} with respect to the variable 
\smath{x}.
Similarly, \smath{\mbox{\bf degree}\opLeftPren{}u, 
\allowbreak{} lv\opRightPren{}}, where \smath{lv} is 
a list of variables, returns
a list of degrees of polynomial \smath{u} with respect 
to each of the variables
in \smath{lv}.
\item if \smath{u}
is an element of an \spadtype{AbelianMonoidRing} or
\spadtype{GradedModule} domain:
\smath{\mbox{\bf degree}\opLeftPren{}u\opRightPren{}} 
returns the maximum of the exponents of the terms of \smath{u}.
\item if \smath{u} is a series:
\smath{\mbox{\bf degree}\opLeftPren{}u\opRightPren{}} 
returns the degree of the leading term of \smath{u}.
\item if \smath{u} is an element of a domain of category 
\spadtype{ExtensionField}: 
\smath{\mbox{\bf degree}\opLeftPren{}u\opRightPren{}}
returns the degree of the minimal polynomial of \smath{u} 
if \smath{u} is algebraic
with respect to the
ground field \smath{F}, and {\tt \%infinity} otherwise.
\item if \smath{u} is a permutation:
\smath{\mbox{\bf degree}\opLeftPren{}u\opRightPren{}} 
returns the number of points moved by the permutation.
\item if \smath{u} is a permutation group:
\smath{\mbox{\bf degree}\opLeftPren{}u\opRightPren{}} 
returns the number of points moved by all permutations of the group \smath{u}.
\seeOther{\spadfun{degree}}
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{delete}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  integerOrSegment}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->\$}{LinearAggregate}
{\smath{\mbox{\bf delete}\opLeftPren{}u, 
\allowbreak{} i\opRightPren{}} returns a copy of 
linear aggregate \smath{u} with
the \eth{\smath{i}} element deleted. Note: for lists,
\code{delete(a, i) == {\tt concat}(a(0..i-1), a(i + 1, ..))}.
\newitem\smath{\mbox{\bf delete}\opLeftPren{}u, 
\allowbreak{} i..j\opRightPren{}} returns a copy 
of \smath{u} with the \eth{\smath{i}}
through \eth{\smath{j}} element deleted.
Note: for lists, \code{delete(a, i..j) = concat(a(0..i-1), a(j+1..))}.
\newitem\smath{\mbox{\bf delete!}\opLeftPren{}u, 
\allowbreak{} i\opRightPren{}} destructively deletes 
the \eth{\smath{i}} element of \smath{u}.
\newitem\smath{\mbox{\bf delete!}\opLeftPren{}u, 
\allowbreak{} i..j\opRightPren{}} destructively deletes 
elements \smath{u}.\smath{i} 
through \smath{u}.\smath{j} of \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{deleteProperty}}\opLeftPren{}
{\it basicOperator}, \allowbreak{}{\it  string}\opRightPren{}%
}%
}%
{2}{(\$, String)->\$}{BasicOperator}
{\smath{\mbox{\bf deleteProperty}\opLeftPren{}op, \allowbreak{} s
\opRightPren{}} destructively removes property \smath{s} from \smath{op}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{denom}}\opLeftPren{}
{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{denominator}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->D}{QuotientFieldCategory}
{\opkey{Argument x can be from domain \spadtype{Fraction(R)} for 
some domain \smath{R}, or of type \spadtype{Expression}}
if the result is of type \smath{R}.
\newitem
\smath{\mbox{\bf denom}\opLeftPren{}x\opRightPren{}} returns the 
denominator of \smath{x} as an object
of domain \smath{R}; if \smath{x} is of type \spadtype{Expression}, 
it returns
an object of domain \spadtype{SMP(R, Kernel(Expression R))}.
\newitem
\smath{\mbox{\bf denominator}\opLeftPren{}x\opRightPren{}} 
returns the denominator of \smath{x} as an element
of \spadtype{Fraction(R)}; if \smath{x} is of type \spadtype{Expression},
it returns an object of domain Expression(R).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{denominators}}\opLeftPren{}
{\it fractionOrContinuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(R)}{ContinuedFraction}
{\smath{\mbox{\bf denominator}\opLeftPren{}frac\opRightPren{}} 
is the denominator of the fraction \smath{frac}.
\newitem\smath{\mbox{\bf denominators}\opLeftPren{}cf\opRightPren{}} 
returns the stream of
denominators of the approximants of the continued fraction
\smath{x}.
If the continued fraction is finite, then the stream will be
finite.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{depth}}\opLeftPren{}{\it stack}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{StackAggregate}
{\smath{\mbox{\bf depth}\opLeftPren{}st\opRightPren{}} 
returns the number of elements of stack
\smath{st}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dequeue}}\opLeftPren{}{\it queue}\opRightPren{}%
 \opand \mbox{\axiomFun{dequeue!}}\opLeftPren{}{\it queue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{QueueAggregate}
{\smath{\mbox{\bf dequeue}\opLeftPren{}[ x, y, \ldots, z]\opRightPren{}} 
creates a
dequeue with first (top or front) element \smath{x}, second
element \smath{y}, \smath{\ldots}, and last (bottom or back) element
\smath{z}.
\newitem\smath{\mbox{\bf dequeue!}\opLeftPren{}q\opRightPren{}} 
destructively extracts the first (top)
element from queue \smath{q}.
The element previously second in the queue becomes the first
element.
A call to \spadfun{error} occurs if \smath{q} is empty.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{derivationCoordinates}}\opLeftPren{}
{\it vectorOfElements}, \allowbreak{}{\it  derivationFunction}\opRightPren{}%
}%
}%
{2}{(Vector(\$), (R)->R)->Matrix(R)}{MonogenicAlgebra}
{\smath{\mbox{\bf derivationCoordinates}\opLeftPren{}v, 
\allowbreak{} \quad{}'\opRightPren{}} returns a matrix 
\smath{M} such that \smath{v' = M v}.
Argument \smath{v} is a vector of elements from \smath{R}, a domain
of category \spadtype{MonogenicAlgebra} over a ring \smath{R}.
Argument \smath{'} is a derivation function defined on \smath{R}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{derivative}}\opLeftPren{}
{\it basicOperator\opt{, property}}\opRightPren{}%
}%
}%
{1}{(BasicOperator)->Union(List((List(A))->A), "failed")}
{BasicOperatorFunctions1}
{\smath{\mbox{\bf derivative}\opLeftPren{}op\opRightPren{}} 
returns the value of the \mbox{\tt "\%diff"}
property of \smath{op} if it has one, and \mbox{\tt "failed"} otherwise.
\newitem\smath{\mbox{\bf derivative}\opLeftPren{}op, 
\allowbreak{} dprop\opRightPren{}} attaches \smath{dprop} as the
\mbox{\tt "\%diff"} property of \smath{op}.
Note: if \smath{op} has a \mbox{\tt "\%diff"} property \smath{f}, then
applying a derivation \smath{D} to \smath{op}(a) returns
\smath{f(a) D(a)}.
Argument \smath{op} must be unary.
\newitem\smath{\mbox{\bf derivative}\opLeftPren{}op, 
\allowbreak{} [f_1, \allowbreak{} \ldots, f_n]\opRightPren{}} attaches
\smath{[ f_1, \ldots, f_n]} as the \mbox{\tt "\%diff"} property
of \smath{op}.
Note: if \smath{op} has such a \mbox{\tt "\%diff"} property, then applying
a derivation \smath{D} to \smath{op(a_1, \ldots, a_n)} returns
\smath{f_1(a_1, \ldots, a_n) D(a_1) + \cdots + fn(a_1, \ldots, a_n)
D(a_n)}.
\newitem\seeAlso{\smath{D}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{destruct}}\opLeftPren{}
{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{SExpressionCategory}
{\smath{\mbox{\bf destruct}\opLeftPren{}se\opRightPren{}}, where \smath{se} is
the \smath{SExpression} \smath{(a_1, \ldots, a_n)}, returns the list
\smath{[ a_1, \ldots, a_n]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{determinant}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->R}{MatrixCategory}
{\smath{\mbox{\bf determinant}\opLeftPren{}m\opRightPren{}} 
returns the determinant of the matrix \smath{m}, or calls
\spadfun{error} if the matrix is not square.
Note: the underlying coefficient domain of \smath{m} is assumed to
have a commutative \spadop{*}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{diagonal}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(List(R))->\$}{MatrixCategory}
{\smath{\mbox{\bf diagonal}\opLeftPren{}m\opRightPren{}}, 
where \smath{m} is a square matrix, returns a vector
consisting of the diagonal elements of \smath{m}.
\newitem
\smath{\mbox{\bf diagonal}\opLeftPren{}f\opRightPren{}},
where \smath{f} is a function of type \spadsig{(A, A)}{T}
is the function \smath{g}
such that \smath{g(a) = f(a, a)}.
See \spadtype{MappingPackage} for related functions.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{diagonal?}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{MatrixCategory}
{\smath{\mbox{\bf diagonal?}\opLeftPren{}m\opRightPren{}} tests if the matrix
\smath{m} is square and diagonal.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{diagonalMatrix}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{1}{(List(R))->\$}{MatrixCategory}
{\smath{\mbox{\bf diagonalMatrix}\opLeftPren{}l\opRightPren{}},
where \smath{l} is a list or vector of elements, returns a
(square) diagonal matrix with those
elements of \smath{l} on the diagonal.
\newitem\smath{\mbox{\bf diagonalMatrix}\opLeftPren{}
[ m_1, \ldots, m_k]\opRightPren{}}
creates a block diagonal matrix \smath{M} with block matrices
\smath{m_1}, \ldots, \smath{m_k} down the diagonal,
with 0 block matrices elsewhere.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{diagonalProduct}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->R}{SquareMatrixCategory}
{\smath{\mbox{\bf diagonalProduct}\opLeftPren{}m\opRightPren{}} 
returns the product of the elements on the diagonal of the matrix \smath{m}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dictionary}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{DictionaryOperations}
{\smath{\mbox{\bf dictionary}\opLeftPren{}\opRightPren{}}\$\smath{R} 
creates an empty dictionary of type \smath{R}.
\newitem\smath{\mbox{\bf dictionary}\opLeftPren{}
[ x, y, \ldots, z]\opRightPren{}} creates a 
dictionary consisting of entries \smath{x, y, \ldots, z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{difference}}\opLeftPren{}
{\it setAggregate}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, S)->\$}{SetAggregate}
{\smath{\mbox{\bf difference}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}} returns the set aggregate \smath{u} with element
\smath{x} removed.
\newitem\smath{\mbox{\bf difference}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} returns the set aggregate 
\smath{w} consisting of elements 
in set aggregate \smath{u} but not in set aggregate \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{differentialVariables}}\opLeftPren{}
{\it differentialPolynomial}\opRightPren{}%
}%
}%
{1}{(\$)->List(S)}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf differentialVariables}\opLeftPren{}p\opRightPren{}} 
returns a list of differential 
indeterminates occurring in a differential polynomial \smath{p}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{differentiate}}\opLeftPren{}
{\it expression\opt{, options}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{DifferentialRing}
{See \spadfun{D}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{digamma}}\opLeftPren{}
{\it complexDoubleFloat}\opRightPren{}%
}%
}%
{1}{(Complex(DoubleFloat))->Complex(DoubleFloat)}{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf digamma}\opLeftPren{}x\opRightPren{}} 
is the function, \smath{\psi(x)}, defined by
$\psi(x) = \Gamma'(x)/\Gamma(x).$
Argument x is either a small float or a complex small float.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{digit}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{CharacterClass}
{\smath{\mbox{\bf digit}\opLeftPren{}\opRightPren{}} 
returns the class of all characters for 
which \spadfunFrom{digit?}{Character} is \smath{true}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{digit?}}\opLeftPren{}{\it character}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Character}
{\smath{\mbox{\bf digit?}\opLeftPren{}ch\opRightPren{}} 
tests if character \smath{c} is a digit character, that is, one of 0..9.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{digits}}\opLeftPren{}
{\it \opt{positiveInteger}}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->PositiveInteger}{FloatingPointSystem}
{\smath{\mbox{\bf digits}\opLeftPren{}\opRightPren{}} 
returns the current precision of floats in
numbers of digits.
\newitem
\smath{\mbox{\bf digits}\opLeftPren{}n\opRightPren{}} set the
\spadfunFrom{precision}{FloatingPointSystem} of floats
to \smath{n} digits.
\newitem
\smath{\mbox{\bf digits}\opLeftPren{}x\opRightPren{}} 
returns a stream of \smath{p}-adic
digits of p-adic integer
\smath{n}.
\seeType{PAdicInteger}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dihedral}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{ I -> SPOL RN    --dihedral group}{}{}
{\smath{\mbox{\bf dihedral}\opLeftPren{}n\opRightPren{}} 
is the cycle index of the
dihedral group of degree \smath{n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dihedralGroup}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(List(Integer))->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf dihedralGroup}\opLeftPren{}
[ i_1, \ldots, i_k]\opRightPren{}} constructs
the dihedral group of order \smath{2k} acting on the integers
\smath{i_1}, \ldots, \smath{i_k}. Note: duplicates in the list will be removed.
\newitem\smath{\mbox{\bf dihedralGroup}\opLeftPren{}n\opRightPren{}} 
constructs the dihedral group of order \smath{2n}
acting on integers \smath{1, \ldots, n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dilog}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LiouvillianFunctionCategory}
{\smath{\mbox{\bf dilog}\opLeftPren{}x\opRightPren{}} returns the 
dilogarithm of \smath{x}, that is,  \smath{\int {log(x) / (1 - x) dx}}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dim}}\opLeftPren{}{\it color}\opRightPren{}%
}%
}%
{1}{(Color)->\$}{Palette}
{\smath{\mbox{\bf dim}\opLeftPren{}c\opRightPren{}} 
sets the shade of a hue \smath{c}, above dark but
below bright.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dimension}}\opLeftPren{}
{\it \opt{various}}\opRightPren{}%
}%
}%
{0}{()->CardinalNumber}{VectorSpace}
{\smath{\mbox{\bf dimension}\opLeftPren{}\opRightPren{}\$R} 
returns the dimensionality of the vector space
or rank of Lie algebra \smath{R}.
\newitem\smath{\mbox{\bf dimension}\opLeftPren{}I\opRightPren{}} 
gives the dimension of the ideal \smath{I}.
\newitem\smath{\mbox{\bf dimension}\opLeftPren{}s\opRightPren{}} 
returns the dimension of the point category \smath{s}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dioSolve}}\opLeftPren{}{\it equation}\opRightPren{}%
}%
}%
{1}{(Equation(Expression(R)))->List(Equation(Expression(R)))}
{TransSolvePackage}
{\smath{\mbox{\bf dioSolve}\opLeftPren{}eq\opRightPren{}} 
computes a basis of all minimal solutions
for a linear homomogeneous Diophantine equation \smath{eq}, then
all minimal solutions of the inhomogeneous equation.
Alternatively, an expression \smath{u} may be given 
for \smath{eq} in which case the equation
\smath{eq} is defined as \smath{u=0}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{directory}}\opLeftPren{}
{\it filename}\opRightPren{}%
}%
}%
{1}{(\$)->String}{FileNameCategory}
{\smath{\mbox{\bf directory}\opLeftPren{}f\opRightPren{}} 
returns the directory part of the file name.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{directProduct}}\opLeftPren{}
{\it vector}\opRightPren{}%
}%
}%
{1}{(Vector(R))->\$}{DirectProductCategory}
{\smath{\mbox{\bf directProduct}\opLeftPren{}v\opRightPren{}} 
converts the vector \smath{v} to become a direct product
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{discreteLog}}\opLeftPren{}
{\it finiteFieldElement}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{FiniteFieldCategory}
{\smath{\mbox{\bf discreteLog}\opLeftPren{}a\opRightPren{}\$F} 
computes the discrete logarithm of \smath{a} with respect to 
\smath{\mbox{\bf primitiveElement}\opLeftPren{}\opRightPren{}\$F} 
of the field \smath{F}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{discreteLog}}\opLeftPren{}
{\it finiteFieldElement}, 
\allowbreak{}{\it  finiteFieldElement}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Union(NonNegativeInteger, "failed")}{FieldOfPrimeCharacteristic}
{\smath{\mbox{\bf discreteLog}\opLeftPren{}b, 
\allowbreak{} a\opRightPren{}} computes \smath{s} such that
\smath{b^s = a} if such an \smath{s} exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{discriminant}}\opLeftPren{}
{\it polynomial\opt{, symbol}}\opRightPren{}%
}%
}%
{0}{()->R}{FramedAlgebra}
{\smath{\mbox{\bf discriminant}\opLeftPren{}p\optinner{, x}\opRightPren{}} 
returns the discriminant of the polynomial
\smath{p} with respect to the variable \smath{x}.
If \smath{x} is univariate, the second argument may be omitted.
\newitem\smath{\mbox{\bf discriminant}\opLeftPren{}\opRightPren{}\$R}
returns \smath{\mbox{\bf determinant}\opLeftPren{}
{\mbox {\bf traceMatrix}}()\$R\opRightPren{}} of a
\spadtype{FramedAlgebra} domain \smath{R}.
\newitem\smath{\mbox{\bf discriminant}\opLeftPren{}
[ v_1, .., v_n]\opRightPren{}} returns \smath{\mbox{\bf determinant}
\opLeftPren{}traceMatrix([ v_1, .., v_n])\opRightPren{}} 
where the \smath{v_i} each have 
\smath{n} elements.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{display}}\opLeftPren{}
{\it text\opt{, width}}\opRightPren{}%
}%
}%
{1}{(\$)->Void}{ScriptFormulaFormat}
{\smath{\mbox{\bf display}\opLeftPren{}t\optinner{, w}\opRightPren{}},
where \smath{t} is either IBM SCRIPT Formula Format or \TeX{} text,
outputs \smath{t} so that each line has length \smath{\leq w}.
The default value of \smath{w} is that length set by
the system command \spadsyscom{)set output length}.
\newitem\smath{\mbox{\bf display}\opLeftPren{}op, 
\allowbreak{} f\opRightPren{}} attaches \smath{f} 
as the \mbox{\tt "\%display"} property
of \smath{op}.
\newitem
\smath{\mbox{\bf display}\opLeftPren{}op\opRightPren{}} 
returns the \mbox{\tt "\%display"} property of \smath{op} if it has one 
attached, and \mbox{\tt "failed"} otherwise.
\newitem Value \smath{f} either has type \spadsig{OutputForm}{OutputForm}
or else \spadsig{List(OutputForm)}{OutputForm}.
Argument \smath{op} must be unary.
Note: if \smath{op} has a \mbox{\tt "\%display"} 
property \smath{f} of the former type,
then \smath{op(a)} gets converted to \spadtype{OutputForm} as \smath{f(a)}.
If \smath{f} has the latter type,
then \smath{op(a_1, \ldots, a_n)} gets converted to
\spadtype{OutputForm} as \smath{f(a_1, \ldots, a_n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{distance}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Integer}{RecursiveAggregate}
{\smath{\mbox{\bf distance}\opLeftPren{}u, \allowbreak{} v\opRightPren{}},
where \smath{u} and \smath{v}
are recursive aggregates (for example, lists)
returns the path length (an integer) from node \smath{u} to \smath{v}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{distdfact}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  boolean}\opRightPren{}%
}%
}%
{2}{(FP, Boolean)->Record(cont:F, 
factors:List(Record(irr:FP, pow:Integer)))}{DistinctDegreeFactorize}
{\smath{\mbox{\bf distdfact}\opLeftPren{}p, 
\allowbreak{} squareFreeFlag\opRightPren{}} produces the complete
\typeout{check distdfact}
factorization of the polynomial \smath{p} returning an internal
data structure.
If argument \smath{squareFreeFlag} is \smath{true}, the polynomial
is assumed square free.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{distribute}}\opLeftPren{}
{\it expression\opt{, f}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ExpressionSpace}
{\smath{\mbox{\bf distribute}\opLeftPren{}f\optinner{, g}\opRightPren{}} 
expands all the kernels in
\smath{f} that contain \smath{g} in their arguments and that are
formally enclosed by a \spadfunFrom{box}{ExpressionSpace} or a
\spadfunFrom{paren}{ExpressionSpace} expression.
By default, \smath{g} is the list of all kernels in \smath{f}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{divide}}\opLeftPren{}{\it element}, 
\allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(quotient:\$, remainder:\$)}{EuclideanDomain}
{\smath{\mbox{\bf divide}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
divides \smath{x} by \smath{y} producing a
record containing a \smath{quotient} and \smath{remainder}, where
the remainder is smaller (see
\spadfunFrom{sizeLess?}{EuclideanDomain}) than the divisor
\smath{y}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{divideExponents}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->Union(\$, "failed")}
{UnivariatePolynomialCategory}
{\smath{\mbox{\bf divideExponents}\opLeftPren{}p, 
\allowbreak{} n\opRightPren{}} returns a new polynomial resulting
from dividing all exponents of the polynomial \smath{p} by the non
negative integer \smath{n}, or \mbox{\tt "failed"} if no exponent is
exactly divisible by \smath{n}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{divisors}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->List(Integer)}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf divisors}\opLeftPren{}i\opRightPren{}} 
returns a list of the divisors of integer
\smath{i}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{domain}}\opLeftPren{}
{\it typeAnyObject}\opRightPren{}%
}%
}%
{1}{(\$)->SExpression}{Any}
{\smath{\mbox{\bf domain}\opLeftPren{}a\opRightPren{}} 
returns the type of the original object that
was converted to \spadtype{Any}
as object of type \spadtype{SExpression}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{domainOf}}\opLeftPren{}
{\it typeAnyObject}\opRightPren{}%
}%
}%
{1}{(\$)->OutputForm}{Any}
{\smath{\mbox{\bf domainOf}\opLeftPren{}a\opRightPren{}} returns a 
printable form of the type of the
original type of \smath{a}, an object
of type \spadtype{Any}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{dot}}\opLeftPren{}{\it vector}, \allowbreak{}
{\it  vector}\opRightPren{}%
}%
}%
{2}{(\$, \$)->R}{DirectProductCategory}
{\smath{\mbox{\bf dot}\opLeftPren{}v_1, \allowbreak{} v_2\opRightPren{}} 
computes the inner product of the vectors
\smath{v_1} and \smath{v_2}, or calls \spadfun{error} if \smath{x}
and \smath{y} are not of the same length.
\newitem \smath{\mbox{\bf dot}\opLeftPren{}of\opRightPren{}}, 
where \smath{of} is an object of type
\spadtype{OutputForm} (normally unexposed), returns an output form
with one dot overhead\texht{ (\.{x})}{}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{doubleRank}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(A)->NonNegativeInteger}{AlgebraPackage}
{\smath{\mbox{\bf doubleRank}\opLeftPren{}x\opRightPren{}},
where \smath{x} is an element of a domain \smath{R}
of category \spadtype{FramedNonAssociativeAlgebra},
determines the number of linearly independent elements in
\smath{b_1 x}, \ldots, \smath{b_n x}, where 
\smath{b=[ b_1, \ldots, b_n]} is the
fixed basis for \smath{R}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{doublyTransitive?}}\opLeftPren{}\opRightPren{}%
}%
}%
{1}{(UP)->Boolean}{AlgFactor}
{\smath{\mbox{\bf doublyTransitive?}\opLeftPren{}p\opRightPren{}}
tests if polynomial \smath{p}, is irreducible over the field
\smath{K} generated by its coefficients, and if \smath{p(X)/(X -
a)} is irreducible over \smath{K(a)} where \smath{p(a) = 0}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{draw}}\opLeftPren{}{\it functionOrExpression}, 
\allowbreak{}{\it  range}\allowbreak $\,[$ , \allowbreak{}
{\it  options}$]$\opRightPren{}%
}%
}%
{2}{((DoubleFloat)->DoubleFloat, Segment(Float))->
TwoDimensionalViewport}{TopLevelDrawFunctionsForCompiledFunctions}
{\smath{f}, \smath{g}, and \smath{h} below denote user-defined
functions which map one or more \spadtype{DoubleFloat} values to a
\spadtype{DoubleFloat} value.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}f, 
\allowbreak{} a..b\opRightPren{}} draws the \twodim{} graph of 
\smath{y = f(x)} as \smath{x} 
ranges from \smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to
\smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}curve(f, g), 
\allowbreak{} a..b\opRightPren{}} draws the \twodim{} graph of
the parametric curve \smath{x = f(t), y = g(t)} as \smath{t}
ranges from \smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}f, 
\allowbreak{} a..b, \allowbreak{} c..d\opRightPren{}} 
draws the \threedim{} graph of
\smath{z = f(x, y)} as \smath{x} ranges from 
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} to
\smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
and \smath{y} ranges from \smath{\mbox{\bf min}\opLeftPren{}c, 
\allowbreak{} d\opRightPren{}} to
\smath{\mbox{\bf max}\opLeftPren{}c, \allowbreak{} d\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}curve(f, g, h), 
\allowbreak{} a..b\opRightPren{}} draws a \threedim{} graph
of the parametric curve \smath{x = f(t), y = g(t), z = h(t)} as
\smath{t} ranges from \smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}surface(f, g, h), 
\allowbreak{} a..b, \allowbreak{} c..d\opRightPren{}} draws the
\threedim{} graph of the parametric
surface \smath{x = f(u, v)}, \smath{y = g(u, v)}, 
\smath{z = h(u, v)} as \smath{u} ranges from 
\smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to 
\smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
and \smath{v} ranges from \smath{\mbox{\bf min}\opLeftPren{}c, 
\allowbreak{} d\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}c, 
\allowbreak{} d\opRightPren{}}.
\medbreak\bigopkey{Arguments \smath{f}, \smath{g}, and \smath{h}
below
denote an \spadtype{Expression} involving the variables indicated as arguments.
For example, \smath{f(x, y)} denotes an expression involving the
variables \smath{x}
and \smath{y}.}
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}f(x), 
\allowbreak{} x = a..b\opRightPren{}} draws the \twodim{} graph of
\smath{y = f(x)} as
\smath{x} ranges from \smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}curve(f(t), g(t)), 
\allowbreak{} t = a..b\opRightPren{}} draws the \twodim{} graph of the
parametric curve \smath{x = f(t), y = g(t)} as \smath{t} ranges from 
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} to 
\smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}f(x, y), \allowbreak{} x = a..b, 
\allowbreak{} y = c..d\opRightPren{}} draws the
\threedim{} graph of \smath{z = f(x, y)} as \smath{x} ranges from
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} to 
\smath{\mbox{\bf max}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} and \smath{y} 
ranges from
\smath{\mbox{\bf min}\opLeftPren{}c, \allowbreak{} d\opRightPren{}} to 
\smath{\mbox{\bf max}\opLeftPren{}c, \allowbreak{} d\opRightPren{}}.
\bigitem\smath{\mbox{\bf draw}\opLeftPren{}curve(f(t), g(t), h(t)), 
\allowbreak{} t = a..b\opRightPren{}} draws the
\threedim{} graph of the parametric curve \smath{x = f(t)},
\smath{y = g(t)}, \smath{z = h(t)} as \smath{t} ranges from
\smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}.
\bigitem\smath{{\bf draw}(surface(f(u, v), g(u, v), h(u, v)), u = a..b,
v = c..d)} draws the \threedim{} graph of the parametric surface
\smath{x = f(u, v)}, \smath{y = g(u, v)}, \smath{z = h(u, v)} as
\smath{u} ranges from \smath{\mbox{\bf min}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} and
\smath{v} ranges from \smath{\mbox{\bf min}\opLeftPren{}c, 
\allowbreak{} d\opRightPren{}} to \smath{\mbox{\bf max}\opLeftPren{}c, 
\allowbreak{} d\opRightPren{}}.
\medbreak Each of the \spadfun{draw} operations optionally take
options given as
extra arguments.
\smallbreak\opoption{adaptive}{true} turns on adaptive plotting.
\smallbreak\opoption{clip}{true} turns on \twodim{} clipping.
\smallbreak\opoption{colorFunction}{f} specifies the color based
on a function.
\smallbreak\opoption{coordinates}{p} specifies a change of
coordinate systems of point \smath{p}:
\smath{bipolar},
\smath{bipolarCylindrical},
\smath{conical},
\smath{elliptic},
\smath{ellipticCylindrical},
\smath{oblateSpheroidal},
\smath{parabolic},
\smath{parabolicCylindrical},
\smath{paraboloidal},
\smath{prolateSpheroidal},
\smath{spherical}, and
\smath{toroidal}
\smallbreak\opoption{curveColor}{p} specifies a color index 
for \twodim{} graph curves from the pallete \smath{p}.
\smallbreak\opoption{pointColor}{p} specifies a color index 
for \twodim{} graph points
from the palette \smath{p}.
\smallbreak\opoption{range}{[ a..b]} provides a user-specified range
for implicit curve plots.
\smallbreak\opoption{space}{sp} adds the current graph to 
\spadtype{ThreeSpace} object
\smath{sp}.
\smallbreak\opoption{style}{s} specifies the drawing style in
which the graph will be plotted: \smath{wire}, \smath{solid},
\smath{shade}, \smath{smooth}.
\smallbreak\opoption{title}{s} titles the graph with string \smath{s}.
\smallbreak\opoption{toScale}{true} causes the graph to be drawn to scale.
\smallbreak\opoption{tubePoints}{n} specifies the number of 
points \smath{n} defining
the circle which creates the tube around a \threedim{} curve. 
The default value is 6.
\smallbreak\opoption{tubeRadius}{r} specifies a \spadtype{Float} 
radius \smath{r}
for a tube plot around a \threedim{} curve.
\smallbreak\opoption{unit}{[ a, b]} marks off the units of a \twodim{} graph
in increments \smath{a} along the x-axis, \smath{b} along the y-axis.
\smallbreak\opoption{var1Steps}{n} indicates the number of 
subdivisions \smath{n}
of the first range variable.
\smallbreak\opoption{var2Steps}{n} indicates the number of
subdivisions \smath{n}
of the second range variable.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{drawToScale}}\opLeftPren{}
{\optArg{boolean}}\opRightPren{}%
}%
}%
{0}{()->Boolean}{GraphicsDefaults}
{\smath{\mbox{\bf drawToScale}\opLeftPren{}\opRightPren{}} 
tests if plots are currently to be drawn to scale.
\newitem\
\smath{\mbox{\bf drawToScale}\opLeftPren{}true\opRightPren{}} 
causes plots to be drawn to scale.
\smath{\mbox{\bf drawToScale}\opLeftPren{}false\opRightPren{}} 
causes plots to be drawn to fill up the
viewport window.
The default setting is \smath{false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{duplicates}}\opLeftPren{}
{\it dictionary}\opRightPren{}%
}%
}%
{1}{(\$)->List(Record(entry:S, count:NonNegativeInteger))}{MultiDictionary}
{\smath{\mbox{\bf duplicates}\opLeftPren{}d\opRightPren{}} 
returns a list of values which have
duplicates in \smath{d}}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{Ei}}\opLeftPren{}{\it variable}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LiouvillianFunctionCategory}
{\smath{\mbox{\bf Ei}\opLeftPren{}x\opRightPren{}} 
returns the exponential integral of \smath{x}:
\smath{\int exp(x)/x {\rm dx}}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eigenMatrix}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(Fraction(Polynomial(Fraction(Integer)))))->
Union(Matrix(Expression(Fraction(Integer))), 
\mbox{\tt "failed"})}{RadicalEigenPackage}
{\smath{\mbox{\bf eigenMatrix}\opLeftPren{}A\opRightPren{}} 
returns the matrix \smath{B} such that
\smath{BA(\mbox{\bf inverse } B)} is diagonal, or \mbox{\tt
"failed"} if no such
\smath{B} exists.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eigenvalues}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Fraction(Polynomial(Fraction(Integer))))}{EigenPackage}
{\smath{\mbox{\bf eigenvalues}\opLeftPren{}A\opRightPren{}},
where \smath{A} is a matrix with rational function coefficients,
returns the eigenvalues of the matrix \smath{A}
which are expressible as rational functions over the rational numbers.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eigenvector}}\opLeftPren{}
{\it eigenvalue}, \allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(Fraction(Integer))), 
Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Matrix(Fraction(Polynomial(Fraction(Integer)))))}
{EigenPackage}
{\smath{\mbox{\bf eigenvector}\opLeftPren{}eigval, 
\allowbreak{} A\opRightPren{}} returns the eigenvectors belonging
to the eigenvalue \smath{eigval} for the matrix \smath{A}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eigenvectors}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Union(Record(algrel:Fraction(Polynomial(Fraction(Integer))), 
algmult:Integer, 
algvec:List(Matrix(Fraction(Polynomial(Fraction(Integer)))))), 
Record(eigval:Fraction(Polynomial(Fraction(Integer))), eigmult:Integer, 
eigvec:List(Matrix(Fraction(Polynomial(Fraction(Integer))))))))}{EigenPackage}
{\smath{\mbox{\bf eigenvectors}\opLeftPren{}A\opRightPren{}} 
returns the eigenvalues and eigenvectors
for the matrix \smath{A}.
The rational eigenvalues and the corresponding eigenvectors are
explicitly computed.
The non-rational eigenvalues are defined via their minimal
polynomial.
Their corresponding eigenvectors are expressed in terms of a
``generic'' root of this polynomial.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{element?}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  ideal}\opRightPren{}%
}%
}%
{2}{(DPoly, \$)->Boolean}{PolynomialIdeals}
{\smath{\mbox{\bf element?}\opLeftPren{}f, \allowbreak{} I\opRightPren{}} 
tests if the polynomial \smath{f} belongs
to the ideal \smath{I}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{elementary}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{ I -> SPOL RN}{}{}
{\smath{\mbox{\bf elementary}\opLeftPren{}n\opRightPren{}} 
is the \eth{\smath{n}} elementary symmetric
function expressed in terms of power sums.
See \axiomType{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{elliptic}}\opLeftPren{}
{\it scaleFactor}\opRightPren{}%
}%
}%
{1}{(R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf elliptic}\opLeftPren{}r\opRightPren{}} 
returns a function for transforming elliptic
coordinates to Cartesian coordinates.
The function returned will map the point \smath{(u, v)} to \smath{x
= r \cosh(u) \cos(v)}, \smath{y = r \sinh(u) \sin(v)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ellipticCylindrical}}\opLeftPren{}
{\it scaleFactor}\opRightPren{}%
}%
}%
{1}{(R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf ellipticCylindrical}\opLeftPren{}r\opRightPren{}} 
returns a function for
transforming elliptic cylindrical coordinates to Cartesian
coordinates as a function of the scale factor \smath{r}.
The function returned will map the point \smath{(u, v, z)} to
\smath{x = r \cosh(u) \cos(v)}, \smath{y = r \sinh(u) \sin(v)},
\smath{z}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{elt}}\opLeftPren{}{\it structure}, \allowbreak{}
{\it  various}\allowbreak $\,[$ , \allowbreak{}
{\it  \ldots}$]$\opRightPren{}%
}%
}%
{1}{(\$)->R}{CartesianTensor}
{\opkey{\smath{\mbox{\bf elt}\opLeftPren{}u, \allowbreak{} v\opRightPren{}}, 
usually written as \smath{u.v} or
\smath{u(v)}, regards the structure \smath{u} as a function and
applies structure \smath{u} to argument \smath{v}.
Many types export \spadfun{elt} with multiple arguments;
\smath{\mbox{\bf elt}\opLeftPren{}u, \allowbreak{} v, 
\allowbreak{} w\ldots\opRightPren{}} is generally written
\smath{u(v, w\ldots)}.
The interpretation of \smath{u} depends on its type.
If \smath{u} is:}
\begin{simpleList}
\item an indexed aggregate such as a list, stream, vector, or string:
\smath{u.i}, \smath{1 \leq i \leq maxIndex(u)}, is equivalently
written \smath{u(i)} and
returns the \eth{\smath{i}} element of \smath{u}.
Also, \smath{u(i, y)} returns \smath{u(i)} if \smath{i} is an
appropriate index for
\smath{u}, and \smath{y} otherwise.
\item a linear aggregate:
\smath{u(i..j)} returns the aggregate of elements of \smath{u(k)}
for \smath{k=i, i+1, \ldots, j}
in that order.
\item a basic operator: \smath{u(x)} applies the unary operator
\smath{u} to \smath{x};
similarly, \smath{u.[x_1, \ldots, x_n]} applies the \smath{n}-ary operator
\smath{u} to \smath{x_1, \ldots, x_n}.
Also,
\smath{u(x, y)}, \smath{u(x, y, z)}, and \smath{u(x, y, z, w)} respectively
apply the binary, ternary, or 4-ary operator \smath{u} to arguments.
\item a univariate polynomial or rational function:
\smath{u(y)} evaluates the rational function or polynomial with
the distinguished variable replaced by the value of \smath{y};
this value may either be another rational function or polynomial
or a member of the underlying coefficient domain.
\item a list: \smath{u.first} is equivalent to 
\smath{\mbox{\bf first}\opLeftPren{}u\opRightPren{}} and returns
the first element of list \smath{u}.
Also, \smath{u.last} is equivalent to 
\smath{\mbox{\bf last}\opLeftPren{}u\opRightPren{}} and returns
the last element of
list \smath{u}.
Both of these call \spadfun{error} if \smath{u} is the empty list.
Similarly, \smath{u.rest} is equivalent to 
\smath{\mbox{\bf rest}\opLeftPren{}u\opRightPren{}} and
returns the list \smath{u}
beginning at its second element, or calls \spadfun{error} 
if \smath{u} has less than
two elements.
\item a library:
\smath{u(name)} returns the entry in the library stored under the
key \smath{name}.
\item a linear ordinary differential operator:
\smath{u(x)} applies the differential operator \smath{u} to the
value \smath{x}.
\item a matrix or two-dimensional array:
\smath{u(i, j\optinner{, x})}, \smath{1 \leq i \leq nrows(u), 
1 \leq j \leq ncols(m)}, returns the
element in the \eth{\smath{i}} row and \eth{\smath{j}} 
column of the matrix \smath{m}.
If the indices are out of range and an extra argument 
\smath{x} is provided,
then \smath{x} is returned; otherwise, \spadfun{error} is called.
Also, \smath{u([i_1, \ldots, i_m], [j_1, \ldots, j_m])} returns
the \smath{m}-by-\smath{n} matrix consisting of elements 
\smath{u(i_k, j_l)} of \smath{u}.
\item a permutation group:
\smath{u(i)} returns the \smath{i}-th generator of the group \smath{u}.
\item a point: \smath{u.i} returns the \eth{\smath{i}} component 
of the point \smath{u}.
\item a rewrite rule:
\smath{u(f\optinner{, n})} applies rewrite rule \smath{u} to 
expression \smath{f}
at most \smath{n} times, where \smath{n=\infty} by default.
When the left-hand side of \smath{u} matches a subexpression of \smath{f},
the subexpression is replaced by the right-hand side of \smath{u} 
producing a new \smath{f}.
After \smath{n} iterations or when no further match occurs, the 
transformed \smath{f}
is returned.
\item a ruleset:
\smath{u(f\optinner{, n})} applies ruleset \smath{u} to expression 
\smath{f} at most \smath{n}
times, where \smath{n=\infty} by default.
Similar to last case, except that on each iteration, each rule in 
the ruleset is
applied in turn in attempt to find a match.
\item an \axiomType{SExpression} \smath{(a_1, \ldots, a_n\quad{}.\quad{}b)}
(where \smath{b} denotes the \spadfun{cdr} of the last node):
\smath{u.i} returns \smath{a_i}; similarly
\smath{u.[i_1, \ldots, i_m]} returns \smath{(a_{i_1}, \ldots, a_{i_m})}.
\item a univariate series:
\smath{u(r)} returns the coefficient of the term of degree
\smath{r} in \smath{u}.
\item a symbol: \smath{u[a_1, \ldots, a_n]} returns \smath{u}
subscripted by \smath{a_1, \ldots, a_n}.
\item a cartesian tensor:
\smath{u(r)} gives a component of a rank 1 tensor;
\smath{u([i_1, \ldots, l_n])} gives a component of a rank \smath{n} tensor;
\smath{u()} gives the component of a rank 0 tensor.
Also: \smath{u(i, j)},
\smath{u(i, j, k)},
and \smath{u(i, j, k, l)} gives a component of a rank 2, 3, and 4
tensors respectively.
\item See also \axiomType{QuadraticForm},
\axiomType{FramedNonAssociativeAlgebra}, and
\axiomType{FunctionFieldCategory}.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{empty}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Aggregate}
{\smath{\mbox{\bf empty}\opLeftPren{}\opRightPren{}\$R} creates an 
aggregate of type \smath{R} with 0
elements.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{empty?}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Aggregate}
{\smath{\mbox{\bf empty?}\opLeftPren{}u\opRightPren{}} tests if aggregate 
\smath{u} has 0 elements.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{endOfFile?}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{TextFile}
{\smath{\mbox{\bf endOfFile?}\opLeftPren{}f\opRightPren{}} tests whether 
the file \smath{f} is
positioned after the end of all text.
If the file is open for output, then this test always returns
\smath{true}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{enqueue!}}\opLeftPren{}{\it value}, \allowbreak{}
{\it  queue}\opRightPren{}%
}%
}%
{2}{(S, \$)->S}{QueueAggregate}
{\smath{\mbox{\bf enqueue!}\opLeftPren{}x, \allowbreak{} q\opRightPren{}} 
inserts \smath{x} into the queue \smath{q}
at the back end.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{enterPointData}}\opLeftPren{}{\it space}, 
\allowbreak{}{\it  listOfPoints}\opRightPren{}%
}%
}%
{2}{(\$, List(Point(R)))->NonNegativeInteger}{ThreeSpace}
{\smath{\mbox{\bf enterPointData}\opLeftPren{}s, \allowbreak{} 
[p_0, \allowbreak{} p_1, \allowbreak{} \ldots, p_n]\opRightPren{}} 
adds a list of points
from \smath{p_0} through \smath{p_n} to the \axiomType{ThreeSpace}
\smath{s}, and returns the index of the start of the list.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{entry?}}\opLeftPren{}{\it value}, \allowbreak{}
{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(Entry, \$)->Boolean}{IndexedAggregate}
{\smath{\mbox{\bf entry?}\opLeftPren{}x, \allowbreak{} u\opRightPren{}},
where \smath{u} is an indexed aggregate
(such as a list, vector, or string),
tests if \smath{x} equals \smath{u . i} for some index \smath{i}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{epilogue}}\opLeftPren{}
{\it formattedObject}\opRightPren{}%
}%
}%
{1}{(\$)->List(String)}{ScriptFormulaFormat}
{\smath{\mbox{\bf epilogue}\opLeftPren{}t\opRightPren{}} extracts the 
epilogue section of an IBM
SCRIPT Formula Format or \TeX{} formatted object \smath{t}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eq}}\opLeftPren{}{\it sExpression}, \allowbreak{}
{\it  sExpression}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{SExpressionCategory}
{\smath{eq(s, t)}, for \axiomType{SExpression}s
\smath{s} and \smath{t} returns \smath{true} if EQ(\smath{s}, \smath{t})
is \smath{true} in Common Lisp.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eq?}}\opLeftPren{}{\it aggregate}, \allowbreak{}
{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{Aggregate}
{\smath{\mbox{\bf eq?}\opLeftPren{}u, \allowbreak{} v\opRightPren{}} 
tests if two aggregates \smath{u} and \smath{v}
are same objects
in the Axiom store.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{equality}}\opLeftPren{}
{\it operator}, \allowbreak{}{\it  function}\opRightPren{}%
}%
}%
{2}{(\$, (\$, \$)->Boolean)->\$}{BasicOperator}
{\smath{\mbox{\bf equality}\opLeftPren{}op, 
\allowbreak{} f\opRightPren{}} attaches \smath{f} as 
the \mbox{\tt "\%equal?"} property to
\smath{op}.
Argument \smath{f} must be a boolean-valued ``equality'' function defined
on \axiomType{BasicOperator} objects.
If \smath{op1} and \smath{op2} have the same name, and one of them has
an \mbox{\tt "\%equal?"} property \smath{f}, then 
\smath{f(op1, op2)} is called to
decide whether \smath{op1} and \smath{op2} should be considered equal.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{equation}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  expression}\opRightPren{}%
}%
}%
{2}{(S, S)->\$}{Equation}
{\smath{\mbox{\bf equation}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} creates the equation \smath{a = b}.
\newitem\smath{\mbox{\bf equation}\opLeftPren{}v, 
\allowbreak{} a..b\opRightPren{}},
also written: \smath{v=a..b},
creates a segment binding value with variable \smath{v} and
segment \smath{a..b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{erf}}\opLeftPren{}{\it variable}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LiouvillianFunctionCategory}
{\smath{\mbox{\bf erf}\opLeftPren{}x\opRightPren{}} 
returns the error function of \smath{x}:
\smath{{2 \over \sqrt(\pi)}\int {exp^{-x^2} dx}}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{error}}\opLeftPren{}
{\it string\opt{, string}}\opRightPren{}%
}%
}%
{1}{(List(String))->Exit}{ErrorFunctions}
{\smath{\mbox{\bf error}\opLeftPren{}msg\opRightPren{}} 
displays error message \smath{msg} and terminates.
Argument \smath{msg} is either a string or a list of strings.
\newitem\smath{\mbox{\bf error}\opLeftPren{}name, 
\allowbreak{} msg\opRightPren{}} is similar except that
the error message is preceded by a message saying that the
error occured in a function named \smath{name}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{euclideanGroebner}}\opLeftPren{}
{\it ideal\opt{, string, string}}\opRightPren{}%
}%
}%
{1}{(List(Dpol))->List(Dpol)}{EuclideanGroebnerBasisPackage}
{\smath{\mbox{\bf euclideanGroebner}\opLeftPren{}lp\optinner{, 
"info", "redcrit}\opRightPren{}} computes a Gr\"obner basis for a polynomial 
ideal over a Euclidean domain generated by the list of polynomials \smath{lp}.
If the string \mbox{\tt "info"} is given as a second argument,
a summary is given of the critical pairs.
If the string \mbox{\tt "redcrit"} is given as a third argument,
the critical pairs are printed.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{euclideanNormalForm}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  groebnerBasis}\opRightPren{}%
}%
}%
{2}{(Dpol, List(Dpol))->Dpol}{EuclideanGroebnerBasisPackage}
{\smath{\mbox{\bf euclideanNormalForm}\opLeftPren{}poly, 
\allowbreak{} gb\opRightPren{}} reduces the polynomial
\smath{poly} modulo the precomputed Gr\"obner basis \smath{gb}
giving a canonical representative of the residue class.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{euclideanSize}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{EuclideanDomain}
{\smath{\mbox{\bf euclideanSize}\opLeftPren{}x\opRightPren{}} 
returns the Euclidean size of the
element \smath{x},
or calls \spadfun{error} if \smath{x} is zero.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eulerPhi}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf eulerPhi}\opLeftPren{}n\opRightPren{}} 
returns the number of integers between 1 and
\smath{n} (including 1) which are relatively prime to \smath{n}.
This is the Euler phi function \smath{\phi(n)}, also called the
totient function.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{euler}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf euler}\opLeftPren{}n\opRightPren{}} 
returns the \eth{\smath{n}} Euler number.
This is \smath{2^n E(n, 1/2)}, where \smath{E(n, x)} is the
\eth{\smath{n}} Euler polynomial.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{eval}}\opLeftPren{}
{\it expression\opt{, options}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{FunctionSpace}
{\opkey{Many domains have forms of the \spadfun{eval}
defined. Here are some the most common forms.}
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}f\opRightPren{}} unquotes all the 
quoted operators in \smath{f}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}f, \allowbreak{} x = v\opRightPren{}} 
replaces symbol or expression \smath{x} by
\smath{v} in \smath{f};
if \smath{x} is an expression, it must be retractable to a single
\axiomType{Kernel}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}f, \allowbreak{} [x_1 = v_1, 
\allowbreak{} \ldots, x_n = v_n]\opRightPren{}} returns \smath{f}
with symbols
or expressions \smath{x_i}
replaced by \smath{v_i} in parallel;
if \smath{x_i} is an expression, it must be retractable to a
single \axiomType{Kernel}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}f, \allowbreak{} [x_1, \allowbreak{} 
\ldots, x_n]\opRightPren{}} unquotes all
the quoted operations in \smath{f} whose name is one of the \smath{x_i}.'s.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}f, \allowbreak{} x\opRightPren{}} 
unquotes all quoted operators in \smath{f}
whose name is \smath{x}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}e, \allowbreak{} s, 
\allowbreak{} f\opRightPren{}}
replaces every subexpression of \smath{e} of the form
\smath{s(a_1, \dots, a_n)} by \smath{f(a_1, \ldots, a_n)}.
The function \smath{f} can have type
\spadsig{Expression}{Expression} if \smath{s} is a unary operator;
otherwise \smath{f}
must have signature \spadsig{List(Expression)}{Expression}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}e, \allowbreak{} [s_1, 
\allowbreak{} \ldots, s_n], [f_1, \ldots, f_n]\opRightPren{}},
replaces every subexpression of \smath{e} of the form
\smath{s_i(a_1, \dots, a_{n_i})} by \smath{f_i(a_1, \ldots, a_{n_i})}.
If all the \smath{s_i}'s are unary operators, the functions
\smath{f_i} can have signature \spadsig{Expression}{Expression};
otherwise, the \smath{f_i} must have signature
\spadsig{List(Expression)}{Expression}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}p, \allowbreak{} el\opRightPren{}}, 
where \smath{p} is a permutation,
returns the image of element {\it el} under \smath{p}.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}s\opRightPren{}}, 
where \spad{s} is of type \axiomType{SymmetricPolynomial} with
rational number coefficients, returns the sum of the 
coefficients of a cycle index.
See \axiomType{CycleIndicators} for details.
\newitem
\smath{\mbox{\bf eval}\opLeftPren{}f, 
\allowbreak{} s\opRightPren{}}, where \spad{s} is of type 
\axiomType{SymmetricPolynomial}
with rational number coefficients and \spad{f} is a function of type
\spadsig{Integer}{Algebra Fraction Integer},
evaluates the cycle index s by applying
the function \spad{f} to each integer in a monomial partition,
forms their product and sums the results over all monomials.
See \axiomType{EvaluateCycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{evaluate}}\opLeftPren{}
{\it operator}, \allowbreak{}{\it  function}\opRightPren{}%
}%
}%
{2}{(BasicOperator, (A)->A)->BasicOperator}{BasicOperatorFunctions1}
{\smath{\mbox{\bf evaluate}\opLeftPren{}op\opRightPren{}} 
returns the value of the \mbox{\tt "\%eval"} property
of \axiomType{BasicOperator}
object \smath{op} if it has one, and \mbox{\tt "failed"} otherwise.
\newitem
\smath{\mbox{\bf evaluate}\opLeftPren{}op, 
\allowbreak{} f\opRightPren{}} attaches \smath{f} as the \mbox{\tt "\%eval"}
property of \smath{op}.
If \smath{op} has an \mbox{\tt "\%eval"} property \smath{f}, then applying
\smath{op} to a
returns the result of \smath{f(a)}.
If \smath{f} takes a single argument, then
applying \smath{op} to a value \smath{a} returns the result \smath{f(a)}.
If \smath{f} takes a list of arguments, then
applying \smath{op} to \smath{a_1, \ldots, a_n} returns the
result of \smath{f(a_1, \ldots, a_n)}.
\newitem
Argument \smath{f} may also be an anonymous function of
the form \smath{u +-> g(u)}. In this case,
\smath{g} {\it must} be additive,
that is, \smath{g(a + b) = g(a) + g(b)} for any
\smath{a} and \smath{b} in \smath{R}.
This implies that \smath{g(n a) = n g(a)} for any \smath{a}
in \smath{R} and integer \smath{n > 0}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{even?}}\opLeftPren{}
{\it integerNumber}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{IntegerNumberSystem}
{\smath{\mbox{\bf even?}\opLeftPren{}n\opRightPren{}} 
tests if integer \smath{n} is even.
\newitem
\smath{\mbox{\bf even?}\opLeftPren{}p\opRightPren{}} 
tests if permutation \smath{p} is an even
permutation, that is, that
the \smath{\mbox{\bf sign}\opLeftPren{}p) = 1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{every?}}\opLeftPren{}{\it predicate}, 
\allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->Boolean}{HomogeneousAggregate}
{\smath{\mbox{\bf every?}\opLeftPren{}pred, 
\allowbreak{} u\opRightPren{}} tests if {\it pred(x)} is \smath{true}
for all elements \smath{x} of \smath{u}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{exists?}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{FileNameCategory}
{\smath{\mbox{\bf exists?}\opLeftPren{}f\opRightPren{}} 
tests if the file \smath{f} exists in the file
system.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{exp}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{expIfCan}}\opLeftPren{}{\it x}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ElementaryFunctionCategory}
{\smath{\mbox{\bf exp}\opLeftPren{}x\opRightPren{}} 
returns {\tt \%e} to the power \smath{x}.
\newitem
\smath{\mbox{\bf expIfCan}\opLeftPren{}z\opRightPren{}} 
returns exp(\smath{z}) if possible, and
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{exp1}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Float}
{\smath{\mbox{\bf exp1}\opLeftPren{}\opRightPren{}\$R} returns exp 1: 
\smath{2.7182818284\ldots} either
a float or a small float according to whether \smath{R=} \axiomType{Float}
or \smath{R=} \axiomType{DoubleFloat}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{expand}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf expand}\opLeftPren{}f\opRightPren{}} performs the 
following expansions
on \axiomType{Expression} \smath{f:}
\begin{simpleList}
\item Logs of products are expanded into sums of logs.
\item Trigonometric and hyperbolic trigonometric functions of
sums are expanded into sums of products of trigonometric
and hyperbolic trigonometric functions.
\item Formal powers of the form \smath{(a/b)^c} are expanded into
\smath{a^c  b^{(-c)}}.
\end{simpleList}
\newitem
\smath{\mbox{\bf expand}\opLeftPren{}ir\opRightPren{}},
where \smath{ir} is an \axiomType{IntegrationResult},
returns the list of possible real functions corresponding to \smath{ir}.
\newitem
\smath{\mbox{\bf expand}\opLeftPren{}lseg\opRightPren{}},
where \smath{lseg} is a list of segments, returns a list with all segments
expanded.
For example, \code{expand [1..4, 7..9] = [1, 2, 3, 4, 7, 8, 9]}.
\newitem
\smath{\mbox{\bf expand}\opLeftPren{}l..h \mbox{ \tt by } k\opRightPren{}} 
returns
a list of explicit elements.
For example, \code{expand(1..5 by 2) = [1, 3, 5]}.
\newitem
\smath{\mbox{\bf expand}\opLeftPren{}f\opRightPren{}} 
returns an unfactored form of factored object \smath{f}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{expandLog}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf expandLog}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\mbox{\bf log}\opLeftPren{}a/b\opRightPren{}}
appearing in \axiomType{Expression} \smath{f} into \smath{\log(a) - \log(b)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{expandPower}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf expandPower}\opLeftPren{}f\opRightPren{}} 
converts every power \smath{(a/b)^c} appearing
in \axiomType{Expression} \smath{f} into \smath{a^c  b^{-c}}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{explicitEntries?}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{LazyStreamAggregate}
{\smath{\mbox{\bf explicitEntries?}\opLeftPren{}s\opRightPren{}} 
tests if the stream \smath{s} has
explicitly computed entries.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{explicitlyEmpty?}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{LazyStreamAggregate}
{\smath{\mbox{\bf explicitlyEmpty?}\opLeftPren{}s\opRightPren{}} 
tests if the stream is an (explicitly) empty stream.
Note: this is a null test which will not cause lazy evaluation.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{explicitlyFinite?}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{StreamAggregate}
{\smath{\mbox{\bf explicitlyFinite?}\opLeftPren{}s\opRightPren{}} 
tests if the stream \smath{s} has a finite
number of elements. Note: for many datatypes, 
\code{explicitlyFinite?(s) = not possiblyInfinite?(s)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{exponent}}\opLeftPren{}
{\it floatOrFactored}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{FloatingPointSystem}
{\smath{\mbox{\bf exponent}\opLeftPren{}fl\opRightPren{}} returns the
\spadfunFrom{exponent}{FloatingPointSystem} part of
a float or small float \smath{fl}.
\newitem
\smath{\mbox{\bf exponent}\opLeftPren{}u\opRightPren{}}, 
where \smath{u} is a factored object, returns the
exponent of the
first factor of \smath{u}, or 0 if the factored object 
consists solely of a unit.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{expressIdealMember}}\opLeftPren{}
{\it listOfIdeals}, \allowbreak{}{\it  ideal}\opRightPren{}%
}%
}%
{2}{(List(\$), \$)->Union(List(\$), "failed")}{PrincipalIdealDomain}
{\smath{\mbox{\bf expressIdealMember}\opLeftPren{}[f_1, \allowbreak{} 
\ldots, f_n], h\opRightPren{}} returns a representation of ideal \smath{h} 
as a linear combination of the ideals \smath{f_i} or \mbox{\tt "failed"} 
if \smath{h} is not in the ideal generated by the \smath{f_i}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{exptMod}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  nonNegativeInteger}, 
\allowbreak{}{\it  polynomial}
\allowbreak $\,[$ , \allowbreak{}{\it  prime}$]$\opRightPren{}%
}%
}%
{3}{(FP, NonNegativeInteger, FP)->FP}{DistinctDegreeFactorize}
{\smath{\mbox{\bf exptMod}\opLeftPren{}u, \allowbreak{} k, 
\allowbreak{} v\optinner{, p}\opRightPren{}}
raises the polynomial \smath{u} to the \eth{\smath{k}} 
power modulo the polynomial \smath{v}.
If a prime \smath{p} is given, the power is also computed modulo that prime.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{exquo}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, R)->Union(\$, "failed")}{ComplexCategory}
{\smath{\mbox{\bf exquo}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} either returns an element \smath{c} such that
\smath{cb=a} or \mbox{\tt "failed"} if no such element can be found.
Values \smath{a} and \smath{b} are members of a domain of category
\axiomType{IntegralDomain}.
\newitem\smath{\mbox{\bf exquo}\opLeftPren{}A, 
\allowbreak{} r\opRightPren{}} returns the exact quotient of the
elements of matrix \smath{A} by
coefficient \smath{r}, or calls \spadfun{error} if this is not
possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extend}}\opLeftPren{}
{\it stream}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->\$}{LazyStreamAggregate}
{\smath{\mbox{\bf extend}\opLeftPren{}ps, 
\allowbreak{} n\opRightPren{}}, where \smath{ps} is a power series,
causes all terms of \smath{ps} of degree \smath{\leq n} to be computed.
\newitem\smath{\mbox{\bf extend}\opLeftPren{}st, 
\allowbreak{} n\opRightPren{}}, where \smath{st} is a stream, causes
entries
to be computed so that \smath{st} has at least \smath{n}
explicit entries, or so that all entries of \smath{st} are finite with
length \smath{\leq n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extendedEuclidean}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  element}\allowbreak $\,[$ , \allowbreak{}
{\it  element}$]$\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(coef1:\$, coef2:\$, generator:\$)}{EuclideanDomain}
{\opkey{Argments \smath{x}, \smath{y}, and \smath{z} are members
of a domain of category \axiomType{EuclideanDomain}.}
\newitem\smath{\mbox{\bf extendedEuclidean}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} returns a record
\smath{rec} containing three fields: \smath{coef1}, \smath{coef2},
and \smath{generator} where \smath{rec.coef1*x+rec.coef2*y =
rec.generator} and \smath{rec.generator} is a \smath{gcd} of
\smath{x} and \smath{y}.
The \smath{gcd} is unique only up to associates if
{\tt canonicalUnitNormal} is not asserted.
Note: See \spadfun{principalIdeal} for a version of this operation
which accepts an arbitrary length list of arguments.
\newitem\smath{\mbox{\bf extendedEuclidean}\opLeftPren{}x, 
\allowbreak{} y, \allowbreak{} z\opRightPren{}} either returns a record
\smath{rec} of two fields \smath{coef1} and \smath{coef2} where
\smath{rec.coef1*x+rec.coef2*y=z}, and \mbox{\tt "failed"} if \smath{z}
cannot be expressed as such a linear combination of \smath{x} and
\smath{y}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extendedIntegrate}}\opLeftPren{}
{\it rationalFnct}, \allowbreak{}{\it  symbol}, \allowbreak{}{\it  
rationalFnct}\opRightPren{}%
}%
}%
{3}{(Fraction(Polynomial(F)), Symbol, Fraction(Polynomial(F)))->
Union(Record(ratpart:Fraction(Polynomial(F)), 
coeff:Fraction(Polynomial(F))), "failed")}
{RationalFunctionIntegration}
{\smath{\mbox{\bf extendedIntegrate}\opLeftPren{}f, \allowbreak{} x, 
\allowbreak{} g\opRightPren{}} returns fractions \smath{[h,
c]} such that \smath{dc/dx = 0} and \smath{dh/dx = f - cg} if
\smath{(h, c)} exist, and \mbox{\tt "failed"} otherwise.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extensionDegree}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->OnePointCompletion(PositiveInteger)}{ExtensionField}
{\smath{\mbox{\bf extensionDegree}\opLeftPren{}\opRightPren{}\$F} 
returns the degree of the field extension \smath{F}
if the extension is algebraic, and {\tt infinity} if it is not.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extension}}\opLeftPren{}{\it filename}\opRightPren{}%
}%
}%
{1}{(\$)->String}{FileNameCategory}
{\smath{\mbox{\bf extension}\opLeftPren{}fn\opRightPren{}} 
returns the type part of the file name
\smath{fn} as a string.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extract!}}\opLeftPren{}{\it bag}\opRightPren{}%
}%
}%
{1}{(\$)->S}{BagAggregate}
{\smath{\mbox{\bf extract!}\opLeftPren{}bg\opRightPren{}} 
destructively removes a (random) item from
bag \smath{bg}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extractBottom!}}\opLeftPren{}
{\it dequeue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{DequeueAggregate}
{\smath{\mbox{\bf extractBottom!}\opLeftPren{}d\opRightPren{}} 
destructively extracts the bottom
(back) element from the dequeue \smath{d}, or calls
\spadfun{error} if \smath{d} is empty.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{extractTop!}}\opLeftPren{}{\it dequeue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{DequeueAggregate}
{\smath{\mbox{\bf extractTop!}\opLeftPren{}d\opRightPren{}} 
destructively extracts the top (front)
element from the
dequeue \smath{d}, or calls \spadfun{error} if \smath{d} is empty.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{e}}\opLeftPren{}{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->\$}{CliffordAlgebra}
{\smath{\mbox{\bf e}\opLeftPren{}n\opRightPren{}} 
produces the appropriate unit element of a
\axiomType{CliffordAlgebra}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factor}}\opLeftPren{}
{\it polynomial\opt{, numbers}}\opRightPren{}%
}%
}%
{1}{(\$)->Factored(\$)}{UniqueFactorizationDomain}
{\smath{\mbox{\bf factor}\opLeftPren{}x\opRightPren{}} 
returns the factorization of \smath{x} into
irreducibles, where \smath{x} is a member of any domain of
category \axiomType{UniqueFactorizationDomain}.
\newitem\smath{\mbox{\bf factor}\opLeftPren{}p, 
\allowbreak{} lan\opRightPren{}}, where \smath{p} is a polynomial
and \smath{lan} is a list of algebraic numbers, factors \smath{p}
over the extension generated by the algebraic numbers given by the
list \smath{lan}.
\newitem\smath{\mbox{\bf factor}\opLeftPren{}upoly, 
\allowbreak{} prime\opRightPren{}}, where \smath{upoly} is a
univariate polynomial and \smath{prime} is a prime integer,
returns the list of factors of \smath{upoly} modulo the integer
prime \smath{p}, or calls \spadfun{error} if \smath{upoly} is not
square-free modulo \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorFraction}}\opLeftPren{}
{\it fraction}\opRightPren{}%
}%
}%
{1}{(Fraction(Polynomial(R)))->Fraction(Factored(Polynomial(R)))}
{RationalFunctionFactorizer}
{\smath{\mbox{\bf factorFraction}\opLeftPren{}r\opRightPren{}} 
factors the numerator and the
denominator of the polynomial fraction \smath{r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorGroebnerBasis}}\opLeftPren{}
{\it listOfPolynomials\opt{, boolean}}\opRightPren{}%
}%
}%
{1}{(List(Dpol))->List(List(Dpol))}{GroebnerFactorizationPackage}
{\smath{\mbox{\bf factorGroebnerBasis}\opLeftPren{}basis
\optinner{, flag}\opRightPren{}} checks
whether the \smath{basis} contains reducible polynomials and uses
these to split the \smath{basis}.
Information about partial results is given if a second argument of
\smath{true} is given.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorials}}\opLeftPren{}
{\it expression\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{CombinatorialOpsCategory}
{\smath{\mbox{\bf factorials}\opLeftPren{}f
\optinner{, x}\opRightPren{}} rewrites the permutations and
binomials in \smath{f} in terms of factorials.
If a symbol \smath{x} is given as a second argument,
the operation rewrites only those terms involving \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorial}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(I)->I}{IntegerCombinatoricFunctions}
{\smath{\mbox{\bf factorial}\opLeftPren{}n\opRightPren{}}, 
where \smath{n} is an integer, returns the
integer value of \smath{n!
= \prod\nolimits_1^n{i}}.
\newitem \smath{\mbox{\bf factorial}\opLeftPren{}n\opRightPren{}}, 
where n is an expression, returns a
formal expression denoting \smath{n!} Note: \smath{n!
= n (n-1)!} when \smath{n > 0}; also, \smath{0!
= 1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorList}}\opLeftPren{}
{\it factoredForm}\opRightPren{}%
}%
}%
{1}{(\$)->List(Record(flg:Union("nil", "sqfr", "irred", "prime"), 
fctr:R, xpnt:Integer))}{Factored}
{\smath{\mbox{\bf factorList}\opLeftPren{}f\opRightPren{}}, 
for a factored form \smath{f}, returns
list of records.
Each record corresponds to a factor of \smath{f} and has three
fields: \smath{flg}, \smath{fctr}, and \smath{xpnt}.
The \smath{fctr} lists the factor and \smath{xpnt}, the exponent.
The \smath{flg} is one of the strings: \mbox{\tt "nil"}, \mbox{\tt "sqfr"},
\mbox{\tt "irred"}, or \mbox{\tt "prime"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorPolynomial}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(SparseUnivariatePolynomial(\$))->
Factored(SparseUnivariatePolynomial(\$))}{PolynomialFactorizationExplicit}
{\smath{\mbox{\bf factorPolynomial}\opLeftPren{}p\opRightPren{}} 
returns the factorization
of a sparse univariate polynomial \smath{p} as a factored form.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factors}}\opLeftPren{}
{\it factoredForm}\opRightPren{}%
}%
}%
{1}{(\$)->List(Record(factor:R, exponent:Integer))}{Factored}
{\smath{\mbox{\bf factors}\opLeftPren{}u\opRightPren{}} returns a list of 
the factors of a factored
form \smath{u} in a form as a list suitable for iteration.
Each element in the list is a record containing both a
\smath{factor} and \smath{exponent} field.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorsOfCyclicGroupSize}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(Record(factor:Integer, exponent:Integer))}{FiniteFieldCategory}
{\smath{\mbox{\bf factorsOfCyclicGroupSize}\opLeftPren{}\opRightPren{}} 
returns the factorization of
\smath{\mbox{\bf size}\opLeftPren{})-1}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{factorSquareFreePolynomial}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(SparseUnivariatePolynomial(\$))->
Factored(SparseUnivariatePolynomial(\$))}{PolynomialFactorizationExplicit}
{\smath{\mbox{\bf factorSquareFreePolynomial}\opLeftPren{}p\opRightPren{}} 
factors the univariate
polynomial \smath{p} into irreducibles, where \smath{p} is known to
be square free and primitive with respect to its main variable.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fibonacci}}\opLeftPren{}
{\it nonNegativeInteger}\opRightPren{}%
}%
}%
{1}{(Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf fibonacci}\opLeftPren{}n\opRightPren{}} returns 
the \eth{\smath{n}} Fibonacci
number.
The Fibonacci numbers \smath{F[n]} are defined by \smath{F[0] =
F[1] = 1} and \smath{F[n] = F[n-1] + F[n-2]}.
The algorithm has running time \smath{O(\log(n)^3)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{filename}}\opLeftPren{}{\it directory}, 
\allowbreak{}{\it  name}, \allowbreak{}{\it  extension}\opRightPren{}%
}%
}%
{3}{(String, String, String)->\$}{FileNameCategory}
{\smath{\mbox{\bf filename}\opLeftPren{}d, \allowbreak{} n, 
\allowbreak{} e\opRightPren{}} creates a file name with string
\smath{d} as its directory, string \smath{n} as its name and
string \smath{e} as its extension.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fill!}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  value}\opRightPren{}%
}%
}%
{2}{(\$, Entry)->\$}{IndexedAggregate}
{\smath{\mbox{\bf fill!}\opLeftPren{}a, \allowbreak{} x\opRightPren{}} 
replaces each entry in aggregate \smath{a} by
\smath{x}.
The modified \smath{a} is returned.
If \smath{a} is a domain of category
\smath{TwoDimensionalArrayCategory} such as a matrix,
\smath{\mbox{\bf fill!}\opLeftPren{}a, \allowbreak{} x\opRightPren{}} 
sets every element of \smath{a} to \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{filterUntil}}\opLeftPren{}
{\it predicate}, \allowbreak{}{\it  stream}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->\$}{InfiniteTuple}
{\smath{\mbox{\bf filterUntil}\opLeftPren{}p, 
\allowbreak{} s\opRightPren{}} returns \smath{[x_0, x_1, \ldots, x_n]},
where stream \smath{s = [x_0, x_1, x_2, ..]} and 
\smath{n} is the smallest index
such that \smath{p(x_n) = true}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{filterWhile}}\opLeftPren{}
{\it predicate}, \allowbreak{}{\it  stream}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->\$}{Stream}
{\smath{\mbox{\bf filterWhile}\opLeftPren{}pred, 
\allowbreak{} s\opRightPren{}} returns \smath{[x_0, x_1, \ldots,
x_{(n-1)}]} where
\smath{s = [x_0, x_1, x_2, ..]} and
\smath{n} is the smallest index such that \smath{p(x_n) = false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{find}}\opLeftPren{}{\it predicate}, 
\allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->Union(S, "failed")}{Collection}
{\smath{\mbox{\bf find}\opLeftPren{}pred, \allowbreak{} u\opRightPren{}} 
returns the first \smath{x} in \smath{u}
such that \smath{\mbox{\bf pred}\opLeftPren{}x\opRightPren{}} 
is \smath{true}, and \mbox{\tt "failed"}
if no such \smath{x} exists.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{findCycle}}\opLeftPren{}
{\it nonNegativeInteger}, \allowbreak{}{\it  stream}\opRightPren{}%
}%
}%
{2}{(NonNegativeInteger, \$)->
Record(cycle?:Boolean, prefix:NonNegativeInteger, 
period:NonNegativeInteger)}{Stream}
{\smath{\mbox{\bf findCycle}\opLeftPren{}n, 
\allowbreak{} st\opRightPren{}} determines if stream \smath{st} is
periodic within \smath{n}
terms.
The operation returns a record with three fields: \smath{cycle?},
\smath{prefix}, and \smath{period}.
If \smath{cycle?} has value true,
\smath{period} denotes the period of the cycle,
and \smath{prefix} gives the number of terms in the stream before
the cycle begins.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{finite?}}\opLeftPren{}
{\it cardinalNumber}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{CardinalNumber}
{\smath{\mbox{\bf finite?}\opLeftPren{}f\opRightPren{}} 
tests if expression f is finite.
\newitem
\smath{\mbox{\bf finite?}\opLeftPren{}a\opRightPren{}} 
tests if cardinal number \smath{a} is a
finite cardinal, that is, an integer.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fintegrate}}\opLeftPren{}
{\it taylorSeries}, \allowbreak{}{\it  symbol}, \allowbreak{}
{\it  coefficient}\opRightPren{}%
}%
}%
{3}{(()->\$, Symbol, Coef)->\$}{TaylorSeries}
{\smath{\mbox{\bf fintegrate}\opLeftPren{}s, 
\allowbreak{} v, \allowbreak{} c\opRightPren{}} integrates the series \smath{s} with
respect to variable \smath{v} and having \smath{c} 
as the constant of integration.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{first}}\opLeftPren{}
{\it aggregate\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(\$)->Entry}{IndexedAggregate}
{\smath{\mbox{\bf first}\opLeftPren{}u\opRightPren{}} 
returns the first element \smath{x} of aggregate \smath{u}.
\newitem\smath{\mbox{\bf first}\opLeftPren{}u, 
\allowbreak{} n\opRightPren{}} returns a copy of the first \smath{n}
elements of \smath{u}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fixedPoint}}\opLeftPren{}
{\it function\opt{, positiveInteger}}\opRightPren{}%
}%
}%
{ (A->A) -> A}{}{}
{\smath{\mbox{\bf fixedPoint}\opLeftPren{}f\opRightPren{}},
a function of type \spadsig{A}{A},
is the fixed point of function \smath{f}.
That is, \smath{\mbox{\bf fixedPoint}\opLeftPren{}f) = 
f(\mbox{\bf fixedPoint}(f))}.
\newitem
\smath{\mbox{\bf fixedPoint}\opLeftPren{}f, \allowbreak{} n\opRightPren{}},
where \smath{f} is a function of type \spadsig{List(A)}{List(A)}
and \smath{n} is a positive integer, is the fixed point of function
\smath{f} which is assumed to transform a list of length
\smath{n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fixedPoints}}\opLeftPren{}
{\it permutation}\opRightPren{}%
}%
}%
{1}{(\$)->Set(S)}{Permutation}
{\smath{\mbox{\bf fixedPoints}\opLeftPren{}p\opRightPren{}} 
returns the points fixed by the permutation \smath{p}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{flagFactor}}\opLeftPren{}{\it base}, 
\allowbreak{}{\it  exponent}, \allowbreak{}{\it  flag}\opRightPren{}%
}%
}%
{3}{(R, Integer, Union("nil", "sqfr", "irred", "prime"))->\$}{Factored}
{\smath{\mbox{\bf flagFactor}\opLeftPren{}base, 
\allowbreak{} exponent, \allowbreak{} flag\opRightPren{}} 
creates a factored object 
with a single factor whose \smath{base} is asserted to be properly described 
by the information \smath{flag}:
one of the strings \mbox{\tt "nil"}, \mbox{\tt "sqfr"}, \mbox{\tt "irred"}, and \mbox{\tt "prime"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{flatten}}\opLeftPren{}{\it inputForm}\opRightPren{}%
}%
}%
{ $ -> $}{}{}
{\smath{\mbox{\bf flatten}\opLeftPren{}s\opRightPren{}} 
returns an input form corresponding to \smath{s} with
all the nested operations flattened to triples using new
local variables.
This operation is used to optimize compiled code.
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{flexible?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf flexible?}\opLeftPren{}\opRightPren{}\$R} 
tests if \smath{2 \mbox{\bf
associator}(a, b, a) = 0}
for all \smath{a}, \smath{b} in a domain \smath{R}
of category \axiomType{FiniteRankNonAssociativeAlgebra}.
Note: only this can be tested since, in general, it is not known
whether \smath{2a=0} implies \smath{a=0}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{flexibleArray}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf flexibleArray}\opLeftPren{}ls
\opRightPren{}} creates a flexible array from a list of
elements \smath{ls}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{float?}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}{\smath{
\mbox{\bf float?}\opLeftPren{}s\opRightPren{}} is \smath{true} if \smath{s} is 
an atom and belongs o \smath{Flt}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{float}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\allowbreak $\,[$ , 
\allowbreak{}{\it  positiveinteger}$]$\opRightPren{}%
}%
}%
{2}{(Integer, Integer)->\$}{FloatingPointSystem}
{\smath{\mbox{\bf float}\opLeftPren{}a, \allowbreak{} e\opRightPren{}} 
returns \smath{a {\tt base()}^e} as a float.
\newitem\smath{\mbox{\bf float}\opLeftPren{}a, \allowbreak{} e, 
\allowbreak{} b\opRightPren{}} returns \smath{a b ^ e} as a float.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{floor}}\opLeftPren{}
{\it rationalNumber}\opRightPren{}%
}%
}%
{1}{(\$)->D}{QuotientFieldCategory}
{\smath{\mbox{\bf floor}\opLeftPren{}fr\opRightPren{}},
where \smath{fr} is a fraction,
returns the largest integral element below \smath{fr}.
\newitem \smath{\mbox{\bf floor}\opLeftPren{}fl\opRightPren{}}, 
where \smath{fl} is a float,
returns the largest integer \smath{<= fl}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{formula}}\opLeftPren{}
{\it formulaFormat}\opRightPren{}%
}%
}%
{1}{(\$)->List(String)}{ScriptFormulaFormat}
{\smath{\mbox{\bf formula}\opLeftPren{}t\opRightPren{}} 
extracts the formula section of an IBM
SCRIPT Formula formatted object \smath{t}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fractionPart}}\opLeftPren{}
{\it fraction}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{QuotientFieldCategory}
{\smath{\mbox{\bf fractionPart}\opLeftPren{}x\opRightPren{}} 
returns the fractional part of \smath{x}.
Argument \smath{x} can be a fraction, a radix (binary, decimal, or
hexadecimal) expansion, or a float.
Note: \smath{x} = whole(\smath{x}) + fractionPart(\smath{x}).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fractRadix}}\opLeftPren{}
{\it listOfIntegers}, \allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{2}{(List(Integer), List(Integer))->\$}{RadixExpansion}
{\smath{\mbox{\bf fractRadix}\opLeftPren{}pre, 
\allowbreak{} cyc\opRightPren{}} creates a fractional radix expansion
from a list of prefix ragits and a list of cyclic ragits.
For example, \smath{\mbox{\bf fractRadix}\opLeftPren{}[1], 
\allowbreak{} [6]\opRightPren{}} will return
\smath{0.16666666\ldots}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{fractRagits}}\opLeftPren{}
{\it radixExpansion}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(Integer)}{RadixExpansion}
{\smath{\mbox{\bf fractRagits}\opLeftPren{}rx\opRightPren{}} 
returns the ragits of the fractional
part of a radix expansion as a stream of integers.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{freeOf?}}\opLeftPren{}{\it expression}, 
\allowbreak{}{\it  kernel}\opRightPren{}%
}%
}%
{2}{(\$, Symbol)->Boolean}{ExpressionSpace}
{\smath{\mbox{\bf freeOf?}\opLeftPren{}x, \allowbreak{} k\opRightPren{}} 
tests if expression \smath{x} does not
contain
any operator whose name is the symbol or kernel \smath{k}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{Frobenius}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ExtensionField}
{\smath{\mbox{\bf Frobenius}\opLeftPren{}a\opRightPren{}\$F} 
returns \smath{a^q} where \smath{q} is
the \smath{\mbox{\bf size}\opLeftPren{}\opRightPren{}\$F} 
of extension field \smath{F}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{front}}\opLeftPren{}{\it queue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{QueueAggregate}
{\smath{\mbox{\bf front}\opLeftPren{}q\opRightPren{}} 
returns the element at the front of the queue, or
calls \spadfun{error} if \smath{q} is empty.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{frst}}\opLeftPren{}{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->S}{LazyStreamAggregate}
{\smath{\mbox{\bf frst}\opLeftPren{}s\opRightPren{}} 
returns the first element of stream \smath{s}.
Warning: this function should only be called after a
\smath{empty?} test has been made since there is no error check.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{function}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  name}\allowbreak $\,[$ , \allowbreak{}
{\it  options}$]$\opRightPren{}%
}%
}%
{2}{(S, Symbol)->Symbol}{MakeFunction}
{\opkey{Most domains provide an operation which converts
objects to type \axiomType{InputForm}.
Argument \smath{e} below denotes an object from such a domain.
These operations create user-functions from already computed results.}
\newitem\smath{\mbox{\bf function}\opLeftPren{}e, \allowbreak{} f
\opRightPren{}} creates a function \smath{f() == e}.
\newitem\smath{\mbox{\bf function}\opLeftPren{}e, \allowbreak{} f, 
\allowbreak{} [x_1, \allowbreak{} \ldots, x_n]\opRightPren{}} 
creates a function 
\smath{f(x_1, \ldots, x_n) == e}.
\newitem\smath{\mbox{\bf function}\opLeftPren{}e, \allowbreak{} f, 
\allowbreak{} x\opRightPren{}} creates a function \smath{f(x) == e}.
\newitem\smath{\mbox{\bf function}\opLeftPren{}e, 
\allowbreak{} f, \allowbreak{} x, \allowbreak{} y\opRightPren{}} 
creates a function \smath{f(x, y) == e}.
\newitem\smath{\mbox{\bf function}\opLeftPren{}expr, 
\allowbreak{} [x_1, \allowbreak{} \ldots, x_n], f\opRightPren{}},
where \smath{expr} is an input form and
where \smath{f} and the \smath{x_i}'s are symbols,
returns the input form
corresponding to \smath{f(x_1, \ldots, x_n) == {\rm i}}.
See also \spadfun{unparse}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{Gamma}}\opLeftPren{}{\it smallFloat}\opRightPren{}%
}%
}%
{1}{(Complex(DoubleFloat))->Complex(DoubleFloat)}{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf Gamma}\opLeftPren{}x\opRightPren{}} is the Euler 
gamma function, \smath{\mbox{\bf Gamma}\opLeftPren{}x\opRightPren{}},
defined by
\smath{\Gamma(x) = \int\nolimits_0^\infty {t^{(x-1)}*exp(-t) dt}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{gcdPolynomial}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(SparseUnivariatePolynomial(\$), SparseUnivariatePolynomial(\$))->
SparseUnivariatePolynomial(\$)}{PolynomialFactorizationExplicit}
{\smath{\mbox{\bf gcdPolynomial}\opLeftPren{}p, \allowbreak{} q\opRightPren{}} returns the \spadfun{gcd} of the
univariate polynomials \smath{p} and \smath{q}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{gcd}}\opLeftPren{}
{\it element\opt{, element, element}}\opRightPren{}%
}%
}%
{1}{(List(\$))->\$}{GcdDomain}
{\smath{\mbox{\bf gcd}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
returns the greatest common divisor of \smath{x} and \smath{y}.
Arguments \smath{x} and \smath{y} are elements of a domain of
category \smath{GcdDomain}.
\newitem\smath{\mbox{\bf gcd}\opLeftPren{}[x_1, 
\allowbreak{} \ldots, x_n]\opRightPren{}} returns the
common \smath{gcd} of the elements of the list of \smath{x_i}.
\newitem\smath{\mbox{\bf gcd}\opLeftPren{}p_1, \allowbreak{} p_2, 
\allowbreak{} prime\opRightPren{}} computes the \smath{gcd} of the univariate
polynomials \smath{p_1} and \smath{p_2} modulo the prime integer 
\smath{prime}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{generalizedContinuumHypothesisAssumed?}}
\opLeftPren{}{\it \opt{bool}}\opRightPren{}%
}%
}%
{0}{()->Boolean}{CardinalNumber}
{\smath{\mbox{\bf generalizedContinuumHypothesisAssumed?}
\opLeftPren{}\opRightPren{}} tests if the hypothesis is currently assumed.
\newitem
\smath{\mbox{\bf generalizedContinuumHypothesisAssumed}
\opLeftPren{}bool\opRightPren{}} dictates
that the hypothesis is or is not to be assumed, according to
whether \smath{bool} is true or false.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{generalPosition}}\opLeftPren{}
{\it ideal}, \allowbreak{}{\it  listOfVariables}\opRightPren{}%
}%
}%
{2}{(\$, List(OrderedVariableList(vl)))->
Record(mval:Matrix(F), invmval:Matrix(F), genIdeal:\$)}{PolynomialIdeals}
{\smath{\mbox{\bf generalPosition}\opLeftPren{}I, 
\allowbreak{} listvar\opRightPren{}} performs a random linear
transformation on the variables in \smath{listvar} and returns
the transformed ideal \smath{I} along with the change of basis matrix.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{generate}}\opLeftPren{}
{\it function\opt{, element}}\opRightPren{}%
}%
}%
{1}{(()->S)->\$}{Stream}
{\smath{\mbox{\bf generate}\opLeftPren{}f\opRightPren{}},
where \smath{f} is a function of no arguments,
creates an infinite stream all of whose elements are equal to
the value of \smath{f()}. Note: \smath{\mbox{\bf generate}
\opLeftPren{}f) = [f(), f(), f(), \ldots]}.
\newitem\smath{\mbox{\bf generate}\opLeftPren{}f, 
\allowbreak{} x\opRightPren{}},
where \smath{f} is a function of one argument,
creates an infinite stream whose first element is \smath{x}
and whose \eth{\smath{n}} element (\smath{n > 1}) is \smath{f} applied to the
previous element.
Note: \smath{\mbox{\bf generate}\opLeftPren{}f, x) = 
[x, f(x), f(f(x)), \ldots]}.
\newitem See also \axiomType{HallBasis}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{generator}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf generator}\opLeftPren{}\opRightPren{}\$R} returns 
a root of the defining polynomial
of a domain of category \axiomType{FiniteAlgebraicExtensionField} \smath{R}.
This element generates the field as an algebra over the ground field.
\newitem
See also \axiomType{MonogenicAlgebra} and \axiomType{FreeNilpotentLie}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{generators}}\opLeftPren{}{\it ideal}\opRightPren{}%
}%
}%
{1}{(\$)->List(DPoly)}{PolynomialIdeals}
{\smath{\mbox{\bf generators}\opLeftPren{}I\opRightPren{}} returns 
a list of generators for the ideal \smath{I}.
\newitem\smath{\mbox{\bf generators}\opLeftPren{}gp\opRightPren{}} 
returns the generators of a permutation
group {\it gp}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{genus}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->NonNegativeInteger}{FunctionFieldCategory}
{\smath{\mbox{\bf genus}\opLeftPren{}\opRightPren{}}{\bf \$}\smath{R} 
returns the genus of
the algebraic function field \smath{R}.
If \smath{R} has several
absolutely irreducible components, then the genus of one of them is
returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{getMultiplicationMatrix}}\opLeftPren{}\opRightPren{}%
 \optand \mbox{\axiomFun{getMultiplicationTable}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Matrix(PrimeField(p))}{FiniteFieldNormalBasis}
{\smath{\mbox{\bf getMultiplicationMatrix}\opLeftPren{}\opRightPren{}\$R} 
returns a matrix multiplication table
for domain \axiomType{FiniteFieldNormalBasis(p, n)},
a finite extension field of degree \smath{n} over the domain
\axiomType{PrimeField(p)} with \smath{p} elements.
Each element of the matrix is a member of the underlying prime field.
\newitem
\smath{\mbox{\bf getMultiplicationTable}\opLeftPren{}\opRightPren{}\$R} 
is similar except that the
multiplication table for the normal basis of the field
is represented by a vector of lists of records, each record
having two fields: \smath{value}, an element of the prime field over
which the domain is built, and \smath{index}, a small integer.
This table is used to perform multiplications between field elements.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{getVariableOrder}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Record(high:List(Symbol), low:List(Symbol))}
{UserDefinedVariableOrdering}
{\smath{\mbox{\bf getVariableOrder}\opLeftPren{}\opRightPren{}} 
returns \smath{[[b_1, \ldots, b_m],
[a_1, \ldots, a_n] ]} such that the ordering on the variables was given
by \smath{\mbox{\bf setVariableOrder}\opLeftPren{}[b_1, 
\allowbreak{} \ldots, b_m], [a_1, \ldots, a_n]\opRightPren{}}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{getZechTable}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->PrimitiveArray(SingleInteger)}{FiniteFieldCyclicGroup}
{\smath{\mbox{\bf getZechTable}\opLeftPren{}\opRightPren{}\$F} 
returns the Zech logarithm table of the
\index{Zech logarithm}
field
\smath{F} where \smath{F} is some domain
\axiomType{FiniteFieldCyclicGroup(p, extdeg)}.
This table is used to perform additions in the field quickly.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{gramschmidt}}\opLeftPren{}
{\it listOfMatrices}\opRightPren{}%
}%
}%
{1}{(List(Matrix(Expression(Fraction(Integer)))))->
List(Matrix(Expression(Fraction(Integer))))}{RadicalEigenPackage}
{\opkey{Argument \smath{lv} has the form of a list of matrices of
elements of type \axiomType{Expression}.}
\newitem
\smath{\mbox{\bf gramschmidt}\opLeftPren{}lv\opRightPren{}} 
converts the list of column vectors
\smath{lv} into a set of orthogonal column vectors of Euclidean
length 1 using the Gram-Schmidt algorithm.
\index{Gram-Schmidt algorithm}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{graphs}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{ I -> SPOL RN}{}{}
{\smath{\mbox{\bf graphs}\opLeftPren{}n\opRightPren{}} 
is the cycle index of the group induced on
the edges of a graph by applying the symmetric function to the
\smath{n} nodes.
See \axiomType{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{green}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Color}
{\smath{\mbox{\bf green}\opLeftPren{}\opRightPren{}} 
returns the position of the green hue from total hues.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{groebner}}\opLeftPren{}
{\it listOfPolynomials}\opRightPren{}%
}%
}%
{1}{(List(Dpol))->List(Dpol)}{GroebnerPackage}
{\smath{\mbox{\bf groebner}\opLeftPren{}lp\opRightPren{}} 
computes a Gr\"obner basis for a polynomial
ideal generated by the list of polynomials \smath{lp}.
\newitem \smath{\mbox{\bf groebner}\opLeftPren{}I\opRightPren{}} 
returns a set of generators of ideal
\smath{I} that are a Gr\"obner basis for \smath{I}.
\newitem \smath{\mbox{\bf groebner}\opLeftPren{}lp, \allowbreak{} 
infoflag\opRightPren{}} computes a Gr\"obner basis
for a polynomial ideal generated by the list of polynomials
\smath{lp}.
Argument \smath{infoflag} is used to get information on the
computation.
If \smath{infoflag} is \mbox{\tt "info"}, then summary information 
is displayed for
each s-polynomial generated.
If \smath{infoflag} is \mbox{\tt "redcrit"}, the reduced critical pairs are
displayed.
To get the display of both kinds of information, use
\smath{\mbox{\bf groebner}\opLeftPren{}lp, \allowbreak{} "info", 
\allowbreak{} "redcrit"\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{groebner?}}\opLeftPren{}{\it ideal}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{PolynomialIdeals}
{\smath{\mbox{\bf groebner?}\opLeftPren{}I\opRightPren{}} 
tests if the generators of the ideal
\smath{I} are a Gr\"obner basis.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{groebnerIdeal}}\opLeftPren{}
{\it listOfPolynomials}\opRightPren{}%
}%
}%
{1}{(List(DPoly))->\$}{PolynomialIdeals}
{\smath{\mbox{\bf groebnerIdeal}\opLeftPren{}lp\opRightPren{}} 
constructs the ideal generated by the
list of
polynomials \smath{lp} assumed to be a Gr\"obner basis.
Note: this operation avoids a Gr\"obner basis computation.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{groebnerFactorize}}\opLeftPren{}
{\it listOfPolynomials\opt{options}}\opRightPren{}%
}%
}%
{1}{(List(Dpol))->List(List(Dpol))}{GroebnerFactorizationPackage}
{\smath{\mbox{\bf groebnerFactorize}\opLeftPren{}lp
\optinner{, bool}\opRightPren{}} returns
a list of list of polynomials, each inner list denoting a Gr\"obner basis.
The union of the solutions of the bases is the solution of the system of
equations given by \smath{lp}.
Information about partial results is printed if a
second argument is given with value \smath{true}.
\newitem
\smath{\mbox{\bf groebnerFactorize}\opLeftPren{}lp, 
\allowbreak{} nonZeroRestrictions\optinner{, bool}\opRightPren{}},
where \smath{nonZeroRestrictions} is a list of polynomials, is similar.
Here, however, the solutions to the system of equations are computed
under the restriction that the polynomials in the second argument
do not vanish.
Information about partial results is printed if a
third argument with value \smath{true} is given.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ground}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{ground?}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf ground}\opLeftPren{}p\opRightPren{}} 
retracts expression polynomial \smath{p} to the coefficient ring, or
calls \spadfun{error} if such a retraction is not possible.
\newitem
\smath{\mbox{\bf ground?}\opLeftPren{}p\opRightPren{}} 
tests if an expression or polynomial \smath{p} is a member 
of the coefficient ring.
\seeAlso{\spadfun{ground?}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{harmonic}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(Integer)->Fraction(Integer)}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf harmonic}\opLeftPren{}n\opRightPren{}} 
returns the \eth{\smath{n}} harmonic number, defined by
\smath{H[n] = \sum\nolimits_{k=1}^n {1/k}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{has}}\opLeftPren{}
{\it domain}, \allowbreak{}{\it  property}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf has}\opLeftPren{}R, \allowbreak{} prop\opRightPren{}} tests if domain \smath{R} has
property \smath{prop}.
Argument \smath{prop} is either a category, operation, an attribute,
or a combination of these.
For example, \code{Integer has Ring}
and \code{Integer has commutative("*")}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{has?}}\opLeftPren{}
{\it operation}, \allowbreak{}{\it  property}\opRightPren{}%
}%
}%
{2}{(\$, String)->Boolean}{BasicOperator}
{\smath{\mbox{\bf has?}\opLeftPren{}op, 
\allowbreak{} s\opRightPren{}} tests if property \smath{s} is attached to
\smath{op}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hash}}\opLeftPren{}{\it number}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf hash}\opLeftPren{}n\opRightPren{}} 
returns the hash code for \smath{n},
an integer or a float.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hasHi}}\opLeftPren{}
{\it segment}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{UniversalSegment}
{\smath{\mbox{\bf hasHi}\opLeftPren{}seg\opRightPren{}} 
tests whether the segment \smath{seg} has an
upper bound.
For example, \smath{\mbox{\bf hasHi}\opLeftPren{}1..) = false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hasSolution?}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  vector}\opRightPren{}%
}%
}%
{2}{(M, Col)->Boolean}{LinearSystemMatrixPackage}
{\smath{\mbox{\bf hasSolution?}\opLeftPren{}A, 
\allowbreak{} B\opRightPren{}} tests if the linear 
system \smath{AX = B} has a solution,
where \smath{A} is a matrix and \smath{B} is a (column) vector.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hconcat}}\opLeftPren{}
{\it outputForms\opt{, outputForm}}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf hconcat}\opLeftPren{}o_1, 
\allowbreak{} o_2\opRightPren{}}, where \smath{o_1} and \smath{o_2} are
objects of type \axiomType{OutputForm} (normally unexposed),
returns an output form for the horizontal concatenation of forms
\smath{o_1} and \smath{o_2}.
\newitem
\smath{\mbox{\bf hconcat}\opLeftPren{}lof\opRightPren{}},
where \smath{lof} is a list of objects of type
\axiomType{OutputForm} (normally unexposed),
returns an output form for the horizontal concatenation of the
elements of \smath{lof}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{heap}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{2}{((S, S)->Boolean, V)->V}{FiniteLinearAggregateSort}
{\smath{\mbox{\bf heap}\opLeftPren{}ls\opRightPren{}} 
creates a \axiomType{Heap} of elements consisting
of the elements of \smath{ls}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{heapSort}}\opLeftPren{}
{\it predicate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S, S)->Boolean, V)->V}{FiniteLinearAggregateSort}
{\smath{\mbox{\bf heapSort}\opLeftPren{}pred, 
\allowbreak{} agg\opRightPren{}} sorts the aggregate agg with the
ordering function \smath{pred} using the heapsort algorithm.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{height}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{ExpressionSpace}
{\smath{\mbox{\bf height}\opLeftPren{}f\opRightPren{}}, 
where \smath{f} is an expression, returns the
highest nesting level appearing in \smath{f}.
Constants have height 0.
Symbols have height 1.
For any operator \smath{op} and expressions \smath{f_1}, \ldots,
\smath{f_n},
\smath{op(f_1, \ldots, f_n)} has height equal to \smath{1 +
max(height(f_1), \ldots, height(f_n))}.
\newitem\smath{\mbox{\bf height}\opLeftPren{}d\opRightPren{}} 
returns the number of elements in
dequeue \smath{d}.
Note: \smath{\mbox{\bf height}\opLeftPren{}d) = \# d}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hermiteH}}\opLeftPren{}
{\it nonNegativeInteger}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(NonNegativeInteger, R)->R}{OrthogonalPolynomialFunctions}
{\smath{\mbox{\bf hermiteH}\opLeftPren{}n, 
\allowbreak{} x\opRightPren{}} is the \eth{\smath{n}} Hermite polynomial,
\smath{H[n](x)}, defined by
\smath{\mbox{\bf exp}\opLeftPren{}2 t x-t^2) = \sum
\nolimits_{n=0}^\infty{H[n](x)t^n/n!}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hexDigit}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{CharacterClass}
{\smath{\mbox{\bf hexDigit}\opLeftPren{}\opRightPren{}} 
returns the class of all characters for which
\spadfunFrom{hexDigit?}{Character} is \smath{true}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hexDigit?}}\opLeftPren{}
{\it character}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Character}
{\smath{\mbox{\bf hexDigit?}\opLeftPren{}c\opRightPren{}} 
tests if \smath{c} is a hexadecimal numeral,
that is, one of 0..9, a..\smath{f} or A..\smath{F}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hex}}\opLeftPren{}{\it rationalNumber}\opRightPren{}%
}%
}%
{1}{(Fraction(Integer))->\$}{HexadecimalExpansion}
{\smath{\mbox{\bf hex}\opLeftPren{}r\opRightPren{}} 
converts a rational number to a hexadecimal
expansion.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hi}}\opLeftPren{}{\it segment}\opRightPren{}%
}%
}%
{1}{(\$)->S}{SegmentCategory}
{\smath{\mbox{\bf hi}\opLeftPren{}s\opRightPren{}} 
returns the second endpoint of segment \smath{s}.
For example, \smath{\mbox{\bf hi}\opLeftPren{}l..h) = h}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{horizConcat}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{MatrixCategory}
{\smath{\mbox{\bf horizConcat}\opLeftPren{}x, 
\allowbreak{} y\opRightPren{}} horizontally concatenates two matrices
with an equal number of rows.
The entries of \smath{y} appear to the right of the entries of
\smath{x}.
The operation calls \spadfun{error} if the matrices do not have the 
same number of rows.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{htrigs}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf htrigs}\opLeftPren{}f\opRightPren{}} converts all 
the exponentials in expression \smath{f} into hyperbolic sines and cosines.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hue}}\opLeftPren{}{\it palette}\opRightPren{}%
}%
}%
{1}{(\$)->Color}{Palette}
{\smath{\mbox{\bf hue}\opLeftPren{}p\opRightPren{}} returns 
the hue field of the indicated palette \smath{p}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hue}}\opLeftPren{}{\it color}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{Color}
{\smath{\mbox{\bf hue}\opLeftPren{}c\opRightPren{}} returns 
the hue index of the indicated color \smath{c}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{hypergeometric0F1}}\opLeftPren{}
{\it complexDF}, \allowbreak{}{\it  complexSF}\opRightPren{}%
}%
}%
{2}{(Complex(DoubleFloat), Complex(DoubleFloat))->Complex(DoubleFloat)}
{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf hypergeometric0F1}\opLeftPren{}c, 
\allowbreak{} z\opRightPren{}} is the hypergeometric function 
\smath{0F1(c; z)}.
Arguments \smath{c} and \smath{z} are both either small floats
or complex small floats.}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ideal}}\opLeftPren{}{\it polyList}\opRightPren{}%
}%
}%
{1}{(List(DPoly))->\$}{PolynomialIdeals}
{\smath{\mbox{\bf ideal}\opLeftPren{}polyList\opRightPren{}} 
constructs the ideal generated by the
list of polynomials \smath{polyList}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{imag}}\opLeftPren{}{\it expression}\opRightPren{}%
 \optand \mbox{\axiomFun{imagi}}\opLeftPren{}
{\it quaternionOrOctonion}\opRightPren{}%
 \opand \mbox{\axiomFun{imagI}}\opLeftPren{}{\it octonion}\opRightPren{}%
}%
}%
{1}{(\$)->R}{OctonionCategory}
{\smath{\mbox{\bf imag}\opLeftPren{}x\opRightPren{}} extracts the 
imaginary part of a complex value or
expression \smath{x}.
\newitem
\smath{\mbox{\bf imagI}\opLeftPren{}q\opRightPren{}} extracts the 
\smath{i} part of quaternion \smath{q}.
Similarly, operations \spadfun{imagJ},
and \spadfun{imagK} are used to extract the \smath{j} and \smath{k} parts.
\newitem
\smath{\mbox{\bf imagi}\opLeftPren{}o\opRightPren{}} extracts the 
\smath{i} part of octonion \smath{o}.
Similarly, \spadfun{imagj}, \spadfun{imagk}, \spadfun{imagE},
\spadfun{imagI}, \spadfun{imagJ}, and \spadfun{imagK} are used to extract 
other parts.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{implies}}\opLeftPren{}{\it boolean}, \allowbreak{}
{\it  boolean}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{Boolean}
{\smath{\mbox{\bf implies}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
tests if boolean value \smath{a}
implies boolean value \smath{b}. The
result is \smath{true} except when \smath{a} is \smath{true}
and \smath{b} is \smath{false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{in?}}\opLeftPren{}{\it ideal}, \allowbreak{}
{\it  ideal}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{PolynomialIdeals}
{\smath{\mbox{\bf in?}\opLeftPren{}I, \allowbreak{} J\opRightPren{}} 
tests if the ideal \smath{I} is contained in the ideal \smath{J}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inHallBasis}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  integer}, \allowbreak{}
{\it  integer}\opRightPren{}%
}%
}%
{4}{(Integer, Integer, Integer, Integer)->Boolean}{HallBasis}
{\smath{inHallBasis?(n, leftCandidate, rightCandidate,
left)} tests to see if a new element should be added to the
\smath{P}.
Hall basis being constructed.
The list \smath{[leftCandidate, wt, rightCandidate]} is included in
the basis if in the unique factorization of
\smath{rightCandidate}, we have left factor \smath{leftOfRight}, and
\smath{leftOfRight <= leftCandidate}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{increasePrecision}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->PositiveInteger}{FloatingPointSystem}
{\smath{\mbox{\bf increasePrecision}\opLeftPren{}n\opRightPren{}}
increases the current \spadfunFrom{precision}{FloatingPointSystem}
by \smath{n} decimal digits.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{index}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->\$}{Finite}
{\smath{\mbox{\bf index}\opLeftPren{}i\opRightPren{}} takes a 
positive integer \smath{i} less than or
equal to \smath{\mbox{\bf size}\opLeftPren{}\opRightPren{}} and
returns the \eth{\smath{i}} element of the set.
This operation establishes a bijection between
the elements of the finite set and \smath{1..{\mbox {\bf size}}()}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{index?}}\opLeftPren{}{\it index}, 
\allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(Index, \$)->Boolean}{IndexedAggregate}
{\smath{\mbox{\bf index?}\opLeftPren{}i, \allowbreak{} u\opRightPren{}} 
tests if \smath{i} is an index of
aggregate \smath{u}.
For example, \code{index?(2, [1, 2, 3])} is \smath{true}
but \code{index?(4, [1, 2, 3])} is \smath{false}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{infieldIntegrate}}\opLeftPren{}
{\it rationalFunction}, \allowbreak{}{\it  symbol}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(F)), Symbol)->
Union(Fraction(Polynomial(F)), "failed")}{RationalFunctionIntegration}
{\smath{\mbox{\bf infieldIntegrate}\opLeftPren{}f, 
\allowbreak{} x\opRightPren{}},
where \smath{f} is a fraction of polynomials, returns a fraction
\smath{g} such that \smath{{dg\over dx} = f} if \smath{g} exists,
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{infinite?}}\opLeftPren{}
{\it orderedCompletion}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{OrderedCompletion}
{\smath{\mbox{\bf infinite?}\opLeftPren{}x\opRightPren{}} tests 
if \smath{x} is infinite,
where \smath{x} is a member of the ordered
completion of a domain.
\seeType{OrderedCompletion}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{infinity}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->OnePointCompletion(Integer)}{Infinity}
{\smath{\mbox{\bf infinity}\opLeftPren{}\opRightPren{}} returns 
\smath{infinity}
denoting \smath{+\infty} as a one point completion of the integers.
\seeType{OnePointCompletion}
See also \spadfun{minusInfinity} and \spadfun{plusInfinitity}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{infix}}\opLeftPren{}{\it outputForm}, 
\allowbreak{}{\it  outputForms}\allowbreak $\,[$ , 
\allowbreak{}{\it  OutputForm}$]$\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf infix}\opLeftPren{}o, \allowbreak{} lo\opRightPren{}},
where \smath{o} is an object of type \spadtype{OutputForm} (normally unexposed)
and \smath{lo} is a list of objects of type \spadtype{OutputForm},
creates a form depicting the \smath{n}ary application
of infix operation \smath{o} to a tuple of arguments \smath{lo}.
\newitem
\smath{\mbox{\bf infix}\opLeftPren{}o, \allowbreak{} a, 
\allowbreak{} b\opRightPren{}},
where \smath{o}, \smath{a}, and \smath{b} are objects of type 
\spadtype{OutputForm} (normally unexposed),
creates an output form which displays as: \smath{a\ {\rm op}\ b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{initial}}\opLeftPren{}
{\it differentialPolynomial}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf initial}\opLeftPren{}p\opRightPren{}} returns the 
leading coefficient of
differential polynomial \smath{p} expressed as
a univariate polynomial in its leader.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{initializeGroupForWordProblem}}\opLeftPren{}
{\it group\opt{, integer, integer}}\opRightPren{}%
}%
}%
{1}{(\$)->Void}{PermutationGroup}
{\smath{\mbox{\bf initializeGroupForWordProblem}
\opLeftPren{}gp \optinner{, n, m}\opRightPren{}}
initializes the group {\it gp} for the word problem.
\seeDetails{PermutationGroup}
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{input}}\opLeftPren{}
{\it operator\opt{, function}}\opRightPren{}%
}%
}%
{1}{(\$)->Union((List(InputForm))->InputForm, "failed")}{BasicOperator}
{\smath{\mbox{\bf input}\opLeftPren{}op\opRightPren{}} returns the 
\mbox{\tt "\%input"} property of \smath{op}
if it has one attached, and \mbox{\tt "failed"} otherwise.
\newitem
\smath{\mbox{\bf input}\opLeftPren{}op, \allowbreak{} f\opRightPren{}} 
attaches \smath{f} as the \mbox{\tt "\%input"} property
of \smath{op}.
If \smath{op} has a \mbox{\tt "\%input"} property \smath{f}, then 
\smath{op(a1, \ldots, an)} is
converted to InputForm using \smath{f(a1, \ldots, an)}.
Argument f must be a function with signature
\spadsig{List(InputForm)}{InputForm}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inRadical?}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  ideal}\opRightPren{}%
}%
}%
{2}{(DPoly, \$)->Boolean}{PolynomialIdeals}
{\smath{\mbox{\bf inRadical?}\opLeftPren{}f, \allowbreak{} I\opRightPren{}} 
tests if some power of the polynomial \smath{f} belongs to the ideal \smath{I}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{insert}}\opLeftPren{}{\it x}, \allowbreak{}
{\it  aggregate}\allowbreak $\,[$ , 
\allowbreak{}{\it  integer}$]$\opRightPren{}%
}%
}%
{3}{(S, \$, Integer)->\$}{LinearAggregate}
{\smath{\mbox{\bf insert}\opLeftPren{}x, \allowbreak{} u, 
\allowbreak{} i\opRightPren{}} returns a copy of \smath{u} having
\smath{x} as its \eth{\smath{i}} element.
\newitem\smath{\mbox{\bf insert}\opLeftPren{}v, \allowbreak{} u, 
\allowbreak{} k\opRightPren{}} returns a copy of \smath{u} having \smath{v}
inserted beginning at the \eth{\smath{i}} element.
\newitem
\smath{\mbox{\bf insert!}\opLeftPren{}x, \allowbreak{} u\opRightPren{}} 
destructively inserts item \smath{x} into
bag \smath{u}.
\newitem
\smath{\mbox{\bf insert!}\opLeftPren{}x, \allowbreak{} u\opRightPren{}} 
destructively inserts item \smath{x} as a
leaf into binary search
tree or binary tournament \spad{u}.
\newitem
\smath{\mbox{\bf insert!}\opLeftPren{}x, \allowbreak{} u, 
\allowbreak{} i\opRightPren{}} destructively inserts \smath{x} into
aggregate \smath{u} at position \smath{i}.
\newitem
\smath{\mbox{\bf insert!}\opLeftPren{}v, \allowbreak{} u, 
\allowbreak{} i\opRightPren{}} destructively inserts aggregate \smath{v}
into \smath{u} at position \smath{i}.
\newitem
\smath{\mbox{\bf insert!}\opLeftPren{}x, \allowbreak{} d, 
\allowbreak{} n\opRightPren{}} destructively inserts \smath{n} copies of
\smath{x} into dictionary \smath{d}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{insertBottom!}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  queue}\opRightPren{}%
}%
}%
{2}{(S, \$)->S}{DequeueAggregate}
{\smath{\mbox{\bf insertBottom!}\opLeftPren{}x, 
\allowbreak{} d\opRightPren{}} destructively inserts \smath{x} 
into the dequeue \smath{d} at the 
bottom (back) of the dequeue.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{insertTop!}}\opLeftPren{}{\it element}, 
\allowbreak{}{\it  dequeue}\opRightPren{}%
}%
}%
{2}{(S, \$)->S}{DequeueAggregate}
{\smath{\mbox{\bf insertTop!}\opLeftPren{}x, \allowbreak{} d\opRightPren{}} 
destructively inserts \smath{x} into the dequeue \smath{d}
at the top (front). The element previously at the top of the 
dequeue becomes the second in the dequeue, and so on.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integer}}\opLeftPren{}{\it expression}\opRightPren{}%
 \optand \mbox{\axiomFun{integer?}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{integerIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(S)->Boolean}{IntegerRetractions}
{\smath{\mbox{\bf integer}\opLeftPren{}x\opRightPren{}} returns 
\smath{x} as an integer, or calls \spadfun{error}
if this is not possible.
\newitem
\smath{\mbox{\bf integer?}\opLeftPren{}x\opRightPren{}} tests 
if expression \smath{x} is an integer.
\newitem
\smath{\mbox{\bf integerIfCan}\opLeftPren{}x\opRightPren{}} 
returns expression x as of type \spadtype{Integer}
or else \mbox{\tt "failed"} if it cannot.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integerPart}}\opLeftPren{}{\it float}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{RealNumberSystem}
{\smath{\mbox{\bf integerPart}\opLeftPren{}fl\opRightPren{}} 
returns the integer part of the
mantissa of float \smath{fl}.}




% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integral}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  symbol}\opRightPren{}%
 \opand \mbox{\axiomFun{integral}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  segmentBinding}\opRightPren{}%
}%
}%
{2}{(\$, SegmentBinding(\$))->\$}{PrimitiveFunctionCategory}
{\smath{\mbox{\bf integral}\opLeftPren{}f, 
\allowbreak{} x\opRightPren{}} returns the formal integral \smath{\int {f dx}}.
\newitem
\smath{\mbox{\bf integral}\opLeftPren{}f, 
\allowbreak{} x = a..b\opRightPren{}} returns the formal definite integral
\smath{\int\nolimits_a^b{f(x) dx}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integralBasis}}\opLeftPren{}\opRightPren{}%
 \opand \mbox{\axiomFun{integralBasisAtInfinity}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Vector(\$)}{FunctionFieldCategory}
{\opkey{Domain \smath{F} is the domain of functions on a fixed curve.
\seeType{FunctionFieldCategory}}
\newitem\smath{\mbox{\bf integralBasisAtInfinity}\opLeftPren{}
\opRightPren{}\$F} returns the local
integral basis at infinity.
\newitem\smath{\mbox{\bf integralBasis}\opLeftPren{}\opRightPren{}\$F} 
returns the integral basis for
the curve.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integralCoordinates}}\opLeftPren{}
{\it function}\opRightPren{}%
}%
}%
{1}{(\$)->Record(num:Vector(UP), den:UP)}{FunctionFieldCategory}
{\smath{\mbox{\bf integralCoordinates}\opLeftPren{}f\opRightPren{}},
where \smath{f} is a function on a curve defined by domain \smath{F},
returns the coordinates of \smath{f} with respect to the 
\smath{\mbox{\bf integralBasis}\opLeftPren{}\opRightPren{}\$F}
as polynomials \smath{A_i} together with a common denominator \smath{d}.
Specifically, the operation returns a record having selector
\smath{num} with value \smath{[A_1, \ldots, A_n]} and selector \smath{den} with
value \smath{d} such that
\smath{f = (A_1 w_1 +\ldots+ A_n w_n) / d} where 
\smath{(w_1, \ldots, w_n)} is the
integral basis.
\seeType{FunctionFieldCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integralDerivationMatrix}}\opLeftPren{}
{\it function}\opRightPren{}%
}%
}%
{1}{((UP)->UP)->Record(num:Matrix(UP), den:UP)}{FunctionFieldCategory}
{\smath{\mbox{\bf integralDerivationMatrix}\opLeftPren{}d\opRightPren{}} 
extends the derivation \smath{d} and
returns the coordinates of the derivative of \smath{f} with respect to
the \smath{\mbox{\bf integralBasis}\opLeftPren{}\opRightPren{}\$F} 
as a matrix of polynomials and a common denominator \smath{Q}.
Specifically, the operation returns a record having selector
\smath{num} with value \smath{M}
and selector \smath{den} with value \smath{Q} such that
the \eth{\smath{i}} row of \smath{M} divided by \smath{Q} form the
coordinates of \smath{f} with respect to integral basis
\smath{(w1, \ldots, wn)}.
\seeType{FunctionFieldCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integralMatrix}}\opLeftPren{}\opRightPren{}%
 \opand \mbox{\axiomFun{integralMatrixAtInfinity}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Matrix(Fraction(UP))}{FunctionFieldCategory}
{\opkey{Domain \smath{F} is a domain of functions on a fixed curve. These
operations return a matrix which transform the natural basis to an 
integral basis.
\seeType{FunctionFieldCategory}
}
\newitem
\smath{\mbox{\bf integralMatrix}\opLeftPren{}\opRightPren{}} returns 
\smath{M} such that
\smath{(w_1, \ldots, w_n) = M (1, y, \ldots, y^{n-1})},
where \smath{(w_1, \ldots, w_n)} is the integral basis returned by
\smath{\mbox{\bf integralBasis}\opLeftPren{}\opRightPren{}\$F}.
\newitem
\smath{\mbox{\bf integralMatrixAtInfinity}\opLeftPren{}\opRightPren{}\$F} 
returns matrix \smath{M}
which transforms the natural basis
such that \smath{(v_1, \ldots, v_n) = M (1, y, \ldots, y^{n-1})}
where \smath{(v_1, \ldots, v_n)} is the local integral basis at
infinity returned by \smath{\mbox{\bf integralBasisAtInfinity}
\opLeftPren{}\opRightPren{}\$F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integralRepresents}}
\opLeftPren{}{\it vector}, \allowbreak{}{\it  commonDenominator}\opRightPren{}%
}%
}%
{2}{(Vector(UP), UP)->\$}{FunctionFieldCategory}
{\smath{\mbox{\bf integralRepresents}\opLeftPren{}
[A_1, \allowbreak{} \ldots, A_n], d\opRightPren{}} is the inverse
of the operation
\spadfunFrom{integralCoordinates}{FunctionFieldCategory} defined
for domain \smath{F}, a domain of functions on a fixed curve. Given
the coordinates as polynomials \smath{[A_1, \ldots, A_n]} over
a common denominator \smath{d}, this operation returns the function
represented as\smath{(A_1 w_1+\ldots+A_n w_n)/d} where
\smath{(w_1, \ldots, w_n)} is the integral basisreturned by
\smath{\mbox{\bf integralBasis}\opLeftPren{}\opRightPren{}\$F}.
\seeType{FunctionFieldCategory}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{integrate}}\opLeftPren{}
{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{integrate}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  variable }
\allowbreak $\,[$ , \allowbreak{}
{\it  options}$]$\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf integrate}\opLeftPren{}f\opRightPren{}} 
returns the integral of a
univariate polynomial or power series \smath{f} with respect to
its distinguished variable.
\newitem\smath{\mbox{\bf integrate}\opLeftPren{}f, 
\allowbreak{} x\opRightPren{}} returns the integral of
\smath{f(x)dx}, where \smath{x} is viewed as a real variable.
\newitem\smath{\mbox{\bf integrate}\opLeftPren{}f, 
\allowbreak{} x = a..b\optinner{, "noPole"}\opRightPren{}}
returns the integral of \smath{f(x)dx} from \smath{a} to \smath{b}.
If it is not possible to check whether \smath{f} has a pole for
\smath{x} between \smath{a} and \smath{b}, then a third argument
\mbox{\tt "noPole"} will make this function assume that\smath{f}
has no such pole.This operation calls \spadfun{error} if \smath{f}
has a pole for \smath{x} between \smath{a} and \smath{b} or if
a third argument different from \mbox{\tt "noPole"} is given.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{interpret}}\opLeftPren{}{\it inputForm}\opRightPren{}%
}%
}%
{ $ -> Any}{}{}
{\smath{\mbox{\bf interpret}\opLeftPren{}f\opRightPren{}} 
passes f of type \spadtype{InputForm} to the interpreter.
\newitem
\smath{\mbox{\bf interpret}\opLeftPren{}f\opRightPren{}\$P},
where \smath{P} is the package \spadtype{InputFormFunctions1(R)} for
some type \spadtype{R},
passes \smath{f} of type \spadtype{InputForm} to the interpreter,
and transforms the result into an object of type \smath{R}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{intersect}}\opLeftPren{}
{\it elements\opt{, element}}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{SetAggregate}
{\smath{\mbox{\bf intersect}\opLeftPren{}li\opRightPren{}},
where \smath{li} is a list of ideals,
computes the intersection of the list of ideals \smath{li}.
\newitem
\smath{\mbox{\bf intersect}\opLeftPren{}u, \allowbreak{} v\opRightPren{}},
where \smath{u} and \smath{v} are sets,
returns the set \smath{w} consisting of elements common to both
sets \smath{u} and \smath{v}.
See also \axiomType{Multiset}.
\newitem
\smath{\mbox{\bf intersect}\opLeftPren{}I, \allowbreak{} J\opRightPren{}},
where \smath{I} and \smath{J} are ideals,
computes the intersection of the ideals \smath{I} and \smath{J}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inv}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{DivisionRing}
{\smath{\mbox{\bf inv}\opLeftPren{}x\opRightPren{}} 
returns the multiplicative inverse of \smath{x},
where \smath{x} is an element of a domain of category \spadtype{Group} or
\spadtype{DivisionRing}, or calls \spadfun{error} if
\smath{x} is 0.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inverse}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Union(\$, "failed")}{MatrixCategory}
{\smath{\mbox{\bf inverse}\opLeftPren{}A\opRightPren{}} 
returns the inverse of the matrix \smath{A}, or
\mbox{\tt "failed"} if the matrix is not invertible, 
or calls \spadfun{error} if
the matrix is not square.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inverseColeman}}\opLeftPren{}
{\it listOfIntegers}, \allowbreak{}
{\it  listOfIntegers}, \allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{3}{(List(Integer), List(Integer), Matrix(Integer))->
List(Integer)}{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf inverseColeman}\opLeftPren{}alpha, 
\allowbreak{} beta, \allowbreak{} C\opRightPren{}}
returns the lexicographically smallest permutation in a
double coset of the symmetric group
corresponding to a non-negative Coleman-matrix.
\seeDetails{SymmetricGroupCombinatoricFunctions}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inverseIntegralMatrix}}\opLeftPren{}
\opRightPren{}
\opand \mbox{\axiomFun{inverseIntegralMatrixAtInfinity}}
\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Matrix(Fraction(UP))}{FunctionFieldCategory}
{\opkey{Domain \smath{F} is a domain of functions on a fixed
curve.
These operations return a matrix which transform an integral basis
to a natural basis.
\seeType{FunctionFieldCategory}}
\newitem\smath{\mbox{\bf inverseIntegralMatrix}\opLeftPren{}
\opRightPren{}\$F} returns \smath{M} such
that \smath{M (w_1, \ldots, w_n) = (1, y, \ldots, y^{n-1})} where
\smath{(w_1, \ldots, w_n)} is the integral basis returned by
\smath{\mbox{\bf integralBasis}\opLeftPren{}\opRightPren{}\$F}.
See also \spadfunFrom{integralMatrix}{FunctionFieldCategory}.
\newitem \smath{\mbox{\bf inverseIntegralMatrixAtInfinity}\opLeftPren{}
\opRightPren{}} returns
\smath{M} such that \smath{M (v_1, \ldots, v_n) = (1, y, \ldots,
y^(n-1))} where \smath{(v_1, \ldots, v_n)} is the local integral
basis at infinity returned by
\smath{\mbox{\bf integralBasisAtInfinity}\opLeftPren{}\opRightPren{}\$F}.
See also
\spadfunFrom{integralMatrixAtInfinity}{FunctionFieldCategory}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{inverseLaplace}}\opLeftPren{}{\it expression}, 
\allowbreak{}{\it  symbol}, \allowbreak{}{\it  symbol}\opRightPren{}%
}%
}%
{3}{(F, Symbol, Symbol)->Union(F, "failed")}{InverseLaplaceTransform}
{\smath{\mbox{\bf inverseLaplace}\opLeftPren{}f, \allowbreak{} s, 
\allowbreak{} t\opRightPren{}} returns the Inverse Laplace
transform of \smath{f(s)} using \smath{t} as the new variable, or
\mbox{\tt "failed"} if unable to find a closed form.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{invmod}}\opLeftPren{}{\it positiveInteger}, 
\allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf invmod}\opLeftPren{}a, \allowbreak{} b\opRightPren{}}, 
for relatively prime positive integers \smath{a} and \smath{b}
such that \smath{a < b}, returns \smath{1/a \mod b}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{iomode}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->String}{FileCategory}
{\smath{\mbox{\bf iomode}\opLeftPren{}f\opRightPren{}} returns the 
status of the file \smath{f}
as one of the following strings: {\tt "input", "output"} or {\tt "closed".}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{irreducible?}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(FP)->Boolean}{DistinctDegreeFactorize}
{\smath{\mbox{\bf irreducible?}\opLeftPren{}p\opRightPren{}} 
tests whether the polynomial \smath{p} is irreducible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{irreducibleFactor}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(R, Integer)->\$}{Factored}
{\smath{\mbox{\bf irreducibleFactor}\opLeftPren{}base, \allowbreak{} 
exponent\opRightPren{}} creates a factored
object with a single factor whose \smath{base} is asserted to be
irreducible (flag = \mbox{\tt "irred"}).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{irreducibleRepresentation}}\opLeftPren{}
{\it listOfIntegers\opt{, permutations}}\opRightPren{}%
}%
}%
{2}{(List(Integer), Permutation(Integer))->Matrix(Integer)}
{irreducibleRepresentationPackage}
{\smath{\mbox{\bf irreducibleRepresentation}\opLeftPren{}lambda
\optinner{, pi}\opRightPren{}} returns
a matrix giving the irreducible representation corresponding to
partition \smath{lambda}, represented as a list of integers, in
Young's natural form of the permutation \smath{pi} in the
symmetric group whose elements permute \smath{1, 2, \ldots, n}.
If a second argument is not given, the permutation is taken to be
the following two generators of the symmetric group, namely
\smath{(1 2)} (2-cycle) and \smath{(1 2 \ldots n)}
(\smath(n)-cycle).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{is?}}\opLeftPren{}{\it expression}, \allowbreak{}
{\it  pattern}\opRightPren{}%
}%
}%
{2}{(\$, BasicOperator)->Boolean}{ExpressionSpace}
{\smath{\mbox{\bf is?}\opLeftPren{}expr, \allowbreak{} pat\opRightPren{}} 
tests if the expression \smath{expr} matches the pattern \smath{pat}.
\newitem
\smath{\mbox{\bf is?}\opLeftPren{}expression, \allowbreak{} op\opRightPren{}} 
tests if \smath{expression} is a kernel and is its operator is op.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{isAbsolutelyIrreducible?}}\opLeftPren{}
{\it listOfMatrices}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), Integer)->Boolean}{RepresentationPackage2}
{\smath{\mbox{\bf isAbsolutelyIrreducible?}\opLeftPren{}aG, \allowbreak{} 
numberOfTries\opRightPren{}} uses Norton's irreducibility
test to check for absolute irreduciblity.
\seeDetails{RepresentationPackage2}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{isExpt}}\opLeftPren{}
{\it expression\opt{, operator}}\opRightPren{}%
}%
}%
{1}{(\$)->Union(Record(var:Kernel(\$), exponent:Integer), "failed")}
{FunctionSpace}
{\smath{\mbox{\bf isExpt}\opLeftPren{}p\optinner{, op}\opRightPren{}} 
returns a record with two fields:
\smath{var} denoting a kernel \smath{x},
and \smath{exponent} denoting an integer \smath{n},
if expression \smath{p}
has the form \smath{p = x^n} and \smath{n \not= 0}.
If a second argument \smath{op} is given,
\smath{x} must have the form \smath{op(a)} for some \smath{a}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{isMult}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->Union(Record(coef:Integer, var:Kernel(\$)), "failed")}{FunctionSpace}
{\smath{\mbox{\bf isMult}\opLeftPren{}p\opRightPren{}} returns
a record with two fields:
\smath{coef} denoting an integer \smath{n},
and \smath{var} denoting a kernel \smath{x},
if \smath{p} has the form \smath{n * x} and \smath{n \not= 0},
and \mbox{\tt "failed"} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{isobaric?}}\opLeftPren{}
{\it differentialPolynomial}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf isobaric?}\opLeftPren{}p\opRightPren{}} 
tests if every differential monomial appearing in the differential polynomial 
\smath{p} has the same weight.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{isPlus}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->Union(List(\$), "failed")}{FunctionSpace}
{\smath{\mbox{\bf isPlus}\opLeftPren{}p\opRightPren{}} 
returns \smath{[m_1, \ldots, m_n]} if
\smath{p} has the form \smath{m_1 +\ldots+ m_n} for 
\smath{n > 1} and \smath{m_i \not= 0},
and \mbox{\tt "failed"} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{isTimes}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->Union(List(\$), "failed")}{FunctionSpace}
{\smath{\mbox{\bf isTimes}\opLeftPren{}p\opRightPren{}} 
returns \smath{[a_1, \ldots, a_n]} if
\smath{p} has the form
\smath{a_1*\ldots*a_n} for \smath{n > 1} and \smath{m_i \not= 1},
and \mbox{\tt "failed"} if this is not possible.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{Is}}\opLeftPren{}
{\it subject}, \allowbreak{}{\it  pattern}\opRightPren{}%
}%
}%
{2}{(List(Subject), Pat)->
PatternMatchListResult(Base, Subject, List(Subject))}{PatternMatch}
{\smath{Is(expr, pat)} matches the pattern \smath{pat} on the
expression \smath{expr} and returns a list of matches \smath{[v_1
= e_1, \ldots, v_n = e_n]} or \mbox{\tt "failed"} if matching
fails.
An empty list is returned if either \smath{expr} is exactly equal
to \smath{pat} or if \smath{pat} does not match \smath{expr}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{jacobi}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(Integer, Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf jacobi}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns the Jacobi symbol \smath{J(a/b)}.
\index{Jacobi symbol}
When \smath{b} is odd, \smath{J(a/b) = \prod\nolimits_{p \in
{\bf factors}(b)}{L(a/p)}}.
Note: by convention, 0 is returned if 
\smath{\mbox{\bf gcd}\opLeftPren{}a, b) \not= 1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{jacobiIdentity?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf jacobiIdentity?}\opLeftPren{}\opRightPren{}} 
tests if \smath{(a b) c + (b c) a + (c a) b = 0}
for all \smath{a}, \smath{b}, \smath{c} in a domain
of \spadtype{FiniteRankNonAssociativeAlgebra}. For example,
this relation holds for crossed products of three-dimensional vectors.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{janko2}}\opLeftPren{}
{\it \optinit{listOfIntegers}}\opRightPren{}%
}%
}%
{1}{(List(Integer))->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf janko2}\opLeftPren{}\opRightPren{}} constructs the janko 
group acting on the integers \smath{1, \ldots, 100}.
\newitem
\smath{\mbox{\bf janko2}\opLeftPren{}\optinner{li}\opRightPren{}} constructs 
the janko group acting on the 100 integers given in the list \smath{li}.
The default value of \smath{li} is \smath{[1, \ldots, 100]}.
This operation removes duplicates in the list and calls
\spadfun{error} if \smath{li} does not have exactly 100 distinct entries.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{jordanAdmissible?}}\opLeftPren{}\opRightPren{}%
 \opand \mbox{\axiomFun{jordanAlgebra?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf jordanAdmissible?}\opLeftPren{}\opRightPren{}\$F},
where \smath{F} is a member of
\spadtype{FiniteRankNonAssociativeAlgebra(R)} over
a commutative ring \smath{R},
tests if 2 is invertible
in \smath{R} and if the algebra defined
by \smath{\{a, b\}} defined by \smath{(1/2)(a b+b a)} is a Jordan 
algebra, that is,
satisfies the Jordan identity.
\newitem
\smath{\mbox{\bf jordanAlgebra?}\opLeftPren{}\opRightPren{}\$F} 
tests if the algebra is commutative,
that \smath{\mbox{\bf characteristic}\opLeftPren{})\$F \not= 2},
and \smath{(a b) a^2 - a (b a^2) = 0} for all \smath{a} and \smath{b}
in the algebra (Jordan identity). Example: for every associative algebra
\smath{(A, +, @)}, you can construct a Jordan algebra \smath{(A, +, *)},
where \smath{a*b := (a@b+b@a)/2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{kernel}}\opLeftPren{}{\it operator}, 
\allowbreak{}{\it  expression}\opRightPren{}%
}%
}%
{2}{(BasicOperator, \$)->\$}{ExpressionSpace}
{\smath{\mbox{\bf kernel}\opLeftPren{}op, \allowbreak{} x\opRightPren{}} 
constructs \smath{op}(\smath{x}) without evaluating it.
\newitem
\smath{\mbox{\bf kernel}\opLeftPren{}op, \allowbreak{} [f_1, 
\allowbreak{} \ldots, f_n]\opRightPren{}} constructs \smath{op(f1, \ldots, fn)}
without evaluating it.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{kernels}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->List(Kernel(\$))}{ExpressionSpace}
{\smath{\mbox{\bf kernels}\opLeftPren{}f\opRightPren{}} returns the 
list of all the top-level kernels appearing in
expression \smath{f},
but not the ones appearing in the arguments of the top-level kernels.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{key?}}\opLeftPren{}{\it key}, \allowbreak{}
{\it  dictionary}\opRightPren{}%
 \opand \mbox{\axiomFun{keys}}\opLeftPren{}{\it dictionary}\opRightPren{}%
}%
}%
{2}{(Key, \$)->Boolean}{KeyedDictionary}
{\smath{\mbox{\bf key?}\opLeftPren{}k, \allowbreak{} d\opRightPren{}} 
tests if \smath{k} is a key in dictionary \smath{d}.
Dictionary \smath{d} is an element of a domain of category
\spadtype{KeyedDictionary(K, E)}, where \smath{K}
and \smath{E} denote the domains of keys and entries.
\newitem
\smath{\mbox{\bf keys}\opLeftPren{}d\opRightPren{}} 
returns the list the keys in table \smath{d}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{kroneckerDelta}}\opLeftPren{}
{\it [integer}, \allowbreak{}{\it  integer]}\opRightPren{}%
}%
}%
{0}{()->\$}{CartesianTensor}
{\smath{\mbox{\bf kroneckerDelta}\opLeftPren{}\opRightPren{}} 
is the rank 2 tensor defined by
\smath{\mbox{\bf kroneckerDelta}\opLeftPren{}i, j) = 1} 
if \smath{i=j}, and 0 otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{label}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf label}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}}, 
where \smath{o_1} and \smath{o_2} are
objects of type \spadtype{OutputForm} (normally unexposed),
returns
an output form displaying equation \smath{o_2} with label
\smath{o_1}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{laguerreL}}\opLeftPren{}{\it nonNegativeInteger}, 
\allowbreak{}{\it  x}\opRightPren{}%
 \opand \mbox{\axiomFun{laguerreL}}\opLeftPren{}{\it nonNegativeInteger}, 
\allowbreak{}{\it  nonNegativeInteger}, \allowbreak{}{\it  x}\opRightPren{}%
}%
}%
{2}{(NonNegativeInteger, R)->R}{OrthogonalPolynomialFunctions}
{\smath{\mbox{\bf laguerreL}\opLeftPren{}n, \allowbreak{} x\opRightPren{}} 
is the \eth{\smath{n}} Laguerre
polynomial, \smath{L[n](x)}, defined by \smath{{exp({{-t
x}\over{1-t}})/(1-t)} = \sum\nolimits_{n=0}^\infty {L[n](x)
t^n/n!}}.
\newitem \smath{\mbox{\bf laguerreL}\opLeftPren{}m, 
\allowbreak{} n, \allowbreak{} x\opRightPren{}} is the associated Laguerre
polynomial, \smath{L_m[n](x)}, defined as the \eth{\smath{m}}
derivative of \smath{L[n](x)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lambda}}\opLeftPren{}{\it inputForm}, 
\allowbreak{}{\it  listOfSymbols}\opRightPren{}%
}%
}%
{ ($, List Symbol) -> $}{}{}
{\smath{\mbox{\bf lambda}\opLeftPren{}i, \allowbreak{} [x_1, 
\allowbreak{} \ldots x_n]\opRightPren{}} returns the input form
corresponding to \smath{(x_1, \ldots, x_n) \mapsto i} if \smath{n
> 1}.
See also \spadfun{compiledFunction}, \spadfun{flatten}, and \spadfun{unparse}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{laplace}}\opLeftPren{}{\it expression}, 
\allowbreak{}{\it  symbol}, \allowbreak{}{\it  symbol}\opRightPren{}%
}%
}%
{3}{(F, Symbol, Symbol)->F}{LaplaceTransform}
{\smath{\mbox{\bf laplace}\opLeftPren{}f, \allowbreak{} t, 
\allowbreak{} s\opRightPren{}} returns the Laplace transform of \smath{f(t)},
defined by \smath{\int_{t=0}^\infty{exp(-s t)f(t) {\rm dt}}}.
If the transform cannot be computed, the
formal object \smath{\mbox{\bf laplace}\opLeftPren{}f, 
\allowbreak{} t, \allowbreak{} s\opRightPren{}} is returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{last}}\opLeftPren{}{\it indexedAggregate
\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(\$)->S}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf last}\opLeftPren{}u\opRightPren{}} returns the last 
element of \smath{u}.
\newitem
\smath{\mbox{\bf last}\opLeftPren{}u, \allowbreak{} n\opRightPren{}} 
returns a copy of the last \smath{n} (\smath{n
\geq 0}) elements
of \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{laurent}}\opLeftPren{}
{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{laurentIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->ULS}{UnivariatePuiseuxSeriesConstructorCategory}
{\smath{\mbox{\bf laurent}\opLeftPren{}u\opRightPren{}} converts 
\smath{u} to a Laurent series, or
calls \spadfun{error}
if this is not possible.
\newitem
\smath{\mbox{\bf laurentIfCan}\opLeftPren{}u\opRightPren{}} converts the 
Puiseux series \smath{u}
to a Laurent series, or returns \mbox{\tt "failed"} if this is not possible.
\newitem
\smath{\mbox{\bf laurent}\opLeftPren{}f, \allowbreak{} x = a\opRightPren{}} 
expands the expression \smath{f} as a
Laurent series in powers of \smath{(x - a)}.
\newitem
\smath{\mbox{\bf laurent}\opLeftPren{}f, \allowbreak{} n\opRightPren{}} 
expands the expression \smath{f} as a Laurent series in
powers of \smath{x}; at least \smath{n} terms are computed.
\newitem
\smath{\mbox{\bf laurent}\opLeftPren{}n \mapsto a_n, x = a, 
n_0..\optinner{n_1}\opRightPren{}} returns
a Laurent series defined by
\smath{\sum\nolimits_{n = n_0}^{n_1}{a_n (x - a)^n}}, where
\smath{n_1} is \smath{\infty} by default.
\newitem
\smath{\mbox{\bf laurent}\opLeftPren{}a_n, \allowbreak{} n, 
\allowbreak{} x=a, \allowbreak{} n_0..\optinner{n_1}\opRightPren{}} returns
a Laurent series defined by
\smath{\sum\nolimits_{n=n_0}^{n_1}{a_n(x - a)^n}},
where \smath{n_1} is \smath{\infty} by default.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{laurentRep}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->ULS}{UnivariatePuiseuxSeriesConstructorCategory}
{\smath{\mbox{\bf laurentRep}\opLeftPren{}f(x)\opRightPren{}} 
returns \smath{g(x)}
where the Puiseux series \smath{f(x) = g(x^r)} is 
represented by \smath{[r, g(x)]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lazy?}}\opLeftPren{}{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{LazyStreamAggregate}
{\smath{\mbox{\bf lazy?}\opLeftPren{}s\opRightPren{}} tests
if the first node of the stream \smath{s} is a lazy 
evaluation mechanism which could produce an additional entry to \smath{s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lazyEvaluate}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LazyStreamAggregate}
{\smath{\mbox{\bf lazyEvaluate}\opLeftPren{}s\opRightPren{}} 
causes one lazy evaluation of stream
\smath{s}.
Caution: \smath{s} must be a ``lazy node'' satisfying
\smath{\mbox{\bf lazy?}\opLeftPren{}s) = true}, as there is no error check.
A call to this function may or may not produce an explicit first
entry.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lcm}}\opLeftPren{}
{\it elements\opt{, element}}\opRightPren{}%
}%
}%
{1}{(List(\$))->\$}{GcdDomain}
{\smath{\mbox{\bf lcm}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
returns the least common multiple of \smath{x} and \smath{y}.
\newitem
\smath{\mbox{\bf lcm}\opLeftPren{}lx\opRightPren{}} returns the 
least common multiple of the elements of
the list \smath{lx}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ldexquo}}\opLeftPren{}{\it lodOperator}, 
\allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Union(\$, "failed")}{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf ldexquo}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
returns
\smath{q} such that \smath{a = b*q}, or \mbox{\tt "failed"} 
if no such \smath{q} exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftDivide}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
\optand \mbox{\axiomFun{leftQuotient}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
\opand \mbox{\axiomFun{leftRemainder}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(quotient:\$, remainder:\$)}
{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf leftDivide}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns
a record with two fields: ``quotient'' \smath{q}
and ``remainder'' \smath{r}
such that \smath{a = b q + r} and the degree of \smath{r} is less
than the degree of \smath{b}.
This operation is called ``left division.''
Operation \smath{\mbox{\bf leftQuotient}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns \smath{q}, and
\smath{\mbox{\bf leftRemainder}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns \smath{r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leader}}\opLeftPren{}
{\it differentialPolynomial}\opRightPren{}%
}%
}%
{1}{(\$)->V}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf leader}\opLeftPren{}p\opRightPren{}} 
returns the derivative of the highest rank
appearing in the differential polynomial \smath{p}, or
calls \spadfun{error} if \smath{p} is in the ground ring.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leadingCoefficient}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->R}{AbelianMonoidRing}
{\smath{\mbox{\bf leadingCoefficient}\opLeftPren{}p\opRightPren{}} 
returns the coefficient of the highest degree
term of polynomial \smath{p}.
See also \spadtype{IndexedDirectProductCategory} and
\spadtype{MonogenicLinearOperator}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leadingIdeal}}\opLeftPren{}{\it ideal}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{PolynomialIdeals}
{\smath{\mbox{\bf leadingIdeal}\opLeftPren{}I\opRightPren{}} is the 
ideal generated by the leading terms of the elements of the ideal \smath{I}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leadingMonomial}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{AbelianMonoidRing}
{\smath{\mbox{\bf leadingMonomial}\opLeftPren{}p\opRightPren{}} 
returns the monomial of polynomial \smath{p} with the highest degree.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leaf?}}\opLeftPren{}{\it aggregate}\opRightPren{}%
\optand \mbox{\axiomFun{leafValues}}\opLeftPren{}{\it aggregate}\opRightPren{}%
\opand \mbox{\axiomFun{leaves}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{RecursiveAggregate}
{\opkey{These operations apply to a recursive aggregate \smath{a}.
See, for example,
\spadtype{BinaryTree}.}
\newitem\smath{\mbox{\bf leaf?}\opLeftPren{}a\opRightPren{}} 
tests if \smath{a} is a terminal node.
\newitem\smath{\mbox{\bf leaves}\opLeftPren{}a\opRightPren{}} 
returns the list of values at the leaf nodes
in left-to-right order.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{left}}\opLeftPren{}
{\it binaryRecursiveAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{BinaryRecursiveAggregate}
{\smath{\mbox{\bf left}\opLeftPren{}a\opRightPren{}} 
returns the left child of binary aggregate \smath{a}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftAlternative?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftAlternative?}\opLeftPren{}\opRightPren{}\$F},
where \smath{F} is a domain of \spadtype{FiniteRankNonAssociativeAlgebra},
tests if \smath{2*\mbox{\tt associator}(a, a, b) = 0}
for all \smath{a}, \smath{b} in \smath{F}.
Note: in general, you do not know whether \smath{2*a=0} implies \smath{a=0}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftCharacteristicPolynomial}}
\opLeftPren{}{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->SparseUnivariatePolynomial(R)}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftCharacteristicPolynomial}
\opLeftPren{}p\opRightPren{}\$F} returns the
characteristic polynomial of the left regular representation of
\smath{p} of domain \smath{F} with respect to any basis.
Argument \smath{p} is a member of a domain of category
\spadtype{FiniteRankNonAssociativeAlgebra(R)} where \smath{R} is
a commutative ring.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftDiscriminant}}\opLeftPren{}
{\it \optinit{listOfVectors}}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->R}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftDiscriminant}\opLeftPren{}[v_1, 
\allowbreak{} \ldots, v_n]\opRightPren{}\$F}
where \smath{F} is a domain
of category \spadtype{FramedNonAssociativeAlgebra} over a
commutative ring \smath{R},
returns the determinant
of the \smath{n}-by-\smath{n} matrix whose element at the
\eth{\smath{i}} row and \eth{\smath{j}} column is given by the
left trace of the product
\smath{v_i*v_j}.
Same as \spadfun{determinant}(\smath{\mbox{\bf leftTraceMatrix}
\opLeftPren{}[v_1, \allowbreak{} \ldots, v_n]\opRightPren{}}).
If no argument is given, \smath{v_1, \ldots, v_n} are taken to
elements of the fixed \smath{R}-basis.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftGcd}}\opLeftPren{}{\it lodOperator}, 
\allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf leftGcd}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
computes the value \smath{g} of highest degree such that
\smath{a = aa*g} and \smath{b = bb*g} for some values \smath{aa} and 
\smath{bb}.
The value \smath{g} is computed using left-division.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftLcm}}\opLeftPren{}{\it lodOperator}, 
\allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf leftLcm}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
computes the value \smath{m} of lowest
degree such that \smath{m = a*aa = b*bb} for some values
\smath{aa} and \smath{bb}.
The value \smath{m} is computed using left-division.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftMinimalPolynomial}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->SparseUnivariatePolynomial(R)}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftMinimalPolynomial}\opLeftPren{}a\opRightPren{}} 
returns the polynomial
determined by the smallest non-trivial linear combination of left
powers of \smath{a}, an element of a domain of category
\spadtype{FiniteRankNonAssociativeAlgebra}.
Note: the polynomial has no a constant term because, in general, the
algebra has no unit.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftNorm}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->R}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftNorm}\opLeftPren{}a\opRightPren{}} 
returns the determinant of the left regular representation of \smath{a},
an element of a domain of category \spadtype{FiniteRankNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftPower}}\opLeftPren{}
{\it monad}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->\$}{MonadWithUnit}
{\smath{\mbox{\bf leftPower}\opLeftPren{}a, \allowbreak{} n
\opRightPren{}} returns the \eth{\smath{n}} left power of monad \smath{a},
that is, \smath{\mbox{\bf leftPower}\opLeftPren{}a, n) := 
a {\mbox{\bf leftPower}}(a, n-1)}.
If the monad has a unit then \smath{\mbox{\bf leftPower}
\opLeftPren{}a, 0) := 1}.
Otherwise, define \smath{\mbox{\bf leftPower}\opLeftPren{}a, 1) = a}
See \spadtype{Monad} and \spadtype{MonadWithUnit} for details.
See also \spadfun{leftRecip}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftRankPolynomial}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->SparseUnivariatePolynomial(Polynomial(R))}{FramedNonAssociativeAlgebra}
{\smath{\mbox{\bf leftRankPolynomial}\opLeftPren{}\opRightPren{}\$F} 
calculates the left minimal
polynomial of a generic element of an algebra of domain \smath{F},
a domain of category \spadtype{FramedNonAssociativeAlgebra} over a
commutative ring \smath{R}.
This generic element is an element of the algebra defined by the
same structural constants over the polynomial ring in symbolic
coefficients with respect to the fixed basis.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftRank}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(A)->NonNegativeInteger}{AlgebraPackage}
{\smath{\mbox{\bf leftRank}\opLeftPren{}x\opRightPren{}} 
returns the number of linearly independent
elements in \smath{x b_1}, \ldots, \smath{x b_n}, where
\smath{b=[b_1, \ldots, b_n]} is a basis.
Argument \smath{x} is an element of a domain of category
\spadtype{FramedNonAssociativeAlgebra} over a commutative ring
\smath{R}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftRecip}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Union(\$, "failed")}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftRecip}\opLeftPren{}a\opRightPren{}} 
returns an element that is a left inverse
of \smath{a}, or \mbox{\tt "failed"}, if there is no unit element,
such an element does not exist, or the left reciprocal cannot be
determined (see {\tt unitsKnown}).}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftRecip}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Union(\$, "failed")}{MonadWithUnit}
{\smath{\mbox{\bf leftRecip}\opLeftPren{}a\opRightPren{}} 
returns an element, which is a left inverse
of \smath{a}, or \mbox{\tt "failed"} if such an element doesn't
exist or cannot be determined (see
{\tt unitsKnown}).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftRegularRepresentation}}\opLeftPren{}
{\it element\opt{, vectorOfElements}}\opRightPren{}%
}%
}%
{2}{(\$, Vector(\$))->Matrix(R)}{FiniteRankNonAssociativeAlgebra}
{\opkey{This operation is defined on a domain \smath{F} of
category \spadtype{NonAssociativeAlgebra}.}
\newline\smath{leftRegularRepresentation(a\optinner{, [v_1,
\ldots, v_n]})} returns the matrix of the linear map defined by
left multiplication by \smath{a} with respect to the basis
\smath{[v_1, \ldots, v_n]}.
If a second argument is missing, the basis is taken to be the
fixed basis for \smath{F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftTraceMatrix}}\opLeftPren{}
{\it \opt{vectorOfElements}}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->Matrix(R)}{FiniteRankNonAssociativeAlgebra}
{\opkey{This operation is defined on a domain \smath{F} 
of category \spadtype{NonAssociativeAlgebra}.}
\newline\smath{\mbox{\bf leftTraceMatrix}\opLeftPren{}
\optinner{v}\opRightPren{}}, where \smath{v}
is an optional vector \smath{[v_1, \ldots, v_n]}, returns
the \smath{n}-by-\smath{n} matrix \smath{M} such that
\smath{M_{i, j}} is the left
trace of the product \smath{v_i*v_j} of elements from the
basis \smath{[v_1, \ldots, v_n]}.
If the argument is missing, the basis is taken to be the 
fixed basis for \smath{F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftTrace}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->R}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf leftTrace}\opLeftPren{}a\opRightPren{}} returns 
the trace of the left regular representation of \smath{a},
an element of a domain of category \spadtype{FiniteRankNonAssociativeAlgebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftTrim}}\opLeftPren{}{\it string}, 
\allowbreak{}{\it  various}\opRightPren{}%
}%
}%
{2}{(\$, Character)->\$}{StringAggregate}
{\smath{\mbox{\bf leftTrim}\opLeftPren{}s, \allowbreak{} c\opRightPren{}} 
returns string \smath{s} with all leading characters
\smath{c} deleted. For example,
\spadfun{leftTrim}{\tt (" abc ", " ")} returns {\tt "abc "}.
\newitem
\smath{\mbox{\bf leftTrim}\opLeftPren{}s, \allowbreak{} cc\opRightPren{}} 
returns \smath{s} with all leading characters in
\smath{cc} deleted. For example, \code{leftTrim("(abc)", charClass "()")}
returns \code{"abc"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leftUnit}}\opLeftPren{}\opRightPren{}%
 \opand \mbox{\axiomFun{leftUnits}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Union(Record(particular:\$, basis:List(\$)), "failed")}
{FiniteRankNonAssociativeAlgebra}
{\opkey{These operations are defined on a domain \smath{F} of
category \spadtype{NonAssociativeAlgebra}.}
\newitem\smath{\mbox{\bf leftUnit}\opLeftPren{}\opRightPren{}\$F} 
returns a left unit of the algebra (not
necessarily unique), or \mbox{\tt "failed"} if there is none.
\newitem\smath{\mbox{\bf leftUnits}\opLeftPren{}\opRightPren{}\$F} 
returns the affine space of all
left units of an algebra \smath{F}, or \mbox{\tt "failed"} if
there is none, where \smath{F} is a domain of category
\spadtype{FiniteRankNonAssociativeAlgebra}.
The normal result is returned as a record with selector
\smath{particular} for an element of \smath{F}, and \smath{basis}
for a list of elements of \smath{F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{legendreSymbol}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(Integer, Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf legendreSymbol}\opLeftPren{}a, 
\allowbreak{} p\opRightPren{}} returns the Legendre symbol
\smath{L(a/p)}, \smath{L(a/p) = (-1)^{(p-1)/2} \mod p} for prime
\smath{p}.
This is 0 if \smath{a = 0}, 1 if \smath{a} is a quadratic residue
\smath{\mod p}, and \smath{-1} otherwise.
Note: because the primality test is expensive, use
\smath{\mbox{\bf jacobi}\opLeftPren{}a, \allowbreak{} p\opRightPren{}} 
if you know that \smath{p} is prime.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{LegendreP}}\opLeftPren{}{\it nonNegativeInteger}, 
\allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(NonNegativeInteger, R)->R}{OrthogonalPolynomialFunctions}
{\smath{\mbox{\bf LegendreP}\opLeftPren{}n, \allowbreak{} x\opRightPren{}} 
is the \eth{\smath{n}} Legendre
polynomial, \smath{P[n](x)}, defined by \smath{{1\over
\sqrt(1-2xt+t^2)} ={ \sum\nolimits_{n=0}^\infty {P[n](x) t^n}}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{length}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf length}\opLeftPren{}a\opRightPren{}} 
returns the length of integer \smath{a} in digits.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{less?}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->Boolean}{Aggregate}
{\smath{\mbox{\bf less?}\opLeftPren{}u, \allowbreak{} n\opRightPren{}} 
tests if \smath{u} has less than \smath{n} elements.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{leviCivitaSymbol}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{CartesianTensor}
{\smath{\mbox{\bf leviCivitaSymbol}\opLeftPren{}\opRightPren{}} 
is the rank \smath{dim} tensor defined
by \smath{\mbox{\bf leviCivitaSymbol}\opLeftPren{})
(i_1, \ldots i_{\rm dim})}, which is
\smath{+1}, \smath{-1} or \smath{0} according to whether the
permutation \smath{i_1, \ldots, i_{\rm dim}} is an even
permutation, an odd permutation, or not a permutation of
\smath{i_0, \ldots, i_0+{\rm dim}-1}, respectively, where
\smath{i_0} is the minimum index.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lexGroebner}}\opLeftPren{}
{\it listOfPolynomials}, \allowbreak{}{\it  listOfSymbols}\opRightPren{}%
}%
}%
{2}{(List(Polynomial(F)), List(Symbol))->List(Polynomial(F))}{PolyGroebner}
{\smath{\mbox{\bf lexGroebner}\opLeftPren{}lp, 
\allowbreak{} lv\opRightPren{}} computes a Gr\"obner basis for the
list of polynomials \smath{lp} in lexicographic order.
The variables \smath{lv} are ordered by their position in the list
\smath{lp}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lhs}}\opLeftPren{}
{\it equationOrRewriteRule}\opRightPren{}%
}%
}%
{1}{(\$)->F}{RewriteRule}
{\smath{\mbox{\bf lhs}\opLeftPren{}x\opRightPren{}} 
returns the left hand side of an equation or rewrite-rule.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{library}}\opLeftPren{}{\it filename}\opRightPren{}%
}%
}%
{1}{(FileName)->\$}{Library}
{\smath{\mbox{\bf library}\opLeftPren{}name\opRightPren{}} 
creates a new library file with filename
\smath{name}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lieAdmissible?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf lieAdmissible?}\opLeftPren{}\opRightPren{}\$F} 
tests if the algebra defined by the commutators
is a Lie algebra.
The domain \smath{F} is a member of the category
\spadtype{FiniteRankNonAssociativeAlgebra(R)}.
The property of anticommutativity follows from the definition.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lieAlgebra?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf lieAlgebra?}\opLeftPren{}\opRightPren{}\$F} 
tests if the algebra of
\smath{F}
is anticommutative and
that the Jacobi identity \smath{(a*b)*c + (b*c)*a + (c*a)*b = 0}
is satisfied for all \smath{a}, \smath{b}, \smath{c} in \smath{F}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{light}}\opLeftPren{}{\it color}\opRightPren{}%
}%
}%
{1}{(Color)->\$}{Palette}
{\smath{\mbox{\bf light}\opLeftPren{}c\opRightPren{}} 
sets the shade of a hue \smath{c} to its highest value.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{limit}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  equation}\allowbreak $\,[$ , \allowbreak{}
{\it  direction}$]$\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(R)), Equation(Fraction(Polynomial(R))))->
Union(OrderedCompletion(Fraction(Polynomial(R))), 
Record(leftHandLimit:Union(OrderedCompletion(Fraction(Polynomial(R))), 
"failed"), 
rightHandLimit:Union(OrderedCompletion(Fraction(Polynomial(R))), "failed")), 
"failed")}
{RationalFunctionLimitPackage}
{\smath{\mbox{\bf limit}\opLeftPren{}f(x), 
\allowbreak{} x = a\opRightPren{}} computes 
the real two-sided limit of \smath{f} as its argument 
\smath{x} approaches \smath{a}.
\newitem
\smath{\mbox{\bf limit}\opLeftPren{}f(x), \allowbreak{} x=a, 
\allowbreak{} "left"\opRightPren{}} computes the real limit 
of \smath{f} as its 
argument \smath{x} approaches \smath{a} from the left.
\newitem
\smath{\mbox{\bf limit}\opLeftPren{}f(x), \allowbreak{} x=a, 
\allowbreak{} "right"\opRightPren{}} computes the corresponding limit as 
\smath{x} approaches \smath{a} from the right.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{limitedIntegrate}}\opLeftPren{}
{\it rationalFunction}, \allowbreak{}{\it  symbol}, \allowbreak{}
{\it  listOfRationalFunctions}\opRightPren{}%
}%
}%
{3}{(Fraction(Polynomial(F)), Symbol, 
List(Fraction(Polynomial(F))))->Union(Record(mainpart:Fraction(Polynomial(F)), 
limitedlogs:List(Record(coeff:Fraction(Polynomial(F)), 
logand:Fraction(Polynomial(F))))), "failed")}
{RationalFunctionIntegration}
{\smath{\mbox{\bf limitedIntegrate}\opLeftPren{}f, \allowbreak{} x, 
\allowbreak{} [g_1, \allowbreak{} \ldots, g_n]\opRightPren{}} returns
fractions \smath{[h, [c_i, g_i]]} such
that the \smath{g_i}'s are
among \smath{[g_1, \ldots, g_n]}, \smath{dc_i/dx = 0},
and \smath{d(h + \sum\nolimits_i {c_i {\tt log} g_i})/dx = f} if
possible, \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{linearDependenceOverZ}}\opLeftPren{}
{\it vector}\opRightPren{}%
 \opand \mbox{\axiomFun{linearlyDependentOverZ?}}\opLeftPren{}
{\it vector}\opRightPren{}%
}%
}%
{1}{(Vector(R))->Union(Vector(Integer), "failed")}{IntegerLinearDependence}
{\smath{\mbox{\bf linearlyDependenceOverZ}\opLeftPren{}
[v_1, \allowbreak{} \ldots, v_n]\opRightPren{}} tests
if the elements \smath{v_i} of a ring (typically algebraic numbers or
\spadtype{Expression}s) are linearly dependent over the integers.
If so, the operation returns
\smath{[c_1, \ldots, c_n]} such that
\smath{c_1 v_1 + \cdots + c_n v_n = 0} (for which not all the
\smath{c_i}'s are 0).
If linearly independent over the integers,
\mbox{\tt "failed"} is returned.
\newline
\smath{\mbox{\bf linearlyDependentOverZ?}\opLeftPren{}[v1, 
\allowbreak{} \ldots, vn]\opRightPren{}} returns \smath{true}
if the \smath{vi}'s are linearly dependent over the integers, 
and \smath{false} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lineColorDefault}}\opLeftPren{}
{\it \opt{palette}}\opRightPren{}%
}%
}%
{0}{()->Palette}{ViewDefaultsPackage}
{\smath{\mbox{\bf lineColorDefault}\opLeftPren{}\opRightPren{}} 
returns the default color of lines
connecting points in a \twodim{} viewport.
\newline
\smath{\mbox{\bf lineColorDefault}\opLeftPren{}p\opRightPren{}} 
sets the default color of lines
connecting points in a \twodim{} viewport to the palette
\smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{linSolve}}\opLeftPren{}
{\it listOfPolynomials}, \allowbreak{}{\it  listOfVariables}\opRightPren{}%
}%
}%
{2}{(List(P), List(OV))->Record(particular:Union(Vector(F), "failed"), 
basis:List(Vector(F)))}{LinearSystemPolynomialPackage}
{\smath{\mbox{\bf linSolve}\opLeftPren{}lp, \allowbreak{} 
lvar\opRightPren{}} finds the solutions of the linear system of polynomials 
\smath{lp} = 0 with respect to the list of symbols \smath{lvar}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{li}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LiouvillianFunctionCategory}
{\smath{li(x)} returns the logarithmic integral of \smath{x}
defined by, \smath{\int {dx\over log(x)}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{list}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(S)->\$}{ListAggregate}
{\smath{\mbox{\bf list}\opLeftPren{}x\opRightPren{}} 
creates a list consisting of the one element \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{list?}}\opLeftPren{}
{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}
{\smath{\mbox{\bf list?}\opLeftPren{}s\opRightPren{}} 
tests if \spadtype{SExpression} value \smath{s}
is a Lisp list, possibly the null list.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{listBranches}}\opLeftPren{}
{\it listOfListsOfPoints}\opRightPren{}%
}%
}%
{1}{(\$)->List(List(Point(DoubleFloat)))}{PlottablePlaneCurveCategory}
{\smath{\mbox{\bf listBranches}\opLeftPren{}c\opRightPren{}} 
returns a list of lists of points
representing the branches of the curve \smath{c}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{listRepresentation}}\opLeftPren{}
{\it permutation}\opRightPren{}%
}%
}%
{1}{(\$)->Record(preimage:List(S), image:List(S))}{Permutation}
{\smath{\mbox{\bf listRepresentation}\opLeftPren{}p\opRightPren{}} 
produces a representation {\it rep}
of the permutation \smath{p} as a list of preimages and images
\smath{i}, that is, permutation \smath{p} maps \smath{(rep.{\tt
preimage}).k} to \smath{(rep.{\tt image}).k} for all indices
\smath{k}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{listYoungTableaus}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(List(Integer))->List(Matrix(Integer))}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf listYoungTableaus}\opLeftPren{}lambda\opRightPren{}}, 
where {\it lambda} is a proper
partition, generates the list of all standard tableaus of shape
{\it lambda} by means of lattice permutations.
The numbers of the lattice permutation are interpreted as column
labels.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{listOfComponents}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->List(List(List(Point(R))))}{ThreeSpace}
{\smath{\mbox{\bf listOfComponents}\opLeftPren{}sp\opRightPren{}} 
returns a list of list of list of points for threeSpace
object \smath{sp} assumed to be composed of a list of components, 
each a list of
curves, which in turn is each a list of points,
or calls \spadfun{error} if this is not possible.
}

{\smath{\mbox{\bf listOfCurves}\opLeftPren{}sp\opRightPren{}} 
returns a list of list of subspace component properties
for threeSpace object \smath{sp} assumed to be a list of 
curves, each of which is
a list of subspace components, or calls \spadfun{error} 
if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lo}}\opLeftPren{}{\it segment}\opRightPren{}%
}%
}%
{1}{(\$)->S}{SegmentCategory}
{\smath{\mbox{\bf lo}\opLeftPren{}s\opRightPren{}} 
returns the first endpoint of \smath{s}.
For example, \code{lo(l..h) = l}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{log}}\opLeftPren{}
{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{logIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\smath{\mbox{\bf log}\opLeftPren{}x\opRightPren{}} 
returns the natural logarithm of \smath{x}.
\newitem
\smath{\mbox{\bf logIfCan}\opLeftPren{}z\opRightPren{}} 
returns \smath{\mbox{\bf log}\opLeftPren{}z\opRightPren{}} if possible, and
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{log2}}\opLeftPren{}{\it \opt{float}}\opRightPren{}%
}%
}%
{0}{()->\$}{Float}
{\smath{\mbox{\bf log2}\opLeftPren{}\opRightPren{}} 
returns \smath{ln(2) = 0.6931471805\ldots}.
\newitem
\smath{\mbox{\bf log2}\opLeftPren{}x\opRightPren{}} 
computes the base 2 logarithm for \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{log10}}\opLeftPren{}{\it \opt{float}}\opRightPren{}%
}%
}%
{0}{()->\$}{Float}
{\smath{\mbox{\bf log10}\opLeftPren{}\opRightPren{}} 
returns \smath{ln(10) = 2.3025809299\ldots}.
\newitem
\smath{\mbox{\bf log10}\opLeftPren{}x\opRightPren{}} 
computes the base 10 logarithm for \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{logGamma}}\opLeftPren{}{\it float}\opRightPren{}%
}%
}%
{1}{(Complex(DoubleFloat))->Complex(DoubleFloat)}{DoubleFloatSpecialFunctions}
{\smath{\mbox{\bf logGamma}\opLeftPren{}x\opRightPren{}} 
is the natural log of $\Gamma(x).$
Note: this can often be computed even if $\Gamma(x)$ cannot.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{lowerCase}}\opLeftPren{}
{\it \opt{string}}\opRightPren{}%
 \opand \mbox{\axiomFun{lowerCase?}}\opLeftPren{}
{\it character}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Character}
{\smath{\mbox{\bf lowerCase}\opLeftPren{}\opRightPren{}} 
returns the class of all characters for which 
\spadfunFrom{lowerCase?}{Character} is \smath{true}.
\newitem
\smath{\mbox{\bf lowerCase}\opLeftPren{}c\opRightPren{}}
returns a corresponding lower case alphabetic character \smath{c} if
\smath{c} is an upper case alphabetic character,
and \smath{c} otherwise.
\newitem
\smath{\mbox{\bf lowerCase}\opLeftPren{}s\opRightPren{}} 
returns the string with all characters in lower case.
\newitem
\smath{\mbox{\bf lowerCase?}\opLeftPren{}c\opRightPren{}} 
tests if character \smath{c} is an lower case letter, that is,
one of \smath{a}\ldots\smath{z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{listOfProperties}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->List(SubSpaceComponentProperty)}{ThreeSpace}
{\smath{\mbox{\bf listOfProperties}\opLeftPren{}sp\opRightPren{}} 
returns a list of subspace
component properties for \smath{sp} of type \spadtype{ThreeSpace},
or calls \spadfun{error} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{listOfPoints}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->List(Point(R))}{ThreeSpace}
{\smath{\mbox{\bf listOfPoints}\opLeftPren{}sp\opRightPren{}},
where \smath{sp} is a \spadtype{ThreeSpace} object,
returns the list of points component contained in \smath{sp}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mainKernel}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->Union(Kernel(\$), "failed")}{ExpressionSpace}
{\smath{\mbox{\bf mainKernel}\opLeftPren{}f\opRightPren{}} 
returns a kernel of \smath{f} with maximum
nesting level, or \mbox{\tt "failed"} if \smath{f} has no kernels
(that is, \smath{f} is a constant).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mainVariable}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->Union(VarSet, "failed")}{PolynomialCategory}
{\smath{\mbox{\bf mainVariable}\opLeftPren{}u\opRightPren{}} 
returns the variable of highest ordering
that actually occurs in the polynomial \smath{p}, or \mbox{\tt
"failed"} if no variables are present.
Argument u can be either a polynomial or a rational function.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{makeFloatFunction}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  symbol}\allowbreak $\,[$ , \allowbreak{}
{\it  symbol}$]$\opRightPren{}%
}%
}%
{2}{(S, Symbol)->(DoubleFloat)->DoubleFloat}{MakeFloatCompiledFunction}
{\opkey{Argument \smath{expr} may be of any type that is coercible to
type \spadtype{InputForm} (objects of the most common types can
be so coerced).}
\newitem
\smath{\mbox{\bf makeFloatFunction}\opLeftPren{}expr, 
\allowbreak{} x\opRightPren{}} returns an anonymous function
of type \spadsig{Float}{Float} defined by
\smath{x \mapsto {\rm expr}}.
\newitem
\smath{\mbox{\bf makeFloatFunction}\opLeftPren{}expr, 
\allowbreak{} x, \allowbreak{} y\opRightPren{}} returns an anonymous function
of type \spadsig{(Float, Float)}{Float} defined by
\smath{(x, y) \mapsto {\rm expr}}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{makeVariable}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(S)->(NonNegativeInteger)->\$}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf makeVariable}\opLeftPren{}s\opRightPren{}}, 
where \smath{s} is a symbol,
differential indeterminate, or a differential polynomial,
returns a function \smath{f} defined on the non-negative integers
such that \smath{f(n)}
returns the \eth{\smath{n}} derivative of \smath{s}.
\newitem
\smath{\mbox{\bf makeVariable}\opLeftPren{}s, 
\allowbreak{} n\opRightPren{}} returns the \eth{\smath{n}} derivative of a
differential indeterminate \smath{s} as an algebraic indeterminate.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{makeObject}}\opLeftPren{}{\it functions}, 
\allowbreak{}{\it  range}\allowbreak $\,[$ , \allowbreak{}
{\it  range}$]$\opRightPren{}%
}%
}%
{2}{(ParametricSpaceCurve((DoubleFloat)->DoubleFloat), Segment(Float))->
ThreeSpace(DoubleFloat)}{TopLevelDrawFunctionsForCompiledFunctions}
{Arguments \smath{f}, \smath{g}, and \smath{h} appearing below
with arguments (for example, \smath{f(x, y)}) denote symbolic
expressions involving those arguments.
\largerbreak Arguments \smath{f}, \smath{g}, and \smath{h}
appearing below as symbols without arguments denote user-defined
functions which map one or more \spadtype{DoubleFloat} values to
\spadtype{DoubleFloat} values.
\largerbreak Values \smath{a}, \smath{b}, \smath{c}, and \smath{d}
denote numerical values.
\bigitem\smath{\mbox{\bf makeObject}\opLeftPren{}curve(f, g, h), 
\allowbreak{} a..b\opRightPren{}} returns the space
\smath{sp} of the domain \spadtype{ThreeSpace} with the addition
of the graph of the parametric curve \smath{x = f(t)}, \smath{y =
g(t)}, \smath{z = h(t)} as \smath{t} ranges from 
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}}
to \smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf makeObject}\opLeftPren{}curve(f(t), g(t), h(t)), 
\allowbreak{} t = a..b\opRightPren{}}
returns the space \smath{sp} of the domain \spadtype{ThreeSpace}
with the addition of the graph of the parametric curve \smath{x =
f(t)}, \smath{y = g(t)}, \smath{z = h(t)} as \smath{t} ranges from
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}}.
\bigitem\smath{\mbox{\bf makeObject}\opLeftPren{}f, \allowbreak{} a..b, 
\allowbreak{} c..d\opRightPren{}} returns the space
\smath{sp} of the domain \spadtype{ThreeSpace} with the addition
of the graph of \smath{z = f(x, y)} as \smath{x} ranges from
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
and \smath{y} ranges from
\smath{\mbox{\bf min}\opLeftPren{}c, \allowbreak{} d\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}c, \allowbreak{} d\opRightPren{}}.
\bigitem\smath{\mbox{\bf makeObject}\opLeftPren{}f(x, y), 
\allowbreak{} x = a..b, \allowbreak{} y = c..d\opRightPren{}} returns
the space \smath{sp} of the domain \spadtype{ThreeSpace} with the
addition of the graph of \smath{z = f(x, y)} as \smath{x} ranges
from \smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} and 
\smath{y} ranges
from \smath{\mbox{\bf min}\opLeftPren{}c, \allowbreak{} d\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}c, \allowbreak{} d\opRightPren{}}.
\bigitem\smath{\mbox{\bf makeObject}\opLeftPren{}surface(f, g, h), 
\allowbreak{} a..b, \allowbreak{} c..d\opRightPren{}} returns
the space \smath{sp} of the domain \spadtype{ThreeSpace} with the
addition of the graph of the parametric surface \smath{x = f(u,
v)}, \smath{y = g(u, v)}, \smath{z = h(u, v)} as \smath{u} ranges
from \smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
and \smath{v} ranges
from \smath{\mbox{\bf min}\opLeftPren{}c, \allowbreak{} d\opRightPren{}} 
to \smath{\mbox{\bf max}\opLeftPren{}c, \allowbreak{} d\opRightPren{}}.
\bigitem \smath{makeObject(surface(f(u, v), g(u, v), h(u, v)), u =
a..b, v = c..d)} returns the space \smath{sp} of the domain
\spadtype{ThreeSpace} with the addition of the graph of the
parametric surface \smath{x = f(u, v)}, \smath{y = g(u, v)},
\smath{z = h(u, v)} as \smath{u} ranges from 
\smath{\mbox{\bf min}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} to
\smath{\mbox{\bf max}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
and \smath{v} ranges from \smath{\mbox{\bf min}\opLeftPren{}c, 
\allowbreak{} d\opRightPren{}} to
\smath{\mbox{\bf max}\opLeftPren{}c, \allowbreak{} d\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{makeYoungTableau}}\opLeftPren{}
{\it listOfIntegers}, \allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{2}{(List(Integer), List(Integer))->Matrix(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf makeYoungTableau}\opLeftPren{}lambda, 
\allowbreak{} gitter\opRightPren{}} computes for a given
lattice permutation {\it gitter} and for an improper partition
{\it lambda} the corresponding standard tableau of shape {\it
lambda}.
See \spadfun{listYoungTableaus}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mantissa}}\opLeftPren{}{\it float}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{FloatingPointSystem}
{\smath{\mbox{\bf mantissa}\opLeftPren{}x\opRightPren{}} 
returns the mantissa part of \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{map}}\opLeftPren{}{\it function}, \allowbreak{}
{\it  structure}\allowbreak $\,[$ , \allowbreak{}
{\it  structure}$]$\opRightPren{}%
 \opand \mbox{\axiomFun{map!}}\opLeftPren{}{\it function}, \allowbreak{}
{\it  structure}\opRightPren{}%
}%
}%
{2}{((R)->R, \$)->\$}{AbelianMonoidRing}
{\smath{\mbox{\bf map}\opLeftPren{}fn, \allowbreak{} u\opRightPren{}} 
maps the one-argument function \smath{fn} onto
the components of a structure, returning a new structure.
Most structures allow \smath{f} to have different source and
target domains.
Specifically, the function \smath{f} is mapped onto the following
components of the structure as follows.
If \smath{u} is: \begin{simpleList} \item a series: the
coefficients of the series.
\item a polynomial: the coefficients of the non-zero monomials.
\item a direct product of elements: the elements.
\item an aggregate, tuple, table, or a matrix: all its elements.
\item an operation of the form \smath{op(a_1, \ldots, a_n)}: each
\smath{a_i}, returning \smath{op(f(a_1), \ldots, f(a_n))}.
\item a fraction: the numerator and denominator.
\item complex: the real and imaginary parts.
\item a quaternion or octonion: the real and all imaginary parts.
\item a finite or infinite series or stream: all the coefficients.
\item a factored object: onto all the factors.
\item a segment \smath{a..b} or a segment binding of the form
\smath{x=a..b}: each of the elements from \smath{a} to \smath{b}.
\item an equation: both sides of the equation.
\end{simpleList} \smath{\mbox{\bf map}\opLeftPren{}fn, 
\allowbreak{} u, \allowbreak{} v\opRightPren{}} maps the two argument
function \smath{fn} onto the components of a structure, returning
a new structure.
Arguments \smath{u} and \smath{v} can be matrices, finite
aggregates such as lists, tables, and vectors, and infinite
aggregates such as streams and series.
\bigitem \smath{\mbox{\bf map!}\opLeftPren{}f, 
\allowbreak{} u\opRightPren{}}, where \smath{u} is homogeneous
aggregate, destructively replaces each element \smath{x} of
\smath{u} by \smath{f(x)}.
\bigitem \seeAlso{\spadfun{match}} }

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mapCoef}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  freeAbelianMonoid}\opRightPren{}%
 \opand \mbox{\axiomFun{mapGen}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  freeAbelianMonoid}\opRightPren{}%
}%
}%
{2}{((E)->E, \$)->\$}{FreeAbelianMonoidCategory}
{\smath{\mbox{\bf mapCoeff}\opLeftPren{}f, 
\allowbreak{} m\opRightPren{}} maps unary function \smath{f} onto the
coefficients of a free abelian monoid of the form
\smath{e_1 a_1 +\ldots+ e_n a_n} returning
\smath{f(e_1) a_1 +\ldots+ f(e_n) a_n}.
\newitem\smath{\mbox{\bf mapGen}\opLeftPren{}fn, 
\allowbreak{} m\opRightPren{}} similarly returns
\smath{e_1 f(a_1) +\ldots+ e_n f(a_n)}.
\seeType{FreeAbelianMonoidCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mapDown!}}\opLeftPren{}{\it tree}, 
\allowbreak{}{\it  value}, \allowbreak{}{\it  function}\opRightPren{}%
}%
}%
{2}{((E)->E, \$)->\$}{FreeAbelianMonoidCategory}
{\opkey{These operations make a preorder traversal (node then
left branch
then right branch) of a tree \smath{t} of type
\spadtype{BalancedBinaryTree(S)}, destructively mapping values of
type \smath{S} from the root to the leaves of the tree, then
returning the modified tree as value; \smath{p} is a value of type
\smath{S}.}
\newitem\smath{\mbox{\bf mapDown!}\opLeftPren{}t, 
\allowbreak{} p, \allowbreak{} f\opRightPren{}}, where \smath{f} is a function
of type \spadsig{(S, S)}{S}, replaces the successive interior
nodes of \smath{t} as follows.
The root value \smath{x} is replaced by \smath{q = f(x, p)}.
Then \spadfun{mapDown!} is recursively applied to \smath{(l, q,
f)} and \smath{(r, q, f)} where \smath{l} and \smath{r} are
respectively the left and right subtrees of \smath{t}.
\newitem\smath{\mbox{\bf mapDown!}\opLeftPren{}t, 
\allowbreak{} p, \allowbreak{} f\opRightPren{}}, where \smath{f} is a function
of type \spadsig{(S, S, S)}{List S}, is similar.
The root value of \smath{t} is first replaced by \smath{p}.
Then \smath{f} is applied to three values: the value at the
current, left, and right node (in that order) to produce a list of
two values \spad{l} and \spad{r}, which are then passed
recursively as the second argument of \spadfun{mapDown!} to
the left and right subtrees.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mapExponents}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{((E)->E, \$)->\$}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf mapExponents}\opLeftPren{}fn, 
\allowbreak{} u\opRightPren{}} maps function \smath{fn} onto the
exponents of the non-zero monomials of polynomial \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mapUp!}}\opLeftPren{}
{\it \optinit{tree, }tree, function}\opRightPren{}%
}%
}%
{2}{((E)->E, \$)->\$}{FreeAbelianMonoidCategory}
{\opkey{These operations make an endorder traversal (left branch then
right branch then node) of a tree \smath{t} of type
\spadtype{BalancedBinaryTree(S)}, destructively mapping values of
type \smath{S} from the leaves to the root of the tree, then
returning the modified tree as value; \smath{p} is a value of type
\smath{S}.}
\newitem\smath{\mbox{\bf mapUp!}\opLeftPren{}t, 
\allowbreak{} f\opRightPren{}}, where \smath{f} has type
\spadsig{(S, S)}{S}, replaces the value at each interior node by
\smath{f(l, r)}, where \smath{l} and \smath{r} are the values at
the immediate left and right nodes.
\newitem\smath{\mbox{\bf mapUp!}\opLeftPren{}t, 
\allowbreak{} t_1, \allowbreak{} f\opRightPren{}} 
makes an endorder traversal of
both \smath{t} and \smath{t_1} (of identical shape) in parallel.
The value at each successive interior node of \smath{t} is
replaced by \smath{f(l, r, l_1, r_1)}, where \smath{l} and
\smath{r} are the values at the immediate left and right nodes of
\smath{t}, and \smath{l_1} and \smath{r_1} are corresponding
values of \smath{t_1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mask}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf mask}\opLeftPren{}n\opRightPren{}} returns 
\smath{2^n-1} (an \smath{n}-bit mask).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{match?}}\opLeftPren{}{\it string}, \allowbreak{}
{\it  string}, \allowbreak{}{\it  character}\opRightPren{}%
}%
}%
{3}{(\$, \$, Character)->Boolean}{StringAggregate}
{\smath{\mbox{\bf match?}\opLeftPren{}s, \allowbreak{} t, 
\allowbreak{} char\opRightPren{}} tests if \smath{s} matches \smath{t} except 
perhaps for multiple and consecutive occurrences of character \smath{char}. 
Typically \smath{char} is the blank character.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{match}}\opLeftPren{}{\it list}, \allowbreak{}
{\it  list}\allowbreak $\,[$ , \allowbreak{}{\it  option}$]$\opRightPren{}%
}%
}%
{2}{(List(A), List(B))->(A)->B}{ListToMap}
{\smath{\mbox{\bf match}\opLeftPren{}la, 
\allowbreak{} lb\optinner{, u}\opRightPren{}},
where \smath{la} and \smath{lb} are lists of equal length,
creates a function that can be used by \spadfun{map}.
The target of a source value \smath{x} in \smath{la} is the
value \smath{y} with the corresponding index in \smath{lb}.
Optional argument \smath{u} defines the target for a source
value \smath{a} which is not in \smath{la}.
If \smath{u} is a value of the source domain, then \smath{a} is 
replaced by \smath{u},
which must be a member of \smath{la}.
If \smath{u} is a value of the target domain, the value returned 
by the map for
\smath{a} is \smath{u}.
If \smath{u} is a function \smath{f}, then the value returned is \smath{f(a)}.
If no third argument is given, an error occurs when such a \smath{a} is found.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mathieu11}}\opLeftPren{}
{\it \opt{listOfIntegers}}\opRightPren{}%
 \optand \mbox{\axiomFun{mathieu12}}\opLeftPren{}
{\it \opt{listOfIntegers}}\opRightPren{}%
 \optand \mbox{\axiomFun{mathieu22}}\opLeftPren{}
{\it \opt{listOfIntegers}}\opRightPren{}%
 \optand \mbox{\axiomFun{mathieu23}}\opLeftPren{}
{\it \opt{listOfIntegers}}\opRightPren{}%
 \opand \mbox{\axiomFun{mathieu24}}\opLeftPren{}
{\it \opt{listOfIntegers}}\opRightPren{}%
}%
}%
%
{0}{()->PermutationGroup(Integer)}{PermutationGroupExamples}{%
\smath{\mbox{\bf mathieu11}\opLeftPren{}\optinner{li}\opRightPren{}} 
constructs the
mathieu group acting on the eleven integers given in the list \smath{li}.
Duplicates
in the list will be removed and \spadfun{error} will be called
if \smath{li} has fewer or more than eleven different entries.
The default value of \smath{li} is \smath{[1, \ldots, 11]}.
Operations \smath{mathieu12},
\smath{mathieu22}, and \smath{mathieu23}
and \smath{mathieu24} are similar.
These operations provide examples of permutation groups in Axiom.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{matrix}}\opLeftPren{}{\it listOfLists}\opRightPren{}%
}%
}%
{1}{(List(List(R)))->\$}{RectangularMatrixCategory}
{\smath{\mbox{\bf matrix}\opLeftPren{}l\opRightPren{}} 
converts the list of lists \smath{l} to a
matrix, where the list of lists is viewed as a list of the rows of
the matrix.
\newitem\smath{\mbox{\bf matrix}\opLeftPren{}llo\opRightPren{}},
where \smath{llo} is a list of list of objects of type
\spadtype{OutputForm} (normally unexposed),
returns an output form displaying \smath{llo} as a matrix.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{max}}\opLeftPren{}{\it \opt{various}}\opRightPren{}%
}%
}%
{0}{()->\$}{SingleInteger}
{\smath{\mbox{\bf max}\opLeftPren{}\opRightPren{}} returns 
the largest small integer.
\newline\smath{\mbox{\bf max}\opLeftPren{}u\opRightPren{}} 
returns the largest element of aggregate
\smath{u}.
\newline\smath{\mbox{\bf max}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
returns the maximum of \smath{x} and
\smath{y} relative to a total ordering \axiomOp{<}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{maxColIndex}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{RectangularMatrixCategory}
{\smath{\mbox{\bf maxColIndex}\opLeftPren{}m\opRightPren{}} 
returns the index of the last column of the matrix
or two-dimensional array \smath{m}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{maxIndex}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->Index}{IndexedAggregate}
{\smath{\mbox{\bf maxIndex}\opLeftPren{}u\opRightPren{}} 
returns the maximum index \smath{i} of indexed
aggregate \smath{u}. For most indexed aggregates (vectors, strings, lists),
\smath{\mbox{\bf maxIndex}\opLeftPren{}u\opRightPren{}} is 
equivalent to \smath{\# u.}
}




% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{maxRowIndex}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{RectangularMatrixCategory}
{\smath{\mbox{\bf maxRowIndex}\opLeftPren{}m\opRightPren{}} 
returns the index of the ``last'' row of the matrix
or two-dimensional array \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{meatAxe}}\opLeftPren{}
{\it listOfListsOfMatrices \opt{, boolean, integer, integer}}\opRightPren{}%
}%
}%
{4}{(List(Matrix(R)), Boolean, Integer, Integer)->
List(List(Matrix(R)))}{RepresentationPackage2}
{\smath{\mbox{\bf meatAxe}\opLeftPren{}aG \optinner{, randomElts, 
\allowbreak numOfTries, \allowbreak maxTests}\opRightPren{}} tries to
split the representation given by \smath{aG} and returns a 2-list of
representations. All matrices of argument \smath{aG} are assumed to be 
square and of equal size.
The default values of arguments \smath{randomElts},
\smath{numOfTries} and \smath{maxTests} are \smath{false}, 25, and 7, 
respectively.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{member?}}\opLeftPren{}{\it element}, \allowbreak{}
{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(S, \$)->Boolean}{HomogeneousAggregate}
{\smath{\mbox{\bf member?}\opLeftPren{}x, \allowbreak{} u\opRightPren{}} 
tests if \smath{x} is a member of \smath{u}.
\newitem
\smath{\mbox{\bf member?}\opLeftPren{}pp, \allowbreak{} gp\opRightPren{}}, 
where \smath{pp} is a permutation and
\smath{gp} is a group, tests
whether {\it pp} is in the group {\it gp}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{merge}}\opLeftPren{}{\it various}\opRightPren{}%
 \opand \mbox{\axiomFun{merge!}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{ExtensibleLinearAggregate}
{\smath{\mbox{\bf merge}\opLeftPren{}[s1, \allowbreak{} s2, \allowbreak{} 
\ldots, sn]\opRightPren{}} will create a new
\spadtype{ThreeSpace} object that has the components of all the ones in
the list; groupings of components into composites are maintained.
\newitem
\smath{\mbox{\bf merge}\opLeftPren{}s1, \allowbreak{} s2\opRightPren{}} 
will create a new \spadtype{ThreeSpace}
object that
has the components of \smath{s1} and \smath{s2}; groupings
of components into composites are maintained.
\newitem
\smath{\mbox{\bf merge}\opLeftPren{}\optfirst{p, }a, b\opRightPren{}} 
returns an aggregate \smath{c} which
merges \smath{a} and \smath{b}.
The result is produced by examining each element \smath{x} of \smath{a}
and \smath{y} of \smath{b} successively.
If \smath{p(x, y)} is \smath{true}, then \smath{x} is inserted into  the
result.
Otherwise \smath{y} is inserted.
If \smath{x} is chosen, the next element  of \smath{a} is examined, and so on.
When all the elements of one aggregate are examined, the remaining elements 
of the other are appended. For example, \smath{\mbox{\bf merge}\opLeftPren{}<, 
\allowbreak{} [1, \allowbreak{} 3], \allowbreak{} [2, \allowbreak{} 7, 
\allowbreak{} 5]\opRightPren{}} returns \smath{[1, 2, 3, 7, 5]}.
By default, function \smath{p} is \smath{\leq}.
\newitem
\smath{\mbox{\bf merge!}\opLeftPren{}\optfirst{p}, u, v\opRightPren{}} 
destructively merges the elements \smath{u} and \smath{v} into
\smath{u} using comparison function \smath{p}.
Function \smath{p} is \smath{\leq} by default.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mesh}}\opLeftPren{}
{\it u\opt{, v, w, x}}\opRightPren{}%
}%
}%
{4}{(\$, List(List(List(R))), Boolean, Boolean)->\$}{ThreeSpace}
{\opkey{Argument \smath{sp} below is a \spadtype{ThreeSpace}
object \smath{sp}.
Argument \smath{lc} is a list of curves.
Each curve is either a list of points (objects of type
\spadtype{Point}) or else a list of lists of small floats.}
\newitem\smath{\mbox{\bf mesh}\opLeftPren{}lc\opRightPren{}} 
returns a \spadtype{ThreeSpace} object
defined by \smath{lc}.
\newitem\smath{\mbox{\bf mesh}\opLeftPren{}sp\opRightPren{}} 
returns the list of curves contained in
space \smath{sp}.
\newitem\smath{\mbox{\bf mesh}\opLeftPren{}
\optfirst{sp, }, lc, close1, close2\opRightPren{}} adds the
list of curves \smath{lc} to the \spadtype{ThreeSpace} object
\smath{sp}.
Boolean arguments \smath{close1} and \smath{close2} tell how the
curves and surface are to be closed.
If \smath{close1} is \smath{true}, each individual curve will be
closed, that is, the last point of the list will be connected to
the first point.
If \smath{close2} is \smath{true}, the first and last curves are
regarded as boundaries and are connected.
By default, the argument \smath{sp} is empty.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{midpoints}}\opLeftPren{}
{\it listOfIntervals}\opRightPren{}%
}%
}%
{1}{(List(Record(left:Fraction(Integer), right:Fraction(Integer))))->
List(Fraction(Integer))}{RealZeroPackage}
{\opkey{These operations are defined on ``intervals'' represented
by records with keys \smath{right} and \smath{left}, and rational 
number values.}
\newitem\smath{\mbox{\bf midpoints}\opLeftPren{}isolist\opRightPren{}} 
returns the list of midpoints for the list of intervals \smath{isolist}.
\newitem\smath{\mbox{\bf midpoint}\opLeftPren{}int\opRightPren{}} 
returns the midpoint of the interval \smath{int}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{min}}\opLeftPren{}{\it \opt{u, v}}\opRightPren{}%
}%
}%
{0}{()->\$}{SingleInteger}
{\smath{\mbox{\bf min}\opLeftPren{}\opRightPren{}} returns the 
element of type \spadtype{SingleInteger}.
\newitem
\smath{\mbox{\bf min}\opLeftPren{}u\opRightPren{}} returns the 
smallest element of aggregate \smath{u}.
\newitem
\smath{\mbox{\bf min}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
returns the minimum of \smath{x} and \smath{y} relative to
total ordering \smath{<}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minColIndex}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{RectangularMatrixCategory}
{\smath{\mbox{\bf minColIndex}\opLeftPren{}m\opRightPren{}} 
returns the index of the ``first'' column
of the matrix
or two-dimensional array \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minimalPolynomial}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{1}{(\$)->SparseUnivariatePolynomial(F)}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf minimalPolynomial}\opLeftPren{}x
\optinner{, n}\opRightPren{}} computes the minimal 
polynomial of \smath{x} over the 
field of extension degree \smath{n} over the ground field \smath{F}.
The default value of \smath{n} is 1.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minimalPolynomial}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->UP}{FiniteRankAlgebra}
{\smath{\mbox{\bf minimalPolynomial}\opLeftPren{}a\opRightPren{}} 
returns the minimal polynomial of element \smath{a}
of a finite rank algebra.
\seeType{FiniteRankAlgebra}
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minimumDegree}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  variable}\opRightPren{}%
}%
}%
{1}{(\$)->E}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf minimumDegree}\opLeftPren{}p, 
\allowbreak{} v\opRightPren{}} gives the minimum degree of 
polynomial \smath{p} with 
respect to \smath{v}, that is, viewed as a univariate polynomial in \smath{v}.
\newitem
\smath{\mbox{\bf minimumDegree}\opLeftPren{}p, 
\allowbreak{} lv\opRightPren{}} gives the list of 
minimum degrees of the polynomial \smath{p} 
with respect to each of the variables in the list \smath{lv}.
\newitem
\seeAlso{\spadtype{FiniteAbelianMonoidRing} and 
\spadtype{MonogenicLinearOperator}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minIndex}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->Index}{IndexedAggregate}
{\smath{\mbox{\bf minIndex}\opLeftPren{}aggregate\opRightPren{}} 
returns the minimum index \smath{i} of aggregate \smath{u}.
Note: the \axiomFun{minIndex} of most system-defined indexed aggregates is 1.
See also \spadtype{PointCategory}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minordet}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->R}{MatrixCategory}
{\smath{\mbox{\bf minordet}\opLeftPren{}m\opRightPren{}} 
computes the determinant of the matrix \smath{m} using minors,
or calls \spadfun{error} if the matrix is not square.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minPoly}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(Kernel(\$))->SparseUnivariatePolynomial(\$)}{ExpressionSpace}
{\smath{\mbox{\bf minPoly}\opLeftPren{}k\opRightPren{}} 
returns polynomial \smath{p} such that \smath{p(k) = 0}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minRowIndex}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{RectangularMatrixCategory}
{\smath{\mbox{\bf minRowIndex}\opLeftPren{}m\opRightPren{}} 
returns the index of the ``first'' row of the matrix
or two-dimensional array \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{minusInfinity}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->OrderedCompletion(Integer)}{Infinity}
{\smath{\mbox{\bf minusInfinity}\opLeftPren{}\opRightPren{}} 
returns {\tt \%minusInfinity},
the Axiom name for \smath{-\infty}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{modifyPointData}}\opLeftPren{}{\it space}, 
\allowbreak{}{\it  nonNegativeInteger}, \allowbreak{}
{\it  point}\opRightPren{}%
}%
}%
{3}{(\$, NonNegativeInteger, Point(R))->\$}{ThreeSpace}
{\smath{\mbox{\bf modifyPointData}\opLeftPren{}sp, \allowbreak{} i, 
\allowbreak{} p\opRightPren{}} changes the point at the indexed location 
\smath{i} in the \spadtype{ThreeSpace} object \smath{sp} to \smath{p}.
This operation is useful for making changes to existing data.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{moduloP}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{PAdicIntegerCategory}
{\smath{\mbox{\bf moduloP}\opLeftPren{}x\opRightPren{}}, 
such that \smath{p = \mbox{\bf modulus}()},
 returns a, where \smath{x = a + b p}
where \smath{x} is a \smath{p}-adic integer.
\seeType{PAdicIntegerCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{modulus}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Integer}{PAdicIntegerCategory}
{\smath{\mbox{\bf modulus}\opLeftPren{}\opRightPren{}\$R} 
returns the value of the modulus \smath{p}
of a p-adic integer domain \smath{R}.
\seeType{PAdicIntegerCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{moebiusMu}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf moebiusMu}\opLeftPren{}n\opRightPren{}} 
returns the Moebius function \smath{\mu(n)},
defined as \smath{-1}, \smath{0} or \smath{1} as
follows: \smath{\mu(n) = 0} if \smath{n} is divisible by a square
\smath{ > 1}, and \smath{(-1)^k} if \smath{n} is square-free and
has \smath{k} distinct prime divisors.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{monicDivide}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  polynomial}\allowbreak $\,[$ , 
\allowbreak{}{\it  variable}$]$\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(quotient:\$, remainder:\$)}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf monicDivide}\opLeftPren{}p, 
\allowbreak{} q\optinner{, v}\opRightPren{}} divides the polynomial
\smath{p} by the monic polynomial \smath{q}, returning the record
containing a \smath{quotient} and \smath{remainder}.
For multivariate polynomials, the polynomials are viewed as a
univariate polynomials in \smath{v}.
If \smath{p} and \smath{q} are univariate polynomials, then the
third argument may be omitted.
The operation calls \spadfun{error} if \smath{q} is not monic with
respect to \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{monomial}}\opLeftPren{}{\it coefficient}, 
\allowbreak{}{\it  exponent}\allowbreak $\,[$ , 
\allowbreak{}{\it  option}$]$\opRightPren{}%
}%
}%
{2}{(R, E)->\$}{AbelianMonoidRing}
{\smath{\mbox{\bf monomial}\opLeftPren{}coef, 
\allowbreak{} exp\opRightPren{}} creates a term of
a univariate polynomial or series object from a coefficient \smath{coef} and
exponent \smath{exp}. The variable name must be given by context
(as through a declaration for the result).
\newitem
\smath{\mbox{\bf monomial}\opLeftPren{}c, 
\allowbreak{} [x_1, \allowbreak{} \ldots, x_k], 
[n_1, \ldots, n_k]\opRightPren{}} creates a term
\smath{c x_1^{n_1}\ldots x_k^{n_k}}
of a multivariate power series or polynomial
from coefficient \smath{c}, variables \smath{x_j} and exponents
\smath{n_j}.
\newitem
\smath{\mbox{\bf monomial}\opLeftPren{}c, 
\allowbreak{} x, \allowbreak{} n\opRightPren{}} creates a term \smath{c x^n}
of a polynomial or series
from a coefficient \smath{c}, variable \smath{x}, and exponent \smath{n}.
\newitem
\smath{\mbox{\bf monomial}\opLeftPren{}c, 
\allowbreak{} [n_1, \allowbreak{} \ldots, n_k]\opRightPren{}}
creates a \spadtype{CliffordAlgebra} element \smath{c e(n_1), \ldots, c e(n_k)}
from a coefficient \smath{c} and basis elements \smath{c(i_j)}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{monomial?}}\opLeftPren{}
{\it polynomialOrSeries}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{AbelianMonoidRing}
{\smath{\mbox{\bf monomial?}\opLeftPren{}p\opRightPren{}} 
tests if polynomial or series \smath{p} is a
single monomial.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{monomials}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{PolynomialCategory}
{\smath{\mbox{\bf monomials}\opLeftPren{}p\opRightPren{}} 
returns the list of non-zero monomials of
polynomial \smath{p},
\smath{[a_1 X^{(1)}, \ldots, a_n X^{(n)}]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{more?}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->Boolean}{Aggregate}
{\smath{\mbox{\bf more?}\opLeftPren{}u, \allowbreak{} n\opRightPren{}}
tests if \smath{u} has greater than \smath{n} elements.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{movedPoints}}\opLeftPren{}
{\it permutation}\opRightPren{}%
}%
}%
{1}{(\$)->Set(S)}{Permutation}
{\smath{\mbox{\bf movedPoints}\opLeftPren{}p\opRightPren{}} 
returns the set of points moved by the permutation \smath{p}.
\newitem
\smath{\mbox{\bf movedPoints}\opLeftPren{}gp\opRightPren{}} 
returns the points moved by the group {\it gp}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{mulmod}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, \$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf mulmod}\opLeftPren{}a, \allowbreak{} b, 
\allowbreak{} p\opRightPren{}}, where \smath{a},
\smath{b} are non-negative integers both \smath{<} integer \smath{p},
returns \smath{a b \mod p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multiEuclidean}}\opLeftPren{}
{\it listOfElements}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(List(\$), \$)->Union(List(\$), "failed")}{EuclideanDomain}
{\smath{\mbox{\bf multiEuclidean}\opLeftPren{}[f_1, \allowbreak{} 
\ldots, f_n], z\opRightPren{}} returns a list of
coefficients \smath{[a_1, \ldots, a_n]}
such that \smath{z/\prod_{i=1}^n f_i = \sum\nolimits_{j=1}^n
{a_j/f_j}}.
If no such list of coefficients exists, \mbox{\tt "failed"} is
returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multinomial}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{2}{(I, List(I))->I}{IntegerCombinatoricFunctions}
{\smath{\mbox{\bf multinomial}\opLeftPren{}n, \allowbreak{} 
[m_1, \allowbreak{} m_2, \allowbreak{} \ldots, m_k]\opRightPren{}} returns the
multinomial coefficient \smath{n!/(m_1!
m_2! \ldots m_k!)}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multiple}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{FunctionSpaceAssertions}
{\smath{\mbox{\bf multiple}\opLeftPren{}x\opRightPren{}} 
directs the pattern matcher that \smath{x}
should preferably match a multi-term quantity in a sum or product.
For matching on lists, multiple(\smath{x}) tells the pattern
matcher that \smath{x} should match a list instead of an element
of a list.
This operation calls \spadfun{error} if \smath{x} is not a symbol.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multiplyCoefficients}}\opLeftPren{}
{\it function}, \allowbreak{}{\it  series}\opRightPren{}%
}%
}%
{2}{((Integer)->Coef, \$)->\$}{UnivariateTaylorSeriesCategory}
{\smath{\mbox{\bf multiplyCoefficients}\opLeftPren{}f, 
\allowbreak{} s\opRightPren{}} returns
\smath{\sum\nolimits_{n = 0}^\infty {f(n) a_n x^n}} where \smath{s} is the
series \smath{\sum\nolimits_{n = 0}^\infty{a_n x^n}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multiplyExponents}}\opLeftPren{}
{\it various}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->\$}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf multiplyExponents}\opLeftPren{}p, 
\allowbreak{} n\opRightPren{}},
where \smath{p} is a univariate polynomial or series,
returns a new polynomial
or series resulting from multiplying all exponents by the non
negative integer \smath{n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multiset}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{2}{(SparseUnivariatePolynomial(R), VarSet)->\$}{PolynomialCategory}
{\smath{\mbox{\bf multiset}\opLeftPren{}ls\opRightPren{}} 
creates a multiset with elements from \smath{ls}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{multivariate}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  symbol}\opRightPren{}%
}%
}%
{2}{(SparseUnivariatePolynomial(R), VarSet)->\$}{PolynomialCategory}
{\smath{\mbox{\bf multivariate}\opLeftPren{}p, \allowbreak{} v\opRightPren{}}
converts an anonymous univariate
polynomial \smath{p} to a polynomial in the variable \smath{v}.
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{name}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{1}{(\$)->String}{FileNameCategory}
{\smath{\mbox{\bf name}\opLeftPren{}f\opRightPren{}} returns 
the name part of the file name for file \smath{f}.
\newitem\smath{\mbox{\bf name}\opLeftPren{}op\opRightPren{}} 
returns the name of basic operator \smath{op}.
\newitem\smath{\mbox{\bf name}\opLeftPren{}s\opRightPren{}} 
returns symbol \smath{s} without its scripts.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nand}}\opLeftPren{}{\it boolean}, \allowbreak{}{\it  boolean}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BitAggregate}
{\smath{\mbox{\bf nand}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
returns the logical negation of
\smath{a} and \smath{b}, either booleans or bit aggregates.
Note: \smath{\mbox{\bf nand}\opLeftPren{}a, b) = true} if and only if one of
\smath{a} and \smath{b} is \smath{false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nary?}}\opLeftPren{}{\it basicOperator}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{BasicOperator}
{\smath{\mbox{\bf nary?}\opLeftPren{}op\opRightPren{}} 
tests if \smath{op} accepts an arbitrary number
of arguments.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ncols}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{RectangularMatrixCategory}
{\smath{\mbox{\bf ncols}\opLeftPren{}m\opRightPren{}} 
returns the number of columns in the matrix
or two-dimensional array \smath{m}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{new}}\opLeftPren{}{\it \opt{various}}\opRightPren{}%
}%
}%
{0}{()->\$}{ScriptFormulaFormat}
{\smath{\mbox{\bf new}\opLeftPren{}\opRightPren{}\$R} create a new object
of type \smath{R}. When \smath{R} is an aggregate,
\smath{new} creates an empty object.
Other variations are as follows:
\begin{simpleList}
\item\smath{\mbox{\bf new}\opLeftPren{}s\opRightPren{}}, where s is a symbol,
returns a new symbol whose name starts with \%\smath{s}.
\item\smath{\mbox{\bf new}\opLeftPren{}n, \allowbreak{} x\opRightPren{}} 
returns \smath{\mbox{\bf fill!}\opLeftPren{}new(n), 
\allowbreak{} x\opRightPren{}},
an aggregate of \smath{n} elements, each with value \smath{x}.
\item\smath{\mbox{\bf new}\opLeftPren{}m, \allowbreak{} n, 
\allowbreak{} r\opRightPren{}\$R} creates an \smath{m}-by-\smath{n} array
or matrix of type \smath{R} all of whose entries are \smath{r}.
\item\smath{\mbox{\bf new}\opLeftPren{}d, \allowbreak{} pre, 
\allowbreak{} e\opRightPren{}},
where \smath{d},  smath{pre},  and smath{e} are strings,
constructs the name of a new writable file with \smath{d}
as its directory, \smath{pre} as a prefix of its name and \smath{e}
as its extension. When \smath{d} or \smath{e} is the empty string,
a default is used.
The operation calls \spadfun{error} if a new file cannot be
written in the given directory.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{newLine}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->String}{DisplayPackage}
{\smath{\mbox{\bf newLine}\opLeftPren{}\opRightPren{}} sends a new line 
command to output.
See \spadtype{DisplayPackage}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nextColeman}}\opLeftPren{}{\it listOfIntegers}, 
\allowbreak{}{\it  listOfIntegers}, \allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{3}{(List(Integer), List(Integer), Matrix(Integer))->Matrix(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf nextColeman}\opLeftPren{}alpha, \allowbreak{} beta, 
\allowbreak{} C\opRightPren{}} generates the next
Coleman-matrix of column sums
{\it alpha} and row sums {\it beta} according to the lexicographical
order from bottom-to-top.
The first Coleman matrix is created using \smath{C = {\bf new}(1, 1, 0)}.
Also, \smath{\mbox{\bf new}\opLeftPren{}1, \allowbreak{} 1, 
\allowbreak{} 0\opRightPren{}} indicates that \smath{C} is the 
last Coleman matrix.
See \spadtype{SymmetricGroupCombinatoricFunctions} for details.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nextLatticePermutation}}\opLeftPren{}
{\it integers}, \allowbreak{}{\it  integers}, \allowbreak{}
{\it  boolean}\opRightPren{}%
}%
}%
{3}{(List(Integer), List(Integer), Boolean)->List(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf nextLatticePermutation}\opLeftPren{}lambda, 
\allowbreak{} lattP, \allowbreak{} constructNotFirst\opRightPren{}}
generates the
lattice permutation according to the proper partition 
\smath{lambda} succeeding
the lattice permutation \smath{lattP} in lexicographical order as
long as \smath{constructNotFirst} is \smath{true}.
If \smath{constructNotFirst} is \smath{false}, the first
lattice permutation is returned. The result \smath{nil} 
indicates that \smath{lattP} has no successor.
See \spadtype{SymmetricGroupCombinatoricFunctions} for details.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nextPartition}}\opLeftPren{}
{\it vectorOfIntegers}, \allowbreak{}{\it  vectorOfIntegers}, \allowbreak{}
{\it  integer}\opRightPren{}%
}%
}%
{3}{(List(Integer), Vector(Integer), Integer)->
Vector(Integer)}{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf nextPartition}\opLeftPren{}gamma, 
\allowbreak{} part, \allowbreak{} number\opRightPren{}} 
generates the partition of
\smath{number} which follows \smath{part} according to the
right-to-left lexicographical order.
The partition has the property that its components do not exceed
the corresponding components of \smath{gamma}.
the first partition is achieved by \smath{part={\tt []}}.
Also, {\tt []} indicates that \smath{part} is the last partition.
See \spadtype{SymmetricGroupCombinatoricFunctions} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nextPrime}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(I)->I}{IntegerPrimesPackage}
{\smath{\mbox{\bf nextPrime}\opLeftPren{}n\opRightPren{}} 
returns the smallest prime strictly larger
than \smath{n}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nil}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{List}
{\smath{\mbox{\bf nil}\opLeftPren{}\opRightPren{}\$R} 
returns the empty list of type \smath{R}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nilFactor}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(R, Integer)->\$}{Factored}
{\smath{\mbox{\bf nilFactor}\opLeftPren{}base, 
\allowbreak{} exponent\opRightPren{}} creates a 
factored object with a single factor
with no information about the kind of \smath{base}.
See \spadtype{Factored} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{node?}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{RecursiveAggregate}
{\smath{\mbox{\bf node?}\opLeftPren{}u, \allowbreak{} v\opRightPren{}} 
tests if node \smath{u} is contained in node
\smath{v} (either as a child, a child of a child, etc.).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nodes}}\opLeftPren{}
{\it recursiveAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{RecursiveAggregate}
{\smath{\mbox{\bf nodes}\opLeftPren{}a\opRightPren{}} 
returns a list of all the nodes of aggregate
\smath{a}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{noncommutativeJordanAlgebra?}}
\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf noncommutativeJordanAlgebra?}
\opLeftPren{}\opRightPren{}\$F} tests if the algebra
\smath{F} is flexible and Jordan admissible.
See \spadtype{FiniteRankNonAssociativeAlgebra}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nor}}\opLeftPren{}
{\it boolean}, \allowbreak{}{\it  boolean}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BitAggregate}
{\smath{\mbox{\bf nor}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns the logical \smath{nor} of booleans or
bit aggregates \smath{a} and \smath{b}.
Note: \smath{\mbox{\bf nor}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} = true if and only if both \smath{a} and
\smath{b} are \smath{false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{norm}}\opLeftPren{}
{\it element\opt{, option}}\opRightPren{}%
}%
}%
{1}{(\$)->R}{ComplexCategory}
{\smath{\mbox{\bf norm}\opLeftPren{}x\opRightPren{}} returns:
\begin{simpleList}
\item for complex \smath{x}: 
\smath{\mbox{\bf conjugate}\opLeftPren{}x\opRightPren{}}
.
\item for floats: the absolute value.
\item for quaternions or octonions: the sum of the squares of its coefficients.
\item for a domain of category \spadtype{FiniteRankAlgebra}:
the determinant of the regular representation of \smath{x} with 
respect to any basis.
\end{simpleList}
\smath{\mbox{\bf norm}\opLeftPren{}x\optinner{, p}\opRightPren{}}, 
where \smath{p} is a
positiveInteger and \smath{x} is
an element of a domain of category \spadtype{FiniteAlgebraExtensionField}
over ground field \smath{F},
returns the norm of \smath{x} with respect to the field of extension
degree \smath{d} over the ground field of size.
The default value of \smath{p} is 1.
The operation calls \spadfun{error} if \smath{p} does not divide
the extension degree of \smath{x}.
Note: \smath{\mbox{\bf norm}\opLeftPren{}x, p) = \prod_{i=0}^{n/p} x^{q^{pi}}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{normal?}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf normal?}\opLeftPren{}a\opRightPren{}},
where \smath{a} is a member of a domain of category
\smath{FiniteAlgebraicExtensionField} over a field \smath{F},
tests whether the element \smath{a}
is normal over the ground field \smath{F}, that is, if
\smath{a^{q^i}, 0 \leq i \leq {\bf extensionDegree}()-1} is 
an \smath{F}-basis,
where \smath{q = {\bf size}()}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{normalElement}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteAlgebraicExtensionField}
{\smath{\mbox{\bf normalElement}\opLeftPren{}\opRightPren{}\$R},
where \smath{R} is a domain of category
\smath{FiniteAlgebraicExtensionField} over a field \smath{F},
returns a element, normal over the ground field \smath{F},
that is, \smath{a^{q^i}, 0 \leq i < {\bf extensionDegree}()} 
is an \smath{F}-basis,
where \smath{q = {\bf size}()}.
At the first call, the element is computed by
\spadfunFrom{createNormalElement}{FiniteAlgebraicExtensionField}
then cached in a global variable.
On subsequent calls, the element is retrieved by referencing the
global variable.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{normalForm}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  listOfpolynomials}\opRightPren{}%
}%
}%
{2}{(Dpol, List(Dpol))->Dpol}{GroebnerPackage}
{\smath{\mbox{\bf normalForm}\opLeftPren{}poly, 
\allowbreak{} gb\opRightPren{}} reduces the polynomial \smath{poly}
modulo the precomputed Gr\"obner basis \smath{gb} giving a
canonical representative of the residue class.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{normalise}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(Matrix(Expression(Fraction(Integer))))->
Matrix(Expression(Fraction(Integer)))}{RadicalEigenPackage}
{\smath{\mbox{\bf normalise}\opLeftPren{}v\opRightPren{}} 
returns the column vector \smath{v} divided
by its Euclidean norm; when possible, the vector \smath{v} is
expressed in terms of radicals.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{normalize}}\opLeftPren{}
{\it element \opt, option}\opRightPren{}%
}%
}%
{1}{(Matrix(Expression(Fraction(Integer))))->
Matrix(Expression(Fraction(Integer)))}{RadicalEigenPackage}
{\smath{\mbox{\bf normalize}\opLeftPren{}flt\opRightPren{}} 
normalizes float \smath{flt} at current precision.
\newitem
\smath{\mbox{\bf normalize}\opLeftPren{}f\optinner{, x}\opRightPren{}} 
rewrites \smath{f} using the
least possible number of real algebraically independent kernels
involving symbol \smath{x}.
If no symbol \smath{x} is given, the operation
rewrites \smath{f} using the least possible number of real
algebraically independent kernels.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{normalizeAtInfinity}}\opLeftPren{}
{\it vectorOfFunctions}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->Vector(\$)}{FunctionFieldCategory}
{\smath{\mbox{\bf normalizeAtInfinity}\opLeftPren{}v\opRightPren{}} 
makes \smath{v} normal at infinity,
where
\smath{v} is a vector of functions defined on a curve.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{not}}\opLeftPren{}{\it boolean}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{Boolean}
{\smath{\mbox{\bf not}\opLeftPren{}n\opRightPren{}} 
returns the negation of boolean or bit aggregate
\smath{n}.
\newitem
\smath{\mbox{\bf not}\opLeftPren{}n\opRightPren{}} 
returns the bit-by-bit logical \smath{not} of the
small integer \smath{n}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nrows}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{RectangularMatrixCategory}
{\smath{\mbox{\bf nrows}\opLeftPren{}m\opRightPren{}} 
returns the number of rows in the matrix
or two-dimensional array \smath{m}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nthExponent}}\opLeftPren{}
{\it factored}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->Integer}{Factored}
{\smath{\mbox{\bf nthExponent}\opLeftPren{}u, \allowbreak{} n\opRightPren{}} 
returns the exponent of
the \eth{\smath{n}} factor of \smath{u}, or 0 if \smath{u} has no
such factor.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nthFactor}}\opLeftPren{}
{\it factor}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->R}{Factored}
{\smath{\mbox{\bf nthFactor}\opLeftPren{}u, \allowbreak{} n\opRightPren{}} 
returns the base of the \eth{\smath{n}}
factor of \smath{u}, or 1 if \smath{n} is not a valid index
for a factor.
If \smath{u} consists only of a unit, the unit is returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nthFlag}}\opLeftPren{}
{\it factored}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->Union("nil", "sqfr", "irred", "prime")}{Factored}
{\smath{\mbox{\bf nthFlag}\opLeftPren{}u, \allowbreak{} n\opRightPren{}} 
returns the information flag of the
\eth{\smath{n}} factor of \smath{u}, \mbox{\tt "nil"} if \smath{n} is not a
valid index for a factor.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nthFractionalTerm}}\opLeftPren{}
{\it partialFraction}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->\$}{PartialFraction}
{\smath{\mbox{\bf nthFractionalTerm}\opLeftPren{}p, 
\allowbreak{} n\opRightPren{}} extracts the \eth{\smath{n}}
fractional term from the partial fraction \smath{p}, or 0 if the
index \smath{n} is out of range.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nthRoot}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  integer}\opRightPren{}%
 \opand \mbox{\axiomFun{nthRootIfCan}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->\$}{RadicalCategory}
{\opkey{Argument \smath{x} can be of type \spadtype{Expression},
\spadtype{Complex}, \spadtype{Float} and \spadtype{DoubleFloat}, or
a series.}
\newitem \smath{\mbox{\bf nthRoot}\opLeftPren{}x, 
\allowbreak{} n\opRightPren{}} returns the \eth{\smath{n}} root of
\smath{x}.
If x is not an expression, the operation calls \spadfun{error} if
this is not possible.
\newitem \smath{\mbox{\bf nthRootIfCan}\opLeftPren{}z, 
\allowbreak{} n\opRightPren{}} returns the \eth{\smath{n}}
root of \smath{z} if possible, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{null?}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}
{\smath{\mbox{\bf null?}\opLeftPren{}s\opRightPren{}} 
is \smath{true} if \smath{s} is the \spadtype{SExpression}
object \smath{()}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nullary}}\opLeftPren{}\opRightPren{}%
}%
}%
{ C           -> (()->C)}{}{}
{\smath{\mbox{\bf nullary}\opLeftPren{}x\opRightPren{}}, 
where \smath{x} has type \smath{R}, returns a function
\smath{f} of type \spadsig{}{R} such that
such that \smath{f()} returns the value \smath{c}.
See also \spadfun{constant} for a similar operation.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nullary?}}\opLeftPren{}
{\it basicOperator}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{BasicOperator}
{\smath{\mbox{\bf nullary?}\opLeftPren{}op\opRightPren{}} 
tests if basic operator \smath{op} is nullary.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nullity}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{MatrixCategory}
{\smath{\mbox{\bf nullity}\opLeftPren{}m\opRightPren{}} 
returns the dimension of the null space of the matrix \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{nullSpace}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->List(Col)}{MatrixCategory}
{\smath{\mbox{\bf nullSpace}\opLeftPren{}m\opRightPren{}} 
returns a basis for the null space of the matrix \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfComponents}}\opLeftPren{}
{\it \opt{threeSpace}}\opRightPren{}%
}%
}%
{0}{()->NonNegativeInteger}{FunctionFieldCategory}
{\smath{\mbox{\bf numberOfComponents}\opLeftPren{}\opRightPren{}\$F} 
returns the number of absolutely irreducible components for
a domain \smath{F} of functions defined over a curve.
\newitem
\smath{\mbox{\bf numberOfComponents}\opLeftPren{}sp\opRightPren{}} 
returns the number of distinct
object components in the \spadtype{ThreeSpace} object \smath{s}
such as points, curves, and polygons.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfComputedEntries}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{LazyStreamAggregate}
{\smath{\mbox{\bf numberOfComputedEntries}\opLeftPren{}st\opRightPren{}} 
returns the number of explicitly computed entries of stream \smath{st}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfCycles}}\opLeftPren{}
{\it permutation}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{Permutation}
{\smath{\mbox{\bf numberOfCycles}\opLeftPren{}p\opRightPren{}} 
returns the number of non-trivial cycles of the permutation \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfDivisors}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf numberOfDivisors}\opLeftPren{}n\opRightPren{}} 
returns the number of integers
between 1 and \smath{n} inclusive which divide \smath{n}.
The number of divisors of \smath{n} is often denoted by
\smath{\tau(n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfFactors}}\opLeftPren{}
{\it factored}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{Factored}
{\smath{\mbox{\bf numberOfFactors}\opLeftPren{}u\opRightPren{}} 
returns the number of factors in factored form \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfFractionalTerms}}\opLeftPren{}
{\it partialFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{PartialFraction}
{\smath{\mbox{\bf numberOfFractionalTerms}\opLeftPren{}p\opRightPren{}} 
computes the number of
fractional terms in \smath{p}, or 0 if there is no fractional part.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfHues}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->PositiveInteger}{Color}
{\smath{\mbox{\bf numberOfHues}\opLeftPren{}\opRightPren{}} 
returns the number of total hues.
See also \spadfun{totalHues}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfImproperPartitions}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(Integer, Integer)->Integer}{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf numberOfImproperPartitions}\opLeftPren{}n, 
\allowbreak{} m\opRightPren{}} computes the number of
partitions of the nonnegative integer \smath{n} in \smath{m}
nonnegative parts with regarding
the order (improper partitions). Example:
\code{numberOfImproperPartitions (3, 3)} is 10, since
\code{[0, 0, 3], [0, 1, 2], [0, 2, 1], [0, 3, 0], [1, 0, 2], 
[1, 1, 1], [1, 2, 0], [2, 0, 1], [2, 1, 0], [3, 0, 0]}
are the possibilities. Note: this operation has a recursive implementation.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numberOfMonomials}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf numberOfMonomials}\opLeftPren{}p\opRightPren{}} 
gives the number of non-zero monomials in polynomial \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numer}}\opLeftPren{}{\it fraction}\opRightPren{}%
 \opand \mbox{\axiomFun{numerator}}\opLeftPren{}{\it fraction}\opRightPren{}%
}%
}%
{1}{(\$)->D}{QuotientFieldCategory}
{\opkey{Argument x is from domain \spadtype{Fraction(R)} for some 
domain \smath{R},
or of type \spadtype{Expression}}
\newitem
\smath{\mbox{\bf numer}\opLeftPren{}x\opRightPren{}} returns the 
numerator of \smath{x} as an object
of domain \smath{R}; if \smath{x} is of type \spadtype{Expression}, 
it returns
an object of domain \spadtype{SMP(D, Kernel(Expression R))}.
\newitem
\smath{\mbox{\bf numerator}\opLeftPren{}x\opRightPren{}} returns  
the numerator of \smath{x} as an element
of \spadtype{Fraction(R)}; if \smath{x} if of type \spadtype{Expression},
it returns an object of domain \spadtype{Expression}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numerators}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(R)}{ContinuedFraction}
{\smath{\mbox{\bf numerators}\opLeftPren{}cf\opRightPren{}} 
returns the stream of numerators of the approximants of
the continued fraction \smath{cf}.
If the continued fraction is finite, then the stream will be finite.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{numeric}}\opLeftPren{}
{\it expression\opt{, n}}\opRightPren{}%
}%
}%
{1}{(Expression(S))->Float}{Numeric}
{\smath{\mbox{\bf numeric}\opLeftPren{}x, \allowbreak{} n\opRightPren{}} 
returns a float approximation of expression \smath{x}
to \smath{n} decimal digits accurary.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{objectOf}}\opLeftPren{}
{\it typeAnyObject}\opRightPren{}%
}%
}%
{1}{(\$)->OutputForm}{Any}
{\smath{\mbox{\bf objectOf}\opLeftPren{}a\opRightPren{}} returns a 
printable form of an object
of type \spadtype{Any}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{objects}}\opLeftPren{}{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->Record(points:NonNegativeInteger,
curves:NonNegativeInteger, polygons:NonNegativeInteger,
constructs:NonNegativeInteger)}{ThreeSpace}
{\smath{\mbox{\bf objects}\opLeftPren{}sp\opRightPren{}} 
returns the \spadtype{ThreeSpace} object \smath{sp}.
The result is returned as record with fields:
\smath{points}, the number of points;
\smath{curves}, the number of curves;
\smath{polygons}, the number of polygons; and
\smath{constructs}, the number of constructs.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{oblateSpheroidal}}\opLeftPren{}
{\it function}\opRightPren{}%
}%
}%
{1}{(R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf oblateSpheroidal}\opLeftPren{}a\opRightPren{}},
where \smath{a} is a small float, returns a function to map the
point \smath{(\xi, \eta, \phi)} to cartesian coordinates
\smath{x = a sinh(\xi) sin(\eta) cos(\phi)}, \smath{y = a
sinh(\xi) sin(\eta) sin(\phi)}, \smath{z = a cosh(\xi) cos(\eta)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{octon}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  element}
\allowbreak $\,[$ , \allowbreak{}{\it  elements}$]$\opRightPren{}%
}%
}%
{2}{(Quaternion(R), Quaternion(R))
->\$}{Octonion}
{\smath{\mbox{\bf octon}\opLeftPren{}q_e, \allowbreak{} q_E\opRightPren{}} 
constructs an octonion
whose first 4 components are given by a quaternion \smath{q_e} and whose
last 4 components are given by a quaternion \smath{q_E}.
\newitem
\smath{\mbox{\bf octon}\opLeftPren{}r_e, \allowbreak{} r_i, \allowbreak{} r_j, 
\allowbreak{} r_k, \allowbreak{} r_E, \allowbreak{} r_I, \allowbreak{} r_J, 
\allowbreak{} r_K\opRightPren{}} constructs an octonion from scalars.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{odd?}}\opLeftPren{}{\it x}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{IntegerNumberSystem}
{\smath{\mbox{\bf odd?}\opLeftPren{}n\opRightPren{}} tests 
if integer \smath{n} is odd.
\newitem
\smath{\mbox{\bf odd?}\opLeftPren{}p\opRightPren{}} tests 
if \smath{p} is an odd permutation, that is, 
\smath{\mbox{\bf sign}\opLeftPren{}p\opRightPren{}}
is \smath{-1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{oneDimensionalArray}}\opLeftPren{}
{\it \optinit{integer, }elements}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{IntegerNumberSystem}
{\smath{\mbox{\bf oneDimensionalArray}\opLeftPren{}ls\opRightPren{}} 
creates a one-dimensional array consisting of
the elements of list \smath{ls}.
\newitem\smath{\mbox{\bf oneDimensionalArray}\opLeftPren{}n, 
\allowbreak{} s\opRightPren{}} creates a one-dimensional array of \smath{n}
elements, each with value \smath{s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{one?}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{MonadWithUnit}
{\smath{\mbox{\bf one?}\opLeftPren{}a\opRightPren{}} 
tests whether \smath{a} is the unit 1.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{open}}\opLeftPren{}
{\it file\opt{, string}}\opRightPren{}%
}%
}%
{1}{(Name)->\$}{FileCategory}
{\smath{\mbox{\bf open}\opLeftPren{}s\optinner{, mode}\opRightPren{}} 
returns the file \smath{s} open
in the indicated mode: \mbox{\tt "input"} or \mbox{\tt "output"}.
Argument \smath{mode} is \mbox{\tt "output"} by default.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{operator}}\opLeftPren{}
{\it symbol\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(BasicOperator)->BasicOperator}{ExpressionSpace}
{\smath{\mbox{\bf operator}\opLeftPren{}f, 
\allowbreak{} n\opRightPren{}} makes \smath{f} into an \smath{n}-ary operator.
If the second argument \smath{n} is omitted, \smath{f} has
arbitary \spadgloss{arity}, that is, \smath{f} takes an arbitrary
number of arguments.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{operators}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->List(BasicOperator)}{ExpressionSpace}
{\smath{\mbox{\bf operators}\opLeftPren{}f\opRightPren{}} returns a 
list of all basic operators in \smath{f},
regardless of level.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{optional}}\opLeftPren{}{\it symbol}\opRightPren{}%
}%
}%
{1}{(F)->F}{FunctionSpaceAssertions}
{\smath{\mbox{\bf optional}\opLeftPren{}x\opRightPren{}} tells the 
pattern matcher that \smath{x} can
match an identity (0 in a sum, 1 in a product or exponentiation),
or calls \spadfun{error} if \smath{x} is not a symbol.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{or}}\opLeftPren{}{\it boolean}, \allowbreak{}
{\it  boolean}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BitAggregate}
{\smath{a \or b} returns the logical \smath{or} of booleans or bit 
aggregates \smath{a} and \smath{b}.
\newitem
\smath{n \or m} returns the bit-by-bit logical \smath{or} of the small 
integers \smath{n} and \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{orbit}}\opLeftPren{}{\it group}, \allowbreak{}
{\it  elements}\opRightPren{}%
}%
}%
{2}{(\$, List(S))->Set(List(S))}{PermutationGroup}
{\smath{\mbox{\bf orbit}\opLeftPren{}gp, \allowbreak{} el\opRightPren{}} 
returns the orbit of the element \smath{el} under
the permutation group \smath{gp}, that is, the set of all 
points gained by applying each group element to \smath{el}.
\newitem
\smath{\mbox{\bf orbit}\opLeftPren{}gp, \allowbreak{} ls\opRightPren{}},
where \smath{ls} is a list or
unordered set of elements,
returns the orbit of
\smath{ls} under the permutation group \smath{gp}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{orbits}}\opLeftPren{}{\it group}\opRightPren{}%
}%
}%
{1}{(\$)->Set(Set(S))}{PermutationGroup}
{\smath{\mbox{\bf orbits}\opLeftPren{}gp\opRightPren{}} 
returns the orbits of the permutation group \smath{gp}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ord}}\opLeftPren{}{\it character}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{Character}
{\smath{\mbox{\bf ord}\opLeftPren{}c\opRightPren{}} returns an integer code
corresponding to the character \smath{c}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{order}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{FloatingPointSystem}
{\smath{\mbox{\bf order}\opLeftPren{}p\opRightPren{}} returns:
\begin{simpleList}
\item if \smath{p} is a float: the magnitude of \smath{p}
(Note: \smath{{\rm base}^{{\bf order}(x)} \leq |x| < base^{(1 +
{\bf order}(x))}}.)
\item if \smath{p} is a differential polynomial:
the maximum number of differentiations of a
differential indeterminate among all those appearing in \smath{p}.
\item if \smath{p} is a differential variable:
the number of differentiations of the differential indeterminate
appearing in \smath{p}.
\item if \smath{p} is an element of finite field: the order of an
element in the multiplicative group of the field (the function
calls \spadfun{error} if \smath{p} is 0).
\item if \smath{p} is a univariate power series:
the degree of the lowest order non-zero term in \smath{f}.
(A call to this operation results
in an infinite loop if \smath{f} has no non-zero terms.)
\item if \smath{p} is a \smath{q}-adic integer: the
exponent of the highest power of \smath{q} dividing \smath{p}
(see \spadtype{PAdicIntegerCategory}).
\item if \smath{p} is a permutation: the order of a permutation
\smath{p} as a group element.
\item if \smath{p} is permutation group: the order of the group.
\end{simpleList}
\smath{\mbox{\bf order}\opLeftPren{}p, \allowbreak{} q\opRightPren{}} 
returns the order of the differential
polynomial \smath{p} in differential indeterminate \smath{q}.
\newitem
\smath{\mbox{\bf order}\opLeftPren{}p, \allowbreak{} q\opRightPren{}} 
returns the order of multivariate series
\smath{p}
viewed as a series in \smath{q}
(this operation results in an infinite loop if \smath{f} has
no non-zero terms).
\newitem
\smath{\mbox{\bf order}\opLeftPren{}p, \allowbreak{} q\opRightPren{}} 
returns the largest \smath{n} such that
\smath{q^n} divides polynomial \smath{p}, that is, the order of
\smath{p(x)} at \smath{q(x)=0}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{orthonormalBasis}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Matrix(Expression(Fraction(Integer))))}{RadicalEigenPackage}
{\smath{\mbox{\bf orthonormalBasis}\opLeftPren{}M\opRightPren{}} 
returns the orthogonal matrix
\smath{B}
such that \smath{B M B^{-1}} is diagonal, or
calls \spadfun{error} if \smath{M} is not a symmetric matrix.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{output}}\opLeftPren{}{\it x}\opRightPren{}%
}%
}%
{1}{(OutputForm)->Void}{OutputPackage}
{\smath{\mbox{\bf output}\opLeftPren{}x\opRightPren{}} 
displays \smath{x} on the ``algebra output'' stream
defined by \spadsyscom{)set output algebra}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputAsFortran}}\opLeftPren{}
{\it outputForms}\opRightPren{}%
}%
}%
{1}{(List(OutputForm))->Void}{SpecialOutputPackage}
{\smath{\mbox{\bf outputAsFortran}\opLeftPren{}f\opRightPren{}}
outputs \spadtype{OutputForm} object \smath{f} in FORTRAN format
to the destination defined by
the system command \spadsyscom{)set output fortran}.
If \smath{f} is a list of \spadtype{OutputForm} objects,
each expression in \smath{f} is output in order.
\newitem
\smath{\mbox{\bf outputAsFortran}\opLeftPren{}s, 
\allowbreak{} f\opRightPren{}}, where \smath{s} is a string,
outputs \smath{s = f}, but is otherwise identical.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputAsTex}}\opLeftPren{}
{\it outputForms}\opRightPren{}%
}%
}%
{1}{(List(OutputForm))->Void}{SpecialOutputPackage}
{\smath{\mbox{\bf outputAsTex}\opLeftPren{}f\opRightPren{}}
outputs \spadtype{OutputForm} object \smath{f} in
\TeX{} format
to the destination defined by
the system command \spadsyscom{)set output tex}.
If \smath{f} is a list of \spadtype{OutputForm} objects,
each expression in \smath{f} is output in order.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputFixed}}\opLeftPren{}
{\it \opt{nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(NonNegativeInteger)->Void}{Float}
{\smath{\mbox{\bf outputFixed}\opLeftPren{}\optinner{n}\opRightPren{}} 
sets the output mode of
floats to fixed point notation,
that is, as an integer, a decimal point, and a number of digits.
If \smath{n} is given, then
\smath{n} digits are displayed after the decimal point.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputFloating}}\opLeftPren{}
{\it \opt{nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(NonNegativeInteger)->Void}{Float}
{\smath{\mbox{\bf outputFloating}\opLeftPren{}\optinner{n}\opRightPren{}} 
sets the output mode to
floating (scientific) notation,
that is,
\smath{m 10^e} is displayed as \code{
mEe}.
If \smath{n} is given, \smath{n} digits will be displayed after
the decimal point.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputForm}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf outputForm}\opLeftPren{}x\opRightPren{}} 
creates an object of type
\spadtype{OutputForm} from \smath{x},
an object of type \smath{Integer}, \smath{DoubleFloat},
\smath{String}, or \smath{Symbol}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputGeneral}}\opLeftPren{}
{\it \opt{nonNegativeInteger}}\opRightPren{}%
}%
}%
{0}{()->Void}{Float}
{\smath{\mbox{\bf outputGeneral}\opLeftPren{}\optinner{n}\opRightPren{}} 
sets the output
mode (default mode) to general notation, that is, numbers will be
displayed in either fixed or floating (scientific) notation
depending on the magnitude.
If \smath{n} is given, \smath{n} digits are displayed after
the decimal point.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{outputSpacing}}\opLeftPren{}
{\it nonNegativeInteger}\opRightPren{}%
}%
}%
{1}{(NonNegativeInteger)->Void}{Float}
{\smath{\mbox{\bf outputSpacing}\opLeftPren{}n\opRightPren{}} 
inserts a space after \smath{n} digits on output.
\smath{\mbox{\bf outputSpacing}\opLeftPren{}0\opRightPren{}} 
means no spaces are inserted.
By default, \smath{n = 10}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{over}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf over}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of type 
\spadtype{OutputForm} (normally unexposed),
creates an output form for the vertical fraction of 
\smath{o_1} over \smath{o_2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{overbar}}\opLeftPren{}
{\it outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf overbar}\opLeftPren{}o\opRightPren{}},
where \smath{o} is an object of type 
\spadtype{OutputForm} (normally unexposed),
creates the output form \smath{o} with an overbar.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pack!}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{KeyedAccessFile}
{\smath{\mbox{\bf pack!}\opLeftPren{}f\opRightPren{}} 
reorganizes the file \smath{f} on disk to recover unused space.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{packageCall}}\opLeftPren{}\opRightPren{}%
}%
}%
{ Symbol -> InputForm}{}{}
{\smath{\mbox{\bf packageCall}\opLeftPren{}f\opRightPren{}\$P},
where \smath{P} is the package \spadtype{InputFormFunctions1(R)} for
some type \spadtype{R},
returns the input form corresponding to f\$R.
See also \spadfun{interpret}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pade}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}, \allowbreak{}{\it  series}
\allowbreak $\,[$ , \allowbreak{}{\it  series}$]$\opRightPren{}%
}%
}%
{3}{(NonNegativeInteger, NonNegativeInteger, 
UnivariateTaylorSeries(R, x, pt))->
Union(Fraction(UnivariatePolynomial(x, R)), "failed")}
{PadeApproximantPackage}
{\smath{\mbox{\bf pade}\opLeftPren{}nd, \allowbreak{} dd, 
\allowbreak{} s \optinner{, ds}\opRightPren{}} computes the quotient of
polynomials (if it exists) with numerator degree at most \smath{nd}
and denominator degree at most \smath{dd}.
If a single univariate Taylor series \smath{s} is given, the quotient
approximate must match the series \smath{s} to order \smath{nd +
dd}.
If two series \smath{s} and \smath{ds} are given, \smath{ns} is the
numerator series of the function and \smath{ds} is the denominator
series.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{padicFraction}}\opLeftPren{}
{\it partialFraction}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{PartialFraction}
{\smath{\mbox{\bf padicFraction}\opLeftPren{}q\opRightPren{}} 
expands the fraction \smath{p}-adically in
the primes \smath{p} in the denominator of \smath{q}.
For example, \smath{\mbox{\bf padicFraction}
\opLeftPren{}3/(2^2)) = 1/2 + 1/(2^2)}.
Use \spadfunFrom{compactFraction}{PartialFraction} to return to compact form.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pair?}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}
{\smath{\mbox{\bf pair?}\opLeftPren{}s\opRightPren{}} tests if 
\smath{SExpression} object
is a non-null Lisp object.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{parabolic}}\opLeftPren{}{\it point}\opRightPren{}%
}%
}%
{1}{(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf parabolic}\opLeftPren{}pt\opRightPren{}} 
transforms \smath{pt} from parabolic
coordinates to Cartesian coordinates: the function produced will
map the point \smath{(u, v)} to \smath{x = 1/2 (u^2 - v^2)},
\smath{y = u v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{parabolicCylindrical}}\opLeftPren{}
{\it point}\opRightPren{}%
}%
}%
{1}{(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf parabolicCylindrical}\opLeftPren{}pt\opRightPren{}} 
transforms \smath{pt} from
parabolic cylindrical coordinates to Cartesian coordinates: the
function produced will map the point \smath{(u, v, z)} to \smath{x =
1/2(u^2 - v^2)}, \smath{y = u v}, \smath{z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{paraboloidal}}\opLeftPren{}{\it point}\opRightPren{}%
}%
}%
{1}{(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf paraboloidal}\opLeftPren{}pt\opRightPren{}} 
transforms \smath{pt} from paraboloidal
coordinates to Cartesian coordinates: the function produced will
map the point \smath{(u, v, phi)} to \smath{x = u v {\bf
cos}(\phi)}, \smath{y = u v {\bf sin}(\phi)}, \smath{z = 1/2 (u^2
- v^2)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{paren}}\opLeftPren{}
{\it expressions}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ExpressionSpace}
{\smath{\mbox{\bf paren}\opLeftPren{}f\opRightPren{}} returns (\smath{f})
unless \smath{f} is a list \smath{[f_1, \ldots, f_n]} in
which case it returns \smath{(f_1, \ldots, f_n)}.
This prevents \smath{f} or the constituent \smath{f_i}
from being evaluated when operators are applied to it.
For example, \code{log(1)} returns 0, but \code{log(paren 1)}
returns the formal kernel \code{log((1))}.
Also, {\bf atan}{\it ({\bf paren [}x, 2{\bf ]})} returns the 
formal kernel {\bf atan}{\it ((x, 2))}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{partialDenominators}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(R)}{ContinuedFraction}
{\smath{\mbox{\bf partialDenominators}\opLeftPren{}x\opRightPren{}} 
extracts the denominators
in \smath{x}.
If \smath{x = {\mbox {\bf continuedFraction}}
(b_0, [a_1, \ldots], [b_1, \ldots])},
then \smath{\mbox{\bf partialDenominators}\opLeftPren{}x) = [b_1, b_2\ldots]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{partialFraction}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  factored}\opRightPren{}%
}%
}%
{2}{(R, Factored(R))->\$}{PartialFraction}
{\smath{\mbox{\bf partialFraction}\opLeftPren{}numer, 
\allowbreak{} denom\opRightPren{}} is the main function for
constructing partial fractions.
The second argument \smath{denom} is the denominator and should be
factored.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{partialNumerators}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(R)}{ContinuedFraction}
{\smath{\mbox{\bf partialNumerators}\opLeftPren{}x\opRightPren{}} 
extracts the numerators in
\smath{x},
if \smath{x = {\mbox {\bf continuedFraction}}
(b_0, [a_1, \ldots], [b_1, \ldots], \ldots)},
then \smath{\mbox{\bf partialNumerators}\opLeftPren{}x) = [a_1, \ldots]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{partialQuotients}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->Stream(R)}{ContinuedFraction}
{\smath{\mbox{\bf partialQuotients}\opLeftPren{}x\opRightPren{}} 
extracts the partial quotients in
\smath{x}, if
\smath{x = {\mbox {\bf continuedFraction}}
(b_0, [a_1, \dots], [b_1, \ldots], \ldots)},
then \smath{\mbox{\bf partialQuotients}\opLeftPren{}x) = [b_0, b_1, \ldots]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{particularSolution}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  vector}\opRightPren{}%
}%
}%
{2}{(M, Col)->Union(Col, \mbox{\tt "failed"})}{LinearSystemMatrixPackage}
{\smath{\mbox{\bf aSolution}\opLeftPren{}M, 
\allowbreak{} v\opRightPren{}} finds a particular solution 
\smath{x} of the linear system \smath{Mx = v}.
The result \smath{x} is returned as a vector, or 
\mbox{\tt "failed"} if no solution exists.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{partition}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(I)->I}{IntegerCombinatoricFunctions}
{\smath{\mbox{\bf partition}\opLeftPren{}n\opRightPren{}} 
returns the number of partitions of the
integer \smath{n}.
This is the number of distinct ways that \smath{n} can be written
as a sum of positive integers.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{partitions}}\opLeftPren{}
{\it integer\opt{, integer, integer}}\opRightPren{}%
}%
}%
{1}{(Integer)->Stream(List(Integer))}{PartitionsAndPermutations}
{\smath{\mbox{\bf partitions}\opLeftPren{}i, 
\allowbreak{} j\opRightPren{}} is the stream of all partitions whose
number of parts and largest part are no greater than \smath{i} and
\smath{j}.
\newitem
\smath{\mbox{\bf partitions}\opLeftPren{}n\opRightPren{}} is 
the stream of all partitions of integer
\smath{n}.
\newitem
\smath{\mbox{\bf partitions}\opLeftPren{}p, \allowbreak{} l, 
\allowbreak{} n\opRightPren{}} is the stream of partitions of \smath{n}
whose number of parts is no greater than \smath{p} and whose
largest part is no greater than \smath{l}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{parts}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->List(R)}{TwoDimensionalArrayCategory}
{\smath{\mbox{\bf parts}\opLeftPren{}u\opRightPren{}} 
returns a list of the consecutive elements of \smath{u}.
Note: if \smath{u} is a list, \smath{\mbox{\bf parts}\opLeftPren{}u) = u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pastel}}\opLeftPren{}{\it color}\opRightPren{}%
}%
}%
{1}{(Color)->\$}{Palette}
{\smath{\mbox{\bf pastel}\opLeftPren{}c\opRightPren{}} 
sets the shade of a hue \smath{c} above ``bright'' but below ``light''.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pattern}}\opLeftPren{}
{\it rewriteRule}\opRightPren{}%
}%
}%
{1}{(\$)->Pattern(Base)}{RewriteRule}
{\smath{\mbox{\bf pattern}\opLeftPren{}r\opRightPren{}} 
returns the pattern corresponding to the left hand
side of the rewrite rule \smath{r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{patternMatch}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  expression}, \allowbreak{}
{\it  patternMatchResult}\opRightPren{}%
}%
}%
{3}{(\$, Pattern(S), PatternMatchResult(S, \$))->
PatternMatchResult(S, \$)}{PatternMatchable}
{\smath{\mbox{\bf patternMatch}\opLeftPren{}expr, \allowbreak{} pat, 
\allowbreak{} res\opRightPren{}} matches the pattern 
\smath{pat} to the expression 
\smath{expr}.
The argument \smath{res} contains the variables of \smath{pat}
which are already matched and their matches. Initially,
\smath{res} is the result of \spadfun{new()}, an empty list of matches.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{perfectNthPower?}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(I, NonNegativeInteger)->Boolean}{IntegerRoots}
{\smath{\mbox{\bf perfectNthPower?}\opLeftPren{}n, 
\allowbreak{} r\opRightPren{}} tests if \smath{n} is an
\eth{\smath{r}} power.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{perfectNthRoot}}\opLeftPren{}
{\it integer\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{2}{(I, NonNegativeInteger)->Union(I, "failed")}{IntegerRoots}
{\smath{\mbox{\bf perfectNthRoot}\opLeftPren{}n\opRightPren{}} 
returns a record
with fields ``base'' \smath{x} and
``exponent'' \smath{r} such that
\smath{n = x^r} and \smath{r} is the largest integer such
that \smath{n} is a perfect \eth{\smath{r}} power.
\newitem
\smath{\mbox{\bf perfectNthRoot}\opLeftPren{}n, 
\allowbreak{} r\opRightPren{}} returns the \eth{\smath{r}} root of
\smath{n} if \smath{n} is an \eth{\smath{r}} power, and \mbox{\tt "failed"}
otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{perfectSqrt}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(I)->Union(I, "failed")}{IntegerRoots}
{\smath{\mbox{\bf perfectSqrt}\opLeftPren{}n\opRightPren{}} 
returns the square root of \smath{n} if
\smath{n} is a perfect square, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{perfectSquare?}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(I)->Boolean}{IntegerRoots}
{\smath{\mbox{\bf perfectSquare?}\opLeftPren{}n\opRightPren{}} 
tests if \smath{n} is a perfect square.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{permanent}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(SquareMatrix(n, R))->R}{Permanent}
{\smath{\mbox{\bf permanent}\opLeftPren{}x\opRightPren{}} 
returns the permanent of a square matrix \smath{x},
equivalent to the \spadfun{determinant} except that 
coefficients have no change of sign.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{permutation}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(I, I)->I}{IntegerCombinatoricFunctions}
{\smath{\mbox{\bf permutation}\opLeftPren{}n, 
\allowbreak{} m\opRightPren{}} returns the number of permutations of
\smath{n} objects taken \smath{m} at a time.
Note: \smath{\mbox{\bf permutation}\opLeftPren{}n, m) = n!/(n-m)!}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{permutationGroup}}\opLeftPren{}
{\it listPermutations}\opRightPren{}%
}%
}%
{1}{(List(Permutation(S)))->\$}{PermutationGroup}
{\smath{\mbox{\bf permutationGroup}\opLeftPren{}ls\opRightPren{}} 
coerces a list of permutations \smath{ls} to the group generated by this list.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{permutationRepresentation}}\opLeftPren{}
{\it permutations\opt{, n}}\opRightPren{}%
}%
}%
{1}{(List(Integer))->Matrix(Integer)}{RepresentationPackage1}
{\smath{\mbox{\bf permutationRepresentation}\opLeftPren{}pi, 
\allowbreak{} n\opRightPren{}} returns the matrix
\smath{\delta_{i, pi(i)}} (Kronecker delta) if the permutation
\smath{pi} is in list notation and permutes
\smath{{1, 2, \ldots, n}}.
Argument \smath{pi} may either be permutation or a list of
integers describing a permutation by list notation.
\newitem
\smath{\mbox{\bf permutationRepresentation}\opLeftPren{}
[pi_1, \allowbreak{} \ldots, pi_k], n\opRightPren{}} returns
the list of matrices
\smath{[(\delta_{i, pi_1}(i)), \ldots, (\delta_{i, pi_k(i)})]}
(Kronecker delta) for permutations
\smath{pi_1}, \ldots, \smath{pi_k} of \smath{{1, 2, \ldots, n}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{permutations}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->Stream(List(Integer))}{PartitionsAndPermutations}
{\smath{\mbox{\bf permutations}\opLeftPren{}n\opRightPren{}} 
returns the stream of permutations
formed from \smath{1, 2, \ldots, n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{physicalLength}}\opLeftPren{}
{\it flexibleArray}\opRightPren{}%
\opand \mbox{\axiomFun{physicalLength!}}\opLeftPren{}
{\it flexibleArray}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{1}{(Integer)->Stream(List(Integer))}{PartitionsAndPermutations}
{\opkey{These operations apply to a flexible array \smath{a} and concern the
``physical length'' of \smath{a}, the maximum number of elements that \smath{a}
can hold.
When a destructive operation (such as \spadfun{concat!}) is applied
that increases the number
of elements of \smath{a} beyond this number, new storage is allocated
(generally to be about 50\% larger than current storage allocation)
and the elements from the old storage are copied over to the new storage area.}

\newitem\smath{\mbox{\bf physicalLength}\opLeftPren{}a\opRightPren{}} 
returns the physical length of \smath{a}.
\newitem\smath{\mbox{\bf physicalLength!}\opLeftPren{}a, 
\allowbreak{} n\opRightPren{}} causes
new storage to be allocated for the elements
of \smath{a} with a physical length of \smath{n}. The \spadfun{maxIndex}
elements from the old storage area are copied.
An \spadfun{error} is called if \smath{n} is less than 
\spadfun{maxIndex}\smath{(a)}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pi}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{TranscendentalFunctionCategory}
{\smath{\mbox{\bf pi}\opLeftPren{}\opRightPren{}} returns \smath{\pi},
also denoted by the special symbol \code{\%pi}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pile}}\opLeftPren{}
{\it listOfOutputForms}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf pile}\opLeftPren{}lo\opRightPren{}},
where \smath{lo} is a list of objects of type \spadtype{OutputForm} 
(normally unexposed),
creates the output form consisting of the elements of \smath{lo} displayed
as a pile, that is, each element begins on a new
line and is indented right to the same margin.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{plenaryPower}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, PositiveInteger)->\$}{NonAssociativeAlgebra}
{\opkey{Argument \smath{a} is a member of a domain of 
category \spadtype{NonAssociativeAlgebra}}
\newitem
\smath{\mbox{\bf plenaryPower}\opLeftPren{}a, 
\allowbreak{} n\opRightPren{}} is recursively defined to be
\smath{\mbox{\bf plenaryPower}\opLeftPren{}a, n-1) * 
{\bf plenaryPower}(a, n-1)} for \smath{n>1} and \smath{a} for \smath{n=1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{plusInfinity}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->OrderedCompletion(Integer)}{Infinity}
{\smath{\mbox{\bf plusInfinity}\opLeftPren{}\opRightPren{}} 
returns the constant {\tt \%plusInfinity}
denoting $+\infty$.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{point}}\opLeftPren{}
{\it u\opt{, option}}\opRightPren{}%
}%
}%
{1}{(List(R))->\$}{PointCategory}
{\smath{\mbox{\bf point}\opLeftPren{}p\opRightPren{}} returns a 
\spadtype{ThreeSpace} object which is composed of one component, 
the point \smath{p}.
\smath{\mbox{\bf point}\opLeftPren{}l\opRightPren{}} creates a point 
defined by a list \smath{l}.
\newitem
\newitem
\smath{\mbox{\bf point}\opLeftPren{}sp\opRightPren{}} checks to see if 
the \spadtype{ThreeSpace}
object \smath{sp}
is composed of only a single point and, if so, returns the point, or
calls \spadfun{error} if \smath{sp} has more than one point.
\newitem
\smath{\mbox{\bf point}\opLeftPren{}sp, \allowbreak{} l\opRightPren{}} 
adds a point component defined by a list
\smath{l} to the \spadtype{ThreeSpace} object \smath{sp}.
\newitem
\smath{\mbox{\bf point}\opLeftPren{}sp, \allowbreak{} i\opRightPren{}} 
adds a point component into a component
list of the \spadtype{ThreeSpace} object \smath{sp} at the index given 
by \smath{i}.
\newitem
\smath{\mbox{\bf point}\opLeftPren{}sp, \allowbreak{} p\opRightPren{}} 
adds a point component defined by the point \smath{p}
described as a list, to the \spadtype{ThreeSpace} object \smath{sp}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{point?}}\opLeftPren{}{\it space}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{ThreeSpace}
{\smath{\mbox{\bf point?}\opLeftPren{}sp\opRightPren{}} 
queries whether the \spadtype{ThreeSpace} object \smath{sp},
is composed of a single component which is a point.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pointColor}}\opLeftPren{}
{\it palette}\opRightPren{}%
}%
}%
{1}{(Float)->\$}{DrawOption}
{\smath{\mbox{\bf pointColor}\opLeftPren{}v\opRightPren{}} 
specifies a color \smath{v} for \twodim{} graph points.
This option is expressed in the form \code{pointColor == v}
in the \spadfun{draw} command.
Argument \smath{p} is either a palette or a float.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pointColorDefault}}\opLeftPren{}
{\it \opt{palette}}\opRightPren{}%
}%
}%
{0}{()->Palette}{ViewDefaultsPackage}
{\smath{\mbox{\bf pointColorDefault}\opLeftPren{}\opRightPren{}} 
returns the default color of points in a \twodim{} viewport.
\newitem
\smath{\mbox{\bf pointColorDefault}\opLeftPren{}p\opRightPren{}} sets 
the default color of points in a \twodim{} viewport to the palette \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pointSizeDefault}}\opLeftPren{}
{\it \opt{positiveInteger}}\opRightPren{}%
}%
}%
{0}{()->PositiveInteger}{ViewDefaultsPackage}
{\smath{\mbox{\bf pointSizeDefault}\opLeftPren{}\opRightPren{}} 
returns the default size of the points
in a \twodim{} viewport.
\newitem
\smath{\mbox{\bf pointSizeDefault}\opLeftPren{}i\opRightPren{}} 
sets the default size of the points in
a \twodim{} viewport to \smath{i}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{polarCoordinates}}\opLeftPren{}{\it x}\opRightPren{}%
}%
}%
{1}{(\$)->Record(r:R, phi:R)}{ComplexCategory}
{\smath{\mbox{\bf polarCoordinates}\opLeftPren{}x\opRightPren{}} returns
a record with components \smath{(r, \phi)} such that \smath{x =
re^{i\phi}.}}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{polar}}\opLeftPren{}{\it point}\opRightPren{}%
}%
}%
{1}{(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf polar}\opLeftPren{}pt\opRightPren{}} 
transforms point \smath{pt} from polar coordinates to
Cartesian coordinates. The function produced will map the point
\smath{(r, \theta)} to \smath{x = r {\bf cos}(\theta)} , 
\smath{y = r {\bf sin}(\theta)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pole?}}\opLeftPren{}{\it series}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{PowerSeriesCategory}
{\smath{\mbox{\bf pole?}\opLeftPren{}f\opRightPren{}} tests if the power 
series \smath{f} has a pole.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{polygamma}}\opLeftPren{}{\it k}, \allowbreak{}
{\it  x}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{SpecialFunctionCategory}
{\smath{\mbox{\bf polygamma}\opLeftPren{}k, \allowbreak{} x\opRightPren{}} 
is the \eth{\smath{k}} derivative of
\smath{\mbox{\bf digamma}\opLeftPren{}x\opRightPren{}}, 
often written \smath{\psi(k, x)} in the
literature.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{polygon}}\opLeftPren{}
{\it \optinit{sp, }listOfPoints}\opRightPren{}%
 \opand \mbox{\axiomFun{polygon?}}\opLeftPren{}{\it space}\opRightPren{}%
}%
}%
{1}{(List(Point(R)))->\$}{ThreeSpace}
{\smath{\mbox{\bf polygon}\opLeftPren{}\optfirst{sp, }lp\opRightPren{}} 
adds a polygon defined
by \smath{lp} to the \spadtype{ThreeSpace} object \smath{sp}.
Each \smath{lp} is either a list of points (objects of type \spadtype{Point})
or else a list of small floats.
If \smath{sp} is omitted, it is understood to be empty.
\newitem
\smath{\mbox{\bf polygon}\opLeftPren{}sp\opRightPren{}} returns 
\spadtype{ThreeSpace} object \smath{sp} as a list
of polygons, or an error if \smath{sp} is not composed of a single polygon.
\newitem
\smath{\mbox{\bf polygon?}\opLeftPren{}sp\opRightPren{}} tests 
if the \spadtype{ThreeSpace} object \smath{sp}
contains a single polygon component.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{polynomial}}\opLeftPren{}{\it series}, 
\allowbreak{}{\it  integer}\allowbreak $\,[$ , \allowbreak{}
{\it  integer}$]$\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->Polynomial(Coef)}{UnivariateTaylorSeriesCategory}
{\smath{\mbox{\bf polynomial}\opLeftPren{}s, \allowbreak{} k\opRightPren{}} 
returns a polynomial consisting of the
sum of all terms of
series \smath{s} of degree \smath{\leq k} and greater than or
equal to 0.
\newitem
\smath{\mbox{\bf polynomial}\opLeftPren{}s, \allowbreak{} k_1, 
\allowbreak{} k_2\opRightPren{}} returns a polynomial consisting of the sum
of all terms of Taylor series \smath{s} of degree \smath{d}
with \smath{0 \leq k_1 \leq d \leq k_2}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pop!}}\opLeftPren{}{\it stack}\opRightPren{}%
}%
}%
{1}{(\$)->S}{StackAggregate}
{\smath{\mbox{\bf pop!}\opLeftPren{}s\opRightPren{}} returns 
the top element \smath{x}
from stack \smath{s}, destructively removing it from \smath{s},
or calls \spadfun{error} if \smath{s} is empty.
Note: Use \smath{\mbox{\bf top}\opLeftPren{}s\opRightPren{}} 
to obtain \smath{x} without removing it from \smath{s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{position}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  aggregate}\allowbreak $\,[$ , \allowbreak{}
{\it  index}$]$\opRightPren{}%
}%
}%
{2}{(S, \$)->Integer}{FiniteLinearAggregate}
{\smath{\mbox{\bf position}\opLeftPren{}x, 
\allowbreak{} a\optinner{, n}\opRightPren{}} returns the index \smath{i}
of the first occurrence of \smath{x} in \smath{a} where \smath{i
\geq n}, and \smath{\mbox{\bf minIndex}\opLeftPren{}a) - 1} 
if no such \smath{x} is
found.
The default value of \smath{n} is 1.
\newitem \smath{\mbox{\bf position}\opLeftPren{}cc, \allowbreak{} t, 
\allowbreak{} i\opRightPren{}} returns the position \smath{j
>= i} in \smath{t} of the first character belonging to character
class \smath{cc}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{positive?}}\opLeftPren{}
{\it orderedSetElement}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{OrderedRing}
{\smath{\mbox{\bf positive?}\opLeftPren{}x\opRightPren{}} 
tests if \smath{x} is strictly greater than 0.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{positiveRemainder}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf positiveRemainder}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}, where \smath{b > 1}, yields
\smath{r} where \smath{0 \leq r < b} and \smath{r = a \rem b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{possiblyInfinite?}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{StreamAggregate}
{\smath{\mbox{\bf possiblyInfinite?}\opLeftPren{}s\opRightPren{}} 
tests if the stream \smath{s} could
possibly have an infinite number of elements.
Note: for many datatypes,
\smath{\mbox{\bf possiblyInfinite?}\opLeftPren{}s\opRightPren{}} 
\smath{= \mbox{\bf not } \mbox{\bf explictlyFinite?}(s)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{postfix}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf postfix}\opLeftPren{}op, \allowbreak{} a\opRightPren{}},
where \smath{op} and \smath{a} are objects of type
\spadtype{OutputForm} (normally unexposed),
creates an output form which prints as: \smath{a\quad{}{\rm op}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{powerAssociative?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{\smath{\mbox{\bf powerAssociative?}\opLeftPren{}\opRightPren{}\$F}, 
where \spad{F} is
a domain of category \spadtype{FiniteRankNonAssociativeAlgebra},
tests if all subalgebras generated by
a single element are associative.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{powerSum}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{ I -> SPOL RN}{}{}
{\smath{\mbox{\bf powerSum}\opLeftPren{}n\opRightPren{}} 
is the \smath{n} th power sum symmetric
function.
See \spadtype{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{powmod}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, \$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf powmod}\opLeftPren{}a, \allowbreak{} b, 
\allowbreak{} p\opRightPren{}},
where \smath{a} and \smath{b} are non-negative integers, each \smath{< p},
returns \smath{a^b\mod p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{precision}}\opLeftPren{}
{\it \opt{positiveInteger}}\opRightPren{}%
}%
}%
{0}{()->PositiveInteger}{FloatingPointSystem}
{\smath{\mbox{\bf precision}\opLeftPren{}\opRightPren{}} 
returns the precision of \spadtype{Float} values
in decimal digits.
\newitem
\smath{\mbox{\bf precision}\opLeftPren{}n\opRightPren{}} 
set the precision in the base to \smath{n}
decimal digits.
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prefix}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  listOfOutputForms}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf prefix}\opLeftPren{}o, \allowbreak{} lo\opRightPren{}},
where \smath{o} is an object of type \spadtype{OutputForm} (normally unexposed)
and \smath{lo} is a list of objects of type \spadtype{OutputForm},
creates an output form depicting the \smath{n}ary prefix application
of \smath{o} to a tuple of arguments given by list \smath{lo}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prefix?}}\opLeftPren{}{\it string}, \allowbreak{}
{\it  string}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{StringAggregate}
{\smath{\mbox{\bf prefix?}\opLeftPren{}s, \allowbreak{} t\opRightPren{}} 
tests if the string \smath{s} is the initial
substring of \smath{t}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prefixRagits}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(\$)->List(Integer)}{RadixExpansion}
{\smath{\mbox{\bf prefixRagits}\opLeftPren{}rx\opRightPren{}} 
returns the non-cyclic part of the
ragits of the fractional part of a radix expansion.
For example, if \smath{x = 3/28 = 0.10 714285 714285 \ldots}, then
\smath{\mbox{\bf prefixRagits}\opLeftPren{}x)=[1, 0]}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{presub}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf presub}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of type 
\spadtype{OutputForm} (normally unexposed),
creates an output form for \smath{o_1} presubscripted by \smath{o_2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{presuper}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf presuper}\opLeftPren{}o_1, 
\allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of type 
\spadtype{OutputForm} (normally unexposed),
creates an output form for \smath{o_1} presuperscripted by \smath{o_2}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primaryDecomp}}\opLeftPren{}
{\it ideal}\opRightPren{}%
}%
}%
{1}{(PolynomialIdeals(Fraction(Integer), 
DirectProduct(nv, NonNegativeInteger), vl, 
DistributedMultivariatePolynomial(vl, Fraction(Integer))))->
List(PolynomialIdeals(Fraction(Integer), 
DirectProduct(nv, NonNegativeInteger), vl, 
DistributedMultivariatePolynomial(vl, Fraction(Integer))))}
{IdealDecompositionPackage}
{\smath{\mbox{\bf primaryDecomp}\opLeftPren{}I\opRightPren{}} 
returns a list of primary ideals such
that their intersection is the ideal \smath{I}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prime}}\opLeftPren{}
{\it outputForm\opt{, positiveInteger}}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf prime}\opLeftPren{}o\optinner{, n}\opRightPren{}},
where \smath{o} is an object of type \spadtype{OutputForm} 
(normally unexposed),
creates an output form for \smath{o} following by \smath{n}
primes (that is, a prime like `` ' '').
By default, \smath{n = 1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prime?}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{UniqueFactorizationDomain}
{\smath{\mbox{\bf prime?}\opLeftPren{}x\opRightPren{}} 
tests if \smath{x} cannot be written as the
product of two non-units, that is, \smath{x} is an irreducible
element.
Argument \smath{x} may be an integer, a polynomial, an ideal, or,
in general, any element of a domain of category
\spadtype{UniqueFactorizationDomain}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primeFactor}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(R, Integer)->\$}{Factored}
{\smath{\mbox{\bf primeFactor}\opLeftPren{}base, 
\allowbreak{} exponent\opRightPren{}} creates a factored object with
a single factor whose \smath{base} is asserted to be prime (flag =
\mbox{\tt "prime"}).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primeFrobenius}}\opLeftPren{}
{\it finiteFieldElement\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->\$}{FieldOfPrimeCharacteristic}
{\opkey{Argument \smath{a} is a member of a domain of category
\spadtype{FieldOfPrimeCharacteristic(p)}.}
\newitem
\smath{\mbox{\bf primeFrobenius}\opLeftPren{}a\optinner{, s}\opRightPren{}} 
returns \smath{a^{p^s}}.
The default value of \smath{s} is 1.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primes}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(I, I)->List(I)}{IntegerPrimesPackage}
{\smath{\mbox{\bf primes}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
returns a list of all primes \smath{p} with \smath{a \leq p \leq b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primitive?}}\opLeftPren{}
{\it finiteFieldElement}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{FiniteFieldCategory}
{\smath{\mbox{\bf primitive?}\opLeftPren{}b\opRightPren{}} 
tests whether the element \smath{b}
of a finite field is a generator of the (cyclic) multiplicative group of the
field, that is, is a primitive element.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primitiveElement}}\opLeftPren{}
{\it expressions\opt{, expression}}\opRightPren{}%
}%
}%
{2}{(F, F)->Record(primelt:F, pol1:SparseUnivariatePolynomial(F), 
pol2:SparseUnivariatePolynomial(F), prim:SparseUnivariatePolynomial(F))}
{FunctionSpacePrimitiveElement}
{\smath{\mbox{\bf primitiveElement}\opLeftPren{}a_1, 
\allowbreak{} a_2\opRightPren{}} returns a record with four
components: a primitive element \smath{a} with selector
\smath{primelt}, and three polynomials \smath{q_1}, \smath{q_2},
and \smath{q} with selectors \smath{pol1}, \smath{pol2}, and
\smath{prim}.
The prime element \smath{a} is such that the algebraic extension
generated by \smath{a_1} and \smath{a_2} is the same as that
generated by \smath{a}, \smath{a_i = q_i(a)} and \smath{q(a) = 0}.
The minimal polynomial for \smath{a_2} may involve \smath{a_1}, but
the minimal polynomial for \smath{a_1} may not involve \smath{a_2}.
This operations uses \spadfun{resultant}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primitiveMonomials}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->List(\$)}{PolynomialCategory}
{\smath{\mbox{\bf primitiveMonomials}\opLeftPren{}p\opRightPren{}} 
gives the list of monomials of the
polynomial \smath{p} with their coefficients removed.
Note: \smath{\mbox{\bf primitiveMonomials}\opLeftPren{}
\sum {a_i X^{(i)}}) = [X^{(1)}, \ldots, X^{(n)}]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{primitivePart}}\opLeftPren{}
{\it polynomial\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{FiniteAbelianMonoidRing}
{\smath{\mbox{\bf primitivePart}\opLeftPren{}p\optinner{, v}
\opRightPren{}} returns
the unit normalized form of polynomial \smath{p} divided 
by the \spadfun{content} of \smath{p} with respect to variable \smath{v}.
If no \smath{v} is given, the content is removed with respect to all variables.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{principalIdeal}}\opLeftPren{}
{\it listOfPolynomials}\opRightPren{}%
}%
}%
{1}{(List(\$))->Record(coef:List(\$), generator:\$)}
{PrincipalIdealDomain}
{\smath{\mbox{\bf principalIdeal}\opLeftPren{}[f_1, 
\allowbreak{} \ldots, f_n]\opRightPren{}} returns a record whose
``generator'' component is a generator of the ideal generated by
\smath{[f_1, \ldots, f_n]} whose ``coef'' component is a list of
coefficients \smath{[c_1, \ldots, c_n]} such that
\smath{generator = \sum_i c_i \, f_i}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{print}}\opLeftPren{}{\it outputForm}\opRightPren{}%
}%
}%
{1}{(OutputForm)->Void}{PrintPackage}
{\smath{\mbox{\bf print}\opLeftPren{}o\opRightPren{}} 
writes the output form \smath{o} on standard
output using the two-dimensional formatter.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{product}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{GradedAlgebra}
{\smath{\mbox{\bf product}\opLeftPren{}f(n), 
\allowbreak{} n = a..b\opRightPren{}} returns
\smath{\prod\nolimits_{n=a}^b{f(n)}} as a formal product.
\newitem\smath{\mbox{\bf product}\opLeftPren{}f(n), 
\allowbreak{} n\opRightPren{}} returns the formal product
\smath{P(n)} verifying \smath{{P(n+1)/P(n)} = f(n)}.
\newitem\smath{\mbox{\bf product}\opLeftPren{}s, 
\allowbreak{} t\opRightPren{}}, where \smath{s} and \smath{t} are
cartesian tensors, returns the outer product of \smath{s} and
\smath{t}.
For example, if \smath{r = {\bf product}(s, t)} for rank 2 tensors
\smath{s} and \smath{t}, then \smath{r} is a rank 4 tensor given
by \smath{r_{i, j, k, l} = s_{i, j} t_{k, l}}.
\newitem\smath{\mbox{\bf product}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}, where \smath{a} and \smath{b} are
elements of a graded algebra returns the degree-preserving linear
product.
See \spadtype{GradedAlgebra} for details.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prolateSpheroidal}}\opLeftPren{}
{\it smallFloat}\opRightPren{}%
}%
}%
{1}{(R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf prolateSpheroidal}\opLeftPren{}a\opRightPren{}} returns a
function to transform prolate spheroidal coordinates to Cartesian coordinates.
This function will map the point
\smath{(\xi, \eta, \phi)} to
\smath{x = a {\rm sinh}(\xi) {\rm sin}(\eta) {\rm cos}(\phi)},
\smath{y = a {\rm sinh}(\xi) {\rm sin}(\eta) {\rm sin}(\phi)},
\smath{z = a {\rm cosh}(\xi) {\rm cos}(\eta)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{prologue}}\opLeftPren{}{\it text}\opRightPren{}%
}%
}%
{1}{(\$)->List(String)}{ScriptFormulaFormat}
{\smath{\mbox{\bf prologue}\opLeftPren{}t\opRightPren{}} 
extracts the prologue section of a
IBM SCRIPT Formula Formatter or \TeX{} formatted object \smath{t}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{properties}}\opLeftPren{}
{\it basicOperator\opt{, prop}}\opRightPren{}%
}%
}%
{1}{(\$)->AssociationList(String, None)}{BasicOperator}
{\smath{\mbox{\bf properties}\opLeftPren{}op\opRightPren{}} 
returns the list of all the properties currently attached to \smath{op}.
\newitem
\smath{\mbox{\bf property}\opLeftPren{}op, \allowbreak{} s\opRightPren{}} 
returns the value of property \smath{s} if
it is attached to \smath{op}, and \mbox{\tt "failed"} otherwise.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pseudoDivide}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(coef:R, quotient:\$, remainder:\$)}
{UnivariatePolynomialCategory}
{\smath{\mbox{\bf pseudoDivide}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} returns \smath{(c, q, r)}, when
\smath{p' := p \mbox{ \bf leadingCoefficient}(q)^{{\rm deg}(p) - {\rm
deg}(q) + 1}= c p} is pseudo right-divided by \smath{q}, that is,
\smath{p' = s q + r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pseudoQuotient}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf pseudoQuotient}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} returns \smath{r}, the quotient when
\smath{p' := p {\rm leadingCoefficient}(q)^{{\rm deg} p - {\rm deg} q + 1}}
is pseudo right-divided by \smath{q}, that is,
\smath{p' = s q + r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pseudoRemainder}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf pseudoRemainder}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} = \smath{r}, for polynomials
\smath{p} and \smath{q}, returns the remainder when
\smath{p' := p {\rm leadingCoefficient}(q)^{{\rm deg} p - {\rm deg} q + 1}}
is
pseudo right-divided by \smath{q}, that is, \smath{p' = s q + r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{puiseux}}\opLeftPren{}
{\it expression\opt{, options}}\opRightPren{}%
}%
}%
{1}{(FE)->Any}{ExpressionToUnivariatePowerSeries}
{\smath{\mbox{\bf puiseux}\opLeftPren{}f\opRightPren{}} 
returns a Puiseux expansion of the expression
\smath{f}.
Note: \smath{f} should have only one variable; the series will be
expanded in powers of that variable.
Also, if \smath{x} is a symbol,
\smath{\mbox{\bf puiseux}\opLeftPren{}x\opRightPren{}} returns \smath{x} 
as a Puiseux series.
\newitem
\smath{\mbox{\bf puiseux}\opLeftPren{}f, \allowbreak{} x = a\opRightPren{}} 
expands the expression \smath{f} as a
Puiseux series in powers of \smath{(x - a)}.
\newitem
\smath{\mbox{\bf puiseux}\opLeftPren{}f, \allowbreak{} n\opRightPren{}} 
returns a Puiseux expansion of the expression
\smath{f}.
Note: \smath{f} should have only one variable; the series will be
expanded in powers of that variable and terms will be computed up
to order at least \smath{n}.
\newitem
\smath{\mbox{\bf puiseux}\opLeftPren{}f, \allowbreak{} x = a, 
\allowbreak{} n\opRightPren{}} expands the expression \smath{f} as a
Puiseux series in powers of \smath{(x - a)}; terms will be
computed up to order at least \smath{n}.
\newitem
\smath{\mbox{\bf puiseux}\opLeftPren{}n {\tt +->} a(n), 
\allowbreak{} x = a, \allowbreak{} r_0.., \allowbreak{} r\opRightPren{}} 
returns
\smath{\sum\nolimits_{n = r_0, r_0 + r, r_0 + 2 r, \ldots} a(n) (x - a)^n}.
\newitem
\smath{\mbox{\bf puiseux}\opLeftPren{}a(n), 
\allowbreak{} n, \allowbreak{} x = a, \allowbreak{} r_0.., 
\allowbreak{} r\opRightPren{}} returns
\smath{\sum\nolimits_{n = r_0, r_0 + r, r_0 + 2 r, \ldots} a(n) (x - a)^n}.
\newitem Note: Each of the last two commands have alternate forms
whose third argument is the finite segment \smath{r_0..r_1}
producing a similar series with
a finite number of terms.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{push!}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  stack}\opRightPren{}%
}%
}%
{2}{(S, \$)->S}{StackAggregate}
{\smath{\mbox{\bf push!}\opLeftPren{}x, 
\allowbreak{} s\opRightPren{}} pushes \smath{x} onto stack \smath{s}, that
is, destructively changing \smath{s} so as to have a new first
(top) element \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pushdown}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  symbol}\opRightPren{}%
 \opand \mbox{\axiomFun{pushdterm}}\opLeftPren{}
{\it monomial}, \allowbreak{}{\it  symbol}\opRightPren{}%
}%
}%
{2}{(PRF, OV)->PRF}{MPolyCatRationalFunctionFactorizer}
{\smath{\mbox{\bf pushdown}\opLeftPren{}prf, 
\allowbreak{} var\opRightPren{}} pushes all top level occurences of the
variable \smath{var} into the coefficient domain for the
polynomial \smath{prf}.
\newitem\smath{\mbox{\bf pushdterm}\opLeftPren{}monom, 
\allowbreak{} var\opRightPren{}} pushes all top level
occurences of the variable \smath{var} into the coefficient domain
for the monomial \smath{monom}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pushucoef}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  variable}\opRightPren{}%
}%
}%
{2}{(SparseUnivariatePolynomial(Polynomial(R)), OV)->PRF}
{MPolyCatRationalFunctionFactorizer}
{\smath{\mbox{\bf pushucoef}\opLeftPren{}upoly, 
\allowbreak{} var\opRightPren{}} converts the anonymous univariate
polynomial \smath{upoly} to a polynomial in \smath{var} over
rational functions.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pushuconst}}\opLeftPren{}
{\it rationalFunction}, \allowbreak{}{\it  variable}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(R)), OV)->PRF}{MPolyCatRationalFunctionFactorizer}
{\smath{\mbox{\bf pushuconst}\opLeftPren{}r, \allowbreak{} var\opRightPren{}} 
takes a rational function and raises
all occurences
of the variable \smath{var} to the polynomial level.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{pushup}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  variable}\opRightPren{}%
}%
}%
{2}{(PRF, OV)->PRF}{MPolyCatRationalFunctionFactorizer}
{\smath{\mbox{\bf pushup}\opLeftPren{}prf, \allowbreak{} var\opRightPren{}} 
raises all occurences of the variable
\smath{var} in the coefficients of the polynomial \smath{prf} back
to the polynomial level.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{qelt}}\opLeftPren{}{\it u\opt{, options}}
\opRightPren{}%
}%
}%
{2}{(\$, Dom)->Im}{EltableAggregate}
{\smath{\mbox{\bf qelt}\opLeftPren{}u, \allowbreak{} p\optinner{, options}
\opRightPren{}} is equivalent to
a corresponding \spadfun{elt} form except that it
performs no check that indicies are in range.
Use HyperDoc to discover if a given domain has this alternative operation.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{qsetelt!}}\opLeftPren{}{\it u}, \allowbreak{}
{\it  x}, \allowbreak{}{\it  y}\allowbreak $\,[$ , \allowbreak{}
{\it  z}$]$\opRightPren{}%
}%
}%
{3}{(\$, Dom, Im)->Im}{EltableAggregate}
{\smath{\mbox{\bf qsetelt!}\opLeftPren{}u, \allowbreak{} x, 
\allowbreak{} y\optinner{, z}\opRightPren{}} is equivalent to
a corresponding \spadfun{setelt} form except that it
performs no check that indicies are in range.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quadraticForm}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(SquareMatrix(n, K))->\$}{QuadraticForm}
{\smath{\mbox{\bf quadraticForm}\opLeftPren{}m\opRightPren{}} 
creates a quadratic form from a symmetric, square matrix \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quatern}}\opLeftPren{}{\it element}, \allowbreak{}
{\it  element}, \allowbreak{}{\it  element}, \allowbreak{}
{\it  element}\opRightPren{}%
}%
}%
{4}{(R, R, R, R)->\$}{QuaternionCategory}
{\smath{\mbox{\bf quatern}\opLeftPren{}r, \allowbreak{} i, \allowbreak{} j, 
\allowbreak{} k\opRightPren{}} constructs a quaternion from scalars.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{queue}}\opLeftPren{}
{\it \opt{listOfElements}}\opRightPren{}%
}%
}%
{0}{()->\$}{QueueAggregate}
{\smath{\mbox{\bf queue}\opLeftPren{}\opRightPren{}}\$\smath{R} 
returns an empty queue of type
\smath{R}.
\newitem
\smath{\mbox{\bf queue}\opLeftPren{}[x, \allowbreak{} y, 
\allowbreak{} \ldots, z]\opRightPren{}} creates a queue with first (top)
element \smath{x}, second element \smath{y}, \ldots, and last
(bottom) element \smath{z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quickSort}}\opLeftPren{}
{\it predicate}, \allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S, S)->Boolean, V)->V}{FiniteLinearAggregateSort}
{\smath{\mbox{\bf quickSort}\opLeftPren{}f, 
\allowbreak{} agg\opRightPren{}} sorts the aggregate agg with the
ordering predicate \smath{f} using the quicksort algorithm.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quo}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{NonNegativeInteger}
{\smath{a \quo b} returns the quotient of \smath{a} and \smath{b}
discarding the remainder.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quoByVar}}\opLeftPren{}{\it series}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnivariateTaylorSeriesCategory}
{\smath{\mbox{\bf quoByVar}
\opLeftPren{}a_0 + a_1 x + a_2 x^2 + \cdots\opRightPren{}}
returns \smath{a_1 + a_2 x + a_3 x^2 + \cdots} Thus, this function
subtracts the constant term and divides by the series variable.
This function is used when Laurent series are represented by a
Taylor series and an order.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quote}}\opLeftPren{}{\it outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf quote}\opLeftPren{}o\opRightPren{}}, 
where \smath{o} is an object of type
\spadtype{OutputForm} (normally unexposed),
creates an output form \smath{o} with a prefix quote.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quotedOperators}}\opLeftPren{}
{\it rewriteRule}\opRightPren{}%
}%
}%
{1}{(\$)->List(Symbol)}{RewriteRule}
{\smath{\mbox{\bf quotedOperators}\opLeftPren{}r\opRightPren{}}, 
where \smath{r} is a rewrite rule,
returns the list of operators on the right-hand side of \smath{r}
that are considered quoted, that is, they are not evaluated during
any rewrite, but applied formally to their arguments.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{quotient}}\opLeftPren{}{\it ideal}, 
\allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(\$, DPoly)->\$}{PolynomialIdeals}
{\smath{\mbox{\bf quotient}\opLeftPren{}I, 
\allowbreak{} f\opRightPren{}} computes the quotient of the ideal
\smath{I} by the principal ideal generated by the polynomial
\smath{f}, \smath{(I:(f))}.
\newitem\smath{\mbox{\bf quotient}\opLeftPren{}I, 
\allowbreak{} J\opRightPren{}} computes the quotient of the ideals
\smath{I} and \smath{J}, \smath{(I:J)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radical}}\opLeftPren{}{\it ideal}\opRightPren{}%
}%
}%
{1}{(PolynomialIdeals(Fraction(Integer), 
DirectProduct(nv, NonNegativeInteger), vl, 
DistributedMultivariatePolynomial(vl, Fraction(Integer))))->
PolynomialIdeals(Fraction(Integer), DirectProduct(nv, NonNegativeInteger), 
vl, DistributedMultivariatePolynomial(vl, Fraction(Integer)))}
{IdealDecompositionPackage}
{\smath{\mbox{\bf radical}\opLeftPren{}I\opRightPren{}} 
returns the radical of the ideal \smath{I}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radicalEigenvalues}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Expression(Fraction(Integer)))}{RadicalEigenPackage}
{\smath{\mbox{\bf radicalEigenvalues}\opLeftPren{}m\opRightPren{}} 
computes the eigenvalues of the
matrix \smath{m}; when possible, the eigenvalues are expressed in
terms of radicals.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radicalEigenvectors}}\opLeftPren{}
{\it matrix}\opRightPren{}%
}%
}%
{1}{(Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Record(radval:Expression(Fraction(Integer)), radmult:Integer, 
radvect:List(Matrix(Expression(Fraction(Integer))))))}{RadicalEigenPackage}
{\smath{\mbox{\bf radicalEigenvectors}\opLeftPren{}m\opRightPren{}} 
computes the eigenvalues and the
corresponding eigenvectors of the matrix \smath{m}; when possible,
values are expressed in terms of radicals.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radicalEigenvector}}\opLeftPren{}
{\it eigenvalue}, \allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{2}{(Expression(Fraction(Integer)), 
Matrix(Fraction(Polynomial(Fraction(Integer)))))->
List(Matrix(Expression(Fraction(Integer))))}{RadicalEigenPackage}
{\smath{\mbox{\bf radicalEigenvector}\opLeftPren{}c, 
\allowbreak{} m\opRightPren{}} computes the
eigenvector(\smath{s}) of the matrix \smath{m} corresponding to
the eigenvalue \smath{c}; when possible, values are expressed in
terms of radicals.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radicalOfLeftTraceForm}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(A)}{AlgebraPackage}
{\smath{\mbox{\bf radicalOfLeftTraceForm}\opLeftPren{}\opRightPren{}\$F} 
returns the basis for the
null space
of \smath{\mbox{\bf leftTraceMatrix}\opLeftPren{}\opRightPren{}\$F},
where \smath{F} is a domain of category 
\spadtype{FramedNonAssociativeAlgebra}.
If the algebra is associative, alternative
or a Jordan algebra,
then this space equals the radical (maximal nil ideal) of the algebra.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radicalRoots}}\opLeftPren{}
{\it fractions}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(R)), Symbol)->
List(Expression(R))}{RadicalSolvePackage}
{\smath{\mbox{\bf radicalRoots}\opLeftPren{}rf, 
\allowbreak{} v\opRightPren{}} finds the roots expressed in terms of
radicals of the rational function \smath{rf} with respect to the
symbol \smath{v}.
\newitem
\smath{\mbox{\bf radicalRoots}\opLeftPren{}lrf, 
\allowbreak{} lv\opRightPren{}} finds the roots expressed in terms of
radicals of the list of rational functions \smath{lrf} with
respect to the list of symbols \smath{lv}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radicalSolve}}\opLeftPren{}
{\it eq}, \allowbreak{}{\it  x}\opRightPren{}%
}%
}%
{1}{(Equation(Expression(R)))->List(Equation(Expression(R)))}
{TransSolvePackage}
{See \smath{\mbox{\bf solve}\opLeftPren{}u, \allowbreak{} v\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{radix}}\opLeftPren{}{\it rationalNumber}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(Fraction(Integer), Integer)->Any}{RadixUtilities}
{\smath{\mbox{\bf radix}\opLeftPren{}rn, \allowbreak{} b\opRightPren{}} 
converts rational number \smath{rn} to a
radix expansion in base \smath{b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ramified?}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
 \opand \mbox{\axiomFun{ramifiedAtInfinity?}}\opLeftPren{}\opRightPren{}%
}%
}%
{1}{(UP)->Boolean}{FunctionFieldCategory}
{\opkey{Domain \smath{F} is a domain of functions on a fixed
curve.}
\newitem\smath{\mbox{\bf ramified?}\opLeftPren{}p\opRightPren{}\$F} 
tests whether \smath{p(x) = 0} is ramified.
\newitem\smath{\mbox{\bf ramifiedAtInfinity?}\opLeftPren{}\opRightPren{}} 
tests if infinity is
ramified.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{random}}\opLeftPren{}{\it \opt{u, v}}\opRightPren{}%
}%
}%
{0}{()->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf random}\opLeftPren{}\opRightPren{}\$R} creates a 
random element from
domain \smath{D}.
\newitem
\smath{\mbox{\bf random}\opLeftPren{}gp\optinner{, i}\opRightPren{}} 
returns a random product
of maximal \smath{i} generators of the permutation group {\it gp}.
The value of \smath{i} is 20 by default.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{range}}\opLeftPren{}
{\it listOfSegments}\opRightPren{}%
}%
}%
{1}{(List(Segment(Float)))->\$}{DrawOption}
{\smath{\mbox{\bf range}\opLeftPren{}ls\opRightPren{}},
where \smath{ls} is a list of segments of the form
\smath{[a_1..b_1, \ldots, a_n..b_n]}, provides a user-specified range
for clipping
for the \spadfun{draw} command.
This command may also be
expressed locally to the
\spadfun{draw} command as the option \smath{range == ls}.
The values \smath{a_i} and \smath{b_i} are either given
as floats or rational numbers.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ranges}}\opLeftPren{}
{\it listOfSegments}\opRightPren{}%
}%
}%
{1}{(List(Segment(Float)))->\$}{DrawOption}
{\smath{\mbox{\bf ranges}\opLeftPren{}l\opRightPren{}} provides a 
list of user-specified ranges
for the \spadfun{draw} command.
This command may also be expressed as an option to the \spadfun{draw}
command in the form \smath{{\bf ranges} == l}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rank}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(M)->NonNegativeInteger}{MatrixLinearAlgebraFunctions}
{\smath{\mbox{\bf rank}\opLeftPren{}m\opRightPren{}} returns the 
rank of the matrix \smath{m}. Also:
\newitem
\smath{\mbox{\bf rank}\opLeftPren{}A, \allowbreak{} B\opRightPren{}} 
computes the rank of the complete matrix
\smath{(A|B)} of the linear system \smath{AX = B}.
\newitem
\smath{\mbox{\bf rank}\opLeftPren{}t\opRightPren{}},
where \smath{t} is a
Cartesion tensor,
returns the tensorial rank of \smath{t} (that is, the number of
indices).
\seeAlso{ \spadtype{FiniteRankAlgebra} and
\spadtype{FiniteRankNonAssociativeAlgebra}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rarrow}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf rarrow}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of type
\spadtype{OutputForm} (normally unexposed),
creates a form for the mapping \smath{o_1  \rightarrow o_2}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ratDenom}}\opLeftPren{}
{\it expression\opt{, option}}\opRightPren{}%
}%
}%
{2}{(F, F)->F}{AlgebraicManipulations}
{\smath{\mbox{\bf ratDenom}\opLeftPren{}f\optinner{, u}\opRightPren{}}
rationalizes the denominators appearing in \smath{f}.
If no second argument is given, then all algebraic quantities
are moved into the numerators.
If the second argument is given as an algebraic kernel
\smath{a}, then \smath{a} is removed from the denominators.
Similarly, if \smath{u} is a list of algebraic kernels
\smath{[a_1, \ldots, a_n]}, the operation removes the
\smath{a_i}'s from the denominators in \smath{f}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rational?}}\opLeftPren{}{\it element}\opRightPren{}%
\optand \mbox{\axiomFun{rationalIfCan}}\opLeftPren{}
{\it element}\opRightPren{}%
 \opand \mbox{\axiomFun{rational}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{ComplexCategory}
{\smath{\mbox{\bf rational?}\opLeftPren{}x\opRightPren{}} 
tests if \smath{x} is a rational number,
that is, that it can be converted to type \spadtype{Fraction(Integer)}.
Specifically, if \smath{x} is complex, a quaternion, or an
octonion, it tests that all imaginary parts are 0.
\newitem
\smath{\mbox{\bf rationalIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{x} as a rational number
if possible, and \mbox{\tt "failed"} if it is not.
\newitem
\smath{\mbox{\bf rational}\opLeftPren{}x\opRightPren{}} 
returns \smath{x} as a rational number if
possible, and calls \spadfun{error} if it is not.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rationalApproximation}}\opLeftPren{}
{\it float}, \allowbreak{}
{\it  nonNegativeInteger}\allowbreak $\,[$ , \allowbreak{}
{\it  positiveInteger}$]$\opRightPren{}%
}%
}%
{3}{(\$, NonNegativeInteger, NonNegativeInteger)->Fraction(Integer)}{Float}
{\smath{\mbox{\bf rationalApproximation}\opLeftPren{}f, 
\allowbreak{} n\optinner{, b}\opRightPren{}} computes a
rational approximation \smath{r} to \smath{f} with relative error
\smath{< b^{-n}}, that is \smath{|(r-f)/f| < b^{-n}}, for some
positive integer base \smath{b}.
By default, \smath{b = 10}.
The first argument \smath{f} is either a float or small float.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rationalFunction}}\opLeftPren{}
{\it series}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, Integer, Integer)->Fraction(Polynomial(Coef))}
{UnivariateLaurentSeriesCategory}
{\smath{\mbox{\bf rationalFunction}\opLeftPren{}f, 
\allowbreak{} m, \allowbreak{} n\opRightPren{}} returns a rational function
consisting of the sum of all terms of \smath{f} of
degree \smath{d} with \smath{m \leq d \leq n}.
By default, \smath{n} is the maximum degree of \smath{f}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rationalPoint?}}\opLeftPren{}
{\it value}, \allowbreak{}{\it  value}\opRightPren{}%
}%
}%
{2}{(F, F)->Boolean}{FunctionFieldCategory}
{\smath{\mbox{\bf rationalPoint?}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}\$F} tests if
\smath{(x=a, y=b)} is on the curve
defining function field \smath{F}.
See \spadtype{FunctionFieldCategory}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rationalPoints}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(List(F))}{FunctionFieldCategory}
{\smath{\mbox{\bf rationalPoints}\opLeftPren{})\$} returns the list of all the
affine rational points on the curve
defining function field \smath{F}.
See \spadtype{FunctionFieldCategory}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rationalPower}}\opLeftPren{}
{\it puiseuxSeries}\opRightPren{}%
}%
}%
{1}{(\$)->Fraction(Integer)}{UnivariatePuiseuxSeriesConstructorCategory}
{\smath{\mbox{\bf rationalPower}\opLeftPren{}f(x)\opRightPren{}} 
returns \smath{r} where the Puiseux series \smath{f(x) = g(x^r)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ratPoly}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->SparseUnivariatePolynomial(F)}{AlgebraicManipulations}
{\smath{\mbox{\bf ratPoly}\opLeftPren{}f\opRightPren{}} 
returns a polynomial \smath{p} such that \smath{p} has no algebraic 
coefficients, and \smath{p(f) = 0}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rdexquo}}\opLeftPren{}{\it lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Union(\$, "failed")}{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf rdexquo}\opLeftPren{}a, \allowbreak{} b\opRightPren{}},
where \smath{a} and \smath{b} are linear ordinary differential operators,
returns \smath{q} such that
\smath{a = bq}, or \mbox{\tt "failed"} if no such \smath{q} exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightDivide}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
\optand \mbox{\axiomFun{rightQuotient}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
\opand \mbox{\axiomFun{rightRemainder}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(quotient:\$, remainder:\$)}
{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf rightDivide}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns the pair \smath{q, r} such that
\smath{a = qb + r} and the degree of
\smath{r} is less than the degree of \smath{b}.
The pair is returned as a record with
fields \smath{quotient} and \smath{remainder}.
This process is called ``right division''. Also:
\smath{\mbox{\bf rightQuotient}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns only \smath{q}.
\smath{\mbox{\bf rightRemainder}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} returns only \smath{r}.

}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{read!}}\opLeftPren{}{\it file}\opRightPren{}%
\opand \mbox{\axiomFun{readIfCan!}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->S}{FileCategory}
{\smath{\mbox{\bf read!}\opLeftPren{}f\opRightPren{}} extracts a 
value from file \smath{f}. The state of \smath{f} is modified so a subsequent 
call to \spadfun{read!} will return the next element.
\newitem
\smath{\mbox{\bf readIfCan!}\opLeftPren{}f\opRightPren{}} returns 
a value from the file \smath{f}
or \mbox{\tt "failed"} if this is not possible (that is,
either \smath{f} is not open for reading, or \smath{f} is at the
end of the file).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{readable?}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{FileNameCategory}
{\smath{\mbox{\bf readable?}\opLeftPren{}f\opRightPren{}} tests 
if the named file exists and can be opened for reading.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{readLine!}}\opLeftPren{}{\it file}\opRightPren{}%
 \opand \mbox{\axiomFun{readLineIfCan!}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->String}{TextFile}
{\smath{\mbox{\bf readLineIfCan!}\opLeftPren{}f\opRightPren{}} 
returns a string of the contents
of a line from file \smath{f}, or \mbox{\tt "failed"} if this is not
possible (if
\smath{f} is not readable or is positioned at the end of file).
\newitem
\smath{\mbox{\bf readLine!}\opLeftPren{}f\opRightPren{}} 
returns a string of the contents of a line from the file \smath{f}, and calls 
\spadfun{error} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{real}}\opLeftPren{}{\it x}\opRightPren{}%
 \opand \mbox{\axiomFun{real?}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->R}{ComplexCategory}
{\smath{\mbox{\bf real}\opLeftPren{}x\opRightPren{}} returns 
real part of \smath{x}.
Argument \smath{x} can be an expression or a complex value,
quaternion, or octonion.
\newitem
\smath{\mbox{\bf real?}\opLeftPren{}f\opRightPren{}} tests 
if expression \smath{f = real(f)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{realEigenvectors}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  float}\opRightPren{}%
}%
}%
{2}{(Matrix(Fraction(Integer)), Par)->
List(Record(outval:Par, outmult:Integer, outvect:List(Matrix(Par))))}
{NumericRealEigenPackage}
{\smath{\mbox{\bf realEigenvectors}\opLeftPren{}m, 
\allowbreak{} eps\opRightPren{}} returns a list of records, each
containing a real eigenvalue, its algebraic multiplicity, and
a list of associated eigenvectors.
All these results are computed to precision \smath{eps} as floats
or rational numbers depending on the type of \smath{eps}.
Argument \smath{m} is a matrix of rational functions.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{realElementary}}\opLeftPren{}
{\it expression\opt{, symbol}}\opRightPren{}%
}%
}%
{2}{(F, Symbol)->F}{ElementaryFunctionStructurePackage}
{\smath{\mbox{\bf realElementary}\opLeftPren{}f, 
\allowbreak{} sy\opRightPren{}} rewrites the kernels of \smath{f}
involving \smath{sy} in terms of the 4 fundamental 
real transcendental elementary functions: \smath{log, exp, tan, atan}. 
If \smath{sy}
is omitted, all kernels of \smath{f} are rewritten.

}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{realRoots}}\opLeftPren{}
{\it rationalfunctions}, \allowbreak{}{\it  v}\allowbreak $\,[$ , \allowbreak{}
{\it  w}$]$\opRightPren{}%
}%
}%
{3}{(List(Fraction(Polynomial(Fraction(Integer)))), List(Symbol), Par)->
List(List(Par))}{FloatingRealPackage}
{\smath{\mbox{\bf realRoots}\opLeftPren{}rf, 
\allowbreak{} eps\opRightPren{}} finds the real zeros of a 
univariate rational function
\smath{rf} with precision given by eps.
\newitem
\smath{\mbox{\bf realRoots}\opLeftPren{}lp, \allowbreak{} lv, 
\allowbreak{} eps\opRightPren{}} computes the list of the real solutions 
of the list \smath{lp} of rational functions with rational 
coefficients with respect to the 
variables in \smath{lv}, with precision \smath{eps}. 
Each solution is expressed 
as a list of numbers in order corresponding to the variables in \smath{lv}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{realZeros}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  rationalNumber}\allowbreak $\,[$ , 
\allowbreak{}{\it  option}$]$\opRightPren{}%
}%
}%
{2}{(Pol, Fraction(Integer))->List(Record(left:Fraction(Integer), 
right:Fraction(Integer)))}{RealZeroPackageQ}
{\smath{\mbox{\bf realZeros}\opLeftPren{}pol\opRightPren{}} 
returns a list of isolating intervals for all the real zeros of the univariate 
polynomial \smath{pol}.
\newitem
\smath{\mbox{\bf realZeros}\opLeftPren{}pol\optinner{, eps}\opRightPren{}} 
returns a list of intervals
of length less than the rational number \smath{eps}
for all the real roots of the polynomial \smath{pol}.
The default value of \smath{eps} is ???.
\newitem
\smath{\mbox{\bf realZeros}\opLeftPren{}pol, 
\allowbreak{} int\optinner{, eps}\opRightPren{}} returns a list of intervals of
length less than the rational number \smath{eps} for all the
real roots of the polynomial \smath{pol}
which lie in the interval expressed by the record \smath{int}.
The default value of \smath{eps} is ???.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{recip}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Union(\$, "failed")}{Monoid}
{\smath{\mbox{\bf recip}\opLeftPren{}x\opRightPren{}} 
returns the multiplicative inverse for \smath{x},
or \mbox{\tt "failed"} if no inverse can be found.
\seeAlso{\spadtype{FiniteRankNonAssociativeAlgebra} and
\spadtype{MonadWithUnit}}
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{recur}}\opLeftPren{}{\it function}\opRightPren{}%
}%
}%
{ ((NNI, A)->A) -> ((NNI, A)->A)}{}{}
{\smath{\mbox{\bf recur}\opLeftPren{}f\opRightPren{}},
where \smath{f} is a function of type \spadsig{(NonNegativeInteger, R)}{R}
for some domain \smath{R},
returns  the function \smath{g} such that
\smath{g(n, x)= f(n, f(n-1, \ldots f(1, x)\ldots))}.
For related functions, see \spadtype{MappingPackage}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{red}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Color}
{\smath{\mbox{\bf red}\opLeftPren{}\opRightPren{}} returns 
the position of the red hue from total hues.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reduce}}\opLeftPren{}{\it op}, 
\allowbreak{}{\it  aggregate}\allowbreak $\,[$ , \allowbreak{}{\it  identity}, 
\allowbreak{}{\it  element}$]$\opRightPren{}%
}%
}%
{2}{((S, S)->S, \$)->S}{Collection}
{\smath{\mbox{\bf reduce}\opLeftPren{}f, 
\allowbreak{} u\optinner{, ident, a}\opRightPren{}} reduces the binary
operation \smath{f} across \smath{u}.
For example, if \smath{u} is \smath{[x_1, x_2, \ldots, x_n]} then
\smath{\mbox{\bf reduce}\opLeftPren{}f, \allowbreak{} u\opRightPren{}} 
returns \smath{f(\ldots f(x_1, x_2), \ldots, x_n)}.
\medbreak
An optional identity element of \smath{f}
provided as a third argument affects the result
if \smath{u} has less than two elements.
If \smath{u} is empty, the third argument is
returned if given, and a call to \spadfun{error} occurs
otherwise.
If \smath{u} has one element and the third argument is
given, the value returned is \smath{f(ident, x_1)}.
Otherwise \smath{x_1} is returned.
Thus both \smath{\mbox{\bf reduce}\opLeftPren{}+, 
\allowbreak{} u\opRightPren{}} and \smath{\mbox{\bf reduce}\opLeftPren{}+, 
\allowbreak{} u, \allowbreak{} 0\opRightPren{}}
return \smath{\sum\nolimits_{i=1}^n{x_i}}.
Similarly, \smath{\mbox{\bf reduce}\opLeftPren{}*, 
\allowbreak{} u\opRightPren{}} and 
\smath{\mbox{\bf reduce}\opLeftPren{}*, \allowbreak{} u, 
\allowbreak{} 1\opRightPren{}}
return \smath{\prod\nolimits_{i=1}^n{x_i}}.
\medbreak
An optional fourth argument \smath{z} acts as an
``absorbing element''.
\smath{\mbox{\bf reduce}\opLeftPren{}f, \allowbreak{} u, \allowbreak{} x, 
\allowbreak{} z\opRightPren{}} reduces the binary operation \smath{f} across 
\smath{u},
stopping when an ``absorbing element'' \smath{z} is encountered.
For example \smath{\mbox{\bf reduce}\opLeftPren{}or, \allowbreak{} u, 
\allowbreak{} false, \allowbreak{} true\opRightPren{}} will
stop iterating across \smath{u} returning
\smath{true} as soon as an \smath{x_i = true} is found.
Note: if \smath{u} has one element \smath{x},
\smath{\mbox{\bf reduce}\opLeftPren{}f, \allowbreak{} u\opRightPren{}} 
returns \smath{x}, or calls \spadfun{error} if \smath{u} is empty.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reduceBasisAtInfinity}}\opLeftPren{}
{\it basis}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->Vector(\$)}{FunctionFieldCategory}
{\smath{\mbox{\bf reduceBasisAtInfinity}\opLeftPren{}b_1, 
\allowbreak{} \ldots, b_n\opRightPren{}},
where the \smath{b_i} are functions on a fixed curve,
returns \smath{(x^i \, b_j)} for all
\smath{i}, \smath{j} such that \smath{x^i \, b_j} is locally
integral at infinity.
\seeType{FunctionFieldCategory}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reducedContinuedFraction}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  stream}\opRightPren{}%
}%
}%
{2}{(R, Stream(R))->\$}{ContinuedFraction}
{\smath{\mbox{\bf reducedContinuedFraction}\opLeftPren{}b_0, 
\allowbreak{} b\opRightPren{}} returns a
continued fraction constructed as follows.
If \smath{b = [b_1, b_2, \ldots]} then the result
is the continued fraction \smath{b_0 + 1/(b_1 + 1/(b_2 + \cdots))}.
That is, the result is the same as
\smath{\mbox{\bf continuedFraction}\opLeftPren{}b_0, \allowbreak{} 
[1, \allowbreak{} 1, \allowbreak{} 1, \allowbreak{} \ldots], 
[b_1, b_2, b_3, \ldots]\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reducedForm}}\opLeftPren{}
{\it continuedFraction}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{ContinuedFraction}
{\smath{\mbox{\bf reducedForm}\opLeftPren{}x\opRightPren{}} 
puts the continued fraction \smath{x}
in reduced form, that is, the function returns an
equivalent continued fraction of the
form \smath{\mbox{\bf continuedFraction}\opLeftPren{}b_0, 
\allowbreak{} [1, \allowbreak{} 1, \allowbreak{} 1, \allowbreak{} \ldots], 
[b_1, b_2, b_3, \ldots]\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reducedSystem}}\opLeftPren{}
{\it matrix\opt{, vector}}\opRightPren{}%
}%
}%
{1}{(Matrix(\$))->Matrix(R)}{LinearlyExplicitRingOver}
{\smath{\mbox{\bf reducedSystem}\opLeftPren{}A, 
\allowbreak{} v\opRightPren{}} returns a matrix \smath{B} 
such that \smath{A x = v} 
and \smath{B x = v} have the same solutions.
By default, \smath{v = 0}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reductum}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{AbelianMonoidRing}
{\smath{\mbox{\bf reductum}\opLeftPren{}p\opRightPren{}} 
returns polynomial \smath{p} minus its leading
monomial, or zero if handed the zero element.
\seeAlso{\spadtype{IndexedDirectProdcutCategory} and 
\spadtype{MonogenicLinearOperator}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{refine}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  interval}, \allowbreak{}{\it  precision}\opRightPren{}%
}%
}%
{3}{(Pol, Record(left:Fraction(Integer), right:Fraction(Integer)), 
Fraction(Integer))->Record(left:Fraction(Integer), right:Fraction(Integer))}
{RealZeroPackageQ}
{\smath{\mbox{\bf refine}\opLeftPren{}pol, \allowbreak{} int, 
\allowbreak{} tolerance\opRightPren{}} refines the interval 
\smath{int} containing 
exactly one root of the univariate polynomial \smath{pol} to size less than
the indicated \smath{tolerance}.
Argument \smath{int} is an interval denoted by a record with
selectors \smath{left} and \smath{right}, each with rational number values.
The tolerance is either a rational number or another interval.
In the latter case, \mbox{\tt "failed"} is returned if no such
isolating interval exists.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{regularRepresentation}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  basis}\opRightPren{}%
}%
}%
{2}{(\$, Vector(\$))->Matrix(R)}{FiniteRankAlgebra}
{\smath{\mbox{\bf regularRepresentation}\opLeftPren{}a, 
\allowbreak{} basis\opRightPren{}} returns the matrix of the linear map 
defined by left multiplication by \smath{a} with respect 
to basis \smath{basis}.
Element \smath{a} is a complex element or
an element of a domain \smath{R} of category
\spadtype{FramedAlgebra}.
The second argument may be omitted when a fixed basis is defined for \smath{R}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reindex}}\opLeftPren{}
{\it cartesianTensor}, \allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{2}{(\$, List(Integer))->\$}{CartesianTensor}
{\smath{\mbox{\bf reindex}\opLeftPren{}t, \allowbreak{} 
[i_1, \allowbreak{} \ldots, i_{\rm dim}]\opRightPren{}} 
permutes the indices of
cartesian tensor \smath{t}.
For example, if \smath{r = {\bf reindex}(t, [4, 1, 2, 3])} for a rank 4
tensor \smath{t}, then \smath{r} is the rank 4 tensor
given by \smath{r(i, j, k, l) = t(l, i, j, k)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{relationsIdeal}}\opLeftPren{}
{\it listOfPolynomials}\opRightPren{}%
}%
}%
{1}{(List(DPoly))->SuchThat(List(Polynomial(F)), 
List(Equation(Polynomial(F))))}{PolynomialIdeals}
{\smath{\mbox{\bf relationsIdeal}\opLeftPren{}polyList\opRightPren{}} 
returns the ideal of relations among the polynomials in \smath{polyList}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{relerror}}\opLeftPren{}{\it float}, \allowbreak{}
{\it  float}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Integer}{Float}
{\smath{\mbox{\bf relerror}\opLeftPren{}x, \allowbreak{} y\opRightPren{}},
where \smath{x} and \smath{y} are floats,
computes the absolute value of \smath{x - y} divided by \smath{y},
when \smath{y \not= 0}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rem}}\opLeftPren{}{\it element}, \allowbreak{}
{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{NonNegativeInteger}
{\smath{a \rem b} returns the remainder of \smath{a} and \smath{b}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{remove}}\opLeftPren{}{\it predicate}, 
\allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->\$}{ExtensibleLinearAggregate}
{\opkey{Argument \smath{u} is any extensible aggregate such as a list.}
\newitem
\smath{\mbox{\bf remove}\opLeftPren{}pred, \allowbreak{} u\opRightPren{}} 
returns a copy of \smath{u} removing all elements \smath{x} such that 
\smath{p(x)} is \smath{true}.
Argument \smath{u} may be any homogeneous aggregate including
infinite streams.
Note: for lists and streams, \code{remove(p, u) == [x for x in u | not p(x)]}.
\newitem
\smath{\mbox{\bf remove!}\opLeftPren{}pred, \allowbreak{} u\opRightPren{}} 
destructively removes all elements \smath{x} of \smath{u} such that 
\smath{\mbox{\bf pred}\opLeftPren{}x\opRightPren{}} is \smath{true}.
The value of \smath{u} after all such elements are removed is returned.
\newitem
\smath{\mbox{\bf remove!}\opLeftPren{}x, \allowbreak{} u\opRightPren{}} 
destructively removes all values \smath{x} from \smath{u}.
\newitem
\smath{\mbox{\bf remove!}\opLeftPren{}k, \allowbreak{} t\opRightPren{}},
where \smath{t} is a keyed dictionary,
searches the table \smath{t} for the key \smath{k},
removing and returning the entry if there.
If \smath{t} has no such key, it returns \mbox{\tt "failed"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{removeCoshSq}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf removeCoshSq}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\cosh(u)^2}
appearing in \smath{f} into \smath{1 - \sinh(x)^2}, and also 
reduces higher powers of \smath{\mbox{\bf cosh}\opLeftPren{}u\opRightPren{}} 
with that formula.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{removeDuplicates}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
 \opand \mbox{\axiomFun{removeDuplicates!}}\opLeftPren{}
{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{Collection}
{\smath{\mbox{\bf removeDuplicates}\opLeftPren{}u\opRightPren{}} 
returns a copy of \smath{u} with all duplicates removed.
\newitem
\smath{\mbox{\bf removeDuplicates!}\opLeftPren{}u\opRightPren{}} 
destructively removes duplicates from \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{removeSinhSq}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf removeSinhSq}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\sinh(u)^2}
appearing in \smath{f} into \smath{1 - \cosh(x)^2}, and also 
reduces higher powers of \smath{\mbox{\bf sinh}\opLeftPren{}u\opRightPren{}} 
with that formula.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{removeSinSq}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf removeSinSq}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\sin(u)^2}
appearing in \smath{f} into \smath{1 - \cos(x)^2}, and also 
reduces higher powers of \smath{\mbox{\bf sin}\opLeftPren{}u\opRightPren{}} 
with that formula.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{removeZeroes}}\opLeftPren{}
{\it \optinit{integer, }laurentSeries}\opRightPren{}%
}%
}%
{2}{(Integer, \$)->\$}{UnivariateLaurentSeriesConstructorCategory}
{\smath{\mbox{\bf removeZeroes}\opLeftPren{}\optfirst{n, }f(x)\opRightPren{}}
removes up to \smath{n} leading zeroes from the Laurent series \smath{f(x)}.
If no integer \smath{n} is given, all leading zeroes are removed.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reopen!}}\opLeftPren{}
{\it file}, \allowbreak{}{\it  string}\opRightPren{}%
}%
}%
{2}{(\$, String)->\$}{FileCategory}
{\smath{\mbox{\bf reopen!}\opLeftPren{}f, \allowbreak{} mode\opRightPren{}} 
returns a file \smath{f}
reopened for operation in the indicated mode: \mbox{\tt "input"} or 
\mbox{\tt "output"}.
For example,
\smath{\mbox{\bf reopen!}\opLeftPren{}f, \allowbreak{} 
\mbox{\tt "input"}\opRightPren{}} will reopen the file \smath{f} for input.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{repeating}}\opLeftPren{}
{\it listOfElements\opt{, stream}}\opRightPren{}%
 \opand \mbox{\axiomFun{repeating?}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(List(S))->\$}{Stream}
{\smath{\mbox{\bf repeating}\opLeftPren{}l\opRightPren{}} 
is a repeating stream whose period is the list \smath{l}.
\newitem
\smath{\mbox{\bf repeating?}\opLeftPren{}l, 
\allowbreak{} s\opRightPren{}} tests if a stream \smath{s} is periodic
with period \smath{l}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{replace}}\opLeftPren{}{\it string}, 
\allowbreak{}{\it  segment}, \allowbreak{}{\it  string}\opRightPren{}%
}%
}%
{3}{(\$, UniversalSegment(Integer), \$)->\$}{StringAggregate}
{\smath{\mbox{\bf replace}\opLeftPren{}s, \allowbreak{} i..j, 
\allowbreak{} t\opRightPren{}} replaces the substring \smath{s(i..j)}
of \smath{s} by string \smath{t}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{represents}}\opLeftPren{}
{\it listOfElements\opt{, listOfBasisElements}}\opRightPren{}%
}%
}%
{2}{(Vector(R), Vector(\$))->\$}{FiniteRankAlgebra}
{\smath{\mbox{\bf represents}\opLeftPren{}[a^1, \allowbreak{} .., 
\allowbreak{} a^n]\optinner{, [v^1, .., v^n]}\opRightPren{}}
returns \smath{a^1 v^1 + \cdots + a^n v^n}.
Arguments \smath{v_i} are elements of a domain of
category \spadtype{FiniteRankAlgebra} or
\spadtype{FiniteRankNonAssociativeAlgebra} built over a ring \smath{R}.
The \smath{a_i} are elements of \smath{R}.
In a framed algebra or finite algebra extension field domain
with a fixed basis, \smath{[v_1, \ldots, v_n]} defaults
to the elements of the fixed basis.
See \spadtype{FramedAlgebra}, \spadtype{FramedNonAssociateAlgebra},
and \spadtype{FiniteAlgebraicExtensionField}.
\newitem
\seeAlso{ \spadtype{FunctionFieldCategory}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{resetNew}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Void}{Symbol}
{\smath{\mbox{\bf resetNew}\opLeftPren{}\opRightPren{}} resets the 
internal counter that \smath{\mbox{\bf new}\opLeftPren{}\opRightPren{}} uses.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{resetVariableOrder}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Void}{UserDefinedVariableOrdering}
{\smath{\mbox{\bf resetVariableOrder}\opLeftPren{}\opRightPren{}} 
cancels any previous use of \spadfun{setVariableOrder}
and returns to the default system ordering.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rest}}\opLeftPren{}
{\it aggregate\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf rest}\opLeftPren{}u\opRightPren{}} returns an aggregate 
consisting of all but the first element of \smath{u} (equivalently, the 
next node of \smath{u}).
\newitem
\smath{\mbox{\bf rest}\opLeftPren{}u, \allowbreak{} n\opRightPren{}} 
returns the \eth{\smath{n}} node of \smath{u}.
Note: \smath{\mbox{\bf rest}\opLeftPren{}u, 0) = u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{resultant}}\opLeftPren{}
{\it polynomial}, \allowbreak{}
{\it  polynoial}\allowbreak $\,[$ , \allowbreak{}
{\it  variable}$]$\opRightPren{}%
}%
}%
{3}{(\$, \$, VarSet)->\$}{PolynomialCategory}
{\smath{\mbox{\bf resultant}\opLeftPren{}p, \allowbreak{} q, 
\allowbreak{} v\opRightPren{}} returns the resultant of the polynomials 
\smath{p} and \smath{q} with respect to the variable \smath{v}.
If \smath{p} and \smath{q} are univariate polynomials, the
variable \smath{v} defaults to the unique variable.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{retract}}\opLeftPren{}{\it element}\opRightPren{}%
 \opand \mbox{\axiomFun{retractIfCan}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Union(S, "failed")}{RetractableTo}
{\smath{\mbox{\bf retractIfCan}\opLeftPren{}a\opRightPren{}}\smath{@S} 
returns \smath{a} as an object
of type \smath{S}, or \mbox{\tt "failed"} if this is not possible.
\newitem
\smath{\mbox{\bf retract}\opLeftPren{}a\opRightPren{}}\smath{@S} 
transforms \smath{a} into an element of \smath{S},
or calls \spadfun{error} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{retractable?}}\opLeftPren{}
{\it typeAnyObject}\opRightPren{}%
}%
}%
{1}{(Any)->Boolean}{AnyFunctions1}
{\smath{\mbox{\bf retractable?}\opLeftPren{}a\opRightPren{}\$S} 
tests if object \smath{a}
of type \spadtype{Any} can be converted into an object of type \smath{S}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{reverse}}\opLeftPren{}
{\it linearAggregate}\opRightPren{}%
 \opand \mbox{\axiomFun{reverse!}}\opLeftPren{}
{\it linearAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{FiniteLinearAggregate}
{\smath{\mbox{\bf reverse}\opLeftPren{}a\opRightPren{}} returns a 
copy of linear aggregate \smath{a} with elements in reverse order.
\newitem
\smath{\mbox{\bf reverse!}\opLeftPren{}a\opRightPren{}} destructively 
puts the elements of
linear aggregate \smath{a} in reverse order.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightGcd}}\opLeftPren{}{\it lodOperator}, 
\allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf rightGcd}\opLeftPren{}a, \allowbreak{} b\opRightPren{}},
where \smath{a} and \smath{b} are linear ordinary differential operators,
computes the value \smath{g} of highest degree such that
\smath{a = g*aa} and \smath{b = g*bb} for some values \smath{aa}
and \smath{bb}. The value \smath{g} is computed using right-division.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rhs}}\opLeftPren{}
{\it rewriteRuleOrEquation}\opRightPren{}%
}%
}%
{1}{(\$)->F}{RewriteRule}
{\smath{\mbox{\bf rhs}\opLeftPren{}u\opRightPren{}} 
returns the right-hand side of the rewrite rule
or equation \smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{right}}\opLeftPren{}
{\it binaryRecursiveAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{BinaryRecursiveAggregate}
{\smath{\mbox{\bf right}\opLeftPren{}a\opRightPren{}} returns the right child.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightAlternative?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{FiniteRankNonAssociativeAlgebra}
{See \spadfun{leftAlternative?}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightCharacteristicPolynomial}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->SparseUnivariatePolynomial(R)}{FiniteRankNonAssociativeAlgebra}
{See \spadfun{leftCharacteristicPolynomial}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightDiscriminant}}\opLeftPren{}
{\it basis}\opRightPren{}%
}%
}%
{0}{()->R}{FramedNonAssociativeAlgebra}
{See \spadfun{leftDiscriminant}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightMinimalPolynomial}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->SparseUnivariatePolynomial(R)}{FiniteRankNonAssociativeAlgebra}
{See \spadfun{leftMinimalPolynomial}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightNorm}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->R}{FiniteRankNonAssociativeAlgebra}
{See \spadfun{leftNorm}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightPower}}\opLeftPren{}
{\it monad}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->\$}{MonadWithUnit}
{See \spadfun{rightPower}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightRankPolynomial}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->SparseUnivariatePolynomial(Polynomial(R))}
{FramedNonAssociativeAlgebra}
{See \spadfun{leftRankPolynomial}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightRank}}\opLeftPren{}{\it basis}\opRightPren{}%
}%
}%
{1}{(A)->NonNegativeInteger}{AlgebraPackage}
{See \spadfun{leftRank}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightRecip}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Union(\$, "failed")}{MonadWithUnit}
{See \spadfun{leftRecip}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightRegularRepresentation}}\opLeftPren{}
{\it element\opt{, basis}}\opRightPren{}%
}%
}%
{1}{(\$)->Matrix(R)}{FramedNonAssociativeAlgebra}
{See \spadfun{leftRegularRepresentation}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightTraceMatrix}}\opLeftPren{}
{\it \opt{basis}}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->Matrix(R)}{FiniteRankNonAssociativeAlgebra}
{See \spadfun{leftTraceMatrix}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightTrim}}\opLeftPren{}{\it string}, 
\allowbreak{}{\it  various}\opRightPren{}%
}%
}%
{2}{(\$, Character)->\$}{StringAggregate}
{See \spadfun{leftTrim}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightUnits}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Union(\$, "failed")}{FiniteRankNonAssociativeAlgebra}
{See \spadfun{leftUnits}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rischNormalize}}\opLeftPren{}{\it expression}, 
\allowbreak{}{\it  x}\opRightPren{}%
}%
}%
{2}{(F, Symbol)->Record(func:F, kers:List(Kernel(F)), vals:List(F))}
{ElementaryFunctionStructurePackage}
{\smath{\mbox{\bf rischNormalize}\opLeftPren{}f, 
\allowbreak{} x\opRightPren{}} returns \smath{[g, [k_1, \ldots,
k_n], [h_1, \ldots, h_n]]} such that \smath{g = {\bf normalize}(f,
x)} and each \smath{k_i} was rewritten as \smath{h_i} during the
normalization.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rightLcm}}\opLeftPren{}
{\it lodOperator}, \allowbreak{}{\it  lodOperator}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{LinearOrdinaryDifferentialOperator}
{\smath{\mbox{\bf rightLcm}\opLeftPren{}a, \allowbreak{} b\opRightPren{}},
where \smath{a} and \smath{b} are linear ordinary differential operators,
computes the value \smath{m} of lowest degree 
such that \smath{m = aa*a = bb*b}
for some values \smath{aa} and \smath{bb}. 
The value \smath{m} is computed using right-division.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{roman}}\opLeftPren{}
{\it integerOrSymbol}\opRightPren{}%
}%
}%
{1}{(Integer)->\$}{RomanNumeral}
{\smath{\mbox{\bf roman}\opLeftPren{}x\opRightPren{}} creates a roman 
numeral for integer or symbol \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{romberg}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  threeIntegers}
\opRightPren{}%
\optand \mbox{\axiomFun{rombergOpen}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  twoIntegers}\opRightPren{}%
 \opand \mbox{\axiomFun{rombergClose}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  twoIntegers}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf romberg}\opLeftPren{}fn, \allowbreak{} a, 
\allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, 
\allowbreak{} nmax, \allowbreak{} nint\opRightPren{}}
uses an adaptive romberg method to numerically integrate function
\smath{fn} over the closed interval from \smath{a} to \smath{b},
with relative accuracy \smath{epsrel} and absolute accuracy
\smath{epsabs};
the refinement levels for the checking of convergence
vary from \smath{nmin} to \smath{nmax}.
The method is called ``adaptive'' since it requires an additional
parameter \smath{nint} giving the number of subintervals over which
the integrator independently applies the convergence criteria using
\smath{nmin} and \smath{nmax}.
This is useful when a large number of points are needed only
in a small fraction of the entire interval.
Parameter \smath{fn} is a function of type \spadsig{Float}{Float};
\smath{a}, \smath{b}, \smath{epsrel}, and \smath{epsabs} are floats;
\smath{nmin}, \smath{nmax}, and \smath{nint} are integers.
The operation returns a record containing:
{\tt value}, an estimate of the integral;
{\tt error}, an estimate of the error in the computation;
{\tt totalpts}, the total integral number of
function evaluations, and
{\tt success}, a boolean value that is \smath{true} if
the integral was computed within the user specified error criterion.
See \spadtype{NumericalQuadrature} for details.
\bigitem\smath{\mbox{\bf rombergClosed}\opLeftPren{}fn, 
\allowbreak{} a, \allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, \allowbreak{} nmax\opRightPren{}}
similarly uses the
Romberg method to numerically integrate function \smath{fn}
over the closed interval \smath{a} to \smath{b},
but is not adaptive.
\bigitem\smath{\mbox{\bf rombergOpen}\opLeftPren{}fn, 
\allowbreak{} a, \allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, \allowbreak{} nmax\opRightPren{}} is similar
to \spadfun{rombergClosed}, except that it
integrates function \smath{fn} over
the open interval from \smath{a} to \smath{b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{root}}\opLeftPren{}
{\it outputForm\opt{, positiveInteger}}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf root}\opLeftPren{}o\optinner{, n}\opRightPren{}},
where \smath{o} and \smath{n} are objects of type
\spadtype{OutputForm} (normally unexposed),
creates an output form for the \eth{\smath{n}} root of the form \smath{o}.
By default, \smath{n = 2}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rootOfIrreduciblePoly}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(SparseUnivariatePolynomial(GF))->F}{FiniteFieldPolynomialPackage2}
{\smath{\mbox{\bf rootOfIrreduciblePoly}\opLeftPren{}f\opRightPren{}} 
computes one root of the monic,
irreducible polynomial \smath{f}, whose degree must divide the
extension degree of \smath{F} over \smath{GF}.
That is, \smath{f} splits into linear factors over \smath{F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rootOf}}\opLeftPren{}
{\it polynomial\opt{, variable}}\opRightPren{}%
}%
}%
{1}{(Polynomial(\$))->\$}{AlgebraicallyClosedField}
{\smath{\mbox{\bf rootOf}\opLeftPren{}p\optinner{, y}\opRightPren{}} 
returns \smath{y} such that
\smath{p(y) = 0}.
The object returned displays as \smath{'y}.
The second argument may be omitted when \smath{p} is a polynomial in a unique
variable \smath{y}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rootSimp}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{AlgebraicManipulations}
{\smath{\mbox{\bf rootSimp}\opLeftPren{}f\opRightPren{}} 
transforms every radical of the form
\smath{(a b^{q n+r})^{1/n}}
appearing in expression \smath{f} into \smath{b^q  (a  b^r)^{1/n}}.
This transformation is not in general valid for all complex numbers \smath{b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rootsOf}}\opLeftPren{}
{\it polynomialOrExpression \opt{, symbol}}\opRightPren{}%
}%
}%
{2}{(SparseUnivariatePolynomial(\$), Symbol)->List(\$)}
{AlgebraicallyClosedField}
{\smath{\mbox{\bf rootsOf}\opLeftPren{}p \optinner{, y}\opRightPren{}} returns
the value of \smath{[y_1, \ldots, y_n]} such that \smath{p(y_i) = 0}.
The \smath{y_i} are symbols of the form \%\smath{y} with a suffix number
which are bound in the interpreter to respective root values.
Argument \smath{p} is either an expression or a polynomial.
Argument \smath{y} may be omitted in which case \smath{p} must contain
exactly one symbol.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rootSplit}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{AlgebraicManipulations}
{\smath{\mbox{\bf rootSplit}\opLeftPren{}f\opRightPren{}} 
transforms every radical of the form
\smath{(a/b)^{1/n}} appearing in \smath{f} into \smath{a^{1/n} /
b^{1/n}}.
This transformation is
not in general valid for all complex numbers \smath{a} and \smath{b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rotate!}}\opLeftPren{}{\it queue}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{QueueAggregate}
{\smath{\mbox{\bf rotate!}\opLeftPren{}q\opRightPren{}} rotates 
queue \smath{q} so that the element at
the front of the queue goes to the back of the queue.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{round}}\opLeftPren{}{\it float}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{RealNumberSystem}
{\smath{\mbox{\bf round}\opLeftPren{}x\opRightPren{}} computes the 
integer closest to \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{row}}\opLeftPren{}{\it matrix}, \allowbreak{}
{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->Row}{RectangularMatrixCategory}
{\smath{\mbox{\bf row}\opLeftPren{}m, \allowbreak{} i\opRightPren{}} 
returns the \eth{\smath{i}} row of the matrix
or
two-dimensional array \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rowEchelon}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{MatrixCategory}
{\smath{\mbox{\bf rowEchelon}\opLeftPren{}m\opRightPren{}} 
returns the row echelon form of the matrix
\smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rst}}\opLeftPren{}{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{LazyStreamAggregate}
{\smath{\mbox{\bf rst}\opLeftPren{}s\opRightPren{}} 
returns a pointer to the next node of stream
\smath{s}.
Caution: this function should only be called after a
\axiomFun{empty?} test returns
\smath{true} since no error check is performed.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rubiksGroup}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf rubiksGroup}\opLeftPren{}\opRightPren{}} 
constructs the permutation group representing Rubic's Cube
acting on integers \smath{10i+j} for
\smath{1 \leq i \leq 6, 1 \leq j \leq 8}.
The faces of Rubik's Cube are labelled: Front, Right, Up, 
Down, Left, Back and numbered from 1 to 6.
The pieces on each face (except the unmoveable center piece) 
are clockwise numbered
from 1 to 8 starting with the piece in the upper left corner.
The moves of the cube are represented as permutations on these pieces,
represented as a two digit integer \smath{ij} where 
\smath{i} is the number of the face
and \smath{j} is the number of the piece on this face.
The remaining ambiguities are resolved by looking at the 6 generators
representing  90-degree turns of the faces.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rule}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{2}{(F, F)->\$}{RewriteRule}
{Section \ref{ugUserRules} on page \pageref{ugUserRules}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rules}}\opLeftPren{}{\it ruleset}\opRightPren{}%
}%
}%
{1}{(\$)->List(RewriteRule(Base, R, F))}{Ruleset}
{\smath{\mbox{\bf rules}\opLeftPren{}r\opRightPren{}} 
returns the list of rewrite rules contained in ruleset \smath{r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{ruleset}}\opLeftPren{}
{\it listOfRules}\opRightPren{}%
}%
}%
{1}{(List(RewriteRule(Base, R, F)))->\$}{Ruleset}
{\smath{\mbox{\bf ruleset}\opLeftPren{}[r1, \allowbreak{} 
\ldots, rn]\opRightPren{}} creates a ruleset
from a list of rewrite rules \smath{r_1}, \ldots, \smath{r_n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{rungaKutta}}\opLeftPren{}
{\it vector}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  fourFloats}, \allowbreak{}
{\it  integer}, \allowbreak{}{\it  function}\opRightPren{}%
\opand \mbox{\axiomFun{rungaKuttaFixed}}\opLeftPren{}
{\it vector}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  float}, \allowbreak{}
{\it  float}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  function}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf rungaKutta}\opLeftPren{}y, \allowbreak{} n, 
\allowbreak{} a, \allowbreak{} b, \allowbreak{} eps, \allowbreak{} h, 
\allowbreak{} ncalls, \allowbreak{} derivs\opRightPren{}}
uses a \smath{4}--th order Runga-Kutta method to numerically
integrate the ordinary differential equation $dy/dx = f(y, x)$ 
from \smath{x_1} to \smath{x_2},
where \smath{y} is an \smath{n}--vector of
\smath{n} variables.
Initial and final values are provided by solution vector \smath{y}.
The local truncation error is kept within \smath{eps} by changing
the local step size.
Argument \smath{h} is a trial step size and
\smath{ncalls} is the maximum number of single steps the integrator is
allowed to take.
Argument \smath{derivs}
is a
function of type \spadsig{(Vector Float, Vector Float, Float)}{Void},
which computes the right-hand side of the ordinary differential
equation, then replaces the elements of the first argument
by updated elements.
\bigitem\smath{\mbox{\bf rungaKuttaFixed}\opLeftPren{}y, 
\allowbreak{} n, \allowbreak{} x_1, \allowbreak{} x_2, \allowbreak{} ns, 
\allowbreak{} derivs\opRightPren{}} is similar to
\spadfun{rungaKutta} except that it uses \smath{ns} fixed
steps to integrate the solution vector \smath{y}
from \smath{x_1} to \smath{x_2}, returning the values
in \smath{y}.
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{saturate}}\opLeftPren{}{\it ideal}, 
\allowbreak{}{\it  polynomial}\allowbreak $\,[$ , \allowbreak{}
{\it  listOfVariables}$]$\opRightPren{}%
}%
}%
{2}{(\$, DPoly)->\$}{PolynomialIdeals}
{\smath{\mbox{\bf saturate}\opLeftPren{}I, 
\allowbreak{} f\optinner{, lvar}\opRightPren{}} is the saturation of the
ideal \smath{I} with respect to the multiplicative set generated
by the polynomial \smath{f} in the variables given by
\smath{lvar}, a list of variables.
Argument \smath{lvar} may be omitted in which case \smath{lvar} is
taken to be the list of all variables appearing in \smath{f}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{say}}\opLeftPren{}{\it strings}\opRightPren{}%
}%
}%
{1}{(List(String))->Void}{DisplayPackage}
{\smath{\mbox{\bf say}\opLeftPren{}u\opRightPren{}} 
sends a string or a list of strings \smath{u} to
output.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sayLength}}\opLeftPren{}
{\it listOfStrings}\opRightPren{}%
}%
}%
{1}{(List(String))->Integer}{DisplayPackage}
{\smath{\mbox{\bf sayLength}\opLeftPren{}ls\opRightPren{}} 
returns the total number of characters
in the list of strings \smath{ls}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{scalarMatrix}}\opLeftPren{}
{\it scalar\opt{, dimension}}\opRightPren{}%
}%
}%
{1}{(R)->\$}{SquareMatrixCategory}
{\smath{\mbox{\bf scalarMatrix}\opLeftPren{}r\optinner{, n}\opRightPren{}} 
returns an
\smath{n}-by-\smath{n} matrix with
scalar \smath{r} on the diagonal and zero elsewhere.
The dimension may be omitted if the result is to be an object
of type \smath{\mbox{\bf SquareMatrix}\opLeftPren{}n, 
\allowbreak{} R\opRightPren{}} for some \smath{n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{scan}}\opLeftPren{}{\it binaryFunction}, 
\allowbreak{}{\it  aggregate}, \allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{3}{((S, R)->R, A, R)->B}{FiniteLinearAggregateFunctions2}
{\smath{\mbox{\bf scan}\opLeftPren{}f, \allowbreak{} a, 
\allowbreak{} r\opRightPren{}} successively applies 
\smath{\mbox{\bf reduce}\opLeftPren{}f, 
\allowbreak{} x, \allowbreak{} r\opRightPren{}} to
more and more leading sub-aggregates \smath{x} of aggregrate \smath{a}.
More precisely, if \smath{a} is \smath{[a1, a2, \ldots]}, then
\smath{\mbox{\bf scan}\opLeftPren{}f, \allowbreak{} a, 
\allowbreak{} r\opRightPren{}} returns
\smath{[reduce(f, [a1], r), reduce(f, [a1, a2], r), \ldots]}.
Argument \smath{a} can be any linear aggregate including streams.
For example, if \smath{a} is a list or an infinite stream of 
the form \smath{[x_1, x_2, \ldots]},
then \code{scan(+, a, 0)} returns a list or stream
of the form \smath{[x_1, x_1 + x_2, \ldots]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{scanOneDimSubspaces}}\opLeftPren{}
{\it listOfVectors}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(List(Vector(R)), Integer)->Vector(R)}{RepresentationPackage2}
{\smath{\mbox{\bf scanOneDimSubspaces}\opLeftPren{}basis, 
\allowbreak{} n\opRightPren{}} gives a canonical
representative of the \eth{\smath{n}}
one-dimensional subspace of the vector space generated by the elements of
\smath{basis}.
Consult \spadtype{RepresentationPackage2} using details.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{script}}\opLeftPren{}{\it symbol}, 
\allowbreak{}{\it  listOfListsOfOutputForms}\opRightPren{}%
}%
}%
{2}{(\$, List(List(OutputForm)))->\$}{Symbol}
{\smath{\mbox{\bf script}\opLeftPren{}sy, \allowbreak{} 
[a, \allowbreak{} b, \allowbreak{} c, \allowbreak{} d, 
\allowbreak{} e]\opRightPren{}} 
returns \smath{sy} with
subscripts
\smath{a}, superscripts \smath{b}, pre-superscripts \smath{c},
pre-subscripts \smath{d}, and argument-scripts \smath{e}.
Omitted components are taken to be empty.
For example, \smath{\mbox{\bf script}\opLeftPren{}s, 
\allowbreak{} {\tt [}a, \allowbreak{} b, 
\allowbreak{} c{\tt ]}\opRightPren{}} is equivalent
to \smath{\mbox{\bf script}\opLeftPren{}s, \allowbreak{} 
{\tt [}a, \allowbreak{} b, \allowbreak{} c, \allowbreak{} {\tt []}, 
\allowbreak{} {\tt []]}\opRightPren{}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{scripted?}}\opLeftPren{}{\it symbol}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{Symbol}
{\smath{\mbox{\bf scripted?}\opLeftPren{}sy\opRightPren{}} tests 
if \smath{sy} has been given any scripts.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{scripts}}\opLeftPren{}
{\it symbolOrOutputForm\opt{, listOfOutputForms}}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf scripts}\opLeftPren{}o, \allowbreak{} lo\opRightPren{}},
where \smath{o} is an object of type \spadtype{OutputForm} 
(normally unexposed)
and \smath{lo} is a list \smath{[sub, super, presuper, presub]}
of four objects
of type \spadtype{OutputForm} (normally unexposed),
creates a form for \smath{o} with scripts on all four corners.
\newline\smath{\mbox{\bf scripts}\opLeftPren{}s\opRightPren{}} 
returns all the scripts of \smath{s} as a record with
selectors \smath{sub}, \smath{sup}, \smath{presup}, \smath{presub}, 
and \smath{args},
each with a list of output forms as a value.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{search}}\opLeftPren{}{\it key}, \allowbreak{}
{\it  table}\opRightPren{}%
}%
}%
{2}{(Key, \$)->Union(Entry, "failed")}{KeyedDictionary}
{\smath{\mbox{\bf search}\opLeftPren{}k, \allowbreak{} t\opRightPren{}} 
searches the table \smath{t} for the key
\smath{k},
returning the entry stored in \smath{t} for key \smath{k},
or \mbox{\tt "failed"} if \smath{t} has no such key.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sec}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{secIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\smath{\mbox{\bf sec}\opLeftPren{}x\opRightPren{}} 
returns the secant of \smath{x}.
\newitem
\smath{\mbox{\bf secIfCan}\opLeftPren{}z\opRightPren{}} 
returns \smath{\mbox{\bf sec}\opLeftPren{}z\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sec2cos}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf sec2cos}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\mbox{\bf sec}\opLeftPren{}u\opRightPren{}} 
appearing in \smath{f} into \smath{1/{\rm cos}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sech}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{sechIfCan}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\smath{\mbox{\bf sech}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic secant of \smath{x}.
\newitem
\smath{\mbox{\bf sechIfCan}\opLeftPren{}z\opRightPren{}} 
returns \smath{\mbox{\bf sech}\opLeftPren{}z\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sech2cosh}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf sech2cosh}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\mbox{\bf sech}\opLeftPren{}u\opRightPren{}} 
appearing in \smath{f} into \smath{1/{\rm cosh}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{second}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->S}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf second}\opLeftPren{}u\opRightPren{}} 
returns the second element of recursive aggregate \smath{u}.
Note: \smath{\mbox{\bf second}\opLeftPren{}u) = {\bf first}({\bf rest}(u))}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{segment}}\opLeftPren{}
{\it integer\opt{, integer}}\opRightPren{}%
}%
}%
{1}{(S)->\$}{UniversalSegment}
{\smath{\mbox{\bf segment}\opLeftPren{}i\optinner{, j}\opRightPren{}} returns
the segment \smath{i..j}.
If not qualified by a {\bf by} clause, this notation for
integers \smath{i} and \smath{j}
denotes the tuple of integers \smath{i}, \smath{i+1}, \ldots, \smath{j}.
When \smath{j} is omitted, 
\smath{\mbox{\bf segment}\opLeftPren{}i\opRightPren{}}
denotes the half open segment
\smath{i..}, that is, a segment with no upper bound.
\newline
\smath{\mbox{\bf segment}\opLeftPren{}x = bd\opRightPren{}},
where \smath{bd} is a binding, returns \smath{bd}.
For example, \smath{\mbox{\bf segment}\opLeftPren{}x = a..b\opRightPren{}} 
returns
\smath{a..b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{select}}\opLeftPren{}{\it pred}, \allowbreak{}
{\it  aggregate}\opRightPren{}%
 \opand \mbox{\axiomFun{select!}}\opLeftPren{}{\it pred}, \allowbreak{}
{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S)->Boolean, \$)->\$}{Collection}
{\smath{\mbox{\bf select}\opLeftPren{}p, 
\allowbreak{} u\opRightPren{}} returns a copy of \smath{u} containing only
those elements \smath{x} such that \smath{p(x)} is \smath{true}.
For a list \smath{l}, \smath{select(p, l) == [x {\mbox{ \tt for }
} x {\mbox{ \tt in }} l {\tt |} p(x)]}.
Argument \smath{u} may be any finite aggregate or infinite stream.
\newitem \smath{\mbox{\bf select!}\opLeftPren{}p, 
\allowbreak{} u\opRightPren{}} destructively changes \smath{u} by
keeping only values \smath{x} such that \smath{p(x)} is true.
Argument \smath{u} can be any extensible linear aggregate or
dictionary.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{semicolonSeparate}}\opLeftPren{}
{\it listOfOutputForms}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf semicolonSeparate}\opLeftPren{}lo\opRightPren{}}, 
where \smath{lo} is a list of
objects of type \spadtype{OutputForm} (normally unexposed),
returns an output form which separates the elements of \smath{lo}
by semicolons.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{separant}}\opLeftPren{}
{\it differentialPolynomial}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf separant}\opLeftPren{}polynomial\opRightPren{}} 
returns the partial derivative of
the differential polynomial \smath{p} with respect to its leader.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{separate}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Record(primePart:\$, commonPart:\$)}
{UnivariatePolynomialCategory}
{\smath{\mbox{\bf separate}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} returns \spad({a, b)} such that polynomial
\smath{p = a b} and \smath{a} is relatively prime to \smath{q}.
The result produced is a record with selectors \smath{primePart}
and \smath{commonPart}
with value \smath{a} and \smath{b} respectively.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{separateDegrees}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(FP)->List(Record(deg:NonNegativeInteger, prod:FP))}
{DistinctDegreeFactorize}
{\smath{\mbox{\bf separateDegrees}\opLeftPren{}p\opRightPren{}} 
splits the polynomial \smath{p} into factors.
Each factor is a record with selector \smath{deg},
a non-negative integer, and \smath{prod}, a product of irreducible polynomials
of degree \smath{deg}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{separateFactors}}\opLeftPren{}
{\it listOfRecords}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(List(Record(deg:NonNegativeInteger, prod:FP)), FP)->
List(FP)}{DistinctDegreeFactorize}
{\smath{\mbox{\bf separateFactors}\opLeftPren{}lfact, 
\allowbreak{} p\opRightPren{}} takes the list produced by
\spadfunFrom{separateDegrees}{DistinctDegreeFactorization} along
with the original polynomial \smath{p}, and produces the 
complete list of factors.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{separateFactors}}\opLeftPren{}
{\it listOfRecords}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(List(Record(factor:U, degree:Integer)), 
Integer)->List(U)}{ModularDistinctDegreeFactorizer}
{\smath{\mbox{\bf separateFactors}\opLeftPren{}ddl, 
\allowbreak{} p\opRightPren{}} refines the distinct degree factorization 
produced by \spadfunFrom{ddFact}{ModularDistinctDegreeFactorizer} to give a 
complete list of factors.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sequences}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
\opand \mbox{\axiomFun{sequences}}\opLeftPren{}{\it listOfIntegers}, 
\allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{2}{(List(Integer), List(Integer))->Stream(List(Integer))}
{PartitionsAndPermutations}
{\smath{\mbox{\bf sequences}\opLeftPren{}[l_0, \allowbreak{} l_1, 
\allowbreak{} l_2, \allowbreak{} .., \allowbreak{} l_n]\opRightPren{}} 
is the set of 
all sequences
formed from \smath{l_0} 0's, \smath{l_1} 1's, \smath{l_2} 2's, \ldots, 
\smath{l_n} \smath{n}'s.
\newitem
\smath{\mbox{\bf sequences}\opLeftPren{}l1, \allowbreak{} l2\opRightPren{}} 
is the stream of all sequences that can be composed from
the multiset defined from two lists of integers \smath{l1} and \smath{l2}.
For example, the pair \smath{([1, 2, 4], [2, 3, 5])} represents multiset
with 1 \smath{2}, 2 \smath{3}'s, and 4 \smath{5}'s.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{series}}\opLeftPren{}
{\it specifications\opt{, \ldots}}\opRightPren{}%
}%
}%
{1}{(Stream(Coef))->\$}{UnivariateTaylorSeriesCategory}
{\smath{\mbox{\bf series}\opLeftPren{}expression\opRightPren{}} 
returns a series expansion of the expression \smath{f}.
Note: \smath{f} must have only one variable. The series will be 
expanded in powers
of that variable.
\newitem
\smath{\mbox{\bf series}\opLeftPren{}sy\opRightPren{}}, 
where \smath{sy} is a symbol, returns \smath{sy} as a series.
\newitem
\smath{\mbox{\bf series}\opLeftPren{}st\opRightPren{}},
where \smath{t} is a stream \smath{[a_0, a_1, a_2, \ldots]} 
of coefficients \smath{a_i}
from some ring,
creates the Taylor series \smath{a_0 + a_1 x + a_2 x^2 +\ldots}.
Also, if \smath{st} is a stream of elements of type 
\spadtype{Record(k:NonNegativeInteger, c:R)},
where \smath{k} denotes an exponent and \smath{c}, 
a non-zero coefficient from some ring \smath{R},
it creates a stream of non-zero terms.
The terms in \smath{st} must be ordered by increasing order of exponents.
\newitem
\smath{\mbox{\bf series}\opLeftPren{}f, 
\allowbreak{} x = a\optinner{, n}\opRightPren{}} 
expands the expression \smath{f} as a
series in powers of \smath{(x - a)} with \smath{n} terms.
If \smath{n} is missing, the number of terms is governed by
the value set by the system command \spadsyscom{)set streams calculate}.
\newitem
\smath{\mbox{\bf series}\opLeftPren{}f, \allowbreak{} n\opRightPren{}} 
returns a series expansion of the expression
\smath{f}.
Note: \smath{f} should have only one variable; the series will be
expanded in powers of that variable and terms will be computed up
to order at least \smath{n}.
\newitem
\smath{\mbox{\bf series}\opLeftPren{}i {\tt +->} a(i), 
\allowbreak{} x = a, \allowbreak{} m..\optinner{n, k}\opRightPren{}} 
creates the series
\smath{\sum\nolimits_{i = m..n {\ \tt by \ } k}{a(i)  (x - a)^i}}.
Here \smath{m}, \smath{n}, and \smath{k} are rational numbers.
Upper-limit \smath{n} and stepsize \smath{k} are optional and 
have default values
\smath{n = \infty} and \smath{k = 1}.
\newitem
\smath{\mbox{\bf series}\opLeftPren{}a(i), \allowbreak{} i, 
\allowbreak{} x=a, \allowbreak{} m..\optinner{n, k}\opRightPren{}} returns
\smath{\sum\nolimits_{i = m..n {\bf by} k}{a(n) (x - a)^n}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{seriesSolve}}\opLeftPren{}{\it eq}, 
\allowbreak{}{\it  y}, \allowbreak{}{\it  x}, \allowbreak{}
{\it  c}\opRightPren{}%
}%
}%
{1}{(Equation(Expression(R)))->List(Equation(Expression(R)))}
{TransSolvePackage}
{\bigopkey{\smath{eq} denotes an equation to be solved;
alternatively, an expression \smath{u} may be given for \smath{eq} 
in which case the equation
\smath{eq} is defined as \smath{u=0}.
\largerbreak\smath{leq} denotes a list \smath{[ eq_1\ldots eq_n]} of 
equations; alternatively,
a list of expressions \smath{[ u_1\ldots u_n]}
may be given of \smath{leq} in which case the equations \smath{eq_i} are
defined by \smath{u_i=0}.
}
\bigitem\smath{\mbox{\bf seriesSolve}\opLeftPren{}eq, \allowbreak{} y, 
\allowbreak{} x=a, \allowbreak{} \optinner{y(a)=}b\opRightPren{}} 
returns a Taylor series solution of
\smath{eq} around \smath{x=a} with initial condition \smath{y(a)=b}.
Note: \smath{eq} must be of the form
\smath{f(x, y)y'(x) + g(x, y) = h(x, y)}.
\bigitem\smath{\mbox{\bf seriesSolve}\opLeftPren{}eq, 
\allowbreak{} y, \allowbreak{} x=a, \allowbreak{} 
[ b_0, \ldots, b_{(n-1)}]\opRightPren{}} returns
a Taylor series solution of \smath{eq} around 
\smath{x=a} with initial conditions
\smath{y(a)=b_0},
\smath{y'(a)=b_1},
$\ldots$
\smath{y^{(n-1)}(a)=b_{(n-1)}}.
Equation \smath{eq} must be of the form
\smath{f(x, y, y', \ldots, y^{(n-1)})*y^{(n)}(x)+
g(x, y, x', \ldots, y^{(n-1)}) = h(x, y, y', \ldots, y^{(n-1)})}.
\bigitem\smath{seriesSolve(leq, [ y_1, \ldots, y_n], x =
a, [ y_1(a)=b_1, \ldots, y_n(a)=b_n])} returns a Taylor
series
solution of the equations \smath{eq_i} around \smath{x = a}
with initial conditions \smath{y_i(a)=b_i}.
Note: each \smath{eq_i} must be of the form
\smath{f_i(x, y_1, y_2, \ldots, y_n)y_1'(x) +
g_i(x, y_1, y_2, \ldots, y_n) = h(x, y_1, y_2, \ldots, y_n)}.
\bigitem\smath{seriesSolve(leq, [ y_1, \ldots, y_n], x =
a, [ b_1, \ldots, b_n])} is equivalent to the same
command with
fourth argument \smath{[ y_1(a)=b_1, \ldots, y_n(a)=b_n]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setchildren!}}\opLeftPren{}
{\it recursiveAggregate}\opRightPren{}%
}%
}%
{2}{(\$, List(\$))->\$}{RecursiveAggregate}
{\smath{\mbox{\bf setchildren!}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} replaces the current children of node
\smath{u} with the members of \smath{v} in left-to-right order.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setColumn!}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{3}{(\$, Integer, Col)->\$}{TwoDimensionalArrayCategory}
{\smath{\mbox{\bf setColumn!}\opLeftPren{}m, \allowbreak{} j, 
\allowbreak{} v\opRightPren{}} sets the \eth{\smath{j}} column of
matrix or two-dimensional array \smath{m} to \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setDifference}}\opLeftPren{}
{\it list}, \allowbreak{}{\it  list}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{List}
{\smath{\mbox{\bf setDifference}\opLeftPren{}l_1, 
\allowbreak{} l_2\opRightPren{}} returns a list of the 
elements of \smath{l_1} that are
not also in \smath{l_2}.
The order of elements in the resulting list is unspecified.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setelt}}\opLeftPren{}
{\it structure}, \allowbreak{}{\it  index}, \allowbreak{}
{\it  value}\allowbreak $\,[$ , \allowbreak{}{\it  option}$]$\opRightPren{}%
}%
}%
{3}{(\$, Dom, Im)->Im}{EltableAggregate}
{\smath{\mbox{\bf setelt}\opLeftPren{}u, 
\allowbreak{} x, \allowbreak{} y\opRightPren{}}, also written \smath{u.x := y},
sets the image of \smath{x} to be \smath{y} under \smath{u},
regarded as a function mapping values from the domain of \smath{x} to
the domain of \smath{y}. Specifically, if \smath{u} is:
\begin{simpleList}
\item a list: \smath{u.first := x} is equivalent to
\smath{\mbox{\bf setfirst!}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}}.
Also,
\smath{u.rest := x} is equivalent to 
\smath{\mbox{\bf setrest!}\opLeftPren{}u, \allowbreak{} x\opRightPren{}}, and
\smath{u.last := x} is equivalent to 
\smath{\mbox{\bf setlast!}\opLeftPren{}u, \allowbreak{} x\opRightPren{}}.
\item a linear aggregate,
\smath{u(i..j) := x} destructively replaces each element in the
segment \smath{u(i..j)} by \smath{x}. The value \smath{x} is returned.
Note: This function has the same effect as 
\code{for k in i..j repeat u.k := x; x}.
The length of \smath{u} is unchanged.
\item a recursive aggregate,
\smath{u.value := x} is equivalent to 
\smath{\mbox{\bf setvalue!}\opLeftPren{}u, \allowbreak{} x\opRightPren{}} and 
sets the value part of node \spad{u} to \spad{x}.
Also, if \spad{u} is a \spadtype{BinaryTreeAggregate},
\smath{u.left := x} is equivalent to 
\smath{\mbox{\bf setleft!}\opLeftPren{}u, \allowbreak{} x\opRightPren{}} 
and sets the left child
of \spad{u} to \spad{x}. Simiarly,
\smath{u.right := x} is equivalent to 
\smath{\mbox{\bf setright!}\opLeftPren{}u, \allowbreak{} x\opRightPren{}}.
See also \spadfun{setchildren!}.
\item a table of category TableAggregate(Key, Entry):
u(k) := e is equivalent to \smath{({\bf insert}([k, e], t); e)}, 
where \smath{k} is
a key and \smath{e} is an entry.
\item a library:
\smath{u.k := v} saves the value \smath{v} in the library \smath{u}, so that
it can later be extracted by \smath{u.k}.
\end{simpleList}
\smath{\mbox{\bf setelt}\opLeftPren{}u, 
\allowbreak{} i, \allowbreak{} j, 
\allowbreak{} r\opRightPren{}}, also written, \smath{u(i, j) := r}, sets
the element in the
\eth{\smath{i}} row and \eth{\smath{j}} column of matrix or
two-dimensional array \smath{u}
to \smath{r}.
\newitem
\smath{\mbox{\bf setelt}\opLeftPren{}u, 
\allowbreak{} rowList, \allowbreak{} colList, \allowbreak{} r\opRightPren{}},
also written \smath{u([i_1, i_2, \ldots, i_m], [j_1, j_2, \ldots, j_n]) := r},
where \smath{u} is a matrix or two-dimensional array and
\smath{r} is another \smath{m} by \smath{n} matrix or array,
destructively alters the matrix \smath{u}:
the \smath{x_{i_k, j_l}} is set to \smath{r(k, l)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setEpilogue!}}\opLeftPren{}
{\it formattedObject}, \allowbreak{}{\it  listOfStrings}\opRightPren{}%
}%
}%
{2}{(\$, List(String))->List(String)}{ScriptFormulaFormat}
{\smath{\mbox{\bf setEpilogue!}\opLeftPren{}t, 
\allowbreak{} strings\opRightPren{}} sets the epilogue section of a
formatted object \smath{t} to \smath{strings}.
Argument \smath{t} is either an IBM SCRIPT Formula 
Formatted or \TeX{} formatted object.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setfirst!}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  value}\opRightPren{}%
}%
}%
{2}{(\$, S)->S}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf setfirst!}\opLeftPren{}a, 
\allowbreak{} x\opRightPren{}} destructively 
changes the first element of recursive
aggregate \smath{a} to \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setFormula!}}\opLeftPren{}
{\it formattedObject}, \allowbreak{}{\it  listOfStrings}\opRightPren{}%
}%
}%
{2}{(\$, List(String))->List(String)}{ScriptFormulaFormat}  
{\smath{\mbox{\bf setFormula!}\opLeftPren{}t, 
\allowbreak{} strings\opRightPren{}} sets the formula section of a formatted 
object \smath{t} to \smath{strings}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setIntersection}}\opLeftPren{}
{\it list}, \allowbreak{}{\it  list}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{List}
{\smath{\mbox{\bf setIntersection}\opLeftPren{}l_1, 
\allowbreak{} l_2\opRightPren{}} returns a list of the 
elements that lists \smath{l_1}
and \smath{l_2} have in common. The order of elements 
in the resulting list is unspecified.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setlast!}}\opLeftPren{}
{\it aggregate}, \allowbreak{}{\it  value}\opRightPren{}%
}%
}%
{2}{(\$, S)->S}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf setlast!}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}} destructively changes the last element of
\smath{u} to \smath{x}.
Note: \smath{u.last := x} is equivalent.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setleaves!}}\opLeftPren{}
{\it balancedBinaryTree}, \allowbreak{}{\it  listOfElements}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BinaryRecursiveAggregate}
{\smath{\mbox{\bf setleaves!}\opLeftPren{}t, 
\allowbreak{} ls\opRightPren{}} sets the leaves of balanced binary tree
\smath{t} in left-to-right order to the elements of \smath{ls}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setleft!}}\opLeftPren{}
{\it binaryRecursiveAggregate}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BinaryRecursiveAggregate}
{\smath{\mbox{\bf setleft!}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}} sets the left child of \smath{a} to be
\smath{b}.
}




% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setPrologue!}}\opLeftPren{}
{\it formattedObject}, \allowbreak{}{\it  listOfStrings}\opRightPren{}%
}%
}%
{2}{(\$, List(String))->List(String)}{ScriptFormulaFormat}
{\smath{\mbox{\bf setPrologue!}\opLeftPren{}t, 
\allowbreak{} strings\opRightPren{}} sets the prologue 
section of a formatted object \smath{t} 
to \smath{strings}.
Argument \smath{t} is either an IBM SCRIPT Formula Formatted or 
\TeX{} formatted object.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setProperties!}}\opLeftPren{}
{\it basicOperator}, \allowbreak{}{\it  associationList}\opRightPren{}%
}%
}%
{2}{(\$, AssociationList(String, None))->\$}{BasicOperator}
{\smath{\mbox{\bf setProperties!}\opLeftPren{}op, 
\allowbreak{} al\opRightPren{}} sets the property 
list of basic operator \smath{op} to
association list \smath{l}.
Note: argument \smath{op} is modified ``in place'', that is, no copy is made.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setProperty!}}\opLeftPren{}{\it basicOperator}, 
\allowbreak{}{\it  string}, \allowbreak{}{\it  value}\opRightPren{}%
}%
}%
{3}{(\$, String, None)->\$}{BasicOperator}
{\smath{\mbox{\bf setProperty!}\opLeftPren{}op, 
\allowbreak{} s, \allowbreak{} v\opRightPren{}} attaches property \smath{s} to
\smath{op}, and sets its value to \smath{v}.
Argument \smath{op} is modified ``in place'', that is,
no copy is made.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setrest!}}\opLeftPren{}
{\it aggregate\optinit{, integer}, aggregate}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{UnaryRecursiveAggregate}
{\opkey{Arguments \smath{u} and \smath{v} 
are finite or infinite aggregates of the same type.}
\newitem
\smath{\mbox{\bf setrest!}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} destructively 
changes the rest of \smath{u} to \smath{v}.
\newitem
\smath{\mbox{\bf setrest!}\opLeftPren{}x, \allowbreak{} n, 
\allowbreak{} y\opRightPren{}} destructively changes \smath{x}
so that \smath{\mbox{\bf rest}\opLeftPren{}x, 
\allowbreak{} n\opRightPren{}}, that is, \smath{x} 
after the \eth{\smath{n}} element, equals \smath{y}.
The function will expand cycles if necessary.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setright!}}\opLeftPren{}
{\it binaryRecursiveAggregate}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BinaryRecursiveAggregate}
{\smath{\mbox{\bf setright!}\opLeftPren{}a, 
\allowbreak{} x\opRightPren{}} sets the right child of \smath{t} to be
\smath{x}.}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setRow!}}\opLeftPren{}
{\it matrix}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  row}\opRightPren{}%
}%
}%
{3}{(\$, Integer, Row)->\$}{TwoDimensionalArrayCategory}
{\smath{\mbox{\bf setRow!}\opLeftPren{}m, \allowbreak{} i, 
\allowbreak{} v\opRightPren{}} sets the \eth{\smath{i}} row of matrix or
two-dimensional array \smath{m} to \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setsubMatrix!}}\opLeftPren{}{\it matrix}, 
\allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  matrix}\opRightPren{}%
}%
}%
{4}{(\$, Integer, Integer, \$)->\$}{MatrixCategory}
{\smath{\mbox{\bf setsubMatrix}\opLeftPren{}x, \allowbreak{} i_1, 
\allowbreak{} j_1, \allowbreak{} y\opRightPren{}} destructively 
alters the matrix \smath{x}.
Here \smath{x(i, j)} is set to \smath{y(i-i_1+1, j-j_1+1)} for
\smath{i = i_1, \ldots, i_1-1+{\bf nrows}(y)}
and \smath{j = j_1, \ldots, j_1-1+{\bf ncols}(y)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setTex!}}\opLeftPren{}
{\it text}, \allowbreak{}{\it  listOfStrings}\opRightPren{}%
}%
}%
{2}{(\$, List(String))->List(String)}{TexFormat}
{\smath{\mbox{\bf setTex!}\opLeftPren{}t, 
\allowbreak{} strings\opRightPren{}} sets the TeX section of a TeX form
\smath{t} to \smath{strings}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setUnion}}\opLeftPren{}
{\it list}, \allowbreak{}{\it  list}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{List}
{\smath{\mbox{\bf setUnion}\opLeftPren{}l_1, 
\allowbreak{} l_2\opRightPren{}} appends the two lists \smath{l_1} and
\smath{l_2}, then removes all duplicates.
The order of elements in the resulting list is unspecified.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setvalue!}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  value}\opRightPren{}%
}%
}%
{2}{(\$, S)->S}{RecursiveAggregate}
{\smath{\mbox{\bf setvalue!}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}} destructively changes the value of 
node \smath{u} to \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{setVariableOrder}}\opLeftPren{}
{\it listOfSymbols\opt{, listOfSymbols}}\opRightPren{}%
}%
}%
{1}{(List(Symbol))->Void}{UserDefinedVariableOrdering}
{\smath{\mbox{\bf setVariableOrder}\opLeftPren{}
[a_1, \allowbreak{} \ldots, a_m], [b_1, \ldots, b_n]\opRightPren{}} 
defines an ordering
on the variables given by \smath{a_1 > a_2 > \ldots > a_m >} other variables
\smath{b_1 > b_2 > \ldots > b_n}.
\newitem
\smath{\mbox{\bf setVariableOrder}\opLeftPren{}
[a1, \allowbreak{} \ldots, an]\opRightPren{}} defines an ordering given by
\smath{a_1 > a_2 > \ldots > a_n >} all
other variables.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sFunction}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{L I -> SPOL RN}{}{}
{\smath{\mbox{\bf sFunction}\opLeftPren{}li\opRightPren{}} 
is the S-function of the partition given by list of
linteger \smath{li},
expressed in terms of power sum symmetric functions.
See \spadtype{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{shade}}\opLeftPren{}{\it palette}\opRightPren{}%
}%
}%
{1}{(\$)->Integer}{Palette}
{\smath{\mbox{\bf shade}\opLeftPren{}p\opRightPren{}} 
returns the shade index of the indicated palette \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{shellSort}}\opLeftPren{}{\it sortingFunction}, 
\allowbreak{}{\it  aggregate}\opRightPren{}%
}%
}%
{2}{((S, S)->Boolean, V)->V}{FiniteLinearAggregateSort}
{\smath{\mbox{\bf shellSort}\opLeftPren{}f, \allowbreak{} a\opRightPren{}} 
sorts the aggregate \smath{a}
using the shellSort algorithm with sorting function \smath{f}.
Aggregate \smath{a} can be any finite linear aggregate which is
mutable (for example,
lists, vectors, and strings).
The sorting function \smath{f} has type \spadsig{(R, R)}{Boolean} where
\smath{R} is the domain of the elements of \smath{a}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{shift}}\opLeftPren{}{\it integerNumber}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf shift}\opLeftPren{}a, \allowbreak{} i\opRightPren{}} 
shifts integer number or float \smath{a} by \smath{i} digits.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{showAll?}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Boolean}{Stream}
{\smath{\mbox{\bf showAll?}\opLeftPren{}\opRightPren{}} 
tests if all computed entries of streams will be displayed
according to system command \spadsyscom{)set streams showall}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{showAllElements}}\opLeftPren{}
{\it stream}\opRightPren{}%
}%
}%
{1}{(\$)->OutputForm}{Stream}
{\smath{\mbox{\bf showAllElements}\opLeftPren{}s\opRightPren{}} 
creates an output form displaying all the already
computed elements of stream \smath{s}. This command will not result in any
further computation of elements of \smath{s}. Also, the command has no effect
if the user has previously entered \spadsyscom{)set streams showall true}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{showTypeInOutput}}\opLeftPren{}
{\it boolean}\opRightPren{}%
}%
}%
{1}{(Boolean)->String}{Any}
{\smath{\mbox{\bf showTypeInOutput}\opLeftPren{}bool\opRightPren{}} 
affects the way objects of \spadtype{Any}
are displayed. If \smath{bool} is \smath{true}, the type of the original 
object
that was converted to \spadtype{Any} will be printed. 
If \smath{bool} is \smath{false},
it will not be printed.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{shrinkable}}\opLeftPren{}{\it boolean}\opRightPren{}%
}%
}%
{1}{(Boolean)->String}{Any}
{\smath{\mbox{\bf shrinkable}\opLeftPren{}b\opRightPren{}\$R} 
tells Axiom that flexible arrays of domain \smath{R}
are or are not allowed to shrink (reduce their \spadfun{physicalLength})
according to whether \smath{b} is \smath{true} or \smath{false}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{shufflein}}\opLeftPren{}
{\it listOfIntegers}, \allowbreak{}{\it  streamOfListsOfIntegers}
\opRightPren{}%
}%
}%
{2}{(List(Integer), Stream(List(Integer)))->Stream(List(Integer))}
{PartitionsAndPermutations}
{\smath{\mbox{\bf shufflein}\opLeftPren{}li, 
\allowbreak{} sli\opRightPren{}} 
maps \smath{\mbox{\bf shuffle}\opLeftPren{}li, 
\allowbreak{} u\opRightPren{}} onto all members \smath{u}
of \smath{sli}, concatenating the results.
See \spadtype{PartitionsAndPermutations}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{shuffle}}\opLeftPren{}
{\it listOfIntegers}, \allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{2}{(List(Integer), List(Integer))->Stream(List(Integer))}
{PartitionsAndPermutations}
{\smath{\mbox{\bf shuffle}\opLeftPren{}l1, 
\allowbreak{} l2\opRightPren{}} forms the stream
of all shuffles of \smath{l1} and \smath{l2}, that is, 
all sequences that can
be formed from merging \smath{l1} and \smath{l2}.
See \spadtype{PartitionsAndPermutations}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sign}}\opLeftPren{}
{\it various\opt{, \ldots}}\opRightPren{}%
}%
}%
{4}{(Fraction(Polynomial(R)), Symbol, 
Fraction(Polynomial(R)), String)->Union(Integer, "failed")}
{RationalFunctionSign}
{\smath{\mbox{\bf sign}\opLeftPren{}x\opRightPren{}}, 
where \smath{x} is an element of an ordered ring,
returns 1 if \smath{x} is positive, \smath{-1} 
if \smath{x} is negative, 0 if \smath{x} equals 0.
\newitem
\smath{\mbox{\bf sign}\opLeftPren{}p\opRightPren{}}, 
where \smath{p} is a permutation, returns
\smath{1}, if \smath{p} is an even permutation, or \smath{-1}, if it is odd.
\newitem
\smath{\mbox{\bf sign}\opLeftPren{}f, \allowbreak{} x, 
\allowbreak{} a, \allowbreak{} s\opRightPren{}} returns 
the sign of rational function \smath{f} as
symbol \smath{x} nears \smath{a},
a real value represented by either a rational function or one of the
values {\tt \%plusInfinity}
or {\tt \%minusInfinity}.
If \smath{s} is:
\begin{simpleList}
\item the string {\tt "left"}: from the left (below).
\item the string {\tt "right}: from the right (above).
\item not given: from both sides if \smath{a} is finite.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{simplify}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf simplify}\opLeftPren{}f\opRightPren{}} 
performs the following simplifications on \smath{f:}
\begin{simpleList}
\item rewrites trigs and hyperbolic trigs in terms of \smath{sin},
\smath{cos}, \smath{sinh}, \smath{cosh}.
\item rewrites \smath{sin^2} and \smath{sinh^2} in terms of 
\smath{cos} and \smath{cosh}.
\item rewrites \smath{e^a e^b} as \smath{e^{a+b}}.
\end{simpleList}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{simplifyExp}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf simplifyExp}\opLeftPren{}f\opRightPren{}} 
converts every product \smath{e^a
e^b} appearing in \smath{f} into \smath{e^{a+b}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{simpson}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  threeIntegers}
\opRightPren{}%
\optand \mbox{\axiomFun{simpsonClosed}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  twoIntegers}\opRightPren{}%
\opand \mbox{\axiomFun{simpsonOpen}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  twoIntegers}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf simpson}\opLeftPren{}fn, \allowbreak{} a, 
\allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, 
\allowbreak{} nmax, \allowbreak{} nint\opRightPren{}} uses the
adaptive simpson method to numerically integrate function \smath{fn}
over the closed interval from \smath{a} to \smath{b}, with relative
accuracy \smath{epsrel} and absolute accuracy \smath{epsabs};
the refinement levels for the checking of convergence
vary from \smath{nmin} to \smath{nmax}.
The method is called ``adaptive'' since it requires an additional
parameter \smath{nint} giving the number of subintervals over which
the integrator independently applies the convergence criteria using
\smath{nmin} and \smath{nmax}.
This is useful when a large number of points are needed only
in a small fraction of the entire interval.
Parameter \smath{fn} is a function of type \spadsig{Float}{Float};
\smath{a}, \smath{b}, \smath{epsrel}, and \smath{epsabs} are floats;
\smath{nmin}, \smath{nmax}, and \smath{nint} are integers.
The operation returns a record containing:
{\tt value}, an estimate of the integral;
{\tt error}, an estimate of the error in the computation;
{\tt totalpts}, the total integral number of
function evaluations, and
{\tt success}, a boolean value which is \smath{true} if
the integral was computed within the user specified error criterion.
See \spadtype{NumericalQuadrature} for details.
\bigitem\smath{\mbox{\bf simpsonClosed}\opLeftPren{}fn, 
\allowbreak{} a, \allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, \allowbreak{} nmax\opRightPren{}} similarly uses
the Simpson method to numerically integrate function \smath{fn}
\index{Simpson's method}
over the closed interval \smath{a} to \smath{b},
but is not adaptive.
\bigitem\smath{\mbox{\bf simpsonOpen}\opLeftPren{}fn, 
\allowbreak{} a, \allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, \allowbreak{} nmax\opRightPren{}} is similar
to \spadfun{simpsonClosed}, except that it
integrates function \smath{fn} over
the open interval from \smath{a} to \smath{b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sin}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float}, 
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem
\smath{\mbox{\bf sin}\opLeftPren{}x\opRightPren{}} returns 
the sine of \smath{x} if possible, and
calls \spadfun{error} otherwise.
\newitem
\smath{\mbox{\bf sinIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf sin}\opLeftPren{}x\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sin2csc}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf sin2csc}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\mbox{\bf sin}\opLeftPren{}u\opRightPren{}} 
appearing in \smath{f} into \smath{1/{\rm csc}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{singular?}}\opLeftPren{}
{\it polynomialOrFunctionField}\opRightPren{}%
 \opand \mbox{\axiomFun{singularAtInfinity?}}\opLeftPren{}\opRightPren{}%
}%
}%
{1}{(F)->Boolean}{FunctionFieldCategory}
{\smath{\mbox{\bf singular?}\opLeftPren{}p\opRightPren{}} 
tests whether \smath{p(x) = 0} is singular.
\newitem
\smath{\mbox{\bf singular?}\opLeftPren{}a\opRightPren{}\$F} 
tests if \smath{x = a} is a singularity of the
algebraic function field \smath{F} (a domain of 
\spadtype{FunctionFieldCategory}).
\newitem
\smath{\mbox{\bf singularAtInfinity?}\opLeftPren{}\opRightPren{}\$F} 
tests if the
algebraic function field \smath{F} has a singularity at infinity.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sinh}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{sinhIfCan}}\opLeftPren{}{\it expression}
\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float}, 
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem
\smath{\mbox{\bf sinh}\opLeftPren{}x\opRightPren{}} returns the 
hyperbolic sine of \smath{x} if possible,
and calls \spadfun{error} otherwise.
\newitem
\smath{\mbox{\bf sinhIfCan}\opLeftPren{}x\opRightPren{}} returns 
\smath{\mbox{\bf sinh}\opLeftPren{}x\opRightPren{}} if possible, and 
\mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sinh2csch}}\opLeftPren{}{\it expression}
\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf sinh2csch}\opLeftPren{}f\opRightPren{}} converts 
every \smath{\mbox{\bf sinh}\opLeftPren{}u\opRightPren{}} appearing in 
\smath{f} into \smath{1/{\rm csch}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{size}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->NonNegativeInteger}{Finite}
{\smath{\mbox{\bf size}\opLeftPren{}\opRightPren{}\$F} returns the 
number of elements in the domain of
category \spadtype{Finite}. By definition, each such domain must have
a finite number of elements.
\seeAlso{\spadtype{FreeAbelianMonoidCategory}}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{size?}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->Boolean}{Aggregate}
{\smath{\mbox{\bf size?}\opLeftPren{}a, \allowbreak{} n\opRightPren{}} 
tests if aggregate \smath{a} has exactly \smath{n} elements.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sizeLess?}}\opLeftPren{}{\it element}, 
\allowbreak{}{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{EuclideanDomain}
{\smath{\mbox{\bf sizeLess?}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
tests whether \smath{x} is strictly smaller than \smath{y} with respect 
to the \spadfunFrom{euclideanSize}{EuclideanDomain}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sizeMultiplication}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->NonNegativeInteger}{FiniteFieldNormalBasis}
{\smath{\mbox{\bf sizeMultiplication}\opLeftPren{}\opRightPren{}\$F} 
returns the number of entries in the
multiplication table of the field.
Note: The time of multiplication of field elements depends on this size.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{skewSFunction}}\opLeftPren{}{\it listOfIntegers}, 
\allowbreak{}{\it  listOfIntegers}\opRightPren{}%
}%
}%
{(L I, L I) -> SPOL RN}{}{}
{\smath{\mbox{\bf skewSFunction}\opLeftPren{}li_1, \allowbreak{} li_2
\opRightPren{}} is the S-function
of the partition difference \smath{li_1 - li_2},
expressed in terms of power sum symmetric functions.
See \spadtype{CycleIndicators} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{solve}}\opLeftPren{}{\it u}, \allowbreak{}
{\it  v}\allowbreak $\,[$ , \allowbreak{}{\it  w}$]$\opRightPren{}%
}%
}%
{1}{(Equation(Expression(R)))->List(Equation(Expression(R)))}
{TransSolvePackage}
{\bigopkey{\smath{eq} denotes an equation to be solved; alternatively,
an expression \smath{u} may be given for \smath{eq} in which case the
equation \smath{eq} is defined as \smath{u=0}.
\largerbreak\smath{leq} denotes a list \smath{[ eq_1\ldots eq_n]} of 
equations; alternatively,
a list of expressions \smath{[ u_1\ldots u_n]}
may be given for \smath{leq} in which case the equations \smath{eq_i} are
defined by \smath{u_i=0}.
\largerbreak\smath{epsilon} is either a rational number or a float.
}
\bigitem\smath{\mbox{\bf complexSolve}\opLeftPren{}eq, \allowbreak{} 
epsilon\opRightPren{}} finds all the real solutions
to precision \smath{epsilon}
of the univariate equation \smath{eq} of rational functions with
respect to the unique variable appearing in \smath{eq}.
The complex solutions are either expressed
as rational numbers or floats depending on the type of \smath{epsilon}.
\bigitem\smath{\mbox{\bf complexSolve}\opLeftPren{}[ eq_1\ldots eq_n], 
epsilon\opRightPren{}}
computes the real solutions to precision \smath{epsilon} of a system of
equations \smath{eq_i} involving rational functions.
The complex solutions are either expressed
as rational numbers or floats depending on the type of \smath{epsilon}.
\bigitem\smath{\mbox{\bf radicalSolve}\opLeftPren{}eq\optinner{, x}
\opRightPren{}} finds solutions expressed in terms of
radicals of the equation
\smath{eq} involving rational functions.
Solutions will be found with respect to a \spadtype{Symbol}
given as a second argument to the operation.
This second argument may be omitted when
\smath{eq} contains a unique symbol.
\bigitem\smath{\mbox{\bf radicalSolve}\opLeftPren{}leq{, lv}\opRightPren{}} 
finds solutions
expressed in terms of radicals of the system
of equations \smath{leq} involving rational functions.
Solutions are found with respect to a list \smath{lv} of \spadtype{Symbol}s,
or with respect to all variables appearing in the equations,
if no second argument is given.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}eq\optinner{, x}\opRightPren{}} 
finds exact symbolic solutions to equation
\smath{eq} involving either
rational functions or expressions of type \spadtype{Expression(R)}.
Solutions will be found with respect to a \spadtype{Symbol}
given as a second argument to the operation.
The second argument may be omitted when
\smath{eq} contains a unique symbol.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}leq{, lv}\opRightPren{}} 
finds exact solutions
to a system of equations \smath{leq} involving rational functions 
or expressions
of type \smath{\mbox{\bf Expression}\opLeftPren{}R\opRightPren{}}.
Solutions are found with respect to a list of \smath{lv} of 
\spadtype{Symbol}s,
or with respect to all variables appearing in the equations
if no second argument is given.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}eq, \allowbreak{} 
epsilon\opRightPren{}} finds all the real solutions
to precision \smath{epsilon}
of the univariate equation \smath{eq} of rational functions with
respect to the unique variable appearing in \smath{eq}.
The real solutions are either expressed
as rational numbers or floats depending on the type of \smath{epsilon}.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}[ eq_1\ldots eq_n], 
epsilon\opRightPren{}}
computes the real solutions to precision \smath{epsilon} of a system of
equations \smath{eq_i} involving rational functions.
The real solutions are either expressed
as rational numbers or floats depending on the type of \smath{epsilon}.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}M, 
\allowbreak{} v\opRightPren{}}, where \smath{M} is a matrix and
\smath{v} is a \spadtype{Vector} of coefficients, finds a particular
solution of the system \smath{Mx=v} and a basis of the associated 
homogeneous system
\smath{MX=0}.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}eq, \allowbreak{} y, 
\allowbreak{} x=a, \allowbreak{} [ y_0\ldots y_m]\opRightPren{}} returns either
the solution of the initial value problem \smath{eq},
\smath{y(a) = y_0}, \smath{y'(a)=a_1}, \smath{\ldots} or
\mbox{\tt "failed"} if no solution can be found.
Note: an error occurs if the equation \smath{eq} is not a linear
ordinary equation or of the form \smath{dy/dx = f(x, y)}.
\bigitem\smath{\mbox{\bf solve}\opLeftPren{}eq, \allowbreak{} y, 
\allowbreak{} x\opRightPren{}} returns either a solution of the
ordinary diffential equation \smath{eq} or \mbox{\tt "failed"} if no
non-trivial solution can be found. If \smath{eq} is a linear ordinary
differential equation, a solution is of the form
\smath{[ h, [ b_1, \ldots, ]]} where \smath{h}
is a particular solution and \smath{[ b_1, \ldots, b_m]} are
linearly independent solutions of the associated homogeneous equation
\smath{f(x, y) = 0}. The value returned is a basis for the solution
of the homogeneous equation which are found (note: this is not
always a full basis).
\bigitem See also
\spadfun{dioSolve},
\spadfun{contractSolve},
\spadfun{polSolve},
\spadfun{seriesSolve},
\spadfun{linSolve}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{solveLinearlyOverQ}}\opLeftPren{}
{\it vector}\opRightPren{}%
}%
}%
{2}{(Vector(R), R)->Union(Vector(Fraction(Integer)), "failed")}
{IntegerLinearDependence}
{\smath{\mbox{\bf solveLinearlyOverQ}\opLeftPren{}[v_1, 
\allowbreak{} \ldots, v_n], u\opRightPren{}} 
returns \smath{[c_1, \ldots, c_n]} such that
\smath{c_1v_1 + \cdots + c_n v_n = u}, or \mbox{\tt "failed"} if no such
rational numbers \smath{c_i} exist.
The elements of the \smath{v_i} and \smath{u} can
be from any extension ring with an explicit linear
dependence test, for example,
expressions, complex values, polynomials, rational functions, or exact numbers.
See \spadtype{LinearExplicitRingOver}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{solveLinearPolynomialEquation}}\opLeftPren{}
{\it listOfPolys}, \allowbreak{}{\it  poly}\opRightPren{}%
}%
}%
{2}{(List(SparseUnivariatePolynomial(\$)), 
SparseUnivariatePolynomial(\$))->Union(List(SparseUnivariatePolynomial(\$)),
 "failed")}
{PolynomialFactorizationExplicit}
{\smath{\mbox{\bf solveLinearPolynomialEquation}\opLeftPren{}
[f_1, \allowbreak{} \ldots, f_n], g\opRightPren{}},
where \smath{g} is a polynomial and the \smath{f_i} 
are polynomials relatively prime to
one another,
returns a list of polynomials \smath{a_i} such that 
\smath{g/{\prod_i{f_i}} = \sum_i{ai/fi}},
or \mbox{\tt "failed"} if no such list of \smath{a_i}'s exists.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sort}}\opLeftPren{}{\it 
\optinit{predicate, }aggregate}\opRightPren{}%
 \opand \mbox{\axiomFun{sort!}}\opLeftPren{}{\it 
\optinit{predicate, }aggregate}\opRightPren{}%
}%
}%
{2}{((S, S)->Boolean, \$)->\$}{FiniteLinearAggregate}
{\smath{\mbox{\bf sort}\opLeftPren{}\optfirst{p, }a\opRightPren{}} 
returns a copy of
\smath{a} sorted using total ordering predicate \smath{p}.
\newitem
\smath{\mbox{\bf sort!}\opLeftPren{}\optfirst{p, }u\opRightPren{}} 
returns \smath{u} destructively changed with its
elements ordered by comparison function \smath{p}.
\newitem
By default, \smath{p} is the operation \smath{\leq}.
Thus both \smath{\mbox{\bf sort}\opLeftPren{}u\opRightPren{}} and 
\smath{\mbox{\bf sort!}\opLeftPren{}u\opRightPren{}} returns \smath{u} with
its elements in ascending order.
\newitem
Also: \smath{\mbox{\bf sort}\opLeftPren{}lp\opRightPren{}} 
sorts a list of permutations {\it lp}
according to cycle structure, first according to the length of cycles,
second, if \smath{S} has \spadtype{Finite} or \smath{S} has 
\spadtype{OrderedSet},
according to lexicographical order of entries in cycles of equal length.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{spherical}}\opLeftPren{}{\it point}\opRightPren{}%
}%
}%
{1}{(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf spherical}\opLeftPren{}pt\opRightPren{}} 
transforms point \smath{pt} from spherical coordinates to
Cartesian coordinates, mapping \smath{(r, \theta, \phi)} to
\smath{x = r \sin(\phi) \cos(\theta)}, \smath{y = r \sin(\phi)
\sin(\theta)}, \smath{z = r \cos(\phi)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{split}}\opLeftPren{}{\it element}, \allowbreak{}
{\it  binarySearchTree}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf split}\opLeftPren{}x, \allowbreak{} t\opRightPren{}} 
splits binary search tree \smath{t} into two components, returning a
record of two components:
\smath{less}, a binary search tree whose components are all
less than x; and,
\smath{greater}, a binary search tree with all the rest of the 
components of \spad{t}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{split!}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, Integer)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf split!}\opLeftPren{}u, 
\allowbreak{} n\opRightPren{}} splits \smath{u} into two aggregates:
the first consisting of \smath{v}, the first \smath{n}
elements of \smath{u}, and \smath{w} consisting of all the rest.
The value of \smath{w} is returned.
Thus \smath{v = {\bf first}(u, n)} and \smath{w := {\bf rest}(u, n)}.
Note: afterwards \smath{\mbox{\bf rest}\opLeftPren{}u, 
\allowbreak{} n\opRightPren{}} returns 
\smath{\mbox{\bf empty}\opLeftPren{}\opRightPren{}}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{splitDenominator}}\opLeftPren{}
{\it listOfFractions}\opRightPren{}%
}%
}%
{1}{(A)->Record(num:A, den:R)}{CommonDenominator}
{\smath{\mbox{\bf splitDenominator}\opLeftPren{}u\opRightPren{}},
where \smath{u} is a list of fractions
\smath{[q_1, \ldots, q_n]}, returns \smath{[[p_1, \ldots, p_n], d]} such that
\smath{q_i = p_i/d} and \smath{d} is a common denominator 
for the \smath{q_i}'s.
Similarly, the function is defined for a matrix (respectively, a polynomial)
\smath{u} in which case the \smath{q_i} are the elements of 
(respectively, the coefficients of)
\smath{u}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sqfrFactor}}\opLeftPren{}
{\it element}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(R, Integer)->\$}{Factored}
{\smath{\mbox{\bf sqfrFactor}\opLeftPren{}base, 
\allowbreak{} exponent\opRightPren{}} creates a factored object with
a single factor whose \smath{base} is asserted to be square-free
(flag = {\tt "sqfr"}).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sqrt}}\opLeftPren{}
{\it expression\opt{, option}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{RadicalCategory}
{\smath{\mbox{\bf sqrt}\opLeftPren{}x\opRightPren{}} 
returns the square root of \smath{x}.
\newitem
\smath{\mbox{\bf sqrt}\opLeftPren{}x, \allowbreak{} y\opRightPren{}}, 
where \smath{x} and
\smath{y} are \smath{p}-adic integers, returns a square root of \smath{x} where
argument \smath{y} is a square root of \smath{x \mod p}.
See also \spadtype{PAdicIntegerCategory}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{square?}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{MatrixCategory}
{\smath{\mbox{\bf square?}\opLeftPren{}m\opRightPren{}} 
tests if \smath{m} is a square matrix.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{squareFree}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Factored(\$)}{UniqueFactorizationDomain}
{\smath{\mbox{\bf squareFree}\opLeftPren{}x\opRightPren{}} 
returns the square-free factorization of \smath{x},
that is, such that the factors are pairwise relatively 
prime and each has multiple prime factors.
Argument \smath{x} can be a member of any domain of
category \spadtype{UniqueFactorizationDomain} such as a polynomial or integer.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{squareFreePart}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{PolynomialCategory}
{\smath{\mbox{\bf squareFreePart}\opLeftPren{}p\opRightPren{}} 
returns product of all the prime factors of
\smath{p} each taken with multiplicity one.
Argument \smath{p} can be a member of any domain of
category \spadtype{UniqueFactorizationDomain} such as a polynomial or integer.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{squareFreePolynomial}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(SparseUnivariatePolynomial(\$))->
Factored(SparseUnivariatePolynomial(\$))}{PolynomialFactorizationExplicit}
{\smath{\mbox{\bf squareFreePolynomial}\opLeftPren{}p\opRightPren{}} 
returns the square-free factorization of the univariate polynomial \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{squareTop}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{MatrixCategory}
{\smath{\mbox{\bf squareTop}\opLeftPren{}A\opRightPren{}} 
returns an \smath{n}-by-\smath{n} matrix
consisting of the first \smath{n} rows of the
\smath{m}-by-\smath{n} matrix \smath{A}.
The operation calls \spadfun{error} if \smath{m < n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{stack}}\opLeftPren{}{\it list}\opRightPren{}%
}%
}%
{1}{(List(S))->\$}{StackAggregate}
{\smath{\mbox{\bf stack}\opLeftPren{}[x, \allowbreak{} y, 
\allowbreak{} \ldots, z]\opRightPren{}} creates a stack with first (top)
element \smath{x}, second element \smath{y}, \ldots, and last
element \smath{z}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{standardBasisOfCyclicSubmodule}}\opLeftPren{}
{\it listOfMatrices}, \allowbreak{}{\it  vector}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), Vector(R))->Matrix(R)}{RepresentationPackage2}
{\smath{\mbox{\bf standardBasisOfCyclicSubmodule}
\opLeftPren{}lm, \allowbreak{} v\opRightPren{}} returns a matrix
representation of cyclic submodule over a ring \smath{R}, where
\smath{lm} is a list of matrices and \smath{v} is a vector,
such that the non-zero column vectors are an \smath{R}-basis
for \smath{A v}.
\seeType{RepresentationPackage2}
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{stirling1}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
 \opand \mbox{\axiomFun{stirling2}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(I, I)->I}{IntegerCombinatoricFunctions}
{\smath{\mbox{\bf stirling1}\opLeftPren{}n, \allowbreak{} m\opRightPren{}} 
returns the Stirling number of the first kind.
\newitem
\smath{\mbox{\bf stirling2}\opLeftPren{}n, \allowbreak{} m\opRightPren{}} 
returns the Stirling number of the second kind.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{string?}}\opLeftPren{}{\it various}\opRightPren{}%
 \opand \mbox{\axiomFun{string}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}
{\smath{\mbox{\bf string?}\opLeftPren{}s\opRightPren{}} 
tests if \spadtype{SExpression} object \smath{s} is a string.
\newitem
\smath{\mbox{\bf string}\opLeftPren{}s\opRightPren{}} 
converts the symbol \smath{s} to a string.
An \spadfun{error} is called if the symbol is subscripted.
\newitem
\smath{\mbox{\bf string}\opLeftPren{}s\opRightPren{}} 
returns \spadtype{SExpression} object \smath{s} as
an element of \spadtype{String} if possible,
and otherwise calls \spadfun{error}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{strongGenerators}}\opLeftPren{}
{\it listOfPermutations}\opRightPren{}%
}%
}%
{1}{(\$)->List(Permutation(S))}{PermutationGroup}
{\smath{\mbox{\bf strongGenerators}\opLeftPren{}gp\opRightPren{}} 
returns strong generators for the permutation
group {\it gp}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{structuralConstants}}\opLeftPren{}
{\it basis}\opRightPren{}%
}%
}%
{0}{()->Vector(Matrix(R))}{FramedNonAssociativeAlgebra}
{\smath{\mbox{\bf structuralConstants}\opLeftPren{}basis\opRightPren{}} 
calculates the structural constants
\smath{[(\gamma_{i, j, k}) {\ \tt for\ }  k {\ \tt in\ } 1..rank()\$R]}
of a domain \smath{R} of category 
\spadtype{FramedNonAssociativeAlgebra} over a ring \smath{R},
defined by:
\smath{v_i  v_j = \gamma_{i, j, 1}  v_1 + \cdots + \gamma_{i, j, n}  v_n},
where \smath{v_1}, \ldots, \smath{v_n} is the fixed \smath{R}-module basis.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{style}}\opLeftPren{}{\it string}\opRightPren{}%
}%
}%
{1}{(String)->\$}{DrawOption}
{\smath{\mbox{\bf style}\opLeftPren{}s\opRightPren{}} 
specifies the drawing style in which the graph
will be plotted by the indicated string \smath{s}.
This option is expressed in the form \code{style == s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sub}}\opLeftPren{}{\it outputForm}, \allowbreak{}
{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf sub}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of type
\spadtype{OutputForm} (normally unexposed),
creates an output form for \smath{o_1} subscripted by \smath{o_2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subMatrix}}\opLeftPren{}{\it matrix}, \allowbreak{}
{\it  integer}, \allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}, 
\allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{5}{(\$, Integer, Integer, Integer, Integer)->\$}{MatrixCategory}
{\smath{\mbox{\bf subMatrix}\opLeftPren{}m, \allowbreak{} i_1, 
\allowbreak{} i_2, \allowbreak{} j_1, \allowbreak{} j_2\opRightPren{}} 
extracts the submatrix \smath{[m(i, j)]} where the index
\smath{i} ranges from \smath{i_1} to \smath{i_2} and
the index \smath{j} ranges from \smath{j_1} to \smath{j_2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{submod}}\opLeftPren{}{\it integerNumber}, 
\allowbreak{}{\it  integerNumber}, \allowbreak{}
{\it  integerNumber}\opRightPren{}%
}%
}%
{3}{(\$, \$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf submod}\opLeftPren{}a, \allowbreak{} b, 
\allowbreak{} p\opRightPren{}}, where \smath{0 \leq a < b < p > 1}, returns 
\smath{a-b\mod p},
for integer numbers \smath{a}, \smath{b} and \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subResultantGcd}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  polynomial}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf subResultantGcd}\opLeftPren{}p, 
\allowbreak{} q\opRightPren{}} computes the \smath{gcd} of the polynomials 
\smath{p} and \smath{q} using the SubResultant \smath{GCD} algorithm.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subscript}}\opLeftPren{}{\it symbol}, 
\allowbreak{}{\it  listOfOutputForms}\opRightPren{}%
}%
}%
{2}{(\$, List(OutputForm))->\$}{Symbol}
{\smath{\mbox{\bf subscript}\opLeftPren{}s, \allowbreak{} 
[a1, \allowbreak{} \ldots, an]\opRightPren{}} returns symbol \smath{s} 
subscripted by output forms
\smath{a_1, \ldots, a_n} as a symbol.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subset}}\opLeftPren{}{\it integer}, 
\allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(Integer, Integer, Integer)->List(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf subSet}\opLeftPren{}n, \allowbreak{} m, 
\allowbreak{} k\opRightPren{}} calculates the \eth{\smath{k}} \smath{m}-subset 
of the set
\smath{0, 1, \ldots, (n-1)} in the lexicographic order 
considered as a decreasing map from
\smath{0, \ldots, (m-1)} into \smath{0, \ldots, (n-1)}.
See \spadtype{SymmetricGroupCombinatoricFunctions}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subset?}}\opLeftPren{}{\it set}, 
\allowbreak{}{\it  set}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{SetAggregate}
{\smath{\mbox{\bf subset?}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} tests if set \smath{u} 
is a subset of set \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subspace}}\opLeftPren{}
{\it threeSpace}\opRightPren{}%
}%
}%
{1}{(\$)->SubSpace(3, R)}{ThreeSpace}
{\smath{\mbox{\bf subspace}\opLeftPren{}s\opRightPren{}} 
returns the space component which holds all the point
information in the \spadtype{ThreeSpace} object \smath{s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{substring?}}\opLeftPren{}{\it string}, 
\allowbreak{}{\it  string}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, \$, Integer)->Boolean}{StringAggregate}
{\smath{\mbox{\bf substring?}\opLeftPren{}s, \allowbreak{} t, 
\allowbreak{} i\opRightPren{}} tests if \smath{s} is a substring of \smath{t}
beginning at index \smath{i}. Note: \code{substring?(s, t, 0) = prefix?(s, t)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{subst}}\opLeftPren{}{\it expression}, 
\allowbreak{}{\it  equations}\opRightPren{}%
}%
}%
{2}{(\$, Equation(\$))->\$}{ExpressionSpace}
{\smath{\mbox{\bf subst}\opLeftPren{}f, \allowbreak{} k = g\opRightPren{}} 
formally replaces the kernel \smath{k} by \smath{g} in \smath{f}.
\newitem
\smath{\mbox{\bf subst}\opLeftPren{}f, \allowbreak{} 
[k_1 = g_1, \allowbreak{} \ldots, k_n = g_n]\opRightPren{}} 
formally replaces the kernels
\smath{k_1}, \ldots, \smath{k_n} by \smath{g_1}, \ldots, 
\smath{g_n} in \smath{f}.
\newitem
\smath{\mbox{\bf subst}\opLeftPren{}f, \allowbreak{} [k_1, 
\allowbreak{} \ldots, k_n], [g_1, \ldots, g_n]\opRightPren{}} 
formally replaces kernels
\smath{k_i} by \smath{g_i} in \smath{f}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{suchThat}}\opLeftPren{}{\it symbol}, 
\allowbreak{}{\it  predicates}\opRightPren{}%
}%
}%
{2}{(Symbol, List((D)->Boolean))->Expression(Integer)}{AttachPredicates}
{\smath{\mbox{\bf suchThat}\opLeftPren{}sy, 
\allowbreak{} pred\opRightPren{}} attaches the
predicate \smath{pred} to symbol \smath{sy}.
Argument \smath{pred} may also be a list \smath{[p_1, \ldots, p_n]}
of predicates \smath{p_i}. In this case,
the predicate \smath{pred} attached to \smath{sy}
is \smath{p_1 \and \ldots \and p_n}.
\newitem
\smath{\mbox{\bf suchThat}\opLeftPren{}r, \allowbreak{} [a_1, 
\allowbreak{} \ldots, a_n], f\opRightPren{}} returns the rewrite rule 
\smath{r} with the
predicate \smath{f(a1, \ldots, an)} attached to it.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{suffix?}}\opLeftPren{}{\it string}, 
\allowbreak{}{\it  string}\opRightPren{}%
}%
}%
{2}{(\$, \$)->Boolean}{StringAggregate}
{\smath{\mbox{\bf suffix?}\opLeftPren{}s, 
\allowbreak{} t\opRightPren{}} tests if the string \smath{s} 
is the final substring of \smath{t}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sum}}\opLeftPren{}
{\it rationalFunction}, \allowbreak{}
{\it  symbolOrSegmentBinding}\opRightPren{}%
}%
}%
{2}{(Fraction(Polynomial(R)), 
Symbol)->Union(Fraction(Polynomial(R)), Expression(R))}{RationalFunctionSum}
{\smath{\mbox{\bf sum}\opLeftPren{}a(n), \allowbreak{} n\opRightPren{}},
where \smath{a(n)} is an rational function or expression involving
the symbol \smath{n},
returns the indefinite sum \smath{A} of \smath{a} with respect
to upward difference on \smath{n}, that is, 
\smath{A(n+1) - A(n) = a(n)}.
\newitem
\smath{\mbox{\bf sum}\opLeftPren{}f(n), 
\allowbreak{} n = a..b\opRightPren{}}, where
\smath{f(n)}, \smath{a}, and \smath{b} are rational functions (or polynomials),
computes and returns the sum \smath{f(a) + f(a+1) + \cdots + f(b)} 
as a rational function
(or polynomial).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{summation}}\opLeftPren{}
{\it expression}, \allowbreak{}{\it  segmentBinding}\opRightPren{}%
}%
}%
{2}{(\$, SegmentBinding(\$))->\$}{CombinatorialOpsCategory}
{\smath{\mbox{\bf summation}\opLeftPren{}f, 
\allowbreak{} n = a..b\opRightPren{}} returns the formal sum 
\smath{\sum_{n=a}^b f(n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sumOfDivisors}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf sumOfDivisors}\opLeftPren{}n\opRightPren{}} 
returns the sum of the integers between 1 and
integer \smath{n} (inclusive) which divide \smath{n}.
This sum is often denoted in the literature by \smath{\sigma(n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sumOfKthPowerDivisors}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(Integer, NonNegativeInteger)->Integer}{IntegerNumberTheoryFunctions}
{\smath{\mbox{\bf sumOfKthPowerDivisors}\opLeftPren{}n, 
\allowbreak{} k\opRightPren{}} returns the sum of the
\eth{\smath{k}} powers of the integers between 1 and \smath{n} (inclusive) 
which divide \smath{n}.
This sum is often denoted in the literature by \smath{\sigma_k(n)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sumSquares}}\opLeftPren{}{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->List(Integer)}{GaussianFactorizationPackage}
{\smath{\mbox{\bf sumSquares}\opLeftPren{}p\opRightPren{}} returns the 
list \smath{[a, b]} such that
\smath{a^2+b^2} is equal to the integer prime \smath{p}, and
calls \spadfun{error} if this is not possible.
It will succeed if \smath{p} is 2 or congruent to \smath{1 \mod 4}.
}



% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{sup}}\opLeftPren{}{\it element}, \allowbreak{}
{\it  element}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{OrderedAbelianMonoidSup}
{\smath{\mbox{\bf sup}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
returns the least element from which both \smath{x} and \smath{y} can 
be subtracted.
The purpose of \spadfun{sup} is to act as a supremum with
respect to the partial order imposed by the \smath{-} operation on the domain.
See \spadtype{OrderedAbelianMonoidSup} for details.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{super}}\opLeftPren{}{\it outputForm}, 
\allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf super}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of type 
\spadtype{OutputForm} (normally unexposed),
creates an output form for \smath{o_1} superscripted by \smath{o_2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{superscript}}\opLeftPren{}{\it symbol}, 
\allowbreak{}{\it  listOfOutputForms}\opRightPren{}%
}%
}%
{2}{(\$, List(OutputForm))->\$}{Symbol}
{\smath{\mbox{\bf superscript}\opLeftPren{}s, \allowbreak{} [a_1, 
\allowbreak{} \ldots, a_n]\opRightPren{}} returns symbol \smath{s} 
superscripted by
output forms \smath{[a_1, \ldots, a_n]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{supersub}}\opLeftPren{}{\it outputForm}, 
\allowbreak{}{\it  listOfOutputForms}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf supersub}\opLeftPren{}o, \allowbreak{} lo\opRightPren{}},
where \smath{o} is an object of type \spadtype{OutputForm}
(normally unexposed)
and \smath{lo} is a list of output forms of the form
\smath{[sub_1, super_1, sub_2, super_2, \ldots, sub_n, super_n]}
creates an output form with each subscript aligned under each superscript.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{surface}}\opLeftPren{}{\it function}, 
\allowbreak{}{\it  function}, \allowbreak{}{\it  function}\opRightPren{}%
}%
}%
{3}{(ComponentFunction, ComponentFunction, ComponentFunction)->\$}
{ParametricSurface}
{\smath{\mbox{\bf surface}\opLeftPren{}c_1, \allowbreak{} c_2, 
\allowbreak{} c_3\opRightPren{}} creates a surface from three 
parametric component functions
\smath{c_1}, \smath{c_2}, and \smath{c_3}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{swap!}}\opLeftPren{}{\it aggregate}, 
\allowbreak{}{\it  index}, \allowbreak{}{\it  index}\opRightPren{}%
}%
}%
{3}{(\$, Index, Index)->Void}{IndexedAggregate}
{\smath{\mbox{\bf swap!}\opLeftPren{}u, \allowbreak{} i, 
\allowbreak{} j\opRightPren{}} interchanges elements \smath{i} and \smath{j} 
of aggregate \smath{u}. No meaningful value is returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{swapColumns!}}\opLeftPren{}{\it matrix}, 
\allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, Integer, Integer)->\$}{MatrixCategory}
{\smath{\mbox{\bf swapColumns!}\opLeftPren{}m, \allowbreak{} i, 
\allowbreak{} j\opRightPren{}} interchanges the \eth{\smath{i}} and 
\eth{\smath{j}} columns of \smath{m}
returning \smath{m} which is destructively altered.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{swapRows!}}\opLeftPren{}{\it matrix}, 
\allowbreak{}{\it  integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{3}{(\$, Integer, Integer)->\$}{MatrixCategory}
{\smath{\mbox{\bf swapRows!}\opLeftPren{}m, \allowbreak{} i, 
\allowbreak{} j\opRightPren{}} interchanges the \eth{\smath{i}} and 
\eth{\smath{j}} rows of \smath{m},
returning \smath{m} which is destructively altered.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symbol?}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{SExpressionCategory}
{\smath{\mbox{\bf symbol?}\opLeftPren{}s\opRightPren{}} 
tests if \spadtype{SExpression} object \smath{s}
is a symbol.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symbol}}\opLeftPren{}{\it sExpression}\opRightPren{}%
}%
}%
{1}{(\$)->Sym}{SExpressionCategory}
{\smath{\mbox{\bf symbol}\opLeftPren{}s\opRightPren{}} 
returns \smath{s} as an element of type \spadtype{Symbol},
or calls \spadfun{error} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symmetric?}}\opLeftPren{}{\it matrix}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{MatrixCategory}
{\smath{\mbox{\bf symmetric?}\opLeftPren{}m\opRightPren{}} tests 
if the matrix \smath{m} is square and symmetric,
that is, if each \smath{m(i, j) = m(j, i)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symmetricDifference}}\opLeftPren{}{\it set}, 
\allowbreak{}{\it  set}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{SetAggregate}
{\smath{\mbox{\bf symmetricDifference}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} returns the set aggregate of
elements \smath{x} which are members of set aggregate \smath{u} or
set aggregate \smath{v} but not both.
If \smath{u} and \smath{v} have no elements in common,
\smath{\mbox{\bf symmetricDifference}\opLeftPren{}u, 
\allowbreak{} v\opRightPren{}} returns a copy of \smath{u}.
Note: \smath{symmetricDifference(u, v) = {\bf union}({\bf
difference}(u, v), {\bf difference}(v, u))}
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symmetricGroup}}\opLeftPren{}
{\it integers}\opRightPren{}%
}%
}%
{1}{(List(Integer))->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf symmetricGroup}\opLeftPren{}n\opRightPren{}} 
constructs the symmetric group \smath{S_n} acting on the
integers 1, \ldots, \smath{n}.
The generators are the \smath{n}-cycle \smath{(1, \ldots, n)} 
and the 2-cycle \smath{(1, 2)}.
\newitem
\smath{\mbox{\bf symmetricGroup}\opLeftPren{}li\opRightPren{}}, 
where \smath{li} is a list of integers,
constructs the symmetric group acting on the
integers in the list \smath{li}.
The generators are the cycle given by \smath{li} and
the 2-cycle \smath{(li(1), li(2))}.
Duplicates in the list will be removed.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symmetricRemainder}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{IntegerNumberSystem}
{\smath{\mbox{\bf symmetricRemainder}\opLeftPren{}a, 
\allowbreak{} b\opRightPren{}}, where \smath{b > 1}, yields
\smath{r} where \smath{ -b/2 \leq r < b/2}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{symmetricTensors}}\opLeftPren{}
{\it matrices}, \allowbreak{}{\it  positiveInteger}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), PositiveInteger)->List(Matrix(R))}
{RepresentationPackage1}
{\smath{\mbox{\bf symmetricTensors}\opLeftPren{}la, 
\allowbreak{} n\opRightPren{}}, where \smath{la} is a list
\smath{[a_1, \ldots, a_k]} of \smath{m}-by-\smath{m} square
matrices, applies to each matrix \smath{a_i}, the irreducible,
polynomial representation of the general linear group \smath{GL_m}
corresponding to the partition \smath{(n, 0, \ldots, 0)} of
\smath{n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{systemCommand}}\opLeftPren{}
{\it string}\opRightPren{}%
}%
}%
{1}{(String)->Void}{MoreSystemCommands}
{\smath{\mbox{\bf systemCommand}\opLeftPren{}cmd\opRightPren{}} 
takes the string \smath{cmd} and
passes it to the runtime environment for execution as a system
command.
Although various things may be printed, no usable value is
returned.
}
% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tableau}}\opLeftPren{}
{\it listOfListOfElements}\opRightPren{}%
}%
}%
{1}{(List(List(S)))->\$}{Tableau}
{\smath{\mbox{\bf tableau}\opLeftPren{}ll\opRightPren{}} converts a 
list of lists \smath{ll} to an object
of type \spadtype{Tableau}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tableForDiscreteLogarithm}}\opLeftPren{}
{\it integer}\opRightPren{}%
}%
}%
{1}{(Integer)->Table(PositiveInteger, NonNegativeInteger)}{FiniteFieldCategory}
{\smath{\mbox{\bf tableForDiscreteLogarithm}\opLeftPren{}n\opRightPren{}} 
returns a table of the
discrete logarithms of \smath{a^0} up to \smath{a^{n-1}} which,
when called with the key 
\smath{\mbox{\bf lookup}\opLeftPren{}a^i\opRightPren{}}, returns \smath{i} for
\smath{i} in \smath{0..n-1} for a finite field.
This operation calls \spadfun{error} if
not called for prime divisors of order of multiplicative group.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{table}}\opLeftPren{}
{\it \opt{listOfRecords}}\opRightPren{}%
}%
}%
{1}{(List(Record(key:Key, entry:Entry)))->\$}{TableAggregate}
{\smath{\mbox{\bf table}\opLeftPren{}[p_1, \allowbreak{} p_2, 
\allowbreak{} \ldots, p_n]\opRightPren{}} creates a table with keys of
type \smath{Key} and entries of type \smath{Entry}.
Each pair \smath{p_i} is a record with selectors \smath{key} and
\smath{entry} with values from the corresponding domains
\smath{Key} and \smath{Entry}.
\newitem
\smath{\mbox{\bf table}\opLeftPren{}\opRightPren{}\$T} 
creates a empty table of domain \smath{T}
of category \spadtype{TableAggregate}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tail}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf tail}\opLeftPren{}a\opRightPren{}} 
returns the last node of recursive aggregate \smath{a}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tan}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{tanIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float},
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem
\smath{\mbox{\bf tan}\opLeftPren{}x\opRightPren{}} 
returns the tangent of \smath{x}.
\newitem
\smath{\mbox{\bf tanIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf tan}\opLeftPren{}x\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tan2cot}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf tan2cot}\opLeftPren{}f\opRightPren{}} converts 
every \smath{\mbox{\bf tan}\opLeftPren{}u\opRightPren{}} appearing in 
\smath{f} into \smath{1/{\rm cot}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tan2trig}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf tan2trig}\opLeftPren{}f\opRightPren{}} converts 
every \smath{\mbox{\bf tan}\opLeftPren{}u\opRightPren{}} appearing in 
\smath{f} into \smath{\mbox{\bf sin}\opLeftPren{}u)/{\rm cos}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tanh}}\opLeftPren{}{\it expression}\opRightPren{}%
 \opand \mbox{\axiomFun{tanhIfCan}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(K)->Union(K, "failed")}{PartialTranscendentalFunctions}
{\opkey{Argument x can be a \spadtype{Complex}, \spadtype{Float}, 
\spadtype{DoubleFloat}, or
\spadtype{Expression} value or a series. }
\newitem
\smath{\mbox{\bf tanh}\opLeftPren{}x\opRightPren{}} 
returns the hyperbolic tangent of \smath{x}.
\newitem
\smath{\mbox{\bf tanhIfCan}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf tanh}\opLeftPren{}x\opRightPren{}} if possible, 
and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tanh2coth}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf tanh2coth}\opLeftPren{}f\opRightPren{}} 
converts every \smath{\mbox{\bf tanh}\opLeftPren{}u\opRightPren{}} 
appearing in \smath{f} into \smath{1/{\rm coth}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tanh2trigh}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TranscendentalManipulations}
{\smath{\mbox{\bf tanh2trigh}\opLeftPren{}f\opRightPren{}} converts 
every \smath{\mbox{\bf tanh}\opLeftPren{}u\opRightPren{}} appearing in 
\smath{f} into \smath{\mbox{\bf sinh}\opLeftPren{}u)/{\rm cosh}(u)}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{taylor}}\opLeftPren{}{\it various}, 
\allowbreak{}{\it  ..}\opRightPren{}%
}%
}%
{1}{(\$)->UTS}{UnivariateLaurentSeriesConstructorCategory}
{\smath{\mbox{\bf taylor}\opLeftPren{}u\opRightPren{}} 
converts the Laurent series \smath{u(x)} to a Taylor series  if possible,
and if not, calls \spadfun{error}.
\newitem
\smath{\mbox{\bf taylor}\opLeftPren{}f\opRightPren{}} 
converts the expression \smath{f} into a
Taylor expansion of the expression \smath{f}.
Note: \smath{f} must have only one variable.
\newitem
\smath{\mbox{\bf taylor}\opLeftPren{}sy\opRightPren{}}, 
where \smath{sy} is a symbol, returns \smath{sy} as a Taylor series.
\newitem
\smath{\mbox{\bf taylor}\opLeftPren{}n +-> a(n), 
\allowbreak{} x = a\opRightPren{}} returns \smath{\sum_{n = 0 \ldots}
a(n)(x-a)^n)}.
\newitem
\smath{\mbox{\bf taylor}\opLeftPren{}f, 
\allowbreak{} x = a\optinner{, n}\opRightPren{}} 
expands the expression \smath{f} as a
series in powers of \smath{(x - a)} with \smath{n} terms.
If \smath{n} is missing, the number of terms is governed by
the value set by the system command \spadsyscom{)set streams calculate}.
\newitem
\smath{\mbox{\bf taylor}\opLeftPren{}i +-> a(i), 
\allowbreak{} x = a, \allowbreak{} m..\optinner{n, k}\opRightPren{}} creates the
Taylor series
\smath{\sum\nolimits_{i = m..n {\ \tt by\ } k}{a(i) (x-a)^i}}.
Here \smath{m}, \smath{n} and \smath{k} are integers.
Upper-limit \smath{n} and stepsize \smath{k} are optional 
and have default values
\smath{n = \infty} and \smath{k = 1}.
\newitem
\smath{\mbox{\bf taylor}\opLeftPren{}a(i), \allowbreak{} i, 
\allowbreak{} x=a, \allowbreak{} m..\optinner{n, k}\opRightPren{}} returns
\smath{\sum\nolimits_{i = m..n {\bf by} k}{a(n) (x - a)^n}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{taylorIfCan}}\opLeftPren{}
{\it laurentSeries}\opRightPren{}%
}%
}%
{1}{(\$)->Union(UTS, "failed")}{UnivariateLaurentSeriesConstructorCategory}
{\smath{\mbox{\bf taylorIfCan}\opLeftPren{}f(x)\opRightPren{}} 
converts the Laurent series
\smath{f(x)} to a Taylor series if possible, and returns
\mbox{\tt "failed"} if this is not possible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{taylorRep}}\opLeftPren{}
{\it laurentSeries}\opRightPren{}%
}%
}%
{1}{(\$)->UTS}{UnivariateLaurentSeriesConstructorCategory}
{\smath{\mbox{\bf taylorRep}\opLeftPren{}f(x)\opRightPren{}} 
returns \smath{g(x)}, where \smath{f =
x^n  g(x)} is represented by \smath{[n, g(x)]}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tensorProduct}}\opLeftPren{}
{\it listOfMatrices\opt{, listOfMatrices}}\opRightPren{}%
}%
}%
{2}{(List(Matrix(R)), List(Matrix(R)))->List(Matrix(R))}
{RepresentationPackage1}
{\smath{\mbox{\bf tensorProduct}\opLeftPren{}[a_1, 
\allowbreak{} \ldots, a_k]\optinner{, [b_1, \ldots, b_k]}\opRightPren{}}
calculates the list of Kronecker products of the matrices
\smath{a_i} and \smath{b_i} for
\smath{1 \leq i \leq k}.
If a second argument is missing, the \smath{b_i} is defined as the 
corresponding \smath{a_i}.
Also, \smath{\mbox{\bf tensorProduct}\opLeftPren{}m\opRightPren{}}, 
where \smath{m} is a matrix,
is defined as \smath{\mbox{\bf tensorProduct}\opLeftPren{}[m], 
\allowbreak{} [m]\opRightPren{}}.
Note: If each list of matrices corresponds to a group representation
(representation of generators) of one group, then
these matrices correspond to the tensor product of the two representations.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{terms}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{1}{(\$)->List(Record(gen:S, exp:E))}{FreeAbelianMonoidCategory}
{\smath{\mbox{\bf terms}\opLeftPren{}s\opRightPren{}} 
returns a stream of the non-zero terms
of series \smath{s}.
Each term is returned as a record with selectors
\smath{k} and \smath{c}, which correspond to the
exponent and coefficient, respectively.
The terms are ordered by increasing order of exponents.
\newline
\smath{\mbox{\bf terms}\opLeftPren{}m\opRightPren{}},
where \smath{m} is a free abelian monoid of the form
\smath{e_1 a_1 + \cdots + e_n a_n},
returns \smath{[[a_1, e_1], \ldots, [a_n, e_n]]}.
See \spadtype{FreeAbelianMonoidCategory}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tex}}\opLeftPren{}
{\it formattedObject}\opRightPren{}%
}%
}%
{1}{(\$)->List(String)}{TexFormat}
{\smath{\mbox{\bf tex}\opLeftPren{}t\opRightPren{}} 
extracts the TeX section of a TeX formatted object \smath{t}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{third}}\opLeftPren{}{\it aggregate}\opRightPren{}%
}%
}%
{1}{(\$)->S}{UnaryRecursiveAggregate}
{\smath{\mbox{\bf third}\opLeftPren{}u\opRightPren{}} 
returns the third element of a recursive aggregate \smath{u}.
Note: \smath{\mbox{\bf third}\opLeftPren{}u) = first(rest(rest(u)))}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{title}}\opLeftPren{}{\it string}\opRightPren{}%
}%
}%
{1}{(String)->\$}{DrawOption}
{\smath{\mbox{\bf title}\opLeftPren{}s\opRightPren{}} 
specifies string \smath{s} as the title for a plot.
This option is expressed as a option to the \spadfun{draw} command in the
form \code{title == s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{top}}\opLeftPren{}{\it stack}\opRightPren{}%
 \opand \mbox{\axiomFun{top!}}\opLeftPren{}{\it dequeue}\opRightPren{}%
}%
}%
{1}{(\$)->S}{StackAggregate}
{\smath{\mbox{\bf top}\opLeftPren{}s\opRightPren{}} 
returns the top element \smath{x} from \smath{s}.
\newitem
\smath{\mbox{\bf top!}\opLeftPren{}d\opRightPren{}} 
returns the element at the top (front) of the dequeue.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{toroidal}}\opLeftPren{}{\it value}\opRightPren{}%
}%
}%
{1}{(R)->(Point(R))->Point(R)}{CoordinateSystems}
{\smath{\mbox{\bf toroidal}\opLeftPren{}element\opRightPren{}} 
transforms from toroidal coordinates to Cartesian coordinates:
\smath{\mbox{\bf toroidal}\opLeftPren{}a\opRightPren{}} 
is a function that maps the point \smath{(u, v, \phi)} to
\smath{x = a{\sinh}(v){\cos}(\phi)/({\cosh}(v)-{\cos}(u))},
\smath{y = a{\sinh}(v){\sin}(\phi)/({\cosh}(v)-{\cos}(u))},
\smath{z = a{\sin}(u)/({\cosh}(v)-{\cos}(u))}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{toScale}}\opLeftPren{}{\it boolean}\opRightPren{}%
}%
}%
{1}{(Boolean)->\$}{DrawOption}
{\smath{\mbox{\bf toScale}\opLeftPren{}b\opRightPren{}} 
specifies whether or not a plot is to be drawn
to scale.
This command may be expressed as an option to the
\spadfun{draw} command in the form \smath{toScale == b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{totalDegree}}\opLeftPren{}
{\it polynomial}, \allowbreak{}{\it  listOfVariables}\opRightPren{}%
}%
}%
{2}{(\$, List(VarSet))->NonNegativeInteger}{PolynomialCategory}
{\smath{\mbox{\bf totalDegree}\opLeftPren{}p\optinner{, lv}\opRightPren{}} 
returns the maximum sum
(over all monomials of polynomial \smath{p})
of the variables in the list \smath{lv}.
If a second argument is missing, \smath{lv} is defined
to be all the variables appearing in \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{totalfract}}\opLeftPren{}
{\it polynomial}\opRightPren{}%
}%
}%
{1}{(PRF)->Record(sup:Polynomial(R), inf:Polynomial(R))}
{MPolyCatRationalFunctionFactorizer}
{\smath{\mbox{\bf totalfract}\opLeftPren{}prf\opRightPren{}} 
takes a polynomial whose coefficients are
themselves fractions of polynomials and returns a record
containing the numerator and denominator resulting from putting
\smath{prf} over a common denominator.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{totalGroebner}}\opLeftPren{}
{\it listOfPolynomials}, \allowbreak{}{\it  listOfVariables}\opRightPren{}%
}%
}%
{2}{(List(Polynomial(F)), List(Symbol))->List(Polynomial(F))}{PolyGroebner}
{\smath{\mbox{\bf totalGroebner}\opLeftPren{}lp, 
\allowbreak{} lv\opRightPren{}} computes the Gr\"obner basis for the
\index{Groebner basis@{Gr\protect\"{o}bner basis}}
list of polynomials \smath{lp} with the terms ordered first by
\index{basis!Groebner@{Gr\protect\"{o}bner}}
total degree and then refined by reverse lexicographic ordering.
The variables are ordered by their position in the list
\smath{lv}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tower}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->List(Kernel(\$))}{ExpressionSpace}
{\smath{\mbox{\bf tower}\opLeftPren{}f\opRightPren{}} 
returns all the kernels appearing in \smath{f}, regardless of level.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{trace}}\opLeftPren{}
{\it various}, \allowbreak{}{\it  ..}\opRightPren{}%
}%
}%
{1}{(\$)->R}{SquareMatrixCategory}
{\smath{\mbox{\bf trace}\opLeftPren{}m\opRightPren{}} 
returns the trace of the matrix \smath{m}, that is, the
sum of its diagonal elements.
\newitem\smath{\mbox{\bf trace}\opLeftPren{}a\opRightPren{}} 
returns the trace of the regular
representation of \smath{a},
an element of an algebra of finite rank.
See \spadtype{FiniteRankAlgebra}.
\newitem\smath{\mbox{\bf trace}\opLeftPren{}a\optinner{, d}\opRightPren{}},
where \smath{a} is an element of a finite algebraic extension field,
computes the trace of \smath{a} with respect to the field of
extension degree \smath{d}
over the ground field of size \smath{q}.
This operation calls \spadfun{error} if
\smath{d} does not divide the extension degree of \smath{a}.
The default value of \smath{d} is 1.
Note: 
\smath{\mbox{\bf trace}\opLeftPren{}a, d) = \sum_{i=0}^{n/d} a^{q^{d i}}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{traceMatrix}}\opLeftPren{}
{\it \opt{basis}}\opRightPren{}%
}%
}%
{1}{(Vector(\$))->Matrix(R)}{FiniteRankAlgebra}
{\smath{\mbox{\bf traceMatrix}\opLeftPren{}[v1, \allowbreak{} .., 
\allowbreak{} vn]\opRightPren{}} is the \smath{n}-by-\smath{n}
matrix
whose \smath{i}, \smath{j} element is  \smath{Tr(v_i  v_j)}.
If no argument is given, the \smath{v_i} are assumed to be elements
of the fixed basis.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tracePowMod}}\opLeftPren{}{\it poly}, 
\allowbreak{}{\it  nonNegativeInteger}, \allowbreak{}{\it  poly}
\opRightPren{}%
}%
}%
{3}{(FP, NonNegativeInteger, FP)->FP}{DistinctDegreeFactorize}
{\smath{\mbox{\bf tracePowMod}\opLeftPren{}u, \allowbreak{} k, 
\allowbreak{} v\opRightPren{}} returns \smath{\sum\nolimits_{i=0}^k
{u^{2^i}}}, all computed modulo the polynomial \smath{v}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{transcendenceDegree}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->NonNegativeInteger}{ExtensionField}
{\smath{\mbox{\bf transcendenceDegree}\opLeftPren{}\opRightPren{}\$F} 
returns the transcendence degree
of the field extension
\smath{F}, or 0 if the extension is algebraic.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{transcendent?}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{ExtensionField}
{\smath{\mbox{\bf transcendent?}\opLeftPren{}a\opRightPren{}} 
tests whether an element \smath{a} of
a domain that is an extension field over a ground field \smath{F}
is transcendent
with respect to \smath{F}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{transpose}}\opLeftPren{}
{\it matrix\opt{, options}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{MatrixCategory}
{\smath{\mbox{\bf transpose}\opLeftPren{}m\opRightPren{}} 
returns the transpose of the matrix \smath{m}.
\newitem
\smath{\mbox{\bf transpose}\opLeftPren{}t\optinner{, i, j}\opRightPren{}} 
exchanges the \eth{\smath{i}}
and \eth{\smath{j}} indices of \smath{t}.
For example, if \smath{r = {\bf transpose}(t, 2, 3)} for a rank four
tensor \smath{t}, then \smath{r} is the rank four tensor given by
\smath{r(i, j, k, l) = t(i, k, j, l)}.
If \smath{i} and \smath{j} are not given, they are assumed the
first and last index of \smath{t}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tree}}\opLeftPren{}
{\it value\opt{, listOfChildren}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{MatrixCategory}
{\smath{\mbox{\bf tree}\opLeftPren{}x, \allowbreak{} ls\opRightPren{}} 
creates an element of \spadtype{Tree} with
value \smath{x} at the root node, and immediate children \spad{ls}
in left-to-right order.
\newitem
\smath{\mbox{\bf tree}\opLeftPren{}x\opRightPren{}} is equivalent to 
\smath{\mbox{\bf tree}\opLeftPren{}x, \allowbreak{} []\$List(S)\opRightPren{}} 
where
\spad{x} has type \spad{S}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{trapezoidal}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  threeIntegers}
\opRightPren{}%
\optand \mbox{\axiomFun{trapezoidalClosed}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  twoIntegers}\opRightPren{}%
\opand \mbox{\axiomFun{trapezoidalOpen}}\opLeftPren{}{\it floatFunction}, 
\allowbreak{}{\it  fourFloats}, \allowbreak{}{\it  twoIntegers}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf trapezoidal}\opLeftPren{}fn, \allowbreak{} a, 
\allowbreak{} b, \allowbreak{} epsrel, \allowbreak{} epsabs, 
\allowbreak{} nmin, 
\allowbreak{} nmax, \allowbreak{} nint\opRightPren{}}
uses the adaptive trapezoidal method to numerically integrate
function \smath{fn} over the closed interval from \smath{a} to
\smath{b}, with relative accuracy \smath{epsrel} and absolute
accuracy \smath{epsabs}, where the refinement levels for the
checking of convergence vary from \smath{nmin} to \smath{nmax}.
The method is called ``adaptive'' since it requires an additional
parameter \smath{nint} giving the number of subintervals over
which the integrator independently applies the convergence
criteria using \smath{nmin} and \smath{nmax}; this is useful when
a large number of points are needed only in a small fraction of
the entire interval.
Parameter \smath{fn} is a function of type \spadsig{Float}{Float};
\smath{a}, \smath{b}, \smath{epsrel}, and \smath{epsabs} are
floats; \smath{nmin}, \smath{nmax}, and \smath{nint} are integers.
The operation returns a record containing: {\tt value}, an
estimate of the integral; {\tt error}, an estimate of the error in
the computation; {\tt totalpts}, the total integral number of
function evaluations, and {\tt success}, a boolean value that is
\smath{true} if the integral was computed within the user
specified error criterion.
See \spadtype{NumericalQuadrature} for details.
\bigitem\smath{trapezoidalClosed(fn, a, b, epsrel, epsabs, nmin,
nmax)} similarly uses the trapezoidal method to numerically
\index{trapezoidal method}
integrate function \smath{fn} over the closed interval \smath{a}
to \smath{b}, but is not adaptive.
\bigitem\smath{trapezoidalOpen(fn, a, b, epsrel, epsabs, nmin,
nmax)} is similar to \spadfun{trapezoidalClosed}, except that
it integrates function \smath{fn} over the open interval from
\smath{a} to \smath{b}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{triangularSystems}}\opLeftPren{}
{\it listOfFractions}, \allowbreak{}{\it  listOfSymbols}\opRightPren{}%
}%
}%
{2}{(List(Fraction(Polynomial(R))), 
List(Symbol))->List(List(Polynomial(R)))}{SystemSolvePackage}
{\smath{\mbox{\bf triangularSystems}\opLeftPren{}lf, 
\allowbreak{} lv\opRightPren{}} solves the system of equations
defined by
\smath{lf} with respect to the list of symbols \smath{lv}; the
system of equations is obtaining by equating to zero the list of
rational functions \smath{lf}.
The result is a list of solutions where each solution is expressed
as a ``reduced'' triangular system of polynomials.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{trigs}}\opLeftPren{}{\it expression}\opRightPren{}%
}%
}%
{1}{(F)->F}{TrigonometricManipulations}
{\smath{\mbox{\bf trigs}\opLeftPren{}f\opRightPren{}} 
rewrites all the complex logs and exponentials
appearing in \smath{f} in terms of trigonometric functions.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{trim}}\opLeftPren{}{\it string}, \allowbreak{}
{\it  characterOrCharacterClass}\opRightPren{}%
}%
}%
{2}{(\$, Character)->\$}{StringAggregate}
{\smath{\mbox{\bf trim}\opLeftPren{}s, \allowbreak{} c\opRightPren{}} 
returns \smath{s} with all characters \smath{c}
deleted from right and left ends.
For example, \code{trim(" abc ", char " ")} returns
\code{"abc"}.
Argument \smath{c} may also be a character class, in which case
\smath{s} is returned with all characters in \smath{cc} deleted
from right and left ends.
For example, \code{trim("(abc)", charClass "()")} returns
\spad{"abc"}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{truncate}}\opLeftPren{}
{\it various\opt{, options}}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{RealNumberSystem}
{\smath{\mbox{\bf truncate}\opLeftPren{}x\opRightPren{}} 
returns the integer between \smath{x} and 0
closest to \smath{x}.
\newitem
\smath{\mbox{\bf truncate}\opLeftPren{}f, 
\allowbreak{} m\optinner{, n}\opRightPren{}} returns a (finite) power series
consisting of the sum of all terms of \smath{f} of degree
\smath{d} with \smath{n \leq d \leq m}.
Upper bound \smath{m} is \smath{\infty} by default.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tubePoints}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->\$}{DrawOption}
{\smath{\mbox{\bf tubePoints}\opLeftPren{}n\opRightPren{}} 
specifies the number of points, \smath{n},
defining the circle that creates the tube around a \threedim{}
curve.
The default is 6.
This option is expressed in the form \code{tubePoints == n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tubePointsDefault}}\opLeftPren{}
{\it \opt{positiveInteger}}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->PositiveInteger}{ViewDefaultsPackage}
{\smath{\mbox{\bf tubePointsDefault}\opLeftPren{}i\opRightPren{}} 
sets the number of points to use
when creating the circle to be used in creating a \threedim{} tube
plot to \smath{i}.
\newitem
\smath{\mbox{\bf tubePointsDefault}\opLeftPren{}\opRightPren{}} 
returns the number of points to be
used when creating the circle to be used in creating a \threedim{}
tube plot.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tubeRadius}}\opLeftPren{}{\it float}\opRightPren{}%
}%
}%
{1}{(Float)->\$}{DrawOption}
{\smath{\mbox{\bf tubeRadius}\opLeftPren{}r\opRightPren{}} 
specifies a radius \smath{r} for a tube
plot around a \threedim{} curve.
This operation may be expressed as an option
to the \spadfun{draw} command in the form \code{tubeRadius == r}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{tubeRadiusDefault}}\opLeftPren{}
{\it \opt{float}}\opRightPren{}%
}%
}%
{0}{()->DoubleFloat}{ViewDefaultsPackage}
{\smath{\mbox{\bf tubeRadiusDefault}\opLeftPren{}r\opRightPren{}} 
sets the default radius for a
\threedim{} tube plot to \smath{r}.
\newitem
\smath{\mbox{\bf tubeRadiusDefault}\opLeftPren{}\opRightPren{}} 
returns the radius used for a
\threedim{} tube plot.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{twist}}\opLeftPren{}\opRightPren{}%
}%
}%
{ ((A, B)->C)    -> ((B, A)->C)}{}{}
{\smath{\mbox{\bf twist}\opLeftPren{}f\opRightPren{}},
where \smath{f} is a function of type \smath{(A, B)}{C},
is the function \smath{g} such that \smath{g(a, b)= f(b, a)}.
See \spadtype{MappingPackage} for related functions.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unary?}}\opLeftPren{}
{\it basicOperator}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{BasicOperator}
{\smath{\mbox{\bf unary?}\opLeftPren{}op\opRightPren{}} tests 
if basic operator \smath{op} is unary,
that is, takes exactly one argument.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{union}}\opLeftPren{}{\it set}, \allowbreak{}
{\it  elementOrSet}\opRightPren{}%
}%
}%
{2}{(\$, S)->\$}{SetAggregate}
{\smath{\mbox{\bf union}\opLeftPren{}u, 
\allowbreak{} x\opRightPren{}} returns the set aggregate \smath{u} with the
element \smath{x} added.
If \smath{u} already contains \smath{x}, 
\smath{\mbox{\bf union}\opLeftPren{}u, \allowbreak{} x\opRightPren{}}
returns a copy of \smath{x}.
\newitem
\smath{\mbox{\bf union}\opLeftPren{}u, \allowbreak{} v\opRightPren{}} 
returns the set aggregate of elements that are
members of either set aggregate \smath{u} or \smath{v}.
See also \axiomType{Multiset}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unit}}\opLeftPren{}{\it \opt{various}}\opRightPren{}%
}%
}%
{1}{(\$)->R}{Factored}
{\smath{\mbox{\bf unit}\opLeftPren{}\opRightPren{}} 
returns a unit of the algebra (necessarily
unique), or \mbox{\tt "failed"} if there is none.
\newitem
\smath{\mbox{\bf unit}\opLeftPren{}u\opRightPren{}} 
extracts the unit part of the factored object
\smath{u}.
\newitem
\smath{\mbox{\bf unit}\opLeftPren{}l\opRightPren{}} 
marks off the units on a viewport according to
the indicated list \smath{l}.
This option is expressed in the draw command in the form
\smath{{\tt unit ==} [f_1, f_2]}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unit?}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{IntegralDomain}
{\smath{\mbox{\bf unit?}\opLeftPren{}x\opRightPren{}} 
tests whether \smath{x} is a unit, that is, if
\smath{x} is invertible.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unitCanonical}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{IntegralDomain}
{\smath{\mbox{\bf unitCanonical}\opLeftPren{}x\opRightPren{}} 
returns \smath{\mbox{\bf unitNormal}\opLeftPren{}x).{canonical}}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unitNormalize}}\opLeftPren{}
{\it factored}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{Factored}
{\smath{\mbox{\bf unitNormalize}\opLeftPren{}u\opRightPren{}} 
normalizes the unit part of the
factorization.
For example, when working with factored integers, this operation
ensures that the bases are all positive integers.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unitNormal}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Record(unit:\$, canonical:\$, associate:\$)}{IntegralDomain}
{\smath{\mbox{\bf unitNormal}\opLeftPren{}x\opRightPren{}} 
tries to choose a canonical element from
the associate class of \smath{x}.
If successful, it returns a record with three components
``unit'', ``canonical'' and ``associate''.
The attribute {\tt canonicalUnitNormal}, if asserted, means
that the ``canonical'' element is the same across all associates
of \smath{x}.
If \smath{\mbox{\bf unitNormal}\opLeftPren{}x) = [u, c, a]} 
then \smath{ux = c},
\smath{au = 1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unitsColorDefault}}\opLeftPren{}
{\it \opt{palette}}\opRightPren{}%
}%
}%
{0}{()->Palette}{ViewDefaultsPackage}
{\smath{\mbox{\bf unitsColorDefault}\opLeftPren{}p\opRightPren{}} 
sets the default color of the unit
ticks in a \twodim{} viewport to the palette \smath{p}.
\newitem
\smath{\mbox{\bf unitsColorDefault}\opLeftPren{}\opRightPren{}} 
returns the default color of the unit
ticks in a \twodim{} viewport.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unitVector}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->\$}{DirectProductCategory}
{\smath{\mbox{\bf unitVector}\opLeftPren{}n\opRightPren{}} 
produces a vector with 1 in position
\smath{n} and zero elsewhere.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{univariate}}\opLeftPren{}
{\it polynomial\opt{, variable}}\opRightPren{}%
}%
}%
{1}{(\$)->SparseUnivariatePolynomial(R)}{PolynomialCategory}
{\smath{\mbox{\bf univariate}\opLeftPren{}p\optinner{, v}\opRightPren{}} 
converts the multivariate
polynomial \smath{p} into a univariate polynomial in \smath{v}
whose coefficients are multivariate polynomials in all the other
variables.
If \smath{v} is omitted, then \smath{p} must involve exactly one variable.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{universe}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{FiniteSetAggregate}
{\smath{\mbox{\bf universe}\opLeftPren{}\opRightPren{}}\$\smath{R} 
returns the universal set for
finite set aggregate \smath{R}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unparse}}\opLeftPren{}{\it inputForm}\opRightPren{}%
}%
}%
{ $ -> String}{}{}
{\smath{\mbox{\bf unparse}\opLeftPren{}f\opRightPren{}} 
returns a string \smath{s} such that the parser
would transform \smath{s} to \smath{f}, or
calls \spadfun{error} if \smath{f} is
not the parsed form of a string.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unrankImproperPartitions0}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  integer}\opRightPren{}%
}%
}%
{3}{(Integer, Integer, Integer)->List(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf unrankImproperPartitions0}\opLeftPren{}n, \allowbreak{} m, 
\allowbreak{} k\opRightPren{}} computes the
\eth{\smath{k}} improper partition of nonnegative \smath{n} in
\smath{m} nonnegative parts in reverse lexicographical order.
Example: \smath{ [0, 0, 3] < [0, 1, 2] < [0, 2, 1] < [0, 3, 0] < [1, 0, 2] <
[1, 1, 1] < [1, 2, 0] < [2, 0, 1] < [2, 1, 0] < [3, 0, 0]}.
The operation calls \spadfun{error} if \smath{k} is negative or
too big.
Note: counting of subtrees is done by
\spadfunFrom{numberOfImproperPartitions}{SymmetricGroupCombinatoricFunctions}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unrankImproperPartitions1}}\opLeftPren{}
{\it integer}, \allowbreak{}{\it  integer}, \allowbreak{}
{\it  integer}\opRightPren{}%
}%
}%
{3}{(Integer, Integer, Integer)->List(Integer)}
{SymmetricGroupCombinatoricFunctions}
{\smath{\mbox{\bf unrankImproperPartitions1}\opLeftPren{}n, \allowbreak{} m,
\allowbreak{} k\opRightPren{}} computes the
\eth{\smath{k}} improper partition of nonnegative \smath{n} in at most
\smath{m} nonnegative parts ordered as follows: first, in reverse
lexicographical order according to their non-zero parts, then
according to their positions (i.e.
lexicographical order using \smath{subSet}: \smath{[3, 0, 0] < [0, 3, 0]
< [0, 0, 3] < [2, 1, 0] < [2, 0, 1] < [0, 2, 1] < [1, 2, 0] < [1, 0, 2] <
[0, 1, 2] < [1, 1, 1]}).
Note: counting of subtrees is done by
\spadfun{numberOfImproperPartitionsInternal}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{unravel}}\opLeftPren{}
{\it listOfElement}\opRightPren{}%
}%
}%
{1}{(List(R))->\$}{CartesianTensor}
{\smath{\mbox{\bf unravel}\opLeftPren{}t\opRightPren{}} 
produces a tensor from a list of components such that
\smath{\mbox{\bf unravel}\opLeftPren{}{\bf ravel}(t)) = t}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{upperCase}}\opLeftPren{}{\it string}\opRightPren{}%
 \optand \mbox{\axiomFun{upperCase?}}\opLeftPren{}{\it string}\opRightPren{}%
 \opand \mbox{\axiomFun{upperCase!}}\opLeftPren{}{\it string}\opRightPren{}%
}%
}%
{1}{(\$)->\$}{StringAggregate}
{\smath{\mbox{\bf upperCase!}\opLeftPren{}s\opRightPren{}} 
destructively replaces the alphabetic
characters in \smath{s} by upper case characters.
\newitem
\smath{\mbox{\bf upperCase}\opLeftPren{}\opRightPren{}} 
returns the class of all characters for which
\spadfunFrom{upperCase?}{Character} is \smath{true}.
\newitem
\smath{\mbox{\bf upperCase}\opLeftPren{}c\opRightPren{}} 
converts a lower case letter
\smath{c} to the corresponding upper case letter.
If \smath{c} is not a lower case letter, then it is returned
unchanged.
\newitem
\smath{\mbox{\bf upperCase}\opLeftPren{}s\opRightPren{}} 
returns the string with all characters in
upper case.
\newitem
\smath{\mbox{\bf upperCase?}\opLeftPren{}c\opRightPren{}} tests 
if \smath{c} is an upper case letter,
that is, one of A..\smath{Z}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{validExponential}}\opLeftPren{}
{\it listOfKernels}, \allowbreak{}{\it  expression}, \allowbreak{}
{\it  symbol}\opRightPren{}%
}%
}%
{3}{(List(Kernel(F)), F, Symbol)->Union(F, "failed")}
{ElementaryFunctionStructurePackage}
{\smath{\mbox{\bf validExponential}\opLeftPren{}[k_1, 
\allowbreak{} \ldots, k_n], f, x\opRightPren{}} returns \smath{g}
if \smath{\mbox{\bf exp}\opLeftPren{}f)=g} and \smath{g} involves only
\smath{k_1\ldots{}k_n}, and \mbox{\tt "failed"} otherwise.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{value}}\opLeftPren{}
{\it recursiveAggregate}\opRightPren{}%
}%
}%
{1}{(\$)->S}{RecursiveAggregate}
{\smath{\mbox{\bf value}\opLeftPren{}a\opRightPren{}} 
returns the ``value'' part of a recursive
aggregate \spad{a}, typically the root of tree.
See, for example, \spadtype{BinaryTree}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{var1Steps}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->\$}{DrawOption}
{\smath{\mbox{\bf var1Steps}\opLeftPren{}n\opRightPren{}} 
indicates the number of subdivisions
\smath{n} of the first range variable.
This command may be expressed as an option
to the \spadfun{draw} command in the form \smath{{\bf var1Steps}== n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{var1StepsDefault}}\opLeftPren{}
{\it \opt{positiveInteger}}\opRightPren{}%
}%
}%
{0}{()->PositiveInteger}{ViewDefaultsPackage}
{\smath{\mbox{\bf var1StepsDefault}\opLeftPren{}\opRightPren{}} 
returns the current setting for the
number of steps to take when creating a \threedim{} mesh in the
direction of the first defined free variable (a free variable is
considered defined when its range is specified (that is,
\smath{x=0}..10)).
\newitem
\smath{\mbox{\bf var1StepsDefault}\opLeftPren{}i\opRightPren{}} 
sets the number of steps to take when
creating a \threedim{} mesh in the direction of the first defined
free variable to \smath{i} (a free variable is considered defined
when its range is specified (that is, \smath{x=0}..10)).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{var2Steps}}\opLeftPren{}
{\it positiveInteger}\opRightPren{}%
}%
}%
{1}{(PositiveInteger)->\$}{DrawOption}
{\smath{\mbox{\bf var2Steps}\opLeftPren{}n\opRightPren{}} 
indicates the number of subdivisions,
\smath{n}, of the second range variable.
This option is expressed in the form \smath{{\bf var2Steps} == n}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{var2StepsDefault}}\opLeftPren{}
{\it \opt{positiveInteger}}\opRightPren{}%
}%
}%
{()->PositiveInteger}{ViewDefaultsPackage}
{\smath{\mbox{\bf var2StepsDefault}\opLeftPren{}\opRightPren{}} 
is the current setting for the number
of steps to take when creating a \threedim{} mesh in the direction
of the first defined free variable (a free variable is considered
defined when its range is specified (that is, \smath{x=0}..10)).
\newitem
\smath{\mbox{\bf var2StepsDefault}\opLeftPren{}i\opRightPren{}} 
sets the number of steps to take when
creating a \threedim{} mesh in the direction of the first defined
free variable to \smath{i} (a free variable is considered defined
when its range is specified (that is, \smath{x=0}..10)).
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{variable}}\opLeftPren{}
{\it various}\opRightPren{}%
}%
}%
{1}{(\$)->Symbol}{UnivariatePowerSeriesCategory}
{\smath{\mbox{\bf variable}\opLeftPren{}f\opRightPren{}} 
returns the (unique) power series variable of
the power series \smath{f}.
\newitem
\smath{\mbox{\bf variable}\opLeftPren{}segb\opRightPren{}} 
returns the variable from the left hand
side of the \spadtype{SegmentBinding} \smath{segb}.
For example, if \smath{segb} is \smath{v=a..b}, then
\smath{\mbox{\bf variable}\opLeftPren{}segb\opRightPren{}} 
returns \smath{v}.
\newitem
\smath{\mbox{\bf variable}\opLeftPren{}v\opRightPren{}} 
returns \smath{s} if \smath{v} is any
derivative of the differential indeterminate \smath{s}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{variables}}\opLeftPren{}
{\it expression}\opRightPren{}%
}%
}%
{1}{(\$)->List(Symbol)}{FunctionSpace}
{\smath{\mbox{\bf variables}\opLeftPren{}f\opRightPren{}} 
returns the list of all the variables of
expression, polynomial, rational function, or power series \smath{f}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{vconcat}}\opLeftPren{}
{\it outputForms\opt{, OutputForm} (normally unexposed)}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf vconcat}\opLeftPren{}o_1, 
\allowbreak{} o_2\opRightPren{}}, where \smath{o_1} and \smath{o_2} are
objects of type \spadtype{OutputForm} (normally unexposed),
returns an output form for the vertical concatenation of forms
\smath{o_1} and \smath{o_2}.
\newitem
\smath{\mbox{\bf vconcat}\opLeftPren{}lo\opRightPren{}}, 
where \smath{lo} is a list of objects of type
\spadtype{OutputForm} (normally unexposed), returns an output form
for the vertical concatenation of the elements of \smath{lo}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{vector}}\opLeftPren{}
{\it listOfElements}\opRightPren{}%
}%
}%
{1}{(List(R))->\$}{Vector}
{\smath{\mbox{\bf vector}\opLeftPren{}l\opRightPren{}} converts the 
list \smath{l} to a vector.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{vectorise}}\opLeftPren{}{\it polynomial}, 
\allowbreak{}{\it  nonNegativeInteger}\opRightPren{}%
}%
}%
{2}{(\$, NonNegativeInteger)->Vector(R)}{UnivariatePolynomialCategory}
{\smath{\mbox{\bf vectorise}\opLeftPren{}p, \allowbreak{} n\opRightPren{}} 
returns \smath{[a_0, \ldots, a_{n-1}]}
where \smath{p = a_0 + a_1 x + \cdots + a_{n-1} x^{n-1}} + higher
order terms.
The degree of polynomial \smath{p} can be different from
\smath{n-1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{vertConcat}}\opLeftPren{}{\it matrix}, 
\allowbreak{}{\it  matrix}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{MatrixCategory}
{\smath{\mbox{\bf vertConcat}\opLeftPren{}x, \allowbreak{} y\opRightPren{}} 
vertically concatenates two matrices with an
equal number of columns.
The entries of \smath{y} appear below the entries of \smath{x}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{viewDefaults}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->Void}{ViewDefaultsPackage}
{\smath{\mbox{\bf viewDefaults}\opLeftPren{}\opRightPren{}} 
resets all the default graphics settings.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{viewPosDefault}}\opLeftPren{}
{\it \opt{listOfNonNegativeIntegers}}\opRightPren{}%
}%
}%
{1}{(List(NonNegativeInteger))->List(NonNegativeInteger)}{ViewDefaultsPackage}
{\smath{\mbox{\bf viewPosDefault}\opLeftPren{}[x, \allowbreak{} y]
\opRightPren{}} sets the default \smath{X} and
\smath{Y} position of a viewport window.
Unless overridden explicitly, newly created viewports will have the
\smath{X} and \smath{Y} coordinates \smath{x}, \smath{y}.
\newitem
\smath{\mbox{\bf viewPosDefault}\opLeftPren{}\opRightPren{}} 
returns the default \smath{X} and
\smath{Y} position of a viewport window unless overridden
explicitly, newly created viewports will have these \smath{X} and
\smath{Y} coordinate.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{viewSizeDefault}}\opLeftPren{}
{\it \opt{listOfPositiveIntegers}}\opRightPren{}%
}%
}%
{1}{(List(PositiveInteger))->List(PositiveInteger)}{ViewDefaultsPackage}
{\smath{\mbox{\bf viewSizeDefault}\opLeftPren{}[w, \allowbreak{} h]
\opRightPren{}} sets the default viewport width to \smath{w} and 
height to \smath{h}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{viewWriteAvailable}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->List(String)}{ViewDefaultsPackage}
{\smath{\mbox{\bf viewWriteAvailable}\opLeftPren{}\opRightPren{}} returns 
a list of available methods for writing, such as BITMAP, POSTSCRIPT, etc.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{viewWriteDefault}}\opLeftPren{}
{\it listOfStrings}\opRightPren{}%
}%
}%
{0}{()->List(String)}{ViewDefaultsPackage}
{\smath{\mbox{\bf viewWriteDefault}\opLeftPren{}\opRightPren{}} 
returns the list of things to write in
a viewport data file; a viewAlone file is always generated.
\newitem
\smath{\mbox{\bf viewWriteDefault}\opLeftPren{}l\opRightPren{}} 
sets the default list of things to
write in a viewport data file to the strings in \smath{l}; a
viewAlone file is always generated.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{void}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Void}
{\smath{\mbox{\bf void}\opLeftPren{}\opRightPren{}} produces a void object.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{weakBiRank}}\opLeftPren{}
{\it element}\opRightPren{}%
}%
}%
{1}{(A)->NonNegativeInteger}{AlgebraPackage}
{\smath{\mbox{\bf weakBiRank}\opLeftPren{}x\opRightPren{}} 
determines the number of linearly
independent elements in the \smath{b_i x b_j}, \smath{i, j=1,
\ldots, n}, where \smath{b=[b_1, \ldots, b_n]} is the fixed basis of
a domain of category \spadtype{FramedNonAssociativeAlgebra}.}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{weight}}\opLeftPren{}{\it u}\opRightPren{}%
}%
}%
{1}{(\$)->NonNegativeInteger}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf weight}\opLeftPren{}u\opRightPren{}} returns
\begin{simpleList}
\item if u is a differential polynomial: the maximum weight of all
differential monomials appearing in the differential polynomial
\smath{u}.
\item if u is a derivative:
the weight of the derivative \smath{u}.
\item if u is a basic operator: the weight attached to \smath{u}.
\end{simpleList}
\smath{\mbox{\bf weight}\opLeftPren{}p, \allowbreak{} s\opRightPren{}} 
returns the maximum weight of all differential monomials appearing in 
the differential polynomial \smath{p} when \smath{p} is viewed as a 
differential polynomial in the differential indeterminate \smath{s} alone.
\newitem
\smath{\mbox{\bf weight}\opLeftPren{}op, 
\allowbreak{} n\opRightPren{}} attaches the weight \smath{n} to \smath{op}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{weights}}\opLeftPren{}
{\it differentialPolynomial}, \allowbreak{}
{\it  differentialIndeterminated}\opRightPren{}%
}%
}%
{2}{(\$, S)->List(NonNegativeInteger)}{DifferentialPolynomialCategory}
{\smath{\mbox{\bf weights}\opLeftPren{}p, 
\allowbreak{} s\opRightPren{}} returns a list of weights of differential
monomials appearing in the differential polynomial \smath{p} when
\smath{p} is viewed as a differential polynomial in the
differential indeterminate \smath{s} alone.
If \smath{s} is missing, a list of weights of differential
monomials appearing in differential polynomial \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{whatInfinity}}\opLeftPren{}
{\it orderedCompletion}\opRightPren{}%
}%
}%
{1}{(\$)->SingleInteger}{OrderedCompletion}
{\smath{\mbox{\bf whatInfinity}\opLeftPren{}x\opRightPren{}} 
returns 0 if \smath{x} is finite, 1 if
\smath{x} is \smath{\infty}, and \smath{-1} if \smath{x} is
\smath{-\infty}.
}


% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wholePart}}\opLeftPren{}
{\it various}\opRightPren{}%
}%
}%
{1}{(\$)->R}{ContinuedFraction}
{\smath{\mbox{\bf wholePart}\opLeftPren{}x\opRightPren{}} 
returns the whole part of the fraction
\smath{x}, that is,
the truncated quotient of the numerator by the denominator.
\newitem
\smath{\mbox{\bf wholePart}\opLeftPren{}x\opRightPren{}} 
extracts the whole part of \smath{x}.
That is,
if \smath{x = {\bf continuedFraction}
(b_0, [a_1, a_2, \ldots], [b_1, b_2, \ldots])},
then \smath{\mbox{\bf wholePart}\opLeftPren{}x) = b_0}.
\newitem
\smath{\mbox{\bf wholePart}\opLeftPren{}p\opRightPren{}} 
extracts the whole part of the partial
fraction \smath{p}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wholeRadix}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(List(Integer))->\$}{RadixExpansion}
{\smath{\mbox{\bf wholeRadix}\opLeftPren{}l\opRightPren{}} 
creates an integral radix expansion from a
list of ragits.
For example, \smath{\mbox{\bf wholeRadix}\opLeftPren{}[1, \allowbreak{} 3, 
\allowbreak{} 4]\opRightPren{}} returns \smath{134}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wholeRagits}}\opLeftPren{}
{\it listOfIntegers}\opRightPren{}%
}%
}%
{1}{(\$)->List(Integer)}{RadixExpansion}
{\smath{\mbox{\bf wholeRagits}\opLeftPren{}rx\opRightPren{}} 
returns the ragits of the integer part of
a radix expansion.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wordInGenerators}}\opLeftPren{}{\it permutation}, 
\allowbreak{}{\it  permutationGroup}\opRightPren{}%
}%
}%
{2}{(Permutation(S), \$)->List(NonNegativeInteger)}{PermutationGroup}
{\smath{\mbox{\bf wordInGenerators}\opLeftPren{}p, 
\allowbreak{} gp\opRightPren{}} returns the word for the
permutation \smath{p} in the original generators of the
permutation group {\it gp}, represented by the indices of the
list, given by \spadfun{generators}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wordInStrongGenerators}}\opLeftPren{}
{\it permutation}, \allowbreak{}{\it  permutationGroup}\opRightPren{}%
}%
}%
{2}{(Permutation(S), \$)->List(NonNegativeInteger)}{PermutationGroup}
{\smath{\mbox{\bf wordInStrongGenerators}\opLeftPren{}p, 
\allowbreak{} gp\opRightPren{}} returns the word for the
permutation \smath{p} in the strong generators of the permutation
group {\it gp}, represented by the indices of the list, given by
\spadfun{strongGenerators}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wordsForStrongGenerators}}\opLeftPren{}
{\it listOfListsOfIntegers}\opRightPren{}%
}%
}%
{1}{(\$)->List(List(NonNegativeInteger))}{PermutationGroup}
{\smath{\mbox{\bf wordsForStrongGenerators}\opLeftPren{}gp\opRightPren{}} 
returns the words for the
strong generators
of the permutation group {\it gp} in the original generators of {\it gp},
represented by their indices in the list of nonnegative integers,
given by \spadfun{generators}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{wreath}}\opLeftPren{}{\it symmetricPolynomial}, 
\allowbreak{}{\it  symmetricPolynomial}\opRightPren{}%
}%
}%
{ (SPOL RN, SPOL RN) -> SPOL RN}{}{}
{\smath{\mbox{\bf wreath}\opLeftPren{}s_1, \allowbreak{} s_2\opRightPren{}} 
is the cycle index of the wreath product
of the two groups whose cycle indices are \smath{s_1} and
\smath{s_2}, symmetric polynomials with rational number
coefficients.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{writable?}}\opLeftPren{}{\it file}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{FileNameCategory}
{\smath{\mbox{\bf writable?}\opLeftPren{}f\opRightPren{}} 
tests if the named file can be opened for
writing.
The named file need not already exist.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{write!}}\opLeftPren{}{\it file}, \allowbreak{}
{\it  value}\opRightPren{}%
}%
}%
{2}{(\$, S)->S}{FileCategory}
{\smath{\mbox{\bf write!}\opLeftPren{}f, \allowbreak{} s\opRightPren{}} 
puts the value \smath{s} into the file \smath{f}.
The state of \smath{f} is modified so that subsequent
calls to {\bf write!} will append values to the end of the
file.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{writeLine!}}\opLeftPren{}
{\it textfile\opt{, string}}\opRightPren{}%
}%
}%
{1}{(\$)->String}{TextFile}
{\smath{\mbox{\bf writeLine!}\opLeftPren{}f\opRightPren{}} 
finishes the current line in the file
\smath{f}.
An empty string is returned.
The call \smath{\mbox{\bf writeLine!}\opLeftPren{}f\opRightPren{}} 
is equivalent to
\smath{\mbox{\bf writeLine!}\opLeftPren{}f, \allowbreak{} 
{\tt ""}\opRightPren{}}.
\newitem
\smath{\mbox{\bf writeLine!}\opLeftPren{}f, \allowbreak{} s\opRightPren{}} 
writes the contents of the string
\smath{s} and finishes the current line in the file \smath{f}.
The value of \smath{s} is returned.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{xor}}\opLeftPren{}{\it boolean}, \allowbreak{}
{\it  boolean}\opRightPren{}%
}%
}%
{2}{(\$, \$)->\$}{BitAggregate}
{\smath{\mbox{\bf xor}\opLeftPren{}a, \allowbreak{} b\opRightPren{}} 
returns the logical {\it exclusive-or} of
booleans or bit aggregates \smath{a} and \smath{b}.
\newitem
\smath{\mbox{\bf xor}\opLeftPren{}n, \allowbreak{} m\opRightPren{}} 
returns the bit-by-bit logical {\it xor} of the
small integers \smath{n} and \smath{m}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{xRange}}\opLeftPren{}{\it curve}\opRightPren{}%
}%
}%
{1}{(\$)->Segment(DoubleFloat)}{PlottablePlaneCurveCategory}
{\smath{\mbox{\bf xRange}\opLeftPren{}c\opRightPren{}} 
returns the range of the \smath{x}-coordinates
of the points on the curve \smath{c}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{yCoordinates}}\opLeftPren{}
{\it function}\opRightPren{}%
}%
}%
{1}{(\$)->Record(num:Vector(UP), den:UP)}{FunctionFieldCategory}
{\smath{\mbox{\bf yCoordinates}\opLeftPren{}f\opRightPren{}},
where \smath{f} is a function defined over a curve,
returns the coordinates of \smath{f} with
respect to the natural basis for the curve.
Specifically, the operation returns
\smath{[ [a_1, \ldots, a_n], d]} 
such that \smath{f = (a_1 +\ldots+ a_n y^{n-1}) / d}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{yellow}}\opLeftPren{}\opRightPren{}%
}%
}%
{0}{()->\$}{Color}
{\smath{\mbox{\bf yellow}\opLeftPren{}\opRightPren{}} 
returns the position of the yellow hue from
total hues.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{youngGroup}}\opLeftPren{}{\it various}\opRightPren{}%
}%
}%
{1}{(List(Integer))->PermutationGroup(Integer)}{PermutationGroupExamples}
{\smath{\mbox{\bf youngGroup}\opLeftPren{}
[n_1, \allowbreak{} \ldots, n_k]\opRightPren{}} constructs the direct
product of the
symmetric groups \smath{Sn_1}, \ldots, \smath{Sn_k}.
\newitem
\smath{\mbox{\bf youngGroup}\opLeftPren{}lambda\opRightPren{}} 
constructs the direct product of the
symmetric groups given by the parts of the partition {\it lambda}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{yRange}}\opLeftPren{}{\it curve}\opRightPren{}%
}%
}%
{1}{(\$)->Segment(DoubleFloat)}{PlottablePlaneCurveCategory}
{\smath{\mbox{\bf yRange}\opLeftPren{}c\opRightPren{}} 
returns the range of the \smath{y}-coordinates
of the points on the curve \smath{c}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zag}}\opLeftPren{}
{\it outputForm}, \allowbreak{}{\it  outputForm}\opRightPren{}%
}%
}%
{}{}{}
{\smath{\mbox{\bf zag}\opLeftPren{}o_1, \allowbreak{} o_2\opRightPren{}},
where \smath{o_1} and \smath{o_2} are objects of 
type \spadtype{OutputForm} (normally unexposed),
return an output form displaying
the continued fraction form for \smath{o_2} over \smath{o_1}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zero}}\opLeftPren{}
{\it nonNegativeInteger\opt{, nonNegativeInteger}}\opRightPren{}%
}%
}%
{1}{(NonNegativeInteger)->\$}{VectorCategory}
{\smath{\mbox{\bf zero}\opLeftPren{}n\opRightPren{}} 
creates a zero vector of length \smath{n}.
\newitem
\smath{\mbox{\bf zero}\opLeftPren{}m, \allowbreak{} n\opRightPren{}} 
returns an \smath{m}-by-\smath{n} zero matrix.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zero?}}\opLeftPren{}{\it element}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{AbelianMonoid}
{\smath{\mbox{\bf zero?}\opLeftPren{}x\opRightPren{}} 
tests if \smath{x} is equal to 0.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zeroDim?}}\opLeftPren{}{\it ideal}\opRightPren{}%
}%
}%
{1}{(\$)->Boolean}{PolynomialIdeals}
{\smath{\mbox{\bf zeroDim?}\opLeftPren{}I\opRightPren{}} 
tests if the ideal \smath{I} is zero
dimensional, that is, all its associated primes are maximal.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zeroDimPrimary?}}\opLeftPren{}
{\it ideal}\opRightPren{}%
}%
}%
{1}{(PolynomialIdeals(Fraction(Integer), 
DirectProduct(nv, NonNegativeInteger), vl, 
DistributedMultivariatePolynomial(vl, Fraction(Integer))))->Boolean}
{IdealDecompositionPackage}
{\smath{\mbox{\bf zeroDimPrimary?}\opLeftPren{}I\opRightPren{}} 
tests if the ideal \smath{I} is
0-dimensional primary.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zeroDimPrime?}}\opLeftPren{}
{\it ideal}\opRightPren{}%
}%
}%
{1}{(PolynomialIdeals(Fraction(Integer), 
DirectProduct(nv, NonNegativeInteger), vl, 
DistributedMultivariatePolynomial(vl, Fraction(Integer))))->Boolean}
{IdealDecompositionPackage}
{\smath{\mbox{\bf zeroDimPrime?}\opLeftPren{}I\opRightPren{}} 
tests if the ideal \smath{I} is a
0-dimensional prime.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zeroOf}}\opLeftPren{}
{\it polynomial\opt{, symbol}}\opRightPren{}%
}%
}%
{2}{(SparseUnivariatePolynomial(\$), Symbol)->\$}{AlgebraicallyClosedField}
{\smath{\mbox{\bf zeroOf}\opLeftPren{}p\optinner{, y}\opRightPren{}} 
returns \smath{y} such that
\smath{p(y) = 0}.
If possible, \smath{y} is expressed in terms of radicals.
Otherwise it is an implicit algebraic quantity that displays as \smath{'y}.
If no second argument is given, then \smath{p} must have a unique
variable \smath{y}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zerosOf}}\opLeftPren{}
{\it polynomial\opt{, symbol}}\opRightPren{}%
}%
}%
{1}{(Polynomial(\$))->List(\$)}{AlgebraicallyClosedField}
{\smath{\mbox{\bf zerosOf}\opLeftPren{}p, \allowbreak{} y\opRightPren{}} 
returns \smath{[y_1, \ldots, y_n]} such
that \smath{p(y_i) = 0}.
The \smath{y_i}'s are expressed in radicals if possible.
Otherwise they are implicit algebraic quantities that display as
\smath{y_i}.
The returned symbols \smath{y_1}, \ldots, \smath{y_n} are bound in
the interpreter to respective root values.
If no second argument is given, then \smath{p} must have a unique
variable \smath{y}.
}

% ----------------------------------------------------------------------
\opdata{{\mbox{\axiomFun{zRange}}\opLeftPren{}{\it curve}\opRightPren{}%
}%
}%
{1}{(\$)->Segment(DoubleFloat)}{PlottableSpaceCurveCategory}
{\smath{\mbox{\bf zRange}\opLeftPren{}c\opRightPren{}} 
returns the range of the \smath{z}-coordinates
of the points on the curve \smath{c}.
}
}\onecolumn
%\setcounter{chapter}{5} % Appendix F

%Original Page 691

\chapter{Programs for Axiom Images}
\label{ugAppGraphics}

%
This appendix contains the Axiom programs used to generate
the images in the gallery color insert of this book.
All these input files are included
with the Axiom system.
To produce the images
on page 6 of the gallery insert, for example, issue the command:
\begin{verbatim}
)read images6
\end{verbatim}

These images were produced on an IBM RS/6000 model 530 with a
standard color graphics adapter.  The smooth shaded images
were made from X Window System screen dumps.
The remaining images were produced with Axiom-generated
PostScript output.  The images were reproduced from slides made on an Agfa
ChromaScript PostScript interpreter with a Matrix Instruments QCR camera.


\section{images1.input}
\label{ugFimagesOne}


\begin{verbatim}
)read tknot                                      Read torus knot program

torusKnot(15,17, 0.1, 6, 700)                    A (15,17) torus knot
\end{verbatim}
\index{torus knot}

\newpage

\section{images2.input}
\label{ugFimagesTwo}

These images illustrate how Newton's method converges when computing the
\index{Newton iteration}
complex cube roots of 2.   Each point in the $(x,y)$-plane represents the
complex number $x + iy,$ which is given as a starting point for Newton's
method.  The poles in these images represent bad starting values.
The flat areas are the regions of convergence to the three roots.

\begin{verbatim}
)read newton                               Read the programs from
)read vectors                              Chapter 10
f := newtonStep(x**3 - 2)                  Create a Newton's iteration
                                            function for $x^3 = 2$
\end{verbatim}

The function $f^n$ computes $n$ steps of Newton's method.

\begin{verbatim}
clipValue := 4                              Clip values with magnitude > 4
drawComplexVectorField(f**3, -3..3, -3..3)  The vector field for $f^3$
drawComplex(f**3, -3..3, -3..3)             The surface for $f^3$
drawComplex(f**4, -3..3, -3..3)             The surface for $f^4$
\end{verbatim}

\section{images3.input}
\label{ugFimagesThree}


\begin{verbatim}
)r tknot
for i in 0..4 repeat torusKnot(2, 2 + i/4, 0.5, 25, 250)
\end{verbatim}

\section{images5.input}
\label{ugFimagesFive}


The parameterization of the Etruscan Venus is due to George Frances.
\index{Etruscan Venus}

\begin{verbatim}
venus(a,r,steps) ==
  surf := (u:DFLOAT, v:DFLOAT): Point DFLOAT +->
    cv := cos(v)
    sv := sin(v)
    cu := cos(u)
    su := sin(u)
    x := r * cos(2*u) * cv + sv * cu
    y := r * sin(2*u) * cv - sv * su
    z := a * cv
    point [x,y,z]
  draw(surf, 0..\%pi, -\%pi..\%pi, var1Steps==steps,
       var2Steps==steps, title == "Etruscan Venus")

venus(5/2, 13/10, 50)                                  The Etruscan Venus
\end{verbatim}

The Figure-8 Klein Bottle
\index{Klein bottle}
parameterization is from
``Differential Geometry and Computer Graphics'' by Thomas Banchoff,
in {\it Perspectives in Mathematics,} Anniversary of Oberwolfasch 1984,
Birkh\"{a}user-Verlag, Basel, pp. 43-60.

\begin{verbatim}
klein(x,y) ==
  cx := cos(x)
  cy := cos(y)
  sx := sin(x)
  sy := sin(y)
  sx2 := sin(x/2)
  cx2 := cos(x/2)
  sq2 := sqrt(2.0@DFLOAT)
  point [cx * (cx2 * (sq2 + cy) + (sx2 * sy * cy)), _
         sx * (cx2 * (sq2 + cy) + (sx2 * sy * cy)), _
         -sx2 * (sq2 + cy) + cx2 * sy * cy]

draw(klein, 0..4*\%pi, 0..2*\%pi, var1Steps==50,       Figure-8 Klein bottle
     var2Steps==50,title=="Figure Eight Klein Bottle")
\end{verbatim}

The next two images are examples of generalized tubes.

\begin{verbatim}
)read ntube
rotateBy(p, theta) ==                            Rotate a point $p$ by
  c := cos(theta)                                $\theta$ around the origin
  s := sin(theta)
  point [p.1*c - p.2*s, p.1*s + p.2*c]

bcircle t ==                                     A circle in three-space
  point [3*cos t, 3*sin t, 0]

twist(u, t) ==                                   An ellipse that twists
  theta := 4*t                                   around four times as
  p := point [sin u, cos(u)/2]                   $t$ revolves once
  rotateBy(p, theta)

ntubeDrawOpt(bcircle, twist, 0..2*\%pi, 0..2*\%pi,    Twisted Torus
             var1Steps == 70, var2Steps == 250)

twist2(u, t) ==                                 Create a twisting circle
  theta := t
  p := point [sin u, cos(u)]
  rotateBy(p, theta)

cf(u,v) == sin(21*u)                    Color function with $21$ stripes

ntubeDrawOpt(bcircle, twist2, 0..2*\%pi, 0..2*\%pi,        Striped Torus
  colorFunction == cf, var1Steps == 168,
  var2Steps == 126)
\end{verbatim}

\section{images6.input}
\label{ugFimagesSix}

\begin{verbatim}
-- The height and coloar are the real and argument parts
-- of the Gamma function, respectively.
gam(x,y) ==                                        
  g := Gamma complex(x,y)                          
  point [x,y,max(min(real g, 4), -4), argument g]  
                                                   

draw(gam, -\%pi..\%pi, -\%pi..\%pi,                The Gamma Function
     title == "Gamma(x + \%i*y)", _
     var1Steps == 100, var2Steps == 100)

b(x,y) == Beta(x,y)

draw(b, -3.1..3, -3.1 .. 3, title == "Beta(x,y)")  The Beta Function

atf(x,y) == 
  a := atan complex(x,y)
  point [x,y,real a, argument a]

draw(atf, -3.0..\%pi, -3.0..\%pi)                  The Arctangent function
\end{verbatim}
\index{function!Gamma}
\index{function!Euler Beta}
\index{Euler!Beta function}


\section{images7.input}
\label{ugFimagesSeven}

First we look at the conformal
\index{conformal map}
map $z \mapsto z + 1/z$.
\begin{verbatim}
)read conformal                                    
-- Read program for drawing conformal maps

-- The coordinate grid for the complex plane
f z == z                                           

-- Mapping 1: Source                                                   
conformalDraw(f, -2..2, -2..2, 9, 9, "cartesian")  

-- The map z mapsto z + 1/z
f z == z + 1/z                                     

-- Mapping 1: Target
conformalDraw(f, -2..2, -2..2, 9, 9, "cartesian")  

\end{verbatim}

The map $z \mapsto -(z+1)/(z-1)$ maps
the unit disk to the right half-plane, as shown
\index{Riemann!sphere}
on the Riemann sphere.

\begin{verbatim}
-- The unit disk
f z == z                                                      

-- Mapping 2: Source
riemannConformalDraw(f,0.1..0.99,0..2*\%pi,7,11,"polar")      

-- The map x mapsto -(z+1)/(z-1)
f z == -(z+1)/(z-1)                            

-- Mapping 2: Target
riemannConformalDraw(f,0.1..0.99,0..2*\%pi,7,11,"polar")      

-- Riemann Sphere Mapping
riemannSphereDraw(-4..4, -4..4, 7, 7, "cartesian")       
\end{verbatim}

\section{images8.input}
\label{ugFimagesEight}

\begin{verbatim}
)read dhtri
)read tetra
drawPyramid 4                              Sierpinsky's Tetrahedron

Sierpinsky's Tetrahedron
)read antoine
drawRings 2                                      Antoine's Necklace

Aintoine's Necklace
)read scherk
drawScherk(3,3)                            Scherk's Minimal Surface

)read ribbonsnew
drawRibbons([x**i for i in 1..5], x=-1..1, y=0..2)      Ribbon Plot
\end{verbatim}
\index{Scherk's minimal surface}


%\input{gallery/conformal.htex}
\section{conformal.input}
\label{ugFconformal}
%
The functions in this section draw conformal maps both on the
\index{conformal map}
plane and on the Riemann sphere.
\index{Riemann!sphere}

%-- Compile, don't interpret functions.
%\xmpLine{)set fun comp on}{}
\begin{verbatim}
C := Complex DoubleFloat                        Complex Numbers
S := Segment DoubleFloat                        Draw ranges
R3 := Point DFLOAT                              Points in 3-space
\end{verbatim}

{\bf conformalDraw}{\it (f, rRange, tRange, rSteps, tSteps, coord)}
draws the image of the coordinate grid under {\it f} in the complex plane.
The grid may be given in either polar or Cartesian coordinates.
Argument {\it f} is the function to draw;
{\it rRange} is the range of the radius (in polar) or real (in Cartesian);
{\it tRange} is the range of $\theta$ (in polar) or imaginary (in Cartesian);
{\it tSteps, rSteps}, are the number of intervals in the {\it r} and
$\theta$ directions; and
{\it coord} is the coordinate system to use (either {\tt "polar"} or
{\tt "cartesian"}).

\begin{verbatim}
conformalDraw: (C -> C, S, S, PI, PI, String) -> VIEW3D
conformalDraw(f,rRange,tRange,rSteps,tSteps,coord) ==
  -- Function for changing an (x,y)
  transformC :=                               
    -- pair into a complex number
    coord = "polar" => polar2Complex                 
    cartesian2Complex
  cm := makeConformalMap(f, transformC)
  -- Create a fresh space
  sp := createThreeSpace()                            
  -- Plot the coordinate lines
  adaptGrid(sp, cm, rRange, tRange, rSteps, tSteps)   
  -- Draw the image
  makeViewport3D(sp, "Conformal Map")                 
\end{verbatim}

{\bf riemannConformalDraw}{\it (f, rRange, tRange, rSteps, tSteps, coord)}
draws the image of the coordinate grid under {\it f} on the Riemann sphere.
The grid may be given in either polar or Cartesian coordinates.
Its arguments are the same as those for {\bf conformalDraw}.

\begin{verbatim}
riemannConformalDraw:(C->C,S,S,PI,PI,String)->VIEW3D
riemannConformalDraw(f, rRange, tRange,
                     rSteps, tSteps, coord) ==
  -- Function for changing an $(x,y)$
  transformC :=                               
    -- pair into a complex number
    coord = "polar" => polar2Complex          
    cartesian2Complex
  -- Create a fresh space
  sp := createThreeSpace()                    
  cm := makeRiemannConformalMap(f, transformC)
  -- Plot the coordinate lines
  adaptGrid(sp, cm, rRange, tRange, rSteps, tSteps)  
  curve(sp,[point [0,0,2.0@DFLOAT,0],point [0,0,2.0@DFLOAT,0] ])
  -- Add an invisible point at the north pole for scaling
  makeViewport3D(sp,"Map on the Riemann Sphere")     

-- Plot the coordinate grid
adaptGrid(sp, f, uRange, vRange,  uSteps, vSteps) == 
  -- using adaptive plotting for coordinate lines, and draw
  -- tubes around the lines
  delU := (hi(uRange) - lo(uRange))/uSteps         
  delV := (hi(vRange) - lo(vRange))/vSteps        
  uSteps := uSteps + 1; vSteps := vSteps + 1      
  u := lo uRange
  -- Draw coordinate lines in the v direction; curve c fixes the
  -- current value of u
  for i in 1..uSteps repeat                    
    c := curryLeft(f,u)                        
    cf := (t:DFLOAT):DFLOAT +-> 0             
    makeObject(c,vRange::SEG Float,colorFunction==cf,
      -- Draw the v coordinate line
      space == sp, tubeRadius == .02, tubePoints == 6)
    u := u + delU
  v := lo vRange
  -- Draw coodinate lines in the u direction; curve c fixes the
  -- current value of v
  for i in 1..vSteps repeat                    
    c := curryRight(f,v)                      
    cf := (t:DFLOAT):DFLOAT +-> 1              
    makeObject(c,uRange::SEG Float,colorFunction==cf,
      -- Draw the u coordinate line
      space == sp, tubeRadius == .02, tubePoints == 6)
    v := v + delV
  void()

-- Map a point in the complex plane to the Riemann sphere
riemannTransform(z) ==                         
  r := sqrt norm z                            
  cosTheta := (real z)/r
  sinTheta := (imag z)/r
  cp := 4*r/(4+r**2)
  sp := sqrt(1-cp*cp)
  if r>2 then sp := -sp
  point [cosTheta*cp, sinTheta*cp, -sp + 1]

-- Convert Cartesian coordinates to complex Cartesian form
cartesian2Complex(r:DFLOAT, i:DFLOAT):C ==   
  complex(r, i)                              

-- Convert polar coordinates to complex Cartesian form
polar2Complex(r:DFLOAT, th:DFLOAT):C ==       
  complex(r*cos(th), r*sin(th))               

-- Convert complex function f to a mapping: (DFLOAT,DFLOAT) maps to R3
-- in the complex plane
makeConformalMap(f, transformC) ==            
  (u:DFLOAT,v:DFLOAT):R3 +->                  
    z := f transformC(u, v)                   
    point [real z, imag z, 0.0@DFLOAT]

-- Convert a complex function f to a mapping: (DFLOAT,DFLOAT) maps to R3
-- on the Riemann sphere
makeRiemannConformalMap(f, transformC) ==     
  (u:DFLOAT, v:DFLOAT):R3 +->                 
    riemannTransform f transformC(u, v)       

-- Draw a picture of the mapping of the complex plane to
-- the Riemann sphere
riemannSphereDraw: (S, S, PI, PI, String) -> VIEW3D
riemannSphereDraw(rRange,tRange,rSteps,tSteps,coord) ==
  transformC :=
    coord = "polar" => polar2Complex
    cartesian2Complex
  -- Coordinate grid function
  grid := (u:DFLOAT, v:DFLOAT): R3 +->                 
    z1 := transformC(u, v)
    point [real z1, imag z1, 0]
  -- Create a fresh space
  sp := createThreeSpace()                                 
  -- Draw the flat grid
  adaptGrid(sp, grid, rRange, tRange, rSteps, tSteps)      
  connectingLines(sp,grid,rRange,tRange,rSteps,tSteps)
  -- Draw the sphere
  makeObject(riemannSphere,0..2*\%pi,0..\%pi,space==sp)    
  f := (z:C):C +-> z
  cm := makeRiemannConformalMap(f, transformC)
  -- Draw the sphere grid
  adaptGrid(sp, cm, rRange, tRange, rSteps, tSteps)        
  makeViewport3D(sp, "Riemann Sphere")
 
-- Draw the lines that connect the points in the complex
-- plane to the north pole of the Riemann sphere
connectingLines(sp,f,uRange,vRange,uSteps,vSteps) ==
  delU := (hi(uRange) - lo(uRange))/uSteps          
  delV := (hi(vRange) - lo(vRange))/vSteps          
  uSteps := uSteps + 1; vSteps := vSteps + 1        
  u := lo uRange
  for i in 1..uSteps repeat                         
    v := lo vRange
    for j in 1..vSteps repeat                       
      p1 := f(u,v)
      -- Project p1 onto the sphere
      p2 := riemannTransform complex(p1.1, p1.2)    
      -- Create a line function
      fun := lineFromTo(p1,p2)                      
      cf := (t:DFLOAT):DFLOAT +-> 3
      -- Draw the connecting line
      makeObject(fun, 0..1,space==sp,tubePoints==4, 
                 tubeRadius==0.01,colorFunction==cf)
      v := v + delV
    u := u + delU
  void()

-- A sphere sitting on the complex plane, with radius 1
riemannSphere(u,v) ==                              
  sv := sin(v)                                     
  0.99@DFLOAT*(point [cos(u)*sv,sin(u)*sv,cos(v),0.0@DFLOAT])+
    point [0.0@DFLOAT, 0.0@DFLOAT, 1.0@DFLOAT, 4.0@DFLOAT]
 
-- Create a line function that goes from p1 to p2
lineFromTo(p1, p2) ==                              
  d := p2 - p1                                     
  (t:DFLOAT):Point DFLOAT +->
    p1 + t*d
\end{verbatim}

%\input{gallery/tknot.htex}
\section{tknot.input}
\label{ugFtknot}
%
Create a $(p,q)$ torus-knot with radius $r$ around the curve.
The formula was derived by Larry Lambe.

\begin{verbatim}
)read ntube
torusKnot: (DFLOAT, DFLOAT, DFLOAT, PI, PI) -> VIEW3D
torusKnot(p, q ,r, uSteps, tSteps) ==
  -- Function for the torus knot
  knot := (t:DFLOAT):Point DFLOAT +->               
    fac := 4/(2.2@DFLOAT-sin(q*t))
    fac * point [cos(p*t), sin(p*t), cos(q*t)]
  -- The cross section
  circle := (u:DFLOAT, t:DFLOAT): Point DFLOAT +->  
    r * point [cos u, sin u]
  -- Draw the circle around the knot
  ntubeDrawOpt(knot, circle, 0..2*\%pi, 0..2*\%pi,                             
               var1Steps == uSteps, var2Steps == tSteps)

\end{verbatim}

%\input{gallery/ntube.htex}
\section{ntube.input}
\label{ugFntube}
%
The functions in this file create generalized tubes (also known as generalized
cylinders).
These functions draw a 2-d curve in the normal
planes around a 3-d curve.

\begin{verbatim}
R3 := Point DFLOAT                    Points in 3-Space
R2 := Point DFLOAT                    Points in 2-Space
S := Segment Float                    Draw ranges
                                      Introduce types for functions:
ThreeCurve := DFLOAT -> R3            --the space curve function
TwoCurve := (DFLOAT, DFLOAT) -> R2    --the plane curve function
Surface := (DFLOAT, DFLOAT) -> R3     --the surface function
                                      Frenet frames define a
FrenetFrame :=                        coordinate system around a
   Record(value:R3,tangent:R3,normal:R3,binormal:R3)
                                      point on a space curve
frame: FrenetFrame                    The current Frenet frame
                                      for a point on a curve
\end{verbatim}

{\bf ntubeDraw}{\it (spaceCurve, planeCurve,}
$u_0 .. u_1,$ $t_0 .. t_1)$
draws {\it planeCurve} in the normal planes of {\it spaceCurve.}
The parameter $u_0 .. u_1$ specifies
the parameter range for {\it planeCurve}
and $t_0 .. t_1$ specifies the parameter range for {\it spaceCurve}.
Additionally, the plane curve function takes
a second parameter: the current parameter of {\it spaceCurve}.
This allows the plane curve to change shape
as it goes around the space curve.
See \sectionref{ugFimagesFive} for an example of this.
%
\begin{verbatim}
ntubeDraw: (ThreeCurve,TwoCurve,S,S) -> VIEW3D
ntubeDraw(spaceCurve,planeCurve,uRange,tRange) ==
  ntubeDrawOpt(spaceCurve, planeCurve, uRange, _
               tRange, []$List DROPT)

ntubeDrawOpt: (ThreeCurve,TwoCurve,S,S,List DROPT) -> VIEW3D
-- This function is similar to ntubeDraw, but takes
-- optional parameters that it passes to the draw command
ntubeDrawOpt(spaceCurve,planeCurve,uRange,tRange,l) ==
  delT:DFLOAT := (hi(tRange) - lo(tRange))/10000  
  oldT:DFLOAT := lo(tRange) - 1                   
  fun := ngeneralTube(spaceCurve,planeCurve,delT,oldT)
  draw(fun, uRange, tRange, l)

\end{verbatim}

{\bf nfrenetFrame}{\it (c, t, delT)}
numerically computes the Frenet frame
about the curve {\it c} at {\it t}.
Parameter {\it delT} is a small number used to
compute derivatives.
\begin{verbatim}
nfrenetFrame(c, t, delT) ==
  f0 := c(t)
  f1 := c(t+delT)
  t0 := f1 - f0                              The tangent
  n0 := f1 + f0
  b := cross(t0, n0)                         The binormal
  n := cross(b,t0)                           The normal
  ln := length n
  lb := length b
  ln = 0 or lb = 0 =>
      error "Frenet Frame not well defined"
  n := (1/ln)*n                              Make into unit length vectors
  b := (1/lb)*b
  [f0, t0, n, b]$FrenetFrame
\end{verbatim}

{\bf ngeneralTube}{\it (spaceCurve, planeCurve,}{\it  delT, oltT)}
creates a function that can be passed to the system axiomFun{draw} command.
The function is a parameterized surface for the general tube
around {\it spaceCurve}.  {\it delT} is a small number used to compute
derivatives. {\it oldT} is used to hold the current value of the
{\it t} parameter for {\it spaceCurve.}  This is an efficiency measure
to ensure that frames are only computed once for each value of {\it t}.
\begin{verbatim}
ngeneralTube: (ThreeCurve, TwoCurve, DFLOAT, DFLOAT) -> Surface
ngeneralTube(spaceCurve, planeCurve, delT, oldT) ==
  -- Indicate that frame is global
  free frame                                   
  (v:DFLOAT, t: DFLOAT): R3 +->
    -- If not already computed compute new frame
    if (t $\sim$= oldT) then                      
      frame := nfrenetFrame(spaceCurve, t, delT)  
      oldT := t
    p := planeCurve(v, t)
    -- Project $p$ into the normal plane
    frame.value + p.1*frame.normal + p.2*frame.binormal
                                              
\end{verbatim}

%\input{gallery/dhtri.htex}
\section{dhtri.input}
\label{ugFdhtri}
%
Create affine transformations (DH matrices) that transform
a given triangle into another.

\begin{verbatim}
tri2tri: (List Point DFLOAT, List Point DFLOAT) -> DHMATRIX(DFLOAT)
-- Compute a DHMATRIX that transforms t1 to t2, where
-- t1 and t2 are the vertices of two triangles in 3-space
tri2tri(t1, t2) ==                              
  n1 := triangleNormal(t1)                      
  n2 := triangleNormal(t2)                     
  tet2tet(concat(t1, n1), concat(t2, n2))

tet2tet: (List Point DFLOAT, List Point DFLOAT) -> DHMATRIX(DFLOAT)
-- Compute a DHMATRIX that transforms t1 to t2, where t1 and t2 
-- are the vertices of two tetrahedrons in 3-space
tet2tet(t1, t2) ==                             
  m1 := makeColumnMatrix t1                     
  m2 := makeColumnMatrix t2                     
  m2 * inverse(m1)                              

-- Put the vertices of a tetrahedron into matrix form
makeColumnMatrix(t) ==                          
  m := new(4,4,0)$DHMATRIX(DFLOAT)              
  for x in t for i in 1..repeat
    for j in 1..3 repeat
      m(j,i) := x.j
    m(4,i) := 1
  m

-- Compute a vector normal to the given triangle, whose
-- length is the square root of the area of the triangle
triangleNormal(t) ==                            
  a := triangleArea t                           
  p1 := t.2 - t.1                               
  p2 := t.3 - t.2                               
  c := cross(p1, p2)
  len := length(c)
  len = 0 => error "degenerate triangle!"
  c := (1/len)*c
  t.1 + sqrt(a) * c

-- Compute the area of a triangle using Heron's formula
triangleArea t ==                               
  a := length(t.2 - t.1)                        
  b := length(t.3 - t.2)                        
  c := length(t.1 - t.3)
  s := (a+b+c)/2
  sqrt(s*(s-a)*(s-b)*(s-c))
\end{verbatim}

\section{tetra.input}
\label{ugFtetra}
%
%\input{gallery/tetra.htex}
%\outdent{Sierpinsky's Tetrahedron}

\begin{verbatim}
-- Bring DH matrices into the environment
)set expose add con DenavitHartenbergMatrix      
                                         
-- Set up the coordinates of the corners of the tetrahedron.
x1:DFLOAT := sqrt(2.0@DFLOAT/3.0@DFLOAT)         
x2:DFLOAT := sqrt(3.0@DFLOAT)/6                  

p1 := point [-0.5@DFLOAT, -x2, 0.0@DFLOAT]       
p2 := point [0.5@DFLOAT, -x2, 0.0@DFLOAT]
p3 := point [0.0@DFLOAT, 2*x2, 0.0@DFLOAT]
p4 := point [0.0@DFLOAT, 0.0@DFLOAT, x1]

-- The base of the tetrahedron
baseTriangle  := [p2, p1, p3]                    

-- The middle triangle inscribed in the base of the tetrahedron
-- The bases of the triangles of the subdivided tetrahedron
mt  := [0.5@DFLOAT*(p2+p1), 0.5@DFLOAT*(p1+p3), 0.5@DFLOAT*(p3+p2)]
                                                 
bt1 := [mt.1, p1, mt.2]                          
bt2 := [p2, mt.1, mt.3]                          
bt3 := [mt.2, p3, mt.3]
bt4 := [0.5@DFLOAT*(p2+p4), 0.5@DFLOAT*(p1+p4), 0.5@DFLOAT*(p3+p4)]

-- Create the transformations that bring the base of the
-- tetrahedron to the bases of the subdivided tetrahedron
tt1 := tri2tri(baseTriangle, bt1)                
tt2 := tri2tri(baseTriangle, bt2)                
tt3 := tri2tri(baseTriangle, bt3)                
tt4 := tri2tri(baseTriangle, bt4)                

-- Draw a Sierpinsky tetrahedron with n levels of recursive
-- subdivision
drawPyramid(n) ==                                
  s := createThreeSpace()                        
  dh := rotatex(0.0@DFLOAT)                      
  drawPyramidInner(s, n, dh)
  makeViewport3D(s, "Sierpinsky Tetrahedron")

-- Recursively draw a Sierpinsky tetrahedron
-- Draw the 4 recursive pyramids
drawPyramidInner(s, n, dh) ==                    
  n = 0 => makeTetrahedron(s, dh, n)             
  drawPyramidInner(s, n-1, dh * tt1)             
  drawPyramidInner(s, n-1, dh * tt2)
  drawPyramidInner(s, n-1, dh * tt3)
  drawPyramidInner(s, n-1, dh * tt4)

-- Draw a tetrahedron into the given space with the given
-- color, transforming it by the given DH matrix
makeTetrahedron(sp, dh, color) ==                
  w1 := dh*p1                                    
  w2 := dh*p2                                    
  w3 := dh*p3                                    
  w4 := dh*p4
  polygon(sp, [w1, w2, w4])
  polygon(sp, [w1, w3, w4])
  polygon(sp, [w2, w3, w4])
  void()
\end{verbatim}
\index{Sierpinsky's Tetrahedron}


%\input{gallery/antoine.htex}
\section{antoine.input}
\label{ugFantoine}
%
Draw Antoine's Necklace.
\index{Antoine's Necklace}
Thank you to Matthew Grayson at IBM's T.J Watson Research Center for the idea.

\begin{verbatim}
-- Bring DH matrices into the environment
)set expose add con DenavitHartenbergMatrix           
                                         
-- The transformation for drawing a sub ring
torusRot: DHMATRIX(DFLOAT)                            
                                                      
-- Draw Antoine's Necklace with n levels of recursive subdivision
-- The number of subrings is 10^n. Do the real work
drawRings(n) ==                                
  s := createThreeSpace()                      
  dh:DHMATRIX(DFLOAT) := identity()            
  drawRingsInner(s, n, dh)                     
  makeViewport3D(s, "Antoine's Necklace")

\end{verbatim}

In order to draw Antoine rings, we take one ring, scale it down to
a smaller size, rotate it around its central axis, translate it
to the edge of the larger ring and rotate it around the edge to
a point corresponding to its count (there are 10 positions around
the edge of the larger ring). For each of these new rings we
recursively perform the operations, each ring becoming 10 smaller
rings. Notice how the {\bf DHMATRIX} operations are used to build up
the proper matrix composing all these transformations.

\begin{verbatim}
-- Recursively draw Antoine's Necklace
drawRingsInner(s, n, dh) ==                   
  n = 0 =>                                    
    drawRing(s, dh)
    void()
  t := 0.0@DFLOAT               Angle around ring
  p := 0.0@DFLOAT               Angle of subring from plane
  tr := 1.0@DFLOAT              Amount to translate subring
  inc := 0.1@DFLOAT             The translation increment
  for i in 1..10 repeat         Subdivide into 10 linked rings
    tr := tr + inc
    inc := -inc
    -- Transform ring in center to a link
    dh' := dh*rotatez(t)*translate(tr,0.0@DFLOAT,0.0@DFLOAT)*
           rotatey(p)*scale(0.35@DFLOAT, 0.48@DFLOAT, 0.4@DFLOAT)
    drawRingsInner(s, n-1, dh')
    t := t + 36.0@DFLOAT
    p := p + 90.0@DFLOAT
  void()

-- Draw a single ring into the given subspace,
-- transformed by the given DHMATRIX
drawRing(s, dh) ==                            
  free torusRot                               
  torusRot := dh                              
  makeObject(torus, 0..2*\%pi, 0..2*\%pi, var1Steps == 6,
             space == s, var2Steps == 15)

-- Parameterization of a torus, transformed by the
-- DHMATRIX in torusRot.
torus(u ,v) ==                                
  cu := cos(u)/6                              
                                              
  torusRot*point [(1+cu)*cos(v),(1+cu)*sin(v),(sin u)/6]
\end{verbatim}

%\input{gallery/scherk.htex}
\section{scherk.input}
\label{ugFscherk}
%

Scherk's minimal surface, defined by:
\index{Scherk's minimal surface}
$e^z \cos(x) = \cos(y)$.
See: {\it A Comprehensive Introduction to Differential Geometry,} Vol. 3,
by Michael Spivak, Publish Or Perish, Berkeley, 1979, pp. 249-252.

\begin{verbatim}
-- Offsets for a single piece of Scherk's minimal surface
(xOffset, yOffset):DFLOAT                        

-- Draw Scherk's minimal surface on an m by n patch
drawScherk(m,n) ==                               
  free xOffset, yOffset                         
  space := createThreeSpace()
  for i in 0..m-1 repeat
    xOffset := i*\%pi
    for j in 0 .. n-1 repeat
      -- Draw only odd patches
      rem(i+j, 2) = 0 => 'iter                   
      yOffset := j*\%pi
      -- Draw a patch
      drawOneScherk(space)                       
  makeViewport3D(space, "Scherk's Minimal Surface")

-- The first patch that makes up a single piece of
--  Scherk's minimal surface
scherk1(u,v) ==                                     
  x := cos(u)/exp(v)                                
  point [xOffset + acos(x), yOffset + u, v, abs(v)] 

-- The second patch
scherk2(u,v) ==                                      
  x := cos(u)/exp(v)
  point [xOffset - acos(x), yOffset + u, v, abs(v)]

-- The third patch
scherk3(u,v) ==                                      
  x := exp(v) * cos(u)
  point [xOffset + u, yOffset + acos(x), v, abs(v)]

-- The fourth patch
scherk4(u,v) ==                                     
  x := exp(v) * cos(u)
  point [xOffset + u, yOffset - acos(x), v, abs(v)]

-- Draw the surface by breaking it into four
-- patches and then drawing the patches
drawOneScherk(s) ==                                 
  makeObject(scherk1,-\%pi/2..\%pi/2,0..\%pi/2,space==s,
             var1Steps == 28, var2Steps == 28)       
  makeObject(scherk2,-\%pi/2..\%pi/2,0..\%pi/2,space==s,
             var1Steps == 28, var2Steps == 28)
  makeObject(scherk3,-\%pi/2..\%pi/2,-\%pi/2..0,space==s,
             var1Steps == 28, var2Steps == 28)
  makeObject(scherk4,-\%pi/2..\%pi/2,-\%pi/2..0,space==s,
             var1Steps == 28, var2Steps == 28)
  void()
\end{verbatim}

%Original Page 703

{

%\setcounter{chapter}{6} % Appendix G
\chapter{Glossary}
\label{ugGlossary}

\sloppy

\ourGloss{\glossarySyntaxTerm{!}}{%
{\it (syntax)}
Suffix character
\index{operation!destructive}
for destructive operations.
}

\ourGloss{\glossarySyntaxTerm{,}}{%
{\it (syntax)}
a separator for items in a {\it tuple},
for example, to separate arguments of a function $f(x,y)$.
}


\ourGloss{\glossarySyntaxTerm{\tt =>}}{%
{\it (syntax)}
the expression $a => b$ is equivalent to $if a
then$ {\it exit} $b$.
}


\ourGloss{\glossarySyntaxTerm{?}}{%
1.
{\it (syntax)} a suffix character for Boolean-valued {\bf function}
names, for example, {\bf odd?}.
2.
Prefix character for ``optional'' pattern variables. For example,
the pattern $f(x + y)$ does not match the expression $f(7)$,
but $f(?x + y)$ does, with $x$ matching 0 and $y$ matching 7.
3.
The special type {\bf ?} means {\it don't care}.
For example, the declaration: $x : Polynomial ?$ means
that values assigned to $x$ must be polynomials over an arbitrary
{\it underlying domain}.
}

\ourGloss{\glossaryTerm{abstract datatype}}{%
a programming language principle used in Axiom where a datatype definition has
defined in two parts: (1) a {\it public} part describing a set of
exports,
principally operations that apply to objects of that
type, and (2) a {\it private} part describing the implementation of the
datatype usually in terms of a {\it representation} for objects of
the type.
Programs that create and otherwise manipulate objects of the type may
only do so through its exports.
The representation and other implementation information is specifically
hidden.
}

\ourGloss{\glossaryTerm{abstraction}}{%
described functionally or conceptually without regard to implementation.
}


\ourGloss{\glossaryTerm{accuracy}}{%
the degree of exactness of an approximation or measurement.
In computer algebra systems, computations are typically carried out with
complete accuracy using integers or rational numbers of indefinite size.
Domain {\bf Float} provides a function
\spadfunFrom{precision}{Float} to change the precision for floating-point
computations. Computations using {\bf DoubleFloat} have a fixed
precision but uncertain accuracy.
}


\ourGloss{\glossaryTerm{add-chain}}{%
a hierarchy formed by domain extensions.
If domain $A$ extends domain $B$ and domain $B$ extends
domain $C$, then $A$ has {\it add-chain} $B$-$C$.
}


\ourGloss{\glossaryTerm{aggregate}}{%
a data structure designed to hold multiple values.
Examples of aggregates are {\bf List}, {\bf Set},
{\bf Matrix} and {\bf Bits}.
}


\ourGloss{\glossaryTerm{AKCL}}{%
Austin Kyoto Common LISP, a version of {\it KCL} produced
by William Schelter, Austin, Texas.
}


\ourGloss{\glossaryTerm{algorithm}}{%
a step-by-step procedure for a solution of a problem; a program
}


\ourGloss{\glossaryTerm{ancestor}}{%
(of a domain or category) a category that is a {\it parent}, or
a {\it parent} of a {\it parent}, and so on.
See a {\bf Cross Reference} page of a constructor in Browse.
}


\ourGloss{\glossaryTerm{application}}{%
{\it (syntax)} an expression denoting ``application'' of a function to a
set of {\it argument} parameters.
Applications are written as a {\it parameterized form}.
For example, the form $f(x,y)$ indicates the ``application of the
function $f$ to the tuple of arguments $x$ and $y$.''
See also {\it evaluation} and {\it invocation}.
}


\ourGloss{\glossaryTerm{apply}}{%
See {\it application}.
}


\ourGloss{\glossaryTerm{argument}}{%
1.
(actual argument) a value passed to a function at the time of a
function call; also called an {\it actual
parameter}. 2.
(formal argument) a variable used in the definition of a function to
denote the actual argument passed when the function is called.
}


\ourGloss{\glossaryTerm{arity}}{%
1.
(function) the number of arguments.
2.
(operator or operation) corresponds to the arity of a function
implementing the operator or operation.
}


\ourGloss{\glossaryTerm{assignment}}{%
{\it (syntax)} an expression of the form $x := e$, meaning
``assign the value of $e$ to $x$.''
After {\it evaluation}, the {\it variable} $x$
points to an object obtained by evaluating
the expression $e$.
If $x$ has a {\it type} as a result of a previous
{\it declaration}, the object assigned to $x$ must have
that type.
The interpreter must often coerce the
value of $e$ to make that happen.
For example, the expression $x : Float := 11$
first declares $x$ to be a float, then
forces the interpreter to coerce the integer $11$ to
$11.0$ in order to assign a floating-point value to $x$.
}


\ourGloss{\glossaryTerm{attribute}}{%
a name or functional form denoting {\it any} 
useful computational or mathematical
property. For example, {\bf commutative($"*"$)} asserts that
$*$ is commutative.
Also, {\bf finiteAggregate} is used to assert that an aggregate has
a finite number of immediate components.
}


\ourGloss{\glossaryTerm{basis}}{%
{\it (algebra)} $S$ is a basis of a module $M$ over a
{\it ring} if $S$ generates $M$, and $S$ is linearly
independent.
}


\ourGloss{\glossaryTerm{benefactor}}{%
(of a given domain) a domain or package that the given domain explicitly
references (for example, calls functions from) in its implementation.
See a {\bf Cross Reference} page of a constructor in Browse.
}


\ourGloss{\glossaryTerm{binary}}{%
operation or function with {\it arity} 2.
}


\ourGloss{\glossaryTerm{binding}}{%
the association of a variable with properties such as {\it value}
and {\it type}.
The top-level {\it environment} in the interpreter consists of
bindings for all user variables and functions.
When a {\it function} is applied to arguments, a local environment
of bindings is created, one for
each formal {\it argument} and {\it local variable}.
}


\ourGloss{\glossaryTerm{block}}{%
{\it (syntax)} a control structure where expressions are sequentially
evaluated.
}


\ourGloss{\glossaryTerm{body}}{%
a {\it function body} or {\it loop body}.
}


\ourGloss{\glossaryTerm{boolean}}{%
objects denoted by the literals {\tt true} and
{\tt false}; elements of domain {\bf Boolean}.
\index{Boolean}
See also {\bf Bits}.
}


\ourGloss{\glossaryTerm{built-in function}}{%
a {\it function} in the standard Axiom library.
\index{function!built-in}
Contrast {\it user function}.
}

v
\ourGloss{\glossaryTerm{cache}}{%
1.
(noun) a mechanism for immediate retrieval of previously computed data.
For example, a function that does a lengthy computation might store its
values in a {\it hash table} using the function argument as
the key.
The hash table then serves as a cache for the function (see also
{\tt )set function cache}).
Also, when recurrence relations that depend upon $n$
previous values are compiled, the previous $n$ values are normally
cached (use {\tt )set functions recurrence} to change this).
2.
(verb) to save values in a cache.
}


\ourGloss{\glossaryTerm{capsule}}{%
the part of the body of a
{\it domain constructor} that defines the functions implemented by
the constructor.
}


\ourGloss{\glossaryTerm{case}}{%
{\it (syntax)} an operator used to evaluate code conditionally based on
the branch of a {\bf Union}.
\index{Union}
For example, if value $u$ is $Union(Integer, "failed")$, the
conditional expression $if u case Integer then A else B$ evaluates
$A$ if $u$ is an integer and $B$ otherwise.
}


\ourGloss{\glossaryTerm{Category}}{%
the distinguished object denoting the type of a category; the class of
all categories.
}


\ourGloss{\glossaryTerm{category}}{%
{\it (basic concept)} types denoting
classes of domains.
Examples of categories are {\bf Ring} (``the class of all
rings'') and {\bf Aggregate} (``the class of all aggregates'').
Categories form a hierarchy (formally, a directed acyclic graph)
with the distinquished category {\bf Type}
at the top.
Each category inherits the properties of all its ancestors.
Categories optionally provide ``default definitions'' for
operations they export.
Categories are defined in Axiom by functions called
category constructors.
Technically, a category designates a class of domains with common
operations and
attributes but usually with different
functions
and representations for its
constituent objects.
Categories are always defined using the Axiom library
language (see also {\it category extension}).
See also file {\bf catdef.spad} for definitions of basic algebraic
\index{file!catdef.spad @{\bf catdef.spad}}
categories in Axiom, {\bf aggcat.spad} for data structure
\index{file!aggcat.spad @{\bf aggcat.spad}}
}


\ourGloss{\glossaryTerm{category constructor}}{%
a function that creates categories, described by an abstract datatype in
\index{constructor!category}
the Axiom programming language.
For example, the category constructor {\bf Module} is a function
that takes a domain parameter $R$ and creates the category ``modules
over $R$.''
}


\ourGloss{\glossaryTerm{category extension}}{%
A category $A$ {\it directly extends} a category $B$ if
its definition has the form $A == B with ...$ or
$A == Join(...,B,...)$.
In this case, we also say that $B$ is the {\it parent} of $A$.
We say that a category $A$ extends $B$ if $B$ is
an {\it ancestor} of $A$.
A category $A$ may also directly extend $B$ if
$B$ appears in a conditional expression within the {\tt Exports} part
of the definition to the right of a {\tt with}.
See, for example, file {\bf catdef.spad} for definitions of the
\index{file!catdef.spad @{\bf catdef.spad}}
algebra categories in Axiom, {\bf aggcat.spad} for data structure
\index{file!aggcat.spad @{\bf aggcat.spad}}
categories.
}

\ourGloss{\glossaryTerm{category hierarchy}}{%
hierarchy formed by category extensions.
The root category is {\bf Type}.
\index{Type}
A category can be defined as a {\it Join} of two or more
categories so as to have multiple parents.
Categories may also be parameterized so as to allow conditional
inheritance.
}

\ourGloss{\glossaryTerm{character}}{%
1.
an element of a character set, as represented by a keyboard key.
2.
a component of a string.
For example, the $1$st element of the string $"hello there"$ is the
character {\it h}.
}


\ourGloss{\glossaryTerm{client}}{%
(of a given domain) any domain or package that explicitly calls
functions from the given domain.
See a {\bf Cross Reference} page of a constructor in Browse.
}


\ourGloss{\glossaryTerm{coercion}}{%
an automatic transformation of an object of one {\it type} to an
object of a similar or desired target type.
In the interpreter, coercions and retractions
are done
automatically by the interpreter when a type mismatch occurs.
Compare {\it conversion}.
}


\ourGloss{\glossaryTerm{comment}}{%
textual remarks imbedded in code.
Comments are preceded by a double dash ({\tt --}).
For Axiom library code, stylized comments for on-line
documentation are preceded by two plus signs ({\tt ++}).
}


\ourGloss{\glossaryTerm{Common LISP}}{%
A version of {\it LISP} adopted as an informal standard by major
users and suppliers of LISP.
}


\ourGloss{\glossaryTerm{compile-time}}{%
the time when category or domain constructors are compiled.
Contrast {\it run-time}.
}


\ourGloss{\glossaryTerm{compiler}}{%
a program that generates low-level code from a higher-level source
language. Axiom has three compilers.
A {\it graphics compiler} converts graphical formulas to a compiled
subroutine so that points can be rapidly produced for graphics commands.
An {\it interpreter compiler} optionally compiles
user functions
when first invoked (use
{\tt )set functions compile} to turn this feature on).
A {\it library compiler} compiles all constructors (available on an ``as-is''
basis for Release 1).
}


\ourGloss{\glossaryTerm{computational object}}{%
In Axiom, domains are objects.
This term is used to distinguish the objects that are members of
domains rather than the domains themselves.
}


\ourGloss{\glossaryTerm{conditional}}{%
a {\it control structure} of the form $if A then B else C$.
\index{if}
The {\it evaluation} of $A$ produces {\tt true} or
{\tt false}. If {\tt true}, $B$ evaluates to produce a value;
otherwise $C$ evaluates to produce a value.
When the value is not required, the $else C$ part can be omitted.
}


\ourGloss{\glossaryTerm{constant}}{%
{\it (syntax)} a reserved word used in signatures in
Axiom programming language to signify that an operation always
returns the same value.
For example, the signature $0: constant -> \$$ in the source code
of {\bf AbelianMonoid} tells the Axiom compiler that $0$
is a constant so that suitable optimizations might be performed.
}


\ourGloss{\glossaryTerm{constructor}}{%
a {\it function} that creates a {\it category},
{\it domain}, or {\it package}.
}


\ourGloss{\glossaryTerm{continuation}}{%
when a line of a program is so long that it must be broken into several
lines, then all but the first line are called {\it continuation lines}.
If such a line is given interactively, then each incomplete line must
end with an underscore.
}


\ourGloss{\glossaryTerm{control structure}}{%
program structures that can specify a departure from normal sequential
execution. Axiom has four kinds of control structures:
blocks, {\it case} statements,
conditionals, and loops.
}


\ourGloss{\glossaryTerm{conversion}}{%
the transformation of an object of one {\it type} to one of
another type.
Conversions that can be performed automatically by the
interpreter are called
coercions. These happen when the
interpreter encounters a type mismatch and a similar or declared
target type is needed.
In general, the user must use the infix operation {\tt ::}
to cause this transformation.
}


\ourGloss{\glossaryTerm{copying semantics}}{%
the programming language semantics used in PASCAL
\index{PASCAL}
but {\it not} in
\index{semantics!copying}
Axiom. See also {\it pointer semantics} for details.
\index{semantics!pointer}
}


\ourGloss{\glossaryTerm{data structure}}{%
a structure for storing data in the computer.
Examples are lists
and hash tables.
}


\ourGloss{\glossaryTerm{datatype}}{%
equivalent to {\it domain} in Axiom.
}


\ourGloss{\glossaryTerm{declaration}}{%
{\it (syntax)} an expression of the form $x : T$ where $T$ is
some {\it type}.
A declaration forces all values assigned to
$x$ to be of that type.
If a value is of a different type, the interpreter will try to
coerce the value to type $T$.
Declarations are necessary in case of ambiguity or when a user wants to
introduce an unexposed domain.
}


\ourGloss{\glossaryTerm{default definition}}{%
a function defined by a {\it category}.
Such definitions appear in category definitions of the form \newline
$C: Category == T add I$ \newline
in an optional implementation part $I$ to the
right of the keyword $add$.
}


\ourGloss{\glossaryTerm{default package}}{%
an optional {\it package}
of functions associated with a category.
Such functions are necessarily defined in terms of other operations
exported by the category.
}


\ourGloss{\glossaryTerm{definition}}{%
{\it (syntax)} 1.
An expression of the form $f(a) == b$ defining function $f$
with formal arguments
$a$ and {\it body} $b$;
equivalent to the statement $f == (a) +-> b$.
2.
An expression of the form $a == b$ where $a$ is a
{\it symbol}, equivalent to $a() == b$.
See also {\it macro} where a similar substitution is done at
{\it parse} time.
}


\ourGloss{\glossaryTerm{delimiter}}{%
a {\it character} that marks the beginning or end of some
syntactically correct unit in the language, for example,
{\tt "} for strings, blanks for identifiers.
}

\ourGloss{\glossaryTerm{dependent}}{%
(of a given constructor) another constructor that mentions the given
constructor as an argument or among the types of an exported operation.
See a {\bf Cross Reference} page of a constructor in Browse.
}


\ourGloss{\glossaryTerm{destructive operation}}{%
An operation that changes a component or structure of a value.
\index{operation!destructive}
In Axiom, destructive operations have names ending
with an exclamation mark ({\tt !}).
For example, domain {\bf List} has two operations to reverse
the elements of a list, one named \spadfunFrom{reverse}{List}
that returns a copy of the original list with the elements
reversed, another named \spadfunFrom{reverse}{List} that
reverses the elements {\it in place,} thus destructively changing
the original list.
}

\ourGloss{\glossaryTerm{documentation}}{%
1.
on-line or hard-copy descriptions of Axiom; 2.
text in library code preceded by {\tt ++} comments as opposed to general
comments preceded by {\tt --}.
}


\ourGloss{\glossaryTerm{domain}}{%
{\it (basic concept)} a domain corresponds to the usual notion of
datatypes.
Examples of domains are
{\bf List Float} (``lists of floats''),
{\bf Fraction Polynomial Integer} (``fractions of polynomials of integers''),
and {\bf Matrix Stream CardinalNumber}
(``matrices of infinite streams of cardinal numbers'').
The term {\it domain} actually abbreviates {\it domain of
computation}.
Technically, a domain denotes a class of objects, a class of
operations for creating and otherwise
manipulating these objects, and a class of
attributes describing computationally
useful properties.
Domains may also define functions for its exported operations,
often in terms of some {\it representation} for the objects.
A domain itself is an {\it object} created by a
{\it function} called a {\it domain constructor}.
The types of the exported operations of a domain are arbitary; this gives
rise to a special class of domains called packages.
}


\ourGloss{\glossaryTerm{domain constructor}}{%
a function that creates domains, described by an abstract datatype in
\index{constructor!domain}
the Axiom programming language.
Simple domains like {\bf Integer} and {\bf Boolean} are
created by domain constructors with no arguments.
Most domain constructors take one or more parameters, one usually
denoting an {\it underlying domain}.
For example, the domain {\bf Matrix(R)} denotes ``matrices over
$R$.''
\index{Mapping}
Domains {\bf Mapping},
\index{Record}
{\bf Record}, and {\bf Union} are
\index{Union}
primitive domains.
All other domains are written in the Axiom programming language
and can be modified by users with access to the library source code
and the library compiler.
}


\ourGloss{\glossaryTerm{domain extension}}{%
a domain constructor $A$ is said to {\it extend} a domain
constructor $B$ if $A$'s definition has the form $A
== B add ...$.
This intuitively means ``functions not defined by $A$ are assumed to
come from $B$.''
Successive domain extensions form add-chains
affecting the
search order for functions not implemented
directly by the domain during {\it dynamic lookup}.
}


\ourGloss{\glossaryTerm{dot notation}}{%
using an infix dot ({\tt .}) for the
operation {\bf elt}.
If $u$ is the list $[7,4,-11]$ then both $u(2)$ and
$u.2$ return $4$.
Dot notation nests to the left:
$f.g.h$ is equivalent to $(f.g).h$.
}


\ourGloss{\glossaryTerm{dynamic}}{%
that which is done at {\it run-time} as opposed to
{\it compile-time}.
For example, the interpreter may build a domain ``matrices over
integers'' dynamically in response to user input.
However, the compilation of all functions for matrices and
integers is done during {\it compile-time}.
Constrast {\it static}.
}


\ourGloss{\glossaryTerm{dynamic lookup}}{%
In Axiom, a {\it domain} may or may not explicitly provide
{\it function} definitions for all its exported
operations. These definitions may instead come from domains
in the {\it add-chain} or from default packages.
When a function call is made for an
operation in the domain, up to five steps are carried out.
\begin{enumerate}
\item  If the domain itself implements a function for the operation,
that function is returned.
\item  Each of the domains in the {\it add-chain} are searched;
if one of these domains implements the function, that function is
returned.
\item Each of the default packages
for the
domain are searched in order of the {\it lineage}.
If any of the default packages implements the function, the first one
found is returned.
\item  Each of the default packages
for each of the
domains in the {\it add-chain} are searched in the order of their
{\it lineage}. If any of the default packages implements the
function, the first one found is returned.
\item  If all of the above steps fail, an error message is reported.
\end{enumerate}
}


\ourGloss{\glossaryTerm{empty}}{%
the unique value of objects with type {\bf Void}.
}


\ourGloss{\glossaryTerm{environment}}{%
a set of bindings.
}


\ourGloss{\glossaryTerm{evaluation}}{%
a systematic process that transforms an {\it expression} into an
object called the {\it value} of the expression.
Evaluation may produce side effects.
}

%tpdclip1


\ourGloss{\glossaryTerm{exit}}{%
{\it (reserved word)} an {\it operator} that forces an exit from
the current {\it block}.
For example, the block $(a := 1; if i > 0 then exit a;
a := 2)$ will prematurely exit at the second statement with value 1 if
the value of $i$ is greater than zero.
See {\tt =>} for an alternate syntax.
}

%tpdhere
%tpdhere
%tpdhere
%tpdhere

\ourGloss{\glossaryTerm{explicit export}}{%
1.
(of a domain $D$) any {\it attribute}, {\it operation},
\index{export!explicit}
or {\it category} explicitly mentioned in the {\it type}
exports part $E$ for the domain constructor definition
$D: E == I$ 2.
(of a category $C$) any {\it attribute},
{\it operation}, or {\it category} explicitly mentioned in
the {\it type} specification part $E$ for the category
constructor definition $C: {\it Category} == E$
}


\ourGloss{\glossaryTerm{export}}{%
{\it explicit export} or {\it implicit export} of a domain
or category
}


\ourGloss{\glossaryTerm{expose}}{%
some constructors are {\it exposed}, others {\it unexposed}.
Exposed domains and packages are recognized by the interpreter.
Use {\tt )set expose} to control what is exposed.
Unexposed constructors will appear in Browse prefixed by a star (``{\tt *}'').
}


\ourGloss{\glossaryTerm{expression}}{%
1.
any syntactically correct program fragment.
2.
an element of domain {\bf Expression}.
}


\ourGloss{\glossaryTerm{extend}}{%
see {\it category extension} or {\it domain extension}.
}


\ourGloss{\glossaryTerm{field}}{%
{\it (algebra)} a {\it domain} that is a {\it ring} where
every non-zero element is invertible and where $xy=yx$; a member of
category {\bf Field}.
For a complete list of fields, click on {\bf Domains} under {\bf Cross
Reference} for {\bf Field} in Browse.
}


\ourGloss{\glossaryTerm{file}}{%
1. a program or collection of data stored on disk, tape or other medium.
2. an object of a {\bf File} domain.
}


\ourGloss{\glossaryTerm{float}}{%
a floating-point number with user-specified precision; an element of
domain {\bf Float}.
\index{Float}
Floats are literals written either without an
exponent (for example, $3.1416$), or with an exponent
(for example, $3.12E-12$).
Use function {\it precision} to change the precision of the
mantissa ($20$ digits by default).
See also {\it small float}.
}


\ourGloss{\glossaryTerm{formal parameter}}{%
(of a function) an identifier bound to the value
of an actual {\it argument} on {\it invocation}.
In the function definition $f(x,y) == u$, for example, $x$ and
$y$ are the formal parameters.
}


\ourGloss{\glossaryTerm{frame}}{%
the basic unit of an interactive session; each frame has its own
{\it step number}, {\it environment}, and
{\it history}. In one interactive session, users can create and
drop frames, and have several active frames simultaneously.
}


\ourGloss{\glossaryTermNoIndex{free}}{%
{\it (syntax)}
A keyword used in user-defined functions to declare that
a variable is a {\it free variable} of that function.
\index{free}
For example, the statement $free x$ declares the variable $x$
within the body of a function $f$ to be a free variable in $f$.
Without such a declaration, any variable $x$ that appears on the
left-hand side of an assignment before it is referenced
is regarded as a {\it local variable} of that function.
If the intention of the assignment is to give a value to a
{\it global variable} $x$, the body of that function must
contain the statement $free x$.
A variable that is a parameter to the function is always local.
%This should be a reported bug--->
%, even
%if it has a $free$ declaration.
}


\ourGloss{\glossaryTerm{free variable}}{%
(of a function) a variable that appears in a body of a function but is
not bound by that function.
Contrast with {\it local variable}.
}

\ourGloss{\glossaryTerm{function}}{%
implementation of {\it operation}.
A function takes zero or more {\it argument} parameters and
produces a single return value.
Functions are objects that can be passed as parameters to
functions and can be returned as values of functions.
Functions can also create other functions (see also
{\bf InputForm}).
See also {\it application} and {\it invocation}.
The terms {\it operation} and {\it function} are distinct notions
in Axiom.
An operation is an abstraction of a function, described by
a {\it name} and a {\it signature}.
A function is created by providing an implementation of that
operation by Axiom code.
Consider the example of defining a user-function $fact$ to
compute the {\bf factorial} of a nonnegative integer.
The Axiom statement $fact: Integer -> Integer$
describes the operation, whereas the statement $fact(n) =
reduce(*,[1..n])$ defines the function.
See also {\it generic function}.
}


\ourGloss{\glossaryTerm{function body}}{%
the part of a {\it function}'s definition that is
evaluated when the function is called at {\it run-time}; the part
of the function definition to the right of the {\tt ==}.
}


\ourGloss{\glossaryTerm{garbage collection}}{%
a system function that automatically recycles memory cells from the
{\it heap}. Axiom is built upon {\it Common LISP} that
provides this facility.
}


\ourGloss{\glossaryTerm{garbage collector}}{%
a mechanism for reclaiming storage in the {\it heap}.
}


\ourGloss{\glossaryTerm{Gaussian}}{%
a complex-valued expression, for example, one with both a real and
imaginary part; a member of a {\bf Complex} domain.
}


\ourGloss{\glossaryTerm{generic function}}{%
the use of one function to operate on objects of different types.
One might regard Axiom as supporting generic
operations but not generic functions.
One operation $+: (D, D) -> D$ exists for adding elements in a
ring; each ring however provides its own type-specific function
for implementing this operation.
}


\ourGloss{\glossaryTerm{global variable}}{%
A variable that can be referenced freely by functions.
\index{variable!global}
In Axiom, all top-level user-defined variables defined during an
interactive user session are global variables.
Axiom does not allow {\it fluid variables}, that is, variables
\index{variable!fluid}
bound by a function $f$ that can be referenced by
functions that $f$ calls.
}


\ourGloss{\glossaryTermNoIndex{Gr\protect\"{o}bner basis}}{%
{\it (algebra)} a special basis for a polynomial ideal that allows a
\index{Groebner basis @{Gr\protect\"{o}bner basis}}
simple test for membership.
\index{basis!Groebner@{Gr\protect\"{o}bner}}
It is useful in solving systems of polynomial equations.
}



\ourGloss{\glossaryTerm{group}}{%
{\it (algebra)} a monoid where every element has a multiplicative
inverse.
}


\ourGloss{\glossaryTerm{hash table}}{%
a data structure designed for fast lookup of information stored under ``keys''.
A hash table consists of a set of {\it entries}, each of which
associates a {\it key} with a {\it value}.
Finding the object stored under a key can be fast for
a large number of entries since keys are {\it hashed} into numerical
codes for fast lookup.
}


\ourGloss{\glossaryTerm{heap}}{%
1. an area of storage used by data in programs.
For example, Axiom will use the heap to hold the partial results of
symbolic computations.
When cancellations occur, these results remain in the heap until
garbage collected.
2. an object of a {\bf Heap} domain.
}


\ourGloss{\glossaryTerm{history}}{%
a mechanism that records input and output data for an interactive session.
Using the history facility, users can save computations, review previous
steps of a computation, and restore a previous interactive session at
some later time.
For details, issue the system command {\it )history ?} to the
interpreter. See also {\it frame}.
}


\ourGloss{\glossaryTerm{ideal}}{%
{\it (algebra)} a subset of a ring that is closed under addition and
multiplication by arbitrary ring elements; thus an ideal is
a module over the ring.
}


\ourGloss{\glossaryTerm{identifier}}{%
{\it (syntax)} an Axiom name; a {\it literal} of type
{\bf Symbol}. An identifier begins with an alphabetical character,
\%, ?, or !, and may be followed by any of these or digits.
Certain distinguished reserved words are not allowed as
identifiers but have special meaning in Axiom.
}

\ourGloss{\glossaryTerm{immutable}}{%
an object is immutable if it cannot be changed by an
{\it operation}; it is not a mutable object.
Algebraic objects are generally immutable: changing an algebraic expression
involves copying parts of the original object.
One exception is an object of type {\bf Matrix}.
Examples of mutable objects are data structures such as those of type
\index{semantics!pointer}
{\bf List}. See also {\it pointer semantics}.
}


\ourGloss{\glossaryTerm{implicit export}}{%
(of a domain or category)
\index{export!implicit}
any exported {\it attribute} or {\it operation} or {\it category}
that is not an {\it explicit export}.
For example, {\bf Monoid} and {\bf *} are implicit exports of
{\bf Ring}.
}


\ourGloss{\glossaryTerm{index}}{%
1.
a variable that counts the number of times a {\it loop} is
repeated.
2. the ``address'' of an element in a data structure (see also category
{\bf LinearAggregate}).
}


\ourGloss{\glossaryTerm{infix}}{%
{\it (syntax)} an {\it operator} placed between two
operands; also called a {\it binary
operator}.
For example, in the expression $a + b$, $+$ is the
infix operator.
An infix operator may also be used as a {\it prefix}.
Thus $+(a,b)$ is also permissible in the Axiom
language.
Infix operators have a {\it precedence} relative to one another.
% relative to what?
}


\ourGloss{\glossaryTerm{input area}}{%
a rectangular area on a HyperDoc screen into which users can enter
text.
}


\ourGloss{\glossaryTerm{instantiate}}{%
to build a {\it category}, {\it domain}, or
{\it package} at run-time.
}


\ourGloss{\glossaryTerm{integer}}{%
a {\it literal} object of domain {\bf Integer}, the class of
integers with an unbounded number of digits.
Integer literals consist of one or more consecutive digits (0-9) with no
embedded blanks.
Underscores can be used to separate digits in long integers if
desirable.
}


\ourGloss{\glossaryTerm{interactive}}{%
a system where the user interacts with the computer step-by-step.
}


\ourGloss{\glossaryTerm{interpreter}}{%
the part of Axiom responsible for handling user input
during an interactive session.
%The following is a somewhat simplified description of the typical action of
%the interpreter.
The interpreter parses the user's input expression to create an
expression tree, then does a bottom-up traversal of the tree.
Each subtree encountered that is not a value consists of a root node
denoting an operation name and one or more leaf nodes denoting
operands.
The interpreter resolves type mismatches and uses
type-inferencing and a library database to determine appropriate types for
the operands and the result, and an operation to be performed.
The interpreter next builds a domain to perform the indicated operation,
and invokes a function from the domain to compute a value.
The subtree is then replaced by that value and the process continues.
Once the entire tree has been processed, the value replacing the top
node of the tree is displayed back to the user as the value of the
expression.
}

\ourGloss{\glossaryTerm{invocation}}{%
(of a function) the run-time process involved in
evaluating a {\it function}
{\it application}. This process has two steps.
First, a local {\it environment} is created where
formal arguments
are locally bound by
{\it assignment} to their respective actual {\it argument}.
Second, the {\it function body} is evaluated in that local
environment. The evaluation of a function is terminated either by
completely evaluating the function body or by the evaluation of a
{\tt return} expression.
\index{return}
}

\ourGloss{\glossaryTerm{iteration}}{%
repeated evaluation of an expression or a sequence of expressions.
Iterations use the reserved words
{\tt for},
\index{for}
{\tt while},
\index{while}
and {\tt repeat}.
\index{repeat}
}

\ourGloss{\glossaryTerm{Join}}{%
a primitive Axiom function taking two or more categories as
arguments and producing a category containing all of the operations and
attributes from the respective categories.
}


\ourGloss{\glossaryTerm{KCL}}{%
Kyoto Common LISP, a version of {\it Common LISP} that features
compilation of LISP into the $C$ Programming
Language.
}


\ourGloss{\glossaryTerm{library}}{%
In Axiom, a collection of compiled modules respresenting
{\it category} or {\it domain} constructors.
}


\ourGloss{\glossaryTerm{lineage}}{%
the sequence of
default packages
for a given domain to be
searched during {\it dynamic lookup}.
This sequence is computed first by ordering the category
ancestors of the domain according to their {\it level
number}, an integer equal to the minimum distance of the domain from
the category.
Parents have level 1, parents of parents have level 2, and so on.
Among categories with equal level numbers, ones that appear in the
left-most branches of {\tt Join}s in the source code come first.
See a {\bf Cross Reference} page of a constructor in Browse.
See also {\it dynamic lookup}.
}

\ourGloss{\glossaryTerm{LISP}}{%
acronym for List Processing Language, a language designed for the
manipulation of non-numerical data.
The Axiom library is translated into LISP then compiled into
machine code by an underlying LISP system.
}


\ourGloss{\glossaryTerm{list}}{%
an object of a {\bf List} domain.
}


\ourGloss{\glossaryTerm{literal}}{%
an object with a special syntax in the language.
In Axiom, there are five types of literals:
booleans,
integers,
floats,
strings, and
symbols.
}


\ourGloss{\glossaryTerm{local}}{%
{\it (syntax)}
A keyword used in user-defined functions to declare that
a variable is a {\it local variable} of that function.
Because of default assumptions on variables, such a declaration is
often not necessary but is available to the user for clarity when appropriate.
}

\ourGloss{\glossaryTerm{local variable}}{%
(of a function) a variable bound by that
function and such that its binding is invisible to any function
that function calls.
Also called a {\it lexical} variable.
By default in the interpreter:
\begin{enumerate}
\item
any variable $x$ that appears on the left-hand side of an
assignment
is normally regarded a local variable of that function.
%The right-hand side of an assignment is looked at before the
%left-hand side.
If the intention of an assignment is to change the value of a
{\it global variable} $x$, the body of the function must then
contain the statement $free x$.
\item
any other variable is regarded as a {\it free variable}.
\end{enumerate}
An optional declaration $local x$ is available to declare
explicitly a variable to be a local variable.
All formal parameters
are local variables to the function.
}

\ourGloss{\glossaryTerm{loop}}{%
1.
an expression containing a {\tt repeat}.
\index{repeat}
2.
a collection expression having a
{\tt for} or a
\index{for}
{\tt while},
\index{while}
for example, $[f(i) for i in S]$.
\index{while}
}


\ourGloss{\glossaryTerm{loop body}}{%
the part of a loop following the {\tt repeat}
\index{repeat}
that tells what to do each iteration.
For example, the body of the loop $for x in S repeat B$ is
$B$. For a collection expression, the body of the loop precedes the
initial {\tt for}
\index{for}
or {\tt while}.
\index{while}
}


\ourGloss{\glossaryTerm{macro}}{%
1. {\it (interactive syntax)}
An expression of the form $macro a == b$ where $a$ is a
{\it symbol} causes $a$ to be textually replaced by the
expression $b$ at {\it parse} time.
2.
An expression of the form $macro f(a) == b$ defines a parameterized
macro expansion for a parameterized form $f$. This macro causes a
form $f$($x$) to be textually replaced by the expression
$c$ at parse time, where $c$ is the expression obtained by
replacing $a$ by $x$ everywhere in $b$.
See also {\it definition} where a similar substitution is done
during {\it evaluation}.
3. {\it (programming language syntax)}
An expression of the form $a ==> b$ where $a$ is a symbol.
}


\ourGloss{\glossaryTerm{mode}}{%
a type expression containing a question-mark ({\tt ?}).
For example, the mode {\sf POLY ?} designates {\it the class of all
polynomials over an arbitrary ring}.
}


\ourGloss{\glossaryTerm{mutable}}{%
objects that contain pointers
to other objects and that
\index{semantics!pointer}
have operations defined on them that alter these pointers.
Contrast {\it immutable}.
Axiom uses {\it pointer semantics} as does {\it LISP}
\index{semantics!copying}
in contrast with many other languages such as PASCAL
\index{PASCAL}
that use
{\it copying semantics}.
See {\it pointer semantics} for details.
}

\ourGloss{\glossaryTerm{name}}{%
1.
a {\it symbol} denoting a {\it variable}, such as
the variable $x$.
2.
a {\it symbol} denoting an {\it operation},
that is, the operation $divide: (Integer, Integer) -> Integer$.
}



\ourGloss{\glossaryTerm{nullary}}{%
a function with no arguments, for example,
{\bf characteristic}; operation or function with {\it arity} zero.
}



\ourGloss{\glossaryTerm{object}}{%
a data entity created or manipulated by programs.
Elements of domains, functions, and domains themselves are objects.
The most basic objects are literals; all other objects must
be created by functions.
Objects can refer to other objects using pointers
and can be {\it mutable}.
}

\ourGloss{\glossaryTerm{object code}}{%
code that can be directly executed by hardware; also known as {\it
machine language}.
}


\ourGloss{\glossaryTerm{operand}}{%
an argument of an {\it operator} (regarding an operator as a
{\it function}).
}


\ourGloss{\glossaryTerm{operation}}{%
an abstraction of a {\it function}, described by a
{\it signature}. For example,\\
$fact: NonNegativeInteger -> NonNegativeInteger$ describes an operation for
``the factorial of a (non-negative) integer.''
}


\ourGloss{\glossaryTerm{operator}}{%
special reserved words in the language such as $+$ and
$*$; operators can be either {\it prefix} or
{\it infix} and have a relative {\it precedence}.
}


\ourGloss{\glossaryTerm{overloading}}{%
the use of the same name to denote distinct operations; an
operation is
identified by a {\it signature} identifying its name, the number
and types of its arguments, and its return types.
If two functions can have identical signatures, a {\it package
call} must be made to distinguish the two.
}


\ourGloss{\glossaryTerm{package}}{%
a special case of a domain, one for which the exported operations
depend solely on the parameters
and other explicit domains (contain no \$).
Intuitively, packages are collections of
({\it polymorphic}) functions.
Facilities for integration, differential equations, solution of
linear or polynomial equations, and group theory are provided by
packages.
}


\ourGloss{\glossaryTerm{package call}}{%
{\it (syntax)} an expression of the form $e \$ P$ where $e$ is
an {\it application} and $P$ denotes some {\it package}
(or {\it domain}).
}


\ourGloss{\glossaryTerm{package constructor}}{%
same
\index{constructor!package}
as {\it domain constructor}.
}

\ourGloss{\glossaryTerm{parameter}}{%
see {\it argument}.
}

\ourGloss{\glossaryTerm{parameterized datatype}}{%
a domain that is built on another, for example, polynomials with integer
\index{datatype!parameterized}
coefficients.
}


\ourGloss{\glossaryTerm{parameterized form}}{%
a expression of the form $f(x,y)$, an {\it application} of a
function.
}

\ourGloss{\glossaryTerm{parent}}{%
(of a domain or category) a category which is 
explicitly declared in the source code
definition for the domain either to the left of the {\tt with} or
as an {\it export} of the domain.
See {\it category extension}.
See also a {\bf Cross Reference} page of a constructor in Browse.
}


\ourGloss{\glossaryTerm{parse}}{%
1.
(verb) to transform a user input string representing a valid
Axiom expression into an internal representation as a
tree-structure; the
resulting internal representation is then ``interpreted'' by Axiom to
perform some indicated action.
}

\ourGloss{\glossaryTerm{partially ordered set}}{%
a set with a reflexive, transitive and antisymetric {\it binary}
operation.
}


\ourGloss{\glossaryTerm{pattern matching}}{%
1.
(on expressions) Given an expression called the ``subject'' $u$, the
attempt to rewrite $u$ using a set of ``rewrite rules.''
Each rule has the form $A == B$ where $A$ indicates an
expression called a ``pattern'' and $B$ denotes a ``replacement.''
The meaning of this rule is ``replace $A$ by $B$.''
If a given pattern $A$ matches a subexpression of $u$, that
subexpression is replaced by $B$.
Once rewritten, pattern matching continues until no further changes
occur. 2.
(on strings) the attempt to match a string indicating a ``pattern'' to
another string called a ``subject'', for example, for the purpose of
identifying a list of names.
In Browse, users may enter search strings
for the purpose
of identifying constructors, operations, and attributes.
}

\ourGloss{\glossaryTerm{pile}}{%
alternate syntax for a block, using indentation and column alignment
(see also {\it block}).
}

\ourGloss{\glossaryTerm{pointer}}{%
a reference implemented by a link directed from one object to another in
the computer memory.
An object is said to {\it refer} to another if it has a pointer to that
other object.
Objects can also refer to themselves (cyclic references are legal).
\index{semantics!pointer}
Also more than one object can refer to the same object.
See also {\it pointer semantics}.
}


\ourGloss{\glossaryTerm{pointer semantics}}{%
the programming language semantics used in languages such as LISP that
\index{semantics!copying}
allow objects to be {\it mutable}.
\index{semantics!pointer}
Consider the following sequence of Axiom statements:
\newline
$x : Vector Integer := [1,4,7]$ \newline
$y := x$ \newline
$swap!(x,2,3)$ \newline
The function \spadfunFrom{swap}{Vector}
is used to interchange the second and third value in the list
$x$, producing the value $[1,7,4]$.
What value does $y$ have after evaluation of the third statement?
The answer is different in Axiom than it is in a language with
{\it copying semantics}.
In Axiom, first the vector $[1,2,3]$ is created and the variable
$x$ set to point to this object.
Let's call this object $V$.
Next, the variable $y$ is made to point to $V$ just as
$x$ does.
Now the third statement interchanges the last 2 elements of $V$
(the {\tt !} at the end of the name \spadfunFrom{swap}{Vector} tells you
that this operation is destructive, that is, it changes the elements {\it
in place}).
\index{operation!destructive}
Both $x$ and $y$ perceive this change to $V$.
\index{semantics!copying}
Thus both $x$ and $y$ then have the value $[1,7,4]$.
In PASCAL, the second statement causes a copy of $V$ to be stored
\index{PASCAL}
under $y$.
Thus the change to $V$ made by the third statement does not affect
$y$.
}

\ourGloss{\glossaryTerm{polymorphic}}{%
a {\it function} (for example, one implementing an {\it algorithm})
defined with categorical types so as to be
applicable over a variety of domains
(the domains which are members of the categorical types).
Every Axiom function defined in a domain or package constructor with a
domain-valued parameter is polymorphic.
For example, the same matrix $+$ function is used to add
``matrices over integers'' as ``matrices over matrices over integers.''
}

\ourGloss{\glossaryTerm{postfix}}{%
an {\it operator} that follows its single {\it operand}.
Postfix operators are not available in Axiom.
}

\ourGloss{\glossaryTerm{precedence}}{%
{\it (syntax)} refers to the so-called {\it binding power} of an
operator. For example, $*$ has higher binding power than $+$ so
that the expression $a + b * c$ is equivalent to $a + (b * c)$.
}

\ourGloss{\glossaryTerm{precision}}{%
the number of digits in the specification of a number.
The operation \spadfunFrom{digits}{Float} sets this for objects
of {\bf Float}.
\index{Float}
}

\ourGloss{\glossaryTerm{predicate}}{%
1.
a Boolean-valued function, for example, $odd: Integer -> Boolean$.
2.
a Boolean-valued expression.
}

\ourGloss{\glossaryTerm{prefix}}{%
{\it (syntax)} an {\it operator} such as $-$
that is written {\it before} its single {\it operand}.
Every function of one argument can be used as a prefix operator.
For example, all of the following have equivalent meaning in
Axiom: $f(x)$, $f x$, and $f.x$.
See also {\it dot notation}.
}

\ourGloss{\glossaryTerm{quote}}{%
the prefix {\it operator} {\tt '} meaning {\it do not
evaluate}.
}

\ourGloss{\glossaryTermNoIndex{Record}}{%
(basic domain constructor) a domain constructor used to create an
\index{Record}
inhomogeneous aggregate composed of pairs of
selectors and
values.
A {\bf Record} domain is written in the form
$Record(a1: D1, \ldots, an: Dn)$ ($n > 0$) where
$a1$, \ldots, $an$ are identifiers called the {\it selectors}
of the record, and $D1$, \ldots, $Dn$ are domains indicating
the type of the component stored under selector $an$.
}

\ourGloss{\glossaryTerm{recurrence relation}}{%
A relation that can be expressed as a function $f$ with some
argument $n$ which depends on the value of $f$ at $k$
previous values.
In most cases, Axiom will rewrite a recurrence relation on
compilation so as to {\it cache} its previous $k$ values and
therefore make the computation significantly more efficient.
}


\ourGloss{\glossaryTerm{recursion}}{%
use of a self-reference within the body of a function.
Indirect recursion is when a function uses a function below it in the
call chain.
}

\ourGloss{\glossaryTerm{recursive}}{%
1.
A function that calls itself, either directly or indirectly through
another function.
2.
self-referential.
See also {\it recursive}.
}

\ourGloss{\glossaryTerm{reference}}{%
see {\it pointer}
}

\ourGloss{\glossaryTerm{relative}}{%
(of a domain) A package that exports operations relating to the domain,
in addition to those exported by the domain.
See a {\bf Cross Reference} page of a constructor in Browse.
}

%\ourGloss{\glossaryTermNoIndex{Rep}}{%
%a special identifier used as a {\it local variable} of a domain
%\index{Rep}
%constructor body to denote the representation domain for objects of a
%domain. See {\it representation}.
%}

\ourGloss{\glossaryTerm{representation}}{%
a {\it domain} providing a data structure for elements of a
domain, generally denoted by the special identifier {\it Rep} in
the Axiom programming language.
As domains are abstract datatypes,
this representation is
not available to users of the domain, only to functions defined in the
{\it function body} for a domain constructor.
Any domain can be used as a representation.
}

\ourGloss{\glossaryTerm{reserved word}}{%
a special sequence of non-blank characters with special meaning in the
Axiom language.
Examples of reserved words are names such as {\tt for},
\index{for}
$if$,
\index{if}
and $free$,
\index{free}
operator names such as
$+$ and {\bf mod}, special character strings such as
{\tt ==} and {\tt :=}.
}

\ourGloss{\glossaryTerm{retraction}}{%
to move an object in a parameterized domain back to the underlying
domain, for example to move the object $7$ from a ``fraction of
integers'' (domain {\bf Fraction Integer}) to ``the integers'' (domain
{\bf Integer}).
}

\ourGloss{\glossaryTerm{return}}{%
when leaving a function, the value of the expression following
{\tt return}
\index{return}
becomes the value of the function.
}

\ourGloss{\glossaryTerm{ring}}{%
a set with a commutative addition, associative multiplication, a unit
element, where multiplication is distributive over addition and subtraction.
}

\ourGloss{\glossaryTerm{rule}}{%
{\it (syntax)} 1.
An expression of the form $rule A == B$ indicating a ``rewrite
rule.'' 2.
An expression of the form $rule (R1;...;Rn)$ indicating a set of
``rewrite rules'' $R1$,...,$Rn$.
See {\it pattern matching} for details.
}


\ourGloss{\glossaryTerm{run-time}}{%
the time when computation is done.
Contrast with {\it compile-time}, and
{\it dynamic} as opposed to {\it static}.
For example, the decision of the intepreter to build
a structure such as ``matrices with power series entries'' in response to
user input is made at run-time.
}


\ourGloss{\glossaryTerm{run-time check}}{%
an error-checking that can be done only when the program receives user
input; for example, confirming that a value is in the proper range for a
computation.
}

\ourGloss{\glossaryTerm{search string}}{%
a string entered into an {\it input area} on a HyperDoc screen.
}


\ourGloss{\glossaryTerm{selector}}{%
an identifier used to address a component value of a
{\bf Record} datatype.
\index{Record}
}


\ourGloss{\glossaryTerm{semantics}}{%
the relationships between symbols and their meanings.
The rules for obtaining the {\it meaning} of any syntactically valid
expression.
}

\ourGloss{\glossaryTerm{semigroup}}{%
{\it (algebra)} a {\it monoid} which need not have an identity; it
is closed and associative.
}


\ourGloss{\glossaryTerm{side effect}}{%
action that changes a component or structure of a value.
\index{operation!destructive}
See {\it destructive operation} for details.
}


\ourGloss{\glossaryTerm{signature}}{%
{\it (syntax)} an expression describing the type of an {\it operation}.
A signature has the form $name : source -> target$, where
$source$ is the type of the arguments of the operation, and
$target$ is the type of the result.
}


\ourGloss{\glossaryTerm{small float}}{%
an object of
the domain {\bf DoubleFloat}
for floating-point arithmetic as provided by the
\index{DoubleFloat}
computer hardware.
}


\ourGloss{\glossaryTerm{small integer}}{%
an object of
the domain {\bf SingleInteger}
for integer arithmetic
\index{SingleInteger}
as provided by the computer hardware.
}


\ourGloss{\glossaryTerm{source}}{%
the {\it type} of the argument of a {\it function}; the type
expression before the $->$ in a {\it signature}.
For example, the source of $f : (Integer, Integer) -> Integer$ is
$(Integer, Integer)$.
}


\ourGloss{\glossaryTerm{sparse}}{%
data structure whose elements are mostly identical (a sparse matrix is
one filled mostly with zeroes).
}


\ourGloss{\glossaryTerm{static}}{%
that computation done before run-time, such as compilation.
Contrast {\it dynamic}.
}


\ourGloss{\glossaryTerm{step number}}{%
the number that precedes user input lines in an interactive session;
the output of user results is also labeled by this number.
}


\ourGloss{\glossaryTerm{stream}}{%
an object of {\bf Stream(R)}, a generalization of a
{\it list} to allow an infinite number of elements.
Elements of a stream are computed ``on demand.''
Streams are used to implement various forms of power series.
}


\ourGloss{\glossaryTerm{string}}{%
an object of domain {\bf String}.
Strings are literals consisting of an arbitrary sequence of
characters surrounded by double-quotes ({\tt "}),
for example, $"Look here!"$.
}

\ourGloss{\glossaryTerm{subdomain}}{%
{\it (basic concept)} a {\it domain} together with a
{\it predicate} characterizing the members of the domain
that belong to the subdomain.
The exports of a subdomain are usually distinct from the domain
itself.
A fundamental assumption however is that values in the subdomain
are automatically coerceable to values in
the domain.
For example, if $n$ and $m$ are declared to be members
of a subdomain of the integers, then {\it any} {\it binary}
operation from {\bf Integer} is available on $n$ and
$m$.
On the other hand, if the result of that operation is to be
assigned to, say, $k$, also declared to be of that subdomain,
a {\it run-time} check is generally necessary to ensure that
the result belongs to the subdomain.
}


\ourGloss{\glossaryTerm{such that clause}}{%
{\it (syntax)}
the use of {\tt |} followed by an expression to filter an
iteration.
}


\ourGloss{\glossaryTerm{suffix}}{%
{\it (syntax)} an {\it operator} that is placed after its operand.
Suffix operators are not allowed in the Axiom language.
}


\ourGloss{\glossaryTerm{symbol}}{%
objects denoted by {\it identifier} literals; an
element of domain {\bf Symbol}.
The interpreter, by default, converts the symbol $x$ into
{\bf Variable(x)}.
}


\ourGloss{\glossaryTerm{syntax}}{%
rules of grammar and punctuation for forming correct expressions.
}


\ourGloss{\glossaryTerm{system commands}}{%
top-level Axiom statements that begin with {\tt )}.
System commands allow users to query the database, read files, trace
functions, and so on.
}


\ourGloss{\glossaryTerm{tag}}{%
an identifier used to discriminate a branch of a {\bf Union} type.
\index{Union}
}


\ourGloss{\glossaryTerm{target}}{%
the {\it type} of the result of a {\it function}; the type
expression following the {\tt ->} in a {\it signature}.
}

\ourGloss{\glossaryTerm{top-level}}{%
refers to direct user interactions with the Axiom interpreter.
}


\ourGloss{\glossaryTerm{totally ordered set}}{%
{\it (algebra)} a partially ordered set where any two elements are
comparable.
}


\ourGloss{\glossaryTerm{trace}}{%
use of system function {\tt )trace} to track the arguments passed to
a function and the values returned.
}


\ourGloss{\glossaryTerm{tuple}}{%
an expression of two or more other expressions separated by commas,
for example, $4,7,11$.
Tuples are also used for multiple arguments both for
applications (for example, $f(x,y)$) and in
signatures
(for example, $(Integer, Integer) ->
Integer$). A tuple is not a data structure, rather a syntax mechanism for
grouping expressions.
}


\ourGloss{\glossaryTerm{type}}{%
The type of any {\it category} is the unique symbol {\it
Category}.
The type of a {\it domain} is any {\it category} to
which the domain belongs.
The type of any other object is either the (unique) domain to
which the object belongs or a {\it subdomain} of that domain.
The type of objects is in general not unique.
}

\ourGloss{\glossaryTermNoIndex{Type}}{%
a category with no operations or attributes, of which all other categories
\index{Type}
in Axiom are extensions.
}

\ourGloss{\glossaryTerm{type checking}}{%
a system function that determines whether the datatype of an object is
appropriate for a given operation.
}


\ourGloss{\glossaryTerm{type constructor}}{%
a {\it domain constructor} or {\it category constructor}.
}


\ourGloss{\glossaryTerm{type inference}}{%
when the interpreter chooses the type for an object based on context.
For example, if the user interactively issues the definition
$f(x) == (x + \%i)**2$ then issues $f(2)$, the
interpreter will infer the type of $f$ to be $Integer ->
Complex Integer$.
}


\ourGloss{\glossaryTerm{unary}}{%
operation or function with {\it arity} 1.
}


\ourGloss{\glossaryTerm{underlying domain}}{%
for a {\it domain} that has a single domain-valued parameter, the
{\it underlying domain} refers to that parameter.
For example, the domain ``matrices of integers'' ({\bf Matrix
Integer}) has underlying domain {\bf Integer}.
}


\ourGloss{\glossaryTermNoIndex{Union}}{%
(basic domain constructor) a domain constructor used to combine any set
\index{Union}
of domains into a single domain.
A {\bf Union}
domain is written in the form $Union(a1: D1, ..., an: Dn)$
($n > 0$) where $a1$, ..., $an$ are identifiers called the
{\it tags} of the union, and $D1$, ..., $Dn$ are domains called
the {\it branches} of the union.
The tags $$ai$$ are optional, but required when two of the
$$Di$$ are equal, for example,
$Union(inches: Integer, centimeters: Integer)$. In the interpreter,
values of union domains are automatically coerced to values in the
branches and vice-versa as appropriate.
See also {\it case}.
}


\ourGloss{\glossaryTerm{unit}}{%
{\it (algebra)} an invertible element.
}


\ourGloss{\glossaryTerm{user function}}{%
a function defined by a user during an interactive session.
Contrast {\it built-in function}.
}


\ourGloss{\glossaryTerm{user variable}}{%
a variable created by the user at top-level during an interactive
session.
}


\ourGloss{\glossaryTerm{value}}{%
1.
the result of evaluating an expression.
2.
a property associated with a {\it variable} in a
{\it binding} in an {\it environment}.
}

\ourGloss{\glossaryTerm{variable}}{%
a means of referring to an object, but not an object itself.
A variable has a name and an associated {\it binding} created by
{\it evaluation} of Axiom expressions such as
declarations,
assignments, and
definitions.
In the top-level {\it environment} of the
interpreter, variables are
global variables.
Such variables can be freely referenced in user-defined functions
although a $free$ declaration is needed to assign values to
\index{free}
them. See {\it local variable} for details.
}

\ourGloss{\glossaryTermNoIndex{Void}}{%
the type given when the {\it value} and {\it type} of an
expression are not needed.
\index{Void}
Also used when there is no guarantee at run-time that a value and
predictable mode will result.
}


\ourGloss{\glossaryTerm{wild card}}{%
a symbol that matches any substring including the empty string; for
example, the search string ``{\tt *an*}'' matches any word containing the
consecutive letters ``{\tt a}'' and ``{\tt n}''.
}


\ourGloss{\glossaryTerm{workspace}}{%
an interactive record of the user input and output held in an
interactive history file.
Each user input and corresponding output expression in the workspace has
a corresponding {\it step number}.
The current output expression in the workspace is referred to as
$\%$. The output expression associated with step number $n$ is
referred to by $\%\%(n)$.
The $k$-th previous output expression relative to the current step
number $n$ is referred to by $\%\%(- k)$.
Each interactive {\it frame} has its own workspace.
}

}\onecolumn\fussy


\vfill
\eject
%\setcounter{chapter}{7} % Appendix H
\chapter{BackMatter Quotes}
\begin{quote}
``AXIOM is a milestone in the history of computation. It sets a new
standard for depth and breadth of mathematical software. AXIOM is
a fully integrated environment for exploratory research in mathematics,
easily extensible to new domains. I recommend this book to all researchers
and teachers of advanced courses in scientific and mathematical 
disciplines.''\\
{\bf Anil Nerode}\\
Director, Mathematical Sciences Institute\\
Goldwin Smit Professor of Mathematics, Cornell Univerity
\end{quote}

\begin{quote}
``The AXIOM language is a jewel that should receive wide attention among
mathematicians as potential users and among computer scientists as a
model for excellence in lanuage design''\\
{\bf Michael Rabin}\\
Thomas J. Watson, Sr., Professor of Computer Science\\
Harvard University\\
Albert Einstein Professor of Mathematics\\
Hebrew University
\end{quote}

\begin{quote}
``AXIOM has captured the excitement of the French mathematical community.
It is the first of a new generation of computer algebra systems, and is
highly efficient for large and difficult computations.''\\
{\bf Daniel Lazard}\\
Professor d'Informatique\\
Universite Pierre et Marie Curie, Paris VI
\end{quote}

\begin{quote}
``The abstraction capabilities of AXIOM are unparalleled among presently
available computer algebra systems. Many natural mathematical constructions,
very awkward in other systems, remain natural and simple in AXIOM''\\
{\bf Willard Miller, Jr.}\\
Professor and Associate Director\\
Institute for Mathematics and its Applications\\
University of Minnesota
\end{quote}

\begin{quote}
``AXIOM is the culmination of a quarter of a century of research at IBM.
It represents an important new generation of computer algebra systems.''\\
{\bf Joel Moses}\\
Dean of Engineering\\
D.C. Jackson Professor of Computer Science and Engineering\\
Massachusetts Institute of Technology
\end{quote}

\begin{quote}
``AXIOM is a dream come true - a powerful, fast, flexible system soundly
based on the principles of modern mathematics. For anyone who does a
substantial amount of empirical mathematics, AXIOM is a godsend.''\\
{\bf George E. Andrews}\\
Evan Pugh Professor of Mathematics\\
Pennsylvania State University
\end{quote}

\begin{quote}
``I strongly recommend that statisticians acquaint themselves with AXIOM
for at least two very good reasons. Its algebraic strength offers help
with the combinatoric problems of design of experiments while the
tensor-calculus facilities can provide powerful tools for likelihood
inference.''\\
{\bf John Nelder}\\
Fellow of the Royal Society\\
Professor of Imperial College, London
\end{quote}

\chapter{License}
\begin{verbatim}
Portions Copyright (c) 2005 Timothy Daly

The Blue Bayou image Copyright (c) 2004 Jocelyn Guidry

Portions Copyright (c) 2004 Martin Dunstan

Portions Copyright (c) 1991-2002, 
The Numerical ALgorithms Group Ltd.
All rights reserved.

This book and the Axiom software is licensed as follows:

Redistribution and use in source and binary forms, with or 
without modification, are permitted provided that the following 
conditions are
met:

    - Redistributions of source code must retain the above 
      copyright notice, this list of conditions and the 
      following disclaimer.

    - Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the 
      following disclaimer in the documentation and/or other 
      materials provided with the distribution.

    - Neither the name of The Numerical ALgorithms Group Ltd. 
      nor the names of its contributors may be used to endorse 
      or promote products derived from this software without 
      specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGE.
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Bibliography}
\bibliographystyle{axiom}
\bibliography{axiom}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}
\printindex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}