finesse.solutions.beamtrace module

Solution objects for beam propagations.

class finesse.solutions.beamtrace.ABCDSolution(name, M, direction, symbolic)[source]

Bases: BaseSolution

Solution for a composite ABCD calculation.

Parameters

Marray-like or two-element tuple of array-like

The ABCD matrix / matrices.

directionstr

Direction / plane of computation.

"both" indicates that M is a tuple of the ABCD matrices computed over both the tangential and sagittal planes.

"x" implies M is the ABCD matrix computed over the tangential plane.

"y" implies M is the ABCD matrix computed over the sagittal plane.

symbolicbool

Flag indicating whether the calculations are symbolic.

property M[source]

A copy of the underlying ABCD matrix as a numpy.ndarray.

Getter:: Returns a copy of underlying ABCD matrix.

property direction[source]

The plane in which this ABCD matrix was computed - ‘x’ for tangential, ‘y’ for sagittal.

Getter:: Returns the ABCD matrix plane.

eval()[source]

Evaluate the symbolic ABCD matrix.

Computes the numeric form of the ABCD matrix using the eval method of each parameter reference.

Returns

outnumpy.ndarray: A numeric matrix for the evaluated ABCD.

property symbolic[source]

Indicates whether this ABCD solution is symbolic.

Getter:: Returns True if this stores symbolic expressions, False otherwise.

class finesse.solutions.beamtrace.AstigmaticPropagationSolution(name, ps_x: PropagationSolution, ps_y: PropagationSolution)[source]

Bases: BaseSolution

Solution representation of a call to finesse.tracing.tools.propagate_beam_astig().

Internally this stores two PropagationSolution instances which are used to access the per-plane beam parameters. These propagation solutions can be accessed via AstigmaticPropagationSolution.ps_x and AstigmaticPropagationSolution.ps_y for the tangential and sagittal planes, respectively.

property components[source]: A list of all components (excluding spaces) traversed, in order.

property end_node[source]: The final node of the propagation.

property nodes[source]: A list of all the nodes traversed, in order.

overlap(at)[source]

Overlap between tangential and sagittal beam parameters at a given location of the path.

See PropagationSolution.q() for parameters description.

Returns

Ofloat or Function: Overlap between the beam parameters in each plane, at the specified node.

property overlaps[source]: A dict of nodes to the qx, qy overlaps at these nodes.

property path_length[source]: The geometric path length of the traversed path.

plot(*args, filename=None, show=True, ignore=None, name_xoffsets=None, name_yoffsets=None, ylims=None, npts=1000, resolution='equal', subs=None)[source]

Plot any combination of the beam sizes, accumulated Gouy phases and / or wavefront curvatures over the propagated path, showing the values for both planes.

The expected, valid positional arguments are any combination of:

“beamsize”,
“gouy”,
“curvature”,

or “all” to plot all of the above.

If no positional args are given then the beamsize (first axis) and accumulated Gouy phase (second axis) will be plotted by default.

Note

The resulting figure will be divided into two columns, the first giving the absolute quantity values for both planes and the second giving the difference between the quantities in the two planes (tangential plane minus sagittal plane).

For beam size plots, the tangential plane values are shown in red whilst sagittal are shown in blue. Whilst for any other quantity, the tangential plane values are solid lines and sagittal are dashed lines.

The locations of each component will be marked on the figure, unless the component is in ignore or the component has “AR” or “HR” in its name.

Parameters

filenamestr or file-like, optional

Name of a file or existing file object to save the figure to.

showbool, optional; default: True

Whether to show the figure.

ignorecomponent, sequence of, optional

A component or sequence of components to ignore when making markers.

name_xoffsetsdict, optional

Dictionary of component names to x-axis offsets for shifting where the component name text is placed. The offset value is interpreted in terms of data co-ordinates.

name_yoffsetsdict, optional

Dictionary of component names to y-axis offsets for shifting where the component name text is placed. The offset value is interpreted in terms of data co-ordinates.

ylimsdict, optional

Dictionary of target names (i.e. “beamsize”, “gouy” or “curvature”) to manual axis y-limits.

nptsint, optional; default: 1000

See equivalent argument in PropagationSolution.all_segments().

resolutionstr, optional; default: “equal”

See equivalent argument in PropagationSolution.all_segments().

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

Returns

figFigure: Handle to the figure.
axsaxes: The axis handles.

property ports[source]: A list of all the ports traversed, in order.

property ps_x[source]: The internal PropagationSolution for the tangential plane.

property ps_y[source]: The internal PropagationSolution for the sagittal plane.

qx(at)[source]

Tangential beam parameter at a given location of the path.

See PropagationSolution.q() for parameters and return object descriptions.

qy(at)[source]

Sagittal beam parameter at a given location of the path.

See PropagationSolution.q() for parameters and return object descriptions.

property spaces[source]: A list of all spaces traversed, in order.

property start_node[source]: The starting node of the propagation.

property symbolic[source]: Whether the astigmatism solution is symbolic.

class finesse.solutions.beamtrace.BeamTraceSolution(name, data, forest=None)[source]

Bases: BaseSolution

Trace solution corresponding to calls to Model.beam_trace().

Note that BeamTraceSolution objects are returned via Model.beam_trace() calls, they should never need to be created manually.

This class provides a dict-like interface to beam trace solution data. If trace is an instance of this class then one can access the beam parameters at both planes of a node via

# Using the look-up key notation
qx, qy = trace[node]

# Or the get method
qx, qy = trace.get(node)

One can also access individual plane beam parameters with

# Tangential plane
qx = trace[node].qx

# Sagittal plane
qy = trace[node].qy

A copy of the Python dictionary which stores all the underlying node : (qx, qy) mappings can be obtained with the BeamTraceSolution.data property.

To draw a forest representation of the trace solution data, one can simply do

# Prints the forest of beam parameters
print(trace)

# Stores the forest as a string
trace_str = str(trace)

This forest will be ordered by the trace order used for the associated Model.beam_trace() call which constructed this solution.

property data[source]

A copy of the underlying dictionary of beam trace solution data.

Getter:: Returns the beam trace solution data. Read-only.

property data_qx[source]

A copy of the underlying data dictionary but with only the tangential plane beam parameters selected.

Getter:: Returns a dictionary of traced nodes with corresponding tangential plane beam parameters (read-only).

property data_qy[source]

A copy of the underlying data dictionary but with only the sagittal plane beam parameters selected.

Getter:: Returns a dictionary of traced nodes with corresponding sagittal plane beam parameters (read-only).

get(node, default=None)[source]

Gets the beam parameter(s) at the specified node / port.

Note that node can be an instance of OpticalNode, resulting in this method returning qx and qy for that specific node, or it can be an object of type Port - in which case a dictionary of both the input and output node beam parameters are returned.

Parameters

nodeOpticalNode or Port: The node or port to access.
defaultany, optional; default: None: The value to return if node does not exist within the trace data.

items()[source]: A view on the underlying dict items.

keys()[source]: A view on the underlying dict keys.

print()[source]

Draws the trace solution as a forest of beam parameters.

This uses the TraceForest structure associated with the model that constructed this solution, where each tree is ordered by the trace order of the relevant call to the beam tracing method.

q(node)[source]

A convenience method for getting the non-astigmatic beam parameter at a node.

Warning

This is only intended to be used on nodes which do not exhibit astigmatism. If qx != qy at the node then this method will raise a ValueError.

To get both qx and qy at a node use either:

qx, qy = trace[node]

or:

qx, qy = trace.get(node)

where trace is an instance of this class.

Parameters

nodeOpticalNode: The node at which to obtain q.

Returns

qBeamParam: The beam parameter (which is the same in both planes) at the node.

Raises

exValueError: If the beam parameters qx != qy at the node.

values()[source]: A view on the underlying dict values.

