monogate 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# monogate
+
+> A single binary operator that generates all elementary functions.
+
+```
+eml(x, y) = exp(x) − ln(y)
+```
+
+From this one operator and the constant `1`, every elementary arithmetic function can be constructed as a pure expression tree. Implementation of:
+
+> **"All elementary functions from a single operator"**
+> Andrzej Odrzywołek, Jagiellonian University
+> [arXiv:2603.21852v2](https://arxiv.org/abs/2603.21852) · CC BY 4.0
+
+Live explorer: **https://monogate.dev** (or your deployed URL)
+
+---
+
+## Install
+
+```bash
+npm install monogate
+```
+
+## Usage
+
+```js
+import { op, exp, ln, add, mul, pow, E, ZERO } from "monogate";
+
+// The core operator
+op(1, 1);        // e        (exp(1) − ln(1))
+op(1, op(op(1,1), 1));  // 0   (e − e = 0)
+
+// Derived functions — all built from eml + 1
+exp(3);          // e³
+ln(Math.E);      // 1
+add(2, 3);       // 5
+mul(4, 5);       // 20
+pow(2, 10);      // 1024
+```
+
+## API
+
+All functions are pure and stateless. Domain constraints are noted — violating them produces `NaN` or `±Infinity`.
+
+### Core
+
+| Export | Formula | Nodes | Depth |
+|--------|---------|-------|-------|
+| `op(x, y)` | `exp(x) − ln(y)` | — | — |
+| `E` | `op(1,1)` | 1 | 1 |
+| `ZERO` | `op(1, op(op(1,1), 1))` | 3 | 3 |
+| `NEG_ONE` | `op(ZERO, op(2,1))` | 5 | 4 |
+
+### Elementary functions
+
+| Export | Math | Domain | Nodes | Depth |
+|--------|------|--------|-------|-------|
+| `exp(x)` | eˣ | ℝ | 1 | 1 |
+| `ln(x)` | ln x | x > 0 | 3 | 3 |
+| `sub(x, y)` | x − y | x > 0 | 5 | 4 |
+| `neg(y)` | −y | ℝ (two-regime) | 9 | 5 |
+| `add(x, y)` | x + y | ℝ | 11 | 6 |
+| `mul(x, y)` | x × y | x,y > 0 | 13 | 7 |
+| `div(x, y)` | x / y | x,y > 0 | 15 | 8 |
+| `pow(x, n)` | xⁿ | x > 0 | 15 | 8 |
+| `recip(x)` | 1/x | x > 0 | 5 | 4 |
+
+The **depth** ranking of elementary functions by EML tree depth is new to mathematics.
+
+### `IDENTITIES`
+
+An array of `{ name, emlForm, nodes, depth, status }` records — useful for building explorers or documentation.
+
+## Open challenges
+
+These functions have no known EML construction:
+
+- **sin x** — no construction found
+- **cos x** — no construction found
+- **π** — no construction as a closed EML expression
+- **i** (√−1) — requires extending the domain
+
+Pull requests welcome. If you crack one, open an issue — it's publishable.
+
+## How it works
+
+The grammar is just two production rules:
+
+```
+S → 1
+S → eml(S, S)
+```
+
+Any expression built from this grammar computes some value. The paper proves that the specific compositions above equal the named functions exactly (not approximately). Floating-point errors are at machine epsilon (`< 1e-13`).
+
+The `neg` function uses a two-regime construction to avoid overflow:
+- **y ≤ 0**: tower formula via `exp(eʸ)` — stable because `eʸ ≤ 1`
+- **y > 0**: shift formula — computes `exp(y+1)` instead of a tower
+
+## License
+
+MIT — see [LICENSE](./LICENSE). The underlying mathematics is CC BY 4.0 per the original paper.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "monogate",
+  "version": "0.1.0",
+  "description": "A single binary operator eml(x,y) = exp(x) − ln(y) that generates all elementary functions. Implementation of arXiv:2603.21852 (Odrzywołek, 2026).",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "mathematics",
+    "eml",
+    "elementary-functions",
+    "algebra",
+    "monogate",
+    "exp-minus-log"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/monogate.git"
+  },
+  "homepage": "https://monogate.dev",
+  "bugs": {
+    "url": "https://github.com/your-username/monogate/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/complex.js

@@ -0,0 +1,212 @@
+/**
+ * complex.js — Immutable complex number type for the monogate EML system.
+ *
+ * This file provides standard ℂ arithmetic. It does NOT use EML grammar
+ * constructions — it is the numeric substrate for complex_eml.js.
+ *
+ * All transcendental functions use the PRINCIPAL BRANCH of ln:
+ *   arg(z) ∈ (−π, π]   (branch cut on the negative real axis)
+ *
+ * Precision: results accurate to machine epsilon (~1e-15) away from branch
+ * cuts. Near the negative real axis (|Im| < 1e-12, Re < 0) arg() is subject
+ * to the sign-of-zero ambiguity in IEEE 754 — this is the source of the
+ * floating-point ±iπ sign in the EML escape-from-reals chain.
+ *
+ * @module monogate/complex
+ */
+
+export class Complex {
+  /**
+   * @param {number} re  real part
+   * @param {number} im  imaginary part (default 0)
+   */
+  constructor(re, im = 0) {
+    this.re = re;
+    this.im = im;
+    Object.freeze(this);
+  }
+
+  // ─── Factories ──────────────────────────────────────────────────────────────
+
+  /** @param {number} re @param {number} [im=0] @returns {Complex} */
+  static of(re, im = 0) { return new Complex(re, im); }
+
+  /**
+   * r · exp(iθ)
+   * @param {number} r    magnitude (must be ≥ 0)
+   * @param {number} theta argument in radians
+   * @returns {Complex}
+   */
+  static fromPolar(r, theta) {
+    return new Complex(r * Math.cos(theta), r * Math.sin(theta));
+  }
+
+  /** @param {number} x @returns {Complex} */
+  static real(x) { return new Complex(x, 0); }
+
+  // ─── Arithmetic ─────────────────────────────────────────────────────────────
+
+  /** @param {Complex} other @returns {Complex} */
+  add(other) {
+    return new Complex(this.re + other.re, this.im + other.im);
+  }
+
+  /** @param {Complex} other @returns {Complex} */
+  sub(other) {
+    return new Complex(this.re - other.re, this.im - other.im);
+  }
+
+  /**
+   * (a + bi)(c + di) = (ac − bd) + (ad + bc)i
+   * @param {Complex} other @returns {Complex}
+   */
+  mul(other) {
+    return new Complex(
+      this.re * other.re - this.im * other.im,
+      this.re * other.im + this.im * other.re,
+    );
+  }
+
+  /**
+   * Division via conjugate: this / other = (this · conj(other)) / |other|²
+   * @param {Complex} other @returns {Complex}
+   */
+  div(other) {
+    const d = other.absSquared();
+    return new Complex(
+      (this.re * other.re + this.im * other.im) / d,
+      (this.im * other.re - this.re * other.im) / d,
+    );
+  }
+
+  /** Additive inverse. @returns {Complex} */
+  neg() { return new Complex(-this.re, -this.im); }
+
+  /** Complex conjugate. @returns {Complex} */
+  conj() { return new Complex(this.re, -this.im); }
+
+  /**
+   * Multiplicative inverse: 1/z = conj(z) / |z|²
+   * @returns {Complex}
+   */
+  recip() {
+    const d = this.absSquared();
+    return new Complex(this.re / d, -this.im / d);
+  }
+
+  /**
+   * Scale by a real scalar.
+   * @param {number} r @returns {Complex}
+   */
+  scale(r) { return new Complex(this.re * r, this.im * r); }
+
+  // ─── Transcendental (principal branch) ──────────────────────────────────────
+
+  /**
+   * exp(z) = e^re · (cos(im) + i·sin(im))
+   * @returns {Complex}
+   */
+  exp() {
+    return Complex.fromPolar(Math.exp(this.re), this.im);
+  }
+
+  /**
+   * Principal branch of ln(z): ln|z| + i·arg(z), arg ∈ (−π, π].
+   * Branch cut: negative real axis.
+   * @returns {Complex}
+   * @throws {RangeError} if z = 0
+   */
+  ln() {
+    if (this.isZero()) throw new RangeError("ln_c: argument must be non-zero");
+    return new Complex(Math.log(this.abs()), this.arg());
+  }
+
+  /**
+   * Principal-value power: z^w = exp(w · ln(z))
+   * @param {Complex} w @returns {Complex}
+   */
+  pow(w) {
+    return this.ln().mul(w).exp();
+  }
+
+  // ─── Measurement ────────────────────────────────────────────────────────────
+
+  /**
+   * |z| = hypot(re, im)  — uses Math.hypot to avoid overflow on large components.
+   * @returns {number}
+   */
+  abs() { return Math.hypot(this.re, this.im); }
+
+  /**
+   * arg(z) = atan2(im, re) ∈ (−π, π]
+   * @returns {number}
+   */
+  arg() { return Math.atan2(this.im, this.re); }
+
+  /** |z|² = re² + im²  (cheaper than abs() when only comparing magnitudes). @returns {number} */
+  absSquared() { return this.re * this.re + this.im * this.im; }
+
+  // ─── Predicates ─────────────────────────────────────────────────────────────
+
+  /** @param {number} [tol=0] @returns {boolean} */
+  isZero(tol = 0) { return this.abs() <= tol; }
+
+  /** @param {number} [tol=0] @returns {boolean} */
+  isReal(tol = 0) { return Math.abs(this.im) <= tol; }
+
+  /** @param {number} [tol=0] @returns {boolean} */
+  isPureImaginary(tol = 0) {
+    return Math.abs(this.re) <= tol && !this.isZero(tol);
+  }
+
+  // ─── Equality ───────────────────────────────────────────────────────────────
+
+  /**
+   * Component-wise approximate equality.
+   * @param {Complex} other
+   * @param {number} [tol=1e-10]
+   * @returns {boolean}
+   */
+  equals(other, tol = 1e-10) {
+    return Math.abs(this.re - other.re) <= tol && Math.abs(this.im - other.im) <= tol;
+  }
+
+  // ─── Output ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Human-readable form. Treats components with |value| < 1e-12 as zero.
+   * Examples: "3", "-2i", "1+4i", "2.718-3.14i"
+   * @returns {string}
+   */
+  toString() {
+    const fmt = (v) => {
+      const s = parseFloat(v.toPrecision(10)).toString();
+      return s;
+    };
+    const EPS = 1e-12;
+    const reZero = Math.abs(this.re) < EPS;
+    const imZero = Math.abs(this.im) < EPS;
+
+    if (reZero && imZero) return "0";
+    if (imZero) return fmt(this.re);
+    if (reZero) {
+      if (Math.abs(this.im - 1) < EPS) return "i";
+      if (Math.abs(this.im + 1) < EPS) return "-i";
+      return `${fmt(this.im)}i`;
+    }
+    const sign = this.im < 0 ? "-" : "+";
+    const absIm = Math.abs(this.im);
+    const imStr = Math.abs(absIm - 1) < EPS ? "i" : `${fmt(absIm)}i`;
+    return `${fmt(this.re)}${sign}${imStr}`;
+  }
+
+  /**
+   * Fixed-decimal form for test output.
+   * @param {number} digits @returns {string}
+   */
+  toFixed(digits) {
+    return `${this.re.toFixed(digits)} + ${this.im.toFixed(digits)}i`;
+  }
+}
+
+export default Complex;

package/src/complex.test.js

@@ -0,0 +1,206 @@
+import { describe, it, expect } from "vitest";
+import { Complex } from "./complex.js";
+
+const TIGHT = 1e-14; // direct arithmetic
+const TOL   = 1e-10; // EML chains
+
+const near = (a, b, tol = TIGHT) => Math.abs(a - b) <= tol;
+
+describe("Complex — factories", () => {
+  it("of(re, im)", () => {
+    const z = Complex.of(3, -4);
+    expect(z.re).toBe(3);
+    expect(z.im).toBe(-4);
+  });
+
+  it("of(re) defaults im to 0", () => {
+    expect(Complex.of(5).im).toBe(0);
+  });
+
+  it("fromPolar(r, theta)", () => {
+    const z = Complex.fromPolar(2, Math.PI / 2);
+    expect(near(z.re, 0)).toBe(true);
+    expect(near(z.im, 2)).toBe(true);
+  });
+
+  it("real(x) alias", () => {
+    const z = Complex.real(7);
+    expect(z.re).toBe(7);
+    expect(z.im).toBe(0);
+  });
+
+  it("is frozen / immutable", () => {
+    const z = Complex.of(1, 2);
+    expect(() => { z.re = 99; }).toThrow();
+  });
+});
+
+describe("Complex — arithmetic", () => {
+  const a = Complex.of(3, 4);
+  const b = Complex.of(1, -2);
+
+  it("add", () => {
+    const r = a.add(b);
+    expect(r.re).toBe(4);
+    expect(r.im).toBe(2);
+  });
+
+  it("sub", () => {
+    const r = a.sub(b);
+    expect(r.re).toBe(2);
+    expect(r.im).toBe(6);
+  });
+
+  it("mul: (3+4i)(1-2i) = 11-2i", () => {
+    const r = a.mul(b);
+    expect(r.re).toBe(11);
+    expect(r.im).toBe(-2);
+  });
+
+  it("div: (3+4i)/(1-2i) = -1+2i", () => {
+    const r = a.div(b);
+    expect(near(r.re, -1)).toBe(true);
+    expect(near(r.im,  2)).toBe(true);
+  });
+
+  it("neg", () => {
+    expect(a.neg().re).toBe(-3);
+    expect(a.neg().im).toBe(-4);
+  });
+
+  it("conj", () => {
+    expect(a.conj().re).toBe(3);
+    expect(a.conj().im).toBe(-4);
+  });
+
+  it("recip: 1/(3+4i) = 3/25 - 4/25·i", () => {
+    const r = a.recip();
+    expect(near(r.re, 3/25)).toBe(true);
+    expect(near(r.im, -4/25)).toBe(true);
+  });
+
+  it("scale", () => {
+    const r = a.scale(2);
+    expect(r.re).toBe(6);
+    expect(r.im).toBe(8);
+  });
+
+  it("z · z.recip() ≈ 1", () => {
+    const r = a.mul(a.recip());
+    expect(near(r.re, 1)).toBe(true);
+    expect(near(r.im, 0)).toBe(true);
+  });
+});
+
+describe("Complex — measurement", () => {
+  it("abs of 3+4i = 5", () => {
+    expect(near(Complex.of(3, 4).abs(), 5)).toBe(true);
+  });
+
+  it("arg of i = π/2", () => {
+    expect(near(Complex.of(0, 1).arg(), Math.PI / 2)).toBe(true);
+  });
+
+  it("arg of −1 = π", () => {
+    expect(near(Complex.of(-1, 0).arg(), Math.PI)).toBe(true);
+  });
+
+  it("absSquared", () => {
+    expect(Complex.of(3, 4).absSquared()).toBe(25);
+  });
+});
+
+describe("Complex — transcendental", () => {
+  it("exp(0) = 1", () => {
+    const r = Complex.of(0).exp();
+    expect(near(r.re, 1)).toBe(true);
+    expect(near(r.im, 0)).toBe(true);
+  });
+
+  it("exp(1) = e", () => {
+    expect(near(Complex.of(1).exp().re, Math.E)).toBe(true);
+  });
+
+  it("exp(iπ) = −1  (Euler's identity)", () => {
+    const r = Complex.of(0, Math.PI).exp();
+    expect(near(r.re, -1)).toBe(true);
+    expect(near(r.im,  0)).toBe(true);
+  });
+
+  it("ln(e) = 1", () => {
+    const r = Complex.of(Math.E).ln();
+    expect(near(r.re, 1)).toBe(true);
+    expect(near(r.im, 0)).toBe(true);
+  });
+
+  it("ln(−1) = iπ  (principal branch)", () => {
+    const r = Complex.of(-1).ln();
+    expect(near(r.re, 0)).toBe(true);
+    expect(near(r.im, Math.PI)).toBe(true);
+  });
+
+  it("ln(i) = iπ/2", () => {
+    const r = Complex.of(0, 1).ln();
+    expect(near(r.re, 0)).toBe(true);
+    expect(near(r.im, Math.PI / 2)).toBe(true);
+  });
+
+  it("exp(ln(z)) = z for various z", () => {
+    const zs = [
+      Complex.of(2, 3),
+      Complex.of(-1, 1),
+      Complex.of(0.5, -0.7),
+    ];
+    for (const z of zs) {
+      const r = z.ln().exp();
+      expect(near(r.re, z.re)).toBe(true);
+      expect(near(r.im, z.im)).toBe(true);
+    }
+  });
+
+  it("ln(0) throws", () => {
+    expect(() => Complex.of(0).ln()).toThrow(RangeError);
+  });
+
+  it("pow: i² = −1", () => {
+    const i = Complex.of(0, 1);
+    const r = i.pow(Complex.of(2));
+    expect(near(r.re, -1)).toBe(true);
+    expect(near(r.im,  0)).toBe(true);
+  });
+});
+
+describe("Complex — predicates and equality", () => {
+  it("isZero", () => {
+    expect(Complex.of(0, 0).isZero()).toBe(true);
+    expect(Complex.of(1e-15).isZero(1e-14)).toBe(true);
+    expect(Complex.of(1).isZero()).toBe(false);
+  });
+
+  it("isReal", () => {
+    expect(Complex.of(5).isReal()).toBe(true);
+    expect(Complex.of(5, 1e-13).isReal(1e-12)).toBe(true);
+    expect(Complex.of(5, 1).isReal()).toBe(false);
+  });
+
+  it("isPureImaginary", () => {
+    expect(Complex.of(0, 3).isPureImaginary()).toBe(true);
+    expect(Complex.of(1, 3).isPureImaginary()).toBe(false);
+    expect(Complex.of(0).isPureImaginary()).toBe(false);
+  });
+
+  it("equals with tolerance", () => {
+    expect(Complex.of(1, 2).equals(Complex.of(1 + 1e-11, 2))).toBe(true);
+    expect(Complex.of(1, 2).equals(Complex.of(1 + 1e-9, 2))).toBe(false);
+  });
+});
+
+describe("Complex — toString", () => {
+  it("real-only", () => expect(Complex.of(3).toString()).toBe("3"));
+  it("imaginary-only", () => expect(Complex.of(0, 2).toString()).toBe("2i"));
+  it("pure i", () => expect(Complex.of(0, 1).toString()).toBe("i"));
+  it("negative imaginary", () => expect(Complex.of(0, -1).toString()).toBe("-i"));
+  it("a+bi", () => expect(Complex.of(3, 4).toString()).toBe("3+4i"));
+  it("a-bi", () => expect(Complex.of(3, -4).toString()).toBe("3-4i"));
+  it("zero", () => expect(Complex.of(0, 0).toString()).toBe("0"));
+});