@grnsft/if 0.1.8 → 0.2.0

package/examples/{impls/test → manifests}/sci-o.yml

@@ -2,16 +2,16 @@ name: sci-o-demo
 description:
 tags:
 initialize:
-  models:
-    - name: sci-e
+  plugins:
+    sci-e:
       kind: plugin
-      model: SciEModel
-      path: "@grnsft/if-models"
-    - name: sci-o
+      method: SciE
+      path: "@grnsft/if-plugins"
+    sci-o:
       verbose: false
-      model: SciOModel
-      path: "@grnsft/if-models"
-graph:
+      method: SciO
+      path: "@grnsft/if-plugins"
+tree:
   children:
     child:
       pipeline:
@@ -22,5 +22,5 @@ graph:
       inputs:
         - timestamp: 2023-08-06T00:00
           duration: 3600
-          energy-cpu: 0.001
-          grid-carbon-intensity: 800
+          cpu/energy: 0.001
+          grid/carbon-intensity: 800

package/examples/{impls/test → manifests}/sci.yml

@@ -2,25 +2,26 @@ name: sci-demo
 description: example invoking sci model
 tags:
 initialize:
-  models:
-    - name: sci
+  plugins:
+    sci:
       kind: plugin
-      model: SciModel
-      path: "@grnsft/if-models"
-graph:
+      method: Sci
+      path: "@grnsft/if-plugins"
+      # global-config:
+      #   functional-unit-time: 1 minute
+tree:
   children:
     child:
       pipeline:
         - sci
       config:
         sci:
-          functional-unit-duration: 1
-          functional-unit-time: "1 minute"
+          functional-unit-time: 1 sec
           functional-unit: requests # factor to convert per time to per f.unit
       inputs:
         - timestamp: 2023-07-06T00:00
           duration: 3600
           energy: 5
-          operational-carbon: 5
-          embodied-carbon: 0.02
+          carbon-operational: 5
+          carbon-embodied: 0.02
           requests: 100

package/examples/manifests/shell.yml

@@ -0,0 +1,20 @@
+name: shell-demo
+description: example impl invoking shell model
+tags:
+initialize:
+  plugins:
+    shell:
+      method: Shell
+      path: "@grnsft/if-plugins"
+      global-config:
+        command: python3 /usr/local/bin/sampler
+tree:
+  children:
+    child:
+      pipeline:
+        - shell
+      inputs:
+        - timestamp: "2023-11-02T10:35:31.820Z"
+          duration: 3600
+          cpu/energy: 0.002
+          memory/energy: 0.000005

package/examples/manifests/sum.yml

@@ -0,0 +1,23 @@
+name: sci-e-demo
+description:
+tags:
+initialize:
+  plugins:
+    sum:
+      method: Sum
+      path: "@grnsft/if-plugins"
+      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

package/examples/{impls/test → manifests}/tdp-finder.yml

@@ -2,18 +2,17 @@ name: tdp-finder
 description: demo
 tags:
 initialize:
-  models:
-    - name: tdp-finder # a model that returns an embodied value given the sci embodied attribution equation.
-      model: TdpFinderModel 
-      path: "@grnsft/if-models"
-graph:
+  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: 
+      pipeline:
         - tdp-finder
       config:
       inputs:
         - timestamp: 2023-07-06T00:00
           duration: 300
           physical-processor: AMD 3020e
-

package/examples/manifests/teads-aws.yml

@@ -0,0 +1,22 @@
+name: teads-aws
+description: simple demo invoking TeadsAWS model
+tags:
+initialize:
+  plugins:
+    teads-aws:
+      method: TeadsAWS
+      path: "@grnsft/if-unofficial-plugins"
+      global-config:
+        interpolation: linear
+tree:
+  children:
+    child:
+      pipeline:
+        - teads-aws # duration & config -> embodied
+      defaults:
+        cloud/instance-type: m5n.large
+        cpu/expected-lifespan: 252288000
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 10

package/examples/manifests/teads-curve.yml

@@ -0,0 +1,20 @@
+name: teads-curve
+description: simple demo invoking teads-curve
+tags:
+initialize:
+  plugins:
+    teads-curve:
+      method: TeadsCurve
+      path: "@grnsft/if-unofficial-plugins"
+      global-config:
+        interpolation: spline
+tree:
+  children:
+    child:
+      pipeline:
+        - teads-curve
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 50
+          cpu/thermal-design-power: 100

