Poker Mavens - Utility Programs

Updated 2012-08-21

Introduction

This page contains extra utility programs for Poker Mavens. These are compiled Windows applications ready to use.

Registration Saver 2.00

This program will save the list of players in the waiting lists for your tournaments so that you can take them offline, edit settings or restart the server, and then re-register those players after putting them back online. It communicates with the poker server via the API so it can be used locally or remotely.

Download

Download PMRegSave200.zip here. Unzip and save to a local folder of your choice and run directly (no setup program included).

Instructions

  1. Enter the IP address (or domain), file port, and API password for your poker server. If you are running the utility on the same local network or same computer then enter your local IP or localhost (127.0.0.1).
  2. Click the Load Tournament List button to fetch the current list of tournaments.
  3. Select the desired tournaments in the top list or click the Select All button to select all tournaments. To select or deselect individual tournaments without disturbing other selections, hold the Ctrl key down while clicking on a tournament.
  4. Click the Save Registrations button to fetch the waiting list of players for the selected tournaments. The Saved column will display the number of players registered. Click any indivdual tournament to see the list of registered players in the bottom list. You can manually register and unregister players for the selected tournament if desired. Taking a tournament offline will automatically unregister all players and refund their buy-ins.
  5. Click the Take Offline button to take the selected tournaments offline. The Status column for those tournaments will show a question mark. Click the Refresh Status button to get the current status and confirm they are offline. The Refresh Status button does not affect the list of saved registrations.
  6. Make whatever changes you need to the offline tournaments using the server console or the remote admin interface.
  7. Click the Put Online button to put the selected tournaments back online. Click the Refresh Status button again to refresh the status column.
  8. Click the Re-Register button to re-register all of the saved players for the selected tournaments. Click the Refresh Status once again to confirm the registrations.
  9. You can now close the utility.

Card Shuffling Simulator 1.01

This program is a simulator for the Poker Mavens card shuffler, available (with source code) for anyone who would like to examine its statistical properties. It can generate up to 6 million hands at a time (memory permitting) and uses the same RC4 stream cipher based random number generator and Knuth shuffling algorithm as the main program.

Download

Download PMShuffle101.zip here (Unbranded version here). Unzip and save to a local folder of your choice and run directly (no setup program included). Download the optional Delphi 2009 source code here.

Background

Conspiracy theories often arise from newcomers (and some oldtimers) in online poker in regards to how many "big hands" they seem to observe, especially compared to live games that they may be more familiar with. If not an outright manipulation of the hands by the software, there must be at least something wrong with the program's shuffling algorithm and/or random number generator. These claims are usually just anecdotal and not backed up by any statistical analysis. Ignorance of card odds and mechanics of poker in general, Texas Hold'em in particular, how cards are shuffled in software, and plain old human psychology are major factors. This card simulation utility provides statistical evidence that no "funny business" is actually occurring.

It's human nature to only remember the occasional quads vs straight flush hands and forget about all of the thousands of high card vs pair hands that we see. Someone who learned poker by playing live probably never saw thousands of hands to begin with, as they were lucky to play 20 or 30 hands an hour in a game that got together maybe once a week. With online poker, you're probably playing 60 or 70 hands per hour and maybe several tables at once, any time you feel like it. You are going to see a lot of big hands that way, especially on play money or low stakes tables where everyone limps in preflop and calls all the way to the river. When the action is cheap, people want lots of it, especially when they are playing on instinct and have no idea about what the actual drawing odds are. There are a lot of poker hands that can be made with five exposed community cards and 9 or 10 pairs of hole cards on the table. Contrast this to a table of solid players that raise preflop with good hands and fold with poor hands and no flop was ever dealt. I recently heard poker pro Daniel Negreanu remark on television on an episode of "High Stakes Poker" that he personally had never made a royal flush in all of his years of playing. I personally have made a half-dozen royal flushes just playing on PokerStars for a few years. But that few years consisted of many hundreds of thousands of hands.

The mechanics of shuffling and dealing cards in software is not well understood by most non-programmers so what follows is a brief explanation. Poker Mavens represents a deck of cards simply as an array of numbers from 1 to 52. The 1 represents the deuce of clubs, the 2 the deuce of diamonds, on up to 51 as the ace of hearts and the 52 as the ace of spades. The order of the suits were selected alphabetically (clubs, diamonds, hearts, spades). The actual shuffling algorithm knows nothing about player cards, however. It simply shuffles the array of numbers so that each one is equally likely to end up in any of the 52 slots. This occurs before the hand even starts. It doesn't know that each number corresponds to a playing card, let alone in a poker game, let alone for Texas Hold'em, let alone who they are dealt to or to which table.

