Skip to main content
Version: 1.8.2-RC2

Statements

This file is automatically generated from java files. Do Not Edit It.

Table of Contents​

=, abort, action, add, agents, annealing, ask, aspect, assert, benchmark, break, browse, camera, capture, catch, chart, conscious_contagion, coping, create, data, datalist, default, diffuse, diffusion, display, display_grid, display_population, do, draw, else, emotional_contagion, enforcement, enter, equation, error, event, exhaustive, exit, experiment, explicit, focus, focus_on, generate, genetic, global, graphics, grid, highlight, hill_climbing, if, image, init, inspect, invoke, law, layout, let, light, loop, match, match_between, match_one, match_regex, mesh, migrate, monitor, norm, output, output_file, overlay, parameter, perceive, permanent, plan, pso, put, reactive_tabu, reflex, release, remove, return, rotation, rule, rule, run, sanction, save, set, setup, simulate, sobol, socialize, solve, species, start_simulation, state, status, 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​

Statements by embedment​

General syntax​

A statement represents either a declaration or an imperative command. It consists in a keyword, followed by specific facets, some of them mandatory (in bold), some of them optional. One of the facet names can be omitted (the one denoted as omissible). It has to be the first one.

statement_keyword expression1 facet2: expression2 ... ;
or
statement_keyword facet1: expression1 facet2: expression2 ...;

If the statement encloses other statements, it is called a sequence statement, and its sub-statements (either sequence statements or single statements) are declared between curly brackets, as in:

statement_keyword1 expression1 facet2: expression2... { // a sequence statement
     statement_keyword2 expression1 facet2: expression2...;  // a single statement
     statement_keyword3 expression1 facet2: expression2...;
}

=

Facets​

  • right (float), (omissible) : the right part of the equation (it is mandatory that it can be evaluated as a 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); 
}

Embedments​

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

action​

Facets​

  • name (an identifier), (omissible) : identifier of the 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​

Facets​

  • to (any type in [container, species, agent, geometry]): an expression that evaluates to a container
  • item (any type), (omissible) : any expression to add in the container
  • all (any type): Allows to either pass a container so as to add all its element, or 'true', if the item to add is already a container.
  • at (any type): position in the container of added element

Definition​

Allows to add, i.e. to insert, a new element in a container (a list, matrix, map, ...).Incorrect use: The addition of a new element at a position out of the bounds of the container will produce a warning and let the container unmodified. If all: is specified, it has no effect if its argument is not a container, or if its argument is 'true' and the item to add is not a container. In that latter case

Usages​

  • The new element can be added either at the end of the container or at a particular position.
add expr to: expr_container;    // Add at the end 
add expr at: expr to: expr_container;   // Add at position expr
  • Case of a list, the expression in the facet at: should be an integer.
list<int> workingList <- [];add 0 at: 0 to: workingList ;//workingList equals [0]add 10 at: 0 to: workingList ;//workingList equals [10,0]add 20 at: 2 to: workingList ;//workingList equals [10,0,20]add 50 to: workingList;//workingList equals [10,0,20,50]add [60,70] all: true to: workingList;//workingList equals [10,0,20,50,60,70]
  • Case of a map: As a map is basically a list of pairs key::value, we can also use the add statement on it. It is important to note that the behavior of the statement is slightly different, in particular in the use of the at facet, which denotes the key of the pair.
map<string,string> workingMap <- [];add "val1" at: "x" to: workingMap;//workingMap equals ["x"::"val1"]
  • If the at facet is omitted, a pair expr_item::expr_item will be added to the map. An important exception is the case where the expr_item is a pair: in this case the pair is added.
  • Notice that, as the key should be unique, the addition of an item at an existing position (i.e. existing key) will only modify the value associated with the given key.
  • On a map, the all facet will add all value of a container in the map (so as pair val_cont::val_cont)
  • In case of a graph, we can use the facets node, edge and weight to add a node, an edge or weights to the graph. However, these facets are now considered as deprecated, and it is advised to use the various edge(), node(), edges(), nodes() operators, which can build the correct objects to add to the graph
graph g <- as_edge_graph([{1,5}::{12,45}]); 
add edge: {1,5}::{2,3} to: g; 
list var <- g.vertices; // var equals [{1,5},{12,45},{2,3}] 
list var <- g.edges; // var equals [polyline({1.0,5.0}::{12.0,45.0}),polyline({1.0,5.0}::{2.0,3.0})] 
add node: {5,5} to: g; 
list var <- g.vertices; // var equals [{1.0,5.0},{12.0,45.0},{2.0,3.0},{5.0,5.0}] 
list var <- g.edges; // var equals [polyline({1.0,5.0}::{12.0,45.0}),polyline({1.0,5.0}::{2.0,3.0})]
  • Case of a matrix: this statement can not be used on matrix. Please refer to the statement put.
  • See also: put, remove,

