Simulation Experiment

When a new model is created, one simulation experiment, called Simulation, is automatically created. You can create your own experiments and set up any simulation settings you like. 

 To create a simulation experiment
  1. In the Projects view, right-click (Mac OS: Ctrl+click) the model you are working with and choose New >  Experiment from the popup menu.
    The New Experiment dialog box is displayed.
  1. Choose  Simulation in the Experiment type list.
  2. Type the name of the experiment in the Name edit box.
  3. Select the agent type for the experiment from the Top-level agent drop-down list.
  4. If you want to apply model time settings from another experiment, leave the Copy model time settings from check box selected and choose the experiment in the drop-down list to the right.
  5. Click Finish.

Properties

General

Name – The name of the experiment.
 Since AnyLogic generates a Java class for each experiment, please follow Java naming guidelines and start the name with an uppercase letter. 

Ignore – If selected, the experiment is excluded from the model.

Top-level agent – Using the drop-down list, choose the top-level agent type for the experiment. The agent of this type will play a role of a root for the hierarchical tree of agents in your model.

Maximum available memory – The maximum size of Java heap allocated for the model.

Parameters

Parameters – Here the user can define actual values of parameters of the top-level agent. 

Paste from clipboard – Use this button to paste parameter values from Clipboard to the fields above (the values should be already copied and stored to the Clipboard at the moment).

Model time

Execution mode – Choose the execution mode here:

Virtual time (as fast as possible) – The model runs at its maximum speed and no mapping is made between model time and real time. This time mode is useful when you need to simulate your model for a long period of time.

Real time with scale – In this mode you specify how many model time units one second takes. It is frequently needed when you want your presentation to appear as in real life.

Stop – Defines, whether the model will Stop at specified timeStop at specified date, or it will Never stop. In the first two cases, the stop time is specified using the Stop time/Stop date controls.

Start time – The initial time for the simulation time horizon.

Start date – The initial calendar date for the simulation time horizon.

Stop time – [Enabled if Stop is set to Stop at specified time] The final time for the simulation time horizon (the number of model time units for model to run before it will be stopped).

Stop date – [Enabled if Stop is set to Stop at specified date] The initial calendar date for the simulation time horizon.

Randomness

Random number generator –  Here you specify, whether you want to initialize random number generator for this model randomly or with some fixed seed. This makes sense for stochastic models. Stochastic models require a random seed value for the pseudorandom number generator. In this case model runs cannot be reproduced since the model random number generator is initialized with different values for each model run. Specifying the fixed seed value, you initialize the model random number generator with the same value for each model run, thus the model runs are reproducible. Moreover, here you can substitute AnyLogic default RNG with your own RNG.

Random seed (unique simulation runs) – If selected, the seed value of the random number generator is random. In this case random number generator is initialized with the same value for each model run, and the model runs are unique (non-reproducible).

Fixed seed (reproducible simulation runs) – If selected, the seed value of the random number generator is fixed (specify it in the Seed value field). In this case random number generator is initialized with the same value for each model run, and the model runs are reproducible.

Custom generator (subclass of Random) – If for any reason you are not satisfied with the quality of the default random number generator Random, you can substitute it with your own one. Just prepare your custom RNG (it should be a subclass of the Java class Random, e.g. MyRandom), choose this particular option and type the expression returning an instance of your RNG in the field on the right, for example: new MyRandom() or new MyRandom( 1234 ) You can find more information here.

Selection mode for simultaneous events – Here you can choose the order of execution for simultaneous events (that occur at the same moment of model time). Choose from:

Refer to this section for details on FIFO and LIFO modes.

Window

Window properties define the appearance of the presentation window that will be shown when the user starts the experiment. Note that the size of the experiment window is defined using the model frame and applies to all experiments and agent types of the model.

Title – The title of the presentation window.

Enable zoom and panning – If selected, the user will be allowed to pan and zoom the presentation window.

Maximized size – If selected, the presentation window will be maximized on model launch.

Close confirmation – If selected, the dialog box asking for confirmation will be shown on closing the model window. This will prevent the user from closing the window by occasional clicking the window's close button.

Show Toolbar sections properties section defines, what sections of the toolbar of the presentation window are visible. To make some toolbar section visible, just select the corresponding check box.

Show Statusbar sections properties section defines, what sections of the status bar of the presentation window are visible. To make some status bar section visible, just select the corresponding check box.

Java actions

Initial experiment setup – Experiment initialization code. It is executed when the experiment is created (and its UI is created).

Before each experiment run – Here you specify the code you want to be executed before each experiment run.  

Before simulation run – The code executed before simulation run. This code is run on setup of the model. At this moment the top-level agent of the model is already created, but the model is not started yet. You may perform here some actions with elements of the top-level agent, e.g assign actual parameter values here.

After simulation run – The code executed after simulation run. This code is executed when simulation engine finishes the model execution (Engine.finished() function is called). This code is not executed when you stop your model by clicking the Terminate execution button.

Advanced Java

Imports sectionimport statements needed for correct compilation of the experiment class' code. When Java code is generated, these statements are inserted before definition of the Java class.

Additional class code – Arbitrary member variables, nested classes, constants and methods are defined here. This code will be inserted into the experiment class definition. You can access these class data members anywhere within this experiment. 

Java machine arguments – Specify here Java machine arguments you want to apply on launching your model. You can find the detailed information on possible arguments at Java Sun Microsystems web site: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/java.html

