gymcts 1.0.0__tar.gz → 1.2.0__tar.gz

{gymcts-1.0.0/src/gymcts.egg-info → gymcts-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: gymcts
-Version: 1.0.0
+Version: 1.2.0
 Summary: A minimalistic implementation of the Monte Carlo Tree Search algorithm for planning problems fomulated as gymnaisum reinforcement learning environments.
 Author: Alexander Nasuta
 Author-email: Alexander Nasuta <alexander.nasuta@wzl-iqs.rwth-aachen.de>
@@ -25,7 +25,7 @@ License: MIT License
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
-Project-URL: Homepage, https://github.com/Alexander-Nasuta/pypitemplate
+Project-URL: Homepage, https://github.com/Alexander-Nasuta/gymcts
 Platform: unix
 Platform: linux
 Platform: osx
@@ -34,7 +34,7 @@ Platform: win32
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: rich
@@ -63,6 +63,9 @@ Requires-Dist: furo; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: sphinx-copybutton; extra == "dev"
 Requires-Dist: nbsphinx; extra == "dev"
+Requires-Dist: jupytext; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Dynamic: license-file
 
 # Graph Matrix Job Shop Env
 
@@ -118,8 +121,8 @@ The NaiveSoloMCTSGymEnvWrapper can be used with non-deterministic environments,
 ```python
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -133,10 +136,10 @@ if __name__ == '__main__':
     env.reset()
 
     # 1. wrap the environment with the naive wrapper or a custom gymcts wrapper
-    env = NaiveSoloMCTSGymEnvWrapper(env)
+    env = DeepCopyMCTSGymEnvWrapper(env)
 
     # 2. create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=True,
@@ -170,13 +173,13 @@ if __name__ == '__main__':
 A minimal example of how to use the package with the FrozenLake environment and the DeterministicSoloMCTSGymEnvWrapper is provided in the following code snippet below.
 The DeterministicSoloMCTSGymEnvWrapper can be used with deterministic environments, such as the FrozenLake environment without slippery ice.
 
-The DeterministicSoloMCTSGymEnvWrapper saves the action sequence that lead to the current state in the MCTS node. 
+The DeterministicSoloMCTSGymEnvWrapper saves the action sequence that lead to the current state in the MCTS node.
 
 ```python
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_deterministic_wrapper import DeterministicSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_action_history_wrapper import ActionHistoryMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -190,10 +193,10 @@ if __name__ == '__main__':
     env.reset()
 
     # 1. wrap the environment with the wrapper
-    env = DeterministicSoloMCTSGymEnvWrapper(env)
+    env = ActionHistoryMCTSGymEnvWrapper(env)
 
     # 2. create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=True,
@@ -232,8 +235,8 @@ To create a video of the solution of the FrozenLake environment, you can use the
 ```python  
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -249,10 +252,10 @@ if __name__ == '__main__':
     env.reset()
 
     # 1. wrap the environment with the naive wrapper or a custom gymcts wrapper
-    env = NaiveSoloMCTSGymEnvWrapper(env)
+    env = DeepCopyMCTSGymEnvWrapper(env)
 
     # 2. create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=True,
@@ -413,13 +416,12 @@ The color gradient is based on the minimum and maximum values of the respective
 The visualisation is rendered in the terminal and can be limited to a certain depth of the tree.
 The default depth is 2.
 
-
 ```python
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_deterministic_wrapper import DeterministicSoloMCTSGymEnvWrapper
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_action_history_wrapper import ActionHistoryMCTSGymEnvWrapper
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -433,10 +435,10 @@ if __name__ == '__main__':
     env.reset()
 
     # wrap the environment with the naive wrapper or a custom gymcts wrapper
-    env = DeterministicSoloMCTSGymEnvWrapper(env)
+    env = ActionHistoryMCTSGymEnvWrapper(env)
 
     # create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=False,

{gymcts-1.0.0 → gymcts-1.2.0}/README.md

@@ -52,8 +52,8 @@ The NaiveSoloMCTSGymEnvWrapper can be used with non-deterministic environments,
 ```python
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -67,10 +67,10 @@ if __name__ == '__main__':
     env.reset()
 
     # 1. wrap the environment with the naive wrapper or a custom gymcts wrapper
-    env = NaiveSoloMCTSGymEnvWrapper(env)
+    env = DeepCopyMCTSGymEnvWrapper(env)
 
     # 2. create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=True,
@@ -104,13 +104,13 @@ if __name__ == '__main__':
 A minimal example of how to use the package with the FrozenLake environment and the DeterministicSoloMCTSGymEnvWrapper is provided in the following code snippet below.
 The DeterministicSoloMCTSGymEnvWrapper can be used with deterministic environments, such as the FrozenLake environment without slippery ice.
 
-The DeterministicSoloMCTSGymEnvWrapper saves the action sequence that lead to the current state in the MCTS node. 
+The DeterministicSoloMCTSGymEnvWrapper saves the action sequence that lead to the current state in the MCTS node.
 
 ```python
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_deterministic_wrapper import DeterministicSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_action_history_wrapper import ActionHistoryMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -124,10 +124,10 @@ if __name__ == '__main__':
     env.reset()
 
     # 1. wrap the environment with the wrapper
-    env = DeterministicSoloMCTSGymEnvWrapper(env)
+    env = ActionHistoryMCTSGymEnvWrapper(env)
 
     # 2. create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=True,
@@ -166,8 +166,8 @@ To create a video of the solution of the FrozenLake environment, you can use the
 ```python  
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -183,10 +183,10 @@ if __name__ == '__main__':
     env.reset()
 
     # 1. wrap the environment with the naive wrapper or a custom gymcts wrapper
-    env = NaiveSoloMCTSGymEnvWrapper(env)
+    env = DeepCopyMCTSGymEnvWrapper(env)
 
     # 2. create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=True,
@@ -347,13 +347,12 @@ The color gradient is based on the minimum and maximum values of the respective
 The visualisation is rendered in the terminal and can be limited to a certain depth of the tree.
 The default depth is 2.
 
-
 ```python
 import gymnasium as gym
 
-from gymcts.gymcts_agent import SoloMCTSAgent
-from gymcts.gymcts_deterministic_wrapper import DeterministicSoloMCTSGymEnvWrapper
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
+from gymcts.gymcts_agent import GymctsAgent
+from gymcts.gymcts_action_history_wrapper import ActionHistoryMCTSGymEnvWrapper
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
 
 from gymcts.logger import log
 
@@ -367,10 +366,10 @@ if __name__ == '__main__':
     env.reset()
 
     # wrap the environment with the naive wrapper or a custom gymcts wrapper
-    env = DeterministicSoloMCTSGymEnvWrapper(env)
+    env = ActionHistoryMCTSGymEnvWrapper(env)
 
     # create the agent
-    agent = SoloMCTSAgent(
+    agent = GymctsAgent(
         env=env,
         clear_mcts_tree_after_step=False,
         render_tree_after_step=False,

{gymcts-1.0.0 → gymcts-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gymcts"
-version = "1.0.0"
+version = "1.2.0"
 description = "A minimalistic implementation of the Monte Carlo Tree Search algorithm for planning problems fomulated as gymnaisum reinforcement learning environments."
 readme = "README.md"
 authors = [{ name = "Alexander Nasuta", email = "alexander.nasuta@wzl-iqs.rwth-aachen.de" }]
@@ -21,7 +21,7 @@ dependencies = [
     "gymnasium",
     "matplotlib<3.9",
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 
 
 [project.optional-dependencies]
@@ -53,10 +53,13 @@ dev = [
     "twine",
     "sphinx-copybutton", # for code copy buttons
     "nbsphinx", # for jupyter notebook support in sphinx
+
+    "jupytext", # converting .py examples to jupyter notebook jupytext --to notebook *.py
+    "jupyter", # for jupyter notebook kernel
 ]
 
 [project.urls]
-Homepage = "https://github.com/Alexander-Nasuta/pypitemplate"
+Homepage = "https://github.com/Alexander-Nasuta/gymcts"
 
 [tool.pytest.ini_options]
 addopts = "--cov=gymcts -p no:warnings"

{gymcts-1.0.0 → gymcts-1.2.0}/setup.cfg

@@ -7,12 +7,12 @@ platforms = unix, linux, osx, cygwin, win32
 classifiers = 
 	Programming Language :: Python :: 3
 	Programming Language :: Python :: 3 :: Only
-	Programming Language :: Python :: 3.9
+	Programming Language :: Python :: 3.11
 
 [options]
 packages = 
 	gymcts
-python_requires = >=3.9
+python_requires = >=3.11
 package_dir = 
 	=src
 zip_safe = no

{gymcts-1.0.0 → gymcts-1.2.0}/src/gymcts/colorful_console_utils.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 import matplotlib.pyplot as plt
 import numpy as np
 
@@ -103,8 +105,7 @@ def wrap_with_color_codes(s: object, /, r: int | float, g: int | float, b: int |
            f"{CEND}"
 
 
-
-def wrap_evenly_spaced_color(s: str, n_of_item:int, n_classes:int, c_map="rainbow") -> str:
+def wrap_evenly_spaced_color(s: Any, n_of_item: int, n_classes: int, c_map="rainbow") -> str:
     if s is None or n_of_item is None or n_classes is None:
         return s
 
@@ -117,7 +118,7 @@ def wrap_evenly_spaced_color(s: str, n_of_item:int, n_classes:int, c_map="rainbo
     return f"{color_asni}{s}{CEND}"
 
 
-def wrap_with_color_scale(s: str, value: float, min_val:float, max_val:float, c_map=None) -> str:
+def wrap_with_color_scale(s: str, value: float, min_val: float, max_val: float, c_map=None) -> str:
     if s is None or min_val is None or max_val is None or min_val >= max_val:
         return s
 

gymcts-1.0.0/src/gymcts/gymcts_deterministic_wrapper.py → gymcts-1.2.0/src/gymcts/gymcts_action_history_wrapper.py

@@ -7,12 +7,12 @@ import gymnasium as gym
 from gymnasium.core import WrapperActType, WrapperObsType
 from gymnasium.wrappers import RecordEpisodeStatistics
 
-from gymcts.gymcts_gym_env import SoloMCTSGymEnv
+from gymcts.gymcts_env_abc import GymctsABC
 
 from gymcts.logger import log
 
 
-class DeterministicSoloMCTSGymEnvWrapper(SoloMCTSGymEnv, gym.Wrapper):
+class ActionHistoryMCTSGymEnvWrapper(GymctsABC, gym.Wrapper):
     _terminal_flag: bool = False
     _last_reward: SupportsFloat = 0
     _step_tuple: tuple[WrapperObsType, SupportsFloat, bool, bool, dict[str, Any]] = None

{gymcts-1.0.0 → gymcts-1.2.0}/src/gymcts/gymcts_agent.py

@@ -3,27 +3,28 @@ import gymnasium as gym
 
 from typing import TypeVar, Any, SupportsFloat, Callable
 
-from gymcts.gymcts_gym_env import SoloMCTSGymEnv
-from gymcts.gymcts_naive_wrapper import NaiveSoloMCTSGymEnvWrapper
-from gymcts.gymcts_node import SoloMCTSNode
+from gymcts.gymcts_env_abc import GymctsABC
+from gymcts.gymcts_deepcopy_wrapper import DeepCopyMCTSGymEnvWrapper
+from gymcts.gymcts_node import GymctsNode
+from gymcts.gymcts_tree_plotter import _generate_mcts_tree
 
 from gymcts.logger import log
 
 TSoloMCTSNode = TypeVar("TSoloMCTSNode", bound="SoloMCTSNode")
 
 
-class SoloMCTSAgent:
+class GymctsAgent:
     render_tree_after_step: bool = False
     render_tree_max_depth: int = 2
     exclude_unvisited_nodes_from_render: bool = False
     number_of_simulations_per_step: int = 25
 
-    env: SoloMCTSGymEnv
-    search_root_node: SoloMCTSNode  # NOTE: this is not the same as the root of the tree!
+    env: GymctsABC
+    search_root_node: GymctsNode  # NOTE: this is not the same as the root of the tree!
     clear_mcts_tree_after_step: bool
 
     def __init__(self,
-                 env: SoloMCTSGymEnv,
+                 env: GymctsABC,
                  clear_mcts_tree_after_step: bool = True,
                  render_tree_after_step: bool = False,
                  render_tree_max_depth: int = 2,
@@ -43,13 +44,13 @@ class SoloMCTSAgent:
         self.env = env
         self.clear_mcts_tree_after_step = clear_mcts_tree_after_step
 
-        self.search_root_node = SoloMCTSNode(
+        self.search_root_node = GymctsNode(
             action=None,
             parent=None,
             env_reference=env,
         )
 
-    def navigate_to_leaf(self, from_node: SoloMCTSNode) -> SoloMCTSNode:
+    def navigate_to_leaf(self, from_node: GymctsNode) -> GymctsNode:
         log.debug(f"Navigate to leaf. from_node: {from_node}")
         if from_node.terminal:
             log.debug("Node is terminal. Returning from_node")
@@ -66,7 +67,7 @@ class SoloMCTSAgent:
         log.debug(f"Selected leaf node: {temp_node}")
         return temp_node
 
-    def expand_node(self, node: SoloMCTSNode) -> None:
+    def expand_node(self, node: GymctsNode) -> None:
         log.debug(f"expanding node: {node}")
         # EXPANSION STRATEGY
         # expand all children
@@ -78,7 +79,7 @@ class SoloMCTSAgent:
             self._load_state(node)
 
             obs, reward, terminal, truncated, _ = self.env.step(action)
-            child_dict[action] = SoloMCTSNode(
+            child_dict[action] = GymctsNode(
                 action=action,
                 parent=node,
                 env_reference=self.env,
@@ -110,14 +111,14 @@ class SoloMCTSAgent:
         # restore state of current node
         return action_list
 
-    def _load_state(self, node: SoloMCTSNode) -> None:
-        if isinstance(self.env, NaiveSoloMCTSGymEnvWrapper):
+    def _load_state(self, node: GymctsNode) -> None:
+        if isinstance(self.env, DeepCopyMCTSGymEnvWrapper):
             self.env = copy.deepcopy(node.state)
         else:
             self.env.load_state(node.state)
 
-    def perform_mcts_step(self, search_start_node: SoloMCTSNode = None, num_simulations: int = None,
-                          render_tree_after_step: bool = None) -> tuple[int, SoloMCTSNode]:
+    def perform_mcts_step(self, search_start_node: GymctsNode = None, num_simulations: int = None,
+                          render_tree_after_step: bool = None) -> tuple[int, GymctsNode]:
 
         if render_tree_after_step is None:
             render_tree_after_step = self.render_tree_after_step
@@ -149,7 +150,7 @@ class SoloMCTSAgent:
 
         return action, next_node
 
-    def vanilla_mcts_search(self, search_start_node: SoloMCTSNode = None, num_simulations=10) -> int:
+    def vanilla_mcts_search(self, search_start_node: GymctsNode = None, num_simulations=10) -> int:
         log.debug(f"performing one MCTS search step with {num_simulations} simulations")
         if search_start_node is None:
             search_start_node = self.search_root_node
@@ -178,7 +179,7 @@ class SoloMCTSAgent:
 
         return search_start_node.get_best_action()
 
-    def show_mcts_tree(self, start_node: SoloMCTSNode = None, tree_max_depth: int = None) -> None:
+    def show_mcts_tree(self, start_node: GymctsNode = None, tree_max_depth: int = None) -> None:
 
         if start_node is None:
             start_node = self.search_root_node
@@ -187,13 +188,17 @@ class SoloMCTSAgent:
             tree_max_depth = self.render_tree_max_depth
 
         print(start_node.__str__(colored=True, action_space_n=self.env.action_space.n))
-        for line in self._generate_mcts_tree(start_node=start_node, depth=tree_max_depth):
+        for line in _generate_mcts_tree(
+                start_node=start_node,
+                depth=tree_max_depth,
+                action_space_n=self.env.action_space.n,
+        ):
             print(line)
 
     def show_mcts_tree_from_root(self, tree_max_depth: int = None) -> None:
         self.show_mcts_tree(start_node=self.search_root_node.get_root(), tree_max_depth=tree_max_depth)
 
-    def backpropagation(self, node: SoloMCTSNode, episode_return: float) -> None:
+    def backpropagation(self, node: GymctsNode, episode_return: float) -> None:
         log.debug(f"performing backpropagation from leaf node: {node}")
         while not node.is_root():
             # node.mean_value = ((node.mean_value * node.visit_count) + episode_return) / (node.visit_count + 1)
@@ -209,53 +214,4 @@ class SoloMCTSAgent:
         node.max_value = max(node.max_value, episode_return)
         node.min_value = min(node.min_value, episode_return)
 
-    def _generate_mcts_tree(self, start_node: SoloMCTSNode = None, prefix: str = None, depth: int = None) -> list[str]:
 
-        if prefix is None:
-            prefix = ""
-        import gymcts.colorful_console_utils as ccu
-
-        if start_node is None:
-            start_node = self.search_root_node
-
-        # prefix components:
-        space = '    '
-        branch = '│   '
-        # pointers:
-        tee = '├── '
-        last = '└── '
-
-        contents = start_node.children.values() if start_node.children is not None else []
-        if self.exclude_unvisited_nodes_from_render:
-            contents = [node for node in contents if node.visit_count > 0]
-        # contents each get pointers that are ├── with a final └── :
-        # pointers = [tee] * (len(contents) - 1) + [last]
-        pointers = [tee for _ in range(len(contents) - 1)] + [last]
-
-        for pointer, current_node in zip(pointers, contents):
-            n_item = current_node.parent.action if current_node.parent is not None else 0
-            n_classes = self.env.action_space.n
-
-            pointer = ccu.wrap_evenly_spaced_color(
-                s=pointer,
-                n_of_item=n_item,
-                n_classes=n_classes,
-            )
-
-            yield prefix + pointer + f"{current_node.__str__(colored=True, action_space_n=n_classes)}"
-            if current_node.children and len(current_node.children):  # extend the prefix and recurse:
-                # extension = branch if pointer == tee else space
-                extension = branch if tee in pointer else space
-                # i.e. space because last, └── , above so no more |
-                extension = ccu.wrap_evenly_spaced_color(
-                    s=extension,
-                    n_of_item=n_item,
-                    n_classes=n_classes,
-                )
-                if depth is not None and depth <= 0:
-                    continue
-                yield from self._generate_mcts_tree(
-                    current_node,
-                    prefix=prefix + extension,
-                    depth=depth - 1 if depth is not None else None
-                )

gymcts-1.0.0/src/gymcts/gymcts_naive_wrapper.py → gymcts-1.2.0/src/gymcts/gymcts_deepcopy_wrapper.py

@@ -7,12 +7,12 @@ import gymnasium as gym
 from gymnasium.core import WrapperActType, WrapperObsType
 from gymnasium.wrappers import RecordEpisodeStatistics
 
-from gymcts.gymcts_gym_env import SoloMCTSGymEnv
+from gymcts.gymcts_env_abc import GymctsABC
 
 from gymcts.logger import log
 
 
-class NaiveSoloMCTSGymEnvWrapper(SoloMCTSGymEnv, gym.Wrapper):
+class DeepCopyMCTSGymEnvWrapper(GymctsABC, gym.Wrapper):
 
 
     _terminal_flag:bool = False