Existing VIC workflow

The workflow in all VIC versions up to 4.2.X has essentially remained unchanged. The model uses a nested loop to simulate the hydrology for each model grid cell:

initialize global run settings
foreach grid cell:
    initialize grid cell model parameters
    process meteorological forcings for the entire model period
    initialize model state
    foreach timestep:
        run vic model
        write output
        save model state
cleanup

The reasons to use time as the variable in the inner loop ( VIC classic ) rather than the outer loop ( VIC image mode ) are mainly historic and stem mostly from the fact that VIC has been used predominantly in uncoupled mode, that is with specified atmospheric boundary conditions. Running all times for a single grid cell meant that the entire meteorological record for that grid cell was available and could be manipulated in memory before the model was run. VIC simulations require only limited meteorological inputs (at a minimum daily precipitation, daily minimum temperature, daily maximum temperature, and daily mean wind speed) and can estimate the other required meteorological forcings using the MTCLIM algorithms that are integrated in the VIC code. This generally meant that we did not have to save large and extensive forcings datasets at a time when storage was much more limited (1990s). The latter is less of a concern these days. In addition, because each cell is run independently, it is easy to take advantage of distributed computing environments, because every single grid cell can be run on a different core by subsetting the overall domain.

This page simply documents the order of the computations in the existing (4.2.X and older) VIC implementations. Although the VIC function names may have changed (here they are based on 4.1.2), the procedure is generally the same in older versions of VIC.

Note that in the current VIC versions, all code is stored in a single directory. In the following, not all function calls are mentioned, only the top level calls.

• vicNl.c:main()

  • initialize global run settings

    • initialize_global.c:initialize_global()

      Initialize options and param_set structures with default values

    • cmd_proc.c:cmd_proc()

      Parse command line options and display runtime settings or get the name of the global parameter file.

    • get_global_param.c:get_global_param()

      Process the global parameter file and populate global options and param_set structures. Initialize global variables NF and NR. The latter two variables are used for indexing the atmos struct.

    • output_list_utils.c:create_output_list()

    • set_output_defaults.c:set_output_data_defaults()

    • parse_output_info.c:parse_output_info()

      Configure the list of variables that will be output, initialize the data structure that will store this information (out_data), determine the format that the output will be stored in and assign each variable to an output file. Note that in VIC, the output will be stored in one or more files per grid cell. These files will contain all time steps for that grid cell (and that grid cell only). See the VIC documentation on how to control the contents of VIC output files.

    • read_veglib.c:read_veglib()

      Read the global vegetation library, which is the same for all the grid cells.

    • make_dmy.c:make_dmy()

      Create calendar for the model run (array of structures with information about the day, month and year of each time step).

    • alloc_atmos.c:alloc_atmos()

      Allocate memory for an array of atmos_data_struct structures, which will contain the entire met record for a single grid cell.

  • foreach grid cell:

    • initialize grid cell model parameters

      • read_soilparam.c:read_soilparam()

        Read soil parameter file and initialize soil information for the current grid cell.

      • read_vegparam.c:read_vegparam()

        Read vegetation parameter file and initialize vegetation information for the current grid cell.

      • calc_root_fraction.c:calc_root_fractions()

        Compute the fraction of roots in each soil layer based on the root zone distribution defined in the vegetation parameter file.

      • read_lakeparam.c:read_lakeparam()

        Read lake parameter file and initialize lake information for current grid cell.

      • make_in_and_outfiles.c:make_in_and_outfiles()

        Open forcing input files and output files for the current grid cell.

      • read_snowband.c:read_snowband()

        Read elevation band file and initialize elevation band information for the current grid cell.

    • process meteorological forcings for the entire model period

      • initialize_atmos.c:initialize_atmos()

        Read the forcing files and initialize the atmospheric data structures for all model time steps. This involves invoking the MTCLIM algorithms to estimate the forcing variables that are not provided in the forcing files, but which are used for the computations.

    • initialize model state

      • initialize_model_state.c:initialize_model_state()

        Initialize the model state for the current grid cell either from a state file or based on default values if no state file is provided.

    • foreach timestep:

      • run vic model

        • dist_prec.c:dist_prec()

          This somewhat poorly named routine will set up the variables for the distributed precipitation option (DIST_PRCP) and then invoke the main VIC calculations for either this option or for the grid cell averaged precipitation case. It's poorly named in the sense that it is actually the entry to the main VIC physics code.

          The DIST_PRCP option is rarely used and will be removed, which will simplify the code. The main calls made in this routine full_energy(), put_data(), and write_model_state() can then be made directly in main() (for now) or cleanly separated as part of the code reorganization.

          • full_energy.c:full_energy()

            Entry into main VIC physics core. This routine loops over each vegetation band and each elevation band and invokes surface_fluxes() for each of these. The lake model is run last and separately from these loops.

            Note that this routine has a lot of inline calculations that should probably be encapsulated as separate functions to improve readability.

      • write output

        • put_data.c:put_data()

          Calculate elevation band and grid cell average quantities and populate the out_data structure.

          • write_data.c:write_data()

            Write specified out_data contents to file.

      • save model state

        • write_model_state.c:write_model_state()

          Writes the model state to file. This does not necessarily have to coincide with the end of a VIC model runs, which is why this is within the time step loop rather than only at the end of the model simulation.

  • cleanup

    • Close any open files and free memory (in main()).