hoeiriis / mcts

Implementation for Monte Carlo Tree Search

Table of Contents

1. Introduction
2. Dependencies
   1. C++
      1. Cmake >=3.8
      2. make
      3. Boost >= 1.69
   2. Documentation
   3. C++ tests
3. Compiling
4. Writing documentation
5. Writing tests

Introduction

This repository contains a C++ implementation of the UCT Monte Carlo Tree Search algorithm for single- and two-player environments.

The implementation is intended to be generic enough that a user can derive their own environment from the provided base classes and solve that environment with the core engine.

Dependencies

As this is being developed on Linux, only Linux instructions will be provided as of now. However, this should be applicable to other platforms as well.

C++

Current requirements are as follows:

Cmake >=3.8

make

Boost >= 1.69

This should all be available in your distribution's package manager. If you wish to use a local installation of boost in a non-standard install location, you can set the environment variable BOOST_ROOT="/path/to/your/boost/root", and the CMake script should prioritize that install.

Documentation

This project uses Doxygen to generate documentation. If you wish to build the documentation pages, please install Doxygen and Graphviz.

C++ tests

CMake clones googletests from the official git repo and installs it in GIT_ROOT/External_Libs/GTest Currently, GTest will not be installed AND generate tests on the first run. When building from a clean clone you should run the following sequence of commands before the tests will be compiled:

1. cmake
2. make
3. cmake
4. make
5. make test

After this sequence of commands as been run, the tests will be compiled properly on each invocation of make.

Compiling

Compiling the C++ code is straight forward after installing the above dependencies;

cd MCTS

cmake .

make

The binaries will be in GIT_ROOT/build/bin

Optionally, if you wish to build the documentation:

make doc

Html and latex documentation will be generated in GIT_ROOT/doc

CMake builds test unless explicitly told otherwise (cmake . -DTESTING=NO) Run tests with

make test

Writing documentation

Please document your files, classes, and functions where it isn't self explanatory. Doxygen comments should be in the header files, and not in the .cpp files. That way, users of the library do not need to use the actual source files in order to access the documentation, and can therefore use precompiled binaries instead of compiling it themselves, and editors only need to access the header files being included in order to provide in-editor documentation. Doxygen will not include documentation for your functions if the encapsulating class is not documented, and it will not include documentation for your class if the containing file is not annotated. See TicTacToeEnvironment.h or GIT_ROOT/src/doxygen_example.cpp for an example of the syntax.

See the official doxygen documentation for details.

Writing tests

You can use GIT_ROOT/test/test_environments as a template for setting up your tests.

In order to add tests for a feature:

1. Create a subdirectory for the feature GIT_ROOT/test/, e.g. GIT_ROOT/test/my_awesome_feature/

2. Add add_subdirectory(my_awesome_feature) to GIT_ROOT/test/CMakeLists.txt

3. Add test source files for your feature in your directory, e.g. test_my_awesome_feature.cpp. Include GTest and necessary headers, (#include <gtest/gtest.h>) and start writing tests. GTest defines a number of macros. For most tests you just need TEST, EXPECT_EQ, and EXPECT_DOUBLE_EQ. Define a test with

   TEST(NameOfFunctionBeingTested, PropertyBeingTested){
       EXPECT_EQ(function_output, expected_output);
   }

Add your source file as an executable target in CMakeLists.txt as usual, and link the target against GTest and the feature itself if applicable:

add_executable(test_my_awesome_feature test_my_awesome_feature.cpp

target_link_libraries(test_my_awesome_feature GTest::GTest GTest::Main my_awesome_feature)

And then have gtest detect the test cases and add them:

gtest_discover_tests(test_my_awesome_feature)

For details and more advanced use, check the official documentation:

Google test in CMake

Google test primer

Google mock primer

mcts's Issues

Performance optimizations

This issue is used to write down potential performance optimizations. Please list them in comments:

Make a nullState factory/constructor solution for State

Sometimes, mostly in initializer lists in classes, a State holding no actual data is needed as a temporary State. Functionality for a proper temporary State is needed

Make a cache in SearchNode as to limit calls to the underlying environment

Since the underlying environment potentially has the largest computational cost, it would be a good idea to add a cache to SearchNode that holds the computed values of for instance GetValidChildStates, so we can avoid multiple calls of the same type.
Options to disable this will probably be necessary though, since the memory requirements might increase drastically depending on the environment