update readme (#100)

Author: amj

README.md

@@ -3,13 +3,13 @@ Minigo: A minimalist Go engine modeled after AlphaGo Zero, built on MuGo
 
 This is a pure Python implementation of a neural-network based Go AI, using
 TensorFlow. While inspired by Deepmind's AlphaGo algorithm, this project is not
-a Deepmind project.
+a Deepmind project nor is it affiliated with the official AlphaGo project.
 
 ### This is NOT an official version of AlphaGo ###
 
 Repeat, *this is not the official AlphaGo program by DeepMind*.  This is an
 independent effort by Go enthusiasts to replicate the results of the AlphaGo
-Zero paper ("Mastering the Game of Go without Human Knowledge" *Nature*), with
+Zero paper ("Mastering the Game of Go without Human Knowledge," *Nature*), with
 some resources generously made available by Google.
 
 Minigo is based off of Brian Lee's "MuGo" -- a pure Python implementation of the
@@ -44,10 +44,17 @@ establishes itself as the top Go AI. Instead, we strive for a readable,
 understandable implementation that can benefit the community, even if that
 means our implementation is not as fast or efficient as possible.
 
+While this product might produce such a strong model, we hope to focus on the
+process.  Remember, getting there is half the fun :)
+
 We hope this project is an accessible way for interested developers to have
 access to a strong Go model with an easy-to-understand platform of python code
 available for extension, adaptation, etc.
 
+If you'd like to read about our experiences training models, see RESULTS.md
+
+To see our guidelines for contributing, see CONTRIBUTING.md
+
 Getting Started
 ===============
 
@@ -76,8 +83,8 @@ the dependencies:
 pip3 install -r requirements.txt
 ```
 
-If you wish to run on GPU you must install CUDA 8.0 or later (see TensorFlow
-documentation).
+The `requirements.txt` file assumes you'll use a GPU; if you wish to run on GPU
+you must install CUDA 8.0 or later (see TensorFlow documentation).
 
 If you don't want to run on GPU or don't have one, you can downgrade:
 
@@ -124,23 +131,29 @@ All commands are compatible with either Google Cloud Storage as a remote file
 system, or your local file system. The examples here use GCS, but local file
 paths will work just as well.
 
-To use GCS, set the `BUCKET_NAME` variable and authenticate. Otherwise, all
-commands fetching files from GCS will hang.
+To use GCS, set the `BUCKET_NAME` variable and authenticate via `gcloud login`.
+Otherwise, all commands fetching files from GCS will hang.
 
+For instance, this would set a bucket, authenticate, and then look for the most
+recent model.
 ```bash
 export BUCKET_NAME=your_bucket;
 gcloud auth application-default login
 gsutil ls gs://minigo/models | tail -3
 ```
 
-Which might look like
+Which might look like:
 
 ```
 gs://$BUCKET_NAME/models/000193-trusty.data-00000-of-00001
 gs://$BUCKET_NAME/models/000193-trusty.index
 gs://$BUCKET_NAME/models/000193-trusty.meta
 ```
 
+These three files comprise the model, and commands that take a model as an
+argument usually need the path to the model basename, e.g.
+`gs://$BUCKET_NAME/models/000193-trusty`
+
 You'll need to copy them to your local disk.  This fragment copies the latest
 model to the directory specified by `MINIGO_MODELS`
 
@@ -212,8 +225,8 @@ Overview
 --------
 
 The following sequence of commands will allow you to do one iteration of
-reinforcement learning on 9x9. These are the basic commands used in the
-kubernetified version used to produce the models and games referenced above.
+reinforcement learning on 9x9. These are the basic commands used to produce the
+models and games referenced above.
 
 The commands are
  - bootstrap: initializes a random model
@@ -231,7 +244,7 @@ This command creates a random model, which appears at .
 
 ```bash
 export MODEL_NAME=000000-bootstrap
-python3 main.py bootstrap gs://$BUCKET_NAME/models/$MODEL_NAME -n $BOARD_SIZE
+python3 main.py bootstrap gs://$BUCKET_NAME/models/$MODEL_NAME
 ```
 
 Self-play
