Merge pull request #824 from hjoliver/disambiguate-active

Disambiguate the word "active".

Author: hjoliver

src/7-to-8/major-changes/scheduling.rst

@@ -23,21 +23,22 @@ Cylc can manage infinite workflows of repeating tasks:
 
 Cylc 8 has a new scheduling algorithm that:
 
-- Is much more efficient because it only has to manage active tasks
+- Is much more efficient because it only has to manage
+  :term:`active tasks <active task>`.
 
-  - waiting tasks are not pre-spawned before they are needed
-  - succeeded tasks are not kept across the active task window
-  - no costly indiscriminate dependency matching is done
+  - Tasks are not loaded into memory before they are needed.
+  - Tasks are not retained in memory once they complete.
+  - There is no costly indiscriminate dependency matching.
 - Distinguishes between :term:`optional <optional output>` and
   :term:`required <required output>` task outputs, to support:
 
   - :term:`graph branching` without :term:`suicide triggers <suicide trigger>`
-  - correct diagnosis of :term:`workflow completion`
+  - correct diagnosis of :ref:`workflow completion`
 - Causes no implicit dependence on previous-instance job submit
 
   - instances of same task can run out of cycle point order
   - the workflow will not unnecessarily stall downstream of failed tasks
-- Provides a sensible active-task based window on the evolving workflow
+- Provides a sensible activity-based window on the evolving workflow
 
   - (to fully understand which tasks appeared in the Cylc 7 GUI you had to
     understand the scheduling algorithm)

src/7-to-8/summary.rst

@@ -134,7 +134,7 @@ intervention, which will :term:`stall` the workflow.
 Alternatively, outputs can be marked as :term:`optional <optional output>`,
 which allows :term:`optional graph branching <graph branching>`.
 
-This allows the scheduler to correctly diagnose :term:`workflow completion`.
+This allows the scheduler to correctly diagnose :ref:`workflow completion`.
 
 
 Platform Awareness

src/glossary.rst

@@ -68,50 +68,36 @@ Glossary
       Submit number also appears in the job log path so that job log files
       don't get overwritten.
 
-
-   active
    active task
-      An active task is a task which is near ready to run, in the process of
-      running, or which requires user intervention. These are all the tasks
-      being actively managed by the scheduler at this point in the run. 
+      Active tasks are those tasks held in memory to feed
+      the scheduling algorithm. They form the ``n=0`` :term:`n-window`,
+      so are always visible in the GUI.
 
-      Active tasks are:
+      Active tasks include:
 
-      - Tasks which have some, but not all of their
-        :term:`prerequisites <prerequisite>` satisfied.
-      - ``waiting`` tasks, that are actively waiting on:
+      - ``submitted`` and ``running`` tasks (i.e, tasks with active jobs)
+      - ``preparing`` tasks in the job submission pipeline
+      - ``waiting`` tasks that are nearly ready to run but:
 
-        - :term:`xtriggers <xtrigger>`.
-        - :ref:`internal queues <InternalQueues>`
-        - :ref:`runahead limit <RunaheadLimit>`
+        - have partially satisfied :term:`prerequisites <prerequisite>`
+        - or are waiting on :term:`xtriggers <xtrigger>`,
+          :ref:`internal queues <InternalQueues>`, or the :ref:`runahead limit <RunaheadLimit>`
 
-      - ``preparing`` tasks - i.e. tasks in the process of submitting jobs
-      - ``submitted`` and ``running`` tasks - i.e. those with active jobs
       - tasks that reached a :term:`final status` without completing their
         :term:`required outputs <required output>`
         (e.g. a task failed where success was required).
 
-      Active tasks are in the ``n=0`` :term:`window <n-window>` which means they
-      will always be displayed in the GUI and Tui.
-
-      The distinction between active and non-active tasks is important for
-      the computing of the :term:`runahead limit`.
 
+   n-window
+      The GUI provides a view of the workflow extending ``n`` graph edges out
+      from :term:`active tasks <active task>` - which form the ``n=0``
+      window. The default n-window extent is ``n=1``. 
 
    active cycle
