@fullstackcraftllc/floe 0.0.14 → 0.0.15

package/dist/hedgeflow/charm.d.ts

@@ -0,0 +1,23 @@
+import { ExposurePerExpiry } from '../types';
+import { CharmIntegralConfig, CharmIntegral } from './types';
+/**
+ * Compute the charm integral from now until expiration.
+ *
+ * The charm integral represents the cumulative expected delta change
+ * from time decay alone — i.e., what happens to dealer hedging
+ * regardless of price movement. This is the "unconditional" pressure.
+ *
+ * The dollar CEX values already incorporate Black-Scholes time decay
+ * acceleration (charm ∝ 1/√T near expiry), so no additional time
+ * weighting is needed. Larger CEX values near expiry are the math
+ * doing its job, not something we need to amplify.
+ *
+ * When open interest changes intraday (detected via live OI tracking),
+ * this function should be recomputed with updated exposures to reflect
+ * the new charm landscape.
+ *
+ * @param exposures - Current per-strike exposure data (with live OI if available)
+ * @param config - Optional time step configuration
+ * @returns Charm integral analysis with cumulative curve and per-strike breakdown
+ */
+export declare function computeCharmIntegral(exposures: ExposurePerExpiry, config?: CharmIntegralConfig): CharmIntegral;

package/dist/hedgeflow/charm.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCharmIntegral = computeCharmIntegral;
+/**
+ * Compute the charm integral from now until expiration.
+ *
+ * The charm integral represents the cumulative expected delta change
+ * from time decay alone — i.e., what happens to dealer hedging
+ * regardless of price movement. This is the "unconditional" pressure.
+ *
+ * The dollar CEX values already incorporate Black-Scholes time decay
+ * acceleration (charm ∝ 1/√T near expiry), so no additional time
+ * weighting is needed. Larger CEX values near expiry are the math
+ * doing its job, not something we need to amplify.
+ *
+ * When open interest changes intraday (detected via live OI tracking),
+ * this function should be recomputed with updated exposures to reflect
+ * the new charm landscape.
+ *
+ * @param exposures - Current per-strike exposure data (with live OI if available)
+ * @param config - Optional time step configuration
+ * @returns Charm integral analysis with cumulative curve and per-strike breakdown
+ */
+function computeCharmIntegral(exposures, config = {}) {
+    const { timeStepMinutes = 15 } = config;
+    const spot = exposures.spotPrice;
+    const expiration = exposures.expiration;
+    const now = Date.now();
+    const msRemaining = expiration - now;
+    const minutesRemaining = Math.max(0, msRemaining / 60000);
+    // Per-strike charm breakdown
+    const totalAbsCharm = exposures.strikeExposures.reduce((sum, s) => sum + Math.abs(s.charmExposure), 0);
+    const strikeContributions = exposures.strikeExposures
+        .filter(s => s.charmExposure !== 0)
+        .map(s => ({
+        strike: s.strikePrice,
+        charmExposure: s.charmExposure,
+        fractionOfTotal: totalAbsCharm > 0
+            ? Math.abs(s.charmExposure) / totalAbsCharm
+            : 0,
+    }))
+        .sort((a, b) => Math.abs(b.charmExposure) - Math.abs(a.charmExposure));
+    // Build time-bucketed charm curve
+    // The total CEX is already a per-day rate. For sub-day intervals,
+    // we scale by the fraction of the day each bucket represents.
+    const totalCEX = exposures.totalCharmExposure;
+    const buckets = [];
+    let cumulativeCEX = 0;
+    if (minutesRemaining <= 0) {
+        // Already expired
+        return {
+            spot,
+            expiration,
+            computedAt: now,
+            minutesRemaining: 0,
+            totalCharmToClose: 0,
+            direction: 'neutral',
+            buckets: [],
+            strikeContributions,
+        };
+    }
+    // Walk from now backward toward expiry in timeStepMinutes increments.
+    // At each step, the charm exposure intensifies because the remaining
+    // options are closer to expiry.
+    //
+    // Since CEX is already the dollar exposure rate that incorporates the
+    // current time to expiry, and charm accelerates as 1/√T, we model
+    // the instantaneous charm at t minutes remaining as:
+    //
+    //   CEX(t) ≈ totalCEX * √(minutesRemaining / t)
+    //
+    // This scaling comes from charm ∝ 1/√T: if current charm is computed
+    // at T minutes out, then at t < T minutes it will be larger by √(T/t).
+    //
+    // The integral of CEX(t) dt from t=minutesRemaining down to t=0
+    // gives the total expected delta change, but note the integral of
+    // 1/√t diverges — in practice, charm exposure is bounded because
+    // deep ITM/OTM options have vanishing charm. We cap at t=1 minute.
+    for (let t = minutesRemaining; t >= Math.max(1, timeStepMinutes); t -= timeStepMinutes) {
+        // Charm at this time: scale by √(minutesRemaining / t)
+        const timeScaling = Math.sqrt(minutesRemaining / t);
+        const instantCEX = totalCEX * timeScaling;
+        // Each bucket represents timeStepMinutes of elapsed time.
+        // Convert to fraction of a trading day for the integral.
+        // 6.5 hours = 390 minutes in a standard session.
+        const bucketFractionOfDay = timeStepMinutes / 390;
+        const bucketContribution = instantCEX * bucketFractionOfDay;
+        cumulativeCEX += bucketContribution;
+        buckets.push({
+            minutesRemaining: t,
+            instantaneousCEX: instantCEX,
+            cumulativeCEX,
+        });
+    }
+    // Determine direction
+    let direction = 'neutral';
+    if (cumulativeCEX > 0) {
+        direction = 'buying';
+    }
+    else if (cumulativeCEX < 0) {
+        direction = 'selling';
+    }
+    return {
+        spot,
+        expiration,
+        computedAt: now,
+        minutesRemaining,
+        totalCharmToClose: cumulativeCEX,
+        direction,
+        buckets,
+        strikeContributions,
+    };
+}

