### Run React UI

Source: https://docs.catanatron.com/contributing

Commands to install dependencies and start the React application locally or via Docker.

```bash
cd ui/
npm install
npm start
```

```bash
docker build -t bcollazo/catanatron-react-ui:latest ui/
docker run -it -p 3000:3000 bcollazo/catanatron-react-ui
```

--------------------------------

### Install developer and advanced dependencies

Source: https://docs.catanatron.com/getting-started/installation

Optional installation command for additional features including web and gym support.

```bash
pip install -e .[web,gym,dev]
```

--------------------------------

### Install Catanatron Gymnasium Environment

Source: https://docs.catanatron.com/advanced/openapi

Install the package with the gym extra in the root of the repository.

```bash
pip install -e .[gym]
```

--------------------------------

### Install project dependencies

Source: https://docs.catanatron.com/getting-started/installation

Installs the required packages for the project.

```bash
pip install -e .
```

--------------------------------

### Run the Graphical User Interface

Source: https://docs.catanatron.com/getting-started/installation

Starts the application services using Docker Compose.

```bash
docker compose up
```

--------------------------------

### Install Catanatron Web Subpackage and Save Game Data

Source: https://docs.catanatron.com/using-catanatron/graphical-user-interface

Install the web subpackage to enable saving game data to the database for inspection via the web server. Use the `--db` flag with `catanatron-play` to activate this feature.

```bash
pip install .[web]
catanatron-play --players=W,W,W,W --db --num=1
```

--------------------------------

### Get help on player options

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Display available player types and their configuration parameters.

```bash
catanatron-play --help-players
```

--------------------------------

### Build Sphinx Documentation

Source: https://docs.catanatron.com/contributing

Commands to install documentation dependencies and build the HTML documentation site.

```bash
pip install -r docs/requirements.txt
sphinx-quickstart docs
sphinx-apidoc -o docs/source catanatron
sphinx-build -b html docs/source/ docs/build/html
```

--------------------------------

### Run Test Suite

Source: https://docs.catanatron.com/contributing

Commands to install development dependencies and execute the test suite with coverage reporting or in watch-mode.

```bash
pip install ".[web,gym,dev]"
coverage run --source=catanatron -m pytest tests/ && coverage report
```

```bash
ptw --ignore=tests/integration_tests/ --nobeep
```

--------------------------------

### Run Flask Web Server

Source: https://docs.catanatron.com/contributing

Commands to install web dependencies and run the Flask server locally or via Docker.

```bash
pip install -e .[web]
FLASK_DEBUG=1 FLASK_APP=catanatron.web/catanatron.web flask run
```

```bash
docker build -t bcollazo/catanatron-server:latest . -f Dockerfile.web
docker run -it -p 5001:5001 bcollazo/catanatron-server
```

--------------------------------

### Example directory structure for saved JSON game results

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Illustrates the file structure created when saving game results in JSON format.

```text
data/
├── 2aba0ec4-51e7-47b6-b5a9-113874b2addf.json
├── 353a541b-59d2-4eb8-85ea-d6eb0d162e7f.json
├── 3c5f37ce-a73c-4180-91fd-28bf9f6dacd2.json
├── e31b00a3-845c-4bfd-92bd-c4a42cbafa27.json
└── ee547837-d5e2-4d9b-8420-583b2fdd793d.json

1 directory, 5 files
```

--------------------------------

### Read Large Datasets with Pandas

Source: https://docs.catanatron.com/contributing

Example of reading a large CSV file in chunks using Pandas.

```python
import pandas as pd
x = pd.read_csv("data/mcts-playouts-labeling-2/labels.csv.gzip", compression="gzip", iterator=True)
x.get_chunk(10)
```

--------------------------------

### Access Catanatron CLI help

Source: https://docs.catanatron.com/getting-started/quickstart

Displays available command-line options and usage information.

```bash
catanatron-play --help
```

--------------------------------

### TensorBoard Monitoring

Source: https://docs.catanatron.com/contributing

Command to launch TensorBoard for monitoring training progress.

```bash
tensorboard --logdir logs
```

--------------------------------

### Publish Packages to PyPi

Source: https://docs.catanatron.com/contributing

Commands to build and upload the catanatron and catanatron_gym packages.

```bash
make build PACKAGE=catanatron
make upload PACKAGE=catanatron
make upload-production PACKAGE=catanatron
```

```bash
make build PACKAGE=catanatron_gym
make upload PACKAGE=catanatron_gym
make upload-production PACKAGE=catanatron_gym
```

--------------------------------

### Execute Custom Bots via CLI

Source: https://docs.catanatron.com/advanced/editor

Run the custom bot by specifying the source file and player configuration in the catanatron-play command.

