@tgwf/co2 0.7.0 → 0.9.0

package/src/readme.md

@@ -0,0 +1,66 @@
+# How to use the different models in CO2.js
+
+CO2js offers two models for understanding the environmental impact of compute - the 1byte model (`1byte.js`), and the Sustainable Web Design model (`swd.js`)
+
+### The 1byte model
+
+The default model in use is the 1byte model as used by the Shift Project, as introduced in their report on CO2 emissions from digital infrastructure, [Lean ICT: for a sober digital][soberDigital].
+
+This returns a number for the estimated CO2 emissions for the corresponding number of bytes sent over the wire, and has been used for video streaming, file downloads and websites.
+
+```js
+// assume you have imported or required the CO2 class from 1byte.js
+// for your runtime - either a browser, nodejs, etc.
+
+const bytesSent = (1024 * 1024 * 1024)
+const co2Emission = new CO2();
+const estimatedCO2 = co2Emission.perByte(bytesSent)
+```
+
+
+### The Sustainable Web Design model
+
+As of version 0.9, CO2.js also provides the  [Sustainable Web Design model][swd] for calculating emissions from digital services. As the name suggests, this has been designed for helping understand the environmental impact of websites. Further details are available on the [Sustainable Web Design website explaining the model](https://sustainablewebdesign.org/calculating-digital-emissions/), but for convenience, a short summary is below.
+
+#### How the SWD works
+
+This model uses data transfer as an proxy indicator for total resource usage, and uses this number to extrapolate energy usage numbers for your application as a fraction of the energy used by the total system comprised of:
+
+1. the use-phase energy of datacentres serving content
+2. the use-phase energy network transfering the data
+3. the use-phase energy of user device an user is accessing content on
+4. the total embodied energy used to create all of the above
+
+![swd model](../images/swd-energy-usage.png)
+
+It then converts these energy figures to carbon emissions, based on the carbon intensity of electricity from the [Ember annual global electricity review][Ember-annual-global-electricity-review].
+
+The carbon intensity of electricity figures for the swd model include the the full lifecycle emissions including upstream methane, supply-chain and manufacturing emissions, and include all gases, converted into CO2 equivalent over a 100 year timescale.
+
+This follows the approach used by the IPCC 5th Assessment Report Annex 3 (2014), for the carbon intensity of electricity.
+
+[Ember's methodology notes][ember-methodology] detail where the rest of this data comes from in more detail, as well as any further assumptions made.
+
+
+[ember-methodology]: https://ember-climate.org/app/uploads/2022/03/GER22-Methodology.pdf
+
+[Ember-annual-global-electricity-review]: https://ember-climate.org/insights/research/european-electricity-review-2022/
+
+
+
+
+### Sample usage
+
+```js
+// assume you have imported or required the CO2 class from swd.js
+// for your runtime - either a browser, nodejs, etc.
+
+// assume a 1 megabyte webpage
+const bytesSent = (1024 * 1024 * 1024)
+
+const co2Emission = new CO2();
+const estimatedCO2ForTransfer = co2Emission.emissionsPerVisitInGrams(bytesSent)
+```
+
+[soberDigital]: https://theshiftproject.org/en/lean-ict-2/
+[swd]: https://sustainablewebdesign.org/calculating-digital-emissions

package/src/sustainable-web-design.js

@@ -0,0 +1,224 @@
+"use strict";
+
+/**
+ * Sustainable Web Design
+ *
+ * Updated calculations and figures from
+ * https://sustainablewebdesign.org/calculating-digital-emissions/
+ *
+ *
+ */
+const { fileSize } = require("./constants");
+const { formatNumber } = require("./helpers");
+
+// this refers to the estimated total energy use for the internet around 2000 TWh,
+// divided by the total transfer it enables around 2500 exabytes
+const KWH_PER_GB = 0.81;
+
+// these constants outline how the energy is attributed to
+// different parts of the system in the SWD model
+const END_USER_DEVICE_ENERGY = 0.52;
+const NETWORK_ENERGY = 0.14;
+const DATACENTER_ENERGY = 0.15;
+const PRODUCTION_ENERGY = 0.19;
+
+// These carbon intensity figures https://ember-climate.org/data/data-explorer
+// - Global carbon intensity for 2021
+const GLOBAL_INTENSITY = 442;
+const RENEWABLES_INTENSITY = 50;
+
+// Taken from: https://gitlab.com/wholegrain/carbon-api-2-0/-/blob/master/includes/carbonapi.php
+
+const FIRST_TIME_VIEWING_PERCENTAGE = 0.25;
+const RETURNING_VISITOR_PERCENTAGE = 0.75;
+const PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD = 0.02;
+
+class SustainableWebDesign {
+  constructor(options) {
+    this.options = options;
+  }
+
+  /**
+   * Accept a figure for bytes transferred and return an object representing
+   * the share of the total enrgy use of the entire system, broken down
+   * by each corresponding system component
+   *
+   * @param {number}  bytes - the data transferred in bytes
+   * @return {object} Object containing the energy in kilowatt hours, keyed by system component
+   */
+  energyPerByteByComponent(bytes) {
+    const transferedBytesToGb = bytes / fileSize.GIGABYTE;
+    const energyUsage = transferedBytesToGb * KWH_PER_GB;
+
+    // return the total energy, with breakdown by component
+    return {
+      consumerDeviceEnergy: energyUsage * END_USER_DEVICE_ENERGY,
+      networkEnergy: energyUsage * NETWORK_ENERGY,
+      productionEnergy: energyUsage * PRODUCTION_ENERGY,
+      dataCenterEnergy: energyUsage * DATACENTER_ENERGY,
+    };
+  }
+  /**
+   * Accept an object keys by the different system components, and
+   * return an object with the co2 figures key by the each component
+   *
+   * @param {object} energyBycomponent - energy grouped by the four system components
+   * @param {number} [carbonIntensity] - carbon intensity to apply to the datacentre values
+   * @return {number} the total number in grams of CO2 equivalent emissions
+   */
+  co2byComponent(energyBycomponent, carbonIntensity = GLOBAL_INTENSITY) {
+    const returnCO2ByComponent = {};
+    for (const [key, value] of Object.entries(energyBycomponent)) {
+      // we update the datacentre, as that's what we have information
+      // about.
+      if (key === "dataCenterEnergy") {
+        returnCO2ByComponent[key] = value * carbonIntensity;
+      } else {
+        // We don't have info about the device location,
+        // nor the network path used, nor the production emissions
+        // so we revert to global figures
+        returnCO2ByComponent[key] = value * GLOBAL_INTENSITY;
+      }
+    }
+    return returnCO2ByComponent;
+  }
+
+  /**
+   * Accept a figure for bytes transferred and return a single figure for CO2
+   * emissions. Where information exists about the origin data is being
+   * fetched from, a different carbon intensity figure
+   * is applied for the datacentre share of the carbon intensity.
+   *
+   * @param {number} bytes - the data transferred in bytes
+   * @param {number} `carbonIntensity` the carbon intensity for datacentre (average figures, not marginal ones)
+   * @return {number} the total number in grams of CO2 equivalent emissions
+   */
+  perByte(bytes, carbonIntensity = GLOBAL_INTENSITY) {
+    const energyBycomponent = this.energyPerByteByComponent(bytes);
+
+    // when faced with falsy values, fallback to global intensity
+    if (Boolean(carbonIntensity) === false) {
+      carbonIntensity = GLOBAL_INTENSITY;
+    }
+    // if we have a boolean, we have a green result from the green web checker
+    // use the renewables intensity
+    if (carbonIntensity === true) {
+      carbonIntensity = RENEWABLES_INTENSITY;
+    }
+
+    // otherwise when faced with non numeric values throw an error
+    if (typeof carbonIntensity !== "number") {
+      throw new Error(
+        `perByte expects a numeric value or boolean for the carbon intensity value. Received: ${carbonIntensity}`
+      );
+    }
+
+    const co2ValuesbyComponent = this.co2byComponent(
+      energyBycomponent,
+      carbonIntensity
+    );
+
+    // pull out our values…
+    const co2Values = Object.values(co2ValuesbyComponent);
+
+    // so we can return their sum
+    return co2Values.reduce(
+      (prevValue, currentValue) => prevValue + currentValue
+    );
+  }
+
+  /**
+   * Accept a figure for bytes transferred and return the number of kilowatt hours used
+   * by the total system for this data transfer
+   *
+   * @param {number} bytes
+   * @return {number} the number of kilowatt hours used
+   */
+  energyPerByte(bytes) {
+    const energyByComponent = this.energyPerByteByComponent(bytes);
+
+    // pull out our values…
+    const energyValues = Object.values(energyByComponent);
+
+    // so we can return their sum
+    return energyValues.reduce(
+      (prevValue, currentValue) => prevValue + currentValue
+    );
+  }
+
+  /**
+   * Accept a figure for bytes transferred, and return an object containing figures
+   * per system component, with the caching assumptions applied. This tries to account
+   * for webpages being loaded from a cache by browsers, so if you had a thousand page views,
+   * and tried to work out the energy per visit, the numbers would reflect the reduced amounts
+   * of transfer.
+   *
+   * @param {number} bytes - the data transferred in bytes for loading a webpage
+   * @param {number} firstView - what percentage of visits are loading this page for the first time
+   * @param {number} returnView - what percentage of visits are loading this page for subsequent times
+   * @param {number} dataReloadRatio - what percentage of a page is reloaded on each subsequent page view
+   *
+   * @return {object} Object containing the energy in kilowatt hours, keyed by system component
+   */
+  energyPerVisitByComponent(
+    bytes,
+    firstView = FIRST_TIME_VIEWING_PERCENTAGE,
+    returnView = RETURNING_VISITOR_PERCENTAGE,
+    dataReloadRatio = PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD
+  ) {
+    const energyBycomponent = this.energyPerByteByComponent(bytes);
+    const cacheAdjustedSegmentEnergy = {};
+
+    for (const [key, value] of Object.entries(energyBycomponent)) {
+      // represent the first load
+      cacheAdjustedSegmentEnergy[key] = value * firstView;
+
+      // then represent the subsequent load
+      cacheAdjustedSegmentEnergy[key] += value * returnView * dataReloadRatio;
+    }
+
+    return cacheAdjustedSegmentEnergy;
+  }
+
+  /**
+   * Accept a figure for bytes, and return the total figure for energy per visit
+   * using the default caching assumptions for loading a single website
+   *
+   * @param {number} bytes
+   * @return {number} the total energy use for the visit, after applying the caching assumptions
+   */
+  energyPerVisit(bytes) {
+    // fetch the values using the default caching assumptions
+    const energyValues = Object.values(this.energyPerVisitByComponent(bytes));
+
+    // return the summed of the values to return our single number
+    return energyValues.reduce(
+      (prevValue, currentValue) => prevValue + currentValue
+    );
+  }
+
+  // TODO: this method looks like it applies the carbon intensity
+  // change to the *entire* system, not just the datacenter.
+  emissionsPerVisitInGrams(energyPerVisit, carbonintensity = GLOBAL_INTENSITY) {
+    return formatNumber(energyPerVisit * carbonintensity);
+  }
+
+  annualEnergyInKwh(energyPerVisit, monthlyVisitors = 1000) {
+    return energyPerVisit * monthlyVisitors * 12;
+  }
+
+  annualEmissionsInGrams(co2grams, monthlyVisitors = 1000) {
+    return co2grams * monthlyVisitors * 12;
+  }
+
+  annualSegmentEnergy(annualEnergy) {
+    return {
+      consumerDeviceEnergy: formatNumber(annualEnergy * END_USER_DEVICE_ENERGY),
+      networkEnergy: formatNumber(annualEnergy * NETWORK_ENERGY),
+      dataCenterEnergy: formatNumber(annualEnergy * DATACENTER_ENERGY),
+      productionEnergy: formatNumber(annualEnergy * PRODUCTION_ENERGY),
+    };
+  }
+}
+
+module.exports = SustainableWebDesign;

package/src/sustainable-web-design.test.js

@@ -0,0 +1,81 @@
+const SustainableWebDesign = require("./sustainable-web-design");
+
+describe("sustainable web design model", () => {
+  const swd = new SustainableWebDesign();
+  const averageWebsiteInBytes = 2257715.2;
+
+  describe("energyPerByteByComponent", () => {
+    it("should return a object with numbers for each system component", () => {
+      const groupedEnergy = swd.energyPerByteByComponent(averageWebsiteInBytes);
+
+      expect(groupedEnergy.consumerDeviceEnergy).toBeCloseTo(0.00088564, 8);
+      expect(groupedEnergy.networkEnergy).toBeCloseTo(0.00023844, 8);
+      expect(groupedEnergy.productionEnergy).toBeCloseTo(0.0003236, 8);
+      expect(groupedEnergy.dataCenterEnergy).toBeCloseTo(0.00025547, 8);
+    });
+  });
+
+  describe("energyPerByte", () => {
+    it("should return a number in kilowatt hours for the given data transfer in bytes", () => {
+      const energyForTransfer = swd.energyPerByte(averageWebsiteInBytes);
+      expect(energyForTransfer).toBeCloseTo(0.00170316, 7);
+    });
+  });
+
+  describe("perByte", () => {
+    it("should return a single number for CO2 emissions", () => {
+      expect(typeof swd.perByte(2257715.2)).toBe("number");
+    });
+  });
+
+  describe("energyPerVisit", function () {
+    it("should return a number", () => {
+      expect(typeof swd.energyPerVisit(averageWebsiteInBytes)).toBe("number");
+    });
+
+    it("should calculate the correct energy", () => {
+      expect(swd.energyPerVisit(averageWebsiteInBytes)).toBe(
+        0.0004513362121582032
+      );
+    });
+  });
+
+  describe("emissionsPerVisitInGrams", function () {
+    it("should calculate the correct co2 per visit", () => {
+      const averageWebsiteInBytes = 2257715.2;
+      const energy = swd.energyPerVisit(averageWebsiteInBytes);
+      expect(swd.emissionsPerVisitInGrams(energy)).toEqual(0.2);
+    });
+
+    it("should accept a dynamic KwH value", () => {
+      const averageWebsiteInBytes = 2257715.2;
+      const energy = swd.energyPerVisit(averageWebsiteInBytes);
+      expect(swd.emissionsPerVisitInGrams(energy, 245)).toEqual(0.11);
+    });
+  });
+
+  describe("annualEnergyInKwh", function () {
+    it("should calculate the correct energy in kWh", () => {
+      expect(swd.annualEnergyInKwh(averageWebsiteInBytes)).toBe(27092582400);
+    });
+  });
+
+  describe("annualEmissionsInGrams", function () {
+    it("should calculate the corrent energy in grams", () => {
+      expect(swd.annualEmissionsInGrams(averageWebsiteInBytes)).toBe(
+        27092582400
+      );
+    });
+  });
+
+  describe("annualSegmentEnergy", function () {
+    it("should return the correct values", () => {
+      expect(swd.annualSegmentEnergy(averageWebsiteInBytes)).toEqual({
+        consumerDeviceEnergy: 1174011.9,
+        dataCenterEnergy: 338657.28,
+        networkEnergy: 316080.13,
+        productionEnergy: 428965.89,
+      });
+    });
+  });
+});