Crate aya_poker

source ·
Expand description

AyaPoker is a Rust library for fast poker hand evaluation based on the OMPEval C++ hand evaluator, with support for most popular poker variants.

Features

  • Can be used to rank hands from standard poker, ace-to-five lowball, deuce-to-seven lowball, six-or-better (short-deck), Omaha, Omaha Hi/Lo, Badugi or Baduci.
  • Can evaluate hands with 0 to 7 cards, with the missing cards counting as the worst possible kickers, allowing for use in stud poker games.
  • Uses compile-time generated perfect hash function lookup tables for excellent runtime performance and fast initialization.
  • Has extensive suite of tests to ensure correct implementation of the hand ranking rules for each variant.

Flags

This crate has the following Cargo features:

  • std: By default, aya_poker is a !#[no_std] crate, but can be compiled with the std feature in order to allow the initialization of Decks with system-generated random seeds.
  • colored: Use colored to display cards and hands in color.
  • colored-4color: Same as colored, but using a four-color deck.

Example

use std::cmp::Ordering;

use aya_poker::{base::*, deck::Deck, poker_rank};

const SEED: u64 = 42;
const SAMPLE_SIZE: usize = 100_000;

fn main() -> Result<(), ParseError> {
    // We can initialize cards by specifying the rank and suit,
    // and then use collect to combine the cards into a Hand
    let player = [
        Card::new(Rank::King, Suit::Hearts),
        Card::new(Rank::King, Suit::Clubs),
    ]
    .iter()
    .collect();

    // Or, first parse the cards from strings
    let opponent = ["Js".parse::<Card>(), "Qs".parse::<Card>()]
        .iter()
        .copied()
        .collect::<Result<Hand, ParseError>>()?;

    // Or, parse a space-separated string of cards as a Hand
    let board = "Ah 5s Ts".parse()?;

    let equity = equity_calculator(&player, &opponent, &board);
    println!(
        "{} has {:.1}% equity on {} against {}.",
        player,
        100.0 * equity,
        board,
        opponent
    );

    Ok(())
}

fn equity_calculator(
    player: &Hand,
    opponent: &Hand,
    board: &Hand,
) -> f64 {
    // To simulate board run-outs, we begin by preparing a deck
    // that doesn't contain the already dealt-out cards
    let available_cards = CARDS
        .iter()
        .filter(|c| !player.contains(c))
        .filter(|c| !opponent.contains(c))
        .filter(|c| !board.contains(c));
    let mut deck = Deck::with_seed(available_cards, SEED);

    let mut pots_won = 0.0;
    for _ in 0..SAMPLE_SIZE {
        // Then, for each run we draw cards to complete the board
        deck.reset();
        let missing = 5 - board.len();
        let complete_board = board
            .iter()
            .chain(deck.deal(missing).unwrap().iter())
            .collect::<Hand>();

        // Evaluate the player's hand given the completed board
        let mut player_hand = *player;
        player_hand.extend(complete_board.iter());
        let player_rank = poker_rank(&player_hand);

        // Evaluate the opponent's hand
        let mut opponent_hand = *opponent;
        opponent_hand.extend(complete_board.iter());
        let opponent_rank = poker_rank(&opponent_hand);

        // And record the player's share of the pot for the run
        match player_rank.cmp(&opponent_rank) {
            Ordering::Greater => pots_won += 1.0,
            Ordering::Less => {}
            Ordering::Equal => pots_won += 0.5,
        };
    }

    pots_won / SAMPLE_SIZE as f64
}

Modules

  • base
    Basic types for playing card games.
  • deck
    Deck types optimized for fast shuffling suitable for use in simulators.

Structs

Enums

  • BadugiRankCategory
    A Badugi/Baduci hand-ranking category corresponding to the size of the made hand.
  • PokerRankCategory
    A poker hand-ranking category, i.e. a straight, a flush, etc.

Functions

  • ace_five_rank
    Returns the rank of the best 5-card ace-five lowball poker hand that can be made from the given cards.
  • baduci_rank
    Returns the rank of the best Baduci (Badugi with aces playing high) hand that can be made from the given cards.
  • badugi_rank
    Returns the rank of the best Badugi hand that can be made from the given cards.
  • deuce_seven_rank
    Returns the rank of the best 5-card deuce-seven lowball poker hand that can be made from the given cards.
  • omaha_lo_rank
    Returns the rank of the best 5-card ace-five lowball poker hand that can be made with precisely two hole cards and three cards from the board.
  • omaha_rank
    Returns the rank of the best 5-card poker hand that can be made with two hole cards and three board cards.
  • poker_rank
    Returns the rank of the best standard 5-card poker hand that can be made from the given cards.
  • short_deck_rank
    Returns the rank of the best 5-card six-or-better poker hand that can be made from the given cards.