# Quantik Core
[](https://codecov.io/github/mberlanda/quantik-core-py)
A high-performance Python library for manipulating Quantik game states, optimized for Monte Carlo simulations, game analysis, and AI engines.
## What is Quantik?
Quantik is an elegant 4×4 abstract strategy game where players compete to complete lines with all four unique shapes.
### Game Rules
- **Board**: 4×4 grid (16 squares)
- **Pieces**: 4 different shapes (A, B, C, D) in 2 colors (one per player)
- **Objective**: Be the first to complete a **row**, **column**, or **2×2 zone** containing all four different shapes
- **Gameplay**:
- Players alternate placing one of their remaining pieces on an empty square
- A piece cannot be placed if the opponent already has the same shape in the target square's row, column, or 2×2 zone
- Colors don't matter for winning - only the presence of all four shapes in a line
### Example Victory
```
A B C D ← Row with all 4 shapes = WIN!
. . . .
. . . .
. . . .
```
## Features
This library provides the core foundation for building:
- **Monte Carlo Tree Search (MCTS)** engines
- **Game analysis** and position evaluation systems
- **AI training** and recommendation engines
- **Opening book** generation and endgame databases
- **Statistical analysis** of game patterns
- **Game engines** and tournament systems
- **Research tools** for combinatorial game theory
**Current Implementation:**
- **State Representation**: Complete bitboard-based game state management
- **Serialization**: Binary, QFEN, and CBOR formats
- **Canonicalization**: Symmetry-aware position normalization
- **Move Generation**: Coming in next release
- **Game Logic**: Win detection and move validation (planned)
## Core Capabilities
- **Blazing Fast Operations**: Bitboard-based representation enables O(1) move generation and win detection
- **Compact Memory Footprint**: Game states fit in just 16 bytes with optional 18-byte canonical serialization
- **Symmetry Normalization**: Automatic canonicalization under rotations, reflections, color swaps, and shape relabeling
- **Cross-Language Compatibility**: Binary format designed for interoperability with Go, Rust, and other engines
- **Human-Readable Format**: QFEN (Quantik FEN) notation for debugging and documentation
- **Self-Describing Serialization**: CBOR-based format for robust data exchange
## Installation
```bash
pip install quantik-core
```
## Quick Start
```python
from quantik_core import State
# Create an empty game state
state = State.empty()
# Create a position using QFEN notation
state = State.from_qfen("A.../..b./.c../...D")
# Convert to human-readable format
qfen = state.to_qfen()
print(f"Position: {qfen}") # Output: A.../..b./.c../...D
# Get canonical representation for symmetry analysis
canonical_key = state.canonical_key()
print(f"Canonical key: {canonical_key.hex()}")
# Serialize to binary format (18 bytes)
binary_data = state.pack()
restored_state = State.unpack(binary_data)
# Serialize to CBOR for cross-language compatibility
cbor_data = state.to_cbor(canon=True, meta={"game_id": 123})
restored_from_cbor = State.from_cbor(cbor_data)
```
## Performance
- **State Operations**: Bitboard-based representation enables fast position manipulation
- **Canonicalization**: <1µs per position with precomputed lookup tables
- **Memory Usage**: 16 bytes per game state + 1MB for transformation LUTs
- **Serialization**: 18-byte binary format, human-readable QFEN, or self-describing CBOR
## Use Cases
### Position Analysis and Canonicalization
```python
from quantik_core import State
# Create different equivalent positions
pos1 = State.from_qfen("A.../..../..../....")
pos2 = State.from_qfen("..../..../..../.a..") # Rotated + color swapped
# Both have the same canonical representation
assert pos1.canonical_key() == pos2.canonical_key()
```
### Database Storage and Retrieval
```python
# Use canonical keys as database indices
positions_db = {}
canonical_key = state.canonical_key()
positions_db[canonical_key] = {"eval": 0.75, "visits": 1000}
```
### Cross-Language Data Exchange
```python
# Save position with metadata for other engines
data = state.to_cbor(
canon=True,
mc=5000, # Monte Carlo simulations
meta={"depth": 12, "engine": "quantik-py-v1"}
)
# Binary format for high-performance applications
binary = state.pack() # Just 18 bytes
```
## Technical Details
- **Representation**: 8 disjoint 16-bit bitboards (one per color-shape combination)
- **Symmetries**: Dihedral group D4 (8 rotations/reflections) × color swap × shape permutations = 384 total
- **Serialization**: Versioned binary format with little-endian 16-bit words
- **Canonicalization**: Lexicographically minimal representation across symmetry orbit
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Citation
If you use this library in research, please cite:
```bibtex
@software{quantik_core,
title={Quantik Core: High-Performance Game State Manipulation},
author={Mauro Berlanda},
year={2025},
url={https://github.com/mberlanda/quantik-core-py}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "quantik-core",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "quantik, board-games, game-ai, monte-carlo, bitboards, game-engine, mcts, game-theory, combinatorial-games",
"author": null,
"author_email": "Mauro Berlanda <mauro.berlanda@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/eb/3dc1dab99d814c183dbf983111be6cb0db9d8ac79a5db57404bd3a86d32e/quantik_core-0.1.1.tar.gz",
"platform": null,
"description": "# Quantik Core\n\n[](https://codecov.io/github/mberlanda/quantik-core-py)\n\n\nA high-performance Python library for manipulating Quantik game states, optimized for Monte Carlo simulations, game analysis, and AI engines.\n\n## What is Quantik?\n\nQuantik is an elegant 4\u00d74 abstract strategy game where players compete to complete lines with all four unique shapes.\n\n### Game Rules\n\n- **Board**: 4\u00d74 grid (16 squares)\n- **Pieces**: 4 different shapes (A, B, C, D) in 2 colors (one per player)\n- **Objective**: Be the first to complete a **row**, **column**, or **2\u00d72 zone** containing all four different shapes\n- **Gameplay**: \n - Players alternate placing one of their remaining pieces on an empty square\n - A piece cannot be placed if the opponent already has the same shape in the target square's row, column, or 2\u00d72 zone\n - Colors don't matter for winning - only the presence of all four shapes in a line\n\n### Example Victory\n\n```\nA B C D \u2190 Row with all 4 shapes = WIN!\n. . . .\n. . . .\n. . . .\n```\n\n## Features\n\nThis library provides the core foundation for building:\n\n- **Monte Carlo Tree Search (MCTS)** engines\n- **Game analysis** and position evaluation systems \n- **AI training** and recommendation engines\n- **Opening book** generation and endgame databases\n- **Statistical analysis** of game patterns\n- **Game engines** and tournament systems\n- **Research tools** for combinatorial game theory\n\n**Current Implementation:**\n- **State Representation**: Complete bitboard-based game state management\n- **Serialization**: Binary, QFEN, and CBOR formats\n- **Canonicalization**: Symmetry-aware position normalization\n- **Move Generation**: Coming in next release\n- **Game Logic**: Win detection and move validation (planned)\n\n## Core Capabilities\n\n- **Blazing Fast Operations**: Bitboard-based representation enables O(1) move generation and win detection\n- **Compact Memory Footprint**: Game states fit in just 16 bytes with optional 18-byte canonical serialization\n- **Symmetry Normalization**: Automatic canonicalization under rotations, reflections, color swaps, and shape relabeling\n- **Cross-Language Compatibility**: Binary format designed for interoperability with Go, Rust, and other engines\n- **Human-Readable Format**: QFEN (Quantik FEN) notation for debugging and documentation\n- **Self-Describing Serialization**: CBOR-based format for robust data exchange\n\n## Installation\n\n```bash\npip install quantik-core\n```\n\n## Quick Start\n\n```python\nfrom quantik_core import State\n\n# Create an empty game state\nstate = State.empty()\n\n# Create a position using QFEN notation\nstate = State.from_qfen(\"A.../..b./.c../...D\")\n\n# Convert to human-readable format\nqfen = state.to_qfen()\nprint(f\"Position: {qfen}\") # Output: A.../..b./.c../...D\n\n# Get canonical representation for symmetry analysis\ncanonical_key = state.canonical_key()\nprint(f\"Canonical key: {canonical_key.hex()}\")\n\n# Serialize to binary format (18 bytes)\nbinary_data = state.pack()\nrestored_state = State.unpack(binary_data)\n\n# Serialize to CBOR for cross-language compatibility\ncbor_data = state.to_cbor(canon=True, meta={\"game_id\": 123})\nrestored_from_cbor = State.from_cbor(cbor_data)\n```\n\n## Performance\n\n- **State Operations**: Bitboard-based representation enables fast position manipulation\n- **Canonicalization**: <1\u00b5s per position with precomputed lookup tables\n- **Memory Usage**: 16 bytes per game state + 1MB for transformation LUTs\n- **Serialization**: 18-byte binary format, human-readable QFEN, or self-describing CBOR\n\n## Use Cases\n\n### Position Analysis and Canonicalization\n```python\nfrom quantik_core import State\n\n# Create different equivalent positions\npos1 = State.from_qfen(\"A.../..../..../....\") \npos2 = State.from_qfen(\"..../..../..../.a..\") # Rotated + color swapped\n\n# Both have the same canonical representation\nassert pos1.canonical_key() == pos2.canonical_key()\n```\n\n### Database Storage and Retrieval\n```python\n# Use canonical keys as database indices\npositions_db = {}\ncanonical_key = state.canonical_key()\npositions_db[canonical_key] = {\"eval\": 0.75, \"visits\": 1000}\n```\n\n### Cross-Language Data Exchange\n```python\n# Save position with metadata for other engines\ndata = state.to_cbor(\n canon=True,\n mc=5000, # Monte Carlo simulations\n meta={\"depth\": 12, \"engine\": \"quantik-py-v1\"}\n)\n\n# Binary format for high-performance applications\nbinary = state.pack() # Just 18 bytes\n```\n\n## Technical Details\n\n- **Representation**: 8 disjoint 16-bit bitboards (one per color-shape combination)\n- **Symmetries**: Dihedral group D4 (8 rotations/reflections) \u00d7 color swap \u00d7 shape permutations = 384 total\n- **Serialization**: Versioned binary format with little-endian 16-bit words\n- **Canonicalization**: Lexicographically minimal representation across symmetry orbit\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Citation\n\nIf you use this library in research, please cite:\n```bibtex\n@software{quantik_core,\n title={Quantik Core: High-Performance Game State Manipulation},\n author={Mauro Berlanda},\n year={2025},\n url={https://github.com/mberlanda/quantik-core-py}\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "High-performance core utilities for Quantik game state manipulation",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/mauroberlanda/quantik-core-py/issues",
"Documentation": "https://quantik-core-py.readthedocs.io",
"Homepage": "https://github.com/mauroberlanda/quantik-core-py",
"Repository": "https://github.com/mauroberlanda/quantik-core-py"
},
"split_keywords": [
"quantik",
" board-games",
" game-ai",
" monte-carlo",
" bitboards",
" game-engine",
" mcts",
" game-theory",
" combinatorial-games"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "234aa51f9244128b6ceeabad9dc530cc3c0dd2c5265417a95695934e74e84357",
"md5": "31f9f2f32514a450b7c3bf52b5d73151",
"sha256": "6bf19505863b05c5565aceffd12b3e3cacf849d127fad56e6059b07daee53248"
},
"downloads": -1,
"filename": "quantik_core-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31f9f2f32514a450b7c3bf52b5d73151",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7990,
"upload_time": "2025-09-05T05:37:03",
"upload_time_iso_8601": "2025-09-05T05:37:03.183133Z",
"url": "https://files.pythonhosted.org/packages/23/4a/a51f9244128b6ceeabad9dc530cc3c0dd2c5265417a95695934e74e84357/quantik_core-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d0eb3dc1dab99d814c183dbf983111be6cb0db9d8ac79a5db57404bd3a86d32e",
"md5": "018a61066ed4169f7351fa0be62c6f72",
"sha256": "cee896e39ed00aed9ea63385400bf46f966b5099e221bfaea0cbd0f3f0d1818d"
},
"downloads": -1,
"filename": "quantik_core-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "018a61066ed4169f7351fa0be62c6f72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13068,
"upload_time": "2025-09-05T05:37:04",
"upload_time_iso_8601": "2025-09-05T05:37:04.415624Z",
"url": "https://files.pythonhosted.org/packages/d0/eb/3dc1dab99d814c183dbf983111be6cb0db9d8ac79a5db57404bd3a86d32e/quantik_core-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 05:37:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mauroberlanda",
"github_project": "quantik-core-py",
"github_not_found": true,
"lcname": "quantik-core"
}
JSON
