diff options
Diffstat (limited to 'site/docs')
| -rw-r--r-- | site/docs/documentation/Input/M3SA.md | 92 | ||||
| -rw-r--r-- | site/docs/documentation/Input/M3SASchema.md | 115 | ||||
| -rw-r--r-- | site/docs/documentation/Input/ScenarioSchema.md | 2 | ||||
| -rw-r--r-- | site/docs/tutorials/M3SA-integration-tutorial.mdx | 188 | ||||
| -rw-r--r-- | site/docs/tutorials/cloud-capacity-planning.mdx | 1 |
5 files changed, 397 insertions, 1 deletions
diff --git a/site/docs/documentation/Input/M3SA.md b/site/docs/documentation/Input/M3SA.md new file mode 100644 index 00000000..6c97d207 --- /dev/null +++ b/site/docs/documentation/Input/M3SA.md @@ -0,0 +1,92 @@ +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](M3SASchema.md) +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](M3SASchema.md). + +### Simple + +The simplest M3SA setup that can be provided to OpenDC is shown below: + +```json +{ + "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: + +```json +{ + "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. diff --git a/site/docs/documentation/Input/M3SASchema.md b/site/docs/documentation/Input/M3SASchema.md new file mode 100644 index 00000000..5a3503ca --- /dev/null +++ b/site/docs/documentation/Input/M3SASchema.md @@ -0,0 +1,115 @@ +Below is the schema for the MultiMetaModel JSON file. This schema can be used to validate a MultiMetaModel setup file. +A setup file can be validated using a JSON schema validator, such as https://www.jsonschemavalidator.net/. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "multimodel": { + "type": "boolean", + "default": true, + "description": "Whether or not to build a Multi-Model. If set to false, a Meta-Model will not be computed either." + }, + "metamodel": { + "type": "boolean", + "default": true, + "description": "Whether to build a Meta-Model." + }, + "metric": { + "type": "string", + "description": "What metric to be analyzed from the computed files." + }, + "current_unit": { + "type": "string", + "default": "", + "description": "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": { + "type": "integer", + "default": 10, + "enum": [-9, -6, -3, 1, 3, 6, 9], + "description": "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." + }, + "seed": { + "type": "integer", + "default": 0, + "minimum": 0, + "description": "The seed of the simulation. This must correspond to the seed from the output folder (from seed=x)." + }, + "window_size": { + "type": "integer", + "default": 1, + "minimum": 1, + "description": "The size of the window, used for aggregating the chunks." + }, + "window_function": { + "type": "string", + "default": "mean", + "enum": ["mean", "median"], + "description": "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": { + "type": "string", + "default": "mean", + "enum": ["mean", "median"], + "description": "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": { + "type": "number", + "minimum": 0.0001, + "description": "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 20 samples per minute, or 1 sample every 3 seconds." + }, + "plot_type": { + "type": "string", + "default": "time_series", + "enum": ["time_series", "cumulative", "cumulative_time_series"], + "description": "The type of the plot, generated by the Multi-Model and Meta-Model." + }, + "plot_title": { + "type": "string", + "default": "", + "description": "The title of the plot." + }, + "x_label": { + "type": "string", + "default": "Time", + "description": "The label for the x-axis of the plot." + }, + "y_label": { + "type": "string", + "default": "Metric Unit", + "description": "The label for the y-axis of the plot." + }, + "y_min": { + "type": "number", + "description": "The minimum value for the vertical axis of the plot." + }, + "y_max": { + "type": "number", + "description": "The maximum value for the vertical axis of the plot." + }, + "x_min": { + "type": "number", + "description": "The minimum value for the horizontal axis of the plot." + }, + "x_max": { + "type": "number", + "description": "The maximum value for the horizontal axis of the plot." + }, + "x_ticks_count": { + "type": "integer", + "minimum": 1, + "description": "The number of ticks on x-axis." + }, + "y_ticks_count": { + "type": "integer", + "minimum": 1, + "description": "The number of ticks on y-axis." + } + }, + "required": [ + "metric" + ] +} +``` diff --git a/site/docs/documentation/Input/ScenarioSchema.md b/site/docs/documentation/Input/ScenarioSchema.md index bd800fd7..78ec55f7 100644 --- a/site/docs/documentation/Input/ScenarioSchema.md +++ b/site/docs/documentation/Input/ScenarioSchema.md @@ -75,7 +75,7 @@ A scenario file can be validated using a JSON schema validator, such as https:// "required": [ "topologies", "workloads", - "allocationPolicies", + "allocationPolicies" ] } ``` diff --git a/site/docs/tutorials/M3SA-integration-tutorial.mdx b/site/docs/tutorials/M3SA-integration-tutorial.mdx new file mode 100644 index 00000000..c09011c7 --- /dev/null +++ b/site/docs/tutorials/M3SA-integration-tutorial.mdx @@ -0,0 +1,188 @@ +--- +sidebar_position: 2 +title: M3SA Integration +hide_title: true +sidebar_label: M3SA Integration +description: M3SA Integration +--- + +# M3SA integration tutorial + +M3SA is a tool able to perform "Multi-Meta-Model Simulation Analysis". The tool is designed to analyze the output of +simulations, by leveraging predictions, generate Multi-Model graphs, novel models, and more. M3SA can integrate with any +simulation infrastructure, as long as integration steps are followed. + +We build our tool towards performance, scalability, and **universality**. In this document, we present the steps to +integrate our tool into your simulation infrastructure. + +If you are using OpenDC, none of adaptation steps are necessary, yet they can be useful to understand the structure +of the tool. Step 3 is still necessary. + +## Step 1: Adapt the simulator output folder structure + +The first step is to adapt the I/O of your simulation to the format of our tool. The output folder structure should have +the +following format: + +``` +[1] ── {simulation-folder-name} 📁 🔧 +[2] ├── inputs 📁 🔒 +[3] │ └── {m3sa-config-file}.json 📄 🔧 +[4] │ └── {other input files / folders} 🔧 +[5] ├── outputs 📁 🔒 +[6] │ ├── raw-output 📁 🔒 +[7] │ │ ├── 0 📁 🔒 +[8] │ │ │ └── seed={your_seed}🔒 +[9] │ │ │ └── {simulation_data_file}.parquet 📄 🔧 +[10] │ │ │ └── {any other files / folders} ⚪ +[11] │ │ ├── 1 📁 ⚪ 🔒 +[12] │ │ │ └── seed={your_seed} 📁 ⚪ 🔒 +[13] │ │ │ └── {simulation_data_file}.parquet 📄 ⚪ 🔧 +[14] │ │ │ └── {any other files / folders} ⚪ +[15] │ │ ├── metamodel 📁 ⚪ +[16] │ │ └── seed={your_seed} 📁 ⚪ +[17] │ │ └── {your_metric_name}.parquet 📄 ⚪ +[18] │ │ └── {any other files / folders} ⚪ +[19] │ └── {any other files / folders} 📁 ⚪ +[20]| └──{any other files / folders} 📁 ⚪ +``` + +📄 = file <br /> +📁 = folder <br /> +🔒 = fixed, the name of the folder/file must be the same.<br /> +🔧 = flexible, the name of the folder/file can differ. However, the item must be present.<br /> +⚪ = optional and flexible. The item can be absent. <br /> + +- [1] = the name of the analyzed folder. +- [2] = the _inputs_ folder, containing various inputs / configuration files. +- [3] = the configuration file for M3SA, flexible naming, but needs to be a JSON file +- [4],[10],[14],[18],[19],[20] = any other input files or folders. +- [5] = the _outputs_ folder, containing the raw-output. can contain any other files or folders, besides the raw-output +folder. +After running a simulation, also a "simulation-analysis" folder will be generated in this folder. +- [6] = raw-output folder, containing the raw output of the simulation. +- [7],[11] = the IDs of the models. Must always start from zero. Possible values are 0, 1, 2 ... n, and "metamodel". The +id +of "metamodel" is reserved for the Meta-Model. Any simulation data in the respective folder will be treated as +Meta-Model data. +- [8],[12] = the seed of the simulation. the seed must be the same for both [8], [12], and other equivalent, further +files. +- [9],[13] = the file in which the simulation data is stored. The name of the file can differ, but it must be a parquet +file. +- [15] = the Meta-Model folder, optional. If the folder is present, its data will be treated as Meta-Model data. +- [16] = the Meta-Model seed folder. The seed must be the same as the seed of the simulation. +- [17] = the Meta-Model output. The name of the file is of the type ```{your_metric_name}.parquet```. For example, if +you analyze CO2 emissions, the file will be named ```co2_emissions.parquet```. + +--- + +## Step 2: Adapt the simulation file format + +The simulator data file must be a 🪵 _parquet_ 🪵 file. + +The file must contain (at least) the columns: + +- timestamp: the timestamp, in miliseconds, of the data point (e.g., 30000, 60000, 90000) - the time unit is flexible. +- {metric_name}: the value of the metric at the given timestamp. This is the metric analyzed (e.g., CO2_emissions, +energy_usage). + +e.g., if you are analyzing the CO2 emissions of a datacenter, for a timeperiod of 5 minutes, and the data is sampled +every 30 seconds, the file will look like this: + +| timestamp | co2_emissions | +|-----------|---------------| +| 30000 | 31.2 | +| 60000 | 31.4 | +| 90000 | 28.5 | +| 120000 | 31.8 | +| 150000 | 51.5 | +| 180000 | 51.2 | +| 210000 | 51.4 | +| 240000 | 21.5 | +| 270000 | 21.8 | +| 300000 | 21.2 | + +--- + +## Step 3: Running M3SA + +### 3.1 Setup the Simulator Specifics + +Update the simulation folder name ([9], [13], [17] from Step 1), in the +file ```simulator_specifics.py```, from ```opendc/src/python/simulator_specifics.py```. + +### 3.2 Setup the python program arguments + +### Arguments for Main.py Setup +Main.py takes two arguments: + +1. Argument 1 is the path to the output directory where M3SA output files will be stored. +2. Argument 2 is the path to the input file that contains the configuration of M3SA. + +e.g., + +```json +"simulation-123/outputs/" "simulation-123/inputs/m3sa-configurator.json" +``` + +### 3.3 Working directory Main.py Setup + +Make sure to set the working directory to the directory where the main.py file is located. + +e.g., + +``` +/your/path/to-analyzer/src/main/python +``` + +If you are using OpenDC, you can set the working directory to the following path: + +``` +/your/path/opendc/opendc-analyze/src/main/python +``` + +--- + +## Optional: Step 4: Simulate and analyze, with one click + +The simulation and analysis can be executed as a single command; if no errors are encountered, from the user +perspective, +this operation is atomic. We integrated M3SA into OpenDC to facilitate this process. + +To further integrate M3SA into any simulation infrastructure, M3SA needs to called from +the simulation infrastructure, and provided the following running setup: + +1. script language: Python +2. argument 1: the path of the output directory, in which M3SA output files will be stored +3. argument 2: the path of the input file, containing the configuration of M3SA +4. other language-specific setup + +For example, the integration of the M3SA into OpenDC can be found +in ```Analyzr.kt``` from ```opendc-analyze/src/main/kotlin/Analyzr.kt```. +Below, we provide a snippet of the code: + +```kotlin +val ANALYSIS_SCRIPTS_DIRECTORY: String = "./opendc-analyze/src/main/python" +val ABSOLUTE_SCRIPT_PATH: String = + Path("$ANALYSIS_SCRIPTS_DIRECTORY/main.py").toAbsolutePath().normalize().toString() +val SCRIPT_LANGUAGE: String = "python3" + +fun analyzeResults(outputFolderPath: String, analyzerSetupPath: String) { + val process = ProcessBuilder( + SCRIPT_LANGUAGE, + ABSOLUTE_SCRIPT_PATH, + outputFolderPath, // argument 1 + analyzerSetupPath // argument 2 + ) + .directory(Path(ANALYSIS_SCRIPTS_DIRECTORY).toFile()) + .start() + + val exitCode = process.waitFor() + if (exitCode == 0) { + println("[Analyzr.kt says] Analysis completed successfully.") + } else { + val errors = process.errorStream.bufferedReader().readText() + println("[Analyzr.kt says] Exit code ${exitCode}; Error(s): $errors") + } +} +``` diff --git a/site/docs/tutorials/cloud-capacity-planning.mdx b/site/docs/tutorials/cloud-capacity-planning.mdx index a55c6a20..df9cb566 100644 --- a/site/docs/tutorials/cloud-capacity-planning.mdx +++ b/site/docs/tutorials/cloud-capacity-planning.mdx @@ -3,6 +3,7 @@ sidebar_position: 1 title: Cloud Capacity Planning hide_title: true sidebar_label: Cloud Capacity Planning +description: Cloud Capacity Planning --- # Cloud Capacity Planning Tutorial |