HELP NEWKIT Aaron Sloman July 1999 LIB SIM_AGENT LIB POPRULEBASE (From Version 5.0) Major changes July 1999. Last updated 18 Aug 2000 Note: before looking at any of the HELP or LIB files referred to below, it is necessary to run the command uses newkit to ensure that you get the new versions of the library, not the old ones. There should be a file: $poplocal/local/lib/newkit.p linked to $poplocal/local/newkit/newkit.p The versions of Poprulebase and Sim_agent are held in $poplocal/local/newkit/prb/ $poplocal/local/newkit/sim/ These should be linked to $poplocal/local/prb and $poplocal/local/sim respectively. This file is $poplocal/local/newkit/sim/help/newkit and also browsable on the internet at http://www.cs.bham.ac.uk/research/poplog/newkit/sim/help/newkit CONTENTS -- Summary SIM_AGENT V5.0, Poprulebase V5.0 -- Terminology: ruleclusters -- -- For readers new to Sim_agent: what is a rulefamily? -- New "define :rulesystem" syntax -- Specifying activation intervals: "with_interval" -- Activation intervals -- Rulesystems transferred to databases -- -- What happens when sim_setup runs -- -- Rulesystem information in the database -- -- [RULE_SYSTEM ] -- -- [RULE_SYSTEM_STARTUP <4-element vector>] (optional) -- -- [RULE_SYSTEM_SECTION
] (optional) -- -- [RULE_CLUSTER ] -- Backward compatibility -- -- Change to cycle_limit specifications -- -- Additional contents of database -- -- Explicit operations on contents of sim_rulesystem slot -- -- Alterations to Poprulebase database facilities -- -- . In LIB POPRULEBASE -- -- . In LIB SIM_AGENT -- Further documentation -- Summary SIM_AGENT V5.0, Poprulebase V5.0 --------------------------- The Sim_agent toolkit had a major revision in June/July 1999 allowing the rulesets within an agent to be stored within its database instead of being held in a list in the sim_rulesystem slot. This required a minor revision to some parts of Poprulebase, especially facilities for printing databases (to prevent rulesystems and rulesets being printed every time). Some other utilities had to be modified to ignore the new additions to the database. Additional condition-types and action-types will be introduced later to aid manipulation of rulesystems and their components at run time. Independently of the change in implementation of rulesystems, there is another change: a new "interval" mechanism for specifying the frequency of activation of some or all of an agent's internal mechanisms, e.g. once every N time slices, or "daily" "weekly", etc. Initial tests show that after these changes there is little or no discernible effect on efficiency. Accessing individual rulesets at run time may take a little longer, but the extra time is a tiny fraction of the total time for running rulesets, and the mechanisms for running rulesets are unchanged. There are other minor consequential changes. This file summarises the changes, and will be updated from time to time as further mechanisms, based on the new implementation, are added. -- Terminology: ruleclusters ------------------------------------------ The word "rulecluster" is used below to refer to both rulesets and rulefamilies. -- -- For readers new to Sim_agent: what is a rulefamily? A rulesystem specifies the internal processing architecture of an agent or object. It may contain many rulesets and rulefamilies, which are "notionally" run concurrently. A rulefamily combines several rulesets, only one of which is current at any time. Rules in a ruleset in a rulefamily can have actions which switch control between different rulesets within that rulefamily, using the facilities described in HELP RULESYSTEMS: [SAVERULESET ] [RESTORERULESET ] [SWITCHRULESET ] [PUSHRULESET ] [POPRULESET] Those actions are defined in LIB RULEFAMILY To simplify repeatedly writing "ruleset or rulefamily" this document uses "rulecluster" as a term to cover both. Likewise HELP RULESYSTEMS has been updated to reflect this. The latest version is always accessible at ftp://ftp.cs.bham.ac.uk/pub/dist/poplog/newkit/prb/help/rulesystems -- New "define :rulesystem" syntax ------------------------------------ In Version 5 of sim_agent the syntax for defining rulesystems (composed of ruleclusters) has been extended to allow activation intervals to be specified. All the old syntax still works except that "cycle_limit" can be used only once, near the beginning of the ruleset specification, before the specification of included ruleclusters. Although the syntax is largely unchanged, how it works has changed. Previously the rulesystem specification was translated into a list of ruleclusters with additional information defining the execution environment. Each agent's rulesystem was stored in its sim_rulesystem slot. In the new system, the contents of the rulesystem are be transferred to the agent's internal database by the sim_setup procedure defined in LIB SIM_AGENT, which is invoked before the agent is first run, as explained below. Despite this change, most rulesystem definitions should appear to work exactly as before, with a few exceptions, described below. Example files which run unchanged in the new system are: TEACH ARMYSIM.P TEACH SIM_DEMO TEACH SIM_SHEEP.P TEACH SIM_FEELINGS The changes appear not to have affected execution speeds of these files but I have so far not done proper testing except on the first one. -- Specifying activation intervals: "with_interval" ------------------- The syntax for specifying activation intervals is explained in detail in HELP RULESYSTEMS/with_interval There are three ways to specify an activation interval. o Use the sim_interval slot value in the object or agent o Use with_interval at the top of a rulesystem definition must be an integer, decimal or word o Use with_interval for particular ruleclusters. can be a number or word optionally followed by a colon and additional number: e.g. in this format, where "..." represents the name of a rulecluster include ... with_interval 3 ;;; run every 3 cycles include ... with_interval 0.25 ;;; Run every cycle with probability 0.25 ;;; i.e. run randomly, on average once every 4 cycles include ... with_interval day ;;; run every day include ... with_interval 3 : 4 ;;; run every 3 cycles with limit 4 ;;; NB put a space in front of the colon, to prevent ;;; any chance of it being interpreted as a number radix include ... with_interval day : 4 ;;; run every day with limit 4 The integer after the colon specifies a cycle limit for the rulecluster. E.g. "with_interval 3 :4" means that the ruleset or rulefamily should run only once in every 3 cycles of the sim_agent scheduler, but when it runs it should be given 4 cycles of the rule-interpreter (unless a STOP action causes earlier termination). Instead of a word or number specifying the interval, it is possible to use a string for the interval, but then you will need to redefine sim_interval_test to interpret the string as explained below. If the interval is a decimal rather than an integer it is interpreted via a randomiser. I.e. the decimal represents the probability of running on any cycle. -- Activation intervals ----------------------------------------------- The idea of an activation interval was inspired by the SDML toolkit developed at Manchester Metropolitan University Moss, S. J., Gaylard, H., Wallis, S. and Edmonds, B. (1998). SDML: A Multi-Agent Language for Organizational Modelling. In Computational and Mathematical Organization Theory, 4, pages 43-69. (http://www.cpm.mmu.ac.uk/cpmrep16.html) This allows agents to run hourly, daily, weekly. etc. The new sim_agent activation intervals provide similar facilities. An activation interval can be specified for an agent class or instance, for a rulesystem, or for individual ruleclusters within a rulesystem. The interval determines how often the relevant mechanisms are run. The interval can be specified either as an integer N, or a decimal number D <= 1.0, or a word, such as "second", "day", "week" If it is an integer N then the agent, or the individual rulecluster, will be run only once in every N time-slices. If it is a decimal number D, D should be between 0.0 and 1.0. Then the probability of it running in any timeslice is D. (A random decision maker is used). If it is a word naming a time-interval, i.e. "second", "minute", "hour", "day", "week", then activation will occur only once every T time slices, where T will be computed on the basis the notional time in milliseconds allocated to each time-slice. The global variable sim_cycle_milliseconds can have a value which is false (the default) or an integer. To make each time-slice represent 5 seconds, do 5000 -> sim_cycle_milliseconds; To make each time-slice represent 1 day, do 24*60*60*1000 -> sim_cycle_milliseconds; I.e. 86400000 -> sim_cycle_milliseconds; Suppose the value of sim_cycle_milliseconds is K. Then if the activation interval specified for a mechanism is "day", then it will run once in every 24*60*60*1000/K cycles of the scheduler. The currently supported symbolic intervals are "second" "minute" "hour" "day" However these are recognised only if sim_cycle_milliseconds is not false. Otherwise a mishap results. Full details can be found in the code for sim_interval_test in LIB SIM_AGENT Redefine sim_interval_test if you need to. E.g. you could extend it to handle strings specifying some other kind of interval. Later it may be possible to add some "real-time" scheduling options, but how fine-grained this can be will depend on speed of available CPUs and the types of programs included. (And garbage collections are a potential problem.) -- Rulesystems transferred to databases ------------------------------- The most important change in V5.0 of the toolkit is that before agents are first run the method sim_setup transfers the agent's rulesystem into the database. -- -- What happens when sim_setup runs The rulesystem is analysed and the individual rulesets and ruleclusters transferred to the agent's database. The remaining "skeleton" rulesystem is stored in the database in the form of list which gives the names of all the ruleclusters used. Additional items taken from the header of the rulesystem definition, including items corresponding to the DLOCAL, LVARS, cycle_limit, use_section and with_interval specifications at the top of a rulesystem definition are stored in the database. -- -- Rulesystem information in the database After sim_setup(agent) has run, a skeleton rulesystem is constructed in the form of database items with the following structure, where the vector and name are optional. [RULE_SYSTEM ] [RULE_SYSTEM_STARTUP <4-element vector>] If prb_use sections is true before compilation of the libraries, then there may also be an entry of this form: [RULE_SYSTEM_SECTION
] An agent can alter the contents of its rulesystem by adding or removing items. E.g. the order in which the ruleclusters are to be run can be changed, or the activation interval can be changed. Getting sleepy or tired might be implemented by increasing the activation interval. A changed level of arousal might be implemented by increasing the cycle limits for some or all ruleclusters. {{XXX need to be able to have a "sleep until" option?}} -- -- [RULE_SYSTEM ] The main rulesystem specification in the database contains: The word "RULE_SYSTEM" (This may change to something less likely to clash with user keywords) An optional reference (created by consref) holding the name of the rulesystem (included by default if you use define_rulesystem). The rulesystem name (a word in a reference: see HELP CONSREF) Where the words are names of rulesets or rulefamilies, in the order in which they are to be run in each time slice, corresponding to the order of "include" statements in the rulesystem definition. (It is possible that the actual rulesets of rulefamilies may be in the original list, rather than their names. In that case appropriate new names for them are created using gensym.) NOTE: At present, although (as described in HELP RULESYSTEMS) a rulesystem declaration may include one of debug = true; debug = false; neither has any effect. In future it may be that the latter option will cause some optimisations which may reduce flexibility, e.g. making it impossible for a redefined ruleset to affect running agents because the rulesystem information uses hard links. -- -- [RULE_SYSTEM_STARTUP <4-element vector>] (optional) If present, the main control information for rulesystems is stored in a four element vector in the database, in this format: [RULE_SYSTEM_STARTUP { } ] Each of the four items may be false, if there was no specification in the rulesystem definition. If all four are false there is no database entry of this form. is false or holds the local environment information specified in [DLOCAL ....] If present this is a list starting with the word "DLOCAL" containing information about which aspects of the environment are to be stored when the rulesystem starts and restored on exit, along with any new initialisations of dynamically local variables. For efficiency, initialisation instructions are compiled when the rulesystem declaration is compiled. More precisely the list is of the form [DLOCAL ] The values of the variables in are saved, and the is run to do initialisations. is false or holds the information for extending popmatchvars specified in [LVARS ....] If not false takes the form of a two element vector { } where is the list of words to be added to popmatchvars, while the rulesystem is running, and is run to initialise (some of their) their values. This works a bit like sysDLVARS described in REF VMCODE NOTE: for efficiency the system does not reset values of global matcher variables on exit from sim_run_agent. It is possible that this could cause problems. This may be addressed later. is false or holds the information specified in cycle_limit = If present this is a vector {limit } is false or holds the information specified in with_interval = If present this is a vector {rulesystem_interval } will be an integer, decimal or word as explained above. In cases where all four items would be false because the rulesystem definition had none of the header items, the the 4-element vector is not created. -- -- [RULE_SYSTEM_SECTION
] (optional) If prb_use_sections is true and the rulesystem definition includes use_section =
then the database will contain an entry of the form [RULE_SYSTEM_SECTION
] where
is a section (see HELP SECTIONS). Then sim_run_agent will save the current section on entry, will make
the current section while it runs, and will restore the old section on exit. Since sections change how "valof" works, this needs to be used with care, but be an aid to modularity in large programs. (Individual ruleclusters may also use their own sections.) -- -- [RULE_CLUSTER ] There are also separate items in the database for each rulecluster. They are invoked by the scheduler running through the rulesystem list. Each rulecluster is represented in the database by a four element list with one of the following formats: [RULE_CLUSTER ] [RULE_CLUSTER ] Where is the word following "define :ruleset" or "define :rulefamily" is either the ruleset (a list) or a rulefamily, an instance of the recordclass prb_rulefamily defined in LIB RULEFAMILY and described near the end of HELP RULESYSTEMS is a two element vector, of one of these two forms {limit } {interval } Where can take one of the forms described above. The last item is false if there is no limit or interval information. The fact that the information about an agent's rulesystem is stored in its own database using entries of this form, means that rules can more easily have conditions and actions which check the current rulesystem, making it easier for an agent to observe or update its own architecture. New rule-condition and rule-action formats will be introduced to make it easier to manipulate ruleclusters, though the above mechanisms allow an experienced user of the Pop-11 pattern matcher to do everything needed, using pattern restriction procedures if necessary to dig into vectors. (See HELP MATCHES) {{XXX perhaps the vectors should be replaced by lists, to simplify pattern matching.}} sections XXXXX -- Backward compatibility --------------------------------------------- The changes have been made in such a way as to be almost completely backwards compatible, except for the points listed below. As far as speed is concerned, on a number of tests the differences in speed between the old and the new system have proved to be negligible. Extracting the rulesystem and ruleclusters from an object's database on each time-slice may take a little more time, than simply going through a list of ruleclusters. However this extra time is normally negligible, compared with the time required to run the agent's rulesets the increase (The deterioration could be more noticeable for agents whose rulesystems include very large numbers of ruleclusters. If necessary, mechanisms for dealing with this will be added later.) There are three sources of incompatibility which may require changes in some applications of the toolkit: -- -- Change to cycle_limit specifications A rulesystem declaration (using define :rulesystem ...) can now have only ONE occurrence of "cycle_limit" near the beginning, before the first "include" and before "with_interval". Previously a later occurrence of "cycle_limit" affected all subsequent ruleclusters. This unstructured facility has been removed. The same effect can be achieved using the with_limit qualifier for several individual ruleclusters specified using "include". See HELP RULESYSTEMS -- -- Additional contents of database After switching to the new toolkit, differences in behaviour may arise if there are rules or procedures which explicitly interrogate the property holding the agent's database, since there will now be new items stored there: the rulesystem specification and the ruleclusters. There may also be accidental keyword clashes if "RULE_SYSTEM" or "RULE_CLUSTER" has previously been used as the first item of database entries. -- -- Explicit operations on contents of sim_rulesystem slot After switching to the new toolkit, differences in behaviour may arise if there are rules or procedures which explicitly operate on the contents of the agent's sim_rulesystem slot. Previously that slot held a list of ruleclusters, specifying the order in which they are run. Now information about the rulesystem is transferred into the database when sim_setup(object) is run. During this process the initial contents of the sim_rulesystem slot are analysed, and information transferred to the agent's database. After that a string is assigned to the sim_rulesystem slot, indicating that the rulesystem has been processed. This will cause an error if any attempt is made to treat the contents as a list. -- -- Alterations to Poprulebase database facilities -- -- . In LIB POPRULEBASE prb_noprint_keys A new user assignable global variable holding a list of database keywords, default [] prb_print_table(dbtable, keys); Changed to to ignore keys in prb_noprint_keys -- -- . In LIB SIM_AGENT sim_noprint_keys A list of keys to be assigned to prb_noprint_keys while sim_scheduler is running. Default value is the list [RULE_SYSTEM RULE_CLUSTER RULE_SYSTEM_STARTUP] If prb_use_sections is made true before poprulebase and sim_agent are compiled, then the list is [RULE_SYSTEM RULE_CLUSTER RULE_SYSTEM_STARTUP RULE_SYSTEM_SECTION] sim_clear_database(dbtable); This procedure has been altered so that if dbtable includes any database items starting with any of these words "RULE_SYSTEM" "RULE_CLUSTER" "RULE_SYSTEM_STARTUP" "RULE_SYSTEM_SECTION" then those items are not cleared from the database. XXX to be completed -- Further documentation ---------------------------------------------- HELP RULESYSTEMS HELP POPRULEBASE HELP SIM_AGENT .... --- $poplocal/local/newkit/sim/help/newkit --- Copyright University of Birmingham 2002. All rights reserved. ------