COGENT Version 2.3 Help

Creating and Editing Models

The Box and Arrow Diagram Editor

The box and arrow editor is accessed by selecting the Diagram page from a model's window when the model has been opened in edit mode (e.g., by double-clicking on the model's icon in the Diagrammatic History view).

The box and arrow editor consists of a large canvas in which a box and arrow diagram may be displayed and a palette of buttons corresponding to the various types of box and arrow. By default this palette is located beneath the canvas.

Instances of boxes may be created and positioned on the canvas by clicking on the appropriate icon on the palette and then clicking on the required position on the canvas. This will result in a box of the selected type being drawn on the canvas. Arrows may be drawn between existing boxes by selecting the appropriate arrow type (a read arrow or a send/write arrow) and then clicking on the arrow's source box, dragging the mouse to the target box, and then releasing the mouse button.

A number of techniques may be used to modify elements once they have been placed on the diagram canvas. Boxes on the canvas may be repositioned by dragging them to a new location (using the left mouse button), and double clicking on a box will open the box, allowing inspection and modification of its contents. All diagram elements are also responsive to clicks with other mouse buttons. Right-clicking on a box, for example, pops up a menu with the following options:

Canvas:Operate on the entire box and arrow canvas. Selecting this item pops up a further window with options to: Clear the box and arrow diagram; Reload the diagram from disk; Import a text formatted representation of the diagram from disk; and Export a text formatted representation of the diagram to disk.
Open:Open the box for editing or viewing. This pops up a new window displaying the details of the selected box. If the box is opened in edit mode, those details may be edited and changes saved.
Change Type:Change the type (i.e., class) of the selected box. Selecting this menu item pops up a further menu from which the desired resultant type may be selected. Where sensible, the contents of boxes are preserved across changes to their type.
Print...:Print the contents of the selected box. See the separate documentation on printing for further details.
Promote:Promote the selected box out of the current box and arrow diagram and into its parent diagram. This option is only available for boxes that are embedded within compound boxes.
Demote:Demote the selected box into an existing compound box located on the same diagram. This option is only available for diagrams that include compound boxes.
Duplicate:Create a duplicate copy of the selected box. This function copies the entire contents of the selected box and all arrows to/from that box. The duplicate box is placed on the canvas slightly to the right and below the original.
Delete:Delete a box from the diagram and place it on COGENT's clipboard. Objects on the clipboard may be pasted back onto a diagram at a later point in time if desired.
Paste:Move a box from the clipboard onto the diagram canvas. Note that the clipboard is a stack-like data structure, so multiple items can be cut onto it. They will then be pasted back in the reverse order in which they were cut (i.e., most recent first).

Right-clicking on an arrow pops up a menu with the following options:

Toggle Type:Change the type of arrow, from read to write or vice versa.
Reverse:Reverse the arrow (i.e., swap its source and target boxes).
Delete:Delete the arrow from the diagram. Deleted arrows are not placed on the clipboard, and consequently cannot be pasted back onto the diagram.

For both box and arrow menus, items that are inappropriate in the current context will be greyed out and will not function.

Users with three-button mouses may use the middle button to create and redirect arrows.

Other Editors

Different types of COGENT box may contain different types of elements. Compound boxes, for example, contain box and arrow diagrams. Processes, by contrast, contain rules and condition definitions. Correspondingly, compounds have a "Diagram" view whereas processes have a "Rules and Condition Definitions" view. Where sensible, the functionality of the mouse buttons on these corresponding views is replicated. Thus, double-clicking on any object within any of these views (whether it be a box, a rule, or a buffer element) will open an editor on that object, and right-clicking will pop up a menu with options similar to those available from the box and arrow editor.

COGENT provides special purpose editors for all types of elements. In particular, in addition to the box and arrow editor described above, it provides special purpose editors for rules, condition definitions, buffer elements and data elements. The editors are designed to be easy to use, and not documented in detail here.

Working With Properties

The properties panel of each box includes five buttons: Add, Edit, Delete, Freeze and Thaw. The first three of these buttons are for specifying user-defined properties. The last two relate to fixing property values by freezing or thawing them. Buttons which are not applicable for a given box are greyed out.

Freezing and Thawing Properties

