@tellegen/engine 0.3.0 → 0.4.1

package/README.md

@@ -17,6 +17,23 @@ import {
 The wasm files are resolved relative to the package module. Host apps must serve
 package asset files from `node_modules`.
 
+A host that preloads or budgets the engine's two large assets names them by
+export rather than by path: `@tellegen/engine/wasm` is the WebAssembly binary
+and `@tellegen/engine/places` the populated places table. In Vite, import them
+with `?url`:
+
+```ts
+import engineWasmUrl from "@tellegen/engine/wasm?url";
+import placesUrl from "@tellegen/engine/places?url";
+```
+
+Elsewhere, `import.meta.resolve("@tellegen/engine/wasm")` gives the file's URL.
+`syntheticPlacesUrl()` returns the places table's URL at run time.
+
+Under a Content Security Policy the engine needs `script-src 'wasm-unsafe-eval'`
+(to compile WebAssembly; never `'unsafe-eval'`) and `worker-src 'self'`: its
+workers are same-origin module workers.
+
 ## Browser Ingestion
 
 Case and JSON entry points accept the original bytes:
@@ -42,6 +59,39 @@ bare model JSON is now `unknown`; regenerate it as `pio-ir` from source data.
 Every API that accepts a byte buffer rejects inputs larger than
 `MAX_ENGINE_INPUT_BYTES` (128 MiB) before worker dispatch.
 
+## Synthetic Grid Generation
+
+`createSynthSession(request, { osm?, places?, signal? })` generates a
+geo-referenced transmission grid for a region, one stage per `advance()`, on a
+dedicated worker. Request and report types come from `@tellegen/engine/synth`.
+The populated places table ships as `dist/data/populated_places.json`;
+`syntheticPlacesUrl()`, `fetchSyntheticPlaces()` and `loadSyntheticPlaces()`
+locate and load it. The
+[synthetic generation guide](https://eigenergy.github.io/tellegen/synthetic-generation.html)
+describes the stages, the demand model and the evidence.
+
+## Data Sources
+
+The package ships data from third parties:
+
+- **Natural Earth** v5.1.2 populated places (`dist/data/populated_places.json`,
+  which names the release and its source file's SHA-256) and country areas
+  (compiled into the wasm): public domain,
+  [naturalearthdata.com](https://www.naturalearthdata.com/about/terms-of-use/).
+- **Ember**, *Yearly Electricity Data*, through **Our World in Data**,
+  *Energy dataset*: national electricity demand, compiled into the wasm.
+  Licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/);
+  the table keeps each country's latest year, so changes were made. Its
+  population column is Our World in Data's series, compiled from the sources
+  at [ourworldindata.org/population-sources](https://ourworldindata.org/population-sources).
+- **National transmission voltage levels**, compiled into the wasm from the
+  operator, regulator and standards documents each entry cites.
+
+Grids generated with `source: "osm"` contain data from OpenStreetMap, ©
+OpenStreetMap contributors, under the ODbL 1.0. The
+[third-party notices](https://eigenergy.github.io/tellegen/third-party-notices.html)
+give the full credits.
+
 ## Migrating To 0.2
 
 - Pass `Uint8Array` to `ingestCase`. For an existing string, use
@@ -56,20 +106,20 @@ Every API that accepts a byte buffer rejects inputs larger than
   `kind: "distribution"` with a `format`; `not-json` is `unknown`; and
   `transmission` and `ambiguous` are additional outcomes.
 
-## Contracts
+## Generated types
 
-The public contract version is `CONTRACT_VERSION`, which matches the package version. `CONTRACT_SOURCE_SHA256` records the `crates/tellegen/src/api.rs` content used to generate `src/generated/contracts.ts`.
+`ENGINE_VERSION` is the package version. `API_SOURCE_SHA256` records the `crates/tellegen/src/api.rs` content used to generate `src/generated/api-types.ts`.
 
 Run the generator after Rust API changes:
 
 ```sh
-npm run contracts
+npm run types
 ```
 
 CI runs `npm run build:engine` from the repository root, and that runs
-`contracts:check`. A stale generated contract fails the build.
+`types:check`. Stale generated types fail the build.
 
-Breaking contract changes:
+Breaking changes to the generated types:
 
 - Removing or renaming exported request or response fields.
 - Changing field units, enum tags, formulation ids, solve status tags, or sensitivity operand/parameter shapes.
@@ -95,3 +145,13 @@ npm run pack:engine
 Svelte package. It releases through Changesets with the other npm packages. The
 hosted demo under `apps/web` is private and consumes `@tellegen/svelte` through
 the same workspace file dependency used by the local examples.
+
+## Citing
+
+If you use this package in published work, please cite the tellegen paper:
+Samuel Talkington, Frederik Geth, Qian Zhang, Le Xie, and Skyler Liu. 2026.
+*Interactive Power Flow in the Browser*. The Inaugural ACM Conference on Digital
+Transformation (ACM DXConf 2026), Ann Arbor, MI, USA.
+[doi:10.1145/3847238.3849038](https://doi.org/10.1145/3847238.3849038). The
+[repository README](https://github.com/eigenergy/tellegen#citing) has the BibTeX
+entry.