Movement in continuous space

Calling agent movement functions
Defining movement with flowchart blocks

AnyLogic continuous space support includes ability to set and retrieve the current agent location, to move the agent with the specified speed from one location to another, to execute action upon arrival, and to animate the (static or moving) agent at its location. Part of continuous space functionality does not even require the agents to belong to an explicitly specified space — the default space type assumed is continuous space.

Calling agent movement functions

You make agent move to new location by calling one of its numerous movement functions.

Agent type has a rich API for moving in continuous space. First, there are functions to obtain the current location and distance (these functions work when the agent is moving as well). Then there is a set of functions for relocating the agent and getting the related information. The agents can move with some travel time or jump instantly to the target location.

You can set the initial speed and rotation of agent animation and define agent reaction on reaching the destination.

Check what specific features have agents when moving inside and outside of networks.

Sometimes calling one or another function may result in triggering the code of an agent action On arrival to target location.

First, you might need to get information about the agent position and define its target location coordinates.

Obtaining the current location

Function	Description
double getX()	Returns the current (up-to-date) x coordinate of the agent in continuous space.
double getY()	Returns the current (up-to-date) y coordinate of the agent in continuous space.
double getZ()	Returns the current (up-to-date) z coordinate of the agent in continuous space.
Position getPosition()	Returns the current (up-to-date) x, y (and z in case of 3D space) coordinate of the agent in continuous space and its orientation as well.

Getting the target coordinates

Function	Description
double getTargetX()	Returns the X-coordinate of the target location if the agent is moving, and its current X otherwise.
double getTargetY()	Returns the Y-coordinate of the target location if the agent is moving, and its current Y otherwise.
double getTargetZ()	Returns the Z-coordinate of the target location if the agent is moving, otherwise current Z-coordinate.

Calculating distance

Function	Description
double distanceTo(Agent other)	Returns the distance to a given other agent.
double distanceTo(Agent other, LengthUnits units)	Calculates the distance from this agent to a given other agent in the specified units.
double distanceTo(Point point)	Calculates the distance from this agent to a given point.
double distanceTo(Point point, LengthUnits units)	Calculates the distance from this agent to a given point in specified units.
double distanceTo(double x, double y)	Calculates the distance from this agent to a given point (x, y) in space.
double distanceTo(double x, double y, LengthUnits units)	Calculates the distance from this agent to a given point (x, y) in space in specified units.
double distanceTo(level level, double x, double y)	Calculates the distance from this agent to a given point on a given level.
double distanceTo(Level level, double x, double y, LengthUnits units)	Calculates the distance from this agent to a given point on a given level in specified units.
double distanceTo(double x, double y, double z)	Calculates the distance from this agent to a given point (x, y, z) in continuous 3D space.

Agent movement

The movement goes at the given speed (which however can be changed dynamically). The agent will execute On arrival to target location action when (and if) it reaches the target location.

The following methods make agents move to the given target location along the shortest straight line.

moveTo() and moveToInTime() functions provide several notations, enabling defining target location in different ways:

You can define location as:

X, Y coordinates: moveTo(double x, double y)
X, Y, Z coordinates: moveTo(double x, double y, double z)
Point: moveTo(Point location)
Attractor: moveTo(Attractor attractor)
Network node: moveTo(Node node)
Network node and location inside the node — (x,y,z) point: moveTo(Node node, Point location)

You can define movement to the specific model element using its name as the target. Such objects have the following types:

For agent movement initiated with call of any moveTo() function, On arrival to target destination code is executed when the movement is finished.

Movement

Function	Description
void moveTo(double x, double y)	Starts movement to the given target location. x, y — X-, Y-coordinates of the target location
void moveToStraight(double x, double y)	Starts straight movement (ignoring network/routes) to the given target location. x, y — X-, Y-coordinates of the target location
void moveTo(double x, double y, double z)	Starts movement to the given target location. x, y, z — X-, Y-, Z-coordinates of the target location
void moveToStraight(double x, double y, double z)	Starts straight movement (ignoring network/routes) to the given target location. x, y, z — X-, Y-, Z-coordinates of the target location
void moveTo(Agent agent)	Starts movement to the given agent. agent — the agent to move to
void moveToStraight(Agent agent)	Starts straight movement (ignoring network/routes) to the given agent. agent — the agent to move to
void moveTo(Point location)	Starts movement in the direction of the given target location. location — the target location
void moveToStraight(Point location)	Starts straight movement (ignoring network/routes) in the direction of the given target location. location — the target location
void moveTo(INode node)	Starts movement to the specified network node. node — the network node
void moveTo(INode node, Point location)	Starts movement to the specified location inside the given network node. node — the network node location — (optional) location within node, may be null
void moveTo(Attractor attractor)	Starts movement to the given attractor. attractor — the attractor
void moveToNearestAgent(java.lang.Iterable<? extends Agent> agents)	Starts movement to the nearest agent from the given collection (or population). agents — the collection (or population) of agents

