////
  // Copyright (c) 2021, 2026 Contributors to the Eclipse Foundation
  //
  // This program and the accompanying materials are made
  // available under the terms of the Eclipse Public License 2.0
  // which is available at https://www.eclipse.org/legal/epl-2.0/
  //
  // SPDX-License-Identifier: EPL-2.0
////

include::_initCommon.adoc[]

== Throughput per Resource Editor

The throughput per resource editor helps to identify where the specification can be optimized for throughput performance of the system.

As the specification is partitioned in multiple files (i.e. dispatching, settings, schedule, etc.) this makes it rather difficult to identify where the specification can be optimized for throughput. 
For this a new view has been designed which provides an overview of the most critical information with respect to throughput optimization for a specific activity dispatching sequence.

For each resource in the specification a tab page is available in the editor. 
The tab page shows an ordered table with all actions that are relevant for its resource. 
More information about the table content can be found in section <<the-resource-actions-table>>.
The _Outline_ view shows an overview of the throughput per resource and the throughput of the total activity dispatching sequence, for more information see section <<the-outline-view>>.

=== Opening the Throughput per Resource Editor

The Throughput per Resource editor shows information for a specific activity dispatching sequence.
For this reason the editor can be opened by means of the context menu of a particular dispatching file.
The use of the context menu is needed as by default the <<create-activity-dispatching-specification, Dispatching Editor>> is opened when double-clicking a dispatching file.
To open the Throughput per Resource editor right-click a dispatching file in the _Model Explorer_ view and select _Open With -> Throughput per Resource Editor_ from the context menu.

image::{imgsdir}/throughput-per-resource-open.png[]

NOTE: Eclipse remembers the last editor used to open a file. When double-clicking the file this editor will be used again to open the file. The _Open With_ context should be used to open the file using another editor.

=== The Resource Actions Table

The resource actions table contains a row for every action in the activity dispatching sequence that is relevant for the resource.
The rows are ordered as such that their actions are ordered in topological order w.r.t. the activity dispatching sequence. Topological ordering basically means that an action will never be listed before all actions required to be executed prior to the action.
So this doesn't guarantee that two succeeding actions in the table are executed in sequence as they might be executed in parallel. 
For more information on how the action sequence is determined please see section <<calculating-the-throughput-per-resource>>.

In general a table cell will be gray when its information is not applicable for the action at that table row. 
When needed the data in the table either can be refreshed or reloaded.

Refreshing the data - by means of the image:{imgsdir}/refresh.png[] toolbar button - will update all data in the resource actions table and _Outline_ view reflecting the current state of the editor including already made changes.

Reloading the data - by means of the image:{imgsdir}/reload.png[] toolbar button - will discard all made changes and reload the specification models. This action can be used to reload changes in the specification which are made outside the Throughput per Resource editor. 

WARNING: The Throughput per Resource editor will not detect added/deleted resources, axes and setpoints. When these are modified the Throughput per Resource editor needs to be closed and re-opened again. 

The table contains the following columns:

[horizontal]
Peripheral:: The fully qualified name (format _<Resource Name>.<Peripheral Name>_) of the peripheral performing the action.   

Action:: The fully qualified name (format _<Activity Name>.<Action Name>_) of the action.  

Name / From / Distance:: Either the name of the peripheral action, the start position or the distance of the move. 

To:: The end position for the move (if applicable).

Settling:: The axes that require settling for the move.

Old _<Axis>_:: The start location per axis for the move.

New _<Axis>_:: The end location per axis for the move. An icon image:{imgsdir}/ArrowUp.png[] indicates that the axis is adjusted as part of the move.
The image:{imgsdir}/IntegerFieldEditor.png[] icon in the column header indicates that the values in this column may be edited. 
Profile:: The motion profile name for the move.
The image:{imgsdir}/IntegerFieldEditor.png[] icon in the column header indicates that the values in this column may be edited.

_<Setpoint>_ time:: For every setpoint, the minimum time needed to adjust the setpoint using its axis motion profiles. 
In other words, the time needed to adjust the setpoint conforming to its motion profile, not taking into account the adjustment of other setpoints, thus no stretching will be applied.   

Time:: The time needed to perform the action. An icon image:{imgsdir}/critical.png[] indicates that the action is on the critical path of the resource. 
For more information see section <<calculating-the-throughput-per-resource>> and section <<gantt-chart-with-critical-path>>. 
The image:{imgsdir}/IntegerFieldEditor.png[] icon in the column header indicates that the values in this column may be edited. 
Do note though that this only applies for the times of peripheral actions and not for moves. 

WARNING: When editing: If the setting file contains a composed expression it will be replaced with the edited constant value.


image::{imgsdir}/throughput-per-resource-editor.png[]

=== The Outline View

The image in the previous section also shows the _Outline_ view. 
This view shows a table with an overview of the throughput per resource and - in the last row - the throughput for the total activity dispatching sequence.
For more information on how the throughput is calculated for a resource, please see section <<calculating-the-throughput-per-resource>>.

The table contains the following columns:

[horizontal]
Resource:: The resource for which the throughput is calculated.
Makespan:: The total time needed to perform all resource actions in the activity dispatching sequence. 
No. Iterations:: The number of iterations for this resource in the activity dispatching sequence, for more information see section <<specifying-the-number-of-iterations>>.
Iteration Makespan:: The total time needed to perform exactly 1 iteration in the activity dispatching sequence. 
Throughput:: The theoretical maximum number of iterations per hour that this resource is capable of executing.

=== Calculating the Throughput per Resource

This section provides some background information on what is meant by calculating the throughput per resource.

Though the systems throughput performance is determined by the full orchestration of all actions for all resources and peripherals in the system, sometimes it is good to know which resource is most critical in this orchestration.
When calculating the throughput per resource the theoretical maximum throughput of the resource is calculated as if no actions of other resources are limiting its throughput, with the exemption of all actions in the 'entangled' section of an activity.

.The entangled section of an activity
With the entangled section of an activity the section is meant in which multiple resources are working together in harmony, most likely to transfer a product from one location to another.
Maybe this can be explained a bit easier by use of the following example. 
The figure below shows the schedule of an activity dispatching sequence with an overlay that illustrates the pre, post and entangled sections of an activity. 
The activity 'Robot1_GiveTo_Robot2' is repeated twice in the dispatching.

image::{imgsdir}/throughput-per-resource-schedule1.png[]

In the entangled section Robot2 first needs to clamp before Robot1 is allowed to unclamp. 
This causes a gap in the schedule of Robot1 as illustrated by the blue rectangles. 
As these gaps are within the entangled section, they are kept in the schedule when calculating the throughput for Robot1.

Additionally to gaps in the entangled section, Robot2 also has gaps in the schedule in its prepare section, as illustrated by the yellow rectangles in the schedule. 
These gaps are caused by Robot1 delaying Robot2.
For calculating the throughput for Robot2 the pre and post sections of Robot1 will be omitted and a schedule will be used as illustrated in the following image.

image::{imgsdir}/throughput-per-resource-schedule2.png[]