Statements - gama-platform/gama GitHub Wiki
This file is automatically generated from java files. Do Not Edit It.
=, abort, action, add, agents, annealing, ask, aspect, assert, benchmark, betad, break, browse, camera, capture, catch, category, chart, conscious_contagion, continue, coping, create, data, datalist, default, diffuse, display, display_grid, do, do_rule, draw, else, emotional_contagion, enforcement, enter, equation, error, event, exit, experiment, exploration, focus, focus_on, genetic, global, graphics, grid, highlight, hill_climbing, if, image_layer, init, inspect, invoke, law, layout, let, light, loop, match, match_between, match_one, match_regex, mesh, migrate, monitor, morris, norm, output, overlay, parameter, perceive, permanent, plan, pso, put, reactive_tabu, reflex, release, remove, restore, return, rotation, rule, run, sanction, save, set, setup, sobol, socialize, solve, species, species_layer, start_simulation, state, status, stochanalyse, switch, tabu, task, test, text, trace, transition, try, unconscious_contagion, user_command, user_init, user_input, user_panel, using, Variable_container, Variable_number, Variable_regular, warn, write,
- Batch method
- Behavior
- Experiment
-
Layer
- agents, camera, chart, display_grid, event, graphics, image_layer, light, mesh, overlay, rotation, species_layer,
- Output
- Parameter
- Sequence of statements or action
-
Single statement
- =, add, assert, break, category, conscious_contagion, continue, data, datalist, diffuse, do, draw, emotional_contagion, enforcement, error, focus, focus_on, highlight, invoke, law, let, put, remove, restore, return, rule, save, set, socialize, solve, status, text, unconscious_contagion, user_input, warn, write,
- Species
- Variable (container)
- Variable (number)
- Variable (regular)
-
Behavior
- add, ask, assert, benchmark, capture, conscious_contagion, create, diffuse, do, emotional_contagion, enforcement, error, focus, focus_on, highlight, if, inspect, let, loop, migrate, put, release, remove, restore, return, run, save, set, socialize, solve, start_simulation, status, switch, trace, transition, try, unconscious_contagion, using, warn, write,
- Environment
- Experiment
- Layer
-
Model
- action, aspect, coping, do_rule, equation, experiment, law, norm, output, perceive, plan, reflex, rule, run, sanction, setup, species, start_simulation, state, task, test, user_command, user_init, user_panel, Variable_container, Variable_number, Variable_regular,
- Output
-
Sequence of statements or action
- add, ask, assert, assert, benchmark, break, capture, conscious_contagion, continue, create, data, datalist, diffuse, do, draw, emotional_contagion, enforcement, error, focus, focus_on, highlight, if, inspect, let, loop, migrate, put, release, remove, restore, return, save, set, socialize, solve, status, switch, trace, transition, try, unconscious_contagion, using, warn, write,
- Single statement
-
Species
- action, aspect, coping, do_rule, equation, law, norm, perceive, plan, reflex, rule, run, sanction, setup, species, start_simulation, state, task, test, user_command, user_init, user_panel, Variable_container, Variable_number, Variable_regular,
- action
-
aspect
- draw,
- chart
-
display
- agents, camera, chart, display_grid, event, graphics, image_layer, light, mesh, overlay, rotation, species_layer,
-
equation
- =,
- fsm
-
if
- else,
- output
- parallel_bdi
- permanent
-
probabilistic_tasks
- task,
- rules
- simple_bdi
-
sorted_tasks
- task,
- species_layer
- state
- switch
- test
- try
- user_command
- user_first
- user_init
- user_last
- user_only
- user_panel
-
weighted_tasks
- task,
A statement represents either a declaration or an imperative command. It consists in a keyword, followed by specific facets, some of them mandatory (in bold), some of them optional. One of the facet names can be omitted (the one denoted as omissible). It has to be the first one.
statement_keyword expression1 facet2: expression2 ... ;
or
statement_keyword facet1: expression1 facet2: expression2 ...;
If the statement encloses other statements, it is called a sequence statement, and its sub-statements (either sequence statements or single statements) are declared between curly brackets, as in:
statement_keyword1 expression1 facet2: expression2... { // a sequence statement
statement_keyword2 expression1 facet2: expression2...; // a single statement
statement_keyword3 expression1 facet2: expression2...;
}
-
right
(float), (omissible) : the right part of the equation (it is mandatory that it can be evaluated as a float -
left
(any type): the left part of the equation (it should be a variable or a call to the diff() or diff2() operators)
Allows to implement an equation in the form function(n, t) = expression. The left function is only here as a placeholder for enabling a simpler syntax and grabbing the variable as its left member.
- The syntax of the = statement is a bit different from the other statements. It has to be used as follows (in an equation):
float t;
float S;
float I;
equation SI {
diff(S,t) = (- 0.3 * S * I / 100);
diff(I,t) = (0.3 * S * I / 100);
}
- The
=
statement is of type: Single statement - The
=
statement can be embedded into: equation, - The
=
statement embeds statements:
-
name
(an identifier), (omissible) : identifier of the action -
index
(a datatype identifier): if the action returns a map, the type of its keys -
of
(a datatype identifier): if the action returns a container, the type of its elements -
type
(a datatype identifier): the action returned type -
virtual
(boolean): whether the action is virtual (defined without a set of instructions) (false by default)
Allows to define in a species, model or experiment a new action that can be called elsewhere.
- The simplest syntax to define an action that does not take any parameter and does not return anything is:
action simple_action {
// [set of statements]
}
- If the action needs some parameters, they can be specified betwee, braquets after the identifier of the action:
action action_parameters(int i, string s){
// [set of statements using i and s]
}
- If the action returns any value, the returned type should be used instead of the "action" keyword. A return statement inside the body of the action statement is mandatory.
int action_return_val(int i, string s){
// [set of statements using i and s]
return i + i;
}
- If virtual: is true, then the action is abstract, which means that the action is defined without body. A species containing at least one abstract action is abstract. Agents of this species cannot be created. The common use of an abstract action is to define an action that can be used by all its sub-species, which should redefine all abstract actions and implements its body.
species parent_species {
int virtual_action(int i, string s);
}
species children parent: parent_species {
int virtual_action(int i, string s) {
return i + i;
}
}
- See also: do,
- The
action
statement is of type: Sequence of statements or action - The
action
statement can be embedded into: Species, Experiment, Model, - The
action
statement embeds statements: assert, return,
-
to
(any type in [container, species, agent, geometry]): the left member of the addition assignment ('cont << expr;') is an expression cont that evaluates to a container (list, map, matrix, graph) -
item
(any type), (omissible) : the right member of the addition assignment ('cont << expr;') is an expression expr that evaluates to the element(s) to be added to the container -
all
(any type): the symbol '<<+' allows to pass a container as item so as to add all its elements to the receiving container -
at
(any type): the index at which to add the item can be specified using 'container[index]' and the symbol '+<-' must prefix the item (instead of '<<', which would be ambiguous if the container contains other containers)'
A statement used to add items to containers. It can be written using the classic syntax (add ... to: ...
) or a compact one, which is now preferred.
- To add an element to a container (other than a matrix), use
container << element;
orcontainer <+ element;
(classic form:add element to: container;
) - To add all the elements contained in another container, use
container <<+ elements;
(classic form:add all: elements to: container;
) - To add an element to a container at a certain index, use
container[index] +<- element;
(classic form:add element at: index to: container;
)
- The new element can be added either at the end of the container or at a particular position.
expr_container << expr; // Add expr at the end
expr_container[index] +<- expr; // Add expr at position index
- For lists, the index can only be integers
list<int> workingList <- [];
workingList[0] +<- 0; // workingList equals [0]
workingList[0] +<- 10; // workingList equals [10,0]
workingList[2] +<- 20; // workingList equals [10,0,20]
workingList <+ 50; // or workingList << 50; // workingList equals [10,0,20,50]
workingList <<+ [60,70]; // Add all the values in the list // workingList equals [10,0,20,50,60,70]
- Case of a map: As a map is basically a list of pairs key::value, we can also use the add statement on it. It is important to note that the behavior of the statement is slightly different, in particular in the use of the at facet, which denotes the key of the pair.
map<string,string> workingMap <- [];
workingMap['x'] +<- 'val1'; //equivalent to workingMap['x'] <- 'val1' // workingMap equals ["x"::"val1"]
- If no index is provided, a pair (expr_item::expr_item) will be added to the map. An important exception is the case where the expr_item is a pair itself: in this case, the pair is added.
workingMap << 'val2'; // workingMap equals ["x"::"val1", "val2"::"val2"]
workingMap << "5"::"val4"; // workingMap equals ["x"::"val1", "val2"::"val2", "5"::"val4"]
- Notice that, as the key should be unique, the addition of an item at an existing position (i.e. existing key) will only modify the value associated with the given key.
workingMap['x'] +<- "val3"; // workingMap equals ["x"::"val3", "val2"::"val2", "5"::"val4"]
- On a map, the all facet will add all the values of a container in the map: if the argument is a map itself, all its pairs will be added, otherwise a set of pairs <cont_value, cont_value> will be added
workingMap <<+ ["val4","val5"]; // workingMap equals ["x"::"val3", "val2"::"val2", "5"::"val4","val4"::"val4","val5"::"val5"]
- In case of a graph, it is advised to use the various edge(), node(), edges(), nodes() operators, which can build the correct objects to add to the graph
graph g <- as_edge_graph([{1,5}::{12,45}]);
g << edge({1,5}::{2,3});
list var <- g.vertices; // var equals [{1,5},{12,45},{2,3}]
list var <- g.edges; // var equals [polyline({1.0,5.0}::{12.0,45.0}),polyline({1.0,5.0}::{2.0,3.0})]
g << node({5,5});
list var <- g.vertices; // var equals [{1.0,5.0},{12.0,45.0},{2.0,3.0},{5.0,5.0}]
list var <- g.edges; // var equals [polyline({1.0,5.0}::{12.0,45.0}),polyline({1.0,5.0}::{2.0,3.0})]
- The
add
statement is of type: Single statement - The
add
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, - The
add
statement embeds statements:
-
value
(container): the set of agents to display -
name
(a label), (omissible) : Human readable title of the layer -
aspect
(an identifier): the name of the aspect that should be used to display the species -
fading
(boolean): Used in conjunction with 'trace:', allows to apply a fading effect to the previous traces. Default is false -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. In case of negative value OpenGl will position the layer out of the environment. -
refresh
(boolean): (openGL only) specify whether the display of the species is refreshed. (true by default, useful in case of agents that do not move) -
rotate
(float): Defines the angle of rotation of this layer, in degrees, around the z-axis. -
selectable
(boolean): Indicates whether the agents present on this layer are selectable by the user. Default is true -
size
(point): extent of the layer in the screen from its position. Coordinates in [0,1[ are treated as percentages of the total surface, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Like in 'position', an elevation can be provided with the z coordinate, allowing to scale the layer in the 3 directions -
trace
(any type in [boolean, int]): Allows to aggregate the visualization of agents at each timestep on the display. Default is false. If set to an int value, only the last n-th steps will be visualized. If set to true, no limit of timesteps is applied. -
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
visible
(boolean): Defines whether this layer is visible or not
agents
allows the modeler to display only the agents that fulfill a given condition.
- The general syntax is:
display my_display {
agents layer_name value: expression [additional options];
}
- For instance, in a segregation model,
agents
will only display unhappy agents:
display Segregation {
agents agentDisappear value: people as list where (each.is_happy = false) aspect: with_group_color;
}
- See also: display, chart, event, graphics, display_grid, image_layer, overlay, species_layer,
- The
agents
statement is of type: Layer - The
agents
statement can be embedded into: display, - The
agents
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
aggregation
(a label), takes values in: {min, max}: the agregation method -
init_solution
(map): init solution: key: name of the variable, value: value of the variable -
maximize
(float): the value the algorithm tries to maximize -
minimize
(float): the value the algorithm tries to minimize -
nb_iter_cst_temp
(int): number of iterations per level of temperature -
temp_decrease
(float): temperature decrease coefficient. At each iteration, the current temperature is multiplied by this coefficient. -
temp_end
(float): final temperature -
temp_init
(float): initial temperature
This algorithm is an implementation of the Simulated Annealing algorithm. See the wikipedia article and [batch161 the batch dedicated page].
- As other batch methods, the basic syntax of the annealing statement uses
method annealing
instead of the expectedannealing name: id
:
method annealing [facet: value];
- For example:
method annealing temp_init: 100 temp_end: 1 temp_decrease: 0.5 nb_iter_cst_temp: 5 maximize: food_gathered;
- The
annealing
statement is of type: Batch method - The
annealing
statement can be embedded into: Experiment, - The
annealing
statement embeds statements:
-
target
(any type in [container, agent]), (omissible) : an expression that evaluates to an agent or a list of agents -
as
(species): an expression that evaluates to a species -
parallel
(any type in [boolean, int]): (experimental) setting this facet to 'true' will allow 'ask' to use concurrency when traversing the targets; setting it to an integer will set the threshold under which they will be run sequentially (the default is initially 20, but can be fixed in the preferences). This facet is false by default.
Allows an agent, the sender agent (that can be the [Sections161#global world agent]), to ask another (or other) agent(s) to perform a set of statements. If the value of the target facet is nil or empty, the statement is ignored.
- Ask a set of receiver agents, stored in a container, to perform a block of statements. The block is evaluated in the context of the agents' species
ask ${receiver_agents} {
${cursor}
}
- Ask one agent to perform a block of statements. The block is evaluated in the context of the agent's species
ask ${one_agent} {
${cursor}
}
- If the species of the receiver agent(s) cannot be determined, it is possible to force it using the
as
facet. An error is thrown if an agent is not a direct or undirect instance of this species
ask ${receiver_agent(s)} as: ${a_species_expression} {
${cursor}
}
- To ask a set of agents to do something only if they belong to a given species, the
of_species
operator can be used. If none of the agents belong to the species, nothing happens
ask ${receiver_agents} of_species ${species_name} {
${cursor}
}
- Any statement can be declared in the block statements. All the statements will be evaluated in the context of the receiver agent(s), as if they were defined in their species, which means that an expression like
self
will represent the receiver agent and not the sender. If the sender needs to refer to itself, some of its own attributes (or temporary variables) within the block statements, it has to use the keywordmyself
.
species animal {
float energy <- rnd (1000) min: 0.0;
reflex when: energy > 500 { // executed when the energy is above the given threshold
list<animal> others <- (animal at_distance 5); // find all the neighboring animals in a radius of 5 meters
float shared_energy <- (energy - 500) / length (others); // compute the amount of energy to share with each of them
ask others { // no need to cast, since others has already been filtered to only include animals
if (energy < 500) { // refers to the energy of each animal in others
energy <- energy + myself.shared_energy; // increases the energy of each animal
myself.energy <- myself.energy - myself.shared_energy; // decreases the energy of the sender
}
}
}
}
- If the species of the receiver agent cannot be determined, it is possible to force it by casting the agent. Nothing happens if the agent cannot be casted to this species
- The
ask
statement is of type: Sequence of statements or action - The
ask
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, Output, - The
ask
statement embeds statements:
-
name
(an identifier), (omissible) : identifier of the aspect (it can be used in a display to identify which aspect should be used for the given species). Two special names can also be used: 'default' will allow this aspect to be used as a replacement for the default aspect defined in preferences; 'highlighted' will allow the aspect to be used when the agent is highlighted as a replacement for the default (application of a color)
Aspect statement is used to define a way to draw the current agent. Several aspects can be defined in one species. It can use attributes to customize each agent's aspect. The aspect is evaluate for each agent each time it has to be displayed.
- An example of use of the aspect statement:
species one_species {
int a <- rnd(10);
aspect aspect1 {
if(a mod 2 = 0) { draw circle(a);}
else {draw square(a);}
draw text: "a= " + a color: #black size: 5;
}
}
- The
aspect
statement is of type: Behavior - The
aspect
statement can be embedded into: Species, Model, - The
aspect
statement embeds statements: draw,
-
value
(boolean), (omissible) : a boolean expression. If its evaluation is true, the assertion is successful. Otherwise, an error (or a warning) is raised. -
label
(string): a string displayed instead of the failed expression in order to customize the error or warning if the assertion is false -
warning
(boolean): if set to true, makes the assertion emit a warning instead of an error
Allows to check if the evaluation of a given expression returns true. If not, an error (or a warning) is raised. If the statement is used inside a test, the error is not propagagated but invalidates the test (in case of a warning, it partially invalidates it). Otherwise, it is normally propagated
- Any boolean expression can be used
assert (2+2) = 4;
assert self != nil;
int t <- 0; assert is_error(3/t);
(1 / 2) is float
- if the 'warn:' facet is set to true, the statement emits a warning (instead of an error) in case the expression is false
assert 'abc' is string warning: true
- See also: test, setup, is_error, is_warning,
- The
assert
statement is of type: Single statement - The
assert
statement can be embedded into: test, action, Sequence of statements or action, Behavior, Sequence of statements or action, - The
assert
statement embeds statements:
-
message
(any type), (omissible) : A message to display alongside the results. Should concisely describe the contents of the benchmark -
repeat
(int): An int expression describing how many executions of the block must be handled. The output in this case will return the min, max and average durations
Displays in the console the duration in ms of the execution of the statements included in the block. It is possible to indicate, with the 'repeat' facet, how many times the sequence should be run
- The
benchmark
statement is of type: Sequence of statements or action - The
benchmark
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
benchmark
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
outputs
(list): The list of output variables to analyse -
report
(string): The path to the file where the Betad report will be written -
sampling
(an identifier): The sampling method to build parameters sets that must be factorial based to some extends - available are: latinhypercube, orthogonal, factorial, uniform, saltelli, morris -
factorial
(list): The number of automated steps to swip over, when step facet is missing in parameter definition. Default is 9 -
results
(string): The path to the file where the automatic batch report will be written -
sample
(int): The number of sample required.
This algorithm runs an exploration with a given sampling to compute BetadKu - see doi: 10.1007/s10588-021-09358-5
- For example:
method sobol sample_size:100 outputs:['my_var'] report:'../path/to/report/file.txt';
- The
betad
statement is of type: Batch method - The
betad
statement can be embedded into: Experiment, - The
betad
statement embeds statements:
break
allows to interrupt the current sequence of statements.
- The
break
statement is of type: Single statement - The
break
statement can be embedded into: Sequence of statements or action, - The
break
statement embeds statements:
-
name
(string), (omissible) : The name of the camera. Will be used to populate a menu with the other camera presets. Can provide a value to the 'camera:' facet of the display, which specifies which camera to use.Using the special constant #default will make it the default of the surrounding display -
distance
(float): If the 'location:' facet is not defined, defines the distance (in world units) that separates the camera from its target. If 'location:' is defined, especially if it is using a symbolic position, allows to specify the distance to keep from the target. If neither 'location:' or 'distance:' is defined, the default distance is the maximum between the width and the height of the world -
dynamic
(boolean): If true, the location, distance and target are automatically recomputed every step. Default is false. When true, will also set 'locked' to true, to avoid interferences from users -
lens
(any type in [float, int]): Allows to define the lens -- field of view in degrees -- of the camera. Between 0 and 360. Defaults to 45° -
location
(any type in [point, string]): Allows to define the location of the camera in the world, i.e. from where it looks at its target. If 'distance:' is specified, the final location is translated on the target-camera axis to respect the distance. Can be a (possibly dynamically computed) point or a symbolic position (#from_above, #from_left, #from_right, #from_up_right, #from_up_left, #from_front, #from_up_front) that will be dynamically recomputed if the target movesIf 'location:' is not defined, it will be that of the default camera (#from_top, #from_left...) defined in the preferences. -
locked
(boolean): If true, the user cannot modify the camera location and target by interacting with the display. It is automatically set when the camera is dynamic, so that the display can 'follow' the coordinates; but it can also be used with fixed coordinates to 'focus' the display on a specific scene -
target
(any type in [point, agent, geometry]): Allows to define the target of the camera (what does it look at). It can be a point (in world coordinates), a geometry or an agent, in which case its (possibly dynamic) location it used as the target. This facet can be complemented by 'distance:' and/or 'location:' to specify from where the target is looked at. If 'target:' is not defined, the default target is the centroid of the world shape.
camera
allows the modeler to define a camera. The display will then be able to choose among the camera defined (either within this statement or globally in GAMA) in a dynamic way. Several preset cameras are provided and accessible in the preferences (to choose the default) or in GAML using the keywords #from_above, #from_left, #from_right, #from_up_right, #from_up_left, #from_front, #from_up_front, #isometric.These cameras are unlocked (so that they can be manipulated by the user), look at the center of the world from a symbolic position, and the distance between this position and the target is equal to the maximum of the width and height of the world's shape. These preset cameras can be reused when defining new cameras, since their names can become symbolic positions for them. For instance: camera 'my_camera' location: #from_top distance: 10; will lower (or extend) the distance between the camera and the center of the world to 10. camera 'my_camera' locked: true location: #from_up_front target: people(0); will continuously follow the first agent of the people species from the up-front position.
- See also: display, agents, chart, event, graphics, display_grid, image_layer, species_layer,
- The
camera
statement is of type: Layer - The
camera
statement can be embedded into: display, - The
camera
statement embeds statements:
-
target
(any type in [agent, container]), (omissible) : an expression that is evaluated as an agent or a list of the agent to be captured -
as
(species): the species that the captured agent(s) will become, this is a micro-species of the calling agent's species -
returns
(a new identifier): a list of the newly captured agent(s)
Allows an agent to capture other agent(s) as its micro-agent(s).
- The preliminary for an agent A to capture an agent B as its micro-agent is that the A's species must defined a micro-species which is a sub-species of B's species (cf. [Species161#Nesting_species Nesting species]).
species A {
...
}
species B {
...
species C parent: A {
...
}
...
}
- To capture all "A" agents as "C" agents, we can ask an "B" agent to execute the following statement:
capture list(B) as: C;
- Deprecated writing:
capture target: list (B) as: C;
- See also: release,
- The
capture
statement is of type: Sequence of statements or action - The
capture
statement can be embedded into: Behavior, Sequence of statements or action, - The
capture
statement embeds statements:
This statement cannot be used alone
- See also: try,
- The
catch
statement is of type: Sequence of statements or action - The
catch
statement can be embedded into: try, - The
catch
statement embeds statements:
-
name
(a label), (omissible) : The title of the category displayed in the UI -
color
(rgb): The background color of the category in the UI -
expanded
(boolean): Whether the category is initially expanded or not
Allows to define a category of parameters that will serve to group parameters in the UI. The category can be declared as initially expanded or closed (overriding the corresponding preference) and with a background color
- The
category
statement is of type: Single statement - The
category
statement can be embedded into: Experiment, - The
category
statement embeds statements:
-
name
(string), (omissible) : the identifier of the chart layer -
axes
(rgb): the axis color -
background
(rgb): the background color -
color
(rgb): Text color -
gap
(float): minimum gap between bars (in proportion) -
label_background_color
(rgb): Color of the label background (for Pie chart) -
label_font
(any type in [string, font]): Label font face. Either the name of a font face or a font -
label_text_color
(rgb): Color of the label text (for Pie chart) -
legend_font
(any type in [string, font]): Legend font face. Either the name of a font face or a font -
memorize
(boolean): Whether or not to keep the values in memory (in order to produce a csv file, for instance). The default value, true, can also be changed in the preferences -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. -
reverse_axes
(boolean): reverse X and Y axis (for example to get horizental bar charts -
series_label_position
(an identifier), takes values in: {default, none, legend, onchart, yaxis, xaxis}: Position of the Series names: default (best guess), none, legend, onchart, xaxis (for category plots) or yaxis (uses the first serie name). -
size
(point): the layer resize factor: {1,1} refers to the original size whereas {0.5,0.5} divides by 2 the height and the width of the layer. In case of a 3D layer, a 3D point can be used (note that {1,1} is equivalent to {1,1,0}, so a resize of a layer containing 3D objects with a 2D points will remove the elevation) -
style
(an identifier), takes values in: {line, area, bar, dot, step, spline, stack, 3d, ring, exploded, default}: The sub-style style, also default style for the series. -
tick_font
(any type in [string, font]): Tick font face. Either the name of a font face or a font. When used for a series chart, it will set the font of values on the axes, but When used with a pie, it will modify the font of messages associated to each pie section. -
tick_line_color
(rgb): the tick lines color -
title_font
(any type in [string, font]): Title font face. Either the name of a font face or a font -
title_visible
(boolean): chart title visible -
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
type
(an identifier), takes values in: {xy, scatter, histogram, series, pie, radar, heatmap, box_whisker}: the type of chart. It could be histogram, series, xy, pie, radar, heatmap or box whisker. The difference between series and xy is that the former adds an implicit x-axis that refers to the numbers of cycles, while the latter considers the first declaration of data to be its x-axis. -
visible
(boolean): Defines whether this layer is visible or not -
x_label
(string): the title for the X axis -
x_log_scale
(boolean): use Log Scale for X axis -
x_range
(any type in [float, int, point, list]): range of the x-axis. Can be a number (which will set the axis total range) or a point (which will set the min and max of the axis). -
x_serie
(any type in [list, float, int]): for series charts, change the default common x serie (simulation cycle) for an other value (list or numerical). -
x_serie_labels
(any type in [list, float, int, string]): change the default common x series labels (replace x value or categories) for an other value (string or numerical). -
x_tick_line_visible
(boolean): X tick line visible -
x_tick_unit
(float): the tick unit for the y-axis (distance between horizontal lines and values on the left of the axis). -
x_tick_values_visible
(boolean): X tick values visible -
y_label
(string): the title for the Y axis -
y_log_scale
(boolean): use Log Scale for Y axis -
y_range
(any type in [float, int, point, list]): range of the y-axis. Can be a number (which will set the axis total range) or a point (which will set the min and max of the axis). -
y_serie_labels
(any type in [list, float, int, string]): for heatmaps/3d charts, change the default y serie for an other value (string or numerical in a list or cumulative). -
y_tick_line_visible
(boolean): Y tick line visible -
y_tick_unit
(float): the tick unit for the x-axis (distance between vertical lines and values bellow the axis). -
y_tick_values_visible
(boolean): Y tick values visible -
y2_label
(string): the title for the second Y axis -
y2_log_scale
(boolean): use Log Scale for second Y axis -
y2_range
(any type in [float, int, point, list]): range of the second y-axis. Can be a number (which will set the axis total range) or a point (which will set the min and max of the axis). -
y2_tick_unit
(float): the tick unit for the x-axis (distance between vertical lines and values bellow the axis).
chart
allows modeler to display a chart: this enables to display specific values of the model at each iteration. GAMA can display various chart types: time series (series), pie charts (pie) and histograms (histogram).
- The general syntax is:
display chart_display {
chart "chart name" type: series [additional options] {
[Set of data, datalists statements]
}
}
- See also: display, agents, event, graphics, display_grid, image_layer, overlay, quadtree, species_layer, text,
- The
chart
statement is of type: Layer - The
chart
statement can be embedded into: display, - The
chart
statement embeds statements: add, ask, data, datalist, do, put, remove, set, using,
-
emotion_created
(emotion): the emotion that will be created with the contagion -
emotion_detected
(emotion): the emotion that will start the contagion -
name
(an identifier), (omissible) : the identifier of the unconscious contagion -
charisma
(float): The charisma value of the perceived agent (between 0 and 1) -
decay
(float): The decay value of the emotion added to the agent (between 0 and 1) -
intensity
(float): The intensity value of the emotion added to the agent (between 0 and 1) -
receptivity
(float): The receptivity value of the current agent (between 0 and 1) -
threshold
(float): The threshold value to make the contagion -
when
(boolean): A boolean value to get the emotion only with a certain condition
enables to directly add an emotion of a perceived species if the perceived agent gets a particular emotion.
- Other examples of use:
conscious_contagion emotion_detected:fear emotion_created:fearConfirmed;
conscious_contagion emotion_detected:fear emotion_created:fearConfirmed charisma: 0.5 receptivity: 0.5;
- The
conscious_contagion
statement is of type: Single statement - The
conscious_contagion
statement can be embedded into: Behavior, Sequence of statements or action, - The
conscious_contagion
statement embeds statements:
continue
allows to skip the remaining statements inside a loop and an ask and directly move to the next element. Inside a switch, it has the same effect as break.
- The
continue
statement is of type: Single statement - The
continue
statement can be embedded into: Sequence of statements or action, - The
continue
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the rule -
belief
(predicate): The mandatory belief -
beliefs
(list): The mandatory beliefs -
desire
(predicate): The mandatory desire -
desires
(list): The mandatory desires -
emotion
(emotion): The mandatory emotion -
emotions
(list): The mandatory emotions -
ideal
(predicate): The mandatory ideal -
ideals
(list): The mandatory ideals -
lifetime
(int): the lifetime value of the mental state created -
new_belief
(predicate): The belief that will be added -
new_beliefs
(list): The belief that will be added -
new_desire
(predicate): The desire that will be added -
new_desires
(list): The desire that will be added -
new_emotion
(emotion): The emotion that will be added -
new_emotions
(list): The emotion that will be added -
new_ideal
(predicate): The ideal that will be added -
new_ideals
(list): The ideals that will be added -
new_uncertainties
(list): The uncertainty that will be added -
new_uncertainty
(predicate): The uncertainty that will be added -
obligation
(predicate): The mandatory obligation -
obligations
(list): The mandatory obligations -
parallel
(any type in [boolean, int]): setting this facet to 'true' will allow 'perceive' to use concurrency with a parallel_bdi architecture; setting it to an integer will set the threshold under which they will be run sequentially (the default is initially 20, but can be fixed in the preferences). This facet is true by default. -
remove_belief
(predicate): The belief that will be removed -
remove_beliefs
(list): The belief that will be removed -
remove_desire
(predicate): The desire that will be removed -
remove_desires
(list): The desire that will be removed -
remove_emotion
(emotion): The emotion that will be removed -
remove_emotions
(list): The emotion that will be removed -
remove_ideal
(predicate): The ideal that will be removed -
remove_ideals
(list): The ideals that will be removed -
remove_intention
(predicate): The intention that will be removed -
remove_obligation
(predicate): The obligation that will be removed -
remove_obligations
(list): The obligation that will be removed -
remove_uncertainties
(list): The uncertainty that will be removed -
remove_uncertainty
(predicate): The uncertainty that will be removed -
strength
(any type in [float, int]): The stregth of the mental state created -
threshold
(float): Threshold linked to the emotion. -
uncertainties
(list): The mandatory uncertainties -
uncertainty
(predicate): The mandatory uncertainty -
when
(boolean):
enables to add or remove mantal states depending on the emotions of the agent, after the emotional engine and before the cognitive or normative engine.
- Other examples of use:
coping emotion: new_emotion("fear") when: flip(0.5) new_desire: new_predicate("test");
- The
coping
statement is of type: Behavior - The
coping
statement can be embedded into: simple_bdi, parallel_bdi, Species, Model, - The
coping
statement embeds statements:
-
species
(any type in [species, agent]), (omissible) : an expression that evaluates to a species, the species of the agents to be created. In the case of simulations, the name 'simulation', which represents the current instance of simulation, can also be used as a proxy to their species -
as
(species): optionally indicates a species into which to cast the created agents. -
from
(any type): an expression that evaluates to a localized entity, a list of localized entities, a string (the path of a file), a file (shapefile, a .csv, a .asc or a OSM file) or a container returned by a request to a database -
number
(int): an expression that evaluates to an int, the number of created agents -
returns
(a new identifier): a new temporary variable name containing the list of created agents (a list, even if only one agent has been created) -
with
(map): an expression that evaluates to a map, for each pair the key is a species attribute and the value the assigned value
Allows an agent to create number
agents of species species
, to create agents of species species
from a shapefile or to create agents of species species
from one or several localized entities (discretization of the localized entity geometries).
- Its simple syntax to create
an_int
agents of speciesa_species
is:
create a_species number: an_int;
create species_of(self) number: 5 returns: list5Agents;
- In GAML modelers can create agents of species
a_species
(with two attributestype
andnature
with types corresponding to the types of the shapefile attributes) from a shapefilethe_shapefile
while reading attributes 'TYPE_OCC' and 'NATURE' of the shapefile. One agent will be created by object contained in the shapefile:
create a_species from: the_shapefile with: [type:: read('TYPE_OCC'), nature::read('NATURE')];
- In order to create agents from a .csv file, facet
header
can be used to specified whether we can use columns header:
create toto from: "toto.csv" header: true with:[att1::read("NAME"), att2::read("TYPE")];
or
create toto from: "toto.csv" with:[att1::read(0), att2::read(1)]; //with read(int), the index of the column
- Similarly to the creation from shapefile, modelers can create agents from a set of geometries. In this case, one agent per geometry will be created (with the geometry as shape)
create species_of(self) from: [square(4), circle(4)]; // 2 agents have been created, with shapes respectively square(4) and circle(4)
- Created agents are initialized following the rules of their species. If one wants to refer to them after the statement is executed, the returns keyword has to be defined: the agents created will then be referred to by the temporary variable it declares. For instance, the following statement creates 0 to 4 agents of the same species as the sender, and puts them in the temporary variable children for later use.
create species (self) number: rnd (4) returns: children;
ask children {
// ...
}
- If one wants to specify a special initialization sequence for the agents created, create provides the same possibilities as ask. This extended syntax is:
create a_species number: an_int {
[statements]
}
- The same rules as in ask apply. The only difference is that, for the agents created, the assignments of variables will bypass the initialization defined in species. For instance:
create species(self) number: rnd (4) returns: children {
set location <- myself.location + {rnd (2), rnd (2)}; // tells the children to be initially located close to me
set parent <- myself; // tells the children that their parent is me (provided the variable parent is declared in this species)
}
- Deprecated uses:
// Simple syntax
create species: a_species number: an_int;
- If
number
equals 0 or species is not a species, the statement is ignored.
- The
create
statement is of type: Sequence of statements or action - The
create
statement can be embedded into: Behavior, Sequence of statements or action, - The
create
statement embeds statements:
-
legend
(string), (omissible) : The legend of the chart -
value
(any type in [float, point, list]): The value to output on the chart -
accumulate_values
(boolean): Force to replace values at each step (false) or accumulate with previous steps (true) -
color
(any type in [rgb, list]): color of the serie, for heatmap can be a list to specify [minColor,maxColor] or [minColor,medColor,maxColor] -
fill
(boolean): Marker filled (true) or not (false) -
line_visible
(boolean): Whether lines are visible or not -
marker
(boolean): marker visible or not -
marker_shape
(an identifier), takes values in: {marker_empty, marker_square, marker_circle, marker_up_triangle, marker_diamond, marker_hor_rectangle, marker_down_triangle, marker_hor_ellipse, marker_right_triangle, marker_vert_rectangle, marker_left_triangle}: Shape of the marker -
marker_size
(float): Size in pixels of the marker -
style
(an identifier), takes values in: {line, area, bar, dot, step, spline, stack, 3d, ring, exploded}: Style for the serie (if not the default one sepecified on chart statement) -
thickness
(float): The thickness of the lines to draw -
use_second_y_axis
(boolean): Use second y axis for this serie -
x_err_values
(any type in [float, list]): the X Error bar values to display. Has to be a List. Each element can be a number or a list with two values (low and high value) -
y_err_values
(any type in [float, list]): the Y Error bar values to display. Has to be a List. Each element can be a number or a list with two values (low and high value) -
y_minmax_values
(list): the Y MinMax bar values to display (BW charts). Has to be a List. Each element can be a number or a list with two values (low and high value)
This statement allows to describe the values that will be displayed on the chart.
- The
data
statement is of type: Single statement - The
data
statement can be embedded into: chart, Sequence of statements or action, - The
data
statement embeds statements:
-
value
(list): the values to display. Has to be a matrix, a list or a List of List. Each element can be a number (series/histogram) or a list with two values (XY chart) -
legend
(list), (omissible) : the name of the series: a list of strings (can be a variable with dynamic names) -
accumulate_values
(boolean): Force to replace values at each step (false) or accumulate with previous steps (true) -
color
(list): list of colors, for heatmaps can be a list of [minColor,maxColor] or [minColor,medColor,maxColor] -
fill
(boolean): Marker filled (true) or not (false), same for all series. -
line_visible
(boolean): Line visible or not (same for all series) -
marker
(boolean): marker visible or not -
marker_shape
(an identifier), takes values in: {marker_empty, marker_square, marker_circle, marker_up_triangle, marker_diamond, marker_hor_rectangle, marker_down_triangle, marker_hor_ellipse, marker_right_triangle, marker_vert_rectangle, marker_left_triangle}: Shape of the marker. Same one for all series. -
marker_size
(list): the marker sizes to display. Can be a list of numbers (same size for each marker of the series) or a list of list (different sizes by point) -
style
(an identifier), takes values in: {line, area, bar, dot, step, spline, stack, 3d, ring, exploded}: Style for the serie (if not the default one sepecified on chart statement) -
thickness
(float): The thickness of the lines to draw -
use_second_y_axis
(boolean): Use second y axis for this serie -
x_err_values
(list): the X Error bar values to display. Has to be a List. Each element can be a number or a list with two values (low and high value) -
y_err_values
(list): the Y Error bar values to display. Has to be a List. Each element can be a number or a list with two values (low and high value) -
y_minmax_values
(list): the Y MinMax bar values to display (BW charts). Has to be a List. Each element can be a number or a list with two values (low and high value)
add a list of series to a chart. The number of series can be dynamic (the size of the list changes each step). See Ant Foraging (Charts) model in ChartTest for examples.
- The
datalist
statement is of type: Single statement - The
datalist
statement can be embedded into: chart, Sequence of statements or action, - The
datalist
statement embeds statements:
-
value
(any type), (omissible) : The value or values this statement tries to match
Used in a switch match structure, the block prefixed by default is executed only if no other block has matched (otherwise it is not).
- The
default
statement is of type: Sequence of statements or action - The
default
statement can be embedded into: switch, - The
default
statement embeds statements:
-
var
(an identifier), (omissible) : the variable to be diffused. If diffused over a field, then this name will serve to identify the diffusion -
on
(any type in [species, field, list]): the list of agents (in general cells of a grid), or a field on which the diffusion will occur -
avoid_mask
(boolean): if true, the value will not be diffused in the masked cells, but will be restitute to the neighboring cells, multiplied by the proportion value (no signal lost). If false, the value will be diffused in the masked cells, but masked cells won't diffuse the value afterward (lost of signal). (default value : false) -
cycle_length
(int): the number of diffusion operation applied in one simulation step -
mask
(matrix): a matrix that masks the diffusion ( created from an image for instance). The cells corresponding to the values smaller than "-1" in the mask matrix will not diffuse, and the other will diffuse. -
matrix
(matrix): the diffusion matrix ("kernel" or "filter" in image processing). Can have any size, as long as dimensions are odd values. -
method
(an identifier), takes values in: {convolution, dot_product}: the diffusion method. One of 'convolution' or 'dot_product' -
min
(float): if a value is smaller than this value, it will not be diffused. By default, this value is equal to 0.0. This value cannot be smaller than 0. -
propagation
(a label), takes values in: {diffusion, gradient}: represents both the way the signal is propagated and the way to treat multiple propagation of the same signal occurring at once from different places. If propagation equals 'diffusion', the intensity of a signal is shared between its neighbors with respect to 'proportion', 'variation' and the number of neighbors of the environment places (4, 6 or 8). I.e., for a given signal S propagated from place P, the value transmitted to its N neighbors is : S' = (S / N / proportion) - variation. The intensity of S is then diminished by S*
proportion on P. In a diffusion, the different signals of the same name see their intensities added to each other on each place. If propagation equals 'gradient', the original intensity is not modified, and each neighbors receives the intensity : S / proportion - variation. If multiple propagation occur at once, only the maximum intensity is kept on each place. If 'propagation' is not defined, it is assumed that it is equal to 'diffusion'. -
proportion
(float): a diffusion rate -
radius
(int): a diffusion radius (in number of cells from the center) -
variation
(float): an absolute value to decrease at each neighbors
This statements allows a value to diffuse among a species on agents (generally on a grid) depending on a given diffusion matrix.
- A basic example of diffusion of the variable phero defined in the species cells, given a diffusion matrix math_diff is:
matrix<float> math_diff <- matrix([[1/9,1/9,1/9],[1/9,1/9,1/9],[1/9,1/9,1/9]]);
diffuse var: phero on: cells matrix: math_diff;
- The diffusion can be masked by obstacles, created from a bitmap image:
diffuse var: phero on: cells matrix: math_diff mask: mymask;
- A convenient way to have an uniform diffusion in a given radius is (which is equivalent to the above diffusion):
diffuse var: phero on: cells proportion: 1/9 radius: 1;
- The
diffuse
statement is of type: Single statement - The
diffuse
statement can be embedded into: Behavior, Sequence of statements or action, - The
diffuse
statement embeds statements:
-
name
(a label), (omissible) : the identifier of the display -
antialias
(boolean): Indicates whether to use advanced antialiasing for the display or not. The default value is the one indicated in the preferences of GAMA ('false' is its factory default). Antialising produces smoother outputs, but comes with a cost in terms of speed and memory used. -
autosave
(any type in [boolean, point, string]): Allows to save this display on disk. This facet accepts bool, point or string values. If it is false or nil, nothing happens. 'true' will save it at a resolution of 500x500 with a standard name (containing the name of the model, display, resolution, cycle and time). A non-nil point will change that resolution. A non-nil string will keep 500x500 and change the filename (if it is not dynamically built, the previous file will be erased). Note that setting autosave to true in a display will synchronize all the displays defined in the experiment -
axes
(boolean): Allows to enable/disable the drawing of the world shape and the ordinate axes. Default can be configured in Preferences -
background
(rgb): Allows to fill the background of the display and its toolbar with a specific color. Beware that this color, used in the UI, will not be affected by the light used in the display. -
camera
(string): Allows to define the name of the camera to use. Default value is 'default'. Accepted values are (1) the name of one of the cameras defined using the 'camera' statement or (2) one of the preset cameras, accessible using constants: #from_above, #from_left, #from_right, #from_up_left, #from_up_right, #from_front, #from_up_front, #isometric -
fullscreen
(any type in [boolean, int]): Indicates, when using a boolean value, whether or not the display should cover the whole screen (default is false). If an integer is passed, specifies also the screen to use: 0 for the primary monitor, 1 for the secondary one, and so on and so forth. If the monitor is not available, the first one is used -
keystone
(container): Set the position of the 4 corners of your screen ([topLeft,topRight,botLeft,botRight]), in (x,y) coordinate ( the (0,0) position is the top left corner, while the (1,1) position is the bottom right corner). The default value is : [{0,0},{1,0},{0,1},{1,1}] -
light
(boolean): Allows to enable/disable the light at once. Default is true -
locked
(boolean): Allows to lock/unlock a 2D display when it opens. For 3D displays please use thecamera
statement -
orthographic_projection
(boolean): Allows to enable/disable the orthographic projection. Default can be configured in Preferences -
parent
(an identifier): Declares that this display inherits its layers and attributes from the parent display named as the argument. Expects the identifier of the parent display or a string if the name of the parent contains spaces -
refresh
(boolean): Indicates the condition under which this output should be refreshed (default is true) -
show_fps
(boolean): Allows to enable/disable the drawing of the number of frames per second -
toolbar
(any type in [boolean, rgb]): Indicates whether the top toolbar of the display view should be initially visible or not. If a color is passed, then the background of the toolbar takes this color -
type
(a label): Allows to use either Java2D (for planar models) or OpenGL (for 3D models) as the rendering subsystem -
virtual
(boolean): Declaring a display as virtual makes it invisible on screen, and only usable for display inheritance -
z_far
(float): Set the distances to the far depth clipping planes. Must be positive. -
z_near
(float): Set the distances to the near depth clipping planes. Must be positive.
A display refers to an independent and mobile part of the interface that can display species, images, texts or charts.
- The general syntax is:
display my_display [additional options] { ... }
- Each display can include different layers (like in a GIS).
display gridWithElevationTriangulated type: opengl {
grid cell elevation: true triangulation: true;
species people aspect: base;
}
- The
display
statement is of type: Output - The
display
statement can be embedded into: output, permanent, - The
display
statement embeds statements: agents, camera, chart, display_grid, event, graphics, image_layer, light, mesh, overlay, rotation, species_layer,
-
species
(species), (omissible) : the species of the agents in the grid -
border
(rgb): the color to draw lines (borders of cells) -
elevation
(any type in [matrix, float, int, boolean]): Allows to specify the elevation of each cell, if any. Can be a matrix of float (provided it has the same size than the grid), an int or float variable of the grid species, or simply true (in which case, the variable called 'grid_value' is used to compute the elevation of each cell) -
grayscale
(boolean): if true, givse a grey value to each polygon depending on its elevation (false by default) -
hexagonal
(boolean): -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. In case of negative value OpenGl will position the layer out of the environment. -
refresh
(boolean): (openGL only) specify whether the display of the species is refreshed. (true by default, usefull in case of agents that do not move) -
rotate
(float): Defines the angle of rotation of this layer, in degrees, around the z-axis. -
selectable
(boolean): Indicates whether the agents present on this layer are selectable by the user. Default is true -
size
(point): extent of the layer in the screen from its position. Coordinates in [0,1[ are treated as percentages of the total surface, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Like in 'position', an elevation can be provided with the z coordinate, allowing to scale the layer in the 3 directions -
smooth
(boolean): Applies a simple convolution (box filter) to smooth out the terrain produced by this field. Does not change the values of course. -
text
(boolean): specify whether the attribute used to compute the elevation is displayed on each cells (false by default) -
texture
(file): Either file containing the texture image to be applied on the grid or, if not specified, the use of the image composed by the colors of the cells -
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
triangulation
(boolean): specifies whther the cells will be triangulated: if it is false, they will be displayed as horizontal squares at a given elevation, whereas if it is true, cells will be triangulated and linked to neighbors in order to have a continuous surface (false by default) -
visible
(boolean): Defines whether this layer is visible or not -
wireframe
(boolean): if true displays the grid in wireframe using the lines color
display_grid
is used using the grid
keyword. It allows the modeler to display in an optimized way all cell agents of a grid (i.e. all agents of a species having a grid topology).
- The general syntax is:
display my_display {
grid ant_grid lines: #black position: { 0.5, 0 } size: {0.5,0.5};
}
- To display a grid as a DEM:
display my_display {
grid cell texture: texture_file text: false triangulation: true elevation: true;
}
- The
display_grid
statement is of type: Layer - The
display_grid
statement can be embedded into: display, - The
display_grid
statement embeds statements:
-
action
(an identifier), (omissible) : the name of an action or a primitive -
internal_function
(any type): -
with
(map): a map expression containing the parameters of the action
Allows the agent to execute an action or a primitive. For a list of primitives available in every species, see this [BuiltIn161 page]; for the list of primitives defined by the different skills, see this [Skills161 page]. Finally, see this [Species161 page] to know how to declare custom actions.
- The simple syntax (when the action does not expect any argument and the result is not to be kept) is:
do name_of_action_or_primitive;
- In case the action expects one or more arguments to be passed, they are defined by using facets (enclosed tags or a map are now deprecated):
do name_of_action_or_primitive arg1: expression1 arg2: expression2;
- In case the result of the action needs to be made available to the agent, the action can be called with the agent calling the action (
self
when the agent itself calls the action) instead ofdo
; the result should be assigned to a temporary variable:
type_returned_by_action result <- self name_of_action_or_primitive [];
- In case of an action expecting arguments and returning a value, the following syntax is used:
type_returned_by_action result <- self name_of_action_or_primitive [arg1::expression1, arg2::expression2];
- Deprecated uses: following uses of the
do
statement (still accepted) are now deprecated:
// Simple syntax:
do action: name_of_action_or_primitive;
// In case the result of the action needs to be made available to the agent, the `returns` keyword can be defined; the result will then be referred to by the temporary variable declared in this attribute:
do name_of_action_or_primitive returns: result;
do name_of_action_or_primitive arg1: expression1 arg2: expression2 returns: result;
type_returned_by_action result <- name_of_action_or_primitive(self, [arg1::expression1, arg2::expression2]);
// In case the result of the action needs to be made available to the agent
let result <- name_of_action_or_primitive(self, []);
// In case the action expects one or more arguments to be passed, they can also be defined by using enclosed `arg` statements, or the `with` facet with a map of parameters:
do name_of_action_or_primitive with: [arg1::expression1, arg2::expression2];
or
do name_of_action_or_primitive {
arg arg1 value: expression1;
arg arg2 value: expression2;
...
}
- The
do
statement is of type: Single statement - The
do
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, - The
do
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the rule -
when
(boolean): The condition to fulfill in order to execute the statements embedded in the rule. when: true makes the rule always activable -
priority
(float): An optional priority for the rule, which is used to sort activable rules and run them in that order
A simple definition of a rule (set of statements which execution depend on a condition and a priority).
- The
do_rule
statement is of type: Behavior - The
do_rule
statement can be embedded into: rules, Species, Experiment, Model, - The
do_rule
statement embeds statements:
-
geometry
(any type), (omissible) : any type of data (it can be geometry, image, text) -
anchor
(point): Only used when perspective: true in OpenGL. The anchor point of the location with respect to the envelope of the text to draw, can take one of the following values: #center, #top_left, #left_center, #bottom_left, #bottom_center, #bottom_right, #right_center, #top_right, #top_center; or any point between {0,0} (#bottom_left) and {1,1} (#top_right) -
at
(point): location where the shape/text/icon is drawn -
begin_arrow
(any type in [int, float]): the size of the arrow, located at the beginning of the drawn geometry -
border
(any type in [rgb, boolean]): if used with a color, represents the color of the geometry border. If set to false, expresses that no border should be drawn. If not set, the borders will be drawn using the color of the geometry. -
color
(any type in [rgb, container]): the color to use to display the object. In case of images, will try to colorize it. You can also pass a list of colors : in that case, each color will be matched to its corresponding vertex. -
depth
(float): (only if the display type is opengl) Add an artificial depth to the geometry previously defined (a line becomes a plan, a circle becomes a cylinder, a square becomes a cube, a polygon becomes a polyhedron with height equal to the depth value). Note: This only works if the geometry is not a point -
end_arrow
(any type in [int, float]): the size of the arrow, located at the end of the drawn geometry -
font
(any type in [font, string]): the font used to draw the text, if any. Applying this facet to geometries or images has no effect. You can construct here your font with the operator "font". ex : font:font("Helvetica", 20 , #plain) -
lighted
(boolean): Whether the object should be lighted or not (only applicable in the context of opengl displays) -
perspective
(boolean): Whether to render the text in perspective or facing the user. Default is in perspective. -
precision
(float): (only if the display type is opengl and only for text drawing) controls the accuracy with which curves are rendered in glyphs. Between 0 and 1, the default is 0.1. Smaller values will output much more faithful curves but can be considerably slower, so it is better if they concern text that does not change and can be drawn inside layers marked as 'refresh: false' -
rotate
(any type in [float, int, pair]): orientation of the shape/text/icon; can be either an int/float (angle) or a pair float::point (angle::rotation axis). The rotation axis, when expressed as an angle, is by defaut {0,0,1} -
size
(any type in [float, point]): Size of the shape/icon/image to draw, expressed as a bounding box (width, height, depth; if expressed as a float, represents the box as a cube). Does not apply to texts: use a font with the required size instead -
texture
(any type): the texture(s) that should be applied to the geometry. Either a path to a file or a list of paths -
width
(float): The line width to use for drawing this object. In OpenGL displays, this attribute is considered as optional and not implemented by all gaphic card vendors. The default value is set by the preference found in Displays>OpenGL Rendering Properties (which, when inspected, also provides the maximal possible value on the local graphics configuration) -
wireframe
(boolean): a condition specifying whether to draw the geometry in wireframe or not
draw
is used in an aspect block to express how agents of the species will be drawn. It is evaluated each time the agent has to be drawn. It can also be used in the graphics block.
- Any kind of geometry as any location can be drawn when displaying an agent (independently of his shape)
aspect geometryAspect {
draw circle(1.0) empty: !hasFood color: #orange ;
}
- Image or text can also be drawn
aspect arrowAspect {
draw "Current state= "+state at: location + {-3,1.5} color: #white font: font('Default', 12, #bold) ;
draw file(ant_shape_full) rotate: heading at: location size: 5
}
- Arrows can be drawn with any kind of geometry, using begin_arrow and end_arrow facets, combined with the empty: facet to specify whether it is plain or empty
aspect arrowAspect {
draw line([{20, 20}, {40, 40}]) color: #black begin_arrow:5;
draw line([{10, 10},{20, 50}, {40, 70}]) color: #green end_arrow: 2 begin_arrow: 2 empty: true;
draw square(10) at: {80,20} color: #purple begin_arrow: 2 empty: true;
}
- The
draw
statement is of type: Single statement - The
draw
statement can be embedded into: aspect, Sequence of statements or action, Layer, - The
draw
statement embeds statements:
This statement cannot be used alone
- See also: if,
- The
else
statement is of type: Sequence of statements or action - The
else
statement can be embedded into: if, - The
else
statement embeds statements:
-
emotion_detected
(emotion): the emotion that will start the contagion -
name
(an identifier), (omissible) : the identifier of the emotional contagion -
charisma
(float): The charisma value of the perceived agent (between 0 and 1) -
decay
(float): The decay value of the emotion added to the agent -
emotion_created
(emotion): the emotion that will be created with the contagion -
intensity
(float): The intensity value of the emotion created to the agent -
receptivity
(float): The receptivity value of the current agent (between 0 and 1) -
threshold
(float): The threshold value to make the contagion -
when
(boolean): A boolean value to get the emotion only with a certain condition
enables to make conscious or unconscious emotional contagion
- Other examples of use:
emotional_contagion emotion_detected:fearConfirmed;
emotional_contagion emotion_detected:fear emotion_created:fearConfirmed;
emotional_contagion emotion_detected:fear emotion_created:fearConfirmed charisma: 0.5 receptivity: 0.5;
- The
emotional_contagion
statement is of type: Single statement - The
emotional_contagion
statement can be embedded into: Behavior, Sequence of statements or action, - The
emotional_contagion
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the enforcement -
law
(string): The law to enforce -
norm
(string): The norm to enforce -
obligation
(predicate): The obligation to enforce -
reward
(string): The positive sanction to apply if the norm has been followed -
sanction
(string): The sanction to apply if the norm is violated -
when
(boolean): A boolean value to enforce only with a certain condition
apply a sanction if the norm specified is violated, or a reward if the norm is applied by the perceived agent
- Other examples of use:
focus var:speed; //where speed is a variable from a species that is being perceived
- The
enforcement
statement is of type: Single statement - The
enforcement
statement can be embedded into: Behavior, Sequence of statements or action, - The
enforcement
statement embeds statements:
In an FSM architecture, enter
introduces a sequence of statements to execute upon entering a state.
- In the following example, at the step it enters into the state s_init, the message 'Enter in s_init' is displayed followed by the display of the state name:
state s_init {
enter {
write "Enter in" + state;
}
write state;
}
- See also: state, exit, transition,
- The
enter
statement is of type: Sequence of statements or action - The
enter
statement can be embedded into: state, - The
enter
statement embeds statements:
-
name
(an identifier), (omissible) : the equation identifier -
params
(list): the list of parameters used in predefined equation systems -
simultaneously
(list): a list of species containing a system of equations (all systems will be solved simultaneously) -
vars
(list): the list of variables used in predefined equation systems
The equation statement is used to create an equation system from several single equations.
- The basic syntax to define an equation system is:
float t;
float S;
float I;
equation SI {
diff(S,t) = (- 0.3 * S * I / 100);
diff(I,t) = (0.3 * S * I / 100);
}
- If the type: facet is used, a predefined equation system is defined using variables vars: and parameters params: in the right order. All possible predefined equation systems are the following ones (see [EquationPresentation161 EquationPresentation161] for precise definition of each classical equation system):
equation eqSI type: SI vars: [S,I,t] params: [N,beta];
equation eqSIS type: SIS vars: [S,I,t] params: [N,beta,gamma];
equation eqSIR type:SIR vars:[S,I,R,t] params:[N,beta,gamma];
equation eqSIRS type: SIRS vars: [S,I,R,t] params: [N,beta,gamma,omega,mu];
equation eqSEIR type: SEIR vars: [S,E,I,R,t] params: [N,beta,gamma,sigma,mu];
equation eqLV type: LV vars: [x,y,t] params: [alpha,beta,delta,gamma];
- If the simultaneously: facet is used, system of all the agents will be solved simultaneously.
- See also: =, solve,
- The
equation
statement is of type: Sequence of statements or action - The
equation
statement can be embedded into: Species, Model, - The
equation
statement embeds statements: =,
-
message
(string), (omissible) : the message to display in the error.
The statement makes the agent output an error dialog (if the simulation contains a user interface). Otherwise displays the error in the console.
- Throwing an error
error 'This is an error raised by ' + self;
- The
error
statement is of type: Single statement - The
error
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
error
statement embeds statements:
-
name
(string), (omissible) : the type of event captured: basic events include #mouse_up, #mouse_down, #mouse_move, #mouse_exit, #mouse_enter, #mouse_menu, #mouse_drag, #arrow_down, #arrow_up, #arrow_left, #arrow_right, #escape, #tab, #enter, #page_up, #page_down or a character -
action
(action): The identifier of the action to be executed in the context of the simulation. This action needs to be defined in 'global' or in the current experiment, without any arguments. The location of the mouse in the world can be retrieved in this action with the pseudo-constant #user_location -
type
(string): Type of device used to generate events. Defaults to 'default', which encompasses keyboard and mouse
event
allows to interact with the simulation by capturing mouse or key events and doing an action. The name of this action can be defined with the 'action:' facet, in which case the action needs to be defined in 'global' or in the current experiment, without any arguments. The location of the mouse in the world can be retrieved in this action with the pseudo-constant #user_location. The statements to execute can also be defined in the block at the end of this statement, in which case they will be executed in the context of the experiment
- The general syntax is:
event [event_type] action: myAction;
- For instance:
global {
// ...
action myAction () {
point loc <- #user_location; // contains the location of the mouse in the world
list<agent> selected_agents <- agents inside (10#m around loc); // contains agents clicked by the event
// code written by modelers
}
}
experiment Simple type:gui {
display my_display {
event #mouse_up action: myAction;
}
}
- See also: display, agents, chart, graphics, display_grid, image_layer, overlay, species_layer,
- The
event
statement is of type: Layer - The
event
statement can be embedded into: display, - The
event
statement embeds statements:
In an FSM architecture, exit
introduces a sequence of statements to execute right before exiting the state.
- In the following example, at the state it leaves the state s_init, he will display the message 'EXIT from s_init':
state s_init initial: true {
write state;
transition to: s1 when: (cycle > 2) {
write "transition s_init -> s1";
}
exit {
write "EXIT from "+state;
}
}
- See also: enter, state, transition,
- The
exit
statement is of type: Sequence of statements or action - The
exit
statement can be embedded into: state, - The
exit
statement embeds statements:
-
name
(a label), (omissible) : identifier of the experiment -
title
(string): -
type
(a label): The type of the experiment:gui
,batch
,test
, etc. -
autorun
(boolean): Whether this experiment should be run automatically when launched (false by default) -
benchmark
(boolean): If true, make GAMA record the number of invocations and running time of the statements and operators of the simulations launched in this experiment. The results are automatically saved in a csv file in a folder called 'benchmarks' when the experiment is closed -
control
(an identifier): the control architecture used for defining the behavior of the experiment -
keep_seed
(boolean): Allows to keep the same seed between simulations. Mainly useful for batch experiments -
keep_simulations
(boolean): In the case of a batch experiment, specifies whether or not the simulations should be kept in memory for further analysis or immediately discarded with only their fitness kept in memory -
parallel
(any type in [boolean, int]): When set to true, use multiple threads to run its simulations. Setting it to n will set the numbers of threads to use -
parent
(an identifier): the parent experiment (in case of inheritance between experiments) -
record
(boolean): Cannot be used in batch experiments. Whether the simulations run by this experiment are recorded so that they be run backward. Boolean expression expected, which will be evaluated by simulations at each cycle, so that the recording can occur based on specific conditions (for instance 'every(10#cycles)'). A value of 'true' will record each step. -
repeat
(int): In the case of a batch experiment, expresses hom many times the simulations must be repeated -
schedules
(container): A container of agents (a species, a dynamic list, or a combination of species and containers) , which represents which agents will be actually scheduled when the population is scheduled for execution. For instance, 'species a schedules: (10 among a)' will result in a population that schedules only 10 of its own agents every cycle. 'species b schedules: []' will prevent the agents of 'b' to be scheduled. Note that the scope of agents covered here can be larger than the population, which allows to build complex scheduling controls; for instance, defining 'global schedules: [] {...} species b schedules: []; species c schedules: b + world; ' allows to simulate a model where the agents of b are scheduled first, followed by the world, without even having to create an instance of c. -
skills
(list): the skills attached to the experiment -
until
(boolean): In the case of a batch experiment, an expression that will be evaluated to know when a simulation should be terminated -
virtual
(boolean): Whether the experiment is virtual (cannot be instantiated, but only used as a parent, false by default)
Declaration of a particular type of agent that can manage simulations. If the experiment directly imports a model using the 'model:' facet, this facet must be the first one after the name of the experiment. Any experiment attached to a model is a species (introduced by the keyword 'experiment' which directly or indirectly inherits from an abstract species called 'experiment' itself. This abstract species (sub-species of 'agent') defines several attributes and actions that can then be used in any experiment. Experiments also define several attributes, which, in addition to the attributes inherited from agent, form the minimal set of knowledge any experiment will have access to.
- The
experiment
statement is of type: Experiment - The
experiment
statement can be embedded into: Model, - The
experiment
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
factorial
(list): The number slices (value) applied to each parameter to build the factorial experimental plan. -
from
(string): a path to a file where each lines correspond to one parameter set and each colon a parameter -
iterations
(int): The number of iteration for orthogonal sampling, 5 by default -
levels
(int): The number of levels for morris sampling, 4 by default -
outputs
(list): The list of output variables to track throughout exploration -
results
(string): The path to the file where the automatic batch report will be written -
sample
(int): The number of sample required, 132 by default -
sampling
(string): The name of the sampling method among: latinhypercube, orthogonal, factorial, uniform, saltelli, morris -
with
(list): the list of parameter sets to explore; a parameter set is defined by a map: key: name of the variable, value: expression for the value of the variable
This is the standard batch method. The exploration mode is defined by default when there is no method element present in the batch section. It explores all the combination of parameter values in a sequential way. You can also choose a sampling method for the exploration. See [batch161 the batch dedicated page].
- As other batch methods, the basic syntax of the exploration statement uses
method exploration
instead of the expectedexploration name: id
:
method exploration;
- Simplest example:
method exploration;
- Using sampling facet:
method exploration sampling:latinhypercube sample:100;
- Using from facet:
method exploration from:"../path/to/my/exploration/plan.csv";
- Using with facet:
method exploration with:[["a"::0.5, "b"::10],["a"::0.1, "b"::100]];
- The
exploration
statement is of type: Batch method - The
exploration
statement can be embedded into: Experiment, - The
exploration
statement embeds statements:
-
agent_cause
(agent): the value of the agent causing the created belief (can be nil -
belief
(predicate): The predicate to focus on the beliefs of the other agent -
desire
(predicate): The predicate to focus on the desires of the other agent -
emotion
(emotion): The emotion to focus on the emotions of the other agent -
expression
(any type): an expression that will be the value kept in the belief -
id
(string): the identifier of the focus -
ideal
(predicate): The predicate to focus on the ideals of the other agent -
is_uncertain
(boolean): a boolean to indicate if the mental state created is an uncertainty -
lifetime
(int): the lifetime value of the created belief -
strength
(any type in [float, int]): The priority of the created predicate -
truth
(boolean): the truth value of the created belief -
uncertainty
(predicate): The predicate to focus on the uncertainties of the other agent -
var
(any type in [any type, list, container]): the variable of the perceived agent you want to add to your beliefs -
when
(boolean): A boolean value to focus only with a certain condition
enables to directly add a belief from the variable of a perceived species.
- Other examples of use:
focus var:speed /*where speed is a variable from a species that is being perceived*/
- The
focus
statement is of type: Single statement - The
focus
statement can be embedded into: Behavior, Sequence of statements or action, - The
focus
statement embeds statements:
-
value
(any type), (omissible) : The agent, list of agents, geometry to focus on
Allows to focus on the passed parameter in all available displays. Passing 'nil' for the parameter will make all screens return to their normal zoom
- Focuses on an agent, a geometry, a set of agents, etc...
focus_on my_species(0);
- The
focus_on
statement is of type: Single statement - The
focus_on
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
focus_on
statement embeds statements:
-
name
(an identifier), (omissible) : The name of this method. For internal use only -
aggregation
(a label), takes values in: {min, max, avr}: the agregation method -
crossover_prob
(float): crossover probability between two individual solutions -
improve_sol
(boolean): if true, use a hill climbing algorithm to improve the solutions at each generation -
max_gen
(int): number of generations -
maximize
(float): the value the algorithm tries to maximize -
minimize
(float): the value the algorithm tries to minimize -
mutation_prob
(float): mutation probability for an individual solution -
nb_prelim_gen
(int): number of random populations used to build the initial population -
pop_dim
(int): size of the population (number of individual solutions) -
stochastic_sel
(boolean): if true, use a stochastic selection algorithm (roulette) rather a determistic one (keep the best solutions)
This is a simple implementation of Genetic Algorithms (GA). See the wikipedia article and [batch161 the batch dedicated page]. The principle of the GA is to search an optimal solution by applying evolution operators on an initial population of solutions. There are three types of evolution operators: crossover, mutation and selection. Different techniques can be applied for this selection. Most of them are based on the solution quality (fitness).
- As other batch methods, the basic syntax of the
genetic
statement usesmethod genetic
instead of the expectedgenetic name: id
:
method genetic [facet: value];
- For example:
method genetic maximize: food_gathered pop_dim: 5 crossover_prob: 0.7 mutation_prob: 0.1 nb_prelim_gen: 1 max_gen: 20;
- The
genetic
statement is of type: Batch method - The
genetic
statement can be embedded into: Experiment, - The
genetic
statement embeds statements:
-
name
(a label), (omissible) : the human readable title of the graphics -
background
(rgb): the background color of the layer. Default is none -
border
(rgb): Color to apply to the border of the rectangular shape of the layer. Default is none -
fading
(boolean): Used in conjunction with 'trace:', allows to apply a fading effect to the previous traces. Default is false -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. In case of negative value OpenGl will position the layer out of the environment. -
refresh
(boolean): (openGL only) specify whether the display of the species is refreshed. (true by default, usefull in case of agents that do not move) -
rotate
(float): Defines the angle of rotation of this layer, in degrees, around the z-axis. -
size
(point): extent of the layer in the screen from its position. Coordinates in [0,1[ are treated as percentages of the total surface, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Like in 'position', an elevation can be provided with the z coordinate, allowing to scale the layer in the 3 directions -
trace
(any type in [boolean, int]): Allows to aggregate the visualization at each timestep on the display. Default is false. If set to an int value, only the last n-th steps will be visualized. If set to true, no limit of timesteps is applied. -
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
visible
(boolean): Defines whether this layer is visible or not
graphics
allows the modeler to freely draw shapes/geometries/texts without having to define a species. It works exactly like a species [Aspect161 aspect]: the draw statement can be used in the same way.
- The general syntax is:
display my_display {
graphics "my new layer" {
draw circle(5) at: {10,10} color: #red;
draw "test" at: {10,10} size: 20 color: #black;
}
}
- See also: display, agents, chart, event, graphics, display_grid, image_layer, overlay, species_layer,
- The
graphics
statement is of type: Layer - The
graphics
statement can be embedded into: display, - The
graphics
statement embeds statements:
-
value
(agent), (omissible) : The agent to hightlight -
color
(rgb): An optional color to highlight the agent. Note that this color will become the default color for further higlight operations
Allows to highlight the agent passed in parameter in all available displays, optionaly setting a color. Passing 'nil' for the agent will remove the current highlight
- Highlighting an agent
highlight my_species(0) color: #blue;
- The
highlight
statement is of type: Single statement - The
highlight
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
highlight
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
aggregation
(a label), takes values in: {min, max, avr}: the agregation method -
init_solution
(map): init solution: key: name of the variable, value: value of the variable -
iter_max
(int): number of iterations. this number corresponds to the number of "moves" in the parameter space. For each move, the algorithm will test the whole neighborhood of the current solution, each neighbor corresponding to a particular set of parameters and thus to a run. Thus, there can be several runs per iteration (maximum: 2^(number of parameters)). -
maximize
(float): the value the algorithm tries to maximize -
minimize
(float): the value the algorithm tries to minimize
This algorithm is an implementation of the Hill Climbing algorithm. See the wikipedia article and [batch161 the batch dedicated page].
- As other batch methods, the basic syntax of the
hill_climbing
statement usesmethod hill_climbing
instead of the expectedhill_climbing name: id
:
method hill_climbing [facet: value];
- For example:
method hill_climbing iter_max: 50 maximize : food_gathered;
- The
hill_climbing
statement is of type: Batch method - The
hill_climbing
statement can be embedded into: Experiment, - The
hill_climbing
statement embeds statements:
-
condition
(boolean), (omissible) : A boolean expression: the condition that is evaluated.
Allows the agent to execute a sequence of statements if and only if the condition evaluates to true.
- The generic syntax is:
if bool_expr {
[statements]
}
- Optionally, the statements to execute when the condition evaluates to false can be defined in a following statement else. The syntax then becomes:
if bool_expr {
[statements]
}
else {
[statements]
}
string valTrue <- "";
if true {
valTrue <- "true";
}
else {
valTrue <- "false";
}
// valTrue equals "true"
string valFalse <- "";
if false {
valFalse <- "true";
}
else {
valFalse <- "false";
}
// valFalse equals "false"
- ifs and elses can be imbricated as needed. For instance:
if bool_expr {
[statements]
}
else if bool_expr2 {
[statements]
}
else {
[statements]
}
- The
if
statement is of type: Sequence of statements or action - The
if
statement can be embedded into: Behavior, Sequence of statements or action, Layer, Output, - The
if
statement embeds statements: else,
-
name
(any type), (omissible) : the name/path of the image (in the case of a raster image), a matrix of int, an image file -
color
(rgb): in the case of a shapefile, this the color used to fill in geometries of the shapefile. In the case of an image, it is used to tint the image -
gis
(any type in [file, string]): the name/path of the shape file (to display a shapefile as background, without creating agents from it) -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. In case of negative value OpenGl will position the layer out of the environment. -
refresh
(boolean): (openGL only) specify whether the image display is refreshed or not. (false by default, true should be used in cases of images that are modified over the simulation) -
rotate
(float): Defines the angle of rotation of this layer, in degrees, around the z-axis. -
size
(point): extent of the layer in the screen from its position. Coordinates in [0,1[ are treated as percentages of the total surface, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Like in 'position', an elevation can be provided with the z coordinate, allowing to scale the layer in the 3 directions -
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
visible
(boolean): Defines whether this layer is visible or not
image_layer
allows modeler to display an image (e.g. as background of a simulation). Note that this image will not be dynamically changed or moved in OpenGL, unless the refresh: facet is set to true.
- The general syntax is:
display my_display {
image image_file [additional options];
}
- For instance, in the case of a bitmap image
display my_display {
image "../images/my_backgound.jpg";
}
- If you already have your image stored in a matrix
display my_display {
image my_image_matrix;
}
- Or in the case of a shapefile:
display my_display {
image testGIS gis: "../includes/building.shp" color: rgb('blue');
}
- It is also possible to superpose images on different layers in the same way as for species using opengl display:
display my_display {
image "../images/image1.jpg";
image "../images/image2.jpg";
image "../images/image3.jpg" position: {0,0,0.5};
}
- See also: display, agents, chart, event, graphics, display_grid, overlay, species_layer,
- The
image_layer
statement is of type: Layer - The
image_layer
statement can be embedded into: display, - The
image_layer
statement embeds statements:
-
name
(any type), (omissible) : the identifier of the inspector -
attributes
(list): the list of attributes to inspect. A list that can contain strings or pair<string,type>, or a mix of them. These can be variables of the species, but also attributes present in the attributes table of the agent. The type is necessary in that case -
refresh
(boolean): Indicates the condition under which this output should be refreshed (default is true) -
type
(an identifier), takes values in: {agent, table}: the way to inspect agents: in a table, or a set of inspectors -
value
(any type): the set of agents to inspect, could be a species, a list of agents or an agent
inspect
(and browse
) statements allows modeler to inspect a set of agents, in a table with agents and all their attributes or an agent inspector per agent, depending on the type: chosen. Modeler can choose which attributes to display. When browse
is used, type: default value is table, whereas wheninspect
is used, type: default value is agent.
- An example of syntax is:
inspect "my_inspector" value: ant attributes: ["name", "location"];
- The
inspect
statement is of type: Output - The
inspect
statement can be embedded into: output, permanent, Behavior, Sequence of statements or action, - The
inspect
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the law -
all
(boolean): add an obligation for each belief -
belief
(predicate): The mandatory belief -
beliefs
(list): The mandatory beliefs -
lifetime
(int): the lifetime value of the mental state created -
new_obligation
(predicate): The predicate that will be added as an obligation -
new_obligations
(list): The list of predicates that will be added as obligations -
parallel
(any type in [boolean, int]): setting this facet to 'true' will allow 'perceive' to use concurrency with a parallel_bdi architecture; setting it to an integer will set the threshold under which they will be run sequentially (the default is initially 20, but can be fixed in the preferences). This facet is true by default. -
strength
(any type in [float, int]): The stregth of the mental state created -
threshold
(float): Threshold linked to the obedience value. -
when
(boolean):
enables to add a desire or a belief or to remove a belief, a desire or an intention if the agent gets the belief or/and desire or/and condition mentioned.
- Other examples of use:
rule belief: new_predicate("test") when: flip(0.5) new_desire: new_predicate("test");
- The
law
statement is of type: Single statement - The
law
statement can be embedded into: Species, Model, - The
law
statement embeds statements:
-
value
(any type), (omissible) : Either #none, to indicate that no layout will be imposed, or one of the four possible predefined layouts: #stack, #split, #horizontal or #vertical. This layout will be applied to both experiment and simulation display views. In addition, it is possible to define a custom layout using the horizontal() and vertical() operators -
background
(rgb): Whether the whole interface of GAMA should be colored or not (nil by default) -
consoles
(boolean): Whether the consoles are visible or not (true by default) -
controls
(boolean): Whether the experiment should show its control toolbar on top or not -
editors
(boolean): Whether the editors should initially be visible or not -
navigator
(boolean): Whether the navigator view is visible or not (false by default) -
parameters
(boolean): Whether the parameters view is visible or not (true by default) -
tabs
(boolean): Whether the displays should show their tab or not -
toolbars
(boolean): Whether the displays should show their toolbar or not -
tray
(boolean): Whether the bottom tray is visible or not (true by default)
Represents the layout of the display views of simulations and experiments
- For instance, this layout statement will allow to split the screen occupied by displays in four equal parts, with no tabs. Pairs of display::weight represent the number of the display in their order of definition and their respective weight within a horizontal and vertical section
layout horizontal([vertical([0::5000,1::5000])::5000,vertical([2::5000,3::5000])::5000]) tabs: false;
- The
layout
statement is of type: Output - The
layout
statement can be embedded into: output, - The
layout
statement embeds statements:
-
name
(a new identifier), (omissible) : The name of the temporary variable -
index
(a datatype identifier): The type of the index if this declaration concerns a container -
of
(a datatype identifier): The type of the contents if this declaration concerns a container -
type
(a datatype identifier): The type of the temporary variable -
value
(any type): The value assigned to the temporary variable
Declaration and initialization of a temporary variable.
- The
let
statement is of type: Single statement - The
let
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
let
statement embeds statements:
-
name
(string), (omissible) : The name of the light source, must be unique (otherwise the last definition prevails). Will be used to populate a menu where light sources can be easily turned on and off. Special names can be used:Using the special constant #ambient will allow to redefine or control the ambient light intensity and presenceUsing the special constant #default will replace the default directional light of the surrounding display -
active
(boolean): a boolean expression telling if the light is on or off. (default value if not specified : true) -
angle
(float): the angle of the spot light in degree (only for spot light). (default value : 45) -
constant_attenuation
(float): the constant attenuation of the positionnal light. (default value : 0) -
direction
(point): the direction of the light (only for direction and spot light). (default value : {0.5,0.5,-1}) -
dynamic
(boolean): specify if the parameters of the light need to be updated every cycle or treated as constants. (default value : true). -
intensity
(any type in [int, rgb]): an int / rgb / rgba value to specify either the color+intensity of the light or simply its intensity. (default value if not specified can be set in the Preferences. If not, it is equal to: (160,160,160,255) ). -
linear_attenuation
(float): the linear attenuation of the positionnal light. (default value : 0) -
location
(point): the location of the light (only for point and spot light) in model coordinates. Default is {0,0,20} -
quadratic_attenuation
(float): the quadratic attenuation of the positionnal light. (default value : 0) -
show
(boolean): If true, draws the light source. (default value if not specified : false). -
type
(string): the type of light to create. A value among {#point, #direction, #spot}
light
allows to define diffusion lights in your 3D display. They must be given a name, which will help track them in the UI. Two names have however special meanings: #ambient, which designates the ambient luminosity and color of the scene (with a default intensity of (160,160,160,255) or the value set in the Preferences) and #default, which designates the default directional light applied to a scene (with a default medium intensity of (160,160,160,255) or the value set in the Preferences in the direction given by (0.5,0.5,1)). Redefining a light named #ambient or #regular will then modify these default lights (for example changing their color or deactivating them). To be more precise, and given all the default values of the facets, the existence of these two lights is effectively equivalent to redefining:light #ambient intensity: gama.pref_display_light_intensity; light #default type: #direction intensity: gama.pref_display_light_intensity direction: {0.5,0.5,-1};
- The general syntax is:
light 1 type:point location:{20,20,20} color:255, linear_attenuation:0.01 quadratic_attenuation:0.0001 show:true dynamic:false;
light 'spot1' type: #spot location:{20,20,20} direction:{0,0,-1} color:255 angle:25 linear_attenuation:0.01 quadratic_attenuation:0.0001 draw:true dynamic: false;
light 'point2' type: #point direction:{1,1,-1} color:255 draw:true dynamic: false;
- See also: display,
- The
light
statement is of type: Layer - The
light
statement can be embedded into: display, - The
light
statement embeds statements:
-
name
(a new identifier), (omissible) : a temporary variable name -
from
(any type in [int, float]): an int or float expression that represents the lower bound of the loop -
over
(any type in [container, point]): a list, point, matrix or map expression -
step
(any type in [int, float]): an int or float expression that represents the incrementation of the loop -
times
(int): an int expression -
to
(any type in [int, float]): an int or float expression that represents the higher bound of the loop -
while
(boolean): a boolean expression
Allows the agent to perform the same set of statements either a fixed number of times, or while a condition is true, or by progressing in a collection of elements or along an interval of numbers. Be aware that there are no prevention of infinite loops. As a consequence, open loops should be used with caution, as one agent may block the execution of the whole model.
- The basic syntax for repeating a fixed number of times a set of statements is:
loop times: an_int_expression {
// [statements]
}
- The basic syntax for repeating a set of statements while a condition holds is:
loop while: a_bool_expression {
// [statements]
}
- The basic syntax for repeating a set of statements by progressing over a container of a point is:
loop a_temp_var over: a_collection_expression {
// [statements]
}
- The basic syntax for repeating a set of statements while an index iterates over a range of values with a fixed step of 1 is:
loop a_temp_var from: int_expression_1 to: int_expression_2 {
// [statements]
}
- The incrementation step of the index can also be chosen:
loop a_temp_var from: int_expression_1 to: int_expression_2 step: int_expression3 {
// [statements]
}
- In these latter three cases, the name facet designates the name of a temporary variable, whose scope is the loop, and that takes, in turn, the value of each of the element of the list (or each value in the interval). For example, in the first instance of the "loop over" syntax :
int a <- 0;
loop i over: [10, 20, 30] {
a <- a + i;
} // a now equals 60
- The second (quite common) case of the loop syntax allows one to use an interval of integers or floats. The from and to facets take an int or float expression as arguments, with the first (resp. the last) specifying the beginning (resp. end) of the inclusive interval (i.e. [to, from]). If the step is not defined, it is assumed to be equal to 1 or -1, depending on the direction of the range. If it is defined, its sign will be respected, so that a positive step will never allow the loop to enter a loop from i to j where i is greater than j
list the_list <-list (species_of (self));
loop i from: 0 to: length (the_list) - 1 {
ask the_list at i {
// ...
}
} // every agent of the list is asked to do something
- The
loop
statement is of type: Sequence of statements or action - The
loop
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
loop
statement embeds statements:
-
value
(any type), (omissible) : The value or values this statement tries to match
In a switch...match structure, the value of each match block is compared to the value in the switch. If they match, the embedded statement set is executed. Four kinds of match can be used, equality, containment, betweenness and regex matching
- match block is executed if the switch value is equals to the value of the match:
switch 3 {
match 1 {write "Match 1"; }
match 3 {write "Match 2"; }
}
- match_between block is executed if the switch value is in the interval given in value of the match_between:
switch 3 {
match_between [1,2] {write "Match OK between [1,2]"; }
match_between [2,5] {write "Match OK between [2,5]"; }
}
- match_one block is executed if the switch value is equals to one of the values of the match_one:
switch 3 {
match_one [0,1,2] {write "Match OK with one of [0,1,2]"; }
match_between [2,3,4,5] {write "Match OK with one of [2,3,4,5]"; }
}
- The
match
statement is of type: Sequence of statements or action - The
match
statement can be embedded into: switch, - The
match
statement embeds statements:
-
source
(any type in [file, matrix, species]), (omissible) : Allows to specify the elevation/value of each cell by passing a grid, a raster, image or csv file or directly a matrix of int/float. The dimensions of the field are those of the file or matrix. -
above
(float): Can be used to specify a 'minimal' value under which the render will not render the cells with this value -
border
(rgb): the color to draw lines (borders of cells) -
color
(any type in [rgb, list, map]): displays the field using the given color or colors. When a simple color is provided, paints each cell with this color, with a brightness depending on the value of the cell.When a list of colors is provided, they are used in a cyclic manner to color each cell, independently from their value. When this list is casted to apalette
(using the corresponding operator), it is used to color each cell based on its value (with interpolation between the colors). When agradient
(see the corresponding operator) is passed, the interpolation between the two extreme colors is computed by GAMA.When ascale
(see the corresponding operator) is passed, cells are colored depending on where their value fits in the scale, with no interpolation -
grayscale
(boolean): if true, paints each cell with a value of grey depending on its value. Supersedes 'color' if it is defined (it is actually equivalent to passing '#gray' tocolor:
). False by default -
no_data
(float): Can be used to specify a 'no_data' value, forcing the renderer to not render the cells with this value. If not specified, that value will be searched in the field to display -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. -
refresh
(boolean): (openGL only) specify whether the display of the species is refreshed. (true by default, but should be deactivated if the field is static) -
rotate
(float): Defines the angle of rotation of this layer, in degrees, around the z-axis. -
scale
(float): Represents the z-scaling factor, which allows to scale all values of the field. -
size
(any type in [point, float]): Represents the extent of the layer in the screen from its position. Coordinates in [0,1[ are treated as percentages of the total surface, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Like in 'position', an elevation can be provided with the z coordinate, allowing to scale the layer in the 3 directions. This latter possibility allows to limit the height of the field. If only a flat value is provided, it is considered implicitly as the z maximal amplitude (or z scaling factor if < 1) -
smooth
(any type in [boolean, int]): Applies a simple convolution (box filter) to smooth out the terrain produced by this field. If true, one pass is done with a simple 3x3 kernel. Otherwise, the user can specify the number of successive passes (up to 4). Specifying 0 is equivalent to passing false -
text
(boolean): specify whether the value that represents the elevation is displayed on each cell (false by default) -
texture
(file): A file containing the texture image to be applied to the field. If not specified, the field will be displayed either in color or grayscale, depending on the other facets. Supersedes bothgrayscale
andcolor
-
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
triangulation
(boolean): specifies wether the cells of th field will be triangulated: if it is false, they will be displayed as horizontal squares at a given elevation, whereas if it is true, cells will be triangulated and linked to neighbors in order to have a continuous surface (false by default) -
visible
(boolean): Defines whether this layer is visible or not -
wireframe
(boolean): if true displays the field in wireframe using the lines color
Allows the modeler to display in an optimized way a field of values, optionally using elevation. Useful for displaying DEMs, for instance, without having to load them into a grid. Can be fed with a matrix of int/float, a grid, a csv/raster/image file and supports many visualisation options
- The general syntax is:
display my_display {
field a_filename lines: #black position: { 0.5, 0 } size: {0.5,0.5} triangulated: true texture: anothe_file;
}
- The
mesh
statement is of type: Layer - The
mesh
statement can be embedded into: display, - The
mesh
statement embeds statements:
-
source
(any type in [agent, species, container, an identifier]), (omissible) : can be an agent, a list of agents, a agent's population to be migrated -
target
(species): target species/population that source agent(s) migrate to. -
returns
(a new identifier): the list of returned agents in a new local variable
This command permits agents to migrate from one population/species to another population/species and stay in the same host after the migration. Species of source agents and target species respect the following constraints: (i) they are "peer" species (sharing the same direct macro-species), (ii) they have sub-species vs. parent-species relationship.
- It can be used in a 3-levels model, in case where individual agents can be captured into group meso agents and groups into clouds macro agents. migrate is used to allows agents captured by groups to migrate into clouds. See the model 'Balls, Groups and Clouds.gaml' in the library.
migrate ball_in_group target: ball_in_cloud;
- The
migrate
statement is of type: Sequence of statements or action - The
migrate
statement can be embedded into: Behavior, Sequence of statements or action, - The
migrate
statement embeds statements:
-
name
(a label), (omissible) : identifier of the monitor -
value
(any type): expression that will be evaluated to be displayed in the monitor -
color
(rgb): Indicates the (possibly dynamic) color of this output (default is a light gray) -
refresh
(boolean): Indicates the condition under which this output should be refreshed (default is true)
A monitor allows to follow the value of an arbitrary expression in GAML.
- An example of use is:
monitor "nb preys" value: length(prey as list) refresh_every: 5;
- The
monitor
statement is of type: Output - The
monitor
statement can be embedded into: output, permanent, - The
monitor
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
levels
(an identifier): Number of level for the Morris method, can't be 1 -
outputs
(list): The list of output variables to analyze through morris method -
report
(string): The path to the file where the Morris report will be written -
sample
(an identifier): The size of the sample for Morris samples -
csv
(string): The path of morris sample .csv file. If don't use, automatic morris sampling will be perform and saved in the corresponding file -
results
(string): The path to the file where the automatic batch report will be written
This algorithm runs a Morris exploration - it has been built upon the SILAB librairy - disabled the repeat facet of the experiment
- For example:
method morris sample_size:100 nb_levels:4 outputs:['my_var'] report:'../path/to/report.txt;
- The
morris
statement is of type: Batch method - The
morris
statement can be embedded into: Experiment, - The
morris
statement embeds statements:
-
name
(an identifier), (omissible) : the name of the norm -
finished_when
(boolean): the boolean condition when the norm is finished -
instantaneous
(boolean): indicates if the norm is instananeous -
intention
(predicate): the intention triggering the norm -
lifetime
(int): the lifetime of the norm -
obligation
(predicate): the obligation triggering of the norm -
priority
(float): the priority value of the norm -
threshold
(float): the threshold to trigger the norm -
when
(boolean): the boolean condition when the norm is active
a norm indicates what action the agent has to do in a certain context and with and obedience value higher than the threshold
- The
norm
statement is of type: Behavior - The
norm
statement can be embedded into: Species, Model, - The
norm
statement embeds statements:
-
autosave
(any type in [boolean, string]): Allows to save the whole screen on disk. A value of true/false will save it with the resolution of the physical screen. Passing it a string allows to define the filename Note that setting autosave to true (or to any other value than false) will synchronize all the displays defined in the experiment -
synchronized
(boolean): Indicates whether the displays that compose this output should be synchronized with the simulation cycles
output
blocks define how to visualize a simulation (with one or more display blocks that define separate windows). It will include a set of displays, monitors and files statements. It will be taken into account only if the experiment type is gui
.
- Its basic syntax is:
experiment exp_name type: gui {
// [inputs]
output {
// [display, file, inspect, layout or monitor statements]
}
}
- The
output
statement is of type: Output - The
output
statement can be embedded into: Model, Experiment, - The
output
statement embeds statements: display, inspect, layout, monitor,
-
background
(rgb): the background color of the overlay displayed inside the view (the bottom overlay remains black) -
border
(rgb): Color to apply to the border of the rectangular shape of the overlay. Nil by default -
center
(any type): an expression that will be evaluated and displayed in the center section of the bottom overlay -
color
(any type in [list, rgb]): the color(s) used to display the expressions given in the 'left', 'center' and 'right' facets -
left
(any type): an expression that will be evaluated and displayed in the left section of the bottom overlay -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. In case of negative value OpenGl will position the layer out of the environment. -
right
(any type): an expression that will be evaluated and displayed in the right section of the bottom overlay -
rounded
(boolean): Whether or not the rectangular shape of the overlay should be rounded. True by default -
size
(point): extent of the layer in the view from its position. Coordinates in [0,1[ are treated as percentages of the total surface of the view, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Unlike 'position', no elevation can be provided with the z coordinate -
transparency
(float): the transparency rate of the overlay (between 0 -- opaque and 1 -- fully transparent) when it is displayed inside the view. The bottom overlay will remain at 0.75 -
visible
(boolean): Defines whether this layer is visible or not
overlay
allows the modeler to display a line to the already existing bottom overlay, where the results of 'left', 'center' and 'right' facets, when they are defined, are displayed with the corresponding color if defined.
- To display information in the bottom overlay, the syntax is:
overlay "Cycle: " + (cycle) center: "Duration: " + total_duration + "ms" right: "Model time: " + as_date(time,"") color: [#yellow, #orange, #yellow];
- See also: display, agents, chart, event, graphics, display_grid, image, species_layer,
- The
overlay
statement is of type: Layer - The
overlay
statement can be embedded into: display, - The
overlay
statement embeds statements:
-
var
(an identifier): the name of the variable (that should be declared in global) -
name
(a label), (omissible) : The message displayed in the interface -
among
(list): the list of possible values that this parameter can take -
category
(string): a category label, used to group parameters in the interface -
colors
(list): The colors of the control in the UI. An empty list has no effects. Only used for sliders and switches so far. For sliders, 3 colors will allow to specify the color of the left section, the thumb and the right section (in this order); 2 colors will define the left and right sections only (thumb will be dark green); 1 color will define the left section and the thumb. For switches, 2 colors will define the background for respectively the left 'true' and right 'false' sections. 1 color will define both backgrounds -
disables
(list): a list of global variables whose parameter editors will be disabled when this parameter value is set to true or to a value that casts to true (they are otherwise enabled) -
enables
(list): a list of global variables whose parameter editors will be enabled when this parameter value is set to true or to a value that casts to true (they are otherwise disabled) -
extensions
(list): Makes only sense for file parameters. A list of file extensions (like 'gaml', 'shp', etc.) that restricts the choice offered to the users to certain file types (folders not concerned). Default is empty, effectively accepting all files -
in_workspace
(boolean): Makes only sense for file parameters. Whether the file selector will be restricted to the workspace or not -
init
(any type): the init value -
labels
(list): The labels that will be displayed for switches (instead of True/False) -
max
(any type): the maximum value -
min
(any type): the minimum value -
on_change
(any type): Provides a block of statements that will be executed whenever the value of the parameter changes -
read_only
(boolean): Whether this parameter is read-only or editable -
slider
(boolean): Whether or not to display a slider for entering an int or float value. Default is true when max and min values are defined, false otherwise. If no max or min value is defined, setting this facet to true will have no effect -
step
(float): the increment step (mainly used in batch mode to express the variation step between simulation) -
type
(a datatype identifier): the variable type -
unit
(string): the variable unit -
updates
(list): a list of global variables whose parameter editors will be updated when this parameter value is changed (their min, max, step and among values will be updated accordingly if they depend on this parameter. Note that it might lead to some inconsistencies, for instance a parameter value which becomes out of range, or which does not belong anymore to a list of possible values. In these cases, the value of the affected parameter will not change)
The parameter statement specifies which global attributes (i) will change through the successive simulations (in batch experiments), (ii) can be modified by user via the interface (in gui experiments). In GUI experiments, parameters are displayed depending on their type.
- In gui experiment, the general syntax is the following:
parameter title var: global_var category: cat;
- In batch experiment, the two following syntaxes can be used to describe the possible values of a parameter:
parameter 'Value of toto:' var: toto among: [1, 3, 7, 15, 100];
parameter 'Value of titi:' var: titi min: 1 max: 100 step: 2;
- The
parameter
statement is of type: Parameter - The
parameter
statement can be embedded into: Experiment, - The
parameter
statement embeds statements:
-
target
(any type in [container, agent]): the list of the agent you want to perceive -
name
(an identifier), (omissible) : the name of the perception -
as
(species): an expression that evaluates to a species -
emotion
(emotion): The emotion needed to do the perception -
in
(any type in [float, geometry]): a float or a geometry. If it is a float, it's a radius of a detection area. If it is a geometry, it is the area of detection of others species. -
parallel
(any type in [boolean, int]): setting this facet to 'true' will allow 'perceive' to use concurrency with a parallel_bdi architecture; setting it to an integer will set the threshold under which they will be run sequentially (the default is initially 20, but can be fixed in the preferences). This facet is true by default. -
threshold
(float): Threshold linked to the emotion. -
when
(boolean): a boolean to tell when does the perceive is active
Allow the agent, with a bdi architecture, to perceive others agents
- the basic syntax to perceive agents inside a circle of perception
perceive name_of_perception target: the_agents_you_want_to_perceive in: distance when: condition {
//Here you are in the context of the perceived agents. To refer to the agent who does the perception, use myself.
//If you want to make an action (such as adding a belief for example), use ask myself{ do the_action}
}
- The
perceive
statement is of type: Behavior - The
perceive
statement can be embedded into: Species, Model, - The
perceive
statement embeds statements:
Represents the outputs of the experiment itself. In a batch experiment, the permanent section allows to define an output block that will NOT be re-initialized at the beginning of each simulation but will be filled at the end of each simulation.
- For instance, this permanent section will allow to display for each simulation the end value of the food_gathered variable:
permanent {
display Ants background: rgb('white') refresh_every: 1 {
chart "Food Gathered" type: series {
data "Food" value: food_gathered;
}
}
}
- The
permanent
statement is of type: Output - The
permanent
statement can be embedded into: Experiment, - The
permanent
statement embeds statements: display, inspect, monitor,
-
name
(an identifier), (omissible) : -
emotion
(emotion): -
finished_when
(boolean): -
instantaneous
(boolean): -
intention
(predicate): -
priority
(float): -
threshold
(float): -
when
(boolean):
define an action plan performed by an agent using the BDI engine
- The
plan
statement is of type: Behavior - The
plan
statement can be embedded into: Species, Model, - The
plan
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
iter_max
(int): number of iterations -
aggregation
(a label), takes values in: {min, max, avr}: the agregation method -
maximize
(float): the value the algorithm tries to maximize -
minimize
(float): the value the algorithm tries to minimize -
num_particles
(int): number of particles -
weight_cognitive
(float): weight for the cognitive component -
weight_inertia
(float): weight for the inertia component -
weight_social
(float): weight for the social component
This algorithm is an implementation of the Particle Swarm Optimization algorithm. Only usable for numerical paramaters and based on a continuous parameter space search. See the wikipedia article for more details.
- As other batch methods, the basic syntax of the
pso
statement usesmethod pso
instead of the expectedpso name: id
:
method pso [facet: value];
- For example:
method pso iter_max: 50 num_particles: 10 weight_inertia:0.7 weight_cognitive: 1.5 weight_social: 1.5 maximize: food_gathered;
- The
pso
statement is of type: Batch method - The
pso
statement can be embedded into: Experiment, - The
pso
statement embeds statements:
-
in
(any type in [container, species, agent, geometry]): the left member of the put assignment ('cont[index] <- expr;') is an expression cont that evaluates to a container (list, map, matrix). It makes no sense for graphs -
item
(any type), (omissible) : the right member of the put assignment ('cont[index] <- expr;') is an expression expr that evaluates to the element(s) to be put in the container -
all
(any type): when no index is specified between the square brackets, the put assignement applies to all elements and changes their value to the one provided -
at
(any type): the key or index at which to put the new value is specified bycontainer[index]
-
key
(any type): the key or index at which to put the new value is specified bycontainer[index]
A statement used to put items into containers at specific keys or indices. It can be written using the classic syntax (put ... in: ...
) or a compact one, which is now preferred.
- To put an element in a container at a given index, use
container[index] <- element;
(classic form:put element in: container at: index;
) - To put an element in a container at all indices (i.e. replace all values by the element), use
container[] <- element
(classic form:put element in: container all: true;
)
- The allowed configurations are the following ones:
expr_container[index] <- expr; // put or replace expr at index in the container
expr_container[] <- expr; // put expr at every index in the container (replace all values)
- In the case of a list, the position should be an integer in the bounds of the list. The facet all: is used to replace all the elements of the list by the given value.
list<int>putList <- [1,2,3,4,5]; // putList equals [1,2,3,4,5]
putList[1] <- -10; // putList equals [1,-10,3,4,5]
putList[] <- 10; // putList equals [10,10,10,10,10]
- In the case of a matrix, the position should be a point in the bounds of the matrix. If no position is provided, it is used to replace all the elements of the matrix by the given value.
matrix<int>putMatrix <- matrix([[0,1],[2,3]]); // putMatrix equals matrix([[0,1],[2,3]])
putMatrix[{1,1}] <- -10; // putMatrix equals matrix([[0,1],[2,-10]]);
putMatrix[] <- 10; // putMatrix equals matrix([[10,10],[10,10]])
- In the case of a map, the position should be one of the key values of the map. Notice that if the given key value does not exist in the map, a new pair key::value will be added to the map. The facet all is used to replace the value of all the pairs of the map.
map<string,int>putMap <- ["x"::4,"y"::7]; // putMap equals ["x"::4,"y"::7]
putMap['y'] <- -10; // putMap equals ["x"::4,"y"::-10]
putMap['z'] <- -20; // putMap equals ["x"::4,"y"::-10, "z"::-20]
putMap[] <- -30 ; // putMap equals ["x"::-30,"y"::-30, "z"::-30]
- The
put
statement is of type: Single statement - The
put
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, - The
put
statement embeds statements:
-
name
(an identifier), (omissible) : -
aggregation
(a label), takes values in: {min, max, avr}: the agregation method -
cycle_size_max
(int): minimal size of the considered cycles -
cycle_size_min
(int): maximal size of the considered cycles -
init_solution
(map): init solution: key: name of the variable, value: value of the variable -
iter_max
(int): number of iterations. this number corresponds to the number of "moves" in the parameter space. For each move, the algorithm will test the whole neighborhood of the current solution, each neighbor corresponding to a particular set of parameters and thus to a run. Thus, there can be several runs per iteration (maximum: 2^(number of parameters)). -
maximize
(float): the value the algorithm tries to maximize -
minimize
(float): the value the algorithm tries to minimize -
nb_tests_wthout_col_max
(int): number of movements without collision before shortening the tabu list -
tabu_list_size_init
(int): initial size of the tabu list -
tabu_list_size_max
(int): maximal size of the tabu list -
tabu_list_size_min
(int): minimal size of the tabu list
This algorithm is a simple implementation of the Reactive Tabu Search algorithm ((Battiti et al., 1993)). This Reactive Tabu Search is an enhance version of the Tabu search. It adds two new elements to the classic Tabu Search. The first one concerns the size of the tabu list: in the Reactive Tabu Search, this one is not constant anymore but it dynamically evolves according to the context. Thus, when the exploration process visits too often the same solutions, the tabu list is extended in order to favor the diversification of the search process. On the other hand, when the process has not visited an already known solution for a high number of iterations, the tabu list is shortened in order to favor the intensification of the search process. The second new element concerns the adding of cycle detection capacities. Thus, when a cycle is detected, the process applies random movements in order to break the cycle. See the batch dedicated page.
- As other batch methods, the basic syntax of the reactive_tabu statement uses
method reactive_tabu
instead of the expectedreactive_tabu name: id
:
method reactive_tabu [facet: value];
- For example:
method reactive_tabu iter_max: 50 tabu_list_size_init: 5 tabu_list_size_min: 2 tabu_list_size_max: 10 nb_tests_wthout_col_max: 20 cycle_size_min: 2 cycle_size_max: 20 maximize: food_gathered;
- The
reactive_tabu
statement is of type: Batch method - The
reactive_tabu
statement can be embedded into: Experiment, - The
reactive_tabu
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the reflex -
when
(boolean): an expression that evaluates a boolean, the condition to fulfill in order to execute the statements embedded in the reflex.
Reflexes are sequences of statements that can be executed by the agent. Reflexes prefixed by the 'reflex' keyword are executed continuously. Reflexes prefixed by 'init' are executed only immediately after the agent has been created. Reflexes prefixed by 'abort' just before the agent is killed. If a facet when: is defined, a reflex is executed only if the boolean expression evaluates to true.
- Example:
reflex my_reflex when: flip (0.5){ //Only executed when flip returns true
write "Executing the unconditional reflex";
}
- The
reflex
statement is of type: Behavior - The
reflex
statement can be embedded into: Species, Experiment, Model, - The
reflex
statement embeds statements:
-
target
(any type in [agent, list]), (omissible) : an expression that is evaluated as an agent/a list of the agents to be released -
as
(species): an expression that is evaluated as a species in which the micro-agent will be released -
in
(agent): an expression that is evaluated as an agent that will be the macro-agent in which micro-agent will be released, i.e. their new host -
returns
(a new identifier): a new variable containing a list of the newly released agent(s)
Allows an agent to release its micro-agent(s). The preliminary for an agent to release its micro-agents is that species of these micro-agents are sub-species of other species (cf. [Species161#Nesting_species Nesting species]). The released agents won't be micro-agents of the calling agent anymore. Being released from a macro-agent, the micro-agents will change their species and host (macro-agent).
- We consider the following species. Agents of "C" species can be released from a "B" agent to become agents of "A" species. Agents of "D" species cannot be released from the "A" agent because species "D" has no parent species.
species A {
...
}
species B {
...
species C parent: A {
...
}
species D {
...
}
...
}
- To release all "C" agents from a "B" agent, agent "C" has to execute the following statement. The "C" agent will change to "A" agent. The won't consider "B" agent as their macro-agent (host) anymore. Their host (macro-agent) will the be the host (macro-agent) of the "B" agent.
release list(C);
- The modeler can specify the new host and the new species of the released agents:
release list (C) as: new_species in: new host;
- See also: capture,
- The
release
statement is of type: Sequence of statements or action - The
release
statement can be embedded into: Behavior, Sequence of statements or action, - The
release
statement embeds statements:
-
from
(any type in [container, species, agent, geometry]): the left member of the removal assignment ('cont >> expr;') is an expression cont that evaluates to a container (list, map, graph) -
item
(any type), (omissible) : the right member of the removal assignment ('cont >> expr;') is an expression expr that evaluates to the element(s) to be removed from the container -
all
(any type): the symbol '>>-' allows to pass a container as item so as to remove all of its elements from the receiving container. If the item is not a container, all of its occurrences are removed -
index
(any type): any expression, the key at which to remove the element from the container -
key
(any type): If a key/index is to be removed (instead of a value), it must be indicated by usingcontainer[]
instead ofcontainer
A statement used to remove items from containers. It can be written using the classic syntax (remove ... from: ...
) or a compact one, which is now preferred.
- To remove an element from a container (other than a matrix), use
container >> element;
orcontainer >- element;
(classic form:remove element from: container;
) - To remove an index/key from a container (other than a matrix) use
container[] >> index
orcontainer[] >- index
(classic form:remove key: index from: container;
) - To remove all the elements contained in another container, use
container >>- elements;
(classic form:remove all: elements from: container;
) - To remove all the indexes contained in another container, use
container[] >>- indices;
(classic form:remove key: indices all: true from: container;
) - To remove all the occurences of an element in the container, use
container >>- element;
(classic form:remove element from: container all: true;
)
- This statement should be used in the following ways, depending on the kind of container used and the expected action on it:
expr_container >> expr (or expr_container >- expr) to remove an element
expr_container[] >> expr (or expr_container[] >- expr) to remove an index or a key;
expr_container >>- expr (to remove all occurences of expr), expr_container >>- container_of_expr (to remove all the elements in the passed argument), expr_container[] >>- container_of_expr (to remove all the index/keys in the passed argument)
- In the case of list,
>-
of>>
is used to remove the first occurence of a given expression, whereas>>-
is used to remove all its occurrences. Indices can also be removed in the same way
list<int> removeList <- [3,2,1,2,3];
removeList >- 2; // removeList equals [3,1,2,3]
removeList >>- 3; // removeList equals [1,2]
removeList[] >- 1; // removeList equals [1]
- In the case of map, to remove the pair identified by a given key, we have to specify that we are working on the keys. Same for lists
map<string,int> removeMap <- ["x"::5, "y"::7, "z"::7];
removeMap[] >- "x"; // removeMap equals ["y"::7, "z"::7]
removeMap[] >>- removeMap.keys; // removeMap equals map([])
- A map can be managed as a list of pairs: remove then operates on the values by default
map<string,int> removeMapList <- ["x"::5, "y"::7, "z"::7, "t"::5];
removeMapList >> 7; // removeMapList equals ["x"::5, "z"::7, "t"::5]
removeMapList >>- [5,7]; // removeMapList equals ["t"::5]
removeMapList[] >- "t"; // removeMapList equals map([])
- In the case of a graph, if a node is removed, all edges to and from this node are also removed. Note that the use of edge()/node()/edges()/nodes() operators is necessary
graph removeGraph <- as_edge_graph([{1,2}::{3,4},{3,4}::{5,6}]);
removeGraph >> node(1,2);
list var <- removeGraph.vertices; // var equals [{3,4},{5,6}]
list var <- removeGraph.edges; // var equals [polyline({3,4}::{5,6})]
removeGraph >> edge({3,4},{5,6});
list var <- removeGraph.vertices; // var equals [{3,4},{5,6}]
list var <- removeGraph.edges; // var equals []
- In the case of an agent or a shape,
remove
allows to remove an attribute from the attributes map of the receiver. However, for agents, it will only remove attributes that have been added dynamically, not the ones defined in the species or in its built-in parent.
global {
init {
create speciesRemove;
speciesRemove sR <- speciesRemove(0);
sR['a'] <- 100; // sR.a now equals 100
sR[] >> "a"; // sR.a does not exist anymore
}
}
- The
remove
statement is of type: Single statement - The
remove
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, - The
remove
statement embeds statements:
-
target
(agent), (omissible) : The agent to restore. Its attributes will be replaced by the ones stored in the file or string. No verification is done regarding the compatibility -
from
(any type in [string, file]): The file or the string from which to restore the agent
Allows to restore any agent that has been previously serialised or saved to a file, e.g. string s <- serialize(a);
... restore a from: s;
or save simulation to: 'sim.gsim' format: 'binary';
... restore simulation from: file('sim.gsim');
- The
restore
statement is of type: Single statement - The
restore
statement can be embedded into: Behavior, Sequence of statements or action, - The
restore
statement embeds statements:
-
value
(any type), (omissible) : an expression that is returned
Allows to immediately stop and tell which value to return from the evaluation of the surrounding action or top-level statement (reflex, init, etc.). Usually used within the declaration of an action. For more details about actions, see the following [Section161 section].
- Example:
string foo {
return "foo";
}
reflex {
string foo_result <- foo(); // foos_result is now equals to "foo"
}
- In the specific case one wants an agent to ask another agent to execute a statement with a return, it can be done similarly to:
// In Species A:
string foo_different {
return "foo_not_same";
}
/// ....
// In Species B:
reflex writing {
string temp <- some_agent_A.foo_different []; // temp is now equals to "foo_not_same"
}
- The
return
statement is of type: Single statement - The
return
statement can be embedded into: action, Behavior, Sequence of statements or action, - The
return
statement embeds statements:
-
angle
(any type in [float, int]), (omissible) : Defines the angle of rotation around the axis. No default defined. -
axis
(point): The axis of rotation, defined by a vector. Default is {0,0,1} (rotation around the z axis)This facet can be complemented by 'distance:' and/or 'location:' to specify from where the target is looked at. If 'target:' is not defined, the default target is the centroid of the world shape. -
dynamic
(boolean): If true, the rotation is applied every step. Default is false. -
location
(point): Allows to define the center of the rotation. Defaut value is not specified is the center of mass of the world (i.e. {width/2, height/2, max(width, height) / 2})
camera
allows the modeler to define a camera. The display will then be able to choose among the camera defined (either within this statement or globally in GAMA) in a dynamic way. Several preset cameras are provided and accessible in the preferences (to choose the default) or in GAML using the keywords #from_above, #from_left, #from_right, #from_up_right, #from_up_left, #from_front, #from_up_front.These cameras are unlocked (so that they can be manipulated by the user), look at the center of the world from a symbolic position, and the distance between this position and the target is equal to the maximum of the width and height of the world's shape. These preset cameras can be reused when defining new cameras, since their names can become symbolic positions for them. For instance: camera 'my_camera' location: #from_top distance: 10; will lower (or extend) the distance between the camera and the center of the world to 10. camera 'my_camera' locked: true location: #from_up_front target: people(0); will continuously follow the first agent of the people species from the up-front position.
- See also: display, agents, chart, event, graphics, display_grid, image_layer, species_layer,
- The
rotation
statement is of type: Layer - The
rotation
statement can be embedded into: display, - The
rotation
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the rule -
all
(boolean): add a desire for each belief -
belief
(predicate): The mandatory belief -
beliefs
(list): The mandatory beliefs -
desire
(predicate): The mandatory desire -
desires
(list): The mandatory desires -
emotion
(emotion): The mandatory emotion -
emotions
(list): The mandatory emotions -
ideal
(predicate): The mandatory ideal -
ideals
(list): The mandatory ideals -
lifetime
(any type in [int, list]): the lifetime value of the mental state created -
new_belief
(predicate): The belief that will be added -
new_beliefs
(list): The belief that will be added -
new_desire
(predicate): The desire that will be added -
new_desires
(list): The desire that will be added -
new_emotion
(emotion): The emotion that will be added -
new_emotions
(list): The emotion that will be added -
new_ideal
(predicate): The ideal that will be added -
new_ideals
(list): The ideals that will be added -
new_uncertainties
(list): The uncertainty that will be added -
new_uncertainty
(predicate): The uncertainty that will be added -
obligation
(predicate): The mandatory obligation -
obligations
(list): The mandatory obligations -
parallel
(any type in [boolean, int]): setting this facet to 'true' will allow 'perceive' to use concurrency with a parallel_bdi architecture; setting it to an integer will set the threshold under which they will be run sequentially (the default is initially 20, but can be fixed in the preferences). This facet is true by default. -
remove_belief
(predicate): The belief that will be removed -
remove_beliefs
(list): The belief that will be removed -
remove_desire
(predicate): The desire that will be removed -
remove_desires
(list): The desire that will be removed -
remove_emotion
(emotion): The emotion that will be removed -
remove_emotions
(list): The emotion that will be removed -
remove_ideal
(predicate): The ideal that will be removed -
remove_ideals
(list): The ideals that will be removed -
remove_intention
(predicate): The intention that will be removed -
remove_obligation
(predicate): The obligation that will be removed -
remove_obligations
(list): The obligation that will be removed -
remove_uncertainties
(list): The uncertainty that will be removed -
remove_uncertainty
(predicate): The uncertainty that will be removed -
strength
(any type in [float, int, list]): The stregth of the mental state created -
threshold
(float): Threshold linked to the emotion. -
uncertainties
(list): The mandatory uncertainties -
uncertainty
(predicate): The mandatory uncertainty -
when
(boolean):
enables to add a desire or a belief or to remove a belief, a desire or an intention if the agent gets the belief or/and desire or/and condition mentioned.
- The
rule
statement is of type: Single statement - The
rule
statement can be embedded into: simple_bdi, parallel_bdi, Species, Model, - The
rule
statement embeds statements:
-
name
(string), (omissible) : Indicates the name of the experiment to run -
of
(string): Indicates the model containing the experiment to run -
core
(int): Indicates the number of cores to use to run the experiments -
end_cycle
(int): Indicates the cycle at which the experiment should stop -
seed
(int): Provides a predetermined seed instead of letting GAMA choose one -
with_output
(map): This needs to be docummented -
with_param
(map): The parameters to pass to the new experiment
- The
run
statement is of type: Sequence of statements or action - The
run
statement can be embedded into: Behavior, Single statement, Species, Model, - The
run
statement embeds statements:
-
name
(an identifier), (omissible) :
declare the actions an agent execute when enforcing norms of others during a perception
- The
sanction
statement is of type: Behavior - The
sanction
statement can be embedded into: Species, Model, - The
sanction
statement embeds statements:
-
data
(any type), (omissible) : the data that will be saved to the file or the file itself to save when data is used in its simplest form -
attributes
(any type in [map, list]): Allows to specify the attributes of a shape file or GeoJson file where agents are saved. Can be expressed as a list of string or as a literal map. When expressed as a list, each value should represent the name of an attribute of the shape or agent. The keys of the map are the names of the attributes that will be present in the file, the values are whatever expressions neeeded to define their value. -
buffering
(string): Allows to specify a buffering strategy to write the file. Accepted values areper_cycle
andper_simulation
,no_buffering
. In the case ofper_cycle
orper_simulation
, all the write operations in the simulation which used these values would be executed all at once at the end of the cycle or simulation while keeping the initial order. In case of 'per_agent' all operations will be released when the agent is killed (or the simulation ends). Those strategies can be used to optimise a simulation's execution time on models that extensively write in files. Theno_buffering
(which is the system's default) will directly write into the file. -
crs
(any type): the name of the projection, e.g. crs:"EPSG:4326" or its EPSG id, e.g. crs:4326. Here a list of the CRS codes (and EPSG id): http://spatialreference.org -
format
(string): a string representing the format of the output file (e.g. "shp", "asc", "geotiff", "png", "text", "csv"). If the file extension is non ambiguous in facet 'to:', this format does not need to be specified. However, in many cases, it can be useful to do it (for instance, when saving a string to a .pgw file, it is always better to clearly indicate that the expected format is 'text'). -
header
(boolean): an expression that evaluates to a boolean, specifying whether the save will write a header if the file does not exist -
rewrite
(boolean): a boolean expression specifying whether to erase the file if it exists or append data at the end of it. Only applicable to "text" or "csv" files. Default is true -
to
(string): an expression that evaluates to an string, the path to the file, or directly to a file
Allows to save data in a file.
- Its simple syntax is:
save data to: output_file format: a_file_format;
- To save data in a text file:
save (string(cycle) + "->" + name + ":" + location) to: "save_data.txt" format: "text";
- To save the values of some attributes of the current agent in csv file:
save [name, location, host] to: "save_data.csv" format: "csv";
- To save the values of all attributes of all the agents of a species into a csv (with optional attributes):
save species_of(self) to: "save_csvfile.csv" format: "csv" header: false;
- To save the geometries of all the agents of a species into a shapefile (with optional attributes):
save species_of(self) to: "save_shapefile.shp" format: "shp" attributes: ['nameAgent'::name, 'locationAgent'::location] crs: "EPSG:4326";
- To save the grid_value attributes of all the cells of a grid into an ESRI ASCII Raster file:
save grid to: "save_grid.asc" format: "asc";
- To save the grid_value attributes of all the cells of a grid into geotiff:
save grid to: "save_grid.tif" format: "geotiff";
- To save the grid_value attributes of all the cells of a grid into png (with a worldfile):
save grid to: "save_grid.png" format: "image";
- The save statement can be use in an init block, a reflex, an action or in a user command. Do not use it in experiments.
- The
save
statement is of type: Single statement - The
save
statement can be embedded into: Behavior, Sequence of statements or action, - The
save
statement embeds statements:
-
name
(any type), (omissible) : the name of an existing variable or attribute to be modified -
value
(any type): the value to affect to the variable or attribute
Allows to assign a value to the variable or attribute specified
- The
set
statement is of type: Single statement - The
set
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, - The
set
statement embeds statements:
The setup statement is used to define the set of instructions that will be executed before every [#test test].
- As every test should be independent from the others, the setup will mainly contain initialization of variables that will be used in each test.
species Tester {
int val_to_test;
setup {
val_to_test <- 0;
}
test t1 {
// [set of instructions, including asserts]
}
}
- The
setup
statement is of type: Sequence of statements or action - The
setup
statement can be embedded into: Species, Experiment, Model, - The
setup
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
outputs
(list): The list of output variables to analyse through sobol indexes -
report
(string): The path to the file where the Sobol report will be written -
sample
(an identifier): The size of the sample for the sobol sequence -
path
(string): The path to the saltelli sample csv file. If the file doesn't exist automatic Saltelli sampling will be performed and saved in the corresponding location -
results
(string): The path to the file where the automatic batch report will be written
This algorithm runs a Sobol exploration - it has been built upon the moea framework at https://github.com/MOEAFramework/MOEAFramework - disabled the repeat facet of the experiment
- For example:
method sobol sample_size:100 outputs:['my_var'] report:'../path/to/report/file.txt';
- The
sobol
statement is of type: Batch method - The
sobol
statement can be embedded into: Experiment, - The
sobol
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the socialize statement -
agent
(agent): the agent value of the created social link -
dominance
(float): the dominance value of the created social link -
familiarity
(float): the familiarity value of the created social link -
liking
(float): the appreciation value of the created social link -
solidarity
(float): the solidarity value of the created social link -
trust
(float): the trust value of the created social link -
when
(boolean): A boolean value to socialize only with a certain condition
enables to directly add a social link from a perceived agent.
- Other examples of use:
do socialize;
- The
socialize
statement is of type: Single statement - The
socialize
statement can be embedded into: Behavior, Sequence of statements or action, - The
socialize
statement embeds statements:
-
equation
(an identifier), (omissible) : the equation system identifier to be numerically solved -
max_step
(float): maximal step, (used with dp853 method only), (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this value -
method
(string): integration method (can be one of "Euler", "ThreeEighthes", "Midpoint", "Gill", "Luther", "rk4" or "dp853", "AdamsBashforth", "AdamsMoulton", "DormandPrince54", "GraggBulirschStoer", "HighamHall54") (default value: "rk4") or the corresponding constant -
min_step
(float): minimal step, (used with dp853 method only), (sign is irrelevant, regardless of integration direction, forward or backward), the last step can be smaller than this value -
nSteps
(float): Adams-Bashforth and Adams-Moulton methods only. The number of past steps used for computation excluding the one being computed (default value: 2 -
scalAbsoluteTolerance
(float): allowed absolute error (used with dp853 method only) -
scalRelativeTolerance
(float): allowed relative error (used with dp853 method only) -
step_size
(float): integration step, use with fixed step integrator methods (default value: 0.005*step) -
t0
(float): the first bound of the integration interval (defaut value: cycle*step, the time at the begining of the current cycle.) -
tf
(float): the second bound of the integration interval. Can be smaller than t0 for a backward integration (defaut value: cycle*step, the time at the begining of the current cycle.)
Solves all equations which matched the given name, with all systems of agents that should solved simultaneously.
- Other examples of use:
solve SIR method: #rk4 step_size:0.001;
- The
solve
statement is of type: Single statement - The
solve
statement can be embedded into: Behavior, Sequence of statements or action, - The
solve
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the species -
cell_height
(float): (grid only), the height of the cells of the grid -
cell_width
(float): (grid only), the width of the cells of the grid -
compile
(boolean): -
control
(skill): defines the architecture of the species (e.g. fsm...) -
edge_species
(species): In the case of a species defining a graph topology for its instances (nodes of the graph), specifies the species to use for representing the edges -
file
(file): (grid only), a bitmap file that will be loaded at runtime so that the value of each pixel can be assigned to the attribute 'grid_value' -
files
(list): (grid only), a list of bitmap file that will be loaded at runtime so that the value of each pixel of each file can be assigned to the attribute 'bands' -
frequency
(int): The execution frequency of the species (default value: 1). For instance, if frequency is set to 10, the population of agents will be executed only every 10 cycles. -
height
(int): (grid only), the height of the grid (in terms of agent number) -
horizontal_orientation
(boolean): (hexagonal grid only),(true by default). Allows use a hexagonal grid with a horizontal or vertical orientation. -
mirrors
(any type in [list, species]): The species this species is mirroring. The population of this current species will be dependent of that of the species mirrored (i.e. agents creation and death are entirely taken in charge by GAMA with respect to the demographics of the species mirrored). In addition, this species is provided with an attribute called 'target', which allows each agent to know which agent of the mirrored species it is representing. -
neighbors
(int): (grid only), the chosen neighborhood (4, 6 or 8) -
optimizer
(string): (grid only),("A*" by default). Allows to specify the algorithm for the shortest path computation ("BF", "Dijkstra", "A*" or "JPS*" -
parallel
(any type in [boolean, int]): (experimental) setting this facet to 'true' will allow this species to use concurrency when scheduling its agents; setting it to an integer will set the threshold under which they will be run sequentially (the default is initially 20, but can be fixed in the preferences). This facet has a default set in the preferences (Under Performances > Concurrency) -
parent
(species): the parent class (inheritance) -
schedules
(container): A container of agents (a species, a dynamic list, or a combination of species and containers) , which represents which agents will be actually scheduled when the population is scheduled for execution. Note that the world (or the simulation) is always scheduled first, so there is no need to explicitly mention it. Doing so would result in a runtime error. For instance, 'species a schedules: (10 among a)' will result in a population that schedules only 10 of its own agents every cycle. 'species b schedules: []' will prevent the agents of 'b' to be scheduled. Note that the scope of agents covered here can be larger than the population, which allows to build complex scheduling controls; for instance, defining 'global schedules: [] {...} species b schedules: []; species c schedules: b; ' allows to simulate a model where only the world and the agents of b are scheduled, without even having to create an instance of c. -
skills
(list): The list of skills that will be made available to the instances of this species. Each new skill provides attributes and actions that will be added to the ones defined in this species -
topology
(topology): The topology of the population of agents defined by this species. In case of nested species, it can for example be the shape of the macro-agent. In case of grid or graph species, the topology is automatically computed and cannot be redefined -
torus
(boolean): is the topology toric (defaut: false). Needs to be defined on the global species. -
use_individual_shapes
(boolean): (grid only),(true by default). Allows to specify whether or not the agents of the grid will have distinct geometries. If set to false, they will all have simpler proxy geometries -
use_neighbors_cache
(boolean): (grid only),(true by default). Allows to turn on or off the use of the neighbors cache used for grids. Note that if a diffusion of variable occurs, GAMA will emit a warning and automatically switch to a caching version -
use_regular_agents
(boolean): (grid only),(true by default). Allows to specify if the agents of the grid are regular agents (like those of any other species) or minimal ones (which can't have sub-populations, can't inherit from a regular species, etc.) -
virtual
(boolean): whether the species is virtual (cannot be instantiated, but only used as a parent) (false by default) -
width
(int): (grid only), the width of the grid (in terms of agent number)
The species statement allows modelers to define new species in the model. global
and grid
are speciel cases of species: global
being the definition of the global agent (which has automatically one instance, world) and grid
being a species with a grid topology.
- Here is an example of a species definition with a FSM architecture and the additional skill moving:
species ant skills: [moving] control: fsm { }
- In the case of a species aiming at mirroring another one:
species node_agent mirrors: list(bug) parent: graph_node edge_species: edge_agent { }
- The definition of the single grid of a model will automatically create gridwidth x gridheight agents:
grid ant_grid width: gridwidth height: gridheight file: grid_file neighbors: 8 use_regular_agents: false { }
- Using a file to initialize the grid can replace width/height facets:
grid ant_grid file: grid_file neighbors: 8 use_regular_agents: false { }
- The
species
statement is of type: Species - The
species
statement can be embedded into: Model, Environment, Species, - The
species
statement embeds statements:
-
species
(species), (omissible) : the species to be displayed -
aspect
(an identifier): the name of the aspect that should be used to display the species -
fading
(boolean): Used in conjunction with 'trace:', allows to apply a fading effect to the previous traces. Default is false -
position
(point): position of the upper-left corner of the layer. Note that if coordinates are in [0,1[, the position is relative to the size of the environment (e.g. {0.5,0.5} refers to the middle of the display) whereas it is absolute when coordinates are greater than 1 for x and y. The z-ordinate can only be defined between 0 and 1. The position can only be a 3D point {0.5, 0.5, 0.5}, the last coordinate specifying the elevation of the layer. In case of negative value OpenGl will position the layer out of the environment. -
refresh
(boolean): (openGL only) specify whether the display of the species is refreshed. (true by default, usefull in case of agents that do not move) -
rotate
(float): Defines the angle of rotation of this layer, in degrees, around the z-axis. -
selectable
(boolean): Indicates whether the agents present on this layer are selectable by the user. Default is true -
size
(point): extent of the layer in the screen from its position. Coordinates in [0,1[ are treated as percentages of the total surface, while coordinates > 1 are treated as absolute sizes in model units (i.e. considering the model occupies the entire view). Like in 'position', an elevation can be provided with the z coordinate, allowing to scale the layer in the 3 directions -
trace
(any type in [boolean, int]): Allows to aggregate the visualization of agents at each timestep on the display. Default is false. If set to an int value, only the last n-th steps will be visualized. If set to true, no limit of timesteps is applied. -
transparency
(float): the transparency level of the layer (between 0 -- opaque -- and 1 -- fully transparent) -
visible
(boolean): Defines whether this layer is visible or not
The species_layer
statement is used using the species keyword
. It allows modeler to display all the agent of a given species in the current display. In particular, modeler can choose the aspect used to display them.
- The general syntax is:
display my_display {
species species_name [additional options];
}
- Species can be superposed on the same plan (be careful with the order, the last one will be above all the others):
display my_display {
species agent1 aspect: base;
species agent2 aspect: base;
species agent3 aspect: base;
}
- Each species layer can be placed at a different z value using the opengl display. position:{0,0,0} means the layer will be placed on the ground and position:{0,0,1} means it will be placed at an height equal to the maximum size of the environment.
display my_display type: opengl{
species agent1 aspect: base ;
species agent2 aspect: base position:{0,0,0.5};
species agent3 aspect: base position:{0,0,1};
}
- The
species_layer
statement is of type: Layer - The
species_layer
statement can be embedded into: display, species_layer, - The
species_layer
statement embeds statements: species_layer,
-
name
(string), (omissible) : The name of the experiment to run -
of
(string): The path to the model containing the experiment -
seed
(int): The seed to use for initializing the random number generator of the new experiment -
with_param
(map): The parameters to pass to the new experiment
- The
start_simulation
statement is of type: Sequence of statements or action - The
start_simulation
statement can be embedded into: Behavior, Single statement, Species, Model, - The
start_simulation
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the state -
final
(boolean): specifies whether the state is a final one (i.e. there is no transition from this state to another state) (default value= false) -
initial
(boolean): specifies whether the state is the initial one (default value = false)
A state, like a reflex, can contains several statements that can be executed at each time step by the agent.
- Here is an exemple integrating 2 states and the statements in the FSM architecture:
state s_init initial: true {
enter {
write "Enter in" + state;
}
write state;
transition to: s1 when: (cycle > 2) {
write "transition s_init -> s1";
}
exit {
write "EXIT from "+state;
}
}
state s1 {
enter {write 'Enter in '+state;}
write state;
exit {write 'EXIT from '+state;}
}
- See also: enter, exit, transition,
- The
state
statement is of type: Behavior - The
state
statement can be embedded into: fsm, Species, Experiment, Model, - The
state
statement embeds statements: enter, exit,
-
message
(any type), (omissible) : Allows to display a necessarily short message in the status box in the upper left corner. No formatting characters (carriage returns, tabs, or Unicode characters) should be used, but a background color can be specified. The message will remain in place until it is replaced by another one or by nil, in which case the standard status (number of cycles) will be displayed again -
color
(rgb): The color used for displaying the background of the status message
The statement makes the agent output an arbitrary message in the status box.
- Outputting a message
status ("This is my status " + self) color: #yellow;
- The
status
statement is of type: Single statement - The
status
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
status
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
outputs
(list): The list of output variables to analyse -
report
(string): The path to the file where the Sobol report will be written -
iterations
(int): The number of iteration for orthogonal sampling, 5 by default -
results
(string): The path to the file where the automatic batch report will be written -
sample
(int): The number of sample required , 10 by default -
sampling
(an identifier): The sampling method to build parameters sets. Available methods are: latinhypercube, orthogonal, factorial, uniform, saltelli, morris
This algorithm runs an exploration with a given sampling to compute a Stochasticity Analysis
- For example:
method stochanalyse sampling:'latinhypercube' outputs:['my_var'] replicat:10 report:'../path/to/report/file.txt';
- The
stochanalyse
statement is of type: Batch method - The
stochanalyse
statement can be embedded into: Experiment, - The
stochanalyse
statement embeds statements:
-
value
(any type), (omissible) : an expression
The "switch... match" statement is a powerful replacement for imbricated "if ... else ..." constructs. All the blocks that match are executed in the order they are defined, unless one invokes 'break', in which case the switch statement is exited. The block prefixed by default is executed only if none have matched (otherwise it is not).
- The prototypical syntax is as follows:
switch an_expression {
match value1 {...}
match_one [value1, value2, value3] {...}
match_between [value1, value2] {...}
default {...}
}
- Example:
switch 3 {
match 1 {write "Match 1"; }
match 2 {write "Match 2"; }
match 3 {write "Match 3"; }
match_one [4,4,6,3,7] {write "Match one_of"; }
match_between [2, 4] {write "Match between"; }
default {write "Match Default"; }
}
- The
switch
statement is of type: Sequence of statements or action - The
switch
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
switch
statement embeds statements: default, match,
-
name
(an identifier), (omissible) : The name of the method. For internal use only -
aggregation
(a label), takes values in: {min, max, avr}: the agregation method -
init_solution
(map): init solution: key: name of the variable, value: value of the variable -
iter_max
(int): number of iterations. this number corresponds to the number of "moves" in the parameter space. For each move, the algorithm will test the whole neighborhood of the current solution, each neighbor corresponding to a particular set of parameters and thus to a run. Thus, there can be several runs per iteration (maximum: 2^(number of parameters)). -
maximize
(float): the value the algorithm tries to maximize -
minimize
(float): the value the algorithm tries to minimize -
tabu_list_size
(int): size of the tabu list
This algorithm is an implementation of the Tabu Search algorithm. See the wikipedia article and [batch161 the batch dedicated page].
- As other batch methods, the basic syntax of the tabu statement uses
method tabu
instead of the expectedtabu name: id
:
method tabu [facet: value];
- For example:
method tabu iter_max: 50 tabu_list_size: 5 maximize: food_gathered;
- The
tabu
statement is of type: Batch method - The
tabu
statement can be embedded into: Experiment, - The
tabu
statement embeds statements:
-
name
(an identifier), (omissible) : the identifier of the task -
weight
(float): the priority level of the task
As reflex, a task is a sequence of statements that can be executed, at each time step, by the agent. If an agent owns several tasks, the scheduler chooses a task to execute based on its current priority weight value.
- The
task
statement is of type: Behavior - The
task
statement can be embedded into: weighted_tasks, sorted_tasks, probabilistic_tasks, Species, Experiment, Model, - The
task
statement embeds statements:
-
name
(an identifier), (omissible) : identifier of the test
The test statement allows modeler to define a set of assertions that will be tested. Before the execution of the embedded set of instructions, if a setup is defined in the species, model or experiment, it is executed. In a test, if one assertion fails, the evaluation of other assertions continue.
- An example of use:
species Tester {
// set of attributes that will be used in test
setup {
// [set of instructions... in particular initializations]
}
test t1 {
// [set of instructions, including asserts]
}
}
- The
test
statement is of type: Behavior - The
test
statement can be embedded into: Species, Experiment, Model, - The
test
statement embeds statements: assert,
-
message
(any type), (omissible) : the text to display. -
background
(rgb): The color of the background of the text -
category
(a label): a category label, used to group parameters in the interface -
color
(rgb): The color with wich the text will be displayed -
font
(any type in [font, string]): the font used to draw the text, which can be built with the operator "font". ex : font:font("Helvetica", 20 , #bold)
The statement makes an experiment display text in the parameters view.
- The
text
statement is of type: Single statement - The
text
statement can be embedded into: Experiment, - The
text
statement embeds statements:
All the statements executed in the trace statement are displayed in the console.
- The
trace
statement is of type: Sequence of statements or action - The
trace
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
trace
statement embeds statements:
-
to
(an identifier): the identifier of the next state -
when
(boolean), (omissible) : a condition to be fulfilled to have a transition to another given state
In an FSM architecture, transition
specifies the next state of the life cycle. The transition occurs when the condition is fulfilled. The embedded statements are executed when the transition is triggered.
- In the following example, the transition is executed when after 2 steps:
state s_init initial: true {
write state;
transition to: s1 when: (cycle > 2) {
write "transition s_init -> s1";
}
}
- The
transition
statement is of type: Sequence of statements or action - The
transition
statement can be embedded into: Sequence of statements or action, Behavior, - The
transition
statement embeds statements:
Allows the agent to execute a sequence of statements and to catch any runtime error that might happen in a subsequent catch
block, either to ignore it (not a good idea, usually) or to safely stop the model
- The generic syntax is:
try {
[statements]
}
- Optionally, the statements to execute when a runtime error happens in the block can be defined in a following statement 'catch'. The syntax then becomes:
try {
[statements]
}
catch {
[statements]
}
- The
try
statement is of type: Sequence of statements or action - The
try
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
try
statement embeds statements: catch,
-
emotion
(emotion): the emotion that will be copied with the contagion -
name
(an identifier), (omissible) : the identifier of the unconscious contagion -
charisma
(float): The charisma value of the perceived agent (between 0 and 1) -
decay
(float): The decay value of the emotion added to the agent -
receptivity
(float): The receptivity value of the current agent (between 0 and 1) -
threshold
(float): The threshold value to make the contagion -
when
(boolean): A boolean value to get the emotion only with a certain condition
enables to directly copy an emotion present in the perceived species.
- Other examples of use:
unconscious_contagion emotion:fearConfirmed;
unconscious_contagion emotion:fearConfirmed charisma: 0.5 receptivity: 0.5;
- The
unconscious_contagion
statement is of type: Single statement - The
unconscious_contagion
statement can be embedded into: Behavior, Sequence of statements or action, - The
unconscious_contagion
statement embeds statements:
-
name
(a label), (omissible) : the identifier of the user_command -
action
(action): the identifier of the action to be executed. This action should be accessible in the context in which the user_command is defined (an experiment, the global section or a species). A special case is allowed to maintain the compatibility with older versions of GAMA, when the user_command is declared in an experiment and the action is declared in 'global'. In that case, all the simulations managed by the experiment will run the action in response to the user executing the command -
category
(string): a category label, used to group parameters in the interface -
color
(rgb): The color of the button to display -
continue
(boolean): Whether or not the button, when clicked, should dismiss the user panel it is defined in. Has no effect in other contexts (menu, parameters, inspectors) -
when
(boolean): the condition that should be fulfilled (in addition to the user clicking it) in order to execute this action -
with
(map): the map of the parameters::values required by the action
Anywhere in the global block, in a species or in an (GUI) experiment, user_command statements allows to either call directly an existing action (with or without arguments) or to be followed by a block that describes what to do when this command is run.
- The general syntax is for example:
user_command kill_myself action: some_action with: [arg1::val1, arg2::val2, ...];
- See also: user_init, user_panel, user_input,
- The
user_command
statement is of type: Sequence of statements or action - The
user_command
statement can be embedded into: user_panel, Species, Experiment, Model, - The
user_command
statement embeds statements: user_input,
-
name
(an identifier), (omissible) : The name of the panel -
initial
(boolean): Whether or not this panel will be the initial one
Used in the user control architecture, user_init is executed only once when the agent is created. It opens a special panel (if it contains user_commands statements). It is the equivalent to the init block in the basic agent architecture.
- See also: user_command, user_init, user_input,
- The
user_init
statement is of type: Behavior - The
user_init
statement can be embedded into: Species, Experiment, Model, - The
user_init
statement embeds statements: user_panel,
-
init
(any type): the init value -
returns
(a new identifier): a new local variable containing the value given by the user -
name
(a label), (omissible) : the displayed name -
among
(list): the set of acceptable values, only for string inputs -
max
(float): the maximum value -
min
(float): the minimum value -
slider
(boolean): Whether to display a slider or not when applicable -
type
(a datatype identifier): the variable type
It allows to let the user define the value of a variable.
- Other examples of use:
user_panel "Advanced Control" {
user_input "Location" returns: loc type: point <- {0,0};
create cells number: 10 with: [location::loc];
}
- See also: user_command, user_init, user_panel,
- The
user_input
statement is of type: Single statement - The
user_input
statement can be embedded into: user_command, - The
user_input
statement embeds statements:
-
name
(an identifier), (omissible) : The name of the panel -
initial
(boolean): Whether or not this panel will be the initial one
It is the basic behavior of the user control architecture (it is similar to state for the FSM architecture). This user_panel translates, in the interface, in a semi-modal view that awaits the user to choose action buttons, change attributes of the controlled agent, etc. Each user_panel, like a state in FSM, can have a enter and exit sections, but it is only defined in terms of a set of user_commands which describe the different action buttons present in the panel.
- The general syntax is for example:
user_panel default initial: true {
user_input 'Number' returns: number type: int <- 10;
ask (number among list(cells)){ do die; }
transition to: "Advanced Control" when: every (10);
}
user_panel "Advanced Control" {
user_input "Location" returns: loc type: point <- {0,0};
create cells number: 10 with: [location::loc];
}
- See also: user_command, user_init, user_input,
- The
user_panel
statement is of type: Behavior - The
user_panel
statement can be embedded into: fsm, user_first, user_last, user_init, user_only, Species, Experiment, Model, - The
user_panel
statement embeds statements: user_command,
-
topology
(topology), (omissible) : the topology
using
is a statement that allows to set the topology to use by its sub-statements. They can gather it by asking the scope to provide it.
- All the spatial operations are topology-dependent (e.g. neighbors are not the same in a continuous and in a grid topology). So
using
statement allows modelers to specify the topology in which the spatial operation will be computed.
float dist <- 0.0;
using topology(grid_ant) {
d (self.location distance_to target.location);
}
- The
using
statement is of type: Sequence of statements or action - The
using
statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer, - The
using
statement embeds statements:
-
name
(a new identifier), (omissible) : The name of the attribute -
<-
(any type): The initial value of the attribute. Same as init: -
->
(any type in [int, float, point, date]): Used to specify an expression that will be evaluated each time the attribute is accessed. Equivalent to 'function:'. This facet is incompatible with both 'init:' and 'update:' and 'on_change:' (or the equivalent final block) -
const
(boolean): Indicates whether this attribute can be subsequently modified or not -
function
(any type): Used to specify an expression that will be evaluated each time the attribute is accessed. Equivalent to '->'. This facet is incompatible with both 'init:', 'update:' and 'on_change:' (or the equivalent final block) -
index
(a datatype identifier): The type of the key used to retrieve the contents of this attribute -
init
(any type): The initial value of the attribute. Same as <- -
of
(a datatype identifier): The type of the contents of this container attribute -
on_change
(any type): Provides a block of statements that will be executed whenever the value of the attribute changes -
type
(a datatype identifier): The type of the attribute -
update
(any type): An expression that will be evaluated each cycle to compute a new value for the attribute
Declaration of an attribute of a species or an experiment
- The
Variable_container
statement is of type: Variable (container) - The
Variable_container
statement can be embedded into: Species, Experiment, Model, - The
Variable_container
statement embeds statements:
-
name
(a new identifier), (omissible) : The name of the attribute -
<-
(any type in [int, float, point, date]): The initial value of the attribute. Same as 'init:' -
->
(any type in [int, float, point, date]): Used to specify an expression that will be evaluated each time the attribute is accessed. Equivalent to 'function:'. This facet is incompatible with both 'init:' and 'update:' and 'on_change:' (or the equivalent final block) -
among
(list): A list of constant values among which the attribute can take its value -
const
(boolean): Indicates whether this attribute can be subsequently modified or not -
function
(any type in [int, float, point, date]): Used to specify an expression that will be evaluated each time the attribute is accessed. Equivalent to '->'. This facet is incompatible with both 'init:' and 'update:' -
init
(any type in [int, float, point, date]): The initial value of the attribute. Same as '<-' -
max
(any type in [int, float, point, date]): The maximum value this attribute can take. The value will be automatically clampled if it is higher. -
min
(any type in [int, float, point, date]): The minimum value this attribute can take. The value will be automatically clamped if it is lower. -
on_change
(any type): Provides a block of statements that will be executed whenever the value of the attribute changes -
step
(any type in [int, float, point, date]): A discrete step (used in conjunction with min and max) that constrains the values this variable can take -
type
(a datatype identifier): The type of the attribute, either 'int', 'float', 'point' or 'date' -
update
(any type in [int, float, point, date]): An expression that will be evaluated each cycle to compute a new value for the attribute
Declaration of an attribute of a species or an experiment; this type of attributes accepts min:, max: and step: facets, automatically clamping the value if it is lower than min or higher than max.
- The
Variable_number
statement is of type: Variable (number) - The
Variable_number
statement can be embedded into: Species, Experiment, Model, - The
Variable_number
statement embeds statements:
-
name
(a new identifier), (omissible) : The name of the attribute -
<-
(any type): The initial value of the attribute. Same as init: -
->
(any type in [int, float, point, date]): Used to specify an expression that will be evaluated each time the attribute is accessed. Equivalent to 'function:'. This facet is incompatible with both 'init:' and 'update:' and 'on_change:' (or the equivalent final block) -
among
(list): A list of constant values among which the attribute can take its value -
const
(boolean): Indicates whether this attribute can be subsequently modified or not -
function
(any type): Used to specify an expression that will be evaluated each time the attribute is accessed. This facet is incompatible with both 'init:', 'update:' and 'on_change:' (or the equivalent final block) -
index
(a datatype identifier): The type of the index used to retrieve elements if the type of the attribute is a container type -
init
(any type): The initial value of the attribute. Same as <- -
of
(a datatype identifier): The type of the elements contained in the type of this attribute if it is a container type -
on_change
(any type): Provides a block of statements that will be executed whenever the value of the attribute changes -
type
(a datatype identifier): The type of this attribute. Can be combined with facets 'of' and 'index' to describe container types -
update
(any type): An expression that will be evaluated each cycle to compute a new value for the attribute
Declaration of an attribute of a species or an experiment
- The
Variable_regular
statement is of type: Variable (regular) - The
Variable_regular
statement can be embedded into: Species, Experiment, Model, - The
Variable_regular
statement embeds statements:
-
message
(string), (omissible) : the message to display as a warning.
The statement makes the agent output an arbitrary message in the error view as a warning.
- Emmitting a warning
warn "This is a warning from " + self;
- The
warn
statement is of type: Single statement - The
warn
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
warn
statement embeds statements:
-
message
(any type), (omissible) : the message to display. Modelers can add some formatting characters to the message (carriage returns, tabs, or Unicode characters), which will be used accordingly in the console. -
buffering
(string): Allows to specify a buffering strategy to write in the console. Accepted values areper_cycle
andper_simulation
,no_buffering
. In the case ofper_cycle
orper_simulation
, all the write operations in the simulation which used these values would be executed all at once at the end of the cycle or simulation while keeping the initial order. In case of 'per_agent' all operations will be released when the agent is killed (or the simulation ends). Those strategies can be used to optimise a simulation's execution time on models that extensively write in files. Theno_buffering
(which is the system's default) will directly write into the file. -
color
(rgb): The color with wich the message will be displayed. Note that different simulations will have different (default) colors to use for this purpose if this facet is not specified -
end
(string): The string to be appened at the end of the message. By default it's a new line character: '\n' or '\r\n' depending on the operating system.
The statement makes the agent output an arbitrary message in the console.
- Outputting a message
write "This is a message from " + self;
- The
write
statement is of type: Single statement - The
write
statement can be embedded into: Behavior, Sequence of statements or action, Layer, - The
write
statement embeds statements: