[education/kstars] doc: Update scheduler handbook section.
Hy Murveit
null at kde.org
Mon Jul 3 09:09:22 BST 2023
Git commit 50f904ee8660e6096c28a12d1b76b4c7b47cc953 by Hy Murveit.
Committed on 03/07/2023 at 07:19.
Pushed by murveit into branch 'master'.
Update scheduler handbook section.
M +140 -21 doc/ekos-scheduler.docbook
M +- -- doc/ekos_scheduler.png
A +- -- doc/ekos_scheduler_settings.png
M +- -- doc/mosaic_create_jobs.png
https://invent.kde.org/education/kstars/-/commit/50f904ee8660e6096c28a12d1b76b4c7b47cc953
diff --git a/doc/ekos-scheduler.docbook b/doc/ekos-scheduler.docbook
index 1fba1174ce..e567f5b3c1 100644
--- a/doc/ekos-scheduler.docbook
+++ b/doc/ekos-scheduler.docbook
@@ -19,39 +19,96 @@
</mediaobject>
</screenshot>
<sect3 id="ekos-scheduler-introduction">
- <title>Introduction</title>
+ <title>Introduction</title>
<para>
- Ekos Scheduler is an indispensable arsenal in building your robotic observatory. A Robotic observatory is an observatory composed of several subsystems that are orchestrated together to achieve a set of scientific objectives without human intervention. It is the only Ekos module that does not require Ekos to be started as it is utilized to <emphasis>start</emphasis> and <emphasis>stop</emphasis> Ekos. It is designed to be straightforward and intuitive. However, the scheduler should only be used after you mastered Ekos and knows all the quirks of your equipment. Since the complete process is automated, including focus, guiding, and meridian flip, all equipment should be thoroughly used with Ekos and all their parameters and settings adjusted to achieve the best result.
+ The Ekos Scheduler is an important component of you imaging workflow. It connects to INDI, starts and stops all the other Ekos modules, schedules jobs according to their constraints and priorities, monitors those jobs as they execute, and then safely brings down the system when jobs are done, or before dawn. Whether you are running multi-day imaging sessions for multiple targets, or simplying trying to image a single target for a few hours, it is advisable to have the Scheduler control your imaging sessions.
</para>
+ </sect3>
+ <sect3 id="scheduler-table">
+ <title>Scheduler Table</title>
<para>
- With Ekos, the user can utilize the powerful sequence queue to image batches of images for a particular target. In simple setups, the user is expected to focus the CCD, align the mount, frame the target, and start guiding before initiating the capture process. For more complex observatory environments, there are usually predefined custom procedures to be executed to prepare the observatory for imaging, and another set of procedures on shutdown. The user may plan to image one or more targets during the night and expects data to be ready by morning. In &kstars;, tools such as the <link linkend="tool-obsplanner">Observation Planner</link> and <link linkend="tool-whatsup">What's up Tonight</link> help the user in selecting candidates for imaging. After selecting the desired candidates, the user can add them to the Ekos Scheduler list for evaluation. The user may also add the targets directly in Ekos scheduler or select a FITS file of a previous image.
+ The heart of the Scheduler is a table displaying the list of Scheduler jobs the user wants to run. Associated with each jobs are attributes (mostly described in the settings section below). The attributes describe the name of the job, where the telescope should be pointed when imaging that job, a description of what types of images should be captured, constraints about when the jobs should run (e.g. altitude, twilight, moon, landscape blockages, etc), things that need to be done before and after the job is run, and strategies for dealing with errors.
</para>
- </sect3>
+ <para>
+ You can add, delete, modify or change the order of rows in the Scheduler table.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ You can add a Scheduler job row into the table by clicking the <guilabel>+</guilabel> control above the table, if all required attributes are filled out (name, position, and sequence file).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you click on a row, you can then click the <guilabel>-</guilabel> control above the table to delete that row.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you click on a row, you can then click the <guilabel>^</guilabel> or <guilabel>v</guilabel> controls to move those rows up or down in the job list.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you double click on a row, the attributes of that job are filled in to the various settings on the Scheduler page. You can then change one or more of those attributes, and then click the checkmark above the table (after your double-click, the <guilabel>+</guilabel> became a <guilabel>checkmark</guilabel>), and the new attributes are assigned to that job.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect3>
+ <sect3 id="scheduling-algorthm">
+ <title>Scheduling Algorithm</title>
+ <para>
+ The Scheduler table (above) lists jobs in order of priority, with higher jobs (on lower-numbered rows) having higher priority than jobs further down the list (with higher-numbered rows).
+ </para>
+ <para>
+ The Scheduler regularly plans (an re-plans) which jobs should be run, and when. It can start executing a given job, and then later preempt that job for a new one. It can become idle if no jobs can be run (e.g. in daylight), and sleep until such a time that it becomes active again. Its aim is to keep the equipment as busy as possible, while respecting the scheduler-table's priorties. Here's how it works.
+ </para>
+ <para>
+ When the scheduler starts (or when it replans, which it does every second while active), it looks through the entire list of jobs, starting at the highest priority job, and working its way down to the lowest priority one if necessary. When it finds a job that can run, it starts that job, possibly preempting the currently running job. A jobs can run if it's constraints are met, e.g. the target is not blocked by the local terrain, it meets the minimum altitude constraint, it has not already completed all the desired imaging, ...
+ </para>
+ </sect3>
+ <para>
+ The algorithm shows its projected next start times and stop times for all job in the Scheduler table. It also shows its estimate of times jobs will run during the next 48 hours in the log panel at the bottom of the window. See the screenshot of the scheduler window at the top of this section.
+ </para>
+ <para>
+ The scheduling algorithm described in the above paragraph is known as the Greedy Scheduling algorithm. It is the recommended one to use. In previous versions of Ekos, there was another "Classic scheduling algorithm" which is currently being phased out. That scheme could not preempt running jobs, and thus did not makes as much use of the equipment as the Greedy Algorithm.
+ </para>
+ <sect3 id="scheduler-files">
+ <title>Scheduler Files (.esq)</title>
+ <para>
+ The scheduler table with its list of jobs and attributes can be saved onto disk and read back in. It writes an .esq file. Controls for writing the current Scheduler table to disk, and reading back other .esq files are located above the table to the right.
+ </para>
+ </sect3>
<sect3 id="ekos-scheduler-settings">
- <title>Settings</title>
+ <title>Settings</title>
<para>
- Ekos Scheduler provides a simple interface to aid the user in setting the conditions and constraints required for an observation job. Each observation job is composed of the following:
+ Ekos Scheduler provides a simple interface to aid the user in setting the conditions and constraints required for an Scheduler job. You must select the <guilabel>Target</guilabel>, its coordinates, and the <guilabel>Sequence</guilabel> before you can add a job to the Scheduler.
+ </para>
+ <para>
+ Each Scheduler job is composed of the following:
</para>
<itemizedlist>
<listitem>
<para>
- <guilabel>Target name and coordinates</guilabel>: Select target from the <link linkend="findobjects">Find Dialog</link> or <guibutton>Add</guibutton> it from <link linkend="tool-obsplanner">Observation Planner</link>. You can also enter a custom name.
+ <guilabel>Target name and coordinates</guilabel>: Select target from the <link linkend="findobjects">Find Dialog</link> or <guibutton>Add</guibutton> it from <link linkend="tool-obsplanner">Observation Planner</link>. You can also enter a custom name. Coordinates can also be copied from the SkyMap using the button just to the right of the coordinates.
</para>
</listitem>
<listitem>
<para>
- Optional <guilabel>FITS File</guilabel>: If a FITS file is specified, the astrometry solver shall solve the file and use the central RA/DEC as the target coordinates.
+ Optional <guilabel>PA</guilabel>: The position angle (or image rotation) can be specified for systems with camera rotation hardware.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Sequence</guilabel> file: The sequence file is constructed in the Ekos <link linkend="ekos-capture">Capture Module</link>. It contains the number of images to capture, filters, temperature settings, prefixes, download directory, &etc;
+ Optional <guilabel>FITS File</guilabel>: If a FITS file is specified, the astrometry solver solves the file and use the central RA/DEC as the target coordinates.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Priority</guilabel>: Set job priority in the range of 1 to 20 where 1 designates the highest priority and 20 the lowest priority. Priority is applied in calculating the weight used to select the next target to image.
+ <guilabel>Sequence</guilabel> file: The sequence file is constructed in the Ekos <link linkend="ekos-capture">Capture Module</link>. It has a list of capture specifications, where each spec details the number of images to capture, which filter to use, the exposure length, the gain, file naming details, temperature settings, prefixes, download directory, &etc;
</para>
</listitem>
<listitem>
@@ -61,29 +118,78 @@
</listitem>
<listitem>
<para>
- <guilabel>Steps</guilabel>: The user selects which Ekos modules should be utilized in the observation job execution workflow.
+ <guilabel>Steps</guilabel>: The user selects what steps should be taken at the start of the job. The possibilities are: (1) Start mount tracking, (2) autofocus, (3) run a plate solving alignment, (4) start the auto-guider. One or more can be chosen.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Startup Conditions</guilabel>: Conditions that must be met <emphasis role="bold">before</emphasis> the observation job is started. Currently, the user may select to start as soon as possible, <guimenuitem>ASAP</guimenuitem>, or when the target is near or past culmination, or at a specific time.
+ <guilabel>Startup Conditions</guilabel>: Conditions that must be met <emphasis role="bold">before</emphasis> the Scheduler job is started. Currently, the user may select to start as soon as possible, <guimenuitem>ASAP</guimenuitem>, or when the target is near or past culmination, or at a specific time.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Constraints</guilabel>: Constraints are conditions that must be met <emphasis role="bold">at all times</emphasis> during the observation job execution process. These include minimum target altitude, minimum moon separation, twilight observation, artificial horizon altitude constraints, and weather monitoring.
+ <guilabel>Constraints</guilabel>: These are conditions that must be met <emphasis role="bold">at all times</emphasis> during the Scheduler job execution process. These include minimum target altitude, minimum moon separation, twilight observation, artificial horizon altitude constraints, and weather monitoring.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Completion Conditions</guilabel>: Conditions that trigger completion of the observation job. The default selection is to simply mark the observation job as complete once the sequence process is complete. Additional conditions enable the user to repeat the sequence process indefinitely or up until a specific time.
+ <guilabel>Completion Conditions</guilabel>: Conditions that trigger completion of the Scheduler job. The default selection is to simply mark the Scheduler job as complete once the sequence process is complete. Additional conditions enable the user to repeat the sequence process a number of times or indefinitely, or up until a specific time.
</para>
</listitem>
</itemizedlist>
+ </sect3>
+ <sect3 id="other-options">
+ <title>Other options</title>
<para>
- You must select the <guilabel>Target</guilabel> and <guilabel>Sequence</guilabel> before you can add a job to the Scheduler. When the scheduler starts, it evaluates all jobs in accord to the conditions and constraints specified and attempts to select the best job to execute. Selection of the job depends on a simple heuristic algorithm that scores each job given the conditions and constraints, each of which is weighted accordingly. If two targets have identical conditions and constraints, usually the higher priority target followed by higher altitude target is selected for execution. If no candidates are available at the current time, the scheduler goes into sleep mode and wakes up when the next job is ready for execution.
+ There are several other options to control how the Scheduler behaves. These are found in the general KStars Settings menu, shown below, in its Ekos tab and Scheduler sub-tab.
</para>
- <screenshot>
+ <screenshot>
+ <screeninfo>
+ Scheduler Settings
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="ekos_scheduler_settings.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Scheduler Settings</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <sect4 id="remember-job-progress">
+ <title>Remember job progress</title>
+ <para>
+ Among the settings shown above, one important one is known as <guilabel>Remember job progress</guilabel>. When this box is checked and a job is running, the Scheduler looks at the job's images already captured on disk, and doesn't re-capture the ones that are already there. The benefit is that if a job is restarted, or re-run another night, or if multiple jobs are being run together, stopping and starting when they are runnable, then jobs re-start right where they left off. This works well with the <guilabel>Repeat until terminated</guilabel> job-completion option. If <guilabel>Remember job progress</guilabel> is unchecked, jobs would restart from the start of their sequence specification each time, which probably isn't what you want. Unfortunately, if the images are not stored on the same computer that Ekos is running on, then this feature doesn't work and the jobs restart from their beginning.
+ </para>
+ <para>
+A possibly confusing side-effect of <guilabel>Remember job progress</guilabel> is that if you've run a job using the (default) Sequence Completion finish condition, and it has captured all its images, and now you want to run the job again, the Scheduler won't schedule the job because it believes that all the images have already been captured. You'd either need to move those images elsewhere on disk, or change the finish condition to Repeat for N Times, or Repeat Until Terminated.
+ </para>
+ </sect4>
+ <sect4 id="group-repeats">
+ <title>Group repeats</title>
+ <para>
+ This feature allows you to run two or more scheduler jobs at roughly the same priority, such that if they were both runnable, they would progress at roughly the same rate. This may be applicable, for example, to jobs imaging the multiple tiles in a mosaic, but is generally applicable to any set of jobs.
+ </para>
+ <para>
+ Normally the (Greedy) scheduler's job priority is set by the row the job is listed in the Scheduler's job table. Jobs on rows closer to the top run with higher priority than jobs lower down. Thus, if a job on row 2 (Job2) uses <guilabel>Repeat Until Terminated</guilabel>, and that job's running constraints are satisfied, a lower down job (e.g. Job3) will not be scheduled to run.
+ </para>
+ <para>If you wish to alternate jobs, you can assign each of the jobs the same <guilabel>group</guilabel> name, and give the jobs one of the repeating finish conditions (e.g. Repeat for N times, or Repeat Until Terminated). With that setup, jobs in the same group will cede to each other if they have completed more 'Repeat Iterations' than the other job. So, if Job2 with group "MyGroup" completes its 2nd iteration, and Job3 with the same group name has only completed 0 or 1 iterations, when the time comes to schedule Job2, Job3 will run instead.
+ </para>
+ <para>
+Practically speaking, imagine you had a 6-panel mosaic you wanted to alternate. You might give all of those jobs the same group name, make them all e.g. "Repeat for 5 times". Then, they would run in lock-step. The cadence of job switching would be controlled by the length of the sequence file assigned to each of those jobs. You wouldn't want to make the cadence too short (e.g. capturing one 2-minute image), as there is overhead in switching jobs. For instance, starting jobs may involved aligning, starting guiding, and even focusing.
+ </para>
+ </sect4>
+ <sect4 id="repeat-all-jobs">
+ <title>Repeat all jobs</title>
+ <para>
+There is a checkbox and number input right below the Schuduler jobs table that allows you to repeat the entire schedule N times. This can be used to alternate a few jobs. You can just list the jobs on the scheduler, set it to repeat N times, and the jobs will repeat. However, this change is incompatible with 'Remember job progress (above) and unavailable if Remember Job Progress is checked. (Note: Remember Job Progress is recommended.)
+ </para>
+ </sect4>
+ </sect3>
+ <sect3 id="workflow">
+ <title>Workflow</title>
+
+ <screenshot>
<screeninfo>
Scheduler + Planner
</screeninfo>
@@ -166,7 +272,7 @@
</listitem>
</itemizedlist>
<para>
- Ekos Scheduler only initiates the startup procedure once the startup time for the first observation job is close (default <emphasis>lead</emphasis> time is 5 minutes before <emphasis>startup</emphasis> time). Once the startup procedure is completed successfully, the scheduler picks the observation job target and starts the sequence process. If a startup script is specified, it shall be executed first.
+ Ekos Scheduler only initiates the startup procedure once the startup time for the first Scheduler job is close (default <emphasis>lead</emphasis> time is 5 minutes before <emphasis>startup</emphasis> time). Once the startup procedure is completed successfully, the scheduler picks the Scheduler job target and starts the sequence process. If a startup script is specified, it shall be executed first.
</para>
</sect3>
@@ -206,13 +312,23 @@
Load the sequence file in the <link linkend="ekos-capture">Capture module</link> and start the imaging process.
</para>
</listitem>
+ <listitem>
+ <para>
+ Coordinate module issues, such as failures in guiding or alignment. They may result is Scheduler job suspensions and rescheduling.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Note--some of the inter-module interactions are initiated by the modules themselves, but are monitored by the Scheduler. These include meridian flips, autofocus runs initiated by temperature change or timer expiration, and minimum guiding deviation requirements for capture.
+ </para>
+ </listitem>
</itemizedlist>
</sect3>
<sect3 id="ekos-scheduler-shutdown">
<title>Shutdown</title>
<para>
- Once the observation job is completed successfully, the scheduler selects the next target. If the next target scheduled time is not due yet, the mount is parked until the target is ready. Furthermore, if the next scheduled target is not due for a user-configurable time limit, the scheduler performs a <emphasis>preemptive</emphasis> shutdown to preserve resources and performs the startup procedure again when the target is due.
+ Once the Scheduler job is completed successfully, the scheduler selects the next Scheduler job. If no job can be scheduled at this time, the mount is parked until a next job can run. Furthermore, if the next job is not due for a user-configurable time limit, the scheduler performs a <emphasis>preemptive</emphasis> shutdown to preserve resources and performs the startup procedure again when the target is due.
</para>
<para>
If an unrecoverable error occurs, the observatory initiates shutdown procedure. If there is a shutdown script, it will be executed last.
@@ -288,7 +404,7 @@ sys.stdout.flush()
exit(0)
</programlisting>
<para>
- The startup and shutdown scripts must be <emphasis>executable</emphasis> in order for Ekos to invoke them (⪚ use <userinput>chmod +x startup_script.py</userinput> to mark the script as executable). Ekos Scheduler enables truly simple robotic operation without the need of any human intervention in any step of the process. Without human presence, it becomes increasingly critical to gracefully recover from failures in any stage of the observation run. Using &plasma; notifications, the user can configure audible alarms and email notifications for the various events in the scheduler.
+ The startup and shutdown scripts must be <emphasis>executable</emphasis> in order for Ekos to invoke them (⪚ use <userinput>chmod +x startup_script.py</userinput> to mark the script as executable). Ekos Scheduler enables truly simple robotic operation without the need of any human intervention in any step of the process. Without human presence, it becomes increasingly critical to gracefully recover from failures in any stage of the observation run. Using &plasma; notifications, the user can configure audible alarms and email notifications for the various events in the Scheduler.
</para>
</sect3>
@@ -407,7 +523,10 @@ exit(0)
</listitem>
<listitem>
<para>
- <emphasis role="bold">Create Jobs</emphasis>: The final step is to select the sequence file and directory to store the images. Target field is automatically filled but may be changed as desired. Select the steps each scheduler job should execute in sequence (Track -> Focus -> Align -> Guide -> Capture), and adjust the frequency of automatic alignment and focus routines that must be executed during the mosaic operation. For example, if <guilabel>Align Every</guilabel> is set to 2 Scheduler Jobs, then the first job will run the astrometry alignment, while the second job will skip it. When the third job is executed, alignment is performed again and so forth.
+ <emphasis role="bold">Create Jobs</emphasis>: The final step is to select the sequence file and directory to store the images. Target field may be automatically filled but may be changed as desired. Select the steps each scheduler job should execute in sequence (Track -> Focus -> Align -> Guide -> Capture), and adjust the frequency of automatic alignment and focus routines that must be executed during the mosaic operation. For example, if <guilabel>Align Every</guilabel> is set to 2 Scheduler Jobs, then the first job will run the astrometry alignment, while the second job will skip it. When the third job is executed, alignment is performed again and so forth.
+ </para>
+ <para>
+ If you want the different mosaic tile jobs to alternate, then fill in the group name with an identifier that all the tile jobs will share, and select a repeating completion condition.
</para>
<screenshot>
<screeninfo>
@@ -425,7 +544,7 @@ exit(0)
</listitem>
</orderedlist>
<para>
- Click <guibutton>Create Jobs</guibutton> to generate mosaic scheduler jobs and add them to the schedule queue.
+ Click <guibutton>Create Jobs</guibutton> to generate mosaic scheduler jobs and add them to the schedule queue. You can further edit the jobs individually, as you would normal Scheduler jobs.
</para>
</sect3>
</sect2>
diff --git a/doc/ekos_scheduler.png b/doc/ekos_scheduler.png
index 7549a41147..ec663f898e 100644
Binary files a/doc/ekos_scheduler.png and b/doc/ekos_scheduler.png differ
diff --git a/doc/ekos_scheduler_settings.png b/doc/ekos_scheduler_settings.png
new file mode 100644
index 0000000000..c3ef28c3a2
Binary files /dev/null and b/doc/ekos_scheduler_settings.png differ
diff --git a/doc/mosaic_create_jobs.png b/doc/mosaic_create_jobs.png
index c76873488f..e4434ef2fd 100644
Binary files a/doc/mosaic_create_jobs.png and b/doc/mosaic_create_jobs.png differ
More information about the kde-doc-english
mailing list