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/api/python/z3/z3.py

@@ -7336,26 +7336,44 @@ class Solver(Z3PPObject):
         return self.cube_vs
 
     def root(self, t):
-        t = _py2expr(t, self.ctx)
         """Retrieve congruence closure root of the term t relative to the current search state
         The function primarily works for SimpleSolver. Terms and variables that are
         eliminated during pre-processing are not visible to the congruence closure.
         """
+        t = _py2expr(t, self.ctx)
         return _to_expr_ref(Z3_solver_congruence_root(self.ctx.ref(), self.solver, t.ast), self.ctx)
 
     def next(self, t):
-        t = _py2expr(t, self.ctx)
         """Retrieve congruence closure sibling of the term t relative to the current search state
         The function primarily works for SimpleSolver. Terms and variables that are
         eliminated during pre-processing are not visible to the congruence closure.
         """
+        t = _py2expr(t, self.ctx)
         return _to_expr_ref(Z3_solver_congruence_next(self.ctx.ref(), self.solver, t.ast), self.ctx)
 
-    def solve_for(self, t):
-        t = _py2expr(t, self.ctx)
+    def explain_congruent(self, a, b):
+        """Explain congruence of a and b relative to the current search state"""
+        a = _py2expr(a, self.ctx)
+        b = _py2expr(b, self.ctx)
+        return _to_expr_ref(Z3_solver_congruence_explain(self.ctx.ref(), self.solver, a.ast, b.ast), self.ctx)
+
+    def solve_for1(self, t):
         """Retrieve a solution for t relative to linear equations maintained in the current state.
         The function primarily works for SimpleSolver and when there is a solution using linear arithmetic."""
-        return _to_expr_ref(Z3_solver_solve_for(self.ctx.ref(), self.solver, t.ast), self.ctx)
+        t = _py2expr(t, self.ctx)
+        return _to_expr_ref(Z3_solver_solve_for1(self.ctx.ref(), self.solver, t.ast), self.ctx)
+
+    def solve_for(self, ts):
+        """Retrieve a solution for t relative to linear equations maintained in the current state."""
+        vars = AstVector(ctx=self.ctx);
+        terms = AstVector(ctx=self.ctx);
+        guards = AstVector(ctx=self.ctx);
+        for t in ts:
+            t = _py2expr(t, self.ctx)                
+            vars.push(t)
+        Z3_solver_solve_for(self.ctx.ref(), self.solver, vars.vector, terms.vector, guards.vector)
+        return [(vars[i], terms[i], guards[i]) for i in range(len(vars))]
+
 
     def proof(self):
         """Return a proof for the last `check()`. Proof construction must be enabled."""