Package fr.univ_artois.lgi2a.similar.microkernel.levels

Interface ILevel

  • All Superinterfaces:
    ITimeModel
    All Known Implementing Classes:
    AbstractLevel, ExtendedLevel
    public interface ILevel
extends ITimeModel
    Models a level of the simulation.

    Correspondence with theory

    An instance of this class models a level l∈𝕃

    Usage

    The reaction of a level is a process changing the value of the last consistent public local dynamic state of the level from a time stamp tl to the next time stamp of the level tl+dtl. This process relies on the following steps:

    1. The engine first loops over the system influences located in both the last consistent dynamic state δl(tl) and the ones located in the transitory dynamic state of the level right before the computation of the reaction. During this loop, the engine removes the processed system influences from the both dynamic states. This process might add new influences to the simulation (for instance the 'add agent to simulation' influence produces 'add public local state of agent to level' influences). In such a case, if at least one added influence is a system influence, the engine performs another loop to manage them.
    2. Once all the system influences are processed, the engine performs a user-defined reaction to the system influences, as described by the makeSystemReaction(SimulationTimeStamp, SimulationTimeStamp, ConsistentPublicLocalDynamicState, Collection, boolean, InfluencesMap) method. This user-defined reaction:
      • Updates the public local state of the environment and of the agents contained in the last consistent dynamic state, according to the modifications depicted by the regular influences. This operation is part of the transformation of the last consistent dynamic state δl(tl) into the new last consistent dynamic state δl(tl + dtl). 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 public local state of agent to level' system influence.
      • Can produce new influences (for instance the addition of an agent to the simulation). The system influences added in such a way will be processed either during the next reaction of the level they are aimed at (if the targeted level is not currently computing its reaction), or during the current reaction (in the next steps of this process).
    3. The engine then performs a user-defined reaction to the regular influences, as described by the makeRegularReaction(SimulationTimeStamp, SimulationTimeStamp, ConsistentPublicLocalDynamicState, Set, InfluencesMap) method. This user-defined reaction:
      • Updates the public local state of the environment and of the agents contained in the last consistent dynamic state, according to the modifications depicted by the regular influences. This operation is part of the transformation of the last consistent dynamic state δl(tl) into the new last consistent dynamic state δl(tl + dtl).
      • Determines which regular influences do persist after the reaction and which ones are consumed by the reaction (and are thus not retained in the new last consistent dynamic state).
      • Can produce new influences (for instance the addition of an 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 (if the targeted level is not currently computing its reaction or if the influence is a regular influence), or during the current reaction (in the next steps of this process).
    4. The engine then loops again over the system influences that were added by the user-defined reactions into the levels that are computing a reaction. During this loop, the engine removes the processed system influences from the both dynamic states. This process might add new influences to the simulation (for instance the 'add agent to simulation' influence produces 'add public local state of agent to level' influences). In such a case, if at least one added influence is a system influence, the engine performs another loop to manage them.
    5. Once all the system influences are processed, the engine performs a user-defined reaction to the system influences, as described by the makeSystemReaction(SimulationTimeStamp, SimulationTimeStamp, ConsistentPublicLocalDynamicState, Collection, boolean, InfluencesMap) method. This user-defined reaction:
      • Updates the public local state of the environment and of the agents contained in the last consistent dynamic state, according to the modifications depicted by the regular influences. This operation is part of the transformation of the last consistent dynamic state δl(tl) into the new last consistent dynamic state δl(tl + dtl). 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 public local state of agent to level' system influence.
      • Can produce new influences (for instance the addition of an agent to the simulation). The influences added in such a way will be processed during the next reaction of the level they are aimed at.
    Author:
    Yoann Kubera

    • Method Detail

      • getIdentifier

        LevelIdentifier getIdentifier()
        Gets the identifier of this level.
        Returns:
        The identifier of this level.

      • getPerceptibleLevels

        Set<LevelIdentifier> getPerceptibleLevels()
        Gets the levels that can be perceived by agents located in this level.

        It corresponds to the out neighborhood NP+( this )⊂𝔾P of the this level in the perception relation graph.

        Returns:
        The levels that can be perceived by agents located in this level.

      • getInfluenceableLevels

        Set<LevelIdentifier> getInfluenceableLevels()
        Gets the levels that can be influenced by agents located in this level.

        It corresponds to the out neighborhood NI+( this )⊂𝔾I of the this level in the perception relation graph.

        Returns:
        The levels that can be influenced by agents located in this level.

      • getLastConsistentState

        ConsistentPublicLocalDynamicState getLastConsistentState()
        Gets the last consistent dynamic state of the level.
        Returns:
        The last consistent dynamic state of the level.

      • getLastTransitoryState

        TransitoryPublicLocalDynamicState getLastTransitoryState()
        Gets the last transitory dynamic state of the level.
        Returns:
        The last transitory dynamic state of the level.

      • makeRegularReaction

        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

        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 makeRegularReaction(SimulationTimeStamp, SimulationTimeStamp, ConsistentPublicLocalDynamicState, Set, InfluencesMap) method.
        newInfluencesToProcess - The data structure where the influences resulting from this user reaction have to be added.