endplay.evaluate

Functions for evaluating bridge hands using a variety of different metrics.

Data:

bergen_hcp_scale	Bergen HCP scale with A=4.5, K=3, Q=1.5, J=0.75, T=0.25
length_dist_scale	Distribution point scale which awards a point for each extra card in a suit over 4
mixed_fit_dist_scale	Combined scale using shortage_fit_dist_scale and length_dist_scale
mixed_nofit_dist_scale	Combined scale using shortage_nofit_dist_scale and length_dist_scale
shortage_fit_dist_scale	Distribution point scale when a trump fit is found with void=5, singleton=3, doubleton=1
shortage_nofit_dist_scale	Distribution point scale with void=3, singleton=2, doubleton=1
standard_hcp_scale	Classic HCP scale with A=4, K=3, Q=2, J=1

Functions:

cccc(hand)	Uses the Kaplan four cs algorithm from the October 1982 issue of Bridge world magazine.
controls(hand)	Return the number of controls in a sequence, using A=2 and K=1
dist_points(obj[, scale, exclude])	Return the extra points for distribution for a hand or suit holding using the given scale.
exact_shape(hand)	Return the shape of a hand as a list starting from spades, e.g.
hcp(obj[, scale])	Return the high card points of a hand or suit holding using a given scale.
is_balanced(hand)	Returns True if the hand shape is 4333, 4432 or 5332
is_minor_semibalanced(hand)	Returns True if the hand shape is balanced or contains doubletons in both minors
is_semibalanced(hand)	Returns True if the hand shape is balanced or 5422
is_single_suited(hand[, min_length, ...])	Returns True if the hand is singled suited
is_three_suited(hand[, strict])	Returns True if the hand has three suits with at least four cards in them.
is_two_suited(hand[, strict])	Returns True if the hand contains at least 10 cards in two suits.
losers(hand)	Returns the number of losers in a hand.
major_shape(hand)	Return the shape of a hand's major holding from longest to shortest
minor_shape(hand)	Return the shape of a hand's minor holding from longest to shortest
quality(hand)	Uses the quality algorithm (from the October 1982 issue of Bridge World magazine)
rule_of_n(hand)	Returns the hcp of the hand added to the length of the two longest suits
shape(hand)	Return the shape of a hand as a list from longest to shortest, e.g.
top_honours(hand[, lowest_honour])	Return the number of top honors in a suit
total_points(obj[, hcp_scale, dist_scale, ...])	Return the sum of high card points and distribution points in a hand.

endplay.evaluate.bergen_hcp_scale: list[float] = [4.5, 3, 1.5, 0.75, 0.25, 0, 0, 0, 0, 0, 0, 0, 0]

Bergen HCP scale with A=4.5, K=3, Q=1.5, J=0.75, T=0.25

endplay.evaluate.cccc(hand: Union[Hand, SuitHolding]) → float

Uses the Kaplan four cs algorithm from the October 1982 issue of Bridge world magazine. This implementation is based on the interpretation of the algorithm described on http://www.rpbridge.net/8j19.htm

endplay.evaluate.controls(hand: Union[Iterable, Card, Rank]) → int

Return the number of controls in a sequence, using A=2 and K=1

endplay.evaluate.dist_points(obj: Union[Hand, SuitHolding], scale: list[float] = [3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], exclude: Iterable[Denom] = []) → float

Return the extra points for distribution for a hand or suit holding using the given scale. Five scales are predefined:

• shortage_nofit_dist_scale: Standard evaluation of shortage points if no trump fit is agreed, void=3, singleton=2, doubleton=1

• shortage_fit_dist_scale: Standard evaluation of shortage points if trump fit is agreed, void=5, singleton=3, doubleton=1

• length_dist_scale: Standard evaluation of length points, one point for each extra card in a suit with more than four cards in it, i.e. 5 cards=1, 6 cards=2, etc…

Parameters:

• obj – Hand or suit holding to evaluate

• scale – A list of 14 numbers which assign points to each suit length in ascending order, e.g. [3,2,1,0,…] is used for the standard shortage points where void=3, singleton=2 etc…

• exclude – List of suits to be excluded from distribution calculations if a Hand object is passed, in order to e.g. exclude the trump suit from the calculation

endplay.evaluate.exact_shape(hand: Hand) → list[int]

Return the shape of a hand as a list starting from spades, e.g. (5, 2, 3, 3)

endplay.evaluate.hcp(obj: Union[Iterable[Union[Card, Rank, AlternateRank]], Card, Rank, AlternateRank], scale: list[float] = [4, 3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0]) → float

