The dtkeden manual - distributed communication features for tkeden

(Note: this document was originally titled "The Not-So-Quick Guide to dtkeden".)

This document describes the special features of dtkeden, a distributed version of tkeden. The dtkeden variant of tkeden was designed and developed by Pi-Hwa Sun in connection with his doctoral thesis, and has since been maintained in conjunction with tkeden by Ashley Ward. This guide is a revision by Meurig Beynon, Russell Boyatt and Ashley Ward (December 2003) of a document first produced by Sun and Richard Cartwright (October 1998). It complements existing literature on tkeden and should be read in conjunction with the documentation on EDEN, DoNaLD, SCOUT and the MSc lecture notes M2, M5, T1 and Th1.

Abstract

The dtkeden tool is designed to be used in a client/server configuration over a TCP/IP network (which could be a LAN or in principle a WAN if firewalls do not cause a problem). In its current version, there can be many clients associated with one server. Each client supports interaction by a modeller acting in the role of an agent within a concurrent system (an internal agent) in respect of activities such as configuring the agent's environment, or making observations and actions. The server then supports the interaction of a modeller acting in the role of an external observer who can construe the interactions amongst agents in the concurrent system in several different ways. To this end, the tool allows the modeller at the server to configure the interaction in one of four different modes, and (in some circumstances) to mediate the interaction amongst clients by acting as a superagent. There is also support for virtual agency, whereby a definition can be associated with a particular agent who may or may not be located at a dtkeden client.

This document includes information about running the tool, the four modes for agent interaction and the mechanisms for sending messages between servers and clients. It also describes the built-in support for the LSD notation and the mechanisms for controlling virtual agency available in the tool.

Conceptual Uses for dtkeden
Using dtkeden
Automating communication in dtkeden
1. Automation on the server
2. Automation on the client
The LSD Notation in dtkeden for Normal Mode
Virtual Agency
Matters Arising
Known Bugs

1. Conceptual Introduction

The dtkeden tool is an extension of the tkeden tool with the addition of support for distributed modelling. Built on network communication over TCP/IP sockets (using the facilities in the Tcl interpreter in tkeden), dtkeden is based on a client/server configuration and provides a multi-agent, experiential modelling environment. Within this environment, each modeller has their own personal modelling environment similar to that supplied by tkeden, together with network communication to a server. Each dtkeden client is identified by a login name, and communication from this client to the server is attributed to a virtual agent with the appropriate login name.

The qualities of dtkeden as a modelling environment can only be realised by following good practice in model construction. In interpreting interaction in the dtkeden environment, it is vital to conceive the representation of states and transitions within tkeden in an idealised form, viz. as based on the use of definitive scripts specified using Eden definitions and functions, together with actions that can be regarded as redefinitions within a script. This presumes that the modelling activity at each network node is in spirit close to that discussed in connection with the Abstract Definitive Machine (ADM) in lecture Th1, and that communication is essentially based upon transmitting definitions from one modeller to another. In practice, just as tkeden can be abused as a purely procedural programming language, so also can dtkeden be abused so that issues of concurrency and synchronisation become at least as complex and difficult to address as they are in traditional concurrent programming environments. In particular, communication between nodes can involve the transmission of any fragment of valid tkeden input, and may not be confined to a block of redefinitions. The discussion of different modelling modes below makes sense only with respect to disciplined use of dtkeden in which the principles of modelling with the ADM are respected as far as possible.

Conceptually, the modeller who uses the server's modelling environment as superagent is modelling/observing the interactions amongst the internal agents in the entire system from an external observer's viewpoint. The modeller who uses a client as a standard agent is modelling/observing part of the system from an internal agent's perspective. There are many ways in which the external observer and the internal agents can construe their interaction in the context of the situation to which the model refers. To accommodate this, the dtkeden client-server environment can be configured in four different modes. In typical use, it is to be expected that the mode is chosen to suit the modelling context at the outset, and is subsequently unchanged. The four possible modes of interaction are Normal, Broadcast, Interference and Private. The nature of the construal of multi-agent interaction to which each mode informally corresponds, and the principal mechanisms used to support this construal, are as follows:

Normal Mode (the default mode)

