path: root/src/hyper/pages/ug15.ht

% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved.
% !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk.

\texht{\setcounter{chapter}{14}}{} % Chapter 15 

%
\newcommand{\ugWhatsNewTitle}{What's New in \Language{} Version 2.0}
\newcommand{\ugWhatsNewNumber}{15.}
%
% =====================================================================
\begin{page}{ugWhatsNewPage}{15. What's New in \Language{} Version 2.0}
% =====================================================================
\beginscroll

Many things have changed in this new version of \Language{} and
we describe many of the more important topics here.

%------------------------------------------------------------------------
\beginmenu
    \menudownlink{{15.1. Important Things to Read First}}{ugWhatsNewImportantPage}
    \menudownlink{{15.2. The New \Language{} Library Compiler}}{ugWhatsNewAsharpPage}
    \menudownlink{{15.3. The NAG Library Link}}{nagLinkIntroPage}
    \menudownlink{{15.4. Interactive Front-end and Language}}{ugWhatsNewLanguagePage}
    \menudownlink{{15.5. Library}}{ugWhatsNewLibraryPage}
    \menudownlink{{15.6. \HyperName}}{ugWhatsNewHyperDocPage}
    \menudownlink{{15.7. Documentation}}{ugWhatsNewDocumentationPage}
\endmenu
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugWhatsNewImportantTitle}{Important Things to Read First}
\newcommand{\ugWhatsNewImportantNumber}{15.1.}
%
% =====================================================================
\begin{page}{ugWhatsNewImportantPage}{15.1. Important Things to Read First}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------

If you have any private {\tt .spad} files (that is, library files
which were not shipped with \Language{}) you will need to
recompile them.  For example, if you wrote the file {\tt
regress.spad} then you should issue {\tt )compile regress.spad}
before trying to use it.

The internal representation of \axiomType{Union}  has changed. 
This means that \texht{\linebreak}{} \Language{} data saved 
with Release 1.x may not
be readable by this Release. If you cannot recreate the saved data      
by recomputing in Release 2.0, please contact NAG for assistance.       

%------------------------------------------------------------------------
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugWhatsNewAsharpTitle}{The New \Language{} Library Compiler}
\newcommand{\ugWhatsNewAsharpNumber}{15.2.}
%
% =====================================================================
\begin{page}{ugWhatsNewAsharpPage}{15.2. The New \Language{} Library Compiler}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------

A new compiler is now available for \Language{}.
The programming language is referred to as the \Language{} Extension Language
(or \axiomxl{} for short), and
improves upon the old \Language{} language in many ways.
The \spadcmd{)compile} command has been upgraded to be able to
invoke the new or old compilers.
The language and the compiler are described in the hard-copy
documentation which came with your \Language{} system.

To ease the chore of upgrading your {\it .spad} files (old
compiler) to {\it .as} files (new compiler), the
\spadcmd{)compile} command has been given a {\tt )translate}
option. This invokes a special version of the old compiler which
parses and analyzes your old code and produces augmented code
using the new syntax.
Please be aware that the translation is not necessarily one
hundred percent complete or correct.
You should attempt to compile the output with the \axiomxl{} compiler
and make any necessary corrections.


\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\nagLinkIntroTitle}{The NAG Library Link}
\newcommand{\nagLinkIntroNumber}{15.3.}
%
% =====================================================================
\begin{page}{nagLinkIntroPage}{15.3. The NAG Library Link}
% =====================================================================
\beginscroll

The \naglib{} link allows you to call NAG Fortran
routines from within \Language{}, passing \Language{} objects as parameters
and getting them back as results.

The \naglib{} and, consequently, the link are divided into {\em chapters},
which cover different areas of numerical analysis.  The statistical
and sorting {\em chapters} of the Library, however, are not included in the
link and various support and utility routines (mainly the F06 and X
{\em chapters}) have been omitted.

Each {\em chapter} has a short (at most three-letter) name;
for example, the {\em chapter} devoted to the
solution of ordinary differential equations is called D02.  When
using the link via the \downlink{\HyperName{} interface}{htxl1},
you will be presented with a complete menu of these {\em chapters}. The
names of individual routines within each {\em chapter} are formed by
adding three letters to the {\em chapter} name, so for example the routine
for solving ODEs by Adams method is called
\axiomFunFrom{d02cjf}{NagOrdinaryDifferentialEquationsPackage}.

\beginmenu
    \menudownlink{{15.3.1. Interpreting NAG Documentation}}{nagDocumentationPage}
    \menudownlink{{15.3.2. Using the Link}}{nagLinkUsagePage}
    \menudownlink{{15.3.3. Providing values for Argument Subprograms}}{aspSectionPage}
    \menudownlink{{15.3.4. General Fortran-generation utilities in \Language{}}}{generalFortranPage}
    \menudownlink{{15.3.5. Some technical information}}{nagTechnicalPage}
\endmenu
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\nagDocumentationTitle}{Interpreting NAG Documentation}
\newcommand{\nagDocumentationNumber}{15.3.1.}
%
% =====================================================================
\begin{page}{nagDocumentationPage}{15.3.1. Interpreting NAG Documentation}
% =====================================================================
\beginscroll

Information about using the \naglib{} in general, and about using
individual routines in particular, can be accessed via \HyperName{}.
This documentation refers to the Fortran routines directly; the
purpose of this subsection is to explain how this corresponds to the
\Language{} routines.

For general information about the \naglib{} users should consult
\downlink{Essential Introduction to the NAG Foundation Library}{manpageXXintro}.
The documentation is in ASCII format, and a description of the conventions
used to represent mathematical symbols is given in
\downlink{Introduction to NAG On-Line Documentation}{manpageXXonline}.
Advice about choosing a routine from a particular {\em chapter} can be found in
the \downlink{Chapter Documents}{FoundationLibraryDocPage}.

\subsubsection{Correspondence Between Fortran and \Language{} types}