package/examples/manifests/time-sync.yml

@@ -0,0 +1,32 @@
+name: time-sync-demo
+description:
+tags:
+initialize:
+  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: 1
+          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/examples/manifests/watt-time.yml

@@ -0,0 +1,42 @@
+name: watt-time-demo
+description: null
+tags: null
+initialize:
+  plugins:
+    mock-observations:
+      path: "@grnsft/if-plugins"
+      method: MockObservations
+      global-config:
+        timestamp-from: 2024-02-26T00:00
+        timestamp-to: 2024-02-26T00:10
+        duration: 60
+        components:
+          - cloud/instance-type: Standard_A1_v2
+          - cloud/instance-type: Standard_A2_v2
+        generators:
+          common:
+            cloud/vendor: azure
+            cloud/region: uk-west
+            geolocation: 37.7749,-122.4194
+          randint:
+            cpu/utilization:
+              min: 1
+              max: 99
+    watttime:
+      path: "@grnsft/if-unofficial-plugins"
+      method: WattTimeGridEmissions
+tree:
+  children:
+    application:
+      pipeline:
+        - mock-observations
+        - watttime
+      config:
+      inputs:
+        - timestamp: "2024-02-26 00:00:00"
+          duration: 60
+          cloud/instance-type: Standard_A1_v2
+          cloud/vendor: azure
+          cloud/region: uk-west
+          geolocation: 37.7749,-122.4194
+          cpu/utilization: 15

package/jest.config.js

@@ -10,5 +10,10 @@ module.exports = {
       },
     ],
   },
-  modulePathIgnorePatterns: ['./build', './src/__tests__/unit/lib/impls'],
+  modulePathIgnorePatterns: [
+    './build',
+    './src/__tests__/unit/lib/manifest',
+    './src/__tests__/integration/helpers',
+    './src/__tests__/integration/test-data',
+  ],
 };

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "@grnsft/if",
   "description": "Impact Framework",
-  "version": "v0.1.8",
+  "version": "v0.2.0",
   "author": {
     "name": "Green Software Foundation",
     "email": "info@gsf.com"
   },
   "bin": {
-    "impact-engine": "./build/index.js"
+    "if": "./build/index.js"
   },
   "bugs": {
     "url": "https://github.com/Green-Software-Foundation/if/issues/new?assignees=&labels=feedback&projects=&template=feedback.md&title=Feedback+-+"
   },
   "dependencies": {
-    "copyfiles": "^2.4.1",
+    "@commitlint/cli": "^18.6.0",
+    "@commitlint/config-conventional": "^18.6.0",
     "js-yaml": "^4.1.0",
-    "moment": "^2.29.4",
-    "moment-range": "^4.0.2",
+    "luxon": "^3.4.4",
     "ts-command-line-args": "^2.5.1",
     "typescript": "^5.1.6",
+    "winston": "^3.11.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {
@@ -27,9 +28,11 @@
     "@jest/globals": "^29.6.1",
     "@types/jest": "^29.5.7",
     "@types/js-yaml": "^4.0.5",
+    "@types/luxon": "^3.4.2",
     "@types/node": "^20.8.9",
     "fixpack": "^4.0.0",
     "gts": "^5.0.0",
+    "husky": "^8.0.0",
     "jest": "^29.6.1",
     "ts-jest": "^29.1.1"
   },
@@ -55,14 +58,16 @@
     "url": "https://github.com/Green-Software-Foundation/if"
   },
   "scripts": {
-    "build": "rm -rf build && tsc --project tsconfig.build.json && copyfiles -u 2 src/config/units.yaml build/config",
+    "build": "rm -rf build && tsc --project tsconfig.build.json",
     "coverage": "jest --verbose --coverage",
     "fix": "gts fix",
     "fix:package": "fixpack",
-    "impact-engine": "npx ts-node src/index.ts",
+    "if": "npx ts-node src/index.ts",
     "lint": "gts lint",
+    "prepare": "husky install",
     "prepublish": "npm run build",
-    "test": "jest --verbose"
+    "test": "jest --verbose --testPathPattern=src/__tests__/unit",
+    "test:integration": "jest --verbose --testPathPattern=src/__tests__/integration"
   },
   "stability": "stable",
   "types": "src/index.d.ts"