-      A cycle point is active if it contains any :term:`active tasks <active task>`.
-
-      Active cycles are counted towards the :term:`runahead limit`.
-
-
-   window
-   n-window
-   active window
-      The GUI provides a :term:`graph`-based window or view of the workflow at
-      runtime, including tasks out to ``n`` graph edges from current
+      A cycle point is considered to be active if it contains any
       :term:`active tasks <active task>`.
 
-      Active tasks form the ``n=0`` window.
+     Active cycles count toward the :term:`runahead limit`.
 
       .. seealso::
 
@@ -358,7 +344,6 @@ Glossary
          "1/bar" -> "2/bar" -> "3/bar"
 
 
-
       .. seealso::
 
          * :ref:`tutorial-integer-cycling`
@@ -376,12 +361,15 @@ Glossary
 
 
    cycle point
-      The unique label given to tasks that belong to a particular :term:`cycle`.
+      The label given to tasks that belong to a particular :term:`cycle`.
       For :term:`integer cycling` these will be integers, e.g. ``1``, ``2``,
       ``3``, etc.
       For :term:`datetime cycling` they will be :term:`ISO 8601` datetimes,
       e.g. ``2000-01-01T00:00Z``.
 
+      Cylc can run multiple cycles at once, dependencies allowing, so each
+      task instance has its own cycle point label.
+
       .. seealso::
 
          * :term:`initial cycle point`
@@ -993,7 +981,8 @@ Glossary
       This refers to starting a new instance of the Cylc :term:`scheduler`
       program to manage a particular :term:`workflow`. This can be from
       scratch, for installed workflows that haven't run previously, or to
-      restart one that shut down prior to :term:`completion <workflow completion>`.
+      restart one that shut down prior to
+      :ref:`completion <workflow completion>`.
 
       .. seealso::
 
@@ -1170,7 +1159,7 @@ Glossary
    stop
    shutdown
       A :term:`scheduler` can shut down on request, or automatically on
-      :term:`workflow completion`. The :term:`workflow` is then stopped and no
+      :ref:`workflow completion`. The :term:`workflow` is then stopped and no
       further :term:`jobs <job>` will be submitted.
 
       By default, the scheduler waits for any submitted or running task
@@ -1216,9 +1205,10 @@ Glossary
       workflow :term:`source directory` before reload, rather than made by
       editing the installed files directly.
 
-      :ref:`RemoteInit` will be redone for each job platform, when the first job is submitted there after a reload.
+      :ref:`RemoteInit` will be redone for each job platform, when the first
+      job is submitted there after a reload.
 
-      Any :term:`task` that is :term:`active <active task>` at reload
+      Any task that is :term:`active <active task>` at reload
       will continue with its pre-reload configuration.
       The next instance of the task (at the next cycle point)
       will adopt the new configuration.
@@ -1433,7 +1423,7 @@ Glossary
       - Or, if expiry is optional, then the outputs are complete if it expires.
 
       Tasks that achieve a :term:`final status` with complete outputs have done
-      their job, allowing the workflow to move on.
+      their job in the workflow, allowing the scheduler to move on.
 
       Tasks that achieve a final status with incomplete outputs are retained in
       :term:`n=0 <n-window>` pending user intervention, and will :term:`stall`
@@ -1587,7 +1577,7 @@ Glossary
 
    stall
    stalled workflow
-      A stalled workflow has not run to :term:`completion <workflow completion>`
+      A stalled workflow has not :ref:`run to completion <workflow completion>`
       but cannot continue without manual intervention. 
 
       A stalled scheduler stays alive for a configurable timeout period
@@ -1613,8 +1603,7 @@ Glossary
 
 
    suicide trigger
-      Suicide triggers remove :term:`tasks <task>` from the 
-      :term:`active window <n-window>` at runtime.
+      Suicide triggers remove tasks from the :term:`n=0 window <n-window>`.
 
       They are denoted by exclamation marks, and are triggered like normal
       dependencies. For instance, the following suicide trigger will remove the
@@ -1702,16 +1691,14 @@ Glossary
 
 
    flow front
