fcmanual.tex

波浪数值模拟

When {\tt <num>}=1, the ic is alongshore homogeneous and is a single array of
ascii numbers.   The array sizes are {\tt NX} for $u$ and {\tt NX+1} for $v$.
The boundary conditions that the model uses must already be set up in these initial
conditions.   This is also rather kludgy but makes things simpler right now.   If
you don't understand the $u$ and $v$ boundary conditions consult the other documentation.
When {\tt <num>=2}, a 2-D initial condition field is specified.   I warn against using
this because one must make sure that the initial condition field satisfies the continuity
equation.  If it doesn't then there will be problems since we have a rigid-lid model.

\smallskip

The seventh line, allows one to optionally load a streamfunction initial condition. 
Again the format is 
\begin{center}
{\tt <num>  phi\_file}
\end{center}
where {\tt <num>} can only take the values of 0 or 2.  When zero, no streamfunction
is loaded in.   When two, the ({\tt NX},{\tt NY})2-D array in {\tt phi\_file} is
loaded, and the corresponding $u$ and $v$ are \emph{added} to the pre-existing
$u$ and $v$ initial conditions.   This is really useful for creating small perturbations
to initially homogeneous alongshore currents.  The streamfunction must
satisfy the non-flow boundary condition at the boundaries.  

\begin{center} PASSIVE TRACER \end{center}

{\tt tracer [on,off]  [pointsrc]  <x> <y> <qsrc> <kappa>  <half\_life> }
where {\tt <qsrc>} is the flux source in units ..., 
{\tt <kappa>} is the lateral diffusivity, and
{\tt <half\_life>} is the tracer half life in units of seconds.



\begin{center} FLOATS  \end{center}

{\tt floats [on,off]  [random,file,point]  <nfloats/filename/nfloats> (<x> <y>) } \\
where {\tt random} puts {\tt nfloats} in random locations in the model domain,
{\tt file} loads up the initial float positions from {\tt filename} in x y pairs.
Still need to implement point floats.   

\begin{center} MODEL TIMING \end{center}

