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
|
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:
- Variables:
- 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():targetmakes an equality,min_valand/ormax_valan inequality. A constraint is not a merit term: it stays out offun_array,residual_vectorandsum_squared. Only the native damped least squares enforces constraints; the other optimizers raiseConfigurationError.- 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, timessqrt(quadrature_w * field_w * wavelength_w) * weight, sosum(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. Withmode="penalty"they are merit operands withmin_val/max_val,center_thicknessandedge_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_glassormax_center_airis 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
ConstraintorOperandobjects.- Raises:
ConfigurationError – If
modeis 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_arrayandsum_squared, so every optimizer sees them. With batching, its rays share the operands’ bundles.- Parameters:
block – The block.
- Returns:
The block.
- Raises:
ConfigurationError – If
blockis not aResidualBlock.
- add_variable(optic, variable_type, scaler: Scaler = None, **kwargs)#
Add a variable to the merit function
- 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’sinput_data. Operands with an effective weight of zero are excluded from the result.When batching is enabled, delegates to the
BatchedRayEvaluatorwhich 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
- 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:
- 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_ifor 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 equalssum(residual_vector() ** 2).Residual block rows follow the operands, already weighted.
When batching is enabled, delegates to the
BatchedRayEvaluatorwhich 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:
- Return type:
be.ndarray
- rss()#
RSS of current merit function
- run()[source]#
Run the optimizer for compensation.
- Returns:
The result of the optimizer run.
- Return type:
- sum_squared()#
Calculate the sum of squared operand weighted deltas.
When batching is enabled, delegates to the
BatchedRayEvaluatorwhich 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 frominput_data(or None).wavelength: The wavelength index or value frominput_data(or None).operand_weight(float): The user-setOperand.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.