Version: 🚧 2024-06 🚧

Statements

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,

Statements by kinds

Batch method
- annealing, betad, exploration, genetic, hill_climbing, morris, pso, reactive_tabu, sobol, stochanalyse, tabu,
Behavior
- abort, aspect, coping, do_rule, init, norm, perceive, plan, reflex, sanction, state, task, test, user_init, user_panel,
Experiment
- experiment,
Layer
- agents, camera, chart, display_grid, event, graphics, image_layer, light, mesh, overlay, rotation, species_layer,
Output
- browse, display, inspect, layout, monitor, output, permanent,
Parameter
- parameter,
Sequence of statements or action
- action, ask, benchmark, capture, catch, create, default, else, enter, equation, exit, if, loop, match, match_between, match_one, match_regex, migrate, release, run, setup, start_simulation, switch, trace, transition, try, user_command, using,
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
- global, grid, species,
Variable (container)
- Variable_container,
Variable (number)
- Variable_number,
Variable (regular)
- 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, restore, return, run, save, set, socialize, solve, start_simulation, status, switch, trace, transition, try, unconscious_contagion, using, warn, write,
Environment
- species,
Experiment
- action, annealing, betad, category, do_rule, exploration, genetic, hill_climbing, morris, output, parameter, permanent, pso, reactive_tabu, reflex, setup, sobol, state, stochanalyse, tabu, task, test, text, user_command, user_init, user_panel, Variable_container, Variable_number, Variable_regular,
Layer
- add, ask, benchmark, do, draw, error, focus_on, highlight, if, let, loop, put, remove, set, status, switch, trace, try, using, warn, write,
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
- ask, if,
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
- run, start_simulation,
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
- assert, return,
aspect
- draw,
chart
- add, ask, data, datalist, do, put, remove, set, using,
display
- agents, camera, chart, display_grid, event, graphics, image_layer, light, mesh, overlay, rotation, species_layer,
equation
- =,
fsm
- state, user_panel,
if
- else,
output
- display, inspect, layout, monitor,
parallel_bdi
- coping, rule,
permanent
- display, inspect, monitor,
probabilistic_tasks
- task,
rules
- do_rule,
simple_bdi
- coping, rule,
sorted_tasks
- task,
species_layer
- species_layer,
state
- enter, exit,
switch
- default, match,
test
- assert,
try
- catch,
user_command
- user_input,
user_first
- user_panel,
user_init
- user_panel,
user_last
- user_panel,
user_only
- user_panel,
user_panel
- user_command,
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...;
}

=

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)

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); 
} 

See also: equation, solve,

Embedments

The = statement is of type: Single statement
The = statement can be embedded into: equation,
The = statement embeds statements:

action

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)

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

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)'

Definition

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; or container <+ 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;)

Usages

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})]

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

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

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_layer, overlay, species_layer,

Embedments

The agents statement is of type: Layer
The agents statement can be embedded into: display,
The agents statement embeds statements:

annealing

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

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 expected annealing 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

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.

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 keyword myself.

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, Layer, Output,
The ask statement embeds statements:

aspect

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

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

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

message (any type), (omissible) : A message to display alongside the results. Should concisely describe the contents of the benchmark
buffering (string): Allows to specify a buffering strategy to write in the console. Accepted values are per_cycle and per_simulation, no_buffering. In the case of per_cycle or per_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. The no_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.
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

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:

betad

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
bootstrap (int): The number of time each parameter value is boostraped (or resampled in another context)
results (string): The path to the file where the automatic batch report will be written
sample (int): The number of sample required.

Definition

This algorithm runs an exploration with a given sampling to compute BetadKu - see doi: 10.1007/s10588-021-09358-5

Usages

For example:

method sobol sample_size:100 outputs:['my_var'] report:'../path/to/report/file.txt'; 

Embedments

The betad statement is of type: Batch method
The betad statement can be embedded into: Experiment,
The betad statement embeds statements:

break

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

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.

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. 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.

Usages

See also: display, agents, chart, event, graphics, display_grid, image_layer, species_layer,

