Package fr.univ_artois.lgi2a.similar.extendedkernel.levels

Class ExtendedLevel

java.lang.Object

fr.univ_artois.lgi2a.similar.microkernel.libs.abstractimpl.AbstractLevel

fr.univ_artois.lgi2a.similar.extendedkernel.levels.ExtendedLevel

All Implemented Interfaces:

ILevel, ITimeModel

public class ExtendedLevel
extends AbstractLevel

Models a level in the extended kernel.

On the opposite of the micro-kernel, where level classes had to be created, this class is self-sufficient. The operational code of the reaction processes and of the time model is defined in a separate class. The level class only stores a reference to this class.

Benefits

This property has a huge benefit:

• The behavior of the environment can evolve at runtime.

Level specification

The specification of such levels requires the following operations during the initialization of the simulation:

• The initialization of the dynamic state of the level, using the following methods:
  • IModifiablePublicLocalDynamicState.setPublicLocalStateOfEnvironment(fr.univ_artois.lgi2a.similar.microkernel.environment.ILocalStateOfEnvironment)
• The specification of the reaction model of the level, using the setReactionModel(ILevelReactionModel) method.

Introspection and intercession

Level introspection is achieved with the following methods:

• getTimeModel()
• getReactionModel()

Level intercession is achieved with the following methods:

• setReactionModel(ILevelReactionModel)

Author:

Yoann Kubera

Constructor Summary

Constructors

Constructor	Description
ExtendedLevel(SimulationTimeStamp initialTime, LevelIdentifier identifier, ITimeModel timeModel, ILevelReactionModel reactionModel)	Builds an initialized instance of level having a specific identifier, a perception and influence relation graph containing only an edge between this level and itself, a specific time model and no reaction model.

Method Summary

Modifier and Type	Method	Description
SimulationTimeStamp	getNextTime(SimulationTimeStamp currentTime)	Gets the time stamp following a specific time stamp in this model.
ILevelReactionModel	getReactionModel()	Gets the reaction model used by the level.
ITimeModel	getTimeModel()	Gets the time model used by this level.
void	makeRegularReaction(SimulationTimeStamp transitoryTimeMin, SimulationTimeStamp transitoryTimeMax, ConsistentPublicLocalDynamicState consistentState, Set<IInfluence> regularInfluencesOftransitoryStateDynamics, InfluencesMap remainingInfluences)	Performs a user-defined reaction to the regular influences that were lying in the most recent consistent dynamic state of the level and to the influences that were added into the transitory dynamic state of the level.
void	makeSystemReaction(SimulationTimeStamp transitoryTimeMin, SimulationTimeStamp transitoryTimeMax, ConsistentPublicLocalDynamicState consistentState, Collection<IInfluence> systemInfluencesToManage, boolean happensBeforeRegularReaction, InfluencesMap newInfluencesToProcess)	Performs a user-defined reaction to the system influences that are lying in the most recent consistent dynamic state of the level and to the influences that were added into the transitory dynamic state of the level.
void	setReactionModel(ILevelReactionModel newReactionModel)	Sets the reaction model used by the level.

Methods inherited from class fr.univ_artois.lgi2a.similar.microkernel.libs.abstractimpl.AbstractLevel

addInfluenceableLevel, addPerceptibleLevel, getIdentifier, getInfluenceableLevels, getLastConsistentState, getLastTransitoryState, getPerceptibleLevels, initializeStates

Methods inherited from class java.lang.Object

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

Constructor Detail

ExtendedLevel

public ExtendedLevel(SimulationTimeStamp initialTime,
                     LevelIdentifier identifier,
                     ITimeModel timeModel,
                     ILevelReactionModel reactionModel)

Builds an initialized instance of level having a specific identifier, a perception and influence relation graph containing only an edge between this level and itself, a specific time model and no reaction model.

The dynamic state has to be initialized using the following methods:

• The initialization of the dynamic state of the level, using the following methods:
  • IModifiablePublicLocalDynamicState.setPublicLocalStateOfEnvironment(fr.univ_artois.lgi2a.similar.microkernel.environment.ILocalStateOfEnvironment)
• The specification of the reaction model of the level, using the setReactionModel(ILevelReactionModel) method.

Parameters:

initialTime - The initial time stamp of the level.

identifier - The identifier of the level.

timeModel - The time model used by this level.

reactionModel - The reaction model used by this level.

Method Detail

getTimeModel

public ITimeModel getTimeModel()

Gets the time model used by this level.

Returns:

The time model used by this level.

getReactionModel

public ILevelReactionModel getReactionModel()

Gets the reaction model used by the level.

Returns:

The reaction model used by the level.

Throws:

NoSuchElementException - If no reaction model is defined for this level.

setReactionModel

public void setReactionModel(ILevelReactionModel newReactionModel)

Sets the reaction model used by the level.

