@cortex-js/compute-engine 0.32.0 → 0.32.1

package/dist/types/compute-engine/compilation/types.d.ts

@@ -0,0 +1,83 @@
+/* 0.32.1 */
+import type { BoxedExpression } from '../global-types';
+/**
+ * Source code in the target language
+ */
+export type TargetSource = string;
+/**
+ * A compiled function that can be executed
+ */
+export type CompiledFunction = string | ((args: ReadonlyArray<BoxedExpression>, compile: (expr: BoxedExpression) => TargetSource, target: CompileTarget) => TargetSource);
+/**
+ * Mapping of operators to their target language representation and precedence
+ */
+export type CompiledOperators = Record<MathJsonSymbol, [
+    op: string,
+    prec: number
+]>;
+/**
+ * Mapping of function names to their target language implementation
+ */
+export type CompiledFunctions = {
+    [id: MathJsonSymbol]: CompiledFunction;
+};
+/**
+ * Target language compilation configuration
+ */
+export interface CompileTarget {
+    /** Get operator representation for the target language */
+    operators?: (op: MathJsonSymbol) => [op: string, prec: number] | undefined;
+    /** Get function implementation for the target language */
+    functions?: (id: MathJsonSymbol) => CompiledFunction | undefined;
+    /** Get variable representation for the target language */
+    var: (id: MathJsonSymbol) => string | undefined;
+    /** Format string literals for the target language */
+    string: (str: string) => string;
+    /** Format numeric literals for the target language */
+    number: (n: number) => string;
+    /** Format whitespace for the target language */
+    ws: (s?: string) => string;
+    /** Code to be inserted at the beginning of the compiled output */
+    preamble: string;
+    /** Current indentation level */
+    indent: number;
+    /** Target language identifier (for debugging/logging) */
+    language?: string;
+}
+/**
+ * Base interface for language-specific compilation targets
+ */
+export interface LanguageTarget {
+    /** Get the default operators for this language */
+    getOperators(): CompiledOperators;
+    /** Get the default functions for this language */
+    getFunctions(): CompiledFunctions;
+    /** Create a CompileTarget for this language */
+    createTarget(options?: Partial<CompileTarget>): CompileTarget;
+    /** Compile an expression to executable code in this language */
+    compileToExecutable(expr: BoxedExpression, options?: CompilationOptions): CompiledExecutable;
+}
+/**
+ * Options for compilation
+ */
+export interface CompilationOptions {
+    /** Custom function implementations */
+    functions?: Record<MathJsonSymbol, TargetSource | Function>;
+    /** Variable bindings */
+    vars?: Record<MathJsonSymbol, TargetSource>;
+    /** Additional imports/libraries to include */
+    imports?: unknown[];
+    /** Additional preamble code */
+    preamble?: string;
+}
+/**
+ * A compiled expression that can be executed
+ */
+export interface CompiledExecutable {
+    /** Execute the compiled code */
+    (...args: any[]): any;
+    /** Get the source code */
+    toString(): string;
+    /** Flag indicating this is a compiled expression */
+    isCompiled: true;
+}

package/dist/types/compute-engine/cost-function.d.ts

@@ -0,0 +1,13 @@
+/* 0.32.1 */
+/**
+ * The default cost function, used to determine if a new expression is simpler
+ * than the old one.
+ *
+ * To change the cost function used by the engine, set the
+ * `ce.costFunction` property of the engine or pass a custom cost function
+ * to the `simplify` function.
+ *
+ */
+export declare function costFunction(expr: BoxedExpression): number;
+export declare function leafCount(expr: BoxedExpression): number;
+export declare const DEFAULT_COST_FUNCTION: typeof costFunction;

package/dist/types/compute-engine/function-utils.d.ts

