Pipe-It Manaul 20130806

PIPE-IT MANUAL
Copyright 2013 Petrostreamz AS.

All rights reserved.
2013-08-06
Questions may be addressed to:
support@petrostreamz.com
Website:
http://petrostreamz.com

Table of Contents

Pipe-It Advantages ..................................................................6
Getting Started .........................................................................8
Register for an account and a license ............................................................ 8
Download Pipe-It Software ......................................................................... 10
Pipe-It Installation ..................................................................................... 11
Installed Components ................................................................................. 15
Pipe-It Preferences..................................................................................... 15
How to use Pipe-It: A small working example ..................... 20
Pipe-It Example: Launch a GAWK program .................................................. 20
Help and Documentation ...................................................... 31
Tooltip ...................................................................................................... 31
Pipe-It Help System ................................................................................... 31
Support by email ........................................................................................ 32
The main software components ........................................... 33
Introduction............................................................................................... 33
Terminology .............................................................................................. 35
Pipe-It Graphical Elements ................................................... 36
Resources .................................................................................................. 36
Program (Script) ........................................................................................ 39
Scripter Dialog Box ..................................................................................... 40
Example .................................................................................................... 40
Summary of Scripter Dialog Options ............................................................ 47
Pipe-It Projects & Sub-Projects ............................................ 51
Projects & Composites ................................................................................ 52
Composites ................................................................................................ 53
Export of Composite ................................................................................... 54
Importing .................................................................................................. 55
Sockets ..................................................................................................... 56
Socket Types ............................................................................................. 57
Runner ...................................................................................................... 59

Using Projects by multiple users .................................................................. 59
Example Pipe-It Projects ............................................................................. 60
Designing Pipe-It projects ........................................................................... 62
Pipe-It Graphical User Interface .......................................... 65
Tool Bar .................................................................................................... 66
Multiple Views ....................................................................... 71
Operating Systems ..................................................................................... 72
Interactions with Canvas ............................................................................ 73
Save As Dialog ........................................................................................... 90
Displaying the model status and results ....................................................... 91
Exporting and Importing data ..................................................................... 92
Optimizer ............................................................................... 95
Introduction and example ........................................................................... 95
Optimization .............................................................................................. 99
The Solvers ............................................................................................... 99
Solver plugin API ..................................................................................... 100
Example .................................................................................................. 101
Reference ................................................................................................ 102
Solver Parameters .................................................................................... 114
Optimization Variables .............................................................................. 117
Random Sampler Solver ........................................................................... 118
Case Matrix Solver ................................................................................... 118
Nelder-Mead Simplex-Reflection Solver ...................................................... 118
IPOPT Solver ........................................................................................... 119
NOMAD ................................................................................................... 121
The DotNumericsPlugin solvers ................................................................. 121
Linkz .................................................................................... 122
Introduction............................................................................................. 122
Linkz Window .......................................................................................... 122
Creating a new link .................................................................................. 123
Using Delimiters and Regular Expression ................................................... 126
The Optimizer Connection ........................................................................ 128
More than a single value .......................................................................... 128
MapLinkz ................................................................................................. 130
Links in Annotations ................................................................................. 131
Streamz ............................................................................... 132
Introduction............................................................................................. 132

Streamz Language Commands .................................................................. 134
Streamz GUI (Streamz Assistants) ............................................................. 136
Streamz Copier ........................................................................................ 145
Streamz Tabulator.................................................................................... 146
Streamz Separator ................................................................................... 149
Streamz Generic ...................................................................................... 150
Streamz Documentation ........................................................................... 150
Strexzel ............................................................................... 151
Strexzel Macro Commands ........................................................................ 151
Comments ............................................................................................... 152
Accumulate.............................................................................................. 152
Add Note ................................................................................................. 153
Calculate ................................................................................................. 154
Change Stream Units................................................................................ 157
Edit Component ....................................................................................... 158
Edit Variable ............................................................................................ 159
Expose Components ................................................................................. 161
Insert Component .................................................................................... 162
Insert Streams ......................................................................................... 164
Insert Variable ......................................................................................... 165
Load Characterization ............................................................................... 168
Move Component ..................................................................................... 170
Move Streams .......................................................................................... 171
Move Variable .......................................................................................... 173
Name Characterization ............................................................................. 174
Remove Columns ..................................................................................... 175
Remove Component ................................................................................. 176
Remove Streams ...................................................................................... 177
Remove Variable ...................................................................................... 178
Save Characterization ............................................................................... 179
Set Constant ............................................................................................ 180
Set Formula ............................................................................................. 181
Set Precision ............................................................................................ 185
Seed ....................................................................................................... 187
Strexzel GUI ............................................................................................ 187
Strexzel interaction with Pipe-It. ............................................................... 193
Console mode / Command line arguments ................................................. 193
Convertors ........................................................................... 195
Ecl2Str .................................................................................................... 195
Pre Ecl..................................................................................................... 197
Sen2Str ................................................................................................... 202
Script Assistant ................................................................... 206

Overview ................................................................................................. 206
Using Scripts............................................................................................ 206
Creating Scripts ....................................................................................... 207
Modifying Scripts...................................................................................... 209
Workflow ................................................................................................. 210
Detailed Description ................................................................................. 211
Plotz..................................................................................... 219
Plotz GUI ............................................................................................... 223
Help ....................................................................................................... 224
Graphical Interface and Functionality ........................................................ 228
Appendix ............................................................................. 232
Streamz Tabulation Reference .................................................................. 234
Terminology ............................................................................................ 237
Advanced Linkz trick................................................................................. 242
Interaction with 3rd party software ........................................................... 243
Getting Started with Streamz (Application) ................................................ 245
Plots on Canvas in Pipe-It projects and using "R" language ........................ 259
Pipe-It File types ...................................................................................... 262
Copyright Notice ...................................................................................... 263
Disclaimer ............................................................................................... 263

Pipe-It Manual Page 6
Pipe-It Advantages
Petrostreamzs Pipe-It is a new methodology for asset optimization
and exploitation where petroleum streams are optimized over the
whole value chain of, and within each, petroleum sector for:
maximum product value
better decisions for investments and technical solutions
cost reductions
Petroleum resources originate as static bodies of oil and gas in
underground reservoirs. As these resources are exploited, they flow as
petroleum streams into a production system. Streams are mixed and
processed, splitting into new streams. Mixing and splitting of streams
occurs throughout a labyrinth of wells, surface equipment, pipelines,
storage facilities, transportation with new mixing and products being
generated at the final refinery destination. With Pipe-It users can
manage their petroleum streams and optimize the production of
hydrocarbons.
Pipe-It has the ability to keep a detailed, quantitative upstream-to-
downstream accounting of the individual components making up
petroleum resources. This bridges the work of reservoir engineers, who
talks in terms of volumetric rates, to the processing engineers, who
talk in terms of component molar rates, and ultimately to managers
who talk in terms of currency, revenue, net present value and profit.
With Pipe-It software, a petroleum resource stream can be described
simply as crude oil and gas, or it can be quantified with the hundreds of
molecular constituents (methane, propane, , benzene, carbon dioxide,
). It also allows for every conceivable description between simple and
complex LPG, NGL, GTL products, crude oil refinery distillation cuts,
wax, asphaltenes, and mercaptons. Even monetary value in any
currency, instead of barrels.
Pipe-It allows a project to be visualized with an intuitive graphical
layout design. One visualization can be created to give a clear vision of
the project from a top-level management point-of-view, showing how
fields are connected and interact at major process facilities and export
terminals. Other visualizations detail sub-projects like a subsea well
template or a satellite process facility, always maintaining the actual
connectivity to other elements in the project. Custom visualizations of
the same Project can be made by each individual or team working on a
Project.
Pipe-It allows an entire project or elements of a project to be executed
(run). This might involve executing external computer programs
describing performance of reservoirs, wells, pipelines, process facilities,
storage and transportation vessels, and final-destination refining. Pipe-
It allows these 3rd-party programs to communicate using Pipe-Its
engine.
Not only does Pipe-It rely on computational programs for resource
streams, it allows access to measured data provided by online metering
and spot testing stored in databases. Sophisticated data management
features of the Streamz engine allows measured and calculated data to
be compared on a consistent basis in terms of quantity (mass, volume,
etc.) and time period (daily, monthly, annual). Once on a common
basis comparative stream data can be used as the basis for
optimization.
A unique technology called Linkz allows Pipe-It to "connect" to tokens
(numbers and strings) in text files irrespective of formats. These tokens
are then available to Pipe-Its execution and optimization engines and
become part of the overall optimization. This ability together with the
possibility of executing any program that can be launched from the OS
gives Pipe-It an unprecedented capability and flexibility making it an
ideal framework for integrated computational integration. No programs
are imposed on the end user (they choose which programs are best
suited for their area of expertise), but rather Pipe-It embraces all and
facilitates their integration (connected execution) and data-exchange.
Pipe-Its Optimization Interface allows (through Linkz) any number in
any file to be variables, constraints and/or objectives of an
optimization. Multiple levels of optimization can be defined and be
active in a single top level global optimization. Different solvers and
directions of optimization (MAX, MIN) can be specified for each instance
of the global or local optimization. A set of robust solvers are provided,
which can be extended by means of documented API.
Pipe-It includes a command-line version that can be called by not only
other programs (even batch files) but also by itself! This allows Pipe-It
to be embedded within any other software that can launch an OS
command-line. This also means Pipe-It can recursively call many
instances of itself from within a top-level graphical instance. This is the
basis of multi-level local and global optimization made possible by Pipe-
It.

Getting Started
Petrostreamz Pipe-It (referred to as simply Pipe-It henceforth) is a
software solution for scalable integration and optimization of petroleum
assets. With a unique graphical platform, Pipe-It intuitively integrates
complex data and model configurations typically found in our industry.
Once data and models are integrated, Pipe-It provides sensitivity
assessment and optimization capability to define business opportunities
dependent on complex cause-and-affect dependencies of revenue
opportunities and cost management. Our fundamental philosophy is
that current work flows should not be disturbed, with each application
custodian continuing to use the same software, including all utilities for
pre- and post-processing.
This document provides an introduction to the use of Pipe-It and is
meant to be a guide for understanding and using a project built by
Petrostreamz AS for clients. Other sections in this document contain
example to give the users all necessary details.
Please refer to Pipe-It Example Projects for some examples.
Petrostreamz Support department can also arrange necessary training
courses, short video tutorials or provide on-site support / consultancy
services. Please contact support@petrostreamz.com.

Register for an account and a license
To start using Pipe-It, you will need to install the Pipe-It software in
your machine. The software and a trial Pipe-It license is available upon
request.
The first step is to register to create an account. This registration is
free and only requires you to provide some information to be
considered for a three-month trial Pipe-It license. Once you get your
account, you can sign in to download the Pipe-It software.
The registration procedure:
Go to the website http://petrostreamz.com
Choose "Download" tab on the top menu.
Enter your e-mail address, for first time registration you will need to
choose "No, I'd like to register".

Click "Go to registration".
Fill-in all required information.
If you are registering to get a trial license, choose "Accept Trial License
terms".

If you or your company has already bought a commercial license,
choose "I am a Pipe-It customer and/or my company is a Pipe-It
customer already".
Click "Create new account".
Petrostreamz will send an e-mail confirming that your registration is
successful.
The approval process could take a few days. Once your account has
been approved, you will get an e-mail containing information about
how to log-in, set your password, download Pipe-It and other details.

Download Pipe-It Software
Once your account at Petrostreamz has been activated, you will receive
an email containing all the information you need to log in, set your
password, and other details.
After you log in and set your password by following the procedure
mentioned in the email, you can start to download the Pipe-It software.

How to download Pipe-It:
Log in at http://petrostreamz.com/user using your e-mail and
password.
Navigate to the download page by clicking Download at the top of the
page.

Click on the link provided to access the download area.

Once you have navigated to the download area, you can download the
Pipe-It installation file by choosing the newest version of Pipe-It Setup
(.exe). The installation packages for Mac OS X systems and Linux
systems are available on request.

Note:
On the same page you can also download Pipe-It examples and
brochures, these could help you to get familiar with Pipe-It.
Enjoy!

Pipe-It Installation
Windows Operating System
Pipe-It is distributed as a packed installation executable that is an
application installation and configuration service. This binary is an
engine for the installation, maintenance, and removal of Petrostreamz
software on modern Microsoft Windows systems.
On other systems the installation procedures might be different.
Installation packages are available for Mac OS X systems and Linux
systems (on request).

Quick Installation Guide
Here is an explanation of the installation procedure that allows you to
quickly install Pipe-It on your desktop system.

File Naming and Versioning
Petrostreamz AS provides installation binaries with the following
naming convention, for example:
Pi peI t Set up- 1. 3. 0. exe
This allows you to keep track of build number and have up-to-date
versions. You can easily compare this build ID with that of the version
currently installed, which is shown in the About dialog (About Us on the
Help menu):

Executing Pipe-It Installer
Welcome Message
The first screen that you see indicates that Pipe-It installation is
successfully started and that it will guide you through all installation
steps and choices. It also shows the build number to keep you aware of
which version you are installing:

Choose Install Location
This page allows you to check the installation path of Pipe-It and if
required change it to another one that is more convenient for your
installation. Note that this installation path is stored in the registry, so
when you run a Pipe-It installer with a new version to update Pipe-It, it
will load the previous installation path automatically. Then you only
need to check that it is correct and press the "Install" button:

Installation Progress
The page indicates installation progress, and shows you the files being
copied to your hard drive if "Show details" is clicked. Just wait few
seconds to get the software installed:

Installation Completed
Finally you get a screen that indicates that the installation is
completed. Also by default it allows you to run Pipe-It directly when the
installation is closed:

Installed Components
The Pipe-It software product includes the following components
distributed within the installer binary:
Petrostreamz components
Pipe-It.exe - Main GUI Application.
Pipe-Itc.exe - Non-GUI version of Pipe-It that can be invoked from
other programs or by Pipe-It itself!
Streamz.exe - The "Engine" of Pipe-It. Sophisticated stream
management program with track record of industry-strength projects
under its belt. See Streamz documentation for more info.
ProjectBuilder.exe - Wizard-based builder of Pipe-It project. Uses a
template (see below) designed for specific application (e.g. EclBOz) and
customizes it based on user supplied data. The Wizard displays pages
for user interaction and replaces/duplicates elements in the template to
create a ready to run Pipe-It project.
Growing set of standard conversion utilities to facilitate integration of
popular engineering software (e.g. Eclipse, Sensor)
A set of Solver for use by the Optimizer
A set of Project Builder Templates
A set of Scripter Assistant Program short-cuts.
3rd party components
Qt Libraries - DLLs to run GUI software.
UnxUtils - Set of Unix utilities built for Win32 to use in projects for
cross-platform issues. See also http://unxutils.sourceforge.net/ The
installer program appends the path in each launched instance of Pipe-it
so all these commands are available in command line.

Pipe-It Preferences
Petrostreamz Pipe-It, like most of the applications on your computer, has
a set of preferences you can customize. You use preferences to specify
things such as auto-save settings and a default folder for storing projects.
At this point it is recommended to change at least the default editor from
Notepad (on Windows) to the one you are used to. You can worry about
the others as you get more experience with using Pipe-It.
To view or change preferences:
Win: Choose Edit > Preferences
Mac: Choose Pipe-It > Preferences
Preferences are tabbed into 3 pages:
General
Text Editor
Canvas
General Preferences
The page of preferences defines settings:

Beep on project run finished - the checkbox makes Pipe-It beeping when
execution of your project is finished. By default the setting is enabled, but
you can disable it when running Optimizations and it produces several
beeps too often. Anyway this is good indication for long term executions
to attract attention.
Auto-save opened projects - the option with defined interval enables
timer to save your project after defined time from last save operation. It
saves project into model+view files, ppm and ppv with same file name as
opened project but prepended with "~". In case of power failure you have
possibility to extract lost changes to project by getting information from
auto-save files.
Text Editor Preferences
Text Editor page allows you to define default text editor for Edit Item
action for Resources. Note that it is different than double-click on
Resource which invokes Application from default system association with
this file type. Instead Right click on Resource and choosing Edit Item, or
just pressing F4 invokes association defined by this preferences page.
It can be very useful if you would like to have fast way of starting File
edition process but without changing the default association in OS to start
editor with double-click. Using F4 invokes Editor specified in Pipe-It and
allows to keep double-clicking for processing the file by some utility.

You can see that the page allows you to extend associations for several
file types. By default it provides additional association for image files to
show you example of defining new bindings to your editing applications.
Canvas Preferences
You can customize next canvas settings:

Use mouse wheel for zooming By default the mouse while (or the
trackpad found on current portable computers) is used to scroll up and
down in the canvas. This setting will allow the user to use it for zooming
in and out instead.
Reverse mouse wheel direction when use for zoom Zoom-in and Zoom-
out are swapped from the default action.
Animate connectors on Project Run - when you run your project, then
active connections (which are connected to elements that are being
processed this time) are animated by moving dots to show you which
Resources are currently used or produced by running Scripters.

Make new item selected when adding to canvas Fairly obvious.
Make green checkmarks disappear on first mouse move - When execution
of project is completed then all processed elements got checkmarks (in
right top corner) to indicate completeness of executed elements.
Checkmarks that indicates problems attracts attention to resolve situation
and start execution again. But in case of successful execution all elements
are marked with green checkmarks and not required to be kept on canvas
to continue your operations. For such case you can use the option to keep
green checkmarks until first mouse move - you definitely notice the
project state and can continue work.
It is convenient if project run time is huge and you need indication when
you return to computer to look at completeness of the execution.
Animate slow shading during Time used to fade the checkmarks.

How to use Pipe-It: A small working
example
You can use Pipe-It to "pipe" together your project from bottom-up or
top-down. Each software application being launched is called a Process.
Any file connected with a Process is called a Resource. You can chain
together as many Processes as needed using Connectors, in any order
(parallel and/or series). A collection of Processes can be grouped into a
Composite. The total collection of all Processes, Resources, and
Composites is a Pipe-It Project. An entire Pipe-It Project can be run
time-and-again with changes to any input data using the Optimizer.
The Runner orchestrates, without user intervention, intelligent and
efficient launching of all Processes in a Pipe-It Project. And by using
Linkz, any data in Resource files can be accessed and used for further
operation.
In this page, you will find a step-by-step procedure to build a very
simple Pipe-It project. This example will help you to start the
interaction with Pipe-It. A detailed description of a Pipe-It element can
be examined by clicking the referenced item (a hyperlink).

