path: root/src/hyper/pages/ug04.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}{3}}{} % Chapter 4

%
\newcommand{\ugInOutTitle}{Input Files and Output Styles}
\newcommand{\ugInOutNumber}{4.}
%
% =====================================================================
\begin{page}{ugInOutPage}{4. Input Files and Output Styles}
% =====================================================================
\beginscroll

In this chapter we discuss how to collect \Language{} 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 \texht{\TeX}{TeX}, FORTRAN and
monospace two-dimensional format.\footnote{\texht{\TeX}{TeX} is a
trademark of the American Mathematical Society.}

The printed version of this book uses the \Language{}
\texht{\TeX}{TeX} output formatter.
When we demonstrate a particular output style, we will need to
turn \texht{\TeX}{TeX} formatting off and the output style on so
that the correct output is shown in the text.

\beginmenu
    \menudownlink{{4.1. Input Files}}{ugInOutInPage}
    \menudownlink{{4.2. The axiom.input File}}{ugInOutSpadprofPage}
    \menudownlink{{4.3. Common Features of Using Output Formats}}{ugInOutOutPage}
    \menudownlink{{4.4. Monospace Two-Dimensional Mathematical Format}}{ugInOutAlgebraPage}
    \menudownlink{{4.5. TeX Format}}{ugInOutTeXPage}
    \menudownlink{{4.6. IBM Script Formula Format}}{ugInOutScriptPage}
    \menudownlink{{4.7. FORTRAN Format}}{ugInOutFortranPage}
\endmenu
\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutInTitle}{Input Files}
\newcommand{\ugInOutInNumber}{4.1.}
%
% =====================================================================
\begin{page}{ugInOutInPage}{4.1. Input Files}
% =====================================================================
\beginscroll
%
In this section we explain what an {\it input file} is and
%-% \HDindex{file!input}{ugInOutInPage}{4.1.}{Input Files}
why you would want to know about it.
We discuss where \Language{} 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
\spadgloss{workspace} and how to use the \spadgloss{history}
facility to generate an input file from the statements you have
entered directly into the workspace.

An {\it input} file contains \Language{} expressions and system
commands.
Anything that you can enter directly to \Language{} can be put
into an input file.
This is how you save input functions and expressions that you wish
to read into \Language{} more than one time.

To read an input file into \Language{}, use the \spadcmd{)read}
system command.
%-% \HDsyscmdindex{read}{ugInOutInPage}{4.1.}{Input Files}
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
\spadcmd{)read matrix.input} or even \spadcmd{)read matrix}?
\Language{} 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
\Language{}.
To change the current working directory, use the \spadcmd{)cd} system command.
The command \spadsys{)cd} by itself shows the current
working
%-% \HDindex{directory!default for searching}{ugInOutInPage}{4.1.}{Input Files}
directory.
%-% \HDsyscmdindex{cd}{ugInOutInPage}{4.1.}{Input Files}
To change it to
%-% \HDindex{file!input!where found}{ugInOutInPage}{4.1.}{Input Files}
the \spadsys{src/input} subdirectory for user ``babar'',
issue
\begin{verbatim}
)cd /u/babar/src/input
\end{verbatim}
\Language{} 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 \Language{}.

\beginImportant
If you have the \Language{} history facility turned on (which it is
by default), you can save all the lines you have entered into the
workspace by entering
\begin{verbatim}
)history )write
\end{verbatim}
%-% \HDsyscmdindex{history )write}{ugInOutInPage}{4.1.}{Input Files}

\Language{} 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 \spadsys{)cd}.
%-% \HDsyscmdindex{cd}{ugInOutInPage}{4.1.}{Input Files}
\endImportant

In \downlink{``\ugLangBlocksTitle''}{ugLangBlocksPage} in Section \ugLangBlocksNumber\ignore{ugLangBlocks}
we discuss using indentation in input files to group statements
into {\it blocks.}

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutSpadprofTitle}{The axiom.input File}
\newcommand{\ugInOutSpadprofNumber}{4.2.}
%
% =====================================================================
\begin{page}{ugInOutSpadprofPage}{4.2. The axiom.input File}
% =====================================================================
\beginscroll

