This tutorial is the first in series of three tutorials that provide a general practical introduction to pSeven. Introductory tutorials do not involve any real task yet and describe a toy workflow which uses a few simple blocks purely for explanation purposes.
In case you find something described in this tutorial unfamiliar, see section Introduction for general information on pSeven interface and functions.
Every workflow in pSeven is a part of some project. A project can contain multiple workflows and provides a database to store workflow results. Projects are also used to organize files — for example, keeping related workflows and their input data together.
All tutorials found in this manual assume you are working with the Tutorials project. If you have not created this project yet, see Tutorial Project.
To add a workflow, first of all you need to open or create a project that shall contain it.
- Open the Tutorials project.
- Select File ‣ New Workflow from the main menu. You can also use the new workflow shortcut on the Welcome tab or select New Workflow from the Project pane context menu.
When you add a workflow in Workspace, pSeven automatically switches to Edit.
In Edit you now see a new empty workflow . Note that the workflow is untitled — it means that it is not saved to a file yet and thus it will not yet appear in project contents in Workspace.
You can also add workflows in Edit using the button on the tab bar and edit multiple workflows switching between their tabs.
Workflows in pSeven can have descriptions that are edited in workflow configuration.
- Add a description to your workflow: click on the edit toolbar to open the workflow configuration dialog. Input some text on the General tab.
Click to save the description and close the dialog. Later you can edit the description at any time.
To save a new workflow to a file (so that it appears in Workspace), you can use the save button on the tab bar or select File ‣ Save Workflow from the main menu.
- Save the workflow before continuing: click on the tab bar and input a file name in the dialog (for example, SimpleWorkflow).
Note that workflows are always saved to the project directory. You cannot save a workflow outside the current project or to a subdirectory in the project.
When saved, the new workflow name appears on its tab in Edit. You can switch to Workspace and verify that the workflow file now exists in your project.
To show the tooltip, select the workflow in the Project or the Filesystem pane. Note that file attributes (type, size and modification date) are now shown in the tooltip.
Switch back to Edit to proceed with creating a workflow: adding blocks and connecting them with links.
Blocks are added to the workflow from the Block Library pane in Edit.
The library uses tag sorting. You can expand the tag nodes to see a list of blocks. To find a specific block you can also filter the library by block name or tag. For example, rand will find the Random block, and tegra will find all Integration blocks (the filter is case insensitive and can match partial names).
To add a block to the workflow, you can either double-click its name in the Block Library pane or drag it from the pane to the edit area.
- Add a Random block — for example, expand General and double-click Random .
Every block in a workflow has a unique name in order to tell blocks of the same type from each other. When adding a new block, you have to specify its name in the Add Block dialog.
- Type the name in the dialog (for example, RandGen) and click . Note that the name has to begin with a letter, and some special symbols are not allowed.
The RandGen block is added and now you can see it in the workflow.
Hovering the mouse cursor over a block brings up an information tooltip . If you select (single-click) a block, you can also find these details on the information panel (this panel can be toggled with the button ).
The RandGen block has been added with the default configuration which makes it generate and output a single random value. However the majority of blocks in pSeven (and Random, as well) have various configuration options which can change block behavior, its inputs, outputs and other properties, as you can see further.
The RandGen block which is currently configured to generate a single random value (default) can also fill vectors or matrices with random values. The output mode is changed in the block configuration.
- Double-click the RandGen block to open the configuration dialog. Default configuration generates a scalar value from the uniform distribution.
If you switch to the Ports tab in the configuration dialog, you can note that currently there is a single output port value which outputs the generated scalar (do and done are special signal ports common for all blocks; these ports can be used for block synchronization).
Making changes in block configuration often results in altering its inputs and outputs. For example, let us reconfigure RandGen to output a random matrix.
- Switch back to the Configuration tab in the dialog.
- Set the output mode to matrix .
- Change other options if you wish (double-click option value to edit). Non-default options are displayed in bold .
If you look at the Ports tab after these changes, you can see that two new input ports are added: rows and cols.
Values received to these ports set the number of rows and columns in the generated matrix. Note that these settings are not present in block options, so you are required to send these values to input ports — otherwise the block will not start.
- Click in the configuration dialog to save settings and close the window.
Note that pSeven informs you that there is a problem with the workflow by sending warnings to the Issues pane.
Toggle the Issues pane to see what the problem is. You can see two warnings informing that required input ports do not receive any value; as a consequence, the block that is the source of these warnings will not start when you run the workflow. The third warning tells you that an output value is not used anywhere.
Note also that if you have changed block options, these changes (non-default option values ) are now listed on the information panel.
Reported issues can have different severity levels. A warning informs about a non-critical misconfiguration which does not prohibit to run the workflow. As for the current workflow, for example: you could run it right now, ignoring the warnings; there would be no block errors, but the workflow would simply do nothing. An error is a critical issue, and a workflow with errors will cease to run.
To fix current issue with RandGen inputs, the values that determine the matrix size have to be defined somewhere and sent to the rows and cols input ports of the RandGen block. A straightforward way is to use a Const block that can define and output constants.
- Add a Const block to the workflow.
- This block shall set matrix size: name it Size .
Double-click Size to open block configuration. By default, it defines no constants, so the list is empty.
To add constants, use the context menu or the button to bring up the Add Constants dialog. You need to define two constants, for the number of rows and columns. Both constants can be added at once — just list them in the Name field:
- Name: rows, cols (note that the names are case-sensitive).
- Value: any integer value (for simplicity purposes, set a small value like 5).
Both constants will have the same value, but you can change it in block configuration afterwards. Verify that two constants have been added.
Adding constants also adds output ports (with the same names) to the Size block. The constants, and hence their ports, are intentionally named the same as RandGen inputs: this is needed for the autolinking feature explained below. If you mistyped a name, double-click it in the Name column to correct. You can also change values in the Value column if you wish: double-click a value to edit, or hover it and click .
Click in the block configuration dialog to save settings.
If you look at the Size block information panel, you can note that two new output ports were added, and both are assigned some values. You can now link the blocks to send these values to RandGen inputs.
The monitoring mechanism in pSeven allows to capture the activity of any port in a workflow, both input and output. When a port is monitored, all data it sends or receives is immediately copied to the project database available in Analyze.
Monitoring is set up in two steps:
- First, you select the ports that allow their monitoring.
- Second, you select which ports (from allowed ones) are actually monitored while the worfklow runs. This step is optional: by default, monitoring is enabled for all ports selected at the first step.
This way you can first select only the important ports, then adjust monitoring settings quickly without referring to a full list of workflow ports. In particular, it helps in the case of a complex workflow that is created and run by different users.
Ports that allow their monitoring can be selected in block configuration.
- Double-click RandGen to open the configuration dialog.
- Switch to the Ports tab .
- Select the value port for monitoring .
- Click to save settings and close the dialog.
Select RandGen to view its details.
The information pane shows more changes done to the block: rows and cols inputs are now connected; value output is disconnected (its name is grayed out) but monitored . Note that monitoring resolved the issue from before: there are no more warnings on the Issues panel because now pSeven knows how data from the value port is used.
A new monitor for the port you have just selected now appears in Run.
- Switch to the Run screen and note that a new monitor “Randgen.value” appeared in the Configuration tab.
Here you can disable and enable monitoring quickly (new monitors are enabled by default). This completes the essential configuration, further settings are optional.
Note that the monitor’s name and description are defaults copied from RandGen properties. pSeven allows to change them if you want to make monitoring settings in Run easier to understand. For example, you can add a description explaining the role of this port in the workflow, which will hopefully help another user to better understand what data is monitored.
Names and descriptions of monitored ports are edited in workflow configuration (this is the same tool you used earlier to add a workflow description; it is available both in Run and Edit).
- Open workflow configuration and switch to the Monitoring tab .
- This tab provides an overview of existing monitors. Note that if there are many of them, you can filter the list by partial name (case insensitive) to find the one you need. You can also add and remove monitors here instead of selecting ports in block configuration. Finally, you can change the name of any monitor (give it a new alias) and edit its description.
- Double-click the default alias to edit, remove it and type a new name. It is best to keep this name short and simple, for example: Random Data.
- Double-click the default description and replace it with your text. Description works better when you want to add more details describing the monitored value.
- Click to save settings and close the dialog.
Note the changes in monitoring configuration.
One of the reasons to set meaningful aliases is that the alias becomes the name of the record in the project database that stores monitored data. So, current configuration is:
- Monitor the value output of the RandGen block (capture all data output to this port).
- Save this data to the project database for further analysis, storing it under a record named “Random Data”.
Would you not set an alias, the record would be given a default name in “Block.port” format (“RandGen.value”). This becomes important in analysis of complex tasks with many monitored values. The idea is that the data itself — its meaning, type, structure, other details which you can specify in alias and description — is more relevant to the user than its source block and port — which, if required, can be traced back from the alias using the workflow configuration tool.
Now you have a very simple workflow that generates and saves some random data.
This workflow uses only the most basic capabilities found in pSeven, but it is ready to launch. You can now run the workflow to see the results.
- Verify there are no validation issues and correct, if any.
- Verify the data monitor you added earlier is enabled .
- Save your workflow and click to run it .
When you run a workflow, the bottom panel in Run automatically switches to the run log.
The Run Log tab always shows the last run log of the current workflow. Previous run logs, if needed, can be found in the pSeven console . Note that the console holds a single log common for all opened workflows, while the information in Run Log is specific to the workflow you currently use (edit or run) — that is, there is a separate last run log on each workflow tab .
When the workflow is complete, a message regarding its status is displayed in the Statistics pane (together with the details on block statistics and execution time).
The status can be either “Finished successfully” or “Finished with errors”. You may single-click details to get some extra information about error details.
The current workflow should run without errors. Both its blocks started once: Size output constants that set matrix size and RandGen generated a random matrix after receiving these settings. Size (Const) is one of the few blocks that do not require any input to start — that is why it was selected as a “workflow starter”.
The workflow in this tutorial is linear, but in general workflows can contain loops. A typical example is any optimization workflow, which is always built around an optimization loop controlled by an Optimizer block (see the Optimization Basics tutorial, for instance; a generic example is also available in the Sampling Loop tutorial). Blocks inside the loop start multiple times, in which case block statistics become more useful — for example, you can tell the number of function evaluations by looking at the number of block startups inside an optimization loop.
As you can see, blocks starting order is in fact determined by links between them: a block starts as soon as it has all required data, and links control how data travels between blocks. This rule is known as the data flow concept. Note that there is no need to specify block execution order explicitly; however, you can delay the startup of a certain block until another block finishes (using the do and done ports).
Now that we have briefly described what happens during a workflow run, let us switch to Analyze to discuss its results.
In Analyze you can see that the data collected from your workflow now appears on the Project Database pane.
The project database is common for all workflows in the project, and each workflow creates a node named the same as the workflow file. Its child nodes store run results. By default, each run creates a new child node, using the workflow start timestamp to generate the run name. Also there is a special node named “<last run>” — this is an alias for the most recent run record.
Alternatively, you can set a fixed run name in Run to collect all data under the same record. Such setting appends new results to previous ones without overwriting them. Note that in this case “<last run>” references the fixed name and will also contain data from all runs — not only from the actual last run.
Reports are explained in more detail in the Results and Reports tutorial. In particular, it provides examples of using a fixed run name and the “<last run>” record.
A run record stores various information including basic statistics, workflow input values and so on. For now we are only interested in the data found in “Monitoring”.
- Expand “Monitoring” to see the “Random Data” record which stores the data obtained by the monitor you added earlier.
The “Random Data” record can be easily added to a report as a data sample. After this you can use it for plotting and analysis.
- Click on the tab bar or select File ‣ New Report from the main menu to create a new report.
- Drag the “Random Data” record to an empty area in the report.
- pSeven automatically creates a sample viewer to show the data.
pSeven provides a quick plotting function which instantly creates a plot of desired type based on an existing sample viewer.
- Click the parallel coordinates button on the report toolbar to get a plot of “Random Data” in parallel coordinates (this is one of the plot types used to visualize multidimensional data; here, each polyline represents a matrix row which can be understood as point coordinates in 5-dimensional space).
Quick plots use default configuration; after adding a plot, you can click in the plot title bar to adjust it (change fonts, labels, colors and other details).
Note that a report can include many tables and plots, so there is no need to create a new report for each. Nevertheless you can add multiple reports to a project, view and edit them simultaneously (similar to workflows).
To save a report, click on the tab bar or select File ‣ Save Report. Same as a new workflow, a new report is untitled until you save it to a file, and report files can be saved only to the project directory.
This tutorial includes only the most essential information and omits many details. It is also strongly recommended to complete the next two tutorials (Workflow as a Tool, followed by Results and Reports) before starting any other.
- Save the workflow you have created in this tutorial: it will be required further. The report you have created when viewing the results is no longer needed, but you can also save it if you wish.
Note that the tutorials mentioned above continue with the same workflow. Workflow as a Tool shows how to customize the workflow interface in Run, using the current workflow as an example. Results and Reports uses data generated by this toy workflow when explaining how to create a report that automatically processes workflow results.