Calibrator

class Melodie.Calibrator(config: Config, scenario_cls: Type[Scenario] | None, model_cls: Type[Model] | None, data_loader_cls: Type[DataLoader] = None, processors: int = 1, parallel_mode: Literal['process', 'thread'] = 'process')

Bases: BaseModellingManager

The Calibrator uses a genetic algorithm to tune scenario parameters.

It aims to find the parameter set that minimizes the “distance” between a model’s output and a predefined target (e.g., empirical data).

Parameters:

• config – The project Config object.

• scenario_cls – The Scenario subclass for the model.

• model_cls – The Model subclass for the model.

• data_loader_cls – The DataLoader subclass for the model.

• processors – The number of processor cores to use for parallel computation of the genetic algorithm.

• parallel_mode – The parallelization mode. "process" (default) uses subprocess-based parallelism, suitable for all Python versions. "thread" uses thread-based parallelism, which is recommended for Python 3.13+ (free-threaded/No-GIL builds) for better performance.

setup()

A hook for setting up the Calibrator.

This method should be overridden in a subclass to define which scenario properties to calibrate using add_scenario_calibrating_property().

collect_data()

(Optional) A hook to define which agent and environment properties to record.

This is not required for calibration itself but is useful for saving detailed simulation data during the calibration process. Use add_environment_property() to register properties.

generate_scenarios() → List[Scenario]

Generate scenarios from the CalibratorScenarios table.

Returns:

A list of Scenario objects.

get_params_scenarios() → List

Load the genetic algorithm parameters from the CalibratorParamsScenarios table.

Returns:

A list of dictionaries, where each dictionary contains the GA parameters for one calibration run.

run()

The main entry point for starting the calibration process.

run_once_new(scenario: Scenario, calibration_params: GACalibratorParams)

(Internal) Run a single calibration path.

target_function(model: Model) → float | int

(Internal) A wrapper for the user-defined distance function.

distance(model: Model) → float

The distance function to be minimized by the calibrator.

This method must be overridden in a subclass. It should take a Model object (representing the final state of a simulation run) and return a single float value representing the “distance” or error between the model’s output and the desired target.

Parameters:

model – The Model object after a simulation run.

Returns:

A float representing the distance.

add_scenario_calibrating_property(prop: str)

Register a scenario property to be calibrated.

The specified property will be tuned by the genetic algorithm within the bounds defined in the CalibratorParamsScenarios table.

Parameters:

prop – The name of the scenario property to calibrate.

add_environment_property(prop: str)

Register an environment property to be recorded during calibration.

This allows for saving the values of specific environment properties for each simulation run within the calibration process.

Parameters:

prop – The name of the environment property to record.