Package ghidra.features.bsim.query.client

# Class ExecutableScorerSingle

java.lang.Object
ghidra.features.bsim.query.client.ExecutableScorer
ghidra.features.bsim.query.client.ExecutableScorerSingle

public class ExecutableScorerSingle extends ExecutableScorer
ExecutableComparison scorer to use when we are comparing exactly one executable against a set of other executables (one to many). We override the `ExecutableScorer` (compare many to many) so that it effectively accesses only a single row of the scoring matrix to get the "one to many" behavior we want. The getNormalizedScore() methods on the base class require that executable self-scores, other than the singled-out executable's self-score, be cached in some way. Thus this scorer needs a `ScoreCaching` class.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class ghidra.features.bsim.query.client.ExecutableScorer

  `ExecutableScorer.FunctionPair`

- ## Field Summary

  ### Fields inherited from class ghidra.features.bsim.query.client.ExecutableScorer

  `executableSet, index2ExeMap, sigThreshold, simThreshold, singleExe, singleExeXref`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExecutableScorerSingle(ScoreCaching cache)`
  Construct the scorer.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `checkPreliminaryPairThreshold(int hitcount, int pairThreshold)`
  Make check if we are going to have too many pairs.
  `void`
  `commitSelfScore()`
  Commit the singled out executables self-significance score to permanent storage
  `protected void`
  `commitSelfScore(String md5, float selfScore)`
  Commit a self-significance score for a specific executable to permanent storage
  `int`
  `countSelfScores()`
  `float`
  `getScore(int a)`
  Get score of executable (as compared to our singled out executable)
  `float`
  `getScore(int a, int b)`
  Return the similarity score between two executables
  `float`
  `getSelfScore(int a)`
  Retrieve the similarity score of an executable with itself
  `float`
  `getSingularSelfScore()`
  `protected void`
  `initializeScores()`
  Initialize the scoring matrix with zero.
  `protected List<ExecutableScorer.FunctionPair>`
  `pairFunctions(LSHVectorFactory vectorFactory, List<DescriptionManager> vec2func, List<VectorResult> vectors, int hitcount, int pairThreshold)`
  Generate all pairs of functions for any function associated with a list of vectors For each pair of functions generate the FunctionPair object with corresponding similarity and significance.
  `void`
  `prefetchSelfScores(List<ExecutableRecord> missing)`
  Pre-load self-scores of the registered executables.
  `void`
  `resetStorage(double simThresh, double sigThresh)`
  Clear any persistent storage for self-significance scores, and establish new thresholds
  `protected void`
  `scorePair(ExecutableScorer.FunctionPair pair)`
  Given a pair of score contributing functions that have been fully filtered, add the score into the matrix
  `void`
  `setSingleExecutable(String md5)`
  Set a single executable as focus to enable the single parameter getScore(int)

  ### Methods inherited from class ghidra.features.bsim.query.client.ExecutableScorer

  `addExecutable, getExecutable, getExecutable, getNormalizedScore, getNormalizedScore, getSigThreshold, getSimThreshold, getSingularExecutable, labelAndFilter, numExecutables, populateExecutableIndex, scoreCluster, transferSettings`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ExecutableScorerSingle

    public ExecutableScorerSingle(ScoreCaching cache) throws LSHException
    Construct the scorer. If normalized scores are required, a self-score cacher must be provided.
    Parameters:
      `cache` - is the self-score cacher or null
    Throws:
      `LSHException` - for problems initializing the cache

- ## Method Details

  - ### setSingleExecutable

    public void setSingleExecutable(String md5) throws LSHException
    Description copied from class: `ExecutableScorer`
    Set a single executable as focus to enable the single parameter getScore(int)
    Overrides:
      `setSingleExecutable` in class `ExecutableScorer`
    Parameters:
      `md5` - is the 32-character md5 hash of the executable single out
    Throws:
      `LSHException` - if we can't find the executable

  - ### countSelfScores

    public int countSelfScores()
    Overrides:
      `countSelfScores` in class `ExecutableScorer`
    Returns:
      number of executable self-significance scores are (will be) available

  - ### resetStorage

    public void resetStorage(double simThresh, double sigThresh) throws LSHException
    Description copied from class: `ExecutableScorer`
    Clear any persistent storage for self-significance scores, and establish new thresholds
    Overrides:
      `resetStorage` in class `ExecutableScorer`
    Parameters:
      `simThresh` - is the new similarity threshold
      `sigThresh` - is the new significance threshold
    Throws:
      `LSHException` - if there's a problem clearing storage

  - ### getSingularSelfScore

    public float getSingularSelfScore()
    Overrides:
      `getSingularSelfScore` in class `ExecutableScorer`

  - ### initializeScores

    protected void initializeScores()
    Description copied from class: `ExecutableScorer`
    Initialize the scoring matrix with zero. The matrix size is the number of executables registered with addExecutable()
    Overrides:
      `initializeScores` in class `ExecutableScorer`

  - ### checkPreliminaryPairThreshold

    protected boolean checkPreliminaryPairThreshold(int hitcount, int pairThreshold)
    Description copied from class: `ExecutableScorer`
    Make check if we are going to have too many pairs. This is preliminary because we haven't yet fetched the functions
    Overrides:
      `checkPreliminaryPairThreshold` in class `ExecutableScorer`
    Parameters:
      `hitcount` - is the total number of pairs to fetch
      `pairThreshold` - is the maximum number of pairs allowed
    Returns:
      true if the pair threshold is not exceeded

  - ### scorePair

    protected void scorePair(ExecutableScorer.FunctionPair pair)
    Description copied from class: `ExecutableScorer`
    Given a pair of score contributing functions that have been fully filtered, add the score into the matrix
    Overrides:
      `scorePair` in class `ExecutableScorer`
    Parameters:
      `pair` - is the pair of functions

  - ### pairFunctions

    protected List<ExecutableScorer.FunctionPair> pairFunctions(LSHVectorFactory vectorFactory, List<DescriptionManager> vec2func, List<VectorResult> vectors, int hitcount, int pairThreshold)
    Description copied from class: `ExecutableScorer`
    Generate all pairs of functions for any function associated with a list of vectors For each pair of functions generate the FunctionPair object with corresponding similarity and significance. This is inherently quadratic, but we try to be efficient. Duplicate vector pairs are only compared once and the similarity cached, and each function pair is generated only once, ie. (funcA,funcB) but not (funcB,funcA)
    Overrides:
      `pairFunctions` in class `ExecutableScorer`
    Parameters:
      `vectorFactory` - provides weights for significance scores
      `vec2func` - is the list of FunctionDescription sets associated with each vector
      `vectors` - is the list of vectors
      `hitcount` - is the cumulative total of functions
      `pairThreshold` - is the maximum number of pairs that can be produced
    Returns:
      the array of FunctionPairs or null if pairThreshold is exceeded

  - ### getScore

    public float getScore(int a)
    Description copied from class: `ExecutableScorer`
    Get score of executable (as compared to our singled out executable)
    Overrides:
      `getScore` in class `ExecutableScorer`
    Parameters:
      `a` - is the index of the executable
    Returns:
      the score

  - ### getSelfScore

    public float getSelfScore(int a) throws LSHException
    Description copied from class: `ExecutableScorer`
    Retrieve the similarity score of an executable with itself
    Overrides:
      `getSelfScore` in class `ExecutableScorer`
    Parameters:
      `a` - is the index of the executable
    Returns:
      its self-similarity score
    Throws:
      `LSHException` - if the score is not accessible

  - ### commitSelfScore

    public void commitSelfScore() throws LSHException
    Description copied from class: `ExecutableScorer`
    Commit the singled out executables self-significance score to permanent storage
    Overrides:
      `commitSelfScore` in class `ExecutableScorer`
    Throws:
      `LSHException` - if there's a problem writing, or the operation isn't supported

  - ### commitSelfScore

    protected void commitSelfScore(String md5, float selfScore) throws LSHException
    Description copied from class: `ExecutableScorer`
    Commit a self-significance score for a specific executable to permanent storage
    Overrides:
      `commitSelfScore` in class `ExecutableScorer`
    Parameters:
      `md5` - is the 32-character md5 hash of the executable
      `selfScore` - is the self-significance score
    Throws:
      `LSHException` - if there's a problem writing, or the operation isn't supported

  - ### getScore

    public float getScore(int a, int b)
    Description copied from class: `ExecutableScorer`
    Return the similarity score between two executables
    Overrides:
      `getScore` in class `ExecutableScorer`
    Parameters:
      `a` - is the index matching getXrefIndex() of the first executable
      `b` - is the index matching getXrefIndex() of the second executable
    Returns:
      the similarity score

  - ### prefetchSelfScores

    public void prefetchSelfScores(List<ExecutableRecord> missing) throws LSHException
    Pre-load self-scores of the registered executables.
    Parameters:
      `missing` - (optional - may be null) will contain the list of exes missing a score
    Throws:
      `LSHException` - if there are problems loading scores