# 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"
}
JSON
