pams documentation

This file documents pams version 2.005.

What is pams?

Pams is poslfit's analyser of Maven simulations, a Perl script that extracts statistical information from simulation logs generated by Brian Sheppard's Scrabble analysis tool Maven. Pams runs on any system that supports Perl, and has been tested on Macintosh, Unix and DOS systems.

How do I install it?

Macintosh: If you don't already have a copy of Perl installed on your machine, get one from www.perl.com and install it. Save the pams script as a file, beginning with the line that starts "#!". Run Perl, open the pams script file, and re-save it as a "droplet".
Unix: Save the script in a file in your executables directory, beginning with the line that starts "#!". Edit that line to refer to your local copy of Perl. Use chmod to make the file executable.

How do I run it?

First use Maven to create a simulation log file. For more information about this, consult Maven's documentation.

Macintosh

To run pams with no options, just drag a simulation log file onto the pams icon and drop it. To specify options, make a copy of the pams icon and rename it to include the options. For example, if you want an equity histogram and all output redirected to a file called o, you could name the copy p -e -o o.

TIP: Because of window content size limitations in MacPerl, you will often want to redirect output to a file.

TIP: You do not need to interrupt a simulation to analyse it; if you analyse a simulation in progress, pams will just warn you if the last line of the log file is still incomplete (and ignore it).

Unix

At your shell prompt, type: pams [any options] log-file-name.

What are these options?

-b turn: For each play that you simulated, and for the turn number you specify, display diagrams showing which show how often each square was used, and how much each square contributed to expected equity.
-B: Similar to -b, but includes effects of all simulated turns
-e: Display an equity histogram, suitable for determining the percentage probability that a play will lead to a win, or to being ahead by a certain amount at simulation depth.
-h lines: Read only the beginning of the log file, up to the number of lines you specify. Useful if you have a huge log file that will take a long time to analyse, and you're trying to decide what information you want pams to calculate.
-H: Format output using HTML tags
-m: Use Maven's equity calculations when showing equity histograms. If you don't trust Maven's rack leave parameters (and you shouldn't, when simulating), you shouldn't usually use this option. Without this option, the equity values tabulated will be based solely on the positive and negative contributions of simulated plays. You should however always use this option when analysing an endgame position, to pick up the contribution of tiles stuck on the last rack, and pams will warn you if it thinks you forgot.
-o file: Write output to the specified file, and not the display. Useful for Macs, where the standard output stream doesn't support paging and is limited in size.
-p: Print parsed log file lines, for debugging purposes.
-q: Be terse, and suppress the initial board diagram, some headings and legends.
-r tiles: Analyse only those racks where the simulated opponent holds the specified tiles. Useful if you have partial information about what tiles your opponent holds. This of course reduces the number of iterations that are analysed by a factor of whatever the likelihood is that opponent holds the tiles in question. E.g., if opp is 25% likely to hold 'ES', then pams will look at only about a quarter of the lines in the log file if you run it with -r es.
-t: Display the number of tiles played each turn. Useful for estimating how often a play leads to a bingo or a tile exchange.
-v: Display the version number of the script you are running. It should match the one at the top of this file.