com.anylogic.engine

Class AgentList<E extends Agent>

java.lang.Object

com.anylogic.engine.AgentList<E>

Type Parameters:

E - agent type

All Implemented Interfaces:

com.anylogic.engine.internal.Child, java.io.Serializable, java.lang.Iterable<E>

Direct Known Subclasses:

AgentArrayList, AgentLinkedHashSet

public abstract class AgentList<E extends Agent>
extends java.lang.Object
implements java.lang.Iterable<E>, java.io.Serializable, com.anylogic.engine.internal.Child

Agent population list interface

Author:

AnyLogic North America, LLC https://anylogic.com

See Also:

AgentArrayList, Serialized Form

Constructor Summary

Constructors

Constructor and Description
AgentList(Agent owner)

Method Summary

Modifier and Type	Method and Description
abstract void	_add(E agent) This method should not be called by user Call add_EONAME() method of class containing embedded object with name EONAME or agent.
abstract boolean	_remove(Agent agent) This method should not be called by user Call remove_EONAME() method of class containing embedded object with name EONAME or agent.
double	average(java.lang.String fieldName) Returns the average of (numeric) field values for all agents in this collection
double	average(java.lang.String fieldName, java.lang.String triggerFieldName) Returns the average of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)
void	callCreate(E agent, int index) This method is internal and shouldn't be called by user.
void	callCreate(E agent, int index, TableInput tableInput) This method is internal and shouldn't be called by user.
void	callSetupParameters(E agent, int index) This method is internal and shouldn't be called by user.
void	callSetupParameters(E agent, int index, TableInput tableInput) This method is internal and shouldn't be called by user.
abstract boolean	contains(java.lang.Object agent) Returns true if this agent population contains the specified element.
int	count(java.lang.String triggerFieldName) Returns the number of agents in this collection which have true value of a boolean field with name triggerFieldName
void	fillFromTable(TableInput tableInput) Creates agents from the given table using the parameters mapping configured in AnyLogic, adds to this population and starts agents.
void	fillFromTable(TableInput tableInput, java.util.function.BiConsumer<TableInput,E> agentSetupCode, boolean callCreate, boolean startAgents) Creates agents from the given table, sets their parameters and adds to this population.
void	fillFromTable(TableInput tableInput, java.util.function.BiConsumer<TableInput,E> agentSetupCode, java.util.function.Function<TableInput,java.lang.Integer> numberOfAgents, boolean callCreate, boolean startAgents) Creates agents from the given table, sets their parameters and adds to this population.
java.util.List<E>	findAll(java.util.function.Predicate<E> condition) Returns new list with agents from this population which meet the given condition.
E	findFirst(java.util.function.Predicate<E> condition) Returns the first agent from this population which meets the given condition.
abstract E	get(int index) Returns the agent element at the specified position in this agent population.
Agent	getEnvironment() Returns the environment where this agent population belongs to.
Agent	getOwner() Returns the owner agent that encapsulates this population.
double	getPresentationScaleOnOwnerSpace() Returns the scale of the agent presentation animation on its space or 1.0 if space isn't defined or agent list is empty
<T> T	getValueFromTable(java.lang.String columnLabel, java.lang.Class<T> returnType)
E	instantiateAgent(int index) This method is internal and shouldn't be called by user.
abstract boolean	isEmpty() Returns true if this agent population contains no elements.
boolean	isPresentationEnabled() This method is internal and shouldn't be called by user.
abstract java.util.Iterator<E>	iterator() Returns an iterator over the agent population.
double	max(java.lang.String fieldName) Returns the maximum of (numeric) field values for all agents in this collection
double	max(java.lang.String fieldName, java.lang.String triggerFieldName) Returns the maximum of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)
double	min(java.util.Collection<? extends Agent> agents, java.lang.String fieldName, java.lang.String triggerFieldName) Deprecated. will be removed in the next (7.1+) release, please use min(String, String) instead
double	min(java.lang.String fieldName) Returns the minimum of (numeric) field values for all agents in this collection
double	min(java.lang.String fieldName, java.lang.String triggerFieldName) Returns the minimum of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)
void	onChange() Calls onChange() for all the agents in this list.
E	random() Randomly returns one agent from this population (uses uniform distribution from the Engine) This method runs in linear time This method returns null if the population is empty
E	random(java.util.Random r) Randomly returns one agent from this population (ses the specified random number generator to choose the element) This method runs in linear time This method returns null if the population is empty
E	randomExcept(Agent agent) Randomly returns one agent from this population except the given agent (uses uniform distribution from the Engine) This method runs in linear time This method returns null if the population is empty or contains the only given agent
E	randomExcept(java.util.Set<? extends Agent> agents) Randomly returns one agent from this population except the given agents (uses uniform distribution from the Engine) This method runs in linear time multiplied by the complexity of 'contains' check of the given set This method returns null if the population is empty or all the agents are contained in the given agents set.
void	restoreOwner(java.lang.Object owner) Deprecated.
void	setEnvironment(Agent environment)
abstract int	size() Returns the number of elements in this agent population.
java.util.stream.Stream<E>	stream() Returns a sequential Stream with this agent population as its source.
double	sum(java.lang.String fieldName) Returns the sum of (numeric) field values for all agents in this collection
double	sum(java.lang.String fieldName, java.lang.String triggerFieldName) Returns the sum of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

