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 Grid file structure and User Input Variables 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 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 4 - Generate the grid file

The Packet1 test case uses a simple Cartesian grid, which is generated with the cart_mesh program (see Constructing a Cartesian 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 the paraview website). Follow the Download link of the paraview website to install the program. If you are unfamiliar with paraview, you can use this tutorial to learn how to use it.