Add file formats page in docs

doc/file_formats.rst

@@ -0,0 +1,121 @@
+File formats
+============
+
+lemke reads two kinds of plain-text input files: **LCP files** and **bimatrix files**.
+
+
+Common rules
+------------
+
+Comments
+   Lines starting with ``#``, ``%`` or ``*`` are ignored. Use them for
+   notes, titles or the source of a game.
+
+   Keep in mind that only whole lines starting with these characters are ignored,
+   i.e. a ``#`` in the middle of a line does not start a comment.
+
+Spaces
+   Every item, including keywords such as ``n=`` and ``M=``,
+   must be separated from its neighbours by white space.
+
+   Extra line breaks and white spaces are ignored.
+
+Numbers
+   Entries are read as exact rational numbers. You can use integers,
+   fractions such as ``1/3``, and decimals such as ``0.33``.
+
+   Each parsed decimal is rounded (half away from zero) to a specified
+   number of decimal places, which is 4 by default.
+   This number can be set by the ``decimals`` argument
+   in the library, and the ``--decimals`` flag via the CLI.
+
+Errors
+    In case of a malformed file, an error is thrown.
+
+Examples
+    You can view the ``examples/`` directory for additional example files.
+
+
+LCP files
+---------
+
+An LCP file describes the problem
+
+.. math::
+
+   w = q + Mz, \qquad w \ge 0, \quad z \ge 0, \quad z^\top w = 0,
+
+together with a covering vector :math:`d` for Lemke's algorithm, where
+:math:`M` is an :math:`n \times n` matrix and :math:`q` and :math:`d` are
+vectors of length :math:`n`.
+
+Structure
+~~~~~~~~~
+
+1. The file starts with the keyword ``n=`` followed by the dimension
+   :math:`n`, for example ``n= 5``. The keyword and the number are separate
+   words, so write a space between them.
+2. The keywords ``M=``, ``q=`` and ``d=`` follow, each introducing its data.
+   They may appear in any order, but each of them must appear.
+
+   - ``M=`` is followed by :math:`n \cdot n` numbers, the entries of
+     :math:`M` row by row.
+   - ``q=`` and ``d=`` are each followed by :math:`n` numbers.
+
+Example
+~~~~~~~
+
+A simple 2x2 LCP:
+
+.. code-block:: text
+
+   # a 2x2 LCP
+
+   n= 2
+   M= 2/3 1.2
+      1 2
+   q= -1 -1
+   d= 1 1
+
+
+Bimatrix files
+--------------
+
+A bimatrix file describes a two-player game in strategic form. The row
+player has :math:`m` pure strategies, the column player has :math:`n`, and
+the game is given by two payoff matrices :math:`A` and :math:`B`, each of
+size :math:`m \times n`.
+
+Structure
+~~~~~~~~~
+
+1. The file starts with the two integers :math:`m` and :math:`n`, with no
+   keywords.
+2. Next come the :math:`m \cdot n` payoffs of the row player (matrix
+   :math:`A`), row by row.
+3. Last come the :math:`m \cdot n` payoffs of the column player (matrix
+   :math:`B`), row by row.
+
+Entry :math:`(i, j)` of each matrix is the payoff to that player when the row
+player chooses strategy :math:`i` and the column player chooses strategy
+:math:`j`.
+
+Example
+~~~~~~~
+
+A 2×2 coordination game, "Battle of the Sexes":
+
+.. code-block:: text
+
+   # Battle of the Sexes
+
+   # m n
+   2 2
+
+   # row player's payoffs A
+   3 0
+   0 2
+
+   # column player's payoffs B
+   2 0
+   0 3

doc/index.rst

@@ -16,3 +16,4 @@ Installation
    :maxdepth: 2
 
    api
+   file_formats

examples/game

@@ -7,4 +7,4 @@
 # B=
 2 0
 0 7
-# max= 4, min= 0
+# max= 7, min= 0