@vessel-dsp/runtime 0.4.1 → 0.5.0

package/dist/worklet/v2-audio-worklet.js

@@ -1339,7 +1339,10 @@ var OPAMP_FOLD_STREAK = 6;
 function opAmpHalfSwing(railHigh, railLow) {
   return Math.max((railHigh - railLow) / 2, 1e-9);
 }
-var OPAMP_GAIN_BANDWIDTH_HZ = 1e6;
+var OPAMP_DEFAULT_GAIN_BANDWIDTH_HZ = 1e6;
+function opAmpGainBandwidthHz(stamp) {
+  return stamp.gainBandwidthHz ?? OPAMP_DEFAULT_GAIN_BANDWIDTH_HZ;
+}
 var OPAMP_POLE_BAND = 8;
 function boundOpAmpRaw(raw, halfSwing) {
   const limit = OPAMP_POLE_BAND * halfSwing;
@@ -1850,6 +1853,8 @@ var ReferenceRuntime = class {
   limiterTrace = typeof process !== "undefined" && process.env?.VESSEL_LIMITER_TRACE === "1";
   limitedIterationCount = 0;
   limitedIterationPerSample = [];
+  /** Fold reseeds taken so far (diagnostic, read past `private` by the stall study's tracer). */
+  foldReseedCount = 0;
   /** Series ohms of whatever drives the input jack -- see `prepare()`'s option. */
   inputSourceOhms = 0;
   /**
@@ -4025,7 +4030,9 @@ var ReferenceRuntime = class {
     let bestDelta = Number.POSITIVE_INFINITY;
     let noImprovement = 0;
     let foldStreak = 0;
-    let foldReseeded = false;
+    let foldReseeds = 0;
+    let lastWorstNode = -1;
+    let lastWorstSign = 0;
     for (let iteration = 0; iteration < iterations; iteration += 1) {
       used = iteration + 1;
       this.limitedIterate = false;
@@ -4153,6 +4160,12 @@ var ReferenceRuntime = class {
           }
         }
       }
+      const damping = dc ? 1 : this.opAmpStepDamping(block, blockIndex, current, next, dt, dc);
+      if (damping < 1) {
+        for (let i = 0; i < size; i++) {
+          next[i] = current[i] + damping * (next[i] - current[i]);
+        }
+      }
       if (relaxing) {
         for (let i = 0; i < size; i++) {
           next[i] = current[i] + alpha * (next[i] - current[i]);
@@ -4161,6 +4174,10 @@ var ReferenceRuntime = class {
       const delta = maxAbsDifference(next, current);
       worstNode = worstDifferenceIndex(next, current);
       worstDelta = delta;
+      const worstSign = Math.sign((next[worstNode] ?? 0) - (current[worstNode] ?? 0));
+      const reversed = dc || worstNode === lastWorstNode && worstSign !== 0 && lastWorstSign !== 0 && worstSign !== lastWorstSign;
+      lastWorstNode = worstNode;
+      lastWorstSign = worstSign;
       if (delta < bestDelta * 0.999) {
         bestDelta = delta;
         noImprovement = 0;
@@ -4173,7 +4190,7 @@ var ReferenceRuntime = class {
           }
         }
       } else {
-        noImprovement += 1;
+        noImprovement += reversed ? 1 : 0;
         if (!relaxing) {
           if (noImprovement >= NEWTON_NON_CONTRACTING_LIMIT && iteration >= NEWTON_RELAXATION_EARLIEST_ITERATION) {
             relaxing = true;
@@ -4204,13 +4221,15 @@ var ReferenceRuntime = class {
       }
       const limitedOpamp = this.limitedOpamp;
       foldStreak = limitedOpamp?.folded === true ? foldStreak + 1 : 0;
-      if (!dc && !foldReseeded && limitedOpamp !== null && foldStreak >= OPAMP_FOLD_STREAK) {
-        foldReseeded = true;
+      if (!dc && limitedOpamp !== null && foldStreak >= OPAMP_FOLD_STREAK) {
+        foldReseeds += 1;
+        this.foldReseedCount += 1;
         foldStreak = 0;
         const wasHigh = (start[limitedOpamp.output] ?? limitedOpamp.centre) >= limitedOpamp.centre;
-        current[limitedOpamp.output] = wasHigh ? limitedOpamp.railLow : limitedOpamp.railHigh;
+        const toHigh = foldReseeds % 2 === 1 ? wasHigh : !wasHigh;
+        current[limitedOpamp.output] = toHigh ? limitedOpamp.railHigh : limitedOpamp.railLow;
         this.opampHistory.set(limitedOpamp.key, {
-          differential: wasHigh ? -limitedOpamp.band : limitedOpamp.band,
+          differential: toHigh ? limitedOpamp.band : -limitedOpamp.band,
           step: 0,
           cap: limitedOpamp.maxStep
         });
@@ -4250,6 +4269,53 @@ var ReferenceRuntime = class {
     }
     return { solution: current, converged, used, worstNode, worstDelta };
   }
+  /**
+   * The factor the Newton update is scaled by so that no railed op-amp's differential moves
+   * further than its step cap and no op-amp output node moves further than one full swing:
+   * the smallest `cap / |requested differential step|` and `2 * halfSwing / |requested output
+   * step|` over the block's railed op-amps, or 1. `current` is the iterate the rows were
+   * stamped at and `next` the undamped solve. The history read here is the one the stamps
+   * wrote this iteration, so `differential` is the point each row's tangent was taken at and
+   * `cap` the step the next evaluation will allow; a request inside both bounds scales nothing.
+   * Mirrored in `Engine.cpp` (`opAmpStepDamping`); the two must agree to the operation.
+   */
+  opAmpStepDamping(block, blockIndex, current, next, dt, dc) {
+    let damping = 1;
+    for (const stamp of block.stamps) {
+      if (stamp.kind !== "ideal-opamp" || stamp.railHigh === null || stamp.railLow === null) {
+        continue;
+      }
+      const history = this.opampHistory.get(
+        packHistoryKey3(blockIndex, stamp.plus, stamp.minus, stamp.output)
+      );
+      if (history === void 0) continue;
+      const halfSwing = opAmpHalfSwing(stamp.railHigh, stamp.railLow);
+      const alpha = dc ? 1 : opAmpPoleAlpha(
+        stamp.openLoopGain,
+        opAmpGainBandwidthHz(stamp),
+        dt,
+        this.sampleRate
+      );
+      const effectiveGain = alpha * stamp.openLoopGain;
+      const linearWidth = halfSwing / effectiveGain;
+      const band = OPAMP_DIFFERENTIAL_BAND * linearWidth;
+      const nextDifferential = clamp(
+        (next[stamp.plus] ?? 0) - (next[stamp.minus] ?? 0),
+        -band,
+        band
+      );
+      const magnitude = Math.abs(nextDifferential - history.differential);
+      if (magnitude > history.cap) {
+        damping = Math.min(damping, history.cap / magnitude);
+      }
+      const swing = 2 * halfSwing;
+      const outputStep = Math.abs((next[stamp.output] ?? 0) - (current[stamp.output] ?? 0));
+      if (outputStep > swing) {
+        damping = Math.min(damping, swing / outputStep);
+      }
+    }
+    return damping;
+  }
   /**
    * Build-order step 6, vertical slice: the part of a block's matrix that is the same for
    * every Newton iteration of this sample -- every stamp `newtonPortRowsOf` calls linear,
@@ -5073,7 +5139,7 @@ var ReferenceRuntime = class {
       const key = packHistoryKey3(blockIndex, stamp.plus, stamp.minus, stamp.output);
       const alpha = opAmpPoleAlpha(
         stamp.openLoopGain,
-        OPAMP_GAIN_BANDWIDTH_HZ,
+        opAmpGainBandwidthHz(stamp),
         dt,
         this.sampleRate
       );
@@ -5718,26 +5784,29 @@ var ReferenceRuntime = class {
         );
         const alpha = dc ? 1 : opAmpPoleAlpha(
           stamp.openLoopGain,
-          OPAMP_GAIN_BANDWIDTH_HZ,
+          opAmpGainBandwidthHz(stamp),
           dt,
           this.sampleRate
         );
         const effectiveGain = alpha * stamp.openLoopGain;
         const linearWidth = halfSwing / effectiveGain;
         const previous = this.opampHistory.get(opampKey);
-        const previousDifferential = previous?.differential ?? 0;
         const rawDifferential = (solution[stamp.plus] ?? 0) - (solution[stamp.minus] ?? 0);
         const band = OPAMP_DIFFERENTIAL_BAND * linearWidth;
         const bounded = clamp(rawDifferential, -band, band);
+        const previousDifferential = previous?.differential ?? bounded;
         const step = bounded - previousDifferential;
         const maxStep = OPAMP_MAX_DIFFERENTIAL_STEP * linearWidth;
         const reversing = previous !== void 0 && previous.step !== 0 && step !== 0 && Math.sign(step) !== Math.sign(previous.step);
         const previousCap = previous?.cap ?? maxStep;
         const cap = reversing ? Math.max(previousCap / 2, linearWidth / 64) : Math.min(maxStep, previousCap * 1.2);
         const limited = Math.abs(step) > cap;
+        const folded = cap <= linearWidth / 8 && Math.abs(step) >= linearWidth / 256;
         if (limited) {
           this.limitedIterate = true;
           this.limitedBy = `opamp +=${stamp.plus} -=${stamp.minus} out=${stamp.output}`;
+        }
+        if (limited || folded) {
           this.limitedOpamp = {
             key: opampKey,
             output: stamp.output,
@@ -5746,7 +5815,7 @@ var ReferenceRuntime = class {
             railLow: stamp.railLow,
             band,
             maxStep,
-            folded: cap <= linearWidth / 8
+            folded
           };
         }
         const differential = limited ? previousDifferential + Math.sign(step) * cap : bounded;
@@ -5763,10 +5832,11 @@ var ReferenceRuntime = class {
           clamp(scaled, -OPAMP_SATURATION_BAND, OPAMP_SATURATION_BAND)
         );
         const slope = effectiveGain * (1 - derivativeShape * derivativeShape);
+        const linearisedAt = limited ? differential : rawDifferential;
         matrix[row][stamp.output] += 1;
         matrix[row][stamp.plus] -= slope;
         matrix[row][stamp.minus] += slope;
-        rhs[row] = output - slope * differential;
+        rhs[row] = output - slope * linearisedAt;
         break;
       }
       case "vccs": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vessel-dsp/runtime",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"description": "Real-time MNA simulation runtime and solver console for VesselDSP Program ROMs.",
 	"keywords": [
 		"guitar-pedal",
@@ -58,7 +58,7 @@
 		"generate-kernels": "bun scripts/generate-kernels.ts"
 	},
 	"dependencies": {
-		"@vessel-dsp/compiler": "0.4.0"
+		"@vessel-dsp/compiler": "0.5.0"
 	},
 	"publishConfig": {
 		"access": "public"