Merge branch 'release/0.6.0'

.github/workflows/build-develop.yml

@@ -34,7 +34,7 @@ jobs:
         conan profile update settings.compiler.libcxx=libstdc++11 default
 
     - name: Conan Install Dependencies
-      run: conan install -if build . 
+      run: conan install -if build . --build=missing
 
     - name: Configure CMake
       # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.

.github/workflows/build-main.yml

@@ -34,7 +34,7 @@ jobs:
         conan profile update settings.compiler.libcxx=libstdc++11 default
 
     - name: Conan Install Dependencies
-      run: conan install -if build . 
+      run: conan install -if build . --build=missing
 
     - name: Configure CMake
       # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.

CMakeLists.txt

@@ -5,8 +5,8 @@ cmake_minimum_required(VERSION 3.13)
 set(PROJECT_NAME "kami")
 
 set(VERSION_MAJOR 0)
-set(VERSION_MINOR 5)
-set(VERSION_PATCH 1)
+set(VERSION_MINOR 6)
+set(VERSION_PATCH 0)
 set(VERSION_STRING ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH})
 
 project(${PROJECT_NAME}
@@ -23,9 +23,6 @@ conan_basic_setup()
 
 set(PROJECT_NAMESPACE ${PROJECT_NAME})
 
-find_package(spdlog)
-find_package(Threads)
-
 if(CMAKE_COMPILER_IS_GNUCC)
     option(ENABLE_COVERAGE "Enable coverage reporting for gcc/clang" FALSE)
 endif()

conanfile.py

@@ -3,7 +3,7 @@
 
 class KamiConan(ConanFile):
     name = "kami"
-    version = "0.5.1"
+    version = "0.6.0"
     license = "MIT"
     author = "James P. Howard, II <[email protected]>"
     url = "https://github.com/jhuapl/kami"
@@ -44,8 +44,8 @@ def package_info(self):
 
 
     def requirements(self):
-        self.requires("fmt/7.1.3")
-        self.requires("spdlog/1.8.5")
-        self.requires("cli11/1.9.1")
+        self.requires("fmt/9.0.0")
+        self.requires("spdlog/1.10.0")
+        self.requires("cli11/2.2.0")
         self.requires("neargye-semver/0.3.0")
         self.requires("gtest/cci.20210126")

docs/changelog.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+- :release:`0.6.0 <2022.08.19>`
+- :feature:`0` Added a to do list to the documentation
+- :feature:`0` Completed basic unit tests
+- :feature:`0` Removed step()/run() from Model interface
+- :feature:`0` Revised interfaces to the grids
+- :feature:`0` Updated all support packages to most current versions
+
 - :release:`0.5.1 <2022.08.11>`
 - :support:`0` Completed initial unit tests
 - :support:`0` Added background info to READ ME

docs/index.rst

@@ -18,13 +18,49 @@ Introduction
 
 Kami is Agent-Based Modeling in Modern C++.
 
+Overview
+========
+
+Agent-based models (ABMs) are models for simulating the actions of
+individual actors within a provided environment to understand the
+behavior of the agents, most individually and collectively.  ABMs
+are particularly suited for addressing problems governed by nonlinear
+processes or where there is a wide variety of potential responses
+an individual agent may provide depending on the environment and
+behavior of other agents.  Because of this, ABMs have become powerful
+tools in both simulation and modeling, especially in public health
+and ecology, where they are also known as individual-based models.
+ABMs also provide support in economic, business, robotics, and many
+other fields.
+
+Design Objectives
+-----------------
+
+Kami provides agent-based modeling modern C++.  The objectives in
+writing Kami are that it be lightweight, memory-efficient, and fast.
+It should be possible to develop a simple working model in under
+one hour of C++ development time.  Accordingly, the platform is
+modeled on the Mesa_ library in Python, which itself was inspired
+by the MASON_ library in Java.
+
+Many ABM platforms are designed around interaction and real time
+observation of the agent dynamics.  Kami does not provide a
+visualization interface.  Instead, Kami is meant to be used for
+ABMs requiring many runs with different starting conditions.
+Accordingly, Kami is single-threaded and multiple cores should be
+taken advantage of through multiple parallel runs of the supervising
+model.
+
+..  _MASON: https://cs.gmu.edu/~eclab/projects/mason/
+..  _Mesa: https://mesa.readthedocs.io
+
 ..  toctree::
     :hidden:
     :maxdepth: 2
 
-    overview
     installation
     tutorial
     api/library_root
     changelog
+    todo
     license

docs/todo.rst

@@ -0,0 +1,24 @@
+To Do List
+==========
+
+Must Dos
+--------
+The list below is a list of things considered necessary before
+a 1.0 release.  This list is *not* static.
+
+- Network domain
+- Data collection process
+- Demonstration of data collection process
+- Tutorial write up
+
+Wishlist
+--------
+The list below is a list of things considered nice to have at
+any point.
+
+- Revise unit tests to take advantage of fixtures
+- Documentation with basic introduction to ABMs
+- Network Boltzmann model example
+- Additional examples as appropriate
+
+..  toctree::

examples/README.md

@@ -3,5 +3,5 @@
 Each folder in here is automatically traversed by the root level cmake list file.
 
 1. Copy one of the existing folders to a new name.
-2. The name of the folder will be the name of the library
+2. The name of the folder will be the name of the example
 3. Change the source file list.

examples/boltzmann1d/CMakeLists.txt

@@ -2,6 +2,8 @@
 # Set minimum version of CMake.
 cmake_minimum_required(VERSION 3.13)
 
+find_package(spdlog)
+
 set(EXAMPLE_NAME "boltzmann1d")
 
 project(${EXAMPLE_NAME} LANGUAGES CXX)

examples/boltzmann1d/boltzmann1d.cc

@@ -26,15 +26,14 @@
 #include "boltzmann1d.h"
 
 #include <exception>
+#include <list>
 #include <map>
 #include <memory>
 #include <optional>
 #include <random>
 #include <stdexcept>
 
-#include <CLI/App.hpp>
-#include <CLI/Config.hpp>
-#include <CLI/Formatter.hpp>
+#include <CLI/CLI.hpp>
 
 #include <spdlog/sinks/stdout_color_sinks.h>
 #include <spdlog/spdlog.h>
@@ -78,7 +77,7 @@ kami::AgentID MoneyAgent1D::step(std::shared_ptr<kami::Model> model) {
     return this->get_agent_id();
 }
 
-kami::GridCoord1D MoneyAgent1D::move_agent(std::shared_ptr<kami::Model> model) {
+std::optional<kami::GridCoord1D> MoneyAgent1D::move_agent(std::shared_ptr<kami::Model> model) {
     console->trace("Entering move_agent");
     auto agent_id = get_agent_id();
 
@@ -87,9 +86,12 @@ kami::GridCoord1D MoneyAgent1D::move_agent(std::shared_ptr<kami::Model> model) {
         throw (std::domain_error("model is missing domain"));
     auto world = std::static_pointer_cast<kami::MultiGrid1D>(domain.value());
 
-    auto move_list = world->get_neighborhood(agent_id, false);
+    auto move_list_opt = world->get_neighborhood(agent_id, false);
+    if (!move_list_opt)
+        return std::nullopt;
+    auto move_list = move_list_opt.value();
     std::uniform_int_distribution<int> dist(0, (int) move_list->size() - 1);
-    auto new_location = move_list->at(dist(*rng));
+    auto new_location = *std::next(move_list->begin(), dist(*rng));
 
     console->trace("Moving Agent {} to location {}", agent_id, new_location);
     world->move_agent(agent_id, new_location);
@@ -113,13 +115,17 @@ std::optional<kami::AgentID> MoneyAgent1D::give_money(std::shared_ptr<kami::Mode
     auto population = std::static_pointer_cast<kami::Population>(agents.value());
 
     auto location = world->get_location_by_agent(agent_id);
-    auto cell_mates = world->get_location_contents(location.value());
+    auto cell_mates_opt = world->get_location_contents(location.value());
+
+    if (!cell_mates_opt)
+        return std::nullopt;
 
+    auto cell_mates = cell_mates_opt.value();
     if (cell_mates->size() < 2)
         return std::nullopt;
 
     std::uniform_int_distribution<int> dist(0, (int) cell_mates->size() - 1);
-    kami::AgentID other_agent_id = cell_mates->at(dist(*rng));
+    auto other_agent_id = *std::next(cell_mates->begin(), dist(*rng));
     auto other_agent = std::static_pointer_cast<MoneyAgent1D>(population->get_agent_by_id(other_agent_id).value());
 
     console->trace("Agent {} giving unit of wealth to agent {}", agent_id, other_agent_id);
@@ -157,12 +163,6 @@ BoltzmannWealthModel1D::BoltzmannWealthModel1D(unsigned int number_agents, unsig
     }
 }
 
-std::shared_ptr<kami::Model> BoltzmannWealthModel1D::run(unsigned int steps) {
-    for (auto i = 0; i < steps; i++)
-        step();
-    return shared_from_this();
-}
-
 std::shared_ptr<kami::Model> BoltzmannWealthModel1D::step() {
     console->trace("Executing model step {}", ++_step_count);
     _sched->step(shared_from_this());
@@ -175,8 +175,14 @@ int main(int argc, char **argv) {
     CLI::App app{ident};
     unsigned int x_size = 16, agent_count = x_size, max_steps = 100, initial_seed = 42;
 
+    // This exercise is really stupid.
+    auto levels_list = std::make_unique<std::list<std::string>>();
+    for (auto &level_name: SPDLOG_LEVEL_NAMES)
+        levels_list->push_back(std::string(level_name.data(), level_name.size()));
+
     app.add_option("-c", agent_count, "Set the number of agents")->check(CLI::PositiveNumber);
-    app.add_option("-l", log_level_option, "Set the logging level")->check(CLI::IsMember(SPDLOG_LEVEL_NAMES));
+    app.add_option("-l", log_level_option, "Set the logging level")->check(
+            CLI::IsMember(levels_list.get(), CLI::ignore_case));
     app.add_option("-n", max_steps, "Set the number of steps to run the model")->check(CLI::PositiveNumber);
     app.add_option("-s", initial_seed, "Set the initial seed")->check(CLI::Number);
     app.add_option("-x", x_size, "Set the number of columns")->check(CLI::PositiveNumber);

examples/boltzmann1d/boltzmann1d.h

@@ -65,7 +65,7 @@ class MoneyAgent1D : public kami::Agent {
     /**
      * Move the agent to a random location on the world
      */
-    kami::GridCoord1D move_agent(std::shared_ptr<kami::Model> model);
+    std::optional<kami::GridCoord1D> move_agent(std::shared_ptr<kami::Model> model);
 
     /**
      * Give money to a random agent
@@ -96,14 +96,7 @@ class BoltzmannWealthModel1D : public kami::Model {
     /**
      * Execute a single time-step for the model.
      */
-    std::shared_ptr<kami::Model> step() override;
-
-    /**
-     * Execute a number of time-steps for the model.
-     *
-     * @param[in] n the number of steps to execute.
-     */
-    std::shared_ptr<kami::Model> run(unsigned int n) override;
+    std::shared_ptr<kami::Model> step();
 
 private:
     unsigned int _step_count;

examples/boltzmann2d/CMakeLists.txt

@@ -2,6 +2,8 @@
 # Set minimum version of CMake.
 cmake_minimum_required(VERSION 3.13)
 
+find_package(spdlog)
+
 set(EXAMPLE_NAME "boltzmann2d")
 
 project(${EXAMPLE_NAME} LANGUAGES CXX)