This is GameTheory.info, produced by Macaulay2, version 1.25.11

GameTheory -- a package for computing equilibria in game theory
***************************************************************

Description
===========

Game Theory is a package for several equilibrium concepts in game theory. It
constructs the algebro-geometric and combinatorial models for Nash, correlated,
dependency, and conditional independence equilibria. The latter three notions
of equilibria are all generalizations of Nash equilibria. An $n$-player game in
normal form is defined by $n$-tensors of format $d_1 \times d_2 \times \cdots
\times d_n$, where $d_i$ is the number of pure strategies of player $i$. The
entry $\{j_1, j_2, \cdots, j_n\}$ of the $i$-th (payoff) tensor for player $i$
is the payoff when player $1$ chooses strategy $j_1$, player $2$ chooses
strategy $j_2$, and so on. One can define a specific game or a random game,
e.g., a list with random tensors.

+----------------------------------------------------------------------------+
|i1 : A = zeroTensor {2,2};                                                  |
+----------------------------------------------------------------------------+
|i2 : B = zeroTensor {2,2};                                                  |
+----------------------------------------------------------------------------+
|i3 : A#{0,0} = 3;  A#{0,1} = 0;  A#{1,0} = 0;  A#{1,1} = 2;                 |
+----------------------------------------------------------------------------+
|i7 : B#{0,0} = 2;  B#{0,1} = 0;  B#{1,0} = 0;  B#{1,1} = 3;                 |
+----------------------------------------------------------------------------+
|i11 : X = {randomTensor {2,2,2}, randomTensor {2,2,2}, randomTensor {2,2,2}}|
|                                                                            |
|o11 = {Tensor{...11...}, Tensor{...11...}, Tensor{...11...}}                |
|                                                                            |
|o11 : List                                                                  |
+----------------------------------------------------------------------------+
|i12 : randomGame {2,2,2}                                                    |
|                                                                            |
|o12 = {Tensor{...11...}, Tensor{...11...}, Tensor{...11...}}                |
|                                                                            |
|o12 : List                                                                  |
+----------------------------------------------------------------------------+

The notion of Nash equilibria is one of the central topics in game theory.
See nashEquilibriumIdeal, computes a
square system of $d_1 + \cdots + d_n$ polynomials that algebraically model the
set of totally mixed Nash equilibria. In the case where the dimension of this
ideal is zero (commonly referred to as a generic game), one can use the mixed
volume of the Newton polytopes of each polynomial in the system to obtain an
upper bound on the number of totally mixed Nash equilibria. The list of these
Newton polytopes is provided by deltaList. The
mixed volume of these polytopes equals the number of certain block
derangements. The method numberTMNE, is typically
faster than mixedVolume (Polyhedra), in this case.

+-----------------------------------------------------------------------------+
|i13 : NR = nashEquilibriumRing X;                                            |
+-----------------------------------------------------------------------------+
|i14 : I = nashEquilibriumIdeal(NR,X)                                         |
|                                                                             |
|               67                  1                 31                      |
|o14 = ideal (- --p      p       - --p      p       - --p      p       +      |
|               18 {1, 0} {2, 0}   20 {1, 1} {2, 0}   20 {1, 0} {2, 1}        |
|      -----------------------------------------------------------------------|
|       7                  43                 19                 39           |
|      --p      p      , - --p      p       - --p      p       + --p      p   |
|      12 {1, 1} {2, 1}     7 {0, 0} {2, 0}   20 {0, 1} {2, 0}    7 {0, 0} {2,|
|      -----------------------------------------------------------------------|
|           13                  35                  1                 17      |
|         + --p      p      , - --p      p       - --p      p       - --p     |
|      1}   63 {0, 1} {2, 1}     9 {0, 0} {1, 0}   24 {0, 1} {1, 0}    2 {0,  |
|      -----------------------------------------------------------------------|
|                  23                                                         |
|        p       - --p      p      , p       + p       - 1, p       + p       |
|      0} {1, 1}    5 {0, 1} {1, 1}   {0, 0}    {0, 1}       {1, 0}    {1, 1} |
|      -----------------------------------------------------------------------|
|      - 1, p       + p       - 1)                                            |
|            {2, 0}    {2, 1}                                                 |
|                                                                             |
|o14 : Ideal of NR                                                            |
+-----------------------------------------------------------------------------+
|i15 : dim I                                                                  |
|                                                                             |
|o15 = 0                                                                      |
+-----------------------------------------------------------------------------+
|i16 : degree I                                                               |
|                                                                             |
|o16 = 2                                                                      |
+-----------------------------------------------------------------------------+
|i17 : D = deltaList {2,2,2}                                                  |
|                                                                             |
|o17 = {Polyhedron{...1...}, Polyhedron{...1...}, Polyhedron{...1...}}        |
|                                                                             |
|o17 : List                                                                   |
+-----------------------------------------------------------------------------+
|i18 : mixedVolume D                                                          |
|                                                                             |
|o18 = 2                                                                      |
|                                                                             |
|o18 : QQ                                                                     |
+-----------------------------------------------------------------------------+
|i19 : blockDerangements {2,2,2}                                              |
|                                                                             |
|o19 = {{set {(2, 0)}, set {(0, 0)}, set {(1, 0)}}, {set {(1, 0)}, set {(2,   |
|      -----------------------------------------------------------------------|
|      0)}, set {(0, 0)}}}                                                    |
|                                                                             |
|o19 : List                                                                   |
+-----------------------------------------------------------------------------+
|i20 : numberTMNE {2,2,2}                                                     |
|                                                                             |
|o20 = 2                                                                      |
+-----------------------------------------------------------------------------+

The set of correlated equilibria of a game forms a convex polytope inside the
(probability) simplex which is the standard simplex of dimension $d_1 \cdots
d_n -1$. Thus, the variables are taken from probabilityRing.
In particular, the map from nashEquilibriumRing,
to probabilityRing, is
the Segre embedding.

+--------------------------------------------------+
|i21 : CE1 = correlatedEquilibria {A, B}           |
|                                                  |
|o21 = CE1                                         |
|                                                  |
|o21 : Polyhedron                                  |
+--------------------------------------------------+
|i22 : dim CE1                                     |
|                                                  |
|o22 = 3                                           |
+--------------------------------------------------+
|i23 : vertices CE1                                |
|                                                  |
|o23 = | 1 0 2/7 3/8 6/25 |                        |
|      | 0 0 3/7 0   9/25 |                        |
|      | 0 0 0   1/4 4/25 |                        |
|      | 0 1 2/7 3/8 6/25 |                        |
|                                                  |
|               4       5                          |
|o23 : Matrix QQ  <-- QQ                           |
+--------------------------------------------------+
|i24 : facets CE1                                  |
|                                                  |
|o24 = (| 0  -1 0  0  |, 0)                        |
|       | -3 2  0  0  |                            |
|       | 0  0  -1 0  |                            |
|       | -2 0  3  0  |                            |
|       | 0  2  0  -3 |                            |
|       | 0  0  3  -2 |                            |
|                                                  |
|o24 : Sequence                                    |
+--------------------------------------------------+
|i25 : CE2 = correlatedEquilibria randomGame{2,2,2}|
|                                                  |
|o25 = CE2                                         |
|                                                  |
|o25 : Polyhedron                                  |
+--------------------------------------------------+
|i26 : dim CE2                                     |
|                                                  |
|o26 = 7                                           |
+--------------------------------------------------+

The algebro-geometric model of dependency equilibria is called Spohn variety.
Its defining ideal is given by rank one conditions on Spohn matrices. One can
also define Konstanz matrices which is crucial to understand the projection of
dependency equilibria to the payoff region.

+-----------------------------------------------------------------------------+
|i27 : PR = probabilityRing {2,2,2};                                          |
+-----------------------------------------------------------------------------+
|i28 : X = randomGame {2,2,2};                                                |
+-----------------------------------------------------------------------------+
|i29 : spohnMatrices(PR,X)                                                    |
|                                                                             |
|o29 = {| p_{0, 0, 0}+p_{0, 0, 1}+p_{0, 1, 0}+p_{0, 1, 1} 5/3p_{0, 0,         |
|       | p_{1, 0, 0}+p_{1, 0, 1}+p_{1, 1, 0}+p_{1, 1, 1} 6/5p_{1, 0,         |
|      -----------------------------------------------------------------------|
|      0}+3p_{0, 0, 1}+8/7p_{0, 1, 0}+6/5p_{0, 1, 1}  |, | p_{0, 0, 0}+p_{0,  |
|      0}+6/7p_{1, 0, 1}+6p_{1, 1, 0}+3/10p_{1, 1, 1} |  | p_{0, 1, 0}+p_{0,  |
|      -----------------------------------------------------------------------|
|      0, 1}+p_{1, 0, 0}+p_{1, 0, 1}                                          |
|      1, 1}+p_{1, 1, 0}+p_{1, 1, 1}                                          |
|      -----------------------------------------------------------------------|
|      9/4p_{0, 0, 0}+1/3p_{0, 0, 1}+1/2p_{1, 0, 0}+1/3p_{1, 0, 1}  |, | p_{0,|
|      3/10p_{0, 1, 0}+3/8p_{0, 1, 1}+1/2p_{1, 1, 0}+8/7p_{1, 1, 1} |  | p_{0,|
|      -----------------------------------------------------------------------|
|      0, 0}+p_{0, 1, 0}+p_{1, 0, 0}+p_{1, 1, 0} 5/7p_{0, 0,                  |
|      0, 1}+p_{0, 1, 1}+p_{1, 0, 1}+p_{1, 1, 1} 3/2p_{0, 0,                  |
|      -----------------------------------------------------------------------|
|      0}+7p_{0, 1, 0}+6/5p_{1, 0, 0}+1/5p_{1, 1, 0}   |}                     |
|      1}+5/3p_{0, 1, 1}+3/2p_{1, 0, 1}+5/4p_{1, 1, 1} |                      |
|                                                                             |
|o29 : List                                                                   |
+-----------------------------------------------------------------------------+
|i30 : spohnIdeal(PR,X);                                                      |
|                                                                             |
|o30 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i31 : konstanzMatrix(PR,X)                                                   |
|                                                                             |
|o31 = | k_0-5/3 k_0-3   k_0-8/7  k_0-6/5 0       0       0       0        |  |
|      | 0       0       0        0       k_0-6/5 k_0-6/7 k_0-6   k_0-3/10 |  |
|      | k_1-9/4 k_1-1/3 0        0       k_1-1/2 k_1-1/3 0       0        |  |
|      | 0       0       k_1-3/10 k_1-3/8 0       0       k_1-1/2 k_1-8/7  |  |
|      | k_2-5/7 0       k_2-7    0       k_2-6/5 0       k_2-1/5 0        |  |
|      | 0       k_2-3/2 0        k_2-5/3 0       k_2-3/2 0       k_2-5/4  |  |
|                                                                             |
|                         6                 8                                 |
|o31 : Matrix (PR[k ..k ])  <-- (PR[k ..k ])                                  |
|                  0   2             0   2                                    |
+-----------------------------------------------------------------------------+

The algebro-geometric model of conditional independence equilibria is obtained
by intersecting the Spohn variety with the conditional independence model of a
given set of conditional independence statements, followed by the removal of
certain components. The set of conditional independence statements can be
generated via graphical models.

+-----------------------------------------------------------------------------+
|i32 : G1 = graph ({}, Singletons => {1,2,3});                                |
+-----------------------------------------------------------------------------+
|i33 : G2 = graph ({{1,2}}, Singletons => {3});                               |
+-----------------------------------------------------------------------------+
|i34 : I1 = spohnCI(PR,X,G1);                                                 |
|                                                                             |
|o34 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i35 : I2 = spohnCI(PR,X,G2);                                                 |
|                                                                             |
|o35 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i36 : J = probabilitySumIdeal(PR)                                            |
|                                                                             |
|o36 = ideal(p          + p          + p          + p          + p          + |
|             {0, 0, 0}    {0, 0, 1}    {0, 1, 0}    {0, 1, 1}    {1, 0, 0}   |
|      -----------------------------------------------------------------------|
|      p          + p          + p          - 1)                              |
|       {1, 0, 1}    {1, 1, 0}    {1, 1, 1}                                   |
|                                                                             |
|o36 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i37 : J1 = I1 + J;                                                           |
|                                                                             |
|o37 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i38 : J2 = I1 + J;                                                           |
|                                                                             |
|o38 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+

Acknowledgement
===============

