@grnsft/if 0.3.3-beta.0 → 0.4.0-beta.0

package/manifests/plugins/{sci-m → sci-embodied}/success.yml

@@ -1,18 +1,17 @@
-name: sci-m
+name: sci-embodied
 description: successful path
 tags:
 initialize:
   outputs: ['yaml']
   plugins:
-    "sci-m": # a model that calculates m from te, tir, el, rr and rtor
-      method: SciM
-      verbose: false
-      path: "@grnsft/if-plugins"
+    "sci-embodied": # a model that calculates m from te, tir, el, rr and rtor
+      method: SciEmbodied
+      path: "builtin"
 tree:
   children:
     child:
       pipeline:
-        - sci-m # duration & config -> embodied
+        - sci-embodied # duration & config -> embodied
       defaults:
         device/emissions-embodied: 1533.120 # gCO2eq
         time-reserved: 3600 # 1hr in seconds

package/manifests/plugins/shell/failure-invalid-command.yml

@@ -6,7 +6,7 @@ initialize:
   plugins:
     shell:
       method: Shell
-      path: "@grnsft/if-plugins"
+      path: "builtin"
       global-config:
         command: 1000
 tree:

package/manifests/plugins/shell/success.yml

@@ -2,11 +2,10 @@ name: shell
 description: successful path
 tags:
 initialize:
-  outputs: ['yaml']
   plugins:
     shell:
       method: Shell
-      path: "@grnsft/if-plugins"
+      path: 'builtin'
       global-config:
         command: python3 /usr/local/bin/sampler
 tree:

package/manifests/plugins/sum/failure-missing-input-param.yml

@@ -6,7 +6,7 @@ initialize:
   plugins:
     sum:
       method: Sum
-      path: "@grnsft/if-plugins"
+      path: "builtin"
       global-config:
         input-parameters: ["cpu/energy", "network/energy"]
         output-parameter: "energy"

package/manifests/plugins/sum/failure-missing-output-param.yml

@@ -0,0 +1,28 @@
+name: sum
+description: missing `output-parameter` in global-config
+tags:
+initialize:
+  outputs: ['yaml']
+  plugins:
+    sum:
+      method: Sum
+      path: "builtin"
+      global-config:
+        input-parameters: ["cpu/energy", "network/energy"]
+       # output-parameter: "energy"
+tree:
+  children:
+    child:
+      pipeline:
+        - sum
+      config:
+        sum:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 0.001
+          network/energy: 0.001
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 0.001
+          network/energy: e

package/manifests/plugins/sum/success.yml

@@ -6,7 +6,7 @@ initialize:
   plugins:
     sum:
       method: Sum
-      path: "@grnsft/if-plugins"
+      path: "builtin"
       global-config:
         input-parameters: ["cpu/energy", "network/energy"]
         output-parameter: "energy"

package/manifests/plugins/tdp-finder/failure-unsupported-physical-processor.yml

@@ -0,0 +1,19 @@
+name: tdp-finder
+description: successful path
+tags:
+initialize:
+  outputs: ['yaml']
+  plugins:
+    tdp-finder: # a model that returns an embodied value given the sci embodied attribution equation.
+      method: TdpFinder
+      path: "@grnsft/if-plugins"
+tree:
+  children:
+    child:
+      pipeline:
+        - tdp-finder
+      config:
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 300
+          physical-processor: AMD 302

package/manifests/plugins/time-sync/failure-missing-global-config.yml

@@ -0,0 +1,34 @@
+name: time-sync
+description: missing global config
+tags:
+initialize:
+  output:
+    - yaml
+  plugins:
+    'time-sync':
+      method: TimeSync
+      path: "builtin"
+      global-config: 
+        # start-time: '2023-12-12T00:00:00.000Z'
+        # end-time: '2023-12-12T00:01:00.000Z'
+        # interval: 5
+        # allow-padding: true
+tree:
+  children:
+    child:
+      pipeline:
+        - time-sync
+      config:
+      inputs:
+        - timestamp: '2023-12-12T00:00:00.000Z'
+          duration: 3
+          energy-cpu: 0.001
+        - timestamp: '2023-12-12T00:00:01.000Z'
+          duration: 5
+          energy-cpu: 0.001
+        - timestamp: '2023-12-12T00:00:06.000Z'
+          duration: 7
+          energy-cpu: 0.001
+        - timestamp: '2023-12-12T00:00:13.000Z'
+          duration: 30
+          energy-cpu: 0.001

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@grnsft/if",
   "description": "Impact Framework",
