@hestia-earth/engine-models 0.81.5 → 0.82.0

package/formulas/README.md

@@ -0,0 +1,190 @@
+# Model formulas
+
+This folder contains the KaTeX formulas extracted from each model's
+documentation, together with the **bindings** that tie every symbol in a formula
+to a value logged at runtime (the "jlog"). With these you can render a model's
+formula and *substitute* its symbols with the actual values from a given
+execution — so a user can see exactly where a result came from.
+
+The files here are generated by `scripts/generate-formulas.js` (run as part of
+`npm run build:models`). Do not edit them by hand — edit the model's `.md`
+documentation instead (see [Authoring bindings](#authoring-bindings)).
+
+## Contents
+
+| File | Description |
+| --- | --- |
+| `<model>/<term>.json` | One file per documentation page that contains at least one formula. |
+| `index.json` | Aggregate of every formula, keyed by `docPath`. This is what the package imports. |
+
+## Data shape
+
+```ts
+interface IFormulaBinding {
+  symbol: string;        // the KaTeX symbol as written, e.g. "E_{CH4}", "GE"
+  description?: string;  // the "Where:" list description text
+  key?: string;          // the jlog field this symbol resolves to (absent for constants)
+  column?: string;       // for a \sum: the column to read per row of a packed table
+}
+
+interface IFormula {
+  formula: string;           // KaTeX source, without the `$$` delimiters
+  bindings: IFormulaBinding[];
+}
+```
+
+`key` is special-cased: `"value"` is the **result** (the left-hand side of the
+equation), and any other key is a field to read from the model's jlog entry. A
+binding with no `key` is a display-only constant (e.g. `55.65`).
+
+When a symbol sits under a `\sum` and its value comes from a per-input **table**
+(a packed `log_as_table` string), the binding also carries a `column`: `key` is
+the table's log key and `column` is the field to read from each row.
+
+## Getting the formulas for a model
+
+The package exposes two helpers (re-exported from the package root):
+
+```ts
+import { getFormulas, getFormulasForLink } from '@hestia-earth/engine-models';
+
+// By the same parameters used to look up a model in model-links.json:
+getFormulas({ model: 'ipcc2019', term: 'ch4ToAirEntericFermentation' });
+// => [ { formula: 'E_{CH4} = (GE \\times Y_m) / 55.65', bindings: [...] } ]
+
+getFormulas({ model: 'ipcc2019', modelKey: 'pastureGrass' });
+// => [ ...20 formulas... ]
+
+// Or, if you already have a model-links entry (an IModel):
+import { findMatchingModel } from '@hestia-earth/engine-models';
+const link = findMatchingModel({ model: 'ipcc2019', term: 'ch4ToAirEntericFermentation' });
+getFormulasForLink(link);
+```
+
+Both always return an **array** (a documentation page may define several
+formulas), and an **empty array** when the model is unknown or has no formulas.
+
+## Rendering & substituting
+
+`renderFormula(formula, values)` turns one `IFormula` plus a map of values into
+three KaTeX strings (without the `$$` delimiters):
+
+- **symbolic** — the formula as authored (`E_{CH4} = (GE \times Y_m) / 55.65`)
+- **substituted** — symbols replaced by their values (`59.24 = (52340 \times 0.063) / 55.65`)
+- **annotated** — symbols kept, each wrapped in `\htmlData{key=..., value=...}{symbol}`
+  so the DOM node carries `data-key` / `data-value` for a tooltip or toggle
+
+It only substitutes *declared* symbols (longest-first), so `\times`, subscripts
+and constants are never touched, and a symbol with no value is left symbolic.
+
+```ts
+import { getFormulas, renderFormula } from '@hestia-earth/engine-models';
+
+const [formula] = getFormulas({ model: 'ipcc2019', term: 'ch4ToAirEntericFermentation' });
+
+// `values` maps each binding key to its value for ONE execution. You supply it,
+// so you decide where each value comes from (see "Where the values come from").
+const values = { value: 59.24, total_feed_in_MJ: 52340, enteric_factor: 0.063 };
+
+const { symbolic, substituted, annotated } = renderFormula(formula, values);
+```
+
+### Where the values come from
+
+`renderFormula` is agnostic — it just reads `values[key]` for each binding. The
+values for one execution come from that model's **jlog** entry (the fields logged
+via `debugValues` / `logRequirements`, keyed exactly as in the bindings). The
+result symbol (`key: "value"`) is a special case: an emission's numeric value may
+be logged, or read from the recalculated node it belongs to — supply whichever
+your platform has. A minimal join over a jlog node's `logs[]`:
+
+```ts
+const values = Object.assign({}, ...(jlogNode.logs || []));
+// then set values.value from the node's result if it isn't logged:
+values.value ??= recalculatedEmission?.value;
+```
+
+### Expanding a `\sum`
+
+When a formula sums over inputs (`CO_2 = \sum_i M_{urea,i} \times EF_i`) and its
+summand symbols are bound to table columns, `renderFormula` expands the sum once
+per row — provided `values[<table key>]` holds the packed `log_as_table` string
+(or an array of row objects). Each row's columns fill the summand:
+
+```ts
+const [formula] = getFormulas({ model: 'ipcc2019', term: 'co2ToAirUreaHydrolysis' });
+const { substituted } = renderFormula(formula, {
+  value: 24.4,
+  urea_values: 'id:urea_value:100_factor:0.2;id:ureaKgN_value:50_factor:0.088'
+});
+// 24.4 = (100 \times 0.2) + (50 \times 0.088)
+```
+
+Without the table string the `\sum` is left symbolic.
+
+### Rendering with KaTeX
+
+`\htmlData` is **disabled by default** — opt in with a narrowly-scoped `trust`
+callback:
+
+```ts
+import katex from 'katex';
+import 'katex/dist/katex.min.css';
+
+katex.render(substituted, element, {
+  displayMode: true,
+  trust: (ctx) => ctx.command === '\\htmlData',
+  strict: false,
+});
+```
+
+Because every substituted symbol is a real DOM node carrying `data-key` /
+`data-value`, the symbol ↔ value toggle and hover tooltips are pure DOM — no
+re-render required:
+
+```ts
+element.querySelectorAll('[data-key]').forEach((span) => {
+  const el = span as HTMLElement;
+  el.title = `${el.dataset.key} = ${el.dataset.value}`;
+});
+```
+
+## Authoring bindings
+
+Bindings live in the model's `.md` documentation. Add a backticked `` `[logkey]` ``
+token to each symbol in the "Where:" list that follows a formula:
+
+```markdown
+$$E_{CH4} = (GE \times Y_m) / 55.65$$
+
+Where:
+
+- $E_{CH4}$ = Methane emissions (in kg $CH_4$) `[value]`
+- $GE$ = Gross Energy intake (in MJ). `[total_feed_in_MJ]`
+- $Y_m$ = Methane conversion factor. `[enteric_factor]`
+- $55.65$ = The energy content of methane.   <!-- constant, no binding -->
+```
+
+- Bind the result (left-hand side) to `` `[value]` ``.
+- Bind every other symbol to the jlog field it corresponds to — the `key` passed
+  to `debugValues` / `logRequirements` in the model's `.py` (e.g. `enteric_factor`).
+- Leave constants unbound; they render as-is.
+
+For a `\sum` over inputs, bind each summand symbol to a **table column** with
+`` `[<table key>:<column>]` `` — the log key of the packed `log_as_table` value
+and the per-row field:
+
+```markdown
+$$CO_2 = \sum_i M_{urea,i} \times EF_i$$
+
+Where:
+
+- $CO_2$ = carbon dioxide emission from urea hydrolysis (kg) `[value]`
+- $M_{urea,i}$ = mass of each urea fertiliser applied (kg) `[urea_values:value]`
+- $EF_i$ = product-specific CO<sub>2</sub> emission factor `[urea_values:factor]`
+```
+
+`scripts/validate-documentation.js` validates these on every build: it errors if a
+bound symbol is not in the formula or a symbol is bound twice. It warns (without
+failing) when there is no `` `[value]` `` result, several results, or a key is not
+found in the sibling `.py` — a hint that the value is logged via a shared util.

package/formulas/deRuijterEtAl2010/nh3ToAirCropResidueDecomposition.json

@@ -0,0 +1,30 @@
+{
+  "docPath": "hestia_earth/models/deRuijterEtAl2010/nh3ToAirCropResidueDecomposition.md",
+  "formulas": [
+    {
+      "formula": "NH_3 = a \\times N_{AG} \\times \\frac{17}{14}",
+      "bindings": [
+        {
+          "symbol": "N_{AG}",
+          "description": "is the total nitrogen in crop residue in kg."
+        }
+      ]
+    },
+    {
+      "formula": "a = (0.38 \\times N_{AG} \\times \\frac{1000}{AG_{DM}} - 5.44) / 100",
+      "bindings": [
+        {
+          "symbol": "0 \\le a < 17\\%"
+        },
+        {
+          "symbol": "N_{AG}",
+          "description": "is the total nitrogen in crop residue in kg."
+        },
+        {
+          "symbol": "AG_{DM}",
+          "description": "is the above ground crop residue dry matter in kg, considering the quantity left on field or incorporated only."
+        }
+      ]
+    }
+  ]
+}

package/formulas/emepEea2019/co2ToAirFuelCombustion.json

@@ -0,0 +1,23 @@
+{
+  "docPath": "hestia_earth/models/emepEea2019/co2ToAirFuelCombustion.md",
+  "formulas": [
+    {
+      "formula": "CO_2 = \\sum_i M_{fuel,i} \\times EF_i",
+      "bindings": [
+        {
+          "symbol": "CO_2",
+          "description": "total carbon dioxide emission from fuel combustion (kg)",
+          "key": "value"
+        },
+        {
+          "symbol": "M_{fuel,i}",
+          "description": "mass of each fuel input $i$ (kg)"
+        },
+        {
+          "symbol": "EF_i",
+          "description": "CO<sub>2</sub> emission factor for fuel input $i$"
+        }
+      ]
+    }
+  ]
+}

package/formulas/emepEea2019/nh3ToAirExcreta.json

@@ -0,0 +1,27 @@
+{
+  "docPath": "hestia_earth/models/emepEea2019/nh3ToAirExcreta.md",
+  "formulas": [
+    {
+      "formula": "NH_3 = TAN \\times EF_{NH_3} \\times \\frac{17}{14}",
+      "bindings": [
+        {
+          "symbol": "NH_3",
+          "description": "ammonia emission from excreta (kg NH<sub>3</sub>)",
+          "key": "value"
+        },
+        {
+          "symbol": "TAN",
+          "description": "total ammoniacal nitrogen in excreta (kg N)"
+        },
+        {
+          "symbol": "EF_{NH_3}",
+          "description": "management-specific NH<sub>3</sub> emission factor"
+        },
+        {
+          "symbol": "\\frac{17}{14}",
+          "description": "conversion of NH<sub>3</sub>-N to NH<sub>3</sub>"
+        }
+      ]
+    }
+  ]
+}

package/formulas/emepEea2019/pm10ToAirAnimalHousing.json

@@ -0,0 +1,28 @@
+{
+  "docPath": "hestia_earth/models/emepEea2019/pm10ToAirAnimalHousing.md",
+  "formulas": [
+    {
+      "formula": "PM = N_{animals} \\times EF_{PM} \\times t_{housing}",
+      "bindings": [
+        {
+          "symbol": "PM",
+          "description": "particulate matter (PM<sub>10</sub>) emission from animal housing (kg)",
+          "key": "value"
+        },
+        {
+          "symbol": "N_{animals}",
+          "description": "average animal population"
+        },
+        {
+          "symbol": "EF_{PM}",
+          "description": "animal-type-specific emission factor (from `pm10ToAirEea2019`)"
+        },
+        {
+          "symbol": "t_{housing}",
+          "description": "total housing duration (days)",
+          "key": "number_of_days_in_animal_housing"
+        }
+      ]
+    }
+  ]
+}

package/formulas/emepEea2019/pm25ToAirAnimalHousing.json

@@ -0,0 +1,28 @@
+{
+  "docPath": "hestia_earth/models/emepEea2019/pm25ToAirAnimalHousing.md",
+  "formulas": [
+    {
+      "formula": "PM = N_{animals} \\times EF_{PM} \\times t_{housing}",
+      "bindings": [
+        {
+          "symbol": "PM",
+          "description": "particulate matter (PM<sub>2.5</sub>) emission from animal housing (kg)",
+          "key": "value"
+        },
+        {
+          "symbol": "N_{animals}",
+          "description": "average animal population"
+        },
+        {
+          "symbol": "EF_{PM}",
+          "description": "animal-type-specific emission factor (from `pm25ToAirEea2019`)"
+        },
+        {
+          "symbol": "t_{housing}",
+          "description": "total housing duration (days)",
+          "key": "number_of_days_in_animal_housing"
+        }
+      ]
+    }
+  ]
+}

package/formulas/emepEea2019/tspToAirAnimalHousing.json

@@ -0,0 +1,28 @@
+{
+  "docPath": "hestia_earth/models/emepEea2019/tspToAirAnimalHousing.md",
+  "formulas": [
+    {
+      "formula": "PM = N_{animals} \\times EF_{PM} \\times t_{housing}",
+      "bindings": [
+        {
+          "symbol": "PM",
+          "description": "total suspended particulate (TSP) emission from animal housing (kg)",
+          "key": "value"
+        },
+        {
+          "symbol": "N_{animals}",
+          "description": "average animal population"
+        },
+        {
+          "symbol": "EF_{PM}",
+          "description": "animal-type-specific emission factor (from `tspToAirEea2019`)"
+        },
+        {
+          "symbol": "t_{housing}",
+          "description": "total housing duration (days)",
+          "key": "number_of_days_in_animal_housing"
+        }
+      ]
+    }
+  ]
+}

package/formulas/hestia/feedConversionRatio/feedConversionRatioCarbon.json

@@ -0,0 +1,23 @@
+{
+  "docPath": "hestia_earth/models/hestia/feedConversionRatio/feedConversionRatioCarbon.md",
+  "formulas": [
+    {
+      "formula": "FCR_C = \\frac{\\sum C_{feed}}{C_{product}}",
+      "bindings": [
+        {
+          "symbol": "FCR_C",
+          "description": "carbon-based feed conversion ratio",
+          "key": "value"
+        },
+        {
+          "symbol": "\\sum C_{feed}",
+          "description": "total carbon in feed intake"
+        },
+        {
+          "symbol": "C_{product}",
+          "description": "carbon in animal product output"
+        }
+      ]
+    }
+  ]
+}