When \Language{} starts up, it tries to read the input file
{\bf axiom.input} from your home
%-% \HDindex{start-up profile file}{ugInOutSpadprofPage}{4.2.}{The axiom.input File}
directory.
%-% \HDindex{file!start-up profile}{ugInOutSpadprofPage}{4.2.}{The axiom.input File}
It there is no {\bf axiom.input} in your home directory, it reads the copy
located in its own {\bf src/input} directory.
%-% \HDindex{file!axiom.input @{\bf axiom.input}}{ugInOutSpadprofPage}{4.2.}{The axiom.input File}
The file usually contains
system commands to personalize your \Language{} 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
\spadcmd{)set output fortran on}
in {\bf axiom.input}.
%-% \HDsyscmdindex{quit}{ugInOutSpadprofPage}{4.2.}{The axiom.input File}
If you do not want to be prompted for confirmation when you issue
the \spadcmd{)quit} system command, place
\spadcmd{)set quit unprotected}
in {\bf axiom.input}.
%-% \HDsyscmdindex{set quit unprotected}{ugInOutSpadprofPage}{4.2.}{The axiom.input File}
If you then decide that you do want to be prompted, issue
\spadcmd{)set quit protected}.
%-% \HDsyscmdindex{set quit protected}{ugInOutSpadprofPage}{4.2.}{The axiom.input File}
This is the default setting
so that new users do not leave \Language{}
inadvertently.\footnote{The
system command \spadsys{)pquit} always prompts you for
confirmation.}

To see the other system variables you can set, issue \spadsys{)set}
or use the \HyperName{} {\bf Settings} facility to view and change
\Language{} system variables.

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutOutTitle}{Common Features of Using Output Formats}
\newcommand{\ugInOutOutNumber}{4.3.}
%
% =====================================================================
\begin{page}{ugInOutOutPage}{4.3. Common Features of Using Output Formats}
% =====================================================================
\beginscroll

In this section we discuss how to start and stop the display
%-% \HDindex{output formats!common features}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
of the different output formats and how to send the output to the
screen or to a file.
%-% \HDindex{file!sending output to}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
To fix ideas, we use FORTRAN output format for most of the
examples.

You can use the \spadcmd{)set output}
system
%-% \HDindex{output formats!starting}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
command to
%-% \HDindex{output formats!stopping}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
toggle or redirect the different kinds of output.
%-% \HDsyscmdindex{set output}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
The name of the kind of output follows ``output'' in the command.
The names are

\indent{0}
\beginitems
\item[fortran]  for FORTRAN output.
\item[algebra]  for monospace two-dimensional mathematical output.
\item[tex]      for \texht{\TeX}{TeX} output.
\item[script]   for IBM Script Formula Format output.
\enditems
\indent{0}

For example, issue \spadsys{)set output fortran on} to turn on
FORTRAN format and
issue \spadsys{)set output fortran off} to turn it off.
By default, {\tt algebra} is {\tt on} and all others are {\tt off}.
%-% \HDsyscmdindex{set output fortran}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
When output is started, it is sent to the screen.
To send the output to a file, give the file name without
%-% \HDindex{output formats!sending to file}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
directory or extension.
\Language{} appends a file extension depending on the kind of
output being produced.
\xtc{
Issue this to redirect FORTRAN output to, for example, the file
{\bf linalg.sfort}.
}{
\spadpaste{)set output fortran linalg}
}
\noOutputXtc{
You must {\it also} turn on the creation of FORTRAN output.
The above just says where it goes if it is created.
}{
\spadpaste{)set output fortran on}
}
In what directory is this output placed?
It goes into the directory from which you started \Language{},
or if you have used the \spadsys{)cd} system command, the one
that you specified with \spadsys{)cd}.
%-% \HDsyscmdindex{cd}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
You should use \spadcmd{)cd} before you send the output to the file.

\noOutputXtc{
You can always direct output back to the screen by issuing this.
%-% \HDindex{output formats!sending to screen}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
}{
\spadpaste{)set output fortran console}
}
\noOutputXtc{
Let's make sure FORTRAN formatting is off so that nothing we
do from now on produces FORTRAN output.
}{
\spadpaste{)set output fortran off}
}
\noOutputXtc{
We also delete the demonstrated output file we created.
}{
\spadpaste{)system rm linalg.sfort}
}

