Running ACCIV

How to run multiple passes of ACCIV

Setting up Geometry Factors

Especially when working with images of planetary atmospheres, it is common to have image pixels that do not all have the same physical size. This is because maps are given in longitude/latitude coordinates, so meaning that the size of a pixel (in kilometers) depends on its latitude.

In order support longitude/latitude images but to produce accurate velocity fields in m/s, ACCIV requires a file (typically gridGeometryFactors.h5) that contains these multiplicative factor required to convert the unit of length used in the bounds field in each image (e.g. longitude/latitude, see SettingUpACCIV) and the unit of length that is appropriate for velocities (e.g. meters).

If the bounds of an image are already given in an appropriate unit of length for computing velocities (e.g. typical laboratory images), then the geometry is considered to be "flat". The user can generate a flat geometry-factors file from any of the available image files as follows:

/path/to/acciv/makeGeometryFactors.exe image001.h5 gridGeometryFactors.h5 flat

In this example, we run makeGeometryFactors.exe with one of our image files (image001.h5), specify that the geometric factors should be written out to gridGeometryFactors.h5, and specify that the geometry is flat (all pixels are the same size).

Geometry factors for images of planetary atmospheres

In planetary-science applications, your input data typically has length units of degrees (latitude/longitude) and time units of seconds, so ACCIV first generates output velocities in units of degrees/sec. It then converts these data to meters/sec using the conversion factors found in gridGeometryFactors.h5. Planets are oblate spheroids, so the conversion factors vary with latitude, and are different for different planets. The tool makeGeometryFactors.exe makes the task of generating the geometric factors relatively simple, and can can be adapted to cases not currently supported if there is a demand. If you just run the executable with no arguments, you see:

acciv> ./makeGeometryFactors.exe
example usage: makeGeometryFactors.exe image001.h5 gridGeometryFactors.h5 [centric] [Saturn] [flat] [Re=7e7 Rp=6e7]
default is planetographic latitude and Jovian radii

The first two arguments are an input image file from which to extract the bounds variable (assumed to be longitude/latitude) and an output file where the geometric factors are stored. The argument centric means that "planetocentric" Latitude, rather than the default "planetographic" Latitude will be used (see below). The argument flat indicates that no geometric conversion is required (because bounds are already in the appropriate units of length). This would be the case for typical laboratory images, or planetary images where the curvature is negligible. Finally, Re=XXX Rp=XXX allows the user to specify the equatorial and polar radii of any planet in meters. The parameters can be used in the following combinations:

makeGeometryFactors.exe image001.h5 gridGeometryFactors.h5 ...
  ... # (No additional arguments) Jupiter with planetographic latitude
  ... centric # Jupiter with planetocentric latitude
  ... Saturn # Saturn with planetographic latitude
  ... centric Saturn # Saturn with planetocentric latitude
  ... Re=XXX Rp=XXX # Arbitrary planet with planetographic latitude
  ... centric Re=XXX Rp=XXX # Arbitrary planet with planetocentric latitude
  ... flat # Laboratory experiment or other images with no curvature

Note: positive x and positive longitude are assumed to be in opposite directions. The longitude on the left of the image must always be higher than the longitude on the right (i.e., no weirdness because of being close to ±180° longitude). One way to be on the safe side is to define the longitude relative to the center of the image, rather than as an absolute. You can always add the center longitude back in when you plot figures.

You can access helpful information about coordinates on the NASA PDS Atmospheres Node:

http://pds-atmospheres.nmsu.edu/education_and_outreach/encyclopedia/latitude.htm.

Running one ACCIV pass

Running a single pass of ACCIV is relatively trivial once the images and parameter files have been set up. Here's how to run the first pass of the first "day" in the syntheticTest test case:

cd day1/pass1
/path/to/acciv/acciv.exe

Typically, it is worth running each ACCIV pass manually and then checking the output velocity fields to make sure they look sensible before proceeding to the next pass. However, if you are very confident in your parameter choices for several passes, they can be combined into a single script. Here is an example from the same test case that executes six ACCIV passes in order to obtain a single velocity field from 8 synthetic "cloud" images:

syntheticTest: sixPassScript.csh

#!/bin/csh
setenv acciv '../../../../acciv/acciv.exe'
../../acciv/makeGeometryFactors.exe image001.h5 gridGeometryFactors.h5 flat
cd day1/pass1
date
echo  day1/pass1
$acciv
cd ../pass2
date
echo  day1/pass2
$acciv
cd ../../day2/pass1
date
echo  day2/pass1
$acciv
cd ../pass2
date
echo  day2/pass2
$acciv
cd ../../days_1_2/pass1
date
echo  days_1_2/pass1
$acciv
cd ../pass2
date
echo  days_1_2/pass2
$acciv
cd ../..
date

The first line sets up an alias to call acciv.exe. The second line computes trivial "flat" geometry factors as described above. After that, the script tells your computer to move into the directory for an ACCIV pass, call ACCIV, and then move on to the next pass’ directory after ACCIV completes.

If you run the script, ACCIV will generate a lot of progress information and display it to your screen. If you would rather capture this information into a log file, you could redirect it:

./sixPassScript.csh >& sixPassScript.log