tmmcore 0.1.0 → 0.2.0

package/src/taylorJet.js

@@ -0,0 +1,261 @@
+/**
+ * taylorJet.js : third-order truncated Taylor arithmetic for complex functions.
+ *
+ * A jet stores the coefficients of a truncated power series:
+ *
+ *     [ f, f', f''/2!, f'''/3! ]
+ *
+ * each entry a complex `[re, im]` pair. Every operation below is ordinary power-
+ * series algebra, so composing them differentiates a function exactly, with no
+ * finite differences and no step size to choose. Feed a jet through the same
+ * code that computes a value and the derivatives come out alongside it.
+ *
+ * This is what makes the phase-dispersion kernel possible: carry the
+ * characteristic matrix in jets of angular frequency and the reflection
+ * coefficient emerges with the three derivatives that group delay, GDD and TOD
+ * are built from.
+ *
+ * The differentiation variable is whatever the caller chose. In `phase.js` it is
+ * angular frequency, so a jet of the refractive index means
+ * `[ñ, dñ/dω, (d²ñ/dω²)/2, (d³ñ/dω³)/6]`. Use `jetFromDerivatives` to build one
+ * from plain derivatives without doing the factorials by hand, and
+ * `jetDerivatives` to read them back.
+ *
+ * All arithmetic is double precision.
+ */
+
+/** Highest derivative carried. Jets are arrays of `JET_ORDER + 1` entries. */
+export const JET_ORDER = 3;
+
+const zero = () => [0, 0];
+const addComplex = (a, b) => [a[0] + b[0], a[1] + b[1]];
+const subComplex = (a, b) => [a[0] - b[0], a[1] - b[1]];
+const scaleComplex = (a, scalar) => [a[0] * scalar, a[1] * scalar];
+const multiplyComplex = (a, b) => [
+    a[0] * b[0] - a[1] * b[1],
+    a[0] * b[1] + a[1] * b[0],
+];
+const divideComplex = (a, b) => {
+    const denominator = b[0] * b[0] + b[1] * b[1];
+    return [
+        (a[0] * b[0] + a[1] * b[1]) / denominator,
+        (a[1] * b[0] - a[0] * b[1]) / denominator,
+    ];
+};
+const sqrtComplex = (value) => {
+    const magnitudeRoot = Math.sqrt(Math.hypot(value[0], value[1]));
+    const angle = Math.atan2(value[1], value[0]) / 2;
+    return [magnitudeRoot * Math.cos(angle), magnitudeRoot * Math.sin(angle)];
+};
+
+/** A constant: value with all derivatives zero. */
+export function jetConstant(value, imaginary = 0) {
+    return [[value, imaginary], zero(), zero(), zero()];
+}
+
+/**
+ * Build a jet from plain derivatives, applying the factorials.
+ * Each argument is a number or a complex `[re, im]` pair.
+ */
+export function jetFromDerivatives(value, first = 0, second = 0, third = 0) {
+    const asComplex = item => Array.isArray(item) ? [...item] : [item, 0];
+    return [
+        asComplex(value),
+        asComplex(first),
+        scaleComplex(asComplex(second), 1 / 2),
+        scaleComplex(asComplex(third), 1 / 6),
+    ];
+}
+
+/** Read a jet back as plain derivatives `[f, f', f'', f''']`. */
+export function jetDerivatives(jet) {
+    return [jet[0], jet[1], scaleComplex(jet[2], 2), scaleComplex(jet[3], 6)];
+}
+
+export function jetAdd(left, right) {
+    return left.map((value, index) => addComplex(value, right[index]));
+}
+
+export function jetSubtract(left, right) {
+    return left.map((value, index) => subComplex(value, right[index]));
+}
+
+/** Multiply every order by a real scalar. */
+export function jetScale(jet, scalar) {
+    return jet.map(value => scaleComplex(value, scalar));
+}
+
+export function jetMultiply(left, right) {
+    const result = Array.from({ length: JET_ORDER + 1 }, zero);
+    for (let order = 0; order <= JET_ORDER; order++) {
+        for (let index = 0; index <= order; index++) {
+            result[order] = addComplex(
+                result[order],
+                multiplyComplex(left[index], right[order - index]),
+            );
+        }
+    }
+    return result;
+}
+
+export function jetReciprocal(jet) {
+    const result = Array.from({ length: JET_ORDER + 1 }, zero);
+    result[0] = divideComplex([1, 0], jet[0]);
+    for (let order = 1; order <= JET_ORDER; order++) {
+        let sum = zero();
+        for (let index = 1; index <= order; index++) {
+            sum = addComplex(sum, multiplyComplex(jet[index], result[order - index]));
+        }
+        result[order] = scaleComplex(divideComplex(sum, jet[0]), -1);
+    }
+    return result;
+}
+
+export function jetDivide(numerator, denominator) {
+    return jetMultiply(numerator, jetReciprocal(denominator));
+}
+
+/** Principal square root, branch matching `csqrt` in tmm.js. */
+export function jetSqrt(jet) {
+    const result = Array.from({ length: JET_ORDER + 1 }, zero);
+    result[0] = sqrtComplex(jet[0]);
+    const twiceRoot = scaleComplex(result[0], 2);
+    for (let order = 1; order <= JET_ORDER; order++) {
+        let known = zero();
+        for (let index = 1; index < order; index++) {
+            known = addComplex(known, multiplyComplex(result[index], result[order - index]));
+        }
+        result[order] = divideComplex(subComplex(jet[order], known), twiceRoot);
+    }
+    return result;
+}
+
+export function jetExp(jet) {
+    const result = Array.from({ length: JET_ORDER + 1 }, zero);
+    const magnitude = Math.exp(jet[0][0]);
+    result[0] = [magnitude * Math.cos(jet[0][1]), magnitude * Math.sin(jet[0][1])];
+    for (let order = 1; order <= JET_ORDER; order++) {
+        let sum = zero();
+        for (let index = 1; index <= order; index++) {
+            sum = addComplex(
+                sum,
+                scaleComplex(multiplyComplex(jet[index], result[order - index]), index),
+            );
+        }
+        result[order] = scaleComplex(sum, 1 / order);
+    }
+    return result;
+}
+
+export function jetLog(jet) {
+    const result = Array.from({ length: JET_ORDER + 1 }, zero);
+    result[0] = [Math.log(Math.hypot(jet[0][0], jet[0][1])), Math.atan2(jet[0][1], jet[0][0])];
+    const derivative = [jet[1], scaleComplex(jet[2], 2), scaleComplex(jet[3], 3), zero()];
+    const quotient = jetMultiply(derivative, jetReciprocal(jet));
+    for (let order = 1; order <= JET_ORDER; order++) {
+        result[order] = scaleComplex(quotient[order - 1], 1 / order);
+    }
+    return result;
+}
+
+/** Real power via exp(p log z); the log branch cut applies. */
+export function jetPower(jet, exponent) {
+    return jetExp(jetScale(jetLog(jet), exponent));
+}
+
+/** Sine and cosine together, since the recurrences share their terms. */
+export function jetSinCos(jet) {
+    const sine = Array.from({ length: JET_ORDER + 1 }, zero);
+    const cosine = Array.from({ length: JET_ORDER + 1 }, zero);
+    const [real, imaginary] = jet[0];
+    sine[0] = [Math.sin(real) * Math.cosh(imaginary), Math.cos(real) * Math.sinh(imaginary)];
+    cosine[0] = [Math.cos(real) * Math.cosh(imaginary), -Math.sin(real) * Math.sinh(imaginary)];
+    for (let order = 1; order <= JET_ORDER; order++) {
+        let sineSum = zero();
+        let cosineSum = zero();
+        for (let index = 1; index <= order; index++) {
+            sineSum = addComplex(
+                sineSum,
+                scaleComplex(multiplyComplex(jet[index], cosine[order - index]), index),
+            );
+            cosineSum = addComplex(
+                cosineSum,
+                scaleComplex(multiplyComplex(jet[index], sine[order - index]), index),
+            );
+        }
+        sine[order] = scaleComplex(sineSum, 1 / order);
+        cosine[order] = scaleComplex(cosineSum, -1 / order);
+    }
+    return { sine, cosine };
+}
+
+export const jetSin = jet => jetSinCos(jet).sine;
+export const jetCos = jet => jetSinCos(jet).cosine;
+
+/**
+ * Chain rule for a scalar function known only through its derivatives.
+ *
+ * Given f(x0) and [f'(x0), f''(x0), f'''(x0)], and a jet for x, return the jet
+ * for f(x). This is the bridge from a dispersion formula differentiated by hand
+ * or by a symbolic tool into the jet arithmetic here.
+ */
+export function jetCompose(value, derivatives, xJet) {
+    const displacement = xJet.map((coefficient, index) => index === 0 ? zero() : coefficient);
+    const first = jetScale(displacement, derivatives[0] ?? 0);
+    const second = jetScale(jetMultiply(displacement, displacement), (derivatives[1] ?? 0) / 2);
+    const third = jetScale(
+        jetMultiply(jetMultiply(displacement, displacement), displacement),
+        (derivatives[2] ?? 0) / 6,
+    );
+    return jetAdd(jetAdd(jetConstant(value), first), jetAdd(second, third));
+}
+
+/**
+ * The jet of wavelength as a function of angular frequency, λ(ω) = 2πc/ω.
+ *
+ * Needs no value for c: with λ and ω both given, every derivative follows from
+ * λ' = -λ/ω. Units are therefore the caller's own, and the wavelength unit of
+ * the result is whatever `lambda` was given in.
+ */
+export function wavelengthOmegaJet(lambda, omega) {
+    // Written as repeated multiplication rather than `omega ** 3` so the C
+    // kernel can produce the identical double.
+    return [
+        [lambda, 0],
+        [-lambda / omega, 0],
+        [lambda / (omega * omega), 0],
+        [-lambda / (omega * omega * omega), 0],
+    ];
+}
+
+/** Combine a real-valued jet and an imaginary-valued jet into one complex jet. */
+export function jetWithImaginaryPart(realJet, imaginaryJet) {
+    return realJet.map((coefficient, index) => [coefficient[0], imaginaryJet[index][0]]);
+}
+
+/** Floor the value at `minimum`, flattening the jet to a constant when it bites. */
+export function jetClampRealMinimum(jet, minimum) {
+    return jet[0][0] >= minimum ? jet : jetConstant(minimum);
+}
+
+/**
+ * Bound the imaginary part, flattening the jet to a constant when it bites.
+ *
+ * Guards the same overflow `layerMatrix` guards in tmm.js: the phase thickness
+ * of a strongly absorbing layer grows without bound and cosh of it overflows.
+ * Past the limit the layer is already opaque, so the derivatives are zero to
+ * machine precision and dropping them keeps the matrix finite.
+ */
+export function jetClampImaginary(jet, limit) {
+    if (jet[0][1] > limit) {
+        return jet.map((coefficient, index) => [coefficient[0], index === 0 ? limit : 0]);
+    }
+    if (jet[0][1] < -limit) {
+        return jet.map((coefficient, index) => [coefficient[0], index === 0 ? -limit : 0]);
+    }
+    return jet;
+}
+
+export function jetIsFinite(jet) {
+    return jet.every(coefficient => coefficient.every(Number.isFinite));
+}

