lczerolens.search#

Search utilities.

Classes#

`Heuristic`	Heuristic protocol for evaluating chess positions.
`RandomHeuristic`	Simple heuristic for MCTS.
`MaterialHeuristic`	Heuristic that outputs uniform policy and material advantage as value.
`ModelHeuristic`	Evaluate boards using a neural network model for MCTS.
`Node`	Node for MCTS using LczeroBoard.
`MCTS`	Monte Carlo Tree Search with PUCT formula.

Module Contents#

class lczerolens.search.Heuristic[source]#

Bases: Protocol

Heuristic protocol for evaluating chess positions.

evaluate(board)[source]#

Evaluate a single board.

Parameters:: board (LczeroBoard) – LczeroBoard instance representing the current board state
Returns:: Dictionary with fields value and policy.
Return type:: TensorDict

class lczerolens.search.RandomHeuristic[source]#

Simple heuristic for MCTS.

evaluate(board)[source]#

Evaluate a single board.

Parameters:: board (LczeroBoard) – LczeroBoard instance
Returns:: Dictionary with fields value and policy.
Return type:: TensorDict

class lczerolens.search.MaterialHeuristic(piece_values=None, normalization_constant=0.1, activation=torch.tanh)[source]#

Heuristic that outputs uniform policy and material advantage as value.

Parameters:

piece_values (Optional[Dict[int, int]])
normalization_constant (float)
activation (Callable[[torch.Tensor], torch.Tensor])

default_piece_values[source]#

piece_values[source]#

normalization_constant = 0.1[source]#

activation[source]#

evaluate(board)[source]#

Compute the label for a given model and input.

Parameters:: board (lczerolens.board.LczeroBoard)
Return type:: tensordict.TensorDict

class lczerolens.search.ModelHeuristic(model)[source]#

Evaluate boards using a neural network model for MCTS.

Parameters:: model (lczerolens.model.LczeroModel)

_model[source]#

evaluate(board)[source]#

Evaluate a single board using the Lczero model.

Returns TensorDict with ‘value’ and ‘policy’.

Parameters:: board (lczerolens.board.LczeroBoard)
Return type:: tensordict.TensorDict

class lczerolens.search.Node(board, parent)[source]#

Node for MCTS using LczeroBoard.

Parameters:

board (lczerolens.board.LczeroBoard)
parent (Node)

board[source]#

parent[source]#

is_terminal: bool[source]#

children: Dict[chess.Move, Node][source]#

legal_moves: Tuple[chess.Move, Ellipsis][source]#

visits: torch.Tensor[source]#

q_values: torch.Tensor[source]#

_value: torch.Tensor | None = None[source]#

_policy: torch.Tensor | None = None[source]#

_initialized: bool = False[source]#

property value[source]#

property policy[source]#

property initialized[source]#

set_evaluation(td)[source]#

Set the evaluation for the node.

Parameters:: td (TensorDict) – TensorDict containing value and policy tensors.
Return type:: None

class lczerolens.search.MCTS(c_puct=1.0, n_parallel_rollouts=1)[source]#

Monte Carlo Tree Search with PUCT formula.

Parameters:

c_puct (float)
n_parallel_rollouts (int)

c_puct = 1.0[source]#

n_parallel_rollouts = 1[source]#

search_(root, heuristic, iterations=10)[source]#

Perform MCTS search on the given root node.

Parameters:

root (Node) – Node instance representing the current board state.
heuristic (Heuristic) – Heuristic instance to evaluate board states.
iterations (int) – Number of iterations to run the MCTS search.

Return type:

None

_select_(node)[source]#

Select the move to explore based on the PUCT formula.

Parameters:: node (Node)
Return type:: chess.Move

_evaluate_(node, heuristic)[source]#

Evaluate a single board.

Parameters:

node (Node) – Node instance representing the current board state.
heuristic (Heuristic) – Heuristic instance to evaluate board states.

Returns:

value – Value tensor for the current node.

Return type:

torch.Tensor

_backpropagate_(node, value)[source]#

Backpropagate the reward from the leaf node to the root node.

Parameters:

node (Node) – Node instance representing the leaf node.
value (float) – Float value to backpropagate.

Return type:

None

render_tree(max_depth=3, save_to=None, min_visit_percentage=0.0)[source]#

Render the MCTS tree as an SVG.

Parameters:

root (Node) – Root node of the tree.
max_depth (int, default=3) – Maximum depth to render.
save_to (Optional[str], default=None) – Path to save the SVG. If None, returns the SVG string.
min_visit_percentage (float)

Returns:

SVG string of the tree, or None if saved to file.

Return type:

Optional[str]