Controlling the model execution

Controlling the model execution from code

When running an AnyLogic model, you can control the model execution using the control panel, displayed at the bottom of the AnyLogic model window.

The control panel contains buttons for controlling the execution of the launched model:

Button	Command	Description
	Run	[Visible only if the model is not running currently] Runs the model from its current state. The model will be run until you manually stop it by clicking the Pause or Stop button (or until something in the model pauses or stops its execution). You can either run the model until the specified moment of model time, or for a specified period of model time starting from the current moment. See Running the model until a certain date or for a certain time interval for details.
	Pause	[Visible only if the model is running currently] Pauses the running model. You can resume the paused simulation any time. You can pause the model at the specified moment of model time, see Running the model until a certain date or for a certain time interval for details.
	Stop	Terminates the model run.

Run AnyLogic model window: The Run button control becomes disabled when there is no activity in the model. This indicates that your model has completed its work.

You can enable or disable these buttons and check their state (enabled / disabled) from code during the model runtime.

Controlling the model execution from code

You may need to programmatically control your model execution. For example, you may need to pause the model on some event, such as event expiration, and resume its execution when a statechart transition occurs. AnyLogic provides a rich API capable of solving all tasks related to controlling the model execution.

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

To call an engine function, write, for example, getEngine().finish() wherever you need it in your model.

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

Engine function	Agent’s function	Short description	Full description
boolean start()	N/A	Starts the model (if it is currently idle) and pauses it.	The engine command applicable only in IDLE state (does nothing and returns false in other states). Does the following: Sets up the start time of the model execution. Creates whatever is needed in the root object — calls root.create();. Starts the model (first events are scheduled) — calls root.start();. Puts the engine in 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.	The engine command applicable only in the RUNNING state (does nothing and returns false in other states). Puts the engine in the 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 the context where this function is called: If this function is called from the model execution thread, from control action code, or from on-click code of a shape, it returns true immediately. The model is paused immediately after the current event is executed. If this function is called from other locations (for example, a user-defined concurrent thread), it waits for the model execution thread to terminate and returns true. By the time this function finishes, the engine may be in the 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 the RUNNING state and then starts the model execution.	The engine command applicable only in the PAUSED state (in other states, does nothing and returns false). Puts the engine into the 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) the top-level agent has been destroyed (state -> FINISHED) an exception occurred during the event execution or the agent destruction (state -> ERROR) This function should never be called from the model execution thread! By the time this function finishes, the engine may already be in the 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 about it. Then puts the engine into the IDLE state and returns true.	The engine command applicable only in any non-IDLE state (in the 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 the context where this function is called: When this function 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 the PLEASE_WAIT state. The model is stopped and destroyed some time later (the 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 the finish() function in such situations. When this function is called from other locations (for example, a user-defined concurrent thread), it waits for the model execution thread to terminate, then destroys the model (calls root.onDestroy()) and forgets it. After that, it puts the engine into the IDLE state and returns true.
boolean finish()	boolean finishSimulation()	Finishes the currently running or paused model. Unlike the stop() function, it does not destroy the model, so you can examine and analyze its state.	The engine command applicable only in the 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 the context where this function is called: When this function is called from the model execution thread, control action code, or from on-click code of a shape, it returns true immediately. The model is finished just after the current event is executed (the After Simulation Run code of an experiment may be used to handle this moment). When this function is called from other locations (for example, a user-defined concurrent thread), it waits for the model execution thread to terminate and returns true. By the time this function finishes, the engine may be in the 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 the virtual time mode regardless any settings.	Runs the model in the fastest possible way in the same (calling) thread. The run is done in the virtual time mode regardless any settings. The function finishes in one of the following cases: an 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) the stop time is reached (state -> FINISHED) pause() was called (state -> PAUSED) finish() was called (state -> FINISHED) the top-level agent has been destroyed (state -> FINISHED) an exception occurred during the model execution (state -> ERROR) The model is locked for both write and read during the entire run, so you should not try to display the agent presentation, 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 the FINISHED, ERROR or PAUSED state. This function should never be called from the model execution thread! Returns false if the engine state does not allow for making a step.
Engine.State getState()	N/A	Returns the current state of the engine (IDLE, PAUSED, RUNNING, FINISHED, ERROR, or PLEASE_WAIT).	Returns the current state of the engine: IDLE — no model is set for execution, doing nothing. PAUSED — the model is set and have started, ready to run or make a step. RUNNING — in the model execution loop invoked by run() or runFast(). FINISHED — the model execution has finished OK, but the model is not yet destroyed. ERROR — the model execution has finished with an error, the model is not yet destroyed. PLEASE_WAIT — in the process of executing an uninterruptible command like pause(), step(), or stop(). However, there is no guarantee that this state will always be the case, as changes can be made at any time.
boolean getRealTimeMode()	N/A	Returns the current model execution mode.	Returns true if the current execution mode is real-time, false if virtual-time.
void setRealTimeMode(boolean on)	N/A	Sets the virtual or real time execution mode.	Sets the virtual or real time execution mode. In the virtual time mode the model is executed as fast as possible. In the real time mode, the engine tries to maintain the given scale between the model time and real time. on — true means that the model execution is scaled to the real time.
double getRealTimeScale()	N/A	Returns the currently set real time scale of the model execution.	Returns the currently set real time scale of the model execution, that is, the number of model time units to be simulated per real second. The actual scale will depend on factors such as simulation performance, applications running in parallel, and so on. This scale only has effect in the real time execution mode.
void setRealTimeScale(double scale)	N/A	Sets the desired real time scale of model execution.	Sets the desired real time scale of model execution, that is, the number of model time units to be simulated per real second. The actual scale will depend on factors such as simulation performance, applications running in parallel, and so on. This scale only has effect in the real time execution mode. scale — the new real time scale.

How can we improve this article?