Running CGCAM
=============
Cgcam requires both a grid file and an input file in order to run. The
grid file (grid.dat) obviously contains the grid information whereas the
input file (cgcam.inp) contains a list of the parameters that will both
specify the case and control the behavior of the run. Additional files may
also be required in order to access more advanced features of the code and
these will be described in connection with those features. This section
provides only a brief overview of the steps required to set up a case and
run it and thus the details of both the grid generation and the input file
construction are not discussed here. See sections :ref:`grid_file` and
:ref:`inputs` for more complete information.
To run the code, follow the steps below:
Step 1 - Build the executables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you have not already done so, follow the :ref:`building_cgcam`
instructions in order to build the code.
Step 2 - Prepare an input file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The easiest way to get started is to run one of the example cases that ship
with the cgcam code. These are located in ~/cgcam/examples. Each example
case includes the required input files (cart_mesh.inp, cgcam.inp) as well
as a Readme file that gives a short description of the case. In most
cases, more advanced simulations can be set up through fairly simple
modifications to one of the test cases. For illustration, we will use the
cgcam/examples/Packet1 case, which simulates a 2-D gravity wave packet that
is shaped only in the vertical direction. Copy the contents of the
``/cgcam/examples/Packet1`` directory to a location where you would like to
perform the run. It is bad style to perform the run the cgcam/examples
directory since you will then clutter your cgcam distribution with several
potentially large output files.
Step 3 - Link or copy executable files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Link or copy the executables to the local directory (or include
``/path_to_cgcam/cgcam/src`` in your search path)
::
ln -s /path_to_cgcam/cgcam/src/cgcam .
ln -s /path_to_cgcam/cgcam/src/cart_mesh .
Step 4 - Generate the grid file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Packet1 test case uses a simple Cartesian grid, which is generated
with the cart_mesh program (see :ref:`cart_mesh` for complete details).
The cart_mesh program reads inputs from the file cart_mesh.inp, which is
contained in the Packet1 example directory. Move into your copy of the
Packet1 directory and issue
::
cart_mesh
The cart_mesh program will print some information regarding the mesh
spacings and stretching rates to the screen and it will also produce the
the grid.dat file. Three additional files ([xyz]_points.out) will also
be written and these contain a complete listing of the grid points as
well as the stretching rates.
Step 5 - Run the case
~~~~~~~~~~~~~~~~~~~~~
You must be on a platform containing an mpi environment. The command used
to launch a mpi job is not standard, but we will use the generic form
``mpirun``, which is likely to succeed on most systems. If this does not
work for you, check the documentation for your system. Note that it may
not be possible to launch a mpi job from a login node on a large-scale
cluster (most of the DoD centers are set up this way). In this case you
will need to prepare a batch script that will submitted to the queue in
order to run your job on one or more compute nodes. Again see the
system documentation for instructions on how to set up a batch script.
::
mpirun -np xx cgcam
where `xx` is the number of processors. Ideally the number of processors
should evenly divide the number of points in the vertical direction
(parameter `Nz`) in cgcam.inp. The code will still run for other
choices but these will not be load-balanced and the parallel efficiency
will drop.
Step 6 - Look at the output
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Time history files
------------------
The files \*.out contain some simple statistics that give some indication
regarding the progress and health of the run. These files are:
:cgcam.out: General information about the run. Warnings an errors are
listed here as is the cpu time taken for the run.
:dims.out: Summary of the number of mesh points and
details regarding the problem decomposition.
:params.out: A complete listing of parameter values used for all possible
inputs, including those set by default.
:Tmax.out: Maximum values of the thermodynamic variables as a function of time.
:umax.out: Maximum (absolute) values of u, v, w, and p as a function of time.
Paraview visualization files
----------------------------
Time sequences of planar visualization files are typically generated for
each run and these provide a good overview of the results. By default,
three sets of visualization files will be generated, one for each normal
direction, and these will be named xy01_xxxx.vtk, xz01_xxxx.vtk, and
yz01_xxxx.vtk, where xxxx is the frame number (0000, 0001, ...). For
2-D runs there is only one useful plane and thus there will only be one
sequence of vtk files.
The vtk files are most conveniently viewed with the paraview, an open-source
interactive visualization program (see |paraview_link|). Follow
the `Download` link of the paraview website to install the program. If you
are unfamiliar with paraview, you can use this |paraview_tutorial|
to learn how to use it.
.. |paraview_link| raw:: html
the paraview website
.. |paraview_tutorial| raw:: html
tutorial