Package com.apple.foundationdb.kmeans

Record Class PartitionEvaluator.Parameters

java.lang.Object
java.lang.Record
com.apple.foundationdb.kmeans.PartitionEvaluator.Parameters
Record Components:
distanceEstimator - the distance estimator used for all distance computations
minRelativeSseGain - minimum relative SSE (sum of squared errors) improvement required; candidates with less improvement are rejected. May be negative if the caller wants to accept some SSE increase (e.g. for merges).
minSeparation - minimum inter-cluster separation required; not checked when the candidate has fewer than two clusters
maxLowMarginRate - maximum fraction of vectors with low assignment margin; not checked when the candidate has fewer than two clusters
minChildFraction - minimum fraction of vectors in the candidate's smallest cluster; candidates that violate this are reported as PartitionEvaluator.Decision.INVALID_CANDIDATE. This is the only balance threshold that can invalidate a candidate outright, so callers that must always have some admissible candidate should keep it low. Use 0.0 to disable.
maxRelativeImbalance - maximum PartitionEvaluator.PartitionStats.relativeImbalance() the candidate may have, in [0, 1]; candidates that violate this are reported as PartitionEvaluator.Decision.KEEP_CURRENT. Use 1.0 to disable this check.
lowMarginThreshold - distance threshold below which a vector's assignment margin is considered "low"; if non-positive, a metric-dependent default is used (0.02 for cosine, 5% of p95 for L2)
alphaSseGain - weight for the SSE gain component in the composite score
betaSeparationGain - weight for the separation gain component in the composite score
gammaImbalancePenalty - weight for the imbalance penalty in the composite score
deltaLowMarginPenalty - weight for the low-margin-rate penalty in the composite score
minScoreGain - minimum composite score improvement the candidate must achieve over the current partitioning to be accepted
Enclosing class:
PartitionEvaluator
public static record PartitionEvaluator.Parameters(@Nonnull DistanceEstimator distanceEstimator, double minRelativeSseGain, double minSeparation, double maxLowMarginRate, double minChildFraction, double maxRelativeImbalance, double lowMarginThreshold, double alphaSseGain, double betaSeparationGain, double gammaImbalancePenalty, double deltaLowMarginPenalty, double minScoreGain) extends Record
Tuning parameters that control when a candidate repartitioning is accepted or rejected, and how the composite quality score is computed.

Balance is policed by two thresholds that deliberately measure different things. minChildFraction is a plain fraction because it stands in for an absolute vector count — "do not produce a cluster too small to be worth having" — and the population being partitioned does not depend on k. maxRelativeImbalance is normalized by k because spread does: the worst achievable PartitionEvaluator.PartitionStats.imbalance() is (k−1)/k, so only the rescaled PartitionEvaluator.PartitionStats.relativeImbalance() means the same thing at every k.

