OLGA OPCServer Guide

DYNAMIC MULTIPHASE FLOW SIMULATOR

OLGA 2015 Version 2015.1

OPC server guide

OLGA OPC server TN-341010017509/20

Page i


Page ii

TABLE OF CONTENTS: OLGA OPC server Page 1.

INTRODUCTION

1

2.

OVERVIEW OF OLGA OPC SERVER 2.1 The OPC Standard 2.2 OLGA OPC server 2.3 Simulator modes 2.4 Simulator items 2.4.1 Time resolution of Date items 2.5 Security 2.5.1 Access control 2.5.2 Non-administrator users 2.6 Running the OPC server 2.6.1 Running the OPC server as an executable 2.6.2 Registering the OPC server 2.6.3 Register the OLGA OPC server as a Windows Service 2.6.4 OPC server command line parameters 2.6.5 DCOM settings 2.7 Running several OLGA OPC servers from the same case

2 2 2 3 3 3 3 3 4 4 4 4 5 5 6 6

3.

OLGA OPC SERVER CONFIGURATION AND CONTROL 3.1 Configuring the OLGA OPC server 3.2 Simulation speed control (INTEGRATION keyword) 3.3 Simulator control commands 3.3.1 The Snap Commands 3.3.2 SetTime 3.3.3 Stop 3.3.4 PAUSE 3.4 Special global variables 3.4.1 Input items 3.4.2 Output items 3.5 Model output – SERVERDATA keyword 3.6 Model input – EXPOSE key 3.7 Model specific commands 3.7.1 Pig Launch 3.8 Simulator item namespace 3.8.1 Properties on the items

8 8 9 10 10 11 11 11 11 11 11 12 13 14 14 15 16

4.

WORKFLOW EXAMPLE: ADDING OPC SERVER TO STANDARD OLGA CASE 4.1 Enabling the OPC server 4.2 Configuring output variables 4.3 Configuring input variables 4.4 The simulation session

18 18 18 19 20

5.

REFERENCE LIST

24


1.

Page 1

INTRODUCTION

This document provides a guideline for how to use the OLGA* OPC server. It describes the keywords and keys used to configure the OPC server, how to set up output via the GUI, and how an OPC client can issue commands, and send values to the running OLGA simulation. In order to consume data a OPC server, an OPC client is required. OLGA comes with a customized OPC client for viewing and accessing data on the OLGA OPC server called OLGA Namespace Explorer[1] (ONE). The tool can be accessed from the OLGA Tools menu. In addition, several 3rd party vendors provides OPC clients that can be used to access OPC servers like the OLGA OPC server. By default you need administrator privileges to run OLGA using the OPC server. In the OLGA installer, there is an option to pre-install five OPC servers which can be run by nonadministrator users. For more information see the OLGA Installation Guide


2.

Page 2

OVERVIEW OF OLGA OPC SERVER

2.1 The OPC Standard OPC is a standard method to allow for exchange of data between industrial and automation systems. The OPC foundation maintains and develops standards that ensure that this exchange is possible. In the OPC standard information is organized into three levels: The OPC server, OPC Group and OPC Item (sometimes also referred to as an OPC tag). The OPC server contains information about how clients can connect, and one server can contain one or several groups, which in turn contains the OPC items. There is no direct access to an OPC Item from the server, all connections have to go through the OPC Group. All OPC items consists of a value, a timestamp and a quality value. (OPC Foundation, 2002).

Item 1 Group 1

Item 2 Item 3

OPC Server 1 Item 1 Group 2 Item 2

Figure 1: The OPC DA data model

The OPC standard stresses that OPC Items just serve as data connections, they are not the actual data sources: “The OPC Item should be thought of as simply specifying the data, not as the actual physical source of the data that the address references” (OPC Foundation, 2002, p. 3). This means that the latest known value will be available on the OPC server even if the connection to a data source is lost. The OLGA OPC server uses OPC Classic for information exchange. OPC Classic is based on the Microsoft Component Object Model (COM) and Distributed Component Object Model (DCOM) standards, and the OPC standard used in OLGA is the “OPC DA version 2.05a”.

2.2 OLGA OPC server An instance of the OLGA OPC server is an OPC server for a specific OLGA model running in the OLGA engine. The rationale behind this is that the available data (input and output) depends on the model scope as well as the model options. For instance, a model with MEG tracking gives additional possibilities for input and output variables compared to the same model without MEG tracking.


Page 3

The data provided by the OPC server also depends on the components and process equipment included in the model. If, e.g., a model includes a valve “A” then the OPC server can be configured to provide the valve opening as input data item. If later valve “A” is deleted from the model, the OPC server will not provide the valve opening input item. Thus the available data on the OPC server is determined by model scope. The model command interface and input/output variables that can be made available on the OPC server are defined by specific keywords and keys in the model configuration. More information on how this is configured is described further down in this document.