We thank Ben Hollering (see https://sites.google.com/view/benhollering ) and
Mahrud Sayrafi (see https://sites.google.com/view/mahrud ) for their support
during the Macaulay2 in the Sciences Workshop (see
https://www.mis.mpg.de/de/events/series/macaulay2-in-the-sciences ) where the
development of this package began.

Contributors
============

The following people have generously contributed their time and effort to this
project: Luca Sodomaco (see https://sites.google.com/view/luca-sodomaco/home ).

References
==========

This package is based on the following papers:

- Nash Equilibria: [H. Abo, I. Portakal, and L. Sodomaco: A vector bundle
approach to Nash equilibria (see https://arxiv.org/abs/2504.03456 )] available
on arXiv.

- Correlated Equilibria: [M.-C. Brandenburg, B. Hollering, I. Portakal:
Combinatorics of Correlated Equilibria (see
https://www.tandfonline.com/doi/full/10.1080/10586458.2024.2340000 )]
Experimental Mathematics, 2024.

- Dependency Equilibria: [I. Portakal and B. Sturmfels: Geometry of dependency
equilibria (see https://www.openstarts.units.it/server/api/core/bitstreams/
12c8c6f4-d535-49e3-b6a5-d4f12c331b0f/content )] published in Rend. Istit. Mat.
Univ. Trieste 54 (Art. No. 5), 2022, 13, 2022.

- Conditional Independence Equilibria: [I. Portakal and J. Sendra-Arranz: Game
theory of undirected graphical models (see
https://www.sciencedirect.com/science/article/pii/S0021869324006707 )] Journal
of Algebra, Volume 666, 2025.

Caveat
======

GameTheory uses Polyhedra.m2 for the methods of correlated equilibria and
GraphicalModels.m2 for the methods of conditional independence equilibria.
Throughout the package, we followed Macaulay2's convention of zero-based
indexing. This can be seen e.g., in the methods of nashEquilibriumRing,
and probabilityRing. In
particular, for an $n$-player game, the players are labeled $0, \ldots, n-1$,
and if player $i$ has $d_i$ pure strategies, they are labeled $0, \ldots,
d_i-1$.

Authors
=======

  * Erin Connelly (see https://erinconnelly96.github.io/ )
    <erin.connelly@uni-osnabrueck.de>
  * Vincenzo Galgano (see https://sites.google.com/view/vincenzogalgano )
    <galgano@mpi-cbg.de>
  * Zhuang He (see https://sites.google.com/view/hezhuang/home )
    <zhuang.he@unito.it>
  * Lars Kastner (see https://lkastner.github.io ) <kastner@math.tu-berlin.de>
  * Giacomo Maletto (see https://www.kth.se/profile/gmaletto )
    <gmaletto@kth.se>
  * Elke Neuhaus (see https://sites.google.com/view/elkeneuhaus )
    <elke@neuhaus-rp.de>
  * Irem Portakal (see https://www.irem-portakal.de ) <mail@irem-portakal.de>
  * Hannah Tillmann-Morris (see
    https://sites.google.com/view/hannah-tillmann-morris )
    <tillmann@mis.mpg.de>
  * Chenyang Zhao (see https://www.felixzhao.com/ ) <cz2922@ic.ac.uk>

Version
=======

This documentation describes version 1.0 of GameTheory, released May, 2025.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{GameTheorySource,                                                      |
|  title = {{GameTheory: computing equilibria in game theory. Version~1.0}},  |
|  author = {Erin Connelly and Vincenzo Galgano and Zhuang He and Lars Kastner|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|-----------------------------------------------------------------------------|
|and Giacomo Maletto and Elke Neuhaus and Irem Portakal and Hannah            |
|-----------------------------------------------------------------------------|
|Tillmann-Morris and Chenyang Zhao},                                          |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * Tensor -- a mutable hash table representing a tensor
  * Functions and commands
      * assemblePlayeriPolynomials -- get
        all incentive constraint polynomials for a player
      * assemblePolynomial -- compute incentive
        constraint polynomial for deviation
      * "blockDerangements" -- see blockDerangements(List),
        -- compute the block derangements
      * ciIdeal -- the ideal of a list of conditional
        independence statements
      * correlatedEquilibria -- compute the
        correlated equilibrium polytope for a game
      * "deltaList" -- see deltaList(List), --
        generate the list of Newton polytopes for a generic game
      * enumerateTensorIndices -- generate index
        tuples for a tensor with given dimensions
      * getVariableToIndexset -- retrieve a
        polynomial ring variable by its index tuple
      * indexset -- get the list of index tuples of a tensor
      * intersectWithCImodel -- ideal of the
        intersection of a given variety with the conditional independence model
      * konstanzMatrix -- construct the Konstanz matrix
        of a given game
      * mapToMarkovRing -- ring isomorphism from the
        given probabilityRing to the corresponding markovRing
      * mapToProbabilityRing -- ring isomorphism
        to the given probabilityRing from the corresponding markovRing
      * "nashEquilibriumIdeal" -- see nashEquilibriumIdeal(Ring,List),
        -- make the Nash Equilibrium
        ideal
      * "nashEquilibriumRing" -- see nashEquilibriumRing(List),
        -- define the Nash Equilibrium ring
      * "numberTMNE" -- see numberTMNE(List), --
        compute the maximum number of totally mixed Nash equilibria for a
        generic game
      * probabilityRing -- ring of probability
        distributions of a game indexed by ordered multi-indices
      * probabilitySumIdeal -- ideal enforcing that
        a probability distribution sums to 1
      * randomGame -- construct a game of a given format
        with arbitrary payoffs
      * randomTensor -- construct a tensor with random
        entries from a given ring
      * slice -- extract a slice of a tensor
      * spohnCI -- ideal of the Spohn conditional independence
        (CI) variety
      * spohnIdeal -- compute the ideal of the Spohn variety
        of a given game
      * spohnMatrices -- compute the list of Spohn
        matrices of a given game
      * toMarkovRing -- ring of joint probability
        distributions created with the markovRing function from the
        GraphicalModels package
      * zeroTensor -- construct a tensor with zero entries
        from a given ring.
  * Methods
      * "assemblePlayeriPolynomials(Ring,Tensor,ZZ)" -- see
        assemblePlayeriPolynomials, -- get all
        incentive constraint polynomials for a player
      * "assemblePolynomial(Ring,Tensor,List)" -- see assemblePolynomial,
        -- compute incentive constraint polynomial for
        deviation
      * blockDerangements(List) -- compute
        the block derangements
      * "ciIdeal(Ring,Graph)" -- see ciIdeal, -- the ideal of a
        list of conditional independence statements
      * "ciIdeal(Ring,Graph,List)" -- see ciIdeal, -- the ideal
        of a list of conditional independence statements
      * "ciIdeal(Ring,List)" -- see ciIdeal, -- the ideal of a
        list of conditional independence statements
      * "ciIdeal(Ring,List,List)" -- see ciIdeal, -- the ideal
        of a list of conditional independence statements
      * coefficientRing(Tensor) (missing documentation)
      * "correlatedEquilibria(List)" -- see correlatedEquilibria,
        -- compute the correlated equilibrium polytope
        for a game
      * deltaList(List) -- generate the list of
        Newton polytopes for a generic game
      * "enumerateTensorIndices(List)" -- see enumerateTensorIndices,
        -- generate index tuples for a tensor with
        given dimensions
      * "enumerateTensorIndices(ZZ)" -- see enumerateTensorIndices,
        -- generate index tuples for a tensor with
        given dimensions
      * format(Tensor) (missing documentation)
      * "getVariableToIndexset(Ring,List)" -- see getVariableToIndexset,
        -- retrieve a polynomial ring variable by its
        index tuple
      * "indexset(Tensor)" -- see indexset, -- get the list of
        index tuples of a tensor
      * "intersectWithCImodel(Ideal,Graph)" -- see intersectWithCImodel,
        -- ideal of the intersection of a given variety
        with the conditional independence model
      * "intersectWithCImodel(Ideal,Graph,List)" -- see
        intersectWithCImodel, -- ideal of the
        intersection of a given variety with the conditional independence model
      * "intersectWithCImodel(Ideal,List)" -- see intersectWithCImodel,
        -- ideal of the intersection of a given variety
        with the conditional independence model
      * "intersectWithCImodel(Ideal,List,List)" -- see
        intersectWithCImodel, -- ideal of the
        intersection of a given variety with the conditional independence model
      * konstanzMatrix(Ring,List) (missing documentation)
      * "mapToMarkovRing(Ring)" -- see mapToMarkovRing,
        -- ring isomorphism from the given probabilityRing to the corresponding
        markovRing
      * "mapToProbabilityRing(Ring)" -- see mapToProbabilityRing,
        -- ring isomorphism to the given probabilityRing
        from the corresponding markovRing
      * nashEquilibriumIdeal(Ring,List)
        -- make the Nash Equilibrium
        ideal
      * nashEquilibriumRing(List), --
        define the Nash Equilibrium ring
      * numberTMNE(List) -- compute the maximum
        number of totally mixed Nash equilibria for a generic game
      * "probabilityRing(List)" -- see probabilityRing,
        -- ring of probability distributions of a game indexed by ordered
        multi-indices
      * "probabilitySumIdeal(Ring)" -- see probabilitySumIdeal,
        -- ideal enforcing that a probability distribution
        sums to 1
      * randomGame(List) (missing documentation)
      * "randomTensor(List)" -- see randomTensor, --
        construct a tensor with random entries from a given ring
      * "randomTensor(Ring,List)" -- see randomTensor, --
        construct a tensor with random entries from a given ring
      * "slice(Tensor,List,List)" -- see slice, -- extract a slice
        of a tensor
      * "spohnCI(Ring,List,Graph)" -- see spohnCI, -- ideal of
        the Spohn conditional independence (CI) variety
      * "spohnCI(Ring,List,Graph,List)" -- see spohnCI, -- ideal
        of the Spohn conditional independence (CI) variety
      * "spohnCI(Ring,List,List)" -- see spohnCI, -- ideal of
        the Spohn conditional independence (CI) variety
      * "spohnCI(Ring,List,List,List)" -- see spohnCI, -- ideal
        of the Spohn conditional independence (CI) variety
      * spohnIdeal(Ring,List) (missing documentation)
      * spohnMatrices(Ring,List) (missing documentation)
      * "toMarkovRing(Ring)" -- see toMarkovRing, -- ring
        of joint probability distributions created with the markovRing function
        from the GraphicalModels package
      * "zeroTensor(List)" -- see zeroTensor, -- construct a
        tensor with zero entries from a given ring.
      * "zeroTensor(Ring,List)" -- see zeroTensor, --
        construct a tensor with zero entries from a given ring.
  * Symbols
      * KonstanzVariableName (missing documentation)
      * ProbabilityVariableName (missing documentation)

For the programmer
==================

The object GameTheory, is a package (Macaulay2Doc),
defined in GameTheory.m2.

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:914:0.

assemblePlayeriPolynomials -- get all incentive constraint polynomials for a player
***********************************************************************************

  * Usage:
        assemblePlayeriPolynomials(PR, Xi, i)
  * Inputs:
      * PR, a ring (Macaulay2Doc), Polynomial ring of
        probabilities.
      * Xi, an instance of the type Tensor, Tensor of strategy
        probabilities.
      * i, an integer (Macaulay2Doc), The player index.
  * Outputs:
      * a list (Macaulay2Doc), A list of polynomials corresponding
        to the player's deviation constraints.

Description
===========

For a given player $i$, this method computes all incentive constraint
polynomials $\forall k,l \in [d_i]$, representing deviations from strategy $k$
to $l$.

+---------------------------------------------------------+
|i1 : R = QQ[p_{0,0}, p_{0,1}, p_{1,0}, p_{1,1}];         |
+---------------------------------------------------------+
|i2 : Xi = randomTensor(QQ, {2,2});                       |
+---------------------------------------------------------+
|i3 : assemblePlayeriPolynomials(R, Xi, 0)                |
|                                                         |
|         15          1           15          1           |
|o3 = {0, --p       + -p      , - --p       - -p      , 0}|
|          4 {0, 0}   2 {0, 1}     4 {1, 0}   2 {1, 1}    |
|                                                         |
|o3 : List                                                |
+---------------------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * assemblePolynomial -- compute incentive
    constraint polynomial for deviation
  * correlatedEquilibria -- compute the correlated
    equilibrium polytope for a game

Ways to use assemblePlayeriPolynomials:
=======================================

  * "assemblePlayeriPolynomials(Ring,Tensor,ZZ)"

For the programmer
==================

The object assemblePlayeriPolynomials, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1254:0.

assemblePolynomial -- compute incentive constraint polynomial for deviation
***************************************************************************

  * Usage:
        assemblePolynomial(PR, Xi, {i,k,l})
  * Inputs:
      * PR, a ring (Macaulay2Doc), Polynomial ring of strategy
        probabilities.
      * Xi, an instance of the type Tensor, Tensor of strategy
        probabilities.
      * {i, k, l}, a list (Macaulay2Doc), A triple where: - $i$ is
        the player index, - $k$ is the current strategy, - $l$ is the deviating
        strategy.
  * Outputs:
      * a ring element (Macaulay2Doc), A polynomial
        representing the incentive constraint for player $i$ deviating from $k$
        to $l$.

Description
===========

This function computes a linear inequality encoding the condition for a
correlated equilibrium: the expected utility from playing $k$ should be no less
than from playing $l$.

+------------------------------------------------+
|i1 : R = QQ[p_{0,0}, p_{0,1}, p_{1,0}, p_{1,1}];|
+------------------------------------------------+
|i2 : Xi = randomTensor(QQ, {2,2});              |
+------------------------------------------------+
|i3 : assemblePolynomial(R, Xi, {0,0,1})         |
|                                                |
|     15          1                              |
|o3 = --p       + -p                             |
|      4 {0, 0}   2 {0, 1}                       |
|                                                |
|o3 : R                                          |
+------------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * getVariableToIndexset -- retrieve a
    polynomial ring variable by its index tuple
  * assemblePlayeriPolynomials -- get all
    incentive constraint polynomials for a player

Ways to use assemblePolynomial:
===============================

  * "assemblePolynomial(Ring,Tensor,List)"

For the programmer
==================

The object assemblePolynomial, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1217:0.

blockDerangements(List) -- compute the block derangements
*********************************************************

  * Function: blockDerangements,
  * Usage:
        blockDerangements D
  * Inputs:
      * D, a list (Macaulay2Doc), a list of integers representing
        the format of the game
  * Outputs:
      * a list (Macaulay2Doc), a list of block derangements with
        respect to D.

Description
===========

Given a partition $\{F_0,\ldots,F_{n-1}\}$ of a finite set $F$, a block
derangement of $F$ with respect to $\{F_0,\ldots,F_{n-1}\}$ is a permutation
$P\colon F\to F$ of $F$ such that $P(F_i)\cap F_i=\emptyset$ for every
$i\in\{0,\ldots,n-1\}$.

The function considers the input $D=(d_0,\ldots,d_{n-1})$, defines the set
$F=F_0\cup\cdots\cup F_{n-1}$, where $F_i=\{(i,j)\mid j\in\{0,\ldots,d_i-2\}\}$
for every $i\in\{0,\ldots,n-1\}$, and computes the set of permutations of F.
Then, it creates an empty list BD, and for each permutation $P$, if $P(F_i)\cap
F_i=\emptyset$ for every $i\in\{0,\ldots,n-1\}$, then $P$ is added to the list
BD. The function returns the list BD.

The number of elements of BD corresponds to the maximum number of totally mixed
Nash equilibria of a generic game of a given format.

+---------------------------------------------------------------------+
|i1 : D = {3,3,3};                                                    |
+---------------------------------------------------------------------+
|i2 : BD = blockDerangements D;                                       |
+---------------------------------------------------------------------+
|i3 : netList BD                                                      |
|                                                                     |
|     +--------------------+--------------------+--------------------+|
|o3 = |set {(2, 1), (1, 0)}|set {(0, 0), (2, 0)}|set {(0, 1), (1, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(2, 0), (1, 1)}|set {(2, 1), (0, 0)}|set {(1, 0), (0, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(2, 1), (1, 0)}|set {(0, 1), (2, 0)}|set {(0, 0), (1, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(2, 0), (1, 1)}|set {(2, 1), (0, 1)}|set {(0, 0), (1, 0)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(2, 1), (2, 0)}|set {(0, 0), (0, 1)}|set {(1, 0), (1, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(1, 0), (2, 0)}|set {(2, 1), (0, 0)}|set {(0, 1), (1, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(2, 1), (1, 1)}|set {(0, 0), (2, 0)}|set {(1, 0), (0, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(1, 0), (2, 0)}|set {(2, 1), (0, 1)}|set {(0, 0), (1, 1)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(2, 1), (1, 1)}|set {(0, 1), (2, 0)}|set {(0, 0), (1, 0)}||
|     +--------------------+--------------------+--------------------+|
|     |set {(1, 0), (1, 1)}|set {(2, 1), (2, 0)}|set {(0, 0), (0, 1)}||
|     +--------------------+--------------------+--------------------+|
+---------------------------------------------------------------------+

See also
========

  * deltaList -- generate the list of Newton
    polytopes for a generic game
  * numberTMNE -- compute the maximum number of
    totally mixed Nash equilibria for a generic game

Ways to use this method:
========================

  * blockDerangements(List) -- compute the
    block derangements
-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1494:0.

ciIdeal -- the ideal of a list of conditional independence statements
*********************************************************************

  * Usage:
        ciIdeal (R, Stmts)
        ciIdeal (R, G)
        ciIdeal (R, Stmts, PlayerNames)
        ciIdeal (R, G, PlayerNames)
  * Inputs:
      * R, a ring (Macaulay2Doc), must be created using
        probabilityRing
      * Stmts, a list (Macaulay2Doc), the list of conditional
        independence statements
      * G, a graph (Graphs), the graph modelling the conditional
        dependencies between players
      * PlayerNames, a list (Macaulay2Doc), the ordered list of
        players - the names of the random variables in the conditional
        independence statements or vertices of the graph. If PlayerNames is
        omitted, the players (or the vertices of G) are assumed to be labelled
        1..n.
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal in R of conditional
        independence relations

Description
===========

ciIdeal computes the ideal of a list of conditional independence statements.
The input can be the list of conditional independence statements itself, or a
graph modelling the conditional dependencies between players. This method is
the same as conditionalIndependenceIdeal (GraphicalModels),
from GameTheory.m2, included
here for convenience and compatibility with this package.

A single conditional independence statement is a list consisting of three
disjoint lists of indices for random variables, e.g. $\{ \{1,2\},\{4\}, \{3\}
\}$ which represents the conditional independence statement "$(X_1, X_2)$ is
conditionally independent of $X_4$ given $X_3$". Given an undirected graph $G$,
the conditional independence statements are produced via the globalMarkov
function from the GraphicalModels package. A global Markov statement for $G$ is
a list $\{A, B, C\}$ of three disjoint lists of vertices of $G$, where the
subset $C$ separates the subset $A$ from the subset $B$ in the graph $G$.

The output is an ideal of the given ring PR, which must be created using the
probabilityRing function. This function computes the ideal using the
conditionalIndependenceIdeal (GraphicalModels),
function from the GraphicalModels package, then maps it to an ideal of PR via
the mapToProbabilityRing function.

+-----------------------------------------------------------------------------+
|i1 : FF = ZZ/32003;                                                          |
+-----------------------------------------------------------------------------+
|i2 : d = {2,3,2};                                                            |
+-----------------------------------------------------------------------------+
|i3 : PR = probabilityRing (d, CoefficientRing => FF);                        |
+-----------------------------------------------------------------------------+
|i4 : G = graph ({}, Singletons => {1,2,3});                                  |
+-----------------------------------------------------------------------------+
|i5 : I = ciIdeal (PR, G)                                                     |
|                                                                             |
|o5 = ideal (- p         p          + p         p         , - p         p     |
|               {0, 0, 1} {1, 0, 0}    {0, 0, 0} {1, 0, 1}     {0, 1, 0} {1,  |
|     ------------------------------------------------------------------------|
|           + p         p         , - p         p          + p         p      |
|     0, 0}    {0, 0, 0} {1, 1, 0}     {0, 1, 0} {1, 0, 1}    {0, 0, 1} {1, 1,|
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     0}     {0, 1, 1} {1, 0, 0}    {0, 0, 0} {1, 1, 1}     {0, 1, 1} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     1}    {0, 0, 1} {1, 1, 1}     {0, 1, 1} {1, 1, 0}    {0, 1, 0} {1, 1,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 2, 0} {1, 0, 0}    {0, 0, 0} {1, 2, 0}     {0, 2, 0} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     1}    {0, 0, 1} {1, 2, 0}     {0, 2, 0} {1, 1, 0}    {0, 1, 0} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     0}     {0, 2, 0} {1, 1, 1}    {0, 1, 1} {1, 2, 0}     {0, 2, 1} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 0, 0} {1, 2, 1}     {0, 2, 1} {1, 0, 1}    {0, 0, 1} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 2, 1} {1, 1, 0}    {0, 1, 0} {1, 2, 1}     {0, 2, 1} {1, 1,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     1}    {0, 1, 1} {1, 2, 1}     {0, 2, 1} {1, 2, 0}    {0, 2, 0} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 0, 1} {0, 1, 0}    {0, 0, 0} {0, 1, 1}     {0, 1, 0} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 0, 0} {1, 1, 0}     {0, 1, 1} {1, 0, 0}    {0, 0, 1} {1, 1,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     0}     {0, 1, 0} {1, 0, 1}    {0, 0, 0} {1, 1, 1}     {0, 1, 1} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     1}    {0, 0, 1} {1, 1, 1}     {1, 0, 1} {1, 1, 0}    {1, 0, 0} {1, 1,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 0, 1} {0, 2, 0}    {0, 0, 0} {0, 2, 1}     {0, 2, 0} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 0, 0} {1, 2, 0}     {0, 2, 1} {1, 0, 0}    {0, 0, 1} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     0}     {0, 2, 0} {1, 0, 1}    {0, 0, 0} {1, 2, 1}     {0, 2, 1} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     1}    {0, 0, 1} {1, 2, 1}     {1, 0, 1} {1, 2, 0}    {1, 0, 0} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 1, 1} {0, 2, 0}    {0, 1, 0} {0, 2, 1}     {0, 2, 0} {1, 1,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 1, 0} {1, 2, 0}     {0, 2, 1} {1, 1, 0}    {0, 1, 1} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     0}     {0, 2, 0} {1, 1, 1}    {0, 1, 0} {1, 2, 1}     {0, 2, 1} {1, 1,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     1}    {0, 1, 1} {1, 2, 1}     {1, 1, 1} {1, 2, 0}    {1, 1, 0} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 0, 1} {0, 1, 0}    {0, 0, 0} {0, 1, 1}     {0, 0, 1} {0, 2,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 0, 0} {0, 2, 1}     {0, 1, 1} {0, 2, 0}    {0, 1, 0} {0, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 0, 1} {1, 0, 0}    {0, 0, 0} {1, 0, 1}     {0, 1, 1} {1, 0,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 1, 0} {1, 0, 1}     {0, 2, 1} {1, 0, 0}    {0, 2, 0} {1, 0,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 0, 1} {1, 1, 0}    {0, 0, 0} {1, 1, 1}     {0, 1, 1} {1, 1,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 1, 0} {1, 1, 1}     {0, 2, 1} {1, 1, 0}    {0, 2, 0} {1, 1,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {1, 0, 1} {1, 1, 0}    {1, 0, 0} {1, 1, 1}     {0, 0, 1} {1, 2,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {0, 0, 0} {1, 2, 1}     {0, 1, 1} {1, 2, 0}    {0, 1, 0} {1, 2,   |
|     ------------------------------------------------------------------------|
|       , - p         p          + p         p         , - p         p        |
|     1}     {0, 2, 1} {1, 2, 0}    {0, 2, 0} {1, 2, 1}     {1, 0, 1} {1, 2,  |
|     ------------------------------------------------------------------------|
|        + p         p         , - p         p          + p         p         |
|     0}    {1, 0, 0} {1, 2, 1}     {1, 1, 1} {1, 2, 0}    {1, 1, 0} {1, 2,   |
|     ------------------------------------------------------------------------|
|       )                                                                     |
|     1}                                                                      |
|                                                                             |
|o5 : Ideal of PR                                                             |
+-----------------------------------------------------------------------------+

Here is an example where the vertices of the graph need to be relabeled.

+-----------------------------------------------------------------------------+
|i6 : FF = ZZ/32003                                                           |
|                                                                             |
|o6 = FF                                                                      |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : d = {2,3,2};                                                            |
+-----------------------------------------------------------------------------+
|i8 : PR = probabilityRing (d, CoefficientRing => FF);                        |
+-----------------------------------------------------------------------------+
|i9 : G = graph {{John,Matthew},{Matthew,Sarah}};                             |
+-----------------------------------------------------------------------------+
|i10 : I = ciIdeal (PR, G, {John,Matthew,Sarah})                              |
|                                                                             |
|o10 = ideal (- p         p          + p         p         , - p         p    |
|                {0, 0, 1} {1, 0, 0}    {0, 0, 0} {1, 0, 1}     {0, 1, 1} {1, |
|      -----------------------------------------------------------------------|
|            + p         p         , - p         p          + p         p     |
|      1, 0}    {0, 1, 0} {1, 1, 1}     {0, 2, 1} {1, 2, 0}    {0, 2, 0} {1,  |
|      -----------------------------------------------------------------------|
|           )                                                                 |
|      2, 1}                                                                  |
|                                                                             |
|o10 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+

Here is an example where the conditional independence relations are given with
a List.

+-----------------------------------------------------------------------------+
|i11 : FF = ZZ/32003                                                          |
|                                                                             |
|o11 = FF                                                                     |
|                                                                             |
|o11 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i12 : d = {2,3,2};                                                           |
+-----------------------------------------------------------------------------+
|i13 : PR = probabilityRing (d, CoefficientRing => FF);                       |
+-----------------------------------------------------------------------------+
|i14 : G = graph {{1,2},{2,3}};                                               |
+-----------------------------------------------------------------------------+
|i15 : L = {{{1},{3},{2}}}                                                    |
|                                                                             |
|o15 = {{{1}, {3}, {2}}}                                                      |
|                                                                             |
|o15 : List                                                                   |
+-----------------------------------------------------------------------------+
|i16 : I1 = ciIdeal (PR,G)                                                    |
|                                                                             |
|o16 = ideal (- p         p          + p         p         , - p         p    |
|                {0, 0, 1} {1, 0, 0}    {0, 0, 0} {1, 0, 1}     {0, 1, 1} {1, |
|      -----------------------------------------------------------------------|
|            + p         p         , - p         p          + p         p     |
|      1, 0}    {0, 1, 0} {1, 1, 1}     {0, 2, 1} {1, 2, 0}    {0, 2, 0} {1,  |
|      -----------------------------------------------------------------------|
|           )                                                                 |
|      2, 1}                                                                  |
|                                                                             |
|o16 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i17 : I2 = ciIdeal (PR,L)                                                    |
|                                                                             |
|o17 = ideal (- p         p          + p         p         , - p         p    |
|                {0, 0, 1} {1, 0, 0}    {0, 0, 0} {1, 0, 1}     {0, 1, 1} {1, |
|      -----------------------------------------------------------------------|
|            + p         p         , - p         p          + p         p     |
|      1, 0}    {0, 1, 0} {1, 1, 1}     {0, 2, 1} {1, 2, 0}    {0, 2, 0} {1,  |
|      -----------------------------------------------------------------------|
|           )                                                                 |
|      2, 1}                                                                  |
|                                                                             |
|o17 : Ideal of PR                                                            |
+-----------------------------------------------------------------------------+
|i18 : I1 == I2                                                               |
|                                                                             |
|o18 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * conditionalIndependenceIdeal (GraphicalModels)
    -- ideal of a list of
    conditional independent statements
  * mapToProbabilityRing -- ring isomorphism to
    the given probabilityRing from the corresponding markovRing
  * toMarkovRing -- ring of joint probability
    distributions created with the markovRing function from the GraphicalModels
    package
  * ciIdeal -- the ideal of a list of conditional independence
    statements
  * globalMarkov (GraphicalModels) -- global Markov
    statements for a graph or a directed graph

Ways to use ciIdeal:
====================

  * "ciIdeal(Ring,Graph)"
  * "ciIdeal(Ring,Graph,List)"
  * "ciIdeal(Ring,List)"
  * "ciIdeal(Ring,List,List)"

For the programmer
==================

The object ciIdeal, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1947:0.

correlatedEquilibria -- compute the correlated equilibrium polytope for a game
******************************************************************************

  * Usage:
        correlatedEquilibria X
  * Inputs:
      * X, a list (Macaulay2Doc), A list of payoff tensors, one for
        each player.
  * Outputs:
      * a convex polyhedron (Polyhedra), The polytope
        representing the set of correlated equilibria for the game.

Description
===========

This method constructs and returns the correlated equilibrium polytope for a
finite game. The input is a list of payoff tensors, one for each player. The
tensor at position i gives the payoffs for player i.

+--------------------------------------------------------------+
|i1 : X1 = zeroTensor(QQ, {2,2});                              |
+--------------------------------------------------------------+
|i2 : X2 = zeroTensor(QQ, {2,2});                              |
+--------------------------------------------------------------+
|i3 : X1#{0,0} = -99; X1#{0,1} = 1; X1#{1,0} = 0; X1#{1,1} = 0;|
+--------------------------------------------------------------+
|i7 : X2#{0,0} = -99; X2#{0,1} = 0; X2#{1,0} = 1; X2#{1,1} = 0;|
+--------------------------------------------------------------+
|i11 : CE = correlatedEquilibria {X1, X2}                      |
|                                                              |
|o11 = CE                                                      |
|                                                              |
|o11 : Polyhedron                                              |
+--------------------------------------------------------------+
|i12 : vertices CE                                             |
|                                                              |
|o12 = | 0 0 1/199  0      1/10000    |                        |
|      | 1 0 99/199 1/101  99/10000   |                        |
|      | 0 1 99/199 1/101  99/10000   |                        |
|      | 0 0 0      99/101 9801/10000 |                        |
|                                                              |
|               4       5                                      |
|o12 : Matrix QQ  <-- QQ                                       |
+--------------------------------------------------------------+
|i13 : facets CE                                               |
|                                                              |
|o13 = (| -1 0   0   0  |, 0)                                  |
|       | 99 -1  0   0  |                                      |
|       | 99 0   -1  0  |                                      |
|       | 0  0   0   -1 |                                      |
|       | 0  -99 0   1  |                                      |
|       | 0  0   -99 1  |                                      |
|                                                              |
|o13 : Sequence                                                |
+--------------------------------------------------------------+
|i14 : fVector CE                                              |
|                                                              |
|o14 = {5, 9, 6, 1}                                            |
|                                                              |
|o14 : List                                                    |
+--------------------------------------------------------------+
+----------------------------------+
|i15 : X = randomGame {2,2,3};     |
+----------------------------------+
|i16 : CE = correlatedEquilibria X;|
+----------------------------------+
|i17 : dim CE                      |
|                                  |
|o17 = 11                          |
+----------------------------------+

See also
========

  * assemblePolynomial -- compute incentive
    constraint polynomial for deviation
  * assemblePlayeriPolynomials -- get all
    incentive constraint polynomials for a player

Ways to use correlatedEquilibria:
=================================

  * "correlatedEquilibria(List)"

For the programmer
==================

The object correlatedEquilibria, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1297:0.

deltaList(List) -- generate the list of Newton polytopes for a generic game
***************************************************************************

  * Function: deltaList,
  * Usage:
        deltaList d
  * Inputs:
      * d, a list (Macaulay2Doc), a list of positive integers,
        representing the format of the game
  * Outputs:
      * a list (Macaulay2Doc), a list of polytopes formed by taking
        the product of certain convex sets and simplices

Description
===========

For a generic $n$-player game where the $i$-th player has $d_i$ pure
strategies, the maximum number of isolated totally mixed Nash equilibria is
given by the mixed volume of the following list of polytopes:

\[ (\Delta^{(1)}, \cdots, \Delta^{(1)},\Delta^{(2)}, \cdots, \Delta^{(2)},
\cdots, \Delta^{(n)}, \cdots, \Delta^{(n)}),\]

where each $\Delta^{(i)}$ repeats itself $d_i - 1$ times, and is the product of
simplices

\[ \Delta^{(i)} := \Delta_{d_{1}-1}\times \Delta_{d_{2}-1} \times \cdots \times
\Delta_{d_{i-1}-1} \times \{0\} \times \Delta_{d_{i+1}-1} \times \cdots \times
\Delta_{d_{n}-1}.\]

This function constructs and returns this list of polytopes. Each
$\Delta^{(i)}$ is a polytope in an ambient vector space of dimension
$d_1+d_2+\cdots+d_{n}-n$.

+--------------------------------------------------------------------+
|i1 : DL = deltaList {2,2,2}                                         |
|                                                                    |
|o1 = {Polyhedron{...1...}, Polyhedron{...1...}, Polyhedron{...1...}}|
|                                                                    |
|o1 : List                                                           |
+--------------------------------------------------------------------+

Each entries of DL is a polytope of dimension 2, in a $2+2+2-3=3$ dimensional
vector space.

+-----------------------------+
|i2 : apply(DL, p -> dim p)   |
|                             |
|o2 = {2, 2, 2}               |
|                             |
|o2 : List                    |
+-----------------------------+
|i3 : apply(DL, p -> ambDim p)|
|                             |
|o3 = {3, 3, 3}               |
|                             |
|o3 : List                    |
+-----------------------------+

See also
========

  * nashEquilibriumRing -- define the
    Nash Equilibrium ring
  * nashEquilibriumIdeal -- make
    the Nash Equilibrium ideal

Ways to use this method:
========================

  * deltaList(List) -- generate the list of Newton
    polytopes for a generic game
-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1413:0.

enumerateTensorIndices -- generate index tuples for a tensor with given dimensions
**********************************************************************************

  * Usage:
        enumerateTensorIndices d
  * Inputs:
      * d, an integer (Macaulay2Doc), A single integer.
      * d, a list (Macaulay2Doc), A list of integers, representing
        the format of a tensor.
  * Outputs:
      * a list (Macaulay2Doc), A list of index tuples, where each
        tuple corresponds to a coordinate of the tensor.

Description
===========

This function generates all possible index tuples for a tensor with the
specified dimensions. For a tensor of format $d_1 \times d_2 \cdots d_n$, it
returns a list of all tuples $(i_1, i2, \ldots, i_n)$ where $0 \leq i_j < d_j$.

+-----------------------------------------------------------------------------+
|i1 : enumerateTensorIndices 5                                                |
|                                                                             |
|o1 = {{0}, {1}, {2}, {3}, {4}}                                               |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : enumerateTensorIndices {2,2}                                            |
|                                                                             |
|o2 = {{0, 0}, {0, 1}, {1, 0}, {1, 1}}                                        |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : enumerateTensorIndices {3,2,4}                                          |
|                                                                             |
|o3 = {{0, 0, 0}, {0, 0, 1}, {0, 0, 2}, {0, 0, 3}, {0, 1, 0}, {0, 1, 1}, {0,  |
|     ------------------------------------------------------------------------|
|     1, 2}, {0, 1, 3}, {1, 0, 0}, {1, 0, 1}, {1, 0, 2}, {1, 0, 3}, {1, 1, 0},|
|     ------------------------------------------------------------------------|
|     {1, 1, 1}, {1, 1, 2}, {1, 1, 3}, {2, 0, 0}, {2, 0, 1}, {2, 0, 2}, {2, 0,|
|     ------------------------------------------------------------------------|
|     3}, {2, 1, 0}, {2, 1, 1}, {2, 1, 2}, {2, 1, 3}}                         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Tensor -- a mutable hash table representing a tensor
  * zeroTensor -- construct a tensor with zero entries from
    a given ring.
  * randomTensor -- construct a tensor with random entries
    from a given ring

Ways to use enumerateTensorIndices:
===================================

  * "enumerateTensorIndices(List)"
  * "enumerateTensorIndices(ZZ)"

For the programmer
==================

The object enumerateTensorIndices, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:953:0.

getVariableToIndexset -- retrieve a polynomial ring variable by its index tuple
*******************************************************************************

  * Usage:
        getVariableToIndexset(R, indexTuple)
  * Inputs:
      * R, a ring (Macaulay2Doc), A polynomial ring whose variables
        are indexed by tuples.
      * indexTuple, a list (Macaulay2Doc), A list representing the
        index of the variable.
  * Outputs:
      * a ring element (Macaulay2Doc), The variable from the
        ring corresponding to the given index.

Description
===========

Given a ring $R = \mathbb{Q}[p_{\{i,j\}}]$, this method retrieves $p_{\{i,j\}}$
when passed the index $\{i,j\}$.

+-----------------------------------------------+
|i1 : R = QQ[p_{0,0}, p_{0,1}, p_{1,0}, p_{1,1}]|
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing                            |
+-----------------------------------------------+
|i2 : getVariableToIndexset(R, {1,0})           |
|                                               |
|o2 = p                                         |
|      {1, 0}                                   |
|                                               |
|o2 : R                                         |
+-----------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * assemblePolynomial -- compute incentive
    constraint polynomial for deviation

Ways to use getVariableToIndexset:
==================================

  * "getVariableToIndexset(Ring,List)"

For the programmer
==================

The object getVariableToIndexset, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1178:0.

indexset -- get the list of index tuples of a tensor
****************************************************

  * Usage:
        indexset T
  * Inputs:
      * T, an instance of the type Tensor, A tensor whose index
        set is to be retrieved.
  * Outputs:
      * a list (Macaulay2Doc), A list of index tuples corresponding
        to the entries of the tensor.

Description
===========

Given a tensor $T$ of format $\{d_1, d_2, \dots, d_n\}$, this method returns a
list of all index tuples $(i_1, i_2, \dots, i_n)$ such that $0 \leq i_j < d_j$
for each dimension $j$. Difference from enumerateTensorIndices,
is that indexset can only be used with a Tensor object.
See indexset, retrieves precomputed indices stored as metadata in a
Tensor.

+-----------------------------------------------------------------------------+
|i1 : T = zeroTensor(QQ, {2,3,4});                                            |
+-----------------------------------------------------------------------------+
|i2 : indexset T                                                              |
|                                                                             |
|o2 = {{0, 0, 0}, {0, 0, 1}, {0, 0, 2}, {0, 0, 3}, {0, 1, 0}, {0, 1, 1}, {0,  |
|     ------------------------------------------------------------------------|
|     1, 2}, {0, 1, 3}, {0, 2, 0}, {0, 2, 1}, {0, 2, 2}, {0, 2, 3}, {1, 0, 0},|
|     ------------------------------------------------------------------------|
|     {1, 0, 1}, {1, 0, 2}, {1, 0, 3}, {1, 1, 0}, {1, 1, 1}, {1, 1, 2}, {1, 1,|
|     ------------------------------------------------------------------------|
|     3}, {1, 2, 0}, {1, 2, 1}, {1, 2, 2}, {1, 2, 3}}                         |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
+-----------------------------+
|i3 : T = zeroTensor(QQ, {2});|
+-----------------------------+
|i4 : indexset T              |
|                             |
|o4 = {{0}, {1}}              |
|                             |
|o4 : List                    |
+-----------------------------+

See also
========

  * zeroTensor -- construct a tensor with zero entries from
    a given ring.
  * randomTensor -- construct a tensor with random entries
    from a given ring
  * enumerateTensorIndices -- generate index
    tuples for a tensor with given dimensions

Ways to use indexset:
=====================

  * "indexset(Tensor)"

For the programmer
==================

The object indexset, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1023:0.

intersectWithCImodel -- ideal of the intersection of a given variety with the conditional independence model
************************************************************************************************************

  * Usage:
        intersectWithCImodel(V, Stmts)
        intersectWithCImodel(V, Stmts, PlayerNames)
        intersectWithCImodel(V, G)
        intersectWithCImodel(V, G, PlayerNames)
  * Inputs:
      * V, an ideal (Macaulay2Doc), an ideal of a ring created
        with probabilityRing
      * Stmts, a list (Macaulay2Doc), the list of conditional
        independence statements
      * G, a graph (Graphs), the graph modelling the conditional
        dependencies between players
      * PlayerNames, a list (Macaulay2Doc), the ordered list of
        players - the names of the random variables in the conditional
        independence statements or vertices of the graph. If PlayerNames is
        omitted, the players (or the vertices of G) are assumed to be labelled
        1..n.
  * Optional inputs (Macaulay2Doc),:
      * Verbose (missing documentation) => ..., default value false,
  * Outputs:
      * an ideal (Macaulay2Doc), The ideal of the intersection of
        the given variety with the conditional independence model determined by
        the conditional independence statements/graph.

Description
===========

intersectWithCImodel calculates the ideal of the intersection of the given
variety V with the conditional independence model determined by a set of
conditional probability statements or an undirected graph. More precisely, the
output is the ideal of the closure of the variety given by removing the
components in the coordinate hyperplanes from the intersection of the variety V
and the conditional independence model.

The input for the conditional independence model can be a set of conditional
probability statements or an undirected graph. A single conditional
independence statement is a list consisting of three disjoint lists of indices
for random variables, e.g. $\{ \{1,2\},\{4\}, \{3\} \}$ which represents the
conditional independence statement "$(X_1, X_2)$ is conditionally independent
of $X_4$ given $X_3$". In the context of game theory, the variable $X_i$
represents the strategy of player $i$.

Given an undirected graph $G$, the conditional independence statements are
produced via the globalMarkov function from the GraphicalModels package. A
global Markov statement for $G$ is a list $\{A, B, C\}$ of three disjoint lists
of vertices of $G$, where the subset $C$ separates the subset $A$ from the
subset $B$ in the graph $G$.

+----------------------------------------------------+
|i1 : FF = ZZ/32003;                                 |
+----------------------------------------------------+
|i2 : d = {2,2,2};                                   |
+----------------------------------------------------+
|i3 : X = randomGame(d, CoefficientRing => FF);      |
+----------------------------------------------------+
|i4 : PR = probabilityRing(d, CoefficientRing => FF);|
+----------------------------------------------------+
|i5 : V = spohnIdeal(PR, X);                         |
|                                                    |
|o5 : Ideal of PR                                    |
+----------------------------------------------------+
|i6 : G1 = graph ({}, Singletons => {1,2,3});        |
+----------------------------------------------------+
|i7 : G2 = graph ({{1,2}}, Singletons => {3});       |
+----------------------------------------------------+
|i8 : I1 = intersectWithCImodel(V, G1);              |
|                                                    |
|o8 : Ideal of PR                                    |
+----------------------------------------------------+
|i9 : I2 = intersectWithCImodel(V, G2);              |
|                                                    |
|o9 : Ideal of PR                                    |
+----------------------------------------------------+

Here is an example where the vertices of the graph need to be relabeled.

+-------------------------------------------------------------+
|i10 : FF = ZZ/32003;                                         |
+-------------------------------------------------------------+
|i11 : d = {2,2,2};                                           |
+-------------------------------------------------------------+
|i12 : X = randomGame(d, CoefficientRing => FF);              |
+-------------------------------------------------------------+
|i13 : PR = probabilityRing(d, CoefficientRing => FF);        |
+-------------------------------------------------------------+
|i14 : V = spohnIdeal(PR, X);                                 |
|                                                             |
|o14 : Ideal of PR                                            |
+-------------------------------------------------------------+
|i15 : G1 = graph {{John,Matthew},{Matthew,Sarah}};           |
+-------------------------------------------------------------+
|i16 : G2 = graph {{a,b},{b,c},{c,a}};                        |
+-------------------------------------------------------------+
|i17 : I1 = intersectWithCImodel(V, G1, {John,Matthew,Sarah});|
|                                                             |
|o17 : Ideal of PR                                            |
+-------------------------------------------------------------+
|i18 : I2 = intersectWithCImodel(V, G2, {a,b,c});             |
|                                                             |
|o18 : Ideal of PR                                            |
+-------------------------------------------------------------+

Here is an example where the conditional independence relations are given with
a List.

+-----------------------------------------------------+
|i19 : FF = ZZ/32003;                                 |
+-----------------------------------------------------+
|i20 : d = {2,2,2};                                   |
+-----------------------------------------------------+
|i21 : X = randomGame(d, CoefficientRing => FF);      |
+-----------------------------------------------------+
|i22 : PR = probabilityRing(d, CoefficientRing => FF);|
+-----------------------------------------------------+
|i23 : V = spohnIdeal(PR, X);                         |
|                                                     |
|o23 : Ideal of PR                                    |
+-----------------------------------------------------+
|i24 : G = graph ({{1,2}},Singletons => {3});         |
+-----------------------------------------------------+
|i25 : L = {{{1,2},{3},{}}};                          |
+-----------------------------------------------------+
|i26 : I1 = intersectWithCImodel(V, G);               |
|                                                     |
|o26 : Ideal of PR                                    |
+-----------------------------------------------------+
|i27 : I2 = intersectWithCImodel(V, L);               |
|                                                     |
|o27 : Ideal of PR                                    |
+-----------------------------------------------------+
|i28 : I1 == I2                                       |
|                                                     |
|o28 = true                                           |
+-----------------------------------------------------+

The Verbose=>true option prints the progress of each step in the saturation
process - a message is printed after saturating the ideal $V$, the conditional
independence ideal $I$, and the sum $V + I$ with respect to each hyperplane of
the probability simplex.

+-----------------------------------------------------+
|i29 : FF = ZZ/32003;                                 |
+-----------------------------------------------------+
|i30 : d = {2,3,2};                                   |
+-----------------------------------------------------+
|i31 : X = randomGame(d, CoefficientRing => FF);      |
+-----------------------------------------------------+
|i32 : PR = probabilityRing(d, CoefficientRing => FF);|
+-----------------------------------------------------+
|i33 : V = spohnIdeal(PR, X);                         |
|                                                     |
|o33 : Ideal of PR                                    |
+-----------------------------------------------------+
|i34 : L = {{{1,2},{3},{}}};                          |
+-----------------------------------------------------+
|i35 : I = intersectWithCImodel(V, L, Verbose=>true); |
|Completed step 1 of saturating CI ideal              |
|Completed step 1 of saturating input ideal           |
|Completed step 2 of saturating CI ideal              |
|Completed step 2 of saturating input ideal           |
|Completed step 3 of saturating CI ideal              |
|Completed step 3 of saturating input ideal           |
|Completed step 4 of saturating CI ideal              |
|Completed step 4 of saturating input ideal           |
|Completed step 5 of saturating CI ideal              |
|Completed step 5 of saturating input ideal           |
|Completed step 6 of saturating CI ideal              |
|Completed step 6 of saturating input ideal           |
|Completed step 7 of saturating CI ideal              |
|Completed step 7 of saturating input ideal           |
|Completed step 8 of saturating CI ideal              |
|Completed step 8 of saturating input ideal           |
|Completed step 9 of saturating CI ideal              |
|Completed step 9 of saturating input ideal           |
|Completed step 10 of saturating CI ideal             |
|Completed step 10 of saturating input ideal          |
|Completed step 11 of saturating CI ideal             |
|Completed step 11 of saturating input ideal          |
|Completed step 12 of saturating CI ideal             |
|Completed step 12 of saturating input ideal          |
|Completed step 13 of saturating CI ideal             |
|Completed step 13 of saturating input ideal          |
|Completed step 1 of saturating sum                   |
|Completed step 2 of saturating sum                   |
|Completed step 3 of saturating sum                   |
|Completed step 4 of saturating sum                   |
|Completed step 5 of saturating sum                   |
|Completed step 6 of saturating sum                   |
|Completed step 7 of saturating sum                   |
|Completed step 8 of saturating sum                   |
|Completed step 9 of saturating sum                   |
|Completed step 10 of saturating sum                  |
|Completed step 11 of saturating sum                  |
|Completed step 12 of saturating sum                  |
|                                                     |
|o35 : Ideal of PR                                    |
+-----------------------------------------------------+

See also
========

  * conditionalIndependenceIdeal (GraphicalModels)
    -- ideal of a list of
    conditional independent statements
  * mapToProbabilityRing -- ring isomorphism to
    the given probabilityRing from the corresponding markovRing
  * toMarkovRing -- ring of joint probability
    distributions created with the markovRing function from the GraphicalModels
    package
  * ciIdeal -- the ideal of a list of conditional independence
    statements
  * globalMarkov (GraphicalModels) -- global Markov
    statements for a graph or a directed graph

Ways to use intersectWithCImodel:
=================================

  * "intersectWithCImodel(Ideal,Graph)"
  * "intersectWithCImodel(Ideal,Graph,List)"
  * "intersectWithCImodel(Ideal,List)"
  * "intersectWithCImodel(Ideal,List,List)"

For the programmer
==================

The object intersectWithCImodel, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:2061:0.

konstanzMatrix -- construct the Konstanz matrix of a given game
***************************************************************

  * Usage:
        konstanzMatrix(PR, X)
  * Inputs:
      * PR, a ring (Macaulay2Doc), a probability ring obtained via
        probabilityRing(Di), where $Di = \{d_1 , \cdots , d_n\}$ is the format
        of the game
      * X, a list (Macaulay2Doc), a list of n tensors of format
        $D_i$ describing the payoffs of the game
  * Optional inputs (Macaulay2Doc),:
      * KonstanzVariableName (missing documentation) => ..., default value "k",
  * Outputs:
      * a matrix (Macaulay2Doc), the $(d_1 + \ldots + d_n) \times
        (d-1 \cdots d_n)$-dimensional Konstanz matrix

Description
===========

It is crucial that the formats in PR and X match up. The Konstanz matrix
$K_X(k)$ is the unique matrix with monic polynomials as entries such that the
Spohn variety is the union $\bigcup_{k \in (\mathbb P^1)^n} \ker K_X(k)$.

+-----------------------------------------------------------------------------+
|i1 : Di = {2,2,3};                                                           |
+-----------------------------------------------------------------------------+
|i2 : PR = probabilityRing(Di);                                               |
+-----------------------------------------------------------------------------+
|i3 : X = randomGame(Di);                                                     |
+-----------------------------------------------------------------------------+
|i4 : K = konstanzMatrix(PR,X)                                                |
|                                                                             |
|o4 = | k_0-9/2 k_0-9/4 k_0-3/4  k_0-7/4 k_0-7/9 k_0-7/10 0        0          |
|     | 0       0       0        0       0       0        k_0-7/10 k_0-7/3    |
|     | k_1-5/4 k_1-2/9 k_1-3/10 0       0       0        k_1-10   k_1-3/2    |
|     | 0       0       0        k_1-3/7 k_1-5   k_1-10/9 0        0          |
|     | k_2-5/3 0       0        k_2-6/5 0       0        k_2-5/3  0          |
|     | 0       k_2-7/2 0        0       k_2-5/7 0        0        k_2-1/10   |
|     | 0       0       k_2-2/5  0       0       k_2-5/9  0        0          |
|     ------------------------------------------------------------------------|
|     0       0       0        0       |                                      |
|     k_0-7   k_0-3/7 k_0-6/7  k_0-6   |                                      |
|     k_1-7/8 0       0        0       |                                      |
|     0       k_1-5/6 k_1-5    k_1-2/5 |                                      |
|     0       k_2-3/7 0        0       |                                      |
|     0       0       k_2-9/10 0       |                                      |
|     k_2-4/3 0       0        k_2-4/7 |                                      |
|                                                                             |
|                        7                 12                                 |
|o4 : Matrix (PR[k ..k ])  <-- (PR[k ..k ])                                   |
|                 0   2             0   2                                     |
+-----------------------------------------------------------------------------+

The optional argument KonstanzVariableName allows to change the name of the
variables. If no variable name choice is specified, the variables will be named
with k.

+----------------------------------------------------------+
|i5 : Di = {2,2};                                          |
+----------------------------------------------------------+
|i6 : PR = probabilityRing(Di);                            |
+----------------------------------------------------------+
|i7 : X = randomGame(Di);                                  |
+----------------------------------------------------------+
|i8 : K = konstanzMatrix(PR,X, KonstanzVariableName => "z")|
|                                                          |
|o8 = | z_0-5/9 z_0-5/9 0       0       |                  |
|     | 0       0       z_0-6/7 z_0-6   |                  |
|     | z_1-5/4 0       z_1-8/5 0       |                  |
|     | 0       z_1-2/9 0       z_1-9/4 |                  |
|                                                          |
|                        4                 4               |
|o8 : Matrix (PR[z ..z ])  <-- (PR[z ..z ])                |
|                 0   1             0   1                  |
+----------------------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * randomGame -- construct a game of a given format with
    arbitrary payoffs
  * spohnMatrices -- compute the list of Spohn matrices
    of a given game
  * spohnIdeal -- compute the ideal of the Spohn variety of
    a given game

Ways to use konstanzMatrix:
===========================

  * konstanzMatrix(Ring,List) (missing documentation)

For the programmer
==================

The object konstanzMatrix, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1740:0.

KonstanzVariableName
********************

Functions with optional argument named KonstanzVariableName:
============================================================

  * konstanzMatrix(...,KonstanzVariableName=>...) (missing documentation)

For the programmer
==================

The object KonstanzVariableName (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in currentString:1:388.

mapToMarkovRing -- ring isomorphism from the given probabilityRing to the corresponding markovRing
**************************************************************************************************

  * Usage:
        mapToMarkovRing R
  * Inputs:
      * R, a ring (Macaulay2Doc), must be a probabilityRing
  * Outputs:
      * a ring map (Macaulay2Doc), the isomorphism identifying R
        with toMarkovRing(R). The variable $p_{\{i_1, \ldots, i_k\}}$ is sent
        to $q_{(i_1+1, \dots , i_k+1)}$.

Description
===========

This function creates the RingMap from a given probabilityRing to its
canonically isomorphic markovRing.

+-----------------------------------------------------------------------------+
|i1 : R = probabilityRing {2,3,4};                                            |
+-----------------------------------------------------------------------------+
|i2 : markovR = toMarkovRing R;                                               |
+-----------------------------------------------------------------------------+
|i3 : F = mapToMarkovRing R                                                   |
|                                                                             |
|o3 = map (markovR, R, {q     , q     , q     , q     , q     , q     ,       |
|                        1,1,1   1,1,2   1,1,3   1,1,4   1,2,1   1,2,2        |
|                                                                             |
|o3 : RingMap markovR <-- R                                                   |
|-----------------------------------------------------------------------------|
|q     , q     , q     , q     , q     , q     , q     , q     , q     ,      |
| 1,2,3   1,2,4   1,3,1   1,3,2   1,3,3   1,3,4   2,1,1   2,1,2   2,1,3       |
|-----------------------------------------------------------------------------|
|q     , q     , q     , q     , q     , q     , q     , q     , q     })     |
| 2,1,4   2,2,1   2,2,2   2,2,3   2,2,4   2,3,1   2,3,2   2,3,3   2,3,4       |
+-----------------------------------------------------------------------------+
|i4 : target F                                                                |
|                                                                             |
|o4 = markovR                                                                 |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : source F                                                                |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : isInjective F                                                           |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : F.matrix                                                                |
|                                                                             |
|o7 = | q_(1,1,1) q_(1,1,2) q_(1,1,3) q_(1,1,4) q_(1,2,1) q_(1,2,2) q_(1,2,3) |
|     ------------------------------------------------------------------------|
|     q_(1,2,4) q_(1,3,1) q_(1,3,2) q_(1,3,3) q_(1,3,4) q_(2,1,1) q_(2,1,2)   |
|     ------------------------------------------------------------------------|
|     q_(2,1,3) q_(2,1,4) q_(2,2,1) q_(2,2,2) q_(2,2,3) q_(2,2,4) q_(2,3,1)   |
|     ------------------------------------------------------------------------|
|     q_(2,3,2) q_(2,3,3) q_(2,3,4) |                                         |
|                                                                             |
|                   1            24                                           |
|o7 : Matrix markovR  <-- markovR                                             |
+-----------------------------------------------------------------------------+

See also
========

  * toMarkovRing -- ring of joint probability
    distributions created with the markovRing function from the GraphicalModels
    package
  * mapToProbabilityRing -- ring isomorphism to
    the given probabilityRing from the corresponding markovRing

Ways to use mapToMarkovRing:
============================

  * "mapToMarkovRing(Ring)"

For the programmer
==================

The object mapToMarkovRing, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1817:0.

mapToProbabilityRing -- ring isomorphism to the given probabilityRing from the corresponding markovRing
*******************************************************************************************************

  * Usage:
        mapToProbabilityRing R
  * Inputs:
      * R, a ring (Macaulay2Doc), must be a probabilityRing
  * Outputs:
      * a ring map (Macaulay2Doc), the isomorphism identifying R
        with toMarkovRing(R). The variable $q_{(i_1+1, \dots , i_k+1)}$ is sent
        to $p_{\{i_1, \ldots, i_k\}}$.

Description
===========

This function creates the RingMap to a given probabilityRing from its
canonically isomorphic markovRing.

+-----------------------------------------------------------------------------+
|i1 : R = probabilityRing {2,3,4};                                            |
+-----------------------------------------------------------------------------+
|i2 : markovR = toMarkovRing R;                                               |
+-----------------------------------------------------------------------------+
|i3 : F = mapToProbabilityRing R                                              |
|                                                                             |
|o3 = map (R, markovR, {p         , p         , p         , p         , p     |
|                        {0, 0, 0}   {0, 0, 1}   {0, 0, 2}   {0, 0, 3}   {0,  |
|                                                                             |
|o3 : RingMap R <-- markovR                                                   |
|-----------------------------------------------------------------------------|
|     , p         , p         , p         , p         , p         , p         |
|1, 0}   {0, 1, 1}   {0, 1, 2}   {0, 1, 3}   {0, 2, 0}   {0, 2, 1}   {0, 2,   |
|-----------------------------------------------------------------------------|
|  , p         , p         , p         , p         , p         , p         ,  |
|2}   {0, 2, 3}   {1, 0, 0}   {1, 0, 1}   {1, 0, 2}   {1, 0, 3}   {1, 1, 0}   |
|-----------------------------------------------------------------------------|
|p         , p         , p         , p         , p         , p         , p    |
| {1, 1, 1}   {1, 1, 2}   {1, 1, 3}   {1, 2, 0}   {1, 2, 1}   {1, 2, 2}   {1, |
|-----------------------------------------------------------------------------|
|     })                                                                      |
|2, 3}                                                                        |
+-----------------------------------------------------------------------------+
|i4 : target F                                                                |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : source F                                                                |
|                                                                             |
|o5 = markovR                                                                 |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : isInjective F                                                           |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : F.matrix                                                                |
|                                                                             |
|o7 = | p_{0, 0, 0} p_{0, 0, 1} p_{0, 0, 2} p_{0, 0, 3} p_{0, 1, 0} p_{0, 1,  |
|     ------------------------------------------------------------------------|
|     1} p_{0, 1, 2} p_{0, 1, 3} p_{0, 2, 0} p_{0, 2, 1} p_{0, 2, 2} p_{0, 2, |
|     ------------------------------------------------------------------------|
|     3} p_{1, 0, 0} p_{1, 0, 1} p_{1, 0, 2} p_{1, 0, 3} p_{1, 1, 0} p_{1, 1, |
|     ------------------------------------------------------------------------|
|     1} p_{1, 1, 2} p_{1, 1, 3} p_{1, 2, 0} p_{1, 2, 1} p_{1, 2, 2} p_{1, 2, |
|     ------------------------------------------------------------------------|
|     3} |                                                                    |
|                                                                             |
|             1      24                                                       |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * toMarkovRing -- ring of joint probability
    distributions created with the markovRing function from the GraphicalModels
    package
  * mapToProbabilityRing -- ring isomorphism to
    the given probabilityRing from the corresponding markovRing

Ways to use mapToProbabilityRing:
=================================

  * "mapToProbabilityRing(Ring)"

For the programmer
==================

The object mapToProbabilityRing, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1855:0.

nashEquilibriumIdeal(Ring,List) -- make the Nash Equilibrium ideal
******************************************************************

  * Function: nashEquilibriumIdeal,
  * Usage:
        nashEquilibriumIdeal(R, L)
  * Inputs:
      * R, a ring (Macaulay2Doc), the Nash Equilibrium ring.
        Typically obtained via nashEquilibriumRing,
      * L, a list (Macaulay2Doc), a list of n payoff tensors
  * Outputs:
      * an ideal (Macaulay2Doc), an ideal in the Nash Equilibrium
        ring R generated by the Nash equilibrium polynomials, along with the
        linear relations of the probability variables

Description
===========

For an $n$-player game, the totally mixed Nash equilibria are the zero loci of
a system of polynomials in the interior of product of probability simplices.
The coefficients of these polynomials are certain differences of the entries of
the payoff tensors. These polynomials, together with the linear constraints
$\sum^{d_i -1}_{j=0} p_{i,j}=1$ for each player $i$, generate an ideal in the
polynomial ring computed by nashEquilibriumRing.

+-----------------------------------------------------------------------------+
|i1 : tensors = randomGame {2,2,2};                                           |
+-----------------------------------------------------------------------------+
|i2 : R = nashEquilibriumRing tensors;                                        |
+-----------------------------------------------------------------------------+
|i3 : I = nashEquilibriumIdeal(R, tensors)                                    |
|                                                                             |
|              67                  1                 31                  7    |
|o3 = ideal (- --p      p       - --p      p       - --p      p       + --p   |
|              18 {1, 0} {2, 0}   20 {1, 1} {2, 0}   20 {1, 0} {2, 1}   12 {1,|
|     ------------------------------------------------------------------------|
|                  43                 19                 39                   |
|       p      , - --p      p       - --p      p       + --p      p       +   |
|     1} {2, 1}     7 {0, 0} {2, 0}   20 {0, 1} {2, 0}    7 {0, 0} {2, 1}     |
|     ------------------------------------------------------------------------|
|     13                  35                  1                 17            |
|     --p      p      , - --p      p       - --p      p       - --p      p    |
|     63 {0, 1} {2, 1}     9 {0, 0} {1, 0}   24 {0, 1} {1, 0}    2 {0, 0} {1, |
|     ------------------------------------------------------------------------|
|          23                                                                 |
|        - --p      p      , p       + p       - 1, p       + p       - 1,    |
|     1}    5 {0, 1} {1, 1}   {0, 0}    {0, 1}       {1, 0}    {1, 1}         |
|     ------------------------------------------------------------------------|
|     p       + p       - 1)                                                  |
|      {2, 0}    {2, 1}                                                       |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

An introduction together with the relevant definitions is given in Chapter 6,
Sturmfels, Bernd, Solving Systems of Polynomial Equations. American
Mathematical Society, 2002 and in Abo, Hirotachi, Portakal, Irem, and Sodomaco,
Luca, A vector bundle approach to Nash equilibria, arXiv:2504.03456.

See also
========

  * nashEquilibriumRing -- define the
    Nash Equilibrium ring
  * deltaList -- generate the list of Newton
    polytopes for a generic game
  * blockDerangements -- compute the block
    derangements
  * numberTMNE -- compute the maximum number of
    totally mixed Nash equilibria for a generic game

Ways to use this method:
========================

  * nashEquilibriumIdeal(Ring,List)
    -- make the Nash Equilibrium ideal
-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1371:0.

nashEquilibriumRing(List) -- define the Nash Equilibrium ring
*************************************************************

  * Function: nashEquilibriumRing,
  * Usage:
        nashEquilibriumRing L
  * Inputs:
      * L, a list (Macaulay2Doc), a list of n-see Tensor,
        s with same dimensions
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring generated by mixed
        strategies

Description
===========

Let $p_{i,j}$ be the probability of $i$-th player choosing the $j$-th strategy,
where $j \in \{0, \cdots, d_j-1\}$. The ideal of the totally mixed Nash
equilibria of the game is defined in the polynomial ring over a field $k$ with
generators $\{p_{i,j} \ | \ 0\leq i\leq n-1, 0\leq j\leq d_j-1\}$. The ring
generators are ordered lexicographically.

+-----------------------------------------------------------------------------+
|i1 : tensors = randomGame {2,4,3};                                           |
+-----------------------------------------------------------------------------+
|i2 : R = nashEquilibriumRing tensors;                                        |
+-----------------------------------------------------------------------------+
|i3 : baseRing R                                                              |
|                                                                             |
|o3 = QQ                                                                      |
|                                                                             |
|o3 : Ring                                                                    |
+-----------------------------------------------------------------------------+
|i4 : gens R                                                                  |
|                                                                             |
|o4 = {p      , p      , p      , p      , p      , p      , p      , p      ,|
|       {0, 0}   {0, 1}   {1, 0}   {1, 1}   {1, 2}   {1, 3}   {2, 0}   {2, 1} |
|     ------------------------------------------------------------------------|
|     p      }                                                                |
|      {2, 2}                                                                 |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * nashEquilibriumIdeal -- make
    the Nash Equilibrium ideal
  * deltaList -- generate the list of Newton
    polytopes for a generic game
  * blockDerangements -- compute the block
    derangements
  * numberTMNE -- compute the maximum number of
    totally mixed Nash equilibria for a generic game

Ways to use this method:
========================

  * nashEquilibriumRing(List) -- define
    the Nash Equilibrium ring
-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1332:0.

numberTMNE(List) -- compute the maximum number of totally mixed Nash equilibria for a generic game
**************************************************************************************************

  * Function: numberTMNE,
  * Usage:
        numberTMNE d
  * Inputs:
      * d, a list (Macaulay2Doc), a list of integers representing
        the format of the game
  * Outputs:
      * an integer (Macaulay2Doc), an integer value, the degree of
        the top Chern class of a vector bundle on a product of projective
        spaces, representing the maximum number of totally mixed Nash
        equilibria of a generic game of format $\mathbf{d}$.

Description
===========

For an $n$-player game where the $i$-th player has $d_i$ pure strategies, the
maximum number of isolated totally mixed Nash equilibria is given by the degree
$c(\mathbf{d})$ of the top Chern class of the following vector bundle:

\[E := \bigoplus_{i=0}^{n-1}
\mathcal{O}_{\mathbb{P}^{\mathbf{d}}}(\mathbf{1}_i)^{\oplus (d_i - 1)},\]

where $\mathbb{P}^{\mathbf{d}}=\prod_{i=0}^{n-1}\mathbb{P}^{d_i-1}$ and
$\mathbf{1}_i=(1,\ldots,1,0,1,\ldots,1)$, where the entry $0$ is in the $i$-th
component. In particular, this function computes the integer $c(\mathbf{d})$ as
the coefficient of the monomial $\prod_{i=0}^{n-1} h_i^{d_i-1}$ in
$\prod_{i=0}^{n-1} \hat{h}_i^{d_i-1}$ with $\hat{h}_i\coloneqq \sum_{j\neq
i}h_j$, where $h_i$ denotes the pullback of the hyperplane class on the $i$-th
factor $\mathbb{P}^{d_i-1}$ of $\mathbb{P}^{\mathbf{d}}$ via the projection
map.

+-------------------------+
|i1 : d = {2,2,2};        |
+-------------------------+
|i2 : nTMNE = numberTMNE d|
|                         |
|o2 = 2                   |
+-------------------------+

Alternatively, if you have a tensor $T$, you can compute its maximum number as
follows:

+---------------------------------+
|i3 : T = randomTensor {2,2,2}    |
|                                 |
|o3 = Tensor{...11...}            |
|                                 |
|o3 : Tensor                      |
+---------------------------------+
|i4 : nTMNE2 = numberTMNE format T|
|                                 |
|o4 = 2                           |
+---------------------------------+

See also
========

  * blockDerangements -- compute the block
    derangements

Ways to use this method:
========================

  * numberTMNE(List) -- compute the maximum number
    of totally mixed Nash equilibria for a generic game
-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1455:0.

probabilityRing -- ring of probability distributions of a game indexed by ordered multi-indices
***********************************************************************************************

  * Usage:
        probabilityRing(Di)
  * Inputs:
      * Di, a list (Macaulay2Doc), a list of natural numbers
        $d_0,\dots,d_{n-1}$
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (missing documentation) => ..., default value QQ,
      * ProbabilityVariableName (missing documentation) => ..., default value
        "p",
  * Outputs:
      * a ring (Macaulay2Doc), a polynomial ring with a tensor of
        variables $p_{i_0,\dots,i_{n-1}}$ such that $i_j$ runs from $0$ to
        $d_j-1$.

Description
===========

The list $Di$ represents the format of the game. In this example, we create a
ring of probability distributions coming from a game of format {2, 3, 2}. This
format can be accessed from the ring through the field "gameFormat".

The variables $p#i$ are the entries of the tensor $p$, which can be accessed
from the ring through the field "probabilityVariable".

+-----------------------------------------------------------------------------+
|i1 : Di = {2,3,2};                                                           |
+-----------------------------------------------------------------------------+
|i2 : PR = probabilityRing Di;                                                |
+-----------------------------------------------------------------------------+
|i3 : numgens PR                                                              |
|                                                                             |
|o3 = 12                                                                      |
+-----------------------------------------------------------------------------+
|i4 : pairs PR#"probabilityVariable"                                          |
|                                                                             |
|o4 = {(indexes, {{0, 0, 0}, {0, 0, 1}, {0, 1, 0}, {0, 1, 1}, {0, 2, 0}, {0,  |
|                                                                             |
|     ------------------------------------------------------------------------|
|     2, 1}, {1, 0, 0}, {1, 0, 1}, {1, 1, 0}, {1, 1, 1}, {1, 2, 0}, {1, 2,    |
|                                                                             |
|     ------------------------------------------------------------------------|
|     1}}), ({1, 1, 0}, p         ), ({1, 1, 1}, p         ), ({1, 0, 0}, p   |
|                        {1, 1, 0}                {1, 1, 1}                {1,|
|     ------------------------------------------------------------------------|
|          ), ({0, 2, 0}, p         ), ({1, 0, 1}, p         ), ({0, 2, 1},   |
|     0, 0}                {0, 2, 0}                {1, 0, 1}                 |
|     ------------------------------------------------------------------------|
|     p         ), ({0, 1, 0}, p         ), ({0, 1, 1}, p         ), (format, |
|      {0, 2, 1}                {0, 1, 0}                {0, 1, 1}            |
|     ------------------------------------------------------------------------|
|     {2, 3, 2}), ({0, 0, 0}, p         ), ({0, 0, 1}, p         ), ({1, 2,   |
|                              {0, 0, 0}                {0, 0, 1}             |
|     ------------------------------------------------------------------------|
|     0}, p         ), ({1, 2, 1}, p         ), (coefficients, PR)}           |
|          {1, 2, 0}                {1, 2, 1}                                 |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

The optional argument "CoefficientRing" allows to change the base field. If no
choice is specified, the base field is set to QQ. It is also possible to change
the name of the variable tensor through the optional argument
"ProbabilityVariableName", which is set to the string "p" by default.

+-----------------------------------------------------------------------------+
|i5 : PR2 = probabilityRing (Di, CoefficientRing=>RR,                         |
|-----------------------------------------------------------------------------|
|ProbabilityVariableName=>"q");                                               |
+-----------------------------------------------------------------------------+
|i6 : coefficientRing PR2                                                     |
|                                                                             |
|o6 = RR                                                                      |
|       53                                                                    |
|                                                                             |
|o6 : RealField                                                               |
+-----------------------------------------------------------------------------+
|i7 : pairs PR2#"probabilityVariable"                                         |
|                                                                             |
|o7 = {(indexes, {{0, 0, 0}, {0, 0, 1}, {0, 1, 0}, {0, 1, 1}, {0, 2, 0}, {0,  |
|                                                                             |
|     ------------------------------------------------------------------------|
|     2, 1}, {1, 0, 0}, {1, 0, 1}, {1, 1, 0}, {1, 1, 1}, {1, 2, 0}, {1, 2,    |
|                                                                             |
|     ------------------------------------------------------------------------|
|     1}}), ({1, 1, 0}, q         ), ({1, 1, 1}, q         ), ({1, 0, 0}, q   |
|                        {1, 1, 0}                {1, 1, 1}                {1,|
|     ------------------------------------------------------------------------|
|          ), ({0, 2, 0}, q         ), ({1, 0, 1}, q         ), ({0, 2, 1},   |
|     0, 0}                {0, 2, 0}                {1, 0, 1}                 |
|     ------------------------------------------------------------------------|
|     q         ), ({0, 1, 0}, q         ), ({0, 1, 1}, q         ), (format, |
|      {0, 2, 1}                {0, 1, 0}                {0, 1, 1}            |
|     ------------------------------------------------------------------------|
|     {2, 3, 2}), ({0, 0, 0}, q         ), ({0, 0, 1}, q         ), ({1, 2,   |
|                              {0, 0, 0}                {0, 0, 1}             |
|     ------------------------------------------------------------------------|
|     0}, q         ), ({1, 2, 1}, q         ), (coefficients, PR2)}          |
|          {1, 2, 0}                {1, 2, 1}                                 |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

Some functions such as spohnIdeal, konstanzMatrix,
see ciIdeal, or spohnCI,  require
the ring to be created by this function or in a similar manner.

See also
========

  * spohnIdeal -- compute the ideal of the Spohn variety of
    a given game
  * konstanzMatrix -- construct the Konstanz matrix of a
    given game
  * ciIdeal -- the ideal of a list of conditional independence
    statements
  * spohnCI -- ideal of the Spohn conditional independence (CI)
    variety

Ways to use probabilityRing:
============================

  * "probabilityRing(List)"

For the programmer
==================

The object probabilityRing, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1546:0.

probabilitySumIdeal -- ideal enforcing that a probability distribution sums to 1
********************************************************************************

  * Usage:
        probabilitySumIdeal R
  * Inputs:
      * R, a ring (Macaulay2Doc), a ring typically from
        probabilityRing,
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal generated by the sum of
        all probabilities minus 1

Description
===========

Constructs the ideal expressing normalization of a joint probability
distribution. If given a list, it first calls probabilityRing,
with default options.

+-----------------------------------------------------------------------------+
|i1 : R = probabilityRing {2,3,4};                                            |
+-----------------------------------------------------------------------------+
|i2 : probabilitySumIdeal R                                                   |
|                                                                             |
|o2 = ideal(p          + p          + p          + p          + p          +  |
|            {0, 0, 0}    {0, 0, 1}    {0, 0, 2}    {0, 0, 3}    {0, 1, 0}    |
|     ------------------------------------------------------------------------|
|     p          + p          + p          + p          + p          + p      |
|      {0, 1, 1}    {0, 1, 2}    {0, 1, 3}    {0, 2, 0}    {0, 2, 1}    {0, 2,|
|     ------------------------------------------------------------------------|
|        + p          + p          + p          + p          + p          +   |
|     2}    {0, 2, 3}    {1, 0, 0}    {1, 0, 1}    {1, 0, 2}    {1, 0, 3}     |
|     ------------------------------------------------------------------------|
|     p          + p          + p          + p          + p          + p      |
|      {1, 1, 0}    {1, 1, 1}    {1, 1, 2}    {1, 1, 3}    {1, 2, 0}    {1, 2,|
|     ------------------------------------------------------------------------|
|        + p          + p          - 1)                                       |
|     1}    {1, 2, 2}    {1, 2, 3}                                            |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * spohnIdeal -- compute the ideal of the Spohn variety of
    a given game
  * spohnCI -- ideal of the Spohn conditional independence (CI)
    variety

Ways to use probabilitySumIdeal:
================================

  * "probabilitySumIdeal(Ring)"

For the programmer
==================

The object probabilitySumIdeal, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1577:0.

ProbabilityVariableName
***********************

Functions with optional argument named ProbabilityVariableName:
===============================================================

  * probabilityRing(...,ProbabilityVariableName=>...) (missing documentation)

For the programmer
==================

The object ProbabilityVariableName (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in currentString:1:388.

randomGame -- construct a game of a given format with arbitrary payoffs
***********************************************************************

  * Usage:
        randomGame(Di)
  * Inputs:
      * Di, a list (Macaulay2Doc), a list describing the format of
        the game
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (missing documentation) => ..., default value QQ,
  * Outputs:
      * a list (Macaulay2Doc), a list of n tensors of the given
        format that are the payoff tensors of a random game

Description
===========

The list $Di$ represents the format of the game. This example creates a random
game of format $2 \times 2$.

+--------------------------------------------------------+
|i1 : X = randomGame({2,2});                             |
+--------------------------------------------------------+
|i2 : peek X#0                                           |
|                                                        |
|o2 = Tensor{coefficients => QQ                         }|
|            format => {2, 2}                            |
|            indexes => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
|                      3                                 |
|            {1, 0} => -                                 |
|                      4                                 |
|                      7                                 |
|            {1, 1} => -                                 |
|                      4                                 |
|                      9                                 |
|            {0, 0} => -                                 |
|                      2                                 |
|                      9                                 |
|            {0, 1} => -                                 |
|                      4                                 |
+--------------------------------------------------------+
|i3 : peek X#1                                           |
|                                                        |
|o3 = Tensor{coefficients => QQ                         }|
|            format => {2, 2}                            |
|            indexes => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
|                       7                                |
|            {0, 1} => --                                |
|                      10                                |
|                       7                                |
|            {1, 0} => --                                |
|                      10                                |
|                      7                                 |
|            {0, 0} => -                                 |
|                      9                                 |
|                      7                                 |
|            {1, 1} => -                                 |
|                      3                                 |
+--------------------------------------------------------+

The optional argument CoefficientRing allows to change the ring of payoffs. If
no coefficient choice is specified, the payoffs will be rational numbers. This
example creates a random game of format $2 \times 2$ with integer coefficients.

+--------------------------------------------------------+
|i4 : X = randomGame({2,2}, CoefficientRing => ZZ);      |
+--------------------------------------------------------+
|i5 : peek X#0                                           |
|                                                        |
|o5 = Tensor{{0, 0} => 6                                }|
|            {0, 1} => 0                                 |
|            {1, 0} => 2                                 |
|            {1, 1} => 6                                 |
|            coefficients => ZZ                          |
|            format => {2, 2}                            |
|            indexes => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
+--------------------------------------------------------+
|i6 : peek X#1                                           |
|                                                        |
|o6 = Tensor{{0, 0} => 9                                }|
|            {0, 1} => 3                                 |
|            {1, 0} => 5                                 |
|            {1, 1} => 6                                 |
|            coefficients => ZZ                          |
|            format => {2, 2}                            |
|            indexes => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
+--------------------------------------------------------+

Outputs of this function can be used as input for the functions
nashEquilibriumIdeal,
spohnMatrices, spohnIdeal, and
konstanzMatrix.

See also
========

  * nashEquilibriumIdeal -- make
    the Nash Equilibrium ideal
  * spohnMatrices -- compute the list of Spohn matrices
    of a given game
  * spohnIdeal -- compute the ideal of the Spohn variety of
    a given game
  * konstanzMatrix -- construct the Konstanz matrix of a
    given game

Ways to use randomGame:
=======================

  * randomGame(List) (missing documentation)

For the programmer
==================

The object randomGame, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1620:0.

randomTensor -- construct a tensor with random entries from a given ring
************************************************************************

  * Usage:
        randomTensor format
        randomTensor(R, format)
  * Inputs:
      * format, a list (Macaulay2Doc), A list of integers
        specifying the format of the tensor (e.g. {2,2,2} creates a 2x2x2
        tensor)
      * R, a ring (Macaulay2Doc), (Optional) A ring from which
        random coefficients will be drawn.
  * Outputs:
      * an instance of the type Tensor, A tensor whose entries
        are randomly selected elements of the ring.

Description
===========

This method constructs a tensor with the specified format and fills it with
random elements from the given ring. Internally, it uses a hash table where
each key is a multi-index (a list of positions) and the value is a random
element from the ring. Metadata such as the format, coefficient ring, and index
set are stored in the tensor as well.

+--------------------------------------------------------+
|i1 : T1 = randomTensor {2,2,2};                         |
+--------------------------------------------------------+
|i2 : T1#{0,1,1}                                         |
|                                                        |
|     7                                                  |
|o2 = -                                                  |
|     4                                                  |
|                                                        |
|o2 : QQ                                                 |
+--------------------------------------------------------+
|i3 : T2 = randomTensor(ZZ/101, {2,2});                  |
+--------------------------------------------------------+
|i4 : peek T2                                            |
|                                                        |
|o4 = Tensor{{0, 0} => 16                               }|
|            {0, 1} => 22                                |
|            {1, 0} => 45                                |
|            {1, 1} => -34                               |
|            format => {2, 2}                            |
|            indexes => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
|                             ZZ                         |
|            coefficients => ---                         |
|                            101                         |
+--------------------------------------------------------+

See also
========

  * zeroTensor -- construct a tensor with zero entries from
    a given ring.

Ways to use randomTensor:
=========================

  * "randomTensor(List)"
  * "randomTensor(Ring,List)"

For the programmer
==================

The object randomTensor, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1107:0.

slice -- extract a slice of a tensor
************************************

  * Usage:
        slice(T, Lstart, Lend)
  * Inputs:
      * T, an instance of the type Tensor, A tensor from which
        to extract the slice.
      * Lstart, a list (Macaulay2Doc), A list of fixed indices
        before the varying position.
      * Lend, a list (Macaulay2Doc), A list of fixed indices after
        the varying position.
  * Outputs:
      * a list (Macaulay2Doc), A list of entries of the tensor
        along the specified dimension.

Description
===========

This method varies the index at the position given by the length of Lstart,
iterating from 0 to $d_i - 1$, where $d_i$ is the corresponding index of the
format.

The slice is formed by fixing all other indices and varying only the one at the
slicing position.

+---------------------------------+
|i1 : T = zeroTensor(QQ, {2,3,2});|
+---------------------------------+
|i2 : T#{0,0,0} = 5;              |
+---------------------------------+
|i3 : T#{0,1,0} = 6;              |
+---------------------------------+
|i4 : T#{0,2,0} = 7;              |
+---------------------------------+
|i5 : slice(T, {0}, {0})          |
|                                 |
|o5 = {5, 6, 7}                   |
|                                 |
|o5 : List                        |
+---------------------------------+

See also
========

  * enumerateTensorIndices -- generate index
    tuples for a tensor with given dimensions
  * Tensor -- a mutable hash table representing a tensor

Ways to use slice:
==================

  * "slice(Tensor,List,List)"

For the programmer
==================

The object slice, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1146:0.

spohnCI -- ideal of the Spohn conditional independence (CI) variety
*******************************************************************

  * Usage:
        spohnCI(PR, X, G)
        spohnCI(PR, X, G, PlayerNames)
        spohnCI(PR, X, Stmts)
        spohnCI(PR, X, Stmts, PlayerNames)
  * Inputs:
      * PR, a ring (Macaulay2Doc), the probability ring (must be
        created with probabilityRing)
      * X, a list (Macaulay2Doc), the n tensors defining the game
      * G, a graph (Graphs), the graph specifying the conditional
        independence conditions
      * Stmts, a list (Macaulay2Doc), a list of lists {L1,L2,L3}
        corresponding to the relation "L1 and L2 are conditionally independent
        given L3".
      * PlayerNames, a list (Macaulay2Doc), the ordered list of
        players - the names of the random variables in the conditional
        independence statements or vertices of the graph. If PlayerNames is
        omitted, the players (or the vertices of G) are assumed to be labelled
        1..n.
  * Optional inputs (Macaulay2Doc),:
      * Verbose (missing documentation) => ..., default value false,
  * Outputs:
      * an ideal (Macaulay2Doc), The ideal of the Spohn CI variety

Description
===========

spohnCI computes the ideal of the Spohn conditional independence variety for a
game $X$ and conditional independence model determined by an undirected graph
$G$ or set of conditional independence statements $Stmts$.

The input for the conditional independence model can be a set of conditional
probability statements or an undirected graph. A single conditional
independence statement is a list consisting of three disjoint lists of indices
for players, e.g. $\{ \{1,2\},\{4\}, \{3\} \}$ which represents the conditional
independence statement "The strategies of Players 1 and 2 are conditionally
independent of Player 4's strategy given Player 3's strategy".

Given an undirected graph $G$, the conditional independence statements are
produced via the globalMarkov function from the GraphicalModels package. A
global Markov statement for $G$ is a list $\{A, B, C\}$ of three disjoint lists
of vertices of $G$, where the subset $C$ separates the subset $A$ from the
subset $B$ in the graph $G$.

+----------------------------------------------------+
|i1 : FF = ZZ/32003;                                 |
+----------------------------------------------------+
|i2 : d = {2,2,2};                                   |
+----------------------------------------------------+
|i3 : X = randomGame(d, CoefficientRing => FF);      |
+----------------------------------------------------+
|i4 : PR = probabilityRing(d, CoefficientRing => FF);|
+----------------------------------------------------+
|i5 : G1 = graph ({}, Singletons => {1,2,3});        |
+----------------------------------------------------+
|i6 : G2 = graph ({{1,2}}, Singletons => {3});       |
+----------------------------------------------------+
|i7 : I1 = spohnCI(PR,X,G1);                         |
|                                                    |
|o7 : Ideal of PR                                    |
+----------------------------------------------------+
|i8 : I2 = spohnCI(PR,X,G2);                         |
|                                                    |
|o8 : Ideal of PR                                    |
+----------------------------------------------------+

Here is an example where the vertices of the graph need to be relabeled.

+-----------------------------------------------------+
|i9 : FF = ZZ/32003;                                  |
+-----------------------------------------------------+
|i10 : d = {2,3,2};                                   |
+-----------------------------------------------------+
|i11 : X = randomGame(d, CoefficientRing => FF);      |
+-----------------------------------------------------+
|i12 : PR = probabilityRing(d, CoefficientRing => FF);|
+-----------------------------------------------------+
|i13 : G1 = graph {{John,Matthew},{Matthew,Sarah}};   |
+-----------------------------------------------------+
|i14 : G2 = graph {{a,b},{b,c},{c,a}};                |
+-----------------------------------------------------+
|i15 : I1 = spohnCI(PR,X,G1, {John,Matthew,Sarah});   |
|                                                     |
|o15 : Ideal of PR                                    |
+-----------------------------------------------------+
|i16 : I2 = spohnCI(PR,X,G2, {a,b,c});                |
|                                                     |
|o16 : Ideal of PR                                    |
+-----------------------------------------------------+

Here is an example where the conditional independence relations are given with
a List.

+-----------------------------------------------------+
|i17 : FF = ZZ/32003;                                 |
+-----------------------------------------------------+
|i18 : d = {2,2,2};                                   |
+-----------------------------------------------------+
|i19 : X = randomGame(d, CoefficientRing => FF);      |
+-----------------------------------------------------+
|i20 : PR = probabilityRing(d, CoefficientRing => FF);|
+-----------------------------------------------------+
|i21 : G = graph ({{1,2}},Singletons => {3});         |
+-----------------------------------------------------+
|i22 : L = {{{1,2},{3},{}}};                          |
+-----------------------------------------------------+
|i23 : I1 = spohnCI(PR,X,G);                          |
|                                                     |
|o23 : Ideal of PR                                    |
+-----------------------------------------------------+
|i24 : I2 = spohnCI(PR,X,L);                          |
|                                                     |
|o24 : Ideal of PR                                    |
+-----------------------------------------------------+
|i25 : I1 == I2                                       |
|                                                     |
|o25 = true                                           |
+-----------------------------------------------------+

The Verbose=>true option prints the progress of each step in the saturation
process - a message is printed after saturating the ideal of the Spohn variety
$V$, the conditional independence ideal $I$, and the sum $V + I$ with respect
to each hyperplane of the probability simplex.

+-----------------------------------------------------+
|i26 : FF = ZZ/32003;                                 |
+-----------------------------------------------------+
|i27 : d = {2,3,2};                                   |
+-----------------------------------------------------+
|i28 : X = randomGame(d, CoefficientRing => FF);      |
+-----------------------------------------------------+
|i29 : PR = probabilityRing(d, CoefficientRing => FF);|
+-----------------------------------------------------+
|i30 : L = {{{1,2},{3},{}}};                          |
+-----------------------------------------------------+
|i31 : I = spohnCI(PR, X, L, Verbose=>true);          |
|Completed step 1 of saturating CI ideal              |
|Completed step 1 of saturating input ideal           |
|Completed step 2 of saturating CI ideal              |
|Completed step 2 of saturating input ideal           |
|Completed step 3 of saturating CI ideal              |
|Completed step 3 of saturating input ideal           |
|Completed step 4 of saturating CI ideal              |
|Completed step 4 of saturating input ideal           |
|Completed step 5 of saturating CI ideal              |
|Completed step 5 of saturating input ideal           |
|Completed step 6 of saturating CI ideal              |
|Completed step 6 of saturating input ideal           |
|Completed step 7 of saturating CI ideal              |
|Completed step 7 of saturating input ideal           |
|Completed step 8 of saturating CI ideal              |
|Completed step 8 of saturating input ideal           |
|Completed step 9 of saturating CI ideal              |
|Completed step 9 of saturating input ideal           |
|Completed step 10 of saturating CI ideal             |
|Completed step 10 of saturating input ideal          |
|Completed step 11 of saturating CI ideal             |
|Completed step 11 of saturating input ideal          |
|Completed step 12 of saturating CI ideal             |
|Completed step 12 of saturating input ideal          |
|Completed step 13 of saturating CI ideal             |
|Completed step 13 of saturating input ideal          |
|Completed step 1 of saturating sum                   |
|Completed step 2 of saturating sum                   |
|Completed step 3 of saturating sum                   |
|Completed step 4 of saturating sum                   |
|Completed step 5 of saturating sum                   |
|Completed step 6 of saturating sum                   |
|Completed step 7 of saturating sum                   |
|Completed step 8 of saturating sum                   |
|Completed step 9 of saturating sum                   |
|Completed step 10 of saturating sum                  |
|Completed step 11 of saturating sum                  |
|Completed step 12 of saturating sum                  |
|                                                     |
|o31 : Ideal of PR                                    |
+-----------------------------------------------------+

See also
========

  * spohnIdeal -- compute the ideal of the Spohn variety of
    a given game
  * ciIdeal -- the ideal of a list of conditional independence
    statements
  * intersectWithCImodel -- ideal of the
    intersection of a given variety with the conditional independence model
  * conditionalIndependenceIdeal (GraphicalModels)
    -- ideal of a list of
    conditional independent statements

Ways to use spohnCI:
====================

  * "spohnCI(Ring,List,Graph)"
  * "spohnCI(Ring,List,Graph,List)"
  * "spohnCI(Ring,List,List)"
  * "spohnCI(Ring,List,List,List)"

For the programmer
==================

The object spohnCI, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:2169:0.

spohnIdeal -- compute the ideal of the Spohn variety of a given game
********************************************************************

  * Usage:
        spohnIdeal(PR,X)
  * Inputs:
      * PR, a ring (Macaulay2Doc), a probability ring obtained via
        probabilityRing(Di), where $Di$ is the format of the game
      * X, a list (Macaulay2Doc), a list of n tensors of format
        $D_i$ describing the payoffs of the game
  * Outputs:
      * a list (Macaulay2Doc), the ideal generated by the $2\times
        2$ minors of the Spohn matrices of the game $X$

Description
===========

It is crucial that the formats in PR and X match up. The Spohn ideal $I_X$ is
the ideal defining the Spohn variety of a game $X$, which contains the
dependency equilibria of the game $X$. Its generators are given by the $2\times
2$ minors of the Spohn matrices. This function uses the function spohnMatrices
to compute the Spohn matrices of the given game.

+------------------------------+
|i1 : Di = {2,2,3};            |
+------------------------------+
|i2 : PR = probabilityRing(Di);|
+------------------------------+
|i3 : X = randomGame(Di);      |
+------------------------------+
|i4 : I = spohnIdeal(PR,X);    |
|                              |
|o4 : Ideal of PR              |
+------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * randomGame -- construct a game of a given format with
    arbitrary payoffs
  * spohnMatrices -- compute the list of Spohn matrices
    of a given game
  * konstanzMatrix -- construct the Konstanz matrix of a
    given game

Ways to use spohnIdeal:
=======================

  * spohnIdeal(Ring,List) (missing documentation)

For the programmer
==================

The object spohnIdeal, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1695:0.

spohnMatrices -- compute the list of Spohn matrices of a given game
*******************************************************************

  * Usage:
        spohnMatrices(PR,X)
  * Inputs:
      * PR, a ring (Macaulay2Doc), a probability ring obtained via
        probabilityRing(Di), where $Di$ is the format of the game
      * X, a list (Macaulay2Doc), a list of n tensors of format
        $D_i$ describing the payoffs of the game
  * Outputs:
      * a list (Macaulay2Doc), the list of n Spohn matrices
        describing the dependency equilibria of the game $X$

Description
===========

It is crucial that the formats in PR and X match up. The Spohn matrix $M_i$ is
the $d_i \times 2$ matrix encoding the denominators and nominators of the
conditional expected payoffs of the $i$-th player. The Spohn matrices have rank
one at the dependency equilibria of the game $X$.

+-----------------------------------------------------------------------------+
|i1 : Di = {2,2,3};                                                           |
+-----------------------------------------------------------------------------+
|i2 : PR = probabilityRing(Di);                                               |
+-----------------------------------------------------------------------------+
|i3 : X = randomGame(Di);                                                     |
+-----------------------------------------------------------------------------+
|i4 : M = spohnMatrices(PR,X)                                                 |
|                                                                             |
|o4 = {| p_{0, 0, 0}+p_{0, 0, 1}+p_{0, 0, 2}+p_{0, 1, 0}+p_{0, 1, 1}+p_{0, 1, |
|      | p_{1, 0, 0}+p_{1, 0, 1}+p_{1, 0, 2}+p_{1, 1, 0}+p_{1, 1, 1}+p_{1, 1, |
|                                                                             |
|     ------------------------------------------------------------------------|
|     2} 9/2p_{0, 0, 0}+9/4p_{0, 0, 1}+3/4p_{0, 0, 2}+7/4p_{0, 1, 0}+7/9p_{0, |
|     2} 7/10p_{1, 0, 0}+7/3p_{1, 0, 1}+7p_{1, 0, 2}+3/7p_{1, 1, 0}+6/7p_{1, 1|
|                                                                             |
|     ------------------------------------------------------------------------|
|     1, 1}+7/10p_{0, 1, 2} |, | p_{0, 0, 0}+p_{0, 0, 1}+p_{0, 0, 2}+p_{1, 0, |
|     , 1}+6p_{1, 1, 2}     |  | p_{0, 1, 0}+p_{0, 1, 1}+p_{0, 1, 2}+p_{1, 1, |
|                                                                             |
|     ------------------------------------------------------------------------|
|     0}+p_{1, 0, 1}+p_{1, 0, 2} 5/4p_{0, 0,                                  |
|     0}+p_{1, 1, 1}+p_{1, 1, 2} 3/7p_{0, 1,                                  |
|                                                                             |
|     ------------------------------------------------------------------------|
|     0}+2/9p_{0, 0, 1}+3/10p_{0, 0, 2}+10p_{1, 0, 0}+3/2p_{1, 0, 1}+7/8p_{1, |
|     0}+5p_{0, 1, 1}+10/9p_{0, 1, 2}+5/6p_{1, 1, 0}+5p_{1, 1, 1}+2/5p_{1, 1, |
|                                                                             |
|     ------------------------------------------------------------------------|
|     0, 2} |, | p_{0, 0, 0}+p_{0, 1, 0}+p_{1, 0, 0}+p_{1, 1, 0} 5/3p_{0, 0,  |
|     2}    |  | p_{0, 0, 1}+p_{0, 1, 1}+p_{1, 0, 1}+p_{1, 1, 1} 7/2p_{0, 0,  |
|              | p_{0, 0, 2}+p_{0, 1, 2}+p_{1, 0, 2}+p_{1, 1, 2} 2/5p_{0, 0,  |
|     ------------------------------------------------------------------------|
|     0}+6/5p_{0, 1, 0}+5/3p_{1, 0, 0}+3/7p_{1, 1, 0}   |}                    |
|     1}+5/7p_{0, 1, 1}+1/10p_{1, 0, 1}+9/10p_{1, 1, 1} |                     |
|     2}+5/9p_{0, 1, 2}+4/3p_{1, 0, 2}+4/7p_{1, 1, 2}   |                     |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * randomGame -- construct a game of a given format with
    arbitrary payoffs
  * spohnIdeal -- compute the ideal of the Spohn variety of
    a given game
  * konstanzMatrix -- construct the Konstanz matrix of a
    given game

Ways to use spohnMatrices:
==========================

  * spohnMatrices(Ring,List) (missing documentation)

For the programmer
==================

The object spohnMatrices, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1658:0.

Tensor -- a mutable hash table representing a tensor
****************************************************

  * Usage:
        T = zeroTensor(R, d)
  * Outputs:
      * an instance of the type Tensor, A Tensor object storing
        values at multi-indices.

Description
===========

The type Tensor is a mutable hash table with additional metadata to represent
multi-dimensional arrays. Each tensor has an associated format (list of
dimensions), a coefficient ring, and a set of index keys.

+-------------------------------------+
|i1 : T = zeroTensor(QQ, {2,2});      |
+-------------------------------------+
|i2 : T#{0,0} = 1;                    |
+-------------------------------------+
|i3 : T#{1,1} = 5;                    |
+-------------------------------------+
|i4 : format T                        |
|                                     |
|o4 = {2, 2}                          |
|                                     |
|o4 : List                            |
+-------------------------------------+
|i5 : coefficientRing T               |
|                                     |
|o5 = QQ                              |
|                                     |
|o5 : Ring                            |
+-------------------------------------+
|i6 : indexset T                      |
|                                     |
|o6 = {{0, 0}, {0, 1}, {1, 0}, {1, 1}}|
|                                     |
|o6 : List                            |
+-------------------------------------+

See also
========

  * zeroTensor -- construct a tensor with zero entries from
    a given ring.
  * randomTensor -- construct a tensor with random entries
    from a given ring

Methods that use an object of class Tensor:
===========================================

  * "assemblePlayeriPolynomials(Ring,Tensor,ZZ)" -- see
    assemblePlayeriPolynomials, -- get all
    incentive constraint polynomials for a player
  * "assemblePolynomial(Ring,Tensor,List)" -- see assemblePolynomial,
    -- compute incentive constraint polynomial for
    deviation
  * coefficientRing(Tensor) (missing documentation)
  * format(Tensor) (missing documentation)
  * "indexset(Tensor)" -- see indexset, -- get the list of
    index tuples of a tensor
  * "slice(Tensor,List,List)" -- see slice, -- extract a slice of
    a tensor

For the programmer
==================

The object Tensor, is a type (Macaulay2Doc), with
ancestor classes MutableHashTable (Macaulay2Doc), <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:986:0.

toMarkovRing -- ring of joint probability distributions created with the markovRing function from the GraphicalModels package
*****************************************************************************************************************************

  * Usage:
        toMarkovRing R
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), created
        using the probabilityRing method
  * Outputs:
      * a polynomial ring (Macaulay2Doc), a polynomial
        ring isomorphic to the input ring created by the markovRing method from
        the GraphicalModels package, with variables $q_{(i_1+1, \dots ,
        i_k+1)}$ corresponding to the variables $p_{\{i_1, \ldots, i_k\}}$ of
        the input ring

Description
===========

Given a ring created with the probabilityRing function, this function creates
the canonically isomorphic ring defined by the markovRing function from the
GraphicalModels package. The variable name of the output ring is set to be
different from the variable name of the input ring: the default variable name
of the output ring is "p", and if the variable name of the input ring is "p"
then the variable name of the output ring becomes "q".

+-----------------------------------------------------------------------------+
|i1 : R = probabilityRing({2,3,4}, CoefficientRing => ZZ/32003,               |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
|-----------------------------------------------------------------------------|
|ProbabilityVariableName => "x")                                              |
+-----------------------------------------------------------------------------+
|i2 : markovR = toMarkovRing R;                                               |
+-----------------------------------------------------------------------------+
|i3 : numgens markovR                                                         |
|                                                                             |
|o3 = 24                                                                      |
+-----------------------------------------------------------------------------+
|i4 : R_0, R_11, R_23                                                         |
|                                                                             |
|o4 = (x         , x         , x         )                                    |
|       {0, 0, 0}   {0, 2, 3}   {1, 2, 3}                                     |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * probabilityRing -- ring of probability
    distributions of a game indexed by ordered multi-indices
  * gaussianRing (GraphicalModels) -- ring of Gaussian
    correlations on n random variables or a graphical model

Ways to use toMarkovRing:
=========================

  * "toMarkovRing(Ring)"

For the programmer
==================

The object toMarkovRing, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1779:0.

zeroTensor -- construct a tensor with zero entries from a given ring.
*********************************************************************

  * Usage:
        zeroTensor format
        zeroTensor(R, format)
  * Inputs:
      * format, a list (Macaulay2Doc), A list of integers
        specifying the format of the tensor (e.g., {2,2,2} creates a 2x2x2
        tensor with zero entries).
      * R, a ring (Macaulay2Doc), A ring from which zeros will be
        drawn (optional).
  * Outputs:
      * an instance of the type Tensor, A tensor whose entries
        are all zero.

Description
===========

This method constructs a tensor with the specified format and fills it with
zeros from the given ring. Internally, it uses a hash table where each key is a
multi-index (a list of positions). Metadata such as the format, coefficient
ring, and index set are stored in the tensor as well. It is useful for defining
a custom tensor.

+--------------------------------------------------------+
|i1 : T = zeroTensor {2,2};                              |
+--------------------------------------------------------+
|i2 : T#{0,0} = 1;                                       |
+--------------------------------------------------------+
|i3 : T#{0,1} = 2;                                       |
+--------------------------------------------------------+
|i4 : T#{1,0} = 3;                                       |
+--------------------------------------------------------+
|i5 : T#{1,1} = 4;                                       |
+--------------------------------------------------------+
|i6 : format T                                           |
|                                                        |
|o6 = {2, 2}                                             |
|                                                        |
|o6 : List                                               |
+--------------------------------------------------------+
|i7 : peek T                                             |
|                                                        |
|o7 = Tensor{{0, 0} => 1                                }|
|            {0, 1} => 2                                 |
|            {1, 0} => 3                                 |
|            {1, 1} => 4                                 |
|            coefficients => QQ                          |
|            format => {2, 2}                            |
|            indexes => {{0, 0}, {0, 1}, {1, 0}, {1, 1}} |
+--------------------------------------------------------+

See also
========

  * randomTensor -- construct a tensor with random entries
    from a given ring

Ways to use zeroTensor:
=======================

  * "zeroTensor(List)"
  * "zeroTensor(Ring,List)"

For the programmer
==================

The object zeroTensor, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in GameTheory.m2:1068:0.