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)

class ElementInfo

Information about an element in a mode matching solution.

clearance_left: float | None

Clearance to the previous element or shifting range boundary if the element is a free element

clearance_right: float | None

Clearance to the next element or shifting range boundary if the element is a free element

couplings: ndarray | None

Coupling vector of the element with respect to all degrees of freedom if it is a free element

dof: int | None

Degree of freedom index of the element in the parametrized setup if it is a free element

element: ThinLens | ThickLens

The element object itself

focal_length: float

Focal length of the element

grad_focus: float | None

Gradient of the final beam focus with respect to the element position if it is a free element

grad_waist: float | None

Gradient of the final beam waist with respect to the element position if it is a free element

position: float

Position of the element in the setup

sensitivities: ndarray | None

Sensitivity vector of the element with respect to all degrees of freedom if it is a free element

sensitivity: float | None

Sensitivity of the element, if it is a free element

shape: str

ASCII representation of the element shape

shifting_range: ShiftingRange | None

The shifting range the element belongs to if it is a free element

class SolutionSummary

Summary dictionary for mode matching analysis.

const_space: list[ndarray]

The basis vectors spanning the constant overlap sub-space.

couplings: ndarray

The coupling matrix.

elements: list[ThinLens | ThickLens]

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

grad_focus: ndarray

The gradient of the final beam focus with respect to the element positions.

grad_waist: ndarray

The gradient of the final beam waist with respect to the element positions.

max_sensitivity: float

The maximal sensitivity.

max_sensitivity_axis: int

The index of the degree of freedom with maximal sensitivity.

min_coupling: float

The minimal coupling.

min_coupling_pair: tuple[int, int]

The indices of the pair of degrees of freedom with minimal coupling.

min_cross_sens: float

The minimal cross-sensitivity.

min_cross_sens_direction: ndarray

The direction of the least cross-sensitive pair of degrees of freedom.

min_cross_sens_pair: tuple[int, int]

The indices of the pair of degrees of freedom with minimal cross-sensitivity.

min_sensitivity: float

The minimal sensitivity.

min_sensitivity_axis: int

The index of the degree of freedom with minimal sensitivity.

num_elements: int

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

overlap: float

The mode overlap of the solution.

positions: ndarray

The positions of the free elements in the setup.

sensitivities: ndarray

The sensitivity matrix.

solution: ModeMatchingSolution

The analyzed mode matching solution.

element_summary_df(axial_unit=None, radial_unit=None, fraction_unit=None, sensitivity_unit=None) → DataFrame

Create a summary DataFrame of the elements in the solution.

Parameters:

• axial_unit (LengthUnit | None, default: None) – Unit to use for the axial quantities along the beam, i.e., the coordinate along the beam. If None, this defaults to Config.Units.axial.

• radial_unit (LengthUnit | None, default: None) – Unit to use for the radial across the beam, i.e., the beam radius. If None, this defaults to Config.Units.radial.

• fraction_unit (FractionUnit | None, default: None) – Unit for fractional quantities, i.e., the mode overlap and coupling coefficients. If None, this defaults to Config.Units.fraction.

• sensitivity_unit (SensitivityUnit | None, default: None) – Unit for sensitivity quantities, i.e., the overlap lost for a certain squared displacement. If None, this defaults to Config.Units.sensitivity.

Return type:

DataFrame

Returns:

A DataFrame containing the summary data for each element, see element_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 element_summary: list[ElementInfo]

A summary of the elements in the mode matching solution.

Returns:

A list of dictionaries containing the summary data for each element, see ElementInfo for details.

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.

property summary: SolutionSummary

Summary dictionary of the analysis results.

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