AgentList

public AgentList(Agent owner)

Method Detail

getOwner

public Agent getOwner()

Returns the owner agent that encapsulates this population.

Returns:

owner agent

_add

@AnyLogicInternalCodegenAPI
public abstract void _add(E agent)

This method should not be called by user
Call add_EONAME() method of class containing embedded object with name EONAME or agent.goToPopulation( population )

_remove

@AnyLogicInternalCodegenAPI
public abstract boolean _remove(Agent agent)

This method should not be called by user
Call remove_EONAME() method of class containing embedded object with name EONAME or agent.goToPopulation( null )

setEnvironment

@AnyLogicInternalCodegenAPI
public void setEnvironment(Agent environment)

getEnvironment

public Agent getEnvironment()

Returns the environment where this agent population belongs to.

Returns:

the environment where this agent population belongs to

size

public abstract int size()

Returns the number of elements in this agent population.
If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:

the number of elements in this agent population

isEmpty

public abstract boolean isEmpty()

Returns true if this agent population contains no elements.

Returns:

true if this agent population contains no elements

contains

public abstract boolean contains(java.lang.Object agent)

Returns true if this agent population contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e)).

Parameters:

agent - element whose presence in this agent population is to be tested

Returns:

true if this agent population contains the specified element

random

public final E random()

Randomly returns one agent from this population
(uses uniform distribution from the Engine)
This method runs in linear time
This method returns null if the population is empty

Returns:

the agent randomly chosen from this population
(uses uniform distribution from the Engine)

random

public E random(java.util.Random r)

Randomly returns one agent from this population
(ses the specified random number generator to choose the element)
This method runs in linear time
This method returns null if the population is empty

Parameters:

r - the random number generator.

Returns:

the agent randomly chosen from this population
(uses uniform distribution from the Engine)

randomExcept

public E randomExcept(Agent agent)

Randomly returns one agent from this population except the given agent
(uses uniform distribution from the Engine)
This method runs in linear time
This method returns null if the population is empty or contains the only given agent

Parameters:

agent - agent not to be chosen

Returns:

the agent randomly chosen from this population but not the given agent
(uses uniform distribution from the Engine)

randomExcept

public E randomExcept(java.util.Set<? extends Agent> agents)

Randomly returns one agent from this population except the given agents
(uses uniform distribution from the Engine)
This method runs in linear time multiplied by the complexity of 'contains' check of the given set
This method returns null if the population is empty or all the agents are contained in the given agents set.

Parameters:

agents - agent not to be chosen

Returns:

the agent randomly chosen from this population (uses uniform distribution from the Engine)

Since:

7.3

findAll

public java.util.List<E> findAll(java.util.function.Predicate<E> condition)

Returns new list with agents from this population which meet the given condition.
Usage examples:

 for (Person person : people.findAll( p -> p.age > 20 )) {
        traceln( person );
 }
 
 Person person = randomFrom( people.findAll( p -> p.income < 5000 ) );
 

Parameters:

condition - the condition to test

Returns:

always new instance of list, modifiable, with agents which have true value of the given condition

Since:

7.2

findFirst

public E findFirst(java.util.function.Predicate<E> condition)

Returns the first agent from this population which meets the given condition.
Usage example:

 Person person = people.findFirst( p -> p.age > 20 );
 

Parameters:

condition - the condition to test

Returns:

the agent has true value of the given condition, or null if there is no such agent or the population is empty.

Since:

7.2

onChange

public void onChange()

Calls onChange() for all the agents in this list. Such notification to the agent means "some of your data may have changed during this event". You can call this function if you wish all the agents in this list to notice the change even if they had no events.
For more information, see Agent.onChange()

See Also:

Agent.onChange()