Command-line arguments – Here you can specify command line arguments you want to pass to your model. You can get the values of passed argument values in the experiment's Additional class code using the String[] getCommandLineArguments() method.

Advanced
Enable anti-aliasing – If selected, anti-aliasing is performed. Anti-aliasing is a process of smoothing the drawing of points or lines that would otherwise appear jagged. However, note that more time is spent on rendering the presentation with the anti-aliasing set.

Enable enhanced model elements animation – If selected, enhanced animation will be shown for system dynamics flows and stocks at the model runtime.

Enable adaptive frame management – Choose, whether you want to specify adaptive frame rate, or explicitly defined fixed update rate in frames per second. Adaptive update rate will be recalculated during the model simulation to fix up the specified ratio between simulation speed and presentation smoothness.

CPU ratio (Presentation:Simulation) – [Enabled if Enable adaptive frame management is selected] If the adaptive frame management is turned on, specify here the ratio between simulation speed and presentation smoothness. 
However, presentation rendering takes longer, and frequent presentation update will slow the model simulation. So, choose between smooth presentation and fast simulation and set up the presentation update rate according to your needs.

Frames per second – [Enabled if Enable adaptive frame management is not selected] If the adaptive frame management is turned off, specify here the presentation update rate (in frames per second). The greater update rate you specify, the smoother presentation will appear. However, presentation rendering takes longer, and frequent presentation update will slow the model simulation. So, choose between smooth presentation and fast simulation and set up the presentation update rate according to your needs.

Load top-level agent from snapshot – If selected, the experiment will load the model state from the snapshot file specified using the control to the right. The experiment will be started from the time when the model state was saved. 

Functions

Controlling execution

Function

Description

void run()

Starts the experiment execution from the current state.

If the model does not exist yet, the function resets the experiment, creates and starts the model.

void pause()

Pauses the experiment execution.

void step()

Performs one step of experiment execution.

If the model does not exist yet, the function resets the experiment, creates and starts the model.

void stop()

Terminates the experiment execution.

void finish()

Sets a flag that, when tested by the engine, causes it to finish after completing the current event execution.

void close()

This method returns immediately and performs the following actions in a separate thread:

  • Stops experiment if it is not stopped,
  • Destroys the model,
  • Closes the experiment window (only if model is started in the application mode).

Experiment.State getState()

Returns the current state of the experiment: IDLE, PAUSED, RUNNING, FINISHED, ERROR, or PLEASE_WAIT.

double getRunTimeSeconds()

Returns the duration of the experiment execution in seconds, excluding pause times.

int getRunCount()

Returns the number of the current simulation run, i.e., the number of times the model was destroyed.

double getProgress()

Returns the progress of the experiment: a number between 0 and 1 depending on what part of experiment is completed, or -1 if not known.

Accessing the model

Function

Description

Engine getEngine()

Returns the engine executing the model. To access the model's top-level agent (typically, Main), call getEngine().getRoot();

Presentation getPresentation()

Returns the presentation object of the model, or null if there is none.

Restoring the model state from snapshot

Function

Description

void setLoadRootFromSnapshot(
String snapshotFileName)

Tells the experiment to load the top-level agent from AnyLogic snapshot file. This method is only available in AnyLogic Professional.

Parameter:
snapshotFileName - the name of the AnyLogic snapshot file, for example:
"C:\\My Model.als"

boolean isLoadRootFromSnapshot()

Returns true if the experiment is configured to start the simulation from the state loaded from the snapshot file; returns false otherwise.

String getSnapshotFileName()

Returns the name of the snapshot file, from which this experiment is configured to start the simulation.

Error handling

Function

Description

RuntimeException 
error(Throwable cause, String errorText)

Signals an error during the model run by throwing a RuntimeException with errorText preceded by the agent full name. 

This method never returns, it throws runtime exception by itself. The return type is defined for the cases when you would like to use the following form of call:
throw error("my message")
;

Parameters:
cause - the cause (which will be saved for more detailed message), may be null.
errorText - the text describing the error that will be displayed.

RuntimeException 
errorInModel(Throwable cause, String errorText)

Signals a model logic error during the model run by throwing a ModelException with specified error text preceded by the agent full name.

This method never returns, it throws runtime exception by itself. The return type is defined for the cases when you would like to use the following form of call:
throw errorInModel("my message")
;

This method differs from error() in the way of displaying error message: model logic errors are 'softer' than other errors, they use to happen in the models and signal the modeler that model might need some parameters adjustments.

Examples are 'agent was unable to leave flowchart block because subsequent block was busy', 'insufficient capacity of pallet rack' etc.

Parameters:
cause - the cause (which will be saved for more detailed message), may be null.
errorText - the text describing the error that will be displayed.

public void onError(Throwable error)

This method may be overridden to perform custom handling of the errors that occurred during the model execution (i.e., errors in the action code of events, dynamic events, transitions, entry/exit codes of states, formulas, etc.). 

By default, this method does nothing as its definition is empty. To override it, you can add a function to the experiment, name it onError and define a single argument of the java.lang.Throwable for it.

Parameter:
error - an error which has occurred during event execution.

Command-line arguments

Function

Description

String[] getCommandLineArguments()

Returns an array of Command-line arguments passed to this experiment on model start. Never returns null: if no arguments are passed, an empty array is returned.

You can call this function in the experiment's Additional class code.