Chapter 6 PSPMevodyn: evolutionary dynamics

6.1 Theoretical background

In the context of adaptive dynamics the change over evolutionary time in a set of life history traits, characterizing the individuals of a population, can be described by the so-called canonical equation (Dieckmann and Law 1996). This canonical equation specifies a system of ordinary differential equation for the values of a trait vector \(\mathbf{x}=(x_1,\ldots,x_n)\), assuming that the population size is large (infinite) and that evolution is limited by small mutation steps in the trait values. More specifically,

\[\begin{equation} \dfrac{d\mathbf{x}}{dt}\;=\;n_e(\mathbf{x})\, \theta\, \mathbf{\Sigma}\, \dfrac{\partial s_\mathbf{x}(\mathbf{y})}{\partial \mathbf{y}}\biggl|_{\mathbf{y}=\mathbf{x}}\tag{6.1} \end{equation}\]

Here, \(n_e(\mathbf{x})\) is the effective population size, \(\theta\) the mutation probability per birth event, \(\mathbf{\Sigma}\) the \(n\)–dimensional mutational variance–covariance matrix summarizing the distribution of mutations around the resident type \(\mathbf{x}\) and \({\partial s_\mathbf{x}(\mathbf{y})}/{\partial \mathbf{y}}\) is the selection gradient (see also equation (5.1)). As discussed in section 5.1 the selection gradient is sign–equivalent with the following derivative of \(R_0\):

\[\dfrac{\partial R_0(\mathbf{y}, \tilde{E}(\mathbf{x}))}{\partial \mathbf{y}}\biggl|_{\mathbf{y}=\mathbf{x}}\]

This partial derivative of \(R_0\) with respect to life history parameters is the quantity that is used to analyze evolutionary fixed points of PSPMs, as explained in sections 5.1-5.3. Furthermore, we can assume that the effective population size \(n_e(\mathbf{x})\) is proportional to the birth rate of a structured population, \(\tilde{b}(\mathbf{x})\), for a given value of the trait vector. In other words, the evolutionary dynamics of the values of the life history parameters can be assumed to be proportional to the product of the population birth rate and the partial derivative of \(R_0\):

\[\begin{equation} \dfrac{d\mathbf{x}}{dt}\;\propto\;\tilde{b}(\mathbf{x})\,\mathbf{\Sigma}\,\dfrac{\partial R_0(\mathbf{y}, \tilde{E}(\mathbf{x}))}{\partial \mathbf{y}}\biggl|_{\mathbf{y}=\mathbf{x}} \tag{6.2} \end{equation}\]

Given that the software package routinely computes both \(\tilde{b}(\mathbf{x})\) as well as \({\partial R_0(\mathbf{y}, \tilde{E}(\mathbf{x}))}/{\partial \mathbf{y}}\) while analyzing evolutionary fixed points in PSPMs, it is easy to understand that simulating the dynamics of the life history trait values over evolutionary time is a straightforward extension.

Hence, the PSPManalysis package contains in addition to the PSPMdemo and PSPMequi functions a function called PSPMevodyn to simulate the change in an arbitrary number of life history parameters over evolutionary time. As a starting point the function takes an ecological equilibrium state for a particular set of parameters and computes both the partial derivative of \(R_0\) with respect to the evolving parameters and the value of the population birth rate \(\tilde{b}\) in equilibrium. Given these 2 quantities, it computes the value of the right-hand side of expression (6.2) that is proportional to the evolutionary rate of change in the life history parameters as determined by the canonical equation. Unless explicitly specified, the function assumes that the mutational variance-covariance matrix \(\mathbf{\Sigma}\) equals the identity matrix. Finally, it uses the computed value of the evolutionary rate of change to derive new values for the evolving parameters using the Euler method for numerical integration of ordinary differential equations.

6.2 Arguments and output of the PSPMevodyn function

