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]
-
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
, orGridRobot.STAY
- Raises
ValueError – If given direction is not one of GridRobot.UP`,
GridRobot.DOWN
,GridRobot.LEFT
,GridRobot.RIGHT
, orGridRobot.STAY