LIBPFonOPC^® Maintenance and user manual

This document is the maintenance and user manual for LIBPFonOPC^® on-line solutions developed with LIBPF^® (LIBrary for Process Flowsheeting) version 1.1. It is also available in Italian.

See the LIBPFonOPC^® Installation manual for more informations on the development system, the architecture and the functionalities of LIBPFonOPC^®.

Concepts

Variables

The variables are classified as follows:

1. input: variables acquired by reading from the Distributed Control System (DCS), at least one;

2. result: results i.e., variables written to the DCS, optional;

3. constant: constant parameters for the calculation, optional.

Any variable of input or result type is a punctual link between a TAG of the DCS and a LIBPF^® variable.

All the variables (be they of input, result or constant type) must contain all the following elements:

• OPCtag: Value of the TAG into the DCS (including, if needed .PV or .SP extensions) for the connecting points (input and result) or numerical value in case of a constant;

• description: An optional descriptive text of the variable;

• TAG: Full path of the variable in LIBPF^®, see the next paragraph;

• UOM: Unit of measurement of the variable in the DCS: empty string for the dimensionless variables or one of the units specified in this table:

Additionally, the items of input or result type may contain the following optional elements:

• min: Minimum permissible value in the units of measurement specified by the UOM element – default value: -3.402823466E38;

• max: Maximum permissible value in the units of measurement specified by the UOM element – default value: +3.402823466E38.

If the min and max fields are set to finite values and not to the default values, these are used to keep the variables within an allowable range:

• For an item of input type, the value acquired via reading from the DCS is forced to remain within the [min..max] range;

• For an item of result type, the calculation result is forced to remain within the [min..max] range before being written to the DCS.

If the values of min and max are inconsistent (max <= min) an alert message is sent to the event log and both min and max values are reset to the default value.

Variables in LIBPF^®

In order to fill in correctly the TAG element of each variable, the full path of the variable in LIBPF^® must be given.

The LIBPF^® variables can be scalars (temperature, mass flow) or vectors (composition, mass flow for each component); the latter are indexed with the identifiers of the components: x[H2], mdotcomps[N2].

The list of the components is defined once and for all during the creation of the application, and in order to modify at a later time the choice of components you need to recompile the application.

In the following examples the available components with the respective identifiers are presented in this table:

The variables are grouped in objects that are type instances and which may in turn contain sub-objects.

When you want to reference a variable mdot contained in an object of type Phase called Tphase contained in the object of type StreamEosVapor called S01, the syntax requires to separate the identifiers of the models with the colon character (:) and in the end the variable with a period (.); in this example the full path of the variable is:

S01:Tphase.mdot

The types used in LIBPF^® OPC are the generic LIBPF^® types (see the LIBPF^® SDK Classes overview):

• Phase and its derived PhaseTotal, PhaseEos<PhaseType::vapor>, PhaseEos<PhaseType::liquid>, PhasePcsaft<PhaseType::vapor> and PhasePcsaft<PhaseType::liquid>

• StreamEosVapor

• StreamEosLiquidVapor

• StreamPcsaftVapor

• StreamPcsaftLiquidVapor

and additionally the types specific to the solution.

The Phase and its derived types define an homogeneous phase of matter and contain the scalar variables reported in this table:

and the vector variables reported in this table:

The StreamEosVapor and StreamPcsaftVapor types define a material stream in vapor phase with the volumetric properties determined with the equation of state of Kwong, Redlich and Soave or PC-SAFT, respectively.

They contain the following scalar variables:

• T: Temperature

• P: Pressure

and also an object of type phase appropriate for the total phase (vapor) called Tphase.

The StreamEosLiquidVapor and StreamPcsaftLiquidVapor types define a two phase material stream (vapor / liquid) with the volumetric properties and fugacity coefficients determined with the equation of state of Kwong, Redlich and Soave or PC-Saft, respectively.

They contain the following scalar variables:

• T: Temperature

• P: Pressure

They also contain the following sub-objects:

