+
+
+
+
or you can directly load AnimalShogi class
Animal Shogi (Dōbutsu shōgi) is a variant of shogi primarily developed for children. It consists of a 3x4 board and four types of pieces (five including promoted pieces). One of the rule differences from regular shogi is the Try Rule, where entering the opponent's territory with the king leads to victory.
+See also Wikipedia
+| Name | +Value | +
|---|---|
| Version | +v2 |
+
| Number of players | +2 |
+
| Number of actions | +132 |
+
| Observation shape | +(4, 3, 194) |
+
| Observation type | +float |
+
| Rewards | +{-1, 0, 1} |
+
| Index | +Description | +
|---|---|
[:, :, 0:5] |
+my pieces on board | +
[:, :, 5:10] |
+opponent's pieces on board | +
[:, :, 10:16] |
+my hands | +
[:, :, 16:22] |
+opponent's hands | +
[:, :, 22:24] |
+repetitions | +
| ... | +... | +
[:, :, 193] |
+player_id's turn' |
+
[:, :, 194] |
+Elapsed timesteps (normalized to 1) |
+
Uses AlphaZero like action label:
+132 labels8 x 12 (direction) x (source square)3 x 12 (drop piece type) x (destination square)Non-zero rewards are given only at the terminal states. +The reward at terminal state is described in this table:
+| + | Reward | +
|---|---|
| Win | ++1 |
+
| Lose | +-1 |
+
| Draw | +0 |
+
Termination happens when
+In cases 3 and 4, the game is declared a draw.
+v2 : Fixed a bug in Pawn drop #1218 by @KazukiOhta (v2.3.0)v1 : Fixed visualization #1208 and bug in Gold's move #1209 by @KazukiOhta (v2.2.0)v0 : Initial release (v1.0.0)Pgx offers a baseline model for Animal Shogi. Users can use it for an anchor opponent in evaluation. +See our paper for more details. See this colab for how to use it.
+++[!WARNING] +Curren latest model (
+animal_shogi_v0) is trained withv0environment. It may perform significantly worse inv1environment.
| Model ID | +Description | +
|---|---|
animal_shogi_v0 |
+See our paper for the training details. | +
This is the list of all public APIs of Pgx.
+Two important components in Pgx are State and Env.
pgx.State
+
+
+
+ Bases: ABC
Base state class of all Pgx game environments. Basically an immutable (frozen) dataclass.
+A basic usage is generating via Env.init:
state = env.init(jax.random.PRNGKey(0))
+and Env.step receives and returns this state class:
state = env.step(state, action)
+Serialization via flax.struct.serialization is supported.
+There are 6 common attributes over all games:
Attributes:
+| Name | +Type | +Description | +
|---|---|---|
current_player |
+
+ Array
+ |
+
+
+
+ id of agent to play. +Note that this does NOT represent the turn (e.g., black/white in Go). +This ID is consistent over the parallel vmapped states. + |
+
observation |
+
+ Array
+ |
+
+
+
+ observation for the current state.
+ |
+
rewards |
+
+ Array
+ |
+
+
+
+ the |
+
terminated |
+
+ Array
+ |
+
+
+
+ denotes that the state is terminal state. Note that
+some environments (e.g., Go) have an |
+
truncated |
+
+ Array
+ |
+
+
+
+ indicates that the episode ends with the reason other than termination.
+Note that current Pgx environments do not invoke truncation but users can use |
+
legal_action_mask |
+
+ Array
+ |
+
+
+
+ Boolean array of legal actions. If illegal action is taken, +the game will terminate immediately with the penalty to the palyer. + |
+
pgx/core.py66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 | |
env_id: EnvId
+
+
+ abstractmethod
+ property
+
+
+Environment id (e.g. "go_19x19")
+save_svg(filename, *, color_theme=None, scale=None)
+
+Save the entire state (not observation) to a file.
+The filename must end with .svg
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ color_theme
+ |
+
+ Optional[Literal['light', 'dark']]
+ |
+
+
+
+ xxx see also global config. + |
+
+ None
+ |
+
+ scale
+ |
+
+ Optional[float]
+ |
+
+
+
+ change image size. Default(None) is 1.0 + |
+
+ None
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ None
+ |
+
+
+
+ None + |
+
pgx/core.pyto_svg(*, color_theme=None, scale=None)
+
+Return SVG string. Useful for visualization in notebook.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ color_theme
+ |
+
+ Optional[Literal['light', 'dark']]
+ |
+
+
+
+ xxx see also global config. + |
+
+ None
+ |
+
+ scale
+ |
+
+ Optional[float]
+ |
+
+
+
+ change image size. Default(None) is 1.0 + |
+
+ None
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ SVG string + |
+
pgx/core.pypgx.Env
+
+
+
+ Bases: ABC
Environment class API.
+Example usage
+ +pgx/core.py159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 | |
id: EnvId
+
+
+ abstractmethod
+ property
+
+
+Environment id.
+num_actions: int
+
+
+ property
+
+
+Return the size of action space (e.g., 9 in Tic-tac-toe)
+num_players: int
+
+
+ abstractmethod
+ property
+
+
+Number of players (e.g., 2 in Tic-tac-toe)
+observation_shape: Tuple[int, ...]
+
+
+ property
+
+
+Return the matrix shape of observation
+version: str
+
+
+ abstractmethod
+ property
+
+
+Environment version. Updated when behavior, parameter, or API is changed. +Refactoring or speeding up without any expected behavior changes will NOT update the version number.
+init(key)
+
+Return the initial state. Note that no internal state of +environment changes.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ key
+ |
+
+ PRNGKey
+ |
+
+
+
+ pseudo-random generator key in JAX. Consumed in this function. + |
+ + required + | +
Returns:
+| Name | Type | +Description | +
|---|---|---|
State |
+ State
+ |
+
+
+
+ initial state of environment + |
+
pgx/core.pyobserve(state, player_id)
+
+step(state, action, key=None)
+
+Step function.
+ +pgx/core.pypgx.EnvId = Literal['2048', 'animal_shogi', 'backgammon', 'bridge_bidding', 'chess', 'connect_four', 'gardner_chess', 'go_9x9', 'go_19x19', 'hex', 'kuhn_poker', 'leduc_holdem', 'minatar-asterix', 'minatar-breakout', 'minatar-freeway', 'minatar-seaquest', 'minatar-space_invaders', 'othello', 'shogi', 'sparrow_mahjong', 'tic_tac_toe']
+
+
+ module-attribute
+
+
+Naming convention of EnvId
Hyphen - is used to represent that there is a different original game source (e.g., MinAtar), and underscore - is used for the other cases.
pgx.make(env_id)
+
+Load the specified environment.
+ +BridgeBidding environment
BridgeBidding environment requires the domain knowledge of bridge game.
+So we forbid users to load the bridge environment by make("bridge_bidding").
+Use BridgeBidding class directly by from pgx.bridge_bidding import BridgeBidding.
pgx/core.py317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 | |
pgx.available_envs()
+
+List up all environment id available in pgx.make function.
Example usage
+pgx.available_envs()
+('2048', 'animal_shogi', 'backgammon', 'chess', 'connect_four', 'go_9x9', 'go_19x19', 'hex', 'kuhn_poker', 'leduc_holdem', 'minatar-asterix', 'minatar-breakout', 'minatar-freeway', 'minatar-seaquest', 'minatar-space_invaders', 'othello', 'shogi', 'sparrow_mahjong', 'tic_tac_toe')
+BridgeBidding environment
BridgeBidding environment requires the domain knowledge of bridge game.
+So we forbid users to load the bridge environment by make("bridge_bidding").
+Use BridgeBidding class directly by from pgx.bridge_bidding import BridgeBidding.
pgx/core.pypgx.set_visualization_config(*, color_theme='light', scale=1.0, frame_duration_seconds=0.2)
+
+pgx/_src/visualizer.pypgx.save_svg(state, filename, *, color_theme=None, scale=None)
+
+pgx/_src/visualizer.pypgx.save_svg_animation(states, filename, *, color_theme=None, scale=None, frame_duration_seconds=None)
+
+pgx/_src/visualizer.pypgx.BaselineModelId = Literal['animal_shogi_v0', 'gardner_chess_v0', 'go_9x9_v0', 'hex_v0', 'othello_v0', 'minatar-asterix_v0', 'minatar-breakout_v0', 'minatar-freeway_v0', 'minatar-seaquest_v0', 'minatar-space_invaders_v0']
+
+
+ module-attribute
+
+
+pgx.make_baseline_model(model_id, download_dir='baselines')
+
+pgx/_src/baseline.pyimport jax
+import jax.numpy as jnp
+import pgx
+
+seed = 42
+batch_size = 10
+key = jax.random.PRNGKey(seed)
+
+
+def act_randomly(rng_key, obs, mask):
+ """Ignore observation and choose randomly from legal actions"""
+ del obs
+ probs = mask / mask.sum()
+ logits = jnp.maximum(jnp.log(probs), jnp.finfo(probs.dtype).min)
+ return jax.random.categorical(rng_key, logits=logits, axis=-1)
+
+
+# Load the environment
+env = pgx.make("go_9x9")
+init_fn = jax.jit(jax.vmap(env.init))
+step_fn = jax.jit(jax.vmap(env.step))
+
+# Initialize the states
+key, subkey = jax.random.split(key)
+keys = jax.random.split(subkey, batch_size)
+state = init_fn(keys)
+
+# Run random simulation
+while not (state.terminated | state.truncated).all():
+ key, subkey = jax.random.split(key)
+ action = act_randomly(subkey, state.observation, state.legal_action_mask)
+ state = step_fn(state, action) # state.reward (2,)
+This illustrative example helps to understand
+state.current_player is definedEnv.step behaves against already terminated statesimport jax
+import jax.numpy as jnp
+import pgx
+from pgx.experimental.utils import act_randomly
+
+seed = 42
+batch_size = 10
+key = jax.random.PRNGKey(seed)
+
+# Prepare agent A and B
+# Agent A: random player
+# Agent B: baseline player provided by Pgx
+A = 0
+B = 1
+
+# Load the environment
+env = pgx.make("go_9x9")
+init_fn = jax.jit(jax.vmap(env.init))
+step_fn = jax.jit(jax.vmap(env.step))
+
+# Prepare baseline model
+# Note that it additionaly requires Haiku library ($ pip install dm-haiku)
+model_id = "go_9x9_v0"
+model = pgx.make_baseline_model(model_id)
+
+# Initialize the states
+key, subkey = jax.random.split(key)
+keys = jax.random.split(subkey, batch_size)
+state = init_fn(keys)
+print(f"Game index: {jnp.arange(batch_size)}") # [0 1 2 3 4 5 6 7 8 9]
+print(f"Black player: {state.current_player}") # [1 1 0 1 0 0 1 1 1 1]
+# In other words
+print(f"A is black: {state.current_player == A}") # [False False True False True True False False False False]
+print(f"B is black: {state.current_player == B}") # [ True True False True False False True True True True]
+
+# Run simulation
+R = state.rewards
+while not (state.terminated | state.truncated).all():
+ # Action of random player A
+ key, subkey = jax.random.split(key)
+ action_A = jax.jit(act_randomly)(subkey, state)
+ # Greedy action of baseline model B
+ logits, value = model(state.observation)
+ action_B = logits.argmax(axis=-1)
+
+ action = jnp.where(state.current_player == A, action_A, action_B)
+ state = step_fn(state, action)
+ R += state.rewards
+
+print(f"Return of agent A = {R[:, A]}") # [-1. -1. -1. -1. -1. -1. -1. -1. -1. -1.]
+print(f"Return of agent B = {R[:, B]}") # [1. 1. 1. 1. 1. 1. 1. 1. 1. 1.]
+Note that we can avoid to explicitly deal with the first batch dimension like [:, A] by using vmap later.