Merge pull request #98 from leela-zero/next

merge leela-zero/next

.gitignore

@@ -11,3 +11,4 @@ leelaz_opencl_tuning
 /build-autogtp-*
 /build-validation-*
 .vs/
+build/

CMakeLists.txt

@@ -1,6 +1,6 @@
 # This file is part of Leela Zero.
 # Copyright (C) 2017 Marco Calignano
-# Copyright (C) 2017-2018 Gian-Carlo Pascutto and contributors
+# Copyright (C) 2017-2019 Gian-Carlo Pascutto and contributors
 # Leela Zero is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to Leela Zero
+
+## C++ Usage
+
+Leela Zero is written in C++14, and generally encourages writing in modern C++ style.
+
+This means that:
+
+* The code overwhelmingly uses Almost Always Auto style, and so should you.
+* Prefer range based for and non-member (c)begin/(c)end.
+* You can rely on boost 1.58.0 or later being present.
+* Manipulation of raw pointers is to be avoided as much as possible.
+* Prefer constexpr over defines or constants.
+* Prefer "using" over typedefs.
+* Prefer uniform initialization.
+* Prefer default initializers for member variables.
+* Prefer emplace_back and making use of move assignment.
+* Aim for const-correctness. Prefer passing non-trivial parameters by const reference.
+* Use header include guards, not #pragma once (pragma once is non-standard, has issues with detecting identical files, and is slower https://gcc.gnu.org/bugzilla/show_bug.cgi?id=58770)
+* config.h is always the first file included.
+* Feel free to use templates, but remember that debugging obscure template metaprogramming bugs is not something people enjoy doing in their spare time.
+* Using exceptions is allowed.
+
+## Code Style
+
+* Look at the surrounding code and the rest of the project!
+* Indentation is 4 spaces. No tabs.
+* public/private/protected access modifiers are de-indented
+* Maximum line length is 80 characters. There are rare exceptions in the code, usually involving user-visible text strings.
+* Ifs are always braced, with very rare exceptions when everything fits on one line and doing it properly makes the code less readable.
+* The code generally avoids any pointer passing and allows non-const references for parameters. Still, for new code it should be preferred to a) put input parameters first b) use return values over output parameters.
+* Function arguments that wrap are aligned.
+* Member variables in a class have an m_ prefix and are private. Members of POD structs don't and aren't.
+* Constants and enum values are ALL_CAPS.
+* Variables are lowercase.
+* Function names are underscore_case.
+* Classes are CamelCase.
+* Comments are preferably full sentences with proper capitalization and a period.
+* Split the includes list into config.h, standard headers and our headers.
+
+If something is not addressed here or there is no similar code, the Google C++ Style Guide is always a good reference.
+
+We might move to enforce clang-format at some point.
+
+## Adding dependencies
+
+C++ does not quite have the package systems JavaScript and Rust have, so some restraint should be excercised when adding dependencies. Dependencies typically complicate the build for new contributors, especially on Windows, and reliance on specific, new versions can be a nuisance on Unix based systems.
+
+The restraints on modern header-only libraries are significantly less because they avoid most of the above problems.
+
+If a library is not mature and well-supported on Windows, Linux *and* macOS, you do not want it.
+
+This is not an excuse to re-invent the wheel.
+
+## Upgrading dependencies
+
+The code and dependencies should target the latest stable versions of Visual Studio/MSVC, and the latest stable/LTS releases of common Linux distros, with some additional delay as not everyone will be able to upgrade to a new stable/LTS right away.
+
+For example, upgrading to C++17 or boost 1.62.0 (oldest version in a Debian stable or Ubuntu LTS release) can be considered if there's a compelling use case and/or we can confirm it is supported on all platforms we reasonably target.
+
+## Merging contributions
+
+Contributions come in the form of pull requests against the "next" branch.
+
+They are rebased or squashed on top of the next branch, so the history will stay linear, i.e. no merge commits.
+
+Commit messages follow Linux kernel style: a summary phrase that is no more than 70-75 characters (but preferably <50) and describes both what the patch changes, as well as why the patch might be necessary.
+
+If the patch is to a specific subsystem (AutoGTP, Validation, ...) then prefix the summary by that subsystem (e.g. AutoGTP: ...).
+
+This is followed by a blank line, and a description that is wrapped at 72 characters. Good patch descriptions can be large time savers when someone has to bugfix the code afterwards.
+
+The end of the commit message should mention which (github) issue the patch fixes, if any, and the pull request it belongs to.
+
+Patches need to be reviewed before merging. Try to find the person who worked on the code last, or who has done work in nearby code (git blame is your friend, and this is why we write proper commit messages...). With some luck that is someone with write access to the repository. If not, you'll have to ping someone who does.
+
+Experience says that the majority of the pull requests won't live up to this ideal, which means that maintainers will have to squash patch series and clean up the commit message to be coherent before merging.
+
+If you are a person with write access to the repo, and are about to merge a commit, ask yourself the following question: am I confident enough that I understand this code, so that I can and am willing to go in and fix it if it turns out to be necessary? If the answer to this question is no, then do not merge the code. Not merging a contribution (quickly) is annoying for the individual contributor. Merging a bad contribution is annoying for everyone who wants to contribute now and in the future.
+
+If a contributor can't be bothered to fix up the trailing whitespace in their patch, odds are they aren't going to be willing to fix the threading bug it introduces either.
+
+## "Improvements" and Automagic
+
+Improvements to the engine that can affect strength should include supporting data. This means no-regression tests for functional changes, and a proof of strength improvement for things which are supposed to increase strength.
+
+The tools in the validation directory are well-fit for this purpose, as
+is the python tool "ringmaster".
+
+The number of configurable options should be limited where possible. If it is not possible for the author to make rules of thumb for suitable values for those options, then the majority of users have no hope of getting them right, and may mistakenly make the engine weaker. If you must introduce new ones, consider limiting their exposure to developers only via USE_TUNER and set a good default for them.
+
+## GTP Extensions
+
+GTP makes it possible to connect arbitrary engines to arbitrary interfaces.
+
+Unfortunately GTP 2 isn't extensive enough to realistically fit all needs of analysis GUIs, which means we have had to extend it. The lack of standardization here means that Go software is continously catching up to the chess world, especially after UCI was introduced. We should aim to make this situation better, not worse.
+
+This means that extensions have the possibility of outliving Leela Zero (or any GUIs) provided they are well thought out.
+
+It makes sense to be thoughtful here, consider the responsibilities of both GUI and engine, and try to come up with flexible building blocks rather than a plethora of commands for very specific use cases.
+
+Experience and previous discussions can help understanding:
+
+* lz-analyze "avoid" and "allow" were added in pull request [#1949](https://github.com/leela-zero/leela-zero/pull/1949).
+* lz-analyze got a side-to-move option in pull request [#1872](https://github.com/leela-zero/leela-zero/pull/1872) and [#1642](https://github.com/leela-zero/leela-zero/pull/1642).
+* lz-analyze got a "prior" tag in pull request [#1836](https://github.com/leela-zero/leela-zero/pull/1836).
+* lz-analyze was added in pull request [#1388](https://github.com/leela-zero/leela-zero/pull/1388).
+* lz-setoption was added in pull request [#1741](https://github.com/leela-zero/leela-zero/pull/1741).
+* Pull request [#2170](https://github.com/leela-zero/leela-zero/pull/2170) has some discussion regarding how to navigate SGF
+  files that were parsed by the engine via GTP.

README.md

@@ -1,7 +1,5 @@
-[![Linux Build Status](https://travis-ci.org/gcp/leela-zero.svg?branch=next)](https://travis-ci.org/gcp/leela-zero)
-[![Windows Build Status](https://ci.appveyor.com/api/projects/status/pf1hcgly8f1a8iu0/branch/next?svg=true)](https://ci.appveyor.com/project/gcp/leela-zero/branch/next)
-
-
+[![Linux Build Status](https://travis-ci.org/leela-zero/leela-zero.svg?branch=next)](https://travis-ci.org/leela-zero/leela-zero)
+[![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)
 
 # What
 
@@ -44,17 +42,17 @@ the distributed effort. But you can still play, especially if you are patient.
 
 ### Windows
 
-Head to the Github releases page at https://github.com/gcp/leela-zero/releases,
+Head to the Github releases page at https://github.com/leela-zero/leela-zero/releases,
 download the latest release, unzip, and launch autogtp.exe. It will connect to
 the server automatically and do its work in the background, uploading results
 after each game. You can just close the autogtp window to stop it.
 
 ### macOS and Linux
 
-Follow the instructions below to compile the leelaz binary, then go into
-the autogtp subdirectory and follow [the instructions there](autogtp/README.md)
-to build the autogtp binary. Copy the leelaz binary into the autogtp dir, and
-launch autogtp.
+Follow the instructions below to compile the leelaz and autogtp binaries in
+the build subdirectory. Then run autogtp as explained in the
+[contributing](#contributing) instructions below.
+Contributing will start when you run autogtp.
 
 ## Using a Cloud provider
 
@@ -66,15 +64,18 @@ There are community maintained instructions available here:
 
 * [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)
 
-# I just want to play right now
+# I just want to play with Leela Zero right now
 
-Download the best known network weights file from: https://zero.sjeng.org/best-network
+Download the best known network weights file from [here](https://zero.sjeng.org/best-network), or, if you prefer a more human style,
+a (weaker) network trained from human games [here](https://sjeng.org/zero/best_v1.txt.zip).
 
-And head to the [Usage](#usage) section of this README.
+If 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)
+section of this README.
 
-If you prefer a more human style, a network trained from human games is available here: https://sjeng.org/zero/best_v1.txt.zip.
+If you are on Unix or macOS, you have to compile the program yourself. Follow
+the compilation instructions below and then read the [Usage](#usage-for-playing-or-analyzing-games) section.
 
-# Compiling
+# Compiling AutoGTP and/or Leela Zero
 
 ## Requirements
 
@@ -85,71 +86,89 @@ If you prefer a more human style, a network trained from human games is availabl
 https://github.com/KhronosGroup/OpenCL-Headers/tree/master/CL)
 * OpenCL ICD loader (ocl-icd-libopencl1 on Debian/Ubuntu, or reference implementation at https://github.com/KhronosGroup/OpenCL-ICD-Loader)
 * An OpenCL capable device, preferably a very, very fast GPU, with recent
-drivers is strongly recommended (OpenCL 1.1 support is enough).
+drivers is strongly recommended (OpenCL 1.1 support is enough). Don't
+forget to install the OpenCL driver if this part is packaged seperately
+by the Linux distribution (e.g. nvidia-opencl-icd).
 If you do not have a GPU, add the define "USE_CPU_ONLY", for example
 by adding -DUSE_CPU_ONLY=1 to the cmake command line.
 * Optional: BLAS Library: OpenBLAS (libopenblas-dev) or Intel MKL
 * The program has been tested on Windows, Linux and macOS.
 
-## Example of compiling and running - Ubuntu & similar
+## Example of compiling - Ubuntu & similar
 
     # Test for OpenCL support & compatibility
     sudo apt install clinfo && clinfo
 
     # Clone github repo
-    git clone https://github.com/gcp/leela-zero
+    git clone https://github.com/leela-zero/leela-zero
     cd leela-zero
     git submodule update --init --recursive
 
     # Install build depedencies
     sudo apt install libboost-dev libboost-program-options-dev libboost-filesystem-dev opencl-headers ocl-icd-libopencl1 ocl-icd-opencl-dev zlib1g-dev
 
-    # Use stand alone directory to keep source dir clean
+    # Use a stand alone build directory to keep source dir clean
     mkdir build && cd build
+
+    # Compile leelaz and autogtp in build subdirectory with cmake
     cmake ..
     cmake --build .
+
+    # Optional: test if your build works correctly
     ./tests
-    curl -O https://zero.sjeng.org/best-network
-    ./leelaz --weights best-network
 
-## Example of compiling and running - macOS
+## Example of compiling - macOS
 
     # Clone github repo
-    git clone https://github.com/gcp/leela-zero
+    git clone https://github.com/leela-zero/leela-zero
     cd leela-zero
     git submodule update --init --recursive
 
     # Install build depedencies
-    brew install boost cmake
+    brew install boost cmake zlib
 
-    # Use stand alone directory to keep source dir clean
+    # Use a stand alone build directory to keep source dir clean
     mkdir build && cd build
+
+    # Compile leelaz and autogtp in build subdirectory with cmake
     cmake ..
     cmake --build .
+
+    # Optional: test if your build works correctly
     ./tests
-    curl -O https://zero.sjeng.org/best-network
-    ./leelaz --weights best-network
 
-## Example of compiling and running - Windows
+## Example of compiling - Windows
 
     # Clone github repo
-    git clone https://github.com/gcp/leela-zero
+    git clone https://github.com/leela-zero/leela-zero
     cd leela-zero
     git submodule update --init --recursive
+
     cd msvc
     Double-click the leela-zero2015.sln or leela-zero2017.sln corresponding
     to the Visual Studio version you have.
     # Build from Visual Studio 2015 or 2017
-    # Download <https://zero.sjeng.org/best-network> to msvc\x64\Release
-    msvc\x64\Release\leelaz.exe --weights best-network
 
-# Usage
+# Contributing
 
-The engine supports the [GTP protocol, version 2](https://www.lysator.liu.se/~gunnar/gtp/gtp2-spec-draft2/gtp2-spec.html).
+For Windows, you can use a release package, see ["I want to help"](#windows).
+
+Unix and macOS, after finishing the compile and while in the build directory:
+
+    # Copy leelaz binary to autogtp subdirectory
+    cp leelaz autogtp
+
+    # Run AutoGTP to start contributing
+    ./autogtp/autogtp
+
+
+# Usage for playing or analyzing games
 
 Leela Zero is not meant to be used directly. You need a graphical interface
 for it, which will interface with Leela Zero through the GTP protocol.
 
+The engine supports the [GTP protocol, version 2](https://www.lysator.liu.se/~gunnar/gtp/gtp2-spec-draft2/gtp2-spec.html).
+
 [Lizzie](https://github.com/featurecat/lizzie/releases) is a client specifically
 for Leela Zero which shows live search probilities, a win rate graph, and has
 an automatic game analysis mode. Has binaries for Windows, Mac, and Linux.
@@ -161,6 +180,10 @@ capability.
 show variations and winning statistics in the game tree, as well as a heatmap
 on the game board.
 
+[GoReviewPartner](https://github.com/pnprog/goreviewpartner) is a tool for
+automated review and analysis of games using bots (saved as .rsgf files),
+Leela Zero is supported.
+
 A lot of go software can interface to an engine via GTP,
 so look around.
 
@@ -300,8 +323,7 @@ If interrupted, training can be resumed with:
 # Todo
 
 - [ ] Further optimize Winograd transformations.
-- [ ] Implement GPU batching.
-- [ ] GTP extention to exclude moves from analysis.
+- [ ] Implement GPU batching in the search.
 - [ ] Root filtering for handicap play.
 - More backends:
 - [ ] MKL-DNN based backend.
@@ -332,3 +354,14 @@ https://github.com/LeelaChessZero/lc0
 # License
 
 The 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.
+
+Additional permission under GNU GPL version 3 section 7
+
+If you modify this Program, or any covered work, by linking or
+combining it with NVIDIA Corporation's libraries from the
+NVIDIA CUDA Toolkit and/or the NVIDIA CUDA Deep Neural
+Network library and/or the NVIDIA TensorRT inference library
+(or a modified version of those libraries), containing parts covered
+by the terms of the respective license agreement, the licensors of
+this Program grant you additional permission to convey the resulting
+work.