```bash
catanatron-play --code=myplayers.py --players=R,R,R,FOO --num=10
```

--------------------------------

### Clone the Catanatron repository

Source: https://docs.catanatron.com/getting-started/installation

Initial step to download the project source code from GitHub.

```bash
git clone git@github.com:bcollazo/catanatron.git
cd catanatron/
```

--------------------------------

### Performance Testing

Source: https://docs.catanatron.com/contributing

Commands for profiling and benchmarking the application performance.

```bash
pyinstrument -r html --from-path catanatron-play --players AB:2,AB:2
```

```bash
python -m cProfile -o profile.pstats examples/play_batch_example.py
snakeviz profile.pstats
```

```bash
pytest --benchmark-compare=0001 --benchmark-compare-fail=mean:10% --benchmark-columns=min,max,mean,stddev
```

--------------------------------

### Create a Python virtual environment

Source: https://docs.catanatron.com/getting-started/installation

Sets up an isolated Python environment requiring version 3.11 or higher.

```bash
python -m venv venv
source ./venv/bin/activate
```

--------------------------------

### Run Catanatron simulation via CLI

Source: https://docs.catanatron.com/getting-started/quickstart

Executes a simulation of 100 games with specified player types.

```bash
catanatron-play --players=R,R,R,W --num=100
```

--------------------------------

### Run 10 1v1 games between VictoryPointPlayer and ValueFunctionPlayer

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Simulate 10 games where two specific player types compete.

```bash
catanatron-play --num 10 --players VP,F
```

--------------------------------

### Play a full game with RandomPlayer

Source: https://docs.catanatron.com/using-catanatron/images-and-media

Initializes a game with four random players and executes it until completion.

```python
from catanatron import Game, RandomPlayer, Color

# Play a simple 4v4 game
players = [
    RandomPlayer(Color.RED),
    RandomPlayer(Color.BLUE),
    RandomPlayer(Color.WHITE),
    RandomPlayer(Color.ORANGE),
]
game = Game(players)
print(game.play())  # returns winning color
```

--------------------------------

### Open game state in GUI

Source: https://docs.catanatron.com/using-catanatron/images-and-media

Opens the current game state in a browser using the GUI Docker service.

```python
from catanatron.web.utils import open_link
open_link(game)  # opens game in browser
```

--------------------------------

### Implement Basic Gymnasium Training Loop

Source: https://docs.catanatron.com/advanced/openapi

A standard training loop using the Gymnasium interface. Ensure the agent selects actions from info['valid_actions'].

```python
import random
import gymnasium
import catanatron.gym

env = gymnasium.make("catanatron/Catanatron-v0")
observation, info = env.reset()
for _ in range(1000):
    # your agent here (this takes random actions)
    action = random.choice(info["valid_actions"])

    observation, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated
    if done:
        observation, info = env.reset()
env.close()
```

--------------------------------

### Play 1v1 with custom discard and win conditions

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Play a game with specific discard limits and victory points to win, using quiet mode.

```bash
catanatron-play --num 1 --players F,H --quiet --config-discard-limit 9 --config-vps-to-win 15
```

--------------------------------

### Implement a Custom Player Bot

Source: https://docs.catanatron.com/advanced/editor

Define a new player class by inheriting from Player and implementing the decide method. Register the class using register_cli_player to make it available in the CLI.

```python
from catanatron import Player
from catanatron.cli import register_cli_player

class FooPlayer(Player):
    def decide(self, game, playable_actions):
        """Should return one of the playable_actions.

        Args:
            game (Game): complete game state. read-only.
            playable_actions (Iterable[Action]): options to choose from
        Return:
            action (Action): Chosen element of playable_actions
        """
        # ===== YOUR CODE HERE =====
        # As an example we simply return the first action:
        return playable_actions[0]  # type: ignore
        # ===== END YOUR CODE =====

register_cli_player("FOO", FooPlayer)
```

--------------------------------

### Integrate with Stable-Baselines3 Maskable PPO

Source: https://docs.catanatron.com/advanced/openapi

Use SB3-Contrib's ActionMasker to handle valid action constraints during training.

```python
import gymnasium
import numpy as np
from sb3_contrib.common.maskable.policies import MaskableActorCriticPolicy
from sb3_contrib.common.wrappers import ActionMasker
from sb3_contrib.ppo_mask import MaskablePPO
import catanatron.gym


def mask_fn(env) -> np.ndarray:
    valid_actions = env.unwrapped.get_valid_actions()
    mask = np.zeros(env.action_space.n, dtype=np.float32)
    mask[valid_actions] = 1

    return np.array([bool(i) for i in mask])


# Init Environment and Model
env = gymnasium.make("catanatron/Catanatron-v0")
env = ActionMasker(env, mask_fn)  # Wrap to enable masking
model = MaskablePPO(MaskableActorCriticPolicy, env, verbose=1)

# Train
model.learn(total_timesteps=10_000)
```

