EML-Math

EML Mathematics — a universal real-valued foundation for elementary mathematics, built from a single binary operator.

Repo: https://github.com/andrewkwatts-maker/EML-Math

Created by Andrew K Watts. Based on the EML Sheffer operator established by Andrzej Odrzywolek: arXiv:2603.21852v2 (CC BY 4.0).

The core idea

A single binary operator generates every elementary function:

eml(x, y) = exp(x) − ln(y)

This is the EML Sheffer operator — the continuous analog of the NAND gate for Boolean logic. From it the 36 standard elementary functions (+, −, ×, /, exp, ln, sin, cos, tan, π, e, …) can all be reconstructed as composed expression trees.

EMLPoint is the operator's computation node — simultaneously a mathematical state and a composable expression-tree leaf:

from eml_math import EMLPoint
import math

EMLPoint(1, 1).tension()                                  # e   = eml(1, 1)
EMLPoint(2, 1).tension()                                  # exp(2)
EMLPoint(1, EMLPoint(EMLPoint(1, math.e), 1)).tension()   # ln(e) = 1.0

What's new in v2.x

The 2.x line keeps the same scope (pure-EML universal-math toolkit) but sharpens correctness and readability of the pure-EML LaTeX renderer. Highlights since v1.x:

• Numerical validation of every famous equation — 1,000 random variable combinations × 47 entries in FAMOUS × EMLEvaluator ≡ a reference Python form, 46,000+ comparisons in ~2 s. See tests/test_famous_random.py.
• pow(x, n) is now mathematically correct for non-literal exponents — emits exp(exp(ln(n) + ln(ln(x)))) instead of the earlier incorrect exp(add(ln(n), ln(x))) (which collapsed to n·x). Fixes (x-1)**2 → (x-1)^2 after expand_numeric_constants.
• Pure-EML LaTeX recogniser picks up 1/x, −ln x, a − b, a + b, x^c (including the double-exp pow shape) directly from the pure-EML structure, in addition to the existing e^x, ln x, −x rules.
• Algebraic simplifications in the renderer: ln(1) → 0, e^0 → 1, x + 0 = x, 0 − x = −x, double-negation cancellation, exp(ln y) = y. Hover-on-sub-expression reads as math instead of literal EML scaffolding.
• BOTTOM (⊥) renders as 0 — readable, not an abstract symbol. The longer eml(⊥, …) shapes are still consumed by the pattern matchers so the change only surfaces in rare compound expressions.
• Width-aware tidy-tree layout — compute_layout accepts a width_for_label callback; the contour walker reserves the actual rendered box footprint per node so wide eml labels can't collide with narrow 0/1 stubs.
• Layout overlap fix for deep cousins — the contour walker now propagates n.shift + n.mod (not just n.mod) when descending, so descendants of every sibling live in the same frame as descendants of earlier siblings.

The slim core

eml-math stays the pure-EML universal-math toolkit: the operator, expression trees, symbolic regression, the elementary-function operator library, the famous-equations registry, and the flow-diagram renderer. Nothing else.

Algebras and physics are now in eml-spectral — the sister package, v1.0.0 release. EML-tree representations of Clifford algebras, octonions, exceptional algebras (E7/E8/Freudenthal), Lorentz-invariant spacetime ops, named GR metrics, and the spectral-flow operator Φ all live there. Same zero-deps philosophy, optional Rust acceleration, optional C API.

pip install eml-spectral   # transitively installs eml-math >= 1.2.0

Installation

pip install eml-math               # core
pip install eml-math[ext]          # + numpy, sympy
pip install eml-math[precision]    # + mpmath
pip install eml-math[dev]          # + pytest, ruff, mypy

For the algebras / physics layer:

pip install eml-spectral
# transitively pulls in eml-math >= 1.2.0

Companion app — eml_math.Launch()

The pip wheel ships with a one-call launcher for the EML-Math-App — a KivyMD visual explorer for the library. It builds the expression tree live as you type, renders Normal-math / EML-primitive LaTeX previews, draws the EML graph with hover-per-node sub-expression preview, lets you copy any sub-tree in Normal / EML / LaTeX / Python / JSON, and exports PNG at any DPI.

