Activities - Ejenta Brahms

Primitive

A primitive activity is the lowest level of activity an agent or object works on for a specified amount of time. A primitive activity has no side-effects.

Syntax

primitive-activity	::=	primitive activity activity-name ( { param-decl [ . param-decl ]* } ) { { display : ID.literal-string ; { priority : [ ID.unsigned \| param-name ] ; { random : [ ID.truth-value \| param-name ] ; { min_duration : [ ID.unsigned \| param-name ] ; { max_duration : [ ID.unsigned \| param-name ] ; { resources } }
activity-name	::=	ID.name
param-decl	::=	param-type param-name
param-type	::=	ATT.type-def
param-name	::=	ID.name
resources	::=	resources : [ param-name \| OBJ.object-name ] [ , [ param-name \| OBJ.object-name ]*;
activity-ref	::=	activity-name ( { param-expr [ , param-expr ]* } ) ;
param-expr	::=	GRP.group-name \| AGT.agent-name \| CLS.class-name \| OBJ.object-name \| COC.conceptual-class-name \| COB.conceptual-object-name \| ARE.area-name \| VAR.variable-name \| ID.number \| ID.literal-symbol \| ID.literal-string \| ID.truth-value

Semantics

Declaration and reference

All activities have to be declared in the activities section of either a group, agent, class, object, or composite-activity. The declared activities can then be referenced in the workframes defined for the group, agent, class or object.

Parameters

It is possible to define input parameters for primitive activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Activities can be assigned a priority. The priorities of activities in a workframe are used to define the priority of a workframe. The workframe will get the priority of the activity with the highest priority defined in the workframe.

Duration

Activities in general have a duration. The duration of the activity can be defined to be a fixed amount of time when the random attribute is set to false and the max-duration attribute has to be set to the maximum duration in seconds. The duration of the activity can also be defined to be a random amount of time when the random attribute is set to true, the min-duration attribute has to be set to the minimum duration of the activity in seconds and the max-duration attribute has to be set to the maximum duration of the activity in seconds.

Resources

Artifacts (objects) can be defined as being a resource or not by setting the resource attribute to either true or false. In general artifacts that are worked on by agents are not considered to be a resource in an activity (a form, a fax). Artifacts that are used by an agent in an activity are considered to be resources ( a fax machine, a telephone).

It is possible to associate artifacts with activities for statistical purposes and for the purpose of generating object flows by defining them in the list of resources for an activity. Artifacts which are defined as resources are also called resource objects. Resource objects associated with activities will only collect statistics and will not be used for the object flow generation. Artifacts which are defined not to be a resource and which are associated with an activity are also called touch objects. Touch objects should be associated with one or more conceptual object(s) for object flow purposes and statistical purposes.

Example

primitive_activity study() {
    max_duration: 3000;
  }

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type < class-name >, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.

Move

A move activity is a primitive activity but is used to move an agent from its current location to the location as specified in the activity. The move activity first checks whether the duration is specified for the move activity. If the specified duration is larger than 0 it will use that duration for the move. If no duration is specified or the specified duration is 0 then the simulation engine tries to determine its duration by calculating the time it takes to move from the current location to the goal location using the shortest path specified between the two location. If no paths are specified between the locations then the duration of the move activity will be 0.

When the move activity is started the agent or object being moved will be location-less. All of the facts and beliefs about the location of the agent will be retracted as well as the location facts and beliefs of the agents or objects contained by the agent or object. By default all agents in the same location as the start location of the move will detect that the agent/object is leaving and will retract the beliefs about the location of those agents and objects. It is possible to specify explicitly in which areas agents will detect the moving agent leaving the location by specifying a list of areas in the detectDepartureIn property for the move activity. If the detectDepartureInSubAreas is false then only agents in the specified areas will detect the departure, not the agents in the sub areas of the specified areas.

When the activity is interrupted or impassed the agent or object will still remain location-less. It is possible that while the activity is interrupted the agent or object was moved to another location. If the agent or object moves while the activity was interrupted the duration of the interrupted activity will be recalculated as if the move never happened. If the agent or object did not move while interrupted then the activity will resume, the duration will not be recalculated, the activity will be active for the remaining duration.

On arrival in the goal location a fact and belief will be asserted for the traveling agent or object about its new location. For all contained agents/objects a fact is asserted about their new location, the contained agents will also get a belief about their new location. By default the agents in the goal location will detect the traveling agent as well as any contained agents. The traveling agent and contained agent(s) will detect all the agents and objects in the goal location. For any of the contained objects the traveling agent will get a belief of the object. The model builder can control who detects the arrival by specifying a list of areas in the detectArrivalIn property for the activity. Only the agents located in the specified list of areas and their sub-areas will detect the arrival of the agent and its contained agents. If the detectArrivalInSubAreas property is set to false then the agents located in the sub areas of the specified areas will not detect the arrival of the agent and its contained agents.

Syntax

move-activity	::=	move PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } { location : [ ARE.area-name \| PAC.param-name ] ; } { detectDepartureIn : [ ARE.area-name \| PAC.param-name ] [ , [ ARE.area-name \| PAC.param-name ]]; } { detectDepartureInSubAreas : [ ID.truth-value \| PAC.param-name ] ; } { detectArrivalIn : [ ARE.area-name \| PAC.param-name ] [ , [ ARE.area-name \| PAC.param-name ]]; } { detectArrivalInSubAreas : [ ID.truth-value \| PAC.param-name ] ; } }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for move activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity. It is recommended to make the first parameter the goal-location of the move activity.

Priority

Duration

Activities in general have a duration. In case of the move activity it is not necessary to define a duration of the activity. The duration of the activity is calculated by the simulation engine using the path definitions defining the distance between two locations. The simulation will determine the shortest path of travel from the current location to the goal location and calculate the travel time based on the distance. The duration of the move activity will in that case be the same as the calculated travel time. It is possible however to still define the duration of the activity. If the simulation engine cannot find a travel path then the defined duration will be used. The duration of the activity can be defined to be a fixed amount of time. The random attribute has to be set to false and the max-duration attribute has to be set to the maximum duration in seconds. The duration of the activity can also be defined to be a random amount of time. To define a random amount of time the random attribute has to be set to true, the min-duration attribute has to be set to the minimum duration of the activity in seconds and the max-duration attribute has to be set to the maximum duration of the activity in seconds.

DetectDepartureIn

The detectDepartureIn-property of the move activity specifies the areas for which the agents located in those areas will detect the moving agent leaving its current location. Those agents will retract the belief about the location of the moving agent if they have a belief about the location of the moving agent.

DetectDepartureInSubAreas

The detectDepartureInSubAreas property has as a value either true or false and specifies whether the departure of the agent is noticed by only the agents in the areas specified by the detectDepartureIn property or also the sub areas of the specified areas. If the value is true then not only will the agents located in the specified areas detect the agent's departure, also the agents in the sub areas of the specified areas will detect the departure. If the value is false the agents in the sub areas of the specified areas will not detect the departure. The default is true.

DetectArrivalIn

The detectArrivalIn-property of the move activity specifies the areas for which the agents located in those areas will detect the moving agent arriving in its destination location. Those agents will assert the belief about the new location of the moving agent.

DetectArrivalInSubAreas

The detectArrivalInSubAreas property has as a value of either true or false and specifies whether the arrival of the agent is noticed by only the agents in the areas specified by the detectArrivalIn property or also the agents in the sub areas of the specified areas. If the value is true then not only will the agents located in the specified areas detect the agent's arrival, also the agents in the sub areas of the specified areas will detect the arrival. If the value is false the agents in the sub areas of the specified areas will not detect the arrival. The default is true.

Example

move moveToLocation(Building loc) {
    location: loc;
  }

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
detectDepartureIn = < the start location of the moving agent >
detectDepartureInSubAreas = true
detectArrivalIn = < the destination location of the moving agent >
detectArrivalInSubAreas = true

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type < class-name > or list-of < class-name >, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The location parameter must be of type < areadef-name >.
The parameter types for the 'detectDepartureIn' and 'detectArrivalIn' areas must be of type < area-def-name >, the values for the parameters assigned to the 'detectDepartureIn' and 'detectArrivalIn' property must be VAR.variable-name, PAR.parameter-name or ARE.area-name.
The detectDepartureInSubAreas and detectArrivalInSubAreas parameters must be of type boolean and its input values must be one of true or false.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.

Create Agent

A create agent activity is a primitive activity allowing dynamic creation of one or more new agents. By default the activity creates only one agent. The user can also specify a quantity defining how many agents have to be created in the activity, this is useful if more than one agent has to be created in the activity without having to repeat the activity. When creating agent(s) the agents can be made a member of one or more groups. The groups have to be specified in the memberof property of the activity. The created agents will inherit all the behavior specified for the groups.

The user can specify when the actual creation has to take place by setting the 'when' value to either start or end. The created agent(s) are bound to the unbound variable specified in the destination property of the activity. If no destination variable is specified the binding does not take place.

After the agent is created the virtual machine will determine whether it needs to place the agent in a specific location. The activity checks the location property. If a location is specified the instance will be placed in that location. If no location is specified the agent remains location-less. When the agent is placed in the location a fact will be created about the location of the new agent and all agents in that location will detect the new agent's location (they will get a belief about the location of the new instance) and the newly created agent will detect all agents and objects in that location.

The newly created agent(s) will be initialized, initial beliefs will be asserted to the belief set of the agent and initial facts about the new agent will be asserted to the fact set of the world. The agent's work will be initialized.

The last thing the activity does is bind the unbound variable specified in the destination property with the new agent(s). If more than one agent is created the variable must be a collect-all variable. If the variable is for-one or for-each only the first agent will be bound to the variable.

Syntax

create-agent-activity	::=	create agent PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } { memberof : [ GRP.group-name \| PAC.param-name ] [ , [ GRP.group-name \| PAC.param-name ]* ]; { quantity : [ ID.unsigned \| PAC.param-name ] ; } { destination : [ PAC.param-name ] ; } { destination_name : [ ID.literal-symbol \| PAC.param-name ] ; } { location : [ ARE.area-name \| PAC.param-name ] ; } { when : [ start \| end \| PAC.param-name ] ; } }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for create-agent activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

Activities in general have a duration. The duration of the activity can be defined to be a fixed amount of time. The random attribute has to be set to false and the max-duration attribute has to be set to the maximum duration in seconds. The duration of the activity can also be defined to be a random amount of time. To define a random amount of time the random attribute has to be set to true, the min-duration attribute has to be set to the minimum duration of the activity in seconds and the max-duration attribute has to be set to the maximum duration of the activity in seconds.

When

The when attribute defines when the actual action has to take place, at the 'start' of the activity or at the 'end' of the activity.

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
memberof = brahms.base.BaseGroup
quantity = 1
destination = none
destination_name = "NoNameAgent"
location = none
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type < class-name > or list-of < class-name >, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The memberof parameter type has to be of meta-type Group and its input value must be one of VAR.variable-name or GRP.group-name.
The quantity parameter has to be of integer type and its input value must be one of VAR.variable-name or an integer value. The quantity must be 1 or more.
The destination parameter type has to be of type GRP.group-name and its input value must be an unbound variable (VAR.variable-name).
The location parameter type has to be of type ADF.areadef and its input value must be one of VAR.variable-name or ARE.area-name.
The when parameter must be of type symbol and its input values must be one of start or end.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.

Create Area

A create area activity is a primitive activity allowing dynamic creation of a new area. When creating a new area the area is by default made an instance of the area definition BaseAreaDef, the user can specify his/her own area definition as well. The area definition has to be specified in the 'instanceof' property. The area will inherit all the behavior specified for the area definition. The new area can be turned into a sub area for another area by assigning the parent area for the new area to the 'partof' property.

The new area can be inhabited by an initial set of agents or objects by specifying the agents and objects that are to be the inhabitants of the new area using the 'inhabitants' property.

The user can specify when the actual creation has to take place by setting the 'when' value to either start or end. The created area is bound to the unbound variable specified in the destination property of the activity. If no destination variable is specified the binding does not take place.

The newly created area will next be initialized, initial facts about the new area will be asserted to the fact set of the world.

The last thing the activity does is bind the unbound variable specified in the destination property with the new area.

Syntax

create-area-activity	::=	create_area PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } { instanceof : [ ADF.areadef-name \| PAC.param-name ] [ , [ ADF.areadef-name \| PAC.param-name ]* ]; { partof : [ ARE.area-name \| PAC.param-name ] ; } { inhabitants : [ AGT.agent-name \| OBJ.object-name \| PAC.param-name ] [, AGT.agent-name \| OBJ.object-name \| PAC.param-name ]* ]; } { destination : [ PAC.param-name ] ; } { destination_name : [ ID.literal-symbol \| PAC.param-name ] ; } { when : [ start \| end \| PAC.param-name ] ; } }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for create-area activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

Instance Of

The instanceof property specifies the area definition the new area is to be an instance of. It's the new area's parent 'class'.

Part Of

The partof property specifies the area the new area is to be made a part of. This makes the new area a sub area of the specified 'part of' area.

Inhabitants

The inhabitants property specifies the agents and objects that are to be located in the new area. If any of the inhabitants is located somewhere else then they will be relocated to the new area without any time consumption.

When

The when attribute defines when the actual action has to take place, at the 'start' of the activity or at the 'end' of the activity.

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
instanceof = brahms.base.BaseAreaDef
partof = none
inhabitants = none
destination = none
destination_name = "NewArea"
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type < class-name > or list-of < class-name >, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The instancepof parameter type has to be of meta-type AreaDef and its input value must be one of VAR.variable-name or ADF.areadef-name.
The partof parameter has to be of type ADF.areadef-name and its input value must be one of VAR.variable-name or ARE.area-name.
The inhabitant parameter has to be of type GRP.group-name or CLS.class-name and its input value must be one of VAR.variable-name, AGT.agent-name or OBJ.object-name.
The destination parameter type has to be of type ADF.areadef-name and its input value must be an unbound variable (VAR.variable-name).
The when parameter must be of type symbol and its input values must be one of start or end.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.

Create Object

A create object activity is a primitive activity allowing dynamic creation of new (conceptual) objects or copies of objects. The user can specify when the actual creation/copy has to take place by setting the 'when' value to either start or end. In either case, new or copy, a new (conceptual) instance is created and assigned to the unbound variable specified in the destination property of the activity.

The (conceptual) class from which an instance is created is determined differently between the new and copy action. The behavior of the two will therefore be discussed separately.

In case of a new action the activity will determine the class of the new instance from the source property. If the source specifies a class or conceptual class the activity will create an instance of that class. If the source specifies a (conceptual) object it will create an instance of the class of that (conceptual) object.

In case if a copy action the activity will determine the class of the new instance from the destination property. The source will determine the (conceptual) class from the unbound variable. The activity then creates an instance of that class.

After the instance is created and if the instance is an object and not a conceptual object the activity will determine whether it needs to place the object in a specific location. The activity first checks the location property. If a location is specified the instance will be placed in that location. If the location property does not specify a location the activity will check the source property. If the source property is an object it will check if that object has a location. If so the object will be placed in the same location as the source object. When the instance is placed in the location a fact will be created about the location of the new instance and all agents in that location will detect the new instance's location (they will get a belief about the location of the new instance).

The newly created instance will be initialized, initial beliefs will be asserted to the belief set of the object and initial facts about the new instance will be asserted to the fact set of the world. If the instance is an object with behavior its work will be initialized.

The activity will next determine whether the new (conceptual) instance needs to be made a part of conceptual objects. The activity first checks whether the conceptual-object property specifies any conceptual objects. If so it will make the new instance a part of those conceptual object(s). If no value is specified for the conceptual-object property the activity will check with the source. If the source property specifies an object or conceptual object, it will make the new instance a part of the same conceptual objects the source object is a part of. The appropriate aggregate relations will be generated as facts and beliefs.

If the new instance is created as a copy the activity will copy all beliefs of the source object to the new instance. This is only performed if both the source and new instance are objects, not when they are conceptual instances.

The last thing the activity does is bind the unbound variable specified in the destination property with the new instance.

Syntax

create-object-activity	::=	create_object PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } action : [ new \| copy \| PAC.param-name ] ; source : [ CLS.class-name \| OBJ.object-name \| COC.conceptual-class-name \| COB.conceptual-object-name \| PAC.param-name ] ; destination : [ PAC.param-name ] ; { destination_name : [ ID.literal-symbol \| PAC.param-name ] ; } { location : [ ARE.area-name \| PAC.param-name ] ; } { conceptual-object : [ COB.conceptual-object-name \| PAC.param-name ] [ , [ COB.conceptual-object-name \| PAC.param-name ] ]; } { when : [ start* \| end \| PAC.param-name ] ; }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for create-object activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity. It is recommended to make the first three parameters in a create-object activity:

