Package fr.univ_artois.lgi2a.similar.microkernel.libs.tools.engine

Class AbstractSimulationEngineWithInitialization

    • Constructor Detail

      • AbstractSimulationEngineWithInitialization

        public AbstractSimulationEngineWithInitialization()
        Builds an instance of this simulation engine.

    • Method Detail

      • isAbortionRequested

        public boolean isAbortionRequested()
        Tells if the simulation has to be aborted or not.
        Returns:
        true if the user requested the abortion of the simulation.

      • getAgents

        public Set<IAgent4Engine> getAgents()
        Gets the set of all the agents lying in the simulation.

        Usage

        This method is used in probes to read the data about the simulation, when the simulation reaches a time stamp.

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

        Returns:
        The set of all the agents lying in the simulation.

      • getLevelIdentifiers

        public Set<LevelIdentifier> getLevelIdentifiers()
        Gets the set of level identifiers contained in the simulation.

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

        Returns:
        The list of levels contained in the simulation.

      • getLevels

        public Map<LevelIdentifier,​ILevel> getLevels()
        Gets the list of levels contained in the simulation.

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

        Returns:
        The list of levels contained in the simulation.

      • getAgents

        public Set<IAgent4Engine> getAgents​(LevelIdentifier level)
        Gets the set of all the agents lying in a specific level of the simulation.

        Usage

        This method is used in probes to read the data about the simulation, when the simulation reaches a time stamp.

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

        Parameters:
        level - The levels where to get the agents.
        Returns:
        The set of all the agents lying in a specific level of in the simulation.

      • getEnvironment

        public IEnvironment4Engine getEnvironment()
        Gets the environment the simulation.

        Usage

        This method is used in probes to read the data about the simulation, when the simulation reaches a time stamp.

        Returns:
        The environment of the simulation.

      • disambiguation

        public ConsistentPublicLocalDynamicState disambiguation​(TransitoryPublicLocalDynamicState transitoryDynamicState)
        Disambiguates a public local dynamic state, i.e. transforms a transitory state into a fully observable state.

        This operation can introduce biases since it provides an estimation of the real state of a level, using the information stored into a transitory dynamic state.

        Parameters:
        transitoryDynamicState - The transitory state for which a disambiguation is computed.
        Returns:
        the observable dynamic state corresponding to the disambiguation of the transitory dynamic state.

      • getSimulationDynamicStates

        public IPublicDynamicStateMap getSimulationDynamicStates()
        Gets the current dynamic states of the simulation.

        Usage

        This method is used in probes to read the data about the simulation, when the simulation reaches a time stamp.

        Returns:
        The dynamic state of the simulation, containing either consistent states (the current time stamp of the simulation is equal to the time stamp of the level) or transitory states (in the other case).

      • requestSimulationAbortion

        public void requestSimulationAbortion()
        Requests the abortion of the simulation currently running with this simulation engine. In response, the simulation engine will stop the simulation once the simulation reaches a partly-consistent state.

      • runNewSimulation

        public void runNewSimulation​(ISimulationModel simulationModel)
        Initializes and then runs completely a simulation.

        This method has the responsibility to call the appropriate methods of the probes at the different moments of the simulation.

        Parameters:
        simulationModel - The simulation model running the simulation.

      • runNewSimulationWithoutCheckingErrors

        public void runNewSimulationWithoutCheckingErrors​(ISimulationModel simulationModel)
        Performs the same task than the runNewSimulation(ISimulationModel) method, but without checking errors.
        Parameters:
        simulationModel - The simulation model used to generate a new simulation.

      • initializeSimulation

        protected void initializeSimulation​(ISimulationModel simulationModel)
        Initializes the simulation that will run.
        Parameters:
        simulationModel - The model of the simulation instance being run with this engine.
        Throws:
        IllegalArgumentException - if:
        • No level was defined for this simulation.
        • The name of a level is null.
        • Two levels have the same name.
        • The environment of the simulation is null
        IllegalStateException - If the simulation model contains errors.

      • performSimulation

        protected SimulationTimeStamp performSimulation​(ISimulationModel simulationModel)
        Runs the simulation, so that it will go from its initial state to its final state.
        Parameters:
        simulationModel - The model of the simulation.
        Returns:
        The final time stamp of the simulation.
        Throws:
        ExceptionSimulationAborted - If the simulation was aborted by the user.
        Exception - If an exception was caught while running the simulation.

      • performSimulation

        protected abstract SimulationTimeStamp performSimulation​(ISimulationModel simulationModel,
                                                         DynamicStateMap currentSimulationDynamicState,
                                                         LinkedHashMap<LevelIdentifier,​ILevel> levels,
                                                         LinkedHashMap<LevelIdentifier,​LinkedHashSet<IAgent4Engine>> agents,
                                                         IEnvironment4Engine environment)
        Runs the simulation, so that it goes from its current initial state to its final state.

        Implementation instructions

        This method has multiple roles along the execution of the simulation:

        • Determine when the perception, global state revision and decision methods of the agents are called, using the value of the levels, agents and environment arguments.
        • Determine when the natural method of the environment is called using the value of the levels, agents and environment arguments.
        • Determine when the reaction of a level is computed using the value of the levels, agents and environment arguments.
        • Determine how the reaction is computed:
          • Write how the system influences are managed: the addition of the public local state of an agent to a level implies the addition of the agent for that level in the levels argument.
          • Include the produced influences either into the reaction of other levels, or in their transitory state dynamics
        • Update the content of the levels, agents and environment arguments according to the changes occurring during the execution of the simulation.
        • When the simulation reaches an half-consistent state, this method has to update the value of the currentSimulationDynamicState argument to match the real state of the simulation: if a level is consistent, then its consistent state has to be put in currentSimulationDynamicState (see ILevel.getLastConsistentState()). If it is transitory, then its transitory state has to be put in currentSimulationDynamicState (see ILevel.getLastTransitoryState());
        • When the simulation reaches an half-consistent state, this method has the responsibility to call the IProbe.observeAtPartialConsistentTime(SimulationTimeStamp, fr.univ_artois.lgi2a.similar.microkernel.ISimulationEngine) method of each probe of the simulation (after the operations described in the previous item of this list);
        • After each reaction phase, check that the abortion flag is raised (see isAbortionRequested()). If true, stop the execution of the simulation and throw an ExceptionSimulationAborted exception.
        Parameters:
        simulationModel - The model of the simulation being run.
        currentSimulationDynamicState - Models the public local dynamic states of the simulation being forwarded to the probes to display the content of the simulation. This map contains either consistent dynamic states (if the current time stamp of the simulation is equal to the current time stamp of the level) or transitory dynamic state (if the level is currently between two of its time stamps).
        levels - A map associating a level to its identifier. This map initially contains the levels in their initial state.
        agents - A map associating the agents lying in each level of the simulation to the identifier of the level. This map contains the initial agents of the simulation, in their initial state.
        environment - The environment where the simulation takes place. This environment is in its initial state.
        Returns:
        The final time stamp of the simulation.