Once the shuffle occurs, the order of the cards is fixed until the hand is complete. The cards that a player gets is determined by the rules of Texas Hold'em. The software simply follows those rules and has no more say in the matter. It's all up to the players in how they play their hands and if there will be a flop, turn, or river card dealt. The first card in the deck goes to the first player clockwise from the button. The player on the button is the last one to get a card. Then that process is repeated for the second hole card. The next five cards will make up the community cards, if needed. Poker Mavens does not use burn cards. Note that a player leaving or joining the table completely changes the hands that will be made, as does a player sitting out in a ring game table since they are skipped. Also, if multiple tables are active, any particular table will get a different set of decks than if they were the only table running. As mentioned, the shuffling algorithm knows nothing of these particulars. Even a lousy shuffling algorithm would still produce equally looking random hands and couldn't create an usual number of "big hands" even if it wanted to.

What makes a good card shuffling algorithm are two main requirements: each card must have an equal chance of landing in any position in the deck, and the random number generator used by the shuffler must be unpredictable to a human observer so that they cannot determine the future order of the cards. Poker Mavens satisfies both of these requirements using the highly efficient shuffling algorithm described in "The Art of Computer Programming", a series of acclaimed books written by noted computer scientist Donald Knuth. The random number generator uses an RC4 stream cipher, designed by noted cryptographer Ronald Rivest. The stream cipher is seeded with a random 256-bit key, generated by hashing a seed pool with the SHA-256 hash algorithm. The seed pool is constructed by sampling the CPU's 1.193 MHz high-performance counter. Those samplings occur each time the operating system communicates an internal message to the Server Module, which can be thousands of times per second and is also affected by interaction with the game administrator (mouse movements, key presses, etc.). The full source code for these routines is provided in the download link above.

Instructions

The interface for the shuffling simulator consists of a scrollable list of shuffled card decks and a three-tab menu above it, labeled Shuffle, Texas Hold'em Stats, and Card Stats. Each line in the list holds all 52 cards of a single shuffled deck. The shuffling algorithm used is the same one used in the main Poker Mavens program.

Use the Shuffle tab to add shuffled decks to the list by typing in the desired number and clicking the "Add to List" button. The program can use up to 2 GB of RAM, which corresponds to approximately 6 million shuffles maximum. Adding more than that will crash the program with an "Out of Memory" error. Use the "Clear All" button to clear the list and the "Save to File" to export the current list to a text file.

Use the Texas Hold'em Stats tab to simulate hands dealt to a table of Texas Hold'em players. The two hole cards for the selected position are displayed in red while the community cards are displayed in blue. When any particular hand is selected in the deck list, the poker hand made for the selected position is displayed on the status line below the list.

Use the Players droplist to select the number of active players, from 2 to 10. When changing this setting, you will see how it affects both hole cards and community cards dealt, even though the deck itself does not change.

Use the Position droplist to select the player you want to use in the statistical analysis. The "D" position represents the player with the Dealer Button and other settings (D-1, D-2, etc.) are offsets from that position. When a position with "rotate" is selected, the stats will simulate a rotating button. For example, if you selected "D (rotate)", the red hole cards will be in the last position on hand 1, second to last on hand 2, third to last on hand 3, etc. This simulates what happens in an actual game, assuming the number of players held constant.

Use the Dealt droplist to specify how many cards should be used in the statistical analysis: "Hole" for hole cards only, "Flop" for hole + flop, "Turn" for hole + flop + turn, and "River" for all. You will see the number of blue columns change in the list as you change this setting.

Click the Stats button to display the poker hand stats for the selected position, using all hands in the list. The output will look something like this:

Player position: D
Cards dealt: River
Shuffles: 100000

High Card:       17554  (17.5540%)
Pair:            43841  (43.8410%)
Two Pair:        23283  (23.2830%)
Three of a Kind: 4841  (4.8410%)
Straight:        4565  (4.5650%)
Flush:           3036  (3.0360%)
Full House:      2666  (2.6660%)
Four of a Kind:  186  (0.1860%)
Straight Flush:  25  (0.0250%)
Royal Flush:     3  (0.0030%)

Use the "Find Next" button to locate a particular poker hand, starting in the list just past the current selected deck. For example, if you select "Flush" in the Hand droplist and click the Find Next button, the cursor will move to the next Flush found for the selected position as determined by the red hole cards and blue community cards. Note that each hand also has "-" and "+" options such that "Flush -" instructs the program to find the next Flush or lesser hand while "Flush +" finds the next Flush or better hand.

