fcmanual.tex

波浪数值模拟

\documentclass[12pt]{article}

\usepackage{times}
\usepackage{natbib}

\baselineskip = 16pt

\setlength{\parindent}{0pt}
\setlength{\parskip}{8pt}
\setlength{\textwidth}{6.5in}
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}


\begin{document}

\begin{center}
{\bf HOW TO COMPILE AND RUN funwaveC}
\end{center}

{\tt funwaveC} is an implementation of the fully nonlinear bousinessq
equations of \citep{WeiKirby95} that also includes the extensions for
a wavemaker and wave breaking.    This manual only details how to run
the model and does not describe the dynamics.

\section{Building}

To compile the program the \texttt{glib} and \texttt{gtk} of libraries
must be present.    The correct version number is the 1.2 series
The \texttt{glib} library is used to handle
various  I/O and memory resource things.    The \texttt{gtk} libarary
handles all the GUI window stuff.    These libraries work together and
are installed on most GNU/Linux and UNIX systems.    They can be
installed  \texttt{OS X} using \texttt{fink}.    The source code for
the libraries also can be downloaded from \texttt{www.gtk.org} and
again both rpms and source tar balls are available.   
 If you use rpms make sure the appropriate header files are installed.
This may require also installing the development version of glib.   
Installation of \texttt{glib} and \texttt{gtk} can be checked
by typing at a shell prompt: \texttt{\% glib-config --version}
and \texttt{\% gtk-config --version}.    If you get a response such as \texttt{1.2.8}
then you are in business.    I recommend using version /> 1.2.8.
Note the 2.0 series of these libraries will not work!

Once these libraries are installed,
To build the program, untar the distribution and enter the \texttt{shallow} directory.
Type the command \texttt{./configure}, and then \texttt{cd funwaveC}
and type \texttt{make}.    The program should
compile automatically.   This has been configured for Linux, Sun, and
OS X.

\section{Running funwaveC}

funwaveC is run on the command line by invoking at the prompt: \\
\texttt{\% funwaveC test.init}  \\
where \texttt{test.init} is the name of the input file.   
There are a number of command line options that are available.
These are\\
\begin{tabular}{rl}
-h &  Print out help information on usage and quit \\
-p &  Parse the input file to check for errors and quit \\
-g &  Opens up a GUI timing window while the model runs \\
-v &  Prints out model kinetic and potential energy at each level 1 time \\
-d [1,2,3] &  Prints out diagnostic information at either a level 1,2,
or 3 time step 
\end{tabular}

\section{Input File}


The input information is given by the filename on the command line or by 
default by \texttt{default.init}.    Comments are allowed in the initialization
file by putting a '\%' at the start of the comment line.
The format of \texttt{default.init} is:

\begin{center} MODEL DYNAMICS\end{center}
The model dynamics are given by the first line of the .init file which 
should look like \\
\texttt{funwaveC dynamics [wei_kirby,nwogu,peregrine,nswe,linear]} \\
where the options in [] define the model dynamics.   

\begin{center} GRID SIZE \& SPACING\end{center}
The grid sizes are given by the first line of the init file as \\
\texttt{dimension <nx>  <ny>  <dx>  <dy>} \\
Note that \texttt{ny} MUST be even (is this really true?)!  
The units of \texttt{dx} and \texttt{dy}
are meters.   For a run with a x and y domains of 1000 m by 450 m
and 5 meter grid spacing the line would read 
the line would be:  \texttt{dimension 201 90 5 5}

\begin{center} BOTTOM STRESS INFORMATION  \end{center}

\texttt{bottomstress  cd}
The drag coefficient $c_d$ is nondimensional and is typically $O(10^{-3})$.

\begin{center} LATERAL FRICTION  INFORMATION  \end{center}

\texttt{mixing  [none,newtonian0,biharmonic0]  nu }
The lateral friction can be either \texttt{none}, \texttt{newtonian0} or 
\texttt{biharmonic0}.    Eventually I may add other options.
%3 options for each (see \texttt{doc.tex}).   One can also use
%\texttt{newt(0,1,2)} or \texttt{bi(0,1,2)}.   
\texttt{nu} is the lateral viscoscity or hyperviscosity depending on the lateral 
friction chosen.   

\begin{center} BATHYMETRY \end{center}
The second line loads the bathymetry.  The format is
\begin{center}
{\tt bathymetry [flat, planar, file1d, file2d]  [h0, (slope h0),  filename, filename]}
\end{center}
The options for each are
where {\tt <format>} is either {\tt flat}, {\tt planar}, or {\tt file}.
If {\tt flat}, the bathymetry is
assumed constant everywhere and is given (in meters) by {\tt h0}.
When the format is 
\begin{center}
{\tt planar   slope h0}
\end{center}
the bathymetry is planar with
constant slope in x that is given by {\tt slope} and
depth at $x=0$ of {\tt h0} (in meters).
If the format is 
\begin{center}
{\tt file1d   filename}
\end{center}
The alongshore uniform bathymetry if loaded from the file {\tt  filename}
which is an ascii file of a single vector of length {\tt nx-1}.

This version
does not allow for alongshore inhomogeneous bathymetry.

\begin{center} FORCING \end{center}
The third line sets the cross-shore and alongshore forcing.   The format is
\begin{center}
{\tt forcing  <num1>  num/forcing\_file  <num2>  num/forcing\_file}
\end{center}
where {\tt <num>} is either 0, 1, 2, or 3,4 (only for alongshore forcing).  
When {\tt <num>}=0, then there is a
constant forcing in that direction given by the second parameter {\tt num}.
When {\tt <num>}=1, the forcing is alongshore homogeneous and
the forcing file is a single array of ascii numbers.   The way it is set up now is
that for cross-shore and alongshore forcing, the array sizes are {\tt NX-2} and {\tt NX-1}.
No forcing values are given at the boundary points since they are never used.
When {\tt <num>=2}, the forcing is
given by a 2-D ascii array where the second dimension is {\tt NY}.  To be clear, rows
correspond to the same cross-shore location, and columns correspond to the same
alongshore location.   I use {\tt matlab} to make these arrays and save them in ascii mode.
When {\tt <num>=3} for the alongshore forcing, it assumes the $y$-forcing is in frictional
balance with the initial condition given for $v$.   This is convenient for running shear
wave cases at different values of $\mu$ in that the forcing file does not need to be recomputed.
Note the forcing is calculated from the $v$ initial condition specified on line 6 (described
below), and does not include any streamfunction perturbation.  The case {\tt <num>=4}
is for reproducing the ANH96 results with many wavelength domains.  In this case, the
line should contain the parameters
\begin{center}
{\tt <num>  $\epsilon$ b  J}
\end{center}
which describe how the alongshore forcing is peturbed in the model.  These parameters
are described in the documentation. $\epsilon$ and {\tt b} are floating pt numbers
and $J$ must be an integer.    For the ANH96 3 wavelength run the parameters
are (0.01,1,3) - ANH96 p. 193.

\begin{center} INITIAL CONDITIONS \end{center}

The fifth and sixth lines load the $u$ and $v$ initial conditions respectively.  The
format is identical to that for the forcing
\begin{center}
{\tt <num>  ic\_file}
\end{center}
Now when {\tt <num}=0, there is a \emph{zero} initial condition for $u$
and a constant given by {\tt ic\_file} for $v$.  When {\tt <num>}=-1 for
the $v$ initial condition then it is zero.