{
    "info": {
        "author": "ImparaAI",
        "author_email": "author@example.com",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3"
        ],
        "description": "A Python3 library for running a [Monte Carlo tree search](https://en.wikipedia.org/wiki/Monte_Carlo_tree_search), either traditionally by drilling down to end game states or with expert policies as might be provided by a neural network.\n\n- **Version:** 1.3.1\n\n[![Build Status](https://travis-ci.org/ImparaAI/monte-carlo-tree-search.png?branch=master)](https://travis-ci.org/ImparaAI/monte-carlo-tree-search)\n\n# Monte Carlo tree search basics\n\nThe Monte Carlo tree search (MCTS) algorithm can help with making a decision from a number of options. It avoids exploring every possible option by randomly sampling a small number of pathways and picking the move with the highest probability of victory. This is commonly applied to games like chess or go where it's useful to know what move should come next if you want to win the game.\n\nMCTS works by expanding the search tree to figure out which moves (or child/subsequent states) are likely to produce a positive result if chosen. While time is available, the algorithm continues to explore the tree, always slightly favoring the direction that has either proven to be fruitful or is less explored. When no time is left, the most explored direction is chosen.\n\nThe search tree expansion can be done in two different ways:\n\n- **Traditional**: At least one random rollout to a game's end state (e.g. win, loss, tie) for each move under evaluation so the algorithm can make a choice.\n- **Expert policy (i.e. neural network)**: Instead of expensively rolling all the way out to a game's end state ask an expert (a neural network for example) which move is most likely to produce a positive outcome.\n\nFor a deeper dive into the topic, check out [this article](http://tim.hibal.org/blog/alpha-zero-how-and-why-it-works/).\n\n# This library\n\nAs the user of this library, you only have to provide:\n\n- A function that finds the direct children of each search tree node (called the **`child_finder`**)\n- A function for evaluating nodes for end state outcomes (called the **`node_evaluator`**)\n-- *(Not necessary with neural network)*\n\n# Usage\n\nCreate a new Monte Carlo tree:\n\n```python\nfrom chess import Game\nfrom montecarlo.node import Node\nfrom montecarlo.montecarlo import MonteCarlo\n\nchess_game = Game()\nmontecarlo = MonteCarlo(Node(chess_game))\n```\n\nThe root node describes your current game state. This state will be used by you later in the **`child_finder`** and the **`node_evaluator`**.\n\nFor the sake of demonstration, we will assume you have a generic `Game` library that can tell you what moves are possible and allows you to perform those moves to change the game's state.\n\n## Traditional Monte Carlo\n\nAdd a **`child_finder`** and a **`node_evaluator`**:\n\n```python\ndef child_finder(node):\n\tfor move in node.state.get_possible_moves():\n\t\tchild = Node(deepcopy(node.state)) #or however you want to construct the child's state\n\t\tchild.state.move(move) #or however your library works\n\t\tnode.add_child(child)\n\ndef node_evaluator(self, node):\n\tif node.state.won():\n\t\treturn 1\n\telif node.state.lost():\n\t\treturn -1\n\nmontecarlo.child_finder = child_finder\nmontecarlo.node_evaluator = node_evaluator\n```\n\nThe **`child_finder`** should add any child nodes to the parent node passed into the function, if there are any. If there are none, the parent should be in an end state, so the **`node_evaluator`** should return a value between `-1` and `1`.\n\n## Expert policy (AI)\n\nIf you have an expert policy that you can apply to the children as they're being generated, the library will recognize that it doesn't need to make the costly drill down to an end state. If your neural net produces both an expert policy value for the children and a win value for the parent node, you can skip declaring the `node_evaluator` altogether.\n\n```python\ndef child_finder(self, node):\n\twin_value, expert_policy_values = neural_network.predict(node.state)\n\n\tfor move in node.state.get_possible_moves():\n\t\tchild = Node(deepcopy(node.state))\n\t\tchild.state.move(move)\n\t\tchild.player_number = child.state.whose_turn()\n\t\tchild.policy_value = get_child_policy_value(child, expert_policy_values) #should return a probability value between 0 and 1\n\t\tnode.add_child(child)\n\n\tnode.update_win_value(win_value)\n\nmontecarlo.child_finder = child_finder\n```\n\n## Simulate and make a choice\n\nRun the simulations:\n\n```python\nmontecarlo.simulate(50) #number of expansions to run. higher is typically more accurate at the cost of processing time\n```\n\nOnce the simulations have run you can ask the instance to make a choice:\n\n```python\nchosen_child_node = montecarlo.make_choice()\nchosen_child_node.state.do_something()\n```\n\nAfter you've chosen a new root node, you can override it on the `montecarlo` instance and do more simulations from the new position in the tree.\n\n```python\nmontecarlo.root_node = montecarlo.make_choice()\n```\n\nIf you're training a neural network, you may want to make a more exploratory choice for the first N moves of a game:\n\n```python\nmontecarlo.root_node = montecarlo.make_exploratory_choice()\n```\n\nThis won't provide a purely random choice, rather it will be random with a bias favoring the more explored pathways.\n\n## Turn-based environments\n\nIf you are modeling a turn-based environment (e.g. a two player board game), set the `player_number` on each node so the selection process can invert child win values:\n\n```python\nnode = Node(state)\nnode.player_number = 1\n```\n\nIt doesn't matter what this number is (you can use 1 and 2 or 5 and 6), only that it is consistent with other nodes.\n\n## Tweaking the discovery factor\n\nWhen building a new child node, you can change the rate at which discovery is preferred:\n\n```python\nnode = Node(state)\nnode.discovery_factor = 0.2 #0.35 by default, can be between 0 and 1\n```\n\nThe closer this number is to 1, the more discovery will be favored over demonstrated value in later simulations.",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/ImparaAI/monte-carlo-tree-search",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "imparaai-montecarlo",
        "package_url": "https://pypi.org/project/imparaai-montecarlo/",
        "platform": "",
        "project_url": "https://pypi.org/project/imparaai-montecarlo/",
        "project_urls": {
            "Homepage": "https://github.com/ImparaAI/monte-carlo-tree-search"
        },
        "release_url": "https://pypi.org/project/imparaai-montecarlo/1.3.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Library for running a Monte Carlo tree search either traditionally or with expert policies",
        "version": "1.3.1"
    },
    "last_serial": 4492595,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "f5b3f0d37d33e13e241d734fab7f5337",
                    "sha256": "48e102fae1927e48b5ba1cc0c33fca62afb6273d7b0983716e18a35c1771c54d"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "f5b3f0d37d33e13e241d734fab7f5337",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 3680,
                "upload_time": "2018-09-15T00:35:33",
                "url": "https://files.pythonhosted.org/packages/b5/73/35db0b059e6f5ed7d4feba1fb40441ab267bc41e38937beb5223fe3751d8/imparaai-montecarlo-1.0.0.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2e1db56a8c7ad5ee2a038bf13f11ea98",
                    "sha256": "4c18d6b88dd608213fff6812e7b78683ed62c5d2395453fadadf5b3b13d532b1"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "2e1db56a8c7ad5ee2a038bf13f11ea98",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 3678,
                "upload_time": "2018-09-15T00:55:56",
                "url": "https://files.pythonhosted.org/packages/ab/3a/8feb24139e828bf7bec081864503c7bd354b527c538306c2b7bb2d27ae0f/imparaai-montecarlo-1.0.2.tar.gz"
            }
        ],
        "1.0.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "703198d240cb284705e7a533bc42693b",
                    "sha256": "16174a34c1e595b5b420bf5054369f9a70a3f34f1fa2a9ffa0cb04a33e250575"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.0.3.tar.gz",
                "has_sig": false,
                "md5_digest": "703198d240cb284705e7a533bc42693b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4689,
                "upload_time": "2018-09-15T01:17:52",
                "url": "https://files.pythonhosted.org/packages/3d/29/b1941ffed03585a17e08c05ac906adcec0fadfa70bbc820be71369a171dd/imparaai-montecarlo-1.0.3.tar.gz"
            }
        ],
        "1.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "ca08d65c74a07ee0fe0ef4a1071efca3",
                    "sha256": "ddf4b98f60f54d9599aae34b4afcb3e6298f157e2d4cca7dc7fa46eb2cbb7bc6"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "ca08d65c74a07ee0fe0ef4a1071efca3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4709,
                "upload_time": "2018-09-18T03:43:17",
                "url": "https://files.pythonhosted.org/packages/dc/5e/ae263eb85772875d20b529fe19ac94e7f478a3df59d4ea1c5393f19fb496/imparaai-montecarlo-1.1.0.tar.gz"
            }
        ],
        "1.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c265d5a080c2a8f25fb3bda3fe3a656c",
                    "sha256": "f67ae6912bd5bfc2b8513e3c2088c6ef84ed1a1cd1c5b61dc6aa258b9398eeec"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "c265d5a080c2a8f25fb3bda3fe3a656c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4716,
                "upload_time": "2018-09-20T01:15:26",
                "url": "https://files.pythonhosted.org/packages/9b/ab/893fa9c1d55302ab13d89919fb3d1b2dfbd95ca56292849523b601c035bf/imparaai-montecarlo-1.1.1.tar.gz"
            }
        ],
        "1.1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4663ee57f19e5a08342dc6acf3e785cc",
                    "sha256": "de1b5cc348b6cf7a994b0451bfba3a7479f26956569f1a463cc5f200b94e26da"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "4663ee57f19e5a08342dc6acf3e785cc",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4723,
                "upload_time": "2018-09-20T22:24:44",
                "url": "https://files.pythonhosted.org/packages/79/4e/db767e4dec2900cf8fbcbaf624b8c690db649940f4f620803b3527de8aac/imparaai-montecarlo-1.1.2.tar.gz"
            }
        ],
        "1.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4e283b10d8b5b62f5a68942c4ca32507",
                    "sha256": "4b66c82302c8db3430b15c64c0f5699e907220b86861a19eea65deb5ccfb09f0"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "4e283b10d8b5b62f5a68942c4ca32507",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4897,
                "upload_time": "2018-09-22T06:26:27",
                "url": "https://files.pythonhosted.org/packages/33/22/c5b70848ff769652511bf8b6e71b7cdf777a4f498b1e2a560b34346f9b8c/imparaai-montecarlo-1.2.0.tar.gz"
            }
        ],
        "1.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "bba020813d010c826d345fea4f219dd1",
                    "sha256": "409e352431a09c15d3ae73b5a7776edbeb1aa8eaf9d086a0c0639f5c5e07376a"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "bba020813d010c826d345fea4f219dd1",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4899,
                "upload_time": "2018-09-22T07:16:18",
                "url": "https://files.pythonhosted.org/packages/bc/22/89d62ffbd9de7dca68e98a8a604dc9a9ac0d0274b04368ab2d258d066051/imparaai-montecarlo-1.2.1.tar.gz"
            }
        ],
        "1.3.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "153c93513ec3064ea1d3a977b1fd8e51",
                    "sha256": "d2867bd16e4bb748c3159cd459a6e1484d3ed293fffa814a1aaa1c0a4d2e992e"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.3.0.tar.gz",
                "has_sig": false,
                "md5_digest": "153c93513ec3064ea1d3a977b1fd8e51",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 5733,
                "upload_time": "2018-09-29T23:20:52",
                "url": "https://files.pythonhosted.org/packages/99/8b/afdb370d2ab0211bba6ab22c4ff0beb950d6e75c80bce9a3e9031d9a0db2/imparaai-montecarlo-1.3.0.tar.gz"
            }
        ],
        "1.3.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "357aa3899bbed77f16ba9eb1221179cb",
                    "sha256": "e7d3a3f32d124674cdd11590c3dc466c79fbc0c29e2be6571b7d03fa08aad8fe"
                },
                "downloads": -1,
                "filename": "imparaai-montecarlo-1.3.1.tar.gz",
                "has_sig": false,
                "md5_digest": "357aa3899bbed77f16ba9eb1221179cb",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 5889,
                "upload_time": "2018-11-16T06:55:56",
                "url": "https://files.pythonhosted.org/packages/89/05/e10f6ad365280d0b6d0bbab18f36df9ff9c2a09a4189c00292d8fc23bb6f/imparaai-montecarlo-1.3.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "357aa3899bbed77f16ba9eb1221179cb",
                "sha256": "e7d3a3f32d124674cdd11590c3dc466c79fbc0c29e2be6571b7d03fa08aad8fe"
            },
            "downloads": -1,
            "filename": "imparaai-montecarlo-1.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "357aa3899bbed77f16ba9eb1221179cb",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 5889,
            "upload_time": "2018-11-16T06:55:56",
            "url": "https://files.pythonhosted.org/packages/89/05/e10f6ad365280d0b6d0bbab18f36df9ff9c2a09a4189c00292d8fc23bb6f/imparaai-montecarlo-1.3.1.tar.gz"
        }
    ]
}