2.3 Simulator modes OLGA can run in two different modes through the OPC server: The first mode, called SIMULATOR, lets OLGA run at a given speed relative to real-time. In the second mode, called EXTERNAL, OLGA follows an external clock. This requires that the OPC client updates an external clock item provided on the OLGA OPC server; OLGA runs (performs simulation time steps) as long as the external clock time is greater that the internal simulation clock time of OLGA.(Cf. key SIMULATORMODE in section 4.1.).

2.4 Simulator items The OLGA OPC server namespace holds a collection of objects named items (variables). Each item holds the current value of a given OLGA calculated output, input or command. The items in the namespace can be: 1. Output data: a. OLGA calculated trend variables, for instance pressure at a specific position, liquid level in a separator etc. b. OLGA calculated profile variables, for instance pressure profile of a flow path. 2. Input data, for instance valve opening, mass flow rate of a source or a pressure boundary specification. 3. Commands, for instance save snap and load snap commands, stop command, etc. Commands and input data are writable, while output data are read only. 2.4.1 Time resolution of Date items The OPC server items like SIMTIME, INITTIME and ExternalClock are of data type Date. The date has a resolution of 1/64th second.

2.5 Security 2.5.1 Access control The access of the OPC server from the different OPC clients is configured with the DCOM configuration tool (DCOMcnfg.exe). The security settings can be set both for the computer as a default setting (see Figure 2) and/or it can be overridden individually for the different DCOM servers. In the case where the OPC server needs to access the OPC client, in the case of a callback (data subscription or shutdown), the DCOM security setting of the OPC client has to be configured.


Page 4

Figure 2. Default DCOM setting for the computer

DCOM security settings for a OLGA OPC server can be set if the server is registered as a server or as a Windows Service. More information about registration of the server can be found in section 2.6 Running the OPC server. 2.5.2 Non-administrator users To install OPC servers that can be run by non-administrator users, there is an option in the Custom dialog of the OLGA installer (OPC servers for non-admin users) to pre-register 5 OPC servers for use without administrator privileges. These five OPC servers are always named OLGAOPCServer, OLGAOPCServer1, OLGAOPCServer2, OLGAOPCServer3 and OLGAOPCServer4. Any other OLGA OPC servers require administrator privileges as usual. OLGAOPCServer is the default server name set in SERVEROPTIONS. It is not recommended to use the command line arguments for preregistered OPC servers.

2.6 Running the OPC server There are three options for running the OLGA OPC server. 2.6.1 Running the OPC server as an executable The default behaviour of the OLGA OPC server is to be available the simulator is running and not visible to any OPC clients when the simulator is not running. This means that the running OLGA case is registered as an OPC server when the simulator is starting up, and unregistered when simulation is done and the simulator stops. Since the OPC server is unregistered when the simulation stops and the simulator exits, an OPC client cannot start the OLGA OPC server and consequently the OLGA simulation engine . 2.6.2 Registering the OPC server


Page 5

If you want to keep the OPC server visible to clients when the simulation is not running, you can register the OLGA case as an OPC server. When the OPC server is registered, it will always be available for OPC clients even if the simulation is not running. If an OPC client connects to the OPC server, the simulation will start simulating the OLGA case that was previously registered. The server can also be started and stopped from command line using the parameter given in section 2.6.4. 2.6.3 Register the OLGA OPC server as a Windows Service If you are running OLGA on a remote server, without any user interaction except via the OPC server, you might want to register OLGA as a service. This means that OLGA will run without a user logged into the server, and without any open console windows. You can also set up the service to automatically start when Windows has started. Any information, warnings and errors from OLGA can be found in the Windows Event Viewer. Registering OLGA as a service automatically also registers the OLGA OPC server. 2.6.4 OPC server command line parameters The command line parameters listed below are used to preregister an OLGA case as an OPC server. You can also remove an OLGA case as an OPC server. -regServer + This parameter is used to register an OLGA case as an OPC server. -regService + This parameter is used to register an OLGA case as an OPC server where OLGA will be running as a Windows service. -unreg This parameter is used to unregister OLGA server or Windows service. -start This parameter is used to start an OLGA case already registered as an OPC server or Windows service. -stop Use this parameter to stop a running registered service. This only applies when the OLGA case is registered as a Windows service. These parameters will typically be used in OLGA server solutions where it is important to  keep OPC server information so that DCOM security settings are not removed when OLGA terminates.  avoid OLGA terminating when e.g. the user logs off the computer.

Note: These parameters are not available through the OLGA GUI.

