PokerMLwiki

Legacy card utilities

From the PokerML wiki

Legacy card utilities
Also known as CardUtils, hand conversion, suit abstraction, preflop equities
Files 9
Lines of code 322
Languages JSON, Python
Entry points CardUtils.py
First commit 2 October 2024
Last commit 4 December 2024
Main contributors Sean May (100%)
Revision 56ad610

Legacy card utilities is a collection of utility functions in CardUtils.py for converting between card representations, generating poker hands, and applying suit abstractions to compress hand ranges. The module stores preflop equities as a JSON lookup table and provides functions to query hand strength and manipulate hand sets for use in range calculations.

flowchart LR
  n1["CardUtils.py"]
  n2[["Game state management"]]
  n2 -->|"calls"| n1
Data flow of Legacy card utilities

Overview

Card representations use integer encoding from 0 to 51, where rank is calculated by dividing by 4 and suit by the remainder, enabling efficient storage and comparison.[1] The module provides functions to convert between text notation (such as "AK" or "JJ+") and hand sets, supporting range notation with "+" for consecutive hands.[2] Three abstraction functions—suitDifferenceAbstraction(), suitedAbstraction(), and offsuitAbstraction()—compress hand ranges by grouping similar hands and consolidating their probabilities.[3] listNumStringsToListHands() converts equity data from numeric string format to displayable card strings in sorted order.[4] preFlopEquities.json contains precomputed win probabilities for all two-card hand matchups, keyed by numeric hand notation with suit suffix ('s' for suited, 'o' for offsuit).[5]

How it works

numToCard() maps integers to card strings by using the rank index (integer divided by 4) and suit index (remainder modulo 4) to look up stored rank and suit symbols.[1] textToHand() parses a two-character hand notation into ranks, then calls ranksToHands() to generate all possible card combinations with those ranks.[6] ranksToHands() generates all hands for a given rank pair by iterating through suit combinations; for pairs it excludes duplicate suits, for non-pairs it includes all combinations.[7] textToHandSet() parses comma-separated hand ranges and expands shorthand notation like "JT+" (connected hands of increasing rank) and "22+" (consecutive pairs) into full hand sets.[8]

suitDifferenceAbstraction() merges hands with identical ranks if the absolute difference between their suit indices is equal, pooling probability concentrations into a single representative hand.[9] suitedAbstraction() and offsuitAbstraction() group suited hands or offsuit hands respectively with identical ranks, transferring concentration mass to the highest-ranked representative.[10]

History

  • Preflop equity calculations were completed on 16 October 2024 using square root equity evaluation after initial Monte Carlo simulations.[11]
  • Range equity calculations against hands were added on 2 October 2024, followed by improvements to hand abstractions on 3 October 2024.[12][13]
  • Hand abstraction techniques were improved on 14 October 2024 before the module was incorporated into the alpha-beta pruning solver.[14][15]

See also

References

  1. ^ a b CardUtils.py:L7-8@56ad610 (numToCard)
  2. ^ CardUtils.py:L18-54@56ad610
  3. ^ CardUtils.py:L88-144@56ad610
  4. ^ CardUtils.py:L74-85@56ad610 (listNumStringsToListHands)
  5. ^ preFlopEquities.json:L1-30@56ad610
  6. ^ CardUtils.py:L18-21@56ad610 (textToHand)
  7. ^ CardUtils.py:L24-35@56ad610 (ranksToHands)
  8. ^ CardUtils.py:L38-54@56ad610 (textToHandSet)
  9. ^ CardUtils.py:L88-106@56ad610 (suitDifferenceAbstraction)
  10. ^ CardUtils.py:L108-144@56ad610
  11. ^ Commit fc26d32: "Long calculation for pre-flop equities using SqRoot equity evaluation completed."
  12. ^ Commit cb17cd6: "Range text view, Range equity against hand given board"
  13. ^ Commit 66afd2a: "Updated README, tests for Range"
  14. ^ Commit 7865c3d: "Improved abstractions, Monte-Carlo simulations implemented"
  15. ^ Commit c5f62a9: "Alpha-beta pruning working on river. Heuristics need some work"

This page was last edited on 24 March 2026, at commit 56ad610.