Pipe-It Example: Launch a GAWK program
In this example, we will utilize Pipe-It to launch a gawk program (
http://www.gnu.org/software/gawk/manual/gawk.html) that will
extract data from a text file. Windows version of GAWK is installed with
Pipe-It as part of UnixUtils, to facilitate execution of Pipe-It projects
across operating systems.
Open the Pipe-It software. Go to the Start menu and choose the Pipe-It
program.
Save the Pipe-It project in your preferred directory.
Go to the File menu and choose "Save" or "Save As". You could also
use the shortcut provided (Ctrl+S or Ctrl+Shift+S) to do this operation.
Note: A shortcut for an operation (if any) can be seen on the menu.

You can start building the project by adding a title or a note in the
Canvas to identify and/or give a general description of the Pipe-It
project.
Choose the text-box (Annotation) symbol in the Toolbar and place it at
the preferred location on the Canvas. Double-click to edit the
annotation text and press "OK" when finished.
You could also edit the display (Color/Line/Font etc.) by placing the
cursor on the text-box, right-click, and choose "Open Item
Properties...".


Adding a Resource to the Pipe-It project. Choose the Resource symbol
on the Toolbar, or just simply press "R", and place a Resource element
on the Canvas.

Associate a data-file (employee.txt) with the Resource.
Right click on the Resource box and choose "Set Resource File...". Find
the data-file and click "Save". Un this case you will create this file, so
just give it the suggested, or another, name.

Right-click this resource and choose to Open in Editor (or just press
F4 after selecting the resource:

Depending on your Pipe-It Preferences the empty file will open in
Notepad or your preferred text Editor. Populate it with the following
data and Save it.
00 Thomas Manager Sal es $5, 000
200 J ason Devel oper Technol ogy $5, 500
300 Sanj ay Sysadmi n Technol ogy $7, 000
400 Ni sha Manager Mar ket i ng $9, 500
500 Randy DBA Technol ogy $6, 000
This data can be copied from the website which is the source of this
example:
(http://www.thegeekstuff.com/2010/01/awk-introduction-tutorial-7-
awk-print-examples/)
Add one more Resources and associate it with the (actions.awk) using
the same procedure as above and populate it with the following:
{pr i nt ; }
Adding a Process to the Pipe-It project. Choose Process symbol on the
Toolbar and choose "Program(Script)" or just simply press "P". Place
the Process element on the Canvas.

You can rename the Process element by right-clicking on it and
selecting "Rename Element...", or just simply press F2 with the Process
element on the Canvas selected.
Connect all input resources to the process by using Connectors.
Click the Connectors symbol on the Toolbar to activate it and then
connect the preferred resource with the process element. First move
the mouse to the (actions.awk) Resource, connection points (small
white marks) should show up on the edge of the element. Left-click
once at one of the points, then move to the Process element and left-
click again at one of the connection points on that element (you can
also just click and hold the left mouse button at the connection point on
the Resource and then go to a connection point on the Process and
release the button). Now the Resource and the Process should be
connected by an arrow, going from the Resource to the Process. Do the
same for the (employee.txt) Resource.
The Pipe-It project should now look similar to this. A second annotation
(text box) has been added to provide additional information.


To be able to launch the Gawk program, we need to write a script
inside the Process element based on the Pipe-It usage of the AWK
syntax.
Double-click the process element and in the "Script" box type the
command line to invoke Gawk application.
gawk
The syntax of the awk command is actually:
gawk - f act i ons- f i l e dat a- f i l e [ > r esul t - f i l e]
Thus, inside the "Script" box we need to use the syntax above and insert
actions-file (.awk) first, then the input file and the output file.
The command line inside the "Script" window should look like:


Run the Pipe-It project by clicking the "Run Project" symbol on the
Toolbar or by using the shortcut "Ctrl+R".
A green check-mark symbol will appear on the elements if the project
runs successfully. If an error occurs, you will see a red-flag symbol on the
broken element.

Since the optional output file was not specified in this example, gawk
sends the output of the program to the standard output. Pipe-It
provides a console to capture this output from the program. To view
this console click on the View menu item and select Show Console:

A Console Window will open to show the result of the execution. In this
example since the actions file contained only the action to print, each
line will be printed on the console:

The next step in this mini-tutorial is to save the result instead to a file.
Create another Resource on the canvas and connect it as an Output to
the Process (start the connector from the Process and drive it to the
new Resource). Associate this resource to a file named result.txt:

Canvas
Console
Output of gawk
Since the syntax of gawk requires redirection operator (>) to pass
the output to a file instead of to the console, we need to modify the
Script in the Program. To enable the > to be interpreted correctly by
the operating system (Windows), the command line needs to be
processed via the command shell. The final command needed looks like
this:

Run the project again. This time the Console only logs what was done
but the result is sent to the file. In the picture below the result.txt file
is opened in Notepad to show the content.

Pipe-It offers many features to make your projects flexible, robust and
sustainable. One such feature is the use of Resource References
instead of directly coded file names (Covered in detail later in this
manual). You might want to come back to this project when you have
studied it. The screenshot below shows the content of the Process. Note
that the Script uses Resource References syntax while the parsed
command line is identical to what we saw earlier.

Before we close this project, let us try to alter the action, which is very
boring right now. Change the content of the action.awk file to (fourth
col umn cont ai ns Technol ogy) :
$4 ~/Technology/ {print;}

Resource reference syntax
Corresponding
Command line
Pipe-It uses gawk to select only lines fulfilling certain criteria and write
the results to a file. Save and close the Pipe-It project.
Congratulations! You have just created your first Pipe-It project and
run it.
This Pipe-It project example is very simple and far from what Pipe-It
can do in real application. This exercise comes with the intention to
help new users to start the basic interaction with Pipe-It.

For some real Pipe-It project examples, please refer to Pipe-It Example
Projects and on the website.

Help and Documentation
There are several ways to get help in Pipe-It, depending on the level of
help required.
Tooltip
Hypertext - short description of object in the user interface. The
description usually appears within a few seconds when the cursor is
placed over an object.

Pipe-It Help System
Pipe-It comes with a built-in help system where you can find Pipe-It
and Streamz documentation (in English). You can invoke this system
by pressing F1 or going to the Help menu in the main Pipe-It window.
Currently this PDF Pipe-It Manual is linked to the help system.

Future versions will be provided in a format similar to a web browser
that shows hypertext content with links and images. By using this
system, you can access the Pipe-It and Streamz documentation, a
panel with a list of keywords, a bookmarks panel and a search system
that allows you to easily find the content that you are interested in.

Support by email
Sending an e-mail - to the Support Department at
support@petrostreamz.com is the highest level of help and can be used
to resolve intricate problems when you are otherwise stuck.

The main software components
Introduction
This section will give a brief introduction to the software components in
the Pipe-It package.

The figure shows the main software components of the Pipe-It package.
In the figure, solid lines indicate that the program has a graphical user
interface (GUI). Dashed line indicates that the program is started from
the command line, without GUI. File type extensions of the input files
are also shown. Most of the programs write out to the same file or
same type of file.
Pipe-It
The main program with GUI.
Pipe-Itc
The command line version of Pipe-It.
Linkz
It is used to define links to individual data elements or matrices inside
files. Linkz can work with any text file and with MS Excel (binary or
xml) files. Through a GUI the user can "teach" Linkz how to find the
desired data elements. The link definitions are saved in a .ppl file.
Optimizer
A control panel to set up and start automatic iterations of executions,
using a solver. The optimizer can use links into data files defined with
Linkz.
(Solvers)
A solver contains the optimization algorithm. It is started by the
Optimizer and takes over control during optimization. A collection of
solvers is delivered with Pipe-It, most of them are in dynamic libraries
(.dll). Choice of solver is available from a menu in the Optimizer.
Runner
A part of Pipe-It that takes care of execution of the project. It is not
visible to the user. The Runner runs only the parts of a large project
that need updating according to changed data and dependencies.
Streamz
Uses .str (Stream files). It calculates combination and splitting of
collections of streams. It is both a command line program and tightly
integrated within Pipe-It.
Strexzel
A spreadsheet-like program that is specially made to do operations on
.str files, which are beyond the scope of Streamz.
Plotz
Makes graphs / plots.
MapLinkz
Copies data from one file to another by using links defined with Linkz.
It is integrated with Pipe-It and easy to use in projects in the Pipe-It
GUI.
(Converters)
A collection of utilities that can read various other file formats,
including binary files, and produce .str files.
ProjectBuilder
A utility program that can read definitions from "templates" (made by
expert users), and based on these it shows Wizard-like question pages
to the user, collects data about the new project from the user's
answers, and generates (possibly very large) Pipe-It project files as a
result.
ScriptAssistant
A utility that helps the user to set up how to use (a new) external
program (what input it needs, what output it generates etc.) from
within Pipe-It. The result is that the external program becomes
apparently integrated in Pipe-It and easier to use in a Pipe-It project.

Terminology
Unsure about what we mean? Need a one line definition of a term used on
the website? What is a Resource? A Process?
Refer to the Appendix for a collection of all technical terms in the context
of Pipe-It. Even Pipe-It is defined here! Use the search function to search
for the term.
Pipe-It Graphical Elements
Pipe-It is a unique software application that allows you to graphically
and computationally integrate models and optimize petroleum assets.
Pipe-It can launch any software application you are currently running,
on any operating system. Pipe-It chains together your applications, in
series and parallel. Pipe-It's versatile Streamz technology manages the
complex oil and gas streams processed by models making up an
integrated asset. Our fundamental philosophy is that current work flows
should not be disturbed, with each application custodian continuing to
use the same software, including all utilities for pre- and post-
processing. The main function of Pipe-It is to provide added value
through
modular & scalable integration solutions
local & global optimization capability
visual organizational functionality

Resources
Resources are representations of files on disk. The default shape is a
rounded rectangle with a pale blue color. They should usually be
renamed to something appropriate in the context of the project. They
need to be linked to the appropriate file on disk via "Set Resource file"
context-menu option. An easy way to create a new (or multiple)
resource is to drag the file from file explorer on to canvas. This creates
the resource, gives it a default name and also set the file linking in on
quick step.

Resources are connected to other processes only but never to another
resource directly.
Right click on the resource and select "Set resource file" to associate
the resource element to a physical file.

Select a file and press "save" to associate the file with the resource
element

The resource element on the canvas will be updated with the file name.

The element can be renamed to a more convenient name by pressing
F2 and typing in a new name. It will still be associated with the
selected file.
If the resource points to a stream file, a characterization name can be
associated with the stream file by pressing F3 and typing in the name.

Pressing <CTRL>+<I> will open the item properties dialog, where the
various properties can be inspected and modified. If characterizations
have been added to the project via Streamz Library
(<CTRL><SHIFT><Z>), these will be available in the Characterization
dropdown. Stream file input and output options can also be defined in
this property page.

Program (Script)
Programs are operations that modifies an upstream resource to create
a new downstream resource . The default shape is an ellipse (oval) with
a pale green color. They should usually be renamed to something
appropriate in the context of the project. They are usually connected on
the upstream and the downstream sides to resources. They can never
be connected directly to another program. The most often used
program is a generic Scripter where the user can specify any command
line for execution. A program canvas element can be created by
clicking on the "P" icon in the toolbar and dragging the ellipse on to the
canvas.

The application executable and its command line arguments is
described in the scripter properties dialog. Select the process and press
<F4> to open this dialog, or open it from the context menu.

Scripter Dialog Box
Example
The scripter command line can be explicitly entered by the user. For
example if the scripter launches the reservoir simulator SENSOR and
first argument is the input data file, the commands written into the
scripter would be:
SENSOR. exe i nput . dat
Pipe-It allows a flexible syntax to make projects and programs portable
by using reference to connected resources. The files actually connected
to those resource will then be used to make up the command line on-
the-fly at time of execution.
To illustrate this, let's set up a process for converting a stream file with
the Strexzel application, we will need an input stream file, a macro file.
When the program executes, it will produce an output file.

Let's select the program and open the scripter properties dialog. You
can do this by selecting the program and by pressing F4, or by
selecting "Open Scripter" from the context program context menu.


You get a window divided into 3 parts. The first part with the label
Script is a space for you to write the command required to launch
your program.
In the example below, we have used the Strexzel utility. A normal
command line invocation for Strexzel for opening a stream file, running
a macro file and output the result to a second stream file is:
St r exzel - m<macr o f i l e> - i <i nput st r eamf i l e> - o <out put st r eamf i l e>
First we need to type in the name of the application that we want Pipe-
It to execute when the project runs. In this case, the application name
is "Strexzel". The simplest way to populate this script area is directly
file names. However the user needs to know exactly the names of the
files (including the path relative to the current folder). Suppose the files
are located in the current folder. The following picture shows what a
Script may look like.


In this case the Script and the Command Line are identical.
However Pipe-It is designed to provide the names of the files needed as
arguments on the command line automatically, if a Resource (set to a
file) is connected to the Process using a Connector. In fact that is the
purpose of the connectors to provide Processes with files (via
Resources).
To use this flexible, and more robust, way of populating the Script you
need to use the Insert New Argument button. This results in a box
with many choices. Many of the defaults can usually be used.

You need to decide what kind of file you are currently adding as an
argument. In the case of the <macro file> argument it is an input to
Strexzel. Files (via Resources) get connected to Processes (or
Programs) at certain connection points called Sockets.
Since we have used the generic program, we will instead see a list of
generic socket types:
This displays a list of resources connected to the program via input
sockets. By default each new Process has two Sockets, an Input and an
Output Socket. This can be accessed by the Choose button in front of
the Socket choice in this window. Selecting this button would show up a
small window like:

Where clicking the button of your choice will select it and take you back
to the original window.
If the program had been created using a utility, or a user has added
more sockets, a list of recognized sockets would have been displayed.

Since we are working with a simple example with two input files and
one output files, we proceed with the default sockets and stick with I1
(First Input Socket).
We need to set the resource that will be used as the first argument. We
click on the Choose button in front of First Resource to get the
following dialog:

This dialog lists the resources that are connected to the chosen Socket
(I1 in our case) of the program. We can select the resource using
forward referencing or backward referencing indexes. In the forward
referencing scheme, an integer index is assigned to each resource. In
the backward referencing scheme an integer reference relative to the
number of resources is used. If we have three resources and want to
reference the second one using the forward referencing scheme, we will
use the index "2". If we want to use backward referencing, we will use
the index "n-1".
Backward referencing is for geeks. Normal people will use forward
references. In this example we will use forward referencing. Since we
already have the resources (with files) connected to the Program, they
show up under respective columns. We select the macro file by clicking
on its index (1) in the forward referencing column. The dialog will close
automatically after we have selected a reference.
Since this argument also needs a switch (-m) we can specify it as part
of the Bounding Text entry as shown in the figure:

This ensures that the switch is written only if the argument is written to
the command line (useful for optional arguments). When you click
Insert you get a new entry in the script.

Here we see the Script and the Command Line are not identical but the
arguments are made up of Resource References that translate to a file
argument. This is a flexible and portable way of setting up Programs in
Pipe-It that can be reused. Just pointing a Resource to a different file
can update the command line without the used having to do anything.
Following similar steps other arguments of the Script can be added to
complete the Program. It should look something like the figure below.
Remember to select the 2
nd
Resource for the Input stream file and the
Output socket for the Output stream file. Also remember to use
appropriate switch entries (-i and o) for the appropriate arguments.

Summary of Scripter Dialog Options
Field Mandatory Description Actions / dialogs
Script yes Describes an application
command line using
Pipe-It reference
syntax.
edit manually or
compose by using the
"Insert new
reference" button.
Socket yes socket name to be
inserted in reference.
This can be an input or
output socket
Edit manually or open
the "socket reference"
dialog by pressing the
"choose" button next
to the field. This
opens the socket
reference dialog
(described below).
Selecting a value in
this dialog will
populate the field.
First
resource
yes The first resource name
to be inserted in the
reference
Edit manually or open
the "resource
reference" dialog by
pressing the "choose"
button next to the
field. This opens the
resource reference
dialog (described
below). Selecting a
value in this dialog
will populate the field.
Last
resource
no This lets you select a
resource as above, but
it is only used if you
want to specify a range
of resources in the
reference. The range is
given by two indexes
using forward or
backward referencing.
same as above.
Minimum no The field "minimum"
(matches required for
insertion) indicates the
minimum number of
connected resources
that has to be active for
the program to execute.
Spin button for
increasing or
decreasing the value.
Relative /
Fixed file
path
yes Defines the reference as
a fixed path or a
relative reference
Select using radio
buttons. Defaults to
relative.
Exclude
File
Extension
no If this is selected, the
reference expansion will
exlude the file extension
Checkbox.
Parent
Directory
Only
no If this is selected, the
reference expansion will
only refer to the parent
directory for the
resource
Checkbox.
Insert yes Press this button to
insert a new reference
in the script field. The
reference will be
composed using
Button.
selected values from the
fields described above.
Error - Area to show when
Script has un references
resources/files

Working
dir
no Defines the working
directory for the
program.
Pressing the button
displays a field where
the working directory
can be defined.
Utility no Expands a list with
preconfigured utilities.
Selecting a utility from
the list will preconfigure
the contents.
The button opens the
script translation
dialog (described
below).

Notice that Pipe-It has preconfigured Program templates (utilities) for a
set of bundled applications. By using these to define a program instead
of the generic Program icon, Pipe-It will be able to provide a full set of
possible command line parameters.

Each argument in the Script is abstracted as follows
The first character in the argument specifies if the resource is
referenced as a relative or a fixed path.
"R1@I1" signifies that the resource path is relative "F1@I1" signifies that
the resource path is fixed
The second character refers to the resource index. This is used to
identify the correct resource in the case that multiple resources are
connected to a program via the same socket
"R1@I1" signifies that the resource path is relative and that we reference
the first resource
Notice that Pipe-It uses its own abstractions for representing command
line arguments. The command line switches and options are identical to
a normal command line, but the argument file references are replaced
with an alternate syntax. This syntax makes it possible for Pipe-It to
create valid program command lines by referring to its own resource
abstractions instead of referring to specific files directly. By creating a
program representation with the Strexzel utility, Pipe-It creates the
following command line for us:
St r exzel { - m" R1@I 1" } { - i "R1@I 2" } { - c " R1@I 3" } { - o " R1@O1" } {
- s " R1@O2" } { - l "R1@O3" }
This predefined command line contains all known command line
arguments for the applications.
To illustrate this, let's set up a process for converting a stream file with
the Strexzel application, we will need an input stream file, a macro file.
When the program executes, it will produce an output file.

Since Pipe-It is aware of the command line interface for Strexzel, The
command line
St r exzel { - m" R1@I 1" }{ - i " R1@I 2" }{ - c " R1@I 3" } { - o " R1@O1"
}{- s " R1@O2" } { - l "R1@O3" }
is generated automatically.
Connectors pointing to the program are interpreted as input, and
connectors pointing away from the program are interpreted as output.
Resources are referenced via input or output sockets. Sockets are
identified by type and number

Pipe-It Projects & Sub-Projects
Excel files are called spreadsheets. Powerpoint files are called
presentations. Similarly Pipe-It "files" are called projects. Pipe-It
projects consists of many component files. Not just single files like
most other applications. Pipe-It Project View (*.ppv) file store the
visual content of the project. Pipe-It Project Model (*.ppm) file is most
important and stores the logical model describing the all the elements
in the project their connections, their grouping into composites, the
files associated with each resource, the command lines of each scripter
etc. Pipe-It Project Linkz (*.ppl) file stores all the variables collected
from all text files that are part of the project, their current values and
algorithms to locate them in later runs. Pipe-It Project Streamz Library
(*.pps) files store Streamz characterizations and conversions used in
the project.
The location of these 4 files is called the root folder of the project. Most
other files mentioned under can be located anywhere on the disk.
However, to make the project portable it is recommended that all such
files are located at or under the root folder.
If the project contains optimization, one or a series of Pipe-It Project
Optimization (*.ppo) files are also present. They can be located
anywhere.
Since Pipe-It is a multiple application integration framework, allowing
the launch of many internal and external applications, a large number
of application specific files become part of the project. Many of these
files may be represented as Resources in the Pipe-It project and
become "known" to the project. Many other files just exist and are
created, read and written by applications. All files connected to
initiating resources (those that are not downstream of any process) are
also mandatory for the proper execution of the project. These files are
typically located at the root or in folders under the root.
Designing a Pipe-It project requires some planning. Simple projects
might contain only a handful of data files linked to resources and these
can live in the project root folder. But real life projects contain
hundreds if not thousands of files. It makes sense to organize these
files in a sensible folder hierarchy. The project within Pipe-It should
also follow the folder structure using composites and sub-composites as
far as possible. This helps in cloning of composites in case a new
instance of the functionality encapsulated in the composite is to be
created. Pipe-It estimates the % of files that resides within a particular
sub-folder of the project and offers to the user the possibility of
duplicating files. This is really a powerful option as all files, their
connections to resources, their Linkz variables, and all process
command lines are cloned.
Making order of the hundreds and thousand files is another reason for
collecting related files together.
Projects & Composites
Project is container for all elements of modeling processes. Of course
keeping all the elements on same canvas makes the scheme very
complex for understanding and tracking processe details. To help with
this some or all elements in a project can be organized in Sub-
Processes or Composites.
We recommend to use the term Project for meaning whole project. Also
it means a set of 4 files that defines the project - logical model + visual
model + variable links + Streamz Library (ppm + ppv + ppl + pps).
The term Composite is used for defining some part of whole project
that is organized separately from other elements. Actually composites
are small sub-projects that work in same way as other elements of
canvas.
Because Composite is actually sub-project that defines some
operations, it can also have nested composites of second level and so
on.
From this point of view, the project is tree of composites:

Or similar but top to bottom structure:

Composites
As mentioned in the section on Projects, composites are a way to make
a project easier to understand. They will compose parts of a project
together into one box for a less cluttered appearance. For example one
may make one composite for the reservoir part of the field, and one for
the processing part of the field. Each composite may also be run
individually. Project can have any amount of nested composites:

Connections from elements within a composite to elements outside (or
inside other composites) are made via Sockets that look visually unique
for each different type.

Export of Composite
It is possible to export complete composites to standalone projects by
using:

Selecting the Composite and right-clicking give this dialog. There are
two possibilities:

Save Composite as a Pipe-It Project: The data files connected to
resources are referenced at original locations. All nested elements are
carried over. But associated Linkz variables and Streamz Library are
not.
Save Composite as a Pipe-It Archive creates a complete standalone
copy of all datafiles, folders, files, Linkz variables, Streamz Library that
are specific to this composite, and nested composites. This is a
preferred way to send a complete portion of a project to someone else.
Importing
Importing composites is done Selecting the File/Import menu option
after which the typical file browser window allows you to find the ppv
file to import.

An alternate way is to drag the ppv file, like any other resource, on to
the canvas. In this case a dialog to choose insertion of resource or
import of composite is offered:

See Also
Sockets
Socket Types

Sockets
Except for connectors, every element has a number of sockets. When
you connect two elements, you actually connect an output socket from
one to an input socket on the other. Each socket has a different
purpose. Think of connecting a stereo receiver to a set of speakers. You
can't just attach your wires at random. Each speaker will have exactly
two terminals (sockets), but the receiver might have 20 or 30, all with
a different purpose. You have to connect the receiver's "Right Speaker
Positive" terminal to the positive terminal on the right-hand speaker,
and so forth.
All currently defined resources, manifolds, and distributors have exactly
two sockets -- one for input and one for output. By default, they're
named Input and Output, respectively. You're free to rename them
(except Resources), but you can't delete these sockets or add new
ones. Currently defined processes (i.e., Scripters), also start with two
sockets, Input and Output, but you can add any number of either type,
as well as rename them. Since you can define your own sockets for
each process, it's up to you to define how they're to be used and to
what they should be connected. Generally, though, if you plan to attach
resources of different types to a process, it would make sense to define
a different socket for each type of input or output.

From the contextual pop-up menu, bring up the Edit Sockets dialog for
the Scripter. There you'll see all of your sockets and be able to edit
them. You'll also see which connectors are attached to each socket and
in which order (which is also editable).
TIP: If different "types" of resources are connected to a scripter and
are to be used for different types of arguments on the command line
then it is recommended to create new sockets for each type of
connected resource, otherwise the wrong file may end up at the
position of the wrong argument.

Socket Types
All elements (except connectors) have sockets. Let's pass through
types to show what kinds of sockets can be used in appropriate items.
Resources
Resources have exactly two sockets -- one for input and one for
output:
Resource Input Socket
Resource Output Socket

Processes
Scripters also start with two sockets, Input and Output, but you can
delete either one and/or add any number of either type, as well as
rename them.
Process Input Socket
Process Output Socket

Composites
Composites can have all 4 types of sockets due to all available internal
elements:
Resource Input Socket
Resource Output Socket
Process Input Socket
Process Output Socket
Let's illustrate all possible types of sockets inside composites:

Runner
The Runner is a behind-the-scene component of Pipe-It that
orchestrates the execution of the project. It checks the status of all the
elements, if all the resources have associated files connected, and
decides the order of execution. It manages the launching of scripter
command lines to the OS and waits for their completion. It determines
the complete dependencies of the elements and keeps the elements on
hold till all the upstream elements are up to date. The runner is visually
invisible to the end user, who will only interact through the GUI.
Pipe-Itc allows running a model from a command line without invoking
the GUI at all. In such case the Pipe-It Runner is only being invoked
directly.
Runner's Project (Composite) execution logic
The rules for running composites are the following:
All active processes within the running composite, and within its
nested, active sub-composites, will be checked and run in the proper
order.
All active resources within the running composite, and within its nested,
active sub-composites, will be checked and updated in the proper
order.
All processes outside of the running composite will be considered
inactive (as will any connection to or from such a process).
All active resources outside of the running composite will be checked
and updated if attached to the running composite by a chain of active
connections that is either strictly upstream or strictly downstream.
If one wants to completely isolate a running composite from all outside
elements, the easiest way to do that is to deactivate the composite
itself (non-recursively). The composite can still be opened and run in
that state, but all outside connections will be considered inactive. This
could prove to be a useful technique for testing individual composites.
Be advised that the results might differ from those obtained by running
the complete project, however.
Using Projects by multiple users
Pipe-It allows projects to be opened by single user at same time. To
prevent inconsistency due to simultaneous modifications to project
files, there is lock file is created when user opens a project. The lock
file contains information about user and host name, time stamp of last
access (load or save) to project and PID of process.
When you try to open project being in use by another user, you will get
a warning which indicates a user name and computer, so you can
contact him directly to unlock the project and have possibility to open
and modify it.

Example Pipe-It Projects
This section gives glimpses of the showcase projects built with Pipe-It.
Both the scale (number of elements) and technical complexity and
variety of the projects are impressive.
Multi-Field Complex Fluid Integration (Statoil)
Over 11,000 Resources in this project and nearly 3500 Processes
(application launches).
Production Optimization with Assisted HM (Petrobras)
Master project that performs the production optimization.

Compositional Well Test Allocation (Equion/Ecopetrol)

Almost 1500 Resources and 750 Processes organized in 600
Composites.

Norwegian Continental Shelf Forecast (NPD)

Almost 20,000 elements covering each and every field of the NCS.
Historical data updated automatically from NPDs Fact Pages. Decline
Curve based forecast with stream management allows flexible and
simplified what-if scenarios.
Designing Pipe-It projects
Pipe-It projects consist of many components. The Pipe-It Project View
(*.ppv) file store the visual content of the project. The Pipe-It Project
Model (*.ppm) file is most important and stores the logical model
describing the all the elements in the project their connections, their
grouping into composites, the files associated with each resource, the
command lines of each scripter etc. The Pipe-It Project Linkz (*.ppl) file
stores all the variables collected from all text files that are part of the
project, their current values and algorithms to locate them in later
runs.
The location of these 3 files is called the root folder of the project. Most
other files mentioned under can be located anywhere on the disk.
However, to make the project portable it is recommended that all such
files are located at or under the root folder.
If the project contains optimization, one or a series of Pipe-It Project
Optimization (*.ppo) files are also present. They can be located
anywhere.
A complete project will also contain data files that are connected to
each resource. All files connected to initiating resources (those that are
not downstream of any process) are also mandatory for the proper
execution of the project. These files are typically located at the root or
in folders under the root.
Designing a Pipe-It project requires some planning. Simple projects
might contain only a handful of data files linked to resources and these
can live in the project root folder. But real life projects contain
hundreds if not thousands of files. It makes sense to organize these
files in a sensible folder hierarchy. The project within Pipe-It should
also follow the folder structure using composites and sub-composites as
far as possible. This helps in cloning of composites in case a new
instance of the functionality encapsulated in the composite is to be
created. Pipe-It estimates the % of files that resides within a particular
sub-folder of the project and offers to the user the possibility of
duplicating files. This is really a powerful option as all files, their
connections to resources, their Linkz variables, and all process
command lines are cloned.
Making order of the hundreds and thousand files is another reason for
collecting related files together.

Use Recycle Loops

Pipe-It runs projects in an efficient manner. Only outdated parts are
executed. All resources in the project are checked for modification
dates of files to decide which part of project should be executed. This
avoids unnecessary execution of the same Process in subsequent runs
to generate identical data.
But there may be certain instances when some identified portion of the
project should be executed each time you press Run button. For
example, imagine a project which fetches input data from some
network services (e.g. Web Services). Before processing the rest of the
project there should be a mechanism to get updated data from the
external component (Web Services) since the external component may
not be automatically updating a resource within the Pipe-It project.
A simple two-manifold recycle loop is the simplest way to achieve this.
Everything within and downstream of such a recycle loop is guaranteed
to run every time the project is run (because the loop always outdates
itself).
Caution : Using recycle loops sparingly. Using them without proper
consideration may have unexpected side-effects such as downstream
processes being executed before upstream processes.

Utility Method Dialog
In process of designing projects you may find that you use similar
script commands repeatedly. Usually they only differ in filenames and
few other arguments. To make the script writing easier and some-what
automated, rather than writing it from scratch each time, you can use
Utilities available to a default installation of Pipe-It to use templates
applicable to your project. Or create new ones.
See Script Assistant for more details.

Pipe-It Graphical User Interface
The Pipe-It graphical user interface offers easy access to functions for
creating, maintaining and executing Pipe-It projects. Diagrams,
describing resources, processes and their dependencies can be created
by manipulating graphical elements in the canvas window. Resources
(files/data) can be connected to processes (applications) via input and
output sockets. Processes and resources can be grouped and labeled as
composites, that can be executed by Pipe-It.
Data, or fragments of data in resources can be tagged and linked using
Linkz. This enables Pipe-It to select specific data elements from project
files and feed these to one of available optimizer plugins. Or transfer
them from one file to another using MapLinkz.
Pipe-It projects are hierarchical in nature and can be viewed as a tree
structure in the Pipe-It explorer window (left). Clicking on an item in
the explorer will highlight the corresponding graphical element in the
canvas.
After creating project structure and links to data, a project can then be
executed and optimized. The built in runner schedules processes
execution and determines from the dependencies and the state of the
resources when a given process is allowed to start. Project execution
involves running applications that are external to Pipe-It as well as
internal Pipe-It components. Textual output from the runner and these
applications is shown in the console output window (usually bottom).


Tool Bar
Application Tool Bar consists of 3 main sections:

Now describe all available actions in the tool bar:
File Operations

This section has 3 main standard file actions as:
Create New Project
Open Project from disk
Save Project
Note that Open Icon has small arrow in right bottom corner. If the
Open icon is pressed and held for one second then a drop-down menu
appears with list of recently opened projects.

Navigation, Selection and Zoom

First 3 buttons (greyed out in picture above) allow navigation through
currently opened composites. Back and Forward work in same way
as navigation buttons in a web browser. Up button changes view to
upper-level parent composite. All these buttons can be pressed and
held for one second to get list of history entries or, in case of Up
button, for list of all parents of current composite.
Next 3 buttons Select, Zoom In and Zoom Out manage the current
mouse cursor mode.
Select allows selection, resizing, moving etc. canvas actions on mouse
click. This is the most common mode of operation.
Zoom In on click to canvas changes the zoom level for +10%
Zoom Out on click to canvas changes the zoom level for -10%
When Zoom In or Zoom Out is selected, then holding Alt (on Mac:
Option) button temporally switch to opposite zoom action.
Also in Zoom In or Zoom Out, area selection on canvas switches view
to Zoom-To-Fit the selection area into view:

Next to it is the, 1:1 button. It is not a mode button, it just switches
current view to un-zoomed (1:1) scale or in other words to 100%
scale.
Finally, Last button in the tool bar is Zoom-To-Fit action with drop-
down menu. Just pressing the button switch zoom level to fit all your
presented canvas elements in current view. It has drop-down menu to
apply Zoom-To-Fit to:
Current Window - Ctrl+9
Zoom-to-Fit Canvas - Ctrl+6
Elements to insert and Run

The toolbar contains 6 buttons which to add elements to the Canvas.
The behavior of these buttons can be summarized as click-and-click.
This means the button should be click once on the tool bar and then
the location on the Canvas should be clicked where that element should
be placed.
Double clicking for continuous insertion mode
You may also double click on buttons on the tool bar. This will turn on
the tool until you choose another one. This will prove practical if you
want to add more than one element of the same type to the canvas.
For example if you have lot of connectors to make, just double click
and make all your connectors as you want them to be, without having
to turn the connector tool on for each one.
Insert Resource
This button means adding a Resource to canvas. The resource
object represents a file on disk. Though you can give a several name to
the resource without a connection to actual used file name of the
associated file on disk.
On canvas the object looks like:

First double-click on the object opens Select File Dialog to associate a
file with the object. A double-click on the object, that already has
association, runs OS defined default Application associated with the file.
For example, clicking on a resource with associated "text.txt" file, will
open Notepad.exe
Also you can just drag-and-drop from Window Explorer to Canvas a file
object. It will create a Resource automatically, associate the file to
resource object and renames the resource it to File Name of dropped
file.
Insert Scripter
This button means adding a Program (Script) to canvas. The
scripter object represents an application to execute.
On canvas the object looks in such way:

Double-click on the object opens Edit Script Dialog.
Sub-menu associated with the button allows to change default action to
insert other elements that are bound to Program category.

Insert Manifold, Distributor and Sockets
This button means adding a Manifold to canvas. Manifold gather
information from multiple resources into one visual connector.
Sub-menu associated with the button allows adding other type of
similar elements Distributors, Input/Output Resourse/Process
Sockets.

Insert Composite
This button means adding a Composite (Sub-Project) to canvas.
On canvas the object looks in such way:

Look at Composites? and Socket types? pages for more details.
Insert Annotation

The next button allows placement of new connectors between
resources and processes.
Insert Annotation
This button means adding a object with text or image that does not
play role in logic but can represent some illustration, information or
instructions for the project.
Undo Button
provides fast way to revert your changes one step at a time.
Group of Run actions

The section has 3 buttons that allows you control running of current
composite or the entire project.
Run. Clicking this button commences the execution of the current
composite, or the entire project if the top level Canvas was in focus.
The run button changes into a Stop ( ) button allowing the user to
halt the execution if needed.
Refresh. Cleans the run status indicators that appear on Elements
during and after execution.
Optimizer. The wizard button invokes the Optimizer window for
repeated executions of the current (and lower level) composites.
Multiple Views
Pipe-It is used to visually connect the different components of a
petroleum asset together. Pipe-It controls the flow of petroleum
components from the reservoir to the point of sales. The logical model
connection between all the components in the petroleum asset is stored
as Pipe-It ppm (model) files. Each user may have independent visual
representations of the model stored as ppv (view) files. Each project
consists of one ppmodel file and one/multiple ppview files as well as
the project related data files.
Main Window
Pipe-It Application implements Multiple Document Interface (MDI),
whose windows reside under a single parent window

Operating Systems
Pipe-It is written in C++ using the Qt toolkit from Trolltech. Hence the
product is developed in a cross platform environment and made
commercially available for the following operating system platforms:
Microsoft Windows 32-bit (runs on XP/Vista/Win 7)
MacOS (Beta)
Linux : Red Hat Enterprise Linux (RHEL 6.4) Beta.


Interactions with Canvas
Adding new Elements to Canvas
Insert Menu items and corresponding toolbar icons are typically used to
insert new elements like resources, processes and connectors. To add
multiple instances double-clicking the icon allows repeated additions on
the canvas. Every subsequent click adds an instance of the element
currently chosen. To come out of this mode use the ESC key.
Connectors are invoked in similar fashion from the Insert menu item or
toolbar Icon, but one needs to move the mouse to the source element
first (resource or process) when the element comes alive and shows its
socket dock positions. The nearest dock becomes enlarged and the user
chooses it by clicking (and releasing) the mouse button. The start of
the connector is set and then the user moves to the destination
element and repeats the procedure to set the end of the connector.
NOTE that connections between resource-resource and process-process
pairs are prohibited and the GUI will not allow it (the wrong element
does not expose its socket dock positions).
Selecting, Moving and Resizing
Selecting a single element is simple - just click on it. Selecting multiple
elements can be done by shift-clicking and/or ctrl-clicking on the
additional items. Also a rubber-band selection can be obtained by
enclosing the required element by means of the mouse within a
rectangle. The selected element(s) become visually highlighted.
Moving an element is by moving the currently selected element while
keeping the mouse button pressed. If multiple elements are selected
they will all move. If two elements are connected and one of them is
moved, the appropriate end of the connector moves too.
Align, resize and Z-order
Resizing of individual elements are done by dragging the "handles" in
appropriate direction. More advances alignment, resizing and Z-order of
multiple elements are controlled by the Layout menu item.
Layout menu

All these options are about appearance of your project. One can align
the elements chosen in many different ways, including the most used,
horizontally or vertically.
Under the resize option one can make two or more elements the same
size, same width, height. One may also distribute them horizontally or
vertically for a clean look. (This option sets the distance between
elements the same).
The Z-order option is only useful if you have overlapping elements.
Then you can bring an element to the front or to the back of the
canvas. If you have more than two elements on top of each other, the
two last options under Z-order is useful, to alter the order of the
overlapping elements.
Alignment & distribution is also possible by the context (right-click)
menu:

Grouping Elements into Composites
See Also
Item Properties
Item Collections
Double Clicking
Context Menu
Item Properties Dialog
Item properties are available by making Right-button click on selected
items, or by Keyboard shortcut - Ctrl+I (Mac: Cmd+I). Also it is
accessible from
Edit > Item Properties...
The action shows tabbed interface for all properties of current or
selected item(s) such as names, visual properties etc.

Now you can see it in details on the image. Left side contains list of
available Elements in current Collection. You can select items which you
would like to apply properties changes to by mouse or using Collection
Presets button at bottom.
See Also: Collection Presets
Now we can consider all tabbed properties:
Basic
This page has Name and Comments properties. Note that Name is
unique identifier so if you enter same identifier as already presented in
current composite, the dialog will not accept it.

Display

Display page contains all settings related how Element is shown on
canvas. It can be grouped by next sections:
Shape Geometry
Here you can apply geometry changes and select shape type you would
like to use for the item.
Ellipse
Rectangle
Rounded Rectangle
(for last case property rounding % is available)
Line Style
If the Element is Connector then the section means properties of the
line. In case of shapes the section provides properties of border line of
these shapes.
Color Fill
The section allows to change way how the element is filled by color.
You can apply different types of gradient with color selection of begin
and end points gradient. Also you can make your elements transparent
by selecting appropriate Transparency property in color selection.
Text Properties
Here you can change font, alignment and text positioning around shape
(inside / outside)
Image
The page allows to assign picture to the Element and change such
properties image placing as scaling, wrapping text and alignments.

Model
Model page has logic properties of project model depending of type of
Element,
For example, in case of Resource they are File and Characterization file.
Additionally if the resource is a Stream file resource, StreamFile Input
and Output Options may be entered here.

If the Element is Scripter, then page has same interface as dialog for
editing scripts.
Composites have settings to select Parallel or Sequential Execution.


Collection Pre-sets and User-defined sets
Pipe-It has a powerful feature to set up virtual collections of graphical
elements that may span multiple composites in a project. Once
invoked, such collections can be used with item properties dialog to
similar settings to all elements in the collection using Apply to All
(wherever available).
First possibility is to use the tree view icon hidden in the bottom left
corner of the Pipe-It interface.
Clicking bring up the panel on the left. To hide it again click the cross
as shown.

Another way to show and hide the Sidebar is to use the View Menu:

Once the Sidebar is open, it shows the pre-set called Current View
Shapes. This means all the graphical items on the current viewed
Canvas (excluding connectors) will be part of the collection. Other pre-
defined pre-sets are shown below. Note that presets with Items instead
of Shapes will include Connectors in addition. These are usually not so
interesting.

The most interesting item on the list is Add new Preset. This will
essentially allow you to perform the task of Filtering that was available
in earlier version, but at the same time is more flexible.

In the above sequence I started with Add a new Preset. This gives me
the view on the left. I then:
remove the Items I do not need (everything except the Resources)
click on the send drop-down (called None) to select Resource File and
in the filter Criteria drop-down I select ends with.
In the empty field I write str.
The Display will update to that shown on the right side, and I can give
it a name (e.g. STR resources) and save the preset. Effectively what I
have done is to create a collection in the Sidebar that shows all the
Resources in the entire project that have connections to a file that ends
with the str extension. When I click the items of the collection Pipe-It
navigatees to the canvas containing the item and selects it.

Once created the user-defined Presets are also available, together with
the defualt ones, in the Item Properties. This is a powerful means to
collect, for example:
Resources with a particular characterization set and apply another
characterization to all in the collection.
Annotations in all projects and apply Fill & Line color to all in the
collection.

Double clicking behavior
Double clicking behavior changes with object being double-clicked and
the number of such objects.
Resources
Double clicking Resources launches the operating system (OS)
association for the file type. It is very convenient if you have defined
association to process the file or you have Text Editor bound to the file
type.
Remember that with F4 or Context Menu > Edit Item you can open the
resource file in the editor of your preference.
See Also: Text Editor Preferences for details about defining default Text
Editor
Scripters
Double clicking Scripter Processes opens Edit Script dialog
Composites
Double clicking the Composite leads you into the composite itself.
Composite Sockets
Double clicking the composite Socket opens a menu that allows you to
navigate to parent composite or connected Resources or Scripters to
locate them:

If there is a single item the socket is connected to, it directly navigates
to that item.
Other Elements
Double clicking all other elements on the canvas leads you into the
item properties. If you try to double click the canvas nothing will
happen.

Right-click Context Menu
The right click menu is available when you right click on the canvas or
when you right click on an element on the canvas. The options not
available for a particular element are grayed out. The menu will give
you different opportunities explained below.

Right-click on the Canvas allows one to Navigate (if relevant), Paste /
Clone if relevant, Go to Item Properties for the Canvas, adjust Canvas
Settings. Show Project in Explorer with open the Windows Explorer
(Finder in Mac) and locate the project model (ppm) file. This is very
useful for dragging files into the project as resrouces.
The Set Modified Status will set the out-of-date status of each element
on the Canvas so that Pipe-It is forced to execute them, and thus any
connected downstream elements, to bring them up to date.
Right-click on Resource

Open
Context menu provides options for opening the item in several ways
Open in OS (Resources only)
This item runs the OS association for the File which is assigned to the
Resource. You can specify the association in your operating system
preferences or in your favorite file manager like Total Commander.
Open Editor (Resources only)
This one will run application which is set as Editor for the type of File
which is assigned to the Resource. By default this is notepad window
application (or TextEdit for Mac) and paint for image files. You can
easily change these settings in the Preferences Window, Text Editor tab
(you can access it with menu -> Edit -> Preferences...) Remember that
you have keyboard shortcut F4 for the item.
Open in Linkz (Resources only)
Linkz has own file viewer optimized for showing and navigating huge
files for defining links to values encoded in these files. This menu item
provide fast access to the Linkz File Viewer to define new links or edit
existing ones.
Open Linzk Values (Resources only)
For files which have already defined links to some values, the menu
item shows you simple form for editing these values:

White Save button new changed values are written to the file.
See also: Linkz
Open Item properties
When you choose this option a menu will appear. On the left in the
menu you may pick the elements you want to alter, either by picking
them manually, or by using the filtering function.
See Item Properties for details
Create composite from Selection, and elevate to parent level
The function Create composite from Selection wraps all that you have
selected together into a composite. If things are connected, it takes
care of the manifolds and distributors for connecting the elements
inside the composites to the elements outside.
If you choose elevate to parent level, it will move the element you right
clicked on up one level in the hierarchy.
You can also just pick an element and drag it into a composite element
if you want to. The software will take care of the connections for you,
but you may want to change the appearance to make it look the way
you want.
Edit sockets (Scripters, Composites)
Here you can see what the different elements are connected with
(Connector names). This can be useful when you have elements inside
a composite connected to another element outside the composite. Also
you will get a question about this if you have one resource outside a
composite, and two input sockets inside the composite. If you then
make a connector from the resource to the composite, you will be
asked to which socket you want the resource to be connected.
Rename item
This gives you the opportunity to rename the element.
Set Resource file
Here one may associate a resource to its originating source of
information. This is typically a text file. This option is only available for
the resource element.
Set Characterization
Although this will be shown for all resources this is relevant only to
stream file resources that will participate in Streamz Processes. Once
invoked the database of characterizations in the Streamz Library are
offered for selection.
Show Resource in Explorer
This option could be useful in case one might want to open the linked
file with another application than the one used while double-clicking.
For example .str files are associated with Strexzel but if the user would
like to open it with Excel on a special occasion this option could be used
to locate the file in the Explorer and the use Windows Open With
context menu item.
Set Script Command
This option is only available for a Scripter. This allows the specification
of the script to be executed when this process is launched by the
runner. This is done by setting the command in the box that appears
when ones choose the Set script command option.
For utilities provided with Pipe-It there is another, maybe simpler way
to set this command. Choose the option Item properties by right-
clicking on the process and click the Model tab. Here a button called
Open Utility Editor appears. Click on that and one may choose the
most used utilities. This way much of the work writing the script
command is done automatically, but it is only an option for the utilities
included with the software.
See Using Utility Method for details
Enable, Disable and Set Modified Status
Enable let you enable an element that you previously have disabled.
Disabling an element can be done if one does not want it to be included
in the project execution at run time. Although visually the element is
part of the project the runner will exclude it when determining the
execution order and that actual run.
Pipe-It keeps track of the up-to-date status of each and every
element and runs only those that are not up-to-date. This could be
critical in huge projects with large run times of individual parts. Set
Modified Status is an option that is used to force the model to be rerun
from a specific point. Even though a resource is up-to-date the user
can force Pipe-It to include the resource in the run.
Canvas Settings
To view or change settings of canvas of current composite:
Choose Edit > Canvas Settings
The dialog allows to change canvas size using predefined sizes and
select the way of filling background of canvas. By default all new
projects get Petrostreamz background image.

You can fill background with color or image which can fill canvas in next
3 ways:
Single Image + you can define position on canvas
Scaled to fill whole canvas
Tiled
Browse button allows to select image from Project images.
By checking Save as default for new projects your new settings will be
saved as default for all new project you will create in Pipe-It next time.

Save As Dialog
Pipe-It projects consist of two files which define logic and view. Logic is
defined in ppm file. View in ppv. Ppv is the main file for user
interaction. Users double-click (or drag-drop) this file for opening a
Pipe-It project. When the project is saved with a name .ppv is the
extension. Behind the scenes corresponding .ppm files (& .ppl / .pps if
needed) will be saved.

Remember that Save As stores only model and view files and do not do
anything regarding files bound to Resources. So if you save your
project under another location, you have to copy all supplementary
files.
One way to copy all files bound to resources is to save as a Pipe-It
Project Archive:

Displaying the model status and results
Once the model is built and the end user pushes the run button, Pipe-
It will validate the model and return with visual element describing the
status of the model. Each resource and process will initially be marked
with a (light bulb) indication that the elements status is pending.
- means that the Element is under processing now or pending
processing.
- execution of the Element completed OK.
- Element is broken due to problem in execution.
- processing of the Element is incomplete.
Once the model starts processing the individual elements, the element
will either turn the status to OK with a (green tick mark), or if some
problem has been encountered, show a (red flag ). Notice that the
status of the elements will be updated in the Pipe-It Explorer (Tree
View) as well.
While running the model, the Runner will output text to the Pipe-It
Standard Output (Console) window. Any error or warning messages will
be displayed in this window. The Pipe-It Standard Output window will
be refreshed for each run and the end user is urged to copy and paste
the results into an editor, or save as a date-time-stamped log file to
compare the output from two consecutive runs.

Exporting and Importing data
Exporting the Canvas
Exporting the current Canvas as an image is as simple as selecting all
items (Edit/Select All or Ctrl-A) and pasting in the target application:

Exporting ZIP Package
As explained in an earlier section one can use the File/SaveAs menu
item to export the complete package as a zip file including all folder
structure and all files that have been connected to resources. This is a
wonderful way to package your project for sending out or exchanging
with your co-workers. All files in the project root folder are included but
only those files that have resources in the project are included.
To use it profitably, users should try to always have a resource
representation to any file that is important to the project. i.e. there
should not be any "hidden" file.
Importing data
Use File > Import menu
Import Composite provides way to import separate project as
composite into current canvas. It allows to exchange parts beetween
projects using Export/Import? Composite features.
Import Composite opens Open PPV File dialog which allows to locate
ppv file and loads it as Composite object into current canvas. The
composite is inserted into top-left corner of canvas.

A second way to import a Composite is to just drag the .ppv file onto
the Canvas from the Explorer window. A choice is offered to Insert a
Resource or Import a Composite.

Optimizer
Introduction and example
The Optimizer is the interface for multiple launches of an entire Pipe-It
project (or subset / composite of a project) in an optimization context.
It acts as a GUI control panel where it is possible to run the Pipe-It
project automatically over and over again in a sequence of iterations
utilizing a solver, or in single runs without solver, but still collecting
History data. Optimization is also possible through Pipe-Itc, which runs
from the command line without a GUI.
The purpose of optimization would typically be to let the computer find
a combination of values of some selected input variables which
optimize a specified output variable. The output to be optimized could
be for example the amount of oil, the value in USD, or something else
that the user has specified.
Example
As a first example, to get to know the appearance of the optimizer and
how to use it, we shall make an example to minimize the value of a
function f(x,y) of two variables. Note that there is no Pipe-It project
model with simulations involved in this simple example, only the
function defined in the optimizer:
f(x,y) = (x-1)
2
+ (y-0.5)
2

By inspection we can easily see that the solution is x = 1, y = 0.5,
which gives the minimum value of f = 0.
Now start Pipe-It (not shown).


Press the + button to add new variables. Add three variables.

Double click on the variable names and write the names. Double click
and select the variable role from a drop-down list. OBJ means objective
function (which is to be optimized).


The lower and upper bounds that we write here are the bounds that the
solver must stay within when it sets values for the decision variables.
We have written that the solver must stay within [-2,4] for both
variables in this example.

Select the solver that will be doing the optimization.
Now save the ppo file (not shown).

Push the Optimize button. This hands the execution control of the
optimization over to the solver. Note that model execution in this
simple example is just that the optimizer will evaluate the expression
for f.

It found the solution x = 1, y = 0.5. The minimum value of f ~ 0.
Optimization

Schematic which shows informally some of the data and execution flow
during optimization. The execution goes around and around in
iterations.
During optimization, the algorithm and execution is controlled by the
solver. Briefly explained, for each iteration the solver determines values
for the decision variables and sets the values into the optimizer. The
optimizer / Pipe-It calculates auxiliary variables, writes data to files
utilizing Linkz, executes the Pipe-It project, reads data from files
utilizing Linkz, calculates more auxiliary variables and the objective and
makes the values available to the solver. Then the solver uses the
results in its solution algorithm and may start a new iteration with
different values for the decision variables.
More information about this and the roles of the different variables can
be found on the Optimization Variables page.
The Solvers
The execution of the numerical solver algorithm is done by a solver.
Pipe-It offers a collection of different solvers that the user can choose
from.

Drop-down menu for selection of solver. The figure shows the solvers
that are currently provided with Pipe-It. Most of them are implemented
in dynamic libraries (*.dll on Windows). The solver libraries are also
known as solver plugins in the Pipe-It context. It is possible to add new
solvers to Pipe-It by placing such plugin files in the Solvers folder in the
Pipe-It installation folder. They will then immediately become available
through this menu for use in Pipe-It. Note also that there can be more
than one solver in each plugin (e.g., in DotNumericsPlugin.dll there are
three solvers).
The user can select which solver to use. The solver selection is saved in
the ppo file. The solvers are documented in more detail here.
Case Matrix
Dot Numerics
Simplex
Truncated Newton
L-BFGS-B
IPOPT
NOMAD
Random Sampler
Reflection
Solver plugin API
Pipe-It has an open Application Programming Interface (API) for solver
plugins, which makes it possible for anyone to make their own solver
plugins. The API is documented in detail in separate documents. As
mentioned, when a plugin is placed in the Solvers folder in the Pipe-It
folder, it becomes available immediately for use in Pipe-It. So,
implementing a new solver and making it available for use in Pipe-it
can be done without modifying the source code of Pipe-It.

Example

A more realistic optimizer case. Some things to notice: Only three of all
the auxiliary variables have constraints switched on. Those that are off
have had their cells for Lower and Upper emptied by the user and
grayed out. VARs can not have expressions (grayed out cells), while
CONs can not have expressions if they are connected to a link.
Equation expressions are not shown in their entirety due to small cells,
but by double clicking, they will be shown in the expression editor. In
the Link column are listed the names of links defined in Linkz, which
the variables are connected to. There are no links to arrays, so the [i]
column is empty. Location shows the filenames of the data that are
linked to. The case is set up to maximize the Net Present Value.
Variable 3 has constraints switched on. Due to its Role it will be
calculated before the Pipe-It model execution. If it is calculated to be
outside one of the bounds (i.e., violate the constraint), the model will
be executed anyway because it is not until after the model execution in
each iteration that the solver gets to know about the constraints
violation.
Be aware of:
There are some rules that determine whether a link is read from or
written to file.
Evaluation order
sequentially, from top to bottom, not like in a spreadsheet
evaluation groups
See the Optimization Variables page for more details.
Reference

Overview of the Optimizer GUI. The parts listed on the left side of the
figure are documented below, in a top to bottom sequence.

Menus

This is the main menu of the Optimizer window. The submenu items
are explained below.

New
Closes any previously open ppo file, clears everything and makes the
Optimizer window ready to receive input to define a new ppo file.
Open
Opens a file dialog box to select a ppo file to open.
Open Recent >
It keeps a list of recently opened files to make it faster to open one of
them.
Close
Closes the optimizer window, but the ppo file is not closed.
Save
Saves the ppo file. Note that the run History is also saved in the same
ppo file. For unsaved files, it behaves like Save As...
TIP: If the user has done a lot of runs and does not want to save the
run History (to a potentially large ppo file), select Edit / Clear History
before saving.
Save As
Opens a file dialog box to let the user decide the filename and the
folder to be saved to.
Save and Plot
First saves the ppo file, and then starts the Plotz application which
reads input from the ppo file.
Revert to Saved
If the user confirms in a dialog box, it discards the current edit state of
the ppo file and reads the file in again from the disk.
Quit
Quits (exits) the Optimizer and Pipe-It.

Undo
Undoes last action in the Optimizer GUI.
Redo
Redoes last action that was undone.
Cut
(The Cut action is now not activated.)
Copy
Copies the selected data to the clipboard. It works on both single cells
and whole rows (variables).
Paste
Pastes data from the clipboard. It works on both single cells and whole
rows (variables). If a variable is pasted, it is given a new name
automatically. There are limitations on what can be pasted, depending
on where it is to be pasted and the data content.
Delete
To delete one or more variables, select whole rows at the left edge of
the table and then select Edit / Delete or push the 'Minus' button.
Select All
Selects all the variables in the table.
Move Selected Variables Up
The rows (variables) that have been selected in the table are moved up
one line.
Move Selected Variables Down
The rows (variables) that have been selected in the table are moved
down one line.
Clear History
Clears the run History.

Add Decision Variable
Adds a new VAR at the bottom of the table.
Add Auxiliary Variable
Adds a new auxiliary variable at the bottom of the table. Two levels of
sub-menus open up. The first is to let the user select whether the
variable is to be evaluated before or after the model execution, the
second is to select whether the variable will have the Constraints
setting switched on or off.
Add Objective
Adds a new objective function/variable. Note that there can be only one
(active) OBJ when optimization is started. In the case of multiple OBJs,
which one to be active can be selected on Toolbar 2 or set manually in
the leftmost column of the table.
Add Derivative
Sub-menus open up to guide the user to define partial derivatives of
variables with constraints (including the OBJ) with respect to all the
decision variables.

This menu shows the list of available solvers, which is the same list as
in the Active Solver drop-down menu.

Optimize
Hands the execution control over to the solver. The solver will then try
to optimize by going through a sequence of iterations. Note that the
current composite of the Pipe-It project is executed, which is not
necessarily the whole project if the user has opened a composite in the
main window.
Run Model Once (without solver)
This is similar to executing one iteration of an optimization, except that
there is no solver involved. Just as for optimizations, the current
composite of the Pipe-It project is executed, and a history record is
appended to the History.
Note that Run Once from the Optimizer is different from pressing Run
Project in the Pipe-It main window. The latter will not use anything
from the setup (variables, links etc.) in the Optimizer and will not
append a record to the History.
Stop
Stops optimization.
Stop after current iteration
Finishes the current iteration and then stops the optimization.
Keep History
This setting is on by default and means that the History is appended to
for each new optimization or Run Once. If the setting is off, the History
will be cleared first, deleting all the records from previous
optimizations.
Save between iterations
This setting means that the ppo file is saved after each iteration. This
can be useful if one wants to monitor progress in the ppo file with some
monitoring program, or to ensure that most of the work will be saved
anyway if an execution error should occur. It will slow down the overall
execution somewhat.
Solver Parameters
Opens a Solver Parameters window. (See explanation in that page.)

Precision
Opens a dialog box to set the display precision of numbers (Lower,
Value, Upper) in the table. This setting affects only the display in the
GUI, not the values stored internally, used in calculations or saved to
file.

The window menu is identical to the Window menu in the main window.

The help menu is identical to the Help menu in the main window.

Toolbar 1

This is the first Optimizer toolbar. Many of these items are duplicating
the functionality in the menus; in those cases there is a link to the
explanation. The toolbar can be hidden by right-clicking on the toolbar,
or the menu at the top, and unchecking Optimizer.
New, Open, Save, Undo, Redo,
Linkz
Open the Linkz tool.
History
Open the History window of the optimizer, which shows the results of
model executions, i.e., the values of the variables stored for each
optimization iteration.
Note 1: When a ppo file is saved, the history is automatically saved in
the same file.
Note 2: The history can be cleared by selecting Edit / Clear History in
the Optimizer or pushing the Clear History button in the History
window.
Active Solver
This box shows which solver has been selected as the active solver to
be used in subsequent optimizations. The box can be opened as a drop-
down menu.
RunOnce, Optimize.

Composite information

This is a new item introduced in Pipe-It version 1.3.0. It might not be
shown in other screenshots. Its purpose is to draw the users attention,
when they are working with the Optimizer window, to the actual
Composite (or Top Level Project) that is in focus and will be executed
when the Run Once or Optimize button is clicked. This will help prevent
launch of the wrong part of the project since the Canvas might be
hidden or minimized.
Columns

Active: The variables with a checkmark are active. If switched off, the
variable will be inactive, grayed out, and invisible to the solver.
However, the (constant) value of inactive variables are still available in
formulae (expressions, equations) where they might be used.
Name: The name of each variable. The names must be unique.
Role: See the Optimization Variables page.
Constraints: When this option is checked on, two constraints are
presented to the solver: Lower <= Value and Value <= Upper. When
this option is off, the variable is invisible (non-existent) to the solver.
Note: The state of this selection has an impact on Lower and Upper
columns. When 'constraints' is off, the Lower and Upper are allowed to
be empty (not even showing 0). When 'constraints' is on, Lower and
Upper should not be empty. If they are, then color and a message will
indicate to the user that a value must be given.
Type: real or int (integer), can be selected by double-clicking and
choosing the Type from a drop-down menu.
Lower: Lower bound for decision variables and constraints.
Value: Value either set by the user, set by the solver, calculated or
read from file via Linkz. When a variable is referenced by its name, this
is the value that is substituted where applicable.
Upper: Upper bound for decision variables and constraints.
Equation: Expression using variable names and arithmetic. There is
also a number of different functions available for use in the expression.
See the Optimization Variables section for detailed description of how
the variables of the different roles are evaluated by the optimizer
during runs.
Link: Link defined with Linkz.
[i:] Array index in Linkz.
@: @-sign.
Location: Location (file) of the link defined in Linkz.
Column selection: Pressing this little icon opens a menu to select which
columns are to be visible or hidden. The setting is saved automatically.
Column widths can be adjusted by dragging the heading separators.
The column widths setting is saved automatically.

Table
The table (see picture) shows the variables, one variable at each row.
Each Role has its own background color. It is possible to select several
rows by clicking and dragging in the vertical header (the line numbers
on the left side), and several cells can be selected within the table. By
holding down Ctrl, cells can be selected and deselected, thereby adding
and removing cells in a selection. Clicking outside of a selected area
changes the selection to that single cell, and the work continues on that
cell. There are some different context menus available by right-clicking.
Some cells must be double-clicked to be edited, others can be edited
by writing directly. For numeric values, tool-tips (let the mouse pointer
hover on a cell) will show the full stored precision of the number. There
are tool-tips on various other columns as well.
All operations, except Hide, done on elements in the table are covered
by Undo and Redo. There is one limitation to the undo completeness:
Values in the Value column produced by optimization or Run Once are
not covered by undo. This means that Undo will recover the second last
user edited value, and subsequent Redo will recover the last user
edited value, not the execution result.
If Lower is greater than Upper, the numbers will be shown in red color.
If Value is out of bounds [Lower, Upper], it will be shown in red color.

Context menus

Context menus appear after right-clicking (on Windows). Which menu
that appears depends on where the right-click was done. The figure
shows the available context menus in the Optimizer.
Insert: First select one or more rows, then right-click and choose
Insert. The same number of new variables (rows) as selected will be
inserted.
Hide: Select the rows to be hidden, then choose Hide.
Unhide: Select rows that 'span' the rows to be unhidden and then
choose Unhide.

Columns menu. Select which columns that are to be hidden or visible.
This is the same menu that is obtained from Column selection.

Swap Lower and Upper. First select an area in the table to work on,
then right-click in the Lower column within the selected area. The same
menu is available for the Upper column (not shown).
Clear selected Lower/Upper: The selected cells will be made empty.
See Constraints for more about empty cells.

Set selected Value to 0. Works on Value column in the selected area.

Toolbar 2

Add decision variable, Delete selected variables, Move selected
variables up, Move selected variables down.

Max Iterations
The user can set the maximum number of iterations that the solver
may use during optimization.
Direction
This setting determines if the goal of the solver is to maximize or
minimize the objective function. It is also possible to select 'Find
Feasible', which causes the solver to stop at the first feasible solution
(i.e., that does not violate any of the constraints).
Target
The variable name shown here is the name of the active objective
variable/function (OBJ). Only one can be active when the optimization
starts. If more than one OBJ has been defined, then selecting one of
them in this drop-down menu will set the other ones as inactive in the
'Active' column in the table.

Console
Iteration output, warnings and error messages etc. are printed in the
console window. During a run, if the output is scrolling rapidly due to
much output, the user can click in the output text in the console
window to stop the automatic scrolling and scroll up to the desired
place (while new output is being added at the end, outside of the view).
To restart the automatic scrolling one can scroll all the way down to the
bottom and click below the output, or click in the console window and
press Ctrl+End.

Solver Parameters

The figure shows the Solver parameters window with the parameters of
IPOPT as an example.
Each solver (e.g., IPOPT, Reflection, ...) defines its own set of
parameters. The parameters' names and default values are transferred
automatically from all the solvers to the optimizer so that they can be
shown in this window. At any one time, the window shows the
parameters of only the "active solver", as selected in the optimizer
window (before the parameters window is opened).
Here is an explanation of the columns:
Name: The parameters' names, as defined in the solver.
Current value:
The values in this column can be edited in this window by the user.
(Other columns can not be edited directly).
The values will be used in the subsequent optimization run.
Initialization: If the column is empty, values are first copied in from
Solver default, then overwritten by values from User default (if there
are any values saved there), then overwritten by values from the .ppo-
file (if there are any values saved there).
The values present in this column are automatically written to the .ppo-
file when that file is saved. (Saving of the .ppo-file is done from the
optimizer window.)
.ppo:
Values are read from the .ppo-file (if present in the file) and shown
here.
User default: Values are read from and automatically saved to the
QSettings. There is one set of values for each solver for each user on
each computer.
Solver default: Default values defined in the solver.
Lower boundary (not shown):
Upper boundary (not shown):
Previous: Is equal to Current when the window is opened, and will be
reinstated as current if Cancel is pressed.
Data type: Real (= floating point number), int, or text.
Description: This is a description of each variable, provided by the
solver. The same text pops up as a tool-tip if the cursor is placed on
the description or on the parameter name. Increasing the row height
will make more of the description text visible.

The arrows in the figure show the data flow of solver parameter values.
Green arrows show the reading and writing of data. Red arrows show
the initialization of the Current value column. Blue arrow shows the
Save button action.
Buttons and menus

Copies the values from the columns mentioned in the different menu
items to the Current value. (Red arrows in the figure).

Copies the values of the Current value column to the User default
column so that the values can be automatically saved in the QSettings.
(Blue arrow in the figure).

Compares the values in the Current value with other columns according
to menu selection. Comparison results are shown as background color.
Emphasis is on showing differences, and yellow means different values.
The mode "Compare current value with all (green)" is different from the
modes above in that the emphasis is on showing equality. It shows
equality with green color, and if there is at least one column that is
different from Current, it shows current in yellow (and no color on
those that are different). (Try it out, it makes sense.)
The Help button shows a description of the active solver.
There is a context-menu on the right end of the header to hide
columns, the same menu can also be opened by right-clicking on the
column headers. Column widths can be adjusted by dragging the
column separators in the heading. The hiding of columns and column
widths are saved and restored automatically (in QSettings) between
sessions. Row heights can be adjusted similarly to column widths, but
are not saved and restored between sessions.

Optimization Variables
Variable Roles:
VAR: User- or optimizer-specified. May be written to file. Updated
before any other variable and before model execution.
AUX: Either set by equation, read from file, or user-specified, in that
order of priority. If set by equation, may also be written to file.
Updated after VARs but before model execution.
CON: Unless a user-specified constant, either read from file or set by
equation, after model execution. (Note: Constraints are recognized for
all variables, not just the results labeled CON).
OBJ: Same as CON, except the optimizer will try to minimize or
maximize it.
Detailed explanations:
Before each model run (which could be an optimization iteration), all
VARs are updated first. They will have either been manually specified
by the user, or else set to new values by the optimizer engine. VARs
are never set by equation. If a VAR is associated with a file, it will be
written to its file during this update phase.
Then, still before the model run, each AUX variable will be updated in
turn. An AUX may be associated with an equation, a file, both, or
neither. If it has an equation, it will always be set by that equation
(using the current values of any referenced variables). If it also has a
file, the updated value will then be written to the file. If it has a file but
no equation, then it will be read from (instead of written to) that file. If
it has neither equation nor file, it will just be used as a user-specified
constant.
After the VARs and AUXs have been updated and (if necessary) written
to their files, the model will then be executed.
After the model execution, all other variables (CON and OBJ) will be
updated in the order specified, regardless of type. Each of these
variables can have either an equation or a file, but not both (it can also
have neither, which would just make it a user-specified constant). If it's
not just a constant, then it will either be set from its equation (using
the current values of any referenced variables) or read from its file.
Constraints will then be tested for all variable types (not just CON,
which is now really a misnomer) and fed back, along with the OBJ, to
the optimizer (if necessary).

Some solvers are provided with the default installation of Pipe-It. They
are described below.
Random Sampler Solver
This solver is intended to provide a succession of random values (within
the defined Lower and Upper bounds) of the VAR variables defined in
the Optimzer and launch the project with those values. The values of
OBJ and CON are read after the completion of run and stored as part of
the optimization History. The number of iterations will depend on the
Max Iterations value. At the end of all the iterations, the best solution
will be restored. This solver is ideal for getting a feel of the solution
space and is often the first step in an optimization problem.
Random Sampler can run also when there is no OBJ variable defined.
Case Matrix Solver
Case matrix is different from the other solvers in that it provides a
spreadsheet to the user to enter the values with which to run the
project. (In older versions of Pipe-It the Case Matrix is referred to as
Experimental Design.) The project can then be executed for any row
(set of values) or for all the cases. The values of OBJ and CONS are
read after the completion of the run(s) and stored in the History
records. Cut and paste from Excel into the Case Matrix is possible. The
case matrix can be saved as a tab-delimited file. Case Matrix can
typically be used for performing scenario studies and evaluating the
performance of the project for sets of input variables. (Case matrix is
built-in and not in a plugin.)
Nelder-Mead Simplex-Reflection Solver
The Nelder and Mead (1965) reflection simplex algorithm is the default
"real" solver provided with Pipe-It. This algorithm does not require
derivatives and is very robust. It utilizes a direct search method of
optimization that works moderately well for stochastic problems. It is
based on evaluating a function at the vertices of a simplex, then
iteratively shrinking the simplex as better points are found until some
desired bound is obtained. Lagarias et al. (1998) studied the
convergence properties of the Nelder-Mead reflection simplex, and
concludes that they are at best linear.
The Reflection solver allows specification of two parameters that affect
the convergence of this solver:
Fractional Convergence Tolerance (ftol): the solver converges if the
absolute value of the difference between the best and worst objective
values within the current simplex (including penalties for constraint
violations) is less than or equal to ftol times the absolute value of the
best objective value. This tolerance determines the accuracy to which
the optimum objective can be found, but it should be kept larger than
the precision (i.e., noise or round-off level) of the model. Otherwise,
before converging, the algorithm could encounter conflicting directional
trends, which could lead to expansions of the simplex before the
second convergence criterion (below) could be met. The current default
(5e-7) is intended to give 6 digits of accuracy in the optimum objective,
but it probably requires at least 7 digits of precision in the model.
Movelength Convergence Tolerance (ltol): the solver converges if the
simplex contracts to where the best vertex is less than or equal to the
square root of ltol in distance from any other vertex (with the distance
between the upper and lower bound for any independent variable
defined as 1). This tolerance determines the accuracy to which the
independent variables at the optimum solution can be found, but it
should be kept larger than the minimum relative change in the
independent variables that would produce a measurable change
(greater than the noise level) in the objective. Unfortunately, this is a
little difficult to estimate without prior knowledge of the second
derivatives of the objective at the optimum solution. The current
default (1e-12) is intended to determine the independent variables to
within 1e-6 times the differences between their bounds, which might be
a higher accuracy than many problems warrant.
The solver converges if either criterion is met.
TIP: If the defaults don't seem to work well for a particular problem,
and the precision of the problem is estimated to be epsilon, say, then
one might try setting ftol to somewhere between 10 and 100 times
epsilon and ltol to roughly ftol squared.
http://en.wikipedia.org/wiki/Nelder-Mead_method
IPOPT Solver
IPOPT, short for "Interior Point OPTimizer, pronounced I-P-Opt", is a
software library for large scale nonlinear optimization of continuous
systems. This is the default derivatives-based solver provided with
Pipe-It.
The following parameters can be adjusted:
Plugin parameters
1- or 2-sided differences: Specifies whether the numerical
differentiation should be 1- or 2-sided.
Model precision: If set to a value larger than 0, it will be used to
automatically set the perturbation size, the convergence tolerances and
the constraint violation tolerances in the following ways:
Perturbation size will be the square root of the model precision.
Convergence tolerance and constraint violation tolerance will be the
square root of the perturbation size.
Acceptable convergence tolerance and acceptable constraint violation
tolerance will be 5 times the value of convergence tolerance and
constraint violation tolerance.
Perturbation size: Perturbation used in numerical differentiation.
IPOPT solver parameters
Convergence tolerance (tol): See link
Constraint violation tolerance (constr_viol_tol): See link
Dual infeasibility tolerance (dual_inf_tol): See link
Acceptable convergence tolerance (acceptable_tol): See link
Acceptable constraint violation tolerance
(acceptable_constr_viol_tol): See link
Additional Ipopt options file (option_file_name): The file name of
the file where additional parameters for the IPOPT solver can be set. A
list of the most common options can be seen in the IPOPT Options
Reference.
Explanation of the difference between tolerances and acceptable
tolerances from the IPOPT documentation for acceptable convergence
tolerance:
There are two levels of termination criteria. If the usual "desired"
tolerances (see tol, dual_inf_tol etc) are satisfied at an iteration, the
algorithm immediately terminates with a success message. On the other
hand, if the algorithm encounters "acceptable_iter" many iterations in a
row that are considered "acceptable", it will terminate before the desired
convergence tolerance is met. This is useful in cases where the algorithm
might not be able to achieve the "desired" level of accuracy.
http://www.coin-or.org/projects/
NOMAD
NOMAD (Nonlinear Optimization by Mesh Adaptive Direct Search) is a
C++ implementation of the Mesh Adaptive Direct Search (Mads)
algorithm. http://www.gerad.ca/nomad/Project/Home.html
This solver can be used for mixed-integer nonlinear problems.
The DotNumericsPlugin solvers
Three solvers are available: Simplex, Truncated Newton, and L-BFGS-
B.
http://www.dotnumerics.com/
Downhill Simplex method of Nelder and Mead (Unconstrained and
bounded constrained minimization). Minimization [of] a multivariate
function using a Downhill Simplex method.
Truncated Newton (Unconstrained and bounded constrained
minimization). Minimization [of] a multivariate function using a
Truncated Newton algorithm.
L-BFGS-B (Unconstrained and bounded constrained minimization).
Minimization [of] a multivariate function subject to bounds on the
variables using a Limited memory BroydenFletcherGoldfarbShanno
method.
Note that bounds can be defined only for decision variables. Other
constraints cannot be defined with the DotNumerics solvers.

Linkz
Introduction
Linkz is the technology that allows the user to pin-point numbers in
text (and Excel) files and denotes them as variables of the Pipe-It
project. An intuitive and robust fingerprinting method is used
customized by the user to uniquely define the location of the number
with respect to surrounding tokens. These numbers can then be read
and written by Pipe-It standard runs and for optimization. Repeatedly
and without regard to their original line in the file. Columns/Rows and
whole matrices are supported. Text tokens too, though they cannot be
used in the Optimizer.

Linkz Window

The Linkz windows (also called the repository) is a visual representation
of the project_name.ppl file and contains the entire Linkz variables
defined in the project. This is a good place to orient oneself to a new
projects variables. On the left is a file/folder window with tags showing
number of links in each file or folder. Each Linkz variable is identified by
a name and a location (file).
The current value in the file can be interrogated by clicking on the
refresh icon that appears when the mouse pointer is close to the value:

Creating a new link
All links in Pipe-it are handled via Resources. To create new link in a file
ensure that it is represented as a Resource on the Pipe-it Canvas, right-
click it and select Open in Linkz:

It opens in the Linkz file viewer. Find the number you are interested to
link to. You have the Search bar to help you locate it for the first time.
Double-click this number. It turns blue and opens a New Link
definition window with suggestion for the Name, the value it has read
and the first keyword it has selected (in red) to identify this value. The
current location of the value is mentioned (5
th
token on line 16) and the
property of the keyword (1
st
token the same line as the value).

Additional keywords can be added on lines both above & below the line
where the value of interest resides. Each such keyword is highlighted
red in the Linkz view for clarity.

Once the OK button is pressed, the link is colored green and is also
added to the list of Links at the top of the Linkz Viewer:

Linkz File Viewer
The file viewer window provides good visualization of links locating. All
link values are highlighted with green color to indicate places where
Linkz is watching for values. If you click mouse on the green area of
link to select it, the file viewer will highlight keywords used for locating
the value. These keywords can be located around the value on above or
below lines.
When Linkz searches for the value of link it looks for such "fingerprints"
- value with surrounding keywords. Of course it is not necessary to
have these keywords unique, and often it is not possible to find such
unique definition in case of repeating some blocks of similar text in file.
In such situation Linkz counts occurrences of matches and choices
defined occurrence.
Also there is a way to start the value lookup from end of file. Then
Linkz counts occurrences of matches from end. It can be extremely
useful for files with iterations - file is compound of blocks of almost
same content and only last block contains values that should be linked.
Because the amount of these blocks is not same on each execution it
makes sense to start the value search from end of file.
Let's have a closer look at the link definition
Edit Link Dialog
Double-clicking an already defined link brings usp the same dialog to
edit the link.
First you can see the link name and value. Link name is editable - so
you can rename your link. Below there is an indication of location - line
number, index of token in the line, occurrence and buttons with arrows
to adjust the position of value (they can be useful if after file
modification linkz found wrong token and you need to adjust line or
token index) The list of keyword has also similar buttons for adjusting
positions of keywords. With plus and minus buttons you can add
additional keywords or remove existing. By default just added keyword
is the first token in line. So after adding you move it with arrow buttons
to position where your keyword is located. Finally you have option
enable the link lookup from the end of file. With Test button you can
test your link - the you can see updated occurrence.
We recommend to use at least 2-3 keywords for better definition of
location and to have occurrence equal to 1 - which mean that it is first
found location from begin or end of file.
If you work with huge file and your value is located at the end of file,
then it is recommended to use Locate the link starting from end of file.
Otherwise it has to parse whole file from the begin to find the location.
In case of 100MB it means minutes and if you are using the link in
some operations in your project it can slow down the execution.
Using Delimiters and Regular Expression
List of currently defined delimiters are provided in the drop-down menu

Each delimiter is based on a particular regular expression that will be
used for both the values and the keywords.
The actual expression, ability to edit those expressions and to store
new presets with modified delimiters is obtained by clicking on the
Delimiters button to get the following window:

There are two methods how the content of a file can be split into the
cells and whole file is represented as one huge table of tokens.
1. Tokenization
The Tokenization method means that during the splitting the
regular expression will be used to match the content of the tokens but
not the separation entities. As result of such approach all separators
are just omitted but also they are not matched and counted so this
method cannot handle cells(tokens) containing empty content.
Example: We would like to split line: cats;;;dogs;dolphins using
regular expression to match everything except symbol ; [^;]+.
As result of tokenization method you will get table:
cats dogs dolphins
But there is no way to get table containing two empty cells which are
suggested to be between cats and dogs
2. Separation
The Separation method uses opposite approach when defined regular
expression will be used to match the content of separation entities. In
this case we can count and match empty tokens/cells. If we consider
example above and use regular expression to match symbol ;, then
all separators will be counted and matched separately and result table
is:
cats dogs dolphins

The Optimizer Connection
One major reason for creating links using Linkz is the ability to use
them in optimization. The only way the Pipe-It Optimizer can read/write
values in files is via Linkz. So there exists a short cut to add the link
being created as an Optimizer Variable. However the Optimizer must
have been invoked at least once during the Pipe-It session for this
check box to show up:

More than a single value
The other major use of links are Pipe-Its ability to pass links from one
file to another using MapLinkz. MapLinkz is discussed further in the this
section but the power of MapLinkz becomes apparent when rows,
columns and entire matrices are transferred.
Before such large chunks of data are transferred they have to be
created. The type of link (default = single value) is defined in the drop
down menu:

The GUI elements that are involved in a column link definition.
When matrix links are being defined special case should be taken since
the behavior is to mimic that of a spreadsheet.
a) Tab-delimited should be used and tab-delimited Delimiters should
be chosen.
b) If the table (matrix) is in a non-tab delimited file expansion and
shrinkage of table content is likely to be erroneous.
c) Less & More buttons should be used to specify behavior when the
source matrix has less or more data than the receiving matrix
link.
d) With carefully planned matrix links very powerful spreadsheet
style transfer of tables from input to output resources can be
achieved.
e) Array/Matrix links required element specifications in the
Optimizer since each variable expects a single value.
MapLinkz