The NAG documentation refers to the Fortran types of objects; in
general, the correspondence to \Language{} types is as follows.
\indent{4}
\beginitems
\item[-] Fortran INTEGER corresponds to \Language{} \axiomType{Integer}.
\item[-] Fortran DOUBLE PRECISION corresponds to \Language{} \axiomType{DoubleFloat}.
\item[-] Fortran COMPLEX corresponds to \Language{} \axiomType{Complex DoubleFloat}.
\item[-] Fortran LOGICAL corresponds to \Language{} \axiomType{Boolean}.
\item[-] Fortran CHARACTER*(*) corresponds to \Language{} \axiomType{String}.
\enditems
\indent{0}
(Exceptionally, for NAG EXTERNAL parameters -- ASPs in link parlance
-- REAL and COMPLEX correspond to \axiomType{MachineFloat} and \axiomType{MachineComplex},
respectively; see \downlink{``\aspSectionTitle''}{aspSectionPage} in Section \aspSectionNumber\ignore{aspSection}.)

The correspondence for aggregates is as follows.
\indent{4}
\beginitems
\item[-] A one-dimensional Fortran array corresponds to an \Language{} \texht{\linebreak}{}
      \axiomType{Matrix} with one column.
\item[-] A two-dimensional Fortran ARRAY corresponds to an \Language{} \texht{\linebreak}{}
      \axiomType{Matrix}.
\item[-] A three-dimensional Fortran ARRAY corresponds to an \Language{} \texht{\linebreak}{}
      \axiomType{ThreeDimensionalMatrix}.
\enditems
\indent{0}
Higher-dimensional arrays are not currently needed for the \naglib{}.

Arguments which are Fortran FUNCTIONs or SUBROUTINEs correspond
to special ASP domains in \Language{}. See \downlink{``\aspSectionTitle''}{aspSectionPage} in Section \aspSectionNumber\ignore{aspSection}.

\subsubsection{Classification of NAG parameters}

NAG parameters are classified as belonging to one (or more)
of the following categories: {\tt Input}, {\tt Output}, {\tt Workspace} or {\tt External} procedure.
Within {\tt External} procedures a similar classification is used, and parameters
may also be {\tt Dummies}, or {\tt User Workspace} (data structures not used by the
NAG routine but provided for the convenience of the user).

When calling a NAG routine via the link the user only provides values
for {\tt Input} and {\tt External} parameters.

The order of the parameters is, in general, different from  the order
specified in the \naglib{} documentation. The Browser description
for each routine helps in determining the correspondence. As a rule of
thumb, {\tt Input} parameters come first followed by {\tt Input/Output}
parameters. The {\tt External} parameters are always found at the end.


\subsubsection{IFAIL}

NAG routines often return diagnostic information through a parameter called
\axiom{ifail}.  With a few exceptions, the principle is that on input
\axiom{ifail} takes
one of the values $-1,0,1$.  This determines how the routine behaves when
it encounters an error:
\indent{4}
\beginitems
\item[-] a value of 1 causes the NAG routine to return without printing an error
message;
\item[-] a value of 0 causes the NAG routine to print an error message and abort;
\item[-] a value of -1 causes the NAG routine to return and print an error message.
\enditems
\indent{0}

The user is STRONGLY ADVISED to set \axiom{ifail} to \texht{$-1$}{-1} when using the link.
If \axiom{ifail} has been set to \texht{$1$}{1} or \texht{$-1$}{-1} on input, then its value on output
will determine the possible cause of any error.  A value of \texht{$0$}{0} indicates
successful completion, otherwise it provides an index into a table of
diagnostics provided as part of the routine documentation (accessible via
\Browse{}).

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\nagLinkUsageTitle}{Using the Link}
\newcommand{\nagLinkUsageNumber}{15.3.2.}
%
% =====================================================================
\begin{page}{nagLinkUsagePage}{15.3.2. Using the Link}
% =====================================================================
\beginscroll

The easiest way to use the link is via the
\downlink{\HyperName{} interface}{htxl1}.
You will be presented with a set of fill-in forms where
you can specify the parameters for each call.  Initially, the forms
contain example values, demonstrating the use of each routine (these,
in fact, correspond to the standard NAG example program for the
routine in question).  For some parameters, these values can provide
reasonable defaults; others, of course, represent data.  When you
change a parameter which controls the size of an array, the data in
that array are reset to a ``neutral'' value -- usually zero.

When you are satisfied with the values entered, clicking on the
``Continue'' button will display the \Language{} command needed to
run the chosen NAG routine with these values.  Clicking on the
``Do It'' button will then cause \Language{} to execute this command
and return the result in the parent \Language{} session, as described
below.  Note that, for some routines, multiple HyperDoc ``pages'' are
required, due to the structure of the data.  For these, returning to
an earlier page causes HyperDoc to reset the later pages (this is a
general feature of HyperDoc); in such a case, the simplest way to
repeat a call, varying a parameter on an earlier page, is probably to
modify the call displayed in the parent session.

An alternative approach is to call NAG routines directly in your
normal \Language{} session (that is, using the \Language{}
interpreter).  Such calls return an
object of type \axiomType{Result}.  As not
all parameters in the underlying NAG routine are required in the
AXIOM call (and the parameter ordering may be different), before
calling a NAG routine you should consult the description of the
\Language{} operation in the Browser.  (The quickest route to this
is to type the routine name, in lower case, into the Browser's
input area, then click on {\tt Operations}.)  The parameter names
used coincide with NAG's, although they will appear here in lower
case.  Of course, it is also possible to become familiar with the
\Language{} form of a routine by first using it through the
\downlink{\HyperName{} interface}{htxl1}.

