Overview

A new feature in VCell 4.2 is the ability to run complex simulations in which one or more parameters can vary according to a specified list of possible values, or spanning a defined range. When running such a simulation, a (possibly large) number of different simulation jobs are actually submitted to the server, and are executed in parallel on different compute nodes. The results from each these simulation jobs can be viewed separately in the data viewer by selecting a particular combination of parameter values.

This capability enables the user to do a “brute force” exploration of the parameter space of a model. This is enabled in a single simulation specification, without having to tediously create, edit, run, and compare many individual simulations that would test the different combinations of parameter values.

Important Note:

Click here for additional information on backward compatibility and upcoming changes.

Specifying Parameter Scans

Recall that the Simulation Editor window allows you to override the default value of any parameter by specifying a different value to be used during the simulation. Up to now, the parameter editing tab of this window had two columns, one showing the default value, and one the changed value (if any; highlighted in red) for all parameters. Starting with VCell 4.2, a third column is introduced, labeled "Scan". If the checkbox in that column is checked, the user can override the default parameter value with not one, but several different values (i.e. a "parameter scan") - and the simulation will be performed with every value specified for that parameter.

When more than one parameter is checked for scanning over a range of values, the simulation will be performed with all possible combinations of values for all scanned parameters. The figure below shows the Simulation Editor window for such a simulation, where 2 parameters where specified for scans, one over a range of 5 values, and one over a range of 3 values, resulting in a total of 15 different combinations for which the simulation is being run.


To specify a scan, one must check the corresponding checkbox for the parameter, and a dialog box will appear as shown below.


There are 2 ways of specifying the actual values to be used for a parameter scan:

• as a range (as in the example above), where the minimum, the maximum, and the number of different values is being specified (and equal interval values will be computed automatically - for the example above, they would be 0.5, 1.375, 2.25, 3.125, 4.0)
• as a list, where any number of comma- or space-separated values can be typed in, as shown in the example below
  
  

Tip: Another new feature in VCell 4.2 is the possibility to specify a non-default parameter value not only as a simple numeric value, but as a free-form mathematical expression involving other parameters. This allows a powerful way of doing parameter scans, where one parameter is being scanned over a range of values, and another is specified to "follow" the scanned parameter, and also take many different values - as in the example below:

Here, the parameter Vmax_bleaching2 is specified as a function of Vmax_bleaching1 (which is scanned over 5 different values). However, in this case, not all 5 x 5 = 25 possible combination of values are used, but only 5 combinations, where whenever Vmax_bleaching1 is being changed, Vmax_bleaching2 is also being changed, but always to the corresponding function (twice Vmax_bleaching1, in this case)

Tip: Specifying a range for a parameter scan has a checkbox "log". If this is used, the intermediate values between the minimum and maximum are not calculated as equal interval values, but as equal ratio values - e.g. for the example below, the values would be 0.1, 1.0, 10, and 100. This allows scanning over several orders of magnitude in a progressive way.

All these different ways of specifying parameter scans and non-default parameter values can be combined at will. The example below shows a simulation specification with several scans and a parameter that "follows" one of the scanned ones, resulting in a total number of combinations of 60 different jobs.

Viewing Results

The Data Viewer window for simulation results for a simulation that specifies a parameter scan retains (for the time being) the same basic layout as for a normal simulation. The only change is an added set of controls that enables the user to traverse the various result sets according to all possible combinations of parameter values.

If the simulation specifies one or more parameter scans, there will be a table of all parameters which have been scanned at the bottom of the results window. The column headers have the name of the parameters, and each column has a variable number of rows listing all actual values that have been used. Below is shown an example results window for the simulation shown at the beginning of this document, that specifies 15 jobs by scanning 2 parameters (Vmax_bleaching1 and Vmax_bleaching2) over 3 and 5 values, respectively. The highlighted values are the ones for which the actual data is being displayed


By default, the Data Viewer will first appear with the first value for each parameter as the selected value to display the data. To see the data for another combination of values, one must click in the parameter value table and select different values for one or more of the parameters, as shown in the example below. All display selections (variables to be displayed, plot controls, etc.) will be retained when moving from one combination of values to another.


Tip: When using parameter scans, certain combination of values can have unexpected results, including failed simulations, while others may lead to successful runs. Also, while the jobs are running, some jobs may have finished while others may have not yet started (for example due to user quota limitations of number of simultaneous jobs). Therefore, it can often happen that some combinations of values have no data to display - in which case the results window will blank out. Please check both the status of the simulation in the status display and browse through all different combination of values when viewing data for parameter scan simulations.