{"id":13513592,"url":"https://github.com/leela-zero/leela-zero","last_synced_at":"2025-05-14T06:11:55.933Z","repository":{"id":37484461,"uuid":"108166281","full_name":"leela-zero/leela-zero","owner":"leela-zero","description":"Go engine with no human-provided knowledge, modeled after the AlphaGo Zero paper.","archived":false,"fork":false,"pushed_at":"2024-05-02T18:00:51.000Z","size":3802,"stargazers_count":5455,"open_issues_count":373,"forks_count":1014,"subscribers_count":288,"default_branch":"next","last_synced_at":"2025-04-11T02:51:24.587Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leela-zero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-24T18:19:43.000Z","updated_at":"2025-04-11T02:23:09.000Z","dependencies_parsed_at":"2024-06-19T02:56:08.601Z","dependency_job_id":"186113a6-cce4-4d3b-ba77-049953e80825","html_url":"https://github.com/leela-zero/leela-zero","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leela-zero%2Fleela-zero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leela-zero%2Fleela-zero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leela-zero%2Fleela-zero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leela-zero%2Fleela-zero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leela-zero","download_url":"https://codeload.github.com/leela-zero/leela-zero/tar.gz/refs/heads/next","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254080047,"owners_count":22011310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T05:00:32.270Z","updated_at":"2025-05-14T06:11:55.885Z","avatar_url":"https://github.com/leela-zero.png","language":"C++","funding_links":[],"categories":["Sensor Processing","C++","C++ (70)"],"sub_categories":["Machine Learning"],"readme":"[![Linux Build Status](https://travis-ci.org/leela-zero/leela-zero.svg?branch=next)](https://travis-ci.org/leela-zero/leela-zero)\n[![Windows Build Status](https://ci.appveyor.com/api/projects/status/dcvp31x1e0yavrtf/branch/next?svg=true)](https://ci.appveyor.com/project/gcp/leela-zero-8arv1/branch/next)\n\n# What\n\nA Go program with no human provided knowledge. Using MCTS (but without\nMonte Carlo playouts) and a deep residual convolutional neural network stack.\n\nThis is a fairly faithful reimplementation of the system described\nin the Alpha Go Zero paper \"[Mastering the Game of Go without Human Knowledge](https://www.nature.com/articles/nature24270.epdf?author_access_token=VJXbVjaSHxFoctQQ4p2k4tRgN0jAjWel9jnR3ZoTv0PVW4gB86EEpGqTRDtpIz-2rmo8-KG06gqVobU5NSCFeHILHcVFUeMsbvwS-lxjqQGg98faovwjxeTUgZAUMnRQ)\".\nFor all intents and purposes, it is an open source AlphaGo Zero.\n\n# Wait, what?\n\nIf you are wondering what the catch is: you still need the network weights.\nNo network weights are in this repository. If you manage to obtain the\nAlphaGo Zero weights, this program will be about as strong, provided you\nalso obtain a few Tensor Processing Units. Lacking those TPUs, I'd recommend\na top of the line GPU - it's not exactly the same, but the result would still\nbe an engine that is far stronger than the top humans.\n\n# Gimme the weights\n\nRecomputing the AlphaGo Zero weights will [take about 1700 years on commodity hardware](http://web.archive.org/web/20190205013627/http://computer-go.org/pipermail/computer-go/2017-October/010307.html).\n\nOne reason for publishing this program is that we are running a public,\ndistributed effort to repeat the work. Working together, and especially\nwhen starting on a smaller scale, it will take less than 1700 years to get\na good network (which you can feed into this program, suddenly making it strong).\n\n# I want to help\n\n## Using your own hardware\n\nYou need a PC with a GPU, i.e. a discrete graphics card made by NVIDIA or AMD,\npreferably not too old, and with the most recent drivers installed.\n\nIt is possible to run the program without a GPU, but performance will be much\nlower. If your CPU is not *very* recent (Haswell or newer, Ryzen or newer),\nperformance will be outright bad, and it's probably of no use trying to join\nthe distributed effort. But you can still play, especially if you are patient.\n\n### Windows\n\nHead to the Github releases page at https://github.com/leela-zero/leela-zero/releases,\ndownload the latest release, unzip, and launch autogtp.exe. It will connect to\nthe server automatically and do its work in the background, uploading results\nafter each game. You can just close the autogtp window to stop it.\n\n### macOS and Linux\n\nFollow the instructions below to compile the leelaz and autogtp binaries in\nthe build subdirectory. Then run autogtp as explained in the\n[contributing](#contributing) instructions below.\nContributing will start when you run autogtp.\n\n## Using a Cloud provider\n\nMany cloud companies offer free trials (or paid solutions, not discussed here)\nthat are usable for helping the leela-zero project.\n\nThere are community maintained instructions available here:\n* [Running Leela Zero client on a Tesla V100 GPU for free (Google Cloud Free Trial)](https://docs.google.com/document/d/1P_c-RbeLKjv1umc4rMEgvIVrUUZSeY0WAtYHjaxjD64/edit?usp=sharing)\n\n* [Running Leela Zero client on a Tesla V100 GPU for free (Microsoft Azure Cloud Free Trial)](https://docs.google.com/document/d/1DMpi16Aq9yXXvGj0OOw7jbd7k2A9LHDUDxxWPNHIRPQ/edit?usp=sharing)\n\n# I just want to play with Leela Zero right now\n\nDownload the best known network weights file from [here](https://zero.sjeng.org/best-network), or, if you prefer a more human style,\na (weaker) network trained from human games [here](https://sjeng.org/zero/best_v1.txt.zip).\n\nIf you are on Windows, download an official release from [here](https://github.com/leela-zero/leela-zero/releases) and head to the [Usage](#usage-for-playing-or-analyzing-games)\nsection of this README.\n\nIf you are on macOS, Leela Zero is available through [Homebrew](https://homebrew.sh), the de facto standard\npackage manager. You can install it with:\n```\nbrew install leela-zero\n```\n\nIf you are on Unix, you have to compile the program yourself. Follow\nthe compilation instructions below and then read the [Usage](#usage-for-playing-or-analyzing-games) section.\n\n# Compiling AutoGTP and/or Leela Zero\n\n## Requirements\n\n* GCC, Clang or MSVC, any C++14 compiler\n* Boost 1.58.x or later, headers and program_options, filesystem and system libraries (libboost-dev, libboost-program-options-dev and libboost-filesystem-dev on Debian/Ubuntu)\n* zlib library (zlib1g \u0026 zlib1g-dev on Debian/Ubuntu)\n* Standard OpenCL C headers (opencl-headers on Debian/Ubuntu, or at\nhttps://github.com/KhronosGroup/OpenCL-Headers/tree/master/CL)\n* OpenCL ICD loader (ocl-icd-libopencl1 on Debian/Ubuntu, or reference implementation at https://github.com/KhronosGroup/OpenCL-ICD-Loader)\n* An OpenCL capable device, preferably a very, very fast GPU, with recent\ndrivers is strongly recommended (OpenCL 1.1 support is enough). Don't\nforget to install the OpenCL driver if this part is packaged seperately\nby the Linux distribution (e.g. nvidia-opencl-icd).\nIf you do not have a GPU, add the define \"USE_CPU_ONLY\", for example\nby adding -DUSE_CPU_ONLY=1 to the cmake command line.\n* Optional: BLAS Library: OpenBLAS (libopenblas-dev) or Intel MKL\n* The program has been tested on Windows, Linux and macOS.\n\n## Example of compiling - Ubuntu \u0026 similar\n\n    # Test for OpenCL support \u0026 compatibility\n    sudo apt install clinfo \u0026\u0026 clinfo\n\n    # Clone github repo\n    git clone https://github.com/leela-zero/leela-zero\n    cd leela-zero\n    git submodule update --init --recursive\n\n    # Install build depedencies\n    sudo apt install cmake g++ libboost-dev libboost-program-options-dev libboost-filesystem-dev opencl-headers ocl-icd-libopencl1 ocl-icd-opencl-dev zlib1g-dev\n\n    # Use a stand alone build directory to keep source dir clean\n    mkdir build \u0026\u0026 cd build\n\n    # Compile leelaz and autogtp in build subdirectory with cmake\n    cmake ..\n    cmake --build .\n\n    # Optional: test if your build works correctly\n    ./tests\n\n## Example of compiling - macOS\n\n    # Clone github repo\n    git clone https://github.com/leela-zero/leela-zero\n    cd leela-zero\n    git submodule update --init --recursive\n\n    # Install build depedencies\n    brew install boost cmake zlib\n\n    # Use a stand alone build directory to keep source dir clean\n    mkdir build \u0026\u0026 cd build\n\n    # Compile leelaz and autogtp in build subdirectory with cmake\n    cmake ..\n    cmake --build .\n\n    # Optional: test if your build works correctly\n    ./tests\n\n## Example of compiling - Windows\n\n    # Clone github repo\n    git clone https://github.com/leela-zero/leela-zero\n    cd leela-zero\n    git submodule update --init --recursive\n\n    cd msvc\n    Double-click the leela-zero2015.sln or leela-zero2017.sln corresponding\n    to the Visual Studio version you have.\n    # Build from Visual Studio 2015 or 2017\n\n# Contributing\n\nFor Windows, you can use a release package, see [\"I want to help\"](#windows).\n\nUnix and macOS, after finishing the compile and while in the build directory:\n\n    # Copy leelaz binary to autogtp subdirectory\n    cp leelaz autogtp\n\n    # Run AutoGTP to start contributing\n    ./autogtp/autogtp\n\n\n# Usage for playing or analyzing games\n\nLeela Zero is not meant to be used directly. You need a graphical interface\nfor it, which will interface with Leela Zero through the GTP protocol.\n\nThe engine supports the [GTP protocol, version 2](https://www.lysator.liu.se/~gunnar/gtp/gtp2-spec-draft2/gtp2-spec.html).\n\n[Lizzie](https://github.com/featurecat/lizzie/releases) is a client specifically\nfor Leela Zero which shows live search probilities, a win rate graph, and has\nan automatic game analysis mode. Has binaries for Windows, Mac, and Linux.\n\n[Sabaki](http://sabaki.yichuanshen.de/) is a very nice looking GUI with GTP 2\ncapability.\n\n[LeelaSabaki](https://github.com/SabakiHQ/LeelaSabaki) is modified to\nshow variations and winning statistics in the game tree, as well as a heatmap\non the game board.\n\n[GoReviewPartner](https://github.com/pnprog/goreviewpartner) is a tool for\nautomated review and analysis of games using bots (saved as .rsgf files),\nLeela Zero is supported.\n\nA lot of go software can interface to an engine via GTP,\nso look around.\n\nAdd the --gtp commandline option on the engine command line to enable Leela\nZero's GTP support. You will need a weights file, specify that with the -w option.\n\nAll required commands are supported, as well as the tournament subset, and\n\"loadsgf\". The full set can be seen with \"list_commands\". The time control\ncan be specified over GTP via the time\\_settings command. The kgs-time\\_settings\nextension is also supported. These have to be supplied by the GTP 2 interface,\nnot via the command line!\n\n# Weights format\n\nThe weights file is a text file with each line containing a row of coefficients.\nThe layout of the network is as in the AlphaGo Zero paper, but any number of\nresidual blocks is allowed, and any number of outputs (filters) per layer,\nas long as the latter is the same for all layers. The program will autodetect\nthe amounts on startup. The first line contains a version number.\n\n* Convolutional layers have 2 weight rows:\n    1) convolution weights\n    2) channel biases\n* Batchnorm layers have 2 weight rows:\n    1) batchnorm means\n    2) batchnorm variances\n* Innerproduct (fully connected) layers have 2 weight rows:\n    1) layer weights\n    2) output biases\n\nThe convolution weights are in [output, input, filter\\_size, filter\\_size]\norder, the fully connected layer weights are in [output, input] order.\nThe residual tower is first, followed by the policy head, and then the value\nhead. All convolution filters are 3x3 except for the ones at the start of the policy and value head, which are 1x1 (as in the paper).\n\nThere are 18 inputs to the first layer, instead of 17 as in the paper. The\noriginal AlphaGo Zero design has a slight imbalance in that it is easier\nfor the black player to see the board edge (due to how padding works in\nneural networks). This has been fixed in Leela Zero. The inputs are:\n\n```\n1) Side to move stones at time T=0\n2) Side to move stones at time T=-1  (0 if T=0)\n...\n8) Side to move stones at time T=-7  (0 if T\u003c=6)\n9) Other side stones at time T=0\n10) Other side stones at time T=-1   (0 if T=0)\n...\n16) Other side stones at time T=-7   (0 if T\u003c=6)\n17) All 1 if black is to move, 0 otherwise\n18) All 1 if white is to move, 0 otherwise\n```\n\nEach of these forms a 19 x 19 bit plane.\n\nIn the training/caffe directory there is a zero.prototxt file which contains a\ndescription of the full 40 residual block design, in (NVIDIA)-Caffe protobuff\nformat. It can be used to set up nv-caffe for training a suitable network.\nThe zero\\_mini.prototxt file describes a smaller 12 residual block case. The\ntraining/tf directory contains the network construction in TensorFlow format,\nin the tfprocess.py file.\n\nExpert note: the channel biases seem redundant in the network topology\nbecause they are followed by a batchnorm layer, which is supposed to normalize\nthe mean. In reality, they encode \"beta\" parameters from a center/scale\noperation in the batchnorm layer, corrected for the effect of the batchnorm mean/variance adjustment. At inference time, Leela Zero will fuse the channel\nbias into the batchnorm mean, thereby offsetting it and performing the center operation. This roundabout construction exists solely for backwards\ncompatibility. If this paragraph does not make any sense to you, ignore its\nexistence and just add the channel bias layer as you normally would, output\nwill be correct.\n\n# Training\n\n## Getting the data\n\nAt the end of the game, you can send Leela Zero a \"dump\\_training\" command,\nfollowed by the winner of the game (either \"white\" or \"black\") and a filename,\ne.g:\n\n    dump_training white train.txt\n\nThis will save (append) the training data to disk, in the format described below,\nand compressed with gzip.\n\nTraining data is reset on a new game.\n\n## Supervised learning\n\nLeela can convert a database of concatenated SGF games into a datafile suitable\nfor learning:\n\n    dump_supervised sgffile.sgf train.txt\n\nThis will cause a sequence of gzip compressed files to be generated,\nstarting with the name train.txt and containing training data generated from\nthe specified SGF, suitable for use in a Deep Learning framework.\n\n## Training data format\n\nThe training data consists of files with the following data, all in text\nformat:\n\n* 16 lines of hexadecimal strings, each 361 bits longs, corresponding to the\nfirst 16 input planes from the previous section\n* 1 line with 1 number indicating who is to move, 0=black, 1=white, from which\nthe last 2 input planes can be reconstructed\n* 1 line with 362 (19x19 + 1) floating point numbers, indicating the search probabilities\n(visit counts) at the end of the search for the move in question. The last\nnumber is the probability of passing.\n* 1 line with either 1 or -1, corresponding to the outcome of the game for the\nplayer to move\n\n## Running the training\n\nFor training a new network, you can use an existing framework (Caffe,\nTensorFlow, PyTorch, Theano), with a set of training data as described above.\nYou still need to contruct a model description (2 examples are provided for\nCaffe), parse the input file format, and outputs weights in the proper format.\n\nThere is a complete implementation for TensorFlow in the training/tf directory.\n\n### Supervised learning with TensorFlow\n\nThis requires a working installation of TensorFlow 1.4 or later:\n\n    src/leelaz -w weights.txt\n    dump_supervised bigsgf.sgf train.out\n    exit\n    training/tf/parse.py 6 128 train.out\n\nThis will run and regularly dump Leela Zero weight files (of networks with 6\nblocks and 128 filters) to disk, as well as snapshots of the learning state\nnumbered by the batch number. If interrupted, training can be resumed with:\n\n    training/tf/parse.py 6 128 train.out leelaz-model-batchnumber\n\n# Todo\n\n- [ ] Further optimize Winograd transformations.\n- [ ] Improve GPU batching in the search.\n- [ ] Root filtering for handicap play.\n- More backends:\n- [ ] MKL-DNN based backend.\n- [ ] CUDA specific version using cuDNN or cuBLAS.\n- [ ] AMD specific version using MIOpen/ROCm.\n\n# Related links\n\n* Status page of the distributed effort:\nhttps://zero.sjeng.org\n* GUI and study tool for Leela Zero:\nhttps://github.com/featurecat/lizzie\n* Watch Leela Zero's training games live in a GUI:\nhttps://github.com/barrybecker4/LeelaWatcher\n* Original Alpha Go (Lee Sedol) paper:\nhttps://storage.googleapis.com/deepmind-media/alphago/AlphaGoNaturePaper.pdf\n* Alpha Go Zero paper:\nhttps://deepmind.com/documents/119/agz_unformatted_nature.pdf\n* Alpha Zero (Go, Chess, Shogi) paper:\nhttps://arxiv.org/pdf/1712.01815.pdf\n* AlphaGo Zero Explained In One Diagram:\nhttps://medium.com/applied-data-science/alphago-zero-explained-in-one-diagram-365f5abf67e0\n* Stockfish chess engine ported to Leela Zero framework:\nhttps://github.com/LeelaChessZero/lczero\n* Leela Chess Zero (chess optimized client)\nhttps://github.com/LeelaChessZero/lc0\n\n# License\n\nThe code is released under the GPLv3 or later, except for ThreadPool.h, cl2.hpp, half.hpp and the eigen and clblast_level3 subdirs, which have specific licenses (compatible with GPLv3) mentioned in those files.\n\nAdditional permission under GNU GPL version 3 section 7\n\nIf you modify this Program, or any covered work, by linking or\ncombining it with NVIDIA Corporation's libraries from the\nNVIDIA CUDA Toolkit and/or the NVIDIA CUDA Deep Neural\nNetwork library and/or the NVIDIA TensorRT inference library\n(or a modified version of those libraries), containing parts covered\nby the terms of the respective license agreement, the licensors of\nthis Program grant you additional permission to convey the resulting\nwork.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleela-zero%2Fleela-zero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleela-zero%2Fleela-zero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleela-zero%2Fleela-zero/lists"}