@grnsft/if 0.6.0-beta.0 → 0.7.0-beta.0

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

@@ -2,135 +2,136 @@
 
 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)
+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
+Our plugin follows the Cloud Carbon Footprint methodology for calculating embodied carbon and extends it to scale down the total embodied carbon for a piece of hardware by the portion of it that should be allocated to a particular application, using a `usage-ratio` and `time`. The `usage-ratio` is a term that can be used to scale by, for example, the storage you actually use on a shared server, rather than the total storage available for that hardware, or the time you are active compared to the hardware lifespan.
 
-### Plugin config
 
-Not Needed
+## Parameters
 
-### Plugin parameter metadata
+### Plugin Configuration
 
-The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method` of the parameters of the inputs and outputs
+The `SciEmbodied` plugin requires a configuration object and parameter metadata (optional) to do the calculation.
 
-- `inputs`: describe the parameters of the `inputs`. Each parameter has:
+### Plugin Parameter Metadata
 
-  - `description`: description of the parameter
-  - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+The `parameter-metadata` section contains information about the `description`, `unit`, and `aggregation-method` of the input and output parameters.
 
-- `outputs`: describe the `carbon-embodied` parameter. The parameter has the following attributes:
-  - `description`: description of the parameter
-  - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+- `inputs`: Describes the parameters for the input data. Each parameter includes:
+  - `description`: A brief description of the parameter.
+  - `unit`: The unit of measurement for the parameter.
+  - `aggregation-method`: The method used to aggregate this parameter (`sum`, `avg`, or `none`).
 
-### Inputs
+- `outputs`: Describes the `embodied-carbon` parameter, which includes:
+  - `description`: A brief description of the parameter.
+  - `unit`: The unit of measurement for the parameter.
+  - `aggregation-method`: The method used to aggregate this parameter (`sum`, `avg`, or `none`).
 
-- `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.
+### Mapping
 
-> 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.
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
 
-## Returns
+```yaml
+sci-embodied:
+  method: SciEmbodied
+  path: 'builtins'
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
-- `carbon-embodied`: the carbon emitted in manufacturing and disposing of a component, in gCO2eq
+### Config
 
-## Calculation
+`baseline-vcpus`: the number of CPUs to use in the baseline server, defaults tothe CCF value of 1,
+`baseline-memory`: the amount of memory to use in the baseline server, defaults tothe CCF value of 16,
+`baseline-emissions`: the embodied carbon assumed to represent a baseline server, in g
+`lifespan`: the lifespan of the device, in seconds. Defaults to 4 years (126144000 seconds),
+`time`: the time to consider when scaling the total device embodied carbon, if not given defaults to `duration`
+`vcpu-emissions-constant`: emissions for a CPU in gCO2e. Defaults tothe CCF value (100000),
+`memory-emissions-constant`: value used in calculating emissions due to memory, defaults to the CCf value of 533/384
+`ssd-emissions-constant`: emissions for a SSD in gCO2e. Defaults tothe CCF value (50000),
+`hdd-emissions-constant`: emissions for a CPU in gCO2e. Defaults tothe CCF value (100000),
+`gpu-emissions-constant`: emissions for a GPU in gCO2e. Defaults tothe CCF value (150000),
+`output-parameter`: name to give the output value, defaults to `embodied-carbon`
 
-To calculate the embodied carbon, `m` for a software application, use the equation:
+Note that if you do not provide any config at all, we will fallback to defaults for everything, equivalent to setting the baseline server equal to the CCF version, which has 1000000g of embodied emissions.
 
-```
-m = te * ts * rs
-```
+### Inputs
 
-Where:
+- `vCPUs`: number of CPUs available on device
+- `memory`: amount of RAM available on device, in GB
+- `ssd`: number of SSD drives mounted on device
+- `hdd`: number of HDD drives mounted on device
+- `gpu`: number of GPUs available on device
+- `duration`: The length of time the hardware is reserved for use by the software, in seconds.
+- `time`: the time to use for scalign the total embodied carbon per timestap, if you do not want to use `duration`
+- `usage-ratio`: the ratio by which to scale down the total embodied carbon according to your usage, e.g. for a shared storage server the total storage divided by your actual storage.
 
-- `device/emissions-embodied` = Total embodied emissions; the sum of Life Cycle Assessment (LCA) emissions for the component.
+Note that if you do not provide any inputs at all, we fall back to defaults that are equivalent to using the full resources of the baseline server, scaled only by `duration`.
 
-- `timeShare` = Time-share; the share of the total life span of the hardware reserved for use by an application.
+### Outputs
 
-  - `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.
+- `embodied-carbon`: The total embodied emissions for the component, measured in gCO2e, per timestep.
 
