Add the distributed equality engine manager (#4867)

This is the first step towards making the approach for theory combination in CVC4 configurable.

This PR introduces the "distributed equality engine manager", which encapsulates the current policy that TheoryEngine uses regarding equality engines: each Theory creates a separate copy of an equality engine. The eventual plan is that the official equality engine of Theory is not necessarily unique to the theory, if equality engines are shared. A variant of this class could implement that policy.

This PR does not impact the code, it simply adds the definition of the class. A forthcoming PR will integrate this class into TheoryEngine, which will use dynamic allocation for equality engine objects.

FYI @barrettcw

6 files changed, 353 insertions, 5 deletions

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 67692f5c0..77c363317 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -478,6 +478,9 @@ libcvc4_add_sources(
   theory/decision_strategy.h
   theory/eager_proof_generator.cpp
   theory/eager_proof_generator.h
+  theory/ee_manager_distributed.cpp
+  theory/ee_manager_distributed.h
+  theory/ee_setup_info.h
   theory/engine_output_channel.cpp
   theory/engine_output_channel.h
   theory/evaluator.cpp
diff --git a/src/theory/ee_manager_distributed.cpp b/src/theory/ee_manager_distributed.cpp
new file mode 100644
index 000000000..21237816f
--- /dev/null
+++ b/src/theory/ee_manager_distributed.cpp
@@ -0,0 +1,126 @@
+/*********************                                                        */
+/*! \file ee_manager_distributed.cpp
+ ** \verbatim
+ ** Top contributors (to current version):
+ **   Andrew Reynolds
+ ** This file is part of the CVC4 project.
+ ** Copyright (c) 2009-2020 by the authors listed in the file AUTHORS
+ ** in the top-level source directory) and their institutional affiliations.
+ ** All rights reserved.  See the file COPYING in the top-level source
+ ** directory for licensing information.\endverbatim
+ **
+ ** \brief Management of a distributed approach for equality sharing.
+ **/
+
+#include "theory/ee_manager_distributed.h"
+
+#include "theory/quantifiers_engine.h"
+#include "theory/theory_engine.h"
+
+namespace CVC4 {
+namespace theory {
+
+const EeTheoryInfo* EqEngineManager::getEeTheoryInfo(TheoryId tid) const
+{
+  std::map<TheoryId, EeTheoryInfo>::const_iterator it = d_einfo.find(tid);
+  if (it != d_einfo.end())
+  {
+    return &it->second;
+  }
+  return nullptr;
+}
+
+EqEngineManagerDistributed::EqEngineManagerDistributed(TheoryEngine& te)
+    : d_te(te), d_masterEENotify(nullptr)
+{
+}
+
+EqEngineManagerDistributed::~EqEngineManagerDistributed() {}
+
+void EqEngineManagerDistributed::finishInit()
+{
+  context::Context* c = d_te.getSatContext();
+  // allocate equality engines per theory
+  for (TheoryId theoryId = theory::THEORY_FIRST;
+       theoryId != theory::THEORY_LAST;
+       ++theoryId)
+  {
+    Theory* t = d_te.theoryOf(theoryId);
+    if (t == nullptr)
+    {
+      // theory not active, skip
+      continue;
+    }
+    // always allocate an object in d_einfo here
+    EeTheoryInfo& eet = d_einfo[theoryId];
+    EeSetupInfo esi;
+    if (!t->needsEqualityEngine(esi))
+    {
+      // theory said it doesn't need an equality engine, skip
+      continue;
+    }
+    // allocate the equality engine
+    eet.d_allocEe.reset(allocateEqualityEngine(esi, c));
+  }
+
+  const LogicInfo& logicInfo = d_te.getLogicInfo();
+  if (logicInfo.isQuantified())
+  {
+    // construct the master equality engine
+    Assert(d_masterEqualityEngine == nullptr);
+    QuantifiersEngine* qe = d_te.getQuantifiersEngine();
+    Assert(qe != nullptr);
+    d_masterEENotify.reset(new MasterNotifyClass(qe));
+    d_masterEqualityEngine.reset(new eq::EqualityEngine(*d_masterEENotify.get(),
+                                                        d_te.getSatContext(),
+                                                        "theory::master",
+                                                        false));
+
+    for (TheoryId theoryId = theory::THEORY_FIRST;
+         theoryId != theory::THEORY_LAST;
+         ++theoryId)
+    {
+      Theory* t = d_te.theoryOf(theoryId);
+      if (t == nullptr)
+      {
+        // theory not active, skip
+        continue;
+      }
+      EeTheoryInfo& eet = d_einfo[theoryId];
+      // Get the allocated equality engine, and connect it to the master
+      // equality engine.
+      eq::EqualityEngine* eeAlloc = eet.d_allocEe.get();
+      if (eeAlloc != nullptr)
+      {
+        // set the master equality engine of the theory's equality engine
+        eeAlloc->setMasterEqualityEngine(d_masterEqualityEngine.get());
+      }
+    }
+  }
+}
+
+void EqEngineManagerDistributed::MasterNotifyClass::eqNotifyNewClass(TNode t)
+{
+  // adds t to the quantifiers term database
+  d_quantEngine->eqNotifyNewClass(t);
+}
+
+eq::EqualityEngine* EqEngineManagerDistributed::getMasterEqualityEngine()
+{
+  return d_masterEqualityEngine.get();
+}
+
+eq::EqualityEngine* EqEngineManagerDistributed::allocateEqualityEngine(
+    EeSetupInfo& esi, context::Context* c)
+{
+  if (esi.d_notify != nullptr)
+  {
+    return new eq::EqualityEngine(
+        *esi.d_notify, c, esi.d_name, esi.d_constantsAreTriggers);
+  }
+  // the theory doesn't care about explicit notifications
+  return new eq::EqualityEngine(c, esi.d_name, esi.d_constantsAreTriggers);
+}
+
+}  // namespace theory
+}  // namespace CVC4
diff --git a/src/theory/ee_manager_distributed.h b/src/theory/ee_manager_distributed.h
new file mode 100644
index 000000000..67140515a
--- /dev/null
+++ b/src/theory/ee_manager_distributed.h
@@ -0,0 +1,145 @@
+/*********************                                                        */
+/*! \file ee_manager_distributed.h
+ ** \verbatim
+ ** Top contributors (to current version):
+ **   Andrew Reynolds
+ ** This file is part of the CVC4 project.
+ ** Copyright (c) 2009-2020 by the authors listed in the file AUTHORS
+ ** in the top-level source directory) and their institutional affiliations.
+ ** All rights reserved.  See the file COPYING in the top-level source
+ ** directory for licensing information.\endverbatim
+ **
+ ** \brief Management of a distributed approach for equality engines over
+ ** all theories.
+ **/
+
+#include "cvc4_private.h"
+
+#ifndef CVC4__THEORY__EE_MANAGER_DISTRIBUTED__H
+#define CVC4__THEORY__EE_MANAGER_DISTRIBUTED__H
+
+#include <map>
+#include <memory>
+
+#include "theory/ee_setup_info.h"
+#include "theory/theory.h"
+#include "theory/uf/equality_engine.h"
+
+namespace CVC4 {
+
+class TheoryEngine;
+
+namespace theory {
+
+/**
+ * This is (theory-agnostic) information associated with the management of
+ * an equality engine for a single theory. This information is maintained
+ * by the manager class below.
+ *
+ * Currently, this simply is the equality engine itself, which is a unique_ptr
+ * for memory management purposes.
+ */
+struct EeTheoryInfo
+{
+  /** The equality engine allocated by this theory (if it exists) */
+  std::unique_ptr<eq::EqualityEngine> d_allocEe;
+};
+
+/** Virtual base class for equality engine managers */
+class EqEngineManager
+{
+ public:
+  virtual ~EqEngineManager() {}
+  /**
+   * Get the equality engine theory information for theory with the given id.
+   */
+  const EeTheoryInfo* getEeTheoryInfo(TheoryId tid) const;
+
+ protected:
+  /** Information related to the equality engine, per theory. */
+  std::map<TheoryId, EeTheoryInfo> d_einfo;
+};
+
+/**
+ * The (distributed) equality engine manager. This encapsulates an architecture
+ * in which all theories maintain their own copy of an equality engine.
+ *
+ * This class is not responsible for actually initializing equality engines in
+ * theories (since this class does not have access to the internals of Theory).
+ * Instead, it is only responsible for the construction of the equality
+ * engine objects themselves. TheoryEngine is responsible for querying this
+ * class during finishInit() to determine the equality engines to pass to each
+ * theories based on getEeTheoryInfo.
+ *
+ * This class is also responsible for setting up the master equality engine,
+ * which is used as a special communication channel to quantifiers engine (e.g.
+ * for ensuring quantifiers E-matching is aware of terms from all theories).
+ */
+class EqEngineManagerDistributed : public EqEngineManager
+{
+ public:
+  EqEngineManagerDistributed(TheoryEngine& te);
+  ~EqEngineManagerDistributed();
+  /**
+   * Finish initialize, called by TheoryEngine::finishInit after theory
+   * objects have been created but prior to their final initialization. This
+   * sets up equality engines for all theories.
+   *
+   * This method is context-independent, and is applied once during
+   * the lifetime of TheoryEngine (during finishInit).
+   */
+  void finishInit();
+  /** get the master equality engine */
+  eq::EqualityEngine* getMasterEqualityEngine();
+
+ private:
+  /** notify class for master equality engine */
+  class MasterNotifyClass : public theory::eq::EqualityEngineNotify
+  {
+   public:
+    MasterNotifyClass(QuantifiersEngine* qe) : d_quantEngine(qe) {}
+    /**
+     * Called when a new equivalence class is created in the master equality
+     * engine.
+     */
+    void eqNotifyNewClass(TNode t) override;
+
+    bool eqNotifyTriggerEquality(TNode equality, bool value) override
+    {
+      return true;
+    }
+    bool eqNotifyTriggerPredicate(TNode predicate, bool value) override
+    {
+      return true;
+    }
+    bool eqNotifyTriggerTermEquality(TheoryId tag,
+                                     TNode t1,
+                                     TNode t2,
+                                     bool value) override
+    {
+      return true;
+    }
+    void eqNotifyConstantTermMerge(TNode t1, TNode t2) override {}
+    void eqNotifyPreMerge(TNode t1, TNode t2) override {}
+    void eqNotifyPostMerge(TNode t1, TNode t2) override {}
+    void eqNotifyDisequal(TNode t1, TNode t2, TNode reason) override {}
+
+   private:
+    /** Pointer to quantifiers engine */
+    QuantifiersEngine* d_quantEngine;
+  };
+  /** Allocate equality engine that is context-dependent on c with info esi */
+  eq::EqualityEngine* allocateEqualityEngine(EeSetupInfo& esi,
+                                             context::Context* c);
+  /** Reference to the theory engine */
+  TheoryEngine& d_te;
+  /** The master equality engine notify class */
+  std::unique_ptr<MasterNotifyClass> d_masterEENotify;
+  /** The master equality engine. */
+  std::unique_ptr<eq::EqualityEngine> d_masterEqualityEngine;
+};
+
+}  // namespace theory
+}  // namespace CVC4
+
+#endif /* CVC4__THEORY__EE_MANAGER_DISTRIBUTED__H */
diff --git a/src/theory/ee_setup_info.h b/src/theory/ee_setup_info.h
new file mode 100644
index 000000000..c029fcd04
--- /dev/null
+++ b/src/theory/ee_setup_info.h
@@ -0,0 +1,52 @@
+/*********************                                                        */
+/*! \file ee_setup_info.h
+ ** \verbatim
+ ** Top contributors (to current version):
+ **   Andrew Reynolds
+ ** This file is part of the CVC4 project.
+ ** Copyright (c) 2009-2020 by the authors listed in the file AUTHORS
+ ** in the top-level source directory) and their institutional affiliations.
+ ** All rights reserved.  See the file COPYING in the top-level source
+ ** directory for licensing information.\endverbatim
+ **
+ ** \brief Setup information for an equality engine.
+ **/
+
+#include "cvc4_private.h"
+
+#ifndef CVC4__THEORY__EE_SETUP_INFO__H
+#define CVC4__THEORY__EE_SETUP_INFO__H
+
+#include <string>
+
+namespace CVC4 {
+namespace theory {
+
+namespace eq {
+class EqualityEngineNotify;
+}
+
+/**
+ * This is a helper class that encapsulates instructions for how a Theory
+ * wishes to initialize and setup notifications with its official equality
+ * engine, e.g. via a notification class (eq::EqualityEngineNotify).
+ *
+ * This includes (at a basic level) the arguments to the equality engine
+ * constructor that theories may wish to modify. This information is determined
+ * by the Theory during needsEqualityEngine.
+ */
+struct EeSetupInfo
+{
+  EeSetupInfo() : d_notify(nullptr), d_constantsAreTriggers(true) {}
+  /** The notification class of the theory */
+  eq::EqualityEngineNotify* d_notify;
+  /** The name of the equality engine */
+  std::string d_name;
+  /** Constants are triggers */
+  bool d_constantsAreTriggers;
+};
+
+}  // namespace theory
+}  // namespace CVC4
+
+#endif /* CVC4__THEORY__EE_SETUP_INFO__H */
diff --git a/src/theory/theory.cpp b/src/theory/theory.cpp
index f6532b1e5..f1bfd052d 100644
--- a/src/theory/theory.cpp
+++ b/src/theory/theory.cpp
@@ -91,6 +91,8 @@ Theory::~Theory() {
   smtStatisticsRegistry()->unregisterStat(&d_computeCareGraphTime);
 }
 
+bool Theory::needsEqualityEngine(EeSetupInfo& esi) { return false; }
+
 TheoryId Theory::theoryOf(options::TheoryOfMode mode, TNode node)
 {
   TheoryId tid = THEORY_BUILTIN;
diff --git a/src/theory/theory.h b/src/theory/theory.h
index fecdafb17..e40534dc4 100644
--- a/src/theory/theory.h
+++ b/src/theory/theory.h
@@ -39,6 +39,7 @@
 #include "theory/assertion.h"
 #include "theory/care_graph.h"
 #include "theory/decision_manager.h"
+#include "theory/ee_setup_info.h"
 #include "theory/logic_info.h"
 #include "theory/output_channel.h"
 #include "theory/theory_id.h"
@@ -265,6 +266,30 @@ class Theory {
   bool isLegalElimination(TNode x, TNode val);
 
  public:
+  //--------------------------------- initialization
+  /**
+   * @return The theory rewriter associated with this theory. This is primarily
+   * called for the purposes of initializing the rewriter.
+   */
+  virtual TheoryRewriter* getTheoryRewriter() = 0;
+  /**
+   * !!!! TODO: use this method (https://github.com/orgs/CVC4/projects/39).
+   *
+   * Returns true if this theory needs an equality engine for checking
+   * satisfiability.
+   *
+   * If this method returns true, then the equality engine manager will
+   * initialize its equality engine field via setEqualityEngine above during
+   * TheoryEngine::finishInit, prior to calling finishInit for this theory.
+   *
+   * Additionally, if this method returns true, then this method is required to
+   * update the argument esi with instructions for initializing and setting up
+   * notifications from its equality engine, which is commonly done with
+   * a notifications class (eq::EqualityEngineNotify).
+   */
+  virtual bool needsEqualityEngine(EeSetupInfo& esi);
+  //--------------------------------- end initialization
+
   /**
    * Return the ID of the theory responsible for the given type.
    */
@@ -331,11 +356,6 @@ class Theory {
   virtual ~Theory();
 
   /**
-   * @return The theory rewriter associated with this theory.
-   */
-  virtual TheoryRewriter* getTheoryRewriter() = 0;
-
-  /**
    * Subclasses of Theory may add additional efforts.  DO NOT CHECK
    * equality with one of these values (e.g. if STANDARD xxx) but
    * rather use range checks (or use the helper functions below).