fr.lifl.jedi.model
Class Agent

java.lang.Object
  extended by java.util.Observable
      extended by fr.lifl.jedi.model.Agent
All Implemented Interfaces:
java.util.Observer

public abstract class Agent
extends java.util.Observable
implements java.util.Observer

This class represents an agent family -- i.e. an entity of the simulated phenomenon -- in the JEDI simulation framework.

Agents position in the environment

In JEDI, agents are physically represented in the environment with a rectangle surface (see getSurface()), for which :

Both have a double precision. This surface is used as a bounding box :

Agents direction and position

An agent can move according to its direction (see getDirection()), which is expressed in degrees. The methods getXPosition() and getYPosition() define the current position of the center of the agent (the center of its surface). The methods getPreviousXposition() and getPreviousYposition() define the position that the agent had at the beginning of the time step.

Agents Behavior

An agent updates (see update()) its state at the beginning of a time step, before that any agent performs its interaction selection process.

In summary, the behavior of an agent is decomposed as following.
If the agent has the ability to initiate at least one interaction :

  1. It first perceives its neighboring agents;
  2. For every priority of the interaction matrix in decreasing order :
    1. The agent checks which interactions of a particular priority are possible with agents from the neighborhood. This leads to the construction of a AbstractRealizableTuple set.
    2. The agent uses an interaction selection policy (see InteractionSelectionPolicy) to select a tuple from this set.

      If no tuple was selected, then the priority is decreased, otherwise, the loop is over.

  3. If a tuple was selected, the agent initiates the corresponding interaction.

An agent interacts only with the agents it perceives. In JEDI, perceiving the set of neighboring agents is made in the method perceive(Environment, Set).

An agent perceives all agents that lie in a particular surface of the environment. This surface is built thanks to the tools provided in the singleton class HaloBuilder.

The behavior of an agent (and its interaction selection process) is defined by its interaction matrix line. Please see getInteractionMatrixLine() and InteractionMatrixLine for more informations.

The method getInitiatedInteraction()} returns the interaction the agent initiated -- an instance of the AbstractRealizableTuple class -- during the current simulation step. Obviously, the value it returns is consistent only at the end of a simulation step.

