1. Jacob Crossman With help from Bob Marinier Anthony Deschamps
New Goal System (NGS) 4.x
Jacob Crossman
With help from
Bob Marinier
Anthony Deschamps

2. NGS 4.x – a new Soar programming abstraction layer
Origins/Purpose
NGS = New Goal System
Initially a few productions and macros to make writing top-state goal forests easier/consistent
I wrote NGS 1.0 in 2004
Various improvements and libraries were added by others since then (up to NGS 3.x)
Simultaneously I worked on the High-Level Symbolic Representation (HLSR):
Goal was a higher level language
Compiled to both Soar and ACT-R
Worked but not optimized for Soar programming
NGS 4.x – a new Soar programming abstraction layer
Still makes goal forests easy (but doesn’t force it)
Is a much, much more

3. Overview NGS 4.x is implemented in TCL
99% of code is written in TCL – if you are writing raw Soar, in most cases, you are doing it wrong
Retains some aspects of Soar syntax (e.g. variables, dot notation)
RHS functions still use ”raw” Soar
It is a library that you load before you load your domain specific code
It “compiles” into raw Soar (no TCL runtime required except for debugging)
No, there isn’t a specific debugger, but there are two very useful debugging commands:
“np” – new print (NGS-aware WME printing)
“nps” – new print stack (NGS goal stack printing)

4. Anatomy of a Production
sp “production-name
[ngs-match-* <s> …]
[ngs-bind <s> foo.bar.position]
[ngs-is-X <bar> etc]
[ngs-gt <position> x 5.0] 
[ngs-create-X <foo> new-attr <new-val>] OR
[ngs-create-X-by-operator <s> <foo> new-attr <new-val>]
[ngs-tag <new-val> my-tag]”

5. Wrapping the Left Hand Side
All productions start with an “ngs-match” production
Always binds the state
Each macro is intended to bind the correct items for a given purpose (e.g. create goal, return value, etc)
Most productions are followed with one or more “ngs-bind” lines that bind a pattern in working memory
Other macros are used to make simple tests (e.g. “ngs-is-type” or “ngs-gt”)

6. ngs-bind ngs-bind is a mini-language by itself
Simplifies complex bind trees
Automates variable creation
Supports some comparisons
Greatly simplifies LHS binding logic and makes easier to read
Example:
[ngs-bind <s> agent:<me>]
[ngs-bind <me> situations.situation!StopAhead \
vehicle-state.stable-velocity:<:$THRESHOLD]
TURNS INTO 
(<s> ^agent <me>)
(<me> ^situations <situations>)
(<situations> ^situation <situation>)
(<situation> ^type StopAhead)
(<me> ^vehicle-state <vehicle-state>)
(<vehicle-state> ^stable-velocity < 0.02)

7. Wrapping the Right Hand Side
Right hand sides typically structured as
Primary action (o or i-supported)
Secondary/supporting actions
Common Right Hand Side Macros
I-Supported
O-Supported
Typed Objects
ngs-create-typed-object
ngs-create-typed-object-by-operator
ngs-create-typed-sub-object-by-operator
Attributes
ngs-create-attribute
ngs-create-attribute-by-operator
ngs-remove-attribute-by-opeator
Tags
ngs-tag
ngs-create-tag-by-operator
ngs-remove-tag-by-operator
Goals
ngs-create-goal-in-place
ngs-create-goal-by-operator
ngs-remove-goal-by-operator
Other
ngs-deep-copy-by-operator
ngs-create-output-command-by-operator

8. Operator Applications
NGS 4.x does not require any operator application applications
All applications in library
Guarantee proper application for complex structure creation (up to 5 levels deep)
Properly syncs up with side effects
One operator per production (but see side effects on next slide)
Operators are all-or-nothing – they either completely construct their object or don’t (no partial applies)
Operators can create
Deep structure (typed objects and/or deep copy)
Links (attributes)
Tags
Output commands

9. Operator Side Effects
Side effects can be used to create simple structure along with the primary operator application
Common: create tags
Other: link object somewhere else, set timer, etc
Two macros
ngs-add-primitive-side-effect
ngs-add-tag-side-effect

10. Example: Counting Teammates
sp "my-team*propose*count*expected-num-human-team-members
[ngs-match-top-state <s> robo-agent.my-team.member. \
member-info!HumanEntity]
[ngs-bind <my-team> expected-num-human-team-members:<cur-count>]
[ngs-nex
-->
[ngs-create-attribute-by-operator <s> <my-team> \
expected-num-human-team-members "(+ <cur-count> 1)"]
[ngs-add-tag-side-effect $NGS_SIDE_EFFECT_ADD <member> counted]"
Expanded Code (as viewed from Soar IDE, reformatted for space/clarity):
sp {my-team*propose*count*expected-num-human-team-members
(state <s> ^superstate nil)
(<s> ^robo-agent <robo-agent>)
(<robo-agent> ^my-team <my-team>)
(<my-team> ^member <member>)
(<member> ^member-info <member-info>)
(<member-info> ^type HumanEntity)
(<my-team> ^expected-num-human-team-members <cur-count>)
(<member> -^__tagged*counted)
-->
(<s> ^operator <o> + =)
(<o> ^name (concat |create-wme--| <my-team> |--expected-num-human-team-members--| (+ <cur-count> 1))
^type atomic)
(<o> ^__tagged*ngs*i-supported *YES* +)
(<o> ^dest-object <my-team>
^dest-attribute expected-num-human-team-members
^new-obj (+ <cur-count> 1)
^replacement-behavior ngs-replace)
(<o> ^__tagged*ngs*intelligent-construction *YES* +)
(<o> ^__tagged*ngs*op-create-primitive *YES* +)
(<o> ^side-effect <side-effect139> +)
(<side-effect139> ^action create ^destination-object <member> ^destination-attribute __tagged*counted
^value *YES* ^replacement-behavior ngs-replace ^type NGS_SideEffect ^my-type NGS_SideEffect)}

11. Goals Goals as defined by NGS 4.x are top-state structures
Goals must be declared using NGS_DeclareGoal (creates many required productions)
All goals are indexed multiple ways
Primary type
Base types
Requested decision name
Can be o-supported or i-supported (though I recommend i-supported goal stacks)
You can also create classic Soar substates, but these are called “states” not “goals”

12. Decision Goals You can setup persistent decisions using goals as well
Works a lot like a persistent state stack, but doesn’t block the reasoning process
Also re-decides when the options related to the decision change in any way
Easy to link up with an explanation system to explain the decision
Multiple parts to the process
A goal can request a decision (this is a request for a value to be set for a given attribute)
Other goals can be assigned to the decision
If more than one goal is assigned to the same decision, a substate is created
In the substate, one of the assigned goals is selected (like in an operator tie)
I tend to create task goal hierarchies out of i-supported decision goals – decide on sub-tasks and other supporting items like destination, formation, sensor direction, etc

13. Substates and “Functions”
NGS 4.x also supports sub-states
”Free” sub-states with no constraints or restrictions
“Function” sub-states
Provide for return values
Return is all-or-nothing
Multiple return values supported
Used to implement decision goals
sp "achieve-message-handled*propose*handle-mission-message*via-deep-copy
[ngs-match-goal <s> AchieveMessageHandled <g>]
[ngs-bind <s> robo-agent] [ngs-bind <g> message!MissionMessage.payload]
[ngs-is-not-tagged <g> message-copied]
-->
[ngs-create-function-operator <s> handle-mission-message <o> <ret-vals> \
<g> message-copied]
[ngs-create-ret-val-in-place payload <ret-vals> <robo-agent> my-mission]
[ngs-tag <o> $RS_DEEP_COPY_MESSAGE]"

14. Context Variables
Context variables can be used to simplify the process of turning raw data into “decision quality” data
Sampled Values
Periodic Sampled Value: Sample every n milliseconds
Stable Value (Change-based sampling): Sample on change > threshold
Timed Stable Value: Sample when value doesn’t change for n milli-seconds
Binned Values
Dynamically Binned Values: Bin value, expand the current bin
Statically Binned Values: Bin value based on fixed ranges
Decided Values
Selected Value: Value selected from multiple alternatives. E.g. the target speed of the vehicle (speed limit, traffic speed, weather speed)
Simple Inferred Value: Value inferred from a combination of other values
Other
Computed Value: value computed from one or more mathematical functions
Synced Value: adaptively sample and remap data from input link and automatically keep in sync with the original value

15. Example of Context Variables
NGS_DefineStableValue sample-pool categoryA slow-value-single-delta
sp "test*create-stable-value*single-delta
  [ngs-match-to-create-context-variable <s> sample-pool categoryA:<pool>]    
-->
  [ngs-create-stable-value <pool> slow-value-single-delta <s> rapid-value 1.0]"
NGS_DefineDynamicBinValue sample-pool categoryA my-speed
sp "test*create-dyn-bin-value*my-speed
[ngs-match-to-create-context-variable <s> sample-pool categoryA:<pool>]
-->
[ngs-create-dyn-bin-value <pool> my-speed <s> my-velocity <bins> \
{ <s> velocity-delta } $NGS_CTX_VAR_DELTA_TYPE_PERCENT]
[ngs-add-dyn-bin <bins> stopped 0.15 {} { } ]
[ngs-add-dyn-bin <bins> walking 1.0 stopped]
[ngs-add-dyn-bin <bins> jogging 2.0 walking]
[ngs-add-dyn-bin <bins> running 3.0 jogging { }]
[ngs-add-dyn-bin <bins> sprinting 4.0 running]
[ngs-add-dyn-bin <bins> speeding {} sprinting 0.5]"

16. Nuggets/Coal Nuggets Coal Is easier to read and write
Makes writing Soar code faster
Reduces bugs (especially low level bugs)
It’s efficient and creates expert-level code in many cases
LOTs of functionality (I’ve left out many things here including built-in support for explanation)
Coal
Not a complete language/abstraction
Have to debug in raw Soar (but it’s not as hard as you might think)
Type system is currently very weak
Doesn’t (yet) support semantic and episodic memory directly (likely will by the end of the year)

17. https://github.com/soartech/new-goal-system-4
Where to Get It
Available open source on GitHub
Includes a Developer Guide
All of the NGS 4 basics are covered
More advanced features like ”Decision Goals” and “Context Variables” are not covered yet
For debugging to work, you will need a recent nightly build of Soar (or maybe the newest release ?)
Use NGS 4.x with Soar IDE – you get code expansion and error checking