From: Eric S. Raymond <esr@thyrsus.com>
Date: Thu, 13 Apr 1995 14:00:56 +0000 (+0000)
Subject: Improve the comments.
X-Git-Tag: 2.0~21
X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=5c679dcb14ce68e8f2f05df549ac361adcb2a4fc;p=deal.git

Improve the comments.
---

diff --git a/deal.c b/deal.c
index 09cbd9a..bc427a9 100644
--- a/deal.c
+++ b/deal.c
@@ -1,3 +1,31 @@
+/*
+ * cardprobs -- compute combination probabilities for Magic: The Gathering
+ *
+ * by Jeremy C. York <jeremy@stat.cmu.edu>; cleanup, comments, and
+ * interface improvements by Eric Raymond <esr@snark.thyrsus.com>.
+ *
+ * If I have M special cards (for example, land cards) in my deck, and N
+ * total cards in my deck, and I draw k cards from that deck (*without
+ * replacement* -- the fact that you don't put them back into the deck
+ * can be important for some values of M and N), and if X counts the
+ * number of special cards contained in those k drawn cards...
+ * 
+ * Then X has a hypergeometric distribution, with the following formula
+ * for probabilities:
+ * 
+ *                 B(M, i) * B(N-M, k-i)
+ *      P(X = i) = ---------------------
+ *                   B(N, k)
+ * 
+ * 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)!)
+ *
+ * Compile with:
+ *
+ *	cc cardprobs.c -lm -o cardprobs
+ */
 #include <math.h>
 
 #define BASEHAND	7	/* # cards in initial deal */
@@ -58,6 +86,12 @@ main(argc, argv)
     }
 }
 
+/* 
+ * We avoid nasty numerical problems by using log of gamma function to
+ * calculate factorials, and doing everything on the log scale before
+ * giving the final answer.
+ */
+
 double hyper_prob(x, k, M, N)
     int x, k, M, N;
 {