Skip to content

Commit a5e09ec

Browse files
committed
add info about defaults and node config
1 parent b5dce9f commit a5e09ec

File tree

1 file changed

+20
-3
lines changed

1 file changed

+20
-3
lines changed

docs/major-concepts/manifest-file.md

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,15 @@ tree:
4848
duration: 3600
4949
```
5050
51-
### Global metadata
51+
Everything above the `tree` is collectively referred to as the `context`. The `tree` contains the input data and is structured according to the architecture of the application being examined, with individual components being nodes in the tree. Individual components can be grouped under parent nodes.
52+
53+
### Context
54+
55+
#### Metadata
5256

5357
The global metadata includes the `name`, `description`, and `tags` that can be used to describe the nature of the manifest file. For example, you might name the file `Carbon Jan 2024` or similar. A short description might briefly outline the scope of the manifest file, e.g. `company x's carbon emissions due to web serves from Jab 24 - July 24`. Tags can be used to group manifest files (we do not explicitly use this field for anything currently).
5458

55-
### Plugin initialization
59+
#### Initialize
5660

5761
The initialize section is where you define which plugins will be used in your manifest file and provide the global configuration for them. Below is sample for initialization:
5862

@@ -75,6 +79,7 @@ Impact Framework uses the `initialize` section to instantiate each plugin. A plu
7579

7680
`outputs` is a list of possible export types (currently `csv`, `yaml`, and `log` are supported).
7781

82+
7883
### Tree
7984

8085
The `tree` section of a manifest file defines the topology of all the components being measured. The shape of the `tree` defines the grouping of components. It describes the architecture of the application being studied and contains all the usage observations for each component. The tree has individual components such as leaves, intermediate nodes representing groupings, and the top level is the root.
@@ -158,7 +163,19 @@ tree:
158163
energy: 0.000811
159164
```
160165

161-
### Inputs
166+
#### Node config
167+
168+
Node level configuration is intended to include any configuration data that is constant from timestep to timestep, but varies across components in the tree. Values that are constant both within *and* across components should go in global config instead.
169+
170+
The plugin must be written such that it *expects* these values to exist in node level config and explicitly reads them in. The values expected in node level config should be defined in the plugin README.
171+
172+
#### Defaults
173+
174+
Defaults are fallback values that are only used if a given value is missing in the inputs array. For example, if you have a value that could feasibly be missing in a given timestep, perhaps because your plugin relies on a third party API that can fail, you can provide a value in `defaults` that can be used as a fallback value.
175+
176+
The values in defaults are applied to every timestep where the given value is missing. This means that as well as acting as a fallback `defaults` can be used as a convenience tool for efficiently adding a constant value to every timestep in your inputs array.
177+
178+
#### Inputs
162179

163180
Every component includes an `inputs` field that gets read into plugins as an array. `inputs` are divided into `observations`, each having a `timestamp` and a `duration`. Every `observation` refers to an element in `inputs` representing some snapshot in time.
164181

0 commit comments

Comments
 (0)