Adding "MaxDestroyerEvents" as a step spec to WolframModel (C++) (#619)

## Changes

* Closes #611.
* Adds the `"MaxDestroyerEvents"` (per expression) to `WolframModel` as a step specification:
```wl
WolframModel[{{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}},
             {{1, 1}, {1, 1}},
             <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 2|>,
             "EventSelectionFunction" -> "MultiwaySpacelike"]
```

## Comments
* This works as follows:
The causal graph keeps track of how many destroyer events each expression has (`expressionsIDsToDestroyerEventsCount_`).
During evolution, we check if the destroyer event count of an expression (`causalGraph_.destroyerEventsCount(expressionID)`) exceeds the maximum allowed (`maxDestroyerEvents_`), and if it does, we eliminate that expression and matches related to that expression from the matcher. 

* Missing tests, both for C++ and WL.
* Missing documentation.

## Examples

* Notice how `"MaxDestroyerEvents"` is not a stopping condition, but behaves similar to an event selection function:
```wl
In[] := Table[
  WolframModel[
    {{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}},
    {{1, 1}, {1, 1}},
    <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> maxDestroyerEvents|>,
    "EventSelectionFunction" -> "MultiwaySpacelike"
    ]["ExpressionsEventsGraph", VertexLabels -> "Index"],
  {maxDestroyerEvents, {1, 2, Infinity}}] // GraphicsRow
```

![MaxDestroyerEventsComparison](https://user-images.githubusercontent.com/40190339/109845600-52cc1600-7c1b-11eb-97ec-70992ca65f13.png)

* This is also supported for `"EventSelectionFunction" -> None`:
 ```wl
In[] := Table[
  WolframModel[
    {{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}},
    {{1, 1}, {1, 1}},
    <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> maxDestroyerEvents|>,
    "EventSelectionFunction" -> None
    ]["ExpressionsEventsGraph", VertexLabels -> "Index"],
  {maxDestroyerEvents, {1, 2, 3, Infinity}}] // GraphicsRow
```
![MaxDestroyerEventsComparison2](https://user-images.githubusercontent.com/40190339/109846386-25339c80-7c1c-11eb-88df-2ce339e35f2b.png)

* `"MaxDestroyerEvent" -> 1`, for any `"EventSelectionFunction"`, behaves effectively as a singleway system:
```wl
In[] := Table[
  WolframModel[
    {{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}},
    {{1, 1}, {1, 1}},
    <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 1|>,
    "EventSelectionFunction" -> esf
    ]["ExpressionsEventsGraph", VertexLabels -> "Index"],
  {esf, {"GlobalSpacelike", "MultiwaySpacelike", 
    None}}] // GraphicsRow
```
![MaxDestroyerEventsComparison3](https://user-images.githubusercontent.com/40190339/109846710-75aafa00-7c1c-11eb-8a59-85ca7243d5e4.png)

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/maxitg/setreplace/619)
<!-- Reviewable:end -->

Author: daneelsan

Documentation/SymbolsAndFunctions/WolframModelAndWolframModelEvolutionObject/WolframModelAndWolframModelEvolutionObject.md

@@ -332,6 +332,8 @@ In[] := WolframModel[{{1, 2, 3}, {4, 5, 6}, {2, 5}, {5, 2}} ->
 All possible keys in that association are:
 
 * `"MaxEvents"`: limit the number of individual replacements (in the [`SetReplace`](../SetReplace.md) function meaning).
+* `"MaxDestroyerEvents"`: limits the number of destroyer events per expression. That is, when the destroyer events count
+  of a given expression reaches the maximum number allowed, no further match will involve said expression.
 * `"MaxGenerations"`: limit the number of generations (steps in [`SetReplaceAll`](../SetReplace.md) meaning), same as
   specifying steps directly as a number in `WolframModel`.
 * `"MaxVertices"`: limit the number of vertices in the *final* state only (the total count throughout evolution might be
@@ -349,6 +351,10 @@ attempt to match edges with generations over the limit. Therefore unlike, i.e.,
 the evolution immediately once the limit-violating event is attempted, `"MaxGenerations"` would keep "filling in" events
 for as long as possible until no further matches within allowed generations are possible.
 
+Similarly, the evolution does not terminate when one expression reaches the `"MaxDestroyerEvents"`, but instead the
+expression is removed from future matches. Evolution continues until there are no more expressions whose destroyer
+events count is less than the maximum allowed.
+
 It is also possible to set the step count to `Automatic`, in which case `WolframModel` tries to automatically pick a
 number of steps that showcases the evolution without taking too long. It stops the evolution sooner if the state grows
 quickly:

Kernel/setSubstitutionSystem$cpp.m

@@ -116,16 +116,17 @@
   7 -> $Aborted
 |>;
 
-systemTypeCode[eventSelectionFunction_] := Boole[multiwayEventSelectionFunctionQ[eventSelectionFunction]];
+(* GlobalSpacelike is syntactic sugar for "EventSelectionFunction" -> "MultiwaySpacelike", "MaxDestroyerEvents" -> 1 *)
+
+maxDestroyerEvents[_, $globalSpacelike] = 1;
+maxDestroyerEvents[Automatic | _ ? MissingQ | Infinity, _] = $maxInt64;
+maxDestroyerEvents[n_, _] := n;
 
 (* 0 -> All
    1 -> Spacelike *)
 
-(* GlobalSpacelike is set to All because all concurrently matched expressions are always spacelike in that case,
-   and All is much faster to evaluate. *)
-
 eventSelectionCodes[eventSelectionFunction_, ruleCount_] :=
-  ConstantArray[eventSelectionFunction /. {$globalSpacelike -> 0, None -> 0, $spacelike -> 1}, ruleCount];
+  ConstantArray[eventSelectionFunction /. {None -> 0, ($globalSpacelike | $spacelike) -> 1}, ruleCount];
 
 $orderingFunctionCodes = <|
   $sortedExpressionIDs -> 0,
@@ -167,7 +168,7 @@
     encodeNestedLists[List @@@ mappedRules],
     eventSelectionCodes[eventSelectionFunction, Length[canonicalRules]],
     encodeNestedLists[mappedSet],
-    systemTypeCode[eventSelectionFunction],
+    maxDestroyerEvents[stepSpec[$maxDestroyerEvents], eventSelectionFunction],
     Catenate[Replace[eventOrderingFunction, $orderingFunctionCodes, {2}]],
     Replace[eventDeduplication, $eventDeduplicationCodes],
     RandomInteger[{0, $maxUInt32}]

Kernel/setSubstitutionSystem.m

@@ -18,6 +18,7 @@
 PackageScope["$stepSpecKeys"]
 PackageScope["$maxEvents"]
 PackageScope["$maxGenerationsLocal"]
+PackageScope["$maxDestroyerEvents"]
 PackageScope["$maxFinalVertices"]
 PackageScope["$maxFinalVertexDegree"]
 PackageScope["$maxFinalExpressions"]
@@ -88,6 +89,7 @@
   (* local means the evolution will keep running until no further matches can be made exceeding the max generation.
     This might result in a different evolution order. *)
   $maxGenerationsLocal -> "MaxGenerations",
+  $maxDestroyerEvents -> "MaxDestroyerEvents",
   (* these are any level-2 expressions in the set, not just atoms. *)
   $maxFinalVertices -> "MaxVertices",
   $maxFinalVertexDegree -> "MaxVertexDegree",
@@ -96,6 +98,7 @@
 $stepSpecNamesInErrorMessage = <|
   $maxEvents -> "number of replacements",
   $maxGenerationsLocal -> "number of generations",
+  $maxDestroyerEvents -> "number of destroyer events",
   $maxFinalVertices -> "number of vertices",
   $maxFinalVertexDegree -> "vertex degree",
   $maxFinalExpressions -> "number of edges"|>;
@@ -233,7 +236,7 @@
   "SameInputSetIsomorphicOutputs" -> $sameInputSetIsomorphicOutputs
 |>;
 
-parseParameterValue[caller_, name_, value_, association_] /; MemberQ[Keys[association], value] := association[value];
+parseParameterValue[caller_, name_, value_, association_] /; KeyMemberQ[association, value] := association[value];
 
 General::invalidParameterValue = "`1` `2` should be one of `3`.";
 

Tests/WolframModel.wlt

@@ -355,6 +355,65 @@
         {4, 12, "MaxEvents"}
       ],
 
+      (*** MaxDestroyerEvents ***)
+      With[{rule = {{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}}, init = {{1, 1}, {1, 1}}},
+        {
+          VerificationTest[
+            WolframModel[
+              rule,
+              init,
+              <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 5|>,
+              "EventSelectionFunction" -> "GlobalSpacelike"],
+            WolframModel[
+              rule,
+              init,
+              <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 1|>,
+              "EventSelectionFunction" -> "GlobalSpacelike"]
+          ],
+
+          VerificationTest[
+            WolframModel[rule, init, <|"MaxEvents" -> 5|>],
+            WolframModel[
+              rule,
+              init,
+              <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 1|>,
+              "EventSelectionFunction" -> "MultiwaySpacelike"]
+          ],
+
+          VerificationTest[
+            WolframModel[
+              rule,
+              init,
+              <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 0|>,
+              "EventSelectionFunction" -> "MultiwaySpacelike"]["GenerationsCount"],
+            {0, 0}
+          ]
+        }
+      ],
+
+      VerificationTest[
+        WolframModel[
+          {{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}},
+          {{1, 1}, {1, 1}},
+          <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 2|>,
+          "EventSelectionFunction" -> "MultiwaySpacelike"]["EdgeDestroyerEventsIndices"],
+        {{1, 2}, {1, 2}, {3, 4}, {3, 5}, {4}, {5}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}}
+      ],
+
+      VerificationTest[
+        WolframModel[
+          {{1, 2}, {2, 3}} -> {{2, 3}, {2, 4}, {3, 4}, {2, 1}},
+          {{1, 1}, {1, 1}},
+          <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> 3|>,
+          "EventSelectionFunction" -> "MultiwaySpacelike"]["EdgeDestroyerEventsIndices"],
+        {{1, 2}, {1, 2}, {3, 4, 5}, {3}, {4}, {5}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}}
+      ],
+
+      testUnevaluated[
+        WolframModel[1 -> 2, {1}, <|"MaxEvents" -> 5, "MaxDestroyerEvents" -> -1|>],
+        {WolframModel::invalidSteps}
+      ],
+
       (*** MaxVertices ***)
 
       Table[With[{method = method, $simpleGrowingRule = {{1, 2}} -> {{1, 3}, {3, 2}}, $simpleGrowingInit = {{1, 1}}}, {

libSetReplace/Event.cpp

@@ -10,6 +10,7 @@ class CausalGraph::Implementation {
   // the first event is the "fake" initialization event
   std::vector<Event> events_;
   std::vector<EventID> expressionIDsToCreatorEvents_;
+  std::vector<uint64_t> expressionIDsToDestroyerEventsCount_;
 
   // needed to return the largest generation in O(1)
   Generation largestGeneration_ = 0;
@@ -34,6 +35,7 @@ class CausalGraph::Implementation {
   std::vector<ExpressionID> addEvent(const RuleID ruleID,
                                      const std::vector<ExpressionID>& inputExpressions,
                                      const int outputExpressionsCount) {
+    incrementDestroyerEventsCount(inputExpressions);
     const auto newExpressions = createExpressions(events_.size(), outputExpressionsCount);
     const Generation generation = newEventGeneration(inputExpressions);
     events_.push_back({ruleID, inputExpressions, newExpressions, generation});
@@ -88,13 +90,22 @@ class CausalGraph::Implementation {
     return SeparationType::Spacelike;
   }
 
+  uint64_t destroyerEventsCount(const ExpressionID id) { return expressionIDsToDestroyerEventsCount_[id]; }
+
  private:
   std::vector<ExpressionID> createExpressions(const EventID creatorEvent, const int count) {
     const size_t beginIndex = expressionIDsToCreatorEvents_.size();
     expressionIDsToCreatorEvents_.insert(expressionIDsToCreatorEvents_.end(), count, creatorEvent);
+    expressionIDsToDestroyerEventsCount_.insert(expressionIDsToDestroyerEventsCount_.end(), count, 0);
     return idsRange(beginIndex, expressionIDsToCreatorEvents_.size());
   }
 
+  void incrementDestroyerEventsCount(const std::vector<ExpressionID>& inputExpressions) {
+    for (const auto& id : inputExpressions) {
+      ++expressionIDsToDestroyerEventsCount_[id];
+    }
+  }
+
   static std::vector<ExpressionID> idsRange(const ExpressionID beginIndex, const ExpressionID endIndex) {
     std::vector<ExpressionID> result;
     result.reserve(endIndex - beginIndex);
@@ -167,4 +178,8 @@ Generation CausalGraph::largestGeneration() const { return implementation_->larg
 SeparationType CausalGraph::expressionsSeparation(const ExpressionID first, const ExpressionID second) const {
   return implementation_->expressionsSeparation(first, second);
 }
+
+uint64_t CausalGraph::destroyerEventsCount(const ExpressionID id) const {
+  return implementation_->destroyerEventsCount(id);
+}
 }  // namespace SetReplace

libSetReplace/Event.hpp

@@ -85,6 +85,10 @@ class CausalGraph {
    */
   SeparationType expressionsSeparation(ExpressionID first, ExpressionID second) const;
 
+  /** @brief Number of destroyer events per expression.
+   */
+  uint64_t destroyerEventsCount(ExpressionID id) const;
+
  private:
   class Implementation;
   std::shared_ptr<Implementation> implementation_;

libSetReplace/Set.cpp

@@ -17,7 +17,7 @@ class Set::Implementation {
 
   // Determines the limiting conditions for the evaluation.
   StepSpecification stepSpec_ = {0, 0, 0, 0, 0};  // don't evolve unless asked to.
-  const SystemType systemType_;
+  const uint64_t maxDestroyerEvents_;
   TerminationReason terminationReason_ = TerminationReason::NotTerminated;
 
   std::unordered_map<ExpressionID, AtomsVector> expressions_;
@@ -40,14 +40,14 @@ class Set::Implementation {
  public:
   Implementation(const std::vector<Rule>& rules,
                  const std::vector<AtomsVector>& initialExpressions,
-                 const SystemType& systemType,
+                 const uint64_t maxDestroyerEvents,
                  const Matcher::OrderingSpec& orderingSpec,
                  const Matcher::EventDeduplication& eventDeduplication,
                  const unsigned int randomSeed)
       : Implementation(
             rules,
             initialExpressions,
-            systemType,
+            maxDestroyerEvents,
             orderingSpec,
             eventDeduplication,
             randomSeed,
@@ -98,18 +98,6 @@ class Set::Implementation {
 
     // At this point, we are committed to modifying the set.
 
-    // This goes first, as if the system type is invalid, we want to fail before modifying anything else.
-    if (systemType_ == SystemType::Singleway) {
-      matcher_.removeMatchesInvolvingExpressions(match->inputExpressions);
-      atomsIndex_.removeExpressions(match->inputExpressions);
-      destroyedExpressionsCount_ += match->inputExpressions.size();
-      updateAtomDegrees(&atomDegrees_, match->inputExpressions, -1);
-    } else if (systemType_ == SystemType::Multiway) {
-      matcher_.deleteMatch(match);
-    } else {
-      throw Error::InvalidSystemType;
-    }
-
     // Name newly created atoms as well, now all atoms in the output are explicitly named.
     const auto namedRuleOutputs = nameAnonymousAtoms(explicitRuleOutputs);
 
@@ -118,12 +106,36 @@ class Set::Implementation {
 
     addExpressions(outputExpressionIDs, namedRuleOutputs);
 
+    if (maxDestroyerEvents_ == 1) {
+      matcher_.removeMatchesInvolvingExpressions(match->inputExpressions);
+      atomsIndex_.removeExpressions(match->inputExpressions);
+      // The following only make sense for singleway systems.
+      destroyedExpressionsCount_ += match->inputExpressions.size();
+      updateAtomDegrees(&atomDegrees_, match->inputExpressions, -1);
+    } else if (maxDestroyerEvents_ == static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
+      matcher_.deleteMatch(match);
+    } else {
+      // Only remove expressions whose destroyer events count reached the maximum.
+      matcher_.deleteMatch(match);
+      std::vector<ExpressionID> inputExpressionsToRemove;
+      for (const auto& id : match->inputExpressions) {
+        if (causalGraph_.destroyerEventsCount(id) >= maxDestroyerEvents_) {
+          inputExpressionsToRemove.push_back(id);
+        }
+      }
+      matcher_.removeMatchesInvolvingExpressions(inputExpressionsToRemove);
+      atomsIndex_.removeExpressions(inputExpressionsToRemove);
+    }
+
     return 1;
   }
 
   int64_t replace(const StepSpecification stepSpec, const std::function<bool()>& shouldAbort) {
     updateStepSpec(stepSpec);
     int64_t count = 0;
+    if (maxDestroyerEvents_ == 0) {
+      return count;
+    }
     while (true) {
       if (replaceOnce(shouldAbort)) {
         ++count;
@@ -156,17 +168,17 @@ class Set::Implementation {
   const std::vector<Event>& events() const { return causalGraph_.events(); }
 
  private:
-  Implementation(std::vector<Rule> rules,
+  Implementation(const std::vector<Rule>& rules,
                  const std::vector<AtomsVector>& initialExpressions,
-                 const SystemType& systemType,
+                 const uint64_t maxDestroyerEvents,
                  const Matcher::OrderingSpec& orderingSpec,
                  const Matcher::EventDeduplication& eventDeduplication,
                  const unsigned int randomSeed,
                  const GetAtomsVectorFunc& getAtomsVector,
                  const GetExpressionsSeparationFunc& getExpressionsSeparation)
-      : rules_(rules),
-        systemType_(systemType),
-        causalGraph_(static_cast<int>(initialExpressions.size()), separationTrackingMethod(systemType, rules)),
+      : rules_(optimizeRules(rules, maxDestroyerEvents)),
+        maxDestroyerEvents_(maxDestroyerEvents),
+        causalGraph_(static_cast<int>(initialExpressions.size()), separationTrackingMethod(maxDestroyerEvents, rules)),
         atomsIndex_(getAtomsVector),
         matcher_(rules_,
                  &atomsIndex_,
@@ -185,6 +197,24 @@ class Set::Implementation {
     addExpressions(causalGraph_.allExpressionIDs(), initialExpressions);
   }
 
+  std::vector<Rule> optimizeRules(const std::vector<Rule>& rules, uint64_t maxDestroyerEvents) {
+    if (maxDestroyerEvents == 1) {
+      // The real optimization happens later when we call separationTrackingMethod(1, rules) by setting
+      // SeparationTrackingMethod to None.
+      // EventSelectionFunction is set to All in each rule to prevent breaking: SeparationTrackingMethod::None causes
+      // isSpacelikeSeparated(...) to be always false for any expression pair, thus no new event whose rule is only
+      // applied when expressions are spacelike separated would occur.
+      std::vector<Rule> newRules;
+      newRules.reserve(rules.size());
+      for (const auto& rule : rules) {
+        newRules.push_back(Rule{rule.inputs, rule.outputs, EventSelectionFunction::All});
+      }
+      return newRules;
+    } else {
+      return rules;
+    }
+  }
+
   Atom incrementNextAtom() {
     if (nextAtom_ == std::numeric_limits<Atom>::max()) {
       throw Error::AtomCountOverflow;
@@ -223,7 +253,7 @@ class Set::Implementation {
     unindexedExpressions_.clear();
   }
 
-  bool isMultiway() const { return systemType_ != SystemType::Singleway; }
+  bool isMultiway() const { return maxDestroyerEvents_ > 1; }
 
   TerminationReason willExceedAtomLimits(const std::vector<AtomsVector>& explicitRuleInputs,
                                          const std::vector<AtomsVector>& explicitRuleOutputs) const {
@@ -349,9 +379,10 @@ class Set::Implementation {
     return smallestSoFar;
   }
 
-  static CausalGraph::SeparationTrackingMethod separationTrackingMethod(const SystemType systemType,
+  static CausalGraph::SeparationTrackingMethod separationTrackingMethod(const uint64_t maxDestroyerEvents,
                                                                         const std::vector<Rule>& rules) {
-    if (systemType == SystemType::Singleway) {
+    if (maxDestroyerEvents == 1) {
+      // No need of tracking the separation between expressions if these are removed after each destroyer event.
       return CausalGraph::SeparationTrackingMethod::None;
     }
     for (const auto& rule : rules) {
@@ -365,12 +396,12 @@ class Set::Implementation {
 
 Set::Set(const std::vector<Rule>& rules,
          const std::vector<AtomsVector>& initialExpressions,
-         const SystemType& eventSelectionFunction,
+         uint64_t maxDestroyerEvents,
          const Matcher::OrderingSpec& orderingSpec,
          const Matcher::EventDeduplication& eventDeduplication,
          unsigned int randomSeed)
     : implementation_(std::make_shared<Implementation>(
-          rules, initialExpressions, eventSelectionFunction, orderingSpec, eventDeduplication, randomSeed)) {}
+          rules, initialExpressions, maxDestroyerEvents, orderingSpec, eventDeduplication, randomSeed)) {}
 
 int64_t Set::replaceOnce(const std::function<bool()>& shouldAbort) {
   return implementation_->replaceOnce(shouldAbort, true);