Soil Moisture Estimator

From Wiki
Jump to: navigation, search

The Soil Moisture Estimator (SME) is a numerically based program which estimates water usage on a crop basis. It is designed for world-wide coverage, currently at 3km resolution, with customization for local crops, soil, irrigation, and rain events.

Soil Moisture Estimator application.


Our intent is to create a community based, hydrological atmosphere-soil model platform that is large scale, yet customizable for local environments and crops, with the aim to improve agricultural water management.

  • Our short term goal is to introduce to interested parties the computational platform that we have developed.
 - The SME is open-sourced and therefore easily reviewed by users and developers for errors and improvements.
  • Our intermediate goal is to develop reliable methods to integrate soil moisture sensor data into the computational platform.
 - This includes developing and integrating open-source moisture sensor and acquisition stations.
  • Our long-term goal is to apply lessons learned whereby parameters can be adjusted for local conditions.
 - Estimating soil moisture numerically is a difficult task. Our approach is to lay a theoretical baseline and then heuristically adjust according to local conditions.

The SME is available as a web application or as a stand alone, command line, program which can be downloaded here and used on GNU/Linux systems.

Note: This is an educational platform disseminating research ideas and applications. We hope that the user can benefit from the software and hardware sources provided but we do not take any responsibility for the consequences of decisions based on data released or on the results given in our applications. See the footer disclaimer for more information.


The Soil Moisture Estimator (SME) package contains two components.

One component is the "" program which coordinates the required data for the other component, a specified soil moisture model, which is modular.

We initiate this package with the well-studied Sacramento Soil Moisture Accounting (SMA) method as the back-end soil moisture model. Other soil moisture models will be available in the future.

Implementation Stream

Briefly, the implementation stream looks like this:

Modelled Weather -> Large Scale ETo -> Local ETc/Soil/Rain/Irr -> Soil Moisture

This initial release uses reanalyzed Global Forecast System (GFS) data as input to the Weather, Research and Forecast (WRF) model to produce modelled, hindcast weather data; although other models and input data can be used, including forecast data. Current spatial resolution is about 3km.

The output data from the WRF model are used to calculate standard evapotranspiration (ETo) according to United Nation's Food and Agriculture Organization (FAO) guidelines, over all of a sector's pixels on an hourly basis, for a given period of days. Then, the program calculates the evapotranspiration value, ETc, over the growing season for a specified location, on a daily basis accumulated hourly. The ETc values are reported together with modelled rain events, irrigation events, grow degree days, and temporal crop coefficients.

The reported atmospheric load data (precip/irrigation and ETc) are then used in soil moisture model to calculate water content of the soil over the given period of days. Modelled rain events can be overridden with local data.

ETc FAO Implemention

We implement the FAO guidelines in calculating ETc. An introductory chapter can be found here and followed by a more in-depth chapter here. The single crop model is currently employed.

The procedure is straight forward, a (crop) coefficient is applied to the ETo value, accumulated hourly throughout the day, for the growing season:



[math]ET_c[/math] is the crop evapotranspiration [math][mm~hour^{-1}][/math],
[math]K_{ci}[/math] is the crop coefficient at some time i,
[math]ET_o[/math] is the reference evapotranspiration [math][mm~hour^{-1}][/math].

Crop coefficients can be described as a curve over time or, in the case of the FAO guidelines, as discrete values over stages of the growing season. Following FAO, we use four stages of coefficients: initial, development, middle, and late with associated day intervals. A complete description of crop input file is given below.

Deriving the correct coefficients is key to accurate estimates, and this is a difficult task as a myriad of variables are at play, eg. soil physics, micro-climates, cultivars, spacing, etc. As above, our intent is to create a platform which can be used to converge on working coefficients for local conditions. However, this requires ground sensor data for comparison purposes and so community participation is necessary for local adjustments.

With community participation we hope to compile working coefficients for local areas. An excellent resource for crop coefficients is in the FAO paper referenced above and can serve as starting point for local implementation.