Use the Card Stats tab for generic statistics on card, rank, suit, and deck position. The first Stats button will count how many times the selected card appears in the list in each one of the 52 deck positions. The second Stats button does the same but only considers the card rank (deuce to ace). The third Stats button only considers the card suit (club, diamond, heart, spade). The last Stats button allows you to pick a particular position in the deck (1 to 52) and then counts the occurrences of cards, ranks, and suits in that position. The output will look something like this:

Deck Position: 1
Shuffles: 100000

Suit = Count  (Percent) Avg = 25.0000%

c = 24979  (24.9790%)
d = 25142  (25.1420%)
h = 24861  (24.8610%)
s = 25018  (25.0180%)

Rank = Count  (Percent) Avg = 7.6923%

2 = 7777  (7.7770%)
3 = 7747  (7.7470%)
4 = 7575  (7.5750%)
5 = 7679  (7.6790%)
6 = 7639  (7.6390%)
7 = 7724  (7.7240%)
8 = 7718  (7.7180%)
9 = 7490  (7.4900%)
T = 7809  (7.8090%)
J = 7724  (7.7240%)
Q = 7719  (7.7190%)
K = 7746  (7.7460%)
A = 7653  (7.6530%)

Card = Count  (Percent) Avg = 1.9231%

2c = 2042  (2.0420%)
2d = 1873  (1.8730%)
2h = 1935  (1.9350%)
2s = 1927  (1.9270%)
3c = 1916  (1.9160%)
3d = 1969  (1.9690%)
3h = 1935  (1.9350%)
3s = 1927  (1.9270%)
4c = 1912  (1.9120%)
4d = 1923  (1.9230%)
4h = 1895  (1.8950%)
4s = 1845  (1.8450%)
5c = 1970  (1.9700%)
5d = 1951  (1.9510%)
5h = 1790  (1.7900%)
5s = 1968  (1.9680%)
6c = 1868  (1.8680%)
6d = 1955  (1.9550%)
6h = 1922  (1.9220%)
6s = 1894  (1.8940%)
7c = 1918  (1.9180%)
7d = 1948  (1.9480%)
7h = 1906  (1.9060%)
7s = 1952  (1.9520%)
8c = 1883  (1.8830%)
8d = 1982  (1.9820%)
8h = 1906  (1.9060%)
8s = 1947  (1.9470%)
9c = 1802  (1.8020%)
9d = 1912  (1.9120%)
9h = 1897  (1.8970%)
9s = 1879  (1.8790%)
Tc = 1958  (1.9580%)
Td = 1964  (1.9640%)
Th = 1923  (1.9230%)
Ts = 1964  (1.9640%)
Jc = 1917  (1.9170%)
Jd = 1941  (1.9410%)
Jh = 1923  (1.9230%)
Js = 1943  (1.9430%)
Qc = 1906  (1.9060%)
Qd = 1940  (1.9400%)
Qh = 1950  (1.9500%)
Qs = 1923  (1.9230%)
Kc = 1917  (1.9170%)
Kd = 1893  (1.8930%)
Kh = 1990  (1.9900%)
Ks = 1946  (1.9460%)
Ac = 1970  (1.9700%)
Ad = 1891  (1.8910%)
Ah = 1889  (1.8890%)
As = 1903  (1.9030%)

Poker Mavens 2 Service Utility

Download: PM2Service.zip

This program installs as a Windows Service program and launches the Poker Mavens 2 server application under the specified Windows account. This allows your poker site to automatically start if your server gets rebooted.

Update: this program also works with version 3. Just unzip the files into the version 3 program folder and follow the same directions below.

Poker Mavens already has an "Auto start server at bootup" setting but it only works on systems that don't have user passwords, and thus automatically boot up to a primary Windows account. Remote VPS or dedicated servers always have password protected user accounts for security purposes and thus they do not log into an account on bootup. Windows service programs all start up at boot time and thus don't need an active login.

This service simply launches the PMServer.exe program with the -autostart switch when it starts up. The downside to this method is that Poker Mavens will run in the Windows console session and thus its interface cannot be seen. You will have to use the Remote Admin interface in your web browser to perform administration functions. To stop the program, you will have to kill its process using the Windows Task Manager.

Instructions

Unzip the PM2Service.zip file into the same folder where the Poker Mavens program is located. The default location is:

C:\Program Files (x86)\Briggs Softworks\Poker Mavens 2\

On 32-bit systems, the "(x86)" will not be there.

Run (double-click in Windows Explorer) PM2SInstall.bat to install the service program. You should see this message: "Service installed successfully". Click Ok.

