@hestia-earth/engine-models 0.81.6 → 0.82.1

package/formulas/README.md

@@ -0,0 +1,213 @@
+# 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.
+
+`index.json` is generated by `scripts/generate-formulas.js` (run as part of
+`npm run build:models`). Do not edit it by hand — edit the model's `.md`
+documentation instead (see [Authoring bindings](#authoring-bindings)).
+
+## Contents
+
+`index.json` holds every formula, keyed by the same `docPath` used in
+`model-links.json`: `{ [docPath]: IFormula[] }`. It is the single file 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;       // a column of a packed table (per-row under a \sum, or with `match`)
+  match?: string;        // row selection: the row whose id starts with this, read `column`
+  constant?: string;     // a fixed constant (not logged), substituted as-is
+}
+
+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. `[const]`
+```
+
+- 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`).
+- **Every symbol in the `Where:` list must be annotated.** Tag display-only
+  constants (conversion factors, physical constants, e.g. `55.65`, `\frac{17}{14}`)
+  with `` `[const]` ``: they render as-is and are excluded from coverage. An
+  untagged, unbound symbol is treated as a *genuine missing binding*, not a
+  constant — this is what lets the coverage report tell the two apart.
+- Tag a **named** constant with `` `[const:<value>]` `` (e.g. `ER` → `` `[const:2]` ``):
+  it substitutes to the literal value (rather than rendering as-is) without being
+  logged, and is excluded from coverage.
+
+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]`
+```
+
+When a symbol is a single value living in a specific row of a packed table (not a
+`\sum`), select the row with `` `[<table key>@<id prefix>:<column>]` `` — the row
+whose id (first column) starts with `<id prefix>`, reading `<column>`:
+
+```markdown
+$$N_2O_{indirect} = [(NH_3\text{-}N + NO_x\text{-}N) \times EF_4] \times \frac{44}{28}$$
+
+Where:
+
+- $N_2O_{indirect}$ = indirect N<sub>2</sub>O emission `[value]`
+- $NH_3\text{-}N$ = nitrogen volatilised as ammonia (kg N) `[values@nh3:emission-value]`
+- $NO_x\text{-}N$ = nitrogen volatilised as nitrogen oxides (kg N) `[values@nox:emission-value]`
+- $EF_4$ = emission factor for deposition of volatilised N `[values@nh3:ef4-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.