From: Eric S. Raymond <esr@thyrsus.com>
Date: Thu, 13 Apr 1995 21:14:39 +0000 (+0000)
Subject: Initial revision
X-Git-Tag: 2.0~10
X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=501fc1215b2d097b3f997f9cd454d67dc4268f3a;p=deal.git

Initial revision
---

diff --git a/deal.xml b/deal.xml
new file mode 100644
index 0000000..d5ff241
--- /dev/null
+++ b/deal.xml
@@ -0,0 +1,74 @@
+.TH DEAL 1 "April 12, 1995"
+.SH NAME
+deal \- compute and display deal probabilities
+.SH SYNOPSIS
+.B deal [-h]  [-b base] [-t turns] [-c columns] specials total
+.SH DESCRIPTION
+This program prints out tables of non-replacement draw probabilities,
+rounded to the nearest percent.
+.PP
+Suppose I have M special cards in my deck and N total cards in my deck,
+and I draw k cards from that deck without replacement.  Let X count
+the number of special cards contained in those k drawn cards.
+.PP
+Then X has a hypergeometric distribution, with the following formula
+for probabilities:
+
+.nf
+                B(M, i)B(N-M, k-i)
+     P(X = i) = ---------------------
+                      B(N, k)
+.fi
+
+where B(a,b) is read "a choose b", and is the number of ways
+to choose b objects out of a possible objects.  The formula for it is
+
+    B(a,b) =   a!/(b! (a-b)!)
+
+This program prints out tables of these probabilities.  The `specials'
+and `total' arguments specify M and N.  The table displays values for
+ranges of k and i.
+.PP
+In the table output, a dot designates a probability less than .5% that
+rounds to zero.  Impossible outcomes are blank.
+.PP
+The program accepts the following options to control its output:
+.TP 10
+-b
+Number of cards to assume in the initial hand.  Note: this defaults to
+7, \fBnot\fB to 0!
+.TP 10
+-c
+Number of columns to generate in the report.
+.TP 10
+-h
+Suppress table headers and legends.
+.TP 10
+-t
+Set number of draws to display probabilities for (default to 20 or the
+total number of cards, whichever is less)
+.PP
+.SH EXAMPLES
+To compute the probabilities for drawing your 3 Hurloon 
+Minotaurs during the first 20 turns from a 62-card "Magic: The
+Gathering" deck (MtG starts you with 7 cards):
+
+    deal 3 62
+
+To compute your chances of drawing the 4 aces in 5-card draw poker:
+
+    deal -b 5 4 52 
+
+.SH BUGS
+For various extreme values of the arguments, the code is prone to
+SIGFPE errors in the lgamma() function (it will tell you when this
+happens).  I think this is due to floating-underflow conditions but
+am not familiar enough with the math library or general numerical
+analysis to be sure.
+.PP
+Since it doesn't happen in useful cases, and there is no portable
+fix that I know of, we'll just have to live with it.
+.SH AUTHOR
+Eric S. Raymond <esr@snark.thyrsus.com>.  Based on the `cardprobs'
+program by Jeremy York.  See my home page at
+http://www.thyrsus.com/~esr/home.html for updates and other resources.