Embedments

The camera statement is of type: Layer
The camera statement can be embedded into: display,
The camera statement embeds statements:

capture

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)

Definition

Allows an agent to capture other agent(s) as its micro-agent(s).

Usages

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,

Embedments

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:

catch

Definition

This statement cannot be used alone

Usages

See also: try,

Embedments

The catch statement is of type: Sequence of statements or action
The catch statement can be embedded into: try,
The catch statement embeds statements:

chart

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).

Definition

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).

Usages

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,

Embedments

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,

conscious_contagion

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

Definition

enables to directly add an emotion of a perceived species if the perceived agent gets a particular emotion.

Usages

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;

Embedments

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

Definition

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.

Usages

Embedments

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:

coping

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):

Definition

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.

Usages

Other examples of use:

coping emotion: new_emotion("fear") when: flip(0.5) new_desire: new_predicate("test");

Embedments

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:

create

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

Definition

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).

Usages

Its simple syntax to create an_int agents of species a_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 attributes type and nature with types corresponding to the types of the shapefile attributes) from a shapefile the_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.

Embedments

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:

data

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)

Definition

This statement allows to describe the values that will be displayed on the chart.

Usages

Embedments

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:

datalist

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)

Definition

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.

Usages

Embedments

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:

default

value (any type), (omissible) : The value or values this statement tries to match

Definition

Used in a switch match structure, the block prefixed by default is executed only if no other block has matched (otherwise it is not).

Usages

See also: switch, match,

Embedments

The default statement is of type: Sequence of statements or action
The default statement can be embedded into: switch,
The default statement embeds statements:

diffuse

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

Definition

This statements allows a value to diffuse among a species on agents (generally on a grid) depending on a given diffusion matrix.

Usages

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;

Embedments

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:

display

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 the camera 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.

Definition

A display refers to an independent and mobile part of the interface that can display species, images, texts or charts.

Usages

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; 
}

Embedments

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,

display_grid

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

Definition

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).

Usages

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; 
}

See also: display, agents, chart, event, graphics, image, overlay, species_layer,

Embedments

The display_grid statement is of type: Layer
The display_grid statement can be embedded into: display,
The display_grid statement embeds statements:

do

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

Definition

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.

Usages

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 of do; 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; 
     ... 
}

Embedments

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:

do_rule

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

Definition

A simple definition of a rule (set of statements which execution depend on a condition and a priority).

Usages

Embedments

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:

draw

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

Definition

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.

Usages

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; 
}

Embedments

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:

else

Definition

This statement cannot be used alone

Usages

See also: if,

Embedments

The else statement is of type: Sequence of statements or action
The else statement can be embedded into: if,
The else statement embeds statements:

emotional_contagion

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

Definition

enables to make conscious or unconscious emotional contagion

Usages

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;

Embedments

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:

enforcement

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

Definition

apply a sanction if the norm specified is violated, or a reward if the norm is applied by the perceived agent

Usages

Other examples of use:

focus var:speed; //where speed is a variable from a species that is being perceived

Embedments

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:

enter

Definition

In an FSM architecture, enter introduces a sequence of statements to execute upon entering a state.

Usages

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,

Embedments

The enter statement is of type: Sequence of statements or action
The enter statement can be embedded into: state,
The enter statement embeds statements:

equation

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

Definition

The equation statement is used to create an equation system from several single equations.

Usages

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,

Embedments

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: =,

error

message (string), (omissible) : the message to display in the error.

Definition

The statement makes the agent output an error dialog (if the simulation contains a user interface). Otherwise displays the error in the console.

Usages

Throwing an error

error 'This is an error raised by ' + self;

Embedments

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:

event

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

Definition

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

Usages

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,

Embedments

The event statement is of type: Layer
The event statement can be embedded into: display,
The event statement embeds statements:

exit

Definition

In an FSM architecture, exit introduces a sequence of statements to execute right before exiting the state.

Usages

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,

Embedments

The exit statement is of type: Sequence of statements or action
The exit statement can be embedded into: state,
The exit statement embeds statements:

