Do a bunch more README work.

diff --git a/doc/README.rst b/doc/README.rst
index 6d00dee5e77396cbee8d844108ef55c14ff74312..46407670a2ad0b3d57a9ec8cff98a9f792c1f186 100644 (file)
--- a/doc/README.rst
+++ b/doc/README.rst
@@ -11,6 +11,93 @@ efficiently, and thus the linear games supported by Dunshire are a
 bastard of the two: the cones are symmetric, but the players get to
 choose two interior points.
 
+In this game, we have two players who are competing for a "payoff."
+There is a symmetric cone :math:`K`, a linear transformation :math:`L`
+on the space in which :math:`K` lives, and two points :math:`e_{1}`
+and :math:`e_{2}` in the interior of :math:`K`. The players make their
+"moves" by choosing points from two strategy sets. Player one chooses
+an :math:`\bar{x}` from
+
+.. math::
+  \Delta_{1} =
+    \left\lbrace
+      x \in K\ \middle|\ \left\langle x,e_{2} \right\rangle = 1
+    \right\rbrace
+
+and player two chooses a :math:`\bar{y}` from
+
+.. math::
+  \Delta_{2} &=
+    \left\lbrace
+      y \in K\ \middle|\ \left\langle y,e_{1} \right\rangle = 1
+    \right\rbrace.
+
+That ends the turn, and player one is paid :math:`\left\langle
+L\left(\bar{x}\right),\bar{y}\right\rangle` out of player two's
+pocket. As is usual to assume in game theory, we suppose that player
+one wants to maximize his worst-case payoff, and that player two wants
+to minimize his worst-case *payout*. In other words, player one wants
+to solve the optimization problem,
+
+.. math::
+  \text{find }
+  \underset{x \in \Delta_{1}}{\max}\
+  \underset{y\in \Delta_{2}}{\min}\
+  \left\langle L\left(x\right),y \right\rangle
+
+while player two tries to (simultaneously) solve a similar problem,
+
+.. math::
+  \text{find }
+  \underset{y\in \Delta_{2}}{\min}\
+  \underset{x \in \Delta_{1}}{\max}\
+  \left\langle L\left(x\right),y \right\rangle.
+
+There is at least one pair :math:`\left(\bar{x},\bar{y}\right)` that
+solves these problems optimally, and Dunshire can find it. The optimal
+payoff, called *the value of the game*, is unique. At the moment, the
+symmetric cone :math:`K` can be either the nonnegative orthant or the
+Lorentz "ice cream" cone in :math:`\mathbb{R}^{n}`. Here are two of
+the simplest possible examples, showing off the ability to solve a
+game over both of those cones.
+
+First, we use the nonnegative orthant in :math:`\mathbb{R}^{2}`:
+
+>>> from dunshire import *
+>>> K = NonnegativeOrthant(2)
+>>> L = [[1,0],[0,1]]
+>>> e1 = [1,1]
+>>> e2 = e1
+>>> G = SymmetricLinearGame(L,K,e1,e2)
+>>> print(G.solution())
+Game value: 0.5000000
+Player 1 optimal:
+  [0.5000000]
+  [0.5000000]
+Player 2 optimal:
+  [0.5000000]
+  [0.5000000]
+
+Next we try the Lorentz ice-cream cone in :math:`\mathbb{R}^{2}`:
+
+>>> from dunshire import *
+>>> K = IceCream(2)
+>>> L = [[1,0],[0,1]]
+>>> e1 = [1,1]
+>>> e2 = e1
+>>> G = SymmetricLinearGame(L,K,e1,e2)
+>>> print(G.solution())
+Game value: 0.5000000
+Player 1 optimal:
+  [0.5000000]
+  [0.5000000]
+Player 2 optimal:
+  [0.5000000]
+  [0.5000000]
+
+(The answer when :math:`L`, :math:`e_{1}`, and :math:`e_{2}` are so
+simple is independent of the cone.)
+
 Requirements
 ------------
 
@@ -21,16 +108,15 @@ probably work too.
 Background
 ----------
 
-A linear game is a generalization of a two-person zero-sum matrix
-game~\cite{karlin, parthasarathy-raghavan,
-von_neumann-morgenstern}. Classically, such a game involves a matrix
-:math:`A \in \mathbb{R}^{n \times n}` and a set (the unit simplex) of
-"strategies" :math:`\Delta = \operatorname{conv}\left(
-\left\lbrace e_{1}, e_{2}, \ldots, e_{n} \right\} \right)` from which two
-players are free to choose. If the players choose :math:`x,y \in \Delta`
-respectively, then the game is played by evaluating :math:`y^{T}Ax` as the
-"payoff" to the first player. His payoff comes from the second
-player, so that their total sums to zero.
+A linear game is a generalization of a two-person zero-sum matrix game
+[Karlin]_. Classically, such a game involves a matrix :math:`A \in
+\mathbb{R}^{n \times n}` and a set (the unit simplex) of "strategies"
+:math:`\Delta = \operatorname{conv}\left( \left\lbrace e_{1}, e_{2},
+\ldots, e_{n} \right\} \right)` from which two players are free to
+choose. If the players choose :math:`x,y \in \Delta` respectively,
+then the game is played by evaluating :math:`y^{T}Ax` as the "payoff"
+to the first player. His payoff comes from the second player, so that
+their total sums to zero.
 
 Each player will try to maximize his payoff in this scenario,
 or—what is equivalent—try to minimize the payoff of his
@@ -76,7 +162,7 @@ case, we will pretend from now on that our cones need to be
 symmetric. This simplifies some definitions.
 
 What is a linear game?
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 In the classical setting, the interpretation of the strategies as
 probabilities results in a strategy set :math:`\Delta \subseteq