modified abstract submodel to be a little bit more general

Author: IreneTerrone

examples/cpp/beesandflowers/src/main.cu

@@ -213,7 +213,7 @@ void define_model(ModelDescription &model) {
     flamegpu::stockAgent::submodels::SingleAgentDiscreteMovement move_sub_logic;
 
     // Initialize the submodel
-    auto move_sub_desc = move_sub_logic.addSingleAgentDiscreteMovementSubmodel(model, ENV_DIM, ENV_DIM);
+    move_sub_logic.addSingleAgentDiscreteMovementSubmodel(model, ENV_DIM, ENV_DIM);
 
     // Bind parent agents to submodel
     move_sub_logic.setMovingAgent("bee",
@@ -250,7 +250,7 @@ void define_model(ModelDescription &model) {
     l0.addAgentFunction(calculate_priority);
 
     LayerDescription l1 = model.newLayer();
-    l1.addSubModel(move_sub_desc);
+    l1.addSubModel(move_sub_logic.getSubModelDescription());
 
     LayerDescription l2 = model.newLayer();
     l2.addAgentFunction(update_hunger_wait);

examples/cpp/sugarscapeSubModelAPI/src/main.cu

@@ -131,7 +131,7 @@ int main(int argc, const char ** argv) {
      * Submodel Configuration
      */
     flamegpu::stockAgent::submodels::SingleAgentDiscreteMovement move_sub_logic;
-    auto move_sub_desc = move_sub_logic.addSingleAgentDiscreteMovementSubmodel(model, GRID_WIDTH, GRID_HEIGHT);
+    move_sub_logic.addSingleAgentDiscreteMovementSubmodel(model, GRID_WIDTH, GRID_HEIGHT);
 
     // Bind Bug to the submodel's moving agent
     move_sub_logic.setMovingAgent("bug",
@@ -167,7 +167,7 @@ int main(int argc, const char ** argv) {
     sugar_cell.newFunction("growback", growback);
 
     //  Layer 1: Movement
-    model.newLayer().addSubModel(move_sub_desc);
+    model.newLayer().addSubModel(move_sub_logic.getSubModelDescription());
 
     // Layer 2: Life logic (Metabolism and Growback can happen in parallel)
     {

include/flamegpu/stockAgent/subModels/AbstractSubmodels.h

@@ -1,6 +1,7 @@
 #ifndef INCLUDE_FLAMEGPU_STOCKAGENT_SUBMODELS_ABSTRACTSUBMODELS_H_
 #define INCLUDE_FLAMEGPU_STOCKAGENT_SUBMODELS_ABSTRACTSUBMODELS_H_
 
+#include <string>
 #include "flamegpu/flamegpu.h"
 
 namespace flamegpu {
@@ -13,8 +14,23 @@ namespace submodels {
      */
     class AbstractSubmodel {
      public:
-        virtual void validate() = 0;
         virtual ~AbstractSubmodel() = default;
+
+        /**
+         * Returns the underlying FLAME GPU SubModelDescription.
+         * Throws if the submodel hasn't been initialized/added to a model yet.
+         */
+        virtual flamegpu::SubModelDescription getSubModelDescription() const = 0;
+
+        /**
+         * Validates that all required agents and variables have been mapped.
+         */
+        virtual void validate() = 0;
+
+        /**
+         * Returns the name of the submodel instance.
+         */
+        virtual std::string getName() const = 0;
     };
 
 

include/flamegpu/stockAgent/subModels/SingleAgentDiscreteMovement.h

@@ -4,6 +4,7 @@
 #include <map>
 #include <string>
 #include <memory>
+#include <optional>
 
 #include "AbstractSubmodels.h"
 
@@ -50,12 +51,15 @@ class SingleAgentDiscreteMovement : public AbstractSubmodel {
                   const std::map<std::string, std::string>& state_map = {},
                   bool auto_map = false);
 
+    flamegpu::SubModelDescription getSubModelDescription() const override;
+
     void validate() override;
 
+    std::string getName() const override;
+
  private:
-    // Internal pointer allows SingleAgentDiscreteMovement to be default-constructible
-    std::unique_ptr<flamegpu::SubModelDescription> smm;
-    bool is_initialized = false;
+    // SubModelDescription is a proxy. We use optional to allow late initialization without unique_ptr.
+    std::optional<flamegpu::SubModelDescription> smm;
 
     // Internal setup methods
     void setMessages(flamegpu::AgentDescription &movingAgent, flamegpu::AgentDescription &envAgent, int ENV_SIZE_X, int ENV_SIZE_Y);

src/flamegpu/stockAgent/subModels/SingleAgentDiscreteMovement.cu

@@ -293,9 +293,8 @@ flamegpu::SubModelDescription SingleAgentDiscreteMovement::addSingleAgentDiscret
     sub_model_move.addInitFunction(initial_occupancy_sync);
     sub_model_move.addExitCondition(move_exit_condition);
 
-    this->smm = std::make_unique<SubModelDescription>(model.newSubModel("MovementInstance", sub_model_move));
+    this->smm = model.newSubModel("MovementInstance", sub_model_move);
     this->smm->setMaxSteps(5);
-    this->is_initialized = true;
 
     return *(this->smm);
 }
@@ -304,7 +303,7 @@ void SingleAgentDiscreteMovement::setMovingAgent(const string& parent_name,
                            const map<string, string>& var_map,
                            const map<string, string>& state_map,
                            bool auto_map) {
-    if (!is_initialized) {
+    if (!smm.has_value()) {
         throw exception::InvalidSubModel("SingleAgentDiscreteMovement submodel was not initialized. Call addSingleAgentDiscreteMovementSubmodel() first.");
     }
     auto agent_map = this->smm->bindAgent(INTERNAL_MOVING_AGENT_NAME, parent_name, auto_map, auto_map);
@@ -316,33 +315,44 @@ void SingleAgentDiscreteMovement::setEnvironmentAgent(const string& parent_name,
                            const map<string, string>& var_map,
                            const map<string, string>& state_map,
                            bool auto_map) {
-    if (!is_initialized) {
+    if (!smm.has_value()) {
         throw exception::InvalidSubModel("SingleAgentDiscreteMovement submodel was not initialized. Call addSingleAgentDiscreteMovementSubmodel() first.");
     }
     auto agent_map = this->smm->bindAgent(INTERNAL_ENV_AGENT_NAME, parent_name, auto_map, auto_map);
     for (auto const& [internal_var, parent_var] : var_map) { agent_map.mapVariable(internal_var, parent_var); }
     for (auto const& [internal_state, parent_state] : state_map) { agent_map.mapState(internal_state, parent_state); }
 }
 
-void SingleAgentDiscreteMovement::defineMessageSubmodule(ModelDescription &smm, int ENV_SIZE_X, int ENV_SIZE_Y) {
-    auto m1 = smm.newMessage<MessageArray2D>("cell_status");
+flamegpu::SubModelDescription SingleAgentDiscreteMovement::getSubModelDescription() const {
+    if (!smm.has_value()) {
+        throw exception::InvalidSubModel("SingleAgentDiscreteMovement submodel was not initialized.");
+    }
+    return *smm;
+}
+
+std::string SingleAgentDiscreteMovement::getName() const {
+    return "SingleAgentDiscreteMovement";
+}
+
+void SingleAgentDiscreteMovement::defineMessageSubmodule(ModelDescription &smm_desc, int ENV_SIZE_X, int ENV_SIZE_Y) {
+    auto m1 = smm_desc.newMessage<MessageArray2D>("cell_status");
     m1.newVariable<float>("cell_score");
     m1.newVariable<int>("is_occupied");
     m1.setDimensions(ENV_SIZE_X, ENV_SIZE_Y);
 
-    auto m2 = smm.newMessage<MessageArray2D>("move_requests");
+    auto m2 = smm_desc.newMessage<MessageArray2D>("move_requests");
     m2.newVariable<id_t>("requester_id");
     m2.newVariable<int>("target_x");
     m2.newVariable<int>("target_y");
     m2.newVariable<float>("priority");
     m2.setDimensions(ENV_SIZE_X, ENV_SIZE_Y);
 
-    auto m3 = smm.newMessage<MessageArray2D>("move_responses");
+    auto m3 = smm_desc.newMessage<MessageArray2D>("move_responses");
     m3.newVariable<id_t>("winner_id");
     m3.newVariable<float>("cell_score");
     m3.setDimensions(ENV_SIZE_X, ENV_SIZE_Y);
 
-    auto m4 = smm.newMessage<MessageArray2D>("new_locations");
+    auto m4 = smm_desc.newMessage<MessageArray2D>("new_locations");
     m4.newVariable<id_t>("moving_agent_id");
     m4.setDimensions(ENV_SIZE_X, ENV_SIZE_Y);
 }
@@ -366,16 +376,16 @@ void SingleAgentDiscreteMovement::setMessages(AgentDescription &movingAgent, Age
     envAgent_update_occupancy_fn.setMessageInput("new_locations");
 }
 
-void SingleAgentDiscreteMovement::defineLayer(ModelDescription &smm) {
-    smm.newLayer().addAgentFunction(envAgent_broadcast_status);
-    smm.newLayer().addAgentFunction(movingAgent_request_move);
-    smm.newLayer().addAgentFunction(envAgent_resolve_conflict);
-    smm.newLayer().addAgentFunction(movingAgent_execute_move);
-    smm.newLayer().addAgentFunction(envAgent_update_occupancy);
+void SingleAgentDiscreteMovement::defineLayer(ModelDescription &smm_desc) {
+    smm_desc.newLayer().addAgentFunction(envAgent_broadcast_status);
+    smm_desc.newLayer().addAgentFunction(movingAgent_request_move);
+    smm_desc.newLayer().addAgentFunction(envAgent_resolve_conflict);
+    smm_desc.newLayer().addAgentFunction(movingAgent_execute_move);
+    smm_desc.newLayer().addAgentFunction(envAgent_update_occupancy);
 }
 
 void SingleAgentDiscreteMovement::validate() {
-    if (!this->is_initialized) {
+    if (!this->smm.has_value()) {
         throw exception::InvalidSubModel("SingleAgentDiscreteMovement submodel was not initialized. Call addSingleAgentDiscreteMovementSubmodel() first.");
     }
 

tests/python/stockAgent/test_single_agent_discrete_movement.py

@@ -56,6 +56,10 @@ def test_initialization(self):
         except pyflamegpu.FLAMEGPURuntimeException as e:
             pytest.fail(f"validate() threw {e.type()} unexpectedly: {e.what()}")
 
+        # Check getName and getSubModelDescription
+        assert move_submodel.getName() == "SingleAgentDiscreteMovement"
+        assert move_submodel.getSubModelDescription() is not None
+
     """
     Test 2: Basic Greedy Movement
     Verifies that an agent at (0,0) moves to (1,1) if that cell has a higher score.
@@ -66,10 +70,10 @@ def test_simple_move(self):
         HEIGHT = 3
 
         move_submodel = pyflamegpu.SingleAgentDiscreteMovement()
-        smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
+        move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
 
         # Submodels must be added to a layer to be executed during the simulation step
-        model.newLayer().addSubModel(smd)
+        model.newLayer().addSubModel(move_submodel.getSubModelDescription())
 
         # Define parent agents with necessary variables
         agent = model.newAgent("agent")
@@ -147,8 +151,8 @@ def test_collision_avoidance(self):
         HEIGHT = 3
 
         move_submodel = pyflamegpu.SingleAgentDiscreteMovement()
-        smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
-        model.newLayer().addSubModel(smd)
+        move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
+        model.newLayer().addSubModel(move_submodel.getSubModelDescription())
 
         agent = model.newAgent("agent")
         agent.newVariableInt("x")
@@ -226,8 +230,8 @@ def test_resource_memory(self):
         HEIGHT = 3
 
         move_submodel = pyflamegpu.SingleAgentDiscreteMovement()
-        smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
-        model.newLayer().addSubModel(smd)
+        move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
+        model.newLayer().addSubModel(move_submodel.getSubModelDescription())
 
         agent = model.newAgent("agent")
         agent.newVariableInt("x")
@@ -297,8 +301,8 @@ def test_grid_boundaries(self):
         HEIGHT = 2
 
         move_submodel = pyflamegpu.SingleAgentDiscreteMovement()
-        smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
-        model.newLayer().addSubModel(smd)
+        move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT)
+        model.newLayer().addSubModel(move_submodel.getSubModelDescription())
 
         agent = model.newAgent("agent")
         agent.newVariableInt("x")
@@ -357,3 +361,7 @@ def test_grid_boundaries(self):
 if __name__ == "__main__":
     import unittest
     unittest.main()
+
+if __name__ == "__main__":
+    import unittest
+    unittest.main()

tests/test_cases/stockAgent/test_single_agent_discrete_movement.cu

@@ -46,6 +46,10 @@ TEST(SingleAgentDiscreteMovementTest, Initialization) {
 
     // Validation should pass now
     EXPECT_NO_THROW(move_submodel.validate());
+
+    // Check getName and getSubModelDescription
+    EXPECT_EQ(move_submodel.getName(), "SingleAgentDiscreteMovement");
+    EXPECT_NO_THROW(move_submodel.getSubModelDescription());
 }
 
 /**
@@ -58,10 +62,10 @@ TEST(SingleAgentDiscreteMovementTest, SimpleMove) {
     int HEIGHT = 3;
 
     SingleAgentDiscreteMovement move_submodel;
-    auto smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
+    move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
 
     // Submodels must be added to a layer to be executed during the simulation step
-    model.newLayer().addSubModel(smd);
+    model.newLayer().addSubModel(move_submodel.getSubModelDescription());
 
     // Define parent agents with necessary variables
     auto agent = model.newAgent("agent");
@@ -135,8 +139,8 @@ TEST(SingleAgentDiscreteMovementTest, CollisionAvoidance) {
     int HEIGHT = 3;
 
     SingleAgentDiscreteMovement move_submodel;
-    auto smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
-    model.newLayer().addSubModel(smd);
+    move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
+    model.newLayer().addSubModel(move_submodel.getSubModelDescription());
 
     auto agent = model.newAgent("agent");
     agent.newVariable<int>("x");
@@ -211,8 +215,8 @@ TEST(SingleAgentDiscreteMovementTest, ResourceMemory) {
     int HEIGHT = 3;
 
     SingleAgentDiscreteMovement move_submodel;
-    auto smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
-    model.newLayer().addSubModel(smd);
+    move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
+    model.newLayer().addSubModel(move_submodel.getSubModelDescription());
 
     auto agent = model.newAgent("agent");
     agent.newVariable<int>("x");
@@ -276,8 +280,8 @@ TEST(SingleAgentDiscreteMovementTest, GridBoundaries) {
     int HEIGHT = 2;
 
     SingleAgentDiscreteMovement move_submodel;
-    auto smd = move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
-    model.newLayer().addSubModel(smd);
+    move_submodel.addSingleAgentDiscreteMovementSubmodel(model, WIDTH, HEIGHT);
+    model.newLayer().addSubModel(move_submodel.getSubModelDescription());
 
     auto agent = model.newAgent("agent");
     agent.newVariable<int>("x");