Last update:
$Id$
----------------------------------------------------------------------
Right now, there are only three options for the stand-alone driver which can be
used to test two different mixing methods. The first test is to output Bryan-
Lewis mixing on two columns (a high latitude column and a tropical column),
and output the diffusivity coefficients at each level. This can be run using
pointers (allocate memory in the driver, have CVMix data structures point to
it) or using pure memory copies (allocate memory in the driver AND CVMix).

The third driver sets up a single column using the shear mixing formula found in
the Large, et al. KPP paper. For this test, each level is a different local
gradient Richardson number rather than a different depth to show how viscosity
varies with different choices of Ri.


DIRECTORY STRUCTURE
-------------------

bin/ -- Default location for the cvmix executable.

lib/ -- Default location for libcvmix.a, the library that can be linked in
        to an ocean model.

include/ -- Default location for the .o and .mod files that need to be included
            with libcvmix.a.

doc/ -- Contains documentation. At this point, it only has a PDF of the latest
        protex in-code notes and a script to generate said PDF.

manual/ -- This may be moved into doc/ at some point, it is the scientific
           description of the CVMix package.

bld/ -- Contains auxiliary files needed by the build system. CompileFlags.mak
        has default compile flags for 5 different compilers -- gfortran, 
        pgf90, ifort, xlf90, and nagfor, as well as ftn (the Cray wrapper for
        pgf90). At this time, no other compilers are supported on Cray systems.
        cvmix_setup is a python script that saves information about what
        compiler to use and where netCDF is installed in .CVMix_env.

  bld/obj -- Where .o  and .mod files for the stand-alone drivers are stored.

src/ -- Contains the source code, organized as follows. The top directory
        contains modules needed by the stand-alone driver (output, for example)
        as well as the driver routine itself. Also contains the Makefile used
        to build the cvmix executable.

  src/drivers -- Subroutines called by the driver (one per tests).

  src/shared  -- Where all the modules that are needed to use CVMix with an 
                 outside model are stored. (Use as an svn:external!) Also
                 contains the Makefile used to build the libcvmix.a library.

reg_tests/ -- I envision this becoming a way to do regression tests as we
              develop the code, but for now it just contains two functional
              tests. One outputs the diffusivity coefficients when using
              Bryan-Lewis mixing on two columns (with each column having its
              own B-L parameterization) and the other outputs the viscosity
              coefficients when using the shear mixing scheme in the KPP
              paper. (At this time the tests for double diffusion and tidal
              mixing return all 0s because those modules are not complete.)

              Note that all scripts have a "-h" (or "--help") flag to print
              usage options and a "-nc" (or "--netcdf") flag to turn on netCDF
              output.

              BL Pointer test
              ---------------
              reg_tests/Bryan-Lewis]$ ./BL_test.sh

              BL Mem copy test
              ----------------
              reg_tests/Bryan-Lewis]$ ./BL_test.sh -mc

              Shear mixing test
              -----------------
              reg_Tests/shear-KPP]$ ./Large_test.sh

              Both directories also contain a basic NCL script to produce a
              plot.

              Bryan-Lewis/plot_diff_coeffs.ncl -- makes a plot with depth on
                   the y-axis and diffusivity (for both columns) on the x-axis.
              shear-KPP/plot_visc_coeffs.ncl -- makes a plot with local gradient
                   Richardson number on the x-axis and normalized viscosity
                   coefficient on the y-axis.


INSTALLATION NOTES
------------------

The src directory contains a Makefile and a simple 'make' should be sufficient
to build the standalone driver. The first time you build, the 'cvmix_setup'
utility will run and prompt you for compiler and netcdf information - it will
only run once, and the info is saved in bld/.CVMix_env.

To build with netcdf, run 'make netcdf'.

The default executable is $CVMix/bin/cvmix, but it can be overwritten with
'make EXE=[executable]'.