document finc2

Author: Dimosts

pycona/find_constraint/findc2.py

@@ -10,9 +10,8 @@
 
 class FindC2(FindCBase):
     """
-    This is the version of the FindC function that was presented in
-    Bessiere, Christian, et al., "Learning constraints through partial queries", AIJ 2023
-
+    Implementation of the FindC algorithm from Bessiere et al., "Learning constraints through partial queries" (AIJ 2023).
+    
     This function works also for non-normalised target networks!
     """
 
@@ -32,7 +31,8 @@ def findscope(self):
         """
         Get the findscope function to be used.
 
-        :return: The findscope function.
+        Returns:
+            callable: The function used to determine constraint scopes
         """
         return self._findscope
 
@@ -41,32 +41,39 @@ def findscope(self, findscope):
         """
         Set the findscope function to be used.
 
-        :param findscope: The findscope function.
+        Args:
+            findscope (callable): The function to be used for determining constraint scopes
         """
         self._findscope = findscope
 
     def run(self, scope):
         """
-        Run the FindC2 algorithm.
+        Execute the FindC2 algorithm to learn constraints within a given scope.
+
+        Args:
+            scope (list): Variables defining the scope in which to search for constraints
 
-        :param scope: The scope in which we search for a constraint.
-        :return: The constraint found.
+        Returns:
+            list: The constraint(s) found in the given scope.
+
+        Raises:
+            Exception: If the target constraint is not in the bias (search space).
         """
         assert self.ca is not None
 
         scope_values = [x.value() for x in scope]
 
-        # Initialize delta
+        # Initialize delta with constraints from bias that match the scope
         delta = get_con_subset(self.ca.instance.bias, scope)
         kappaD = [c for c in delta if check_value(c) is False]
+        # Join the constraints in delta with the violated constraints in kappaD
         delta = join_con_net(delta, kappaD)
 
-        # We need to take into account only the constraints in the scope we search on
+        # Get subset of learned constraints in the current scope
         sub_cl = get_con_subset(self.ca.instance.cl, scope)
 
         while True:
-
-            # Try to generate a counter example to reduce the candidates
+            # Generate a query to distinguish between candidate constraints
             if self.generate_findc_query(sub_cl, delta) is False:
 
                 # If no example could be generated
@@ -76,7 +83,7 @@ def run(self, scope):
 
                 restore_scope_values(scope, scope_values)
 
-                # Unravel delta nested ands
+                # Unravel nested AND constraints
                 delta_unraveled = []
                 for c in delta:
                     if c.name == 'and':
@@ -87,8 +94,7 @@ def run(self, scope):
                     else:
                         delta_unraveled.append([c])
 
-                # Return random c in delta otherwise (if more than one, they are equivalent w.r.t. C_l)
-                # Choose the constraint with the smallest number of conjunctions
+                # Return the smallest equivalent conjunction (if more than one, they are equivalent w.r.t. C_l)
                 delta_unraveled = sorted(delta_unraveled, key=lambda x: len(x))
                 return delta_unraveled[0]
 
@@ -103,10 +109,10 @@ def run(self, scope):
                 # delta <- joint(delta,K_{delta}(e))
 
                 kappaD = [c for c in delta if check_value(c) is False]
-
                 scope2 = self.ca.run_find_scope(list(scope)) 
 
                 if len(scope2) < len(scope):
+                    # Recursively learn constraint in sub-scope
                     c = self.run(scope2)
                     self.ca.add_to_cl(c)
                     sub_cl.append(c)
@@ -115,25 +121,30 @@ def run(self, scope):
 
     def generate_findc_query(self, L, delta):
         """
-        Changes directly the values of the variables
+        Generate a query that helps distinguish between candidate constraints.
 
-        :param L: learned network in the given scope
-        :param delta: candidate constraints in the given scope
-        :return: Boolean value representing a success or failure on the generation
-        """
+        Args:
+            L (list): Currently learned constraints in the scope
+            delta (list): Candidate constraints to distinguish between
+
+        Returns:
+            bool: True if a query was generated successfully, False otherwise
 
+        Note:
+            The method directly modifies variable values in the constraint network
+        """
         tmp = cp.Model(L)        
 
         satisfied_delta = sum([c for c in delta])  # get the amount of satisfied constraints from B
 
         scope = get_scope(delta[0])
+
         # at least 1 violated and at least 1 satisfied
         # we want this to assure that each answer of the user will reduce
         # the set of candidates
         tmp += satisfied_delta < len(delta)
         tmp += satisfied_delta > 0
 
-
         max_conj_size = get_max_conjunction_size(delta)
         delta_p = get_delta_p(delta)
 
@@ -143,23 +154,24 @@ def generate_findc_query(self, L, delta):
             kappa_delta_p = sum([c for c in delta_p[p]])
             s += kappa_delta_p < len(delta_p[p])
 
-
-            if not s.solve(): # if a solution is found
+            # Solve without objective for start
+            if not s.solve(): # if a solution is not found
                 continue
 
             # Next solve will change the values of the variables in lY
             # so we need to return them to the original ones to continue if we don't find a solution next
             values = [x.value() for x in scope]
 
-
             p_soft_con = (kappa_delta_p > 0)
 
-            # run with the objective
+            # So a solution was found, try to find a better one now
+            # set the objective
             s.maximize(p_soft_con)
 
-            # So a solution was found, try to find a better one now
+            # Give hint with previous solution to the solver
             s.solution_hint(scope, values)
 
+            # Solve with objective
             flag = s.solve(time_limit=self.time_limit, num_workers=8)
             if not flag:
                 restore_scope_values(scope, values)