Skip to content

metasurface-py

CI PyPI Python 3.11+ License: BSD-3 Streamlit

Open-source Python package for design, analysis, and optimization of electromagnetic metasurfaces for wireless communication and sensing: programmable reflecting surfaces (RIS/IRS), reflectarrays, and surface-wave-fed modulated metasurface (leaky-wave / holographic) antennas. Covers radiation patterns, RIS-assisted channel models, beamforming optimization under hardware constraints, and radar/localization metrics.

Installation

pip install metasurface-py

For development:

pip install -e ".[dev]"

Quickstart

import numpy as np
from metasurface_py.geometry import RectangularLattice
from metasurface_py.elements import PhaseOnlyCell, DiscretePhaseSpace
from metasurface_py.surfaces import Metasurface
from metasurface_py.em import steering_phase, far_field_pattern
from metasurface_py.core.types import AngleGrid
from metasurface_py.plotting import plot_pattern_2d

lattice = RectangularLattice(nx=32, ny=32, dx=5.4e-3, dy=5.4e-3)
cell = PhaseOnlyCell(state_space=DiscretePhaseSpace(num_bits=2))
surface = Metasurface(lattice=lattice, cell=cell, mode="reflect")

freq = 28e9
phase = steering_phase(lattice, theta_steer=np.radians(30), phi_steer=0.0, freq=freq)
state = surface.set_state(phase).quantize(cell.state_space.codebook)

angles = AngleGrid.from_degrees(theta=np.arange(-90, 91, dtype=float), phi=np.array([0.0, 90.0]))
pattern = far_field_pattern(surface, state, freq=freq, angles=angles)
plot_pattern_2d(pattern, cut_phi=0.0)

Features

  • Metasurface modeling — Rectangular/hexagonal lattices, phase-only and lookup-table unit cells, amplitude-phase coupled elements
  • Far-field analysis — Array factor, directivity, sidelobe level, HPBW, beam steering, focusing, multi-beam synthesis
  • Optimization — Continuous (L-BFGS-B, DE), discrete refinement, relax-then-quantize pipeline, multi-objective Pareto sweeps
  • Hardware constraints — Phase quantization, grouped control lines, dead elements, manufacturing noise
  • RIS channel models — Free-space path loss, narrowband SISO RIS-assisted links, optimal phase computation
  • Modulated MTS antennas — Surface-wave-fed leaky-wave apertures: TM surface-wave dispersion, Oliner–Hessel modulated-reactance solver, adiabatic Floquet-mode aperture fields, CP far fields (model documentation)
  • Sensing — Monostatic/bistatic RCS, detection SNR, Fisher information, CRLB for localization
  • Mutual coupling — Canonical dipole coupling approximation
  • Publication-quality plotting — 13+ plot functions, IEEE/Nature/poster presets, colorblind-safe palettes, PDF/PNG export
  • Experiment management — TOML configs, parameter sweeps, reproducibility metadata
  • Interoperability — CSV/HDF5/Touchstone import, scikit-rf adapter, xarray labeled outputs

Tutorials

Interactive Jupyter notebooks that run in Google Colab (no install required):

Notebook Description Colab
01 Getting Started Create a metasurface, steer a beam, compare quantization Open In Colab
02 Optimization Relax-then-quantize with hardware constraints Open In Colab
03 RIS Link RIS-assisted communication link, N² scaling Open In Colab
04 Sensing & ISAC Radar detection, localization CRLB, comms-sensing tradeoff Open In Colab

Examples

Runnable scripts in examples/, including reproductions of published results:

Script Description
01 Beam steering Steer a beam, compare 1/2/3-bit phase quantization
02 Gain vs scan angle Scan-loss sweep
03 Near-field focusing Spherical-wave focusing phase profile
04 Multi-beam Dual-beam synthesis
05 Optimized steering Beam optimization under hardware constraints
06 RIS link RIS-assisted communication link budget
07 Wu & Zhang 2019 Reproduces "Intelligent Reflecting Surface Enhanced Wireless Network" (IEEE TWC 2019): N² SNR scaling, coverage extension
08 Basar et al. 2019 Reproduces "Wireless Communications Through Reconfigurable Intelligent Surfaces" (IEEE Access 2019): scaling law, path loss, coverage
09 Faenzi et al. 2019 Reproduces "Metasurface Antennas: New Models, Applications and Realizations" (Sci. Rep. 2019): leaky-wave dispersion, RHCP patterns, bandwidth — see Modulated MTS Antennas

Citation

If you use metasurface-py in your research, please cite:

@software{metasurface_py,
  author       = {Hodge, John},
  title        = {metasurface-py: Design, analysis, and optimization of programmable electromagnetic metasurfaces},
  year         = {2026},
  url          = {https://github.com/jman4162/metasurface-py},
  version      = {0.3.0},
  license      = {BSD-3-Clause},
}

License

BSD-3-Clause