Actor (Agent)

Bases: GeoAgent, _BaseObj, _LinkNodeActor

An actor in a social-ecological system (or "Agent" in an agent-based model.)

Attributes:

Name	Type	Description
breed		The breed of this actor (by default, class name).
layer	Optional[PatchModule]	The layer where the actor is located.
indices	Optional[PatchModule]	The indices of the cell where the actor is located.
pos	Optional[Pos]	The position of the cell where the actor is located.
on_earth	bool	Whether the actor is standing on a cell.
at	PatchCell | None	The cell where the actor is located.
link	PatchCell | None	The link manipulating proxy.
move	_Movements	The movement manipulating proxy.

Methods:

Name	Description
get	Gets the value of an attribute from the actor or its cell.
set	Sets the value of an attribute on the actor or its cell.
die	Kills the actor.

Source code in abses/actor.py

def __init__(
    self,
    model: MainModel[Any, Any],
    observer: bool = True,
    unique_id: Optional[UniqueID] = None,
    **kwargs,
) -> None:
    _BaseObj.__init__(self, model, observer=observer)
    crs = kwargs.pop("crs", model.nature.crs)
    geometry = kwargs.pop("geometry", None)
    mg.GeoAgent.__init__(
        self, unique_id, model=model, geometry=geometry, crs=crs
    )
    _LinkNodeActor.__init__(self)
    self._cell: Optional[PatchCell] = None
    self._decisions: _DecisionFactory = self._setup_decisions()
    self._alive: bool = True
    self._birth_tick: int = self.time.tick
    self._setup()

geo_type property

geo_type

The type of the geo info.

geometry property writable

geometry

The geometry of the actor.

alive property

alive

Whether the actor is alive.

decisions property

decisions

The decisions that this actor makes.

layer property

layer

Get the layer where the actor is located.

on_earth property

on_earth

Whether agent stands on a cell.

at deletable property writable

at

Get the cell where the agent is located.

pos property writable

pos

Position of the actor.

move cached property

move

A proxy for manipulating actor's location.

1. move.to(): moves the actor to another cell.
2. move.off(): removes the actor from the current layer.
3. move.by(): moves the actor by a distance.
4. move.random(): moves the actor to a random cell.

age

age()

Get the age of the actor.

Source code in abses/actor.py

@alive_required
def age(self) -> int:
    """Get the age of the actor."""
    return self.time.tick - self._birth_tick

get

get(attr, target=None)

Gets attribute value from target.

Parameters:

Name	Type	Description	Default
attr	str	The name of the attribute to get.	required
target	Optional[TargetName]	The target to get the attribute from. If None, the agent itself is the target. If the target is an agent, get the attribute from the agent. If the target is a cell, get the attribute from the cell.	None

Returns:

Type	Description
Any	The value of the attribute.

Source code in abses/actor.py

@alive_required
def get(
    self,
    attr: str,
    target: Optional[TargetName] = None,
) -> Any:
    """Gets attribute value from target.

    Parameters:
        attr:
            The name of the attribute to get.
        target:
            The target to get the attribute from.
            If None, the agent itself is the target.
            If the target is an agent, get the attribute from the agent.
            If the target is a cell, get the attribute from the cell.

    Returns:
        The value of the attribute.
    """
    if attr in self.dynamic_variables:
        return self.dynamic_var(attr)
    return super().get(attr=attr, target=target)

set

set(attr, value, target=None)

Sets the value of an attribute.

Parameters:

Name	Type	Description	Default
attr	str	The name of the attribute to set.	required
value	Any	The value to set the attribute to.	required
target	Optional[TargetName]	The target to set the attribute on. If None, the agent itself is the target. 1. If the target is an agent, set the attribute on the agent. 2. If the target is a cell, set the attribute on the cell.	None

Raises:

Type	Description
TypeError	If the attribute is not a string.
ABSESpyError	If the attribute is protected.

Source code in abses/actor.py

@alive_required
def set(
    self, attr: str, value: Any, target: Optional[TargetName] = None
) -> None:
    """Sets the value of an attribute.

    Parameters:
        attr:
            The name of the attribute to set.
        value:
            The value to set the attribute to.
        target:
            The target to set the attribute on. If None, the agent itself is the target.
            1. If the target is an agent, set the attribute on the agent.
            2. If the target is a cell, set the attribute on the cell.

    Raises:
        TypeError:
            If the attribute is not a string.
        ABSESpyError:
            If the attribute is protected.
    """
    super().set(attr=attr, value=value, target=target)

die

die()

Kills the agent (self)

Source code in abses/actor.py

@alive_required
def die(self) -> None:
    """Kills the agent (self)"""
    self.link.clean()  # 从链接中移除
    if self.on_earth:  # 如果在地上，那么从地块上移除
        self.move.off()
    self.model.agents.remove(self)  # 从总模型里移除
    self._alive = False  # 设置为死亡状态
    del self

setup

setup()

Overwrite this method. It should be called when the actor is initialized.

Source code in abses/actor.py

def setup(self) -> None:
    """Overwrite this method.
    It should be called when the actor is initialized.
    """

moving

moving(cell)

Overwrite this method. It should be called when the actor is moved. The return value is whether the actor can move to the cell.

Source code in abses/actor.py

def moving(self, cell: PatchCell) -> Optional[bool]:
    """Overwrite this method.
    It should be called when the actor is moved.
    The return value is whether the actor can move to the cell.
    """

Either select the agent according to specified criteria.

Parameters:

Name	Type	Description	Default
selection	Union[str, Dict[str, Any]]	Either a string or a dictionary of key-value pairs. Each represents agent attributes to be checked against.	required

Returns:

Type	Description
bool	Whether the agent is selected or not

Source code in abses/selection.py

def selecting(actor, selection: Union[str, Dict[str, Any]]) -> bool:
    """Either select the agent according to specified criteria.

    Parameters:
        selection:
            Either a string or a dictionary of key-value pairs.
            Each represents agent attributes to be checked against.

    Returns:
        Whether the agent is selected or not
    """
    if isinstance(selection, str):
        selection = parsing_string_selection(selection)
    results = []
    for k, v in selection.items():
        attr = getattr(actor, k, None)
        if attr is None:
            results.append(False)
        elif attr == v or str(attr) == v:
            results.append(True)
        else:
            results.append(False)
    return all(results)