Getting Started

From Emergent

This page presents an overview of Emergent, starting up, opening and running an existing simulation, and building your first network!

Contents 1 Running Emergent 1.1 Mac 1.2 Linux 1.3 Microsoft Windows 2 Interface basics 2.1 Menu/Toolbars/Status bar 2.1.1 Main Menu 2.1.1.1 File Menu 2.1.1.2 Edit Menu 2.1.1.3 View Menu 2.1.1.4 Show Menu 2.1.1.5 Tools 2.1.1.6 Window 2.1.1.7 Help 2.1.2 Toolbars 2.1.3 Status Bar 2.1.4 Context Menus 2.2 Clipboard and Drag-and-Drop 2.2.1 Clipboard 2.2.2 Drag and Drop 2.3 Console 3 Viewers 3.1 Tree View 3.1.1 Error and Enable Highlighting 3.1.2 Color Hints 3.1.3 Convenience Features 3.2 Panel View 3.2.1 Panels 3.2.1.1 Edit Panels 3.2.1.2 List Panels 3.2.1.3 Other Panel Types 3.2.2 Control Panels 3.3 3D View 4 Application Basics 4.1 Application Objects 5 Project Basics 6 Running a Simulation 7 Building your first network! 8 Next steps...

Running Emergent

The following are the instructions for launching Emergent in gui mode, without any command line options. For advanced launch scenarios, such as options, batch (no gui) operation, or clusters, see the Emergent Reference.

Mac

• The Emergent.app is installed in /Applications along with all the other applications -- you can drag it from there into your Dock if you want. It can also be run from a terminal shell by typing "emergent".

Linux

• It is installed in the Edutainment/Misc/Emergent or Education/Emergent application start menu, depending on KDE or Gnome

or

• at a console, type:

emergent

Microsoft Windows

• Select the Start/Programs/Emergent/Emergent icon to launch the program

or

• double click the Emergent\bin\emergent.exe icon in Explorer

Interface basics

This section provides a brief description of the main interface elements of the Emergent application.

Menu/Toolbars/Status bar

There are three kinds of menus in Emergent:

1. the main menu — this appears on the top of each window, or in the menu bar on the Mac
2. context menus — these appear when you right click (Mac: ctrl-click) on an object
3. property page menus — these are at the top of the property page for an object, and refer only to that object

Main Menu

This section describes all the items in the main menu of the application.

File Menu

• New Project - this creates a new project
• Open Project - enables you to select a project to open
• Open Recent - enables you to quickly open a recent project
• Save Project - save the current project, prompts for a filename if new
• Save Project As - save the project under a new name
• Close Project - close the current project (prompts for save if changed)
• Options (Mac: Preferences on App menu) - opens the application options dialog
• Print - print the current view
• Quit (main app window only) - exit the application
• Close Window (project windows only) - close the current browser window - note the project remains open - to reopen the viewer, navigate to the root/projects/YourProject, right click, and choose Open View

Edit Menu

note: Emergent currently has no undo capability

• Cut - puts the selected object(s) onto the clipboard; it will be moved if you Paste it somewhere
• Copy - copies the selected object(s) onto the clipboard
• Duplicate - makes a duplicate of the selected object(s) at the current location
• Paste - inserts the object(s) from the clipboard to the current location
• Delete - deletes the selected object(s)

note: if the term Into appears after an edit item, such as Paste Into, it means that the destination is a list or group - this term helps disambiguate situations where the item could either be placed as a peer of other items at its level, or into a list or group

• Find - enables you to find an object(s) by specifying many different kinds of criteria
• Find Next - find the next instance of an object using the previous criteria

View Menu

• Refresh - refreshes the gui so it corresponds to the underlying project items - note that Emergent usually does a good job of keeping the gui refreshed, but a manual refresh could be needed in some obscure scenarios
• Frames - enables you to show or hide any of the main frames currently being used, such as the tree browser, property panel, or 3d view - you can also shrink windows to nothing by using the grab bar that divides frames
• Toolbars - enables you to show or hide any of the current toolbars
• Dock Windows - enables you to show or hide any of the current dock windows, such as the toolbox
• Save View - saves the state of the current view - it will be restored to this state next time it is opened (Emergent currently saves only a few aspects of the view state, such as window size/position, and frame sizes)

Show Menu

Some objects and properties in Emergent are marked as being Expert or Hidden. Expert items are typically for advanced usage scenarios, and so are normally not shown. Hidden items are rarely used, except by Emergent Developers. You can turn on showing of these items globally using this menu. Note that individual property pages enable you to selectively show Expert and Hidden items. If you select Expert or Hidden globally, then the corresponding items are automatically shown in all property panels.

• Normal Only - only show normal items, not Expert or Hidden
• All - show all items
• Normal/Expert/Hidden - individually choose which items to show

You would usually not unselect Normal, except possibly to highlight what are Expert and/or Hidden.

Tools

• Class Browser - opens a browser that enables you to see all the object classes in the system - this can be helpful for programming, or just to see the hierarchical relationship of classes.

Window

This menu provides a list of all browser windows open in the application, so you can easily switch between windows.

Help

• Help - invokes the online help
• About - shows information about the version of the application

Toolbars

There is currently one main application toolbar; it has icons that correspond to some frequently used Main Menu items.

Status Bar

The status bar dynamically displays the help text associated with a menu or other selected item in the gui.

Context Menus

Most objects in Emergent feature rich context menus that are invoked by right clicking (Mac: ctrl-click).

Clipboard and Drag-and-Drop

Emergent makes extensive use of the clipboard, and of Drag and Drop. Most objects in the tree view have clipboard commands associated with them, such as Cut and Paste.

Clipboard

The clipboard can be used throughout Emergent.

Note that when you Cut something, the item is not immediately deleted in the gui - it is only moved when you perform the corresponding Paste. If you choose Cut and then Paste into an external application (including another instance of Emergent) then the operation is identical to a Copy/Paste, i.e. the source is not deleted.

Many contexts will accept data from an external application. For example, you can copy data from many common spreadsheet programs (Excel, Open Office Calc, etc.) and then paste it into an Emergent datatable.

Drag and Drop

You can drag and drop both within an application, and between the application and other applications. For example, you can select a series of cells in a data table, and drag and drop them into a spreadsheet application.

When you complete a drag operation, a context menu will appear at the destination, with the available options, including a Cancel. You will probably want to use this menu until you become familiar with the program; to skip the menu, you can hold down the key indicated next to the operation in the menu.

Many operations such as assignment of an object to a variable can be achieved using drag and drop - you will want to experiment with dragging objects to destinations to discover the operations that can be performed (you can always hit Esc or click Cancel to do nothing.)

Console

The console is a "command line" inside the Emergent application. It displays diagnostic messages, and can be used to print object values, list programs, and other operations. The console appearance will differ, depending on your platform. Some platforms provide the option of showing a free-floating console that tracks underneath your project, or embedding it in the main application window. See the Options panel, and experiment.

Viewers

The main type of window in Emergent is called a viewer - it is a modular window that can contain any of the following:

• toolboxes
• toolbars
• a tree-based Tree View(an "explorer")
• a Panel View
• a 3D View

Tree View

The Tree View provides a familiar "explorer"-style view of objects, starting at some base object. For the application, this is called root; for projects, the root object is the project itself. You can also open Browsers that are rooted on any specific object - just right click and select Browse From Here.

The tree will automatically update if objects are added or removed.

Some subpanels, such as the Program Editor and Spec Editor also have embedded Tree Views, which operate much the same as the one in the Tree View Panel.

You can view the properties of a given item by clicking on it with the mouse. You can select several items by holding down the Ctrl key for each successive item.

Error and Enable Highlighting

Many items that can be shown in the tree view can have an error condition associated with them. The main ones are parameter errors in network simulation objects, and program errors in Programs. When an error is detected, the offending item is highlighted in red - to help you easily find these items (which may be buried inside other items, and not even visible yet in the gui), higher-level items containing error items are highlighted in yellow.

Some items can be disabled (switched off) - for items that support this capability, they will be highlighted in grey

Color Hints

To help differentiate the various categories of objects in the project, colors have been arbitrarily assigned to categories. These colors are used in the text of items in trees, and as background in edit panels. You can enable or disable each use of color in the Preferences panel.

Convenience Features

Trees provide the following convenience features - most are accessed from the right context menu:

• Find from here - you can search for other objects from this point
• clipboard operations (ex Cut, Paste, etc.) where applicable - also generally available on main menu, or via keyboard shortcuts
• Browse from here - you can open a new browser window (tree + panels, no 3D) rooted at the item selected
• Edit Dialog/Panel - you can open an edit dialog on the item, or insure the panel shows the item to edit
• item-specific commands - the most frequently needed commands for this object are available either directly on the right context menu - the remaining commands for the object are in a submenu of it, such as Object/
• Expand/Collapse - you can expand or collapse the children, or all children - double click at item to (alternately) expand/collapse all

Panel View

The Panel View provides panels for editing properties, as well as control panels for objects in the 3d viewer.

Panels

A Panel provides a viewer for properties of objects, and also provides specialized views, such as list views of lists, tabular views of data, and so on.

To switch the view where there is more than one subpanel type, click the button at the top of the panels.

In general, when you left-click on (select) an item in the left hand tree view, then that item will be displayed in the current panel tab in the Panel View. If you would like a specific object's panel to stay visible, you can pin it by right clicking its tab and selecting Pin - this is useful so you can return easily to the properties without having to navigate to the object in the tree. Once you pin a panel, a new panel tab is opened for the items that you select.

Edit Panels

The most common type of panel is an Edit Panel - all objects support this view, which enables the properties ("members") of the object to be edited. Edits generally show a list of name/value pairs, with an appropriate control for each value type. A tooltip and statusbar tip generally accompany each control, to provide more detailed information on the item.

