Many things have changed in this new version of Axiom and we describe many of the more important topics here.
If you have any private .spad files (that is, library files which were not shipped with Axiom) you will need to recompile them. For example, if you wrote the file regress.spad then you should issue )compile regress.spad before trying to use it.
The internal representation of Union has changed. This means that Axiom data saved with Release 1.x may not be readable by this Release. If you cannot recreate the saved data by recomputing in Release 2.0, please contact NAG for assistance.
A new compiler is now available for Axiom. The programming language is referred to as the Aldor, and improves upon the old Axiom language in many ways. The )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 Axiom system.
To ease the chore of upgrading your .spad files (old compiler) to .as files (new compiler), the )compile command has been given a )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 Aldor compiler and make any necessary corrections.
The Nag Library link allows you to call NAG Fortran routines from within Axiom, passing Axiom objects as parameters and getting them back as results.
The Nag Library and, consequently, the link are divided into chapters, which cover different areas of numerical analysis. The statistical and sorting chapters of the Library, however, are not included in the link and various support and utility routines (mainly the F06 and X chapters) have been omitted.
Each chapter has a short (at most three-letter) name; for example, the chapter devoted to the solution of ordinary differential equations is called D02. When using the link via the HyperDoc interface. you will be presented with a complete menu of these chapters. The names of individual routines within each chapter are formed by adding three letters to the chapter name, so for example the routine for solving ODEs by Adams method is called d02cjfd02cjfNagOrdinaryDifferentialEquationsPackage.
Information about using the Nag Library in general, and about using individual routines in particular, can be accessed via HyperDoc. This documentation refers to the Fortran routines directly; the purpose of this subsection is to explain how this corresponds to the Axiom routines.
For general information about the Nag Library users should consult Essential Introduction to the NAG Foundation Library manpageXXintro. The documentation is in ASCII format, and a description of the conventions used to represent mathematical symbols is given in Introduction to NAG On-Line Documentation manpageXXonline. Advice about choosing a routine from a particular chapter can be found in the Chapter Documents FoundationLibraryDocPage.
The NAG documentation refers to the Fortran types of objects; in general, the correspondence to Axiom types is as follows.
(Exceptionally, for NAG EXTERNAL parameters -- ASPs in link parlance -- REAL and COMPLEX correspond to MachineFloat and MachineComplex, respectively; see aspSection .)
The correspondence for aggregates is as follows.
Higher-dimensional arrays are not currently needed for the Nag Library.
Arguments which are Fortran FUNCTIONs or SUBROUTINEs correspond to special ASP domains in Axiom. See aspSection .
NAG parameters are classified as belonging to one (or more) of the following categories: Input, Output, Workspace or External procedure. Within External procedures a similar classification is used, and parameters may also be Dummies, or 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 Input and External parameters.
The order of the parameters is, in general, different from the order specified in the Nag Library documentation. The Browser description for each routine helps in determining the correspondence. As a rule of thumb, Input parameters come first followed by Input/Output parameters. The External parameters are always found at the end.
NAG routines often return diagnostic information through a parameter called . With a few exceptions, the principle is that on input takes one of the values . This determines how the routine behaves when it encounters an error:
The user is STRONGLY ADVISED to set to when using the link. If has been set to or on input, then its value on output will determine the possible cause of any error. A value of indicates successful completion, otherwise it provides an index into a table of diagnostics provided as part of the routine documentation (accessible via Browse).
The easiest way to use the link is via the HyperDoc 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 Axiom command needed to run the chosen NAG routine with these values. Clicking on the ``Do It'' button will then cause Axiom to execute this command and return the result in the parent Axiom session, as described below. Note that, for some routines, multiple HyperDoc ``pages'' are required, due to the structure of the data. For these, returning to an earlier page causes HyperDoc to reset the later pages (this is a general feature of HyperDoc); in such a case, the simplest way to repeat a call, varying a parameter on an earlier page, is probably to modify the call displayed in the parent session.
An alternative approach is to call NAG routines directly in your normal Axiom session (that is, using the Axiom interpreter). Such calls return an object of type Result. As not all parameters in the underlying NAG routine are required in the AXIOM call (and the parameter ordering may be different), before calling a NAG routine you should consult the description of the Axiom operation in the Browser. (The quickest route to this is to type the routine name, in lower case, into the Browser's input area, then click on Operations.) The parameter names used coincide with NAG's, although they will appear here in lower case. Of course, it is also possible to become familiar with the Axiom form of a routine by first using it through the HyperDoc interface htxl1.
As an example of this mode of working, we can find a zero of a function, lying between 3 and 4, as follows:
By default, 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:
In order to avoid conflict with names defined in the workspace, you can also get the values by using the String type (the interpreter automatically coerces them to Symbol)
It is possible to have Axiom display the values of scalar or array results automatically. For more details, see the commands showScalarValuesshowScalarValuesResult and showArrayValuesshowArrayValuesResult.
There is also a .input file for each NAG routine, containing Axiom interpreter commands to set up and run the standard NAG example for that routine.
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 Union of a Filename and an ASP.
For example c05adf requires an object of type Union(fn: FileName,fp: Asp1 F)
The user thus has a choice of providing the name of a file containing Fortran source code, or of somehow generating the ASP within Axiom. If a filename is specified, it is searched for in the local machine, i.e., the machine that Axiom is running on.
The FortranExpression domain is used to represent expressions which can be translated into Fortran under certain circumstances. It is very similar to Expression except that only operators which exist in Fortran can be used, and only certain variables can occur. For example the instantiation FortranExpression([X],[M],MachineFloat) is the domain of expressions containing the scalar and the array .
This allows us to create expressions like:
but not
Those ASPs which represent expressions usually export a coerce from an appropriate instantiation of FortranExpression (or perhaps Vector FortranExpression etc.). For convenience there are also retractions from appropriate instantiations of Expression, Polynomial and Fraction Polynomial.
FortranCode FortranCode allows us to build arbitrarily complex ASPs via a kind of pseudo-code. It is described fully in generalFortran .
Every ASP exports two coerce functions: one from FortranCode and one from List FortranCode. There is also a coerce from Record( localSymbols: SymbolTable, code: List FortranCode) which is used for passing extra symbol information about the ASP.
So for example, to integrate the function abs(x) we could use the built-in abs function. But suppose we want to get back to basics and define it directly, then we could do the following:
The condcondFortranCode operation creates a conditional clause and the assignassignFortranCode an assignment statement.
Suppose we have created the file ``asp.f'' as follows:
and wish to pass it to the NAG routine d01ajf which performs one-dimensional quadrature. We can do this as follows:
This section describes more advanced facilities which are available to users who wish to generate Fortran code from within Axiom. There are facilities to manipulate templates, store type information, and generate code fragments or complete programs.
A template is a skeletal program which is ``fleshed out'' with data when it is processed. It is a sequence of active and passive parts: active parts are sequences of Axiom commands which are processed as if they had been typed into the interpreter; passive parts are simply echoed verbatim on the Fortran output stream.
Suppose, for example, that we have the following template, stored in the file ``test.tem'':
The passive parts lie between the two tokens beginVerbatim and endVerbatim. There are two active statements: one which is simply an Axiom ( \verb+--+) comment, and one which produces an assignment to the current value of f. We could use it as follows:
(A more reliable method of specifying the filename will be introduced below.) Note that the Fortran assignment F=4.0D0/(X*X+1.0D0) automatically converted 4.0 and 1 into DOUBLE PRECISION numbers; in general, the Axiom Fortran generation facility will convert anything which should be a floating point object into either a Fortran REAL or DOUBLE PRECISION object.
Which alternative is used is determined by the command
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 endInput as part of an active portion of the template will cause processing to be ended prematurely at that point.
The processTemplate command comes in two flavours. In the first case, illustrated above, it takes one argument of domain 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 directory, name and extension components, using the operation filename, as in
There is an alternative version of processTemplate, which takes two arguments (both of domain 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 (``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:
| fortranLiteral | writes a string on the Fortran output stream |
| fortranCarriageReturn | writes a carriage return on the Fortran output stream |
| fortranLiteralLine | writes a string followed by a return on the Fortran output stream |
So we could create our comment as follows:
or, alternatively:
We should stress that these functions, together with the outputAsFortran function are the only sure ways of getting output to appear on the Fortran output stream. Attempts to use Axiom commands such as output or 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.
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
(see below). The commands available to manipulate the stack are:
| clearFortranOutputStack | resets the stack to the console |
| pushFortranOutputStack | pushes a FileName onto the stack |
| popFortranOutputStack | pops the stack |
| showFortranOutputStack | returns the current stack |
| topFortranOutputStack | returns the top element of the stack |
These commands are all part of FortranOutputStackPackage.
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.
This domain represents the simple Fortran datatypes: REAL, DOUBLE PRECISION, COMPLEX, LOGICAL, INTEGER, and CHARACTER. It is possible to coerce a String or Symbol into the domain, test whether two objects are equal, and also apply the predicate functions real?real?FortranScalarType etc.
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 coerce an object of FortranScalarType into the domain or construct one from an element of FortranScalarType, a list of Polynomial Integers (which can of course be simple integers or symbols) representing its dimensions, and a Boolean declaring whether it is external or not. The list of dimensions must be empty if the Boolean is true. The functions scalarTypeOf, dimensionsOf and external? return the appropriate parts, and it is possible to get the various basic Fortran Types via functions like fortranReal.
For example:
or
This domain creates and manipulates a symbol table for generated Fortran code. This is used by FortranProgram to represent the types of objects in a subprogram. The commands available are:
| empty | creates a new SymbolTable |
| declare | creates a new entry in a table |
| fortranTypeOf | returns the type of an object in a table |
| parametersOf | returns a list of all the symbols in the table |
| typeList | returns a list of all objects of a given type |
| typeLists | returns a list of lists of all objects sorted by type |
| externalList | returns a list of all EXTERNAL objects |
| printTypes | produces Fortran type declarations from a table |
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:
Initially, any information provided is deemed to be for the main program segment.
Issuing the following command indicates that from now on all information refers to the subprogram .
It is possible to return to processing the main program segment by issuing the command:
The following commands exist:
| returnType | declares the return type of the current subprogram |
| returnTypeOf | returns the return type of a subprogram |
| argumentList | declares the argument list of the current subprogram |
| argumentListOf | returns the argument list of a subprogram |
| declare | provides type declarations for parameters of the current subprogram |
| symbolTableOf | returns the symbol table of a subprogram |
| printHeader | produces the Fortran header for the current subprogram |
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 TheSymbolTable.
This section describes facilities for representing Fortran statements, and building up complete subprograms from them.
This domain is used to represent statements like x < y. Although these can be represented directly in Axiom, it is a little cumbersome, since Axiom evaluates the last statement, for example, to true (since is lexicographically less than ).
Instead we have a set of operations, such as LT to represent , to let us build such statements. The available constructors are:
| LT | |
| GT | |
| LE | |
| GE | |
| EQ | |
| AND | and |
| OR | or |
| NOT | not |
So for example:
This domain represents code segments or operations: currently assignments, conditionals, blocks, comments, gotos, continues, various kinds of loops, and return statements.
For example we can create quite a complicated conditional statement using assignments, and then turn it into Fortran code:
The Fortran code is printed on the current Fortran output stream.
This domain is used to construct complete Fortran subprograms out of elements of FortranCode. It is parameterised by the name of the target subprogram (a Symbol), its return type (from Union(FortranScalarType,``void'')), its arguments (from List Symbol), and its symbol table (from SymbolTable). One can coerce elements of either FortranCode or Expression into it.
First of all we create a symbol table:
Now put some type declarations into it:
Then (for convenience) we set up the particular instantiation of FortranProgram
Create an object of type Expression(Integer):
Now coerce it into FP, and print its Fortran form:
We can generate a FortranProgram using . For example:
Augment our symbol table:
and transform the conditional expression we prepared earlier:
The model adopted for the link is a server-client configuration -- Axiom acting as a client via a local agent (a process called nagman). The server side is implemented by the nagd daemon process which may run on a different host. The nagman local agent is started by default whenever you start Axiom. The nagd server must be started separately. Instructions for installing and running the server are supplied in nugNagd . Use the )set naglink host system command to point your local agent to a server in your network.
On the Axiom side, one sees a set of packages (ask Browse for Nag*) for each chapter, each exporting operations with the same name as a routine in the Nag Library. The arguments and return value of each operation belong to standard Axiom types.
The man pages for the Nag Library are accessible via the description of each operation in Browse (among other places).
In the implementation of each operation, the set of inputs is passed to the local agent nagman, which makes a Remote Procedure Call (RPC) to the remote nagd daemon process. The local agent receives the RPC results and forwards them to the Axiom workspace where they are interpreted appropriately.
How are Fortran subroutines turned into RPC calls? For each Fortran routine in the Nag Library, a C main() routine is supplied. Its job is to assemble the RPC input (numeric) data stream into the appropriate Fortran data structures for the routine, call the Fortran routine from C and serialize the results into an RPC output data stream.
Many Nag Library routines accept ASPs (Argument Subprogram Parameters). These specify user-supplied Fortran routines (e.g. a routine to supply values of a function is required for numerical integration). How are they handled? There are new facilities in Axiom to help. A set of Axiom domains has been provided to turn values in standard Axiom types (such as Expression Integer) into the appropriate piece of Fortran for each case (a filename pointing to Fortran source for the ASP can always be supplied instead). Ask Browse for Asp* to see these domains. The Fortran fragments are included in the outgoing RPC stream, but 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.
The leave keyword has been replaced by the break keyword for compatibility with the new Axiom extension language. See section ugLangLoopsBreak for more information.
Curly braces are no longer used to create sets. Instead, use set followed by a bracketed expression. For example,
Curly braces are now used to enclose a block (see section ugLangBlocks for more information). For compatibility, a block can still be enclosed by parentheses as well.
``Free functions'' created by the Aldor compiler can now be loaded and used within the Axiom interpreter. A free function is a library function that is implemented outside a domain or category constructor.
New coercions to and from type 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.
The FullPartialFractionExpansion domain has been added. This domain computes factor-free full partial fraction expansions. See section FullPartialFractionExpansion for examples.
We have implemented the Bertrand/Cantor algorithm for integrals of hyperelliptic functions. This brings a major speedup for some classes of algebraic integrals.
We have implemented a new (direct) algorithm for integrating trigonometric functions. This brings a speedup and an improvement in the answer quality.
The SmallFloat domain has been renamed DoubleFloat and SmallInteger has been renamed SingleInteger. The new abbreviations as DFLOAT and SINT, respectively. We have defined the macro SF, the old abbreviation for {\sf SmallFloat}, to expand to DoubleFloat and modified the documentation and input file examples to use the new names and abbreviations. You should do the same in any private Axiom files you have.
There are many new categories, domains and packages related to the NAG Library Link facility. See the file
src/algebra/exposed.lsp
for a list of constructors in the naglink Axiom exposure group.
We have made improvements to the differential equation solvers and there is a new facility for solving systems of first-order linear differential equations. In particular, an important fix was made to the solver for inhomogeneous linear ordinary differential equations that corrected the calculation of particular solutions. We also made improvements to the polynomial and transcendental equation solvers including the ability to solve some classes of systems of transcendental equations.
The efficiency of power series have been improved and left and right expansions of at a pole of can now be computed. A number of power series bugs were fixed and the 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 ad hoc way and only a few cases were covered. Now Axiom can do things like
in a systematic way. It only does one level of nesting, though. In other words, we can handle , but not .
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 InputForm; binomial coefficients are displayed in a new way; some new simplifications of radicals have been implemented; the operation complexForm for converting to rectangular coordinates has been added; symmetric product operations have been added to LinearOrdinaryDifferentialOperator.
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 .Xdefaults file.
For various reasons, HyperDoc sometimes displays a secondary window. You can control the size and placement of this window by including and modifying the following line in your .Xdefaults file.
This setting is a standard X Window System geometry specification: you are requesting a window 950 pixels wide by 450 deep and placed in the upper left corner.
Some key definitions have been changed to conform more closely with the CUA guidelines. Press F9 to see the current definitions.
Input boxes (for example, in the Browser) now accept paste-ins from the X Window System. Use the second button to paste in something you have previously copied or cut. An example of how you can use this is that you can paste the type from an Axiom computation into the main Browser input box.
We describe here a few additions to the on-line version of the AXIOM book which you can read with HyperDoc.
A section has been added to the graphics chapter, describing how to build two-dimensional graphs from lists of points. An example is given showing how to read the points from a file. See section ugGraphTwoDbuild for details.
A further section has been added to that same chapter, describing how to add a two-dimensional graph to a viewport which already contains other graphs. See section ugGraphTwoDappend for details.
Chapter 3 and the on-line HyperDoc help have been unified.
An explanation of operation names ending in ``?'' and ``!'' has been added to the first chapter. See the end of the section ugIntroCallFun for details.
An expanded explanation of using predicates has been added to the sixth chapter. See the example involving evenRule in the middle of the section ugUserRules for details.
Documentation for the )compile, )library and )load commands has been greatly changed. This reflects the ability of the )compile to now invoke the Aldor compiler, the impending deletion of the )load command and the new )library command. The )library command replaces )load and is compatible with the compiled output from both the old and new compilers.