Custom Experiment

Custom experiment runs experiment with custom scenario entirely written by user.

Custom experiment gives you maximum flexibility with setting parameters, managing simulation runs, making decisions. It simply gives you a code field where you can do all that (and a lot more) by using a rich Java API of AnyLogic engine (methods like run(), stop(), etc.). Refer to the corresponding section for details.

This experiment has no built-in graphical interface as well as no predefined behavior.

Creating a custom experiment

1. In the Projects view, right-click (Mac OS: Ctrl click) the model item and choose New > Experiment from the popup menu. The New Experiment dialog box is displayed.

2. Choose Custom option in the Experiment Type list.
3. Type the experiment name in the Name edit box.
4. Choose the top-level agent of the experiment from the Top-level agent drop-down list.
5. 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.
   
6. Click Next to go to the next page of the wizard.
7. Here you specify whether you want to load root object of this experiment from a snapshot. If so, select the checkbox on this page and choose a snapshot using the Browse button.
8. Click Finish.

To know how to save / restore model snapshots from custom experiment, please refer here.

Examples

Here are the links to demo models with custom experiments. Please examine the custom experiment's code in its Code properties section to understand the scenario implementation.

The following model is the simplest custom experiment demo. The experiment creates the engine, model, configures and runs the simulation, and outputs the result in Console:

In the following model the custom experiment implements interaction via Console:

In the following model the custom experiment configures and runs optimization without creating the optimization experiment window:

In the following model the custom experiment is used to perform the calibration from the running simulation experiment. Run the simulation, and you will see the button starting the custom experiment performing the calibration:

Custom experiment properties

General

Name – The name of the experiment.
Since AnyLogic generates 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.

Code

Code – Here you can type the code for this custom experiment. By default you can find here code that was automatically generated on the experiment creation. This code creates simulation engine, sets experiment's stop time, creates top-level agent, starts the experiment in the fast mode and then stops it. You can study this very simple code to get some ideas on how to extend it further to achieve the required custom behavior.

Application options

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

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 Documentation web site: http://docs.oracle.com/javase/8/docs/technotes/tools/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 method String[] getCommandLineArguments()

Advanced Java

Imports section – import 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.

Defining custom experiment logic with Java code

Custom experiment may be executed from another experiment - in this case the latter should be passed as an argument to the constructor of the custom experiment. Experiments are executed by calling run() function.

A sample action code of some Main agent which runs custom experiment:

// Create custom experiment, pass currently running experiment
// as an argument to the constructor

MyCustomExperiment e = new MyCustomExperiment(getExperiment());

// setup some custom fields defined in the
// additional class code of MyCustomExperiment:

e.day = getDayOfWeek();

// run experiment

e.run();

// collect results from custom fields defined in the
// additional class code of MyCustomExperiment:

traceln( "result: " e.myResult );

(In the example above, custom experiment has Code (which is actually inside the run() function) which gets field day (defined in the additional class code), uses it in the experiment and then sets some result value to the field myResult).

Usage notes

Use createEngine() to create new Engine instance. Use Engine.runFast() function to run experiment in the fastest possible mode.

Don't forget to setup stop time or stop date to the engine before.

Use ExperimentOptimization.createOptimization(Engine) to create new OptQuest Optimization instance.

The simplest example of run() code:

// Create Engine, initialize random number generator:

Engine engine = createEngine();

// Set stop time

engine.setStopTime( 100 );

// Create new top-level agent:

Main root = new Main(engine, null, null);

// Setup parameters of top-level agent here

root.myParameter = 10;

// Prepare Engine for simulation:

engine.start( root );

// Start simulation in fast mode:

engine.runFast();

// Obtain results of simulation here

traceln( root.myResult );

// Destroy the model:

engine.stop();

You can use the following functions to control the experiment. Custom experiment uses the API of AnyLogic engine.

Creating experiment

Function	Description
Engine createEngine()	Creates engine.
void run()	Use createEngine().

Error handling

Function	Description
void onError (Throwable error)	This function 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 function does nothing as its definition is empty. To override it, you can define the function, 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.
void onError (Throwable error, Agent root)	Similar to onError(Throwable error) function except that it provides one more argument to access the top-level (root) agent of the model. Parameters: error - an error which has occurred during event execution. root - the top-level (root) agent of the model. Useful for experiments with multiple runs executed in parallel. May be null in some cases (e.g. on errors during top-level agent creation).

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. This function is designed for usage inside the run() function.