
##########################################################################
INTRODUCTION
##########################################################################

This code implements a single-grid variable density projection method
for the incompressible Navier-Stokes equations.   Here we use
Godunov upwind methodology for the advection terms, a Crank-Nicholson 
discretization of the viscous terms in the momentum equation, 
and an approximate node-based projection to enforce the divergence-free 
constraint on velocity. 

This algorithm is described in detail in several papers; here we refer
you to the section of the recent paper, "A Conservative Adaptive Projection 
Method for the Variable Density Incompressible Navier-Stokes Equations" 
on the single grid projection algorithm, which can be found on the web site.  
See also the references cited therein.

##########################################################################
MAKING THE EXECUTABLE
##########################################################################
	
To run this code, you must build the varden executable in this directory.
You will also want to build the AmrVis executable in ../pAmrvis.

Modify the GNUmakefile in this directory to set the following flags:

DIM = 2 
COMP = your compiler
DEBUG = TRUE or FALSE
PRECISION = DOUBLE or FLOAT
USE_MPI = FALSE
PROFILE = FALSE

If you want run-time contouring capability then make sure that
USE_GRAPHTOOL is set to TRUE.  If you don't, then leave that flag
at FALSE.

Now type "make."  This should build the executable in this directory.
If you have problems at this point, please contact Ann Almgren
at ASAlmgren@lbl.gov

The executable will look something like run2d.OSF1.KCC.ex .  This is a 
two-dimensional executable built with the OSF1 operating
system, the KCC compiler, and the DEBUG=FALSE flag set in the GNUmakefile.
If DEBUG=TRUE, the executable will look like run2d.OSF1.KCC.DEBUG.ex .
The DEBUG=TRUE option exercises certain debug options in the pBoxLib 
library, and turns on several Fortran debug options also,
which may be helpful if you are trying to debug a new code.  
The DEBUG=FALSE version runs more quickly.

Now, to build the AmrVis executable, type "make" in the pAmrvis directory.

##########################################################################
VIEWING THE DATA
##########################################################################

There are two ways to look at the data which this code generates.  

The first is contour plots - displayed at runtime on the screen (requiring
X windows) and/or as postscript files if you have compiled with
the USE_GRAPHTOOL flag set to TRUE.  See the documentation at the end
of the inputs file to control the contour plotting.  

The second is plot files (plt0001, e.g., after one time step), which
are generated by the VarDen code during runtime.  The frequency of 
plot file generation is controlled in the inputs file by the parameter 
"plot_int."  These files contain the velocity, scalars, pressure averaged 
onto cells, pressure gradient and vorticiy at the time specified.  You can 
add additional derived quantities to the plot files by modifying
Grid::writePlotFile.

To view these plot files you will need to make the 2D executable in
the ../pAmrvis directory.

After the plot file (plt0001, e.g.) has been created, it can be viewed by 
typing 

../pAmrvis/amrvis2d*ex plt0001

Sample plot files from each of the sample problems are included here
in the subdirectory PlotFiles.  

##########################################################################
RUNNING THE EXECUTABLE
##########################################################################

To run the code you will need two different files in your directory : 
one read by main(), the other read by FORT_PROBINIT.  The first
is typically called "inputs", but this name is set on the command
line.  The name of the second is typically "probin", but this
name is set in the inputs file which is read in.

There are six test problems set up for you to run; you can later
edit the prob.F file and the inputs and probin files to create your 
own test problems.  You can also modify the inputs and probin files
to run these test problems at different resolution and with different
parameters.

-----------------------------------------------------------------------------

To run a constant-density inviscid spindown problem, type

run2d.OSF1.KCC.ex inputs1

(This will read probin1)

-----------------------------------------------------------------------------

To run a variable-density inviscid bubble drop problem, type

run2d.OSF1.KCC.ex inputs2

(This will read probin2)

-----------------------------------------------------------------------------

To run a constant-density doubly periodic shear layer problem, type

run2d.OSF1.KCC.ex inputs3

(This will read probin3)

-----------------------------------------------------------------------------

To run a viscous flow-in-a-channel problem, type

run2d.OSF1.KCC.ex inputs4

(This will read probin4)

-----------------------------------------------------------------------------

To run a Poiseuille viscous flow problem in x-y, type

run2d.OSF1.KCC.ex inputs5.2d

(This will read probin5)

-----------------------------------------------------------------------------

To run a Poiseuille viscous flow problem in r-z, type

run2d.OSF1.KCC.ex inputs6

