Existing VIC RASM workflow run

The coupler calls lnd_run_mct for every timestep. During the run step the following calls are made to functions that directly affect VIC:

• main/lnd_comp_mct.F90:lnd_run_mct()

  Main call made by the coupler to the land model

  • main/lnd_comp_mct.F90:lnd_import_mct()

    Populate the a2l data structure with the fields in the x2l_l data structure supplied by the coupler. This also assignes fields that are not used in VIC, so can be cleaned up (CO2 related variables). The a2l structure is used to get the forcings from the coupler to VIC.

  • main/clm_atmlnd.F90:clm_mapa2l()

    Map the a2l structure from the atmospheric to the land grid.

  • Loop over the time steps in the coupling interval:

    This is to allow for multiple model time steps per coupling time step. In the VIC implementation in RASM, there is one model time step per coupling time step, but in principle, the coupling can be done at a lower frequency. Need to make sure that this is actually implemented correctly. It would required that the l2x fields report the appropriate time-aggregated variables.

    • Set the flag that requires an albedo calculation

      CESM would like a forward-looking albedo for the radiation calculation. VIC does not currently provide this. It would be good to implement this to maintain the expected order of the radiation calculations (the order does not change, but VIC will provide albedo for the last time step, whereas the other models will provide it for the next time step). The flag doalb is set if albedo information is needed.

    • Determine if a restart file needs to be written

      Set rstwr flag.

    • main/clm_comp.F90:clm_run1()

      The land model runs in two phases. This function is simply a pass-through to driver1().

      • main/driver.F90:driver1()

        Sets up some MPI information and distribute cell information. The make main call into VIC.

        if master processor:

        • vic/vicMPI.c:msend_mpi_prcp_()

          Note that this is called from driver1() as msend_mpi_prcp().

        if not master processor:

        • vic/vicMPI.c:srecv_mpi_prcp_()

          Note that this is called from driver1() as srecv_mpi_prcp().

        • vic/wrf_vic_interface.c:vicmodelwrf_()

          Note that this is called from driver1() as vicmodelwrf().

          This is the main entry to the VIC code. Memory for the out_data and accum_data structures is allocated and freed in this function. There are three main calls:

          • vic/rcm_misc_functions.c:convert_forcing_data()

            Poorly named legacy function. Populates the VIC forcing_data structure.

          • vic/wrf_vic_band.c:vic_bandwrf()

            • vic/read_atmos.c:read_atmos()

              Uses forcing_data structure to populate the atmos structure. Should be combined with convert_forcing_data(). Nothing is actually read from file in this function.

            • vic/dist_prec.c:dist_prec()

              This subroutine calls the solution routines for a single grid cell for one time step. It also controls the distribution of precipitation and reassembles grid cell data for output. Once the distributed precipitation options is removed, this routine can go away. It essentially serves as a pass through for full_energy() and put_data().

              • *vic/full_energy.c:full_energy()

                This subroutine controls the model core, it solves both the energy and water balance models, as well as frozen soils.

              • *vic/rcm_put_data.c:put_data()

                Populate the out_data structure.

          After this, the variables that will be passed back to the coupler are calculated from the values in out_data. This is done directly in the body of the vicmodelwrf_() function.

          • vic/wrf_accum_data.c:wrf_accum_data()

            Populates the members of the accum_data structure. Supports averaging as well as instantaneous values.

        After vicmodelwrf_(), the main structure is gathered again on the master processor. If I understand this correctly, this means that the master processor keeps the entire model state in memory for the entire land domain. This may become a problem for higher resolution model runs or if the amount of information per grid cell becomes significantly larger.

        if master processor:

        • vic/vicMPI.c:mrecv_mpi_prcp_()

          Note that this is called from driver1() as mrecv_mpi_prcp().

        if not master processor:

        • vic/vicMPI.c:ssend_mpi_prcp_()

          Note that this is called from driver1() as ssend_mpi_prcp().

        Gather the accumulation data onto the master processor. Note that the accumulation data is always sent from the slave to the master.

        if master processor:

        • vic/vicMPI.c:mrecv_mpi_acc_()

          Note that this is called from driver1() as mrecv_mpi_acc().

        if not master processor:

        • vic/vicMPI.c:ssend_mpi_acc_()

          Note that this is called from driver1() as ssend_mpi_acc().

        After the loop over the grid cells there is some cleanup of MPI communication, which should be verified to see if it is still needed.

        if master processor and restart:

        • vic/out_sav_vic.c:outsavvic_()

          Note that this is called from driver1() as outsavvic().

          Write the model state file. This has been modified to write NetCDF files.

        if master processor and output:

        • vic/wrf_write_data.c:wrf_write_data_()

          Note that this is called from driver1() as wrf_write_data().

          Write the model output file based on the values stored in the accum_data structure. This has been modified to write NetCDF files.

    • main/clm_comp.F90:clm_run2()

      The land model runs in two phases. This function is simply a pass-through to driver2(). Note that there are two similar calls to driver2 (one uses default arguments, the other does not).

      • main/driver.F90:driver2()

        The routine does not appear to do anything and can likely be removed.