\xtc{
As an example of this mode of working, we can find a zero
of a function, lying between 3 and 4, as follows:
}{
\spadpaste{answer:=c05adf(3.0,4.0,1.0e-5,0.0,-1,sin(X)::ASP1(F))\bound{answer} }
}
\xtc{
By default, \axiomType{Result} only displays the type of returned values,
since the amount of information returned can be quite large.  Individual
components can be examined as follows:
}{
\spadpaste{answer . x\free{answer}}
}
\xtc{
}{
\spadpaste{answer . ifail\free{answer}}
}
\xtc{
In order to avoid conflict with names defined in the workspace, you can also
get the values by using the \axiomType{String} type (the interpreter automatically
coerces them to \axiomType{Symbol})
}{
\spadpaste{answer "x"\free{answer}}
}


It is possible to have \Language{} display the values of scalar or array
results automatically.  For more details, see the commands  
\axiomFunFrom{showScalarValues}{Result}
and \axiomFunFrom{showArrayValues}{Result}.

\xtc{
There is also a {\bf .input} file for each NAG routine, containing
\Language{} interpreter commands to set up and run the standard NAG
example for that routine.
}{
\spadpaste{)read c05adf.input}
}

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\aspSectionTitle}{Providing values for Argument Subprograms}
\newcommand{\aspSectionNumber}{15.3.3.}
%
% =====================================================================
\begin{page}{aspSectionPage}{15.3.3. Providing values for Argument Subprograms}
% =====================================================================
\beginscroll

There are a number of ways in which users can provide values for argument
subprograms (ASPs).  At the top level the user will see that NAG routines
require
an object from the \axiomType{Union} of a \axiomType{Filename} and an ASP.
\xtc{
For example \axiomFun{c05adf} requires an object of type \texht{\linebreak}{}
\axiomType{Union}(fn: \axiomType{FileName},fp: \axiomType{Asp1 F})
}{
\spadpaste{)display operation c05adf}
}

The user thus has a choice of providing the name of a file containing
Fortran source code, or of somehow generating the ASP within \Language{}.
If a filename is specified, it is searched for in the {\it local} 
machine, i.e., the machine that \Language{} is running on.

\subsubsection{Providing ASPs via \axiomType{FortranExpression}}

The \axiomType{FortranExpression} domain is used to represent expressions
which can be translated into Fortran under certain circumstances.    It is
very similar to \axiomType{Expression} except that only operators which exist
in Fortran can be used, and only certain variables can occur.
For
example the instantiation \axiomType{FortranExpression([X],[M],MachineFloat)}
is the domain of expressions containing the scalar \axiom{X} and the array
\axiom{M}.
\xtc{
This allows us to create expressions like:
}{
\spadpaste{f : FortranExpression([X],[M],MachineFloat) := sin(X)+M[3,1]}
}
\xtc{
but not
}{
\spadpaste{f : FortranExpression([X],[M],MachineFloat) := sin(M)+Y}
}

Those ASPs which represent expressions usually export a \axiomFun{coerce} from
an appropriate instantiation of \axiomType{FortranExpression} (or perhaps
\axiomType{Vector FortranExpression} etc.).  For convenience there are also
retractions from appropriate instantiations of \axiomType{Expression},
\axiomType{Polynomial} and \axiomType{Fraction Polynomial}.

\subsubsection{Providing ASPs via \axiomType{FortranCode}}

\texht{\exptypeindex{FortranCode}}{}
\axiomType{FortranCode} allows us to build arbitrarily complex ASPs via a
kind of pseudo-code.  It is described fully in
\downlink{``\generalFortranTitle''}{generalFortranPage} in Section \generalFortranNumber\ignore{generalFortran}.

Every ASP exports two \axiomFun{coerce} functions: one from
\axiomType{FortranCode} and one from \axiomType{List FortranCode}.  There
is also a \axiomFun{coerce} from \texht{\linebreak}{}
\axiomType{Record( localSymbols: SymbolTable, code: List FortranCode)}
which is used for passing extra symbol information about the ASP.

\xtc{
So for example, to integrate the function abs(x) we could use the built-in
\axiomFun{abs} function.  But suppose we want to get back to basics and define
it directly, then we could do the following:
}{
\spadpaste{d01ajf(-1.0, 1.0, 0.0, 1.0e-5, 800, 200, -1, cond(LT(X,0), assign(F,-X), assign(F,X))) result }
}
The \axiomFunFrom{cond}{FortranCode} operation creates a conditional clause
and the \axiomFunFrom{assign}{FortranCode} an assignment statement.

\subsubsection{Providing ASPs via \axiomType{FileName}}

Suppose we have created the file ``asp.f'' as follows:
\begin{verbatim}
      DOUBLE PRECISION FUNCTION F(X)
      DOUBLE PRECISION X
      F=4.0D0/(X*X+1.0D0)
      RETURN
      END
\end{verbatim}
and wish to pass it to the NAG
routine \axiomFun{d01ajf} which performs one-dimensional quadrature.
We can do this as follows:
\begin{verbatim}
d01ajf(0.0 ,1.0, 0.0, 1.0e-5, 800, 200, -1, "asp.f")
\end{verbatim}

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\generalFortranTitle}{General Fortran-generation utilities in \Language{}}
\newcommand{\generalFortranNumber}{15.3.4.}
%
% =====================================================================
\begin{page}{generalFortranPage}{15.3.4. General Fortran-generation utilities in \Language{}}
% =====================================================================
\beginscroll

This section describes more advanced facilities which are available to users
who wish to generate Fortran code from within \Language{}.  There are
facilities to manipulate templates, store type information, and generate
code fragments or complete programs.

\subsubsection{Template Manipulation}

A template is a skeletal program which is ``fleshed out'' with data when
it is processed.  It is a sequence of {\em active} and {\em passive} parts:
active parts are sequences of \Language{} commands which are processed as if they
had been typed into the interpreter; passive parts are simply echoed
verbatim on the Fortran output stream.

Suppose, for example, that we have the following template, stored in
the file ``test.tem'':
\begin{verbatim}
-- A simple template
beginVerbatim
      DOUBLE PRECISION FUNCTION F(X)
      DOUBLE PRECISION X
endVerbatim
outputAsFortran("F",f)
beginVerbatim
      RETURN
      END