You can abbreviate the words ``\spad{on},'' ``\spad{off}'' and
``\spad{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
%-% \HDindex{output formats!line length}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
\spadcmd{)set output length}
for all formats except FORTRAN.
%-% \HDsyscmdindex{set output length}{ugInOutOutPage}{4.3.}{Common Features of Using Output Formats}
Use \spadcmd{)set fortran fortlength} to
change the FORTRAN line length from its default value of \spad{72}.

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutAlgebraTitle}{Monospace Two-Dimensional Mathematical Format}
\newcommand{\ugInOutAlgebraNumber}{4.4.}
%
% =====================================================================
\begin{page}{ugInOutAlgebraPage}{4.4. Monospace Two-Dimensional Mathematical Format}
% =====================================================================
\beginscroll

This is the default output format for \Language{}.
%-% \HDsyscmdindex{set output algebra}{ugInOutAlgebraPage}{4.4.}{Monospace Two-Dimensional Mathematical Format}
It is usually on when you start the system.
%-% \HDindex{output formats!monospace 2D}{ugInOutAlgebraPage}{4.4.}{Monospace Two-Dimensional Mathematical Format}
%-% \HDindex{monospace 2D output format}{ugInOutAlgebraPage}{4.4.}{Monospace Two-Dimensional Mathematical Format}

\texht{\vskip 4pc}{}
\noOutputXtc{
If it is not, issue this.
}{
\spadpaste{)set output algebra on \bound{algon}}
}
\noOutputXtc{
Since the printed version of this book
(as opposed to the \HyperName{} version)
shows output produced by the
\texht{\TeX}{TeX}{} output formatter,
let us temporarily turn off
\texht{\TeX}{TeX}{} output.
}{
\spadpaste{)set output tex off \bound{texoff}}
}
\xtc{
Here is an example of what it looks like.
}{
\spadpaste{matrix [[i*x**i + j*\%i*y**j for i in 1..2] for j in 3..4] \free{algon texoff}}
}
\noOutputXtc{
Issue this to turn off this kind of formatting.
}{
\spadpaste{)set output algebra off}
}
\noOutputXtc{
Turn \texht{\TeX}{TeX}{} output on again.
}{
\spadpaste{)set output tex on}
}

The characters used for the matrix brackets above are rather ugly.
You get this character set when you issue
%-% \HDindex{character set}{ugInOutAlgebraPage}{4.4.}{Monospace Two-Dimensional Mathematical Format}
\spadcmd{)set output characters plain}.
%-% \HDsyscmdindex{set output characters}{ugInOutAlgebraPage}{4.4.}{Monospace Two-Dimensional Mathematical Format}
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
\spadcmd{)set output characters default}
to get better looking output.

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutTeXTitle}{TeX Format}
\newcommand{\ugInOutTeXNumber}{4.5.}
%
% =====================================================================
\begin{page}{ugInOutTeXPage}{4.5. TeX Format}
% =====================================================================
\beginscroll

\Language{} can produce \texht{\TeX}{TeX}{} output for your
%-% \HDindex{output formats!TeX @{\TeX}}{ugInOutTeXPage}{4.5.}{TeX Format}
expressions.
%-% \HDindex{TeX output format @{\TeX} output format}{ugInOutTeXPage}{4.5.}{TeX Format}
The output is produced using macros from the
\texht{\LaTeX}{LaTeX} document preparation system by
Leslie Lamport.\footnote{See Leslie Lamport, {\it LaTeX: A Document
Preparation System,} Reading, Massachusetts: Addison-Wesley
Publishing Company, Inc., 1986.}
The printed version of this book was produced using this formatter.

