Merge pull request pytorch#34 from zchen0211/master

Design Doc for Game Record

design_doc/go_game.md

@@ -2,7 +2,7 @@
 
 Go Game Rule part.
 
-## 0. Basic info
+## Basic info
 - in src_cpp/elfgames/go/base/board.h
 - Define basic types and coordinates operation:
 ```cpp
@@ -42,7 +42,7 @@ FindAllCandidateMoves();
 float getTrompTaylorScore();
 ```
 
-## 1. Go State
+## Go State
 - A class with all the above functions integrated;
 - in src_cpp/elfgames/go/base/go_state.h
 ```cpp
@@ -61,7 +61,7 @@ private:
 };
 ```
 
-## 2. Go State Ext
+## Go State Ext
 - A class wrapped on GoState to support online behavior;
 - in src_cpp/elfgames/go/go_state_ext.h
 ```cpp
@@ -85,7 +85,7 @@ class GoStateExt {
 ```
 - class GoStateExtOffline
 ```cpp
-class GoStateExtOffline {}
+class GoStateExtOffline {
  fromRecord();
  switchRandomMove(rng);
  generateD4Code(rng);

design_doc/mcts.md

@@ -1,12 +1,12 @@
-# MCTS AI C++ Interface
+# MCTS in ELF OpenGo
 
 - MCTS is generally implemented in C++ with templates.
 - Three important concepts: **Actor**, **Action**, **State**.
 - General implementations available in the directory src_cpp/elf/ai/tree_search;
 - Go-specific available in src_cpp/elfgames/go/mcts/
 - Two modes are supported: a multi-threading mode for training (used in selfplay games), and a pseudo-multi-threading batch mode for online games (e.g., gtp).
 
-## 1. ``Actor``
+## Actor
 - class MCTSActor, a go specific implementation in src_cpp/elfgames/go/mcts/mcts.h
 - Important member function **evaluate** pre-evaluate, get feature and call neural network if necessary, post-process and save in resp;
 ```cpp
@@ -31,7 +31,7 @@ private:
  post_nn(); // pi2response
 ```
 
-## 2. MCTS Go AI
+## MCTS Go AI
 - class **MCTSGoAI**, derived from class **MCTSAI_T<MCTSActor>**. In the class we add following members:
 ```cpp
 class MCTSGoAI : public MCTSAI_T<MCTSActor> {
@@ -82,7 +82,7 @@ private:
 };
 ```
 
-## 2. ``Tree Search Details``
+## Tree Search Details
 - class **TreeSearchSingleThread** in folder src_cpp/elf/ai/tree_search/tree_search.h is for training multi-threading execution.
 ```cpp
 template <typename State, typename Action>
@@ -164,7 +164,7 @@ private:
 };
 ```
 
-## 3. Tree and Nodes
+## Tree and Nodes
 - Base class **NodeBase**
 ```cpp
 template<State>

design_doc/model_interface.md

@@ -1,7 +1,8 @@
 # Model Interface in ELF
 
 ## Model Interface
