----------
Predicates
----------

+--------------------------------------+--------------------------------+---------------------------+
| **Predicate**                        | Operator                       | Output family length      |
+======================================+================================+===========================+
| :math:`\tilde{b} = \predicate{f}\ a` | :math:`f: A \rightarrow \bool` | :math:`|\tilde{b}| = |a|` |
+--------------------------------------+--------------------------------+---------------------------+

The predicate HOF is a transform (see :numref:`ch_conceptual_design/hofs/transforms:Transforms`) whose operator returns Boolean `true` or `false`.
However, instead of the framework interpreting the Boolean result as a data product, the return value is used to short-circuit the processing of the data-flow graph for data products that do not meet the specified criteria.
This short-circuiting behavior is known as *filtering* and is described in :numref:`ch_conceptual_design/hofs/filters:Filtering`.

Note that the output family generated by the predicate is the same length as the input family but with values that are either Boolean `true` or `false`.
It is not until the predicate results are used by the filter that an input family is potentially reduced in length.

.. note::

   Phlex will schedule a predicate HOF for execution only if it is included in a predicate expression (see :numref:`ch_conceptual_design/hofs/filters:Filtering`).

Operator Signature
^^^^^^^^^^^^^^^^^^

.. table::
    :widths: 15 85

    +--------------+------------------------------------------------------+
    | **Operator** | **Allowed signature**                                |
    +==============+======================================================+
    | :math:`f`    | :cpp:`bool function_name(P1, Pn..., Rm...) [quals];` |
    +--------------+------------------------------------------------------+


Registration Interface
^^^^^^^^^^^^^^^^^^^^^^

The workflow in :numref:`workflow` demonstrates a use of a predicate in the :mathfunc:`filter(high_energy)` node, where the predicate is :mathfunc:`high_energy` that operates on each :product:`GoodHits` data product.
Although :numref:`workflow` does not include an explicit node for the :mathfunc:`high_energy` predicate (for reasons of exposition), the predicate HOF *does* have its own node, which is then bound to one or more filters via predicate expressions.
The registration for the predicate node in :numref:`workflow` would look like:

.. code:: c++

   class hits { ... };
   bool high_energy(hits const& hs) { ... }

   PHLEX_REGISTER_ALGORITHMS(config)
   {
     predicate("high_energy", high_energy, concurrency::unlimited)
       .family("GoodHits"_in("APA"));
   }