-- `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.
+## Calculation
 
-## Implementation
+The plugin calculates the total embodied carbon emissions using the following steps:
 
-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`.
+   - CPU emissions (`cpuE`) are calculated based on the difference between allocated vCPUs and baseline vCPUs.
+   - Memory emissions (`memoryE`) are calculated based on the difference between allocated memory and baseline memory.
+   - Emissions for HDD, SSD, and GPU are also calculated based on their respective differences from baseline values.
+   - The total embodied emissions are calculated by summing the baseline emissions with the above components scaling by the usage ratio and time.
 
-## Usage
+## Implementation
 
-The following snippet demonstrates how to call the `sci-embodied` plugin from Typescript.
+The plugin can be instantiated and executed as follows:
 
 ```typescript
 import {SciEmbodied} from 'builtins';
 
-const sciEmbodied = SciEmbodied();
+const sciEmbodied = SciEmbodied(config, parametersMetadata, {});
 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
+    duration: 3600, // time reserved in seconds
+    vCPUs: 2,       // allocated vCPUs
+    memory: 32,     // allocated memory in GB
+    ssd: 100,       // allocated SSD storage in GB
+    hdd: 1000,      // allocated HDD storage in GB
+    gpu: 1,         // allocated GPUs
   },
 ]);
+
+console.log(results);
 ```
 
-## Example manifest
+# 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`:
+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-run` 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
+description: demo invoking sci-embodied
 tags:
 initialize:
   plugins:
     sci-embodied:
       method: SciEmbodied
       path: 'builtins'
+      mapping:
+        device/emissions-embodied: device/carbon-footprint
 tree:
   children:
     child:
       pipeline:
         compute:
-          - 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
+          - sci-embodied
       inputs:
-        - timestamp: 2023-07-06T00:00
+        - timestamp: 2024-08-19T00:00
           duration: 3600
 ```
 
-You can run this example `manifest` by executing the following command from the project root:
+To run this example manifest, use the following command:
 
-```sh
+```bash
 npm i -g @grnsft/if
-if-run --manifest manifests/plugins/sci-embodied.yml --output manifests/outputs/sci-embodied.yml
+if-run --manifest manifests/plugins/sci-embodied/success.yml --output manifests/outputs/success.yml
 ```
-
-The results will be saved to a new `yaml` file in `./examples/outputs`.
-
-## Errors
-
-`SciEmbodied` uses one of IF's error classes
-
-### `SciEmbodiedError`
-
-This error class is used to describe a problem with one of the input values to `sci-embodied`. This is typically due to an incorrect type or a reference to a value that is not available.
-
-You will receive a specific error message explaining which parameter is problematic, and you can check and replace where appropriate.
-
-For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors

package/src/if-run/builtins/shell/README.md

@@ -4,7 +4,7 @@ The `shell` is a wrapper enabling plugins implemented in any other programming l
 
 ## Parameters
 
-### Plugin global config
+### Plugin config
 
 The plugin should be initialized as follows:
 
@@ -14,7 +14,7 @@ initialize:
     shell:
       method: Shell
       path: 'builtin'
-      global-config:
+      config:
         command: python3 /usr/local/bin/sampler
 ```
 