• An object of type PhaseTotal for the total phase called Tphase;

• An object of type Phase appropriate for the vapor phase called Vphase;

• And an object of type Phase appropriate for the liquid phase called Lphase.

Groups

The interface with the DCS is based on sets of variables (groups), corresponding to homogeneous data sets or referring to the same plant unit; there must be at least one group.

Each group must:

• have an unique identifier (id)

• be associated with a model which serves for calculating the variables of type result as a function of inputs and constants

• have at least one input variable.

The groups may also have the optional attributes description and enabled.

Splitting the variables in groups allows you to:

• Selectively enable/disable the groups;

• Associate more groups with the same model to promote modularity and reuse;

• Calculate one group at a time (if the on-demand operating mode is active) for example when values corresponding to certain sections of the plant are updated, while the remaining input variables remain unchanged and hence the other groups  need not be recalculated.

The mandatory attribute id is the identifier of the groups both towards the OPC server or for purposes of instantiation of the corresponding LIBPF^® model. It is therefore subject to the following constraints:

1. It must be unique;

2. It is case-sensitive;

3. Must begin with an alphabetical character (printable UNICODE characters only);

4. The subsequent characters must be alphanumeric or space, underscore _, hyphen -, left [ or right ] square bracket.

The mandatory attribute model determines the type of the LIBPF^® model, a choice of types specific to the on-line application.

The description attribute is optional and allows you to add a textual description to the group.

By means of the optional attribute enabled the groups can be enabled (true or 1) or disabled (enabled=false or 0), if the attribute is missing they are considered as enabled. Enabled means that they are configured with the OPC server and the calculation is performed, disabled means that they are only configured with the OPC server; if the groups (be they enabled or disabled) contain invalid tags, there will initially be errors of the type “Configuration error: impossible to add OPC link [XXXXXX.YY] for group [ZZZZZZZZ]” therefore they will be permanently disconnected since in any case it will be always impossible to enable them.

Operation

An on-line solution based on LIBPF^® OPC can operate in two modes:

• In console mode;

• As a service;

The console mode is useful for troubleshooting and is described in the appropriate chapter.

If running as a service, the application has no access to visible windowing or text mode, it doesn’t write any file or interact in any direct way with the user. In this case, the interaction with the running application occurs indirectly via:

• The LIBPF^® OPC Configurator, which allows to start/stop the service;

• The SCM (Service Control Manager) of the operating system, which allows to start/stop and even pause the service;

• The “Application” event log of the operating system, where critical events (Error), alerts (Warning) and notifications (Information) are recorded;

• The Trace Listener utility which makes the tracing of the operation visible as a list of textual messages.

Configuration and control via the Control Panel

The LIBPF^® OPC Configurator is an interactive interface for controlling the service of the on-line application and its configuration, which can be used as an alternative to the manual methods described in the “Manual configuration” chapter.

You can access the Configurator through the Control Panel by clicking “LIBPFonOPC Configurator” in the “System and Security” category:

The Configurator has an interface with three tabs:

1. Start / stop: to view the status of the LIBPFonOPC^® service, start or stop it.

2. Configure: to edit the general settings of the LIBPFonOPC^® service;

3. Variables: to view, edit, import and export the variables and groups of variables.

Start / stop

From the Start / stop tab you can view the status of the LIBPFonOPC^® service:

There also are two buttons:

• start and

• stop.

When the service is running, the start button is disabled, while when the service is stopped, the stop button is disabled.

When one of these button is clicked, the cursor becomes a hourglass until the command is successfully executed or however within a certain time-out.

On command time-out or end a message is printed in the status bar to describe the outcome.

Note: When the service exits, the connections are interrupted, all references to objects are deleted (particularly the handles to the groups on the OPC server) and the models are closed.

Settings

In the Settings tab you can edit the general settings of the LIBPFonOPC^® service:

The variables that can be configured are:

• home_path: full path of the settings.xml file on the disk, without backslash \ at the end; in the absence of a setting the default value is C:\, the value set by the installer is typically C:\ProgramData\LIBPF 1.0;