The batch file will then launch the Windows Services manager. This can also be started manually by clicking the Start button, Run, and typing in "services.msc".

Right-click on "Briggs Softworks PM2 Service" and select Properties. Click the Log On tab. Check the "This account" option and type in your Windows login name (usually "Administrator"). Enter the password for that account (along with the confirmation) and click Ok. The service cannot be assigned to a non-password account. You should then get the message "The account .\Administrator has been granted the Log On As A Service right". The ".\" represents the current domain and is attached automatically. Click Ok.

The next time the computer is rebooted, the service should start automatically and then launch PMServer.exe with the -autostart switch. You can test that now by manually starting the service:

Right-click on "Briggs Softworks PM2 Service" and select Start. As mentioned before, you will not see the interface because it's running in a different session. Right click on the Windows task bar and launch the Task Manager. On the Processes tab, check the "Show processes from all users" option at the bottom. You should see PM2Service.exe (the service program) and PMServer.exe (Poker Mavens). Use the "End Process" button to kill Poker Mavens. To uninstall the service, run the PM2SUninstall.bat file that was included.

To access the remote admin interface, start up any browser and enter your IP address (with the file port) with "/admin" appended to the end.

Rake Stats 2.00

This program imports ring game hand history files (English only) into a local database file and allows you to calculate statistical reports on the amount of rake collected by player and table. The hand history files can be retrieved locally or remotely via the API. This utility works with Poker Mavens 2.xx and Poker Mavens 3.xx hand history files.

Download PMRakeStats200.zip and unzip into a folder where you have write privileges. No installer is included. Just launch PMRake.exe to start the program. An SQLite database file (PMRake2.db3) will be created in the same folder.

Version 1 of this utility used calculations that distributed the rake equally among all players who were dealt cards in the hand. Now in version 2, you also have the option of distributing the rake proportionally so that the rake credit given to each player is in direct proportion to how many chips they put into the pot on each hand. This option required a stuctural change to the database, specifically the "Share" field in the master table was renamed to "AvgShare" and a new "Share" field was added to the detail table.

Instructions

Use the Hand Histories tab to view and import ring game history files into the database. You have two methods of importing files: loading directly from the local file system or remotely using the Poker Mavens API functions. To use the API method, your poker server needs to be online and you must enter the applicable IP address, file port, and API password. Click the "Get Hand History List" button to see the available ring game files. If you are loading files locally, you will be prompted for the hand history folder.

You may view the contents of a particular file by double clicking its name in the list or by clicking the "View Selected File" button. Click the "Import Selected Files" button to import files into the database. Tournament files are ignored since they do not contain raked hands.

You do not have to worry about accidentally importing the same file more than once. The database tables are keyed on hand number and re-importing will simply overwrite records if they already exist. Note that prior to version 2.92 of Poker Mavens, hands played near midnight might have started in one file and ended in the next day's file. Those hands will not be imported unless you manually edit the files and place the entire hand into one file. This is not an issue with Poker Mavens 2.92 and later where hands are never split across multiple files.

Use the Rake Database tab to view the database of imported hands. The database is an SQLite file called PMRake2.db3 and consists of Master and Detail tables. Click the "Open" button to open the tables for viewing. The database file is saved locally so it does not use the API for viewing. You cannot edit the tables although you can empty them with the "Empty" button. The Master table consists of one record for every raked hand (at least 1 chip raked). The fields are:

The Detail table consists of three fields: Hand, Player, and Share where Hand is the hand number linked to the corresponding hand in the Master table, Player is the name of a player who was dealt into that hand, and Share is the proportional representation of the rake based on the number of chips the player contributed to the pot. Players who were seated and sitting out are not included. The number of players listed for each hand in the Detail table should match the Dealt field in the Master table.

Use the Reports tab to run SQL queries on the database and produce statistical reports. You can limit the hands selected by specific starting and/or ending dates. Select a report in the drop list. This will display the corresponding SQL query. Click the "Load" button to execute the query and the results will be displayed in the table below. The following reports are available:

Note that you can edit the SQL query manually to run your own custom reports. Most of the included reports require an "inner join" function that combines the two tables to perform counts and summations. This is a time consuming operation and thus once your database grows to several hundred thousand hands, it make take several minutes to run each report. Narrowing the date range of the report will speed that query up substantially.

Click the "Export" button to create a CSV (comma separated value) text file of the report output. It can then be imported into any spreadsheet program.

Tourney Fee Stats 1.00

This program imports tournament result files into a local database file and allows you to calculate statistical reports on the amount of entry fees collected by player and tournament. The entry fee is the portion of the tournament buy-in that goes to the house account. The result files can be retrieved directly via the local file system or remotely via the API. This utility works with version 2.xx and version 3.xx tournament result files.

