lczerolens.data#

Data classes for chess game, board, and puzzle.

Attributes#

MISSING_DATASETS_ERROR

Classes#

`GameData`	Data class representing a chess game with moves and metadata.
`BoardData`	Data class representing a single chess board position with metadata.
`PuzzleData`	Data class representing a chess puzzle with solution and metadata.

Functions#

`columns_to_rows`(columns)	Convert a dictionary of columns to a list of dictionaries.
`rows_to_columns`(rows)	Convert a list of dictionaries to a dictionary of columns.

Module Contents#

lczerolens.data.MISSING_DATASETS_ERROR = 'datasets is required to get the dataset features. Install it with `pip install lczerolens[hf]`...[source]#

lczerolens.data.columns_to_rows(columns)[source]#

Convert a dictionary of columns to a list of dictionaries.

Parameters:: columns (Dict[str, List[Any]]) – Dictionary containing columns of data.
Returns:: List of dictionaries, where each dictionary contains the values from one row.
Return type:: List[Dict[str, Any]]

lczerolens.data.rows_to_columns(rows)[source]#

Convert a list of dictionaries to a dictionary of columns.

Parameters:: rows (List[Dict[str, Any]]) – List of dictionaries, where each dictionary contains the values from one row.
Returns:: Dictionary containing columns of data.
Return type:: Dict[str, List[Any]]

class lczerolens.data.GameData[source]#

Data class representing a chess game with moves and metadata.

gameid[source]#

Unique identifier for the game.

Type:: str

moves[source]#

List of moves in the game in standard algebraic notation.

Type:: List[str]

book_exit[source]#

Move number where the game exits book theory, if applicable.

Type:: Optional[int]

gameid: str[source]#

moves: List[str][source]#

book_exit: int | None = None[source]#

classmethod from_dict(obj)[source]#

Create a GameData instance from a dictionary.

Parameters:: obj (Dict[str, str]) – Dictionary containing game data with ‘gameid’ and ‘moves’ keys. The ‘moves’ value should contain moves separated by spaces, with “{ Book exit }” marking the book exit point.
Returns:: A new GameData instance.
Return type:: GameData
Raises:: ValueError – If required keys are missing or if there are multiple book exit markers.

to_boards(n_history=0, skip_book_exit=False, skip_first_n=0, output_dict=True, concept=None)[source]#

Convert the game to a list of board positions.

Parameters:

n_history (int, default=0) – Number of previous moves to include in the board’s move stack.
skip_book_exit (bool, default=False) – Whether to skip positions before book exit.
skip_first_n (int, default=0) – Number of initial positions to skip.
output_dict (bool, default=True) – If True, return dictionaries with board information. If False, return LczeroBoard objects directly.
concept (Optional[Concept], default=None) – Concept to compute labels for each board position.

Returns:

List of board representations, either as dictionaries or LczeroBoard objects.

Return type:

List[Union[Dict[str, Any], LczeroBoard]]

static collate_fn(batch)[source]#

Collate function for batching GameData objects.

Parameters:: batch (List[Dict[str, str]]) – List of dictionaries containing game data.
Returns:: List of GameData instances.
Return type:: List[GameData]

static get_dataset_features()[source]#

Returns the features for the game dataset.

Returns:: Dataset features configuration for the HuggingFace datasets library.
Return type:: Features
Raises:: ImportError – If the datasets library is not available.

class lczerolens.data.BoardData[source]#

Data class representing a single chess board position with metadata.

gameid[source]#

Unique identifier for the game this board belongs to.

Type:: str

moves[source]#

List of moves that led to this board position.

Type:: List[str]

fen[source]#

FEN string representation of the board position.

Type:: str

label[source]#

Optional label for the board position (e.g., concept-based label).

Type:: Optional[Any]

gameid: str[source]#

moves: List[str][source]#

fen: str[source]#

label: Any | None = None[source]#

static get_dataset_features(concept=None)[source]#

Returns the features for the board dataset.

Parameters:: concept (Optional[Concept], default=None) – Concept to determine the label feature type.
Returns:: Dataset features configuration for the HuggingFace datasets library.
Return type:: Features
Raises:: ImportError – If the datasets library is not available.

static board_collate_fn(batch)[source]#

Collate function for creating LczeroBoard objects from batch data.

Parameters:: batch (List[Dict[str, Any]]) – List of dictionaries containing board data with ‘fen’ and ‘moves’ keys.
Returns:: List of LczeroBoard instances.
Return type:: List[LczeroBoard]

static concept_collate_fn(batch, concept=None)[source]#

Collate function for concept-based analysis with labels.

Parameters:

batch (List[Dict[str, Any]]) – List of dictionaries containing board data and labels.
concept (Optional[Concept], default=None) – Concept to determine the label feature type.

Returns:

Tuple containing boards, labels, and original batch data.

Return type:

Tuple[List[LczeroBoard], List[Any], List[Dict[str, Any]]]