\noOutputXtc{
To turn on \texht{\TeX}{TeX}{} output formatting, issue this.
%-% \HDsyscmdindex{set output tex}{ugInOutTeXPage}{4.5.}{TeX Format}
}{
\spadpaste{)set output tex on \bound{texon}}
}
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}
\displaystyle {{3 \  \%i \  {y \sp 3}}+x}&
\displaystyle {{3 \  \%i \  {y \sp 3}}+{2 \  {x \sp 2}}} \\
\displaystyle {{4 \  \%i \  {y \sp 4}}+x}&
\displaystyle {{4 \  \%i \  {y \sp 4}}+{2 \  {x \sp 2}}}
\end{array}
\right]
\leqno(3)
\]
%AXIOM STEP NUMBER: 3
\end{verbatim}
To turn \texht{\TeX}{TeX}{} output formatting off, issue \spadsys{)set
output tex off}.
The \texht{\LaTeX}{LaTeX} macros in the output generated by \Language{}
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}

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutScriptTitle}{IBM Script Formula Format}
\newcommand{\ugInOutScriptNumber}{4.6.}
%
% =====================================================================
\begin{page}{ugInOutScriptPage}{4.6. IBM Script Formula Format}
% =====================================================================
\beginscroll

\Language{} can
%-% \HDindex{output formats!IBM Script Formula Format}{ugInOutScriptPage}{4.6.}{IBM Script Formula Format}
produce IBM Script Formula Format output for your
%-% \HDindex{IBM Script Formula Format}{ugInOutScriptPage}{4.6.}{IBM Script Formula Format}
expressions.

\texht{\vskip 2pc}{}
\noOutputXtc{
To turn IBM Script Formula Format on, issue this.
%-% \HDsyscmdindex{set output script}{ugInOutScriptPage}{4.6.}{IBM Script Formula Format}
}{
\spadpaste{)set output script on}
}
Here is an example of its output.
\begin{verbatim}
matrix [[i*x**i + j*%i*y**j for i in 1..2] for j in 3..4]

.eq set blank @
:df.
<left lb <<<<3 @@ %i @@ <y sup 3>>+x> here <<3 @@ %i @@
<y sup 3>>+<2 @@ <x sup 2>>>> habove <<<4 @@ %i @@
<y sup 4>>+x> here <<4 @@ %i @@ <y sup 4>>+<2 @@
<x up 2>>>>> right rb>
:edf.
\end{verbatim}
\noOutputXtc{
To turn IBM Script Formula Format output formatting off, issue this.
}{
\spadpaste{)set output script off}
}

\endscroll
\autobuttons
\end{page}
%
%
\newcommand{\ugInOutFortranTitle}{FORTRAN Format}
\newcommand{\ugInOutFortranNumber}{4.7.}
%
% =====================================================================
\begin{page}{ugInOutFortranPage}{4.7. FORTRAN Format}
% =====================================================================
\beginscroll

In addition to turning FORTRAN output on and off and stating where the
%-% \HDindex{output formats!FORTRAN}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
output should be placed, there are many options that control the
%-% \HDindex{FORTRAN output format}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
appearance of the generated code.
In this section we describe some of the basic options.
Issue \spadcmd{)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
\spadSyntax{\&} is used in column 6.
Since some versions of FORTRAN have restrictions on the number of lines
per statement, \Language{} breaks long expressions into segments with
a maximum of 1320 characters (20 lines of 66 characters) per segment.
%-% \HDsyscmdindex{set fortran}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
If you want to change this, say, to 660 characters,
issue the system command
%-% \HDsyscmdindex{set fortran explength}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
\spadcmd{)set fortran explength 660}.
%-% \HDindex{FORTRAN output format!breaking into multiple statements}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
You can turn off the line breaking by issuing
\spadcmd{)set fortran segment off}.
%-% \HDsyscmdindex{set fortran segment}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
Various code optimization levels are available.
%
\noOutputXtc{
FORTRAN output is produced after you issue this.
%-% \HDsyscmdindex{set output fortran}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
}{
\spadpaste{)set output fortran on \bound{forton}}
}
\noOutputXtc{
For the initial examples, we set the optimization level to 0, which is the
lowest level.
%-% \HDsyscmdindex{set fortran optlevel}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
}{
\spadpaste{)set fortran optlevel 0 \bound{opt0}\free{forton}}
}
\noOutputXtc{
The output is usually in columns 7 through 72, although fewer columns
are used in the following examples so that the output
%-% \HDindex{FORTRAN output format!line length}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
fits nicely on the page.
}{
\spadpaste{)set fortran fortlength 60}
}
\xtc{
By default, the output goes to the screen and is displayed
before the standard \Language{} two-dimensional output.
In this example, an
assignment to the variable \spad{R1} was generated because this is
the result of step 1.
}{
\spadpaste{(x+y)**3 \free{opt0}}
}
\xtc{
Here is an example that illustrates the line breaking.
}{
\spadpaste{(x+y+z)**3 \free{opt0}}
}

Note in the above examples that integers are generally converted to
%-% \HDindex{FORTRAN output format!integers vs. floats}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
floating point numbers, except in exponents.
This is the default behavior but can be turned off by issuing
\spadcmd{)set fortran ints2floats off}.
%-% \HDsyscmdindex{set fortran ints2floats}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
The rules governing when the conversion is done are:
\indent{4}
\beginitems
\item[1. ] 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[2. ] Convert all other integers in an expression to floating
point numbers.
\enditems
\indent{0}
These rules only govern integers in expressions.
Numbers generated by \Language{} for \spad{DIMENSION} statements are also
integers.

To set the type of generated FORTRAN data,
%-% \HDindex{FORTRAN output format!data types}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
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}

\xtc{
When temporaries are created, they are given a default type of
{\tt REAL.}
Also, the {\tt REAL} versions of functions are used by default.
}{
\spadpaste{sin(x) \free{opt1}}
}
\noOutputXtc{
At optimization level 1, \Language{} removes common subexpressions.
%-% \HDindex{FORTRAN output format!optimization level}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
%-% \HDsyscmdindex{set fortran optlevel}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
}{
\spadpaste{)set fortran optlevel 1 \bound{opt1}\free{forton}}
}
\xtc{
}{
\spadpaste{(x+y+z)**3 \free{opt1}}
}
\noOutputXtc{
This changes the precision to {\tt DOUBLE}.
%-% \HDsyscmdindex{set fortran precision double}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
Substitute \spad{single} for \spad{double}
%-% \HDindex{FORTRAN output format!precision}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
to return to single precision.
%-% \HDsyscmdindex{set fortran precision single}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
}{
\spadpaste{)set fortran precision double \free{opt1}\bound{double1}}
}
\xtc{
Complex constants display the precision.
}{
\spadpaste{2.3 + 5.6*\%i  \free{double1}}
}
\xtc{
The function names that \Language{} generates depend on the chosen
precision.
}{
\spadpaste{sin \%e  \free{double1}}
}
\noOutputXtc{
Reset the precision to \spad{single} and look at these two
examples again.
}{
\spadpaste{)set fortran precision single \free{opt1}\bound{single1}}
}
\xtc{
}{
\spadpaste{2.3 + 5.6*\%i  \free{single1}}
}
\xtc{
}{
\spadpaste{sin \%e  \free{single1}}
}
\xtc{
Expressions that look like lists, streams, sets or matrices cause
array code to be generated.
}{
\spadpaste{[x+1,y+1,z+1] \free{opt1}}
}
\xtc{
A temporary variable is generated to be the name of the array.
%-% \HDindex{FORTRAN output format!arrays}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
This may have to be changed in your particular application.
}{
\spadpaste{set[2,3,4,3,5] \free{opt1}}
}
\xtc{
By default, the starting index for generated FORTRAN arrays is \spad{0}.
}{
\spadpaste{matrix [[2.3,9.7],[0.0,18.778]] \free{opt1}}
}
\noOutputXtc{
To change the starting index for generated FORTRAN arrays to be \spad{1},
%-% \HDsyscmdindex{set fortran startindex}{ugInOutFortranPage}{4.7.}{FORTRAN Format}
issue this.
This value can only be \spad{0} or \spad{1}.
}{
\spadpaste{)set fortran startindex 1 \free{opt1}\bound{start1}}
}
\xtc{
Look at the code generated for the matrix again.
}{
\spadpaste{matrix [[2.3,9.7],[0.0,18.778]] \free{start1}}
}
\endscroll
\autobuttons
\end{page}
%