action
source object
destination object

Priority

Duration

When

The when attribute defines when the actual action has to take place, at the 'start' of the activity or at the 'end' of the activity.

Example

create_object createInvoice(Invoice atm_invoice, Building bd) {
    max_duration: 4;
    action:new;
    source:Invoice;
    destination: atm_invoice;
    location: bd;
    when: start;
  }

Defaults

display = <activity-name>
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
destination_name = "no-name"
location = <location of source object>
conceptual_object = <conceptual-object of source object>
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type < class-name > or list-of < class-name >, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The action parameter must be of type symbol and its input values must be one of new or copy.
The source parameter type has to be of type CLS.class-name or COC.conceptual-class-name and its input value must be one of VAR.variable-name, CLS.object-class-name, OBJ.object-name, COC.conceptual-class-name, or COB.conceptual-object-name.
The destination parameter type has to be of type CLS.class-name or COC.conceptual-class-name and its input value must be an unbound variable (VAR.variable-name).
The location parameter type has to be of type ADF.areadef and its input value must be one of VAR.variable-name or ARE.area-name.
The conceptual-object parameter type has to be of type COC.conceptual-class-name or list-of COC.conceptual-class-name and its input value(s) must be one of VAR.variable-name, COB.conceptual-object-name or a list of any one of these elements.
The when parameter must be of type symbol and its input values must be one of start or end.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.
If the source of the create-object action is a class-name only the new action is allowed.
The destination name defines the unique name given to the created object. If the name exists the engine will automatically add a number at the end of the name to make it a unique name.