package/dist/hedgeflow/curve.d.ts

@@ -0,0 +1,27 @@
+import { ExposurePerExpiry, IVSurface } from '../types';
+import { HedgeImpulseConfig, HedgeImpulseCurve } from './types';
+/**
+ * Compute the hedge impulse curve across a price grid.
+ *
+ * The hedge impulse H(S) at each price level S combines gamma and vanna
+ * exposures via the empirical spot-vol coupling relationship:
+ *
+ *   H(S) = GEX_smoothed(S) - (k / S) * VEX_smoothed(S)
+ *
+ * where:
+ * - GEX_smoothed(S) is the kernel-smoothed gamma exposure at S
+ * - VEX_smoothed(S) is the kernel-smoothed vanna exposure at S
+ * - k is the spot-vol coupling coefficient derived from the IV surface
+ *
+ * Positive H(S) means a spot move toward S triggers dealer buying that
+ * dampens the move (mean-reversion / "wall" behavior).
+ *
+ * Negative H(S) means a spot move toward S triggers dealer selling that
+ * amplifies the move (trend acceleration / "vacuum" behavior).
+ *
+ * @param exposures - Per-strike gamma, vanna, charm exposures
+ * @param ivSurface - The IV surface for regime derivation
+ * @param config - Optional configuration for grid and kernel parameters
+ * @returns Complete hedge impulse curve analysis
+ */
+export declare function computeHedgeImpulseCurve(exposures: ExposurePerExpiry, ivSurface: IVSurface, config?: HedgeImpulseConfig): HedgeImpulseCurve;

