COGENT Version 2.3 Help

Running Models


Once a model has been drawn and the details of each of its boxes specified via the relevant properties and initial contents pages of each box window, the model may be executed either by clicking on any of the Step or Run short-cut icons on any box (or the OOS window), or by selecting the Step or Run item on the Run menu on any box's window. The Step function runs each box in the model through a single processing cycle (as described below). The Run function runs the entire model until processing terminates (or is explicitly halted by the user via the Stop short-cut or menu item). While the model is running, the user may watch messages being received and processed by boxes by opening the boxes and displaying the boxes current state or messages page, as described below.

The Execution Model

The model of computation used by all COGENT models is based on the parallel cyclic execution of each box. A COGENT specification of a model is effectively a specification of the initial state of each box together with a specification of a state transition function for each box. Within this execution model, communication between boxes is handled by simple message passing: messages are removed from a bus at the beginning of each cycle, processed, and then results are placed onto the bus at the end of each cycle. The simplicity of this execution model allows it to generalise in an efficient way to cognitive models built from any COGENT components.

The OOS Window

The OOS window provides access to a variety of widgets for controlling the execution of a model and for monitoring some aspects of the models execution. Figure 1 shows the layout of this window.

Figure 1: The OOS Window

The window consists of a number of buttons on a menu bar, some icon short-cuts to the most commonly used functions, and a notebook with pages labelled Current Script, Variables, Output Trace, OOS Output and OOS Preferences. Each of these pages is described below.

The File and Add Command buttons on the menu bar relate to the script used to control model execution over an extended number of processing cycles. These buttons are only functional when the Current Script page of the notebook is displayed. The Run button provides access to the standard menu of functions for running a model. (See The Menu Bar and Icon Short Cuts for more details.) The Help... button opens a web browser window displaying this help window, and the Done button closes the OOS window.

Current Script

The Current Script page provides access to the experiment script that controls the sequential execution of the model. An experiment script specifies something akin to a procedure within standard experimental psychology for running a model. That procedure might consist, for example, of some initialisation, followed by running a specified number of subjects over a specified number of blocks of trials. COGENT provides a comprehensive scripting language based on concepts from experimental psychology for the specification of experiment procedures. The script shown in Figure 1 above is the default script. It simply runs a single trial, but complex procedures may be specified through options on the Add Command menu. The script shown on the Current Script page may thus be edited (via the Add Command menu) and saved (via the File menu), or other scripts may be created and loaded (via the File menu).


The Variables page, which is only visible after registration, displays values for any currently defined variables. The default script does not employ variables, but they may be used by more complex scripts to control model execution (as described below), and to allow interactions between a COGENT model and the experiment script. As in experimental psychology, variables come in (at least) two types: independent variables, which may be used to pass values from the experiment script into COGENT, and dependent variables, whose value, once set by a COGENT model, is accessible from the scripting language. Further details of the use of variables are given below.

Output Trace

Any output generated when running a model, including initialisation and termination messages, as well as all messages received by data sinks, appears on the Output Trace page. The label above the window indicates where in the current execution the system is up to (in terms of cycle, trial, block, subject and experiment numbers).

The output trace page is a "pagable" canvas: it has a pair of buttons which allow the user to page forwards and backwards through any output (assuming there is more than one page of output).

The contents of the trace may also be printed (via the Print... button) or cleared (via the Clear button), both of which appear on the Output Trace page. These buttons function independently of the model's execution, so it is possible to print or clear a trace while the model is running.

OOS Output

The OOS Output window displays any errors generated by OOS. COGENT attempts to capture all errors before they get to OOS, but some classes of error cannot be caught. If model execution appears to have stopped for no good reason, it is worth checking for errors in this window. If the window contains errors or warning that don't make sense, please contact us at for advice.

OOS Preferences

The OOS Preferences panel provides access to Preferences that control model execution. It replicates the information and controls available in the main preferences window.

The Scripting Language

As described above, the scripting language allows users to specify complex procedures akin to those used in experimental psychology for testing COGENT models.

The Default Script

COGENT provides a simple script which is used in executing all models if no other scripts are specified. By default this script is executed whenever the Run option is selected from the Run menu or when the run short-cut icon is pressed. It is also used by default when the next step of processing is executed via the Step option on the Run or the step short-cut icon.

The default script, as it appears in the Current Script page of the OOS window notebook, is shown in Figure 2:

Figure 2: The OOS Window, showing the Default Script

This script just calls a further script, Trial, once. The Trial script runs a single trial. It is embedded within the repeat loop of the default script so that users may easily modify it to run multiple trials. The Trial script consists of three commands:

     initialise trial
     run till end of trial
     end trial

The purpose of these commands is explained further below.

The script editor may be used to alter the default script, or to replace it completely with one designed to replicate the procedure of a specific experiment.

Basic Scripting Concepts

Trials, Blocks, Subjects and Experiments