Version:
JEDI V 2.2
Created the 30th oct. 2008
Modified the 4th may 2009
Author:
Yoann Kubera
SMAC Team (Systèmes Multi-Agents et Comportement)
LIFL (Laboratoire d'Informatique Fondamentale de Lille)
University of Lille, France

Field Summary
protected  java.awt.geom.Rectangle2D.Double surface
           For various reasons, an agent has to define the surface of the environment it occupies, for instance to avoid collisions with other agents.
 
Constructor Summary
Agent(double width, double height, InteractionMatrixLine line)
          Constructor of the agent, that specifies the width and the height of the surface occupied by the agent.
Agent(double width, double height, PhysicalHalo halo, InteractionMatrixLine line)
          Constructor of the agent, that specifies the width and the height of the surface occupied by the agent.
Agent(InteractionMatrixLine line)
          Constructor of the agent, that makes the assumption that an agent is a point.
Agent(PhysicalHalo halo, InteractionMatrixLine line)
          Constructor of the agent, that makes the assumption that an agent is a point.
 
Method Summary
 void afterStep()
          Does some post-processing, after the end of the behavior of agents.
 void agentUpdate()
          Method called by the simulation core in order to update the agent.
 void beforeStep()
          Does some pre-processing, before starting the behavior of agents.
 double getDirection()
          Gets the direction of the agent.
 PhysicalHalo getHalo()
          Gets the halo of the agent -- i.e.
 double getHeight()
          Gets the height of the agent.
 AbstractRealizableTuple<?> getInitiatedInteraction()
          Gets the tuple that represents the interaction that was initiated by the agent during the simulation step.
 InteractionMatrixLine getInteractionMatrixLine()
          Gets the interaction matrix line of the agent.
 double getPreviousXposition()
          Gets the x coordinate of the position where the agent was at the beginning of the time step.
 double getPreviousYposition()
          Gets the y coordinate of the position where the agent was at the beginning of the time step.
 java.awt.geom.Rectangle2D.Double getSurface()
           For various reasons, an agent has to define the surface of the environment it occupies, for instance to avoid collisions with other agents.
 double getWidth()
          Gets the width of the agent.
 double getXPosition()
          Gets the position of the agents surface center along the x axis.
 double getYPosition()
          Gets the position of the agents surface center along the y axis.
 boolean isActivable()
          This method gets if the agent is activable.
 boolean isInEnvironment()
          Checks if the agent is in the environment.
 boolean isObstacle()
          Checks if the agent is considered as an obstacle.
 boolean isSensitiveToObstacles()
          Checks if the agent is sensitive to obstacles.
protected  void perceive(Environment e, java.util.Set<Agent> neighbors)
          Triggers the perception phase of the agent.
 void setDirection(double d)
          Sets the direction of the agent.
 void setHalo(PhysicalHalo halo)
          Sets the halo of the agent -- i.e.
 void setInEnvironment(boolean b)
          Sets if the agent is in the environment.
 void setInteractionMatrixLine(InteractionMatrixLine line)
          Sets the interaction matrix line of the agent.
 void setNotActivable()
          Set the agent as not activable.
 void setObstacle(boolean b)
          Tells if the agent is considered as an obstacle.
 void setSensitiveToObstacles(boolean b)
          Tells if the agent is sensitive to obstacles.
 void step(Environment e)
          Makes the agent behave, according to its interaction matrix line.
 java.lang.String toString()
           
protected abstract  void update()
          Updates the state of the agent.
 void update(java.util.Observable o, java.lang.Object not)
           
 
Methods inherited from class java.util.Observable
addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

surface

protected java.awt.geom.Rectangle2D.Double surface

For various reasons, an agent has to define the surface of the environment it occupies, for instance to avoid collisions with other agents.

JEDI makes the assumption that this surface is a rectangle :

The only entity that will manipulate this value is the environment class.

Constructor Detail

Agent

public Agent(double width,
             double height,
             PhysicalHalo halo,
             InteractionMatrixLine line)
Constructor of the agent, that specifies the width and the height of the surface occupied by the agent.

By default, agents are neither sensitive to obstacles nor obstacles, and their direction points to the north (is equal to 0).

Parameters:
width - the width of the surface occupied by the agent.
height - the height of the surface occupied by the agent.
halo - the halo of the agent, i.e. a surface where the agent perceives other agents. The halo is built thanks to the HaloBuilder class.
line - the interaction matrix line of the agent.

It defines :

  • what interactions the agent is able to initiate with other agent families as target.
  • the priorities among the interactions the agent can initiate. An agent tries to perform interactions in decreasing values of priorities.

It can be null if the agent has no behavior.

See Also:
InteractionMatrixLine, HaloBuilder

Agent

public Agent(double width,
             double height,
             InteractionMatrixLine line)
Constructor of the agent, that specifies the width and the height of the surface occupied by the agent.

By default, agents are neither sensitive to obstacles nor obstacles, and their direction points to the north (is equal to 0).

With such a constructor, agents do not perceive other agents from the environment.

Parameters:
width - the width of the surface occupied by the agent.
height - the height of the surface occupied by the agent.
line - the interaction matrix line of the agent.

It defines :

  • what interactions the agent is able to initiate with other agent families as target.
  • the priorities among the interactions the agent can initiate. An agent tries to perform interactions in decreasing values of priorities.

It can be null if the agent has no behavior.

See Also:
InteractionMatrixLine, HaloBuilder

Agent

public Agent(PhysicalHalo halo,
             InteractionMatrixLine line)
Constructor of the agent, that makes the assumption that an agent is a point.

By default, agents are neither sensitive to obstacles nor obstacles, and their direction points to the north (is equal to 0).

Parameters:
line - the interaction matrix line of the agent.

It defines :

  • what interactions the agent is able to initiate with other agent families as target.
  • the priorities among the interactions the agent can initiate. An agent tries to perform interactions in decreasing values of priorities.

It can be null if the agent has no behavior.

halo - the halo of the agent, i.e. a surface where the agent perceives other agents. The halo is built thanks to the HaloBuilder class.
See Also:
InteractionMatrixLine

Agent

public Agent(InteractionMatrixLine line)
Constructor of the agent, that makes the assumption that an agent is a point.

By default, agents are neither sensitive to obstacles nor obstacles, and their direction points to the north (is equal to 0).

With such a constructor, agents do not perceive other agents from the environment.

Parameters:
line - the interaction matrix line of the agent.

It defines :

  • what interactions the agent is able to initiate with other agent families as target.
  • the priorities among the interactions the agent can initiate. An agent tries to perform interactions in decreasing values of priorities.

It can be null if the agent has no behavior.

See Also:
InteractionMatrixLine
Method Detail

getHalo

public PhysicalHalo getHalo()
Gets the halo of the agent -- i.e. the surface from the environment in which other agents are considered as perceived.

Returns:
the halo of the agent.

setHalo

public void setHalo(PhysicalHalo halo)
Sets the halo of the agent -- i.e. the surface from the environment in which other agents are considered as perceived -- to a particular surface.

Parameters:
halo - the surface that represents what agents perceive.

Halo are created thanks to the HaloBuilder singleton.


getInteractionMatrixLine

public InteractionMatrixLine getInteractionMatrixLine()
Gets the interaction matrix line of the agent.

It defines :

It can be null if the agent has no behavior.

See Also:
InteractionMatrixLine

setInteractionMatrixLine

public void setInteractionMatrixLine(InteractionMatrixLine line)
Sets the interaction matrix line of the agent.

Parameters:
line - the new interaction matrix line of the agent.

It defines :

  • what interactions the agent is able to initiate with other agent families as target.
  • the priorities among the interactions the agent can initiate. An agent tries to perform interactions in decreasing values of priorities.

It can be null if the agent has no behavior.

See Also:
InteractionMatrixLine

isObstacle

public boolean isObstacle()
Checks if the agent is considered as an obstacle.

Returns:
true, then other agents that are sensitive to obstacles cannot move onto its position.
See Also:
isSensitiveToObstacles()

setObstacle

public void setObstacle(boolean b)
Tells if the agent is considered as an obstacle.

Parameters:
b - If true, then other agents that are sensitive to obstacles cannot move onto its position.
See Also:
isSensitiveToObstacles()

isSensitiveToObstacles

public boolean isSensitiveToObstacles()
Checks if the agent is sensitive to obstacles.

Returns:
true, then the agent cannot move onto a position if its surface will intersect the surface of an obstacle agent.
See Also:
isObstacle()

setSensitiveToObstacles

public void setSensitiveToObstacles(boolean b)
Tells if the agent is sensitive to obstacles.

Parameters:
b - true, then the agent cannot move onto a position if its surface will intersect the surface of an obstacle agent.
See Also:
isObstacle()

getSurface

public java.awt.geom.Rectangle2D.Double getSurface()

For various reasons, an agent has to define the surface of the environment it occupies, for instance to avoid collisions with other agents.

JEDI makes the assumption that this surface is a rectangle :

The only entity that will manipulate this value is the environment class. Do not call this method in another context. Call instead the methods getXPosition(), getYPosition(), getWidth() and getHeight().

Returns:
the surface that represents the agent.

getXPosition

public double getXPosition()
Gets the position of the agents surface center along the x axis.

Returns:
the position of the agents surface center along the x axis.

getYPosition

public double getYPosition()
Gets the position of the agents surface center along the y axis.

Returns:
the position of the agents surface center along the y axis.

getPreviousXposition

public double getPreviousXposition()
Gets the x coordinate of the position where the agent was at the beginning of the time step.

Returns:
the x coordinate of the position where the agent was at the beginning of the time step.

getPreviousYposition

public double getPreviousYposition()
Gets the y coordinate of the position where the agent was at the beginning of the time step.

Returns:
the y coordinate of the position where the agent was at the beginning of the time step.

getWidth

public double getWidth()
Gets the width of the agent. This width corresponds to the width of the surface of the agent.

Returns:
the width of the agent.

getHeight

public double getHeight()
Gets the height of the agent. This height corresponds to the height of the surface of the agent.

Returns:
the height of the agent.

isInEnvironment

public boolean isInEnvironment()
Checks if the agent is in the environment.

This value is used for optimization purpose only.

The only entities that will manipulate this attribute are the Environment and SimulationThread classes.

Returns:
true if the agent is in the environment.

setInEnvironment

public void setInEnvironment(boolean b)
Sets if the agent is in the environment.

This value is used for optimization purpose only.

The only entities that will manipulate this attribute are the Environment and SimulationThread classes.

Parameters:
b - true if the agent is in the environment.

getDirection

public double getDirection()
Gets the direction of the agent.

It belongs to the interval [-180; 180[, and corresponds to the angle expressed counterclockwise from the (0;1) vector.

Thus :

Returns:
the direction of the agent.

setDirection

public void setDirection(double d)
Sets the direction of the agent.

It belongs to the interval [-180; 180[, and corresponds to the angle expressed counterclockwise from the (0;1) vector.

Thus :

Parameters:
d - the new direction of the agent.

isActivable

public boolean isActivable()
This method gets if the agent is activable.

This method returns false if :

The value returned by this method determines if the agent is allowed to participate in the interaction during the time step.

It makes possible to forbid an agent to participate in more than one interaction during a simulation step.

Returns:
true if the agent is activable. In such a case, the agent can participate in any interaction as a source or as a target. If false, it can only be the target of a SingleTargetInteraction, which SingleTargetInteraction.requiresActivableTarget() method returns false.

setNotActivable

public void setNotActivable()
Set the agent as not activable.

If this method is called, the can only be the target of a SingleTargetInteraction, which SingleTargetInteraction.requiresActivableTarget() method returns false until the end of the simulation step.

This method is called only by the simulation core, and has not to be called by the user.


beforeStep

public void beforeStep()
Does some pre-processing, before starting the behavior of agents. By default, this method is empty.


afterStep

public void afterStep()
Does some post-processing, after the end of the behavior of agents. By default, this method is empty.


update

protected abstract void update()
Updates the state of the agent.

An agent updates its state at the beginning of a time step, before that any agent performs its interaction selection process.


agentUpdate

public void agentUpdate()
Method called by the simulation core in order to update the agent.

This method calls update(), and also makes some processing.


perceive

protected void perceive(Environment e,
                        java.util.Set<Agent> neighbors)
Triggers the perception phase of the agent. During this phase, the agent will list all agents it can see in the environment.

An agent sees all agents that lie in a particular surface of the environment. This surface is built thanks to the tools provided in the singleton class HaloBuilder.

Parameters:
e - The environment in which perception is made.
neighbors - The list where neighboring agents are added.

getInitiatedInteraction

public AbstractRealizableTuple<?> getInitiatedInteraction()
Gets the tuple that represents the interaction that was initiated by the agent during the simulation step.

Returns:
the tuple that represents the interaction that was initiated by the agent during the simulation step.

step

public void step(Environment e)
Makes the agent behave, according to its interaction matrix line.

If the agent has the ability to initiate at least one interaction :

  1. It first perceives its neighboring agents;
  2. For every priority of the interaction matrix in decreasing order :
    1. The agent checks which interactions of a particular priority are possible with agents from the neighborhood. This leads to the construction of a AbstractRealizableTuple set.
    2. The agent uses an interaction selection policy (see InteractionSelectionPolicy) to select a tuple from this set.

      If no tuple was selected, then the priority is decreased, otherwise, the loop is over.

  3. If a tuple was selected, the agent initiates the corresponding interaction.

Parameters:
e - The environment where the simulation takes place.
See Also:
InteractionMatrixLine

update

public void update(java.util.Observable o,
                   java.lang.Object not)
Specified by:
update in interface java.util.Observer
See Also:
Observer.update(java.util.Observable, java.lang.Object)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object
See Also:
Object.toString()