endVerbatim
\end{verbatim}
The passive parts lie between the two
tokens {\tt beginVerbatim} and \texht{\linebreak}{} {\tt endVerbatim}.  There
are two active statements: one which is simply an \Language{} (
\texht{\verb+--+}{\-\-})
comment, and one which produces an assignment to the current value
of {\tt f}.  We could use it as follows:
\begin{verbatim}
(4) ->f := 4.0/(1+X**2)

           4
   (4)   ------
          2
         X  + 1
                       
(5) ->processTemplate "test.tem"
      DOUBLE PRECISION FUNCTION F(X)
      DOUBLE PRECISION X
      F=4.0D0/(X*X+1.0D0)
      RETURN 
      END

   (5)  "CONSOLE"
\end{verbatim}

(A more reliable method of specifying the filename will be introduced
below.)  Note that the Fortran assignment {\tt F=4.0D0/(X*X+1.0D0)}
automatically converted 4.0 and 1 into DOUBLE PRECISION numbers; in
general, the \Language{} Fortran generation facility will convert
anything which should be a floating point object into either
a Fortran REAL or DOUBLE PRECISION object.
\xtc{
Which alternative is used is determined by the command
}{
\spadpaste{)set fortran precision}
}

It is sometimes useful to end a template before the file itself ends (e.g. to
allow the template to be tested incrementally or so that a piece of text
describing how the template works can be included).  It is of course possible
to ``comment-out'' the remainder of the file.  Alternatively, the single token
{\tt endInput} as part of an active portion of the template will cause
processing to be ended prematurely at that point.

The \axiomFun{processTemplate} command comes in two flavours.  In the first case,
illustrated above, it takes one argument of domain \axiomType{FileName},
the name of the template to be processed, and writes its output on the
current Fortran output stream.  In general, a filename can be generated
from {\em directory}, {\em name} and {\em extension} components, using
the operation \axiomFun{filename}, as in
\begin{verbatim}
processTemplate filename("","test","tem")
\end{verbatim}
There is an alternative version of \axiomFun{processTemplate}, which
takes two arguments (both of domain \axiomType{FileName}).  In this case the
first argument is the name of the template to be processed, and the
second is the file in which to write the results.  Both versions return
the location of the generated Fortran code as their result
({\tt "CONSOLE"} in the above example).

It is sometimes useful to be able to mix active and passive parts of a
line or statement.  For example you might want to generate a Fortran
Comment describing your data set.  For this kind of application we
provide three functions as follows:
\texht
{
\begin{tabular}{p{1.8in}p{2.6in}}
\axiomFun{fortranLiteral} & writes a string on the Fortran output stream \\
 & \\
\axiomFun{fortranCarriageReturn} & writes a carriage return on the Fortran output stream \\
& \\
\axiomFun{fortranLiteralLine} & writes a string followed by a return
on the Fortran output stream \\
\end{tabular}
}
{
\newline
\axiomFun{fortranLiteral}\tab{25}writes a string on the Fortran output stream\newline
\axiomFun{fortranCarriageReturn}\tab{25}writes a carriage return on the Fortran output stream\newline
\axiomFun{fortranLiteralLine}\tab{25}writes a string followed by a return on the Fortran output stream\newline
}
\xtc{
So we could create our comment as follows:
}{
\spadpaste{m := matrix [[1,2,3],[4,5,6]]\bound{m}}
}
\xtc{
}{
\spadpaste{fortranLiteralLine concat ["C\ \ \ \ \ \ The\ Matrix\ has\ ", nrows(m)::String, "\ rows\ and\ ", ncols(m)::String, "\ columns"]\free{m}}
}
\xtc{
or, alternatively:
}{
\spadpaste{fortranLiteral "C\ \ \ \ \ \ The\ Matrix\ has\ "}
}
\xtc{
}{
\spadpaste{fortranLiteral(nrows(m)::String)}
}
\xtc{
}{
\spadpaste{fortranLiteral "\ rows\ and\ "}
}
\xtc{
}{
\spadpaste{fortranLiteral(ncols(m)::String)\free{m}}
}
\xtc{
}{
\spadpaste{fortranLiteral "\ columns"}
}
\xtc{
}{
\spadpaste{fortranCarriageReturn()}
}

We should stress that these functions, together with the \axiomFun{outputAsFortran}
function are the {\em only} sure ways
of getting output to appear on the Fortran output stream.  Attempts to use
\Language{} commands such as \axiomFun{output} or \axiomFunX{writeline} may appear to give
the required result when displayed on the console, but will give the wrong
result when Fortran and algebraic output are sent to differing locations.  On
the other hand, these functions can be used to send helpful messages to the
user, without interfering with the generated Fortran.

\subsubsection{Manipulating the Fortran Output Stream}
\texht{\exptypeindex{FortranOutputStackPackage}}{}

Sometimes it is useful to manipulate the Fortran output stream in a program,
possibly without being aware of its current value.  The main use of this is
for gathering type declarations (see ``Fortran Types'' below) but it can be useful
in other contexts as well.  Thus we provide a set of commands to manipulate
a stack of (open) output streams.  Only one stream can be written to at
any given time.  The stack is never empty---its initial value is the
console or the current value of the Fortran output stream, and can be
determined using
\xtc{
}{
\spadpaste{topFortranOutputStack()}
}
(see below).
The commands available to manipulate the stack are:
\texht{
\begin{tabular}{ll}
\axiomFun{clearFortranOutputStack} & resets the stack to the console \\
 & \\
\axiomFun{pushFortranOutputStack} & pushes a \axiomType{FileName} onto the stack \\
 & \\
\axiomFun{popFortranOutputStack} & pops the stack \\
 & \\
\axiomFun{showFortranOutputStack} & returns the current stack \\
 & \\
\axiomFun{topFortranOutputStack} & returns the top element of the stack \\
\end{tabular}
}
{
\newline
\axiomFun{clearFortranOutputStack}\tab{25}resets the stack\newline
\axiomFun{pushFortranOutputStack}\tab{25}pushes a \axiomType{FileName} onto the stack\newline
\axiomFun{popFortranOutputStack}\tab{25}pops the stack\newline
\axiomFun{showFortranOutputStack}\tab{25}returns the current stack\newline
\axiomFun{topFortranOutputStack}\tab{25}returns the top element of the stack\newline
}
These commands are all part of \axiomType{FortranOutputStackPackage}.

