Add core API reference + other documentation updates.

Resolves: google-deepmind#895. PiperOrigin-RevId: 468309932 Change-Id: I3cd8efc4abd546d60c1d58dffca2e0afc2ad4f72
RevanMacQueen · Aug 20, 2022 · 7a1a2ee · 7a1a2ee
1 parent 8ff031f
commit 7a1a2ee
Show file tree

Hide file tree

Showing 36 changed files with 1,058 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -28,6 +28,7 @@ Please choose among the following options:
 *   [Installing OpenSpiel](docs/install.md)
 *   [Introduction to OpenSpiel](docs/intro.md)
 *   [API Overview and First Example](docs/concepts.md)
+*   [API Reference](docs/api_reference.md)
 *   [Overview of Implemented Games](docs/games.md)
 *   [Overview of Implemented Algorithms](docs/algorithms.md)
 *   [Developer Guide](docs/developer_guide.md)

diff --git a/docs/api_reference.md b/docs/api_reference.md
@@ -0,0 +1,66 @@
+## OpenSpiel Core API Reference
+
+OpenSpiel consists of several core functions and classes. This page acts as a
+helpful reminder of how to use the main functionality of OpenSpiel.
+
+Most of the functions are described and illustrated via Python syntax and
+examples, and there are pointers to the corresponding C++ functions.
+
+<b><u>Disclaimer</u></b>: This is meant as a guide to facilitate OpenSpiel development
+in Python. However,
+[spiel.h](https://github.com/deepmind/open_spiel/blob/master/open_spiel/spiel.h)
+remains the single source of truth for documentation on the core API.
+
+### Core Functions
+
+Method                                                               | Python                                                       | C++                                                                                                                    | Description
+-------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -----------
+`deserialize_game_and_state(serialized_data: string)`                | [[Python]](api_reference/game_deserialize_game_and_state.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L1127) | Returns a tuple of (game, state) reconstructed from the serialized object data.
+`load_game(game_string: str)`                                        | [[Python]](api_reference/load_game.md)                       | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L1080) | Returns a game object for the specified game string.
+`load_game(game_string: str, parameters: Dict[str, Any])`            | [[Python]](api_reference/load_game.md)                       | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L1083) | Returns a game object for the specified game string and parameter values.
+`registered_names()`                                                 | [[Python]](api_reference/registered_names.md)                | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L1051) | Returns a list of all short names of games in the library.
+`serialize_game_and_state(game: pyspiel.Game, state: pyspiel.State)` | [[Python]](api_reference/game_serialize_game_and_state.md)   | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L1104) | Returns a string representation of the state and game that created it.
+
+### State methods
+
+Method                                       | Python                                                      | C++                                                                                                                   | Description
+-------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -----------
+`action_to_string(player: int, action: int)` | [[Python]](api_reference/state_action_to_string.md)         | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L289) | Returns a string representation of the specified player's action.
+`apply_action(action: int)`                  | [[Python]](api_reference/state_apply_action.md)             | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L230) | Applies the specified action to the state.
+`apply_actions(actions: List[int])`          | [[Python]](api_reference/state_apply_actions.md)            | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L581) | Applies the specified joint action (action for each player) to the state.
+`chance_outcomes()`                          | [[Python]](api_reference/state_chance_outcomes.md)          | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L604) | Returns the a list of (action, prob) tuples representing the chance outcome distribution.
+`current_player()`                           | [[Python]](api_reference/state_current_player.md)           | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L225) | Returns the player ID of the acting player.
+`history()`                                  | [[Python]](api_reference/state_history.md)                  | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L406) | Returns the sequence of actions taken by all players since the start of the game.
+`information_state_string()`                 | [[Python]](api_reference/state_information_state_string.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L433) | Returns a string representing the information state for the current player.
+`information_state_string(player: int)`      | [[Python]](api_reference/state_information_state_string.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L433) | Returns a string representing the information state for the specified player.
+`information_state_tensor()`                 | [[Python]](api_reference/state_information_state_tensor.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L488) | Returns a list of floats representing the information state for the current player.
+`information_state_tensor(player: int)`      | [[Python]](api_reference/state_information_state_tensor.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L488) | Returns a list of floats representing the information state for the specified player.
+`is_chance_node()`                           | [[Python]](api_reference/state_is_chance_node.md)           | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L368) | Returns True if the state represents a chance node, False otherwise.
+`is_simultaneous_node()`                     | [[Python]](api_reference/state_is_simultaneous_node.md)     | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L385) | Returns True if the state represents a simultaneous player node, False otherwise.
+`is_terminal()`                              | [[Python]](api_reference/state_is_terminal.md)              | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L322) | Returns True if the state is terminal (game has finished), False otherwise.
+`legal_actions()`                            | [[Python]](api_reference/state_legal_actions.md)            | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L263) | Returns the list of legal actions for the current player.
+`legal_actions(player: int)`                 | [[Python]](api_reference/state_legal_actions.md)            | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L245) | Returns the list of legal actions for the specified player.
+`observation_string()`                       | [[Python]](api_reference/state_observation_string.md)       | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L516) | Returns a string representing the observation for the current player.
+`observation_string(player: int)`            | [[Python]](api_reference/state_observation_string.md)       | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L516) | Returns a string representing the observation for the specified player.
+`observation_tensor()`                       | [[Python]](api_reference/state_observation_tensor.md)       | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L547) | Returns a list of floats representing the observation for the current player.
+`observation_tensor(player: int)`            | [[Python]](api_reference/state_observation_tensor.md)       | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L547) | Returns a list of floats representing the observation for the specified player.
+`returns()`                                  | [[Python]](api_reference/state_returns.md)                  | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L346) | Returns the list of returns (cumulated reward from the start of the game): one value per player.
+`rewards()`                                  | [[Python]](api_reference/state_rewards.md)                  | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L325) | Returns the list of intermediate rewards (rewards obtained since the last time the player acted): one value per player.
+`serialize()`                                | [[Python]](api_reference/state_serialize.md)                | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L636) | Returns a string representation of the state which can be used to reconstruct the state from the game.
+
+### Game methods
+
+Method                                       | Python                                                                | C++                                                                                                                   | Description
+-------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -----------
+`action_to_string(player: int, action: int)` | [[Python]](api_reference/game_action_to_string.md)                    | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L946) | Returns a (state-independent) string representation of the specified player's action.
+`deserialize_state(serialized_data: str)`    | [[Python]](api_reference/game_deserialize_state.md)                   | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L863) | Reconstructs the state from the serialized state string.
+`information_state_tensor_shape()`           | [[Python]](api_reference/game_information_state_tensor_shape_size.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L815) | Shape that the information state tensor should be perceived as.
+`information_state_tensor_size()`            | [[Python]](api_reference/game_information_state_tensor_shape_size.md) | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L827) | Size of the list (number of values) returned by the state's information state tensor function.
+`max_chance_outcomes()`                      | [[Python]](api_reference/game_max_chance_outcomes.md)                 | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L778) | The maximum number of distinct chance outcomes for chance nodes in the game.
+`max_game_length()`                          | [[Python]](api_reference/game_max_game_length.md)                     | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L873) | The maximum number of distinct chance outcomes for chance nodes in the game.
+`max_utility()`                              | [[Python]](api_reference/game_max_min_utility.md)                     | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L795) | The maximum achievable utility (return) in over any playing (episode) of the game.
+`min_utility()`                              | [[Python]](api_reference/game_max_min_utility.md)                     | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L795) | The minimum achievable utility (return) in over any playing (episode) of the game.
+`new_initial_state()`                        | [[Python]](api_reference/game_new_initial_state.md)                   | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L764) | Returns a new initial state of the game (note: which might be a chance node).
+`num_distinct_actions()`                     | [[Python]](api_reference/game_num_distinct_actions.md)                | [[C++]](https://github.com/deepmind/open_spiel/blob/c6fafb92021a8a3aa5f9746cdb79e74917ed26a5/open_spiel/spiel.h#L752) | Returns the number of (state-independent) distinct actions in the game.
+`observation_tensor_shape()`                 | [[Python]](api_reference/game_observation_tensor_shape_size.md)       | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L835) | Shape that the observation tensor should be perceived as.
+`observation_tensor_size()`                  | [[Python]](api_reference/game_observation_tensor_shape_size.md)       | [[C++]](https://github.com/deepmind/open_spiel/blob/89ba2264a66d9db299108fbd2de4a27b71973f54/open_spiel/spiel.h#L847) | Size of the list (number of values) returned by the state's observation tensor function.
diff --git a/docs/api_reference/game_action_to_string.md b/docs/api_reference/game_action_to_string.md
@@ -0,0 +1,24 @@
+# OpenSpiel game methods: action_to_string
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+`action_to_string(player: int, action: int)`
+
+Returns a string representation of the specified player's action, independent of
+state.
+
+## Examples:
+
+```python
+import pyspiel
+
+game = pyspiel.load_game("matrix_pd")
+print(game.action_to_string(0, 0))
+# Output: Cooperate
+
+# Print first player's second action (1).
+game = pyspiel.load_game("tic_tac_toe")
+print(game.action_to_string(0, 1))
+# Output: x(0, 1)
+```
diff --git a/docs/api_reference/game_deserialize_game_and_state.md b/docs/api_reference/game_deserialize_game_and_state.md
@@ -0,0 +1,49 @@
+# OpenSpiel core functions: deserialize_game_and_state
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+`deserialize_game_and_state(game: pyspiel.Game, state: pyspiel.State)`
+
+Returns a (game, state) tuple that is reconstructed from the serialized string
+data.
+
+Note: pickle can also be used to serialize / deserialize data, and the pickle
+uses the same serialization methods.
+
+## Examples:
+
+```python
+import pyspiel
+
+game = pyspiel.load_game("tic_tac_toe")
+state = game.new_initial_state()
+state.apply_action(4)
+state.apply_action(2)
+state.apply_action(1)
+state.apply_action(5)
+
+serialized_data = pyspiel.serialize_game_and_state(game, state)
+print(serialized_data)
+
+game_copy, state_copy = pyspiel.deserialize_game_and_state(serialized_data)
+print(state_copy)
+
+# Output:
+# # Automatically generated by OpenSpiel SerializeGameAndState
+# [Meta]
+# Version: 1
+#
+# [Game]
+# tic_tac_toe()
+# [State]
+# 4
+# 2
+# 1
+# 5
+#
+#
+# .xo
+# .xo
+# ...
+```
diff --git a/docs/api_reference/game_deserialize_state.md b/docs/api_reference/game_deserialize_state.md
@@ -0,0 +1,34 @@
+# OpenSpiel game methods: deserialize_state
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+`deserialize_state(serialized_data: str)`
+
+Reconstruct a state object from the state's serialized data (from
+`state.serialize()`). The game used to reconstruct must be the same as the game
+that created the original state.
+
+To serialize a state along with the game, use `pyspiel.serialize_game_and_state`
+instead.
+
+## Examples:
+
+```python
+import pyspiel
+
+game = pyspiel.load_game("tic_tac_toe")
+state = game.new_initial_state()
+state.apply_action(4)
+state.apply_action(2)
+state.apply_action(1)
+state.apply_action(5)
+
+state_copy = game.deserialize_state(state.serialize())
+print(state_copy)
+
+# Output:
+# .xo
+# .xo
+# ...
+```
diff --git a/docs/api_reference/game_information_state_tensor_shape_size.md b/docs/api_reference/game_information_state_tensor_shape_size.md
@@ -0,0 +1,27 @@
+# OpenSpiel game methods: information_state_tensor_shape and information_state_tensor_size
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+1.  `information_state_tensor_shape()`
+2.  `information_state_tensor_size()`
+
+(1) Returns the information state tensor's shape: a list of integers
+representing the size of each dimension.
+
+(2) Returns the total number of values used to represent the information state
+tensor.
+
+## Examples:
+
+```python
+import pyspiel
+
+game = pyspiel.load_game("kuhn_poker")
+print(game.information_state_tensor_shape())
+print(game.information_state_tensor_size())
+
+# Output:
+# [11]
+# 11
+```
diff --git a/docs/api_reference/game_max_chance_outcomes.md b/docs/api_reference/game_max_chance_outcomes.md
@@ -0,0 +1,27 @@
+# OpenSpiel game methods: max_chance_outcomes
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+`max_chance_outcomes`
+
+Returns the maximum number of distinct chance outcomes at chance nodes in the
+game.
+
+## Examples:
+
+```python
+import pyspiel
+
+game = pyspiel.load_game("chess")
+print(game.max_chance_outcomes())
+# Outputs: 0   (no chance nodes in Chess)
+
+game = pyspiel.load_game("markov_soccer")
+print(game.max_chance_outcomes())
+# Outputs: 4   (ball starting location, and who gets initiative)
+
+game = pyspiel.load_game("leduc_poker")
+print(game.max_chance_outcomes())
+# Outputs: 6   (three cards in two suits)
+```
diff --git a/docs/api_reference/game_max_game_length.md b/docs/api_reference/game_max_game_length.md
@@ -0,0 +1,32 @@
+# OpenSpiel game methods: max_game_length
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+`max_game_length()`
+
+Returns the maximum and minimum achievable utility (return in any given episode)
+in the game.
+
+For a simultaneous action game, this is the maximum number of joint decisions.
+In a turn-based game, this is the maximum number of individual decisions summed
+over all players. Outcomes of chance nodes are not included in this length.
+
+## Examples:
+
+```python
+import pyspiel
+
+game = pyspiel.load_game("tic_tac_toe")
+print(game.max_game_length())    # Output: 9
+
+# Normal-form games always have one
+game = pyspiel.load_game("blotto")
+print(game.max_game_length())    # Output: 1
+
+# The maximum is arbitrarily defined (and/or customizable) is some games.
+game = pyspiel.load_game("coop_box_pushing")
+print(game.max_game_length())    # Output: 100
+game = pyspiel.load_game("coop_box_pushing(horizon=250)")
+print(game.max_game_length())    # Output: 250
+```
diff --git a/docs/api_reference/game_max_min_utility.md b/docs/api_reference/game_max_min_utility.md
@@ -0,0 +1,32 @@
+# OpenSpiel game methods: max_utility and min_utility
+
+[Back to Core API reference](../api_reference.md) \
+<br>
+
+`max_utility()` \
+`min_utility()`
+
+Returns the maximum and minimum achievable utility (return in any given episode)
+in the game.
+
+## Examples:
+
+```python
+import pyspiel
+
+# Win/loss game
+game = pyspiel.load_game("tic_tac_toe")
+print(game.min_utility())    # Output: -1
+print(game.max_utility())    # Output: 1
+
+# Win/los/draw game (draw counts as 0).
+game = pyspiel.load_game("chess")
+print(game.min_utility())    # Output: -1
+print(game.max_utility())    # Output: 1
+
+# Money game.
+game = pyspiel.load_game("leduc_poked")
+print (game.num_distinct_actions())
+print(game.min_utility())    # Output: -13
+print(game.max_utility())    # Output: 13
+```