From 3aaa2b4e7663dd3ae7a3df9a556b849df52dbcfd Mon Sep 17 00:00:00 2001 From: Moritz Schmidt Date: Sat, 29 Nov 2025 21:01:26 +0100 Subject: [PATCH] Add crosslinks to VisualSoar in various documents and add deprecation warning to SoarIDE --- docs/development/agents/DesignDogma.md | 8 +- .../agent_development_tools/soaride.md | 4 + docs/downloads/soar/latest.md | 10 +- docs/home/QuickStart.md | 4 +- docs/index.md | 4 +- .../VisualSoarKeyboardAndMouseControls.md | 12 +- docs/soar_manual/02_TheSoarArchitecture.md | 215 +++++++++--------- docs/tutorials/soar_tutorial/01.md | 38 ++-- docs/tutorials/soar_tutorial/02.md | 14 +- docs/tutorials/soar_tutorial/03.md | 38 ++-- docs/tutorials/soar_tutorial/06.md | 4 +- 11 files changed, 187 insertions(+), 164 deletions(-) diff --git a/docs/development/agents/DesignDogma.md b/docs/development/agents/DesignDogma.md index 72ca6127..9145bb77 100644 --- a/docs/development/agents/DesignDogma.md +++ b/docs/development/agents/DesignDogma.md @@ -295,8 +295,8 @@ create performance bottlenecks. ## Use an IDE like VisualSoar -Write your Soar code using VisualSoar. If so, maintain and use your VisualSoar -data map! +Write your Soar code using [VisualSoar][VSIDE]. +If so, maintain and use your [VisualSoar][VSIDE] data map! ### Example @@ -306,7 +306,7 @@ N/A Much like comments on code, VisualSoar's enforced structure and data map is exceptionally helpful for people who are examining code they have -not themselves written. VisualSoar provides helpful functionality like syntax +not themselves written. [VisualSoar][VSIDE] provides helpful functionality like syntax highlighting and identifier completion. It also helps you catch bugs in your code by watching for rules that match unspecified WMEs. Such bugs (particularly typos involving nearly identical letters like l and 1) can sometimes require @@ -368,3 +368,5 @@ sp {xxyyzz By violating the intent of the Soar language you will likely achieve undesirable results. There is almost certainly a better way of doing what you are trying to do. + +[VSIDE]: ../../downloads/agent_development_tools/visualsoar.md diff --git a/docs/downloads/agent_development_tools/soaride.md b/docs/downloads/agent_development_tools/soaride.md index 94d8f81d..d8a2b84c 100644 --- a/docs/downloads/agent_development_tools/soaride.md +++ b/docs/downloads/agent_development_tools/soaride.md @@ -7,6 +7,10 @@ Tags: # SoarIDE +???+ warning "Warning" + This project is no longer actively maintained, instead use + [VisualSoar](./visualsoar.md). + The SoarIDE is an advanced editor for the Soar programming language based on the Eclipse platform, developed by Soar Technology. As an Eclipse plugin, the SoarIDE leverages all of the core features of Eclipse including a flexible UI, update manager, diff --git a/docs/downloads/soar/latest.md b/docs/downloads/soar/latest.md index fbacc676..846e5f0c 100644 --- a/docs/downloads/soar/latest.md +++ b/docs/downloads/soar/latest.md @@ -11,7 +11,7 @@ The current version of Soar is {{ soar_version }}. * [Soar Manual PDF](https://github.com/SoarGroup/Soar/releases/download/releases%2F{{soar_version}}/SoarManual.pdf) -* [VisualSoar Manual PDF](https://github.com/SoarGroup/Soar/releases/download/releases%2F{{soar_version}}/VisualSoar_UsersManual.pdf) +* [[VisualSoar][VSIDE] Manual PDF](https://github.com/SoarGroup/Soar/releases/download/releases%2F{{soar_version}}/VisualSoar_UsersManual.pdf) If you would like to build Soar from the current source code, you'll need to acquire the source from our git repository [on GitHub](https://github.com/SoarGroup/Soar). @@ -71,7 +71,7 @@ Tcl 9) ### Project Stability Improvements -* Newly designed JSON format for VisualSoar projects combining the datamap, operator +* Newly designed JSON format for [VisualSoar][VSIDE] projects combining the datamap, operator hierarchy/project layout, and comment files into one file ([#38](https://github.com/SoarGroup/VisualSoar/issues/38), [#5](https://github.com/SoarGroup/VisualSoar/issues/5)) * Far less likely to be corrupted @@ -80,7 +80,7 @@ hierarchy/project layout, and comment files into one file ([#38](https://github. * More robust to collaboration (no non-deterministic output, fewer git conflicts, easier to resolve if they do occur) * Handles arbitrary enum strings, attribute and operator names, etc. - * VisualSoar will write your project in the new format automatically, but + * [VisualSoar][VSIDE] will write your project in the new format automatically, but will ask you to delete the old project files yourself. Effort was taken to eliminate any chance of data loss or other unwanted surprises. * Read/write project and config files atomically @@ -96,7 +96,7 @@ saving everything without confirmation!) ### CLI Support -VisualSoar can now run project datamap validation from the command line by passing +[VisualSoar][VSIDE] can now run project datamap validation from the command line by passing the arguments `--check productionsAgainstDatamap --project `, where `` is the path to your project `.vsa` or `.vsa.json`. @@ -155,3 +155,5 @@ lines getting commented * Parameters are now parsed with the `commons-cli` library * `--help` and incorrect parameters now show CLI parameter documentation, so users don't have to go to the website + +[VSIDE]: ../../downloads/agent_development_tools/visualsoar.md diff --git a/docs/home/QuickStart.md b/docs/home/QuickStart.md index 428e5890..4a6e338e 100644 --- a/docs/home/QuickStart.md +++ b/docs/home/QuickStart.md @@ -18,7 +18,7 @@ and extract to the location of your choice. - Linux/Mac users can run `./SoarJavaDebugger.sh` from the terminal The other included applications are used in the tutorial, which is included under -`documentation/`. The manuals for Soar and VisualSoar can be found there, as +`documentation/`. The manuals for Soar and [VisualSoar][VSIDE] can be found there, as well. You can also build Soar from [source](https://github.com/SoarGroup/Soar) if @@ -26,3 +26,5 @@ you'd like to work with the latest version or make changes to it. Once you have Soar running, you can follow the [Soar Tutorial](../tutorials/soar_tutorial/index.md) to learn how to use it. + +[VSIDE]: ../downloads/agent_development_tools/visualsoar.md diff --git a/docs/index.md b/docs/index.md index 9da74e4d..93f74faa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,7 +19,7 @@ If you are looking for help or discussion, please see our * [**Soar 9.6.4 available for download**](https://github.com/SoarGroup/Soar/releases/download/releases%2F{{soar_version}}/SoarSuite_{{soar_version}}-Multiplatform.zip): This release of Soar contains lots of stability and ergonomics improvements to -VisualSoar and the Soar debugger, as well as newly-added support for LTI aliases. +[VisualSoar][VSIDE] and the Soar debugger, as well as newly-added support for LTI aliases. * This year's Soar workshop (45th) held on May 5, 2025 was a success! We had broad participation from various projects using Soar, including a remarkable presentation from our guest speaker @@ -33,3 +33,5 @@ available on GitHub. * [**Engineer's Guide to Soar**](https://github.com/SoarGroup/Engineers-Guide-to-Soar): A 14-part course on programming Soar for engineers, by Bryan Stearns is now available on GitHub. + +[VSIDE]: ../docs/downloads/agent_development_tools/visualsoar.md diff --git a/docs/reference/VisualSoarKeyboardAndMouseControls.md b/docs/reference/VisualSoarKeyboardAndMouseControls.md index 8329a3de..eb729352 100644 --- a/docs/reference/VisualSoarKeyboardAndMouseControls.md +++ b/docs/reference/VisualSoarKeyboardAndMouseControls.md @@ -9,14 +9,14 @@ key in the shortcuts below. * ESC Close open dialog * Ctrl+Q Quit VisualSoar -* Ctrl+, Open the VisualSoar preferences +* Ctrl+, Open the [VisualSoar][VSIDE] preferences * Ctrl+= Increase font size * Ctrl+- Decrease font size ### Project Level Actions -* Ctrl+N Open a new VisualSoar project -* Ctrl+O Open an existing VisualSoar project +* Ctrl+N Open a new [VisualSoar][VSIDE] project +* Ctrl+O Open an existing [VisualSoar][VSIDE] project * Ctrl+F Open a text file * Alt+X Save all open documents and close VisualSoar * Ctrl+T Tile windows horizontally @@ -33,7 +33,7 @@ key in the shortcuts below. ### Editing -The VisualSoar rule editor uses all the default editing keystrokes +The [VisualSoar][VSIDE] rule editor uses all the default editing keystrokes for area selection, clipboard operations and basic editing: * CTRL+C Copy the selected text to the clipboard @@ -75,7 +75,7 @@ and paste) as well as these keystrokes: ### Context menus -All windows in VisualSoar have context menus that +All windows in [VisualSoar][VSIDE] have context menus that accessible by pressing and holding the right mouse button. @@ -96,3 +96,5 @@ button. When using drag and drop with the datamap you should note that the mouse cursor changes as you begin the operation (the drag part). + +[VSIDE]: ../downloads/agent_development_tools/visualsoar.md diff --git a/docs/soar_manual/02_TheSoarArchitecture.md b/docs/soar_manual/02_TheSoarArchitecture.md index 6a7e6f15..0978be7c 100644 --- a/docs/soar_manual/02_TheSoarArchitecture.md +++ b/docs/soar_manual/02_TheSoarArchitecture.md @@ -45,20 +45,20 @@ problem, and a means of recognizing that the goal has been achieved. Soar’s procedural knowledge can be categorized into four distinct types of knowledge: -1. *Inference Rules* +1. *Inference Rules* In Soar, we call these state elaborations. This knowledge provides monotonic inferences that can be made about the state in a given situation. The knowledge created by such rules are not persistent and exist only as long as the conditions of the rules are met. -2. *Operator Proposal Knowledge* +2. *Operator Proposal Knowledge* Knowledge about when a particular operator is appropriate for a situation. Note that multiple operators may be appropriate in a given context. So, Soar also needs knowledge to determine which of the candidates to choose: -3. *Operator Selection Knowledge* +3. *Operator Selection Knowledge* Knowledge about the desirability of an operator in a particular situation. Such knowledge can be either in terms of a single operator (e.g. never choose this operator in this situation) or relational (e.g. prefer this operator over another in this situation). -4. *Operator Application Rules* +4. *Operator Application Rules* Knowledge of how a specific selected operator modifies the state. This knowledge creates persistent changes to the state that remain even after the rule no longer matches or the operator is no longer selected. @@ -91,10 +91,10 @@ When the knowledge to perform the problem-solving functions is not directly avai productions, Soar is unable to make progress and reaches an impasse. There are three types of possible impasses in Soar: -1. An operator cannot be selected because no new operators are proposed. -2. An operator cannot be selected because multiple operators are proposed and +1. An operator cannot be selected because no new operators are proposed. +2. An operator cannot be selected because multiple operators are proposed and the comparisons are insufficient to determine which one should be selected. -3. An operator has been selected, but there is insufficient knowledge to apply it. +3. An operator has been selected, but there is insufficient knowledge to apply it. In response to an impasse, the Soar architecture creates a substate in which operators can be selected and applied to generate or deliberately retrieve the knowledge that was not directly @@ -121,9 +121,9 @@ You do not need to look at the code at this point. The operators in this task move a single block from its current location to a new location; each operator is represented with the following information: -- the name of the block being moved -- the current location of the block (the "thing" it is on top of) -- the destination of the block (the "thing" it will be on top of) +- the name of the block being moved +- the current location of the block (the "thing" it is on top of) +- the destination of the block (the "thing" it will be on top of) The goal in this task is to stack the blocks so that C is on the table, with block B on top of block C, and block A on top of block B. @@ -184,7 +184,6 @@ candidate operators. For example, a preference may say that operator A is a that operator A is the "best" thing to do at this particular time. Preferences are discussed in detail in [how preferences are evaluated to decide an operator](#how-preferences-are-evaluated-to-decide-an-operator). - ![The six operators proposed for the initial state of the blocks world each move one block to a new location.](Images/blocks-proposal.svg) ### Selecting a single operator: Decision @@ -193,11 +192,11 @@ Soar attempts to select a single operator as a decision, based on the preferences available for the candidate operators. There are four different situations that may arise: -1. The available preferences unambiguously prefer a single operator. -2. The available preferences suggest multiple operators, and prefer a subset that can be +1. The available preferences unambiguously prefer a single operator. +2. The available preferences suggest multiple operators, and prefer a subset that can be selected from randomly. -3. The available preferences suggest multiple operators,but neither case 1 or 2 above hold. -4. The available preferences do not suggest any operators. +3. The available preferences suggest multiple operators,but neither case 1 or 2 above hold. +4. The available preferences do not suggest any operators. In the first case, the preferred operator is selected. In the second case, one of the subset is selected randomly. In the third and fourth cases, Soar has reached an impasse in problem @@ -236,11 +235,11 @@ environment. Therefore, the Soar program directly makes changes to the state when operators are applied. There are four changes that may need to be made when a block is moved in our task: -1. The block that is being moved is no longer where it was (it is no longer "on top" of +1. The block that is being moved is no longer where it was (it is no longer "on top" of the same thing). -2. The block that is being moved is in a new location (it is "on top" of a new thing). -3. The place that the block used to be in is now clear. -4. The place that the block is moving to is no longer clear — unless it is the table, which +2. The block that is being moved is in a new location (it is "on top" of a new thing). +3. The place that the block used to be in is now clear. +4. The place that the block is moving to is no longer clear — unless it is the table, which is always considered "clear".[1](#footnote1) The blocks-world task could also be implemented using an external simulator. In this case, @@ -362,33 +361,33 @@ suitable labels and to use them consistently. The elements in working memory arise from one of four sources: -1. ***Productions***: The actions on the RHS of productions create most working memory +1. ***Productions***: The actions on the RHS of productions create most working memory elements. -2. ***Architecture***: - - (a) State augmentations: The decision procedure automatically creates some special +2. ***Architecture***: + - (a) State augmentations: The decision procedure automatically creates some special state augmentations (type, superstate, impasse, ...) whenever a state is created. States are created during initialization (the first state) or because of an impasse (a substate). - - (b) Operator augmentations: The decision procedure creates the operator + - (b) Operator augmentations: The decision procedure creates the operator augmentation of the state based on preferences. This records the selection of the current operator. -3. ***Memory Systems*** -4. ***SVS*** -5. ***The Environment***: External I/O systems create working memory elements on the +3. ***Memory Systems*** +4. ***SVS*** +5. ***The Environment***: External I/O systems create working memory elements on the input-link for sensory data. The elements in working memory are removed in six different ways: -1. The decision procedure automatically removes all state augmentations it creates when +1. The decision procedure automatically removes all state augmentations it creates when the impasse that led to their creation is resolved. -2. The decision procedure removes the operator augmentation of the state when that +2. The decision procedure removes the operator augmentation of the state when that operator is no longer selected as the current operator. -3. Production actions that user `reject` preferences remove working memory elements that +3. Production actions that user `reject` preferences remove working memory elements that were created by other productions. -4. The architecture automatically removes i-supported WMEs when the productions that +4. The architecture automatically removes i-supported WMEs when the productions that created them no longer match. -5. The I/O system removes sensory data from the input-link when it is no longer valid. -6. The architecture automatically removes WMEs that are no longer linked to a state +5. The I/O system removes sensory data from the input-link when it is no longer valid. +6. The architecture automatically removes WMEs that are no longer linked to a state (because some other WME has been removed). For the most part, the user is free to use any attributes and values that are appropriate for the @@ -471,13 +470,13 @@ to that state. ### Architectural roles of productions -Soar productions can fulfill the following four roles, by retrieving +Soar productions can fulfill the following four roles, by retrieving [different types of procedural knowledge](#types-of-procedural-knowledge-in-soar): -1. Operator proposal -1. Operator comparison -1. Operator application -1. State elaboration +1. Operator proposal +1. Operator comparison +1. Operator application +1. State elaboration A single production should not fulfill more than one of these roles (except for proposing an operator and creating an absolute preference for it). Although @@ -563,21 +562,21 @@ is indifferent to B, and B is indifferent to C, A and C will not be indifferent unless there is a preference that A is indifferent to C (or C and A are both indifferent to all competing values). -- **Acceptable (+)** An `acceptable` preference states that a value is a candidate for selection. +- **Acceptable (+)** An `acceptable` preference states that a value is a candidate for selection. All values, except those with require preferences, must have an `acceptable` preference in order to be selected. If there is only one value with an `acceptable` preference (and none with a require preference), that value will be selected as long as it does not also have a reject or a prohibit preference. -- **Reject (-)** A `reject` preference states that the value is not a candidate for selection. +- **Reject (-)** A `reject` preference states that the value is not a candidate for selection. -- **Better (`>value`), Worse (`value`), Worse (`)** A `best` preference states that the value may be better than any +- **Best (>)** A `best` preference states that the value may be better than any competing value (unless there are other competing values that are also "best"). If a value is `best` (and not `rejected`, `prohibited`, or worse than another), it will be selected over any other value that is not also `best` (or required). If two such @@ -589,22 +588,22 @@ explicit knowledge about the relative worth of two values to dominate knowledge of only a single value. A require preference should be used when a value must be selected for the goal to be achieved.) -- **Worst (<)** A `worst` preference states that the value should be selected only if there are no +- **Worst (<)** A `worst` preference states that the value should be selected only if there are no alternatives. It allows for a simple type of default specification. The semantics of the worst preference are similar to those for the `best` preference. -- **Unary Indifferent (=)** A `unary indifferent` preference states that there +- **Unary Indifferent (=)** A `unary indifferent` preference states that there is positive knowledge that a single value is as good or as bad a choice as other expected alternatives. When two or more competing values both have indifferent preferences, by default, Soar chooses randomly from among the alternatives. (The [`decide indifferent-selection` function](../reference/cli/cmd_decide.md) can be used to change this behavior). -- **Binary Indifferent (=value)** A `binary indifferent` preference states that two values +- **Binary Indifferent (=value)** A `binary indifferent` preference states that two values are mutually indifferent and it does not matter which of these values are selected. It behaves like a unary in different preference, except that the operator value given this preference is only made indifferent to the operator value given as the argument. -- **Numeric-Indifferent (=number)** A `numeric-indifferent` preference is used +- **Numeric-Indifferent (=number)** A `numeric-indifferent` preference is used to bias the random selection from mutually indifferent values. This preference includes a unary indifferent preference, and behaves in that manner when competing with another value having a unary indifferent preference. But when a @@ -621,11 +620,11 @@ learning mechanism. In this way, it’s possible for an agent to begin a task wi only arbitrarily initialized numeric indifferent preferences and with experience learn to make the optimal decisions. See chapter 5 for more information. -- **Require (!)** A `require` preference states that the value must be selected if the goal is to be +- **Require (!)** A `require` preference states that the value must be selected if the goal is to be achieved. A `required` value is preferred over all others. Only a single operator value should be given a `require` preference at a time. -- **Prohibit (~)** A `prohibit` preference states that the value cannot be selected if the goal is +- **Prohibit (~)** A `prohibit` preference states that the value cannot be selected if the goal is to be achieved. If a value has a prohibit preference, it will not be selected for a value of an augmentation, independent of the other preferences. @@ -654,9 +653,9 @@ exits through a arrow to the right, or passes to the next step through an arrow Input to the procedure is the set of current operator preferences, and the output consists of: -1. A subset of the candidate operators, which is either the empty set, a single, winning +1. A subset of the candidate operators, which is either the empty set, a single, winning candidate, or a larger set of candidates that may be conflicting, tied, or indifferent. -2. An impasse-type. +2. An impasse-type. The procedure has several potential exit points. Some occur when the procedure has detected a particular type of impasse. The others occur when the number of candidates has been @@ -666,7 +665,7 @@ reduced to one (necessarily the winner) or zero (a no-change impasse). Each step in Figure 2.8 is described below: -- **RequireTest (!)** This test checks for required candidates in preference memory and also +- **RequireTest (!)** This test checks for required candidates in preference memory and also constraint-failure impasses involving require preferences, cf. [Impasses and Substates](#impasses-and-substates). - If there is exactly one candidate operator with a require preference and that candidate does not have a prohibit preference, then that candidate is the winner @@ -679,56 +678,56 @@ constraint-failure impasses involving require preferences, cf. [Impasses and Sub semantics terminates. - Otherwise — There is no required candidate; candidates are passed to AcceptableCollect. -- **AcceptableCollect (+)** This operation builds a list of operators for which there is an +- **AcceptableCollect (+)** This operation builds a list of operators for which there is an acceptable preference in preference memory. This list of candidate operators is passed to the ProhibitFilter. -- **ProhibitFilter (~)** This filter removes the candidates that have prohibit preferences in +- **ProhibitFilter (~)** This filter removes the candidates that have prohibit preferences in memory. The rest of the candidates are passed to the RejectFilter. -- **RejectFilter (-)** This filter removes the candidates that have reject preferences in mem- +- **RejectFilter (-)** This filter removes the candidates that have reject preferences in mem- ory. -- **Exit Point 1**: +- **Exit Point 1**: - At this point, if the set of remaining candidates is empty, a no-change impasse is created with no operators being selected. - If the set has one member, preference semantics terminates and this set is re- turned. - Otherwise, the remaining candidates are passed to the BetterWorseFilter. -- **BetterWorseFilter (>), (<)** This filter removes any candidates that are worse than an- +- **BetterWorseFilter (>), (<)** This filter removes any candidates that are worse than an- other candidate. -- **Exit point 2**: +- **Exit point 2**: - If the set of remaining candidates is empty, a conflict impasse is created returning the set of all candidates passed into this filter, i.e. all of the conflicted operators. - If the set of remaining candidates has one member, preference semantics terminates and this set is returned. - Otherwise, the remaining candidates are passed to the BestFilter. -- **BestFilter (>)** If some remaining candidate has a best preference, this filter removes any +- **BestFilter (>)** If some remaining candidate has a best preference, this filter removes any candidates that do not have a best preference. If there are no best preferences for any of the current candidates, the filter has no effect. The remaining candidates are passed to the WorstFilter. -- **Exit Point 3**: +- **Exit Point 3**: - At this point, if the set of remaining candidates is empty, a no-change impasse is created with no operators being selected. - If the set has one member, preference semantics terminates and this set is re- turned. - Otherwise, the remaining candidates are passed to the WorstFilter. -- **WorstFilter (<)** This filter removes any candidates that have a `worst` preference. If all +- **WorstFilter (<)** This filter removes any candidates that have a `worst` preference. If all remaining candidates have `worst` preferences or there are no `worst` preferences, this filter has no effect. -- **Exit Point 4**: +- **Exit Point 4**: - At this point, if the set of remaining candidates is empty, a no-change impasse is created with no operators being selected. - If the set has one member, preference semantics terminates and this set is re- turned. - Otherwise, the remaining candidates are passed to the IndifferentFilter. -- **IndifferentFilter (=)** This operation traverses the remaining candidates and marks each +- **IndifferentFilter (=)** This operation traverses the remaining candidates and marks each candidate for which one of the following is true: - the candidate has a unary indifferent preference - the candidate has a numeric indifferent preference @@ -745,22 +744,22 @@ by the [`decide indifferent-selection` command](../reference/cli/cmd_decide.md). The execution of a Soar program proceeds through a number of decision cycles. Each cycle has five phases: -1. **Input**: New sensory data comes into working memory. -2. **Proposal**: Productions fire (and retract) to interpret new data (state +1. **Input**: New sensory data comes into working memory. +2. **Proposal**: Productions fire (and retract) to interpret new data (state elaboration), propose operators for the current situation (operator proposal), and compare proposed operators (operator comparison). All of the actions of these productions are i-supported. All matched productions fire in parallel (and all retractions occur in parallel), and matching and firing continues until there are no more additional complete matches or retractions of productions (*quiescence*). -3. **Decision**: A new operator is selected, or an impasse is detected and a new state is +3. **Decision**: A new operator is selected, or an impasse is detected and a new state is created. -4. **Application**: Productions fire to apply the operator (operator application). +4. **Application**: Productions fire to apply the operator (operator application). The actions of these productions will be o-supported. Because of changes from operator application productions, other productions with i-supported actions may also match or retract. Just as during proposal, productions fire and retract in parallel until quiescence. -5. **Output**: Output commands are sent to the external environment. +5. **Output**: Output commands are sent to the external environment. The cycles continue until the halt action is issued from the Soar program (as the action of a production) or until Soar is interrupted by the user. @@ -803,14 +802,15 @@ When Soar interacts with an external environment, it must make use of mechanisms allow it to receive input from that environment and to effect changes in that environment; the mechanisms provided in Soar are called input functions and output functions. -- **Input functions** add and delete elements from working memory in response to changes in +- **Input functions** add and delete elements from working memory in response to changes in the external environment. -- **Output functions** attempt to effect changes in the external environment. +- **Output functions** attempt to effect changes in the external environment. Input is processed at the beginning of each execution cycle and output occurs at the end of each execution cycle. See [Soar I/O: Input and Output in Soar](./03_SyntaxOfSoarPrograms.md#soar-io-input-and-output-in-soar) for more information. -A simplified version of the Soar algorithm: +A simplified version of the Soar algorithm: + ``` Soar while (HALT not true) Cycle; @@ -880,15 +880,16 @@ decision and if they conflict, no progress can be made from the current situation and the impasse cannot be resolved by additional preferences. #### No-change impasse + A *no-change* impasse arises if a new operator is not selected during -the decision procedure. There are two types of no-change impasses: +the decision procedure. There are two types of no-change impasses: -- A **State no-change impasse** occurs when there are no `acceptable` (or `require`) +- A **State no-change impasse** occurs when there are no `acceptable` (or `require`) preferences to suggest operators for the current state (or all the `acceptable` values have also been rejected). The decision procedure cannot select a new operator. -- A **Operator no-change impasse** occurs when either a new operator is selected for +- A **Operator no-change impasse** occurs when either a new operator is selected for the current state but no additional productions match during the application phase, or a new operator is not selected during the next decision phase. @@ -898,8 +899,8 @@ failure impasse at the same time. In these cases, Soar detects only the constrai impasse. The impasse is detected *during* the selection of the operator, but happens -because one of the four problem-solving functions (described in -[Problem-Solving function in Soar](#problem-solving-functions-in-soar)) +because one of the four problem-solving functions (described in +[Problem-Solving function in Soar](#problem-solving-functions-in-soar)) was incomplete. ### Creating New States @@ -991,20 +992,20 @@ Soar must first determine the function that the working memory element or prefer Soar creates a temporary production, called a **justification**. The justification summarizes the processing in the substate that led to the result: -- **The conditions** of a justification are those working memory elements that exist in the +- **The conditions** of a justification are those working memory elements that exist in the superstate (and above) that were necessary for producing the result. This is determined by collecting all of the working memory elements tested by the productions that fired in the subgoal that led to the creation of the result, and then removing those conditions that test working memory elements created in the subgoal. -- **The action** of the justification is the result of the subgoal. +- **The action** of the justification is the result of the subgoal. Thus, when the substate disappears, the generated justification serves as the production that supports any subgoal results. Soar determines i-support or o-support for the justification and its actions just as it would for any other production, as described in section -[Production Actions and Persistence](#production-actions-and-persistence). +[Production Actions and Persistence](#production-actions-and-persistence). If the justification is an operator application, the result will receive o-support. Otherwise, the result gets i-support from the justification. If such a result loses i-support from the justification, it will be retracted if there @@ -1038,8 +1039,8 @@ Chunks and justifications are very similar in that they both summarize substate They are, in fact, generated by the architecture using the same result dependency trace mechanisms. However, there are some important distinctions: -1. Justifications disappear as soon as its conditions no longer match. -2. Chunks contain variables so that they may match working memory in other situations; +1. Justifications disappear as soon as its conditions no longer match. +2. Chunks contain variables so that they may match working memory in other situations; justifications are similar to an instantiated chunk. In other words, a chunk might be thought of as a permanent and potentially more generalized @@ -1063,12 +1064,14 @@ Side), respectively. A production must meet the following two requirements to have o-supported actions: -1. The RHS has no operator proposals, i.e. nothing of the form +1. The RHS has no operator proposals, i.e. nothing of the form + ``` ( ^operator +) ``` -2. The LHS has a condition that tests the current operator, i.e. something of the form +2. The LHS has a condition that tests the current operator, i.e. something of the form + ``` ( ^operator ) ``` @@ -1088,7 +1091,7 @@ sp {elaborate*state*operator\*name ( ^name something)} ``` -the RHS action gets i-support. Of course, the state bound to `` is destroyed when +the RHS action gets i-support. Of course, the state bound to `` is destroyed when `( ^operator )` retracts, so o-support would make little difference. On the other hand, this production, @@ -1146,24 +1149,24 @@ removed from working memory. Here are possible approaches for resolving specific types of impasses are listed below: -- **Tie impasse** — A tie impasse can be resolved by productions that create preferences that +- **Tie impasse** — A tie impasse can be resolved by productions that create preferences that prefer one option (`better`, `best`, `require`), eliminate alternatives (`worse`, `worst`, `reject`,`prohibit`), or make all of the objects indifferent (`indifferent`). -- **Conflict impasse** — A conflict impasse can be resolved by productions that +- **Conflict impasse** — A conflict impasse can be resolved by productions that create preferences to require one option (`require`), or eliminate the alternatives (`reject`, `prohibit`). -- **Constraint-failure impasse** — A constraint-failure impasse cannot be resolved +- **Constraint-failure impasse** — A constraint-failure impasse cannot be resolved by additional preferences, but may be prevented by changing productions so that they create fewer `require` or `prohibit` preferences. A substate can resolve a constraint-failure impasse through actions that cause all but one of the conflicting preferences to retract. -- **State no-change impasse** — A state no-change impasse can be resolved by productions +- **State no-change impasse** — A state no-change impasse can be resolved by productions that create `acceptable` or `require` preferences for operators. -- **Operator no-change impasse** — An operator no-change impasse can be resolved by +- **Operator no-change impasse** — An operator no-change impasse can be resolved by productions that apply the operator, change the state so the operator proposal no longer matches, or cause other operators to be proposed and preferred. @@ -1327,8 +1330,6 @@ context. The following discussion covers what the GDS does, and how that impacts production knowledge design and implementation. - - **Operation of the Goal Dependency Set**: Consider i-support. The persistence of an i-supported ("instantiation supported") WME depends upon the creating production instantiation (and, more specifically, the features the instantiation tests). @@ -1365,19 +1366,19 @@ the dependency set is empty. Three types of features can be tested in the creation of an o-supported feature. Each requires a slightly different type of update to the dependency set. -1. **Elements in the superstate**: WMEs in the superstate are added directly to the +1. **Elements in the superstate**: WMEs in the superstate are added directly to the goal’s dependency set. In Figure 2.13, the persistent subgoal item 3 is dependent upon A and D. These superstate WMEs are added to the subgoal’s dependency set when 3 is added to working memory at time $t_1$. It does not matter that A is i-supported and Do-supported. -2. **Local i-supported features**: Local i-supported features are not added to the goal +2. **Local i-supported features**: Local i-supported features are not added to the goal dependency set. Instead, the superstate WMEs that led to the creation of the i- supported feature are determined and added to the GDS. In the example, when 4 is created,A, B and C must be added to the dependency set because they are the superstate features that led to 1 , which in turn led to 2 and finally 4. However, because item A was previously added to the dependency set at $t_1$ , it is unnecessary to add it again. -3. **Local o-supported features**: The dependencies of a local o-supported feature have +3. **Local o-supported features**: The dependencies of a local o-supported feature have already been added to the state’s GDS. Thus, tests of local o-supported WMEs do not require additions to the dependency set. In Figure 2.13, the creation of element 5 does not change the dependency set because it is dependent only upon persistent items 3 @@ -1390,25 +1391,25 @@ dependency set. **The role of the GDS in agent desig**n: The GDS places some design time constraints on operator implementation. These constraints are: -- Operator actions that are used to remember a previous state/situation should be asserted in the top state. -- All operator elaborations should be i-supported. -- Any operator with local actions should be designed to be re-entrant. +- Operator actions that are used to remember a previous state/situation should be asserted in the top state. +- All operator elaborations should be i-supported. +- Any operator with local actions should be designed to be re-entrant. Because any dependencies for o-supported subgoal WMEs will be added to the GDS, the developer must decide if an o-supported element should be represented in a substate or the top state. This decision is straightforward if the functional role of the persistent element is considered. Four important capabilities that require persistence are: -1. **Reasoning hypothetically**: Some structures may need to reflect hypothetical states. +1. **Reasoning hypothetically**: Some structures may need to reflect hypothetical states. These are "assumptions" because a hypothetical inference cannot always be grounded in the current context. In problem solvers with truth maintenance, only assumptions are persistent. -2. **Reasoning non-monotonically**: Sometimes the result of an inference changes one +2. **Reasoning non-monotonically**: Sometimes the result of an inference changes one of the structures on which the inference is dependent. As an example, consider the task of counting. Each newly counted item replaces the old value of the count. -3. **Remembering**: Agents oftentimes need to remember an external situation or +3. **Remembering**: Agents oftentimes need to remember an external situation or stimulus, even when that perception is no longer available. -4. **Avoiding Expensive Computations**: In some situations, an agent may have the +4. **Avoiding Expensive Computations**: In some situations, an agent may have the information needed to derive some belief in a new world state but the expense of performing the necessary computation makes this derivation undesirable. For example, in dynamic, complex domains, determining when to make an expensive calculation is @@ -1428,31 +1429,31 @@ computationally expensive than attempting to identify the specific dependent ass ## Footnotes -- [1]: In this blocks-world task, the table always has +- [1]: In this blocks-world task, the table always has room for another block, so it is represented as always being "clear". -- [2]: In order to allow these links to have some +- [2]: In order to allow these links to have some substructure, the attribute name may be an identifier, which means that the attribute may itself have attributes and values, as specified by additional working memory elements. -- [3]: The original state is the "top" of the stack +- [3]: The original state is the "top" of the stack because as Soar runs, this state (created first), will be at the top of the computer screen, and substates will appear on the screen below the top-level state. -- [4]: Technically, an i-supported WME is only retracted +- [4]: Technically, an i-supported WME is only retracted when it loses instantiation support, not when the creating production is retracting. For example, a WME could receive i-support from several different instantiated productions and the retraction of only one would not lead to the retraction of the WME. justification. If such a result loses i-support from the justification, it will be retracted if there is no other support. -- [5]: In the past, Soar had various experimental +- [5]: In the past, Soar had various experimental support mode settings. Since version 9.6, the support mode used is what was previously called mode 4. with rule syntax (explained in [Chapter 3](./03_SyntaxOfSoarPrograms.md)) may wish to skip this section and return at a later point. -- [6]: Robert E. Wray. Ensuring Reasoning Consistency in +- [6]: Robert E. Wray. Ensuring Reasoning Consistency in Hierarchical Architectures. PhD thesis, University of Michigan, 1998. -- [7]: This subsection will primarily use "state," not +- [7]: This subsection will primarily use "state," not "goal." While these terms are often used nearly-interchangeably in the context of Soar, states refer to the set of WMEs comprising knowledge related to a peculiar level of goal. TheGoalDependency Set is the set of state elements upon - which a goal depends. + which a goal depends. diff --git a/docs/tutorials/soar_tutorial/01.md b/docs/tutorials/soar_tutorial/01.md index e8070935..a882d8cd 100644 --- a/docs/tutorials/soar_tutorial/01.md +++ b/docs/tutorials/soar_tutorial/01.md @@ -346,7 +346,7 @@ Soar that halts the agent. From this simple example, you should be able to write your own rules that print out different messages for Soar. If you wish to try this out yourself, you have two choices. The first is -to use VisualSoar. VisualSoar is the Soar development environment and it +to use VisualSoar. [VisualSoar][VSIDE] is the Soar development environment and it lets you develop and manage Soar programs. It has its own documentation and tutorial and can be found at the Soar web pages. Also, the Water-Jug problem that is presented later in this tutorial contains an explanation @@ -642,8 +642,8 @@ with operators. ## An Introduction to VisualSoar To create your own Soar programs, you can use almost any editor. We -recommend VisualSoar because it has internal support for creating Soar -programs. VisualSoar can be found in the same place that the Soar +recommend [VisualSoar][VSIDE] because it has internal support for creating Soar +programs. [VisualSoar][VSIDE] can be found in the same place that the Soar debugger was found. On launch, a fairly blank window entitled VisualSoar will pop-up. At the top, click File | New Project… and you will see a new pop-up window entitled New Agent. In the new window under Agent Name @@ -660,19 +660,19 @@ will be explained as the tutorial proceeds. It is files like these that will contain the rules you write for an agent. The rules will be grouped into different files and file types depending on their function. It is from this window that you will control the way the rules are grouped -together. The actual grouping of rules in VisualSoar is actually +together. The actual grouping of rules in [VisualSoar][VSIDE] is actually completely arbitrary to Soar but will make maintaining and debugging your code much easier for you. Due to this arbitrariness, do not feel that you can create an error by grouping your rules wrong. One of the toughest parts of writing Soar code is visualizing the -tree-like structure of working memory. VisualSoar has a structure called +tree-like structure of working memory. [VisualSoar][VSIDE] has a structure called the Datamap for describing working memory structure. In some ways, it is like making type definitions in other languages. To examine the Datamap, right-click on the root of the tree entitled ‘water-jug’ and click on Open Datamap in the pop-up window. Doing this displays the hierarchical structure of the working memory of your agent in the Datamap water-jug -window. VisualSoar not only lets you visually construct what memory +window. [VisualSoar][VSIDE] not only lets you visually construct what memory should look like, it also lets you run tests to make sure your code follows the proper structure, automatically finding spelling mistakes, misplaced structures, and so on. You can close the Datamap water-jug @@ -912,16 +912,16 @@ sp {water-jug*propose*initialize-water-jug **VisualSoar** – The purpose of this production is to propose the operator that will initialize the water-jug. If you look at the operator -window in VisualSoar you will see that the file at the bottom is titled +window in [VisualSoar][VSIDE] you will see that the file at the bottom is titled “initialize-water-jug.” This is created automatically when you created the water-jug project because a standard practice is to use an initialization operator for a new task. Either double-click on that file or right-click on the file and click Open Rules. This will open up a rule editor in which you will see two rules already partially written. The initialization written above is a very standard one, and because of -this VisualSoar automatically creates a template of it for you (it is +this [VisualSoar][VSIDE] automatically creates a template of it for you (it is the first rule at the top). It may look a little different because -VisualSoar uses a few shortcuts that you will learn later, feel free to +[VisualSoar][VSIDE] uses a few shortcuts that you will learn later, feel free to leave it how it is or change it to the way it is above, it will not matter. Leave this rule window open. @@ -940,7 +940,7 @@ that would not change the meaning of the rule. All the conditions test attributes of the same object (the state), and you can simplify the rule by combining these conditions (just as -VisualSoar did) into a single structure where the identifier `()` is +[VisualSoar][VSIDE] did) into a single structure where the identifier `()` is followed by the attributes: ```Soar @@ -986,22 +986,22 @@ will be created by another rule that dynamically computes it based on the volume and contents (see Section 4.5). **VisualSoar** – In the initialize-water-jug rule window you will notice -that VisualSoar has attempted to write this rule for you also. The +that [VisualSoar][VSIDE] has attempted to write this rule for you also. The application of initializing the water-jug is not as standard as the -proposal and VisualSoar is not able to initialize all of the attributes +proposal and [VisualSoar][VSIDE] is not able to initialize all of the attributes that this project will need. Modify the second rule in the rule window to match the rule above. Now, at the top of VisualSoar, click on Datamap | Check All Productions Against the Datamap. In the feedback window at the bottom you will see a -list of blue warnings. What you just did was make VisualSoar check all +list of blue warnings. What you just did was make [VisualSoar][VSIDE] check all of your rules to see if they matched the Datamap for this project. Recall that the Datamap is a representation of the structure of working memory. Since you just added new augmentations to the state in your rule, but not to the Datamap, warnings are created. To fix this, right-click in the operator window on “water-jug” and click on Open Datamap so that now you have the Datamap and initialize-water-jug -windows open. You will notice that VisualSoar has already included the +windows open. You will notice that [VisualSoar][VSIDE] has already included the structure for the Initialize-water-jug operator – this is automatically created whenever a new operator is added to the operator set. The Datamap is a hierarchical structure that looks like folders and files as @@ -1040,7 +1040,7 @@ selection. Your screen should now look like this: ![](Images/01/image16.png) -Now have VisualSoar check all productions against the Datamap (using the +Now have [VisualSoar][VSIDE] check all productions against the Datamap (using the command under the Datamap tab in the toolbar), you should have no errors. Make sure to save and feel free to close the Datamap and initialize-water-jug windows. @@ -1191,7 +1191,7 @@ When the contents of a jug changes through an operator application rule, this rule will retract the old value of ^empty and fire to compute a new value. -**VisualSoar** – This rule is an elaboration. VisualSoar has a folder +**VisualSoar** – This rule is an elaboration. [VisualSoar][VSIDE] has a folder named elaborations in the operator window to hold files for state elaborations. Right-click on this folder and click “Add a File…”. You will see a text box pop-up. In the Name category type “empty” and click @@ -1430,7 +1430,7 @@ that, hold down the “ctrl” and “shift” keys (usually with your left hand). This should make a new icon appear that has a little arrow (see diagram below). Then let up on the mouse button (while keeping “ctrl” and “shift” down. This will create an attribute of the operator with -name “jug”. (Note: sometimes the display of the Datamap in VisualSoar is +name “jug”. (Note: sometimes the display of the Datamap in [VisualSoar][VSIDE] is not correctly updated. You might need to close the Datamap and reopen it for it to refresh correctly). @@ -1879,7 +1879,7 @@ where should water-jug*apply*initialize\*create\*desired-state be placed? Since it tests the initialize-water-jug operator, it naturally should be added to the folder that holds that operator. Remember, how you group your rules is completely up to you. It makes sense to think of -grouping in VisualSoar as an advanced way to comment code: it doesn’t +grouping in [VisualSoar][VSIDE] as an advanced way to comment code: it doesn’t affect the way the code is interpreted by the computer, but if you or anyone else ever has to alter the code, it will make it much easier to understand. From here on out, it is up to you to choose how you want to @@ -2139,3 +2139,5 @@ problem in Soar. 9. S1 will always be the identifier of the first state, but that is an artifact of the way Soar is implemented. + +[VSIDE]: ../../downloads/agent_development_tools/visualsoar.md diff --git a/docs/tutorials/soar_tutorial/02.md b/docs/tutorials/soar_tutorial/02.md index a1b9ab26..2565f8f0 100644 --- a/docs/tutorials/soar_tutorial/02.md +++ b/docs/tutorials/soar_tutorial/02.md @@ -185,7 +185,7 @@ also be “cloned” or destroyed. To destroy an eater, click on the eater Name the Agent List (highlight it) and press the “Destroy” button. To reload the production rules for the eater, you should use the reload button -(not implemented yet\!), or if you create an Eater using VisualSoar you can use +(not implemented yet\!), or if you create an Eater using [VisualSoar][VSIDE] you can use the runtime tab to reload the agent, reload a file, or change a single rule. Reloading is useful if you have found a bug, modified the rules in the file, and then wish to immediately test them on the current situation. Soar will replace @@ -974,19 +974,19 @@ Productions for Syntax Errors. ![](Images/02/image23.png) -VisualSoar will check all of your productions to make sure that they +[VisualSoar][VSIDE] will check all of your productions to make sure that they conform to the standard syntax rules. The results of this check will appear in the feedback window (which is located at the bottom of the -VisualSoar window). If an error is found, an informative error message +[VisualSoar][VSIDE] window). If an error is found, an informative error message will appear in blue. The first part of the error message will be the name of the file where the error was found and its line number in the format `(line number):` This is then followed by more output which will include the specific path of the file the error was found in, -and why VisualSoar considers it a syntax error: +and why [VisualSoar][VSIDE] considers it a syntax error: ![](Images/02/image24.png) -One of the best features of VisualSoar is that double-clicking on an +One of the best features of [VisualSoar][VSIDE] is that double-clicking on an error message allows you to see exactly where the error occurred. Double-clicking an error message automatically opens the window in which the error was found, and highlights the illegal area in yellow. For @@ -999,7 +999,7 @@ If no errors are found, “There were no errors detected in this project” will be printed in the feedback window. We suggest playing around with this tool. Delete brackets and braces, \# -signs and -->’s to see what errors VisualSoar gives you so that you are +signs and -->’s to see what errors [VisualSoar][VSIDE] gives you so that you are able to quickly recognize what types of messages certain errors give. This will make future debugging much easier. @@ -2308,3 +2308,5 @@ attribute. ^superstate nil ^type state ``` + +[VSIDE]: ../../downloads/agent_development_tools/visualsoar.md diff --git a/docs/tutorials/soar_tutorial/03.md b/docs/tutorials/soar_tutorial/03.md index c92b5585..a886bbc6 100644 --- a/docs/tutorials/soar_tutorial/03.md +++ b/docs/tutorials/soar_tutorial/03.md @@ -12,7 +12,7 @@ intermediate sections teach you to write high-level operators. The end concentrates on refinements of these operators so that your tank is more effective. -You should use VisualSoar in developing your tank. The release includes +You should use [VisualSoar][VSIDE] in developing your tank. The release includes default datamaps for the input and output links so that you do not have to define them yourself. You use them by opening the default project and then using the SAVE AS feature in Visual Soar to save the project under @@ -62,7 +62,7 @@ be loaded when a Tank is created. Each tank has three resources. A summary of these is shown, along with a score, for each tank to the right of the Map window. -- _Health_ +- _Health_ A tank has a maximum of 1000 health points, and dies when its health goes to 0. When a tank dies, it is resurrected at a random open square with the initial values of all of its resources (health=1000, @@ -71,7 +71,7 @@ score, for each tank to the right of the Map window. health decreases by 400. A tank's health is increased when it sits on a healthcharger at a rate of 150 per turn. -- _Energy_ +- _Energy_ A tank has a maximum of 1000 energy points. A tank's energy is decreased when it uses its radar (proportional to the range it has set the radar) or when it uses its shields (20 units per turn). A @@ -81,7 +81,7 @@ score, for each tank to the right of the Map window. to 0, it will not be able to use its radar or shields until it recharges (or dies). -- _Missiles_ +- _Missiles_ A tank starts off with 15 missiles. A tank's supply of missiles is increased by 7 when it picks up a pack of missiles. A tank's supply of missiles is decreased by one each time it fires a missile. @@ -96,7 +96,7 @@ on to use. The information from these sensors is made available to a tank on the input-link. The structure of the input-link augmentation is shown for each sensor. -- _Blocked sensor_ +- _Blocked sensor_ The blocked sensor detects whether the squares immediately adjacent to a tank are blocked or open (yes=blocked, no=open). A square can be blocked by an obstacle or by another tank, but the blocked sensor @@ -112,7 +112,7 @@ shown for each sensor. ^right yes/no ``` -- _Incoming sensor_ +- _Incoming sensor_ The incoming sensor detects whether there is a missile approaching a tank at any distance, unless the missile is on the other side of an obstacle or tank. It does not detect a tank's own missiles. @@ -169,7 +169,7 @@ shown for each sensor. ^color red/blue/purple/… ``` -- _Rwaves sensor_ +- _Rwaves sensor_ The rwave sensor detects if the radar of another tank is detecting the tank from the four directions. @@ -181,7 +181,7 @@ shown for each sensor. ^right yes/no ``` -- _Smell sensor_ +- _Smell sensor_ The smell sensors detects the closest tank, and provides information on how close that tank is and what its color is. If there are two or more tanks equally close, then one of them is chosen at random. The @@ -196,7 +196,7 @@ shown for each sensor. ^distance none/0-28 ``` -- _Sound sensor_ +- _Sound sensor_ The sound sensor detects the closest tank that moved during the last decision, as long as that tank is currently 7 or less squares away. If two or more tanks moved during the last decision and are equally @@ -365,7 +365,7 @@ A tank has several actions it can perform. All actions are performed by augmenting the output-link. All actions can be performed in parallel except for move and rotate. -- _Move_ +- _Move_ A tank can move forward, backward, left, or right. Moving is mutually exclusive with rotating. If a tank tries to move but is blocked, it remains where it is and loses 100 health units. A tank @@ -375,7 +375,7 @@ except for move and rotate. ^move.direction left/right/forward/backward/none ``` -- _Rotate_ +- _Rotate_ A tank can rotate left or right. Rotating is mutually exclusive with moving. A rotate will never fail (assuming the tank is neither killed nor tries to simultaneously move). @@ -384,7 +384,7 @@ except for move and rotate. ^rotate.direction left/right ``` -- _Fire_ +- _Fire_ A tank can fire one missile per decision. Firing can be done in conjunction with any other action. The missile is fired straight ahead in the direction the tank is facing. Firing a missile @@ -396,7 +396,7 @@ except for move and rotate. ^fire.weapon missile. ` -- _Radar_ +- _Radar_ A tank can turn its radar on and off. Turning the radar on will fail if a tank does not have enough energy to supply the radar. This failure will be reflected in that ^radar-distance will adjust itself @@ -432,14 +432,14 @@ except for move and rotate. The following are the objects that can appear on the map: -- ![Obstacles](Images/03/image5.png)_Obstacles_ +- ![Obstacles](Images/03/image5.png)_Obstacles_ Obstacles look like trees and they are there to get in the way. They never move and they cannot be blown up. There will not be any part of the playing field that is inaccessible purely due to wall placement. (Part of the playing field could be temporarily inaccessible due to a tank blocking the way.) -- ![Healthcharger](Images/03/image6.png)_Healthcharger_ +- ![Healthcharger](Images/03/image6.png)_Healthcharger_ There is one healthcharger per map. The healthcharger never moves. For each decision a tank stays on a healthcharger, its health is increased by 150 minus and any damage it may incur by bumping into @@ -452,7 +452,7 @@ The following are the objects that can appear on the map: energy it uses for its shields and/or radar. - ![Packs of missiles](Images/03/image8.png)_Packs of - missiles_ + missiles_ Packs of missiles are scattered around in random squares. They never move of their own accord nor can they be moved. Missiles flying through squares with packs of missiles do not hit those packs. Packs @@ -460,7 +460,7 @@ The following are the objects that can appear on the map: pick up a pack of missiles by moving to its square. The pack of missiles disappears and the tank's missile supply is increased by 7. -- ![Tanks](Images/03/image9.png)_Tanks_ +- ![Tanks](Images/03/image9.png)_Tanks_ Tanks are controlled by TankSoar agents. They do fun stuff like fire missiles and move around, as described above. @@ -1146,7 +1146,7 @@ sp {elaborate*state*name ( ^name )} ``` -This rule is always created by VisualSoar and is in the default set of +This rule is always created by [VisualSoar][VSIDE] and is in the default set of rules, so you don’t have to add it. With these two changes, the new rule is essentially the original, but with the name of the state being tested changed to wander. @@ -2637,3 +2637,5 @@ Some general advice to keep you out of trouble is: - Don’t combine operators that create internal persistent structures. This isn’t as important as the other two; however, by keeping each operator separate, it will be much easier to debug your code. + +[VSIDE]: ../../downloads/agent_development_tools/visualsoar.md diff --git a/docs/tutorials/soar_tutorial/06.md b/docs/tutorials/soar_tutorial/06.md index 796cb48f..d1cd0366 100644 --- a/docs/tutorials/soar_tutorial/06.md +++ b/docs/tutorials/soar_tutorial/06.md @@ -39,7 +39,7 @@ left and right. Because the agent does not know a priori which direction is better, the agent will be indifferent as to the preference between these actions. As you are unfamiliar with the particulars of RL agent design, either type the following code into your favorite editor or open -the VisualSoar *left-right* project in the *Agents* directory: +the [VisualSoar][VSIDE] *left-right* project in the *Agents* directory: #### Initialization @@ -521,3 +521,5 @@ selection. With this explanation, you should experiment with different values of epsilon during different runs in the agents discussed in this tutorial. + +[VSIDE]: ../../downloads/agent_development_tools/visualsoar.md