diff --git a/include/kami/agent.h b/include/kami/agent.h index c34997f..2d8e48f 100644 --- a/include/kami/agent.h +++ b/include/kami/agent.h @@ -125,7 +125,7 @@ namespace kami { * implement the `step()` function, to execute a single time step for each * agent. * - * @see `StagedAgent` + * @see `ReporterAgent`, `StagedAgent` */ class LIBKAMI_EXPORT Agent { private: diff --git a/include/kami/model.h b/include/kami/model.h index 2a2fd71..e7a52b5 100644 --- a/include/kami/model.h +++ b/include/kami/model.h @@ -40,6 +40,8 @@ namespace kami { /** * @brief An abstract for generic models + * + * @see `ReporterModel` */ class LIBKAMI_EXPORT Model : public std::enable_shared_from_this { diff --git a/include/kami/random.h b/include/kami/random.h index fd91255..ea9ec00 100644 --- a/include/kami/random.h +++ b/include/kami/random.h @@ -73,10 +73,27 @@ namespace kami { * @returns returns vector of agents successfully stepped */ std::unique_ptr> - step(std::shared_ptr model, std::unique_ptr> agent_list) override; + step( + std::shared_ptr model, + std::unique_ptr> agent_list + ) override; + /** + * @brief Execute a single time step for a `ReporterModel` + * + * @details This method will randomize the list of Agents provided + * then execute the `Agent::step()` method for every Agent listed. + * + * @param model a reference copy of the `ReporterModel` + * @param agent_list list of agents to execute the step + * + * @returns returns vector of agents successfully stepped + */ std::unique_ptr> - step(std::shared_ptr model, std::unique_ptr> agent_list) override; + step( + std::shared_ptr model, + std::unique_ptr> agent_list + ) override; /** * @brief Set the RNG diff --git a/include/kami/reporter.h b/include/kami/reporter.h index d94028c..45e19f2 100644 --- a/include/kami/reporter.h +++ b/include/kami/reporter.h @@ -45,7 +45,17 @@ namespace kami { class ReporterModel; - class LIBKAMI_EXPORT ReporterAgent : public Agent { + /** + * @brief A superclass for all reporting agents + * + * @details All reporting agents should subclass the `ReportingAgent` class. At a minimum, + * subclasses must implement the `step()` function, to execute a single time step for each + * agent. + * + * @see `Agent`, `StagedAgent` + */ + class LIBKAMI_EXPORT ReporterAgent + : public Agent { public: /** * @brief Collect the current state of the agent @@ -84,7 +94,13 @@ namespace kami { int _step_counter = 0; }; - class LIBKAMI_EXPORT ReporterModel : public Model { + /** + * @brief An abstract for generic models with a reporting capability + * + * @see `Model` + */ + class LIBKAMI_EXPORT ReporterModel + : public Model { public: /** * @brief Constructor @@ -150,7 +166,12 @@ namespace kami { unsigned int _step_count{}; }; - class LIBKAMI_EXPORT Reporter : public std::enable_shared_from_this { + /** + * @brief A `Reporter` is a module that works with `ReporterAgent` and `ReporterModel` + * to collect information about the state of the model for later analysis + */ + class LIBKAMI_EXPORT Reporter + : public std::enable_shared_from_this { public: /** * @brief Constructor diff --git a/include/kami/scheduler.h b/include/kami/scheduler.h index 6595c94..4ce6d30 100644 --- a/include/kami/scheduler.h +++ b/include/kami/scheduler.h @@ -60,6 +60,18 @@ namespace kami { */ virtual std::unique_ptr> step(std::shared_ptr model) = 0; + /** + * @brief Execute a single time step for a `ReporterModel` + * + * @details This method will step through the list of Agents in the + * scheduler's internal queue and then execute the `Agent::step()` + * method for every Agent assigned to this scheduler in the order + * assigned. + * + * @param model a reference copy of the `ReporterModel` + * + * @returns returns vector of agents successfully stepped + */ virtual std::unique_ptr> step(std::shared_ptr model) = 0; /** @@ -76,10 +88,29 @@ namespace kami { * @returns returns vector of agents successfully stepped */ virtual std::unique_ptr> - step(std::shared_ptr model, std::unique_ptr> agent_list) = 0; + step( + std::shared_ptr model, + std::unique_ptr> agent_list + ) = 0; + /** + * @brief Execute a single time step for a `ReporterModel` + * + * @details This method will step through the list of Agents in the + * scheduler's internal queue and then execute the `Agent::step()` + * method for every Agent assigned to this scheduler in the order + * assigned. + * + * @param model a reference copy of the `ReporterModel` + * @param agent_list list of agents to execute the step + * + * @returns returns vector of agents successfully stepped + */ virtual std::unique_ptr> - step(std::shared_ptr model, std::unique_ptr> agent_list) = 0; + step( + std::shared_ptr model, + std::unique_ptr> agent_list + ) = 0; protected: /** diff --git a/include/kami/sequential.h b/include/kami/sequential.h index 2e0f048..4c86f59 100644 --- a/include/kami/sequential.h +++ b/include/kami/sequential.h @@ -63,6 +63,18 @@ namespace kami { */ std::unique_ptr> step(std::shared_ptr model) override; + /** + * @brief Execute a single time step for a `ReporterModel` + * + * @details This method will step through the list of Agents in the + * scheduler's internal queue and then execute the `Agent::step()` + * method for every Agent assigned to this scheduler in the order + * assigned. + * + * @param model a reference copy of the `ReporterModel` + * + * @returns returns vector of agents successfully stepped + */ std::unique_ptr> step(std::shared_ptr model) override; /** @@ -79,10 +91,29 @@ namespace kami { * @returns returns vector of agents successfully stepped */ std::unique_ptr> - step(std::shared_ptr model, std::unique_ptr> agent_list) override; + step( + std::shared_ptr model, + std::unique_ptr> agent_list + ) override; + /** + * @brief Execute a single time step for a `ReporterModel` + * + * @details This method will step through the list of Agents in the + * scheduler's internal queue and then execute the `Agent::step()` + * method for every Agent assigned to this scheduler in the order + * assigned. + * + * @param model a reference copy of the `ReporterModel` + * @param agent_list list of agents to execute the step + * + * @returns returns vector of agents successfully stepped + */ std::unique_ptr> - step(std::shared_ptr model, std::unique_ptr> agent_list) override; + step( + std::shared_ptr model, + std::unique_ptr> agent_list + ) override; }; } // namespace kami