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 onSetupSimulation() 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 onSetupSimulation() 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

      protected RandomGenerator onCreateRandomGenerator()
      Creates the pseudo random number generator that has to be used by the simulation. The seed index is taken using
      invalid reference 
      #getSeedIndex()
      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 int getPrngSeedIndex()
      Returns the index used to create the PRNG seed.
      Returns:
      the index used to create the PRNG seed

    • onInitializeSimulationSeedIndex

      protected 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, which means that the seed used to create the PRNG will be the built-in long (0xFEDCBA0987654321L) plus 0, and thus the same for all simulations. This allows to have a reproducible simulation when the seed index is not set, and to have different simulations by using different seed indices, for example by using a sequence of integers such as 0, 1, 2... This method can be overridden by the user to define a custom seed index initialization.

    • onSetupSimulation

      public void onSetupSimulation()
      Called just before the simulation starts. By default, it calls in the following order, the SimuAgent.onSetupSimulation(), SimuAgent.onSetupSimulation(), Scheduler.onSetupSimulation(), and SimuAgent.onSetupSimulation() methods for each viewer.

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

      It is worth noting that this method is the latest method called by the launcher on all the engine agents before giving to the scheduler the control of the simulation. This provided that, at this point of the launching process, the simulation is ready to start, i.e.: all the agents participating in the simulation have been launched, and already have their Agent.onActivation() method called.

      By default, this method is not called on the simulated agents, which are not considered as engine agents, and thus not known by the launcher. However, the simulated agents have already been launched and have already had their Agent.onActivation() method called, so they are ready to start the simulation as well.

      So, it is possible to override this method to call the SimuAgent.onSetupSimulation() method on the simulated agents as well, if needed.

      Beware that calling this method programmatically or using the GUI after the simulation has started will break reproducibility of the simulation. This facility is provided for testing purposes, and should be used with caution. The only way to reproduce a simulation is to relaunch it from scratch with the same seed index.

      Overrides:
      onSetupSimulation in class SimuAgent

    • onEnd

      protected void onEnd()
      Called when the simulation ends, as the launcher is killed by the scheduler. By default, the launcher then kills the model, environment, and viewers, so that their onEnd() methods are called.

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

      Overrides:
      onEnd in class Watcher

    • onLaunchModel

      protected <M extends SimuModel> M onLaunchModel()
      Launches the simulation model agent and logs the event. Defaultly, the model class is taken from the annotation EngineAgents if it is defined on the class, or from the kernel configuration. If none of these sources provide a model class, the fallback mode is used, which means that the model class is set to SimuModel. This method could be overridden by the user to define a custom model class or to customize the launch process of the model agent.
      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. Defaultly, the environment class is taken from the annotation EngineAgents if it is defined on the class, or from the kernel configuration. If none of these sources provide an environment class, the fallback mode is used, which means that the environment class is set to SimuEnvironment. This method could be overridden by the user to define a custom environment class or to customize the launch process of the environment agent.
      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. Defaultly, the scheduler class is taken from the annotation EngineAgents if it is defined on the class, or from the kernel configuration. If none of these sources provide a scheduler class, the fallback mode is used, which means that the scheduler class is set to TickBasedScheduler. This method could be overridden by the user to define a custom scheduler class or to customize the launch process of the scheduler agent.
      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. Defaultly, the viewers classes are taken from the annotation EngineAgents if it is defined on the class, or from the kernel configuration. If none of these sources provide viewers classes, the fallback mode is used, which means that no viewer is launched. This method could be overridden by the user to define custom viewers classes or to customize the launch process of the viewers agents.

    • onLaunchSimulatedAgents

      protected void onLaunchSimulatedAgents()
      Launches the simulation agents. Defaultly, no simulated agent is launched. This method could be overridden by the user to define custom simulated agents or to customize the launch process of the simulated 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