lczerolens 🔍

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

Getting Started

Installs

pip install lczerolens

Take the viz extra to render heatmaps and the backends extra to use the lc0 backends.

Run Models

Get the best move predicted by a model:

from lczerolens import LczeroBoard, LczeroModel

model = LczeroModel.from_onnx_path("demo/onnx-models/lc0-10-4238.onnx")
board = LczeroBoard()
output = model(board)
legal_indices = board.get_legal_indices()
best_move_idx = output["policy"].gather(
    dim=1,
    index=legal_indices.unsqueeze(0)
).argmax(dim=1).item()
print(board.decode_move(legal_indices[best_move_idx]))

Intervene

In addition to the built-in lenses, you can easily create your own lenses by subclassing the Lens class and overriding the _intervene method. E.g. compute an neuron ablation effect:

from lczerolens import LczeroBoard, LczeroModel, Lens

class CustomLens(Lens):
    _grad_enabled: bool = False

    def _intervene(self, model: LczeroModel, **kwargs) -> dict:
        ablate = kwargs.get("ablate", False)
        if ablate:
            l5_module = getattr(model, "block5/conv2/relu")
            l5_module.output[0, :, 0, 0] = 0 # relative a1
        return getattr(model, "output/wdl").output[0,0].save() # win probability

model = LczeroModel.from_onnx_path("path/to/model.onnx")
lens = CustomLens()
board = LczeroBoard()

clean_results = lens.analyse(model, board)
corrupted_results = lens.analyse(model, board, ablate=True)
print((corrupted_results - clean_results) / clean_results)

Features

• Visualise Heatmaps:
• Probe Concepts:
• Move Prediction:
• Run Models on GPU:
• Evaluate Models on Puzzles:
• Convert Official Weights:

Tutorials

• Walkthrough:
• Piece Value Estimation Using LRP:
• Evidence of Learned Look-Ahead:
• Train SAEs:

Demo

Spaces

• Lczerolens Demo
• Lczerolens Backends Demo
• Lczerolens Puzzles Leaderboard

Local Demo

Additionally, you can run the gradio demos locally. First you'll need to clone the spaces (after cloning the repo):

git clone https://huggingface.co/spaces/Xmaster6y/lczerolens-demo spaces/lczerolens-demo

And optionally the backends demo:

git clone https://huggingface.co/spaces/Xmaster6y/lczerolens-backends-demo spaces/lczerolens-backends-demo

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

make demo

To test the backends use:

make demo-backends

Full Documentation

See the full documentation.

Contribute

See the guidelines in CONTRIBUTING.md.