Metadata-Version: 2.4
Name: tellegen
Version: 0.6.2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Requires-Dist: mcp>=2,<3 ; extra == 'mcp'
Requires-Dist: powerio>=0.11.3,<0.12 ; extra == 'mcp'
Provides-Extra: mcp
License-File: LICENSE
Summary: DC optimal power flow, AC power flow, SOCWR, and KKT sensitivities.
Keywords: opf,power-flow,power-systems,sensitivity,lmp
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://eigenergy.github.io/tellegen/
Project-URL: Homepage, https://tellegen.dev
Project-URL: Repository, https://github.com/eigenergy/tellegen

<p align="center">
  <img src="docs/assets/hero.svg" alt="tellegen power system visualization" width="100%">
</p>

# tellegen

[![CI](https://github.com/eigenergy/tellegen/actions/workflows/ci.yml/badge.svg)](https://github.com/eigenergy/tellegen/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/tellegen.svg?label=crates.io)](https://crates.io/crates/tellegen)
[![npm](https://img.shields.io/npm/v/%40tellegen%2Fengine.svg?label=%40tellegen%2Fengine)](https://www.npmjs.com/package/@tellegen/engine)
[![npm](https://img.shields.io/npm/v/%40tellegen%2Fsvelte.svg?label=%40tellegen%2Fsvelte)](https://www.npmjs.com/package/@tellegen/svelte)
[![docs](https://img.shields.io/badge/docs-eigenergy.github.io%2Ftellegen-blue)](https://eigenergy.github.io/tellegen/)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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](https://github.com/eigenergy/powerio). The project is named for
Tellegen's theorem.

Live demo: [tellegen.dev](https://tellegen.dev). Documentation:
[eigenergy.github.io/tellegen](https://eigenergy.github.io/tellegen/).

## Packages

```sh
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](docs/src/webmcp.md).
Start with the
[framework quickstart](https://eigenergy.github.io/tellegen/framework-quickstart.html);
`examples/browser-minimal/` and `examples/svelte-minimal/` are working
integrations of each package.

### Rust

The solver itself is the [tellegen](https://crates.io/crates/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](https://crates.io/crates/powerio).

```sh
cargo add tellegen powerio serde_json
```

```rust
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](https://eigenergy.github.io/tellegen/multiconductor-pf.html)
page, with the full API reference in the
[multiconductor power-flow guide](https://github.com/eigenergy/tellegen/blob/main/docs/multiconductor-power-flow.md).

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

| case        | territory        | buses | branches |
| ----------- | ---------------- | ----: | -------: |
| ACTIVSg200  | central Illinois |   200 |      245 |
| ACTIVSg500  | South Carolina   |   500 |      597 |
| ACTIVSg7000 | Texas            |  6717 |     9140 |
| CATS        | California       |  8870 |    10823 |

Self-hosted deployments can also register distribution feeders through an
optional [`distribution-cases.json` manifest](docs/src/deployment.md#hosted-distribution-cases).
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](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.

```sh
# 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:

```sh
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](https://eigenergy.github.io/tellegen/http-api.html),
[deployment](https://eigenergy.github.io/tellegen/deployment.html), and
[roadmap](https://eigenergy.github.io/tellegen/direction.html) 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](https://doi.org/10.1145/3847238.3849038),
[arXiv:2610.01922](https://arxiv.org/abs/2610.01922)). Please cite it, and the
software release you used; GitHub's "Cite this repository" button reads
[`CITATION.cff`](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

```bibtex
@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](LICENSE). See
[docs/src/third-party-notices.md](docs/src/third-party-notices.md) for
attributions.

