@hestia-earth/engine-models 0.82.0 → 0.82.2

package/cjs/formulas.d.ts

@@ -19,11 +19,24 @@ export interface IFormulaBinding {
      */
     key?: string;
     /**
-     * For a per-row value inside a packed `log_as_table` string: the column to
-     * read from each row. When set, the symbol sits under a `\sum` and is expanded
-     * once per row (e.g. `\sum_i M_i \times EF_i` → `(32 × 0.166) + (13 × 0.495)`).
+     * A value inside a packed `log_as_table` string: the column to read.
+     * - with no `match`, the symbol sits under a `\sum` and is expanded once per
+     *   row (e.g. `\sum_i M_i \times EF_i` → `(32 × 0.166) + (13 × 0.495)`);
+     * - with `match`, it resolves to a single row (row selection, see `match`).
      */
     column?: string;
+    /**
+     * Row selection: pick the one row of the `key` table whose id (first column)
+     * starts with this value, then read `column` from it. Resolves to a single
+     * value, e.g. `NH_3\text{-}N` → the `emission-value` of the row `nh3…`.
+     */
+    match?: string;
+    /**
+     * A fixed constant (not logged): the symbol always substitutes to this literal
+     * (e.g. `ER` → `2`) and is excluded from coverage. Empty string marks a
+     * constant with no display value.
+     */
+    constant?: string;
 }
 /**
  * A KaTeX formula extracted from a model's documentation, with the bindings

package/cjs/formulas.js

@@ -92,8 +92,9 @@ var formatValue = function (value) {
         return round4(value);
     return formatNumericString(String(value));
 };
-// `\sum` with an optional index subscript (`_i`, `_{i}`, ...) and trailing space.
-var SUM_RE = /\\sum(?:_\{[^}]*\}|_[^\s{])?\s*/;
+// `\sum` with an optional index subscript (`_i`, `_{s=1}`, ...) and upper bound
+// superscript (`^S`, `^{S}`), and trailing space.
+var SUM_RE = /\\sum(?:_\{[^}]*\}|_[^\s{])?(?:\^\{[^}]*\}|\^[^\s{])?\s*/;
 // Parse a packed `log_as_table` string into rows: rows split on `;`, columns on
 // `_`, each column a `key:value` pair (values never contain `_` or `:`).
 var parseTable = function (packed) {
@@ -122,35 +123,63 @@ var parseTable = function (packed) {
  * (or an array of row objects). Without the table it stays symbolic.
  */
 var renderFormula = function (formula, values) {
-    var _a;
-    var columnBindings = formula.bindings.filter(function (b) { return b.key && b.column; });
-    var scalarBindings = formula.bindings.filter(function (b) { return b.key && !b.column; });
-    var sumMatch = columnBindings.length ? SUM_RE.exec(formula.formula) : null;
-    var tableKey = (_a = columnBindings[0]) === null || _a === void 0 ? void 0 : _a.key;
-    var raw = values[tableKey];
-    var rows = !sumMatch
-        ? null
-        : Array.isArray(raw)
-            ? raw
-            : typeof raw === 'string'
-                ? parseTable(raw)
-                : null;
+    // sum: a per-row column under a \sum. point: a single value — a scalar, a row
+    // selection (`match` + `column`), or a fixed constant.
+    var sumBindings = formula.bindings.filter(function (b) { return b.key && b.column && !b.match; });
+    var pointBindings = formula.bindings.filter(function (b) { return (b.key && !(b.column && !b.match)) || b.constant; });
+    var toRows = function (source) {
+        return Array.isArray(source)
+            ? source
+            : typeof source === 'string'
+                ? parseTable(source)
+                : [];
+    };
+    var sumMatch = sumBindings.length ? SUM_RE.exec(formula.formula) : null;
+    // The summand may draw from several parallel tables (e.g. one for values, one
+    // for factors); parse each once and align them by row index.
+    var tableRows = {};
+    if (sumMatch) {
+        sumBindings.forEach(function (b) {
+            var key = b.key;
+            if (!(key in tableRows))
+                tableRows[key] = toRows(values[key]);
+        });
+    }
+    var rowCount = sumMatch
+        ? Math.max.apply(Math, __spreadArray([0], __read(sumBindings.map(function (b) { return tableRows[b.key].length; })), false)) : 0;
+    // Resolve a point binding to a single value: a fixed constant, a scalar lookup,
+    // or the selected row's column for a row selection (`match` = id prefix).
+    var pointValue = function (b) {
+        if (b.constant !== undefined)
+            return b.constant || undefined;
+        if (!b.match)
+            return values[b.key];
+        var row = toRows(values[b.key]).find(function (r) { var _a; return String((_a = Object.values(r)[0]) !== null && _a !== void 0 ? _a : '').startsWith(b.match); });
+        return row ? row[b.column] : undefined;
+    };
+    // How a binding is referenced in the `data-key` attribute.
+    var ref = function (b) {
+        return b.constant !== undefined
+            ? 'const'
+            : "".concat(b.key).concat(b.match ? '@' + b.match : '').concat(b.column ? ':' + b.column : '');
+    };
     // Expand the `\sum` inline, wrapping each row value with `wrapRow`. Returns the
     // original formula when there is no table to expand over.
     var expand = function (wrapRow) {
-        if (!sumMatch || !rows || !rows.length)
+        if (!sumMatch || !rowCount)
             return formula.formula;
         var before = formula.formula.slice(0, sumMatch.index);
         var summand = formula.formula.slice(sumMatch.index + sumMatch[0].length);
-        var symbols = columnBindings.map(function (b) { return b.symbol; });
-        var terms = rows.map(function (row) {
+        var symbols = sumBindings.map(function (b) { return b.symbol; });
+        var terms = Array.from({ length: rowCount }, function (_, i) {
             return '(' +
                 splitOnSymbols(summand, symbols)
                     .map(function (seg) {
                     if (seg.text !== undefined)
                         return seg.text;
-                    var b = columnBindings.find(function (x) { return x.symbol === seg.symbol; });
-                    var value = formatValue(row[b.column]);
+                    var b = sumBindings.find(function (x) { return x.symbol === seg.symbol; });
+                    var row = tableRows[b.key][i];
+                    var value = row ? formatValue(row[b.column]) : null;
                     return value === null ? seg.symbol : wrapRow(b, value);
                 })
                     .join('') +
@@ -158,22 +187,22 @@ var renderFormula = function (formula, values) {
         });
         return before + terms.join(' + ');
     };
-    // Substitute the scalar (non-column) symbols over a working string.
-    var substituteScalars = function (working, wrap) {
-        return splitOnSymbols(working, scalarBindings.map(function (b) { return b.symbol; }))
+    // Substitute the point (single-value) symbols over a working string.
+    var substitutePoints = function (working, wrap) {
+        return splitOnSymbols(working, pointBindings.map(function (b) { return b.symbol; }))
             .map(function (seg) {
             if (seg.text !== undefined)
                 return seg.text;
-            var b = scalarBindings.find(function (x) { return x.symbol === seg.symbol; });
-            return wrap(b, seg.symbol, formatValue(values[b.key]));
+            var b = pointBindings.find(function (x) { return x.symbol === seg.symbol; });
+            return wrap(b, seg.symbol, formatValue(pointValue(b)));
         })
             .join('');
     };
-    var substituted = substituteScalars(expand(function (b, v) { return "\\htmlData{key=".concat(b.key, ":").concat(b.column, "}{").concat(v, "}"); }), function (b, symbol, value) {
-        return value === null ? symbol : "\\htmlData{key=".concat(b.key, "}{").concat(value, "}");
+    var substituted = substitutePoints(expand(function (b, v) { return "\\htmlData{key=".concat(ref(b), "}{").concat(v, "}"); }), function (b, symbol, value) {
+        return value === null ? symbol : "\\htmlData{key=".concat(ref(b), "}{").concat(value, "}");
     });
-    var annotated = substituteScalars(expand(function (b, v) { return "\\htmlData{key=".concat(b.key, ":").concat(b.column, ", value=").concat(v, "}{").concat(v, "}"); }), function (b, symbol, value) {
-        return "\\htmlData{key=".concat(b.key, ", value=").concat(value === null ? 'na' : value, "}{").concat(symbol, "}");
+    var annotated = substitutePoints(expand(function (b, v) { return "\\htmlData{key=".concat(ref(b), ", value=").concat(v, "}{").concat(v, "}"); }), function (b, symbol, value) {
+        return "\\htmlData{key=".concat(ref(b), ", value=").concat(value === null ? 'na' : value, "}{").concat(symbol, "}");
     });
     return { symbolic: formula.formula, substituted: substituted, annotated: annotated };
 };

package/cjs/version.d.ts

@@ -1 +1 @@
-export declare const ENGINE_VERSION = "0.82.0";
+export declare const ENGINE_VERSION = "0.82.2";

package/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ENGINE_VERSION = void 0;
-exports.ENGINE_VERSION = '0.82.0';
+exports.ENGINE_VERSION = '0.82.2';

package/esm/formulas.d.ts

@@ -19,11 +19,24 @@ export interface IFormulaBinding {
      */
     key?: string;
     /**
-     * For a per-row value inside a packed `log_as_table` string: the column to
-     * read from each row. When set, the symbol sits under a `\sum` and is expanded
-     * once per row (e.g. `\sum_i M_i \times EF_i` → `(32 × 0.166) + (13 × 0.495)`).
+     * A value inside a packed `log_as_table` string: the column to read.
+     * - with no `match`, the symbol sits under a `\sum` and is expanded once per
+     *   row (e.g. `\sum_i M_i \times EF_i` → `(32 × 0.166) + (13 × 0.495)`);
+     * - with `match`, it resolves to a single row (row selection, see `match`).
      */
     column?: string;
+    /**
+     * Row selection: pick the one row of the `key` table whose id (first column)
+     * starts with this value, then read `column` from it. Resolves to a single
+     * value, e.g. `NH_3\text{-}N` → the `emission-value` of the row `nh3…`.
+     */
+    match?: string;
+    /**
+     * A fixed constant (not logged): the symbol always substitutes to this literal
+     * (e.g. `ER` → `2`) and is excluded from coverage. Empty string marks a
+     * constant with no display value.
+     */
+    constant?: string;
 }
 /**
  * A KaTeX formula extracted from a model's documentation, with the bindings

package/esm/formulas.js

@@ -55,8 +55,9 @@ const formatValue = (value) => {
         return round4(value);
     return formatNumericString(String(value));
 };
-// `\sum` with an optional index subscript (`_i`, `_{i}`, ...) and trailing space.
-const SUM_RE = /\\sum(?:_\{[^}]*\}|_[^\s{])?\s*/;
+// `\sum` with an optional index subscript (`_i`, `_{s=1}`, ...) and upper bound
+// superscript (`^S`, `^{S}`), and trailing space.
+const SUM_RE = /\\sum(?:_\{[^}]*\}|_[^\s{])?(?:\^\{[^}]*\}|\^[^\s{])?\s*/;
 // Parse a packed `log_as_table` string into rows: rows split on `;`, columns on
 // `_`, each column a `key:value` pair (values never contain `_` or `:`).
 const parseTable = (packed) => packed
@@ -81,50 +82,75 @@ const parseTable = (packed) => packed
  * (or an array of row objects). Without the table it stays symbolic.
  */
 export const renderFormula = (formula, values) => {
-    var _a;
-    const columnBindings = formula.bindings.filter((b) => b.key && b.column);
-    const scalarBindings = formula.bindings.filter((b) => b.key && !b.column);
-    const sumMatch = columnBindings.length ? SUM_RE.exec(formula.formula) : null;
-    const tableKey = (_a = columnBindings[0]) === null || _a === void 0 ? void 0 : _a.key;
-    const raw = values[tableKey];
-    const rows = !sumMatch
-        ? null
-        : Array.isArray(raw)
-            ? raw
-            : typeof raw === 'string'
-                ? parseTable(raw)
-                : null;
+    // sum: a per-row column under a \sum. point: a single value — a scalar, a row
+    // selection (`match` + `column`), or a fixed constant.
+    const sumBindings = formula.bindings.filter((b) => b.key && b.column && !b.match);
+    const pointBindings = formula.bindings.filter((b) => (b.key && !(b.column && !b.match)) || b.constant);
+    const toRows = (source) => Array.isArray(source)
+        ? source
+        : typeof source === 'string'
+            ? parseTable(source)
+            : [];
+    const sumMatch = sumBindings.length ? SUM_RE.exec(formula.formula) : null;
+    // The summand may draw from several parallel tables (e.g. one for values, one
+    // for factors); parse each once and align them by row index.
+    const tableRows = {};
+    if (sumMatch) {
+        sumBindings.forEach((b) => {
+            const key = b.key;
+            if (!(key in tableRows))
+                tableRows[key] = toRows(values[key]);
+        });
+    }
+    const rowCount = sumMatch
+        ? Math.max(0, ...sumBindings.map((b) => tableRows[b.key].length))
+        : 0;
+    // Resolve a point binding to a single value: a fixed constant, a scalar lookup,
+    // or the selected row's column for a row selection (`match` = id prefix).
+    const pointValue = (b) => {
+        if (b.constant !== undefined)
+            return b.constant || undefined;
+        if (!b.match)
+            return values[b.key];
+        const row = toRows(values[b.key]).find((r) => { var _a; return String((_a = Object.values(r)[0]) !== null && _a !== void 0 ? _a : '').startsWith(b.match); });
+        return row ? row[b.column] : undefined;
+    };
+    // How a binding is referenced in the `data-key` attribute.
+    const ref = (b) => b.constant !== undefined
+        ? 'const'
+        : `${b.key}${b.match ? '@' + b.match : ''}${b.column ? ':' + b.column : ''}`;
     // Expand the `\sum` inline, wrapping each row value with `wrapRow`. Returns the
     // original formula when there is no table to expand over.
     const expand = (wrapRow) => {
-        if (!sumMatch || !rows || !rows.length)
+        if (!sumMatch || !rowCount)
             return formula.formula;
         const before = formula.formula.slice(0, sumMatch.index);
         const summand = formula.formula.slice(sumMatch.index + sumMatch[0].length);
-        const symbols = columnBindings.map((b) => b.symbol);
-        const terms = rows.map((row) => '(' +
+        const symbols = sumBindings.map((b) => b.symbol);
+        const terms = Array.from({ length: rowCount }, (_, i) => '(' +
             splitOnSymbols(summand, symbols)
                 .map((seg) => {
                 if (seg.text !== undefined)
                     return seg.text;
-                const b = columnBindings.find((x) => x.symbol === seg.symbol);
-                const value = formatValue(row[b.column]);
+                const b = sumBindings.find((x) => x.symbol === seg.symbol);
+                const row = tableRows[b.key][i];
+                const value = row ? formatValue(row[b.column]) : null;
                 return value === null ? seg.symbol : wrapRow(b, value);
             })
                 .join('') +
             ')');
         return before + terms.join(' + ');
     };
-    // Substitute the scalar (non-column) symbols over a working string.
-    const substituteScalars = (working, wrap) => splitOnSymbols(working, scalarBindings.map((b) => b.symbol))
+    // Substitute the point (single-value) symbols over a working string.
+    const substitutePoints = (working, wrap) => splitOnSymbols(working, pointBindings.map((b) => b.symbol))
         .map((seg) => {
         if (seg.text !== undefined)
             return seg.text;
-        const b = scalarBindings.find((x) => x.symbol === seg.symbol);
-        return wrap(b, seg.symbol, formatValue(values[b.key]));
+        const b = pointBindings.find((x) => x.symbol === seg.symbol);
+        return wrap(b, seg.symbol, formatValue(pointValue(b)));
     })
         .join('');
-    const substituted = substituteScalars(expand((b, v) => `\\htmlData{key=${b.key}:${b.column}}{${v}}`), (b, symbol, value) => value === null ? symbol : `\\htmlData{key=${b.key}}{${value}}`);
-    const annotated = substituteScalars(expand((b, v) => `\\htmlData{key=${b.key}:${b.column}, value=${v}}{${v}}`), (b, symbol, value) => `\\htmlData{key=${b.key}, value=${value === null ? 'na' : value}}{${symbol}}`);
+    const substituted = substitutePoints(expand((b, v) => `\\htmlData{key=${ref(b)}}{${v}}`), (b, symbol, value) => value === null ? symbol : `\\htmlData{key=${ref(b)}}{${value}}`);
+    const annotated = substitutePoints(expand((b, v) => `\\htmlData{key=${ref(b)}, value=${v}}{${v}}`), (b, symbol, value) => `\\htmlData{key=${ref(b)}, value=${value === null ? 'na' : value}}{${symbol}}`);
     return { symbolic: formula.formula, substituted, annotated };
 };

package/esm/version.d.ts

@@ -1 +1 @@
-export declare const ENGINE_VERSION = "0.82.0";
+export declare const ENGINE_VERSION = "0.82.2";

package/esm/version.js

@@ -1 +1 @@
-export const ENGINE_VERSION = '0.82.0';
+export const ENGINE_VERSION = '0.82.2';

package/formulas/README.md

@@ -6,16 +6,15 @@ 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`
+`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
 
-| 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. |
+`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
 
@@ -24,7 +23,9 @@ 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
+  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 {
@@ -162,13 +163,26 @@ 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 -->
+- $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`).
-- Leave constants unbound; they render as-is.
+- **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.
+- Tag a **documentation-only** symbol with `` `[display]` `` when it genuinely
+  can't be substituted and is *not* a constant — e.g. a per-event Monte-Carlo term
+  that never reduces to a single logged value. It renders symbolically and is
+  excluded from coverage. **Do not** use `` `[const]` `` for a real variable to
+  reach coverage: `validate-formula-bindings.js` errors on an empty `` `[const]` ``
+  whose symbol isn't a numeric literal.
 
 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
@@ -184,6 +198,21 @@ Where:
 - $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