|
How do I... |
How to do it |
|
Create a new project |
To create a new agent, select New Project... in the File menu. A dialog will be presented allowing you to name your new agent and specify the path where the agent files will be stored. |
|
To open the existing agent, select Open Project... in the File menu. A dialog will be presented allowing you to navigate to the agent file you wish to open. Select that file and click the Open button. | |
|
Close a project |
To close a project, select Close Project from the File menu in the main window. |
|
Create the operator hierarchy |
To add operators (or files in the case of the elaborations folder) to the operator hierarchy, right-click on the folder node or operator node that you wish to add the operator below. Select Add a Suboperator... A dialog will be presented asking you to name the new operator. If a suboperator is added to a low-level operator (represented with a file node), it becomes a high-level operator, and an elaborations file is created below it. The elaborations file is where non-operator productions relating to the state are stored. |
|
Edit the operator hierarchy |
Once the operator hierarchy has been created, nodes can be renamed by right-clicking on the node and selecting Rename... from the context menu. Nodes can also be deleted by right-clicking and selecting Delete from the context menu. |
|
Create rule files |
Make sure that an agent file is open, then in the operator hierarchy (the left half of the split pane), right-click on any node which is an operator. In most cases, select Add a Suboperator... from the contextual menu. However, if you right-click on the elaborations node, you should select Add a File... since only rules which are not operators are stored under elaborations. Either way, a dialog will be presented allowing you to name the new operator or file. |
|
Once you have created the rule file you can edit it by right-clicking on its node and selecting Open Rules from the contextual menu. This works both with high-level operators (which are represented in the operator hierarchy by folder nodes) as well as low-level operators and files (which are represened by file nodes). A rule editor window will be opened in the right side of the split pane. | |
|
Save a rule file |
Make sure that the window you wish to save is frontmost, then select Save File from the File menu. It is not necessary to do any naming or file system navigation since this is determined by the structure of the operator hierarchy. |
|
Soar Complete |
Visual Soar has the ability to auto-complete (in a unix tab-completion type fashion) certain attribute or values in productions. To access this feature, start typing in a production when you are to a point of entering an attribute name or enumeration value. Hit ctrl-enter to see if VisualSoar can auto-complete the attribute or value for you. Alternatively, you can select Soar Complete from the Soar menu in the rule window. |
|
Check rules againt DataMap content |
First make sure that the data map for the rules you want to check is complete (See Create DataMaps). Select Check Productions Against DataMap from the Soar menu. Any errors will be reported in the feedback window, where double-clicking will take you to the point of the error. |
|
Save all rule files |
Select Save from the File menu in the main window. |
|
DataMaps do not need to be created explicitly since they are created by Visual Soar when the project is created, or when new high-level operators are created. A DataMap is a representation of the range of possibilities for working memory. Any structure that an agent's productions create or test against should be present in the appropriate DataMap. To open the DataMap, right-click on either the root node (the topmost one, which is named for the agent) or any other high-level operator in the operator hierarchy. Select Open DataMap from the contextual menu. | |
|
To automatically generate DataMaps from the your current project's files, select Generate DataMaps from Operator Hierarchy from the File menu of the main window. Visual Soar will then add elements to the dataMaps by viewing content of the current project's files. The results of the DataMap generation will appear in the feedback window in green. Double-clicking on an item in the feedback window will open a rule editor to the location in a production that caused Visual Soar to create this element. Generated elements will appear green in the DataMaps until they are validated by the user. | |
|
First, open the data map as you did when you first created it. Initially, the data map will have a root node with the name of the state it pertains to. From this point, right click on the root node and select one of the five different types of Working Memory Elements to add. They are: Add Identifier..., Add Enumeration..., Add Integer..., Add Float... and Add String.... You will be prompted to give the attribute a name and specify any constraints for the WME's value. Keep in mind that only Identifiers may have other WMEs as their values. Therefore, only Identifier nodes may have children. Note: Working Memory Elements are triples of identifer-attribute-value. The identifer is implict, because it was one that you right-clicked on, so now you are specifying the attribute-value pair. If you want the value to be equivalent to another one in Working Memory see Linking Values. After creating the desired structures in the data map, it can be edited by right-clicking on nodes to produce a context menu. From the context menu, attributes can be renamed by selecting the Rename Attribute... item, or deleted by selecting the Delete Attribute... item. The value can be edited if possible by selecting Edit Value(s).... | |
|
Adding Comments to DataMaps |
To add or edit a comment to an element within a dataMap, right-click on that element and select Add/Edit Comment.... Then type in the desired comment and select OK. To remove a comment, simply right-click on that element and select Remove Comment.... Note that comments do not effect error checking or production matching, they are just there for the user's benefit. |
|
To distinguish between generated DataMap elements and existing elements, generated elements are considered non-validated and colored green. Validating elements can be done several ways.
|
|
|
Attributes can be linked by ctrl-shift dragging attribute-values to the desired place in the datamap. If a link is made to a primitive WME (anything besides an Identifier) it's behavior is the same as making an independent copy. However, if a link is made to an identifier, the name of the link and original node will be intependent, but their children will be shared. | |
|
Source an agent into the TSI |
Visual Soar trys its best to make sure every rule file in the project gets source'd into the TSI if you point it at your <agent>.soar file that exists at the same directory level as your <agent>.vsa file. If for some unexplained reason the source-ing gets out of date, or is wrong. Select Save from the File menu in the main window. To bring it up to date. |
|
Exit VisualSoar |
Select Exit from the File menu. |
|
Find a text string |
If you wish to search a specific file, open that file (see Edit Rule Files) and select Find... from the Search menu. Either way, a dialog will be presented which will allow you to choose the string to seach for, as well as several searching options. Additionally, for a file-specific search, Find Again in the Search menu can be used to repeat the previous search. |
|
Replace a text string |
Basically just like doing a find, except the dialog will contain an additional field in which you can enter the string for the replacement. Replacements can be done one at a time, or for the entire document. |
|
Find a string in the project |
If you want to find all instances of a string in your files, select Find In Project... from the Search menu in the main window. Type in the string you wish to find and click on Find. |
|
Replace a string in the whole project |
If you want to find and replace instances of a string in your project files, select Replace In Project... from the Search menu in the main window. Type in the string you wish to find and click on Find to find the first instance of the string in your project. Clicking on Find again will find the next instance, while Replace will replace the currently selected instance with desired the string and then find the next instance. Replace All will automatically replace every instance of one string with another desired string. |
|
Link an operator |
First off, what does it mean for an operator to be linked? A linked operator is one that produces a new state, but does not define the behavior for that state, because the behavior of that substate is defined elsewhere in the system. But, the linked operator does have it's own set of proposals. How you link operators is by selecting a high-level operator that you want to link and drag it with the link action (ctrl-shift) to the parent of where you want the new linked operator to go. Only high-level operators can be linked. |
|
Move an operator |
To move an operator, select an operator you wish to move, then drag it and drop it onto the new desired parent. If the operator was high-level, it's view of the datamap is updated so that the superstate will point to the new superstate, but all other links are unchanged. It is your reponsibility as the user to update the links as needed. |
|
Export an operator |
To export an operator, select the operator you wish to export from. That operator and its children will be exported and can be imported into another project. Linked operators cannot be exported and thus are converted to low-level operators. Right-click on the parent and select Export. The exported operators are placed in a file called <operator-name>.vse. |
|
Import an operator |
To import operators that you exported from another project. Select the parent of where the new set of operators will be imported from. Right-click on the parent and select Import from the context menu. Select the .vse file that was produced from the export and click on Open. Note: to guarentee the imported operators will work in the new system the features from the old datamap are associated with operators. It is your responsibility to update the features from the operators old datamap to features of the new datamap. |
|
Check Children Against the DataMap |
To check all the children productions against the DataMap, right-click on the parent and select Check Children Against DataMap. |
|
Check All Productions Against the DataMap |
To check all the productions against the DataMap, select Check All Productions Against DataMap from the main window. Note: files and operators with names starting with a "_" will not be checked against the DataMap. |
|
Certain aspects of visual soar's behavior can be changed, how you change them is by selecting Preferences... from the Edit menu in the main window Preferences currently control
| |
|
Insert A Template |
Templates are general layouts for common productions. Templates are just files in which $operator$ and $super-operator$ are replaced with the corresponding current operator name and super-operator name. You can insert a template by selecting the template from the Insert Template menu in the rule editor. If you don't see the desired template or any templates at all, check the template folder in the your preferences. |
|
Open an External Text File |
To open an external text file in Visual Soar, select Open File... from the File menu. A dialog will be presented allowing you to navigate to the text file you wish to open. Select that file and click the Open button. |
|
Copy or Move Attribute-Values in the DataMap |
You can copy or move one attribute selecting an attribute value and dragging (move) or ctrl-dragging (copy) to its new parent. Note: Contigous features can be copied onto the clipboard and pasted onto a new parent through the Edit menu in the datamap window. The semantics of this operation are slightly different than the dragging copy for identifiers, for which a new identifier is created. Whether this is a bug or not has yet to be determined. |
|
Use the Soar Tools Interface (STI) |
Please consult the Soar Tools Interface Homepage for more information. |