Referencing workflows¶

pSeven Enterprise allows you to automate engineering calculations and analysis by interfacing various CAD/CAE systems, product data management (PDM) systems, and others. It also provides wide capabilities for leveraging its own algorithmic library in combination with third-party design tools. Their interaction and data exchange occur without human intervention, which can significantly speed up the computation process and reduce the likelihood of errors, especially when performing complex, multidisciplinary projects.

The central concept in using pSeven Enterprise is workflow, which represents the computation process as a set of blocks and links between them. Each block in a workflow can be considered as a part of a certain task, and the entire workflow as the decomposition of that task. The implementation of complex projects often requires the joint use of several workflows, representing different tasks, for example:

Designing product components in CAD systems, which specifies their geometry, composition and internal characteristics.
Calculating and optimizing the characteristics of individual components using CAE systems, usually carried out in several stages.
Aggregate analysis and interpretation of results.

The implementation of a project in the form of several interconnected workflows ensures the preservation of knowledge and expertise, practices and design methods, as well as reusing existing field data and computational experiments. Each individual workflow can be created and maintained by a separate team of specialists, and all workflows are combined into a complete multidisciplinary workflow. At that, different teams are working in the same environment, in which the sharing of workflows, resources, and computation results is easily controlled by setting access rights.

The described approach assumes the composition of the main workflow referencing child workflows created and maintained by different enterprise teams. Referencing child workflows enables the enterprise to flexibly compose a complete workflow, while providing the ability to edit and run child workflows independently, as well as to reuse a certain workflow by referencing it from multiple workflows.

Understanding workflow reference¶

A straightforward way of making some child workflow a part of the main one is copying: group all blocks of the child workflow along with their links into a single Composite block (see Managing composite blocks), and then copy that Composite block into the main workflow. Combining workflows in this way has a number of drawbacks, such as:

The main workflow actually contains a duplicate of the child one in the state as of the time it was copied. This duplicate is detached from its source, making it difficult to update when modifying the child workflow.
If the same workflow needs to be made a part of several larger workflows, copying creates several independent duplicates. Synchronizing changes to independent duplicates requires additional effort.
The duplicate does not contain workflow run results, which makes it impossible to reuse the data of computational experiments performed using that workflow. Each run of the main workflow causes a new run of the child workflow duplicate.

To overcome these drawbacks, the main workflow can reference rather than copy the child workflow. The key difference between referencing and copying is the elimination of a static duplicate: the Composite block that encloses the child workflow is created not while editing the main workflow, but when initializing its run. Thus, each run of the main workflow gets the child workflow in its current state, including all changes made at the moment. The same applies to publishing the main workflow to AppsHub: the published app contains a copy of the child workflow as of the time of publication.

Workflow reference block¶

A child workflow reference is a special Workflow reference block in the main workflow. This block is the constructor of the child workflow's enclosing Composite block, being created anew at each run of the main workflow. The reference block holds all the information needed to create the enclosing Composite block and connect its ports to the inputs and outputs of the referenced workflow within that block.

When creating a workflow reference block, you select the workflow to be referenced. This can be a workflow from your home folder, or a shared workflow owned by a different user. This block creates and maintains a reference to the selected workflow without creating its duplicate in the main workflow. A Composite block with a copy of the referenced workflow is created "on the fly" when you run the main workflow.

The Composite block for the referenced workflow is derived from the workflow reference block, therefore the latter has the same attributes as the Composite block, including:

Working directory setting. The Composite block that holds the referenced workflow inherits the working directory setting of the workflow reference block. For example, if the working directory of the workflow reference block is set to indexed, the generated Composite block will also have the indexed working directory.
Input and output ports. Input parameters of the referenced workflow map to input ports of the workflow reference block, and outputs of the referenced workflow map to output ports of the workflow reference block. In this way, you can pass input data and retrieve output data from the referenced workflow. Parameter values of the referenced workflow become values assigned to input ports of the workflow reference block. Input ports of the workflow reference block can be made parameters of the main workflow, output ports of that block can be added to results of the main workflow.
Batch mode and parallelization settings. Input ports of the workflow reference block can be switched to batch mode. As a result, batch mode is set for the corresponding ports of the generated Composite block. The workflow reference block also automatically enables batch mode on the ports that have batch mode enabled in the referenced workflow. The Maximum parallelization setting for the generated Composite block is inherited from the respective setting of the workflow reference block; its value can differ from that specified in the referenced workflow.

