Rob J. de Boer
	Home | Research | Publications | Books | CV |

Grind

Phase plane analysis is a powerful approach for analyzing mathematical models comprised of a few ordinary differential equations (ODEs). grind.R is an R-script allowing one to easily study such models by numerical integration, phase plane analysis, finding and following steady states, and fitting models to data. grind.R is a wrapper around several R-packages developed by Karline Soetaert and colleagues. Grind is easy to use because it just defines a few basic functions:

• run() integrates a model numerically and provides a time plot or a trajectory in the phase plane,
• plane() draws nullclines and can provide a vector field or a phase portrait,
• newton() finds steady states and can provide the Jacobian with its eigenvalues and eigenvectors,
• continue() continues a steady state along a parameter thereby providing a bifurcation diagram,
• fit() fits an ODE model to data by estimating its parameters and depicts the result in a timeplot.

We use grind.R in our courses for biology students at Utrecht University because it allows them to easily analyze mathematical models, and export good quality graphics for reports. Researchers may also like grind.R because it allows them to easily define and study simple ODE models, add if-then-else statements, noise and events, and perform non-linear parameter estimation by fitting ODE models to data. The five grind.R functions have several options with well-chosen defaults such that they are typically well-behaved when no options are provided.

Documentation

The best way to get started is to first read this tutorial which provides a basic phase plane analysis of the Lotka Volterra model, and gives instructions for installation. Next try the phaseplane tutorial which illlustrates the usage of run(), plane(), newton(), and continue(). Other tutorials illustrate more involved examples:

• fitting Illustrates the usage of fit() to estimate parameters by fitting a model to one or more data sets.
• running Illustrates how one can add noise and events while running a model, add columns to the output of run(), explains how to solve delay differential equations (DDEs), and illustrates the definition of maps by analyzing the logistic map.
• saddle Digs a little deeper into phase plane analysis by depicting saddle-node bifurcations, eigenvectors and plotting a separatrix.
• hysteresis Depicts saddle-node bifurcations in a model for a vegetation in arid areas, and shows how increasing the grazing rate can lead to a catastrophic collaps that is difficult to repair due to hysteresis.
• chaos3d Illustrates the usage of the cube() extension of Grind by plotting 3-dimensional nullclines, and plotting a 3-D trajectory approaching a chaotic attractor.
• shiny Illustrates how one can make a Shiny app with sliders to set the parameters of a model.

Finally, the manual explains the options of all functions.

Installation

Grind requires the R-packages deSolve, rootSolve, coda and FME, and these need to be installed beforehand. This can be done by Install Packages in the Tools menu of RStudio. Next download the following files:

• The Grind script.
• The LotkaVolterra model.

and store them in a local directory on your device. Open both files with RStudio, "source" the grind.R script and start excecuting the lotka.R script. Repeat the calls of run() and plane() given in the basic tutorial to test if it all works. All files can also be viewed or downloaded from Grind's directory. The version of Grind is reported as a creation date upon sourcing grind.R. We keep a record of Grind updates in the README file.

The extension cube() allows of 3-dimensional phase spaces with nullclines and trajectories. To use this download cube.R and install the plot3D R-package. Look here for a short manual, and check the chaos3d tutorial for an example.

Grind is an R-version of an earlier C-program called GRIND. For diehards the installation instructions of GRIND are still available on this web page. Consider updating and check this page for a translation of GRIND commands into Grind.