openalgo-script 0.6.0 → 0.7.0

package/src/core/stdlib/maths/trigonometric.ts

@@ -0,0 +1,160 @@
+/** Directed integer enclosures for the real-result recipe in section 20.10.4. */
+import { bitLength, ceil, floor, parts, rounded, type Interval } from './transcendental.js';
+import { integerSqrt } from './hypot.js';
+
+export type TrigonometricKind = 'sin' | 'cos' | 'tan' | 'asin' | 'acos' | 'atan' | 'atan2';
+let cachedPi: { precision: number; value: Interval } = { precision: 0, value: [0n, 0n] };
+const negate = (a: Interval): Interval => [-a[1], -a[0]];
+const add = (a: Interval, b: Interval): Interval => [a[0] + b[0], a[1] + b[1]];
+const subtract = (a: Interval, b: Interval): Interval => [a[0] - b[1], a[1] - b[0]];
+const absolute = (n: bigint): bigint => n < 0n ? -n : n;
+
+function ratio(x: number): readonly [bigint, bigint] {
+  const [mantissa, exponent] = parts(x);
+  return exponent >= 0 ? [mantissa << BigInt(exponent), 1n] : [mantissa, 1n << BigInt(-exponent)];
+}
+
+function coarsen(a: Interval, shift: number): Interval {
+  const divisor = 1n << BigInt(shift);
+  return [floor(a[0], divisor), ceil(a[1], divisor)];
+}
+
+function quotient(a: Interval, b: Interval, precision: number): Interval | null {
+  if (b[0] <= 0n && b[1] >= 0n) return null;
+  const scale = 1n << BigInt(precision);
+  let low: bigint | undefined, high: bigint | undefined;
+  for (const numerator of a) for (const denominator of b) {
+    const n = denominator < 0n ? -numerator : numerator, d = absolute(denominator);
+    const lower = floor(n * scale, d), upper = ceil(n * scale, d);
+    if (low === undefined || lower < low) low = lower;
+    if (high === undefined || upper > high) high = upper;
+  }
+  return [low!, high!];
+}
+
+/** Alternating odd powers, with the first omitted term on its signed side. */
+function smallAtan(n: bigint, d: bigint, precision: number): Interval {
+  if (n === 0n) return [0n, 0n];
+  if (n < 0n) return negate(smallAtan(-n, d, precision));
+  const scale = 1n << BigInt(precision), zl = n * scale / d, zh = ceil(n * scale, d);
+  const squaredLow = zl * zl / scale, squaredHigh = ceil(zh * zh, scale);
+  let powerLow = zl, powerHigh = zh, low = 0n, high = 0n, odd = 1n, positive = true;
+  for (;;) {
+    const lower = powerLow / odd, upper = ceil(powerHigh, odd);
+    if (positive) { low += lower; high += upper; } else { low -= upper; high -= lower; }
+    powerLow = powerLow * squaredLow / scale;
+    powerHigh = ceil(powerHigh * squaredHigh, scale);
+    odd += 2n; positive = !positive;
+    if (powerHigh <= 1n) {
+      const tail = ceil(powerHigh, odd);
+      return positive ? [low, high + tail] : [low - tail, high];
+    }
+  }
+}
+
+function pi(precision: number): Interval {
+  if (cachedPi.precision >= precision) return coarsen(cachedPi.value, cachedPi.precision - precision);
+  const a = smallAtan(1n, 5n, precision), b = smallAtan(1n, 239n, precision);
+  const value: Interval = [16n * a[0] - 4n * b[1], 16n * a[1] - 4n * b[0]];
+  cachedPi = { precision, value };
+  return value;
+}
+
+function positiveAtan(n: bigint, d: bigint, precision: number): Interval {
+  if (n === 0n) return [0n, 0n];
+  if (d === 0n) return coarsen(pi(precision), 1);
+  if (n > d) return subtract(coarsen(pi(precision), 1), positiveAtan(d, n, precision));
+  if (2n * n > d) return add(coarsen(pi(precision), 2), smallAtan(n - d, n + d, precision));
+  return smallAtan(n, d, precision);
+}
+
+function pointSeries(z: bigint, precision: number, cosine: boolean): Interval {
+  if (z < 0n) {
+    const out = pointSeries(-z, precision, cosine);
+    return cosine ? out : negate(out);
+  }
+  const scale = 1n << BigInt(precision);
+  if (z === 0n) return cosine ? [scale, scale] : [0n, 0n];
+  const squaredLow = z * z / scale, squaredHigh = ceil(z * z, scale);
+  let low = cosine ? scale : z, high = low, termLow = low, termHigh = low;
+  let degree = cosine ? 0n : 1n, positive = false;
+  for (;;) {
+    const divisor = scale * (degree + 1n) * (degree + 2n);
+    termLow = termLow * squaredLow / divisor;
+    termHigh = ceil(termHigh * squaredHigh, divisor);
+    degree += 2n;
+    if (termHigh <= 1n) return positive ? [low, high + termHigh] : [low - termHigh, high];
+    if (positive) { low += termLow; high += termHigh; } else { low -= termHigh; high -= termLow; }
+    positive = !positive;
+  }
+}
+
+function reducedSinCos(x: number, precision: number): readonly [Interval, Interval] | null {
+  const [n, d] = ratio(x);
+  const reductionPrecision = precision + Math.max(0, bitLength(n) - bitLength(d)) + 32;
+  const scale = 1n << BigInt(reductionPrecision), [pl, ph] = pi(reductionPrecision);
+  const ql = (4n * n * scale + d * ph) / (2n * d * ph);
+  const qh = (4n * n * scale + d * pl) / (2n * d * pl);
+  if (ql !== qh) return null;
+  const residual: Interval = [n * scale / d - ceil(ql * ph, 2n), ceil(n * scale, d) - ql * pl / 2n];
+  const [lower, upper] = coarsen(residual, reductionPrecision - precision);
+  const unit = 1n << BigInt(precision);
+  if (lower < -unit || upper > unit) return null;
+  let sine: Interval = [pointSeries(lower, precision, false)[0], pointSeries(upper, precision, false)[1]];
+  const a = absolute(lower), b = absolute(upper), far = a > b ? a : b;
+  const near = lower <= 0n && upper >= 0n ? 0n : a < b ? a : b;
+  let cosine: Interval = [pointSeries(far, precision, true)[0], pointSeries(near, precision, true)[1]];
+  switch (Number(ql % 4n)) {
+    case 1: [sine, cosine] = [cosine, negate(sine)]; break;
+    case 2: [sine, cosine] = [negate(sine), negate(cosine)]; break;
+    case 3: [sine, cosine] = [negate(cosine), sine]; break;
+  }
+  return [x < 0 ? negate(sine) : sine, cosine];
+}
+
+function inverse(kind: TrigonometricKind, x: number, y: number, precision: number): Interval {
+  if (kind === 'atan') {
+    const [n, d] = ratio(x), out = positiveAtan(n, d, precision);
+    return x < 0 ? negate(out) : out;
+  }
+  if (kind === 'atan2') {
+    if (x === 0) return y > 0 ? coarsen(pi(precision), 1) : negate(coarsen(pi(precision), 1));
+    const [yn, yd] = ratio(y), [xn, xd] = ratio(x);
+    let out = positiveAtan(yn * xd, xn * yd, precision);
+    if (x < 0) out = subtract(pi(precision), out);
+    return y < 0 ? negate(out) : out;
+  }
+  const [n, d] = ratio(x), scale = 1n << BigInt(precision);
+  const radicand = (d * d - n * n) * scale * scale, root = integerSqrt(radicand / (d * d));
+  const upper = root + (root * root * d * d === radicand ? 0n : 1n);
+  if (kind === 'asin') {
+    const out: Interval = [positiveAtan(n * scale, d * upper, precision)[0], positiveAtan(n * scale, d * root, precision)[1]];
+    return x < 0 ? negate(out) : out;
+  }
+  const out: Interval = [positiveAtan(root * d, n * scale, precision)[0], positiveAtan(upper * d, n * scale, precision)[1]];
+  return x < 0 ? subtract(pi(precision), out) : out;
+}
+
+/** The ordinary argument order is preserved, including atan2(y,x). */
+export function trigonometric(kind: TrigonometricKind, first: number, second?: number, start = 160): number | null {
+  if (!Number.isFinite(first) || kind === 'atan2' && !Number.isFinite(second)) return null;
+  const x = kind === 'atan2' ? second! : first, y = kind === 'atan2' ? first : 0;
+  if ((kind === 'asin' || kind === 'acos') && Math.abs(x) > 1) return null;
+  if (kind === 'atan2' && y === 0 && x >= 0) return 0;
+  if (x === 0 && kind !== 'atan2') {
+    if (kind === 'cos') return 1;
+    if (kind !== 'acos') return 0;
+  }
+  if (kind === 'acos' && x === 1) return 0;
+  for (let precision = Math.max(64, start);; precision += 80) {
+    let interval: Interval | null;
+    if (kind === 'sin' || kind === 'cos' || kind === 'tan') {
+      const both = reducedSinCos(x, precision);
+      interval = both === null ? null : kind === 'sin' ? both[0] : kind === 'cos' ? both[1] : quotient(both[0], both[1], precision);
+    } else interval = inverse(kind, x, y, precision);
+    if (interval !== null) {
+      const left = rounded(interval[0], -precision), right = rounded(interval[1], -precision);
+      if (left === right) return left;
+    }
+  }
+}

