Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture

tellegen is a differentiable power flow and optimal power flow engine written in Rust for native targets and WebAssembly. The public browser packages are @tellegen/engine, @tellegen/svelte, and @tellegen/webmcp; the SvelteKit hosted demo is one private consumer.

Repository layout

A Cargo workspace and a web app, side by side.

  • crates/tellegen: the engine. It parses a case through powerio and solves the requested supported formulation. One result envelope carries the fields and sensitivities that formulation defines.
  • crates/tellegen-wasm: the wasm-bindgen adapter that exposes the engine to the browser, built with wasm-pack.
  • crates/tellegen-server: a native HTTP server that serves the bundled cases and the static app.
  • crates/tellegen-cli: a command line front end over the engine’s JSON API.
  • crates/benchmarks: a private harness that runs the PGLib-OPF corpus for validation and timing.
  • packages/engine: the public browser engine package, TypeScript types generated from Rust, and browser wasm transport.
  • packages/svelte: the public Svelte component package for maps, panels, local case files, and browser solves.
  • packages/webmcp: WebMCP tool definitions, validation, and registration lifecycle.
  • apps/web: the private SvelteKit hosted demo that consumes @tellegen/svelte.
  • examples/browser-minimal: a minimal downstream app that imports @tellegen/engine directly.
  • examples/svelte-minimal: a minimal downstream app that imports @tellegen/svelte.

powerio owns parsing and the network and display formats; the engine and the app depend on it.

The engine

Default builds of crates/tellegen solve four formulations through one interface:

  • DC power flow and DC OPF: a B–θ linear/quadratic program;
  • AC power flow: a polar Newton solve; and
  • SOCWR: the Jabr second-order cone relaxation of AC OPF, in W-space.

The non-default native acopf feature adds a fifth, development-only path: an exact polar AC OPF model solved through POUNCE. It has independent primal validation and portable PowerIO solution emission, but no shipping adapter, dual/sensitivity contract, or distribution approval. A separate unpublished WASI adapter and one-shot worker expose the canonical base-case solve for development and CI; ordinary browser builds do not contain its POUNCE asset.

The formulations share one result envelope, but they do not claim the same quantities. DC power flow returns angles and branch flows without prices, optimized dispatch, or sensitivities. DC OPF adds dispatch, objective value, LMPs, and KKT sensitivities. AC power flow returns voltages and nodal injections with Newton sensitivities. SOCWR exposes the quantities and conic KKT sensitivities defined by the relaxation. Formulations that implement the Differentiable trait accept an output Operand and input Parameter; the common driver solves the retained KKT or Newton system for the requested forward or adjoint columns.

The default engine is Rust and compiles to WebAssembly, so the same code runs natively and in the browser. The convex solves use Clarabel; the sensitivities use faer. The exact AC OPF backend runs in opt-in native builds and in the separately built experimental WASI worker. Turning it into a shipping native product remains on the desktop and mobile roadmap; browser support uses a separate WASI worker because the ordinary browser solver build is single threaded and uses wasm32-unknown-unknown.

The two API faces

One numerical core, two faces that share a driver and a result type:

  • Stateless: solve_module(module, request) and capabilities_json(). Each call reads a PowerIO module, solves its declared problem instance, and returns.
  • Stateful: the Study. It starts from a PowerIO module and builds the private solver workspace once. commit applies a set of NetworkEdits and re-solves exactly, optionally returning the requested sensitivity columns in the same solve; preview returns a first order update at the committed point with no re-solve.

Browser packages

packages/engine is the reusable package surface. It exports the generated types, case and display parsing helpers, module based solves, capabilities, the browser Study, and the browser wasm transport. It has no SvelteKit dependency.

packages/svelte consumes @tellegen/engine and exports the map, panels, local file flow, solve card, state provider, and full viewer as Svelte components.

packages/webmcp exports tool definitions, runtime validation, and registration through an adapter that does not depend on Svelte or the engine package.

apps/web consumes the Svelte package and keeps demo concerns: routes, SEO, credits, privacy, deployment, and bundled case pages.

In the browser

@tellegen/engine ships one wasm package built from crates/tellegen-wasm (the conic feature): DC power flow, DC OPF, AC power flow, SOCWR, the Study, and the sensitivity columns. A browser that cannot load it does not solve; the hosted demo shows a notice, and the server’s compute endpoints exist as an opt-in fallback (TELLEGEN_SERVER_COMPUTE).

The Svelte package and the hosted app use Study for DC OPF, AC power flow, and SOCWR. preview returns a first order update for the quantities the chosen formulation defines; commit performs an exact re-solve and can return the displayed sensitivity column. DC power flow uses the stateless solve path, and full nonlinear AC OPF is unavailable in the shipping browser package. Supported solvable case files run in the browser and are not uploaded.

Sources

  • Rust to WebAssembly: wasm-bindgen, wasm-pack
  • Solvers and linear algebra: Clarabel.rs, faer
  • Convex relaxation: R. A. Jabr, “Radial distribution load flow using conic programming,” IEEE Transactions on Power Systems, 21(3), 2006.
  • Svelte: $state