2.6.4.1 Compatibility -regServer and -regService can be used together with other command line options. For –regService, the Windows service has the same name as the OPC server.


Page 6

-start, -stop and -unreg can only be used together with ServerName. For example: OLGA.exe -start ServerName OLGA.exe -stop ServerName OLGA.exe -unreg ServerName

-extclk can be used to override the simulator mode set in the case file. 2.6.4.2 Examples of applying command line options:

Case name: “MyModel.key” SERVERNAME key in SERVEROPTIONS: “MyServer” Registering an OLGA OPC Server: OLGA.exe "C:\caseDir\MyModel.key" -regServer

Registering an OLGA OPC server as a Windows Service: OLGA.exe "C:\caseDir\MyModel.key" -regService

Note that when an OLGA case runs as a service, the OLGA console is not available and output to console is written to the Windows Application event log instead. Starting, stopping and unregister OLGA OPC Servers, also applicable when it is registered as Windows Service: OLGA.exe -start MyServer OLGA.exe -stop MyServer OLGA.exe -unreg MyServer

2.6.5 DCOM settings By default all DCOM and OPC server settings are removed when OLGA executable is terminated gracefully when running in engineering mode. If the case has been registered with the -regServer command, the DCOM and OPC server settings are removed when the command -unreg is run.

2.7 Running several OLGA OPC servers from the same case If you want to run multiple instances of the same OPC server case simultaneously, you will have a conflict since the server name will be the same. To resolve this there is a command line parameter for OLGA, named –serverNamePrefix that will allow for appending a prefix to the serverName. If SERVEROPTIONS.SERVERNAME is MyModel in the case file and OLGA is started with the following command line: Olga.exe -serverNamePrefix "Server1_"

then the name of the OLGA OPC server becomes “SPT.Server1_MyModel.7”


Page 7

Together with the command line parameter -outDir, it is now possible to run the same case with different server names and route the output data of each simulation into different folders with names according to the given prefix. Example: Olga.exe MyModel.key -serverNamePrefix "Server1_" -outDir Server1 Olga.exe MyModel.key -serverNamePrefix "Server2_" -outDir Server2

This will start two OPC “SPT.Server2_MyModel.7”

servers

with

names

“SPT.Server1_MyModel.7”

and

The files generated by OLGA while simulating will be written to folders ...\Server1 and …\Server2 from the folder containing the MyModel.key case file.


3.

Page 8

OLGA OPC SERVER CONFIGURATION AND CONTROL

3.1 Configuring the OLGA OPC server The OLGA OPC server is enabled by adding the SERVEROPTIONS keyword to the case. This keyword contains the following input parameters: Key

Value

SIMULATORMODE [SIMULATOR], EXTERNAL

SERVERNAME

Description Simulator mode. 'Simulator' means a free-running simulator operating on its own. 'External' means that the simulator will try to keep synchronized with the ticking of the external clock, it will wait whenever it catches up with the external clock.

[OLGAOPCServer] The OPC server name. The server name should be a single word, with no spaces (' ') or dots ('.').

MODELNAME

The model or submodel name.

MODULENAME

[Sim]

The module name.

INPUTLOG

[OFF], ON

Turns on or off logging of external inputs to the simulator. Must be ON if later playback for reproducibility of simulation results should be possible.

STOPATENDTIME

[OFF], ON

Specify if the server should follow the ENDTIME setting on the INTEGRATION keyword. Default is OFF which means that the server case will continue running until explicitly stopped.

EXPOSE

Exposable

Yes

States which keys should be made available as input variables on the OPC server. Only keys that are explicitly set with a nondefault value can be exposed. To use the default value, you must define this explicitly..

Only MODELNAME is a required key; the others have meaningful default values. SIMULATORMODE = SIMULATOR lets OLGA run as fast as possible, or at a speed given relative to real time. You can set the speed with key SIMULATIONSPEED in keyword INTEGRATION. SIMULATORMODE = EXTERNAL lets OLGA execute its time-steps until its time becomes greater than the external clock. This item is named ModuleName.ModelName.ExternalClock,


Page 9

and its value should be set to an UTC date/time. To monitor OLGA’s UTC time, add the output variable SIMTIME. To read (or write) the simulation’s biased starting time, inspect the item ModuleName.ModelName.INITTIME. Note that the SIMULATIONSPEED key under INTREGRATION keyword can be used also with SIMULATORMODE = EXTERNAL. Note that a Scheduler in SIMULATORMODE = EXTERNAL will force all its submodels to also use EXTERNAL even if they are specified as SIMULATORMODE = SIMULATOR. The value of SERVERNAME is used by the client to identity the OLGA OPC server. The key must be set to a single word. The word is automatically prefixed with ‘SPT.’ and postfixed with ‘.7’ to form the full OPC server name ‘SPT.ServerName.7’. This text string is echoed by the simulator when the OLGA OPC server is initialized. The value of MODELNAME is used in the naming of the namespace items; the text string is the second level in the item names. INPUTLOG = ON leads to the creation of a OPC server log file in the case directory (where the .opi or .key file is saved). The file is named ‘OlgaCaseName.sil’. The file will record all OPC requests received by the OLGA OPC server.

