katrain-qt/INSTALL.md

# KaTrain Installation

* [Quick install guide for MacOS](#MacQuick)
    * [Troubleshooting and installation from sources](#MacSources)
* [Quick install guide for Windows](#WindowsQuick)
    * [Troubleshooting and installation from sources](#WindowsSources)
* [Quick install guide for Linux](#LinuxQuick)
    * [Troubleshooting and installation from sources](#LinuxSources)
* [Configuring Multiple GPUS](#GPU)
* [Troubleshooting KataGo](#KataGo)

## <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Apple_Logo.svg" alt="macOs" height="35"/> Installation for macOS users

### <a name="MacQuick"></a>Quick install guide

The easiest way to install is probably [brew](https://brew.sh/). Simply run `brew install katrain` and it will download and install the latest pre-built .app, and also install katago if needed.

You can also find downloadable .app files for macOS [here](https://github.com/sanderland/katrain/releases). 
Simply download, unzip the file, mount the .dmg and drag the .app file to your application folder, everything is included.
The first time launching the application you may need to [control-click in finder to give permission for the 'unidentified' app to launch](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac). This is simply a result of Apple charging $99/year to developers to be 'identified'.

Users with the last generation M1 macs with different architecture should then `brew install katago` in addition to this. KaTrain will automatically detect this KataGo binary.

### <a name="MacCommand"></a>Command line install guide

[Open a terminal](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) and enter the following commands:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew install python3
brew install katago
pip3 install katrain
```

If you are using a M1 Mac, at the point of writing, the latest stable release of Kivy (2.0) does not support the new architecture, so we have to use a development snapshot and build it from source:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew install python3
brew install katago

# install dependencies: https://kivy.org/doc/stable/installation/installation-osx.html#install-source-osx
brew install pkg-config sdl2 sdl2_image sdl2_ttf sdl2_mixer gstreamer ffmpeg

# install Kivy from source: https://kivy.org/doc/stable/gettingstarted/installation.html#kivy-source-install
pip3 install "kivy[base] @ https://github.com/kivy/kivy/archive/master.zip" --no-binary kivy

pip3 install katrain
```

Now you can start KaTrain by simply typing `katrain` in a terminal.

These commands install [Homebrew](https://brew.sh), which simplifies installing packages,
 followed by the programming language Python, the KataGo AI, and KaTrain itself.
 
To upgrade to a newer version, simply run `pip3 install -U katrain`

### <a name="MacSources"></a>Troubleshooting and Installation from sources

Installation from sources is essentially the same as for Linux, see [here](#LinuxSources),
 note that you will still need to install your own KataGo, using brew or otherwise. 

If you encounter SSL errors on downloading model files, you may need to follow [these](https://stackoverflow.com/questions/52805115/certificate-verify-failed-unable-to-get-local-issuer-certificate) instructions to fix your certificates.

## <img src="https://upload.wikimedia.org/wikipedia/commons/5/5f/Windows_logo_-_2012.svg" alt="Windows" height="35"/> Installation for Windows users

### <a name="WindowsQuick"></a>Quick install guide

You can find downloadable .exe files for windows [here](https://github.com/sanderland/katrain/releases). 
Simply download and run, everything is included.

### <a name="WindowsSources"></a>Installation from sources

* Download the repository by clicking the green *Clone or download* on this page and *Download zip*. Extract the contents.
* Make sure you have a python installation, I will assume Anaconda (Python 3.7/3.8), available [here](https://www.anaconda.com/products/individual#download-section).
* Open 'Anaconda prompt' from the start menu and navigate to where you extracted the zip file using the `cd <folder>` command.
* Execute the command `pip3 install .`
* Start the app by running `katrain` in the command prompt. 

## <img src="https://upload.wikimedia.org/wikipedia/commons/a/ab/Linux_Logo_in_Linux_Libertine_Font.svg" alt="Linux" height="35"/> Installation for Linux users

### <a name="LinuxQuick"></a>Quick install guide

If you have a working Python 3.6-3.8 available, you should be able to simply:

* Run `pip3 install -U katrain` to install or upgrade.
* Run the program by executing `katrain` in a terminal.

### <a name="LinuxSources"></a>Installation from sources 

This section describes how to install KaTrain from sources,
 in case you want to run it in a local directory or have more control over the process. 
It assumes you have a working Python 3.6+ installation.

* Open a terminal.
* Run the command `git clone https://github.com/sanderland/katrain.git` to download the repository and 
  change directory using `cd katrain`
* Run the command `pip3 install .` to install the package globally, or use `--user` to install locally.
* Run the program by typing `katrain` in the terminal.
    * If you prefer not to install, run without installing using `python3 -m katrain` after installing the 
    dependencies from `requirements.txt`.

A binary for KataGo is included, but if you have compiled your own, press F8 to open general settings and change the 
 KataGo executable path to the relevant KataGo v1.4+ binary.

### <a name="LinuxTrouble"></a>Troubleshooting and advanced installation from sources

You can try to manually install dependencies to resolve some issues relating to missing dependencies,
 e.g. the binary 'wheel' is not provided, KataGo is not starting, or sounds are not working.
You can also follow these instructions if you don't want to install KaTrain, and just run it locally.

First install the following packages, which are either required for building Kivy, 
 or may help resolve missing dependencies for Kivy or KataGo.
```bash
sudo apt-get install python3-pip build-essential git python3 python3-dev ffmpeg libsdl2-dev libsdl2-image-dev\
    libsdl2-mixer-dev libsdl2-ttf-dev libportmidi-dev libswscale-dev libavformat-dev libavcodec-dev zlib1g-dev\
    libgstreamer1.0 gstreamer1.0-plugins-base gstreamer1.0-plugins-good libpulse\
    pkg-config libgl-dev opencl-headers ocl-icd-opencl-dev libzip-dev
```
Then, try installing python package dependencies using:
```bash
pip3 install -r requirements.txt
pip3 install screeninfo # Skip on MacOS, not working
```
In case the sound is not working, or there is no available wheel for your OS or Python version, try building kivy locally using:
```bash
pip3 uninstall kivy
pip3 install kivy --no-binary kivy
```

You can now start KaTrain by running `python3 -m katrain`

In case KataGo does not start, an alternative is to go [here](https://github.com/lightvector/KataGo) and compile KataGo yourself.



## <a name="GPU"></a> Configuring the GPU(s) KataGo uses

In most cases KataGo detects your configuration correctly, automatically searching for OpenCL devices and select the highest scoring device. 
However, if you have multiple GPUs or want to force a specific device you will need to edit the 'analysis_config.cfg' file in the KataGo folder.

To see what devices are available and which one KataGo is using. Look for the following lines in the terminal after starting KaTrain:
```
    Found 3 device(s) on platform 0 with type CPU or GPU or Accelerator
    Found OpenCL Device 0: Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz (Intel) (score 102)
    Found OpenCL Device 1: Intel(R) UHD Graphics 630 (Intel Inc.) (score 6000102)
    Found OpenCL Device 2: AMD Radeon Pro 5500M Compute Engine (AMD) (score 11000102)
    Using OpenCL Device 2: AMD Radeon Pro 5500M Compute Engine (AMD) OpenCL 1.2
```

The above devices were found on a 2019 MacBook Pro with both an on-motherboard graphics chip, and a separate AMD Radeon Pro video card.
As you can see it scores about twice as high as the Intel UHD chip and KataGo has selected
 it as it's sole device. You can configure KataGo to use *both* the AMD and the Intel devices to get the best performance out of the system.

* Open the 'analysis_config.cfg' file in the `katrain/KataGo` folder in your python packages, or local sources.
  If you can't find it, turn on `debug_level=1` in general settings and look for the command that is used to start KataGo.
* Search for `numNNServerThreadsPerModel` (~line 108), uncomment the line by deleting the # and set the value to 2. The line should read `numNNServerThreadsPerModel = 2`.
* Search for `openclDeviceToUseThread` (~line 164), uncomment by deleting the # and set the values to the device ID numbers identified in the terminal.
  From the example above, we would want to use devices 1 and 2, for the Intel and AMD GPUs, but not device 0 (the CPU). In our case, the lines should read:
```
openclDeviceToUseThread0 = 1
openclDeviceToUseThread1 = 2
```
* Run `katrain` and confirm that KataGo is now using both devices, by 
 checking the output from the terminal, which should indicate two devices being used. For example:
```
    Found 3 device(s) on platform 0 with type CPU or GPU or Accelerator
    Found OpenCL Device 0: Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz (Intel) (score 102)
    Found OpenCL Device 1: Intel(R) UHD Graphics 630 (Intel Inc.) (score 6000102)
    Found OpenCL Device 2: AMD Radeon Pro 5500M Compute Engine (AMD) (score 11000102)
    Using OpenCL Device 1: Intel(R) UHD Graphics 630 (Intel Inc.) OpenCL 1.2
    Using OpenCL Device 2: AMD Radeon Pro 5500M Compute Engine (AMD) OpenCL 1.2
```


## <a name="KataGo"></a> Troubleshooting and advanced KataGo settings

See [here](ENGINE.md) for an overview of how to resolve various issues with KataGo.