Each box has a set of properties whose values govern the behaviour and appearance of the box. The basic set of properties associated with a box is determined by the box's class. The various sub-classes of buffer, for example, have properties relating to access and decay. Properties are effectively parameters, or independent variables. When a modeller specifies a box he/she may have some theoretical commitment to the values of certain properties, but be open to values of others. One might, for example, be committed to a buffer having limited capacity, but not be committed to the precise capacity. COGENT's property freezing mechanism allows the modeller to express such commitments. If the modeller freezes a property (by selecting the property's name from the Freeze menu button), then the property's value will be fixed (to whatever it was when it was frozen), and it will not be possible to alter the value unless it is explicitly thawed (via the Thaw menu button).

Frozen properties are greyed out on the properties panel of the box to which the property relates, so it is easy to see the value of a frozen property. It just can't be adjusted. Nor can it be set via the OOS scripting language. In addition, properties that are not frozen are displayed on the Properties page of their ancestor boxes. That is, if a box is contained within a compound, and the box has properties that are not frozen, then those properties will appear (suitably labelled) on the Properties page of the compound. The reason for this is that the parameters of the embedded box are also parameters of the compound: altering the values of the embedded properties will alter the behaviour of the compound.

The intention behind COGENT's property freezing facilities is that by specifying precisely those properties which are free parameters of each box, and by automatically propagating those parameters onto the Properties page of the parent (and the parent's parent, etc.), one can provide a clean specification of the parameters of ones model, and view/adjust this specification from the Properties page of the top-most box's window.

The mechanism replaces a somewhat clumsy mechanism of property promotion available in earlier versions of COGENT.

User-Defined Properties

It is possible to augment the standard set of properties associated with a box through the addition of user-defined properties. A user may, for example, have a process within his/her model that could logically function in one of several ways (e.g., using a continuous representation or a discrete representation). The operation of the process may be parameterised by specifying a user-defined property (e.g., "Discrete") that may be set to true or false. The user-defined property will appear on the panel of properties with the process' other properties, and may be set in precisely the same way. The value of the property may then be referenced in the rules and defined conditions so that the behaviour of the process is determined by the value of the property.

Several different types of user-defined properties are available, including Boolean (i.e., having values of true/false), integer, real, bounded real, enumerated and string. While user-defined properties may be added to boxes of any class, they are currently only really useful in processes, where their values can be queried by rules and defined conditions, and hence where their values can actually influence model behaviour.

The Clipboard

When elements (including rules, condition definitions, and boxes) are deleted from a model they are placed on a global clipboard. Elements on this clipboard may then be pasted back into any appropriate place in the model. The clipboard is actually an unbounded stack. All deleted elements are pushed onto this stack. Pasting from the clipboard is only possible if an element on the clipboard is appropriate for the destination of the paste. That is, for example, it is only possible to paste from the clipboard into a compound box if a box has previously been placed on the clipboard. If the clipboard is empty, or contains only deleted rules, condition definitions, or buffer elements, then pasting into a compound box will not be possible. Similarly, it is only possible to paste into a buffer if the clipboard contains buffer elements or condition definitions.

Paste examines the clipboard and selects the top-most element that is appropriate for the destination of the paste. This may not actually be the top-most element on the clipboard. For example, if the clipboard contains a box and a rule (with the box being the most recently deleted element), pasting into a process will be possible, and the result of that paste will be the inserting of the rule from the clipboard into the process.

Paste buttons should only be active when pasting is actually possible. Successful pastes result in the deletion of the pasted element from the clipboard.

All this means you can, for example, delete some rules from a process, then deleted some boxes from a compound, then delete some elements from a buffer, then paste the deleted boxes into another compound, the deleted rules into another (or the same) process, and ignore the deleted buffer elements.

The contents of the clipboard may be viewed and selectively edited by clicking on the Clipboard... button from the top line of buttons on the Research Programme Manager window. Elements on the clipboard do not persist across COGENT sessions: quitting COGENT clears the clipboard.

Undo and Redo

