docs(tutorial): Add the long-awaited tutorial

docs/tutorial.rst

@@ -1,55 +1,108 @@
 Tutorial
 ========
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
-varius est at dignissim sodales. Nullam mauris velit, imperdiet sit
-amet neque nec, fringilla consectetur odio. In non erat varius,
-fringilla felis ut, sodales orci. Aliquam in turpis ultricies enim
-accumsan commodo. Duis at dolor quis dolor tristique suscipit eget
-at magna. Integer non eros vitae ipsum pellentesque pharetra ac sed
-sapien. Duis justo diam, bibendum ut ullamcorper ac, viverra sit
-amet risus. Curabitur blandit nisl ac posuere fermentum. Nulla
-convallis purus id velit pellentesque tempus. Pellentesque euismod
-augue non diam eleifend fermentum. Vestibulum ante ipsum primis in
-faucibus orci luctus et ultrices posuere cubilia curae;
+Kami's interface is heavily influenced by Mesa_'s interface.  However,
+by being written in C++, Kami runs substantially faster.  This
+allows for faster runs and more runs within a fixed amount of time.
+The advantage here is that an agent-based model (ABM) built on the
+Kami platform is better suited for statistical and Monte Carlo
+approaches to modelling.
 
-Nulla iaculis orci neque, a rhoncus mi vestibulum vitae. Nam ut
-gravida magna. Nam vel dignissim lacus, id accumsan orci. Nullam
-cursus, dui nec finibus sagittis, nisi purus feugiat tortor, a
-aliquet quam metus eget enim. Cras et quam vitae nisi auctor varius
-eget vel lacus. In nibh orci, tempus eu odio et, euismod sodales
-nulla. Fusce luctus sit amet orci non interdum. Ut cursus volutpat
-feugiat. Nulla vitae ultricies augue. Donec orci dolor, convallis
-non tincidunt sit amet, consectetur ut nibh. Cras efficitur dictum
-eros, faucibus pretium odio rutrum at.
+Model Form
+----------
 
-Phasellus lobortis ex nec felis iaculis tincidunt. Sed consequat
-sagittis urna at lobortis. Cras velit lorem, iaculis non felis et,
-sodales tempus erat. Mauris in ultricies metus. Ut bibendum nisl
-vel lectus consequat, vel pharetra est ultrices. Aliquam non lobortis
-massa. Mauris euismod turpis mi, eu tempor lectus molestie in. Donec
-auctor ante sed eros scelerisque volutpat. Morbi semper diam vitae
-ante feugiat, eu hendrerit felis aliquet. Sed placerat velit sit
-amet odio suscipit, a posuere lectus hendrerit. Nulla felis augue,
-cursus a tempus vitae, ullamcorper a ante. Aenean et elit mi.
-Suspendisse potenti. Mauris ac enim libero. Donec finibus id enim
-ut ullamcorper. Suspendisse eu imperdiet tellus.
+Kami-based models have five key components:
 
-Cras commodo vitae massa ac blandit. Donec ut mauris at lectus
-congue euismod in eleifend felis. Mauris id sapien orci. Cras ac
-enim et lectus fringilla vestibulum. Aliquam varius est mattis
-condimentum finibus. Nunc tristique justo nec nunc mollis, sit amet
-tempor neque iaculis. Class aptent taciti sociosqu ad litora torquent
-per conubia nostra, per inceptos himenaeos. Vestibulum ante ipsum
-primis in faucibus orci luctus et ultrices posuere cubilia curae;
-In commodo molestie porttitor. Duis blandit ligula a purus bibendum
-volutpat id in metus. Cras bibendum vel ex in accumsan. Phasellus
-congue ex eu scelerisque consectetur.
+1. Agents, which are objects representing the actors within the model
+2. Populations, which are collections of Agents
+3. Domains, which provide a representation of "physical" space the Agent inhabits
+4. Schedulers, which provide a representation of "time" within the model
+5. Model, which are objects connecting Populations, Domains, and Schedulers
 
