Skip to content

Fly closer to the sun

Ikarus is a high-precision RCWA engine for periodic photonics — metasurfaces, gratings and photonic crystals — with machine-precision validation, real-space field maps and inverse design built in. Pure NumPy/SciPy. No mesh. No time stepping. Just light, decomposed.

Take your first flight How RCWA works API reference

import numpy as np
from ikarus import RCWA

rcwa = RCWA(period_x=1e-6, period_y=1e-6, resolution=64, n_orders=15)
rcwa.add_uniform_layer(height=np.inf, material="Air")    # the sky
rcwa.add_uniform_layer(height=200e-9, material="Si")     # the obstacle
rcwa.add_uniform_layer(height=np.inf, material="SiO2")   # the landing zone
rcwa.set_source(wavelength=1550e-9, theta=0, polarization="linear")

T, R, result = rcwa.simulate()
print(f"R = {result.R_total:.4f}  T = {result.T_total:.4f}  "
      f"R+T = {result.energy_balance:.6f}")   # the books always balance

~10⁻¹⁵agreement with analytic Fresnel

1.5–1.7×faster than grcwa, head-to-head

9dispersive materials built in

1pip install, zero config

Metasurface dispersion fingerprint
A TiO₂ metasurface's angle–wavelength reflectance fingerprint — Rayleigh–Wood anomalies and all — computed in seconds. (See [Flight School, Lesson 6](tutorials/angular-response.md).)

Pick your runway

  • Five minutes to first photon

    Install with pip, build a three-layer stack, get reflectance, transmittance and phase — with every input explained.

    Quick Start

  • Understand the machine

    RCWA explained like you're a photon: harmonics as exit lanes, layers with natural gaits, scattering matrices whose wax never melts.

    How RCWA Works

  • Flight School

    Six hands-on lessons: spectra, gratings, metasurfaces, sweeps, polarization and oblique incidence. All copy-paste runnable.

    Tutorials

  • Let the machine design for you

    Declare what you want — "minimize reflection from 300 to 600 nm" — and a genetic algorithm sculpts the metaatom. Three lines of intent.

    Inverse Design

Why Ikarus exists

Most research RCWA codes are either terse academic scripts (fast, but you need the author in the room to modify them) or heavyweight frameworks (powerful, but the setup costs a weekend). Ikarus aims for the missing third thing:

  • A readable, decomposed engine. The numerically heavy core is stateless and lives apart from the user-facing façade, the material database and the Fourier machinery. Every piece is independently testable — and tested.
  • Correctness you can audit. A validation suite checks the engine against the analytic Fresnel solution (to ~10⁻¹⁵) and an independent mode-matching reference. Energy is conserved to ~10⁻⁹ for lossless gratings.
  • An API that respects your time. Full per-order, vectorial results — efficiencies, complex amplitudes, exit angles, fields — without ceremony.
  • Inverse design in the box. The same metaatom you simulate forward can be optimized backward, gradient-free, with one function call.

Myth break — why \"Ikarus\"?

In the myth, Ikaros strapped on wings of wax and feathers, ignored the flight envelope, and performed an unscheduled rapid disassembly over the Aegean. Our Ikarus is built differently: the scattering-matrix cascade is unconditionally stable — thick layers, evanescent waves, lossy metals — crank them all you like. The wax doesn't melt. (Transfer-matrix codes, on the other hand… see the Theory chapter.)

What's in the toolbox

Capability Status
2-D periodic structures (crossed gratings, metasurfaces)
Pixel-map topologies + shape primitives (circle, ring, polygon, …)
Linear polarization (any angle), oblique incidence
Circular polarization with co/cross-pol decomposition
All diffraction orders with exit angles
Dispersive material database (Si, SiO₂, TiO₂, GaN, GaP, aSi, Au, Si₃N₄, Air)
Custom materials from CSV (n, k) or a Lorentz model
Real-space field reconstruction (xy / xz / yz planes)
Structure & field visualization (matplotlib)
Automatic convergence testing (never / once / always)
HDF5 export / import of results
Numerically stable S-matrix cascade (no transfer-matrix overflow)
Gradient-free inverse design (pixels, parametric shapes, GA / NSGA-III via pymoo)
Declarative parameter sweeps + progress bars (Sweep, progress)
Anisotropic (3×3 tensor) materials on the roadmap
Li inverse-rule factorization (faster TM convergence) Laurent rule only
GPU acceleration CPU (NumPy/SciPy) only

Sixty seconds of metasurface

A square lattice of TiO₂ disks on glass — the classic metasurface building block:

import numpy as np
from ikarus import RCWA, shapes

period = 500e-9
disk = shapes.circle(center=(0.5, 0.5), radius=0.3, grid_shape=(128, 128))

rcwa = RCWA(period_x=period, period_y=period, resolution=(128, 128), n_orders=(10, 10))
rcwa.add_uniform_layer(np.inf, "Air")
rcwa.add_layer(220e-9, disk, ["Air", "TiO2"])   # topology 0 -> Air, 1 -> TiO2
rcwa.add_uniform_layer(np.inf, "SiO2")
rcwa.set_source(wavelength=600e-9, theta=0, polarization="linear")

T, R, result = rcwa.simulate()
print(f"T = {result.T_total:.3f}")
print(f"specular (0,0) order = {result.T_orders[result.order_index(0, 0)]:.3f}")

Want the full show — structure plots, field maps, spectra, circular polarization, HDF5? One command:

python -m ikarus.examples.feature_tour

Ready for takeoff?   Strap on the wings →