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 stream 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.
ACCUMULATE <variable name | component name> <DESCENDING | ASCENDING>
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.
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 | 10 |
This command does not have a GUI equivalent.
ADD NOTE <note text>
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.
Given that Strexzel has loaded the stream file:
STREAMZ 1 Note 'Existing note' Char '' Variable v0 real DATA v0 Amount Comp_01 1 0
ADD NOTE New Note will result in the following stream file after saving:
STREAMZ 1 Note 'Existing note' Note 'Source stream file: <current stream file name>, Macro file:<current macro file name>' Note 'My new note' Char '' Variable v0 real DATA v0 Amount Comp_01 1 0
This command is available from the GUI by selecting Edit/Notes from the menu
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.
CALCULATE <reference name> SSQ <component | variable> <component | variable> <component | variable> <component | variable | constant> [MAX | AVG | MID] [EXCLUDEZEROWEIGHTS]
SSQ is calculated according to the formula
![\[
SSQ = \sum_{i=1}^{n}[\frac{(Qc_{i}-Qm_{i})*w_{i}}{Q_{ref}}]^2
\]](tracmath/6f2be44234bc65d34128260c54fe67e1c334e8fc.png)
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.
If a Qref value of zero is computed, it will be substituted with the value 1.
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)
INSERT STREAMS 1 5 Amount INSERT VARIABLE 1 v1 real INSERT VARIABLE 1 v2 real INSERT COMPONENT 1 c1 INSERT 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 output: SSQ:mySSQ=2.8125. Result written to file: untitled.ssq
CALCULATE <reference name> SumProduct <component | variable> <component | variable>
SumProduct is calculated according to the formula
![\[
SumProduct = \sum_{i=1}^{n}C1_{i} \times C2_{i}
\]](tracmath/247f78e9b17dd058fba5809f855010a67ece4e54.png)
CALCULATE <reference name> Sum <component | variable>
Sum is calculated according to the formula
![\[
Sum = \sum_{i=1}^{n}C_{i}
\]](tracmath/f3032a3701216f679ff765c877677b647037b874.png)
CALCULATE <reference name> Min <component | variable>
Min returns the smallest value found in the variable or component column.
CALCULATE <reference name> Max <component | variable>
Max returns the largest value found in the variable or component column.
CALCULATE <reference name> Mean <component | variable>
Mean returns the average value from a sorted set containing the values from the component or variable column.
CALCULATE <reference name> Median <component | variable>
Median returns the median (center) value from a sorted set containing the values from the component or variable column.
CALCULATE <reference name> LR <component | variable X> <component | variable Y>
Calculates the slope and intercept of the least-squares line going through the data set.
Given a Streamz file with two variables, x and y:
The macro command:
CALCULATE myLine LR x y
Will produce the following output, written to the .SSQ file:
CALCULATE output: LINEAR REGRESSION:myLine=A:1, B:10, R^2:1. Result written to file: untitled.ssq
Where A is the intercept with the y-axis, B is the slope of the line, and R^2 is the coefficient of determination.
CALCULATE <reference name> PR <degree> <component | variable X> <component | variable Y>
Calculates the coefficients and intercept of the least-squares polynom going through the data set.
Given a Streamz file with two variables, x and y:
The macro command:
CALCULATE myPoly PR 2 x y
Will produce the following output, written to the .SSQ file:
CALCULATE output: POLYNOMIALREGRESSION:myPoly = x0 :1, x1 :10, x2 :-1.38778e-15, R^2:1
Where x0, x1, x2 are defined as follows:
![\[
y = x_0 + x_1*x + x_2*x^2
\]](tracmath/c9c502f1fb9890c886cf429c67872dceb193fb3b.png)
R^2 is the coefficient of determination.
This command does not have a GUI equivalent.
CHANGE STREAM UNITS <first stream row number> <number of streams> <Amount | Volume | Moles | 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.
This command will redefine units for a number of streams starting at the stream/row number in the first argument.
Given that Strexzel has loaded the stream file:
STREAMZ 1 Char '' Variable v0 real 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 '' Variable v0 real DATA v0 Moles Comp_01 1 0
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 <position> <component name> <molecular weight>
This command can be used to change a component's name or its molecular weight. <position> refers to the component index.
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".
This command is available from the GUI by selecting Component/Edit component from the menu.
EDIT VARIABLE <variable name> <type> <unit>
This command can be used to change a variable's type and unit.
Valid types are (Valid units in parentheses):
We have two variables and two components in a stream file:
After running
EDIT VARIABLE v2 mass kg
the type of the variable is changed from "real" to "mass" and the unit is set to kg.
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 COMPONENT <component name | component index>
If a stream file contains multiple units, Strexzel will display a column for each component-unit combination. If a column has been removed from view with the REMOVE COLUMN command, the column can be brought back into view by running the expose command.
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.
This command is available from the menu by selecting Components/Expose components from the menu. It does not present a separate GUI.
INSERT COMPONENT <POSITION> <NAME> [MW] INSERT COMPONENT <NAME> <BEGINNING | END> [MW] INSERT COMPONENT <NAME> <BEFORE | AFTER> <NAME> [MW]
The command inserts a new component in the model. The command has three syntax variations.
Parameters:
Given a stream file with two variables and two components
'Executing
INSERT COMPONENT 2 NEW1
results in the "NEW1" component being inserted between c1 and c2 at component index 2
and then executing
INSERT COMPONENT NEW2 BEGINNING
results in the "NEW2" component being inserted as the fist component
and then executing
INSERT COMPONENT NEW3 AFTER NEW1
results in the "NEW3" component being inserted after the "NEW1" component.
This command is available from the menu by selecting Components/Insert Component from the menu.
INSERT STREAMS <first stream rownumber> <number of streams> <Amount> | <Volume> | <Moles> | <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.
This command inserts one or more streams, starting at the stream/row number in the first argument.
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 Moles c1 0 0 0 0 0
This command is available from the menu by selecting Streams/Insert Streams from the menu.
INSERT VARIABLE <POSITION> <NAME> <TYPE> <UNIT> INSERT VARIABLE <NAME> <BEGINNING | END> <TYPE> <UNIT> INSERT VARIABLE <NAME> <BEFORE | AFTER> <NAME> <TYPE> <UNIT>
The command inserts a new component in the model. The command has three syntax variations.
Parameters:
Valid types are (Valid units in parentheses):
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.
This command is available from the menu by selecting Variables/Insert Variable from the menu.
LOAD CHARACTERIZATION <filename>
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.
Given the following characterization file named myChar.chr:
CHARACTERIZATION "SBO+RBO" ========================== COMPONENT MW --------- -- SO SG SW END; (of characterization)
Given that Strexzel has loaded a stream file containing the SO component and some streams
Executing
LOAD CHARACTERIZATION myChr.chr
will result in the SG 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
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 <component name> [LEFT | RIGHT] <number of columns> MOVE COMPONENT <component name> [BEFORE | AFTER] <component name> MOVE COMPONENT <component name> [BEGINNING | END]
The command will move a component to a new position in the model.
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.
This command is available from the menu by selecting Component/Move Component(s) from the menu. The command applies to one or more selected components in the stream window.
MOVE STREAMS <row start> <rowend> [TO <row to start at> | UP <number of rows> | DOWN <number of rows>]
This command can be used to rearrange the sequence of streams in the model.
Given that Strexzel has loaded the following model:
executing
MOVE STREAMS 1 2 DOWN 2
will move the first two streams two rows down.
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 <variable name> [LEFT | RIGHT] <number of columns> MOVE VARIABLE <variable name> [BEFORE | AFTER] <variable name> MOVE VARIABLE <variable name> [BEGINNING | END]
The command will move a variable to a new position in the model.
Given that Strexzel has loaded a model containing two variables and two components.
Executing
MOVE VARIABLE a AFTER b
will result in the two variables changing places.
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 <name>
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.
Given that Strexzel has loaded the stream file:
STREAMZ 1 Char '' DATA Amount C1 Amount C2 0 0
Executing
NAME CHARACTERIZATION myChr
and saving the model will result in the Char now containing the new name.
This command is available from the menu by selecting File/Name characterization from the menu.
REMOVE COLUMNS <index1> [index2] ... [index n]
The command removes variables and or components by view index (visual index, not model index).
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.
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 NAMED <COMPONENT NAME> | <INDEX>
Removes a component based on name or its model index.
Given that Strexzel has defined the following model:
Executing
REMOVE COMPONENT 2
will remove the c2 component.
This command is available from the menu by selecting Component/Remove component from the menu. It applies to a selected component and does not present a separate GUI.
REMOVE STREAMS <rownumber> [rownumber] ... [rownumber]
The command removes streams from the model.
Given that Strexzel has defined the following model:
Executing
REMOVE STREAMS 1 3 5
will remove streams 1,3 & 5 from the model.
REMOVE VARIABLE UNUSED | ALL REMOVE VARIABLE NAMED <variable name>
The command removes variables from the model.
Given that Strexzel has defined the following model:
Executing
REMOVE VARIABLE ALL
will remove all the variables.
This command is available from the menu by selecting Variables/Remove variable(s) from the menu.
SAVE CHARACTERIZATION <filename>
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.
Given that Strexzel has loaded a model containing the components c1 & c2 with respective molecular weights of 20 and 10.
Executing
SAVE CHARACTERIZATION myChar.chr
will save a characterization file with the following contents:
CHARACTERIZATION "" =================== COMPONENT MW --------- -- c1 20 c2 10 END; (of characterization)
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 <NAME> <VALUE>
Defines a constant that later can be referenced in mathematical expressions or formulas.
Executing
SET CONSTANT pi 3.1415926
will make the constant pi available in expressions.
This command does not have any GUI equivalent.
SET FORMULA <component name | variable name> [=] [expression]
The command assigns a formula to a component or variable. An empty <expression> will remove the current formula.
Predefined constants:
Allowed operators:
Defined numerical functions:
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):
Defined string functions:
Comments:
SET FORMULA res = if (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 res = (a >=1) ? 0 : 3
Nested if example:
SET FORMULA res = if (a >=1, if (b==3, 2, 3), 3)
Using combinations of logical operators inside if-statement:
SET FORMULA res = if ((a > 1) and (b<3), 1, 0)
Concatenation:
SET FORMULA res = a // b
Substring with zero based offset:
SET FORMULA res = substr(a, 1, 1)
Convert from a string type (b) to real (res):
SET FORMULA res = str2dbl(b)
SET FORMULA res = 2*sin(varA)+10*cos(varB)
SET FORMULA res = "c2+c3"/2
Where "c2+c3" is a component name that has to be enclosed in quotes because it contains an operator.
SET FORMULA res = v::a+c::a
Where name ambiguity requiring type prefix.
SET FORMULA res = rnd(-5,5)
Assigns random numbers in the interval [-5, 5] to the res column.
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 <precision>
The command changes the models precision (defaults to 6)
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 '' Variable b real Variable a real 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
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 <seed value>
Initializes the internal pseudo random generator with <seed value>
SEED 42
This command is not available via the 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.
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 copied/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.
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 <TAB> 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.
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.
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 int 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.
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.
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:
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:
| Argument | Description |
| --edit | Forces Strexzel to open in GUI mode. Useful for opening a stream file and a corresponding macro file from the command line |
Unless --edit 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.
To avoid conflicts between macro commands and variable / component names, the following names are reserved and cannot be used to name variables or components: