Description Usage Arguments Details Value Author(s) References See Also Examples
Estimates the volumetric transport term (i.e. the rate of change of the concentration due to diffusion and advection) in a 1D, 2D or 3D model of an aquatic system (river, estuary).
Volumetric transport implies the use of flows (mass per unit of time) rather
than fluxes (mass per unit of area per unit of time) as is done in
tran.1D
, tran.2D
or tran.3D
.
The tran.volume.xD
routines are particularly suited for modelling
channels (like rivers, estuaries) where the crosssectional area changes,
but where this area change needs not to be explicitly modelled as such.
Another difference with tran.1D
is that the tran.volume.1D
routine also allows lateral water or lateral mass input (as from side rivers
or diffusive lateral ground water inflow).
The tran.volume.2D
routine can check for water balance and assume an
in or efflux in case the net flows in and out of a box are not = 0
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27  tran.volume.1D(C, C.up = C[1], C.down = C[length(C)],
C.lat = C, F.up = NULL, F.down = NULL, F.lat = NULL,
Disp, flow = 0, flow.lat = NULL, AFDW = 1,
V = NULL, full.check = FALSE, full.output = FALSE)
tran.volume.2D(C, C.x.up = C[1, ], C.x.down = C[nrow(C), ],
C.y.up = C[, 1], C.y.down = C[, ncol(C)],
C.z = C, masscons = TRUE,
F.x.up = NULL, F.x.down = NULL,
F.y.up = NULL, F.y.down = NULL,
Disp.grid = NULL, Disp.x = NULL, Disp.y = Disp.x,
flow.grid = NULL, flow.x = NULL, flow.y = NULL,
AFDW.grid = NULL, AFDW.x = 1, AFDW.y = AFDW.x,
V = NULL, full.check = FALSE, full.output = FALSE)
tran.volume.3D(C, C.x.up = C[1, , ], C.x.down = C[dim(C)[1], , ],
C.y.up = C[, 1, ], C.y.down = C[, dim(C)[2], ],
C.z.up = C[, , 1], C.z.down = C[, , dim(C)[3]],
F.x.up = NULL, F.x.down = NULL,
F.y.up = NULL, F.y.down = NULL,
F.z.up = NULL, F.z.down = NULL,
Disp.grid = NULL,
Disp.x = NULL, Disp.y = Disp.x, Disp.z = Disp.x,
flow.grid = NULL, flow.x = 0, flow.y = 0, flow.z = 0,
AFDW.grid = NULL, AFDW.x = 1, AFDW.y = AFDW.x,
AFDW.z = AFDW.x,
V = NULL, full.check = FALSE, full.output = FALSE)

C 
tracer concentration, defined at the centre of the grid cells. A vector of length N [M/L3] (tran.volume.1D), a matrix of dimension Nr*Nc (tran.volume.2D) or an Nx*Ny*Nz array (tran.volume.3D) [M/L3]. 
C.up 
tracer concentration at the upstream interface. One value [M/L3]. 
C.down 
tracer concentration at downstream interface. One value [M/L3]. 
C.lat 
tracer concentration in the lateral input, defined at
grid cell centres. One value, a vector of length N, or a
list as defined by 
C.x.up 
concentration at upstream boundary in xdirection; vector of length Ny (2D) or matrix of dimensions Ny*Nz (3D) [M/L3]. 
C.x.down 
concentration at downstream boundary in xdirection; vector of length Ny (2D) or matrix of dimensions Ny*Nz (3D) [M/L3]. 
C.y.up 
concentration at upstream boundary in ydirection; vector of length Nx (2D) or matrix of dimensions Nx*Nz (3D) [M/L3]. 
C.y.down 
concentration at downstream boundary in ydirection; vector of length Nx (2D) or matrix of dimensions Nx*Nz (3D) [M/L3]. 
C.z.up 
concentration at upstream boundary in zdirection; matrix of dimensions Nx*Ny [M/L3]. 
C.z.down 
concentration at downstream boundary in zdirection; matrix of dimensions Nx*Ny [M/L3]. 
C.z 
concentration at boundary in zdirection for 2D models where

