Function sp_npos_elections::phragmen::seq_phragmen

source · 
pub fn seq_phragmen<AccountId: IdentifierT, P: PerThing128>(
    to_elect: usize,
    candidates: Vec<AccountId>,
    voters: Vec<(AccountId, VoteWeight, impl IntoIterator<Item = AccountId>)>,
    balancing: Option<BalancingConfig>
) -> Result<ElectionResult<AccountId, P>, Error>
Expand description

Execute sequential phragmen with potentially some rounds of balancing. The return type is list of winners and a weight distribution vector of all voters who contribute to the winners.

  • This function is a best effort to elect rounds members. Nonetheless, if less candidates are available, it will only return what is available. It is the responsibility of the call site to ensure they have provided enough members.
  • If balance parameter is Some(i, t), i iterations of balancing is with tolerance t is performed.
  • Returning winners are sorted based on desirability. Voters are unsorted. Nonetheless, seq-phragmen is in general an un-ranked election and the desirability should not be interpreted with any significance.
  • The returning winners are zipped with their final backing stake. Yet, to get the exact final weight distribution from the winner’s point of view, one needs to build a support map. See crate::SupportMap for more info. Note that this backing stake is computed in ExtendedBalance and may be slightly different that what will be computed from the support map, due to accuracy loss.
  • The accuracy of the returning edge weight ratios can be configured via the P generic argument.
  • The returning weight distribution is normalized, meaning that it is guaranteed that the sum of the ratios in each voter’s distribution sums up to exactly P::one().

This can only fail of the normalization fails. This can happen if for any of the resulting assignments, assignment.distribution.map(|p| p.deconstruct()).sum() fails to fit inside UpperOf<P>. A user of this crate may statically assert that this can never happen and safely expect this to return Ok.

This can only fail if the normalization fails.

Note that rounding errors can potentially cause the output of this function to fail a t-PJR check where t is the standard threshold. The underlying algorithm is sound, but the conversions between numeric types can be lossy.