Track the energy and carbon cost of a computation

morie_emissions_start() opens a tracker; morie_emissions_stop() closes it, appends one row to emissions.csv in output_dir (the CodeCarbon column layout, the same file the Python package writes) and, unless capsule = FALSE, seals the run in a bricklayer capsule: emissions_manifest.json (the measurements, the method and the R environment) and capsule_bundle.json (SHA-256 digests of both files under a post-quantum ML-DSA signature). morie_emissions_track() wraps an expression in the two calls.

Usage

morie_emissions_start(
  project_name = "morie",
  output_dir = NULL,
  output_file = "emissions.csv",
  pue = 1,
  wue = 0,
  country_iso_code = "",
  region = "",
  save_to_file = !is.null(output_dir),
  capsule = !is.null(output_dir),
  key = NULL,
  measure_power_secs = 1
)

morie_emissions_stop(tracker)

morie_emissions_track(expr, ...)

Arguments

project_name

Label written to the CSV and the manifest.

output_dir

Where emissions.csv and the capsule go. NULL (the default) writes nothing: the measurement is returned in R only.

output_file

CSV file name.

pue, wue

Power and water usage effectiveness multipliers.

country_iso_code, region

Location overrides.

save_to_file

Write the CSV row.

capsule

Seal the run in a bricklayer capsule.

key

A signing key from rmoriebricklayer::fips_keygen() or pqc_keygen(); generated per run when NULL.

measure_power_secs

Seconds between utilisation samples of the background sampler (the Python arm's default is 15; 1 here, since R runs are usually shorter).

tracker

The object from morie_emissions_start().

expr

An expression to evaluate under tracking.

...

Passed to morie_emissions_start().

Value

morie_emissions_stop(): the emissions in kg CO2eq, with the full row as attribute data and the capsule paths as attribute capsule. morie_emissions_track(): a list with value, emissions_kg, data and capsule.

Details

Power follows the CodeCarbon methodology: CPU thermal design power from the model name scaled by utilisation as \(TDP (0.1 + 0.9 u^3)\), RAM by DIMM count, no GPU. Utilisation is sampled every measure_power_secs by a C++ background thread reading the kernel's aggregate CPU counters (/proc/stat on Linux, host_statistics on macOS) and power is integrated per sample, as the Python tracker does ("machine" tracking mode). Where no counters exist the R process's CPU time over wall time is used instead ("process" mode). Emissions are energy times the grid's carbon intensity (morie_emissions_carbon_intensity) times PUE. The country comes from country_iso_code, else the MORIE_COUNTRY_ISO environment variable, else a geolocation lookup, else, offline (MORIE_EMISSIONS_OFFLINE set, or the lookup failed), the system time zone mapped to its country through the IANA zone tables (every zone and alias of zone.tab and backward: Europe/Stockholm is Sweden, US/Eastern the United States) and then the territory of the locale (en_CA.UTF-8 is Canada); the world average only when none of these names a country. Two-letter codes are mapped to the energy table's three-letter codes through the full ISO 3166 list.

The capsule's signing key is generated for the run unless key is given, so a verifier learns that the files have not changed since they were sealed, not who sealed them; pass your own rmoriebricklayer::fips_keygen() key to bind the run to you.

Examples

dir <- tempfile()
r <- morie_emissions_track(sum(sqrt(1:1e5)), project_name = "demo",
                           output_dir = dir, country_iso_code = "CAN")
r$emissions_kg > 0
#> [1] TRUE
list.files(dir)
#> [1] "capsule_bundle.json"     "emissions.csv"          
#> [3] "emissions_manifest.json"
unlink(dir, recursive = TRUE)