Return the high card points of a hand or suit holding using a given scale. Two scales are predefined: standard_hcp_scale which uses the traditional 4321 point scale, and bergen_hcp_scale which uses the Bergen scale.

Parameters:

• obj – A (possibly iterable of) card or rank type to evaluate

• scale – A list of 13 numbers which assign points to each rank in descending order, e.g. [4,3,2,1,0,…] is used for the standard HCP scale where an ace is worth 4 points, a king 3 etc…

endplay.evaluate.is_balanced(hand: Hand) → bool

Returns True if the hand shape is 4333, 4432 or 5332

endplay.evaluate.is_minor_semibalanced(hand: Hand) → bool

Returns True if the hand shape is balanced or contains doubletons in both minors

endplay.evaluate.is_semibalanced(hand: Hand) → bool

Returns True if the hand shape is balanced or 5422

endplay.evaluate.is_single_suited(hand: Hand, min_length: int = 6, no_side_suit: bool = False) → bool

Returns True if the hand is singled suited

Parameters:

• min_length – The minimum number of cards to hold in the suit

• no_side_suit – If True, the hand cannot contain another 4 card suit

endplay.evaluate.is_three_suited(hand: Hand, strict: bool = False) → bool

Returns True if the hand has three suits with at least four cards in them.

Parameters:

strict – Only return true if the hand is 4441

endplay.evaluate.is_two_suited(hand: Hand, strict: bool = False) → bool

Returns True if the hand contains at least 10 cards in two suits.

Parameters:

strict – Hand must be at least 5-5

endplay.evaluate.length_dist_scale: list[float] = [0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Distribution point scale which awards a point for each extra card in a suit over 4

endplay.evaluate.losers(hand: Union[Hand, SuitHolding]) → int

Returns the number of losers in a hand. The number of losers in each suit is calculated as: (a) 3 or more cards in a suit: 3 - 1 per AKQ (b) Doubleton: AK=0, Ax/Kx=1, else 2 (c) Singleton: A=0, else 1 (d) Void: 0

endplay.evaluate.major_shape(hand: Hand) → list[int]

Return the shape of a hand’s major holding from longest to shortest

endplay.evaluate.minor_shape(hand: Hand) → list[int]

Return the shape of a hand’s minor holding from longest to shortest

endplay.evaluate.mixed_fit_dist_scale: list[float] = [5, 3, 1, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Combined scale using shortage_fit_dist_scale and length_dist_scale

endplay.evaluate.mixed_nofit_dist_scale: list[float] = [3, 2, 1, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Combined scale using shortage_nofit_dist_scale and length_dist_scale

endplay.evaluate.quality(hand: SuitHolding) → float

Uses the quality algorithm (from the October 1982 issue of Bridge World magazine)

endplay.evaluate.rule_of_n(hand: Hand) → float

Returns the hcp of the hand added to the length of the two longest suits

endplay.evaluate.shape(hand: Hand) → list[int]

Return the shape of a hand as a list from longest to shortest, e.g. a 3424 would return (4, 4, 3, 2)

endplay.evaluate.shortage_fit_dist_scale: list[float] = [5, 3, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Distribution point scale when a trump fit is found with void=5, singleton=3, doubleton=1

endplay.evaluate.shortage_nofit_dist_scale: list[float] = [3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Distribution point scale with void=3, singleton=2, doubleton=1

endplay.evaluate.standard_hcp_scale: list[float] = [4, 3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Classic HCP scale with A=4, K=3, Q=2, J=1

endplay.evaluate.top_honours(hand: Union[Hand, SuitHolding], lowest_honour: Union[Rank, int] = Rank.RJ) → int

Return the number of top honors in a suit

Parameters:

• suit – The suit holding to evaluate

• lowest_honour – The lowest rank to be treated as an honour, or an integer for how many top cards are honours

endplay.evaluate.total_points(obj: Union[Hand, SuitHolding], hcp_scale: list[float] = [4, 3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0], dist_scale: list[float] = [3, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], trump: Optional[Denom] = None, protect_honours: bool = False)

Return the sum of high card points and distribution points in a hand.

Parameters:

• obj – Hand or suit holding to evaluate

• hcp_scale – The HCP scale to use, as for the hcp function

• dist_scale – The distribution points scale, as for the dist_scale function

• trump – If set then distribution points for the given suit are excluded from the calculation

• protect_honours – If True, then honours must be protected for their HCP to be included, i.e. king singleton, queen doubleton etc do not contribute to total points