Eshkol

A Programming Language for Mathematical Computing

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.

---

Why Eshkol?

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

---

Try It Now

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) compiled to a 502KB WASM binary. Automatic differentiation works in the browser:

(derivative (lambda (x) (* x x x)) 2.0)  ;; => 12.0 (3x² at x=2)

---

Quick Start

Installation

# 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, World!

;; hello.esk
(display "Hello, Eshkol!")
(newline)

eshkol-run hello.esk

---

Design Philosophy

The language embodies three fundamental principles that distinguish it from existing mathematical computing environments:

1. Differentiation as a Language Primitive

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 arbitrary-depth gradient nesting through a sophisticated 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))

;; Nested gradients to arbitrary depth
(define hessian-trace 
  (trace (gradient (lambda (x) 
                     (car (gradient f (vector x))))
                   (vector x0))))

2. Deterministic Memory Management

Arena-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.

;; 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 tracking

3. Mathematical Rigor Through Type Theory

The 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 consumed

---

Technical Implementation

Compiler Architecture

Eshkol 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

Runtime Representation

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 efficiency

Memory Architecture

The 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

Automatic Differentiation System

Forward-Mode (Dual Numbers)

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 SIMD

Reverse-Mode (Computational Graphs)

Implements 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;

Symbolic Mode

Performs compile-time AST transformation for symbolic differentiation with algebraic simplification.

---

Language Capabilities

Core Scheme Compatibility

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-rules implementation with pattern matching
• Lexical closures: First-class functions with captured environment support
• Tail call optimization: Direct elimination and trampoline-based constant-stack recursion

Extended Capabilities

Automatic Differentiation (8 Operators)

(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 derivative

N-Dimensional Tensors (30+ Operations)

;; 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)

Advanced Memory Management

;; 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

Advanced Type System

;; 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-time

---

Demonstrated Applications

Neural Network Training

Complete 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))

Scientific Computing

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))

Vector Calculus

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))

---

Performance Characteristics

Compilation Performance

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

Memory Performance

• 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++

Autodiff Overhead

• 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

---

Unique Technical Achievements

1. True Homoiconicity with Native Compilation

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.

2. Mixed-Type Lists with Complete Type Preservation

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)

3. Zero-Overhead Memory Safety

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.

4. Three-Mode Automatic Differentiation

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)

5. HoTT-Based Type System

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

---

Installation and Quick Start

Prerequisites

• CMake 3.14+ (build system)
• LLVM 17 (backend and JIT)
• C17/C++20 compiler (GCC 11+, Clang 14+)
• Ninja (recommended build tool)
• Readline (optional, for REPL enhancements)

Build from Source

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

Verification

# 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-repl

First Program

Create 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.0

Execute: eshkol-run gradient.esk -o gradient && ./gradient

---

Language Features

Complete Scheme Foundation

• 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

Mathematical Computing Extensions

• 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

Machine Learning (v1.1)

• 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

v1.1-accelerate Features

• 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

v1.2-scale Features

Get models into production. Save them, load them, deploy them — and stop being surprised by edge cases.

• Model serialization: .eshkol-model ESKB-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: --wasm produces 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

Modern Language Features

• 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/raise with 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)

---

Ecosystem and Tooling

Interactive Development

The REPL provides full compilation and execution via LLVM JIT:

$ eshkol-repl

Welcome to Eshkol REPL v1.2.3-scale
Type :help for commands, :quit to exit

eshkol> (define (f x) (* x x x))
eshkol> (gradient f (vector 2.0))
#(12.0)

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

Standard Library

Comprehensive libraries implemented in pure Eshkol:

• core.functional.*: composition, currying, combinators
• core.list.*: higher-order functions, transformations, queries
• core.data.*: JSON, CSV, Base64 parsing and serialization
• core.strings.*: 30+ string manipulation utilities
• math.*: special functions (Bessel, Gamma, Beta), constants, ODE solvers
• signal.*: FFT/IFFT, window functions, FIR/IIR filters, Butterworth design
• ml.*: optimization algorithms (Adam, L-BFGS), activations, normalization
• random.*: PRNG, distributions, quantum-inspired RNG
• web.*: WASM/DOM API (80+ functions), HTTP
• tensor.*: shape manipulation, stacking utilities

Build System Integration

# 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.ll

---

Research Context and Comparisons

Positioning in the Language Landscape

Eshkol 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)	✗	✗	✗	✗

Research Contributions

1. OALR Memory Model: First practical implementation of ownership-aware lexical regions in a functional language
2. Native AD Integration: Language-level integration of three AD modes with nested computation support
3. HoTT Gradual Typing: Practical application of Homotopy Type Theory principles to gradual type checking
4. Homoiconic Compilation: Preservation of code-as-data semantics through native compilation

---

Documentation

Tutorials

• 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)

For Users

• Language Guide: Tutorial-style introduction to the language
• Language Reference: Complete function and syntax reference
• Quickstart: Hands-on introduction with examples
• API Reference: Comprehensive function documentation

For Researchers

• 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

For Developers

• 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

---

Future Directions

Version 1.1 (Q1 2026): Performance Acceleration — COMPLETED

• XLA backend, SIMD vectorization, GPU acceleration (Metal/CUDA)
• Parallel primitives, arbitrary-precision arithmetic, consciousness engine
• Full R7RS extensions (call/cc, dynamic-wind, bytevectors)

Version 1.2 (Q2 2026): Scale

• Distributed computing and multi-GPU support
• Model serialization and ONNX export
• Advanced neural network primitives (convolution, attention)

Version 1.5 (Q3 2026): Intelligence

• Advanced neuro-symbolic integration
• Constraint solving and neural-guided symbolic search
• Differentiable programming with symbolic constraints

Version 2.0+ (Q4 2026+): Quantum & Beyond

• Quantum circuit compilation and hybrid algorithms
• Full dependent type enforcement and formal verification
• Whole-program and polyhedral optimization

---

Community and Contributions

Contributing

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.

Documentation Map

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
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
ROADMAP	Canonical release plan
Release Notes	Per-release changelog
SDNC Paper Artefact	Self-Differentiating Neural Computer

Research Applications

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

License and Citation

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.2.3-scale},
  year = {2026},
  url = {https://github.com/tsotchke/eshkol},
  note = {Scheme-based language with native automatic differentiation}
}

---

Technical Specifications

• 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: 528 self-reported tests across 37 suites with automated verification
• Platform: macOS (Intel/Apple Silicon), Linux (x86_64/ARM64), Windows (native x86_64 via Visual Studio 2022 + LLVM 21)

---

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.