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.
To know how to save / restore model snapshots from custom experiment, please refer here.
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:
Demo model: Simple Custom Experiment
In the following model the custom experiment implements interaction via Console:
Demo model: Custom Experiment Interacting with Console
In the following model the custom experiment configures and runs optimization without creating the optimization experiment window:
Demo model: Optimization Without UI
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:
Demo model: Calibration from Within Simulation
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
–
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.
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()
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.
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).
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.
Function |
Description |
Engine createEngine() |
Creates engine. |
void run() |
Use createEngine(). |
Function |
Description |
void onError |
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: |
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: |
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. |