The use of the PSPMevodyn function will be illustrated with the same model as described in section 5.2 and analyzed in section 5.3. In fact, the demo script "Indet_growth" that was already discussed in the previous chapter, performs at the end 2 computations of trait dynamics over evolutionary time. The demo script "Indet_growth" furthermore performs some plotting of the output data generated by these computations.

The general call to the PSPMevodyn function is shown in the command box below.

> output <- PSPMevodyn(modelname = NULL, startpoint = NULL, curvepars = NULL, evopars = NULL, covars = NULL,
                       parameters = NULL, options = NULL, clean = FALSE, force = FALSE, debug = FALSE,
                       silent = FALSE)

The obligatory and optional arguments to the PSPMevodyn function are the following:

  1. The first, obligatory argument to the function PSPMevodyn is the name of the file specifying the PSPM, passed as a string argument. It is unnecessary to include the extension '.R' or '.h' as part of the file name, the PSPMevodyn function will automatically try to locate the appropriate file, checking first for a file implemented in C (with an extension '.h') and subsequently for a file implemented in R (with an extension '.R'). If both a file with an extension '.h' and a file with an extension '.R' are found, the program will use the first one. The program can be forced to use the file with an extension '.R' by including the extension explicitly as part of the filename. The R-commands to analyze the model specified in Indet_growth.h that will be used for the illustration below will therefore all take "Indet_growth" as their first argument. If the file specifying the PSPM can not be found in the current directory, the PSPMevodyn function will ask the user to search in the package directory for a model file with the specified name.

  2. The second, obligatory argument is the initial point of the computation. This initial point should be close to an equilibrium point of the ecological dynamics. The initial point should be a (row) vector with the proper dimension, including as first elements the estimated equilibrium values for all the environment variables and the estimated values of the birth rate for all the structured populations in the model, followed by initial values for all parameters that are allowed to evolve over evolutionary time:

    c(\(<\)environment variables\(>\),\(<\)population birth rates\(>\),\(<\)parameter 1\(>\),\(<\)parameter 2\(>\),....)

    However, environment variables that have been explicitly specified with the program option "envZE" as having a zero equilibrium value and birth rates of populations that have been explicitly specified with the program option "popZE" to be in a zero equilibrium state (see the description of these options under point 7 below), should be omitted from this vector of initial values.

  3. The third, obligatory argument to the PSPMevodyn function is a row vector consisting of 2 elements: (1) the maximum step size in evolutionary time during the integration of the canonical equation and (2) the maximum evolutionary time at which to stop the integration of the canonical equation.

  4. The fourth, obligatory argument to the PSPMevodyn function determines which of the model parameters are allowed to evolve and at which limits further evolution of these parameter is prohibited. This information should be specified by a (row) vector, which for every evolving parameter should include 4 values specifying the index of a structured population, the index of the parameter, its minimum and its maximum value at which its evolution should stop. Therefore, in case of a single evolving parameter, the row vector is of the form:

    c(\(<\)population 1\(>\),\(<\)index 1\(>\),\(<\)minimum 1\(>\),\(<\)maximum 1\(>\))

    The evolving parameter should influence the life history of the individuals of only one structured population in the model, which population is hence evolving. The first element of the vector indicates the index of this evolving structured population that the evolving parameter influences. The second element of the vector indicates the index of the parameter in the array parameter to vary, while the final two elements of the array indicate the minimum and maximum value of the parameter. When two parameters are allowed to evolve, the row vector is of the form:

    c(\(<\)population 1\(>\),\(<\)index 1\(>\),\(<\)minimum 1\(>\),\(<\)maximum 1\(>\),\(<\)population 2\(>\),\(<\)index 2\(>\),\(<\)minimum 2\(>\),\(<\)maximum 2\(>\))

    With multiple evolving parameters the vector has to be extended with 4 values for each of these model parameters with the 4 values specifying the index of the evolving structured population, the index of the evolving parameter as well as its minimum and the maximum value. The number of quadruplets should correspond with the number of initial values for the evolving parameters as specified in the second argument to the function. The integration of the canonical equation is halted before reaching the maximum integration time specified in the third argument to the function, whenever all evolving parameter have reached either their minimum or their maximum limit.

  5. The fifth, optional argument of the PSPMevodyn function specifies the variance–covariance matrix \(\mathbf{\Sigma}\) (see equation (6.1)). This argument can be specified as an \(n\times n\) matrix or as a vector of length \(n\cdot n\), where \(n\) equals the number of evolving parameters. The element \((i,j)\) of the matrix (or equivalently the element \((i\cdot n+j)\) of the vector) should indicate how the selection gradient in trait \(j\) changes the value of trait \(i\) through genetic coupling. If the vector is not specified the matrix \(\mathbf{\Sigma}\) is taken equal to the identity matrix.

  6. The sixth, optional argument of the PSPMevodyn function is a (row) vector of model parameter values. When used, this array should have the same length as the number of parameters in the model (the length of the vector DefaultParameters in R, or the value of PARAMETER_NR in C). When of this length the values will replace the default values of the parameters that are listed in the model specification file. If the array used for this sixth argument is not of the correct length or when it is not specified at all, it will simply be ignored.

  7. The seventh, optional argument of the PSPMevodyn function is a (row) vector of string elements, containing possible options that modify the behavior of the computational module. Most of the options require a value and hence occur as a pair of option name and option value. Only the "test" option (see below) occurs on its own. Options can be specified in any order, but the option value should always immediately follow after the option name. All option values refer to indices of either environment variables, structured populations or individual state variables. Notice, that this index value follows the C-convention of ordering arrays starting at \(0\) (as opposed to R where array indices start at 1). Multiple options can be included into the vector like:

    c("name 1", "value 1","name 2","value 2","name 3","value 3")

    Possible options are:

    1. Option pair c("envZE", "i"): This option pair can be specified several times as part of the option vector of strings. Including this option instructs the computational module to set the value of the environment variable with index "i" equal to \(0\) during the computations of the fixed point problem that determines the selection gradient in the evolving parameters. In addition, the equilibrium condition for this environment variable (as, for example, specified in code block 3.3.1.9 and 3.3.2.12) is ignored and hence not included as condition to hold in the particular equilibrium point. Notice that this can only occur for environment variables that are of the type PERCAPITARATE or POPULATIONINTEGRAL (see section 3.3.1.3 or section 3.3.2.12 above).
    2. Option pair c("popZE", "i"): This option pair can be specified several times as part of the option vector. Including this option forces the computational module to assume that the structured population with index "i" in the model is in a zero equilibrium state. This is the only way to compute an equilibrium with a zero equilibrium state for a particular population. Even if a value of \(0\) would be specified for the birth rate of a population as part of the initial point of the computation, the software would compute the equilibrium curve with a non-zero (non-trivial) equilibrium state for this population. Notice that if a structured population is forced to be in a zero equilibrium state by using the "popZE" option, a zero equilibrium state should also be enforced for all the environment variables that represent integrals over this population distribution (that are hence of the type POPULATIONINTEGRAL).
    3. Option pair c("isort", "i"): This option modifies the output of the equilibrium state of the populations that are stored in an output file with a name of the form <Modelname>-EVODYN-<NNNN>.csb (see below). By default the computational module reports the information about the stable population state distributions by subdividing the axis of the first state variable (the one with index "0") in 100 subintervals of equal length and reporting the statistics for the cohort of individuals within each subinterval. By using the option "isort" the default choice to use the first individual state variable for this subdivision can be changed to the second, third, and so on. Therefore, passing c("isort", "0") as option vector to the PSPMevodyn function is the same as the default behavior: the first individual state variable is used for the subdivision and ordering of the population state distribution, while passing c("isort", "1") would use the second individual state variable for this purpose. Also notice that the number of subdivisions of the individual state variable can be redefined by assigning the dimension COHORT_NR a value different from 100 (see chapter 8).
    4. Option pair c("report", "i"): This option determines how much output the computational module reports to the console. Passing c("report", "1") as option vector to the PSPMevodyn function is the same as the default behavior: the software writes the values of every new solution point that it has computed to the R console. Passing c("report", "2") as option vector to the PSPMevodyn function would make the program write every other computed solution point to the R console, while specifying c("report", "10") as option vector to the PSPMevodyn function implies that every 10th solution point that is computed is written to the R console.
    5. Option c("test"): The last possible option that can be passed to the PSPMevodyn function as part of the option vector is the "test" option. This invokes the computational module in testing mode, which implies that only a single integration of the individual life history is carried out and no iteration to locate a fixed point of a set of equations is performed. In testing mode the computational module reports on the dynamics of the individual state variables, the survival, the cumulative impact on the environment and the expected number of offspring produced by an individual during its different life stage as well as over its entire life. Testing mode is very useful to discover whether or not the model implementation gives sensible results or not.

Four other optional arguments can be passed to the PSPMevodyn function: clean, force, debug and silent. These are all boolean arguments that hence have to be passed to the PSPMevodyn function as \(<\)option name\(>\)=TRUE or \(<\)option name\(>\)=FALSE, the latter being the default value of all options (Specifying these options as argument is hence only useful when setting them equal to TRUE). Unlike the previous arguments, which all modify the computations to be performed, these options modify the behavior of the PSPMevodyn function itself, in particular the compilation of the model specific file into a dynamic library module that can be executed from R. Also unlike all the previous arguments that can be passed, these arguments can be passed in any order and at any position, the PSPMevodyn function will filter these 3 optional arguments from the argument list before passing the filtered argument list to the computational routine.

  • Option clean: When clean=TRUE is passed as argument, this argument instructs the PSPMevodyn function to delete all result files that have been generated during previous calculations with the model. These result files have names of the form <Modelname>-<Type>-<NNNN>.err, <Modelname>-<Type>-<NNNN>.csb and <Modelname>-<Type>-<NNNN>.out, in which <Modelname> refers to the name of the model, <Type> refers to the type of computation that has been performed, which in the case of PSPMevodyn equals EVODYN, and <NNNN> is a unique number that distinguishes consecutive computations of the same type of curve with the same model. Deleting all the output files from previous computations and/or the compiled program executables that the package has generated can also be done separately. The package implements a function PSPMclean() to delete all .bif, .err, .csb and .out files and/or all executable files that are present in the current working directory.

  • Option force: When force=TRUE is passed as argument, it instructs the PSPMevodyn function to force re-compilation of the model specific file into a dynamic library module that can be executed by R. This option will usually not be needed by normal users, as the PSPMevodyn function automatically recompiles the computational module when the model specific file with an '.h' extension is more recently changed than the compiled dynamic library file. However, if for some unclear reason this automatic recompilation fails, the force option can be used to initiate re-compilation.

  • Option debug: When debug=TRUE is passed as argument, it instructs the PSPMevodyn function to turn on debugging flags while compiling the model specific file into a dynamic library module. This option can be useful to detect programming mistakes in the model-specific file that are otherwise hard to track down. The downside is that depending on the version of R that is used, turning on debugging flags during compilation may generate a lot of output, including warnings about standard files of the operating system that are perfectly correct. It is hence not so easy to spot among all these messages the warnings that relate to the model-specific code that has been implemented.

  • Option silent: When silent=TRUE is passed as argument, it instructs the PSPMevodyn function to suppress all messages from the compilation of the model specific file into a dynamic library module. This option is useful to prevent cluttering the console with superfluous messages once a model specific file has been tested sufficiently and functions without problems.

