Add (updated and general) solve_for functionality for arithmetic, add congruence_explain to API to retrieve explanation for why two terms are congruent Tweak handling of smt.qi.max_instantations

Add API solve_for(vars).
It takes a list of variables and returns a triangular solved form for the variables.
Currently for arithmetic. The solved form is a list with elements of the form (var, term, guard).
Variables solved in the tail of the list do not occur before in the list.
For example it can return a solution [(x, z, True), (y, x + z, True)] because first x was solved to be z,
then y was solved to be x + z which is the same as 2z.

Add congruent_explain that retuns an explanation for congruent terms.
Terms congruent in the final state after calling SimpleSolver().check() can be queried for
an explanation, i.e., a list of literals that collectively entail the equality under congruence closure.
The literals are asserted in the final state of search.

Adjust smt_context cancellation for the smt.qi.max_instantiations parameter.
It gets checked when qi-queue elements are consumed.
Prior it was checked on insertion time, which didn't allow for processing as many
instantations as there were in the queue. Moreover, it would not cancel the solver.
So it would keep adding instantations to the queue when it was full / depleted the
configuration limit.

src/solver/combined_solver.cpp

@@ -277,6 +277,7 @@ public:
 
     expr* congruence_next(expr* e) override { switch_inc_mode(); return m_solver2->congruence_next(e); }
     expr* congruence_root(expr* e) override { switch_inc_mode(); return m_solver2->congruence_root(e); }
+    expr_ref congruence_explain(expr* a, expr* b) override { switch_inc_mode(); return m_solver2->congruence_explain(a, b); }
 
 
     expr * get_assumption(unsigned idx) const override {

src/solver/simplifier_solver.cpp

@@ -365,6 +365,7 @@ public:
 
     expr* congruence_root(expr* e) override { return s->congruence_root(e); }
     expr* congruence_next(expr* e) override { return s->congruence_next(e); }
+    expr_ref congruence_explain(expr* a, expr* b) override { return s->congruence_explain(a, b); }
     std::ostream& display(std::ostream& out, unsigned n, expr* const* assumptions) const override {
         return s->display(out, n, assumptions);
     }

src/solver/slice_solver.cpp

@@ -393,6 +393,7 @@ public:
 
     expr* congruence_root(expr* e) override { return s->congruence_root(e); }
     expr* congruence_next(expr* e) override { return s->congruence_next(e); }
+    expr_ref congruence_explain(expr* a, expr* b) override { return s->congruence_explain(a, b); }
     std::ostream& display(std::ostream& out, unsigned n, expr* const* assumptions) const override {
         return s->display(out, n, assumptions);
     }

src/solver/solver.h

@@ -27,6 +27,7 @@ class solver;
 class model_converter;
 
 
+
 class solver_factory {
 public:
     virtual ~solver_factory() = default;
@@ -249,9 +250,17 @@ public:
     virtual expr* congruence_next(expr* e) = 0;
 
     /**
-       \brief try to solve for term e (when e is arithmetical).
+       \brief expose explanation for congruence.
     */
-    virtual bool solve_for(expr* e, expr_ref& term) { return false; }
+    virtual expr_ref congruence_explain(expr* a, expr* b) = 0;
+
+    struct solution {
+        expr* var;
+        expr_ref term;
+        expr_ref guard;
+    };
+
+    virtual void solve_for(vector<solution>& s) {}
 
     /**
        \brief Display the content of this solver.

src/solver/solver_pool.cpp

@@ -81,7 +81,7 @@ public:
     }
     void push_params() override {m_base->push_params();}
     void pop_params() override {m_base->pop_params();}
-
+    
     void collect_param_descrs(param_descrs & r) override { m_base->collect_param_descrs(r); }
     void collect_statistics(statistics & st) const override { m_base->collect_statistics(st); }
     unsigned get_num_assertions() const override { return m_base->get_num_assertions(); }
@@ -264,6 +264,7 @@ public:
 
     expr* congruence_next(expr* e) override { return e; }
     expr* congruence_root(expr* e) override { return e; }
+    expr_ref congruence_explain(expr* a, expr* b) override { return expr_ref(m.mk_eq(a, b), m); }
 
     ast_manager& get_manager() const override { return m_base->get_manager(); }
 

src/solver/tactic2solver.cpp

@@ -145,6 +145,7 @@ public:
 
     expr* congruence_next(expr* e) override { return e; }
     expr* congruence_root(expr* e) override { return e; }
+    expr_ref congruence_explain(expr* a, expr* b) override { return expr_ref(get_manager().mk_eq(a, b), get_manager()); }
 
     model_converter_ref get_model_converter() const override { return m_mc; }