Instant jumping

These functions instantly place the agent to a given location or node. They terminate any movement and do not call On arrival to target location code.

Instant movement (jumping)

All “jump” functions do not call “on arrival” code.

Function	Description
void jumpTo(double x, double y)	Instantly moves the agent to a given location in space. Terminates any movement. x, y — X-, Y-coordinates of the target location
void jumpTo(double x, double y, double z)	Instantly moves the agent to a given location. Terminates any movement. x, y, z — X-, Y-, Z-coordinates of the target location
void jumpTo(INode node)	Instantly moves the agent inside the specified network node. Terminates any movement. node — the network node
void jumpTo(INode location, Point location)	Instantly moves the agent to a given point inside the specified network node. Terminates any movement. node — the network node location — (optional) location within node, may be null
void jumpTo(Point location)	Instantly moves the agent to a given location. Terminates any movement. location — the new location

Defining time of movement

The following methods change the speed of the agent in order to reach target in tripTime model time units. The parameters are the same as above, except for tripTime: this parameter describes the time of the movement.

moveToInTime(Agent agent, double tripTime)
moveToInTime(double x, double y, double tripTime)
moveToInTime(double x, double y, double z, double tripTime)
moveToInTime(Node node, double tripTime)
moveToInTime(Attractor attractor, double tripTime)
moveToNearestAgent(Agent agents, double tripTime)

Each moveToInTime() function has another notation with one more argument: units. Use this notation when you want to specify the trip time not in the model time units, but in some other time units. Pass one of time unit constants (e.g. MINUTE, HOUR, DAY) as the units argument value. Let us say, that model time units are seconds, but the trip time is 2 days, so it is easier for you to write truck.moveToInTime(city, 2, DAY) and the agent truck will start its movement to the agent city. It will take two days for the truck to reach city.

moveToInTime(Agent agent, double tripTime, TimeUnits units)
moveToInTime(double x, double y, double tripTime, TimeUnits units)
moveToInTime(double x, double y, double z, double tripTime, TimeUnits units)
moveToInTime(Node node, double tripTime, TimeUnits units)
moveToInTime(Attractor attractor, double tripTime, TimeUnits units)
moveToNearestAgent(Agent agents, double tripTime, TimeUnits units)

Movement with specified trip time

For all these functions, On arrival to target destination code is executed when the movement is finished.

