@woosh/meep-engine 2.131.3 → 2.131.5

package/src/core/math/physics/mie/compute_lorenz_mie_optical_properties.js

@@ -1,344 +1,8 @@
-import { assert } from "../../../assert.js";
-import { v2_dot } from "../../../geom/vec2/v2_dot.js";
-import { v2_length } from "../../../geom/vec2/v2_length.js";
-import { complex_add } from "../../complex/complex_add.js";
-import { complex_div } from "../../complex/complex_div.js";
-import { complex_mul } from "../../complex/complex_mul.js";
-import { complex_sub } from "../../complex/complex_sub.js";
+import { lorenz_mie_coefs } from "./lorenz_mie_coefs.js";
+import { mie_ab_to_optical_properties } from "./mie_ab_to_optical_properties.js";
 
 // Complex number operations
 
-function vec2(x, y) {
-    return new Float64Array([x, y]);
-}
-
-function vec4(x, y, z, w) {
-    return new Float64Array([x, y, z, w]);
-}
-
-function cadd(a, b) {
-    const r = vec2(0, 0);
-
-    complex_add(r, a, b);
-
-    return r;
-}
-
-function csub(a, b) {
-    const r = vec2(0, 0);
-
-
-    complex_sub(r, a, b);
-
-    return r;
-}
-
-function cmult(a, b) {
-    const r = vec2(0, 0);
-
-
-    complex_mul(r, a, b);
-
-    return r;
-}
-
-function cdiv(a, b) {
-    const r = vec2(0, 0);
-
-
-    complex_div(r, a, b);
-
-    return r;
-}
-
-// Number of terms to include in infinite sums (truncation)
-function terms_to_sum(z) {
-    const size = v2_length(z[0], z[1]);
-    return Math.ceil(size + 4.3 * Math.cbrt(size) + 1.0);
-}
-
-
-// Downward recurrence for A
-function A_all_n(z, M) {
-    const A = new Array(M + 2);
-    A[M + 1] = vec2(0.0, 0.0);
-    for (let n = M; n >= 0; --n) {
-        const tmp = cdiv(vec2(n + 1.0, 0.0), z);
-        A[n] = csub(tmp, cdiv(vec2(1.0, 0.0), cadd(tmp, A[n + 1])));
-    }
-    return A;
-}
-
-// Upward recurrences for B, psi_zeta, and R
-function psi_zeta(n, z, A, old_B, old_psi_zeta) {
-    if (n > 0) {
-        const n_z = cdiv(vec2(n, 0.0), z);
-        const tmp = cmult(csub(n_z, A[n - 1]), csub(n_z, old_B));
-        old_psi_zeta = cmult(old_psi_zeta, tmp);
-    }
-    return old_psi_zeta;
-}
-
-/**
- * Calculates the B_n(z) coefficient for term 'n' via upward recurrence.
- * This is a helper function for LorenzMie_ab.
- *
- * @param {number} n - The current recurrence term index (n >= 0).
- * @param {vec2} z - The complex size parameter (x or y).
- * @param {Array<vec2>} A - Pre-computed log-derivatives A_n(z).
- * @param {vec2} old_B - The previous B coefficient (B_{n-1}).
- * @param {vec2} old_psi_zeta - The previous psi_zeta product term.
- * @returns {vec2} The new B_n coefficient (complex number).
- */
-function B(n, z, A, old_B, old_psi_zeta) {
-
-    if (n > 0) {
-        old_B.psi_zeta = psi_zeta(n, z, A, old_B, old_psi_zeta);
-        old_B = cadd(A[n], cdiv(vec2(0.0, 1.0), old_B.psi_zeta));
-    }
-
-    return old_B;
-}
-
-/**
- * Calculates the R_n(z) coefficient (ratio psi_n / zeta_n) for term 'n'.
- * This is a helper function for LorenzMie_ab.
- *
- * @param {number} n - The current recurrence term index (n >= 0).
- * @param {vec2} z - The complex size parameter (x).
- * @param {Array<vec2>} A - Pre-computed log-derivatives A_n(z).
- * @param {vec2} B_n - The current B_n(z) coefficient.
- * @param {vec2} old_R - The previous R coefficient (R_{n-1}).
- * @returns {vec2} The new R_n coefficient (complex number).
- */
-function R(n, z, A, B_n, old_R) {
-    if (n > 0) {
-        const n_z = cdiv(vec2(n, 0.0), z);
-        const tmp = cdiv(cadd(B_n, n_z), cadd(A[n], n_z));
-        old_R = cmult(old_R, tmp);
-    }
-    return old_R;
-}
-
-/**
- * Calculates the Lorenz-Mie scattering coefficients a_n and b_n for a single term 'n'.
- * This implements the formulas from Figure 3 of Frisvad et al. 2007.
- *
- * @param {number} n - The current recurrence term index (n >= 0).
- * @param {number} size - Unitless size parameter x_vac = 2*pi*r / lambda_vac.
- * @param {vec2} n_p - Complex refractive index of the particle.
- * @param {vec2} n_med - Complex refractive index of the medium.
- * @param {Array<vec2>} A_p - Pre-computed log-derivatives A_n(y) for the particle.
- * @param {Array<vec2>} A_med - Pre-computed log-derivatives A_n(x) for the medium.
- * @param {vec2} old_B - The previous B_{n-1}(x) coefficient.
- * @param {vec2} old_R - The previous R_{n-1}(x) coefficient.
- * @param {vec2} old_psi_zeta - The previous psi_zeta product.
- * @returns {vec4} A vec4 [Re(a_n), Im(a_n), Re(b_n), Im(b_n)] with state properties
- * (.old_B, .old_R, .old_psi_zeta) attached for the next iteration.
- */
-function LorenzMie_ab(n, size, n_p, n_med, A_p, A_med, old_B, old_R, old_psi_zeta) {
-
-    const x = vec2(size * n_med[0], size * n_med[1]);
-    const B_n = B(n, x, A_med, old_B, old_psi_zeta);
-    const R_n = R(n, x, A_med, B_n, old_R);
-    const n_med_A_p = cmult(n_med, A_p[n]);
-    const n_p_A_med = cmult(n_p, A_med[n]);
-    const n_p_A_p = cmult(n_p, A_p[n]);
-    const n_med_A_med = cmult(n_med, A_med[n]);
-    const n_p_B_n = cmult(n_p, B_n);
-    const n_med_B_n = cmult(n_med, B_n);
-    const a = cmult(R_n, cdiv(csub(n_med_A_p, n_p_A_med), csub(n_med_A_p, n_p_B_n)));
-    const b = cmult(R_n, cdiv(csub(n_p_A_p, n_med_A_med), csub(n_p_A_p, n_med_B_n)));
-
-
-    const ab = vec4(a[0], a[1], b[0], b[1]);
-
-    ab.old_psi_zeta = n > 0 ? old_B.psi_zeta : old_psi_zeta;
-    ab.old_B = B_n;
-    ab.old_R = R_n;
-
-    return ab;
-}
-
-/**
- * The following source code implements Lorenz-Mie theory using the formulas presented in the SIGGRAPH 2007 paper
- *
- * Computing the Scattering Properties of Participating
- * Media Using Lorenz-Mie Theory
- *
- * By authors: Jeppe Revall Frisvad
- *             Niels Joergen Christensen
- *             Henrik Wann Jensen
- *
- * Code written by Jeppe Revall Frisvad, 2017.
- * Copyright (c) Jeppe Revall Frisvad 2017
- *
- * Permission is granted to anyone to use this code as
- * software for any purpose, including commercial applications.
- * However, the software is provided 'as-is' without any warranty.
- *
- * @param {number} radius_m - Particle radius (in meters).
- * @param {number} wavelength_m - Wavelength of light in vacuum (in meters).
- * @param {vec2} n_p - Complex refractive index of the particle
- * @param {vec2} n_med - Complex refractive index of the medium (e.g., [1.0, 0.0] for air).
- */
-function lorenz_mie_coefs(
-    wavelength_m,
-    radius_m,
-    n_p,
-    n_med
-) {
-
-    assert.isNumber(wavelength_m, 'wavelength_m');
-    assert.isFinite(wavelength_m, 'wavelength_m');
-    assert.greaterThan(wavelength_m, 0, 'wavelength_m');
-
-    assert.isNumber(radius_m, 'radius_m');
-    assert.isFinite(radius_m, 'radius_m');
-    assert.greaterThan(radius_m, 0, 'radius_m');
-
-    const psize = 2.0 * Math.PI * radius_m / wavelength_m;
-
-    const x = vec2(psize * n_med[0], psize * n_med[1]);
-    const y = vec2(psize * n_p[0], psize * n_p[1]);
-    const M = terms_to_sum(x);
-    const A_med = A_all_n(x, M);
-    const A_p = A_all_n(y, M);
-
-    const e_term = Math.exp(2.0 * x[1]);
-
-    let prev_psi_zeta = vec2(0.5 * (1.0 - Math.cos(2.0 * x[0]) / e_term), -0.5 * Math.sin(2.0 * x[0]) / e_term);
-    let prev_B = vec2(0.0, 1.0);
-    let prev_R = vec2(0.5 * (1.0 - Math.cos(2.0 * x[0]) * e_term), 0.5 * Math.sin(2.0 * x[0]) * e_term);
-
-    const ab = new Float64Array(M * 4);
-
-    for (let n = 0; n < M; ++n) {
-
-        const ab_n = LorenzMie_ab(
-            n, psize, n_p, n_med, A_p, A_med,
-            prev_B, prev_R, prev_psi_zeta
-        );
-
-        prev_psi_zeta = ab_n.old_psi_zeta;
-        prev_B = ab_n.old_B;
-        prev_R = ab_n.old_R;
-
-        // plug the data in
-        ab[4 * n] = ab_n[0];
-        ab[4 * n + 1] = ab_n[1];
-        ab[4 * n + 2] = ab_n[2];
-        ab[4 * n + 3] = ab_n[3];
-    }
-    return ab;
-}
-
-/**
- * Calculates the final optical properties by summing the Mie coefficients.
- * This function implements Equations (2) and (3) from the 2007 paper
- * "Computing the Scattering Properties of Participating Media..."
- *
- * @param {Float32Array} ab - The flat array of a_n, b_n coefficients from LorenzMie_coefs.
- * @param {number} radius - Particle radius (in meters).
- * @param {number} wavelength - Wavelength of light in vacuum (in meters).
- * @param {vec2} n_med - Complex refractive index of the medium (e.g., [1.0, 0.0] for air).
- * @returns {object} An object with Q_e, Q_s, albedo, C_ext, and C_sca.
- */
-function ab_to_optical_properties(
-    ab,
-    wavelength,
-    radius,
-    n_med
-) {
-    const M = ab.length / 4;
-
-    let sum_t = vec2(0, 0); // Complex sum for Ct
-    let sum_s = 0; // Real sum for Cs
-    let sum_g = 0;          // Real sum for Asymmetry (g)
-
-    for (let n = 1; n < M; ++n) {
-        // The 'n' in the paper's formulas
-        const multiplier = 2 * n + 1;
-
-        // Get an and bn from your flat array
-        const an = vec2(ab[4 * n], ab[4 * n + 1]);
-        const bn = vec2(ab[4 * n + 2], ab[4 * n + 3]);
-
-        // 1. For Extinction (Ct)
-        const an_plus_bn = cadd(an, bn);
-        // You need complex math functions cadd, cdiv
-        const n_med_sq = cmult(n_med, n_med);
-        const term_t = cdiv(an_plus_bn, n_med_sq);
-        sum_t = cadd(sum_t, cmult(vec2(multiplier, 0), term_t));
-
-        // 2. For Scattering (Cs)
-        const an_mag_sq = an[0] * an[0] + an[1] * an[1];
-        const bn_mag_sq = bn[0] * bn[0] + bn[1] * bn[1];
-        sum_s += multiplier * (an_mag_sq + bn_mag_sq);
-
-        // 3. Asymmetry Accumulation (New)
-        // Term A: Interference of an and bn
-        // Formula: (2n+1) / (n(n+1)) * Re(an * bn*)
-        const factor_A = (2 * n + 1) / (n * (n + 1));
-        sum_g += factor_A * v2_dot(an[0], an[1], bn[0], bn[1]);
-
-        // Term B: Interference of n and n+1
-        // Formula: (n(n+2)) / (n+1) * Re(an * an+1* + bn * bn+1*)
-        if (n < M - 1) {
-            const n_next = n + 1;
-            const an1_r = ab[4 * n_next];
-            const an1_i = ab[4 * n_next + 1];
-            const bn1_r = ab[4 * n_next + 2];
-            const bn1_i = ab[4 * n_next + 3];
-
-            const factor_B = (n * (n + 2)) / (n + 1);
-
-            const term_an_an1 = v2_dot(an[0], an[1], an1_r, an1_i);
-            const term_bn_bn1 = v2_dot(bn[0], bn[1], bn1_r, bn1_i);
-
-            sum_g += factor_B * (term_an_an1 + term_bn_bn1);
-        }
-    }
-
-    // --- Final Calculations ---
-
-    // Asymmetry Parameter (g)
-    // g = (4/x^2 * sum_g) / (2/x^2 * sum_s) => 2 * sum_g / sum_s
-    let g = 0;
-    if (sum_s > 1e-12) {
-        g = (2 * sum_g) / sum_s;
-    }
-
-    // Extinction (Ct from Eq. 22)
-    const C_t = (Math.pow(wavelength, 2) / (2 * Math.PI)) * sum_t[0]; //
-
-    // Scattering (Cs from Eq. 23)
-    const alpha = (4 * Math.PI * radius * n_med[1]) / wavelength;
-    let gamma;
-    if (Math.abs(alpha) < 1e-10) {
-        // avoid division by 0
-        gamma = 1;
-    } else {
-        gamma = (2 * (1 + (alpha - 1) * Math.exp(alpha))) / Math.pow(alpha, 2);
-    }
-    const n_med_mag_sq = n_med[0] * n_med[0] + n_med[1] * n_med[1];
-    const C_s_factor = (Math.pow(wavelength, 2) * Math.exp(-alpha)) / (2 * Math.PI * gamma * n_med_mag_sq);
-    const C_s = C_s_factor * sum_s;
-
-    // Bulk Coefficients (assuming number density N)
-    const sigma_a_med = (4 * Math.PI * n_med[1]) / wavelength;
-
-    // To get bulk coefficients sigma_t and sigma_s, use the following formulae, where N is numeric density (particles per cubic meter):
-    // sigma_t = sigma_a_med + C_t * N;
-    // sigma_s = C_s * N;
-
-    return {
-        sigma_a_med,
-        C_ext: C_t,
-        C_sca: C_s,
-        g, // Anisotropy parameter
-    }
-}
 
 /**
  * For refractive index, the imaginary part controls the absorption coefficient.
@@ -358,6 +22,6 @@ export function compute_lorenz_mie_optical_properties(
 ) {
     const ab = lorenz_mie_coefs(wavelength, radius, n_p, n_med);
 
-    return ab_to_optical_properties(ab, wavelength, radius, n_med);
+    return mie_ab_to_optical_properties(ab, wavelength, radius, n_med);
 }
 

package/src/core/math/physics/mie/compute_mie_particle_properties_rgb.js

@@ -108,7 +108,7 @@ export function compute_mie_particle_properties_rgb(
 
     // Resolve G
     // If the particle is invisible (no scattering), default to isotropic (0)
-    const final_g = g_weight_total > 1e-12 ? (g_weighted_accumulator / g_weight_total) : 0;
+    const final_g = g_weight_total > 1e-20 ? (g_weighted_accumulator / g_weight_total) : 0;
 
     // convert XYZ -> sRGB
 

package/src/core/math/physics/mie/compute_mie_phase.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Computes the normalized Mie phase function value for a specific angle.
+ *
+ * The phase function P(theta) is normalized such that the integral over 4pi solid angle is 4pi.
+ * This implementation uses the recurrence relations for angular functions pi_n and tau_n as described by Bohren & Huffman.
+ *
+ * @param {Float32Array} ab - The flat array of a_n, b_n coefficients from LorenzMie_coefs.
+ * @param {number} C_sca total scattering cross-section for normalization
+ * @param {number} wavelength - Wavelength of light in vacuum (in meters).
+ * @param {vec2} n_med - Complex refractive index of the medium.
+ * @param {number} cos_theta - Cosine of the angle between incoming light and observation angle.
+ * @returns {number} The normalized phase function value P(theta).
+ */
+export function compute_mie_phase(ab: Float32Array, C_sca: number, n_med: typeof vec2, wavelength: number, cos_theta: number): number;
+import { vec2 } from "./lorenz_mie_coefs.js";
+//# sourceMappingURL=compute_mie_phase.d.ts.map

