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

package/src/builtins/interpolation/README.md

@@ -0,0 +1,168 @@
+# Interpolation Plugin
+
+## Overview
+
+Interpolation is a way to infer new data points from a previously known set of points.
+This plugin provides the `y` value at a given `x` by interpolating between known points. You provide a set of known `x`s and `y`s and a target `x`, the plugin returns the `y` for your `x`.
+
+## Usage
+
+To employ the `Interpolation` plugin, adhere to these steps:
+
+1. **Initialize Plugin**: Import the `Interpolation` function and initialize it with global configuration parameters `method`, `x`, `y`, `input-parameter` and `output-parameter`.
+
+2. **Execute Plugin**: Invoke the `execute` method of the initialized plugin instance with an array of input parameters. Each input parameter should include a `timestamp`, `duration` and `[input-parameter]` information.
+
+3. **Result**: The plugin will return an array of plugin parameters enriched with the calculated average carbon intensity for each input.
+
+## Global Config
+
+- `method`: specifies the interpolation method for the data. Acceptable values are 'linear', 'spline', or 'polynomial'. The default method is linear. (optional)
+- `x`: array of x points. Numbers should be in ascending order (required).
+- `y`: array of y points. Numbers should be in ascending order (required).
+- `input-parameter`: a string defining the name to use its value to calculate the interpolation. It should match an existing key in the inputs array (required).
+- `output-parameter`: a string defining the name to use to add the result of interpolation with additional calculation (required).
+
+`x` and `y` arrays must be equal lengths.
+
+## Input Parameters
+
+The plugin expects the following input parameters:
+
+- `timestamp`: a timestamp for the input (required)
+- `duration`: the amount of time, in seconds, that the input covers. (required)
+- `[input-parameter]` - a field whose name matches the string provided to input-parameter in global config (i.e. if the input-parameter in global config is cpu/utilisation then cpu-utilisation must exist in the input data)
+
+## Output
+
+The plugin outputs a value `z` that is the result of looking up the `y` value at `x = 'input-parameter'` using the user-defined interpolation method in `kWh` units. `z` is assigned to a field with a name defined by `output-parameter` in the output data.
+
+## Error Handling
+
+The plugin conducts input validation using the `zod` library and may throw errors if the provided parameters are invalid.
+
+## Plugin Algorithm
+
+1. **Execution**:
+
+   - Validate Global config
+
+     - `method` - validates if the method is one of these methods: `linear`, `spline`, or `polynomial`. If the method isn’t provided, it sets to `linear`.
+     - `x` and `y` should be arrays of numbers, the length should be equal, and elements should be ordered in the ascendant order.
+     - `input-parameter` - validates if the parameter is string.
+     - `output-parameter` - validates if the parameter is string.
+
+   - Iterate through each input, and do corresponding validation and calculation.
+
+   - Validate input parameters
+
+     - `duration` - validate if the duration is a number
+     - `timestamp` - should be in string or date format
+     - `[input-parameter]` - validates whether the parameter name is included in the input, and if its value should be a number within the range of x points.
+
+   - Calculation
+
+     - If the `method` is provided, choose the right way to calculate. For the `linear` and `polynomial` methods, calculate according to their formulas. For spline interpolation, use the npm module `typescript-cubic-spline`.
+
+2. **Output**: Output the provided input along with the calculated `cpu/energy`
+
+### TypeScript Usage
+
+```ts
+const globalConfig = {
+  method: 'linear',
+  x: [0, 10, 50, 100],
+  y: [0.12, 0.32, 0.75, 1.02],
+  'input-parameter': 'cpu/utilization'
+  'output-parameter': 'cpu/energy'
+
+};
+
+const interpolationPlugin = Interpolation(globalConfig);
+
+const inputs = [
+  {
+    timestamp: '2024-04-16T12:00:00Z',
+    duration: 3600,
+    'cpu/utilization': 45
+  },
+];
+
+const results = interpolationPlugin.execute(inputs);
+
+console.log(results);
+```
+
+### Manifest Usage
+
+#### Input
+
+```yaml
+name: interpolation-demo
+description: simple demo of interpolation plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    interpolation:
+      method: Interpolation
+      path: 'builtin'
+      global-config:
+        method: linear
+        x: [0, 10, 50, 100]
+        y: [0.12, 0.32, 0.75, 1.02]
+        input-parameter: 'cpu/utilization'
+        output-parameter: 'cpu/energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - interpolation
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45
+```
+
+#### Output
+
+```yaml
+name: interpolation-demo
+description: simple demo of interpolation plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    interpolation:
+      method: Interpolation
+      path: 'builtin'
+      global-config:
+        method: linear
+        x: [0, 10, 50, 100]
+        y: [0.12, 0.32, 0.75, 1.02]
+        input-parameter: 'cpu/utilization'
+        output-parameter: 'cpu/energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - interpolation
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45
+      outputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45
+          cpu/energy: 0.00069625
+```
+
+You can execute this by passing it to `ie`. Run the impact using the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./manifests/examples/interpolation.yml --output ./manifests/outputs/interpolation.yml
+```

package/src/builtins/mock-observations/README.md

@@ -0,0 +1,97 @@
+# Mock Observations Plugin
+
+## Introduction
+
+A plugin for mocking observations (inputs) for testing and demo purposes
+
+## Scope
+
+The mode currently mocks 2 types of observation data:
+
+- Common key-value pairs, that are generated statically and are the same for each generated observation/input (see 'helpers/CommonGenerator.ts')
+- Randomly generated integer values for predefined keys (see 'helpers/RandIntGenerator.ts')
+
+### Plugin global config
+
+- `timestamp-from`, `timestamp-to` and `duration` define time buckets for which to generate observations.
+- `generators` define which fields to generate for each observation
+- `components` define the components for which to generate observations. The observations generated according to `timestamp-from`, `timestamp-to`, `duration` and `generators` will be duplicated for each component.
+
+### Authentication
+
+N/A
+
+### Inputs
+
+The plugin's `global-config` section in the manifest file determines its behaviour.
+'inputs' section is ignored.
+
+### Typescript Usage
+
+```typescript
+const mockObservations = MockObservations({
+  'timestamp-from': '2023-07-06T00:00',
+  'timestamp-to': '2023-07-06T00:10',
+  duration: 60,
+  components: {
+    'instance-type': 'A1',
+  },
+  generators: {
+    common: {
+      region: 'uk-west',
+    },
+  },
+});
+const result = await mockObservations.execute([]);
+```
+
+### manifest Example
+
+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 `mock-observation`:
+
+```yaml
+name: mock-observation-demo
+description: example invoking mock-observation plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    mock-observations:
+      kind: plugin
+      method: MockObservations
+      path: 'builtin'
+      global-config:
+        timestamp-from: 2023-07-06T00:00
+        timestamp-to: 2023-07-06T00:10
+        duration: 60
+        components:
+          - instance-type: A1
+          - instance-type: B1
+        generators:
+          common:
+            region: uk-west
+            common-key: common-val
+          randint:
+            cpu/utilization:
+              min: 1
+              max: 99
+            memory/utilization:
+              min: 1
+              max: 99
+tree:
+  children:
+    child:
+      pipeline:
+        - mock-observations
+      inputs:
+```
+
+You can run this example `manifest` by saving it as `manifests/plugins/mock-observation.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./examples/manifests/test/mock-observation.yml --output ./examples/outputs/mock-observation
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`.

package/src/builtins/multiply/README.md

@@ -0,0 +1,94 @@
+# Multiply
+
+`multiply` is a generic plugin for multiplying two or more values in an `input` array.
+
+You provide the names of the values you want to multiply, and a name to use to append the product to the output array.
+
+For example, you could multiply `cpu/energy` and `network/energy` 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 `network/energy`.
+
+## Parameters
+
+### Plugin config
+
+Two parameters are required in global config: `input-parameters` and `output-parameter`.
+
+`input-parameters`: an array of strings. Each string should match an existing key in the `inputs` array
+`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 = input0 * input1 * input2 ... inputN
+```
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Multiply`. Then, you can call `execute()`.
+
+```typescript
+import {Multiply} from 'builtins';
+
+const config = {
+  inputParameters: ['cpu/energy', 'network/energy'],
+  outputParameter: 'energy-product',
+};
+
+const mult = Multiply(config);
+const result = await mult.execute([
+  {
+    duration: 3600,
+    timestamp: '2021-01-01T00:00:00Z',
+    'cpu/energy': 0.001,
+    'memory/energy': 0.0005,
+  },
+]);
+```
+
+## 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 `multiply`:
+
+```yaml
+name: multiply-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    multiply:
+      method: Multiply
+      path: 'builtin'
+      global-config:
+        input-parameters: ['cpu/energy', 'network/energy']
+        output-parameter: 'energy-product'
+tree:
+  children:
+    child:
+      pipeline:
+        - multiply
+      config:
+        multiply:
+      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 `./examples/manifests/test/multiply.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./examples/manifests/test/multiply.yml --output ./examples/outputs/multiply.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`

package/src/builtins/regex/README.md

@@ -0,0 +1,91 @@
+# Regex
+
+`regex` is a generic plugin to match part of one string in an `input` and extract it into an output.
+
+You provide the name of the value you want to match, and a name to use to add the regex to the output array.
+
+For example, `boavizta-cpu` need `cpu/name` to work, however `cloud-metadata` returns `physical-processor` which usually contains a long string of processors that the instance could be separated by `,`, like so:
+
+```
+Intel® Xeon® Platinum 8272CL,Intel® Xeon® 8171M 2.1 GHz,Intel® Xeon® E5-2673 v4 2.3 GHz,Intel® Xeon® E5-2673 v3 2.4 GHz
+```
+
+## Parameters
+
+### Plugin config
+
+- `parameter` - a parameter by a specific configured string
+- `match` - a regex by which needs to match the `parameter`
+- `output` - output parameter name in the input
+
+### Inputs
+
+- `parameter` - as input parameter, must be available in the input array
+
+## Returns
+
+- `output`: the first match of `parameter` with the parameter name with `match` defined in global config.
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Regex`. Then, you can call `execute()`.
+
+```typescript
+
+const globalConfig = {
+  parameter: 'physical-processor',
+  match: '^[^,]+',
+  output: 'cpu/name',
+};
+const regex = Regex(globalConfig);
+
+const input = [
+  {
+    timestamp: '2021-01-01T00:00:00Z',
+    duration: 3600,
+    'physical-processor':
+      'Intel® Xeon® Platinum 8272CL,Intel® Xeon® 8171M 2.1 GHz,Intel® Xeon® E5-2673 v4 2.3 GHz,Intel® Xeon® E5-2673 v3 2.4 GHz',
+  },
+];
+```
+
+## 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 `regex`:
+
+```yaml
+name: regex-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    regex:
+      method: Regex
+      path: 'builtin'
+      global-config:
+        parameter: physical-processor
+        match: ^[^,]+
+        output: cpu/name
+tree:
+  children:
+    child:
+      pipeline:
+        - regex
+      config:
+        regex:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          physical-processor: Intel® Xeon® Platinum 8272CL,Intel® Xeon® 8171M 2.1 GHz,Intel® Xeon® E5-2673 v4 2.3 GHz,Intel® Xeon® E5-2673 v3 2.4 GHz
+```
+
+You can run this example by saving it as `manifests/plugins/regex.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+if --manifest manifests/examples/regex.yml --output manifests/outputs/regex.yml
+```
+
+The results will be saved to a new `yaml` file in `manifests/outputs`.