Backend Soil Moisture Models

The Soil Moisture Accounting (SMA) model is currently implemented in this release and delivers moisture content estimates in the soil at two levels (horizons A and B). It is part of the SME package, available here

How to run

For an estimate of soil water content at different soil levels users can specify the location, run dates, crop, and soil types, in addition to local rain and irrigation events. Currently, with the SMA module there are just two soil levels, corresponding to the "A" (topsoil) and "B" (subsoil) horizons.

SME application with numbered sections

Guide to SME application.

Input section

Location (decimal degrees)

 yellow #1 in the above image

Note: currently about 1/3 of the geographical area of the contiguous 48 states is available for processing. See WRF Hindcast for current operational sectors. If the provided latitude and longitude values are not within the active sectors an error message will appear stating 'Cannot find given location in active sectors'.

The latitude and longitude values of the area of interest, in decimal form. Example: 32.25049, -106.74516

    latitude  32.25049
    longitude  -106.74516

Dates (yyyymmdd)

 yellow #2 in the above image

    planted date crop planted
start run application from this start date
end run application to this end date

Note: if you are using your own irrigation and/or rain files (see #6 and #8 ) be sure their dates sync up with the 'start' and 'end' dates here.

Save location and dates

 yellow #3 in the above image

If you wish to save the shown Location & Dates values to a file (to quickly load at a later time) enter a file name for the file (ex: area3April) and then click 'Save'. Follow your computer's directions to save the file. You may create and save as many files as you like.

Load location and dates

 yellow #4 in the above image

To load a previously created and saved Location and Dates file click 'Load', find and open the file you want to use.


 yellow #5 in the above image

For more precise results or experimentation you may create and save your own 'Crop' files. These files must be 'csv' files.

See "Create 'csv' files" below.

If you choose not to use your own 'Crop' file a default file will be used. Here are the attribute names and values for the default 'Crop' file:

crop -> bean; kc ini -> 0.15; kc mid -> 1.19; kc end -> 0.35; ln ini -> 25; ln dev -> 25; ln mid -> 30; ln late -> 20; gdd basetemp -> 5.1; gdd uppertemp -> 30.5; wilt point -> 10.7;


 yellow #6 in the above image

If you irrigate you may create and save your own 'Irrigation' files (See "Create 'csv' files" below). To use one of your own 'Irrigation' files click on the 'Load' button and open the desired file. The name of the file you chose will be listed to the right of the 'Load' button. The irrigation values are added to the precipitation/rain values.

If you do not use your own 'Irrigation' file the application defaults to no irrigation.


The soil input file depends on the backend soil program. For the Sacramento SMA program

 yellow #7 in the above image

To make and save your own 'Soil' files see "Create 'csv' files" below.

If you choose not to use your own 'Soil' file a default file will be used for demonstration purposes only. Here are the attribute names and values for the default 'Soil' file:

soil -> soil_default; comment -> demo purposes; uztwm -> 50.1; uzfwm -> 40.2; uzk -> 0.1; pctim -> 0.000001; adimp -> 0.0; zperc -> 1.0; rexp -> 0.0; lztwm -> 250.0; lzfsm -> 500.0; lzfpm -> 500.0; lzsk -> 0.01; lzpk -> 0.1; pfree -> 0.1; uztwc_0 -> 0.5; uzfwc_0 -> 0.5; lztwc_0 -> 0.5; lzfsc_0 -> 0.5; lzfpc_0 -> 0.5; adimc_0 -> 0.5;


 yellow #8 in the above image

The data we use from the Weather Research and Forecasting program includes daily precipitation data. It is accurate in a general way, but for a more precise run of the SME application you can provide your own rain values.

See "Create 'csv' files" below. The rain values from this file will replace the rain values from the WRF data.

If you do not use your own 'Rain' file the application defaults to the WRF rain data.

Create 'csv' files

If your going to use your own files for more precise values on crop, soil, irrigation and rain data the files must be in the so-called 'csv' (comma separated values) format. There are a good number of ways to create csv files, such as using vi, Notepad or Excel. See How to Create a CSV file and/or this other How to Create a CSV file.

Note that if you are creating a csv file directly, not through Excel, etc., it's easier to use a text editor such as vi or Notepad and not a word processor, and do not end the last line of the file with an 'Enter', just save the file as is.

You may create, save and use as many as you like of each of the 4 files. To use one of your own files click the 'Load' button and open the file of interest. The name of the file you chose will be listed to the right of the 'Load' button.

Below are the formats for each of the 4 files. The first row contains the 'header' elements and the next row(s) is an example of a data row(s).

Crop csv format:

Crop csv format

Irrigation csv format: the irrigation values are millimeters, mm.

Irrigation csv format

Soil csv format:

soil,comment,uztwm,uzfwm,uzk,pctim,adimp,zperc,rexp,lztwm,lzfsm,lzfpm,lzsk,lzpk,pfree, uztwc_0,uzfwc_0,lztwc_0,lzfsc_0,lzfpc_0,adimc_0

soil_default,demo purposes,50.1,40.2,0.1,0.000001,0.0,1.0,0.0,250.0,500.0,500.0,0.01,0.1,0.1, 0.5,0.5,0.5,0.5,0.5,0.5

Rain csv format: the rain values are millimeters, mm.

Rain csv format


 yellow #9 in the above image

Run the application with the provided input values.

Download results checkbox: activate this checkbox if you wish to receive a .zip file which contains files of data on your run and its results. In effect these are 'hardcopies' of a particular run of the application. For example, the included 'sme.log' file is a text file which contains the same data as the 'Text report' (yellow #14).

Follow your computer's instructions to save the file. Write down the name of the file because it can be a real doozy to recall (ex: After it is saved you will need to 'extract' the contents of the .zip file.

Output section

6 images: ETo and Precipitation

 yellow #10 in the above image

There are 2 image display areas. The left one is for ETo (evapotranspiration) data, the right one for Precipitation data. Both have 3 tabs for a total of 6 available images. All 6 images are 171 x 171 pixels in size but the resolution of each pixel varies in each of the tabs.

    3.3km  each pixel in this image represents an area approximately 3.3 km by 3.3 km.
    10km   each pixel in this image represents an area approximately 10 km by 10 km.
    30km   each pixel in this image represents an area approximately 30 km by 30 km.

Clicking on the '+' in the image will 'zoom-in' the image.

Clicking on the '-' in the image will 'zoom-out' the image.

If your mouse has a wheel you can use it to zoom in and out.

Clicking and holding down the left button on the mouse enables moving the image.

Clicking on the 'house' in the image will restore the image to its initial display size and position.

In the ETo 3.3km image you should see a small blinking red square; in the Precipitation 3.3km image there is a small blinking black square. Your latitude and longitude of interest will be inside this square. Use the '+' sign or the wheel on your mouse to zoom in. Move the mouse around inside the square until the latitude and longitude values shown in #11 approximate the values you entered in #1 for latitude and longitude. It is unlikely they will match exactly, a small disappointing aspect of the display software. Note that the 'Text report' (yellow #14) has the exact latitude and longitude.

If you don't see the small blinking red or black square it's because the underlying or surrounding area is the same or similar color. In this case move the mouse around in the image and look at the latitude and longitude values displayed in #11 until you have homed in on the desired area, then zoom in, etc.

Latitude, Longitude, ETo value; Latitude, Longitude, Precipitation value

 yellow #11 in the above image

Each pixel of a displayed image (171 x 171 pixels = 29,241 total pixels per image) has values representing the pixel's latitude, longitude, and the calculated ETo or Precipitation values. Move your mouse over the image and watch #11 to see the results.

Plot of soil UPPER layer water content for dates provided

 yellow #12 in the above image

Plot of soil LOWER layer water content for dates provided

 yellow #13 in the above image

Text report

 yellow #14 in the above image

Text description of the SME run and its results.