Scenario

class Melodie.Scenario(id_scenario: int | str | None = 0)

Bases: Element

The Scenario class defines a particular parameterization of the model.

A Scenario object holds all parameters and data required for a simulation run. It is created by the Simulator or Calibrator for each scenario defined in the input data tables.

Parameters:

id_scenario – The unique identifier for this scenario. If not provided, it will be assigned automatically by the Simulator.

copy() → Scenario

Create a deep copy of the current scenario object.

Returns:

A new Scenario object.

load_data()

A hook for loading static data tables.

This method is called automatically by the framework after scenario parameters have been loaded. It should be used to load any static data files (e.g., CSVs, matrices) that the model requires.

setup_data()

A hook for pre-computing data based on scenario parameters.

This method is called automatically after load_data(). It is useful for generating derived data, such as agent parameter DataFrames, before the model components are created.

initialize()

A wrapper for the internal _setup method.

This should be called if a scenario object is created and set up manually, outside the standard Simulator execution loop.

setup()

A hook for custom scenario initialization.

This method is called at the beginning of the scenario setup process, before parameters are loaded from the scenario table. It can be used to define scenario-level properties.

load_dataframe(df_info: str | DataFrameInfo)

Load a data frame from a table file in the input directory.

Parameters:

df_info – The name of the CSV or Excel file (e.g., 'my_data.csv').

load_matrix(mat_info: str | MatrixInfo) → ndarray

Load a matrix from a table file in the input directory.

Parameters:

mat_info – The name of the CSV or Excel file (e.g., 'my_matrix.csv').

to_dict()

Convert this scenario object to a dictionary.

Returns:

A dict mapping property names to their values.

to_json()

Convert the scenario to a JSON-serializable dictionary.

This method excludes properties that cannot be serialized, such as the ‘manager’ object, pandas DataFrames, and numpy arrays. These excluded objects will be reloaded independently in worker processes via the load_data() method.

Returns:

A dict containing serializable properties.

get_dataframe(df_info: DataFrameInfo) → pd.DataFrame

(Internal) Get a dataframe from the scenario.

Parameters:

df_info – A DataFrameInfo object.

Returns:

A pandas DataFrame.

get_matrix(matrix_info: MatrixInfo) → np.ndarray

(Internal) Get a matrix from the scenario.

Parameters:

matrix_info – A MatrixInfo object.

Returns:

A 2D numpy array.