Robots

Gridsim provides two levels of abstract robot classes. The first, Robot, is designed to allow a user full control over their robot platform, specifying to communication criteria and allowed movements.

To get started faster, GridRobot implements a simple movement protocol and communication criterion, allowing the user to quickly start implementing their own code on the GridRobot platform.

For details on extending the Robot classes to create your own, see Make your own Robot.

class gridsim.robot.Robot(x: int, y: int)

Abstract base class for all robot classes

Parameters
  • x (int) – Starting x position (grid cell) of the robot

  • y (int) – Starting y position (grid cell) of the robot

abstract comm_criteria(dist_sqr: int) → bool

Criterion for whether messages can be communicated (based on distance).

Note

This takes the squared distance instead of the distance, because it is much less computationally expensive to compute. If you need to take the square root, you can do so here, but because this function is called so much, it will be slow. Instead, consider comparing to the squared communication range.

Note

For simplicity and speed, communication criterion is assumed to be symmetric; therefore, this should return the same value regardless of whether this is called by the sending or receiving robot.

Parameters

dist_sqr (int) – SQUARED distance between this robot and the other robot

Returns

Whether or not the other robot is within communication range

Return type

bool

distance(pos: Tuple[int, int]) → float

Get the Euclidean distance (in grid cells) between this robot and the specified (x, y) grid cell position.

If you want to change the distance metric (e.g., use Manhattan distance instead), you can override this method when you extend the Robot class.

Parameters

pos (Tuple[int, int]) – (x, y) grid cell coordinate to get the distance to

Returns

Euclidean distance of this robot from the given coordinate

Return type

float

get_pos() → Tuple[int, int]

Get the position of the robot in the grid

Returns

(x, y) grid position of the robot, from the top left

Return type

Tuple[int, int]

get_tick() → int

Get the current tick of the robot (how many steps since the simulation started).

Returns

Number of ticks since start of simulation

Return type

int

get_world_dim() → Tuple[int, int]

Get the dimensions of the World that this Robot is in, so it can plan to avoid hitting the boundaries.

Returns

(width, height) dimensions of the world, in grid cells

Return type

Tuple[int, int]

Raises

ValueError – Cannot get dimensions if Robot is not in a World. Add it during creation of a World or with add_robot().

id: int = None

Unique ID of the Robot

abstract init()

Robot-specific initialization that will be run when the robot is set up.

This is called when a Robot is added to a :class:gridsim.world.World`.

abstract loop()

User-implemented loop operation (code the robot runs every loop)

abstract move() → Tuple[int, int]

User-facing move command, essentially sending a request to move to a particular cell.

The robot will only make this move if it doesn’t violate any movement conditions (such as edge of arena or, if enabled, collisions with other robots). Therefore, you do NOT need to implement any collision or edge-of-arena detection in this function.

Returns

(x, y) grid cell position the robot intends to move to

Return type

Tuple[int, int]

msg_received()

This is called when a robot successfully sent its message (i.e., when another robot received its message.)

By default, this does nothing. You can override it in your robot class to execute some operation or set a flag when a message is sent.

abstract receive_msg(msg: Message, dist_sqr: float)

Function called when the robot receives a message. This allows the specific robot implementation to choose how to process the messages that it receives, asynchronously.

Note

This used the squared distance instead of distance. To understand why, see comm_criteria().

Parameters
  • msg (Message) – Received message from another robot

  • dist_sqr (float) – Squared distance of the sending robot from this robot

sample(pos: Optional[Tuple[int, int]] = None, tag: Optional[Tuple[int, int, int]] = None) → Optional[Tuple[float, float, float]]

Sample the RGB environment at the given cell location, or (if no pos given) and the robot’s current position.

This allows you to sample any location in the World, but this is probably cheating. The robot platform you’re modeling likely doesn’t have such extensive sensing capabilities. This function is provided so that you can define any custom sensing capabilities (such as within a radius around your robot, or a line of sight sensor).

Parameters
  • pos (Tuple[int, int], optional) – (x, y) grid cell position of the World to sample. If not specified, the current robot position is sampled.

  • tag (Tuple[int, int, int], optional) – RGB color to tag this position in the World, by default None. If not provided, the cell in the World won’t be tagged with any color. Otherwise, there will be a semi-transparent overlay with the given color in that cell in the World. This is primarily for use with the Viewer, to visualize what has been sampled in the World.

Returns

(red, green, blue) color at the given coordinate in the range [0, 255]. If the world doer not have an environment set, this will return (0, 0, 0). If the given position is outside the boundaries of the World, it will return None.

Return type

Tuple[float, float, float] or None

set_color(r: int, g: int, b: int)

Set the color of the robot (as shown in Viewer) with 8-bit RGB values

Parameters
  • r (int) – Red channel [0, 255]

  • g (int) – Green channel [0, 255]

  • b (int) – Blue channel [0, 255]

Raises

ValueError – If all values are not in the range [0, 255]

set_tx_message(msg: Message)

Set the message that will be continuously broadcast. To enable communication, use this function to send a non-empty Message. (i.e., a message that doesn’t use the empty constructor.)

Parameters

msg (Message) – Message to send to anyone within range

class gridsim.grid_robot.GridRobot(x: int, y: int, comm_range: float = 5)

A robot that moves along the cardinal directions, with customizable communication range.

It provides constants for moving up, down, left, and right.

Parameters
  • x (int) – Starting x position (grid cell) of the robot

  • y (int) – Starting y position (grid cell) of the robot

  • comm_range (float, optional) – Communication radius (in grid cells) of the robot, by default 5

DOWN = 'down'

Robot moves down 1 cell (increase y position by 1)

LEFT = 'left'

Robot moves left 1 cell (decrease x position by 1)

RIGHT = 'right'

Robot moves right 1 cell (increase x position by 1)

STAY = 'stay'

Robot stays where it is

UP = 'up'

Robot moves up 1 cell (decrease y position by 1)

comm_criteria(dist_sqr: int) → bool

Robots can communicate if their Euclidean distance is <= the radius specified at initialization (by default, 5 cells)

Parameters

dist_sqr (int) – Squared Euclidean distance of the other robot with which to communicate

Returns

Whether distance is <= the communication radius

Return type

bool

move() → Tuple[int, int]

Determine the cell the Robot will move to, based on the direction set in by set_motors().

Returns

(x,y) grid cell the robot will move to, if possible/allowed

Return type

Tuple[int, int]

set_direction(dir: str)

Helper function to set the direction the robot will move. Note that this will persist (the robot will keep moving) until the direction is changed.

Parameters

dir (int) – Direction to move, one of GridRobot.UP, GridRobot.DOWN, GridRobot.LEFT, GridRobot.RIGHT, or GridRobot.STAY

Raises

ValueError – If given direction is not one of GridRobot.UP`, GridRobot.DOWN, GridRobot.LEFT, GridRobot.RIGHT, or GridRobot.STAY