Download PMFeeStats100.zip and unzip into a folder where you have write privileges. No installer is included. Just launch PMFee.exe to start the program. An SQLite database file (PMFee.db3) will be created in the same folder.

Instructions

Use the Tournament Results tab to view and import result files into the database. You have two methods of importing files: loading directly from the local file system or remotely using the Poker Mavens API functions. To use the API method, your poker server needs to be online and you must enter the applicable IP address, file port, and API password. Click the "Get Tourney Results List" button to see the available result files. If you are loading files locally, you will be prompted for the tournament results folder.

You may view the contents of a particular file by double clicking its name in the list or by clicking the "View Selected File" button. Click the "Import Selected Files" button to import files into the database. Tournaments with a 0 entry fee (e.g., 1500+0) will be skipped. Tournaments that were aborted by the administrator before they finished will still be imported, but the players who were still active at the time are not included since their entry fees were refunded. You do not have to worry about accidentally importing the same file more than once. The database tables are keyed on tournament number and re-importing will simply overwrite records if they already exist.

Use the Fee Database tab to view the database of imported result files. The database is an SQLite file called PMFee.db3 and consists of Master and Detail tables. Click the "Open" button to open the tables for viewing. The database file is saved locally so it does not use the API for viewing. You cannot edit the tables although you can empty them with the "Empty" button. The Master table consists of one record for every tournament played where a non-zero entry fee was charged. The fields are:

The Detail table consists of two fields: TNumber and Player, where TNumber is the tournament number linked to the corresponding number in the Master table and Player is the name of a player who paid an entry fee into that tournament. For each selected tournament, the number of players listed in the Detail table should match the Paid field in the Master table.

Use the Reports tab to run SQL queries on the database and produce statistical reports. You can limit the tournaments selected by specific starting and/or ending dates. Select a report in the drop list. This will display the corresponding SQL query. Click the "Load" button to execute the query and the results will be displayed in the table below. The following reports are available:

Note that you can edit the SQL query manually to run your own custom reports. Most of the included reports require an "inner join" function that combines the two tables to perform counts and summations. This is a time consuming operation and thus once your database grows very large, it make take several seconds to run each report. Narrowing the date range of the report will speed up that query.

Click the "Export" button to create a CSV (comma separated value) text file of the report output. It can then be imported into any spreadsheet program.

Event Log Viewer 1.01

This program allows you to view multiple event log files and apply numerous filters to isolate only the events that you are interested in. Log files can be loaded directly from the local file system or remotely via the API. Download PMEView101.zip and unzip into any folder. No installer is included. Just launch EViewer.exe to start the program.

Instructions

The main window displays a list of event records just as you would see from the Logs tab in the server console of Poker Mavens. However this utility has the ability to display events across multiple days and apply filters. Click the Select Files button to start.

Use the Local Event Files tab to load log files if they are on the same computer. Click the Select Folder button to specify the folder where your event files are stored. A list of EventLog*.txt files in that folder will be displayed in the list below. Select the files that you want to view and then click Ok.

Use the Remote Event Files tab to load log files using the Poker Mavens API. Your site must be online to use this option. Enter your site's IP address, file port number, and API password in the spaces provided and then click the Get List button to see the list of available event log files. Select the files that you want to view and then click Ok.

Back in the main window, click the Set Filters button if you want to isolate events based on selected filters as shown below. Set Start and End times to only display logs in the specified date or time range. In Event Types, check only the types that you want to see. With Event Descriptions, you can include or exclude events based on text strings found in the Description field. Leave the Include list empty to include all entries not otherwise filtered out by the other settings. If you enter any search strings, at least one of them must appear somewhere in the description for that entry to be displayed. In the Exclude list, enter search strings that will exclude a log entry from appearing if any of the terms you enter are found in the description. Include and Exclude strings are not case sensitive.

Click the Remove Filters button on the main window to display all the selected files without any filtering. Click the Export button to save the current list to a local text file. The name must start with "EventLog" and have a ".txt" extension if you want to load it back later.

Import Utility 1.02

This program will import your Poker Mavens 2 settings and player accounts into version 3. Download PMImport102.zip and unzip into any folder. No installer is included. Just launch PMImport.exe to start the program.

Check the options that you want to import and click the Import button. Poker Mavens 3 cannot be running when you do this. Version 3 settings and accounts are completely separate from version 2 settings. Version 3 stores API, Remote Admin, and player passwords in an encrypted format using a one-way hash. This utility will perform that encryption for you automatically.