Types
A variable's or expression's type (or data type) determines the values it can take, plus the operations that can be performed on or with it. GAML is a statically-typed language, which means that the type of an expression is always known at compile time, and is even enforced with casting operations. There are 4 categories of types:
- primitive types, declared as keyword in the language,
- complex types, also declared as keyword in the language,
- parametric types, a refinement of complex types (mainly children of container) that is dynamically constructed using an enclosing type, a contents type and a key type,
- species types, dynamically constructed from the species declarations made by the modeler (and the built-in species present).
The hierarchy of types in GAML (only primitive and complex types are displayed here, of course, as the other ones are model-dependent) is the following:
Primitive built-in types​
bool​
- Definition: primitive datatype providing two values:
true
orfalse
. - Litteral declaration: both
true
orfalse
are interpreted as boolean constants. - Other declarations: expressions that require a boolean operand often directly apply a casting to bool to their operand. It is a convenient way to directly obtain a bool value.
bool (0) -> false
float​
- Definition: primitive datatype holding floating point values, its absolute value is comprised between 4.9E-324 and 1.8E308.
- Comments: this datatype is internally backed up by the Java double datatype.
- Litteral declaration: decimal notation 123.45 or exponential notation 123e45 are supported.
- Other declarations: expressions that require an integer operand often directly apply a casting to float to their operand. Using it is a way to obtain a float constant.
float (12) -> 12.0
int​
- Definition: primitive datatype holding integer values comprised between -2147483648 and 2147483647 (i.e. between
-2^31
and2^31 - 1
. - Comments: this datatype is internally backed up by the Java int datatype.
- Litteral declaration: decimal notation like 1, 256790 or hexadecimal notation like #1209FF are automatically interpreted.
- Other declarations: expressions that require an integer operand often directly apply a casting to int to their operand. Using it is a way to obtain an integer constant.
int (234.5) -> 234.
string​
- Definition: a datatype holding a sequence of characters.
- Comments: this datatype is internally backed up by the Java String class. However, contrary to Java, strings are considered as a primitive type, which means they do not contain character objects. This can be seen when casting a string to a list using the list operator: the result is a list of one-character strings, not a list of characters.
- Litteral declaration: a sequence of characters enclosed in quotes, like 'this is a string' . If one wants to literally declare strings that contain quotes, one has to double these quotes in the declaration. Strings accept escape characters like
\n
(newline),\r
(carriage return),\t
(tabulation), as well as any Unicode character (\uXXXX
). - Other declarations: see string
- Example: see string operators.
Complex built-in types​
Contrarily to primitive built-in types, complex types have often various attributes. They can be accessed in the same way as attributes of agents:
complex_type nom_var <- init_var;
ltype_attr attr_var <- nom_var.attr_name;
For example:
file fileText <- file("../data/cell.Data");
bool fileTextReadable <- fileText.readable;
agent​
- Definition: a generic datatype that represents an agent whatever its actual species.
- Built-in attributes: these attributes are common to any agent of the simulation
- location (type = point): the location of the agent
- shape (type = geometry): the shape of the agent
- name (type = string): name of the agent (not necessarily unique in its population)
- peers (type = list of agents of the same species): the population of agents of the same species, in the same host, minus the receiver agent
- host (type = agent): the agent that hosts the population of the agent
- Comments: This datatype is barely used since species name can be directly used as datatypes themselves.
- Declaration: the agent casting operator can be applied to any unknown object to cast it as an agent.
container​
- Definition: a generic datatype that represents a collection of data.
- Comments: a container variable can be a list, a matrix, a map... Conversely, each list, matrix, and map is a kind of container. In consequence, every container can be used in container-related operators.
- See also: Container operators
- Declaration:
container c <- [1,2,3];
container c <- matrix [[1,2,3],[4,5,6]];
container c <- map ["x"::5, "y"::12];
container c <- list species1;
conversation​
- Definition: a datatype that represents a conversation between agents in a FIPA-ACL interaction. It contains in particular all the exchanged messages.
- Built-in attributes:
messages
(type = list of messages): the list of messages that compose this conversationprotocol
(type = string): the name of the protocol followed by the conversationinitiator
(type = agent): the agent that has initiated this conversationparticipants
(type = list of agents): the list of agents that participate to this conversationended
(type = bool): whether this conversation has ended or not
date​
-
Definition: a datatype that represents a date (day, month, year, and time). Any date variable can be created in the model. 2 built-in variables exist in a model:
starting_date
(containing the date at the start of the simulation),current_date
(the date at the current step of the simulation, it is updated automatically fromstarting_date
,step
andtime
). In addition, the constant#now
contains the current (real) date. Many operators can be used on dates (such as+
,-
,add_years
...). -
Built-in attributes:
year
(type = int): the year component of the datemonth
(type = int): the month component of the date (1-12)day
(type = int): the day component of the date (1-31)hour
(type = int): the number of hours in the current day of this date (0-23)minute
(type = int): the number of minutes in the current hour of this date (0-59)second
(type = int): the number of seconds in the current minute of this date (0-59)day_of_year
(type = int): the current day number in the year of this date (1-366)day_of_week
(type = int): the index of the day in the current week (with Monday being 1)second_of_day
(type = int): the index of seconds in the day of this date (0-86399)minute_of_day
(type = int): the index of the minute in the day of this date (0-1439)week_of_year
(type = int): the index of the week in the current year (1-52)days_in_month
(type = int): the number of days in the current month of this date (28-31)days_in_year
(type = int): the number of days in the current year of this date (365-366)leap
(type = bool): returns true if the year is a leap yeardate
(type = date): returns a new date object with only the year-month-day components of this date
-
Declaration: a date can be created using different sets of information.
- The simplest one consists in using a list of int values: [year, month of the year, day of the month, hour of the day, minute of the hour, second of the minute] or simply [year, month of the year, day of the month] (time is set to 0 in this case).
date my_date <- date([2010,3,23,17,30,10]); // the 23th of March 2010, at 17:30:10
date my_date2 <- date([2010,3,23]); // the 23th of March 2010, at 00:00:00- Another way consists in using a string with the good format. The following one is perhaps the most complete, with year, month, day, hour, minute, second, and also the time zone.
date my_date <- date("2010-3-23T17:30:10+07:00");
- But the following ones can also be used:
// without time zone:
my_date3 <- date("2010-03-23 17:30:10");
//Dates (without time)
my_date3 <- date("20100323");
my_date3 <- date("2010-03-23");
// Dates using some patterns:
my_date3 <- date("03 23 2010","MM dd yyyy");
my_date3 <- date("01 23 20","HH mm ss"); -
Note: date creation format has been defined in an ISO norm. More examples can be found here: https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#patterns
-
See also: Date operators
field​
- Definition: Fields are two-dimensional matrices holding float values. They can be easily created from arbitrary sources (grid, raster or DEM files, matrices grids) and of course by hand. The values they hold are accessible by agents like grids are, using their current location. They can be the target of the 'diffuse' statement and can be displayed using the 'mesh' layer definition. As such, they represent a lightweight alternative to grids, as they hold spatialized discrete values without having to build agents, which can be particularly interesting for models with large raster data. Several fields can of course be defined, and it makes sense to define them in the global section as, for the moment, they cover by default the whole environment, exactly like grids, and are created alongside them.
- Built-in attributes: a field is a kind of matrix, it thus inherits from the matrix's attributes.
- dimension (type = point): the dimension (columns x rows) of the receiver matrix
- columns (type = int): the number of columns of the receiver matrix
- rows (type = int): the number of rows of the receiver matrix
- cell_size (type = point): the dimension of an individual cell as a point (width, height). Setting it will only change the interpretation made by the field of the values it contains, but not the values themselves.
- bands (type = list of field): The list of bands that are optionally present in the field. The first band is the primary field itself, and each of these bands is a field w/o bands
- no_data (type = float): the value that indicates the absence of data. Setting it will only change the interpretation made by the field of the values it contains, but not the values themselves.
- See also: Field operators
- Declaration: a field can be created from a raster datafile (such as .asc of .tif files), a matrix or be specifying its dimensions.
- a field can be created from a raster datafile
// Initialize a field from a asc simple raster file
field field_from_asc <- field(grid_file("includes/grid.asc"));
// initialize using a tiff raster file
field field_from_tiff <- field(grid_file("includes/Lesponne.tif"));- a field can be created manually:
// Init from a user defined matrix
field field_from_matrix <- field(matrix([[1,2,3],[4,5,6],[7,8,9]]));
// init an empty field of a given size
field empty_field_from_size <- field(10,10);
// init a field for of a given value
field full_field_from_size<- field(10,10,1.0);
// init a field of given size, with a given value and no data
field full_field_from_size_with_nodata <- field (1,1,1.0,0.0);- a field can be created from a grid of cells, the value stored will be the grid's grid_value attribute
global {
field field_from_grid <- field(matrix(cell));
}
grid cell width: 100 height: 100 {
float grid_value <- rnd(1.0,self distance_to world.location);
}
file​
- Definition: a datatype that represents a file.
- Built-in attributes:
- name (type = string): the name of the represented file (with its extension)
- extension(type = string): the extension of the file
- path (type = string): the absolute path of the file
- readable (type = bool, read-only): a flag expressing whether the file is readable
- writable (type = bool, read-only): a flag expressing whether the file is writable
- exists (type = bool, read-only): a flag expressing whether the file exists
- is_folder (type = bool, read-only): a flag expressing whether the file is folder
- contents (type = container): a container storing the content of the file
- Comments: a variable with the
file
type can handle any kind of file (text, image or shape files...). The type of thecontent
attribute will depend on the kind of file. Note that the allowed kinds of file are the followings:- text files: files with the extensions .txt, .data, .csv, .text, .tsv, .asc. The
content
is by default a list of string. - image files: files with the extensions .pgm, .tif, .tiff, .jpg, .jpeg, .png, .gif, .pict, .bmp. The
content
is by default a matrix of int. - shapefiles: files with the extension .shp. The
content
is by default a list of geometry. - properties files: files with the extension .properties. The
content
is by default a map of string::string. - folders. The
content
is by default a list of string.
- text files: files with the extensions .txt, .data, .csv, .text, .tsv, .asc. The
- Remark: Files are also a particular kind of container and can thus be read, written or iterated using the container operators and commands.
- See also: File operators
- Declaration: a file can be created using the generic
file
(that opens a file in read only mode and tries to determine its contents),folder
or thenew_folder
(to open an existing folder or create a new one) unary operators. But things can be specialized with the combination of theread
/write
andimage
/text
/shapefile
/properties
unary operators.
folder(a_string) // returns a file managing a existing folder
file(a_string) // returns any kind of file in read-only mode
read(text(a_string)) // returns a text file in read-only mode
read(image(a_string)) // does the same with an image file.
write(properties(a_string)) // returns a property file which is available for writing
// (if it exists, contents will be appended unless it is cleared
// using the standard container operations).