Both are safe for a single-cluster candidate without special-casing by the caller: smallestFrac is 1.0 and relativeImbalance() is 0, so a merge to one cluster passes any setting of either. That is what makes a fallback merge structurally immune to the balance gates.

  • Field Details

    • DEFAULT_MIN_RELATIVE_SSE_GAIN

      public static final double DEFAULT_MIN_RELATIVE_SSE_GAIN
      Default minimum relative SSE improvement a candidate must show.
      See Also:

    • DEFAULT_MIN_SEPARATION

      public static final double DEFAULT_MIN_SEPARATION
      Default inter-cluster separation floor.
      See Also:

    • DEFAULT_MAX_LOW_MARGIN_RATE

      public static final double DEFAULT_MAX_LOW_MARGIN_RATE
      Default ceiling on the fraction of vectors sitting near a cluster boundary.
      See Also:

    • DEFAULT_MIN_CHILD_FRACTION

      public static final double DEFAULT_MIN_CHILD_FRACTION
      Default floor on the smallest cluster's share; see minChildFraction().
      See Also:

    • DEFAULT_MAX_RELATIVE_IMBALANCE

      public static final double DEFAULT_MAX_RELATIVE_IMBALANCE
      Default ceiling on PartitionEvaluator.PartitionStats.relativeImbalance(); 1.0 disables the check.
      See Also:

    • DEFAULT_LOW_MARGIN_THRESHOLD

      public static final double DEFAULT_LOW_MARGIN_THRESHOLD
      Sentinel selecting the metric-dependent low-margin threshold.
      See Also:

    • DEFAULT_ALPHA_SSE_GAIN

      public static final double DEFAULT_ALPHA_SSE_GAIN
      Default weight of the SSE-gain term in the composite score.
      See Also:

    • DEFAULT_BETA_SEPARATION_GAIN

      public static final double DEFAULT_BETA_SEPARATION_GAIN
      Default weight of the separation-gain term in the composite score.
      See Also:

    • DEFAULT_GAMMA_IMBALANCE_PENALTY

      public static final double DEFAULT_GAMMA_IMBALANCE_PENALTY
      Default weight of the imbalance-penalty term in the composite score.
      See Also:

    • DEFAULT_DELTA_LOW_MARGIN_PENALTY

      public static final double DEFAULT_DELTA_LOW_MARGIN_PENALTY
      Default weight of the low-margin-penalty term in the composite score.
      See Also:

    • DEFAULT_MIN_SCORE_GAIN

      public static final double DEFAULT_MIN_SCORE_GAIN
      Default minimum composite score improvement required to accept a candidate.
      See Also:

  • Constructor Details

    • Parameters

      public Parameters(@Nonnull DistanceEstimator distanceEstimator)
      Convenience constructor that picks a moderately permissive set of defaults, each named by a DEFAULT_* constant above. Tighten or loosen via the canonical constructor as needed.
      Parameters:
      distanceEstimator - the distance estimator used for all distance computations

    • Parameters

      public Parameters(@Nonnull DistanceEstimator distanceEstimator, double minRelativeSseGain, double minSeparation, double maxLowMarginRate, double minChildFraction, double maxRelativeImbalance, double lowMarginThreshold, double alphaSseGain, double betaSeparationGain, double gammaImbalancePenalty, double deltaLowMarginPenalty, double minScoreGain)
      Creates an instance of a Parameters record class.
      Parameters:
      distanceEstimator - the value for the distanceEstimator record component
      minRelativeSseGain - the value for the minRelativeSseGain record component
      minSeparation - the value for the minSeparation record component
      maxLowMarginRate - the value for the maxLowMarginRate record component
      minChildFraction - the value for the minChildFraction record component
      maxRelativeImbalance - the value for the maxRelativeImbalance record component
      lowMarginThreshold - the value for the lowMarginThreshold record component
      alphaSseGain - the value for the alphaSseGain record component
      betaSeparationGain - the value for the betaSeparationGain record component
      gammaImbalancePenalty - the value for the gammaImbalancePenalty record component
      deltaLowMarginPenalty - the value for the deltaLowMarginPenalty record component
      minScoreGain - the value for the minScoreGain record component

  • Method Details

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • distanceEstimator

      @Nonnull public DistanceEstimator distanceEstimator()
      Returns the value of the distanceEstimator record component.
      Returns:
      the value of the distanceEstimator record component

    • minRelativeSseGain

      public double minRelativeSseGain()
      Returns the value of the minRelativeSseGain record component.
      Returns:
      the value of the minRelativeSseGain record component

    • minSeparation

      public double minSeparation()
      Returns the value of the minSeparation record component.
      Returns:
      the value of the minSeparation record component

    • maxLowMarginRate

      public double maxLowMarginRate()
      Returns the value of the maxLowMarginRate record component.
      Returns:
      the value of the maxLowMarginRate record component

    • minChildFraction

      public double minChildFraction()
      Returns the value of the minChildFraction record component.
      Returns:
      the value of the minChildFraction record component

    • maxRelativeImbalance

      public double maxRelativeImbalance()
      Returns the value of the maxRelativeImbalance record component.
      Returns:
      the value of the maxRelativeImbalance record component

    • lowMarginThreshold

      public double lowMarginThreshold()
      Returns the value of the lowMarginThreshold record component.
      Returns:
      the value of the lowMarginThreshold record component

    • alphaSseGain

      public double alphaSseGain()
      Returns the value of the alphaSseGain record component.
      Returns:
      the value of the alphaSseGain record component

    • betaSeparationGain

      public double betaSeparationGain()
      Returns the value of the betaSeparationGain record component.
      Returns:
      the value of the betaSeparationGain record component

    • gammaImbalancePenalty

      public double gammaImbalancePenalty()
      Returns the value of the gammaImbalancePenalty record component.
      Returns:
      the value of the gammaImbalancePenalty record component

    • deltaLowMarginPenalty

      public double deltaLowMarginPenalty()
      Returns the value of the deltaLowMarginPenalty record component.
      Returns:
      the value of the deltaLowMarginPenalty record component

    • minScoreGain

      public double minScoreGain()
      Returns the value of the minScoreGain record component.
      Returns:
      the value of the minScoreGain record component