forageMod: Run CPF model

In samuelVJrobinson/CPForage: Central Place Foraging model based on the Ideal Free Distribution

Description

forageMod runs central-place foraging model given forager and world data.

Function to run central-place foraging (CPF) model based on the ideal-free distribution (IFD). Takes a list of nest parameters, and a list of world parameters, runs the model until convergence, and then returns a list containing a matrix of competitive effects, and a list of matrices of foraging parameters (e.g. time in patch, foraging currency experienced at each cell). Use cpf2df() to convert this to a more readable dataframe.

Usage

forageMod(
  world,
  nests,
  iterlim = 5000,
  verbose = FALSE,
  parallel = FALSE,
  ncore = 4,
  parMethod = "SOCK",
  tol = .Machine$double.eps^0.25
)

Arguments

world	World structure. List.
nests	Nests structure. List of lists.
iterlim	Limit to number of iterations. Default = 5000.
verbose	Should function display progress?
parallel	Should parallel processing be used for large tasks?
ncore	Number of SNOW cores to use (if parallel = TRUE).
parMethod	Message passing for parallel processing (see details below).
tol	Tolerance range for optimization function. Default = .Machine$double.eps^0.25.

Details

parMethod must be either 'SOCK' (Default) or 'MPI'. Requires doSNOW (Windows) and RMPI (Linux) packages.

world should be a named list containing:

• mu: nectar production values (per s); matrix

• e: energy value of nectar (J/μL); matrix

• l: maximum nectar standing crop (μL); matrix

• f: travel time between flowers (s); matrix

• alphaVal: Increase in metabolic rate with load; numeric.

• flDens: flower count per cell; matrix

• cellSize: size of a cell (m)

• forageType: foraging type. See curr.

nests should be a named list containing:

• xloc: x-location of nest (column number) in world; integer.

• yloc: y-location of nest (row number) in world; integer.

• n: number of foragers; integer.

• whatCurr: 'eff' (efficiency) or 'rat' (rate).

• sol: solitary foraging; logical.

• constants: named list of foraging parameters:

  • L_max: maximum load (μL); numeric.

  • v: maximum flight speed (m/s); numeric.

  • betaVal: reduction of flight speed with load (m/s*μL); numeric.

  • p_i: rate of nectar uptake ("licking speed", μL/s); numeric.

  • h: handling time before draining a flower (s); numeric.

  • c_f: energetic cost of flight (J/s); numeric.

  • c_i: energetic cost of non-flight (J/s); numeric.

  • H: time spent in hive/aggregation (s); numeric.

• steps: step sizes to use during optimization; numeric vector.

• eps: accuracy to use for optimization; numeric.

Value

List containing world structure (competition term) and nest structure (forager distribution)

Examples

#Create test world for run
nu_i<-0.3/3600 #Nectar production/hr for a single flower
flDens<-520 #Flower density/m2
e_i<-14.35 #Energetic value/unit
l_i<-1 #Canola standing crop (1uL)
f_i<-0.86 #Inter-flower flight time

#World structure
cellSize<-10 #10m cells (100m^2)
worldSize<-120 #120x120m field (100x100m field with 10m buffer zone worth nothing)
world1<-list(mu=matrix(0,worldSize/cellSize,worldSize/cellSize),
            flDens=matrix(0,worldSize/cellSize,worldSize/cellSize),
            e=matrix(0,worldSize/cellSize,worldSize/cellSize),
            l=matrix(0,worldSize/cellSize,worldSize/cellSize),
            f=matrix(0,worldSize/cellSize,worldSize/cellSize),
            alphaVal=matrix(0,worldSize/cellSize,worldSize/cellSize),
            cellSize=cellSize) #Empty world

world1$mu[c(2:11),c(2:11)]<-nu_i #Per-flower nectar production in canola-filled cells
world1$flDens[c(2:11),c(2:11)]<-flDens*cellSize^2 #Flower number per cell
world1$e[c(2:11),c(2:11)]<-e_i #Energy production in canola-filled cells
world1$l[c(2:11),c(2:11)]<-l_i #Standing crop in cells with no competition
world1$f[c(2:11),c(2:11)]<-f_i #Inter-flower flight time world1$patchLev
world1$alphaVal[c(2:11),c(2:11)] <- 0.013 #proportion increase in flight cost with load

world1$forageType <- 'omniscient' #Foraging style for flowers within patch

#Constants for foragers
honeybeeConstants<-list(L_max=59.5, #Max load capacity (uL) - Schmid-Hempel (1987)
                       v=7.8, #Velocity (m/s) - Unloaded flight speed (Wenner 1963)
                       betaVal=0.102/59.5, #Reduction of flight speed with load (v-v_load)/(v*L_max)
                       p_i=1, # Max loading rate (uL/s)
                       h=1.5, #Handling time per flower (s)
                       #Unloaded flight energetic cost (J/s) (Dukas and Edelstein Keshet 1998)
                       c_f=0.05,
                       c_i=0.0042, #Cost of non-flying activity
                       H=100 #Time spent in the hive (s)
                       )

#Nest structure (social rate maximizers)
nests1<-list(xloc=1,yloc=1,n=1000,whatCurr='rat',sol=FALSE,constants=honeybeeConstants,eps=0)

#Run model
testOutput1<-forageMod(world1,nests1,2000,verbose=FALSE,parallel=FALSE)

#Visualize distribution of foragers
image(testOutput1$nests$n)

samuelVJrobinson/CPForage documentation built on Jan. 20, 2021, 6:22 p.m.