• kernel_path: full path of the LIBPFonOPC.exe executable on disk without backslash (\) at the end; in the absence of a setting the default value is C:\, the value set by the installer is typically C:\Program Files\LIBPF 1.0 (or C:\Program Files (x86)\LIBPF 1.0 if the 32-bit version of LIBPFonOPC is installed on a 64-bit operating system);

• CLSID: COM class identifier of the OPC (Globally unique identifier used to uniquely distinguish different software component interfaces in the Microsoft Component Object Model (COM)) server; default value “Hci.TPNServer”;

• sleepTime in ms (milliseconds): a parameter useful for modulating the CPU load; if a decrease of the impact on the server performance is required, increase this value – to accelerate the frequency of the calculation decrease this value; default value 1000 ms, valid values range from 0 to 10000;

• tracePipe: name of the named pipe for sending the trace messages, default value “LIBPFTracer”;

• traceServer: name of the computer on the named pipe of which the trace messages will be sent, default value “.” (corresponds to the local computer);

• verbosityGlobal: verbosity of generic messages sent to trace: the value 3 corresponds to the maximum number of messages, 0 should silence almost everything; default value 0, valid values range from 0 and 3;

• verbosityFlash: selectively controls the verbosity of the messages regarding the convergence of the resolution algorithms of the vapor/liquid flash, 3 is the maximum, 0 silences almost everything, valid values range from 0 to 3;

• readOnly: if checked, it allows you to run the application in “read only” mode, without writing any value on the DCS; unchecked value;

• maxErrCount: allows you to set the maximum number of alerts for reading/convergence/writing errors for each group, unlimited if set to 0; default value 3.

The alphanumeric settings can be directly modified by writing the new value in the field, or for the sleepTime setting by moving the slide-bar. In the case of paths like home_path and kernel_path, you can make changes by clicking the button containing the folder icon and browsing to the folder of interest.

The changes are immediately written in the system registry, therefore no “Apply” or “Save” button is present in this screen. However, for the changes to take effect, the service must be restarted (this must be done by the user).

After any change is written to the registry, a message is displayed in the status bar, for example: “Key [sleepTime] set to 1; restart service to make change effective“.

Variables

From the variables tab you can view and interactively edit the groups and variables as defined in the current settings.xml file, hence clicking “Save” will save the changes to disk:

The groups and the variables can be viewed by first clicking on the group on the left panel; in the following figure the “E200” group has been selected:

in the right panel the variables (input, results and constants) of the selected group are displayed.

You can modify the existent groups by directly editing the enable/disable check box, the description and the model (for the latter a pull-down list with available models will show up); to enter the edit mode in the alphanumeric fields, click once and wait a second.

In the figure above for example the “E200” and “S500” groups have been activated.

As soon as any change to the variables or groups is performed, a message is displayed in the status bar: “Unsaved changes“ and the “Save” button becomes active.

To add a new group click on the button with the blue symbol to the left of the empty row at the bottom; this way you create a new group with default settings:

which can be modified – particularly at least the id and the model must be set.

To delete an existent group click on the button with the red symbol at the left of the corresponding row.

To reorder the groups you can use the commands “Move up” / “Move down” available on right-clicking each group.

You can change the existent variables by directly editing the OPC tag, the description, the LIBPF^® tag, the units of measurement (for the latter a pull-down list with the available units will appear) and the lower and higher permissible limits; to enter the edit mode in these fields, click once and wait a second.

To add a new variable click on the button with the blue symbol at the left of the empty row; this way you create a new variable with default settings:

that can be modified – particularly at least the OPC tag, Description, LIBPF tag and UOM fields must be set.

To delete an existent variable click on the button with the red symbol at the left of the corresponding row.

To reorder the variables you can use the commands “Move up” / “Move down” available on right-clicking each variable.

The changes are not immediately saved to the settings.xml file, therefore you must click the “Save” button. However for the changes to take effect, also the service must be restarted (that must be done by the user).

