tmmcore 0.3.0 → 0.4.0

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);
@@ -1292,37 +1324,54 @@ void tmm_phase_spectrum(const double *lambdas, const double *omegas, int nLam,
  * derivative, matching the point evaluator's base result.
  *
  *   out   : 10        as tmm_phase_one
- *   deriv : 8 × N     [side][quantity][layer], side 0 = r, 1 = t,
- *                     quantity 0 = dPhaseDeg, 1 = dGD, 2 = dGDD, 3 = dTOD
+ *   deriv : 10 × N    [side][quantity][layer], side 0 = r, 1 = t,
+ *                     quantity 0 = dPhaseDeg, 1 = dGD, 2 = dGDD, 3 = dTOD,
+ *                     4 = d(ln |coefficient|²)/dd, the relative intensity
+ *                     derivative, which the amplitude ratio in ellipsometry
+ *                     needs and which costs nothing here: it is the real part
+ *                     of the same logarithmic derivative the phase is the
+ *                     imaginary part of
  *
  * The prefix/suffix decomposition cannot carry a rescaling, so if the matrix
  * product overflows, `out` is still filled from the plain path and every entry
  * of `deriv` is set to NaN. */
 
-TMM_EXPORT("tmm_phase_jacobian")
-void tmm_phase_jacobian(double lambda, double omega, double theta_deg, int pol,
-                        const double *n0jet, const double *nsjet,
-                        const double *layerJets, const double *thick, int N,
-                        const double *sinJet, double *out, double *deriv) {
-    jet n0 = jread(n0jet), ns = jread(nsjet);
-    jet *layerN = (jet *)malloc(sizeof(jet) * (N > 0 ? N : 1));
-    for (int k = 0; k < N; k++) layerN[k] = jread(&layerJets[8 * k]);
-    jet sine;
-    if (sinJet) sine = jread(sinJet);
-    const jet *sinePtr = sinJet ? &sine : NULL;
+/* Scratch for one wavelength of the phase Jacobian: per-layer matrices with
+ * their thickness derivatives, and the prefix/suffix products. Allocated once
+ * per call by the entry points below, so the batched one reuses it across the
+ * whole grid. */
+typedef struct {
+    jmat2 *layerM, *layerDM, *prefix, *suffix;
+} jphase_jacobian_scratch;
+
+static jphase_jacobian_scratch jphase_jacobian_alloc(int N) {
+    int M = (N > 0 ? N : 1);
+    jphase_jacobian_scratch s;
+    s.layerM  = (jmat2 *)malloc(sizeof(jmat2) * M);
+    s.layerDM = (jmat2 *)malloc(sizeof(jmat2) * M);
+    s.prefix  = (jmat2 *)malloc(sizeof(jmat2) * (N + 1));
+    s.suffix  = (jmat2 *)malloc(sizeof(jmat2) * (N + 1));
+    return s;
+}
 
+static void jphase_jacobian_free(jphase_jacobian_scratch s) {
+    free(s.layerM); free(s.layerDM); free(s.prefix); free(s.suffix);
+}
+
+/* One wavelength of the phase Jacobian; see tmm_phase_jacobian for the layout
+ * of `out` and `deriv`. */
+static void jphase_jacobian_core(double lambda, double omega, double theta_deg, int pol,
+                                 jet n0, jet ns, const jet *layerN, const double *thick, int N,
+                                 const jet *sinePtr, double *out, double *deriv,
+                                 jphase_jacobian_scratch s) {
+    jmat2 *layerM = s.layerM, *layerDM = s.layerDM, *prefix = s.prefix, *suffix = s.suffix;
     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);
 
-    int M = (N > 0 ? N : 1);
-    jmat2 *layerM  = (jmat2 *)malloc(sizeof(jmat2) * M);
-    jmat2 *layerDM = (jmat2 *)malloc(sizeof(jmat2) * M);
     for (int k = 0; k < N; k++) {
         /* Match jphase_core's skip rule for invalid negative/NaN thicknesses,
          * while retaining the useful derivative of a zero-thickness layer. */
@@ -1336,8 +1385,6 @@ void tmm_phase_jacobian(double lambda, double omega, double theta_deg, int pol,
                          &layerM[k], &layerDM[k]);
     }
 
-    jmat2 *prefix = (jmat2 *)malloc(sizeof(jmat2) * (N + 1));
-    jmat2 *suffix = (jmat2 *)malloc(sizeof(jmat2) * (N + 1));
     prefix[0] = jidentity();
     int overflowed = 0;
     for (int k = 0; k < N; k++) {
@@ -1347,8 +1394,7 @@ void tmm_phase_jacobian(double lambda, double omega, double theta_deg, int pol,
 
     if (overflowed) {
         jphase_core(lambda, omega, theta_deg, pol, n0, ns, layerN, thick, N, sinePtr, out);
-        for (long i = 0; i < 8L * N; i++) deriv[i] = NAN;
-        free(layerN); free(layerM); free(layerDM); free(prefix); free(suffix);
+        for (long i = 0; i < 10L * N; i++) deriv[i] = NAN;
         return;
     }
 
@@ -1366,15 +1412,69 @@ void tmm_phase_jacobian(double lambda, double omega, double theta_deg, int pol,
                         &dReflection, &dTransmission);
         const jet sides[2] = { dReflection, dTransmission };
         const jet base[2] = { coefficients.reflection, coefficients.transmission };
-        for (int s = 0; s < 2; s++) {
+        for (int s2 = 0; s2 < 2; s2++) {
             cx dd[4];
-            jderivs(jdiv(sides[s], base[s]), dd);
-            deriv[((long)s * 4 + 0) * N + k] = -dd[0].im * 180.0 / PI;
-            deriv[((long)s * 4 + 1) * N + k] = dd[1].im;
-            deriv[((long)s * 4 + 2) * N + k] = dd[2].im;
-            deriv[((long)s * 4 + 3) * N + k] = dd[3].im;
+            /* d(ln coefficient)/dd: the imaginary part is the phase derivative
+             * (negated for Macleod's sign), the real part is d(ln |c|)/dd, so
+             * twice it is the relative derivative of |c|². */
+            jderivs(jdiv(sides[s2], base[s2]), dd);
+            deriv[((long)s2 * 5 + 0) * N + k] = -dd[0].im * 180.0 / PI;
+            deriv[((long)s2 * 5 + 1) * N + k] = dd[1].im;
+            deriv[((long)s2 * 5 + 2) * N + k] = dd[2].im;
+            deriv[((long)s2 * 5 + 3) * N + k] = dd[3].im;
+            deriv[((long)s2 * 5 + 4) * N + k] = 2.0 * dd[0].re;
         }
     }
+}
 
-    free(layerN); free(layerM); free(layerDM); free(prefix); free(suffix);
+TMM_EXPORT("tmm_phase_jacobian")
+void tmm_phase_jacobian(double lambda, double omega, double theta_deg, int pol,
+                        const double *n0jet, const double *nsjet,
+                        const double *layerJets, const double *thick, int N,
+                        const double *sinJet, double *out, double *deriv) {
+    jet *layerN = (jet *)malloc(sizeof(jet) * (N > 0 ? N : 1));
+    for (int k = 0; k < N; k++) layerN[k] = jread(&layerJets[8 * k]);
+    jet sine;
+    if (sinJet) sine = jread(sinJet);
+    jphase_jacobian_scratch scratch = jphase_jacobian_alloc(N);
+    jphase_jacobian_core(lambda, omega, theta_deg, pol, jread(n0jet), jread(nsjet),
+                         layerN, thick, N, sinJet ? &sine : NULL, out, deriv, scratch);
+    jphase_jacobian_free(scratch);
+    free(layerN);
+}
+
+/* ── Exported: batched phase Jacobian over a wavelength grid ─────────────────
+ * tmm_phase_jacobian at every wavelength of a grid in one call, for a caller
+ * fitting a whole measured spectrum of phase-derived quantities: ellipsometric
+ * Ψ and Δ, or group delay. Inputs are laid out as for tmm_phase_spectrum.
+ *
+ *   out   : nLam × 10        as tmm_phase_spectrum
+ *   deriv : nLam × 10 × N    per λ, the 10 × N block of tmm_phase_jacobian
+ *
+ * A wavelength whose matrix product overflows has its `out` filled from the
+ * plain path and its whole `deriv` block set to NaN, as the single-wavelength
+ * entry point does. */
+
+TMM_EXPORT("tmm_phase_jacobian_spectrum")
+void tmm_phase_jacobian_spectrum(const double *lambdas, const double *omegas, int nLam,
+                                 const double *n0jets, const double *nsjets,
+                                 const double *matJets, const double *thick, int N,
+                                 double theta_deg, int pol,
+                                 const double *sinJets, double *out, double *deriv) {
+    jet *layerN = (jet *)malloc(sizeof(jet) * (N > 0 ? N : 1));
+    jphase_jacobian_scratch scratch = jphase_jacobian_alloc(N);
+    for (int li = 0; li < nLam; li++) {
+        for (int k = 0; k < N; k++) {
+            long base = ((long)k * nLam + li) * 8;
+            layerN[k] = jread(&matJets[base]);
+        }
+        jet sine;
+        if (sinJets) sine = jread(&sinJets[8 * (long)li]);
+        jphase_jacobian_core(lambdas[li], omegas[li], theta_deg, pol,
+                             jread(&n0jets[8 * (long)li]), jread(&nsjets[8 * (long)li]),
+                             layerN, thick, N, sinJets ? &sine : NULL,
+                             &out[10 * (long)li], &deriv[10L * N * li], scratch);
+    }
+    jphase_jacobian_free(scratch);
+    free(layerN);
 }