tmmcore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Achapovsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)"
+          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">
+</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)
+
+</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.
+
+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.
+
+**[Documentation](https://aai2k.github.io/tmmcore/)**
+
+## Install
+
+```bash
+npm install tmmcore
+```
+
+The `.wasm` is prebuilt and included, so no Emscripten toolchain is required.
+
+## Use
+
+```js
+import { tmm } from 'tmmcore';
+
+// A quarter-wave MgF2 layer on glass, at 550 nm, normal incidence.
+const { R, T, A } = tmm(
+    550,            // wavelength, nm
+    0,              // angle of incidence, degrees from normal
+    's',            // polarization: 's' or 'p'
+    [1.0, 0],       // incident medium, ñ = [n, k]
+    [1.52, 0],      // substrate
+    [{ n: [1.38, 0], d: 550 / (4 * 1.38) }]   // quarter wave, thickness in nm
+);
+
+console.log(R);   // 0.012600790214630274
+```
+
+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.
+
+| | |
+|---|---|
+| Refractive index | ñ = n + i·k, with **k ≥ 0** for absorbing media |
+| Time factor | exp(−iωt), so a wave exp(i(kz − ωt)) decays for k > 0 |
+| Wavelength, thickness | nanometres |
+| Angle | degrees from normal |
+| 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.
+
+## Verify it yourself
+
+Two commands, neither 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
+```
+
+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 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.
+
+Timing comparisons against four other packages are in the
+[documentation](https://aai2k.github.io/tmmcore/comparison/), and need a Python
+environment.
+
+## Documentation
+
+- [Getting started](https://aai2k.github.io/tmmcore/getting-started/)
+- [API reference](https://aai2k.github.io/tmmcore/api/)
+- [Examples](https://aai2k.github.io/tmmcore/examples/)
+- [Validation](https://aai2k.github.io/tmmcore/validation/)
+- [Comparison with other TMM packages](https://aai2k.github.io/tmmcore/comparison/)
+
+## Using the C directly
+
+`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
+```
+
+## Licence
+
+[MIT](./LICENSE) © Andrey Achapovsky
+
+Built for and used by [TFStudio](https://github.com/aai2k/TFStudio), an
+open-source optical coating design application.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "tmmcore",
+  "version": "0.1.0",
+  "description": "Transfer-matrix method for multilayer thin-film optics, with exact analytic derivatives. JavaScript, C and WebAssembly.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./tmm.js": "./src/tmm.js",
+    "./tmmWasm.js": "./src/tmmWasm.js",
+    "./tmm_kernel.wasm": "./src/tmm_kernel.wasm",
+    "./tmm_kernel.c": "./src/tmm_kernel.c",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node tests/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",
+    "build:native": "cc -std=c99 -pedantic -Wall -Wextra -O2 -c src/tmm_kernel.c -o tmm_kernel.o"
+  },
+  "keywords": [
+    "thin-film",
+    "optics",
+    "transfer-matrix",
+    "tmm",
+    "multilayer",
+    "optical-coating",
+    "reflectance",
+    "transmittance",
+    "photonics",
+    "webassembly"
+  ],
+  "license": "MIT",
+  "author": "Andrey Achapovsky",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aai2k/tmmcore.git"
+  },
+  "homepage": "https://aai2k.github.io/tmmcore/",
+  "bugs": {
+    "url": "https://github.com/aai2k/tmmcore/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false
+}

package/src/build.ps1

@@ -0,0 +1,121 @@
+# Build the tmmcore WASM kernel with Emscripten (Windows / PowerShell).
+#
+# Usage:
+#   npm run build:wasm            # build the kernel (auto-finds emsdk)
+#   .\src\build.ps1          # same, directly
+#   .\src\build.ps1 -InstallEmsdk   # clone+install emsdk first if missing
+#
+# emcc discovery order (first hit wins):
+#   1. emcc already on PATH
+#   2. $env:EMSDK
+#   3. a list of common install locations (any drive) -- see $candidates below
+#   4. with -InstallEmsdk (or $env:TFS_INSTALL_EMSDK=1): git-clone + install emsdk
+#      into %USERPROFILE%\emsdk, then activate it
+#
+# One-time manual install (if you prefer): https://emscripten.org/docs/getting_started/downloads.html
+#   git clone https://github.com/emscripten-core/emsdk
+#   cd emsdk; .\emsdk install latest; .\emsdk activate latest
+# Then either add it to PATH, set $env:EMSDK to that folder, or just put it in one
+# of the searched locations below and re-run -- no path is hardcoded anymore.
+#
+# NOTE: keep this file ASCII-only. PowerShell 5.1 reads -File scripts as the
+# system codepage, so non-ASCII bytes (em dashes, etc.) break string parsing.
+
+param([switch]$InstallEmsdk)
+
+$ErrorActionPreference = 'Stop'
+$root = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+Set-Location $root
+
+# --- Try to activate emsdk from a known root (returns $true if emcc appears) ---
+function Activate-Emsdk([string]$emsdkRoot) {
+    if (-not $emsdkRoot) { return $false }
+    if (-not (Test-Path $emsdkRoot)) { return $false }
+    $envScript = Join-Path $emsdkRoot 'emsdk_env.ps1'
+    if (-not (Test-Path $envScript)) { return $false }
+    Write-Host "Activating emsdk from $emsdkRoot ..."
+    try { & $envScript | Out-Null } catch { }
+    return [bool](Get-Command emcc -ErrorAction SilentlyContinue)
+}
+
+# --- Ensure emcc is available --------------------------------------------------
+if (-not (Get-Command emcc -ErrorAction SilentlyContinue)) {
+
+    # Candidate emsdk roots, in priority order. NONE is hardcoded as the only
+    # option: we search every common spot across drives so a build on a fresh PC
+    # finds an existing install wherever it was put. Add your own via $env:EMSDK.
+    $candidates = New-Object System.Collections.Generic.List[string]
+    if ($env:EMSDK) { [void]$candidates.Add($env:EMSDK) }
+    foreach ($p in @(
+        (Join-Path $env:USERPROFILE 'emsdk'),
+        (Join-Path $root '..\emsdk'),
+        (Join-Path $root '..\..\emsdk'),
+        'C:\emsdk', 'D:\emsdk', 'X:\emsdk',
+        (Join-Path $env:LOCALAPPDATA 'emsdk'),
+        (Join-Path ${env:ProgramFiles} 'emsdk')
+    )) { if ($p) { [void]$candidates.Add($p) } }
+
+    $activated = $false
+    foreach ($c in $candidates) {
+        if (Activate-Emsdk $c) { $activated = $true; break }
+    }
+
+    # Optional one-shot install (flag or env). Clones into %USERPROFILE%\emsdk.
+    if (-not $activated -and ($InstallEmsdk -or $env:TFS_INSTALL_EMSDK -eq '1')) {
+        $target = Join-Path $env:USERPROFILE 'emsdk'
+        if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+            Write-Error "Cannot auto-install emsdk: git is not on PATH. Install Git, or install emsdk manually."
+            exit 1
+        }
+        if (-not (Test-Path $target)) {
+            Write-Host "Cloning emsdk into $target ..." -ForegroundColor Cyan
+            & git clone --depth 1 https://github.com/emscripten-core/emsdk "$target"
+            if ($LASTEXITCODE -ne 0) { Write-Error "git clone of emsdk failed."; exit 1 }
+        }
+        Write-Host "Installing + activating emsdk 'latest' (one-time, downloads the toolchain) ..." -ForegroundColor Cyan
+        & (Join-Path $target 'emsdk.bat') install latest
+        if ($LASTEXITCODE -ne 0) { Write-Error "emsdk install failed."; exit 1 }
+        & (Join-Path $target 'emsdk.bat') activate latest
+        if ($LASTEXITCODE -ne 0) { Write-Error "emsdk activate failed."; exit 1 }
+        $activated = Activate-Emsdk $target
+    }
+
+    if (-not $activated) {
+        Write-Error @"
+emcc (Emscripten) not found. The WASM TMM kernel needs it to (re)build.
+
+A prebuilt src/tmm_kernel.wasm is committed to the repo, so the desktop
+build (npm run dist) will STILL succeed without emcc -- it just reuses that
+artifact. Only run this when you actually changed tmm_kernel.c.
+
+To build the kernel here, do ONE of:
+  * install emsdk and re-run with auto-detect:
+        .\src\build.ps1 -InstallEmsdk        (clones into %USERPROFILE%\emsdk)
+  * or install it yourself, then point at it:
+        `$env:EMSDK = 'C:\path\to\emsdk'; npm run build:wasm
+  * or just put the emsdk folder in one of: %USERPROFILE%\emsdk, C:\emsdk,
+    a sibling of the project, etc. (searched automatically).
+
+Searched: $($candidates -join '; ')
+"@
+        exit 1
+    }
+}
+
+# Each emcc flag is a quoted token. The EXPORTED_FUNCTIONS value contains commas;
+# unquoted, PowerShell parses them as its array operator and errors ("Missing
+# argument in parameter list"). Quoting passes the literal string through to emcc.
+$emccArgs = @(
+  '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'
+)
+& emcc @emccArgs
+
+Write-Host "Built src/tmm_kernel.wasm"
+node tests/equivalence.mjs

package/src/index.js

@@ -0,0 +1,35 @@
+/**
+ * tmmcore — transfer-matrix method for multilayer thin films.
+ *
+ * Two interchangeable implementations of the same physics:
+ *
+ *   • a JavaScript reference implementation, always available, no dependencies
+ *   • a C kernel compiled to WebAssembly, roughly an order of magnitude faster
+ *
+ * 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`.
+ *
+ * Conventions, which matter more than anything else here:
+ *   ñ = n + ik              k ≥ 0 for absorbing media
+ *   time factor exp(−iωt)
+ *   wavelengths and thicknesses in nm, angles in degrees from normal
+ *   complex numbers are [re, im] pairs
+ *   layers are ordered from the incident medium toward the substrate
+ *
+ * MIT licensed.
+ */
+
+export {
+    // Spectral quantities
+    tmm,
+    // Exact analytic derivatives
+    tmmThicknessJacobian,
+    tmmThicknessHessian,
+    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,
+} from './tmm.js';
+
+export * from './tmmWasm.js';