Running Models

This document applies to version 1.11.00 and above only.


Once a model has been drawn and the details of each of its boxes have been specified, it can be run by clicking on the Run... button on the top line of the model's main window. The window that then appears provides an interface to the underlying execution engine. With this window, the user can step through the model's execution or run a series of trials. In addition, whilst the model is running, the user can watch messages being received and processed by boxes by opening the boxes and displaying the current state or message log.

The Execution Model

The model of computation used by all COGENT cognitive 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. This execution model is both simple and effective.

Initialisation and Experiments

Before it can be executed, a model must be initialised; this empties boxes of their current contents and message lists, and loads relevant boxes with their initial contents. Some box types, such as buffers, have properties which govern when they are initialised, allowing them to accumulate information across a sequence of trials, blocks or even subjects if required.

Boxes can be initialised on each trial, each block, each subject or each session. Correspondingly, there are four levels of initialisation. As well as initialising the appropriate boxes, these levels of initialisation interact with the trial, block and subject counters, such that when, say, a subject initialisation occurs, the subject counter is incremented and the block and trial counters are reset. These counters can be queried by means of special conditions, intended for use by "Experimenter" boxes to facilitate data gathering and analysis.

While developing a model, the different initialisation levels will not generally be required; in such circumstances the default, Initialise Session, which initialises everything and resets all counters, should be adequate.

The Run Window

The run window consists of five sections. From top to bottom these are:

The Execution Buttons

The row of buttons along the top of the Run window allow the user to edit and create scripts, as well as providing the basic interface to COGENT execution. The execution control buttons allow the user to

These buttons' actions depend on the current script; initialisation will reset the system and return to the beginning of the current script. You can use the Run button to execute the script until the end, or Stop the script and then Step forward, a cycle at a time. Clicking Run again will resume execution; Step and Run can be mixed freely.

The current script is saved and restored across sessions, and the model is completely restartable both within and across sessions, so for example you can Stop a running model, close the Run window, shut down COGENT, go on your holidays, restart COGENT and reopen the same model's Run window, whereupon clicking the Run button will continue execution from the point at which it was interrupted.

The Script Editing panel

The sequence of actions to be performed by Run and Step is specified by a script; often this will simply define a single trial, especially in the early stages of model development, but the scripting language permits much more complex sequences, sufficient to specify complex computational experiments. Subcripts can be called using the "repeat" command, so one script can be defined in terms of other scripts. The scripting language also permits specification of box properties, allowing the script to interact with "experimenter" boxes, or even with "subject" boxes for testing a model's sensitivity to property settings.

If you haven't defined your own script, the default script will be used, which looks like this:

	repeat Trial 1 times

This instructs the system to run a single trial, as defined in the subscript "Trial". You can easily change the counter to run the "Trial" script more than once, if you like. The Trial script itself (which you can load if you like) looks like this:

	run to end of trial

Initialisation, as described above, increments the trial counter, loads boxes with their initial contents, and clears all message lists. The "run to end of trial" command instructs COGENT to execute the model in cyclic fashion until it reaches quiescence. Finally, the end(trial) command triggers any special data-analysis routines associated with the end of a trial, such as updating a graph or calculating statistics, using the system_end(Level) special trigger. The end command can be omitted if the model does not require such facilities, but its inclusion is recommended.

All the commands which can appear in scripts are accessible either through the "Command" menu, or by right-clicking on the menu widget at the left hand side of an existing script command. The available commands are:

The "run to end of trial" command will generally only appear in the "Trial" script, but blocks and virtual subjects can be created using the "repeat Subscript N times", "initialise(Level)" and "end(Level)" commands. To define a block of say, 20 trials, you can either edit the default script or create and save your own new one, to look like this:

	repeat Trial 20 times

A more complex scripting example, using trial, block and subject initialisation levels to simulate virtual subjects, and setting properties to manipulate between-subjects experimental variables, is given below.

The Output Trace

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

The output trace window is a ``pagable'' canvas. This means that it has a pair of buttons immediately above the window which allow you to page forwards and backwards through any output (provided 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). Note that these buttons function independently of the model's execution, so it is fine to print or clear a trace while the model is running.

Tracing and Debugging

Models rarely work first time as intended. COGENT provides some tracing facilities to assist with debugging in the form of message logs for all 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 and switch its mode to Current State. (Boxes whose current state does not change will not have this option on their mode menu.) It is thus 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 your 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 the mode of that box's window to Message Log. Message logs are displayed as pagable canvases (like the output trace), so it is possible to page through the log to see all messages. Further, if the message log is open whilst the system is running, messages will appear in the log as they are generated. Thus it is possible to Step through the model and examine the messages generated on any given cycle, or use Run mode, sit back and watch messages arrive and depart.

A complex scripting example

To give an example of the use of scripting to specify complex experimental designs, we can consider how to specify a design using 4 groups of virtual subjects, each receiving a different materials set (Materials1, Materials2, Materials3 or Materials4). Each virtual subject performs 4 blocks of 20 trials, and each group will contain 10 virtual subjects for the complete experimental design.

To define a block of 20 trials, we use the script already defined above, and call it "BlockOf20":

	repeat Trial 20 times

Next we can use this to define a virtual subject, which we can call "OneSubject":

	repeat BlockOf20 4 times

Now we can specify a minimal design, comprising four subjects, one with each materials set (called "FourSubjects"):

	the value of the Materials property in Experimenter is Materials1
	repeat OneSubject 1 times
	the value of the Materials property in Experimenter is Materials2
	repeat OneSubject 1 times
	the value of the Materials property in Experimenter is Materials3
	repeat OneSubject 1 times
	the value of the Materials property in Experimenter is Materials4
	repeat OneSubject 1 times

Note that the box called "Experimenter" must have a user-defined property called "Materials" with the values "Materials1"..."Materials4" for this to work.

Finally we need to run the full complement of 40 subjects, 10 in each condition. If you like, you could change this script to run 10 virtual subjects at a time instead of one, or you could create another script which repeats the "FourSubjects" script 10 times.