Skip to content

ModelOrganization

Arthur Brugière edited this page Sep 7, 2023 · 19 revisions

Organization of a model

As already extensively detailed in the introduction page, defining a model in GAML amounts to defining a model species, which later allows to instantiate a model agent (aka a simulation), which may or may not contain micro-species, and which can be flanked by experiment plans in order to be simulated.

This conceptual structure is respected in the definition of model files, which follows a similar pattern:

  1. Definition of the global species, preceded by a header, in order to represent the model species
  2. Definition of the different micro-species (either nested inside the global species or at the same level)
  3. Definition of the different experiment plans that target this model

Table of contents

Model Header (model species)

The header of a model file begins with the declaration of the name of the model. Contrarily to other statements, this declaration does not end with a semi-colon.

model name_of_the_model

The name of the model is not necessarily the same as the name of the file. It must conform to the general rule for naming species, i.e. be a valid identifier (beginning with a letter, containing only letters, digits, and dashes). This name will be used for building the name of the model species, from which simulations will be instantiated. For instance, the following declaration:

model dummy

will internally create a species called dummy_model, child of the abstract species model, from which simulations (called dummy_model0, dummy_model1, etc.) will be instantiated.

Import gaml file

This declaration is followed by optional import statements that indicate which other models this model is importing. Import statements do not end with a semi-colon.

Importing a model can take two forms. The first one, called inheritance import, is declared as follows:

import "relative_path_to_a_model_file"
import "relative_path_to_another_model_file"

The second one, called usage import, is declared as follows:

import "relative_path_to_a_model_file" as model_identifier

When importing models using the first form, all the declarations of the model(s) imported will be merged with those of the current model (in the order with which the import statements are declared, i.e. the latest definitions of global attributes or behaviors superseding the previous ones).

The second form is reserved for using models as micro-models of the current model. This possibility is still experimental in the current version of GAMA.

The last part of the header is the definition of the global species, which is the actual definition of the model species itself.

global {
    // Definition of [global attributes](GlobalSpecies#declaration), [actions and behaviors](DefiningActionsAndBehaviors)
}

Note that neither the imports nor the definition of global is mandatory. Only the model statement is.

:::info

While importing a model, every file is concatenated. Therefore, every variable will be processed from the gaml file where the experiment is located.

This might lead to some issues explained in #137 where relative path set in an imported file will be based on the model you're starting and not the file you defined it.

:::

Species declarations

The header is followed by the declaration of the different species of agents that populate the model.

The special species global is the world species. You will declare here all the global attributes/actions/behaviors. The global species does not have a name, and is unique in your model.

global {
    // definition of global attributes, actions, behaviors
}

Regular species can be declared with the keyword species. You can declare several regular species, and they all have to be named. A species defines its attributes, actions and behaviors and aspects.

species nameOfSpecies {
	// definition of your species attributes, actions and behaviors and aspects
}

Note that the possibility to define the species after the global definition is actually a convenience: these species are micro-species of the model species and, hence, could be perfectly defined as nested species of global. For instance:

global {
    // definition of global attributes, actions, behaviors
}

species A {...}

species B {...}

is completely equivalent to:

global {
    // definition of [global attributes](GlobalSpecies#declaration), actions, behaviors

    species A {...}

    species B {...}
}

Experiment declarations

Experiments are usually declared at the end of the file. They start with the keyword experiment. They contains the simulation parameters, and the definition of the output (such as displays, monitors or inspectors). You can declare as many experiments as you want.

experiment first_experiment {
    // definition of parameters (intputs)

    // definition of output
    output {...}
}

experiment second_experiment {
    // definition of parameters (inputs)

    // definition of output
}

Note that you have four types of experiments:

  • A GUI experiment allows you to display a graphical interface with input parameters and outputs. It is declared with the following structure:
experiment gui_experiment type:gui {
   [parameters]
   [output]
   [...]
}
  • A Batch experiment allows you to execute numerous successive simulation runs (often used for model exploration). It is declared with the following structure:
experiment batch_experiment type:batch {
   [parameters]
   [exploration method]
   [...]
}
  • A Test experiment allows you to write unit tests on a model (used to ensure its quality). It is declared with the following structure:
experiment test_experiment type:test autorun: true {
   [setup]
   [tests]
   [...]
}
  • A memorize experiment allows you to store each step of the simulation in memory and to backtrack to previous steps. It is declared with the following structure:
experiment test_experiment type:memorize {
   [parameters]
   [output]
   [...]
}

Basic skeleton of a model

Here is the basic skeleton of a model :

model name_of_the_model

global {
	// definition of [global attributes](GlobalSpecies#declaration), actions, behaviours
}

species my_specie {
	// definition of attributes, actions, behaviors
}

experiment my_experiment /* + specify the type : "type:gui", "type:batch", "type:test", or "test:memorize" */
{
	// here the definition of your experiment, with...
	// ... your inputs
	output {
		// ... and your outputs
	}
}

Don't forget this structure! This will be the basis for all the models you will create from now.

  1. What's new (Changelog)
  1. Installation and Launching
    1. Installation
    2. Launching GAMA
    3. Updating GAMA
    4. Installing Plugins
  2. Workspace, Projects and Models
    1. Navigating in the Workspace
    2. Changing Workspace
    3. Importing Models
  3. Editing Models
    1. GAML Editor (Generalities)
    2. GAML Editor Tools
    3. Validation of Models
  4. Running Experiments
    1. Launching Experiments
    2. Experiments User interface
    3. Controls of experiments
    4. Parameters view
    5. Inspectors and monitors
    6. Displays
    7. Batch Specific UI
    8. Errors View
  5. Running Headless
    1. Headless Batch
    2. Headless Server
    3. Headless Legacy
  6. Preferences
  7. Troubleshooting
  1. Introduction
    1. Start with GAML
    2. Organization of a Model
    3. Basic programming concepts in GAML
  2. Manipulate basic Species
  3. Global Species
    1. Regular Species
    2. Defining Actions and Behaviors
    3. Interaction between Agents
    4. Attaching Skills
    5. Inheritance
  4. Defining Advanced Species
    1. Grid Species
    2. Graph Species
    3. Mirror Species
    4. Multi-Level Architecture
  5. Defining GUI Experiment
    1. Defining Parameters
    2. Defining Displays Generalities
    3. Defining 3D Displays
    4. Defining Charts
    5. Defining Monitors and Inspectors
    6. Defining Export files
    7. Defining User Interaction
  6. Exploring Models
    1. Run Several Simulations
    2. Batch Experiments
    3. Exploration Methods
  7. Optimizing Model Section
    1. Runtime Concepts
    2. Optimizing Models
  8. Multi-Paradigm Modeling
    1. Control Architecture
    2. Defining Differential Equations
  1. Manipulate OSM Data
  2. Diffusion
  3. Using Database
  4. Using FIPA ACL
  5. Using BDI with BEN
  6. Using Driving Skill
  7. Manipulate dates
  8. Manipulate lights
  9. Using comodel
  10. Save and restore Simulations
  11. Using network
  12. Headless mode
  13. Using Headless
  14. Writing Unit Tests
  15. Ensure model's reproducibility
  16. Going further with extensions
    1. Calling R
    2. Using Graphical Editor
    3. Using Git from GAMA
  1. Built-in Species
  2. Built-in Skills
  3. Built-in Architecture
  4. Statements
  5. Data Type
  6. File Type
  7. Expressions
    1. Literals
    2. Units and Constants
    3. Pseudo Variables
    4. Variables And Attributes
    5. Operators [A-A]
    6. Operators [B-C]
    7. Operators [D-H]
    8. Operators [I-M]
    9. Operators [N-R]
    10. Operators [S-Z]
  8. Exhaustive list of GAMA Keywords
  1. Installing the GIT version
  2. Developing Extensions
    1. Developing Plugins
    2. Developing Skills
    3. Developing Statements
    4. Developing Operators
    5. Developing Types
    6. Developing Species
    7. Developing Control Architectures
    8. Index of annotations
  3. Introduction to GAMA Java API
    1. Architecture of GAMA
    2. IScope
  4. Using GAMA flags
  5. Creating a release of GAMA
  6. Documentation generation

  1. Predator Prey
  2. Road Traffic
  3. 3D Tutorial
  4. Incremental Model
  5. Luneray's flu
  6. BDI Agents

  1. Team
  2. Projects using GAMA
  3. Scientific References
  4. Training Sessions

Resources

  1. Videos
  2. Conferences
  3. Code Examples
  4. Pedagogical materials
Clone this wiki locally