corset.analysis

Analysis tools for detailed analysis of mode matching solutions.

class corset.analysis.ModeMatchingAnalysis(solution) → None

Analysis of a mode matching solution providing various sensitivity metrics.

Parameters:

solution (ModeMatchingSolution)

summary(sensitivity_unit=None) → dict

Create a summary dictionary of the analysis results

Parameters:

sensitivity_unit (SensitivityUnit | bool | None, default: None) – The unit to use for sensitivities in the summary. If False, the raw sensitivities without unit conversion are used. If None this defaults to Config.sensitivity_unit.

Return type:

dict

Returns:

A dictionary containing the summary data. The keys are

• "overlap": The mode overlap of the solution.

• "num_elements": The number of free elements (i.e. elements used for mode matching) in the setup.

• "elements": A list of the free elements (i.e. elements used for mode matching) in the setup.

• "positions": The positions of the free elements in the setup.

• "min_sensitivity_axis": The index of the degree of freedom with minimal sensitivity.

• "min_sensitivity": The minimal sensitivity in the specified unit.

• "max_sensitivity_axis": The index of the degree of freedom with maximal sensitivity.

• "max_sensitivity": The maximal sensitivity in the specified unit.

• "min_cross_sens_pair": The indices of the pair of degrees of freedom with minimal cross-sensitivity.

• "min_cross_sens": The minimal cross-sensitivity in the specified unit.

• "min_cross_sens_direction": The direction of the least cross-sensitive pair of degrees of freedom.

• "min_coupling_pair": The indices of the pair of degrees of freedom with minimal coupling.

• "min_coupling": The minimal coupling.

• "sensitivities": The sensitivity matrix in the specified unit.

• "couplings": The coupling matrix.

• "const_space": The basis vectors spanning the constant overlap sub-space.

• "grad_focus": The gradient of the final beam focus with respect to the element positions.

• "grad_waist": The gradient of the final beam waist with respect to the element positions.

• "sensitivity_unit": The sensitivity unit used.

• "solution": The analyzed mode matching solution.

summary_df(sensitivity_unit=None) → DataFrame

Create a summary DataFrame of the analysis results

Parameters:

sensitivity_unit (SensitivityUnit | None | bool, default: None) – The unit to use for sensitivities in the summary. If None the default from Config is used. If False, the raw sensitivities without unit conversion are used.

Return type:

DataFrame

Returns:

A DataFrame containing the summary data with one row per value, see summary() for details.

property const_space: list[ndarray]

The basis vectors spanning the constant overlap sub-space around the optimum.

Note

This is simply determined as the corresponding eigenvectors to all but the two largest eigenvalues of the Hessian \(\mathbf{H}\). These eigenvalues are generally not zero but they should by orders of magnitude smaller than the two largest ones.

property couplings: ndarray

The coupling matrix \(\mathbf{R}\) between the different degrees of freedom.

The coupling \(r_{ij}\) between degrees of freedom indexed \(i\) and \(j\) is the normalized cross-sensitivity \(s_{ij}\) between the two degrees of freedom:

\[r_{ij} = \frac{s_{ij}}{\sqrt{s_{ii} s_{jj}}}\]

property focus_and_waist_jacobian: ndarray

The Jacobian \(\mathbf{J}\) of the final beam focus and waist \(\mathbf{f}_{fw}(\mathbf{x})\) with respect to the element positions \(\mathbf{x}\) around the optimum \(\mathbf{x}^*\). The individual elements \(j_{ij}\) of the Jacobian are given by:

\[j_{ij} = \left.\frac{\partial f_{fw,i}(\mathbf{x})}{\partial x_j} \right|_{\mathbf{x} = \mathbf{x}^*}\]

property grad_focus: ndarray

The gradient of the final beam focus with respect to the element positions, equal to the first row of the Jacobian.

property grad_waist: ndarray

The gradient of the final beam waist with respect to the element positions, equal to the second row of the Jacobian.

property hessian: ndarray

The Hessian matrix \(\mathbf{H}\) of the mode overlap function \(o(\mathbf{x})\) around the optimum \(\mathbf{x}^*\). The individual elements \(h_{ij}\) of the Hessian are given by:

\[h_{ij} = \left. \frac{\partial^2 o(\mathbf{x})}{\partial x_i \partial x_j} \right|_{\mathbf{x} = \mathbf{x}^*}\]

For problems with two degrees of freedom the Hessian is always negative definite, if there are more than two degrees of freedom it generally negative semi-definite with reduced rank or at least very bad conditioning.

Note

The Hessian computation assumes, that the gradient of the overlap function is zero at the point where it is computed. This mean the Hessian is only valid if the overlap is approximately 100%. However this should not matter, since Hessian based metrics are only meaningful if computed around a stationary point.

property max_sensitivity: float

The maximal sensitivity among all degrees of freedom.

property max_sensitivity_axis: int

The index \(i\) of the degree of freedom with maximal sensitivity \(s_{ii}\).

property min_coupling: float

The minimal absolute coupling between any pair of degrees of freedom.

property min_coupling_pair: tuple[int, int]

The indices \((i, j)\) of the pair of degrees of freedom with minimal absolute coupling \(r_{ij}\). The second index is always larger than the first.

property min_cross_sens: float

The minimal absolute cross-sensitivity between any pair of degrees of freedom.

property min_cross_sens_direction: ndarray

The direction of the least cross-sensitive pair of degrees of freedom. This is the smallest eigenvector of the 2x2 cross-sensitivity sub-matrix of the least cross-sensitive pair.

property min_cross_sens_pair: tuple[int, int]

The indices \((i, j)\) of the pair of degrees of freedom with minimal absolute cross-sensitivity \(s_{ij}\). The second index is always larger than the first.

property min_sensitivity: float

The minimal sensitivity among all degrees of freedom.

property min_sensitivity_axis: int

The index \(i\) of the degree of freedom with minimal sensitivity \(s_{ii}\).

property sensitivities: ndarray

The sensitivity matrix \(\mathbf{S}\) of the mode overlap around the optimum.

It is proportional to the Hessian \(\mathbf{H}\) with \(\mathbf{S} = -\mathbf{H}/2\). That way the positive loss in mode overlap \(\Delta o\) for small perturbations \(\Delta \mathbf{x}\) around the optimum can be expressed as:

\[\Delta o \approx \mathbf{\Delta x}^T \mathbf{S} \mathbf{\Delta x}\]

solution: ModeMatchingSolution

The mode matching solution to analyze.

corset.analysis.vector_partial(func, default, dims) → Callable[[ndarray], ndarray]

Partial function application for functions with a single vector valued argument.

Parameters:

• func (Callable[[ndarray], ndarray]) – Function to partially apply.

• default (ndarray) – Base vector that is partially applied. The values at the unbound dimensions are ignored.

• dims (Iterable[int]) – The indices of the elements that are the inputs to the resulting function, the remaining values are taken from the default vector.

Return type:

Callable[[ndarray], ndarray]

Returns:

A function that takes only the specified dimensions as input and fills in the rest from the default vector.

corset.analysis.wrap_for_differentiate(func) → Callable[[ndarray], ndarray]

Wrap a function to implement the vectorized input/output behavior expected by scipy.differentiate.hessian() and scipy.differentiate.jacobian().

Return type:

Callable[[ndarray], ndarray]

Parameters:

func (Callable[[ndarray], ndarray])