package/src/tmm.js

@@ -1,5 +1,5 @@
 /**
- * Transfer-matrix method for multilayer thin films — JavaScript reference
+ * Transfer-matrix method for multilayer thin films: JavaScript reference
  * implementation.
  *
  * System model:
@@ -226,7 +226,7 @@ export function tmm(lambda_nm, theta_deg, pol, n0, ns, layers) {
 //   dA/dd = −(dR/dd + dT/dd)
 // The host layer cancels automatically through Pre/Post (a needle of the
 // host index at an interior point gives ~0), so no nₐ²−n_host² term is
-// needed — exactly as in Sullivan's scheme.
+// needed, exactly as in Sullivan's scheme.
 //
 // Returns { R, T, A, gaps, intra } where
 //   gaps[pos]            = [{dR,dT,dA} per candidate]   pos = 0..N
@@ -360,7 +360,7 @@ export function tmmNeedleScan(lambda_nm, theta_deg, pol, n0, ns, layers,
 //   dM_k/dd_k = Q · [[ −sinδ,      −i cosδ / η ],
 //                    [ −i η cosδ,  −sinδ       ]]
 //
-// As δ→0 this collapses to [[0,−iQ/η],[−iQη,0]] — exactly the needle
+// As δ→0 this collapses to [[0,−iQ/η],[−iQη,0]], exactly the needle
 // A-matrix in tmmNeedleScan (needleA), i.e. the needle kernel is the δ=0
 // special case of this; a strong internal-consistency check.
 //
@@ -440,7 +440,7 @@ export function tmmThicknessJacobian(lambda_nm, theta_deg, pol, n0, ns, layers)
 // order optimization methods in the synthesis of multilayer coatings," Comp.
 // Maths. Math. Phys. 33, 1339 (1993)).
 //
-// Derivation (same Abelès matrix calculus as the Jacobian — Macleod Eq.
+// Derivation (same Abelès matrix calculus as the Jacobian, Macleod Eq.
 // 2.111/2.113; pre/post decomposition Sullivan & Dobrowolski 1996):
 //   [B,C] = M₀···M_{N-1}·[1,ηs];  ∂[B,C]/∂dₖ = Pre[k]·(dMₖ)·Post[k+1].
 //   Mixed second partials (i < j, position-ordered):

package/src/tmmWasm.js

@@ -1,9 +1,9 @@
 /**
- * tmmWasm.js — loader and ergonomic wrappers for the WebAssembly TMM kernel.
+ * tmmWasm.js : loader and ergonomic wrappers for the WebAssembly TMM kernel.
  *
  * The kernel (`tmm_kernel.c`, built to `tmm_kernel.wasm`) is a line-by-line port
- * of the JavaScript TMM in `tmm.js`. This module instantiates it — in a browser
- * main thread, a Web Worker, or Node — and exposes wrappers whose signatures
+ * of the JavaScript TMM in `tmm.js`. This module instantiates it : in a browser
+ * main thread, a Web Worker, or Node : and exposes wrappers whose signatures
  * mirror the JS functions.
  *
  * Acceleration is opt-in and falls back to JavaScript: if the `.wasm` is
@@ -11,16 +11,44 @@
  * return `null` and callers use the JS path. Results are identical either way
  * to float64 round-off.
  *
- * Instances are not shared across threads — there is no shared memory, so each
+ * Instances are not shared across threads : there is no shared memory, so each
  * context instantiates its own from the same bytes. Use `instantiateTmmWasm()`
  * where you already hold the bytes (a worker receives them in its init message)
  * and `initTmmWasmFromUrl()` where the artifact is fetchable.
  */
 