OOS recognises several levels of execution, and these levels of execution are represented in COGENT through the initialisation property of most COGENT boxes. Buffers, processes, data sources and sinks, etc., may all be set to initialise on each trial, block, subject, experiment or session. OOS and COGENT assume that a session consists of one or more replications of an experiment. An experiment is assumed to consist of some optional experiment initialisation commands, one or more subjects performing the experiment, and some optional end of experiment commands. This organisation persists down to the basic unit, that of a trial. A block consists of some optional trial initialisation, one or repetitions of a trial, followed by some optional end of block commands.

Given the above, the first step in designing a script is to decide what level of the script is required. Does model evaluation require running a single trial (as in the default script), or does it require running a block of trials (e.g., because of the possibility of learning across trials)? If the latter, then a script oriented towards blocks might be appropriate. If on the other hand the model includes stochastic elements and evaluation requires running a complete experiment (with multiple virtual subjects completing several blocks of trials), then it may be appropriate to design a script at the level of an experiment.

The scripting language provides commands for triggering initialisation and end of unit processing at each level. These are:

initialise experimentInitialise any boxes whose initialisation property is set to experiment trigger to all boxes.
initialise subjectInitialise any boxes whose initialisation property is set to subject trigger to all boxes.
initialise blockInitialise any boxes whose initialisation property is set to block trigger to all boxes.
initialise trialInitialise any boxes whose initialisation property is set to trial trigger to all boxes.
end experimentSend the system_end(experiment) trigger to all boxes.
end subjectSend the system_end(subject) trigger to all boxes.
end blockSend the system_end(block) trigger to all boxes.
end trialSend the system_end(trial) trigger to all boxes.

In addition to the above commands, one further command, run till end of trial, allows running until the end of the current trial (which is defined as point at which processing quiesces).

Independent and Dependent Variables

In experimental psychology the experimenter measures the effect of manipulating the values of independent variables on the values of dependent variables. COGENT and OOS incorporate the concepts of independent and dependent variables.

Independent variables are set within the scripting language via the set variable command (see Figure 3 for an example). Once set a variable's value may be used to set the value of a property within a COGENT box (via the set property command of the scripting language: again, see Figure 3). Note that to access the value of a variable it is necessary to embed the variable's name within the var function. Thus, if lr is a variable, then var(lr) is the value of lr.

Dependent variables may be set within a model through the Set D.V. action available in rules defined within processes and data sources. Their values may then be accessed from the scripting language through the var( ) construct described above. It is then possible to use these values within control structures of the scripting language, and hence design scripts with blocks of commands whose execution is conditional on the model's output.

Control Structures

The scripting language offers the following control structures, each with the obvious interpretation:

     for Var in Set of Values do Block of Commands
     while Condition do Block of Commands
     do Block of Commands while Condition
     repeat Block of Commands N times
     call subscript
     if Condition then Block of Commands

These commands are only available upon registration.

Interacting with Express

The scripting language also provides three commands for interacting with the Express experiment presentation software. Express is a web-based system for presenting experiments and collating results. For more details see The three commands are:

     declare variable
     new subject
     next trial

The functioning of these commands mirrors the corresponding commands in the C API.

These commands are only available upon registration.

A Complex Scripting Example

Figure 3 shows a complex script opened in the Current Script page. This script sets various variables, queries the Express server for a new participant id (pid) and then enters a loop that continues running until the Express server returns a pid of 0.

Figure 3: A Complex Script, Demonstrating Interaction with Express

Tracing and Debugging

COGENT provides a number of facilities for tracing and debugging models that don't quite work as intended. These include message logs for all boxes (which show messages received and generated by boxes) and, for those boxes whose contents change, a window onto their current state throughout processing.

To see the current state of any box, open that box (e.g., by double clicking on it within the box and arrow editor) and switch to the relevant current state panel on the notebook in the bottom section of the window. Boxes whose current state does not change will not have this page on their notebook. In this way it is possible to, for example, open up a buffer and watch its contents change as execution progresses. Hence if something isn't quite right, one possible strategy is to step through the model's execution examining the contents of any suspect buffers at each step. A similar facility is available for data sources and data sinks.

Being able to examine the contents of buffers and data boxes doesn't solve all debugging problems. It can also be useful to see the generation and passing of messages. For this reason all messages are logged and the messages received and sent by any given box can be examined by switching to the Messages page of the notebook on the relevant box's window. Messages are displayed on a pagable canvases, so it is possible to page through the log to see all messages. Further, if the Messages page is open whilst the model is running, messages will appear on the canvas as they are generated. Thus it is possible to step through the model and examine the messages generated on any given cycle, or run the model and watch messages arrive and depart.

It is also possible to trace the evaluation of conditions within specific rules within a process. This may be done by using the trace qualifier on the relevant condition. Once this qualifier has been specified for a condition, attempts to evaluate that condition, and results from successful evaluations, are displayed in the Messages page described above.

COGENT Version 2.3 Help