dress-graph 0.6.1 → 0.8.0

package/README.md

@@ -2,14 +2,14 @@
 
 **A Continuous Framework for Structural Graph Refinement**
 
-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, guaranteed bitwise-equal across any vertex labeling, 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.
+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 self-contained, isomorphism-invariant by construction, guaranteed bitwise-equal across any vertex labeling, 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
-import { dressFit } from 'dress-graph';
+import { fit } from 'dress-graph';
 
-const result = await dressFit({
+const result = await fit({
   numVertices: 4,
   sources:     [0, 1, 2, 0],
   targets:     [1, 2, 3, 3],

package/dress.d.ts

@@ -18,6 +18,8 @@ export interface DressOptions {
     targets: Int32Array | number[];
     /** Optional edge weights (same length as sources) */
     weights?: Float64Array | number[] | null;
+    /** Optional vertex weights (length numVertices) */
+    vertexWeights?: Float64Array | number[] | null;
     /** Graph variant (default: Variant.UNDIRECTED) */
     variant?: number;
     /** Maximum fitting iterations (default: 100) */
@@ -37,8 +39,8 @@ export interface DressResult {
     edgeWeight: Float64Array;
     /** Per-edge dress similarity values */
     edgeDress: Float64Array;
-    /** Per-node aggregated dress similarity */
-    nodeDress: Float64Array;
+    /** Per-vertex aggregated dress similarity */
+    vertexDress: Float64Array;
     /** Number of iterations performed */
     iterations: number;
     /** Final maximum per-edge change */
@@ -48,7 +50,7 @@ export interface DressResult {
 /**
  * Run the DRESS iterative fitting algorithm on an edge list.
  */
-export declare function dressFit(opts: DressOptions): Promise<DressResult>;
+export declare function fit(opts: DressOptions): Promise<DressResult>;
 
 export interface DRESSOptions {
     /** Number of vertices (vertex ids must be in 0..numVertices-1) */
@@ -59,6 +61,8 @@ export interface DRESSOptions {
     targets: Int32Array | number[];
     /** Optional edge weights (same length as sources) */
     weights?: Float64Array | number[] | null;
+    /** Optional vertex weights (length numVertices) */
+    vertexWeights?: Float64Array | number[] | null;
     /** Graph variant (default: Variant.UNDIRECTED) */
     variant?: number;
     /** Pre-compute neighbourhood intercepts (default: false) */
@@ -86,6 +90,8 @@ export interface DeltaDressOptions {
     targets: Int32Array | number[];
     /** Optional edge weights (same length as sources) */
     weights?: Float64Array | number[] | null;
+    /** Optional vertex weights (length numVertices) */
+    vertexWeights?: Float64Array | number[] | null;
     /** Vertices to remove per subset (default: 0 = original graph) */
     k?: number;
     /** Graph variant (default: Variant.UNDIRECTED) */
@@ -94,26 +100,81 @@ export interface DeltaDressOptions {
     maxIterations?: number;
     /** Convergence threshold / bin width (default: 1e-6) */
     epsilon?: number;
+    /** Number of random subgraphs to sample (0 = exhaustive, default: 0) */
+    nSamples?: number;
+    /** Random seed for sampling (default: 0) */
+    seed?: number;
     /** Pre-compute neighbourhood intercepts (default: false) */
     precompute?: boolean;
     /** Return per-subgraph edge values (default: false) */
     keepMultisets?: boolean;
+    /** Compute histogram (default: true) */
+    computeHistogram?: boolean;
 }
 
 export interface DeltaDressResult {
-    /** Bin counts of edge delta values (as Float64 for BigInt-free access) */
-    histogram: Float64Array;
-    /** Number of histogram bins (floor(dmax/epsilon) + 1; dmax = 2 unweighted) */
-    histSize: number;
+    /** Exact sparse histogram entries as (value, count) pairs */
+    histogram: HistogramEntry[];
     /** Per-subgraph edge values, row-major C(N,k) × E (NaN = removed edge; null when not requested) */
     multisets: Float64Array | null;
     /** Number of subgraphs C(N,k) */
     numSubgraphs: number;
 }
 
+export interface HistogramEntry {
+    value: number;
+    count: number;
+}
+
 /**
  * Compute the Delta-k-DRESS histogram by exhaustively removing
  * all k-vertex subsets and measuring edge similarity changes.
  */
-export declare function deltaDressFit(opts: DeltaDressOptions): Promise<DeltaDressResult>;
+export declare function deltaFit(opts: DeltaDressOptions): Promise<DeltaDressResult>;
+
+export interface NablaDressOptions {
+    /** 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;
+    /** Optional vertex weights (length numVertices) */
+    vertexWeights?: Float64Array | number[] | null;
+    /** Vertices to remove per tuple (default: 0 = original graph) */
+    k?: number;
+    /** Graph variant (default: Variant.UNDIRECTED) */
+    variant?: number;
+    /** Maximum fitting iterations (default: 100) */
+    maxIterations?: number;
+    /** Convergence threshold / bin width (default: 1e-6) */
+    epsilon?: number;
+    /** Number of random tuples to sample (0 = exhaustive, default: 0) */
+    nSamples?: number;
+    /** Random seed for sampling (default: 0) */
+    seed?: number;
+    /** Pre-compute neighbourhood intercepts (default: false) */
+    precompute?: boolean;
+    /** Return per-tuple edge values (default: false) */
+    keepMultisets?: boolean;
+    /** Compute histogram (default: true) */
+    computeHistogram?: boolean;
+}
+
+export interface NablaDressResult {
+    /** Exact sparse histogram entries as (value, count) pairs */
+    histogram: HistogramEntry[];
+    /** Per-tuple edge values, row-major (null when not requested) */
+    multisets: Float64Array | null;
+    /** Number of tuples */
+    numTuples: number;
+}
+
+/**
+ * Compute the Nabla-k-DRESS histogram by exhaustively removing
+ * all k-vertex tuples and measuring edge similarity changes.
+ */
+export declare function nablaFit(opts: NablaDressOptions): Promise<NablaDressResult>;
 

package/dress.js

@@ -5,9 +5,9 @@
  *
  * Usage (ES module):
  *
- *   import { dressFit } from './dress.js';
+ *   import { fit } from './dress.js';
  *
- *   const result = await dressFit({
+ *   const result = await fit({
  *     numVertices: 4,
  *     sources:     [0, 1, 2, 0],
  *     targets:     [1, 2, 3, 3],
@@ -75,7 +75,7 @@ export const Variant = Object.freeze({
  * @property {Int32Array}    targets     - Edge target vertices
  * @property {Float64Array}  edgeWeight  - Per-edge variant weights
  * @property {Float64Array}  edgeDress   - Per-edge dress similarity
- * @property {Float64Array}  nodeDress   - Per-node aggregated similarity
+ * @property {Float64Array}  vertexDress   - Per-vertex aggregated similarity
  * @property {number}        iterations  - Iterations performed
  * @property {number}        delta       - Final max per-edge change
  */
@@ -86,7 +86,7 @@ export const Variant = Object.freeze({
  * @param {DressOptions} opts
  * @returns {Promise<DressResult>}
  */
-export async function dressFit(opts) {
+export async function fit(opts) {
     const M = await getModule();
 
     const N = opts.numVertices;
@@ -104,7 +104,7 @@ export async function dressFit(opts) {
     const epsilon     = opts.epsilon ?? 1e-6;
     const precompute  = (opts.precomputeIntercepts ?? false) ? 1 : 0;
 
-    // Allocate C arrays (ownership transfers to dress.c — freed by free_dress_graph)
+    // Allocate C arrays (ownership transfers to dress.c — freed by dress_free_graph)
     const uPtr = M._malloc(E * 4);
     const vPtr = M._malloc(E * 4);
 
@@ -128,10 +128,24 @@ export async function dressFit(opts) {
         }
     }
 
-    // Call init_dress_graph
-    const g = M._init_dress_graph(N, E, uPtr, vPtr, wPtr, variant, precompute);
+    // vertex weights (nullable)
+    let nwPtr = 0; // NULL
+    if (opts.vertexWeights) {
+        if (opts.vertexWeights.length !== N) {
+            throw new Error(`vertexWeights (${opts.vertexWeights.length}) must equal vertex count (${N})`);
+        }
+        nwPtr = M._malloc(N * 8);
+        const heapF64 = M.HEAPF64;
+        const nw = opts.vertexWeights;
+        for (let i = 0; i < N; i++) {
+            heapF64[(nwPtr >> 3) + i] = nw[i];
+        }
+    }
+
+    // Call dress_init_graph
+    const g = M._dress_init_graph(N, E, uPtr, vPtr, wPtr, nwPtr, variant, precompute);
     if (g === 0) {
-        throw new Error('init_dress_graph returned NULL');
+        throw new Error('dress_init_graph returned NULL');
     }
 
     // Allocate output params
@@ -154,20 +168,21 @@ export async function dressFit(opts) {
     //   offset 20: *adj_offset    (ptr32)
     //   offset 24: *adj_target    (ptr32)
     //   offset 28: *adj_edge_idx  (ptr32)
-    //   offset 32: max_degree      (i32)
-    //   offset 36: *W             (ptr32)  raw input weights
+    //   offset 32: max_degree     (i32)
+    //   offset 36: *W             (ptr32)
     //   offset 40: *edge_weight   (ptr32)
-    //   offset 48: *edge_dress    (ptr32)
-    //   offset 52: *edge_dress_next (ptr32)
-    //   offset 56: *node_dress    (ptr32)
-    const ewPtr = M.getValue(g + 44, 'i32');  // edge_weight pointer
-    const edPtr = M.getValue(g + 48, 'i32');  // edge_dress pointer
-    const ndPtr = M.getValue(g + 56, 'i32');  // node_dress pointer
+    //   offset 44: *edge_dress    (ptr32)
+    //   offset 48: *edge_dress_next (ptr32)
+    //   offset 52: *vertex_dress    (ptr32)
+    //   offset 56: *NW            (ptr32)
+    const ewPtr = M.getValue(g + 40, 'i32');  // edge_weight pointer
+    const edPtr = M.getValue(g + 44, 'i32');  // edge_dress pointer
+    const ndPtr = M.getValue(g + 52, 'i32');  // vertex_dress pointer
 
     // Copy results into JS-owned typed arrays
     const edgeWeight = new Float64Array(E);
     const edgeDress  = new Float64Array(E);
-    const nodeDress  = new Float64Array(N);
+    const vertexDress  = new Float64Array(N);
 
     const heapF64 = M.HEAPF64;
     for (let i = 0; i < E; i++) {
@@ -175,7 +190,7 @@ export async function dressFit(opts) {
         edgeDress[i]  = heapF64[(edPtr >> 3) + i];
     }
     for (let i = 0; i < N; i++) {
-        nodeDress[i] = heapF64[(ndPtr >> 3) + i];
+        vertexDress[i] = heapF64[(ndPtr >> 3) + i];
     }
 
     // Copy sources/targets before free
@@ -187,7 +202,7 @@ export async function dressFit(opts) {
     }
 
     // Clean up
-    M._free_dress_graph(g);
+    M._dress_free_graph(g);
     M._free(iterPtr);
     M._free(deltaPtr);
 
@@ -196,7 +211,7 @@ export async function dressFit(opts) {
         targets:    targetsOut,
         edgeWeight: edgeWeight,
         edgeDress:  edgeDress,
-        nodeDress:  nodeDress,
+        vertexDress:  vertexDress,
         iterations: iterations,
         delta:      delta,
     };
@@ -270,8 +285,16 @@ export class DRESS {
             }
         }
 
-        const g = M._init_dress_graph(N, E, uPtr, vPtr, wPtr, variant, precompute);
-        if (g === 0) throw new Error('init_dress_graph returned NULL');
+        let nwPtr = 0;
+        if (opts.vertexWeights && opts.vertexWeights.length === N) {
+            nwPtr = M._malloc(N * 8);
+            for (let i = 0; i < N; i++) {
+                M.HEAPF64[(nwPtr >> 3) + i] = opts.vertexWeights[i];
+            }
+        }
+
+        const g = M._dress_init_graph(N, E, uPtr, vPtr, wPtr, nwPtr, variant, precompute);
+        if (g === 0) throw new Error('dress_init_graph returned NULL');
 
         return new DRESS(M, g, N, E, opts.sources, opts.targets);
     }
@@ -317,20 +340,20 @@ export class DRESS {
         const N = this._n;
 
         // WASM32 offsets
-        const ewPtr = M.getValue(this._g + 44, 'i32');
-        const edPtr = M.getValue(this._g + 48, 'i32');
-        const ndPtr = M.getValue(this._g + 56, 'i32');
+        const ewPtr = M.getValue(this._g + 40, 'i32');
+        const edPtr = M.getValue(this._g + 44, 'i32');
+        const ndPtr = M.getValue(this._g + 52, 'i32');
 
         const edgeWeight = new Float64Array(E);
         const edgeDress  = new Float64Array(E);
-        const nodeDress  = new Float64Array(N);
+        const vertexDress  = 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];
+            vertexDress[i] = M.HEAPF64[(ndPtr >> 3) + i];
         }
 
         return {
@@ -338,19 +361,166 @@ export class DRESS {
             targets:    new Int32Array(this._targets),
             edgeWeight,
             edgeDress,
-            nodeDress,
+            vertexDress,
             iterations: 0,
             delta:      0,
         };
     }
 
+    /**
+     * Compute Δ^k-DRESS on this persistent graph.
+     * @param {number} [k=0]
+     * @param {number} [maxIterations=100]
+     * @param {number} [epsilon=1e-6]
+     * @param {number} [nSamples=0]
+     * @param {number} [seed=0]
+     * @param {boolean} [keepMultisets=false]
+     * @param {boolean} [computeHistogram=true]
+     * @returns {DeltaDressResult}
+     */
+    deltaFit(k = 0, maxIterations = 100, epsilon = 1e-6,
+             nSamples = 0, seed = 0,
+             keepMultisets = false, computeHistogram = true) {
+        if (!this._g) throw new Error('DRESS already freed');
+        const M = this._M;
+        const E = this._e;
+
+        const keepMS = keepMultisets ? 1 : 0;
+        const histSizePtr = M._malloc(4);
+
+        let msPtrPtr = 0;
+        let numSubPtr = 0;
+        if (keepMS) {
+            msPtrPtr  = M._malloc(4);
+            numSubPtr = M._malloc(8);
+            M.setValue(msPtrPtr, 0, 'i32');
+            M.setValue(numSubPtr, 0, 'i32');
+            M.setValue(numSubPtr + 4, 0, 'i32');
+        }
+
+        const histPtr = M._dress_delta_fit_strided(
+            this._g, k, maxIterations, epsilon,
+            nSamples, seed,
+            computeHistogram ? histSizePtr : 0,
+            keepMS, msPtrPtr || 0, numSubPtr || 0,
+            0, 1);
+
+        const histSize = M.getValue(histSizePtr, 'i32');
+
+        const histogram = new Array(histSize);
+        for (let i = 0; i < histSize; i++) {
+            const value = M.HEAPF64[(histPtr >> 3) + i * 2];
+            const countLo = M.HEAPU32[(histPtr >> 2) + i * 4 + 2];
+            const countHi = M.HEAPU32[(histPtr >> 2) + i * 4 + 3];
+            histogram[i] = { value, count: countHi * 4294967296 + countLo };
+        }
+
+        let multisets = null;
+        let numSubgraphs = 0;
+        if (keepMS && msPtrPtr) {
+            const msPtr = M.getValue(msPtrPtr, 'i32');
+            const nsLo = M.HEAPU32[(numSubPtr >> 2)];
+            const nsHi = M.HEAP32[(numSubPtr >> 2) + 1];
+            numSubgraphs = nsHi * 4294967296 + nsLo;
+
+            if (msPtr !== 0 && numSubgraphs > 0) {
+                const totalVals = numSubgraphs * E;
+                multisets = new Float64Array(totalVals);
+                for (let i = 0; i < totalVals; i++) {
+                    multisets[i] = M.HEAPF64[(msPtr >> 3) + i];
+                }
+                M._free(msPtr);
+            }
+            M._free(msPtrPtr);
+            M._free(numSubPtr);
+        }
+
+        if (histPtr) M._free(histPtr);
+        M._free(histSizePtr);
+
+        return { histogram, multisets, numSubgraphs };
+    }
+
+    /**
+     * Compute ∇^k-DRESS on this persistent graph.
+     * @param {number} [k=0]
+     * @param {number} [maxIterations=100]
+     * @param {number} [epsilon=1e-6]
+     * @param {number} [nSamples=0]
+     * @param {number} [seed=0]
+     * @param {boolean} [keepMultisets=false]
+     * @param {boolean} [computeHistogram=true]
+     * @returns {NablaDressResult}
+     */
+    nablaFit(k = 0, maxIterations = 100, epsilon = 1e-6,
+             nSamples = 0, seed = 0,
+             keepMultisets = false, computeHistogram = true) {
+        if (!this._g) throw new Error('DRESS already freed');
+        const M = this._M;
+        const E = this._e;
+
+        const keepMS = keepMultisets ? 1 : 0;
+        const histSizePtr = M._malloc(4);
+
+        let msPtrPtr = 0;
+        let numTupPtr = 0;
+        if (keepMS) {
+            msPtrPtr  = M._malloc(4);
+            numTupPtr = M._malloc(8);
+            M.setValue(msPtrPtr, 0, 'i32');
+            M.setValue(numTupPtr, 0, 'i32');
+            M.setValue(numTupPtr + 4, 0, 'i32');
+        }
+
+        const histPtr = M._dress_nabla_fit(
+            this._g, k, maxIterations, epsilon,
+            nSamples, seed,
+            computeHistogram ? histSizePtr : 0,
+            keepMS, msPtrPtr || 0, numTupPtr || 0);
+
+        const histSize = M.getValue(histSizePtr, 'i32');
+
+        const histogram = new Array(histSize);
+        for (let i = 0; i < histSize; i++) {
+            const value = M.HEAPF64[(histPtr >> 3) + i * 2];
+            const countLo = M.HEAPU32[(histPtr >> 2) + i * 4 + 2];
+            const countHi = M.HEAPU32[(histPtr >> 2) + i * 4 + 3];
+            histogram[i] = { value, count: countHi * 4294967296 + countLo };
+        }
+
+        let multisets = null;
+        let numTuples = 0;
+        if (keepMS && msPtrPtr) {
+            const msPtr = M.getValue(msPtrPtr, 'i32');
+            const ntLo = M.HEAPU32[(numTupPtr >> 2)];
+            const ntHi = M.HEAP32[(numTupPtr >> 2) + 1];
+            numTuples = ntHi * 4294967296 + ntLo;
+
+            if (msPtr !== 0 && numTuples > 0) {
+                const totalVals = numTuples * E;
+                multisets = new Float64Array(totalVals);
+                for (let i = 0; i < totalVals; i++) {
+                    multisets[i] = M.HEAPF64[(msPtr >> 3) + i];
+                }
+                M._free(msPtr);
+            }
+            M._free(msPtrPtr);
+            M._free(numTupPtr);
+        }
+
+        if (histPtr) M._free(histPtr);
+        M._free(histSizePtr);
+
+        return { histogram, multisets, numTuples };
+    }
+
     /**
      * Free the underlying C graph.
      */
     free() {
         if (this._g) {
             const M = this._M;
-            M._free_dress_graph(this._g);
+            M._dress_free_graph(this._g);
             M._free(this._iterPtr);
             M._free(this._deltaPtr);
             this._g = 0;
@@ -372,10 +542,17 @@ export class DRESS {
  * @property {boolean} [precompute=false]            - Pre-compute intercepts
  */
 
+/**
+ * @typedef {Object} HistogramEntry
+ * @property {number} value - Exact DRESS value
+ * @property {number} count - Number of occurrences of that value
+ */
+
 /**
  * @typedef {Object} DeltaDressResult
- * @property {Float64Array} histogram - Bin counts (as Float64 for BigInt-free access)
- * @property {number}       histSize  - Number of bins
+ * @property {HistogramEntry[]} histogram - Exact sparse histogram entries
+ * @property {Float64Array|null} multisets - Per-subgraph edge values, row-major C(N,k) x E
+ * @property {number} numSubgraphs - Number of subgraphs C(N,k)
  */
 
 /**
@@ -387,7 +564,7 @@ export class DRESS {
  * @param {DeltaDressOptions} opts
  * @returns {Promise<DeltaDressResult>}
  */
-export async function deltaDressFit(opts) {
+export async function deltaFit(opts) {
     const M = await getModule();
 
     const N = opts.numVertices;
@@ -401,12 +578,13 @@ export async function deltaDressFit(opts) {
     const variant     = opts.variant ?? Variant.UNDIRECTED;
     const maxIter     = opts.maxIterations ?? 100;
     const epsilon     = opts.epsilon ?? 1e-6;
+    const nSamples    = opts.nSamples ?? 0;
+    const seed        = opts.seed ?? 0;
     const precompute  = (opts.precompute ?? false) ? 1 : 0;
     const keepMS      = (opts.keepMultisets ?? false) ? 1 : 0;
-    const offset      = opts.offset ?? 0;
-    const stride      = opts.stride ?? 1;
+    const computeHist = (opts.computeHistogram ?? true) ? 1 : 0;
 
-    // Allocate C arrays (ownership transfers to init_dress_graph)
+    // Allocate C arrays (ownership transfers to dress_init_graph)
     const uPtr = M._malloc(E * 4);
     const vPtr = M._malloc(E * 4);
 
@@ -427,10 +605,19 @@ export async function deltaDressFit(opts) {
         }
     }
 
+    let nwPtr = 0;
+    if (opts.vertexWeights && opts.vertexWeights.length === N) {
+        nwPtr = M._malloc(N * 8);
+        const heapF64 = M.HEAPF64;
+        for (let i = 0; i < N; i++) {
+            heapF64[(nwPtr >> 3) + i] = opts.vertexWeights[i];
+        }
+    }
+
     // Build graph
-    const g = M._init_dress_graph(N, E, uPtr, vPtr, wPtr, variant, precompute);
+    const g = M._dress_init_graph(N, E, uPtr, vPtr, wPtr, nwPtr, variant, precompute);
     if (g === 0) {
-        throw new Error('init_dress_graph returned NULL');
+        throw new Error('dress_init_graph returned NULL');
     }
 
     // Allocate out-param for hist_size
@@ -447,19 +634,24 @@ export async function deltaDressFit(opts) {
         M.setValue(numSubPtr + 4, 0, 'i32');
     }
 
-    // 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);
+    // Call dress_delta_fit_strided (returns dress_hist_pair_t* on heap)
+    const histPtr = M._dress_delta_fit_strided(g, k, maxIter, epsilon,
+                                 nSamples, seed,
+                                 computeHist ? histSizePtr : 0,
+                                 keepMS, msPtrPtr, numSubPtr, 0, 1);
 
     const histSize = M.getValue(histSizePtr, 'i32');
 
-    // Copy histogram into JS Float64Array (int64 values cast to double)
-    // WASM int64_t is 8 bytes; read as pairs of i32 (little-endian)
-    const histogram = new Float64Array(histSize);
+    // Copy histogram pairs into JS objects.
+    const histogram = new Array(histSize);
     for (let i = 0; i < histSize; i++) {
-        const lo = M.HEAPU32[(histPtr >> 2) + i * 2];
-        const hi = M.HEAP32[(histPtr >> 2) + i * 2 + 1];
-        histogram[i] = hi * 4294967296 + lo;
+        const value = M.HEAPF64[(histPtr >> 3) + i * 2];
+        const countLo = M.HEAPU32[(histPtr >> 2) + i * 4 + 2];
+        const countHi = M.HEAPU32[(histPtr >> 2) + i * 4 + 3];
+        histogram[i] = {
+            value,
+            count: countHi * 4294967296 + countLo,
+        };
     }
 
     // Extract multisets if requested
@@ -487,13 +679,145 @@ export async function deltaDressFit(opts) {
     // Cleanup
     M._free(histPtr);
     M._free(histSizePtr);
-    M._free_dress_graph(g);
+    M._dress_free_graph(g);
 
     return {
         histogram:     histogram,
-        histSize:      histSize,
         multisets:     multisets,
         numSubgraphs:  numSubgraphs,
     };
 }
 
+/**
+ * Compute the Nabla-k-DRESS histogram.
+ *
+ * Exhaustively removes all k-vertex tuples and measures
+ * the change in edge similarity values.
+ *
+ * @param {NablaDressOptions} opts
+ * @returns {Promise<NablaDressResult>}
+ */
+export async function nablaFit(opts) {
+    const M = await getModule();
+
+    const N = opts.numVertices;
+    const E = opts.sources.length;
+
+    if (opts.targets.length !== E) {
+        throw new Error(`sources (${E}) and targets (${opts.targets.length}) must have equal length`);
+    }
+
+    const k           = opts.k ?? 0;
+    const variant     = opts.variant ?? Variant.UNDIRECTED;
+    const maxIter     = opts.maxIterations ?? 100;
+    const epsilon     = opts.epsilon ?? 1e-6;
+    const nSamples    = opts.nSamples ?? 0;
+    const seed        = opts.seed ?? 0;
+    const precompute  = (opts.precompute ?? false) ? 1 : 0;
+    const keepMS      = (opts.keepMultisets ?? false) ? 1 : 0;
+    const computeHist = (opts.computeHistogram ?? true) ? 1 : 0;
+
+    // Allocate C arrays (ownership transfers to dress_init_graph)
+    const uPtr = M._malloc(E * 4);
+    const vPtr = M._malloc(E * 4);
+
+    const heap32 = M.HEAP32;
+    const src = opts.sources;
+    const tgt = opts.targets;
+    for (let i = 0; i < E; i++) {
+        heap32[(uPtr >> 2) + i] = src[i];
+        heap32[(vPtr >> 2) + i] = tgt[i];
+    }
+
+    let wPtr = 0;
+    if (opts.weights && opts.weights.length === E) {
+        wPtr = M._malloc(E * 8);
+        const heapF64 = M.HEAPF64;
+        for (let i = 0; i < E; i++) {
+            heapF64[(wPtr >> 3) + i] = opts.weights[i];
+        }
+    }
+
+    let nwPtr = 0;
+    if (opts.vertexWeights && opts.vertexWeights.length === N) {
+        nwPtr = M._malloc(N * 8);
+        const heapF64 = M.HEAPF64;
+        for (let i = 0; i < N; i++) {
+            heapF64[(nwPtr >> 3) + i] = opts.vertexWeights[i];
+        }
+    }
+
+    // Build graph
+    const g = M._dress_init_graph(N, E, uPtr, vPtr, wPtr, nwPtr, variant, precompute);
+    if (g === 0) {
+        throw new Error('dress_init_graph returned NULL');
+    }
+
+    // Allocate out-param for hist_size
+    const histSizePtr = M._malloc(4);
+
+    // Allocate out-params for multisets (pointer-to-pointer and num_tuples)
+    let msPtrPtr = 0;
+    let numTupPtr = 0;
+    if (keepMS) {
+        msPtrPtr   = M._malloc(4);  // pointer to double*
+        numTupPtr  = M._malloc(8);  // int64_t
+        M.setValue(msPtrPtr, 0, 'i32');
+        M.setValue(numTupPtr, 0, 'i32');
+        M.setValue(numTupPtr + 4, 0, 'i32');
+    }
+
+    // Call dress_nabla_fit (returns dress_hist_pair_t* on heap)
+    const histPtr = M._dress_nabla_fit(g, k, maxIter, epsilon,
+                                 nSamples, seed,
+                                 computeHist ? histSizePtr : 0,
+                                 keepMS, msPtrPtr, numTupPtr);
+
+    const histSize = M.getValue(histSizePtr, 'i32');
+
+    // Copy histogram pairs into JS objects.
+    const histogram = new Array(histSize);
+    for (let i = 0; i < histSize; i++) {
+        const value = M.HEAPF64[(histPtr >> 3) + i * 2];
+        const countLo = M.HEAPU32[(histPtr >> 2) + i * 4 + 2];
+        const countHi = M.HEAPU32[(histPtr >> 2) + i * 4 + 3];
+        histogram[i] = {
+            value,
+            count: countHi * 4294967296 + countLo,
+        };
+    }
+
+    // Extract multisets if requested
+    let multisets = null;
+    let numTuples = 0;
+    if (keepMS && msPtrPtr) {
+        const msPtr = M.getValue(msPtrPtr, 'i32');  // double*
+        // Read int64 num_tuples as lo/hi pair
+        const ntLo = M.HEAPU32[(numTupPtr >> 2)];
+        const ntHi = M.HEAP32[(numTupPtr >> 2) + 1];
+        numTuples = ntHi * 4294967296 + ntLo;
+
+        if (msPtr !== 0 && numTuples > 0) {
+            const totalVals = numTuples * E;
+            multisets = new Float64Array(totalVals);
+            for (let i = 0; i < totalVals; i++) {
+                multisets[i] = M.HEAPF64[(msPtr >> 3) + i];
+            }
+            M._free(msPtr);
+        }
+        M._free(msPtrPtr);
+        M._free(numTupPtr);
+    }
+
+    // Cleanup
+    M._free(histPtr);
+    M._free(histSizePtr);
+    M._dress_free_graph(g);
+
+    return {
+        histogram:  histogram,
+        multisets:  multisets,
+        numTuples:  numTuples,
+    };
+}
+

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "dress-graph",
-    "version": "0.6.1",
-    "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.",
+    "version": "0.8.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 self-contained, 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",

package/dress_wasm.cjs

@@ -1,2 +0,0 @@
-var createDressModule=(()=>{var _scriptName=globalThis.document?.currentScript?.src;return async function(moduleArg={}){var moduleRtn;var Module=moduleArg;var ENVIRONMENT_IS_WEB=!!globalThis.window;var ENVIRONMENT_IS_WORKER=!!globalThis.WorkerGlobalScope;var ENVIRONMENT_IS_NODE=globalThis.process?.versions?.node&&globalThis.process?.type!="renderer";var arguments_=[];var thisProgram="./this.program";var quit_=(status,toThrow)=>{throw toThrow};if(typeof __filename!="undefined"){_scriptName=__filename}else{}var scriptDirectory="";function locateFile(path){if(Module["locateFile"]){return Module["locateFile"](path,scriptDirectory)}return scriptDirectory+path}var readAsync,readBinary;if(ENVIRONMENT_IS_NODE){var fs=require("node:fs");scriptDirectory=__dirname+"/";readBinary=filename=>{filename=isFileURI(filename)?new URL(filename):filename;var ret=fs.readFileSync(filename);return ret};readAsync=async(filename,binary=true)=>{filename=isFileURI(filename)?new URL(filename):filename;var ret=fs.readFileSync(filename,binary?undefined:"utf8");return ret};if(process.argv.length>1){thisProgram=process.argv[1].replace(/\\/g,"/")}arguments_=process.argv.slice(2);quit_=(status,toThrow)=>{process.exitCode=status;throw toThrow}}else if(ENVIRONMENT_IS_WEB||ENVIRONMENT_IS_WORKER){try{scriptDirectory=new URL(".",_scriptName).href}catch{}{readAsync=async url=>{var response=await fetch(url,{credentials:"same-origin"});if(response.ok){return response.arrayBuffer()}throw new Error(response.status+" : "+response.url)}}}else{}var out=console.log.bind(console);var err=console.error.bind(console);var wasmBinary;var ABORT=false;var isFileURI=filename=>filename.startsWith("file://");var readyPromiseResolve,readyPromiseReject;var HEAP8,HEAPU8,HEAP16,HEAPU16,HEAP32,HEAPU32,HEAPF32,HEAPF64;var HEAP64,HEAPU64;var runtimeInitialized=false;function updateMemoryViews(){var b=wasmMemory.buffer;HEAP8=new Int8Array(b);HEAP16=new Int16Array(b);HEAPU8=new Uint8Array(b);HEAPU16=new Uint16Array(b);Module["HEAP32"]=HEAP32=new Int32Array(b);Module["HEAPU32"]=HEAPU32=new Uint32Array(b);HEAPF32=new Float32Array(b);Module["HEAPF64"]=HEAPF64=new Float64Array(b);HEAP64=new BigInt64Array(b);HEAPU64=new BigUint64Array(b)}function preRun(){if(Module["preRun"]){if(typeof Module["preRun"]=="function")Module["preRun"]=[Module["preRun"]];while(Module["preRun"].length){addOnPreRun(Module["preRun"].shift())}}callRuntimeCallbacks(onPreRuns)}function initRuntime(){runtimeInitialized=true;wasmExports["c"]()}function postRun(){if(Module["postRun"]){if(typeof Module["postRun"]=="function")Module["postRun"]=[Module["postRun"]];while(Module["postRun"].length){addOnPostRun(Module["postRun"].shift())}}callRuntimeCallbacks(onPostRuns)}function abort(what){Module["onAbort"]?.(what);what="Aborted("+what+")";err(what);ABORT=true;what+=". Build with -sASSERTIONS for more info.";var e=new WebAssembly.RuntimeError(what);readyPromiseReject?.(e);throw e}var wasmBinaryFile;function findWasmBinary(){return locateFile("dress_wasm.wasm")}function getBinarySync(file){if(file==wasmBinaryFile&&wasmBinary){return new Uint8Array(wasmBinary)}if(readBinary){return readBinary(file)}throw"both async and sync fetching of the wasm failed"}async function getWasmBinary(binaryFile){if(!wasmBinary){try{var response=await readAsync(binaryFile);return new Uint8Array(response)}catch{}}return getBinarySync(binaryFile)}async function instantiateArrayBuffer(binaryFile,imports){try{var binary=await getWasmBinary(binaryFile);var instance=await WebAssembly.instantiate(binary,imports);return instance}catch(reason){err(`failed to asynchronously prepare wasm: ${reason}`);abort(reason)}}async function instantiateAsync(binary,binaryFile,imports){if(!binary&&!ENVIRONMENT_IS_NODE){try{var response=fetch(binaryFile,{credentials:"same-origin"});var instantiationResult=await WebAssembly.instantiateStreaming(response,imports);return instantiationResult}catch(reason){err(`wasm streaming compile failed: ${reason}`);err("falling back to ArrayBuffer instantiation")}}return instantiateArrayBuffer(binaryFile,imports)}function getWasmImports(){var imports={a:wasmImports};return imports}async function createWasm(){function receiveInstance(instance,module){wasmExports=instance.exports;assignWasmExports(wasmExports);updateMemoryViews();return wasmExports}function receiveInstantiationResult(result){return receiveInstance(result["instance"])}var info=getWasmImports();if(Module["instantiateWasm"]){return new Promise((resolve,reject)=>{Module["instantiateWasm"](info,(inst,mod)=>{resolve(receiveInstance(inst,mod))})})}wasmBinaryFile??=findWasmBinary();var result=await instantiateAsync(wasmBinary,wasmBinaryFile,info);var exports=receiveInstantiationResult(result);return exports}class ExitStatus{name="ExitStatus";constructor(status){this.message=`Program terminated with exit(${status})`;this.status=status}}var callRuntimeCallbacks=callbacks=>{while(callbacks.length>0){callbacks.shift()(Module)}};var onPostRuns=[];var addOnPostRun=cb=>onPostRuns.push(cb);var onPreRuns=[];var addOnPreRun=cb=>onPreRuns.push(cb);function getValue(ptr,type="i8"){if(type.endsWith("*"))type="*";switch(type){case"i1":return HEAP8[ptr];case"i8":return HEAP8[ptr];case"i16":return HEAP16[ptr>>1];case"i32":return HEAP32[ptr>>2];case"i64":return HEAP64[ptr>>3];case"float":return HEAPF32[ptr>>2];case"double":return HEAPF64[ptr>>3];case"*":return HEAPU32[ptr>>2];default:abort(`invalid type for getValue: ${type}`)}}var noExitRuntime=true;function setValue(ptr,value,type="i8"){if(type.endsWith("*"))type="*";switch(type){case"i1":HEAP8[ptr]=value;break;case"i8":HEAP8[ptr]=value;break;case"i16":HEAP16[ptr>>1]=value;break;case"i32":HEAP32[ptr>>2]=value;break;case"i64":HEAP64[ptr>>3]=BigInt(value);break;case"float":HEAPF32[ptr>>2]=value;break;case"double":HEAPF64[ptr>>3]=value;break;case"*":HEAPU32[ptr>>2]=value;break;default:abort(`invalid type for setValue: ${type}`)}}var stackRestore=val=>__emscripten_stack_restore(val);var stackSave=()=>_emscripten_stack_get_current();var getHeapMax=()=>2147483648;var alignMemory=(size,alignment)=>Math.ceil(size/alignment)*alignment;var growMemory=size=>{var oldHeapSize=wasmMemory.buffer.byteLength;var pages=(size-oldHeapSize+65535)/65536|0;try{wasmMemory.grow(pages);updateMemoryViews();return 1}catch(e){}};var _emscripten_resize_heap=requestedSize=>{var oldSize=HEAPU8.length;requestedSize>>>=0;var maxHeapSize=getHeapMax();if(requestedSize>maxHeapSize){return false}for(var cutDown=1;cutDown<=4;cutDown*=2){var overGrownHeapSize=oldSize*(1+.2/cutDown);overGrownHeapSize=Math.min(overGrownHeapSize,requestedSize+100663296);var newSize=Math.min(maxHeapSize,alignMemory(Math.max(requestedSize,overGrownHeapSize),65536));var replacement=growMemory(newSize);if(replacement){return true}}return false};var getCFunc=ident=>{var func=Module["_"+ident];return func};var writeArrayToMemory=(array,buffer)=>{HEAP8.set(array,buffer)};var lengthBytesUTF8=str=>{var len=0;for(var i=0;i<str.length;++i){var c=str.charCodeAt(i);if(c<=127){len++}else if(c<=2047){len+=2}else if(c>=55296&&c<=57343){len+=4;++i}else{len+=3}}return len};var stringToUTF8Array=(str,heap,outIdx,maxBytesToWrite)=>{if(!(maxBytesToWrite>0))return 0;var startIdx=outIdx;var endIdx=outIdx+maxBytesToWrite-1;for(var i=0;i<str.length;++i){var u=str.codePointAt(i);if(u<=127){if(outIdx>=endIdx)break;heap[outIdx++]=u}else if(u<=2047){if(outIdx+1>=endIdx)break;heap[outIdx++]=192|u>>6;heap[outIdx++]=128|u&63}else if(u<=65535){if(outIdx+2>=endIdx)break;heap[outIdx++]=224|u>>12;heap[outIdx++]=128|u>>6&63;heap[outIdx++]=128|u&63}else{if(outIdx+3>=endIdx)break;heap[outIdx++]=240|u>>18;heap[outIdx++]=128|u>>12&63;heap[outIdx++]=128|u>>6&63;heap[outIdx++]=128|u&63;i++}}heap[outIdx]=0;return outIdx-startIdx};var stringToUTF8=(str,outPtr,maxBytesToWrite)=>stringToUTF8Array(str,HEAPU8,outPtr,maxBytesToWrite);var stackAlloc=sz=>__emscripten_stack_alloc(sz);var stringToUTF8OnStack=str=>{var size=lengthBytesUTF8(str)+1;var ret=stackAlloc(size);stringToUTF8(str,ret,size);return ret};var UTF8Decoder=globalThis.TextDecoder&&new TextDecoder;var findStringEnd=(heapOrArray,idx,maxBytesToRead,ignoreNul)=>{var maxIdx=idx+maxBytesToRead;if(ignoreNul)return maxIdx;while(heapOrArray[idx]&&!(idx>=maxIdx))++idx;return idx};var UTF8ArrayToString=(heapOrArray,idx=0,maxBytesToRead,ignoreNul)=>{var endPtr=findStringEnd(heapOrArray,idx,maxBytesToRead,ignoreNul);if(endPtr-idx>16&&heapOrArray.buffer&&UTF8Decoder){return UTF8Decoder.decode(heapOrArray.subarray(idx,endPtr))}var str="";while(idx<endPtr){var u0=heapOrArray[idx++];if(!(u0&128)){str+=String.fromCharCode(u0);continue}var u1=heapOrArray[idx++]&63;if((u0&224)==192){str+=String.fromCharCode((u0&31)<<6|u1);continue}var u2=heapOrArray[idx++]&63;if((u0&240)==224){u0=(u0&15)<<12|u1<<6|u2}else{u0=(u0&7)<<18|u1<<12|u2<<6|heapOrArray[idx++]&63}if(u0<65536){str+=String.fromCharCode(u0)}else{var ch=u0-65536;str+=String.fromCharCode(55296|ch>>10,56320|ch&1023)}}return str};var UTF8ToString=(ptr,maxBytesToRead,ignoreNul)=>ptr?UTF8ArrayToString(HEAPU8,ptr,maxBytesToRead,ignoreNul):"";var ccall=(ident,returnType,argTypes,args,opts)=>{var toC={string:str=>{var ret=0;if(str!==null&&str!==undefined&&str!==0){ret=stringToUTF8OnStack(str)}return ret},array:arr=>{var ret=stackAlloc(arr.length);writeArrayToMemory(arr,ret);return ret}};function convertReturnValue(ret){if(returnType==="string"){return UTF8ToString(ret)}if(returnType==="boolean")return Boolean(ret);return ret}var func=getCFunc(ident);var cArgs=[];var stack=0;if(args){for(var i=0;i<args.length;i++){var converter=toC[argTypes[i]];if(converter){if(stack===0)stack=stackSave();cArgs[i]=converter(args[i])}else{cArgs[i]=args[i]}}}var ret=func(...cArgs);function onDone(ret){if(stack!==0)stackRestore(stack);return convertReturnValue(ret)}ret=onDone(ret);return ret};var cwrap=(ident,returnType,argTypes,opts)=>{var numericArgs=!argTypes||argTypes.every(type=>type==="number"||type==="boolean");var numericRet=returnType!=="string";if(numericRet&&numericArgs&&!opts){return getCFunc(ident)}return(...args)=>ccall(ident,returnType,argTypes,args,opts)};{if(Module["noExitRuntime"])noExitRuntime=Module["noExitRuntime"];if(Module["print"])out=Module["print"];if(Module["printErr"])err=Module["printErr"];if(Module["wasmBinary"])wasmBinary=Module["wasmBinary"];if(Module["arguments"])arguments_=Module["arguments"];if(Module["thisProgram"])thisProgram=Module["thisProgram"];if(Module["preInit"]){if(typeof Module["preInit"]=="function")Module["preInit"]=[Module["preInit"]];while(Module["preInit"].length>0){Module["preInit"].shift()()}}}Module["ccall"]=ccall;Module["cwrap"]=cwrap;Module["setValue"]=setValue;Module["getValue"]=getValue;var _init_dress_graph,_malloc,_free,_dress_fit,_free_dress_graph,_dress_get,_delta_dress_fit,_delta_dress_fit_strided,__emscripten_stack_restore,__emscripten_stack_alloc,_emscripten_stack_get_current,memory,__indirect_function_table,wasmMemory;function assignWasmExports(wasmExports){_init_dress_graph=Module["_init_dress_graph"]=wasmExports["d"];_malloc=Module["_malloc"]=wasmExports["e"];_free=Module["_free"]=wasmExports["f"];_dress_fit=Module["_dress_fit"]=wasmExports["g"];_free_dress_graph=Module["_free_dress_graph"]=wasmExports["h"];_dress_get=Module["_dress_get"]=wasmExports["i"];_delta_dress_fit=Module["_delta_dress_fit"]=wasmExports["j"];_delta_dress_fit_strided=Module["_delta_dress_fit_strided"]=wasmExports["k"];__emscripten_stack_restore=wasmExports["l"];__emscripten_stack_alloc=wasmExports["m"];_emscripten_stack_get_current=wasmExports["n"];memory=wasmMemory=wasmExports["b"];__indirect_function_table=wasmExports["__indirect_function_table"]}var wasmImports={a:_emscripten_resize_heap};function run(){preRun();function doRun(){Module["calledRun"]=true;if(ABORT)return;initRuntime();readyPromiseResolve?.(Module);Module["onRuntimeInitialized"]?.();postRun()}if(Module["setStatus"]){Module["setStatus"]("Running...");setTimeout(()=>{setTimeout(()=>Module["setStatus"](""),1);doRun()},1)}else{doRun()}}var wasmExports;wasmExports=await (createWasm());run();if(runtimeInitialized){moduleRtn=Module}else{moduleRtn=new Promise((resolve,reject)=>{readyPromiseResolve=resolve;readyPromiseReject=reject})}
-;return moduleRtn}})();if(typeof exports==="object"&&typeof module==="object"){module.exports=createDressModule;module.exports.default=createDressModule}else if(typeof define==="function"&&define["amd"])define([],()=>createDressModule);