+import { omegaFromLambdaNm } from './phase.js';
+
 let _instance = null;     // TmmWasmInstance | null
 let _enabled = false;     // feature flag (default OFF)
 let _initPromise = null;  // de-dupe concurrent init
 
+// ── Jet marshalling ──────────────────────────────────────────────────────────
+// A jet crosses the boundary as 8 doubles, [re, im] per order.
+
+function writeJet(buf, offset, jet) {
+    for (let i = 0; i < 4; i++) {
+        buf[offset + 2 * i] = jet[i][0];
+        buf[offset + 2 * i + 1] = jet[i][1];
+    }
+}
+
+// The kernel writes NaN where the coefficient is exactly zero and the phase is
+// undefined; the JS reference returns null there, so agree with it.
+function readPhase(buf, offset) {
+    const magnitudeSquared = buf[offset + 4];
+    if (Number.isNaN(magnitudeSquared)) return null;
+    const phaseRad = buf[offset];
+    return {
+        phaseRad,
+        phaseDeg: phaseRad * 180 / Math.PI,
+        gd: buf[offset + 1],
+        gdd: buf[offset + 2],
+        tod: buf[offset + 3],
+        magnitudeSquared,
+    };
+}
+
 // Permissive imports: a STANDALONE_WASM build of pure-math C usually needs no
 // imports, but ALLOW_MEMORY_GROWTH may emit `emscripten_notify_memory_growth`,
 // and some toolchains emit WASI stubs. Cover them so instantiation never throws.