\subsubsection{Fortran Types}

When generating code it is important to keep track of the Fortran types of
the objects which we are generating.  This is useful for a number of reasons,
not least to ensure that we are actually generating legal Fortran code.  The
current type system is built up in several layers, and we shall describe each
in turn.

\subsubsection{FortranScalarType}
\texht{\exptypeindex{FortranScalarType}}{}

This domain represents the simple Fortran datatypes: REAL, DOUBLE PRECISION,
COMPLEX, LOGICAL, INTEGER, and CHARACTER.
It is possible to \axiomFun{coerce} a \axiomType{String} or \axiomType{Symbol}
into the domain, test whether two objects are equal, and also apply
the predicate functions \axiomFunFrom{real?}{FortranScalarType} etc.

\subsubsection{FortranType}
\texht{\exptypeindex{FortranType}}{}

This domain represents ``full'' types: i.e., datatype plus array dimensions
(where appropriate) plus whether or not the parameter is an external
subprogram.  It is possible to \axiomFun{coerce} an object of
\axiomType{FortranScalarType} into the domain or \axiomFun{construct} one
from an element of \axiomType{FortranScalarType}, a list of
\axiomType{Polynomial Integer}s (which can of course be simple integers or
symbols) representing its dimensions, and
a \axiomType{Boolean} declaring whether it is external or not.  The list
of dimensions must be empty if the \axiomType{Boolean} is {\tt true}.
The functions \axiomFun{scalarTypeOf}, \axiomFun{dimensionsOf} and
\axiomFun{external?} return the appropriate
parts, and it is possible to get the various basic Fortran Types via
functions like \axiomFun{fortranReal}.
\xtc{
For example:
}{
\spadpaste{type:=construct(real,[i,10],false)$FortranType}
}
\xtc{
or
}{
\spadpaste{type:=[real,[i,10],false]$FortranType\bound{type}}
}
\xtc{
}{
\spadpaste{scalarTypeOf type\free{type}}
}
\xtc{
}{
\spadpaste{dimensionsOf type\free{type}}
}
\xtc{
}{
\spadpaste{external?  type\free{type}}
}
\xtc{
}{
\spadpaste{fortranLogical()}
}
\xtc{
}{
\spadpaste{construct(integer,[],true)$FortranType}
}

\subsubsection{SymbolTable}
\texht{\exptypeindex{SymbolTable}}{}

This domain creates and manipulates a symbol table for generated Fortran code.
This is used by \axiomType{FortranProgram} to represent the types of objects in
a subprogram.  The commands available are:
\texht{
\begin{tabular}{ll}
\axiomFun{empty} & creates a new \axiomType{SymbolTable} \\
 & \\
\axiomFunX{declare} & creates a new entry in a table \\
 & \\
\axiomFun{fortranTypeOf} & returns the type of an object in a table \\
 & \\
\axiomFun{parametersOf} & returns a list of all the symbols in the table \\
 & \\
\axiomFun{typeList} & returns a list of all objects of a given type \\
 & \\
\axiomFun{typeLists} & returns a list of lists of all objects sorted by type \\
 & \\
\axiomFun{externalList} & returns a list of all {\tt EXTERNAL} objects \\
 & \\
\axiomFun{printTypes} & produces Fortran type declarations from a table\\
\end{tabular}
}
{
\newline
\axiomFun{empty}\tab{25}creates a new \axiomType{SymbolTable}\newline
\axiomFunX{declare}\tab{25}creates a new entry in a table \newline
\axiomFun{fortranTypeOf}\tab{25}returns the type of an object in a table \newline
\axiomFun{parametersOf}\tab{25}returns a list of all the symbols in the table \newline
\axiomFun{typeList}\tab{25}returns a list of all objects of a given type \newline
\axiomFun{typeLists}\tab{25}returns a list of lists of all objects sorted by type \newline
\axiomFun{externalList}\tab{25}returns a list of all {\tt EXTERNAL} objects \newline
\axiomFun{printTypes}\tab{25}produces Fortran type declarations from a table\newline
}
\xtc{
}{
\spadpaste{symbols := empty()$SymbolTable\bound{symbols}}
}
\xtc{
}{
\spadpaste{declare!(X,fortranReal(),symbols)\free{symbols}}
}
\xtc{
}{
\spadpaste{declare!(M,construct(real,[i,j],false)$FortranType,symbols)\free{symbols}}
}
\xtc{
}{
\spadpaste{declare!([i,j],fortranInteger(),symbols)\free{symbols}}
}
\xtc{
}{
\spadpaste{symbols\free{symbols}}
}
\xtc{
}{
\spadpaste{fortranTypeOf(i,symbols)\free{symbols}}
}
\xtc{
}{
\spadpaste{typeList(real,symbols)\free{symbols}}
}
\xtc{
}{
\spadpaste{printTypes symbols\free{symbols}}
}

\subsubsection{TheSymbolTable}
\texht{\exptypeindex{TheSymbolTable}}{}

