@graphty/webgpu-graph-algorithms 0.6.26 → 0.6.28

package/README.md

@@ -1,13 +1,14 @@
 # @graphty/webgpu-graph-algorithms
 
 WebGPU-accelerated graph algorithms and layouts over the `@graphty/graph-format` snapshot, for Node
-(Dawn, through the `webgpu` npm package) and browsers (Chromium). One code base, three entry points:
+(Dawn, through the `webgpu` npm package) and browsers (Chromium). One code base, four entry points:
 
-| Entry                                      | Import        | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@graphty/webgpu-graph-algorithms`         | the core      | the layouts (`createForceAtlas2`, `createFruchtermanReingold`, `createSpringElectrical`, `seedPositions`), the algorithms (`pageRank`, `personalizedPageRank`, `hits`, `eigenvectorCentrality`, `katzCentrality`, `connectedComponents`, `degree`), `createAccelerator`, `calibrateLayout`, `verifyDevice`, `GpuContext`, `WebGpuGraphError`, `isSoftwareAdapter`, the constants (`EXACT_MAX_NODES`, `FA2_DEFAULTS`, `FR_DEFAULTS`, `SE_DEFAULTS`, `LAYOUT_TUNING_DEFAULTS`, ...) and the option / stats / accelerator types |
-| `@graphty/webgpu-graph-algorithms/node`    | Node only     | `createNodeGpuContext`, `probeNodeWebGpu`, `createNodeGpu` (Dawn), `dawnFlags`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `@graphty/webgpu-graph-algorithms/browser` | browsers only | `probeBrowserWebGpu`, `requestGpuContext`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Entry                                      | Import            | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@graphty/webgpu-graph-algorithms`         | the core          | the layouts (`createForceAtlas2`, `createFruchtermanReingold`, `createSpringElectrical`, `seedPositions`), the algorithms (`pageRank`, `personalizedPageRank`, `hits`, `eigenvectorCentrality`, `katzCentrality`, `connectedComponents`, `degree`), `createAccelerator`, `calibrateLayout`, `verifyDevice`, `GpuContext`, `WebGpuGraphError`, `isSoftwareAdapter`, the constants (`EXACT_MAX_NODES`, `FA2_DEFAULTS`, `FR_DEFAULTS`, `SE_DEFAULTS`, `LAYOUT_TUNING_DEFAULTS`, ...) and the option / stats / accelerator types |
+| `@graphty/webgpu-graph-algorithms/node`    | Node only         | `createNodeGpuContext`, `probeNodeWebGpu`, `createNodeGpu` (Dawn), `dawnFlags`, `acquireAccelerator`                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `@graphty/webgpu-graph-algorithms/browser` | browsers only     | `probeBrowserWebGpu`, `requestGpuContext`, `acquireAccelerator`                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `@graphty/webgpu-graph-algorithms/acquire` | Node and browsers | `acquireAccelerator`: the managed accelerator. The `browser` export condition resolves it to the browser build and `node` to the Node build, so one import line serves both and the two builds never meet in one bundle                                                                                                                                                                                                                                                                                                      |
 
 **Status: three force layouts and six algorithms, on the exact and the grid repulsion tiers.**
 ForceAtlas2, Fruchterman-Reingold and ngraph's spring-electrical preset run from Node (`run()`) and from a
@@ -319,6 +320,55 @@ or a non-finite `center` component is `E_INVALID_ARGUMENT`; the function returns
 
 ## Acquisition
 
