org.optaplanner.core.api.score

Interface Score<S extends Score>

Type Parameters:

S - the actual score type

All Superinterfaces:

Comparable<S>

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<S extends Score>
extends Comparable<S>

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

Modifier and Type	Method and Description
S	add(S augment) Returns a Score whose value is (this + augment).
S	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.
S	multiply(double multiplicand) Returns a Score whose value is (this * multiplicand).
S	negate() Returns a Score whose value is (- this).
S	power(double exponent) Returns a Score whose value is (this ^ exponent).
S	subtract(S subtrahend) Returns a Score whose value is (this - subtrahend).
S	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.
S	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

S toInitializedScore()

For example -7init/0hard/-8soft returns 0hard/-8soft.

Returns:

equal score except that getInitScore() is 0.

withInitScore

S 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

S add(S augment)

Returns a Score whose value is (this + augment).

Parameters:

augment - value to be added to this Score

Returns:

this + augment

subtract

S subtract(S 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

S 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

S 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

S 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

S 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