Package ai.timefold.solver.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
@NullMarked 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. Implementations must be immutable, preferably a Java record or even a primitive record, if the target JDK permits that.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Score_
    abs()
    Returns a Score whose value is the absolute value of the score, i.e.
    Score_
    add(Score_ addend)
    Returns a Score whose value is (this + addend).
    Score_
    divide(double divisor)
    Returns a Score whose value is (this / divisor).
    default int
    getInitScore()
    Deprecated, for removal: This API element is subject to removal in a future version.
    No point in using this method anymore.
    default int
    initScore()
    Deprecated, for removal: This API element is subject to removal in a future version.
    No point in using this method anymore.
    boolean
    isFeasible()
    A PlanningSolution is feasible if it has no broken hard constraints.
    default boolean
    isSolutionInitialized()
    Deprecated, for removal: This API element is subject to removal in a future version.
    No point in using this method anymore.
    default boolean
    isZero()
     
    Score_
    multiply(double multiplicand)
    Returns a Score whose value is (this * multiplicand).
    default Score_
    negate()
    Returns a Score whose value is (- this).
    Score_
    power(double exponent)
    Returns a Score whose value is (this ^ exponent).
    Score_
    subtract(Score_ subtrahend)
    Returns a Score whose value is (this - subtrahend).
    default double[]
    toLevelDoubles()
    As defined by toLevelNumbers(), only returns double[] instead of Number[].
    Number[]
    toLevelNumbers()
    Returns an array of numbers representing the Score.
    String
    toShortString()
    Like Object.toString(), but trims score levels which have a zero weight.
    default Score_
    withInitScore(int newInitScore)
    Deprecated, for removal: This API element is subject to removal in a future version.
    No point in using this method anymore.
    Score_
    zero()
    Returns a Score, all levels of which are zero.

    Methods inherited from interface java.lang.Comparable

    compareTo

  • Method Details

    • initScore

      @Deprecated(forRemoval=true, since="1.22.0") default int initScore()
      Deprecated, for removal: This API element is subject to removal in a future version.
      No point in using this method anymore.
      Returns:
      Always zero.

    • getInitScore

      @Deprecated(forRemoval=true) default int getInitScore()
      Deprecated, for removal: This API element is subject to removal in a future version.
      No point in using this method anymore.
      Returns:
      Always zero.

    • withInitScore

      @Deprecated(forRemoval=true, since="1.22.0") default Score_ withInitScore(int newInitScore)
      Deprecated, for removal: This API element is subject to removal in a future version.
      No point in using this method anymore.
      Returns:
      this, init score always zero.

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

    • zero

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

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

    • toLevelDoubles

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

    • isSolutionInitialized

      @Deprecated(forRemoval=true, since="1.22.0") default boolean isSolutionInitialized()
      Deprecated, for removal: This API element is subject to removal in a future version.
      No point in using this method anymore.
      Returns:
      always true

    • isFeasible

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

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