Developer's Guide

Introduction

Poker Prophesier is a Java application, consisting of two libraries: simulator.jar and client.jar, situated in the lib directory of an installation. The client.jar contains the graphical client to the actual Poker Prophesier simulator (that does all the work) which is in simulator.jar.

The simulator has a published public API that developers may use to write their own applications, which can leverage the functionality available in the simulator (subject to the Poker Prophesier license). The Poker Prophesier graphical client included in the installation is an example of such an application.

To write your own applications or client to the simulator, you will need to include the simulator.jar file in your classpath and set up your development environment to point to a JDK/JRE 5.0 installation. The Windows version of the Poker Prophesier installation includes a local JRE situated in the jre directory, where as the Unix installation does not, and it is assumed that you have a JDK/JRE 5.0 installed independently somewhere on your system (/usr/local, for example). You must use at least a 5.0 version of the JDK/JRE, as the simulator was written against this version.

Simple examples of how to write simulator client applications are included in the examples directory of the installation (with an Ant build file) and are also available to view: MySimulatorExample.java and PlayerSimulatorExample.java.

For more in-depth details about the API, consult the public API documentation, starting with the com.javaflair.pokerprophesier.api.adapter.PokerProphesierAdapter class.

Client Design

Communication between a client application and the simulator occurs via the com.javaflair.pokerprophesier.api.adapter.PokerProphesierAdapter class.

Typically, a client interacts with the simulator in the following way:

Instantiates the PokerProphesierAdapter adapter class
Sets any simulator parameters as required
Specifies the appropriate hole cards and community cards
Runs the simulator
Get references to the relevant helper classes which are populated with the simulator results

There are two types of simulation mode: Me vs Opponents and Player vs Player.

Me vs Opponents Mode

A Me vs Opponents simulation is from the perspective of a specific player, me, in a game against several opponents. Using a mixture of simulation and mathematics, the simulator uses my hole cards and the shared community cards to calculate my outs, the probability of improving my hand by the river, the probable hand any single opponent currently holds against my hand and my overall probability of winning the game.

The Me vs Opponents simulation can be configured to include/exclude certain types of hands when generating and calculating the simulation statistics. These parameters must be set before the simulation is executed. Specifically:

setMyOutsHoleCardSensitive()
When calculating the outs available to improve my own hand, this option configures the simulator to ignore outs that would solely lead to better community hands, i.e. hands that are shared amongst all of the players.
setOppHoleCardsRealistic()
In order to take into account that opponents in a game do not just play random hole cards, this option configures the simulator to base its calculations on the fact that an opponent will have a vaguely reasonable starting hand.
As a general rule of thumb, a reasonable starting hand is considered to be:
- A pair
- Suited connectors
- Same suited Ace and another card
- Cards that have a combined face value of 20 or 21
setOppProbMyHandSensitive()
This option configures the simulator to only calculate the probabilities of opponent hands which are better than my current hand.

The Me vs Opponents simulation is started by calling the method runMySimulations(HoleCards, CommunityCards, int, int). After the simulator completes the calculations, the following helpers are populated (depending on the game state):

MyHandHelper - A helper which contains the analysis of my current hand
MyOutsHelper - A helper which contains the details of my current outs
MyHandStatsHelper - A helper which contains the probabilities of my making a particular hand by the river card
OppHandStatsHelper - A helper which contains the probabilities of an opponent currently holding a particular hand
MyGameStatsHelper - A helper which contains the probabilities of my winning, tying or losing the game

Player vs Player Mode

A Player vs Player simulation calculates the probability of every player in a group of players winning or tying a game, given the specified hole cards of each player and the shared community cards.

Optionally, a player's hole cards can be marked as folded or a position left empty by specifying a null value.

The Player vs Player simulation is executed by calling the method runPlayerSimulations(HoleCards[], CommunityCards, int). After the simulator completes the calculations, the following helper is populated:

PlayerGameStatsHelper - A helper which contains the probabilities of each player winning/tying the game

Performance

The Poker Prophesier simulator is mathematically intensive, so as a general rule of thumb, the faster the system (i.e. processor) which Poker Prophesier is running on, the faster the Poker Prophesier simulator can perform the maths.

To give Poker Prophesier a boost, when running an application which is using the simulator, ensure that you use the Java HotSpot Server VM. This improves the overall performance at the cost of a bigger JVM memory footprint. Specifically:

Windows Users
By default, the JRE which is included with the Windows installation of Poker Prophesier is configured to use the Java HotSpot Server VM. If you use a different JDK/JRE, then the default JVM will be the Java HotSpot Client VM. So, to get the best performance when you run your simulator client, just use the JRE included in the Poker Prophesier installation.
Unix Users
By default, any Unix JDK/JRE includes the ability to switch between the Java HotSpot Server and Client VMs. For the best performance use the Server VM, by specifying the -server command-line option when you launch your application, e.g. java -server MyApp. The Poker Prophesier client is started in this way from the bin/run.sh script.

Full details about the VMs are available at Sun's Java site.

Free hit counters