package/src/__tests__/integration/templates/integration.yaml

@@ -0,0 +1,16 @@
+name: integration-template
+description:
+tags:
+initialize:
+  plugins:
+     'sci-e':
+        model: ${model}
+        path: ${path}
+tree:
+  children:
+    child:
+      pipeline:
+        - ${name}
+      config:
+      inputs:
+        - ${input}

package/src/models/README.md

@@ -10,6 +10,7 @@ The following should be defined in the model initialization:
 - `start-time`: global start time as ISO 8061 string
 - `stop`: global end time as ISO 8061 string
 - `interval`: temporal resolution in seconds
+- `error-on-padding`: avoid zero/'zeroish' padding (if needed) and error out instead. `False` by defult.
 
 ### Inputs:
 
@@ -114,6 +115,7 @@ The end result of this gap-filling is that we have continuous 1 second resolutio
     {timestamp: 2023-12-12T00:00:09.000Z, duration: 1, cpu-util: 12, carbon: 2.5, energy: 5, grid-carbon-intensity: 471}
 ]
 ```
+Note that when `error-on-padding` is `true` no gap-filling is performed and the model will error out instead.
 
 #### Trimming and padding
 
@@ -149,7 +151,7 @@ For example, for `startTime = 2023-12-12T00:00:00.000Z` and `endTime = 2023-12-1
 
 ]
 ```
-
+Note that when `error-on-padding` is `true` no padding is performed and the model will error out instead.
 
 #### Resampling rules
 
@@ -199,8 +201,8 @@ const results = timeSyncModel.execute([
 
 IEF users will typically call the model as part of a pipeline defined in an `impl`
 file. In this case, instantiating and configuring the model is handled by
-`impact-engine` and does not have to be done explicitly by the user.
-The following is an example `impl` that calls `time-sync`:
+`if` and does not have to be done explicitly by the user.
+The following is an example `manifest` that calls `time-sync`:
 
 ```yaml
 name: time-sync-demo
@@ -210,16 +212,16 @@ initialize:
   models:
     - name: teads-curve
       model: TeadsCurveModel
-      path: "@grnsft/if-unofficial-models"
+      path: "@grnsft/if-unofficial-plugins"
     - name: sci-e
       model: SciEModel
-      path: "@grnsft/if-models"
+      path: "@grnsft/if-plugins"
     - name: sci-m
-      path: "@grnsft/if-models"
+      path: "@grnsft/if-plugins"
       model: SciMModel
     - name: sci-o
       model: SciOModel
-      path: "@grnsft/if-models"
+      path: "@grnsft/if-plugins"
     - name: time-synchronization
       model: TimeSyncModel
       path: builtin

package/tsconfig.test.json

@@ -9,7 +9,7 @@
     "experimentalDecorators": true,
     "incremental": true,
     "lib": [
-      "es2020"
+      "ES2021"
     ],
     "module": "CommonJS",
     "noEmitOnError": true,

package/Makefile

@@ -1,16 +0,0 @@
-
-
-#Converts the CSV files from CCF Coefficients Database to JSON.
-ccf-data:
-	cat third-party/ccf-coefficients/data/aws-instances.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/aws-instances.json
-	cat third-party/ccf-coefficients/output/coefficients-aws-use.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/aws-use.json
-	cat third-party/ccf-coefficients/output/coefficients-aws-embodied.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/aws-embodied.json
-	cat third-party/ccf-coefficients/data/gcp-instances.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/gcp-instances.json
-	cat third-party/ccf-coefficients/output/coefficients-gcp-use.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/gcp-use.json
-	cat third-party/ccf-coefficients/output/coefficients-gcp-embodied.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/gcp-embodied.json
-	cat third-party/ccf-coefficients/data/azure-instances.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/azure-instances.json
-	cat third-party/ccf-coefficients/output/coefficients-azure-use.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/azure-use.json
-	cat third-party/ccf-coefficients/output/coefficients-azure-embodied.csv | python -c 'import csv, json, sys; print(json.dumps([dict(r) for r in csv.DictReader(sys.stdin)]))' > lib/ccf/azure-embodied.json
-
-install-shell-imp:
-  cp src/lib/shell-imp/sampler /usr/local/bin/sampler

package/build/config/units.yaml