The computational module generates on execution a single list object as output with 2 member elements (see the help page on PSPMevodyn using ?PSPMevodyn). The first element of the output list, output$curvepoints contains the numerical information of the points along the computed curve. This variable output$curvepoints is a matrix, in which each row represents one solution point along the curve. The columns contain the evolutionary time value, the equilibrium value of all environment variables, the equilibrium value for the birth rate of all structured populations in the problem, the current value of the evolving parameter(s), the equilibrium value of all interaction variables defined in the routine Impact(), the per capita growth rate of all environment variables for which this is relevant (those of the type PERCAPITARATE), for each of the structured populations the expected number of offspring produced by an individual during its lifetime (\(R_0\)) and finally the norm of the right-hand side of the system of equations that is solved to obtain the ecological equilibrium. The latter quantity (referred to as RHS norm) measures how close the computed equilibrium point is to the true solution.

The second member element of the output list, output$curvedesc, contains the description of the executed calculation, which includes the command-line that is used for the invocation of the computational routine, the values of all parameters used for the current computation and a header line indicating the meaning of all the output variables produced by the computational module. This textual information is also printed to the R console at the end of calculations. In fact, the PSPMevodyn function prints its report on the calculations by execution of the statement cat(output$curvedesc, sep='\n').

6.3 An example session using the PSPMevodyn function

