Model Module

class corrai.base.model.Model(is_dynamic)

Bases: ABC

Abstract base class for models in Corrai.

A Model defines the interface for simulation-based, analytical, or FMU-driven systems. It provides utilities to map high-level Parameter objects to model-specific properties and to run simulations given parameter-value pairs.

Subclasses must implement the simulate() method.

Parameters:

is_dynamic (bool, default=True) – Indicates if the model returns time dependant results as DataFrame with DatetimeIndex, or is static and returns a Series of values

get_property_from_param(parameter_value_pairs)

Convert (Parameter, value) pairs into a dictionary of model property assignments, handling relative and absolute values.

simulate(property_dict, simulation_options, simulation_kwargs)

Abstract method. Run the simulation and return a pandas DataFrame.

simulate_parameter(parameter_value_pairs, simulation_options, simulation_kwargs)

Helper that combines get_property_from_param() and simulate().

get_property_values(property_list)

Retrieve current values of given model properties. Must be implemented in subclasses if relative parameters are used.

save(file_path)

Persists the model state or parameters to disk. Optional.

__init__(is_dynamic)

get_property_from_param(parameter_value_pairs)

Map (Parameter, value) pairs to a dictionary of model properties.

Handles both absolute and relative parameter definitions. For relative parameters, the initial property value is used as a baseline.

Parameters:

parameter_value_pairs (list of (Parameter, int | float | str)) – List of tuples linking a Parameter object with the value assigned for this simulation.

Returns:

property_dict – Mapping from property names (str) to updated values.

Return type:

dict

abstractmethod simulate(property_dict=None, simulation_options=None, **simulation_kwargs)

Run a simulation for given properties and options.

Must be implemented in subclasses.

Parameters:

• property_dict (dict, optional) – Mapping from model property names to values to override.

• simulation_options (dict, optional) – Options controlling the simulation (e.g., start/end times, timestep, solver parameters).

• simulation_kwargs (dict, optional) – Extra keyword arguments for the simulation routine.

Returns:

Simulation results as a DataFrame with a DateTimeIndex and one or more output columns.

Return type:

pd.DataFrame

simulate_parameter(parameter_value_pairs, simulation_options=None, simulation_kwargs=None)

Simulate the model given a set of parameter-value pairs.

This combines get_property_from_param() and simulate().

Parameters:

• parameter_value_pairs (list of (Parameter, int | float | str)) – The parameters and their assigned values for this run.

• simulation_options (dict, optional) – Options passed to the simulation routine.

• simulation_kwargs (dict, optional) – Additional arguments for the simulation routine.

Returns:

Simulation results as a DataFrame with a DateTimeIndex and one or more output columns.

Return type:

pd.DataFrame

get_property_values(property_list)

Retrieve current values of given properties from the model.

Must be implemented in subclasses if relative parameters are used.

Parameters:

property_list (tuple of str) – Names of model properties.

Returns:

Current values of the requested properties.

Return type:

list of int | float | str

Raises:

NotImplementedError – If not overridden in a subclass.

save(file_path)

Save model state or parameters to disk.

Parameters:

file_path (Path) – Destination path.

Raises:

NotImplementedError – If not overridden in a subclass.