experiment

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)

Definition

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.

Usages

Embedments

The experiment statement is of type: Experiment
The experiment statement can be embedded into: Model,
The experiment statement embeds statements:

exploration

name (an identifier), (omissible) : The name of the method. For internal use only
factorial (int): The number of slice (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

Definition

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].

Usages

As other batch methods, the basic syntax of the exploration statement uses method exploration instead of the expected exploration 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]]; 

Embedments

The exploration statement is of type: Batch method
The exploration statement can be embedded into: Experiment,
The exploration statement embeds statements:

focus

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

Definition

enables to directly add a belief from the variable of a perceived species.

Usages

Other examples of use:

focus var:speed /*where speed is a variable from a species that is being perceived*/

Embedments

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:

focus_on

value (any type), (omissible) : The agent, list of agents, geometry to focus on

Definition

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

Usages

Focuses on an agent, a geometry, a set of agents, etc...

focus_on my_species(0);

Embedments

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:

genetic

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)

Definition

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).

Usages

As other batch methods, the basic syntax of the genetic statement uses method genetic instead of the expected genetic 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; 

Embedments

The genetic statement is of type: Batch method
The genetic statement can be embedded into: Experiment,
The genetic statement embeds statements:

graphics

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

Definition

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.

Usages

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,

Embedments

The graphics statement is of type: Layer
The graphics statement can be embedded into: display,
The graphics statement embeds statements:

highlight

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

Definition

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

Usages

Highlighting an agent

highlight my_species(0) color: #blue;

Embedments

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:

hill_climbing

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

Definition

This algorithm is an implementation of the Hill Climbing algorithm. See the wikipedia article and [batch161 the batch dedicated page].

Usages

As other batch methods, the basic syntax of the hill_climbing statement uses method hill_climbing instead of the expected hill_climbing name: id :

method hill_climbing [facet: value];

For example:

method hill_climbing iter_max: 50 maximize : food_gathered; 

Embedments

The hill_climbing statement is of type: Batch method
The hill_climbing statement can be embedded into: Experiment,
The hill_climbing statement embeds statements:

if

condition (boolean), (omissible) : A boolean expression: the condition that is evaluated.

Definition

Allows the agent to execute a sequence of statements if and only if the condition evaluates to true.

Usages

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] 
}

Embedments

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,

image_layer

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

Definition

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.

Usages

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,

Embedments

The image_layer statement is of type: Layer
The image_layer statement can be embedded into: display,
The image_layer statement embeds statements:

inspect

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

Definition

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.

Usages

An example of syntax is:

inspect "my_inspector" value: ant attributes: ["name", "location"];

Embedments

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:

law

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):

Definition

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.

Usages

Other examples of use:

rule belief: new_predicate("test") when: flip(0.5) new_desire: new_predicate("test");

Embedments

The law statement is of type: Single statement
The law statement can be embedded into: Species, Model,
The law statement embeds statements:

layout

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)

Definition

Represents the layout of the display views of simulations and experiments

Usages

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;

Embedments

The layout statement is of type: Output
The layout statement can be embedded into: output,
The layout statement embeds statements:

let

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

Definition

Declaration and initialization of a temporary variable.

Usages

Embedments

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:

light

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}

Definition

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};

Usages

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,

Embedments

The light statement is of type: Layer
The light statement can be embedded into: display,
The light statement embeds statements:

loop

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

Definition

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.

Usages

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

Embedments

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:

match

value (any type), (omissible) : The value or values this statement tries to match

Definition

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

Usages

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]"; } 
}

See also: switch, default,

Embedments

The match statement is of type: Sequence of statements or action
The match statement can be embedded into: switch,
The match statement embeds statements:

mesh

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 a palette (using the corresponding operator), it is used to color each cell based on its value (with interpolation between the colors). When a gradient (see the corresponding operator) is passed, the interpolation between the two extreme colors is computed by GAMA.When a scale (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' to color:). 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 both grayscale and color
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

Definition

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

Usages

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; 
}

See also: display, agents, grid, event, graphics, image, overlay, species_layer,

