Module org.maxicp
Package org.maxicp.search.blackbox

Class BlackBoxSearch

java.lang.Object
org.maxicp.search.blackbox.BlackBoxSearch
All Implemented Interfaces:
SearchMethod
public class BlackBoxSearch extends Object implements SearchMethod
Commercial-solver-style black-box search orchestrator for modeling-level CP and scheduling problems.

Implements SearchMethod so it can be used as a drop-in replacement for DFSearch inside model.runCP(cp -> ...) via cp.blackBoxSearch(), or directly on a ModelDispatcher via model.blackBoxSearch(), model.solve(...), and model.optimize(...).

Automatically discovers both integer/boolean variables (IntExpression) and scheduling interval variables (IntervalVar) from the model when not explicitly provided.

  • Constructor Details

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model, List<IntExpression> vars, Objective objective)
      Creates a black-box search on explicit integer decision variables with an objective.

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model, Objective objective)
      Creates a black-box search with automatic decision-variable and interval-variable inference.

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model, IntExpression[] vars, Objective objective)
      Creates a black-box search on an array of integer decision variables with an objective.

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model, IntExpression[] vars)
      Creates a black-box search on an array of integer decision variables without objective (feasibility).

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model, IntervalVar... intervals)
      Creates a black-box search on an array of scheduling interval variables.

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model, IntervalVar[][] intervals)
      Creates a black-box search on a 2D matrix of scheduling interval variables.

    • BlackBoxSearch

      public BlackBoxSearch(ModelDispatcher model)
      Creates a black-box search with automatic decision-variable and interval-variable inference.

  • Method Details

    • withVerbosity

      public BlackBoxSearch withVerbosity(BlackBoxSearch.Verbosity verbosity)
      Sets logging verbosity for this search.

    • onIncumbent

      public BlackBoxSearch onIncumbent(BiConsumer<List<Integer>,Integer> listener)
      Registers a callback invoked whenever a new feasible or improving incumbent is recorded.

    • onSolution

      public void onSolution(Consumer<SearchStatistics> listener)
      Description copied from interface: SearchMethod
      Adds a listener that is called on each solution.
      Specified by:
      onSolution in interface SearchMethod
      Parameters:
      listener - the closure to be called whenever a solution is found

    • onFailure

      public void onFailure(Consumer<SearchStatistics> listener)
      Description copied from interface: SearchMethod
      Adds a listener that is called whenever a failure occurs and the search backtracks. This happens when a InconsistencyException is thrown when executing the closure generated by the branching.
      Specified by:
      onFailure in interface SearchMethod
      Parameters:
      listener - the closure to be called whenever a failure occurs and the search need to backtrack

    • addPhase

      public BlackBoxSearch addPhase(String name, RunnableSearch search, double timeShare, boolean requiresFeasible)
      Registers one executable phase in the black-box plan.

    • withDefaultPhasePlan

      public BlackBoxSearch withDefaultPhasePlan()
      Builds the built-in default plan.

    • withOptimizationPlan

      public BlackBoxSearch withOptimizationPlan(BlackBoxSearch.RestartPhaseOptions restart, BlackBoxSearch.LnsPhaseOptions lns, BlackBoxSearch.ExhaustivePhaseOptions exhaustive, double initialExhaustiveShare, double restartShare, double lnsShare, double exhaustiveShare)
      Configures the optimization phase plan explicitly.

    • withFeasibilityPlan

      public BlackBoxSearch withFeasibilityPlan(BlackBoxSearch.RestartPhaseOptions restart, BlackBoxSearch.ExhaustivePhaseOptions exhaustive, double initialExhaustiveShare, double restartShare, double exhaustiveShare)
      Configures the feasibility phase plan explicitly.

    • start

      public SearchStatus start(int timeLimitInSeconds)
      Executes the configured phase plan under a global timeout.
      Parameters:
      timeLimitInSeconds - global timeout in seconds
      Returns:
      merged global status across executed phases

    • solve

      public SearchStatistics solve()
      Description copied from interface: SearchMethod
      Start the solving process
      Specified by:
      solve in interface SearchMethod
      Returns:
      an object with the statistics on the search

    • solve

      public SearchStatistics solve(int timeLimitInSeconds)
      Solves the feasibility model under a wall-clock timeout in seconds.
      Parameters:
      timeLimitInSeconds - timeout in seconds
      Returns:
      aggregated search statistics

    • solve

      public SearchStatistics solve(Predicate<SearchStatistics> limit)
      Description copied from interface: SearchMethod
      Start the solving process with a given predicate called at each node to stop the search when it becomes true.
      Specified by:
      solve in interface SearchMethod
      Parameters:
      limit - a predicate called at each node that stops the search when it becomes true
      Returns:
      an object with the statistics on the search

    • solveSubjectTo

      public SearchStatistics solveSubjectTo(Predicate<SearchStatistics> limit, Runnable subjectTo)
      Description copied from interface: SearchMethod
      Start the solving process with a given predicate called at each node to stop the search when it becomes true. The state manager saves the state before executing the closure and restores it after the search. Any InconsistencyException that may be throw when executing the closure is also catched.
      Specified by:
      solveSubjectTo in interface SearchMethod
      Parameters:
      limit - a predicate called at each node that stops the search when it becomes true
      subjectTo - the closure to execute prior to the search starts
      Returns:
      an object with the statistics on the search

    • optimize

      public SearchStatistics optimize(Objective obj)
      Specified by:
      optimize in interface SearchMethod

    • optimize

      public SearchStatistics optimize(Objective obj, int timeLimitInSeconds)
      Optimizes the given objective under a wall-clock timeout in seconds.
      Parameters:
      obj - symbolic objective to minimize or maximize
      timeLimitInSeconds - timeout in seconds
      Returns:
      aggregated search statistics

    • optimize

      public SearchStatistics optimize(Objective obj, Predicate<SearchStatistics> limit)
      Specified by:
      optimize in interface SearchMethod

    • optimizeSubjectTo

      public SearchStatistics optimizeSubjectTo(Objective objToTighten, Predicate<SearchStatistics> limit, Runnable subjectTo)
      Specified by:
      optimizeSubjectTo in interface SearchMethod

    • optimize

      public SearchStatistics optimize(Objective obj)
      Description copied from interface: SearchMethod
      Start the solving process with a given objective.
      Specified by:
      optimize in interface SearchMethod
      Parameters:
      obj - the objective to optimize that is tightened each time a new solution is found
      Returns:
      an object with the statistics on the search

    • optimize

      public SearchStatistics optimize(Objective obj, int timeLimitInSeconds)
      Optimizes the given low-level objective within the specified time limit (in seconds).

    • optimize

      public SearchStatistics optimize(Objective toTighten, Predicate<SearchStatistics> limit)
      Description copied from interface: SearchMethod
      Start the solving process with a given objective and with a given predicate called at each node to stop the search when it becomes true.
      Specified by:
      optimize in interface SearchMethod
      Parameters:
      toTighten - the objective to optimize that is tightened each time a new solution is found
      limit - a predicate called at each node that stops the search when it becomes true
      Returns:
      an object with the statistics on the search

    • optimizeSubjectTo

      public SearchStatistics optimizeSubjectTo(Objective objToTighten, Predicate<SearchStatistics> limit, Runnable subjectTo)
      Description copied from interface: SearchMethod
      Executes a closure prior to effectively starting a branch and bound depth first search with a given objective to optimize and a given predicate called at each node to stop the search when it becomes true. The state manager saves the state before executing the closure and restores it after the search. Any InconsistencyException that may be thrown when executing the closure is also catched.
      Specified by:
      optimizeSubjectTo in interface SearchMethod
      Parameters:
      objToTighten - the objective to optimize that is tightened each time a new solution is found
      limit - a predicate called at each node that stops the search when it becomes true
      subjectTo - the closure to execute prior to the search starts
      Returns:
      an object with the statistics on the search

    • status

      public SearchStatus status()
      Returns the overall status of the most recent search run.

    • bestSolution

      public Optional<List<Integer>> bestSolution()
      Returns the best incumbent solution found so far, if any.

    • bestIntervalSolution

      public Optional<List<BlackBoxSearch.IntervalSnapshot>> bestIntervalSolution()
      Returns the best incumbent interval snapshots found so far, if any.

    • bestValue

      public Optional<Integer> bestValue(IntExpression var)
      Returns the value of var in the best incumbent solution found so far, if available.

    • bestValues

      public Optional<List<Integer>> bestValues(IntExpression... targetVars)
      Returns the values of the given expressions in the best incumbent solution found so far.

    • bestVarValuesMap

      public Map<IntExpression,Integer> bestVarValuesMap()
      Returns an unmodifiable view of the recorded variable values in the best solution.

    • bestObjectiveValue

      public Optional<Integer> bestObjectiveValue()
      Returns the incumbent objective value, if any.

    • executedPhases

      public List<String> executedPhases()
      Returns phase names that were actually executed (in execution order).

    • updateObjective

      public void updateObjective(Integer objectiveValue)

    • updateSolution

      public void updateSolution(List<Integer> solution)

    • getRunnableSearches

      public List<RunnableSearch> getRunnableSearches()