Skip to main content

Crate game_theory_core

Crate game_theory_core 

Source
Expand description

Exact game-theoretic computation.

No I/O, no async, no protocol handling. A caller-supplied StrategicGame passes through ValidStrategicGame::validate once; every solver takes that type, so an unchecked game cannot reach a solver.

Payoffs cross the API as f64 but are stored and computed as exact rationals, so there is no tolerance anywhere and answers match published textbook solutions exactly.

use game_theory_core::game::{MatrixForm, PayoffKind, StrategicGame, ValidStrategicGame};
use game_theory_core::solve::pure_nash::solve_pure_nash;

let matrix = MatrixForm {
    players: ["Row".into(), "Col".into()],
    row_strategies: vec!["Cooperate".into(), "Defect".into()],
    col_strategies: vec!["Cooperate".into(), "Defect".into()],
    payoff_matrix: vec![
        vec![[3.0, 3.0], [0.0, 4.0]],
        vec![[4.0, 0.0], [1.0, 1.0]],
    ],
    payoff_kind: PayoffKind::Cardinal,
};

let game = ValidStrategicGame::validate(StrategicGame::try_from(matrix)?)?;
let result = solve_pure_nash(&game);

// Both players defect: the unique equilibrium, and worse for both than
// mutual cooperation.
assert_eq!(result.equilibria, vec![vec![1, 1]]);

Extensive-form (game-tree) games take the same route — validate once, then solve. Backward induction returns every subgame-perfect equilibrium:

use game_theory_core::game::Player;
use game_theory_core::{solve_backward_induction, ExtensiveGame, Node, PayoffKind, ValidExtensiveGame};

// The Entrant moves first; if it enters, the Incumbent chooses whether to
// fight. Fighting hurts the Incumbent too, so the threat is not credible.
let game = ExtensiveGame {
    players: vec![
        Player { id: 0, name: "Entrant".into() },
        Player { id: 1, name: "Incumbent".into() },
    ],
    root: 0,
    nodes: vec![
        Node::Decision { player: 0, actions: vec![("In".into(), 1), ("Out".into(), 2)] },
        Node::Decision { player: 1, actions: vec![("Fight".into(), 3), ("Accommodate".into(), 4)] },
        Node::Terminal { payoffs: vec![0.0, 2.0] },
        Node::Terminal { payoffs: vec![-1.0, -1.0] },
        Node::Terminal { payoffs: vec![1.0, 1.0] },
    ],
    information_sets: vec![vec![0], vec![1]],
    payoff_kind: PayoffKind::Cardinal,
};

let game = ValidExtensiveGame::validate(game)?;
let result = solve_backward_induction(&game)?;

// Unique equilibrium: the Entrant enters and the Incumbent accommodates.
assert_eq!(result.solutions.len(), 1);
assert_eq!(result.solutions[0].path, vec![(0, 0), (1, 1)]);

Repeating a stage game changes what is sustainable. Grim trigger with Nash reversion gives the exact patience cooperation requires:

use game_theory_core::{
    analyze_repeated_game, MatrixForm, PayoffKind, Punishment, Rational,
    StrategicGame, ValidStrategicGame,
};

let matrix = MatrixForm {
    players: ["Row".into(), "Col".into()],
    row_strategies: vec!["Cooperate".into(), "Defect".into()],
    col_strategies: vec!["Cooperate".into(), "Defect".into()],
    payoff_matrix: vec![
        vec![[3.0, 3.0], [0.0, 4.0]],
        vec![[4.0, 0.0], [1.0, 1.0]],
    ],
    payoff_kind: PayoffKind::Cardinal,
};
let game = ValidStrategicGame::validate(StrategicGame::try_from(matrix)?)?;

let report = analyze_repeated_game(&game, &[0, 0], Punishment::GrimTrigger, None)?;

// Mutual cooperation is sustainable exactly when the discount factor
// reaches 1/3 — an exact fraction, not a rounded decimal.
assert_eq!(
    report.critical_discount_factor,
    Some(Rational::new(1.into(), 3.into()))
);

Re-exports§

pub use analyze::analyze_repeated_game;
pub use analyze::analyze_structure;
pub use analyze::classify;
pub use analyze::pareto_dominates;
pub use analyze::Archetype;
pub use analyze::ArchetypeReport;
pub use analyze::DominatedEquilibrium;
pub use analyze::PlayerThreshold;
pub use analyze::Punishment;
pub use analyze::RepeatedGameReport;
pub use analyze::SecurityLevel;
pub use analyze::StructureReport;
pub use error::Diagnostic;
pub use error::DiagnosticCode;
pub use error::GtError;
pub use exact::solve_linear_system;
pub use exact::solve_lp;
pub use exact::LinearSolution;
pub use exact::LpProblem;
pub use exact::LpSolution;
pub use game::plan_to_strategy_index;
pub use game::to_strategic;
pub use game::ExtensiveGame;
pub use game::MatrixForm;
pub use game::Node;
pub use game::NodeId;
pub use game::Outcome;
pub use game::PayoffKind;
pub use game::Player;
pub use game::PlayerId;
pub use game::Profile;
pub use game::Rational;
pub use game::StrategicGame;
pub use game::StrategyId;
pub use game::ValidExtensiveGame;
pub use game::ValidStrategicGame;
pub use solve::expected_payoff_against;
pub use solve::expected_payoff_per_strategy;
pub use solve::profitable_deviation;
pub use solve::solve_backward_induction;
pub use solve::solve_dominance;
pub use solve::solve_mixed_nash;
pub use solve::solve_pure_nash;
pub use solve::strictly_dominated_by_mixture;
pub use solve::verify_equilibrium;
pub use solve::verify_mixed_nash;
pub use solve::verify_spe;
pub use solve::verify_spe;
pub use solve::BackwardInductionResult;
pub use solve::Concept;
pub use solve::Deviation;
pub use solve::DominanceMode;
pub use solve::DominanceResult;
pub use solve::Dominator;
pub use solve::EliminationStep;
pub use solve::MixedDeviation;
pub use solve::MixedEquilibrium;
pub use solve::MixedNashResult;
pub use solve::MixedStrategy;
pub use solve::MixedVerifyResult;
pub use solve::NodeDecision;
pub use solve::ProfileCheck;
pub use solve::PureNashResult;
pub use solve::SpeDeviation;
pub use solve::SpeSolution;
pub use solve::SpeVerifyResult;
pub use solve::SupportViolation;
pub use solve::VerifyResult;

Modules§

analyze
Structural properties of a game — what shape it has, independent of any one solution concept.
error
Typed failures. Every variant names what went wrong and what to do instead.
exact
Exact arithmetic helpers. Nothing here approximates.
game
Game representation. Plain data — validation lives in validate.rs.
limits
Hard size limits. Exceeding one is an error naming the limit and the actual value — the crate never truncates a game and answers anyway.
solve
Solution concepts. Every solver takes a validated game — ValidStrategicGame for the strategic-form solvers, ValidExtensiveGame for the tree solvers — and returns a report carrying both the answer and the derivation that produced it.