tmmcore 0.1.0 → 0.3.0

package/README.md

@@ -5,26 +5,22 @@
           srcset="https://raw.githubusercontent.com/aai2k/tmmcore/main/docs/img/banner-on-dark.png">
   <img alt="tmmcore"
        src="https://raw.githubusercontent.com/aai2k/tmmcore/main/docs/img/banner-on-light.png"
-       width="640">
+       width="320">
 </picture>
 
 **Transfer-matrix method for multilayer thin-film optics, with exact analytic derivatives.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![npm](https://img.shields.io/npm/v/tmmcore)](https://www.npmjs.com/package/tmmcore) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+**[Documentation](https://aai2k.github.io/tmmcore/)** · **[Getting started](https://aai2k.github.io/tmmcore/getting-started/)** · **[API](https://aai2k.github.io/tmmcore/api/)** · **[Validation](https://aai2k.github.io/tmmcore/validation/)**
 
 </div>
 
-Takes a stack of layers and returns reflectance, transmittance and absorptance
-for absorbing and dispersive materials, at any angle of incidence, in s and p
-polarization. Alongside the spectra it returns the exact thickness Jacobian, the
-exact thickness Hessian, and the needle-insertion P-function, computed
-analytically rather than by finite differences.
+Takes a stack of layers and returns reflectance, transmittance and absorptance for absorbing and dispersive materials, at any angle of incidence, in s and p polarization. Alongside the spectra it returns the exact thickness Jacobian, the exact thickness Hessian, and the needle-insertion P-function, computed analytically rather than by finite differences.
 
-Ships as JavaScript, as C, and as a WebAssembly build of the C. The JavaScript
-has no dependencies and works on import. WebAssembly is opt-in and roughly an
-order of magnitude faster.
+It also computes phase, group delay, GDD and third-order dispersion, by carrying the same matrix in third-order Taylor arithmetic. Those come out analytically too, so they do not depend on the wavelength grid you sampled and there is no finite-difference step to tune. Their thickness gradients come along in the same call, which is what makes chirped-mirror design a gradient problem.
 
-**[Documentation](https://aai2k.github.io/tmmcore/)**
+Ships as JavaScript, as C, and as a WebAssembly build of the C. The JavaScript has no dependencies and works on import. WebAssembly is opt-in and roughly an order of magnitude faster.
 
 ## Install
 
@@ -56,8 +52,7 @@ Layers run from the incident medium toward the substrate.
 
 ## Conventions
 
-Mismatched conventions are the most common cause of two TMM codes disagreeing,
-so check these first.
+Mismatched conventions are the most common cause of two TMM codes disagreeing, so check these first.
 
 | | |
 |---|---|
@@ -68,31 +63,27 @@ so check these first.
 | Complex numbers | `[re, im]` pairs |
 | Layer order | incident medium → substrate |
 
-This is the complex conjugate of Macleod's convention. R, T and A are identical
-under conjugation; phase-sensitive quantities are not.
+This is the complex conjugate of Macleod's convention. R, T and A are identical under conjugation; phase-sensitive quantities are not.
 
 ## Verify it yourself
 
-Two commands, neither needing anything but Node:
+Three commands, none needing anything but Node:
 
 ```bash
-npm test        # the JavaScript and the C agree, to float64 round-off
-npm run compare # and both agree with an independent implementation
+node examples/01-single-layer.mjs   # matches the closed-form solution
+npm test                            # the JavaScript and the C agree
+npm run compare                     # and both agree with an independent implementation
 ```
 
-The first drives both implementations with identical inputs across absorbing,
-dispersive and oblique-incidence cases and compares every returned quantity.
-64,416 comparisons, worst disagreement 4.4e-16.
+The first tests the equations rather than agreement, and is the only one here that does. A single quarter-wave layer at normal incidence has an exact solution (Macleod §3.2); tmmcore reproduces it to 1.4e-17, inside double-precision epsilon of 2.2e-16.
+
+The second drives both implementations with identical inputs across absorbing, dispersive and oblique-incidence cases and compares every returned quantity. 64,416 comparisons, worst disagreement 4.4e-16. This is two implementations by the same author, so it catches porting bugs and establishes nothing beyond that.
+
+The third checks them against [Steven Byrnes' `tmm`](https://github.com/sbyrnes321/tmm), written independently in Python under the same complex-index convention, so only the mathematics is under test. 12,352 values, worst disagreement 8.6e-14, which is float64 accumulation noise over a forty-layer matrix product.
 
-The second checks them against [Steven Byrnes'
-`tmm`](https://github.com/sbyrnes321/tmm), written independently in Python under
-the same complex-index convention, so only the mathematics is under test. 12,352
-values, worst disagreement 8.6e-14, which is float64 accumulation noise over a
-forty-layer matrix product.
+[Validation](https://aai2k.github.io/tmmcore/validation/) sets out what each level does and does not establish, and lists what is not tested at all.
 
-Timing comparisons against four other packages are in the
-[documentation](https://aai2k.github.io/tmmcore/comparison/), and need a Python
-environment.
+The [comparison with four other TMM packages](https://aai2k.github.io/tmmcore/comparison/) covers accuracy as well as speed, including which of them run in single precision. Reproducing the timings needs a Python environment; the accuracy table does not.
 
 ## Documentation
 
@@ -104,8 +95,7 @@ environment.
 
 ## Using the C directly
 
-`src/tmm_kernel.c` is C99 with no dependencies beyond libm. Drop it into a
-project and compile:
+`src/tmm_kernel.c` is C99 with no dependencies beyond libm. Drop it into a project and compile:
 
 ```bash
 cc -std=c99 -O2 -c src/tmm_kernel.c
@@ -115,5 +105,4 @@ cc -std=c99 -O2 -c src/tmm_kernel.c
 
 [MIT](./LICENSE) © Andrey Achapovsky
 
-Built for and used by [TFStudio](https://github.com/aai2k/TFStudio), an
-open-source optical coating design application.
+Built for and used by [TFStudio](https://github.com/aai2k/TFStudio), an open-source optical coating design application.

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "tmmcore",
-  "version": "0.1.0",
-  "description": "Transfer-matrix method for multilayer thin-film optics, with exact analytic derivatives. JavaScript, C and WebAssembly.",
+  "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",
   "exports": {
     ".": "./src/index.js",
     "./tmm.js": "./src/tmm.js",
+    "./phase.js": "./src/phase.js",
+    "./taylorJet.js": "./src/taylorJet.js",
     "./tmmWasm.js": "./src/tmmWasm.js",
     "./tmm_kernel.wasm": "./src/tmm_kernel.wasm",
     "./tmm_kernel.c": "./src/tmm_kernel.c",
@@ -18,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",
-    "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,_malloc,_free -o src/tmm_kernel.wasm",
+    "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:native": "cc -std=c99 -pedantic -Wall -Wextra -O2 -c src/tmm_kernel.c -o tmm_kernel.o"
   },
   "keywords": [
@@ -34,7 +36,11 @@
     "reflectance",
     "transmittance",
     "photonics",
-    "webassembly"
+    "webassembly",
+    "group-delay",
+    "dispersion",
+    "chirped-mirror",
+    "ultrafast"
   ],
   "license": "MIT",
   "author": "Andrey Achapovsky",

package/src/build.ps1

@@ -24,7 +24,7 @@
 param([switch]$InstallEmsdk)
 
 $ErrorActionPreference = 'Stop'
-$root = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+$root = Split-Path -Parent $PSScriptRoot
 Set-Location $root
 
 # --- Try to activate emsdk from a known root (returns $true if emcc appears) ---
@@ -111,11 +111,17 @@ $emccArgs = @(
   '--no-entry'
   '-sSTANDALONE_WASM=1'
   '-sALLOW_MEMORY_GROWTH=1'
-  '-sEXPORTED_FUNCTIONS=_tmm_one,_tmm_spectrum,_tmm_jacobian,_tmm_needle_scan,_tmm_hessian,_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'
 )
 & emcc @emccArgs
+if ($LASTEXITCODE -ne 0) { Write-Error "emcc failed with exit code $LASTEXITCODE."; exit 1 }
 
 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/index.js

@@ -1,5 +1,5 @@
 /**
- * tmmcore — transfer-matrix method for multilayer thin films.
+ * tmmcore : transfer-matrix method for multilayer thin films.
  *
  * Two interchangeable implementations of the same physics:
  *
@@ -8,7 +8,7 @@
  *
  * The JavaScript path works immediately on import. WebAssembly is opt-in: load
  * the `.wasm` bytes, instantiate, and call the instance methods. Results agree
- * to float64 round-off either way — see `tests/equivalence.mjs`.
+ * to float64 round-off either way : see `tests/equivalence.mjs`.
  *
  * Conventions, which matter more than anything else here:
  *   ñ = n + ik              k ≥ 0 for absorbing media
@@ -32,4 +32,21 @@ export {
     matmul, rescaleMatrix, snellCosTheta, layerMatrix, cmatvec,
 } from './tmm.js';
 
+export {
+    // Phase, group delay, GDD and TOD
+    tmmPhaseDispersion,
+    tmmPhaseThicknessJacobian,
+    // Coefficient jets, for callers wanting r and t rather than the phase
+    tmmCoefficientJets,
+    tmmCoefficientThicknessJets,
+    coefficientPhaseDispersion,
+    coefficientPhaseThicknessDerivatives,
+    // Unit helpers
+    C_NM_PER_FS, omegaFromLambdaNm,
+} from './phase.js';
+
+// Taylor-jet arithmetic. The phase functions take refractive indices as jets;
+// these compose one from any dispersion formula you can write.
+export * from './taylorJet.js';
+
 export * from './tmmWasm.js';