After the change have been written to disk, a message is displayed in the status bar: “Settings.xml file overwritten; restart service to make changes effective“.

You can also:

• Import the previously saved settings.xml file from another location; after choosing the file to be imported:

  

  if there are unsaved changes in the active settings.xml file, a confirmation dialogue appears:

  

  once the operation confirmed the chosen file replaces the active settings.xml file and is immediately loaded onto the screen.

• Export the active settings.xml file with another name: after giving a name to the file that is being exported:

  

  the active settings.xml file is saved with that name and a confirmation dialogue appears:

  

• Update the view (for the case in which the settings.xml file has been modified by an external editor) by forcing the reload of the settings.xml file present on disk; if there are unsaved changes on the screen, a confirmation dialogue appears; once the operation confirmed the active settings.xml file is loaded onto the screen.

Note: After any modification of the variables, in order for the changes to take effect, restarting the service is necessary (and this must be done by the user).

Manual configuration and control

As an alternative to the LIBPFonOPC Configurator you can manually configure and control the on-line solution based on LIBPF^® OPC:

• The variables and the groups are saved into the settings.xml file;

• You can start/stop the service via the Service Control Manager of the operating system;

• You can also configure the main parameters that control the operation of the LIBPF^® OPC by directly manipulating the registry of the operating system.

The settings.xml file

You can manually configure the groups of variables (inputs, results and constants) with the associated calculation model by means of the configuration text file settings.xml encoded using UNICODE UTF-8, found on disk at the full path specified by the home_path variable (typically C:\ProgramData\LIBPF 1.0).

Therefore you have to build or change the settings.xml file before using LIBPF^® OPC. The changes to the file only take effect after relaunching LIBPF^® OPC in console mode or restarting the service.

In order to avoid errors the true configuration file is accompanied by two auxiliary files (which may not be manipulated by the user): schema.xsd (for syntax XML validation schema: https://www.w3.org/TR/xmlschema-2/) and stylesheet.xml (for user-friendly viewing and internal congruence control).

To view the settings.xml file, open it with a browser compatible with XSLT files such as Internet Explorer, Firefox or Safari; this is how the file will appear:

in this list the disabled groups will be shown in light blue. Clicking on a group it is possible to see the details:

NOTE: Opera, Google Chrome and Chromium are not supported because of this bug; Microsoft Edge is also not supported.

For small incremental changes of the configuration file it is advisable to use the free-ware Microsoft XML Notepad (https://microsoft.github.io/XmlNotepad/) utility, while for massive changes (copy and paste) a common text editor (e.g. Notepad) is more convenient.

The following figure shows the file while being edited with XML Notepad, with the composition aids:

If the configuration file is not syntactically correct, errors or warnings are reported in the “Application” event log of the operating system and the connections are not enabled.

Generally, the descriptive texts (tags, labels, descriptions) are not subject to length limitations and thanks to the UNICODE UTF-8 encoding they may contain any special character (such as accented characters, graphical characters, Cyrillic, Greek..).

The general structure of the settings.xml configuration file is shown in the following figure:

The file is organized in groups, each of which is associated to a model and within each group, in input, output and constant variables.

An illustrative settings.xml file in raw XML format could have the following appearance::

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="stylesheet.xsl"?>
<groups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="schema_dummy.xsd">
  <group id="E200" enabled="true" description="Esterification section 200" model="ReactorEsterification">
    <input>
      <OPCtag>TRC201.PV</OPCtag>
      <description>Reactor inlet temperature</description>
      <TAG>R200.T</TAG>
      <UOM>m</UOM>
    </input>
    <input>
      <OPCtag>PRC204.PV</OPCtag>
      <description>Reactor pressure</description>
      <TAG>R200.P</TAG>
      <UOM>barg</UOM>
    </input>
    <input>
      <OPCtag>FIC210.PV</OPCtag>
      <description>Total mass flow</description>
      <TAG>S04.mdot</TAG>
      <UOM>t/h</UOM>
    </input>
    <input>
      <OPCtag>X208.PV</OPCtag>
      <description>Solvent mass fraction</description>
      <TAG>S02:Tphase.w[S]</TAG>
      <UOM></UOM>
    </input>
    <result>
      <OPCtag>X298.PV</OPCtag>
      <description>Predicted fractional conversion</description>
      <TAG>R200:reactions[4].z</TAG>
      <UOM>mm</UOM>
    </result>
  </group>
</groups>

Starting / stopping the service

Launch the Microsoft management console services applet by clicking Start → Control Panel → Administrative Tools → Services and start / stop the service:

Note: When the service exits the connections are interrupted, all references to objects are deleted (in particular the handles to the groups on the OPC server) and the models are closed.

Operating system registry

You can configure the main parameters that control the operation of the LIBPF^® OPC directly through the operating system registry.

The relevant keys are in HKEY_LOCAL_MACHINE\Software\libpf.com\LIBPF 1.0:

Troubleshooting

Tracing

Tracing gives a detailed diagnostic on the program operation.

LIBPF^® OPC has two types of tracing:

T1) tracing of the LIBPF^® OPC module and of the main program;

T2) tracing of the calculations performed by the LIBPF^® CORE module.

