From 0d75e3b691e5ebda1f221a424ef26e67be714158 Mon Sep 17 00:00:00 2001 From: "James P. Howard, II" Date: Sat, 21 Jan 2023 21:50:01 -0500 Subject: [PATCH] docs(examples): Added documentation for each example --- docs/examples/bankreserves.rst | 56 +++++++++++++++++++++++++++++++ docs/examples/boltzmann1d.rst | 60 ++++++++++++++++++++++++++++++++++ docs/examples/boltzmann2d.rst | 43 ++++++++++++++++++++++++ docs/examples/index.rst | 21 ++++++++++++ docs/examples/starter.rst | 24 ++++++++++++++ docs/index.rst | 1 + 6 files changed, 205 insertions(+) create mode 100644 docs/examples/bankreserves.rst create mode 100644 docs/examples/boltzmann1d.rst create mode 100644 docs/examples/boltzmann2d.rst create mode 100644 docs/examples/index.rst create mode 100644 docs/examples/starter.rst diff --git a/docs/examples/bankreserves.rst b/docs/examples/bankreserves.rst new file mode 100644 index 0000000..be915f9 --- /dev/null +++ b/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:: diff --git a/docs/examples/boltzmann1d.rst b/docs/examples/boltzmann1d.rst new file mode 100644 index 0000000..958190c --- /dev/null +++ b/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:: diff --git a/docs/examples/boltzmann2d.rst b/docs/examples/boltzmann2d.rst new file mode 100644 index 0000000..1ef9624 --- /dev/null +++ b/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:: diff --git a/docs/examples/index.rst b/docs/examples/index.rst new file mode 100644 index 0000000..b9b7674 --- /dev/null +++ b/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 diff --git a/docs/examples/starter.rst b/docs/examples/starter.rst new file mode 100644 index 0000000..207a609 --- /dev/null +++ b/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:: diff --git a/docs/index.rst b/docs/index.rst index 035455f..a70dcf0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,6 +65,7 @@ model. abm tutorial api/library_root + examples/index changelog todo license \ No newline at end of file