static concept_init_grad(output, infos)[source]#

Initialize gradients for concept-based analysis.

Parameters:

output (torch.Tensor) – Model output tensor.
infos (Tuple) – Tuple containing labels and other information.

Returns:

Gradient tensor initialized for concept analysis.

Return type:

torch.Tensor

class lczerolens.data.PuzzleData[source]#

Data class representing a chess puzzle with solution and metadata.

puzzle_id[source]#

Unique identifier for the puzzle.

Type:: str

fen[source]#

FEN string representation of the puzzle’s starting position.

Type:: str

initial_move[source]#

The first move that must be played to solve the puzzle.

Type:: chess.Move

moves[source]#

List of moves in the solution sequence.

Type:: List[chess.Move]

rating[source]#

Puzzle rating indicating difficulty.

Type:: int

rating_deviation[source]#

Statistical deviation of the rating.

Type:: int

popularity[source]#

Popularity score of the puzzle.

Type:: int

nb_plays[source]#

Number of times the puzzle has been played.

Type:: int

themes[source]#

List of chess themes/tactics present in the puzzle.

Type:: List[str]

game_url[source]#

URL to the original game where the puzzle occurred.

Type:: str

opening_tags[source]#

List of opening tags associated with the puzzle.

Type:: List[str]

puzzle_id: str[source]#

fen: str[source]#

initial_move: chess.Move[source]#

moves: List[chess.Move][source]#

rating: int[source]#

rating_deviation: int[source]#

popularity: int[source]#

nb_plays: int[source]#

themes: List[str][source]#

game_url: str[source]#

opening_tags: List[str][source]#

classmethod from_dict(obj)[source]#

Create a PuzzleData instance from a dictionary.

Parameters:: obj (Dict[str, Union[str, int, None]]) – Dictionary containing puzzle data with keys matching the class attributes. ‘Moves’ should be a space-separated string of UCI moves. ‘Themes’ and ‘OpeningTags’ should be space-separated strings.
Returns:: A new PuzzleData instance.
Return type:: PuzzleData

__len__()[source]#

Return the number of moves in the puzzle solution.

Returns:: Number of moves in the solution sequence.
Return type:: int

property initial_board: lczerolens.board.LczeroBoard[source]#

Get the board position after the initial move is played.

Returns:: Board position after the initial move.
Return type:: LczeroBoard

board_move_generator(all_moves=False)[source]#

Generate board positions and moves for the puzzle solution.

Parameters:: all_moves (bool, default=False) – If True, yield all moves. If False, only yield moves for the initial player’s turn.
Yields:: Tuple[LczeroBoard, chess.Move] – Board position and the move to be played.
Return type:: Iterable[Tuple[lczerolens.board.LczeroBoard, chess.Move]]

classmethod evaluate_multiple(puzzles, sampler, all_moves=False, compute_metrics=True, **kwargs)[source]#

Evaluate multiple puzzles using a sampler.

Parameters:

puzzles (Iterable[PuzzleData]) – Collection of puzzles to evaluate.
sampler (Sampler) – Sampler to use for move prediction and evaluation.
all_moves (bool, default=False) – Whether to evaluate all moves or only initial player moves.
compute_metrics (bool, default=True) – Whether to compute and return metrics or raw evaluation data.
**kwargs – Additional arguments to pass to the sampler.

Returns:

Either metrics for each puzzle or raw evaluation data.

Return type:

Union[Iterable[Dict[str, float]], Iterable[Tuple[torch.Tensor, torch.Tensor, chess.Move]]]

evaluate(sampler, all_moves=False, **kwargs)[source]#

Evaluate this single puzzle using a sampler.

Parameters:

sampler (Sampler) – Sampler to use for move prediction and evaluation.
all_moves (bool, default=False) – Whether to evaluate all moves or only initial player moves.
**kwargs – Additional arguments to pass to the sampler.

Returns:

Dictionary containing score, perplexity, and normalized_perplexity metrics.

Return type:

Dict[str, float]

static compute_metrics(puzzles, inputs, all_moves=False)[source]#

Compute evaluation metrics for a collection of puzzles.

Parameters:

puzzles (Iterable[PuzzleData]) – Collection of puzzles to evaluate.
inputs (Iterable[Tuple[torch.Tensor, torch.Tensor, chess.Move]]) – Iterator providing utility tensors, legal indices, and predicted moves.
all_moves (bool, default=False) – Whether all moves were evaluated or only initial player moves.

Yields:

Dict[str, float] – Dictionary containing score, perplexity, and normalized perplexity metrics.

Return type:

Iterable[Dict[str, float]]

_repr_svg_()[source]#

Return SVG representation of the puzzle’s initial board.

Returns:: SVG string representation of the board.
Return type:: str

static get_dataset_features()[source]#

Returns the features for the puzzle dataset.

Returns:: Dataset features configuration for the HuggingFace datasets library.
Return type:: Features
Raises:: ImportError – If the datasets library is not available.