
##########################################################################
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 = 3
COMP = your compiler
DEBUG = TRUE or FALSE
PRECISION = DOUBLE or FLOAT
USE_MPI = FALSE
PROFILE = 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 run3d.OSF1.KCC.ex .  This is a 
three-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 run3d.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.

Finally, to make the AmrVis executable, type "make" in the
pAmrvis directory.  Make sure that the GNUmakefile in that
directory has DIM set to 3.

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

To view the data resulting from calculations using the code, you
will want to download and make the Amrvis program also available on the 
web site.

Plot files (plt0001, e.g., after one time step) 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 3D executable in
the ../pAmrvis directory.

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

../pAmrvis/amrvis3d*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 four 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

run3d.OSF1.KCC.ex inputs1

(This will read probin1)

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

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

run3d.OSF1.KCC.ex inputs2

(This will read probin2)

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

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

run3d.OSF1.KCC.ex inputs3

(This will read probin3)

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

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

run3d.OSF1.KCC.ex inputs4

(This will read probin4)

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

To set up a different problem using the variables as given : x-velocity (u),
                                                             y-velocity (v),
                                                             z-velocity (w),
                                                             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, w, 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, bcy_hi, bcz_lo and bcz_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 z-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 16x32x64 calculation you would set 
 
grid.n_cell  = 16 32 64

(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 1x2x4 box starting at the origin, then set 

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

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

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

(13) 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.

(14) 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.

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

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

(17) 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.

(18)  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 5 + 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 5.

(2) Modify "Grid::deriveData(...) appropriately, mimicing the format 
    which is there.  

(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.