@@ -49,6 +77,11 @@ export class TmmWasmInstance {
         // Optional (added later for SQP/Newton accel): a .wasm built before the
         // Hessian kernel existed simply lacks it → callers fall back to JS.
         this._tmm_hessian = ex.tmm_hessian || ex._tmm_hessian || null;
+        // Optional, same reason: the phase-dispersion kernel arrived after the
+        // spectral one, so an older artifact lacks these three.
+        this._tmm_phase_one = ex.tmm_phase_one || ex._tmm_phase_one || null;
+        this._tmm_phase_spectrum = ex.tmm_phase_spectrum || ex._tmm_phase_spectrum || null;
+        this._tmm_phase_jacobian = ex.tmm_phase_jacobian || ex._tmm_phase_jacobian || null;
         const missingExports = !this.malloc || !this.free || !this._tmm_one ||
             !this._tmm_spectrum || !this._tmm_jacobian || !this._tmm_needle_scan;
         if (missingExports) {
@@ -63,7 +96,7 @@ export class TmmWasmInstance {
         if (!ptr) throw new Error('tmmWasm: malloc failed');
         return ptr;
     }
-    // Fresh view — memory.buffer is detached after any growth, so re-create
+    // Fresh view : memory.buffer is detached after any growth, so re-create
     // views AFTER all mallocs for a call are done.
     _view(ptr, nDoubles) {
         return new Float64Array(this.memory.buffer, ptr, nDoubles);
@@ -84,7 +117,7 @@ export class TmmWasmInstance {
     }
 
     /**
-     * Single (λ, θ, pol) — mirrors tmm() in thinFilmMath.js.
+     * Single (λ, θ, pol) : mirrors tmm() in thinFilmMath.js.
      * @returns {{R:number,T:number,A:number}}
      */
     tmmOne(lambda_nm, theta_deg, polCode /* 0=s,1=p */, n0, ns, layers) {
@@ -104,7 +137,7 @@ export class TmmWasmInstance {
     }
 
     /**
-     * Batched spectrum over a λ grid for BOTH polarizations — the boundary-
+     * Batched spectrum over a λ grid for BOTH polarizations : the boundary-
      * amortizing path behind evaluateSpectrum().
      * @param {number[]} lambdas
      * @param {[number,number][]} n0List  incident ñ per λ
@@ -160,7 +193,7 @@ export class TmmWasmInstance {
     }
 
     /**
-     * Analytic thickness Jacobian for one (λ, θ, pol) — mirrors
+     * Analytic thickness Jacobian for one (λ, θ, pol) : mirrors
      * tmmThicknessJacobian(). layers used AS-IS (index parity).
      * @returns {{R,T,A, dRdd:Float64Array, dTdd, dAdd, N}}
      */
@@ -182,7 +215,7 @@ export class TmmWasmInstance {
             n0[0], n0[1], ns[0], ns[1], P(oLay), N, P(oDR), P(oDT), P(oDA), P(oBase));
         // Re-create the view AFTER the kernel call (like tmmSpectrum): under
         // ALLOW_MEMORY_GROWTH the kernel may grow wasm memory, which detaches the
-        // ArrayBuffer `buf` was created over — reading the stale `buf` then yields
+        // ArrayBuffer `buf` was created over : reading the stale `buf` then yields
         // garbage / throws. `out` is a fresh view over the current buffer.
         const out = this._view(ptr, need);
         return {
@@ -197,7 +230,7 @@ export class TmmWasmInstance {
     hasHessian() { return !!this._tmm_hessian; }
 
     /**
-     * Analytic thickness Hessian for one (λ, θ, pol) — mirrors
+     * Analytic thickness Hessian for one (λ, θ, pol) : mirrors
      * tmmThicknessHessian(). Returns first AND second derivatives; the N×N
      * second-derivative blocks are reshaped into nested arrays (one Float64Array
      * row per layer, FULL symmetric) so the shape matches the JS oracle exactly.
@@ -238,8 +271,169 @@ export class TmmWasmInstance {
         };
     }
 
+    /** True if the loaded module carries the phase-dispersion kernel. */
+    hasPhase() { return !!this._tmm_phase_one; }
+
+    /**
+     * Phase, group delay, GDD and TOD at one wavelength : mirrors
+     * tmmPhaseDispersion() in phase.js.
+     *
+     * @param {number[][]} n0Jet  incident-medium index jet, 4 × [re, im]
+     * @param {number[][]} nsJet  substrate index jet
+     * @param {{nJet:number[][], d:number}[]} layers
+     * @param {{omega?:number, sinTheta0Jet?:number[][]}} [options]
+     * @returns {{r: object|null, t: object|null}}
+     */
+    tmmPhaseOne(lambda_nm, theta_deg, polCode, n0Jet, nsJet, layers, options = {}) {
+        const N = layers.length;
+        const omega = options.omega ?? omegaFromLambdaNm(lambda_nm);
+        const sinJet = options.sinTheta0Jet || null;
+        // arena: layerJets[8N] | thick[N] | n0[8] | ns[8] | sin[8] | out[10]
+        const oLay = 0, oThick = 8 * N, oN0 = oThick + N, oNs = oN0 + 8,
+              oSin = oNs + 8, oOut = oSin + 8;
+        const need = oOut + 10;
+        const ptr = this._scratch(need);
+        const buf = this._view(ptr, need);
+        for (let i = 0; i < N; i++) {
+            writeJet(buf, oLay + 8 * i, layers[i].nJet);
+            buf[oThick + i] = layers[i].d;
+        }
+        writeJet(buf, oN0, n0Jet);
+        writeJet(buf, oNs, nsJet);
+        if (sinJet) writeJet(buf, oSin, sinJet);
+        const P = (off) => ptr + off * 8;
+        this._tmm_phase_one(lambda_nm, omega, theta_deg, polCode | 0,
+            P(oN0), P(oNs), P(oLay), P(oThick), N, sinJet ? P(oSin) : 0, P(oOut));
+        const out = this._view(ptr, need);
+        return { r: readPhase(out, oOut), t: readPhase(out, oOut + 5) };
+    }
+
+    /**
+     * Batched phase dispersion over a λ grid : the boundary-amortizing path.
+     *
+     * Unlike `tmmSpectrum` this takes one polarization, because the kernel is an
+     * order of magnitude dearer per sample and callers at normal incidence would
+     * otherwise pay twice for the same numbers.
+     *
+     * @param {number[]} lambdas
+     * @param {number[][][]} n0Jets  index jet per λ
+     * @param {number[][][]} nsJets  index jet per λ
+     * @param {number[][][][]} layerJets  [layer][λ] = index jet
+     * @param {number[]} thick  layer thicknesses (nm), length N
+     * @param {{omegas?:number[], sinJets?:number[][][]}} [options]
+     * @returns {{r: object, t: object}} each `{phaseRad, gd, gdd, tod,
+     *   magnitudeSquared}` of Float64Array(nLam). Failed samples hold NaN.
+     */
+    tmmPhaseSpectrum(lambdas, n0Jets, nsJets, layerJets, thick, theta_deg, polCode, options = {}) {
+        const nLam = lambdas.length;
+        const N = thick.length;
+        const omegas = options.omegas
+            || lambdas.map(lambda => omegaFromLambdaNm(lambda));
+        const sinJets = options.sinJets || null;
+
+        const lamPtr = this._alloc(nLam);
+        const omPtr = this._alloc(nLam);
+        const n0Ptr = this._alloc(8 * nLam);
+        const nsPtr = this._alloc(8 * nLam);
+        const matPtr = this._alloc(Math.max(1, 8 * N * nLam));
+        const thPtr = this._alloc(Math.max(1, N));
+        const sinPtr = sinJets ? this._alloc(8 * nLam) : 0;
+        const outPtr = this._alloc(10 * nLam);
+
+        // Views created after all mallocs (the buffer may have grown/detached).
+        const lam = this._view(lamPtr, nLam);
+        const om = this._view(omPtr, nLam);
+        const n0v = this._view(n0Ptr, 8 * nLam);
+        const nsv = this._view(nsPtr, 8 * nLam);
+        const matv = this._view(matPtr, Math.max(1, 8 * N * nLam));
+        const thv = this._view(thPtr, Math.max(1, N));
+        const sinv = sinJets ? this._view(sinPtr, 8 * nLam) : null;
+        for (let i = 0; i < nLam; i++) {
+            lam[i] = lambdas[i];
+            om[i] = omegas[i];
+            writeJet(n0v, 8 * i, n0Jets[i]);
+            writeJet(nsv, 8 * i, nsJets[i]);
+            if (sinv) writeJet(sinv, 8 * i, sinJets[i]);
+        }
+        for (let k = 0; k < N; k++) {
+            thv[k] = thick[k];
+            const row = layerJets[k];
+            const base = k * nLam * 8;
+            for (let i = 0; i < nLam; i++) writeJet(matv, base + 8 * i, row[i]);
+        }
+
+        this._tmm_phase_spectrum(lamPtr, omPtr, nLam, n0Ptr, nsPtr, matPtr, thPtr, N,
+            theta_deg, polCode | 0, sinPtr, outPtr);
+
+        // De-interleave into one array per quantity before freeing.
+        const out = this._view(outPtr, 10 * nLam);
+        const side = (base) => {
+            const q = {
+                phaseRad: new Float64Array(nLam), gd: new Float64Array(nLam),
+                gdd: new Float64Array(nLam), tod: new Float64Array(nLam),
+                magnitudeSquared: new Float64Array(nLam),
+            };
+            const keys = ['phaseRad', 'gd', 'gdd', 'tod', 'magnitudeSquared'];
+            for (let i = 0; i < nLam; i++) {
+                for (let j = 0; j < 5; j++) q[keys[j]][i] = out[10 * i + base + j];
+            }
+            return q;
+        };
+        const result = { r: side(0), t: side(5) };
+        for (const p of [lamPtr, omPtr, n0Ptr, nsPtr, matPtr, thPtr, outPtr]) this.free(p);
+        if (sinPtr) this.free(sinPtr);
+        return result;
+    }
+
+    /**
+     * Phase dispersion plus exact thickness derivatives : mirrors
+     * tmmPhaseThicknessJacobian(). Layers used AS-IS (index parity).
+     *
+     * @returns {{r, t}} each the phase quantities plus `dPhaseDeg`, `dGd`,
+     *   `dGdd`, `dTod` as Float64Array(N), or `null` arrays on overflow.
+     */
+    tmmPhaseJacobian(lambda_nm, theta_deg, polCode, n0Jet, nsJet, layers, options = {}) {
+        const N = layers.length;
+        const M = Math.max(1, N);
+        const omega = options.omega ?? omegaFromLambdaNm(lambda_nm);
+        const sinJet = options.sinTheta0Jet || null;
+        // arena: layerJets[8N] | thick[N] | n0[8] | ns[8] | sin[8] | out[10] | deriv[8M]
+        const oLay = 0, oThick = 8 * N, oN0 = oThick + N, oNs = oN0 + 8,
+              oSin = oNs + 8, oOut = oSin + 8, oDeriv = oOut + 10;
+        const need = oDeriv + 8 * M;
+        const ptr = this._scratch(need);
+        const buf = this._view(ptr, need);
+        for (let i = 0; i < N; i++) {
+            writeJet(buf, oLay + 8 * i, layers[i].nJet);
+            buf[oThick + i] = layers[i].d;
+        }
+        writeJet(buf, oN0, n0Jet);
+        writeJet(buf, oNs, nsJet);
+        if (sinJet) writeJet(buf, oSin, sinJet);
+        const P = (off) => ptr + off * 8;
+        this._tmm_phase_jacobian(lambda_nm, omega, theta_deg, polCode | 0,
+            P(oN0), P(oNs), P(oLay), P(oThick), N, sinJet ? P(oSin) : 0,
+            P(oOut), P(oDeriv));
+        const out = this._view(ptr, need);
+        const side = (phaseBase, derivBase) => {
+            const base = readPhase(out, phaseBase);
+            if (!base) return null;
+            // The kernel fills the whole block with NaN when the matrix product
+            // overflowed and the prefix/suffix decomposition had to be abandoned.
+            const overflowed = N > 0 && Number.isNaN(out[oDeriv + derivBase * N]);
+            const take = (q) => overflowed
+                ? null
+                : out.slice(oDeriv + (derivBase + q) * N, oDeriv + (derivBase + q) * N + N);
+            return {
+                ...base,
+                dPhaseDeg: take(0), dGd: take(1), dGdd: take(2), dTod: take(3),
+            };
+        };
+        return { r: side(oOut, 0), t: side(oOut + 5, 4) };
+    }
+
     /**
-     * Analytic needle P-function scan — mirrors tmmNeedleScan() in
+     * Analytic needle P-function scan : mirrors tmmNeedleScan() in
      * thinFilmMath.js, reshaping the flat WASM output into the SAME nested
      * structure the synthesis scanners consume.
      * @param {{n:[number,number],d:number}[]} layers   used AS-IS (index parity)
@@ -332,7 +526,7 @@ export function initTmmWasmFromUrl(url) {
             await instantiateTmmWasm(buf);
             return true;
         } catch (e) {
-            // Not built yet / not found — silent fallback to JS.
+            // Not built yet / not found : silent fallback to JS.
             _instance = null;
             return false;
         }
@@ -371,7 +565,7 @@ export async function initTmmWasmMainThread(bytes, enabled) {
     return true;
 }
 
-/** MAIN THREAD: bytes to ship to a worker — only when the feature is active. */
+/** MAIN THREAD: bytes to ship to a worker : only when the feature is active. */
 export function getTmmWasmBytesForWorker() {
     return (_enabled && _workerBytes) ? _workerBytes : null;
 }