Green-Software-Foundation / if

Impact Framework
https://if.greensoftware.foundation/
MIT License
154 stars 40 forks source link

Naming convention for observation parameters (units.yml) #410

Closed jawache closed 7 months ago

jawache commented 9 months ago

Story

As a plugin author, I want guidance regarding how I should name my parameters so as to be a healthy participant in the ecosystem

Rationale

As we develop plugins, each plugin will output more parameters, and those parameters become standards that are consumed in downstream plugins. Very quickly, we are going to have 100's if not 1000's of parameters, and we need some rules regarding how they are named.

Implementation details

This naming convention is being proposed after reviewing the current choice of names and their units and a review of metrology literature. The intention is to propose a standard that aligns somewhat with convention, somewhat with existing metrology rules, doesn't require significant changes to the existing ecosystem of plugins for IF, and is future-proofed.

One big issue with the current units.yml is the inconsistency with naming. Taking one example, we have two params currently cpu-util and energy-cpu. In the first, the cpu is at the start; in the second, the cpu is at the end. We have no rules for where the term cpu should go. This is the reason we need a naming convention.

Types Of Parameters

Looking at the existing units.yml, there seem to be two broad types of parameters.

Each of these will have a different naming convention

Naming Convention - Measurement Parameters

Examples

Parameter Domain Metric Type
energy global energy kWh
energy:j global energy joules
cpu:energy cpu energy kWh
cpu:energy:j cpu energy joules
carbon global carbon gCO2e
grid:carbon-intensity grid carbon-intensity gCO2e/kWh
software:carbon-intensity software carbon-intensity gCO2e/R
cpu:utilization cpu utilization percentage

Naming Convention - Context Parameters

Context parameters will most likely have a type of string, although they may have numeric constants also.

Examples

Priority

5 since this will form part of the standard that hackathon participants should adopt.

Scope

This affects all the model plugins. The changes proposed here would result in existing model plugins needing to be updated to match the new convention.

Size

Documenting 1d Aligning all the existing model plugins 1-2d.

What does "done" look like?

Does this require updates to documentation or other materials??

Yes, we will need docs in the main if docs repo.

What testing is required?

All model unit tests will need to be updated so they pass.

Is this a known/expected update?

Somewhat discussed in several other places https://github.com/Green-Software-Foundation/if/issues/403

jawache commented 8 months ago

Something to discuss, I've used colon as a seperator above (cpu:energy) however in yaml : has a special meaning and is used all the time so it would look like cpu:energy: 100. Technically it's fine since colon only has special meaning if it's followed by a space, if it's inside a key then it's fine.

This has some good rules https://www.yaml.info/learn/quote.html

It seems that the best option is to use / instead of :

grid:carbon-intensity -> grid/carbon-intensity cpu:energy:j -> cpu/energy/j

jawache commented 8 months ago

Going through the current parameters, according to the above rules it should be at least:

Or should it be:

i.e. is embodied and operational, a domain and carbon the metric? or is it fair to say that operational-carbon is a metric?

If the first is ok, then why wouldn't

be ok?

Why is something a domain vs just a more specific particle in a parameter?

Generally I'm leaning to

but I can't figure out a rule as to why that makes sense to me over

jmcook1186 commented 8 months ago

Bumping to Sprint 7

jmcook1186 commented 8 months ago

now just requires docs at if.greensoftware.foundation

jmcook1186 commented 7 months ago

Closing as complete