-  "version": "0.3.3-beta.0",
+  "version": "0.4.0-beta.0",
   "author": {
     "name": "Green Software Foundation",
     "email": "info@gsf.com"
   },
   "bin": {
-    "ie": "./build/index.js"
+    "ie": "./build/index.js",
+    "if-diff": "./build/diff.js"
   },
   "bugs": {
     "url": "https://github.com/Green-Software-Foundation/if/issues/new?assignees=&labels=feedback&projects=&template=feedback.md&title=Feedback+-+"
@@ -15,11 +16,14 @@
   "dependencies": {
     "@commitlint/cli": "^18.6.0",
     "@commitlint/config-conventional": "^18.6.0",
+    "axios": "^1.7.2",
+    "csv-parse": "^5.5.6",
     "csv-stringify": "^6.4.6",
     "js-yaml": "^4.1.0",
     "luxon": "^3.4.4",
     "ts-command-line-args": "^2.5.1",
     "typescript": "^5.1.6",
+    "typescript-cubic-spline": "^1.0.1",
     "winston": "^3.11.0",
     "zod": "^3.22.4"
   },
@@ -31,10 +35,12 @@
     "@types/js-yaml": "^4.0.5",
     "@types/luxon": "^3.4.2",
     "@types/node": "^20.8.9",
+    "axios-mock-adapter": "^1.22.0",
     "fixpack": "^4.0.0",
     "gts": "^5.0.0",
     "husky": "^8.0.0",
     "jest": "^29.6.1",
+    "lint-staged": "^15.2.2",
     "release-it": "^16.3.0",
     "rimraf": "^5.0.5",
     "ts-jest": "^29.1.1"
@@ -67,7 +73,9 @@
     "fix": "gts fix",
     "fix:package": "fixpack",
     "ie": "npx ts-node src/index.ts",
+    "if-diff": "npx ts-node src/diff.ts",
     "lint": "gts lint",
+    "pre-commit": "lint-staged",
     "prepare": "husky install",
     "prepublish": "npm run build",
     "release": "release-it",

package/src/__tests__/integration/manifest/sci-e.yaml

@@ -0,0 +1,23 @@
+name: integration-template
+description: null
+tags: null
+initialize:
+  plugins:
+    sci-e:
+      method: SciE
+      path: '@grnsft/if-plugins'
+  outputs:
+    - log
+tree:
+  children:
+    child:
+      pipeline:
+        - sci-e
+      config:
+        sci-e: {}
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 10
+          memory/energy: 100
+          network/energy: 100

package/src/builtins/README.md

@@ -231,9 +231,9 @@ initialize:
     sci-e:
       method: SciE
       path: '@grnsft/if-plugins'
-    sci-m:
-      path: '@grnsft/if-plugins'
-      method: SciM
+    sci-embodied:
+      path: 'builtin'
+      method: SciEmbodied
     sci-o:
       method: SciO
       path: '@grnsft/if-plugins'
@@ -250,13 +250,13 @@ tree:
       pipeline:
         - teads-curve
         - sci-e
-        - sci-m
+        - sci-embodied
         - sci-o
         - time-sync
       config:
         teads-curve:
           cpu/thermal-design-power: 65
-        sci-m:
+        sci-embodied:
           device/emissions-embodied: 251000 # gCO2eq
           time-reserved: 3600 # 1 hour in s
           device/expected-lifespan: 126144000 # 4 years in seconds

package/src/builtins/coefficient/README.md

@@ -0,0 +1,92 @@
+# Coefficient
+
+`Coefficient` is a generic plugin for multiplying a value in an `input` array by a given coefficient.
+
+You provide the name of the value you want to multiply, a coefficient value, and a name to use to append the product to the output array.
+
+For example, you could multiply `cpu/energy` by 10 and name the result `energy-product`. `energy-product` would then be added to every observation in your input array as the product of `cpu/energy` and 10.
+
+## Parameters
+
+### Plugin global config
+
+Three parameters are required in global config: `input-parameter`, `coefficient` and `output-parameter`.
+
+- `input-parameter`: a string matching an existing key in the `inputs` array
+- `coefficient`: the value to multiply `input-parameter` by.
+- `output-parameter`: a string defining the name to use to add the product of the input parameters to the output array.
+
+### Inputs
+
+All of `input-parameters` must be available in the input array.
+
+## Returns
+
+- `output-parameter`: the product of all `input-parameters` with the parameter name defined by `output-parameter` in global config.
+
+## Calculation
+
+```pseudocode
+output = input * coefficient
+```
+
+## Implementation
+
+To run the plugin from a Typescript app, you must first create an instance of `Coefficient`. Then, you can call `execute()`.
+
+```typescript
+const config = {
+  'input-parameter': 'carbon',
+  coefficient: 10,
+  'output-parameter': 'carbon-product',
+};
+
+const coeff = Coefficient(config);
+const result = coeff.execute([
+  {
+    duration: 3600,
+    timestamp: '2021-01-01T00:00:00Z',
+    carbon: 3,
+  },
+]);
+```
+
+## Example manifest
+
+IF users will typically call the plugin as part of a pipeline defined in a manifest file. In this case, instantiating the plugin is handled by `ie` and does not have to be done explicitly by the user. The following is an example manifest that calls `coefficient`:
+
+```yaml
+name: coefficient-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    coefficient:
+      method: Coefficient
+      path: 'builtin'
+      global-config:
+        input-parameter: 'carbon'
+        coefficient: 3
+        output-parameter: 'carbon-product'
+tree:
+  children:
+    child:
+      pipeline:
+        - coefficient
+      config:
+        coefficient:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          carbon: 30
+```
+
+You can run this example by saving it as `./examples/manifests/coefficient.yml` and executing the following command from the project root:
+
+```sh
+ie --manifest ./examples/manifests/coefficient.yml --output ./examples/outputs/coefficient.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`

package/src/builtins/csv-lookup/README.md

@@ -0,0 +1,142 @@
+# CSV Lookup Plugin
+
+`csv-lookup` is a generic plugin that enables you to select arbitrary data from a given csv file and add it to your manifest file's `input` data.
+
+You provide path to the target csv file pus some query parameters. The filepath can point to a location on the local filesystem or it can be a URL for an online resource. The query parameters include the column names for the target data you want to return (can be one column name, multiple column names or all column names, indicated using `"*"`), plus the column names and values you want to use as selectors.
+
+For example, for the following CSV:
+
+|      |                |                 |            |            |              |           |                  |            |            |                        |            |                            |                                   |                                |                                  |                       |
+| ---- | -------------- | --------------- | ---------- | ---------- | ------------ | --------- | ---------------- | ---------- | ---------- | ---------------------- | ---------- | -------------------------- | --------------------------------- | ------------------------------ | -------------------------------- | --------------------- |
+| year | cloud-provider | cloud-region    | cfe-region | em-zone-id | wt-region-id | location  | geolocation      | cfe-hourly | cfe-annual | power-usage-efficiency | net-carbon | grid-carbon-intensity-24x7 | grid-carbon-intensity-consumption | grid-carbon-intensity-marginal | grid-carbon-intensity-production | grid-carbon-intensity |
+| 2022 | Google Cloud   | asia-east1      | Taiwan     | TW         | TW           | Taiwan    | 25.0375,121.5625 | 0.18       |            |                        | 0          | 453                        |                                   |                                |                                  | 453                   |
+| 2022 | Google Cloud   | asia-east2      | Hong Kong  | HK         | HK           | Hong Kong | 22.3,114.2       | 0.28       |            |                        | 0          | 453                        |                                   |                                |                                  | 360                   |
+| 2022 | Google Cloud   | asia-northeast1 | Tokyo      | JP-TK      | JP-TK        | Tokyo     | 35.6897,139.692  | 0.28       |            |                        | 0          | 463                        |                                   |                                |                                  | 463                   |
+
+
+You could select all the data for the cloud provider `Google Cloud` in the region `asia-east2` using the following configuration:
+
+```yaml
+filepath: https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/region-metadata.csv
+query:
+  cloud-provider: "cloud/provider"
+  cloud-region: "cloud/region"
+output: "*"
+```
+
+Notice that the query parameters are key/value pairs where the key is the column name in the target CSV and the value is a **reference to a value** in your `input` data (*not* an actual value - a reference). This is to enable you to chain CSV lookups together based on information from other plugins in your pipeline.
+
+
+## Parameters
+
+### Plugin config
+
+- `filepath` - path to a csv file, either on the local filesystem or on the internet
+- `query` - an array of key/value pairs where the key is a column name in the target csv and the value is a parameter from inputs
+- `output` - the columns to grab data from and add to output data - should support wildcard or multiple values. 
+
+The plugin also supports data renaming. This means you can grab data from a named column but push it into your manifest file data under another name, for example, maybe we want to grab data from the `processor-name` column int he target csv and add it to the manifest file data as `processor-id` because this is the name expected by some other plugin in your piepline. You can do this by passing comma separated values in arrays. 
+
+```yaml
+output:
+  ["processor-name": "processor-id"]
+```
+
+You can nest arrays to do this renaming for multiple columns.
+
+```yaml
+output:
+  [["processor-name", "processor-model-id"],["tdp","thermal-design-power"]]
+```
+
+All the following values are valid for the `output` field:
+- `"*"`
+- `"tdp"`
+- `["processor-name", "processor-model-id"]`
+- `[["processor-name", "processor-model-id"],["tdp","thermal-design-power"]]`
+
+### Inputs
+
+There are no strict requirements on input for this plugin because they depend upon the contents of the target CSV and your input data at the time the CSV lookup is invoked. Please make sure you are requesting data from columns that exist in the target csv file and that your query values are available in your `input` data.
+
+## Returns
+
+The input data with the requested csv content appended to it.
+
+## Plugin logic
+
+1. Validates global config which contains `filepath`, `query` and `output`.
+2. Tries to retrieve given file (with url or local path).
+3. Parses given CSV.
+4. Filters requested information from CSV.
+5. Adds new key-value pairs to the input data
+6. Returns enriched input data
+
+## Implementation
+
+To run the plugin, you must first create an instance of `CSVLookup`. Then, you can call `execute()`.
+
+```typescript
+const globalConfig = {
+  filepath: 'https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/cloud-metdata-aws-instances.csv',
+  query: {
+    'cloud-provider': 'cloud/provider'
+	  region: 'cloud/region'
+	  'instance-type': 'cloud/instance-type'
+  },
+  output: ['cpu-tdp', 'tdp'],
+};
+const divide = CSVLookup(globalConfig);
+
+const input = [
+  {
+    timestamp: '2023-08-06T00:00'
+    duration: 3600
+    'cpu/energy': 0.001
+    'cloud/provider': gcp
+    'cloud/region': asia-east
+  },
+];
+```
+
+## Example manifest
+
+IF users will typically call the plugin as part of a pipeline defined in a manifest file. In this case, instantiating the plugin is handled by `if` and does not have to be done explicitly by the user. The following is an example manifest that calls `csv-lookup`:
+
+```yaml
+name: csv-lookup-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    cloud-metadata:
+      method: CSVLookup
+      path: 'builtin'
+      global-config:
+        filepath: https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/region-metadata.csv
+        query:
+          cloud-provider: "cloud/provider"
+          cloud-region: "cloud/region"
+        output: "*"
+tree:
+  children:
+    child:
+      pipeline:
+        - cloud-metadata
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cloud/provider: Google Cloud
+          cloud/region: europe-north1
+```
+
+You can run this example by saving it as `./examples/manifests/csv-lookup.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest manifests/plugins/csv-lookup.yml --output manifests/outputs/csv-lookup
+```
+
+The results will be saved to a new `yaml` file in `manifests/outputs`.

package/src/builtins/divide/README.md

@@ -0,0 +1,95 @@
+# Divide
+
+`divide` is a generic plugin for doing arithmetic division of two values in an `input` array.
+
+You provide the names of the values you want to divide, and a name to use to add the divide to the output array.
+
+For example, `boavizta-cpu` need `cpu/number-cores` to work, however `cloud-metadata` returns `vcpus-allocated`, to get number of cores you divide `vcpus-allocated` by 2.
+
+## Parameters
+
+### Plugin config
+
+- `numerator` - a parameter by a specific configured number
+- `denominator` - a parameter by a specific configured number or the number by which `numerator` is divided
+- `output` - the number to a configured output parameter
+
+### Inputs
+
+- `numerator` - as input parameter, must be available in the input array
+- `denominator` - must be available in the input array if is an input parameter
+- `output` - as input parameter, must be available in the input array
+
+## Returns
+
+- `output`: the division of `numerator` with the parameter name into `denominator` with the parameter name defined by `output` in global config.
+
+The plugin throws an exception if the division result is not a number.
+
+## Calculation
+
+```pseudocode
+output = input0 / input1
+```
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Divide`. Then, you can call `execute()`.
+
+```typescript
+const globalConfig = {
+  numerator: 'vcpus-allocated',
+  denominator: 2,
+  output: 'cpu/number-cores',
+};
+const divide = Divide(globalConfig);
+
+const input = [
+  {
+    timestamp: '2021-01-01T00:00:00Z',
+    duration: 3600,
+    'vcpus-allocated': 24,
+  },
+];
+```
+
+## Example manifest
+
+IF users will typically call the plugin as part of a pipeline defined in a manifest file. In this case, instantiating the plugin is handled by `if` and does not have to be done explicitly by the user. The following is an example manifest that calls `divide`:
+
+```yaml
+name: divide-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    divide:
+      method: Divide
+      path: 'builtin'
+      global-config:
+        numerator: vcpus-allocated
+        denominator: 2
+        output: cpu/number-cores
+tree:
+  children:
+    child:
+      pipeline:
+        - divide
+      config:
+        divide:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          vcpus-allocated: 24
+```
+
+You can run this example by saving it as `./examples/manifests/divide.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./examples/manifests/divide.yml --output ./examples/outputs/divide.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`.

package/src/builtins/exponent/README.md

@@ -0,0 +1,97 @@
+# Exponent
+
+`exponent` is a generic plugin for calculating exponent of an input param (as base) and another (as the exponent) in an `input` array.
+
+You provide the names of the values you want to use for the exponent calculation, and a name to use to add the exponent result to the output array.
+
+For example, you use `cpu/energy` as base and `network/energy` as and name the result `energy`. `energy` would then be added to every observation in your input array as `cpu/energy` raised by the exponent `network/energy`.
+
+## Parameters
+
+### Plugin config
+
+Three parameters are required in global config: `input-parameter`, `exponent` and `output-parameter`.
+
+`input-parameter`: a string defining the base. Must match an existing key in the `inputs` array
+`exponent`: a number defining the exponent.
+`output-parameter`: a string defining the name to use to add the result of the exponent to the output array.
+
+### Inputs
+
+`input-parameter` and `exponent` must be available in the input array.
+
+## Returns
+
+- `output-parameter`: `input-parameter` raised by `exponent` with the parameter name defined by `output-parameter` in global config.
+
+## Calculation
+
+```pseudocode
+output = input ^ exponent
+```
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Exponent`. Then, you can call `execute()`.
+
+```typescript
+import {Exponent} from 'builtins';
+
+const config = {
+  inputParameter: ['cpu/energy'],
+  exponent: 2
+  outputParameter: 'energy',
+};
+
+const exponent = Exponent(config);
+const result = await exponent.execute([
+  {
+    duration: 3600,
+    timestamp: '2021-01-01T00:00:00Z',
+    'cpu/energy': 0.1,
+    'energy': 0.01,
+  },
+]);
+```
+
+## Example manifest
+
+IF users will typically call the plugin as part of a pipeline defined in a manifest file. In this case, instantiating the plugin is handled by and does not have to be done explicitly by the user. The following is an example manifest that calls `exponent`:
+
+```yaml
+name: exponent demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    exponent:
+      method: Exponent
+      path: 'builtin'
+      global-config:
+        input-parameter: 'cpu/energy'
+        exponent: 2
+        output-parameter: 'energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - exponent
+      config:
+        exponent:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 0.001
+          network/energy: 0.001
+```
+
+You can run this example by saving it as `manifests/examples/test/exponent.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest manifests/examples/test/exponent.yml --output manifests/outputs/exponent.yml
+```
+
+The results will be saved to a new `yaml` file in `manifests/outputs`.