During a main workflow run, the workflow reference block is replaced by the Composite block that executes a copy of the referenced workflow and issues the results through its output ports. In this way the results of the referenced workflow can be passed to other blocks as well as saved in the results of the main workflow. The workflow reference block is also replaced by the Composite block containing a copy of the referenced workflow when you publish the main workflow to AppsHub.

The main workflow can include several referenced workflows by using a separate block to reference each one. A referenced workflow can also include a block referencing another workflow, thus building a hierarchy of references to child workflows in the main workflow.

Reference-to-Composite conversion¶

When initializing a run or publishing the main workflow, a Composite block is created in it, containing a copy of the referenced workflow. Converting a workflow reference to a Composite block containing a copy of the referenced workflow has the following features:

The Composite block replaces the workflow reference block, inheriting its input and output ports along with all their links within the main workflow.
Ports representing parameters in the referenced workflow become input ports of the Composite block. If the referenced workflow contains blocks that have input ports added to workflow parameters, those ports are uplinked to the corresponding input ports of the Composite block. The current parameter values are assigned to the Composite block input ports as their initial values. All ports that were parameters in the referenced workflow lose the status of parameters in the main workflow. Only those input ports of the Composite block that are declared parameters in the workflow reference block become parameters of the main workflow.
Output ports of the referenced workflow that represent its results become output ports of the Composite block. All result ports of the referenced workflow lose the status of results in the main workflow. Only those output ports of the Composite block that are declared results in the workflow reference block become results of the main workflow.
The generated Composite block has the working directory and parallelization settings the same as the workflow reference block. Its batch mode and other port settings are also the same as on the workflow reference block.

The referenced workflow requires its run resources to function properly. Such resources are files and folders that are marked for copying to the run directory, that is, the run directory prototype (see Workflow run directory). These are files and folders you see on the Files tab in Explorer when you open the workflow directory.

To provide the referenced workflow with access to its run resources, the run directory prototype of the referenced workflow is copied to the run directory of the main workflow as follows:

In the run directory of the main workflow, the working directory for the generated Composite block is configured in accordance with the working directory setting that was selected on the workflow reference block.
The run directory prototype of the referenced workflow is copied to the working directory of the generated Composite block.

If the working directory for the workflow reference block is set to parent, the run directory prototype of the referenced workflow is copied to the working directory of the workflow reference block's direct ancestor in the main workflow's block hierarchy. If a workflow reference block with thе parent working directory setting is in the root of the main workflow, then the run directory prototype of the referenced workflow is copied to the run directory root of the main workflow.
Files copied from the run directory prototype of the referenced workflow take precedence and replace files of the same name and path in the main workflow's run directory.

The examples below help better understand how the run directory of the main workflow is structured depending on the workflow reference block's working directory setting. These examples use the following run directory prototype for the referenced workflow:

🏠.Composite - The working directory prototype for a certain Composite block.
- Data - A data file in the working directory prototype for that Composite block.
Model - A file in the workflow directory root of the referenced workflow.

The above run directory prototype would result from the following contents of the referenced workflow:

🏠 - The root of the referenced workflow.
- Composite - The Composite block with the working directory set to single.

Let the contents of the main workflow be as follows:

🏠 - The root of the main workflow.
- Reference - The reference block for the workflow described above.

If the working directory for the Reference block is set to single, then the contents of the run directory for the main workflow is as follows:

🏠.Reference - The working directory of the Composite block derived from the Reference block.
- Composite - The working directory of the Composite block inherited from the referenced workflow.
  - Data - The data file copied from the working directory prototype of the Composite block held in the referenced workflow.
- Model - The file copied from the workflow directory root of the referenced workflow.

As the Reference block has the single working directory setting, the working directory of the derived Composite block is represented by a separate folder named 🏠.Reference, and the run directory prototype of the referenced workflow is copied to that folder. The working directories for iterations of the derived Composite block are populated in the same way if the Reference block has the indexed working directory setting.

