rsr.rsr.select_refs_by_acquisition

rsr.rsr.select_refs_by_acquisition(cand_states, refs_states_upper, refs_states_lower, gamma=1.0, k=1, validate=False, return_details=False)[source]

Pick the unresolved candidates with the highest acquisition score.

Candidates certified by either reference set are filtered out before scoring, so a certified vector can never be selected however its score would have ranked.

Ties are broken deterministically by the lexicographically smallest component-state vector, so the result never depends on the order in which candidates are supplied. Ties are not incidental here: they occur exactly at the gamma where the ranking switches over. Scores are compared after rounding to nine decimals so the tie-break is not decided by floating-point noise.

Parameters:

  • cand_states (Tensor) – (n_cand, n_var) integer candidate vectors.

  • refs_states_upper (Tensor) – (n_upper, n_var) upper reference coordinates.

  • refs_states_lower (Tensor) – (n_lower, n_var) lower reference coordinates.

  • gamma (float) – Non-negative weight; see acquisition_score().

  • k (int) – Number of candidates to return, in descending score order.

  • validate (bool) – If True, check reference-set consistency first.

  • return_details (bool) – If True, also return the per-candidate deficits and scores.

Returns:

(min(k, n_unresolved),) int64 tensor of indices into cand_states. If return_details, a (indices, details) pair where details holds d_upper, d_lower, scores (all indexed like cand_states) and unresolved (a boolean mask).

Raises:

ValueError – If k < 1, if either reference set is empty, or if no candidate is unresolved.