package/src/core/stdlib/series/conditions.ts

@@ -6,7 +6,7 @@
  * happened on this bar", which is the one answer a reader would act on.
  */
 import type { Flag, Flags, Series, StateRecord, Tail, Value } from '../values/index.js';
-import { NONE, fold, queue, slot, tailOf } from '../values/index.js';
+import { ContributionHistory, NONE, fold, slot, tailOf } from '../values/index.js';
 
 /** `barsSince(cond)`: bars since the condition last held, 0 on the bar itself. */
 export function barsSinceStep(state: StateRecord, key: string, cond: Flag): Value {
@@ -37,10 +37,8 @@ export interface Occasion {
  * `valueWhen(cond, src, occurrence)`: `src` as it stood the last time the
  * condition held, or the one before that.
  *
- * Only the `occurrence + 1` most recent hits are kept, so the memory is fixed
- * by the argument rather than by how much history is loaded. A region whose
- * queue grew with the dataset would not be copyable in the sense
- * `compiled-program.md` 2.11 requires.
+ * A later occurrence can name any earlier true event. Immutable history keeps
+ * those values, including absence, while checkpoints share the sealed prefix.
  */
 export function valueWhenStep(
   state: StateRecord,
@@ -49,15 +47,14 @@ export function valueWhenStep(
   occurrence: number,
 ): Value {
   if (!Number.isInteger(occurrence) || occurrence < 0) return NONE;
-  const wanted = occurrence + 1;
-  const hits = queue(state, key);
+  const held = state[key];
+  let hits = held instanceof ContributionHistory ? held : new ContributionHistory();
   if (input.cond === true) {
-    hits.push(input.src);
-    if (hits.length > wanted) hits.shift();
+    hits = hits.append(input.src);
+    state[key] = hits;
   }
-  if (hits.length !== wanted) return NONE;
-  const first = hits[0];
-  return typeof first === 'number' ? first : NONE;
+  if (hits.count <= occurrence) return NONE;
+  return hits.view(occurrence + 1).at(occurrence);
 }
 
 /** `valueWhen(cond, src, occurrence)` as a tail. */

package/src/core/stdlib/series/statistics.ts

@@ -157,6 +157,7 @@ function jointStep(
   const b = ordered((back) => right.at(back), len);
   const m = moments(a, b, len);
   if (want === 'covariance') return result(m.covariance);
+  if (!Number.isFinite(m.varianceA) || !Number.isFinite(m.varianceB)) return NONE;
   const scale = Math.sqrt(m.varianceA) * Math.sqrt(m.varianceB);
   if (scale === 0) return NONE;
   return result(m.covariance / scale);

package/src/core/stdlib/values/history.ts

@@ -0,0 +1,70 @@
+/** Immutable contribution chunks, shared by state checkpoints and independent forks. */
+import type { Value } from './value.js';
+
+const WIDTH = 32;
+
+interface Chunk {
+  readonly values: readonly Value[];
+  readonly prior: Chunk | null;
+}
+
+/** Appending copies at most one short tail, never the contributed prefix. */
+export class ContributionHistory {
+  readonly head: Chunk | null;
+  readonly tail: readonly Value[];
+  readonly count: number;
+
+  constructor(
+    head: Chunk | null = null,
+    tail: readonly Value[] = Object.freeze([]),
+    count = 0,
+  ) {
+    this.head = head;
+    this.tail = tail;
+    this.count = count;
+    Object.freeze(this);
+  }
+
+  append(value: Value): ContributionHistory {
+    const full = this.tail.length === WIDTH;
+    const head = full ? Object.freeze({ values: this.tail, prior: this.head }) : this.head;
+    const tail = Object.freeze(full ? [value] : [...this.tail, value]);
+    return new ContributionHistory(head, tail, this.count + 1);
+  }
+
+  /** Index chunk references once; each subsequent newest-first read is constant work. */
+  view(length: number): ContributionView {
+    const size = Math.min(length, this.count);
+    const chunks: (readonly Value[])[] = [];
+    let remaining = size - this.tail.length;
+    let head = this.head;
+    while (remaining > 0 && head !== null) {
+      chunks.push(head.values);
+      head = head.prior;
+      remaining -= WIDTH;
+    }
+    return new ContributionView(this.tail, chunks, size);
+  }
+}
+
+/** A transient index into the current window. It is not retained in state. */
+export class ContributionView {
+  private readonly tail: readonly Value[];
+  private readonly chunks: readonly (readonly Value[])[];
+  readonly size: number;
+
+  constructor(
+    tail: readonly Value[], chunks: readonly (readonly Value[])[], size: number,
+  ) {
+    this.tail = tail;
+    this.chunks = chunks;
+    this.size = size;
+  }
+
+  at(back: number): Value {
+    if (back < 0 || back >= this.size || !Number.isInteger(back)) return null;
+    if (back < this.tail.length) return this.tail[this.tail.length - 1 - back]!;
+    const before = back - this.tail.length;
+    return this.chunks[Math.floor(before / WIDTH)]![WIDTH - 1 - before % WIDTH]!;
+  }
+}

package/src/core/stdlib/values/index.ts

@@ -3,6 +3,7 @@ export { NONE, at, isLength, isPresent, result } from './value.js';
 
 export type { StateField, StateRecord, StateSlot } from './region.js';
 export { copyState, flag, held, newState, queue, slot } from './region.js';
+export { ContributionHistory, ContributionView } from './history.js';
 
 export type { Tail } from './tail.js';
 export { fold, tailOf } from './tail.js';

package/src/core/stdlib/values/lookback.ts

@@ -30,8 +30,9 @@
  * the length the script asked for rather than by how much history is loaded,
  * and that is the property a live chart actually needs.
  */
-import type { StateField, StateRecord } from './region.js';
-import { newState } from './region.js';
+import type { StateRecord } from './region.js';
+import { newState, slot } from './region.js';
+import { ContributionHistory } from './history.js';
 import type { Value } from './value.js';
 import { NONE, isLength, isPresent, result } from './value.js';
 
@@ -39,7 +40,7 @@ import { NONE, isLength, isPresent, result } from './value.js';
 export interface Lookback {
   /** Advance by one bar. */
   push(value: Value): void;
-  /** True once `len` bars have gone by, present or not: this is warmup. */
+  /** True after the largest observed length's contributions, present or not. */
   filled(): boolean;
   /** True when the lookback is filled and every bar in it has a value. */
   complete(): boolean;
@@ -64,48 +65,28 @@ export interface Lookback {
  */
 export function ring(record: StateRecord, key: string, len: number | null): Lookback {
   const size = len !== null && isLength(len) ? len : 0;
-  const bars = `${key}:q`;
-  const nextKey = `${key}:n`;
-  const seenKey = `${key}:s`;
+  const bars = `${key}:h`;
+  const maximumKey = `${key}:m`;
   const held = record[bars];
-  let items: StateField[];
-  if (Array.isArray(held) && held.length === size) {
-    items = held;
-  } else {
-    items = new Array<StateField>(size).fill(NONE);
-    record[bars] = items;
-    record[nextKey] = 0;
-    record[seenKey] = 0;
-  }
-
-  const count = (name: string): number => {
-    const value = record[name];
-    return typeof value === 'number' ? value : 0;
-  };
-  const index = (back: number): number => {
-    const from = count(nextKey) - 1 - back;
-    return ((from % size) + size) % size;
-  };
+  let history = held instanceof ContributionHistory ? held : new ContributionHistory();
+  const before = record[maximumKey];
+  const maximum = Math.max(typeof before === 'number' ? before : 0, size);
+  record[maximumKey] = maximum;
+  let view = history.view(size);
+  return lookback(size, (value) => {
+    history = history.append(value);
+    record[bars] = history;
+    view = history.view(size);
+  }, () => size > 0 && history.count >= maximum, (back) => view.at(back));
+}
 
+/** The arithmetic is shared so fixed-length accumulation keeps its exact order. */
+function lookback(
+  size: number, push: (value: Value) => void, filled: () => boolean,
+  at: (back: number) => Value,
+): Lookback {
   const lookback: Lookback = {
-    push(value: Value): void {
-      if (size === 0) return;
-      items[count(nextKey)] = value;
-      const next = count(nextKey) + 1;
-      record[nextKey] = next === size ? 0 : next;
-      if (count(seenKey) < size) record[seenKey] = count(seenKey) + 1;
-    },
-
-    filled(): boolean {
-      return size > 0 && count(seenKey) === size;
-    },
-
-    at(back: number): Value {
-      if (size === 0 || back < 0 || back >= size) return NONE;
-      const value = items[index(back)];
-      return typeof value === 'number' ? value : NONE;
-    },
-
+    push, filled, at,
     presentCount(): number {
       let counted = 0;
       for (let back = size - 1; back >= 0; back -= 1) {
@@ -170,6 +151,9 @@ export type Recurrence = (previous: number, value: number) => number;
  * next present bar continues from where the last one left off. The alternatives
  * are worse: consuming absence as zero would drag the average toward nothing,
  * and re-seeding would let one missing bar restart a two hundred bar average.
+ * Missing lengths also freeze it. Readiness tracks all contributions and the
+ * largest observed length, independently from the running value. A valid step
+ * still advances that value while a later, larger length hides its output.
  */
 export function smoothed(
   record: StateRecord,
@@ -178,21 +162,41 @@ export function smoothed(
   value: Value,
   step: Recurrence,
 ): Value {
-  const seed = ring(record, `${key}~`, len);
+  const countKey = `${key}:n`;
+  const maximumKey = `${key}:m`;
+  const historyKey = `${key}~:h`;
   const runningKey = `${key}:r`;
   const startedKey = `${key}:o`;
+  const valid = len !== null && isLength(len);
+  const count = slot(record, countKey, 0) + 1;
+  const maximum = Math.max(slot(record, maximumKey, 0), valid ? len : 0);
+  record[countKey] = count;
+  record[maximumKey] = maximum;
   if (record[startedKey] !== true) {
-    seed.push(value);
-    const mean = seed.mean();
+    const held = record[historyKey];
+    const before = held instanceof ContributionHistory ? held : new ContributionHistory();
+    const history = before.append(value);
+    record[historyKey] = history;
+    if (!valid || count < maximum) return NONE;
+    const view = history.view(len);
+    let total = 0;
+    for (let back = len - 1; back >= 0; back -= 1) {
+      const next = view.at(back);
+      if (!isPresent(next)) return NONE;
+      total += next;
+    }
+    const mean = result(total / len);
     if (!isPresent(mean)) return NONE;
     record[startedKey] = true;
     record[runningKey] = mean;
+    // Checkpoints retain their immutable version; this live state needs only scalars.
+    delete record[historyKey];
     return result(mean);
   }
-  if (!isPresent(value)) return NONE;
+  if (!valid || !isPresent(value)) return NONE;
   const previous = record[runningKey];
   if (typeof previous !== 'number') return NONE;
   const next = step(previous, value);
   record[runningKey] = next;
-  return result(next);
+  return count >= maximum ? result(next) : NONE;
 }

package/src/core/stdlib/values/region.ts

@@ -11,8 +11,8 @@
  * is what 6.2 refuses in as many words: an engine does not re-seed an average
  * from history, it puts back the record it copied.
  *
- * So a region is a flat record of numbers, booleans, strings and fixed length
- * queues, and `copyState` is the mechanical copy. Every function in this
+ * So a region is a flat record of scalars, bounded mutable queues and immutable
+ * contribution history, and `copyState` is the mechanical copy. Every function in this
  * library is written against one, and the tail form in `tail.ts` is the same
  * step over a region nobody else can reach. That is what lets the one
  * implementation serve both a library call folded over a series and an engine
@@ -23,11 +23,13 @@
  * of them.
  */
 
-/** One field of a state region. A queue is the one compound form 2.11 allows. */
+import type { ContributionHistory } from './history.js';
+
+/** One scalar field of a state region. */
 export type StateField = number | boolean | string | null;
 
 /** What a single key holds. */
-export type StateSlot = StateField | StateField[];
+export type StateSlot = StateField | StateField[] | ContributionHistory;
 
 /** A state region: a flat record, copyable without knowing what owns it. */
 export type StateRecord = Record<string, StateSlot | undefined>;
@@ -37,7 +39,7 @@ export function newState(): StateRecord {
   return {};
 }
 
-/** The mechanical copy 2.11 asks for: one level, with queues cloned. */
+/** Mutable queues are cloned; immutable history versions are safely shared. */
 export function copyState(record: StateRecord): StateRecord {
   const out: StateRecord = {};
   for (const key of Object.keys(record)) {

package/src/core/stdlib/volatility/measures.ts

@@ -9,6 +9,7 @@
 import type { Bar, Series, StateRecord, Tail, Value } from '../values/index.js';
 import { NONE, fold, isPresent, result, tailOf } from '../values/index.js';
 import { extremeStep, historyStep, sumStep } from '../series/index.js';
+import { log, log10 } from '../maths/index.js';
 
 import type { Gap } from './range.js';
 import { gapOf, trueRangeOf } from './range.js';
@@ -41,9 +42,10 @@ export function chopStep(
   if (len === null) return NONE;
   if (!isPresent(distance) || !isPresent(upper) || !isPresent(lower)) return NONE;
   const span = upper - lower;
-  const scale = Math.log10(len);
-  if (!(span > 0) || !(distance > 0) || scale === 0) return NONE;
-  return result((100 * Math.log10(distance / span)) / scale);
+  const scale = log10(len);
+  if (!(span > 0) || !(distance > 0) || !isPresent(scale) || scale === 0) return NONE;
+  const travelled = log10(distance / span);
+  return isPresent(travelled) ? result((100 * travelled) / scale) : NONE;
 }
 
 /** `chop(len)` as a tail. */
@@ -78,7 +80,7 @@ export function hvStep(
   const previous = historyStep(state, `${key}h`, value, 1);
   let logReturn: Value = NONE;
   if (isPresent(value) && isPresent(previous) && value > 0 && previous > 0) {
-    logReturn = result(Math.log(value / previous));
+    logReturn = log(value / previous);
   }
   const deviation = stdevStep(state, `${key}q`, logReturn, len, false);
   if (!isPresent(deviation) || periodsPerYear === null || !(periodsPerYear > 0)) return NONE;

package/src/core/version/version.generated.ts

@@ -4,7 +4,7 @@
 // spec/compiled-program.md, so neither can drift from the thing it names.
 
 /** This build's package version. The release refuses to publish unless the tag, the manifest and this agree. */
-export const VERSION = "0.6.0";
+export const VERSION = "0.7.0";
 
 /**
  * The compiled program format this compiler emits.