Create app.py

app.py

@@ -0,0 +1,187 @@
+"""
+Python implementation and Gradio app for "An Optimal Strategy for [Solitaire] Yahtzee" (James Glenn, 2006)
+Source: https://gunpowder.cs.loyola.edu/~jglenn/research/optimal_yahtzee.pdf
+
+At each turn, the optimal strategy depends only on:
+- The available scoring categories (2**13 possibilities)
+- The total score in the upper section, capped at 63 (2**6 possibilities)
+
+For each of the 2**19 possible states, we compute the expected optimal score for the rest of the game.
+This implementation does not include Yahtzee bonuses or jokers.
+
+The Gradio app then allows you to input your current scorecard and dice roll to get the optimal action.
+"""
+
+import numpy as np
+import gradio as gr
+from tqdm import tqdm
+
+FOUR_OF_A_KIND_IS_40_POINTS = False  # common variant used in France
+
+# Compute Rk and R5 (unique dice combinations for up to 5 dice / exactly 5 dice)
+Rk = np.indices((6,) * 6).reshape(6, -1).T
+Rk = Rk[Rk.sum(axis=1) <= 5]  # size 462
+R5 = Rk[Rk.sum(axis=1) == 5]  # size 252
+
+# Compute R (all combinations of up to 5 dice)
+R = np.indices((7,) * 5).reshape(5, -1).T
+R = np.array([np.bincount(r, minlength=7)[1:] for r in R])
+R = [R[R.sum(axis=1) == i] for i in range(6)]
+
+# Calculate probabilities (P) of each R5 outcome from each Rk roll
+P = np.zeros((len(Rk), len(R5)))
+R5_indices = {tuple(r): i for i, r in enumerate(R5)}
+for i, rk in enumerate(Rk):
+    for r in R[5 - rk.sum()]:
+        P[i, R5_indices[tuple(rk + r)]] += 1
+P /= P.sum(axis=1, keepdims=True)
+M = (P > 0).T  # Mask for valid transitions
+
+# Calculate category scores for all R5 outcomes
+R5_scores = np.zeros((len(R5), 13), dtype=int)
+R5_scores[:, :6] = R5 * np.arange(1, 7)
+upper_score = R5_scores[:, :6].sum(axis=1)
+R5_scores[:, 6] = upper_score
+m = R5.max(axis=1)
+R5_scores[:, 7] = upper_score * (m >= 3)
+R5_scores[:, 8] = (40 if FOUR_OF_A_KIND_IS_40_POINTS else upper_score) * (m >= 4)
+R5_scores[:, 9] = 25 * np.array([set(r) == {0, 2, 3} for r in R5])
+R5_scores[:, 10] = 30 * ((R5[:, 0:4] > 0).all(axis=1)| (R5[:, 1:5] > 0).all(axis=1)| (R5[:, 2:6] > 0).all(axis=1))
+R5_scores[:, 11] = 40 * ((R5[:, 0:5] > 0).all(axis=1) | (R5[:, 1:6] > 0).all(axis=1))
+R5_scores[:, 12] = 50 * (m == 5)
+
+# Initialize state scores:
+# - Bits 0-5: upper section score (capped at 63 for bonus)
+# - Bits 6-11: upper categories (Aces, Twos, Threes, Fours, Fives, Sixes)
+# - Bits 12-18: lower categories (Chance, Three-of-a-kind, Four-of-a-kind, Full House, Small Straight, Large Straight, Yahtzee)
+UPPER_TOTAL_BITS = 2**6 - 1
+UPPER_TOTAL_AND_CATEGORIES_BITS = 2**12 - 1
+CATEGORIES_BITS = 2**19 - 2**6
+
+states = np.arange(2**19, dtype=int)
+scores = np.zeros(2**19, dtype=float)
+
+def get_score(state):
+    # Get children states
+    available = np.array([1 - (state >> (6 + i)) & 1 for i in range(13)])
+    upper_total_states = np.clip((state & UPPER_TOTAL_BITS) + R5_scores * (np.arange(13) < 6), 0, 63)
+    categories_states = (state & CATEGORIES_BITS) + 2 ** np.arange(6, 19)
+    children = available * (upper_total_states + categories_states)
+
+    # Backpropagate scores from children to root of the widget (as per the paper description)
+    s3 = available * (R5_scores + scores[children]) # Roll 3
+    s2 = P @ s3.max(axis=1) # Roll 2
+    s1 = P @ np.where(M, s2, 0).max(axis=1)  # Roll 1
+    s0 = P[0] @ np.where(M, s1, 0).max(axis=1)  # Root state
+
+    return s0, s1, s2, s3
+
+# Identify reachable states (e.g., an upper total of 1 is impossible if only "Twos" was played)
+reachable_states = np.zeros(2**12, dtype=bool)
+U = np.indices((7,) * 6).reshape(6, -1).T  # 6 means unused category
+reachable_states[np.clip((U % 6) @ np.arange(1, 7), 0, 63) + (U < 6) @ (2 ** np.arange(6, 12))] = True
+
+# Compute scores sorted by the number of categories already played
+# The score for the 64 states with all categories played is 0 except if the upper total is 63
+order = np.argsort([bin(state)[:-6].count("1") for state in states])[::-1]
+scores[-1] = 35
+for idx in tqdm(order[63:]):
+    if reachable_states[states[idx] & UPPER_TOTAL_AND_CATEGORIES_BITS]:
+        scores[idx] = get_score(states[idx])[0]
+print(f"Optimal score at the beginning of the game: {scores[0]:.2f}")  # 245.87 as per the paper (section 6)
+
+# Gradio app
+EMPTY = ""
+score_options = {
+    "Ones": [EMPTY, 0, 1, 2, 3, 4, 5],
+    "Twos": [EMPTY, 0, 2, 4, 6, 8, 10],
+    "Threes": [EMPTY, 0, 3, 6, 9, 12, 15],
+    "Fours": [EMPTY, 0, 4, 8, 12, 16, 20],
+    "Fives": [EMPTY, 0, 5, 10, 15, 20, 25],
+    "Sixes": [EMPTY, 0, 6, 12, 18, 24, 30],
+    "Chance": [EMPTY] + list(range(0, 31)),
+    "Three of a kind": [EMPTY] + list(range(0, 31)),
+    "Four of a kind": ([EMPTY, 0, 40] if FOUR_OF_A_KIND_IS_40_POINTS else ([EMPTY] + list(range(0, 31)))),
+    "Full House": [EMPTY, 0, 25],
+    "Small Straight": [EMPTY, 0, 30],
+    "Large Straight": [EMPTY, 0, 40],
+    "Yahtzee": [EMPTY, 0, 50],
+}
+
+categories = list(score_options.keys())
+upper_categories, lower_categories = categories[:6], categories[6:]
+
+def update_components(*inputs):
+    # Parse inputs
+    scorecard = {c: inputs[i] for i, c in enumerate(categories)}
+    roll = inputs[len(categories)]
+    dice = np.array(inputs[len(categories) + 1 :])
+
+    # Compute totals
+    scorecard_values = [0 if v == EMPTY else v for v in scorecard.values()]
+    upper, lower = sum(scorecard_values[:6]), sum(scorecard_values[6:])
+    bonus = 35 if upper > 62 else 0
+
+    # Compute optimal action
+    if (EMPTY not in dice) and (EMPTY in scorecard.values()):
+        state = np.clip(upper, 0, 63) + sum(2 ** (6 + i) for i, c in enumerate(categories) if scorecard[c] != EMPTY)
+        s = get_score(state)[roll]
+        r5 = R5_indices[tuple(np.bincount(dice, minlength=7)[1:])]
+
+        if roll == 3:
+            idx = np.argmax(s[r5])
+            new_score = R5_scores[r5, idx]
+            action = f"Play {categories[idx]} ({new_score} pts)\nExpected score: {upper + lower + new_score + s[r5, idx]:.2f}"
+        else:
+            rk = Rk[np.argmax(np.where(M, s, 0)[r5])]
+            keep = sum([[i + 1] * rk[i] for i in range(6)], [])
+            action = f"Keep {keep}"
+    else:
+        action = ""
+
+    return upper, bonus, lower, lower + bonus + upper, action
+
+
+with gr.Blocks() as app:
+
+    gr.Markdown("""# 🎲 Optimal Yahtzee
+This app recommends the optimal strategy for playing solitaire Yahtzee, based on [James Glenn's 2006 research](http://gunpowder.cs.loyola.edu/~jglenn/research/optimal_yahtzee.pdf).
+### How to use:
+- Enter your current scores in the upper and lower sections.
+- Select the roll number (1, 2, or 3) and input your dice values (1–6).
+- The app will display the optimal dice to keep (rolls 1 or 2) or the best scoring category to select (roll 3).
+""" + FOUR_OF_A_KIND_IS_40_POINTS * "\n**Note:** In this variant, Four of a Kind is worth 40 points.")
+
+    score_inputs = {}
+
+    with gr.Row():
+        with gr.Column():
+            gr.Markdown("### Upper Section")
+            for c in upper_categories:
+                score_inputs[c] = gr.Dropdown(score_options[c], label=c, value=EMPTY)
+            upper_score = gr.Number(label="Upper Total", interactive=False)
+            bonus_score = gr.Number(label="Bonus (if >62)", interactive=False)
+
+        with gr.Column():
+            gr.Markdown("### Lower Section")
+            for c in lower_categories:
+                score_inputs[c] = gr.Dropdown(score_options[c], label=c, value=EMPTY)
+            lower_score = gr.Number(label="Lower Total", interactive=False)
+            total_score = gr.Number(label="Total", interactive=False)
+
+        with gr.Column():
+            gr.Markdown("### Current Roll")
+            roll_input = gr.Dropdown([1, 2, 3], label="Roll number", value=1)
+            dice_inputs = [
+                gr.Dropdown([EMPTY, 1, 2, 3, 4, 5, 6], label=f"Die {i+1}")
+                for i in range(5)
+            ]
+            action_box = gr.Textbox(label="Optimal action", lines=2)
+
+    inputs = list(score_inputs.values()) + [roll_input] + dice_inputs
+    outputs = [upper_score, bonus_score, lower_score, total_score, action_box]
+
+    for inp in inputs:
+        inp.change(update_components, inputs=inputs, outputs=outputs)
+
+app.launch()