Normal mode is associated with 'normal' interaction in the everyday objective world. All the agents are deemed to have a common perception of what the shared observables are, but each may have a different perspective when interacting with them. For instance, all members of a family who live in the same house can be viewed as having 'the same' perception of the key features of the living room, such as the location of the door, the chairs and the lights, but only some of them are currently in a position to see whether or not the door is open or the lights are on (some family members might be out [where? out!]), and only some will be in a position to open the door or move a chair. The important characteristic of this construal of a situation is that all observables are deemed objective, in the sense that, subject to having access to their values, all agents will ascribe the same values to them. For instance (in a 'normal' construal of reality), whether we can see the door to the front room or not, we all believe it to be currently either locked or unlocked, and, were we all in a position to determine whether the door was or was not locked, we would all come to the same conclusion about its status. It is then appropriate to consider that each observable has an authentic value, even though - when the specific context of the modelling scenario is taken into account - we are not all able to see the same observables, and may have different privileges to change their values.

In Normal mode, observables can be classified using the LSD notation at the dtkeden server. For this purpose, the LSD concepts (oracle and handle) are invoked. An oracle refers to the privilege of an agent to observe the authentic value of an observable, and a handle refers to an agent's privilege to change the authentic value of a observable. A special automated agent, the LSD Agent, is located at the server in dtkeden. This agent is responsible for the management of access privileges for observables. When a request to access an observable (for observation or for change) comes from a client to the server, the LSD Agent will check the privilege of the sender for their access permission to that observable. At the same time, if a change to an observable is made, the LSD Agent will propagate this change to all other agents who are authorised to receive it.

In modelling in Normal mode in dtkeden, the authentic values of observables are recorded at the server. It is these values that are propagated to and affected by agents for whom the value is an oracle and/or handle respectively. In all manually invoked communication from a server, the modeller has discretion over the precise set of agents to whom redefinitions of observables are directed. Sending a value of an observable directly to another client resembles communicating your private notion of its current value; sending it to the server resembles a request to change its current authentic value. The LSD Agent at the server is responsible for determining how requests of this nature affect the authentic values of observables and their perception by other agents. For instance, a redefinition of x followed by a 'Send' (see section 2) at a client that has x as an handle will update the authentic value of x at the server, whilst a redefinition of the authentic value of x at the server will update the value of x at all clients for which x is an oracle. Note that the authentic value of x can be redefined in several ways additional to the basic propagated change that dependency implements: it may be the result of a client updating x as a handle and communicating this change, or of a redefinition of the observable x followed by a 'Send' or 'Accept' (see section 2) at the server. Note also that there is scope within Normal mode for each client agent to have a private notion of the current value of x, such as might result from redefinition of x by the client followed by an 'Accept' (see section 2). If x is an oracle for the client, this private value is subject to be overwritten by redefinition of the authentic value of x at the server. Private values for observables of this nature might correspond to values of observables 'as remembered'.

The mechanisms by which the modeller manually communicates redefinitions are complemented by communication procedures (sendServer() and sendClient()) that can be invoked automatically at a client node. Redefinitions sent directly to the server (by sendServer()) update the authentic value and are then propagated to all clients that have the appropriate oracles. Redefinitions sent from one client to another (by sendClient()) are conceptually different; they do not affect the authentic values of variables but represent the private communication of values perceived by one client to another client.
Broadcast Mode
Broadcast mode is a special case of the scenario for 'normal' concurrent interaction. In this mode, any communication from a client is automatically propagated to all other clients (contrast the way in which a client selects particular targets for their communication in Normal mode). Each client has access to those observables that are broadcast by other clients, together with those private observables that the client has defined. Broadcast mode supplies an open environment for multi-agent modelling such as is needed for a multi-user game. A typical application for such an environment might be modelling a card game such as whist, in which at any stage there is a pool of public cards, and each player sees these cards together with the cards in their private hand.
Interference Mode
Interference mode is associated with an understanding of agent interaction that does not assume a shared objective world but admits explicit reference to personal viewpoints and perceptions. This understanding of agent interaction can therefore be seen as both more primitive and more sophisticated than that associated with normal everyday interaction. In Normal mode, the external observer can be seen as maintaining the authentic values of objectively defined observables about which the internal agents have a shared understanding. While it is possible in Normal mode for clients to have private values (such as might represent the values of observables as last recorded by them), these values cannot be referenced by the server: from the perspective of the external observer, the symbol 'x' refers to the authentic value of the observable x as recorded at the server, and any private value associated with x at a client is inaccessible. In Interference mode, in contrast, the external observer can be seen as acknowledging the essentially private nature of the observation of each client and trying to bring coherence to all their independent observations. In this mode, the external observer plays the archetypal role of 'creator of the concurrent system', and has complete discretion over whether and how the individual perceptions of the internal agents can be integrated so as to shape a reality.

