tellegen

Browser visualization for DC OPF, AC power flow, SOCWR, and their sensitivities. Demand and rating edits preview through KKT sensitivity columns and commit as fresh solves in WebAssembly. Case parsing uses powerio. The project is named for Tellegen's theorem.

Live demo: tellegen.dev. Documentation: eigenergy.github.io/tellegen.

Packages

npm install @tellegen/engine   # case parsing and wasm solves, framework agnostic
npm install @tellegen/webmcp   # WebMCP tools and host adapter
npm install @tellegen/analytics # allowlisted, cookieless usage analytics
# map, panels, and solve card as Svelte components, with the map libraries
# they take as peer dependencies
npm install @tellegen/svelte maplibre-gl @deck.gl/core @deck.gl/layers @deck.gl/maplibre

@tellegen/engine exports case parsing, browser solving, the Study preview and commit calls, sensitivities, and generated TypeScript types. @tellegen/svelte exports the map, panels, local file flow, and solve card. @tellegen/webmcp exports the general OPF tools and the conditionally registered propose_capacity_plan and apply_capacity_plan tools through an adapter that does not depend on a UI framework. The hosted demo connects the live Svelte controller to that adapter. See the WebMCP guide. Start with the framework quickstart; examples/browser-minimal/ and examples/svelte-minimal/ are working integrations of each package.

Python

Python 3.11 and newer can install the native engine from PyPI:

python -m pip install tellegen

import tellegen

solution = tellegen.load("case30.m").solve()

The optional MCP server runs the engine in process over stdio:

python -m pip install "tellegen[mcp]"
tellegen-mcp

See the Python guide for calculations, source builds, and the MCP filesystem policy.

Rust

The solver itself is the tellegen crate. The packages above are WebAssembly bindings over it, so a Rust consumer skips them and calls it directly. Case parsing stays in powerio.

cargo add tellegen powerio serde_json

use tellegen::{solve_instance, SolveRequest};

let parsed = powerio::parse(powerio::Source::open("case30.m")?)?;
let network_module = tellegen::ir::balanced_module(parsed)?;
let instance = powerio::DcOpfInstance::from_network(network_module.value().clone())?;

// A DC OPF with bus 2 shifted 50 MW, and the LMP column against demand.
let request: SolveRequest = serde_json::from_str(
    r#"{
        "formulation": "dcopf",
        "edits": { "deltas": { "2": 50.0 } },
        "sensitivities": [
            { "operand": {"Price":"Active"}, "parameter": {"Demand":"Active"} }
        ]
    }"#,
)?;

let solved = solve_instance(&instance, &request).map_err(|e| e.to_string())?;
println!("{:?} objective {:?}", solved.status, solved.objective);

solve_module_json takes and returns JSON strings for callers that hold a stored PowerIO module. It accepts modules containing a balanced network or a declared problem instance; it does not accept bare network JSON. Default features carry the differentiable engine: DC OPF, AC power flow, and the KKT sensitivities. conic adds the SOCWR relaxation and its sensitivities. --no-default-features drops faer and num-complex and leaves the DC OPF solve on its own.

tellegen-cli wraps the same call for scripting: it reads a stored PowerIO module on stdin and writes the solve response to stdout. The request is the first argument, or @PATH to read it from a file when it is larger than the operating system's argument limit (about 128 KB on Linux). Its solve-module command writes an exact PowerIO solution module.

The multiconductor constant-power API, supported transformer profile, units, convergence options, and raw BMOPF limitations are documented in the multiconductor power flow page, with the full API reference in the multiconductor power-flow guide.

Demo

The demo serves three TAMU ACTIVSg synthetic grids and the CATS California Test System. These are synthetic networks on geographic footprints, not surveyed infrastructure:

Self-hosted deployments can also register distribution feeders through an optional distribution-cases.json manifest. Portable PowerIO multiconductor modules open in the distribution viewer and can run supported AC power flow in the browser.

Bus color is locational marginal price. Selecting a bus shows ∂LMP/∂demand at that bus; selecting a binding line shows ∂LMP/∂rating. Dragging a slider applies the sensitivity column live; releasing it re-solves exactly in WebAssembly. The calculation selector offers DC OPF (the default), AC power flow, SOCWR, and experimental nonlinear AC OPF for balanced transmission cases. The website bundles the separate POUNCE WASI solver and enables AC OPF after its browser capability probe succeeds. AC OPF currently solves the unedited base case; demand/rating edits, LMPs, sensitivities, and saving/exporting AC OPF results are not supported.