Embedments

The mesh statement is of type: Layer
The mesh statement can be embedded into: display,
The mesh statement embeds statements:

migrate

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

Definition

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.

Usages

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;

See also: capture, release,

Embedments

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:

monitor

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)

Definition

A monitor allows to follow the value of an arbitrary expression in GAML.

Usages

An example of use is:

monitor "nb preys" value: length(prey as list) refresh_every: 5;  

Embedments

The monitor statement is of type: Output
The monitor statement can be embedded into: output, permanent,
The monitor statement embeds statements:

morris

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

Definition

This algorithm runs a Morris exploration - it has been built upon the SILAB librairy - disabled the repeat facet of the experiment

Usages

For example:

method morris sample_size:100 nb_levels:4 outputs:['my_var'] report:'../path/to/report.txt;

Embedments

The morris statement is of type: Batch method
The morris statement can be embedded into: Experiment,
The morris statement embeds statements:

norm

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

Definition

a norm indicates what action the agent has to do in a certain context and with and obedience value higher than the threshold

Usages

Embedments

The norm statement is of type: Behavior
The norm statement can be embedded into: Species, Model,
The norm statement embeds statements:

output

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

Definition

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.

Usages

Its basic syntax is:

experiment exp_name type: gui { 
   // [inputs] 
   output { 
      // [display, file, inspect, layout or monitor statements] 
   } 
}

See also: display, monitor, inspect, layout,

Embedments

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,

overlay

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

Definition

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.

Usages

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,

Embedments

The overlay statement is of type: Layer
The overlay statement can be embedded into: display,
The overlay statement embeds statements:

parameter

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)

Definition

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.

Usages

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; 

Embedments

The parameter statement is of type: Parameter
The parameter statement can be embedded into: Experiment,
The parameter statement embeds statements:

perceive

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

Definition

Allow the agent, with a bdi architecture, to perceive others agents

Usages

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} 
}

Embedments

The perceive statement is of type: Behavior
The perceive statement can be embedded into: Species, Model,
The perceive statement embeds statements:

permanent

Definition

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.

Usages

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; 
		} 
	} 
}

Embedments

The permanent statement is of type: Output
The permanent statement can be embedded into: Experiment,
The permanent statement embeds statements: display, inspect, monitor,

plan

name (an identifier), (omissible) :
emotion (emotion):
finished_when (boolean):
instantaneous (boolean):
intention (predicate):
priority (float):
threshold (float):
when (boolean):

Definition

define an action plan performed by an agent using the BDI engine

Usages

Embedments

The plan statement is of type: Behavior
The plan statement can be embedded into: Species, Model,
The plan statement embeds statements:

pso

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

Definition

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.

Usages

As other batch methods, the basic syntax of the pso statement uses method pso instead of the expected pso 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; 

Embedments

The pso statement is of type: Batch method
The pso statement can be embedded into: Experiment,
The pso statement embeds statements:

put

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 by container[index]
key (any type): the key or index at which to put the new value is specified by container[index]

Definition

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;)

Usages

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]

Embedments

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:

reactive_tabu

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

Definition

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.

Usages

As other batch methods, the basic syntax of the reactive_tabu statement uses method reactive_tabu instead of the expected reactive_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;

Embedments

The reactive_tabu statement is of type: Batch method
The reactive_tabu statement can be embedded into: Experiment,
The reactive_tabu statement embeds statements:

reflex

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.

Definition

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.

Usages

Example:

reflex my_reflex when: flip (0.5){ 		//Only executed when flip returns true 
    write "Executing the unconditional reflex"; 
}

Embedments

The reflex statement is of type: Behavior
The reflex statement can be embedded into: Species, Experiment, Model,
The reflex statement embeds statements:

release

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)

Definition

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).

Usages

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,

Embedments

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:

remove

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 using container[] instead of container

Definition

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; or container >- element; (classic form: remove element from: container;)
To remove an index/key from a container (other than a matrix) use container[] >> index or container[] >- 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;)

Usages

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 
   } 
} 

This statement can not be used on matrix.
See also: add, put,