Virtual agency is the syntactic device by which private values of observables are associated with clients in the server environment. The observable a as viewed by client X is referred to as X_a. A redefinition of an observable that is communicated from a client to the server is presented to the superagent modeller (at the server) in the input window in a form which makes it convenient for the external observer to shape the concurrent interaction to suit their construal. For instance, the redefinition

a is b+c;

communicated from the client X will appear in the input window at the server as:

>>X a is b+c; >>

If this is processed without any intervention by the superagent modeller (using Accept or Send), it will be associated with the redefinition:

X_a is X_b + X_c;

so that in effect the server is recording/transmitting information about X's private perception of the relationship between the private observables a, b and c. The modeller can alternatively conveniently edit the input

>>X a is b+c; >>

to the form

>> a is b+c; >>

and thereby interpret the action of the agent X as redefining the public value of the observable a.

Since Interference mode allows the external observer to act as a superagent to directly interfere with the interactions between agents, or between each client and the server, it is best suited to applications in which negotiation of concepts or the values of observables is involved. These applications are characteristic of concurrent design activity, where there are many autonomous agents, each of whom has a different perspective on the system or product under development.
Private Mode
In the private mode, each client has their own private values of observables and a "private" communication channel to the server. The conventions for referring to a client's private perception of an observable are similar to those in Interference mode, and make use of virtual agency. In contrast to the Interference mode, a communication to the server takes direct effect on the observables as recorded by the server - the modeller acting as an external observer does not exercise discretion over its interpretation. Moreover, in contrast to Broadcast mode, no request will be propagated to the other clients. This mode is suited to activity in which the modelling has been modularised into independent components, or where other forms of independent interaction - such as the private interactions of a class of pupils, each of whom has the same model - are being monitored or drawn together.

1.5 Summary of interaction modes

The above characteristic of modes in dtkeden is summarised in the following table. The left column portrays a conceptual understanding of the kind of "world" that the mode describes, and the right column gives an operational interpretation. Again we would emphasise the importance of the conceptual understanding.

Summary of `dtkeden` interaction modes
Interaction mode	Conceptually	Technically
Normal	Observables have authentic values All observables are potentially visible to all agents: access privileges are specified using LSD Private communications between agents is possible Eg: living room in a family's understanding	Pressing Send on a client sends the redefinition to the server. The server will propagate redefinitions to all clients that have the LHS as an LSD oracle
Broadcast	Observables have authentic values All non-private observables are visible to all Private communications between agents is not possible Eg: card game	Pressing Send on a client sends the redefinition to the server The server propagates all redefinitions to all clients No virtual agent preprocessing
Interference	Observables don't necessarily have authentic values: determined by the superagent Observables not necessarily visible to all: determined by the superagent Private communications between agents is not possible Eg: concurrent design	Pressing Send on a client places the redefinition, encapsulated in virtual agent context, into the server input window for editing by the superagent
Private	Observables need not have authentic values Observables are visible only to the originally perceiving agents Private communications between agents is not possible, only between client and server. Eg: Private learning activities of pupils in a class.	Pressing Send on a client sends the redefinition, encapsulated in virtual agent context, to the server The server performs no propagation of change to other clients

1.6 Considerations governing modes and behaviours in `dtkeden`

In distinguishing the four modes of interaction in dtkeden, it is helpful to consider various issues that differentiate interaction as it is supported by the interpreter. Relevant questions include:

