Summary

This PR adds a RunSpec class to define how a single Scenario is executed. It has been discussed in #3483 .

Motive

After the Scenario refactor, experiment setup is now handled cleanly, but there is no clear way to define how a Scenario should actually be run. This makes execution logic implicit and inconsistent across use cases. RunSpec introduces a simple and explicit way to define how a model is built, executed, and how results are extracted for a single run.

Implementation

RunSpec acts as a small execution pipeline. By default, it builds a model from a Scenario, runs it using run_for, and returns the model’s data_registry. The class is designed to be subclassed, with clear override points for model construction, execution logic, result extraction, and output formatting.

Tests are added to cover the default behavior and each extension point, including custom execution, extraction, and output formatting.

Usage Examples

Basic usage:

spec = RunSpec(MyModel, steps=100)
sid, rid, result = spec(scenario)

Custom behavior:

class MyRunSpec(RunSpec):
    def execute(self, model):
        model.run_until(50)

    def extract(self, model):
        return model.compute_metrics()