Skip to main content

simulateHandOutcome

Estimated equity vs one or more random villain hands (default villains = 1).

simulateHandOutcome(holeCards: CardInput, board: CardInput, numSimulations: number, seed: number, villains?: number): number

CardInput is string[] or Uint8Array of deck ids 0..51. See Card notation.

Import​

const poker = require('poker-calculations');

ESM (Node):

import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const poker = require('poker-calculations');

When to use​

Use when you need fast equity estimates on partial or full boards and exact enumeration would be too slow—trainers, bots, and range studies. Fix seed (and numSimulations) when you need reproducible numbers across runs.

How to use​

const poker = require('poker-calculations');

const equity = poker.simulateHandOutcome(
  ['Ah', 'Kh'],
  ['Qh', 'Jh', '2c'],
  8000,
  42,
  1,
);
console.log(equity.toFixed(4));

Increase numSimulations until the standard error is acceptable; pair with monteCarloStandardError.

Showdown scoring​

With villains = 1, equity is heads-up win/chop/loss style over trials. With villains > 1, when hero ties for the best hand, hero receives 1 / tiedAtBest of the pot share for that trial. See Numerical semantics.

See also​

parallelHandSimulation · Monte Carlo equity guide