monte-carlo-tree-search


Namemonte-carlo-tree-search JSON
Version 2.0.5 PyPI version JSON
download
home_pagehttps://github.com/kstruempf/MCTS
SummaryA simple package to allow users to run Monte Carlo Tree Search on any perfect information domain
upload_time2024-02-29 08:22:32
maintainer
docs_urlNone
authorPaul Sinclair, Konstantin Strümpf and others
requires_python
licenseMIT
keywords mcts monte carlo tree search
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # MCTS

This package provides a simple way of using Monte Carlo Tree Search in any perfect information domain.

It was originally authored by [pbsinclair42](https://github.com/pbsinclair42/MCTS). This fork however complies with the
[Python Naming Convention](https://namingconvention.org/python/), provides base classes for implementing states and
actions, and includes more comprehensive examples.

## Installation

With [pip](https://pypi.org/project/monte-carlo-tree-search/): `pip install monte-carlo-tree-search`

Without pip: Download the zip/tar.gz file of the [latest release](https://github.com/kstruempf/MCTS/releases),
extract it, and run `python setup.py install`

## Quick Usage

In order to run MCTS, you must implement your own `State` class that extends `mcts.base.base.BaseState` which can fully
describe the state of the world. It must implement four methods:

- `get_current_player()`: Returns 1 if it is the maximizer player's turn to choose an action, or -1 for the minimiser
  player
- `get_possible_actions()`: Returns an iterable of all `action`s which can be taken from this state
- `take_action(action)`: Returns the state which results from taking action `action`
- `is_terminal()`: Returns `True` if this state is a terminal state
- `get_reward()`: Returns the reward for this state. Only needed for terminal states.

You must also choose a hashable representation for an action as used in `get_possible_actions` and `take_action`.
Typically, this would be a class with a custom `__hash__` method, but it could also simply be a tuple, a string, etc.
A `BaseAction` class is provided for this purpose.

Once these have been implemented, running MCTS is as simple as initializing your starting state, then running:

```python
from mcts.base.base import BaseState
from mcts.searcher.mcts import MCTS


class MyState(BaseState):
    def get_possible_actions(self) -> [any]:
        pass

    def take_action(self, action: any) -> 'BaseState':
        pass

    def is_terminal(self) -> bool:
        pass

    def get_reward(self) -> float:
        pass

    def get_current_player(self) -> int:
        pass


initial_state = MyState()

searcher = MCTS(time_limit=1000)
bestAction = searcher.search(initial_state=initial_state)
```

Here the unit of `time_limit=1000` is milliseconds. You can also use for example `iteration_limit=100` to specify the
number of rollouts. Exactly one of `time_limit` and `iteration_limit` should be specified.

```python
best_action = searcher.search(initial_state=initial_state)
print(best_action)  # the best action to take found within the time limit
```

To also receive the best reward as a return value set `need_details` to `True` in `searcher.search(...)`.

```python
best_action, reward = searcher.search(initial_state=initial_state, need_details=True)
print(best_action)  # the best action to take found within the time limit
print(reward)  # the expected reward for the best action
```

**Examples**

You can find some examples using the MCTS here:

* [naughtsandcrosses.py](https://github.com/kstruempf/MCTS/blob/main/mcts/example/naughtsandcrosses.py) is a minimal
  runnable example by [pbsinclair42](https://github.com/pbsinclair42)
* [connectmnk.py](https://github.com/kstruempf/MCTS/blob/main/mcts/example/connectmnk.py) is an example running a full
  game between two MCTS agents by [LucasBorboleta](https://github.com/LucasBorboleta)

## Collaborating

Feel free to raise a new issue for any new feature or bug you've spotted. Pull requests are also welcomed if you're
interested in directly improving the project.

### Coding Guidelines

Commit message should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
This makes contributions easily comprehensible and enables us to automatically generate release notes.

Recommended tooling for developers:

* JetBrains Plugin [Conventional Commit](https://plugins.jetbrains.com/plugin/13389-conventional-commit)
  by [Edoardo Luppi](https://github.com/lppedd)
* Visual Studio
  Plugin [Conventional Commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits)
  by [vivaxy](https://marketplace.visualstudio.com/publishers/vivaxy)

**Example commit message**

```
fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123
```

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/kstruempf/MCTS",
    "name": "monte-carlo-tree-search",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "mcts,monte,carlo,tree,search",
    "author": "Paul Sinclair, Konstantin Str\u00fcmpf and others",
    "author_email": "k.struempf@icloud.com",
    "download_url": "",
    "platform": null,
    "description": "# MCTS\n\nThis package provides a simple way of using Monte Carlo Tree Search in any perfect information domain.\n\nIt was originally authored by [pbsinclair42](https://github.com/pbsinclair42/MCTS). This fork however complies with the\n[Python Naming Convention](https://namingconvention.org/python/), provides base classes for implementing states and\nactions, and includes more comprehensive examples.\n\n## Installation\n\nWith [pip](https://pypi.org/project/monte-carlo-tree-search/): `pip install monte-carlo-tree-search`\n\nWithout pip: Download the zip/tar.gz file of the [latest release](https://github.com/kstruempf/MCTS/releases),\nextract it, and run `python setup.py install`\n\n## Quick Usage\n\nIn order to run MCTS, you must implement your own `State` class that extends `mcts.base.base.BaseState` which can fully\ndescribe the state of the world. It must implement four methods:\n\n- `get_current_player()`: Returns 1 if it is the maximizer player's turn to choose an action, or -1 for the minimiser\n  player\n- `get_possible_actions()`: Returns an iterable of all `action`s which can be taken from this state\n- `take_action(action)`: Returns the state which results from taking action `action`\n- `is_terminal()`: Returns `True` if this state is a terminal state\n- `get_reward()`: Returns the reward for this state. Only needed for terminal states.\n\nYou must also choose a hashable representation for an action as used in `get_possible_actions` and `take_action`.\nTypically, this would be a class with a custom `__hash__` method, but it could also simply be a tuple, a string, etc.\nA `BaseAction` class is provided for this purpose.\n\nOnce these have been implemented, running MCTS is as simple as initializing your starting state, then running:\n\n```python\nfrom mcts.base.base import BaseState\nfrom mcts.searcher.mcts import MCTS\n\n\nclass MyState(BaseState):\n    def get_possible_actions(self) -> [any]:\n        pass\n\n    def take_action(self, action: any) -> 'BaseState':\n        pass\n\n    def is_terminal(self) -> bool:\n        pass\n\n    def get_reward(self) -> float:\n        pass\n\n    def get_current_player(self) -> int:\n        pass\n\n\ninitial_state = MyState()\n\nsearcher = MCTS(time_limit=1000)\nbestAction = searcher.search(initial_state=initial_state)\n```\n\nHere the unit of `time_limit=1000` is milliseconds. You can also use for example `iteration_limit=100` to specify the\nnumber of rollouts. Exactly one of `time_limit` and `iteration_limit` should be specified.\n\n```python\nbest_action = searcher.search(initial_state=initial_state)\nprint(best_action)  # the best action to take found within the time limit\n```\n\nTo also receive the best reward as a return value set `need_details` to `True` in `searcher.search(...)`.\n\n```python\nbest_action, reward = searcher.search(initial_state=initial_state, need_details=True)\nprint(best_action)  # the best action to take found within the time limit\nprint(reward)  # the expected reward for the best action\n```\n\n**Examples**\n\nYou can find some examples using the MCTS here:\n\n* [naughtsandcrosses.py](https://github.com/kstruempf/MCTS/blob/main/mcts/example/naughtsandcrosses.py) is a minimal\n  runnable example by [pbsinclair42](https://github.com/pbsinclair42)\n* [connectmnk.py](https://github.com/kstruempf/MCTS/blob/main/mcts/example/connectmnk.py) is an example running a full\n  game between two MCTS agents by [LucasBorboleta](https://github.com/LucasBorboleta)\n\n## Collaborating\n\nFeel free to raise a new issue for any new feature or bug you've spotted. Pull requests are also welcomed if you're\ninterested in directly improving the project.\n\n### Coding Guidelines\n\nCommit message should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.\nThis makes contributions easily comprehensible and enables us to automatically generate release notes.\n\nRecommended tooling for developers:\n\n* JetBrains Plugin [Conventional Commit](https://plugins.jetbrains.com/plugin/13389-conventional-commit)\n  by [Edoardo Luppi](https://github.com/lppedd)\n* Visual Studio\n  Plugin [Conventional Commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits)\n  by [vivaxy](https://marketplace.visualstudio.com/publishers/vivaxy)\n\n**Example commit message**\n\n```\nfix: prevent racing of requests\n\nIntroduce a request id and a reference to latest request. Dismiss\nincoming responses other than from latest request.\n\nRemove timeouts which were used to mitigate the racing issue but are\nobsolete now.\n\nReviewed-by: Z\nRefs: #123\n```\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A simple package to allow users to run Monte Carlo Tree Search on any perfect information domain",
    "version": "2.0.5",
    "project_urls": {
        "Homepage": "https://github.com/kstruempf/MCTS"
    },
    "split_keywords": [
        "mcts",
        "monte",
        "carlo",
        "tree",
        "search"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0d50e2f12682e0044e60dcd809997cabbeba4634ac14a9aa67e7c7725bee65b2",
                "md5": "4467ccc0bc6e4520577a45f6fa66a942",
                "sha256": "c3f3d7823c1ad1637d2a1fac51a1f7058f34757afd1651413e50a6b7c9c6abd2"
            },
            "downloads": -1,
            "filename": "monte_carlo_tree_search-2.0.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "4467ccc0bc6e4520577a45f6fa66a942",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 10687,
            "upload_time": "2024-02-29T08:22:32",
            "upload_time_iso_8601": "2024-02-29T08:22:32.980829Z",
            "url": "https://files.pythonhosted.org/packages/0d/50/e2f12682e0044e60dcd809997cabbeba4634ac14a9aa67e7c7725bee65b2/monte_carlo_tree_search-2.0.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-29 08:22:32",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "kstruempf",
    "github_project": "MCTS",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "monte-carlo-tree-search"
}
        
Elapsed time: 1.28263s