Rewrite of Scheduler planning

Summary:
This is a full rewrite and verification of all steps of evaluation of a list of scheduler jobs with the following existing constraints:

• Dark sky, which schedules a job to the next astronomical dusk/dawn interval.
• Minimal altitude, which schedules a job up to 24 hours away to the next date and time its target is high enough in the sky.
• Moon separation, combined with altitude constraint, which allows a job to schedule if its target is far enough from the Moon.
• Fixed startup date and time, which schedules a job at a specific date and time.
• Culmination offset, which schedules a job to start up to 24 hours away to the next date and time its target is at culmination, adjusted by an offset.
• Amount of repetitions, eventually infinite, which allows a job imaging procedure to repeat multiple times or indefinitely.
• Fixed completion date and time, which terminates a job at a specific date and time.

The UI now displays target altitudes at the current simulation time, and at startup and completion times. It also displays the lead time or gap time between jobs to help with imaging time optimization. Warnings appear in some situations for the user to detect problematic situations, such as a job completing under the minimal altitude.

The rewrite starts by estimating the imaging duration of each job, and eventually reorders them based on option "Sort Jobs by Altitude and Priority".
The reordering algorithm sorts jobs by altitude, considering a setting target is higher than a rising target.
When the option is enabled, targets will be automatically sorted whenever jobs are evaluated, using the current simulation time for altitude calculations.
When the option is not enabled, a button is available to reorder jobs manually, using the first job startup time for altitude calculation.
This reordering helps to optimize imaging time when preparing a schedule with multiple targets.

The rewrites then proceeds to sequence jobs based on their order in the list, resolving each constraint one after the other.
The sequencing algorithm makes sure there is a minimal gap between jobs, as set in option "Lead Time".
Note that when executing, Scheduler will immediately start a job planned away from current simulation time by an offset smaller than that lead time.
The sequencing algorithm will attempt to resolve all constraints ten times before considering those can't be achieved.
There is no limit to the number of jobs that can be inserted in the queue, but the bounded number of attempts effectively poses a restriction to automated scheduling.

Known bug: The algorithm is not entirely optimized yet, and adding observations may slow the reactivity of the user interface on low-end systems while evaluating.
Known bug: The updated values of the Ekos options are taken into account at the next evaluation of the job list, and not automatically after the options pop-up is dismissed. As there is no periodic evaluation of the job list, the end-user needs to click the "refresh" icon to trigger a new evaluation with the updated settings.

Test Plan:

Use case: start the observation of a target when its altitude is higher than X degrees

If the scheduler job to modify was created previously, double-click its line in the job table to enter edit mode. If the job is being created, the constraint can be set immediately.

Enable the "Minimum Altitude" constraint and specify a minimum altitude the target should be visible at from the KStars geographic location before starting the observation. The constraint is enabled by default with a value of 15 degrees.

Target observation will be then scheduled in the interval between the moment it rises higher than the minimum altitude, to the moment it sets lower that the minimum altitude plus 3 degrees. The altitude cut-off is there to avoid the situation where a scheduler job execution is started and aborted after a few minutes because its preparation steps - focus, alignment and guiding - delayed the capture step.

Known bug: You can set any altitude in [15,90] in the user interface. If you disable the constraint, the minimum value of 0 degrees is enforced. Although the code managing the constraint will only enforce the numerical limit when its value is higher than -90 degrees, the user interface will not allow an minimum altitude lower than 15 degrees, and the scheduler code will not allow a target to be lower than 0 degrees for observation.

Known bug: The altitude cut-off value considered when the target sets cannot be customized.

Use case: start the observation of a target when its angle to the Moon is greater than X degrees

If the scheduler job to modify was created previously, double-click its line in the job table to enter edit mode. If the job is being created, the constraint can be set immediately.

Enable the "Moon Separation" constraint and specify a minimum angle the target and Moon should be separated from, as seen from the KStars geographic location, before starting the observation. The constraint is disabled by default. Target will be then scheduled on the day that separation is higher than the minimum angle.

Known bug: The implementation of this constraint is currently embedded into the altitude constraint, and prevents the altitude check from succeeding if the angle is not large enough. However, the altitude constraint will only look for a suitable date and time in the next rise and set cycle of the target, thus 24 hours at maximum. As the separation with the Moon will not change much during that time, the job will often end up invalid.

Use case: start the observation of a target during night time only

If the scheduler job to modify was created previously, double-click its line in the job table to enter edit mode. If the job is being created, the constraint can be set immediately.

Enable the "Twilight" constraint. The constraint is enabled by default.

Target observation will be then scheduled in the interval between the astronomical dusk to the astronomical dawn, minus the lead time set in the Ekos options. The lead time cut-off is there to avoid the situation where a scheduler job execution is started and aborted after a few minutes because its preparation steps, focus, alignment and guiding, delayed the capture step.

