Difference between revisions of "Sacramento SMA"
(→Implementation) |
|||
(38 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | The SMA project/module provides a soil moisture model for the Soil Moisture Estimator tool and implements a custom C interface to the National Weather Service | + | The SMA project/module provides a back-end soil moisture model for the [https://www.agrineer.org/wiki/index.php?title=Soil_Moisture_Estimator Soil Moisture Estimator] tool and implements a custom C interface to the National Weather Service-University of Arizona Sacramento Soil Moisture Accounting (SMA) model. |
== SMA Module Files == | == SMA Module Files == | ||
− | There are four C programs which make up the module.<br> | + | There are four C programs which make up the module.<br><br> |
− | The first two | + | The first two are interface contributions: |
− | + | * ini.c - reads ini style input variables, from [https://github.com/benhoyt/inih Ben Hoyt] | |
− | + | * sma.c - interfaces between the SME and the SMA model, from Agrineer | |
The next two implement the actual model: | The next two implement the actual model: | ||
− | + | * sacramento_state.c (a version of sac_sma.c) | |
− | + | * fland1.c | |
and were originally part of the MOSCEM package developed at University of Arizona by Yuqiong Liu and others. Permission to use and distribute these files was granted by Professor Hoshin Gupta (University of Arizona) on 2009-08-28. | and were originally part of the MOSCEM package developed at University of Arizona by Yuqiong Liu and others. Permission to use and distribute these files was granted by Professor Hoshin Gupta (University of Arizona) on 2009-08-28. | ||
− | The last two programs were originally downloaded from Google's cached copy of http://info.science.uva.nl/ibed/research/Research_Fields/cbpg/software/code/moscem.0.tar.gz 2009-08-20 by Felix Andrews | + | The last two programs above were originally downloaded from Google's cached copy of http://info.science.uva.nl/ibed/research/Research_Fields/cbpg/software/code/moscem.0.tar.gz 2009-08-20 by Felix Andrews. |
− | For an R language version go to [http://hydromad.catchment.org Hydromad]. Many descriptive phrases and source code on the model | + | For an R language version go to [http://hydromad.catchment.org Hydromad]. Many descriptive phrases and source code on the model came from Hydromad. |
− | The program sacramento_state.c (sac_sma.c) was based on code from | + | The program sacramento_state.c (sac_sma.c) was based on code from the MOSCEM project and simplified by Felix Andrews <felix@nfrac.org> 2010-02-01. Adapted to return state by Joseph Guillaume 2013-10-24. |
− | simplified by Felix Andrews <felix@nfrac.org> 2010-02-01. Adapted to return state by Joseph Guillaume 2013-10-24 | + | |
− | The program fland1.c executes the SAC-SMA operation for one time period. | + | The program fland1.c executes the SAC-SMA operation for one time period. It was initially written in FORTRAN by Eric Anderson-HRL in April 1979. In 1993-94 Patrice O. Yapo rewrote the program in the C language. The transition from FORTRAN to C explains why the C programs use parameters by reference, an artifact from FORTRAN. |
== Implementation == | == Implementation == | ||
− | The SMA module is part of the SME project | + | The SMA module is part of the SME project which can be downloaded from [https://gitlab.com/agrineer/sme here]. The SMA module is in the "Sacramento" directory. |
− | The sma.c program can be run standalone. To create the sma executable, type "make" in the | + | The main sma.c program can be run standalone. To create the sma executable, type "make" in the "sacramento" directory. By default the executable is moved to its parent directory for use by sme.py. Modify the "makefile" to your preference. |
Usage: | Usage: | ||
Line 39: | Line 38: | ||
An example configuration file: | An example configuration file: | ||
− | [FILES] | + | [FILES] |
− | loads = /home/agrineer/sma/input/loads.csv | + | loads = /home/agrineer/sma/input/loads.csv |
− | soil = /home/agrineer/sma/input/soil.csv | + | soil = /home/agrineer/sma/input/soil.csv |
− | output = /home/agrineer/sma/ | + | output = /home/agrineer/sma/output/output.csv |
− | rain = /home/agrineer/sma/input/rain.csv | + | rain = /home/agrineer/sma/input/rain.csv |
− | irr = /home/agrineer/sma/input/irr.csv | + | irr = /home/agrineer/sma/input/irr.csv |
− | Note that when | + | Note that when the sme.py invokes the SMA module the SMA configuration file is constructed on the fly, based on SME data and configuration input files. Since the SMA is a backend module the SME, the user must specify the soil model and its parameter input files in the SME configuration file. |
+ | |||
+ | For example, to reference the SMA with parameters in the sme.py, the SME configuration file might have: | ||
+ | |||
+ | [SoilModel] | ||
+ | model = SMA | ||
+ | |||
+ | [SMA] | ||
+ | program = /home/agrineer/sme/sme/sma | ||
+ | soil = /home/agrineer/sme/tmp/soil.csv | ||
+ | rain = /home/agrineer/sme/tmp/rain.csv | ||
+ | irr = /home/agrineer/sme/tmp/irr.csv | ||
+ | |||
+ | The "loads" file (data) would be generated by the WRF model data and ETo calculations and then submitted to the SMA program. | ||
+ | |||
+ | Note that the web SME tool constructs the configuration file for the sme.py program as above. See the SME description [https://gitlab.com/agrineer/sme here] for more detail. | ||
==Input file format and variable description == | ==Input file format and variable description == | ||
+ | All input files are text based with comma separable variables (.csv). These files can be are read by spreadsheets for presentation and general analysis purposes. | ||
+ | |||
=== Atmospheric Loads === | === Atmospheric Loads === | ||
+ | The "loads" input file consists of a title line followed by value lines. Line values are comma separated (CSV) and the values are for date, precipitation, and ETc. Precipitation and ETc values are given in millimeters. For example,<br><br> | ||
+ | Date,P,E | ||
+ | 2018-01-02,0.00,1.0348 | ||
+ | 2018-01-03,0.00,0.8603 | ||
+ | 2018-01-04,0.00,0.8630 | ||
+ | . | ||
+ | . | ||
+ | . | ||
+ | |||
+ | Currently, comments cannot be placed above the title line. | ||
+ | Note that the precipitation values normally originate from the WRF model and can be overridden by local data input. | ||
+ | |||
=== Soil Attributes === | === Soil Attributes === | ||
+ | |||
+ | The "soil" input file contains comma separated values (CSV) consisting of just a title line and a value line. | ||
+ | |||
+ | The value line has values consisting of: | ||
+ | |||
+ | |||
+ | soil - given soil name (string) | ||
+ | |||
+ | comment - make a comment (string) | ||
+ | |||
+ | uztwm - upper layer (zone) tension water maximum capacity, mm. | ||
+ | The maximum volume of water (normalized to mm) held by the | ||
+ | upper zone between field capacity and the wilting point which can | ||
+ | be lost by direct evaporation and transpiration from soil. This | ||
+ | storage is filled before any water in the upper zone is transferred | ||
+ | to other storages. Use field capacity and wilt point water content | ||
+ | ratios to determine normalized volume (mm) for some depth. ie. | ||
+ | (Ofc - Owp)*depth = uztwm (max et storage capacity). | ||
+ | |||
+ | uzfwm - upper layer free water maximum capacity, mm. This storage is the | ||
+ | source of water for interflow and the driving force for | ||
+ | transferring water to deeper depths. | ||
+ | |||
+ | uzk - interflow depletion rate from the upper layer free water storage, | ||
+ | uzfwm per day. That is, lateral drainage rate of upper zone | ||
+ | free water expressed as a fraction of contents per day. | ||
+ | |||
+ | pctim - permanent impervious area fraction of the catchment which | ||
+ | produces impervious runoff during low flow conditions. | ||
+ | |||
+ | adimp - maximum fraction of an additional impervious area due to | ||
+ | saturation. That is, the additional fraction of the catchment | ||
+ | which exhibits impervious characteristics when the catchment's | ||
+ | tension water requirements are met. | ||
+ | |||
+ | perc - maximum percolation rate coefficient (from upper zone free | ||
+ | water into the lower zone). | ||
+ | |||
+ | rexp - shape parameter of the percolation curve. An exponent | ||
+ | determining the rate of change of the percolation | ||
+ | rate with changing lower zone water contents. | ||
+ | |||
+ | lztwm - lower layer tension water maximum capacity, mm. Water from | ||
+ | this store can only be removed through transpiration. | ||
+ | |||
+ | lzfsm - lower layer supplemental free water maximum capacity, mm. | ||
+ | The maximum volume from which supplemental baseflow can be drawn. | ||
+ | |||
+ | lzfpm - lower layer primary free water maximum capacity, mm. The maximum | ||
+ | capacity from which primary base flow can be drawn. | ||
+ | |||
+ | lzsk - depletion rate of the lower layer supplemental | ||
+ | free water storage, lzfsm per day. That is, lateral drainage rate | ||
+ | of lower zone supplemental free water expressed as | ||
+ | a fraction of contents per day. | ||
+ | |||
+ | lzpk - depletion rate of the lower layer primary free water storage, | ||
+ | lzfpm, per day. That is, lateral drainage rate of lower zone | ||
+ | primary free water expressed as a fraction of contents per day. | ||
+ | |||
+ | pfree - percolation fraction that goes directly to the lower layer free | ||
+ | water storages. Direct percolation fraction from upper to | ||
+ | lower zone free water (the percentage of percolated | ||
+ | water which is available to the lower zone free water | ||
+ | before all lower zone tension water deficiencies are satisfied). | ||
+ | |||
+ | uztwc_0 - initial upper zone tension water content as proportion of ‘uztwm’ | ||
+ | |||
+ | uzfwc_0 - initial upper zone free water content as proportion of ‘uzfwm' | ||
+ | |||
+ | lztwc_0 - initial lower zone tension water content as proportion of ‘lztwm’ | ||
+ | |||
+ | lzfsc_0 - initial lower zone free water secondary as proportion of ‘lzfsm’ | ||
+ | |||
+ | lzfpc_0 - initial lower zone free water primary as proportion of ‘lzfpm’ | ||
+ | |||
+ | adimc_0 - initial additional impervious flow store, as proportion of ‘uztwm+lztwm’ | ||
+ | |||
+ | |||
+ | Value ranges and default values from different studies: | ||
+ | |||
+ | | Blasone et. al.(2008) | Surrgo (2004) | default | units | ||
+ | uztwm | 1-150 | 10-300 | 50.1 | mm | ||
+ | uzfwm | 1-150 | 5-150 | 40.2 | mm | ||
+ | uzk | 0.1-0.5 | 0.10-0.75 | 0.1 | frac/day | ||
+ | pctim | 0.000001-0.1 | N/A | 0.000001 | none | ||
+ | adimp | 0-0.4 | N/A | 0.0 | none | ||
+ | zperc | 1-250 | 5-350 | 1.0 | none | ||
+ | rexp | 0-5 | 1-5 | 0.0 | none | ||
+ | lztwm | 1-500 | 10-500 | 250.0 | mm | ||
+ | lzfsm | 1-1000 | 5-400 | 500.0 | mm | ||
+ | lzfpm | 1-1000 | 10-1000 | 500.0 | mm | ||
+ | lzsk | 0.01-0.25 | 0.01-0.35 | 0.01 | frac/day | ||
+ | lzpk | 0.0001-0.25 | 0.001-0.05 | 0.1 | frac/day | ||
+ | pfree | 0-0.6 | 0.0-0.8 | 0.1 | none | ||
+ | |||
+ | Soil input file example: | ||
+ | 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. | ||
+ | |||
=== Local Rain Events === | === Local Rain Events === | ||
+ | The input file "rain" consists of a title line and value lines with comma separated values (CSV). The values are a date followed by the value in millimeters. Use this file to give local rain events. For example, | ||
+ | |||
+ | Date,Rain (mm) | ||
+ | 2018-01-14,11.67 | ||
+ | 2018-01-15,17.27 | ||
+ | 2018-01-17,0.73 | ||
+ | . | ||
+ | . | ||
+ | . | ||
+ | Providing this file will override the WRF rain values given in the "loads" input file. | ||
+ | |||
=== Irrigation Events === | === Irrigation Events === | ||
+ | The input file "irr" consists of a title line and value lines with comma separated values (CSV). The values are a date followed by the value in millimeters. Use this file to give irrigation dates. For example, | ||
− | + | Date,Irrigation (mm) | |
− | + | 2018-01-10,10.0 | |
− | - | + | 2018-01-20,10.0 |
− | - | + | 2018-01-30,10.0 |
− | + | . | |
− | + | . | |
+ | . | ||
+ | |||
+ | == Output File == | ||
+ | The output file has a title line followed by value lines. All lines are in CSV format. | ||
+ | |||
+ | The title line looks like: | ||
+ | Date,U,uztwc,uzfwc,lztwc,lzfsc,lzfpc,adimc,sett,se1,se3,se4,se5,roimp,sdro,ssur,sif,bfp,bfs,bfcc | ||
+ | |||
+ | A value line consists of: | ||
+ | Date - daily time stamp | ||
+ | U - the simulated effective rainfall (“total channel inflow”) | ||
+ | uztwc - upper zone tension water content | ||
+ | uzfwc - upper zone free water content | ||
+ | lztwc - lower zone tension water content | ||
+ | lzfsc - lower zone free secondary water content | ||
+ | lzfpc - lower zone free primary water content | ||
+ | adimc - tension water contents of the additional impervious area | ||
+ | sett - cumulative total evapotranspiration | ||
+ | se1 - cumulative evapotranspiration from upper zone tension water | ||
+ | se3 - cumulative evapotranspiration from lower zone tension water | ||
+ | se4 - cumulative evapotranspiration | ||
+ | se5 - cumulative evapotranspiration from riparian zone | ||
+ | roimp - runoff from impervious area | ||
+ | sdro - six hour sum of runoff | ||
+ | ssur - surface runoff | ||
+ | sif - interflow | ||
+ | bfp - primary baseflow | ||
+ | bfs - secondary baseflow | ||
+ | bfcc - channel baseflow (bfp+bfs) | ||
== Paper References == | == Paper References == | ||
− | + | Some links describing the Sacramento Soil Moisture Accounting model: | |
[http://www.nws.noaa.gov/oh/hrl/calb/calibration1102/calb_report_section7-8.pdf calb_report7-8.pdf] | [http://www.nws.noaa.gov/oh/hrl/calb/calibration1102/calb_report_section7-8.pdf calb_report7-8.pdf] |
Latest revision as of 14:57, 28 January 2019
The SMA project/module provides a back-end soil moisture model for the Soil Moisture Estimator tool and implements a custom C interface to the National Weather Service-University of Arizona Sacramento Soil Moisture Accounting (SMA) model.
Contents
SMA Module Files
There are four C programs which make up the module.
The first two are interface contributions:
* ini.c - reads ini style input variables, from Ben Hoyt * sma.c - interfaces between the SME and the SMA model, from Agrineer
The next two implement the actual model:
* sacramento_state.c (a version of sac_sma.c) * fland1.c
and were originally part of the MOSCEM package developed at University of Arizona by Yuqiong Liu and others. Permission to use and distribute these files was granted by Professor Hoshin Gupta (University of Arizona) on 2009-08-28.
The last two programs above were originally downloaded from Google's cached copy of http://info.science.uva.nl/ibed/research/Research_Fields/cbpg/software/code/moscem.0.tar.gz 2009-08-20 by Felix Andrews.
For an R language version go to Hydromad. Many descriptive phrases and source code on the model came from Hydromad.
The program sacramento_state.c (sac_sma.c) was based on code from the MOSCEM project and simplified by Felix Andrews <felix@nfrac.org> 2010-02-01. Adapted to return state by Joseph Guillaume 2013-10-24.
The program fland1.c executes the SAC-SMA operation for one time period. It was initially written in FORTRAN by Eric Anderson-HRL in April 1979. In 1993-94 Patrice O. Yapo rewrote the program in the C language. The transition from FORTRAN to C explains why the C programs use parameters by reference, an artifact from FORTRAN.
Implementation
The SMA module is part of the SME project which can be downloaded from here. The SMA module is in the "Sacramento" directory.
The main sma.c program can be run standalone. To create the sma executable, type "make" in the "sacramento" directory. By default the executable is moved to its parent directory for use by sme.py. Modify the "makefile" to your preference.
Usage:
sma -c config_file
Where the configuration file holds "ini" parameters for:
loads - Filepath to atmospheric loads (precip and et) data, described below. soil - Filepath to soil attribute data, described below. output - Filepath to output report, described below. rain - Optional filepath for local rain input data. Overrides climate model rain data. irr - Optional filepath for irrigation events. Events count as precipitation.
An example configuration file:
[FILES] loads = /home/agrineer/sma/input/loads.csv soil = /home/agrineer/sma/input/soil.csv output = /home/agrineer/sma/output/output.csv rain = /home/agrineer/sma/input/rain.csv irr = /home/agrineer/sma/input/irr.csv
Note that when the sme.py invokes the SMA module the SMA configuration file is constructed on the fly, based on SME data and configuration input files. Since the SMA is a backend module the SME, the user must specify the soil model and its parameter input files in the SME configuration file.
For example, to reference the SMA with parameters in the sme.py, the SME configuration file might have:
[SoilModel] model = SMA [SMA] program = /home/agrineer/sme/sme/sma soil = /home/agrineer/sme/tmp/soil.csv rain = /home/agrineer/sme/tmp/rain.csv irr = /home/agrineer/sme/tmp/irr.csv
The "loads" file (data) would be generated by the WRF model data and ETo calculations and then submitted to the SMA program.
Note that the web SME tool constructs the configuration file for the sme.py program as above. See the SME description here for more detail.
Input file format and variable description
All input files are text based with comma separable variables (.csv). These files can be are read by spreadsheets for presentation and general analysis purposes.
Atmospheric Loads
The "loads" input file consists of a title line followed by value lines. Line values are comma separated (CSV) and the values are for date, precipitation, and ETc. Precipitation and ETc values are given in millimeters. For example,
Date,P,E 2018-01-02,0.00,1.0348 2018-01-03,0.00,0.8603 2018-01-04,0.00,0.8630 . . .
Currently, comments cannot be placed above the title line. Note that the precipitation values normally originate from the WRF model and can be overridden by local data input.
Soil Attributes
The "soil" input file contains comma separated values (CSV) consisting of just a title line and a value line.
The value line has values consisting of:
soil - given soil name (string)
comment - make a comment (string)
uztwm - upper layer (zone) tension water maximum capacity, mm. The maximum volume of water (normalized to mm) held by the upper zone between field capacity and the wilting point which can be lost by direct evaporation and transpiration from soil. This storage is filled before any water in the upper zone is transferred to other storages. Use field capacity and wilt point water content ratios to determine normalized volume (mm) for some depth. ie. (Ofc - Owp)*depth = uztwm (max et storage capacity).
uzfwm - upper layer free water maximum capacity, mm. This storage is the source of water for interflow and the driving force for transferring water to deeper depths.
uzk - interflow depletion rate from the upper layer free water storage, uzfwm per day. That is, lateral drainage rate of upper zone free water expressed as a fraction of contents per day.
pctim - permanent impervious area fraction of the catchment which produces impervious runoff during low flow conditions.
adimp - maximum fraction of an additional impervious area due to saturation. That is, the additional fraction of the catchment which exhibits impervious characteristics when the catchment's tension water requirements are met.
perc - maximum percolation rate coefficient (from upper zone free water into the lower zone).
rexp - shape parameter of the percolation curve. An exponent determining the rate of change of the percolation rate with changing lower zone water contents.
lztwm - lower layer tension water maximum capacity, mm. Water from this store can only be removed through transpiration.
lzfsm - lower layer supplemental free water maximum capacity, mm. The maximum volume from which supplemental baseflow can be drawn.
lzfpm - lower layer primary free water maximum capacity, mm. The maximum capacity from which primary base flow can be drawn.
lzsk - depletion rate of the lower layer supplemental free water storage, lzfsm per day. That is, lateral drainage rate of lower zone supplemental free water expressed as a fraction of contents per day.
lzpk - depletion rate of the lower layer primary free water storage, lzfpm, per day. That is, lateral drainage rate of lower zone primary free water expressed as a fraction of contents per day.
pfree - percolation fraction that goes directly to the lower layer free water storages. Direct percolation fraction from upper to lower zone free water (the percentage of percolated water which is available to the lower zone free water before all lower zone tension water deficiencies are satisfied).
uztwc_0 - initial upper zone tension water content as proportion of ‘uztwm’
uzfwc_0 - initial upper zone free water content as proportion of ‘uzfwm'
lztwc_0 - initial lower zone tension water content as proportion of ‘lztwm’
lzfsc_0 - initial lower zone free water secondary as proportion of ‘lzfsm’
lzfpc_0 - initial lower zone free water primary as proportion of ‘lzfpm’
adimc_0 - initial additional impervious flow store, as proportion of ‘uztwm+lztwm’
Value ranges and default values from different studies:
| Blasone et. al.(2008) | Surrgo (2004) | default | units uztwm | 1-150 | 10-300 | 50.1 | mm uzfwm | 1-150 | 5-150 | 40.2 | mm uzk | 0.1-0.5 | 0.10-0.75 | 0.1 | frac/day pctim | 0.000001-0.1 | N/A | 0.000001 | none adimp | 0-0.4 | N/A | 0.0 | none zperc | 1-250 | 5-350 | 1.0 | none rexp | 0-5 | 1-5 | 0.0 | none lztwm | 1-500 | 10-500 | 250.0 | mm lzfsm | 1-1000 | 5-400 | 500.0 | mm lzfpm | 1-1000 | 10-1000 | 500.0 | mm lzsk | 0.01-0.25 | 0.01-0.35 | 0.01 | frac/day lzpk | 0.0001-0.25 | 0.001-0.05 | 0.1 | frac/day pfree | 0-0.6 | 0.0-0.8 | 0.1 | none
Soil input file example: 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.
Local Rain Events
The input file "rain" consists of a title line and value lines with comma separated values (CSV). The values are a date followed by the value in millimeters. Use this file to give local rain events. For example,
Date,Rain (mm) 2018-01-14,11.67 2018-01-15,17.27 2018-01-17,0.73 . . .
Providing this file will override the WRF rain values given in the "loads" input file.
Irrigation Events
The input file "irr" consists of a title line and value lines with comma separated values (CSV). The values are a date followed by the value in millimeters. Use this file to give irrigation dates. For example,
Date,Irrigation (mm) 2018-01-10,10.0 2018-01-20,10.0 2018-01-30,10.0 . . .
Output File
The output file has a title line followed by value lines. All lines are in CSV format.
The title line looks like:
Date,U,uztwc,uzfwc,lztwc,lzfsc,lzfpc,adimc,sett,se1,se3,se4,se5,roimp,sdro,ssur,sif,bfp,bfs,bfcc
A value line consists of:
Date - daily time stamp U - the simulated effective rainfall (“total channel inflow”) uztwc - upper zone tension water content uzfwc - upper zone free water content lztwc - lower zone tension water content lzfsc - lower zone free secondary water content lzfpc - lower zone free primary water content adimc - tension water contents of the additional impervious area sett - cumulative total evapotranspiration se1 - cumulative evapotranspiration from upper zone tension water se3 - cumulative evapotranspiration from lower zone tension water se4 - cumulative evapotranspiration se5 - cumulative evapotranspiration from riparian zone roimp - runoff from impervious area sdro - six hour sum of runoff ssur - surface runoff sif - interflow bfp - primary baseflow bfs - secondary baseflow bfcc - channel baseflow (bfp+bfs)
Paper References
Some links describing the Sacramento Soil Moisture Accounting model:
Plus many more by searching for "Sacramento Soil Moisture Accounting".