Statements
This file is automatically generated from java files. Do Not Edit It.
Table of Contents​
=, action, add, agents, annealing, ask, aspect, assert, benchmark, break, camera, capture, catch, chart, conscious_contagion, coping, create, data, datalist, default, diffuse, display, display_grid, display_population, do, draw, else, emotional_contagion, enforcement, enter, equation, error, event, exhaustive, exit, experiment, focus, focus_on, genetic, graphics, highlight, hill_climbing, if, image, inspect, law, layout, let, light, loop, match, migrate, monitor, norm, output, output_file, overlay, parameter, perceive, permanent, plan, put, reactive_tabu, reflex, release, remove, return, rule, rule, run, sanction, save, set, setup, simulate, socialize, solve, species, start_simulation, state, status, switch, tabu, task, test, trace, transition, try, unconscious_contagion, user_command, user_init, user_input, user_panel, using, Variable_container, Variable_number, Variable_regular, warn, write,
Statements by kinds​
- Batch method
- Behavior
- Behavior
- Experiment
- Layer
- Output
- Parameter
- Sequence of statements or action
- Sequence of statements or action
- Sequence of statements or action
- Sequence of statements or action
- Single statement
- Single statement
- Single statement
- Single statement
- Species
- Variable (container)
- Variable (number)
- Variable (regular)
Statements by embedment​
- 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, return, run, save, set, simulate, socialize, solve, start_simulation, status, switch, trace, transition, try, unconscious_contagion, using, warn, write,
- Environment
- Experiment
- Layer
- Model
- action, aspect, coping, equation, experiment, law, norm, output, perceive, plan, reflex, rule, rule, run, sanction, setup, species, start_simulation, state, task, test, user_command, user_init, user_panel, Variable_container, Variable_number, Variable_regular,
- Sequence of statements or action
- add, ask, assert, assert, benchmark, break, capture, conscious_contagion, create, data, datalist, diffuse, do, draw, emotional_contagion, enforcement, error, focus, focus_on, highlight, if, inspect, let, loop, migrate, put, release, remove, return, save, set, simulate, socialize, solve, status, switch, trace, transition, try, unconscious_contagion, using, warn, write,
- Single statement
- Species
- action, aspect, coping, equation, law, norm, perceive, plan, reflex, rule, rule, run, sanction, setup, simulate, species, start_simulation, state, task, test, user_command, user_init, user_panel, Variable_container, Variable_number, Variable_regular,
- action
- aspect
- draw,
- chart
- display
- display_population
- equation
- =,
- fsm
- if
- else,
- output
- parallel_bdi
- permanent
- probabilistic_tasks
- task,
- rules
- rule,
- simple_bdi
- sorted_tasks
- task,
- state
- switch
- test
- try
- user_command
- user_first
- user_init
- user_last
- user_only
- user_panel
- weighted_tasks
- task,
General syntax​
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...;
}
=
Facets​
right
(float), (omissible) : the right part of the equation (it is mandatory that it can be evaluated as a floatleft
(any type): the left part of the equation (it should be a variable or a call to the diff() or diff2() operators)
Definition​
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.
Usages​
- 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);
}
Embedments​
- The
=
statement is of type: Single statement - The
=
statement can be embedded into: equation, - The
=
statement embeds statements:
action​
Facets​
name
(an identifier), (omissible) : identifier of the actionindex
(a datatype identifier): if the action returns a map, the type of its keysof
(a datatype identifier): if the action returns a container, the type of its elementstype
(a datatype identifier): the action returned typevirtual
(boolean): whether the action is virtual (defined without a set of instructions) (false by default)
Definition​
Allows to define in a species, model or experiment a new action that can be called elsewhere.
Usages​
- 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,
Embedments​
- 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,
add​
Facets​
to
(any type in [container, species, agent, geometry]): an expression that evaluates to a containeritem
(any type), (omissible) : any expression to add in the containerall
(any type): Allows to either pass a container so as to add all its element, or 'true', if the item to add is already a container.at
(any type): position in the container of added element
Definition​
Allows to add, i.e. to insert, a new element in a container (a list, matrix, map, ...).Incorrect use: The addition of a new element at a position out of the bounds of the container will produce a warning and let the container unmodified. If all: is specified, it has no effect if its argument is not a container, or if its argument is 'true' and the item to add is not a container. In that latter case
Usages​
- The new element can be added either at the end of the container or at a particular position.
add expr to: expr_container; // Add at the end
add expr at: expr to: expr_container; // Add at position expr
- Case of a list, the expression in the facet at: should be an integer.
list<int> workingList <- [];add 0 at: 0 to: workingList ;//workingList equals [0]add 10 at: 0 to: workingList ;//workingList equals [10,0]add 20 at: 2 to: workingList ;//workingList equals [10,0,20]add 50 to: workingList;//workingList equals [10,0,20,50]add [60,70] all: true to: workingList;//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 <- [];add "val1" at: "x" to: workingMap;//workingMap equals ["x"::"val1"]
- If the at facet is omitted, 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: in this case the pair is added.
- 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.
- On a map, the all facet will add all value of a container in the map (so as pair val_cont::val_cont)
- In case of a graph, we can use the facets
node
,edge
andweight
to add a node, an edge or weights to the graph. However, these facets are now considered as deprecated, and 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}]);
add edge: {1,5}::{2,3} to: g;
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})]
add node: {5,5} to: g;
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})]
- Case of a matrix: this statement can not be used on matrix. Please refer to the statement put.
- See also: put, remove,
Embedments​
- 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:
agents​
Facets​
value
(container): the set of agents to displayname
(a label), (omissible) : Human readable title of the layeraspect
(an identifier): the name of the aspect that should be used to display the speciesfading
(boolean): Used in conjunction with 'trace:', allows to apply a fading effect to the previous traces. Default is falsefocus
(agent): the agent on which the camera will be focused (it is dynamically computed)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, useful in case of agents that do not move)selectable
(boolean): Indicates whether the agents present on this layer are selectable by the user. Default is truesize
(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 directionstrace
(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)
Definition​
agents
allows the modeler to display only the agents that fulfill a given condition.
Usages​
- 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, overlay, display_population,
Embedments​
- The
agents
statement is of type: Layer - The
agents
statement can be embedded into: display, - The
agents
statement embeds statements:
annealing​
Facets​
name
(an identifier), (omissible) : The name of the method. For internal use onlyaggregation
(a label), takes values in: {min, max}: the agregation methodmaximize
(float): the value the algorithm tries to maximizeminimize
(float): the value the algorithm tries to minimizenb_iter_cst_temp
(int): number of iterations per level of temperaturetemp_decrease
(float): temperature decrease coefficienttemp_end
(float): final temperaturetemp_init
(float): initial temperature
Definition​
This algorithm is an implementation of the Simulated Annealing algorithm. See the wikipedia article and [batch161 the batch dedicated page].
Usages​
- 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;
Embedments​
- The
annealing
statement is of type: Batch method - The
annealing
statement can be embedded into: Experiment, - The
annealing
statement embeds statements:
ask​
Facets​
target
(any type in [container, agent]), (omissible) : an expression that evaluates to an agent or a list of agentsas
(species): an expression that evaluates to a speciesparallel
(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.
Definition​
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.
Usages​
- 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
Embedments​
- 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, - The
ask
statement embeds statements:
aspect​
Facets​
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)
Definition​
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.
Usages​
- 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;
}
}
Embedments​
- The
aspect
statement is of type: Behavior - The
aspect
statement can be embedded into: Species, Model, - The
aspect
statement embeds statements: draw,
assert​
Facets​
value
(boolean), (omissible) : a boolean expression. If its evaluation is true, the assertion is successful. Otherwise, an error (or a warning) is raised.warning
(boolean): if set to true, makes the assertion emit a warning instead of an error
Definition​
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
Usages​
- 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,
Embedments​
- 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:
benchmark​
Facets​
message
(any type), (omissible) : A message to display alongside the results. Should concisely describe the contents of the benchmarkrepeat
(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
Definition​
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
Usages​
Embedments​
- 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:
break​
Facets​
Definition​
break
allows to interrupt the current sequence of statements.
Usages​
Embedments​
- 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:
camera​
Facets​
name
(string), (omissible) : The name of the cameralocation
(point): The location of the camera in the worldlook_at
(point): The location that the camera is lookingup_vector
(point): The up-vector of the camera.
Definition​
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.