The specification of input fluxes in SoilR is often a source of confusion for new users. In this post, I will try to clarify this topic.

First, it is important to remember that SoilR solves systems of ordinary differential equations (ODEs). These equations are different than ordinary difference equations in which the dynamics during a specific interval are represented explicity. In contrast, ODEs do not represent explicity a particular time interval, but they rather consider the dynamics of the system over inifinitesimally small time intervals, in such a way that time is a continuous variable. In other words, SoilR do not compute dynamics for specific time intervals, but rather for any value of time over a specific time range.

This consideration is important when specifying input fluxes in SoilR. Input fluxes must be specified in units of mass per unit of time such as Mg C year-1, or on an area basis as Mg C ha-1 year-1. These units must be consistent with the units of the initial conditions as mass (e.g. Mg C or Mg C ha-1), and the units of decomposition rates in units of inverse time (e.g. year-1).

The input fluxes should be understood as a flux rate, i.e. how fast the mass inputs are entering the system per unit of time. This is similar as a velocity, for example, as when an object is moving in space per unit of time. Because SoilR is not representing specific intervals such as months or years, the specification of the inputs should be done, for any time, at the rate given by the specific units. For example, if the input flux is 3.0 Mg C ha-1 year-1, this flux rate applies to every day, month, or year that is being simulated.

This topic is confusing because in SoilR we need to specify the times at which we want a solution. For example, we may define our time argument as

years <- seq(from=0, to=10, by=1/12)

which is a sequence of time points from 0 to 10 in intervals of 1/12 of a time unit. This is the same as a sequence of 10 years split in months. However, SoilR is not computing the dynamics during the monthly intervals. It simply will compute the solution of the system of ODEs for each of these time points. Therefore, to specify the input fluxes, one must specify them as the flux velocity at which they are entering at those times. One way to do this, although inefficient, would be to create a data.frame specifying that at each of these time points the input flux rate is 3.0 Mg C ha-1 year-1

Inputs <- data.frame(years, rep(3, times=length(years)))

A more efficient way to specify the input fluxes when they are constant is simply by defining the input as one single value and not as a data.frame

Inputs <- 3

SoilR functions for bulding models such as Model will automatically handle input fluxes specified as a constant value or as a data.frame. The data.frame option is useful when the input rate changes over time, but the values must be specified as the input flux rate at each particular time point, and NOT as the amount of inputs that would enter the interval beween time points.

Input fluxes can also be specified through a function that returns the input flux for any time point. SoilR will automatically use the function to internally compute the appropriate input flux for each of the time points being simulated.

When explaining this topic to students, I often give the analogy with the velocity of a car. If I start driving a car, the speedometer shows the instantaneous speed of the car, say 30 km hour-1, but I don’t need to drive for an entire hour to attain this speed. The instantaneous velocity changes as I drive, but the speedometer is giving me the speed in units of km hour-1. It is the same with the input flux rates in SoilR, the velocity at which mass enters the system must be specified for any time point independent of what would happen in flixed time intervals.