class finesse.solutions.beamtrace.NodeData(qx, qy)[source]

Bases: NamedTuple

qx: BeamParam: Alias for field number 0

qy: BeamParam: Alias for field number 1

class finesse.solutions.beamtrace.PropagationSolution(name, node_info, comp_info, symbolic)[source]

Bases: BaseSolution

Solution representation of a call to propagate_beam().

This class contains useful attributes and methods for accessing properties of the beam that was propagated through the path specified by the above function call. If this propagation call was symbolic then each property returned from this class will also be symbolic - evaluate these using the eval method of the symbolic expression.

Note that PropagationSolution objects are returned via propagate_beam() (or Model.propagate_beam()), they should never need to be created manually.

See Beam propagation for details and examples on using this class.

abcd(up_to=None)[source]

Composite ABCD matrix up to a specific point in the path.

Parameters

up_toOpticalNode or Port, str, optional: The location in the path at which to get the composite ABCD matrix. This can be an optical node or a port. When None it will be the to_node of the propgagtion.

Returns

Mnumpy.ndarray: The ABCD matrix, as a NumPy array, computed up to the specified location.

Raises

keKeyError: If up_to is a node or port which does not exist within the solution.
teTypeError: If up_to is not an OpticalNode or Port.

acc_gouy(*args)[source]

Accumulated Gouy phase over a sequence of spaces.

Parameters

argssequence of args: Space components or names of spaces.

Returns

agouyfloat or Function: The accumulated Gouy phase over the given spaces.

acc_gouy_up_to(point)[source]

Accumulated Gouy phase up to a point in the traversed path.

This computes the cumulative Gouy phase from the PropagationSolution.start_node to the specified point.

Parameters

pointOpticalNode or Port or Connector or str: A node, port, component or name of component up to which to compute the accumulated Gouy phase.

Returns

agouyfloat or Function: The accumulated Gouy phase up to the given point.

all_segments(*args, add_gouy=True, w_scale=1, npts=1000, resolution='adaptive', subs=None)[source]

Construct a dictionary containing beam data for all segments of the solution.

The expected, valid positional arguments are any combination of:

“beamsize”,

“gouy”,

“curvature”,

where all three will be used by default if no args are given.

Use PropagationSolution.segment() to obtain the beam data over a single space of the solution.

Parameters

add_gouybool, optional; default: True

Whether to add the last Gouy phase from previous segment to all values of current segment, thereby constructing each “gouy” array entry as accumulated Gouy phases over all segments.

w_scalescalar, optional; default: 1

Quantity to scale beam size values by if calculating these. For example, specify w_scale = 1e3 to get beam sizes in mm. By default the units of the beam size will be in metres.

nptsint, optional; default: 1000

Number of points to use for computing data values. The actual number of data points used per segment depends upon the resolution argument.

resolutionstr, optional; default: “adaptive”

The method of segment resolution setting to use. This can be one of three arguments:

“adaptive”: Sets the number of points per segment in such a way as to attempt to increase the resolution near the waist. Each segment will have a number of points allocated to it accordingly, with the total number of points across all segments then approximately equal to npts.

“equal”: Allocates an equal number of points to each segment, i.e. each segment has int(npts / len(self.spaces)) points.

“all”: Gives npts to all segments, such that the total number of data points across all segments is len(self.spaces) * npts.

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

Returns

datadict: Dictionary of data mapping space : zs, segdata, where space is each space (i.e. segment) in the solution path, zs are the z-axis values and segdata is the dict of data values for the targeted beam properties over the space.

animate(subs, *args, filename=None, show=True, ignore=None, name_xoffsets=None, name_yoffsets=None, ylims=None, npts=200, blit=True, interval=200)[source]

Animate any combination of the beam sizes, accumulated Gouy phases and / or wavefront curvatures over the propagated path using the substitution parameters in subs.

The expected, valid positional arguments (i.e. *args) are any combination of:

“beamsize”,
“gouy”,
“curvature”,

or “all” to animate all of the above.

If no positional args are given then the beamsize (first axis) and accumulated Gouy phase (second axis) will be animated by default.

At least one model parameter substitution in subs must be array-like - this will then be the animation axis. If more than one are array-like then each array must be the same size - the substitutions will then be carried out simulatenously. Any scalar value entry in subs will be applied before the animation axis.

Parameters

subsdict

Dictionary of model parameter substitutions. At least one entry must be array-like such than animation can be performed over this axis.

If multiple substitutions are arrays then they must all be the same size.

filenamestr, optional

Name of a file to save the animation to.

showbool, optional; default: True

Whether to show the resulting animation.

ignorecomponent, sequence of, optional

A component or sequence of components to ignore when making markers.

name_xoffsetsdict, optional

Dictionary of component names to x-axis offsets for shifting where the component name text is placed. The offset value is interpreted in terms of data co-ordinates.

name_yoffsetsdict, optional

Dictionary of component names to y-axis offsets for shifting where the component name text is placed. The offset value is interpreted in terms of data co-ordinates.

ylimsdict, optional

Dictionary of target names (i.e. “beamsize”, “gouy” or “curvature”) to manual axis y-limits.

nptsint, optional; default: 200

Number of points to use for computing beam sizes and Gouy phases over spaces.

blitbool, optional; default: True

Whether blitting is used to optimize drawing.

intervalint, optional; default: 200

Delay between frames in milliseconds.

Returns

figFigure: Handle to the figure.
axsaxes: The axis handles.
anFuncAnimation: Handle to the animation.

animate_acc_gouy(subs, **kwargs)[source]

Animate the accumulated Gouy phases over the propagated path.

This is just a convenience wrapper which is identical to calling PropagationSolution.animate() with "gouy" as the arg.

Returns

figFigure: Handle to the figure.
axAxis: Handle to the axis.
anFuncAnimation: Handle to the animation.

animate_beamsizes(subs, **kwargs)[source]

Animate the beam sizes over the propagated path.

This is just a convenience wrapper which is identical to calling PropagationSolution.animate() with "beamsize" as the arg.

Returns

figFigure: Handle to the figure.
axAxis: Handle to the axis.
anFuncAnimation: Handle to the animation.

animate_curvatures(subs, **kwargs)[source]

Animate the wavefront curvatures over the propagated path.

This is just a convenience wrapper which is identical to calling PropagationSolution.animate() with "curvature" as the arg.

Returns

figFigure: Handle to the figure.
axAxis: Handle to the axis.
anFuncAnimation: Handle to the animation.

beamsize(at)[source]

Beam radius at a given location of the path.

Parameters

See PropagationSolution.q().

Returns

wfloat or Function: Beam size corresponding to the specified node.

Raises

See PropagationSolution.q().

property beamsizes[source]: Dictionary of node to beam size mappings.

property components[source]: A list of all components (excluding spaces) traversed, in order.

compute_distances_matrix(ztype='geometric', subs=None)[source]

Compute the distances between each optic, relative to each other.

Returns a dict of dicts for each “delta z”. Note that each distance value is in metres. Use PropagationSolution.distances_matrix_table() to create a tabulated representation of this dict.

Parameters

ztypestr, optional; default: “geometric”

Type of distance, can be either ‘geometric’ or ‘optical’. In the former case the values are the distances between each optic in terms of sums of space lengths of each space between them. In the latter case, each value is instead the optical path length between each component, i.e. the sum of the product of the space length and refractive index of each space between them.

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

Returns

deltasdict: Dict of dicts for each dz between components.

distances_matrix_table(ztype='geometric', subs=None, numfmt=None, **kwargs)[source]

Returns the distances between each optic, relative to each other, in a table.

Parameters

ztypestr, optional; default: “geometric”:

See PropagationSolution.compute_distances_matrix().

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

numfmtstr or func, optional

Either a function to format numbers or a formatting string. The function must return a string. Defaults to using an SI scale function.

**kwargsdict, optional

Additional arguments to create the table. See finesse.utilities.tables.NumberTable for further documentation. The arguments table, colnames and rownames are already used and should not be passed.

property end_node[source]: The final node of the propagation.

property full_ABCD[source]: The full, composite ABCD matrix from the start to the end of the path.

property nodes[source]: A list of all the nodes traversed, in order.

property optical_path_length[source]

The optical path length of the traversed path.

Equal to the sum of the product of each space length and refractive index in the path.

property path_length[source]

The geometric path length of the traversed path.

Equal to the sum of each space length in the path.

plot(*args, filename=None, show=False, ignore=None, name_xoffsets=None, name_yoffsets=None, ylims=None, npts=1000, resolution='adaptive', single_sided=True, subs=None)[source]

Plot any combination of the beam sizes, accumulated Gouy phases and / or wavefront curvatures over the propagated path.

The expected, valid positional arguments are any combination of:

“beamsize”,
“gouy”,
“curvature”,

or “all” to plot all of the above.

If no positional args are given then the beamsize (first axis) and accumulated Gouy phase (second axis) will be plotted by default.

The locations of each component will be marked on the figure, unless the component is in ignore or the component has “AR” or “HR” in its name.

Parameters

filenamestr or file-like, optional

Name of a file or existing file object to save the figure to.

showbool, optional; default: True

Whether to show the figure.

ignorecomponent, sequence of, optional

A component or sequence of components to ignore when making markers.

name_xoffsetsdict, optional

Dictionary of component names to x-axis offsets for shifting where the component name text is placed. The offset value is interpreted in terms of data co-ordinates.

name_yoffsetsdict, optional

Dictionary of component names to y-axis offsets for shifting where the component name text is placed. The offset value is interpreted in terms of data co-ordinates.

ylimsdict, optional

Dictionary of target names (i.e. “beamsize”, “gouy” or “curvature”) to manual axis y-limits.

nptsint, optional; default: 1000

See equivalent argument in PropagationSolution.all_segments().

resolutionstr, optional; default: “adaptive”

See equivalent argument in PropagationSolution.all_segments().

single_sidedbool

If False the beamsize plot is a single positive line.

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

Returns

figFigure: Handle to the figure.
axsaxes: The axis handles.

plot_acc_gouy(**kwargs)[source]

Plot the accumulated Gouy phases over the propagated path.

This is just a convenience wrapper which is identical to calling PropagationSolution.plot() with "gouy" as the arg.

Returns

figFigure: Handle to the figure.
axAxis: Handle to the axis.

plot_beamsizes(**kwargs)[source]

Plot the beam sizes over the propagated path.

This is just a convenience wrapper which is identical to calling PropagationSolution.plot() with "beamsize" as the arg.

Returns

figFigure: Handle to the figure.
axAxis: Handle to the axis.

plot_curvatures(**kwargs)[source]

Plot the wavefront curvatures over the propagated path.

This is just a convenience wrapper which is identical to calling PropagationSolution.plot() with "curvature" as the arg.

Returns

figFigure: Handle to the figure.
axAxis: Handle to the axis.

property ports[source]: A list of all the ports traversed, in order.

position(point, ptype='geometric')[source]

Gets the position of the specified point relative to the start node.

Parameters

pointOpticalNode or Port or Connector or str: The location in the path from which to obtain the relative position. This can be an optical node, a port, a connector or the name of a connector.
ptypestr: Type of distance, can be either ‘geometric’ or ‘optical’. In the former case the value returned is the distance from the start node to point as a sum of each space length. In the latter case the value returned will be the optical path length from the start node to point, i.e. a sum of each space length multiplied by its refractive index.

Returns

zfloat or symbol: The relative distance from the start node to the measured point.

property positions[source]: A dictionary of the Connector instances to their positions (relative to the start node).

print(subs=None, numfmt=None, **kwargs)[source]

Print the propagated beam properties at each node in a table format.

