.. _sphx_glr_auto_examples_advanced:

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 id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. 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>


.. toctree::
   :hidden:

   /auto_examples/advanced/example_custom_roles
   /auto_examples/advanced/example_custom_events
   /auto_examples/advanced/example_custom_relationships
   /auto_examples/advanced/example_custom_pipeline