Example of External HYSYS Controllers in a DDE Server

By Robb Wheatley, IFACE Group rev 2, April 16, 1998

HYSYS DDE Client DCS Drivers

One of two HYSYS DDE (Dynamic Data Exchange) DCS (Distributed Control System) Drivers may be used to communicate between HYSYS and DDE Servers via the DDE protocol. DDE Synchronous Tag Based Client DDE Synchronous Array Based Client

Both drivers are DDE Clients that initiate communications with DDE Servers. Pressing the Enable button in the DCS View initiates a DDE conversation. An error dialog is generated if the server is unavailable. Pressing the Disable button in the DCS View terminates the DDE conversation. The HYSYS DDE Drivers detect if the server disconnects the conversation with the client. For example, suppose an Excel spreadsheet was closed while a DDE conversation was in progress with a HYSYS application. An error dialog is generated if this situation occurs. DDE client transactions are also initiated periodically according to the data transfer interval configured on the Drivers page tab of the DCS View. Both drivers are synchronous. This means that DDE client transactions may time out when poking / requesting data to / from, or attempting to execute DDE commands on a slow DDE server. The timeout is configurable with the default value set to five thousand milliseconds. If a transaction times out, an error dialog box is generated. Unfortunately, DDE error dialogs may appear at the bottom of the window stack. If HYSYS seems completely unresponsive and a DDE driver is being used, using the ALT-TAB key sequence to cycle the visible window stack may indicate a DDE Error dialog that is causing the problem.

HYSYS DDE DCS Driver Specifics

This section describes the usage and specific details concerning the two HYSYS DDE Client DCS drivers.

General HYSYS DDE Client DCS Driver

Note that HYSYS DCS Drivers are only supported on the Windows NT operating system. When the DDE Client driver is loaded into HYSYS, some extra columns are added to the General Data page of the DCS View. The columns include Server, Topic, Enable Cmd, Reset Cmd, Start Cmd, Stop Cmd, and Disable Cmd. The Server and Topic column contents are used to initiate the DDE Conversation. All of the data transfers configured in the HYSYS DDE Client Driver DCS Views use the same Server, Topic pair for that HYSYS case. For example, when connecting to Microsoft Excel, the <server, topic> pair is as follows. <excel, [filename.xls]WorksheetName> When connecting to MATLAB, the <server, topic> pair is as follows. <matlab, engine> The Enable, Reset, Start, Stop and Disable Cmd column contents specify the command strings to execute on the DDE Server when DCS Link Enable, Integrator Reset, Integrator Start, Integrator Stop, DCS Link Disable events occur in HYSYS. Unfortunately, each vendor seems to use different CF_TEXT format data delimiters in their DDE Servers. We have only tested Microsoft Excel (\r\n separated values and \r\n at the end) and Mathworks MATLAB(\t separated values and \r\n at the end). The General Data page tab column labeled CF_TEXT delimiter exists in an attempt to provide DDE transfer with DDE Servers that we have not tested and that may use a different delimiter

string. If the DDE Server name is excel or matlab, the delimiter string will be internally set to the correct delimiter regardless of what the user enters for a delimiter. The timeout value for synchronous DDE transactions is configured in the Timeout (ms) General Data Page Tab Column. The default value is 5000 milliseconds. For large array based client transactions with a slow DDE Server, this timeout value may need to be increased.

DDE Synchronous Tag Based Client

The tag-based version of the driver allows the user to specify individual DDE item strings for each data element to be transferred. The DDE server and Topic strings are common to each data element and are configured on the General Data page tab of the DCS View. When using this driver, extra columns are added to the matrices in the controller and PV page tabs in the DCS View. DDE items for each data element are entered in these columns. Controller Setpoint (SP) and, possibly, Output (OP) data are requested from the DDE server according to the SP Item and OP Item tags configured in the controller matrix in the Controller page tab of the DCS View. Data is then written to the HYSYS controller attached to the matrix row. Note that the Output is only written if the Status entry in the row is set to DCS. Only the setpoint data is transferred if the Status entry is Internal. PV data is poked from HYSYS to the DDE Server according to the PV Item tags configured in the PV matrices in the PV page tabs of the DCS View. The content of the Status column in a PV matrix determines whether the PV data at that row in the matrix is transferred between HYSYS and the DDE Server. The PV is transferred if the Status value is DCS. The PV is not transferred if the Status value is Internal. A unique DDE transaction is initiated for each single tagged data transfer. The CF_TEXT delimiter for this driver is the end of data character. The delimiter for Excel and MATLAB is \r\n

DDE Synchronous Array Based Client

The array-based version of the driver differs from the tag-based version in that only three DDE Item tags are configured. One tag refers to the array of setpoint data, one tag refers to the array of output data, one tag refers to the array of PV export data and one tag refers to the array of PV import data. These tags are configured on the General Data page tab of the DCS View. The Status column of the controller matrix still governs the application of the received setpoint and output data to HYSYS controllers and PV import data even though the data is transferred between server and client in a single block. The Status column of the PV is ignored in the array-based version of the driver. Only four DDE Client transactions are required to complete the array data transfers. A performance test of data transfer for 20 PID controllers indicated that the array-based data transfer mechanism was about six times faster than the tag-based version. The CF_TEXT delimiter for this driver is the data separation character. For excel, the delimiter is \r\n. For matlab the delimiter is \t.

