# VIC Soil Parameter File

The soil parameter file serves three main purposes:

*   Define the cell ID number of each grid cell. This ID number is essentially a database key that links a grid cell to its parameters in the various parameter files.
*   Define the grid cell soil parameters, as well as geographic information such as grid cell center latitude and longitude.
*   Define initial soil moisture conditions, to be used in the absence of an initial state file.

The soil parameters are supplied to VIC as a single ASCII file, with a separate row for each grid cell, with each field containing a different parameter value (description of this file is below).

Soil hydrologic and thermal parameters needed for the different VIC model set-ups are listed below. All columns of the input file must be filled, but certain parameters need only be defined if the full energy or frozen soil models are activated. Variables in <font color="#ff0000">Red</font> only need to have meaningful values if `FULL_ENERGY` is `TRUE`, otherwise they will be ignored (but a placeholder value of -9999 must still be present in that field unless the documentation explicitly says the field is optional). <font color="#800080">Violet</font> text indicates parameters needed for the frozen soil model. Header lines can be added by starting the line with a '#'.

In previous versions certain parameters were read as average values for the entire soil column. In version 4.0 all soil parameter values are now read for all layers. Converting the soil parameter file from older model versions, should simply require copying column average values to separate columns for each soil moisture layer.

To help in understanding this file, an example file has been attached at the bottom of this page.