The demo script "Indet_growth" illustrates the use of the PSPMevodyn function by simulating the evolutionary dynamics in the parameter \(q\), the scaling power in the model implemented in Indet_growth.h that relates the resource ingestion rate to individual body size (see section 5.2). The particular call to the PSPMevodyn function is shown in the following R command box:

Command box 6.3.A
> output1 <- PSPMevodyn("Indet_growth", c(0.22, 0.03554, 1.0), c(0.05, 10), c(0, 6, 0.5, 1.5))

Building executable Indet_growthevodyn.so ...

<...compilation output lines suppressed in this box...>

 0.005000, 2.20000000E-01, 3.55373787E-02, 1.00000000E+00
 0.010000, 2.18793851E-01, 3.19778211E-02, 9.92635669E-01
 0.015000, 2.18089189E-01, 2.97666950E-02, 9.87408855E-01
<...output lines suppressed in this box...>
 2.555312, 2.15592974E-01, 1.75885630E-02, 9.38263364E-01
 2.605312, 2.15592974E-01, 1.75885630E-02, 9.38263363E-01
 2.655312, 2.15592974E-01, 1.75885629E-02, 9.38263363E-01

> cat(output1$curvedesc)
 #
 # Executing : PSPMevodyn("Indet_growth", c(0.22, 0.03554, 1), c(0.05, 10), c(0, 6, 0.5, 1.5), NULL, ....
 #
 # Parameter values  : 
 #
 #  Delta     :  0.1            Rmax      :  2              Sb        :  0.05         
 #  Sj        :  1              Sm        :  2              Imax      :  1            
 #  q         :  1              Sigma     :  0.5            T         :  0.1          
 #  p         :  1              Mu        :  0.01         
 #
 # Index and name of evolution parameter #1                       : 6 (q)
 # Index of structured population for which parameter #1 evolves  : 0
 #
 #  1:Evol.time          2:E[0]          3:b[0]             4:q       5:I[0][0]       6:I[0][1] .... 
> output1$curvepoints
      Evol.time      E[0]       b[0]         q   I[0][0]   I[0][1]   I[0][2]     R0[0]     RHS norm
 [1,]  0.005000 0.2200000 0.03553738 1.0000000 0.1780000 0.5323024 0.2767885 1.0000000 4.892178e-09
 [2,]  0.010000 0.2187939 0.03197782 0.9926357 0.1781206 0.5210074 0.2886318 1.0000000 6.853246e-09
 [3,]  0.015000 0.2180892 0.02976670 0.9874089 0.1781911 0.5124553 0.2975042 1.0000000 4.976306e-09
<...output lines suppressed in this box...>
[67,]  2.555312 0.2155930 0.01758856 0.9382634 0.1784406 0.4194358 0.3916580 0.9999993 9.697419e-07
[68,]  2.605312 0.2155930 0.01758856 0.9382634 0.1784406 0.4194358 0.3916580 0.9999993 9.697423e-07
[69,]  2.655312 0.2155930 0.01758856 0.9382634 0.1784406 0.4194358 0.3916580 0.9999993 9.697427e-07