The eighth line, controls the timing of the program including total run time and
the time step $dt$.   Before explaining the format, let me explain a little about
how {\tt funwaveC} runs.    The heart of the integration code takes place within
three for loops which look like \\
{\tt  for (i=0 to .... (loop3) \\
\hspace{0.6cm} for (j=0 to .... (loop2)\\
\hspace{1.2cm} for (k=0 to .... (loop1)\\
\hspace{1.8cm} time\_step\_model(); time=time+dt \\}
The user has control of how much run time is spent within each loop.   This is convenient
when one wants to specify the output that the model is to write.    Output is covered in
the next section.   The timing control line contains eight pieces, which must all be present.
The format is \\
{\tt timing  <total\_time> (<units>) <loop2\_time> (<units>) <loop1\_time> (<units>)  <dt> (<units>)}
The four times can be floating point numbers and their meanings are summarized below
\begin{itemize}
\item {\tt total\_time} is the total time the model is to integrate for in the specified units.
\item {\tt loop2\_time} is the time spent in loop2 (i.e. {\tt for (j=0 ...}
\item {\tt loop1\_time} is the time spent in loop1 (i.e. {\tt for (k=0 ...}
\item {\tt dt} is the time step size of the model.
\end{itemize}
The are four possible choices for the units: {\tt (day), (hr), (min), (sec)}.   Different times
can have different units.   

Because the four different times control the number of iterations in the three loops (above),
the four run times must be integer divisible, that is, \\
{\tt total\_time/loop2\_time} \\
{\tt loop2\_time/loop1\_time} \\
{\tt loop1\_time/(2.0*dt)} (for AB2) or {\tt loop1\_time/(3.0*dt)} (for AB3) \\
must all be perfect integers (in common units of course).   
If not the model returns with an error message.   Note also that 
{\tt loop2\_time} can equal {\tt loop1\_time} and {\tt total\_time}
can equal {\tt loop2\_time}.   This means that one iteration of a loop
occurs.

Here is an example of a timing line.  Suppose one wants to run the model for a total of 24 hours,
with time step of 10 sec, and loop1 time of 30 min and loop2 time of 2 hours
(note these values are all integer divisible), then the timing line in the init file
would look like:\\
{\tt 1 (day) 2 (hr) 30 (min) 10 (sec) }\\

\begin{center} OUTPUT \end{center}

There are a number of functions which output the model data and are
contained in the file {\tt output.h}.   There are three options for
output, (1) at the end of loop 1 - called level 1 output, 
(2) at the end of loop 2 - called level 2 output, or (3) at
the end of the model run - called level 3 output.   This allows
for a wide range of output options at various time intervals.
The line format in the init file is the same for all three cases and looks like \\
{\tt <level> arg1 arg2 arg3 arg4 arg5} \\
where {\tt <level>} is the string ``level1'', ``level2'', or ``level3''.  
There can be as many output commands of this sort as desired (provisionally).
Following we describe the detail of each level command.

\textbf{level 1 output}:   There are three possibilities for level 1 output:
(1) point output, (2) alongshore line, and (3) cross-shore line.   Any of
U, V, or P (eta - free-surface) can be output.   For point output the format is: \\
{\tt level1 point <U,V,P> x-loc y-loc filename} \\
where {\tt x-loc} and {\tt y-loc} are the index locations for the point output and
{\tt filename} is the output file.   For example to output U at index location 5,5 to
the file ufile.dat use the command: \\
{\tt level1 point U 5 5 ufile.dat}\\
Note that the index locations cannot be out of bounds, i.e. $0 \le {\tt y-loc} < NY$ and
$0 \le {\tt x-loc} < NX$ (for U, NX+1 for V, NX-1 for P).   An error message is given if
the indicies are out of bounds.

\textbf{level 2 \& 3 output}: 
Level2 and level3 output a variable at the time interval on the entire grid.   The variable
can be eta, vorticity, or streamfunction, and it can be written to a file 
in either ascii or binary format.   Here is an example \\
{\tt level2 eta ascii etap}\\
This command writes in ascii the value of eta at the end of every
level2 loop to a file called etapXX.dat where XX is the value
of the level2 loop index.

\subsection{Example input file}

\begin{quote}
\begin{verbatim}
dimension 201 90 5  6             % dimensions nx ny and dx & dy 
bottomstress  nonlinear1  0.003  waveANH.dat
mixing biharmonic0  1.0           % lateral friction 
bathymetry  planar 0.05 0.05      %  bathymetry
forcing  0  0.0001  4 0.001       %  x & y forcing
0   0.0                           % U ic of zero
1   V.anh                         % the ANH96 V ic
0   phi0.dat                      % streamfunction perturbation 
tracer off  pointsrc 24 5 1.0 1.0  2000
floats off random 3
timing 6 (min) 3 (min) 1 (min) 0.5 (sec)
level1  point t 3 3 term          % point tracer output
level1  floats  file ascii floats1.dat
level1  cross U 0 file ascii Ucross.dat
level1  cross V 0 file ascii Vcross.dat
level3  snapshot N   file ascii eta
level3  snapshot streamfunction       file ascii stream
level3  snapshot vorticity       file ascii vort
level3  snapshot v    file ascii V
level3  snapshot u    file ascii U
level3  snapshot taubx  file ascii taubx
\end{verbatim}
\end{quote}

\section{Running - Command Line Options \& default.init}

There are two command line options to the program, verbose (-v) and diagnostic (-d).
They are invoked on the command line in the usual way.
The verbose option tells the model to write out the value of the integrated
kinetic energy at the end of every level1 loop.   This is useful for making sure
that the model isn't going unstable.    The diagnostic option (-d) 
takes an argument of 1,2, or 3 and reports on
the hard-wired options, the estimated memory usage, the stability parameters,
timing info, and performs some tests (for example explicitly testing
continuity) at the beginning of the model run and at
the end of the intended timing level given by the argument.   
Thus \texttt{-d 3} only gives diagnostic output at the  end of
the model run.   \texttt{-d 1} gives diagnostic output at the end
of every level1 iteration loop.   This is useful for diagnosing stability stuff.

The initialization file can be specified on the command line.   If it is not
{\tt funwaveC} looks for a file called {\tt default.init}.

\section{Bugs}



\end{document}