-
Notifications
You must be signed in to change notification settings - Fork 3
User guide
This guide contains specifications of all the primitives provided by the gs NetLogo extension.
Senders connect to external receivers and send them graph events generated by the agents. Only the observer can create or remove senders. Several senders can be created in the same simulation, for example one connected to a visualization application, another one connected to an analysis application and so on.
All senders share common sourceId which is automatically created when the extension is loaded. They also have a common timeline (a common timeId incremented at each event sent). In this way the whole NetLogo simulation is seen from outside as a unique source.
When a sender is created, agents can use it to send GraphStream events to external receivers. The observer can only send graph events. The turtles can only send node events. The nodeId of events sent by a turtle is a string containing its "who number". For example, the nodeId of turtle 42 is "42". The links can only send edge events. The edgeId of events sent by a link is a string containing the who numbers of its ends separated by underscore. For example the edgeId of link 12 34 is "12_34".
- senderId a string, the unique identifier of the sender
- host a string, the name of the host to connect to
- port a number, the port of the host
Can be called by: observer
Creates a sender. Note that an external receiver must be connected on the other side before calling this command, otherwise a connection refused error occurs. If a sender with this identifier already exists, an error occurs.
Can be called by: observer
Disconnects and removes all the senders (if any) created with gs:add-sender.
Examples
to setup-senders
;; clear all existing senders
gs:clear-senders
;; create a sender connected locally on port 2012
gs:add-sender "local" "localhost" 2012
;; create a remote sender
gs:add-sender "remote" "yoda.galacticrepublic.gov" 4242
end
- senderId a string, the unique identifier of the sender
Can be called by: turtle, link
Uses the specified sender to send a 'node added' event when called by a turtle or an 'edge added' event when called by a link. If there is no sender with this identifier, an error occurs.
Examples
;; creates 10 turtles and sends 'node added' events
crt 10 [
gs:add "snd"
]
;; creates a link between two turtles and sends 'edge added' event
ask one-of turtles [
create-link-with one-of other turtles [
gs:add "snd"
]
]
- senderId a string, the unique identifier of the sender
Can be called by: turtle, link
Uses the specified sender to send a 'node removed' event when called by a turtle or an 'edge removed' event when called by a link. If there is no sender with this identifier, an error occurs.
Example
;; Hungry turtles die and send 'node removed' event
ask patches with [food < 10] [
ask turtles-here [
gs:remove "snd"
die
]
]
;; Remove links between distant turtles and send 'edge removed' events
ask links with [link-length > 10] [
gs:remove "snd"
die
]
- senderId a string, the unique identifier of the sender
- attribute a string, the name of the attribute
- value a number, a boolean, a string or a list, the value of the attribute. If the value is a list, the list must not be empty, the type of its elements can be number or boolean, and all elements must have the same type.
Can be called by: observer, turtle, link
Uses the specified sender to send a 'graph attribute added' event when called by the observer, 'node attribute added' event when called by a turtle or 'edge attribute added' event when called by a link. When the value is a list, it is sent as an array (the element homogeneity requirement comes from here). If there is no sender with this identifier, an error occurs.
Examples
;; sends "ui.antialias" graph attribute
gs:add-attribute "snd" "ui.antialias" true
;; create turtles, register them and their coordinates
crt 100 [
gs:add "snd"
setxy random-xcor random-ycor
gs:add-attribute "snd" "xy" list xcor ycor
]
;; send the lengths of the links
ask links [
gs:add-attribute "snd" "length" link-length
]
- senderId a string, the unique identifier of the sender
- attribute a string, the name of the attribute
Can be called by: observer, turtle, link
Uses the specified sender to send a 'graph attribute removed' event when called by the observer, 'node attribute removed' event when called by a turtle or 'edge attribute removed' event when called by a link. If there is no sender with this identifier, an error occurs.
Examples
;; turtles that have enough to eat are not hungry
ask turtles with [[food] of patch-here > 10] [
gs:remove-attribute "snd" "hungry"
]
- senderId a string, the unique identifier of the sender
Can be called by: observer
Uses the specified sender to send 'graph cleared' event. If there is no sender with this identifier, an error occurs.
Examples
ca
gs:clear "snd"
- senderId a string, the unique identifier of the sender
- step a number, the step number
Can be called by: observer
Uses the specified sender to send a 'step begins' event. If there is no sender with this identifier, an error occurs.
Examples
tick
gs:step "snd" ticks
Receivers receive events sent by external applications, store them and dispatch them to the agents on demand. Only the observer can create or remove receivers. For obvious reasons external applications cannot create or kill turtles or links. That is why the only GraphStream events that agents can receive are attribute events. An exception is the 'step begins' event explained below.
Unlike senders, receivers are active entities and consume resources. Technically, each receiver runs in a separate thread. They must be used with caution by both NetLogo simulations and external applications. For example, if an external application frequently sends values of a node attribute called "foo" and the turtles never consume them, all these values will be stored and eventually a heap overflow will occur.
The (sourceId, timeId) of the incoming events are shared by all the receivers. It means that if for example receiver1 receives an event coming from the source "foo" with timeId 4 and after that receiver2 receives an event coming from the same source with timeId 2, the second event will be ignored. The sourceId of the NetLogo simulation is also taken into account, so the events generated by NetLogo senders that come back to NetLogo will also be ignored.
- receiverId a string, the unique identifier of the receiver
- host a string, the name of the host to connect to
- port a number, the port of the host
- attribute ... strings, optional arguments. If present, the receiver will store only values for these attributes and ignore all other attributes.
Can be called by: observer
Creates a receiver. Note that a receiver must be created before external senders can connect to it. If a receiver with this identifier already exists, an error occurs.
Can be called by: observer
Disconnects and removes all the receivers (if any) created with gs:add-receiver.
Examples
to setup-receivers
gs:clear-receivers
;; this one receives all attribute values
gs:add-receiver "rcv" "localhost" 4321
;; this one ignores all attributes except "foo" and "bar"
(gs:add-receiver "rcv-filtered" "localhost" 4322 "foo" "bar")
end
- receiverId a string, the unique identifier of the receiver
- attribute a string, the name of the attribute to be received
Can be called by: observer, turtle, link
This reporter returns a list of values of the specified attribute received as 'attribute added' or 'attribute changed' events by the specified receiver since the previous call to it (or since the creation of the receiver if this is the first call).
If called by the observer, it reports graph attribute values. If called by a turtle, it reports node attribute values (the nodeId convention is the same as for the senders). If called by a link it reports edge attribute values (the edgeId convention is the same as for the senders).
The reporter is non-blocking and returns the values received so far. If no values are received, an empty list is returned. If there is no receiver with this identifier, an error occurs.
Example
;; turtle size controlled by external application
to resize-turtles
ask turtles [
let sizes gs:get-attribute "rcv" "size"
if not empty? sizes [
;; only the last value received (if any) is taken into account
set size last sizes
]
]
end
- receiverId a string, the unique identifier of the receiver
Can be called by: observer
This reporter returns the value of the step in the first 'step begins' event received by the specified receiver and not yet reported. Warning: this reporter is blocking! If external applications never send 'step begins' event, this call will never return. If there is no receiver with this identifier, an error occurs.
This reporter, together with the gs:step command can be used to synchronize a NetLogo simulation with external application.
Example
to go
;; agents perform actions and send events to some external app
...
ask turtles [
gs:add-attribute "snd" "xy" list xcor ycor
]
...
;; now inform the external app that we are done
gs:step "snd" ticks
;; when the external app receives this 'step begins' event,
;; it computes the sizes of the turtles and sends them back
;; followed by 'step begins' event with the same number of step
;; to be sure to receive the sizes, we block on the 'step begins' event
while [gs:wait-step "rcv" < ticks] []
;; now the sizes are received and turtles can consume them
resize-turtles
;; tick to prepare the next step
tick
end
- receiverId a string, the unique identifier of the receiver
Can be called by: observer
Flushes the specified receiver. The received values of all the graph, node and edge attributes that are not consumed by gs:get-attribute are deleted and definitely lost. All the received steps are also deleted. If there is no receiver with this identifier, an error occurs.
Example
to setup
...
;; clear the values left from previous simulations
gs:flush "rcv"
reset-ticks
end