3.2 Simulation speed control (INTEGRATION keyword) You can control the speed of simulation using the INTEGRATION keyword. The keys in INTEGRATION that can be accessed through the OPC server are: Key MAXDT

Value [1.0 s]

MINDT

[0.001 s]

SIMULATIONSPEED [0 -]

MAXLAGFACT

[0.3 -]

Description Largest time-step allowed. Smallest time-step allowed. Simulation speed relative to real-time. Zero means simulate at highest possible speed. Any other positive number means that the simulator will slow down the simulation so it matches the factor given relative to real time. Maximum lagging factor (see LAGFACT output variable) to allow before the output variable LAGIND is set to 1.

Exposable Yes Yes Yes

Yes

Setting SIMULATIONSPEED to a value other than 0 can result in pauses being inserted between OLGA’s timesteps, to let the average speed of the simulation come as close as possible to the prescribed value. The value is given as a factor of real time, and hence SIMULATIONSPEED = 0.1 indicates that you would like OLGA to spend 10 minutes wall-clock time to reach 1 minute into the simulation. Likewise, by setting SIMULATIONSPEED = 15, you tell OLGA to try to simulate 15 seconds of the model in 1 wall-clock second. Use the global output variable SPEED to monitor the actual speed of OLGA. If SIMULATIONSPEED is set


Page 10

too high, OLGA will not be able to catch up, i.e., the OLGA model will “lag” behind the specified speed. The MAXLAGFACT value defines a threshold for when to report lagging. Lagging is reported through the global output variables LAGFACT and LAGIND.

3.3 Simulator control commands The commands are visible to the client as writeable tags. The initial value is ‘false’ for any command. When the value is set to ‘true’, the command is issued, and execution starts. When the command has been executed, the OLGA OPC server sets the value back to ‘false’. All commands but the Stop command, takes two arguments. The Stop command takes none. The snap commands take a filename, which is a text string, and the SetTime command takes a number of seconds. The snap commands and the SetTime command also take the command argument EnforcePause. When EnforcePause is set to true, a server command behaves as follows: 1. Sets server state to PAUSED. 2. Executes command (Normal). 3. Sets server state to PAUSED.

After a command has executed with EnforcePause set to true, the OLGA simulation state will be PAUSED. In order to get the simulation running again, the OPC item PAUSE has to be set to ‘false’. When EnforcePause is set to false, all server commands behave as before.

As mentioned above, the full name of any command starts with ‘ModuleName.ModelName.’. Below, only the signifying parts of the names are used. 3.3.1 The Snap Commands These three commands handle saving and loading of simulator state, and deleting snap files from the hard disk. The implementation of Save- and LoadSnap is built on the OLGA’s restart mechanism. Command item Argument item

Description

SaveSnap

SaveSnap.File

Saves a snapshot of the simulator state to the file given as argument.

LoadSnap

LoadSnap.File

Reloads a previously saved state stored in the file given as argument.

DeleteSnap

DeleteSnap.File

The file given as argument is deleted from the hard disk.


Page 11

3.3.2 SetTime The SetTime command lets you manipulate OLGA's internal time. The argument SetTime.Time is the OLGA simulator time given as the number of seconds since simulation started. If you use this command, you change the values of the TIME and SIMTIME variables. In the case of EXTERNAL simulator mode (see keyword SERVEROPTIONS), the simulation will halt if SIMTIME now becomes greater than ExternalClock, see section 2.3 and section 4.1 for further details. 3.3.3 Stop The Stop command stops the simulator and closes down the OPC server. Efforts are made to remove the relevant entries in the Windows registry. Accordingly, the OPC client may no longer detect any OLGA OPC server. If you were running a so-called batch run, some informational text is printed while the server is shutting down. You can also stop the case from running, and removing the OPC server by clicking the stop button in the OLGA GUI; for a batch run, you can also try pressing Ctrl+C in the DOS window, or just closing this window. 3.3.4 PAUSE PAUSE is an OPC item, which is always present in the OPC server. When this variable is set to ‘true’, the time integration and simulation in OLGA is paused. When the value is set back to ‘false’, the time integration and simulation resumes. Since PAUSE only exists in the OPC namespace you cannot directly set the value of the PAUSE from the key file. Then you must use the key INITIALSTATE (in SCHEDULER keyword) which can either have value PAUSED or RUNNING (default).

3.4 Special global variables 3.4.1 Input items When the key SIMULATORMODE in SERVEROPTIONS is set to EXTERNAL, the writable tag “ExternalClock” is created at the OPC server. The variable INITTIME is always present in the OPC server. This means that a client can change the initial time of the simulation. 3.4.2 Output items Some output variables that are of special interest when using the OLGA OPC server. The variables LastMessage and State are always present in the OPC server. Note that the variable SIMTIME equals INITTIME + TIME. INITTIME and SIMTIME are UTC date/time, while TIME is always given in seconds. The table below summarizes also some (global and trend) variables that are useful in server simulations: Variable

Description

TIME [s]

OLGA’s internal time. Usually, you see this as the x-axis variable of trend plots

SIMTIME [UTC] This is OLGA’s time as a UTC date/time. The reference point is the UTC time at the moment OLGA started simulating. In server mode, the reference point can be manipulated by writing to INITTIME (see above).


Page 12

SPEED [-]

The ratio between the speed of OLGA’s clock to the speed of the CPU clock (real time). Usually the speed is limited by the hardware and the size of the model, but it may be limited by the value of key SIMULATIONSPEED (see chapter 3.2).

LAGIND [-]

If SIMULATIONSPEED is set, the lag indicator shows 1 when OLGA is too slow, otherwise 0. By setting MAXLAGFACT in the INTEGRATION keyword, one specifies a threshold the speed must deviate before LAGIND becomes different from 0.

LAGFACT [-]

Like LAGIND, this variable depends on SIMULATIONSPEED. It tells how many times faster OLGA needs to run to keep the prescribed simulation speed. Thus, a value of 1.0 shows that OLGA needs to double its speed, or that the speed requirement should be halved.

3.5 Model output – SERVERDATA keyword The SERVERDATA keyword works similar to TRENDDATA and PROFILEDATA keywords, except it does not create a text file. Instead, all specified VARIABLES will be visible on the OPC server output items. Key VARIABLE

Value

DTPLOT

[0 s]

Description List of variable names to be plotted. Units may be specified. Interval for update of server data.

SERVERDATA behaves similar to TRENDDATA, and accepts the same keys. If a position along the pipeline or a labeled process equipment is given, SERVERDATA works like TRENDDATA, i.e., for a single point/equipment on the pipeline. If no position or label is given, SERVERDATA works like TRENDDATA for equipment and branch variables or as PROFILEDATA for each section/boundary variables. Each SERVERDATA has its own DTPLOT key that works for the list of output variables specified with the present keyword. Hence, the user can set different sample intervals for different lists of output items. DTPLOT=0 s means to update the item after every time-step. An example of usage for global variables is: SERVERDATA \ VARIABLE=(HT, LAGFACT, LAGIND, SIMTIME, SPEED, TIME),\ DTPLOT=3 s An example of usage as part of a flowpath network component setting in a first entry profile variables HOL and PT, and in a second entry the trend variable GT is: SERVERDATA VARIABLE=(HOL, PT) SERVERDATA VARIABLE=GT, POSITION="TOPSIDE-OUT" An example of usage as part of a flowpath network component setting a valve labeled ‘CHOKE3’ is: SERVERDATA VARIABLE=VALVOP, VALVE="CHOKE-3"


Page 13

With TRENDDATA it is in this case possible to leave out the equipment key VALVE. This is however not possible with SERVERDATA. Force update on OPC server output items on each OLGA time step In OLGA versions prior to version 7.3.1, the time stamp on the OPC server output items was updated at the interval specified by DTPLOT. In OLGA 7.3.1, the value on the OPC server output items is validated. If the value is unchanged, then the item time stamp is not updated. As of OLGA 7.3.3, OPC server output data of type trend data reports updated time stamps at every OLGA time step independent of whether the item value is changed or not when DTPLOT = 0.

3.6 Model input – EXPOSE key The key EXPOSE is found in several keywords. Its argument is a list of keys belonging to the present keyword, and its effect is create (‘expose’) input items that are mapped to writeable tags in the OPC client. When one of these tags is given a new value by the client, this value becomes the value used in the OLGA simulator at the first time-step after the value was written. This way, exposing keys lets the client control the state of the OLGA simulator; a process simulator could use the input tags to pass values from itself into OLGA. For each keyword that has the EXPOSE key, there is a predefined list of keys the can be exposed. In the GUI, you can press the ‘…’ button at the right of the EXPOSE value field to see the complete list of keys that are exposable. Figure 3 shows this list when the ‘…’ button is clicked in a SOURCE keyword.

Figure 3. The select dialogue for the EXPOSE key of SOURCE keyword.