@@ -30,12 +30,16 @@ The `parameter-metadata` section contains information about `description`, `unit
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
 - `outputs`: describe the output parameter. The parameter has the following attributes:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
 ### Inputs
 
@@ -53,7 +57,11 @@ The specific return types depend on the plugin being invoked. Typically, we woul
 To run the plugin, you must first create an instance of `Shell` and call its `execute()` to run the external plugin.
 
 ```typescript
-const output = Shell({command: '/usr/local/bin/sampler'});
+const config = {
+  command: '/usr/local/bin/sampler',
+};
+const parametersMetadata = {inputs: {}, outputs: {}};
+const output = Shell(config, parametersMetadata);
 const result = await output.execute([
   {
     timestamp: '2021-01-01T00:00:00Z',
@@ -85,7 +93,7 @@ initialize:
     sampler:
       method: Shell
       path: 'builtin'
-      global-config:
+      config:
         command: python3 /usr/local/bin/sampler
 tree:
   children:
@@ -112,7 +120,7 @@ initialize:
     sampler:
       method: Shell
       path: 'builtin'
-      global-config:
+      config:
         command: python3 /usr/local/bin/sampler
 tree:
   children:

package/src/if-run/builtins/subtract/README.md

@@ -10,7 +10,7 @@ For example, you could subtract `cpu/energy` and `network/energy` and name the r
 
 ### Plugin config
 
-Two parameters are required in global config: `input-parameters` and `output-parameter`.
+Two parameters are required in 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 result of the diff to the output array.
@@ -19,16 +19,32 @@ Two parameters are required in global config: `input-parameters` and `output-par
 
 The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method` of the parameters of the inputs and outputs
 
-- `inputs`: describe parameters of the `input-parameters` of the global config. Each parameter has the following attributes:
+- `inputs`: describe parameters of the `input-parameters` of the config. Each parameter has the following attributes:
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
-- `outputs`: describe the parameter of the `output-parameter` of the global config. The parameter has the following attributes:
+- `outputs`: describe the parameter of the `output-parameter` of the config. The parameter has the following attributes:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+
+### Mapping
+
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
+
+```yaml
+subtract:
+  method: Subtract
+  path: 'builtin'
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
 ### Inputs
 
@@ -36,7 +52,7 @@ All of `input-parameters` must be available in the input array.
 
 ## Returns
 
-- `output-parameter`: the subtraction of all `input-parameters` with the parameter name defined by `output-parameter` in global config.
+- `output-parameter`: the subtraction of all `input-parameters` with the parameter name defined by `output-parameter` in config.
 
 ## Calculation
 
@@ -55,9 +71,10 @@ const config = {
   inputParameters: ['cpu/energy', 'network/energy'],
   outputParameter: 'offset/energy',
 };
-
-const subtract = Subtract(config);
-const result = subtract subtract.execute([
+const parametersMetadata = {inputs: {}, outputs: {}};
+const mapping = {};
+const subtract = Subtract(config, parametersMetadata, mapping);
+const result = await subtract.execute([
   {
     duration: 3600,
     timestamp: '2021-01-01T00:00:00Z',
@@ -80,7 +97,7 @@ initialize:
     subtract:
       method: Subtract
       path: 'builtin'
-      global-config:
+      config:
         input-parameters: ['cpu/energy', 'network/energy']
         output-parameter: 'energy/diff'
 tree:
@@ -113,4 +130,4 @@ The results will be saved to a new `yaml` file in `manifests/outputs`.
 
 This error arises when an invalid value is passed to `Subtract`. Typically, this can occur when a non-numeric value (such as a string made of alphabetic characters) is passed where a number or numeric string is expected. Please check that the types are correct for all the relevant fields in your `inputs` array.
 
-For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors)

package/src/if-run/builtins/sum/README.md

@@ -10,7 +10,7 @@ For example, you could add `cpu/energy` and `network/energy` and name the result
 
 ### Plugin config
 
-Two parameters are required in global config: `input-parameters` and `output-parameter`.
+Two parameters are required in 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 result of summing the input parameters to the output array.
@@ -19,16 +19,32 @@ Two parameters are required in global config: `input-parameters` and `output-par
 
 The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method` of the parameters of the inputs and outputs
 
-- `inputs`: describe parameters of the `input-parameters` of the global config. Each parameter has:
+- `inputs`: describe parameters of the `input-parameters` of the config. Each parameter has:
 
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
 
-- `outputs`: describe the parameter of the `output-parameter` of the global config. The parameter has the following attributes:
+- `outputs`: describe the parameter of the `output-parameter` of the config. The parameter has the following attributes:
   - `description`: description of the parameter
   - `unit`: unit of the parameter
-  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+  - `aggregation-method`: aggregation method object of the parameter
+    - `time`: this value is used for `horizontal` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+    - `component`: this value is used for `vertical` aggregation. It can be of the following values: `sum`, `avg`, `copy`, or `none`.
+
+### Mapping
+
+The `mapping` block is an optional block. It is added in the plugin section and allows the plugin to receive a parameter from the input with a different name than the one the plugin uses for data manipulation. The parameter with the mapped name will not appear in the outputs. It also maps the output parameter of the plugin. The structure of the `mapping` block is:
+
+```yaml
+sum:
+  method: Sum
+  path: 'builtin'
+  mapping:
+    'parameter-name-in-the-plugin': 'parameter-name-in-the-input'
+```
 
 ### Inputs
 
@@ -36,7 +52,7 @@ All of `input-parameters` must be available in the input array.
 
 ## Returns
 
-- `output-parameter`: the sum of all `input-parameters` with the parameter name defined by `output-parameter` in global config.
+- `output-parameter`: the sum of all `input-parameters` with the parameter name defined by `output-parameter` in config.
 
 ## Calculation
 
@@ -53,9 +69,14 @@ const config = {
   inputParameters: ['cpu/energy', 'network/energy'],
   outputParameter: 'energy',
 };
+const parametersMetadata = {inputs: {}, outputs: {}};
+const = mapping {
+  'cpu/energy': 'energy-from-cpu',
+  'network/energy': 'energy-from-network',
+};
 
-const sum = Sum(config, parametersMetadata);
-const result = sum.execute([
+const sum = Sum(config, parametersMetadata, mapping);
+const result = await sum.execute([
   {
     timestamp: '2021-01-01T00:00:00Z',
     duration: 3600,
@@ -78,7 +99,7 @@ initialize:
     sum:
       method: Sum
       path: 'builtin'
-      global-config:
+      config:
         input-parameters: ['cpu/energy', 'network/energy']
         output-parameter: 'energy'
       parameter-metadata:
@@ -86,16 +107,28 @@ initialize:
           cpu/energy:
             description: energy consumed by the cpu
             unit: kWh
-            aggregation-method: sum
+            aggregation-method:
+              time: sum
+              component: sum
+            aggregation-method:
+              time: sum
+              component: sum
           network/energy:
             description: energy consumed by data ingress and egress
             unit: kWh
-            aggregation-method: sum
+            aggregation-method:
+              time: sum
+              component: sum
+            aggregation-method:
+              time: sum
+              component: sum
         outputs:
           energy:
             description: sum of energy components
             unit: kWh
-            aggregation-method: sum
+            aggregation-method:
+              time: sum
+              component: sum
 tree:
   children:
     child:
@@ -121,9 +154,9 @@ The results will be saved to a new `yaml` file in `./examples/outputs`.
 
 `Sum` exposes two of the IF error classes.
 
-### GlobalConfigError
+### ConfigError
 
-You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+You will receive an error starting `ConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
 
 The required parameters are:
 

package/src/if-run/builtins/time-converter/README.md

@@ -0,0 +1,136 @@
+# Time Converter
+
+`time-conversion` is a generic plugin for converting time values from a specified time unit to a new given time unit.
+
+You provide the energy value, the time unit associated with this energy, and a new time unit to which you want to convert it.
+
+For example, you could add `energy-per-year`, the time unit `year`, and the new time unit `duration`. The `energy-per-duration` would then be added to every observation in your input array as the converted value of `energy-per-year`, `year` and `duration`.
+
+## Parameters
+
+### Plugin config
+
+These parameters are required in config:
+
+- `input-parameter`: a string that should match an existing key in the `inputs` array
+- `original-time-unit`: a string that defines the time unit of the `input-parameter`. The original time unit should be a valid unit, like `year`, `month`, `day`, `hour` and so on
+- `new-time-unit`: a string that defines the new time unit that the `input-parameter` value should be converted to. The time unit can be `duration`(in which case it grabs the value from the `duration` in the input), or can be other time unit like `second`, `month`, `day`, `week` and so on
+- `output-parameter`: a string defining the name to use to add the result of converting the input parameter to the output array
+
+### Plugin parameter metadata
+
+The `parameter-metadata` section contains information about `description` and `unit` of the parameters of the inputs and outputs
+
+- `inputs`: describe parameters of the `input-parameter` of the config. Each parameter has:
+
+  - `description`: description of the parameter
+  - `unit`: unit of the parameter
+  - `aggregation-method`: the aggregation method of the parameter (can be `sum`, `avg` or `none`)
+
+- `outputs`: describe the parameter of the `output-parameter` of the config. The parameter has the following attributes:
+  - `description`: description of the parameter
+  - `unit`: unit of the parameter
+  - `aggregation-method`: the aggregation method of the parameter (can be `sum`, `avg` or `none`)
+
+### Inputs
+
+The `input-parameter` must be available in the input array.
+
+## Returns
+
+- `output-parameter`: the converted energy of the `input-parameter` with the parameter name defined by `output-parameter` in config.
+
+## Calculation
+
+```pseudocode
+output = input-parameter / original-time-unit * new-time-unit
+```
+
+## Implementation
+
+To run the plugin, you must first create an instance of `TimeConverter`. Then, you can call `execute()`.
+
+```typescript
+const config = {
+  'input-parameter': 'energy-per-year',
+  'original-time-unit': 'year',
+  'new-time-unit': 'duration',
+  'output-parameter': 'energy-per-duration',
+};
+
+const timeConverter = TimeConverter(config, parametersMetadata);
+const result = await timeConverter.execute([
+  {
+    timestamp: '2021-01-01T00:00:00Z',
+    duration: 3600,
+    'energy-per-year': 10000,
+  },
+]);
+```
+
+## 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 `time-coverstion`:
+
+```yaml
+name: time-coverstion demo
+description:
+tags:
+initialize:
+  plugins:
+    time-converter:
+      method: TimeConverter
+      path: builtin
+      config:
+        input-parameter: 'energy-per-year'
+        original-time-unit: 'year'
+        new-time-unit: 'duration'
+        output-parameter: 'energy-per-duration'
+tree:
+  children:
+    child:
+      pipeline:
+        - time-converter
+      config:
+      defaults:
+        energy-per-year: 10000
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+```
+
+You can run this example by saving it as `./examples/manifests/time-coverstion.yml` and executing the following command from the project root:
+
+```sh
+if-run --manifest ./examples/manifests/time-coverstion.yml --output ./examples/outputs/time-coverstion.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`.
+
+## Errors
+
+`TimeConverter` exposes two of the IF error classes.
+
+### ConfigError
+
+You will receive an error starting `ConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+
+The required parameters are:
+
+- `input-parameter`: this must be a string, which is the name of parameter in the `inputs` array
+- `original-time-unit`: this must be a string of time units (`minutes`, `seconds` and so on)
+- `new-time-unit`: this must be a string of time units (e.g. `duration`, `minutes`, `seconds` and so on)
+- `output-parameter`: this must be a string
+
+You can fix this error by checking you are providing valid values for each parameter in the config.
+
+### `MissingInputDataError`
+
+This error arises when a necessary piece of input data is missing from the `inputs` array.
+Every element in the `inputs` array must contain:
+
+- `timestamp`
+- `duration`
+- whatever values you passed to `input-parameter`
+
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors).