Cleanups following comments from developers

Author: knoepfel

doc/_static/phlexframework.css

@@ -16,7 +16,7 @@ table.docutils caption {
 }
 
 .body {
-    background-image: url("preliminary-watermark.png");
+    background-image: url("watermark-preliminary.png");
     background-repeat: repeat;
     background-size: 100%;
 }

doc/_static/watermark-for-dune-review.png

@@ -417,7 +417,7 @@ Conceptual requirements
 
     The framework shall accept exactly one configuration per program execution.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_conceptual_design/program_configuration:Program Configuration`
 
 .. req:: Framework configuration language
     :collapse:
@@ -429,7 +429,7 @@ Conceptual requirements
 
     The framework shall provide the ability to configure the execution of a framework program at runtime using a human-readable language.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_conceptual_design/program_configuration:Program Configuration`
 
 .. req:: I/O plugins
     :collapse:
@@ -591,7 +591,7 @@ Conceptual requirements
 
     The framework shall support executing programs configured by composing configurations of separate components.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Graceful shutdown of framework program
     :collapse:
@@ -677,7 +677,7 @@ Supporting requirements
 
     The framework shall provide the ability to compare two configurations.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Record execution environment
     :collapse:
@@ -965,7 +965,7 @@ Supporting requirements
 
     The framework shall validate an algorithm's configuration against specifications provided at registration time.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Algorithm configuration schema availability
     :collapse:
@@ -977,7 +977,7 @@ Supporting requirements
 
     The framework shall have an option to emit an algorithm's configuration schema in human-readable form.
 
-- See :numref:`ch_conceptual_design/user_configuration:Semantic structure of the configuration`
+- See :numref:`ch_subsystem_design/configuration:Semantic structure of the configuration`
 
 .. req:: Eager validation of algorithm configuration
     :collapse:
@@ -990,7 +990,7 @@ Supporting requirements
 
     The framework shall validate the configuration of each algorithm before that algorithm processes data.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`, :numref:`ch_conceptual_design/user_configuration:Semantic structure of the configuration`.
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`, :numref:`ch_subsystem_design/configuration:Semantic structure of the configuration`.
 
 .. req:: I/O backend for ROOT
     :collapse:
@@ -1143,7 +1143,7 @@ Supporting requirements
 
     The framework shall provide an option to persist the configuration of each framework execution to the output of that execution.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Independence from unique hardware characteristics
     :collapse:
@@ -1166,7 +1166,7 @@ Supporting requirements
 
     The framework shall provide a command-line interface that allows the setting of configuration parameters.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Support local configuration changes
     :collapse:
@@ -1177,7 +1177,7 @@ Supporting requirements
 
     The framework shall support the use of local configuration changes with respect to a separate complete configuration to modify the execution of a program.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Configuration tracing
     :collapse:
@@ -1188,7 +1188,7 @@ Supporting requirements
 
     The framework configuration system shall have an option to provide diagnostic information for an evaluated configuration, including origins of final parameter values.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Configuration language single point of maintenance
     :collapse:
@@ -1200,7 +1200,7 @@ Supporting requirements
 
     The language used for configuring a framework program shall include features for maintaining hierarchical configurations from a single point of maintenance.
 
-- See :numref:`ch_conceptual_design/user_configuration:Mechanics of configuration specification`
+- See :numref:`ch_subsystem_design/configuration:Mechanics of Configuration Specification`
 
 .. req:: Enable identification of data sets containing chunked data products
     :collapse:

doc/_static/preliminary-watermark.png doc/_static/watermark-preliminary.pngdoc/_static/preliminary-watermark.png renamed to doc/_static/watermark-preliminary.png

@@ -74,7 +74,7 @@ When member functions are required, the qualifier :cpp:`const` should be specifi
 
 .. rubric:: Footnotes
 
