### MAPF-GPT Installation and Setup Commands (Bash)

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Provides commands for setting up the MAPF-GPT development environment using uv for local installation or Docker for a pre-built image. It details installing dependencies and activating the virtual environment.

```bash
# Local installation with uv (recommended)
# Install uv: https://docs.astral.sh/uv/getting-started/installation
uv venv --python 3.10
source .venv/bin/activate
uv pip install -r docker/requirements.txt

# Docker installation
cd docker
sh build.sh
# This builds an image with all dependencies pre-installed

# Key dependencies (docker/requirements.txt):
# torch>=2.0,<=2.10
# pogema-toolbox==0.1.1
# huggingface_hub
# pyarrow
# pybind11==2.13.1
# cppimport==22.7.17
# loguru
```

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

### Run MAPF-GPT Example (85M model)

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

Executes an example of the MAPF-GPT approach using the 85M model on the 'wfi_warehouse' map. Demonstrates running a larger model with more agents.

```bash
python example.py --map_name wfi_warehouse --model 85M --num_agents 192
```

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

### Install Dependencies with uv

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

Installs project dependencies using uv, a fast Python package installer. It creates a virtual environment and installs packages from a requirements file.

```bash
uv venv --python 3.10
source .venv/bin/activate
uv pip install -r docker/requirements.txt
```

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

### Environment Setup and Episode Execution in MAPF-GPT (Python)

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Demonstrates how to set up a Multi-Agent Path Finding (MAPF) environment, run an episode, and save an animation. It configures observation types, map names, agent counts, and collision systems.

```python
from pogema.envs import MAPFEnv
from pogema.training import create_eval_env, create_logging_env
from pogema.grid import Environment

# Standard evaluation environment configuration
env_cfg = Environment(
    observation_type="MAPF",          # MAPF observation format
    map_name="validation-random-seed-001",
    num_agents=32,
    max_episode_steps=128,
    obs_radius=5,                     # Observation radius
    seed=42,
    collision_system="soft",          # Soft collisions
    on_target="nothing",              # Behavior when reaching target
    with_animation=True,              # Enable SVG animation
)

# Create evaluation environment with metrics
env = create_eval_env(env_cfg)

# Run episode
observations, infos = env.reset()
print(f"Num agents: {len(observations)}")
print(f"Observation keys: {observations[0].keys()}")
# Keys: global_xy, global_target_xy, global_obstacles, agents, ...

# Step through environment
actions = [0] * len(observations)  # All agents stay in place
observations, rewards, terminated, truncated, infos = env.step(actions)

# Save animation after episode
env.save_animation("output/pathfinding.svg")

# Create logging environment (for dataset generation)
logging_env = create_logging_env(env_cfg)
observations, infos = logging_env.reset()
# Additional info: made_actions, init_positions logged in infos
```

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

### Run MAPF-GPT Example (2M model)

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

Executes an example of the MAPF-GPT approach using the 2M model on a maze map. Allows specifying map name, model size, and number of agents.

```bash
python example.py --map_name validation-mazes-seed-000 --model 2M --num_agents 32
```

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

### MAPF-GPT Installation Verification and Model Loading (Python)

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

A Python script to verify the installation of MAPF-GPT and its dependencies, including PyTorch. It checks for CUDA and MPS availability and demonstrates loading a pre-trained model for inference.

```python
import torch
from mapf_gpt.inference import MAPFGPTInference, MAPFGPTInferenceConfig

# Check device availability
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"MPS available: {torch.backends.mps.is_available()}")

# Test model loading
config = MAPFGPTInferenceConfig(
    path_to_weights='weights/model-2M.pt',
    device='cuda' if torch.cuda.is_available() else 'cpu'
)
algo = MAPFGPTInference(config)
print("Model loaded successfully!")
```

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

