tmmcore 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmmcore",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Transfer-matrix method for multilayer thin-film optics, with exact analytic derivatives and phase dispersion. JavaScript, C and WebAssembly.",
   "type": "module",
   "main": "./src/index.js",
@@ -20,10 +20,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node tests/equivalence.mjs",
+    "test": "node tests/equivalence.mjs && node tests/growing_equivalence.mjs && node tests/growing_eval_equivalence.mjs",
     "compare": "node benchmarks/compare.mjs",
     "examples": "node examples/01-single-layer.mjs && node examples/02-ar-coating.mjs && node examples/03-metal-mirror.mjs && node examples/04-refine.mjs && node examples/05-angle-map.mjs && node examples/06-needle.mjs && node examples/07-jacobian-map.mjs && node examples/08-group-delay.mjs",
-    "build:wasm": "emcc src/tmm_kernel.c -O3 --no-entry -sSTANDALONE_WASM=1 -sALLOW_MEMORY_GROWTH=1 -sEXPORTED_FUNCTIONS=_tmm_one,_tmm_spectrum,_tmm_jacobian,_tmm_needle_scan,_tmm_hessian,_tmm_phase_one,_tmm_phase_spectrum,_tmm_phase_jacobian,_malloc,_free -o src/tmm_kernel.wasm",
+    "build:wasm": "emcc src/tmm_kernel.c -O3 --no-entry -sSTANDALONE_WASM=1 -sALLOW_MEMORY_GROWTH=1 -sEXPORTED_FUNCTIONS=_tmm_one,_tmm_spectrum,_tmm_jacobian,_tmm_needle_scan,_tmm_hessian,_tmm_phase_one,_tmm_phase_spectrum,_tmm_phase_jacobian,_tmm_monitor_curve,_tmm_deposition_spectra,_tmm_growing_eval_create,_tmm_growing_eval_set_top,_tmm_growing_eval_sample,_tmm_growing_eval_free,_malloc,_free -o src/tmm_kernel.wasm",
     "build:native": "cc -std=c99 -pedantic -Wall -Wextra -O2 -c src/tmm_kernel.c -o tmm_kernel.o"
   },
   "keywords": [

package/src/build.ps1

@@ -111,7 +111,7 @@ $emccArgs = @(
   '--no-entry'
   '-sSTANDALONE_WASM=1'
   '-sALLOW_MEMORY_GROWTH=1'
-  '-sEXPORTED_FUNCTIONS=_tmm_one,_tmm_spectrum,_tmm_jacobian,_tmm_needle_scan,_tmm_hessian,_tmm_phase_one,_tmm_phase_spectrum,_tmm_phase_jacobian,_malloc,_free'
+  '-sEXPORTED_FUNCTIONS=_tmm_one,_tmm_spectrum,_tmm_jacobian,_tmm_needle_scan,_tmm_hessian,_tmm_phase_one,_tmm_phase_spectrum,_tmm_phase_jacobian,_tmm_monitor_curve,_tmm_deposition_spectra,_tmm_growing_eval_create,_tmm_growing_eval_set_top,_tmm_growing_eval_sample,_tmm_growing_eval_free,_malloc,_free'
   '-o'
   'src/tmm_kernel.wasm'
 )
@@ -121,3 +121,7 @@ if ($LASTEXITCODE -ne 0) { Write-Error "emcc failed with exit code $LASTEXITCODE
 Write-Host "Built src/tmm_kernel.wasm"
 node tests/equivalence.mjs
 if ($LASTEXITCODE -ne 0) { Write-Error "equivalence tests failed with exit code $LASTEXITCODE."; exit 1 }
+node tests/growing_equivalence.mjs
+if ($LASTEXITCODE -ne 0) { Write-Error "growing_equivalence tests failed with exit code $LASTEXITCODE."; exit 1 }
+node tests/growing_eval_equivalence.mjs
+if ($LASTEXITCODE -ne 0) { Write-Error "growing_eval_equivalence tests failed with exit code $LASTEXITCODE."; exit 1 }

package/src/tmmWasm.js

@@ -59,6 +59,15 @@ function wasmImports() {
     };
 }
 
+// Backstop for growing-evaluator handles that are dropped without free():
+// reclaims their kernel memory when the JS handle is collected. Deterministic
+// free() remains the contract; this only keeps a leak from being permanent.
+const growingEvalFinalizer = typeof FinalizationRegistry !== 'undefined'
+    ? new FinalizationRegistry(({ wasm, ptr }) => {
+        try { wasm._growing_eval_free(ptr); } catch (_) { /* instance gone */ }
+    })
+    : null;
+
 export class TmmWasmInstance {
     constructor(instance) {
         const ex = instance.exports;
@@ -82,6 +91,16 @@ export class TmmWasmInstance {
         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;
+        // Optional, same reason: the growing-stack kernels (monitor curve and
+        // per-step deposition spectra) arrived after all of the above.
+        this._tmm_monitor_curve = ex.tmm_monitor_curve || ex._tmm_monitor_curve || null;
+        this._tmm_deposition_spectra = ex.tmm_deposition_spectra || ex._tmm_deposition_spectra || null;
+        // Optional, same reason: the persistent growing-layer evaluator
+        // (wavelength-grid-per-call) arrived after the two kernels above.
+        this._growing_eval_create = ex.tmm_growing_eval_create || ex._tmm_growing_eval_create || null;
+        this._growing_eval_set_top = ex.tmm_growing_eval_set_top || ex._tmm_growing_eval_set_top || null;
+        this._growing_eval_sample = ex.tmm_growing_eval_sample || ex._tmm_growing_eval_sample || null;
+        this._growing_eval_free = ex.tmm_growing_eval_free || ex._tmm_growing_eval_free || null;
         const missingExports = !this.malloc || !this.free || !this._tmm_one ||
             !this._tmm_spectrum || !this._tmm_jacobian || !this._tmm_needle_scan;
         if (missingExports) {
@@ -192,6 +211,234 @@ export class TmmWasmInstance {
         return res;
     }
 
+    /** True if the loaded module carries the growing-stack kernels. */
+    hasGrowingKernels() {
+        return !!(this._tmm_monitor_curve && this._tmm_deposition_spectra);
+    }
+
+    /** True if the loaded module carries the persistent growing-layer evaluator. */
+    hasGrowingEval() {
+        return !!(this._growing_eval_create && this._growing_eval_set_top
+            && this._growing_eval_sample && this._growing_eval_free);
+    }
+
+    /**
+     * Monitor curve of one growing layer at one wavelength: the completed
+     * stack's matrix is built once, then every sample thickness costs one 2×2
+     * multiply. Returns the forward and substrate-side passes of the coated
+     * surface, both polarizations; the caller does the incoherent slab
+     * combination (or forms A = 1−R−T for a semi-infinite substrate).
+     * @param {[number,number]} n0   incident ñ
+     * @param {[number,number]} ns   substrate ñ
+     * @param {{n:[number,number],d:number}[]} baseLayers  completed stack,
+     *        outermost first
+     * @param {[number,number]} ngNK growing layer ñ
+     * @param {ArrayLike<number>} dArr  sample thicknesses (nm)
+     * @returns {{Rs,Ts,Rp,Tp,Rrs,Rrp}} each a Float64Array(dArr.length)
+     */
+    monitorCurve(lambda_nm, theta_deg, n0, ns, baseLayers, ngNK, dArr) {
+        const NB = baseLayers.length;
+        const nD = dArr.length;
+        // arena: base[3NB] | d[nD] | Rs,Ts,Rp,Tp,Rrs,Rrp [6·nD]
+        const oBase = 0, oD = 3 * NB, oOut = oD + nD;
+        const need = oOut + 6 * nD;
+        const ptr = this._scratch(need);
+        const buf = this._view(ptr, need);
+        for (let i = 0; i < NB; i++) {
+            buf[3 * i + 0] = baseLayers[i].n[0];
+            buf[3 * i + 1] = baseLayers[i].n[1];
+            buf[3 * i + 2] = baseLayers[i].d;
+        }
+        for (let k = 0; k < nD; k++) buf[oD + k] = dArr[k];
+        const P = (off) => ptr + off * 8;
+        this._tmm_monitor_curve(lambda_nm, theta_deg,
+            n0[0], n0[1], ns[0], ns[1], P(oBase), NB, ngNK[0], ngNK[1],
+            P(oD), nD,
+            P(oOut), P(oOut + nD), P(oOut + 2 * nD), P(oOut + 3 * nD),
+            P(oOut + 4 * nD), P(oOut + 5 * nD));
+        // Fresh view after the call: memory growth detaches the old buffer.
+        const out = this._view(ptr, need);
+        return {
+            Rs:  out.slice(oOut, oOut + nD),
+            Ts:  out.slice(oOut + nD, oOut + 2 * nD),
+            Rp:  out.slice(oOut + 2 * nD, oOut + 3 * nD),
+            Tp:  out.slice(oOut + 3 * nD, oOut + 4 * nD),
+            Rrs: out.slice(oOut + 4 * nD, oOut + 5 * nD),
+            Rrp: out.slice(oOut + 5 * nD, oOut + 6 * nD),
+        };
+    }
+
+    /**
+     * Per-step spectra of a growing stack: one call returns the forward and
+     * substrate-side passes of the coated surface after every deposited layer,
+     * so all N step spectra cost about what the final one costs alone. Layers
+     * in DEPOSITION order (first deposited first).
+     * @param {number[]} lambdas
+     * @param {[number,number][]} n0List  incident ñ per λ
+     * @param {[number,number][]} nsList  substrate ñ per λ
+     * @param {[number,number][][]} layerNK  [layer][λ] = ñ, deposition order
+     * @param {number[]} thick   thicknesses (nm); 0 repeats the previous step
+     * @param {number}   theta_deg
+     * @returns {{Rs,Ts,Rp,Tp,Rrs,Rrp}} each a Float64Array(N · nLam),
+     *          step-major: value for step k at wavelength i is at [k·nLam + i]
+     */
+    depositionSpectra(lambdas, n0List, nsList, layerNK, thick, theta_deg) {
+        const nLam = lambdas.length;
+        const N = thick.length;
+        const nOut = Math.max(1, N * nLam);
+
+        const lamPtr = this._alloc(nLam);
+        const n0Ptr  = this._alloc(2 * nLam);
+        const nsPtr  = this._alloc(2 * nLam);
+        const mPtr   = this._alloc(Math.max(1, 2 * N * nLam));
+        const thPtr  = this._alloc(Math.max(1, N));
+        const outPtrs = Array.from({ length: 6 }, () => this._alloc(nOut));
+
+        const lam = this._view(lamPtr, nLam);
+        const n0v = this._view(n0Ptr, 2 * nLam);
+        const nsv = this._view(nsPtr, 2 * nLam);
+        const mv  = this._view(mPtr, Math.max(1, 2 * N * nLam));
+        const thv = this._view(thPtr, Math.max(1, N));
+        for (let i = 0; i < nLam; i++) {
+            lam[i] = lambdas[i];
+            n0v[2 * i] = n0List[i][0]; n0v[2 * i + 1] = n0List[i][1];
+            nsv[2 * i] = nsList[i][0]; nsv[2 * i + 1] = nsList[i][1];
+        }
+        for (let k = 0; k < N; k++) {
+            thv[k] = thick[k];
+            const row = layerNK[k];
+            const base = k * nLam * 2;
+            for (let i = 0; i < nLam; i++) {
+                mv[base + 2 * i]     = row[i][0];
+                mv[base + 2 * i + 1] = row[i][1];
+            }
+        }
+
+        const ok = this._tmm_deposition_spectra(lamPtr, nLam, n0Ptr, nsPtr, mPtr, thPtr, N,
+            theta_deg, ...outPtrs);
+        if (!ok) {
+            for (const p of [lamPtr, n0Ptr, nsPtr, mPtr, thPtr, ...outPtrs]) this.free(p);
+            // The outputs were never written; returning them would hand the
+            // caller uninitialized memory as spectra.
+            throw new Error('tmmWasm: deposition-spectra state allocation failed');
+        }
+
+        const cp = (p) => Float64Array.from(this._view(p, nOut));
+        const [Rs, Ts, Rp, Tp, Rrs, Rrp] = outPtrs.map(cp);
+        for (const p of [lamPtr, n0Ptr, nsPtr, mPtr, thPtr, ...outPtrs]) this.free(p);
+        return { Rs, Ts, Rp, Tp, Rrs, Rrp };
+    }
+
+    /**
+     * Persistent growing-layer evaluator: the completed stack's products for
+     * the whole wavelength grid are folded once and kept in kernel memory;
+     * each sample() then answers one thickness of the growing layer across
+     * the grid. This is the shape a broadband monitor scan needs (a spectrum
+     * per scan while the layers beneath stay fixed), where monitorCurve is
+     * the single-λ, many-thicknesses shape.
+     *
+     * The completed stack arrives OUTERMOST FIRST, layer-major like
+     * depositionSpectra's matNK; zero-thickness entries are skipped.
+     *
+     * The returned handle owns kernel memory: call free() when the layer is
+     * done. A dropped handle is reclaimed by a finalizer eventually, but
+     * deterministic free() is what keeps a long run's footprint flat.
+     *
+     * @param {number[]} lambdas
+     * @param {[number,number][]} n0List  incident ñ per λ
+     * @param {[number,number][]} nsList  substrate ñ per λ
+     * @param {[number,number][][]} layerNK  [layer][λ] = ñ, outermost first
+     * @param {number[]} thick   completed thicknesses (nm)
+     * @param {number}   theta_deg
+     * @returns {{setTop, sample, free}} setTop(ngList) declares the growing
+     *          layer's ñ per λ; sample(d, out?) returns {Rs,Ts,Rp,Tp,Rrs,Rrp}
+     *          (each Float64Array(nLam), written into `out` when given, so a
+     *          scan loop can reuse one set of buffers).
+     */
+    growingEval(lambdas, n0List, nsList, layerNK, thick, theta_deg) {
+        if (!this.hasGrowingEval()) throw new Error('tmmWasm: growing evaluator kernel not in this build');
+        const nLam = lambdas.length;
+        const NB = thick.length;
+
+        const lamPtr = this._alloc(nLam);
+        const n0Ptr  = this._alloc(2 * nLam);
+        const nsPtr  = this._alloc(2 * nLam);
+        const mPtr   = this._alloc(Math.max(1, 2 * NB * nLam));
+        const thPtr  = this._alloc(Math.max(1, NB));
+        const lam = this._view(lamPtr, nLam);
+        const n0v = this._view(n0Ptr, 2 * nLam);
+        const nsv = this._view(nsPtr, 2 * nLam);
+        const mv  = this._view(mPtr, Math.max(1, 2 * NB * nLam));
+        const thv = this._view(thPtr, Math.max(1, NB));
+        for (let i = 0; i < nLam; i++) {
+            lam[i] = lambdas[i];
+            n0v[2 * i] = n0List[i][0]; n0v[2 * i + 1] = n0List[i][1];
+            nsv[2 * i] = nsList[i][0]; nsv[2 * i + 1] = nsList[i][1];
+        }
+        for (let k = 0; k < NB; k++) {
+            thv[k] = thick[k];
+            const row = layerNK[k];
+            const base = k * nLam * 2;
+            for (let i = 0; i < nLam; i++) {
+                mv[base + 2 * i]     = row[i][0];
+                mv[base + 2 * i + 1] = row[i][1];
+            }
+        }
+        const handlePtr = this._growing_eval_create(lamPtr, nLam, theta_deg,
+            n0Ptr, nsPtr, mPtr, thPtr, NB);
+        for (const p of [lamPtr, n0Ptr, nsPtr, mPtr, thPtr]) this.free(p);
+        if (!handlePtr) throw new Error('tmmWasm: growing evaluator allocation failed');
+
+        const self = this;
+        const handle = {
+            ptr: handlePtr,
+            setTop(ngList) {
+                if (!this.ptr) throw new Error('tmmWasm: growing evaluator already freed');
+                const p = self._scratch(2 * nLam);
+                const buf = self._view(p, 2 * nLam);
+                for (let i = 0; i < nLam; i++) {
+                    buf[2 * i] = ngList[i][0]; buf[2 * i + 1] = ngList[i][1];
+                }
+                self._growing_eval_set_top(this.ptr, p);
+            },
+            sample(d, out = null) {
+                if (!this.ptr) throw new Error('tmmWasm: growing evaluator already freed');
+                const p = self._scratch(6 * nLam);
+                const P = (block) => p + block * nLam * 8;
+                const ok = self._growing_eval_sample(this.ptr, d,
+                    P(0), P(1), P(2), P(3), P(4), P(5));
+                // The kernel writes nothing without a declared growing layer;
+                // copying the arena anyway would hand back stale memory.
+                if (!ok) throw new Error('tmmWasm: growing evaluator sampled before setTop');
+                // Fresh view AFTER the call (memory may have grown → detach).
+                const buf = self._view(p, 6 * nLam);
+                if (!out) {
+                    out = {
+                        Rs: new Float64Array(nLam), Ts: new Float64Array(nLam),
+                        Rp: new Float64Array(nLam), Tp: new Float64Array(nLam),
+                        Rrs: new Float64Array(nLam), Rrp: new Float64Array(nLam),
+                    };
+                }
+                out.Rs.set(buf.subarray(0, nLam));
+                out.Ts.set(buf.subarray(nLam, 2 * nLam));
+                out.Rp.set(buf.subarray(2 * nLam, 3 * nLam));
+                out.Tp.set(buf.subarray(3 * nLam, 4 * nLam));
+                out.Rrs.set(buf.subarray(4 * nLam, 5 * nLam));
+                out.Rrp.set(buf.subarray(5 * nLam, 6 * nLam));
+                return out;
+            },
+            free() {
+                if (!this.ptr) return;
+                growingEvalFinalizer?.unregister(this);
+                self._growing_eval_free(this.ptr);
+                this.ptr = 0;
+            },
+        };
+        growingEvalFinalizer?.register(handle,
+            { wasm: this, ptr: handlePtr }, handle);
+        return handle;
+    }
+
     /**
      * Analytic thickness Jacobian for one (λ, θ, pol) : mirrors
      * tmmThicknessJacobian(). layers used AS-IS (index parity).

package/src/tmm_kernel.c

@@ -245,6 +245,336 @@ void tmm_spectrum(const double *lambdas, int nLam,
     if (layers) free(layers);
 }
 
+/* ── Shared tails for the growing-stack kernels ──────────────────────────────
+ * Forward tail: reproduces the [B,C] → r,t → R,T block of tmm_core on an
+ * already-built characteristic matrix. A is not formed here; the incoherent
+ * slab combination that consumes these results computes it after the sum, and
+ * a semi-infinite caller forms 1−R−T itself.
+ *
+ * Reverse tail: reflectance of the same stack seen from the substrate side.
+ * The characteristic matrix of the reversed stack is the anti-transpose of the
+ * forward one (every layer matrix is invariant under anti-transposition), so
+ * the reverse pass costs no second product, and the common rescale factor
+ * cancels in the amplitude ratio. */
+
+static inline void growingTailFwd(mat2 M, cx eta0, cx etaS, double logScale,
+                                  double *outR, double *outT) {
+    cx B = cadd(M.a, cmul(M.b, etaS));
+    cx C = cadd(M.c, cmul(M.d, etaS));
+    cx eta0B = cmul(eta0, B);
+    cx r = cdiv(csub(eta0B, C), cadd(eta0B, C));
+    cx t = cdiv(cmul(cmk(2.0, 0.0), eta0), cadd(eta0B, C));
+    double R = cabs2(r);
+    double T = etaS.re / eta0.re * cabs2(t) * exp(-2.0 * logScale);
+    if (T < 0.0) T = 0.0;
+    *outR = R; *outT = T;
+}
+
+static inline double growingTailRev(mat2 M, cx eta0, cx etaS) {
+    cx B = cadd(M.d, cmul(M.b, eta0));
+    cx C = cadd(M.c, cmul(M.a, eta0));
+    cx etaSB = cmul(etaS, B);
+    cx r = cdiv(csub(etaSB, C), cadd(etaSB, C));
+    return cabs2(r);
+}
+
+/* ── Exported: monitor curve of one growing layer ────────────────────────────
+ * The signal of one layer as it grows on a completed stack, at one wavelength,
+ * both polarizations: the incremental control algorithm of Tikhonravov &
+ * Trubetskov, Appl. Opt. 44, 6877 (2005). The completed stack's characteristic
+ * matrix is built once; each sample then costs one layer matrix, one 2×2
+ * multiply and the tails, so a sweep is linear in samples rather than in
+ * samples × stack depth.
+ *
+ * The growing layer faces the incident medium, so its matrix multiplies the
+ * completed product from the LEFT, exactly as createMonitorTmmEvaluator in the
+ * JS reference.
+ *
+ *   base  : NB triples [n_re, n_im, d_nm], the completed stack outermost first
+ *           (zero-thickness entries skipped, as everywhere)
+ *   ng    : growing layer ñ at this wavelength
+ *   dArr  : nD sample thicknesses of the growing layer (nm); d ≤ 0 evaluates
+ *           the bare completed stack
+ * Outputs (each nD):
+ *   outRs/outTs, outRp/outTp : forward R and T of the coated surface
+ *   outRrs/outRrp            : its reflectance from the substrate side, for
+ *                              callers that model the witness as an incoherent
+ *                              slab with a bare back face */
+
+TMM_EXPORT("tmm_monitor_curve")
+void tmm_monitor_curve(double lambda_nm, double theta_deg,
+                       double n0_re, double n0_im, double ns_re, double ns_im,
+                       const double *base, int NB,
+                       double ng_re, double ng_im,
+                       const double *dArr, int nD,
+                       double *outRs, double *outTs,
+                       double *outRp, double *outTp,
+                       double *outRrs, double *outRrp) {
+    cx n0 = cmk(n0_re, n0_im);
+    cx ns = cmk(ns_re, ns_im);
+    cx ng = cmk(ng_re, ng_im);
+    cx sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
+    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+
+    for (int pol = 0; pol < 2; pol++) {
+        cx eta0 = (pol == 0) ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
+        cx cosThetaS = snellCosTheta(n0, sinTheta0, ns);
+        cx etaS = (pol == 0) ? cmul(ns, cosThetaS) : cdiv(ns, cosThetaS);
+
+        mat2 Mb;
+        Mb.a = cmk(1.0, 0.0); Mb.b = cmk(0.0, 0.0);
+        Mb.c = cmk(0.0, 0.0); Mb.d = cmk(1.0, 0.0);
+        double logScaleB = 0.0;
+        for (int i = 0; i < NB; i++) {
+            cx n = cmk(base[3 * i + 0], base[3 * i + 1]);
+            double d = base[3 * i + 2];
+            if (d <= 0.0) continue;
+            cx cosThetaJ = snellCosTheta(n0, sinTheta0, n);
+            Mb = matmul(Mb, layerMatrix(n, d, lambda_nm, cosThetaJ, pol));
+            logScaleB += rescaleMatrix(&Mb);
+        }
+        cx cosThetaG = snellCosTheta(n0, sinTheta0, ng);
+
+        double *oR  = pol ? outRp  : outRs;
+        double *oT  = pol ? outTp  : outTs;
+        double *oRr = pol ? outRrp : outRrs;
+
+        for (int k = 0; k < nD; k++) {
+            mat2 M = Mb;
+            double logScale = logScaleB;
+            double d = dArr[k];
+            if (d > 0.0) {
+                M = matmul(layerMatrix(ng, d, lambda_nm, cosThetaG, pol), Mb);
+                logScale += rescaleMatrix(&M);
+            }
+            growingTailFwd(M, eta0, etaS, logScale, &oR[k], &oT[k]);
+            oRr[k] = growingTailRev(M, eta0, etaS);
+        }
+    }
+}
+
+/* ── Exported: spectra of a growing stack, one per deposited layer ───────────
+ * The front-surface passes of a deposition run in a single call: layers arrive
+ * in DEPOSITION order (first deposited, substrate-adjacent, first), each is
+ * folded into the running product from the left, since the newest layer faces
+ * the incident medium, and the spectrum after every fold is written out. The
+ * same incremental structure as tmm_monitor_curve over a wavelength grid, so
+ * all N step spectra together cost what the final one costs alone.
+ *
+ * Memory layout mirrors tmm_spectrum:
+ *   matNK : N × nLam × 2, [layer][λ][re, im], deposition order
+ *   thick : N thicknesses (nm); a step of zero thickness repeats the previous
+ *           spectrum, matching the d ≤ 0 skip of the reference loop
+ * Outputs, each N × nLam, step-major ([step][λ]):
+ *   outRs/outTs, outRp/outTp : forward R and T after each step
+ *   outRrs/outRrp            : reflectance from the substrate side after each
+ *                              step, for the incoherent slab combination */
+
+/* Returns 1 on success; 0, with the outputs untouched, when the working
+ * state could not be allocated. */
+TMM_EXPORT("tmm_deposition_spectra")
+int tmm_deposition_spectra(const double *lambdas, int nLam,
+                           const double *n0arr, const double *nsarr,
+                           const double *matNK, const double *thick, int N,
+                           double theta_deg,
+                           double *outRs, double *outTs,
+                           double *outRp, double *outTp,
+                           double *outRrs, double *outRrp) {
+    /* Running product and admittances per (λ, pol); pol-major blocks. */
+    size_t cells = (size_t)nLam * 2;
+    mat2 *M = (mat2 *)malloc(sizeof(mat2) * cells);
+    double *logScale = (double *)malloc(sizeof(double) * cells);
+    cx *eta0v = (cx *)malloc(sizeof(cx) * cells);
+    cx *etaSv = (cx *)malloc(sizeof(cx) * cells);
+    if (!M || !logScale || !eta0v || !etaSv) {
+        free(M); free(logScale); free(eta0v); free(etaSv);
+        return 0;
+    }
+
+    cx sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
+    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+
+    for (int li = 0; li < nLam; li++) {
+        cx n0 = cmk(n0arr[2 * li + 0], n0arr[2 * li + 1]);
+        cx ns = cmk(nsarr[2 * li + 0], nsarr[2 * li + 1]);
+        for (int pol = 0; pol < 2; pol++) {
+            size_t at = (size_t)pol * nLam + li;
+            eta0v[at] = (pol == 0) ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
+            cx cosThetaS = snellCosTheta(n0, sinTheta0, ns);
+            etaSv[at] = (pol == 0) ? cmul(ns, cosThetaS) : cdiv(ns, cosThetaS);
+            M[at].a = cmk(1.0, 0.0); M[at].b = cmk(0.0, 0.0);
+            M[at].c = cmk(0.0, 0.0); M[at].d = cmk(1.0, 0.0);
+            logScale[at] = 0.0;
+        }
+    }
+
+    for (int k = 0; k < N; k++) {
+        double d = thick[k];
+        for (int li = 0; li < nLam; li++) {
+            double lam = lambdas[li];
+            cx n0 = cmk(n0arr[2 * li + 0], n0arr[2 * li + 1]);
+            cx n = cmk(matNK[((size_t)k * nLam + li) * 2 + 0],
+                       matNK[((size_t)k * nLam + li) * 2 + 1]);
+            for (int pol = 0; pol < 2; pol++) {
+                size_t at = (size_t)pol * nLam + li;
+                if (d > 0.0) {
+                    cx cosThetaJ = snellCosTheta(n0, sinTheta0, n);
+                    M[at] = matmul(layerMatrix(n, d, lam, cosThetaJ, pol), M[at]);
+                    logScale[at] += rescaleMatrix(&M[at]);
+                }
+                size_t out = (size_t)k * nLam + li;
+                double *oR  = pol ? outRp  : outRs;
+                double *oT  = pol ? outTp  : outTs;
+                double *oRr = pol ? outRrp : outRrs;
+                growingTailFwd(M[at], eta0v[at], etaSv[at], logScale[at],
+                               &oR[out], &oT[out]);
+                oRr[out] = growingTailRev(M[at], eta0v[at], etaSv[at]);
+            }
+        }
+    }
+
+    free(M); free(logScale); free(eta0v); free(etaSv);
+    return 1;
+}
+
+/* ── Exported: persistent growing-layer evaluator over a wavelength grid ─────
+ * The stateful counterpart of tmm_monitor_curve, batched the other way: one
+ * thickness of the growing layer per call, the WHOLE wavelength grid at once.
+ * This is the shape a broadband monitor scan needs, where every scan reads a
+ * full spectrum of the growing stack and the completed layers beneath do not
+ * change until the layer is cut.
+ *
+ * Lifecycle: create() folds the completed stack's characteristic matrices for
+ * every (λ, pol) once and keeps them; set_top() declares the growing layer's
+ * ñ(λ); sample() then answers one thickness across the grid, costing one layer
+ * matrix, one 2×2 multiply and the tails per (λ, pol). free() releases the
+ * state. Handles are opaque pointers; the caller owns their lifetime.
+ *
+ * Layout matches tmm_deposition_spectra: matNK is NB × nLam × 2 layer-major
+ * with the completed stack OUTERMOST FIRST (the fold is M = M · M_k, exactly
+ * the JS reference createMonitorTmmEvaluator); zero-thickness entries are
+ * skipped. Outputs of sample(), each nLam: forward R and T plus the
+ * substrate-side reflectance, for the incoherent slab combination. */
+
+typedef struct {
+    int nLam;
+    cx sinTheta0;
+    int topSet;
+    double *lam;        /* nLam */
+    cx *n0;             /* nLam */
+    cx *ng;             /* nLam, set_top */
+    cx *cosThetaG;      /* nLam, set_top (polarization-independent) */
+    cx *eta0;           /* 2·nLam, pol-major */
+    cx *etaS;           /* 2·nLam */
+    mat2 *Mb;           /* 2·nLam completed-stack product */
+    double *logScaleB;  /* 2·nLam */
+} growing_eval;
+
+TMM_EXPORT("tmm_growing_eval_free")
+void tmm_growing_eval_free(growing_eval *h) {
+    if (!h) return;
+    free(h->lam); free(h->n0); free(h->ng); free(h->cosThetaG);
+    free(h->eta0); free(h->etaS); free(h->Mb); free(h->logScaleB);
+    free(h);
+}
+
+TMM_EXPORT("tmm_growing_eval_create")
+growing_eval *tmm_growing_eval_create(const double *lambdas, int nLam,
+                                      double theta_deg,
+                                      const double *n0arr, const double *nsarr,
+                                      const double *matNK, const double *thick,
+                                      int NB) {
+    growing_eval *h = (growing_eval *)malloc(sizeof(growing_eval));
+    if (!h) return 0;
+    h->nLam = nLam;
+    h->topSet = 0;
+    h->lam = (double *)malloc(sizeof(double) * nLam);
+    h->n0 = (cx *)malloc(sizeof(cx) * nLam);
+    h->ng = (cx *)malloc(sizeof(cx) * nLam);
+    h->cosThetaG = (cx *)malloc(sizeof(cx) * nLam);
+    h->eta0 = (cx *)malloc(sizeof(cx) * 2 * nLam);
+    h->etaS = (cx *)malloc(sizeof(cx) * 2 * nLam);
+    h->Mb = (mat2 *)malloc(sizeof(mat2) * 2 * nLam);
+    h->logScaleB = (double *)malloc(sizeof(double) * 2 * nLam);
+    if (!h->lam || !h->n0 || !h->ng || !h->cosThetaG
+        || !h->eta0 || !h->etaS || !h->Mb || !h->logScaleB) {
+        tmm_growing_eval_free(h);
+        return 0;
+    }
+
+    h->sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
+    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(h->sinTheta0, h->sinTheta0)));
+
+    for (int li = 0; li < nLam; li++) {
+        h->lam[li] = lambdas[li];
+        cx n0 = cmk(n0arr[2 * li + 0], n0arr[2 * li + 1]);
+        cx ns = cmk(nsarr[2 * li + 0], nsarr[2 * li + 1]);
+        h->n0[li] = n0;
+        for (int pol = 0; pol < 2; pol++) {
+            size_t at = (size_t)pol * nLam + li;
+            h->eta0[at] = (pol == 0) ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
+            cx cosThetaS = snellCosTheta(n0, h->sinTheta0, ns);
+            h->etaS[at] = (pol == 0) ? cmul(ns, cosThetaS) : cdiv(ns, cosThetaS);
+            mat2 M;
+            M.a = cmk(1.0, 0.0); M.b = cmk(0.0, 0.0);
+            M.c = cmk(0.0, 0.0); M.d = cmk(1.0, 0.0);
+            double logScale = 0.0;
+            for (int k = 0; k < NB; k++) {
+                double d = thick[k];
+                if (d <= 0.0) continue;
+                cx n = cmk(matNK[((size_t)k * nLam + li) * 2 + 0],
+                           matNK[((size_t)k * nLam + li) * 2 + 1]);
+                cx cosThetaJ = snellCosTheta(n0, h->sinTheta0, n);
+                M = matmul(M, layerMatrix(n, d, lambdas[li], cosThetaJ, pol));
+                logScale += rescaleMatrix(&M);
+            }
+            h->Mb[at] = M;
+            h->logScaleB[at] = logScale;
+        }
+    }
+    return h;
+}
+
+TMM_EXPORT("tmm_growing_eval_set_top")
+void tmm_growing_eval_set_top(growing_eval *h, const double *ngNK) {
+    if (!h) return;
+    for (int li = 0; li < h->nLam; li++) {
+        cx ng = cmk(ngNK[2 * li + 0], ngNK[2 * li + 1]);
+        h->ng[li] = ng;
+        h->cosThetaG[li] = snellCosTheta(h->n0[li], h->sinTheta0, ng);
+    }
+    h->topSet = 1;
+}
+
+/* Returns 1 on success; 0, with the outputs untouched, for a null handle or
+ * a d > 0 sample before set_top declared the growing layer. The status is
+ * what keeps an unwritten buffer from being read back as data. */
+TMM_EXPORT("tmm_growing_eval_sample")
+int tmm_growing_eval_sample(growing_eval *h, double d,
+                            double *outRs, double *outTs,
+                            double *outRp, double *outTp,
+                            double *outRrs, double *outRrp) {
+    if (!h || (d > 0.0 && !h->topSet)) return 0;
+    for (int li = 0; li < h->nLam; li++) {
+        for (int pol = 0; pol < 2; pol++) {
+            size_t at = (size_t)pol * h->nLam + li;
+            mat2 M = h->Mb[at];
+            double logScale = h->logScaleB[at];
+            if (d > 0.0) {
+                M = matmul(layerMatrix(h->ng[li], d, h->lam[li], h->cosThetaG[li], pol),
+                           h->Mb[at]);
+                logScale += rescaleMatrix(&M);
+            }
+            double *oR  = pol ? outRp  : outRs;
+            double *oT  = pol ? outTp  : outTs;
+            double *oRr = pol ? outRrp : outRrs;
+            growingTailFwd(M, h->eta0[at], h->etaS[at], logScale, &oR[li], &oT[li]);
+            oRr[li] = growingTailRev(M, h->eta0[at], h->etaS[at]);
+        }
+    }
+    return 1;
+}
+
 /* ── Exported: analytic thickness Jacobian for one (λ, θ, pol) ────────────────
  * Faithful port of tmmThicknessJacobian() in thinFilmMath.js. Returns the exact
  * analytic dR/dd_k, dT/dd_k, dA/dd_k for every layer at one sample : the DLS