Starting from an (approximate) equilibrium resource density of \(0.22\) and an (approximate) equilibrium birth rate value of \(0.03554\) for an initial parameter value \(q=1.0\) the evolutionary dynamics is simulated from \(t=0\) (this starting time is always taken equal to \(0\)) till \(t=2.681562\). The simulation stops at this time point, because the evolution in \(q\) has converged to a fixed value and \(q\) is not going to change any further. This final value of \(q\) hence represents a stable and attracting evolutionary state (CSS). In general, the computation will be stopped whenever all evolving parameters have stabilized at a constant value.

The starting point of the computation is contained in the second argument to the function PSPMevodyn, as shown above, whereas the first argument defines the basename of the file with the model implementation "Indet_growth". The third argument to the function PSPMevodyn sets the maximum evolutionary time step to \(0.05\) and the maximum time at which to stop the evolutionary simulation to 10.0, but the latter is never reached because of the convergence to an evolutionarily constant \(q\) value. The fourth argument to the function PSPMevodyn contains a single quadruplet of values, given that only a single parameter is allowed to evolve, defining the index \(0\) of the structured population that is evolving, the index of the parameter \(q\) in the parameter array as defined in Indet_growth.h and its minimum and maximum value at which to stop the computations. The further arguments are left undefined, which implies that the variance–covariance matrix \(\mathbf{\Sigma}\) (refer to equation (6.1)) defaults to the identity matrix and default values are used for all non-evolving model parameters. These default values are defined in the file Indet_growth.h.

During the computations the program reports the current value of the evolutionary time, the ecological equilibrium values of the resource density and the population birth rate and the current value of the evolving parameter \(q\). In the R command box above the values of the computed points along the evolutionary trajectory are saved in the output list element output1$curvepoints, the contents of which are inspected after the PSPMevodyn function finishes and it has printed out the textual information about the computation. The demo script "Indet_growth" uses the data contained in the first and the fourth column of output1$curvepoints to plot the time course of evolutionary change in the parameter \(q\).

In the following R command box, a similar trajectory of the evolutionary dynamics is computed starting from the same ecological equilibrium, but now both the parameter \(q\) and the parameter \(p\), which relates the maintenance costs to individual body size (see section 5.2), are allowed to evolve. To that end, the starting point of the computation is extended with an initial value for the parameter \(p\) (1.0) and the fourth argument of the PSPMevodyn function is extended with 4 values that indicate the index \(0\) of the structured population that is evolving, the index of the parameter \(p\) in the parameter array as defined in Indet_growth.h and its minimum and maximum value at which to stop the computations. In addition, the maximum integration time at which to stop the evolutionary computations is increased to 100. Otherwise, the command line of this computation is identical to the one shown in R command box 6.3.A.

Command box 6.3.B
> output2 <- PSPMevodyn("Indet_growth",c(0.22, 0.03554, 1.0, 1.0),c(0.05, 100),c(0, 6, 0.5, 1.5, 0, 9, 0.5, 1.5))
Dynamic library file Indet_growthevodyn.so is up-to-date

 0.005000, 2.20000000E-01, 3.55373787E-02, 1.00000000E+00, 1.00000000E+00
 0.010000, 2.18004640E-01, 2.95832099E-02, 9.92635669E-01, 1.00669514E+00
 0.015000, 2.17277498E-01, 2.70926149E-02, 9.88746582E-01, 1.01012886E+00
<...output lines suppressed in this box...>
59.942812, 2.13281908E-01, 1.20369433E-02, 4.99967380E-01, 5.34914891E-01
59.992812, 2.13281908E-01, 1.20369433E-02, 4.99967380E-01, 5.34914891E-01
60.042812, 2.13281908E-01, 1.20369433E-02, 4.99967380E-01, 5.34914890E-01

