Running example models and using a cluster

The purpose of these tutorials is to learn how to run the example growth simulations included in GFtbox. It is assumed that you have already downloaded the GFtbox software and have Matlab installed.

Getting Started

1) Explaining the tools. In these tutorials, we will be using GFtboxCommand and ClusterMonitor. This section explains the purpose of these functions.

2) Running a growth simulation for an example model. This section demonstrates how to use GFtboxCommand to run a growth simulation. The model used for the simulation is an example model included with the GFtbox.

3) Altering the simulation parameters. Following on from part 2, here we show how to adjust a simulation parameter within GFtboxCommand. Specifically, we alter the value of dt, the temporal resolution of the simulation, and show how it can be used to verify the correctness of the value specified in the published literature.

4) Altering the model parameters. Finally, we demonstrate how a number of model parameters can be varied by specifying a range of values for each model argument. We show how the computationally expensive task of simulating all combinations of specified ranges can be more efficient if a computer cluster is used via the ClusterMonitor tool.

1 Explaining the tools

GFtboxCommand

This is a command line version of the GFtbox. By command line, we mean that all program functions are operated via typed commands rather than by a graphical interface. Like GFtbox, GFtboxCommand is capable of running growth simulations of an interaction function, and allows the user to specify model and simulation parameters. Unlike GFtbox, this also allows the user to select ranges of values for a number of parameters, and will automatically spawn multiple simulations which explore the various combinations of those parameters. This can be used to evaluate the effect of various parameters on the growth of a given model.

ClusterMonitor

Provides a graphical interface for managing simulations running remotely on a computer cluster. Specifically, it allows you to see which projects are present and running on the cluster, to retrieve the completed projects, to generate images of the simulations at specified stages of growth, and to remove projects from the cluster. If you do not intend to use a computer cluster, then you will not need to use ClusterMonitor.

2 Running a growth simulation for an example model

This tutorial is aimed at running a growth simulation for one of the example interaction functions included with the GFtbox. The purpose of this exercise is to firstly demonstrate how simulations can be invoked using GFtboxCommand, and secondly to show how to reproduce experimental results (specifically, those published in Kennaway et al [2011]) given an interaction function.

Assuming Matlab is installed on your computer, and the latest GFtbox has been downloaded, you can add the GFtbox directory to Matlab's search path, which makes the toolbox accessible from any other path that you choose to work from. For a short tutorial on how to do this, please click here.

Once the GFtbox is added to Matlab, you are ready to run a growth simulation using GFtboxCommand. In this example, the model that we will simulate is called GPT_CASE_RST. Results generated using this model are published in Kennaway et al (2011). By running this simulation, we can confirm the results in the published literature and investigate the suitability of the various parameters.

2A - Running a simulation

The following command can be typed into Matlab to run a simulation of the GPT_CASE_RST interaction function, which contains three growth models: R, S and T. Three separate simulations are run sequentially on your computer, one for each model, each producing results corresponding to five intervals in the growth simulation.

       GFtboxCommand('State','Start','Path','/GrowthToolbox/Models/Published/Kennaway-etal-2011/','Name','GPT_CASE_RST',...
       'Stages',[20 100 140 180 200],'modelname',[1:3]);

GFtboxCommand accepts parameters in pairs, separated by a comma, e.g. 'modelname',[1:3]. The parameters entered here are: State, Path, Name, Stages and modelname.

Batches of simulations can be constructed using the State parameter, as described by this short tutorial. Here, the value 'Start' is specified, which means that we have finished constructing our batch and want to run it now. In this case, our batch will contain only the simulations specified by the remaining GFtbox parameters.

The optional Path parameter refers to the location of the folder (or directory) on your computer where the model interaction function you wish to simulate is stored. Name, is the name of the folder itself. In this case, we are using the GPT_CASE_RST folder which is included in the GrowthToolbox. You may wish to copy this folder elsewhere, if you intend to make changes to the interaction function.

During a growth simulation, a mesh can be generated at each time step of the simulation, which provides a visual representation of the growth of the biological tissue, given the various parameters of growth specified by the interaction function and how they have changed over time. Put another way, the mesh shows exactly what the growing tissue actually looks like. Stages refers to the points in the simulation (measured in hours) at which meshes should be generated and saved. In this example, five stages of growth will be written to disk. These values are chosen to best capture the appearance of the tissue at important stages of the tissue growth.

The final parameter listed here is modelname. This is a model-specific parameter, and in this case the GPT_CASE_RST interaction function contains three separate models for plant growth, allowing the desired model to be a selected. Here, the value [1:3] is specified, which is evaluated in the same way as entering [1 2 3]. This instructs GFtboxCommand to run three separate simulations, one for each of the growth models contained in the interaction function.

The function of every permissible parameter is given by keying the following command into Matlab:

       help GFtboxCommand

2B - Generating images from a completed simulation

Once a growth simulation is completed, the project folder (GPT_CASE_RST, in our example) will contain another folder named "movies". Within movies, there are folders which contain results for the executed simulations. As was instructed in 2A, here we can see three folders corresponding to simulations for the three separate models. Within the first folder are three items.

NB. The results produced may not be visibly identical to those in the published literature. This is because of small, random perturbations which are applied to the initial model meshes to stop them from containing surfaces which are perfectly flat, and therefore biologically unrealistic. The results produced should be qualitatively but not quantitatively the same.

4 Altering the model parameters

3 - Will show dt changed individually, submitted as a range, submitted to a cluster - Will say that Terminal or SSH does same thing, and can still be useful