Communicate

The communicate activity is a primitive activity but allows for the communication of beliefs between the initiating agent or object and another agent or object. With the introduction of the communications library the communication can be more formalized by specifying a message object being an instance of the CommunicativeAct class for the transfer content. The communication activity in that case communicates the beliefs of the CommunicativeAct's belief set. The user can specify when the actual transfer has to take place by setting the 'when' value to either start or end.

Syntax

communicate-activity	::=	communicate PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } type : [ phone \| fax \| email \| face2face \| terminal \| pager \| none \| PAC.param-name ] ; with : [ [ AGT.agent-name \| OBJ.object-name \| PAC.param-name ][, [ AGT.agent-name \| OBJ.object-name \| PAC.param-name ] ]* ; about : TDF.transfer-definition [, TDF.transfer-definition ]; [ , [ COB.conceptual-object-name \| PAC.param-name ] ]; } { when : [ start \| end \| PAC.param-name ] ;} }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for communicate activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity. It is recommended to make the first parameter(s) in a communicate activity the concepts with which is communicated.

Priority

Duration

Type

The type attribute defines what type of communication is used. The type can be one of phone, fax, email, face2face, pager, or none (meaning not specified).

About

The about attribute specifies what beliefs are to be communicated. The transfer definition specifies either the beliefs that are to be transferred or a CommunicativeAct defining the message to be transferred. If the transfer definition is a CommunicativeAct and the transfer action is 'send' then any destination agent or object can be specified. However if the transfer definition is a CommunicativeAct and the transfer action is 'receive' then the value of the 'with' attribute must be the CommunicativeAct declared in the transfer definition to indicate that the agent or object wishes to read the contents of the CommunicativeAct. An agent is not permitted to directly receive a CommunicativeAct from another agent. The agent in such a case is required to request the agent for the message and the receiving agent can then choose to send the requesting agent the desired CommunicativeAct.