package/dist/hedgeflow/curve.js

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeHedgeImpulseCurve = computeHedgeImpulseCurve;
+const regime_1 = require("./regime");
+/**
+ * Detect the modal (most common) strike spacing from an array of strikes.
+ * Handles irregular spacing by finding the most frequent gap.
+ */
+function detectStrikeSpacing(strikes) {
+    if (strikes.length < 2)
+        return 1;
+    const gaps = [];
+    for (let i = 1; i < strikes.length; i++) {
+        const gap = Math.abs(strikes[i] - strikes[i - 1]);
+        if (gap > 0)
+            gaps.push(gap);
+    }
+    if (gaps.length === 0)
+        return 1;
+    // Find modal gap (most common spacing)
+    const gapCounts = new Map();
+    for (const gap of gaps) {
+        // Round to avoid floating point issues
+        const rounded = Math.round(gap * 100) / 100;
+        gapCounts.set(rounded, (gapCounts.get(rounded) || 0) + 1);
+    }
+    let modalGap = gaps[0];
+    let maxCount = 0;
+    for (const [gap, count] of gapCounts) {
+        if (count > maxCount) {
+            maxCount = count;
+            modalGap = gap;
+        }
+    }
+    return modalGap;
+}
+/**
+ * Derive the spot-vol coupling coefficient k from the IV surface.
+ *
+ * From stochastic vol models, the skew encodes the spot-vol correlation:
+ *   skew ≈ rho_SV * volOfVol / atmIV
+ *
+ * The spot-vol coupling for the dealer hedge equation is:
+ *   dSigma ≈ -k * (dS/S)
+ *
+ * So k = -rho_SV * volOfVol * sqrt(252) = -impliedSpotVolCorr * atmIV * sqrt(252)
+ *
+ * For equity indices this typically lands in the range 4-12.
+ */
+function deriveSpotVolCoupling(regimeParams) {
+    const { impliedSpotVolCorr, atmIV } = regimeParams;
+    // k = -correlation * atmIV * annualization
+    // The negative sign is because negative correlation (spot down = vol up)
+    // should produce a positive k (so that -k/S * Vanna has the right sign)
+    const k = -impliedSpotVolCorr * atmIV * Math.sqrt(252);
+    // Clamp to reasonable range (2 to 20)
+    return Math.max(2, Math.min(20, k));
+}
+/**
+ * Apply Gaussian kernel smoothing to map strike-space exposures
+ * into price-space at a given evaluation point.
+ *
+ * weight(K, S) = exp(-((K - S) / lambda)^2)
+ *
+ * @param strikes - Strike prices where exposures are defined
+ * @param values - Exposure values at each strike
+ * @param evalPrice - Price level to evaluate at
+ * @param lambda - Kernel width in price units
+ * @returns Smoothed exposure value at evalPrice
+ */
+function kernelSmooth(strikes, values, evalPrice, lambda) {
+    let weightedSum = 0;
+    let weightSum = 0;
+    for (let i = 0; i < strikes.length; i++) {
+        const dist = (strikes[i] - evalPrice) / lambda;
+        const weight = Math.exp(-(dist * dist));
+        weightedSum += values[i] * weight;
+        weightSum += weight;
+    }
+    return weightSum > 0 ? weightedSum / weightSum : 0;
+}
+/**
+ * Compute the hedge impulse curve across a price grid.
+ *
+ * The hedge impulse H(S) at each price level S combines gamma and vanna
+ * exposures via the empirical spot-vol coupling relationship:
+ *
+ *   H(S) = GEX_smoothed(S) - (k / S) * VEX_smoothed(S)
+ *
+ * where:
+ * - GEX_smoothed(S) is the kernel-smoothed gamma exposure at S
+ * - VEX_smoothed(S) is the kernel-smoothed vanna exposure at S
+ * - k is the spot-vol coupling coefficient derived from the IV surface
+ *
+ * Positive H(S) means a spot move toward S triggers dealer buying that
+ * dampens the move (mean-reversion / "wall" behavior).
+ *
+ * Negative H(S) means a spot move toward S triggers dealer selling that
+ * amplifies the move (trend acceleration / "vacuum" behavior).
+ *
+ * @param exposures - Per-strike gamma, vanna, charm exposures
+ * @param ivSurface - The IV surface for regime derivation
+ * @param config - Optional configuration for grid and kernel parameters
+ * @returns Complete hedge impulse curve analysis
+ */
+function computeHedgeImpulseCurve(exposures, ivSurface, config = {}) {
+    const { rangePercent = 3, stepPercent = 0.05, kernelWidthStrikes = 2, } = config;
+    const spot = exposures.spotPrice;
+    // Derive regime params and spot-vol coupling from IV surface
+    const regimeParams = (0, regime_1.deriveRegimeParams)(ivSurface, spot);
+    const k = deriveSpotVolCoupling(regimeParams);
+    // Extract strike-space data
+    const strikes = exposures.strikeExposures.map(s => s.strikePrice);
+    const gexValues = exposures.strikeExposures.map(s => s.gammaExposure);
+    const vexValues = exposures.strikeExposures.map(s => s.vannaExposure);
+    // Detect strike spacing and compute kernel width in price units
+    const strikeSpacing = detectStrikeSpacing(strikes);
+    const lambda = kernelWidthStrikes * strikeSpacing;
+    // Build price grid
+    const gridMin = spot * (1 - rangePercent / 100);
+    const gridMax = spot * (1 + rangePercent / 100);
+    const gridStep = spot * (stepPercent / 100);
+    const curve = [];
+    for (let price = gridMin; price <= gridMax; price += gridStep) {
+        const gamma = kernelSmooth(strikes, gexValues, price, lambda);
+        const vanna = kernelSmooth(strikes, vexValues, price, lambda);
+        // H(S) = Gamma(S) - (k / S) * Vanna(S)
+        const impulse = gamma - (k / price) * vanna;
+        curve.push({ price, gamma, vanna, impulse });
+    }
+    // Compute impulse at current spot
+    const impulseAtSpot = interpolateImpulseAtPrice(curve, spot);
+    // Compute slope at current spot (dH/dS via central difference)
+    const slopeAtSpot = computeSlopeAtPrice(curve, spot);
+    // Find zero crossings
+    const zeroCrossings = findZeroCrossings(curve);
+    // Find local extrema
+    const extrema = findExtrema(curve);
+    // Compute directional asymmetry
+    const asymmetry = computeAsymmetry(curve, spot);
+    // Classify regime
+    const regime = classifyRegime(impulseAtSpot, slopeAtSpot, asymmetry, curve, spot);
+    // Find nearest attractors (positive impulse basins)
+    const basinsAbove = extrema.filter(e => e.type === 'basin' && e.price > spot);
+    const basinsBelow = extrema.filter(e => e.type === 'basin' && e.price < spot);
+    const nearestAttractorAbove = basinsAbove.length > 0
+        ? basinsAbove.reduce((a, b) => a.price < b.price ? a : b).price
+        : null;
+    const nearestAttractorBelow = basinsBelow.length > 0
+        ? basinsBelow.reduce((a, b) => a.price > b.price ? a : b).price
+        : null;
+    return {
+        spot,
+        expiration: exposures.expiration,
+        computedAt: Date.now(),
+        spotVolCoupling: k,
+        kernelWidth: lambda,
+        strikeSpacing,
+        curve,
+        impulseAtSpot,
+        slopeAtSpot,
+        zeroCrossings,
+        extrema,
+        asymmetry,
+        regime,
+        nearestAttractorAbove,
+        nearestAttractorBelow,
+    };
+}
+/**
+ * Interpolate impulse value at an arbitrary price within the curve
+ */
+function interpolateImpulseAtPrice(curve, price) {
+    if (curve.length === 0)
+        return 0;
+    if (price <= curve[0].price)
+        return curve[0].impulse;
+    if (price >= curve[curve.length - 1].price)
+        return curve[curve.length - 1].impulse;
+    for (let i = 0; i < curve.length - 1; i++) {
+        if (curve[i].price <= price && curve[i + 1].price >= price) {
+            const t = (price - curve[i].price) / (curve[i + 1].price - curve[i].price);
+            return curve[i].impulse + t * (curve[i + 1].impulse - curve[i].impulse);
+        }
+    }
+    return 0;
+}
+/**
+ * Compute slope of the impulse curve at a given price via central difference
+ */
+function computeSlopeAtPrice(curve, price) {
+    if (curve.length < 3)
+        return 0;
+    // Find bracketing points
+    const step = curve[1].price - curve[0].price;
+    const above = interpolateImpulseAtPrice(curve, price + step);
+    const below = interpolateImpulseAtPrice(curve, price - step);
+    return (above - below) / (2 * step);
+}
+/**
+ * Find all zero crossings of the impulse curve
+ */
+function findZeroCrossings(curve) {
+    const crossings = [];
+    for (let i = 0; i < curve.length - 1; i++) {
+        const a = curve[i].impulse;
+        const b = curve[i + 1].impulse;
+        if (a * b < 0) {
+            // Linear interpolation for crossing price
+            const t = Math.abs(a) / (Math.abs(a) + Math.abs(b));
+            const crossPrice = curve[i].price + t * (curve[i + 1].price - curve[i].price);
+            crossings.push({
+                price: crossPrice,
+                direction: b > a ? 'rising' : 'falling',
+            });
+        }
+    }
+    return crossings;
+}
+/**
+ * Find local extrema (basins and peaks) of the impulse curve
+ */
+function findExtrema(curve) {
+    const extrema = [];
+    for (let i = 1; i < curve.length - 1; i++) {
+        const prev = curve[i - 1].impulse;
+        const curr = curve[i].impulse;
+        const next = curve[i + 1].impulse;
+        // Local maximum
+        if (curr > prev && curr > next && curr > 0) {
+            extrema.push({
+                price: curve[i].price,
+                impulse: curr,
+                type: 'basin', // positive max = attractor
+            });
+        }
+        // Local minimum
+        if (curr < prev && curr < next && curr < 0) {
+            extrema.push({
+                price: curve[i].price,
+                impulse: curr,
+                type: 'peak', // negative min = accelerator
+            });
+        }
+    }
+    return extrema;
+}
+/**
+ * Compute directional asymmetry by integrating impulse above and below spot.
+ *
+ * The integration uses the trapezoidal rule over the default range of ±0.5% of spot.
+ * The side with more negative impulse is the path of least resistance.
+ */
+function computeAsymmetry(curve, spot, integrationRangePercent = 0.5) {
+    const rangePrice = spot * (integrationRangePercent / 100);
+    // Integrate from spot to spot + range (upside)
+    let upsideIntegral = 0;
+    let downsideIntegral = 0;
+    const step = curve.length > 1 ? curve[1].price - curve[0].price : 1;
+    for (const point of curve) {
+        if (point.price > spot && point.price <= spot + rangePrice) {
+            upsideIntegral += point.impulse * step;
+        }
+        if (point.price < spot && point.price >= spot - rangePrice) {
+            downsideIntegral += point.impulse * step;
+        }
+    }
+    // More negative integral = more acceleration = path of least resistance
+    let bias = 'neutral';
+    const threshold = Math.max(Math.abs(upsideIntegral), Math.abs(downsideIntegral)) * 0.1;
+    if (upsideIntegral < downsideIntegral - threshold) {
+        bias = 'up'; // Upside has more negative impulse = price gets pulled up
+    }
+    else if (downsideIntegral < upsideIntegral - threshold) {
+        bias = 'down'; // Downside has more negative impulse = price gets pulled down
+    }
+    const denominator = Math.abs(downsideIntegral) || 1e-10;
+    const asymmetryRatio = Math.abs(upsideIntegral) / denominator;
+    return {
+        upside: upsideIntegral,
+        downside: downsideIntegral,
+        integrationRangePercent,
+        bias,
+        asymmetryRatio,
+    };
+}
+/**
+ * Classify the current regime based on the impulse curve characteristics
+ */
+function classifyRegime(impulseAtSpot, slopeAtSpot, asymmetry, curve, spot) {
+    // Compute a threshold based on the curve's overall scale
+    const impulseValues = curve.map(p => Math.abs(p.impulse));
+    const meanAbsImpulse = impulseValues.reduce((a, b) => a + b, 0) / impulseValues.length;
+    if (meanAbsImpulse === 0)
+        return 'neutral';
+    const normalizedAtSpot = impulseAtSpot / meanAbsImpulse;
+    // Strong positive impulse at spot = pinned
+    if (normalizedAtSpot > 0.5) {
+        return 'pinned';
+    }
+    // Negative impulse at spot = expansion potential
+    if (normalizedAtSpot < -0.3) {
+        if (asymmetry.bias === 'up')
+            return 'squeeze-up';
+        if (asymmetry.bias === 'down')
+            return 'squeeze-down';
+        return 'expansion';
+    }
+    // Weak impulse at spot but strong asymmetry
+    if (asymmetry.bias === 'up' && asymmetry.asymmetryRatio > 1.5)
+        return 'squeeze-up';
+    if (asymmetry.bias === 'down' && asymmetry.asymmetryRatio > 1.5)
+        return 'squeeze-down';
+    return 'neutral';
+}