sum

@AnyLogicLegacyAPI
public double sum(java.lang.String fieldName,
                                      java.lang.String triggerFieldName)

Returns the sum of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)

Parameters:

fieldName - the name of the field (case-sensitive) to be summed up

triggerFieldName - the name of the field (case-sensitive) to be checked for true when performing addition
May be null - in this case all the agents are taken

Returns:

sum of field values for agents

sum

public double sum(java.lang.String fieldName)

Returns the sum of (numeric) field values for all agents in this collection

Parameters:

fieldName - the name of the field (case-sensitive) to be summed up

Returns:

the sum of the field values for all agents

average

@AnyLogicLegacyAPI
public double average(java.lang.String fieldName,
                                          java.lang.String triggerFieldName)

Returns the average of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)

Parameters:

fieldName - the name of the field (case-sensitive) to be taken

triggerFieldName - the name of the field (case-sensitive) to be checked for true when performing calculation
May be null - in this case all the agents are taken

Returns:

the average of the field values for agents,
or 0 if there is no suitable agents

average

public double average(java.lang.String fieldName)

Returns the average of (numeric) field values for all agents in this collection

Parameters:

fieldName - the name of the field (case-sensitive) to be taken

Returns:

the average of the field values for all agents,
or 0 if there is no agents

min

@Deprecated
public double min(java.util.Collection<? extends Agent> agents,
                               java.lang.String fieldName,
                               java.lang.String triggerFieldName)

Deprecated. will be removed in the next (7.1+) release, please use min(String, String) instead

min

@AnyLogicLegacyAPI
public double min(java.lang.String fieldName,
                                      java.lang.String triggerFieldName)

Returns the minimum of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)

Parameters:

fieldName - the name of the field (case-sensitive) to be taken

triggerFieldName - the name of the field (case-sensitive) to be checked for true when performing minimum search
May be null - in this case all the agents are taken

Returns:

the minimum of field values for agents
+infinity if there is no suitable agents

min

public double min(java.lang.String fieldName)

Returns the minimum of (numeric) field values for all agents in this collection

Parameters:

fieldName - the name of the field (case-sensitive) to be taken

Returns:

the minimum of the field values for all agents
-infinity if there is no suitable agents

max

@AnyLogicLegacyAPI
public double max(java.lang.String fieldName,
                                      java.lang.String triggerFieldName)

Returns the maximum of (numeric) field values for all agents in this collection which have true value of a boolean field with name triggerFieldName (if specified)

Parameters:

fieldName - the name of the field (case-sensitive) to be taken

triggerFieldName - the name of the field (case-sensitive) to be checked for true when performing maximum search
May be null - in this case all the agents are taken

Returns:

the maximum of field values for agents
-infinity if there is no suitable agents

max

public double max(java.lang.String fieldName)

Returns the maximum of (numeric) field values for all agents in this collection

Parameters:

fieldName - the name of the field (case-sensitive) to be taken

Returns:

the maximum of the field values for all agents
-infinity if there is no suitable agents

count

public int count(java.lang.String triggerFieldName)

Returns the number of agents in this collection which have true value of a boolean field with name triggerFieldName

Parameters:

triggerFieldName - the name of the field (case-sensitive) to be checked for true when performing calculation
May be null - in this case agents.size() is returned (i.e. all the agents are taken)

Returns:

the number of agents which have true value of a boolean field with name triggerFieldName

restoreOwner

@AnyLogicInternalCodegenAPI
 @Deprecated
public final void restoreOwner(java.lang.Object owner)

Deprecated.

This method normally should not be called by user
This method restores owner of this object
The method is used in snapshot saving/loading

Specified by:

restoreOwner in interface com.anylogic.engine.internal.Child

Parameters:

owner - owner of this object, usually Agent, Experiment or ShapeGroup

iterator

public abstract java.util.Iterator<E> iterator()

Returns an iterator over the agent population.
This iterator guarantees the insertion order of elements (i.e. the order in which agent were added to this agent population list).
Note, that returned iterator doesn't support remove operation

Specified by:

iterator in interface java.lang.Iterable<E extends Agent>

Returns:

an Iterator over the elements in this replicated agent

stream

public java.util.stream.Stream<E> stream()

Returns a sequential Stream with this agent population as its source.

Since:

8.0

get

public abstract E get(int index)

Returns the agent element at the specified position in this agent population.
The position index is the number of list element in the insertion order (i.e. the order in which agent were added to this replicated agent list). Thus, index of an element decreases when preceding elements are removed.

Parameters:

index - index of the element to return

Returns:

the element at the specified position in this list

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range ( index < 0 || index >= size())

instantiateAgent

@AnyLogicInternalCodegenAPI
public E instantiateAgent(int index)

This method is internal and shouldn't be called by user.
it may be removed/renamed in future. It is public due to technical reasons.
Creates new instance of agent for this population.
Should be overridden by code generation, default implementation is unsupported

Parameters:

index - index of agent in the population

Returns:

agent the agent

Since:

7.2

callSetupParameters

@AnyLogicInternalCodegenAPI
public void callSetupParameters(E agent,
                                                             int index)

This method is internal and shouldn't be called by user.
it may be removed/renamed in future. It is public due to technical reasons.
Sets agent parameters to the values defined in population

Parameters:

agent - the agent

index - index of agent in the population

callCreate

@AnyLogicInternalCodegenAPI
public void callCreate(E agent,
                                                    int index)

This method is internal and shouldn't be called by user.
it may be removed/renamed in future. It is public due to technical reasons.
Calls Agent.create() and performs some other population-related initializations (if required)

Parameters:

agent - the agent

index - index of agent in the population

callSetupParameters

@AnyLogicInternalCodegenAPI
public void callSetupParameters(E agent,
                                                             int index,
                                                             TableInput tableInput)

This method is internal and shouldn't be called by user.
it may be removed/renamed in future. It is public due to technical reasons.
Sets agent parameters to the values defined in population

Parameters:

agent - the agent

index - index of agent in the population

tableInput - TableInput, if agent is loaded from database, or null otherwise

callCreate

@AnyLogicInternalCodegenAPI
public void callCreate(E agent,
                                                    int index,
                                                    TableInput tableInput)

This method is internal and shouldn't be called by user.
it may be removed/renamed in future. It is public due to technical reasons.
Calls Agent.create() and performs some other population-related initializations (if required)

Parameters:

agent - the agent

index - index of agent in the population

tableInput - TableInput, if agent is loaded from database, or null otherwise

fillFromTable

@AnyLogicInternalAPI
public void fillFromTable(TableInput tableInput)

Creates agents from the given table using the parameters mapping configured in AnyLogic, adds to this population and starts agents.

Parameters:

tableInput - table input (contains information about table source and columns-to-parameters mapping)

Since:

7.2

fillFromTable

@AnyLogicInternalAPI
public void fillFromTable(TableInput tableInput,
                                                java.util.function.BiConsumer<TableInput,E> agentSetupCode,
                                                boolean callCreate,
                                                boolean startAgents)

Creates agents from the given table, sets their parameters and adds to this population.

Parameters:

tableInput - table input (contains information about table source and columns-to-parameters mapping)

agentSetupCode - code to set agent parameters from table

callCreate - true to call Agent.create() for newly added agents (this will create internal structure of agent)

startAgents - true to call Agent.start() for newly added agents (this will schedule events, start statecharts etc.) - callCreate argument is ignored in this case and assumed to be true

Since:

7.2

fillFromTable

@AnyLogicInternalAPI
public void fillFromTable(TableInput tableInput,
                                                java.util.function.BiConsumer<TableInput,E> agentSetupCode,
                                                java.util.function.Function<TableInput,java.lang.Integer> numberOfAgents,
                                                boolean callCreate,
                                                boolean startAgents)

Creates agents from the given table, sets their parameters and adds to this population.

Parameters:

tableInput - table input (contains information about table source and columns-to-parameters mapping)

agentSetupCode - code to set agent parameters from table

numberOfAgents - code to obtain number of agents (to be created with the same parameters) from table

callCreate - true to call Agent.create() for newly added agents (this will create internal structure of agent)

startAgents - true to call Agent.start() for newly added agents (this will schedule events, start statecharts etc.) - callCreate argument is ignored in this case and assumed to be true

Since:

7.2

getValueFromTable

@AnyLogicInternalCodegenAPI
public <T> T getValueFromTable(java.lang.String columnLabel,
                                                            java.lang.Class<T> returnType)

getPresentationScaleOnOwnerSpace

@AnyLogicInternalCodegenAPI
public double getPresentationScaleOnOwnerSpace()

Returns the scale of the agent presentation animation on its space or 1.0 if space isn't defined or agent list is empty

Returns:

the scale of presentation animation on owner space

isPresentationEnabled

@AnyLogicInternalCodegenAPI
public boolean isPresentationEnabled()

This method is internal and shouldn't be called by user.
it may be removed/renamed in future. It is public due to technical reasons.