MapLinkz is a specialized Program / Process that is available from the
Process pull down menu (or just by pressing M on the keyboard). To
differentiate visually from other processes MapLinkz has Dark blue
boundary.

Just like any Program (Script) MapLinkz has input/output sockets for
connecting Resources. These define the files that can be used for
transferring their links from the input to the outputs. Double-clicking
MapLinkz opens the mapping interface:

MapLinkz also reports to the console detail information about the
particular operation. This is very useful when setting up the link and
ensuring the proper and complete data is being transferred.

Links in Annotations
In addition to Optimizer and MapLinkz, links can also be used in
Annotations to display their dynamic values on the Canvas directly. An
interface (Ref) in the Edit Annotation window allows selection of the
link to be specified:

It appear on the canvas with the formatting set in the Edit Annotation
window:

Streamz
Introduction
If you are using Pipe-It, or getting ready to use it, chances are you
want to perform some petroleum stream management tasks. This
means using a stream of data pertaining to actual oil, gas or water
quantities, and/or their properties, and performing some computations
on them. An example might be the aggregation of streams from
multiple wells, originating from a reservoir simulator and feeding to a
process simulator. Or using measurements from a production well test
and obtaining compositional molar streams. When it comes to stream
management, Streamz is the unmatched application that is the envy of
all petroleum applications.
Streamz is a unique program for comprehensive petroleum fluid
management. It is a decade proven technology that is the engine of
Pipe-It, new software for model-based integration and optimization
developed by Petrostreamz AS and launched on December 12, 2011.
Streamz is now exclusively available only as an integral component of
Pipe-It. Streamz is a generic program to convert fluid streams from one
characterization to another. A characterization is a description of the
number and names of components making up the stream, and
optionally their molecular weights & critical properties. Streamz is
controlled by an input file which names the characterizations, their
properties, and defines conversions among them. This file allows the
user to specify opening of stream files, containing the streams in
particular characterizations, and also commands for filtering, combining
and copying streams from one file to another. The program
automatically invokes conversions among the differing characterizations
as required, provided they have been previously supplied.
Is the petroleum engineering application package with Pipe-It that
excels in performing efficient and consistent petroleum streams
management. It is often referred to as engine of Pipe-It. To enable
new Pipe-It users to get familiar with Streamz Pipe-It provides a suite
of assisted mode, automated Streamz Processes. These are accessed
by the user when they click on the drop-down triangle in the Pipe-It
GUI next to the Process ( ) button.

