@sdeverywhere/compile 0.7.35 → 0.7.36

package/dist/index.d.ts

@@ -0,0 +1,394 @@
+import { preprocessVensimModel } from "@sdeverywhere/parse";
+//#region dts-tmp/_shared/model-spec.d.ts
+/**
+ * A variable name as used in the modeling tool, for example `Some Var[DimA]` as used in
+ * a Vensim model.
+ */
+export type VarName = string;
+/**
+ * A variable identifier in the canonical format used internally by SDEverywhere, for
+ * example `_some_var`.  These are derived from a `VarName` by lowercasing the name and
+ * replacing special characters with underscores.
+ */
+export type VarId = string;
+/**
+ * A dimension (subscript range) identifier in the canonical format used internally by
+ * SDEverywhere, for example `_dima`.
+ */
+export type DimId = string;
+/**
+ * Describes a `dat` file that provides data for exogenous data variables in the model.
+ *
+ * This can either be:
+ *   - a plain file name (relative to the model directory), for example `data.dat`, or
+ *   - an object with a single key/value pair, where the key is a prefix that is prepended
+ *     to each variable name read from the file, and the value is the file name, for
+ *     example `{ "prefix ": "data.dat" }`.
+ */
+export type DatFileSpec = string | {
+  [varNamePrefix: string]: string;
+};
+/**
+ * Describes a model (e.g., a Vensim mdl file) and the input/output variables that should
+ * be included in the model generated by SDEverywhere.
+ *
+ * This is the type of the object that is parsed from a `spec.json` file (as passed to the
+ * `sde generate` command using the `--spec` argument) and that is accepted by the
+ * `parseAndGenerate` function.
+ *
+ * All properties are optional.  If neither `inputVarNames` nor `outputVarNames` is
+ * provided, the generated model will include all variables from the model and will not
+ * allow any inputs to be set at runtime.
+ */
+export type ModelSpec = {
+  /**
+   * The input variables for the model, using the
+   * variable names as they appear in the modeling tool.
+   *
+   * When this is provided, only the listed variables can be set at runtime, and any
+   * variables that are not needed to compute the configured `outputVarNames` will be pruned
+   * from the generated model.
+   */
+  inputVarNames?: VarName[];
+  /**
+   * The output variables for the model, using the
+   * variable names as they appear in the modeling tool.
+   *
+   * It is customary to include `Time` as the first output variable.
+   *
+   * When this is provided, only the listed variables (plus the variables needed to compute
+   * them) will be included in the generated model.
+   */
+  outputVarNames?: VarName[];
+  /**
+   * The `dat` files that provide the data for exogenous
+   * data variables in the model.
+   *
+   * Each entry is resolved relative to the model directory (i.e., the directory that is
+   * passed using the `--datadir` argument, which defaults to the directory that contains the
+   * model file).
+   */
+  datFiles?: DatFileSpec[];
+  /**
+   * The mapping of data tag to
+   * Excel workbook file name, used to resolve the data for `GET DIRECT DATA`,
+   * `GET DIRECT CONSTANTS`, and `GET DIRECT LOOKUPS` calls in the model.
+   *
+   * Each key is the tag that appears in the model equation (for example, `?data`), and each
+   * value is the name of an `xlsx` file that is resolved relative to the model directory.
+   */
+  directData?: {
+    [dataTag: string]: string;
+  };
+  /**
+   * The mapping of dimension
+   * name to family name, used when SDEverywhere cannot infer the family for a dimension
+   * from the model alone.
+   *
+   * Both the keys and the values use the dimension names as they appear in the modeling tool
+   * (they are converted to canonical form when the spec file is read).
+   */
+  dimensionFamilies?: {
+    [dimName: string]: string;
+  };
+  /**
+   * The mapping of
+   * variable identifier to the dimension(s) on which that variable should be separated
+   * into one variable instance per subscript.
+   *
+   * Separating a variable is sometimes necessary to break a dependency cycle that would
+   * otherwise prevent the model from being evaluated.  Each value can be either a single
+   * dimension identifier or an array of dimension identifiers.
+   */
+  specialSeparationDims?: {
+    [varId: string]: string | string[];
+  };
+  /**
+   * The dimensions for which all
+   * variables should be separated into one variable instance per subscript.
+   *
+   * This is a convenience alternative to `specialSeparationDims` that avoids the need to
+   * list each affected variable.  Each entry can be either a single dimension identifier or
+   * an array of dimension identifiers; a variable is separated only if every dimension in
+   * the entry appears on the left-hand side of its equation.
+   */
+  separateAllVarsWithDims?: (DimId | DimId[])[];
+  /**
+   * Whether to bundle a model listing with the generated
+   * model.
+   *
+   * If undefined, defaults to false.
+   *
+   * When this is true, a model listing will be bundled with the generated model to allow the
+   * `runtime` package to resolve variables that are referenced by name or identifier.  This
+   * listing will increase the size of the generated model, so it is recommended to set this
+   * to true only if it is needed.
+   */
+  bundleListing?: boolean;
+  /**
+   * Whether to allow constants to be
+   * overridden at runtime using `setConstant`.
+   *
+   * If undefined or false, the generated model will implement `setConstant` as a no-op,
+   * meaning that constants cannot be overridden at runtime.
+   *
+   * If true, all constants in the generated model will be available to be overridden.
+   *
+   * If an array is provided, only those variable names in the array will be available to be
+   * overridden.
+   */
+  customConstants?: boolean | VarName[];
+  /**
+   * Whether to allow lookups to be
+   * overridden at runtime using `setLookup`.
+   *
+   * If undefined or false, the generated model will implement `setLookup` as a no-op,
+   * meaning that lookups cannot be overridden at runtime.
+   *
+   * If true, all lookups in the generated model will be available to be overridden.
+   *
+   * If an array is provided, only those variable names in the array will be available to be
+   * overridden.
+   */
+  customLookups?: boolean | VarName[];
+  /**
+   * Whether to allow for capturing the data
+   * for arbitrary variables at runtime (including variables that are not configured in the
+   * `outputVarNames` array).
+   *
+   * If undefined or false, the generated model will implement `storeOutput` as a no-op,
+   * meaning that the data for arbitrary variables cannot be captured at runtime.
+   *
+   * If true, all variables in the generated model will be available to be captured at
+   * runtime.
+   *
+   * If an array is provided, only those variable names in the array will be available to be
+   * captured at runtime.
+   */
+  customOutputs?: boolean | VarName[];
+  /**
+   * The `dat` files that provide the data for
+   * exogenous data variables in the model.
+   *
+   * DEPRECATED: Use `datFiles` instead.  This property is still honored (but is ignored if
+   * `datFiles` is also provided) and will be removed in a future release.
+   */
+  externalDatfiles?: DatFileSpec[];
+  /**
+   * An optional descriptive name for the model.
+   *
+   * This is not currently used by SDEverywhere, but is allowed (and is included in many
+   * existing `spec.json` files) as a way to document what the model is.
+   */
+  name?: string;
+  /**
+   * The input variable identifiers for the model, in
+   * canonical form.
+   *
+   * This is derived from `inputVarNames` while the model is being read, and is not intended
+   * to be set in a `spec.json` file.
+   */
+  inputVars?: VarId[];
+  /**
+   * The output variable identifiers for the model, in
+   * canonical form.
+   *
+   * This is derived from `outputVarNames` while the model is being read, and is not intended
+   * to be set in a `spec.json` file.
+   */
+  outputVars?: VarId[];
+};
+//#endregion
+//#region dts-tmp/parse-and-generate.d.ts
+/**
+ * The kind of model that is being parsed.
+ *
+ * @typedef {'vensim' | 'xmile'} ModelKind
+ */
+/**
+ * A parsed tree representation of a model, along with the kind of model that was parsed.
+ *
+ * @typedef {Object} ParsedModel
+ * @property {ModelKind} kind The kind of model that was parsed.
+ * @property {import('@sdeverywhere/parse').Model} root The root of the parsed model AST.
+ */
+/**
+ * An operation that can be performed by `parseAndGenerate`.
+ *
+ * - `generateC` writes the generated C code to the build directory.
+ * - `generateJS` writes the generated JS code to the build directory.
+ * - `printVarList` writes variables and subscripts to txt and json files under the build
+ *   directory.
+ * - `printRefIdTest` prints reference identifiers to the console.
+ * - `printRefGraph` prints the variable dependency graph to the console.
+ * - `convertNames` generates no output, but makes the results of model analysis available.
+ *
+ * @typedef {'generateC' | 'generateJS' | 'printVarList' | 'printRefIdTest' | 'printRefGraph' | 'convertNames'} GenerateOperation
+ */
+/**
+ * Parse a Vensim or XMILE model and generate C code.
+ *
+ * This is the primary entrypoint for the `sde generate` command.
+ *
+ * - If `operations` has 'generateC', the generated C code will be written to `buildDir`.
+ * - If `operations` has 'generateJS', the generated JS code will be written to `buildDir`.
+ * - If `operations` has 'printVarList', variables and subscripts will be written to
+ *   txt and json files under `buildDir`.
+ * - If `operations` has 'printRefIdTest', reference identifiers will be printed to the console.
+ * - If `operations` has 'convertNames', no output will be generated, but the results of model
+ *   analysis will be available.
+ *
+ * @param {string} input The preprocessed Vensim or XMILE model text.
+ * @param {ModelKind} modelKind The kind of model to parse.
+ * @param {import('./_shared/model-spec.js').ModelSpec} spec The model spec (from the JSON file).
+ * @param {GenerateOperation[]} operations The set of operations to perform.  If the array is
+ * empty, the model will be read but no operation will be performed.
+ * @param {string} modelDirname The absolute path to the directory containing data (dat, xlsx, csv)
+ * files that are referenced by the model.  These files will be resolved relative to this directory.
+ * @param {string} modelName The model name (without the mdl extension).
+ * @param {string} buildDir The output directory where the C or list files will be written.
+ * @param {string} [varname] The variable name passed to the 'sde causes' command.
+ * @return {Promise<string>} A promise that resolves with the generated C or JS code.
+ */
+export declare function parseAndGenerate(input: string, modelKind: ModelKind, spec: ModelSpec, operations: GenerateOperation[], modelDirname: string, modelName: string, buildDir: string, varname?: string): Promise<string>;
+/**
+ * Read the variable names from the given file, convert them to their
+ * C or Vensim representation, and print the results to the console.
+ *
+ * This is used only to implement the `sde names` command.
+ *
+ * @param {string} namesPathname The path to the file containing variables names.
+ * @param {'to-c' | 'to-vensim'} operation The conversion to perform.
+ * @return {void}
+ */
+export declare function printNames(namesPathname: string, operation: 'to-c' | 'to-vensim'): void;
+/**
+ * Read and parse the given model text and return the parsed model structure.
+ *
+ * @param {string} input The string containing the model text.
+ * @param {ModelKind} modelKind The kind of model to parse.
+ * @param {string} [modelDir] The absolute path to the directory containing data (dat, xlsx, csv)
+ * files that are referenced by the model.  These files will be resolved relative to this directory.
+ * @param {Object} [options] The options that control parsing.
+ * @param {boolean} [options.sort] Whether to sort definitions alphabetically in the preprocess step.
+ * @return {ParsedModel} A parsed tree representation of the model.
+ */
+export declare function parseModel(input: string, modelKind: ModelKind, modelDir?: string, options?: {
+  sort?: boolean;
+}): ParsedModel;
+/**
+ * The kind of model that is being parsed.
+ */
+export type ModelKind = 'vensim' | 'xmile';
+/**
+ * A parsed tree representation of a model, along with the kind of model that was parsed.
+ */
+export type ParsedModel = {
+  /**
+   * The kind of model that was parsed.
+   */
+  kind: ModelKind;
+  /**
+   * The root of the parsed model AST.
+   */
+  root: import('@sdeverywhere/parse').Model;
+};
+/**
+ * An operation that can be performed by `parseAndGenerate`.
+ *
+ * - `generateC` writes the generated C code to the build directory.
+ * - `generateJS` writes the generated JS code to the build directory.
+ * - `printVarList` writes variables and subscripts to txt and json files under the build
+ *   directory.
+ * - `printRefIdTest` prints reference identifiers to the console.
+ * - `printRefGraph` prints the variable dependency graph to the console.
+ * - `convertNames` generates no output, but makes the results of model analysis available.
+ */
+export type GenerateOperation = 'generateC' | 'generateJS' | 'printVarList' | 'printRefIdTest' | 'printRefGraph' | 'convertNames';
+//#endregion
+//#region dts-tmp/_shared/read-dat.d.ts
+/**
+ * The datasets read from external `dat` files, keyed by variable identifier.  Each
+ * dataset is a map of time to value.
+ *
+ * @typedef {Map<import('./model-spec.js').VarId, Map<number, number>>} ExtData
+ */
+/**
+ * Read a Vensim `dat` file with static data and return a Map.
+ * Each dataset consists of a key (the variable name in the canonical
+ * format used by SDE) and a map of time/value pairs.
+ *
+ * @param {string} pathname The absolute path to the dat file.
+ * @param {string} [prefix] An optional prefix string prepended to var names.
+ * @return {Promise<ExtData>} A promise that resolves with a Map containing the datasets.
+ */
+export declare function readDat(pathname: string, prefix?: string): Promise<ExtData>;
+/**
+ * The datasets read from external `dat` files, keyed by variable identifier.  Each
+ * dataset is a map of time to value.
+ */
+export type ExtData = Map<VarId, Map<number, number>>;
+//#endregion
+//#region dts-tmp/_shared/helpers.d.ts
+export declare function canonicalName(name: VarName): VarId;
+//#endregion
+//#region dts-tmp/generate/gen-code.d.ts
+/**
+ * Generate code from the given parsed model.
+ *
+ * @param {import('../parse-and-generate.js').ParsedModel} parsedModel The parsed model structure.
+ * @param {Object} opts The options that control code generation.
+ * @param {import('../_shared/model-spec.js').ModelSpec} opts.spec The parsed `spec.json` object.
+ * @param {import('../parse-and-generate.js').GenerateOperation[]} opts.operations The array
+ * of operations to perform.
+ * @param {import('../_shared/read-dat.js').ExtData} [opts.extData] The map of datasets from
+ * external `.dat` files.
+ * @param {Map<string, any>} [opts.directData] The mapping of dataset name used in a
+ * `GET DIRECT DATA` call (e.g., `?data`) to the tabular data contained in the loaded
+ * data file.
+ * @param {string} [opts.modelDirname] The absolute path to the directory containing data
+ * (dat, xlsx, csv) files that are referenced by the model.  This path is used for
+ * resolving data files for `GET DIRECT SUBSCRIPT` calls.
+ * @param {string} [opts.varname] The variable name passed to the `sde causes` command.
+ * @returns {string} A string containing the generated code.
+ */
+export declare function generateCode(parsedModel: ParsedModel, opts: {
+  spec: ModelSpec;
+  operations: GenerateOperation[];
+  extData?: ExtData;
+  directData?: Map<string, any>;
+  modelDirname?: string;
+  varname?: string;
+}): string;
+//#endregion
+//#region dts-tmp/index.d.ts
+/**
+ * @hidden This is not yet part of the public API; it is exposed only for use
+ * in the experimental playground app.
+ */
+export declare function resetState(): void;
+/**
+ * @hidden This is not yet part of the public API; it is exposed only for use
+ * in the experimental playground app.
+ *
+ * @param {string} mdlContent The string containing the Vensim model text.
+ * @param {string} [modelDir] The absolute path to the directory containing data files.
+ * @return {import('./parse-and-generate.js').ParsedModel} A parsed tree representation of the model.
+ */
+export declare function parseInlineVensimModel(mdlContent: string, modelDir?: string): ParsedModel;
+/**
+ * @hidden This is not yet part of the public API; it is exposed only for use
+ * in the experimental playground app.
+ *
+ * @param {string} mdlContent The string containing the XMILE model text.
+ * @param {string} [modelDir] The absolute path to the directory containing data files.
+ * @return {import('./parse-and-generate.js').ParsedModel} A parsed tree representation of the model.
+ */
+export declare function parseInlineXmileModel(mdlContent: string, modelDir?: string): ParsedModel;
+/**
+ * @hidden This is not yet part of the public API; it is exposed only for use
+ * in the experimental playground app.
+ */
+export declare function getModelListing(): any;
+//#endregion
+export { preprocessVensimModel };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@sdeverywhere/compile",
-  "version": "0.7.35",
+  "version": "0.7.36",
   "description": "The core Vensim to C compiler for the SDEverywhere tool suite.",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@sdeverywhere/parse": "^0.1.6",
+    "@sdeverywhere/parse": "^0.1.7",
     "byline": "^5.0.0",
     "csv-parse": "^7.0.2",
     "fflate": "^0.8.3",
@@ -25,8 +25,10 @@
     "url": "https://github.com/climateinteractive/SDEverywhere/issues"
   },
   "scripts": {
-    "clean": "rm -rf dist",
-    "build": "tsup",
+    "clean": "rm -rf dts-tmp dist",
+    "build:dts": "tsc -p tsconfig-build.json --emitDeclarationOnly --outDir dts-tmp",
+    "build:bundle": "tsdown",
+    "build": "run-s build:dts build:bundle",
     "lint": "eslint . --max-warnings 0",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",