corset.core

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, fit_data=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:
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_png(filename) → Self#

Load an object from a PNG file with YAML metadata.

Parameters:

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

Return type:

Self

Returns:

The loaded object.

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_png(filename) → None#

Save the object to a PNG file with YAML metadata.

Parameters:

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

Return type:

None

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\).

fit_data: tuple[ndarray, ndarray] | None = None#

Data points that were used to fit the beam parameters (positions, radii)

property focus: float#

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

property focus_dev: float | None#

Axial position of the beam focus (standard) deviation

gauss_cov: ndarray | None = None#

2x2 covariance matrix for focus position and waist

property rayleigh_range: float#

Rayleigh range

property waist: float#

Waist radius

property waist_dev: float | None#

Waist radius (standard) deviation

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:
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_png(filename) → Self#

Load an object from a PNG file with YAML metadata.

Parameters:

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

Return type:

Self

Returns:

The loaded object.

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(*, ax=None, points=None, limits=None, beam_kwargs=None, confidence_interval=None, show_fit_data=None, rayleigh_range_cap=None, free_lenses=[], show_legend=None, legend_loc=None, axial_unit=None, radial_unit=None) → OpticalSetupPlot#

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

Return type:

OpticalSetupPlot

Parameters:
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_png(filename) → None#

Save the object to a PNG file with YAML metadata.

Parameters:

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

Return type:

None

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 and attaching fit data.

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 radii 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:
classmethod block(thickness, refractive_index, left_margin=None, right_margin=None, name=None)#

Create a thick lens with two flat surfaces representing a block of material.

Parameters:

  • thickness (float) – Thickness of the block.

  • refractive_index (float) – Refractive index of the block material.

  • left_margin (float | None, default: None) – Optional physical size to the left of the block center. Defaults to half the thickness.

  • right_margin (float | None, default: None) – Optional physical size to the right of the block center. Defaults to half the thickness.

  • name (str | None)

Returns:

ThickLens instance representing a block of material.

Tip

While the solver will generally not allow for any overlap between elements and other mode matching regions, there is a special case that allows a block to be located inside a Passage region. This is useful for ensuring that the beam actually fits through the block.

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

property shape: str#

ASCII lens shape representation.

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:
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

shape: ClassVar[str] = '|'#

ASCII lens shape representation

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

Lens type union

Contents