org.optaplanner.core.api.score

## Interface Score<Score_ extends Score>

- Type Parameters:
    `Score_` - the actual score type to allow addition, subtraction and other arithmetic
  All Superinterfaces:
    Comparable<Score_>
  All Known Subinterfaces:
    FeasibilityScore<S>
  All Known Implementing Classes:
    AbstractBendableScore, AbstractScore, BendableBigDecimalScore, BendableLongScore, BendableScore, HardMediumSoftBigDecimalScore, HardMediumSoftLongScore, HardMediumSoftScore, HardSoftBigDecimalScore, HardSoftDoubleScore, HardSoftLongScore, HardSoftScore, SimpleBigDecimalScore, SimpleDoubleScore, SimpleLongScore, SimpleScore

      public interface Score<Score_ extends Score>
      extends Comparable<Score_>

  A Score is result of the score function (AKA fitness function) on a single possible solution.

  Implementations must be immutable.

  Implementations are allowed to optionally implement Pareto comparison and therefore slightly violate the transitive requirement of `Comparable.compareTo(Object)`.

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

  See Also:
    `AbstractScore`, `HardSoftScore`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Score_` | `add(Score_ addend)` Returns a Score whose value is (this + addend).
    `Score_` | `divide(double divisor)` Returns a Score whose value is (this / divisor).
    `int` | `getInitScore()` The init score is the negative of the number of uninitialized genuine planning variables.
    `boolean` | `isCompatibleArithmeticArgument(Score otherScore)`
    `boolean` | `isSolutionInitialized()` Checks if the `PlanningSolution` of this score was fully initialized when it was calculated.
    `Score_` | `multiply(double multiplicand)` Returns a Score whose value is (this * multiplicand).
    `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).
    `Score_` | `toInitializedScore()` For example `-7init/0hard/-8soft` returns `0hard/-8soft`.
    `Number[]` | `toLevelNumbers()` Returns an array of numbers representing the Score.
    `String` | `toShortString()` Like `Object.toString()`, but trims score levels which have a zero weight.
    `Score_` | `withInitScore(int newInitScore)` For example `0hard/-8soft` with `-7` returns `-7init/0hard/-8soft`.

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Method Detail

    - #### getInitScore

          int getInitScore()

      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

    - #### isSolutionInitialized

          boolean isSolutionInitialized()

      Checks if the `PlanningSolution` of this score was fully initialized when it was calculated.
      Returns:
        true if `getInitScore()` is 0

    - #### toInitializedScore

          Score_ toInitializedScore()

      For example `-7init/0hard/-8soft` returns `0hard/-8soft`.
      Returns:
        equal score except that `getInitScore()` is `0`.

    - #### 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 `getInitScore()` is set to `newInitScore`
      Throws:
        `IllegalStateException` - if the original `getInitScore()` is not 0

    - #### 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

          Score_ negate()

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

    - #### 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 `getInitScore()`. For example: `-3init/-0hard/-7soft` also returns `new int{-0, -7}`

      Returns:
        never null
      See Also:
        `ScoreDefinition.fromLevelNumbers(int, Number[])`

    - #### isCompatibleArithmeticArgument

          boolean isCompatibleArithmeticArgument(Score otherScore)

      Parameters:
        `otherScore` - never null
      Returns:
        true if the otherScore is accepted as a parameter of `add(Score)`, `subtract(Score)` and `Comparable.compareTo(Object)`.

    - #### 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

Copyright © 2006–2020 JBoss by Red Hat. All rights reserved.