@hestia-earth/engine-models 0.87.1 → 0.87.4

package/cjs/validate-config.d.ts

@@ -1,11 +1,126 @@
-import { allowedType, IOrchestratorModelConfig } from './config';
+import { allowedType, IOrchestratorConfig, IOrchestratorModelConfig } from './config';
+/**
+ * JSON Schema (draft-07) describing an orchestrator configuration file.
+ * Note: it uses no external `$ref` and no `format` keyword, so it compiles with any ajv version.
+ */
+export declare const configSchema: {
+    $schema: string;
+    type: string;
+    definitions: {
+        runArgs: {
+            type: string;
+            properties: {
+                skipEmptyValue: {
+                    type: string;
+                };
+                skipAggregated: {
+                    type: string;
+                };
+                termId: {
+                    type: string;
+                };
+                runNonAddedTerm: {
+                    type: string;
+                };
+                runNonMeasured: {
+                    type: string;
+                };
+            };
+        };
+        mergeArgs: {
+            type: string;
+            properties: {
+                sameMethodModel: {
+                    type: string;
+                };
+                skipSameTerm: {
+                    type: string;
+                };
+                replaceThreshold: {
+                    type: string;
+                    minItems: number;
+                    maxItems: number;
+                    items: {
+                        type: string;
+                    }[];
+                };
+                replaceLowerTier: {
+                    type: string;
+                };
+                matchDatesFormat: {
+                    type: string;
+                };
+            };
+        };
+        model: {
+            type: string;
+            properties: {
+                key: {
+                    type: string;
+                };
+                model: {
+                    type: string;
+                };
+                value: {
+                    type: string;
+                };
+                runStrategy: {
+                    type: string;
+                    enum: string[];
+                };
+                runArgs: {
+                    $ref: string;
+                };
+                mergeStrategy: {
+                    type: string;
+                    enum: string[];
+                };
+                mergeArgs: {
+                    $ref: string;
+                };
+                stage: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+            };
+            required: string[];
+        };
+        "model-list": {
+            anyOf: ({
+                $ref: string;
+                type?: undefined;
+                items?: undefined;
+            } | {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+                $ref?: undefined;
+            })[];
+        };
+    };
+    properties: {
+        models: {
+            type: string;
+            items: {
+                $ref: string;
+            };
+        };
+    };
+    required: string[];
+};
+/**
+ * Either a node type, in which case the bundled configuration is used, or a configuration to validate.
+ */
+export type configOrNodeType = allowedType | IOrchestratorConfig;
 /**
  * Use inter-dependencies to detect models that are in the wrong order.
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  * @returns List of models that have dependencies that could not be found prior to running.
  */
