Cfrm 2.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Cfrm --version 2.1.0                
NuGet\Install-Package Cfrm -Version 2.1.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Cfrm" Version="2.1.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Cfrm --version 2.1.0                
#r "nuget: Cfrm, 2.1.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Cfrm as a Cake Addin
#addin nuget:?package=Cfrm&version=2.1.0

// Install Cfrm as a Cake Tool
#tool nuget:?package=Cfrm&version=2.1.0                

Counterfactual Regret Minimization

Counterfactual Regret Minimization (usually abbreviated as "CFR") is a technique for solving imperfect-information games, which are games in which some information is hidden from players. For example, in most card games, players are dealt cards that they keep hidden from the other players. Solving such a game means finding a Nash equilibrium, which is a strategy that cannot be improved further by incremental changes.

Representing game state

Cfrm is a .NET library for applying CFR to a game of two or more players. To solve such a game, you create a concrete class that inherits from an abstract base class called GameState<TAction> that defines the state of the game from the current player's point of view (this state is known as an "information set" in game theory). The type parameter TAction defines the type of actions available in the game (e.g. playing a card, making a bet, etc.). This can be an enum or any other type (such as a Card class).

If you are working in C#, the methods of GameState that you must override are:

  • int CurrentPlayerIdx This is the 0-based index of the current player. For example, if there are four players in a game, their indexes are 0, 1, 2, and 3. Players do not necessarily play in that order, though. (E.g. In trick-taking games, the player who takes a trick typically leads on the next trick.)
  • float[] TerminalValues If the game is in a terminal state (i.e. the game is over), this member answers an array of "payoff" values for each player. For example, in a two-player game, if player 0 wins, she might receive 1 point, while player 1 would receive -1 point for losing, resulting in a payoff array of [ 1, -1] for that outcome. If the sum of the payoffs in a terminal state is always 0, then the game is "zero-sum". If the game is not over, then this member answers null.
  • TAction[] LegalActions If the game is not in a terminal state, this member answers an array of legal actions for the player whose turn it is in the current state. For example, in a poker game, these actions might be Bet or Fold, while in Bridge, the legal actions would be specific bids or cards.
  • GameState<TAction> AddAction(TAction action) This method advances the game to the next state by taking the given action on behalf of the current player.
  • string Key This member answers a string that uniquely describes the state of the game from the point of view of the current player. For example, in a card game, the unique key might contain the history of the game to this point (i.e. all the cards played so far, by all players) plus the hidden cards remaining in the current player's hand.

You can think of GameState as representing all the possible nodes in a game's "move tree". Key is a node's unique ID, LegalActions are the branches leading to the node's child nodes, and AddAction moves from a node to one of its children.

Running CFR

Once your concrete GameState class is ready, you can run CFR by invoking the static member CounterFactualRegret.Minimize, which takes the following arguments:

  • numIterations: The number of CFR iterations to run. Each iteration corresponds to a single play-through of the game.
  • numPlayers: The number of players in the game.
  • getInitialState: This is a callback function that initializes a new game. This initialization can be random (corresponding to shuffling the deck in a card game), or it can move sequentially through all possible initial states in order.

The Minimize function returns a tuple containing two values:

  • float[] expectedGameValue: An array containing the expected payoffs for each player at the Nash equilibrium. If the game is zero-sum, these payoffs will sum to zero.
  • StrategyProfile strategyProfile: A collection of strategies for the game states visited while running CFR. To access these strategies from C#, use the IDictionary<string, float[]> ToDict member. The keys of this dictionary correspond to GameState.Key, while the values are arrays representing the probability of taking each of the GameState.LegalActions at that game state. This profile can be used to play the game according to the strategy found by CFR.

Playing a game

After minimizing regret, the resulting strategy profile can be saved to disk via its Save method. In order to play a game with a saved profile, first load it from disk using the static StrategyProfile.Load method. To play a mixed strategy (e.g. in poker), call the Sample method with a key that corresponds to the state of the game from the current player's point of view. To play a pure strategy, call the Best method, which always chooses the action with the highest probability in a given situation.

F# support

Cfrm is written in F# and supports F# implementations smoothly. The important differences from working in C# are:

  • When inheriting from GameState , you can override TerminalValuesOpt instead of TerminalValues in order to avoid returning null.
  • You can call function CounterFactualRegret.minimize instead of method CounterFactualRegret.Minimize. This allows you to pass in an F# closure for the getInitialState callback instead of the wrapped Func that is passed to Minimize.

Example

There are working examples of Kuhn poker for both C# and F# in the unit test projects.

References

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.1 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.6.0 92 7/17/2024
2.5.0 263 11/7/2023
2.4.0 149 10/24/2023
2.3.0 152 10/24/2023
2.2.0 462 6/22/2022
2.1.0 508 9/13/2020
2.0.0 449 9/6/2020
1.9.0 543 9/6/2020
1.8.0 449 9/2/2020
1.7.0 498 9/1/2020
1.6.0 476 8/31/2020
1.5.0 497 8/30/2020
1.4.0 442 8/26/2020
1.3.0 437 8/26/2020
1.2.0 408 8/25/2020
1.1.0 443 8/24/2020
1.0.0 434 8/24/2020