Pons

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 — Trie-based representation of a bidding system. Auction primitives (Call, Auction, etc.) live in the contract-bridge crate.
• stats — numerically stable accumulators and double-dummy par scoring over histograms.

Card sets and shuffling live in contract-bridge::deck; hand-evaluation kernels in contract-bridge::eval.

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 contract_bridge::Seat;
use contract_bridge::deck::full_deal;
use contract_bridge::eval::{self, HandEvaluator};

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 ddss's solver, linked via ddss-sys in dev-dependencies; see examples/average-ns-par):

use contract_bridge::deck;
use contract_bridge::{Builder, Hand, Seat};
use ddss::{NonEmptyStrainFlags, Solver, Vulnerability};
use pons::stats;
# let north_hand: Hand = "T9762.AT54.JT75.".parse().unwrap();
# let south_hand: Hand = "A.KQ962.A86.Q642".parse().unwrap();

let cards = Builder::new()
    .north(north_hand)
    .south(south_hand)
    .build_partial()
    .expect("north and south hands are disjoint and ≤13 each");
let solutions = Solver::lock().solve_deals(
    &deck::fill_deals(&mut rand::rng(), cards).take(90).collect::<Vec<_>>(),
    NonEmptyStrainFlags::ALL,
);
let par = stats::average_ns_par(
    solutions.into_iter().collect(),
    Vulnerability::NONE,
    Seat::North,
);

Examples

The examples/ directory has runnable programs:

• 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.
• defend-2sx-or-3nt — compare expected NS score from defending 2♠× vs declaring 3NT.

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

Two examples that don't need pons live one level down the stack: generate-deals in contract-bridge and notrump-tricks in ddss (with a parallel copy in dds-bridge).