M3SA

M3SA is setup using a json file. The Multi-Model is a top-layer applied on top of the simulator, capable to leverage into a singular tool the prediction of multiple models. The Meta-Model is a model generated from the Multi-Model, and predicts using the predictions of individual models.

The Multi-Model's properties can be set using a JSON file. The JSON file must be linked to the scenario file and is required to follow the structure below.

Schema

The schema for the scenario file is provided in schema In the following section, we describe the different components of the schema.

General Structure

Variable	Type	Required?	Default	Possible Answers	Description
multimodel	boolean	no	true	true, false	Whether or not to build a Multi-Model. If set to false, a Meta-Model will not be computed either.
metamodel	boolean	no	true	true, false	Whether to build a Meta-Model.
metric	string	yes	N/A	N/A	What metric to be analyzed from the computed files.
current_unit	string	no	""	any string (e.g., "CO2", "Wh")	The international system unit of the metric to be analyzed, without prefixes. e.g., "W" for Watt is ok, "kW" is not.
unit_scaling_magnitude	integer	no	10	-9, -6, -3, 1, 3, 6, 9	The scaling factor to be applied to the metric (10^-9, 10^-6, 10^3, 10^3, 10^6, 10^9). For no scaling, input 1.
window_size	integer	no	1	any positive, non-zero, integer	The size of the window, used for aggregating the chunks.
window_function	string	no	"mean"	"mean", "median"	The function used by the window for aggregating the chunks (e.g., for "mean", the window will compute the mean of the samples).
meta_function	string	no	"mean"	"mean", "median"	The function used by the Meta-Model to be generated. For "mean", the Meta-Model takes the mean of the individual models, at the granularity established by the window-size.
samples_per_minute	double	no	N/A	any positive, non-zero, double	The number of samples per minute, in the prediction data (simulator export rate). e.g., "0.2" means 1 sample every 5 minutes, "20" means a 20 samples per minute, or 1 sample every 3 seconds.
seed	integer	no	0	any integer >= 0	The seed of the simulation. This must correspond to the seed from the output folder (from seed=x).
plot_type	string	no	"time_series"	"time_series", "cumulative", "cumulative_time_series"	The type of the plot, generated by the Multi-Model and Meta-Model.
plot_title	string	no	""	any string	The title of the plot.
x_ticks_count	integer	no	None	any integer, larger than 0	The number of ticks on x-axis.
y_ticks_count	integer	no	None	any integer, larger than 0	The number of ticks on y-axis.
x_label	string	no	"Time"	any string	The label for the x-axis of the plot.
y_label	string	no	"Metric Unit"	any string	The label for the y-axis of the plot.
y_min	double	no	None	any positive, non-zero, double	The minimum value for the vertical axis of the plot.
y_max	double	no	None	any positive, non-zero, double	The maximum value for the vertical axis of the plot.
x_min	double	no	None	any positive, non-zero, double	The minimum value for the horizontal axis of the plot.
x_max	double	no	None	any positive, non-zero, double	The maximum value for the horizontal axis of the plot.

Examples

In the following section, we discuss several examples of M3SA setup files. Any setup file can be verified using the JSON schema defined in schema.

Simple

The simplest M3SA setup that can be provided to OpenDC is shown below:

{
    "metric": "power_draw"
}

This configuration creates a Multi-Model and Meta-Model on the power_draw. All the other parameters are handled by the default values, towards reducing the complexity of the setup.

Complex

A more complex M3SA setup, where the user has more control on teh generated output, is show below:

{
    "multimodel": true,
    "metamodel": false,
    "metric": "carbon_emission",
    "window_size": 10,
    "window_function": "median",
    "metamodel_function": "mean",
    "samples_per_minute": 0.2,
    "unit_scaling_magnitude": 1000,
    "current_unit": "gCO2",
    "seed": 0,
    "plot_type": "cumulative_time_series",
    "plot_title": "Carbon Emission Prediction",
    "x_label": "Time [days]",
    "y_label": "Carbon Emission [gCO2/kWh]",
    "x_min": 0,
    "x_max": 200,
    "y_min": 500,
    "y_max": 1000,
    "x_ticks_count": 3,
    "y_ticks_count": 3
}

This configuration creates a Multi-Model and a Meta-Model which predicts the carbon_emission. The window size is 10, and the aggregation function (for the window) is median. The Meta-Model function is mean. The data has been exported at a rate of 0.2 samples per minute (i.e., a sample every 5 minutes). The plot type is cummulative_time_series, which starts from a y-axis value of 500 and goes up to 1000. Therefore, the Multi-Model and the Meta-Model will show only the values greater than y_min (500) and smaller than y_max (1000). Also, the x-axis will start from 0 and go up to 200, with 3 ticks on the x-axis and 3 ticks on the y-axis.