Function	Description
void moveToInTime(double x, double y, double tripTime)	Starts movement in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime model time units. x — the X-coordinate of the target location. y — the Y-coordinate of the target location. tripTime — the time of the movement trip, in model time units
void moveToInTime(double x, double y, double tripTime, TimeUnits units)	Starts movement in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime time units. x — the X-coordinate of the target location. y — the Y-coordinate of the target location. tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToInTime(double x, double y, double z, double tripTime)	Starts movement in the direction of the given target location in continuous space. Changes the speed of the agent in order to reach target in tripTime model time units. x, y, z — X-, Y-, Z- coordinates of the target location tripTime — the time of the movement trip, in model time units
void moveToInTime(double x, double y, double z, double tripTime, TimeUnits units)	Starts movement in the direction of the given target location in continuous space. Changes the speed of the agent in order to reach target in tripTime time units. x, y, z — X-, Y-, Z- coordinates of the target location tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToInTime(Agent agent, double tripTime)	Starts movement to the given agent. Changes the speed of the agent in order to reach target in tripTime model time units. agent — the agent to move to tripTime — the time of the movement trip, in model time units
void moveToInTime(Agent agent, double tripTime, TimeUnits units)	Starts movement to the given agent. Changes the speed of the agent in order to reach target in tripTime time units. agent — the agent to move to tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToInTime(Attractor attractor, double tripTime)	Starts movement to the given attractor. Changes the speed of the agent in order to reach target in tripTime model time units. attractor — the attractor to move to tripTime — the time of the movement trip, in model time units
void moveToInTime(Attractor attractor, double tripTime, TimeUnits units)	Starts movement to the given attractor. Changes the speed of the agent in order to reach target in tripTime time units. attractor — the attractor to move to tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToInTime(INode node, double tripTime)	Starts movement to the given network node. Changes the speed of the agent in order to reach target in tripTime model time units. attractor — the network node to move to tripTime — the time of the movement trip, in model time units
void moveToInTime(INode node, double tripTime, TimeUnits units)	Starts movement to the given network node. Changes the speed of the agent in order to reach target in tripTime time units. attractor — the network node to move to tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToInTime(INode node, Point location, double tripTime)	Starts movement to the given location inside the specified network node. Changes the speed of the agent in order to reach target in tripTime model time units. node — the network node location — (optional) location within node, may be null tripTime — the time of the movement trip, in model time units
void moveToInTime(INode node, Point location, double tripTime, TimeUnits units)	Starts movement to the given location inside the specified network node. Changes the speed of the agent in order to reach target in tripTime time units. node — the network node location — (optional) location within node, may be null tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToInTime(Point location, double tripTime)	Starts movement in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime model time units. location — the target location tripTime — the time of the movement trip, in model time units
void moveToInTime(Point location, double tripTime, TimeUnits units)	Starts movement in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime time units. location — the target location tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToNearestAgent(java.lang.Iterable<? extends Agent> agents, double tripTime)	Starts movement to the nearest agent from the given collection (or population). Stops any current movement. Changes the speed of the agent in order to reach target in tripTime model time units. agents — the collection (or population) of agents tripTime — the time of the movement trip
void moveToStraightInTime(double x, double y, double z, double tripTime)	Starts straight movement (ignoring network) in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime model time units. x, y, z — X-, Y-, Z- coordinates of the target location tripTime — the time of the movement trip, in model time units
void moveToStraightInTime(double x, double y, double z, double tripTime, TimeUnits units)	Starts straight movement (ignoring network) in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime time units. x, y, z — X-, Y-, Z- coordinates of the target location tripTime — the time of the movement trip, in specified time units units — a constant defining the time units
void moveToStraightInTime(Point location, double tripTime)	Starts straight movement (ignoring network) in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime model time units. location — the target location tripTime — the time of the movement trip, in model time units
void moveToStraightInTime(Point location, double tripTime, TimeUnits units)	Starts straight movement (ignoring network) in the direction of the given target location. Changes the speed of the agent in order to reach target in tripTime time units. location — the target location tripTime — the time of the movement trip, in specified time units units — a constant defining the time units

Additional useful methods

Function	Description
boolean isMoving()	Tests if the agent is currently moving.
double timeToArrival()	If the agent is moving, returns the remaining time to arrival assuming the speed will not change. If the agent is not moving, returns 0. The function returns time in model time units.
double timeToArrival(TimeUnits units)	If the agent is moving, returns the remaining time to arrival assuming the speed will not change. If the agent is not moving, returns 0. The function returns time in given time units. You specify time units with the function argument units, passing one of time unit constants (e.g., MINUTE, HOUR) as the argument value.
void stop()	Stops the agent (if it was moving) and leaves it at the current location. The agent action On arrival to target location is not executed.

Defining movement with flowchart blocks

Another way to move agents is to define corresponding parameters in the flowchart blocks’ properties. Most frequently you build flowcharts using Process Modeling Library.

The Process Modeling Library block, which is designed specifically to simulate agent movement, is called MoveTo. In its properties, you can choose, whether you want the agent to move or to jump to the target destination (option Agent: moves to / is placed (jumps) to). The Destination property has a lot of useful options, which apply both for moving and jumping:

If you select Network / GIS node as Destination, you can simply select it from the Node drop-down list below.

You can also set custom speed for a moving agent, or a trip time, as if you were using moveToInTime() functions.

Learn more about MoveTo block’s parameters in MoveTo.

Usually, when you work with Process Modeling Library, you create a space markup network to define agent locations. Networks are also used to define movement of agents. In this case a network node is very frequently specified as destination location. Agent movement routes may vary depending on whether a node is part of the network or not.

Moreover, you can define exact position inside a destination node with attractors, or define the attractor itself as destination point.

How can we improve this article?