@grnsft/if 0.3.2 → 0.3.4

package/github-processes.md

@@ -66,6 +66,16 @@ Here are the rules applied to each branch:
 - On `main` we can be slightly more flexible. It is acceptable to skip QA for PRs that only change typos, documentation or comments. Any changes to source code or tests should be QA approved before merge.
 - In emergency scenarios where an urgent hotfix is required it might be required to skip QA review on `main` branches - this should only happen with QA authorization so QA can retroactively test as soon as possible.
 
+### How to create a release
+
+Creating a release of `if`, `if-plugins` or `if-unofficial-plugins` is achieved by following these steps:
+
+1) core team member creates a tagged release on `main`
+2) new tagged release triggers automatic commit to be pushed to `main` that updates package and lock files that include new version numbers
+3) `main` branch is manually merged into `release` by core team member
+4) merging into release triggers automatic new release to be created on npm
+
+We use [semantic versioning](https://semver.org/) to number our releases. 
 ## DCO
 
 We require contributors to conform to the DCO agreement on our repositories. This means either signing commits or explicitly adding a DCO commit message. This ensures all contributors agree to the conditions imposed by our licenses and adhere to our expected practices. The DCO must be satisfied in order to PRs to be merged.

package/{examples/manifests/pipeline-demo-2.yml → manifests/bugs/aggregation-error-wrong-metric.yml}

@@ -1,15 +1,10 @@
-name: pipeline-demo
-description:
+name: aggregation-error-wrong-metric
+description: a negative test case that fails due to the aggregation feature being passed an incorrect metric
 tags:
 aggregation:
   metrics:
-    - "carbon"
+    - "dummy-param"
   type: "both"
-params:
-  - name: carbon-plus-energy
-    description: "sum of energies"
-    unit: "kWh"
-    aggregation: sum
 initialize:
   plugins:
     "teads-curve":
@@ -17,14 +12,9 @@ initialize:
       method: TeadsCurve
       global-config:
         interpolation: spline
-    "sum":
+    "sci-e":
       path: "@grnsft/if-plugins"
-      method: Sum
-      global-config:
-        input-parameters:
-          - cpu/energy
-          - network/energy
-        output-parameter: carbon-plus-energy
+      method: SciE
     "sci-m":
       path: "@grnsft/if-plugins"
       method: SciM
@@ -53,7 +43,7 @@ tree:
     child-1:
       pipeline:
         - teads-curve
-        - sum
+        - sci-e
         - sci-m
         - sci-o
         - time-sync
@@ -78,33 +68,25 @@ tree:
           cloud/region: uk-west
           duration: 1
           cpu/utilization: 10
-          network/energy: 10
-          energy: 5
         - timestamp: "2023-12-12T00:00:01.000Z"
           duration: 5
           cpu/utilization: 20
           cloud/instance-type: A1
           cloud/region: uk-west
-          network/energy: 10
-          energy: 5
         - timestamp: "2023-12-12T00:00:06.000Z"
           duration: 7
           cpu/utilization: 15
           cloud/instance-type: A1
           cloud/region: uk-west
-          network/energy: 10
-          energy: 5
         - timestamp: "2023-12-12T00:00:13.000Z"
           duration: 30
           cloud/instance-type: A1
           cloud/region: uk-west
           cpu/utilization: 15
-          network/energy: 10
-          energy: 5
     child-2:
       pipeline:
         - teads-curve
-        - sum
+        - sci-e
         - sci-m
         - sci-o
         - time-sync
@@ -113,7 +95,7 @@ tree:
         group-by:
           group:
             - cloud/region
-            - instance-type
+            - cloud/instance-type
       defaults:
         cpu/thermal-design-power: 100
         grid/carbon-intensity: 800
@@ -129,26 +111,18 @@ tree:
           cpu/utilization: 30
           cloud/instance-type: A1
           cloud/region: uk-west
-          network/energy: 10
-          energy: 5
         - timestamp: "2023-12-12T00:00:01.000Z"
           duration: 5
           cpu/utilization: 28
           cloud/instance-type: A1
           cloud/region: uk-west
-          network/energy: 10
-          energy: 5
         - timestamp: "2023-12-12T00:00:06.000Z"
           duration: 7
           cpu/utilization: 40
           cloud/instance-type: A1
           cloud/region: uk-west
-          network/energy: 10
-          energy: 5
         - timestamp: "2023-12-12T00:00:13.000Z"
           duration: 30
           cpu/utilization: 33
           cloud/instance-type: A1
           cloud/region: uk-west
-          network/energy: 10
-          energy: 5

package/manifests/bugs/azure-importer-ignoring-defaults.yml

@@ -0,0 +1,61 @@
+name: pipeline-demo
+description: https://github.com/Green-Software-Foundation/if-unofficial-plugins/issues/81
+tags:
+# aggregation:
+# metrics:
+# - "carbon"
+# - "energy"
+#type: "both"
+initialize:
+  outputs:
+    - yaml
+    # - csv
+  plugins:
+    "azure-importer":
+      method: AzureImporter
+      path: "@grnsft/if-unofficial-plugins"
+    "try-defaults-1":
+      path: "@grnsft/if-plugins"
+      method: Coefficient
+      global-config:
+        input-parameter: grid/carbon-intensity
+        coefficient: 0.1
+        output-parameter: grid/carbon-intensity
+    "try-defaults-2":
+      path: "@grnsft/if-plugins"
+      method: Coefficient
+      global-config:
+        input-parameter: network/energy
+        coefficient: 1000
+        output-parameter: network/energy
+    "sci-o":
+      method: SciO
+      path: "@grnsft/if-plugins"
+    "group-by":
+      path: "builtin"
+      method: GroupBy
+tree:
+  children:
+    web-front: # name this according to the sub-system, e.g. portal, APIs/backend, DB
+      pipeline:
+        - azure-importer
+        #- try-defaults-1
+        #- try-defaults-2
+        - sci-o
+      config:
+        group-by:
+          group:
+            - instance-type
+        azure-importer:
+          azure-observation-window: 60 min
+          azure-observation-aggregation: "average"
+          azure-subscription-id: 30b6e171-af2c-4fe6-b00d-d4c70f6291fe
+          azure-resource-group: gcf-app_group
+          azure-vm-name: gcf-app
+      defaults:
+        grid/carbon-intensity: 800 # adjust for SG grid
+        network/energy: 0.001 # review for naming accuracy
+      inputs:
+        - timestamp: "2024-04-04T08:00:00.001Z"
+          duration: 3600
+          energy: 100

package/manifests/bugs/azure-importer-incorrect-calculation.yml

@@ -0,0 +1,56 @@
+name: pipeline-demo
+description: https://github.com/Green-Software-Foundation/if-unofficial-plugins/issues/81
+tags: null
+initialize:
+  plugins:
+    azure-importer:
+      path: '@grnsft/if-unofficial-plugins'
+      method: AzureImporter
+    try-defaults-1:
+      path: '@grnsft/if-plugins'
+      method: Coefficient
+      global-config:
+        input-parameter: grid/carbon-intensity
+        coefficient: 0.1
+        output-parameter: grid/carbon-intensity
+    try-defaults-2:
+      path: '@grnsft/if-plugins'
+      method: Coefficient
+      global-config:
+        input-parameter: network/energy
+        coefficient: 1000
+        output-parameter: network/energy
+    sci-o:
+      path: '@grnsft/if-plugins'
+      method: SciO
+    group-by:
+      path: builtin
+      method: GroupBy
+  outputs:
+    - yaml
+if-version: v0.3.2
+tree:
+  children:
+    web-front:
+      pipeline:
+        - azure-importer
+        - try-defaults-1
+        - try-defaults-2
+      config:
+        group-by:
+          group:
+            - instance-type
+        azure-importer:
+          azure-observation-window: 60 min
+          azure-observation-aggregation: average
+          azure-subscription-id: 30b6e171-af2c-4fe6-b00d-d4c70f6291fe
+          azure-resource-group: gcf-app_group
+          azure-vm-name: gcf-app
+      defaults:
+        grid/carbon-intensity: 800
+        network/energy: 0.001
+      inputs:
+        - timestamp: '2024-04-04T08:00:00.001Z'
+          duration: 3600
+          energy: 100
+   

package/manifests/bugs/initialize-error-no-config.yml

@@ -0,0 +1,27 @@
+name: initialize-error-no-config
+description: a negative test case that fails due to plugin initialization missing some required config 
+tags:
+initialize:
+  plugins:
+    teads-curve: 
+      path: '@grnsft/if-unofficial-plugins'
+      method: TeadsCurve
+      global-config:
+  outputs: ['yaml']
+tree:
+  children:
+    child-0:
+      defaults:
+        cpu/thermal-design-power: 100
+      pipeline:
+        - teads-curve
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 1
+          cpu/utilization: 20
+        - timestamp: 2023-07-06T00:01
+          duration: 1
+          cpu/utilization: 80
+        - timestamp: 2023-07-06T00:02
+          duration: 1
+          cpu/utilization: 20

package/manifests/bugs/initialize-error-no-path.yml

@@ -0,0 +1,28 @@
+name: initialize-error-no-path
+description: a negative test case that fails because the path is mising in a plugin initialization
+tags:
+initialize:
+  plugins:
+    teads-curve: 
+      path:
+      method: TeadsCurve
+      global-config:
+        interpolation: spline
+  outputs: ['yaml']
+tree:
+  children:
+    child-0:
+      defaults:
+        cpu/thermal-design-power: 100
+      pipeline:
+        - teads-curve
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 1
+          cpu/utilization: 20
+        - timestamp: 2023-07-06T00:01
+          duration: 1
+          cpu/utilization: 80
+        - timestamp: 2023-07-06T00:02
+          duration: 1
+          cpu/utilization: 20

package/manifests/bugs/initialize-error-no-plugins.yml

@@ -0,0 +1,23 @@
+name: initialize-error-no-path
+description: a negative test case that fails becuase no plugins are included in the initialize block
+tags:
+initialize:
+  plugins:
+  outputs: ['yaml']
+tree:
+  children:
+    child-0:
+      defaults:
+        cpu/thermal-design-power: 100
+      pipeline:
+        - teads-curve
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 1
+          cpu/utilization: 20
+        - timestamp: 2023-07-06T00:01
+          duration: 1
+          cpu/utilization: 80
+        - timestamp: 2023-07-06T00:02
+          duration: 1
+          cpu/utilization: 20

package/manifests/bugs/input-error-missing-duration.yml

@@ -0,0 +1,21 @@
+name: input-error-missing-duration
+description: a negative test case that fails due to the required `duration` field being omitted from input data
+tags:
+initialize:
+  plugins:
+    teads-curve: 
+      path: '@grnsft/if-unofficial-plugins'
+      method: TeadsCurve
+      global-config:
+        interpolation: spline
+  outputs: ['yaml']
+tree:
+  children:
+    child-0:
+      defaults:
+        cpu/thermal-design-power: 100
+      pipeline:
+        - teads-curve
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          cpu/utilization: 20

package/manifests/bugs/pipeline-error-naming-mismatch.yml

@@ -0,0 +1,28 @@
+name: pipeline-error-naming-mismatch
+description: a negative test case that fails due to the plugin name in the pipeline not matching the name given in initialize 
+tags:
+initialize:
+  plugins:
+    teads-curve: 
+      path: '@grnsft/if-unofficial-plugins'
+      method: TeadsCurve
+      global-config:
+        interpolation: spline
+  outputs: ['yaml']
+tree:
+  children:
+    child-0:
+      defaults:
+        cpu/thermal-design-power: 100
+      pipeline:
+        - wrong-name
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 1
+          cpu/utilization: 20
+        - timestamp: 2023-07-06T00:01
+          duration: 1
+          cpu/utilization: 80
+        - timestamp: 2023-07-06T00:02
+          duration: 1
+          cpu/utilization: 20

package/manifests/bugs/pipeline-error-uninitialized-plugin.yml

@@ -0,0 +1,29 @@
+name: pipeline-uninitialized-plugin-error
+description: a negative test case that fails due to an uninitialized plugin being invoked in a pipeline
+tags:
+initialize:
+  plugins:
+    teads-curve: 
+      path: '@grnsft/if-unofficial-plugins'
+      method: TeadsCurve
+      global-config:
+        interpolation: spline
+  outputs: ['yaml']
+tree:
+  children:
+    child-0:
+      defaults:
+        cpu/thermal-design-power: 100
+      pipeline:
+        - teads-curve
+        - multiply
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 1
+          cpu/utilization: 20
+        - timestamp: 2023-07-06T00:01
+          duration: 1
+          cpu/utilization: 80
+        - timestamp: 2023-07-06T00:02
+          duration: 1
+          cpu/utilization: 20

package/{examples/manifests/boavizta-pipeline.yml → manifests/bugs/pipeline-ordering-error.yml}

@@ -1,14 +1,13 @@
-name: boavizta-demo
-description:
+name: pipeline-ordering-error
+description: a negative test case that fails because sci-o is invoked too early in the pipeline (before its inputs are generated)
 tags:
 initialize:
   plugins:
-    boavizta-cpu:
-      method: BoaviztaCpuOutput
+    "teads-curve":
       path: "@grnsft/if-unofficial-plugins"
+      method: TeadsCurve
       global-config:
-        allocation: LINEAR
-        verbose: true
+        interpolation: spline
     "sum":
       path: "@grnsft/if-plugins"
       method: Sum
@@ -41,10 +40,10 @@ tree:
   children:
     child-1:
       pipeline:
-        - boavizta-cpu
+        - teads-curve
+        - sci-o
         - sum
         - sci-m
-        - sci-o
         - time-sync
         - sci
       config:
@@ -56,8 +55,6 @@ tree:
         device/expected-lifespan: 94608000 # 3 years in seconds
         resources-reserved: 1
         resources-total: 8
-        cpu/number-cores: 24
-        cpu/name: Intel® Core™ i7-1185G7
       inputs:
         - timestamp: "2023-12-12T00:00:00.000Z"
           cloud/instance-type: A1

package/{examples/manifests → manifests/examples}/basic.yml

@@ -1,5 +1,5 @@
-name: basic-demo
-description:
+name: basic
+description: a minimal manifest executing a single plugin on a single component for a single timestep
 tags:
 initialize:
   plugins:
@@ -8,6 +8,7 @@ initialize:
       method: TeadsCurve
       global-config:
         interpolation: spline
+  outputs: ['yaml']
 tree:
   children:
     child-0:

package/{examples/manifests → manifests/examples}/generics.yml

@@ -1,5 +1,5 @@
-name: generic-arithmetic-demo
-description:
+name: generics
+description: a pipeline that does arbitrary calculations using our generic arithmetic builtins
 tags:
 initialize:
   plugins:

package/{examples/manifests/asim-demo.yml → manifests/examples/mock-cpu-util-to-carbon.yml}

@@ -1,11 +1,7 @@
-name: My Manifest File
-description: My First Manifest File 💚
-# aggregation:
-#   metrics:
-#     - 'carbon'
-#   type: 'both'
+name: mock-cpu-util-to-carbon
+description: a complete pipeline that starts with mocked CPU utilization data and outputs operational carbon in gCO2eq
 initialize:
-  outputs: ['yaml', 'csv']
+  outputs: ['yaml']
   plugins: 
     group-by: 
       path: 'builtin'

package/{examples/manifests → manifests/examples}/nesting.yml

@@ -1,5 +1,5 @@
-name: nesting-demo
-description: null
+name: nesting
+description: a manifest that includes nested child components
 tags:
   kind: web
   complexity: moderate
@@ -11,6 +11,7 @@ aggregation:
   type: "both"
 params:
 initialize:
+  outputs: ['yaml']
   plugins:
     teads-curve:
       path: "@grnsft/if-unofficial-plugins"

package/{examples/manifests → manifests/examples}/pipeline-teads-sci.yml

@@ -1,5 +1,5 @@
 name: pipeline-teads-sci
-description:
+description: a full pipeline seeded with some hardcoded input data and yielding an SCI score
 tags:
 initialize:
   plugins:

package/{examples/manifests/pipeline-demo.yml → manifests/examples/pipeline-with-aggregate.yml}

@@ -1,5 +1,5 @@
-name: realistic-pipeline-demo
-description:
+name: pipeline-with-aggregate
+description: a full pipeline with the aggregate feature enabled
 tags:
 aggregation:
   metrics:

package/{examples/manifests → manifests/examples}/pipeline-with-mocks.yml

@@ -1,5 +1,5 @@
-name: pipeline-with-mock-obs-demo
-description:
+name: pipeline-with-mocks
+description: a full pipeline seeded with data from mock-observations feature
 tags:
 aggregation:
   metrics:
@@ -56,6 +56,7 @@ initialize:
     "group-by":
       path: builtin
       method: GroupBy
+  outputs: ['yaml']
 tree:
   children:
     child-1:

package/manifests/features/aggregate-horizontal.yml

@@ -0,0 +1,44 @@
+name: Aggregation
+description: Apply `horizontal` aggregation
+aggregation:
+  metrics:
+    - 'cpu/utilization'
+  type: 'horizontal'
+initialize:
+  plugins:
+    cloud-metadata:
+      method: CloudMetadata
+      path: "@grnsft/if-plugins"              
+tree:
+  children:
+    application:
+      pipeline:
+        - cloud-metadata
+      children:
+        uk-west:
+          children:
+            server-1:
+              inputs:
+                - timestamp: '2024-02-26 00:00:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 89
+                - timestamp: '2024-02-26 00:05:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 59
+            server-2:
+              inputs:
+                - timestamp: '2024-02-26 00:00:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 24
+                - timestamp: '2024-02-26 00:05:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 27
+                

package/manifests/features/aggregate-vertical.yml

@@ -0,0 +1,44 @@
+name: Aggregation
+description: Apply `vertical` aggregation
+aggregation:
+  metrics:
+    - 'cpu/utilization'
+  type: 'vertical'
+initialize:
+  plugins:
+    cloud-metadata:
+      method: CloudMetadata
+      path: "@grnsft/if-plugins"              
+tree:
+  children:
+    application:
+      pipeline:
+        - cloud-metadata
+      children:
+        uk-west:
+          children:
+            server-1:
+              inputs:
+                - timestamp: '2024-02-26 00:00:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 89
+                - timestamp: '2024-02-26 00:05:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 59
+            server-2:
+              inputs:
+                - timestamp: '2024-02-26 00:00:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 24
+                - timestamp: '2024-02-26 00:05:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 27
+                

package/manifests/features/aggregate.yml

@@ -0,0 +1,44 @@
+name: Aggregation
+description: Apply both `horizontal` and `vertical` aggregations
+aggregation:
+  metrics:
+    - 'cpu/utilization'
+  type: 'both'
+initialize:
+  plugins:
+    cloud-metadata:
+      method: CloudMetadata
+      path: "@grnsft/if-plugins"              
+tree:
+  children:
+    application:
+      pipeline:
+        - cloud-metadata
+      children:
+        uk-west:
+          children:
+            server-1:
+              inputs:
+                - timestamp: '2024-02-26 00:00:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 89
+                - timestamp: '2024-02-26 00:05:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 59
+            server-2:
+              inputs:
+                - timestamp: '2024-02-26 00:00:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 24
+                - timestamp: '2024-02-26 00:05:00'
+                  duration: 300
+                  cloud/instance-type: m5n.large
+                  cloud/vendor: aws
+                  cpu/utilization: 27
+