### Run MAPF-GPT Inference with example.py

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Execute the MAPF-GPT model on pathfinding scenarios using the `example.py` script. This script loads pre-trained weights, sets up a POGEMA environment, and generates an SVG animation of the solution. It supports various map types, agent counts, and device configurations (CUDA, MPS).

```bash
python example.py --map_name validation-mazes-seed-000 --model 2M --num_agents 32 --device cuda

python example.py --map_name wfi_warehouse --model 85M --num_agents 192 --device cuda

python example.py --map_name validation-random-seed-001 --model 6M --num_agents 64 --device mps

python example.py --show_map_names
```

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

### Run MAPF-GPT Benchmark

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

Launches the evaluation of MAPF-GPT models (2M, 6M, and optionally 85M) on the POGEMA benchmark set. Results are saved and logged.

```bash
python benchmark.py
```

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

### Create POGEMA Environments with Wrappers

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

This snippet shows how to create and configure POGEMA environments using wrapper functions. These wrappers add capabilities such as animation support, runtime metrics, and action logging, making the environments more suitable for evaluation and analysis.

```python
from pogema import pogema_v0, AnimationConfig, AnimationMonitor
from pogema_toolbox.create_env import Environment
from create_env import create_eval_env, create_logging_env
```

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

### Build Docker Image

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

Builds the Docker image for the MAPF-GPT environment. This command navigates to the docker directory and executes the build script.

```bash
cd docker & sh build.sh
```

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

### Download MAPF-GPT Dataset using Python Script

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

This script facilitates the download of the MAPF-GPT dataset from the Hugging Face Hub. Users can specify the number of files to download to manage disk space, especially if the full 1 billion training samples are not required.

```python
python download_dataset.py
```

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

### Generate Custom Training Datasets with LaCAM

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

This section outlines the process of generating custom training datasets from scratch using LaCAM as the expert solver. It involves instance generation via POGEMA, solving with LaCAM, observation extraction, filtering duplicates, balancing action distributions, and saving to Arrow format. The process can be initiated by running the `generate_dataset.py` script.

```bash
# Generate dataset using the provided script
python generate_dataset.py
```

```text
# Generation pipeline:
# 1. Run LaCAM expert on configured scenarios
# 2. Split results by map into individual JSON files
# 3. Process files in parallel to extract observations
# 4. Filter duplicates and balance action distributions
# 5. Save as Arrow files for efficient training

# Disk space requirements:
# - Temporary files: ~20 GB
# - Final 1B dataset: 256 GB
```

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

### Download Pre-trained Datasets

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Provides instructions and scripts to download the pre-trained 1 billion tensor-action pair training dataset and validation set from Hugging Face. The dataset is stored in Arrow format and is suitable for training MAPF-GPT models.

```bash
# Download dataset using the provided script
python dataset/download_dataset.py

# Dataset structure:
# dataset/
# ├── train/
# │   ├── chunk_0_part_0.arrow   # 2^21 pairs, ~512 MB
# │   ├── chunk_0_part_1.arrow
# │   └── ... (500 files total, 256 GB)
# └── validation/
#     └── chunk_0_part_0.arrow   # 2^20 pairs for validation
```

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

### Generate MAPF-GPT Dataset from Scratch using Python Script

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

This script allows for the generation of the MAPF-GPT dataset from scratch or for creating modified versions. It encompasses instance generation, solving, observation filtering, shuffling, and saving to `.arrow` files. Configuration files in `dataset_configs` can be modified to reduce resource requirements.

```python
python generate_dataset.py
```

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

### Configure and Run Custom Dataset Generation Pipeline

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

This Python snippet details the configuration and execution of the custom dataset generation pipeline. It involves setting parameters like the number of chunks, files per chunk, desired dataset size, maze ratio, and the number of parallel processes. The pipeline includes steps for running the LaCAM expert, splitting JSON files by map, and generating dataset chunks.