When

The when attribute defines when the actual communication has to take place, at the 'start' of the activity or at the 'end' of the activity.

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
type = none
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.

The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.

The parameters assigned to any of the attributes must be of the correct type.

The parameter types for resources must be of type <class-name> or list-of <class-name>, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.

The type-parameter type has to be a literal-symbol and its values must be one of phone, fax, e-mail, face2face, pager, or none.

The with-parameter type has to be one of 'Agent' , CLS.object-class-name, list-of Agent or list-of CLS.object-class-name and its input value must be one of AGT.agent-name, OBJ.object-name, VAR.variable-name or a list of any of these elements. The with-parameter must be of type CommunicativeAct if the about-parameter specifies a transfer definition of type 'receive(<CommunicativeAct>)' and must be the exact same CommunicativeAct value as specified in the transfer definition.

The when parameter must be of type symbol and its input values must be one of start or end.

The minimum duration of the activity defines the minimum duration in seconds.

The maximum duration of the activity defines the maximum duration in seconds.

Broadcast

The broadcast activity is a primitive activity but allows for the initiator to broadcast information into a location. By default every agent in the same location as the initiator will receive the broadcasted beliefs. The model builder can also specify to what areas the beliefs are to be broadcast thereby indicating whether sub areas should be included or not. If the model builder specifies a list of areas then the broadcast will communicate the given beliefs to all agents located in those specified areas. The model builder can specify when the actual transfer has to take place by setting the when value to either start or end of the activity. The user can in this case not specify with whom or what should be communicated.