Embedments

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:

restore

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

Definition

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');

Usages

Embedments

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:

return

value (any type), (omissible) : an expression that is returned

Definition

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].

Usages

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"  
}

Embedments

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:

rotation

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})

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. 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.

Usages

See also: display, agents, chart, event, graphics, display_grid, image_layer, species_layer,

Embedments

The rotation statement is of type: Layer
The rotation statement can be embedded into: display,
The rotation statement embeds statements:

rule

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):

Definition

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.

Usages

Embedments

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:

run

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

Embedments

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:

sanction

name (an identifier), (omissible) :

Definition

declare the actions an agent execute when enforcing norms of others during a perception

Usages

Embedments

The sanction statement is of type: Behavior
The sanction statement can be embedded into: Species, Model,
The sanction statement embeds statements:

save

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 are per_cycle and per_simulation, no_buffering. In the case of per_cycle or per_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. The no_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

Definition

Allows to save data in a file.

Usages

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.

Embedments

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:

set

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

Definition

Allows to assign a value to the variable or attribute specified

Usages

Embedments

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:

setup

Definition

The setup statement is used to define the set of instructions that will be executed before every [#test test].

Usages

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] 
    } 
}

See also: test, assert,

Embedments

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:

sobol

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

Definition

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

Usages

For example:

method sobol sample_size:100 outputs:['my_var'] report:'../path/to/report/file.txt'; 

Embedments

The sobol statement is of type: Batch method
The sobol statement can be embedded into: Experiment,
The sobol statement embeds statements:

socialize

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

Definition

enables to directly add a social link from a perceived agent.

Usages

Other examples of use:

do socialize;

Embedments

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:

solve

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.)

Definition

Solves all equations which matched the given name, with all systems of agents that should solved simultaneously.

Usages

Other examples of use:

solve SIR method: #rk4 step_size:0.001;

Embedments

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:

species

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)

Definition

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.

Usages

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 { }

Embedments

The species statement is of type: Species
The species statement can be embedded into: Model, Environment, Species,
The species statement embeds statements:

species_layer

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

Definition

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.

Usages

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}; 
}

See also: display, agents, chart, event, graphics, display_grid, image, overlay,

Embedments

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,

start_simulation

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

Embedments

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:

state

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)

Definition

A state, like a reflex, can contains several statements that can be executed at each time step by the agent.

Usages

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,

Embedments

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,

status

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

Definition

The statement makes the agent output an arbitrary message in the status box.

Usages

Outputting a message

status ("This is my status " + self) color: #yellow;

Embedments

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:

stochanalyse

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

Definition

This algorithm runs an exploration with a given sampling to compute a Stochasticity Analysis

Usages

For example:

method stochanalyse sampling:'latinhypercube' outputs:['my_var'] replicat:10 report:'../path/to/report/file.txt'; 

Embedments

The stochanalyse statement is of type: Batch method
The stochanalyse statement can be embedded into: Experiment,
The stochanalyse statement embeds statements:

switch

value (any type), (omissible) : an expression

Definition

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).

Usages

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"; } 
}

See also: match, default, if,

Embedments

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,

tabu

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

Definition

This algorithm is an implementation of the Tabu Search algorithm. See the wikipedia article and [batch161 the batch dedicated page].

Usages

As other batch methods, the basic syntax of the tabu statement uses method tabu instead of the expected tabu name: id :

method tabu [facet: value];

For example:

method tabu iter_max: 50 tabu_list_size: 5 maximize: food_gathered;

Embedments

The tabu statement is of type: Batch method
The tabu statement can be embedded into: Experiment,
The tabu statement embeds statements:

task

name (an identifier), (omissible) : the identifier of the task
weight (float): the priority level of the task

Definition

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.

Usages

Embedments

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:

test

name (an identifier), (omissible) : identifier of the test

Definition

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.

Usages

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] 
    } 
}

See also: setup, assert,

Embedments

The test statement is of type: Behavior
The test statement can be embedded into: Species, Experiment, Model,
The test statement embeds statements: assert,

