////
  // Copyright (c) 2021, 2025 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[]

== Schedule Activities

=== Scheduling & Configurations

NOTE: Scheduling an activity sequence requires a fully specified system. See section <<logistics-specification>> for more information on creating this specification.

Scheduling an activity sequence generates a Gantt chart that represents the system execution in time. Within an activity sequence one or more activities can be included. These activities will be scheduled as parallel as possible adhering to the claim/release strategy. If activities cannot be scheduled in parallel the order of this section is applied. An activity typically starts with claiming a Resource, hence this activity can only start if it predecessor activity has released this Resource.

Optionally an offset can be defined for an activity sequence. The scheduler will ensure that these activities will not be started before the offset time.

The easiest way to run a Timing Analysis is to select a dispatching file _and_ a compatible setting file. 
Then right click and select Run As/Timing Analysis.

TIP: Use <ctrl> <click> to select more than one item

image::{imgsdir}/scheduling-select-dispatching-setting.png[]

TIP: You can explore the effect of different settings by combining a dispatching file with different setting files.

For more advanced scheduling options you can use the _Run Configurations_ window. Follow the above selection procedure but 
choose _Run As - Run Configurations..._, or use the dropdown from the green play button in the toolbar on top.

image::{imgsdir}/generate_schedule_runconfigurationsPlayButton.png[]
 
Available scheduling configurations show in the list on the left side of the _Run Configurations_ window below the entry for _Timing Analysis_. 

image::{imgsdir}/generate_schedule_available_configurations.png[]

TIP: A new configuration can be created by using the _New Launch Configuration_ button image:{imgsdir}/generate_schedule_new.png[]

A _Timing Analysis_ run configuration consist of the following elements: 

* *Name* Allows the user to identify the configuration for future usage. 
* *Activity Dispatching* Each configuration refers to one particular _dispatching_ file. This is a required field.
* *Physical settings file* The settings to be used to generate the schedule.
* *Show* 
** *no Gantt chart* No Gantt chart is generated
** *Gantt chart* A Gantt chart is generated and is shown on-screen. The timing of the Gantt chart is based on fixed timing settings and default values. The coloring is based on correspondence between _Activities_ and _Resources_, see below for a more detailed explanation.
** *Gantt chart with critical path* A critical path analysis of the schedule is made, based on fixed timing settings and default values, and is represented in a Gantt chart. The coloring is based on the outcome of the critical path analysis. See below for an explanation of the coloring scheme.
** *Gantt chart using stochastic impact analysis* Based on fixed timing and default values a Gantt chart is generated. The coloring is based on the probability that a task will be on the critical path given the specified timing distributions. In order to determine this probability 200 samples are drawn. For each sample a schedule is determined and a critical path analysis is performed. See below for an explanation of the coloring scheme.

* *Options* 
** *Show web animation* The scheduling produces skeleton files for _Javascript/Paperscript_ based 2D animations. The default animation shows colored dots and by modifying the skeletons arbitrary animations can be produced. If the configuration also generates a Gantt chart an timing indicator is shown on the Gantt chart that is synchronized with the timing of the animation. The _Javascript_ files are located at _analysis/scheduled/animated_.
** *Remove dependencies for claims and releases* Before calculating the critical path the dependencies relating to claims and releases are cut short. As a result claims and releases are not included in the dependency graph and are thus removed from the critical path while preserving the net effective dependencies between actions. *_NB The claims and actions themselves are not removed from the schedule nor is the timing of the schedule influenced by this option._*


=== Gantt Charts

The Gantt chart shows a resource on the Y-axis for every Peripheral which participates in the activity sequence. The X-axis shows the relative time in seconds. Each resource in the Gantt chart shows a low bar and a high bar:

[horizontal]

Low bar:: Represents the claiming of a _Resource_ in the _Machine_ by an _Activity_. This bar is replicated for all _Peripherals_ in the claimed _Resource_. 
High Bar:: Represents an action that is performed by a _Peripheral_. An action can be either a move or an atomic action.

The arrows represent the dependencies between the tasks. 

[NOTE]
====
When a Gantt chart is generated, result files are stored in the project folder _analysis/scheduled_ (i.e. a Gantt file _<file>.etf_). The file name of the _etf_ file is derived from the file name of the _dispatching_ file that is scheduled. The Gantt file is automatically opened in an editor showing the Gantt chart.
==== 

image::{imgsdir}/tutorial_scheduled.png[] 

TIP: The _Properties_ view shows detailed information about the selected bar. 
user attributes, trace points, scheduling phases and repeat steps will also be shown in the properties and can be 
used to filter the Gantt chart.

==== Gantt chart

In case of a Gantt chart without critical path analysis the color of the low bars represent the _Activity_ that holds the claim. Additionally all actions, the high bars, of the same _Resource_ are colored equally. The black arrows indicate the dependencies as specified in the _Activity_ and the gray arrows indicate the dependencies between _Activities_ as derived from the claim/release strategy. +
 +
If a resource is passively claimed by multiple activities then the properties show the activities that apply.
For passive claims the name shown is `Claimed passively by ...`

===== Scheduling the actions in the activities

An action can be scheduled using two types of algorithms: As Soon As Possible (ASAP) or As Late As Possible (ALAP). The default algorithm for all actions is **ASAP**,
unless specified otherwise as described in <<logistics-specification>>. As mentioned previously, resource claiming or releasing are always **ASAP** by design. +
**ASAP** executes each action on a resource as soon as the resource is available, and all preceding actions have finished. +
**ALAP** executes each action on a resource as late as possible. You can see the difference between the two schedules illustrated below.

.ASAP scheduling example for Action A3
image::{imgsdir}/tutorial_scheduled.png[] 

.ALAP scheduling example for Action A3
image::{imgsdir}/tutorial_scheduled-ALAP-new.png[] 

==== Gantt chart with critical path

In project management the critical path is defined as “the sequence of scheduled activities that determines the duration of the project.” 
The same applies for the calculated schedule as visualized in the Gantt chart.

When a critical path analysis has been performed the actions and dependencies are either colored red or grey. Red indicates an action or dependency is on the critical path of the schedule. The low bars can be dark red, light red or grey. Dark red indicates both claim and release are on the critical path. Light red indicates either claim or release, but not both, are on the critical path. Grey is used to indicate neither claim or release are on the critical path.

image::{imgsdir}/generate_schedule_criticalPath.png[]

==== Gantt chart using stochastic impact analysis

The actions in the Gantt chart of the stochastic impact analysis are colored based on the probability that the action is on the critical path taking into account the specified timing distributions. A dark bluish grey indicates that the action will never be on the critical path, bright red indicates the action is always on the critical path. Intermediate colors are used to indicate intermediate probabilities. Tasks can be selected by using the mouse and the Properties window shows the property _Critical_ that displays the probability that the selected task is on the critical path. 

image::{imgsdir}/generate_schedule_stochastic.png[]

==== Filtering

By default the Gantt chart will hide all superfluous information. 
To show all information in the Gantt chart use the Eclipse TRACE4CPS toolbar to _Clear all filters_. 
Now all dependencies a drawn and also the dispatching offset is visualized. 

TIP: For more information about the possibilities in the ESI Trace viewer, see the 
ifdef::eclipse-help[]
link:/help/topic/org.eclipse.trace4cps.ui/html/content/vis.html[TRACE user manual].
endif::eclipse-help[]
ifndef::eclipse-help[]
TRACE user manual in the Help menu.
endif::eclipse-help[]

image::{imgsdir}/tutorial_scheduled_nofilter.png[]