This domain creates and manipulates one global symbol table to be used, for
example, during template processing. It is
also used when
linking to external Fortran routines. The
information stored for each subprogram (and the main program segment, where
relevant) is:
\indent{4}
\beginitems
\item[-] its name;
\item[-] its return type;
\item[-] its argument list;
\item[-] and its argument types.
\enditems
\indent{0}
Initially, any information provided is deemed to be for the main program
segment.
\xtc{
Issuing the following command indicates that from now on all information
refers to the subprogram \axiom{F}.
}{
\spadpaste{newSubProgram F}
}
\xtc{
It is possible to return to processing the main program segment by issuing
the command:
}{
\spadpaste{endSubProgram()}
}
The following commands exist:
\texht{
\begin{tabular}{p{1.6in}p{2.8in}}
\axiomFunX{returnType} & declares the return type of the current subprogram \\
 & \\
\axiomFun{returnTypeOf} & returns the return type of a subprogram \\
 & \\
\axiomFunX{argumentList} &  declares the argument list of the current subprogram \\
 & \\
\axiomFun{argumentListOf} &  returns the argument list of a subprogram \\
 & \\
\axiomFunX{declare} & provides type declarations for parameters of the current subprogram \\
 & \\
\axiomFun{symbolTableOf} & returns the symbol table  of a subprogram \\
 & \\
\axiomFun{printHeader} & produces the Fortran header for the current subprogram \\
\end{tabular}
}
{
\newline
\axiomFunX{returnType}\tab{25}declares the return type of the current subprogram \newline
\axiomFun{returnTypeOf}\tab{25}returns the return type of a subprogram \newline
\axiomFunX{argumentList}\tab{25}declares the argument list of the current subprogram \newline
\axiomFun{argumentListOf}\tab{25}returns the argument list of a subprogram \newline
\axiomFunX{declare}\tab{25}provides type declarations for parameters of the current subprogram \newline
\axiomFun{symbolTableOf}\tab{25}returns the symbol table  of a subprogram \newline
\axiomFun{printHeader}\tab{25}produce the Fortran header for the current subprogram \newline
}
In addition there are versions of these commands which are parameterised by
the name of a subprogram, and others parameterised by both the name of a
subprogram and by an instance of \axiomType{TheSymbolTable}.
\xtc{
}{
\spadpaste{newSubProgram F \bound{forPleasure}}
}
\xtc{
}{
\spadpaste{argumentList!(F,[X])\free{forPleasure}}
}
\xtc{
}{
\spadpaste{returnType!(F,real)\free{forPleasure}}
}
\xtc{
}{
\spadpaste{declare!(X,fortranReal(),F)\free{forPleasure}}
}
\xtc{
}{
\spadpaste{printHeader F\free{forPleasure}}
}

\subsubsection{Advanced Fortran Code Generation}

This section describes facilities for representing Fortran statements, and
building up complete subprograms from them.

\subsubsection{Switch}
\texht{\exptypeindex{Switch}}{}

This domain is used to represent statements like {\tt x < y}.  Although
these can be represented directly in \Language{}, it is a little cumbersome,
since \Language{} evaluates the last statement, for example, to \axiom{true}
(since \axiom{x} is  lexicographically less than \axiom{y}).

Instead we have a set of operations, such as \axiomFun{LT} to represent \axiom{<},
to let us build such statements.  The available constructors are:
\texht{
\centerline{{\begin{tabular}{ll}}}
\centerline{{\axiomFun{LT} & $<$ }}
\centerline{{\axiomFun{GT} & $>$ }}
\centerline{{\axiomFun{LE} & $\leq$ }}
\centerline{{\axiomFun{GE} & $\geq$ }}
\centerline{{\axiomFun{EQ} & $=$ }}
\centerline{{\axiomFun{AND} & $and$}}
\centerline{{\axiomFun{OR} & $or$ }}
\centerline{{\axiomFun{NOT} & $not$ }}
\centerline{{\end{tabular}}}
}
{
\newline
\axiomFun{LT}\tab{25}\texht{$<$}{<} \newline
\axiomFun{GT}\tab{25}\texht{$>$}{>} \newline
\axiomFun{LE}\tab{25}\texht{$\leq$}{<=} \newline
\axiomFun{GE}\tab{25}\texht{$\geq$}{>=} \newline
\axiomFun{EQ}\tab{25}\texht{$=$}{=} \newline
\axiomFun{AND}\tab{25}\texht{$and$}{{\tt and}}\newline
\axiomFun{OR}\tab{25}\texht{$or$}{{\tt or}} \newline
\axiomFun{NOT}\tab{25}\texht{$not$}{{\tt not}} \newline
}
\xtc{
So for example:
}{
\spadpaste{LT(x,y)}
}

\subsubsection{FortranCode}

This domain represents code segments or operations: currently assignments,
conditionals, blocks, comments, gotos, continues, various kinds of loops,
and return statements.
\xtc{
For example we can create quite a complicated conditional statement using
assignments, and then turn it into Fortran code:
}{
\spadpaste{c := cond(LT(X,Y),assign(F,X),cond(GT(Y,Z),assign(F,Y),assign(F,Z)))\bound{c}}
}
\xtc{
}{
\spadpaste{printCode c\free{c}}
}

The Fortran code is printed
on the current Fortran output stream.

\subsubsection{FortranProgram}
\texht{\exptypeindex{FortranProgram}}{}

This domain is used to construct complete Fortran subprograms out of
elements of \axiomType{FortranCode}.  It is parameterised by the name of the
target subprogram (a \axiomType{Symbol}), its return type (from
\axiomType{Union}(\axiomType{FortranScalarType},``void'')),
its arguments (from \axiomType{List Symbol}), and
its symbol table (from \axiomType{SymbolTable}).  One can
\axiomFun{coerce} elements of either \axiomType{FortranCode}
or \axiomType{Expression} into it.

\xtc{
First of all we create a symbol table:
}{
\spadpaste{symbols := empty()$SymbolTable\bound{symbols}}
}
\xtc{
Now put some type declarations into it:
}{
\spadpaste{declare!([X,Y],fortranReal(),symbols)\free{symbols}}
}
\xtc{
Then (for convenience)
we set up the particular instantiation of \axiomType{FortranProgram}
}{
\spadpaste{FP := FortranProgram(F,real,[X,Y],symbols)\free{symbols}\bound{FP}}
}
\xtc{
Create an object of type \axiomType{Expression(Integer)}:
}{
\spadpaste{asp := X*sin(Y)\bound{asp}}
}
\xtc{
Now \axiomFun{coerce} it into \axiomType{FP}, and print its Fortran form:
}{
\spadpaste{outputAsFortran(asp::FP)\free{FP asp}}
}

We can generate a \axiomType{FortranProgram} using \axiom{FortranCode}.  For
example:
\xtc{
Augment our symbol table:
}{
\spadpaste{declare!(Z,fortranReal(),symbols)\free{symbols}\bound{Z}}
}
\xtc{
and transform the conditional expression we prepared earlier:
}{
\spadpaste{outputAsFortran([c,returns()]::FP) \free{FP c Z}}
}

%------------------------------------------------------------------------
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\nagTechnicalTitle}{Some technical information}
\newcommand{\nagTechnicalNumber}{15.3.5.}
%
% =====================================================================
\begin{page}{nagTechnicalPage}{15.3.5. Some technical information}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------

The model adopted for the link is a server-client configuration
-- \Language{} acting as a client via a local agent
(a process called {\tt nagman}). The server side is implemented
by the {\tt nagd} daemon process which may run on a different host.
The {\tt nagman} local agent is started by default whenever you
start \Language{}. The {\tt nagd} server must be started separately.
Instructions for installing and running the server are supplied
in \texht{\downlink{``\nugNagdTitle''}{nugNagdPage} in Section \nugNagdNumber\ignore{nugNagd}}{printed form}. 
Use the \spadcmd{)set naglink host} system command
to point your local agent to a server in your network.



On the \Language{} side, one sees a set of {\em packages}
(ask \Browse{} for {\em Nag*}) for each chapter, each exporting
operations with the same name as a routine in the \naglib{}.
The arguments and return value of each operation belong to
standard \Language{} types.

The {\tt man} pages for the \naglib{} are accessible via the description
of each operation in \Browse{} (among other places).

In the implementation of each operation, the set of inputs is passed
to the local agent {\tt nagman}, which makes a
Remote Procedure Call (RPC) to the
remote {\tt nagd} daemon process.  The local agent receives the RPC
results and forwards them to the \Language{} workspace where they
are interpreted appropriately.

How are Fortran subroutines turned into RPC calls?
For each Fortran routine in the \naglib{}, a C main() routine
is supplied.
Its job is to assemble the RPC input (numeric) data stream into
the appropriate Fortran data structures for the routine, call the Fortran
routine from C and serialize the results into an RPC output data stream.

Many \naglib{} routines accept ASPs (Argument Subprogram Parameters).
These specify user-supplied Fortran routines (e.g. a routine to
supply values of a function is required for numerical integration).
How are they handled? There are new facilities in \Language{} to help.
A set of \Language{} domains has been provided to turn values in standard
 \Language{} types (such as Expression Integer) into the appropriate
piece of Fortran for each case (a filename pointing to Fortran source
for the ASP can always be supplied instead).
Ask \Browse{} for {\em Asp*} to see these domains. The Fortran fragments
are included in the outgoing RPC stream, but {\tt nagd} intercepts them,
compiles them, and links them with the main() C program before executing
the resulting program on the numeric part of the RPC stream.


%------------------------------------------------------------------------
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugWhatsNewLanguageTitle}{Interactive Front-end and Language}
\newcommand{\ugWhatsNewLanguageNumber}{15.4.}
%
% =====================================================================
\begin{page}{ugWhatsNewLanguagePage}{15.4. Interactive Front-end and Language}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------

The \axiom{leave} keyword has been replaced by the
\axiom{break} keyword for compatibility with the new \Language{}
extension language.
See section \downlink{``\ugLangLoopsBreakTitle''}{ugLangLoopsBreakPage} in Section \ugLangLoopsBreakNumber\ignore{ugLangLoopsBreak}
for more information.

Curly braces are no longer used to create sets. Instead, use
\axiomFun{set} followed by a bracketed expression. For example,
\xtc{
}{
\spadpaste{set [1,2,3,4]}
}

Curly braces are now used to enclose a block (see section
\downlink{``\ugLangBlocksTitle''}{ugLangBlocksPage} in Section \ugLangBlocksNumber\ignore{ugLangBlocks}
for more information). For compatibility, a block can still be 
enclosed by parentheses as well.

``Free functions'' created by the \axiomxl{} compiler can now be
loaded and used within the \Language{} interpreter. A {\it free
function} is a library function that is implemented outside a
domain or category constructor.

New coercions to and from type \axiomType{Expression} have been
added. For example, it is now possible to map a polynomial
represented as an expression to an appropriate polynomial type.

Various messages have been added or rewritten for clarity.

%------------------------------------------------------------------------
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugWhatsNewLibraryTitle}{Library}
\newcommand{\ugWhatsNewLibraryNumber}{15.5.}
%
% =====================================================================
\begin{page}{ugWhatsNewLibraryPage}{15.5. Library}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------

