Package org.optaplanner.core.api.score

Interface Score<Score_ extends Score<Score_>>

Type Parameters:
Score_ - the actual score type to allow addition, subtraction and other arithmetic
All Superinterfaces:
Comparable<Score_>, Serializable
All Known Subinterfaces:
IBendableScore<Score_>
All Known Implementing Classes:
AbstractBendableScore, AbstractScore, BendableBigDecimalScore, BendableLongScore, BendableScore, HardMediumSoftBigDecimalScore, HardMediumSoftLongScore, HardMediumSoftScore, HardSoftBigDecimalScore, HardSoftLongScore, HardSoftScore, SimpleBigDecimalScore, SimpleLongScore, SimpleScore
public interface Score<Score_ extends Score<Score_>> extends Comparable<Score_>, Serializable
A Score is result of the score function (AKA fitness function) on a single possible solution.
See Also:

  • Method Details

    • initScore

      default int initScore()
      The init score is the negative of the number of uninitialized genuine planning variables. If it's 0 (which it usually is), the PlanningSolution is fully initialized and the score's Object.toString() does not mention it.

      During Comparable.compareTo(Object), it's even more important than the hard score: if you don't want this behaviour, read about overconstrained planning in the reference manual.

      Returns:
      higher is better, always negative (except in statistical calculations), 0 if all planning variables are initialized

    • getInitScore

      @Deprecated(forRemoval=true) default int getInitScore()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use initScore() instead.
      As defined by initScore().

    • withInitScore

      Score_ withInitScore(int newInitScore)
      For example 0hard/-8soft with -7 returns -7init/0hard/-8soft.
      Parameters:
      newInitScore - always negative (except in statistical calculations), 0 if all planning variables are initialized
      Returns:
      equals score except that initScore() is set to newInitScore

    • add

      Score_ add(Score_ addend)
      Returns a Score whose value is (this + addend).
      Parameters:
      addend - value to be added to this Score
      Returns:
      this + addend

    • subtract

      Score_ subtract(Score_ subtrahend)
      Returns a Score whose value is (this - subtrahend).
      Parameters:
      subtrahend - value to be subtracted from this Score
      Returns:
      this - subtrahend, rounded as necessary

    • multiply

      Score_ multiply(double multiplicand)
      Returns a Score whose value is (this * multiplicand). When rounding is needed, it should be floored (as defined by Math.floor(double)).

      If the implementation has a scale/precision, then the unspecified scale/precision of the double multiplicand should have no impact on the returned scale/precision.

      Parameters:
      multiplicand - value to be multiplied by this Score.
      Returns:
      this * multiplicand

    • divide

      Score_ divide(double divisor)
      Returns a Score whose value is (this / divisor). When rounding is needed, it should be floored (as defined by Math.floor(double)).

      If the implementation has a scale/precision, then the unspecified scale/precision of the double divisor should have no impact on the returned scale/precision.

      Parameters:
      divisor - value by which this Score is to be divided
      Returns:
      this / divisor

    • power

      Score_ power(double exponent)
      Returns a Score whose value is (this ^ exponent). When rounding is needed, it should be floored (as defined by Math.floor(double)).

      If the implementation has a scale/precision, then the unspecified scale/precision of the double exponent should have no impact on the returned scale/precision.

      Parameters:
      exponent - value by which this Score is to be powered
      Returns:
      this ^ exponent

    • negate

      default Score_ negate()
      Returns a Score whose value is (- this).
      Returns:
      - this

    • abs

      Score_ abs()
      Returns a Score whose value is the absolute value of the score, i.e. |this|.
      Returns:
      never null

    • zero

      Score_ zero()
      Returns a Score, all levels of which are zero.
      Returns:
      never null

    • isZero

      default boolean isZero()
      Returns:
      true when this is equal to zero().

    • toLevelNumbers

      Number[] toLevelNumbers()
      Returns an array of numbers representing the Score. Each number represents 1 score level. A greater score level uses a lower array index than a lesser score level.

      When rounding is needed, each rounding should be floored (as defined by Math.floor(double)). The length of the returned array must be stable for a specific Score implementation.

      For example: -0hard/-7soft returns new int{-0, -7}

      The level numbers do not contain the initScore(). For example: -3init/-0hard/-7soft also returns new int{-0, -7}

      Returns:
      never null

    • toLevelDoubles

      default double[] toLevelDoubles()
      As defined by toLevelNumbers(), only returns double[] instead of Number[].
      Returns:
      never null

    • isSolutionInitialized

      default boolean isSolutionInitialized()
      Checks if the PlanningSolution of this score was fully initialized when it was calculated.
      Returns:
      true if initScore() is 0

    • isFeasible

      boolean isFeasible()
      A PlanningSolution is feasible if it has no broken hard constraints and isSolutionInitialized() is true. Simple scores (SimpleScore, SimpleLongScore, SimpleBigDecimalScore) are always feasible, if their initScore() is 0.
      Returns:
      true if the hard score is 0 or higher and the initScore() is 0.

    • toShortString

      String toShortString()
      Like Object.toString(), but trims score levels which have a zero weight. For example 0hard/-258soft returns -258soft.

      Do not use this format to persist information as text, use Object.toString() instead, so it can be parsed reliably.

      Returns:
      never null