-      :term:`Active tasks <active task>`, i.e. tasks in the
-      :term:`n=0 window <n-window>`, with a common :term:`flow number`
+      :term:`Active tasks <active task>` with a common :term:`flow number`
       comprise the active front of the flow.
 
 
    flow merge
-      When a :term:`flow` tries to spawn a child task and finds an instance
-      with the same task ID already exists in the ``n=0`` :term:`active
-      window`, one merged task will carry both flow numbers forward.
-
+      If a spawned task encounters another :term:`active task` with the same
+      task ID, the two instances will merge and carry both :term:`flow`
+      numbers forward.
 
    event
       An event is a milestone in the lifecycle of a :term:`workflow` or
@@ -1747,12 +1734,9 @@ Glossary
 
    runahead limit
    runahead
-      In a :term:`cycling workflow`, the runahead limit determines how far
-      ahead of the oldest :term:`active cycle` the workflow is permitted
-      to run.
-
-      The "oldest active cycle point" is the first cycle in the workflow to contain
-      any :term:`active tasks <active task>` (e.g. running tasks).
+      In a :term:`cycling workflow` the runahead limit determines how
+      far ahead, in :term:`cycle points <cycle point>`, activity can 
+      extend beyond the earliest submitted or running tasks.
 
       .. seealso::
 
@@ -1761,26 +1745,12 @@ Glossary
          * :term:`active cycle`
 
 
-   workflow completion
-      A workflow is complete, and the scheduler will automatically
-      :term:`shut down <shutdown>`, if no tasks remain in the
-      :term:`n=0 <n-window>`.
-
-      That is, all active tasks have finished, and no tasks remain waiting on
-      :term:`prerequisites <prerequisite>` or "external" constraints (such as
-      :term:`xtriggers <xtrigger>` or task :term:`hold`).
-
-      If no active tasks remain and all external constraints are satisfied,
-      but the n=0 window contains tasks waiting with partially satisfied
-      :term:`prerequisites <prerequisite>`, or tasks with :term:`final status` and
-      :term:`incomplete outputs <output completion>`, then the workflow is
-      not complete and the scheduler will :term:`stall` pending manual intervention.
-
    dummy task
       A task which runs a trivially simple script such as ``sleep 1``,
       ``exit 0`` or ``true``, or which uses :ref:`task-run-modes.skip`
       to avoid running a script at all.
 
+
    dummy mode
       A workflow run mode that replaces all tasks with :term:`dummy tasks <dummy task>`.
       See :ref:`workflow-run-modes.dummy`.

src/reference/changes.rst

@@ -245,17 +245,14 @@ N-Window selector in the GUI
 
 The :term:`n-window` determines how much of a workflow is visible in the GUI / Tui.
 
-The ``n=0`` window contains only the active tasks
-(i.e. queued, preparing, submitted or running tasks).
+You can change the n-window extent in the GUI with a toolbar button, to display
+more or less of the graph around current :term:`active tasks <active task>`.
+This affects all GUI views equally, not just the graph view.
 
-The ``n=1`` window, also contains tasks one "edge" out from active tasks
-(i.e. the tasks immediately upstream or downstream of active tasks).
+The ``n=0`` window contains only the active tasks.
 
-The ``n=2`` window, also contains tasks two "edges" out from active tasks,
-and so on.
-
-It is now possible to change the window extent in the GUI via a button in the
-toolbar allowing you to see tasks further back in the workflow's history.
+The ``n=1`` window displays tasks out to one graph edge around the active
+tasks; ``n=2`` out to two graph edges; and so on.
 
 .. image:: changes/gui-n-window-selector.gif
    :width: 100%
@@ -306,7 +303,7 @@ When a task achieves a final status, its outputs are validated against a "comple
 expression" to ensure that it has produced all of its
 :term:`required outputs <required output>`.
 If a task fails this validation check it is said to have "incomplete outputs"
-and will be retained in the :term:`active window` pending user intervention.
+and will be retained in the :term:`n=0 window <n-window>` pending user intervention.
 
 This completion expression is generated automatically from the graph.
 By default, tasks are expected to succeed, if you register any additional

