Parameter

Agent may have parameters. Parameters are frequently used for representing some characteristics of the modeled object. They are helpful when object instances have the same behavior described in agent type, but differ in some parameter values. There is a clear difference between variables and parameters. A variable represents a model state, and may change during simulation. A parameter is commonly used to describe objects statically. A parameter is normally a constant in a single simulation, and is changed only when you need to adjust your model behavior.

Top-level agent parameters can serve as inputs for the models that are exported to AnyLogic Cloud. Model inputs are set up using the Run Configuration editor. The Label defined for the parameter in the Value editor section will be used as a default name of the corresponding input. If a certain Control type is set for the parameter in the Value editor section, it will be used as the default control type for the corresponding input in the cloud model version. Note that you can use only Static parameters (defined in the Advanced section) of the int, double, boolean and string value types for the exporting model inputs. If a parameter is set up to retrieve its value by calling a function, this value will be retrieved prior to exporting and it will be exported with the model as the fixed value.

Units

If your parameter defines one of the following: time, speed, length, acceleration, rate, or area, you can specify this explicitly and define units for this parameter in a handy way.

For example, the following units are supported for Time and Speed:

• Time: milliseconds, seconds, minutes, hours, days, weeks, months, years.
• Speed: meters per second, kilometers per hour, feet per second, feet per minute, miles per hour, knots.

Parameter types

Alike other simulation tools AnyLogic supports parameters of primitive types: double, int, boolean. But only AnyLogic gives you infinite possibilities in parameterizing your objects by supporting parameters of any Java classes.

You can define parameters of common Java classes – e.g., a parameter of String class to represent character strings. You can create a parameter of the Object class (the base class for all Java classes) and assign an instance of any Java class to this parameter. Later on you will need to check the actual type of this parameter and cast it explicitly to the original Java class. For details on Java classes, see Java SDK documentation.

Since all AnyLogic objects are instances of Java classes, you can define parameters of these classes and thus use AnyLogic objects as parameters.

So long as parameters are frequently used in system dynamics models, and sometimes these models operate with arrays, AnyLogic supports creating parameters of array type.

Creating a parameter

1. Drag the Parameter element from the Agent palette onto the graphical diagram.
2. Go to the Properties view.
3. Type the name of the parameter in the Name edit box. The name is used to identify and access the parameter.
4. If your parameter defines one of the following: time, speed, length, acceleration, rate, or area, specify this explicitly by choosing the corresponding Type for this parameter. Then choose the Unit from the drop-down list below.
5. Otherwise, specify the Java type for the parameter. You can choose one of the most-used types (int, double, boolean, String) using the corresponding option from the Type buttons group. If you need to define a parameter of some other Java class, choose Other option and type the required class name in the edit box to the right.
6. Specify the parameter's default value in the Default value edit box. The value of the parameter can be changed afterwards during the model simulation using the set_parameterName(new value) function. If default value is not specified, Java rules apply, for example a parameter of type double is set to 0, a parameter of type boolean is false.
7. If you want to make the parameter a hyperarray used in system dynamics, select the System dynamics array check box, then go to the Dimensions table and select the dimensions of this array. To define default values of array elements, click the Edit... button and initialize the array as described here.

Properties

General properties

Name – The name of the parameter. The name is used to identify and access the parameter.

Show name – If selected, the name of the parameter is displayed on a presentation diagram.

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

Visible - If selected, the event is visible at runtime.

Type – [Visible if the parameter is Static or Dynamic] The type of the parameter. Choose a measurable type (Time, Speed, Length, etc.) or one of the Java primitive types (int, double, boolean, String) using the corresponding option from the Type list. If you need a parameter of some other Java class, choose the Other option and type the required class name in the edit box to the right.
If System dynamics array is enabled, type is automatically defined as HyperArray.

Unit – [Visible if the Type parameter is set to one of the measurable types (Time, Speed, Length, etc.)] The measurement units of the parameter value. The set of available units depends on the selected Type. For example, if Length is set as the parameter type, length units (inch, mile, meter, etc.) will be available for selection.

Default value – You can define the default value for the parameter here. The value of the parameter can be changed afterwards during the model simulation. If default value is not specified, Java rules apply, for example, a parameter of type double is set to 0, a parameter of type boolean is set to false.
If System dynamics array is enabled, the button Edit is available for editing array values.

System dynamics array – [Visible if the parameter is not Action] If selected, the parameter is of array type. Properties for array parameters look slightly different.

Dimensions – [Visible if System dynamics array is enabled] The list of dimensions that will act as dimensions of this array variable. Click the "plus" button to add a dimension. The dialog window Edit dimensions will appear. You can select a dimension from the list of all available dimensions defined in this model or create a new dimension for this goal. Use the "cross" button to remove a dimension from the list of Dimensions.
Please refer to the Defining an array variable section for details.