| Column                            | Variable Name             | Units     | Number of Values  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|--------------------------------   |------------------------   |---------- |------------------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------    |
| 1                                 | run_cell                  | N/A       | 1                 | 1 = Run Grid Cell, 0 = Do Not Run                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 2                                 | gridcel                   | N/A       | 1                 | Grid cell number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 3                                 | lat                       | degrees   | 1                 | Latitude of grid cell                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 4                                 | lon                       | degrees   | 1                 | Longitude of grid cell                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 5                                 | infilt                    | N/A       | 1                 | Variable infiltration curve parameter (binfilt)                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 6                                 | Ds                        | fraction  | 1                 | Fraction of Dsmax where non-linear baseflow begins                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 7                                 | Dsmax                     | mm/day    | 1                 | Maximum velocity of baseflow                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 8                                 | Ws                        | fraction  | 1                 | Fraction of maximum soil moisture where non-linear baseflow occurs                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 9                                 | c                         | N/A       | 1                 | Exponent used in baseflow curve, normally set to 2                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 10 : (Nlayer+9)                   | expt                      | N/A       | Nlayer            | Exponent n (`=3+2/lambda`) in Campbell's eqn for hydraulic conductivity, HBH 5.6 (where lambda = soil pore size distribution parameter). Values should be `> 3.0.` |
| (Nlayer+10):(2\*Nlayer+9)          | Ksat                      | mm/day    | Nlayer            | Saturated hydrologic conductivity                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| (2\*Nlayer+10):(3\*Nlayer+9)        | phi_s                     | mm/mm     | Nlayer            | Soil moisture diffusion parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| (3\*Nlayer+10):(4\*Nlayer+9)        | init_moist                | mm        | Nlayer            | Initial layer moisture content                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| (4\*Nlayer+10)                     | elev                      | m         | 1                 | Average elevation of grid cell                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| (4\*Nlayer+11):(5\*Nlayer+10)       | depth                     | m         | Nlayer            | Thickness of each soil moisture layer                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| <font color="#ff0000"> (5\*Nlayer+11) </font> | <font color="#ff0000"> avg_T </font>| <font color="#ff0000"> C </font> | <font color="#ff0000"> 1 </font> | <font color="#ff0000"> Average soil temperature, used as the bottom boundary for soil heat flux solutions </font> |
| <font color="#ff0000"> (5\*Nlayer+12 </font> | <font color="#ff0000"> dp </font> | <font color="#ff0000"> m </font> | <font color="#ff0000"> 1 </font> | <font color="#ff0000"> Soil thermal damping depth (depth at which soil temperature remains constant through the year, ~4 m) </font>|
| <font color="#800080"> (5\*Nlayer+13):(6\*Nlayer+12) </font> | <font color="#800080"> bubble </font> | <font color="#800080"> cm </font> | <font color="#800080"> Nlayer </font> | <font color="#800080"> Bubbling pressure of soil. Values should be > 0. </font>  |
| <font color="#ff0000"> (6\*Nlayer+13):(7\*Nlayer+12) </font> | <font color="#ff0000"> quartz </font> | <font color="#ff0000">  </font>   | <font color="#ff0000"> Nlayer </font> | <font color="#ff0000"> Quartz content of soil </font> |
| (7\*Nlayer+13):(8\*Nlayer+12)       | bulk_density              | kg/m3     | Nlayer            | Bulk density of soil layer                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| (8\*Nlayer+13):(9\*Nlayer+12)       | soil_density              | kg/m3     | Nlayer            | Soil particle density, normally 2685 kg/m<sup>3</sup>                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **(Optional)**                        | organic                   | fraction  | Nlayer            | Fraction of soil layer that is organic. If ORGANIC_FRACT is TRUE in the [global parameter file](GlobalParam.md), this variable must be included in the soil parameter file.  If ORGANIC_FRACT is FALSE then this variable must not appear in the soil parameter file. (release 4.1.2 and later) |
| **(Optional)**                        | bulk_dens_org             | kg/m3     | Nlayer            | Bulk density of organic portion of soil. If ORGANIC_FRACT is TRUE in the [global parameter file](GlobalParam.md), this variable must be included in the soil parameter file.  If ORGANIC_FRACT is FALSE then this variable must not appear in the soil parameter file. (release 4.1.2 and later)                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **(Optional)**                        | soil_dens_org             | kg/m3     | Nlayer            | Soil particle density of organic portion of soil, normally 1300 kg/m<sup>3</sup>. If ORGANIC_FRACT is TRUE in the [global parameter file](GlobalParam.md), this variable must be included in the soil parameter file. If ORGANIC_FRACT is FALSE then this variable must not appear in the soil parameter file. (release 4.1.2 and later)                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| (9\*Nlayer+13)                     | off_gmt                   | hours     | 1                 | Time zone offset from GMT. This parameter determines how VIC interprets sub-daily time steps relative to the model start date and time. <br><br>**NOTE: Important update in VIC 4.1.2:** <br><br>We have adopted the following convention for off_gmt: <li>An **off_gmt** value of `0` indicates that the model start date/time is relative to **Greenwich Mean Time (GMT)**. <li>An **off_gmt** value of (`grid_cell_longitude*24/360`) indicates that the model start date/time is relative to local time. <li>When outputting sub-daily results, VIC's output files are referenced to the model start date/time; therefore they are controlled by **off_gmt** (`off_gmt=0` means VIC results are referenced to GMT; `off_gmt=(grid_cell_longitude*24/360)` means VIC results are referenced to local time). <li>**Daily** supplied forcings are assumed to start/end at midnight in **local time**; the forcing start date/time is thus in **local time**. When VIC disaggregates daily forcings into sub-daily forcings, **off_gmt** will be used to determine the time lag between the start of the forcing's diurnal cycle and the start of the VIC simulation. <li>**Sub-daily** supplied forcings are assumed to occur relative to **the time zone indicated by off_gmt**. Therefore, if VIC outputs these sub-daily forcings, they will occur at the exact same time of day as in the input files. <br><br>Therefore, if mixing daily and sub-daily forcing inputs, it is important that any sub-daily forcing inputs be shifted as necessary to be in the time zone indicated by off_gmt.                                                                                                                                                                                                                                                                                                                       |
| (9\*Nlayer+14):(10\*Nlayer+13)      | Wcr_FRACT                 | fraction  | Nlayer            | Fractional soil moisture content at the critical point (~70% of field capacity) (fraction of maximum moisture)                                                                                                                                                                                                                                                                                                                                                                                        |
| (10\*Nlayer+14):(11\*Nlayers+13)    | Wpwp_FRACT                | fraction  | Nlayer            | Fractional soil moisture content at the wilting point (fraction of maximum moisture)                                                                                                                                                                                                                                                                                                                                                                                                                  |
| (11\*Nlayer+14)                    | rough                     | m         | 1                 | Surface roughness of bare soil                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| (11\*Nlayer+15)                    | snow_rough                | m         | 1                 | Surface roughness of snowpack                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| (11\*Nlayer+16)                    | annual_prec               | mm        | 1                 | Average annual precipitation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| (11\*Nlayer+17):(12\*Nlayer+16)     | resid_moist               | fraction  | Nlayer            | Soil moisture layer residual moisture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| <font color="#800080"> (12\*Nlayer+17) </font> | <font color="#800080"> fs_active </font> | <font color="#800080"> 1 or 0 </font> | <font color="#800080"> 1 </font> | <font color="#800080"> If set to 1, then frozen soil algorithm is activated for the grid cell. A 0 indicates that frozen soils are not computed even if soil temperatures fall below 0C. </font> |
| **(Optional)**                        | frost_slope               | C         | 1                 | Slope of uniform distribution of soil temperature (if SPATIAL_FROST == TRUE in the [global parameter file](GlobalParam.md)).                                                                                                                                                                                                                                                                                                                                                                                            |
| **(Optional)**                        | max_snow_distrib_slope    | m         | 1                 | Maximum slope of the snow depth distribution. This is only used if SPATIAL_SNOW == TRUE in the [global parameter file](GlobalParam.md).  <br><br>This parameter should be set to twice the spatial average snow depth at which coverage == 1.0. In other words, if we define depth_thresh to be the minimum spatial average snow depth below which coverage < 1.0, then max_snow_distrib_slope = 2*depth_thresh.  <br><br>*NOTE*: Partial snow coverage is **only** computed when the snow pack has started **melting** and the `spatial average snow pack depth <= max_snow_distrib_slope/2`. During the accumulation season, coverage is 1.0. Even after the pack has started melting and `depth <= max_snow_distrib_slope/2`, new snowfall resets coverage to 1.0, and the previous partial coverage is stored. Coverage remains at 1.0 until the new snow has melted away, at which point the previous partial coverage is recovered.     |
| **(Optional)**                        | July_Tavg                 | C         | 1                 | Average July air temperature, used for treeline computations (required if [COMPUTE_TREELINE](GlobalParam.md#COMPUTE_TREELINE) == TRUE in the [global parameter file](GlobalParam.md)).                                                                                                                                                                                                                                                                                                                                                                     |

Note: if BASEFLOW is set to NIJSSEN2001 in the [global parameter file](GlobalParam.md), VIC will interpret the baseflow parameters Ds, Dsmax, Ws, and c to be the alternative baseflow parameters D1, D2, D3, and D4.</font="red">

## Example Soil Parameter File:

Example Soil Parameter File: VIC 4.0.5/4.0.6 Water Balance

    #RUN    GRID    LAT LNG INFILT  Ds  Ds_MAX  Ws  C   EXPT_1  EXPT_2  EXPT_3  Ksat_1  Ksat_2  Ksat_3  PHI_1   PHI_2   PHI_3   MOIST_1 MOIST_2 MOIST_3 ELEV    DEPTH_1 DEPTH_2 DEPTH_3 AVG_T   DP  BUBLE1  BUBLE2  BUBLE3  QUARZ1  QUARZ2  QUARZ3  BULKDN1 BULKDN2 BULKDN3 PARTDN1 PARTDN2 PARTDN3 OFF_GMT WcrFT1  WcrFT2  WcrFT3  WpFT1   WpFT2   WpFT3   Z0_SOIL Z0_SNOW PRCP    RESM1   RESM2   RESM3   FS_ACTV JULY_TAVG
    1   7   43.739  -92.4.0 0.010   1.e-4   3.05    0.93    2   4.0 4.0 4.0 250.0   250.0   250.0   -999    -999    -999    0.4 0.4 0.4 306.3   0.1 6.90    2.000   14.0    4.0 75.0    75.0    75.0    0.24    0.24    0.24    1306    1367    1367    2650    2650    2650    -6  0.330   0.330   0.330   0.133   0.133   0.133   0.001   0.010   500 0.02    0.02    0.02    1   18.665
