corset.solver

Contents

corset.solver#

Mode matching solver and related data structures.

The main entry point is the function mode_match(), it will setup the ModeMatchingProblem. The problem defined with the help of ShiftingRange, Aperture, and Passage instances. The constructed ModeMatchingProblem yields ModeMatchingCandidate instances that are then optimized to produce ModeMatchingSolution instances. Each step containing a reference to the data structure it is based on. The actual constrained optimization is carried out using scipy.optimize.minimize() using the SLSQP method. All solutions will then be collected in a SolutionList for convenient analysis and filtering.

class corset.solver.Aperture(position, radius) → None#

Aperture constraint for the optical setup.

Parameters:

  • position (float)

  • radius (float)

property apertures: tuple[Aperture]#

A tuple containing this aperture. Used for uniform interface with Passage.

position: float#

Axial position of the aperture

radius: float#

Aperture radius, i.e. maximum beam radius at this position.

class corset.solver.ModeMatchingCandidate(problem, populations) → None#

A candidate lens population for a mode matching problem.

Parameters:
generate_initial_positions(random) → ndarray#

Generate a set of initial positions for free lenses of the candidate.

Parameters:

random (bool) – Whether to generate random initial positions or evenly spaced positions.

Return type:

ndarray

Returns:

Array of initial positions for the lenses.

optimize(filter_pred, random_initial_positions, equal_setup_tol, solution_per_population) → list[ModeMatchingSolution]#

Optimize the candidate to find mode matching solutions.

Parameters:

  • filter_pred (Callable[[ModeMatchingSolution], bool]) – Predicate function that must return True for a solution to be accepted.

  • random_initial_positions (int) – Number of random initial positions to generate in addition to the equally spaced one.

  • equal_setup_tol (float) – Tolerance for considering two solutions as equal for eliminating duplicates.

  • solution_per_population (int) – Maximum number of solutions to optimize and return.

Return type:

list[ModeMatchingSolution]

Returns:

List of optimized mode matching solutions for the candidate.

property beam_constraint: NonlinearConstraint#

Nonlinear constraint to ensure beam radius is within aperture constraints.

property constraints: list[NonlinearConstraint | LinearConstraint]#

List of position constraints and beam constraints if there are any.

property parametrized_setup: ParametrizedSetup#

Parametrized optical setup for the candidate.

populations: list[tuple[ThinLens | ThickLens, ...]]#

Lens populations for each range

property position_constraint: LinearConstraint#

Linear constraint ensuring lenses do not overlap, stay within ranges and do not swap order.

problem: ModeMatchingProblem#

The parent mode matching problem

class corset.solver.ModeMatchingProblem(setup, desired_beam, ranges, selection, min_elements, max_elements, constraints, rng) → None#

Mode matching problem definition.

Parameters:
classmethod lens_combinations(ranges, base_selection, min_elements, max_elements, current_populations=[]) → Generator[list[tuple[ThinLens | ThickLens, ...]], None, None]#

Recursive helper function to generate all possible lens populations for the given ranges.

Parameters:

  • ranges (list[ShiftingRange]) – Remaining ranges to process.

  • base_selection (Sequence[ThinLens | ThickLens]) – Global selection of lenses to choose from.

  • min_elements (int) – Minimum number of elements remaining to place.

  • max_elements (int) – Maximum number of elements remaining to place.

  • current_populations (list[tuple[ThinLens | ThickLens, ...]], default: []) – Current lens populations for the processed ranges.

Yields:

list[tuple[Lens, …]] – The next lens populations for all ranges.

Return type:

Generator[list[tuple[ThinLens | ThickLens, ...]], None, None]

candidates() → Generator[ModeMatchingCandidate, None, None]#

Generate all possible range population candidates for the mode matching problem.

Return type:

Generator[ModeMatchingCandidate, None, None]

Returns:

Generator of ModeMatchingCandidate instances.

property aperture_constraints: list[Aperture]#

List of all constraints as Aperture constraints. Passage constraints are converted to two Aperture constraints.

constraints: Sequence[Aperture | Passage]#

Beam constraints on the optical setup

desired_beam: Beam#

Desired output beam after the optical setup

property interleaved_elements: list[tuple[float, ThinLens | ThickLens] | int]#

List of all (potential) elements, ranges where elements can be placed are represented by their index instead of the (position, element) tuple. Used for easy construction of parametrized setups.

max_elements: int#

Maximum number of elements to use

min_elements: int#

Minimum number of elements to use

ranges: list[ShiftingRange]#

Ranges where lenses can be placed

rng: Generator#

Seeded random number generator for reproducibility

selection: Sequence[ThinLens | ThickLens]#

Selection of lenses to choose from for mode matching

setup: OpticalSetup#

Initial optical setup

class corset.solver.ModeMatchingSolution(candidate, overlap, positions) → None#

A solution to a mode matching problem.

Implements _repr_png_() to show a plot of the solution setup in IPython environments.

Parameters:
optimize_coupling(min_abs_improvement=0.1, min_rel_improvement=0.5) → ModeMatchingSolution | None#

Optimize the solution to reduce coupling between least coupled pair while maintaining mode matching.

Note that this requires at least 3 elements so that there is at least one degree of freedom left after mode matching.

Parameters:

  • min_abs_improvement (float, default: 0.1) – Minimum absolute improvement in coupling to return the new solution.

  • min_rel_improvement (float, default: 0.5) – Minimum relative improvement in coupling to return the new solution.

Return type:

ModeMatchingSolution | None

Returns:

A new ModeMatchingSolution with improved coupling if successful, otherwise None.

plot_all(*, plot_kwargs={}, reachability_kwargs={}, sensitivity_kwargs={}) → tuple[Figure, tuple[ModeMatchingPlot, ReachabilityPlot, SensitivityPlot]]#

Plot all analyses, see corset.plot.plot_mode_match_solution_all()

Return type:

tuple[Figure, tuple[ModeMatchingPlot, ReachabilityPlot, SensitivityPlot]]

Parameters:

  • self (ModeMatchingSolution)

  • plot_kwargs (dict)

  • reachability_kwargs (dict)

  • sensitivity_kwargs (dict)

plot_reachability(*, displacement=0.005, num_samples=7, grid_step=2, dimensions=None, focus_range=None, waist_range=None, ax=None) → ReachabilityPlot#

Plot the reachability analysis, see corset.plot.plot_reachability()

Return type:

ReachabilityPlot

Parameters:

  • self (ModeMatchingSolution)

  • displacement (float | list[float])

  • num_samples (int | list[int])

  • grid_step (int | list[int])

  • dimensions (list[int] | None)

  • focus_range (tuple[float, float] | None)

  • waist_range (tuple[float, float] | None)

  • ax (Axes | None)

plot_sensitivity(*, dimensions=None, worst_overlap=0.98, x_range=None, y_range=None, z_range=None, z_n=3, force_contours=False, ax=None) → SensitivityPlot#

Plot the sensitivity analysis, see corset.plot.plot_sensitivity()

Return type:

SensitivityPlot

Parameters:

  • self (ModeMatchingSolution)

  • dimensions (tuple[int, int] | tuple[int, int, int] | None)

  • worst_overlap (float)

  • x_range (tuple[float, float] | None)

  • y_range (tuple[float, float] | None)

  • z_range (tuple[float, float] | None)

  • z_n (int)

  • force_contours (bool)

  • ax (Axes | None)

plot_setup(*, ax=None) → ModeMatchingPlot#

Plot the solution setup, see corset.plot.plot_mode_match_solution_setup()

Return type:

ModeMatchingPlot

Parameters:
property analysis: ModeMatchingAnalysis#

Analysis data for this solution.

candidate: ModeMatchingCandidate#

The candidate that produced this solution

overlap: float#

Mode overlap of the solution

positions: ndarray#

Positions of the lenses in the solution

property setup: OpticalSetup#

Optical setup corresponding to this solution.

class corset.solver.ParametrizedSetup(initial_beam, elements) → None#

Parametrized optical setup where some or all element positions are free parameters.

Parameters:
substitute(positions, validate=True) → OpticalSetup#

Substitute free parameters with given positions.

Parameters:

  • positions (list[float] | ndarray) – Positions to substitute for free parameters in order, must match number of free parameters.

  • validate (bool, default: True) – Whether to validate the positions in the resulting setup.

Return type:

OpticalSetup

Returns:

The resulting optical setup with substituted positions.

elements: list[tuple[float | None, ThinLens | ThickLens]]#

Optical elements as (position | None, element) tuples. None represents a free element / parameter.

property free_elements: list[int]#

List of indices of free elements (positions that are None).

initial_beam: Beam#

Initial beam before left most element