The T1 trace is normally sent to console, or to a named pipe if anybody is listening. The default named pipe is local: \\.\pipe\LIBPFTrace; using the tracePipe and traceServer registry entries you can change the name and remote workstation on which the connection is being attempted. In this case the user on whose behalf the LIBPF^® OPC program is launched (normally the local NT AUTHORITY/SYSTEM account on the server in case of running as a service) has the needed credentials to open the named pipe on the remote workstation. You can for example start the service impersonating a domain account with the appropriate access rights.

To request the trace, launch the TraceListener.exe utility before starting the service, with a double click on Start → Programs → LIBPF 1.0 → Trace Listener.

The T2 trace instead is only sent to console, therefore in order to view it you have to start LIBPF^® OPC in console mode (see next paragraph).

Console mode operation

To be able to view both trace T1 and T2, instead of starting LIBPF^® OPC as a service, start it via Start → Programs → LIBPF 1.0 → LIBPFonOPC console.

If you need to save in a file the trace sent to the console, open a Prompt command window, change the current folder to C:\Program Files\LIBPF 1.0 (or C:\Program Files (x86)\LIBPF 1.0 if the 32-bit version of LIBPFonOPC is installed on a 64-bit operating system) and run the program with the commands:

cd C:\Program Files\LIBPF 1.0
LIBPFonOPC -console > %USERPROFILE%Desktop\log.txt

The program can be stopped by pressing the q key (lower-case Q) when the focus is on the console in which it runs.

By closing LIBPFonOPC this way in console mode, all references to objects are deleted (particularly the handles to the groups on the OPC server), the simulation is closed, the connection with the OPC server is interrupted and finally the application is closed. If instead the console in which LIBPFonOPC is running is directly shut down, the resources on the OPC server are not freed, which could lead to problems with certain OPC server implementations.

Exit codes

At the end of an execution in console mode without errors, the application will exit with code 0. The negative exit codes are associated to fatal errors:

When the program generates a fatal error, it should also send a message to the “Application” event log of the operating system.

Please refer to the following “Errors” section for the corrective actions to take case by case.

Event logging: categories and types of messages

The messages in the “Application” event log are of four types (classification defined by the operating system):

1. Error

2. Warning

3. Information

4. Success

Additionally the messages emitted by LIBPF^® OPC are divided in four categories:

1. XML: related to the validation and scanning of the settings.xml file

2. OPC: related to the communication with the OPC server

3. LIBPF: related to LIBPF^® CORE

4. General: related to the connection to the named pipe, to the management of the communication with the SCM (Service Control Manager), to the expiration date of the application user license, starting and stopping notifications.

Errors

Notices

Information (information and success)

There is normally no required corrective action for these messages.