Function compile

src/compute-engine/compilation/compile-expression.ts:59–194

(
  expr: Expression,
  options?: CompileExpressionOptions<T>
)

 *
 * If the expression cannot be compiled, falls back to interpretation
 * (success: false, run: applicableN1) unless `options.fallback` is false,
 * in which case it throws.
 *
 * ## Real-only special functions (compile targets)
 *
 * The built-in targets implement most special functions (`Erf`, `Gamma`,
 * `Zeta`, the Bessel/Airy family, …) with **real-only** library helpers
 * (`_SYS.erf`, `scipy.special.erf`, GLSL `log2`, …). They accept a real scalar
 * only. Elementary functions that *do* have a complex extension (`Sin`, `Exp`,
 * `Sqrt`, `Power`, …) dispatch to a complex helper when an argument is
 * complex-valued; the real-only special functions do not. A complex value
 * must never reach a real helper (a compiled `Erf(z)` would return −1): under
 * `mode: 'strict'` the compiler **fails closed** (D6) with the offending
 * head; under `auto` (the default) and `complex` a MAYBE-complex operand (a
 * `complex`-typed symbol, a promoted radical, a wide binding in complex mode)
 * takes the D2/D6 runtime rule — the real helper runs when the value's
 * imaginary part is exactly zero, `NaN` otherwise — and only a STATICALLY
 * non-real operand (`Erf(2i)`) is the compile-time decline. The shader
 * targets always fail closed. (`Real`/`Imaginary`/`Argument`/`Conjugate` are
 * exempt: they consume a complex value by design.)
 */
export function compile<T extends string = 'javascript'>(
  expr: Expression,
  options: CompileExpressionOptions<T> & { realOnly: true }
): CompilationResult<T, number>;
export function compile<T extends string = 'javascript'>(
  expr: Expression,
  options?: CompileExpressionOptions<T>
): CompilationResult<T>;
export function compile<T extends string = 'javascript'>(
  expr: Expression,
  options?: CompileExpressionOptions<T>
): CompilationResult<T> {
  assertCompilationOptionsContract(options);
  // The deprecated `complexPromotion: true` maps to `mode: 'complex'` — but
  // only where the target OFFERS complex mode. The flag was documented as
  // ignored on the shader targets ("they keep the real kernel
  // unconditionally"), so a caller passing it globally must not see a shader
  // compile that used to succeed decline with `unsupported-mode`; on such a
  // target the alias is dropped and the target's default mode applies.
  const deprecated = applyDeprecatedModeOptions(options);
  options = deprecated.options;
  const modeFromAlias = deprecated.modeFromAlias;

  // An option-contract violation, not a compilation failure: raised OUTSIDE
  // the `try` so the interpreter fallback cannot swallow it. A direct custom
  // target never gets CSE in Phase 1 (§4.2), so an EXPLICIT `cse: true` here
  // is a request that cannot be honored — silently stamping it off would leave
  // the caller believing CSE ran.
  if (options?.target !== undefined && options.cse === true)
    throw new Error(
      'CSE is not supported on direct custom targets in Phase 1; omit `cse` ' +
        'or use a registered target.'
    );

  try {
    // Determine the target to use
    if (options?.target) {