Package org.optaplanner.core.impl.solver.termination

## Interface Termination

- All Superinterfaces:
    `EventListener`, `PhaseLifecycleListener`, `SolverLifecycleListener`
  All Known Implementing Classes:
    `AbstractCompositeTermination`, `AbstractTermination`, `AndCompositeTermination`, `BasicPlumbingTermination`, `BestScoreFeasibleTermination`, `BestScoreTermination`, `ChildThreadPlumbingTermination`, `OrCompositeTermination`, `PhaseToSolverTerminationBridge`, `ScoreCalculationCountTermination`, `StepCountTermination`, `TimeMillisSpentTermination`, `UnimprovedStepCountTermination`, `UnimprovedTimeMillisSpentScoreDifferenceThresholdTermination`, `UnimprovedTimeMillisSpentTermination`

      public interface Termination
      extends PhaseLifecycleListener

  A Termination determines when a `Solver` or a `Phase` should stop.

  An implementation must extend `AbstractTermination` to ensure backwards compatibility in future versions.

  See Also:
    `AbstractTermination`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `double` | `calculatePhaseTimeGradient​(AbstractPhaseScope phaseScope)` | See `calculateSolverTimeGradient(DefaultSolverScope)`.
    `double` | `calculateSolverTimeGradient​(DefaultSolverScope solverScope)` | A timeGradient is a relative estimate of how long the search will continue.
    `Termination` | `createChildThreadTermination​(DefaultSolverScope solverScope, ChildThreadType childThreadType)` | Create a `Termination` for a child `Thread` of the `Solver`.
    `boolean` | `isPhaseTerminated​(AbstractPhaseScope phaseScope)` | Called by the `Phase` after every step and every move to determine if the search should stop.
    `boolean` | `isSolverTerminated​(DefaultSolverScope solverScope)` | Called by the `Solver` after every phase to determine if the search should stop.

    - ### Methods inherited from interface org.optaplanner.core.impl.phase.event.PhaseLifecycleListener

      `phaseEnded, phaseStarted, stepEnded, stepStarted`

    - ### Methods inherited from interface org.optaplanner.core.impl.solver.event.SolverLifecycleListener

      `solvingEnded, solvingStarted`

- - ### Method Detail

    - #### isSolverTerminated

          boolean isSolverTerminated​(DefaultSolverScope solverScope)

      Called by the `Solver` after every phase to determine if the search should stop.
      Parameters:
        `solverScope` - never null
      Returns:
        true if the search should terminate.

    - #### isPhaseTerminated

          boolean isPhaseTerminated​(AbstractPhaseScope phaseScope)

      Called by the `Phase` after every step and every move to determine if the search should stop.
      Parameters:
        `phaseScope` - never null
      Returns:
        true if the search should terminate.

    - #### calculateSolverTimeGradient

          double calculateSolverTimeGradient​(DefaultSolverScope solverScope)

      A timeGradient is a relative estimate of how long the search will continue.

      Clients that use a timeGradient should cache it at the start of a single step because some implementations are not time-stable.

      If a timeGradient can not be calculated, it should return -1.0. Several implementations (such a `SimulatedAnnealingAcceptor`) require a correctly implemented timeGradient.

      A Termination's timeGradient can be requested after they are terminated, so implementations should be careful not to return a timeGradient above 1.0.

      Parameters:
        `solverScope` - never null
      Returns:
        timeGradient t for which `0.0 <= t <= 1.0 or -1.0` when it is not supported. At the start of a solver t is 0.0 and at the end t would be 1.0.

    - #### calculatePhaseTimeGradient

          double calculatePhaseTimeGradient​(AbstractPhaseScope phaseScope)

      See `calculateSolverTimeGradient(DefaultSolverScope)`.
      Parameters:
        `phaseScope` - never null
      Returns:
        timeGradient t for which `0.0 <= t <= 1.0 or -1.0` when it is not supported. At the start of a phase t is 0.0 and at the end t would be 1.0.

    - #### createChildThreadTermination

          Termination createChildThreadTermination​(DefaultSolverScope solverScope,
                                                   ChildThreadType childThreadType)

      Create a `Termination` for a child `Thread` of the `Solver`.
      Parameters:
        `solverScope` - never null
        `childThreadType` - never null
      Returns:
        not null
      Throws:
        `UnsupportedOperationException` - if not supported by this termination