saef 3.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- saef/__init__.py +27 -0
- saef/__main__.py +3 -0
- saef/_calc.py +350 -0
- saef/_core.py +165 -0
- saef/cli.py +73 -0
- saef/data/cloud_region_factors.csv +144 -0
- saef/data/factors_v3_lifecycle.csv +103 -0
- saef/data/grid_intensity_all.csv +241 -0
- saef/data/model_class_mapping.csv +188 -0
- saef/data/model_factors.csv +33 -0
- saef/data/region_grid_crosswalk.csv +18 -0
- saef/data/region_water_factors.csv +18 -0
- saef/data/reserved_capacity_factors.csv +4 -0
- saef/data/token_basis_constants.csv +8 -0
- saef-3.0.0.dist-info/METADATA +115 -0
- saef-3.0.0.dist-info/RECORD +20 -0
- saef-3.0.0.dist-info/WHEEL +4 -0
- saef-3.0.0.dist-info/entry_points.txt +2 -0
- saef-3.0.0.dist-info/licenses/LICENSE +396 -0
- saef-3.0.0.dist-info/licenses/LICENSE-CODE +24 -0
saef/__init__.py
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""SOMA AI Emission Factors (SAEF): estimated carbon and water factors for AI inference."""
|
|
2
|
+
from ._core import (
|
|
3
|
+
DATASET_VERSION,
|
|
4
|
+
Estimate,
|
|
5
|
+
SaefError,
|
|
6
|
+
citation,
|
|
7
|
+
estimate,
|
|
8
|
+
factor,
|
|
9
|
+
grids,
|
|
10
|
+
model_class_for,
|
|
11
|
+
regions,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__version__ = DATASET_VERSION
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"DATASET_VERSION",
|
|
18
|
+
"Estimate",
|
|
19
|
+
"SaefError",
|
|
20
|
+
"__version__",
|
|
21
|
+
"citation",
|
|
22
|
+
"estimate",
|
|
23
|
+
"factor",
|
|
24
|
+
"grids",
|
|
25
|
+
"model_class_for",
|
|
26
|
+
"regions",
|
|
27
|
+
]
|
saef/__main__.py
ADDED
saef/_calc.py
ADDED
|
@@ -0,0 +1,350 @@
|
|
|
1
|
+
"""Calculator for the SAEF v3 lifecycle-boundary tables. Reads only the bundled CSVs.
|
|
2
|
+
|
|
3
|
+
Method (dataset V3_LIFECYCLE_SPEC.md, section 10):
|
|
4
|
+
kg CO2e = T_eff / 1e6 x inference footprint + T_billed / 1e6 x training term
|
|
5
|
+
T_eff = (T_out + W_in x T_in_uncached + W_cache x T_in_cached) / D
|
|
6
|
+
Never multiply a billed token count by an inference footprint.
|
|
7
|
+
"""
|
|
8
|
+
import csv
|
|
9
|
+
import difflib
|
|
10
|
+
import io
|
|
11
|
+
import re
|
|
12
|
+
from functools import lru_cache
|
|
13
|
+
from importlib import resources
|
|
14
|
+
|
|
15
|
+
PATH_NOISE = {
|
|
16
|
+
"models", "model", "publishers", "registries", "versions", "version", "projects", "locations",
|
|
17
|
+
"deployments", "inference-profile", "inference-profiles", "endpoints", "foundry", "openai",
|
|
18
|
+
"azureml:", "azureml", "arn:aws:bedrock:", "providers", "catalogs", "assets",
|
|
19
|
+
}
|
|
20
|
+
DOT_REGION = {"us", "eu", "apac", "us-gov", "global", "jp", "au", "ca", "sa", "me", "il", "uk", "in"}
|
|
21
|
+
DOT_VENDOR = {
|
|
22
|
+
"anthropic", "amazon", "meta", "mistral", "cohere", "ai21", "stability", "deepseek", "openai",
|
|
23
|
+
"google", "writer", "luma", "twelvelabs", "qwen", "nvidia", "moonshot", "zai", "minimax",
|
|
24
|
+
"microsoft", "xai", "alibaba", "tencent", "baidu", "perplexity", "snowflake", "databricks",
|
|
25
|
+
}
|
|
26
|
+
UNKNOWN_REGION = {"", "unknown", "global", "global-average", "world", "any", "none", "mixed", "multi-region"}
|
|
27
|
+
EU27_REGION = {"eu-27", "eu27", "eu", "eu-only", "eu data zone", "european union"}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class SaefError(ValueError):
|
|
31
|
+
pass
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@lru_cache(maxsize=None)
|
|
35
|
+
def read(name):
|
|
36
|
+
text = resources.files("saef").joinpath("data", name).read_text(encoding="utf-8")
|
|
37
|
+
rows = list(csv.DictReader(io.StringIO(text, newline="")))
|
|
38
|
+
for i, r in enumerate(rows, 2):
|
|
39
|
+
r["_file"], r["_line"] = name, i
|
|
40
|
+
return tuple(rows)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def prov(out, quantity, row, col):
|
|
44
|
+
out.append({"quantity": quantity, "file": row["_file"], "line": row["_line"], "column": col, "value": row[col]})
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@lru_cache(maxsize=None)
|
|
48
|
+
def constants():
|
|
49
|
+
return {r["constant"]: r for r in read("token_basis_constants.csv")}
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def const(name):
|
|
53
|
+
return float(constants()[name]["central"])
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def normalise_identifier(identifier):
|
|
57
|
+
s = str(identifier).strip().lower()
|
|
58
|
+
cands = [s]
|
|
59
|
+
body = s
|
|
60
|
+
if body.startswith("arn:aws:bedrock:"):
|
|
61
|
+
body = body.rsplit("/", 1)[-1]
|
|
62
|
+
segs = [x for x in body.split("/") if x and x not in PATH_NOISE and not x.isdigit()]
|
|
63
|
+
if segs:
|
|
64
|
+
body = segs[-1]
|
|
65
|
+
cands.append(body)
|
|
66
|
+
stripped, dropped = body, []
|
|
67
|
+
while "." in stripped:
|
|
68
|
+
head, rest = stripped.split(".", 1)
|
|
69
|
+
if head in DOT_REGION or head in DOT_VENDOR:
|
|
70
|
+
dropped.append(head)
|
|
71
|
+
stripped = rest
|
|
72
|
+
else:
|
|
73
|
+
break
|
|
74
|
+
if stripped != body:
|
|
75
|
+
cands.append(stripped)
|
|
76
|
+
if dropped and dropped[-1] in DOT_VENDOR:
|
|
77
|
+
cands.append(f"{dropped[-1]}-{stripped}")
|
|
78
|
+
cands += [c.replace(".", "-") for c in cands if "." in c]
|
|
79
|
+
out = list(dict.fromkeys(c for c in cands if c))
|
|
80
|
+
return out
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _rank(pattern):
|
|
84
|
+
lit_prefix = pattern.split("*", 1)[0]
|
|
85
|
+
return (len(lit_prefix), len(pattern.replace("*", "")), len(pattern), pattern)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
@lru_cache(maxsize=None)
|
|
89
|
+
def _patterns():
|
|
90
|
+
out = []
|
|
91
|
+
for r in read("model_class_mapping.csv"):
|
|
92
|
+
for alt in r["pattern"].split(";"):
|
|
93
|
+
alt = alt.strip().lower()
|
|
94
|
+
if alt:
|
|
95
|
+
rx = re.compile("".join(".*" if p == "*" else re.escape(p) for p in re.split(r"(\*)", alt)))
|
|
96
|
+
out.append((_rank(alt), rx, r))
|
|
97
|
+
out.sort(key=lambda x: x[0], reverse=True)
|
|
98
|
+
return out
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _measured_id(cands):
|
|
102
|
+
byid = {r["model_id"].lower(): r["model_id"] for r in read("model_factors.csv")}
|
|
103
|
+
bylast = {k.rsplit("/", 1)[-1]: v for k, v in byid.items()}
|
|
104
|
+
for c in cands:
|
|
105
|
+
c = c.strip().lower()
|
|
106
|
+
if c in byid:
|
|
107
|
+
return byid[c]
|
|
108
|
+
if c in bylast:
|
|
109
|
+
return bylast[c]
|
|
110
|
+
return None
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def map_model(identifier):
|
|
114
|
+
cands = normalise_identifier(identifier)
|
|
115
|
+
warnings, p = [], []
|
|
116
|
+
hit = next((r for _k, rx, r in _patterns() if any(rx.match(c) for c in cands)), None)
|
|
117
|
+
if hit is None:
|
|
118
|
+
raise SaefError("model_class_mapping.csv has no default row")
|
|
119
|
+
prov(p, "model class", hit, "model_class")
|
|
120
|
+
out = dict(
|
|
121
|
+
identifier=str(identifier), pattern=hit["pattern"], basis=hit["basis"], model_class=hit["model_class"],
|
|
122
|
+
own_factor_model_id=hit["own_factor_model_id"] or None, out_of_scope=hit["model_class"] == "out-of-scope",
|
|
123
|
+
is_default_fallback=hit["basis"] == "default", warnings=warnings, provenance=p,
|
|
124
|
+
)
|
|
125
|
+
if out["is_default_fallback"]:
|
|
126
|
+
warnings.append(f"unmapped model identifier {identifier!r}: defaulted to Class {hit['model_class']} and flagged")
|
|
127
|
+
if out["out_of_scope"]:
|
|
128
|
+
out["model_class"] = None
|
|
129
|
+
warnings.append(f"{identifier!r} matches the out-of-scope pattern {hit['pattern']!r}: {hit['notes']}")
|
|
130
|
+
elif hit["basis"] == "tier":
|
|
131
|
+
warnings.append(
|
|
132
|
+
f"class proxy for a closed model: {identifier!r} was placed in Class {hit['model_class']} by the "
|
|
133
|
+
f"vendor pricing tier, not by a disclosed size ({hit['size_or_tier_note']})"
|
|
134
|
+
)
|
|
135
|
+
direct = _measured_id(cands + [str(identifier)])
|
|
136
|
+
if direct:
|
|
137
|
+
out["own_factor_model_id"] = direct
|
|
138
|
+
out["basis"] = "measured"
|
|
139
|
+
return out
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _suggest(region):
|
|
143
|
+
pool = {r["region_id"] for r in read("cloud_region_factors.csv")} | {r["grid_id"] for r in read("grid_intensity_all.csv")}
|
|
144
|
+
low = region.lower()
|
|
145
|
+
near = sorted(x for x in pool if x.lower().startswith(low))[:8] or difflib.get_close_matches(region, sorted(pool), n=5)
|
|
146
|
+
return near
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def resolve_region(provider=None, region=None):
|
|
150
|
+
"""Resolve to one grid row. Unknown or global regions use the global average, as the dataset's decision rule says;
|
|
151
|
+
a region string that matches nothing raises SaefError."""
|
|
152
|
+
warnings, p = [], []
|
|
153
|
+
grids = {r["grid_id"]: r for r in read("grid_intensity_all.csv")}
|
|
154
|
+
key = (region or "").strip()
|
|
155
|
+
low = key.lower()
|
|
156
|
+
|
|
157
|
+
def finish(grid_row, how, class_row=None, region_id=None):
|
|
158
|
+
prov(p, "grid carbon intensity", grid_row, "grid_kg_co2e_per_kwh")
|
|
159
|
+
return dict(
|
|
160
|
+
grid_id=grid_row["grid_id"], grid_name=grid_row["name"],
|
|
161
|
+
grid_kg_co2e_per_kwh=float(grid_row["grid_kg_co2e_per_kwh"]),
|
|
162
|
+
class_row=grid_row if class_row is None else class_row,
|
|
163
|
+
region_id=region_id or grid_row["grid_id"], how=how, warnings=warnings, provenance=p,
|
|
164
|
+
)
|
|
165
|
+
|
|
166
|
+
if low in UNKNOWN_REGION:
|
|
167
|
+
warnings.append("region unknown or global: the global-average grid row (WORLD) is applied, per the dataset's serving-region decision rule")
|
|
168
|
+
return finish(grids["WORLD"], "unknown -> global average", region_id="global-average")
|
|
169
|
+
if low in EU27_REGION:
|
|
170
|
+
warnings.append("EU data zone or EU-only processing: the EU-27 average grid row (EU27) is applied")
|
|
171
|
+
return finish(grids["EU27"], "EU-only processing -> EU-27", region_id="eu-27")
|
|
172
|
+
|
|
173
|
+
cloud = [r for r in read("cloud_region_factors.csv") if r["region_id"].lower() == low]
|
|
174
|
+
if provider:
|
|
175
|
+
cloud = [r for r in cloud if r["provider"].lower() == provider.strip().lower()]
|
|
176
|
+
if cloud:
|
|
177
|
+
if len({r["grid_id"] for r in cloud}) > 1:
|
|
178
|
+
raise SaefError(f"Region {region!r} is used by several providers with different grids, pass provider=")
|
|
179
|
+
r = cloud[0]
|
|
180
|
+
if r["mapping_confidence"] == "medium":
|
|
181
|
+
warnings.append(f"region mapping confidence is medium for {r['provider']}/{r['region_id']}: {r['mapping_notes']}")
|
|
182
|
+
prov(p, "cloud region to grid", r, "grid_id")
|
|
183
|
+
return finish(grids[r["grid_id"]], f"cloud region {r['provider']}/{r['region_id']}", class_row=r, region_id=r["region_id"])
|
|
184
|
+
|
|
185
|
+
hit = next((r for r in read("region_grid_crosswalk.csv") if r["region_id"].lower() == low), None)
|
|
186
|
+
if hit:
|
|
187
|
+
prov(p, "printed region to grid", hit, "grid_id")
|
|
188
|
+
return finish(grids[hit["grid_id"]], f"printed region {hit['region_id']}", region_id=hit["region_id"])
|
|
189
|
+
if key.upper() in grids:
|
|
190
|
+
g = grids[key.upper()]
|
|
191
|
+
return finish(g, f"{g['kind'].replace('_', ' ')} {g['grid_id']}")
|
|
192
|
+
byname = [r for r in grids.values() if r["name"].strip().lower() == low]
|
|
193
|
+
if len(byname) == 1:
|
|
194
|
+
return finish(byname[0], f"country name -> {byname[0]['grid_id']}")
|
|
195
|
+
hint = _suggest(key)
|
|
196
|
+
msg = f"Unknown region {region!r}."
|
|
197
|
+
if hint:
|
|
198
|
+
msg += f" Did you mean: {', '.join(hint)}?"
|
|
199
|
+
msg += " Use a cloud region id (see saef.regions()), an ISO-3 country code, an eGRID subregion, 'eu-27' or 'unknown'."
|
|
200
|
+
raise SaefError(msg)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def effective_tokens(output=0.0, uncached_input=0.0, cached_input=0.0):
|
|
204
|
+
return (output + const("W_in") * uncached_input + const("W_cache") * cached_input) / const("D")
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def effective_from_billed(billed):
|
|
208
|
+
s = const("default_input_share")
|
|
209
|
+
return billed * (1 - s + const("W_in") * s) / const("D")
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _class_terms(cl, reg, p):
|
|
213
|
+
c = cl.lower()
|
|
214
|
+
row = reg["class_row"]
|
|
215
|
+
cols = {
|
|
216
|
+
"footprint": f"class_{c}_inference_footprint_kg_per_m_effective_tokens",
|
|
217
|
+
"training": f"class_{c}_training_kg_per_m_billed_tokens",
|
|
218
|
+
"footprint_high": f"class_{c}_inference_footprint_high_case_kg_per_m_effective_tokens",
|
|
219
|
+
"development": f"class_{c}_development_line_kg_per_m_effective_tokens",
|
|
220
|
+
"electricity": f"class_{c}_electricity_kg_per_m_effective_tokens",
|
|
221
|
+
"embodied": f"class_{c}_embodied_kg_per_m_effective_tokens",
|
|
222
|
+
"construction": f"class_{c}_construction_kg_per_m_effective_tokens",
|
|
223
|
+
"per_billed": f"class_{c}_factor_kg_per_m_billed_tokens_default_mix",
|
|
224
|
+
}
|
|
225
|
+
if cols["footprint"] not in row:
|
|
226
|
+
raise SaefError(f"no class factors for model class {cl!r}; use A, B or C")
|
|
227
|
+
f = {k: float(row[col]) for k, col in cols.items()}
|
|
228
|
+
for k in ("footprint", "training", "footprint_high", "development"):
|
|
229
|
+
prov(p, k.replace("_", " "), row, cols[k])
|
|
230
|
+
f["basis"] = f"class {cl} mean of the measured members, H100"
|
|
231
|
+
return f
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def _model_terms(model_id, reg, p):
|
|
235
|
+
r = next((r for r in read("model_factors.csv") if r["model_id"] == model_id and r["gpu"] == "H100"), None)
|
|
236
|
+
if r is None:
|
|
237
|
+
return None
|
|
238
|
+
grid = reg["grid_kg_co2e_per_kwh"]
|
|
239
|
+
fac, fac_hi = float(r["facility_wh_per_1k_effective_tokens"]), float(r["facility_wh_high_case_per_1k_effective_tokens"])
|
|
240
|
+
emb, con = float(r["embodied_kg_co2e_per_m_tokens"]), float(r["construction_kg_co2e_per_m_tokens"])
|
|
241
|
+
emb_hi, con_hi = float(r["embodied_high_case_kg_co2e_per_m_tokens"]), float(r["construction_high_case_kg_co2e_per_m_tokens"])
|
|
242
|
+
tr = float(r["training_kg_co2e_per_m_billed_tokens"])
|
|
243
|
+
for q, col in (("facility Wh per 1,000 effective tokens", "facility_wh_per_1k_effective_tokens"),
|
|
244
|
+
("embodied", "embodied_kg_co2e_per_m_tokens"), ("construction", "construction_kg_co2e_per_m_tokens"),
|
|
245
|
+
("training term", "training_kg_co2e_per_m_billed_tokens")):
|
|
246
|
+
prov(p, q, r, col)
|
|
247
|
+
mult = (1 - const("default_input_share") + const("W_in") * const("default_input_share")) / const("D")
|
|
248
|
+
foot = fac * grid + emb + con
|
|
249
|
+
return dict(
|
|
250
|
+
footprint=foot, training=tr, footprint_high=fac_hi * grid + emb_hi + con_hi,
|
|
251
|
+
development=float(r["development_line_kg_co2e_per_m_tokens_global"]) / float(r["grid_kg_co2e_per_kwh"]) * grid,
|
|
252
|
+
electricity=fac * grid, embodied=emb, construction=con, per_billed=foot * mult + tr,
|
|
253
|
+
model_class=r["model_class"], basis=f"measured model {model_id}, H100",
|
|
254
|
+
)
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
def emissions(model=None, model_class=None, provider=None, region=None, billed_tokens=None,
|
|
258
|
+
output_tokens=0.0, input_tokens=0.0, cached_input_tokens=0.0):
|
|
259
|
+
warnings, p = [], []
|
|
260
|
+
if (model is None) == (model_class is None):
|
|
261
|
+
raise SaefError("Pass exactly one of model or model_class")
|
|
262
|
+
own = None
|
|
263
|
+
if model is not None:
|
|
264
|
+
mm = map_model(model)
|
|
265
|
+
warnings += mm["warnings"]
|
|
266
|
+
p += mm["provenance"]
|
|
267
|
+
if mm["out_of_scope"]:
|
|
268
|
+
raise SaefError(f"{model!r} is out of scope (embeddings, image, audio, video or moderation): no estimate. {mm['warnings'][-1]}")
|
|
269
|
+
cl, own, basis = mm["model_class"], mm["own_factor_model_id"], mm["basis"]
|
|
270
|
+
matched = mm["pattern"]
|
|
271
|
+
else:
|
|
272
|
+
cl = {"a": "A", "b": "B", "c": "C"}.get(str(model_class).strip().lower().replace("class_", "")[:1], None)
|
|
273
|
+
if cl is None:
|
|
274
|
+
raise SaefError(f"Unknown model class {model_class!r}; use A, B or C")
|
|
275
|
+
basis, matched = "caller-supplied", None
|
|
276
|
+
reg = resolve_region(provider, region)
|
|
277
|
+
warnings += reg["warnings"]
|
|
278
|
+
p += reg["provenance"]
|
|
279
|
+
|
|
280
|
+
if billed_tokens is not None:
|
|
281
|
+
billed = float(billed_tokens)
|
|
282
|
+
t_eff = effective_from_billed(billed)
|
|
283
|
+
warnings.append(
|
|
284
|
+
f"no input/output split given: the default input share {const('default_input_share'):g} and no cache credit were applied"
|
|
285
|
+
)
|
|
286
|
+
else:
|
|
287
|
+
billed = float(input_tokens) + float(cached_input_tokens) + float(output_tokens)
|
|
288
|
+
t_eff = effective_tokens(float(output_tokens), float(input_tokens), float(cached_input_tokens))
|
|
289
|
+
if not cached_input_tokens:
|
|
290
|
+
warnings.append("no cached-token count given, so no cache credit was taken")
|
|
291
|
+
for k in ("W_in", "W_cache", "D", "default_input_share"):
|
|
292
|
+
prov(p, f"token basis {k}", constants()[k], "central")
|
|
293
|
+
|
|
294
|
+
f = _model_terms(own, reg, p) if own else None
|
|
295
|
+
if f is not None:
|
|
296
|
+
cl, basis = f["model_class"], "measured"
|
|
297
|
+
else:
|
|
298
|
+
f = _class_terms(cl, reg, p)
|
|
299
|
+
kg = t_eff / 1e6 * f["footprint"] + billed / 1e6 * f["training"]
|
|
300
|
+
kg_high = t_eff / 1e6 * f["footprint_high"] + billed / 1e6 * f["training"]
|
|
301
|
+
return dict(
|
|
302
|
+
kg_co2e=kg, kg_co2e_high_case=kg_high, development_line_kg_co2e=t_eff / 1e6 * f["development"],
|
|
303
|
+
electricity_kg_co2e=t_eff / 1e6 * f["electricity"], embodied_kg_co2e=t_eff / 1e6 * f["embodied"],
|
|
304
|
+
construction_kg_co2e=t_eff / 1e6 * f["construction"], training_kg_co2e=billed / 1e6 * f["training"],
|
|
305
|
+
model=model, matched_pattern=matched, model_class=cl, class_basis=basis, own_factor_model_id=own,
|
|
306
|
+
is_default_fallback=bool(model is not None and mm["is_default_fallback"]),
|
|
307
|
+
region_id=reg["region_id"], grid_id=reg["grid_id"], grid_kg_co2e_per_kwh=reg["grid_kg_co2e_per_kwh"],
|
|
308
|
+
region_resolution=reg["how"], billed_tokens=billed, effective_tokens=t_eff, factors=f,
|
|
309
|
+
warnings=warnings, provenance=p, _reg=reg,
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def water(t_eff, model_class, provider=None, region=None):
|
|
314
|
+
"""Water for an effective-token count under both hydropower conventions, or available=False."""
|
|
315
|
+
warnings, p = [], []
|
|
316
|
+
reg = resolve_region(provider, region)
|
|
317
|
+
warnings += reg["warnings"]
|
|
318
|
+
rid = reg["region_id"]
|
|
319
|
+
wf = {r["region_id"]: r for r in read("region_water_factors.csv")}
|
|
320
|
+
if reg["how"].startswith("unknown") or rid not in wf:
|
|
321
|
+
warnings.append(
|
|
322
|
+
f"no water factor for region {rid!r}: region_water_factors.csv covers {len(wf)} regions only "
|
|
323
|
+
f"and has no unknown-region fallback. Disclose water as not available"
|
|
324
|
+
)
|
|
325
|
+
return dict(available=False, region_id=rid, warnings=warnings, provenance=p)
|
|
326
|
+
w = wf[rid]
|
|
327
|
+
fl = next((r for r in read("factors_v3_lifecycle.csv") if r["model_class"] == model_class and r["gpu"] == "H100" and r["region_id"] == rid), None)
|
|
328
|
+
if fl is None:
|
|
329
|
+
raise SaefError(f"no factors_v3_lifecycle.csv row for class {model_class} / H100 / {rid}")
|
|
330
|
+
fac, srv = float(fl["facility_wh_per_1k_effective_tokens"]), float(fl["server_wh_per_1k_effective_tokens"])
|
|
331
|
+
prov(p, "facility Wh per 1,000 effective tokens", fl, "facility_wh_per_1k_effective_tokens")
|
|
332
|
+
prov(p, "server Wh per 1,000 effective tokens", fl, "server_wh_per_1k_effective_tokens")
|
|
333
|
+
k = t_eff / 1000.0
|
|
334
|
+
base = srv if w["wue_denominator"].startswith("IT load") else fac
|
|
335
|
+
onsite = base * float(w["wue_l_per_kwh"])
|
|
336
|
+
if w["wue_basis_as_published"] == "withdrawal":
|
|
337
|
+
onsite *= float(w["withdrawal_to_consumption"])
|
|
338
|
+
prov(p, "on-site WUE", w, "wue_l_per_kwh")
|
|
339
|
+
out = dict(available=True, region_id=rid, ml_onsite=onsite * k, ml_offsite_reig=None, ml_offsite_excl_hydro=None,
|
|
340
|
+
ml_total_reig=None, ml_total_excl_hydro=None, warnings=warnings, provenance=p)
|
|
341
|
+
if not w["ewif_l_per_kwh"]:
|
|
342
|
+
warnings.append(f"no off-site water factor for {rid}: {w['ewif_source']}. Only the on-site term is reported")
|
|
343
|
+
else:
|
|
344
|
+
off, off_x = fac * float(w["ewif_l_per_kwh"]), fac * float(w["ewif_excl_hydro_l_per_kwh"])
|
|
345
|
+
prov(p, "off-site EWIF (hydropower allocated)", w, "ewif_l_per_kwh")
|
|
346
|
+
prov(p, "off-site EWIF excluding hydropower", w, "ewif_excl_hydro_l_per_kwh")
|
|
347
|
+
out.update(ml_offsite_reig=off * k, ml_offsite_excl_hydro=off_x * k,
|
|
348
|
+
ml_total_reig=(onsite + off) * k, ml_total_excl_hydro=(onsite + off_x) * k)
|
|
349
|
+
warnings.append("two hydropower conventions are reported and neither is preferred: 'reig' allocates reservoir evaporation to electricity, 'excl_hydro' excludes it")
|
|
350
|
+
return out
|
saef/_core.py
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
from dataclasses import dataclass, field
|
|
2
|
+
from typing import Optional
|
|
3
|
+
|
|
4
|
+
from . import _calc
|
|
5
|
+
from ._calc import SaefError
|
|
6
|
+
|
|
7
|
+
DATASET_VERSION = "3.0.0"
|
|
8
|
+
|
|
9
|
+
BIBTEX = """@misc{llopis2026somafactors,
|
|
10
|
+
author = {Llopis-Garcia, Guillermo},
|
|
11
|
+
title = {{SOMA AI Emission Factors (SAEF)}},
|
|
12
|
+
year = {2026},
|
|
13
|
+
publisher = {Zenodo},
|
|
14
|
+
version = {v3.0.0},
|
|
15
|
+
doi = {10.5281/zenodo.20443585},
|
|
16
|
+
url = {https://doi.org/10.5281/zenodo.20443585}
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
@misc{llopis2026accounting,
|
|
20
|
+
author = {Llopis-Garcia, Guillermo},
|
|
21
|
+
title = {Accounting for Purchased Artificial Intelligence Inference in Corporate Greenhouse Gas Inventories: A Token-Based Method},
|
|
22
|
+
year = {2026},
|
|
23
|
+
eprint = {2606.10660},
|
|
24
|
+
archivePrefix = {arXiv},
|
|
25
|
+
note = {Accepted for publication in Sustainable Production and Consumption (Elsevier)}
|
|
26
|
+
}
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def regions(provider=None):
|
|
31
|
+
"""Cloud region ids (AWS, Azure, Google Cloud), sorted. Pass provider='aws'|'azure'|'gcp' to filter."""
|
|
32
|
+
rows = _calc.read("cloud_region_factors.csv")
|
|
33
|
+
if provider:
|
|
34
|
+
rows = [r for r in rows if r["provider"].lower() == provider.strip().lower()]
|
|
35
|
+
return sorted({r["region_id"] for r in rows})
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def grids():
|
|
39
|
+
"""Grid ids usable as a region: ISO-3 country codes, eGRID subregions, EU27, WORLD and one subnational row."""
|
|
40
|
+
return sorted(r["grid_id"] for r in _calc.read("grid_intensity_all.csv"))
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def model_class_for(model):
|
|
44
|
+
"""Map a model identifier such as 'gpt-4o' to its class (A, B or C) via model_class_mapping.csv.
|
|
45
|
+
|
|
46
|
+
An identifier that matches no pattern is assigned the conservative class C, as the dataset specifies."""
|
|
47
|
+
m = _calc.map_model(model)
|
|
48
|
+
if m["out_of_scope"]:
|
|
49
|
+
raise SaefError(f"{model!r} is out of scope (embeddings, image, audio, video or moderation)")
|
|
50
|
+
return m["model_class"]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def factor(model_class="B", region="us-east-1", provider=None):
|
|
54
|
+
"""Class factor at one region, H100 central case.
|
|
55
|
+
|
|
56
|
+
kg_co2e_per_1m_billed_tokens is the headline for a billed total with the default input share.
|
|
57
|
+
terms are kg CO2e per million EFFECTIVE tokens (electricity, embodied, construction), plus training per million billed tokens."""
|
|
58
|
+
cl = _calc.emissions(model_class=model_class, provider=provider, region=region, billed_tokens=1e6)
|
|
59
|
+
f = cl["factors"]
|
|
60
|
+
return {
|
|
61
|
+
"model_class": cl["model_class"],
|
|
62
|
+
"region_id": cl["region_id"],
|
|
63
|
+
"grid_id": cl["grid_id"],
|
|
64
|
+
"grid_kg_co2e_per_kwh": cl["grid_kg_co2e_per_kwh"],
|
|
65
|
+
"kg_co2e_per_1m_billed_tokens": f["per_billed"],
|
|
66
|
+
"kg_co2e_per_1m_effective_tokens": f["footprint"],
|
|
67
|
+
"kg_co2e_per_1m_effective_tokens_high_case": f["footprint_high"],
|
|
68
|
+
"terms": {
|
|
69
|
+
"electricity": f["electricity"],
|
|
70
|
+
"embodied": f["embodied"],
|
|
71
|
+
"construction": f["construction"],
|
|
72
|
+
"training_per_1m_billed_tokens": f["training"],
|
|
73
|
+
},
|
|
74
|
+
"effective_per_billed_tokens": _calc.effective_from_billed(1.0),
|
|
75
|
+
"version": DATASET_VERSION,
|
|
76
|
+
"warnings": cl["warnings"],
|
|
77
|
+
"provenance": cl["provenance"],
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@dataclass(frozen=True)
|
|
82
|
+
class Estimate:
|
|
83
|
+
kg_co2e: float
|
|
84
|
+
kg_co2e_high_case: float
|
|
85
|
+
development_line_kg_co2e: float
|
|
86
|
+
terms_kg_co2e: dict
|
|
87
|
+
water_ml: Optional[float]
|
|
88
|
+
water_ml_excl_hydro: Optional[float]
|
|
89
|
+
model: Optional[str]
|
|
90
|
+
model_class: str
|
|
91
|
+
class_basis: str
|
|
92
|
+
region_id: str
|
|
93
|
+
grid_kg_co2e_per_kwh: float
|
|
94
|
+
billed_tokens: float
|
|
95
|
+
effective_tokens: float
|
|
96
|
+
warnings: list = field(repr=False)
|
|
97
|
+
provenance: list = field(repr=False)
|
|
98
|
+
water: dict = field(repr=False)
|
|
99
|
+
version: str = DATASET_VERSION
|
|
100
|
+
note: str = "Estimate, not a measurement. The high case is a conservative bound; the development line is reported separately and is not part of kg_co2e."
|
|
101
|
+
|
|
102
|
+
@property
|
|
103
|
+
def sources(self):
|
|
104
|
+
return self.provenance
|
|
105
|
+
|
|
106
|
+
def to_dict(self):
|
|
107
|
+
return {k: getattr(self, k) for k in self.__dataclass_fields__}
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def estimate(
|
|
111
|
+
tokens=None,
|
|
112
|
+
model=None,
|
|
113
|
+
model_class=None,
|
|
114
|
+
region=None,
|
|
115
|
+
provider=None,
|
|
116
|
+
output_tokens=None,
|
|
117
|
+
input_tokens=0.0,
|
|
118
|
+
cached_input_tokens=0.0,
|
|
119
|
+
):
|
|
120
|
+
"""Estimate kg CO2e (and water in mL where the region has a water factor) for AI inference.
|
|
121
|
+
|
|
122
|
+
Pass tokens, the BILLED total (input plus output), or pass output_tokens with input_tokens and
|
|
123
|
+
cached_input_tokens for a billing-export split. Pass model or model_class. region may be a cloud
|
|
124
|
+
region id, an ISO-3 country code, an eGRID subregion, 'eu-27' or None for the global average.
|
|
125
|
+
Every number is traced in provenance by file, line and column.
|
|
126
|
+
"""
|
|
127
|
+
if (tokens is None) == (output_tokens is None):
|
|
128
|
+
raise SaefError("Pass either tokens (billed total) or output_tokens (with input_tokens)")
|
|
129
|
+
given = tokens if tokens is not None else output_tokens
|
|
130
|
+
if given < 0 or input_tokens < 0 or cached_input_tokens < 0:
|
|
131
|
+
raise SaefError("token counts must be >= 0")
|
|
132
|
+
r = _calc.emissions(
|
|
133
|
+
model=model, model_class=model_class, provider=provider, region=region,
|
|
134
|
+
billed_tokens=tokens, output_tokens=output_tokens or 0.0,
|
|
135
|
+
input_tokens=input_tokens, cached_input_tokens=cached_input_tokens,
|
|
136
|
+
)
|
|
137
|
+
w = _calc.water(r["effective_tokens"], r["model_class"], provider, region)
|
|
138
|
+
return Estimate(
|
|
139
|
+
kg_co2e=r["kg_co2e"],
|
|
140
|
+
kg_co2e_high_case=r["kg_co2e_high_case"],
|
|
141
|
+
development_line_kg_co2e=r["development_line_kg_co2e"],
|
|
142
|
+
terms_kg_co2e={
|
|
143
|
+
"electricity": r["electricity_kg_co2e"],
|
|
144
|
+
"embodied": r["embodied_kg_co2e"],
|
|
145
|
+
"construction": r["construction_kg_co2e"],
|
|
146
|
+
"training": r["training_kg_co2e"],
|
|
147
|
+
},
|
|
148
|
+
water_ml=w["ml_total_reig"] if w["available"] else None,
|
|
149
|
+
water_ml_excl_hydro=w["ml_total_excl_hydro"] if w["available"] else None,
|
|
150
|
+
model=model,
|
|
151
|
+
model_class=r["model_class"],
|
|
152
|
+
class_basis=r["class_basis"],
|
|
153
|
+
region_id=r["region_id"],
|
|
154
|
+
grid_kg_co2e_per_kwh=r["grid_kg_co2e_per_kwh"],
|
|
155
|
+
billed_tokens=r["billed_tokens"],
|
|
156
|
+
effective_tokens=r["effective_tokens"],
|
|
157
|
+
warnings=list(dict.fromkeys(r["warnings"] + w["warnings"])),
|
|
158
|
+
provenance=r["provenance"] + w["provenance"],
|
|
159
|
+
water=w,
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def citation():
|
|
164
|
+
"""BibTeX for the dataset (Zenodo concept DOI 10.5281/zenodo.20443585) and the method paper."""
|
|
165
|
+
return BIBTEX
|
saef/cli.py
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import argparse
|
|
2
|
+
import json
|
|
3
|
+
|
|
4
|
+
from . import __version__, citation, estimate, factor, regions
|
|
5
|
+
from ._core import SaefError
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def _print_estimate(e):
|
|
9
|
+
print(f"SAEF {e.version} model={e.model or '-'} class={e.model_class} ({e.class_basis}) region={e.region_id} grid={e.grid_kg_co2e_per_kwh:g} kg/kWh")
|
|
10
|
+
print(f"billed tokens: {e.billed_tokens:,.0f} effective tokens: {e.effective_tokens:,.0f}")
|
|
11
|
+
print(f"kg CO2e: {e.kg_co2e:.6g} (conservative high case {e.kg_co2e_high_case:.6g}; development line {e.development_line_kg_co2e:.6g}, reported separately)")
|
|
12
|
+
for term, value in e.terms_kg_co2e.items():
|
|
13
|
+
print(f" {term}: {value:.6g} kg")
|
|
14
|
+
if e.water_ml is None:
|
|
15
|
+
print("water: not available for this region")
|
|
16
|
+
else:
|
|
17
|
+
print(f"water mL: {e.water_ml:.6g} (hydropower allocated), {e.water_ml_excl_hydro:.6g} (excluding hydropower)")
|
|
18
|
+
for w in e.warnings:
|
|
19
|
+
print(f"warning: {w}")
|
|
20
|
+
print("sources (file:line, column):")
|
|
21
|
+
for s in e.provenance:
|
|
22
|
+
print(f" {s['quantity']}: {s['file']}:{s['line']} {s['column']} = {s['value']}")
|
|
23
|
+
print(e.note)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def main(argv=None):
|
|
27
|
+
p = argparse.ArgumentParser(prog="saef", description="SOMA AI Emission Factors (estimates, not measurements)")
|
|
28
|
+
p.add_argument("--version", action="version", version=f"saef {__version__}")
|
|
29
|
+
sub = p.add_subparsers(dest="cmd", required=True)
|
|
30
|
+
|
|
31
|
+
e = sub.add_parser("estimate", help="estimate kg CO2e and water for a token count")
|
|
32
|
+
e.add_argument("--tokens", type=float, help="billed total (input plus output)")
|
|
33
|
+
e.add_argument("--output-tokens", type=float, help="output tokens, with --input-tokens")
|
|
34
|
+
e.add_argument("--input-tokens", type=float, default=0.0)
|
|
35
|
+
e.add_argument("--cached-input-tokens", type=float, default=0.0)
|
|
36
|
+
g = e.add_mutually_exclusive_group(required=True)
|
|
37
|
+
g.add_argument("--model")
|
|
38
|
+
g.add_argument("--model-class", dest="model_class")
|
|
39
|
+
e.add_argument("--region", default=None, help="cloud region id, ISO-3 country, eGRID subregion, eu-27; default global average")
|
|
40
|
+
e.add_argument("--provider", default=None)
|
|
41
|
+
e.add_argument("--json", action="store_true")
|
|
42
|
+
|
|
43
|
+
f = sub.add_parser("factor", help="show the class factor at a region")
|
|
44
|
+
f.add_argument("--model-class", dest="model_class", default="B")
|
|
45
|
+
f.add_argument("--region", default="us-east-1")
|
|
46
|
+
f.add_argument("--provider", default=None)
|
|
47
|
+
|
|
48
|
+
r = sub.add_parser("regions", help="list cloud region ids")
|
|
49
|
+
r.add_argument("--provider", default=None)
|
|
50
|
+
sub.add_parser("cite", help="print BibTeX")
|
|
51
|
+
|
|
52
|
+
args = p.parse_args(argv)
|
|
53
|
+
try:
|
|
54
|
+
if args.cmd == "estimate":
|
|
55
|
+
res = estimate(
|
|
56
|
+
tokens=args.tokens, model=args.model, model_class=args.model_class, region=args.region,
|
|
57
|
+
provider=args.provider, output_tokens=args.output_tokens, input_tokens=args.input_tokens,
|
|
58
|
+
cached_input_tokens=args.cached_input_tokens,
|
|
59
|
+
)
|
|
60
|
+
if args.json:
|
|
61
|
+
print(json.dumps(res.to_dict(), indent=2))
|
|
62
|
+
else:
|
|
63
|
+
_print_estimate(res)
|
|
64
|
+
elif args.cmd == "factor":
|
|
65
|
+
print(json.dumps(factor(args.model_class, args.region, args.provider), indent=2))
|
|
66
|
+
elif args.cmd == "regions":
|
|
67
|
+
print("\n".join(regions(args.provider)))
|
|
68
|
+
else:
|
|
69
|
+
print(citation())
|
|
70
|
+
except SaefError as err:
|
|
71
|
+
print(f"saef: error: {err}")
|
|
72
|
+
return 2
|
|
73
|
+
return 0
|