Added starter example

docs/changelog.rst

@@ -1,6 +1,7 @@
 Changelog
 =========
 
+- :feature:`0` Added a barebones "starter" model to build from
 - :support:`0` Numerous documentation cleanups
 - :bug:`0` Numerous code cleanups to remove void returns and eliminate stored Model references
 - :feature:`0` Restructured the entire interface

examples/starter/CMakeLists.txt

@@ -0,0 +1,18 @@
+####
+# Set minimum version of CMake.
+cmake_minimum_required(VERSION 3.13)
+
+set(EXAMPLE_NAME "starter")
+
+project(${EXAMPLE_NAME} LANGUAGES CXX)
+
+create_executable(
+        NAME ${EXAMPLE_NAME}
+        SOURCES starter.cc
+        PUBLIC_DEFINITIONS USE_DOUBLE_PRECISION=1
+        PRIVATE_DEFINITIONS DEBUG_VERBOSE
+        PRIVATE_INCLUDE_PATHS ${CMAKE_SOURCE_DIR}/include
+        PUBLIC_LINKED_TARGETS fmt spdlog kami::libkami
+)
+
+set_target_properties(${EXAMPLE_NAME} PROPERTIES VERSION ${KAMI_VERSION_STRING})

examples/starter/starter.cc

@@ -0,0 +1,114 @@
+/*-
+ * Copyright (c) 2020 The Johns Hopkins University Applied Physics
+ * Laboratory LLC
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "starter.h"
+
+#include <map>
+#include <memory>
+#include <random>
+
+#include <CLI/App.hpp>
+#include <CLI/Config.hpp>
+#include <CLI/Formatter.hpp>
+
+#include <spdlog/sinks/stdout_color_sinks.h>
+#include <spdlog/spdlog.h>
+#include <spdlog/stopwatch.h>
+
+#include <kami/agent.h>
+#include <kami/kami.h>
+#include <kami/model.h>
+#include <kami/population.h>
+#include <kami/random.h>
+
+std::shared_ptr<spdlog::logger> console = nullptr;
+std::shared_ptr<std::ranlux24> rng = nullptr;
+
+template <>
+struct fmt::formatter<kami::AgentID> : fmt::formatter<std::string> {
+    static auto format(kami::AgentID agent_id, format_context &ctx) {
+        return format_to(ctx.out(), "{}", agent_id.to_string());
+    }
+};
+
+kami::AgentID StarterAgent::step(std::shared_ptr<kami::Model> model) {
+    this->_step_counter++;
+    return this->get_agent_id();
+}
+
+StarterModel::StarterModel(unsigned int number_agents, unsigned int new_seed) {
+    rng = std::make_shared<std::ranlux24>();
+    rng->seed(new_seed);
+
+    auto sched = std::make_shared<kami::RandomScheduler>(rng);
+    auto pop = std::make_shared<kami::Population>();
+
+    _sched = sched;
+    _pop = pop;
+
+    console->debug("Scheduler initiated with seed {}", new_seed);
+
+    _step_count = 0;
+
+    for (unsigned int i = 0; i < number_agents; i++) {
+        auto new_agent = std::make_shared<StarterAgent>();
+
+        console->trace("Initializing agent with AgentID {}", new_agent->get_agent_id());
+        _pop->add_agent(new_agent);
+    }
+}
+
+void StarterModel::run(unsigned int steps) {
+    for (auto i = 0; i < steps; i++) step();
+}
+
+void StarterModel::step() {
+    console->trace("Executing model step {}", ++_step_count);
+    _sched->step(shared_from_this());
+}
+
+int main(int argc, char **argv) {
+    std::string ident = "starter";
+    std::string log_level_option = "info";
+    CLI::App app{ident};
+    unsigned int agent_count = 100, max_steps = 100, initial_seed = 42;
+
+    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("-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);
+    CLI11_PARSE(app, argc, argv);
+
+    console = spdlog::stdout_color_st(ident);
+    console->set_level(spdlog::level::from_str(log_level_option));
+    console->info("Compiled with Kami/{}, log level {}", kami::version.to_string(), log_level_option);
+    console->info("Starting Starter Model with {} agents for {} steps", agent_count, max_steps);
+
+    auto model = std::make_shared<StarterModel>(agent_count, initial_seed);
+
+    spdlog::stopwatch sw;
+    for(int i = 0; i < max_steps; i++) model->step();
+    console->info("Starter Model simulation complete, requiring {} seconds", sw);
+}

examples/starter/starter.h

@@ -0,0 +1,81 @@
+/*-
+ * Copyright (c) 2022 The Johns Hopkins University Applied Physics
+ * Laboratory LLC
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#pragma once
+#ifndef STARTER_H
+#define STARTER_H
+
+#include <iostream>
+#include <map>
+
+#include <kami/agent.h>
+#include <kami/kami.h>
+#include <kami/multigrid1d.h>
+#include <kami/random.h>
+
+/**
+ * A starter agent for a starter model
+ */
+class StarterAgent : public kami::Agent {
+    int _step_counter = 0;
+
+public:
+    /**
+     * Execute a single time-step for the agent
+     */
+    kami::AgentID step(std::shared_ptr<kami::Model> model) override;
+};
+
+/**
+ * The one-dimensional Boltzmann wealth model
+ */
+class StarterModel : public kami::Model {
+private:
+    unsigned int _step_count;
+
+public:
+    /**
+     * Create an instance of the one-dimensional Boltzmann wealth model.
+     *
+     * @param[in] number_agents the number of agents to assign to the model.
+     * @param[in] length_x the length of the one-dimensional world the agents
+     * occupy.
+     */
+    explicit StarterModel(unsigned int number_agents = 10, unsigned int new_seed = 42);
+
+    /**
+     * Execute a single time-step for the model.
+     */
+    void step() override;
+
+    /**
+     * Execute a number of time-steps for the model.
+     *
+     * @param[in] n the number of steps to execute.
+     */
+    void run(unsigned int n) override;
+};
+
+#endif  // STARTER_H