Implementation of External HYSYS Controllers in an OLE Automation Client

By Robb Wheatley – IFACE Group, Hyprotech Ltd. – rev 2, April 16, 1998

This document describes mechanisms that may be used by an OLE Automation client for data
transfer and synchronization in Advanced Process Control applications. The same mechanisms
are also easily applied to other applications that may require data transfer and synchronization
between HYSYS and an external application. A very simple control application is the focus of the
description. The essential idea presented is that HYSYS may be used to simulate the plant while
control algorithms may be implemented in some external OLE client application. The actual
control algorithm is not particularly important in this presentation.

This document assumes that the reader has some knowledge of the HYSYS OLE Automation
Server and at least some exposure to Visual Basic. An overview of the example application,
some code examples, and instructions for running the example are presented.

Many internal HYSYS variables are available to OLE Automation clients. There are two classes
exported in the HYSYS type library, Application and SimulationCase. It is possible to navigate to
most objects on a HYSYS flowsheet from instances of these classes.

The following lines of Visual Basic create and bind a HYSYS case to a variable. In the example,
the VB subroutines LoadHYSYS and LoadCase contained in the Form1 form module perform a
similar operation to the code snippet listed below. The case is navigated to find two instances of
an internal HYSYS feedback controller class. The setpoint and output variables of the two
controllers are assigned the value 20.0.

Dim HyApp As Application

Dim SimCase As SimulationCase
Set HyApp = CreateObject(“HYSYS.Application”)
Set SimCase = GetObject(“d:\someCase.hsc”)
For each Ctrl in SimCase.FlowSheet.Operations(“FBControlOp”)
Ctlr.SetpointValue = 20.0
Next

The problem with this approach is that the values of the variables are assigned one at a time.
Each assignment requires a round trip across the process boundary between the HYSYS OLE
Automation Server and the external OLE Automation Client (VB in this case). Performance
degrades rapidly as the number of values to transfer increases. To help remedy this situation, an
interface to the HYSYS ProcessDataTable object allows more efficient data transfer across
process boundaries by reading or writing a set of data values in one boundary crossing.

A screenshot of the HYSYS example case is show in Figure 1. This case shows a PFD
containing two level control loops, faceplates for each of the controllers, and a ProcessDataTable
named ProcData1. ProcData1 contains the setpoints (SP), process variables (PV), and outputs
(OP) for the two level controllers LIC-100 and LIC-101 and simulation time variables. The Tag
and Access Mode columns in a ProcessDataTable configure the direction of OLE data transfers
between the ProcData1 server object and some OLE Automation Client. The following snippet of
VB code reads controller PV values from the data table, performs some control algorithm
calculations, and writes controller SP and OP values to the data table

1. Dim Dt as DataTable
2. Dim Rtags As Variant
3. Set Dt = simCase.DataTables(“ProcData1”)
4. Dt.StartTransfer
5. Rtags = Dt.ReadTags
6. Rvalues = Dt.GetValues(Rtags)

7. Dim Wtags As Variant

8. Dim WValues () As Double
9. Wtags = Dt.WriteTags
10. ReDim Wvalues(Ubound(Wtags)) As Double
11. ‘ Perform controller calculations here
12. Wvalues(0) = result of controller calc 1
13. Wvalues(1) = result of controller calc 2
14. Dt.SetValue Wtags, WValues
15. Dt.EndTransfer

Figure 1 xtrnlctl.hsc Example Case

Lines 1, 2, 7, and 8 are VB variable declarations. Line 3 binds an object variable to the
ProcData1 data table. Lines 4 and 15 set the boundary of a data transfer session during which
the data table tags cannot be modified. Line 5 returns a Variant that contains an array of string
tag names for the entries in the data table which have a Read or Read/Write AccessMode. Line 6
uses the ReadTags method of the data table and the RTags array to return an identically
dimensioned array of values for the tags in RValues. Line 9 returns a Variant that contains an
array of string tags for the entries in the data table which have a Write or ReadWrite
AccessMode. HYSYS variables that are not specifiable but have a Write Access mode in the data
table will not be added to the list of write tags since a write operation on them will fail. A list of
these incorrectly configured tags may be acquired using the CalcWriteTags method. Line 10
redimensions the array Wvalues to be identical to the Wtags array. Assume for now that Line 11
goes off and does some useful controller calculations. The Wvalues array is populated with
controller output values in lines 12 and 13. Finally, the new controller outputs are written to the
tagged variables in Line 14.

