org.hd.d.pg2k.ai.scorer
Interface ScorerIF

All Known Implementing Classes:

AbstractImgScorer, AbstractNonParamScorer, AbstractScorer, FixedScore, LocalSampler, MaxScore, MinScore, NoConfidence, RandomPositiveScore, RandomScore, SimpleExposure, ZeroScore

public interface ScorerIF

Base interface to compute the score and confidence for an exhibit. All methods in this interface are guaranteed to be "safe" insofaras they will complete in "reasonable" time with reasonable heap memory (and other resource, eg stack) and without doing anything that wouldn't be allowed in a minimal Applet/JWS sandbox.

All classes implementing this interface should be completely thread-safe in their implementation of the computeScoreAndConfidence() method, and preferrably purely functional (no visible side-effects), with as many concurrent threads as required safely doing separate computations in any one instance.

Classes implementing this interface should, where possible, do their calculations using integer arithmetic, since FPUs to support float/double calaculations may be a scarce resource on newer highly-threaded CPUs such as Sun's Niagara.

computeScoreAndConfidence

ScoreAndConf computeScoreAndConfidence(SimpleExhibitPipelineIF dataSource,
                                       java.lang.String exhibitName)
                                       throws java.io.IOException

Compute score [-1,+1] and confidence[0,+1] for given exhibit; never null.

Parameters:

dataSource - souce of exhibit data and metadata; never null

exhibitName - name of exhibit; must be syntactically valid and not null

Throws:

java.io.IOException - in case of difficulty fetching the exhibit details/data or in computing the result

getBaseName

java.lang.String getBaseName()

Get (base) name of this Scorer (excluding any parameters); never null. Pure alphanumeric, essentially the same rules as for a Java Class identifier (but with '$' and '_' and '.' excluded), ie [a-zA-Z][a-zA-Z0-9]*.

getNameAndParameters

java.lang.String getNameAndParameters()

Get name of this Scorer suffixed with any parameters; never null. If there are any parameters then they appended with the form (:name=value)*.

getPerturbedDefsAndValues

java.util.List<ScorerParam> getPerturbedDefsAndValues()

Computes randomly-perturbed parameters (if any); never null. This returns with zero or more of any parameters of the current Scorer usually altered by a small amount and guaranteed to be valid (in range).

The net effect is that most changes should be small and verging on insignificant, but some changes should be large enough to help escape from local minima/maxima.

createPerturbedVariant

ScorerIF createPerturbedVariant()

Create perturbed (gently mutated) variant.

getParameterDefsAndValues

java.util.List<ScorerParam> getParameterDefsAndValues()

Get (immutable) canonical-order parameter definitions and current values for this Scorer; never null.

createVariant

ScorerIF createVariant(java.lang.String nameAndParameters)
                       throws java.lang.IllegalArgumentException

Create variant of same base Scorer with (name and) parameters String; never null. Most Scorers will provide a public constructor taking a String argument with the same effect, but this allows us to enforce the requirement in the interface (at the low cost of retaining and starting from something like the no-arg instance).

May be able to share some (immutable) state with the original instance, and the value returned is immutable and may not be new.

Throws:

java.lang.IllegalArgumentException - for unparsable or inappropriate input

createVariant

ScorerIF createVariant(java.lang.String baseName,
                       java.util.List<ScorerParam> parameters)
                       throws java.lang.IllegalArgumentException

Create variant of same base Scorer with base name and parameters; never null. Most Scorers will provide a public constructor taking a String argument with the same effect, but this allows us to enforce the requirement in the interface (at the low cost of retaining and starting from something like the no-arg instance).

May be able to share some (immutable) state with the original instance, and the value returned is immutable and may not be new.

Throws:

java.lang.IllegalArgumentException - for unparsable or inappropriate input