Parameters:

newReactionModel - The new reaction model used by the level.

makeRegularReaction

public void makeRegularReaction(SimulationTimeStamp transitoryTimeMin,
                                SimulationTimeStamp transitoryTimeMax,
                                ConsistentPublicLocalDynamicState consistentState,
                                Set<IInfluence> regularInfluencesOftransitoryStateDynamics,
                                InfluencesMap remainingInfluences)

Performs a user-defined reaction to the regular influences that were lying in the most recent consistent dynamic state of the level and to the influences that were added into the transitory dynamic state of the level.

Usage

This method has to:

• Update the local state of the environment and of the agents contained in the consistent dynamic state consistentState argument of this method according to the modifications depicted by the regular influences.
• Add to the newInfluencesToProcess set the influences persisting after the reaction. The influences that were consumed by the reaction are not added to this set.
• Add to the newInfluencesToProcess set the new influences that were produced by this reaction (for instance the addition of an agent to the simulation). The system reactions will be processed after this user reaction to regular influences if the level they are aimed at is a level currently computing its reaction. Otherwise, the system influence is managed during the next reaction of the targeted level. Moreover, the regular influences added in such a way will be processed during the next reaction of the level they are aimed at.

This method cannot:

• Add influences directly into the consistent state of the simulation. If it does so, it puts the simulation into an inconsistent state.

Parameters:

transitoryTimeMin - The lower bound of the transitory period of the level for which this reaction is performed.

transitoryTimeMax - The upper bound of the transitory period of the level for which this reaction is performed.

consistentState - The consistent state being updated by this user reaction.

regularInfluencesOftransitoryStateDynamics - The regular influences that have to be managed by this reaction to go from the previous consistent state to the next consistent state of the level.

remainingInfluences - The data structure that will contain the influences that were produced by the user during the invocation of this method, or the influences that persist after this reaction.

makeSystemReaction

public void makeSystemReaction(SimulationTimeStamp transitoryTimeMin,
                               SimulationTimeStamp transitoryTimeMax,
                               ConsistentPublicLocalDynamicState consistentState,
                               Collection<IInfluence> systemInfluencesToManage,
                               boolean happensBeforeRegularReaction,
                               InfluencesMap newInfluencesToProcess)

Performs a user-defined reaction to the system influences that are lying in the most recent consistent dynamic state of the level and to the influences that were added into the transitory dynamic state of the level. This method is called twice during the reaction phase of the level:

• A first time right after the system reaction to the system influences happening at the beginning of the reaction phase. It gives the opportunity to perform a user-defined reaction to the system influences that were added to the transitory dynamic state of the level during the transitory period (for instance to add an agent to the topology of the environment).
• A second time right after the system reaction to the system influences happening after the user-defined reaction to the regular influences. It gives the opportunity to perform a user-defined reaction to the system influences that were created by the user during the user reaction to the regular influences.

Usage

This method can:

• Update the local state of the environment and of the agents contained in the consistent dynamic state consistentState argument of this method according to the modifications depicted by the system influences. For instance, if the public local state of the environment defines an agent grid, this method can add the public local state of an agent to the grid, in reaction to the 'add agent to level' system influence.
• Add to the newInfluencesToProcess set the new influences that were produced by this reaction (for instance the addition of a new agent to the simulation). The influences added in such a way will be processed either during the next reaction of the level they are aimed at (happensBeforeRegularReaction false or the level being targeted by the influence is not currently computing a reaction).

This method cannot:

• Add influences directly into the consistent state of the simulation. If it does so, it puts the simulation into an inconsistent state.

Parameters:

transitoryTimeMin - The lower bound of the transitory period of the level for which this reaction is performed.

transitoryTimeMax - The upper bound of the transitory period of the level for which this reaction is performed.

consistentState - The consistent state of the level being progressively updated by the reaction to go from its value at the time transitoryTimeMin to its value at the time transitoryTimeMax. Note that this state already includes the side effects of the system influences listed in the systemInfluencesToManage argument.

systemInfluencesToManage - The system influences that have to be managed by this reaction to go from the previous consistent state to the next consistent state of the level.

happensBeforeRegularReaction - true if this user-defined system reaction is performed before the call to the ILevel.makeRegularReaction(SimulationTimeStamp, SimulationTimeStamp, ConsistentPublicLocalDynamicState, Set, InfluencesMap) method.

newInfluencesToProcess - The data structure where the influences resulting from this user reaction have to be added.

getNextTime

public SimulationTimeStamp getNextTime(SimulationTimeStamp currentTime)

Gets the time stamp following a specific time stamp in this model.

Note: for simulation consistency reasons, this method has to be deterministic: calling twice this method with the same parameter has to produce the same output.

Parameters:

currentTime - The time stamp for which this method computes a successor.

Returns:

The time stamp following the currentTime time stamp.