Extended Variables

Extended variables provide a set of extension properties/methods that not oly help create powerful digital twin simulations but can also be used to customize and beautify its generated reports.

Note

All extended variables (except custom ones): Output, Constant, Simulated, X-Axis are automatically and dynamically created/updated within the custom code ExtendedVariables region everytime code gets Reset or Updated.

Properties

Extended Variable	Type											Scope
	Xaxis		Output (State)		Constant		Simulated		Custom			Initialize		EvaluateStep
Property	Read	Write	Read	Write	Read	Write	Read	Write	Read	Write		Read	Write	Read	Write
VariableName			✓		✓		✓		✓			✓		✓
DisplayName	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓			✓	✓
Tooltip	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓			✓	✓
DefaultHexColor			✓	✓	✓	✓	✓	✓	✓	✓			✓	✓
InitialValue			✓ *2		*1		✓ *2	✓	✓ *2	✓			✓	✓
PreviousValue	✓		✓ *2		*1		✓ *2		✓ *2					✓
Value	✓				✓			✓ *3		✓ *3				✓	✓
SimMin	✓	✓ *3			✓				✓	✓			✓	✓
SimRes	✓	✓ *3			✓				✓	✓			✓	✓
SimMax	✓	✓ *3			✓				✓	✓			✓	✓
IsState	✓		✓		✓		✓		✓			✓		✓
IsConstant	✓		✓		✓		✓		✓			✓		✓
IsSimulated	✓		✓		✓		✓		✓			✓		✓
IsCustom	✓		✓		✓		✓		✓			✓		✓
IsXAxis	✓		✓		✓		✓		✓			✓		✓
Extended Variable	Type											Scope
Method	Xaxis		Output (State)		Constant		Simulated		Custom			Initialize		EvaluateStep
ForceSetInitialValue(value)			✓									✓

*1 It is a constant. Use ‘Value’ instead

*2 Value provided/available only after first iteration of ‘EvaluateStep’

*3 It is expected/mandatory to be provided/set

VariableName

Is the name of the variable itself, as provided/show on the Outputs and Constant/Simulated variables panels setup.

Important

Cannot be null, empty, contain white spaces or any ileal/invalid C# variable name character.

Example

string CDWgLVarName = this.CDWgL.VariableName;

DisplayName

UI friendly display name to show on the report section.

Note

If not provided, DisplayName, takes VariableName value.

Example

this.CDWgL.DisplayName = "CDW (g/L)";

Tooltip

UI friendly tooltip (message which appears when a cursor is positioned over) within the Report section plots.

Note

If not provided, Tooltip, takes DisplayName value.

Example

this.CDWgL.Tooltip = "Cell dry weight (g/L)";

DefaultHexColor

UI friendly variable assigned default color for report section.

Note

If not provided, an auto generated color will be set.

Tip

Color Picker tools can be found on the internet where one can visually pick a color and a hex color code is provided. That code can then be copy/pasted as a value for DefaultHexColor.

this.CDWgL.DefaultHexColor = "#ff7f0e";

InitialValue

Provides initial value of the variable (e.g., if a time series, at time t0).

Important

This property is set automatically by the toolbox. It should only be called from within the EvaluateStep method, and after first iteration.

Example

if(!this.IsFirstStep)
{
    ... = varName.InitialValue;
}

PreviousValue

Provides value stored when exiting previous EvaluateStep method execution.

Important

This property is set automatically by the toolbox. It should only be called from within the EvaluateStep method, and after first iteration.

Value

Current value of variable.

Error

It is an error to try to read Value from an hybrid model Output variable. Value for this type of variables is automatically calculated by the toolbox and assigned after exiting EvaluateStep method. Therefore, for Output variables PreviousValue must be used when needed.

Important

It is expected/mandatory that Simulated and Custom variables provide the variable value within the EvaluateStep method (Simulated variables (ti) - Values section). As the name suggests, Simulated means that user is providing the logic on how to simulate those variables and provide a value for it at each call of EvaluateStep.

SimMin

Intended for Constant variables. Indicates start (minimum) value that variable will take along all possible simulations.

SimRes

Intended for Constant variables. Indicates resolution (step) value that variable will move along simulations.

SimMax

Intended for Constant variables. Indicates end (maximum) value that variable will take along all possible simulations.

IsState

Returns True/False depending if variable is of type Output (state variable) or not.

IsConstant

Returns True/False depending if variable is of type Constant or not.

IsSimulated

Returns True/False depending if variable is of type Simulated or not.

IsCustom

Returns True/False depending if variable is of type Custom or not.

IsXAxis

Returns True/False depending if variable is of type XAxis or not.

Methods

ForceSetInitialValue(value)

There might be cases, where Output variables initial value might not be the same for all simulations to perform but dependent on Constant/Simulated variables values.

In that case, providing the Sim. (Init. [u]) value on the Output variables panel does not apply as it will be provided dynamically on runtime while simulations are carried out. Therefore, to properly indicate that value will be overwrites, we can set affected variables Sim. (Init. [u]) to NaN.

To override previous NaN and provide a specific InitialValue, for each Output variable, current method can be used.

Important

Current method must/can only be used in the scope of Initialize method (CustomCodeIni region).

Example

Assume that output variable A does not have a constant initial value value for all posable simulation combinations, but its initial value depends on other process factors such as Constant variables B and C. In that case we can provide a calculated runtime value,

public override void Initialize()
{ 
    #region CustomCodeIni
    double calculatedIniValA = this.B.Value / this.C.Value;
    ...
    this.A.ForceSetInitialValue(calculatedIniValA);
    #endregion
    ...
}

Custom Extend Variables

Important

Custom created extended variables involve an increase in code maintainability and complexity. It is highly recommended to no use them unless required.

Custom variables might be required mandatory for proper digital twin behavior only if Use Symbolic Expressions is set to True. In new versions of the digital twin this option is by default set to False and its value cannot be modified.

Custom extended variables allows you to create Extended Variables manually; thats it, they are not handled by the digital twin and user must manually declare them, and trigger its methods manually.

Create

Warning

It is mandatory to declare custom extended variables within the UserCustomVariables region.

When creating a custom extended variable, it is mandatory to declare them within the UserCustomVariables region and initialize them within the CustomCodeIni region.

Next example illustrates how to create a custom extended variable names MyCustomExtendedVar1,

Example

...
#region UserCustomVariables   
// Custom variables can be declared here.
private ExtendedVariable MyCustomExtendedVar1;
#endregion

public override void Initialize()
{
    #region CustomCodeIni
    // Custom code here.
    this.MyCustomExtendedVar1 = this.NewVariable("MyCustomExtendedVar1");
    this.MyCustomExtendedVar1.Value = TOBESET;
    #endregion
    ...
}
...