% $Header: /d/hoffmann/usr2/people/marsa/doc/rnpl/RCS/refman.tex,v 1.11 1995/06/01 14:38:27 marsa Exp marsa $
\documentstyle [11pt] {report} 
%
\pagestyle{empty}
%
\topmargin=-0.75in
\hoffset=-0.75in
\textheight=9.0in \vsize\textheight
\textwidth=6.5in \hsize\textwidth
%
\newcommand{\TT}[1]{{\tt #1}}
\newcommand{\RNPL}{{\tt RNPL}}
\newcommand{\NR}{{\tt NR}}
\newcommand{\NT}{{\tt NT}}
\newcommand{\tabspace}{0.5cm}
\newcommand{\T}{\hspace*{\tabspace}}
\newcommand{\hilo}[2]{{}^{\raise2pt\hbox{$\scriptstyle{#1}$}}
                _{\lower2pt\hbox{$\scriptstyle{#2}$}}}
\newcommand{\ind}[2]{{}\hilo{#1}{#2}}
\newcommand{\dt}{\,\triangle t\,}
\newcommand{\dr}{\,\triangle r\,}
\newcommand{\lb}{\left(}
\newcommand{\rb}{\right)}
%
\title{
  The \RNPL\ Reference Manual 
}
%
\author{Robert L. Marsa \\
        Department of Physics and Astronomy \\
				The University of Pittsburgh \\
				Pittsburgh, PA 15260 \\[0.10cm]
				rmarsa@felipe.phyast.pitt.edu \\[0.10cm]
        Matthew W. Choptuik \\
        Center for Relativity \\
        The University of Texas at Austin \\
      Austin, TX, 78712-1081 \\[0.10cm]
        matt@infeld.ph.utexas.edu \\
}
%
\date{February 1996}
%
\begin {document}
%
\maketitle
%
\section*{Introduction}\label{Intro}

The acronym \RNPL\ stands for Rapid Numerical Prototyping Language.  
It is a language for expressing time-dependent systems of partial 
differential equations and the information necessary for solving them 
using finite-difference techniques.  It has advantages over 
traditional programming languages
such as C and FORTRAN because it only requires the user to enter the 
essential structure of the program while it fills in the details.

\RNPL\ can produce complete working programs, or a 
``skeleton'' that the user can complete.  The programs include facilities 
for reading parameters from a file, interactive control over 
output times and functions, memory management, and state 
dumping for calculation interruption and restart.
Throughout this manual, program examples will be given in 
Courier , while the rest of the text will be in Times.

\chapter{Program Structure}\label{structure}

An RNPL program consists of a series of object declarations.  RNPL is
strongly typed, so all data objects which are referenced must be
declared.  There are some exceptions to this rule having to do with
coordinates (see Section \ref{coords}).  Since RNPL is strictly
declarative, there are no ``executable'' statements.  Thus, there is no
notion of order as in a traditional programming language.  Declarations
can occur in any order in the source file.  The complete RNPL grammar is
shown in Section \ref{grammar}.

RNPL is case-sensitive in general, although case will be ignored if the
backend language is case insensitive (see Section \ref{}).  RNPL
statements are made up of tokens which fall into four classes--reserved
words, names, operators, and punctuation.  These tokens are listed in
Table \ref{tokens} and the operators are listed again in Table
\ref{ops}.  White space (space, tab, newline) is meaningless except as a
token separator, so it can be used freely in a source file to provide
clarity.

There are two kinds of comments in RNPL programs.  The first kind is
like a UNIX shell comment.  It starts with a \TT{\#} at the beginning of a
line and continues till the end of the line.  The second kind is like a
C++ comment.  It starts with \TT{//} and ends at the end of the line. 
The following example illustrates both kinds of comments.

\begin{verbatim}
# This is the first kind of comment
float A on grid1  // This is the second kind of comment
// So is this
\end{verbatim}

\section{Data Objects}\label{dataobj}

There are five kinds of data objects available in an RNPL program: 
parameters, coordinates, grids, grid functions, and attributes.  These
objects are in turn made up of scalars, vectors, and index vectors. 
Scalars are made up of a single integer, float, or string, while vectors
are one dimensional arrays of scalars.  Index vectors are arrays of
triples.  The first element of the triple gives a starting index, the
second gives an ending index, and the third gives a stride.

\section{Parameters}\label{parameters}

A parameter can be declared in several ways depending on 
whether it is a scalar or a vector,  whether or not it 
has a default value, and whether or not it is a ``constant.'' 
Some example declarations are:

\begin{verbatim}
parameter int fred
constant parameter float jim := 5
parameter float george[10]
parameter float ted[3] = [2.0 1.7 11]
parameter string name := "file_name"
constant parameter string comments[2] := ["comment 1" "comment 2"]
\end{verbatim}

As the examples show, the parameter declaration begins with the 
reserved word \TT{parameter}\ 
(optionally preceded by the reserved word 
constant). This is followed by a type which can be 
int , float , or string.  Next comes a name with a size specification 
if the parameter is a vector.  Finally, there is an 
optional assignment statement consisting of either = or := and a value.

Parameters provide a means of getting information to the program at run 
time.  The use of parameters is discussed in section \ref{param.files}.

\subsection{System Parameters}\label{sys.param}

Along with the parameters discussed above, is a special type of 
parameter known as the system parameter.  These parameters are
program dependent, but must be known at compile time.  Therefore,
system parameters must have default values and are not read from
parameter files.  Currently system parameters must be scalars.
There is one predefined system parameter which specifies the memory
size for FORTRAN programs in doubles.  Its default value is 2000000.
An example statement follows:

\begin{verbatim}
system parameter int memsiz := 100000
\end{verbatim}

System parameters are placed in a file called \TT{sys\_param.inc}.

\section{Coordinate Systems}
\label{coordinates}

The \RNPL\ compiler must know which names are coordinates.  It further groups 
these names into systems.  Some example coordinate declarations are:

\begin{verbatim}
rect coordinates t,x,y,z
sph coordinates t,r,theta,phi
\end{verbatim}

First comes a coordinate system name, then the reserved word \TT{coordinates},
and then a comma-separated list of names.  Order is important, with the 
first coordinate in the list taken to be time.  Any time coordinate can 
be repeated in other coordinate systems, but each spatial coordinate 
can be used only once.

\section{Grids}
\label{grids}

Grids define the spatial regions over which the grid functions will be defined 
as well as their storage.  A grid declaration can take one of several forms, 
the longest of which would be something like:

\begin{verbatim}
uniform rect[x,z] grid g1 [1:Nx][1:Nz] {xmin:xmax}{zmin:zmax}
\end{verbatim}

The first word can be \TT{uniform} or \TT{nonuniform}, 
though only the former is 
currently defined.  Next comes the name of the coordinate system followed
by a list of coordinates on which the grid is defined.  The above grid is 
two dimensional with coordinates $x$ and $z$.
After the coordinate
system comes the reserved word \TT{grid} followed by the grid name.  Next 
comes the index region.  In this example, the first index starts at 1 and 
goes to \TT{Nx}, 
while the second starts at 1 and goes to \TT{Nz}.  \TT{Nx}
and \TT{Nz} must be defined elsewhere.  The index regions can contain 
arbitrary expressions such as \TT{[A*B+C-2:4*Nx-5/a]}, however, as discussed
in section \ref{coord.diffs}, it is best to keep to forms like \TT{[1:Nx]} 
and \TT{[0:Nx-1]}, where \TT{Nx} has been declared as a parameter.  Finally, 
comes the coordinate region which gives the actual spatial ranges of the 
coordinates.  In the example, we have $xmin \le x \le xmax$ and 
$zmin \le z \le zmax$ .  Coordinate regions must be of the form 
\TT{\{name1:name2\}}, where \TT{name1} and \TT{name2} 
have been declared as parameters.

Other forms of the grid declaration leave out one or more of the above parts. 
The minimum allowable declaration is:
\begin{verbatim}
uniform rect grid g2
\end{verbatim}

This declaration (along with the example coordinate declaration in section 
\ref{coordinates}) declares \TT{g2} to be a three dimensional grid with
coordinates $x, y$ and $z$.
The index region will be 
\TT{[0:Nx-1][0:Ny-1][0:Nz-1]} for C output and 
\TT{[1:Nx][1:Ny][1:Nz]} for FORTRAN output.  The 
coordinate region will be 
\TT{\{xmin:xmax\}\{ymin:ymax\}\{zmin:zmax\}}

\section{Grid Functions}
\label{gfuncs}

A grid function is a function defined on a grid at one or more times.  
Some examples of grid function declarations are:

\begin{verbatim}
float A on g1 at -1,0,1
int B on g2 at 0,1
float C on g1
float D on g2 at -1,0,1 alias
float E on g3 at 0,1 "Electric Field"
\end{verbatim}

First comes the grid function type, either \TT{float} or \TT{int}.  Next 
comes the name followed by the reserved word \TT{on} and the grid name on 
which the function is defined.  If the declaration stopped here 
(such as that for \TT{C} above), we get a single time level.  Adding 
the reserved word \TT{at} followed by a list of offsets (positive or negative 
integers) gives a function defined on one time level for each offset.  
For instance the definition for \TT{A} would give a three time level 
function defined at times $n-1 , n ,$ and $n+1$.  Next comes the optional 
reserved word \TT{alias} which declares common storage for the first and 
last time levels.  Following any of these declarations can be a string 
which is used as a ``print name'' for the grid function.  Uses for the 
print name will be explained in chapter \ref{implementation}.

\section{Attributes}
\label{attributes}
An attribute is a flag array associated with the grid functions.  For 
instance, an attribute may tell which grid functions are to be output 
and which are not.  Attributes are defined in a similar manner to vector 
parameters, except the size is replaced by an encoding.  The encoding is 
either \TT{encodeone} or \TT{encodeall}, with \TT{encodeone} giving one 
value per grid function and \TT{encodeall} giving one value per time 
level per grid function.  For instance,  if five grid functions are 
defined, three of which have three time levels each while the remaining 
two have two levels each, then an attribute marked as \TT{encodeone} would 
have a length of five, while an attribute marked as \TT{encodeall} would 
have a length of thirteen.  In this case an output flag array could be 
defined as either

\begin{verbatim}
attribute int out_gf encodeone
\end{verbatim}

\noindent
or

\begin{verbatim}
attribute int out_gf encodeone := [0 0 1 1 0]
\end{verbatim}

\section{Derivative Operators}
\label{dopers}

Derivative operators are operators which act on grid functions. 
They are used for turning differential equations into finite difference
equations.  Here is a declaration for a forward difference operator:

\begin{verbatim}
operator D_FW(f,r) := (<0>f[1] - <0>f[0])/dr
\end{verbatim}

Whenever an operator is used in an expression (see section
\ref{expression}), the operator is replaced by its definition.  The name
\TT{f} is arbitrary.  It simply shows where the expression goes in the 
definition.   For instance, if \TT{D\_FW(3*A+B,r)} appeared in an expression, 
the \TT{f}'s in the right hand side would be replaced by \TT{3*A+B}.
The notation \TT{<0>f[1]} is interpreted as $ f^{n}_{i+1}$,
that is, f at the nth time level and i+1st grid position. The \TT{<>[]} is 
really an operator which acts on expressions as follows:

\begin{flushleft}
\TT{<a>f[b]} $\rightarrow$ 
   f if f is a number or parameter or time coordinate \\
\TT{<a>f[b]} $\rightarrow$ 
   $f_{i+b}$ if f is a spatial coordinate \\
\TT{<a>f[b]} $\rightarrow$
   $f^{n+a}_{i+b}$ if f is a grid function \\
\end{flushleft}

Three dimensional forward difference operators would look like this:

\begin{verbatim}
operator D_FW(f,x) := (<0>f[1][0][0] - <0>f[0][0][0])/dx
operator D_FW(f,y) := (<0>f[0][1][0] - <0>f[0][0][0])/dy
operator D_FW(f,z) := (<0>f[0][0][1] - <0>f[0][0][0])/dz
\end{verbatim}

Operator definitions can be nested as in:

\begin{verbatim}
operator D_FW(f,r) := (<0>f[1] - <0>f[0])/dr
operator D_BW(f,r) := (<0>f[0] - <0>f[-1])/dr
operator D_CN1(f,r,r) := D_BW(D_FW(<0>f[0],r),r)
operator D_CN2(f,r,r) := D_BW(D_FW(<1>f[0],r),r)
\end{verbatim}

As you can predict, the definition of \TT{D\_CN1} will result in the
usual centered second derivative, namely 
$(f^n_{i+1} - 2 f^n_i + f^n_{i-1})/dr^2$, while the
definition of \TT{D\_CN2} will result in the same thing applied at the
advanced time level, that is 
$(f^{n+1}_{i+1} - 2 f^{n+1}_i + f^{n+1}_{i-1})/dr^2$.  The list of
coordinate names after the \TT{f} signifies with respect to which 
coordinate(s) the derivative is taken.

Although operators are defined like derivatives and act as
derivatives under certain circumstances (see section
\ref{expression}), they can be defined to perform other functions,
such as the following definition which performs spatial averaging.

\begin{verbatim}
operator AVG(f,r) := (<0>f[1] + <0>f[0])/2
\end{verbatim}

Because operators are internally treated as derivatives, even
definitions such as this need the coordinate list.

\section{Residuals}
\label{residuals}

Residuals define the system of equations, typically by using
derivative operators.  Consider the following residual definition:

\begin{verbatim}
residual phi { [0:0]       := D_LF(phi,t) ;
               [1:Nx-2]    := D_LF(phi,t,t) - D_LF(phi,x,x) ;
               [Nx-1:Nx-1] := D_LF(phi,t) }
\end{verbatim}

Assuming the proper definitions of the derivative operators, this residual will
encodes the linear wave equation on a string with the end points fixed. 
An equivalent declaration would be:

\begin{verbatim}
residual phi { [0:0]       := D_LF(phi,t) = 0 ;
               [1:Nx-2]    := D_LF(phi,t,t) = D_LF(phi,x,x) ;
               [Nx-1:Nx-1] := D_LF(phi,t) = 0 }
\end{verbatim}

First comes the reserved word \TT{residual} followed by the name of the
grid function whose residual is being defined.  Next comes a
bracket-enclosed set of index regions and expressions.  The index region
shows over what range the expression is a valid description of the
behavior of the system.  The union of the index regions should equal the
index region of the grid on which the function is defined, but this is
not required.  Note that each region-expression pair is separated by a
semi-colon.

The residual tells how to determine the advanced value of a grid
function.  Thus, the residual must contain \TT{<a>f...} where \TT{a} is
the offset to the most advanced time level defined for grid function
\TT{f}.

Part of a residual for a three dimensional grid function would look
like:

\begin{verbatim}
residual A { [1:Nx][1:1][1:1] := D_LF(A,x) + D_FW(B,y) ;
          [Nx:Nx][1:Ny][1:Nz] := <1>A[0][0][0] = 5.0*C }
\end{verbatim}

The reserved word \TT{residual} can be preceded by the reserved word
\TT{evaluate} which tells the compiler to produce code which will
evaluate the residual.

In addition, the word \TT{residual} can be followed by a global offset
for example:

\begin{verbatim}
residual <1>[0] A { [1:Nx] := ... }
\end{verbatim}

This offset is applied globally to each expression appearing in the
residual.

See section \ref{expression} for more information on expressions.

\section{Initializations}
\label{inits}

An initialization defines the initial data for a grid function.  Its form 
is identical to the residual declaration with \TT{residual} replaced by
\TT{initialize}.  However the expression is interpreted differently. 
Consider the following initialization declaration:

\begin{verbatim}
initialize phi { [1:Nr] := amp*exp(-((r-c)/delta)^2) }
\end{verbatim}

Unlike the residual declaration, the expression in the initialization
must not contain its grid function.  The retarded time level of the grid
function is set to the expression.  In the case above, \TT{phi} will be
set to a Gaussian.

\section{Loop Driver}
\label{looper}

The loop driver declaration has the form \TT{looper name}, where
\TT{name} is any identifier.   When the compiler processes the driver 
statement, it looks in its library directory for a file called name.drv\_lang, 
where lang is c, f77, or f90.  It then simply includes this file into the 
generated source.

There are currently two predefined loopers: iterative and standard.  The 
iterative looper makes an initial guess at the advanced grid function values,
then calls the update routines and iterates until the norm of the 
residual is below a threshold.  The standard driver just calls the update 
routines.

\section{Updates}
\label{updates}

Update declarations can take many forms.  Here are some examples:

\begin{verbatim}
auto update phi,pi,beta

stub evolver updates A,B,C 
  header A, B[Bnp1,Bn,Bnm1], C[C], x,y,z,dt,auto work#0(5*Nx*Ny*Nz),
         static work#1(3*Nx*Ny-.5*Nz)

myroutine.inc myupdate update A,B header A,B,dt
\end{verbatim}

The first form defines an automatic update.  The declaration above would cause
the compiler to produce a routine to update the grid functions phi, pi, and beta
if residuals have been declared for them.  Otherwise, the compiler has no idea
how to update the grid functions and will produce an error message.

The second declaration will cause the compiler to produce the header for
a routine called evolver which is expected to update grid functions A,
B, and C.  The body of the routine is left blank, to be filled in by the
user.  Following the reserved word \TT{header}, comes a list of things
to appear in the calling sequence for the function.  A grid function
name such as \TT{A} above will cause all the time levels of A to be
passed to the function.  If A has three time levels (1,0,-1), then they will be
named A\_np1, A\_n, and A\_nm1 by default.  The user can provide his own
names to override the defaults as in the case of \TT{B}.  If only one
name is provided (as for \TT{C}), the time levels will be passed in as
the elements of a single vector, the first component of which will be
the advanced time level.

Other things that can appear in the header list are coordinates (such as
x,y,z above) and coordinate differentials (such as dt).  Parameters can
also be included in the list.  Work arrays are declared like the final
two parameters.  First comes \TT{auto} or \TT{static}.  Static work
arrays are declared at the start of the program and persist throughout. 
Auto work arrays are allocated before the call to the update routine and
are destroyed afterwards.  Next comes the word \TT{work} followed by the
\TT{\#} symbol and an integer.  This integer is tacked onto the end of the
word work to form the name of the array.  Finally comes an expression
for the size of the work array enclosed in parentheses.

\section{Expressions}
\label{expression}

Expressions are made up mainly of identifiers separated by operators. 
\RNPL\ defines the usual set of arithmetic operators (\TT{+,-,*,/})
along with exponentiation (\TT{\^{}} or \TT{**}).  The operators obey the usual
precedence rules.

Identifiers may be names of grid functions, coordinates, or parameters. 
In addition, grid functions may be supplied with temporal and spatial
offsets (see section \ref{dopers}), and coordinates may be supplied
with a spatial offset.

Expressions can also contain the well-known functions exp, log, tan,
sin, cos, sinh, cosh, tanh, and sqrt as well as derivative operators.

Here is an example of a complicated \RNPL\ expression:

\begin{verbatim}
a*b+(c*2.67/<0>phi[1] + d^2)/tan(theta) - r[-1]*D_(phi*3/a,r) +
  cos(3*eta)*D_(eta+D_(phi,r),r) + expand D_(a*b + c,r)
\end{verbatim}

You'll notice the word \TT{expand} before the last derivative operator. 
This tells \RNPL\ to symbolically expand the derivative before making
the operator substitution.  Thus, the final term is equivalent to:

\begin{verbatim}
D_(a,r)*b + a*D_(b,r) + D_(c,r)
\end{verbatim}

\chapter{Implementation}
\label{implementation}

\section{Case Sensitivity}
\label{case.sens}

Identifiers in \RNPL\ are case sensitive if the target language is C and
are case insensitive if the target language is FORTRAN.  Regardless of
the target language, reserved words may be given in all lower case or
all upper case.  Case combinations will produce syntax errors.

\section{Coordinate Differentials}
\label{coord.diffs}

Coordinate differentials are assumed to be anything that is a coordinate name 
with a d in front of it, such as dt or dx if t and x are coordinates. 
A coordinate differential is defined by the index region and coordinate
region of the first grid which uses its coordinate.  For instance, if
the following coordinate system and grids are defined:

\begin{verbatim}
rect coordinates t,x,y

uniform rect grid g1 [1:Nx][1:Ny] {xmin:xmax} {ymin:ymax}
uniform rect[x] grid g2 [1:N] {min:max}
\end{verbatim}

then dx will be defined from g1 by $dx = (xmax-xmin)/(Nx-1)$ even
though g2 may have a different coordinate spacing.

\section{Special Parameters and Attributes}
\label{spec.param.attr}

There are several ``special'' parameters defined by \RNPL\.  These are declared
by the program (if not by the user) and given default values.  They will be 
read from the parameter file if it contains them.  These 
parameters are shown in the following list along with their definitions 
and default values.

\begin{verbatim}
constant parameter float start_t := 0 // start time
constant parameter int iter := 100 // number of iterations
constant parameter float epsiter := 1e-5 // iteration threshold
constant parameter int fout := 0  // file output (0 no, 1 yes)
constant parameter int ser := 0 // fs output (0 no, 1 yes) if appropriate
constant parameter float lambda := .5 // dt/dr, dr=sqrt((dx^2+dy^2+dz^2)/3)
constant parameter int rmod := 1 // output every rmodth time step
constant parameter string in_file // name of file from which initial data 
                                  // will be read
constant parameter string out_file // name of file to which data will 
                                   // be written
constant parameter int level := 0 // refinement level
constant parameter int s_step := 0 // starting iteration number
constant parameter string tag := "" // prepend symbol for grid function names
constant parameter int N<c>0 := 2 // base number of grid points for the 
                                // coordinate c (there is one for each spatial 
                                // coordinate)
\end{verbatim}

\newcommand{\Nc}{{\hbox{\tt N<c>}}}

The names \Nc, where \TT{<c>} is a coordinate, 
are declared internally to \RNPL. 
They are NOT parameters, nor should they be declared by the user.  \Nc\ is
defined at run time by $\Nc = {\hbox{\tt N<c>0}}\,\,2^{level} + 1$.  
Thus, if a grid is
defined with an index region of length \Nc, it will be automatically
scaled simply by changing the value of level in the parameter file. 
Grids defined in this way will always have an odd number of points in
each dimension.

There is one pre-defined attribute: \TT{out\_gf}.  
This is an integer array with 
one element for each grid function, that is:

\begin{verbatim}
attribute int out_gf encodeone
\end{verbatim}

Each element is assigned the default value of 0.  This element tells whether 
output is enabled for that grid function or not.  The values of this
attribute can be changed during program execution.


\chapter{Compiler Usage}
\label{comp.usage}

\section{Code Generation}

The \RNPL\ compiler is called from the command line with the following
command:

\begin{verbatim}
rnpl -lang [program_file]
\end{verbatim}

The switch -lang tells \RNPL\ what the target output language is, c, f77, or 
f90.

The compiler generates code for two programs, the solver and the initial 
data generator.  If program\_file is specified, rnpl will output the solver 
code to a file.  The extensions .rnpl or \_rnpl will be removed from the end 
of program\_file if they exist.  The appropriate extension for the output 
language is then appended (.c or .f).  The initial data generator is written
to program\_file\_init plus the appropriate extension (.c or .f)  If no 
program\_file is specified, rnpl reads from stdin and writes to stdout.  In 
this case, the initial data generator goes to r\_out\_init (.c or .f).  Errors 
are directed to stderr.

\RNPL\ sends the code for the update routines to a file named updates(.h or
.f).  Also, a default attribute file is produced, named
.rnpl.attributes.

In the case of FORTRAN output, two include files named globals.inc and
other\_glbs.inc are also produced.

The compiler needs certain support files which it looks for in the current 
directory or in the directory defined by the environment variable RNPL\_PATH.

\section{Target Language Compilation}

Once the \RNPL\ compiler has been executed, the C or FORTRAN sources
must be built.  In the case of C output, simply compile the two .c
files since updates.h is automatically included.  For FORTRAN code,
compile the solver and updates.f and link them together.

\chapter{Generated Programs}
\label{gen.progs}

\section{Parameter Files}
\label{param.files}
A parameter file is an ASCII file containing arbitrary text along with
lines of the form name := value, where name is the name of a parameter,
and value is its new value.  At run time, \RNPL\ generated programs will
read this file and use any values found to initialize parameters.

Here is an example parameter file:

\begin{verbatim}
This is a parameter file
tag := "a_"
level := 1
Nx0 := 100
xmin := -10
in_file := "init_data.hdf"
out_file := "dump.hdf"
\end{verbatim}

\section{Solver}

If \RNPL\ is run on wave.rnpl and the resulting source files are then compiled 
into executables named wave and wave\_init, then the solver (wave) can be 
executed by typing ``wave param\_file'' or ``wave'' on the command line.  
Param\_file is an ASCII file of parameter values as discussed above.  If
no parameter file is given on the command line, the program will prompt
for one. If there is no initial data file (in\_file), wave 
will execute wave\_init to generate one.  If wave\_init doesn't exist,
wave will print a warning and continue without reading the initial data.
If there is an initial data file, wave will read it and continue.  Every 
rmod time steps (rmod is a parameter), wave will generate output as specified 
by out\_gf, ser, and fout.  It will print the current step and value of time 
to stdout.  During execution, the user can type \^C or \^Z to stop wave.  A 
menu will then be presented which allows the user to change the output frequency 
(rmod) and which grid functions will be output (out\_gf).   The user can 
also choose to quit.  Upon termination (either forced or after ``iter'' time 
steps), wave will dump state to out\_file.  Execution can later be resumed 
by copying out\_file to in\_file and rerunning wave.

\section{Initial Data Generator}

The initial data generator can be run from the command line as well as 
being called by the solver.  It reads the same parameter file as the solver
and writes the initial data to in\_file.

\section{Output}

One of the design goals of \RNPL\ is to provide uniform and automatic
access to I/O facilities to aid the user in examining the results of 
computations.  As discussed in section~\ref{spec.param.attr}, there 
is currently one pre-defined 
attribute: \TT{out\_gf}.  If the special 
parameter \TT{fout} is set, then every \TT{rmod} time steps, output 
is generated for every grid function for which output has been
enabled via \TT{out\_gf}.  Output is to \TT{.hdf} files: one
file for each selected grid function is created, and each file 
consists of a sequence of dumps labelled with the actual output 
time.  These files can then be post-processed with a variety 
of software, including the Explorer$^{\rm TM}$ module, 
\TT{ReadHDF\_GFT0} available via anonymous ftp from 
\TT{helmholtz.ph.utexas.edu} in \TT{/pub/explorer/modules}.

The interface to the lower level \TT{.hdf} routines is also
directly accessible from \TT{C} or \TT{Fortran} codes which 
have {\em not} been generated using \RNPL\ and is described in 
{\em The RNPL User's Guide}. 

\chapter{RNPL Grammar in BNR Format}
\begin{tabbing}
\hspace{3cm} \= \hspace{1.5cm} \= \kill
dec\_list \> $\rightarrow$ \\
\> $\mid$ \> dec\_list declaration \\
\\
declaration \> $\rightarrow$ \> param\_dec \\
\> $\mid$ \> coord\_dec \\
\> $\mid$ \> grid\_dec \\
\> $\mid$ \> gfunc\_dec \\
\> $\mid$ \> attrib\_dec \\
\> $\mid$ \> d\_operator \\
\> $\mid$ \> residual \\
\> $\mid$ \> initialization \\
\> $\mid$ \> looper \\
\> $\mid$ \> update \\
\\
param\_dec \> $\rightarrow$ \>  {\bf param} p\_type name \\
\> $\mid$ \> {\bf param} p\_type name {\bf assignop} scalar \\
\> $\mid$ \> {\bf param} p\_type name v\_size \\
\> $\mid$ \> {\bf param} p\_type name v\_size {\bf assignop} vector \\
\> $\mid$ \> {\bf const param} p\_type name \\
\> $\mid$ \> {\bf const param} p\_type name {\bf assignop} scalar \\
\> $\mid$ \> {\bf const param} p\_type name v\_size \\
\> $\mid$ \> {\bf const param} p\_type name v\_size {\bf assignop} vector \\
\\
coord\_dec  \> $\rightarrow$ \>  name {\bf coordinates} coord\_list \\
\\
grid\_dec  \> $\rightarrow$ \>  g\_type name {\bf grid} name i\_region c\_region \\
\> $\mid$ \> g\_type name {\bf grid} name \\
\> $\mid$ \> g\_type name {\bf obrack} coord\_list {\bf cbrack grid} name i\_region \\
\> \>        c\_region \\
\> $\mid$ \> g\_type name {\bf obrack} coord\_list {\bf cbrack grid} name \\
\\
gfunc\_dec  \> $\rightarrow$ \>  type name {\bf on} name \\
\> $\mid$ \> type name {\bf on} name str \\
\> $\mid$ \> type name {\bf on} name {\bf at} o\_list \\
\> $\mid$ \> type name {\bf on} name {\bf at} o\_list {\bf alias} \\
\> $\mid$ \> type name {\bf on} name {\bf at} o\_list str \\
\> $\mid$ \>type name {\bf on} name {\bf at} o\_list {\bf alias} str \\
\\
attrib\_dec  \> $\rightarrow$ \>  {\bf attrib} p\_type name encoding \\
\> $\mid$ \> {\bf attrib} p\_type name encoding {\bf assignop} vector \\
\\
d\_operator  \> $\rightarrow$ \>  {\bf operator} d\_op {\bf assignop} expr \\
\\
residual  \> $\rightarrow$ \>  {\bf resid} name {\bf obrace} res\_list {\bf cbrace} \\
\> $\mid$ \> {\bf resid} time index name {\bf obrace} res\_list {\bf cbrace} \\
\> $\mid$ \> {\bf evaluate resid} name {\bf obrace} res\_list {\bf cbrace} \\
\> $\mid$ \> {\bf evaluate resid} time index name {\bf obrace} res\_list {\bf cbrace} \\
\\
initialization  \> $\rightarrow$ \>  {\bf initialize} name {\bf obrace} res\_list {\bf cbrace} \\
\\
looper  \> $\rightarrow$ \>  {\bf looper} name \\
\\
update  \> $\rightarrow$ \>  name name {\bf update} coord\_list {\bf header} ref\_list \\
\> $\mid$ \> {\bf stub} name {\bf update} coord\_list {\bf header} ref\_list \\
\> $\mid$ \> {\bf auto update} coord\_list \\
\\
p\_type  \> $\rightarrow$ \>  {\bf int} \\
\> $\mid$ \> {\bf float} \\
\> $\mid$ \> {\bf string} \\
\\
name  \> $\rightarrow$ \>  {\bf iden} \\
\\
scalar  \> $\rightarrow$ \>  {\bf inum} \\
\> $\mid$ \> {\bf minus inum} \\
\> $\mid$ \> {\bf num} \\
\> $\mid$ \> {\bf minus num} \\
\> $\mid$ \> {\bf str} \\
\\
v\_size  \> $\rightarrow$ \>  {\bf obrack inum cbrack} \\
\\
vector  \> $\rightarrow$ \>  {\bf obrack} scalar\_list {\bf cbrack} \\
\\
coord\_list  \> $\rightarrow$ \>  name \\
\> $\mid$ \> coord\_list {\bf comma} name \\
\\
g\_type  \> $\rightarrow$ \>  {\bf uniform} \\
\> $\mid$ \> {\bf nonuniform} \\
\\
i\_region  \> $\rightarrow$ \>  {\bf obrack} expr {\bf colon} expr {\bf cbrack} \\
\> $\mid$ \> {\bf obrack} expr {\bf colon} expr {\bf cbrack} i\_region \\
\\
c\_region  \> $\rightarrow$ \>  {\bf obrace} name {\bf colon} name {\bf cbrace} \\
\> $\mid$ \> {\bf obrace} name {\bf colon} name {\bf cbrace} c\_region \\
\\
type  \> $\rightarrow$ \>  {\bf int} \\
\> $\mid$ \> {\bf float} \\
\\
o\_list  \> $\rightarrow$ \>  {\bf inum} \\
\> $\mid$ \> {\bf minus inum} \\
\> $\mid$ \> o\_list {\bf comma inum} \\
\> $\mid$ \> o\_list {\bf comma minus inum} \\
\\
encoding  \> $\rightarrow$ \>  {\bf encodeone} \\
\> $\mid$ \> {\bf encodeall} \\
\\
d\_op  \> $\rightarrow$ \>  name {\bf oparen} expr {\bf comma} coord\_list {\bf cparen} \\
\> $\mid$ \> {\bf expand} name {\bf oparen} expr {\bf comma} coord\_list {\bf cparen} \\
\\
expr  \> $\rightarrow$ \>  expr {\bf plus} expr \\
\> $\mid$ \> expr {\bf minus} expr \\
\> $\mid$ \> expr {\bf equals} expr \\
\> $\mid$ \> expr {\bf times} expr \\
\> $\mid$ \> expr {\bf divide} expr \\
\> $\mid$ \> expr {\bf caret} expr \\
\> $\mid$ \> {\bf plus} expr \\
\> $\mid$ \> {\bf minus} expr \\
\> $\mid$ \> {\bf oparen} expr {\bf cparen} \\
\> $\mid$ \> d\_op \\
\> $\mid$ \> func \\
\> $\mid$ \> gfunc \\
\> $\mid$ \> coord \\
\> $\mid$ \> name \\
\> $\mid$ \> {\bf num} \\
\> $\mid$ \> {\bf inum} \\
\\
res\_list  \> $\rightarrow$ \>  i\_region {\bf assignop} expr \\
\> $\mid$ \> res\_list {\bf scolon} i\_region {\bf assignop} expr \\
\\
time  \> $\rightarrow$ \>  {\bf oabr inum cabr} \\
\> $\mid$ \> {\bf oabr minus inum cabr} \\
\\
index  \> $\rightarrow$ \>  {\bf obrack inum cbrack} \\
\> $\mid$ \> {\bf obrack minus inum cbrack} \\
\> $\mid$ \> {\bf obrack inum cbrack} index \\ 
\> $\mid$ \> {\bf obrack minus inum cbrack} index \\ 
\\
ref\_list  \> $\rightarrow$ \>  reference \\
\> $\mid$ \> ref\_list {\bf comma} reference \\
\\
scalar\_list  \> $\rightarrow$ \>  scalar \\
\> $\mid$ \> scalar\_list scalar \\
\\
func  \> $\rightarrow$ \>  name {\bf oparen} expr {\bf cparen} \\
\\
gfunc  \> $\rightarrow$ \>  time name index \\
\\
coord  \> $\rightarrow$ \>  name {\bf obrack inum cbrack} \\
\\
reference  \> $\rightarrow$ \>  name \\
\> $\mid$ \> name {\bf obrack} coord\_list {\bf cbrack} \\
\> $\mid$ \> {\bf auto work pound inum oparen} expr {\bf cparen} \\
\> $\mid$ \> {\bf static work pound inum oparen} expr {\bf cparen} \\
\\
\end{tabbing}
Terminals

\begin{tabbing}
\hspace{3cm} \= \kill
{\bf param}  \> parameter or PARAMETER \\
{\bf assignop} \> := or = \\
{\bf coordinates} \> coordinates or COORDINATES \\
{\bf grid} \> grid or GRID \\
{\bf obrack} \> [ \\
{\bf cbrack} \> ] \\
{\bf on} \> on or ON \\
{\bf at} \> at or AT \\
{\bf attrib} \> attribute or ATTRIBUTE \\
{\bf operator} \> operator or OPERATOR \\
{\bf resid} \> residual or RESIDUAL \\
{\bf obrace} \> \{ \\
{\bf cbrace} \> \} \\
{\bf evaluate} \> evaluate or EVALUATE \\
{\bf initialize} \> initialize or INITIALIZE \\
{\bf looper} \> looper or LOOPER \\
{\bf update} \> update or updates or UPDATE or UPDATES \\
{\bf int} \> int or INT \\
{\bf float} \> float or FLOAT \\
{\bf string} \> string or STRING \\
{\bf iden} \> see below \\
{\bf inum} \> positive integer \\
{\bf minus} \> $-$ \\
{\bf num} \> positive real number \\
{\bf str} \> ``any characters'' \\
{\bf comma} \> , \\
{\bf uniform} \> uniform or UNIFORM \\
{\bf nonuniform} \> nonuniform or NONUNIFORM \\
{\bf colon} \> : \\
{\bf encodeone} \> encodeone or ENCODEONE \\
{\bf encodeall} \> encodeall or ENCODEALL \\
{\bf oparen} \> ( \\
{\bf cparen} \> ) \\
{\bf expand} \> expand or EXPAND \\
{\bf plus} \> + \\
{\bf times} \> * \\
{\bf divide} \> / \\
{\bf caret} \> \verb+^+ or ** \\
{\bf scolon} \> ; \\
{\bf oabr} \> $<$ \\
{\bf cabr} \> $>$ \\
\end{tabbing}
An iden is string which starts with a letter or \_ and contains letters, 
digits,  and \_.  It can also be two or more iden's separated by . or \verb+->+.  
For example, the following are valid iden's: \\
frank \\
AlBerT0 \\
\_george123fred\_\_\_ \\
brad.charles \\
employer\verb+->+name.first \\

%
\chapter{Acknowledgements}
%
This work was supported by 
NSF PHY-9310083 to R.A. Matzner, and 
ASC9318152 (ARPA supplemented) to the Binary Black Holes Grand Challenge
Alliance
%
\begin{thebibliography}{99}
%
\end  {thebibliography}
%
\end {document}