The example program is executed in HYSYS dynamics mode. Objects in the external client
application may register with the data table. Registered objects implement the NotifyEvent
interface. When events occur in HYSYS, the data table triggers the execution of the NotifyEvent
methods in the registered objects. The ODL code to define the NotifyEvent interface listed below
indicates that there are 8 methods in the interface. Each method returns a BOOLEAN and takes
no arguments.
interface NotifyEvent : IDispatch
{
BOOLMETHOD(EnableEvent, "Enable Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(DisableEvent, "Disable Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(StartEvent, "Start Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(StopEvent, "Stop Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(ResetEvent, "Reset Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(AbortEvent, "Abort Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(AdviseEvent, "Advise Event Notification", NO_HELP_PANEL, none);
BOOLMETHOD(CompletionEvent, "Completion Event Notification", NO_HELP_PANEL, none);
}

The example case triggers data transfers every Integrator timestep. Each time step, the
ProcessDataTable triggers a NotifyAdviseEvent on any registered NotifyEventSink objects. The
VB EBSink.cls and EventSink.cls class modules implement the NotifyEvent interface. In the VB
application, an instance of the EBSink class registers with the data table to receive these events
as indicated in the following code.

Public eventSink As EBSink

Set eventSink = new EBSink
Dt.AddNotifyEventSink(“vtablesink”, eventSink) ‘this line registers with the data table
….
Dt.RemoveNotifyEventSink(eventSink) ‘ this will cleanup before the application exits

Note that the EBSink class includes the Implements NotifyEvent statement. This means the the
EBSink class may be early-bound. This statement also requires that all of the methods in the
interface must be implemented even if they will never be triggered. The process data table
currently triggers the AdviseEvent, StartEvent, StopEvent, ResetEvent, and CompletionEvent
methods. However, the EBSink class still implements all eight methods in the interface. It is
possible to implement the interface using a Dispatch interface (late-binding) but the notifications
will only be half as fast. Performance is a primary concern when dealing with data transfers
occurring during dynamic simulations.

The EventSink class module in the VB application implements a Dispatch interface. Note that
only methods that are actually used need to be implemented in dispatch interfaces. In the
example, only the AdviseEvent method needs to be implemented. The code to register an
instance of the EventSink class is commented out in the application code but it was left in to
indicate that a late bound Dispatch interface could be used instead of an early bound interface.

The EBSink class implements the NotifyAdviseEvent method. This method will be triggered by
the data table every timestep. Following the template pseudo-code presented previously, the
implementation reads HYSYS PV values using the data table GetValues method with the
previously determined Rtags as an argument. Next, new controller outputs are computed
according to a simple PID algorithm. Finally, computed outputs and external setpoint values are
written into the data table using the SetValues method with the write tags (wtags) and new values
(wvalues) as arguments. Some additional pseudo-code is show below to illustrate the principle.
The actual VB code is a little bit different but the idea is the same.

‘ Read the HYSYS controller PV’s

Dim Rvalues as Variant
Rvalues = Dt.GetValues(rtags)

‘Compute the new controller outputs

Dim Wvalues[0 to 3] As Double
Wvalues[0] = setpointOfController1
Wvalues[1] = ComputePID(controller1, Rvalues[0])
Wvalues[2] = setpointOfController2
Wvalues[3] = CompuePID(controller2, Rvalues[1])

‘Write the new setpoint and output values into the data table
Dt.SetValue(Wtags, Wvalues)
The StartEvent, StopEvent, and ResetEvent methods are triggered when the HYSYS integrator is
started, stopped, or reset respectively. The HYSYS processDataTable also triggers a
CompletionEvent method in response to a steady state completion but we are only concerned
with dynamics here.

The controller algorithm implemented in the example is a very simple implementation of a PID
controller. The actual algorithm is not particularly important, as we are more concerned with the
data transfer and synchronization mechanisms. Readers are encouraged to drop in their own
algorithms.

In order for a HYSYS controller output to be overridden with an external controller output, the
execution mode of the internal HYSYS controller must be set to External. The execution mode for
a controller may be manipulated interactively using the HYSYS controller view. Alternatively, the
execution mode may be changed programmatically from an OLE Automation Client using the
IsLinkedToExternalDCS property of the Controller interface.

There is no problem mixing DataTable transfers and normal OLE method calls. In the example,
normal OLE calls are used to synchronize the external controllers in the SyncToInternalController
subroutine. In situations where the performance of the data transfer is not critical it may be more
convenient to use direct method calls. When performance is required, use a DataTable.

Another thing to be aware of is that unit conversion capabilities are available for data transferred
via the HYSYS ProcessDataTable. Data is transferred in internal HYSYS units unless a
conversion is specified in the GetValues or SetValues methods. In the example, we had to
transfer the simulation timestep in minutes rather than seconds for the control algorithm to work
correctly. Controller PV, SP and OP’s are all in the default % units in the example so no
conversions were required for these variables.

Running the Example Application

The following steps may be executed to run the example program. Refer to Fig 2 for GUI details.
 Start VB 5.0 from the \hysysRootDir\samples\xtrnlctl directory
 Load the VB project file xtrnlctl.vbp
 Start the application from the VB environment

The VB form shown in Figure 2 appears

 Click the Browse button and use the dialog to navigate to the example HYSYS case
 xtrnlctl.hsc is the example HYSYS case
 Click the Load Case button to load HYSYS and load the example case
 After HYSYS starts and the case loads, the controller parameters in the VB app are initialized
to the values in the HYSYS case.
 The integrator Start and Reset buttons becomes enabled. These buttons provide remote
control over the HYSYS integrator.
 The Controller Setpoint, Kp, Ti, and Td fields (show in green background) also become
enabled to allow modifications to the PID controller response.
 Clicking the Start button starts the HYSYS integrator. Data transfers commence and the
external controllers start to function. The controller outputs change. The PVs eventually reach
the setpoint values and the controller outputs level out. Any of the fields shown in green
maybe interactively manipulated. Clicking the Reset button stops the HYSYS integrator and
resets the simulation time to zero.
 The simulation time received from HYSYS is shown in the Sim Time text field.
 Change the setpoint of controller LIC-100 in the VB application and observe the changes in
the ProcessDataTable ProcData1 and the LIC-100 faceplate in the HYSYS case.
 Checking the Trace Checkbox pops a form that logs the NotifyAdviseEvent method of the
registered EBSink instance performing the PID calculation. Click the Stop button to stop the
integrator. Click the Clear Traces button to clear the trace window. Click the Start button to
see the event traces as the integrator starts again.
 Clicking the Quit button closes the case, unloads HYSYS and terminates the application.

Figure 2. OLE Automation Client – VB 5.0 External Controller Application XtrnlCtl.vbp