text

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)

Definition

The statement makes an experiment display text in the parameters view.

Usages

Embedments

The text statement is of type: Single statement
The text statement can be embedded into: Experiment,
The text statement embeds statements:

trace

Definition

All the statements executed in the trace statement are displayed in the console.

Usages

Embedments

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:

transition

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

Definition

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.

Usages

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"; 
	} 
}

See also: enter, state, exit,

Embedments

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:

try

Definition

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

Usages

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] 
}

Embedments

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,

unconscious_contagion

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

Definition

enables to directly copy an emotion present in the perceived species.

Usages

Other examples of use:

unconscious_contagion emotion:fearConfirmed;  
unconscious_contagion emotion:fearConfirmed charisma: 0.5 receptivity: 0.5;

Embedments

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:

user_command

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

Definition

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.

Usages

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,

Embedments

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,

user_init

name (an identifier), (omissible) : The name of the panel
initial (boolean): Whether or not this panel will be the initial one

Definition

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.

Usages

See also: user_command, user_init, user_input,

Embedments

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,

user_input

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

Definition

It allows to let the user define the value of a variable.

Usages

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,

Embedments

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:

user_panel

name (an identifier), (omissible) : The name of the panel
initial (boolean): Whether or not this panel will be the initial one

Definition

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.

Usages

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,

Embedments

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,

using

topology (topology), (omissible) : the topology

Definition

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.

Usages

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); 
}

Embedments

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:

Variable_container

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

Definition

Declaration of an attribute of a species or an experiment

Usages

Embedments

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:

Variable_number

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

Definition

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.

Usages

Embedments

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:

Variable_regular

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

Definition

Declaration of an attribute of a species or an experiment

Usages

Embedments

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:

warn

message (string), (omissible) : the message to display as a warning.

Definition

The statement makes the agent output an arbitrary message in the error view as a warning.

Usages

Emmitting a warning

warn "This is a warning from " + self;

Embedments

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:

write

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 are per_cycle and per_simulation, no_buffering. In the case of per_cycle or per_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. The no_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.

Definition

The statement makes the agent output an arbitrary message in the console.

Usages

Outputting a message

write "This is a message from " + self;

Embedments

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:

Table of Contents​

Statements by kinds​

Statements by embedment​

General syntax​

=

Facets​

Definition​

Usages​

Embedments​

action​

Facets​

Definition​

Usages​

Embedments​

add​

Facets​

Definition​

Usages​

Embedments​

agents​

Facets​

Definition​

Usages​

Embedments​

annealing​

Facets​

Definition​

Usages​

Embedments​

ask​

Facets​

Definition​

Usages​

Embedments​

aspect​

Facets​

Definition​

Usages​

Embedments​

assert​

Facets​

Definition​

Usages​

Embedments​

benchmark​

Facets​

Definition​

Usages​

Embedments​

betad​

Facets​

Definition​

Usages​

Embedments​

break​

Facets​

Definition​

Usages​

Embedments​

camera​

Facets​

Definition​

Usages​

Embedments​

capture​

Facets​

Definition​

Usages​

Embedments​

catch​

Facets​

Definition​

Usages​

Embedments​

category​

Facets​

Definition​

Usages​

Embedments​

chart​

Table of Contents

Statements by kinds

Statements by embedment

General syntax

Facets

Definition

Usages

Embedments

action

Facets

Definition

Usages

Embedments

add

Facets

Definition

Usages

Embedments

agents

Facets

Definition

Usages

Embedments

annealing

Facets

Definition

Usages

Embedments

ask

Facets

Definition

Usages

Embedments

aspect

Facets

Definition

Usages

Embedments

assert

Facets

Definition

Usages

Embedments

benchmark

Facets

Definition

Usages

Embedments

betad

Facets

Definition

Usages

Embedments

break

Facets

Definition

Usages

Embedments

camera

Facets

Definition

Usages

Embedments

capture

Facets

Definition

Usages

Embedments

catch

Facets

Definition

Usages

Embedments

category

Facets

Definition

Usages

Embedments

chart

Facets