Getting Started

From emergent
Jump to: navigation, search
Crystal Clear app display.png Using emergent

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

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

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

Linux

  • emergent is installed in the Edutainment/Misc/Emergent or Education/Emergent application start menu, depending on KDE or Gnome. The GUI can also be launched from the console by typing emergent.

Microsoft Windows

  • emergent is installed in C:\Program Files. The GUI can be launched by selecting the emergent icon from the Windows Start Menu or from the Windows Desktop. NOTE: The GUI can also be launched by double clicking the Emergent\bin\emergent.exe icon in Explorer, or by typing emergent from a Windows Command Prompt.

Application Basics

When you start emergent it opens a Root window with the Startup Wizard that gives you the choice of creating a new project (several templates are available), opening an existing project or downloading and opening a published project. Once you have opened a project you usually won't return to the root window.

Graphical Interface Elements

The next few sections provide a brief description of the main interface elements of the emergent application.

The following menus are used in the emergent user interface:

  1. Main Menu — the Main Menu appears on the top of each window, or in the menu bar on the Mac
  2. Application Toolbar — the Application Toolbar appears directly below the Main Menu
  3. Programming Toolbar — by default the Tools appear on the left-hand side of each window
  4. Status Bar — the status information appears at the bottom of each window
  5. Context Menus — the context menus appear when you right click (Mac: ctrl-click) on an object
  6. Property Page Menus — the property page menu can be found at the top of the center Editor for each object when that object is selected, and refers only to that object


Main Menu

