Tutorials
=========

Step-by-step tutorials to help you learn JaxABM concepts and techniques.

Getting Started
---------------

.. toctree::
   :maxdepth: 1

   basic_model
   adding_agents
   running_simulations

Core Concepts
-------------

.. toctree::
   :maxdepth: 1

   agent_behaviors
   environment_state
   parameter_spaces

Advanced Topics
---------------

.. toctree::
   :maxdepth: 1

   jax_optimization
   gpu_acceleration
   custom_metrics

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

**Basic Model Creation**
   Learn how to create your first JaxABM model with simple agents and basic behaviors.

**Agent Behaviors**
   Understand how to define complex agent behaviors and interactions.

**Parameter Calibration**
   Master the art of finding optimal parameters for your models using various methods.

**Sensitivity Analysis**
   Learn to identify which parameters most influence your model outcomes.

**Performance Optimization**
   Discover how to make your models run faster using JAX transformations.

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

Before starting these tutorials, make sure you have:

1. **JaxABM installed**: See :doc:`../installation`
2. **Basic Python knowledge**: Familiarity with Python syntax
3. **NumPy basics**: Understanding of array operations
4. **Optional: JAX knowledge**: Helpful but not required

Learning Path
-------------

We recommend following this sequence:

1. Start with :doc:`basic_model` to understand core concepts
2. Move to :doc:`adding_agents` to learn about agent creation
3. Practice with :doc:`running_simulations` for execution basics
4. Explore :doc:`agent_behaviors` for advanced agent programming
5. Master :doc:`../calibration/index` for parameter optimization

Each tutorial includes:

- **Conceptual explanation** of the topic
- **Complete code examples** you can run
- **Exercises** to test your understanding
- **Common pitfalls** and how to avoid them
- **Next steps** for further learning

Need Help?
----------

If you get stuck:

1. Check the :doc:`../api/index` for detailed function documentation
2. Look at :doc:`../examples/index` for more complete examples
3. Review the troubleshooting sections in each guide
4. Open an issue on GitHub for bugs or unclear documentation