If the working directory for the Reference block is set to parent, then the contents of the run directory for the main workflow in this case is as follows:

🏠.Reference.Composite - The working directory of the Composite block inherited from the referenced workflow.
- Data - The data file copied from the working directory prototype of the Composite block held in the referenced workflow.
Model - The file copied from the workflow directory root of the referenced workflow.

As the Reference block has the parent working directory setting, the working directory of the derived Composite block is the run directory itself. Therefore, the run directory prototype of the referenced workflow is copied to the run directory root of the main workflow. To indicate the origin of the derived Composite block, the name of the working directory for its child Composite block is supplemented with the name of the Reference block.

Working directory path¶

When initializing a workflow run, the workflow reference block is replaced with the generated Composite block, the working directory of which has the same contents as the run directory for the referenced workflow. Accordingly, within a main workflow run, blocks of the referenced workflow can get the path to the working directory through the internal information port @Working directory path of the generated Composite block. To create links to that port, the workflow provides an internal information of the same name (see Workflow as a composite block).

When executing the workflow standalone, its blocks can use the workflow's @Working directory path internal port to get the path to the current run directory. If the workflow is run by reference in the main workflow, each link to the @Working directory path internal port of the referenced workflow is replaced with a similar link to the @Working directory path port of the generated Composite block. By using those links, blocks in the referenced workflow can get the path to the working directory of the Composite block derived from the workflow reference block.

Using workflow reference¶

You can create a workflow reference block in your main workflow in a few ways:

In the Explorer pane, locate the workflow to be referenced and drag it from Explorer to the main workflow.
From the menu on the workflow edit toolbar, select the Add workflow reference... command to open the workflow reference dialog. There, select the workflow to be referenced, or input its path.

When you select the workflow reference block in the main workflow, the Workflow reference properties pane displays the current path to the referenced workflow. You can select a different workflow to be referenced by using the Reference another workflow... command from the menu on the workflow edit toolbar.

Unlike a Composite block, a workflow reference block itself does not contain any workflow, therefore, its referenced workflow opens on a separate tab. To open the referenced workflow for editing, double-click its reference block on the tab where you are editing the main workflow, or select the Open referenced workflow command from the menu on the workflow edit toolbar.

The workflow reference block has the same configuration elements as any Composite block. In the block properties pane, you can:

Set the working directory. The available options are the same as with a Composite block, see Working directory settings for details.
Add ports and manage their settings. Port settings for a workflow reference block are similar to Composite block port settings, see Configuring inputs and outputs of a composite block for details.

Input ports of the workflow reference block have batch mode always enabled, if batch mode is enabled for the corresponding ports of the referenced workflow. If you need to disable batch mode on the workflow reference block, in this case you must edit the referenced workflow, disabling batch mode for its inputs.
Enable parallelization. To enable parallelization, the Maximum parallelization setting must be greater than one; in addition, at least one of the input ports must be configured as a batch mode port.

During a main workflow run, the workflow reference block actually turns into a Composite block with settings inherited from the workflow reference block. This Composite block contains a copy of the referenced workflow (see Workflow as a composite block). The same happens when the main workflow is published to AppsHub.

In the case of a shared workflow that includes a referenced workflow, the behavior of the workflow reference block depends on the access rights setting. Let's assume the owner of the main workflow shares it with Alice, granting her either read-only or read-write access to that workflow. As a result:

Alice can run the main workflow regardless of her rights to access the referenced workflow. The computations using the referenced workflow are performed even if Alice has no access to that workflow.
Having no access to the referenced workflow, Alice cannot open it from the main workflow, but she can contact the owner of the referenced workflow with a request to provide access or make changes, if needed. The referenced workflow is identified by its path and name, which is displayed in the properties pane for the workflow reference block.
If Alice has read-write access to the main workflow, she can make any changes to the workflow reference block. Specifically, she can manage the settings and initial values of the ports, select a different workflow to be referenced, etc.

It is possible for the main workflow to reference a shared one. Main workflow users with read-write access to the referenced workflow can edit it by double-clicking its workflow reference block. Those with read-only access can open the referenced workflow for viewing this way.