Merge pull request #8 from QuentinWach/windows

[Windows Release]: Add platform support and documentation

Author: QuentinWach

.gitattributes

@@ -0,0 +1,2 @@
+fixtures/mode_solver/**/*.json text eol=lf
+fixtures/mode_solver/**/*.hdf5 binary

.github/workflows/publish.yml

@@ -47,7 +47,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-15-intel, macos-15]
+        os: [ubuntu-latest, macos-15-intel, macos-15, windows-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
@@ -60,16 +60,25 @@ jobs:
         run: uv python install ${{ matrix.python-version }}
 
       - name: Build wheel
+        shell: bash
         run: |
+          extra_args=()
+          if [[ "${{ runner.os }}" == "Linux" ]]; then
+            extra_args+=(--auditwheel repair)
+          fi
+
           uv tool run --from "maturin>=1.7,<2" maturin build \
             --release \
             --out dist \
             --interpreter "$(uv python find ${{ matrix.python-version }})" \
             --compatibility pypi \
-            --auditwheel repair
+            "${extra_args[@]}"
 
       - name: Smoke-test wheel
-        run: PYTHON="$(uv python find ${{ matrix.python-version }})" ./scripts/smoke_dist.sh
+        shell: bash
+        run: |
+          python_bin="$(uv python find ${{ matrix.python-version }})"
+          "$python_bin" scripts/smoke_dist.py --python "$python_bin"
 
       - name: Upload wheel
         uses: actions/upload-artifact@v4
@@ -106,7 +115,7 @@ jobs:
           python scripts/check_release_metadata.py
           python scripts/check_dist_artifacts.py dist \
             --require-cpython 3.10 3.11 3.12 3.13 \
-            --require-platform macosx manylinux
+            --require-platform macosx manylinux win
           twine check dist/*
 
       - name: Upload checked distributions

.github/workflows/tests.yml

@@ -47,7 +47,7 @@ jobs:
 
       - name: Smoke-test wheel
         if: matrix.python-version == '3.13'
-        run: PYTHON="$(uv python find ${{ matrix.python-version }})" ./scripts/smoke_dist.sh
+        run: uv run python scripts/smoke_dist.py --python "$(uv python find ${{ matrix.python-version }})"
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
@@ -84,3 +84,36 @@ jobs:
 
       - name: Run Rust tests
         run: cargo test --no-default-features
+
+  test-windows:
+    name: Windows portable tests
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build extension
+        run: uv run maturin develop
+
+      - name: Run Python tests
+        run: uv run pytest -m "not slow"
+
+      - name: Run Rust tests
+        run: cargo test --no-default-features
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test wheel
+        run: uv run python scripts/smoke_dist.py --python "$(uv python find 3.13)"

README.md

@@ -1,6 +1,7 @@
 # micromode
 
-A minimal FDFD electromagnetic mode solver for rasterized waveguide cross sections with a Rust core made to be a standard plugin for FDTD engines.
+A high-performance electromagnetic mode solver.
+It uses the FDFD method on a regular Yee-grid and is written in native Rust.
 
 [![License](https://img.shields.io/github/license/QuentinWach/micromode)](LICENSE)
 [![Tests](https://img.shields.io/github/actions/workflow/status/QuentinWach/micromode/tests.yml?branch=main&label=tests)](https://github.com/QuentinWach/micromode/actions/workflows/tests.yml)
@@ -10,73 +11,21 @@ A minimal FDFD electromagnetic mode solver for rasterized waveguide cross sectio
 pip install micromode
 ```
 
-## Supported Platforms
-
-The Python package uses the portable Rust sparse backend. It does not require
-external native sparse-solver libraries at install time.
-
-Published wheels are built for:
-
-- Linux, CPython 3.10-3.13
-- macOS Intel and Apple Silicon, CPython 3.10-3.13
-
-Source builds should work on platforms with a supported Rust toolchain and
-Python 3.10-3.13. Windows source builds use the same portable backend, but
-Windows wheels are not release-tested yet.
-
-## Source Builds
-
-For the portable backend, install Rust and build normally:
-
-```bash
-pip install .
-```
-
-or, for local development:
-
-```bash
-uv sync --all-extras
-uv run maturin develop
-```
-
-## Performance
-
-MicroMode is designed to make high-performance mode solving available without
-requiring users to install external solver stacks. The production backend is a
-portable Rust sparse shift-invert eigensolver, so source installs and wheels do
-not depend on ARPACK, UMFPACK, SuiteSparse, BLAS/LAPACK, or a Fortran compiler.
-That matters for simulation workflows that need to run in CI, notebooks,
-container images, FDTD plugins, and cross-platform design tools.
-
-The native solver is not a dense fallback. It uses sparse finite-difference
-operators throughout, applies AMD fill-reducing ordering before sparse LU
-factorization, stores LU factors in a packed format for repeated triangular
-solves, and runs an Arnoldi iteration targeted around the requested effective
-index. The Arnoldi stage uses shift-invert, adaptive Ritz-pair checkpointing,
-early stopping once requested modes are stable, and selective Ritz vector
-reconstruction so work is spent on the modes that will actually be returned.
-
-On the repository benchmark problem, the pure Rust backend solves larger grids
-in the same performance class as the previous optional UMFPACK-backed path while
-remaining much easier to install and distribute. For example, a release build on
-an Apple Silicon development machine solves an `80x50` diagonal benchmark grid
-in roughly `90 ms` for two modes with residuals around `1e-12`. Exact timings
-depend on hardware and problem shape, but the important point is architectural:
-MicroMode keeps the deployability of a pure Rust package without giving up the
-sparse-solver performance expected for practical waveguide grids.
 
 ## Why Use It?
 
-- Grid-first API: pass arrays directly, with no required geometry model.
-- Fast, portable Rust sparse backend: one production solve path.
-- Practical outputs: fields, `n_eff`, `k_eff`, mode area, polarization fractions,
+- **Grid-first API**: pass arrays directly, with no required geometry model.
+- **Fast**, portable Rust sparse backend: one production solve path.
+- **Practical** outputs: fields, `n_eff`, `k_eff`, mode area, polarization fractions,
   Lorentz overlaps, plotting, dataframe export, and HDF5 save/load.
-- Tensor-aware: supports scalar, diagonal anisotropic, and full tensor material
+- **Tensor-aware**: supports scalar, diagonal anisotropic, and full tensor material
   grids.
-- Works for both 2D cross sections and 1D slices.
+- Works for both **2D cross sections and 1D slices**.
 
 You give it a material grid. It returns guided modes: effective indices, six-component fields, polarization metrics, mode area, overlaps, diagnostics, plots, and HDF5 output. MicroMode is intentionally not a CAD or geometry package. It is the solver piece you use after geometry has already been rasterized onto a mode-plane grid.
 
+_Micromode is the **default mode solver** in the [BEAMZ FDTD engine](https://github.com/beamzorg/beamz)._
+
 
 ## Quick Start
 
@@ -106,3 +55,44 @@ print(data.n_eff.values)
 data.plot_field("Ex", mode_index=0)
 data.to_hdf5("modes.h5")
 ```
+
+
+## High Performance
+
+MicroMode is designed to make high-performance mode solving available without
+requiring users to install external solver stacks. The production backend is a
+**portable Rust [sparse](https://en.wikipedia.org/wiki/Sparse_matrix)
+[shift-invert](https://en.wikipedia.org/wiki/Preconditioner#Spectral_transformation)
+[eigensolver](https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors)**, so
+source installs and wheels do **not** depend on
+[ARPACK](https://en.wikipedia.org/wiki/ARPACK),
+[UMFPACK](https://en.wikipedia.org/wiki/UMFPACK),
+[SuiteSparse](https://en.wikipedia.org/wiki/SuiteSparse),
+[BLAS](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms)/
+[LAPACK](https://en.wikipedia.org/wiki/LAPACK), or a Fortran compiler.
+That matters for simulation workflows that need to run in CI, notebooks,
+container images, FDTD plugins, and cross-platform design tools.
+
+The native solver is **not a dense fallback**. It uses
+[sparse](https://en.wikipedia.org/wiki/Sparse_matrix)
+[finite-difference](https://en.wikipedia.org/wiki/Finite_difference_method)
+operators throughout, applies
+[AMD fill-reducing ordering](https://en.wikipedia.org/wiki/Minimum_degree_algorithm)
+before sparse [LU factorization](https://en.wikipedia.org/wiki/LU_decomposition),
+stores LU factors in a packed format for repeated triangular solves, and runs an
+[Arnoldi iteration](https://en.wikipedia.org/wiki/Arnoldi_iteration) targeted
+around the requested effective index. The Arnoldi stage uses
+**shift-invert**, adaptive
+[Ritz-pair](https://en.wikipedia.org/wiki/Ritz_method) checkpointing, early
+stopping once requested modes are stable, and selective Ritz vector
+reconstruction so work is spent on the modes that will actually be returned.
+
+On the repository benchmark problem, the **pure Rust backend** solves larger grids
+in the same performance class as the previous optional UMFPACK-backed path while
+remaining much easier to install and distribute. For example, a release build on
+an Apple Silicon development machine solves an `80x50` diagonal benchmark grid
+in roughly **`90 ms` for two modes** with residuals around **`1e-12`**. Exact
+timings depend on hardware and problem shape, but the important point is
+architectural: MicroMode keeps the **deployability of a pure Rust package**
+without giving up the sparse-solver performance expected for practical
+waveguide grids.

docs/release.md

@@ -71,6 +71,5 @@ checks metadata, and publishes to PyPI using Trusted Publishing.
 
 ## Current Wheel Scope
 
-The release workflow builds macOS and Linux wheels for Python 3.10 through
-3.13. Windows wheels are intentionally not enabled yet; add Windows once the
-portable backend has release coverage on that target.
+The release workflow builds Linux, macOS, and Windows wheels for Python 3.10
+through 3.13.

pyproject.toml

@@ -25,6 +25,9 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Rust",
+  "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
   "Topic :: Scientific/Engineering",
   "Topic :: Scientific/Engineering :: Physics",
 ]

scripts/check_release_metadata.py

@@ -43,7 +43,11 @@ def main() -> None:
         )
     require("--compatibility pypi" in publish_workflow, "publish workflow must request PyPI-compatible wheels")
     require("--auditwheel repair" in publish_workflow, "Linux release wheels must be auditwheel-repaired")
-    require("--require-platform macosx manylinux" in publish_workflow, "release artifact check must require macOS and manylinux wheels")
+    require("windows-latest" in publish_workflow, "publish workflow is missing Windows wheel builds")
+    require(
+        "--require-platform macosx manylinux win" in publish_workflow,
+        "release artifact check must require macOS, manylinux, and Windows wheels",
+    )
 
     changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
     require(project["version"] in changelog, "Python version is not mentioned in CHANGELOG.md")

scripts/smoke_dist.py

@@ -0,0 +1,66 @@
+"""Smoke-test a built wheel in a fresh virtual environment."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "wheel",
+        nargs="?",
+        help="Wheel to install; defaults to the newest matching dist/micromode-*.whl",
+    )
+    parser.add_argument(
+        "--python",
+        default=os.environ.get("PYTHON", sys.executable),
+        help="Python executable used to create the temporary virtual environment",
+    )
+    args = parser.parse_args()
+
+    wheel = Path(args.wheel).resolve() if args.wheel else latest_wheel(python_tag(args.python))
+    with tempfile.TemporaryDirectory() as tmp:
+        venv_dir = Path(tmp) / "venv"
+        run([args.python, "-m", "venv", str(venv_dir)])
+        venv_python = venv_dir / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+        run([str(venv_python), "-m", "pip", "install", "--upgrade", "pip"])
+        run([str(venv_python), "-m", "pip", "install", str(wheel)])
+        run([str(venv_python), str(ROOT / "scripts/smoke_wheel.py")])
+
+
+def latest_wheel(required_tag: str) -> Path:
+    wheels = sorted(
+        (ROOT / "dist").glob(f"micromode-*-{required_tag}-*.whl"),
+        key=lambda path: path.stat().st_mtime,
+        reverse=True,
+    )
+    if not wheels:
+        raise SystemExit(f"no {required_tag} wheel found in dist/")
+    return wheels[0].resolve()
+
+
+def python_tag(python: str) -> str:
+    command = [
+        python,
+        "-c",
+        "import sys; print(f'cp{sys.version_info.major}{sys.version_info.minor}')",
+    ]
+    result = subprocess.run(command, check=True, capture_output=True, text=True)
+    return result.stdout.strip()
+
+
+def run(command: list[str]) -> None:
+    subprocess.run(command, check=True)
+
+
+if __name__ == "__main__":
+    main()

scripts/smoke_dist.sh

@@ -2,15 +2,10 @@
 set -euo pipefail
 
 wheel="${1:-}"
-if [[ -z "$wheel" ]]; then
-  wheel="$(ls -t dist/micromode-*.whl | head -n 1)"
-fi
 python_bin="${PYTHON:-python}"
 
-tmpdir="$(mktemp -d)"
-trap 'rm -rf "$tmpdir"' EXIT
-
-"$python_bin" -m venv "$tmpdir/venv"
-"$tmpdir/venv/bin/python" -m pip install --upgrade pip
-"$tmpdir/venv/bin/python" -m pip install "$wheel"
-"$tmpdir/venv/bin/python" scripts/smoke_wheel.py
+if [[ -n "$wheel" ]]; then
+  "$python_bin" scripts/smoke_dist.py --python "$python_bin" "$wheel"
+else
+  "$python_bin" scripts/smoke_dist.py --python "$python_bin"
+fi