-.. [#f1] In C++, the function signature corresponds to the function *declaration* [CppFunctionDecl]_, for which the type :cpp:`P` and :cpp:`P const` are treated identically by the compiler.
+.. [#f1] In C++, the function signature corresponds to the function *declaration* [Cpp-Function]_, for which the type :cpp:`P` and :cpp:`P const` are treated identically by the compiler.
          However, for the function implementation or *definition*, algorithm authors are encouraged to use :cpp:`P const` to help guarantee the immutability of data.
 .. [#f2] Phlex permits the registration of member functions that do not use the :cpp:`const` qualifier.
          However, using such functions is highly discouraged as it indicates a class instance is modifiable during member-function execution, which is at odds with Phlex's functional-programming paradigm.
@@ -83,4 +83,4 @@ When member functions are required, the qualifier :cpp:`const` should be specifi
 
    .. rubric:: References
 
-.. [CppFunctionDecl] https://en.cppreference.com/w/cpp/language/function.html
+.. [Cpp-Function] https://en.cppreference.com/w/cpp/language/function.html

doc/appendices/requirements.rst

@@ -54,7 +54,7 @@ where
 Partitions
 ^^^^^^^^^^
 
-Factorizing a set of data into non-overlapping subsets that collectively span the entire set is called creating a set *partition* [Wiki-partition]_.
+Factorizing a set of data into non-overlapping subsets that collectively span the entire set is called creating a set *partition* [Wiki-Partition]_.
 Each subset of the partition is called a *cell*.
 In the above example, the role of the :math:`\textit{into\_spills}` operation is to partition the input sequence into `Spill`\ s so that there is one fold result per `Spill`.
 In general, however, the partitioning function is of the form :math:`\textit{part}: \{\iset{c}\} \rightarrow \mathbb{P}(\iset{c})`, where:
@@ -157,4 +157,4 @@ Possible solutions include using :cpp:`std::atomic_ref<double>` [#fatomicref]_,
 
    .. rubric:: References
 
-.. [Wiki-partition] https://en.wikipedia.org/wiki/Partition_of_a_set
+.. [Wiki-Partition] https://en.wikipedia.org/wiki/Partition_of_a_set

doc/ch_conceptual_design/algorithms.rst

@@ -13,24 +13,24 @@ Partitioned Unfolds
 +----------------------------------------------------------+------------------------------------------------+------------------------+
 
 As discussed in :numref:`ch_preliminaries/functional_programming:Sequences of Data and Higher-Order Functions`, the opposite of a fold is an *unfold*, where a sequence of objects is generated from a single object.
-The example given in :numref:`ch_preliminaries/data_flow:Data Flow with Sequences` is :math:`\textit{iota}`, which generates a sequence of contiguous integers given one input number:
+The example given in :numref:`ch_preliminaries/data_flow:Data Flow with Sequences` is :math:`\text{iota}`, which generates a sequence of contiguous integers given one input number:
 
 .. math::
 
-    c = [1,\ 2,\ 3,\ \dots,\ n] = \textit{iota}\ n = \unfold{\gt 0}{\textit{decrement}}\ n
+    c = [1,\ 2,\ 3,\ \dots,\ n] = \text{iota}\ n = \unfold{greater\_than\_zero}{decrement}\ n
 
-where :math:`\textit{iota}` has been expressed in terms of an unfold HOF that receives the predicate :math:`\gt 0` and a generator called :math:`\textit{decrement}`.
+where :math:`\text{iota}` has been expressed in terms of an unfold HOF that receives the predicate :math:`greater\_than\_zero` and a generator called :math:`decrement`.
 
-The unfold operation is recursively called until the predicate returns `false`, whereby it emits an empty list :math:`[\ ]`:
+The unfold operation is repeatedly called until the predicate returns `false`, whereby it emits an empty list :math:`[\ ]`:
 
 .. math::
    :no-wrap:
 
     \begin{align*}
-    c &= \unfold{\gt 0}{\textit{decrement}}\ n \\
-      &= \unfold{\gt 0}{\textit{decrement}}\ n-1\ \boldsymbol{+}\ [n] \\
+    c &= \unfold{greater\_than\_zero}{decrement}\ n \\
+      &= \unfold{greater\_than\_zero}{decrement}\ n-1\ \boldsymbol{+}\ [n] \\
       &\quad\quad \vdots \\
-      &= \unfold{\gt 0}{\textit{decrement}}\ 0\ \boldsymbol{+}\ [1, 2, \dots, n-1, n] \\
+      &= \unfold{greater\_than\_zero}{decrement}\ 0\ \boldsymbol{+}\ [1, 2, \dots, n-1, n] \\
       &=[\ ]\ \boldsymbol{+}\ [1, 2, \dots, n-1, n]
     \end{align*}
 
@@ -46,7 +46,7 @@ Heuristically, this can be thought of as executing the function:
        while predicate(next_value):
            # generator returns a new value for next_value
            next_value, sequence_element = generator(next_value)
-           result.append(sequence_element)
+           result.prepend(sequence_element)
        return result
 
 where the user supplies the :py:`predicate` (:math:`p`) and :py:`generator` (:math:`\textit{gen}`) algorithms.
@@ -66,7 +66,7 @@ Next Type
 
 The signatures for the operators :math:`p` and :math:`\textit{gen}` have the curious type :math:`N`, which seems unrelated to the input sequence :math:`d`, whose elements are of type :math:`D`, or the output sequence :math:`c`, whose elements are of type :math:`C`.
 The type :math:`N` refers to the type of the *next* value on which the unfold operates.
-In the :math:`\textit{iota}` example above, the type :math:`N` is the same as the input argument :math:`n`, which is an integer, and it is the same as that of the output sequence elements, which are also integers.
+In the :math:`\text{iota}` example above, the type :math:`N` is the same as the input argument :math:`n`, which is an integer, and it is the same as that of the output sequence elements, which are also integers.
 
 The unfold in :numref:`workflow`, however, demonstrates an example where :math:`N` is equal to neither :math:`D` nor :math:`C`.
 Whereas the input type :math:`D` corresponds to the :cpp:`"SimDepos"` data product in each `Spill`, the output type :math:`C` represents the :cpp:`"Waveforms"` data products produced for each `APA`.

doc/ch_conceptual_design/hofs/partitioned_folds.rst

@@ -5,7 +5,7 @@ Windows
 +---------------------------------------+---------------------------------------------------------+------------------------+
 | **Window**                            | Operators                                               | Output sequence length |
 +=======================================+=========================================================+========================+
-| :math:`y = \window{f}{adj}{label}\ x` | :math:`f': X \times \opt{X} \rightarrow Y`              | :math:`|y| = |x|`      |
+| :math:`y = \window{f}{adj}{label}\ x` | :math:`f: X \times \opt{X} \rightarrow Y`              | :math:`|y| = |x|`      |
 |                                       +---------------------------------------------------------+                        |
 |                                       | :math:`adj: \iset{x} \times \iset{x} \rightarrow \bool` |                        |
 |                                       +---------------------------------------------------------+                        |
@@ -31,12 +31,12 @@ A straightforward :math:`adj` implementation might be to group the :cpp:`"GoodHi
 
          \isequence{hs}{\text{APA}} = [\ \rlap{$\overbracket{\phantom{hs_1 \ \ hs_2}}^{a}\ \ \overbracket{\phantom{hs_3\ \ hs_4}}^{c}$}hs_1, \underbracket{hs_2,\  hs_3}_{b},\ hs_4,\ \dots,\ \underbracket{hs_{n-1},\ hs_n}_{m}\ ]
 
-The data products corresponding to windows :math:`a` through :math:`m` are grouped into pairs and presented to the :cpp:`make_tracks` algorithm, which has the signature :math:`\text{Hits} \times \text{Hits} \rightarrow \text{Tracks}`.
-There are, at most, :math:`n-1` unique pairs that can be presented to the function :cpp:`make_tracks` such that:
+The data products corresponding to windows :math:`a` through :math:`m` are grouped into pairs and presented to an algorithm :math:`make\_tracks'`, which has the signature :math:`\text{Hits} \times \text{Hits} \rightarrow \text{Tracks}`.
+There are, at most, :math:`n-1` unique pairs that can be presented to the function :math:`make\_tracks'` such that:
 
 .. math::
 
-    \left[ts_i\right]_{i \in \iset{\text{APA}}'} = \left[make\_tracks(hs_i, hs_{i+1})\right]_{i \in \iset{\text{APA}}'} = \window{make\_tracks}{adj}{\text{APA}} \isequence{hs}{\text{APA}}
+    \left[ts_i\right]_{i \in \iset{\text{APA}}'} = \left[make\_tracks'(hs_i, hs_{i+1})\right]_{i \in \iset{\text{APA}}'} = \window{make\_tracks'}{adj}{\text{APA}} \isequence{hs}{\text{APA}}
 
 where the index set :math:`\iset{\text{APA}}'` is :math:`\iset{\text{APA}}` without the last identifier :math:`n` [#flast]_.
 In this example, the identifier of the first :math:`hs` object in the pair is used to identify the tracks collection :math:`ts`.
@@ -46,40 +46,41 @@ Operator Signatures
 ^^^^^^^^^^^^^^^^^^^
 
 One limitation of the above formulation is that index sets of the input and output sequences are not the same.
-To address this infelicity, the function signature of :cpp:`make_tracks` can be adjusted such that the second argument receives an optional type:
+To address this infelicity, the function signature of :math:`make\_tracks'` can be adjusted such that the second argument receives an optional type.
+We call this new algorithm :math:`make\_tracks`:
 
 .. math::
 
-   make\_tracks': \text{Hits} \times \opt{\text{Hits}} \rightarrow \text{Tracks}
+   make\_tracks: \text{Hits} \times \opt{\text{Hits}} \rightarrow \text{Tracks}
 
 thus permitting symmetry between the input and output data-product sequences:
 
 .. math::
 
-   \isequence{ts}{\text{APA}} &= \left[make\_tracks'(hs_i, hs_{i+1})\right]_{i \in \iset{\text{APA}}'} \boldsymbol{+}\ \left[make\_tracks'(hs_n, ())\right] \\
-   &= \window{make\_tracks'}{adj}{\text{APA}} \isequence{hs}{\text{APA}}
+   \isequence{ts}{\text{APA}} &= \window{make\_tracks}{adj}{label} \isequence{hs}{\text{APA}} \\
+   &=\left[make\_tracks(hs_i, hs_{i+1})\right]_{i \in \iset{\text{APA}}'} \boldsymbol{+}\ \left[make\_tracks(hs_n, ())\right]
 
-where :math:`\boldsymbol{+}` is the list-concatenation operator, and :math:`()` is the unit element.
-Phlex supports the function signature whose second argument is an optional type :math:`\opt{X}`; the prime following the function name (e.g. :math:`f'`) is a reminder that the second argument is an optional type.
+where :math:`label` returns the value of `APA`, :math:`\boldsymbol{+}` is the list-concatenation operator, and :math:`()` is the null value.
+Phlex supports the function signature whose second argument is an optional type :math:`\opt{X}`.
 
 .. table::
     :widths: 12 88
 
     +---------------+------------------------------------------------------------------------------------+
     | **Operator**  | **Allowed signature**                                                              |
     +===============+====================================================================================+
-    | :math:`f'`    | :cpp:`return_type function_name(P1, P2*, Rm...) [quals];`                          |
+    | :math:`f`     | :cpp:`return_type function_name(P1, Opt<P2>, Rm...) [quals];`                      |
     +---------------+------------------------------------------------------------------------------------+
     | :math:`adj`   | :cpp:`bool function_name(<P1 identifier>, <P2 identifier>) [quals];`               |
     +---------------+------------------------------------------------------------------------------------+
     | :math:`label` | *Name of data-set category of output data products*                                |
     +---------------+------------------------------------------------------------------------------------+
 
 The :cpp:`return_type` must model the created data-product type described in :numref:`ch_conceptual_design/algorithms:Return Types`.
-The algorithm :math:`f'` may also create multiple data products by returning a :cpp:`std::tuple<T1, ..., Tn>`  where each of the types :cpp:`T1, ..., Tn` models a created data-product type.
+The algorithm :math:`f` may also create multiple data products by returning a :cpp:`std::tuple<T1, ..., Tn>`  where each of the types :cpp:`T1, ..., Tn` models a created data-product type.
 
-The second argument :cpp:`P2*` indicates that an optional type is passed to the algorithm.
-It is permitted to use resources (i.e. :cpp:`Rm...`) in the function :math:`f'`.
+The second argument :cpp:`Opt<P2>` indicates that an optional type is passed to the algorithm.
+It is permitted to use resources (i.e. :cpp:`Rm...`) in the function :math:`f`.
 The data-product set identifers of :cpp:`P1` and :cpp:`P2` are used to determine whether two data-products reside in adjacent data-product sets.
 
 Registration Interface
@@ -91,15 +92,16 @@ The :math:`\textit{window(make\_tracks)}` node in :numref:`workflow` would be re
 
    class hits { ... };
    class tracks { ... };
+   class id { ... };
    tracks make_tracks(tracks const& ts, tracks const* next_ts) { ... }
-   bool are_adjacent(phlex::id const& left, phlex::id const& right) { ... }
+   bool are_adjacent(id const& left, id const& right) { ... }
 
    PHLEX_REGISTER_ALGORITHMS(config)
    {
      products("GoodTracks") =
        window(
          "track_maker",          // <= Node name for framework
-         make_tracks,            // <= Window algorithm (f')
+         make_tracks,            // <= Window algorithm (f)
          are_adjacent            // <= Adjacency criterion
          "APA",                  // <= Output data-product category
          concurrency::unlimited  // <= Allowed concurrency
@@ -108,7 +110,7 @@ The :math:`\textit{window(make\_tracks)}` node in :numref:`workflow` would be re
    }
 
 Note that the second input parameter for :cpp:`make_tracks` is an optional type.
-The type :cpp:`phlex::id` is a putative type that enables the comparison of data-product set identifiers for establishing adjacency.
+The type :cpp:`id` is a metadata type (possibly defined by the experiment) that enables the comparison of data-product identifiers for establishing adjacency.
 
 .. rubric:: Footnotes