Class SimuLauncher

java.lang.Object
madkit.kernel.Agent
madkit.simulation.SimuAgent
madkit.kernel.Watcher
madkit.simulation.SimuLauncher
public abstract class SimuLauncher extends Watcher
Main class for launching a simulation. This class is responsible for initializing the simulation environment, simulation model, and scheduler. It also launches the simulation agents and viewers.

This class is intended to be extended by the user to define the simulation engine, if the default setup should customized. The user can define the simulation environment, model, and scheduler classes by overriding the onLaunchEnvironment(), onLaunchModel(), and onLaunchScheduler() methods, respectively. The user can also define the simulation agents and viewers by overriding the onLaunchSimulatedAgents() and onLaunchViewers() methods, respectively. The user can also define the simulation startup behavior by overriding the onSimulationStart() method.

Crucially, this class is also responsible for initializing the pseudo random number generator (PRNG) that has to be used by the simulation agents for ensuring the reproducibility of the simulation. The PRNG is initialized with a seed that can be set by the user. The seed is a long integer that can be set by the user by overriding the onInitializeSimulationSeedIndex() method. By default, the seed index is 0. See onInitializeSimulationSeedIndex() method.

  • Constructor Details Link icon

    • SimuLauncher Link icon

      protected SimuLauncher()
      Default constructor. It initializes the simulation community name to the class name of the simulation engine.

  • Method Details Link icon

    • onActivation Link icon

      protected void onActivation()
      This method is called when the simulation engine is activated. It initializes the simulation community, creates the engine and model groups, and requests the role SimuOrganization.LAUNCHER_ROLE in the group SimuOrganization.ENGINE_GROUP. Then, it initiates the simulation by first creating the pseudo random number generator by calling the onCreateRandomGenerator(). Then, it launches the simulation model, environment, scheduler, and viewers by calling in order the onLaunchModel(), onLaunchEnvironment(), onLaunchScheduler(), onLaunchViewers(), and onLaunchSimulatedAgents() methods. Finally, it calls the onSimulationStart() method. If the start parameter is set to true, it starts the simulation by calling the startSimulation()

      By default the logger level is set to Level.INFO.

      Overrides:
      onActivation in class Watcher

    • onCreateRandomGenerator Link icon

      public RandomGenerator onCreateRandomGenerator()
      Creates the pseudo random number generator that has to be used by the simulation. The seed index is taken from the kernel configuration. If the seed index is not set, the default value is 0.
      Returns:
      the pseudo random number generator that will be used by the simulation

    • setPRNGSeedIndex Link icon

      public void setPRNGSeedIndex(int seedIndex)
      Sets the seed which is used to create a PRNG. The actual seed that will be used will be computed by adding seedIndex to the built-in long (0xFEDCBA0987654321L), which is used as initial seed. This is done so that the obtained long respects the many seed bits characteristic. Moreover it is known that a good practice, considering how seeds should be chosen, is to take them in sequence. See this blog: Random number generator seed mistakes So a simulation suite can be obtained by using this method with a consecutive list of int: 1, 2, 3...
      Parameters:
      seedIndex - the seed index to set. Privilege the use of sequence of integers such as 0, 1, 2...

    • getPRNGSeedIndex Link icon

      public long getPRNGSeedIndex()
      Returns the seed used to create the PRNG.
      Returns:
      the seed used to create the PRNG

    • onInitializeSimulationSeedIndex Link icon

      public void onInitializeSimulationSeedIndex()
      Initializes the simulation seed index. By default, the seed index is taken from the kernel configuration, and if not set the seed index is set 0.

    • onSimulationStart Link icon

      public void onSimulationStart()
      Called before the simulation starts. By default, it calls the Scheduler.onSimulationStart(), SimuAgent.onSimulationStart(), SimuAgent.onSimulationStart(), and SimuAgent.onSimulationStart() methods for each viewer.

      This method can be overridden by the user to define fine tuning of the simulation initialization.

      Overrides:
      onSimulationStart in class SimuAgent

    • onLaunchModel Link icon

      protected <M extends SimuModel> M onLaunchModel()
      Returns the seed used to create the PRNG.
      Type Parameters:
      M - the type of the model
      Returns:
      the model agent for this simulation

    • onLaunchEnvironment Link icon

      protected <E extends SimuEnvironment> E onLaunchEnvironment()
      Launches the simulation environment agent and logs the event.
      Type Parameters:
      E - the type of the environment
      Returns:
      the environment agent for this simulation

    • onLaunchScheduler Link icon

      protected <S extends Scheduler<?>> S onLaunchScheduler()
      Launches the simulation scheduler agent and logs the event.
      Type Parameters:
      S - the type of the scheduler
      Returns:
      the scheduler agent for this simulation

    • onLaunchViewers Link icon

      protected void onLaunchViewers()
      Launches the simulation viewers agents and logs their launch.

    • onLaunchSimulatedAgents Link icon

      protected abstract void onLaunchSimulatedAgents()
      Launches the simulation agents.

    • startSimulation Link icon

      protected void startSimulation()
      Start simulation.

    • getScheduler Link icon

      public <S extends Scheduler<?>> S getScheduler()
      Gets the scheduler.
      Overrides:
      getScheduler in class SimuAgent
      Type Parameters:
      S - the generic type
      Returns:
      the scheduler

    • getEnvironment Link icon

      public <E extends SimuEnvironment> E getEnvironment()
      Gets the environment.
      Overrides:
      getEnvironment in class SimuAgent
      Type Parameters:
      E - the element type
      Returns:
      the environment

    • getModel Link icon

      public <M extends SimuModel> M getModel()
      Gets the model.
      Overrides:
      getModel in class SimuAgent
      Type Parameters:
      M - the generic type
      Returns:
      the model

    • getEngineAgentsArgsFrom Link icon

      public static final List<String> getEngineAgentsArgsFrom(Class<?> target) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException, SecurityException
      Gets the engine agents args from.
      Parameters:
      target - the target
      Returns:
      the engine agents args from
      Throws:
      IllegalAccessException - the illegal access exception
      InvocationTargetException - the invocation target exception
      NoSuchMethodException - the no such method exception
      SecurityException - the security exception

    • getModelGroup Link icon

      public String getModelGroup()
      Returns the model group associated with the simulation.
      Overrides:
      getModelGroup in class SimuAgent
      Returns:
      the model group

    • getCommunity Link icon

      public String getCommunity()
      Returns the name of the simulation community.
      Overrides:
      getCommunity in class SimuAgent
      Returns:
      the community

    • getEngineGroup Link icon

      public String getEngineGroup()
      Returns the engine group associated with the simulation.
      Overrides:
      getEngineGroup in class SimuAgent
      Returns:
      the name of the engine group

    • getViewers Link icon

      public List<SimuAgent> getViewers()
      Returns the the viewers that are actually running.
      Overrides:
      getViewers in class SimuAgent
      Returns:
      the running viewers

    • prng Link icon

      public RandomGenerator prng()
      Returns the pseudo random number generator that has to be used by the simulation agents.
      Overrides:
      prng in class SimuAgent
      Returns:
      the pseudo random number generator of the simulation

    • setRandomGnerator Link icon

      public void setRandomGnerator(RandomGenerator randomGenerator)
      Sets the pseudo random number generator that has to be used by the simulation.
      Parameters:
      randomGenerator - the randomGenerator to set