xmaster6y/lczerolens

🔬 Interpretability for Leela Chess Zero networks.

lczerolens 🔍

Leela Chess Zero (lc0) Lens: a set of utilities to make the analysis of Leela Chess Zero networks easy.

Getting Started

Installs

pip install lczerolens

Load a Model

Build a model from leela file (convert then load):

from lczerolens import AutoBuilder

model = AutoBuilder.from_path(
    "leela-network.onnx"
)

Predict a Move

Use a wrapper and the utils to predict a policy vector and obtain an UCI move:

import chess
import torch

from lczerolens import move_utils, ModelWrapper

# Wrap the model
wrapper = ModelWrapper(model)
board = chess.Board()

# Get the model predictions
out = wrapper.predict(board)
policy = out["policy"]

# Use the prediction
best_move_index = policy.argmax()
move = move_utils.decode_move(best_move_index)
board.push(move)

print(uci_move, board)

Compute a Heatmap

Use a lens to compute a heatmap

from lczerolens import visualisation_utils, LrpLens

# Get the lens
lens = LrpLens()

# Compute the relevance
assert lens.is_compatible(wrapper)
relevance = lens.compute_heatmap(board, wrapper)

# Choose a plane index and render the heatmap on the board
plane_index = 0
heatmap = relevance_tensor[plane_index].view(64)
if board.turn == chess.BLACK:
    heatmap = heatmap.view(8, 8).flip(0).view(64)
svg_board, fig = visualisation_utils.render_heatmap(
    board, heatmap, normalise="abs"
)

Convert a Network

To convert a network you'll need to have installed the lc0 extra:

pip install lczerolens[lc0]

from lczerolens import lczero as lczero_utils

lczero_utils.convert_to_onnx(
    "leela-network.pb.gz",
    "leela-network.onnx"
)

Demo

Additionally, you can run the gradio demo locally (also deployed on HF). First you'll need gradio, which is packaged in the demo extra:

pip install lczerolens[demo]

And then launch the demo (running on port 8000):

make demo

Full Documentation

🔴 Documentation coming soon.

Contribute

See the guidelines in CONTRIBUTING.md.

lczerolens's Issues

Update Demo & Docs

Description

With the new API changes, the demo and the documentation need to be updated.

Acceptance Criterion

• The code is documented
• Utilities and class test are written
• The code was reviewed

Tasks

• #20
• #21
• #22
• #19

Setup Docs

Description

Setup documentation using sphinx.

Tasks

• Presentation and logo
• WIP pages
• Basic features
• Deploy pipeline

Rewrite dataset analysis with generator

Description

More memory friendly.

Acceptance Criterion

• The code is documented
• Utilities and class test are written
• The code was reviewed

Tasks

• Change the code to make dataset lense iterators

Batching label prediction

Description

Batch the label prediction.

Acceptance Criterion

• The code is documented
• Utilities and class tests are written
• The code was reviewed

Tasks

• Compute labels per batch option
• Make the concept dataset batch labelise
• Optionally make it on device if available

Update the documentation

Add notebooks in docs

Check dependencies

Update the demo