Struct neumann::MatrixGame

pub struct MatrixGame { /* fields omitted */ }

Matrix games are finite zero-sum two-player games.

Examples

Rock-paper-scisors.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
MatrixGame::from(rewards);

Implementations

impl MatrixGame

pub fn is_empty(&self) -> bool

Return whether the array has any elements

pub fn is_square(&self) -> bool

Returns true if both players have the same number of possible actions.

Examples

Rock-paper-scisors is a square game.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
let matrix_game = MatrixGame::from(rewards);
assert!(matrix_game.is_square());

A 2x3 game is not square.

let rewards = array![[0, 1, -1], [0, -1, 2]];
let matrix_game = MatrixGame::from(rewards);
assert!(!matrix_game.is_square());

pub fn is_completely_mixed(&self) -> bool

Returns true if both players have the same number of possible actions and a unique optimal strategy which has full support¹.

Examples

Rock-paper-scisors is a completely-mixed game.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
let matrix_game = MatrixGame::from(rewards);
assert!(matrix_game.is_completely_mixed());

A game with dominant strategies is not completely-mixed.

let rewards = array![[0, 2, 1], [2, 0, 1], [-1, -1, -1]];
let matrix_game = MatrixGame::from(rewards);
assert!(!matrix_game.is_completely_mixed());

---

1. Kaplansky, I. (1945). A Contribution to Von Neumann's Theory of Games. Annals of Mathematics, 46(3), second series, 474-479. doi:10.2307/1969164 ↩

pub fn reduce_to_square(&mut self)

Reduces the matrix game to a square sub-game with the same value and whose optimal strategies are also optimal in the original game.

If the matrix game has dimensions mxn, then the resulting matrix game has dimensions min(m, n)xmin(m, n).

Examples

Rock-paper-scisors can not be reduce further, so it stays the same.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
let mut matrix_game = MatrixGame::from(rewards);
matrix_game.reduce_to_square();
assert_eq!(matrix_game.matrix(), &array![[0., 1., -1.], [1., -1., 0.], [-1., 0., 1.]]);

A game with a rectangular shape can be reduced.

let rewards = array![[0, 2], [2, 0], [-1, -1]];
let mut matrix_game = MatrixGame::from(rewards);
matrix_game.reduce_to_square();
assert_eq!(matrix_game.matrix(), &array![[0., 2.], [2., 0.]]);

pub fn kernel_completely_mixed(&self) -> (Vec<usize>, Vec<usize>, MatrixGame)

Returns the indices, together with the corresponding sub-matrix game, of a square sub-matrix which is completely-mixed¹ whose value is the same as the original game.

The first vector of indices corresponds to actions of the row player. The second vector of indices corresponds to actions of the column player.

See is_completely_mixed method for an explanation of completely-mixed matrix games.

Examples

Rock-paper-scisors is already completely-mixed so its kernel is the whole game.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
let matrix_game = MatrixGame::from(rewards.clone());
let (kernel_rows, kernel_columns, kernel_matrix_game) = matrix_game.kernel_completely_mixed();
assert_eq!(kernel_rows, vec![0, 1, 2]);
assert_eq!(kernel_columns, vec![0, 1, 2]);
assert_eq!(kernel_matrix_game, MatrixGame::from(rewards));

A game with a rectangular shape.

let rewards = array![[0, 2], [2, 0], [-1, -1]];
let matrix_game = MatrixGame::from(rewards);
let (kernel_rows, kernel_columns, kernel_matrix_game) = matrix_game.kernel_completely_mixed();
assert_eq!(kernel_rows, vec![0, 1]);
assert_eq!(kernel_columns, vec![0, 1]);
assert_eq!(kernel_matrix_game, MatrixGame::from(array![[0, 2], [2, 0]]));

---

1. Kaplansky, I. (1945). A Contribution to Von Neumann's Theory of Games. Annals of Mathematics, 46(3), second series, 474-479. doi:10.2307/1969164 ↩

pub fn reduce_row_best(&self) -> usize

Returns the least beneficial action for the row player.

In other words, if this action is prohibited for the row player, then the value of the restricted game diminishes the least.