-Maecenas pellentesque eget quam ac pellentesque. Morbi id tempus
-urna. In accumsan molestie neque nec imperdiet. Nam ultricies lacinia
-magna. Nullam dictum, massa ac fermentum rhoncus, lacus eros
-pellentesque ante, sed sollicitudin eros est in dui. Interdum et
-malesuada fames ac ante ipsum primis in faucibus. Integer porttitor,
-ante id bibendum volutpat, mi nunc mollis eros, sed auctor turpis
-mi et sem.
+In general, a model should have one scheduler, one domain, and some
+number of agents.  However, it would not be impossible to have more
+than one scheduler or more than one domain.  Because this is
+implemented in C++, your agents should subclass Agent and your model
+should subclass model.  The schedulers and domains are sufficient
+as is for their purposes though custom schedulers and domains are
+not unreasonable.
+
+A Minimal ABM
+-------------
+
+The minimal ABM starts with the simplest possible agent.  Here, we
+create a class called ``MinimalAgent``:
+
+.. code-block:: c++
+  :linenos:
+
+    class MinimalAgent : public kami::Agent {
+    public:
+        kami::AgentID step(std::shared_ptr<kami::Model> model) override {
+            return this->get_agent_id();
+        }
+    };
+
+An ``Agent``, and its subclasses, will automatically inherit an ``AgentID``,
+which is the unique identifier for the session.  The only explicit
+requirement on the ``Agent`` subclass is a `step()` method that accepts
+a ``shared_ptr`` to a ``Model`` and it must return the ``Agent``'s ``AgentID``.
+Obviously, an ``Agent`` should do something useful before returning.
+
+The second component is ``MinimalModel:``
+
+.. code-block:: c++
+  :linenos:
+
+  class MinimalModel: public kami::Model {
+  public:
+      MinimalModel() {
+          auto sched = std::make_shared<kami::SequentialScheduler>();
+          set_scheduler(sched);
+
+          auto pop = std::make_shared<kami::Population>();
+          set_population(pop);
+
+          for (auto i = 0; i < 10; i++) {
+              auto new_agent = std::make_shared<MinimalAgent>();
+              pop->add_agent(new_agent);
+          }
+      }
+  };
+
+The ``MinimalModel`` performs some important tasks that important to do
+during the setup or soon thereafter.  In the constructor, first, a
+scheduler is created.  The ``SequentialScheduler`` is the simplest
+scheduler and has no configuration needed.  Using `set_scheduler()`,
+part of the Model class, the scheduler is associated with this
+model.  Second, a `Population` is created and associated with this
+model with the `set_population()` method.
+
+After this, the constructor initializes 10 ``MinimalAgents`` and adds
+them to the population.
+
+.. code-block:: c++
+  :linenos:
+
+  int main() {
+      auto model = std::make_shared<MinimalModel>();
+
+      for (int i = 0; i < 10; i++)
+          model->step();
+
+      return 0;
+  }
+
+The last part is our `main()` function.  It creates the `MinimalModel`
+then executes its `step()` method 10 times.  The `step()` method, by
+default, calls the `step()` method of the scheduler.  In the case of
+the ``SequentialScheduler``, it loops over all the ``Agent`` instances in the
+``Population`` and executes the associated `step()` method of each ``Agent``.
+
+That is it.  It is the simplest minimal model that can be created
+using the Kami platform.  However, for a basis, it is likely better
+to use the starter model, included in the examples directory.
+
+..  _Mesa: https://mesa.readthedocs.io
+
+..  toctree::

examples/minimal/minimal.cc

@@ -33,7 +33,7 @@
 #include <kami/population.h>
 #include <kami/sequential.h>
 
-class MinimumAgent
+class MinimalAgent
         : public kami::Agent {
 public:
     kami::AgentID step(std::shared_ptr<kami::Model> model) override {
@@ -41,22 +41,25 @@ public:
     }
 };
 
-class MinimumModel
+class MinimalModel
         : public kami::Model {
 public:
-    MinimumModel() {
-        _sched = std::make_shared<kami::SequentialScheduler>();
-        _pop = std::make_shared<kami::Population>();
+    MinimalModel() {
+        auto sched = std::make_shared<kami::SequentialScheduler>();
+        set_scheduler(sched);
+
+        auto pop = std::make_shared<kami::Population>();
+        set_population(pop);
 
         for (auto i = 0; i < 10; i++) {
-            auto new_agent = std::make_shared<MinimumAgent>();
-            _pop->add_agent(new_agent);
+            auto new_agent = std::make_shared<MinimalAgent>();
+            pop->add_agent(new_agent);
         }
     }
 };
 
 int main() {
-    auto model = std::make_shared<MinimumModel>();
+    auto model = std::make_shared<MinimalModel>();
 
     for (int i = 0; i < 10; i++)
         model->step();