example: add surrogate modeling demonstration with scikit-learn

[Nithurshen]

Summary

This PR adds a new example, surrogate_modeling, which demonstrates how to integrate Mesa with Scikit-learn to create an emulator (surrogate model). This allows users to approximate the behavior of a complex Agent-Based Model (ABM) across a high-dimensional parameter space using only a small number of actual simulation runs.

Motive

Computational expense is a common bottleneck in ABM research, especially during calibration or sensitivity analysis. This PR offloads these concerns to Scikit-learn and Scipy to provide users with a robust workflow for efficient experimentation.

Implementation

• The example is self-contained in examples/surrogate_modeling/ to demonstrate integration without modifying the core library.
• Avoided batch_run and DataCollector in favor of manual Python loops to align with Mesa 4.0 roadmap.

Usage Examples

Users can run the entire pipeline from sampling to prediction with a single command:

python -m examples.surrogate_modeling.analysis

Running simulations for training data...
Surrogate model trained.

Prediction for {'n': 65, 'width': 22, 'height': 22}:
Approximated Gini: 0.6262

Additional Notes

• Added a new optional dependency group surrogate in pyproject.toml including scikit-learn.

[EwoutH]

Cool applications. Clearly shows something new.

@quaquel do you have an opinion on surrogate modelling for ABMs? Has its place in high SNR-models with stable and continuous outcome landscapes, but tricky and used with caution?

Maybe best used as an evaluation tool. With the quality of the surrogate model fit as the main outcome.

[EwoutH]

This might be nice as a Jupyter notebook, with maybe a few visualisations (but don't overdo it)

[Nithurshen]

I have added analysis.ipynb

[tpike3]

scipy and pandas are already dependencies of mesa

[Nithurshen]

Done

[tpike3]

I don't think we need the pyproject.toml the readme already list the dependencies.

[Nithurshen]

Done

[tpike3]

This is really cool @Nithurshen thanks! Could you add a brief description to the repo readme in other examples