Crate for contract bridge

This library provides tools for analyzing and simulating hands in the card game contract bridge. It is named after an anatomical part of the brainstem and also "bridge" in Latin.

Modules

bidding — Call, Auction, and a Trie-based representation of a bidding system.
deck — card sets, shuffling, and iterators that fill in partial deals.
eval — hand-evaluation kernels (HCP, shortness, LTC, NLTC, BUM-RAP, Fifths, Zar).
stats — numerically stable accumulators and double-dummy par scoring over histograms.

Feature flags

serde — derive Serialize/Deserialize for the library's value types. Off by default.

Quick start

Deal 10 random hands and evaluate the North hand with several point counts:

use pons::{full_deal, eval};
use pons::eval::HandEvaluator;
use dds_bridge::Seat;

let mut rng = rand::rng();
for _ in 0..10 {
    let deal = full_deal(&mut rng);
    let north = deal[Seat::North];

    let hcp: u8 = eval::SimpleEvaluator(eval::hcp).eval(north);
    let nltc: f64 = eval::NLTC.eval(north);
    let zar: u8 = eval::zar(north);

    println!("{}  HCP={hcp}  NLTC={nltc}  Zar={zar}", deal.display(Seat::North));
}

Estimate NS par from random fill-in deals (requires dds-bridge's solver, linked via dds-bridge-sys in dev-dependencies; see examples/average-ns-par):

use pons::{deck, stats};
use dds_bridge::{Deal, Hand, Seat};
use dds_bridge::solver::{self, StrainFlags, Vulnerability};

let cards = Deal::new(north_hand, Hand::EMPTY, south_hand, Hand::EMPTY);
let solutions = solver::Solver::lock().solve_deals(
    &deck::fill_deals(&mut rand::rng(), cards)?.take(90).collect::<Vec<_>>(),
    StrainFlags::all(),
)?;
let par = stats::average_ns_par(
    solutions.into_iter().collect(),
    Vulnerability::NONE,
    Seat::North,
);

Examples

The examples/ directory has runnable programs:

generate-deals — stream random deals to stdout.
notrump-tricks — average tricks taken in notrump per hand feature.
check-nltc and check-zar — validate hand-evaluation methods against double-dummy results.
average-ns-par — Monte-Carlo NS par score for a partial deal.

Run any of them with cargo run --example <name>.

MSRV