Syntax

broadcast-activity	::=	broadcast PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } type : [ phone \| fax \| email \| face2face \| terminal \| pager \| none \| PAC.param-name ] ; to : [ [ ARE.area-name \| PAC.param-name ][, [ ARE.area-name \| PAC.param-name ] ]* ; { toSubAreas : [ ID.truth-value \| PAC.param-name ] ; } about : TDF.transfer-definition [, TDF.transfer-definition ]; { when : [ start* \| end \| PAC.param-name ] ;} }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for broadcast activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

The to-property of the broadcast activity specifies the areas in which a broadcast can be heard. This means that all agents located in the specified areas will receive the broadcast beliefs.

ToSubAreas

The toSubAreas property has as a value either true or false and specifies whether a broadcast is also heard in the sub areas of the areas specified in the to-property. If the value is true then not only will the broadcast go to all agents located in the specified areas, it will also go to all the sub areas of the areas specified in the to-property. The default is true.

When

The when attribute defines when the actual broadcast has to take place, at the 'start' of the activity or at the 'end' of the activity.

Example

broadcast announceTime() {
    random: false;
    max_duration: 1;
    about: 
      send(current.time = current.time);
    when: end;   
  }

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
to = <performing agent location>
toSubAreas = true
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type < class-name > or list-of < class-name >, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The parameter types for the 'to' areas must be of type <area-def-name>, the values for the parameters assigned to the 'to' property must be either VAR.variable-name, PAR.parameter-name or ARE.area-name.
The toSubAreas parameter must be of type boolean and its input values must be one of true or false.
The when parameter must be of type symbol and its input values must be one of start or end.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.