(This will read probin6)

##########################################################################

To set up a different problem using the variables as given : x-velocity (u),
                                                             y-velocity (v),
                                                             density  (rho),
                                                             tracer 

(1) Determine which problem-specific constant parameters you would like to 
    be able to change at run-time.   Put these into probin (using the format
    there) and edit probdata.H to incorporate them appropriately - make
    sure to add them both to the declaration statement as well as the
    common block.

(2) Edit FORT_INITDATA and/or the routines it calls in prob.F to set 
    up your initial data.  You must initialize all the state variables - 
    u, v, rho, and the tracer.  

(3) If you would like the velocity field to satisfy div(u) = S
    rather than div(u) = 0, you must set S on cell centers and
    on nodes by editing mkdivucc.F and mkdivunod.F .  The current
    default is S = 0.

(4) If you would like to have a forcing term in your scalar equation,
    define it in mkscalforce.F

IN INPUTS:

(5) Set boundary conditions using the boundary condition flags 
    bcx_lo,bcx_hi,bcy_lo and bcy_hi.  See the comments there for a 
    description of the flags.  If you are using inflow boundary conditions, 
    you must edit "setvelinflow" and "setscalinflow" in prob.F appropriately 
    to supply the correct inflow boundary conditions.

(6) If this is a viscous problem, set visc_coef to be the dynamic
    viscosity (assumed constant).

(7) If you would like your scalar to diffuse, set the diff_coef array
    appropriately.

(8) If you have gravity in your problem then set the gravity value 
    according to your physical units.  The default in mkforce.F is
    that gravity acts in the y-direction; you can of course change this.

(9) Set max_step and stop_time to determine how long your 
    calculation will run. If you want to be governed by max_step, 
    set stop_time to a very large number.  If you want to be governed 
    by stop_time, set max_step to be a very large integer.

(10)Set check_int and plot_int to govern your graphics output
    and restart capability.

(11)Set grid.n_cell to be the size (in index space) of your problem,
    e.g. for a 16x32 calculation you would set 
 
grid.n_cell  = 16 32

(12)Set grid.prob_lo and grid.prob_hi to be the physical coordinates of
    the low and high ends of your domain.  E.g. if your calculation is
    in a 1x2 box starting at the origin, then set 

grid.prob_lo  = 0. 0.
grid.prob_hi  = 1. 2.     

(13)Set the contour intervals to be positive numbers if you want to see
    run-time contour plots of the variables.  You can also have these
    generate postscript files at runtime, or both.

##########################################################################

IF YOU NEED TO, MODIFY THE FOLLOWING IN INPUTS.  OTHERWISE, LEAVE AT
THEIR DEFAULT VALUES.

(14) Set the cfl number to be any number from 0 to 1 (in order to keep
     the calculation stable).  Suggested value for a relatively stable
     problem is 0.9; if your problem is unstable at this value then you
     must reduce it accordingly.

(15) If the problem starts with a small velocity but large acceleration,
     it is suggested that you set init_shrink to be smaller than 1, e.g.
     0.1.  If not, leave init_shrink =  1.

(16) Decide how you want to advect your scalars, using conservative or
     convective differences.  Set grid.is_conserv appropriately.

(17) Leave slope_order = 4 and init_iter = 2 unless you have reasons
     to change them.

(18) On a double precision workstation or a CRAY, leave the tolerances 
     hg.tol and mac.tol at 1.e-12 unless you have reason to change them. 
     For a single precision machine you will need to raise these values.

(19)  Leave the multigrid flags as is unless you like to see the
      convergence of the multigrid solves. 

##########################################################################

If you want to advect n additional quantities as tracers in addition 
to density, you must follow these steps:

(1) Define N_STATE in Grid.cpp to be 4 + n.
    The current version of the code is set up to have only one scalar
   ("tracer") in addition to the density, hence N_STATE is set to 4.

(2) Modify "Grid::deriveData(...) appropriately, mimicing the format 
    which is there.  Note that you are allowed to choose the name of 
    the variable in deriveData - make sure that you then add the 
    variable to the list of contour variables in the inputs file, 
    using the same name.

(3) Modify "Grid::writePlotFile(...) appropriately, uncomment the 
    line which is commented there using the name "new_scalar" - replace
    new_scalar by the name you used in (2) above.

(4) Initialize the new variable appropriately in FORT_INITDATA in prob.F .

(5) Modify mkscalforce.F appropriately if there is a forcing term for the
    new scalar.
