η (Eta)
A Lisp/Scheme-inspired language with built-in logic programming,
automatic differentiation, neural networks, and causal inference.

Quick Start · VS Code Extension · Jupyter Kernel · Build from Source · Architecture · Modules & Stdlib · All Documentation · Release Notes

Language Guides

Area	Guides
Foundations	Basics · Regex · Time · CSV · Networking · Actors / Message Passing
Logic & Constraints	Logic Programming · CLP · Fact Tables
Numerics & ML	AAD · Eigen — Linear Algebra & Stats · LibTorch — Neural Networks
Causal	Causal Inference & Do-Calculus

Featured Examples

Causal Decision Engine for Portfolio Optimisation (Notebook)

---

What is Eta?

Eta is a Scheme-like language designed for symbolic reasoning, differentiable programming, neural-network training, and causal inference — all from a single S-expression syntax. It compiles to compact bytecode and runs on a stack-based VM implemented in C++ (NaN-boxed values, closures, TCO, call/cc, hygienic macros, module system — see Architecture for the full compilation pipeline).

Headline Features

Domain	What you get	Deep-dive
Scheme Core	Closures, tail-call elimination, first-class continuations (call/cc), hygienic syntax-rules macros, module system with import filters	Bytecode & VM · Modules
Logic Programming	VM-native structural unification & backtracking — seven dedicated opcodes give you Prolog-style pattern matching without leaving the language	Logic
Constraint Logic Programming	clp(Z) integer-interval and clp(FD) finite-domain solvers built on the unification layer	CLP
Reverse-Mode AAD	VM-native tape-based automatic differentiation — standard arithmetic is recorded transparently when a TapeRef operand is present; zero closure overhead	AAD – Finance Examples
Linear Algebra & Statistics	Eigen-backed multivariate OLS, covariance/correlation matrices, column quantiles over FactTables; plus std.stats descriptive stats, CIs, t-tests, and simple OLS over lists	Stats
Neural Networks (libtorch)	Native C++ bindings to PyTorch's backend — tensors, autograd, NN layers, optimizers, and GPU offload from Eta code	LibTorch
Causal Inference	Pearl's do-calculus engine, back-door / front-door adjustment, and end-to-end factor analysis	Causal
Message Passing & Actors	Erlang-style actor model via nng: spawn child processes, send!/recv! over PAIR sockets, worker-pool parallel fan-out, REQ/REP, PUB/SUB, SURVEYOR/RESPONDENT, and supervision trees (one-for-one, one-for-all) — network-transparent across machines	Networking · Message Passing · Supervisors
End-to-End Pipeline	All domains compose: symbolic differentiation → do-calculus identification → logic/CLP validation → libtorch neural estimation → AAD risk → CLP(R)+QP allocation	Portfolio Engine · Causal Primer

The implementation ships as seven executables, a VS Code extension, and a Jupyter kernel:

Bytecode Compiler (etac)
Interpreter (etai)
Interactive REPL (eta_repl)
Language Server (eta_lsp)
Debug Adapter (eta_dap)
Test Runner (eta_test)
Jupyter Kernel (eta_jupyter)
VS Code Extension

---

Install & Run

Download the latest release for your platform, unpack it, and run the installer:

Platform	Archive
Windows x64	eta-v0.4.0-win-x64.zip
Linux x86_64	eta-v0.4.0-linux-x86_64.tar.gz

# Windows                              # Linux / macOS
cd eta-v0.2.0-win-x64                  cd eta-v0.4.0-linux-x86_64
.\install.cmd                          chmod +x install.sh && ./install.sh

The installer adds bin/ to your PATH, sets ETA_MODULE_PATH, and installs the VS Code extension automatically if VS Code is detected.

Note

Open a new terminal after running the installer for the environment changes to take effect.

Run a script — etai

etai compiles a .eta file in-memory and executes it immediately:

$ etai examples/hello.eta
Hello, world!
2432902008176640000

Ahead-of-time compile — etac

etac compiles .eta source to compact .etac bytecode. etai then loads .etac files directly, skipping all front-end phases (lex, parse, expand, link, analyze, emit) for faster startup:

$ etac examples/hello.eta
compiled examples/hello.eta → examples/hello.etac (3 functions, 1 module(s))

$ etai examples/hello.etac
Hello, world!
2432902008176640000

Key flags:

Flag	Effect
-O	Enable optimization passes (constant folding, dead code elimination)
--disasm	Print human-readable bytecode to stdout (no .etac written)
--no-debug	Strip source maps for a smaller output file
-o <path>	Custom output path (default: <input>.etac)

$ etac -O examples/hello.eta -o hello-opt.etac
$ etac --disasm examples/hello.eta

Interactive REPL — eta_repl

