Grid

class Melodie.GridItem(agent_id: int, grid, x: int = 0, y: int = 0)

Bases: Agent

grid

A Grid that this GridItem belongs to.

x

Coordinate x on the grid, an int.

y

Coordinate y on the grid, an int.

class Melodie.GridAgent(agent_id: int, x: int = 0, y: int = 0, grid=None)

Bases: GridItem

category

Category indicating agent class, an int.

set_category() → int

Set the category of GridAgent.

As there may be more than one types of agent wandering around the grid, category is used to tell the type of GridAgent. So be sure to inherit this method in custom GridAgent implementation.

Returns:

int

rand_move_agent(x_range, y_range)

Randomly move to a new position within x and y range.

Returns:

None

class Melodie.Spot(spot_id: int, grid: Grid, x: int = 0, y: int = 0)

Bases: GridItem

get_spot_agents()

Get all agents on the spot.

Returns:

a list of grid agent.

class Melodie.Grid(spot_cls: ClassVar[Spot], scenario=None)

Bases: object

Grid is a widely-used discrete space for ABM. Grid contains many Spot`s, each `Spot could contain several agents.

Parameters:

  • spot_cls – The class of Spot

  • width – The width of Grid

  • height – The height of Grid

  • wrap – If true, the coordinate overflow will be mapped to another end.

  • caching – If true, the neighbors and bound check results will be cached to avoid re-computing.

setup_params(width: int, height: int, wrap=True, caching=True, multi=True)

Setup the parameters of grid.

Parameters:

  • width – int

  • height – int

  • wrap – bool, True by default.

If True, GridAgent will re-enter the grid on the other side if it moves out of the grid on one side. :param caching: bool, True by default. If true, the grid caches the neighbor of each spot. :param multi: bool, True by default. If true, more than one agent could stand on one spot. If false, error will be raised when attempting to place multiple agents on one spot. :return: None

setup()

Be sure to inherit this function.

Returns:

None

add_category(category_name: str)

Add agent category :param category_name: :return:

get_spot(x, y) → Spot

Get a Spot at position (x, y)

Parameters:

  • x –

  • y –

Returns:

The Spot at position (x, y)

get_agent_ids(category: str, x: int, y: int) → Set[int]

Get all agent of a specific category from the spot at (x, y) :param category: :param x: :param y: :return: A set of int, the agent ids.

coords_wrap(x, y)

Wrap the coordination :param x: :param y: :return:

add_agent(agent: GridAgent)

Add an agent to the grid

Parameters:

  • agent – An GridAgent object.

  • category – A string, the name of category. The category should be registered.

Returns:

remove_agent(agent: GridAgent)

Remove agent from the grid

Parameters:

agent –

Returns:

move_agent(agent: GridAgent, target_x, target_y)

Move agent to target position. :param agent_id: :param category: :param target_x: :param target_y: :return:

get_agent_pos(agent_id: int, category: str) → Tuple[int, int]

Get the agent position at the grid. :param agent_id: :param category: :return:

height()

Get the height of grid

Returns:

height, an int

width()

Get the width of grid

Returns:

width, an int

get_neighbors(agent: GridAgent, radius=1, moore=True, except_self=True)

Get the neighbors of one spot at (x, y).

Parameters:

  • x –

  • y –

  • radius –

  • moore –

  • except_self –

Returns:

A list of the tuple: (Agent category, Agent id).

get_spot_agents(spot: Spot)

Get agents on the spot.

get_colormap()

Get the role of each spot.

Returns:

A tuple. The first item is a nested list for spot roles, and the second item is a dict for agent roles.

spots_to_json()

Convert spots in this grid into a list of json-serializable dict

Returns:

JSON serializable list

get_empty_spots()

Get all empty spots from grid.

Returns:

a list of empty spot coordinates.

setup_agent_locations(category, initial_placement='direct') → None

Add an agent category.

For example, if there are two classes of agents: Wolf(GridAgent) and Sheep(GridAgent), and there are 100 agents with id 0~99 for each class. It is obvious in such a circumstance that we cannot identify an agent only with agent id.So it is essential to use category_name to distinguish two types of agents.

Parameters:

  • category_id – The id of new category.

  • category – An AgentList object

  • initial_placement – A str object stand for initial placement.

Returns:

None

set_spot_property(attr_name: str, array_2d)

Extract property values from a 2d-numpy-array and assign to each spot.

rand_move_agent(agent: GridAgent, category, range_x, range_y)

Randomly move an agent with maximum movement range_x in x axis and range_y in y axis.

Parameters:

  • agent – Must be Melodie.GridAgent, not Agent. That is because GridAgent has predefined properties required in Grid.

  • range_x – The activity range of agent on the x axis.

  • range_y – The activity range of agent on the y axis.

For example, if the agent is at (0, 0), range_x=1 and range_y=0, the result can be (-1, 0), (0, 0) or (1, 0). The probability of these three outcomes are equal.

Returns:

(int, int), the new position