A key will only be exposed on the OPC server if the following conditions hold: 1)

The key is in the list of exposable keys.

2)

The key is chosen for exposure.

3)

The key is in use (not grayed out) in the case configuration.


Page 14

4) The key has an explicit value given by the user, or it has a default value that is a meaningful value in a physical sense (e.g. VALVE OPENING = 0 is meaningful, but the default SOURCE WATERCUT = -1 is not).

If you specify EXPOSE = STDFLOWRATE for a SOURCE that uses MASSFLOW key, a warning is printed, and no namespace item is created. If, however, you set EXPOSE = ALL then a number of items may be created. Exactly which items these will be, is decided by rules given above. Thus, it is important to note that the value ALL does not mean all keys. The following example will create namespace items for WATERFRACTION, TEMPERATURE, MASSFLOW and GASFRACTION keys: SOURCE LABEL="SOUR-2-1", TIME=0 s, EXPOSE=ALL, PIPE="PIPE-1",\ SECTION=1, WATERFRACTION=0 -,\ GASFRACTION=-1 -, TEMPERATURE=62 C, MASSFLOW=4 kg/s All the four keys belong to the list of exposable keys for SOURCE (and they are explicitly given). The following example will create namespace items for WATERCUT, TEMPERATURE and STDFLOWRATE keys; and two warnings: SOURCE LABEL="SOUR-1-1", TIME=0 s, \ EXPOSE=(WATERCUT, TEMPERATURE, STDFLOWRATE,\ TOTALWATERFRACTION, MASSFLOW), \ PIPE="PIPE-1", SECTION=1, TEMPERATURE=62 C, \ STDFLOWRATE=1.4 MMscf/d, PHASE=GAS, WATERCUT=0.2 – The warnings concern TOTALWATERFRACTION (black in GUI) since it is not explicitly given, and MASSFLOW (gray in GUI) since it cannot be given when standard conditions are used, viz.: SOURCE: key 'TOTALWATERFRACTION' in object 'SOUR-1-1' is not user specified and will not be exposed SOURCE: key 'MASSFLOW' in object 'SOUR-1-1' is not user specified and will not be exposed Below you will find all keywords that can be used with the EXPOSE key.

3.7 Model specific commands 3.7.1 Pig Launch For each pig in the OLGA case, an OPC command item is automatically added to the server for its launching into the pipeline. The format of the command is ModuleName.ModelName.LABEL.Launch. The LABEL part is the label naming the pig. The pig is launched when the value of the OPC item is set true; when the key is actually launched, the item is reset to false by OLGA. If the pig cannot be released, probably because


Page 15

it is currently running, a message is given in the LastMessage item. Note that if two pigs enter the same section of a pipeline, OLGA will exit with an error message.

3.8 Simulator item namespace Each item has an unique name in the namespace. The name is stored in the property called ItemID. All names start with the module name; its value is taken from the key MODULENAME of keyword SERVEROPTIONS, and the default value is ‘Sim’. It is followed by a name that identifies the model, which is taken from the key MODELNAME, also under SERVEROPTIONS. Thus we have the following: Item

Name

Outputs

ModuleName.ModelName.LABEL.VARIABELNAME

Inputs

ModuleName.ModelName.LABEL.KEY

Global outputs

ModuleName.ModelName.VARIABELNAME

Global inputs

ModuleName.ModelName.KEY

Commands

ModuleName.ModelName.CommandName

Command arguments

ModuleName.ModelName.CommandName.Argument

In the case where the label does not exists, a virtual label is constructed. This is the case for SERVERDATA where the group position is used. - PIPE, SECTION: The label is constructed by a combination of the key LABEL set in the parent keyword NETWORKCOMPONENT (e.g. FLOWPATH, SEPARATOR, PIDCONTROLLER, etc.) and the value of keys PIPE and SECTION set under the SERVERDATA keyword. - POSITION: The label is given the value of key POSITION. - ABSPOSITION: The label is given by the value of key ABSPOSITION with a prefix “POS“. In the server case used to make the example below (picture shows the Matrikon OPC Explorer), ModuleName is set to ‘Toolkit’; ModelName is set to ‘ServerDemo’. We see Toolkit.ServerDemo.SIMULATIONSPEED being highlighted. This item is a global input. At the top of the listing, you see Toolkit.ServerDemo.C-1.CONTR. This item is an input related to the controller with label ‘C-1’. At the bottom you find Toolkit.ServerDemo.UPSTREAM-CHOKE.PT, which is an output item; its value is the pressure (PT) at position UPSTREAM-CHOKE. The value is a scalar, not a vector, so this is a trend variable. The item Toolkit.ServerDemo.P1.HOL is an output for the profile variable HOL in the flowpath labeled ‘P1’. You may also notice Toolkit.ServerDemo.SaveSnap and Toolkit.ServerDemo.SaveSnap.File. This is a command and its argument.


