corset.core

Core classes for representing and simulating Gaussian beams and optical setups.

Setups are represented as OpticalSetup instances which propagate an initial Beam through a sequence of Lens elements. This yields a piecewise defined beam radius made from Gaussian beam segments between the elements. The individual beams are represented using a complex beam parameter combined with an axial offset and wavelength. The beams are propagated using the ray transfer matrix method for Gaussian beams, see here.

class corset.core.Beam(beam_parameter, z_offset, wavelength, gauss_cov=None) → None

Paraxial Gaussian beam representation.

Implements _repr_png_() to show a plot of the beam radius in IPython environments produced by Beam.plot().

Parameters:

• beam_parameter (complex)

• z_offset (float)

• wavelength (float)

• gauss_cov (ndarray | None)

classmethod fit(positions, radii, wavelength, p0=None) → Beam

Fit a Gaussian beam radius to measured data.

This uses scipy.optimize.curve_fit() to estimate the focus position and waist given arrays of axial positions and measured radii.

Parameters:

• positions (ndarray) – Axial positions where radii were measured.

• radii (ndarray) – Measured beam radii corresponding to the positions.

• wavelength (float) – Wavelength used to relate waist and Rayleigh range.

• p0 (tuple[float, float] | None, default: None) – Initial guess for (focus, waist). If omitted a simple heuristic is used.

Return type:

Beam

Returns:

Beam instance fitted to the data.

classmethod from_gauss(focus, waist, wavelength, cov=None) → Beam

Create a Beam instance from focus position and waist.

Parameters:

• focus (float) – The axial position of the beam focus.

• waist (float) – The beam waist radius.

• wavelength (float) – The wavelength of the beam.

• cov (ndarray | None, default: None) – Optional 2x2 covariance matrix for the focus and waist.

Return type:

Beam

Returns:

Beam instance.

classmethod load_yaml(filename) → Self

Load an object from a YAML file.

If this is called from a subclass the loaded object type must match that subclass.

Parameters:

filename (str | Path) – Path to the YAML file.

Return type:

Self

Returns:

The loaded object.

Raises:

• ValueError – If the YAML file does not contain a ‘data’ field.

• TypeError – If the loaded object type does not match the class used to call this method.

plot(**kwargs) → OpticalSetupPlot

Plot the beam as part of an optical setup with no other elements.

Parameters:

**kwargs – Keyword arguments forwarded to OpticalSetup.plot().

Return type:

OpticalSetupPlot

Returns:

OpticalSetupPlot instance for further customization.

radius(z) → float | ndarray

Compute the beam radius at axial position(s).

Parameters:

z (float | ndarray) – Axial position(s) where the beam radius is evaluated.

Return type:

float | ndarray

Returns:

Beam radius at the specified axial position(s).

radius_dev(z) → float | ndarray

Compute the beam radius (standard) deviation at axial position(s).

Parameters:

z (float | ndarray) – Axial position(s) where the beam radius deviation is evaluated.

Return type:

float | ndarray

Returns:

Beam radius deviation at the specified axial position(s).

Raises:

ValueError – If the covariance matrix is not defined for this beam.

save_yaml(filename) → None

Save the object to a YAML file.

Parameters:

• filename (str | Path) – Path to the YAML file.

• self (Any)

Return type:

None

beam_parameter: complex

Complex beam parameter \(q = z - z_0 + i z_R\) defined at position \(z\) with focus at \(z_0\) and Rayleigh range \(z_R\).

property focus: float

Axial position of the beam focus i.e. waist position

gauss_cov: ndarray | None = None

2x2 covariance matrix for focus position and waist

property rayleigh_range: float

Rayleigh range

property waist: float

Waist radius

wavelength: float

Wavelength of the beam

z_offset: float

Axial position at which the ray is defined

class corset.core.OpticalSetup(initial_beam, elements, validate=True) → None

Optical setup described by an initial beam and a sequence of elements.

Implements _repr_png_() to show a plot of the optical setup in IPython environments produced by OpticalSetup.plot().

Parameters:

• initial_beam (Beam)

• elements (list[tuple[float, ThinLens | ThickLens]])

• validate (dataclasses.InitVar[bool])

classmethod fit(positions, radii, wavelength, elements, p0=None) → OpticalSetup

Fit an optical setup to measured data.

Parameters:

• positions (ndarray) – Axial positions where radii were measured.

• radii (ndarray) – Measured beam radii corresponding to the positions.

• wavelength (float) – Wavelength used to relate waist and Rayleigh range.

• elements (Sequence[tuple[float | tuple[float, float], ThinLens | ThickLens]]) – Optical elements as (position, element) tuples sorted by position. positions can be specified as float to describe a fixed position or as (expected, deviation) tuple to fit the element position between expected - deviation and expected + deviation.

• p0 (tuple[float, float] | None, default: None) – Initial guess for (focus, waist). If omitted a simple heuristic is used.

Return type:

OpticalSetup

Returns:

OpticalSetup instance fitted to the data.

Raises:

• ValueError – If the initial guess for element positions are not in ascending order.

• ValueError – If the fitted element positions are invalid, i.e. not in ascending order.

