Existing VIC RASM workflow initialize

During the initialization step the following calls are made to functions that directly affect VIC:

• main/lnd_comp_mct.F90:lnd_init_mct()

  • main/vic_cpl_indices.F90:vic_cpl_indices_set()

    Set the coupler indices needed by the land model coupler interface. This includes the x2l and l2x fields. Any new fields that need to be exchanged with the coupler need to be added to this module. The module can be cleaned up to remove fields that are exchanged by CLM, but that are not relevant to VIC.

  • Initialize MPI communication and time manager

  • main/clm_varctl.F90:set_clmvarctl()

    Set control variables for run. Not sure how CLM specific this is. Most of this seems very generic for any land model (maybe rename to set_lndvarctl() or simply leave as is).

  • main/clm_comp.F90:clm_init0()

    • main/initializeMod.F90:initialize1()

      • main/clm_varpar.F90:clm_varpar_init()

        Initializes variables in clm_varpar module. Not clear how much of this is reused for VIC. At the very least lsmlon and lsmlat are used elsewhere (I think), which indicate the number of longitude and latitude points on the grid. In this routine they are set to the cpp directives LSMLON and LSMLAT in preproc.h. The actual values are set further down in initialize1(). Most, if not all, of the other variables appear to be CLM specific.

      • main/controlMod.F90:control_init()

        Initialize CLM run control information. Some of this is reused for VIC information. Reads the namelist file for VIC and checks that restart and/or history files are available as needed. Includes mods by Jose Renteria to set output averaging intervals.

        • main/clm_varctl.F90:clm_varctl_init()

          Mostly appears to set CLM specific variables. Can likely be cleaned up and shortened.

        • main/controlMod.F90:control_spmd()

          Distribute namelist data all processors.

      • main/controlMod.F90:control_print()

        if master processor: write out control variables. Can be cleaned up for VIC.

      • The next section of initialize1() processes the land surface grid ( main/surfrdMod.F90 ) and decomposes the grid for MPI ( main/decompInitMod.F90 ) . Need to go through this carefully to determine what is VIC-specific and how the MPI section works.

      • Broadcast the VIC filenames for the VIC soil file (fvicsoil), vegetation file (fvicveg), snow file (fvicsnow) and vegetation library (fveglib) using shr_mpi_bcast().

      • vic/wrf_allomem.c:allomemvic_

        Note that the call is made as allomemvic().

        • vic/wrf_init_global_vic.c:init_global_vicwrf()

          Initializes global_param, options, and param_set structures, which are declared as extern and treated as global variables. Needs cleaning and should probably be replaced in a rewrite.

        • The remainder of the functions allocates memory for prcp_vic, error_vic, accum_data and out_buffer structures. Also initializes the variables associated with temporal aggregation of the output. Most of the variables in this function are declared as extern and are basically treated as global variables.

          Need to go through this carefully to determine whether this is where the memory is overallocated. Not sure that that is actually the case.

      • vic/wrf_initialize_vic_model.c:initvicwrf_()

        Note that the call is made as initvicwrf.

        Initializes VIC soil, vegetation and snow parameters for each model grid cell. The function is called once per model run. Most of the function is only executed on the master processor ( iam == 0 ).

        • if master processor:

          • vic/rcm_misc_functions.c:get_date()

            Populate and return dmy struct with the current time. Should be updated to allow full time information used (minutes and seconds) or switched to use the CESM clock/calendar.

          • vic/check_files.c:check_files()

            Misnamed utility function. Simply opens the vegetation library, vegetation, soil, and elevation band files and sets the file pointer.

            • vic/open_file.c:open_file()

            Open file (and has some code to handle zipped files). Not sure whether and how much of this is necessary.

          • vic/read_veglib.c:read_veglib()

            Read the vegetation library file. This information is the same for all grid cells and is later broadcast to all processors.

          • vic/wrf_initialize_vic_model.c:getNetCDFData()

            Read the restart file and populate the netcdf_restart_struct.

          • loop over the soil parameter file:

            • vic/rcm_make_dist_prcp.c:make_dist_prcp()

              Allocate memory (still all on the master processor) for the various VIC data structures.

              • vic/make_snow_data.c:make_snow_data()

                Allocate memory for the snow_data_struct.

              • vic/make_energy_bal.c:make_energy_bal()

                Allocate memory for the energy_bal_struct. Contains hardwired values for the number of nodes.

              • vic/make_veg_var.c:make_veg_var()

                Allocate memory for the veg_var_struct.

              • vic/make_cell_data.c:make_cell_data

                Allocate memory for cell_data_struct.

              • vic/make_soil_param.c:make_soil_param

                Allocate memory for soil_con_struct.

              • vic/make_veg_param.c;make_veg_param()

                Allocate memory for veg_con_struct.

            • vic/read_soilparam.c:read_soilparam()

              Read soil parameter file and return soil_con_struct. Includes some memory allocation as well.

            • vic/read_vegparam.c:read_vegparam()

              Read vegetation parameter file and return pointer to an array of veg_con_struct. Includes some memory allocation as well.

            • vic/read_snowband.c:read_snowband()

              Read elevation band file. Includes some memory allocation as well. Note that these three functions sound similar, but have different interfces.

            • vic/calc_root_fractions.c:calc_root_fractions()

              Computes the fraction of roots in each soil layer based on the root zone distribution defined in the vegetation parameter file. Roots are assumed to be linearly distributed within each root zone.

            • vic/initialize_model_state.c:initialize_model_state()

              Initializes the model state. Parts of this code are not used and this routine would benefit from further clean up.

              • vic/initialize_snow.c:initialize_snow()

                Set all variables in the snow_data_struct to default values. Can be cleaned (not all variables are used) and includes some hardcoded variables.

              • vic/initialize_soil.c:initialize_soil()

                Initialize soil moisture to the default amount in the soil parameter file.

              • vic/initialize_veg.c:initialize_veg()

                Set moisture states in veg_var_struct to zero.

              • vic/read_initial_model_state.c:read_initial_model_state()

                Legacy name. There is no read from file, but instead the data in the netcdf_restart_struct is used to populate the various other structures.

          • Close the soil, vegetation, and elevation band parameter files.

          • vic/wrf_initialize_vic_model.c:deleteNetCDFData()

            Free the netcdf_restart_struct used to read the model state file. This is the last call that is only done on the master processor.

        • vic/vicMPI.c:distribute_veg_lib()

          Broadcast the vegetation library (which is the same for all grid cells).

        • vic/vicMPI.c:distribute_dmy()

          Broadcast model time step information

  • main/clm_comp.F90:clm_init1()

    • main/initializeMod.F90:initialize2()

      There is legacy RTM code halfway down this routine (currently commented out), which can be removed.

      • main/areaMod.F90:map_setmapsFM()`

        Mapping between atmospheric and land grids. Note that this routine includes some adjustments for downscaling, but these adjustments may be very specific to CLM. No special mapping are needed in RASM at this time, because the land and atmosphere resolutions are identical.

      • main/clmtypeInitMod.F90:initClmtype()

        This is where CLM initialization happens, including memory allocation. There is no need to execute most (all?) of this as part of VIC-RASM, but it might be good to adopt a similar workflow for the VIC coupling. Note that CLM memory and the hierarchy of land surface elements are different from that in VIC. Would be worthwhile to revisit how this is done in VIC, given the structure in CLM.

      • main/decompMod.F90:get_proc_bounds()

        Retrieve gridcell, landunit, column, and pft bounds for process. Not sure if there is a VIC equivalent.

      • main/clm_atmlnd.F90:init_atm2lnd_type()

        Allocate memory and initialize the met data structures that contain the atm2lnd exchanges.

      • main/clm_atmlnd.F90:init_lnd2atm_type()

        Allocate memory and initialize the data structures that contain the lnd2atm exchanges.

        Note that this and the previous routine are executed twice. Once on the land grid and once on the atmosphere grid.

      • main/initGridcellsMod.F90:initGridcells()

        Initializes sub-grid mapping for each land grid cell. This seems fairly CLM specific, but some of the information may be used in the VIC implementation as well.

  • main/clm_comp.F90:clm_init2()

    • In the CLM implementation this was used to initialize the surface albedo, but this code is commented out. Not sure whether this code is needed in the VIC implementation.

    • main/clm_atmlnd.F90:clm_map2gcell()

      Part of this code is re-used for VIC to set radiation and albedo related terms in the l2a structure, but it is not clear whether this is actually used. Need to make sure whether this actually does anything meaningful (and under what circumstances) and if so whether it does the right thing.

    • main/clm_comp.F90:lnd_SetgsMap_mct()

      Build the land grid numbering for MCT.

    • main/clm_comp.F90:lnd_domain_mct()

      Initialize lnd domain for MCT.

    • Initialize lnd attribute vectors x2l_l_* and l2x_l_* through repeated calls to mct_aVect_init() and 'mct_aVect_zero()'. Not clear whether these vectors are used.

    • main/clm_atmlnd.F90:clm_mapl2a()

      Maps lnd2atm fields from land grid to external grid

    • main/clm_comp.F90:lnd_export_mct()

      Map from l2x to l2x structure

      Note that clm_map2la() and lnd_export_mct() are called in sequence after initialization and after each model time step to export land information to the coupler.