Page 16

Figure 4. OPC client connected to the OLGA OPC server, showing several types of items

Please note that the item namespace depends on how the OLGA model is specified. The OLGA OPC server does not fill the namespace with a fixed set of items. As long as the simulation of a model is repeated, and the model is unchanged, then the namespace will be the same. However, if the model is changed – delete a valve, rename a label, add another SERVERDATA keyword or remove some key names from an EXPOSE key’s argument – then the namespace will change accordingly. Note also that changes that are made by the client, while the case is running, are not recorded in the case. You must use the OLGA GUI to make a permanent change to the case. 3.8.1 Properties on the items The items in the namespace are equipped with data value, time stamp, quality, unit and description properties. The data value is shown with respect to the unit selected in the OLGA model. The time stamp is the time (UTC) that the data value was last updated on the OPC server. The quality is usually ‘good’; in principle it can become ‘uncertain’ or ‘bad’ if OLGA for some reason fails to write the value in the namespace. The additional properties on the items are ‘EU units’ and ‘Item description’, see Figure 5.


Page 17

Figure 5. Properties for output trend variable PT

The ‘EU units’ show the unit that was specified in the OLGA model; the figure shows that the pressure is somewhat above 1020 psig. The ‘Item description’ is an explanatory text string related to the item.


4.

Page 18

WORKFLOW EXAMPLE: ADDING OPC SERVER TO STANDARD OLGA CASE

In this section we demonstrate how to enable the OPC server for a standard OLGA case. We start from a simple case consisting of one flowpath with a valve. The valve is controlled by a controller that regulates the valve opening depending on the holdup in the section upstream of the valve.

4.1 Enabling the OPC server The SERVEROPTIONS keyword is used to activate the OPC server. The keyword is found in category Case Definition. Add SERVEROPTIONS to the case, and set the MODELNAME key to “ServerDemo”. Leave the rest of the keys at their default values:

Figure 6. Add SERVEROPTIONS and set MODELNAME key

The key STOPATENDTIME with value OFF causes the simulator to run until the Server Stop command is trigged or Ctrl-C is typed in the OLGA console window. If you want the case to stop at the given ENDTIME key in the INTEGRATION keyword, then set STOPATENDTIME to ON.

4.2 Configuring output variables The case consists of a flowpath labeled P1, a valve labeled CHOKE-1-1, a ESD controller labeled C-1, a position upstream of the choke labeled UPSTREAM-CHOKE and a position downstream of the choke labeled DOWNSTREAM-CHOKE. To make output variables available to the server they must be configured using the keyword SERVERDATA. This keyword is similar to TRENDDATA and PROFILEDATA, and can be thought of as a hybrid of the two.  Add the SERVERDATA keyword to the Output category under the C-1 ESD controller (see figure below). Select the CONTR output variable.  Add SERVERDATA to the Output category of the P1 flowpath, and select variable PT at positions DOWNSTREAM-CHOKE and UPSTREAM-CHOKE.  Add another SERVERDATA for the flowpath, and select variables USG and USL for positions DOWNSTREAM-CHOKE and UPSTREAM-CHOKE.  Add another SERVERDATA for the flowpath, and select variable VALVOP for valve CHOKE-1-1.


Page 19

 Add another SERVERDATA for the flowpath, and select variable HOL. SERVERDATA will automatically recognize this as a profile variable since neither pipe/section, nor position is given.  Add SERVERDATA under the global output category, and select the variables SIMTIME, TIME, HT and SPEED.

Figure 7. Adding SERVERDATA output for the ESD controller

Omitting to specify a position or pipe/section in the SERVERDATA keyword, makes OLGA interpret the variables as profile variables. As a consequence, when you specify an output variable for process equipment under a flowpath, you must also go into the Equipment section and set the relevant keyword. Otherwise, OLGA tries to interpret the variable as a profile variable, and will fail with the message “No sources specified for trend plot”. An example would be that adding GTSOUR for a SERVERDATA located under some flowpath, requires that you also set SOURCE = … .

4.3 Configuring input variables By adding input variables to the namespace, you (i.e., an OPC client) can control the OLGA simulation interactively. You add input variables by giving them as arguments to the EXPOSE key. There are a handful of keywords that have this key – among them the controllers.  Expose (create an input item) the SETPOINT of the controller by giving the EXPOSE key under the ESD controller the value of “SETPOINT” (see screenshot below).  In INTEGRATION keyword, set key EXPOSE to SIMULATIONSPEED  In NODE ‘N1’, set key EXPOSE to PRESSURE

