Controlling the Model Execution Programmatically

You may need to control your model execution programmatically. For example, you may need to pause the model on some event, e.g. on event expiry and resume its execution when some statechart transition will be taken. AnyLogic offers a rich API capable of solving all tasks concerned with controlling the model execution. 

The table below lists the related functions of the model engine and analogous methods available at each agent.

To call some engine function, write e.g. getEngine().finish() wherever you need in your model.

Alternatively, you can simply call analogous function finishSimulation() from any agent's activity.

Engine function

Agent's function

Short description

Full description

boolean start()

N/A

Starts the model (if it is idle at the moment) and pauses it.

Engine command applicable only in IDLE state (in other states does nothing and returns false). 

Does the following:

1. Sets up the start time of the model execution
2. Creates whatever is needed in the root object - calls root.create();
3. Starts the model (first events get scheduled) - calls root.start();
4. Puts the engine into the PAUSED state.

boolean pause()

boolean pauseSimulation()

Pauses the running model. Puts the engine into PAUSED state and causes the model to terminate after completing the current event execution.

Engine command applicable only in RUNNING state (in other states does nothing and returns false). Puts the engine into PLEASE_WAIT state and then sets a flag that, when tested by the engine, causes it to terminate after completing the current event execution. Further behavior depends on context where this method is called:

  • When this method is called from the model execution thread, from control action code, or from on-click code of a shape, it returns true immediately. Model is paused just after current event execution

  • When this method is called from other locations (e.g. user-defined concurrent thread), it waits for the model execution thread to terminate and returns true.

Note that by the time this method finishes, the engine may be in PAUSED, FINISHED, or ERROR state.

Returns: false if the engine state does not allow pausing

boolean run()

boolean runSimulation()

If the model is paused at the moment, runs the model.  Puts the engine into RUNNING state and then starts the model execution.

Engine command applicable only in PAUSED state (in other states does nothing and returns false). Puts the engine into RUNNING state and then starts the model execution in a separate thread. The execution may discontinue due to the one of the following reasons

- there are no more events to execute (state -> FINISHED)

- stopTime is reached (state -> FINISHED)

- pause() was called (state -> PAUSED)

- top level agent has been destroyed (state -> FINISHED)

- exception occurred during event execution or agent destruction (state -> ERROR)

This method should never be called from the model execution thread!

Please note that by the time this method finishes, then engine may already be in PAUSED, FINISHED, or ERROR state.

Returns: false if the engine state does not allow running

boolean stop()

boolean stopSimulation()

Terminates the model execution, destroys the model and forgets it. Then puts the engine into IDLE state and returns true.

Engine command applicable only in any non-IDLE state (in IDLE state does nothing and returns false). If the state is RUNNING, sets a flag that, when tested by the model execution thread, causes it to terminate. Further behavior depends on context where this method is called:

When this method is called from the model execution thread, or from control action code, or from on-click code of a shape, it returns true immediately, leaving the model in PLEASE_WAIT state. Model is stopped and destroyed some time later (After Simulation Run code of an experiment or On Destroy code of the top level agent may be used to handle this moment)

It is more recommended to use finish() method in such situations

When this method is called from other locations (e.g. user-defined concurrent thread), it waits for the model execution thread to terminate and then destroys the model (calls root.onDestroy()) and forgets it. Then puts the engine into IDLE state and returns true.

boolean finish()

boolean finishSimulation()

Finishes currently running or paused model. Unlike stop() method, it does not destroy the model, so you can examine and analyze its state.

Engine command applicable only in RUNNING or PAUSED state (in other states does nothing and returns false). Sets a flag that, when tested by the engine, causes it to finish after completing the current event execution. Further behavior depends on context where this method is called:

  • When this method is called from the model execution thread, control action code, or from on-click code of a shape, it returns true immediately. Model is finished just after current event execution (After Simulation Run code of an experiment may be used to handle this moment)

  • When this method is called from other locations (e.g. user-defined concurrent thread), it waits for the model execution thread to terminate and returns true.

Note that by the time this method finishes, the engine may be in FINISHED, or ERROR state.

Returns: false if the engine state does not allow pausing

boolean runFast()

N/A

Runs the model in the fastest possible way. The run is done in virtual time mode regardless any settings. 

Runs the model in the fastest possible way in the same (calling) thread. The run is done in virtual time mode regardless any settings. The method finishes in one of the following cases:

- illegal engine state when it is called (returns false, in all other cases - returns true)

- there are no more events/equations to execute (state -> FINISHED)

- stopTime is reached (state -> FINISHED)

- pause() was called (state -> PAUSED)

- finish() was called (state -> FINISHED)

- top level agent has been destroyed (state -> FINISHED)

- exception occurred during model execution (state -> ERROR)

The model is locked for both write and read during the entire run, so you should not try to display presentation of the agents, or execute any concurrent actions that may access the model.

Returns: false if the engine state does not allow running

boolean step()

N/A

Makes at most one discrete step of the model (can be done from the PAUSED state only). 

Makes at most one discrete step of the model (can be done from the PAUSED state only). Finishes in either FINISHED, ERROR or PAUSED state.

This method should never be called from the model execution thread!

Returns: false if the engine state does not allow for making a step

int getState()

N/A

Returns the current state of the engine (IDLE, PAUSED, RUNNING, STEP, FINISHED, or ERROR). 

Returns the current state of the engine:

IDLE - no model is set for execution, doing nothing

PAUSED - model is set and have started, ready to run or make a step

RUNNING - in the loop of model execution invoked by run() or runFast()

FINISHED - the model execution is finished OK, but the model is not yet destroyed

ERROR - the model execution is finished with error, the model is not yet destroyed

PLEASE_WAIT - in the process of executing a non-interruptable command like pause(), step() or stop()

The state is however not guaranteed as may be modified concurrently.