The following sections describe all the items in the main menu bar 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 (project window only) - save the current project, prompt for a filename if the project is new
  • Save Project As (project window only) - save the project under a new name
  • Save Note Changes (project window only) - prefix new message to the project Change Log
  • Updt Change Log (project window only) - prefix new message to the project Change Log
  • Save All Projects - save all currently open projects, prompt for a filename if any project is new
  • SVN Browser - browse svn project repository (only enabled if the project directory is part of an svn working copy)
  • SVN Add - adds your project to svn if you have an svn repository
  • SVN Commit - commits project changes to svn if you have previously add the project
  • Open Project From Web - Displays a list of projects published to the emergent, or other, wiki
  • Publish Project On Web - allows you to add your project to those published on the emergent, or other, wiki
  • Update Project On Web - update a previously published project with new version
  • Upload Other Files to Web - upload and associate other files, data, weight files, etc with a project - they will be listed on the project wiki page
  • Browse Program Libraries on Web - view and install published emergent programs (notice that this one is programs not projects)
  • Close Project (project window only) - close the current project (prompts for save if changed)
  • Options (Mac: 'Preferences' on App menu) - opens the emergent application options dialog
  • Close Window (project window 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
  • Quit (main app window only) - exit emergent

Edit Menu

  • Undo -- undo last edit or action -- see css console for information on what was undone -- see Undo
  • Redo -- redo last action that was Undone -- see Undo
  • Cut - puts the selected object(s) onto the clipboard; it will be moved if you Paste it somewhere -- see Cut and Paste
  • Copy - copies the selected object(s) onto the clipboard -- see Cut and Paste
  • Duplicate (project window only) - makes a duplicate of the selected object(s) at the current location -- see object copy
  • Paste - inserts the object(s) from the clipboard to the current location -- see Cut and Paste
    'Paste Into' - the destination for the 'Paste' operation 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
    'Paste Assign' - the destination for the 'Paste' operation object is a matching object - this term helps disambiguate situations where the item could either be placed as a peer of other items at its level, or assigned to completely replace an existing item
  • Delete - deletes the selected object(s) -- see object delete
  • Find - enables you to find an object(s) by specifying many different kinds of 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
  • Back - browser-style navigation of the project Navigator which allows you to go back to the previous object selected in the project Navigator, and displays the corresponding view in the center Editor
  • Forward - browser-style navigation of the project Navigator which allows you to go forward to the next object selected in the project Navigator, and displays the corresponding view in the center Editor
  • Frames - enables you to show or hide any of the main frames currently being used, such as the Navigator, Editor, or Visualizer. Note: You can also dynamically shrink these frames to nothing by using the grab bar that divides frames.
  • Toolbars - enables you to show or hide the Application and Programming toolbars
  • Navigator Only ... Reset Frames - a series of menu items that will allow you to get any combination of the Navigator, Editor and Visualizer frames
  • Incr Font Size / Decr Font Size - these items change the font size on a temporary basis - useful if you are projecting and want your audience to be able to read the text
  • Save View State - 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 want to leave the 'Show' option set to 'Normal', except possibly to highlight what are Expert and/or Hidden. The 'Normal' items are all that is required for standard usage.

Control Menu

Menu items for running a program, some have keyboard equivalents and there are buttons for these actions on the Application Toolbar

  • Init - initialize a program
  • Run - run a program
  • Continue - resume a stopped program
  • Stop - pause a program
  • Step - will step a program that has been stopped and stepped using the program step controller
  • Trace - will display a list (stack) showing the currently stopped program and the one that called it, and so on

Tools

  • Diff Compare - compare 2 objects (e.g. 2 data tables or 2 programs) - you can also select one object in the navigator and choose Object/Diff_Compare from the context menu
  • Choose Key Bindings - dialog that allows you to change the key sequence associated with any action that already has a key sequence
  • Reset Key Bindings - set key sequences back to defaults
  • C++ Class Reference
  • Type Info Reference
  • SVN Browser Emergent - Browse the emergent source code repository
  • SVN Browser Repo - browse the cluster run repository
  • Open Remote Server - start the server so that clients using telnet protocol can control the project
  • Close Remote Server - shutdown the server

Data

A wealth of methods that can be run on data tables to generate, analyze and process data

Window

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

Help

  • Web Docs - takes you to the "Using Emergent" web page which has links to lots of other useful documentation
  • C++ Class Reference - invokes the Help Browser
  • Report Bug - takes you to bugzilla so you can report or search for bugs

Application Toolbar

The emergent application toolbar has icons that correspond to some frequently used Main Menu items. (You can hide the names under the icons - Use the Emergent/Preferences menu item (called Options in Windows version)

Programming Toolbar

When inside a project, the programming toolbar (docked by default on the left-hand side of the window) provides access to a toolbox containing clip/drag/droppable basic and advanced emergent Program elements.

Status Bar

The status bar (at the bottom of the window) dynamically displays the help text associated with a objects, menu items, or other selected items in the GUI. For a full listing of the help text, see the Help Browser.

Context Menus

Most objects in emergent feature rich context menus that are invoked by right clicking on the object (Mac: ctrl-click). The context menus allow you to quickly access the large range of menu options which apply to that object (such as 'Find from here' and catagories such as 'Object', 'ControlPanel', and 'Edit')

Property Page Menus

When an object is selected in the Navigator the top of the tabbed object in the center Editor displays the 'Property Page Menu' for that object. The 'Property Page Menu' is a subset of the full 'Context Menus' (above), and contains relevant menu catagories such as 'Object' and 'ControlPanel'.

Clipboard / 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 to Cut and Paste objects.

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 Preferences/Options panel, and experiment.

Toggle the lock icon in the console toolbar to switch between a free floating console window and one that locks to the bottom of your main project window.

Viewers

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

  • toolbars (see Property Page Menus above)
  • Navigator on the left side of the window, to the right of the 'Tools' -- with a tree browser view of all the objects in the project -- provides the primary means of accessing objects for editing and further manipulation.
  • Editor tabbed frame in the center -- items selected in the Navigator will have an edit dialog presented here. also contains view control panels for the 3D viewer objects (see next).
  • Visualizer tabbed frame on the right -- shows three-dimensional views of Network, DataTable and Virtual Environment objects

Navigator

The Navigator provides a familiar "explorer"-style browser 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 View contains the following major catagories for each project: docs, wizards, ctrl_panels, data, programs, viewers, and networks.

  • The tree will automatically update if objects are added or removed.
  • You can view the properties of a given item in the tree by clicking on it with the mouse.
  • You can select several items from the tree by holding down the Ctrl key (Command key on Mac) while clicking each successive item.

Error and Enable Highlighting

Many items that can be shown in the Navigator 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. To turn off an item check its "off" box on its property page or toggle the "off" state using context menu.

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 the use of color in the browser tree or in the edit panel, by selecting the corresponding color hints option from the Preferences.

Convenience Features

The Tree View provides the following convenience features - most are accessed from the right mouse-click context menu:

  • Find from here - you can search for other objects with that objects scope (also Replace from here)
  • 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 to expand to default state or collapse if now open - double click while holding control key (command on Mac) will "expand all". The default expand state for the main groups can be set in Preferences.

Editor

The Editor provides panels for editing properties, as well as control panels for objects in the Visualizer. A Panel provides a viewer for properties of objects, and also provides specialized views, such as list views of lists, tabular views of data, 3D Viewer options, and so on. When more then one sub-panel type is available, the view for a particular panel can be switched by clicking on the view button near the top of the panel (e.g. 'List View' and 'Properties') below the Property Page Menu.

Editor behavior when you select an object in the Navigator

In general, when you left-click to select an object in the Navigator, that object will be displayed in the left-most tab in the Editor panel. When a new object is selected from the tree view, it will replace the currently displayed object in the unpinned left-most edit tab. If you would like a specific object to stay visible in the center panel, you can pin the tab by right clicking on the 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 tab, a new panel tab is opened for any new objects that you select in the tree view.

Editor behavior when you select a tab in the Visualizer

Similarily, when you left-click to select a particular 'frame' tab in the right hand Visualizer, then that frame's control options will be displayed in the right-most tab in the Editor. When a new frame tab is selected from the Visualizer, it will replace the currently displayed frame options in the right-most edit tab. There is only one frame tab automatically provided in the center panel, and it cannot be pinned.

Edit Panels (sub panels of the Editor)

The most common type of Editor 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.

All simple controls like check boxes, selectors, etc 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 auto-Apply.

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 Edit Panel Types

Various other objects have specialized additional sub-panels 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 Visualizer objects, such as networks and graphs, provide a control panel for easily changing the view parameters. When you have a 3D View frame visible, any associated control panels will be automatically shown in the right hand tab of the Editor View. Only the control panels for the currently selected Visualizer 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.

Visualizer

Emergent enables you to visualize many types of objects in a true 3D Visualizer. This provides a space for one or more 3D Frames (T3Frames), each frame can hold a view containing several 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 set to 'New Frame', or you can make a new blank frame by right clicking any frame tab and selecting 'Add Frame'.

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 . . Along with docs and wizards, the root object contains these important collections:

  • projects - a list of all projects open in the application - you will rarely if ever need to use this
  • 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)
  • ctrl_panels - a ControlPanel 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
  • 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 3D 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 Navigator Tree View, browse to and left-click on: programs/LeabraAll_Std/LeabraBatch
    The LeabraBatch Editor panel should be showing in the middle of the project window.
  4. click Init - if it asks to "Initialize network weights?" click "yes".
  5. click Run

The simulation should start running, and you will see the simulon attempting to catch the ball in the the right 3D Viewer.

Building your first network!

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

Next steps...

After you have built a simple network, the AX Tutorial provides a comprehensive introduction to many of the more detailed aspects of the emergent program. → next AX Tutorial