tolerancing.compensator#

Compensator Module

This module contains a class for compensating perturbations in an optical system. The CompensatorOptimizer class is used to optimize a set of variables to compensate for perturbations in an optical system.

Kramer Harrison, 2024

Classes

CompensatorOptimizer([method, tol])

A class representing a compensator for a tolerancing problem.

class CompensatorOptimizer(method='generic', tol=1e-05)[source]#

A class representing a compensator for a tolerancing problem. This class optimizes a set of variables to compensate for perturbations in an optical system.

Parameters:
  • method (str) – The type of optimizer to use. Default is ‘generic’. Other options: ‘least_squares’

  • tol (float) – The tolerance for the optimizer. Default is 1e-5.

Variables:
  • method (str) – The type of optimizer to use. Default is ‘generic’. Other options include ‘least_squares’.

  • tol (float) – The tolerance for the optimizer. Default is 1e-5.

  • _optimizer_map (dict) – A mapping of optimizer types to their respective classes.

add_constraint(operand_type=None, target=None, min_val=None, max_val=None, weight=1, input_data=None, tol=1e-08)#

Add a hard constraint. Experimental.

Uses the operand spec of add_operand(): target makes an equality, min_val and/or max_val an inequality. A constraint is not a merit term: it stays out of fun_array, residual_vector and sum_squared. Only the native damped least squares enforces constraints; the other optimizers raise ConfigurationError.

Parameters:
  • operand_type – Registered operand name.

  • target – Equality target.

  • min_val – Lower bound of the operand value.

  • max_val – Upper bound of the operand value.

  • weight – Positive scale of the rows, effective_weight * delta.

  • input_data – Operand input data.

  • tol – Feasibility tolerance of each row, in row units.

Returns:

The new Constraint.

Raises:

ConfigurationError – If the specification is invalid.

add_default_merit(optic: Optic, kind: str = 'spot', rings: int = 3, arms: int = 6, reference: str = 'centroid', fields: str | Sequence[int] = 'all', wavelengths: str | Sequence[int] = 'all', weight: float = 1.0) → DefaultMeritBlock#

Add a per-ray default merit on a Gaussian pupil. Experimental.

Adds one DefaultMeritBlock, no operands. Each residual is transverse (dx, dy) or OPD per ray, times sqrt(quadrature_w * field_w * wavelength_w) * weight, so sum(r ** 2) estimates the weighted RMS squared.

Parameters:
  • optic – The optic.

  • kind – "spot" or "wavefront".

  • rings – Quadrature rings.

  • arms – Quadrature arms.

  • reference – "centroid" or "chief".

  • fields – "all" or field indices.

  • wavelengths – "all" or wavelength indices.

  • weight – Scale of every row.

Returns:

The new block.

Raises:

ConfigurationError – If an argument is invalid.

add_operand(operand_type=None, target=None, min_val=None, max_val=None, weight=1, input_data=None)#

Add an operand to the merit function

add_physical_constraints(optic: Optic, min_center_glass: float | None = None, min_edge_glass: float | None = None, min_center_air: float | None = None, min_edge_air: float | None = None, max_center: float | None = None, *, max_center_glass: float | None = None, max_center_air: float | None = None, max_edge_glass: float | None = None, max_edge_air: float | None = None, mode: str = 'constraint', weight: float = 1.0, tol: float = 1e-08) → list#

Add thickness limits between lens surfaces. Experimental.

Opt-in: Optiland never applies these limits by itself. A limit left as None is not applied. The gaps from the object and to the image are not limited. Limits are magnitudes, also after a mirror.

With mode="constraint" the limits are hard constraints, which only the native damped least squares enforces. With mode="penalty" they are merit operands with min_val/max_val, center_thickness and edge_thickness, which work with every optimizer but may be violated at the optimum.

Parameters:
  • optic – The optic.

  • min_center_glass – Smallest center thickness in glass.

  • min_edge_glass – Smallest edge thickness in glass.

  • min_center_air – Smallest center thickness in air.

  • min_edge_air – Smallest edge thickness in air.

  • max_center – Largest center thickness in glass and air, unless max_center_glass or max_center_air is given.

  • max_center_glass – Largest center thickness in glass.

  • max_center_air – Largest center thickness in air.

  • max_edge_glass – Largest edge thickness in glass.

  • max_edge_air – Largest edge thickness in air.

  • mode – "constraint" or "penalty".

  • weight – Weight of each row or operand.

  • tol – Feasibility tolerance of each row, for "constraint".

Returns:

The new Constraint or Operand objects.

Raises:

ConfigurationError – If mode is unknown, no limit is set or the limits are inconsistent.

add_residual_block(block: ResidualBlock) → ResidualBlock#

Add a residual block to the merit. Experimental.

The block’s rows follow the operands in residual_vector, fun_array and sum_squared, so every optimizer sees them. With batching, its rays share the operands’ bundles.

Parameters:

block – The block.

Returns:

The block.

Raises:

ConfigurationError – If block is not a ResidualBlock.

add_variable(optic, variable_type, scaler: Scaler = None, **kwargs)#

Add a variable to the merit function

property batching_enabled: bool#

Whether batched evaluation is currently active.

block_info()#

Print one summary row per residual block. Experimental.

block_spans() → list[tuple[int, int, ResidualBlock]]#

(first row, end row, block) of each block in the residual vector.

clear_constraints()#

Remove all hard constraints. Experimental.

clear_operands()#

Clear all operands from the merit function

clear_residual_blocks()#

Remove all residual blocks from the merit. Experimental.

clear_variables()#

Clear all variables from the merit function

constraint_info()#

Print the hard constraint rows at the current state. Experimental.

constraint_vector()#

Signed constraint rows at the current state. Experimental.

Each row is effective_weight * delta, signed so that an equality is feasible at 0 and an inequality at <= 0.

Returns:

A 1-D array with one entry per row.

Return type:

be.ndarray

disable_batching()#

Disable batched ray evaluation and use standard per-operand evaluation.

drop_block_rows(rows: Sequence[int] | np.ndarray) → int#

Drop rows of residual blocks from the ray set. Experimental.

For native drivers, ray-set re-validation. Operand rows are never dropped, and neither are a block’s last rows.

Parameters:

rows – Indices into the residual vector.

Returns:

The number of rows dropped.

enable_batching()#

Enable batched ray evaluation for faster optimization.

When batching is enabled, operands that require ray tracing are grouped by optic and wavelength so that redundant traces are eliminated. This can dramatically speed up merit-function evaluation for problems with many ray operands.

The evaluator is re-created whenever this method is called, so it always reflects the current set of operands.

fun_array()#

Array of operand contribution terms for the merit function.

Each term is computed as:

(effective_weight(op) * op.delta()) ** 2

where effective_weight = operand.weight * field_weight * wl_weight. Field and wavelength weights are read from the optic stored in each operand’s input_data. Operands with an effective weight of zero are excluded from the result.

When batching is enabled, delegates to the BatchedRayEvaluator which minimises redundant ray traces.

Residual block rows follow the operands, squared.

Returns:

1-D array of per-operand contribution values. Returns [0.0] when there are no active operands or block rows.

Return type:

be.ndarray

get_optimizer()[source]#
property has_variables#

Check if the optimizer has variables. If no variables are present, then the optimizer will not run.

Returns:

True if the optimizer has variables, False otherwise.

Return type:

bool

info()#

Print information about the optimization problem.

merit_info()#

Print information about the merit function.

property num_residuals: int#

operands plus block rows.

Type:

Length of residual_vector()

operand_info()#

Print information about the operands in the merit function

residual_vector()#

Vector of weighted operand deltas (unsquared).

Returns a 1-D array whose i-th element is weight_i * delta_i for each operand. This is the residual vector r needed by least-squares algorithms such as the Damped Least-Squares (Levenberg-Marquardt) optimizer.

Unlike fun_array(), the values are not squared, so the merit function equals sum(residual_vector() ** 2).

Residual block rows follow the operands, already weighted.

When batching is enabled, delegates to the BatchedRayEvaluator which minimises redundant ray traces.

Returns:

A 1-D array of length num_residuals.

Return type:

be.ndarray

residuals_and_constraints()#

Residuals followed by constraint rows, from one evaluation.

With batching, constraint rows share the merit’s ray bundles. Experimental.

Returns:

residual_vector() then constraint_vector().

Return type:

be.ndarray

restore_block_rows() → None#

Bring back all dropped block rows. Experimental.

rss()#

RSS of current merit function

run()[source]#

Run the optimizer for compensation.

Returns:

The result of the optimizer run.

Return type:

scipy.optimize.OptimizeResult

sum_squared()#

Calculate the sum of squared operand weighted deltas.

When batching is enabled, delegates to the BatchedRayEvaluator which minimises redundant ray traces.

update_optics()#

Update all optics considered in the optimization problem.

The optics that own variables are updated first, so that configurations linked to them by pickups read the new values. Every other optic referenced by an operand is then updated, each optic once per call.

variable_info()#

Print information about the variables in the merit function.

weight_breakdown() → list[dict]#

Return a list of dicts describing each operand’s effective weight.

The effective weight is the product of the operand’s own weight, the field weight (looked up from the optic via the operand’s input_data), and the wavelength weight. The formula used in the merit function is:

(effective_weight × delta) ** 2

Each returned dict contains:

  • operand_type (str): The operand type string.

  • field: The field index or coordinate from input_data (or None).

  • wavelength: The wavelength index or value from input_data (or None).

  • operand_weight (float): The user-set Operand.weight.

  • field_weight (float): The field’s weight from the optic (1.0 if not resolvable).

  • wl_weight (float): The wavelength’s weight from the optic (1.0 if not resolvable).

  • effective_weight (float): Product of the three weights above.

Returns:

One dict per operand in self.operands.

Return type:

list[dict]