Parameter arguments – [Visible if the parameter is Dynamic or Action] Here you can define some optional arguments for your dynamic or action parameter to enable passing some additional input data necessary for parameter calculations.
Each row of the table specifies one particular argument. To remove argument, select the corresponding row in the table and click the "cross" button. Rearrange arguments in the table using "arrow" buttons.

Default action - [Visible if the parameter is Action] - You can define the default action for the parameter here.

Value editor

Label – The label of the parameter, which will be shown instead of parameter name. If this agent type is used as a root class in some experiments, this label is also used in Default UIs that AnyLogic generates for those experiments.

Control type – Choose the control type that enables the user to specify a parameter value.

Text – If selected, the user is enabled to specify actual parameter value using a text field.

Check Button – If selected, the user is enabled to specify actual parameter value using a check box.

Radio Button – If selected, the user is enabled to specify actual parameter value using a group of radio buttons. Radio buttons (option names and values assigned to these choices) are specified in the table.

Combo – If selected, the user is enabled to specify actual parameter value using a combo box. Combo box items (item names and values assigned to these choices) are specified in the table.

Editable Combo – If selected, the user is enabled to specify actual parameter value using editable combo box. Combo box items (item names and values assigned to these choices) are specified in the table. In the cloud, Editable Combo acts as a Combo (see above).

Slider – If selected, the user is enabled to specify actual parameter value using a slider. Minimum and maximum values of the slider are defined using the edit boxes min and max.

Rotation editor – If selected, the user is enabled to specify actual parameter value using a rotation editor.

Control type includes the following options when System dynamics array is enabled:

Hyper array editor – If selected, the user is enabled to specify values of this parameter-array using a hyper array editor.

Element chooser – If selected, the user is enabled to specify actual parameter value using the element chooser control.

Hide conditions – The list of conditions defining when the actual parameter is hidden. Specify the Parameter, the Condition and Value.

Advanced

Static – If selected, the parameter is static, i.e. it is evaluated once, but may be changed during the model execution. In the field of a static parameter you can define its value (that can be casted to the type of the parameter).

Dynamic – If selected, the parameter is dynamic, i.e. its value is recalculated each time you assess the parameter and it acts as a function. Dynamic parameters are accessed using function-call notation: myParameter(), not myParameter

Action – Dynamically executed code piece, evaluated each time a certain event occurs at the object.

System dynamics units – If selected, you will be able to specify units of measurements for this parameter as system dynamics modelers do. Say, you define people as the SD units for this parameter in the edit box to the right of this option. Having specified units for all system dynamics elements of your model, you may perform unit checking to find out dimension inconsistencies in your model.

Save in snapshot – [Visible if the parameter is Static] If selected, the parameter will be saved in the model snapshot.

On change – [Visible if the parameter is Static] The code that will be executed on every parameter change. Please note that this code will be called only on set_parameterName() function calls (simple assignment like parameter=5; will not invoke the change handler). And the handler is also not executed in the case set_parameterName() function assigns the value equal to the actual parameter value.
Here in the code you can use the variable oldValue that stores the old value of the parameter (the value this parameter had before this particular change of the value).

Defining a reaction on parameter change

If some upper-level agent contains other agents, its parameters can be linked to parameters of these agents that use it as the environment. In this case, parameter changes are propagated down the agent tree along the parameter dependencies. This mechanism is called parameter propagation. Propagate values of parameters down the agent tree in the following cases:

• You need to change parameters of several agents (perhaps of different types). You can do this by creating a single parameter of the top-level agent and propagating its value to several parameters you need to change.
• You need to perform an experiment varying, optimizing, or calibrating some parameters of an agent which is not a top-level agent of the experiment. In this case, you also need parameter propagation since you can optimize the model by changing only its top-level agent's parameters.

You can define a parameter change handler and specify any actions you want to be performed on parameter change. For instance, you can store the changed parameter value in the database or send a notification message as a reaction on the parameter change.

1. Select the parameter in the graphical editor or in the Projects view.
2. In the Advanced section of the Properties view, define the code that needs to be executed on parameter change in the On change field. Please note that this code will be called only on set_<parametername>() function calls (a simple assignment like parameter=5; will not invoke the change handler). The handler is also not executed in the case the set_<parametername>() function assigns the value that is equal to the current parameter value.
   In the code you can use the oldValue variable that stores the old value of the parameter (the value this parameter had before this particular change of the value).
   

Related topics

Viewing parameters at runtime

Modifying parameters at runtime