Skip to contents

Basic Usage of salmoRodeo

Thomas Petzoldt and Justus Möller

2025-07-01

Background

SALMO (Simulation by an Analytical Lake Model, Benndorf 1979; Benndorf and Recknagel 1982; Recknagel 1989) and further developed by several authors, e.g. Petzoldt et al. (2005), Rolinski et al. (2005) and Sachse et al. (2014) is a dynamic ecological model that simulates essential pelagic food web compartments of lakes and reservoirs. Its state variables are soluble reactive phosphorus, inorganic nitrogen, two or three functional phytoplankton groups, zooplankton, oxygen and detritus. Other important, e.g. predation by fish or sediment-water interactions, are included by empirical equations.

Over the years, several “monolithic” implementations and forks have appeared, that have in common to be difficult to maintain. The version provided here was implemented by Justus Möller as part of a study project. It aims to make modificatins and extensions easier by emplying a tabular description of processes and stoichiometry. The code generator package (rodeo, Kneis, Petzoldt, and Berendonk 2017; Kneis 2024) to generate executable code.

This vignette demonstrates the basic setup, execution, and plotting functionalities of the salmoRodeo package. It showcases how to initialize a model, set parameters and initial conditions, run simulations, and visualize results.

Setup and Model Compilation

We begin by loading the salmoRodeo package and setting up the model. By default, model_setup() uses input files from the package’s internal models directory.

library("salmoRodeo")
library("deSolve")

# Setup and compile model using default input files
model <- model_setup()

You could also specify a local data file if your inputs are not bundled with the package:

#model <- model_setup(datafile="inputs.tsv")

Setting Time, Parameters, and Initial Conditions

Next, we define the simulation time steps (e.g. 2 years), initial state variable values, and any custom parameter settings. Note that due to its implementation as a state variable, xsum must be the sum of x1 + x2 + x3.

times <- seq(1, 730, 1)

# Set initial values for state variables
model <- set_initval(model, c(n=3, p=50, x1=0.1, x2=0.1, x3=0.1, z=0.1, d=1, xsum=0.3))

# Apply default parameter values (or provide specific changes if needed)
model <- set_pars(model)

Optional: Cloning and Altering Parameters for Comparison

The rodeo package allows you to clone model objects, which is useful for comparing different parameter scenarios without re-compiling the model from scratch. We’ll create a clone and modify a few parameters. Remember that set_pars() is cumulative if called multiple times on the same objec.

model2 <- model$clone()
model2 <- set_pars(model2, c(npsfmode = 0, MOMIN = 0.03, MOT=0.012))

# Verify the altered parameters
model2$getPars()[c("MOMIN", "MOT")]

Running Simulations

Now, we run the dynamic simulations for both the original and the cloned models using the specified time steps and solver settings.

out <- model$dynamics(times = times, diagnostics = TRUE, atol = 1e-8,
                      rtol = 1e-2, method = "adams", fortran = TRUE)

out2 <- model2$dynamics(times = times, diagnostics = TRUE, atol = 1e-8,
                        rtol = 1e-2, method = "adams", fortran = TRUE)

Visualizing Results and Diagnostics

Finally, we plot the output from both simulations to compare the state variable trajectories and run diagnostics to check the model’s performance.

plot(out, out2, which=c("n", "p", "x1", "x2", "x3", "z", "d", "xsum", "pin"))
deSolve::diagnostics(out)

References

Benndorf, J. 1979. “Kausalanalyse, Theoretische Synthese Und Simulation Des Eutrophierungsprozesses in Stehenden Und Gestauten Gewässern.” Habilitationsschrift, TU Dresden, Fakultät Bau-, Wasser- und Forstwesen.
Benndorf, J., and F. Recknagel. 1982. “Problems of Application of the Ecological Model SALMO to Lakes and Reservoirs Having Various Trophic States.” Ecological Modelling 17: 129–45.
Kneis, David. 2024. Rodeo: A Code Generator for ODE-Based Models. https://doi.org/10.32614/CRAN.package.rodeo.
Kneis, David, Thomas Petzoldt, and Thomas U. Berendonk. 2017. “An R-package to Boost Fitness and Life Expectancy of Environmental Models.” Environmental Modelling & Software 96: 123–27. https://doi.org/10.1016/j.envsoft.2017.06.036.
Petzoldt, T., S. Rolinski, K. Rinke, M. König, H. Z. Baumert, and J. Benndorf. 2005. “SALMO: Die ökologische Komponente des gekoppelten Modells.” Wasserwirtschaft 95: 28–33.
Recknagel, Friedrich. 1989. Applied Systems Ecology Approach and Case Studies in Aquatic Ecology. Berlin, Boston: De Gruyter. https://doi.org/doi:10.1515/9783112650929.
Rolinski, S., T. Petzoldt, H. Z. Baumert, K Bigalke, H. Horn, and J. Benndorf. 2005. “Das physikalisch-ökologisch gekoppelte Talsperrenmodell.” Wasserwirtschaft 95: 34–38.
Sachse, René, Thomas Petzoldt, Maria Blumstock, Santiago Moreira, Marlene Pätzig, Jacqueline Rücker, Jan H. Janse, Wolf M. Mooij, and Sabine Hilt. 2014. “Extending One-Dimensional Models for Deep Lakes to Simulate the Impact of Submerged Macrophytes on Water Quality.” Environmental Modelling & Software 61: 410–23.