hpyhex-rs 0.2.3
Simplified implementations of the HappyHex game components and hexagonal system in Rust.
Requires Python: >=3.8
Keywords: grid, game, happyhex, hex, pyo3, rust

For the Rust crate of the same name, see [hpyhex-rs on crates.io](https://crates.io/crates/hpyhex-rs) or [hpyhex-rs Rust Source](https://github.com/williamwutq/hpyhex-rs/tree/master/README.md).

# hpyhex-rs
Simplified implementations of the HappyHex game components and hexagonal system in Rust.
This is a drop-in replacement for the original `hpyhex` package, optimized for performance and memory usage. Offers up to 200x speed improvements in critical operations and around 60x speed improvements in essential gameplay workflows.

## Installation
```bash
pip install hpyhex-rs
```

## **Important Notes**
1. **Conflicting with Native Python Package**
   
   `hpyhex-rs` conflicts with the existing `hpyhex` package on PyPI. If you have `hpyhex` installed, please uninstall it first using:
   ```bash
   pip uninstall hpyhex
   ```
   
3. **Difference in Importing Modules**  
   
   In `hpyhex-rs`, all main classes and functions are located directly under the `hpyhex` module. For example, to import the `Hex` class, use:
   ```python
   from hpyhex import Hex, Game
   ```
   In contrast, the original `hpyhex` package requires importing from submodules (`hex` and `game`), such as:
   ```python
   from hpyhex.hex import Hex
   from hpyhex.game import Game
   ```
   
   For the best import compatibility, use the following pattern:
   ```python
   try:
      from hpyhex import Hex, Game  # hpyhex-rs
      hpyhex_version = "hpyhex-rs"
   except ImportError:
      from hpyhex.hex import Hex    # hpyhex
      from hpyhex.game import Game   # hpyhex
      hpyhex_version = "hpyhex"
   ```
   This code attempts to import from `hpyhex-rs` first, and falls back to the original `hpyhex` package if that fails, allowing your code to work with either package seamlessly.

4. **Not Interoperable with Original Package**
   
   Due to differences in the Rust implementation, `hpyhex-rs` objects cannot be mixed with the original `hpyhex` package objects. The `Hex` of `hpyhex-rs` is not compatible and cannot be converted to/from the `Hex` of `hpyhex`, for example.
   
   **This matters primarily in serialization scenarios**, but not in regular usage, as you would typically use either `hpyhex` or `hpyhex-rs` exclusively in a project. 
   
   If you are using built-in APIs in `hpyhex` to serialize data structures (e.g., `int(piece_value)`, `Piece(integer_value)`), you can load them back using `hpyhex-rs`, and vice versa. The byte representation of pieces is compatible between the two packages.
   
   However, if you use a python tool to serialize data structures from `hpyhex` as Python objects (e.g., `pickle`), you cannot load them back using `hpyhex-rs`, and vice versa. `hpyhex-rs` offers `serialize` and `deserialize` functions for its own data structures.

5. **Does Not Contain `benchmark` Module (Yet)**
   
   The original `hpyhex` package contains a `benchmark` module for performance testing of machine learned, heuristic, determinstic, and random algorithms. This module is not yet implemented in `hpyhex-rs`, but may be added in future releases. The source code for the benchmark module is very short and can be found [online](https://raw.githubusercontent.com/williamwutq/hpyhexml/main/hpyhex/hpyhex/benchmark.py). You may copy it into your project if needed.
   
6. **Updates Can Lag Behind Original Package**
   
   This package currently targets the [0.2.0](https://pypi.org/project/hpyhex/0.2.0/) version of `hpyhex`. Features from later versions may not be fully supported yet, but may be added in future releases.

## Features
- Hexagonal grid representation
- Basic game mechanics for HappyHex
- Utility functions for hexagonal calculations
- High performance through Rust implementation
- Native serialization and deserialization methods compatible with Rust hpyhex-rs crate
- NumPy integration for machine learning applications

## Author
Developed by William Wu.

## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/williamwutq/hpyhex-rs/tree/master/py/LICENSE) file for details. Visit [MIT License](https://opensource.org/licenses/MIT) for more information about the MIT License. The choice of license is to offer compatibility with the original `hpyhex` package and the broader HappyHex project, which also uses the MIT License.

## Quickstart

1. Install the package:
   ```bash
   pip install hpyhex-rs
   ```
2. Import and use the main classes as shown above.
3. Create custom algorithms to interact with the game environment.

## Examples

See the [examples directory](https://github.com/williamwutq/hpyhex-rs/tree/master/py/examples/) for complete example scripts demonstrating various functionalities of the library, including basic usage, game simulations, serialization, and NumPy integration.

Also see the [benchmark directory](https://github.com/williamwutq/hpyhex-rs/tree/master/py/bench) for performance benchmarking code, which are excellent examples of the hpyhex API usage, supplemental to the simple [hpyhex](https://pypi.org/project/hpyhex/) documentation.

## Main Classes

- **Hex**: Represents a hexagonal grid coordinate using a custom line-based system. Supports arithmetic, hashing, and tuple compatibility.
- **Piece**: Represents a shape made of 7 blocks, optimized for memory and performance. Use `PieceFactory` to create pieces by name or byte value.
- **HexEngine**: Manages the hexagonal grid, supports adding pieces, eliminating lines, and computing entropy.
- **PieceFactory**: Utility for creating pieces by name, byte, or randomly. Provides access to all predefined pieces.
- **Game**: Manages the game state, piece queue, score, and turn. Supports adding pieces and making moves with algorithms.

## Hexagonal System

The `Hex` class represents a 2D coordinate in a hexagonal grid system using a specialized integer coordinate model. It supports both raw coordinate access and derived line-based computations across three axes: I, J, and K.

### Coordinate System

This system uses three axes (I, J, K) that run diagonally through the hexagonal grid:

- I+ is 60 degrees from J+, J+ is 60 degrees from K+, and K+ is 60 degrees from I-.
- Coordinates (i, k) correspond to a basis for representing any hexagon.
- **Raw coordinates** (or hex coordinates) refer to the distance of a point along one of the axes multiplied by 2.
- For raw coordinates, the relationships between the axes are defined such that `i - j + k = 0`.
- **Line coordinates** (or line-distance based coordinates) are based on the distance perpendicular to the axes.
- For line coordinates, the relationships between the axes are defined such that `I + J - K = 0`.
- All line coordinates correspond to some raw coordinate, but the inverse is not true. Due to the complexities with dealing with raw coordinates, it is preferable to use line coordinates. **The `hpyhex` API discourages the use of raw coordinates, and all its methods refers to line coordinates only, except those for backward compatibility.**

#### Coordinate System Visualization

Three example points with raw coordinates (2i, 2j, 2k):

```
   I
  / * (5, 4, -1)
 /     * (5, 7, 2)
o - - J
 \ * (0, 3, 3)
  \
   K
```

Three example points with line coordinates (I, J, K):

```
   I
  / * (1, 2, 3)
 /     * (3, 1, 4)
o - - J
 \ * (2, -1, 1)
  \
   K
```

### Grid Structure

- Uses an axial coordinate system (I, K) to represent hexagonal grids, where J = K - I.
- Three axes: I, J, K (not to be confused with 3D coordinates).
- Line-coordinates (I, K) are perpendicular distances to axes, calculated from raw coordinates.

### Grid Size

The total number of blocks in a hexagonal grid of radius `r` is calculated as:

```
Aₖ = 1 + 3*r*(r - 1)
```

This is derived from the recursive pattern:

```
Aₖ = Aₖ₋₁ + 6*(k - 1); A₁ = 1
```

Valid hexagonal grid sizes for common radii:
- Radius 0: 0 cell (Not valid for HexEngine, but can be valid for other purposes)
- Radius 1: 1 cell
- Radius 2: 7 cells
- Radius 3: 19 cells
- Radius 4: 37 cells
- Radius 5: 61 cells
- Radius 6: 91 cells
- Radius 10: 271 cells

### Hex Class Details

Represents a hexagonal grid coordinate using a custom line-based coordinate system.

This class models hexagonal positions with two line coordinates (i, k), implicitly defining the third axis (j) as `j = k - i` to maintain hex grid constraints. It supports standard arithmetic, equality, and hashing operations, as well as compatibility with coordinate tuples.

For small grids, Hex instances are cached for performance, allowing more efficient memory usage and faster access. The caching is limited to a range of -64 to 64 for both i and k coordinates.

Use of Hex over tuples is recommended for clarity and to leverage the singleton feature of small Hexes.

#### Attributes
- `i` (int): The line i coordinate.
- `j` (int): The computed line j coordinate (k - i).
- `k` (int): The line k coordinate.

#### Notes
- This class is immutable and optimized with `__slots__`.
- Raw coordinate methods (`__i__`, `__j__`, `__k__`) are retained for backward compatibility.
- Only basic functionality is implemented; complex adjacency, iteration, and mutability features are omitted for simplicity.

## Usage
```python
from hpyhex import Hex, Piece, HexEngine
from hpyhex import Game, PieceFactory, random_engine

# Create a hexagonal coordinate
coo = Hex(0, 1)

# Create a piece by name
piece = PieceFactory.get_piece("triangle_3_a")

# Create a game engine with radius 3
engine = HexEngine(3)

# Add a piece to the engine
engine.add_piece(piece, coo)

# Eliminate lines and get score
score = len(engine.eliminate()) * 5

# Create a game with engine radius and queue size
# Note that although the parameters are named engine and queue, they refer to the radius of the engine and the size of the piece queue respectively. They are not named engine_radius or queue_size.
game = Game(engine=3, queue=5)
print(game)

# Make a move using a custom algorithm
def simple_algorithm(engine, queue):
	# Always place the first piece at the center
	return 0, Hex(0, 0)
game.make_move(simple_algorithm)

# Serialize and save the game state compatibly with hpyhex-rs crate
serialized_engine = engine.hpyhex_rs_serialize()
serialized_pieces = [p.hpyhex_rs_serialize() for p in game.piece_queue]
with open("my_game_data.bin", "wb") as binary_file:
   binary_file.write(serialized_engine)
   for piece_bytes in serialized_pieces:
      binary_file.write(piece_bytes)

# Interact with NumPy
import numpy as np

# Convert a piece to a NumPy boolean array
piece_array = piece.to_numpy()

# Create a piece from a NumPy uint8 array
arr = np.array([1, 1, 1, 0, 0, 0, 0], dtype=np.uint8)
new_piece = Piece.from_numpy_uint8(arr)

# Convert a random engine to a NumPy array
a_random_engine = random_engine(6)
engine_array = a_random_engine.to_numpy_uint32()

# Create an engine from a NumPy uint32 array
arr_engine = np.random.randint(0, 2, size=91, dtype=np.uint32) # Example for radius 6
new_engine = HexEngine.from_numpy_uint32(arr_engine, radius=6)

# Note that all dtypes listed in the NumPy Integration section are supported, and float16 is also supported if compiled with the "half" feature.
```

## Native Serialization

`hpyhex-rs` provides native serialization and deserialization methods for `HexEngine` and `Piece` classes, compatible with the Rust `hpyhex-rs` crate's `TryFrom<Vec<u8>>` and `Into<Vec<u8>>` implementations.

The serialization methods are named `hpyhex_rs_serialize()` and `hpyhex_rs_deserialize(data: bytes)`, and are available as instance methods for serialization and class methods for deserialization. The naming are prefixed with `hpyhex_rs_` to be future-proof against potential naming conflicts with other serialization methods that might be provided by the target package, `hpyhex`, in the future.

For examples, see [examples 1](./examples/01_binary_serialization.py) for serializing and deserializing `HexEngine`, `Piece`, and entire `Game` states using these methods. For more complex integration with other workflows, see other examples in the [examples directory](./examples/).

### Hex Serialization
- `hpyhex_rs_serialize() -> bytes`: Serializes the `Hex` coordinate into a byte vector.
- `hpyhex_rs_deserialize(data: bytes) -> Hex`: Deserializes a byte vector into a `Hex` instance.

### Piece Serialization
- `hpyhex_rs_serialize() -> bytes`: Serializes the `Piece` into a single byte representing the occupancy state of its blocks.
- `hpyhex_rs_deserialize(data: bytes) -> Piece`: Deserializes a byte vector into a `Piece` instance.

### HexEngine Serialization
- `hpyhex_rs_serialize() -> bytes`: Serializes the `HexEngine` into a byte vector. The format includes the radius as a 4-byte little-endian integer followed by the block states.
- `hpyhex_rs_deserialize(data: bytes) -> HexEngine`: Deserializes a byte vector into a `HexEngine` instance.

### Game Serialization
- `hpyhex_rs_serialize() -> bytes`: Serializes the `Game` into a byte vector. First, the score and turn of the `Game` are serialized into 4-byte little-edian integers, followed by the Vector of `Piece`s, and then the Game's engine with `HexEngine.hpyhex_rs_serialize`.
- `hpyhex_rs_deserialize(data: bytes) -> HexEngine`: Deserializes a byte vector into a `Game` instance, creating its own `HexEngine` instance.

## Native Representation

- `hpyhex_rs_render(prefix: str = "", suffix: str = "", space: str = " ", fill: str = "X", empty: str = "O") -> str`: An instance method on `HexEngine` that renders the current state of the hexagonal grid as a string. The grid is displayed with filled blocks represented by `fill`, empty blocks by `empty`, and spacing controlled by `space`. Optional `prefix` and `suffix` can be added to each line.

```python
>>> from hpyhex import random_engine, HexEngine
>>> print(random_engine(7).hpyhex_rs_render())
       X X O X O O X       
      X O O O X O O O      
     X X X X O O X O X     
    O O X O O X X O X O    
   O O O O O X X O X O O   
  O X O O X X O O X X X O  
 X X O X X X X O O O X O X 
  O O O X O O X O O O O X  
   O X X O X O X X O O X   
    O O O O X O O O X X    
     O X O X O X X O X     
      X X X O X X O X      
       O X X X O O O 
```

- `hpyhex_rs_render_external(values: List[Any], prefix: str = "", suffix: str = "", extra: bool = False) -> str`: A static method that renders a list of values into a string representation of a hexagonal grid. The values are arranged in a hexagonal pattern, with optional prefix and suffix for each line, and an extra line toggle for better alignment. Supports any Python object types as values, converting them to strings for display.

```python
>>> from hpyhex import HexEngine
>>> print(HexEngine.hpyhex_rs_render_external([2, 5, 6.7, 4, 3.65, 4, 5, 3, 0, 0, 45, [6,], 9, 3, 6, 6.7, "He", 4, 9], extra=True))
                                            
            2       5       6.7             
                                            
        4       3.65    4       5           
                                            
    3       0       0       45      [6]     
                                            
        9       3       6       6.7         
                                            
            He      4       9               
                                            
>>> import math
>>> print(HexEngine.hpyhex_rs_render_external(["Number", "PI?", ["r", 5], math.pi, 3, "Math", -5.42]))
                    Number              PI?                           
          ['r', 5]            3.14159265          3                   
                    Math                -5.42                         
```

## Native Methods

- `hpyhex_rs_add_piece_with_index(piece_index: int, position_index: int) -> bool`: A special method in the `Game` class that allows adding a piece using its index in the piece queue and the position index in the engine directly. This method is not part of the original `hpyhex` API but is provided for performance optimization.

- `hpyhex_rs_index_block(radius: int, coo: Hex) -> int`: A static method that retrieves the index of the block at the specified Hex coordinate for a given radius without needing a HexEngine instance. Returns the index or -1 if out of range. This avoids the need to create a HexEngine just to get an index, improving performance for batch operations.

- `hpyhex_rs_coordinate_block(radius: int, index: int) -> Hex`: A static method that retrieves the Hex coordinate of the block at the specified index for a given radius without needing a HexEngine instance. This simplifies coordinate calculation and may improve performance by avoiding unnecessary instance creation.

- `hpyhex_rs_adjacency_list(radius: int) -> List[List[int]]`: A static method that generates the adjacency list for blocks in a hexagonal grid of the specified radius. Each inner list contains the indices of neighboring blocks for the corresponding block. This provides direct access to adjacency information, enabling efficient batch workflows and eliminating redundant calculations across multiple HexEngine instances with the same radius.

- `hpyhex_rs_pair_vec_to_list_any(radius: int, sentinel: Any, values: List[Tuple[Any, Hex]]) -> List[Any]`: Converts a list of (value, Hex) pairs into a list aligned with the hexagonal grid, filling unfilled positions with the specified sentinel value. Supports any Python object types for values and sentinels. NumPy versions also exist for various dtypes with fixed sentinels (see [Pair Vector to List Conversion section](#pair-vector-to-list-conversion) for details).

See the [Adjacency Structure for HexEngine](#adjacency-structure-for-hexEngine) section for more details on how to use the adjacency list. The section describes usage of the adjacency list in the context of NumPy integration, but the same principles apply when using the native method.

## Usage Advices

### Use Objects Provided by This Package
When using `hpyhex-rs`, ensure that you create and manipulate objects (like `Hex`, `Piece`, `HexEngine`, etc.) using the classes provided by this package. Although the API, which is defined in the original `hpyhex` package, accepts various types of inputs (like tuples for coordinates), using the native classes from `hpyhex-rs` ensures optimal performance and compatibility.

For example, following the original flyweight pattern in the `Hex` coordinate class, which uses a cache for small coordinates, the `Hex` class in `hpyhex-rs` also has a similar cache in Rust memory, which is not held by the GIL. Effectively, this means small Hex objects do not contain actual data, but just a pointer to a shared object in Rust memory. There are multiple ways to represent a `Hex` coordinate, either as a tuple `(i, k)`, `(i, j, k)`, or a `Hex` object. While all of them are accepted by most functions in the API, only `Hex` participates in the caching mechanism. Therefore, for frequently used coordinates, it is recommended to create and reuse `Hex` objects from `hpyhex-rs` instead of using tuples.

Take another example of `Piece` objects. Like the original optimized `Piece` in `hpyhex`, no pieces are created at all. Since there are only a total of 127 pieces made out of blocks, all pieces are pre-defined and stored in a global registry. When you create a piece using `Piece()`, it simply returns a reference to the corresponding pre-defined piece object. The Rust implementation further optimizes this by storing all piece objects in Rust memory, removing them from the control of the GIL. When expensive piece operations such as `count_neighbors` are performed, the Rust implementation quickly accesses the piece data and performs raw arithmetic and bit operations in Rust, significantly improving performance compared to the original Python implementation. None of those benefits are provided if integers are used instead of `Piece` objects, although they may seem smaller in memory. (Remember all Python objects have overhead in memory, and an integer is a Python object too.)

### Use Optimized Methods Provided by This Package
When using `hpyhex-rs`, prefer using methods provided by this package for better performance. If a function is already provided by the package, don't write your own implementation in Python, as it may be less efficient.

To illustrate this, take the example of `check_positions` of `HexEngine`. The original `hpyhex` package implements `check_positions` in Python as follows:
```python
def check_positions(self, piece: Union[Piece, int]) -> List[Hex]:
   if isinstance(piece, int):
      piece = Piece(piece)
   elif not isinstance(piece, Piece):
      raise TypeError("Piece must be an instance of Piece or an integer representing a Piece state")
   positions = []
   for a in range(self.radius * 2):
      for b in range(self.radius * 2):
         hex = Hex(a, b)
         if self.check_add(hex, piece):
            positions.append(hex)
   return positions
```

Obviously, if the fact that `hpyhex-rs` provides a Rust-backed implementation of `check_positions` is ignored, the above Python implementation can be used as `hpyhex-rs` also provides the `radius` attribute and `check_add` method. However, this implementation is inefficient as it creates various temporary Python objects, which are managed by the GIL, and performs various method calls (such as `range`) in Python, which are slow.

The `hpyhex-rs` package provides a Rust-backed implementation of `check_positions`, which performs all operations in Rust memory, avoiding the overhead of Python object management and method calls. In the entire expensive process of checking all possible positions, the GIL is only acquired once. The radius is not passed as a Python object, but as a direct integer in the Rust struct. The nested loops are performed in Rust, and `Hex` objects are created directly as structs without going through Python constructors. Further, instead of calling the `check_add` method, a special version of `check_add` that takes in raw Rust structs representing `Hex` and `Piece` is used, avoiding the overhead of interacting with Python objects at all. These optimizations mean the Rust-backed `check_positions` is more than **100 times** faster than the native Python implementation, as per [benchmarking](https://github.com/williamwutq/hpyhex-rs/tree/master/py/bench/bench.py) results.

### Don't Reinvent the Wheel
It is tempting to implement your own versions of the various abstractions provided by this package, such as `Game`, which intuitively is just a combination of `HexEngine` and a piece queue, and does not offer too much extra customization. Unless your purpose is different from the original intention of `hpyhex`, it is recommended to use the provided `Game` class directly, as it interacts with the optimized Rust versions of `HexEngine` and `PieceFactory` without the overhead of creating intermediate Python objects. For extra functionality, consider building on top of `Game` instead of re-implementing it completely.

### Not Enough for GUI Applications
If you are building a GUI application for a simple version of HappyHex and deeply hated the original Java codebase, you possibly have pondered upon this package for performance, as it advertises itself as a high-performance implementation of the Python `hpyhex` package, which has a simple and useful API. Unless you already did a lot of work in Python, however, you should not use Python for your GUI applications, as it is not well-suited for GUI development and may lead to performance issues and a poor user experience. The [hpyhex-rs](https://crates.io/crates/hpyhex-rs) Rust crate, which is inspired by the Python API, not only provides similar functionality and abstractions, which make your transition to that package easier, but also provides further abstractions such as thread-safe guards, extended HexEngine with potential attributes for each cell, and an integrated game environment designed specifically for GUI threading needs. Consider using Rust as your main programming language for GUI applications, or integrate with C++ via FFI to use existing C++ GUI frameworks.

## The Statistics

(See [bench directory](https://github.com/williamwutq/hpyhex-rs/tree/master/py/bench/) for full benchmarking code and results.)

All are tested on Apple M2 Pro with 16GB RAM, Python 3.11, Rust 1.92.0, macOS Sonoma 14.5.

### Speed Improvements

The Rust implementation of `hpyhex-rs` delivers dramatic performance improvements over the native Python `hpyhex` package. By leveraging Rust's zero-cost abstractions, efficient memory management, and ability to operate outside Python's Global Interpreter Lock (GIL), `hpyhex-rs` achieves speedups ranging from 2x to over 200x across different operations. These improvements are particularly significant for computationally intensive tasks like position checking, neighbor counting, and game simulations, making `hpyhex-rs` ideal for AI training, Monte Carlo simulations, and other performance-critical applications.

### Benchmark Comparison

The following table summarizes the performance improvements across major operation categories. All measurements represent typical use cases from each category, with speedup calculated as the ratio of Python execution time to Rust execution time.

| Category                | Representative Operation     | Python (µs) | Rust (µs) | Speedup    |
|-------------------------|------------------------------|-------------|-----------|------------|
| Hex Creation            | Cached hex creation          | 4.52        | 2.73      | 1.7x       |
| Hex Arithmetic          | Addition                     | 0.655       | 0.082     | 8.0x       |
| Hex Methods             | shift_i/j/k operations       | 0.272       | 0.068     | 4.0x       |
| Hex Collections         | Create set of hexes          | 108.01      | 58.41     | 1.8x       |
| Piece Creation          | From integer                 | 13.88       | 5.12      | 2.7x       |
| Piece Methods           | Count neighbors              | 3.37        | 0.077     | **43.8x**  |
| Piece Iteration         | Get contiguous pieces        | 47.65       | 0.990     | **48.1x**  |
| Mixed Operations        | Hex + Piece workflow         | 355.70      | 103.08    | 3.5x       |
| HexEngine Creation      | Radius 3 engine              | 0.195       | 0.131     | 1.5x       |
| HexEngine Coordinates   | index_block operation        | 0.412       | 0.087     | 4.7x       |
| HexEngine State         | get_state by hex             | 0.474       | 0.187     | 2.5x       |
| HexEngine Piece Ops     | check_positions (r=3)        | 73.69       | 0.459     | **160.5x** |
| HexEngine Neighbors     | count_neighbors              | 6.56        | 0.101     | **64.9x**  |
| HexEngine Eliminate     | eliminate (r=3, 1 line)      | 6.71        | 0.461     | 14.6x      |
| HexEngine Analysis      | compute_dense_index          | 32.63       | 0.214     | **152.5x** |
| HexEngine Serialization | From string                  | 3.44        | 0.462     | 7.4x       |
| HexEngine Collections   | Create set of engines        | 2.48        | 1.68      | 1.5x       |
| HexEngine Mixed         | AI evaluation                | 282.37      | 2.12      | **133.2x** |
| Random Creation         | Random engine (r=100)        | 11,980      | 302.38    | **39.6x**  |
| PieceFactory Lookup     | get_piece by name            | 0.206       | 0.133     | 1.5x       |
| PieceFactory Generation | Generate 100 pieces          | 54.15       | 10.57     | 5.1x       |
| PieceFactory Validation | get_piece (valid)            | 0.199       | 0.132     | 1.5x       |
| Game Creation           | Radius 3, queue 3            | 2.30        | 0.467     | 4.9x       |
| Game Properties         | Queue property access        | 0.074       | 0.237     | 0.3x*      |
| Game Add Piece          | Successful add               | 463.95      | 3.86      | **120.1x** |
| Game Make Move          | Random algorithm             | 451.23      | 4.40      | **102.6x** |
| Game Full Simulation    | 10 random moves              | 3,730       | 38.32     | **97.3x**  |
| Game Serialization      | __str__ method               | 75.25       | 6.10      | 12.3x      |
| Game Edge Cases         | Invalid index handling       | 0.306       | 0.191     | 1.6x       |
| Integration             | Create game + 5 moves        | 2,050       | 21.29     | **96.3x**  |

*Note: The queue property shows slower performance in Rust due to the overhead of converting Rust data structures to Python objects.*

### Highlights

Several operation categories demonstrate exceptional performance gains:

- **HexEngine check_positions** is **160x** faster. check_positions is a critical operation used by many heuristic algorithms and optimizers to gather valid piece placements. This speedup hugely benefits all downstream algorithms relying on position checking.
- **HexEngine compute_dense_index** is **152x** faster. A few critical algorithms, such as `nrsearch`, depends on Density Index computations. This speedup makes those algorithms significantly faster.
- **HexEngine AI evaluation** (checking and scoring positions) is **133x** faster. This is mainly due to the combined speedups in various critical HexEngine operations used to play the game.
- **Game add_piece** operation are **120x** faster. The core of the game is adding pieces to the engine, and this speedup directly translates to faster game simulations and AI training.
- **Game make_move** operations are **102x** faster, enabling rapid turn-based simulations.
- **Full game simulations** run **97x** faster, reducing a 3.7ms Python game to just 38µs in Rust. This benefits reinforcement learning, Monte Carlo Tree Search, test data generation, and other scenarios requiring many game simulations.
- **Piece count_neighbors** operations are **44x faster**.

These improvements are achieved through Rust's ability to perform raw arithmetic and bit operations in native code, combined with intelligent caching strategies that keep frequently-used data structures in Rust memory outside the GIL's control.

## NumPy Integration

`hpyhex-rs` provides NumPy integration for machine learning and development of fast game-playing heuristics agents. This is what makes `hpyhex-rs` stand out from the original `hpyhex` package, which does not provide any NumPy integration.

### Installation

The default pre-built wheels on PyPI include NumPy support. Simply install via pip:
```bash
pip install hpyhex-rs
```

Or if building from source, enable the `numpy` feature in your `Cargo.toml`.

### Experimental Features

Float16 (half precision) support is experimental and requires enabling the `half` feature flag during build. To use float16 serialization methods, ensure you have NumPy installed with float16 support, and compile the library from source with the `half` feature enabled:

```toml
[dependencies.hpyhex-rs]
version = "..."
features = ["numpy", "half"]
```

Note that the feature is experimental and not officially supported nor tested extensively. On machines that does not support float16 or installed with a version of numpy that does not support float16, this function may lead to undefined behavior or crashes. Those unintended behaviors could be subtle and hard to debug, so even if code with this feature seems to work, make sure to check the output as it has known to misintepret memory or lead to silent data corruption in some cases.

### Examples

See the [examples directory](https://github.com/williamwutq/hpyhex-rs/tree/master/py/examples/) for complete example scripts demonstrating NumPy integration. These examples cover converting `HexEngine` and `Piece` objects to and from NumPy arrays, serializing game states, and integrating with machine learning workflows. The demonstrations include both basic usage and advanced scenarios. The example framework is PyTorch for machine learning, but the NumPy integration is framework-agnostic and can be used with any library that supports NumPy arrays (which are most of them).

### No Serialization for Hex

Hex has no need for serialization to numpy arrays, as it is just a coordinate container. Batch serialization of hex coordinates are needed, but an array of hexagonal coordinates only has meaning in the context of a grid, which is either a HexEngine or a Piece. Therefore, serialization from and to NumPy is only implemented for HexEngine or a Piece, but not Hex.

### Serialization for Piece

The `Piece` class provides efficient conversion to and from NumPy arrays representing its 7 block states. All conversions produce or consume 1-dimensional arrays of shape `(7,)`, where each element represents whether the corresponding block is occupied.

#### Converting to NumPy

The `to_numpy()` method returns a boolean array by default:
```python
from hpyhex import PieceFactory
import numpy as np

piece = PieceFactory.get_piece("triangle_3_a")

# Default: boolean array
arr = piece.to_numpy()
# arr.dtype == np.bool_
# arr.shape == (7,)
# arr = [True, True, False, True, False, False, False]
```

For specific numeric types, use the typed conversion methods:
```python
# Integer types
arr_i8 = piece.to_numpy_int8()      # dtype: int8
arr_u8 = piece.to_numpy_uint8()     # dtype: uint8
arr_i16 = piece.to_numpy_int16()    # dtype: int16
arr_u16 = piece.to_numpy_uint16()   # dtype: uint16
arr_i32 = piece.to_numpy_int32()    # dtype: int32
arr_u32 = piece.to_numpy_uint32()   # dtype: uint32
arr_i64 = piece.to_numpy_int64()    # dtype: int64
arr_u64 = piece.to_numpy_uint64()   # dtype: uint64

# Floating point types
arr_f32 = piece.to_numpy_float32()  # dtype: float32
arr_f64 = piece.to_numpy_float64()  # dtype: float64

# Half precision (requires "half" feature, experimental)
arr_f16 = piece.to_numpy_half()     # dtype: float16
```

#### Converting from NumPy

Use the corresponding `from_numpy_*` methods to construct a Piece from a NumPy array. The array must have shape `(7,)` and the appropriate dtype. For unsigned integer types, non-zero values are treated as occupied blocks, for signed integers and floating point types, positive values are treated as occupied blocks and zero or negative values as empty blocks. This design aims to make conversion from a softmax output of a neural network straightforward.
```python
# From boolean array
arr = np.array([True, True, True, False, False, False, False])
piece = Piece.from_numpy_bool(arr)

# From integer arrays
arr_u8 = np.array([1, 1, 1, 0, 0, 0, 0], dtype=np.uint8)
piece = Piece.from_numpy_uint8(arr_u8)

arr_i32 = np.array([1, 1, 1, 0, 0, 0, 0], dtype=np.int32)
piece = Piece.from_numpy_int32(arr_i32)

# From floating point arrays
arr_f64 = np.array([1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 0.0])
piece = Piece.from_numpy_float64(arr_f64)
```

#### Validation and Error Handling

All `from_numpy_*` methods validate the input array:

- **Shape validation**: Array must have exactly shape `(7,)` 
- **Type validation**: Array dtype must match the method's expected type

If validation fails, a `ValueError` is raised:
```python
# Wrong shape
arr = np.array([1, 1, 1, 0, 0])  # Only 5 elements
try:
    piece = Piece.from_numpy_uint8(arr)
except ValueError as e:
    print(f"Error: {e}")  # Shape mismatch
# Wrong dtype
arr = np.array([1, 1, 1, 0, 0, 0, 0], dtype=np.float32)
try:
    piece = Piece.from_numpy_uint8(arr)
except ValueError as e:
    print(f"Error: {e}")  # Dtype mismatch
```

#### Type Casting Considerations

NumPy arrays cannot be easily cast between types at the Rust/Python boundary. Therefore, **there is no universal `from_numpy()` method**. You must use the specific typed method that matches your array's dtype:
```python
# No automatic type detection
arr = np.array([1, 1, 1, 0, 0, 0, 0], dtype=np.int32)
# piece = Piece.from_numpy(arr)  # This method doesn't exist!

# Use the typed method matching your dtype
piece = Piece.from_numpy_int32(arr)

# If you need to convert between types, do it in NumPy first:
arr_f32 = arr.astype(np.float32) # Note that Numpy does a copy here
piece = Piece.from_numpy_float32(arr_f32)
```

#### Zero Copy

There is no need for zero-copy conversion between NumPy arrays and `Piece` objects, as the data size is only 7 bytes. In addition, since Pieces are optimized with a fixed cache of pre-defined objects, they are already "zero-copy" in a sense that no new memory allocation is needed when creating a Piece from its byte representation. Therefore, all conversions involve "copying" data between the NumPy array and the Piece object.

#### Supported Data Types

The following table summarizes all supported NumPy dtypes for Piece serialization:

| NumPy dtype | `to_numpy_*` method     | `from_numpy_*` method    | Notes                                  |
|-------------|-------------------------|--------------------------|----------------------------------------|
| `bool_`     | `to_numpy()` (default)  | `from_numpy_bool()`      | Most memory efficient                  |
| `int8`      | `to_numpy_int8()`       | `from_numpy_int8()`      | Signed 8-bit integer                   |
| `uint8`     | `to_numpy_uint8()`      | `from_numpy_uint8()`     | Unsigned 8-bit integer                 |
| `int16`     | `to_numpy_int16()`      | `from_numpy_int16()`     | Signed 16-bit integer                  |
| `uint16`    | `to_numpy_uint16()`     | `from_numpy_uint16()`    | Unsigned 16-bit integer                |
| `int32`     | `to_numpy_int32()`      | `from_numpy_int32()`     | Signed 32-bit integer                  |
| `uint32`    | `to_numpy_uint32()`     | `from_numpy_uint32()`    | Unsigned 32-bit integer                |
| `int64`     | `to_numpy_int64()`      | `from_numpy_int64()`     | Signed 64-bit integer                  |
| `uint64`    | `to_numpy_uint64()`     | `from_numpy_uint64()`    | Unsigned 64-bit integer                |
| `float16`   | `to_numpy_half()`       | `from_numpy_half()`      | Requires "half" feature (experimental) |
| `float32`   | `to_numpy_float32()`    | `from_numpy_float32()`   | Common for ML applications             |
| `float64`   | `to_numpy_float64()`    | `from_numpy_float64()`   | Double precision                       |

**Recommended types:**
- Use `bool_` for minimal memory footprint or in machine learning
- Use `uint8` for serialization to compact integer formats
- Use `float32` for general machine learning (PyTorch, TensorFlow default)

### Serialization for Vector of Piece (Piece Queues)

The `Piece` class provides efficient conversion to and from NumPy arrays for collections of pieces, commonly used for piece queues in game states. All conversions work with lists of `Piece` objects.

#### Converting to NumPy

The `vec_to_numpy_flat()` method returns a flattened 1D boolean array by default, concatenating all pieces' block states:
```python
from hpyhex import PieceFactory
import numpy as np

pieces = [
   PieceFactory.get_piece("triangle_3_a"),
   PieceFactory.get_piece("triangle_3_b"),
   PieceFactory.get_piece("corner_3_a")
]

# Default: flattened boolean array
arr = Piece.vec_to_numpy_flat(pieces)
# arr.dtype == np.bool_
# arr.shape == (21,)  # 3 pieces * 7 blocks each
```

For stacked representation, use `vec_to_numpy_stacked()` which returns a 2D array:
```python
# Stacked: 2D boolean array
arr_2d = Piece.vec_to_numpy_stacked(pieces)
# arr_2d.dtype == np.bool_
# arr_2d.shape == (3, 7)  # (num_pieces, 7)
# arr_3d.stride == (8, 1)  # row-major order, padded for alignment
```

For specific numeric types, use the typed conversion methods:
```python
# Integer types (flat)
arr_i8_flat = Piece.vec_to_numpy_int8_flat(pieces)      # dtype: int8
arr_u8_flat = Piece.vec_to_numpy_uint8_flat(pieces)     # dtype: uint8
arr_i16_flat = Piece.vec_to_numpy_int16_flat(pieces)    # dtype: int16
arr_u16_flat = Piece.vec_to_numpy_uint16_flat(pieces)   # dtype: int16
arr_i32_flat = Piece.vec_to_numpy_int32_flat(pieces)    # dtype: int32
arr_u32_flat = Piece.vec_to_numpy_uint32_flat(pieces)   # dtype: uint32
arr_i64_flat = Piece.vec_to_numpy_int6