\documentclass{book}
%\usepackage{axiom}
\usepackage{graphicx}
% struggle with latex figurefloating behavior
\renewcommand\floatpagefraction{.9}
\renewcommand\topfraction{.9}
\renewcommand\bottomfraction{.9}
\renewcommand\textfraction{.1}
\setcounter{totalnumber}{50}
\setcounter{topnumber}{50}
\setcounter{bottomnumber}{50}
% spadcommands are the actual text that you type at the axiom prompt
\newcommand{\spadcommand}[1]%
{\begin{flushleft}{\tt #1}\end{flushleft}\vskip .1cm }
% spadgraph are the actual text that you type at the axiom prompt for draw
\newcommand{\spadgraph}[1]%
{\begin{flushleft}{\tt #1}\end{flushleft}\vskip .1cm }
% returnType is the type signature returned by the axiom interpreter
\newcommand{\returnType}[1]%
{\begin{flushright}{\tt #1}\end{flushright}\vskip .1cm}
% spadsig gives the standard > notation for signatures
\newcommand{\spadsig}[2]{{\sf #1 $\rightarrow$ #2}}
% The book begins with some introductory material that is not really
% listed as a chapter. This creates a header similar to \chapter.
\newcommand{\pseudoChapter}[1]%
{\vskip .5in \noindent {\Large{\bf #1}}\vskip .5in}
% The book begins with some introductory material that is not really
% listed as a section. This creates a header similar to \section.
\newcommand{\pseudoSection}[1]%
{\vskip .25in \noindent {\large{\bf #1}}\vskip .25in}
% spadofFrom records the operation in the index and the domain in the index
\newcommand{\spadopFrom}[2]{\index{library!operations!#1 @\begingroup \string\tt{} #1 \endgroup}\index{#2}``{\tt #1}''}
% spadfunFrom records the function name and domain in the index
\newcommand{\spadfunFrom}[2]{{\bf #1}\index{#1 @\begingroup \string\bf{} #1 \endgroup}\index{#2}}
% special meanings for math characters
\newcommand{\N}{\mbox{\bbold N}}
\newcommand{\Natural}{\mbox{\bbold N}}
\newcommand{\Z}{\mbox{\bbold Z}}
\newcommand{\Integer}{\mbox{\bbold Z}}
\newcommand{\Rational}{\mbox{\bbold Q}}
\newcommand{\Q}{\mbox{\bbold Q}}
\newcommand{\Complex}{\mbox{\bbold C}}
\newcommand{\C}{{\mathcal C}}
\newcommand{\Real}{\mbox{\bbold R}}
\newcommand{\F}{{\mathcal F}}
\newcommand{\R}{{\mathcal R}}
% draw a box around a text block
\newcommand\boxed[2]{%
\begin{center}
\begin{tabular}{c}
\hline
\begin{minipage}{#1}
\normalsize
{#2}
\end{minipage}\\
\hline
\end{tabular}
\end{center}}
\newcommand{\optArg}[1]{{{\tt [}{#1}{\tt ]}}}
\newcommand{\argDef}[1]{{\tt ({#1})}}
\newcommand{\funSyntax}[2]{{\bf #1}{\tt ({\small\it{#2}})}}
\newcommand{\funArgs}[1]{{\tt ({\small\it {#1}})}\newline}
\newcommand{\condata}[4]{{\bf #1} {\bf #2} {\bf #3} {\bf #4}}
\def\glossaryTerm#1{{\bf #1}\index{#1}}
\def\glossaryTermNoIndex#1{{\bf #1}}
\def\glossarySyntaxTerm#1{{\tt #1}\index{#1}}
\long\def\ourGloss#1#2{\par\pagebreak[3]{#1}\newline{#2}}
\def\csch{\mathop{\rm csch}\nolimits}
\def\erf{\mathop{\rm erf}\nolimits}
\def\zag#1#2{
{{\hfill \left. {#1} \right}
\over
{\left {#2} \right. \hfill}
}
}
% these bitmaps are used by HyperDoc
\newdimen\commentWidth
\commentWidth=11pc
\newdimen\colGutterWidth
\colGutterWidth=1pc
\newdimen\baseLeftSkip
\baseLeftSkip=\commentWidth \advance\baseLeftSkip by \colGutterWidth
\newcommand\ExitBitmap{{\setlength{\unitlength}{0.01in}\begin{picture}(50,16)(0,0)\special{psfile=ps/exit.ps}\end{picture}}}
\newcommand\ReturnBitmap{{\setlength{\unitlength}{0.01in}\begin{picture}(50,16)(0,0)\special{psfile=ps/home.ps}\end{picture}}}
\newcommand\HelpBitmap{{\setlength{\unitlength}{0.01in}\begin{picture}(50,16)(0,0)\special{psfile=ps/help.ps}\end{picture}}}
\newcommand\UpBitmap{{\setlength{\unitlength}{0.01in}\begin{picture}(50,16)(0,0)\special{psfile=ps/up.ps}\end{picture}}}
\newcommand{\tpd}[5]{{\setlength{\unitlength}{0.01in}\begin{picture}(#1,#2)(#3,#4)\special{psfile=#5}\end{picture}}}
\begin{document}
\begin{titlepage}
\center{\includegraphics{ps/axiomFront.ps}}
\vskip 0.1in
\includegraphics{ps/bluebayou.ps}\\
\vskip 0.1in
{\Huge{The 30 Year Horizon}}
\vskip 0.1in
$$
\begin{array}{lll}
Manuel\ Bronstein & William\ Burge & Timothy\ Daly \\
James\ Davenport & Michael\ Dewar & Martin\ Dunstan \\
Albrecht\ Fortenbacher & Patrizia\ Gianni & Johannes\ Grabmeier \\
Jocelyn\ Guidry & Richard\ Jenks & Larry\ Lambe \\
Michael\ Monagan & Scott\ Morrison & William\ Sit \\
Jonathan\ Steinbach & Robert\ Sutor & Barry\ Trager \\
Stephen\ Watt & Jim\ Wen & Clifton\ Williamson
\end{array}
$$
\center{\large{VOLUME 1: TUTORIAL}}
\end{titlepage}
\pagenumbering{roman}
\begin{verbatim}
The Blue Bayou image Copyright (c) 2004 Jocelyn Guidry
Portions Copyright (c) 2004 Martin Dunstan
Portions Copyright (c) 19912002, 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}
\tableofcontents
\vfill
\eject
\setlength{\parindent}{0em}
\setlength{\parskip}{1ex}
{\Large{\bf New Foreword}}
\vskip .25in
On October 1, 2001 Axiom was withdrawn from the market and ended
life as a commercial product.
On September 3, 2002 Axiom was released under the Modified BSD
license, including this document.
On August 27, 2003 Axiom was released as free and open source
software available for download from the Free Software Foundation's
website, Savannah.
Work on Axiom has had the generous support of the Center for
Algorithms and Interactive Scientific Computation (CAISS) at
City College of New York. Special thanks go to Dr. Gilbert
Baumslag for his support of the long term goal.
The online version of this documentation is roughly 1000 pages.
In order to make printed versions we've broken it up into three
volumes. The first volume is tutorial in nature. The second volume
is for programmers. The third volume is reference material. We've
also added a fourth volume for developers. All of these changes
represent an experiment in printondemand delivery of documentation.
Time will tell whether the experiment succeeded.
Axiom has been in existence for over thirty years. It is estimated to
contain about three hundred manyears of research and has, as of
September 3, 2003, 143 people listed in the credits. All of these
people have contributed directly or indirectly to making Axiom
available. Axiom is being passed to the next generation. I'm looking
forward to future milestones.
With that in mind I've introduced the theme of the ``30 year horizon''.
We must invent the tools that support the Computational Mathematician
working 30 years from now. How will research be done when every bit of
mathematical knowledge is online and instantly available? What happens
when we scale Axiom by a factor of 100, giving us 1.1 million domains?
How can we integrate theory with code? How will we integrate theorems
and proofs of the mathematics with spacetime complexity proofs and
running code? What visualization tools are needed? How do we support
the conceptual structures and semantics of mathematics in effective
ways? How do we support results from the sciences? How do we teach
the next generation to be effective Computational Mathematicians?
The ``30 year horizon'' is much nearer than it appears.
\vskip .25in
%\noindent
Tim Daly\\
CAISS, City College of New York\\
November 10, 2003 ((iHy))
\vfill
\eject
\pagenumbering{arabic}
\setcounter{chapter}{0} % Chapter 1
\chapter{Introduction to Axiom}
\label{ugNewIntro}
\section{Introduction to Axiom}
Welcome to the world of Axiom.
We call Axiom a scientific computation system:
a selfcontained 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({{1\over{(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:
$$
{\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({{{2 \ {\sqrt{3}}\ {{\root{3}\of{a}}^
2}\ {\root{3}\of{{b \ x}+ a}}}+{a \ {\sqrt{3}}}}\over{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)}\over{{18}\ {a^2}\ {x^2}\ {\sqrt{3}}\ {\root{3}\of{a}}}
$$
\returnType{Type: Union(Expression Integer,...)}
Axiom provides stateoftheart 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**4949*x**4+9 = 0,1.e49)}
$$
\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, nonlinear optimization, linear
algebra, basic statistics, stepwise 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.
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$}
\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 hardcopy output.
\subsection{HyperDoc}
\begin{figure}[htbp]
\includegraphics[bbllx=1, bblly=1, bburx=298, bbury=290]{ps/hroot.ps}
\caption{Hyperdoc opening menu}
\label{figintrobr}
\end{figure}
HyperDoc presents you windows on the world of Axiom,
offering online help, examples, tutorials, a browser, and reference
material. HyperDoc gives you online 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 mouseactive; 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 Figure \ref{figintrobr} on
page~\pageref{figintrobr} 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 userdefined function is one
that computes the successive Legendre polynomials. Axiom lets
you define these polynomials in a piecewise way.
The first Legendre polynomial.
\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*n1)*x*p(n1)  (n1) * p(n2))/n}
\returnType{Type: Void}
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 computationthey 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}
$$
{{{46189} \over {256}} \ {x \sp {10}}} {{{109395} \over {256}} \ {x \sp
8}}+{{{45045} \over {128}} \ {x \sp 6}} {{{15015} \over {128}} \ {x \sp
4}}+{{{3465} \over {256}} \ {x \sp 2}} {{63} \over {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 machinecode. 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)}
$$
{5688265542052017822223458237426581853561497449095175} \over
{77371252455336267181195264}
$$
\returnType{Type: Polynomial Fraction Integer}
In general, a user function is typeanalyzed 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}, {{{{15}\over 2}\ {x^2}}{3 \over 2}},
{{{{35}\over 2}\ {x^3}}{{{15}\over 2}\ x}}, {{{{315}\over
8}\ {x^4}}{{{105}\over 4}\ {x^2}}+{{15}\over 8}}, \right.
\\
\\
\displaystyle
\left.{{{{693}\over 8}\ {x^5}}{{{315}\over 4}\ {x^3}}+{{{105}\over
8}\ x}}, {{{{3003}\over{16}}\ {x^6}}{{{3465}\over{16}}\ {x^
4}}+{{{945}\over{16}}\ {x^2}}{{35}\over{16}}}, \right.
\\
\\
\displaystyle
\left.{{{{6435}\over{16}}\ {x^7}}{{{9009}\over{16}}\ {x^5}}+
{{{3465}\over{16}}\ {x^3}}{{{315}\over{16}}\ x}}, \right.
\\
\\
\displaystyle
\left.{{{{109395}\over{128}}\ {x^8}}{{{45045}\over{32}}\ {x^
6}}+{{{45045}\over{64}}\ {x^4}}{{{3465}\over{32}}\ {x^2}}+{{3
15}\over{128}}}, \right.
\\
\\
\displaystyle
\left.{{{{230945}\over{128}}\ {x^9}}{{{109395}\over{32}}\ {x^
7}}+{{{135135}\over{64}}\ {x^5}}{{{15015}\over{32}}\ {x^3}}+
{{{3465}\over{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.
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({{{2 \ x}+ \pi}\over 2}\right)}+
{{1 \over 3}\ {{\left(x {\pi \over 2}\right)}^2}}+
{{7 \over{90}}\ {{\left(x {\pi \over 2}\right)}^4}}+
{{{62}\over{2835}}\ {{\left(x {\pi \over 2}\right)}^6}}+
\\
\\
\displaystyle
{{{127}\over{18900}}\ {{\left(x {\pi \over 2}\right)}^8}}+
{{{146}\over{66825}}\ {{\left(x {\pi \over 2}\right)}^{10}}}+
{O \left({{\left(x {\pi \over 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)}
$$
{44590788901016030052447242300856550965644} \over
{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}
{x+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}
{1 \over {x+i}} & 0 \\
{1 \over {{2 \ x}+{2 \ i}}} & {1 \over 2}
\end{array}
\right]
$$
\returnType{Type: Union(Matrix Fraction Polynomial Complex Integer,...)}
\subsection{Pattern Matching}
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}
Solve the system $S$ using rational number arithmetic and
30 digits of accuracy.
\spadcommand{solve(S,1/10**30)}
$$
\left[
{\left[ {y=2}, {x={{1757879671211184245283070414507} \over
{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 ={{{\sqrt{ 3}}+ 1}\over 2}}\right]}, \right.
\\
\\
\displaystyle
\left.{\left[{y = 2}, {x ={{{\sqrt{ 3}}+ 1}\over 2}}\right]},
{\left[{y =  2}, {x ={1 \over{\root{3}\of{3}}}}\right]},
\right.
\\
\\
\displaystyle
\left.{\left[{y =  2}, {x ={{{{\sqrt{ 1}}\ {\sqrt{3}}} 1}\over{2
\ {\root{3}\of{3}}}}}\right]}, {\left[{y =  2}, {x ={{{{\sqrt{
1}}\ {\sqrt{3}}} 1}\over{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 runtime 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
\chapter{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 typechecking. Unlike these languages, types in
Axiom are dynamic objects: they are created at runtime 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.
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 easeofuse.
The Axiom interpreter uses typeinferencing 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:
\subsection{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 lowerlevel 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}.
\subsection{The Type of Basic Objects is a Domain or Subdomain}
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.
\subsection{Domains Have Types Called Categories}
Domain 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 typecorrectness. 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.
\subsection{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}
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.
\subsection{Categories Form Hierarchies}
Categories form hierarchies (technically, directedacyclic 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}
\subsection{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 lexicographiccomparison in an algorithm.
However, it is wrong to use the same {\tt <} with this definition
of absolutevalue: $$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}.
\subsection{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}
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}:
floatingpoint numbers, rational numbers, complex rational functions,
and power series, to name a few.
\subsection{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 = \pmatrix{x^2+1&0\cr0&x / 2\cr}$$
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''.
\subsection{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 typechecking at compile time;
\item fast linkage to operations in domainvalued parameters;
\item optimization techniques to be used for partially specified types
(operations for ``vectors of $R$'', for instance, can be opencoded even
though {\tt R} is unknown).
\end{itemize}
\subsection{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.
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 codeeconomy.
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{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}
$$
2 \over 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
informatin 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{(4.6)::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}
$$
{23} \over 5
$$
\returnType{Type: Fraction Integer}
where ``\%'' represents the previous {\it result} (not the calculation).
Although Axiom has the ability to work with floatingpoint 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 partof $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 {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 + \%i)**3}
$$
{{46} \over {27}}+{{1 \over 3} \ 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*\%i)}
$$
3
$$
\returnType{Type: PositiveInteger}
\spadcommand{imag(3+ 2*\%i)}
$$
2
$$
\returnType{Type: PositiveInteger}
\spadcommand{conjugate(3 + 2*\%i)}
$$
3 {2 \ 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*\%i}
$$
{144}+{{24} \ 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 floatingpoint values in exponent notation
and the latter causes it to use fixedpoint notation. For example:
\spadcommand{outputFloating(); \%}
$$
0.3141592653 5897932384 6264338327 9502884197 E 1
$$
\returnType{Type: Float}
\spadcommand{outputFloating(3); 0.00345}
$$
0.345 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 {3 \over {2 \sp 2}}+{3 \over 5}
$$
\returnType{Type: PartialFraction Integer}
\spadcommand{padicFraction(\%)}
$$
6 {1 \over 2} {1 \over {2 \sp 2}}+{3 \over 5}
$$
\returnType{Type: PartialFraction Integer}
\spadcommand{compactFraction(\%)}
$$
6 {3 \over {2 \sp 2}}+{3 \over 5}
$$
\returnType{Type: PartialFraction Integer}
\spadcommand{padicFraction(234/40)}
$$
{117} \over {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 numberOf FractionalTerms}:
\spadcommand{t := partialFraction(234,40)}
$$
6 {3 \over {2 \sp 2}}+{3 \over 5}
$$
\returnType{Type: PartialFraction Integer}
\spadcommand{wholePart(t)}
$$
6
$$
\returnType{Type: PositiveInteger}
\spadcommand{numberOfFractionalTerms(t)}
$$
2
$$
\returnType{Type: PositiveInteger}
\spadcommand{p := nthFractionalTerm(t,1)}
$$
{3 \over {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 nonzero values if the arithmetic
is performed modulo a prime number. Thus arithmetic modulo a nonprime
integer is possible but the reciprocal operation is undefined and will
generate an error. Attempting to use the {\tt PrimeField} type constructor
with a nonprime argument will generate an error. An example of nonprime
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. Multiline
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 and a description placed after a calculation begins with
two plus signs ``++''. The socalled ``plus plus'' comments are used
within the algebra files and are processed by the compiler to add
to the documentation. The socalled ``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 $n1$ 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
sideeffect 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 onedimensional 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}
Onedimensional array 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 onedimensional 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.
Onedimensional 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 onedimensional 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 onedimensional 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[
{1 \over 2}, {1 \over 3}, {1 \over {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 onedimensional 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 onedimensional
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 b.2} above did not alter
{\sl a}. 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 oneline 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 different 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 userdefined
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 ifthenelse} 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 ifthenelse} 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  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}
\begin{verbatim}
x:=1
y:=1
while x < 4 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 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
\begin{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 rowmajor
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)
\end{verbatim}
\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)
\end{verbatim}
\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}  {\sl BoolExpr} in {\sl seg} repeat {\sl loopBody}\\
for {\sl var}  {\sl BoolExpr} in {\sl list} repeat {\sl loopBody}
\end{center}
Some examples are:
\begin{verbatim}
for i in 1..10  prime?(i) repeat
output(i)
\end{verbatim}
\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)
\end{verbatim}
\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)
\end{verbatim}
\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)
\{verbatim}
\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]
\end{verbatim}
\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 predefined. 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]
\end{verbatim}
\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]
\end{verbatim}
\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.
%\setcounter{chapter}{0} % Chapter 1
\hyphenation{
multiset
UnivariatePolynomial
MultivariatePolynomial
DistributedMultivariatePolynomial
HomogeneousDistributedMultivariatePolynomial
NewDistributedMultivariatePolynomial
GeneralDistributedMultivariatePolynomial
}
\chapter{An Overview of Axiom}
\label{ugIntro}
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 startup
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}
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 multiplewindow hypertext system
that lets you \index{window} view Axiom documentation and
examples online, 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 Chapter \ref{ugHyper} on page~\pageref{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.
\boxed{4.6in}{
\vskip 0.1cm
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.
\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 CtrlEnd} 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.
\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}
$$
{{19} \over 4}
$$
\returnType{Type: Fraction Integer}
The above expression is equivalent to this.
\spadcommand{((1 + 2)  ((3 / 4) * (3 ** 2)))  1}
$$
{{19} \over 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))}
$$
{11} \over 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}
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.
Chapter~\ref{ugTypes} on page~\pageref{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)}
$$
1 \over {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.
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 Section \ref{ugLangAssign} on page~\pageref{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+{3 \over 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 righthand side of assignment
2

3
to an object of the type Integer of the lefthand side.
\end{verbatim}
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
\ref{ugTypesConvert} on page~\pageref{ugTypesConvert}.} For example,
to display an object, it is necessary to convert the object to type
{\tt OutputForm}.
This produces a polynomial with rational number coefficients.
\spadcommand{p := r**2 + 2/3}
$$
{r \sp 2}+{2 \over 3}
$$
\returnType{Type: Polynomial Fraction Integer}
Create a quotient of polynomials with integer coefficients
by using ``{\tt ::}''.
\spadcommand{p :: Fraction Polynomial Integer }
$$
{{3 \ {r \sp 2}}+2} \over 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 floatingpoint 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.
\subsection{Some Predefined Macros}
\label{ugIntroMacros}
Axiom provides several macros for your convenience.\footnote{See
\ref{ugUserMacros} on page~\pageref{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 Section \ref{ugInOutIn} on page~\pageref{ugInOutIn}),
can use indentation to indicate the program structure .
(see Section \ref{ugLangBlocks} on page~\pageref{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 multiline comments other than starting
each line with ``{\tt }'' or ``{\tt ++}''.
\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}
$$
{55739} \over {2520}
$$
\returnType{Type: Fraction Integer}
To factor fractions, you have to pmap {\bf factor} onto the numerator
and denominator.
\spadcommand{map(factor,r)}
$$
{{139} \ {401}} \over {{2 \sp 3} \ {3 \sp 2} \ 5 \ 7}
$$
\returnType{Type: Fraction Factored Integer}
{\tt SingleInteger} refers to machine wordlength integers.
In English, this expression means ``$11$ as a small integer''.
\spadcommand{11@SingleInteger}
$$
11
$$
\returnType{Type: SingleInteger}
Machine doubleprecision floatingpoint numbers are also available for
numeric and graphical applications.
\spadcommand{123.21@DoubleFloat}
$$
123.21000000000001
$$
\returnType{Type: DoubleFloat}
The normal floatingpoint type in Axiom, {\tt Float}, is a
software implementation of floatingpoint 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 floatingpoint numbers.
This is a floatingpoint 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
floatingpoint 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}
$$
{{46} \over {27}}+{{1 \over 3} \ i}
$$
\returnType{Type: Complex Fraction Integer}
The standard operations on complex numbers are available.
\spadcommand{conjugate \% }
$$
{{46} \over {27}} {{1 \over 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}
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))}
$$
{{159} \over {2 \sp 8}} {{23} \over {3 \sp 4}} {{12} \over {5 \sp 2}}+{1
\over 7}
$$
\returnType{Type: PartialFraction Integer}
or expanded format.
\spadcommand{padicFraction(\%)}
$$
{1 \over 2}+{1 \over {2 \sp 4}}+{1 \over {2 \sp 5}}+{1 \over {2 \sp 6}}+{1
\over {2 \sp 7}}+{1 \over {2 \sp 8}} {2 \over {3 \sp 2}} {1 \over {3 \sp
3}} {2 \over {3 \sp 4}} {2 \over 5} {2 \over {5 \sp 2}}+{1 \over 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}
$$
{4 \over 7}+{{2 \over 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}
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 Section
\ref{ugxProblemFinitePrime} on page~\pageref{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
packagecalling 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)}
$$
2 \over {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}
If we do this, we should get $b$.
\spadcommand{2/\%+1}
$$
{\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)}\over{\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 noncommutative, 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{Lists are discussed in Section \ref{ListXmpPage} on
page~\pageref{ListXmpPage}} is the most commonly used data structure in
Axiom for holding objects all of the same type. The name {\it list} is
short for ``linkedlist 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}
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{Streams are discussed in Section{StreamXmpPage} on
page~\pageref{StreamXmpPage}}
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 alreadycomputed
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 onedimensional array} is another data structure used to hold
objects of the same type \footnote{OnedimensionalArray is discussed in
Section \ref{OneDimensionalArrayXmpPage} on
page~\pageref{OneDimensionalArrayXmpPage}}. Unlike lists,
onedimensional arrays are inflexiblethey are
\index{array!onedimensional} implemented using a fixed block of
storage. Their advantage is that they give quick and equal access
time to any element.
A simple way to create a onedimensional 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, {3 \over 2}
\right]
$$
\returnType{Type: OneDimensionalArray Fraction Integer}
Onedimensional arrays are also mutable: you can change their
constituent elements ``in place.''
\spadcommand{a.3 := 11; a}
$$
\left[
1, 7, {11}, {3 \over 2}
\right]
$$
\returnType{Type: OneDimensionalArray Fraction Integer}
However, onedimensional 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
packagecalling 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 onedimensional 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{FlexibleArray is discussed in Section
\ref{FlexibleArrayXmpPage} on page~\pageref{FlexibleArrayXmpPage}} is
a cross between a list \index{array!flexible} and a onedimensional
array. Like a onedimensional 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}
Flexible arrays are used to implement ``heaps.'' A {\it heap} is an
example of a data structure called a {\it priority queue}, where
elements are ordered with respect to one another. A heap
\footnote{Heap is discussed in Section \ref{HeapXmpPage} on
page~\pageref{HeapXmpPage}} 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 {\it 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 oneatatime 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). \footnote{BinarySearchTrees are discussed in Section
\ref{BinarySearchTreeXmpPage} on page~\pageref{BinarySearchTreeXmpPage}}
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.
\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.
\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{Sets are discussed in Section \ref{SetXmpPage}
on page~\pageref{SetXmpPage}} 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\{
{1 \over 3}, {1 \over 3}, {4 \over 5}
\right\}
$$
\returnType{Type: Set Fraction Integer}
A {\it multiset} is a set that keeps track of the number of duplicate
values. \footnote{Multisets are discussed in Section
\ref{MultiSetXmpPage} on page~\pageref{MultiSetXmpPage}}
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 ``keyvalue'' 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 generalpurpose 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 \ref{ugTypesRecords} on
page~\pageref{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}
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 \ref{ugTypesUnions} on
page~\pageref{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 Chapter \ref{ugDomains} on
page~\pageref{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 onedimensional
aggregates with elements that are themselves aggregates, for example,
lists of lists, onedimensional arrays of lists of multisets, and so
on. For applications requiring twodimensional homogeneous
aggregates, you will likely find {\it twodimensional arrays}
\index{matrix} and {\it matrices} most useful.
\index{array!twodimensional}
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 {\tt Matrix},
{\tt Permanent}, {\tt SquareMatrix}, {\tt Vector}, see Section
\ref{ugProblemEigen} on page~\pageref{ugProblemEigen} (computation of
eigenvalues and eigenvectors), and Section \ref{ugProblemLinPolEqn} on
page~\pageref{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}
The ``collections'' construct (see \ref{ugLangIts} on
page~\pageref{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}
{1 \over {x 2}} & {1 \over {x 3}} & {1 \over {x 4}} & {1 \over {x 5}} \\
{1 \over {x 3}} & {1 \over {x 4}} & {1 \over {x 5}} & {1 \over {x 6}} \\
{1 \over {x 4}} & {1 \over {x 5}} & {1 \over {x 6}} & {1 \over {x 7}} \\
{1 \over {x 5}} & {1 \over {x 6}} & {1 \over {x 7}} & {1 \over {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.
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
Chapter \ref{ugUser} on page~\pageref{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!piecewise definition} piecewise definition of the
function. \index{piecewise 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(n1)}
\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 ifthenelse} 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 spaceconsumptive version.
\spadcommand{fa(50)}
\begin{verbatim}
Compiling function fac with type Integer > Integer
\end{verbatim}
$$
30414093201713378043612608166064768844377641568960512000000000000
$$
\returnType{Type: PositiveInteger}
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 oneline functions in Axiom. If you place your
function definitions in {\bf .input} files \index{file!input} (see
\ref{ugInOutIn} on page~\pageref{ugInOutIn}), you can have multiline
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 rightmultiplied.
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 ifthenelse} 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}
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 twoargument 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 (userdefined) 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.
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 nonzero
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. Socalled
``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
nonlinear 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*x1)**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**2x*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)}
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, nonrecursive) 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
Section \ref{ugProblemLimits} on page~\pageref{ugProblemLimits}.
You can take limits of functions with parameters.
\index{limit!of function with parameters}
\spadcommand{g := csc(a*x) / csch(b*x)}
$$
{\csc
\left(
{{a \ x}}
\right)}
\over {\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)}
$$
b \over a
$$
\returnType{Type: Union(OrderedCompletion Expression Integer,...)}
A variable may also approach plus or minus infinity:
\spadcommand{h := (1 + k/x)**x}
$$
{{x+k} \over x} \sp x
$$
\returnType{Type: Expression Integer}
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 \ref{ugProblemSeries} on
page~\pageref{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} {{{a \sp 3} \over 6} \ {x \sp 3}}+{{{a \sp 5} \over {120}} \ {x
\sp 5}} {{{a \sp 7} \over {5040}} \ {x \sp 7}}+{{{a \sp 9} \over {362880}}
\ {x \sp 9}} {{{a \sp {11}} \over {39916800}} \ {x \sp {11}}}+{O
\left(
{{x \sp {12}}}
\right)}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}
This expression expands {\tt sin(a*x)} in powers of {\tt (x  \%pi/4)}.
\spadcommand{series(sin(a*x),x = \%pi/4)}
$$
{\sin
\left({{{a \ \pi} \over 4}}\right)}+
{a \ {\cos \left({{{a \ \pi} \over 4}} \right)}
\ {\left( x {\pi \over 4} \right)}}
\hbox{\hskip 2.0cm}
$$
$$
{{{{a \sp 2} \ {\sin \left({{{a \ \pi} \over 4}} \right)}}\over 2}
\ {{\left( x {\pi \over 4} \right)}\sp 2}} 
{{{{a \sp 3} \ {\cos \left({{{a \ \pi} \over 4}} \right)}}\over 6}
\ {{\left( x {\pi \over 4} \right)}\sp 3}} +
$$
$$
{{{{a \sp 4} \ {\sin \left({{{a \ \pi} \over 4}} \right)}}\over {24}}
\ {{\left( x {\pi \over 4} \right)}\sp 4}} +
{{{{a \sp 5} \ {\cos \left({{{a \ \pi} \over 4}} \right)}}\over {120}}
\ {{\left( x {\pi \over 4} \right)}\sp 5}} 
$$
$$
{{{{a \sp 6} \ {\sin \left({{{a \ \pi} \over 4}} \right)}}\over {720}}
\ {{\left( x {\pi \over 4} \right)}\sp 6}} 
{{{{a \sp 7} \ {\cos \left({{{a \ \pi} \over 4}} \right)}}\over {5040}}
\ {{\left( x {\pi \over 4} \right)}\sp 7}} +
$$
$$
{{{{a \sp 8} \ {\sin \left({{{a \ \pi} \over 4}} \right)}}\over {40320}}
\ {{\left( x {\pi \over 4} \right)}\sp 8}} +
{{{{a \sp 9} \ {\cos \left({{{a \ \pi} \over 4}} \right)}}\over {362880}}
\ {{\left( x {\pi \over 4} \right)}\sp 9}} 
$$
$$
{{{{a \sp {10}} \ {\sin \left({{{a \ \pi} \over 4}} \right)}}
\over {3628800}}
\ {{\left( x {\pi \over 4} \right)}\sp {10}}} +
{O \left({{{\left( x {\pi \over 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 inplace 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 {4 \over 3}} {{1 \over 6} \ {x \sp {{10} \over 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/(1x)$.
\index{series!Taylor}
\spadcommand{f := series(1/(1x),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/(1x),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+
{{1 \over 2} \ {x \sp 2}}+
{{1 \over 3} \ {x \sp 3}}+
{{1 \over 4} \ {x \sp 4}}+
{{1 \over 5} \ {x \sp 5}}+
{{1 \over 6} \ {x \sp 6}}+
{{1 \over 7} \ {x \sp 7}}+
\\
\\
\displaystyle
{{1 \over 8} \ {x \sp 8}}+
{{1 \over 9} \ {x \sp 9}}+
{{1 \over {10}} \ {x \sp {10}}}+
{{1 \over {11}} \ {x \sp {11}}}+
{O \left({{x \sp {12}}} \right)}
\end{array}
$$
\returnType{Type: UnivariatePuiseuxSeries(Expression Integer,x,0)}
\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+{{1 \over 2} \ {x \sp 2}}+{{1 \over 6} \ {x \sp 3}}+{{1 \over {24}} \
{x \sp 4}}+{{1 \over {120}} \ {x \sp 5}}+{{1 \over {720}} \ {x \sp 6}} +
\hbox{\hskip 1.0cm}
$$
$$
{{1
\over {5040}} \ {x \sp 7}} +
{{1 \over {40320}} \ {x \sp 8}}+{{1 \over
{362880}} \ {x \sp 9}}+{{1 \over {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}
\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))}
$$
{\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)}\over{z + 1}
$$
\returnType{Type: Expression Integer}
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)}
$$
{\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)}
\over{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 factorizationfree algorithm.
\spadcommand{integrate((x**2+2*x+1)/((x+1)**6+1),x)}
$$
{\arctan
\left(
{{{x \sp 3}+{3 \ {x \sp 2}}+{3 \ x}+1}}
\right)}
\over 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[
{{\log
\left(
{{{{{\left( {x \sp 2} a
\right)}
\ {\sqrt {a}}}+{2 \ a \ x}} \over {{x \sp 2}+a}}}
\right)}
\over {2 \ {\sqrt {a}}}}, {{\arctan
\left(
{{{x \ {\sqrt {a}}} \over a}}
\right)}
\over {\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.
$$
{{\log
\left(
{{{{x \ {\sqrt {a}}}+a} \over {\sqrt {a}}}}
\right)}
{\log
\left(
{{{{x \ {\sqrt {a}}} a} \over {\sqrt {a}}}}
\right)}}
\over {2 \ {\sqrt {a}}}
$$
\returnType{Type: Expression Integer}
The following two examples illustrate the limitations of tablebased
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)}
$$
{{\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}} \over {{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)}
$$
\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(
{{{{2 \ {\sqrt {3}} \ {{\root {3} \of {a}} \sp 2} \ {\root {3} \of {{{b \
x}+a}}}}+{a \ {\sqrt {3}}}} \over {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)
\over {{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 tabledriven
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} {{{\log
\left(
{{{\sqrt {{b+{ \%Q \ a}}}}+1}}
\right)}
\over \%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(
{{{{2 \ {\cosh
\left(
{{{\sqrt {{x+b}}}+1}}
\right)}}
{2 \ x}} \over {{\sinh
\left(
{{{\sqrt {{x+b}}}+1}}
\right)}
{\cosh
\left(
{{{\sqrt {{x+b}}}+1}}
\right)}}}}
\right)}}
{2 \ {\sqrt {{x+b}}}}
$$
\returnType{Type: Union(Expression Integer,...)}
A strong structurechecking 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
$$
\left(
\begin{array}{@{}l}
{8 \ {\log
\left(
{{{3 \ {{\tan
\left(
{{{\arctan
\left(
{x}
\right)}
\over 3}}
\right)}
\sp 2}} 1}}
\right)}}
{3 \ {{\tan
\left(
{{{\arctan
\left(
{x}
\right)}
\over 3}}
\right)}
\sp 2}}+
\\
\\
\displaystyle
{{18} \ x \ {\tan
\left(
{{{\arctan
\left(
{x}
\right)}
\over 3}}
\right)}}
\end{array}
\right)
\over {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^33xg^23g+x=0}$$
\item
Integrate $g$ using this algebraic relation; this produces:
$${{(24g^2  8)\log(3g^2  1) + (81x^2 + 24)g^2 + 72xg  27x^2  16}
\over{54g^2  18}}$$
\item
Rationalize the denominator, producing:
$${8\log(3g^21)  3g^2 + 18xg + 16} \over {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)}
$$
{{2 \ {\sqrt {{{\log
\left(
{x}
\right)}+x}}}}
\over {{\log
\left(
{x}
\right)}+x}}
$$
\returnType{Type: Union(Expression Integer,...)}
While incomplete for nonelementary functions, Axiom can
handle some of them.
\spadcommand{integrate(exp(x**2) * erf(x) / (erf(x)**3  erf(x)**2  erf(x) + 1),x)}
$$
{{{\left( {\erf
\left(
{x}
\right)}
1
\right)}
\ {\sqrt {\pi}} \ {\log
\left(
{{{{\erf
\left(
{x}
\right)}
1} \over {{\erf
\left(
{x}
\right)}+1}}}
\right)}}
{2 \ {\sqrt {\pi}}}} \over {{8 \ {\erf
\left(
{x}
\right)}}
8}
$$
\returnType{Type: Union(Expression Integer,...)}
More examples of Axiom's integration capabilities are discussed in
Section \ref{ugProblemIntegration} on page~\pageref{ugProblemIntegration}.
\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={{{x \sp 5} {{10} \ {x \sp 3}}+{{20} \ {x \sp 2}}+4} \over
{{15} \ x}}},
\right.
\\
\\
\displaystyle
\left.
{basis={\left[ {{{2 \ {x \sp 3}} {3 \ {x \sp 2}}+1}
\over x}, {{{x \sp 3} 1} \over x}, {{{x \sp 3} {3 \ {x \sp 2}} 1}
\over 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[ {1 \over {\sqrt {{{x \sp 2}+1}}}},
{{\log
\left(
{{{\sqrt {{{x \sp 2}+1}}} x}}
\right)}
\over {\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( {2 \over {\sqrt {x}}}
\right)}},
{e \sp {2 \over {\sqrt {x}}}}
\right]
$$
\returnType{Type: List Expression Integer}
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)}={{y
\left(
{x}
\right)}
\over {{{y
\left(
{x}
\right)}
\ {\log
\left(
{{y
\left(
{x}
\right)}}
\right)}}+x}}
$$
\returnType{Type: Equation Expression Integer}
\spadcommand{solve(deq, y, x)}
$$
{{{y
\left(
{x}
\right)}
\ {{\log
\left(
{{y
\left(
{x}
\right)}}
\right)}
\sp 2}} {2 \ x}} \over {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+
{{1 \over 3} \ {t \sp 3}}+
{{2 \over {15}} \ {t \sp 5}}+
{{{17} \over {315}} \ {t \sp 7}}+
{{{62} \over {2835}} \ {t \sp 9}}+
{O \left({{t \sp {11}}} \right)}},
\right.
\hbox{\hskip 2.0cm}
$$
$$
\hbox{\hskip 0.4cm}
\left.
{1+
{{1 \over 2} \ {t \sp 2}}+
{{5 \over {24}} \ {t \sp 4}}+
{{{61} \over {720}} \ {t \sp 6}}+
{{{277} \over {8064}} \ {t \sp 8}}+
{{{50521} \over {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 stateoftheart 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.
A system of two equations involving a symbolic parameter $t$.
\spadcommand{S(t) == [x**22*y**2  t,x*yy5*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={{2451682632253093442511} \over
{295147905179352825856}}}
\right]},
\right.
$$
$$
\left.
{\left[ {y=5}, {x={{2451682632253093442511} \over
{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.e20)}
$$
\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 {{{a+1} \over 2}}}} \right]},
{\left[ {x=1}, {y={\sqrt {{{a+1} \over 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}
Solve the system for unknowns $[x,y,z]$,
reducing the solution to triangular form.
\spadcommand{solve(eqns,[x,y,z])}
$$
\left[
{\left[ {x={a \over b}}, {y=0}, {z={{a \sp 2} \over {b \sp 2}}}
\right]},
\right.
\hbox{\hskip 10.0cm}
$$
$$
\left.
\begin{array}{@{}l}
\left[
{x={{{z \sp 3}+{2 \ b \ {z \sp 2}}+{{b \sp 2} \ z} a} \over b}},
{y={z+b}},
\right.
\hbox{\hskip 10.0cm}
\\
\\
\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}}
\hbox{\hskip 4.0cm}
\\
\\
\displaystyle
\left.
{2 \ a \ {b \sp 2} \ z} {b \sp 3}+{a \sp 2}=0
\right]
\end{array}
\right]
\hbox{\hskip 7.0cm}
$$
\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}.
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$ piecewise.''
\spadcommand{f(0) == 1; g(0) == 1}
\returnType{Type: Void}
``Here is the general term for $f$.''
\spadcommand{f(n) == e/2*f(n1)  x*g(n1)}
\returnType{Type: Void}
``And here is the general term for $g$.''
\spadcommand{g(n) == x*f(n1) + d/3*g(n1)}
\returnType{Type: Void}
``What is value of $f(3)$?''
\spadcommand{f(3)}
$$
{x \sp 3}+{{\left( e+{{1 \over 3} \ d}
\right)}
\ {x \sp 2}}+{{\left( {{1 \over 4} \ {e \sp 2}} {{1 \over 6} \ d \ e}
{{1 \over 9} \ {d \sp 2}}
\right)}
\ x}+{{1 \over 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(n1)  x*g(n1)}
\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(n1) + d/3*g(n1)
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}} {{1 \over 3} \ {d \sp 2} \ x}+{{1 \over {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+{{1 \over 3} \ d}
\right)}
\ {x \sp 2}}+{{\left( {{1 \over 4} \ {e \sp 2}} {{1 \over 6} \ d \ e}
{{1 \over 9} \ {d \sp 2}}
\right)}
\ x}+{{1 \over 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 straightline program onto the file
{\bf mynew.input} on your disk.
\section{Graphics}
\label{ugIntroGraphics}
Axiom has a two and threedimensional 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 twodimensional 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/rose1.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$}
\end{figure}
This is an example of Axiom's threedimensional 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 Section \ref{ugProblemNumeric} on page~\pageref{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/atan1.ps}
\begin{figure}[htbp]
\includegraphics[bbllx=14, bblly=14, bburx=175, bbury=185]{ps/P28b.eps}
\caption{atan}
\end{figure}
An exhibit of Axiom images is given later. For a description of the
commands and programs that produced these figures, see
\ref{ugAppGraphics} on page~\pageref{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 \ref{ugGraph} on
page~\pageref{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}
\label{ugTypes}
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 floatingpoint
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
floatingpoint 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)}.''
After an Axiom computation, the type is displayed toward the
righthand 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 $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.
\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}
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}
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}
%
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 the appendix. 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 systemwide 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 categoriesand all categories these other categories
extendare also exported by the domains.
For example, polynomial domains belong to {\tt PolynomialCategory}.
This category explicitly mentions some twentynine 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 Chapter
\ref{ugCategories} on page~\pageref{ugCategories}.
We now return to our discussion of domains.
Domains {\it export} a set of operations to make them available for
systemwide 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
domainbut 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 \ref{ugTypesConvert} on page~\pageref{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.
\section{Writing Types and Modes}
\label{ugTypesWriting}
We have already seen in the last section \ref{ugTypesBasic} on
page~\pageref{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 Section \ref{ugTypesDeclare} on page~\pageref{ugTypesDeclare}),
\spadcommand{f : Integer > String}
\returnType{Type: Void}
You need to do so when you convert an object from one type to another
(See Section \ref{ugTypesConvert} on page~\pageref{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 Section \ref{ugTypesPkgCall} on page~\pageref{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.
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 Section \ref{ugTypesPkgCall} on page~\pageref{ugTypesPkgCall})
then you should enclose the argument in parentheses.
\spadcommand{(2/3)@Fraction(Polynomial(Integer))}
$$
2 \over 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)}
$$
2 \over 3
$$
\returnType{Type: Fraction Polynomial Integer}
If the type is used in a declaration and the argument is a singleword
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 \\
{\tt UnivariatePolynomial(x, Float)} \\
{\tt MultivariatePolynomial([z,w,r], Complex Float)} \\
{\tt SquareMatrix(3, Integer)} \\
{\tt FactoredFunctions2(Integer,Fraction Integer)}
\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.\\
{\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 Section \ref{ugTypesDeclare}
on page~\pageref{ugTypesDeclare}) and conversions (Section
\ref{ugTypesConvert} on page~\pageref{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.
\boxed{4.6in}{
\vskip 0.1cm
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}
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
\ref{ugSysCmdwhat} on page~\pageref{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.
\boxed{4.6in}{
\vskip 0.1cm
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
Section \ref{ugIntroAssign} on page~\pageref{ugIntroAssign} and
Section \ref{ugLangAssign} on page~\pageref{ugLangAssign}.
To see how to declare your own functions,
see \ref{ugUserDeclare} on page~\pageref{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 righthand side of assignment
4

5
to an object of the type Integer of the lefthand 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}
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)}
$$
{4 \over {y+x}}+{{y \over 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 {2 \over 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 \ref{ugTypesConvert} on
page~\pageref{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.
\boxed{4.6in}{
\vskip 0.1cm
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.\\
}
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 lefthand 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)}
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}
\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}.
\boxed{4.6in}{
\vskip 0.1cm
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 floatingpoint number.
\spadcommand{sayBranch 2.718281828}
\begin{verbatim}
Float branch
\end{verbatim}
\returnType{Type: Void}
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,...)}
Assign it a rational number.
\spadcommand{r := 3/2}
$$
3 \over 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 (\ref{ugTypesRecords} on page~\pageref{ugTypesRecords}),
you can write {\tt Union} types \index{selector!union} with selectors.
\index{union!selector}
\boxed{4.6in}{
\vskip 0.1cm
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.
\ref{ugTypesUnionsWOSel} on page~\pageref{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 righthand argument.
\index{case} If you accidentally use the branch type on the righthand
side of {\tt case}, {\tt false} will be returned.
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}, {3 \over 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}
$$
3 \over 2
$$
\returnType{Type: Fraction Integer}
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}
\boxed{4.6in}{
\vskip 0.1cm
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}
\spadcommand{m := matrix [ [x3/4*\%i,z*y**2+1/2],[3/7*\%i*y**4  x,12\%i*9/5] ]}
$$
\left[
\begin{array}{cc}
{x {{3 \over 4} \ i}} & {{{y \sp 2} \ z}+{1 \over 2}} \\
{{{3 \over 7} \ i \ {y \sp 4}} x} & {{12} {{9 \over 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 {{3 \ i} \over 4}} & {{{y \sp 2} \ z}+{1 \over 2}} \\
{{{{3 \ i} \over 7} \ {y \sp 4}} x} & {{{60} {9 \ i}} \over 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}
{{{4 \ x} {3 \ i}} \over 4} & {{{2 \ {y \sp 2} \ z}+1} \over 2} \\
{{{3 \ i \ {y \sp 4}} {7 \ x}} \over 7} & {{{60} {9 \ i}} \over 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}
{{{4 \ x} {3 \ i}} \over 4} & {{{2 \ {y \sp 2} \ z}+1} \over 2} \\
{{{7 \ x}+{3 \ {y \sp 4} \ i}} \over 7} & {{{60} {9 \ i}} \over 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}
{{{4 \ x} {3 \ i}} \over 4} & {{{2 \ {y \sp 2} \ z}+1} \over 2} \\
{{{7 \ x}+{3 \ {y \sp 4} \ i}} \over 7} & {{{60} {9 \ i}} \over 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 \ref{ugTypesBasic} on page~\pageref{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.
Recall that $m$ looks like this.
\spadcommand{m}
$$
\left[
\begin{array}{cc}
{x {{3 \over 4} \ i}} & {{{y \sp 2} \ z}+{1 \over 2}} \\
{{{3 \over 7} \ i \ {y \sp 4}} x} & {{12} {{9 \over 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 \\
{{3 \over 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}
{{3 \over 4} \ i} & {1 \over 2} \\
0 & {{12} {{9 \over 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 \\
{{3 \over 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}
{{3 \over 4} \ i} & {1 \over 2} \\
0 & {{12} {{9 \over 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 \\
{{3 \ i} \over 7} & 0
\end{array}
\right]}
\ {y \sp 4}}+{{\left[
\begin{array}{cc}
1 & 0 \\
1 & 0
\end{array}
\right]}
\ x}+{\left[
\begin{array}{cc}
{{3 \ i} \over 4} & {1 \over 2} \\
0 & {{{60} {9 \ i}} \over 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}.
Currently, there are only two systemdefined 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 $32$, 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}
This is an element of {\tt Fraction Integer}.
\spadcommand{2 ** (2)}
$$
1 \over 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**(i1) for i in 2..5]} be? On one hand,
$i1$ 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,
$i1$ 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**(i1) 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**((i1) :: 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**((i1) 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}
\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 \ref{ugTypesDeclare} on page~\pageref{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}
$$
2 \over 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)}
$$
2 \over 3
$$
\returnType{Type: Float}
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.
\boxed{4.6in}{
\vskip 0.1cm
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.
\boxed{4.6in}{
\vskip 0.1cm
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 SmallFloat} on two
integers, you could write {\bf min}(4,89){\tt SmallFloat}. Another use of
package calling is to tell AXIOM to use a library function rather than a
function you defined. We discuss this in
Section \ref{ugUserUse} on page~\pageref{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
suchandsuch a type.'' The second says ``compute the result and then convert
to an object of suchandsuch 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 lefthand 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}
(By the way, the operation \spadfunFrom{concat}{String} or juxtaposition
is used to concatenate two strings.)
\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.
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}
{1 \over 8} & {1 \over 6} \\
{1 \over 4} & {1 \over 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}
{1 \over 8} & {1 \over 6} \\
{1 \over 4} & {1 \over 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}
{1 \over 8} & {1 \over 6} \\
{1 \over 4} & {1 \over 9}
\end{array}
\right]
$$
\returnType{Type: Matrix Fraction Integer}
\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
packagecalling 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.
\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 \ref{ugTypesPkgCall} on
page~\pageref{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}
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 \ref{ugUserTriangle} on
page~\pageref{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}
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 framebyframe basis. A {\it frame}
(see \ref{ugSysCmdframe} on page~\pageref{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 Chapter
\ref{ugBrowse} on page~\pageref{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}
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.
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 ComplexCategory 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
\ref{Complex} on page~\pageref{Complex} for more information on that and see
\ref{ugUserDeclare} on page~\pageref{ugUserDeclare}
for more information on function types.
%\setcounter{chapter}{2}
\chapter{Using HyperDoc}
\label{ugHyper}
\begin{figure}[htbp]
\begin{picture}(324,260)%(54,0)
\special{psfile=ps/hroot.ps}
\end{picture}
\caption{The HyperDoc root window page.}
\end{figure}
HyperDoc is the gateway to Axiom. \index{HyperDoc} It's both an
online tutorial and an online 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.
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
toplevel menu.
\section{Key Definitions}
\label{ugHyperKeys}
The following keyboard definitions are in effect throughout HyperDoc.
See \ref{ugHyperScroll} on page~\pageref{ugHyperScroll} and
\ref{ugHyperInput} on page~\pageref{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 toplevel window or quits the HyperDoc facility if you are at the toplevel.
\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.
Move the cursor with the mouse to the ``downarrow'' 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 ``uparrow'' 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
\ref{ugHyperInput} on page~\pageref{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 rightarrow \fbox{$\rightarrow$} and
leftarrow 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 topmost 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.
\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 toplevel 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 casesensitive, 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.
\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 ``pastedin.''
Click again on the button and you see that the pastedin 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 worryHyperDoc 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}
\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 fixedwidth.
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}
\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 twodimensional 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.
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.
\boxed{4.6in}{
\vskip 0.1cm
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 \ref{ugLangBlocks} on page~\pageref{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{startup profile file}
directory. \index{file!startup 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}
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 twodimensional 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}
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 TwoDimensional 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.
\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{1}. 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{
{{\hfill \left. {#1} \right}
\over
{\left {#2} \right. \hfill}
}
}
\end{verbatim}
\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.
>+x> here < <3 @@ %i @@
>+<2 @@ > > > habove < < <4 @@ %i @@
>+x> here < <4 @@ %i @@ >+<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}
By default, the output goes to the screen and is displayed before the
standard Axiom twodimensional 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}
\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}
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}
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}{0} % Appendix A
\newcommand{\lanb}{{\tt [}}
\newcommand{\ranb}{{\tt ]}}
\newcommand{\vertline}{$$}
\chapter{Axiom System Commands}
\label{ugSysCmd}
This chapter describes system commands, the commandline
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 useraccess 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 userlevel is {\tt interpreter}.
\index{userlevel}
In addition to the {\tt )set} command (discussed in
\ref{ugSysCmdset} on page~\pageref{ugSysCmdset})
you can use the HyperDoc settings facility to change the {\it userlevel.}
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}
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.
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{)boot}
\index{ugSysCmdboot}
\index{boot}
\par\noindent{\bf User Level Required:} development
\par\noindent{\bf Command Syntax:}
\begin{list}{}
\item {\tt )boot} {\it bootExpression}
\end{list}
\par\noindent{\bf Command Description:}
This command is used by Axiom system developers to execute
expressions written in the BOOT language.
For example,
\begin{verbatim}
)boot times3(x) == 3*x
\end{verbatim}
creates and compiles the Common Lisp function ``times3''
obtained by translating the BOOT code.
\par\noindent{\bf Also See:}
{\tt )fin} \index{ugSysCmdfin},
{\tt )lisp} \index{ugSysCmdlisp},
{\tt )set} \index{ugSysCmdset}, and
{\tt )system} \index{ugSysCmdsystem}.
\section{)cd}
\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{)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{)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
\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{)compile}
\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}.as}
\item {\tt )compile {\it directory/fileName}.as}
\item {\tt )compile {\it fileName}.ao}
\item {\tt )compile {\it directory/fileName}.ao}
\item {\tt )compile {\it fileName}.al}
\item {\tt )compile {\it directory/fileName}.al}
\item {\tt )compile {\it fileName}.lsp}
\item {\tt )compile {\it directory/fileName}.lsp}
\item {\tt )compile {\it fileName}.spad}
\item {\tt )compile {\it directory/fileName}.spad}
\item {\tt )compile {\it fileName} )new}
\item {\tt )compile {\it fileName} )old}
\item {\tt )compile {\it fileName} )translate}
\item {\tt )compile {\it fileName} )quiet}
\item {\tt )compile {\it fileName} )noquiet}
\item {\tt )compile {\it fileName} )moreargs}
\item {\tt )compile {\it fileName} )onlyargs}
\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}
\par\noindent{\bf Command Description:}
You use this command to invoke the new Axiom library compiler or
the old Axiom system compiler.
The {\tt )compile} system command is actually a combination of
Axiom processing and a call to the Aldor compiler.
It is performing doubleduty, acting as a frontend to
both the Aldor compiler and the old Axiom system
compiler.
(The old Axiom system compiler was written in Lisp and was
an integral part of the Axiom environment.
The Aldor compiler is written in C and executed by the operating system
when called from within Axiom.)
The command compiles files with file extensions {\it .as, .ao}
and {\it .al} with the
Aldor compiler and files with file extension {\it .spad} with the
old Axiom system compiler.
It also can compile files with file extension {\it .lsp}. These
are assumed to be Lisp files genererated by the Aldor
compiler.
If you omit the file extension, the command looks to see if you
have specified the {\tt )new} or {\tt )old} option.
If you have given one of these options, the corresponding compiler
is used.
Otherwise, the command first looks in the standard system
directories for files with extension {\it .as, .ao} and {\it
.al} and then files with extension {\it .spad}.
The first file found has the appropriate compiler invoked on it.
If the command cannot find a matching file, an error message is
displayed and the command terminates.
The {\tt )translate} option is used to invoke a special version
of the old system compiler that will translate a {\it .spad} file
to a {\it .as} file. That is, the {\it .spad} file will be parsed and
analyzed and a file using the new syntax will be created. By default,
the {\it .as} file is created in the same directory as the
{\it .spad} file. If that directory is not writable, the current
directory is used. If the current directory is not writable, an
error message is given and the command terminates.
Note that {\tt )translate} implies the {\tt )old} option so the
file extension can safely be omitted. If {\tt )translate} is
given, all other options are ignored.
Please be aware that the translation is not necessarily one
hundred percent complete or correct.
You should attempt to compile the output with the Aldor compiler
and make any necessary corrections.
We now describe the options for the new Aldor compiler.
The first thing {\tt )compile} does is look for a source code
filename among its arguments.
Thus
\begin{verbatim}
)compile mycode.as
)compile /u/jones/as/mycode.as
)compile mycode
\end{verbatim}
all invoke {\tt )compiler} on the file {\tt
/u/jones/as/mycode.as} if the current Axiom working
directory is {\tt /u/jones/as.} (Recall that you can set the
working directory via the {\tt )cd} command. If you don't set it
explicitly, it is the directory from which you started
Axiom.)
This is frequently all you need to compile your file.
This simple command:
\begin{enumerate}
\item Invokes the Aldor compiler and produces Lisp output.
\item Calls the Lisp compiler if the Aldor compilation was
successful.
\item Uses the {\tt )library} command to tell Axiom about
the contents of your compiled file and arrange to have those
contents loaded on demand.
\end{enumerate}
Should you not want the {\tt )library} command automatically
invoked, call {\tt )compile} with the {\tt )nolibrary} option.
For example,
\begin{verbatim}
)compile mycode.as )nolibrary
\end{verbatim}
The general description of Aldor command line arguments is in
the Aldor documentation.
The default options used by the {\tt )compile} command can be
viewed and set using the {\tt )set compiler args} Axiom
system command.
The current defaults are
\begin{verbatim}
O Fasy Fao Flsp laxiom MnoAXL_W_WillObsolete DAxiom
\end{verbatim}
These options mean:
\begin{itemize}
\item {\tt O}: perform all optimizations,
\item {\tt Fasy}: generate a {\tt .asy} file,
\item {\tt Fao}: generate a {\tt .ao} file,
\item {\tt Flsp}: generate a {\tt .lsp} (Lisp)
file,
\index{Lisp!code generation}
\item {\tt laxiom}: use the {\tt axiom} library {\tt libaxiom.al},
\item {\tt MnoAXL\_W\_WillObsolete}: do not display messages
about older generated files becoming obsolete, and
\item {\tt DAxiom}: define the global assertion {\tt Axiom} so that the
Aldor libraries for generating standalone code
are not accidentally used with Axiom.
\end{itemize}
To supplement these default arguments, use the {\tt )moreargs} option on
{\tt )compile.}
For example,
\begin{verbatim}
)compile mycode.as )moreargs "v"
\end{verbatim}
uses the default arguments and appends the {\tt v} (verbose)
argument flag.
The additional argument specification {\bf must be enclosed in
double quotes.}
To completely replace these default arguments for a particular
use of {\tt )compile}, use the {\tt )onlyargs} option.
For example,
\begin{verbatim}
)compile mycode.as )onlyargs "v O"
\end{verbatim}
only uses the {\tt v} (verbose) and {\tt O} (optimize)
arguments.
The argument specification {\bf must be enclosed in double quotes.}
In this example, Lisp code is not produced and so the compilation
output will not be available to Axiom.
To completely replace the default arguments for all calls to {\tt
)compile} within your Axiom session, use {\tt )set compiler args.}
For example, to use the above arguments for all compilations, issue
\begin{verbatim}
)set compiler args "v O"
\end{verbatim}
Make sure you include the necessary {\tt l} and {\tt Y}
arguments along with those needed for Lisp file creation.
As above, {\bf the argument specification must be enclosed in double
quotes.}
By default, the {\tt )library} system command {\it 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 toplevel 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.as )nolibrary
)library mycode )noexpose
\end{verbatim}
Once you have established your own collection of compiled code,
you may find it handy to use the {\tt )dir} option on the
{\tt )library} command.
This causes {\tt )library} to process all compiled code in the
specified directory. For example,
\begin{verbatim}
)library )dir /u/jones/as/quantum
\end{verbatim}
You must give an explicit directory after {\tt )dir}, even if you
want all compiled code in the current working directory
processed, e.g.
\begin{verbatim}
)library )dir .
\end{verbatim}
The {\tt )compile} command works with several file extensions. We saw
above what happens when it is invoked on a file with extension {\tt
.as.} A {\tt .ao} file is a portable binary compiled version of a
{\tt .as} file, and {\tt )compile} simply passes the {\tt .ao} file
onto Aldor. The generated Lisp file is compiled and {\tt )library}
is automatically called, just as if you had specified a {\tt .as} file.
A {\tt .al} file is an archive file containing {\tt .ao} files. The
archive is created (on Unix systems) with the {\tt ar} program. When
{\tt )compile} is given a {\tt .al} file, it creates a directory whose
name is based on that of the archive. For example, if you issue
\begin{verbatim}
)compile mylib.al
\end{verbatim}
the directory {\tt mylib.axldir} is created. All
members of the archive are unarchived into the
directory and {\tt )compile} is called on each {\tt .ao} file found. It
is your responsibility to remove the directory and its contents, if you
choose to do so.
A {\tt .lsp} file is a Lisp source file, presumably, in our context,
generated by Aldor when called with the {\tt Flsp} option. When
{\tt )compile} is used with a {\tt .lsp} file, the Lisp file is
compiled and {\tt )library} is called. You must also have present a
{\tt .asy} generated from the same source file.
The following are descriptions of options for the old system compiler.
You can compile category, domain, and package constructors
contained in files with file extension {\it .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 {\bf matrix.spad.}
If you do not specify a {\it directory,} the working current
directory (see
\ref{ugSysCmdcd} on page~\pageref{ugSysCmdcd})
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.
\index{abbreviation}
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 {\bf .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 default is {\tt )library.}
Note that the semantics of {\tt )library} and {\tt )nolibrary}
for the new Aldor compiler and for the old system compiler are
completely different.
The {\tt )vartrace} option causes the compiler to generate
extra code for the constructor to support conditional tracing of
variable assignments. (see
\ref{ugSysCmdtrace} on page~\pageref{ugSysCmdtrace}). Without
this option, this code is suppressed and one cannot use
the {\tt )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 old system 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.
%% BEGIN OBSOLTE
% It is important for you to realize that it does not suffice to compile a
% constructor to use the new code in the interpreter.
% After compilation, the {\tt )load} command with the
% {\tt )update} option should be used to bring in the new code
% and update internal system tables with information about the
% constructor.
%% END OBSOLTE
\par\noindent{\bf Also See:}
{\tt )abbreviation} \index{ugSysCmdabbreviation},
{\tt )edit} \index{ugSysCmdedit}, and
{\tt )library} \index{ugSysCmdlibrary}.
\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 userdefined 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
\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:}
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}
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.
\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
(\ref{ugSysCmdframe} on page~\pageref{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 \ref{ugSysCmdcd} on page~\pageref{ugSysCmdcd}).
Note that these history database files are not text files (in fact,
they are directories themselves), and so are not in humanreadable
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}.
\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 \ref{ugSysCmdcd} on page~\pageref{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{)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.as} 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.
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{)load}
\index{ugSysCmdload}
\index{load}
\par\noindent{\bf User Level Required:} interpreter
%% BEGIN OBSOLETE
% \par\noindent{\bf Command Syntax:}
% \begin{list}{}
% \item{\tt )load {\it libName1 \lanb{}libName2 ...\ranb{}} \lanb{})update\ranb{}}
% \item{\tt )load {\it libName1 \lanb{}libName2 ...\ranb{}} )cond \lanb{})update\ranb{}}
% \item{\tt )load {\it libName1 \lanb{}libName2 ...\ranb{}} )query}
% \item{\tt )load {\it libName1 \lanb{}libName2 ...\ranb{}} )noexpose}
% \end{list}
%% END OBSOLETE
\par\noindent{\bf Command Description:}
This command is obsolete. Use {\tt )library} instead.
%% BEGIN OBSOLETE
% The {\tt )load} command is used to bring in the compiled library code
% for constructors and update internal system tables with information
% about the constructors.
% This command is usually only used by Axiom library developers.
%
% The abbreviation of a constructor serves as part of the name of the
% directory in which the compiled code is stored (see
% \ref{ugSysCmdabbreviation} for a discussion of defining and querying
% abbreviations).
% The abbreviation is used in the {\tt )load} command.
% For example, to load the constructors {\tt Integer},
% {\tt NonNegativeInteger} and {\tt List} which have
% abbreviations {\tt INT}, {\tt NNI} and {\tt LIST},
% respectively, issue the command
% \begin{verbatim}
% )load INT NNI LIST
% \end{verbatim}
% To load constructors only if they have not already been
% loaded (that is., load {\it conditionally}), use the {\tt )cond}
% option:
% \begin{verbatim}
% )load INT NNI LIST )cond
% \end{verbatim}
% To query whether particular constructors have been loaded, use the
% {\tt )query} option:
% \begin{verbatim}
% )load I NNI L )query
% \end{verbatim}
% When constructors are loaded from Axiom system directories, some
% checks and updates are not performed because it is assumed that the system
% knows about these constructors.
% To force these checks and updates to occur, add the {\tt )update}
% option to the command:
% \begin{verbatim}
% )load INT NNI LIST )update
% )load INT NNI LIST )cond )update
% \end{verbatim}
% The only time it is really necessary to use the {\tt )load} command is
% when a new constructor has been compiled or an existing constructor has
% been modified and then compiled.
% If an {\tt )abbreviate} command has been issued for a constructor, it
% will be automatically loaded when needed.
% In particular, any constructor that comes with the Axiom system
% will be automatically loaded.
%
% If you write several interdependent constructors it is important that
% they all get loaded when needed.
% To accomplish this, either load them manually or issue
% {\tt )abbreviate} commands for each of the constructors so that they
% will be automatically loaded when needed.
%
% Constructors are automatically exposed in the frame in which you load
% them unless you use the {\tt )noexpose} option.
% \begin{verbatim}
% )load MATCAT )noexpose
% \end{verbatim}
% See \ref{ugTypesExpose}
% for more information about constructor exposure.
%
% \par\noindent{\bf Also See:}
% {\tt )abbreviation} \index{ugSysCmdabbreviation} and
% {\tt )compile} \index{ugSysCmdcompile}.
%% END OBSOLETE
\section{)trace}
\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{)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}.
\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 \ref{ugInOutIn} on page~\pageref{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}.
\section{)set}
\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 commanddriven with a menu display.
It is treestructured.
To see all toplevel 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.
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{)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}
\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}.
\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 Sexpression}
\item{\tt )before} {\it Sexpression}
\item{\tt )break after}
\item{\tt )break before}
\item{\tt )cond} {\it Sexpression}
\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.
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 sexpressions correctly,
%!! I recommand not documenting )after )before and )cond
\begin{description}
%\item[{\tt )after} {\it Sexpression}]
%causes the given Common Lisp {\it Sexpression} to be
%executed after exiting the traced function.
%\item[{\tt )before} {\it Sexpression}]
%causes the given Common Lisp {\it Sexpression} 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 Sexpression}]
%causes trace information to be shown only if the given
%Common Lisp {\it Sexpression} evaluates to nonNIL. 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 nonNIL.
%\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 nth 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 twodimensional 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.
\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 \ref{ugSysCmdcompile} on
page~\pageref{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 \ref{ugSysCmdcompile} on
page~\pageref{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}.
\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 nth
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}
\index{what}
\par\noindent{\bf User Level Required:} interpreter
\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 
userdefined 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
userlevel.
\index{what commands}
Your userlevel
\index{userlevel}
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 recreated 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}.
\chapter{THINGS TO BE INTEGRATED}
\section{email 1}
\begin{verbatim}
There is something called the "addchain formed by domain
extensions" which is described in the Glossary of the Axiom
book:
"addchain
a hierarchy formed by domain extensions. If domain A extends
domain B and domain B extends domain C, then A has addchain
BC."
and
"domain extension
a domain constructor A is said to extend a domain constructor B
if A's definition has the form A == Badd.... This intuitively
means "functions not defined by A are assumed to come from B."
Successive domain extensions form addchains affecting the
search order for functions not implemented directly by the
domain during dynamic lookup.
"dynamic lookup
In Axiom, a domain may or may not explicitly provide function
definitions for all its exported operations. These definitions
may instead come from domains in the addchain or from default
packages. When a function call is made for an operation in the
domain, up to five steps are carried out.
1. If the domain itself implements a function for the operation,
that function is returned.
2. Each of the domains in the addchain are searched; if one
of these domains implements the function, that function is
returned.
3. Each of the default packages for the domain are searched in
order of the lineage. If any of the default packages implements
the function, the first one found is returned.
4. Each of the default packages for each of the domains in the
addchain are searched in the order of their lineage. If any
of the default packages implements the function, the first
one found is returned.
5. If all of the above steps fail, an error message is reported.

\end{verbatim}
\end{document}