co2114 2026.1.1__tar.gz → 2026.1.2__tar.gz

{co2114-2026.1.1 → co2114-2026.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2114
-Version: 2026.1.1
+Version: 2026.1.2
 Summary: codebase for co2114
 Author: wil ward
 Requires-Python: >=3.12

{co2114-2026.1.1 → co2114-2026.1.2}/co2114/agent/environment.py

@@ -66,7 +66,7 @@ class BaseEnvironment:
 
         for i in range(steps):
             self.__counter += 1
-            if self.is_done:  # print terination message and exit
+            if self.is_done:  # print termination message and exit
                 print(f"{self}: Simulation complete after {i} of {steps} iterations.")
                 return
             self.step() # else iterate one step

{co2114-2026.1.1 → co2114-2026.1.2}/co2114/optimisation/planning.py

@@ -4,7 +4,12 @@ from ..agent.environment import GraphicEnvironment
 from ..search.util import manhattan
 import random
 
-PRESET_STATES = {
+from typing import override
+
+Location = tuple[int, int]
+State = None | dict[str, dict[House | Hospital, Location] | dict[str, int]]
+Numeric = int | float
+PRESET_STATES: dict[str, dict[str, list[Location] | int]] = {
     "empty": None,
     '0': {
         "hospitals": [(2, 4)],
@@ -41,35 +46,99 @@ PRESET_STATES = {
 
 
 class HospitalOptimiser(Optimiser, UtilityBasedAgent):
-    def explore(self, state):
+    """ Hospital Optimiser Agent"""
+    def explore(self, state:State) -> None:
+        """ Move hospitals to new locations in state
+        
+        :param state: new state with hospital locations
+        """
         if not state: return
         print(f"{self}: exploring state\n    {state['hospitals']}")
         for hospital, loc in state["hospitals"].items():
             hospital.location = loc
 
-    def utility(self, state):
-        """ calculate distance from each hospital to houses """
+    @override
+    def utility(self, state:State) -> Numeric:
+        """ Calculate utility of possible state by calculating distance
+            of each hospital to houses
+        
+        Returns negative total distance to be minimised.
+
+        :param state: current state with hospital and house locations
+        :return: negative total distance
+        """
         obj = 0
-        houses, hospitals = state["houses"], state["hospitals"]
-        for house in houses:
-            dist_to_nearest = infinity   # very big
-            for hospital in hospitals:
-                dist = manhattan(
-                    houses[house],
-                    hospitals[hospital])
-                if dist < dist_to_nearest:
-                    dist_to_nearest = dist
-            obj += dist_to_nearest
+        houses: dict[House, Location] = state["houses"]  # type: ignore
+        hospitals: dict[Hospital, Location] = state["hospitals"]  # type: ignore
+
+        for house in houses: # iterate over houses
+            dist_to_nearest_hospital = infinity   # very big
+
+            for hospital in hospitals:  # iterate over hospitals
+                house_loc    = houses[house]
+                hospital_loc = hospitals[hospital]
+
+                dist = manhattan(house_loc, hospital_loc)
+
+                # calculate closest distance
+                if dist < dist_to_nearest_hospital:
+                    dist_to_nearest_hospital = dist
+
+            obj += dist_to_nearest_hospital # add distance for this house
         return -obj
 
 
 class HospitalPlacement(GraphicEnvironment):
-    def __init__(self, init=None, *args, **kwargs):
+    """ Hospital Placement Environment
+     
+    Allows placement of hospitals and houses on a grid
+    
+    Has a state consisting of hospital and house locations and bounds of the environment
+    """
+    def __init__(self,
+                 init:dict[str, list[Location] | int] | None = None,
+                 *args,
+                 **kwargs) -> None:
+        """ Constroctor for HospitalPlacement environment
+        
+        :param init: initial state dictionary with hospital and house locations and height/width of environment
+        :param args: additional args for GraphicEnvironment
+        :param kwargs: additional kwargs for GraphicEnvironment
+        """
         super().__init__(*args, **kwargs)
         self.initialise_state(init)
+ 
+
+    def initialise_state(self,
+                         state_dict: dict[str, list[Location] | int]) -> None:
+        """ Initialise environment state from state dictionary 
+        
+        :param state_dict: state dictionary with hospital and house locations and height/width of environment
+        """
+        if state_dict is None: return  # empty state
+
+        if "height" in state_dict:
+            self.height = state_dict["height"]
+
+        if "width" in state_dict:
+            self.width = state_dict["width"]
+
+        self.size = self.width, self.height
+
+        if "hospitals" in state_dict:
+            for loc in state_dict["hospitals"]:
+                self.add_thing(Hospital(), location=loc)
+
+        for loc in state_dict["houses"]:
+            self.add_thing(House(), location=loc)
+
 
     @property
-    def state(self):
+    def state(self) -> State:
+        """ Attribute returning current environment state 
+        
+        :return: current state with hospital and house locations and bounds of environment
+        """
         return {
             "hospitals": {
                 thing: thing.location
@@ -85,7 +154,12 @@ class HospitalPlacement(GraphicEnvironment):
         }
 
     @property
-    def neighbours(self):
+    def neighbours(self) -> list[State]:
+        """ Generate neighbouring states by moving each hospital
+            in each direction by one unit if possible.
+
+        :return: list of neighbouring states
+        """
         neighbours = []
         for i, hospital in enumerate(self.state["hospitals"]):
             location = hospital.location
@@ -97,17 +171,31 @@ class HospitalPlacement(GraphicEnvironment):
                     neighbours.append(candidate)
         return neighbours
 
-    def is_inbounds(self, location):
+    def is_inbounds(self, location:Location) -> bool:
+        """ Checks if location is in bounds and unoccupied
+        
+        :return bool: True if location is in bounds and unoccupied
+        """
         if not super().is_inbounds(location):
             return False
         return len(self.things_at(location)) == 0
 
-    def add_agent(self, agent:Agent):
+    @override
+    def add_agent(self, agent:Agent) -> None:
+        """ Add agent to environment, overrides GraphicEnvironment method as agent has no location.
+        
+        :param agent: agent to add
+        """
         if not isinstance(agent, Agent):
             raise TypeError(f"{self}: {agent} is not an Agent.")
         self.agents.add(agent)
 
-    def add_thing_randomly(self, thing):
+    @override
+    def add_thing_randomly(self, thing:things.Thing) -> None:
+        """ Add thing to random unoccupied location in environment
+        
+        :param thing: thing to add
+        """
         x = random.randint(self.x_start, self.x_end-1)
         y = random.randint(self.y_start, self.y_end-1)
         lim, count = 10, 0
@@ -120,35 +208,31 @@ class HospitalPlacement(GraphicEnvironment):
             y = random.randint(self.y_start, self.y_end-1)
         self.add_thing(thing, (x,y))
 
-
-    def initialise_state(self, state_dict):
-        if state_dict is None:
-            return
-        if "height" in state_dict:
-            self.height = state_dict["height"]
-        if "width" in state_dict:
-            self.width = state_dict["width"]
-        self.size = self.width, self.height
-        if "hospitals" in state_dict:
-            for loc in state_dict["hospitals"]:
-                self.add_thing(Hospital(), location=loc)
-        for loc in state_dict["houses"]:
-            self.add_thing(House(), location=loc)
-        
-
     @property
-    def is_done(self):
+    def is_done(self) -> bool:
+        """ Definition of when environment is done """
         if len(self.agents) == 0: return True  # if there are no agents
         return hasattr(self, "success") and self.success
 
-    def percept(self, agent):
+    @override
+    def percept(self, agent:Agent) -> tuple[State, list[State]]:
+        """ Percept for agent in environment
+        
+        :return tuple: current state and neighbouring states
+        """
         return self.state, self.neighbours
 
-    def execute_action(self, agent, action):
-        """ Execute an action """
+    @override
+    def execute_action(self,
+                       agent:HospitalOptimiser,action:tuple[str,State]) -> None:
+        """ Execute an action 
+        
+        :param agent: agent performing action
+        :param action: action to execute, tuple of command and state. possible commands are "done" and "explore"
+        """
         command, state = action
         match command:
-            case "done":
+            case "done":  # optimisation complete
                 if state:
                     agent.explore(state)
                 self.success = True

{co2114-2026.1.1 → co2114-2026.1.2}/co2114/optimisation/things.py

@@ -2,17 +2,26 @@ from ..search import things
 
 from ..util.fonts import platform
 
+from typing import override
+
+# Re-export relevant classes from things module
 Agent = things.Agent
 UtilityBasedAgent = things.UtilityBasedAgent
 
 class Hospital(things.Thing):
+    @override
     def __repr__(self):
+        """ String representation of a Hospital. """
         return "🏥" if platform != "darwin" else "+"
 
 class House(things.Thing):
+    @override
     def __repr__(self):
+        """ String representation of a House. """
         return "🏠" if platform != "darwin" else "^"
 
 class Optimiser(things.Agent):
+    @override
     def __repr__(self):
+        """ String representation of an Optimiser. """
         return "📈"

{co2114-2026.1.1 → co2114-2026.1.2}/co2114.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: co2114
-Version: 2026.1.1
+Version: 2026.1.2
 Summary: codebase for co2114
 Author: wil ward
 Requires-Python: >=3.12

{co2114-2026.1.1 → co2114-2026.1.2}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup
 
 setup(
     name="co2114",
-    version="2026.1.1",
+    version="2026.1.2",
     description="codebase for co2114",
     author="wil ward",
     python_requires=">=3.12",