@@ -245,29 +258,28 @@ gs://$BUCKET_NAME/data/selfplay/$MODEL_NAME/local_worker/*.tfrecord.zz
 gs://$BUCKET_NAME/sgf/$MODEL_NAME/local_worker/*.sgf
 ```
 
-(-n 9 makes 9x9 games)
 ```bash
 python3 main.py selfplay gs://$BUCKET_NAME/models/$MODEL_NAME \
   --readouts 10 \
-  --games 8 \
-  -v 3 -n 9 \
+  -v 3 \
   --output-dir=gs://$BUCKET_NAME/data/selfplay/$MODEL_NAME/local_worker \
   --output-sgf=gs://$BUCKET_NAME/sgf/$MODEL_NAME/local_worker
 ```
-(-n 9 makes it play 9x9 games)
 
 Gather
 ------
 
-This command takes multiple tfrecord.zz files (which will probably be KBs in size)
-and shuffles them into tfrecord.zz files that are ~100 MB in size.
-
 ```
 python3 main.py gather
 ```
 
+This command takes multiple tfrecord.zz files (which will probably be KBs in size)
+and shuffles them into tfrecord.zz files that are ~100 MB in size.
+
 Gathering is done according to model numbers, so that games generated by
-one model stay together. The output will be in the directories
+one model stay together.  By default, `rl_loop.py` will use directories
+specified by the environment variable `BUCKET_NAME`, set at the top of
+`rl_loop.py`
 
 ```
 gs://$BUCKET_NAME/data/training_chunks/$MODEL_NAME-{chunk_number}.tfrecord.zz
@@ -295,7 +307,6 @@ python3 main.py train gs://$BUCKET_NAME/data/training_chunks \
     --load-file=gs://$BUCKET_NAME/models/000000-bootstrap \
     --generation-num=1 \
     --logdir=path/to/tensorboard/logs \
-    -n 9
 ```
 
 The updated model weights will be saved at the end. (TODO: implement some sort
@@ -313,8 +324,7 @@ Running Minigo on a Cluster
 As you might notice, playing games is fairly slow.  One way to speed up playing
 games is to run Minigo on many computers simultaneously.  Minigo was originally
 trained by containerizing these worker jobs and running them on a Kubernetes
-cluster, hosted on the Google Cloud Platform (TODO: links for installing GCP
-SDK, kubectl, etc.)
+cluster, hosted on the Google Cloud Platform.
 
 *NOTE* These commands will result in VMs being created and will result in
 charges to your GCP account!  *Proceed with care!*
@@ -371,7 +381,7 @@ Bringing up a cluster
 ---------------------
 
 0. Switch to the `cluster` directory
-1. Set the common environment variables in `common` corresponding to your GCP project and bucket names.
+1. Set the common environment variables in `common.sh` corresponding to your GCP project and bucket names.
 2. Run `deploy`, which will:
   a. Create a bucket
   b. Create a service account
@@ -476,8 +486,8 @@ To kill the job,
 envsubst < player.yaml | kubectl delete -f -
 ```
 
-Preflight checks for a training run.
-====================================
+Preflight checklist for a training run.
+=======================================
 
 
 Setting up the selfplay cluster
@@ -519,7 +529,7 @@ Setting up the selfplay cluster
 Useful things for the selfplay cluster
 --------------------------------------
 
-* Getting a list of the selfplay games ordered by most recent start
+* Getting a list of the selfplay games ordered by start time.
   ```
   kubectl get po --sort-by=.status.startTime
   ```
@@ -537,13 +547,9 @@ Useful things for the selfplay cluster
   ```
 
 
-Setting up logging via stackdriver, plus metrics, bla bla.
-
-
-If you've run rsync to collect a set of SGF files (cheatsheet: `python3
-rl_loop.py smart-rsync --source-dir="gs://$BUCKET_NAME/sgf/" --from-model-num 0
---game-dir=sgf/`), here are some handy
-bashisms to run on them:
+If you've run rsync to collect a set of SGF files (cheatsheet: `gsutil -m cp -r
+gs://$BUCKET_NAME/sgf/$MODEL_NAME sgf/`), here are some handy
+bash fragments to run on them:
 
 * Find the proportion of games won by one color:
   ```
@@ -567,7 +573,5 @@ bashisms to run on them:
   \; | ministat
   ```
 
-
-etc...
-
-
+Also check the 'oneoffs' directory for interesting scripts to analyze e.g. the
+resignation threshold.