Package fr.univ_artois.lgi2a.similar.microkernel.agents

Interface IAgent

All Known Subinterfaces:

IAgent4Engine

All Known Implementing Classes:

AbstractAgent, ExtendedAgent, PassiveAgent

public interface IAgent

Models an agent contained in the simulation.

An agent is characterized by a category, telling which kind of agent it models.

Correspondence with theory

An instance of this class models an agent a∈𝔸 from the simulation.

Usage

This is the ideal interface of an agent, from the perspective of a simulation designer. Because of implementation constraints, agents have instead to implement the IAgent4Engine interface.

Author:

Yoann Kubera

See Also:

AgentCategory

Method Summary

Modifier and Type	Method	Description
void	decide(LevelIdentifier levelId, SimulationTimeStamp timeLowerBound, SimulationTimeStamp timeUpperBound, IGlobalState globalState, ILocalStateOfAgent publicLocalState, ILocalStateOfAgent privateLocalState, IPerceivedData perceivedData, InfluencesMap producedInfluences)	Produces the influences resulting from the decisions of an agent from a specific level, for a specific transitory period.
AgentCategory	getCategory()	Gets the 'category' of agents to which this instance belongs to.
IGlobalState	getGlobalState()	Gets the global state of the agent.
Set<LevelIdentifier>	getLevels()	Gets the collection of the levels where this agent lies, i.e. the levels where this agent has a local state.
ILocalStateOfAgent	getPrivateLocalState(LevelIdentifier levelIdentifier)	Gets the private local state of the agent located in a specific level of the simulation.
ILocalStateOfAgent	getPublicLocalState(LevelIdentifier levelIdentifier)	Gets the public local state of the agent located in a specific level of the simulation.
IPerceivedData	perceive(LevelIdentifier level, SimulationTimeStamp timeLowerBound, SimulationTimeStamp timeUpperBound, Map<LevelIdentifier,ILocalStateOfAgent> publicLocalStates, ILocalStateOfAgent privateLocalState, IPublicDynamicStateMap dynamicStates)	Creates the data perceived by an agent located in a specific level.
void	reviseGlobalState(SimulationTimeStamp timeLowerBound, SimulationTimeStamp timeUpperBound, Map<LevelIdentifier,IPerceivedData> perceivedData, IGlobalState globalState)	Revises the content of the global state of the agent, using the previous value of its global state and the data that were lastly perceived by the agent.

Method Detail

getCategory

AgentCategory getCategory()

Gets the 'category' of agents to which this instance belongs to.

This method can return the name of this class, or any other string representation modeling the equivalence class of the agent.

Examples:

• Car
• Prey
• Water drop

Returns:

The 'category' of the agent.

getLevels

Set<LevelIdentifier> getLevels()

Gets the collection of the levels where this agent lies, i.e. the levels where this agent has a local state.