--------------------------------

### Configure Gymnasium Environment

Source: https://docs.catanatron.com/advanced/openapi

Customize the environment using the config dictionary to set map types, victory points, and custom reward functions.

```python
import gymnasium
from catanatron import Color
from catanatron.players.weighted_random import WeightedRandomPlayer
import catanatron.gym


def my_reward_function(game, p0_color):
    winning_color = game.winning_color()
    if p0_color == winning_color:
        return 100
    elif winning_color is None:
        return 0
    else:
        return -100


# 3-player catan on a "Mini" map (7 tiles) until 6 points.
env = gymnasium.make(
    "catanatron.gym/Catanatron-v0",
    config={
        "map_type": "MINI",
        "vps_to_win": 6,
        "enemies": [
            WeightedRandomPlayer(Color.RED),
            WeightedRandomPlayer(Color.ORANGE),
        ],
        "reward_function": my_reward_function,
        "representation": "mixed",
    },
)
```

--------------------------------

### Generate Game Data in CSV Format

Source: https://docs.catanatron.com/advanced/data-and-machine-learning

Use this command to generate game data in CSV format. The `--output-format csv` flag ensures data is saved as GZIP compressed CSV files. Data is continuously appended to existing files.

```bash
catanatron-play --num 5 --players F,F,R,R --output data/ --output-format csv
```

--------------------------------

### Docker GPU TensorFlow Environment

Source: https://docs.catanatron.com/contributing

Commands to run a TensorFlow GPU container for development.

```bash
docker run -it tensorflow/tensorflow:latest-gpu-jupyter bash
docker run -it --rm -v $(realpath ./notebooks):/tf/notebooks -p 8888:8888 tensorflow/tensorflow:latest-gpu-jupyter
```

--------------------------------

### Run 1,000 games with Random Players

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Execute a large number of games with all players set to random.

```bash
catanatron-play --num 1000 --players R,R,R,R
```

--------------------------------

### Save game results in JSON format

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Run multiple games and save the results to a specified directory in JSON format.

```bash
catanatron-play --num 5 --players F,F,R,R --output data/ --output-format json
```

--------------------------------

### Generate Game Data in Parquet Format

Source: https://docs.catanatron.com/advanced/data-and-machine-learning

This command generates game data in Parquet format. Unlike CSV, Parquet format generates one file per game.

```bash
catanatron-play --num 5 --players F,R --output data/ --output-format parquet
```

--------------------------------

### Pit 3-player Catan with a high discard limit

Source: https://docs.catanatron.com/using-catanatron/interactive-blocks

Run a single game with three players and a significantly increased discard limit.

```bash
catanatron-play --num 1 --players W,F,AB:2 --config-discard-limit 999
```

--------------------------------

### Include Board Tensors in Data Generation

Source: https://docs.catanatron.com/advanced/data-and-machine-learning

Add the `--include-board-tensor` flag to generate a 3D tensor representing the Catan board state for each game state. This flag is useful for machine learning but may slightly slow down simulations.

```bash
catanatron-play --num 5 --players AB:2,AB:2 --output data/ --output-format csv --include-board-tensor
```

--------------------------------

### Count Maritime Trades with Custom Accumulator

Source: https://docs.catanatron.com/using-catanatron/markdown

Implement a custom accumulator to count maritime trades during simulations. Register it using `register_cli_accumulator` to enable it for command-line play.

```python
from catanatron import ActionType
from catanatron.cli import SimulationAccumulator, register_cli_accumulator

class PortTradeCounter(SimulationAccumulator):
  def before_all(self):
    self.num_trades = 0

  def step(self, game_before_action, action):
    if action.action_type == ActionType.MARITIME_TRADE:
      self.num_trades += 1

  def after_all(self):
    print(f'There were {self.num_trades} trades with the bank!')

register_cli_accumulator(PortTradeCounter)
```

--------------------------------

### Inspect game state components

Source: https://docs.catanatron.com/using-catanatron/images-and-media

Accesses internal board and player state objects for debugging purposes during simulation.

```python
print(game.state.board.map.tiles)
print(game.state.board.buildings)
print(game.state.board.roads)
print(game.state.player_state)
```

--------------------------------

### Iterate over game plys

Source: https://docs.catanatron.com/using-catanatron/images-and-media

Executes the game step-by-step by manually triggering each decision point until a winner is determined.

```python
game = Game(players)
while game.winning_color() is None:
    print(game.state)
    action = game.play_tick()
    print(action)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.