```python
from generate_dataset import run_expert, split_json, generate_chunks
import multiprocessing as mp

# Configure dataset parameters in generate_dataset.py
CONFIGS = [
    "dataset_configs/10-medium-mazes/10-medium-mazes-part1.yaml",
    "dataset_configs/12-medium-random/12-medium-random-part1.yaml",
]

NUM_CHUNKS = 10           # Number of output chunks (reduce for smaller dataset)
FILE_PER_CHUNK = 10       # Files per chunk
DESIRED_SIZE = 10*2**21   # Samples per chunk (~20M)
MAZE_RATIO = 0.9          # 90% maze, 10% random maps
NUM_PROCESSES = 50        # Parallel workers

# Step 1: Generate expert data with LaCAM
run_expert()

# Step 2: Split JSON files by map
files = ["LaCAM_data/dataset_configs/10-medium-mazes/10-medium-mazes-part1/LaCAM.json"]
with mp.Pool() as pool:
    pool.map(split_json, files)

# Step 3: Generate dataset chunks
generate_chunks()
```

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

### Train MAPF-GPT Models

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Scripts for training MAPF-GPT models, supporting distributed data parallel (DDP) training across multiple GPUs. Features include gradient accumulation, mixed precision, and automatic checkpointing. Configuration options are specified in Python files.

```bash
# Train a 6M parameter model on single GPU
torchrun --standalone --nproc_per_node=1 train.py mapf_gpt/config-6M.py

# Train on multiple GPUs (4 GPUs)
torchrun --standalone --nproc_per_node=4 train.py mapf_gpt/config-85M.py

# Resume training from checkpoint
# Edit config file to set: init_from = 'resume'
torchrun --standalone --nproc_per_node=1 train.py mapf_gpt/config-6M.py
```

```python
# Model configuration (mapf_gpt/config-6M.py)
compile = True                              # Use torch.compile for speed
max_iters = 30000                           # Total training iterations
lr_decay_iters = 30000                      # LR decay schedule length

batch_size = 2048                           # Micro-batch size per GPU
n_layer = 8                                 # Transformer layers
n_head = 8                                  # Attention heads
n_embd = 256                                # Embedding dimension

train_data_file = "dataset/train"           # Training data path
valid_data_file = "dataset/validation"      # Validation data path

block_size = 256                            # Context window size
gradient_accumulation_steps = 16            # Gradient accumulation

# init_from = 'resume'                      # Uncomment to resume training

# Training output:
# INFO: Train set size: 1.00 B pairs
# INFO: Validation set size: 1.05 M pairs
# INFO: Number of training epochs: 0.98
# INFO: number of parameters: 6.29M
# INFO: step 0: train loss 1.8234, val loss 1.8156
# INFO: iter 100: loss 0.9823, time 245.32ms, mfu 42.15%
```

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

### Train MAPF-GPT Model using PyTorch DistributedDataParallel

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/README.md

This script is used for training the MAPF-GPT model from scratch or fine-tuning existing models. It supports PyTorch DistributedDataParallel (DDP) for multi-GPU training, configurable via the `nproc_per_node` argument. A configuration file specifies model and training parameters.

```python
torchrun --standalone --nproc_per_node=1 train.py gpt/config-6M.py
```

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

### Forward Pass and Inference with PyTorch

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Demonstrates the forward pass for training with loss computation and inference for action predictions using PyTorch. Requires the PyTorch library and a CUDA-enabled GPU.

```python
input_tokens = torch.randint(0, 67, (32, 256), dtype=torch.long, device='cuda')
target_actions = torch.randint(0, 5, (32, 256), dtype=torch.long, device='cuda')
logits, loss = model(input_tokens, targets=target_actions)
print(f"Loss: {loss.item():.4f}")

model.eval()
with torch.no_grad():
    actions = model.act(input_tokens, do_sample=True)  # Shape: (batch_size,)
    # Actions: 0=stay, 1=up, 2=down, 3=left, 4=right
```

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

