{"id":25008771,"url":"https://github.com/f14-bertolotti/torchess","last_synced_at":"2025-03-30T01:26:43.630Z","repository":{"id":272182070,"uuid":"915682580","full_name":"f14-bertolotti/torchess","owner":"f14-bertolotti","description":"cuda torch extension for a chess engine","archived":false,"fork":false,"pushed_at":"2025-02-02T13:59:51.000Z","size":227,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-02T14:33:13.336Z","etag":null,"topics":["chess","cuda","torch"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f14-bertolotti.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-12T14:29:05.000Z","updated_at":"2025-02-02T14:01:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"43c3aca5-0aa2-414e-a033-ad2bb7cb29af","html_url":"https://github.com/f14-bertolotti/torchess","commit_stats":null,"previous_names":["f14-bertolotti/pawner","f14-bertolotti/torch-chess","f14-bertolotti/torchess"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f14-bertolotti%2Ftorchess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f14-bertolotti%2Ftorchess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f14-bertolotti%2Ftorchess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f14-bertolotti%2Ftorchess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f14-bertolotti","download_url":"https://codeload.github.com/f14-bertolotti/torchess/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246263834,"owners_count":20749358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","cuda","torch"],"created_at":"2025-02-05T03:28:42.005Z","updated_at":"2025-03-30T01:26:43.598Z","avatar_url":"https://github.com/f14-bertolotti.png","language":"Python","readme":"\n# Torchess  \n\n**Torchess** is a pure CUDA-based PyTorch extension for chess, designed for reinforcement learning applications. It provides a minimal, low-level interface for managing chess environments efficiently on the GPU.  \n\n## Features  \n- Fully implemented in CUDA for fast execution.  \n- Simple and minimalistic interface.  \n- Designed for reinforcement learning environments.  \n- Supports batched operations across multiple environments.  \n\n---\n\n## Installation  \n\nCreate a virtual environment and install the package:  \n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install torchess\n```\n\n---\n\n## API  \n\n### 1. **Initialization**  \n```python\nboards, players = init(envs: int)\n```\n- **Input:**  \n  - `envs`: Number of environments (games) to initialize.  \n- **Output:**  \n  - `boards`: A tensor of shape `(envs, 100)` representing chess boards initialized to the starting position.  \n  - `players`: A tensor of shape `(envs,)` indicating the current player to move (0 for white).  \n\n### 2. **Reset**  \n```python\nboards, players = reset(boards: torch.Tensor, players: torch.Tensor, mask: torch.Tensor | None = None)\n```\n- **Input:**  \n  - `boards`: Current board states.  \n  - `players`: Current players.  \n  - `mask` (optional): Boolean tensor indicating which environments should be reset.  \n- **Output:**  \n  - Resets selected boards to the starting position. If `mask` is `None`, all boards are reset.  \n\n### 3. **Step**  \n```python\nstep(boards: torch.Tensor, actions: torch.Tensor, players: torch.Tensor, dones: torch.Tensor, rewards: torch.Tensor)\n```\n- **Input:**  \n  - `boards`: Current board states.  \n  - `actions`: Tensor of moves to apply.  \n  - `players`: Current players.  \n  - `dones`: Tensor indicating which environments have ended.  \n  - `rewards`: Tensor storing rewards.  \n- **Effect:**  \n  - Advances each game by one step.  \n  - Updates `boards`, `players`, `dones`, and `rewards` **in place**.  \n\n\u003e **Note:** Any additional structure (e.g., Gym compatibility) should be implemented separately. This is a low-level interface for RL applications.  \n\n---\n\n## Board Representation  \n\nA chessboard is represented as a `100`-element tensor:  \n- **First 64 elements**: Piece positions (8×8 board).  \n- **Last 36 elements**: Additional game state information.  \n\n### **Piece Encoding**  \n\n| Piece            | Value |\n|-----------------|------:|\n| Empty           | 0     |\n| White Pawn      | 1     |\n| White Knight    | 2     |\n| White Bishop    | 3     |\n| White Rook      | 4     |\n| White Queen     | 5     |\n| White King      | 6     |\n| Black Pawn      | 7     |\n| Black Knight    | 8     |\n| Black Bishop    | 9     |\n| Black Rook      | 10    |\n| Black Queen     | 11    |\n| Black King      | 12    |\n\n### **Game State Encoding (Last 36 Elements)**  \n\n| Description                      | Index |\n|----------------------------------|------:|\n| White king moved                | 64    |\n| Black king moved                | 65    |\n| White kingside rook moved        | 66    |\n| Black kingside rook moved        | 67    |\n| White queenside rook moved       | 68    |\n| Black queenside rook moved       | 69    |\n| White previous move              | 70    |\n| White move before that           | 75    |\n| Black previous move              | 80    |\n| Black move before that           | 85    |\n| White king position              | 90    |\n| Black king position              | 92    |\n| Rule 50 counter                  | 94    |\n| Threefold repetition counter     | 95    |\n\n---\n\n## Action Representation  \n\nActions are encoded using **algebraic notation**, specifying:  \n1. **Source position** (`row, col`)  \n2. **Target position** (`row, col`)  \n3. **Special move flag (optional, fifth element)**  \n\n### **Special Move Encoding**  \n\n| Move Type         | Value |\n|------------------|------:|\n| Normal move     | 0     |\n| King-side castling | 1     |\n| Queen-side castling | 2     |\n| Queen promotion | 3     |\n| Rook promotion  | 4     |\n| Bishop promotion | 5     |\n| Knight promotion | 6     |\n\n---\n\n## Reward Representation  \n\n- **Games terminate when a player makes an invalid move.**  \n- **Reward system:**  \n  - **Invalid move:** `-1` penalty.  \n  - **Invalid move while in check:** Opponent receives `+1`.  \n  - **50-move rule (no captures/promotions in 50 turns):** Draw (`+0.5` for both players).  \n\n\u003e **Note:** Checkmate and stalemate are not explicitly checked to maintain speed. When a player checkmate the other, the game naturally ends the next turn because the losing player has no valid move to make.\n\n---\n\n## Threefold Repetition Rule  \n\n- In standard chess, a player can claim a draw if the same position occurs three times.  \n- **In this engine**, instead of tracking full game history, a draw is triggered when **actions are repeated three times**, preventing endless loops in RL training.  \n\n---\n\n## Support the Project  \n\nIf you find this useful, consider **starring the repository** ⭐. This helps gauge interest and encourages further development!  \n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff14-bertolotti%2Ftorchess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff14-bertolotti%2Ftorchess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff14-bertolotti%2Ftorchess/lists"}