.. _py-dg/Strategies: ********************************************************** dg/Strategies ********************************************************** .. default-domain:: py .. py:currentmodule:: mod .. cpp:namespace:: mod This section describes two interfaces for the derivation graph strategies; the basic API and an embedded language which is built on the basic API. Usually the embedded strategy language is easiest and sufficient for constructing strategies. The semantics of the individual strategies are described in :ref:`dgStrat`. Note that a :class:`DGStrat` is a representation of a strategy and must be given to a derivation graph to be evaluated. .. _dg_edsl: The Embedded Strategy Language ############################### The strategy language is really a collection of proxy classes with a lot of operator overloading, thus the normal syntax and semantics of Python applies. The following is the grammar for the strategies. .. productionlist:: dgStrat strat: strats : `strat` ">>" `strat` : rule : "addSubset(" graphs ")" : "addUniverse(" graphs ")" : "execute(" executeFunc ")" : "filterSubset(" filterPred ")" : "filterUniverse(" filterPred ")" : "leftPredicate[" derivationPred "](" `strat` ")" : "rightPredicate[" derivationPred "](" `strat` ")" : "repeat" [ "[" int "]" ] "(" strat ")" : "revive(" `strat` ")" A ``strats`` must be an iterable of :token:`~dgStrat:strat`, e.g., an iterable of :class:`Rule`. A ``graphs`` can either be a single :class:`Graph`, an iterable of graphs, or a function taking no arguments and returning a list of graphs. The functions in the language have the following signatures. .. function:: addSubset(g, *gs, graphPolicy=IsomorphismPolicy.Check) addUniverse(g, *gs, graphPolicy=IsomorphismPolicy.Check) Depending on ``g`` it calls either :func:`DGStrat.makeAddStatic` or :func:`DGStrat.makeAddDynamic`. :param g: graph(s) to add, or a callback to compute them. :type g: Graph or Iterable[Graph] or Callable[[], Iterable[Graph]] :param gs: a variable amount of additional arguments with graphs, unless ``g`` is a callback, then no additional arguments may be given. :type gs: Graph or Iterable[Graph] :param IsomorphismPolicy graphPolicy: the policy to use when adding the graphs. When :attr:`IsomorphismPolicy.Check` is given, and a graph is added which is isomorphic to an existing graph in the internal database of the :class:`DG` the strategy is executed on, then a :class:`LogicError` is thrown. .. function:: execute(f) :returns: the result of :func:`DGStrat.makeExecute`. .. function:: filterSubset(p) filterUniverse(p) :returns: the result of the corresponding :func:`DGStrat.makeFilter`. .. data:: leftPredicate rightPredicate Objects of unspecified type which can be used as ``obj[pred](strat)``. This will call respectively :func:`DGStrat.makeLeftPredicate` or :func:`DGStrat.makeRightPredicate`. .. data:: repeat An object of unspecified type which can be used either as ``repeat(strat)`` or ``repeat[limit](strat)``. This will call :func:`DGStrat.makeRepeat`. .. function:: revive(strat) :returns: the result of :func:`DGStrat.makeRevive`. The Basic API ################# .. class:: DGStrat .. staticmethod:: makeAddStatic(onlyUniverse, graphs, graphPolicy) :param bool onlyUniverse: if the strategy is :ref:`strat-addUniverse` or :ref:`strat-addSubset`. :param graphs: the graphs to be added by the strategy. :type graphs: list[Graph] :param IsomorphismPolicy graphPolicy: refers to the checking of each added graph against the internal graph database. :returns: an :ref:`strat-addUniverse` strategy if ``onlyUniverse`` is ``True``, otherwise an :ref:`strat-addSubset` strategy. :rtype: DGStrat :raises: :class:`LogicError` if there is a ``None`` in ``graphs``. .. staticmethod:: makeAddDynamic(onlyUniverse, graphsFunc, graphPolicy) :param bool onlyUniverse: if the strategy is :ref:`strat-addUniverse` or :ref:`strat-addSubset`. :param graphsFunc: a function returning the graphs to be added by the strategy. :type graphsFunc: Callable[[], list[Graph]] :param IsomorphismPolicy graphPolicy: refers to the checking of each added graph against the internal graph database. :returns: an :ref:`strat-addUniverse` strategy if ``onlyUniverse`` is ``True``, otherwise an :ref:`strat-addSubset` strategy. :rtype: DGStrat .. staticmethod:: makeSequence(strats) :param strats: the strategies to evaluate in sequence. :type strats: list[DGStrat] :returns: a :ref:`strat-sequence` strategy. :rtype: DGStrat :raises: :class:`LogicError` if the given list of strategies is empty. :raises: :class:`LogicError` if there is a ``None`` in ``strats``. .. staticmethod:: makeParallel(strats) :param strats: the sub-strategies to evaluate. :type strats: list[DGStrat] :returns: a :ref:`strat-parallel` strategy. :rtype: DGStrat :raises: :class:`LogicError` if `strats` is empty. :raises: :class:`LogicError` if there is a ``None`` in ``strats``. .. staticmethod:: makeFilter(alsoUniverse, p) :param bool alsoUniverse: if the strategy is :ref:`strat-filterUniverse` or :ref:`strat-filterSubset`. :param p: the filtering predicate being called for each graph in either the subset or the universe. The predicate is called with the graph and the graph state as arguments, and a bool stating whether the call is the first in the filtering process. :type p: Callable[[Graph, DGStrat.GraphState, bool], bool] :returns: a :ref:`strat-filterUniverse` strategy if ``onlyUniverse`` is ``True``, otherwise a :ref:`strat-filterSubset` strategy. :rtype: DGStrat .. staticmethod:: makeExecute(func) :param func: A function being executed when the strategy is evaluated. :type func: Callable[[DGStrat.GraphState], None] :returns: an :ref:`strat-execute` strategy. :rtype: DGStrat .. staticmethod:: makeRule(r) :param Rule r: the rule to make into a strategy. :returns: a :ref:`strat-rule` strategy. :rtype: DGStrat :raises: :class:`LogicError` is ``r`` is ``None``. .. staticmethod:: makeLeftPredicate(p, strat) :param p: the predicate to be called on each candidate derivation. Even though the predicate is called with a :class:`Derivation` object, only the left side and the rule of the object is valid. :type p: Callable[[Derivation], bool] :param DGStrat strat: the sub-strategy to be evaluated under the constraints of the left predicate. :returns: a :ref:`strat-leftPredicate` strategy. :rtype: DGStrat :raises: :class:`LogicError` if ``strat`` is ``None``. .. staticmethod:: makeRightPredicate(p, strat) :param p: the predicate to be called on each candidate derivation. :type p: Callable[[Derivation], bool] :param DGStrat strat: the sub-strategy to be evaluated under the constraints of the right predicate. :returns: a :ref:`strat-rightPredicate` strategy. :rtype: DGStrat :raises: :class:`LogicError` if ``strat`` is ``None``. .. staticmethod:: makeRevive(strat) :param DGStrat strat: the strategy to encapsulate. :returns: a :ref:`strat-revive` strategy. :rtype: DGStrat :raises: :class:`LogicError` if ``strat`` is ``None``. .. staticmethod:: makeRepeat(limit, strat) :param int limit: the maximum number of iterations. :param DGStrat strat: the strategy to be repeated. :returns: a :ref:`strat-repeat` strategy. :rtype: DGStrat :raises: :class:`LogicError` if ``limit`` is negative. :raises: :class:`LogicError` if ``strat`` is ``None``. .. class:: GraphState This class represents a graph state with a subset :math:`S` and a universe :math:`U` fulfilling :math:`S\subseteq U`. .. attribute:: subset The subset :math:`\mathcal{S}`. :type: list[Graph] .. attribute:: universe The universe :math:`\mathcal{U}`. :type: list[Graph]