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

Class BlackBoxSearch

java.lang.Object
org.maxicp.search.blackbox.BlackBoxSearch
public class BlackBoxSearch extends Object
Phase-based black-box search orchestrator for modeling-level CP problems.

A BlackBoxSearch executes a sequence of configured phases, each phase being a RunnableSearch with a relative time budget. The class stores and propagates incumbents (solution and objective value), handles early stopping criteria, and merges per-phase statuses into a global status.

Time-share semantics:

  • Each phase has a timeShare in (0,1].
  • Configured shares must sum to at most 1.0 (not necessarily exactly 1.0).
  • If shares sum to less than 1.0, the remaining budget is assigned to the last phase in the configured sequence when that phase is reached.
  • The actual per-phase budget is always capped by the currently remaining global time.

  • Constructor Details

    • BlackBoxSearch

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

    • BlackBoxSearch

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

      The variables are obtained from ModelDispatcher.getDecisionVariables(). This is convenient for LNS users who want to freeze only real decision variables and avoid freezing derived expressions.

    • BlackBoxSearch

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

    • BlackBoxSearch

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

    • BlackBoxSearch

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

  • Method Details

    • withVerbosity

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

    • addPhase

      public BlackBoxSearch addPhase(String name, RunnableSearch search, double timeShare, boolean requiresFeasible)
      Registers one executable phase in the black-box plan.
      Parameters:
      name - descriptive phase name used in logs and diagnostics
      search - runnable implementation executed for the phase
      timeShare - relative share of the global timeout allocated to this phase for non-last phases (must be in (0,1]; shares across phases must sum to at most 1.0)
      requiresFeasible - whether this phase can run only after an incumbent exists
      Returns:
      this search instance for fluent configuration

    • withDefaultPhasePlan

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

      Feasibility: initial exhaustive + restart phases.

      Optimization: initial exhaustive + restart + LNS + exhaustive phases.

    • 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.

      Shares do not need to sum to exactly 1.0; they must sum to at most 1.0. Any remaining fraction is effectively left to the last configured phase via remaining-time assignment.

    • withFeasibilityPlan

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

      Shares do not need to sum to exactly 1.0; they must sum to at most 1.0. Any remaining fraction is effectively left to the last configured phase via remaining-time assignment.

    • start

      public SearchStatus start(int timeLimitInSeconds)
      Executes the configured phase plan under a global timeout.

      Early stop conditions:

      Parameters:
      timeLimitInSeconds - global timeout in seconds
      Returns:
      merged global status across executed phases

    • bestSolution

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

    • 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()