Debian Codegraph @

man/forcings.Rd

raw
1 \name{forcings}
2 \alias{forcings}
3 \title{
4 Passing Forcing Functions to Models Written in R or Compiled Code.
5 }
6 \description{
7 A \code{forcing function} is an external variable that is essential to the
8 model, but not explicitly modeled. Rather, it is imposed as a time-series.
9 Thus, if a model uses forcing variables, their value at each time point
10 needs to be estimated by interpolation of a data series.
11 }
12
13 \details{
14
15 The \code{forcing functions} are imposed as a data series, that contains
16 the values of the forcings at specified times.
17
18 Models may be defined in compiled C or FORTRAN code, as well as in R.
19
20 If the model is defined in \emph{R code}, it is most efficient to:
21
22 1. define a function that performs the linear interpolation,
23 using \R's \code{\link{approxfun}}. It is generally recommended to use
24 \code{rule = 2}, such as to allow extrapolation outside of the time interval,
25 especially when using the Livermore solvers, as these may exceed the last
26 time point.
27
28 2. call this function within the model's derivative function,
29 to interpolate at the current timestep.
30
31 See first example.
32
33 If the models are defined in \emph{compiled C or FORTRAN code}, it is possible to
34 use \code{deSolve}s forcing function update algorithm. This is the
35 compiled-code equivalent of \code{approxfun} or \code{approx}.
36
37 In this case:\cr
38 1. the forcing function data series is provided by means
39 of argument \code{forcings},
40
41 2. \code{initforc} is the name of the forcing function initialisation function,
42 as provided in \file{dllname}, while
43
44 3. \code{fcontrol} is a list used to finetune how the forcing update should
45 be performed.
46
47 The \bold{fcontrol} argument is a list that can supply any of the following
48 components (conform the definitions in the \link[stats]{approxfun} function):
49 \describe{
50 \item{method }{specifies the interpolation method to be used.
51 Choices are \code{"linear"} or \code{"constant"},}
52 \item{rule }{an integer describing how interpolation is to take place
53 outside the interval [min(times), max(times)].
54 If \code{rule} is \code{1} then an error will be triggered and the
55 calculation will stop if \code{times} extends the interval of the
56 forcing function data set. If it is \code{2}, the \bold{default}, the
57 value at the closest data extreme is used, a warning will be printed if
58 \code{verbose} is \code{TRUE},
59
60 Note that the default differs from the \code{approx} default.}
61 \item{f }{For \code{method = "constant"} a number between \code{0} and
62 \code{1} inclusive, indicating a compromise between left- and
63 right-continuous step functions. If \code{y0} and \code{y1} are the
64 values to the left and right of the point then the value is
65 \code{y0 * (1 - f) + y1 * f} so that \code{f = 0} is right-continuous and
66 \code{f = 1} is left-continuous,
67 }
68 \item{ties }{Handling of tied \code{times} values. Either a function
69 with a single vector argument returning a single number result or the
70 string \code{"ordered"}.
71
72 Note that the default is \code{"ordered"}, hence the existence of ties will
73 NOT be investigated; in the \code{C} code this will mean that -if ties
74 exist, the first value will be used; if the dataset is not ordered,
75 then nonsense will be produced.
76
77 Alternative values for \code{ties} are \code{mean}, \code{min} etc
78 }
79 }
80 The defaults are:
81
82 \code{fcontrol = list(method = "linear", rule = 2, f = 0, ties = "ordered")}
83
84 Note that only ONE specification is allowed, even if there is more than
85 one forcing function data set.
86
87 More information about models defined in compiled code is in the package
88 vignette ("compiledCode").
89 }
90 \note{
91 How to write compiled code is described in package vignette
92 \code{"compiledCode"}, which should be referred to for details.
93
94 This vignette also contains examples on how to pass forcing functions.
95 }
96 \author{
97 Karline Soetaert,
98
99 Thomas Petzoldt,
100
101 R. Woodrow Setzer
102 }
103 \seealso{
104 \code{\link{approx}} or \code{\link{approxfun}}, the \R function,
105
106 \code{\link{events}} for how to implement events.
107 }
108 \examples{
109 ## =============================================================================
110 ## FORCING FUNCTION: The sediment oxygen consumption example - R-code:
111 ## =============================================================================
112
113 ## Forcing function data
114 Flux <- matrix(ncol=2,byrow=TRUE,data=c(
115 1, 0.654, 11, 0.167, 21, 0.060, 41, 0.070, 73,0.277, 83,0.186,
116 93,0.140,103, 0.255, 113, 0.231,123, 0.309,133,1.127,143,1.923,
117 153,1.091,163,1.001, 173, 1.691,183, 1.404,194,1.226,204,0.767,
118 214, 0.893,224,0.737, 234,0.772,244, 0.726,254,0.624,264,0.439,
119 274,0.168,284 ,0.280, 294,0.202,304, 0.193,315,0.286,325,0.599,
120 335, 1.889,345, 0.996,355,0.681,365,1.135))
121
122 parms <- c(k=0.01)
123
124 times <- 1:365
125
126 ## the model
127 sediment <- function( t, O2, k)
128 list (c(Depo(t) - k * O2), depo = Depo(t))
129
130 # the forcing functions; rule = 2 avoids NaNs in interpolation
131 Depo <- approxfun(x = Flux[,1], y = Flux[,2], method = "linear", rule = 2)
132
133 Out <- ode(times = times, func = sediment, y = c(O2 = 63), parms = parms)
134
135 ## same forcing functions, now constant interpolation
136 Depo <- approxfun(x = Flux[,1], y = Flux[,2], method = "constant",
137 f = 0.5, rule = 2)
138
139 Out2 <- ode(times = times, func = sediment, y = c(O2 = 63), parms = parms)
140
141 mf <- par(mfrow = c(2, 1))
142 plot (Out, which = "depo", type = "l", lwd = 2, mfrow = NULL)
143 lines(Out2[,"time"], Out2[,"depo"], col = "red", lwd = 2)
144
145 plot (Out, which = "O2", type = "l", lwd = 2, mfrow = NULL)
146 lines(Out2[,"time"], Out2[,"O2"], col = "red", lwd = 2)
147
148 ## =============================================================================
149 ## SCOC is the same model, as implemented in FORTRAN
150 ## =============================================================================
151
152 out<- SCOC(times, parms = parms, Flux = Flux)
153
154 plot(out[,"time"], out[,"Depo"], type = "l", col = "red")
155 lines(out[,"time"], out[,"Mineralisation"], col = "blue")
156
157 ## Constant interpolation of forcing function - left side of interval
158 fcontrol <- list(method = "constant")
159
160 out2 <- SCOC(times, parms = parms, Flux = Flux, fcontrol = fcontrol)
161
162 plot(out2[,"time"], out2[,"Depo"], type = "l", col = "red")
163 lines(out2[,"time"], out2[,"Mineralisation"], col = "blue")
164
165
166 \dontrun{
167 ## =============================================================================
168 ## show examples (see respective help pages for details)
169 ## =============================================================================
170
171 example(aquaphy)
172
173 ## show package vignette with tutorial about how to use compiled models
174 ## + source code of the vignette
175 ## + directory with C and FORTRAN sources
176 vignette("compiledCode")
177 edit(vignette("compiledCode"))
178 browseURL(paste(system.file(package = "deSolve"), "/doc", sep = ""))
179 }
180
181 }
182
183 \keyword{utilities}