Panics

If the game is empty.

Examples

Forgetting about the worst action for the row player.

let rewards = array![[0, 1], [1, 0], [-1, -1]];
let matrix_game = MatrixGame::from(rewards);
assert_eq!(matrix_game.reduce_row_best(), 2);

pub fn reduce_column_best(&self) -> usize

Returns the least beneficial action for the column player.

In other words, if this action is prohibited for the column player, then the value of the restricted game increases the least.

Panics

If the game is empty.

Examples

Forgetting about the worst action for the column player.

let rewards = array![[1, 0, -1], [1, -1, 0]];
let matrix_game = MatrixGame::from(rewards);
assert_eq!(matrix_game.reduce_column_best(), 0);

pub fn reduce_row(&self, row: usize) -> MatrixGame

Returns a matrix game with one action less for the row player.

Examples

Forgetting about the first action for the row player.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
let matrix_game = MatrixGame::from(rewards);
let sub_matrix_game = matrix_game.reduce_row(0);
assert_eq!(sub_matrix_game.matrix(), &array![[1., -1., 0.], [-1., 0., 1.]]);

Forgetting about the last action for the row player.

let rewards = array![[1, 2, 3], [4, 5, 6], [7, 8, 9]];
let matrix_game = MatrixGame::from(rewards);
let sub_matrix_game = matrix_game.reduce_row(2);
assert_eq!(sub_matrix_game.matrix(), &array![[1., 2., 3.], [4., 5., 6.]]);

pub fn reduce_column(&self, column: usize) -> MatrixGame

Returns a matrix game with one action less for the column player.

Examples

Forgetting about the last action for the column player.

let rewards = array![[0, 1, -1], [1, -1, 0], [-1, 0, 1]];
let matrix_game = MatrixGame::from(rewards);
let sub_matrix_game = matrix_game.reduce_column(2);
assert_eq!(sub_matrix_game.matrix(), &array![[0., 1.], [1., -1.], [-1., 0.]]);

Forgetting about the first action for the column player.

let rewards = array![[1, 2, 3], [4, 5, 6], [7, 8, 9]];
let matrix_game = MatrixGame::from(rewards);
let sub_matrix_game = matrix_game.reduce_column(2);
assert_eq!(sub_matrix_game.matrix(), &array![[1., 2.], [4., 5.], [7., 8.]]);

pub fn matrix(&self) -> &Array2<f64>

Returns the reward matrix for the row player.

pub fn solve_row(&self) -> (Vec<f64>, f64)

Returns an optimal strategy for the row player and the value of the game, i.e. the value this player can ensure.

pub fn value(&self) -> f64

Returns the value of the game.

pub fn solve(&self) -> (Vec<f64>, Vec<f64>, f64)

Returns a Nash equilibrium and the value of the game.

pub fn shape(&self) -> [usize; 2]

Shape of the matrix game.

First the number of row actions, then the number of column actions.

pub fn actions_row(&self) -> usize

Number of row actions

pub fn actions_column(&self) -> usize

Number of column actions

Trait Implementations

impl Clone for MatrixGame

fn clone(&self) -> MatrixGame

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MatrixGame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for MatrixGame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> From<ArrayBase<OwnedRepr<T>, Dim<[usize; 2]>>> for MatrixGame where
    T: Into<f64> + Clone, 

fn from(matrix: Array2<T>) -> Self

Performs the conversion.

impl Into<ArrayBase<OwnedRepr<f64>, Dim<[usize; 2]>>> for MatrixGame

fn into(self) -> Array2<f64>

Performs the conversion.

impl PartialEq<MatrixGame> for MatrixGame

fn eq(&self, other: &MatrixGame) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &MatrixGame) -> bool

This method tests for !=.

impl Playable for MatrixGame

fn play(&self)

Starts a REPL to play the game.

The user is asked to input a strategy, one probability at a time. For robustness, inputs are read as weights: a renormalization is performed to obtain the mixed strategy.

Remarks

Values are parsed using the fasteval crate, accepting a big range of inputs.

impl StructuralPartialEq for MatrixGame