@@ -1,112 +0,0 @@
-carbon:
-  description: an amount of carbon emitted into the atmosphere
-  unit: gCO2e
-  aggregation: sum
-core-units:
-  description: number of cores available
-  unit: cores
-  aggregation: none
-cpu-util:
-  description: refers to CPU utilization.
-  unit: percentage
-  aggregation: avg
-disk-io:
-  description: refers to GB of data written/read from disk
-  unit: GB
-  aggregation: sum
-duration:
-  description: refers to the duration of the input
-  unit: seconds
-  aggregation: sum
-energy:
-  description: amount of energy utilised by the component
-  unit: kWh
-  aggregation: sum
-energy-cpu:
-  description: Energy consumed by the CPU of the component
-  unit: kWh
-  aggregation: sum
-expected-lifespan:
-  description: Total Expected Lifespan of the Component in Seconds
-  unit: seconds
-  aggregation: sum
-energy-memory:
-  description: Energy consumed by the Memory of the component
-  unit: kWh
-  aggregation: sum
-embodied-carbon:
-  description: Embodied Emissions of the component
-  unit: gCO2e
-  aggregation: sum
-energy-network:
-  description: Energy consumed by the Network of the component
-  unit: kWh
-  aggregation: 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: sum
-functional-unit-time:
-  description: string describing the unit of time in which the final SCI calculation should be expressed, e.g. "1-min"
-  unit: none
-  aggregation: none
-gpu-util:
-  description: refers to CPU utilization.
-  unit: percentage
-  aggregation: avg
-grid-carbon-intensity:
-  description: Carbon intensity for the grid
-  unit: gCO2eq/kWh
-  aggregation: avg
-instance-type:
-  description: Type of Cloud Instance name used in the cloud provider APIs
-  unit: None
-  aggregation: None
-location:
-  description: Geographic location of provider as string (for watt-time model it is provided as latitude and longitude, comma separated, in decimal degrees)
-  unit: None (decimal degrees for watt-time model)
-  aggregation: None
-operational-carbon:
-  description: Operational Emissions of the component
-  unit: gCO2e
-  aggregation: sum
-physical-processor:
-  description: Name of the physical processor 
-  unit: None
-  aggregation: none
-vendor:
-  description: Name of the cloud service provider in the ccf model. Can be aws, gcp or azure
-  unit: None
-  aggregation: none
-ram-alloc:
-  description: refers to GB of memory allocated.
-  unit: GB
-  aggregation: avg
-ram-util:
-  description: refers to percentage of memory utilized.
-  unit: percentage
-  aggregation: avg
-resources-reserved:
-  description: resources reserved for an application
-  unit: count
-  aggregation: none
-thermal-design-power:
-  description: thermal design power for a processor
-  unit: kwh
-  aggregation: avg
-total-embodied-emissions:
-  description: total embodied emissions of some component
-  unit: gCO2e
-  aggregation: sum
-timestamp:
-  description: refers to the time of occurrence of the input
-  unit: RFC3339
-  aggregation: none
-time-reserved:
-  description: time reserved for a component
-  unit: seconds
-  aggregation: none
-total-resources:
-  description: total resources available
-  unit: count
-  aggregation: none

package/build/lib/models-universe.d.ts

@@ -1,36 +0,0 @@
-import { ImplInitializeModel, InitalizedModels } from '../types/models-universe';
-/**
- * Models Initialization Lifecycle.
- */
-export declare class ModelsUniverse {
-    /**
-     * Models list.
-     */
-    initalizedModels: InitalizedModels;
-    /**
-     * Checks if model is instance of `IOutputModelInterface`.
-     */
-    private instanceOfModel;
-    /**
-     * Imports module by given `path`.
-     */
-    private importModuleFrom;
-    /**
-     * Imports `module` from given `path`, then checks if it's `ModelPluginInterface` extension.
-     */
-    private importAndVerifyModule;
-    /**
-     * Returns plugin model. Checks if model is missing then rejects with error.
-     * Then checks if `path` is starting with github, then grabs the repository name.
-     * Imports module, then checks if it's a class which implements input model interface.
-     */
-    private handModel;
-    /**
-     * Initializes and registers model.
-     */
-    writeDown(modelToInitalize: ImplInitializeModel): Promise<InitalizedModels>;
-    /**
-     * Returns existing model by `name`.
-     */
-    getInitializedModel(modelName: string, config: any): Promise<import("../types/model-interface").ModelPluginInterface>;
-}