Get

A get activity is a primitive activity that allows an agent or object to pick up or transfer one or more objects and/or agents, referred to as items, from an area, agent or object, to carry it with it while performing activities. The picked up agents and/or objects are said to be contained by the agent or object that picked up the agents/objects. An agent or object can put the picked up agents/objects down or transfer them to another agent or object by using the put activity (PUT).

When the agents and/or objects are picked up the get activity will generate the appropriate containment beliefs and facts. For each picked up agent/object the activity will generate a fact in the world and a belief for the agent/object performing the activity of the form:

<agent|object> contains <item>

If the item(s) are being transferred from another agent or object then the containment relation for that item for the agent or object the item is transferred from will be negated.

<agent|object> contains <item> is false

Whenever the agent or object moves to another location it will take the contained items with it to that new location. The contained items will no longer have a location, i.e. no location facts will be generated for contained items until they are put down in a location. If the moving agent/object knows of the location of the contained item before the move it will also know of the location of the contained item after the move, i.e. a location belief will be generated for the carried item for the carrying agent/object.

Note that the virtual machine will generate warnings if an agent tries to get an item that is contained by another concept then the one specified as the source. The items for which a warning is generated are ignored.

Syntax

get-activity	::=	get PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } items source : [ OBJ.object-name \| AGT.agent-name \| ARE.area-name \| PAC.param-name ] ;} { when : [ start \| end \| PAC.param-name ] ;} }
items	::=	items : [ PAC.activity-name \| OBJ.object-name \| AGT.agent-name ] [ , [ PAC.activity-name \| OBJ.object-name \| AGT.agent-name ]* ] ;

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for get activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

Items

The items are the agents or objects that need to be picked up or transferred and are to be contained by the agent or object performing the get activity.

Source

The source specifies where the item(s) are being picked up or transferred from. The source can be either an area, another agent or another object. If no source is specified, then the agent's or object's current location is assumed.

When

The when attribute defines when the actual pick-up has to take place, at the 'start' of the activity or at the 'end' of the activity.

Example

get getAtmCardFromAtm(BankCard card, Atm atm) {
    random: true;
    min_duration: 1;
    max_duration: 5;
    items: card;
    source: atm;
  }

Defaults

display = < activity-name >
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
source =<agent's of object's current location>
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type <class-name> or list-of <class-name>, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.
The when parameter must be of type symbol and its input values must be one of start or end.
The parameter types for items must be of type < group-name > or list-of <group-name> or <object-class-name> or list-of <object-class-name>, the parameters assigned to the items must be either VAR.variable-name or AGT.agent-name or OBJ.object-name or a list of any of these three.
The parameter type for the source must be of type < areadef-name >, <class-name> or <group-name>. The value assigned to the parameter must be one of VAR.variable-name, AGT.agent-name, OBJ.object-name, or ARE.area-name.

