Rename MoveGenerator agent hooks to save/restore_proposal_state and copy_state_from

Author: soheilshahrouz

vpr/src/place/move_generators/move_generator.h

@@ -147,22 +147,24 @@ class MoveGenerator {
     virtual void process_outcome(double /*reward*/, e_reward_function /*reward_fun*/) {}
 
     /**
-     * @brief Returns an identifier for the internal decision ("arm") behind the
-     * most recent propose_move(). Only meaningful for RL-agent based generators.
-     * Capturing it after each proposal and restoring it before the matching
-     * outcome lets a caller interleave proposals and still replay outcomes in order.
+     * @brief Returns a token describing the generator's state after the most
+     * recent propose_move(). Only needed when outcomes are not reported right
+     * after each proposal. A caller can record the token and reward of each
+     * proposal and apply them later in a batch. Stateless generators return 0.
      */
-    virtual size_t get_last_action() const { return 0; }
+    virtual size_t save_proposal_state() const { return 0; }
 
-    /// @brief Restores the action identifier captured by get_last_action().
-    virtual void set_last_action(size_t /*action*/) {}
+    /**
+     * @brief Restores a token from save_proposal_state() so the next
+     * process_outcome() is credited to that proposal.
+     */
+    virtual void restore_proposal_state(size_t /*state*/) {}
 
     /**
-     * @brief Copies the RL agent's Q-values from `other`, which must be
-     * a generator of the same concrete type, so a replica proposes exactly
-     * what the master would.
+     * @brief Copies the state from `other`, which must be of the same
+     * concrete type, so this generator proposes what `other` would.
      */
-    virtual void sync_state_from(const MoveGenerator& /*other*/) {}
+    virtual void copy_state_from(const MoveGenerator& /*other*/) {}
 
     /**
      * @brief Calculates the agent's reward and the total process outcome

vpr/src/place/move_generators/simpleRL_move_generator.cpp

@@ -31,11 +31,11 @@ void SimpleRLMoveGenerator::process_outcome(double reward, e_reward_function rew
     karmed_bandit_agent->process_outcome(reward, reward_fun);
 }
 
-void SimpleRLMoveGenerator::sync_state_from(const MoveGenerator& other) {
+void SimpleRLMoveGenerator::copy_state_from(const MoveGenerator& other) {
     // Callers always pass a generator of the same concrete type,
     // and this runs once per sync rather than per move, so the cost is negligible.
     const SimpleRLMoveGenerator* other_rl = dynamic_cast<const SimpleRLMoveGenerator*>(&other);
-    VTR_ASSERT_MSG(other_rl != nullptr, "Can only sync agent state from another SimpleRLMoveGenerator.");
+    VTR_ASSERT_MSG(other_rl != nullptr, "Can only copy agent state from another SimpleRLMoveGenerator.");
     karmed_bandit_agent->copy_state_from(*other_rl->karmed_bandit_agent);
 }
 

vpr/src/place/move_generators/simpleRL_move_generator.h

@@ -59,7 +59,7 @@ class KArmedBanditAgent {
     size_t last_action() const { return last_action_; }
 
     /// @brief Overrides the action credited by the next process_outcome() call.
-    ///        See MoveGenerator::get_last_action() for the intended usage.
+    ///        See MoveGenerator::save_proposal_state() for the intended usage.
     void set_last_action(size_t action) { last_action_ = action; }
 
     /// @brief Copies the learned state (Q-values, action counts, step size) from `other`.
@@ -264,14 +264,14 @@ class SimpleRLMoveGenerator : public MoveGenerator {
     // Receives feedback about the outcome of the previously proposed move
     void process_outcome(double reward, e_reward_function reward_fun) override;
 
-    /// @brief Returns/overrides the agent action behind the most recent proposal.
-    ///        See MoveGenerator::get_last_action() for the intended usage.
-    size_t get_last_action() const override { return karmed_bandit_agent->last_action(); }
-    void set_last_action(size_t action) override { karmed_bandit_agent->set_last_action(action); }
+    /// @brief Saves/restores the agent action behind the most recent proposal.
+    ///        See MoveGenerator::save_proposal_state() for the intended usage.
+    size_t save_proposal_state() const override { return karmed_bandit_agent->last_action(); }
+    void restore_proposal_state(size_t state) override { karmed_bandit_agent->set_last_action(state); }
 
     /// @brief Copies the agent state from another SimpleRLMoveGenerator.
-    ///        See MoveGenerator::sync_state_from() for the intended usage.
-    void sync_state_from(const MoveGenerator& other) override;
+    ///        See MoveGenerator::copy_state_from() for the intended usage.
+    void copy_state_from(const MoveGenerator& other) override;
 };
 
 template<class T, class>