Streamz Copier copies of all streams from all incoming stream files to
all connected output stream files. Unless filters are invoked.
Automatically performs characterization conversions if needed.
Streamz Tabulator aggregates incoming streams, whether from a
single or multiple stream file to produced, usually smaller, aggregated
stream files. Conversions performed automatically. Typical usage:
aggregate well streams to field streams.
Streamz Separator is used to separate each stream in an input
stream file to produce two separated streams on in each of two (gas &
oil) output stream files. There are no conversions allowed, input and
output stream files should be in the same characterization. One of 3
methods (EOS Flash, Split Factors, and K-values) can be specified.
However in the current version only EOS Flash method is available.
Pressure and temperature conditions of the Separator can be specified
or taken from an attached Pre-Include file (in which case they can be
manipulated by the Optimizer.
A complete Surface Processing Facility can be modeled by connecting
the product streams from one separator as the feed stream to the next.
Streamz Generic is a user specified Stream management task
implemented as a ready-to-run Pipe-It Process. All connected stream
file Resources, and their corresponding characterizations, are made
available on-the-fly. The user can concentrate on writing Streamz
code to define the non-vanilla task at hand. Great for learning and
validating Streamz commands.
When a user graduates to become a power user of Streamz they can
access the full power of Streamz by writing Streamz driver files of their
own and launching Streamz as a standard 3
rd
party application (or via
the supplied Streamz Script; see image below). The user is totally
uninhibited and all Streamz command documented in the reference
manual can be used. However in the context of using Streamz within a
Pipe-It integrated project users at all levels of Streamz knowledge will
tend to use the Streamz Processes, utilizing the benefit of on-the-fly
code generated based on the stream resources, characterizations and
conversion in use.

More and more Streamz Processes are likely to be added providing
more Streamz functionality via the Pipe-It GUI.

Streamz Language Commands
Streamz is built to take instructions from a user written driver file using
the Streamz command "language". The user typically states fluid
characterizations, specifies conversions among multiple
characterisations and causes the program to convert quantities
contained in stream files containing hundreds (or millions) of streams.
A rich set of about 30 commands (primary keywords) are understood
by Streamz (but not very well by users). The alphabetical list is given
below. Each is explained, with examples on page linked to the
command.
Primary Keywords Brief Description
BIPS Enter a table of Binary Interaction Parameters
CD Change Directory
CHARACTERIZATION Name and enter a fluid characterization
CLEAR Clear named filters and streams
COMBINE Combine input streams into named streams
COMPONENT
Enter a table of properties for current
characterization
CONVERT
Define a conversion procedure from a named to
"current" characterization
COPY Copy streams from input to output stream files
DEFINE Define named filters
DOMAIN Name domains and their types
ECHO Turn on echoing of input (driver) files
END Declare the end of current primary keyword
EOF Declare the end of file
EOS
Declare the Equation of State for next
characterization
FILTER Define named filters
GAMMAFILE
Open and close files for Gamma distribution
results
INCLUDE Include files
LUMP
Create lumped fraction from defined
components
MIX
Prepare named streams from other streams or
components
PROCESS
Process a stream through a set of connected
separators
REDUCE
Convert from molar streams to volumetric
streams
RESTORE
Make a previously defined characterization
"current"
SEPARATOR Define a separator
SPLITFILE Open and close split files
STREAMFILE Open and close stream files
TABS Define "tab" positions for current file
TAG Add variables & values to named streams
TABULATE Sum-up and tabulate variables while converting
TITLE Define a boxed title
TOTAL Sum named streams
VARIABLE Name variables and their types
WRITE Output named streams to stream file(s)
These commands are discussed in detail in a separate Streamz
Language documentation.
Streamz GUI (Streamz Assistants)
Streamz predates Pipe-It by almost 5 years and is a comprehensive
stream management solution by itself. It was created in 2001 and
immediately began to be used in large scale projects involving
integration of multiple reservoir simulation output, conversion from
black-oil to compositional streams and simplified surface process
simulations. Streamz has a rich command language allowing it to
perform all its tasks on hundreds and thousands of streams. It has the
capability to perform a series of tasks with output files of one tasks
becoming input files of following tasks. But to the new engineer the
richness of the command language becomes a barrier in using it.
Pipe-it was born from the need to making Streamz easy to use. Having
an intuitive and easy to understand graphical interface itself Pipe-It
provides GUI assistants for the most often used tasks of Streamz. The
user merely connects the stream file (.str) Resources to these
assistants, fill in some fields to specify optional information and a
stream management Process is ready to be launched in Pipe-It.
There are three steps necessary to use this Streamz GUI:
Populating the Streamz Library
Assigning characterizations to Resources
Dropping the Streamz Assistants on the Canvas & connecting
Input/Output? Streamz Resources.
Populating the Streamz Library

Start Pipe-It and load the project you want to work with. Now click in
the Stream Library icon on the toolbar, as show in the figure, to launch
the Stream Library.

Click on the '+' icon on the toolbar to add a file. A standard file browser
dialog box opens up to allow you to select the file. This file will be a
standard Streamz characterization or conversion file in proper Streamz
syntax. The file importer will validate the file before importing it and
lists the number of Streamz characterizations and conversion
definitions found. It is possible that a file being imported into the
library contains multiple characterizations and/or conversions but this is
not recommended.

Once a file is chosen the above dialog is shown to the user. This
example is an import of a single characterization contained in the file
"Pvt/EOS19.chr". If the user needs to review the content of the file
they can click on the "Open in Editor" button. If some edits were made
the file can be re-loaded. Once the user is satisfied they can click the
OK button to complete the import. The image below shows an import of
a file containing a conversion.

Window shown after choosing a file for import. Recognized
characterizations and conversions are shown. Errors will also appear
here if encountered.

A Streamz library as is appears after being populated with few files.
The Files tab is shown here. Some file entries are expanded to show
the characterizations and conversions contained in them. Some
overview, like the number of conversions and characterizations, as also
listed.

The characterization tab is selected in the Streamz library. More details
about each characterization and their usage in the project is listed.

The Conversion tab is selected. A Matrix and List view is available. The
Matrix view give a good orientation on conversion methods available in
the library for use.
Assigning characterizations to Resources
Once characterizations have been added the Library, assigning one to a
stream file Resources is simple.

Using Streamz Processes (Assistants)
Clicking on the appropriate Streamz Processes will allow dropping them
on to the Canvas

Opening each of these shows a tabbed window where the specifications
of each Streamz method are provided by the user based on presented
GUI. Each of these process have some parts in common, which we
discuss now, before taking up the parts specific to each.
Basic

Basic tab is usually the first one for each Streamz Process. It allows the
user to:
Normalize. The incoming stream will be normalized (each component
value for each stream will be divided by the sum of all the component
values for that stream. This will allow calculations of mole fractions or
composition from streams containing molar rates, for example.
Scale. Multiply each stream quantity by a number. Note that only
stream quantities (values of each component) are scaled and not the
variables.
Stream Filter specifications. Graphically build up a composite filter
using multiple criteria based on values of variables and/or stream
compositional property. Only streams from the input files satisfying the
filter will be passed and copied (and converted if necessary) to output
files.
Conversion

The Conversion tab shows the current conversion to be used for this
Streamz Process. If input and output resources have same
characterization the entry will be usually empty. However in some
cases (calculations or mass rates from moles) the non-default
convertor may be invoked.

For Streamz Process involving a conversion the appropriate convertor
would be shown:

Streams

This tab is mostly for information. It confirm that there are input and
output resources connected to the process and also that their
characterization has been set. It will also populate the window with all
the current variables present in the respective stream files.
An Offset for a stream variable can be specified here to shift all values
for the variable by that amount. This might be useful to get multiple
stream files to a common time basis, for example.
Code
The Code page give a preview of the Streamz code that is generated on
the fly, based on the selections and specifications in the other tabs.
This is a useful educational tool for learning the syntax of Streamz. This
is also useful for debugging purposes. This code will be echoed into the
Pipe-It console and will be executed by a launch of Streamz within
Pipe-It. This code is for view only and cannot be edited by the user.
Only the Streamz Generic has the possibility to add user code, but
limited to the streamz task portion of the code.

Streamz Copier
This is the simplest of Streamz tasks and correspondingly has the least
amount of graphical interfaces. Apart from the common tabs discussed
earlier, the Advanced tab has the following additional specifications:
Domain specification. By default Pipe-It sets up the most commonly
used domain called Time consisting of the pair of Time variables T1 and
T2. These variables exist in many stream files that have their origins in
reservoir simulators and have been post-processes by Pipe-It
Convertors (e.g. Ecl2Str). If other domains need to be set up the
Advanced tab of the Copier, and all other Streamz Process provided
this area.
Multiply Stream Quantities by Variables/Domains. This check box
allows the user to set up multiplication of stream quantities by values
of stream variables applicable for that stream. Or by domains (interval
between two variable of the same type). This could be used, for
example, to obtain cumulative production in each (uneven) time step
from rates of production during that time-step. If the start time and
end time are T1(days) and T2(days) and a domain is setup as above,
Multiply by the time domain will achieve this.
Divide Stream Quantities by Variables/Domains. This check box
allows the user to set up division of stream quantities by values of
stream variables applicable for that stream. Or by domains This could
be used, for example, to obtain production rate in each (uneven) time
step from cumulative production during that time-step.

The above Advanced specification for the Copy Process is designed to
obtain yearly rates from daily rate.
Streamz Tabulator
Basic. All consecutive streams tagged with the same values of
requested tabulation variables/domains will be aggregated (added) and
output as a single stream in tabulated form. Only the values of the
requested variables will be part of the table. Typical usage is in case of
reservoir simulation streams that originally contain streams for each
well grid connection, A 'Tabulate Time (d) and Well will add all the
connection streams to well level but the original time-steps are
retained. Cannot be used with two or more stream files from different
simulations where the time-step is likely to be different. Gathering (see
Advanced panel) options should be used in such cases.

In example above well to group aggregation is being performed (well
the title of the Streamz Tabulator) hence Tabulation of Time(d) and
Group variables are requested.
The Display option allows request for other variables that are not
participating in the tabulation but are needed to be reported in the
output stream file. Only variables that are not changed from stream to
stream in the output will be shown, the other variables will have a
blank column.
Other options for Normalize, Scale and Filter are still available in the
this Basic tab and usable as described in common section.
Advanced. The advanced tab of the Tabulator still have the Multiply
and Divide options but the Divide offer two variations.
Divide Input Stream Quantities by Variables/Domains. This
option will divide the input streams before aggregating them as part of
the tabulation.


Divide Output Stream Quantities by Variables/Domains. This
option will divide the output streams after aggregating them as part of
the tabulation. The division is once per output streams. If the division is
by a domain the extent of the variables in the output stream is used for
the division.
Gather. The gathering (collate) options are very powerful and allow
the user to output tabulated streams at user-specified intervals. The
intervals can be equally spaced throughout or in batches. Ordering
options additionally allow the gathered streams to be put in ascending
order for any of the chosen tabulation variables. Finally the ordered
streams may be output as running totals instead of actual quantities for
each stream by choosing to accumulate them.
Streamz Separator

A Streamz Separator is used in Pipe-It. On double-clicking the specific
tab ask for the type of Separation and the details. In the current
version only the EOS Flash separation method is available for which
values of temperature and pressure of the separator should be entered
by the user. User defined or pre-existing variables may be used.

Streamz Generic

A Streamz Generic offers pre-written (read-only) Streamz code
generation based on the Resource connectivity and Streamz Library
usage at the top. On the lower half is an area for user specific code
where the full power of Streamz Application is available. By default this
is populated by only the COPY command.
Streamz Documentation
Other documentation, available in the Appendix, for Streamz are:
Getting Started With Streamz Application.
Streamz Tabulation Reference.
Strexzel
Strexzel is an application for reading, manipulating and writing stream
files. The application can run in a GUI mode where the user can
view/create stream files and manipulate the streams with macro
commands. Macros or streams files can then be saved to disk. In
console mode, Strexzel will execute a macro file against an input str
file, and create a new str file as output.
If Strexzel is started without any command line arguments, it will open
in GUI mode.

Strexzel Macro Commands
Accumulate
Add Note
Calculate
Change Stream Units
Edit Component
Edit Variable
Expose Component
Insert Component
Insert Streams
Insert Variable
Load Characterization
Move Component
Move Streams
Move Variable
Name Characterization
Remove Columns
Remove Component
Remove Streams
Remove Variable
Save Characterization
Set Constant
Set Formula
Set Precision
Seed
Comments
Arguments in brackets are optional. Arguments in angle brackets
are mandatory. A list of arguments separated by a vertical bar
represents a list of valid choices. These are mutually exclusive.
Macro commands can be executed interactively (View/Macro) in
the GUI or as a script when Strexzel is running in console mode.
In GUI mode, errors are logged to the message window
(View/Message). In console mode, error messages are logged to
a separate log file specified by the "-l" option.
References to ambiguous column names (in case a variable and a
component has the same name) van be resolved by prefixing the
variable column with "v::" and/or the component column with
"c::"
Stream files on disk have a header section defining types of
variables used in the file, notes and characterization. This section
is not explicitly shown in Strexzel.

Accumulate
ACCUMULATE <var i abl e name | component name> <DESCENDI NG | ASCENDI NG>
Description
The accumulate command uses an internal accumulator, initially set to
zero. It iterates through the column data, starting at the top or bottom,
depending on the value of the last argument. For a given row it adds
the cell value of that row to the accumulator and then updates the cell
with the accumulator value.
Example
Given the dataset:

v0 v1
1 1 2
2 1 2
3 1 2
4 1 2
5 1 2
,the macro command ACCUMULATE v1 ASCENDING will transform
the data in the v1 column to:

v0 v1
1 1 2
2 1 4
3 1 6
4 1 8
5 1 16
GUI
This command does not have a GUI equivalent.

Add Note
Syntax
ADD NOTE <note text>
Description
The "add note" command will append a new note to the note section in
the stream file. The name of the stream file and the name of the macro
file will be included in the note section.
Example
Given that Strexzel has loaded the stream file:
STREAMZ 1
Not e ' Exi st i ng not e'
Char ' '
Var i abl e v0 r eal
DATA

v0 Amount Comp_01
1 0
ADD NOTE New Note will result in the following stream file after
saving:
STREAMZ 1
Not e ' Exi st i ng not e'
Not e ' Sour ce st r eamf i l e: <cur r ent st r eamf i l e name>, Macr o
f i l e: <cur r ent macr o f i l e name>'
Not e ' My new not e'
Char ' '
DATA

v0 Amount Comp_01
1 0
GUI
This command is available from the GUI by selecting Edit/Notes? from
the menu

Calculate
The Calculate command operates on vectors / columns instead of single
cell values. The result of a calculation is stored in a <current macro
name>.SSQ file.
All variations of this command takes a <reference name> as a first
argument. This is a text id that can be used to link to the calculated
result. The second argument is the function name. The implemented
functions are SSQ, SumProduct, Sum, Min, Max and Mean. The syntax
for each command is given in separate paragraphs below.
Syntax
SSQ
CALCULATE <reference name> SSQ <component | variable> <component |
variable> <component | variable> <component | variable |
constant> [MAX | AVG | MID] [EXCLUDEZEROWEIGHTS]
SSQ is calculated according to the formula
=
(
=1

The first <component | variable> argument corresponds to Qc, the
second to Qm, the third to w and the fourth to Qref. The Qref argument
can be given as a variable or component reference, a constant (defined
by SET CONSTANT <name> <value>) or a literal value. The last
argument (MAX,AVG,MID) is optional and defines which algorithm that
Strexzel should use for computing the Qref value. If no algorithm is
specified, Strexzel will default to MAX. Algorithm specification is only
applicable to component or variable argument. If the argument is a
constant or a literal, an error will occur.
MAX: Selects the maximum value from the column vector specified by
the Qref argument.
MIN: Selects the minimum value from the column vector specified by
the Qref argument.
AVG: Selects the median value from the column vector specified by the
Qref argument.
EXCLUDEZEROWEIGHTS: This optional algorithm control parameter
makes it possible to exclude rows containing zero weights from the
calculation.
If a Qref value of zero is computed, it will be substituted with the value
1.
Sum product
CALCULATE <reference name> SumProduct <component | variable> <component |
variable>
SumProduct is calculated according to the formula

= 1
=1
2

Sum
CALCULATE <reference name> Sum <component | variable>
Sum is calculated according to the formula

=
=1

Min
CALCULATE <reference name> Min <component | variable>
Min returns the smallest value found in the variable or component
column.
Max
CALCULATE <reference name> Max <component | variable>
Max returns the largest value found in the variable or component
column.
Mean
CALCULATE <reference name> Mean <component | variable>
Mean returns the median value from a sorted set conteining the values
from the component or variable column.
Example
The following macro creates a stream file with 5 streams, two variables
and two components and initiates these with dummy data. It finally
computes SSQ for v1=Qc, v2=Qm, c1=w and c2=Max(Qref)
I NSERT STREAMS 1 5 Amount
I NSERT VARI ABLE 1 v1 r eal
I NSERT VARI ABLE 1 v2 r eal
I NSERT COMPONENT 1 c1
I NSERT COMPONENT 1 c2
SET FORMULA v1 1
SET FORMULA v2 2
SET FORMULA c1 3
SET FORMULA c2 4
CALCULATE mySSQ SSQ v1 v2 c1 c2
The output is then written to the .SSQ file
CALCULATE out put : SSQ: mySSQ=2. 8125. Resul t wr i t t en t o f i l e: unt i t l ed. ssq
GUI
This command does not have a GUI equivalent.

Change Stream Units
Syntax
CHANGE STREAM UNI TS <f i r st st r eamr ow number > <number of st r eams> <Amount |
Vol ume | Mol es | Mass>
Important: By running this command, it is possible to create stream file
containing multiple units. While this is a valid stream file, formulas in
Strexzel macros will not be able to refer to or assign values to
component columns in such a file.
Description
This command will redefine units for a numbe of stream streams
starting at the stream/row number in the first argument.
Example
Given that Strexzel has loaded the stream file:
STREAMZ 1
Char ' '
DATA

v0 Amount Comp_01
1 0
CHANGE STREAM UNITS 1 1 Moles will result in the following stream
file after saving:
STREAMZ 1
Char ' '
DATA

v0 Mol es Comp_01
1 0
GUI
This command is available from the GUI by selecting Streams/Change?
Stream Units from the menu. The command applies to streams that are
selected (by selecting the row headers)

Edit Component
Syntax
EDIT COMPONENT <position> <component name> <molecular weight>
Description
This comand can be used to change a components name or its
molecular weight. <position> refers to the component index.
Example
We have two variables and two components in a stream file:

After running
EDIT COMPONENT 1 NewName
The name of the component will have been changed from "c1" to
"NewName" and the molecular weight changed to 10.

GUI
This command is available from the GUI by selecting Component/Edit
component from the menu.

Edit Variable
Syntax
EDIT VARIABLE <variable name> <type> <unit>
Description
This comand can be used to change a variable's type and unit.
Valid types are (Valid units in parentheses):
string (n/a)
integer (n/a)
real (n/a)
time (a, d, h, min, mo, s, wk, yr)
distance (cm, ft, in, km, m, mi, mm, yd)
area (acre, cm2, ft2, ha, in2, km2, m2, mi2, mm2, yd2)
volume (acre-ft, acre-in, bbl, cm3, ft3, in3, yd3, dl, dm3, gal, l, m3,
Mcf, ml, mm3, MMcf)
mass (g, kg, lbm, t, ton)
mole (mol, kmol, lbmol, MMscf, Mscf, scf, sm3)
temperature (C, F, K, R)
pressure (atm, atmg, bar, barg, kg/cm2, kg/cm2g, kPa, kPag, MPa,
MPag, Pa, Pag, psia, psig, torr, torrg)
Example
We have two variables and two components in a stream file:

After running
EDIT VARIABLE v2 mass kg
The type of the variable changed from "real" to "mass" and the unit set
to kg.

GUI
This command is available from the GUI by selecting Variables/Edit?
variable from the menu. The command applies to a selected variable
(by selecting the column header).

Expose Components
Syntax
EXPOSE COMPONENT <component name | component index>
Description
If a stream file contains multiple units, Strexzel will display a column
for each component-unit combination. If a columne has been removed
from view with the REMOVE COLUMN command, the column can be brought
back into view by running the expose command.
Example
Given a stream file with mass and amount units and a single
component. The user has deleted one of the columns:

After running
EXPOSE COMPONENTS c1
The Amount c1 column is again visible.

GUI
This command is available from the menu by selecting
Components/Expose? components from the menu. It does not present
a separate GUI.

Insert Component
Syntax
I NSERT COMPONENT <POSI TI ON> <NAME> [ MW]
I NSERT COMPONENT <NAME> <BEGI NNI NG | END> [ MW]
I NSERT COMPONENT <NAME> <BEFORE | AFTER> <NAME> [ MW]
Description
The command inserts a new component in the model. The command
has three syntax variations.
Parameters:
<POSI TI ON> specifies that the component will be inserted at a specific
index. This is a value between 1 and the number of already defined
components in the model.
<NAME> is the name of the new component.
[MW] The component's molecular weight (optional).
<BEGI NNI NG> specifies that the new component will be inserted in the first
component column.
<END> specifies that the new component will be inserted after the last
component column.
<BEFORE> specifies that the component will be inserted in the column
preceding another component (identified by the next <NAME> argument).
<AFTER> specifies that the component will be inserted after another
component (identified by the next <name> argument).
Example
Given a stream file with two variables and two components

Executing
I NSERT COMPONENT 2 NEW1
results in the "NEW1" component being inserted between c1 and c2 at
component index 2

and then executing
I NSERT COMPONENT NEW2 BEGI NNI NG
results in the "NEW2" component being inserted as the fist component

and then executing
I NSERT COMPONENT NEW3 AFTER NEW1
results in the "NEW3" component being inserted after the "NEW1"
component.

GUI
Components/Insert? Component from the menu.

Insert Streams
Syntax
I NSERT STREAMS <f i r st st r eamr ownumber > <number of st r eams> <Amount > |
<Vol ume> | <Mol es> | <Mass>
Important: By running this command, it is possible to create stream file
containing multiple units. While this is a valid stream file, formulas in
Strexzel macros will not be able to refer to or assign values to
component columns in such a file.
Description
This command inserts one or more streamsstarting at the stream/row
number in the first argument.
Example
Given that Strexzel has loaded an empty stream file:
STREAMZ 1
Char ' '
DATA
executing
INSERT STREAMS 1 5 moles
(and then, in this example, a component (c1) just to get some data)
will insert 5 streams in the model (and stream file after saving)
STREAMZ 1
Char ' '
DATA

Mol es c1
0
0
0
0
0
GUI
This command is available from the menu by selecting Streams/Insert?
Streams from the menu.

Insert Variable
Syntax
I NSERT VARI ABLE <POSI TI ON> <NAME> <TYPE> <UNI T>
I NSERT VARI ABLE <NAME> <BEGI NNI NG | END> <TYPE> <UNI T>
I NSERT VARI ABLE <NAME> <BEFORE | AFTER> <NAME> <TYPE> <UNI T>
Description
The command inserts a new variable in the model. The command has
three syntax variations.
Parameters:
<POSI TI ON> specifies that the variable will be inserted at a specific index.
This is a value between 1 and the number of already defined variables
in the model.
<NAME> is the name of the new variable.
<BEGI NNI NG> specifies that the new variable will be inserted in the first
variable column.
<END> specifies that the new variable will be inserted after the last
variable column.
<BEFORE> specifies that the variable will be inserted in the column
preceding another variable (identified by the next <NAME> argument).
<AFTER> specifies that the variable will be inserted after another variable
(identified by the next <NAME> argument).
<TYPE> specifies the variables type.
<UNI T> specifies the variables unit (optional for real, integer and string).
Valid types are (Valid units in parentheses):
string (n/a)
integer (n/a)
real (n/a)
time (a, d, h, min, mo, s, wk, yr)
distance (cm, ft, in, km, m, mi, mm, yd)
area (acre, cm2, ft2, ha, in2, km2, m2, mi2, mm2, yd2)
volume (acre-ft, acre-in, bbl, cm3, ft3, in3, yd3, dl, dm3, gal, l, m3,
Mcf, ml, mm3, MMcf)
mass (g, kg, lbm, t, ton)
mole (mol, kmol, lbmol, MMscf, Mscf, scf, sm3)
temperature (C, F, K, R)
pressure (atm, atmg, bar, barg, kg/cm2, kg/cm2g, kPa, kPag, MPa,
MPag, Pa, Pag, psia, psig, torr, torrg)
Example
Given a stream file with two variables and two components

Executing
INSERT VARIABLE 2 NEW1 mass kg
results in the "NEW1" variable being inserted between the a and the b
variable at variable index 2

and then executing
INSERT VARIABLE NEW2 beginning volume dm3
results in the "NEW2" variable being inserted as the fist variable

and then executing
INSERT VARIABLE NEW3 AFTER NEW1 time h
results in the "NEW3" variable being inserted after the "NEW1"
variable.

GUI
This command is available from the menu by selecting Variables/Insert
Variable from the menu.

Load Characterization
Syntax
LOAD CHARACTERI ZATI ON <f i l ename>
Description
Loads a characterization file for the model. The command will update
the model with this characterization. This will in effect create
component representations in the model for components that are found
in the specified characterization file (if not already defined).
The <filename> parameter can contain a file name, relative or absolute
path to a file name. The path syntax is different for MacOS (using
forward slash) and Windows (using back slash). But Windows also
allows use of forward slash so it is recommended (in general in Pipe-It)
to use forward slashes to allow the project to be portable.
If a relative path is specified, this will be interpreted as relative to the
startup folder for the application.
Example
Given the following characterization file named myChar.chr.
CHARACTERI ZATI ON " SBO+RBO"
==========================

COMPONENT MW
- - - - - - - - - - -
SO
SG
SW

END; ( of char act er i zat i on)
Given that Strexzel has loaded a stream file containing the SG
component and some streams

Executing
LOAD CHARACTERIZATION myChr.chr
will result in the SQ and SW components being created

If the model is saved, the streamz file will have the characterization
name and components defined
STREAMZ 1
Char ' SBO+RBO'
DATA

Amount SO Amount SG Amount SW
0 0 0
0 0 0
0 0 0
GUI
This command is available from the menu by selecting File/Load
Characterization from the menu. Upon activation, it presents a
standard file open dialog that enables the user to browse to the desired
file.

Move Component
Syntax
MOVE COMPONENT <component name> [ LEFT | RI GHT] <number of col umns>
MOVE COMPONENT <component name> [ BEFORE | AFTER] <component name>
Description
The command will move a component to a new position in the model.
Specifying "BEFORE" or "AFTER" can be used to move a component to
another position, relative to another component identified by the
second <component name> argument. Specifying "LEFT" or "RIGHT" moves a
component <number of columns> in the specified direction. <number of
col umns> cannot be a number that would result in a move to a 0 or
negative index, or an index greater than the number of defined
components.
Example
Given that Strexzel has loaded a model containing two variables and
two components.

Executing
MOVE COMPONENT c1 AFTER c2
will result in the two components changing places.

GUI
This command is available from the menu by selecting Compnent/Move
Component(s) from the menu. The command applies to one or more
selected components in the stream window.

Move Streams
Syntax
MOVE STREAMS <r ow st ar t > <r owend> [ TO <r ow t o st ar t at > | UP <number of
r ows> | DOWN <number of r ows>]
Description
This command can be used to rearrange the sequence of streams in the
model.
Example
Given that Strexzel has loaded the following model:

executing
MOVE STREAMS 1 2 DOWN 2
will move the first two streams two rows down.

GUI
This command is available from the menu by selecting Streams/Move?
streams(s) from the menu. The command applies to one or more
selected streams in the stream window.

Move Variable
Syntax
MOVE VARI ABLE <var i abl e name> [ LEFT | RI GHT] <number of col umns>
MOVE VARI ABLE <var i abl e name> [ BEFORE | AFTER] <var i abl e name>
Description
The command will move a variable to a new position in the model.
Specifying "BEFORE" or "AFTER" can be used to move a variable to
another position, relative to another variable identified by the second
<variable name> argument. Specifying "LEFT" or "RIGHT" moves a
variable <number of col umns> in the specified direction. <number of col umns>
cannot be a number that would result in a move to a 0 or negative
index, or an index greater than the number of defined variables.
Example
Given that Strexzel has loaded a model containing two variables and
two components.

Executing
MOVE VARI ABLE a AFTER b
will result in the two variables changing places.

GUI
This command is available from the menu by selecting Variables/Move
variables(s) from the menu. The command applies to one or more
selected variables in the stream window.

Name Characterization
Syntax
NAME CHARACTERI ZATI ON <name>
Description
This command updates the characterization name in the model. (It
does not save the characterization). This name corresponds to the Char
name in a streamz file.
Example
Executing
NAME CHARACTERI ZATI ON myChr
and saving the model will result in the Char now containing the new
name

GUI
This command is available from the menu by selecting File/Name
Characterization from the menu.

Remove Columns
Syntax
REMOVE COLUMNS <i ndex1> [ i ndex2] . . . [ i ndex n]
Description
The command removes variables and or components by view index
(visual index, not model index).
Example
Given that Strexzel has defined the following model:

Executing
REMOVE COLUMNS 1 2 4
will remove the variables a and b, along with component c2

GUI
This command is available from the GUI by selecting one or more
column headers and then pressing the <DEL> (or equivalent) key.
Variable and Component columns can be selected at the same time.

Remove Component
Syntax
REMOVE COMPONENT NAMED <COMPONENT NAME> | <I NDEX>
Description
Removes a component based on name or its model index.
Example

Executing
REMOVE COMPONENT 2
will remove the c2 component.

GUI
Component/Remove? component from the menu. It applies to a
selected component and does not present a separate GUI.

Remove Streams
Syntax
REMOVE STREAMS <r ownumber > [ r ownumber ] . . . [ r ownumber ]
Description
The command removes streams from the model.
Example

Executing
REMOVE STREAMS 1 3 5
will remove streams 1,3 & 5 from the model.

Remove Variable
Syntax
REMOVE VARI ABLE UNUSED | ALL
REMOVE VARI ABLE NAMED <var i abl e name>
Description
The command removes variables from the model. <ALL> specifies that all
variables should be removed. <UNUSED> specifies that variables that are
defined, but not used should be removed. <var i abl e name> specified that a
specific variable should be removed.
Example

Executing
REMOVE VARI ABLE ALL
will remove all the variables.

GUI
Variables/Remove? variable(s) from the menu.

Save Characterization
Syntax
SAVE CHARACTERI ZATI ON <f i l ename>
Description
Saves a characterization file for the model.
The <filename> parameter can contain a file name, relative or absolute
path to a file name. The path syntax is different for MacOS (using
forward slash) and Windows (using back slash)
If a relative path is specified, this will be interpreted as relative to the
startup folder for the application.
Example
Given that Strexzel has loaded a model containing the components c1
& c2 with respective molecular weights of 10 and 20.
Executing
SAVE CHARACTERI ZATI ON myChar . chr
will save a characterization file with the following contents:
CHARACTERI ZATI ON " "
===================

COMPONENT MW
- - - - - - - - - - -
c1 20
c2 10

END; ( of char act er i zat i on)
GUI
This command is available from the menu by selecting File/Save?
Characterization from the menu. It presents a standard file save dialog
that enables the user to select a location for the characterization file.

Set Constant
Syntax
SET CONSTANT <NAME> <VALUE>
Description
Defines a constant that later can be referenced in mathematical
expressions or formulas.
Example
Executing
SET CONSTANT pi 3. 1415926
will make the constant pi available in expressions.
GUI
This command does not have any GUI equivalent.

Set Formula
Syntax
SET FORMULA <component name | var i abl e name> [ =] [ expr essi on]
Description
The command assigns a formula to a component or variable. An empty
<expression> will remove the current formula.
Predefined constants:
e - 2.718281828459045235360287
pi - 3.141592653589793238462643
Allowed operators:
+, -, *, /,
Logical: ==, !=, >, <, <=, >=, and, or, xor (case sensitive)
Bit manipulation: &, |, <<, >> (bitwise AND, OR, SHIFT LEFT, SHIFT
RIGHT)
String concatenation
if then else conditionals with lazy evaluation: ?:
Unit postfix operators:
Unit postfixes {n}, {mu}, {m}, {k}, {G}, {M} (nano, micro, milli, kilo,
giga, mega)
Defined numerical functions:
sin - sine function.
cos -cosine function.
tan - tangens function.
asin - arcus sine function.
acos - arcus cosine function.
atan - arcus tangens function.
sinh - hyperbolic sine function.
cosh - hyperbolic cosine function.
tanh - hyperbolic tangens function.
asinh - hyperbolic arcus sine function.
acosh - hyperbolic arcus cosine function.
atanh - hyperbolic arcus tangens function.
log2 - base 2 logarithm.
log10 - base 10 logarithm.
log - (log10).
ln - e base logarithm.
exp - e raised to the power of the argument.
sqrt - square root of the argument.
sign - returns -1 if the argument is less than zero, 1 if it is greater than
zero, otherwise zero.
round - rounds a number to the specified number of digits.
abs - absolute value.
rnd - takes two arguments (lower and upper bound) and returns a
pseudo random number in the range [lower bound, upper bound].
Random generator should bee initialized by running the SEED
command before using this function.
Functions with variable number of arguments. These functions can take
a variable range as argument or a comma separated list of arguments
(example: sum(var1:var5) will return the sum of the variables from
var1 to var5)
sum
min
max
avg
Defined string functions:
tostring
concat
substr
strlen
str2dbl
toupper
tolower
Comments:
Be very careful if using logical operators on the result of calulations
involving real as these calculations may lead to a loss of precision. This
is also the case when referring to typed variables using units. Unit
conversion may occur in the background and this can lead to a loss of
precision.
Expressions can be nested
Expressions can reference constants defined by the SET CONSTANT
command.
Ambiguities between variables and components can be resolved by
prefixing variables with "v::" and components with "c::"
Formulas are not persisted in stream files.
Formulas are evaluated and the model is updated in one pass. Updated
references does not trigger re-evaluation.
Referencing component or variable names that contain mathematical
operators, requires quotes around the name (Example: SET FORMULA a =
" C1+C2")
A weakness in the parser may lead to problems discriminating between
the string literal and quoted variable or component reference by the
same name.
IF Syntax Example
SET FORMULA r es = i f ( a >=1, 0, 3)
First argument is the condition, using logical operators, second is the
value that is assigned given that it evaluates to true, third is the value
assigned given that it evaluates to false). The expression is equivalent
to:
SET FORMULA r es = ( a >=1) ? 0 : 3
Nested if example:
SET FORMULA r es = i f ( a >=1, i f ( b==3, 2, 3) , 3)
Using combinations of logical operators inside if-statement:
SET FORMULA r es = i f ( ( a > 1) and ( b<3) , 1, 0)
String function
SET FORMULA r es = a / / b
concatenation
SET FORMULA r es = subst r ( a, 1, 1)
substring with zero based offset
SET FORMULA r es = st r 2dbl ( b)
convert from a string type (b)
to real (res)
Math expressions
SET FORMULA r es = 2*si n( var A) +10*cos( var B)

SET FORMULA r es = "c2+c3"/ 2
where "c2+c3" is a component name that has to be enclosed in quotes
because it contains an operator
SET FORMULA r es = v: : a+c: : a
Where name ambiguity requiring type prefix
SET FORMULA r es = r nd( - 5, 5)
Assigns random numbers in the interval [-5, 5] to the res column
GUI
This command is available from the GUI by selecting a column and then
typing in a formula in the formula edit window.

The formula bar accepts (and ignores) options = in front of the
formula.

Set Precision
Syntax
SET PRECI SI ON <pr eci si on>
Description
The command changes the models precision (defaults to 6)
Example
Given the model:

Executing SET PRECISION 2 changes the precision in the model

Saving this model results in the following stream file:
STREAMZ 1
Char ' '
Var i abl e b r eal
Var i abl e a r eal
DATA

a b Amount c1 Amount c2
1 10 1e+02 1e+03
2 20 2e+02 2e+03
3 30 3e+02 3e+03
4 40 4e+02 4e+03
5 50 5e+02 5e+03
GUI
This command is available by selecting Edit / Output precision from the
menu.

The user can select a lower view precision by selecting View/Precision?.
Here it is possible to select a different precision for viewing purposes.
This precision can not be higher than the output precision.

Seed
Syntax
SEED <seed val ue>
Description
Initializes the internal pseudo random generator with <seed value>
Example
SEED 42
GUI
This command is not available via the GUI.

Strexzel GUI
The Strexzel GUI has three main components. These are the stream
viewer window, the macro editor and the message window. Functions
for manipulating stream files are available via the GUI or as macro
commands. Most GUI actions have macro equivalents and will be
recorded in the macro window. Macros can then be edited and tested in
the macro editor before they are saved as macro (.stm) files.

Stream window
The stream displays the contents of stream files. Streams are
represented as rows and variables and components as columns. If the
stream file/model contains variables, these will be displayed to the left
of the component columns.
Streams can be filtered on columns by specifying a column in the filter
drop box and a selection criteria in the filter text box.

If Strexzel already has a loaded stream file, opening a new file by
clicking the toolbar button or selecting File/Open from the menu, will
open the file in a new instance of Strexzel.

Cells can be modified via Strexzel macros, manually, or data can be
copy/pasted to from the grid by selecting Copy/Paste from the Edit
menu or by using keyboard shortcut keys.


Actions can be undone/redone by selecting Edit/Undo/Redo from the
menu, or via keyboard shortcuts (<CTRL>+<Z> / <CTRL>+<Y>)
No changes are made to the stream file before the user selects
File/Save/SaveAs from the menu, or clicks the save icon on the toolbar
Macro window
The macro window can be made visible or hidden by selecting
View/Macro from the menu. User GUI actions are recorded as macros
and can be further edited in the macro window.

When a user types new text in the macro window, Strexzel will try to
match the text against known commands or variables/components. If
matches are found, Strexzel will display a droplist of matching
commands. Pressing <ENTER> completes a selection in this droplist.

Tip: When working with files containing long variable or component
names, double clicking on a column header will insert the name at the
current location in the macro window.

The macro window has it's own toolbar. This contains shortcuts for
loading/saving macro files and executing/debugging macros.

In edit mode, the macro editor behaves just like any other simple text
editor. If the user switches to debug mode, Strexzel will attempt to run
the macro. In this mode, the current command is identified by a yellow
background, already executed lines with a green background, and
failed lines with a red background. The user can execute the next line,
or backtrack using the arrow keys, or step, using the toolbar buttons.
Normal editing is allowed in debug mode, but the Strexzel will stop
execution on the first error. On encountering an error, a message will
be displayed in the message window. This message will give feedback
to the user regarding the error and also show an example of the correct
syntax for the failed command.

Message window
The message window can be made visible/hidden by selecting
View/Message from the menu. The window will display error and status
messages to the user. User actions that affect the state of the model
will result in a "processed ok" or error message in the message
window.

Formulas
Any column can be assigned a formula. This can be done by selecting
the column and typing in the formula in the formula edit box. Press
<ENTER> to activate the formula. The formula syntax is described in
the SET FORMULA documentation.

Formulas will be recorded as macros and can be persisted as macro
files, but are not saved in the stream file.

Menu/Toolbar
All GUI actions that are not view, or preference related have macro
equivalents, but not all macro commands have GUI equivalent. All
functions are described under Strexzel macros.
Strexzel interaction with Pipe-It.
Pipe-It has integrated Strexzel, which is really a separate application, in
two important ways.
The Strexzel Utility on Pipe-It Toolbar is the natural way to drop a
Strexzel instance on the Canvas. This has been discussed elsewhere:

Another useful interaction is when the user wants to load an str file and
a corresponding macro file together in a single graphical instance of
Strexzel. In such case the user selects the two resources on the Pipe-It
canvas and right-clicks to get an Open in Strexzel option:

Console mode / Command line arguments
This is the mode for running Strexzel inside a Pipe-It project. Output
that normally is presented in the message window is now written to the
Console and an optional log file.
The command line arguments are:
Argument Description
-i
Input stream file. If this is the only argument, Strexzel will
start in GUI mode and open the file
-o Output stream file
-m Macro file
-l Log file
-t Test/verification file
-c
Characterization file. This file is loaded after the stream file
and before any specified macro is executed.
-s SSQ file where the SSQ result(s) are written to.
Command line options:
- - edi t
Forces Strexzel to open in GUI mode. Useful for opening a
stream file and a corresponding macro file from the
command line
Unless - - edi t is specified, Strexzel will open the stream and macro file
(and optionally the characterization file), then execute the macro and
write the result to console out and optionally a log file. Strexzel will
return an exit code of 0 if the macro execution is successful, or a
positive number in case of an error.

Convertors
Convertors are a group of growing applications that help convert files
from a foreign format to the format used by Streamz.
Ecl2Str
Description
This convertor is designed to read the Eclipse Simulator
(Schlumberger) UNSMRY and SMSPEC files and the input DATA file to
create a corresponding Stream file based on certain options. It is the
main utility to get Eclipse production results into Pipe-It. It has existed
since 1999 and continuously improved to keep pace with the evolution
of Eclipse.
Command Line Arguments
-a Date to Phase-in model. Used to shift time variables.
-b Only use if input file is using different byte-order.
-c Characterization name.
-d ECLIPSE input .dat file.
-e Date to end output of results. Used to output part results.
-f
Reference date. Use to adjust time variables in multi-model
scenarios.
-g Gas injection present (non-use = OFF).
-k
Key grouping option, takes comma-separated list without
spaces.
-l Calculation level. [g, w, c].
-m
Path mapping definition file, tab-delimited, multiline, format:
old_path[tab]new_path[new line]old_path2[tab]new_path2
-o Output .str file (main output of this utiity).
-p
Input pvt file. For use in getting BO output from Comp runs.
Need to provide quivalent BO data file or pvt file containing
BOPVT data.
-r Restart date. Date to start output of results. Used to output
part results.
-s ECLIPSE Input UNSMRY file.
-t
Minimum time step. Skips times steps less than this (in
days.
-T Find and run tests (used with special Test Bench setup).
-v Error level output. -v [err | warn | info | debug].
-w Name of water component.
-x
Use settings from .psm file (for backward compatibility -
ignores all other cmd args).
-h Command line help.
A Scripter Assistant Utility is available on the toolbar for its easy usage:

Example


Pre Ecl
Description
PreEcl will read an Eclipse data and write to an Eclipse summary
include file. The purpose is to ensure that the Eclipse data set includes
request for writing out all necessary output vectors to the UNSMRY file
to enable Pipe-It to later convert it to stream file format. An include
file, specified by the -s argument below, is created containing the
keywords. A new DATA file, specified by the -o argument, is also
created containing an INCLUDE statement pointing to this include file.
Otherwise the content of the new DATA file is identical to the original
input DATA file.
Command Line Arguments
-d ECLIPSE Original Input (*.DATA) file.
-o ECLIPSE Updated Input (*.DATA) file with include keyword.
-s ECLIPSE Include (*.SUMMARY) file.
-l Calculation level. -l [g | w | c].
-m Path mapping definition file, tab-delimited, multiline, format.
-x
-v Error level output. -v [err | warn | info | debug].
If the data file contains a BLACKOIL keyword it will proceed to add the
following set of keywords (depending on the calculation level) to the
summary include file:
Keyword Descriptione Calculation level
FOPR Field oil production rate f
FGPR Field gas production rate f
FOPT Field oil production total f
FGPT Field gas production total f
FOPRS Field solution oil production rate f
FGPRS Field solution gas production rate f
FOPTS Field solution oil production total f
FGPTS Field solution gas production total f
FPR Field pressure f
FWPR Field water production rates f
GOPR Group oil production rate f, g
GGPR Group gas production rate f, g
GOPT Group oil production total f, g
GGPT Group gas production total f, g
GOPRS Group solution oil production rate f, g
GGPRS Group solution gas production rate f, g
GOPTS Group solution oil production total f, g
GGPTS Group solution gas production total f, g
GWPR Group water production rate f, g
WOPR Well oil production rate f, g, w
WGPR Well gas production rate f, g, w
WOPT Well oil production total f, g, w
WGPT Well gas production total f, g, w
WOPRS Well solution oil production rate f, g, w
WGPRS Well solution gas production rate f, g, w
WOPTS Well solution oil production total f, g, w
WGPTS Well solution gas production total f, g, w
WBHP Well BHP pressure f, g, w
WWPR Well water production rate f, g, w
WGIR Well gas injection rate f, g, w, i
WWIR Well water production rate f, g, w, i
COFR Connection oil flow rate f, g, w, i, c
CGFR Connection gas flow rate f, g, w, i, c
COFRS Connection free oil flow rate f, g, w, i, c
CGFRS Connection free gas flow rate f, g, w, i, c
BPR Block pressure f, g, w, i, c
CWFR Connection water flow rate f, g, w, i, c
If the BLACKOIL keyword is not encountered, it will add the following
set of keyword (depending on the calculation level) :
FOPR Field oil production rate f
FGPR Field gas production rate f
FOPT Field oil production total f
FGPT Field gas production total f
FZMF Field stream mole fraction f
FXMF Field liquid mole fraction f
FYMF Field vapour mole fraction f
FHMPR Field hydrocarbon molar production rate f
FPR Field pressure f
FWPR Field water production rate f
GOPR Group oil production rate f, g
GGPR Group gas production rate f, g
GOPT Group oil production total f, g
GGPT Group gas production total f, g
GZMF Group stream mole fraction f, g
GXMF Group liquid mole fraction f, g
GYMF Group vapour mole fraction f, g
GHMPR Group hydrocarbon molar production rate f, g
GWPR Group water production rate f, g
WOPR Well oil production rate f, g, w
WGPR Well gas production rate f, g, w
WOPT Well oil production total f, g, w
WGPT Well gas production total f, g, w
WZMF Well stream mole fraction f, g, w
WXMF Well liquid mole fraction f, g, w
WYMF Well vapour mole fraction f, g, w
WHMPR Well hydrocarbon molar production rate f, g, w
WBHP Well bottom hole pressure f, g, w
WWPR Well water production rate f, g, w
CCFR Connection component flow rate f, g, w, c
BPR Block pressure f, g, w, c
COPR Connection oil production rate f, g, w, c
CGPR Connection gas production rate f, g, w, c
CWPR Connection water production rate f, g, w, c
The converter updates the output file (from -o) with an include
statement for the summary file (from -s). It finally traverses the group
tree structure and writes keywords for the corresponding level back to
the summary file.
A Scripter Assistant Utility is available on the toolbar for its easy usage:


Example

Comments
Pre_Ecl and Ecl2Str use a common library for parsing Eclipse files. This
parser will only recognize keywords that are relevant for converting
data to Streamz files. The parser scans the input in a line by line
manner and ignores comments and unrecognized keywords. This can
potentially have side effects if a recognized keyword is also a
parameter for an unrecognized keyword. When used from Pre_Ecl, the
eclipse parser will read and attempt to parse the following keywords:
Section Recognized keywords
RUNSPEC FIELD, METRIC, LAB, DIMENS, LGR, TABDIMS, COMPS,
BLACKOIL, WELLDIMS, SMRYDIMS, STRT
SCHEDULE
SOLUTION, END, OUTSOL, RPTSOL, RESTART, TSTEP,
DATES, WLIST, WEFAC, GEFAC, [WELSPECS | WELLSPEC |
WELSPECL], [COMPDAT | COMPDATL | COMPDATM],
GRUPTREE
If Pre_Ecl is unable to interpret data associated with required fields, it
will generate an error to the console and exit. The eclipse parser can in
some cases define default values for omitted data. In these cases, the
parser will log this to the console.

Sen2Str
Description
Sen2Str is similar to Ecl2Str in that both read production data from
binary files of reservoir simulators. Sen2Str does this task for the
SENSOR (Coats Engineering) simulator. Two modes are available, one
for the fort.74 binary file and the other for the fort.61 binary file.
fort.74 Command Line Arguments
-b Only use if fort.74 file is big endian.
-c Characterization name.
-d Sensor input .dat file.
-g Gas injection present (non-use = OFF).
-o Sensor out file (used for reading PVT data).
-p Sensor fort.74 file (needs PSM keyword in Sensor .dat file).
-r Restart day (used to specify start of T2 in STR file).
-s Output .str file (main output of this utiity).
-x
fort.61 Command Line Options
--well Export well records.
--platform Export platform records.
--region Export region records.
--
superregion
Export superregion records.
--field Export field records.
--tracer
Export tracer section from Fort.61. Each combination of
cptname and name are exported as a separate file. The
filename is prefixed "tracer_".
--bigendian

fort.61 Command Line Arguments
-p Sensor fort.61 file.
-s Output .str file (main output of this utiity).
-r Restart day (used to specify start of T2 in STR file).

A Scripter Assistant Utility is available on the toolbar for its easy usage
of either mode:

Example

SENSOR based Pipe-It project where the normal mode (Fort.74) and
fort.61 mode is used. The corresponding Scripts are shown below.


Script Assistant
Script Assistant is an application for creating predefined Program
shortcuts. A suite of scripts is supplied by Petrostreamz, and available
in the toolbar. The scripts will set up the Program Script automatically,
by defining sockets and a Graphical User Interface (GUI) for selecting
switches and options.
Overview
Table of Contents
Overview
Workflow
Detailed Description
Reference Documentation
Examples
Scripts supplied by Petrostreamz or created by the user are available in
Pipe-It's toolbar?.

Novice and expert user of Pipe-It will utilize these scripts to quickly use
custom Processes for often used programs. The Script Assistant
facilitates creation of new scripts and modification of existing scripts
through a GUI?.
Using Scripts
If you are new to Pipe-It, you might only have Petrostreamz Scripts
available in your toolbar. This section will show you how to use one of
those scripts in your project.
Select the Strexzel icon and drag the script to the Canvas?.

Connect? the desired resources to the created script. Sockets? is
automatically available through the script, which ensures that the
command line is correctly created.

Creating Scripts
This section will demonstrate how to create a simple script. We chose
to create a script which will launch the software PhazeComp, an
equation-of-state program for compositional phase behavior modeling
and fluid characterization.
Open Script Assistant and press the 'New' toolbar button.
Name the script PhazeComp, press save, and double click the new
script in the Global Scripts list.
PhazeComps command line is expected to look like: "PhazeComp
[inputfile] [outputfile]". Start by setting up the executable.
This assumes that the PhazeComp is in your operating systems
command path. If this is not the case, refer to your operating systems
manual, or add the complete path your executable file. Adding the
complete path might make it harder to share the project with others,
as they might not have the executable located in the same directory,
adding often used applications to the environment path is
recommended.

Click the icon button to add an icon.
PhazeComp does not accept any command line options, so we can skip
the Options list.
Add a new reference by clicking the add reference button. Populate the
dialog as follows:

Add another reference named "PhazeComp output file (*.*)", similar as
step 6, except you chose output socket instead.
To allow the user of the script to connect resources which does not go
to the command line, but established dependencies, add two more
sockets - one input and one output both with the "Goes To Command
Line" option unchecked. Name them "Other Input Dependencies" and
"Other Output Dependencies". Your reference list should now look lie
this:

Exceptions - Warnings/errorr. Script Assistant also allows you to add
the syntax specifications of the programs warnings and error
messages. Doing this will allow Pipe-It to catch errors and warnings,
and organize them in the console window.? Exceptions are identified by
a name, type, description and search pattern (regular expression). To
learn more about regular you can read more about it here. Phazecomp
outputs Errors, Warnings and Fatal Errors which can be caught be the
regular expression:
8. ^\ \ #{6}\ \ s+ERROR\ \ : \ \ s+( . *) \ \ #{6}
Add all 6 regular expressions illustrated underneath:

Press "Save Script" and PhazeComp is now available in the toolbar from
Pipe-It.
Modifying Scripts
Modification of scripts is initiated from the Script Assistant's main
window. This example will demonstrate how to modify the script we
created earlier by adding another socket where the user is supposed to
connect include files.
Find the script you created in the Global Script List, and double click it.

Add another file reference named "Include Files", which does not go to
the command line.
Workflow
Using Script Assistant is an opportunity to personalize Pipe-It, integrate
your favorite programs and applications as a part of Pipe-It. An
advanced user of Pipe-It will be able to recognize frequently repeated
creations of specific Programs and create a script instead. There is
several possible workflows, but here is one suggestion on how to go
about creating good scripts:
Create the script, give it a file name and a script name.
Find or create an icon. The image should be square, and scale well to
16x16 pixels.
Investigate which command line arguments your program accepts.
Asses if they all are useful, if there's too many it might get confusing.
Divide the program's arguments you wish to include into references
and options.
Set up the references one by one.
Set up the options one by one. Preview the results to make sure it is
intuitive to use.
If the program has a fixed syntax of the error output, set them up in
the exception tab.
Detailed Description
Script Assistant GUI
The Script Assistant GUI has three main windows. The Script Window
for managing and creating new scripts. The Edit Dialog for editing
individual scripts, and the Argument Dialog for editing a scripts
arguments.
Script Window
The Script Assistants main window is designed for
Creating new scripts
Editing existing scripts.
Deleting Scripts
Organizing your scripts.

The menu bar
The menu consist of the File and Edit menu.
File Menu

New creates a new script
Save saves the current structure settings
Exit exits script assistant
Edit Menu
Create a new Script
Open an existing Script
Save Settings
Edit highlighted script
Delete highlighted script
Scripts tab
Structure tab
Global scripts list
Script names
Script file location
Project scripts list. Will only show up if opened with an active project.
Edit Dialog
The Script Assistants edit window is designed for creating and
organizing a scripts arguments, warnings and error log output.
Creating new arguments for a script.
Deleting arguments for a script.
Organizing your arguments.
Defining warnings and error regular expressions.
Preview scripts.

Script Name The scripts name, which will be used to identify the
Script in Pipe-It and Script Assistant.
Icon Button Used to set the Scripts Icon.
Executable The name of the executable you wish the script to
execute. You can use the browse button to locate it, but be wary of
absolute path if you plan to share the project.
Options A list of of different options to be presented to the user. The
list displays the options name, type and values. Editing of options is
done via the Option Dialog. Options can be added, removed, or moved
by using the buttons underneath the option list. A preview of how the
script will appear in Pipe-It can be viewed by pressing the Preview
button, which will open the Preview Dialog.
References A list of file references. Each reference represent one
socket, and has a name, type, and reference text. The reference text is
translated to a file path based on options selected in the reference
dialog. The reference dialog is accessed by double clicking a reference.
Option Dialog
Types:
Integer
Floating Point
List
Check Box
Date
String
Reference Dialog
The Script Assistants Reference dialog is designed for editing a scripts
file references.
The GUI
Reference Name: Edit the reference name.
Goes To Command Line: Check if the file should go to the command
line or not. A typical usage for a file reference which does not go to the
command line is when the connection is supposed to be used for
establishing dependencies.
Allow Multiple Connections: Check if more than the first connector
connection to the socket should go to the command line or not.
Socket Type: Specifies whether the socket is an input or output
socket.
Minimum Matches for Execution: Sets the minimum required
connections to the socket to make the program execute.
Bounding Text: Sets the reference's bounding text. It is often used to
add quotes and arguments.
Substitution: Relative File Path or full file path. Example: Use
C:\Projects\SPE3\model\model.dat or \model.dat, relative to the
current working directory.
Exclude File Extension: Check to exclude file exenstion. Example:
File = model.dat results in model if checked.
Parent Directory Only: Reference the parent directory instead of the
file. Example: C:\Projects\SPE3\model\model.dat results in
C:\Projects\SPE3\model
Current Reference: Displays the current reference based on the
current selections in the dialog.

Preview Dialog
Exception Tab
Petrostreamz Scripts
Pipe-It Applications
Pipe-Itc
Pipe-Itc is the command line version of Pipe-It and is often used to call
external Pipe-it projects.
Streamz
Streamz is a unique program for comprehensive petroleum fluid
management. It requires a Streamz driver file as input, and produces a
Streamz log file as output.
Strexzel
Strexzel is a Petrostreamz developed program for editing Stream files.
The script will usually launch Strexzel in macro mode.
Input Sockets:
Socket Socket Name Description
1
Macro file
(*.STM) File
Specifies the macro file which will be executed
on launch
2
Input StreamFile
(*.STR)
Input stream file. If this is the only argument,
Strexzel will start in GUI mode and open the
file
Output Sockets:
Socket Socket Name Description
1 Output StreamFile (*.STR) Output stream file
2 Output SSQ File (*.SSQ) Sum of Squares File
3 Output LOG file (*.LOG) Log File
Options:
Strexzel does not have any options.
Pre_Ecl
Pre_Ecl prepares an Eclipse data file, before it is run, to output results
needed by Pipe-It.
Convertors
Convertors translates files with a specific format to a Stream file.
Ecl2Str
Ecl2Str converts Eclipse output to stream file format.

Sen2Str
Sen2Str converts SENSOR output to stream file format.

txt2Str
txt2Str converts a general tabular text file to stream file format.
Reference Documentation
Examples
When a script is used in a project, the customized Program is set up. It
provides a GUI for setting switches, and sockets for connecting
resources.


Scripts are stored in three locations.
[Pipe-It Installation Directory]\Utilities Scripts supplied by
Petrostreamz. These will be overwritten every time you update Pipe-It.
[Application Data Folder]\Petrostreamz\utilities\ Your users scripts,
available in all projects for the current computers user. These will take
precedence over Petrostreamz utilities if duplicate script names are
found.
[Current Project Folder]\Utilities\ Project utilities, available in the
current open project. Each time you save a project which uses scripts,
all utilities used will be saved in this folder. These scripts will take
precedence over all other utilities if duplcicates are found.

Plotz
Plotz is a standalone program packaged with Pipe-It to plot the
important result or data that the user might be interested in viewing
graphically. It has special automated handling of stream file that may
contain hundreds of thousands of streams for plotting. Additionally it
supports automated plotting of history data in Optimizer ppo files.
Plotz can also plot data from other sources. Tabular data from any plot
files are plotted very easily by naming and specifying columns via an
interface that closely resembles Linkz.
Automated Plotting of Stream files (.str)
Plotz had been tightly integrated into Pipe-It by means of right-click
menu of Resources:

This generates a basic Plot in no time

This only works for Stream file Resources. In many cases this auto
generated plot may be serve the purpose sufficiently well (just to view
the development of the component against time).
However if the user needs to adjust the x- and y- data and split the
plot into multiple charts, adjust the plotted series properties etc. for
this particular file, he/she can customize to heart|s content and save
the result to a *.plotz file.

These files are xml files containing all information to recreate the plot.
They can contain the references to the files used and data used from
those files. Once such files are created, they can be dragged onto the
Canvas as Resources. A Plotz Process should be also placed and and
the Plotz Resource connected to it. For Dependencies sake (to ensure
the Plotz process is re-run) STR Resource used in the Plotz instance
should also be connected.

When the project is run, the Plotz process will run after the STR
Resource is updated and a graphical instance of Plotz, with the updated
data and the customized properties of the Plot will be shown.
If the purpose of the plot is to save the results for a report, Plotz has
an output file argument (using the -o before the file name) to direct the
result to a pdf, png or jpg file without bringing up the graphical
interface:

If multiple Resources are selected before the right-click, Plotz will try to
set up a Comparison Plot where it matches common individual
components present in both files and setting up a chart for each.

Again the plot may be customized and saved if needed. In this example
both axis are changed from Linear to Logarithmic due to the nature of
the data. Observed data for gas rates are being compared against
model data in Pipe-It unique Liquid Rich Shale Templates History
Matching module.

Plotz GUI

Plotz interface is divided into:
Charts area: Rendering of the chart occurs here. New charts can be
added by using the + buttons in the left corner of this area. Charts can
be moved to left or right using the arrow buttons on the right corner of
this area.
Properties Panel: Properties Panel may or may not be visible at any
moment. To make it visible use the Window/Show Properties Panel
menu item. To close this panel use the small cross on the top right
corner. This is subdivided into:
Source Data area: Use the + button to browse for files that contain
source data to be plotted. STR & PPO files load directly while other
types of files need a Linkz style user assistance (discussed later). Each
data container is shown under each file in a tree like manner.
Plotted Series area: Data containers from the above may be dragged
and dropped onto the X or Y columns of this area to immediately plot
them in the current chart. Double-clicking into an entry here brings the
Display properties tab for that item and allows one to customize the
appearance.
Manage Axes area: This allows adding new X- or Y- axes for the
current chart in focus.
Help
Normal the working in Plotz are straightforward but may need some
practice to get used to. All the properties of all the items can be
customized.
From the Help menu item one can get access to a summary of Plotz
options:

Using templates
Templates are .plotz files that contain customizations of the different
items of a plot. Usually the data sources and the plotted series are
removed before saving a Plot as a template.
A colorful template may be saved:

When making a default plot (e.g. using the right-click method to Plot a
Stream File) may result in a plot like:

Now using a template by specifying on the command line:

Will yield a customized plot automatically:

Using the command-line
Once a desired plot is set up, the command line mode is the most
common usage of Plotz with Pipe-It. Many time Plotz will be used as
quality check points. In such cases the Input Plotz file will be used with
all input STR files to launch Plotz in a graphical instance, as part of a
complete Pipe-It project execution. The engineer can visually inspect
the plots and close the Plotz program to let the remaining project
execute. If the engineer finds inconsistent results, the project execution
can be stopped at that point. Hence it will not be necessary to wait for
the completion of the complete project to QC the results. Multiple Plotz
instances may be set up in this way to QC different key points in a
complicated project.
A plot involving optimization should not be set up in this way since the
iterations will require unnecessary user intervention (to close the Plotz
windows).
Another usage of the command line mode is to automatically obtain
PDF, png or jpg output of the important plots in a project
automatically. This can even be combined with an Optimizer run (Case
Matrix for example) and an slick file zipping, copying and renaming
processes, to obtain thousands of quality plots automatically.
To facilitate the use of these mode of operations Pipe-It include a Plotz
Utility made using the Script Assistant:

It has pre-configured Plotz command line and sockets for easy use of
Plotz command line mode.

This can be dropped on the Canvas, connected to the Resources and
run very easily. The command line adapts to the particular usage:

Graphical Interface and Functionality
Creating a new plot
A new plot is automatically created when the Plotz is opened and it is
ready for use straight away. Additionally, if your work needs to be
cleared then you can start it all over by using a menu option File ->
New. Bear in mind that if you have some unsaved work in the current
plot you will be offered to save it. In addition, when you quit the
application your current plot size and position settings will be saved so
opening it for next time returns you to the previous state.

Saving a plot
To save your current plot, there are two options available for that: File
-> Save or
File -> Save as. In case of the File -> Save option, if your plot is
new and you have not saved it yet then you will be asked for a file
where to save the plot, otherwise if you opened the plot from a saved
one or have it saved already, then the current plot file will be silently
overwritten. In addition, if you have not changed your Title items
name then upon saving it will be set to the filename (without the
extension) else it remains untouched. It is commonly recommended to
save your plot in time to prevent data loss due to some unforeseen
consequences.

Opening a plot file
Plot files are opened from a File -> Open menu option. However there
are several requirements for plot files and data files. If you have saved
a plot file and there is a series opened in the plot file. Be sure that the
series file in the same relative path as when you made the save as
otherwise your plot file will be opened and the series are marked as
inexistent (you will be able to set the series file to proper one after
you have opened the plot).

If you have saved one of plot files recently and about to open it again,
there is a fastest way of reaching it, just use the File -> Open Recent.
Recently opened plots are automatically appear there.

If you have opened a file, made some changes there and about to
return to the initial state, its fairly easy to do, just use File -> Revert
to Saved option.

Export
You can export your current plot to the document .pdf format as well as
image formats, such as .jpeg, .png, .gif.

You can either export the whole plot to the desired format or just the
current chart.
File -> Export exports the whole plot.
File -> Export Chart exports only current chart.

Items
The whole plot scene is a set of items. You can interact with those
items, such as select, change properties, add, remove, etc. Some of
items are dynamically added and removed, such as Axes and Datasets.
There are two non-removable (core) items: Background and Area.
All items are selectable and have properties that can be changed in the
Properties panel (see below).
All items are selectable, just point over the item and press the left
mouse button. You will see the selection being drawn around the items
border.



Appendix

Streamz Tabulation Reference
TABUl at e [ ( var 1| dom1) uni t s [ AND ( var 2| dom2) uni t s . . . ] ] [ I F f l t r ]
[ FROM i nf i l e1 [ AND i nf i l e2 . . . ] ] [ TO out f i l e1 [ AND out f i l e2
. . . ] ]
[ WEI GHt [ OVER| PER| BY] ( var 4| dom4) uni t s [ AND ( var 5| dom5) uni t s
. . . ] ]
[ OVER ( var 6| dom6) uni t s [ AND ( var 7| dom7) uni t s . . . ] ]
[ PER ( var 8| dom8) uni t s [ AND ( var 9| dom9) uni t s . . . ] ]
[ DI SPl ay ( var 10| dom10) uni t s [ AND ( var 11| dom11) uni t s . . . ] ]
[ ( COLLATe| ORDER*| ACCRUe) [ dom12 uni t s [ val 1 [ val 2 . . . ]
[ STEP uni t s st ep1 [ st ep2 . . . ] ] ] ] ]
PER and WEIGHt PER are new options that apply to the COPY,
COMBine, TOTAL, TABUlate, PROCess, and REALLOCate commands.
PER is very similar to OVER, except for when it gets applied. For output
streams that are created from just a single input stream (as is always
the case with the COPY, PROCess, and REALLOCate commands), PER
and OVER give identical results. When an output stream is composed of
several constituent streams, however (as can be the case with the
COMBine, TOTAL, or TABUlate commands), the effects might be
different (although not necessarily). OVER is applied once for each
constituent stream (you can remember this as "over and over"),
whereas PER is applied just once "per" output stream. Generally, OVER
will give you an average constituent rate of some sort, whereas PER
will give you a combined average rate, which might be different.
Detailed explanations, along with the actual formulas, are given in the
associated document "Weighting.pdf". DISPlay (alias SHOW*) is
another new option for the TABUlate command. It can be used to
display the output values of variables other than those tabulated and
collated. Variables that are simply DISPlayed will have no effect on how
the tabulations or collations are performed. They will just be output
whenever they can be determined unambiguously. Specifically, an
ordinary variable will be shown whenever its value is the same for all
constituents of an output stream, while domain variables will be
adjusted to show the encompassing domains for each output stream.
The most powerful new feature, though, is the COLLATe (alias
GATHER*) option and the related options ORDER* (alias REORDER*)
and ACCRUe (alias INTEGRAte). As you can see, each one of these
options has several options of its own. Some examples:
COLLATE
COLLATE time days
COLLATE time years 0 1 2 3 4 5 d.
COLLATE time months 0 1 2 3 STEP months 3*3 4*6 2*12
Explanations:
Collate all of the streams for which the tabulated variables match.
Same as (a), but also track and output the overall range of a domain.
Same as (a), but divide the collated streams into two or more domain
ranges specified by explicit collation points.
Same as (c), but allow one or more collation points to be specified
explicitly, with the remainder specified by a list of interval steps.
Let's assume "TABULATE WELL" is the primary command and that your
input files include streams from 10 unique wells (satisfying any
specified filter). Here are the results you'd get from the above options:
Ten total output streams (one for each well), where each stream would
contain the name of the well and the sum of all the input stream
amounts associated with the corresponding well. That sum could also
be WEIGHted to convert rates to cumulatives, OVERed or PERed to
convert cumulatives to average rates, or WEIGHted OVER or WEIGHted
PER to convert rates to average rates.
Same as (a), except the total time range for each well (in days) would
also be shown for each output stream.
As many as 70 total output streams (up to 7 for each well). For each
well, you would get the cumulative or average amounts (depending on
the WEIGHt, OVER and PER options) for time ranges that might include
(but only if non-empty): minimum to 0 years, 0-1 years, 1-2 years, 2-3
years, 3-4 years, 4-5 years, and 5 to maximum years.
As many as 140 total output streams (up to 14 for each well). For each
well, you would get the cumulative or average amounts (depending on
the WEIGHt, OVER and PER options) for time ranges that might include
(but only if non-empty): minimum to 0 months, 0-1 months, 1-2
months, 2-3 months, 3-6 months, 6-9 months, 9-12 months, 12-18
months, 18-24 months, 24-30 months, 30-36 months, 36-48 months,
48-60 months, and 60 to maximum months.
Now let's assume that "TABULATE WELL AND TIME (MONTHS)" is the
primary command. The results of cases (b), (c), and (d) remain
essentially the same, except the times will always be output by
months, regardless of the units given for the collation points. Case (a)
will behave quite differently, however. It will now collate all the streams
that have unique combinations of WELL, starting TIME, and ending
TIME. That could be any number of streams (as few as 10 or as many
as the total number of input streams).
As you can see, you'll have a lot of flexibility at your disposal. As for
the specific question about reporting cumulative molar productions,
let's assume that you simply want monthly cumulatives for each well
over a 10-year period (for example). If your input streams are already
in terms of cumulatives, you would say:
TABULATE WELL, COLLATE TIME MONTH 0, STEP MONTHS 120*1
On the other hand, if your input streams are in terms of daily rates,
you would simply add "WEIGHT TIME DAYS" to the above command.
Then, if you decided you wanted average daily rates for each well over
those monthly time periods, you would just add "OVER TIME DAYS" or
(more likely) "PER TIME DAYS" to the previous command, depending
on how your input data were arranged and the type of average you
wanted (see Weighting.pdf for more information).
If you replace the COLLATe keyword with ORDER* (leaving all other
input the same), the output streams will be sorted according to the
following criteria:
Highest priority: Output stream units (in case your conversions lead
to differences). Amounts will come first, then Volumes, Moles, and
finally Masses.
Next priorities: Tabulated variables (except those belonging to the
ORDERed domain, if any). Priority will be assigned in the order the
variables (or domains) were specified by the TABUlate command (with
lower domain variables taking priority over their upper counterparts).
The variables will be sorted into ascending order (numerically or
alphabetically), with undefined variables coming last.
Final priority: The ORDERed domain, which will be sorted into
ascending order.
DISPlayed variables will have no effect on the sorting.
The final option uses the keyword ACCRUe. If you use this in place of
the ORDER* keyword, each set of ordered results (having the same
tabulated variables aside from the ordered domain) will be further
combined into running totals before being output. All of the other
previous rules for the ORDER option (as well as for the WEIGHT, OVER
and PER options) still apply.

Terminology
Unsure about what we mean? Need a one line definition of a term used
on the website? What is a Resource? A Process?
This is the place you want to bookmark. A collection of all technical
terms in the context of Pipe-It. Even Pipe-It is defined here! Use the
search function to search for the term.
TERM EXPLANATION
Annotations Text boxes that have no bearing on the execution of a
project. They are useful in providing titles and notes to
the user of the project.
App2Str Format translators from 3rd party applications to Pipe-
It/Streamz stream file (*.str) format. Ecl2Str(from
Eclipse
TM
) and Sen2Str(from Sensor
TM
) are shipped
with Pipe-It. Large scale usage of Pipe-It with other
programs are likely to result in newer App2Str utilities.
Canvas The graphical playing field displayed by Pipe-It. It is,
by default, gray in color with an image of the Pipe-It
logo in the background. There always exists the main
top level canvas, but the user may create multiple
cascading composites, each having their own
canvases.
Characterization A flexible collection of components, and optionally
their properties, that may be used to represent
streams in stream files. Quantities of each component
(of the characterization) are stored as values in
stream files. Quantities may be in mass, moles,
volumes, or a generic amount. Usually defined in
simple text files that are imported into Pipe-It Streamz
Library prior to use.
Composite A brownish rectangle with round corners and double
lines. Used to group logically related base elements
(Resources, Processes or other Composites). Used to
define the extent of execution of a part of a project.
Connectors An elbowed (or straight) line with an arrow-head
defining a connection between Resources and
Processes. Connections transcending composites go
via sockets but can always be tracked back to the
originating Resource or Process.
Conversion A translation of streams from one characterization to
another. A Streamz conversion method is defined in
a simple file and imported into the Streamz Library,
automatically connecting to pre-existing in-out
characterization pairs. In case of ambiguity user
assistance is need. Once in the library, their usage is
mostly automatic.
Linkz The Pipe-It proprietary technology that allows the user
to pin-point numbers in text (and Excel) files and
denote them as variables of the Pipe-It project. An
intuitive and robust fingerprinting method is used
customized by the user to uniquely define the location
of the number with respect to surrounding tokens.
These numbers can then be read and written by Pipe-
It. Repeatedly and without regard to their original line
in the file. Columns/Rows? and whole matrices are
supported. Text tokens too.
Map Linkz The customized Pipe-It process that manages mapping
of Linkz variables from one resource to another (read
one file to another). Enables quick and easy way to
pass results of one application as input to another.
Optimizer Pipe-It supervisor that can control multiple launches
of the underlying Pipe-It model. Works with Linkz
variables to cause values to written (VAR and AUX) to
files before the launch of the model, or cause the
values to be read (AUX, OBJ and KPI) after the
completion of the model run. Can launch multiple
user-specified (Case Matrix) or automated (Solver
Driven) executions of the underlying model. The
underlying model may be the full project or parts of it
(Composites).
Petrostreamz Is the Trondheim, Norway based company that
develops and sells Pipe-It. It also offers consultancy
and training related to Pipe-It.
Pipe-It Is the software application developed and sold by
Petrostreamz AS. Conceptually it allows piping
together the various computational models used in a
value chain, or workflow, into an integrated &
automated project. Once integrated and automated, it
allows the user to optimize on any key result
computed by the integrated poject.
Pipe-It model Strictly the model part of a Pipe-It project. The Pipe-It
Project Model (ppm) file is the main entry point for
Pipe-Its Runner and is only needed to execute a
project. For typical usage of Pipe-It, the term model is
interchangeably used with the term project.
Pipe-It project A collection of files that represent all the graphical
(*.ppv) and logical (*.ppm) parts of a Pipe-It data-set.
The Pipe-It Project View (ppv) file is the main entry
point into Pipe-It and is the point of interaction for the
user. Ppv files are associated with Pipe-It upon
installation and double-clicking a projects ppv file
loads it into Pipe-It.
Pipe-Itc The command line version of Pipe-It, enabling Pipe-It
to be called from any 3rd party application that can
launch applications. Since Pipe-It is such an
application, Pipe-It can call Pipe-It itself!
Plotz The visualization tool of Pipe-It. Runs as any 3rd party
application. Can make 2-d plots of any tabulated data
in text or Excel files. Can easily mix-n-match. Special
handling of stream files allows users to be up-and-
running with most frequent of Resources. Command
line usage allows dump of scores created plots as PDF
(or image) files ready for reports or presentations.
Process A greenish oval. Represents a launch of an application
(program, script etc.) from within Pipe-It. Can only
connect to Resources on input/output, never directly
to another Process.
Resource A pale-bluish rectangle with round corners. Can be
dropped from the toolbar using an icon of the same
appearance. Represents a file on the disk. If no file is
specified, it will report a broken status to the Runner.
Runner Often called the brain of Pipe-It, it is the hidden
entity that come into play when the user hits the Run
(or Play) button on the Pipe-It toolbar. It analyses the
myriad of interconnected Pipe-It Resources, Processes
and Composites and determines the most efficient way
of launching the entire project. All dependencies are
worked out and possibilities of parallel / sequential
executions considered. It sets up the queue of
resources & applications to be run, causing the
dependent applications to be waiting for the
completion of upstream portions of the project.
Sockets Connection ports that drive the connectors in and out
of composites. Also the connections points on
Resources and Processes. Single Input and Output
sockets pre-exists on each such graphical element,
more of each type can be added and renamed by the
user.
Solver A Pipe-It supplied or user plugged-in algorithm to
control the multiple launches of Pipe-It from the
Optimizer automatically driving the currently selected
OBJ (Objective) to a maximum, minimum or first-
feasible value. User specified bounds of all variables
(VAR/AUX/KPI) will be honored during the
optimization.
Stream files Tab-delimited text files following rules of Streamz.
Contain a header section followed by stream data that
can easily run into millions of streams. Each line is a
single stream. Each stream contains optional tags of
variables followed by quantity of all components
making up the stream.
Streamz Is the petroleum engineering application package with
Pipe-It that excels in performing efficient and
consistent petroleum streams management. It is often
referred to as engine of Pipe-It.
Streamz Copier Copies of all streams from all incoming stream files to
all connected output stream files. Unless filters are
invoked. Automatically performs characterization
conversions if needed.
Streamz Generic A user specified Stream management task
implemented as a ready-to-run Pipe-It Process. All
connected stream file Resources, and their
corresponding characterizations, are made available
on-the-fly. The user can concentrate on writing
Streamz code to define the non-vanilla task at hand.
Great for learning and validating Streamz commands.
Streamz
Processes
These are a collection of automated ready-to-run
Streamz tasks embedded into Pipe-It to get the user
up-and-running with streams management.
Streamz
Tabulator
Aggregates incoming streams, whether from a single
or multiple stream file to produced, usually smaller,
aggregated stream files. Conversions performed
automatically. Typical usage: aggregate well streams
to field streams.
Strexzel Stream file editor allowing manipulation of existing
Streamz variables and/or components, including
mathematical manipulations. All such actions are
recorded in Macros that can be used on command-line
mode in Pipe-It with no user interference. Sum of
Squares of differences (SSQ) between columns of
stream data can easily be computed allowing, for
example, history matching of measured data by
optimizing the computational model.

Advanced Linkz trick
Example 1, Output of PhazeComp
Output of PhazeComp application looks in such way:

Problem of locating values of variables which are based in fourth
column "Current" is related to possibility of presence of numbers in
"Reg Var" column. Then with appearing a number in the column, the
position of token can shifted and you get wrong value of your variable.
Solution
We need to avoid of considering numbers in "Reg Var" as tokens. For
this you need to change delimiters regular expression. Because value of
variable is definitely larger than 2 digits, we can just ignore all tokens
with length less than 3 symbols. For this, in delimiters dialog, change
TOKEN REGEXP
[ ^$del i mi t er s] + to [ ^$del i mi t er s] {3, }
It means that instead "+" (which means at least one symbol and more)
linkz will look for "{3,}" (which means at least three symbols and
more)
Then first two columns will be ignored and tokens are counted from
"Variable" column.

Interaction with 3rd party software
Pipe-It is built to launch any 3rd party application like Eclipse
1
, Hysys
2
,
VIP
3
, OLGA
4
and others via the Program (Script). If the program
expects command line argument (e.g. file names) and/or options
(switches), they can be supplied. If the program binary (executable) is
not on the system path then the entire path to the executable should
be included. Quotes should be used if spaces are part of the path.
Example with Eclipse, assuming eclrun is on the path:
ecl r un Ecl i pse " ODEHI MPES_PSM"
Example with Olga, where the executable is not on the path:
" c: \ Pr ogr amFi l es ( x86) \ SPT Gr oup\ OLGA 7. 2. 2\ opi . exe" "Hydr at e. genkey"
Pipe-It can use resource references to make the command line flexible
and reusable.
If a 3
rd
party application is used frequently then Pipe-Its Script
Assistant can be used to create a short-cut on the toolbar and the
application appears tightly embedded into Pipe-It. Its usage becomes
as simple as drag and drop.
Modifying data used by these applications and using results produced
by these applications is as simple as using Linkz on the applications
input and output files.
Launching application that donot have text files for interaction is
accomplished by wrapping the launch in a COM-complaint scripting
language. Windows ships with the Windows Scripting Host (WHS) that
can read and execute *.vbs files to accomplish this. If the user has
other scripting environments installed on the computer where Pipe-It is
to be used, for example Ruby, Perl, Python etc., any & all such systems
can be used instead.
Interacting with Microsoft Excel
The Pipe-It created resource files (*.str files) are tab de-limited and
can readily be opened in a spreadsheet program like Microsoft Excel.
The Pipe-It scripter command can be set to execute a the following

1
Eclipse is trademark of Schlumberger Ltd
2
Hysys is trademark of AspenTech Inc
3
VIP is trade mark Landmark Graphics Corp.
4
OLGA is the trademark of Schlumberger.
command, where one or more .str files can be specified before the .xls
file that will use the data from these files:
" C: / Pr ogr amFi l es ( x86) / Mi cr osof t Of f i ce/ Of f i ce14/ EXCEL. EXE" "OUTPUT- STR\
VLC2. st r " "Pol yFi t . xl s"
A simpler way, if you do not want to find out the location of Excel,
would be:
Cmd / c St ar t Excel " OUTPUT- STR\ VLC2. st r " "Pol yFi t . xl s"
This causes Excel to behave as it is part of Pipe-It since the execution
continues as soon as the instance of Excel is closed.

Getting Started with Streamz (Application)
Introduction
Pipe-It provides the user with a set of tools to manage the conversion of information
among a multitude of models handling fluid streams. This software is developed to be
very flexible to use. It can perform automated, multi-step conversions using batch
scripts on a large number of streams. The package consists of a GUI for visually piping
together a project, running external models to generate or import fluid streams,
powered by the core program Streamz. This manual will get the user up and running
with the Streamz program using a typical data set and explains the use of each
command as they are encountered.
Conventions used in this document
Any reference to "Streamz" in the text refers to the Streamz program. To distinguish
between different kinds of text, we use a few typographical conventions:
Upper case, bold font is used for Streamz keywords mentioned in the text:
CONVERT, TITLE, MOLES, COPY
User-specified data to Streamz keywords are in italics:
TITLE title_string
Portions of an actual data-set used in this document are in Courier font, and enclosed
within a box:
t i t l e ' Exampl e conver si on of Bl ack- Oi l st r eams'
subt i t l e ' Conver t ed t o 6 component EOS'
Definitions
Keyword types:
Command primary keyword that introduces instructions.
Sub-command sub-level keyword that introduces further instructions.
Option sub-level keyword that sets parameters.
Arguments user-specified input to a keyword.
Introducing Streamz
Streamz is a generic program to convert fluid streams from one characterization to
another. A fluid stream is any collection of data containing information about the
amounts of the constituents of a petroleum fluid, and any other associated information
like origin, pressure, temperature, etc. A characterization is a definition of the names of
components making up the fluid stream and, in most cases, their molecular weights.
Exceptions include black-oil streams, which do not have associated molecular weights.
Equation-of-state (EOS) characterizations may also include critical properties and binary
interaction parameters.
The user controls a run of Streamz via one or more nested driver files, the
first of which is the Primary Input file. This file (through possible inclusion of
other driver files) names the fluid characterizations, describes their
properties, and defines conversions between them. It allows the user to
specify the opening of stream files containing the streams for particular
characterizations, and also allows instructions for filtering, combining and
copying streams from one file to another. This interaction of Streamz with
various files is depicted in Figure 1. Instructions are in the form of
commands, sub-commands, options and arguments. All keywords and
arguments are case insensitive for recognition purposes, but retain their
user-specified cases otherwise (in particular for arguments such as title
strings and file names). The program automatically invokes conversions
among the required characterizations. Typically, various pre-processors
generate the program commands, thereby ensuring that the syntax is
correct.

Invoking Streamz
Streamz can be invoked by using the Streamz utility in Pipe-It, or from the operating
system's command line using the program name Streamz. Up to two command-line
arguments can follow the Streamz command. The first argument is the name of the
Primary Input file, which contains the instructions and keywords to the Streamz
program. The second argument is the name of the Standard Output file, to which the
program will write various messages about its execution. Path information included with
the file names will be considered relative to the current working directory from which the
Streamz command was issued. Streamz normally requires additional input from one or
more stream files and can generate other "result" files, but these can only be specified
from within the Primary Input file.
St r eamz I nput Fi l e Out put Fi l e
Invoking the program with only the first argument results in a prompt to the user (in the
form of a simple text prompt or a standard file dialog box, depending on the operating
system) to supply the name of the Standard Output file. If the prompt is canceled, there
will be no Standard Output file. If "@" (without the quotes) is given in response to the
file dialog box, the Standard Output will be redirected to the screen. Invoking the
program with no arguments results in prompts for both the Primary Input and Standard
Output files, in that order.
A Typical Data-Set
This section steps through the "hows" and "whys" of a typical Primary Input file to
Streamz. This input file is an example of a typical usage of the Streamz program, and
contains some of the most used keywords and their options. This data set is designed to
give the first time user a template to start creating his/her own input files that allow
using the program straight away. This section will list the full data set and then step
through it line-by-line (or portion-by-portion), explaining the syntax and usage of each
keyword and option.
Description
The data set is set up to first convert streams, in the form of surface oil and gas
volumes, from a popular black-oil reservoir simulator (Eclipse 100) into 6-component
molar-rate streams. Next, a conversion to 6-component mass-rate streams is
performed. The 6-component molar-rate streams are then converted to 17-component
molar-rate streams required by a process simulator.
The Data-Set
Ti t l e ' A dat a- set f or a r i ch gas condensat e f i el d, Opi t z'
TI TLE ' Bl ack- oi l t o EOS- 6 Conver si on'

CHAR ' Opi t z BO'
NAME
SO
SG

STREAMFI LE I NP1: I NPUT "Opi t zBO. st r "
CHAR ' Opi t z EOS- 6'
NAME MW
X1 18. 640
X2 58. 890
X3 112. 420
CN1 179. 980
CN2 310. 000
CN3 480. 000

CONVERT ' Opi t z BO' f r omVOLUMES t o MOLES
SET PRES ( bar ) 422. 073
SPLI T SO X1 3. 62E- 03 8. 28E- 01 1. 01E+00
9. 36E- 01 1. 28E+00 2. 15E- 01
SPLI T SG X1 3. 84E- 02 4. 52E- 03 1. 06E- 03
2. 37E- 04 - 5. 15E- 04 - 2. 35E- 04
SET PRES ( bar ) 400
SPLI T SO X1 - 1. 44E- 02 8. 74E- 01 1. 06E+00
9. 68E- 01 1. 28E+00 1. 76E- 01
SPLI T SG X1 3. 84E- 02 4. 45E- 03 9. 89E- 04
1. 89E- 04 - 5. 24E- 04 - 1. 75E- 04
SPLI T SO X1 - 9. 77E- 02 1. 03E+00 1. 24E+00
1. 07E+00 1. 22E+00 9. 83E- 02
SPLI T SG X1 3. 85E- 02 4. 21E- 03 7. 10E- 04
3. 84E- 05 - 4. 13E- 04 - 5. 18E- 05
SPLI T SO X1 - 1. 77E- 01 1. 13E+00 1. 42E+00
1. 14E+00 1. 12E+00 7. 78E- 02
SPLI T SG X1 3. 84E- 02 4. 05E- 03 4. 52E- 04
- 3. 97E- 05 - 2. 32E- 04 - 1. 89E- 05
SPLI T SO X1 - 1. 98E- 01 1. 09E+00 1. 58E+00
1. 16E+00 1. 05E+00 7. 17E- 02
SPLI T SG X1 3. 82E- 02 4. 12E- 03 2. 57E- 04
- 5. 58E- 05 - 1. 10E- 04 - 7. 73E- 06
SET PRES ( bar ) 50
SPLI T SO X1 - 1. 27E- 01 8. 11E- 01 1. 62E+00
1. 20E+00 1. 07E+00 7. 26E- 02
SPLI T SG X1 3. 79E- 02 4. 52E- 03 2. 37E- 04
- 6. 83E- 05 - 1. 00E- 04 - 6. 87E- 06

STREAMFI LE OUT1: OUTPUT ' Opi t zEOS6z. st r '

COPY

STREAMFI LE I NP1: CLOSE
STREAMFI LE OUT1: CLOSE

TI TLE ' Opi t z EOS- 6 t o EOS- 17 Conver si on'
TI TLE ' ( kgmol es/ day of EOS- 6 t o kgmol es/ hr of EOS- 17) '
TI TLE ' ( al so t o kg/ hr of EOS- 6) '

STREAMFI LE I NP1: I NPUT ' Opi t zEOS6z. st r '
STREAMFI LE OUT1: OUTPUT ' Opi t zEOS6w. st r '

CONVERT ' Opi t z EOS- 6' t o MASS

NAME MW FULLNAME
CO2 ' CARBON DI OXI DE'
N2 ' NI TROGEN '
C1 ' METHANE '
C2 ' ETHANE '
C3 ' PROPANE '
I C4 ' I SOBUTANE '
C4 ' N- BUTANE '
I C5 ' 2- METHYL BUTANE'
C5 ' N- PENTANE '
C6 84. 198 ' HEXANES '
C7 97. 464
C8 111. 251
C9 125. 799
C10 139. 157
CN1 180. 000
CN2 310. 000
CN3 480. 000

CONVERT ' Opi t z EOS- 6' f r omMOLES t o MOLES, conser ve MASS

GAMMA X3 C7, FI LE GAM1
SHAPE 1. 570, AVERAGE 1. 0, BOUND 0. 662693471, ORI GI N 1. 0

SET PRES 423 bar
SPLI T X1 CO2 0. 03514 0. 00462 0. 84342 0. 11682
SPLI T X2 C3 0. 50204 0. 07055 0. 19427 0. 05624 0. 08078 0. 09611

SET PRES 373. 3 bar
SPLI T X1 CO2 0. 03459 0. 00485 0. 84757 0. 11299
SPLI T X2 C3 0. 51820 0. 07066 0. 19165 0. 05460 0. 07709 0. 08779

SET PRES 318. 2 bar
SPLI T X1 CO2 0. 03397 0. 00492 0. 85170 0. 10941
SPLI T X2 C3 0. 53182 0. 07159 0. 19091 0. 05227 0. 07273 0. 08068

SET PRES 263 bar
SPLI T X1 CO2 0. 03396 0. 00492 0. 85388 0. 10725
SPLI T X2 C3 0. 54201 0. 07101 0. 18935 0. 05089 0. 07101 0. 07574

SET PRES 207. 8 bar
SPLI T X1 CO2 0. 03378 0. 00495 0. 85473 0. 10653
SPLI T X2 C3 0. 54935 0. 07134 0. 19025 0. 04875 0. 06897 0. 07134

SET PRES 152. 7 bar
SPLI T X1 CO2 0. 03429 0. 00480 0. 85325 0. 10766
SPLI T X2 C3 0. 55334 0. 07151 0. 19109 0. 04924 0. 06800 0. 06682

SET PRES 97. 5 bar
SPLI T X1 CO2 0. 03509 0. 00469 0. 84823 0. 11198
SPLI T X2 C3 0. 55519 0. 07285 0. 18874 0. 05077 0. 06843 0. 06402

SET PRES 49. 3 bar
SPLI T X1 CO2 0. 03604 0. 00432 0. 83710 0. 12254
SPLI T X2 C3 0. 55296 0. 07289 0. 19728 0. 04956 0. 06706 0. 06025


GAMMAFI LE GAM1: OPEN ' Opi t zEOS6. gam'
NEWSFI LE NWS1: OPEN ' Opi t zEOS17. nws' , USER AAZ

COPY, SCALI NG 0. 041666667 ; ( conver t dai l y t o hour l y pr oduct i on)
Stepping through the data-set
This section steps through the Primary Input file presented in the previous section.
Ti t l e ' A dat a- set f or a r i ch gas condensat e f i el d, Opi t z'
TI TLE ' Bl ack- oi l t o EOS- 6 Conver si on'
The purpose of the TITLE command is to print a boxed title to the standard output file.
The quoted string following the TITLE keyword is centered within a box made up of
asterisk (*) characters. The box expands to accommodate the full length of the string.
This may be used to visually separate different tasks being run from the same input file.
A sub-command recognized within the context of TITLE is SUBTITLE (also given by a
subsequent TITLE keyword, as illustrated above). Each of these sub-commands prints
its line of text within the same box as the primary TITLE text. Using SUBTITLE after
another keyword has been used (i.e., outside the context of the TITLE command) will
result in an error.
CHAR ' Opi t z BO'
NAME
SO
SG
The CHAR command names a fluid characterization. In the present example, the
characterization_name "Opitz BO" is defined.
The NAME sub-keyword triggers the tabular input of an EOS property
table, which defines the names and properties (such as molecular weights
and critical parameters) of the components that make up the
characterization. Because a black-oil characterization is being defined in
this example, the property table consists of only the component names.
In this case, the names given to the two components are "SO" and "SG"
(Surface Oil and Surface Gas). A detailed discussion of the property table
is included later.
STREAMFI LE I NP1: I NPUT "Opi t zBO. st r "
The STREAMFILE keyword initiates the opening of a stream file for either input or
output. The first argument to the keyword is a file_nickname (INP1 used here). The sub-
command INPUT directs that an existing file is to be opened for input. Its argument is
either the actual file name ("OpitzBO.str" in our example case) or else the keyword
PROMPT, in case the user wants to be prompted interactively for the actual file name. If
the file name is entered here, and contains blanks or unusual punctuation, it should be
quoted. It may contain OS specific path directives if the file is in another directory,
relative to the current input file. The information in the file being opened should
correspond to the "current" characterization. The current characterization is the one just
defined (or made "current" with the RESTORE command, followed by the appropriate
char_name). In our case it is the "Opitz BO" characterization with two components. The
stream data in the file being opened with this STREAMFILE command should contain
the quantity information for two components only.
NAME MW
X1 18. 640
X2 58. 890
X3 112. 420
CN1 179. 980
CN2 310. 000
CN3 480. 000
Here we have the definition of a second characterization using the CHAR command. We
need two defined characterizations to convert from one to the other. This is an EOS
characterization named "Opitz EOS-6" with 6 components. The NAME sub-keyword
triggers tabular input of an EOS property table and defines the properties of the
components that make up this characterization. This tabular input scheme is very
flexible, allowing any of the component properties (including their NAME) to be input in
any order. Each property is identified by a heading keyword. For example, MW indicates
molecular weight. The only constraint of the tabular input scheme is that any entries in
the table that belong to a particular heading (i.e., property) should line up with the
heading. This allows unknown entries to be left blank without misaligning the rest of the
table. The specific rules for lining up the table are described in Appendix A of the
Streamz Reference Manual. The name of each component is listed under the NAME
heading. The value of any other property corresponding to that component is entered in
the same row, lined up under the heading corresponding to the desired property. In our
example case, the molecular weight of X3 is 112.420. This input scheme is designed to
enable cut-and-paste from any other data file or spreadsheet with minimal editing. The
example requires only the NAME and MW properties but input of a full EOS property
table is also allowed for forward compatibility.
CONVERT ' Opi t z BO' f r omVOLUMES t o MOLES
The CONVERT keyword initiates the definition of a conversion procedure to convert
streams corresponding to an input characterization into streams corresponding to an
output characterization. The first argument to the keyword is the name of the input
characterization (in this case "Opitz BO"). This must have been previously defined. The
output characterization is the "current" characterization (the one defined last or made
"current" by the RESTORE command). The FROM option defines the input units
expected by the conversion procedure. Conversion will be possible only for input streams
specified in these (or compatible) units. Four units are currently understood, namely
MASS, MOLES, VOLUMES, and AMOUNT. The FROM units should match those in the
corresponding input stream files (MASS and MOLES are compatible if the component
molecular weights have been defined). The actual streams may be in more specific,
dimensional units, which may also denote rates, concentrations, fluxes, etc. For
example, kgmol, lbmol/day, gmole/cc, or lbmol/ft
2
/sec would all fall under the category
of MOLES. The true, dimensional units are not relevant to the program, but should be
kept track of by the user, so as not to confuse lbmol/day with kgmol/hr, for example. We
use VOLUMES here because we know that the input streams are in Sm
3
/D (i.e.
volumetric rates). The TO option specifies the units of the output streams. A CONSERVE
option to the CONVERT command will be discussed later in this section. If the FROM
units are not specified, they will default to the TO units, the CONSERVE units, or
MOLES, in that order of preference. Then, if the TO or CONSERVE units have not been
specified, they will default to the FROM units.
SET PRES ( bar ) 422. 073
SPLI T SO X1 3. 62E- 03 8. 28E- 01 1. 01E+00
9. 36E- 01 1. 28E+00 2. 15E- 01
SPLI T SG X1 3. 84E- 02 4. 52E- 03 1. 06E- 03
2. 37E- 04 - 5. 15E- 04 - 2. 35E- 04
.
.
.

SET PRES ( bar ) 50
SPLI T SO X1 - 1. 27E- 01 8. 11E- 01 1. 62E+00
1. 20E+00 1. 07E+00 7. 26E- 02
SPLI T SG X1 3. 79E- 02 4. 52E- 03 2. 37E- 04
- 6. 83E- 05 - 1. 00E- 04 - 6. 87E- 06
One way to convert an input stream to an output stream is through a set of split factors.
Each split factor specifies the portion of a given input component that partitions into a
given output component. Each component (input or output) may have several split
factors associated with it and the split factors may be functions of one or more control
variables. Streamz handles the input of these split factors by means of the SET and
SPLIT (or DELUMP) keywords, which are discussed in this section. Examples are shown
in the above extract, which contains only a portion of the relevant part of the data-set
(missing portions are replaced by dots).
The SET sub-command is known within the context of the CONVERT
command and is used to specify control variables and set their values.
Here we designate the previously defined pressure variable "PRES"
(defined in our input stream file by the VARIABLE command) as our one
control variable and set its value initially to 422.073 bar (variables of
pressure, temperature, time or distance need to be assigned unitsin this
case, BAR). Our split factors therefore become piecewise linear functions
of pressure, starting with those at 422.073 bar. If we had specified
additional control variables, the split factors would become piecewise
linear functions of those variables as well. The first argument to the SET
sub-command is the name of the primary control variable, followed by its
value and units (if applicable), in either order (the parentheses shown
here are optional and are actually ignored). Additional control variables,
along with their values and units, could be given as additional arguments,
as long as only one input line is used for the entire set of control
variables. If the split factors are known to be constant, there is no need
for the SET keyword.
The SPLIT (or its alias DELUMP) sub-command is one of the two methods
Streamz uses to convert streams (the other being GAMMA distribution
modeling). This specifies the split factors for conversion of a single input
component to one or many output components. A split factor is the
fraction of a component in the input stream that goes into a specified
component of the output stream. The first argument to this keyword is
always the name of the input component. That's followed by a series of
doublets, each consisting of an output component name and its split factor,
in either order. Either element of each doublet may be omitted, however.
If the component is omitted, it defaults to the one following that of the
previous doublet (with the first doublet defaulting to the first component).
If a split factor is omitted, it defaults to 1. The doublets continue until a
keyword that is not a component name is encountered. Thus, at 422.073
bar in our example, SO will split into six output components, starting with
component X1. The same applies to SG. Since the CONVERT is FROM
VOLUMES TO MOLES, each volume of SO will split into 3.62E-03 MOLES of
X1, 8.28E-01 MOLES of X2, 1.01E+00 MOLES of X3, 9.36E-01 MOLES of
CN1, 1.28E+00 MOLES of CN2, and 2.15E-01 MOLES of CN3. Similarly,
each volume of SG will split into 3.84E-02 MOLES of X1, 4.52E-03 MOLES
of X2, 1.06E-03 MOLES of X3, 2.37E-04 MOLES of CN1, -5.15E-04 MOLES
of CN2, and -2.35E-04 MOLES of CN3. Note that this conversion assumes
that the actual input VOLUMES will have units of Sm
3
(for both SO and SG)
and that the MOLES it produces on output will actually be kgmols. Also
note that negative split factors are normal for this type of process-
dependent, black-oil to compositional conversion. Here, SG/SO ratios of
915 or more would result in negative EOS mole fractions, but for the
process of interest, input streams that are saturated at 422.073 bar
should never have SG/SO ratios that high. That being said, the design of
process-dependent conversions is beyond the scope of this document.
Split factors are defined for a range of values of the dependent variable.
In our example, the streams from a reservoir simulator are expected to
be saturated at pressures from 422 bar to 50 bar. Each table uses the SET
keyword to set the value of the pressure control variable, and uses the
SPLIT keyword to define the split factors associated with each pressure
"node". If a stream (in a stream file being converted) has this associated
variable at an intermediate value, linear interpolation is used to calculate
the split factors for conversion.
The STREAMFILE keyword has already been discussed for input files. Here it is used
with the OUTPUT option, which takes either the name of the file to be created
("OpitzEOS6z.str" in this case) or else the keyword PROMPT, in case the user wants to
be prompted interactively for the new file name. Because the "Opitz EOS-6"
characterization is "current", the streams written to this file will correspond to this
characterization.
COPY
The COPY command initiates a read & write operation from all open input stream files to
all open output stream files (one of each, in this case). Because the input and output
files correspond to different characterizations, each stream needs to be converted before
output. The program invokes the relevant conversion definition (in this case split factors
are used) automatically. Because the SPLIT command is used with the SET option, and
because the streams in the input stream file have a defined pressure variable named
PRES, the split factors will be interpolated (if necessary) and then used to calculate the
output streams. For advanced usage, the COPY command allows conditional processing
(using the IF option to select criteria specified by previous FILTER commands), variable
WEIGHTING (and OVERING), stream NORMALIZATION, constant SCALING, and
selective outputting (using the TO option to specify the file_nicknames of only the files
to which output is desired).
STREAMFI LE I NP1: CLOSE
STREAMFI LE OUT1: CLOSE
The STREAMFILE command is used with the CLOSE option to close the files associated
with the supplied file_nicknames.
TI TLE ' Opi t z EOS- 6 t o EOS- 17 Conver si on'
TI TLE ' ( kgmol es/ day of EOS- 6 t o kgmol es/ hr of EOS- 17) '
TI TLE ' ( al so t o kg/ hr of EOS- 6) '
Three TITLE commands are used. The first is interpreted as the primary TITLE
command and the next two are interpreted as SUBTITLE sub-commands. The result is
the output of all three lines, in a single box, to the Standard Output file. This visually
marks the start of the next task being run from the same file.
STREAMFI LE I NP1: I NPUT ' Opi t zEOS6z. st r '
STREAMFI LE OUT1: OUTPUT ' Opi t zEOS6w. st r '
Two stream files are associated with file_nicknames ("INP1" and "OUT1") and opened.
The first ("OpitzEOS6z.str") is the same as that used for OUTPUT in the previous task.
It is being used for INPUT now, allowing intermediate results from the same run of
Streamz to be used for subsequent conversions. The second is a new OUTPUT file. Since
both STREAMFILE commands are issued one after the other, both will be associated
with the same, "current" characterization ("Opitz EOS-6"). As we will soon see, this is
exactly what is required.
CONVERT ' Opi t z EOS- 6' t o MASS
This CONVERT command defines a conversion from the "Opitz EOS-6" characterization
to the "current" (also "Opitz EOS-6") characterization. Conversions from any
characterization to "itself" are always defined, as long as the FROM and TO units are
compatible. The only reason for specifying this type of self-conversion is to force a
change of units (TO MASS, in this case) for each stream processed. The FROM units
aren't specified, so by the rules previously outlined, they are assumed to equal the
specified TO units, MASS. The CONVERT FROM MASS (of "Opitz EOS-6") TO MASS (of
"Opitz EOS-6") is trivial (and even if non-trivial SPLIT factors were entered, they'd be
ignored). It will obviously work for input streams given with MASS as units, but it will
also work for input streams given in MOLES. That's because the "Opitz EOS-6"
characterization includes the molecular weights of all its components, making MOLES
and MASS completely compatible (i.e., internally convertible) for this characterization.
In either case, all output streams will be given in MASS. The next COPY command will
automatically invoke this CONVERT TO MASS when it copies the streams from INP1 to
OUT1, since both of these files are associated with the "Opitz EOS-6" characterization.
NAME MW FULLNAME
CO2 ' CARBON DI OXI DE'
N2 ' NI TROGEN '
.
.
.
C6 84. 198 ' HEXANES '
.
.
.
CN2 310. 000
CN3 480. 000
We now define a new, 17-component characterization. Reproduced above is only a
portion of the original data-set. Note the use of a new property, FULLNAME. This allows
names of components containing embedded spaces, which might be required in some
usages. The FULLNAME property might also be used to associate a remark with the
component. Currently this property is used for output to an in-house process simulator
format.
CONVERT ' Opi t z EOS- 6' f r omMOLES t o MOLES, conser ve MASS
This command defines the conversion from the "Opitz EOS-6" characterization to the
current ("Opitz EOS-17") characterization. The conversion is defined from molar streams
to molar streams. Note the use of the CONSERVE option. This allows the user to specify
the quantities to conserve during the conversion (MASS, in this case). Use of the
CONSERVE option has two effects. First, the split factors will be checked for possible
material balance errors; if they will not conserve the requested quantities, warnings will
be issued. Second, it determines the way Gamma distribution modeling is performed.
Gamma modeling can conserve either moles or mass, but generally not both. Moles are
conserved by default, but the option to CONSERVE MASS can be used instead. Any
combination of FROM, TO, and CONSERVE units may be specified, but the CONSERVE
option has an effect only if the conserved units are compatible with both the FROM and
TO units. Otherwise, it is ignored.
GAMMA X3 C7, FI LE GAM1
SHAPE 1. 570, AVERAGE 1. 0, BOUND 0. 662693471, ORI GI N 1. 0
The GAMMA option is another possible method of defining the conversion between
characterizations (the first being the SPLIT option). It can be used just by itself, if the
characterization contains only heavy components for which a continuous distribution is a
good approximation (e.g., heptanes plus, C
7+
, or decanes plus, C
10+
). Or it can be used
for a heavy-end subset of the components, with split factors being used for the
remaining, lighter components. It expects 2 mandatory arguments in the form of the
names of one component each of the input and output characterizations. These are the
lightest components in each which are requested to participate in the Gamma modeling.
The molecular weights and the amounts of all input components as heavy as, or heavier
than, that specified, would be used to calculate a gamma distribution model. The model,
and the molecular weights of all output components as heavy as, or heavier than, that
specified, would then be used to calculate the amounts of the output stream. In the
example, we specify that X3 and heavier components (MW-wise) should be fit to a
Gamma distribution model. We also specify that C7 and heavier components of the
output streams will receive amounts based on the calculated model.
Without going into the mathematical details here, the Gamma model
describes a continuous molar distribution as a function of molecular
weight. The function itself is defined for molecular weights from an origin
value to infinity, but only the molecular weights greater than or equal to a
boundary value (greater than or equal to the origin value) are considered for
the molar distribution. The molar distribution has an average MW and the
function has a particular shape, which can (a) decay exponentially from a
finite value at the origin MW, (b) decay faster than exponentially from an
infinite value at the origin MW, or (c) decay slower than exponentially
after rising from zero at the origin MW and going through a maximum.
Shapes of type (b) are typical for gas condensates and shapes of type (c)
are typical for heavy oils, while shape (a) falls in-between. The
distribution is described by four parameters: one for the shape and three
others for the origin, boundary, and average molecular weights.
The calculation of the model is essentially the determination of the four
model parameters by means of regression. The user has control over the
regression by specifying the starting values and the upper & lower bounds
of these parameters. The four model parameters are specified by optional
sub-keywords known within the context of the CONVERT command. These
sub-keywords are SHAPE, BOUNDARY, AVERAGE, and ORIGIN (or ZERO).
The exponential shape (a) has a SHAPE parameter of 1. Shapes of type
(b) have SHAPE parameters less than 1 (typically no less than 0.4) and
shapes of type (c) have SHAPE parameters greater than 1 (typically no
greater than 5). The model's average MW is given by the product of the
AVERAGE parameter (typically around 1) and the calculated average MW
of the portion of the input stream being modeled. The model's boundary
MW is given by the product of the BOUNDARY parameter (between 0 and
1) and the MW of the input component specified as the first argument to
the GAMMA keyword. The model's origin MW is given by the product of the
ORIGIN parameter (between 0 and 1) and the model's boundary MW.
Each of the four parameter keywords may be entered with zero to three
numerical arguments. If a particular parameter keyword is entered
without any arguments (or if it is not entered at all), its default initial
value and bounds will be used during regression. If it is entered with at
least one argument, the first argument is taken as the parameter's initial
value, the minimum argument is taken as the lower bound for regression,
and the maximum argument is taken as the upper bound. If the initial
value and both bounds turn out to be equal (e.g., when only one
argument is entered), then that single fixed value will be used for the
model and it will not be altered by regression. In our case we have fixed
all the parameters. They were calculated previously by fitting a sample of
the fluid to the Gamma distribution model.
An optional sub-keyword within the context of the GAMMA keyword is
FILE. This specifies the nickname of the file to which gamma model results
are written. An actual file needs to be opened with the GAMMAFILE
command and associated with this nickname before the results will
actually be written. We use the file_nickname "GAM1" in this example.
SET PRES 423 bar
SPLI T X1 CO2 0. 03514 0. 00462 0. 84342 0. 11682
SPLI T X2 C3 0. 50204 0. 07055 0. 19427 0. 05624 0. 08078 0. 09611
.
.
.
SET PRES 49. 3 bar
SPLI T X1 CO2 0. 03604 0. 00432 0. 83710 0. 12254
SPLI T X2 C3 0. 55296 0. 07289 0. 19728 0. 04956 0. 06706 0. 06025
Again we have reproduced only a portion of the relevant part of the data-set. The
current conversion definition uses a combination of GAMMA and SPLIT methods. While
the X3-plus to C7-plus conversion is covered by the GAMMA command, pressure-
dependent split factors are specified for the conversion of the other components. X1 of
input streams splits into C02 and the next 3 components (based on order of definition in
CHAR command) of the output streams. X2 splits into C3 and the next 5 components.
The splitting is a function of pressure where interpolation is used if required.
This specifies the file_nickname and the actual disk file where streams corresponding to
the "current" characterization ("Opitz EOS-17") will be written.
GAMMAFI LE GAM1: OPEN ' Opi t zEOS6. gam'
NEWSFI LE NWS1: OPEN ' Opi t zEOS17. nws' , USER AAZ
The primary GAMMAFILE command is used to OPEN (also possible with the FILE or
OUTPUT keywords), CLOSE, or PROMPT for a file where the results of gamma
modeling are to be written. It first associates a file_nickname (GAM1, in this case) with
this file. This file_nickname must be used when closing the file or when specifically
directing output to it (with the FILE option of the GAMMA sub-command of the
CONVERT command). The OPEN sub-keyword takes the name of the file to be created
("OpitzEOS6.gam" in this case) as its argument. Gamma files are typically used for a
small number of streams.
The primary NEWSFILE command provides temporary functionality to
create output stream files in an in-house process simulator format. It
uses the OPEN (also possible with the FILE or OUTPUT keywords), CLOSE,
or PROMPT options to handle a file of this type. It first associates a
file_nickname (NWS1, in this case) with this file. This file_nickname must be
used when closing the file (using the CLOSE option) or when specifically
directing output to it (with the TO option of the COPY, TABULATE, or WRITE
commands). The OPEN sub-keyword takes the name of the file to be
created ("OpitzEOS17.nws" in this case) as its argument. An additional
sub-keyword (required by the proprietary process simulator format) is
USER, which takes the initials of the user as its argument ("AAZ" in the
example). The NEWSFILE command is likely to be eliminated from
Streamz in a future version.
COPY, SCALI NG 0. 041666667 ; ( conver t dai l y t o hour l y pr oduct i on)
The COPY command copies the streams from all open input stream files to all open
output stream files (or a subset specified by the TO option), converting the streams as
needed. The SCALING option multiplies the output streams by a constant factor. This
can be used for conversion from one set of units (e.g. moles/day) to another
(moles/hour), for example. Other options are illustrated in the Streamz Reference
Manual.
Keyword Abbreviations
Streamz keywords have some required starting characters, with any trailing characters
being optional. Optional trailing characters may be replaced by anything (or nothing).
For example:
In CONVERT only CONV is required. And since the trailing characters can
be replaced, CONVERSION is also valid for that keyword.
The required part, or abbreviations, of some keywords are listed in the
table below.
Keyword Abbreviation
AVERAGE AVE
BOUNDARY BOUND
CLOSE CLOS
CONSERVE CONS
CONVERT CONV
FILTER FILT
FULLNAME FULL
GAMMAFILE GAMMAF
INPUT INP
MOLES MOLE
NEWSFILE NEWSF
NORMALIZATION NORM
ORIGIN ORIG
OUTPUT OUT
OVERING OVER
PROMPT PROM
RESTORE REST
SCALING SCAL
STREAMFILE STREAMF
SUBTITLE SUBT
TABULATE TABU
TITLE TIT
VARIABLE VAR
VOLUMES VOLUME
WEIGHTING WEIGH
A Typical Stream file
A Stream file consists of a header section and a data section. The header section
contains information about the file and defines the basic characteristics of the stream
data in the file. The data section contains headings for the data and the actual stream
data. An important point to note is that stream files are tab-delimited. This means that
each individual piece of information (i.e. each record) is separated from the next by a
tab character. It is important that such files are not edited in a text editor that removes
the tabs and converts them to spaces. The reason for using tab-delimited files is the
ease of import into Microsoft Excel for further manipulation.

Plots on Canvas in Pipe-It projects and using
"R" language
Using Item properties dialog or with drag-and-drop you can easily
attach images to your canvas items. Pipe-It uses OS file watchers, so if
any of your image is changed, it is reloaded and appropriate items,
which have attached the image, are updated.
It opens very powerful way to generate graphics and diagrams from
your project scripts and show result images directly on canvas. You can
use different utils or languages to generate them - they should be just
part of your project (just scripters) to run with project and update
appropriate graphics files.
One of advantages is possibility to use "R" language. This is very
powerful language that used for for statistical computing and graphics.
For example few screenshots that illustrates possibilities at their
webpage:
http://www.r-project.org/screenshots/screenshots.html
http://addictedtor.free.fr/graphiques/thumbs.php?sort=votes
As example we can study how to make plots for some STR file. Imagine
that you have some Resource with attached STR file:

This file: TUNE.str contains:
St r eamz 1
Not e "Case: P50"
Char "BO+W"
Var i abl e Year I nt eger
Var i abl e Gr oup St r i ng

Dat a

Set Gr oup TUNE

Year Amount s SO SG SW
2006 271552 555555550 13781
2007 150029 1736142619 6788
2008 26812 4347876676 1239
2009 178500 5451284722 0
2010 109233 6447013889 0
2011 40767 6385229167 0
2012 151500 1478472222 6122
2013 135000 1305000000 5510
2014 15000 145000000 612
There is a table that can be easily loaded with "R" language. For
generating graphic "Year" --> "Amounts", only 4 lines of "R" code is
required:
The script file: str-to-png.r contains:
png( "TUNE. st r . png" )
i np <- r ead. t abl e( "TUNE. st r " , sep="\ t " , ski p=11, h=T)
pl ot ( i np[ [ 1] ] , i np[ [ 2] ] , t ype="b")
dev. of f ( )
Now you need to create simple script that call this "R" script file and
generates png

(You need to have "R" in your PATH environment variable)

When you run the project you get TUNE.str.png. Which you can attach
as background directly to your Resource file.

Then the plot will be generated each time your resource got new data
and is completed during project run and background of the Resource
will be updated automatically.
Actually you can attach the image to any other item - "script-to-png" or
canvas background or background of composite or annotation - it does
not matter, Pipe-It watch if the image is changed and updates
appropriate items on canvas. You can create several "monitors" to
watch how some diagrams are changed during run etc.
See also:
http://www.r-project.org/
http://www.r-project.org/screenshots/screenshots.html
http://addictedtor.free.fr/graphiques/thumbs.php?sort=votes

Pipe-It File types
The following file types are used by Pipe-It. The extensions are typical
but not mandatory.
*.stz Streamz engine driver files
*.str Pipe-It resource (stream) files
*.psm Pipe-It utility driver files
*.log Log files containing messages logged by Streamz or utilities.
*.chr Characterization files containing the format description of
resources
*.cnv Conversion files containing methods for conversion of resources
from one format to another
*.ppm Logical project model in XML format
*.ppv Visualization of the project model in XML format
*.ppl Linkz library of the project in XML format
*.pps Streamz library of the project in XML format
The program performs operations on a project depending on 3 required
files:
Petrostreamz Pipe-It View file with default extension .ppv that
contains the project visual description of the elements of the project.
Petrostreamz Pipe-It Model file with default extension .ppm that
contains the project model description including all elements (Resource
and Process) and element dependencies and execution information.
Optionally two additional files may be used for projects that are typical:
Petrostreamz Pipe-It Linkz file with default extension .ppl that
contains the project library of all links used in project.
Petrostreamz Pipe-It Streamz Library file with default extension
.pps that contains the project library of all characterizations and
conversion that can be used in project.
Copyright Notice
Copyright 2006, 2013 Petrostreamz AS. All rights reserved. No part of
this manual may be reproduced, stored in a retrieval system, or
translated in any form or by any means, electronic or mechanical,
including photocopying and recording, without the prior written
permission of Petrostreamz AS, Granaasveien 1, 7048 Trondheim,
Norway

Disclaimer
Use of this product is governed by the License Agreement.
Petrostreamz AS makes no warranties, express, implied, or statutory,
with respect to the product described herein and disclaims without
limitation any warranties of merchantability or fitness for a particular
purpose. Petrostreamz AS reserves the right to revise the information
in this manual at any time without notice.

Pipe-It Manaul 20130806

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Pipe-It Manaul 20130806

Hochgeladen von

Copyright:

Verfügbare Formate

PIPE-IT MANUAL

Copyright 2013 Petrostreamz AS.

Das könnte Ihnen auch gefallen