dress-graph 0.3.1 → 0.5.0

package/README.md

@@ -2,28 +2,19 @@
 
 **A Continuous Framework for Structural Graph Refinement**
 
-DRESS is a provably continuous relaxation of the Weisfeiler–Leman algorithm.
-At depth k, higher-order DRESS is **provably at least as powerful as (k+2)-WL**
-in expressiveness — the base algorithm (k=0) already matches 2-WL, and each
-level adds one WL dimension.
-Yet it is dramatically cheaper to compute: a single DRESS run costs
-O(I · m · d_max) where I is the number of iterations, and depth-k requires
-C(n,k) independent runs — a total of O(C(n,k) · I · m · d_max), compared to
-O(n^(k+3)) for (k+2)-WL.  Space complexity is O(n + m), compared to
-O(n^(k+2)) for (k+2)-WL.
-The algorithm is embarrassingly parallel in two orthogonal ways — across the
-C(n,k) subproblems and across edge updates within each iteration — enabling
-distributed/cloud and multi-core/GPU/SIMD implementations.
+DRESS is a deterministic, parameter-free framework that iteratively refines the structural similarity of edges in a graph to produce a canonical fingerprint: a real-valued edge vector, obtained by converging a non-linear dynamical system to its unique fixed point. The fingerprint is isomorphism-invariant by construction, numerically stable (no overflow, no error amplification, no undefined behavior), fast and embarrassingly parallel to compute: DRESS total runtime is O(I * m * d_max) for I iterations to convergence, and convergence is guaranteed by Birkhoff contraction.
 
 ## Quick start
 
 ```javascript
-const dress = require('./dress_wasm.cjs');
+import { dressFit } from 'dress-graph';
 
-dress.onReady(() => {
-  const result = dress.dressFit(4, [0, 1, 2, 0], [1, 2, 3, 3]);
-  console.log(result.edgeDress);
+const result = await dressFit({
+  numVertices: 4,
+  sources:     [0, 1, 2, 0],
+  targets:     [1, 2, 3, 3],
 });
+console.log(result.edgeDress);
 ```
 
 For the full API and documentation, see the [main repository](https://github.com/velicast/dress-graph).

package/dress.d.ts

@@ -24,7 +24,7 @@ export interface DressOptions {
     maxIterations?: number;
     /** Convergence threshold (default: 1e-6) */
     epsilon?: number;
-    /** Pre-compute neighbourhood intercepts (default: true) */
+    /** Pre-compute neighbourhood intercepts (default: false) */
     precomputeIntercepts?: boolean;
 }
 
@@ -50,6 +50,33 @@ export interface DressResult {
  */
 export declare function dressFit(opts: DressOptions): Promise<DressResult>;
 
+export interface DressGraphOptions {
+    /** Number of vertices (vertex ids must be in 0..numVertices-1) */
+    numVertices: number;
+    /** Edge source vertices (0-based) */
+    sources: Int32Array | number[];
+    /** Edge target vertices (0-based) */
+    targets: Int32Array | number[];
+    /** Optional edge weights (same length as sources) */
+    weights?: Float64Array | number[] | null;
+    /** Graph variant (default: Variant.UNDIRECTED) */
+    variant?: number;
+    /** Pre-compute neighbourhood intercepts (default: false) */
+    precomputeIntercepts?: boolean;
+}
+
+/**
+ * A persistent DRESS graph supporting repeated fit / get calls.
+ */
+export declare class DressGraph {
+    private constructor();
+    static create(opts: DressGraphOptions): Promise<DressGraph>;
+    fit(maxIterations?: number, epsilon?: number): { iterations: number; delta: number };
+    get(u: number, v: number, maxIterations?: number, epsilon?: number, edgeWeight?: number): number;
+    result(): DressResult;
+    free(): void;
+}
+
 export interface DeltaDressOptions {
     /** Number of vertices (vertex ids must be in 0..numVertices-1) */
     numVertices: number;
@@ -89,3 +116,4 @@ export interface DeltaDressResult {
  * all k-vertex subsets and measuring edge similarity changes.
  */
 export declare function deltaDressFit(opts: DeltaDressOptions): Promise<DeltaDressResult>;
+

package/dress.js

@@ -66,7 +66,7 @@ export const Variant = Object.freeze({
  * @property {number} [variant=0]                   - Variant (see Variant enum)
  * @property {number} [maxIterations=100]           - Max fitting iterations
  * @property {number} [epsilon=1e-6]                - Convergence threshold
- * @property {boolean} [precomputeIntercepts=true]  - Pre-compute intercepts
+ * @property {boolean} [precomputeIntercepts=false]  - Pre-compute intercepts
  */
 
 /**
@@ -102,7 +102,7 @@ export async function dressFit(opts) {
     const variant     = opts.variant ?? Variant.UNDIRECTED;
     const maxIter     = opts.maxIterations ?? 100;
     const epsilon     = opts.epsilon ?? 1e-6;
-    const precompute  = (opts.precomputeIntercepts ?? true) ? 1 : 0;
+    const precompute  = (opts.precomputeIntercepts ?? false) ? 1 : 0;
 
     // Allocate C arrays (ownership transfers to dress.c — freed by free_dress_graph)
     const uPtr = M._malloc(E * 4);
@@ -138,8 +138,8 @@ export async function dressFit(opts) {
     const iterPtr  = M._malloc(4);  // int*
     const deltaPtr = M._malloc(8);  // double*
 
-    // Call fit
-    M._fit(g, maxIter, epsilon, iterPtr, deltaPtr);
+    // Call dress_fit
+    M._dress_fit(g, maxIter, epsilon, iterPtr, deltaPtr);
 
     const iterations = M.getValue(iterPtr, 'i32');
     const delta      = M.getValue(deltaPtr, 'double');
@@ -201,6 +201,162 @@ export async function dressFit(opts) {
     };
 }
 
+// ── Persistent DressGraph class ─────────────────────────────────────
+
+/**
+ * A persistent DRESS graph that supports repeated fit and get calls.
+ *
+ * Usage:
+ *   const g = await DressGraph.create({
+ *     numVertices: 4,
+ *     sources: [0,1,2,0],
+ *     targets: [1,2,3,3],
+ *   });
+ *   g.fit();                          // fit with defaults
+ *   const d = g.get(0, 2);           // virtual edge query
+ *   const res = g.result();          // snapshot of current results
+ *   g.free();                        // explicitly free C graph
+ */
+export class DressGraph {
+    /** @private */
+    constructor(module, gPtr, n, e, sources, targets) {
+        this._M = module;
+        this._g = gPtr;
+        this._n = n;
+        this._e = e;
+        this._sources = new Int32Array(sources);
+        this._targets = new Int32Array(targets);
+        this._iterPtr  = module._malloc(4);
+        this._deltaPtr = module._malloc(8);
+    }
+
+    /**
+     * Create a persistent DressGraph.
+     *
+     * @param {Object} opts
+     * @param {number}              opts.numVertices
+     * @param {Int32Array|number[]} opts.sources
+     * @param {Int32Array|number[]} opts.targets
+     * @param {Float64Array|number[]|null} [opts.weights]
+     * @param {number} [opts.variant=0]
+     * @param {boolean} [opts.precomputeIntercepts=false]
+     * @returns {Promise<DressGraph>}
+     */
+    static async create(opts) {
+        const M = await getModule();
+
+        const N = opts.numVertices;
+        const E = opts.sources.length;
+
+        if (opts.targets.length !== E)
+            throw new Error('sources and targets must have equal length');
+
+        const variant    = opts.variant ?? Variant.UNDIRECTED;
+        const precompute = (opts.precomputeIntercepts ?? false) ? 1 : 0;
+
+        const uPtr = M._malloc(E * 4);
+        const vPtr = M._malloc(E * 4);
+        for (let i = 0; i < E; i++) {
+            M.HEAP32[(uPtr >> 2) + i] = opts.sources[i];
+            M.HEAP32[(vPtr >> 2) + i] = opts.targets[i];
+        }
+
+        let wPtr = 0;
+        if (opts.weights && opts.weights.length === E) {
+            wPtr = M._malloc(E * 8);
+            for (let i = 0; i < E; i++) {
+                M.HEAPF64[(wPtr >> 3) + i] = opts.weights[i];
+            }
+        }
+
+        const g = M._init_dress_graph(N, E, uPtr, vPtr, wPtr, variant, precompute);
+        if (g === 0) throw new Error('init_dress_graph returned NULL');
+
+        return new DressGraph(M, g, N, E, opts.sources, opts.targets);
+    }
+
+    /**
+     * Fit the DRESS model.
+     * @param {number} [maxIterations=100]
+     * @param {number} [epsilon=1e-6]
+     * @returns {{iterations: number, delta: number}}
+     */
+    fit(maxIterations = 100, epsilon = 1e-6) {
+        if (!this._g) throw new Error('DressGraph already freed');
+        const M = this._M;
+        M._dress_fit(this._g, maxIterations, epsilon, this._iterPtr, this._deltaPtr);
+        return {
+            iterations: M.getValue(this._iterPtr, 'i32'),
+            delta:      M.getValue(this._deltaPtr, 'double'),
+        };
+    }
+
+    /**
+     * Query the DRESS value for an edge (existing or virtual).
+     * @param {number} u - source vertex (0-based)
+     * @param {number} v - target vertex (0-based)
+     * @param {number} [maxIterations=100]
+     * @param {number} [epsilon=1e-6]
+     * @param {number} [edgeWeight=1.0]
+     * @returns {number}
+     */
+    get(u, v, maxIterations = 100, epsilon = 1e-6, edgeWeight = 1.0) {
+        if (!this._g) throw new Error('DressGraph already freed');
+        return this._M._dress_get(this._g, u, v, maxIterations, epsilon, edgeWeight);
+    }
+
+    /**
+     * Extract a snapshot of the current results.
+     * @returns {DressResult}
+     */
+    result() {
+        if (!this._g) throw new Error('DressGraph already freed');
+        const M = this._M;
+        const E = this._e;
+        const N = this._n;
+
+        // WASM32 offsets
+        const ewPtr = M.getValue(this._g + 36, 'i32');
+        const edPtr = M.getValue(this._g + 40, 'i32');
+        const ndPtr = M.getValue(this._g + 48, 'i32');
+
+        const edgeWeight = new Float64Array(E);
+        const edgeDress  = new Float64Array(E);
+        const nodeDress  = new Float64Array(N);
+
+        for (let i = 0; i < E; i++) {
+            edgeWeight[i] = M.HEAPF64[(ewPtr >> 3) + i];
+            edgeDress[i]  = M.HEAPF64[(edPtr >> 3) + i];
+        }
+        for (let i = 0; i < N; i++) {
+            nodeDress[i] = M.HEAPF64[(ndPtr >> 3) + i];
+        }
+
+        return {
+            sources:    new Int32Array(this._sources),
+            targets:    new Int32Array(this._targets),
+            edgeWeight,
+            edgeDress,
+            nodeDress,
+            iterations: 0,
+            delta:      0,
+        };
+    }
+
+    /**
+     * Free the underlying C graph.
+     */
+    free() {
+        if (this._g) {
+            const M = this._M;
+            M._free_dress_graph(this._g);
+            M._free(this._iterPtr);
+            M._free(this._deltaPtr);
+            this._g = 0;
+        }
+    }
+}
+
 // ── Delta-k-DRESS API ───────────────────────────────────────────────
 
 /**
@@ -246,6 +402,8 @@ export async function deltaDressFit(opts) {
     const epsilon     = opts.epsilon ?? 1e-6;
     const precompute  = (opts.precompute ?? false) ? 1 : 0;
     const keepMS      = (opts.keepMultisets ?? false) ? 1 : 0;
+    const offset      = opts.offset ?? 0;
+    const stride      = opts.stride ?? 1;
 
     // Allocate C arrays (ownership transfers to init_dress_graph)
     const uPtr = M._malloc(E * 4);
@@ -288,9 +446,9 @@ export async function deltaDressFit(opts) {
         M.setValue(numSubPtr + 4, 0, 'i32');
     }
 
-    // Call delta_fit  (returns int64_t* — pointer to histogram on heap)
-    const histPtr = M._delta_fit(g, k, maxIter, epsilon, histSizePtr,
-                                 keepMS, msPtrPtr, numSubPtr);
+    // Call delta_dress_fit_strided  (returns int64_t* — pointer to histogram on heap)
+    const histPtr = M._delta_dress_fit_strided(g, k, maxIter, epsilon, histSizePtr,
+                                 keepMS, msPtrPtr, numSubPtr, offset, stride);
 
     const histSize = M.getValue(histSizePtr, 'i32');
 
@@ -337,3 +495,4 @@ export async function deltaDressFit(opts) {
         numSubgraphs:  numSubgraphs,
     };
 }
+

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "dress-graph",
-    "version": "0.3.1",
-    "description": "DRESS — A Continuous Framework for Structural Graph Refinement (WebAssembly)",
+    "version": "0.5.0",
+    "description": "DRESS is a deterministic, parameter-free framework that iteratively refines the structural similarity of edges in a graph to produce a canonical fingerprint: a real-valued edge vector, obtained by converging a non-linear dynamical system to its unique fixed point. The fingerprint is isomorphism-invariant by construction, numerically stable (no overflow, no error amplification, no undefined behavior), fast and embarrassingly parallel to compute: DRESS total runtime is O(I * m * d_max) for I iterations to convergence, and convergence is guaranteed by Birkhoff contraction.",
     "type": "module",
     "main": "dress.js",
     "types": "dress.d.ts",