:orphan:

Examples
========

Example scripts demonstrating BAM Engine usage patterns.

The examples are organized into three sections:

- **Basic**: Getting started tutorials for new users
- **Advanced**: Custom components and pipeline modifications
- **Extensions**: Scenarios from the BAM literature

These examples are simplified demonstrations focused on teaching core concepts.
For detailed analysis with validation bounds and statistical annotations, see
the ``validation`` package:

.. code-block:: bash

   # Baseline scenario with full validation
   python -m validation.scenarios.baseline

   # Growth+ scenario with full validation
   python -m validation.scenarios.growth_plus



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Basic Examples
==============

Start here if you're new to BAM Engine. These examples demonstrate fundamental
concepts and basic usage patterns.

Examples in this section:

1. **Hello World**: The simplest possible BAM Engine example - initialize, run, and visualize
2. **Configuration**: Customize simulation parameters using keyword arguments
3. **YAML Configuration**: Configure simulations using YAML files
4. **Logging**: Configure logging levels globally and per-event
5. **BAM Operations**: Comprehensive guide to the ops module for NumPy-free array operations
6. **Type System**: Using Float, Int, Bool, Agent type aliases for custom roles
7. **Simulation Results**: Comprehensive guide to SimulationResults for data collection
8. **Baseline Scenario**: Simplified baseline scenario from section 3.9.1 of the original BAM book

These examples will teach you:

* How to initialize and run a basic simulation
* How to configure simulation parameters via kwargs and YAML files
* How to collect and visualize simulation results
* How to compare different economic scenarios
* How to reproduce scenarios from the BAM literature
* How to use type aliases for extending BAM Engine
* How to configure and use the logging system

Note: The baseline scenario example is a simplified demonstration. For full
validation with target bounds and statistical annotations, run:

.. code-block:: bash

   python -m validation.scenarios.baseline



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This is the simplest possible BAM Engine example. It shows how to initialize a simulation, run it for a few periods, and display basic results.">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_hello_world_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_hello_world`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Hello BAM Engine</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to customize simulation parameters using keyword arguments. You can override any default parameter to explore different economic scenarios.">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_configuration_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_configuration`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Configuring Your Simulation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to configure BAM Engine simulations using YAML files. YAML configuration is useful for:">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_yaml_configuration_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_yaml_configuration`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">YAML Configuration</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates BAM Engine&#x27;s logging system. Learn how to:">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_logging_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_logging`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Logging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example provides a comprehensive guide to the ops module, which offers NumPy-free array operations for writing custom events. The ops module makes BAM Engine accessible to economists who may not be familiar with NumPy.">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_ops_module_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_ops_module`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">BAM Operations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates BAM Engine&#x27;s type aliases for defining custom roles and components. These types hide NumPy complexity while maintaining full type safety.">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_typing_module_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_typing_module`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Type System</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to collect and analyze simulation results using the SimulationResults class. Learn how to:">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_results_module_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_results_module`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Simulation Results</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example reproduces the baseline scenario from section 3.9.1 of the original BAM model book (Delli Gatti et al., 2011). This scenario demonstrates the fundamental dynamics of the model with standard parameter values.">

.. only:: html

  .. image:: /auto_examples/basic/images/thumb/sphx_glr_example_baseline_scenario_thumb.png
    :alt:

  :doc:`/auto_examples/basic/example_baseline_scenario`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">BAM Baseline Scenario</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Advanced Examples
=================

Examples showing advanced features like custom events, roles, relationships,
and pipeline configuration. These examples require familiarity with the basic
concepts covered in the basic examples.

Examples in this section:

1. **Custom Roles**: Define new agent components with the ``@role`` decorator
2. **Custom Events**: Create custom events with the ``@event`` decorator
3. **Custom Relationships**: Define many-to-many relationships with edge data
4. **Custom Pipeline**: Customize the event execution pipeline via YAML
5. **Ops Module**: NumPy-free operations for custom event logic

These examples will teach you:

* How to extend the model with custom agent behaviors using roles
* How to create custom economic events and policies
* How to define relationships between roles with edge-specific data
* How to modify the event execution order
* How to use the ops module for safe array operations
* How to integrate custom components into simulations

Prerequisites
-------------

Before working through these examples, make sure you're comfortable with:

* Basic simulation setup (see basic/example_hello_world.py)
* Configuration via kwargs (see basic/example_configuration.py)
* Results collection (see basic/example_results_module.py)
* Type aliases (see basic/example_typing_module.py)



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to create custom roles (components) to extend BAM Engine with new agent behaviors and state. Custom roles are essential for modeling economic phenomena not covered by the built-in roles.">

.. only:: html

  .. image:: /auto_examples/advanced/images/thumb/sphx_glr_example_custom_roles_thumb.png
    :alt:

  :doc:`/auto_examples/advanced/example_custom_roles`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom Roles</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to create custom events (systems) to extend BAM Engine with new economic mechanisms. Custom events can implement policies, shocks, regulations, or any periodic process.">

.. only:: html

  .. image:: /auto_examples/advanced/images/thumb/sphx_glr_example_custom_events_thumb.png
    :alt:

  :doc:`/auto_examples/advanced/example_custom_events`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom Events</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to define many-to-many relationships between agents using the @relationship decorator. Relationships are essential for modeling network effects, supply chains, and multi-agent interactions.">

.. only:: html

  .. image:: /auto_examples/advanced/images/thumb/sphx_glr_example_custom_relationships_thumb.png
    :alt:

  :doc:`/auto_examples/advanced/example_custom_relationships`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom Relationships</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to customize the event execution pipeline using YAML configuration. Custom pipelines let you reorder events, add custom events, or remove built-in events.">

.. only:: html

  .. image:: /auto_examples/advanced/images/thumb/sphx_glr_example_custom_pipeline_thumb.png
    :alt:

  :doc:`/auto_examples/advanced/example_custom_pipeline`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom Pipeline</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Extension Examples
==================

Examples demonstrating extensions from the original BAM model
(Delli Gatti et al., 2011).

These examples reproduce research extensions from the BAM book:

* **Growth+ Model**: R&D investment and endogenous productivity growth.
  Demonstrates how to create custom roles and events to extend BAM Engine.
* **Consumption and Buffer Shock**: Household consumption shocks and savings buffer dynamics
* **Parameter Space Exploration**: Systematic exploration of model sensitivity to key parameters
* **Preferential Attachment**: Preferential attachment in consumption and firm entry mechanisms

Each example includes detailed explanations of the economic mechanisms and
comparison with results from the original literature.

Note: The Growth+ example is a simplified demonstration focused on teaching
how to create custom extensions. For full validation with target bounds and
statistical annotations, run:

.. code-block:: bash

   python -m validation.scenarios.growth_plus



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example implements the Growth+ extension from chapter 3.8 of Macroeconomics from the Bottom-up, demonstrating endogenous productivity growth based on R&amp;D investment.">

.. only:: html

  .. image:: /auto_examples/extensions/images/thumb/sphx_glr_example_growth_plus_thumb.png
    :alt:

  :doc:`/auto_examples/extensions/example_growth_plus`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Growth+ Model Extension</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example implements the buffer-stock consumption extension from Section 3.9.4 of Macroeconomics from the Bottom-up, replacing the baseline mean-field MPC with an individual adaptive rule based on buffer-stock saving theory.">

.. only:: html

  .. image:: /auto_examples/extensions/images/thumb/sphx_glr_example_buffer_stock_thumb.png
    :alt:

  :doc:`/auto_examples/extensions/example_buffer_stock`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Buffer-Stock Consumption Extension</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates robustness analysis inspired by Section 3.10 of Macroeconomics from the Bottom-up (Delli Gatti et al., 2011).">

.. only:: html

  .. image:: /auto_examples/extensions/images/thumb/sphx_glr_example_robustness_thumb.png
    :alt:

  :doc:`/auto_examples/extensions/example_robustness`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Robustness Analysis</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/basic/index.rst
   /auto_examples/advanced/index.rst
   /auto_examples/extensions/index.rst



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_