This method returns the levels in which the agent is defined, i.e. a list containing the identifier of each level l∈𝕃 such that φ_a(]t,t′[, l) exists. The value of ]t,t′[ is defined by the context in which this method is called.

Usage and safety

This method has to be used only in the simulation engine.

This method has to ensure that two consecutive iterations over this set always return its items in the same order.

Returns:

A collection containing the identifier of the levels where this agent lies.

getGlobalState

IGlobalState getGlobalState()

Gets the global state of the agent.

This method returns the value μ_a(t) or μ_a(]t,t′[)∈𝕄_a, where the value of ]t,t′[ is defined by the context in which this method is called.

Usage and safety

This method has to be used only in the simulation engine.

Returns:

The global state of the agent.

getPublicLocalState

ILocalStateOfAgent getPublicLocalState(LevelIdentifier levelIdentifier)

Gets the public local state of the agent located in a specific level of the simulation.

This method returns the value φ_a⁺(t, levelIdentifier) or φ_a⁺(]t,t′[, levelIdentifier) ∈Φ_a⁺, where the value of ]t,t′[ is defined by the context in which this method is called.

Usage and safety

This method has to be used only in the simulation engine.

Parameters:

levelIdentifier - The identifier of the level of the public local state;

Returns:

The public local state of the agent in the specified level.

Throws:

NoSuchElementException - If the agent does not define a public local state for the provided level identifier.

getPrivateLocalState

ILocalStateOfAgent getPrivateLocalState(LevelIdentifier levelIdentifier)

Gets the private local state of the agent located in a specific level of the simulation.

This method returns the value φ_a^-(t, levelIdentifier) or φ_a^-(]t,t′[, levelIdentifier) ∈Φ_a^-, where the value of ]t,t′[ is defined by the context in which this method is called.

Usage and safety

This method has to be used only in the simulation engine or in the reaction of the level identified by levelIdentifier.

Parameters:

levelIdentifier - The identifier of the level of the private local state;

Returns:

The private local state of the agent in the specified level.

Throws:

NoSuchElementException - If the agent does not define a private local state for the provided level identifier.

perceive

IPerceivedData perceive(LevelIdentifier level,
                        SimulationTimeStamp timeLowerBound,
                        SimulationTimeStamp timeUpperBound,
                        Map<LevelIdentifier,ILocalStateOfAgent> publicLocalStates,
                        ILocalStateOfAgent privateLocalState,
                        IPublicDynamicStateMap dynamicStates)

Creates the data perceived by an agent located in a specific level.

This method corresponds to the application perception_{a, ]t,t+dtl[, l} of this agent.

Parameters:

level - The level from which perception is made (i.e. "l" in the notations).

timeLowerBound - Is the lower bound of the transitory period of the level identified by level from which the perception is made by this agent (i.e. "t" in the notations).

timeUpperBound - Is the upper bound of the transitory period of the level identified by level from which the perception is made by this agent (i.e. t+dt_l in the notations).

publicLocalStates - All the public local states of the agent.

privateLocalState - The private local state of the agent in the level from which perception is made (i.e. φ_a^-( t, level ) in the notations).

dynamicStates - The dynamic state of the various levels that can be perceived from the level level. This value has previously been disambiguated by a heuristic defined in the simulation engine.

Returns:

The data being perceived by the agent from the level identified by level, for the transitory period ]timeLowerBound, timeUpperBound[.

reviseGlobalState

void reviseGlobalState(SimulationTimeStamp timeLowerBound,
                       SimulationTimeStamp timeUpperBound,
                       Map<LevelIdentifier,IPerceivedData> perceivedData,
                       IGlobalState globalState)

Revises the content of the global state of the agent, using the previous value of its global state and the data that were lastly perceived by the agent.

This method corresponds to the application memoryRev_{a, ]t,t+dt[} of this agent.

As a side effect of this method call, the value μ_a( t ) of the argument globalState is updated to become μ_a(]t,t+dt[)

Parameters:

timeLowerBound - Is the lower bound of the transitory period for which the global state revision is made by this agent (i.e. "t" in the notations).

timeUpperBound - Is the upper bound of the transitory period for which the global state revision is made by this agent (i.e. "t+dt" in the notations).

perceivedData - The map containing the data that were lastly perceived from the various levels of the simulation.

globalState - The previous value of the global state of the agent being updated by this method call.

decide

void decide(LevelIdentifier levelId,
            SimulationTimeStamp timeLowerBound,
            SimulationTimeStamp timeUpperBound,
            IGlobalState globalState,
            ILocalStateOfAgent publicLocalState,
            ILocalStateOfAgent privateLocalState,
            IPerceivedData perceivedData,
            InfluencesMap producedInfluences)

Produces the influences resulting from the decisions of an agent from a specific level, for a specific transitory period.

This method corresponds to the application decision_{a, ]t,t+dtl[,l} of this agent.

Parameters:

levelId - The identifier of the level from which the decision is made (i.e. "l" in the notations).

timeLowerBound - Is the lower bound of the transitory period for which the decision is made by this agent (i.e. "t" in the notations).

timeUpperBound - Is the upper bound of the transitory period for which the decision is made by this agent (i.e. "t+dt" in the notations).

globalState - The revised global state of the agent when it made a decision (i.e. μ_a(t+dt) in the notations).

publicLocalState - The public local state of the agent in the level from which decision is made (i.e. φ_a⁺( t, level ) in the notations).

privateLocalState - The private local state of the agent in the level from which decision is made (i.e. φ_a^-( t, level ) in the notations).

perceivedData - The data that were perceived about the level identified by levelId and its perceptible levels.

producedInfluences - The map where the influences resulting from the decisions are stored.