Adding Parameters to a Component

In some cases the components will create and add parameters automatically when you edit them; however, in other cases you may want to create parameters and add them to components as you build the model.

Declaring Parameters

In many cases, when you are programmatically configuring components (as opposed to using the GUI), the parameters often must be created ahead of time so that they are available for the component APIs (discussed later) to use (the component GUIs typically do this for you). The main class for representing component parameters and properties is the Variable class, of which there are subclasses for each parameter structure (DtScalarVariable for scalars, DtArrayVariable for arrays, and DtAggregateVariable for aggregates). There are corresponding non-Dt versions of these subclasses (ScalarVariable, ArrayVariable, AggregateVariable) that are available at run time (while the Dt versions are not) that do not allow you to reconfigure the parameter but only interrogate it and set/get the value (where appropriate; see below).

DtScalarVariable scalarVar =
DtModelManager.createScalarVariable("my Param", 
EsiTypes.REAL, Variable.ROLE_PARAMETER, 
Variable.MODE_INPUT, null, null);

Note the following:

  • The datatype is provided using a static constant from the EsiTypes class in the com.engineous.sdk.vars package. This class has many other constants that are useful for building models; it is suggested that you look at the javadocs for this class to be familiar with what is available.

  • The Variable class has many static constants defined for various aspects of the variable, including its role (parameter or property), structure, and mode (input, output, inout, or local).

  • The final two arguments can be used for defining units and limits for the parameter, which are described in more detail below.

Accessing and Setting the Value of a Parameter

The value of a parameter can be accessed or set using the Value object that the parameter holds. Because values inherently make sense only for individual quantities, they are only defined for (Dt)ScalarVariables or for specific elements from an (Dt)ArrayVariable.

Value val = scalarVar.getValueObj();
or
Value val = arrayVar.getValueObj(index);
(There are multiple formats for sending in the indexes.)

Once the Value object is obtained, you can get the value.

double d = val.getAsReal();
(There are methods for other data types as well.) or set the value

val.setValue(doubleVal);
 (There are methods for other data types as well.)

While this example is shown for parameters of type Real (whose value is stored as a double), there are methods for integer (long), string, Boolean, and Object as well. The call you make will depend on the type of parameter you are dealing with, which can be retrieved from the call scalarVar.getType() and compared against the type constants defined in EsiTypes. In general, all SIMULIA-supplied datatypes will allow setting/getting the value using a String and will perform the expected conversion.

Adding Units to a Parameter

In addition to documenting the parameter and knowing what the value refers to, a parameter may have units defined to accommodate unit conversion during execution of the model. Units are defined by publishing them to the Library and can be used by a parameter by referring to the published name of the unit. For detailed information on publishing units, see Publishing the Unit.

scalarVar.setUnitType("com.engineous.unit.length.Meter");

There is a corresponding getUnitType method as well. Typically, you need not do anything with the units for a parameter; Isight will use any existing units for conversion purposes, as noted previously. However, you can obtain the Unit object for the parameter using

Unit unit = scalarVar.getUnit();

Adding Limits to a Parameter

A parameter can have allowed values specified to ensure that the value is set within a certain range or from among certain values at run time. To specify values, define a limit for the variable and configure the limit. There are two types of limits:

  • RangeLimit (for defining lower and/or upper values)

  • DiscreteLimit (for defining a set of allowed values).

    scalarVar.setLimitType(EsiTypes.RANGE_LIMIT);
Limit limit = scalarVar.getarrayofValues();
limit.setLowerBound(double);
limit.setLowerInclusive(true);

or 
scalarVar.setLimitType(EsiTypes.DISCRETE_LIMIT);
Limit limit = scalarVar.getLimit();
limit.setAllowedValues(String[]);
\\(arrayofValues can be provided as String[], double[], and 
Value[]);

To test the value of a parameter against the limit, call the following:

limit.verify(scalarVar.getValueObj());

Creating Mappings (data flow) between Parameters in Different Components

Every component has its own set of parameters. To pass values from one parameter to another, a mapping must be created using a DtDataFlow object. When building a model using the Design Gateway, an automapping capability is used (depending on your preferences) to construct mappings automatically between parameters that match name and structure. When building a model using the API, you must construct these mappings explicitly.

DtDataFlow df = DtModelManager.createDataFlow(fromParameter,
toParameter); 
myTask.addDataFlow(df);

Note: Dataflows are maintained by the parent component for that level of the simulation process flow. Thus, for mappings between parameters in a parent and child component or between two sibling components, the DtDataFlow object must be added to the parent component.

For a large number of parameters this procedure becomes unwieldy. Therefore, a utility class called DtUtils in the com.engineous.sdk.model package provides some useful methods for performing mappings on components provided that you can accept the rules of automapping (same name, same structure, and output-input mode relationship).

DtUtils.autoMapComponents(component1, component2);

You should review some of the other methods available on the DtUtils class to become familiar with the other capabilities it provides.