Known bug: The twilight constraint uses the astronomical dawn and dusk of the current simulation day, even if the target is scheduled to a date that is different. Though there is not much change to that interval day after day, it will cause unexpected delays or lost imaging time when an automated observatory is set to sleep for a few days.

Use case: start the observation of a target when it is culminating

If the scheduler job to modify was created previously, double-click its line in the job table to enter edit mode. If the job is being created, the constraint can be set immediately.

Change the start-up conditions to the "Culmination" constraint, and specify a positive or negative offset in minutes to the culmination time of the target from the KStars geographic location before starting the observation. The start-up constraint is set to "as soon as possible" by default.

Target observation will then be scheduled to start at the next culmination date and time, adjusted by the specified offset.

Known bug: Because the culmination calculation has a certain level of incertitude, it may happen that the schedule is not stable when evaluated at different date and time values: when re-evaluated later, the job may be found starting after the effective adjusted culmination, and pushed to the next day as jobs cannot be scheduled sooner than they are currently occurring at during an evaluation. To resolve this situation, increase the lead time in the Ekos options to relax the precision of the job start-up time.

Use case: start the observation of a target at a fixed time

If the scheduler job to modify was created previously, double-click its line in the job table to enter edit mode. If the job is being created, the constraint can be set immediately.

Change the start-up conditions to the "Start At" constraint, and specify a date and time at which starting the observation. The start-up constraint is set to "as soon as possible" by default. The date and time is local to the KStars geographic position.

Target observation will then be scheduled to start at the indicated date and time.

Known bug: Because the real conditions in which the jobs execute may make the duration of the previous job longer than expected, it may happen that some jobs are aborted before starting because the start-up time is passed at the moment they are started. It is currently not possible to customize the duration of the preliminary steps of a job, and a job scheduled to start at a fixed time will not accept to start at a different time. To partially resolve this situation, increase the lead time in the Ekos options to relax the precision of the job start-up time and help with the schedule of prior jobs.

Use case: finish the observation of a target at a fixed time

If the scheduler job to modify was created previously, double-click its line in the job table to enter edit mode. If the job is being created, the constraint can be set immediately.

Change the completion conditions to the "Finish At" constraint, and specify a date and time at which completing the observation. The completion constraint is set to "finish sequence" by default. The date and time is local to the KStars geographic position.

Target observation will then be scheduled to repeat until the indicated date and time. Because the real conditions in which the job execute may make the duration of that job longer than expected, using a fixed repeat count may result in a completion time later than planned. Using a fixed completion time ensure the following job will start at the expected fixed time.

Use case: change the order of observation of targets

If an observation target is currently edited, exit the edition mode by clicking on the "check" icon.

Open the Ekos option, and disable option "Sort Jobs per Altitude and Priority" in the Scheduler tab.

Select an observation target by clicking on its line in the job table. That line is highlighted as a result, and the state of icons "up" and "down" above the job table comply with the following rules:

• If the selected job is the first of the list, the "up" icon is disabled.
• If the selected job is the last of the list, the "down" icon is disabled.
• If the selected job is the only one in the list, the "up" and "down" icons are disabled.
• In other situations both "up" and "down" icons are enabled.

Clicking the enabled "up" button will swap the selected job with its previous sibling. Clicking the enabled "down" button will swap the selected job with its following sibling.

The schedule of the observation targets following and including the swapped jobs will re-evaluate automatically after the operation.

Use case: sort observations of targets per their altitude

If an observation target is currently edited, exit the edition mode by clicking on the "check" icon.

Open the Ekos option, and disable option "Sort Jobs per Altitude and Priority" in the Scheduler tab.

Examine the start-up time of the first observation target of the job table. When the "sort" icon is clicked, the algorithm computes the altitudes of all observation targets, reorders them per their computed altitude, then re-evaluates the schedule of all jobs.

The sort algorithm orders altitude from set to rise:

• If target A is setting and target B is rising, then A will be sorted before B.
• If target A is lower than target B, but is setting, then A will be sorted before B.
• If target A is lower than target B, but is rising, then A will be sorted after B.

Use case: systematically sort observations of targets per their altitude

If an observation target is currently edited, exit the edition mode by clicking on the "check" icon.

Open the Ekos option, and enable option "Sort Jobs per Altitude and Priority" in the Scheduler tab. When that option is enabled, evaluation of targets will systematically reorder observations. The algorithm computes the altitudes of all observation targets _at the current simulation time it is executed_, reorders them per their computed altitude, then re-evaluates the schedule of all jobs.

The sort algorithm orders altitude from set to rise:

• If target A is setting and target B is rising, then A will be sorted before B.
• If target A is lower than target B, but is setting, then A will be sorted before B.
• If target A is lower than target B, but is rising, then A will be sorted after B.

Reviewers: mutlaqja, wreissenberger, lancaster

Reviewed By: mutlaqja

Subscribers: yurchor, kde-edu

Tags: KDE Edu

Differential Revision: https://phabricator.kde.org/D16429