tmmcore 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmmcore",
-  "version": "0.3.0",
+  "version": "0.4.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 && 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",
+    "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_phase_jacobian_spectrum,_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/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) => {
@@ -419,14 +430,17 @@ export function coefficientPhaseDispersion(coefficientJet) {
  */
 export function coefficientPhaseThicknessDerivatives(coefficientJet, thicknessJets) {
     if (!thicknessJets) return null;
-    const result = { phaseDeg: [], gd: [], gdd: [], tod: [] };
+    const result = { phaseDeg: [], gd: [], gdd: [], tod: [], logMagnitudeSquared: [] };
     for (const thicknessJet of thicknessJets) {
         const logarithmicDerivative = jetDivide(thicknessJet, coefficientJet);
         const derivatives = jetDerivatives(logarithmicDerivative);
+        // The imaginary part of d(ln c)/dd is the phase derivative; the real
+        // part is d(ln |c|)/dd, so twice it is the relative derivative of |c|².
         result.phaseDeg.push(-derivatives[0][1] * 180 / Math.PI);
         result.gd.push(derivatives[1][1]);
         result.gdd.push(derivatives[2][1]);
         result.tod.push(derivatives[3][1]);
+        result.logMagnitudeSquared.push(2 * derivatives[0][0]);
     }
     return result;
 }
@@ -489,8 +503,10 @@ export function tmmPhaseDispersion(lambda_nm, theta_deg, pol, n0Jet, nsJet, laye
  * thicknesses are skipped and receive zero derivative entries.
  *
  * @returns {{r, t}} where each side is the phase quantities plus
- *   `{dPhaseDeg, dGd, dGdd, dTod}`, arrays of length `layers.length`. The
- *   derivative arrays are `null` if the matrix product overflowed.
+ *   `{dPhaseDeg, dGd, dGdd, dTod, dLogMagnitudeSquared}`, arrays of length
+ *   `layers.length`. `dLogMagnitudeSquared` is d(ln |coefficient|²)/dd, the
+ *   relative intensity derivative. The derivative arrays are `null` if the
+ *   matrix product overflowed.
  */
 export function tmmPhaseThicknessJacobian(lambda_nm, theta_deg, pol, n0Jet, nsJet, layers, options = {}) {
     const prepared = prepare(lambda_nm, layers, options);
@@ -513,6 +529,7 @@ export function tmmPhaseThicknessJacobian(lambda_nm, theta_deg, pol, n0Jet, nsJe
             dGd: derivatives ? derivatives.gd : null,
             dGdd: derivatives ? derivatives.gdd : null,
             dTod: derivatives ? derivatives.tod : null,
+            dLogMagnitudeSquared: derivatives ? derivatives.logMagnitudeSquared : null,
         };
     };
     return {

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
 };