Add Sustainable Web Design version 4

fershad commented 2 months ago

Triage

Type of change

Please select any of the below items that are appropriate.

This pull request:

[x] Adds a new carbon estimation model to CO2.js
[ ] Adds new functionality to an existing model
[ ] Fixes a bug with an existing model implementation
[ ] Add other new functionality to CO2.js
[ ] Add new data to CO2.js
[ ] Improves developer experience for contributors
[ ] Adds contributors to CO2.js
[ ] Does something not specified above

Related issue/s

Please list below any issues this pull request is related to.

119

Docs changes required

Do any changes made in this pull request require parts of the CO2.js documentation to be updated?

[x] Yes
[ ] No
[ ] I don't know

If you answered "Yes", please create an corresponding issue in our Developer Documentation repository.

Describe the changes made in this pull request

As clearly as possible, describe the changes made in the pull request. You should at least detail "what changes have been made" and "what the results of these changes will be".

These changes add the newer Sustainable Web Design Model version 4 calculation into CO2.js. This update DOES NOT remove the existing version 3 methodology which will continue to remain the default in CO2.js for the time being. Developers will have the option to opt-in to using the update version 4 methodology in their projects. They can do this when instantiating a new CO2 object that using the Sustainable Web Design Model. Code examples are below:

import {co2} from "@tgwf/co2";

const default = new co2(); // This will use SWDM version 3
const version3 = new co2({model: "swd"}); // This will use SWDM version 3
const version4 = new co2({model: "swd", version: 4}); // This uses SWDM version 4

The version key accepts a value of type number that must equal to 4. If that is not set, then the version 3 calculations are used by CO2.js.

Changes to outputs

Functionality wise, there are no changes between version 3 and version 4 of CO2.js. The perByte, perVisit, perByteTrace, and perVisitTrace functions all remain the same and accept the same inputs in both versions. The outputs of these functions also do no change by default.

However, when using the perByteTrace or perVisitTrace functions, developers can now pass in a greenHostingFactor value for use in the estimates. This value is used by the respective calculation if the green parameter passed into the function is false. When green === true then the GREEN_HOSTING_FACTOR used is set to 1.0. This reflects a continuation of the functionality that exists in Sustainable Web Design version 3 when changing the grid intensity of the data center segment (see: #197)

import {co2} from "@tgwf/co2";

const version4 = new co2({model: "swd", version: 4});
const bytes = 1000;
const greenHosting = true;
const options = { greenHostingFactor: 0.6 };

// This will set the `GREEN_HOSTING_FACTOR` used in the estimates to `1.0` despite the fact that it's also passed in using the options object.
const estimate = version4.perByteTrace(1000, greenHosting, options);

// This will set the `GREEN_HOSTING_FACTOR` used in the estimates to `0.6` as the parameter for green hosting has been set to `false`.
const estimate2 = version4.perByteTrace(1000, false, options);

Another important change to the output is seen when users select to return results per segment. These give a more detailed breakdown of the emissions estimates across each system segment. In SWDM version 4, emissions estimates are further separated into operational and embodied emissions. These are now all returned when a user asks for segmented results.

import { co2 } from '@tgwf/co2'

const version4 = new co2({model: "swd", version: 4, results: "segment" });

/* Results will be returned with the following keys
{
  dataCenterOperationalCO2e,
  networkOperationalCO2e,
  consumerDeviceOperationalCO2e,
  dataCenterEmbodiedCO2e,
  networkEmbodiedCO2e,
  consumerDeviceEmbodiedCO2e,
  totalOperationalCO2e,
  totalEmbodiedCO2e,
  dataCenterCO2e,
  networkCO2e,
  consumerDeviceCO2e,
  firstVisitCO2e, // Only for perVisit and perVisitTrace functions
  returnVisitCo2e, // Only for perVisit and perVisitTrace functions
  total
}
*/

Other things to note

Again, this update DOES NOT remove the existing version 3 methodology which will continue to remain the default in CO2.js for the time being. We will make an announcement and widely communicate the plan to switch to version 4 being the default later.
Communication around the difference in CO2e estimates returned using version 3 and version 4 will be made in a blog post on the Green Web Foundation blog that will accompany this release.
~~The SWD Rating Scale has not yet been added to the version 4 methodology. It could be included later in this PR, or via another PR if this one gets merged first.~~

fershad commented 1 month ago

@mrchrisadams when you've got some time, can you please mark my homework.

fershad commented 1 month ago

Added values and tests for the SWDM v4 Rating Scale to this update

fershad commented 1 month ago

Thanks @mrchrisadams I've fixed those constants & refactored a bit of code that was duplicated within and across models.

This is ready to merge & should be the final code change before publishing v0.16.0

thegreenwebfoundation / co2.js