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 None the default from Config is used. If False, the raw sensitivities without unit conversion are used.

Returns:

• “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.

Return type:

A dictionary containing the summary data. The keys are

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 two all but the two largest eigenvalues of the Hessian \(\mathbf{H}\). These eigenvalues are usually many orders of magnitude smaller than the two largest ones, but generally not zero.

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.

property max_sensitivity: float

The maximal absolute sensitivity among all degrees of freedom.

property max_sensitivity_axis: int

The index \(i\) of the degree of freedom with maximal absolute 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 absolute sensitivity among all degrees of freedom.

property min_sensitivity_axis: int

The index \(i\) of the degree of freedom with minimal absolute 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.make_focus_and_waist(solution) → Callable[[ndarray], ndarray]

Create a function that computes the focus and waist of the final beam as a function of the free element positions.

Parameters:

solution (ModeMatchingSolution) – The mode matching solution to base the focus and waist function on.

Return type:

Callable[[ndarray], ndarray]

Returns:

A function that takes an array of element positions and returns the focus and waist.

corset.analysis.make_mode_overlap(solution) → Callable[[ndarray], float]

Create a function that computes the mode overlap as the function of the free element positions.

Parameters:

solution (ModeMatchingSolution) – The mode matching solution to base the overlap function on.

Return type:

Callable[[ndarray], float]

Returns:

A function that takes an array of element positions and returns the mode overlap.

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])