package/src/builtins/sci/README.md

@@ -0,0 +1,89 @@
+# SCI (software carbon intensity)
+
+[SCI](https://sci-guide.greensoftware.foundation/) represents the amount of carbon emitted per [functional unit](https://sci-guide.greensoftware.foundation/R/).
+
+## Parameters
+
+### Plugin global config
+
+- `functional-unit`: the name of the functional unit in which to express the carbon impact (required)
+
+
+### Inputs
+
+
+- `carbon`: total carbon in gCO2eq (required)
+- `functional-unit`: whatever `functional-unit` you define in global config also has to be present in each input, for example if you provide `functional-unit: requests` in global config, `requests` must be present in your input data.
+
+## Returns
+
+- `sci`: carbon expressed in terms of the given functional unit
+
+## Calculation
+
+SCI is calculated as:
+
+```pseudocode
+sci = carbon / functional unit
+```
+
+
+## IF Implementation
+
+To run the plugin, you must first create an instance of `Sci`. Then, you can call `execute()` to return `sci`.
+
+```typescript
+import {Sci} from 'builtins';
+
+const sci = Sci({'functional-unit': 'requests'});
+const results = await sci.execute(
+  [
+    {
+      'carbon': 5'
+      duration: 1,
+      requests: 100,
+    },
+  ]
+);
+```
+
+## 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 `sci`:
+
+```yaml
+name: sci-demo
+description: example invoking sci plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    sci:
+      method: Sci
+      path: 'builtin'
+      global-config:
+        functional-unit: 'requests'
+tree:
+  children:
+    child:
+      pipeline:
+        - sci
+      config:
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          carbon: 5
+          duration: 1
+          requests: 100
+```
+
+You can run this example `manifest` by saving it as `./manifests/plugins/sci.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest manifests/plugins/sci.yml --output manifests/outputs/sci.yml
+```
+
+The results will be saved to a new `yaml` file.

package/src/builtins/sci-embodied/README.md

@@ -0,0 +1,110 @@
+# SCI-Embodied
+
+Software systems cause emissions through the hardware that they operate on, both through the energy that the physical hardware consumes and the emissions associated with manufacturing the hardware. Embodied carbon refers to the carbon emitted during the manufacture and eventual disposal of a component. It is added to the operational carbon (carbon emitted when a component is used) to give an overall SCI score.
+
+Read more on [embodied carbon](https://github.com/Green-Software-Foundation/sci/blob/main/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md#embodied-emissions)
+
+## Parameters
+
+### Plugin config
+
+Not Needed
+
+### Inputs
+
+- `device/emissions-embodied`: the sum of Life Cycle Assessment (LCA) emissions for the component
+- `device/expected-lifespan`: the length of time, in seconds, between a component's manufacture and its disposal
+- `resources-reserved`: the number of resources reserved for use by the software
+- `resources-total`: the total number of resources available
+- `duration`: the amount of time covered by an observation, in this context it is used as the share of the total life span of the hardware reserved for use by an application, in seconds.
+
+> Note that if you have a plugin pipeline that adds `vcpus-allocated` and `vcpus-total` to each observation, such as the `cloud-metadata` plugin, those values will be used **in preference** to the given `resources-reserved` and `resources-total` fields.
+
+## Returns
+
+- `carbon-embodied`: the carbon emitted in manufacturing and disposing of a component, in gCO2eq
+
+## Calculation
+
+To calculate the embodied carbon, `m` for a software application, use the equation:
+
+```
+m = te * ts * rs
+```
+
+Where:
+
+- `device/emissions-embodied` = Total embodied emissions; the sum of Life Cycle Assessment (LCA) emissions for the component.
+
+- `timeShare` = Time-share; the share of the total life span of the hardware reserved for use by an application.
+
+  - `timeShare` is calculated as `duration/'device/expected-lifespan'`, where:
+    - `duration` = the length of time the hardware is reserved for use by the software.
+    - `device/expected-lifespan` = Expected lifespan: the length of time, in seconds, between a component's manufacture and its disposal.
+
+- `resourceShare` = Resource-share; the share of the total available resources of the hardware reserved for use by an application.
+  - `resourceShare` is calculated as `resources-reserved/resources-total`, where:
+    - `resources-reserved` = Resources reserved; the number of resources reserved for use by the software.
+    - `resources-total` = Total Resources; the total number of resources available.
+
+## Implementation
+
+IF implements the plugin based on the logic described above. To run the plugin, you must first create an instance of `SciEmbodied`. Then, you can call `execute()` to return `m`.
+
+## Usage
+
+The following snippet demonstrates how to call the `sci-embodied` plugin from Typescript.
+
+```typescript
+import {SciEmbodied} from 'builtins';
+
+const sciEmbodied = SciEmbodied();
+const results = await sciEmbodied.execute([
+  {
+    'device/emissions-embodied': 200, // in gCO2e for total resource units
+    duration: 60 * 60 * 24 * 30, // time reserved in seconds, can point to another field "duration"
+    'device/expected-lifespan': 60 * 60 * 24 * 365 * 4, // lifespan in seconds (4 years)
+    'resources-reserved': 1, // resource units reserved / used
+    'resources-total': 1, // total resource units available
+  },
+]);
+```
+
+## 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 `sci-embodied`:
+
+```yaml
+name: sci-embodied
+description: simple demo invoking sci-embodied
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    sci-embodied:
+      method: SciEmbodied
+      path: 'builtins'
+tree:
+  children:
+    child:
+      pipeline:
+        - sci-embodied # duration & config -> embodied
+      defaults:
+        device/emissions-embodied: 1533.120 # gCO2eq
+        device/expected-lifespan: 3 # 3 years in seconds
+        resources-reserved: 1
+        resources-total: 8
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+```
+
+You can run this example `manifest` by executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest manifests/plugins/sci-embodied.yml --output manifests/outputs/sci-embodied.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`.