masscons 
When 
F.up 
total tracer input at the upstream interface. One value [M/T]. 
F.down 
total tracer input at downstream interface. One value [M/T]. 
F.lat 
total lateral tracer input, defined at grid cell centres.
One value, a vector of length N, or a 1D list property as defined by 
F.x.up 
total tracer input at the upstream interface in xdirection. positive = INTO model domain. A vector of length Ny (2D) or a matrix of dimensions Ny*Nz (3D) [M/T]. 
F.x.down 
total tracer input at downstream interface in xdirection. positive = INTO model domain. A vector of length Ny (2D) or a matrix of dimensions Ny*Nz (3D) [M/T]. 
F.y.up 
total tracer input at the upstream interface in ydirection. positive = INTO model domain. A vector of length Nx (2D) or a matrix of dimensions Nx*Nz (3D) [M/T]. 
F.y.down 
total tracer input at downstream interface in ydirection. positive = INTO model domain. A vector of length Nx (2D) or a matrix of dimensions Nx*Nz (3D) [M/T]. 
F.z.up 
total tracer input at the upstream interface in zdirection. positive = INTO model domain. A matrix of dimensions Nx*Ny [M/T]. 
F.z.down 
total tracer input at downstream interface in zdirection. positive = INTO model domain. A matrix of dimensions Nx*Ny [M/T]. 
Disp.grid 
BULK dispersion coefficients defined on all grid cell
interfaces. For 
Disp 
BULK dispersion coefficient, defined on grid cell interfaces.
One value, a vector of length N+1, or a 1D list property as defined by 
Disp.x 
BULK dispersion coefficient in xdirection, defined on grid cell interfaces. One value, a vector of length (Nx+1), a 
Disp.y 
BULK dispersion coefficient in ydirection, defined on grid cell
interfaces. One value, a vector of length (Ny+1),
a 
Disp.z 
BULK dispersion coefficient in zdirection, defined on grid cell interfaces. One value, a vector of length (Nz+1), or a Nx*Ny*(Nz+1) array [L3/T]. 
flow 
water flow rate, defined on grid cell interfaces. One value, a vector of length N+1, or a list as defined by 
flow.lat 
lateral water flow rate [L3/T] into each volume box, defined at grid cell centres. One value, a vector of
length N, or a list as defined by 
flow.grid 
flow rates defined on all grid cell interfaces. Can be positive (downstream flow) or negative (upstream flow). Should contain elements x.int, y.int, z.int (3D), arrays with the values on the interfaces in x, y and zdirection [L3/T]. 
flow.x 
flow rates in the xdirection, defined on grid cell
interfaces. Can be positive (downstream flow) or negative (upstream flow).
One value, a vector of length (Nx+1),
a 
flow.y 
flow rates in the ydirection, defined on grid cell
interfaces. Can be positive (downstream flow) or negative (upstream flow).
One value, a vector of length (Ny+1),
a 
flow.z 
flow rates in the zdirection, defined on grid cell interfaces. Can be positive (downstream flow) or negative (upstream flow). One value, a vector of length (Nz+1), or a Nx*Ny*(Nz+1) array [L3/T]. 
AFDW 
weight used in the finite difference scheme for advection,
defined on grid cell interfaces; backward = 1, centred = 0.5, forward = 0;
default is backward. One value, a vector of length N+1, or a
list as defined by 
AFDW.grid 
weight used in the finite difference scheme for advection
in the xdirection, defined on grid cell interfaces; backward = 1,
centred = 0.5, forward = 0; default is backward.
For 
AFDW.x 
weight used in the finite difference scheme for advection
in the xdirection, defined on grid cell interfaces; backward = 1,
centred = 0.5, forward = 0; default is backward.
One value, a vector of length (Nx+1),
a 
AFDW.y 
weight used in the finite difference scheme for advection
in the ydirection, defined on grid cell interfaces; backward = 1,
centred = 0.5, forward = 0; default is backward.
One value, a vector of length (Ny+1),
a 
AFDW.z 
weight used in the finite difference scheme for advection
in the zdirection, defined on grid cell interfaces; backward = 1,
centred = 0.5, forward = 0; default is backward.
One value, a vector of length (Nz+1),
a 
V 
grid cell volume, defined at grid cell centres [L3]. One value, a
vector of length N, or a list as defined by 
full.check 
logical flag enabling a full check of the consistency
of the arguments (default = 
full.output 
logical flag enabling a full return of the output
(default = 
The boundary conditions are of type
1. zerogradient (default)
2. fixed concentration
3. fixed input
The bulk dispersion coefficient (Disp
) and the flow rate
(flow
) can be either one value or a vector of length N+1, defined at
all grid cell interfaces, including upstream and downstream boundary.
The spatial discretisation is given by the volume of each box (V
),
which can be one value or a vector of length N+1, defined at the centre of
each grid cell.
The water flow is mass conservative. Over each volume box, the routine calculates internally the downstream outflow of water in terms of the upstream inflow and the lateral inflow.
dC 
the rate of change of the concentration C due to transport, defined in the centre of each grid cell [M/L3/T]. 
F.up 
mass flow across the upstream boundary, positive = INTO model domain. One value [M/T]. 
F.down 
mass flow across the downstream boundary, positive = OUT of model domain. One value [M/T]. 
F.lat 
lateral mass input per volume box, positive = INTO model domain. A vector of length N [M/T]. 
flow 
water flow across the interface of each grid cell. A vector
of length N+1 [L3/T]. Only provided when ( 
flow.up 
water flow across the upstream (external) boundary, positive = INTO
model domain. One value [L3/T]. Only provided when ( 
flow.down 
water flow across the downstream (external) boundary, positive = OUT
of model domain. One value [L3/T]. Only provided when
( 
flow.lat 
lateral water input on each volume box, positive = INTO model
domain. A vector of length N [L3/T]. Only provided when
( 
F 
mass flow across at the interface of each grid cell. A vector
of length N+1 [M/T]. Only provided when ( 
Filip Meysman <filip.meysman@nioz.nl>, Karline Soetaert <karline.soetaert@nioz.nl>
Soetaert and Herman (2009) A practical guide to ecological modelling  using R as a simulation platform. Springer.
advection.volume.1D
, for more sophisticated advection schemes
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86  ## =============================================================================
## EXAMPLE : organic carbon (OC) decay in a widening estuary
## =============================================================================
# Two scenarios are simulated: the baseline includes only input
# of organic matter upstream. The second scenario simulates the
# input of an important side river half way the estuary.
#====================#
# Model formulation #
#====================#
river.model < function (t = 0, OC, pars = NULL) {
tran < tran.volume.1D(C = OC, F.up = F.OC, F.lat = F.lat,
Disp = Disp, flow = flow.up, flow.lat = flow.lat,
V = Volume, full.output = TRUE)
reac <  k*OC
return(list(dCdt = tran$dC + reac, Flow = tran$flow))
}
#======================#
# Parameter definition #
#======================#
# Initialising morphology estuary:
nbox < 500 # number of grid cells
lengthEstuary < 100000 # length of estuary [m]
BoxLength < lengthEstuary/nbox # [m]
Distance < seq(BoxLength/2, by = BoxLength, len =nbox) # [m]
Int.Distance < seq(0, by = BoxLength, len = (nbox+1)) # [m]
# Cross sectional area: sigmoid function of estuarine distance [m2]
CrossArea < 4000 + 72000 * Distance^5 /(Distance^5+50000^5)
# Volume of boxes (m3)
Volume < CrossArea*BoxLength
# Transport coefficients
Disp < 1000 # m3/s, bulk dispersion coefficient
flow.up < 180 # m3/s, main river upstream inflow
flow.lat.0 < 180 # m3/s, side river inflow
F.OC < 180 # input organic carbon [mol s1]
F.lat.0 < 180 # lateral input organic carbon [mol s1]
k < 10/(365*24*3600) # decay constant organic carbon [s1]
#====================#
# Model solution #
#====================#
#scenario 1: without lateral input
F.lat < rep(0, length.out = nbox)
flow.lat < rep(0, length.out = nbox)
Conc1 < steady.1D(runif(nbox), fun = river.model, nspec = 1, name = "OC")
#scenario 2: with lateral input
F.lat < F.lat.0 * dnorm(x =Distance/lengthEstuary,
mean = Distance[nbox/2]/lengthEstuary,
sd = 1/20, log = FALSE)/nbox
flow.lat < flow.lat.0 * dnorm(x = Distance/lengthEstuary,
mean = Distance[nbox/2]/lengthEstuary,
sd = 1/20, log = FALSE)/nbox
Conc2 < steady.1D(runif(nbox), fun = river.model, nspec = 1, name = "OC")
#====================#
# Plotting output #
#====================#
# use S3 plot method
plot(Conc1, Conc2, grid = Distance/1000, which = "OC",
mfrow = c(2, 1), lwd = 2, xlab = "distance [km]",
main = "Organic carbon decay in the estuary",
ylab = "OC Concentration [mM]")
plot(Conc1, Conc2, grid = Int.Distance/1000, which = "Flow",
mfrow = NULL, lwd = 2, xlab = "distance [km]",
main = "Longitudinal change in the water flow rate",
ylab = "Flow rate [m3 s1]")
legend ("topright", lty = 1:2, col = 1:2, lwd = 2,
c("baseline", "+ side river input"))

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.