-export declare const validateConfigOrder: (nodeType: allowedType) => {
+export declare const validateConfigOrder: (config: configOrNodeType) => {
     model: IOrchestratorModelConfig;
     existing: string[];
     missing: string[];
@@ -14,6 +129,6 @@ export declare const validateConfigOrder: (nodeType: allowedType) => {
  * Detect multiple models running in parallel when they should not.
  * Note: we use the `mergeArgs` to handle special cases when multiple identical models CAN run in parallel
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  */
-export declare const validateConfigDuplicates: (nodeType: allowedType) => IOrchestratorModelConfig[];
+export declare const validateConfigDuplicates: (config: configOrNodeType) => IOrchestratorModelConfig[];

package/cjs/validate-config.js

@@ -36,9 +36,18 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateConfigDuplicates = exports.validateConfigOrder = void 0;
+exports.validateConfigDuplicates = exports.validateConfigOrder = exports.configSchema = void 0;
 var config_1 = require("./config");
 var utils_1 = require("./utils");
+var schema = require("../config/config-schema.json");
+/**
+ * JSON Schema (draft-07) describing an orchestrator configuration file.
+ * Note: it uses no external `$ref` and no `format` keyword, so it compiles with any ajv version.
+ */
+exports.configSchema = schema;
+var resolveConfig = function (config) {
+    return typeof config === 'string' ? (0, config_1.loadConfig)(config) : config;
+};
 // models not included in the links
 var skipModels = ['emissions.deleted', 'transformations'];
 var isHestiaResidueCyclicModel = function (_a) {
@@ -85,13 +94,12 @@ var matchDependencies = function (models) { return function (model) {
 /**
  * Use inter-dependencies to detect models that are in the wrong order.
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  * @returns List of models that have dependencies that could not be found prior to running.
  */
-var validateConfigOrder = function (nodeType) {
-    var config = (0, config_1.loadConfig)(nodeType);
+var validateConfigOrder = function (config) {
     // flatten all models to process one by one, starting with the last one
-    var models = config.models.flat();
+    var models = resolveConfig(config).models.flat();
     var results = models.filter(includeModel).map(matchDependencies(models));
     return results.filter(function (r) { return r.missing.length > 0; });
 };
@@ -109,12 +117,13 @@ var findDuplicatedConfigs = function (models) {
  * Detect multiple models running in parallel when they should not.
  * Note: we use the `mergeArgs` to handle special cases when multiple identical models CAN run in parallel
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  */
-var validateConfigDuplicates = function (nodeType) {
-    var config = (0, config_1.loadConfig)(nodeType);
-    var duplicates = config.models
-        .map(function (value) { return (Array.isArray(value) ? findDuplicatedConfigs(value) : []); })
+var validateConfigDuplicates = function (config) {
+    var duplicates = resolveConfig(config)
+        .models.map(function (value) {
+        return Array.isArray(value) ? findDuplicatedConfigs(value) : [];
+    })
         .flat(2);
     return duplicates;
 };

package/cjs/version.d.ts

@@ -1 +1 @@
-export declare const ENGINE_VERSION = "0.87.1";
+export declare const ENGINE_VERSION = "0.87.4";

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.87.1';
+exports.ENGINE_VERSION = '0.87.4';

package/config/config-schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "type": "object",
+  "definitions": {
+    "runArgs": {
+      "type": "object",
+      "properties": {
+        "skipEmptyValue": {
+          "type": "boolean"
+        },
+        "skipAggregated": {
+          "type": "boolean"
+        },
+        "termId": {
+          "type": "string"
+        },
+        "runNonAddedTerm": {
+          "type": "boolean"
+        },
+        "runNonMeasured": {
+          "type": "boolean"
+        }
+      }
+    },
+    "mergeArgs": {
+      "type": "object",
+      "properties": {
+        "sameMethodModel": {
+          "type": "boolean"
+        },
+        "skipSameTerm": {
+          "type": "boolean"
+        },
+        "replaceThreshold": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
+        "replaceLowerTier": {
+          "type": "boolean"
+        },
+        "matchDatesFormat": {
+          "type": "string"
+        }
+      }
+    },
+    "model": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        },
+        "runStrategy": {
+          "type": "string",
+          "enum": ["add_blank_node_if_missing", "add_key_if_missing", "always"]
+        },
+        "runArgs": {
+          "$ref": "#/definitions/runArgs"
+        },
+        "mergeStrategy": {
+          "type": "string",
+          "enum": ["default", "list", "node", "append"]
+        },
+        "mergeArgs": {
+          "$ref": "#/definitions/mergeArgs"
+        },
+        "stage": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2
+        }
+      },
+      "required": ["key", "model", "runStrategy", "mergeStrategy"]
+    },
+    "model-list": {
+      "anyOf": [
+        { "$ref": "#/definitions/model" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/definitions/model" }
+        }
+      ]
+    }
+  },
+  "properties": {
+    "models": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/model-list"
+      }
+    }
+  },
+  "required": ["models"]
+}

package/esm/validate-config.d.ts

@@ -1,11 +1,126 @@
-import { allowedType, IOrchestratorModelConfig } from './config';
+import { allowedType, IOrchestratorConfig, IOrchestratorModelConfig } from './config';
+/**
+ * JSON Schema (draft-07) describing an orchestrator configuration file.
+ * Note: it uses no external `$ref` and no `format` keyword, so it compiles with any ajv version.
+ */
+export declare const configSchema: {
+    $schema: string;
+    type: string;
+    definitions: {
+        runArgs: {
+            type: string;
+            properties: {
+                skipEmptyValue: {
+                    type: string;
+                };
+                skipAggregated: {
+                    type: string;
+                };
+                termId: {
+                    type: string;
+                };
+                runNonAddedTerm: {
+                    type: string;
+                };
+                runNonMeasured: {
+                    type: string;
+                };
+            };
+        };
+        mergeArgs: {
+            type: string;
+            properties: {
+                sameMethodModel: {
+                    type: string;
+                };
+                skipSameTerm: {
+                    type: string;
+                };
+                replaceThreshold: {
+                    type: string;
+                    minItems: number;
+                    maxItems: number;
+                    items: {
+                        type: string;
+                    }[];
+                };
+                replaceLowerTier: {
+                    type: string;
+                };
+                matchDatesFormat: {
+                    type: string;
+                };
+            };
+        };
+        model: {
+            type: string;
+            properties: {
+                key: {
+                    type: string;
+                };
+                model: {
+                    type: string;
+                };
+                value: {
+                    type: string;
+                };
+                runStrategy: {
+                    type: string;
+                    enum: string[];
+                };
+                runArgs: {
+                    $ref: string;
+                };
+                mergeStrategy: {
+                    type: string;
+                    enum: string[];
+                };
+                mergeArgs: {
+                    $ref: string;
+                };
+                stage: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+            };
+            required: string[];
+        };
+        "model-list": {
+            anyOf: ({
+                $ref: string;
+                type?: undefined;
+                items?: undefined;
+            } | {
+                type: string;
+                items: {
+                    $ref: string;
+                };
+                $ref?: undefined;
+            })[];
+        };
+    };
+    properties: {
+        models: {
+            type: string;
+            items: {
+                $ref: string;
+            };
+        };
+    };
+    required: string[];
+};
+/**
+ * Either a node type, in which case the bundled configuration is used, or a configuration to validate.
+ */
+export type configOrNodeType = allowedType | IOrchestratorConfig;
 /**
  * Use inter-dependencies to detect models that are in the wrong order.
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  * @returns List of models that have dependencies that could not be found prior to running.
  */
-export declare const validateConfigOrder: (nodeType: allowedType) => {
+export declare const validateConfigOrder: (config: configOrNodeType) => {
     model: IOrchestratorModelConfig;
     existing: string[];
     missing: string[];
@@ -14,6 +129,6 @@ export declare const validateConfigOrder: (nodeType: allowedType) => {
  * Detect multiple models running in parallel when they should not.
  * Note: we use the `mergeArgs` to handle special cases when multiple identical models CAN run in parallel
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  */
-export declare const validateConfigDuplicates: (nodeType: allowedType) => IOrchestratorModelConfig[];
+export declare const validateConfigDuplicates: (config: configOrNodeType) => IOrchestratorModelConfig[];

package/esm/validate-config.js

@@ -1,5 +1,12 @@
 import { loadConfig } from './config';
 import { findMatchingModelFromConfig } from './utils';
+import * as schema from '../config/config-schema.json';
+/**
+ * JSON Schema (draft-07) describing an orchestrator configuration file.
+ * Note: it uses no external `$ref` and no `format` keyword, so it compiles with any ajv version.
+ */
+export const configSchema = schema;
+const resolveConfig = (config) => typeof config === 'string' ? loadConfig(config) : config;
 // models not included in the links
 const skipModels = ['emissions.deleted', 'transformations'];
 const isHestiaResidueCyclicModel = ({ model, value }) => model === 'hestia' && (value === null || value === void 0 ? void 0 : value.startsWith('residue'));
@@ -34,13 +41,12 @@ const matchDependencies = (models) => (model) => {
 /**
  * Use inter-dependencies to detect models that are in the wrong order.
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  * @returns List of models that have dependencies that could not be found prior to running.
  */
-export const validateConfigOrder = (nodeType) => {
-    const config = loadConfig(nodeType);
+export const validateConfigOrder = (config) => {
     // flatten all models to process one by one, starting with the last one
-    const models = config.models.flat();
+    const models = resolveConfig(config).models.flat();
     const results = models.filter(includeModel).map(matchDependencies(models));
     return results.filter((r) => r.missing.length > 0);
 };
@@ -54,12 +60,11 @@ const findDuplicatedConfigs = (models) => {
  * Detect multiple models running in parallel when they should not.
  * Note: we use the `mergeArgs` to handle special cases when multiple identical models CAN run in parallel
  *
- * @param nodeType Cycle, Site, or ImpactAssessment
+ * @param config Cycle, Site, or ImpactAssessment to use the bundled configuration, or a configuration itself.
  */
-export const validateConfigDuplicates = (nodeType) => {
-    const config = loadConfig(nodeType);
-    const duplicates = config.models
-        .map((value) => (Array.isArray(value) ? findDuplicatedConfigs(value) : []))
+export const validateConfigDuplicates = (config) => {
+    const duplicates = resolveConfig(config)
+        .models.map((value) => Array.isArray(value) ? findDuplicatedConfigs(value) : [])
         .flat(2);
     return duplicates;
 };

package/esm/version.d.ts

@@ -1 +1 @@
-export declare const ENGINE_VERSION = "0.87.1";
+export declare const ENGINE_VERSION = "0.87.4";

package/esm/version.js

@@ -1 +1 @@
-export const ENGINE_VERSION = '0.87.1';
+export const ENGINE_VERSION = '0.87.4';

package/formulas/README.md

@@ -217,3 +217,7 @@ Where:
 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.
+
+## Delimiters
+
+The guide renders formulas with `marked-katex-extension`, whose tokenizer only picks up an inline `$...$` when the opening `$` starts the line or follows a space, and the closing `$` ends the line or is followed by a space or one of `?!.,:`. `($x$)` fails both and renders as literal `$x$` on the page, with no error anywhere — so write `( $x$ )`, or reword. `scripts/validate-katex.js` checks every model doc for this on every build.

package/formulas/index.json

@@ -2184,7 +2184,7 @@
       "bindings": [
         {
           "symbol": "E_{CH4}",
-          "description": "Methane emissions (in kg $CH_4$)",
+          "description": "Methane emissions, in kg $CH_4$.",
           "key": "value"
         },
         {
@@ -2199,7 +2199,7 @@
         },
         {
           "symbol": "55.65",
-          "description": "The energy content of methane (in MJ/kg $CH_4$).",
+          "description": "The energy content of methane, in MJ/kg $CH_4$.",
           "constant": ""
         }
       ]
@@ -5721,12 +5721,12 @@
         },
         {
           "symbol": "C_{resp}",
-          "description": "is the carbon lost via respiration, in kg C per Cycle (equal to $C_{harvest}$).",
+          "description": "is the carbon lost via respiration, in kg C per Cycle, equal to $C_{harvest}$.",
           "key": "c_resp"
         },
         {
           "symbol": "C_{excr}",
-          "description": "is the carbon in excreta, in kg C per Cycle (half the value of $C_{harvest}$).",
+          "description": "is the carbon in excreta, in kg C per Cycle, half the value of $C_{harvest}$.",
           "key": "c_excr"
         },
         {