This internally calls PropagationSolution.table() and prints its return string.

Parameters

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

numfmtstr or func, optional

Either a function to format numbers or a formatting string. The function must return a string. Defaults to “{:.3f}” for the first 6 columns and lambda q: f”{q.real:.3f} + {q.imag:.3f}j” for the last one.

**kwargsdict, optional

Additional arguments to create the table. See finesse.utilities.tables.NumberTable for further documentation. The arguments table, colnames and rownames are already used and should not be passed.

q(at) → BeamParam[source]

Beam parameter at a given node of the path.

Parameters

atOpticalNode or str: The location in the path at which to get the beam parameter. This can be an optical node or the name of the optical node.

Returns

qBeamParam: The beam parameter corresponding to the specified node.

Raises

keKeyError: If at is a node which does not exist within the solution.
veValueError: If at is a string corresponding to a node which doesn’t exist in the associated model.
teTypeError: If at is not an OpticalNode or a string.

property qs[source]: Dictionary of node to beam parameter mappings.

segment(node, *args, normalise_z=True, w_scale=1, npts=400, subs=None)[source]

Obtain data for a segment of the beam over the space attached to the specified node.

The expected, valid positional args are any combination of:

“beamsize”,

“gouy”,

“curvature”,

where all three will be used by default if none of these are given.

Use PropagationSolution.all_segments() to obtain the beam data over all spaces of the solution.

Parameters

nodeOpticalNode

The starting node of the segment.

normalise_zbool, optional; default: True

Whether to normalise returned data["z"] array such that first value of this is zero.

w_scalescalar, optional; default: 1

Quantity to scale beam size values by if calculating these. For example, specify w_scale = 1e3 to get beam sizes in mm. By default the units of the beam size will be in metres.

nptsint, optional; default: 400

Number of points to use for computing data values.

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

Returns

zsnumpy.ndarray: Array of z-axis values corresponding to the position of the node up to the length of the attached space. If normalise_z is True then the position of node will be subtracted from all values, such that the first value in this array will be zero.
datadict: Dictionary of data mapping args : values, where args are those specified (see above) and values are the arrays of values corresponding to each of these args as a function of the z-axis values.

property spaces[source]: A list of all spaces traversed, in order.

property start_node[source]: The starting node of the propagation.

property symbolic[source]: Whether the propagation solution is symbolic.

table(subs=None, numfmt=None, **kwargs)[source]

Construct a table showing the beam properties at each node.

Parameters

subsdict, optional

A dictionary of model parameter to value substitutions to pass to the eval methods of symbolic expressions.

If this solution object is not symbolic then this argument is ignored.

numfmtstr or func, optional

Either a function to format numbers or a formatting string. The function must return a string. Defaults to “{:.3f}” for the first 7 columns and lambda q: f”{q.real:.3f} + {q.imag:.3f}j” for the last one.

**kwargsdict, optional

Additional arguments to create the table. See finesse.utilities.tables.NumberTable for further documentation. The arguments table, colnames and rownames are already used and should not be passed.

Returns

table : finesse.utilities.NumberTable

w(at)[source]: Identical to PropagationSolution.beamsize().

w0(at)[source]: Identical to PropagationSolution.waistsize().

waistpos(from_point)[source]

Waist position as measured at from_point.

Parameters

See PropagationSolution.q().

Returns

wfloat or Function: Distance to the waist from the specified node.

Raises

See PropagationSolution.q().

property waistpositions[source]: Dictionary of node to waist position (as measured from node) mappings.

waistsize(at)[source]

Waist radius as measured from a given location of the path.

Parameters

See PropagationSolution.q().

Returns

wfloat or Function: Waist size using the beam parameter basis at the specified node.

Raises

See PropagationSolution.q().

property ws[source]: Identical to PropagationSolution.beamsizes

z0(from_point)[source]: Identical to PropagationSolution.waistpos().

property z0s[source]: Identical to PropagationSolution.waistpositions