The \axiomType{FullPartialFractionExpansion}
domain has been added. This domain computes factor-free full
partial fraction expansions.
See section
\downlink{`FullPartialFractionExpansion'}{FullPartialFractionExpansionXmpPage}\ignore{FullPartialFractionExpansion}
for examples.

We have implemented the Bertrand/Cantor algorithm for integrals of
hyperelliptic functions. This brings a major speedup for some
classes of algebraic integrals.

We have implemented a new (direct) algorithm for integrating trigonometric
functions. This brings a speedup and an improvement in the answer
quality.

The {\sf SmallFloat} domain has been renamed
\axiomType{DoubleFloat} and {\sf SmallInteger} has been renamed
\axiomType{SingleInteger}. The new abbreviations as
\axiomType{DFLOAT} and \axiomType{SINT}, respectively.
We have defined the macro {\sf SF}, the old abbreviation for {\sf
SmallFloat}, to expand to \axiomType{DoubleFloat} and modified
the documentation and input file examples to use the new names
and abbreviations. You should do the same in any private \Language{}
files you have.

There are many new categories, domains and packages related to the
NAG Library Link facility. See the file

\unixcommand{\env{AXIOM}/../../src/algebra/exposed.lsp}{xterm\ -e\ vi\ +"/naglink"\ \env{AXIOM}/../../src/algebra/exposed.lsp}

for a list of constructors in the {\bf naglink} \Language{} exposure group.

We have made improvements to the differential equation solvers
and there is a new facility for solving systems of first-order 
linear differential equations.
In particular, an important fix was made to the solver for
inhomogeneous linear ordinary differential equations that
corrected the calculation of particular solutions.
We also made improvements to the polynomial
and transcendental equation solvers including the
ability to solve some classes of systems of transcendental
equations.

The efficiency of power series have been improved and left and right
expansions of \spad{tan(f(x))} at \spad{x =} a pole of \spad{f(x)}
can now be computed.
A number of power series bugs were fixed and the \axiomType{GeneralUnivariatePowerSeries}
domain was added.
The power series variable can appear in the coefficients and when this
happens, you cannot differentiate or integrate the series.  Differentiation
and integration with respect to other variables is supported.

A domain was added for representing asymptotic expansions of a
function at an exponential singularity.

For limits, the main new feature is the exponential expansion domain used
to treat certain exponential singularities.  Previously, such singularities
were treated in an {\it ad hoc} way and only a few cases were covered.  Now
\Language{} can do things like

\begin{verbatim}
limit( (x+1)**(x+1)/x**x - x**x/(x-1)**(x-1), x = %plusInfinity)
\end{verbatim}

in a systematic way.  It only does one level of nesting, though.  In other
words, we can handle \spad{exp(} some function with a pole \spad{)}, but not
\texht{\linebreak}{} \spad{exp(exp(} some function with a pole \spad{)).}

The computation of integral bases has been improved through careful
use of Hermite row reduction. A P-adic algorithm
for function fields of algebraic curves in finite characteristic has also
been developed.

Miscellaneous:
There is improved conversion of definite and indefinite integrals to
\axiomType{InputForm};
binomial coefficients are displayed in a new way;
some new simplifications of radicals have been implemented;
the operation \spadfun{complexForm} for converting to rectangular coordinates
has been added;
symmetric product operations have been added to \axiomType{LinearOrdinaryDifferentialOperator}.

%------------------------------------------------------------------------
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugWhatsNewHyperDocTitle}{\HyperName}
\newcommand{\ugWhatsNewHyperDocNumber}{15.6.}
%
% =====================================================================
\begin{page}{ugWhatsNewHyperDocPage}{15.6. \HyperName}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------

The buttons on the titlebar and scrollbar have been replaced
with ones which have a 3D effect. You can change the foreground and
background colors of these ``controls'' by including and modifying
the following lines in your {\bf .Xdefaults} file.
\begin{verbatim}
Axiom.hyperdoc.ControlBackground: White
Axiom.hyperdoc.ControlForeground: Black
\end{verbatim}

For various reasons, \HyperName{} sometimes displays a
secondary window. You can control the size and placement of this
window by including and modifying
the following line in your {\bf .Xdefaults} file.
%
\begin{verbatim}
Axiom.hyperdoc.FormGeometry: =950x450+100+0
\end{verbatim}
%
This setting is a standard X Window System geometry specification:
you are requesting a window 950 pixels wide by 450 deep and placed in
the upper left corner.

Some key definitions have been changed to conform more closely
with the CUA guidelines. Press
\texht{F9}{\downlink{F9}{ugHyperKeysPage}}
to see the current definitions.

Input boxes (for example, in the Browser) now accept paste-ins from
the X Window System. Use the second button to paste in something
you have previously copied or cut. An example of how you can use this
is that you can paste the type from an \Language{} computation
into the main Browser input box.


%------------------------------------------------------------------------
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugWhatsNewDocumentationTitle}{Documentation}
\newcommand{\ugWhatsNewDocumentationNumber}{15.7.}
%
% =====================================================================
\begin{page}{ugWhatsNewDocumentationPage}{15.7. Documentation}
% =====================================================================
\beginscroll
%------------------------------------------------------------------------
\texht{
We describe here a few additions to the on-line
version of the AXIOM book which you can read with
HyperDoc.
}{}

A section has been added to the graphics chapter, describing
how to build \twodim{} graphs from lists of points. An example is
given showing how to read the points from a file.
See section \downlink{``\ugGraphTwoDbuildTitle''}{ugGraphTwoDbuildPage} in Section \ugGraphTwoDbuildNumber\ignore{ugGraphTwoDbuild}
for details.

A further section has been added to that same chapter, describing
how to add a \twodim{} graph to a viewport which already
contains other graphs.
See section
\downlink{``\ugGraphTwoDappendTitle''}{ugGraphTwoDappendPage} in Section \ugGraphTwoDappendNumber\ignore{ugGraphTwoDappend}
for details.

Chapter 3 
and the on-line \HyperName{} help have been unified.

An explanation of operation names ending in ``?'' and ``!'' has
been added to the first chapter. 
See the
end of the section
\downlink{``\ugIntroCallFunTitle''}{ugIntroCallFunPage} in Section \ugIntroCallFunNumber\ignore{ugIntroCallFun}
for details.

An expanded explanation of using predicates has
been added to the sixth chapter. See the
example involving \userfun{evenRule} in the middle of the section
\downlink{``\ugUserRulesTitle''}{ugUserRulesPage} in Section \ugUserRulesNumber\ignore{ugUserRules}
for details.

Documentation for the \spadcmd{)compile}, \spadcmd{)library} and
\spadcmd{)load} commands has been greatly changed. This reflects
the ability of the \spadcmd{)compile} to now invoke the \axiomxl{}
compiler, the impending deletion of the \spadcmd{)load} command
and the new \spadcmd{)library} command.
The \spadcmd{)library} command replaces \spadcmd{)load} and is
compatible with the compiled output from both the old and new
compilers.

\endscroll
\autobuttons
\end{page}
%