Eshkol is a Scheme-based programming language that unifies functional programming with native automatic differentiation, providing a mathematically rigorous foundation for gradient-based optimization, numerical simulation, and machine learning research. Built on Homotopy Type Theory foundations and compiled to native code via LLVM, Eshkol delivers mathematical correctness and deterministic performance without sacrificing the elegance of homoiconic Lisp syntax.
v1.3.4-evolve — a resident-correctness release. Automatic per-iteration
memory reclamation now matches explicit with-region even for loops that mutate
persistent state; parallel-map is race-free for collection-valued closures;
gradients are exact through every callable form (indirect and curried, no
finite-difference fallback); printed floats round-trip (R7RS 6.2.6); and the
strict type checker accepts idiomatic dynamic-but-validated code. It also lands
the high-precision numerics wave (Ozaki-II exact and reduced-precision GEMM
tiers, a mixed-precision linear solver, and a native 128-bit integer type
i128), a Moonlab v1.2.0 quantum pin, and full hosted-VM tensor-matmul parity.
The full release-gate record and exact platform matrix are in
RELEASE_NOTES.md; see
ANNOUNCEMENT.md for the full release story.
Full documentation index — every guide, reference, and design doc in one place.
Because calculus should be a compiler primitive, not a library.
;; Train a linear model: learn y = 2x from data
;; The compiler differentiates the loss function automatically.
(define training-data '((1.0 2.0) (2.0 4.0) (3.0 6.0) (4.0 8.0) (5.0 10.0)))
(define (predict w x) (* w x))
(define (loss w)
(fold-left (lambda (total pair)
(let ((error (- (predict w (car pair)) (cadr pair))))
(+ total (* error error))))
0.0 training-data))
;; Gradient descent — the compiler computes d(loss)/dw
(define (train w lr steps)
(if (= steps 0) w
(train (- w (* lr (derivative loss w))) lr (- steps 1))))
(display (train 0.0 0.01 200)) ;; => 2.0 (learned w = 2)Eshkol brings mathematical computing to Lisp and delivers what other languages promise:
- True automatic differentiation - Not numerical approximation. Exact symbolic, forward-mode, and reverse-mode AD with full vector calculus (∇, ∇·, ∇×, ∇²)
- Zero-overhead abstractions - Type-level proofs erase at compile time. Arena allocation is O(1). No runtime penalties for safety
- Deterministic performance - No garbage collector means no unpredictable pauses. Critical for real-time systems and production ML
- Native compilation - LLVM backend generates machine code competitive with hand-written C while preserving high-level expressiveness
- Web platform - Compiles to WebAssembly with 59 DOM bindings. The project website is itself written in Eshkol. AD works in the browser via dual number propagation through a 64-opcode core bytecode VM
- Consciousness engine - 22 compiled primitives: logic programming (unification, knowledge bases), active inference (factor graphs, belief propagation, free energy), and global workspace theory (softmax competition, content broadcasting)
- Mathematical rigor - HoTT type foundations ensure correctness properties are mathematically provable, not just tested
No installation required. Visit eshkol.ai to try Eshkol in your browser:
- Playground — Full REPL with a 64-opcode core VM and 555+ built-in functions, running in WebAssembly
- Learn — interactive textbook with runnable code examples, plus 27 in-depth tutorials
- Examples — 11 complete programs you can run instantly (AD, neural networks, ODE solving, logic programming)
The website itself is written in Eshkol (1,500+ lines) and compiles to a 220,306-byte (about 215 KiB) WASM binary. Automatic differentiation works in the browser:
(derivative (lambda (x) (* x x x)) 2.0) ;; => 12.0 (3x² at x=2)Eshkol's AD is a compiler primitive: exact forward-mode, reverse-mode, and
symbolic differentiation out of the box, plus — new in v1.3.0-evolve — an
arbitrary-order Taylor-tower engine. (derivative-n f x k) and
(taylor f x k) give you the k-th derivative or the full coefficient
series for any k, exactly (arbitrary-precision bignum/rational, not
floating-point) when the math supports it, with validated interval-remainder
bounds (taylor-model) and sparse multivariate recovery
(sparse-hessian, mixed-partial, gradient-n) on top:
(derivative-n (lambda (y) (* y y y)) 3.0 1) ;; => 27 (f'(x) = 3x^2 at x=3)
(taylor (lambda (x) (exp x)) 0.5 4) ;; => the first 5 Taylor coefficients of exp at x=0.5gradient is exact reverse-mode AD however the callable is reached — named
directly, passed through a function parameter, wrapped, or applied in curried
form. (gradient f pt) through a wrapper and the curried ((gradient f) pt) are
byte-identical to the direct call, with no finite-difference fallback anywhere in
the gradient path.
See the Automatic Differentiation guide for the full walkthrough, or CHANGELOG.md for the phase-by-phase (P0-P12) engineering detail.
# Prerequisites: CMake 3.14+, LLVM, C17/C++20 compiler
git clone https://github.com/tsotchke/eshkol.git
cd eshkol
# Build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
# Optional: Build REPL
cmake --build build --target eshkol-repl
# Add to PATH
export PATH=$PATH:$(pwd)/build;; hello.esk
(display "Hello, Eshkol!")
(newline)eshkol-run hello.eskThe language embodies three fundamental principles that distinguish it from existing mathematical computing environments:
Automatic differentiation is not a library feature—it is intrinsic to the language semantics. Eshkol provides three distinct AD modes (symbolic, forward-mode, reverse-mode) with native support for vector calculus operators (∇, ∇·, ∇×, ∇²) and exact nested higher-order differentiation through a computational tape-stack architecture.
;; Define any differentiable function
(define (loss-function params data)
(let ((predictions (neural-network params data)))
(mean-squared-error predictions (data-labels data))))
;; Compute exact gradients - no frameworks, no approximations.
;; `gradient` takes (function vector); close over the data inside a
;; one-vector-argument lambda so the gradient is taken w.r.t. params only.
(define gradients
(gradient (lambda (p) (loss-function p training-data))
initial-params))
;; Exact higher-order derivatives by nesting the scalar `derivative` operator.
;; f(x) = x^3 -> f''(2) = 6*2 = 12
(derivative (lambda (x)
(derivative (lambda (y) (* y y y)) x))
2.0) ;; => 12Arena-based allocation with Ownership-Aware Lexical Regions (OALR) eliminates garbage collection entirely, providing O(1) allocation and deterministic deallocation. This architecture ensures predictable performance characteristics essential for real-time systems and production machine learning deployments. As of v1.3.4, automatic per-iteration reclamation matches explicit with-region even in a resident tick/daemon loop that mutates persistent state every iteration: such a loop is lowered with a per-loop nursery whose write barriers promote escapees and whose back edge resets the nursery, so RSS stays flat without any explicit region annotation. with-region remains available for scratch regions but is no longer required to get flat RSS in a long-running loop.
;; Automatic scope-based memory management
(with-region 'computation
(let ((large-dataset (load-training-data)))
(train-model large-dataset)))
;; All memory automatically freed - no GC pauses, ever
;; Explicit ownership semantics when needed
(define resource (owned (acquire-expensive-resource)))
(transfer-to-subsystem (move resource)) ; Compile-time ownership trackingThe gradual type system, grounded in Homotopy Type Theory, enables compile-time verification of dimensional correctness, resource linearity, and functional purity while preserving Scheme's dynamic flexibility. Type violations produce warnings without preventing compilation, allowing rapid prototyping with optional formal verification.
;; Types provide compile-time guarantees without runtime overhead
(define (matrix-multiply (A : Matrix<Float64, m, n>)
(B : Matrix<Float64, n, p>)) : Matrix<Float64, m, p>
(matmul A B)) ; Dimensions verified at compile-time
;; Linear resources with compile-time consumption tracking
(define quantum-state : (Linear (Superposition 8))
(prepare-quantum-register))
(define measurement (measure quantum-state)) ; quantum-state consumedEshkol is implemented as a production compiler written in C17/C++20, utilizing LLVM for native code generation. The implementation comprises:
- Recursive descent parser with comprehensive macro expansion (syntax-rules)
- HoTT type checker with bidirectional inference and dependent type support
- Modular LLVM backend with 21 specialized code generation components
- Arena memory allocator with optimized allocation primitives
- Production JIT REPL enabling interactive development with persistent state
All values are represented as 16-byte tagged structures with 8-bit type tags and efficient union-based storage. Heap objects utilize 8-byte headers with subtype information, enabling type consolidation while preserving fine-grained semantic distinctions:
typedef struct eshkol_tagged_value {
uint8_t type; // Primary type classification
uint8_t flags; // Exactness, linearity, ownership flags
uint16_t reserved; // Future extensibility
union {
int64_t int_val; // Exact integers, symbols, characters
double double_val; // Inexact real numbers
uint64_t ptr_val; // Heap object pointers
} data;
} eshkol_tagged_value_t; // Exactly 16 bytes for cache efficiencyThe arena allocator implements bump-pointer allocation with lexical scope tracking, delivering O(1) allocation performance and deterministic cleanup:
- 64KB default block size optimized for CPU cache behavior
- Scope stack management for nested region tracking
- Header-prefixed objects enabling type introspection and metadata
- Zero fragmentation through sequential allocation patterns
Utilizes dual number arithmetic for efficient first-derivative computation:
typedef struct eshkol_dual_number {
double value; // f(x)
double derivative; // f'(x)
} eshkol_dual_number_t; // 16 bytes, perfect for SIMDImplements tape-based automatic differentiation with support for arbitrary nesting:
typedef struct ad_tape {
ad_node_t** nodes; // Nodes in evaluation order
size_t num_nodes; // Current node count
ad_node_t** variables; // Input variable references
size_t num_variables; // Variable count
} ad_tape_t;
// Global tape stack for nested gradient computation
extern ad_tape_t* __ad_tape_stack[32];
extern int __ad_tape_depth;Performs compile-time AST transformation for symbolic differentiation with algebraic simplification.
Eshkol implements R7RS-compatible Scheme with modern extensions:
- 39 special forms:
define,lambda,let/let*/letrec,if/cond/case/match,quote/quasiquote,guard/raise,call/cc,dynamic-wind - 550+ built-in functions: Complete numeric tower (int64/bignum/rational/double/complex), list operations, string manipulation, I/O, ML builtins
- Hygienic macros: Full
syntax-rulesimplementation with pattern matching - Lexical closures: First-class functions with captured environment support
- Tail call optimization: Direct elimination and trampoline-based constant-stack recursion
(derivative f x) ; Forward-mode: ℝ → ℝ
(gradient f point) ; Reverse-mode: ℝⁿ → ℝⁿ
(jacobian F point) ; Vector function: ℝⁿ → ℝᵐˣⁿ
(hessian f point) ; Second derivatives: ℝⁿ → ℝⁿˣⁿ
(divergence F point) ; ∇·F: ℝⁿ → ℝ
(curl F point) ; ∇×F: ℝ³ → ℝ³
(laplacian f point) ; ∇²f: ℝⁿ → ℝ
(directional-derivative f p dir) ; D_v f: directional derivativeNew in v1.3.0-evolve — the Taylor-tower AD matrix. Beyond the classic operators, Eshkol now differentiates to arbitrary order, returns exact (bignum/rational) derivatives, and provides validated (Taylor-model), multivariate, tensor, sparse, and checkpointed-reverse AD:
(taylor f x k) ; K+1 Taylor coefficients of f at x
(derivative-n f x k) ; k-th derivative, any order, exact when possible
(mixed-partial f xs idxs) ; arbitrary-order mixed partial derivative
(gradient-n f xs order) ; full order>=3 symmetric derivative tensor
(taylor-model f x0 r k) ; validated AD: polynomial + interval remainder
(sparse-hessian f xs) ; sparse Hessian via colored recovery(derivative-n (lambda (x) (* x x x x x)) 2.0 3) ; => 240 (d³/dx³ x⁵, any order)
(derivative-n (lambda (x) (expt x 30)) 7 1) ; => 96597172674395391805128210 (EXACT bignum)
(taylor (lambda (x) (exp x)) 0.0 4) ; => (1 1 0.5 0.166667 0.0416667) (Taylor series)See the Automatic Differentiation user guide for the full surface — arbitrary order, exact coefficients, mixed partials, tensor towers, Taylor models, sparse Hessians, checkpointed reverse, differentiable control flow, and tower numerics — every example runnable.
;; Tensor creation and manipulation
(zeros 100) ; 1D zero vector
(ones 10 10) ; 2D identity preparation
(eye 4) ; 4×4 identity matrix
(arange 0 100 0.1) ; 1000-element range
(linspace -1 1 1000) ; Linearly-spaced values
;; Linear algebra operations
(matmul A B) ; Matrix multiplication
(tensor-dot u v) ; Dot product / contraction
(transpose M) ; Matrix transposition
(solve A b) ; Linear system solution (LU decomposition)
(det M) ; Determinant (Gaussian elimination)
(inv M) ; Matrix inverse (Gauss-Jordan);; Arena-based regions with automatic cleanup
(with-region 'training-session
(let ((model (initialize-large-model))
(data (load-training-batch)))
(gradient-descent-step model data)))
;; Memory deterministically freed
;; Ownership and borrowing semantics
(define resource (owned (acquire-gpu-buffer)))
(define processed (move resource)) ; Transfer ownership
(borrow processed (lambda (r) (analyze r))) ; Temporary access
(define shared-ref (shared processed)) ; Reference counting;; HoTT-based gradual typing with dependent types
(define (safe-array-access (arr : Vector<Float64, n>)
(idx : Nat) {idx < n}) : Float64
(vector-ref arr idx)) ; Bounds verified statically
;; Polymorphic function types
(define map : (∀ (A B) (-> (-> A B) (List A) (List B)))
(lambda (f lst) ...))
;; Linear resource tracking
(define quantum-state : (Linear Superposition)
(prepare-quantum-bits 8))
(measure quantum-state) ; Consumption verified at compile-timeComplete multi-layer perceptron with automatic differentiation:
(require stdlib)
;; Define network architecture
(define (neural-network weights inputs)
(fold (lambda (layer input)
(relu (tensor-add (matmul layer input)
(layer-bias layer))))
inputs
weights))
;; Loss function with L2 regularization
(define (total-loss weights data targets lambda-reg)
(+ (mse (neural-network weights data) targets)
(* lambda-reg (sum-squares weights))))
;; Training step with exact gradients
(define (train-step weights data targets learning-rate)
(let ((grad (gradient (lambda (w) (total-loss w data targets 0.01)) weights)))
(tensor-sub weights (tensor-mul grad (vector learning-rate)))))
;; Training loop
(define final-weights
(fold train-step initial-weights training-batches))Linear algebra and numerical methods implemented in pure Eshkol:
;; Solve system of equations: Ax = b
(define A (reshape (vector 4.0 1.0 2.0 3.0) 2 2))
(define b (vector 7.0 10.0))
(define x (solve A b 2)) ; Uses LU decomposition with partial pivoting
;; Numerical integration (Simpson's rule)
(define area (integrate (lambda (x) (* x x x)) 0.0 2.0 1000))
;; Root finding (Newton-Raphson method)
(define sqrt-2
(newton (lambda (x) (- (* x x) 2.0)) ; f(x) = x² - 2
(lambda (x) (* 2.0 x)) ; f'(x) = 2x
1.0 1e-10 100))
;; Eigenvalue estimation (power iteration)
(define dominant-eigenvalue
(power-iteration covariance-matrix n 1000 1e-12))Physical field analysis with native differential operators:
;; Electric field: E = ∇V (gradient of potential)
(define (electric-field potential point)
(gradient potential point))
;; Divergence theorem verification: ∇·E
(define (field-divergence E-field region-points)
(map (lambda (p) (divergence E-field p)) region-points))
;; Curl for magnetic fields: B = ∇×A
(define (magnetic-field vector-potential point)
(curl vector-potential point))
;; Wave equation: ∇²φ - (1/c²)(∂²φ/∂t²) = 0
(define (laplacian-operator scalar-field point)
(laplacian scalar-field point))| Component | Compile Time | Generated IR | Native Perf |
|---|---|---|---|
| Simple expression | ~50ms | Optimized | C-performance |
| Neural network | ~800ms | SIMD-enabled | parity with NumPy |
| Tensor operations | ~200ms | Vectorized | Hand-tuned speed |
- Arena allocation: O(1) bump-pointer, zero fragmentation
- Cache efficiency: 16-byte tagged values, 32-byte cons cells
- Deterministic cleanup: No GC pauses, predictable latency
- Memory usage: Competitive with manually managed C++
- Forward-mode: 2-3x slowdown (industry standard)
- Reverse-mode: 3-5x slowdown with O(n) memory (optimal)
- Symbolic: Zero runtime overhead (compile-time transformation)
- Nested gradients: Logarithmic space complexity via tape stack
Unlike interpreted Lisps, Eshkol preserves code-as-data semantics while generating native machine code. Lambda functions maintain their S-expression representations through a runtime registry, enabling full introspection of compiled code.
Each cons cell stores complete type information in both car and cdr positions, enabling heterogeneous lists with zero type erasure:
;; Each element retains full type information
(define mixed-list (list 42 "hello" (lambda (x) x) #(1.0 2.0 3.0)))
(map type-of mixed-list) ; => (int64 string closure tensor)Arena allocation with compile-time ownership tracking provides memory safety without runtime cost. Linear types and borrow checking prevent use-after-free and double-free errors at compilation time.
The only language providing symbolic, forward-mode, and reverse-mode AD with seamless interoperability:
;; Symbolic (compile-time, zero overhead)
(diff (* x x) x) ; → (* 2 x)
;; Forward-mode (dual numbers, exact derivatives)
(derivative (lambda (x) (* x x x)) 2.0) ; → 12.0
;; Reverse-mode (computational graphs, scalable to large functions)
(gradient (lambda (v) (complex-loss-function v)) parameter-vector)Dependent types enable compile-time verification of array bounds, matrix dimensions, and resource consumption:
;; Matrix multiplication with dimension checking
(define (safe-matmul (A : Matrix<Float64, m, k>)
(B : Matrix<Float64, k, n>)) : Matrix<Float64, m, n>
(matmul A B)) ; k dimensions must match - verified statically- CMake 3.14+ (build system)
- LLVM 21 (backend and JIT)
- C17/C++20 compiler (GCC 11+, Clang 14+)
- Ninja (recommended build tool)
- Readline (optional, for REPL enhancements)
git clone https://github.com/tsotchke/eshkol.git
cd eshkol
# Configure build
cmake -B build -DCMAKE_BUILD_TYPE=Release
# Compile (parallel build recommended)
cmake --build build -j$(nproc)
# Optional: Build interactive REPL
cmake --build build --target eshkol-repl
# Add to path
export PATH=$PATH:$(pwd)/build# Test basic functionality
echo '(+ 1 2 3)' | eshkol-run # Should output: 6
# Test automatic differentiation
echo '(derivative (lambda (x) (* x x)) 5.0)' | eshkol-run # Should output: 10.0
# Test neural network capability
eshkol-run tests/neural/nn_working.esk
# Interactive REPL
eshkol-replCreate hello.esk:
;; gradient.esk - Gradient computation demonstration
(require stdlib)
(define (quadratic x) (+ (* x x) (* 2 x) 1))
(define point 3.0)
(display "f(x) = x² + 2x + 1")
(newline)
(display "f(3) = ") (display (quadratic point)) (newline)
(display "f'(3) = ") (display (derivative quadratic point)) (newline)
;; Expected output:
;; f(x) = x² + 2x + 1
;; f(3) = 16.0
;; f'(3) = 8.0Execute: eshkol-run gradient.esk -o gradient && ./gradient
- Lexical scoping with proper closures and captured environments
- Proper tail calls with direct elimination and trampoline support
- Hygienic macros via syntax-rules with pattern matching
- First-class continuations (
call/cc,dynamic-wind) - R7RS compatibility for core semantics and standard procedures
- N-dimensional tensors with element-wise operations and broadcasting
- Linear algebra: LU decomposition, QR, SVD, Cholesky, eigenvalue estimation
- Numerical methods: Simpson's integration, Newton-Raphson root finding, ODE solvers (Euler, RK4)
- Vector field analysis: divergence, curl, Laplacian operators
- Statistical functions: variance, covariance, correlation, distributions
- Signal processing: FFT/IFFT, window functions (Hamming, Hann, Blackman, Kaiser), FIR/IIR filters, Butterworth design
- 75+ ML builtins: activations, losses, optimizers, CNN layers, transformer ops, training utilities
- Weight initialization: Xavier, Kaiming, LeCun (uniform and normal variants)
- Training utilities: learning rate schedulers, gradient clipping, dataloader
- Optimization algorithms: gradient descent, Adam, L-BFGS, conjugate gradient
- GPU acceleration: Metal (Apple Silicon) with SF64 software float64, CUDA (NVIDIA)
- Parallel primitives:
parallel-map,parallel-fold,parallel-filter,future/force - Exact arithmetic: Arbitrary-precision integers (bignums), rational numbers, R7RS numeric tower
- Consciousness engine: Logic programming, factor graphs with belief propagation, global workspace
- First-class continuations:
call/cc,dynamic-wind,guard/raise - Dual backend: Bytecode VM (64 core opcodes, ESKB format) alongside LLVM native compiler
- Windows support: Native Visual Studio 2022 + ClangCL/LLVM 21 build with UTF-8 REPL and DLL bundling
Get models into production. Save them, load them, deploy them — and stop being surprised by edge cases.
- Model serialization:
.eshkol-modelESKB-extended binary format for round-tripping trained networks - Stable C FFI: pybind11 Python bindings with NumPy zero-copy interop
- Per-thread arenas: Safe concurrent memory allocation; deep recursion (100K stack frames) on a 512 MB thread stack
- Image I/O: PNG/JPEG/WebP/BMP read/write/resize for vision pipelines via native platform/system codecs
- Plotting stdlib: Inline matplotlib-style charts via PNG output
- Actionable error messages: Compile errors point at the exact source line and column with caret underline
- JSON Schema validation: Draft 7 subset for experiment-manifest / preregistration enforcement (
json-schema-valid?,json-schema-validate) - R7RS-compliant scoping: User redefines of stdlib functions cleanly shadow the stdlib version (LinkOnceODR linkage; variadic-info hygiene)
- WASM library mode:
--wasmproduces self-contained module without falling through to native link - Hardening: subprocess shell-injection fix, Python FFI AST-injection fix, integer-overflow guards (arena/KB/image), path-traversal defence, ReDoS protection, sanitizer-clean ASan/UBSan CI lane
- 87-test edge/security suite: regression coverage for symbol consistency, AD tape state, parser line tracking, stdlib symbol resolution, HTTP/server smoke behavior, and every fix in this release
- Consumer-hardening correctness wave: an emitted compile-time error now
prevents artifact emission and execution, so a diagnosed program fails the
build instead of producing a wrong answer. Exactness is decided from an
operand's runtime tag rather than a result's value shape, on the native
flonum integer-division family and across the bytecode VM's numeric surface;
automatic differentiation answers exactly at exact (rational/bignum) points,
survives per-iteration nursery reclamation, and no longer returns zeros above
gradient arity 16;
define-library/importresolve same-unit libraries on all three back ends; and--shared-liblinks a real, C-ABI-correct shared library. - New capability: a portable event loop (kqueue / epoll / IOCP, fail-closed
on WASM), a fixed-point and
i128exact-accumulation engine with order-independent bit-exact reductions, the qLLM bridge implementation, and embedding / Fréchet-mean backward passes. - Portable 16-file release payload: 15 platform archives plus
SHA256SUMS.txt. Linux x64/ARM64 ship Lite, XLA, and CUDA; macOS x64/ARM64 ship Lite and XLA; Windows x64 ships Lite, XLA, and CUDA; Windows ARM64 ships Lite and XLA. Windows ARM64 CUDA is not advertised because NVIDIA does not provide the required supported toolkit. - Clean-host package execution: relocated core/agent JITs, persistent AOT cache links, image-codec dependencies, generic ARM64 stdlib code, architecture-matched compiler-rt, and CUDA consumer paths are verified by the release workflow rather than inferred from builder-local success.
- Execution-backed evidence, all measured on the release commit: the
aggregate suite 45/45 suites and 770 individual tests, CTest 139/139, the
SICP full-book gate 88/88 probes across all five chapters under both
-rand AOT, and the reference-Scheme differential oracle 34/34 AGREE against chibi-scheme 0.12.0. The language-surface gate enforces a monotonic floor of 1,091 declared constructs at 100% execution-backed coverage: a construct earns its row by dispatching or executing in a passing run, and lexical name-presence is a diagnostic only, earning no release credit. CTest results are now completion-oracle evidence in their own right, so a red suite turns the release gate red. - Explicit VM scope: this is not a claim of complete backend parity. The
951-row ratchet classifies 578 VM-supported entries, 44 justified
native-only entries, and 329 explicit gaps in
tests/vm_parity/PARITY.tsv; see VM Parity for the enforced contract.
See RELEASE_NOTES.md for the gate matrix and ANNOUNCEMENT.md for the release narrative.
Evolve. An arbitrary-order automatic-differentiation system (Taylor towers, phases P0-P12), full R7RS conformance on the portable differential corpus, closure/TCO/memory robustness hardening, and a permanent multi-pillar adversarial-testing infrastructure.
- Arbitrary-order AD (Taylor towers):
(taylor f x k)/(derivative-n f x k)compute every derivative up to any orderkin one pass — exactly (bignum/rational coefficients) when the arithmetic supports it, with no-heap compile-time-kmonomorphization, arbitrary-order mixed partials (mixed-partial,gradient-n) via a Griewank-Utke-Walther layer, reverse-over-Taylor and checkpointed high-order reverse-mode, tensor-valued towers throughmatmul/conv2d, validated Taylor models with interval-remainder bounds (taylor-model), sparse high-order tensors (sparse-hessian), differentiable control flow, and tower-based numerics (taylor-ode-solve,taylor-root). See the Automatic Differentiation guide. - Full R7RS conformance: the reference-Scheme differential oracle now
agrees with chibi-scheme 34/34 (100%) on the portable corpus —
applywith leading arguments, multi-vectorvector-map, quasiquoted vector literals,cond/case=>clauses, allocatingvector-copy(including on#(...)literals), theerror-object?/error-object-message/error-object-irritantsfamily, R7RSwriteescaping, nested ellipsis insyntax-rules, and 2-argumentsubstringare all fixed. - Full SICP support: an 88-probe full-book gate (
tests/sicp/,scripts/run_sicp_smoke.sh) covering chapters 1-5 — including the metacircular, analyzing, lazy, andambnondeterministic evaluators, the query system, and the register-machine simulators — passing under both-r(JIT) and AOT. - Robustness: mutual tail calls are proper O(1)-stack R7RS tail calls on
AArch64; named-let TCO covers every tail position including through
guard; the closure-capture ceiling is raised 16 → 64; a class of unbounded RSS growth in long-running loops is fixed with automatic per-iteration arena reclamation; a shutdown-teardown race and a deep- recursionSIGILL-with-no-diagnostic bug are both fixed;eshkol-run -r/AOT caching now invalidates correctly on transitive(load ...)/(require ...)dependency changes. - Build:
--emit-depfileplus a canonicalcmake/EshkolCompile.cmakefor embedding the Eshkol compiler in a consumer's CMake build. - VM/Web: every example on eshkol.ai runs (browser VM builtin table reconciled with the native compiler; WASM JS glue checked in CI against every symbol the backend can emit).
- Adversarial testing infrastructure (new, permanent): a multi-path
differential harness + fuzzer, a feature-pair edge matrix, an AD
finite-difference oracle, a stress harness with RSS/time budgets, a VM
parity ratchet, six depth-parametric sweep families, and external oracles
(reference-Scheme differential, sanitizer fuzzing, metamorphic-law
checking) — all wired into the ICC readiness oracle. See
docs/TESTING.md.
Some deep-edge findings surfaced by the new harnesses remain open and are
tracked in docs/KNOWN_ISSUES.md and the changelog's
Known Issues section (e.g. order-≤2 vector gradient-of-gradient,
hessian/laplacian on tensor points, deep non-tail recursion in stdlib
sort/filter). See CHANGELOG.md.
- String interpolation via
~{expr}inside strings, with~~{for a literal opener - Named keyword arguments in function and lambda formals, e.g.
(define (scale x #:factor factor) (* x factor)) - Pattern matching with algebraic data type support
- Module system with dependency resolution, package manager (
eshkol-pkg), and R7RS(import ...)/(define-library ...)forms. R7RS import-set modifiers (only,except,rename, and explicit prefixes) lower through the existing module loader and alias machinery. - Exception handling via
guard/raisewith typed exception hierarchies - Multiple return values with destructuring assignment
- Hash tables with generic key/value types and O(1) average access
- Records via
define-record-type(R7RS) - Bytevectors for binary data (R7RS 6.9)
The REPL provides full compilation and execution via LLVM JIT:
$ eshkol-repl
Welcome to Eshkol REPL v1.3.0-evolve
Type :help for commands, :quit to exit
eshkol> (define (f v) (let ((x (vref v 0))) (* x x x)))
eshkol> (gradient f (vector 2.0))
#(12)
eshkol> :type (gradient f (vector 2.0))
Vector<Float64, 1>
eshkol> :ast (lambda (x) (* x x))
(λ (x) (* x x))
eshkol> :load my-program.esk
Loaded 15 expressions from my-program.esk
Comprehensive libraries implemented in pure Eshkol:
core.functional.*: composition, currying, combinatorscore.list.*: higher-order functions, transformations, queriescore.data.*: JSON, CSV, Base64 parsing and serializationcore.strings.*: 30+ string manipulation utilitiesmath.*: special functions (Bessel, Gamma, Beta), constants, ODE solverssignal.*: FFT/IFFT, window functions, FIR/IIR filters, Butterworth designml.*: optimization algorithms (Adam, L-BFGS), activations, normalizationrandom.*: PRNG, distributions, quantum-inspired RNGweb.*: WASM/DOM API (80+ functions), HTTPtensor.*: shape manipulation, stacking utilities
# Compile to native executable
eshkol-run program.esk -o program
# Compile to object file for linking
eshkol-run library.esk -c -o library.o
# Link with external libraries
eshkol-run main.esk -l linear-algebra -l graphics -o app
# Generate LLVM IR for analysis
eshkol-run --dump-ir program.esk # Produces program.llEshkol occupies a unique position combining the mathematical rigor of Julia, the functional elegance of Racket, the memory safety of Rust, and the AD capabilities of JAX, while maintaining true Lisp homoiconicity.
| Feature | Eshkol | Julia | JAX | Racket | Rust |
|---|---|---|---|---|---|
| Native AD | ✓ (3 modes) | ✗ | ✓ (reverse) | ✗ | ✗ |
| Memory Safety | ✓ (arena+linear) | ✗ | ✗ | ✓ (GC) | ✓ (ownership) |
| Homoiconicity | ✓ (native) | ✓ (partial) | ✗ | ✓ | ✗ |
| Native Compilation | ✓ (LLVM) | ✓ | ✓ (XLA) | ✗ | ✓ |
| Deterministic Perf | ✓ (no GC) | ✗ | ✗ | ✗ | ✓ |
| Dependent Types | ✓ (HoTT) | ✗ | ✗ | ✗ | ✗ |
- OALR Memory Model: First practical implementation of ownership-aware lexical regions in a functional language
- Native AD Integration: Language-level integration of three AD modes with nested computation support
- HoTT Gradual Typing: Practical application of Homotopy Type Theory principles to gradual type checking
- Homoiconic Compilation: Preservation of code-as-data semantics through native compilation
- First 5 Minutes: Install, hello world, 5 wow moments
- Why Eshkol?: Side-by-side comparison vs Python and JavaScript
- Cookbook: 30 copy-paste recipes for common tasks
- All 27 Tutorials: Feature guides + complete project tutorials (neural networks, expert systems, self-improving programs)
- Automatic Differentiation: Arbitrary-order Taylor-tower AD guide, new in v1.3.0-evolve
- Language Guide: Tutorial-style introduction to the language
- Language Reference: Complete, example-verified function and syntax reference
- Complete Language Specification: Full technical specification
- Quick Reference: One-page cheat sheet
- Quickstart: Hands-on introduction with examples
- API Reference: Comprehensive function documentation
- Automatic Differentiation Guide: The full v1.3 AD surface — arbitrary order, exact, validated, tensor, sparse, checkpointed — example-driven
- Automatic Differentiation: Mathematical foundations and implementation
- Type System: HoTT theory and practical realization
- Memory Architecture: Arena allocation and OALR semantics
- Compiler Design: LLVM backend and optimization strategies
- Contributing Guide: Architecture overview and development workflow
- Test Coverage: Comprehensive test documentation
- Overview: Start Here
- Platform Program: Freestanding / kernel / embedded architecture plan aligned to the roadmap
- XLA backend, SIMD vectorization, GPU acceleration (Metal/CUDA)
- Parallel primitives, arbitrary-precision arithmetic, consciousness engine
- Full R7RS extensions (call/cc, dynamic-wind, bytevectors)
- Distributed computing and multi-GPU support
- Model serialization and ONNX export
- Advanced neural network primitives (convolution, attention)
- Advanced neuro-symbolic integration
- Constraint solving and neural-guided symbolic search
- Differentiable programming with symbolic constraints
- Quantum circuit compilation and hybrid algorithms
- Full dependent type enforcement and formal verification
- Whole-program and polyhedral optimization
Eshkol welcomes contributions from researchers and practitioners. The codebase is architected for extensibility:
- Modular codegen: Add new backends by implementing CodegenModule interface
- Type system: Extend HoTT types through TypeFamily registration
- Standard library: Pure Eshkol implementations in
lib/core/ - Testing: Comprehensive test coverage required for all features
See CONTRIBUTING.md for development setup and coding standards.
| Document | Purpose |
|---|---|
| QUICKSTART | 15-minute getting-started guide |
| Tutorials | 27 step-by-step tutorials |
| API Reference | Complete reference (555+ builtins, 336 documented procedures) |
| Language Guide | Conceptual user guide |
| Quick Reference | One-page cheat sheet |
| Automatic Differentiation Guide | Arbitrary-order Taylor-tower AD walkthrough |
| Complete Language Specification | Full technical specification |
| Standard Library API | Stdlib module surfaces, including infrastructure modules (Appendix B) |
| Architecture deep-dives | Per-subsystem technical breakdowns (37 docs) |
| FAQ | Installation, troubleshooting, common questions |
| Test Coverage | What the 37-suite gate verifies |
| Known Issues | Current limitations and v1.3+ items |
| Testing & Adversarial Harnesses | SICP gate + the five adversarial harnesses and how to run them |
| VM Parity | Bytecode-VM vs native-codegen parity ratchet |
| ROADMAP | Canonical release plan |
| Release Notes | Per-release changelog |
| SDNC Paper Artefact | Self-Differentiating Neural Computer |
Eshkol is designed for:
- Integrated AI systems programming: Platform native self-improving, long-running agents and robotics
- Machine learning research: Native AD, deterministic performance, mathematical correctness
- Numerical analysis: High-precision computing, algorithm development, performance optimization
- Programming language research: Type theory, memory management, compilation techniques
- Computer graphics: Differentiable rendering, optimization-based animation
Eshkol is released under the MIT License. For academic use, please cite:
@software{eshkol2025,
title = {Eshkol: A Programming Language for Mathematical Computing},
author = {tsotchke},
version = {1.3.0-evolve},
year = {2026},
url = {https://github.com/tsotchke/eshkol},
note = {Scheme-based language with native automatic differentiation}
}- Language: C17 runtime, C++20 compiler implementation
- Backend: LLVM 21 with native code generation and JIT support
- Memory: Arena-based allocation with deterministic cleanup
- Types: HoTT-based gradual typing with dependent type support
- AD: Forward/reverse/symbolic modes with nested computation
- Testing: 44/44 suites and 716/716 tests; CTest 76/76; executable language coverage 1,078/1,078
- Platform: macOS x64/ARM64, Linux x64/ARM64, and Windows x64/ARM64 via LLVM 21. CUDA 12.4 packages target Linux x64/ARM64 and Windows x64; Windows ARM64 CUDA is not advertised.
Eshkol represents a synthesis of functional programming elegance, mathematical rigor, and systems programming performance. It is designed for researchers, engineers, and practitioners who require both expressive power and computational efficiency in their mathematical computing workflows.
Where Lisp meets differential geometry, and performance meets mathematical correctness.
Engineered for researchers and engineers building machine learning systems, numerical simulations, and differentiable algorithms where mathematical correctness and performance are non-negotiable.