User Tutorials and How-To Guides
=================================

Welcome to the comprehensive tutorial series for the Ergodic Insurance Framework. These hands-on guides will walk you through everything from basic setup to advanced insurance optimization strategies.

.. note::
   **New to the framework?** Start with :doc:`01_getting_started` to get up and running in minutes!

Tutorial Overview
-----------------

Our tutorials are designed to take you from beginner to expert:

1. **Getting Started** - Installation, setup, and your first simulation
2. **Basic Simulation** - Understanding the simulation engine and parameters
3. **Configuring Insurance** - Setting up single and multi-layer insurance programs
4. **Optimization Workflow** - Finding optimal insurance strategies
5. **Analyzing Results** - Interpreting metrics and making decisions
6. **Advanced Scenarios** - Real-world applications and complex strategies

Quick Start Path
----------------

Depending on your role and objectives, follow these recommended paths:

**For Actuaries and Risk Managers:**
   1. :doc:`01_getting_started`
   2. :doc:`03_configuring_insurance`
   3. :doc:`05_analyzing_results`

**For Financial Analysts:**
   1. :doc:`01_getting_started`
   2. :doc:`04_optimization_workflow`
   3. :doc:`05_analyzing_results`

**For Developers and Researchers:**
   1. :doc:`02_basic_simulation`
   2. :doc:`04_optimization_workflow`
   3. :doc:`06_advanced_scenarios`

Tutorials
---------

.. toctree::
   :numbered:
   :maxdepth: 2
   :caption: Step-by-Step Tutorials:

   01_getting_started
   02_basic_simulation
   03_configuring_insurance
   04_optimization_workflow
   05_analyzing_results
   06_advanced_scenarios

Support Resources
-----------------

.. toctree::
   :maxdepth: 1
   :caption: Help & Support:

   troubleshooting

Learning Objectives
-------------------

By completing these tutorials, you will be able to:

* **Set up and run** insurance simulations for your specific use case
* **Configure** complex multi-layer insurance programs
* **Optimize** insurance parameters for maximum growth while controlling risk
* **Analyze** results using ergodic theory principles
* **Apply** the framework to real-world business scenarios
* **Troubleshoot** common issues and optimize performance

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

**Required:**
   * Python 3.12 or higher
   * Basic Python knowledge (running scripts, installing packages)

**Helpful but not required:**
   * Understanding of insurance concepts (retention, limits, premiums)
   * Basic statistics knowledge (distributions, averages)
   * Familiarity with financial metrics (ROE, ROA)

Interactive Learning
--------------------

All tutorials include:

* **Working code examples** that you can run immediately
* **Visualizations** to understand concepts intuitively
* **Best practices** from real-world applications
* **Common pitfalls** and how to avoid them
* **Exercises** to test your understanding

Code Examples
-------------

All code examples in these tutorials are:

* ✅ **Tested** - Every example has been verified to work
* ✅ **Complete** - Full working code, not just snippets
* ✅ **Documented** - Clear comments explaining each step
* ✅ **Practical** - Based on real-world use cases

Getting Help
------------

If you encounter issues:

1. Check the :doc:`troubleshooting` guide for common problems
2. Review the example notebooks in ``ergodic_insurance/notebooks/``
3. Consult the :doc:`../api/modules` for detailed function documentation
4. File an issue on `GitHub <https://github.com/AlexFiliakov/Ergodic-Insurance-Limits/issues>`__

Tutorial Notebooks
------------------

Jupyter notebook versions of these tutorials are available in:
``ergodic_insurance/notebooks/tutorials/``

These notebooks allow you to:

* Run code interactively
* Modify parameters and see results immediately
* Save your own experiments and notes
* Share analyses with colleagues

Next Steps
----------

Ready to begin? Start with :doc:`01_getting_started` to install the framework and run your first simulation!

For those who prefer learning by example, check out our :doc:`../examples` section for complete working demonstrations.

.. note::
   **Time Investment:** Each tutorial takes approximately 30-45 minutes to complete. The entire series can be completed in about 4 hours.

For Help
--------

* Check the :doc:`../user_guide/faq` for common questions
* Consult the :doc:`../user_guide/glossary` for term definitions
* Review example notebooks in ``ergodic_insurance/notebooks/``
* Open an issue on `GitHub <https://github.com/AlexFiliakov/Ergodic-Insurance-Limits/issues>`__
* Contact: Alex Filiakov (alexfiliakov@gmail.com)

Happy Learning!
---------------

We're excited to help you master insurance optimization using ergodic theory. These tutorials represent the culmination of extensive research and real-world application.

Let's transform insurance from a cost center to a growth enabler! 🚀