Package com.amalgamasimulation.graphagent

Class GraphAgent<N extends AgentGraphNode,A extends AgentGraphArc>

java.lang.Object
com.amalgamasimulation.graphagent.GraphAgent<N,A>
Type Parameters:
N - type of values stored in graph nodes
A - type of values stored in graph arcs
All Implemented Interfaces:
Agent, Timeable
Direct Known Subclasses:
LongAgent, LongAgentTail
public class GraphAgent<N extends AgentGraphNode,A extends AgentGraphArc> extends Object implements Agent
Class representing an agent that lives and moves inside a GraphEnvironment.
Author:
Andrey Malykhanov

  • Field Details

    • lastTrajectoryNodeIndex

      protected int lastTrajectoryNodeIndex

    • lastTrajectoryPointIndex

      protected int lastTrajectoryPointIndex

    • basis

      protected int basis

    • engine

      protected Engine engine

  • Constructor Details

    • GraphAgent

      public GraphAgent(Engine engine)
      Creates a new instance of GraphAgent that is simulated with the specified Engine.
      Parameters:
      engine - specified engine

  • Method Details

    • time

      public double time()
      Description copied from interface: Agent
      Returns the current simulation time
      Specified by:
      time in interface Agent
      Returns:
      current simulation time

    • getCurrentNode

      public Graph<N,A>.Node getCurrentNode()
      Returns the node where this agent is currently located, or null if this agent is not currently located at a node
      Returns:
      node where this agent is currently located, or null

    • getCurrentArc

      public Graph<N,A>.Arc getCurrentArc()
      Returns the arc on which this agent is currently located, or null if this agent is not currently located on an arc
      Returns:
      arc on which this agent is currently located, or null
      See Also:

    • getCurrentArcAbsOffset

      public double getCurrentArcAbsOffset()
      Returns the non-negative absolute offset of position on arc where this agent is currently located, or -1 if this agent is not currently located on an arc
      Returns:
      absolute offset of position on arc where this agent is currently located, or -1
      See Also:

    • getCurrentAnimationPoint

      public Point getCurrentAnimationPoint()
      Returns the current Point in 2D space pointing to the current location of this agent, or a point with infinite coordinates (new Point(Double.POSITIVE_INFINITY, Double.POSITIVE_INFINITY) if this agent is not currently in graph.

      This method must be called from animation when it is needed to determine where to show this agent. Calling getCurrentPoint() from animation might result in non-reproducibility of the model.

      Returns:
      current Point in 2D space pointing to the current location of this agent, or a point with infinite coordinates

    • getCurrentPosition

      public GeometricGraphPosition<N,A> getCurrentPosition()
      Returns current position of this agent in form of GeometricGraphPosition, or null if this agent is not currently in graph
      Returns:
      GeometricGraphPosition pointing to current position of this agent, or null
      See Also:

    • getGraphPath

      public AgentGraphPath<N,A> getGraphPath()
      Returns the current path of this agent in form of AgentGraphPath, or null if this agent has currently no path
      Returns:
      current path of this agent in form of AgentGraphPath, or null

    • getTrajectory

      public Polyline getTrajectory()
      Returns the current remaining trajectory of this agent, i.e. the Polyline ahead of this agent that it will travel according to its path. Returned polyline includes the current Segment and all segments ahead of this agent. Returns null if this agent has currently no path
      Returns:
      Polyline representing the remaining trajectory of this agent, or null

    • setVelocity

      public void setVelocity(double newVelocity)
      Sets the new velocity to this agent. If this agent is moving and the specified new velocity does not equal to agent's current velocity, this agent's velocity gets changed immediately.

      Positive velocity can only be set if this agent has its path (i.e. hasPath() == true). Otherwise, a RuntimeException is thrown

      Negative and infinite velocities are not allowed. If such value is passed, a RuntimeException is thrown

      Parameters:
      newVelocity - - specified velocity
      See Also:

    • getVelocity

      public double getVelocity()
      Returns the current velocity of this agent, or zero if this agent is not moving
      Returns:
      current velocity of this agent

    • isMoving

      public boolean isMoving()
      Checks whether this agent is currently moving, i.e. its velocity is greater than zero (getVelocity()>0)
      Returns:
      true is this agent is moving, false otherwise
      See Also:

    • cancelMoving

      public void cancelMoving()
      Stops this agent and forgets its moving path and target. More specifically:
    • If this agent is moving, stops moving
    • If this agent has a path (even if this agent is not moving), erases this path, sets the path to null
    • If this agent does not have a path, does nothing
      • See Also:

    • moveTo

      public CompletionStage<Void> moveTo(GeometricGraphPosition<N,A> destPosition, double velocity)
      Starts moving this agent to the specified destination position in the graph with the specified velocity along the shortest path from agent's current position.

      The shortest path is calculated with respect to weights of arcs and nodes set in agent's GraphEnvironment.

      If this agent is currently moving somewhere else, it forgets its current destination and is assigned a new path.

      If zero velocity is specified, the path is set to this agent, but it just does not start moving. It can start moving when setVelocity(double) is called with a positive value.

      If no path is found from agent's current position to the specified position, onPathNotFound(List) method is called. The default implementation of this method throws a RuntimeException, but it can be overridden in subclasses.

      If this agent is not in graph or has not been assigned to a GraphEnvironment, a RuntimeException is thrown.

      Parameters:
      destPosition - specified destination position in the graph of this agent's GraphEnvironment
      velocity - specified velocity. Must be finite and non-negative
      See Also:

    • moveToClosest

      public CompletionStage<Void> moveToClosest(List<GeometricGraphPosition<N,A>> destPositions, double velocity)
      Starts moving this agent to the closest one of the specified destination positions in the graph with the specified velocity along the shortest path from this agent's current position.

      Closeness and shortest path are determined with respect to weights of arcs and nodes set in agent's GraphEnvironment.

      If this agent is currently moving somewhere else, it forgets its current destination and is assigned a new path.

      If zero velocity is specified, the path is set to this agent, but it just does not start moving. It can start moving when setVelocity(double) is called with a positive value.

      If no path is found from agent's current position to either of the specified positions, onPathNotFound(List) method is called. The default implementation of this method throws a RuntimeException, but it can be overridden in subclasses.

      If this agent is not in graph or has not been assigned to a GraphEnvironment, a RuntimeException is thrown.

      Parameters:
      destPositions - list of destination positions in the graph of this agent's GraphEnvironment, from which the closest one is selected
      velocity - specified velocity. Must be finite and non-negative
      See Also:

    • jumpTo

      public CompletionStage<Void> jumpTo(GeometricGraphPosition<N,A> position)
      Jumps this agent to the specified position. If this agent is moving or has a path, cancels its movement and forgets its path before jumping.
      Parameters:
      position - position in the graph of this agent's GraphEnvironment where this agent will be placed

    • jumpTo

      public CompletionStage<Void> jumpTo(Graph<N,A>.Node node)
      Jumps this agent to the specified node of graph of this agent's GraphEnvironment. If this agent is moving or has a path, cancels its movement and forgets its path before jumping.
      Parameters:
      node - node of the graph of this agent's GraphEnvironment where this agent will be placed

    • jumpTo

      public CompletionStage<Void> jumpTo(Graph<N,A>.Arc arc, double arcAbsOffset)
      Jumps this agent to the specified absolute offset of the specified arc of graph of this agent's GraphEnvironment. If this agent is moving or has a path, cancels its movement and forgets its path before jumping.
      Parameters:
      arc - arc of the graph of this agent's GraphEnvironment where this agent will be placed
      arcAbsOffset - absolute offset of the specified arc where this agent will be placed

    • tryUpdatePosition

      protected void tryUpdatePosition()

    • enterSegment

      protected void enterSegment(Segment segment, double segmentAbsOffset)

    • onSegmentExited

      protected void onSegmentExited()

    • beforeExitedArc

      public void beforeExitedArc(Graph<N,A>.Arc arc)
      Callback method called before exiting entering an arc. To be overridden in subclasses. This agent is still on the specified arc when this method is called

      Event of exiting an arc can happen in 3 cases:

    • in process of moving
    • before jumping from current position on an arc
    • before turning to opposite arc
      • Parameters:
      arc - arc being exited
      See Also:

    • afterEnteredNode

      public void afterEnteredNode(Graph<N,A>.Node node)
      Callback method called immediately after entering a node. To be overridden in subclasses. This agent is already in the specified node when this method is called
      Parameters:
      node - node being entered
      See Also:

    • beforeExitedNode

      public void beforeExitedNode(Graph<N,A>.Node node)
      Callback method called before exiting a node. To be overridden in subclasses. This agent is still in the specified node when this method is called
      Parameters:
      node - node being exited
      See Also:

    • afterEnteredArc

      public void afterEnteredArc(Graph<N,A>.Arc arc)
      Callback method called immediately after entering an arc. To be overridden in subclasses. This agent is already on the specified arc when this method is called

      Event of entering an arc can happen in 3 cases:

    • in process of moving
    • after jumping to a position on the specified arc
    • after turning to opposite arc
      • Parameters:
      arc - arc being entered
      See Also:

    • onDestinationReached

      public void onDestinationReached(GeometricGraphPosition<N,A> destPosition)
      Callback method called after this agent reaches its destination, i.e. the final position of its path. The destination is determined as final position of any movement initiated by any overload of moveTo or moveToClosest method.

      Note that jumpTo methods do not initiate movements and thus do not lead to calling this callback.

      Parameters:
      destPosition - the position that has been reached
      See Also:

    • jumpToPathDestPosition

      protected void jumpToPathDestPosition()

    • startMovingAlongPath

      protected void startMovingAlongPath(double velocity)

    • isPossibleToStartMoving

      protected boolean isPossibleToStartMoving(double velocity)

    • addCallbackPosition

      public void addCallbackPosition(GeometricGraphPosition<N,A> position)
      Adds a callback position that will initiate calling onCallbackPositionReached(GeometricGraphPosition, boolean) method when this agent reaches the specified position.

      If callback positions are disabled in this agent's GraphEnvironment, throws a RuntimeException. Callback positions can be enabled or disabled in constructor of GraphEnvironment(boolean, boolean, boolean, boolean, boolean) The method GraphEnvironment.isCallbackPositionsEnabled() checks whether the callback positions are enabled

      Parameters:
      position - specified position
      See Also:

    • removeCallbackPosition

      public void removeCallbackPosition(GeometricGraphPosition<N,A> position)
      Removes a callback position previously added by addCallbackPosition(GeometricGraphPosition) method. Does nothing if no such callback position has previously been added.
      Parameters:
      position - callback position to be removed
      See Also:

    • onCallbackPositionReached

      public void onCallbackPositionReached(GeometricGraphPosition<N,A> postition, boolean isAgentCallback)
      Callback method called when this agent reaches a callback position. To be overridden in subclasses.
      Parameters:
      postition - callback position that have been reached
      isAgentCallback - true if the callback position is this agent's callback position added by addCallbackPosition(GeometricGraphPosition) method, false otherwise

    • onOtherAgentReached

      public void onOtherAgentReached(GraphAgent<N,A> otherAgent, boolean isMovingInSameDirection)
      Callback method called when this agent reaches another agent, i.e. graph positions of this agent and the other agent become either equal or reverse. To be overridden in subclasses.
      Parameters:
      otherAgent - another agent
      isMovingInSameDirection - true if both agents are moving in the same direction, false otherwise

    • clearCallbackPositions

      public void clearCallbackPositions()
      Removes all callback positions of this agent.

    • checkEvents

      protected void checkEvents()

    • setGraphEnvironment

      public void setGraphEnvironment(GraphEnvironment<N,A,?> graphEnvironment)
      Sets the GraphEnvironment to this agent. This agent starts to live in the specified graph environment after this call. If this agent has been assigned to some other graph environment, removes it from that graph environment before placing into the specified one.
      Parameters:
      graphEnvironment - graph environment to be set to this agent

    • isInGraph

      public boolean isInGraph()
      Checks whether this agent is in graph, i.e. it hasGraphEnvironment() and it has been jumped to some position of the graph environment's graph.

      This method returns true if and only if getCurrentPosition() != null

      Returns:
      true if this agent is in graph, false otherwise
      See Also:

    • isAtNode

      public boolean isAtNode()
      Checks whether this agent is currently located in some node of the graph of its graph environment.

      The result of this method is equivalent to result of the following expression:
      isInGraph() && getCurrentNode() != null

      Returns:
      true if this agent is in a node, false otherwise
      See Also:

    • isOnArc

      public boolean isOnArc()
      Checks whether this agent is currently located on some arc of the graph of its graph environment.

      The result of this method is equivalent to the result of the following expression:
      isInGraph() && getCurrentArc() != null

      Returns:
      true if this agent is on an arc, false otherwise

    • hasPath

      public boolean hasPath()
      Checks whether this agent currently has a path, i.e. it has some way and destination to reach. The path can be retrieved by getGraphPath() method.
      Returns:
      true if this agent currently has a path, false otherwise
      See Also:

    • hasGraphEnvironment

      public boolean hasGraphEnvironment()
      Checks if this agent has been set to a GraphEnvironment. This can be done with setGraphEnvironment(GraphEnvironment) method
      Returns:
      true if this agent has been set to a GraphEnvironment, false otherwise

    • onPathNotFound

      public void onPathNotFound(List<GeometricGraphPosition<N,A>> possibleDestinationPositions)
      Callback method called when no path can be found from this agent's position to the destination specified in one of the overloads of moveTo or moveToClosest method.
      See Also:

    • setCurrentPathInternal

      protected void setCurrentPathInternal(AgentGraphPath<N,A> path)

    • eraseCurrentPathInternal

      protected void eraseCurrentPathInternal()

    • leaveCurrentNodeInternal

      protected void leaveCurrentNodeInternal()

    • leaveCurrentArcInternal

      protected void leaveCurrentArcInternal()

    • enterNodeInternal

      protected void enterNodeInternal(Graph<N,A>.Node node)

    • enterArcInternal

      protected void enterArcInternal(Graph<N,A>.Arc arc, double arcAbsOffset, Segment segment, double segmentAbsOffset)

    • jumpTo

      public CompletionStage<Void> jumpTo(N nodeValue)
      Jumps this agent to the node having the specified value. If this agent is moving or has a path, cancels its movement and forgets its path before jumping.
      Parameters:
      nodeValue - value of the node in the graph of this agent's GraphEnvironment where this agent will be placed

    • getGraphEnvironment

      public GraphEnvironment<N,A,?> getGraphEnvironment()
      Returns a GraphEnvironment which has been set to this agent, or null if no environment has been set to this agent
      Returns:
      GraphEnvironment which has been set to this agent, or null
      See Also:

    • moveTo

      public CompletionStage<Void> moveTo(N nodeValue, double velocity)
      Starts moving this agent to the node in the graph having the specified value with the specified velocity along the shortest path from agent's current position.

      The shortest path is calculated with respect to weights of arcs and nodes set in agent's GraphEnvironment.

      If this agent is currently moving somewhere else, it forgets its current destination and is assigned a new path.

      If zero velocity is specified, the path is set to this agent, but it just does not start moving. It can start moving when setVelocity(double) is called with a positive value.

      If no path is found from agent's current position to the specified node, onPathNotFound(List<GeometricGraphPosition<N, A>>) method is called. The default implementation of this method throws a RuntimeException, but it can be overridden in subclasses.

      If this agent is not in graph or has not been assigned to a GraphEnvironment, a RuntimeException is thrown.

      Parameters:
      nodeValue - value of the node in the graph of this agent's GraphEnvironment which this agent will be sent to
      velocity - specified velocity. Must be finite and non-negative
      See Also:

    • enableCommandsExecution

      protected void enableCommandsExecution()

    • cancelMovingInternal

      protected void cancelMovingInternal()

    • moveToInternal

      protected void moveToInternal(GeometricGraphPosition<N,A> destPosition, double velocity)

    • moveToClosestInternal

      protected void moveToClosestInternal(List<GeometricGraphPosition<N,A>> destPositions, double velocity)

    • getShortestPathToClosest

      protected AgentGraphPath<N,A> getShortestPathToClosest(List<GeometricGraphPosition<N,A>> destPositions)

    • getShortestPath

      protected AgentGraphPath<N,A> getShortestPath(GeometricGraphPosition<N,A> destPosition)

    • getShortestPath

      protected AgentGraphPath<N,A> getShortestPath(Predicate<Graph<N,A>.Node> indicator)

    • jumpToInternal

      protected void jumpToInternal(Graph<N,A>.Node node)

    • jumpToInternal

      protected void jumpToInternal(Graph<N,A>.Arc arc, double arcAbsOffset)

    • disableCommandsExecution

      protected void disableCommandsExecution()

    • setVelocityInternal

      protected void setVelocityInternal(double newVelocity)

    • getHeading

      public double getHeading()
      Returns the current heading of this agent if this agent is currently on an arc. Current heading is the heading of the Segment which this agent is currently on. If this agent is at a node, returns zero.

      The heading is calculated according to the rules described for Segment.getHeading() method.

      Returns:
      current heading of this agent, in radians, or 0 if this agent is at a node

    • getCurrentAnimationHeading

      public double getCurrentAnimationHeading()
      Returns the current heading of this agent if this agent is currently on an arc. Current heading is the heading of the Segment which this agent is currently on. If this agent is at a node, returns zero.

      This method must be called from animation when it is needed to determine where to show this agent. Calling getHeading() from animation might result in non-reproducibility of the model.

      Returns:
      current heading of this agent, in radians, or 0 if this agent is at a node

    • isOtherAgentInNodeHavingSameDirection

      protected boolean isOtherAgentInNodeHavingSameDirection(GraphAgent<?,?> otherAgent)

    • moveTo

      public CompletionStage<Void> moveTo(Predicate<Graph<N,A>.Node> indicator, double velocity)
      Starts movement of the agent from the current position (node or arc) to the specified graph node along the shortest path.


      If no path exists between agent's current position (node or arc) to the specified node, function does nothing.
      If agent already is in the specified node, function does nothing.

      Parameters:
      indicator - the Predicate which must return true to indicate that a node is a valid destination

    • moveToIndicatorInternal

      protected void moveToIndicatorInternal(Predicate<Graph<N,A>.Node> indicator, double velocity)

    • getCurrentPoint

      public Point getCurrentPoint()
      Returns the current Point where this agent is currently located in 2D space. If this agent is not in a graph, returns a point with infinite coordinates (new Point(Double.POSITIVE_INFINITY, Double.POSITIVE_INFINITY)).
      Returns:
      current Point where this agent is currently located in 2D space

    • getCurrentAnimationArcAbsOffset

      public double getCurrentAnimationArcAbsOffset()
      Returns the non-negative absolute offset of position on arc where this agent is currently located, or -1 if this agent is not currently located on an arc.

      This method must be called from animation when it is needed to determine where to show this agent. Calling getCurrentArcAbsOffset() from animation might result in non-reproducibility of the model.

      Returns:
      absolute offset of position on arc where this agent is currently located, or -1
      See Also:

    • resetDistanceTraveled

      public void resetDistanceTraveled()
      Resets the built-in distance traveled counter to zero.
      See Also:

    • getDistanceTraveled

      public double getDistanceTraveled()
      Gets the distance this agent traveled since its creation or last resetDistanceTraveled() call.
      Returns:
      distance this agent traveled since its creation or last resetDistanceTraveled() call

    • tryUpdateDistanceTraveled

      protected void tryUpdateDistanceTraveled()

    • allowEnterArc

      public boolean allowEnterArc(Graph<N,A>.Arc arc)
      Callback method used to implement advanced functionality like passby or waiting for something specific before entering arcs. The basic implementation is always to return true. To be overridden in subclasses.
      Parameters:
      arc - arc that this agent attempts to enter
      Returns:
      true if this agent should be allowed to enter the specified arc, false otherwise

    • moveTo

      public CompletionStage<Void> moveTo(Graph<N,A>.Node node, double velocity)
      Starts moving this agent to the specified node in the graph with the specified velocity along the shortest path from agent's current position.

      The shortest path is calculated with respect to weights of arcs and nodes set in agent's GraphEnvironment.

      If this agent is currently moving somewhere else, it forgets its current destination and is assigned a new path.

      If zero velocity is specified, the path is set to this agent, but it just does not start moving. It can start moving when setVelocity(double) is called with a positive value.

      If no path is found from agent's current position to the specified node, onPathNotFound(List) method is called. The default implementation of this method throws a RuntimeException, but it can be overridden in subclasses.

      If this agent is not in graph or has not been assigned to a GraphEnvironment, a RuntimeException is thrown.

      Parameters:
      node - node in the graph of this agent's GraphEnvironment which this agent will be sent to
      velocity - specified velocity. Must be finite and non-negative
      See Also:

    • getCurrentAnimationTrajectoryAbsoluteOffset

      public double getCurrentAnimationTrajectoryAbsoluteOffset()
      Returns the current absolute offset of this agent's position on its trajectory, or 0 if this agent does not have any trajectory.
      Returns:
      current absolute offset of this agent's position on its trajectory, or 0

    • tryExecuteCommand

      protected void tryExecuteCommand(Runnable runnable, Command.Type type)

    • moveAlongPath

      public CompletionStage<Void> moveAlongPath(AgentGraphPath<N,A> path, double velocity)

    • removeFromGraphInternal

      protected void removeFromGraphInternal()

    • removeFromGraphEnvironment

      public void removeFromGraphEnvironment()
      Removes this agent from the GraphEnvironment which it has been set to.

    • getName

      public String getName()
      Description copied from interface: Agent
      Returns the name of this agent
      Specified by:
      getName in interface Agent
      Returns:
      name of this agent

    • engine

      public Engine engine()
      Description copied from interface: Agent
      Returns the reference to the Engine that is used to simulate this agent's behavior
      Specified by:
      engine in interface Agent
      Returns:
      reference to the Engine that is used to simulate this agent's behavior