### MAPFGPTInference Class for Action Predictions

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

The `MAPFGPTInference` class handles loading pre-trained MAPF-GPT models and generating action predictions for agents. It automates model weight downloads from Hugging Face, tokenizes observations, and performs batched inference. The class requires configuration for model path, device, agent count, and various radii for observation.

```python
import torch
from pogema_toolbox.create_env import Environment
from pogema_toolbox.run_episode import run_episode
from create_env import create_eval_env
from mapf_gpt.inference import MAPFGPTInference, MAPFGPTInferenceConfig

# Configure the inference model
config = MAPFGPTInferenceConfig(
    path_to_weights='weights/model-6M.pt',  # Auto-downloads from HuggingFace
    device='cuda',                           # 'cuda', 'cpu', or 'mps'
    num_agents=13,                           # Max agents to track
    cost2go_radius=5,                        # Cost-to-go observation radius
    agents_radius=5,                         # Agent visibility radius
    context_size=256,                        # Transformer context window
    batch_size=2048,                         # Inference batch size
)

# Initialize the inference engine
algo = MAPFGPTInference(config)
algo.reset_states()

# Create POGEMA environment
env_cfg = Environment(
    observation_type="MAPF",
    map_name="validation-random-seed-001",
    num_agents=32,
    max_episode_steps=128,
    obs_radius=5,
    seed=42,
)
env = create_eval_env(env_cfg)

# Run a complete episode
results = run_episode(env, algo)
print(f"Success Rate: {results['CSR']}, Sum of Costs: {results['SoC']}")

# Manual step-by-step inference
observations, infos = env.reset()
algo.reset_states()
done = False
while not done:
    actions = algo.act(observations)  # Returns list of actions [0-4] for each agent
    observations, rewards, terminated, truncated, infos = env.step(actions)
    done = all(terminated) or all(truncated)
```

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

### Run Benchmark Evaluation

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Executes a comprehensive benchmark evaluation of MAPF-GPT models across various scenario categories including random maps, mazes, warehouses, MovingAI, and puzzles. The evaluation results are saved and can be logged to Weights & Biases. This script requires the 'pogema_toolbox' and 'mapf_gpt' libraries.

```bash
# Run full benchmark evaluation
python benchmark.py

# The benchmark evaluates on these scenario categories:
# - 01-random: Random obstacle maps
# - 02-mazes: Procedurally generated mazes
# - 03-warehouse: Warehouse-style maps with aisles
# - 04-movingai: Maps from the MovingAI benchmark
# - 05-puzzles: Challenging puzzle scenarios

# Expected console output:
# ┌─────────────────┬──────────┬──────────┬──────────┐
# │ Scenario        │ MAPF-2M  │ MAPF-6M  │ MAPF-85M │
# ├─────────────────┼──────────┼──────────┼──────────┤
# │ Random          │ 0.89     │ 0.92     │ 0.95     │
# │ Mazes           │ 0.91     │ 0.94     │ 0.97     │
# │ Warehouse       │ 0.85     │ 0.88     │ 0.92     │
# │ MovingAI        │ 0.78     │ 0.82     │ 0.87     │
# │ Puzzles         │ 0.72     │ 0.76     │ 0.81     │
# └─────────────────┴──────────┴──────────┴──────────┘
```

```python
# Programmatic benchmark usage
from pathlib import Path
import yaml
from pogema_toolbox.evaluator import evaluation
from pogema_toolbox.registry import ToolboxRegistry
from pogema_toolbox.create_env import Environment
from create_env import create_eval_env
from mapf_gpt.inference import MAPFGPTInference, MAPFGPTInferenceConfig

# Register components
ToolboxRegistry.register_env("Environment", create_eval_env, Environment)
ToolboxRegistry.register_algorithm("MAPF-GPT", MAPFGPTInference, MAPFGPTInferenceConfig)

# Load maps and config
with open("eval_configs/01-random/maps.yaml", "r") as f:
    maps = yaml.safe_load(f)
ToolboxRegistry.register_maps(maps)

with open("eval_configs/01-random/01-random.yaml") as f:
    eval_config = yaml.safe_load(f)

# Run evaluation
eval_dir = Path("eval_configs/01-random")
evaluation(eval_config, eval_dir=eval_dir)
```

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