Embedments​

  • The add statement is of type: Single statement
  • The add statement can be embedded into: chart, Behavior, Sequence of statements or action, Layer,
  • The add statement embeds statements:

agents​

Facets​

  • value (container): the set of agents to 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; 
}

Embedments​

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

annealing​

Facets​

  • name (an identifier), (omissible) : The name of the method. For internal use 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
  • 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​

Facets​

  • 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​

Facets​

  • name (an identifier), (omissible) : identifier of the aspect (it can be used in a display to identify which aspect should be used for the given species). Two special names can also be used: 'default' will allow this aspect to be used as a replacement for the default aspect defined in preferences; 'highlighted' will allow the aspect to be used when the agent is highlighted as a replacement for the default (application of a color)

Definition​

Aspect statement is used to define a way to draw the current agent. Several aspects can be defined in one species. It can use attributes to customize each agent's aspect. The aspect is evaluate for each agent each time it has to be displayed.

Usages​

  • An example of use of the aspect statement:
species one_species { 
	int a <- rnd(10); 
	aspect aspect1 { 
		if(a mod 2 = 0) { draw circle(a);} 
		else {draw square(a);} 
		draw text: "a= " + a color: #black size: 5; 
	} 
}

Embedments​

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

assert​

Facets​

  • value (boolean), (omissible) : a boolean expression. If its evaluation is true, the assertion is successful. Otherwise, an error (or a warning) is raised.
  • warning (boolean): if set to true, makes the assertion emit a warning instead of an error

Definition​

Allows to check if the evaluation of a given expression returns true. If not, an error (or a warning) is raised. If the statement is used inside a test, the error is not propagagated but invalidates the test (in case of a warning, it partially invalidates it). Otherwise, it is normally propagated

Usages​

  • Any boolean expression can be used
assert (2+2) = 4; 
assert self != nil; 
int t <- 0; assert is_error(3/t); 
(1 / 2) is float
  • if the 'warn:' facet is set to true, the statement emits a warning (instead of an error) in case the expression is false
assert 'abc' is string warning: true

Embedments​

  • The assert statement is of type: Single statement
  • The assert statement can be embedded into: test, action, Sequence of statements or action, Behavior, Sequence of statements or action,
  • The assert statement embeds statements:

benchmark​

Facets​

  • message (any type), (omissible) : A message to display alongside the results. Should concisely describe the contents of the benchmark
  • repeat (int): An int expression describing how many executions of the block must be handled. The output in this case will return the min, max and average durations

Definition​

Displays in the console the duration in ms of the execution of the statements included in the block. It is possible to indicate, with the 'repeat' facet, how many times the sequence should be run

Usages​

Embedments​

  • The benchmark statement is of type: Sequence of statements or action
  • The benchmark statement can be embedded into: Behavior, Sequence of statements or action, Layer,
  • The benchmark statement embeds statements:

break​

Facets​

Definition​

break allows to interrupt the current sequence of statements.

Usages​

Embedments​

  • The break statement is of type: Single statement
  • The break statement can be embedded into: Sequence of statements or action,
  • The break statement embeds statements:

camera​

Facets​

  • name (string), (omissible) : The name of the 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​

Embedments​

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

capture​

Facets​

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

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​

Facets​

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​

Facets​

  • 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, whisker, 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, a label]): 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 horyzontal 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, a label]): 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] 
   } 
}

Embedments​

conscious_contagion​

Facets​

  • 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
  • intensity (float): The intensity 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 add an emotion of a perceived specie if the perceived agent ges a patricular 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:

coping​

Facets​

  • 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​

Facets​

  • 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; 