-- class ModelInterface is a python class saving network models
+- class ModelInterface is a python class saving network models.
+- Its member `models` is a k-v store to call a CNN model by name.
 ```python
 class ModelInterface(object):
   def __init__(self, option_map):

design_doc/options.md

@@ -1,20 +1,21 @@
 # ELF Option Parser and Interface
 
-## 0. Design of Option
- 1. Basically in the folder src_cpp/elf/options/ and src_py/elf/options/;
- 2. Important classes like **game**, **model**, **trainer**, **evaluator**, **sampler** and so forth;
+Since ELF Go project has a lot of options, we have a separate folding to manage and implement options in both C++ and python.
 
-## 1. Option Spec Class
- 1. All arguments from command line are parsed by argparser in py_option_spec.py
- 2. class **PyOptionSpec** does the parsing;
- 3. Inheritted from class **OptionSpec** in C++;
- 3. After doing the parsing, **parse()** will convert the parsed arguments to a Option Map class.
+## Design of Option
+- Basically in the folder src_cpp/elf/options/ and src_py/elf/options/;
+- Important classes like **game**, **model**, **trainer**, **evaluator**, **sampler** and so forth;
 
+## Option Spec Class (Python)
+- All arguments from command line are parsed by argparser in py_option_spec.py
+- class **PyOptionSpec** does the parsing;
+- Inheritted from class **OptionSpec** in C++;
+- After doing the parsing, **parse()** will convert the parsed arguments to a Option Map class.
 
-## 2. Option Map Class
- 1. A class to handle Argument by Json shared info between python and C++;
- 2. class **PyOptionMap** receives a **PyOptionSpec** class and saves as a member;
- 3. Inherited from class **OptionMap** in C++;
+## Option Map Class (Python)
+- A class to handle Argument by Json shared info between python and C++;
+- class **PyOptionMap** receives a **PyOptionSpec** class and saves as a member;
+- Inherited from class **OptionMap** in C++;
 
 ## 3. Detailed Design
 - class OptionSpec (C++)

design_doc/record.md

@@ -0,0 +1,109 @@
+# Record
+
+- record in folder src_cpp/elfgames/go/record.h is a c++ implementation with **json** for serialization.
+
+## Json Utils
+- JSON util functions are defined as macros in src_cpp/elf/utils/json_utils.h
+```cpp
+#define JSON_LOAD(target, j, field)
+#define JSON_LOAD_OPTIONAL(target, j, field)
+#define JSON_SAVE(j, field)
+#define JSON_SAVE_OBJ(j, field)
+#define JSON_LOAD_OBJ_ARGS(target, j, field, ...)
+#define JSON_LOAD_VEC(target, j, field)
+#define JSON_LOAD_VEC_OPTIONAL(target, j, field)
+```
+
+## Client
+- Client Type: either invalid, selfplay or eval-then selfplay:
+```cpp
+struct ClientType {};
+```
+- Client Control: set json stuff like client type, resign threshold and so on.
+```cpp
+struct ClientCtrl {
+  void setJsonFields(json& j);
+  static ClientCtrl createFromJson(
+      const json& j,
+      bool player_swap_optional = false);
+};
+```
+- Model Pair
+```cpp
+struct ModelPair {};
+```
+
+## Message Related Request
+- Message request
+```cpp
+struct MsgRequest {
+  ModelPair vers;
+  ClientCtrl client_ctrl;
+
+  void setJsonFields(json& j);
+  static MsgRequest createFromJson(const json& j) {}
+  std::string setJsonFields(); 
+};
+```
+- Message Result (mcts policy and value for a game)
+```cpp
+struct CoordRecord {
+  unsigned char prob[BOUND_COORD];
+};
+
+struct MsgResult {
+  std::vector<int64_t> using_models;
+  std::vector<CoordRecord> policies;
+  std::string content;
+  std::vector<float> values;
+
+  // set self value to the json object fields
+  void setJsonFields(json& j) const {};
+  // get results from a json file (one game) save num_move, value...
+  static MsgResult createFromJson(const json& j) {}
+
+};
+```
+- Others
+```cpp
+struct MsgVersion {};
+enum RestartReply {};
+struct MsgRestart {};
+```
+
+## Record
+- A struct with both MsgRequest and MsgResult
+```cpp
+struct Record {
+  MsgRequest request;
+  MsgResult result;
+
+  uint64_t timestamp = 0;
+  uint64_t thread_id = 0;
+  int seq = 0;
+  float pri = 0.0;
+  bool offline = false;
+
+  // save self members to the json object j
+  void setJsonFields(json& j) const {}
+  // load everything from json object j and save to self members
+  static Record createFromJson(const json& j) {}
+  // return a vector of record by first json::parse(string)
+  // iteratively createFromJson()
+  static std::vector<Record> createBatchFromJson(const std::string& json_str) {
+  // same as above
+  static bool loadBatchFromJsonFile(
+      const std::string& f,
+      std::vector<Record>* records);
+  // batch setJsonFields
+  static std::string dumpBatchJsonString();
+};
+```
+- A wrapper on record on a vector of Record
+```cpp
+struct Records {
+  std::string identity;
+  std::unordered_map<int, ThreadState> states;
+  std::vector<Record> records;
+};
+```

design_doc/sampler.md

@@ -1,6 +1,6 @@
 # Sampler in ELF
 
-Python class in src_py/rlpytorch/sampler/ folder.
+Python class in src_py/rlpytorch/sampler/ folder. It is a little out-of-date and not realy used in the Go project.
 
 ## Class Sampler
 - Used to sample an action from policy.

design_doc/trainer.md

@@ -27,7 +27,7 @@ class Evaluator(object):
 ```
 
 ## Trainer
-- An extra rl_method added to the Evaluator, has a member as evaluator
+- Trainer is also a pure python class wrapped on evaluator.
 ```python
 class Trainer(object):
   def __init__(self, option_map, ...):