simonbb 0.0.6__tar.gz → 0.0.7__tar.gz

{simonbb-0.0.6 → simonbb-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simonbb
-Version: 0.0.6
+Version: 0.0.7
 Summary: A small package to facilitate teaching AI courses at business schools
 Project-URL: Homepage, https://simonbb.com
 Author-email: Huaxia Rui <huaxia.rui@simon.rochester.edu>
@@ -18,6 +18,7 @@ Requires-Dist: langchain~=1.2.13
 Requires-Dist: langgraph~=1.1.3
 Requires-Dist: matplotlib~=3.10.8
 Requires-Dist: numpy~=2.4.0
+Requires-Dist: opencv-python~=5.0.0.93
 Requires-Dist: pytorch-ignite~=0.5.4
 Requires-Dist: pyyaml~=6.0.3
 Requires-Dist: ray~=2.56.0

{simonbb-0.0.6 → simonbb-0.0.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simonbb"
-version = "0.0.6"
+version = "0.0.7"
 authors = [
 	{ name="Huaxia Rui", email="huaxia.rui@simon.rochester.edu" },
 ]
@@ -34,6 +34,7 @@ dependencies = [
 	"pytorch-ignite~=0.5.4",
 	"stable_baselines3~=2.9.0",
 	"ray~=2.56.0",
+	"opencv-python~=5.0.0.93",
 	"pyyaml~=6.0.3"
 ]
 [project.urls]

{simonbb-0.0.6 → simonbb-0.0.7}/src/simonbb/cis433/experience.py

@@ -25,9 +25,9 @@ class Experience:
 
 class ExperienceSource:
     """
-    Simple n-step experience source using single or multiple environments
+    n-step experience source using single or multiple environments
 
-    Every experience contains n list of Experience entries
+    Every experience contains a list of n Experience entries
     """
     Item = tt.Tuple[Experience, ...]
 
@@ -39,7 +39,7 @@ class ExperienceSource:
         :param env: environment or list of environments to be used
         :param agent: callable to convert batch of states into actions to take
         :param steps_count: count of steps to track for every experience chain
-        :param steps_delta: how many steps to do between experience items
+        :param steps_delta: how many steps to do between subjectory emissions
         :param env_seed: seed to be used in Env.reset() call
         """
         assert steps_count >= 1
@@ -54,7 +54,7 @@ class ExperienceSource:
         self.agent = agent
         self.steps_count = steps_count
         self.steps_delta = steps_delta
-        self.total_rewards = []
+        self.total_rewards = [] # simple sum of immediate rewards, without discounting
         self.total_steps = []
         self.agent_states = [agent.initial_state() for _ in self.pool]
         self.env_seed = env_seed
@@ -67,7 +67,7 @@ class ExperienceSource:
             else:
                 obs, _ = env.reset()
             states.append(obs)
-            histories.append(deque(maxlen=self.steps_count))
+            histories.append( deque(maxlen=self.steps_count) ) # Note the max length of the double-ended queue
             cur_rewards.append(0.0)
             cur_steps.append(0)
 
@@ -81,17 +81,16 @@ class ExperienceSource:
                 next_state, r, is_done, is_tr, _ = env.step(action)
                 cur_rewards[idx] += r
                 cur_steps[idx] += 1
-                history.append(Experience(state=state, action=action, reward=r, done_trunc=is_done or is_tr))
+                history.append(Experience(state=state, action=action, reward=r, done_trunc=is_done or is_tr)) # push out the oldest step once deque is full (i.e., steps_count reached)
                 if len(history) == self.steps_count and iter_idx % self.steps_delta == 0:
                     yield tuple(history)
                 states[idx] = next_state
                 if is_done or is_tr:
-                    # generate tail of history
                     if 0 < len(history) < self.steps_count:
                         yield tuple(history)
                     while len(history) > 1:
                         history.popleft()
-                        yield tuple(history)
+                        yield tuple(history) # a sub-trajectory of the history
                     self.total_rewards.append(cur_rewards[idx])
                     self.total_steps.append(cur_steps[idx])
                     cur_rewards[idx] = 0.0
@@ -104,13 +103,15 @@ class ExperienceSource:
                     history.clear()
             iter_idx += 1
 
+
+    # pop_total_rewards() returns a list of total rewards (without discounting), one per env, after an episode ends
     def pop_total_rewards(self) -> tt.List[float]:
         r = self.total_rewards
         if r:
             self.total_rewards = []
             self.total_steps = []
         return r
-
+    # pop_total_rewards() returns a list of total rewards (without discounting) and number of steps, one per env, after an episode ends
     def pop_rewards_steps(self) -> tt.List[tt.Tuple[float, int]]:
         res = list(zip(self.total_rewards, self.total_steps))
         if res:
@@ -148,12 +149,54 @@ class ExperienceSourceFirstLast(ExperienceSource):
             else:
                 last_state = exp[-1].state
                 elems = exp[:-1]
-            total_reward = 0.0
+            discounted_total_reward = 0.0
             for e in reversed(elems):
-                total_reward *= self.gamma
-                total_reward += e.reward
-            yield ExperienceFirstLast(state=exp[0].state, action=exp[0].action,
-                                      reward=total_reward, last_state=last_state)
+                discounted_total_reward *= self.gamma
+                discounted_total_reward += e.reward
+            yield ExperienceFirstLast(state=exp[0].state, action=exp[0].action, reward=discounted_total_reward, last_state=last_state)
+
+
+
+class ExperienceReplayBuffer:
+    def __init__(self, experience_source: tt.Optional[ExperienceSource], buffer_size: int):
+        self.experience_source_iter = None if experience_source is None else iter(experience_source)
+        self.buffer: tt.List[ExperienceSource.Item] = []
+        self.capacity = buffer_size
+        self.pos = 0
+
+    def __len__(self):
+        return len(self.buffer)
+
+    def __iter__(self) -> tt.Iterator[ExperienceSource.Item]:
+        return iter(self.buffer)
+
+    def sample(self, batch_size: int) -> tt.List[ExperienceSource.Item]:
+        """
+        Get one random batch from experience replay
+        :param batch_size: size of the batch to sample
+        :return: list of experience entries
+        """
+        if len(self.buffer) <= batch_size:
+            return self.buffer
+        # Warning: replace=False makes random.choice O(n)
+        keys = np.random.choice(len(self.buffer), batch_size, replace=True)
+        return [self.buffer[key] for key in keys]
+
+    def _add(self, sample: ExperienceSource.Item):
+        if len(self.buffer) < self.capacity:
+            self.buffer.append(sample)
+        else:
+            self.buffer[self.pos] = sample
+        self.pos = (self.pos + 1) % self.capacity
+
+    def populate(self, samples: int):
+        """
+        Populates samples into the buffer
+        :param samples: how many samples to populate
+        """
+        for _ in range(samples):
+            entry = next(self.experience_source_iter)
+            self._add(entry)
 
 
 def vector_rewards(rewards: tt.Deque[np.ndarray], dones: tt.Deque[np.ndarray], gamma: float) -> np.ndarray:
@@ -406,47 +449,6 @@ class ExperienceSourceBuffer:
             yield self.buffer[episode][ofs:ofs+self.steps_count]
 
 
-class ExperienceReplayBuffer:
-    def __init__(self, experience_source: tt.Optional[ExperienceSource], buffer_size: int):
-        self.experience_source_iter = None if experience_source is None else iter(experience_source)
-        self.buffer: tt.List[ExperienceSource.Item] = []
-        self.capacity = buffer_size
-        self.pos = 0
-
-    def __len__(self):
-        return len(self.buffer)
-
-    def __iter__(self) -> tt.Iterator[ExperienceSource.Item]:
-        return iter(self.buffer)
-
-    def sample(self, batch_size: int) -> tt.List[ExperienceSource.Item]:
-        """
-        Get one random batch from experience replay
-        :param batch_size: size of the batch to sample
-        :return: list of experience entries
-        """
-        if len(self.buffer) <= batch_size:
-            return self.buffer
-        # Warning: replace=False makes random.choice O(n)
-        keys = np.random.choice(len(self.buffer), batch_size, replace=True)
-        return [self.buffer[key] for key in keys]
-
-    def _add(self, sample: ExperienceSource.Item):
-        if len(self.buffer) < self.capacity:
-            self.buffer.append(sample)
-        else:
-            self.buffer[self.pos] = sample
-        self.pos = (self.pos + 1) % self.capacity
-
-    def populate(self, samples: int):
-        """
-        Populates samples into the buffer
-        :param samples: how many samples to populate
-        """
-        for _ in range(samples):
-            entry = next(self.experience_source_iter)
-            self._add(entry)
-
 
 class PrioReplayBufferNaive:
     def __init__(self, exp_source, buf_size, prob_alpha=0.6):

{simonbb-0.0.6 → simonbb-0.0.7}/src/simonbb/cis433/ignite.py

@@ -13,39 +13,38 @@ class EpisodeEvents(EventEnum):
 
 
 class EndOfEpisodeHandler:
-    def __init__(self, exp_source: ExperienceSource, alpha: float = 0.98,
-                 bound_avg_reward: Optional[float] = None,
-                 subsample_end_of_episode: Optional[int] = None):
+    def __init__(self, exp_source: ExperienceSource, alpha: float = 0.98, bound_avg_reward: Optional[float] = None, period: Optional[int] = None):
         """
-        Construct end-of-episode event handler
+        This end-of-episode event handler, triggered by Events.ITERATION_COMPLETED, fires an EPISODE_COMPLETED event for every episode, or every {period} number of episodes
         :param exp_source: experience source to use
         :param alpha: smoothing alpha param
         :param bound_avg_reward: optional boundary for average reward
-        :param subsample_end_of_episode: if given, end of episode event will be subsampled by this amount
+        :param period: if given, end of episode event fire once every {period} episodes
         """
         self._exp_source = exp_source
         self._alpha = alpha
         self._bound_avg_reward = bound_avg_reward
         self._best_avg_reward = None
-        self._subsample_end_of_episode = subsample_end_of_episode
+        self._period = period
 
     def attach(self, engine: Engine):
-        engine.add_event_handler(Events.ITERATION_COMPLETED, self)
-        engine.register_events(*EpisodeEvents)
+        engine.add_event_handler( Events.ITERATION_COMPLETED, self ) # invoke EndOfEpisodeHandler() instance whenever an iteration (consisting of multiple episodes) is completed
+        engine.register_events( *EpisodeEvents )
         State.event_to_attr[EpisodeEvents.EPISODE_COMPLETED] = "episode"
         State.event_to_attr[EpisodeEvents.BOUND_REWARD_REACHED] = "episode"
         State.event_to_attr[EpisodeEvents.BEST_REWARD_REACHED] = "episode"
 
     def __call__(self, engine: Engine):
+        # pop_rewards_steps() returns a list of (total rewards, steps) of newly completed episodes since the last call of pop_rewards_steps().
         for reward, steps in self._exp_source.pop_rewards_steps():
             engine.state.episode = getattr(engine.state, "episode", 0) + 1
-            engine.state.episode_reward = reward
+            engine.state.episode_reward = reward # sum of immediate rewards of all steps during the episode, without discounting
             engine.state.episode_steps = steps
             engine.state.metrics['reward'] = reward
             engine.state.metrics['steps'] = steps
             self._update_smoothed_metrics(engine, reward, steps)
-            if self._subsample_end_of_episode is None or engine.state.episode % self._subsample_end_of_episode == 0:
-                engine.fire_event(EpisodeEvents.EPISODE_COMPLETED)
+            if self._period is None or engine.state.episode % self._period == 0:
+                engine.fire_event( EpisodeEvents.EPISODE_COMPLETED )
             if self._bound_avg_reward is not None and engine.state.metrics['avg_reward'] >= self._bound_avg_reward:
                 engine.fire_event(EpisodeEvents.BOUND_REWARD_REACHED)
             if self._best_avg_reward is None:
@@ -110,13 +109,10 @@ class PeriodEvents(EventEnum):
     ITERS_10000_COMPLETED = "iterations_10000_completed"
     ITERS_100000_COMPLETED = "iterations_100000_completed"
 
-
 class PeriodicEvents:
     """
-    The same as CustomPeriodicEvent from ignite.contrib, but use true amount of iterations,
-    which is good for TensorBoard
+    The same as CustomPeriodicEvent from ignite.contrib, but use true amount of iterations, which is good for TensorBoard
     """
-
     INTERVAL_TO_EVENT = {
         10: PeriodEvents.ITERS_10_COMPLETED,
         100: PeriodEvents.ITERS_100_COMPLETED,