Movements

abses.space.move._Movements

_Movements(actor)

A class that handles actor movement in the simulation.

This class provides methods for moving actors between cells in the simulation grid. It handles basic movement operations like moving to specific coordinates, moving in directions, and random movement.

Attributes:

Name	Type	Description
actor		The actor instance this movement handler belongs to.
model		The model instance this movement handler operates in.
seed		Unique identifier for the actor, used for random number generation.

Source code in abses/space/move.py

def __init__(self, actor: Actor) -> None:
    self.actor = actor
    self.model = actor.model
    self.seed = actor.unique_id

layer property

layer

The current layer of the operating actor.

to

to(to=None, layer=None, indices=False)

Move the actor to a specific location.

Parameters:

Name	Type	Description	Default
to	PatchCell | Coordinate | Literal['random'] | None	The position to move to. If position is a Coordinate -a tuple of (row, col), it will be moved to the same layer. If pos is None, the actor will be removed from the world.	None
indices	bool	The indices to move to.	False
layer	Optional[PatchModule]	The layer where the actor is located. If layer is None, the actor will be moved to the same layer as the actor's current layer.	None
indices	bool	Whether the position is indices. If indices is True, the position is indices. If indices is False, the position is position.	False

Raises:

Type	Description
ABSESpyError	If the input layer is not consistent with the actor's layer. If the position is out of bounds. Or, if the pos is coordinate without layer.

Source code in abses/space/move.py

def to(
    self,
    to: PatchCell | Coordinate | Literal["random"] | None = None,
    layer: Optional[PatchModule] = None,
    indices: bool = False,
) -> None:
    """
    Move the actor to a specific location.

    Parameters:
        to:
            The position to move to.
            If position is a Coordinate -a tuple of (row, col),
            it will be moved to the same layer.
            If pos is None, the actor will be removed from the world.
        indices:
            The indices to move to.
        layer:
            The layer where the actor is located.
            If layer is None, the actor will be moved to the same layer as the actor's current layer.
        indices:
            Whether the position is indices.
            If indices is True, the position is indices.
            If indices is False, the position is position.

    Raises:
        ABSESpyError:
            If the input layer is not consistent with the actor's layer.
            If the position is out of bounds.
            Or, if the pos is coordinate without layer.
    """
    if isinstance(to, PatchCell):
        self._layer_is_consistent(to.layer)
        _put_agent_on_cell(self.actor, to)
        return
    if layer is None and self.layer is None:
        raise ABSESpyError("No operating layer is specified.")
    layer = self._operating_layer(layer=layer)
    if to == "random":
        cell = cast(PatchCell, layer.cells_lst.random.choice())
        _put_agent_on_cell(self.actor, cell)
        return
    if isinstance(to, tuple) and len(to) == 2:
        x, y = to
        if indices:
            cell = layer.array_cells[x, y]
        else:
            cell = layer.cells[x][y]
        _put_agent_on_cell(self.actor, cell)
        return
    # 检查这个位置的类型，返回图层和位置
    raise TypeError(f"Invalid position type {to}.")

off

off()

Remove the actor from the world.

Raises:

Type	Description
ABSESpyError	If the actor is not located on a cell, thus cannot move.

Source code in abses/space/move.py

def off(self) -> None:
    """Remove the actor from the world.

    Raises:
        ABSESpyError:
            If the actor is not located on a cell, thus cannot move.
    """
    if self.actor.at is None:
        return
    if hasattr(self.actor.at, "agents"):
        self.actor.at.agents.remove(self.actor)
    del self.actor.at

by

by(direction, distance=1)

Move the actor by a specific distance.

Parameters:

Name	Type	Description	Default
direction	MovingDirection	The direction to move. It should be a direction string such as: "left", "right", "up", "down", "up left", "up right", "down left", "down right".	required
distance	int	The distance to move toward the direction.	1

Raises:

Type	Description
ABSESpyError	If the actor is not located on a cell, thus cannot move.
ValueError	If the direction is invalid.

Source code in abses/space/move.py

@alive_required
def by(self, direction: MovingDirection, distance: int = 1) -> None:
    """Move the actor by a specific distance.

    Parameters:
        direction:
            The direction to move.
            It should be a direction string such as:
            "left", "right", "up", "down", "up left", "up right", "down left", "down right".
        distance:
            The distance to move toward the direction.

    Raises:
        ABSESpyError:
            If the actor is not located on a cell, thus cannot move.
        ValueError:
            If the direction is invalid.
    """
    if (self.actor.at is None) or (self.layer is None):
        raise ABSESpyError("The actor is not located on a cell, thus cannot move.")
    old_row, old_col = self.actor.at.indices
    if direction == "left":
        new_indices = (old_row, old_col - distance)
    elif direction == "right":
        new_indices = (old_row, old_col + distance)
    elif direction == "up":
        new_indices = (old_row - distance, old_col)
    elif direction == "down":
        new_indices = (old_row + distance, old_col)
    elif direction in {"up left", "left up"}:
        new_indices = (old_row - distance, old_col - distance)
    elif direction in {"up right", "right up"}:
        new_indices = (old_row - distance, old_col + distance)
    elif direction in {"down left", "left down"}:
        new_indices = (old_row + distance, old_col - distance)
    elif direction in {"down right", "right down"}:
        new_indices = (old_row + distance, old_col + distance)
    else:
        raise ValueError(f"Invalid direction {direction}.")
    cell = self.layer.array_cells[new_indices[0], new_indices[1]]
    self.actor.move.to(cell, indices=True)

random

random(prob=None, **kwargs)

Move the actor to a random location nearby.

Parameters:

Name	Type	Description	Default
prob	Optional[str]	The probability to select a cell.	None
kwargs	Any	Passing keyword args to PatchCell.neighboring, used to select neighboring cells.	{}

Source code in abses/space/move.py

@alive_required
def random(self, prob: Optional[str] = None, **kwargs: Any) -> None:
    """Move the actor to a random location nearby.

    Parameters:
        prob:
            The probability to select a cell.
        kwargs:
            Passing keyword args to `PatchCell.neighboring`,
            used to select neighboring cells.
    """
    if self.actor.at is None:
        raise ABSESpyError("The actor is not located on a cell.")
    cells = self.actor.at.neighboring(**kwargs)
    self.actor.move.to(cells.random.choice(prob=prob))