In jonaslenz/toolbox.e3d: Toolbox for the soil erosion modeling tool EROSION-3D

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

knitr::opts_chunk$set(
  echo = TRUE
)

The R wrapper package toolbox.e3d was created to perform often occurring tasks done with the soil erosion model EROSION-3D in an easy usable and reproducible way. It requires a licensed EROSION-3D installation on a Windows system. A download link and license conditions for this software are available from Geognostics (http://bodenerosion.com/e3d_demo.html).

EROSION-3D is designed as software with Graphical User Interface (GUI) with limited command-line support introduced in version 3.15. The toolbox.e3d uses only the command-line interaction, for fully reproducible work. Each manual change in modeling is seen as non-reproducible or at least failure-prone [@gmd_executive_editors_editorial_2019].

The toolbox.e3d was developed with the 32-bit EROSION-3D version 3.2.0.9. As the command-line interaction was sparsely used up to now, several functions may not work with older versions of EROSION-3D.

Command-line interaction with EROSION-3D

There are three basic commands to run EROSION-3D from command-line [@von_werner_erosion-3d_2007]:

• '/c' for calculation
• '/r' for pre-processing of relief set
• '/s' for pre-processing of soil set (available from version 3.2.0.9)

All further options (paths to input files, modeling options) are set in a *.PAR file.

For Example, this command would run an EROSION-3D calculation from the R-environment:

system2("e3d", '/c "C:/E3Dmodel/model/run.par"', wait=TRUE)

and as pure command-line call:

e3d /r C:/E3Dmodel/model/run.par

Installation

Use the following commands in R to install toolbox.e3d:

# Install devtools from CRAN
install.packages("devtools")

# Install toolbox.e3d
devtools::install_github("jonaslenz/toolbox.e3d")

EROSION-3D needs to be installed and licensed separately, please refer to the EROSION-3D web page or the handbook for specific installation instructions [@von_werner_erosion-3d_2003].

Test setup

Once EROSION-3D is installed and activated and toolbox.e3d is installed, their interaction can be tested using:

toolbox.e3d::get_version.E3D()

This function checks, if EROSION-3D can be found in the system PATH-Variable. If it is not present in PATH it searches for EROSION-3D in the registry and adds it temporarily to PATH for the current R-session.

If this function fails with error message "cannot access e3d installation" you should check the installation of EROSION-3D and add the installation folder manually to system PATH.

When successful this function runs a dummy erosion-3D model and returns the version number in the created file result.log.

Determination of calibration parameters skinfactor and resistance to erosion

The soil input parameters of EROSION-3D include the two calibration parameters skinfactor and resistance to erosion. Determination of these two needs to be done to fit the model output with runoff/soil-loss measurement data obtained in rainfall simulations in field. In previous works these parameters were determined manually with the hillslope-erosion modeling tool EROSION-2D [@michael_anwendung_2000; @schindewolf_parameterization_2012]. Both erosion-modeling tools share basic algorithms, but show differences in available model options and possible input accuracy of parameters.

For fully reproducible results, synthetic land-use and Digital Elevation Models (DEM) are used to model rainfall simulation plots in EROSION-3D. Multiple independent plots - identical in relief but differing in target calibration parameter - are calculated simultaneously. The model output is analyzed and used to iterate calibration parameter values, until a certain accuracy is reached.

Determination of skinfactor for different calibration targets

The skinfactor is a calibration parameter to saturated hydraulic conductivity in the infiltration submodule in EROSION-3D. It can be determined for the fitting target cumulative runoff from the plot or for an infiltration rate at a certain time step.

Fitting target cumulative runoff

To fit the calculated to the measured cumulative runoff for an experiment on a soil with

• 30 mass-% clay Cl
• 40 mass-% silt Si

• 30 mass-% sand Sa (clay+silt+sand must equal 100 mass-%)

• 1.3 mass-% - content of organic bound carbon Corg

• 1300 $kg/m^3$ dry bulk density Bulk
• 22 vol-% initial soil moisture at start of experiment Moist

which produced

• 100 liters total runoff CumRunoff after 30 minutes endmin

with experimental settings of

• 0.5 $mm/min$ rainfall intensity intensity
• 1 $m$ wide plot plotwidth
• 10 $m$ long plot plotlength
• 10 $\%$ slope inclination slope

with model option

• limitation of potential infiltration to available water ponding = TRUE
• display output of calibration parameter values for each iteration step silent = FALSE

the skinfactor can be determined by:

skin_cum <-
toolbox.e3d::determine.skin.runoff.E3D(Cl = 30, Si = 40, Sa = 30,
                          Corg = 1.3, Bulk = 1300, Moist = 22,
                          CumRunoff = 100, intensity = 0.5,
                          plotwidth = 1, plotlength = 10,
                          slope = 10,
                          endmin = 30,
                          ponding = TRUE, silent = FALSE)
skin_cum

Fitting target infiltration rate

Using the same values as in the preceding example with a differing fitting target of:

• 0.2 mm/min infiltration rate infilrate after 30 minutes endmin

the skinfactor can be determined by:

skin_inf <-
toolbox.e3d::determine.skin.infil.E3D(Cl = 30, Si = 40, Sa = 30,
                         Corg = 1.3, Bulk = 1300, Moist = 22,
                         infilrate = 0.2, intensity = 0.5,
                         plotwidth = 1, plotlength = 10,
                         slope = 10,
                         endmin = 30,
                         ponding = TRUE, silent = FALSE)
skin_inf

Determination of resistance to erosion for different calibration targets

Resistance to erosion is a calibration parameter of the particle detachment calculation in the erosion submodule in EROSION-3D. It can be determined for the fitting target cumulative soil loss from the plot or to a sediment concentration at a certain time step.

The erosion submodule of EROSION-3D uses nine grain-size fractions instead of the three used in the infiltration submodule. Therefore Cl, Si and Sa are separated in fine, middle and coarse fractions for the determination functions.

Fitting target cumulative soil loss

To fit the calculated to the measured cumulative soil loss for an experiment on a soil with

• 5 mass-% fine clay FCl, 10 mass-% middle clay MCl, 15 mass-% coarse clay CCl
• 10 mass-% fine silt FSi, 20 mass-% middle silt MSi, 10 mass-% coarse silt CSi

• 15 mass-% fine sand FSa, 10 mass-% middle sand MSa, 5 mass-% coarse sand CSa (total sum must equal 100 mass-%)

• 1.3 mass-% - content of organic bound carbon Corg

• 1300 kg/m^3 dry bulk density Bulk

• 22 vol-% initial soil moisture at start of experiment Moist

• skinfactor Skin from previous determination (100 liters total runoff after 30 minutes endmin)

• a total soil loss of 1 kg soil loss
• 0.05 $s/m^{1/3}$ Mannings-$n$ hydraulic surface roughness Roughness
• 20 % soil cover by plants, plant residues, stones, ... Cover

with experimental settings of

• 0.5 mm/h rainfall intensity intensity
• 1 m wide plot plotwidth
• 10 m long plot plotlength
• 10 $\%$ slope inclination slope

with model option

• limitation of potential infiltration to available water ponding = TRUE
• output of calibration parameter values for each iteration step silent = FALSE

resistance to erosion can be determined by:

eros_cum <-
  toolbox.e3d::determine.eros.cumsed.E3D(FCl=5,MCl=10,CCl=15,
                                       FSi=10,MSi=20,CSi=10,
                                       FSa=15,MSa=10,CSa=5,
                                       Corg = 1.3, Bulk = 1300, Moist = 22,
                                       Skin = skin_cum, Roughness=0.05, Cover = 20,
                                       Soilloss = 1,
                                       intensity = 0.5, plotwidth = 1,
                                       plotlength = 10, slope = 10,
                                       endmin = 30, ponding = TRUE, silent = FALSE)
eros_cum

Fitting target sediment concentration

To be added ...

Validation modeling

Validation modeling can be used to check how input parameters and model options will affect modeling results. Due to the high number of possible combinations this section shall describe a possible work flow demonstrating fully reproducible work with EROSION-3D.

The effect of differing skinfactor values (from two determination methods) on the modeled runoff volume and soil loss is used as example. The models are run on synthetic elevation and land use models with independent slope stripes, as described in [@lenz_konzeptionelle_2017].

Create model folders

As first step folders are created including a basic EROSION-3D model:

path <- toolbox.e3d::create_folders.E3D(path = "C:/E3Dmodel_toolbox/")

Soil set

EROSION-3D needs at least two files for the soil set:

• a landuse.asc, defining an ID for each raster cell,
• and a soil_params.csv defining soil parameters for each ID in landuse.asc.

To apply changes to soil parameters soil_params.csv can be read and modified:

soils <- read.csv(file.path(path,"soil/soil_params.csv"))[1,]

# soil parameters are set according to example in parameter determination
  soils$BLKDENSITY <- 1300
  soils$CORG       <- 1.3
  soils$INITMOIST  <- 22
  soils$FT         <- 5
  soils$MT         <- 10
  soils$GT         <- 15
  soils$FU         <- 10
  soils$MU         <- 20
  soils$GU         <- 10
  soils$FS         <- 15
  soils$MS         <- 10
  soils$GS         <- 5
  soils$ROUGHNESS  <- 0.05
  soils$COVER      <- 20
  soils$ERODIBIL   <- eros_cum

# parameters derived automatically by EROSION-3D are set to 0
  soils$THETA_R <- 0
  soils$THETA_S <- 0
  soils$ALPHA <- 0
  soils$NORDPOL <- 0

# a second soil parameter entry is created
  soils[2,] <- soils[1,]

# ID of second entry is set
  soils$POLY_ID<- 1:nrow(soils)

# skinfactors are set for each entry separately
  soils$SKINFACTOR[1] <- skin_cum
  soils$SKINFACTOR[2] <- skin_inf

  write.csv(soils,file.path(path,"soil/soil_params.csv"),
            row.names = FALSE, quote = FALSE)

The synthetic landuse.asc can be created with:

  toolbox.e3d::write.landuse.E3D(POLY_ID = soils$POLY_ID, length = 10,
            path = file.path(path,"soil/"), filename = "landuse.asc")

Soil set creation since version 3.2.0.9

Since version 3.2.0.9 EROSION-3D can pre-process the soil set from a given land use raster and a soil_params file. This allows the analysis of parameters derived by EROSION-3D (*.pid files, THETA_R, THETA_S, ALPHA, ...)

The input files must be written to the model parent folder:

# write files to parent folder
  write.csv(soils,file.path(path,"soil_params.csv"),
            row.names = FALSE, quote = FALSE)
  toolbox.e3d::write.landuse.E3D(POLY_ID = soils$POLY_ID, length = 10,
            path = file.path(path), filename = "landuse.asc")

They must be defined in the *.par file:

# read, modify and rewrite *.par
  run_par <- ini::read.ini(file.path(path,"run.par"))
  run_par[["Soil_landuse"]][["rdb_dat"]] <- file.path(path,"soil_params.csv")
  run_par[["Soil_landuse"]][["rdb_grd"]] <- file.path(path,"landuse.asc")
  ini::write.ini(run_par,filepath = file.path(path,"run.par"))

And can than be pre-processed by:

# pre-process soil set
  system2("e3d", paste0('/s "',normalizePath(file.path(path,"run.par")),'"'), wait=TRUE)

# read resulting soil_params
  soilsbyE3D <- read.csv(file.path(path,"soil/soil_params.csv"))

Digital elevation Model and relief set

A synthetic DEM is created with:

toolbox.e3d::write.relief.E3D(POLY_ID = soils$POLY_ID, length = 10,slope = 11,
                              path = path, filename = "dem.asc")

where length (in meters) and slope (inclination in %) define the slope geometry.

The number of elements in POLY_ID defines the number of independent slopes simulated in parallel.

The EROSION-3D relief set can be created with:

system2("e3d", paste0('/r "',normalizePath(file.path(path,"run.par")),'"'), wait=TRUE)

Since vertical DEM resolution is limited to 2 decimal digits (i.e. to 0.01 m) in EROSION-3D by default, step-like artifacts can be introduced. To check for such artifacts one can read unique values from the slope file created by EROSION-3D:

slope_E3D <- raster::raster(normalizePath(file.path(path,"relief/slope.asc")))
unique(raster::values(slope_E3D))

If only one value is returned all slope values are equal and no step artifacts were introduced.
The default vertical accuracy of EROSION-3D can be modified by the Relief option "dem_roundval" in the *.run file. The default value of 100 implies a vertical accuracy of 0.01 m, while a value of 1000 would imply a vertical accuracy of 0.001 m.

Create rainfall file

An EROSION-3D compatible rainfall file can be written by:

toolbox.e3d::write.rainfile.E3D(time = c(0,30*60), intens = c(0.5,0), path,
                                filename = "rain_e3d.csv")

• Time and intens are numeric vectors of equal length.
• Time gives the time steps in seconds, at which rainfall-intensity changes occurs.
• Intens gives the rainfall-intensity for the following time period in mm/min.

Run calculation

Once all input files are prepared the simulation can be run:

# command-line call to run EROSION-3D
system2("e3d", paste0('/c "',normalizePath(file.path(path,"run.par")),'"'), wait=TRUE)

Afterwards, the results can be analyzed:

#read runoff in liters (*1000)
runoff <- raster::raster(file.path(path,"result/sum_q.asc"))[,1]*1000
sed <- raster::raster(file.path(path,"result/sum_sedvol.asc"))[,1]

cbind(soils[,c("POLY_ID","SKINFACTOR")], runoff, sed)

The hypothetical results show, that runoff and soil loss calculated with the skinfactor determined for the fitting target cumulative runoff meet the expectations (100 l runoff, 1 kg soil loss) quite well, whereas the results calculated with the skinfactor determined for the fitting target infiltration rate are less than half the expected value.

Delete model folder

To clear the work space and delete all model files run:

unlink(file.path("C:/E3Dmodel_toolbox/"), force = T, recursive = T)

References

jonaslenz/toolbox.e3d documentation built on Jan. 16, 2025, 5:24 a.m.