thin_film.optimization.optimizer

Thin Film Optimizer Module

This module contains the ThinFilmOptimizer class, which provides a high-level interface for optimizing thin film stacks. It creates its own optimization framework specifically designed for thin film applications.

Corentin Nannini, 2025

Classes

StackSnapshot(thicknesses_um)	Minimal stack snapshot kept for reset and future tolerance workflows.
ThinFilmOptimizer(stack)	High-level interface for optimizing thin film stacks.
VariableInfo(variable, min_val, max_val, ...)	Information about an optimization variable.

class StackSnapshot(thicknesses_um: list[float])

Minimal stack snapshot kept for reset and future tolerance workflows.

classmethod capture(stack: ThinFilmStack) → StackSnapshot

restore(stack: ThinFilmStack) → None

thicknesses_um: list[float]

class ThinFilmOptimizer(stack: ThinFilmStack)

High-level interface for optimizing thin film stacks.

This class provides a fluent API for setting up and running optimizations on thin film stacks. It handles the conversion between different units and provides its own optimization framework.

add_angular_operand(property: str, wavelength_nm: float, aoi_deg_range: list[float], target_type: str, value: float | list[float], weight: float = 1.0, polarization: str = 's') → ThinFilmOptimizer

Convenience method to add an angular operand with multiple AOI values.

Parameters:

• property – Property to optimize (“R”, “T”, “A”).

• wavelength_nm – Single wavelength value in nm.

• aoi_deg_range – List of angles of incidence in degrees.

• target_type – Type of target (“equal”, “over”, “below”).

• value – Target value(s). Single value or list matching aoi_deg_range length.

• weight – Operand weight for optimization. Defaults to 1.0.

• polarization – Polarization state (“s”, “p”, “u”). Defaults to “s”.

Returns:

self for method chaining.

Return type:

ThinFilmOptimizer

Example

>>> optimizer.add_angular_operand(
...     property="R",
...     wavelength_nm=550.0,
...     aoi_deg_range=[0.0, 20.0, 40.0, 60.0],
...     target_type="below",
...     value=[0.08, 0.10, 0.14, 0.20],
...     polarization="s",
... )

add_interpolated_operand(property: str, wavelength_nm: list[float], target_type: str, value: list[float], weight: float = 1.0, aoi_deg: float = 0.0, polarization: str = 's') → ThinFilmOptimizer

Convenience method to add an interpolated spectral operand.

Parameters:

• property – Property to optimize (“R”, “T”, “A”).

• wavelength_nm – List of wavelength values in nm.

• target_type – Type of target (“equal”, “over”, “below”).

• value – List of target values matching wavelength_nm length.

• weight – Operand weight for optimization. Defaults to 1.0.

• aoi_deg – Angle of incidence in degrees. Defaults to 0.0.

• polarization – Polarization state (“s”, “p”, “u”). Defaults to “s”.

Returns:

self for method chaining.

Return type:

ThinFilmOptimizer

Example

>>> optimizer.add_interpolated_operand(
...     property="T",
...     wavelength_nm=[450.0, 550.0, 650.0],
...     target_type="equal",
...     value=[0.88, 0.94, 0.89],
...     aoi_deg=0.0,
...     polarization="u",
... )

add_operand(property: str | None = None, wavelength_nm: float | list[float] | None = None, target_type: Literal['equal', 'below', 'over'] | None = None, value: float | list[float] | None = None, weight: float = 1.0, aoi_deg: float | list[float] = 0.0, polarization: str = 'u', tolerance: float = 1e-06, target: float | None = None, min_val: float | None = None, max_val: float | None = None, input_data: dict[str, Any] | None = None, label: str | None = None, operand_type: str | None = None) → ThinFilmOptimizer

Add an optimization operand.

Parameters:

• property – Operand key. Built-ins are ‘R’, ‘T’, and ‘A’. Any registered operand key is also accepted.

• operand_type – Alias of property. Useful for explicit custom calls.

• wavelength_nm – Wavelength(s) in nanometers for spectral R/T/A operands. Can be scalar or array.

• target_type – Type of target (‘equal’, ‘below’, ‘over’) for spectral R/T/A operands.

• value – Target value(s) for spectral R/T/A operands. Can be scalar or array for interpolation.

• weight – Weight for this operand. Defaults to 1.0.

• aoi_deg – Angle(s) of incidence in degrees for spectral R/T/A operands. Can be scalar or array. Defaults to 0.0.

• polarization – Polarization state (‘s’, ‘p’, ‘u’) for spectral R/T/A operands. Defaults to ‘u’.

• tolerance – Tolerance for ‘equal’ spectral targets. Defaults to 1e-6.

• target – Equality target for custom registered operands.

• min_val – Lower inequality bound for custom registered operands.

• max_val – Upper inequality bound for custom registered operands.

• input_data – Input dictionary for custom registered operands.

• label – Optional display label for custom registered operands.

Returns:

self for method chaining.

Raises:

ValueError – If inputs are invalid for the chosen operand mode.

Examples

Built-in spectral operand at a single wavelength and angle:

>>> optimizer.add_operand(
...     property="R",
...     wavelength_nm=550.0,
...     target_type="below",
...     value=0.05,
...     aoi_deg=0.0,
...     polarization="s",
... )

Built-in spectral operand over a wavelength range:

>>> optimizer.add_operand(
...     property="T",
...     wavelength_nm=[450.0, 550.0, 650.0],
...     target_type="equal",
...     value=[0.90, 0.95, 0.90],
...     aoi_deg=0.0,
...     polarization="u",
... )

Built-in angular operand at fixed wavelength:

>>> optimizer.add_operand(
...     property="R",
...     wavelength_nm=550.0,
...     target_type="over",
...     value=[0.95, 0.90, 0.85],
...     aoi_deg=[0.0, 30.0, 60.0],
...     polarization="p",
... )

add_spectral_operand(property: Literal['R', 'T', 'A'], wavelengths_nm: list[float], target_type: Literal['equal', 'below', 'over'], value: float, weight: float = 1.0, weights: list[float] | None = None, aoi_deg: float = 0.0, polarization: str = 'u', tolerance: float = 1e-06) → ThinFilmOptimizer

Add a spectral optimization operand (convenience method).

Parameters:

• property – Optical property to target (‘R’, ‘T’, or ‘A’).

• wavelengths_nm – List of wavelengths in nanometers.

• target_type – Type of target (‘equal’, ‘below’, ‘over’).

• value – Target value.

• weight – Weight for this operand. Defaults to 1.0.

• weights – Per-wavelength weights (alternative to weight). Defaults to None.

• aoi_deg – Angle of incidence in degrees. Defaults to 0.0.

• polarization – Polarization state (‘s’, ‘p’, ‘u’). Defaults to ‘u’.

• tolerance – Tolerance for ‘equal’ targets. Defaults to 1e-6.

Returns:

self for method chaining.

add_variable(layer_index: int, min_nm: float | None = None, max_nm: float | None = None, apply_scaling: bool = True) → ThinFilmOptimizer

Add a layer thickness as an optimization variable.

Parameters:

• layer_index – Index of the layer to vary (0-based).

• min_nm – Minimum thickness in nanometers. Defaults to None (no bound).

• max_nm – Maximum thickness in nanometers. Defaults to None (no bound).

• apply_scaling – Whether to apply scaling for optimization. Defaults to True.

Returns:

self for method chaining.

fun_array() → ndarray

Array of operand weighted deltas for the current stack state.

get_current_performance() → dict[str, Any]

Get current performance metrics for all targets.

Returns:

Current values for all targets.

Return type:

dict

info() → None

Display information about the optimizer state in tabular format.

optimize(method: Literal['L-BFGS-B', 'TNC', 'SLSQP'] = 'L-BFGS-B', max_iterations: int = 100, tolerance: float = 1e-06, verbose: bool = False, **kwargs) → dict

Run the optimization.

Parameters:

• method – Optimization method to use. Defaults to “L-BFGS-B”. See

• options. (scipy.optimize.minimize for)

• max_iterations – Maximum number of iterations. Defaults to 100.

• tolerance – Convergence tolerance. Defaults to 1e-6.

• verbose – Whether to print optimization progress. Defaults to False.

• **kwargs – Additional keyword arguments for the optimizer.

Returns:

Optimization results including success status, final merit,

iterations, and thickness changes.

Return type:

dict

Raises:

ValueError – If no variables or targets are defined.

plot_operands(ax, plot_type: Literal['wavelength', 'angle'] = 'wavelength', wavelength_range_nm: tuple[float, float] | None = None, angle_range_deg: tuple[float, float] | None = None, num_points: int = 100, fixed_wavelength_nm: float = 550.0, fixed_angle_deg: float = 0.0) → None

Plot optimization operands on the provided axes (lightweight version).

Parameters:

• ax – Matplotlib axes to plot on.

• plot_type – Type of plot - “wavelength” or “angle”.

• wavelength_range_nm – Wavelength range for plotting (min, max) in nm.

• angle_range_deg – Angle range for plotting (min, max) in degrees.

• num_points – Number of points for plotting smooth curves.

• fixed_wavelength_nm – Fixed wavelength when plotting vs angle.

• fixed_angle_deg – Fixed angle when plotting vs wavelength.

static register_operand(name: str, func, overwrite: bool = False) → None

Register a custom operand metric function.

reset() → ThinFilmOptimizer

Reset the stack to its initial state.

Returns:

self for method chaining.

rss() → float

Root sum of squares of the current merit function.

sum_squared() → float

Calculate the sum of squared operand deltas.

class VariableInfo(variable: LayerThicknessVariable, min_val: float | None, max_val: float | None, layer_index: int)

Information about an optimization variable.

layer_index: int

max_val: float | None

min_val: float | None

variable: LayerThicknessVariable