$ eta_repl
η> (+ 1 2 3 4 5)
=> 15
η> (exit)

VS Code — debugging, heap inspector, disassembly

The installer automatically sets up the VS Code extension. Configure the paths in settings (Ctrl+, → search Eta):

{
  "eta.lsp.serverPath":     "/path/to/eta-v0.2.0/bin/eta_lsp",
  "eta.dap.executablePath": "/path/to/eta-v0.2.0/bin/eta_dap"
}

Open the examples/ folder, open any .eta file, and press F5 to debug. The extension provides:

• Syntax highlighting and live diagnostics (LSP)
• Breakpoints & stepping — F10 Step Over · F11 Step In · Shift+F11 Step Out · F5 Continue
• Heap Inspector — live memory gauge, per-kind object stats, GC root tree with drill-down (Ctrl+Shift+P → Eta: Show Heap Inspector)
• Disassembly View — live bytecode with current-PC marker in the Debug sidebar (Ctrl+Shift+P → Eta: Show Disassembly)
• GC Roots Tree — expandable root categories (Stack, Globals, Frames), module-grouped globals, object drill-down
• Child Processes — debug sidebar panel listing all spawned actor processes with PID, endpoint, and live/exited status

For the full feature tour with screenshots, see VS Code Extension.

Build from source

# Linux / macOS
./scripts/build-release.sh ./dist/eta-release
cd dist/eta-release && ./install.sh

# Windows (PowerShell)
.\scripts\build-release.ps1 .\dist\eta-release
cd dist\eta-release; .\install.cmd

Full prerequisites, manual CMake steps, and CI details: Building from Source. The release archive layout (bin/, lib/, stdlib/, editors/) is documented in Quick Start.

Tip

See TLDR.md for a step-by-step walkthrough with screenshots, or Quick Start for the full reference. A guided tour of the example programs lives in the Language Guide.

---

Compilation Pipeline

Every Eta source file flows through six phases before execution. The Driver class orchestrates the full pipeline and owns the runtime state:

flowchart LR
    SRC["Source\n(.eta)"] --> LEX["Lexer"]
    LEX --> PAR["Parser"]
    PAR --> EXP["Expander"]
    EXP --> LNK["Module\nLinker"]
    LNK --> SEM["Semantic\nAnalyzer"]
    SEM --> EMT["Emitter"]
    EMT --> VM["VM\nExecution"]
    EMT --> SER["Serialize\n(.etac)"]
    SER -.->|"etai fast-load"| VM

    style SRC fill:#2d2d2d,stroke:#58a6ff,color:#c9d1d9
    style LEX fill:#1a1a2e,stroke:#58a6ff,color:#c9d1d9
    style PAR fill:#1a1a2e,stroke:#58a6ff,color:#c9d1d9
    style EXP fill:#1a1a2e,stroke:#58a6ff,color:#c9d1d9
    style LNK fill:#16213e,stroke:#79c0ff,color:#c9d1d9
    style SEM fill:#16213e,stroke:#79c0ff,color:#c9d1d9
    style EMT fill:#0f3460,stroke:#56d364,color:#c9d1d9
    style VM  fill:#0f3460,stroke:#56d364,color:#c9d1d9
    style SER fill:#0f3460,stroke:#56d364,color:#c9d1d9

Loading

Phase	Input	Output	Header
Lexer	Raw UTF-8 text	Token stream	lexer.h
Parser	Tokens	S-expression AST (SExpr)	parser.h
Expander	SExpr trees	Desugared core forms + macros	expander.h
Module Linker	Expanded modules	Resolved imports/exports	module_linker.h
Semantic Analyzer	Linked modules	Core IR (Node graph)	semantic_analyzer.h
Emitter	Core IR	BytecodeFunctions	emitter.h
VM	Bytecode	Runtime values (LispVal)	vm.h

Note

Every phase reports errors through a unified DiagnosticEngine with span information.

---

Key Design Highlights

