Plotting

metasurface_py.plotting

Plotting utilities for patterns, geometry, and results.

plot_convergence(data, ax=None, ylabel='Objective Value', **kwargs)

Plot optimization convergence curves.

Parameters:

Name	Type	Description	Default
data	dict[str, NDArray[floating[Any]]]	Dict mapping label to 1D array of objective values per iteration.	required
ax	Axes | None	Matplotlib axes. Created if None.	None
ylabel	str	Label for y-axis.	'Objective Value'
**kwargs	Any	Passed to ax.plot().	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_element_amplitude_phase(response, nx, ny, fig=None, **kwargs)

Plot amplitude and phase maps side by side.

Parameters:

Name	Type	Description	Default
response	NDArray[complexfloating[Any, Any]]	Complex element responses, shape (N,).	required
nx	int	Number of elements along x.	required
ny	int	Number of elements along y.	required
fig	Any | None	Matplotlib figure. Created if None.	None
**kwargs	Any	Passed to pcolormesh.	{}

Returns:

Type	Description
Any	The matplotlib Figure.

plot_gain_vs_frequency(data, ax=None, freq_unit='GHz', **kwargs)

Plot gain vs frequency for multiple configurations.

Parameters:

Name	Type	Description	Default
data	dict[str, list[tuple[float, float]]]	Dict mapping label to list of (freq, gain_dbi) tuples. Frequency values should match freq_unit.	required
ax	Axes | None	Matplotlib axes. Created if None.	None
freq_unit	str	Label for frequency axis (default "GHz").	'GHz'
**kwargs	Any	Passed to ax.plot().	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_gain_vs_scan_angle(data, ax=None, **kwargs)

Plot peak gain vs steering angle for multiple configurations.

Parameters:

Name	Type	Description	Default
data	dict[str, list[tuple[float, float]]]	Dict mapping label to list of (angle_deg, gain_dbi) tuples.	required
ax	Axes | None	Matplotlib axes. Created if None.	None
**kwargs	Any	Passed to ax.plot().	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_lattice(lattice, ax=None, **kwargs)

Plot element positions.

Parameters:

Name	Type	Description	Default
lattice	SupportsLattice	Lattice object.	required
ax	Axes | None	Matplotlib axes. Created if None.	None
**kwargs	Any	Passed to ax.scatter().	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_pattern_2d(pattern, cut_phi=0.0, ax=None, db=True, normalize=True, **kwargs)

Plot a 2D pattern cut (E-plane or H-plane).

Parameters:

Name	Type	Description	Default
pattern	DataArray	Far-field pattern with dims (theta, phi).	required
cut_phi	float	Phi value for the cut [rad].	0.0
ax	Axes | None	Matplotlib axes. Created if None.	None
db	bool	If True, plot in dB scale.	True
normalize	bool	If True, normalize to peak.	True
**kwargs	Any	Passed to ax.plot().	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_pattern_3d(pattern, ax=None, db=True, db_range=30.0, **kwargs)

Plot 3D radiation pattern on a sphere.

Parameters:

Name	Type	Description	Default
pattern	DataArray	Far-field pattern with dims (theta, phi).	required
ax	Any | None	Matplotlib 3D axes. Created if None.	None
db	bool	If True, use dB scale for radius.	True
db_range	float	Dynamic range in dB.	30.0
**kwargs	Any	Passed to ax.plot_surface().	{}

Returns:

Type	Description
tuple[Figure, Any]	Tuple of (Figure, Axes3D).

plot_pattern_comparison(patterns, cut_phi=0.0, ax=None, db=True, normalize=True, **kwargs)

Overlay multiple pattern cuts for comparison.

This is the most common figure in metasurface papers: continuous vs quantized, proposed vs baseline, simulated vs measured.

Parameters:

Name	Type	Description	Default
patterns	list[tuple[DataArray, str]]	List of (pattern, label) tuples.	required
cut_phi	float	Phi value for the cut [rad].	0.0
ax	Axes | None	Matplotlib axes. Created if None.	None
db	bool	If True, plot in dB scale.	True
normalize	bool	If True, normalize each to its own peak.	True
**kwargs	Any	Passed to each ax.plot() call.	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_pattern_polar(pattern, cut_phi=0.0, ax=None, db=True, db_range=40.0, **kwargs)

Plot a polar pattern cut.

Parameters:

Name	Type	Description	Default
pattern	DataArray	Far-field pattern with dims (theta, phi).	required
cut_phi	float	Phi value for the cut [rad].	0.0
ax	Axes | None	Polar matplotlib axes. Created if None.	None
db	bool	If True, plot in dB scale.	True
db_range	float	Dynamic range in dB for floor clipping.	40.0
**kwargs	Any	Passed to ax.plot().	{}

Returns:

Type	Description
Axes	The matplotlib Axes.

plot_pattern_uv(pattern, ax=None, db=True, db_range=40.0, **kwargs)

Plot pattern in u-v space as a filled contour.

Parameters:

Name	Type	Description	Default
pattern	DataArray	Far-field pattern with dims (theta, phi).	required
ax	Axes | None	Matplotlib axes. Created if None.	None
db	bool	If True, plot in dB scale.	True
db_range	float	Dynamic range for color scaling.	40.0
**kwargs	Any	Passed to ax.pcolormesh().	{}

Returns:

Type	Description
tuple[Axes, Any]	Tuple of (Axes, QuadMesh).

plot_state_map(state, nx, ny, ax=None, **kwargs)

Plot phase state as a 2D color map on the element grid.

Parameters:

Name	Type	Description	Default
state	SurfaceState	Surface state.	required
nx	int	Number of elements along x.	required
ny	int	Number of elements along y.	required
ax	Axes | None	Matplotlib axes. Created if None.	None
**kwargs	Any	Passed to ax.pcolormesh().	{}

Returns:

Type	Description
tuple[Axes, Any]	Tuple of (Axes, QuadMesh).

save_figure(fig, path, formats=('pdf', 'png'))

Save a figure in multiple formats for publication.

Parameters:

Name	Type	Description	Default
fig	Figure	Matplotlib figure to save.	required
path	str | Path	Base path without extension (e.g., "figures/pattern").	required
formats	tuple[str, ...]	File formats to save. Defaults to PDF (vector) + PNG (raster).	('pdf', 'png')

Returns:

Type	Description
list[Path]	List of saved file paths.

set_publication_style(target='ieee')

Apply publication-quality matplotlib rcParams.

Parameters:

Name	Type	Description	Default
target	Literal['ieee', 'ieee_double', 'nature', 'poster']	Publication target controlling figure size and font scaling. "ieee" — 3.5in single-column (default). "ieee_double" — 7in double-column. "nature" — 89mm single-column. "poster" — large format with scaled-up fonts.	'ieee'