DDE Demonstration Programs

The basic purpose of this demonstration is to indicate how the HYSYS DCS Link can be used to help design control algorithms using an external software system to compute control actions and using HYSYS to model the plant. The control designer can focus on the controller and let HYSYS model the plant. Note that, in general, any HYSYS DCS driver may be substituted for the DDE drivers presented in this document. When the DCS link is enabled, an external program interacts with internal HYSYS controllers. Two types of interaction are possible. As previously mentioned, the Status column in the controller matrix on the controllers

page tab of the DCS View indicates whether setpoint only (Internal) or setpoint and output (DCS) data transfer is desired for a given controller. In the first scenario, only the controller setpoint is modified externally. This type of situation might occur in a multivariable control problem where the setpoints of several dependent controllers are modified according to some external algorithm. In this case, the internal HYSYS controllers still calculate their own output values. In the second scenario, an external program modifies both controller setpoints and outputs. This mechanism allows an external controller to replace an internal HYSYS controller. The output of the external controller is written directly to the output of the internal HYSYS controller thus bypassing the internal control. Controller setpoint information is also transferred for HYSYS GUI purposes. A simple HYSYS case including two tanks with level controls is used for demonstration purposes. Controller Status fields are both set to DCS in the demonstration HYSYS cases. Control actions are computed by an external program and results are transferred via the DDE Client DCS link. Equation 1 gives the basic PID controller response. Both the DDE Server demonstrations use this equation to calculate the controller outputs signals to send back to HYSYS. Note that the implementation of this equation in the demonstrations is very basic to keep the example code clear. The controller output calculations are synchronized with the HYSYS integrator using the Execute Cmd configured in the General Data Page Tab of the DCS View. Each data transfer period in HYSYS triggers the execution of the Execute Cmd on the DDE Server allowing iterative calculation of controller outputs.

op = bias + action kp error +

action kp

( error ) dt + ction

kp d

