Model

Models contain the agents and tiles that make up the simulation. They also provide some functionality for manipulating said simulation, such as buttons, and ways to visualize simulation data, such as graphs.

To run a model, use

agents.run(model)
class agents.Model(title, x_tiles=50, y_tiles=50, tile_size=8, cell_data_file=None)

Creates a model with the given title. There are two ways of creating a model; creating a blank model of size x_tiles times y_tiles with no predetermined data, or creating a model with predetermined data from a cell_data_fille.

Parameters:
  • title – The title of the model (to show in the simulation window).
  • x_tiles – The number of tiles on the x-axis. Ignored if a cell_data_file is provided.
  • y_tiles – The number of tiles on the y-axis. Ignored if a cell_data_file is provided.
  • tile_size – The width/height of each tile in pixels.
  • cell_data_file – If provided, generates a model from the data file instead. The data is not immediately to the tiles, but must be applied with Model.reload().
add_agent(agent, setup=True)

Adds an agent to the model.

Parameters:
  • agent – The agent to add to the model.
  • setup – Whether or not to run the agent’s setup function (default True).
add_agents(agents)

Adds a collection of agents.

Parameters:agents – The agents to add.
add_button(label, func, toggle=False)

Adds a button that runs a provided function when pressed. Can be specified to be a toggled button, which will cause the button to continuously call the function while toggled on.

Parameters:
  • label – The label on the button.
  • func – The function to run when the button is pressed.
  • toggle – Whether or not the button should be a toggled button.
add_checkbox(variable)

Adds a checkbox that can be used to change the value of a variable between true and false.

Parameters:variable – The name of the variable to adjust. Must be provided as a string.
add_controller_row()

Creates a new row to place controller widgets on (buttons, sliders, etc.).

add_ellipse(x, y, w, h, color)

Draws an ellipse on the simulation area. Returns a shape object that can be used to refer to the ellipse.

Parameters:
  • x – The top-left x-coordinate of the ellipse.
  • y – The top-left y-coordinate of the ellipse.
  • w – The width of the ellipse.
  • h – The height of the ellipse.
  • color – The color of the ellipse.
add_rect(x, y, w, h, color)

Draws a square on the simulation area. Returns a shape object that can be used to refer to the square.

Parameters:
  • x – The top-left x-coordinate of the square.
  • y – The top-left y-coordinate of the square.
  • w – The width of the square.
  • h – The height of the square.
  • color – The color of the square.
add_slider(variable, initial, minval=0, maxval=100)

Adds a slider that can be used to adjust the value of a variable in the model.

Parameters:
  • variable – The name of the variable to adjust. Must be privded as a string.
  • minval – The minimum value of the variable.
  • maxval – The maximum value of the variable.
  • initial – The initial value of the variable.
agent_line_chart(variable, min_y=None, max_y=None)

Adds a line chart to the simulation window that shows the trend of multiple variables over time.

Parameters:
  • variables – The names of the variables. Must be provided as a list of strings.
  • colors – The color of each line.
  • min_y – The minimum value on the y-axis.
  • max_y – The maximum value on the y-axis.
agents_ordered(variable, increasing=True)

Returns a list of agents in the model, ordered based on one of their attributes. Agents who do not have the attribute are not included in the list.

Parameters:
  • variable – The attribute to order by.
  • increasing – Whether or not to order the agents in increasing or decreasing order (default True).
bar_chart(variables, color)

Adds a bar chart to the simulation window that shows the relation between multiple variables.

Parameters:
  • variables – The list of the variables. Must be provided as a list of strings.
  • color – The color of all the bars.
clear_plots()

Clears the data from all plots.

clear_shapes()

Clears all shapes in the model.

disable_wrapping()

Disables wrapping. Agents attempting to move outside the simulation area will collide with the border and be moved back to the closest point inside.

enable_wrapping()

Enables wrapping, i.e. turns the simulation area toroidal. Agents exiting the simulation area on one side will enter on the other side.

get_shapes()

Returns an iterator containing all the shapes in the model.

histogram(variable, minimum, maximum, bins, color)

Adds a histogram to the simulation window that shows how the agents in the model are distributed based on a specific attribute.

Parameters:
  • variable – The name of the attribute to base the distribution on. Must be provided as a string.
  • minimum – The minimum value of the distribution.
  • maximum – The maximum value of the distribution.
  • bins – The number of bins in the histogram.
  • color – The color of all the bars.
is_paused()

Returns whether the model is paused or not.

line_chart(variables, colors, min_y=None, max_y=None)

Adds a line chart to the simulation window that shows the trend of multiple variables over time.

Parameters:
  • variables – The names of the variables. Must be provided as a list of strings.
  • colors – The color of each line.
  • min_y – The minimum value on the y-axis.
  • max_y – The maximum value on the y-axis.
monitor(variable)

Adds a single line that shows the value of the given variable.

Parameters:variable – The variable to monitor.
on_close(func)

Defines a function to be run when the simulation window is closed. This is generally used to close any open file pointers.

pause()

Pauses the model. The main effect of this is to ignore the “on” status of any toggled buttons, meaning that step functions and similar are not run.

reload()

Applies the data from the cell-data-file to the tiles in the model. Only usable if the model was created with a cell_data_file in the constructor.

reset()

Resets the model by doing the following:

  • Destroys all agents.
  • Clears the set of agents.
  • Clears the set of shapes.
  • Clears all tiles (removes all of their info and colors them black).
  • Clears all plots.
  • Unpauses the model.
tile(x, y)

Returns the tile at the (x,y) position in the tile-grid (not the (x,y) position of the simulation area).

Parameters:
  • x – The x-coordinate of the tile.
  • y – The y-coordinate of the tile.
unpause()

Unpauses the model. See Model.pause().

update_plots()

Updates all plots with the relevant data. Usually called in each iteration of the simulation (i.e. in a step function or similar).

wrapping()

Returns whether wrapping is enabled or not.

Cell-data file format

The two initial lines are skipped, and may be used to describe the cell-data or for other comments. The third line must contain a set of column names, seperated by tabs. The column names specify the names of variables stored by each tile. The first and second column cannot be used for variables, but must instead contain x and y coordinates, respectively.

The remaining lines of the file should then contain the coordinates and variable data. The start of a cell-data file might look like this:

This file contains cell data for a model where each cell/tile has some resource.
The data specifies the rate of resource production and max resource content for each cell.
x    y       prod    max_res
0    0       0.15    10.0
1    0       0.20    20.0
2    0       0.05    30.0
3    0       0.35    5.0
...