Class SimuAgent

java.lang.Object
madkit.kernel.Agent
madkit.simulation.SimuAgent
Direct Known Subclasses:
Scheduler, Watcher
public class SimuAgent extends Agent
An agent class designed to be used with the default simulation engine provided by this package. This class provides a number of convenience methods for interacting with the simulation engine and other agents within the simulation. A SimuAgent has to be launched by a SimuLauncher, or transitively by another agent launched by a SimuLauncher. This is necessary for the SimuAgent to be linked to a SimuLauncher. This ensures that the agent has access to the simulation model, environment, scheduler, and other simulation-specific components. Essentially, this ensures that all the agents of one simulation instance share the same pseudo-random number generator and simulation time. If the agent is not launched by a SimuLauncher, it will throw an IllegalStateException when attempting to access these components.
See Also:

  • Constructor Details

    • SimuAgent

      public SimuAgent()

  • Method Details

    • getLauncher

      public SimuLauncher getLauncher()
      Retrieves the simulation engine associated with this agent.
      Returns:
      the SimuLauncher instance.
      Throws:
      IllegalStateException - if the agent has not been launched or was not launched by a SimuAgent.

    • launchAgent

      public Agent.ReturnCode launchAgent(Agent agent, int timeout)
      Launches a new agent. If the agent being launched is also a SimuAgent, it will inherit the simulation engine from this agent.
      Overrides:
      launchAgent in class Agent
      Parameters:
      agent - the agent to be launched.
      timeout - the maximum time to wait for the agent to launch.
      Returns:
      the result of the launch operation as a Agent.ReturnCode.

    • getCommunity

      public String getCommunity()
      Returns the community associated with the simulation.
      Returns:
      the name of the simulation community.

    • getEngineGroup

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

    • getModelGroup

      public String getModelGroup()
      Returns the model group associated with the simulation.
      Returns:
      the name of the model group.

    • getScheduler

      public <S extends Scheduler<?>> S getScheduler()
      Retrieves the scheduler associated with the simulation engine.
      Type Parameters:
      S - the type of the scheduler.
      Returns:
      the scheduler instance.

    • getModel

      public <M extends SimuModel> M getModel()
      Retrieves the simulation model associated with this agent.
      Type Parameters:
      M - the type of the simulation model.
      Returns:
      the simulation model instance.

    • getEnvironment

      public <E extends SimuEnvironment> E getEnvironment()
      Retrieves the environment associated with the simulation.
      Type Parameters:
      E - the type of the environment.
      Returns:
      the environment instance.

    • prng

      public RandomGenerator prng()
      Retrieves the pseudo-random number generator used in the simulation model.
      Overrides:
      prng in class Agent
      Returns:
      the RandomGenerator instance.

    • getViewers

      public List<SimuAgent> getViewers()
      Retrieves the list of viewer agents associated with the simulation.
      Returns:
      a list of SimuAgent viewers.

    • onSimulationStart

      public void onSimulationStart()
      Method to be called on simulation startup. This can be overridden by subclasses to perform initialization tasks. 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.

      More precisely, this call is done on the engine agents, by the launcher, in the following order: (1) the Scheduler, (2) the SimuModel, (3) the SimuEnvironment, and (4) on all the Viewer agents.

      It is worth noting that, by default, this method is not called on the simulated agents, because the default implementation of SimuLauncher does not have access to them. Still it is easy to specialize the launcher to achieve this, or by using a Probe in any of the engine agents.

      So, it can be overridden to perform any action that could be useful before the simulation starts.

      By default, this method does nothing, except for the SimuLauncher which will start the simulation.

    • requestSimuRole

      @Deprecated(since="6.0.1", forRemoval=true) public Agent.ReturnCode requestSimuRole(String group, String role)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Requests a role within the simulation community.

      Deprecated since 6.0.1. It is considered as just overloading the API for no good reason. Use Agent.requestRole(String, String, String) or playRole(String)} instead.

      Parameters:
      group - the group within which the role is requested.
      role - the role to be requested.
      Returns:
      the result of the role request as a Agent.ReturnCode.

    • playRole

      public Agent.ReturnCode playRole(String role)
      Plays a role within the model group of the simulation.

      This method is equivalent to calling requestRole(getCommunity(), getModelGroup(), role).

      It is provided as a convenience method for agents that need to play roles within the simulation model.
      Parameters:
      role - the role
      Returns:
      the return code

    • createSimuGroup

      @Deprecated(since="6.0.1", forRemoval=true) public Agent.ReturnCode createSimuGroup(String group)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Creates a simulation group with the specified name in the simulation community.

      Deprecated since 6.0.1. It is considered as just overloading the API for no good reason. Use Agent.createGroup(String, String) instead.

      Parameters:
      group - the name of the group to be created
      Returns:
      a ReturnCode indicating the result of the group creation

    • leaveSimuRole

      @Deprecated(since="6.0.1", forRemoval=true) public Agent.ReturnCode leaveSimuRole(String group, String role)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Leaves a specified role in the given simulation group.

      Deprecated since 6.0.1. It is considered as just overloading the API for no good reason. Use Agent.leaveRole(String, String, String) or leaveRole(String) instead.

      Parameters:
      group - the name of the group from which to leave the role
      role - the name of the role to be left
      Returns:
      a ReturnCode indicating the result of leaving the role

    • leaveRole

      public Agent.ReturnCode leaveRole(String role)
      Leaves a specified role in the model group of the simulation.

      This method is equivalent to calling leaveRole(getCommunity(), getModelGroup(), role).

      Parameters:
      role - the name of the role to be left
      Returns:
      a ReturnCode indicating the result of leaving the role

    • leaveSimuGroup

      @Deprecated(since="6.0.1", forRemoval=true) public Agent.ReturnCode leaveSimuGroup(String group)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Leaves the specified simulation group.

      Deprecated since 6.0.1. It is considered as just overloading the API for no good reason. Use Agent.leaveGroup(String, String) instead.

      Parameters:
      group - the name of the group to be left
      Returns:
      a ReturnCode indicating the result of leaving the group

    • getSimuTimer

      public <T extends SimuTimer<?>> T getSimuTimer()
      Returns the SimuTimer of the current simulation. This is automatically initialized when the agent is associated with an activator for the first time. So it stays null if the agent is not related to a simulation
      Returns:
      the simulationTime of the simulation in which the agent participates
      Throws:
      NullPointerException - if this agent is not part of a simulation

    • getNextEventDate

      public LocalDateTime getNextEventDate() throws ClassCastException
      Method which is used by discrete-event simulation activators for doing fine-grained simulations. By default, this method returns an event which is one second ahead of the current date of the simulation. So, this method can be overridden to fulfill the simulation requirement
      Returns:
      the date of the next event for this agent.
      Throws:
      ClassCastException - if the agent is not part a simulation whose scheduling is based on a DateBasedTimer
      See Also: