Local Code

Initialize

Within the Initialize method, certain methods can be used to help implement code behavior/functionality.

Methods

GetConstantVariablesValues

Returns a string with all constant variables names and its value for the current simulation (combination).

Example

public override void Initialize()
{
    #region CustomCodeIni
    ...
    string constantVarsValuesInfo = this.GetConstantVariablesValues();
    #endregion
    ...
}

Note that this is really meaningless by itself. This method is used mostly for debug purposes in conjunction with the WriteLine one.

public override void Initialize()
{
    #region CustomCodeIni
    ...
    string constantVarsValuesInfo = this.GetConstantVariablesValues();
    this.WriteLine(constantVarsValuesInfo);
    ...
    #endregion
    ...
}

WriteLine

Warning

It is highly recommended to not use this method unless for debugging purposes. It can block the UI (no-responsive) thread!

If there is the need to display specific messages on the digital twin logger, this method can be used to output messages.

Example

Consider that code is not working properly and you would like to know what is the value of a variable when starting the Initialize method. Considering a variable MyConstantVar1,

public override void Initialize()
{
    #region CustomCodeIni
    ...
    this.WriteLine($"The value is: {this.MyConstantVar1.Value.ToString()}");
    ...
    #endregion
    ...
}

Evaluate Step

Within the EvaluateStep method, certain properties/methods can be used to help implement code behavior/functionality.

Methods

StopSimulation

Indicates digital twin engine that current simulation should be stopped after current EvaluateStep is finished.

Important

Affects only ongoing simulation (combination). After ongoing simulation (combination) is stopped, next one (next combination) will be started independently.

Each simulation executes the EvaluateStep method as many times as X-Axis SimSteps (simulation steps). There might be the case, that you might want to stop simulation before performing all steps.

Note

Stopping ongoing simulation with current method does not invalidate simulation. As a consequence, when shown in the report section the X-Axis for that simulation might not reach the SimMax value but the one where it was stopped at.

Example

Consider that setting up a simulation duration (X-Axis) as follows,

this.XAxis.SimMin = 0.0; // Start value
this.XAxis.SimRes = 0.1; // Step (Resolution)
this.XAxis.SimMax = 18.5; // End value

where values values represent hours. Simulation will yield in SimSteps = 185 starting from X.Value = 0 to X.Value = 18.5 hours, incrementing each EvaluateStep call its value by 0.1 hours.

Lets now assume that we are simulating a process that concentrates a product (MySimulatedVar1). Maybe we don’t want to wait 185 steps to finish that ongoing simulation (combination), but before that if a condition is meet (e.g., concentration has reached 4.6 g/L). In that case a code like this could be used,

public override void EvaluateStep()
{
    #region CustomCodeEval
    ...
    if(this.MySimulatedVar1.Value >= 4.6d)
    {
        this.StopSimulation();
    }
    #endregion   
}

If condition >= 4.6 g/L is reached for example at step 75, when generating the report, this specific simulation instead of having a duration of 0 - 18.5 hours will be 0 - 7.8 hours as it is stopped at hour 7.8 (step 75).

StopSimulationPending

Note

This property is Read Only.

Returns True if StopSimulation method has been called; False otherwise.

Properties

StepsCount

Note

This property is Read Only.

Returns total number of steps to be performed for ongoing simulation (combination).

Its value is equivalent to SimSteps from X-Axis.

StepNo

Note

This property is Read Only.

Returns current step number. If ongoing simulation have 75 steps and at that moment EvaluateStep is being called for the 32 time, StepNo = 31.

Warning

StepNo is provided on a zero-based index.

That means that its value on first EvaluateStep call will be StepNo = 0 and its last one (unless simulation is stopped) will be StepNo = StepsCount - 1.

IsFirstStep

Note

This property is Read Only.

Returns True if StepNo = 0; False otherwise.

References

Hybrid Model

Warning

This reference should only be used (if needed) for digital twins created from an hybrid model.

The Model instance (reference) allows user to access digital twin underlying hybrid model basic properties and methods than can be used by the user independently of digital twin pre-designed logic.

Properties

Count

Returns the number of models within that hybrid model exported to the digital twin.

When exporting an hybrid model to the digital twin from its report section, multiple models can be selected to export an aggregated hybrid model conformed by multiple models taking as a result its average.

If exported model consist of 1 hybrid model, Count = 1; if exported in an aggregated manner, as many as exported models number will be indicated.

Example

int numberOfUnderlyingModels = this.Model.Count;

Methods

EstimateOutput

Warning

Digital twin has its on pre-designed logic on how to manage in the background the exported hybrid model, automatically wrapping the Extended Variables, Initialize and EvaluateStep method in conjunction to the automatic Mass Balance calculation methods.

If there is the use case where you still need to access this method; use at your own risk.

Method Signature

double[] EstimateOutput(double[] ystates_m_previter, double[] xmed_previter, double[] vol_previter)

Example

double[] ystates_m_previter = ...;
double[] xmed_previter = ...;
double[] vol_previter = ...;

double[] outputs_m_ti = this.Model.ModelsEstimateOutput(ystates_m_previter, xmed_previter, vol_previter);

Tip

If you need to know the names and indexes of outputs and inputs on how model was created, you can use following code. Do not use the Model reference.

# Outputs Names
string[] OutputsName = this.OutputsName;

Mass Balance

Warning

This reference should only be used (if needed) for digital twins created from an hybrid model.

Digital twin will automatically provide one mass balance entry foreach hybrid model output variable.

Methods

The methods described in this section are used to allow user interact with the mass balance helper in a friendly and intuitive way. The first part of the methods (variable) is always provided automatically and user only needs to replace (when need) the TOBESET placeholder by its value.

SetInitialVolume

Warning

This method can only be used within the MandatoryCodeIni region (Initial volume section)

If no mass balances where used during the hybrid model training, digital twin will automatically set the value to 1 indicating that no mass balance were used for those variables (e.g., MyOutputVar1 in next code example).

Example

#region MandatoryCodeIni
...
// Initial volume (if any; set '1.0d' if not)
this.MassBalance.SetInitialVolume(MyOutputVar1, 1 );
...
#endregion

On the other hand, if mass balance were used for some output variables, those will require user to mandatory provide a value. A place holder TOBESET will be set by default (e.g., MyOutputVar2 in next code example).

Example

#region MandatoryCodeIni
...
// Initial volume (if any; set '1.0d' if not)
...
this.MassBalance.SetInitialVolume(MyOutputVar2, TOBESET );
...
#endregion

Important

Make sure that the provided value has same units as ones used on hybrid model training Mass Balance -> Volume.

Tip

The value to provide as the Initial Volume for required variables can be provided directly replacing the TOBESET place holder with its value.

If value TOBESET requires calculations, it is extremely recommended to perform those calculations within the CustomCodeIni region, assigning result value to a local variable defined in that region, and directly replacing the TOBESET placeholder by that local variable. This will help you keep code clean and organized.

SetAddedMass

Warning

This method can only be used within the MandatoryCodeEval region (Output variables (ti) - Added mass section)

User must mandatory provide a value for the amount of added mass foreach output variables that used mass balances during hybrid model training. To do so, replace TOBESET place holder by its value at that step (or ti).

Note

If digital twin detects that certain output variables do not require/were not using mass balances during hybrid model training, its value will be automatically set to 0 (e.g., MyOutputVar1).

#region MandatoryCodeEval
// Output variables (ti) - Added mass (if any; set '0.0d' if none).
this.MassBalance.SetAddedMass(MyOutputVar1, 0 );
this.MassBalance.SetAddedMass(MyOutputVar2, TOBESET );
...
#endregion

Important

Make sure that the provided value has same units as the respective output variables mass.

Example

If output variable MyOutputVar2 units are g/L, provided value for Added Mass has to be in g dimension.

Warning

On the hybrid model Mass Balance setup, Feed is provided as a cumulative value.

The digital twin requires to provide only the added amount of mass (delta mass) at the current ti step; not the cumulative one including all previous steps as done in the hybrid model training!

SetAddedVolume

Warning

This method can only be used within the MandatoryCodeEval region (Output variables (ti) - Added volume section)

User must mandatory provide a value for the amount of added volume foreach output variables that used mass balances during hybrid model training. To do so, replace TOBESET place holder by its value at that step (or ti).

Note

If digital twin detects that certain output variables do not require/were not using mass balances during hybrid model training, its value will be automatically set to 0 (e.g., MyOutputVar1).

#region MandatoryCodeEval
...
// Output variables (ti) - Added volume (if any; set '0.0d' if none).
this.MassBalance.SetAddedVolume(MyOutputVar1, 0 );
this.MassBalance.SetAddedVolume(MyOutputVar2, TOBESET );
...
#endregion

Important

Make sure that the provided value has same units as the respective output variables volume.

Example

If output variable MyOutputVar2 units are g/L, provided value for Added Volume has to be in L dimension.

Warning

On the hybrid model Mass Balance setup, Volume is provided as a cumulative value.

The digital twin requires to provide only the added amount of volume (delta volume) at the current ti step; not the cumulative one including all previous steps as done in the hybrid model training!

Error

It is an error to provide a value different than 0 for a specific variable on the SetAddedMass(...) method and not provide a >0 value for the same variable SetAddedVolume(...); if mass gets added, volume is being added too.

SetSampledVolume

Warning

This method can only be used within the MandatoryCodeEval region (Output variables (ti) - Sampled volume section)

User must mandatory provide a value for the amount of subtracted/removed volume foreach output variables that used mass balances during hybrid model training. To do so, replace TOBESET place holder by its value at that step (or ti).

Note

If digital twin detects that certain output variables do not require/were not using mass balances during hybrid model training, its value will be automatically set to 0 (e.g., MyOutputVar1).

#region MandatoryCodeEval
...
// Output variables (ti) - Sampled volume (if any; set '0.0d' if none).
this.MassBalance.SetSampledVolume(MyOutputVar1, 0 );
this.MassBalance.SetSampledVolume(MyOutputVar2, TOBESET );
...
#endregion

Important

Make sure that the provided value has same units as the respective output variables volume.

Example

If output variable MyOutputVar2 units are g/L, provided value for Sampled Volume has to be in L dimension.

Note

On the hybrid model Mass Balance setup, Sample is provided as non cumulative (amount of volume subtracted for each sample). Digital twin behaves the same way for samples; provide only the subtracted amount of volume (delta volume) during sample at the current ti step; not the cumulative one.

Important

Sampled Volume is independent of Added Volume!

Added Volume is intended for volumes related to feeds (e.g., glucose feed) while Sampled Volume is a sample itself (finite amount of volume subtracted, e.g., from the reactor).

Digital Twin will first recalculate mass balances with Added Volume to correct concentrations and after that, subtract Sampled Volume to corrected overall volume.