### MAPF Observation Tokenization for Transformer Models

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

This Python code demonstrates how to use the `Tokenizer` class to convert MAPF observations into token sequences suitable for transformer models. It covers initializing the tokenizer, creating a sample observation, encoding it into tensors or NumPy arrays, and decoding tokens back into an observation. The vocabulary structure is also detailed.

```python
from tokenizer.tokenizer import Tokenizer, Encoder
from tokenizer.parameters import InputParameters
import numpy as np

# Initialize tokenizer with default parameters
cfg = InputParameters()
tokenizer = Tokenizer(cfg)

# Create a sample observation
observation = {
    "agents": [
        {
            "relative_pos": (0, 0),           # Agent position relative to ego
            "relative_goal": (5, 3),          # Goal position relative to ego
            "previous_actions": ["n", "u", "r", "r", "d"],  # Last 5 actions
            "next_action": "0101",            # Greedy action hint (binary) 
        },
        {
            "relative_pos": (2, -1),
            "relative_goal": (8, 0),
            "previous_actions": ["n", "n", "l", "u", "u"],
            "next_action": "0011",
        },
    ],
    "cost2go": np.zeros((11, 11), dtype=int),  # 11x11 cost-to-go grid
}

# Encode observation to tensor
tokens = tokenizer(observation, return_tensors="pt")
print(f"Token shape: {tokens.shape}")  # Shape: (256,)

# Encode to numpy array
tokens_np = tokenizer.encode(observation)
print(f"Numpy shape: {tokens_np.shape}")  # Shape: (256,)

# Decode back to observation
decoded = tokenizer.decode(tokens)
print(f"Decoded agents: {len(decoded['agents'])}")

# Vocabulary structure:
# - Indices 0-43: Coordinate values (-20 to +20, plus special values)
# - Indices 44-49: Actions (n=none, w=wait, u=up, d=down, l=left, r=right)
# - Indices 50-65: Next action hints (binary 0000 to 1111)
# - Index 66: Padding token (!)
```

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

### Download MAPF-GPT Datasets with Hugging Face Hub

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

This snippet demonstrates how to download specific parts of the MAPF-GPT dataset, including the validation set and a subset of the training data, using the `hf_hub_download` function. It allows for custom dataset sizes by adjusting the number of training chunks downloaded.

```python
from huggingface_hub import hf_hub_download

repo_id = "aandreychuk/MAPF-GPT"
local_dir = "dataset"

# Download validation set (required)
hf_hub_download(
    repo_id=repo_id,
    repo_type='dataset',
    subfolder="validation",
    filename="chunk_0_part_0.arrow",
    local_dir=local_dir
)

# Download subset of training data (5 chunks = ~25 GB)
for chunk in range(5):  # Reduce from 50 for smaller dataset
    for part in range(10):
        hf_hub_download(
            repo_id=repo_id,
            repo_type='dataset',
            subfolder="train",
            filename=f"chunk_{{chunk}}_part_{{part}}.arrow",
            local_dir=local_dir
        )
```

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

### Model Configuration Parameters for MAPF-GPT (Python)

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

Defines configuration parameters for different sized MAPF-GPT models (2M, 6M, 85M) and general training hyperparameters. These settings control model architecture, training iterations, batch sizes, and optimization details.

