finesse.tracing.tools module

Beam propagation tools for use outside of a simulation context.

The recommended function for most use-cases is propagate_beam() (and propagate_beam_astig() for astigmatic beam propagations) which traces a beam through a specified path of a model. See Beam propagation for details and examples.

finesse.tracing.tools.acc_gouy(from_node=None, to_node=None, via_node=None, path=None, q_in=None, direction='x', symbolic=False, deg=True, **kwargs)[source]

Computes the accumulated Gouy phase along a specified path.

By setting the argument symbolic to true, this method will return a symbolic representation of the accumulated Gouy phase rather than a number.

If the argument q_in is not specified then this value will be determined from a call to Model.beam_trace(). Arguments to this beam trace call can be passed via the kwargs of this method.

Parameters

from_nodeNode: Node to trace from.
to_nodeNode: Node to trace to.
via_nodeNode (or sequence of), optional: Optional node to trace via.
pathOpticalPath, optional: A pre-generated path to use.
q_inBeamParam, complex, optional: Beam parameter to use at starting node. If not specified then this will be determined from a beam trace. Note that, if specified, this can also be a symbolic beam parameter.
directionstr, optional; default: “x”: Plane of computation (can be ‘x’, ‘y’ or None).
symbolicbool, optional; default: False: Flag determining whether to return a symbolic representation.
degreesbool, optional; default: True: Flag determining whether to convert return value from radians to degrees.

finesse.tracing.tools.compute_abcd(from_node=None, to_node=None, via_node=None, path=None, direction='x', symbolic=False, simplify=False, solution_name=None)[source]

Computes the composite ABCD matrix through a given path.

By setting the argument symbolic to true, this method will return a symbolic representation of the ABCD matrix rather than a numeric matrix.

Parameters

from_nodeNode: Node to trace from.
to_nodeNode: Node to trace to.
via_nodeNode (or sequence of), optional: Optional node to trace via.
pathOpticalPath, optional: A pre-generated path to use (produced from a call to Model.path()).
directonstr, optional: Direction of ABCD matrix computation (can be ‘x’, for tangential plane, or ‘y’, for sagittal plane).
symbolicbool, tuple(Parameters), optional; default: False: If False a numerical ABCD propagation is computed. If True, a symbolic ABCD propagation is calculated instead. A tuple of parameters can also be provided, in this case these parameters will be kept symbolic
simplifybool, optional: Attempt to simplify symbolic equations, can be slow for complex models

Returns

outABCDSolution: ABCD matrix solution object between the specified nodes.

finesse.tracing.tools.compute_cavity_mismatches(model, cav1=None, cav2=None)[source]

Computes the mismatch parameter (see BeamParam.mismatch() for the equation) between cavities of the model.

If either / both of cav1, cav2 are not specified then these will be set to all the cavities of the model. This means that the default behaviour of this method (specifying no args) is to compute mismatches between each cavity in the model.

If either of each cavity in a coupling is unstable then the mismatch values between these will be given as np.nan.

Parameters

cav1Cavity, str, optional; default: None: A single cavity object (or its name). Defaults to None such that all cavities are used.
cav2Cavity, str, optional; default: None: A single cavity object (or its name). Defaults to None such that all cavities are used.

Returns

mmxfloat or dict

If both cav1 and cav2 were specified then this will be a single number giving the mismatch between these cavities in the tangential plane.

Otherwise, mmx is a dictionary of (c1, c2): mm_x mappings, where c1 and c2 are the cavity names and mm_x is the mismatch between any two cavities in the tangential plane.

mmyfloat or dict

If both cav1 and cav2 were specified then this will be a single number giving the mismatch between these cavities in the sagittal plane.

Otherwise, mmy is a dictionary of (c1, c2): mm_y mappings, where c1 and c2 are the cavity names and mm_y is the mismatch between any two cavities in the sagittal plane.

finesse.tracing.tools.handle_symbolic(*args, symbolic: tuple | bool, simplify: bool, sym_func: Callable, num_func: Callable)[source]