Put

A put activity is a primitive activity that allows an agent or object to put down (drop) or transfer one or more objects and/or agents, referred to as items, carried by the agent or object performing the activity. The items are either dropped in the current or specified location or transferred to another agent or object. The carrying agent/object will no longer carry the item while performing future activities. An agent or object must have picked up, retrieved or received the items earlier by using the get activity (GET) or put activity (in case of transfer to the agent). If the agent or object is not carrying an item being put down by the carrying agent/object, then the put activity will do nothing except take time if a duration is specified.

When the agents and/or objects are dropped or transferred, the put activity will generate the appropriate negation of the containment beliefs and facts. For each dropped agent/object the activity will generate a fact in the world and a belief for the agent/object performing the activity of the form:

<agent|object> contains <item> is false

If the items are being transferred to another agent or object then for those items a new containment relation is generated both in the form of facts and beliefs:

<agent|object> contains <item>

Whenever the agent or object moves to another location it will no longer take the dropped items with it to that new location. For each item dropped in a location the activity will generate a location fact and a location belief for the dropped item for each agent that is located in the same location. The location of the dropped item will be the same location as the carrying agent or object if no destination is specified and the specified location if a destination location is specified. If the carrying agent or object does not have a location when the item(s) are dropped then the dropped items will not get a location either and no location facts and beliefs are generated for the dropped items.

Note that the virtual machine will generate warnings if an agent tries to put an item down or transfer an item that is not contained by the agent/object performing the activity. The items for which a warning is generated are ignored. ### Syntax

Syntax

put-activity	::=	put PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } items destination : [ OBJ.object-name \| AGT.agent-name \| ARE.area-name \| PAC.param-name ] ;} { when : [ start \| end \| PAC.param-name ] ;} }
items	::=	items : [ PAC.activity-name \| OBJ.object-name \| AGT.agent-name ] [ , [ PAC.activity-name \| OBJ.object-name \| AGT.agent-name ]* ] ;

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for put activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

Items

The items are the agents or objects that need to be picked up or transferred and are to be contained by the agent or object performing the get activity.

Source

When

The when attribute defines when the actual pick-up has to take place, at the 'start' of the activity or at the 'end' of the activity.

Defaults

display = <activity-name>
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none
destination =<agent's or object's current location>
when = end

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type <class-name> or list-of <class-name>, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.
The when parameter must be of type symbol and its input values must be one of start or end.
The parameter types for items must be of type <group-name> or list-of <group-name> or <object-class-name> or list-of <object-class-name>, the parameters assigned to the items must be either VAR.variable-name or AGT.agent-name or OBJ.object-name or a list of any of these three.
The parameter type for the source must be of type <areadef-name>, <class-name> or <group-name>. The value assigned to the parameter must be one of VAR.variable-name, AGT.agent-name, OBJ.object-name, or ARE.area-name.

Gesture

A gesture activity is a primitive activity used for indicating gesture changes made by an agent or object. This activity is primarily to be used in combination with a virtual reality environment such as OWorld/Adobe Atmosphere. The gestures as indicated by the gesture activity are visualized in the virtual reality environment provided that environment supports the specified gestures.

Syntax

gesture-activity	::=	put PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } gesture : [ ID.literal-symbol \| PAC.param-name ] ;} }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for gesture activities. These input parameters can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

Gesture

The gesture specifies the gesture made by the agent or object performing the activity. This is just a symbolic value and does not affect an agent or object's behavior in a Brahms simulation or agent-system. The virtual reality environment that interfaces with the Brahms environment interprets the symbolic value and visualizes the gesture if that environment supports the gesture. It is up to the model builder to come to an agreement with the developers of the virtual environment on what gestures will be supported and how they should be named.

Defaults

display = <activity-name>
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type <class-name> or list-of <class-name>, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.
The parameter type for the gesture must be of type symbol.

Java

A java activity is a primitive activity but its actual behavior is specified in Java code. The java activity specifies the fully qualified name of the class that implements the IExternalActivity interface or extends the AbstractExternalActivity class. When the java activity is to be executed an instance of the class is created and the code for the activity executed. If the class extends the AbstractExternalActivity class then the java code will have access to the parameters passed to the activity, belief set of the agent or object and the fact set of the world and will be able to conclude new beliefs and facts.

Syntax