Can the external observer refer to the private observables of internal agents?
Does the server automatically accept the input sent from clients?
Does input from clients get transmitted automatically to other clients via the server?
What is the default convention for access privileges when observables are introduced?
Are communications from clients automatically accepted by the server?
When extra clients are introduced, what observables are in existence?
How are client instantiation and observable introduction synchronised?
Is there visualisation associated with observables?
Does communication from clients get registered as potential input at the server, rather than automatically accepted?

In broad terms, we can consider the role of the external observer in Normal mode as relatively passive, and as relating to singular conditions that are encountered in normal shared reality. The external observer may be called upon to frame unusual changes in the environment for interaction (e.g. such as might simulate some redecoration of a living room) or to arbitrate where there are singular interactions (e.g. as when two people are in conflict about opening / shutting the door), but this does not involve a true negotiation of reality. The role of the server is to mediate a shared reality, and this may involve synthesising both manual and automatic communication. Broadcast mode can be seen as a specialisation of interaction in Normal mode, where the possibility of agents not observing changes to certain aspects of shared state, or of making partial communications of state, is not admitted.

In contrast, Interference mode is concerned with more radical and active intervention on the part of the external observer in shaping what is deemed to be inter-subjective. It requires activity that is dominated by human intervention and the exercising of intelligence on the part of the modellers: the potential for automation is then more limited, and communication is predominantly hand-crafted. Private mode is a specialisation of communication within this framework, in which some of the external observer's discretion over what is communicated from agents is removed, but the privacy of these communications is preserved. In this mode, the external observer can play a powerful role in organising and interpreting the private interactions of client modellers, but is more limited in the extent to which they can interfere with them.

The choice of mode in which to conduct distributed modelling with dtkeden is determined by the nature of the external observer's construal. It is clear that this choice is pragmatic in character and that the justification for making one assumption about the nature of agent interaction rather than another is informal and empirically based. The constructs that support one mode of interaction are not necessarily available in another mode, and - if they available - may have a different significance. For example, the use of the LSD notation is confined to Normal Mode, whilst virtual agency is a concept that can be used in any mode even where it refers to agents other than those sited at clients. More technical discussion of the practical use of dtkeden follows.

2. Using dtkeden

The dtkeden tool is implemented only on Solaris and Linux presently: there is a bug which crashes the server on client connection in Windows. Examples of models that use dtkeden include VEL, clayon tunnel and the car parking simulator.

The following command is used to run a dtkeden server:

dtkeden -s -c n
example: mischief> dtkeden -s -c 55

The flag "-s" signifies that the tool is to run in server mode (superagent) and "-c n" signifies that the server should listen on communication channel "n". The particular n refers to the communication channel at the server, an integer between 0 and 99. The available flags can be listed using the "-u" (for "u"sage) flag. You can run a dtkeden server alone without any clients and get equivalent features to tkeden (and probably some extra bugs!).

The following command is used to run a dtkeden client:

dtkeden -a -c n -h hostname
example: cottage> dtkeden -a -c 55 -h mischief