Figure 8. Setting EXPOSE = SETPOINT for an ESDCONTROLLER. Press the (...) button in the Model Browser to open the dialogue box on the left


Page 20

Setting these three EXPOSE keys will result in the creation of three writeable input items – which will allow the client to control a setpoint, the simulation speed and the pressure in the outlet node ‘N1’ while the simulation is running.

4.4 The simulation session The case is now OPC enabled and ready to run. Start the case by clicking on the Run batch button or press F4 key. This may give some additional information about how the OPC server is being configured, and should display a message about having successfully enabled the OPC server.

Figure 9. Messages written when OLGA OPC server starts

Note that the simulation end-time is ignored in server mode when key STOPATENDTIME = OFF, so the familiar message Elapsed simulation-time is now:

0.00 S

( 0 % of simulation completed )

Is not shown, as it would never get past 0 %. Instead, a message like seen above is printed at periodically wall-clock intervals, to inform about progress of the simulation. The “Sim.time” shown is the simulation time, i.e., the wall clock time when the simulation started plus the number of seconds the simulation has reached – formatted as a date-time string. Now, you should start your OPC client, connect to the server named ‘SPT.OLGAOPCServer.7’, and add all items to the tag list. The figure below shows all the items imported in the Matrikon OPC Explorer when running OLGA on the sample case ‘server_demo_with_opc.opi’.


Page 21

Figure 10. All tags when running server_demo_with_opc.opi

You see from the list of tags that there are some items that the OLGA OPC server creates regardless of which OLGA model is being simulated. These are: 

items for commands and command arguments: -

DeleteSnap, DeleteSnap.File, DeleteSnap.EnforcePause

-

LoadSnap, LoadSnap.File, LoadSnap.EnforcePause

-

SaveSnap, SaveSnap.File, SaveSnap.EnforcePause

-

SetTime, SetTime.Time

-

Stop

-

PAUSE



a text item echoing the latest message (info/warning) that was written from the OLGA simulator: LastMessage



an input item for the initial time, as UTC value: INITTIME



an output item showing the state of the simulator as text: State

The input item INITTIME defaults to the UTC date/time when the simulation was started. In the current version it is not possible to set this value in the configuration; it can only be changed by the client. If simulator mode EXTERNAL is used, then OLGA does not start running until the external clock is stepped – which makes it possible to change the value of INITTIME before the first time-step. It may also be useful to change this value in combination when loading a snap file. Note, that you cannot run interactive simulations in the GUI with the OPC server. 4.4.1.1 Lowering the controller set-point to trigger the valve to close For the case running, the holdup is around 0.75 and the set-point for the controller is 0.8. The valve is fully open. Lowering the set-point below the current holdup will make the controller close the valve, and the holdup and pressure upstream should increase. The set-point can be changed by writing a new value to the item “Sim.ServerDemo.C-1.SETPOINT”. In the Figure


Page 22

below the set-point has been changed to 0.6. You can see the expected effects on results by plotting a trend plot of usual output variables in OLGA.

Figure 11. Changing the setpoint from 0.8 to 0.6

4.4.1.2 Saving a snap file and loading it again A snap file can be saved by writing a snap filename to the item “Sim.ServerDemo. SaveSnap.File”, and then toggling “Sim.ServerDemo.SaveSnap” to true. All commands are ‘false’ when not active, and stay ‘true’ while they are being executed. The value of “Sim.ServerDemo.LastMessage” is changed since it will echo the informative message that a snap file was saved. To load a previous simulator state, you use the LoadSnap command. Set the name of a snap file earlier saved in the item “Sim.ServerDemo.LoadSnap.File”, and toggle the “Sim.ServerDemo.LoadSnap” command to true. Watch the value of the ‘LastMessage’ item in the client. To remove old snap-files you may use the “DeleteSnap” command and its argument in the same manner as explained above. 4.4.1.3 Pausing the simulation and stopping the server When you Toggle the item “Sim.ServerDemo.PAUSE” to ‘true’, the simulation is set to a paused state. Input items and commands can still be manipulated, but the flow network is not stepped forward in time. By toggling the item to ‘false’, the simulation will continue where it left off – potentially with some new values set depending on which input items were altered during the pause. Toggling the item “Sim.ServerDemo.Stop” will take down the simulation and the OPC server. No further action will be possible on the OPC client; in fact it will lose the connection to the


Page 23

OLGA OPC server. The case may then again be configured in the OLGA GUI in the usual fashion. Please try toggling the PAUSE switch and activating the Stop command, and see what happens in the OLGA GUI and on your OPC client.


5.

REFERENCE LIST OPC Foundation 2002, OPC Data Access Custom Interface Standard 2.05a

Page 24

OLGA OPCServer Guide

Recommend Documents