package/dist/hedgeflow/index.d.ts

@@ -0,0 +1,33 @@
+import { ExposurePerExpiry, IVSurface } from '../types';
+import { HedgeImpulseConfig, CharmIntegralConfig, HedgeFlowAnalysis } from './types';
+export type { MarketRegime, RegimeParams, HedgeImpulseConfig, HedgeImpulsePoint, HedgeImpulseCurve, ZeroCrossing, ImpulseExtremum, DirectionalAsymmetry, ImpulseRegime, CharmIntegralConfig, CharmBucket, CharmIntegral, HedgeFlowAnalysis, } from './types';
+export { deriveRegimeParams, interpolateIVAtStrike } from './regime';
+export { computeHedgeImpulseCurve } from './curve';
+export { computeCharmIntegral } from './charm';
+/**
+ * Compute a complete hedge flow analysis for a single expiration.
+ *
+ * This combines the hedge impulse curve (conditional: what happens if
+ * price moves) with the charm integral (unconditional: what happens
+ * from time passage alone).
+ *
+ * The two analyses are intentionally kept separate because they answer
+ * orthogonal questions:
+ *
+ * - Impulse curve: "If spot moves to price S, do dealers amplify or
+ *   dampen the move?" (Left panel)
+ * - Charm integral: "If spot does nothing, where does time decay
+ *   push things?" (Right panel)
+ *
+ * Both update in real-time as:
+ * - Spot price changes → impulse curve re-evaluates k and kernel positions
+ * - Option quotes change → IV surface updates → regime params change
+ * - Open interest changes → exposure recalculation → both panels update
+ *
+ * @param exposures - Per-strike gamma, vanna, charm exposures for one expiration
+ * @param ivSurface - IV surface for the same expiration (used for regime derivation)
+ * @param impulseConfig - Optional config for the impulse curve grid and kernel
+ * @param charmConfig - Optional config for the charm integral time stepping
+ * @returns Combined hedge flow analysis
+ */
+export declare function analyzeHedgeFlow(exposures: ExposurePerExpiry, ivSurface: IVSurface, impulseConfig?: HedgeImpulseConfig, charmConfig?: CharmIntegralConfig): HedgeFlowAnalysis;

package/dist/hedgeflow/index.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCharmIntegral = exports.computeHedgeImpulseCurve = exports.interpolateIVAtStrike = exports.deriveRegimeParams = void 0;
+exports.analyzeHedgeFlow = analyzeHedgeFlow;
+const regime_1 = require("./regime");
+const curve_1 = require("./curve");
+const charm_1 = require("./charm");
+// Re-export regime functions
+var regime_2 = require("./regime");
+Object.defineProperty(exports, "deriveRegimeParams", { enumerable: true, get: function () { return regime_2.deriveRegimeParams; } });
+Object.defineProperty(exports, "interpolateIVAtStrike", { enumerable: true, get: function () { return regime_2.interpolateIVAtStrike; } });
+// Re-export computation functions
+var curve_2 = require("./curve");
+Object.defineProperty(exports, "computeHedgeImpulseCurve", { enumerable: true, get: function () { return curve_2.computeHedgeImpulseCurve; } });
+var charm_2 = require("./charm");
+Object.defineProperty(exports, "computeCharmIntegral", { enumerable: true, get: function () { return charm_2.computeCharmIntegral; } });
+/**
+ * Compute a complete hedge flow analysis for a single expiration.
+ *
+ * This combines the hedge impulse curve (conditional: what happens if
+ * price moves) with the charm integral (unconditional: what happens
+ * from time passage alone).
+ *
+ * The two analyses are intentionally kept separate because they answer
+ * orthogonal questions:
+ *
+ * - Impulse curve: "If spot moves to price S, do dealers amplify or
+ *   dampen the move?" (Left panel)
+ * - Charm integral: "If spot does nothing, where does time decay
+ *   push things?" (Right panel)
+ *
+ * Both update in real-time as:
+ * - Spot price changes → impulse curve re-evaluates k and kernel positions
+ * - Option quotes change → IV surface updates → regime params change
+ * - Open interest changes → exposure recalculation → both panels update
+ *
+ * @param exposures - Per-strike gamma, vanna, charm exposures for one expiration
+ * @param ivSurface - IV surface for the same expiration (used for regime derivation)
+ * @param impulseConfig - Optional config for the impulse curve grid and kernel
+ * @param charmConfig - Optional config for the charm integral time stepping
+ * @returns Combined hedge flow analysis
+ */
+function analyzeHedgeFlow(exposures, ivSurface, impulseConfig = {}, charmConfig = {}) {
+    const regimeParams = (0, regime_1.deriveRegimeParams)(ivSurface, exposures.spotPrice);
+    const impulseCurve = (0, curve_1.computeHedgeImpulseCurve)(exposures, ivSurface, impulseConfig);
+    const charmIntegral = (0, charm_1.computeCharmIntegral)(exposures, charmConfig);
+    return {
+        impulseCurve,
+        charmIntegral,
+        regimeParams,
+    };
+}

