.. _sphx_glr_auto_examples_basic:

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>


.. toctree::
   :hidden:

   /auto_examples/basic/example_hello_world
   /auto_examples/basic/example_configuration
   /auto_examples/basic/example_yaml_configuration
   /auto_examples/basic/example_logging
   /auto_examples/basic/example_ops_module
   /auto_examples/basic/example_typing_module
   /auto_examples/basic/example_results_module
   /auto_examples/basic/example_baseline_scenario