package/src/core/math/physics/mie/compute_mie_phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute_mie_phase.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/physics/mie/compute_mie_phase.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,sCAPW,YAAY,SACZ,MAAM,kCACN,MAAM,aAEN,MAAM,GACJ,MAAM,CAsElB;qBAnFoB,uBAAuB"}

package/src/core/math/physics/mie/compute_mie_phase.js

@@ -0,0 +1,84 @@
+import { vec2 } from "./lorenz_mie_coefs.js";
+
+/**
+ * Computes the normalized Mie phase function value for a specific angle.
+ *
+ * The phase function P(theta) is normalized such that the integral over 4pi solid angle is 4pi.
+ * This implementation uses the recurrence relations for angular functions pi_n and tau_n as described by Bohren & Huffman.
+ *
+ * @param {Float32Array} ab - The flat array of a_n, b_n coefficients from LorenzMie_coefs.
+ * @param {number} C_sca total scattering cross-section for normalization
+ * @param {number} wavelength - Wavelength of light in vacuum (in meters).
+ * @param {vec2} n_med - Complex refractive index of the medium.
+ * @param {number} cos_theta - Cosine of the angle between incoming light and observation angle.
+ * @returns {number} The normalized phase function value P(theta).
+ */
+export function compute_mie_phase(
+    ab,
+    C_sca,
+    n_med,
+    wavelength,
+    cos_theta,
+) {
+
+    // If there is effectively no scattering, return isotropic phase (1.0)
+    if (C_sca < 1e-30) return 1.0;
+
+    const M = ab.length / 4;
+
+    // Initialize sums as scalars (faster than array access)
+    // S1 = Real + Imaginary parts
+    let S1_r = 0.0;
+    let S1_i = 0.0;
+
+    // S2 = Real + Imaginary parts
+    let S2_r = 0.0;
+    let S2_i = 0.0;
+
+    // Angular function recurrence initialization
+    let pi_prev = 0.0; // pi_0 = 0
+    let pi_cur = 1.0;  // pi_1 = 1
+
+    for (let n = 1; n < M; ++n) {
+        // 1. Load Coefficients directly (Zero Allocation)
+        const idx = 4 * n;
+        const an_r = ab[idx];
+        const an_i = ab[idx + 1];
+        const bn_r = ab[idx + 2];
+        const bn_i = ab[idx + 3];
+
+        // 2. Angular Recurrence
+        // tau_n = n * cos_theta * pi_n - (n + 1) * pi_{n-1}
+        const tau_cur = n * cos_theta * pi_cur - (n + 1) * pi_prev;
+
+        // 3. Update Sums
+        // factor = (2n + 1) / (n(n + 1))
+        const factor = (2 * n + 1) / (n * (n + 1));
+
+        // S1 += factor * (an * pi + bn * tau)
+        S1_r += factor * (an_r * pi_cur + bn_r * tau_cur);
+        S1_i += factor * (an_i * pi_cur + bn_i * tau_cur);
+
+        // S2 += factor * (an * tau + bn * pi)
+        S2_r += factor * (an_r * tau_cur + bn_r * pi_cur);
+        S2_i += factor * (an_i * tau_cur + bn_i * pi_cur);
+
+        // 4. Prepare next iteration
+        // pi_{n+1} = ((2n + 1) * cos * pi_n - (n + 1) * pi_{n-1}) / n
+        const pi_next = ((2 * n + 1) * cos_theta * pi_cur - (n + 1) * pi_prev) / n;
+        pi_prev = pi_cur;
+        pi_cur = pi_next;
+    }
+
+    // Calculate Intensity: (|S1|^2 + |S2|^2) / 2
+    const S1_sq = S1_r * S1_r + S1_i * S1_i;
+    const S2_sq = S2_r * S2_r + S2_i * S2_i;
+    const intensity = 0.5 * (S1_sq + S2_sq);
+
+    // Wavenumber in medium k = 2pi * Re(n_med) / lambda
+    const k_med = (2.0 * Math.PI * n_med[0]) / wavelength;
+    const k2 = k_med * k_med;
+
+    // Normalization: P(theta) = 4pi * I / (k^2 * C_sca)
+    return (4.0 * Math.PI * intensity) / (k2 * C_sca);
+}

package/src/core/math/physics/mie/lorenz_mie_coefs.d.ts

@@ -0,0 +1,29 @@
+export function vec2(x: any, y: any): Float64Array;
+export function cadd(a: any, b: any): Float64Array;
+export function cmult(a: any, b: any): Float64Array;
+export function cdiv(a: any, b: any): Float64Array;
+/**
+ * The following source code implements Lorenz-Mie theory using the formulas presented in the SIGGRAPH 2007 paper
+ *
+ * Computing the Scattering Properties of Participating
+ * Media Using Lorenz-Mie Theory
+ *
+ * By authors: Jeppe Revall Frisvad
+ *             Niels Joergen Christensen
+ *             Henrik Wann Jensen
+ *
+ * Code written by Jeppe Revall Frisvad, 2017.
+ * Copyright (c) Jeppe Revall Frisvad 2017
+ *
+ * Permission is granted to anyone to use this code as
+ * software for any purpose, including commercial applications.
+ * However, the software is provided 'as-is' without any warranty.
+ *
+ * @param {number} radius_m - Particle radius (in meters).
+ * @param {number} wavelength_m - Wavelength of light in vacuum (in meters).
+ * @param {vec2} n_p - Complex refractive index of the particle
+ * @param {vec2} n_med - Complex refractive index of the medium (e.g., [1.0, 0.0] for air).
+ * @returns {Float64Array} Mie coefficients a_n and b_n in form [a_n0.r, a_n0.i, b_n0.r, b_n0.i, ... a_nN.r, a_nN.i, b_nN.r, b_nN.i]
+ */
+export function lorenz_mie_coefs(wavelength_m: number, radius_m: number, n_p: typeof vec2, n_med: typeof vec2): Float64Array;
+//# sourceMappingURL=lorenz_mie_coefs.d.ts.map

package/src/core/math/physics/mie/lorenz_mie_coefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lorenz_mie_coefs.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/physics/mie/lorenz_mie_coefs.js"],"names":[],"mappings":"AAOA,mDAEC;AAMD,mDAMC;AAWD,oDAOC;AAED,mDAOC;AA8GD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+CALW,MAAM,YADN,MAAM,yCAIJ,YAAY,CAqDxB"}