Rocketeer Voyager Man Page

Written by John Norris and Robert Fiedler, revised 4/19/06

Note: we strongly recommend using the script ~rfiedler/bin/voyager
to run Voyager on compute nodes.  The information provided here
is to help the user understand what the script is doing.  The
voyager script prompts you for the information it needs.

................................................................................

The current version of Rocketeer Voyager is 1.3.6, on turing in
/turing/projects/csar/CSAR_Vis/v1.3.6/bin

Usage: Voyager [-c camera_file] [-f list_file] [-F image_name_format] [-s files_per_snapshot] RocketN.roc

-c camera_file - Specify a camera file (e.g., rocket.cam) saved from
                 an interactive session of Rocketeer or Apollo/Houston.

-f list_file   - Specify a file containing the filenames of the datafiles.
                 If more than one HDF files is needed to produce each
                 image, use the -s option to specify the number.
                 Group together the names of the files for each image.
                 You may use the ~rfiedler/bin/listgen script to
                 create file lists conveniently.

-F format   - Specify a C printf-style format string for use in generating
              filenames for the images.  The string should expect a float
              argument (the time), so should use exactly one of %e, %E, %f,
              %g, or %G.  We suggest using "frm_%09.6f" which means that the 
              number will take 9 spaces, with six to the right of the 
              decimal place, to match Rocstar 3 output dump file name
              time stamps (e.g., frm_07.100000.tiff)

              The default directory for the images is the one containing
              the Voyager executable.  To write them in a different
              directory, append the full path name, e.g.,
              "-F $HOME/frames/frm_%09.6f".

-s number   - Indicates the number of HDF data files per snapshot.  If
              there are 16 partitions and one hdf file per partition,
              use s = 16.  If you have multiple materials, such as
              data from fluid* and solid* files plotted in the same
              image, s should be 2 times the number of partitions (or
              Rocpanda I/O servers). 

RocketN.roc - A *.roc file saved during an interactive session of Rocketeer
              or Apollo.  It contains all the imformation for generating
              an image, including the camera position and the list of files.
              The -c and -f options override the contents of the *.roc file.

Redundant Notes:

1) Use the utility ~rfiedler/bin/listgen to generate the list of HDF file 
   names for Rocstar simulations.  Some people prefer to use the
   "sort" command, when appropriate.  All of the HDF files for 
   each snapshot must be grouped together -- you cannot, for example, 
   list all fluids files and then all solids files.

   The listgen script is set up to append to file "filelist" the names 
   of all HDF files at each output time to produce plots that include 
   one or two materials (fluids and solids).

   You also need to use the option "-s m" in the Voyager command 
   line, as in the example above, where m = the number of HDF files
   needed to produce a single image.

2) On turing, you should use the script ~rfiedler/bin/voyager to create
   and submit a batch job to run Voyager.