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. See onActivation() for a detailed description of the simulation initialization process.

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.

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

  • Constructor Details

    • SimuLauncher

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

  • Method Details

    • onActivation

      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 (prng) by calling the onCreateRandomGenerator().

      Then, it launches the engine agents of the simulation in the following order:

      Then, it calls the onSimulationStart() method.

      Finally, if the start switch is passed on the command line or through the arguments of the main method, it automatically starts the simulation by calling the startSimulation(), which, by default, send the starting message to the scheduler.

      Overrides:
      onActivation in class Watcher

    • onCreateRandomGenerator

      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

      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

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

    • onInitializeSimulationSeedIndex

      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

      public void onSimulationStart()
      Called before the simulation starts. By default, it calls in the following order, 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

      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

      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

      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

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

    • onLaunchSimulatedAgents

      protected void onLaunchSimulatedAgents()
      Launches the simulation agents.

    • startSimulation

      protected void startSimulation()
      Start simulation.

    • getScheduler

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

    • getEnvironment

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

    • getModel

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

    • getEngineAgentsArgsFrom

      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

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

    • getCommunity

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

    • getEngineGroup

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

    • getViewers

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

    • prng

      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

      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