package/dist/hedgeflow/regime.d.ts

@@ -0,0 +1,7 @@
+import { IVSurface } from '../types';
+import { RegimeParams } from './types';
+/**
+ * Derive regime parameters from the IV surface
+ */
+export declare function deriveRegimeParams(ivSurface: IVSurface, spot: number): RegimeParams;
+export declare function interpolateIVAtStrike(strikes: number[], ivs: number[], targetStrike: number): number;

package/dist/hedgeflow/regime.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveRegimeParams = deriveRegimeParams;
+exports.interpolateIVAtStrike = interpolateIVAtStrike;
+/**
+ * Derive regime parameters from the IV surface
+ */
+function deriveRegimeParams(ivSurface, spot) {
+    const { strikes, smoothedIVs } = ivSurface;
+    const atmIV = interpolateIVAtStrike(strikes, smoothedIVs, spot) / 100;
+    const skew = calculateSkewAtSpot(strikes, smoothedIVs, spot);
+    const impliedSpotVolCorr = skewToCorrelation(skew);
+    const curvature = calculateCurvatureAtSpot(strikes, smoothedIVs, spot);
+    const impliedVolOfVol = curvatureToVolOfVol(curvature, atmIV);
+    const regime = ivToRegime(atmIV);
+    const expectedDailySpotMove = atmIV / Math.sqrt(252);
+    const expectedDailyVolMove = impliedVolOfVol / Math.sqrt(252);
+    return {
+        atmIV,
+        impliedSpotVolCorr,
+        impliedVolOfVol,
+        regime,
+        expectedDailySpotMove,
+        expectedDailyVolMove,
+    };
+}
+function skewToCorrelation(skew) {
+    const SKEW_TO_CORR_SCALE = 0.15;
+    return Math.max(-0.95, Math.min(0.5, skew * SKEW_TO_CORR_SCALE));
+}
+function curvatureToVolOfVol(curvature, atmIV) {
+    const VOL_OF_VOL_SCALE = 2.0;
+    return Math.sqrt(Math.abs(curvature)) * VOL_OF_VOL_SCALE * atmIV;
+}
+function ivToRegime(atmIV) {
+    if (atmIV < 0.15)
+        return 'calm';
+    if (atmIV < 0.20)
+        return 'normal';
+    if (atmIV < 0.35)
+        return 'stressed';
+    return 'crisis';
+}
+function interpolateIVAtStrike(strikes, ivs, targetStrike) {
+    if (strikes.length === 0 || ivs.length === 0)
+        return 20;
+    if (strikes.length === 1)
+        return ivs[0];
+    let lower = 0;
+    let upper = strikes.length - 1;
+    for (let i = 0; i < strikes.length - 1; i++) {
+        if (strikes[i] <= targetStrike && strikes[i + 1] >= targetStrike) {
+            lower = i;
+            upper = i + 1;
+            break;
+        }
+    }
+    if (targetStrike <= strikes[0])
+        return ivs[0];
+    if (targetStrike >= strikes[strikes.length - 1])
+        return ivs[ivs.length - 1];
+    const t = (targetStrike - strikes[lower]) / (strikes[upper] - strikes[lower]);
+    return ivs[lower] + t * (ivs[upper] - ivs[lower]);
+}
+function calculateSkewAtSpot(strikes, ivs, spot) {
+    if (strikes.length < 2)
+        return 0;
+    let lowerIdx = 0;
+    let upperIdx = strikes.length - 1;
+    for (let i = 0; i < strikes.length - 1; i++) {
+        if (strikes[i] <= spot && strikes[i + 1] >= spot) {
+            lowerIdx = i;
+            upperIdx = i + 1;
+            break;
+        }
+    }
+    const dIV = ivs[upperIdx] - ivs[lowerIdx];
+    const dK = strikes[upperIdx] - strikes[lowerIdx];
+    return dK > 0 ? (dIV / dK) * spot : 0;
+}
+function calculateCurvatureAtSpot(strikes, ivs, spot) {
+    if (strikes.length < 3)
+        return 0;
+    let centerIdx = 0;
+    for (let i = 0; i < strikes.length; i++) {
+        if (Math.abs(strikes[i] - spot) < Math.abs(strikes[centerIdx] - spot)) {
+            centerIdx = i;
+        }
+    }
+    if (centerIdx === 0 || centerIdx === strikes.length - 1)
+        return 0;
+    const h = (strikes[centerIdx + 1] - strikes[centerIdx - 1]) / 2;
+    if (h <= 0)
+        return 0;
+    const ivMinus = ivs[centerIdx - 1];
+    const iv = ivs[centerIdx];
+    const ivPlus = ivs[centerIdx + 1];
+    return ((ivPlus - 2 * iv + ivMinus) / (h * h)) * spot * spot;
+}