+### One call: `acquireAccelerator`
+
+Most applications want "a working GPU accelerator, or the reason there is none". `acquireAccelerator` is that
+call, the same in Node and in a browser:
+
+```ts
+import { accelerated } from "@graphty/algorithms";
+import { acquireAccelerator } from "@graphty/webgpu-graph-algorithms/acquire";
+
+const gpu = acquireAccelerator(); // nothing is probed until the first current()
+
+const result = await gpu.current();
+if (!result.ok) {
+    console.warn(`running on the CPU: ${result.reason}`, result.fix ?? "");
+}
+// the GPU when there is one, the CPU otherwise
+const ranks = await accelerated(result.ok ? result.accelerator : null).pageRank(snapshot);
+
+gpu.dispose(); // when you are done: releases the device
+```
+
+The first `current()` probes for an adapter, opens a context, runs the device self-check (below) and builds the
+accelerator. Later calls return the same accelerator. After the device is lost, or after you dispose the
+accelerator, the next `current()` acquires a new device; a run that was in flight when the device was lost still
+fails with `E_DEVICE_LOST`, because finishing it somewhere else would hide the failure.
+
+`result.ok === false` is a decision made before any work runs, so running a CPU implementation then is detection,
+not a fallback. `result.code` says why:
+
+| Code                 | Meaning                                                                      | `result.fix`                                                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `E_NO_WEBGPU`        | no WebGPU in this runtime; in Node, the optional `webgpu` package is missing | Node: the install command; a browser page that is not a secure context: serve it over https or from localhost |
+| `E_NO_ADAPTER`       | WebGPU exists but no adapter answered                                        | null                                                                                                          |
+| `E_SOFTWARE_ONLY`    | the adapter is a software renderer (llvmpipe, SwiftShader, WARP)             | pass `acceptSoftware: true`                                                                                   |
+| `E_DEVICE_INCORRECT` | the device got a known prefix sum wrong; `result.check` says where           | null                                                                                                          |
+
+Options: `acceptSoftware` (default `false`: a software adapter is usually slower than the CPU), `powerPreference`
+(default `"high-performance"`), `accelerator` (passed to `createAccelerator`: layout tuning, betweenness
+defaults), `warnUnreleasedSnapshots`, and in Node `adapter` (a substring of the Dawn adapter name, such as
+`"4070"`; ignored in a browser). A decline is remembered for the life of the handle; create a new handle to ask
+again. Any other failure (a device request that failed) rejects `current()`, and the next call tries again.
+
+`@graphty/webgpu-graph-algorithms/acquire` has no build of its own: the `browser` export condition (and the
+default) resolves it to the `./browser` build, `node` to the `./node` build. The `./browser` and `./node`
+subpaths export the same `acquireAccelerator` for code that is only ever one or the other.
+
+The lower-level calls below are what it is made of, for when you need a context without an accelerator, your own
+device, or control over limits and features.
+
 ### Node
 
 ```ts

package/dist/acquire.d.ts

@@ -0,0 +1,2 @@
+export { acquireAccelerator } from "./src/browser/index.js";
+export type { AcceleratorDeclined, AcceleratorReady, AcquireAcceleratorOptions, AcquireResult, ManagedAccelerator } from "./src/types/managed.js";

package/dist/browser.js

@@ -1,4 +1,5 @@
-import { G as GpuContext, W as WebGpuGraphError } from "./chunks/context-BZY6SMsM.js";
+import { G as GpuContext, W as WebGpuGraphError } from "./chunks/accelerator-B-FjQwaA.js";
+import { m as manageAccelerator } from "./chunks/managed-D_GdQtnu.js";
 function navigatorGpu() {
   if (typeof navigator === "undefined") {
     return void 0;
@@ -25,7 +26,23 @@ function requestGpuContext(options) {
   }
   return GpuContext.create({ powerPreference: "high-performance", ...options, gpu, runtime: "browser" });
 }
+function acquireAccelerator(options) {
+  return manageAccelerator(
+    {
+      probe: (o, rejectSoftware) => probeBrowserWebGpu({ powerPreference: o.powerPreference, rejectSoftware }),
+      open: (o, probe, rejectSoftware) => requestGpuContext({
+        adapter: probe.adapter ?? void 0,
+        powerPreference: o.powerPreference,
+        rejectSoftware,
+        warnUnreleasedSnapshots: o.warnUnreleasedSnapshots
+      }),
+      noWebGpuFix: () => globalThis.isSecureContext === false ? "serve the page over https or from localhost: WebGPU needs a secure context" : null
+    },
+    options
+  );
+}
 export {
+  acquireAccelerator,
   probeBrowserWebGpu,
   requestGpuContext
 };

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sources":["../src/browser/index.ts"],"sourcesContent":["/// <reference types=\"@webgpu/types\" preserve=\"true\" />\n/**\n * The ./browser entry (spec 2.1, 2.3, 3.4; contract 3.6): the only directory of the package allowed to read\n * navigator.gpu. probeBrowserWebGpu never throws; requestGpuContext tags the context runtime \"browser\".\n */\n\nimport { GpuContext } from \"../context.js\";\nimport { WebGpuGraphError } from \"../errors.js\";\nimport type { GpuContextOptions, ProbeResult } from \"../types/context.js\";\n\n/** Options of the browser helpers (spec 3.4); a type alias, not an empty `extends` interface, which strictTypeChecked's no-empty-object-type (allowInterfaces \"never\") reports. */\nexport type BrowserGpuOptions = Omit<GpuContextOptions, \"gpu\" | \"device\" | \"runtime\">;\n\n/**\n * navigator.gpu, or undefined when the runtime has no navigator or no WebGPU (Node 22 has a navigator\n * without gpu; browsers without WebGPU have navigator.gpu undefined).\n * @returns the GPU object or undefined\n */\nfunction navigatorGpu(): GPU | undefined {\n    if (typeof navigator === \"undefined\") {\n        return undefined;\n    }\n    const candidate: { readonly gpu?: GPU | undefined } = navigator;\n    return candidate.gpu;\n}\n\n/**\n * navigator.gpu absent -> { ok: false, code: \"E_NO_WEBGPU\" }; else GpuContext.probe. Never throws.\n * @param options - the power preference and the software policy\n * @returns the probe result\n */\nexport function probeBrowserWebGpu(options?: BrowserGpuOptions): Promise<ProbeResult> {\n    return GpuContext.probe({\n        gpu: navigatorGpu(),\n        powerPreference: options?.powerPreference ?? \"high-performance\",\n        rejectSoftware: options?.rejectSoftware,\n    });\n}\n\n/**\n * GpuContext.create({ gpu: navigator.gpu, powerPreference: \"high-performance\", runtime: \"browser\", ...options });\n * pass `{ adapter: probe.adapter }` to reuse the probed adapter; create() honours rejectSoftware.\n * @param options - see BrowserGpuOptions\n * @returns the context\n */\nexport function requestGpuContext(options?: BrowserGpuOptions): Promise<GpuContext> {\n    const gpu = navigatorGpu();\n    if (gpu === undefined && options?.adapter === undefined) {\n        return Promise.reject(\n            new WebGpuGraphError(\"E_NO_WEBGPU\", \"navigator.gpu is undefined: this browser or context has no WebGPU\", {\n                reason: \"navigator.gpu is undefined\",\n                hint: \"WebGPU needs a supporting browser and a secure context (https or localhost)\",\n            }),\n        );\n    }\n    return GpuContext.create({ powerPreference: \"high-performance\", ...options, gpu, runtime: \"browser\" });\n}\n"],"names":[],"mappings":";AAkBA,SAAS,eAAgC;AACrC,MAAI,OAAO,cAAc,aAAa;AAClC,WAAO;AAAA,EACX;AACA,QAAM,YAAgD;AACtD,SAAO,UAAU;AACrB;AAOO,SAAS,mBAAmB,SAAmD;AAClF,SAAO,WAAW,MAAM;AAAA,IACpB,KAAK,aAAA;AAAA,IACL,iBAAiB,SAAS,mBAAmB;AAAA,IAC7C,gBAAgB,SAAS;AAAA,EAAA,CAC5B;AACL;AAQO,SAAS,kBAAkB,SAAkD;AAChF,QAAM,MAAM,aAAA;AACZ,MAAI,QAAQ,UAAa,SAAS,YAAY,QAAW;AACrD,WAAO,QAAQ;AAAA,MACX,IAAI,iBAAiB,eAAe,qEAAqE;AAAA,QACrG,QAAQ;AAAA,QACR,MAAM;AAAA,MAAA,CACT;AAAA,IAAA;AAAA,EAET;AACA,SAAO,WAAW,OAAO,EAAE,iBAAiB,oBAAoB,GAAG,SAAS,KAAK,SAAS,WAAW;AACzG;"}
+{"version":3,"file":"browser.js","sources":["../src/browser/index.ts"],"sourcesContent":["/// <reference types=\"@webgpu/types\" preserve=\"true\" />\n/**\n * The ./browser entry (spec 2.1, 2.3, 3.4; contract 3.6): the only directory of the package allowed to read\n * navigator.gpu. probeBrowserWebGpu never throws; requestGpuContext tags the context runtime \"browser\".\n */\n\nimport { GpuContext } from \"../context.js\";\nimport { WebGpuGraphError } from \"../errors.js\";\nimport { manageAccelerator } from \"../managed.js\";\nimport type { GpuContextOptions, ProbeResult } from \"../types/context.js\";\nimport type { AcquireAcceleratorOptions, ManagedAccelerator } from \"../types/managed.js\";\n\nexport type {\n    AcceleratorDeclined,\n    AcceleratorReady,\n    AcquireAcceleratorOptions,\n    AcquireResult,\n    ManagedAccelerator,\n} from \"../types/managed.js\";\n\n/** Options of the browser helpers (spec 3.4); a type alias, not an empty `extends` interface, which strictTypeChecked's no-empty-object-type (allowInterfaces \"never\") reports. */\nexport type BrowserGpuOptions = Omit<GpuContextOptions, \"gpu\" | \"device\" | \"runtime\">;\n\n/**\n * navigator.gpu, or undefined when the runtime has no navigator or no WebGPU (Node 22 has a navigator\n * without gpu; browsers without WebGPU have navigator.gpu undefined).\n * @returns the GPU object or undefined\n */\nfunction navigatorGpu(): GPU | undefined {\n    if (typeof navigator === \"undefined\") {\n        return undefined;\n    }\n    const candidate: { readonly gpu?: GPU | undefined } = navigator;\n    return candidate.gpu;\n}\n\n/**\n * navigator.gpu absent -> { ok: false, code: \"E_NO_WEBGPU\" }; else GpuContext.probe. Never throws.\n * @param options - the power preference and the software policy\n * @returns the probe result\n */\nexport function probeBrowserWebGpu(options?: BrowserGpuOptions): Promise<ProbeResult> {\n    return GpuContext.probe({\n        gpu: navigatorGpu(),\n        powerPreference: options?.powerPreference ?? \"high-performance\",\n        rejectSoftware: options?.rejectSoftware,\n    });\n}\n\n/**\n * GpuContext.create({ gpu: navigator.gpu, powerPreference: \"high-performance\", runtime: \"browser\", ...options });\n * pass `{ adapter: probe.adapter }` to reuse the probed adapter; create() honours rejectSoftware.\n * @param options - see BrowserGpuOptions\n * @returns the context\n */\nexport function requestGpuContext(options?: BrowserGpuOptions): Promise<GpuContext> {\n    const gpu = navigatorGpu();\n    if (gpu === undefined && options?.adapter === undefined) {\n        return Promise.reject(\n            new WebGpuGraphError(\"E_NO_WEBGPU\", \"navigator.gpu is undefined: this browser or context has no WebGPU\", {\n                reason: \"navigator.gpu is undefined\",\n                hint: \"WebGPU needs a supporting browser and a secure context (https or localhost)\",\n            }),\n        );\n    }\n    return GpuContext.create({ powerPreference: \"high-performance\", ...options, gpu, runtime: \"browser\" });\n}\n\n/**\n * The managed accelerator on navigator.gpu: probe, context, device self-check and accelerator on the first\n * `current()`, a new device after a loss, disposal by `dispose()`. A software adapter is declined unless\n * `acceptSoftware` is set. The same function as the `./acquire` subpath resolves to in a browser.\n * @param options - see AcquireAcceleratorOptions; `adapter` is ignored here\n * @returns the handle; nothing is probed until `current()` is called\n */\nexport function acquireAccelerator(options?: AcquireAcceleratorOptions): ManagedAccelerator {\n    return manageAccelerator(\n        {\n            probe: (o, rejectSoftware) => probeBrowserWebGpu({ powerPreference: o.powerPreference, rejectSoftware }),\n            open: (o, probe, rejectSoftware) =>\n                requestGpuContext({\n                    adapter: probe.adapter ?? undefined,\n                    powerPreference: o.powerPreference,\n                    rejectSoftware,\n                    warnUnreleasedSnapshots: o.warnUnreleasedSnapshots,\n                }),\n            noWebGpuFix: () =>\n                (globalThis as { isSecureContext?: boolean }).isSecureContext === false\n                    ? \"serve the page over https or from localhost: WebGPU needs a secure context\"\n                    : null,\n        },\n        options,\n    );\n}\n"],"names":[],"mappings":";;AA4BA,SAAS,eAAgC;AACrC,MAAI,OAAO,cAAc,aAAa;AAClC,WAAO;AAAA,EACX;AACA,QAAM,YAAgD;AACtD,SAAO,UAAU;AACrB;AAOO,SAAS,mBAAmB,SAAmD;AAClF,SAAO,WAAW,MAAM;AAAA,IACpB,KAAK,aAAA;AAAA,IACL,iBAAiB,SAAS,mBAAmB;AAAA,IAC7C,gBAAgB,SAAS;AAAA,EAAA,CAC5B;AACL;AAQO,SAAS,kBAAkB,SAAkD;AAChF,QAAM,MAAM,aAAA;AACZ,MAAI,QAAQ,UAAa,SAAS,YAAY,QAAW;AACrD,WAAO,QAAQ;AAAA,MACX,IAAI,iBAAiB,eAAe,qEAAqE;AAAA,QACrG,QAAQ;AAAA,QACR,MAAM;AAAA,MAAA,CACT;AAAA,IAAA;AAAA,EAET;AACA,SAAO,WAAW,OAAO,EAAE,iBAAiB,oBAAoB,GAAG,SAAS,KAAK,SAAS,WAAW;AACzG;AASO,SAAS,mBAAmB,SAAyD;AACxF,SAAO;AAAA,IACH;AAAA,MACI,OAAO,CAAC,GAAG,mBAAmB,mBAAmB,EAAE,iBAAiB,EAAE,iBAAiB,gBAAgB;AAAA,MACvG,MAAM,CAAC,GAAG,OAAO,mBACb,kBAAkB;AAAA,QACd,SAAS,MAAM,WAAW;AAAA,QAC1B,iBAAiB,EAAE;AAAA,QACnB;AAAA,QACA,yBAAyB,EAAE;AAAA,MAAA,CAC9B;AAAA,MACL,aAAa,MACR,WAA6C,oBAAoB,QAC5D,+EACA;AAAA,IAAA;AAAA,IAEd;AAAA,EAAA;AAER;"}