• ValueError – If no data point is before the first element when using beam parameter initial guess heuristic.

classmethod load_yaml(filename) → Self

Load an object from a YAML file.

If this is called from a subclass the loaded object type must match that subclass.

Parameters:

filename (str | Path) – Path to the YAML file.

Return type:

Self

Returns:

The loaded object.

Raises:

• ValueError – If the YAML file does not contain a ‘data’ field.

• TypeError – If the loaded object type does not match the class used to call this method.

plot(*, points=None, limits=None, beam_kwargs=None, confidence_interval=None, rayleigh_range_cap=None, free_lenses=[], ax=None, show_legend=None, legend_loc=None) → OpticalSetupPlot

Plot the optical setup, see corset.plot.plot_setup()

Return type:

OpticalSetupPlot

Parameters:

• self (OpticalSetup)

• points (int | ndarray | None)

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

• beam_kwargs (dict | None)

• confidence_interval (float | bool | None)

• rayleigh_range_cap (float | None)

• free_lenses (list[int])

• ax (Axes | None)

• show_legend (bool | None)

• legend_loc (str | None)

radius(z) → float | ndarray

Compute the beam radius at axial position(s).

Return type:

float | ndarray

Parameters:

z (float | ndarray)

radius_dev(z) → float | ndarray

Compute the beam radius confidence interval at axial position(s).

Return type:

float | ndarray

Parameters:

z (float | ndarray)

save_yaml(filename) → None

Save the object to a YAML file.

Parameters:

• filename (str | Path) – Path to the YAML file.

• self (Any)

Return type:

None

property beam_parameters: list[complex]

Compute the ray vectors between elements including before the first element and after the last.

property beams: list[Beam]

Compute the Beam instances between elements including before the first element and after the last.

property beams_fast: list[Beam]

Compute the Beam instances without propagating covariances.

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

Optical elements as (position, element) tuples sorted by position

property gauss_covariances: list[ndarray | None]

Compute the covariance matrices between elements including before the first element and after the last.

initial_beam: Beam

Initial beam before left most element

validate: dataclasses.InitVar[bool] = True

Validate that elements are sorted by position

class corset.core.ThickLens(in_roc, out_roc, thickness, refractive_index, left_margin=0.0, right_margin=0.0, name=None) → None

Thick lens element including additional information.

The signs of the radius of curvature follow the standard optics convention where positive radii correspond to surfaces that are convex when viewed from the input side of the lens. This means that on the entry surface, a positive radius of curvature is a convex surface while on the exit surface, a negative radius of curvature is convex. Use ThickLens.FLAT to represent a flat surface. This is an alias for float('inf').

Parameters:

• in_roc (float)

• out_roc (float)

• thickness (float)

• refractive_index (float)

• left_margin (float)

• right_margin (float)

• name (str | None)

classmethod load_yaml(filename) → Self

Load an object from a YAML file.

If this is called from a subclass the loaded object type must match that subclass.

Parameters:

filename (str | Path) – Path to the YAML file.

Return type:

Self

Returns:

The loaded object.

Raises:

• ValueError – If the YAML file does not contain a ‘data’ field.

• TypeError – If the loaded object type does not match the class used to call this method.

save_yaml(filename) → None

Save the object to a YAML file.

Parameters:

• filename (str | Path) – Path to the YAML file.

• self (Any)

Return type:

None

FLAT: ClassVar[float] = inf

Surface radius representing a flat surface

property focal_length: float

Approximate focal length of the thick lens calculated using the lensmaker’s equation.

in_roc: float

Input surface radius of curvature, positive is convex

left_margin: float = 0.0

Physical size to the left of the lens center

property matrix: ndarray

ABCD matrix of the lens element.

name: str | None = None

Name for reference and plotting

out_roc: float

Output surface radius of curvature, negative is convex

refractive_index: float

Refractive index of the lens material

right_margin: float = 0.0

Physical size to the right of the lens center

thickness: float

Thickness of the lens

class corset.core.ThinLens(focal_length, left_margin=0.0, right_margin=0.0, name=None) → None

Thin lens element including additional information.

Parameters:

• focal_length (float)

• left_margin (float)

• right_margin (float)

• name (str | None)

classmethod load_yaml(filename) → Self

Load an object from a YAML file.

If this is called from a subclass the loaded object type must match that subclass.

Parameters:

filename (str | Path) – Path to the YAML file.

Return type:

Self

Returns:

The loaded object.

Raises:

• ValueError – If the YAML file does not contain a ‘data’ field.

• TypeError – If the loaded object type does not match the class used to call this method.

save_yaml(filename) → None

Save the object to a YAML file.

Parameters:

• filename (str | Path) – Path to the YAML file.

• self (Any)

Return type:

None

focal_length: float

Focal length of the lens

left_margin: float = 0.0

Physical size to the left of the focal plane

property matrix: ndarray

ABCD matrix of the lens element.

name: str | None = None

Name for reference and plotting

right_margin: float = 0.0

Physical size to the right of the focal plane

corset.core.Lens = corset.core.ThinLens | corset.core.ThickLens

Lens type union