Helipad.spatial( bool square = None, int x = 10, int y = None, bool wrap = True, bool|float diag = False )

Sets up functions, properties, and methods for spatial models. This function should be run before the control panel is drawn.

The function does several things:

1. Creates a patch primitive to represent map coordinates. In addition to the usual agent methods, the patch primitive has the following methods and properties:
   • patch.up(), patch.down(), patch.left(), and patch.right() — return the patch one over from the current patch in the specified direction.
   • patch.neighbors() — returns a list of the four (or eight, if diag==True) surrounding patches.
   • patch.agentsOn —  a list of all agents currently on the patch.
2. Creates a network named 'space' connecting each patch to its neighbors.
3. Adds a model.patches property, a dict of dicts by coordinates. A patch at coordinates (2,5) can be accessed using model.patches[2][5].
4. Adds movement methods and properties to agents of all primitives except patches, which cannot move.
   • agent.moveUp(), agent.moveDown(), agent.moveLeft(), and agent.moveRight() — move the agent one patch over starting from the current location.
   • agent.move(x, y) — moves the agent some number of patches over and some number of patches down.
   • agent.moveTo(x, y) or agent.moveTo(patch) — moves the agent to the patch located at (x,y) or the location of the patch.
   • agent.distanceFrom(agent) — calculates the spatial distance between the current agent and another.
   • agent.location — the current coordinates of the agent. Patches also have patch.location, but it cannot be modified. Integer locations correspond to the center of a patch, so the range of the x dimension is -0.5 to model.param('x')-0.5, and mutatis mutandis for y.
   • agent.orientation — the angle in degrees of the agent’s current heading.
   • agent.orientTo(agent) — Sets the agent’s orientation toward a particular patch or another agent.
   • agent.forward(steps) — Moves the agent some distance in the direction of its current orientation.
   • agent.patch — The patch that the agent is currently on.
5. Registers the Charts visualizer and a spatial plot upon it. The spatial plot object has a config() method that allows various aspects of the map to be customized. By default patches are displayed in a grid with colors corresponding to a specified parameter, and agents are displayed as dots of their breed color. The model.visual object can be used to display other chart plots alongside the spatial map. Note that functions calling model.spatial() do not then need to call model.useVisual().
6. Creates a 'dimension' parameter or 'x' and 'y' parameters for the size of the map, depending on if the map is set to square or not.
7. Creates an agentPosition hook that takes an agent object and the model object, and returns x,y coordinates. If not specified, agents are randomly positioned when instantiated.

This function is in pre-alpha and is not API stable. Backward-compatibility according to the deprecation policy is not guaranteed until the feature is finalized.

Parameters

• square — bool, optional

  Whether to link the height and width of the map together. square will be inferred to be True if y is not explicitly set.

  Default value: None

• x — int, optional

  The default width of the map.

  Default value: 10

• y — int, optional

  The default height of the map. If y is not specified, square will be inferred to be True. If square is explicitly set to True, y will be ignored.

  Default value: None

• wrap — bool, optional

  Whether patches at the edges of the map should be connected to patches on the opposite edge.

  Default value: True

• diag — bool|float, optional

  Whether to connect patches to their diagonals, and if so, the weight of the connection (between 0 and 1).

  Default value: False

Return Value — SpatialPlot

The SpatialPlot object, subclass of ChartPlot, which can be used to customize various aspects of the map visualization.