tmmcore 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmmcore",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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,7 +20,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node tests/equivalence.mjs && node tests/growing_equivalence.mjs && node tests/growing_eval_equivalence.mjs",
+    "test": "node tests/equivalence.mjs && node tests/growing_equivalence.mjs && node tests/growing_eval_equivalence.mjs && node tests/absorbing_incident.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,_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",

package/src/index.js

@@ -29,7 +29,7 @@ export {
     tmmNeedleScan,
     // Low-level primitives, for building variants on the same conventions
     cadd, csub, cmul, cdiv, cabs2, cconj, csqrt, ccos, csin, creal, cimag,
-    matmul, rescaleMatrix, snellCosTheta, layerMatrix, cmatvec,
+    matmul, rescaleMatrix, snellCosTheta, incidentCosTheta, layerMatrix, cmatvec,
 } from './tmm.js';
 
 export {

package/src/phase.js

@@ -46,6 +46,7 @@ import {
     jetDerivatives,
     jetDivide,
     jetMultiply,
+    jetRealPart,
     jetScale,
     jetSinCos,
     jetSqrt,
@@ -124,11 +125,25 @@ function rescaleMatrix(matrix, threshold) {
     return Math.log(scale);
 }
 
+// The transverse invariant is Re(n0) sinθ0, as in tmm.js: an absorbing incident
+// medium carries a wave whose amplitude falls along the normal only.
 function snellCosine(incidentIndex, incidentSine, layerIndex) {
-    const layerSine = jetDivide(jetMultiply(incidentIndex, incidentSine), layerIndex);
+    const layerSine = jetDivide(jetMultiply(jetRealPart(incidentIndex), incidentSine), layerIndex);
     return jetSqrt(jetSubtract(jetConstant(1), jetMultiply(layerSine, layerSine)));
 }
 
+// cosθ0 of the incident medium: the plain cosine while the index is real at
+// every order, otherwise from the same real invariant as the layers, so the
+// incident admittance is sqrt(N0² − n0² sin²θ0) and matches tmm.js.
+function incidentCosine(incidentIndex, incidentSine, incidentSineJet, thetaDeg) {
+    if (incidentIndex.some(coefficient => coefficient[1] !== 0)) {
+        return snellCosine(incidentIndex, incidentSine, incidentIndex);
+    }
+    return incidentSineJet
+        ? jetSqrt(jetSubtract(jetConstant(1), jetMultiply(incidentSine, incidentSine)))
+        : jetConstant(Math.cos(thetaDeg * Math.PI / 180));
+}
+
 function admittance(index, cosine, polarization) {
     return polarization === 's'
         ? jetMultiply(index, cosine)
@@ -249,10 +264,8 @@ export function tmmCoefficientJets({
     layers,
 }) {
     const incidentSine = incidentSineJet || jetConstant(Math.sin(thetaDeg * Math.PI / 180));
-    const incidentCosine = incidentSineJet
-        ? jetSqrt(jetSubtract(jetConstant(1), jetMultiply(incidentSine, incidentSine)))
-        : jetConstant(Math.cos(thetaDeg * Math.PI / 180));
-    const incidentEta = admittance(incidentIndexJet, incidentCosine, polarization);
+    const incidentEta = admittance(incidentIndexJet,
+        incidentCosine(incidentIndexJet, incidentSine, incidentSineJet, thetaDeg), polarization);
     const substrateCosine = snellCosine(incidentIndexJet, incidentSine, substrateIndexJet);
     const substrateEta = admittance(substrateIndexJet, substrateCosine, polarization);
 
@@ -301,10 +314,8 @@ export function tmmCoefficientThicknessJets(options) {
         layers,
     } = options;
     const incidentSine = incidentSineJet || jetConstant(Math.sin(thetaDeg * Math.PI / 180));
-    const incidentCosine = incidentSineJet
-        ? jetSqrt(jetSubtract(jetConstant(1), jetMultiply(incidentSine, incidentSine)))
-        : jetConstant(Math.cos(thetaDeg * Math.PI / 180));
-    const incidentEta = admittance(incidentIndexJet, incidentCosine, polarization);
+    const incidentEta = admittance(incidentIndexJet,
+        incidentCosine(incidentIndexJet, incidentSine, incidentSineJet, thetaDeg), polarization);
     const substrateCosine = snellCosine(incidentIndexJet, incidentSine, substrateIndexJet);
     const substrateEta = admittance(substrateIndexJet, substrateCosine, polarization);
     const layerData = layers.map((layer) => {

package/src/taylorJet.js

@@ -233,6 +233,11 @@ export function jetWithImaginaryPart(realJet, imaginaryJet) {
     return realJet.map((coefficient, index) => [coefficient[0], imaginaryJet[index][0]]);
 }
 
+/** The real part of a complex jet, order by order. */
+export function jetRealPart(jet) {
+    return jet.map(coefficient => [coefficient[0], 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);

package/src/tmm.js

@@ -20,7 +20,9 @@
  * it to float64 round-off (see tests/).
  *
  * References:
- *   • Macleod, Thin-Film Optical Filters 5th ed., §2.4, Eqs. 2.111, 2.123–2.125
+ *   • Macleod, Thin-Film Optical Filters 5th ed., §2.4, Eqs. 2.111, 2.123–2.125;
+ *     Eq. 2.83 (transmittance out of an absorbing incident medium);
+ *     §10.2, Eqs. 10.11–10.13 (tilted admittances from the real invariant n0 sinθ0)
  *   • Sullivan & Dobrowolski, Appl. Opt. 35, 5484 (1996), Eqs. (3)–(6)
  *   • Tikhonravov, Trubetskov & DeBell, Appl. Opt. 35, 5493 (1996)
  */
@@ -90,14 +92,37 @@ function rescaleMatrix(M) {
 }
 
 // ── Snell's law ───────────────────────────────────────────────────────────────
+//
+// Every wave in the stack shares one transverse wavevector, n0 sinθ0 with n0
+// the REAL part of the incident index (Macleod 5th ed., §10.2, Eqs. 10.11 to
+// 10.13). An absorbing incident medium then carries an inhomogeneous wave whose
+// amplitude falls along the normal only, and each medium's cosθ follows from
+// that one real invariant. Putting the complex index into the invariant would
+// make the amplitude vary along the interface, so energy would flow sideways
+// inside lossless layers and R + T would be wrong by a term linear in the
+// incident k at oblique incidence.
 
 function snellCosTheta(n0, sinTheta0, nj) {
-    // sinThetaJ = n0 * sinTheta0 / nj   (complex)
-    const sinThetaJ = cdiv(cmul(n0, sinTheta0), nj);
+    // sinThetaJ = Re(n0) * sinTheta0 / nj   (complex)
+    const sinThetaJ = cdiv(cmul([n0[0], 0], sinTheta0), nj);
     // cosTheta = sqrt(1 - sin²θ)
     return csqrt(csub([1, 0], cmul(sinThetaJ, sinThetaJ)));
 }
 
+// cosθ0 of the incident medium. A transparent medium keeps the plain
+// sqrt(1 − sin²θ0). An absorbing one takes its cosine from the same real
+// invariant as the layers, so its tilted admittance is sqrt(N0² − n0² sin²θ0)
+// and the incident wave belongs to the same boundary problem as the rest of
+// the stack. R + T then departs from 1 for lossless layers only by the
+// interference of the incident and reflected waves in the absorbing medium,
+// the term Macleod's Eq. 2.83 carries, which is second order in k0 for a
+// bare interface.
+function incidentCosTheta(n0, sinTheta0) {
+    return n0[1] === 0
+        ? csqrt(csub([1, 0], cmul(sinTheta0, sinTheta0)))
+        : snellCosTheta(n0, sinTheta0, n0);
+}
+
 // ── Layer characteristic matrix ───────────────────────────────────────────────
 
 function layerMatrix(nj, dj_nm, lambda_nm, cosTheta_j, pol) {
@@ -150,7 +175,7 @@ function layerMatrix(nj, dj_nm, lambda_nm, cosTheta_j, pol) {
  */
 export function tmm(lambda_nm, theta_deg, pol, n0, ns, layers) {
     const sinTheta0 = [Math.sin(theta_deg * Math.PI / 180), 0];
-    const cosTheta0 = csqrt(csub([1, 0], cmul(sinTheta0, sinTheta0)));
+    const cosTheta0 = incidentCosTheta(n0, sinTheta0);
 
     // Admittance of incident medium
     const eta0 = pol === 's'
@@ -241,7 +266,7 @@ function cmatvec(M, v) {
 export function tmmNeedleScan(lambda_nm, theta_deg, pol, n0, ns, layers,
                               candidateNs, intraFracs = []) {
     const sinTheta0 = [Math.sin(theta_deg * Math.PI / 180), 0];
-    const cosTheta0 = csqrt(csub([1, 0], cmul(sinTheta0, sinTheta0)));
+    const cosTheta0 = incidentCosTheta(n0, sinTheta0);
     const eta0 = pol === 's' ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
     const cosThetaS = snellCosTheta(n0, sinTheta0, ns);
     const etaS = pol === 's' ? cmul(ns, cosThetaS) : cdiv(ns, cosThetaS);
@@ -368,7 +393,7 @@ export function tmmNeedleScan(lambda_nm, theta_deg, pol, n0, ns, layers,
 // `metrics()` in tmmNeedleScan.
 export function tmmThicknessJacobian(lambda_nm, theta_deg, pol, n0, ns, layers) {
     const sinTheta0 = [Math.sin(theta_deg * Math.PI / 180), 0];
-    const cosTheta0 = csqrt(csub([1, 0], cmul(sinTheta0, sinTheta0)));
+    const cosTheta0 = incidentCosTheta(n0, sinTheta0);
     const eta0 = pol === 's' ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
     const cosThetaS = snellCosTheta(n0, sinTheta0, ns);
     const etaS = pol === 's' ? cmul(ns, cosThetaS) : cdiv(ns, cosThetaS);
@@ -464,7 +489,7 @@ export function tmmThicknessJacobian(lambda_nm, theta_deg, pol, n0, ns, layers)
 // (tests/hessian_fd_validation.mjs).*
 export function tmmThicknessHessian(lambda_nm, theta_deg, pol, n0, ns, layers) {
     const sinTheta0 = [Math.sin(theta_deg * Math.PI / 180), 0];
-    const cosTheta0 = csqrt(csub([1, 0], cmul(sinTheta0, sinTheta0)));
+    const cosTheta0 = incidentCosTheta(n0, sinTheta0);
     const eta0 = pol === 's' ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
     const cosThetaS = snellCosTheta(n0, sinTheta0, ns);
     const etaS = pol === 's' ? cmul(ns, cosThetaS) : cdiv(ns, cosThetaS);
@@ -598,5 +623,5 @@ export function tmmThicknessHessian(lambda_nm, theta_deg, pol, n0, ns, layers) {
 
 export {
     cadd, csub, cmul, cdiv, cabs2, cconj, csqrt, ccos, csin, creal, cimag,
-    matmul, rescaleMatrix, snellCosTheta, layerMatrix, cmatvec
+    matmul, rescaleMatrix, snellCosTheta, incidentCosTheta, layerMatrix, cmatvec
 };

package/src/tmm_kernel.c

@@ -23,7 +23,8 @@
  * Builds with any C99 compiler; no dependencies beyond libm.
  *
  * References:
- *   • Macleod, Thin-Film Optical Filters 5th ed., §2.4, Eqs. 2.111, 2.123–2.125
+ *   • Macleod, Thin-Film Optical Filters 5th ed., §2.4, Eqs. 2.111, 2.123–2.125;
+ *     Eq. 2.83; §10.2, Eqs. 10.11–10.13 (tilted admittances, real invariant)
  *   • Sullivan & Dobrowolski, Appl. Opt. 35, 5484 (1996), Eqs. (3)–(6)
  *   • Tikhonravov, Trubetskov & DeBell, Appl. Opt. 35, 5493 (1996)
  *   • Birge & Kärtner, Appl. Opt. 45, 1478 (2006)   [phase dispersion]
@@ -110,13 +111,24 @@ static inline vec2 cmatvec(mat2 M, vec2 v) {
     return o;
 }
 
-/* ── Snell's law: cosθ_j from incident (n0, sinθ0) into medium nj ─────────── */
+/* ── Snell's law: cosθ_j from incident (n0, sinθ0) into medium nj ───────────
+ * The transverse invariant is Re(n0) sinθ0 (Macleod 5th ed., §10.2, Eqs.
+ * 10.11–10.13): an absorbing incident medium carries a wave whose amplitude
+ * falls along the normal only, and every medium's cosθ follows from that one
+ * real invariant. Mirrors snellCosTheta / incidentCosTheta in tmm.js. */
 
 static inline cx snellCosTheta(cx n0, cx sinTheta0, cx nj) {
-    cx sinThetaJ = cdiv(cmul(n0, sinTheta0), nj);
+    cx sinThetaJ = cdiv(cmul(cmk(n0.re, 0.0), sinTheta0), nj);
     return csqrt_(csub(cmk(1.0, 0.0), cmul(sinThetaJ, sinThetaJ)));
 }
 
+/* cosθ0 of the incident medium: the plain cosine for a transparent medium,
+ * otherwise from the same real invariant as the layers. */
+static inline cx incidentCosTheta(cx n0, cx sinTheta0) {
+    if (n0.im == 0.0) return csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+    return snellCosTheta(n0, sinTheta0, n0);
+}
+
 /* ── Layer characteristic matrix (pol: 0 = s, 1 = p) ─────────────────────── */
 
 static inline mat2 layerMatrix(cx nj, double dj_nm, double lambda_nm, cx cosTheta_j, int pol) {
@@ -149,7 +161,7 @@ static void tmm_core(double lambda_nm, double theta_deg, int pol,
                      cx n0, cx ns, const double *layers, int N,
                      double *outR, double *outT, double *outA) {
     cx sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
-    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+    cx cosTheta0 = incidentCosTheta(n0, sinTheta0);
 
     cx eta0 = (pol == 0) ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
 
@@ -314,7 +326,7 @@ void tmm_monitor_curve(double lambda_nm, double theta_deg,
     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)));
+    cx cosTheta0 = incidentCosTheta(n0, sinTheta0);
 
     for (int pol = 0; pol < 2; pol++) {
         cx eta0 = (pol == 0) ? cmul(n0, cosTheta0) : cdiv(n0, cosTheta0);
@@ -392,11 +404,11 @@ int tmm_deposition_spectra(const double *lambdas, int nLam,
     }
 
     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]);
+        cx cosTheta0 = incidentCosTheta(n0, sinTheta0);
         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);
@@ -503,13 +515,13 @@ growing_eval *tmm_growing_eval_create(const double *lambdas, int nLam,
     }
 
     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;
+        cx cosTheta0 = incidentCosTheta(n0, h->sinTheta0);
         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);
@@ -593,7 +605,7 @@ void tmm_jacobian(double lambda_nm, double theta_deg, int pol,
     cx ns = cmk(ns_re, ns_im);
 
     cx sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
-    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+    cx cosTheta0 = incidentCosTheta(n0, sinTheta0);
     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);
@@ -696,7 +708,7 @@ void tmm_needle_scan(double lambda_nm, double theta_deg, int pol,
                      double *base, double *gaps, double *intra) {
     cx n0 = cmk(n0_re, n0_im), ns = cmk(ns_re, ns_im);
     cx sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
-    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+    cx cosTheta0 = incidentCosTheta(n0, sinTheta0);
     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);
@@ -805,7 +817,7 @@ void tmm_hessian(double lambda_nm, double theta_deg, int pol,
     cx ns = cmk(ns_re, ns_im);
 
     cx sinTheta0 = cmk(sin(theta_deg * PI / 180.0), 0.0);
-    cx cosTheta0 = csqrt_(csub(cmk(1.0, 0.0), cmul(sinTheta0, sinTheta0)));
+    cx cosTheta0 = incidentCosTheta(n0, sinTheta0);
     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);
@@ -1083,10 +1095,32 @@ static double jmatmag(jmat2 M) {
     return magnitude;
 }
 
+/* The real part of a jet, order by order. */
+static inline jet jreal(jet a) {
+    jet o;
+    for (int i = 0; i < JET_N; i++) o.c[i] = cmk(a.c[i].re, 0.0);
+    return o;
+}
+static inline int jhas_imag(jet a) {
+    for (int i = 0; i < JET_N; i++) if (a.c[i].im != 0.0) return 1;
+    return 0;
+}
+
+/* Same real invariant Re(n0) sinθ0 as snellCosTheta, in jet arithmetic. */
 static inline jet jsnell_cos(jet n0, jet sin0, jet nj) {
-    jet s = jdiv(jmul(n0, sin0), nj);
+    jet s = jdiv(jmul(jreal(n0), sin0), nj);
     return jsqrt_j(jsub(jconst(1.0, 0.0), jmul(s, s)));
 }
+/* cosθ0 of the incident medium: from the same real invariant as the layers
+ * when the medium absorbs at any order, otherwise the plain cosine, taken
+ * from the sine jet when the caller supplied one. Mirrors incidentCosine in
+ * phase.js. */
+static inline jet jincident_cos(jet n0, jet incidentSine, int fromSineJet, double theta_deg) {
+    if (jhas_imag(n0)) return jsnell_cos(n0, incidentSine, n0);
+    return fromSineJet
+        ? jsqrt_j(jsub(jconst(1.0, 0.0), jmul(incidentSine, incidentSine)))
+        : jconst(cos(theta_deg * PI / 180.0), 0.0);
+}
 static inline jet jadmittance(jet n, jet cosv, int pol) {
     return (pol == 0) ? jmul(n, cosv) : jdiv(n, cosv);
 }
@@ -1207,9 +1241,7 @@ static void jphase_core(double lambda, double omega, double theta_deg, int pol,
                         const jet *sinJet, double *out10) {
     jet wavelength = jwavelength(lambda, omega);
     jet incidentSine = sinJet ? *sinJet : jconst(sin(theta_deg * PI / 180.0), 0.0);
-    jet incidentCosine = sinJet
-        ? jsqrt_j(jsub(jconst(1.0, 0.0), jmul(incidentSine, incidentSine)))
-        : jconst(cos(theta_deg * PI / 180.0), 0.0);
+    jet incidentCosine = jincident_cos(n0, incidentSine, sinJet != NULL, theta_deg);
     jet incidentEta = jadmittance(n0, incidentCosine, pol);
     jet substrateCosine = jsnell_cos(n0, incidentSine, ns);
     jet substrateEta = jadmittance(ns, substrateCosine, pol);
@@ -1313,9 +1345,7 @@ void tmm_phase_jacobian(double lambda, double omega, double theta_deg, int pol,
 
     jet wavelength = jwavelength(lambda, omega);
     jet incidentSine = sinePtr ? *sinePtr : jconst(sin(theta_deg * PI / 180.0), 0.0);
-    jet incidentCosine = sinePtr
-        ? jsqrt_j(jsub(jconst(1.0, 0.0), jmul(incidentSine, incidentSine)))
-        : jconst(cos(theta_deg * PI / 180.0), 0.0);
+    jet incidentCosine = jincident_cos(n0, incidentSine, sinePtr != NULL, theta_deg);
     jet incidentEta = jadmittance(n0, incidentCosine, pol);
     jet substrateCosine = jsnell_cos(n0, incidentSine, ns);
     jet substrateEta = jadmittance(ns, substrateCosine, pol);