AtHeartEngineer/kami
1
0
Fork 0
mirror of https://github.com/JHUAPL/kami.git synced 2026-01-08 14:33:53 -05:00
Code Issues Packages Projects Releases Wiki Activity

Cleanups and updates to all of the documentation

Browse Source
This commit is contained in:
James P. Howard, II
2022-08-02 19:29:50 -04:00
parent 3faa5b4c50
commit 95165f4d72
16 changed files with 219 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
include/kami/agent.h
View File

@@ -37,9 +37,9 @@
namespace kami {
/**
* A unique identifier for each `Agent`.
* @brief A unique identifier for each `Agent`.
*
* The unique identifier permits ordering to allow `AgentID`s to be used as keys
* @details The unique identifier permits ordering to allow `AgentID`s to be used as keys
* for `std::map`. The unique identifier is unique for the session, however,
* `AgentID`s are not guaranteed to be unique from session-to-session.
*
@@ -50,9 +50,9 @@ namespace kami {
inline static long long _id_next = 1;
/**
* The unique identifier is a `long long`.
* @brief The unique identifier is a `long long`.
*
* The unique identifier is an unsigned integer that increments
* @details The unique identifier is an unsigned integer that increments
* monotonically with each new `AgentID` instantiated. This is
* substantially faster than other potential identifiers, such
* as MD5 hashes or UUID objects.
@@ -61,19 +61,19 @@ namespace kami {
public:
/**
* Constructs a new unique identifier.
* @brief Constructs a new unique identifier.
*/
AgentID() : _id(_id_next++){};
/**
* Convert the identifier to a human-readable string.
* @brief Convert the identifier to a human-readable string.
*
* @return a human-readable form of the `AgentID` as `std::string`.
*/
[[nodiscard]] std::string to_string() const { return std::to_string(_id); }
/**
* Test if two `AgentID` instances are equal.
* @brief Test if two `AgentID` instances are equal.
*
* @param lhs is the left-hand side of the equality test.
* @param rhs is the right-hand side of the equality test.
@@ -82,7 +82,7 @@ namespace kami {
friend bool operator==(const AgentID &lhs, const AgentID &rhs);
/**
* Test if two `AgentID` instances are not equal.
* @brief Test if two `AgentID` instances are not equal.
*
* @param lhs is the left-hand side of the equality test.
* @param rhs is the right-hand side of the equality test.
@@ -91,9 +91,9 @@ namespace kami {
friend bool operator!=(const AgentID &lhs, const AgentID &rhs);
/**
* Test if one AgentID is less than another.
* @brief Test if one AgentID is less than another.
*
* Due to the way AgentID instances are used internally,
* @details Due to the way AgentID instances are used internally,
* the AgentID must be orderable. The `<` operator provides a
* basic ordering sufficient for `std::map`.
*
@@ -105,9 +105,9 @@ namespace kami {
friend bool operator<(const AgentID &lhs, const AgentID &rhs);
/**
* Output an AgentID to the specified output stream
* @brief Output an AgentID to the specified output stream
*
* The form of the output will be the same as that produced by the
* @details The form of the output will be the same as that produced by the
* `to_string()` member function.
*
* @param lhs is the stream to output the `AgentID` to
@@ -118,9 +118,9 @@ namespace kami {
};
/**
* A superclass for all agents.
* @brief A superclass for all agents.
*
* All agents should subclass the `Agent` class. At a minimum, subclasses must
* @details All agents should subclass the `Agent` class. At a minimum, subclasses must
* implement the `step()` function, to execute a single time step for each
* agent.
*
@@ -135,22 +135,24 @@ namespace kami {
public:
/**
* Get the `Agent`'s `AgentID`.
* @brief Get the `Agent`'s `AgentID`.
*
* @return the `AgentID`
*/
[[nodiscard]] AgentID get_agent_id() const;
/**
* Execute a time-step for the agent
* @brief Execute a time-step for the agent
*
* This function should step the agent instance. Any activities that the
* @details This function should step the agent instance. Any activities that the
* agent should perform as part of its time step should be in this function.
*
* @param model a reference copy of the model
*/
virtual void step(std::shared_ptr<Model> model) = 0;
/**
* Compare if two `Agent`s are the same `Agent`.
* @brief Compare if two `Agent`s are the same `Agent`.
*
* @param lhs is the left-hand side of the equality test.
* @param rhs is the right-hand side of the equality test.
@@ -166,7 +168,7 @@ namespace kami {
friend bool operator==(const Agent &lhs, const Agent &rhs);
/**
* Compare if two `Agent`s are not the same `Agent`.
* @brief Compare if two `Agent`s are not the same `Agent`.
*
* @param lhs is the left-hand side of the equality test.
* @param rhs is the right-hand side of the equality test.
@@ -183,9 +185,9 @@ namespace kami {
};
/**
* A superclass for all staged agents.
* @brief A superclass for all staged agents.
*
* Staged agents use a two-phase step to allow agents to take actions without
* @details Staged agents use a two-phase step to allow agents to take actions without
* updating the state of the model before all agents have been allowed to
* update. All work necessary to advance the `StagedAgent` state should take
* place in the `step()` function. However, the `StagedAgent` should not actually
@@ -197,11 +199,14 @@ namespace kami {
class LIBKAMI_EXPORT StagedAgent : public Agent {
public:
/**
* Post-step advance the agent
* @brief Post-step advance the agent
*
* This method should be called after `step()`. Any updates or cleanups to
* @details This method should be called after `step()`. Any updates or cleanups to
* the agent that must happen for the `StagedAgent` to complete its step must
* happen here.
*
* @param model a reference copy of the model
*
*/
virtual void advance(std::shared_ptr<Model> model) = 0;
};