java-activity	::=	java PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { random : [ ID.truth-value \| PAC.param-name ] ; } { min_duration : [ ID.unsigned \| PAC.param-name ] ; } { max_duration : [ ID.unsigned \| PAC.param-name ] ; } { PAC.resources } class : [ ID.literal-string \| PAC.param-name ] ;} { when : [ start \| end PAC.param-name ] ; } }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for java activities. These input parameters can be used to make activities more generic. In the activity reference the values for the input parameters have to be passed. It is possible to pass unbound variables as parameters to the java activity that can then be bound to a value in the Java code called when the activity is executed. This is a good method to get results back from a Java activity.

Priority

Duration

Class

The Class specified the fully qualified name of the Java class that is to be instantiated by the virtual machine to perform the activity. The fully qualified name must be a string. The class can also be specified through a parameter.

When

The when attribute defines when the actual communication has to take place, at the 'start' of the activity or at the 'end' of the activity.

Example

println_d(string message, double p1, string out) {
    class: "brahms.base.system.PrintlnActivity";
  }

Defaults

display = <activity-name>
priority = 0
random = false
min_duration = 0
max_duration = 0
resources = none

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.
The parameter types for resources must be of type <class-name> or list-of <class-name>, the parameters assigned to the resources must be either VAR.variable-name or OBJ.object-name or a list of any of these two.
The minimum duration of the activity defines the minimum duration in seconds.
The maximum duration of the activity defines the maximum duration in seconds.
The when parameter must be of type symbol and its input values must be one of start or end.
The class parameter must be of type string. The value for the class must specify the fully qualified name of the Java class. The class must be in the Java classpath. The class must implement the interface gov.nasa.arc.brahms.vm.api.jac.IExternalActivity or extend the abstract class gov.nasa.arc.brahms.vm.api.jac.AbstractExternalActivity.

Composite

A composite activity is an activity that has workframes, thoughtframes, and activities declared within. Unlike primitive activities no duration is specified for this activity. The duration of this type of activity depends on the workframes that will be worked on as part of the activity. Composite activities allow us to build a hierarchy of workframes. Activites declared in a composite activity can only be referenced by workframes within its composite activity.

Syntax

composite-activity	::=	composite PAC.activity-name ( { PAC.param-decl [ , PAC.param-decl ]* } ) { { display : ID.literal-string ; } { priority : [ ID.unsigned \| PAC.param-name ] ; } { end_condition : [ detectable \| nowork ] ; } { WFR.detectable-decl } { GRP.activities } { GRP.workframes } { GRP.thoughtframes } }

Semantics

Declaration and reference

Parameters

It is possible to define input parameters for composite activities. These input parameters are in the first place used to pass on variables defined in a workframe for use in the workframes defined for the composite activity and second they can be used to make activities more generic. Values for the input parameters have to be passed by workframes that reference activity.

Priority

Duration

Composite activities themselves do not have a duration. Workframes within a composite activity have activities that have specific durations. Therefore, the total duration for performing a composite activity is the aggregated duration of the activities within the workframes.

End-condition

The end-condition of a composite activity defines how a composite activity can be ended. There are three possibilities:

Only end it on the basis of an end-activity detectable. The end-condition has to be set to 'detectable'. When a detectable having an action type of 'end-activity' is detected the composite activity will be ended.
End the activity when there's no more work to work on. The end-condition has to be set to 'no-work'. If none of the workframes as defined in the composite-activities can be worked on the activity will be ended.
End the activity when there's no more work to work on, or when an end-activity detectable is detected. The end-condition has to be set to 'no-work' and an end-activity detectable needs to be defined for the composite activity. This case combines the first two cases.

composite_activity activitiesInKitchen(long enterKitchenTime) {
        end_condition: detectable;
        detectables:
          detectable leaveKitchen {
            detect((current.location != Kitchen))
            then end_activity;
          }
        activities:
        worfkrames:
          workframe wf_InKitchen {
            variables:
              forone(string) who;
            when((current.name != unknown) and
            (who = current.name))
            do {
              println_sl("%1 is in Kitchen at %2", who, enterKitchenTime);
            }
        }
      }

Defaults

display = <activity-name>
priority = 0
end_condition = nowork

Constraints

The signature of an activity must be unique within the definition of a group, agent, class, object, or composite-activity. The signature consists of the name of the activity and the types of the argument list in the order the arguments are listed.
The input parameter type of a parameter defined in the declaration of an activity must be the same as the input value type or variable type in the reference of the activity.
The parameters assigned to any of the attributes must be of the correct type.

Beliefs and Facts Frames