5
  • In GAML modelers can create agents of species a_species (with two attributes typeandnaturewith types corresponding to the types of the shapefile attributes) from a shapefilethe_shapefile` while reading attributes 'TYPE_OCC' and 'NATURE' of the shapefile. One agent will be created by object contained in the shapefile:
create a_species from: the_shapefile with: [type:: read('TYPE_OCC'), nature::read('NATURE')];
  • In order to create agents from a .csv file, facet header can be used to specified whether we can use columns header:
create toto from: "toto.csv" header: true with:[att1::read("NAME"), att2::read("TYPE")]; 
or 
create toto from: "toto.csv" with:[att1::read(0), att2::read(1)]; //with read(int), the index of the column
  • Similarly to the creation from shapefile, modelers can create agents from a set of geometries. In this case, one agent per geometry will be created (with the geometry as shape)
create species_of(self) from: [square(4),circle(4)]; 	// 2 agents have been created, with shapes respectively square(4) and circle(4)
  • Created agents are initialized following the rules of their species. If one wants to refer to them after the statement is executed, the returns keyword has to be defined: the agents created will then be referred to by the temporary variable it declares. For instance, the following statement creates 0 to 4 agents of the same species as the sender, and puts them in the temporary variable children for later use.
create species (self) number: rnd (4) returns: children; 
ask children { 
        // ... 
}
  • If one wants to specify a special initialization sequence for the agents created, create provides the same possibilities as ask. This extended syntax is:
create a_species number: an_int { 
     [statements] 
}
  • The same rules as in ask apply. The only difference is that, for the agents created, the assignments of variables will bypass the initialization defined in species. For instance:
create species(self) number: rnd (4) returns: children { 
     set location <- myself.location + {rnd (2), rnd (2)}; // tells the children to be initially located close to me 
     set parent <- myself; // tells the children that their parent is me (provided the variable parent is declared in this species)  
}
  • Deprecated uses:
// Simple syntax 
create species: a_species number: an_int;

  • If number equals 0 or species is not a species, the statement is ignored.

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​

Facets​

  • 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, whisker, 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​

Facets​

  • 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, whisker, 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​

Facets​

  • 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​

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​

Facets​

  • 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, 31, 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​

Facets​

  • 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 with a specific color
  • 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
  • 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 ambient_light: 100 { 
	grid cell elevation: true triangulation: true; 
	species people aspect: base; 
}

Embedments​

display_grid​

Facets​

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

Embedments​

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

display_population​

Facets​

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

Embedments​

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

do​

Facets​

  • 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,
  • The do statement embeds statements:

draw​

Facets​

  • 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)
  • material (material): Set a particular material to the object (only if you use it in an "opengl2" display).
  • perspective (boolean): Whether to render the text in perspective or facing the user. Default is true.
  • 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 in [string, list, file]): 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
  • 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​

Facets​

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​

Facets​

  • 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​

Facets​

  • 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​

applay 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​

Facets​

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 "Enter in" + state; 
		} 
		write state; 
	}

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​

Facets​

  • 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​

Facets​

  • 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​

Facets​

  • name (an identifier), (omissible) : the type of event captured: can be "mouse_up", "mouse_down", "mouse_move", "mouse_exit", "mouse_enter", "mouse_menu" 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 peripheric used to generate events. Defaults to 'default', which encompasses keyboard and mouse
  • unused (an identifier), takes values in: {mouse_up, mouse_down, mouse_move, mouse_enter, mouse_exit, mouse_menu}: an unused facet that serves only for the purpose of declaring the string values

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

Embedments​

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

exhaustive​

Facets​

  • name (an identifier), (omissible) : The name of the method. For internal use only

Definition​

This is the standard batch method. The exhaustive 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. See [batch161 the batch dedicated page].

Usages​

  • As other batch methods, the basic syntax of the exhaustive statement uses method exhaustive instead of the expected exhaustive name: id :
method exhaustive [facet: value];
  • For example:
method exhaustive maximize: food_gathered;

Embedments​

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

exit​

Facets​

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

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​

Facets​

  • name (a label), (omissible) : identifier of the experiment
  • title (a label):
  • type (a label), takes values in: {batch, memorize, gui, test, headless}: the type of the experiment (either 'gui' or 'batch'
  • 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):
  • frequency (int): the execution frequence of the experiment (default value: 1). If frequency: 10, the experiment is executed only each 10 steps.
  • 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)
  • 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):
  • 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

Usages​

Embedments​

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

explicit​

Facets​

  • name (an identifier), (omissible) : The name of the method. For internal use only
  • parameter_sets (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 algorithm run simulations with the given parameter sets

Usages​

  • As other batch methods, the basic syntax of the explicit statement uses method explicit instead of the expected explicit name: id :
method explicit [facet: value];
  • For example:
method explicit parameter_sets:[["a"::0.5, "b"::10],["a"::0.1, "b"::100]];

Embedments​

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

focus​

Facets​

  • agent_cause (agent): the agentCause value of 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 specie.

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​

Facets​

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

generate​

Facets​

  • attributes (map): To specify the explicit link between agent attributes and file based attributes
  • from (any type): To specify the input data used to inform the generation process. Various data input can be used:
  • list of csv_file: can be aggregated or micro data
  • matrix: describe the joint distribution of two attributes
  • genstar generator: a dedicated gaml type to enclose various genstar options all in one
  • species (any type in [species, agent]), (omissible) : The species of the agents to be created.
  • generator (string): To specify the type of generator you want to use: as of now there is only DS (or DirectSampling) available
  • number (int): To specify the number of created agents interpreted as an int value. If facet is ommited or value is 0 or less, generator will treat data used in the 'from' facet as contingencies (i.e. a count of entities) and infer a number to generate (if distribution is used, then only one entity will be created

Definition​

Allows to create a synthetic population of agent from a set of given rules

Usages​

  • The synthax to create a minimal synthetic population from aggregated file is:
synthesis my_species from: [source_file]; attributes: [age::["below 18","19 to 45","more than 46"] 
synthesis my_species from: my_matrix number: 5 returns: list5Agents;

Embedments​

  • The generate statement is of type: Sequence of statements or action
  • The generate statement can be embedded into: Behavior, Sequence of statements or action,
  • The generate statement embeds statements:

genetic​

Facets​

  • 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​

Facets​

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

Embedments​

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

highlight​

Facets​

  • 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​

Facets​

  • 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
  • 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​

Facets​

  • 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​

Facets​

  • name (any type in [string, file]), (omissible) : Human readable title of the image layer
  • 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
  • file (any type in [string, file]): the name/path of the image (in the case of a raster 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 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 layer_name file: image_file [additional options]; 
}
  • For instance, in the case of a bitmap image
display my_display { 
   image background file:"../images/my_backgound.jpg"; 
}
  • 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 image1 file:"../images/image1.jpg"; 
  image image2 file:"../images/image2.jpg"; 
  image image3 file:"../images/image3.jpg" position: {0,0,0.5}; 
}

Embedments​

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

inspect​

Facets​

  • 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​

Facets​

  • 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​

Facets​

  • 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 (true 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​

Facets​

  • name (a new identifier), (omissible) : The name of the variable declared
  • 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 variable
  • value (any type): The value assigned to this variable

Definition​

Allows to declare a temporary variable of the specified type and to initialize it with a value

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​

Facets​

  • 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)
  • 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 draw_light:true update: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

Embedments​

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

loop​

Facets​

  • name (a new identifier), (omissible) : a temporary variable name
  • from (int): an int expression
  • over (any type in [container, point]): a list, point, matrix or map expression
  • step (int): an int expression
  • times (int): an int expression
  • to (int): an int expression
  • 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 integers. 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. The from and to facets take an integer 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​

Facets​

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

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​

Facets​

  • source (any type in [file, matrix, species]), (omissible) : Allows to specify the elevation 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.
  • border (rgb): the color to draw lines (borders of cells)
  • color (any type in [rgb, list, map]): if true, and if neither 'grayscale' or 'texture' are specified, displays the field using the given color or colors. List of colors, palettes (with interpolation), gradients and scales are supported
  • grayscale (boolean): if true, gives a grey color to each polygon depending on its elevation (false by default). Supersedes 'color' if it is defined.
  • 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
  • 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; 
}

Embedments​

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

migrate​

Facets​

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

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​

Facets​

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

norm​

Facets​

  • 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​

Facets​

  • 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) in a display 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] 
   } 
}

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, output_file,

output_file​

Facets​

  • name (an identifier), (omissible) : The name of the file where you want to export the data
  • data (string): The data you want to export
  • footer (string): Define a footer for your export file
  • header (string): Define a header for your export file
  • refresh (boolean): Indicates the condition under which this file should be saved (default is true)
  • rewrite (boolean): Rewrite or not the existing file
  • type (an identifier), takes values in: {csv, text, xml}: The type of your output data

Definition​

Represents an output that writes the result of expressions into a file

Usages​

Embedments​

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

overlay​

Facets​

  • 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];

Embedments​

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

parameter​

Facets​

  • 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 (a label): 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 (a label): 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​

Facets​

  • 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: a_distance when: a_certain_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: Sequence of statements or action
  • The perceive statement can be embedded into: Species, Model,
  • The perceive statement embeds statements:

permanent​

Facets​

  • synchronized (boolean): Indicates whether the displays that compose this output should be synchronized with the simulation cycles

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, output_file,

plan​

Facets​

  • 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​

Facets​

  • 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​

Facets​

  • in (any type in [container, species, agent, geometry]): an expression that evaluates to a container
  • item (any type), (omissible) : any expression
  • all (any type): any expression
  • at (any type): any expression
  • key (any type): any expression

Definition​

Allows the agent to replace a value in a container at a given position (in a list or a map) or for a given key (in a map). Note that the behavior and the type of the attributes depends on the specific kind of container.

Usages​

  • The allowed parameters configurations are the following ones:
put expr at: expr in: expr_container; 
put all: expr in: expr_container;
  • In the case of a list, the position should an integer in the bound of the list. The facet all: is used to replace all the elements of the list by the given value.
putList <- [1,2,3,4,5]; //putList equals [1,2,3,4,5]put -10 at: 1 in: putList;//putList equals [1,-10,3,4,5]put 10 all: true in: putList;//putList equals [10,10,10,10,10]
  • In the case of a matrix, the position should be a point in the bound of the matrix. The facet all: is used to replace all the elements of the matrix by the given value.
putMatrix <- matrix([[0,1],[2,3]]); //putMatrix equals matrix([[0,1],[2,3]])put -10 at: {1,1} in: putMatrix;//putMatrix equals matrix([[0,1],[2,-10]])put 10 all: true in: putMatrix;//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, the given 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.
putMap <- ["x"::4,"y"::7]; //putMap equals ["x"::4,"y"::7]put -10 key: "y" in: putMap;//putMap equals ["x"::4,"y"::-10]put -20 key: "z" in: putMap;//putMap equals ["x"::4,"y"::-10, "z"::-20]put -30 all: true in: putMap;//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​

Facets​

  • 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
  • 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 [batch161 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​

Facets​

  • 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​

Facets​

  • target (any type in [agent, list, attributes]), (omissible) : an expression that is evaluated as an agent/a list of the agents to be released or an agent saved as a map
  • 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;

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​

Facets​

  • from (any type in [container, species, agent, geometry]): an expression that evaluates to a container
  • item (any type), (omissible) : any expression to remove from the container
  • all (any type): an expression that evaluates to a container. If it is true and if the value a list, it removes the first instance of each element of the list. If it is true and the value is not a container, it will remove all instances of this value.
  • index (any type): any expression, the key at which to remove the element from the container
  • key (any type): any expression, the key at which to remove the element from the container

Definition​

Allows the agent to remove an element from a container (a list, matrix, map...).

Usages​

  • This statement should be used in the following ways, depending on the kind of container used and the expected action on it:
remove expr from: expr_container; 
remove index: expr from: expr_container; 
remove key: expr from: expr_container; 
remove all: expr from: expr_container;
  • In the case of list, the facet item: is used to remove the first occurence of a given expression, whereas all is used to remove all the occurrences of the given expression.
list<int> removeList <- [3,2,1,2,3];remove 2 from: removeList;//removeList equals [3,1,2,3]remove 3 all: true from: removeList;//removeList equals [1,2]remove index: 1 from: removeList;//removeList equals [1]
  • In the case of map, the facet key: is used to remove the pair identified by the given key.
map<string,int> removeMap <- ["x"::5, "y"::7, "z"::7];remove key: "x" from: removeMap;//removeMap equals ["y"::7, "z"::7]remove 7 all: true from: removeMap;//removeMap equals map([])
  • In addition, a map a be managed as a list with pair key as index. Given that, facets item:, all: and index: can be used in the same way:
map<string,int> removeMapList <- ["x"::5, "y"::7, "z"::7, "t"::5];remove 7 from: removeMapList;//removeMapList equals ["x"::5, "z"::7, "t"::5]remove [5,7] all: true from: removeMapList;//removeMapList equals ["t"::5]remove index: "t" from: removeMapList;//removeMapList equals map([])
  • In the case of a graph, both edges and nodes can be removes using node: and edge facets. If a node is removed, all edges to and from this node are also removed.
graph removeGraph <- as_edge_graph([{1,2}::{3,4},{3,4}::{5,6}]); 
remove node: {1,2} from: removeGraph; 
remove node(1,2) from: removeGraph; 
list var <- removeGraph.vertices; // var equals [{3,4},{5,6}] 
list var <- removeGraph.edges; // var equals [polyline({3,4}::{5,6})] 
remove edge: {3,4}::{5,6} from: removeGraph; 
remove edge({3,4},{5,6}) from: removeGraph; 
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 now equals 100 
      remove key:"a" from: sR; 	// sR.a now equals nil 
   } 
} 
 
species speciesRemove { 
   int a <- 100;  
}
  • 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:

return​

Facets​

  • 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​

Facets​

  • 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​

Embedments​

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

rule​

Facets​

  • 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 rule statement is of type: Behavior
  • The rule statement can be embedded into: rules, Species, Experiment, Model,
  • The rule statement embeds statements:

rule​

Facets​

  • 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​

Facets​

  • 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):
  • with_param (map):

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​

Facets​

  • 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​

Facets​

  • data (any type), (omissible) : the data that will be saved to the file
  • 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.
  • 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
  • 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
  • type (an identifier), takes values in: {shp, text, csv, asc, geotiff, image, kml, kmz, json, dimacs, dot, gexf, graphml, gml, graph6}: an expression that evaluates to an string, the type of the output file (it can be only "shp", "asc", "geotiff", "image", "text" or "csv")

Definition​

Allows to save data in a file. The type of file can be "shp", "asc", "geotiff", "text" or "csv".

Usages​

  • Its simple syntax is:
save data to: output_file type: a_type_file;
  • To save data in a text file:
save (string(cycle) + "->"  + name + ":" + location) to: "save_data.txt" type: "text";
  • To save the values of some attributes of the current agent in csv file:
save [name, location, host] to: "save_data.csv" type: "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" type: "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" type: "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" type: "asc";
  • To save the grid_value attributes of all the cells of a grid into geotiff:
save grid to: "save_grid.tif" type: "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" type: "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​

Facets​

  • 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​

Facets​

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

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:

simulate​

Facets​

  • comodel (file), (omissible) :
  • repeat (int):
  • reset (boolean):
  • share (list):
  • until (boolean):
  • with_experiment (string):
  • with_input (map):
  • with_output (map):

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. It obeys the following syntax, where the target attribute denotes the receiver agent(s):

Usages​

  • Other examples of use:
 
ask receiver_agent(s) { 
     // [statements] 
}

Embedments​

  • The simulate statement is of type: Single statement
  • The simulate statement can be embedded into: chart, Experiment, Species, Behavior, Sequence of statements or action,
  • The simulate statement embeds statements:

sobol​

Facets​

  • 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
  • sample (an identifier): The size of the sample for the sobol sequence
  • report (string): The path to the file where the Sobol report will be written
  • 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​

Facets​

  • 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:
 
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​

Facets​

  • 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 (float): (deprecated) integration step, use with fixed step integrator methods (default value: 0.005*step)
  • 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: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​

Facets​

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

start_simulation​

Facets​

  • name (string), (omissible) : The name of the experiment to run
  • of (string): The path to the model containing the experiment
  • seed (int):
  • with_param (map):

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​

Facets​

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

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​

Facets​

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

switch​

Facets​

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

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​

Facets​

  • 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
  • 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​

Facets​

  • 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​

Facets​

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

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​

Facets​

  • 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​

Facets​

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​

Facets​

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

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​

Facets​

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​

Facets​

  • 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 presents in the perceived specie.

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​

Facets​

  • 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 (a label): 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, ...];

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​

Facets​

  • 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​

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​

Facets​

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

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​

Facets​

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

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​

Facets​

  • 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​

Facets​

  • name (a new identifier), (omissible) : The name of the attribute
  • category (a label): Soon to be deprecated. Declare the parameter in an experiment instead
  • 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:' and 'update:'
  • 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
  • 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
  • parameter (a label): Soon to be deprecated. Declare the parameter in an experiment instead
  • 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​

Allows to declare 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​

Facets​

  • name (a new identifier), (omissible) : The name of the attribute
  • among (list): A list of constant values among which the attribute can take its value
  • category (a label): Soon to be deprecated. Declare the parameter in an experiment instead
  • 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. This facet is incompatible with both 'init:' and 'update:'
  • init (any type in [int, float, point, date]): The initial value of the attribute
  • 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
  • parameter (a label): Soon to be deprecated. Declare the parameter in an experiment instead
  • 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​

Allows to declare an attribute of a species or 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​

Facets​

  • name (a new identifier), (omissible) : The name of the attribute
  • among (list): A list of constant values among which the attribute can take its value
  • category (a label): Soon to be deprecated. Declare the parameter in an experiment instead
  • 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
  • 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
  • parameter (a label): Soon to be deprecated. Declare the parameter in an experiment instead
  • 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​

Allows to declare 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​

Facets​

  • 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​

Facets​

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

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: