tidy3d.plugins.autograd.optimizers.optimize

class optimize

Bases:

Run a full gradient-descent optimization loop (convenience wrapper).

This is a thin convenience wrapper around the optax-style stepping API provided by this module (no optax dependency required). It is not intended to grow into a full optimization framework — for advanced use cases (custom stopping criteria, checkpointing, schedulers, DRC-aware updates, etc.) use the lower-level optimizer.init / optimizer.update / apply_updates interface directly.

Uses autograd.value_and_grad to compute gradients of objective_fn at each step, then updates parameters using the provided optimizer.

Parameters:

• objective_fn (Callable[[Params], Union[float, np.ndarray]]) – Scalar-valued objective function evaluated on the current parameters. It must accept the same parameter structure as params0 and return a differentiable scalar (Python float or scalar np.ndarray) that autograd.value_and_grad can handle.

• params0 (np.ndarray, float, or dict) – Initial parameter values as a single array, a scalar, or a dict of arrays/scalars.

• optimizer (Adam) – Optimizer instance that provides .init() and .update() methods.

• num_steps (int) – Number of optimization steps to run.

• bounds (tuple or dict, optional) – Parameter bounds applied after each update step. For array params: a (lo, hi) tuple where None disables a side. For dict params: a dict mapping parameter keys to (lo, hi) tuples. Keys absent from the dict are left unclipped.

• callback (Optional[Callable[[Params, Params, AdamState, int, Union[float, np.ndarray]], None]]) – If provided, called each step before the parameter update as callback(params, grad, state, step_index, objective_val). All arguments reflect the pre-update state of the current iterate, and grad / objective_val are the raw outputs of objective_fn before any min/max direction handling. The final (post-loop) params are available in the return value.

• direction ({"min", "max"} = "min") – Optimization direction. "min" performs gradient descent on objective_fn. "max" performs gradient ascent by negating the gradient passed to the optimizer while still recording the raw objective values in history["objective_fn_val"].

Returns:

(params, state, history) where history is a dict with keys "objective_fn_val" and "grad_norm", each a list of per-step values of the raw objective and raw gradient norm, respectively.

Return type:

tuple