class corset.solver.Passage(left, right, radius) → None#
Parameters:

  • left (float)

  • right (float)

  • radius (float)

classmethod centered(center, width, radius) → Passage#

Convenience constructor for a passage centered at a given position.

Parameters:

  • center (float) – Center position of the passage.

  • width (float) – Width of the passage.

  • radius (float) – Passage radius.

Return type:

Passage

Returns:

Passage instance centered at the given position.

property apertures: tuple[Aperture, Aperture]#

Representation of the constraint as two Aperture constraints at the passage boundaries.

left: float#

Left boundary of the passage

radius: float#

Passage radius, i.e. maximum beam radius within the passage

right: float#

Right boundary of the passage

class corset.solver.ShiftingRange(left, right, min_elements=0, max_elements=inf, selection=<factory>) → None#

Range where lenses can be placed.

Parameters:

  • left (float)

  • right (float)

  • min_elements (int)

  • max_elements (int)

  • selection (list[ThinLens | ThickLens])

left: float#

Range left boundary

max_elements: int = inf#

Maximum number of lenses that can be placed in this range.

min_elements: int = 0#

Minimum number of lenses to be placed in this range

right: float#

Range right boundary

selection: list[ThinLens | ThickLens]#

Optional set of lenses to use for this range, if empty the global selection is used.

class corset.solver.SolutionList(solutions) → None#

List of mode matching solutions with convenient methods for filtering and sorting.

Supports (array) indexing, iteration, and other list-like operations. Implements _repr_html_() to show a pandas.DataFrame representation in IPython environments.

Parameters:

solutions (list[ModeMatchingSolution])

query(expr) → SolutionList#

Filter solutions based on a pandas.DataFrame.query() expression applied to the DataFrame representation.

Parameters:

expr (str) – Query string, see pandas.DataFrame.query() for details.

Return type:

SolutionList

Returns:

A new SolutionList containing only the solutions that satisfy the query.

sort_values(by, ascending=True) → SolutionList#

Sort solutions based on a column or list of columns in the DataFrame representation.

Parameters:

  • by (str | list[str]) – Column name or list of column names to sort by.

  • ascending (bool, default: True) – Whether to sort in ascending order.

Return type:

SolutionList

Returns:

A new SolutionList with solutions sorted by the specified columns.

property df: DataFrame#

DataFrame representation of the solutions for easy analysis.

solutions: list[ModeMatchingSolution]#

List of mode matching solutions

corset.solver.mode_match(setup, desired_beam, ranges, selection=[], min_elements=1, max_elements=inf, constraints=[], filter_pred=0.999, random_initial_positions=0, solution_per_population=1, equal_setup_tol=0.001, random_seed=0)#

Solve a mode matching problem by optimizing lens positions while respecting constraints.

Parameters:

  • setup (Beam | OpticalSetup) – Initial optical setup or initial beam.

  • desired_beam (Beam) – Desired output beam after the optical setup.

  • ranges (list[ShiftingRange]) – Shifting ranges where lenses can be placed.

  • selection (Sequence[ThinLens | ThickLens], default: []) – Selection of lenses to choose from for mode matching.

  • min_elements (int, default: 1) – Minimum number of elements to use.

  • max_elements (int, default: inf) – Maximum number of elements to use.

  • constraints (Sequence[Aperture | Passage], default: []) – Beam constraints on the resulting optical setup.

  • filter_pred (Callable[[ModeMatchingSolution], bool] | float | None, default: 0.999) – Predicate function or minimum overlap float to filter solutions.

  • random_initial_positions (int, default: 0) – Number of random initial positions to generate per candidate.

  • solution_per_population (int, default: 1) – Maximum number of solutions to optimize and return per lens population.

  • equal_setup_tol (float, default: 0.001) – Tolerance for considering two solutions as equal for eliminating duplicates.

  • random_seed (int, default: 0) – Random seed for reproducibility.

Returns:

A SolutionList containing the optimized mode matching solutions.

corset.solver.mode_overlap(delta_z, waist_a, waist_b, wavelength) → float#

Compute the mode overlap between two Gaussian beams.

Parameters:

  • delta_z (float) – Axial distance between the beam waists.

  • waist_a (float) – Waist radius of the first beam.

  • waist_b (float) – Waist radius of the second beam.

  • wavelength (float) – Wavelength of the beams.

Return type:

float

Returns:

Mode overlap between the two beams.

Contents