ICM Calculator

Calculate ICM equities for poker tournament payouts.

Installation

Add @poker-apprentice/icm-calculator as a dependency.

• yarn:

  yarn add @poker-apprentice/icm-calculator

• npm:

  npm install @poker-apprentice/icm-calculator --save

Usage

This package exports a calculate function that can be used to calculate ICM payouts for a poker tournament based upon prize values and remaining chip stacks. To use it, simply pass an object containing numeric arrays of payouts values and chipStacks values.

calculate

The calculate function performs an exact calculation whenever it can be done quickly, falling back to a Monte Carlo estimate for scenarios where an exact calculation would be too expensive. The cost of an exact calculation depends on both the number of chip stacks and the number of payouts, so exact results are returned for any final table (up to ~19 players with every place paid), or for much larger fields when only a few places are paid.

import { calculate } from '@poker-apprentice/icm-calculator';

const icmAmounts = calculate({
  payouts: [425, 280, 130, 75],
  chipStacks: [150000, 98750, 45500, 13250],
});
console.log(icmAmounts); // => [323.2, 278.12, 195.79, 112.89]

This function should be preferred over calculateExact and calculateEstimate in virtually all cases.

calculateExact

The calculateExact function is based upon the Malmuth-Harville equation in section 2.2 of this article from the Journal of the Mathematical Society of the Philippines. It is implemented as a dynamic program over subsets of players, making it fast for any realistic final table. The amount of work grows with the number of player subsets that can occupy the paid places, so it becomes expensive when both the number of chip stacks and the number of payouts are large (e.g.: beyond ~19 players when every place is paid), and it throws an error beyond 30 chip stacks. Use calculate to fall back to an estimate automatically in those scenarios.

import { calculateExact } from '@poker-apprentice/icm-calculator';

const icmAmounts = calculateExact({
  payouts: [425, 280, 130, 75],
  chipStacks: [150000, 98750, 45500, 13250],
});
console.log(icmAmounts); // => [323.2, 278.12, 195.79, 112.89]

calculateEstimate

The calculateEstimate function performs a Monte Carlo simulation (i.e.: random sampling) to come up with an acceptable approximate ICM calculation. This is based upon the ICM equities algorithm proposed by Tysen Streib on the 2+2 forums.

For data sets represented by chipStacks that are too large for calculateExact, the calculateEstimate function is recommended for time-sensitive implementations.

import { calculateEstimate } from '@poker-apprentice/icm-calculator';

const icmAmounts = calculateEstimate({
  payouts: [425, 280, 130, 75],
  chipStacks: [150000, 98750, 45500, 13250],
});
console.log(icmAmounts); // => [323.2, 278.12, 195.79, 112.89]

Optionally, an iterations option can be provided to override the default value of 10,000. This value specifies how many Monte Carlo simulations should be performed per the number of chip stacks provided in chipStacks. (For example, if chipsStacks is set to [1000, 500] and iterations is set to 10, then 2×10=20 total calculations will be performed.)

import { calculateEstimate } from '@poker-apprentice/icm-calculator';

const icmAmounts = calculateEstimate({
  payouts: [425, 280, 130, 75],
  chipStacks: [150000, 98750, 45500, 13250],
  iterations: 250,
});
console.log(icmAmounts); // => [323.2, 278.12, 195.79, 112.89]

Contributing

If you'd like to fix a bug, add a feature, improve the documentation, or anything else to better this library, pull requests are welcomed!

1. Clone the repository:

   git clone [email protected]:poker-apprentice/icm-calculator.git

2. Install dependencies:

   yarn install

3. Include tests for your changes, and open a pull request.

If you are interested in contributing, but you are stuck or lost at any point in your efforts, please reach out for help!