src/user-guide/interventions/index.rst

@@ -558,7 +558,8 @@ Remove Tasks
 
          The removed task will be greyed out but it might not
          disappear from view because the GUI displays all tasks
-         in a graph-based window around current active tasks.
+         in a graph-based :term:`n-window` surrounding current
+         :term:`active tasks <active task>`.
 
 
    .. tab-item:: CLI

src/user-guide/running-workflows/reflow.rst

@@ -26,8 +26,8 @@ See :ref:`below<flow-trigger-use-cases>` for uses, and an
 :ref:`example<new-flow-example>`, of concurrent flows.
 
 .. note::
-   Flows :ref:`merge<flow-merging>` where (and if) tasks collide in the ``n=0``
-   :term:`active window`. Downstream of a merge, tasks are considered to belong
+   Flows :ref:`merge<flow-merging>` where (and if) tasks collide in the
+   :term:`n=0 window <n-window>`. Downstream of a merge, tasks are considered to belong
    to all of their constituent flows.
 
 
@@ -92,7 +92,7 @@ Triggering in Specific Flows
 
    The result is like the default above, except that tasks in the new front
    belong only to the specified flow(s), regardless of which flows are
-   :term:`active` at triggering time.
+   active at triggering time.
 
 Triggering a New Flow
    ``cylc trigger --flow=new ID``
@@ -117,20 +117,21 @@ Triggering with No Active Flows
    ``cylc trigger [--wait] ID``
 
    By default, triggered tasks will be given the flow numbers of the most
-   recent active task. This can happen, for instance, if you restart a
-   completed workflow and then trigger a task in it. The result will be the
-   same as if you had triggered the task just before the workflow completed.
+   recent :term:`active tasks <active task>`. This can happen, for instance,
+   if you restart an already-completed workflow and then manually trigger a
+   task in it. The task's flow number will be the same as if you
+   had triggered it just before the workflow completed.
 
-Special Case: Triggering ``n=0`` Tasks
-   Tasks in the ``n=0`` window are :term:`active tasks <active task>`.
-   Their flow membership is already determined - that of
-   the parent tasks that spawned them.
+Special Case: Triggering ``n=0`` (:term:`active tasks <active task>`)
+   Active tasks already have flow membership assigned.
+   Flow numbers are inherited, on entering the active wndow, from parent
+   (upstream) tasks in the graph.
 
    - Triggering a task with a submitted or running job has no effect
      (it is already triggered).
-   - Triggering other :term:`n=0 tasks <n-window>`, including tasks with
-     :term:`incomplete outputs <output completion>` queues them to run in
-     the flow that they already belong to.
+   - Triggering other :term:`active tasks <active task>`, including those with
+     :term:`incomplete outputs <output completion>`, queues them to run with
+     their existing flow numbers.
 
 
 .. _flow-merging:
@@ -142,8 +143,9 @@ If a task spawning into the :term:`n=0 window <n-window>` finds another instance
 of itself (same task ID) already there, the two will merge and carry both
 (sets of) flow numbers forward. Downstream tasks will belong to both flows.
 
-Flow merging is necessary because :term:`active <active task>` task IDs
-must be unique.
+Flows merge because every :term:`active task` must have a unique ID. However,
+merging is also useful: it allows a simpler single flow to continue downstream of
+multi-flow interventions.
 
 If the original task instance has a :term:`final status` (and has been retained
 in the :term:`n=0 window <n-window>` with
@@ -157,9 +159,9 @@ Stopping Flows
 By default, ``cylc stop`` halts the workflow and shuts the scheduler down.
 
 It can also stop specific flows: ``cylc stop --flow=N`` removes the flow number
-``N`` from :term:`active tasks <active task>`. Tasks that have no flow
-numbers left as a result do not spawn children at all. If there are no active
-flows left, the scheduler shuts down.
+``N`` from :term:`active tasks <active task>`. Tasks with no remaining flow
+numbers will not spawn downstream activity. If there are
+no active flows left, the scheduler shuts down.
 
 .. TODO update this section post https://github.com/cylc/cylc-flow/issues/4741