d ( error dt

(1)

bias = control valve bias parameter 1.0 = direct action 1.0 = reverse kp = controller gain error = setpo int process var iable action = controller

i = controller integral time constant d = controller derivative time constant

The mechanism to transfer HYSYS integrator data values from HYSYS to an external program is less than intuitive. Basically, the integrator variables need to be set up in a spreadsheet import cell and a spreadsheet export cell must be configured to refer to the input cell. The contents of the export cell in the spreadsheet will show up in the variable navigator brought up from the PV Page Tab in the DCS View. Performing the following steps allows data transfer of integrator time parameters. Create a spreadsheet object in the Workbook and open the Spreadsheet page tab. Open the Integrator View Click the value of the integrator parameter with the right mouse button and drag and drop it onto a cell in the spreadsheet( A6 for example). Note that this variable is an import variable. In a different spreadsheet cell, enter a formula, which refers to the import cell. For example, setting a formula for the cell B6 = +A6 will create an export variable to export the integrator parameter. The spreadsheet cell B6 will show up as a spreadsheet variable in the object navigator used to configure the PV matrix in the DCS view and the value will be identical to the integrator parameter. Add the spreadsheet cell to the PV matrix.

The current time and step sizes are transferred to calculate integral and derivatives of the error. Note that this assumes that the Data Transfer Period on the DCS Drivers Page Tab is set to 0.0 so that data is transferred every time step. If this is not the case the server code must be changed to calculate the previous time and store it.

HYSYS-MATLAB DDE Demo

Several events in HYSYS trigger the execution of MATLAB m-files as indicated in the following table. Event Enable DCS Link Integrator Reset Integrator Start Data Transfer Event Integrator Stop Disable DCS Link Occurs When User presses Enable (DCS View) User presses Integrator Reset (Integrator View) User presses Integrator Start (Integrator View) During each data transfer timestep User presses Integrator Stop (Integrator View) User presses Disable (DCS View) DDE Server Commands pidstart pidreset pidexec pidstop Demo m-files pidstart.m pidreset.m none pidexec.m none pidstop.m

The DDE Server Commands in the table above are entered into the appropriate columns of the matrix on the General Data Page DCS View. The demo m-files indicated in the table are executed when the corresponding event occurs in HYSYS. The following m-files are used for the demo. Tparrset.m Tparrplt.m Pid.m Pidstart.m Pidstop.m Pidexec.m The DDE item tags to configure arrays for data transfer of controller setpoints, controller outputs, and process variables are MATLAB vector names as indicated in the following table. Array Setpoint Output PV Export PV Import Array Tags sp op pv pvimport

These tag names are entered in the General Data page tab of the DCS View. Once the HYSYS DCS link is enabled, these variables may be viewed by typing their names in the MATLAB command window. The contents of the vector will be listed in the command window. Other MATLAB vectors of interest include kp, ti, and td.

Instructions for Running the MATLAB-HYSYS DDE demo

Note that this demo was constructed with MATLAB version 4.2.1c. It has since been updated to work correctly on MATLAB 5.2 as well, although the earlier version is still supplied. Start HYSYS and load the "mlbdemo.hsc" case. Start MATLAB In the MATLAB command window, cd to the directory that contains the demo m-files (depending on the version of MATLAB in use, the m-files will be in either the 42 or 52 folders). In HYSYS, open the DCS View (:Tools:DCS: from the menu bar if it is not visible) In HYSYS, press the DCS View Enable button. A MATLAB figure window that contains two empty controller response plots will appear. In HYSYS, press the Integrator Reset button (:Simulation:Integrator View). This resets the time to zero. In HYSYS, press the Integrator Start button. Plot traces indicating controller response trajectories will begin to appear in the plot window as data transfer events occur. In HYSYS, press the Integrator Stop button to stop the data transfer.

In HYSYS, press the DCS View Disable button to disable the DCS link.

HYSYS-MATLAB Demo Notes

In the MATLAB 5.2 demo, the figure does not appear after the first time the DDE link is enabled. Simply disable the link and enable it once more and the figure should appear. This seems to only be a problem the first time the link is enabled on a particular MATLAB session. The plots in MATLAB are dynamically generated and the data is NOT stored. If the plot is repainted, the existing trace is erased. Only the currently plotted point actually exists as part of the MATLAB plot object. Thus, upon resizing of the MATLAB figure window, all previous drawn points are erased. After the simulation has exceeded the time scale, the plot window may be re-scaled interactively by clicking the left mouse button on the plot window Any of the controller parameters (sp, pvimport, kp, ti, or td) may be modified interactively by setting the appropriate vector entry in the MATLAB command window. For example, to change the setpoint of controller LIC-101 to 50.0, type "sp(2) = 50.0" in the MATLAB command window. The change will be reflected in the HYSYS DCS View, HYSYS controller faceplates, and the MATLAB plot.

HYSYS-Excel DDE Demo

Several events in HYSYS trigger the execution of Excel Macros as indicated in the following table. Event Enable DCS Link Integrator Reset Integrator Start Data Transfer Event Integrator Stop Disable DCS Link Occurs When User presses Enable (DCS View) User presses Integrator Reset (Integrator View) User presses Integrator Start (Integrator View) During each data transfer timestep User presses Integrator Stop (Integrator View) User presses Disable (DCS View) DDE Server Cmd [run(PidStart)] [run(PidReset)] [run(PidExec)] [run(PidStop)] Demo XL Macro PidStart PidReset none PidExec None PidStop

The DDE Server Commands in the table above are entered into the appropriate columns of the matrix on the General Data Page of the DCS View. The indicated Excel macro is executed when the corresponding event occurs in HYSYS. The Excel macros are contained in a module named DDEAccess in the demo Excel spreadsheet file.

HYSYS-Excel DDE Array-Based Demo

The DDE item tags to configure arrays for data transfer of controller setpoints, controller outputs, and process variables are ranges of cells in the Excel demo worksheet as indicated in the following table. Array Setpoint Output PV PVImport Array Tags R3C3:R4C3 R3C5:R4C5 R8C3:R14C3 R18C4:R19C4

These tag names are entered in the General Data page tab of the DCS View. The contents of the data vectors are displayed in the demo Excel worksheet. It is straightforward to modify the other controller parameters on the Excel spreadsheet.

Instructions for running the Excel-HYSYS DDE Demos

Start HYSYS and load the xldemo.hsc case Start Excel and load the xldemo.xls spreadsheet In HYSYS, open the DCS View (:Tools:DCS: from the menu bar if it is not visible)

In HYSYS, press the DCS View Enable button. In HYSYS, press the Integrator Reset button (:Simulation:Integrator View). This resets the time to zero. In HYSYS, press the Integrator Start button. Plot traces indicating controller response trajectories will begin to appear in the Excel spreadsheet as data transfer events occur. In HYSYS, press the Integrator Stop button to stop the data transfer. In HYSYS, press the DCS View Disable button to disable the DCS link.

HYSYS-Excel DDE Tag-Based Demo

Note that a second HYSYS case named xlddetag.hsc is used to demonstrate the tag-based DDE Client driver. The difference between the tag-based and array-based examples is that the tag-based example has a single Excel worksheet cell configured for each SP, OP, and PV data element, rather than three arrays configured with ranges of Excel cells. Cell references are configured on the Controller and PV page tabs of the DCS View. Instructions for running the tag-based example are similar to those for the array-based example, just substitute the name xlddetag.hsc for xldemo.hsc

HYSYS-Excel DDE Demo Notes

The ExcelToHYSYS worksheet will update the display in a rather annoying fashion. The variables of the controllers may be manipulated by editing the appropriate spreadsheet cells. Note that a buffer keeps track of 100 data points. Once the 100 points have been collected, the buffer is erased and the old points are lost. Flushing the buffer erases a portion of the data visible on the screen The controller response plots on the Excel worksheet re-scale automatically.