Running the VIC-WUR Image Driver

Dependencies:

The Image Driver has three dependencies:

  1. A C compiler. We routinely test VIC-WUR using the following compilers:

    • GNU (gcc version 4+)
    • Clang (clang version 3+)

    VIC-WUR has also been compiled using these compilers:

  2. MPI. We have tested VIC-WUR with the following MPI implementations:

  3. netCDF4

Note

Compiling the Image Driver may also be done with OpenMP. Nearly all modern C compilers include the OpenMP standard and users will need to ensure that the makefile has the appropriate compiler flag (usually -fopenmp). See the discussion below for how to control OpenMP parallelization.

Compiling

In most cases, you will need to edit the NETCDF_PATH and MPI_PATH variables in the Makefile.

If you want to use a compiler other than mpicc, either edit the Makefile or set the MPICC environment variable, e.g.

    MPICC=/path/to/mpi_c_compiler

The flags and libraries required to compile VIC-WUR with netCDF are automatically determined in the Makefile. They can be overwritten by setting the following two environment variables. These variables can be determined by running nc-config --all.

    NC_LIBS="-L/path/to/libs ..."
    NC_CFLAGS="-I/path/to/includes -your_c_flags ..."

In some versions of the MPI library (e.g. OPEN-MPI with Intel), you may also need to set the environment variable MX_RCACHE=2 prior to compiling.

  • Change directory, cd, to the "Image Driver" source code directory and type make

    cd vic/drivers/image
make

  • If this completes without errors, you will now see a file called vic_image.exe in this directory. vic_image.exe is the executable file for the model.

Run VIC-WUR

At the command prompt, type:

    ./vic_image.exe -g global_parameter_filename.txt

where global_parameter_filename = name of the global parameter file corresponding to your project.

The VIC-WUR image driver can be run using parallel processing with MPI and/or OpenMP.

Note

Users are encouraged to consult their system administrator for assistance in configuring the VIC-WUR image driver for parallel processing applications.

To run VIC-WUR image driver using multiple processors using MPI, type the following instead:

    mpiexec -np $n_proc ./vic_image.exe -g global_parameter_filename.txt

where n_proc = number of processors to be used. Note that different MPI implementations may use different names for the MPI executable such as: mpirun, mpiexec_mpt, or mpiexec.hydra.

To run the VIC-WUR image driver using multiple processors with OpenMP (threads), set the environment variable OMP_NUM_THREADS:

    export OMP_NUM_THREADS=8
    ./vic_image.exe -g global_parameter_filename.txt

These two parallelization methods may also be combined using a Hybrid OpenMP/MPI approach. However, that configuration is usually machine, compiler, or scheduler dependent.

Other Command Line Options

VIC-WUR has a few other command line options:

  • ./vic_image.exe -v: says which version of VIC-WUR this is
  • ./vic_image.exe -h: prints a list of all the VIC-WUR command-line options
  • ./vic_image.exe -o: prints a list of all of the current compile-time settings in this executable; to change these settings, you must edit the appropriate header files (e.g. vic_def.h or vic_driver_shared.h) and recompile using make full.