The flag "-a" signifies that this is a client (agent) and "-h hostname" signifies that the client should connect to the server running on a computer system with name "hostname". Technically, this corresponds to use of a socket number n+9000. Note these socket numbers have not been reserved for this use by IANA so may conflict with other network applications (see the file /etc/services on a UNIX machine or http://www.iana.org/assignments/port-numbers). If you wish many clients can be run on the same physical machine (provided you can cope with the large number of resulting windows!) rather than using many different machines. Currently, each client is allowed to connect to one server only. When connected to the specified server, a window requesting a login name opens at the client.

2.1 Server Interaction Modes

When started as a server (with the "-s" flag), dtkeden displays an input window like the one shown below. This is a window into which EDEN, DoNaLD, SCOUT and Sasami definitions can be typed, together with the supported subset of the LSD Notation (see section 4) and the context switching associated with virtual agency (see section 5). Most menus are the same as those in standard tkeden. The additional menu items/buttons "Type" and "Send" are special to dtkeden and are described in more detail below.

When dtkeden is started, the superagent, acting in the role of an external observer, may need to specify a modelling mode of interaction for the whole system other than the default Normal Mode. In the current version, there are four modes serving different styles of modelling, as previously described. In conventional use of dtkeden, it is recommended that the modelling mode be established at the beginning of interaction and not subsequently modified during a modelling session. (It is technically possible to change the mode during a modelling session but there are conceptual and semantic problems with making the change.) To specify a modelling mode, you can click on the Type menu item and then select a choice from the submenu. Normal mode is the default.

Note: In this section of this document, the term request is used to refer to a valid message, which can be any segment of tkeden input. As explained above it is necessary to base dtkeden use in the ADM model in order to maintain conceptual integrity and this means alterations should consisting primarily of the form of dependency-based redefintions. (Although if you wish to retain conceptual control, we would recommend that your messages consist primarily of dependency-based redefinitions rather than procedural proc invocations etc).

2.2 Send and Accept

Pressing the "Send" button causes the request currently in the input window to be sent to other network nodes (according to the communication conventions that are operating in the current mode) and also performs the same function as the "Accept" button. Using "Accept" on its own does not cause any propagation to other nodes (unless the request involves invoking a sendClient() or sendServer() procedure to explicitly send definitions). In monitoring and interpreting agent interaction it is helpful to consult the command histories of the server and clients (the window produced from the menu View -> History).

2.3 LSD privileges in the symbol table

For the management of agents' privileges in "Normal Mode", the LSD Agent in dtkeden creates and maintains three lists - representing oracles, handles and states - for each observable. For example, if the list of oracle privileges for an observable mmm is [xxx, yyy], then both agents xxx and yyy (but not zzz) have the oracle privilege for the observable mmm. You can see these three lists by using the function symboldetail("mmm") (or symboldetail(&mmm), see also the symboltable() and symbols() functions in the Eden language reference for details of name, type, text, targets and sources), which returns the privilege details associated with observable mmm. The format of the EDEN list returned is:

[name (eg mmm),type,text,targets,sources,[oracle_agents],[handle_agents],[state_agents]]
For example:

a is b+c
writeln(symboldetail("a"));
["a","formula"," b+c;",[],["b","c"],[EVERYONE],[sun,carters],[EVERYONE]]

In the current implementation of dtkeden, only the first two of these three lists, which respectively refer to agents having the observables as an oracle and as a handle, have any practical significance.

For any observable, at any point in the interaction, its oracle_agents list and handle_agents list either:

is empty ([]) - no agent has the associated privilege;
contains only the special agent "EVERYONE" ([EVERYONE]) - meaning that every agent has the associated privilege, or
contains an explicit list of the names of the agents with the associated privilege, but not containing EVERYONE (e.g. [sun,carters]).

When creating a new variable, dtkeden refers to a system variable called "EveryOneAllowed" in order to give the default access privilege for each new definition of an observable. The two settings are:

EveryOneAllowed = TRUE; - all new variables are created with all privilege lists initially set to [EVERYONE]
EveryOneAllowed = FALSE; - all new variables are created with all privilege lists initially set to []

If you want a variable that is not an oracle to a particular client, ensure that EveryOneAllowed = FALSE; before you create the variable. Because of the EveryOneAllowed variable, absence of a variable from the LSD description does not imply lack of oracle and handle privileges. (Whether this is a sensible design or not is left as an exercise to the reader.)

Therefore, to use LSD, follow the ordering in the following example:

%eden
EveryOneAllowed = FALSE;
%lsd
... (your LSD here)
%eden
... (your model here)

The variable propagateType also has effect on client/server communication: check the EDEN FAQ for further information.

2.4 The `synchronize` variable

The superagent can determine the nature of synchronised communication between the server and the underlying EDEN, DoNaLD and SCOUT interpreters by setting the value of the system variable synchronize. When the synchronisation variable is set to true, dtkeden waits until the underlying processing initiated by sending a redefinition is finished before sending the next redefinition to other clients. When the synchronisation variable is set to false, redefinitions are transmitted to other clients without any waiting for local redefinition and therefore are not guaranteed to be processed correctly.

synchronize = 1; ----> synchronised (the default)
synchronize = 0; ----> not synchronised

This system variable value should be set with caution as it can give rise to infinite waiting.

2.5 Logging in as a client

When a user runs the client version of dtkeden, they are prompted for an agent name in a login window, like the one shown below. This determines the virtual agent name that will be associated with their input on all communications to the server.

Having entered an agent name (note that pressing return is equivalent to pressing the OK button), a dtkeden client input window is displayed, as shown directly below. This window contains the same menu items as tkeden with the addition of a "Send" item.

After entering an agent name, you are connected to the specified server. You can send a request (e.g. in the form of a definitive script) to the server by clicking "Send" menu item. This operation forces dtkeden to both accept scripts and send them to the server as well (see 2.2 above). The way in which a transmitted script is handled by the server depends on the interactive mode of the server as chosen by the superagent.

Note: a -w argument (for "who" -- the number of possible single-character arguments is now small!) was added in EDEN version 1.62 for specifying the dtkeden client login name, and can be used to avoid the manual entry shown above.

3. Automating communication in dtkeden

In this section, the mechanisms available to automate communication between the dtkeden server and clients are discussed.

3.1 Automation on the server

sendClient("clientname", "script");
example: sendClient("client1", "a is b+c;");

sendClient() allows a redefinition to be sent to a specified client. Here, a clientname refers to the name that was entered when the client agent initiated connection.

3.2 Automation on the client

There are more commands supporting network communication at the clients than at the server. Note that it is the Accept menu item rather than the Send menu item that is required in order to execute the following communication commands.

sendServer("serverName", "scripts");

example: sendServer("mischief", "x is y-z;");

Sends a redefinition to the server.

sendClient("clientName", "scripts");

example:sendClient("client1", "a is b+c;");

Sends a redefinition to another specific client.

queryObs("observableName");

example: queryObs("x");

Queries an observable's current authentic value.

renewObs("observableName");

example: renewObs("x");

Renews a definition or value to be the same as the authentic value on the server.

The commands queryObs() and renewObs() are useful in modelling in the Private Mode. This is because each agent is involved in individual modelling without interference from other client agents - an activity that is in some respects similar to personal private thinking that may diverge from an objective or consensus understanding. Using these commands, it is possible to retrieve the current 'centrally agreed' definition or value of a variable.

4. The LSD Notation in `dtkeden` for Normal Mode

There is support for the LSD Notation in the dtkeden server when it is operating in "Normal Mode". The LSD agent is configured by scripts written in the LSD notation. There are also some procedural commands available which perform the same function. Symbol table entries for variables store entries for oracle, handle and state, but in practice (as remarked above) only oracles and handles have any effect. Scripts in the LSD Notation start with "%lsd" and end with the name of another notation, such as "%eden". The syntax is as follows:

%lsd
agent agentName
oracle observableName[, observableName]
handle observableName[, observableName]
state observableName[, observableName]
remove LSDType observableName[, observableName]

The agent statement associates all the following statements with agent agentName. The oracle, handle and state observable lists contain observable names associated with the privileges to access the observables by agentName. The following example illustrates how to use the LSD notation.

%lsd             <----- declare the use of LSD notation
agent xxx       <----- declare the agent name
oracle a, b, c <----- add agent xxx the oracle agency for observables a, b, c.
handle a, m      <----- add agent xxx the handle agency on observables a, m.
remove oracle b <----- remove from agent xxx the oracle agency for observable b.

agent yyy        <----- declare a new agent name
oracle m, c      <----- add agent yyy the oracle agency for observables m, c.
handle b, m      <----- add agent yyy the handle agency for observables b, m.

%eden            <----- back to EDEN

You can choose the "View LSD Description" sub item in the pop down menu of the View item of the server's input window menu to check your LSD description. (Note however that there may be some bugs in the implementation of the window as the information it uses is procedurally constructed and modified rather than dependent upon symboltable() state).

The LSD agent can also be configured programmatically, using the following commands.

addAgency("agentName", "LSDType", "observableName");
example: addAgency("yyy", "oracle", "b");
removeAgency("agentName", "LSDType", "observableName");
example: removeAgency("yyy", "handle", "m");

checkAgency("agentName", "LSDType", "observableName");
example: checkAgency("xxx", "handle", "w");

In these syntax descriptions, LSDType is one of three basic three supported keywords in the LSD Notation: oracle, handle and state. The first two commands (addAgency() and removeAgency()) are procedures and the last (checkAgency) is a function returning a value of TRUE or FALSE. If TRUE (actually an integer of value 1) is returned by the command checkAgency, it means that the specified agent agentName has the identified privilege LSDType for the specified observable observableName. If the agent does not have this privilege, a FALSE value (0) is returned.

5. Virtual Agency

A modification of the tkeden machine in dtkeden allowed the addition of a virtual agent feature. The Eden machine can be set into a particular "context" which causes it to perform pre-processing and/or privilege checks on symbol names that it encounters. Two character command codes are used to set the current machine context. The return command code ">>" can always be used to set the machine context back to the default.

The command codes that may be used will now be described. Each code is identified by the first two symbols.

">>"
This symbol is followed by an agent name and switches the machine into a context where the agent name followed by an underscore character is prepended to all symbol names (except for names of system functions). This context will persist until the context is changed or it is reset to the root context using the return ">>" symbol. For example, the script

        >>sun
        x is y + z;
        >>

will be interpreted as follows:

        sun_x is sun_y + sun_z;
"><"
This symbol is used to indicate that the string that follows is the the name of a variable that contains an agent's name. The machine is switched into a context where the agent's name (not the variable name) followed by an underscore character is prepended to all symbol names (except for names of system functions). For example, the following code

        name = "button1";
        >< name
        a is b - c;
        >>

will be interpreted as:

        button1_a is button1_b - button1_c;
">~"
This symbol is used in Normal mode as a prefix to the name of a client agent. The machine then checks that the named agent has the appropriate LSD privileges to modify any variables that are redefined. The machine is effectively "role playing" the named agent. No pre-processing of symbol names is performed. For example, provided that agent sun has the observable x as a handle, the script

        >~ sun
        x is y + z;
        >>

will be interpreted as:

        x is y + z;

Notes

The ">~" code is for use in "Normal Mode" interaction. The remaining codes are used in the other modes of interaction.
There are two additional command codes "<>" and "<<", which perform the same functions as ">>" and "><" respectively, but the preprocessing appends rather than prepends the agent name to the symbol name. These command codes are therefore redundant and should not be used in new models. They are documented here so that older models may be understood.
There are five additional command codes ">$", "<$", ">>$", "<<$" and "$$". They appear to have the following functions (determined by Eric Chan): ">$" sets the context of the following scripts/definitions to a given client -- eg ">$client1" would cause the following script to be sent to client1 using sendClient(); "<$" is similar to ">$" but fetches the client name from the symbol table by lookup() like "><"; ">>$" does the same as ">$" plus ">>client1"; "<<$" does the same as "<$" plus "<<client1"; "$$" resets to the root global space. We recommend that these codes should not be used in new models -- they are documented here so that older models may be understood.
Additionally, the symbol "~" is used to prevent the preprocessor from appending an agent name. For example, the script
>>sun
x is y + ~z;
>>

will be interpreted as:

sun_x is sun_y + z;
In the current version of dtkeden, virtual agency is implemented in the EDEN, DoNaLD and SCOUT notations (not Sasami or EDDI).

6. Matters arising

The current implementation of dtkeden makes provision in the symbol table for an observable to be classified as an LSD state observable: completing this implementation would involve ensuring that observables were introduced into and deleted from the modelling environment as and when agents themselves entered and withdrew from the concurrent interaction. Implementing this feature would involve the use of the special Eden function forget() procedure to manage the symbol table appropriately. This would enable dtkeden to emulate more of the functionality of the ADM.
Virtual agency has an essential role in dtkeden as a way of distinguishing the different agent views of what is conceptually the same observable. In this application of virtual agents, nesting of agents is not appropriate. Virtual agency can (and has) also be used to create multiple instances of data, and has been incorporated into tkeden for application in this role (and the previous version of this document gave an example, which we no longer recommend). In this context, nesting of agents might be a welcome feature. But it has proved difficult to use it effectively and intelligibly (see e.g. the way that grids of Scout buttons are generated in projecttimetableKeen2000), and other methods of generating multiple instances of data are generally to be preferred.
There are at present no known good solutions to the problem of instantiating multiple copies of sets of definitions, partly because there is no good solution to the problem of specifying a set of definitions. Perhaps,the best solution developed so far is that originally implemented by Edward Yung and used in the DoNaLD implementation. In this technique, prototype definitions containing parameters marked with the ? character are preprocessed into full form by interpretation using the Eden execute() command macro function. See introtoempresentWard2002/utils.eden for a full example. The basic idea is:
```
prototype = "a is ?1 + c;
d is ?2;\n%donald
line l
l = [{200, 200}, {?3, ?3}]";

ref = "a";
pos = 300;

execute(macro(prototype, "b", ref, str(pos)));
/* a is b + c;
   d is a;
   %donald
   line l
   l = [{200, 200}, {300, 300}]
*/
```
Because Empirical Modelling is rooted in personal experience, and objectivity is derived through classifying experience, it might seem that distributed EM should be based on a peer-to-peer rather than a client-server architecture. A practical motivation for adopting such an architecture is that the load on the server in dtkeden can be heavy. It may well be that there is a place for a peer-to-peer tool to support distributed EM, but the client-server framework is itself quite well-suited to the concept of concurrency as created in the mind of the external observer, and the server has a key role in supporting the external observer's construal.

7. Known Bugs

In version 1.40 and probably many others, "Send" on the client appears not to imply "Accept", as the older dtkeden-sep31999 version implies it should.
Virtual agency works by prepending an agent name followed by an underscore character to a reference. The references are still made to the flat Eden namespace, and so can conflict with other users of that space. For example, DoNaLD defines a variable 'A_x' to store attributes for each DoNaLD entity 'x', so use of the virtual agent 'A' will cause interesting interactions with DoNaLD attributes.
When a new client joins a system with some pre-existing state it is not automatically updated with the current state.
It should be possible to log in using a command line argument, but this isn't implemented yet
The dtkeden server implementation when compiled for Windows crashes when a client logs in... but then when run with a debugger it works OK. Hmmm.
Recent versions of the tool (eg 1.46?) seem to fail to 'accept' the first definition 'sent' from the client.
As the code base is larger in dtkeden, expect more bugs in dtkeden than tkeden: if you have no use for the special features of dtkeden, we recommend that you use tkeden.

TODO list for this document

Figure out and properly document the EveryOneAllowed, synchronize, higherPriority and propagateType variables. (There is some brief information [which may or may not be correct!] about propagateType and EveryOneAllowed in the EDEN FAQ).
Problems and solutions for creating multiple instances of data are partially documented here and in the Eden FAQ - merge them.
Possibly <~ is omitted. Found some more documentation in /dcs/emp/sun/tkeden.sun/tkeden/readme.sun - merge this in.
There is some mention in the code (in EX/parser.c) of a >>$ virtual agent notation. It seems to be completely undocumented and some work would be needed to figure it out.

Changes to this document

24-Jun-2005: Added mention of the new -w argument. [Ashley]
13-Jun-2005: Added more explanation of the EveryOneAllowed variable as determined with Eric. Fixed EDEN FAQ links. [Ashley]
10-Jun-2005: Added information determined by Eric about control codes ">$", "<$", ">>$", "<<$" and "$$". [Ashley]
2-Jun-2005: Fixed spelling of synchronize keyword, which was previously incorrectly spelt synchronised. [Ashley]
21-Apr-2005: Document moved to new home in Warwick SiteBuilder. [Ashley]
1-Apr-2005: Added mention of >>$ notation in TODO list above. [Ashley]
14-Jan-2005: Fixed the first link to LSD documentation - modifying ref to LSD document to glossary. Ashley has pointed out that there are other places even in this file where this arises, and suggests that a forwarding page be added at old location. [Meurig?]
12-Jan-2005: Fixed typo in Abstract and Contents title HTML. [Ashley]
9-Feb-2004: Added TODO about readme.sun. [Ashley]
31-Jan-2004: Added note about apparent ">$", "<$", ">>$" and "><$" command modes. These "changes" and TODO sections introduced. [Ashley]
Early Jan-2004: Few URLs corrected, added note about larger code base in dtkeden. [Ashley]
December 2003: Major reworking of this document by Meurig Beynon, Russell Boyatt and Ashley Ward. Title changed from "A Quick Guide..." to "The Not So Quick Guide...".
October 1998: Original version of this document by Pi-Hwa (Patrick) Sun and Richard Cartwright.