@@ -0,0 +1,120 @@
+/* 0.32.1 */
+import type { BoxedDefinition, BoxedExpression, ComputeEngine, Scope } from './global-types';
+/***
+ * ### THEORY OF OPERATIONS
+ *
+ * The body of a `["Function"]` expression is a `["Block"]` expression,
+ * which is scoped. The function arguments are declared in that scope as well.
+ *
+ * Some expressions with anonymous parameters (e.g. `["Add", "_", 1]`)
+ * are rewritten to a `["Function"]` expression with anonymous parameters
+ * (e.g. `["Function", ["Block", ["Add", "_", 1]], "_"]`).
+ *
+ *
+ * #### DURING BOXING (in makeLambda())
+ *
+ * During the boxing/canonicalization phase of a function
+ * (`["Function"]` expression or operator of expression):
+ *
+ * 1/ If not a `["Function"]` expression, the expression is rewritten
+ *    to a `["Function"]` expression with anonymous parameters
+ * 2/ A new scope is created
+ * 3/ The function parameters are declared in the scope
+ * 4/ The function body is boxed in the context of the scope and the scope
+ *    is associated with the function
+ *
+ *
+ * #### DURING EVALUATION (executing the result of makeLambda())
+ *
+ * 1/ The arguments are evaluated in the current scope
+ * 2/ The context is swapped to the function scope
+ * 3/ The function parameters are set to the value of the arguments
+ * 4/ The function body is evaluated in the context of the function scope
+ * 5/ The context is swapped back to the current scope
+ * 6/ The result of the function body is returned
+ *
+ */
+/**
+ * From an expression, return a predicate function, which can be used to filter.
+ */
+export declare function predicate(_expr: BoxedExpression): (...args: BoxedExpression[]) => boolean;
+/**
+ * From an expression, create an ordering function, which can be used to sort.
+ */
+export declare function order(_expr: BoxedExpression): (a: BoxedExpression, b: BoxedExpression) => -1 | 0 | 1;
+/**
+ * Given an expression, rewrite it to a symbol or canonical Function form.
+ *
+ * - symbol (no change):
+ *      "Sin"
+ *     -> "Sin"
+ *
+ * - built-in function:
+ *      ["BuiltinFunction", "Sin"]
+ *     -> "Sin"
+ *
+ * - parenthesized expression:
+ *      ["Delimiter", ["Add", "_", 1], "'()'"]
+ *     -> ["Function", ["Block", ["Add", "_", 1]], "_"]
+ *
+ * - explicit parameters (adding a block to serve as a scope for the arguments):
+ *      ["Function", ["Add", "x", 1], "x"]
+ *      -> ["Function", ["Block", ["Add", "x", 1]], "x"]
+ *
+ *
+ * - single anonymous parameters:
+ *      ["Add", "_", 1]
+ *      -> ["Function", ["Block", ["Add", "_", 1]], "_"]
+ *
+ * - multiple anonymous parameters:
+ *      ["Add", "_1", "_2"]
+ *      -> ["Function", ["Block", ["Add", "_1", "_2"]], "_1", "_2"]
+ *
+ *
+ */
+export declare function canonicalFunctionLiteral(expr: BoxedExpression | undefined): BoxedExpression | undefined;
+/** Assuming that ops has the following form:
+ * - body
+ * - ...params
+ * return a canonical function literal (["Function", body, ...params]) where
+ * body is potentially wrapped in a Block expression and the arguments are
+ * declared in the scope of the body.
+ */
+export declare function canonicalFunctionLiteralArguments(ce: ComputeEngine, ops: ReadonlyArray<BoxedExpression>): BoxedExpression | undefined;
+/**
+ * Apply arguments to an expression which is either:
+ * - a `["Function"]` expression
+ * - the symbol for a function, e.g. `Sin`.
+ */
+export declare function apply(fn: BoxedExpression, args: ReadonlyArray<BoxedExpression>): BoxedExpression;
+/**
+ * Return a lambda function, assuming a scoped environment has been
+ * created and there is a single numeric argument
+ */
+export declare function makeLambdaN1(expr: BoxedExpression): ((arg: number) => number) | undefined;
+/**
+ * Given an expression such as:
+ * - ["Function", ["Add", 1, "x"], "x"]
+ * - ["Function", ["Divide", "_", 2]]
+ * - ["Multiply, "_", 3]
+ * - ["Add, "_1", "_2"]
+ * - "Sin"
+ *
+ * return a JS function that can be called with arguments.
+ */
+export declare function applicable(fn: BoxedExpression): (xs: ReadonlyArray<BoxedExpression>) => BoxedExpression | undefined;
+/**
+ * Use `applicableN1()` when the function is known to be a function with a
+ * single real argument that returns a real value.
+ *
+ * Unlike `apply()`, `applicableN1()` returns a function that can be called
+ * with an argument.
+ *
+ */
+export declare function applicableN1(fn: BoxedExpression): (x: number) => number;
+/**
+ * Given a string like "f(x,y)" return, ["f", ["x", "y"]]
+ */
+export declare function parseFunctionSignature(s: string): [id: string, args: string[] | undefined];
+/** Lookup a definition matching a symbol in a lexical scope chain */
+export declare function lookup(id: MathJsonSymbol, scope: Scope): undefined | BoxedDefinition;