Feature	Detail
NaN-Boxing	All values are 64-bit; doubles pass through unboxed while tagged types (fixnums, chars, symbols, heap pointers) are encoded in the NaN mantissa. → Deep-dive
AOT Compilation	etac compiles .eta → .etac bytecode; etai loads .etac files directly, skipping all front-end phases. Supports -O optimization passes (constant folding, DCE). → Deep-dive
47-bit Fixnums	Integers up to ±70 trillion are stored inline — no heap allocation.
Mark-Sweep GC	Stop-the-world collector with sharded heap, hazard pointers, and a GC callback for auto-triggering on soft-limit. → Deep-dive
Tail-Call Elimination	TailCall and TailApply opcodes reuse the current stack frame.
First-Class Continuations	call/cc captures the full stack + winding stack; dynamic-wind is supported.
Hygienic Macros	syntax-rules with ellipsis patterns.
Module System	(module …) forms with import/export, only, except, rename filters. → Deep-dive
Arena Allocator	IR nodes are block-allocated in a 16 KB arena for cache locality.
Concurrent Heap	boost::unordered::concurrent_flat_map with 16 shards for lock-free reads.
LSP Integration	JSON-RPC language server for real-time diagnostics in any editor.
DAP Integration	Debug Adapter Protocol server (eta_dap) enables breakpoints, step-through debugging, call-stack inspection, and REPL-style expression evaluation directly in VS Code.
libtorch Integration	Native C++ bindings to PyTorch's backend for tensors, autograd, neural-network layers, optimizers, and GPU offload. → Deep-dive
nng Networking	Erlang-style actor model: spawn processes, send!/recv!, worker-pool for parallel fan-out, REQ/REP, PUB/SUB, SURVEYOR/RESPONDENT — network-transparent over IPC or TCP. → Deep-dive · Actor Model

---

Standard Library

The prelude auto-loads the following modules:

Module	Highlights
std.core	identity, compose, flip, constantly, iota, assoc-ref, list utilities
std.math	pi, e, square, gcd, lcm, expt, sum, product
std.io	println, eprintln, read-line, port redirection helpers
std.collections	map*, filter, foldl, foldr, sort, zip, range, vector ops
std.regex	regex:compile, regex:match?, regex:search, regex:find-all, regex:replace, regex:split
std.logic	==, copy-term, naf, findall, run1, run*, run-n — Prolog/miniKanren-style combinators
std.freeze	freeze, dif — suspended goals & structural disequality on attributed vars
std.db	defrel, assert, retract, call-rel, tabled — fact-table-backed relations with SLG-lite tabling
std.clp	clp:domain, clp:in-fd, clp:solve, clp:all-different, clp:labeling, clp:minimize/maximize — CLP(Z) and CLP(FD)
std.clpb	clp:boolean, clp:and/or/xor/imp/eq/not, clp:card, clp:sat?, clp:taut? — CLP(B) Boolean propagation
std.clpr	clp:real, clp:r<=, clp:r=, clp:r-minimize/maximize, clp:rq-minimize/maximize — CLP(R) linear + convex QP
std.causal	dag:*, do:identify, do:estimate-effect — causal inference engine
std.csv	csv:open-reader, csv:read-record, csv:read-typed-row, csv:open-writer, csv:save-file
std.fact_table	make-fact-table, fact-table-insert!, fact-table-query, fact-table-fold — columnar fact tables
std.stats	Descriptive stats, CIs, t-tests, OLS regression (Eigen-backed)
std.time	Wall-clock + monotonic time, UTC/local parts, ISO-8601 formatting
std.torch	tensor, forward, train-step!, sgd, adam — libtorch neural networks
std.net	spawn, send!, recv!, monitor, worker-pool, with-socket, request-reply, pub-sub, survey — Erlang-style actors & nng
std.supervisor	one-for-one, one-for-all — supervision trees over actor processes
std.test	assert-equal, assert-true, run-tests — lightweight test framework

(module my-app
  (import std.core)
  (import std.collections)
  (import std.io)
  (begin
    (define xs (iota 10))                    ;; (0 1 2 3 4 5 6 7 8 9)
    (println (filter odd? xs))               ;; (1 3 5 7 9)
    (println (foldl + 0 (filter even? xs)))  ;; 20
  ))

---

Documentation

The most-clicked pages — see docs/index.md for the full index (architecture deep-dives, every stdlib module, runtime internals, networking design, release notes, roadmap):

Page	Contents
Quick Start	Installing, running etai/etac, REPL, modules, VS Code extension
VS Code Extension	Install, configure, debugging, heap/disassembly/child-process panels, Test Explorer
Jupyter Kernel	eta_jupyter install, notebook gallery, rich-display helpers (jupyter:table, jupyter:plot, jupyter:dag)
Build from Source	Prerequisites, one-script builds, manual CMake, CI, testing, project layout
Architecture	Full system diagram, phase-by-phase walkthrough, Core IR node types
Bytecode & VM	Opcode reference, compilation trace, call stack model, TCO
Modules & Stdlib	Module syntax, linker phases, import filters, standard library reference
Language Guide	Guided tour of the language using simple example programs with expected output
AAD – Finance Examples	Reverse-mode AD walkthrough, xVA sensitivities, European Greeks, SABR vol surface
Causal Inference	Do-calculus engine, back-door adjustment, finance factor analysis
Portfolio Engine	End-to-end demo: do-calculus + CLP(R) QP + AAD risk + actor-parallel scenarios

---

License

See LICENSE for details.