From 96046070f0918de84f6cb7c2c055b04d494b78b5 Mon Sep 17 00:00:00 2001 From: manushak Date: Wed, 30 Oct 2024 07:42:58 +0400 Subject: [PATCH 1/2] update explain feature's examples --- docs/major-concepts/manifest-file.md | 15 +- docs/users/how-to-use-the-explain-feature.md | 224 ++++++++++--------- 2 files changed, 121 insertions(+), 118 deletions(-) diff --git a/docs/major-concepts/manifest-file.md b/docs/major-concepts/manifest-file.md index e90359f..8accac5 100644 --- a/docs/major-concepts/manifest-file.md +++ b/docs/major-concepts/manifest-file.md @@ -161,9 +161,9 @@ This section is autogenerated at runtime. It is a list of all the parameter meta ```yaml explain: - carbon: - plugins: - - sci + sci: + inputs: + carbon: unit: gCO2eq description: >- total carbon emissions attributed to an application's usage as the sum @@ -171,17 +171,14 @@ explain: aggregation-method: time: sum component: sum - requests: - plugins: - - sci + requests: unit: requests description: number of requests made to application in the given timestep aggregation-method: time: sum component: sum - sci: - plugins: - - sci + outputs: + sci: unit: gCO2eq/request description: >- software carbon intensity expressed as a rate of carbon emission per diff --git a/docs/users/how-to-use-the-explain-feature.md b/docs/users/how-to-use-the-explain-feature.md index f71640f..5098ade 100644 --- a/docs/users/how-to-use-the-explain-feature.md +++ b/docs/users/how-to-use-the-explain-feature.md @@ -239,116 +239,122 @@ When we execute this manifest, the following `explain` block is added to the out ```yaml explain: - vCPUs: - plugins: - - sci-embodied - unit: CPUs - description: number of CPUs allocated to an application - aggregation-method: - time: copy - component: copy - memory: - plugins: - - sci-embodied - unit: GB - description: RAM available for a resource, in GB - aggregation-method: - time: copy - component: copy - ssd: - plugins: - - sci-embodied - unit: SSDs - description: number of SSDs available for a resource - aggregation-method: - time: copy - component: copy - hdd: - plugins: - - sci-embodied - unit: HDDs - description: number of HDDs available for a resource - aggregation-method: - time: copy - component: copy - gpu: - plugins: - - sci-embodied - unit: GPUs - description: number of GPUs available for a resource - aggregation-method: - time: copy - component: copy - usage-ratio: - plugins: - - sci-embodied - unit: dimensionless - description: >- - a scaling factor that can be used to describe the ratio of actual resource - usage comapred to real device usage, e.g. 0.25 if you are using 2 out of 8 - vCPUs, 0.1 if you are responsible for 1 out of 10 GB of storage, etc - aggregation-method: - time: copy - component: copy - time: - plugins: - - sci-embodied - unit: seconds - description: >- - a time unit to scale the embodied carbon by, in seconds. If not - provided,time defaults to the value of the timestep duration. - aggregation-method: - time: copy - component: copy - embodied-carbon: - plugins: - - sci-embodied - - sum-carbon - unit: gCO2eq - description: >- - carbon emitted during the production, distribution and disposal of a - hardware component, scaled by the fraction of the component's lifespan - being allocated to the application under investigation - aggregation-method: - time: sum - component: sum - carbon-operational: - plugins: - - sum-carbon - unit: gCO2eq - description: carbon emitted due to an application's execution - aggregation-method: - time: sum - component: sum - carbon: - plugins: - - sum-carbon - - sci - unit: gCO2eq - description: >- - total carbon emissions attributed to an application's usage as the sum of - embodied and operational carbon - aggregation-method: - time: sum - component: sum - requests: - plugins: - - sci - unit: requests - description: number of requests made to application in the given timestep - aggregation-method: - time: sum - component: sum + sci-embodied: + inputs: + vCPUs: + description: number of CPUs allocated to an application + unit: CPUs + aggregation-method: + time: copy + component: copy + memory: + description: RAM available for a resource, in GB + unit: GB + aggregation-method: + time: copy + component: copy + ssd: + description: number of SSDs available for a resource + unit: SSDs + aggregation-method: + time: copy + component: copy + hdd: + description: number of HDDs available for a resource + unit: HDDs + aggregation-method: + time: copy + component: copy + gpu: + description: number of GPUs available for a resource + unit: GPUs + aggregation-method: + time: copy + component: copy + usage-ratio: + description: >- + a scaling factor that can be used to describe the ratio of actual + resource usage comapred to real device usage, e.g. 0.25 if you are + using 2 out of 8 vCPUs, 0.1 if you are responsible for 1 out of 10 GB + of storage, etc + unit: dimensionless + aggregation-method: + time: copy + component: copy + time: + description: >- + a time unit to scale the embodied carbon by, in seconds. If not + provided,time defaults to the value of the timestep duration. + unit: seconds + aggregation-method: + time: copy + component: copy + outputs: + embodied-carbon: + description: embodied carbon for a resource, scaled by usage + unit: gCO2eq + aggregation-method: + time: sum + component: sum + sum-carbon: + inputs: + carbon-operational: + unit: gCO2eq + description: carbon emitted due to an application's execution + aggregation-method: + time: sum + component: sum + embodied-carbon: + unit: gCO2eq + description: >- + carbon emitted during the production, distribution and disposal of a + hardware component, scaled by the fraction of the component's lifespan + being allocated to the application under investigation + aggregation-method: + time: sum + component: sum + outputs: + carbon: + unit: gCO2eq + description: >- + total carbon emissions attributed to an application's usage as the sum + of embodied and operational carbon + aggregation-method: + time: sum + component: sum sci: - plugins: - - sci - unit: gCO2eq/request - description: >- - software carbon intensity expressed as a rate of carbon emission per - request - aggregation-method: - time: sum - component: sum + inputs: + carbon: + unit: gCO2eq + description: >- + total carbon emissions attributed to an application's usage as the sum + of embodied and operational carbon + aggregation-method: + time: sum + component: sum + functional-unit: + description: >- + the name of the functional unit in which the final SCI value should be + expressed, e.g. requests, users + unit: none + aggregation-method: + time: sum + component: sum + requests: + unit: requests + description: number of requests made to application in the given timestep + aggregation-method: + time: sum + component: sum + outputs: + sci: + unit: gCO2eq/request + description: >- + software carbon intensity expressed as a rate of carbon emission per + request + aggregation-method: + time: sum + component: sum ``` ## When _not_ to use `explainer` From a194a6e965922d70e0fa4760b4bc723cd6f74901 Mon Sep 17 00:00:00 2001 From: manushak Date: Wed, 30 Oct 2024 07:43:42 +0400 Subject: [PATCH 2/2] fix reference to the explain feature's documentation --- docs/users/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/users/index.md b/docs/users/index.md index f3bc2f5..7948fe9 100644 --- a/docs/users/index.md +++ b/docs/users/index.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Users -This section contains information for Impact Framework users. You are a user if you want to apply the Impact Framework to your own use-case, such as using it to measure the environmental impact of your own apps running on some cloud platform. +This section contains information for Impact Framework users. You are a user if you want to apply the Impact Framework to your own use-case, such as using it to measure the environmental impact of your own apps running on some cloud platform. The user documentation includes: @@ -14,7 +14,7 @@ The user documentation includes: - [How to write manifest files](./how-to-write-manifests.md) - [How to export CSV file with `if-csv`](./how-to-export-csv-file-with-if-csv.md) - [How to compare files with `if-diff`](./how-to-compare-files-with-if-diff.md) -- [How to check parameters and units using `explain`](./using-the-explain-feature.md) +- [How to check parameters and units using `explain`](./how-to-use-the-explain-feature.md) - [How to verify manifest files with `if-check`](./how-to-verify-files-with-if-check.md) -If you are looking for guidance for how to *change or update* the Impact Framework by adding new features, fixing bugs or building new plugins, you should go to our [`developers` documentation](../developers/) instead. +If you are looking for guidance for how to _change or update_ the Impact Framework by adding new features, fixing bugs or building new plugins, you should go to our [`developers` documentation](../developers/) instead.