```python
# 2M Parameter Model (mapf_gpt/config-2M.py)
compile = True
max_iters = 30000
lr_decay_iters = 30000
batch_size = 4096
n_layer = 5
n_head = 5
n_embd = 160
block_size = 256
gradient_accumulation_steps = 16

# 6M Parameter Model (mapf_gpt/config-6M.py)
compile = True
max_iters = 30000
lr_decay_iters = 30000
batch_size = 2048
n_layer = 8
n_head = 8
n_embd = 256
block_size = 256
gradient_accumulation_steps = 16

# 85M Parameter Model (mapf_gpt/config-85M.py)
compile = True
max_iters = 400000
lr_decay_iters = 400000
batch_size = 512
n_layer = 12
n_head = 12
n_embd = 768
block_size = 256
gradient_accumulation_steps = 16

# Training hyperparameters (defaults in train.py)
learning_rate = 6e-4      # Peak learning rate
min_lr = 6e-5             # Minimum learning rate
warmup_iters = 2000       # Warmup steps
weight_decay = 1e-1       # AdamW weight decay
beta1 = 0.9               # Adam beta1
beta2 = 0.95              # Adam beta2
grad_clip = 1.0           # Gradient clipping
dropout = 0.0             # Dropout (0 for pretraining)
```

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

### Configure LACAM3 C++ Library Build with CMake

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/lacam/lacam3/CMakeLists.txt

This CMake script configures the build for the LACAM3 library. It finds all C++ source files in the ./src directory, sets the project name, creates a static library, and specifies compilation options, C++ standard, and interface include directories. It also ensures position-independent code is enabled.

```cmake
cmake_minimum_required(VERSION 3.16)
file(GLOB SRCS "./src/*.cpp")
project(lacam3)
add_library(${PROJECT_NAME} STATIC ${SRCS})
target_compile_options(${PROJECT_NAME} PUBLIC -O3 -Wall)
target_compile_features(${PROJECT_NAME} PUBLIC cxx_std_17)
target_include_directories(${PROJECT_NAME} INTERFACE ./include)

set_property(TARGET lacam3 PROPERTY POSITION_INDEPENDENT_CODE ON)
```

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

### Configure LACAM C++ Library with CMake

Source: https://github.com/cognitiveaisystems/mapf-gpt/blob/main/lacam/CMakeLists.txt

This snippet configures a shared C++ library named 'lacam' using CMake. It specifies C++17 as the required standard, includes a private directory for headers from 'lacam3', and links against the 'lacam3' library and the pthreads library.

```cmake
cmake_minimum_required(VERSION 3.16)
project(lacam-project CXX)

add_subdirectory(./lacam3)

add_library(lacam SHARED main.cpp)
target_compile_features(lacam PUBLIC cxx_std_17)
target_include_directories(lacam PRIVATE ./lacam3/include)
target_link_libraries(lacam lacam3 libpthread.so)
```

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

### GPT Model Architecture for MAPF

Source: https://context7.com/cognitiveaisystems/mapf-gpt/llms.txt

The `GPT` class implements a transformer-based model with non-causal self-attention, tailored for MAPF action prediction. It features weight tying between token embeddings and output projections, and supports Flash Attention for enhanced inference efficiency. Model configuration includes block size, vocabulary size, number of layers and heads, embedding dimension, and dropout rate.

```python
from mapf_gpt.model import GPT, GPTConfig
import torch

# Define model configuration
config = GPTConfig(
    block_size=256,      # Maximum sequence length (context size)
    vocab_size=67,       # Size of token vocabulary
    n_layer=8,           # Number of transformer blocks
    n_head=8,            # Number of attention heads
    n_embd=256,          # Embedding dimension
    dropout=0.0,         # Dropout rate (0 for inference)
    bias=False,          # Whether to use bias in linear layers
)

# Initialize model
model = GPT(config)
model.to('cuda')
model.eval()

# Load pre-trained weights
checkpoint = torch.load('weights/model-6M.pt', map_location='cuda')
model.load_state_dict(checkpoint['model'], strict=False)

# Get model parameter count
print(f"Parameters: {model.get_num_params() / 1e6:.2f}M")
```

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