> cat(output2$curvedesc)
 #
 # Executing : PSPMevodyn("Indet_growth", c(0.22, 0.03554, 1, 1), c(0.05, 100), c(0, 6, 0.5, 1.5, ....
 #
 # Parameter values  : 
 #
 #  Delta     :  0.1            Rmax      :  2              Sb        :  0.05         
 #  Sj        :  1              Sm        :  2              Imax      :  1            
 #  q         :  1              Sigma     :  0.5            T         :  0.1          
 #  p         :  1              Mu        :  0.01         
 #
 # Index and name of evolution parameter #1                       : 6 (q)
 # Index of structured population for which parameter #1 evolves  : 0
 # Index and name of evolution parameter #2                       : 9 (p)
 # Index of structured population for which parameter #2 evolves  : 0
 #
 #  1:Evol.time          2:E[0]          3:b[0]             4:q             5:p       6:I[0][0] ....

> output2$curvepoints
        Evol.time      E[0]       b[0]         q         p   I[0][0]   I[0][1]   I[0][2] R0[0]     RHS norm
   [1,]  0.005000 0.2200000 0.03553738 1.0000000 1.0000000 0.1780000 0.5323024 0.2767885     1 4.892178e-09
   [2,]  0.010000 0.2180046 0.02958321 0.9926357 1.0066951 0.1781995 0.5129883 0.3003329     1 4.469165e-09
   [3,]  0.015000 0.2172775 0.02709261 0.9887466 1.0101289 0.1782722 0.5013552 0.3134773     1 5.888298e-09
<...output lines suppressed in this box...>
[1213,] 59.942812 0.2132819 0.01203694 0.4999674 0.5349149 0.1786717 0.3555098 0.3474280     1 1.283301e-06
[1214,] 59.992812 0.2132819 0.01203694 0.4999674 0.5349149 0.1786717 0.3555098 0.3474280     1 1.283300e-06
[1215,] 60.042812 0.2132819 0.01203694 0.4999674 0.5349149 0.1786717 0.3555098 0.3474280     1 1.283300e-06

The output in the command box above shows that again the evolutionary dynamics are halted before the maximum time (100) is reached. As soon as an evolving parameter (here the parameter \(q\)) drops below its minimum value or exceeds its maximum value, as specified in the fourth argument to the function PSPMevodyn, it is stopped from evolving further, which in the case of the computation shown above leads to convergence to a constant value of the second evolving life history parameter \(p\). This convergence ultimately halts the computation. The computation is therefore in this case stopped because no further evolution occurs, but computations will also stop whenever all evolving parameters have reached either their minimum or their maximum limit.

6.4 Output files generated by the PSPMevodyn function

The computational module that is produced by the PSPMevodyn function generates 3 output files. The name of these files is always of the form <Modelname>-EVODYN-<NNNN>.<ext>, in which <Modelname> is the same as the name of the file specifying the model excluding its '.R' or '.h' extension, <NNNN> is a 4-digit number that is unique for the current computation and .<ext> is the extension, which can be either .err, .csb or .out. The unique number distinguishes the same types of curve computations for the same model from each other. The number is obtained by considering increasing values of <NNNN> (i.e., 0000, 0001, 0002 and so forth) and testing whether result files with the particular index are already present. The program uses the first value of <NNNN> that is not in use.

The file called <Modelname>-EVODYN-<NNNN>.err that is generated during the computations contains information about the numerical progress of the computations. It reports details on the steps taken during the Newton iteration, the convergence to the solution, as well as information about the steps taken along the curve that is being computed. This file can be informative in case the computation of a particular curve stops for unknown reasons, but is otherwise of little use.

The output file called <Modelname>-EVODYN-<NNNN>.out holds the same information as is contained in the two elements of the output list returned by the PSPMevodyn function, output$curvepoints and output$curvedesc (see the help page on PSPMevodyn using ?PSPMevodyn). The first lines of this file all start with a '#' sign and contain the information about the run performed, which is also contained in output$curvedesc and can be listed by the statement cat(output$curvedesc, sep='\n'). Following this descriptive header the file contains columns with computational results that are also contained in the variable output$curvepoints (see, for example, R command box 6.3.A). In fact, the two elements of the output list, output$curvepoints and output$curvedesc, are generated by reading the contents of the file <Modelname>-EVODYN-<NNNN>.out from disk after the computations have ended, storing all lines that start with a '#' sign into a single string variable output$curvedesc, while storing the information on all other lines into the data matrix output$curvepoints.