When you view an item for the first time, the Apply and Revert buttons at the bottom are both disabled - this means the object has not been changed. As soon as you make a change to any field (except as noted next), the Apply and Revert buttons will be activated. You can continue changing fields, until you are ready to commit your changes by pressing Apply. Once you Apply, the object is updated, and the buttons again are disabled. If you change your mind, and would like to cancel making your changes, press Revert - this will restore the object to the state it had before you started editing it.

If a member name has an exclamation point, then the entire item will be automatically saved/updated if you change that value. In other words, it is the same as editing the item and hitting Apply in one step. Any other pending changes will also be applied at the same time. You cannot Revert from autoapply.

List Panels

Lists and Groups ("collections") also have a List Panel that shows the items in the list. You can perform operations on these items, such as moving them via drag and drop, or invoking context menu operations.

Other Panel Types

Various other objects have specialized addtional subpanels to help view and edit the item. For example, datatables have a built-in editor, programs have a built-in program editor, and so on.

Control Panels

Many 3d objects, such as networks and graphs, provide a control panel for easily changing the view parameters. When you have a 3d panel visible, any associated control panels will be show in the right hand side of the Panel View. Only the control panels for the currently selected 3d frame are shown.

Unlike the Object Panels, Control Panels are always shown, and are automatically pinned in place.

Note that there is often some overlap between the values that can be changed in an Edit Panel for an object, and those that can be changed in a Control Panel. The difference, is that the Control Panel is a customized gui interface that has been optimized for controlling the item, whereas the Edit Panel is a generic, machine-generated interface.

3D View

Emergent enables you to visualize many types of objects in a true 3D viewer. The 3D View provides a space for one or more 3D Frames, each of which can hold a view of many objects. You can have as many Frames as you want, and can visualize an object any number of times in any number of frames. For example, you can show a tabular 3D view of a data table in one frame, and a graph of that data in another frame, or even several graphs in one frame.

Each object type that supports 3D views has an item on its context menu that enables you to make a new view.

To make a new frame, you can either make a view of an object, and leave the frame name blank, or you can make a new blank frame by right clicking any frame tab and selecting New Frame.

Application Basics

When you start Emergent it opens an Application Browser with a Tree View panel and a Properties panel (these are explained in more detail in the Projects section below.) The items in this window are not usually that important when you are using Emergent - you usually interact with Project windows (and windows you open from Projects.)

Application Objects

All objects in an Emergent application live in lists (or groups) or other objects. The base of this tree is called root and in programs is referred to by a single period . . The root object contains these collections:

• projects - a list of all projects open in the application - if you close the project browser for a project, without closing the project itself, the project remains open, you can reopen it by right clicking and selecting Open New Project Browser
• viewers - this is a list of all non-project viewers open - you will rarely if ever need to use this
• plugins - a list of all plugins that were found on startup - note that plugins are not loaded automatically, you must enable desired plugins and then restart the application
• colorspecs - named color specifications - you can edit these if the colors are not to your liking

Project Basics

An Emergent Project is an object that contains all the other types of objects that make up a network simulation. A Project has the following main collections (follow the links for detailed descriptions of the object types):

• docs - a Doc object is a web-like document that can be used to document a model, provide instructions on operating it, and so on
• wizards - a Wizard provides automated assistance in creating other objects, such as complete network simulations (note: you will never create these)
• edits - a SelectEdit provides a way to gather properties from many other objects, to set them in one place - for example, you can collect various network parameters all in one place, to easily set them
• data - holds datatables - the system automatically provides several subgroups to help organize your data, you can also add new subgroups of your own
• data proc - holds pre-built DataProc objects - similar to Wizards, these provide various data services that operate on data (note: you will never create these)
• programs - a Program controls network simulations, data processing, and other automated procedures - when you use a wizard to create a simulation, it automatically imports the required standard programs from the program library
• viewers - holds Viewer objects - every project gets a Default Viewer, which is created when the project is created, and opened automatically when the project is opened - you can also create additional viewers - you might want to do this for larger projects, to include lesser-used graphs or other 3D views - to open auxiliary views, right click the view and select View Window
• networks - most network simulations use a single network, but you can create more than one, such as for example to experiment with different configurations

Running a Simulation

This section provides a simple tutorial on running an existing simulation. Since the ultimate goal of brains is moving the organism around, we will use the virt_env simulation to show a simple brain controlling the arm of a simulon.

1. select File/Open Project - navigate to Emergent/demo/virt_env
2. select ve_arm.proj
   The project will open.
3. in the Project Browser, navigate to: programs/LeabraAll_Std/LeabraBatch
   The LeabraBatch edit panel should be showing in the Panel View.
4. click Init - if it asks to "Initialize network weights?" click "yes".
5. click Run

The simulation should start running.

Building your first network!

Ok, we are ready to build your own first network!

Next steps...

The AX Tutorial provides a comprehensive introduction to many aspects of the program, and is a good place to go next.