5
include/kami/config.h.in
View File

@@ -55,6 +55,11 @@
namespace kami {
/**
* @brief A reference copy of the current version of Kami
*
* @return the version as a `semver` object
*/
constexpr semver::version version{KAMI_VERSION_MAJOR, KAMI_VERSION_MINOR, KAMI_VERSION_PATCH};
} // namespace kami

44
include/kami/domain.h
View File

@@ -33,47 +33,47 @@
namespace kami {
/**
* Provides an environment for the agents to participate in.
*
* Implementations of virtual environments are expected to subclass `Domain`.
*/
/**
* @brief Provides an environment for the agents to participate in.
*
* @details Implementations of virtual environments are expected to subclass `Domain`.
*/
class LIBKAMI_EXPORT Domain {
protected:
/**
* Constructor.
* @brief Constructor.
*
* Making this constructor protected makes the class abstract without having
* @details Making this constructor protected makes the class abstract without having
* to create any virtual functions.
*/
Domain() = default;
};
/**
* Provides a coordinate system for each `Domain`.
*
* The coordinate system must be able to produce a human-readable version of the
* coordinates given. For instance, an integer grid in two dimensions would
* provide standard Descartes coordinates like (0, 0) for the origin, or (2, 3)
* for the position that is two units "up" and three units to the "right" of the
* origin. Implementation of a coordinate system is left up to the user, though
* there are several established systems provided.
*
* @see GridCoord
*/
/**
* @brief Provides a coordinate system for each `Domain`.
*
* @details The coordinate system must be able to produce a human-readable version of the
* coordinates given. For instance, an integer grid in two dimensions would
* provide standard Descartes coordinates like (0, 0) for the origin, or (2, 3)
* for the position that is two units "up" and three units to the "right" of the
* origin. Implementation of a coordinate system is left up to the user, though
* there are several established systems provided.
*
* @see GridCoord
*/
class LIBKAMI_EXPORT Coord {
public:
/**
* Convert the coordinate to a human-readable string.
* @brief Convert the coordinate to a human-readable string.
*
* @return a human-readable form of the `Coord` as `std::string`.
*/
[[nodiscard]] virtual std::string to_string() const = 0;
/**
* Output a `Coord` to the specified output stream
* @brief Output a `Coord` to the specified output stream
*
* The form of the output will be the same as that produced by the
* @details The form of the output will be the same as that produced by the
* `to_string()` member function.
*
* @param lhs is the stream to output the `Coord` to

68
include/kami/grid1d.h
View File

@@ -37,40 +37,40 @@
namespace kami {
/**
* One-dimensional coordinates
*/
/**
* @brief One-dimensional coordinates
*/
class LIBKAMI_EXPORT GridCoord1D : public GridCoord {
public:
/**
* Constructor for one-dimensional coordinates
* @brief Constructor for one-dimensional coordinates
*/
explicit GridCoord1D(int x_coord) : _x_coord(x_coord){};
/**
* Return the `x` coordinate
* @brief Return the `x` coordinate
*/
[[nodiscard]] int get_x_location() const;
/**
* Convert the coordinate to a human-readable string.
* @brief Convert the coordinate to a human-readable string.
*
* @return a human-readable form of the `Coord` as `std::string`.
*/
[[nodiscard]] std::string to_string() const override;
/**
* Test if two coordinates are equal
* @brief Test if two coordinates are equal
*/
friend bool operator==(const GridCoord1D &lhs, const GridCoord1D &rhs);
/**
* Test if two coordinates are not equal
* @brief Test if two coordinates are not equal
*/
friend bool operator!=(const GridCoord1D &lhs, const GridCoord1D &rhs);
/**
* Output a given coordinate to the specified stream
* @brief Output a given coordinate to the specified stream
*/
friend std::ostream &operator<<(std::ostream &lhs, const GridCoord1D &rhs);
@@ -78,18 +78,18 @@ namespace kami {
int _x_coord;
};
/**
* A one-dimensional grid where each cell may contain agents
*
* The grid is linear and may wrap around in its only dimension.
*
* @see `MultiGrid1D`
* @see `SoloGrid1D`
*/
/**
* @brief A one-dimensional grid where each cell may contain agents
*
* @details The grid is linear and may wrap around in its only dimension.
*
* @see `MultiGrid1D`
* @see `SoloGrid1D`
*/
class LIBKAMI_EXPORT Grid1D : public GridDomain {
public:
/**
* Constructor
* @brief Constructor
*
* @param[in] maximum_x the length of the grid.
* @param[in] wrap_x should the grid wrap around on itself.
@@ -97,12 +97,12 @@ namespace kami {
explicit Grid1D(unsigned int maximum_x, bool wrap_x = false);
/**
* Destructor
* @brief Destructor
*/
virtual ~Grid1D();
/**
* Place agent on the grid at the specified location.
* @brief Place agent on the grid at the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to add.
* @param[in] coord the coordinates of the agent.
@@ -113,7 +113,7 @@ namespace kami {
virtual bool add_agent(AgentID agent_id, GridCoord1D coord) = 0;
/**
* Remove agent from the grid.
* @brief Remove agent from the grid.
*
* @param[in] agent_id the `AgentID` of the agent to remove.
*
@@ -122,7 +122,7 @@ namespace kami {
bool delete_agent(AgentID agent_id);
/**
* Remove agent from the grid at the specified location
* @brief Remove agent from the grid at the specified location
*
* @param[in] agent_id the `AgentID` of the agent to remove.
* @param[in] coord the coordinates of the agent.
@@ -132,7 +132,7 @@ namespace kami {
bool delete_agent(AgentID agent_id, const GridCoord1D &coord);
/**
* Move an agent to the specified location.
* @brief Move an agent to the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to move.
* @param[in] coord the coordinates of the agent.
@@ -140,7 +140,7 @@ namespace kami {
bool move_agent(AgentID agent_id, GridCoord1D coord);
/**
* Inquire if the specified location is empty.
* @brief Inquire if the specified location is empty.
*
* @param[in] coord the coordinates of the query.
*
@@ -150,7 +150,7 @@ namespace kami {
[[nodiscard]] bool is_location_empty(const GridCoord1D& coord) const;
/**
* Inquire if the specified location is valid within the grid.
* @brief Inquire if the specified location is valid within the grid.
*
* @param[in] coord the coordinates of the query.
*
@@ -159,7 +159,7 @@ namespace kami {
[[nodiscard]] bool is_location_valid(const GridCoord1D& coord) const;
/**
* Get the location of the specified agent.
* @brief Get the location of the specified agent.
*
* @param[in] agent_id the `AgentID` of the agent in question.
*
@@ -168,7 +168,7 @@ namespace kami {
[[nodiscard]] GridCoord1D get_location_by_agent(AgentID agent_id) const;
/**
* Get the contents of the specified location.
* @brief Get the contents of the specified location.
*
* @param[in] coord the coordinates of the query.
*
@@ -180,14 +180,14 @@ namespace kami {
[[nodiscard]] std::vector<AgentID> *get_location_contents(const GridCoord1D& coord) const;
/**
* Inquire to whether the grid wraps in the `x` dimension.
* @brief Inquire to whether the grid wraps in the `x` dimension.
*
* @return true if the grid wraps, and false otherwise
*/
[[nodiscard]] bool get_wrap_x() const;
/**
* Return the neighborhood of the specified Agent
* @brief Return the neighborhood of the specified Agent
*
* @param[in] agent_id the `AgentID` of the agent in question
* @param[in] include_center should the center-point, occupied by the agent,
@@ -199,7 +199,7 @@ namespace kami {
[[nodiscard]] std::vector<GridCoord1D> get_neighborhood(AgentID agent_id, bool include_center) const;
/**
* Return the neighborhood of the specified location
* @brief Return the neighborhood of the specified location
*
* @param[in] coord the coordinates of the specified location.
* @param[in] include_center should the center-point, occupied by the agent,
@@ -211,7 +211,7 @@ namespace kami {
[[nodiscard]] std::vector<GridCoord1D> get_neighborhood(const GridCoord1D& coord, bool include_center) const;
/**
* Get the size of the grid in the `x` dimension.
* @brief Get the size of the grid in the `x` dimension.
*
* @return the length of the grid in the `x` dimension
*/
@@ -219,18 +219,18 @@ namespace kami {
protected:
/**
* A vector containing the `AgentID`s of all agents assigned to this
* @brief A vector containing the `AgentID`s of all agents assigned to this
* grid.
*/
std::vector<AgentID> *_agent_grid;
/**
* A map containing the grid location of each agent.
* @brief A map containing the grid location of each agent.
*/
std::map<AgentID, GridCoord1D> *_agent_index;
/**
* Automatically adjust a coordinate location for wrapping.
* @brief Automatically adjust a coordinate location for wrapping.
*
* @param[in] coord the coordinates of the specified location.
*

74
include/kami/grid2d.h
View File

@@ -37,46 +37,46 @@
namespace kami {
/**
* Two-dimensional coordinates
*/
/**
* @brief Two-dimensional coordinates
*/
class LIBKAMI_EXPORT GridCoord2D : public GridCoord {
public:
/**
* Constructor for two-dimensional coordinates
* @brief Constructor for two-dimensional coordinates
*/
GridCoord2D(int x_coord, int y_coord)
: _x_coord(x_coord), _y_coord(y_coord){};
/**
* Get the coordinate in the first dimension or `x`.
* @brief Get the coordinate in the first dimension or `x`.
*/
[[nodiscard]] int get_x_location() const;
/**
* Get the coordinate in the second dimension or `y`.
* @brief Get the coordinate in the second dimension or `y`.
*/
[[nodiscard]] int get_y_location() const;
/**
* Convert the coordinate to a human-readable string.
* @brief Convert the coordinate to a human-readable string.
*
* @return a human-readable form of the `Coord` as `std::string`.
*/
[[nodiscard]] std::string to_string() const override;
/**
* Test if two coordinates are equal
* @brief Test if two coordinates are equal
*/
friend bool operator==(const GridCoord2D &, const GridCoord2D &);
/**
* Test if two coordinates are not equal
* @brief Test if two coordinates are not equal
*/
friend bool operator!=(const GridCoord2D &, const GridCoord2D &);
/**
* Output a given coordinate to the specified stream
* @brief Output a given coordinate to the specified stream
*/
friend std::ostream &operator<<(std::ostream &, const GridCoord2D &);
@@ -84,18 +84,18 @@ namespace kami {
int _x_coord, _y_coord;
};
/**
* A two-dimensional grid where each cell may contain agents
*
* The grid is linear and may wrap around in its only dimension.
*
* @see `MultiGrid2D`
* @see `SoloGrid2D`
*/
/**
* @brief A two-dimensional grid where each cell may contain agents
*
* @details The grid is linear and may wrap around in its only dimension.
*
* @see `MultiGrid2D`
* @see `SoloGrid2D`
*/
class LIBKAMI_EXPORT Grid2D : public GridDomain {
public:
/**
* Constructor
* @brief Constructor
*
* @param[in] maximum_x the length of the grid in the first dimension
* @param[in] maximum_y the length of the grid in the second dimension
@@ -108,12 +108,12 @@ namespace kami {
bool wrap_y = false);
/**
* Destructor
* @brief Destructor
*/
virtual ~Grid2D();
/**
* Place agent on the grid at the specified location.
* @brief Place agent on the grid at the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to add.
* @param[in] coord the coordinates of the agent.
@@ -124,7 +124,7 @@ namespace kami {
virtual bool add_agent(AgentID agent_id, GridCoord2D coord) = 0;
/**
* Remove agent from the grid.
* @brief Remove agent from the grid.
*
* @param[in] agent_id the `AgentID` of the agent to remove.
*
@@ -133,7 +133,7 @@ namespace kami {
bool delete_agent(AgentID agent_id);
/**
* Remove agent from the grid at the specified location
* @brief Remove agent from the grid at the specified location
*
* @param[in] agent_id the `AgentID` of the agent to remove.
* @param[in] coord the coordinates of the agent.
@@ -143,7 +143,7 @@ namespace kami {
bool delete_agent(AgentID agent_id, const GridCoord2D &coord);
/**
* Move an agent to the specified location.
* @brief Move an agent to the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to move.
* @param[in] coord the coordinates of the agent.
@@ -151,7 +151,7 @@ namespace kami {
bool move_agent(AgentID agent_id, GridCoord2D coord);
/**
* Inquire if the specified location is empty.
* @brief Inquire if the specified location is empty.
*
* @param[in] coord the coordinates of the query.
*
@@ -161,7 +161,7 @@ namespace kami {
[[nodiscard]] bool is_location_empty(const GridCoord2D& coord) const;
/**
* Inquire if the specified location is valid within the grid.
* @brief Inquire if the specified location is valid within the grid.
*
* @param[in] coord the coordinates of the query.
*
@@ -170,7 +170,7 @@ namespace kami {
[[nodiscard]] bool is_location_valid(const GridCoord2D& coord) const;
/**
* Get the location of the specified agent.
* @brief Get the location of the specified agent.
*
* @param[in] agent_id the `AgentID` of the agent in question.
*
@@ -179,7 +179,7 @@ namespace kami {
[[nodiscard]] GridCoord2D get_location_by_agent(AgentID agent_id) const;
/**
* Get the contents of the specified location.
* @brief Get the contents of the specified location.
*
* @param[in] coord the coordinates of the query.
*
@@ -191,21 +191,21 @@ namespace kami {
[[nodiscard]] std::vector<AgentID> *get_location_contents(const GridCoord2D& coord) const;
/**
* Inquire to whether the grid wraps in the `x` dimension.
* @brief Inquire to whether the grid wraps in the `x` dimension.
*
* @return true if the grid wraps, and false otherwise
*/
[[nodiscard]] bool get_wrap_x() const;
/**
* Inquire to whether the grid wraps in the `y` dimension.
* @brief Inquire to whether the grid wraps in the `y` dimension.
*
* @return true if the grid wraps, and false otherwise
*/
[[nodiscard]] bool get_wrap_y() const;
/**
* Return the neighborhood of the specified Agent
* @brief Return the neighborhood of the specified Agent
*
* @param[in] agent_id the `AgentID` of the agent in question.
* @param[in] neighborhood_type the neighborhood type.
@@ -220,7 +220,7 @@ namespace kami {
[[nodiscard]] std::vector<GridCoord2D> get_neighborhood(AgentID agent_id, GridNeighborhoodType neighborhood_type, bool include_center) const;
/**
* Return the neighborhood of the specified location
* @brief Return the neighborhood of the specified location
*
* @param[in] coord the coordinates of the specified location.
* @param[in] neighborhood_type the neighborhood type.
@@ -235,14 +235,14 @@ namespace kami {
[[nodiscard]] std::vector<GridCoord2D> get_neighborhood(const GridCoord2D& coord, GridNeighborhoodType neighborhood_type, bool include_center) const;
/**
* Get the size of the grid in the `x` dimension.
* @brief Get the size of the grid in the `x` dimension.
*
* @return the length of the grid in the `x` dimension
*/
[[nodiscard]] unsigned int get_maximum_x() const;
/**
* Get the size of the grid in the `y` dimension.
* @brief Get the size of the grid in the `y` dimension.
*
* @return the length of the grid in the `xy dimension
*/
@@ -250,18 +250,18 @@ namespace kami {
protected:
/**
* A vector containing the `AgentID`s of all agents assigned to this
* @brief A vector containing the `AgentID`s of all agents assigned to this
* grid.
*/
std::vector<AgentID> **_agent_grid;
/**
* A map containing the grid location of each agent.
* @brief A map containing the grid location of each agent.
*/
std::map<AgentID, GridCoord2D> *_agent_index;
/**
* Automatically adjust a coordinate location for wrapping.
* @brief Automatically adjust a coordinate location for wrapping.
*
* @param[in] coord the coordinates of the specified location.
*

1
include/kami/kami.h
View File

@@ -34,6 +34,7 @@
namespace kami {
// Forward declarations to clean up a lot of include-file madness
class Agent;
class AgentID;
class Domain;

14
include/kami/model.h
View File

@@ -36,9 +36,9 @@
namespace kami {
/**
* An abstract for generic models
*/
/**
* @brief An abstract for generic models
*/
class LIBKAMI_EXPORT Model : public std::enable_shared_from_this<Model> {
protected:
std::shared_ptr<Domain> _domain = nullptr;
@@ -47,18 +47,18 @@ namespace kami {
public:
/**
* Execute a fixed number of time-steps for the model.
* @brief Execute a fixed number of time-steps for the model.
*
* This function should execute a fixed number of time-steps for the model.
* @details This function should execute a fixed number of time-steps for the model.
*
* @param[in] n the number of time steps to execute.
*/
virtual void run(unsigned int n) = 0;
/**
* Execute a single time-step for the model.
* @brief Execute a single time-step for the model.
*
* This function should step the model instance. Any activities that the
* @details This function should step the model instance. Any activities that the
* model should perform as part of its time step should be in this function.
*/
virtual void step() = 0;

17
include/kami/multigrid1d.h
View File

@@ -35,15 +35,18 @@
namespace kami {
/**
* @brief A one-dimensional grid where each cell may contain multiple agents
*
* @details The grid is linear and may wrap around in its only dimension.
*/
/**
* @brief A one-dimensional grid where each cell may contain multiple agents
*
* @details The grid is linear and may wrap around in its only dimension.
*
* @see `Grid1D`
* @see `SoloGrid1D`
*/
class LIBKAMI_EXPORT MultiGrid1D : public Grid1D {
public:
/**
* Constructor
* @brief Constructor
*
* @param[in] maximum_x the length of the grid.
* @param[in] wrap_x should the grid wrap around on itself.
@@ -52,7 +55,7 @@ namespace kami {
: Grid1D(maximum_x, wrap_x) {}
/**
* Place agent on the grid at the specified location.
* @brief Place agent on the grid at the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to add.
* @param[in] coord the coordinates of the agent.

20
include/kami/multigrid2d.h
View File

@@ -35,18 +35,18 @@
namespace kami {
/**
* @brief A two-dimensional grid where each cell may contain multiple agents
*
* @details The grid is linear and may wrap around in its only dimension.
*
* @see `Grid2D`
* @see `SoloGrid2D`
*/
/**
* @brief A two-dimensional grid where each cell may contain multiple agents
*
* @details The grid is linear and may wrap around in either dimension.
*
* @see `Grid2D`
* @see `SoloGrid2D`
*/
class LIBKAMI_EXPORT MultiGrid2D : public Grid2D {
public:
/**
* Constructor
* @brief Constructor
*
* @param[in] maximum_x the length of the grid in the first dimension
* @param[in] maximum_y the length of the grid in the second dimension
@@ -59,7 +59,7 @@ namespace kami {
: Grid2D(maximum_x, maximum_y, wrap_x, wrap_y) {};
/**
* Place agent on the grid at the specified location.
* @brief Place agent on the grid at the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to add.
* @param[in] coord the coordinates of the agent.

13
include/kami/population.h
View File

@@ -34,8 +34,9 @@
#include <kami/kami.h>
namespace kami {
/**
* An abstract for generic models
* @brief An abstract for generic models
*/
class LIBKAMI_EXPORT Population {
protected:
@@ -43,7 +44,7 @@ namespace kami {
public:
/**
* Get a reference to an `Agent` by `AgentID`
* @brief Get a reference to an `Agent` by `AgentID`
*
* @param[in] agent_id the `AgentID` to search for.
*
@@ -52,21 +53,21 @@ namespace kami {
[[nodiscard]] std::shared_ptr<Agent> get_agent_by_id(AgentID agent_id) const;
/**
* Add an Agent to the Population.
* @brief Add an Agent to the Population.
*
* @param agent The Agent to add.
*/
void add_agent(const std::shared_ptr<Agent> &agent);
/**
* Remove an Agent from the Population.
* @brief Remove an Agent from the Population.
*
* @param agent_id The AgentID of the agent to remove.
*/
void delete_agent(AgentID agent_id);
/*
* Returns the agent list.
/**
* @brief Returns the agent list.
*/
std::shared_ptr<std::vector<AgentID>> get_agent_list();
};

27
include/kami/random.h
View File

@@ -37,16 +37,14 @@
namespace kami {
/**
* Will execute all agent steps in a random order.
*
* A random scheduler will iterate over the agents assigned
* to the scheduler and call their `step()` function in a random order.
* That order should be different for each subsequent call to `step()`,
* but is not guaranteed not to repeat.
*
* @note First create a Model for the scheduler to live in.
*/
/**
* @brief Will execute all agent steps in a random order.
*
* @details A random scheduler will iterate over the agents assigned
* to the scheduler and call their `step()` function in a random order.
* That order should be different for each subsequent call to `step()`,
* but is not guaranteed not to repeat.
*/
class LIBKAMI_EXPORT RandomScheduler : public SequentialScheduler {
private:
std::shared_ptr<std::ranlux24> _rng = nullptr;
@@ -71,12 +69,15 @@ namespace kami {
* @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 model
* @param agent_list list of agents to execute the step
*/
void step(std::shared_ptr<Model> model, std::shared_ptr<std::vector<AgentID>> agent_list) override;
/**
* Set the random number generator used to randomize the order of agent
* @brief Set the RNG
*
* @details Set the random number generator used to randomize the order of agent
* stepping.
*
* @param rng [in] A uniform random number generator of type `std::mt19937`,
@@ -85,7 +86,9 @@ namespace kami {
void set_rng(std::shared_ptr<std::ranlux24> rng);
/**
* Get a reference to the random number generator used to randomize
* @brief Get the RNG
*
* @details Get a reference to the random number generator used to randomize
* the order of agent stepping.
*/
std::shared_ptr<std::ranlux24> get_rng();

7
include/kami/scheduler.h
View File

@@ -30,8 +30,6 @@
#include <kami/model.h>
namespace kami {
class Model;
/**
* Create a Kami scheduler.
*
@@ -51,9 +49,11 @@ namespace kami {
* @brief Execute a single time step.
*
* @details This method will step through the list of Agents in the
* `Population` and then execute the `Agent::step()`
* `Population` associated with `model` 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 model
*/
virtual void step(std::shared_ptr<Model> model) = 0;
@@ -65,6 +65,7 @@ namespace kami {
* method for every Agent assigned to this scheduler in the order
* assigned.
*
* @param model a reference copy of the model
* @param agent_list list of agents to execute the step
*/
virtual void step(std::shared_ptr<Model> model, std::shared_ptr<std::vector<AgentID>> agent_list) = 0;

21
include/kami/sequential.h
View File

@@ -36,16 +36,14 @@
namespace kami {
/**
* @brief Will execute all agent steps in a sequential order.
*
* @details A sequential scheduler will iterate over the agents assigned
* to the scheduler and call their `step()` function in a sequential order.
* That order is preserved between calls to `step()` but may be modified by
* `addAgent()` or `deleteAgent()`.
*
* \pre First create a Model for the scheduler to live in.
*/
/**
* @brief Will execute all agent steps in a sequential order.
*
* @details A sequential scheduler will iterate over the agents assigned
* to the scheduler and call their `step()` function in a sequential order.
* That order is preserved between calls to `step()` but may be modified by
* `addAgent()` or `deleteAgent()`.
*/
class LIBKAMI_EXPORT SequentialScheduler : public Scheduler {
public:
/**
@@ -55,6 +53,8 @@ namespace kami {
* 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 model
*/
void step(std::shared_ptr<Model> model);
@@ -66,6 +66,7 @@ namespace kami {
* method for every Agent assigned to this scheduler in the order
* assigned.
*
* @param model a reference copy of the model
* @param agent_list list of agents to execute the step
*/
virtual void step(std::shared_ptr<Model> model, std::shared_ptr<std::vector<AgentID>> agent_list);

17
include/kami/sologrid1d.h
View File

@@ -34,15 +34,18 @@
namespace kami {
/**
* @brief A one-dimensional grid where each cell may contain only one Agent
*
* @details The grid is linear and may wrap around in its only dimension.
*/
/**
* @brief A one-dimensional grid where each cell may contain one agenta
*
* @details The grid is linear and may wrap around in its only dimension.
*
* @see `Grid1D`
* @see `MultiGrid1D`
*/
class LIBKAMI_EXPORT SoloGrid1D : public Grid1D {
public:
/**
* Constructor
* @brief Constructor
*
* @param[in] maximum_x the length of the grid.
* @param[in] wrap_x should the grid wrap around on itself.
@@ -51,7 +54,7 @@ namespace kami {
: Grid1D(maximum_x, wrap_x) {}
/**
* Place agent on the grid at the specified location.
* @brief Place agent on the grid at the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to add.
* @param[in] coord the coordinates of the agent.

20
include/kami/sologrid2d.h
View File

@@ -34,18 +34,18 @@
namespace kami {
/**
* @brief A two-dimensional grid where each cell may contain only one Agent
*
* @details The grid is linear and may wrap around in its only dimension.
*
* @see `MultiGrid2D`
* @see `Grid2D`
*/
/**
* @brief A two-dimensional grid where each cell may contain multiple agents
*
* @details The grid is linear and may wrap around in either dimension.
*
* @see `Grid2D`
* @see `MultiGrid2D`
*/
class LIBKAMI_EXPORT SoloGrid2D : public Grid2D {
public:
/**
* Constructor
* @details Constructor
*
* @param[in] maximum_x the length of the grid in the first dimension
* @param[in] maximum_y the length of the grid in the second dimension
@@ -56,7 +56,7 @@ namespace kami {
: Grid2D(maximum_x, maximum_y, wrap_x, wrap_y) {};
/**
* Place agent on the grid at the specified location.
* @details Place agent on the grid at the specified location.
*
* @param[in] agent_id the `AgentID` of the agent to add.
* @param[in] coord the coordinates of the agent.

10
include/kami/staged.h
View File

@@ -55,6 +55,8 @@ namespace kami {
* scheduler's internal queue and then execute the `StagedAgent::step()`
* method for every StagedAgent assigned to this scheduler in the order
* assigned.
*
* @param model a reference copy of the model
*/
void advance(std::shared_ptr<Model> model);
@@ -66,18 +68,22 @@ namespace kami {
* method for every StagedAgent assigned to this scheduler in the order
* assigned.
*
* @param model a reference copy of the model
* @param agent_list list of agents to execute the step
*/
void advance(std::shared_ptr<Model> model, std::shared_ptr<std::vector<AgentID>> agent_list);
public:
/**
* Execute a single time step.
* @brief Execute a single time step
*
* This method will step through the list of Agents in the scheduler's
* @details This method will step through the list of Agents in the scheduler's
* internal queue and execute the `Agent::step()` method for each `Agent`
* in the same order. Finally, it will execute the `Agent::advance()`
* method for each Agent in the same order.
*
* @param model a reference copy of the model
* @param agent_list list of agents to execute the step
*/
void step(std::shared_ptr<Model> model, std::shared_ptr<std::vector<AgentID>> agent_list) override;
};