docs(examples): Added documentation for each example

docs/examples/bankreserves.rst

@@ -0,0 +1,56 @@
+bankreserves
+============
+
+This example provides a two-dimensional bank reserves model (BSM)
+as an example of a simple application of the reporter classes for
+monitoring the internal functioning of the model.
+
+The BSM is a type of computational model that simulates the behavior
+of customers and their interactions with a bank. It is used to study
+the dynamics of the money supply and the management of reserves by
+the bank.
+
+In a BSM, individuals are represented as autonomous agents that
+make decisions about saving, borrowing, and repaying loans based
+on their individual objectives and constraints. The bank is also
+represented as an agent that maintains accounts for each individual.
+The interactions between individuals and the bank are simulated
+over time, and the model can be used to study the effects of different
+reserve requirements policies on the creation of money, borrowing,
+lending, and savings.
+
+One of the main advantages of a BSM is that it allows for the
+examination of the micro-level interactions between individuals and
+the bank, which can provide a more detailed understanding of the
+dynamics of the monetary system.
+
+It is important to note that BSMs are a simplified representation
+of the real world and may not capture all the nuances of the monetary
+system being studied. It's also important to use this model in
+conjunction with other methods to fully understand the monetary
+system.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - -c *agent_count*
+     - Set the number of agents
+   * - -f *output_file_name*
+     - Set the JSON report file
+   * - -l *log_level_option*
+     - Set the logging level
+   * - -n *max_steps*
+     - Set the number of steps to run the model
+   * - -s *initial_seed*
+     - Set the initial seed
+   * - -x *x_size*
+     - Set the number of columns
+   * - -y *y_size*
+     - Set the number of rows
+   * - -w *max_initial_wealth*
+     - Set the maximum initial agent wealth
+
+..  toctree::

docs/examples/boltzmann1d.rst

@@ -0,0 +1,60 @@
+boltzmann1d
+===========
+
+This example provides a one-dimensional Boltzmann wealth model (BWM)
+as an example of a simple application of the one-dimensional gridded
+system.
+
+The BWM is a type of agent-based model used to study the distribution
+of wealth among individuals or agents within a population. The model
+is named after the physicist Ludwig Boltzmann, who first proposed
+a similar model to study the distribution of energy among particles
+in a gas.
+
+In a BWM, agents are assigned a certain amount of wealth, and the
+model simulates their interactions over time.  These interactions
+can include buying and selling goods and services, lending and
+borrowing money, and inheriting wealth from other agents.
+
+The key feature of the BWM is that it incorporates a "wealth-exchange
+mechanism" which determines the probability of agents making a
+wealth exchange with each other. This mechanism is often based on
+the difference in wealth between agents, with wealthier agents more
+likely to make exchanges with other wealthy agents.
+
+The model can be run for a specified number of time steps, and the
+resulting wealth distribution can be analyzed to study the emergence
+of wealth inequality and the factors that contribute to it. The
+model can also be used to study the effects of different policies
+or interventions on the wealth distribution.
+
+The BWM has been used to study a variety of different economic
+systems, including capitalist, socialist, and feudal systems.
+However, it is important to note that like other agent-based models,
+the BWM is a simplified representation of the real world and may
+not capture all the nuances of the economic system being studied.
+
+Overall, the BWM is a useful tool for studying the distribution of
+wealth and the emergence of wealth inequality in a population. It
+can provide insight into the factors that contribute to wealth
+inequality and the effects of different policies on the distribution
+of wealth.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - -c *agent_count*
+     - Set the number of agents
+   * - -l *log_level_option*
+     - Set the logging level
+   * - -n *max_steps*
+     - Set the number of steps to run the model
+   * - -s *initial_seed*
+     - Set the initial seed
+   * - -x *x_size*
+     - Set the number of columns
+
+..  toctree::

docs/examples/boltzmann2d.rst

@@ -0,0 +1,43 @@
+boltzmann2d
+===========
+
+This example provides a two-dimensional Boltzmann wealth model (BWM)
+as an example of a simple application of the two-dimensional gridded
+system.
+
+The BWM is a type of agent-based model used to study the distribution
+of wealth among individuals within a population. The model simulates
+agents' interactions over time, such as buying and selling goods,
+lending and borrowing money, and inheriting wealth. The model is
+based on a "wealth-exchange mechanism" which determines the probability
+of agents making a wealth exchange with each other, it is often
+based on the difference in wealth between agents. The model can be
+run for a specified number of time steps, and the resulting wealth
+distribution can be analyzed to study the emergence of wealth
+inequality and the factors that contribute to it.
+
+For more information on BWMs, please see the boltzmann1d_
+example documentation.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - -c *agent_count*
+     - Set the number of agents
+   * - -l *log_level_option*
+     - Set the logging level
+   * - -n *max_steps*
+     - Set the number of steps to run the model
+   * - -s *initial_seed*
+     - Set the initial seed
+   * - -x *x_size*
+     - Set the number of columns
+   * - -y *y_size*
+     - Set the number of rows
+
+..  _boltzmann1d: boltzmann1d.html
+
+..  toctree::

docs/examples/index.rst

@@ -0,0 +1,21 @@
+Examples
+========
+
+* bankreserves_
+* boltzmann1d_
+* boltzmann2d_
+* starter_
+
+..  _bankreserves: bankreserves.html
+..  _boltzmann1d: boltzmann1d.html
+..  _boltzmann2d: boltzmann2d.html
+..  _starter: starter.html
+
+..  toctree::
+    :hidden:
+    :maxdepth: 1
+
+    bankreserves
+    boltzmann1d
+    boltzmann2d
+    starter

docs/examples/starter.rst

@@ -0,0 +1,24 @@
+starter
+=======
+
+This example provides a starter scaffold for beginning a new
+agent-based model (ABM).  The agents and models perform no real
+functions in the starter and is likely to be the most minimum
+functioning model.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - -c *agent_count*
+     - Set the number of agents
+   * - -l *log_level_option*
+     - Set the logging level
+   * - -n *max_steps*
+     - Set the number of steps to run the model
+   * - -s *initial_seed*
+     - Set the initial seed
+
+..  toctree::

docs/index.rst

@@ -65,6 +65,7 @@ model.
     abm
     tutorial
     api/library_root
+    examples/index
     changelog
     todo
     license