Dropped .m, .raw, .aux, .epc, .pwb, .dss, and recognized JSON cases parse in the browser and never upload. Files with coordinates render in place; files without can be placed by clicking the map or paired with .csv, .json, or .geojson geography (powerio's GeoLayer reader; branch routes render as polylines). A PowerWorld .pwd file renders as approximate substation positions, or fills a sibling case without coordinates through its substation numbers. Saved PowerIO modules and exports carry the placement, and the layout downloads as a .geo.json layer.

Development

Prerequisites: Rust from rust-toolchain.toml with rustfmt, clippy, and the wasm32-unknown-unknown target; Node.js 22 or newer; wasm-pack 0.15.x; mdBook 0.5.x for docs.

# backend with the embedded fallback cases
TELLEGEN_ALLOW_FALLBACK=1 cargo run -p tellegen-server

# frontend demo (the dev server proxies /api to localhost:8000)
npm ci
npm run wasm
rustup target add wasm32-wasip1
npm run wasm:acopf
npm run build:engine
npm run build:webmcp
npm run build:analytics
npm run build:svelte
npm --workspace tellegen-frontend run dev

Tests:

cargo test --workspace --exclude tellegen-py
npm run check && npm run build && npm run smoke:web && npm run test:downstream

Case data comes from the operator, not the repository. With the ACTIVSg and CATS distributions under ~/Datasets, scripts/stage-data.sh ~/Datasets stages the complete cases into data/; the server serves whatever is staged.

Repository layout

• crates/: Rust workspace — tellegen (engine), tellegen-synth (geographic synthetic grids), tellegen-wasm (WebAssembly), tellegen-server (HTTP), tellegen-cli, benchmarks
• packages/engine/: @tellegen/engine browser package
• packages/svelte/: @tellegen/svelte component package
• packages/webmcp/: reusable WebMCP tools, validation, and registration
• packages/analytics/: @tellegen/analytics, the allowlisted usage analytics shared with MapToGrid
• apps/web/: the hosted demo, a SvelteKit consumer of the Svelte package
• examples/: minimal Vite and Svelte integrations of each package
• docs/src/: mdBook source; scripts/build-docs.sh builds it
• docs/evidence/: checked-in measurement records (generator sweeps, WebMCP challenge runs, studies, multiconductor references) and the scripts that reproduce them

The HTTP API, deployment, and roadmap pages cover the server surface, hosting, and where the project is going.

Citing

tellegen is described in Interactive Power Flow in the Browser, presented at the Inaugural ACM Conference on Digital Transformation (ACM DXConf 2026, Ann Arbor, October 2026; doi:10.1145/3847238.3849038, arXiv:2610.01922). Please cite it, and the software release you used; GitHub's "Cite this repository" button reads CITATION.cff.

Samuel Talkington, Frederik Geth, Qian Zhang, Le Xie, and Skyler Liu. 2026. Interactive Power Flow in the Browser. In The Inaugural ACM Conference on Digital Transformation (ACM DXConf 2026), October 29–30, 2026, Ann Arbor, MI, USA. ACM, New York, NY, USA, 9 pages. https://doi.org/10.1145/3847238.3849038

@inproceedings{talkington2026tellegen,
  title     = {Interactive Power Flow in the Browser},
  author    = {Talkington, Samuel and Geth, Frederik and Zhang, Qian and Xie, Le and Liu, Skyler},
  booktitle = {The Inaugural ACM Conference on Digital Transformation (ACM DXConf 2026)},
  year      = {2026},
  month     = oct,
  location  = {Ann Arbor, MI, USA},
  publisher = {Association for Computing Machinery},
  address   = {New York, NY, USA},
  numpages  = {9},
  isbn      = {979-8-4007-3028-3},
  doi       = {10.1145/3847238.3849038},
  eprint    = {2610.01922},
  archivePrefix = {arXiv}
}

@software{tellegen2026software,
  title     = {tellegen: interactive power flow and optimal power flow in the browser},
  author    = {Talkington, Samuel and Geth, Frederik and Zhang, Qian and Xie, Le and Liu, Skyler},
  year      = {2026},
  version   = {0.4.0},
  url       = {https://github.com/eigenergy/tellegen},
  license   = {MIT}
}

License

MIT. See docs/src/third-party-notices.md for attributions.