Module org.chocosolver
Package org.chocosolver.solver.search

Interface IResolutionHelper

  • All Superinterfaces:
    ISelf<Solver>
    All Known Subinterfaces:
    ISolver
    All Known Implementing Classes:
    Solver
    public interface IResolutionHelper
extends ISelf<Solver>
    Interface to define most commonly used resolution procedures.

    Project: choco-solver.

    Since:
    25/04/2016.
    Author:
    Jean-Guillaum Fages, Charles Prud'homme, Guillaume Lelouet

    • Method Detail

      • findSolution

        default Solution findSolution​(Criterion... stop)
        Attempts to find a solution of the declared satisfaction problem.
        • If the method returns null:
          • either a stop criterion (e.g., a time limit) stops the search before a solution has been found,
          • or no solution exists for the problem (i.e., over-constrained).
        • if the method returns a Solution:
          • a solution has been found. This method can be called anew to look for the next solution, if any.

        If a solution has been found, since the search process stops on that solution, variables' value can be read, e.g., intvar.getValue() or the solution can be recorded: 

            
 	Solution s = new Solution(model);
 	s.record();

        Basically, this method runs the following instructions: 

             
     if(ref().solve()) {
          return new Solution(ref()).record();
     }else{
          return null;
       }
        Note that all variables will be recorded Note that it clears the current objective function, if any
        Parameters:
        stop - optional criterion to stop the search before finding a solution
        Returns:
        a Solution if and only if a solution has been found, null otherwise.

      • findAllSolutions

        default List<Solution> findAllSolutions​(Criterion... stop)
        Attempts to find all solutions of the declared satisfaction problem.
        • If the method returns an empty list:
          • either a stop criterion (e.g., a time limit) stops the search before any solution has been found,
          • or no solution exists for the problem (i.e., over-constrained).
        • if the method returns a list with at least one element in it:
          • either the resolution stops eagerly du to a stop criterion before finding all solutions,
          • or all solutions have been found.

        This method run the following instructions: 

             
     List<Solution> solutions = new ArrayList<>();
     while (model.getSolver().solve()){
          solutions.add(new Solution(model).record());
     }
     return solutions;
        Note that all variables will be recorded Note that it clears the current objective function, if any
        Parameters:
        stop - optional criterion to stop the search before finding all solutions
        Returns:
        a list that contained the found solutions.

      • streamSolutions

        default Stream<Solution> streamSolutions​(Criterion... stop)
        Attempts to find all solutions of the declared problem.
        • If the method returns an empty list:
          • either a stop criterion (e.g., a time limit) stops the search before any solution has been found,
          • or no solution exists for the problem (i.e., over-constrained).
        • if the method returns a list with at least one element in it:
          • either the resolution stops eagerly du to a stop criterion before finding all solutions,
          • or all solutions have been found.

        Basically, this method runs the following instructions: 

         
 	List<Solution> solutions = new ArrayList<>();
 	while (model.getSolver().solve()) {
 		solutions.add(new Solution(model).record());
    }
 	return solutions;
        Note that all variables will be recorded
        Parameters:
        stop - optional criterion to stop the search before finding all/best solution
        Returns:
        a list that contained the found solutions.

      • findOptimalSolution

        default Solution findOptimalSolution​(IntVar objective,
                                     boolean maximize,
                                     Criterion... stop)
        Attempt to find the solution that optimizes the mono-objective problem defined by a unique objective variable and an optimization criteria.
        • If this method returns null:
          • either the resolution stops eagerly du to a stop criterion (e.g., a time limit) and no solution has been found so far,
          • or the problem cannot be satisfied (i.e., over constrained).
        • If this method returns a Solution:
          • either the resolution stops eagerly du to a stop criterion and the solution is the best found so far but not necessarily the optimal one,
          • or it is the optimal one.

        Basically, this method runs the following instructions: 

             
     model.setObjective(maximize, objective);
     Solution s = new Solution(model);
     while (model.getSolver().solve()) {
          s.record();
     }
     return model.getSolver().isFeasible() == ESat.TRUE ? s : null;
        Note that all variables will be recorded
        Parameters:
        objective - integer variable to optimize
        maximize - set to true to solve a maximization problem, set to false to solve a minimization problem.
        stop - optional criterion to stop the search before finding all/best solution
        Returns:
        • null if the problem has no solution or a stop criterion stops the search before finding a first solution
        • a Solution if at least one solution has been found. The solution is proven to be optimal if no stop criterion stops the search.

      • findAllOptimalSolutions

        default List<Solution> findAllOptimalSolutions​(IntVar objective,
                                               boolean maximize,
                                               Criterion... stop)
        Attempt to find the solution that optimizes the mono-objective problem defined by a unique objective variable and an optimization criteria, then finds and stores all optimal solution. Searching for all optimal solutions is only triggered if the first search is complete. This method works as follow:
        1. It finds and prove the optimum
        2. It resets the search and enumerates all solutions of optimal cost
        Note that the returned list can be empty.
        • If the method returns an empty list:
          • either a stop criterion (e.g., a time limit) stops the search before any solution has been found,
          • or no solution exists for the problem (i.e., over-constrained).
        • if the method returns a list with at least one element in it:
          • either the resolution stops eagerly du to a stop criterion before finding all solutions,
          • or all optimal solutions have been found.
        This method runs the following instructions: 
             
     ref().findOptimalSolution(objective, maximize, stop);
     if (!ref().isStopCriterionMet()  &&
          model.getSolver().getMeasures().getSolutionCount() > 0) {
         int opt = _model.getSolver().getObjectiveManager().getBestSolutionValue().intValue();
         model.getSolver().reset();
         model.clearObjective();
         model.arithm(objective, "=", opt).post();
         return findAllSolutions();
     } else {
          return Collections.emptyList();
     }
        Note that all variables will be recorded
        Parameters:
        objective - the variable to optimize
        maximize - set to true to solve a maximization problem, set to false to solve a minimization problem.
        stop - optional criterion to stop the search before finding all/best solution
        Returns:
        a list that contained the solutions found.

      • streamOptimalSolutions

        default Stream<Solution> streamOptimalSolutions​(IntVar objective,
                                                boolean maximize,
                                                Criterion... stop)
        Attempt to find the solution that optimizes the mono-objective problem defined by a unique objective variable and an optimization criteria, then finds and stores all optimal solution. This method works as follow:
        1. It finds and prove the optimum
        2. It resets the search and enumerates all solutions of optimal cost
        Note that the returned list can be empty.
        • If the method returns an empty list:
          • either a stop criterion (e.g., a time limit) stops the search before any solution has been found,
          • or no solution exists for the problem (i.e., over-constrained).
        • if the method returns a list with at least one element in it:
          • either the resolution stops eagerly du to a stop criterion before finding all solutions,
          • or all optimal solutions have been found.

        Basically, this method runs the following instructions: 

             
     ref().findOptimalSolution(objective, maximize);
     if (model.getSolver().getMeasures().getSolutionCount() > 0) {
         int opt = _model.getSolver().getObjectiveManager().getBestSolutionValue().intValue();
         model.getSolver().reset();
         model.clearObjective();
         model.arithm(objective, "=", opt).post();
         return findAllSolutions();
     } else {
          return Collections.emptyList();
     }
        Note that all variables will be recorded
        Parameters:
        objective - the variable to optimize
        maximize - set to true to solve a maximization problem, set to false to solve a minimization problem.
        stop - optional criterion to stop the search before finding all/best solution
        Returns:
        a list that contained the solutions found.

      • findParetoFront

        default List<Solution> findParetoFront​(IntVar[] objectives,
                                       boolean maximize,
                                       Criterion... stop)
        Attempts optimize the value of the objectives variable w.r.t. to an optimization criteria. Finds and stores all optimal solution. Note that the returned list can be empty.
        • If the method returns an empty list:
          • either a stop criterion (e.g., a time limit) stops the search before any solution has been found,
          • or no solution exists for the problem (i.e., over-constrained).
        • if the method returns a list with at least one element in it:
          • either the resolution stops eagerly du to a stop criterion before finding all solutions,
          • or all optimal solutions have been found.
        Basically, this method runs the following instructions: 

         
 ParetoOptimizer pareto = new ParetoOptimizer(maximize, objectives);
 	while (ref().solve()) {
 		pareto.onSolution();
 	}
 	return pareto.getParetoFront();
        Note that all variables will be recorded
        Parameters:
        objectives - the array of variables to optimize
        maximize - set to true to solve a maximization problem, set to false to solve a minimization problem.
        stop - optional criterions to stop the search before finding all/best solution
        Returns:
        a list that contained the solutions found.

      • findLexOptimalSolution

        default Solution findLexOptimalSolution​(IntVar[] objectives,
                                        boolean maximize,
                                        Criterion... stop)
        Attempts optimize the value of the objectives variable w.r.t. to an optimization criteria. Finds and stores the optimal solution, if any. Moreover, the objective variables are ordered wrt their significance. The first objective variable is more significant or equally significant to the second one, which in turn is more significant or equally significant to the third one, etc. On an optimal solution of a maximization problem, the first variable is maximized, then the second one is maximized, etc. Note that if a stop criteria stops the search eagerly, no optimal solution may have been found. In that case, the best solution, if at least one has been found, is returned. Note that all variables will be recorded
        Parameters:
        objectives - the list of objectives to find the optimal. A solution o1..on is optimal if lexicographically better than any other correct solution s1..sn
        maximize - to maximize the objective, false to minimize.
        stop - stop criterion are added before search and removed after search.
        Returns:
        A solution with the optimal objectives value, null if no solution exists or search was stopped before a solution could be found. If null, check if a criterion was met to find out was caused the null.

      • eachSolutionWithMeasure

        default void eachSolutionWithMeasure​(BiConsumer<Solution,​IMeasures> cons,
                                     Criterion... stop)
        Explore the model, calling a BiConsumer for each Solution with its corresponding IMeasures.

        The Solution and the IMeasures provided by the Biconsumer are always the same reference, consider either extracting values from them or copy them. See IMeasures and Solution.copySolution()

        The consumer and the criterion should not be linked ; instead use ACounter sub-classes.

        Note that all variables will be recorded
        Parameters:
        cons - the consumer of solution and measure couples
        stop - optional criterions to stop the search before finding all/best solution