The file called <Modelname>-EVODYN-<NNNN>.csb contains for every curve point that has been computed information on the parameters, for which the point has been computed, the equilibrium values of all environment variables and the stable distribution of all structured populations in the model. This is a binary file, the content of which can be accessed from R using the function csbread. For example, the file Indet_growth-EVODYN-0000.csb is generated by the invocation of the PSPMevodyn function in R command box 6.3.A. Its contents can be listed by:

Command box 6.4.A
> csbread("Indet_growth-EVODYN-0000.csb")

States in file Indet_growth-EVODYN-0000.csb:

    1: State-5.000000E-03
    2: State-1.000000E-02
    3: State-1.500000E-02
<...output lines suppressed in this box...>
   71: State-2.581562E+00
   72: State-2.631562E+00
   73: State-2.681562E+00

The structure called State-1.500000E-02 contains the population state in the ecological equilibrium that occurred at time point \(t=0.015\) during the simulation of evolutionary dynamics, as its name suggests. Its contents can be read into the workspace by issuing the command csbread("Indet_growth-EVODYN-0000.csb",3) or csbread("Indet_growth-EVODYN-0000.csb","State-1.500000E-02").

Loading this state into the R workspace reveals it to be a list containing various arrays of numbers, as shown in the following box:

Command box 6.4.B
> popstate <- csbread("Indet_growth-EVODYN-0000.csb", "State-1.500000E-02")
> popstate
$EvoTime
[1] 0.015

$EvoPars
[1] 0.9874089

$Parameters
 [1] 0.1000000 2.0000000 0.0500000 1.0000000 2.0000000 1.0000000 0.9874089 0.5000000 0.1000000 1.0000000
[11] 0.0100000

$Environment
[1] 0.2180892

$Pop00_BirthStates
     Istate00 Istate01
[1,]        0     0.05

$Pop00
            Density   Istate00   Istate01
  [1,] 5.571417e-01   10.00401 0.05718031
  [2,] 4.528618e-01   30.72728 0.07462823
  [3,] 3.680999e-01   51.45054 0.09665210
<...output lines suppressed in this box...>
 [98,] 1.037446e-09 2020.16080 1.98742578
 [99,] 8.432681e-10 2040.88406 1.98758088
[100,] 6.854340e-10 2061.60733 1.98773223

The first element of the list (called $EvoTime) representing the population state State-1.500000E-02 is the value of the evolutionary time \(t\) at which the current population state occurs. The second element, an array called $EvoPars, contains the values at evolutionary time \(t\) of all the evolving model parameters. The third element, an array called $Parameters, contains the values of all the model parameters for which the population state has been computed, while the fourth member of the list contains the equilibrium values of all environment variables. The two subsequent arrays in the list characterize the stable population distribution, of which the first (called $Pop00_BirthStates) specifies the state at birth of the individuals. The other (called $Pop00) is a two-dimensional array characterizing the population distribution in equilibrium with the first column $Pop00[,1] representing the density profile of the equilibrium population and the subsequent columns $Pop00[,2] and $Pop00[,3] representing the average values of the individual state variables with index \(0\) and 1 (corresponding to individual age and body size in the model implemented in Indet_growth.h), as shown in the R command box above. If individuals are characterized by more than two individual state variables, the values of these follow in additional columns of the two-dimensional array $Pop00. The R command box above also illustrates that the dimension of the array $Pop00 indicates that the population is represented by 100 cohorts of individuals (see chapter 8 for the option to change this number). The number of individuals in cohort \(i\) is given by the array element $Pop00[i,1], while the average value of the individual state variable with index \(0\) and 1 (average age and average size in the current model) are given by $Pop00[i,2] and $Pop00[i,3], respectively.