The Undo/Redo facility allows edits to a model to be reversed. There are four broad classes of edit that can be made to a model: box-related edits (e.g., cutting, pasting, inserting and deleting boxes), arrow-related edits (e.g., inserting, deleting, and reversing arrows), clause-related edits (e.g., inserting, modifying, cutting and pasting buffer and process elements), and property-related edits (e.g., setting, adding and deleting items on a box's properties panel).

All edits to each box are stored so that, in case of error, they can be undone. Edits that are undone can then be redone, unless further edits are made between the undo and attempted redo. Edits can even be reversed after a box has been saved. Note however that when you exit COGENT all undo lists are discarded. You cannot therefore restart COGENT and undo edits from a previous session.

Each box stores its edits locally, so selecting Undo or Redo from the Edit menu of a given box will undo/redo the last edit to that particular box, not the last edit to the model itself.

COGENT writes all edits to disk. If COGENT should crash it is able to recover edits by reading this edit log and applying them to your model. (Whenever a model is saved the edit log is deleted.) If, on opening a model, COGENT discovers an edit log associated with any of the boxes in that model it will ask if it should attempt a recovery.

Note that it is possible to make a sequence of changes to a model with one set of mouse movements. For example, an existing arrow between two boxes can be diverted to and from a third box by dragging the middle of the arrow with the middle mouse button. This edit is recorded as three separate changes: deleting the original arrow and added two separate arrows. Undoing the edit will undo each step separately. That is, to completely reverse the edit it is necessary to undo the last three actions.


COGENT's find facility allows the user to search for all occurrences of a given term in the rules, condition definitions, buffer elements, etc. of a model. Selecting Find from the Edit pull-down menu on any box opens the find dialogue, shown in Figure 1.

Figure 1: The find dialogue

To search for a specific term, enter the term in the Find: field and hit the Search button. COGENT will search for occurrences of the Find term (i.e., terms which literally match it) in the box from which Find was selected (and, if the box from which Find was selected is a compound box, all sub-boxes). Find displays its results in a list in the lower half of the find window. Selecting any entry in that list will pop-up the window containing the object (rule, condition, buffer element, etc.) that contains the find term, with the object selected.

Note that find is currently only able to find objects containing terms that match literally with the find term. Terms match literally if a) all non-variable sub-terms are identical; and b) any variables contained in them share the same name. For example, find animal(X) will match animal(X) but not animal(dog) or animal(Y). It is planned to extend the functionality of find to allow search for terms that unify with the find term.

Finally, note also that if find is given a term such as cat, it will find occurrences of that term within cat(tigger) and is_a(animal, cat) but not within cats([tigger,thomas]). That is, the find term may match the functor or an argument of a complex term, but it must match exactly and entirely.


COGENT's replace facility allows all terms within the rules, condition definitions, buffer elements, etc. of a model that match a given pattern to be replaced by an alternate pattern. Figure 2 shows the replace dialogue, which appears when Replace is selected from a box's Edit menu.

Figure 2: The Replace dialogue

To use the facility, enter a term in the Find: field and enter the replacement term in the Replace with: field. Click on the Replace All button and COGENT will search for all occurrences of the find term (i.e., terms which literally match it) in the box from which replace was selected and replace them with occurrences of the replace term. When finished, replace will report the number of occurrences of the term that were found and replaced.

Replace uses the same search mechanisms as find, and the terms replaced will be exactly those found by find. As with find, it is planned to extend the functionality of replace to allow replacement of terms that unify with the find term.

The scope of replace is defined by the box from which replace was selected. If it is selected from the top-level compound box, it will replace all terms within the entire model. If it is selected from a sub-box, it will only replace terms within that sub-box. If the sub-box is a compound, it will recurse through the sub-boxes of that compound.

Replace may also be used to selectively replace instances of a pattern. The Find Next button searches the contents of the box from which replace was selected in a canonical order and finds the next item in the box that contains occurrences of the nominated pattern. The Replace button then replaces those occurrences with the pattern specified in the Replace with field. Alternatively, the occurrence may be skipped by selecting Find Next again.

View Term List

The Term List page of the notebook displays an alphabetical list of terms used by elements within the box, and the numbder of times those terms are used. This page is intended to provide a minimal dictionary of terms used within a model. It may be useful, for example, for checking typing errors (which would be apparent if two terms have similar but different spellings).

Figure 4: The Term List page

View Connectivity

The Connectivity page of the notebook allows the user to check that a box and arrow diagram is syntactically well-formed. The page (shown in Figure 4 below) presents the user with a list of suspect arrows, together with a brief description of the reason why the arrow appears suspect. The well-formedness check will detect arrows that are superfluous, arrows that are syntactically illegal (e.g., a buffer cannot send messages, so a send/write arrow should not exit a buffer), arrows that are required but missing, and arrows whose internal representation is inconsistent. Syntactically ill-formed models will probably still work as intended, but they may give a misleading impression of the connectivity of boxes within a model, so it is generally best to address any suspect arrows reported on the Connectivity page.

Figure 4: The Connectivity page

View Singletons

Singleton variables are variables that occur just once in the element and whose name does not begin with the under-score character. Singleton variables may be harmless, but they may reflect typing errors. The Singletons page of the notebook (see Figure 5 below) provides the user with a list of all singleton variables that occur within a box. Clicking on an entry in the singletons list will open an editor on that element, allowing the user to check that variable in context and, if necessary, fix it.

Figure 5: The Singletons page

COGENT Version 2.3 Help