Handles logic for the ‘symbolic’ argument for propagate_beam() and compute_abcd().

Parameters

symbolictuple | bool: If True or a tuple, returns a symbolic equation. If tuple, only returns symbolic equation with symbols in the tuple. Else returns numeric.
simplifybool: Wether to simplify the symbolics
sym_funcCallable: Function to call for symbolic solution
num_funcCallable: Function to call for numeric solution

Returns

Any: Symbolic or numeric solution

Raises

ValueError: When ‘symbolic’ is not a tuple or a boolean

finesse.tracing.tools.propagate_beam(from_node=None, to_node=None, via_node=None, path=None, q_in=None, direction='x', symbolic=False, simplify=False, solution_name=None, reverse_propagate=False, **kwargs)[source]

Propagates a beam through a specified path, returning dictionaries of the beam parameter at each node and component.

This method returns a PropagationSolution instance.

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

By setting the argument symbolic to true, this method will return symbolic representations of the beam parameters, ABCD matrices and accumulated Gouy phases. Specific symbols can be kept by passing a list of symbol names to symbolic instead of a True or False flag. Any symbol names not provided will use their current evaluated value. The simplify flag when True will try to apply symbolic simplification to the beam propagation. For long propagations through many components using many symbols, this will be slow and might be faster not using any simplification.

The argument q_in can be used to specify an arbitrary input beam parameter to be used at the starting node of the propagation. If not given then this will be determined from a call to Model.beam_trace(). Arguments to this beam trace call can be passed via the kwargs of this method.

Parameters

from_nodeOpticalNode: Node to trace from.
to_nodeOpticalNode: Node to trace to.
via_nodeOpticalNode (or sequence of), optional: Optional node to trace via.
pathOpticalPath, optional: A pre-generated path to use.
q_inBeamParam, complex, optional: Beam parameter to use at starting node. If not specified then this will be determined from a beam trace. Note that, if specified, this can also be a symbolic beam parameter.
directionstr, optional; default: “x”: Plane of computation (can be ‘x’, ‘y’ or None).
symbolicbool, tuple(Parameters), optional; default: False: If False a numerical ABCD propagation is computed. If True, a symbolic ABCD propagation is calculated instead. A tuple of parameters can also be provided, in this case these parameters will be kept symbolic
simplifybool, optional: When True, symbolic simplication will be attempted. When using many symbols and large propagation paths this will significantly increase computational time.
reverse_propagatebool, optional: When True, the beam will be propagated in the reverse of the optical path found. This allows beams to be traced backwards through components like directional beamsplitters.

Returns

psPropagationSolution: A solution object for the propagation.

finesse.tracing.tools.propagate_beam_astig(from_node=None, to_node=None, via_node=None, path=None, qx_in=None, qy_in=None, symbolic=False, solution_name=None, reverse_propagate=False, **kwargs)[source]

Propagates the beam through a specified path over both the tangential and sagittal planes.

Internally this calls propagate_beam() twice - for both the tangential and sagittal planes - and returns a solution object which stores the returns of these as properties.

Parameters

from_nodeNode: Node to trace from.
to_nodeNode: Node to trace to.
via_nodeNode (or sequence of), optional: Optional node to trace via.
pathOpticalPath, optional: A pre-generated path to use.
qx_inBeamParam, complex, optional: Beam parameter, in the tangential plane, to use at starting node. If not specified then this will be determined from a beam trace. Note that, if specified, this can also be a symbolic beam parameter.
qy_inBeamParam, complex, optional: Beam parameter, in the sagittal plane, to use at starting node. If not specified then this will be determined from a beam trace. Note that, if specified, this can also be a symbolic beam parameter.
symbolicbool, optional; default: False: Flag determining whether to return a symbolic representation.

Returns

astig_solAstigmaticPropagationSolution: A solution object consisting of the propagation solutions for both planes and methods for accessing the per-plane beam parameters and overlaps.