Optimize

metasurface_py.optimize

Optimization module for metasurface phase configuration.

MaxCapacityObjective dataclass

Maximize MIMO capacity for an RIS-assisted link.

Returns negative capacity (for minimization).

Parameters:

Name	Type	Description	Default
mimo_link	Any	MIMORISLink instance.	required
snr_linear	float	Total SNR (linear).	100.0

__call__(state, surface, freq, **kwargs)

Evaluate: returns negative capacity.

MaxGainObjective dataclass

Maximize directivity in a target direction.

Returns negative gain (for minimization).

Parameters:

Name	Type	Description	Default
target_theta	float	Target polar angle [rad].	required
target_phi	float	Target azimuthal angle [rad].	required
angles	AngleGrid	Observation angle grid for pattern evaluation.	required

__call__(state, surface, freq, **kwargs)

Evaluate: returns negative peak gain (minimize this).

MinSidelobeObjective dataclass

Minimize peak sidelobe level.

Returns positive SLL (in dB, closer to 0 is worse).

Parameters:

Name	Type	Description	Default
target_theta	float	Main beam polar angle [rad].	required
target_phi	float	Main beam azimuthal angle [rad].	required
angles	AngleGrid	Observation angle grid.	required
exclusion_radius	float	Angular exclusion around main beam [rad].	0.15

__call__(state, surface, freq, **kwargs)

Evaluate: returns negative SLL (minimize for lower sidelobes).

OptimizationResult dataclass

Result of a metasurface optimization run.

Parameters:

Name	Type	Description	Default
state	SurfaceState	Final optimized surface state.	required
state_continuous	SurfaceState | None	Pre-quantization continuous state (if applicable).	None
objective_value	float	Final objective function value.	0.0
convergence_history	NDArray[floating[Any]]	Objective value per iteration.	(lambda: array([], dtype=float64))()
runtime_seconds	float	Wall-clock time for optimization.	0.0
method	str	Name of the optimization method used.	''
config	dict[str, Any]	Frozen dict of all optimization parameters.	dict()

ParetoResult dataclass

Result of a Pareto sweep.

Parameters:

Name	Type	Description	Default
states	list[SurfaceState]	List of Pareto-optimal surface states.	required
objective_values	NDArray[floating[Any]]	(n_points, 2) array of objective values.	required
weights	NDArray[floating[Any]]	(n_points,) array of alpha weights used.	required
obj_a_name	str	Name of first objective.	'Objective A'
obj_b_name	str	Name of second objective.	'Objective B'

WeightedGainSidelobeObjective dataclass

Weighted combination of gain and sidelobe level.

objective = alpha * (-gain_dBi) + (1-alpha) * (-SLL_dB)

Lower is better for both terms.

Parameters:

Name	Type	Description	Default
target_theta	float	Target beam direction [rad].	required
target_phi	float	Target beam azimuthal angle [rad].	required
angles	AngleGrid	Observation angle grid.	required
alpha	float	Weight for gain term (0 to 1). Default 0.7.	0.7
exclusion_radius	float	SLL exclusion radius [rad].	0.15

__call__(state, surface, freq, **kwargs)

Evaluate weighted objective.

optimize_continuous(objective, surface, freq, angles, method='L-BFGS-B', x0=None, maxiter=200, seed=None, **scipy_kwargs)

Optimize continuous phase values using SciPy.

Parameters:

Name	Type	Description	Default
objective	Callable[[NDArray[floating[Any]], Metasurface, float], float]	Callable(state, surface, freq) -> float to minimize.	required
surface	Metasurface	Metasurface object.	required
freq	float	Frequency [Hz].	required
angles	AngleGrid	Observation angles (passed through for reference).	required
method	Literal['L-BFGS-B', 'differential_evolution']	"L-BFGS-B" (local) or "differential_evolution" (global).	'L-BFGS-B'
x0	NDArray[floating[Any]] | None	Initial phase values [rad]. Random if None.	None
maxiter	int	Maximum iterations.	200
seed	int | None	Random seed for reproducibility.	None
**scipy_kwargs	Any	Additional kwargs for the SciPy optimizer.	{}

Returns:

Type	Description
OptimizationResult	OptimizationResult with optimized continuous state.

pareto_sweep(objective_a, objective_b, surface, freq, angles, n_points=11, maxiter=100, seed=42, obj_a_name='Objective A', obj_b_name='Objective B')

Generate Pareto front via weighted scalarization.

Sweeps alpha from 0 to 1, optimizing: objective = alpha * obj_a + (1 - alpha) * obj_b

Parameters:

Name	Type	Description	Default
objective_a	Any	First objective callable.	required
objective_b	Any	Second objective callable.	required
surface	Metasurface	Metasurface object.	required
freq	float	Frequency [Hz].	required
angles	AngleGrid	Observation angles.	required
n_points	int	Number of Pareto points.	11
maxiter	int	Max iterations per point.	100
seed	int	Random seed.	42
obj_a_name	str	Label for first objective.	'Objective A'
obj_b_name	str	Label for second objective.	'Objective B'

Returns:

Type	Description
ParetoResult	ParetoResult with states and objective values.

refine_discrete(objective, surface, state, freq, angles, max_sweeps=3)

Refine a discrete state via coordinate descent.

For each element, tries all codebook entries and keeps the best. Repeats for max_sweeps passes.

Parameters:

Name	Type	Description	Default
objective	Callable[[NDArray[floating[Any]], Metasurface, float], float]	Callable(state, surface, freq) -> float to minimize.	required
surface	Metasurface	Metasurface object.	required
state	SurfaceState	Initial discrete surface state.	required
freq	float	Frequency [Hz].	required
angles	AngleGrid	Observation angles (for reference).	required
max_sweeps	int	Number of full sweeps over all elements.	3

Returns:

Type	Description
OptimizationResult	OptimizationResult with refined discrete state.

relax_then_quantize(objective, surface, freq, angles, continuous_method='L-BFGS-B', refine=True, maxiter=200, seed=None)

Optimize via relax-then-quantize pipeline.

1. Optimize continuous phases
2. Quantize to the surface's discrete codebook
3. Optionally refine with coordinate descent

This is the standard approach in metasurface optimization literature and the recommended default workflow.

Parameters:

Name	Type	Description	Default
objective	Callable[[NDArray[floating[Any]], Metasurface, float], float]	Callable(state, surface, freq) -> float to minimize.	required
surface	Metasurface	Metasurface object.	required
freq	float	Frequency [Hz].	required
angles	AngleGrid	Observation angle grid.	required
continuous_method	Literal['L-BFGS-B', 'differential_evolution']	Method for continuous optimization.	'L-BFGS-B'
refine	bool	Whether to apply discrete refinement after quantization.	True
maxiter	int	Max iterations for continuous optimization.	200
seed	int | None	Random seed.	None

Returns:

Type	Description
OptimizationResult	OptimizationResult with final state and full history.