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

---

One simulation, three views: an aSi pillar metasurface, the resonant spectrum Ikarus computes for it, and the light trapped inside at resonance — about fifteen lines of Python end to end. (Build it yourself in Flight School.)

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 adjoint gradients (or a genetic algorithm, chosen automatically) sculpt 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 with one function call — adjoint gradients for freeform topology (thousands of pixels), a genetic algorithm for everything else, chosen automatically.

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)
Normal-vector factorization (Fast Fourier Factorization) — exact convergence on curved/oblique boundaries, on by default
Li inverse-rule + Laurent factorization — available explicitly
Adjoint (gradient-based) inverse design — freeform pixel maps to thousands of DOFs, min-feature fab filter, auto-selected
Gradient-free inverse design — parametric shapes, Structure, Pareto fronts (GA / NSGA-III)
Declarative parameter sweeps + progress bars (Sweep, progress)
Anisotropic (birefringent) materials — wave plates, c-plates, patterned birefringence
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 →