import eml_math
eml_math.Launch()        # finds or clones EML-Math-App, runs it

On first call the launcher looks for a sibling EML-Math-App checkout next to your eml-math source directory; otherwise it clones the matching version tag from GitHub into ~/.eml-math-app and pip install -e it. Subsequent calls reuse the cached checkout.

The app needs the Kivy stack:

pip install eml-math-app   # installs Kivy + KivyMD too
eml-math-app               # CLI entry point if you'd rather skip Python

Public API reference

Every name below is importable directly from eml_math.

Every symbol has a Python docstring — help(eml_math.Searcher), help(eml_math.decompress), etc. read the inline documentation.

Quickstart — symbolic regression

Searcher finds an EML expression that matches a target numeric value:

from eml_math import Searcher

s = Searcher(target=2.71828)
result = s.search()
print(result.formula)      # 'eml(1, 1)'   (i.e. e)

compress and recognize go in the other direction:

from eml_math import compress, recognize

print(recognize(3.14159))         # ('π', 3.141592653589793, 0.0)
print(compress("exp(x) - ln(y)")) # SearchResult: matches the EML primitive itself

Generating equation graphs (SVG / PNG / PDF / HTML)

Every formula in the famous-equations registry can be rendered to SVG / PNG / PDF / HTML directly. The same primitives work on any EML expression you build.

One-liner from a famous equation

from eml_math.famous import get

einstein = get("einstein_e_mc2")

# Bytes → write yourself
open("einstein.svg", "w", encoding="utf-8").write(einstein.flow_svg(width=900, height=600))
open("einstein.png", "wb").write(einstein.flow_png(width=900, height=600))
open("einstein.pdf", "wb").write(einstein.flow_pdf(width=900, height=600))

# Self-contained interactive HTML (UMD bundle inlined)
open("einstein.html", "w", encoding="utf-8").write(einstein.parse().flow_html(width=900, height=600))

Direct from an EML expression

from eml_math import parse_eml_tree

tree = parse_eml_tree(
    "EML: ops.sqrt(ops.add(ops.pow(eml_vec('a'), eml_scalar(2.0)), "
    "ops.pow(eml_vec('b'), eml_scalar(2.0))))",
    pure_eml=True,
)

open("pythagoras.svg", "w", encoding="utf-8").write(tree.flow_svg(width=1200, height=900))
open("pythagoras.png", "wb").write(tree.flow_png(width=1200, height=900))

Render-time options

Useful kwargs accepted by flow_svg / flow_png / flow_pdf:

For a different visual style, post-process the layout JSON before rendering — see the next section.

Layout-intermediate JSON pipeline (this is how styles are applied)

For finer control — or to render the same geometry from JavaScript / post-process it programmatically — go through the layout-intermediate form. to_layout returns a JSON-serialisable dict; the post-processes return a transformed copy; render_layout_svg / render_layout_png / render_layout_pdf produce final output.

The two named styles in the gallery are post-process pipelines applied to the same to_layout(tree) output:

import json
from eml_math import (
    to_layout, render_layout_svg, render_layout_png, render_layout_pdf,
    organic_layout, fit_to_canvas,
)

layout = to_layout(tree, width=1200, height=900)

# Apply organic style
layout = organic_layout(layout,
                        branch_angle=24.0, length_scale=44.0,
                        length_decay=0.97, min_length=24.0,
                        branch_jitter=0.12, trunk_pull=0.35,
                        balance="subtree_size")
layout = fit_to_canvas(layout, margin=20)

# Inspect / save the geometry before rendering
with open("pythagoras_layout.json", "w", encoding="utf-8") as f:
    json.dump(layout, f, indent=2)

# Render to whatever you need
open("pythagoras.svg", "w", encoding="utf-8").write(render_layout_svg(layout))
open("pythagoras.png", "wb").write(render_layout_png(layout))
open("pythagoras.pdf", "wb").write(render_layout_pdf(layout))

Knobs on organic_layout worth knowing:

• length_decay (default 0.97) — how aggressively branches shrink per generation. Closer to 1.0 keeps deep leaves spaciously apart.
• min_length (default 22) — floor on per-generation branch length. Even after length_decay reduces the geometric length, no branch shrinks below this. Set to 0 for the pure geometric decay look.
• trunk_pull (default 0.35) — how strongly each child's growing direction is pulled back toward the global trunk axis. Prevents long chains from curling into a tight spiral.
• balance (default "subtree_size") — assigns the larger subtree to the outside of each fork so the tree visually balances.

Compact JSON for the tree itself

The expression tree (independent of layout) round-trips through a tiny JSON-friendly array. Useful for storage, transport, or rendering on the JS side without re-parsing the EML string:

import json
from eml_math import to_compact, from_compact

compact = to_compact(tree)             # list of nested arrays
encoded = json.dumps(compact)          # plain JSON, ~7× smaller than the dict form
rebuilt = from_compact(json.loads(encoded))   # exact structural round-trip

Browser-side rendering (eml_flow.js)

eml_math.web ships a UMD bundle that renders the same layout JSON in the browser. Two ways to use it:

from eml_math import flow_html, get_flow_js, FLOW_JS_PATH

# Self-contained HTML (the JS bundle is inlined — open the file, no server needed)
open("einstein.html", "w", encoding="utf-8").write(
    tree.flow_html(width=900, height=600)
)

# Or grab the bundle to host yourself
open("static/eml_flow.js", "w", encoding="utf-8").write(get_flow_js())
print("Bundle path on disk:", FLOW_JS_PATH)

In your own page:

<script src="eml_flow.js"></script>
<script>
  const layout = /* JSON dumped from to_layout(...) */;
  document.body.innerHTML = EMLFlow.renderSVG(layout);
</script>

Batch generation — the famous-equations gallery

To regenerate every equation in the registry across all styles (produces formal/, gentle/, organic/, tree/ folders with PNG + PDF for each, plus a self-contained index.html):

python examples/famous_gallery.py [output_dir]   # default: ./famous_gallery

Output structure:

famous_gallery/
├── index.html        # browse every style of every equation
├── formal/
│   ├── png/einstein_e_mc2.png
│   └── pdf/einstein_e_mc2.pdf
├── organic/   (same layout)
├── gentle/    (same layout)
└── tree/      (same layout)

Famous-equations registry

from eml_math import all_famous_equations, get_famous

print([eq.name for eq in all_famous_equations()])
# ['Pythagoras', 'Euler identity', 'E = mc²', 'Schrödinger', ...]

einstein = get_famous("einstein_e_mc2")
print(einstein.eml_formula)    # the EML-tree form

Rust accelerator (optional)

The wheel bundles a Rust extension exposing Rayon-parallel batch operators (exp_n, ln_n, add_n, mul_n, sin_n, tension_n, …):

from eml_math.eml_core import tension_n
import numpy as np

xs = np.linspace(0, 5, 1_000_000)
ys = np.ones_like(xs)
out = tension_n(xs.tolist(), ys.tolist())   # parallel

A C/C++/Rust shared-library API lives under c_api/ for embedding the operator into other languages. Build it with:

cargo build --release -p eml_c_api

Project layout

eml-math/                           # this repo
├─ src/eml_math/                    # Python sources (the slim core)
│  ├─ render/                       # Abstracted renderer pipeline
│  │  ├─ layout.py                  # Reingold-Tilford tidy-tree
│  │  ├─ edges.py                   # straight / curve / spline path generators
│  │  ├─ palette.py                 # palette helpers
│  │  └─ renderers/                 # SVG, HTML, PNG, PDF — pluggable Renderer protocol
│  └─ ...
├─ rust/eml_core/                   # Rust accelerator (PyO3 module)
├─ c_api/                           # C/C++/Rust shared-library bindings
├─ docs/                            # Static-HTML site (index/api/guide/concepts)
└─ tests/                           # pytest suite (2077 tests, 0 required deps)

License

MIT, © Andrew K Watts.