com.anylogic.engine.AgentList<E>

Type Parameters:: E - agent type

All Implemented Interfaces:: com.anylogic.engine.internal.Child, IterableWithSize<E>, Serializable, Iterable<E>

Direct Known Subclasses:: AgentArrayList, AgentLinkedHashSet

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

Agent population list interface

Author:: AnyLogic North America, LLC https://anylogic.com
See Also:: AgentArrayListSerialized Form

Constructor Summary

Constructor	Description
`AgentList(Agent owner)`

Method Summary

Modifier and Type	Method	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.`goToPopulation( population )`
`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 )`
`double`	`average(String fieldName)`	Returns the average of (numeric) field values for all agents in this collection
`double`	`average(String fieldName, 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. 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)
`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)
`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
`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
`abstract boolean`	`contains(Object agent)`	Returns `true` if this agent population contains the specified element.
`int`	`count(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, 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, BiConsumer<TableInput,E> agentSetupCode, Function<TableInput,Integer> numberOfAgents, boolean callCreate, boolean startAgents)`	Creates agents from the given table, sets their parameters and adds to this population.
`List<E>`	`findAll(Predicate<E> condition)`	Returns new list with agents from this population which meet the given condition. Usage examples:
`E`	`findFirst(Predicate<E> condition)`	Returns the first agent from this population which meets the given condition. Usage example:
`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.
`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(String columnLabel, Class<T> returnType)`
`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
`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. it may be removed/renamed in future. It is public due to technical reasons.
`abstract Iterator<E>`	`iterator()`	Returns an iterator over the agent population. This iterator guarantees the insertion order of elements (i.e.
`double`	`max(String fieldName)`	Returns the maximum of (numeric) field values for all agents in this collection
`double`	`max(String fieldName, 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(String fieldName)`	Returns the minimum of (numeric) field values for all agents in this collection
`double`	`min(String fieldName, 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)
`double`	`min(Collection<? extends Agent> agents, String fieldName, String triggerFieldName)`	Deprecated. will be removed in the next (7.1+) release, please use `min(String, String)` instead
`void`	`onChange()`	Calls onChange() for all the agents in this list.
`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
`final E`	`random(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(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.
`final void`	`restoreOwner(Object owner)`	Deprecated.
`void`	`setEnvironment(Agent environment)`
`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`.
`Stream<E>`	`stream()`	Returns a sequential Stream with this agent population as its source.
`double`	`sum(String fieldName)`	Returns the sum of (numeric) field values for all agents in this collection
`double`	`sum(String fieldName, 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 Details

AgentList

public AgentList(Agent owner)

Method Details

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.

Specified by:: size in interface IterableWithSize<E extends Agent>
Returns:: the number of elements in this agent population

isEmpty

public abstract boolean isEmpty()

Returns true if this agent population contains no elements.

Specified by:: isEmpty in interface IterableWithSize<E extends Agent>
Returns:: true if this agent population contains no elements

contains

public abstract boolean contains(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 final E random(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(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 List<E> findAll(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(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(String fieldName,
 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(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(String fieldName,
 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(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(Collection<? extends Agent> agents,
 String fieldName,
 String triggerFieldName)

Deprecated.

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

min

@AnyLogicLegacyAPI
public double min(String fieldName,
 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(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(String fieldName,
 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(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(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(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 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 Iterable<E extends Agent>
Returns:: an Iterator over the elements in this replicated agent

stream

public 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.

Specified by:: get in interface IterableWithSize<E extends Agent>
Parameters:: index - index of the element to return
Returns:: the element at the specified position in this list
Throws:: 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,
 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,
 BiConsumer<TableInput,E> agentSetupCode,
 Function<TableInput,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(String columnLabel,
 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.

Class AgentList<E extends Agent>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Details

AgentList

Method Details

getOwner

_add

_remove

setEnvironment

getEnvironment

size

isEmpty

contains

random

random

randomExcept

randomExcept

findAll

findFirst

onChange

sum

sum

average

average

min

min

min

max

max

count

restoreOwner

iterator

stream

get

instantiateAgent

callSetupParameters

callCreate

callSetupParameters

callCreate

fillFromTable

fillFromTable

fillFromTable

getValueFromTable

getPresentationScaleOnOwnerSpace

isPresentationEnabled