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.

Nested Class Summary

Nested classes/interfaces inherited from class madkit.kernel.Agent

Agent.ReturnCode

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	SimuLauncher()	Default constructor.

Method Summary

Modifier and Type	Method	Description
String	getCommunity()	Returns the name of the simulation community.
static final List<String>	getEngineAgentsArgsFrom(Class<?> target)	Gets the engine agents args from.
String	getEngineGroup()	Returns the engine group associated with the simulation.
<E extends SimuEnvironment> E	getEnvironment()	Gets the environment.
<M extends SimuModel> M	getModel()	Gets the model.
String	getModelGroup()	Returns the model group associated with the simulation.
long	getPRNGSeedIndex()	Returns the seed used to create the PRNG.
<S extends Scheduler<?>> S	getScheduler()	Gets the scheduler.
List<SimuAgent>	getViewers()	Returns the the viewers that are actually running.
protected void	onActivation()	This method is called when the simulation engine is activated.
RandomGenerator	onCreateRandomGenerator()	Creates the pseudo random number generator that has to be used by the simulation.
void	onInitializeSimulationSeedIndex()	Initializes the simulation seed index.
protected <E extends SimuEnvironment> E	onLaunchEnvironment()	Launches the simulation environment agent and logs the event.
protected <M extends SimuModel> M	onLaunchModel()	Returns the seed used to create the PRNG.
protected <S extends Scheduler<?>> S	onLaunchScheduler()	Launches the simulation scheduler agent and logs the event.
protected void	onLaunchSimulatedAgents()	Launches the simulation agents.
protected void	onLaunchViewers()	Launches the simulation viewers agents and logs their launch.
void	onSimulationStart()	Called before the simulation starts.
RandomGenerator	prng()	Returns the pseudo random number generator that has to be used by the simulation agents.
void	setPRNGSeedIndex(int seedIndex)	Sets the seed which is used to create a PRNG.
void	setRandomGnerator(RandomGenerator randomGenerator)	Sets the pseudo random number generator that has to be used by the simulation.
protected void	startSimulation()	Start simulation.

Methods inherited from class madkit.kernel.Watcher

addProbe, getProbes, onEnd, removeAllProbes, removeProbe, toString

Methods inherited from class madkit.simulation.SimuAgent

createSimuGroup, getLauncher, getNextEventDate, getSimuTimer, launchAgent, leaveRole, leaveSimuGroup, leaveSimuRole, playRole, requestSimuRole

Methods inherited from class madkit.kernel.Agent

activate, broadcast, broadcastWithRole, broadcastWithRoleWaitForReplies, checkAgentAddress, createGroup, createGroup, createGroup, end, equals, executeThisAgent, executeThisAgent, exitOnKill, getAgentsWithRole, getAgentWithRole, getKernelAddress, getKernelConfig, getLogger, getMailbox, getName, getNetworkID, getOrganization, getReplyTo, handleRequestActionMessage, hashCode, isAlive, killAgent, killAgent, launchAgent, launchAgent, leaveGroup, leaveRole, live, nextMessage, onLive, pause, receiveMessage, reload, reply, replyWithRole, requestRole, requestRole, send, send, sendWaitReply, sendWaitReply, sendWithRole, sendWithRole, sendWithRoleWaitReply, sendWithRoleWaitReply, setupDefaultGUI, waitAnswer, waitAnswer, waitNextMessage, waitNextMessage

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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:

• the model agent by calling the onLaunchModel() method
• the environment agent by calling the onLaunchEnvironment() method
• the scheduler agent by calling the onLaunchScheduler() method
• the viewers agents by calling the onLaunchViewers() method
• the simulated agents by calling the onLaunchSimulatedAgents() method

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